Skip to content

docs(citations): replace stale cross-file line-number citations with symbol references - #216

Merged
argszero merged 1 commit into
mainfrom
docs/line-number-citations
Sep 13, 2026
Merged

argszero merged 1 commit into
mainfrom
docs/line-number-citations

Conversation

@argszero

Copy link
Copy Markdown
Owner

Summary

Comments in three files cited cross-file positions as file.ext:line, and those
line numbers no longer hold the construct the sentence names — a reader
following the pointer lands on unrelated code. This is the line-number sibling
of the §-reference drift fixed in C2022/C2023
(PR #179); line numbers are the
more fragile citation form, because they rot whenever any line is inserted or
deleted above them, regardless of whether the citing sentence is still true.

Measured before the change: 11 such citations in 4 tracked files, of which
6 no longer resolve:

citing site cited what it now points at
ui/js/app.js:1021 src/routes/wallet.rs:230-232 if let Some(s) = f
ui/js/app.js:1021 src/routes/wallet.rs:403-405 (blank line)
ui/js/app.js:1021 src/routes/wallet.rs:473 ""
src/routes/mod.rs:2390 ops.rs:101 .query_row(
src/routes/mod.rs:2390 ops.rs:175 "uptime_hours": hours,
src/i18n_pack.rs:937 api.js:66 an unrelated comment line (unrecoverable: api.js was rewritten after C2028)

Related Issue

None (no issue exists for this; none was fabricated).

Changes

  • ui/js/app.js — the direction-set citation now names the construct
    (TX_INCOME_TYPES / TX_EXPENSE_TYPES, the single source the SQL is
    rendered from) instead of the three dead line numbers.
  • src/routes/mod.rs — the ops.rs:101/:175 pair (where total_txs is
    computed and returned) now names ops.rs::runtime.
  • src/i18n_pack.rs — the api.js:66 provenance note is unresolvable, so
    the line number is dropped and the provenance sentence kept.
  • ui/index.htmlapp.js cache-bust bumped (20260914-120260914-2).
  • No config / schema / data-structure change (comment-only), so
    config/config.example.toml needs no sync.

Only stale citations are touched: the five that still resolve
(src/routes/ops.rs:94/103, docs/prototype/aitokenpool-console.html:574/1197,
ui/index.html:338) are deliberately left alone — they are the negative control
that proves the change was targeted rather than a blind sweep (same discipline as
C2023, which kept the live db.rs:3 reference). Nothing is renumbered: a new
number would just be another snapshot waiting to rot.

Tests

  • cargo test217 passed (unchanged; comment-only, no test touched).
  • cargo fmt --check — clean.
  • cargo clippy --all-targets -- -D warnings — clean.
  • Acceptance instrument (a checker over the tracked text, with a
    false-positive control: the smtp.gmail.com:465 host:port must not be
    treated as a citation):
    before population 11 / stale 6 → after population 5 / stale 0,
    and the 5 live citations resolve unchanged.
    The enumeration is shorthand-aware — a naive filename:line regex finds
    only 7 of 11, because the list compresses repeats
    (wallet.rs:230-232 / 403-405 / 473) and drops the filename (:175).

Checklist

  • Branch name follows the convention (docs/line-number-citations).
  • Commit message uses Conventional Commits (docs(citations): …).
  • Single responsibility, minimal change (4 files, +4/−4).

…symbol references

Comments in three files pointed at `file:line` positions that no longer hold
the construct they name, so a reader following the pointer lands on unrelated
code. This is the line-number sibling of the `§`-reference drift fixed in
C2022/C2023, and line numbers are the more fragile citation form.

- ui/js/app.js: the wallet.rs:230-232 / 403-405 / 473 list (the direction
  CASE expression / signed_pts_expr) now names `TX_INCOME_TYPES` /
  `TX_EXPENSE_TYPES`, the single source the SQL is rendered from.
- src/routes/mod.rs: the ops.rs:101/:175 pair (where `total_txs` is computed
  and returned) now names `ops.rs::runtime`.
- src/i18n_pack.rs: the api.js:66 provenance note is no longer resolvable
  (api.js was rewritten after C2028), so the line number is dropped.

Only stale citations are touched: the five that still resolve (ops.rs:94/103
and the three ui/README.md ones) are deliberately left as the negative
control. Comment-only change, no behaviour, no test change (217 passed).
@argszero
argszero merged commit aeb56c8 into main Sep 13, 2026
1 check passed
@argszero
argszero deleted the docs/line-number-citations branch September 13, 2026 17:30
argszero added a commit that referenced this pull request Sep 13, 2026
Two rendered strings in `ui/js/i18n.js` point at material that the
2026-08-22 docs flattening deleted:

- `wallet.raise.sub` / `admin.raise.sub` carry the requirement id
  `US-20`. Commit 6d87213 (#119) rewrote docs/user-stories.md into a
  current-state doc and dropped every `US-<n>` id, so `US-20` resolves
  nowhere: `grep -rn 'US-[0-9]' docs/ README.md README.en.md` is empty at
  HEAD. Every other `US-` id in the repo lives in a code comment or in
  ui/README.md; these were the only ones shown to users.
- `mk.detail.routeVal` cites 「架构 v0.2 路由策略」. The same commit
  deleted the `4.2.1 路由与故障转移策略(v0.2)` section from
  docs/architecture.md, and that file has no version stamp left.

One root cause, two pointer shapes: #179 fixed the `§N` references the
flattening broke and #216 the `file:line` ones, but the `name + stamp`
shape (`US-20`, `v0.2`) was never audited.

The pack values are now plain prose (both sentences were already
self-contained), each edited static fallback in ui/index.html is kept
byte-equal to its pack value, and the three ui/README.md lines that cited
the deleted section are re-pointed at the section that carries the
content today (docs/architecture.md §3, the `router.rs` row), in the
style of #179.

`ui/` text only: no Rust change, no i18n key added or removed (786/786
before and after), no new T() call sites or data-i18n attributes. i18n.js
content changed, so its cache-bust is bumped (20260912-5 -> 20260914-4).

Co-authored-by: argszero <argszero@argszerodeMac-mini.local>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant