docs(citations): replace stale cross-file line-number citations with symbol references - #216
Merged
Merged
Conversation
…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).
7 tasks
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Comments in three files cited cross-file positions as
file.ext:line, and thoseline 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 themore 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:
ui/js/app.js:1021src/routes/wallet.rs:230-232if let Some(s) = fui/js/app.js:1021src/routes/wallet.rs:403-405ui/js/app.js:1021src/routes/wallet.rs:473""src/routes/mod.rs:2390ops.rs:101.query_row(src/routes/mod.rs:2390ops.rs:175"uptime_hours": hours,src/i18n_pack.rs:937api.js:66api.jswas 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 isrendered from) instead of the three dead line numbers.
src/routes/mod.rs— theops.rs:101/:175pair (wheretotal_txsiscomputed and returned) now names
ops.rs::runtime.src/i18n_pack.rs— theapi.js:66provenance note is unresolvable, sothe line number is dropped and the provenance sentence kept.
ui/index.html—app.jscache-bust bumped (20260914-1→20260914-2).config/config.example.tomlneeds 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 controlthat proves the change was targeted rather than a blind sweep (same discipline as
C2023, which kept the live
db.rs:3reference). Nothing is renumbered: a newnumber would just be another snapshot waiting to rot.
Tests
cargo test— 217 passed (unchanged; comment-only, no test touched).cargo fmt --check— clean.cargo clippy --all-targets -- -D warnings— clean.false-positive control: the
smtp.gmail.com:465host:port must not betreated 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:lineregex findsonly 7 of 11, because the list compresses repeats
(
wallet.rs:230-232 / 403-405 / 473) and drops the filename (:175).Checklist
docs/line-number-citations).docs(citations): …).