[naresh-FD]

Stacked on #3

This PR is based on change/AUDIT-001-reposcribe-tests-and-fixes (PR #3), so it shows only its own two commits. It needs #3 first: the ADR change replaces the it.todo that #3 added in adr.test.ts. When #3 merges, GitHub should retarget this PR to main; if it does not, change the base by hand.

What

Two defects that the AUDIT-001 audit found and left open, now fixed:

1. TypeScript @param descriptions (a83576e). getParamDescription looked for a tag whose text started with the parameter name, but ts-morph returns a tag's comment without its name, so no description was ever found. Every documented parameter came out empty, and docgen validate listed it as undocumented. It now matches the tag by its own name, reads the JSDoc from the node that carries it (the variable statement for const arrow functions), and strips the optional {type}, a leading hyphen and line breaks. Names that share a prefix (id / idx) no longer pick up each other's text.
2. ADR numbering (5b42242). docgen adr new used the file count plus one, so ADR-001 and ADR-003 present produced a second ADR-003, and a deleted ADR's number was reused. It now takes the highest ADR-<n> plus one, ignores files that are not numbered ADRs (README.md, ADR-template.md) and keeps counting past three digits.

docs/technical/parser-typescript.md and docs/technical/cli.md describe the new behaviour.

Tests

Written first and seen failing for the right reason (empty descriptions; duplicate or reused numbers):

• param-docs.test.ts: 8 tests (hyphen, no hyphen, {type}, shared prefix, undocumented parameter, multi-line, arrow function, class method). Five deliberate breakages of the parser were each caught.
• adr.test.ts: the it.todo becomes 6 tests (gap, deletion, four-digit numbers, non-ADR files, empty folder, no overwrite). Five deliberate breakages were each caught.

Checks run locally

Command	Exit	Result
pnpm build	0	7/7 tasks
pnpm test --force	0	14/14 tasks; cli 31 passed, parser-typescript 15 passed
pnpm test:e2e	0	4 modules, 13 HTML artifacts
node scripts/run-docgen.cjs validate --json	0	still reports passed: false, but self-documentation coverage rose from 35% (main) to 37%, and violations fell from 562 to 557 with none added

CI

No CI runs on this PR while its base is the PR #3 branch: the repository's "Build, test, and validate documentation" workflow only triggers for pull requests into main. It will run once #3 merges and this PR is retargeted to main. Until then the local results above are the only evidence.

Behaviour changes to review

• @param text now appears in ParamNode.description, in generated docs and in coverage. Documented parameters that were counted as undocumented now count as documented, so coverage can only go up.
• adr new may pick a higher number than before when there are gaps. For folders with no gaps nothing changes.

CHANGE_ID: AUDIT-001

🤖 Generated with Claude Code