Repository navigation
Conversation
ParamNode.description was always empty for Java: the lookup read a comment before the parameter list node, but the @PARAM tags are in the Javadoc of the method or constructor that owns the list. Read them from there. The text was never lost (it stays in the member's tags); the description field the renderers read was simply never filled. A varargs parameter (`String... parts`) was also reported as `arg` with type `Object`, because tree-sitter-java's spread_parameter has no `name` or `type` field: the name is inside its variable_declarator and the type is its first other named child. Report it under its own name as an array of the element type (`String[]`), still with isRest set. Both behaviours failed new tests first (DocumentedService.java fixture: constructor, method, varargs, undocumented and a @PARAM for a parameter that does not exist). docs/technical/parser-java.md no longer lists the empty descriptions as a limitation. Gates: parser-java 4/4; tsc --noEmit clean. Change: AUDIT-001 (RS-05) Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…l hint
The config schema, the orchestrator and the CLI help all accept a
Confluence output, but no package renders it. Enabling it made the
plugin loader fail with "Could not resolve plugin
@docgen/renderer-confluence ... npm install @docgen/renderer-confluence",
sending users to install a package that does not exist.
Stop early in the orchestrator, before any plugin is loaded: enabling
output.confluence (or running `generate --format confluence`) now fails
with "Confluence output is not available: RepoScribe has no Confluence
renderer. Set output.confluence.enabled to false, or generate markdown,
html or pdf." The same check covers snapshot and validate, which load
the same plugins. The config schema is unchanged, so existing files
still load.
The `generate --format` help no longer lists confluence. The
configuration reference said enabling it makes `docgen publish` push
pages; there is no publish command, so it now opens with a "Not
implemented" note, and the CLI reference says confluence is rejected.
New tests (orchestrator.outputs.test.ts) failed 3 of 3 before the fix.
Checked with the real CLI: exit 1 with the message, JSON output keeps its
{success:false,error} shape, markdown generation unaffected.
Change: AUDIT-001 (RS-15)
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The adr command had no tests. Add adr.test.ts (8 tests, 1 todo): `new` creates ADR-001 in docs/decisions with the title, the given status and today's date; the next ADR is numbered after the existing ones with a lowercase hyphenated file name; a missing title exits 1; adr.directory from .docgen.yaml is honoured; `list` handles no directory, sorts by file name and ignores non-markdown files; an unknown action exits 1. A mutation of the numbering made 4 of them fail. The CLI help said "Action: new, list, update", but there is no update action: `adr update` exits 1 with "Unknown ADR action". The reference docs already said new and list only, so only the help text changes. New numbers by file count rather than by the highest existing number, so ADR-001 and ADR-003 present would create a second ADR-003. That is a behaviour change, so it is recorded as a todo test, not fixed here. Gates: adr.test.ts 8 passed, 1 todo; tsc --noEmit clean. Change: AUDIT-001 (RS-14) Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The debounced watch loop had no test. Export watchAndRegenerate and let callers pass the watcher and the delay, defaulting to fs.watch and 200 ms, so behaviour is unchanged. generate.watch.test.ts drives it with a fake watcher and fake timers: every source root is watched recursively; a burst of changes causes one regeneration after the debounce (200 ms by default); a change during a run is queued and run afterwards, never concurrently; a failed generation is logged and watching continues; a watcher error rejects. Two mutations (a different default delay, no "already running" guard) each made exactly one test fail. Checked against the real command too: `generate --watch` over the e2e fixture noticed an edit to a source file and regenerated in 373 ms. docs/technical/cli.md now lists what watch mode does, all of it covered by the tests. Gates: generate.watch 6/6; tsc --noEmit clean. Change: AUDIT-001 (RS-06) Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The incremental cache that watch mode relies on had no test. Add cache.test.ts (5 tests), observing the private parseSourceFile with a spy: unchanged files are parsed once and then served from the cache; an edited file is the only one parsed again and its new content is reported; a changed modification time counts as a change even at the same size; files dropped from the list are evicted and parsed again if they return; callers get copies, so changing a result cannot corrupt the cache. Always trusting the cache made 2 of them fail, and disabling eviction made 1 fail. docs/technical/parser-typescript.md had nothing on the cache. It now states these rules, including that the check does not read file contents, so an edit that keeps both size and modification time is not noticed. Gates: cache.test.ts 5/5; tsc --noEmit clean. Change: AUDIT-001 (RS-07) Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The diff command is the CI gate for API compatibility but only its report builder was tested. Cover the exit-code decision (breaking + flag -> 1, breaking without flag -> unchanged, non-breaking + flag -> unchanged), the failure path, that the base ref is archived rather than checked out, and that the temporary directory is always removed. Git, tar, the filesystem and the snapshots are mocked. Six deliberate breakages of diff.ts were each caught by these tests. CHANGE_ID: AUDIT-001 Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…ls (AUDIT-001: RS-06) watchAndRegenerate and WatchDependencies became exported for testing; RepoScribe's own validator listed them as undocumented. Add TSDoc, including parameters. CHANGE_ID: AUDIT-001 Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…01: RS-15) core.md still mapped confluence to a renderer package that does not exist and described its options as live; configuration.md still said `docgen publish` pushes pages. Both now say it is not implemented, matching the code. CHANGE_ID: AUDIT-001 Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
ADVISORY: RepoScribe documentation validationCoverage: 36% (threshold: 80%) |
getParamDescription looked for a tag whose text started with the parameter name, but ts-morph returns the comment without the name, so no description was ever found and `docgen validate` listed every documented parameter as undocumented. Match the tag by its own name instead, read the JSDoc from the node that carries it (the variable statement for const arrow functions), and strip the hyphen and line breaks. Eight tests, five deliberate breakages each caught. Self-validation: 567 -> 557 violations, none added. CHANGE_ID: AUDIT-001 Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
`docgen adr new` took the file count plus one, so a gap or a deleted ADR made it reuse a number (ADR-001 and ADR-003 present produced a second ADR-003). Use the highest `ADR-<n>` found instead, ignore files that are not numbered ADRs, and keep counting past three digits. The it.todo from the audit becomes six real tests; five deliberate breakages are each caught. CHANGE_ID: AUDIT-001 Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…m-and-adr-fixes Carry TypeScript `@param` text into the docs and number ADRs after the highest existing one
ADVISORY: RepoScribe documentation validationCoverage: 37% (threshold: 80%) |
Use a schema-validated config and the silent logger through one helper
rather than `{} as any` and `console as any` in each test. The test file is
excluded from the package tsconfig, so it was also typechecked explicitly.
CHANGE_ID: AUDIT-001
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
ADVISORY: RepoScribe documentation validationCoverage: 37% (threshold: 80%) |
This branch has not been deployed
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.
What
Six AUDIT-001 rows for RepoScribe, one commit per concern (tests written first, then the fix where there was a defect):
d6c3323): Javadoc@paramtext now reachesParamNode.description(it was always empty), and varargs parameters get their real name andT[]type (they were reported asarg/Object).e4104a4,7cf993f): there is no Confluence renderer, but the config accepted it and the failure was a misleading install hint for a package that does not exist. Enabling it now stops with "Confluence output is not available: RepoScribe has no Confluence renderer." The CLI help and the docs (configuration.md,cli.md,core.md) say it is not implemented.f8c1a10): 8 tests; the help no longer advertises anupdateaction that does not exist.b4e80de,04eeceb):watchAndRegeneratetakes optional injectablewatchanddebounceMs, with 6 tests using a fake watcher and fake timers. A realgenerate --watchrun also regenerated after an edit. TSDoc added for the now-exported API.c45fc51): 5 tests for the mtime+size cache (hit, change, mtime-only change, eviction, copy-on-read).diff --fail-on-breaking(4b62d3a): 8 tests for the exit code and failure paths. Six deliberate breakages ofdiff.tswere each caught.Checks run locally (at
04eeceb;7cf993fchanges docs only)pnpm buildpnpm test --forcepnpm test:e2enode scripts/run-docgen.cjs validate --jsonpassed: false: 36% against an 80% threshold.mainwas already at 35% (491 undocumented), so this is not newThat validate run lists 5 more "parameter undocumented" violations than
main, all forwatchAndRegenerate, even though it has@paramtags. The same happens for existing code such asParserPlugin.parse, so the TypeScript parser seems to drop@paramdescriptions. That is a separate defect that I have not verified or fixed.CI has not run on this branch.
Behaviour changes to review
confluencenow fails with a different, accurate message.--formatand theadraction.Known gaps left as
it.todoADR numbers come from the file count and can duplicate after deletions.
CHANGE_ID: AUDIT-001
🤖 Generated with Claude Code