Skip to content

docs: repoint 5 dangling section references to their current sections - #179

Merged
argszero merged 1 commit into
mainfrom
docs/fix-dangling-section-refs
Sep 12, 2026
Merged

argszero merged 1 commit into
mainfrom
docs/fix-dangling-section-refs

Conversation

@argszero

Copy link
Copy Markdown
Owner

Summary

Repoint the 5 section references in tracked files that point at headings which no longer exist.

The 2026-08-22 docs flattening (6d87213, "concise current-state docs") cut docs/architecture.md from 18 headings to 9 — deleting the entire 4.x subsection layer — and docs/user-stories.md from 14 headings to 5. Five references have cited dead headings ever since, and nothing in the repo notices: a maintainer reading src/router.rs gets no signal that its citation is stale.

Location Was Now Why that target
src/router.rs:1 architecture §4.2.1 §3 模块 routing/failover is described in the router.rs row of the module table
src/router.rs:17 architecture §4.2.1 §3 模块 same row states the 5-second cooldown
src/billing.rs:1 architecture §4.3/4.4 §3 模块 the billing.rs row carries token→price→points
src/gateway.rs:1 architecture §4.1 §6 API 一览 gateway.rs has no row in the module table; its endpoints are listed in §6
ui/README.md:25 user-stories §1.1 §4 UI 约定 that section's first bullet is the 「尽量少用弹窗」 rule

src/db.rs:3 (architecture §5) already resolves and is deliberately left untouched — a blanket "delete every section reference" pass would have destroyed the only live one.

Each target was read at HEAD before repointing, and each now cites a section that actually contains the content. The old numbering is kept in the two places where it still carries meaning (router.rs and ui/README.md), because the surviving document no longer has subsections, so the reader has no other way to connect the two.

Related Issue

No issue exists for this — the defect was found by scanning the repository itself, not reported. Leaving this empty rather than fabricating a reference.

Changes

  • Repoint 5 dangling section references (src/router.rs, src/billing.rs, src/gateway.rs, ui/README.md)
  • Comment/doc-only: zero production behaviour change, zero i18n keys, no cache-bust, no config/data structure touched
  • src/db.rs:3 left as-is (it resolves)

Tests

  • cargo test165 passed / 0 failed
  • cargo fmt --check — clean
  • cargo clippy --all-targets -- -D warnings — clean, 0 warnings
  • Reference resolver, before vs after: 1 of 6 → 6 of 6 resolving

The resolver walks every § occurrence in tracked files and resolves it against the current heading set of the document it names. It carries panicking positive controls (the heading extractor must find docs/architecture.md §1/§5 and docs/user-stories.md §4, or it aborts rather than reporting a vacuous "clean"), and it is proven non-vacuous by running it against the pre-flatten tree (6d87213^), where the same references resolve 8 of 8 — i.e. the "rot" is real and the tool can see both states. No unit test was added: this is a documentation/comment fix with no behaviour to assert, and the repo deliberately carries no doc-linting toolchain (same call as #178).

Checklist

  • Branch naming follows convention (docs/)
  • Commit message uses Conventional Commits (docs: — no single scope spans three src/ modules plus ui/)
  • Single responsibility, minimal change (5 lines across 4 files)

The 2026-08-22 docs flattening (6d87213) cut docs/architecture.md from 18
headings to 9 and docs/user-stories.md from 14 to 5, dropping the entire
4.x subsection layer. Five section references in tracked files have pointed
at headings that no longer exist ever since:

  src/router.rs:1,17  architecture 4.2.1  -> 3 (module table, router.rs row)
  src/billing.rs:1    architecture 4.3/4.4 -> 3 (module table, billing.rs row)
  src/gateway.rs:1    architecture 4.1    -> 6 (API list; gateway.rs has no
                                             row in the module table)
  ui/README.md:25     user-stories 1.1    -> 4 (UI 约定)

Each target was read at HEAD and verified to actually carry the cited
content before repointing. src/db.rs:3 (architecture 5) already resolves
and is deliberately left untouched. Comment/doc-only: no production
behaviour change, no i18n keys, no cache-bust.
@argszero
argszero merged commit a366162 into main Sep 12, 2026
1 check passed
@argszero
argszero deleted the docs/fix-dangling-section-refs branch September 12, 2026 06:27
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