h-dv/code-index

Watch

Fork 0

Documentation truth and structure: compiled-in-parser story, stale counts, no config reference, README as diary #527

New issue

Closed

opened 2026-11-09 08:03:48 +01:00 by buildagent · 1 comment

buildagent commented

2026-11-09 08:03:48 +01:00

Member

Consolidated scope (triage 2026-11-09)

Priority: Medium: users and agents are told the wrong product shape.

This issue is now the canonical tracker for:

generate docs/configuration.md from the Config structs; init writes [logging], which nothing reads; [watcher] mode/poll_interval_ms are silently ignored (from #528, closed and merged here; its full report stays readable there)
a short README plus docs/* with an index; comment policy (invariants, not history) (from #529, closed and merged here; its full report stays readable there)

Original report

Summary

The user-facing docs still describe a product with compiled-in parsers, contradict themselves, and carry about 15 stale concrete claims. Every one of them passes CI, because the doc gates check names and verbs, never meaning, counts or config keys.

A. The builtin-vs-plugin story is told three incompatible ways

README.md:683-686: release has no native parsers and "no native fallback".
README.md:880-882: "Native language fallbacks remain enabled during the staged rollout".
README.md:586-595: the language table labels each plugin "tree-sitter-rust" and so on, as if compiled in. README.md:888-890 says the "built-in TypeScript and JavaScript plugins/extractor" handle .svelte.ts and Vue <script>.
crates/plugins/Cargo.toml: "THE SHIPPED BUILD KEEPS ONLY RUBY'S BUILTIN". But release builds use --no-default-features, so it keeps none, which the running daemon confirms. .forgejo/workflows/ci.yml:1787 repeats the claim.
The UpdateConfig doc at crates/indexer/src/config.rs around line 105 says languages.enabled "selects among builtins".
Building from source (README.md:251-263: cargo build --release, then init, then index) yields Ruby only, and nothing tells the user how to get the other languages.
Automatic install vs explicit grant: README.md:921-925, 949-951 say the daemon detects languages and installs and enables signed first-party packages. ARCHITECTURE.md:552-555 says enabling "requires an explicit capability grant". README.md:898-900 still says to run languages owner <lang> package by hand.

B. CONTRIBUTING's "Adding a language plugin" describes a retired path

CONTRIBUTING.md:163-182: implement LanguagePlugin in crates/plugins/src/<lang>.rs and register it in all_plugins(). Languages now ship as .cip wasm packages, and the real guide, _prdoc/guides/80-package-authoring.md, is never linked.

C. Stale counts and facts

ARCHITECTURE.md:7 says "Three binaries"; there are four, counting code-index-plugin-host.
ARCHITECTURE.md:49 says IndexAccess has "18 methods total"; crates/daemon/src/access.rs:147-637 has 43.
ARCHITECTURE.md:380-381 says "21 *Args types / tool 22"; there are 23 tools.
ARCHITECTURE.md:455-460 says the daemon has "a single Arc<Mutex<Connection>>"; a read pool exists (daemon/src/startup.rs:52, and the document's own line 255).
ARCHITECTURE.md:536-537: the plugin operator surface listed there omits add, update, catalog, key, trust and sign.
ARCHITECTURE.md:557-559 says the citation gate "cannot see markdown"; it can now.
README.md:296 says "14 resources"; at least 17 are served.
README.md:878 says "ten packages"; distribution/registry.v1.json has 11.
README.md:1225: the relationship enum is missing worktree (config.rs:613).
README.md:1279 promises "Phase 2" tools that do not exist (find_base_definition, …).
CONTRIBUTING.md:6 says "Rust 1.88+"; the workspace rust-version is 1.99.1 (Cargo.toml:80).
CONTRIBUTING.md:62 says "Seven corpus repositories"; tests/corpus/corpus.toml has 9.
CONTRIBUTING.md:199-211 says 6 crates and "five language plugins"; there are 17+ crates.
CONTRIBUTING.md:166 says rust.rs is "~450 lines"; it is 3,864.
CONTRIBUTING.md:221 says the daemon "owns a single port"; it binds 127.0.0.1:0.
CONTRIBUTING.md:18 lists "four gates"; CLAUDE.md requires six.

D. Why the gates miss this

crates/abi/tests/doc_citation_gate.rs checks that backticked lower-snake names of five or more words resolve to real items. Its own table shows the root markdown yields 670 backticked spans and 1 citation, so README and ARCHITECTURE are effectively ungated. It does not scan docs/** or the MCP-served crates/mcp-server/src/docs/*.md. readme_cli_reference.rs only checks that each --help verb appears somewhere in the README.

Proposal

Write one authoritative "what ships" paragraph: release has zero builtins, all languages come from signed packages, and here is what init/the daemon installs automatically, on which trigger, signed by whom, and how to turn it off. Fix A and B against that paragraph, and add a "from source" section.
Generic mechanism instead of a fix per claim: take derivable counts out of prose ("the tools", not "23 tools"), or add one derived-facts registry test that checks every remaining number against the code. That covers tool count, resource count, catalog size, IndexAccess arity, the relationship enum, the binary list, rust-version and the corpus size. Extend the citation gate's scan to docs/** and crates/mcp-server/src/docs.

Note: per project rules, do not write the current release version into new docs.

Found by an automated docs-vs-code review (2026-11-09). README:880, CONTRIBUTING:6, ARCHITECTURE:7 and release.yml were verified by hand.

Filed from a five-agent review of master @ e3ec6ead (bloat, robustness, agent usefulness, docs, architecture). Every finding was spot-checked in the main session before filing.

## Consolidated scope (triage 2026-11-09) **Priority: Medium**: users and agents are told the wrong product shape. This issue is now the canonical tracker for: - [ ] generate `docs/configuration.md` from the `Config` structs; `init` writes `[logging]`, which nothing reads; `[watcher] mode/poll_interval_ms` are silently ignored (from #528, closed and merged here; its full report stays readable there) - [ ] a short README plus `docs/*` with an index; comment policy (invariants, not history) (from #529, closed and merged here; its full report stays readable there) --- ## Original report ## Summary The user-facing docs still describe a product with compiled-in parsers, contradict themselves, and carry about 15 stale concrete claims. Every one of them passes CI, because the doc gates check names and verbs, never meaning, counts or config keys. ### A. The builtin-vs-plugin story is told three incompatible ways - `README.md:683-686`: release has no native parsers and "no native fallback". - `README.md:880-882`: "Native language fallbacks remain enabled during the staged rollout". - `README.md:586-595`: the language table labels each plugin "tree-sitter-rust" and so on, as if compiled in. `README.md:888-890` says the "built-in TypeScript and JavaScript plugins/extractor" handle `.svelte.ts` and Vue `<script>`. - `crates/plugins/Cargo.toml`: "THE SHIPPED BUILD KEEPS ONLY RUBY'S BUILTIN". But release builds use `--no-default-features`, so it keeps **none**, which the running daemon confirms. `.forgejo/workflows/ci.yml:1787` repeats the claim. - The `UpdateConfig` doc at `crates/indexer/src/config.rs` around line 105 says `languages.enabled` "selects among builtins". - **Building from source** (`README.md:251-263`: `cargo build --release`, then `init`, then `index`) yields Ruby only, and nothing tells the user how to get the other languages. - **Automatic install vs explicit grant:** `README.md:921-925, 949-951` say the daemon detects languages and installs and enables signed first-party packages. `ARCHITECTURE.md:552-555` says enabling "requires an explicit capability grant". `README.md:898-900` still says to run `languages owner <lang> package` by hand. ### B. CONTRIBUTING's "Adding a language plugin" describes a retired path `CONTRIBUTING.md:163-182`: implement `LanguagePlugin` in `crates/plugins/src/<lang>.rs` and register it in `all_plugins()`. Languages now ship as `.cip` wasm packages, and the real guide, `_prdoc/guides/80-package-authoring.md`, is never linked. ### C. Stale counts and facts - `ARCHITECTURE.md:7` says "Three binaries"; there are four, counting `code-index-plugin-host`. - `ARCHITECTURE.md:49` says `IndexAccess` has "18 methods total"; `crates/daemon/src/access.rs:147-637` has 43. - `ARCHITECTURE.md:380-381` says "21 `*Args` types / tool 22"; there are 23 tools. - `ARCHITECTURE.md:455-460` says the daemon has "a single `Arc<Mutex<Connection>>`"; a read pool exists (`daemon/src/startup.rs:52`, and the document's own line 255). - `ARCHITECTURE.md:536-537`: the plugin operator surface listed there omits `add`, `update`, `catalog`, `key`, `trust` and `sign`. - `ARCHITECTURE.md:557-559` says the citation gate "cannot see markdown"; it can now. - `README.md:296` says "14 resources"; at least 17 are served. - `README.md:878` says "ten packages"; `distribution/registry.v1.json` has 11. - `README.md:1225`: the relationship enum is missing `worktree` (`config.rs:613`). - `README.md:1279` promises "Phase 2" tools that do not exist (`find_base_definition`, …). - `CONTRIBUTING.md:6` says "Rust 1.88+"; the workspace `rust-version` is 1.99.1 (`Cargo.toml:80`). - `CONTRIBUTING.md:62` says "Seven corpus repositories"; `tests/corpus/corpus.toml` has 9. - `CONTRIBUTING.md:199-211` says 6 crates and "five language plugins"; there are 17+ crates. - `CONTRIBUTING.md:166` says `rust.rs` is "~450 lines"; it is 3,864. - `CONTRIBUTING.md:221` says the daemon "owns a single port"; it binds `127.0.0.1:0`. - `CONTRIBUTING.md:18` lists "four gates"; CLAUDE.md requires six. ### D. Why the gates miss this `crates/abi/tests/doc_citation_gate.rs` checks that backticked lower-snake names of five or more words resolve to real items. Its own table shows the root markdown yields 670 backticked spans and **1** citation, so README and ARCHITECTURE are effectively ungated. It does not scan `docs/**` or the MCP-served `crates/mcp-server/src/docs/*.md`. `readme_cli_reference.rs` only checks that each `--help` verb appears somewhere in the README. ## Proposal 1. Write one authoritative "what ships" paragraph: release has zero builtins, all languages come from signed packages, and here is what `init`/the daemon installs automatically, on which trigger, signed by whom, and how to turn it off. Fix A and B against that paragraph, and add a "from source" section. 2. **Generic mechanism instead of a fix per claim:** take derivable counts out of prose ("the tools", not "23 tools"), or add one **derived-facts registry test** that checks every remaining number against the code. That covers tool count, resource count, catalog size, `IndexAccess` arity, the relationship enum, the binary list, `rust-version` and the corpus size. Extend the citation gate's scan to `docs/**` and `crates/mcp-server/src/docs`. Note: per project rules, do not write the current release version into new docs. Found by an automated docs-vs-code review (2026-11-09). README:880, CONTRIBUTING:6, ARCHITECTURE:7 and release.yml were verified by hand. --- _Filed from a five-agent review of master @ e3ec6ead (bloat, robustness, agent usefulness, docs, architecture). Every finding was spot-checked in the main session before filing._

buildagent added the

labels

2026-11-09 08:03:48 +01:00

buildagent changed title from ~~Docs describe compiled-in parsers and carry ~15 stale counts that no gate checks — add a derived-facts registry~~ to Documentation truth and structure: compiled-in-parser story, stale counts, no config reference, README as diary

2026-11-09 09:21:03 +01:00

buildagent added

and removed

labels

2026-11-09 09:21:03 +01:00

buildagent referenced this issue

2026-11-09 09:21:41 +01:00

No .code-index.toml reference; init writes [logging] which nothing reads; [watcher] mode/poll_interval_ms are silently ignored #528

buildagent referenced this issue

2026-11-09 09:21:41 +01:00

Docs and source comments are written as history, not reference: 1.3k-line README, orphaned docs/, 35-53% comment share #529

buildagent referenced this issue

2026-11-12 18:41:44 +01:00

v0.41.51: bounded text arguments, truthful path and startup answers, review grading by effective visibility #580

buildagent referenced this issue from a commit

2026-11-12 20:47:09 +01:00

Merge codex-r26: documentation matches the tree, configuration reference with a key gate (#527)

buildagent referenced this issue

2026-11-12 22:22:54 +01:00

Arguments, settings and documented facts disagree or lack one checked source #570

buildagent commented

2026-11-12 22:23:10 +01:00

Author

Member

Merged into #570.
docs/configuration.md is checked by configuration_reference_matches_decoder_both_ways; product/build/authoring guidance was corrected on master.
Remaining: Documentation structure and facts; no-effect key policy is under Compatibility and release settings.

Merged into #570. docs/configuration.md is checked by configuration_reference_matches_decoder_both_ways; product/build/authoring guidance was corrected on master. Remaining: Documentation structure and facts; no-effect key policy is under Compatibility and release settings.

buildagent closed this issue

2026-11-12 22:23:10 +01:00

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

h-dv/code-index#527

No description provided.

Rows
Columns