Skip to content

tech-debt K: Docs, stale counts, and shipped bundle weight #168

Description

@mmcky

Version, test and suite counts are stale in seven files because the release checklist names only three of them. Measured truth at v0.23.0: 51 suites, 1,198 passing tests (suite runs in ~2.5s).

Also here: five CLI flags documented nowhere including the concurrency control on both bulk commands; src/cli/README.md documents a renamed binary and 1 of 8 commands; both module maps omit the two newest modules; glossary term counts wrong for French and mutually contradictory across four files.

Bundle: sourcesContent: false (the committed sourcemap is 2.85 MB against a 1.5 MB bundle and Node never reads it — action.yml uses node24, which offers no way to pass --enable-source-maps), and delete the dist-action/glossary copy loop that nothing reads at runtime — see #95.

Findings covered

11 audit findings land here. F<n> are stable references into the audit; rank is the report ordering (1 = act first of 139).

  • F69 ½ · rank 117 · low · t/t — build-action.mjs copies glossary/*.json into a runtime-dead dist-action/glossary/
  • F68 · rank 118 · low · t/t — The committed sourcemap inlines all 227 sources — 2.92 MB vs ~0.8 MB, for no added debuggability
  • F108 · rank 119 · low · t/t — And it is shipped in every action download and provably never read
  • F131 · rank 132 · med · t/t — src/cli/README.md documents a nonexistent resync binary, a superseded model default and 1 of 8 commands
  • F47 · rank 133 · low · t/t — Version and test-count claims seven releases stale on the public landing page
  • F117 · rank 134 · low · t/t — Hand-maintained test counts stale by ~30% across five files
  • F129 · rank 135 · low · t/t — Version, test and suite counts stale in seven files — only the one the release checklist names was refreshed
  • F132 · rank 136 · med · s/s — Both module maps omit the same modules, and now all three v0.22/v0.23 modules
  • F133 · rank 137 · med · s/s — docs/developer/testing.md inventories 32 of 55 suites
  • F134 · rank 138 · low · t/t — Glossary term counts wrong for French and mutually contradictory across four files
  • F130 · rank 139 · low · s/s — Five CLI flags exist and are documented nowhere, including the concurrency control on both bulk LLM commands

Plan

Estimate 14.5h · Rebuilds dist-action/ yes · Wave 1, PR K

Docs, counts and bundle. F47 + F117 + F129 stale counts; F131 delete src/cli/README.md for a pointer; F132 + F133 module maps and suite inventory; F134 glossary term counts; F130 five undocumented flags; F68 + F108 sourcesContent: false; F69 delete the dist-action/glossary copy loop


From the technical-debt audit of 2026-07-23 (141 candidates adversarially verified, re-validated against v0.23.0, 139 live). Effort is stopgap / full — t≈0.5h, s≈3.5h, m≈11h, L≈28h. Items marked ½ were partially addressed by v0.22.0/v0.23.0.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationRepo docs and contributor meta

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions