docs(roadmap): deep-audit codebase readability with corrected metrics#337
Merged
Conversation
… and expanded scope Second pass over the codebase-readability roadmap item with updated findings grounded in commit 282e235 on main. Key changes from first pass: - Corrected metrics: 25 too_many_lines (not 17), 231 Style::default() chains (not 120), 82 Dockerfile FROM literals, 123 manifest filename strings, 10 mount helper duplications (not 9), 4 config_with_agents copies - Phase 2 expanded from flat table to 3-tier structure: Tier A (13 files >2000L), Tier B (8 files 1000-2000L), Tier C (10 files 800-1000L) — 31 tracked files total - Phase 1.5 reorganized into 6 numbered sub-sections with per-extraction file lists - Added per-module health table with LOC, file count, //! coverage, and key risk per module - Added mega-functions table with function names and line counts - Added magic numbers extraction section (Phase 1.5.6) - Added agent match-arm dispatch duplication (7+ files) - Added production unwrap() call count (4 total, 2 should use expect()) - Added wildcard import audit (0 in production, 91 test-only) - Corrected //! coverage: 65/116 (56%), not 53/116 (46%) - Removed redundant structural claim about import style Co-authored-by: opencode-agent[bot] <opencode-agent[bot]@users.noreply.github.com> Signed-off-by: opencode-agent[bot] <opencode-agent[bot]@users.noreply.github.com> Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com>
bb7b93b to
d579120
Compare
donbeave
added a commit
that referenced
this pull request
May 18, 2026
…#337) Second deep-audit pass over the codebase-readability roadmap item with corrected metrics and expanded scope. Phase 2 expanded from flat 13-file table to 31-file three-tier structure (Tier A: 13 files >2000L, Tier B: 8 files 1000-2000L, Tier C: 10 files 800-1000L). Phase 1.5 reorganized into 6 numbered sub-sections. Added per-module health table, mega-functions table, magic numbers extraction, agent dispatch duplication, and production unwrap() audit. Corrected metrics: 25 too_many_lines, 231 Style::default() chains, 82 Dockerfile FROM literals, 123 manifest filename strings. Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> Co-authored-by: opencode-agent[bot] <opencode-agent[bot]@users.noreply.github.com>
donbeave
added a commit
that referenced
this pull request
May 20, 2026
…se-readability.mdx (#418) PR #337 rewrote Phase 2 of codebase-readability.mdx from a single linked-name table into Tier A/B/C LOC tables and dropped the leaf links to the four existing split-* roadmap pages (split-runtime-launch, split-input-editor, split-operator-env, split-app-mod). Those pages stayed in the sidebar but became unreachable from the parent program doc and the roadmap overview. Three subsequent re-bakes (#355, #366, #387) did not restore the links. Adds a short "Design pages" subsection at the top of Phase 2 linking the four split-* pages with their LOC and one-line scope, and notes that the remaining Tier A/B/C entries do not yet have dedicated pages. Sidebar and overview audits pass after the change; Tier A/B/C tables are unchanged. Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> Co-authored-by: Amp <amp@ampcode.com>
donbeave
added a commit
that referenced
this pull request
Jun 7, 2026
…se-readability.mdx (#418) PR #337 rewrote Phase 2 of codebase-readability.mdx from a single linked-name table into Tier A/B/C LOC tables and dropped the leaf links to the four existing split-* roadmap pages (split-runtime-launch, split-input-editor, split-operator-env, split-app-mod). Those pages stayed in the sidebar but became unreachable from the parent program doc and the roadmap overview. Three subsequent re-bakes (#355, #366, #387) did not restore the links. Adds a short "Design pages" subsection at the top of Phase 2 linking the four split-* pages with their LOC and one-line scope, and notes that the remaining Tier A/B/C entries do not yet have dedicated pages. Sidebar and overview audits pass after the change; Tier A/B/C tables are unchanged. Signed-off-by: Alexey Zhokhov <alexey@zhokhov.com> Co-authored-by: Amp <amp@ampcode.com>
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
1 participant
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
Second deep-audit pass over the codebase-readability roadmap item, correcting metrics that were wrong in the first pass (PR #334) and expanding Phase 2 from a flat 13-file table to a 31-file three-tier structure. The updated findings are grounded in commit
282e235onmain. Key corrections: 25too_many_linessuppressions (was 17), 231Style::default()chains across 21 files (was 120), 82 Dockerfile FROM literals (new), 123 manifest filename strings (new), and a new per-module health table covering all 11 top-level modules.Verify locally
Documentation
cd docs bun install --frozen-lockfile bun run devAstro serves at
http://localhost:4321/. Pages to walk:http://localhost:4321/reference/roadmap/codebase-readability/
UPDATED page. Check the per-module health table (new), Phase 2 three-tier split table (replaces flat table), and Phase 1.5 numbered sub-sections (6 instead of 4).
Migration notes
None.