Skip to content

feat: doc_coverage and cognitive_complexity methods (Gaze analyzer protocol v1.2.0) - #18

Merged
jflowers merged 62 commits into
zero-dot-force:mainfrom
jflowers:005-doc-cognitive-methods
Nov 1, 2026
Merged

jflowers merged 62 commits into
zero-dot-force:mainfrom
jflowers:005-doc-cognitive-methods

Conversation

@jflowers

@jflowers jflowers commented Nov 1, 2026

Copy link
Copy Markdown
Contributor

Summary

Closes #6

Implements the two methods Gaze analyzer protocol v1.2.0 added, completing reading-stone's optional-method surface:

  • doc_coverage (US1/US3): one row per public symbol — name, package, kind, file, line, documented, doc_snippet — over the exported module surface plus public members of exported classes, with the closed kind set (function, type, constant, variable, class, method). documented is true iff a JSDoc comment is attached to the implementation declaration (overload-aware); doc_snippet is the first non-tag summary line, omitted when empty. Rows are (file, line, name)-ordered and byte-identical across identical requests.
  • cognitive_complexity (US2/US4): one row per analyzed function — package, function, file, line, cognitive_complexity — from a nesting-aware SonarSource walk over the TypeScript AST: if/for/while/do/catch/switch and ternary increments (1 + nesting), flat else, labeled break/continue, direct recursion, &&/||/?? maximal-run sequences, folding at extracted function-likes with nesting reset at anonymous boundaries. Scores are pinned by the normative FR-010 fixture table.
  • Server wiring: both methods registered in the dispatch table with the shared analysis-params validation and -32602 error table; capabilities flipped to doc_coverage: true and cognitive_complexity: true; the reserved -32601 set shrunk to exactly {analyze, stream}.
  • Docs: README method status table, AGENTS.md structure/ownership, NOTICE attribution (byte-for-byte pinned in tests/cli.test.ts), and both openspec spec deltas (protocol, server).

All 29 tasks across 7 phases complete; every CI gate green at the protected thresholds. Spec review: APPROVE WITH ADVISORIES (iteration 1). Code review: APPROVE WITH ADVISORIES — 4/4 reviewers approved (adversary, architect, curator, guard); all advisories are follow-up-scoped, none blocking (see Known Issues).

How to Test

Run the CI gates (all must pass):

npm ci
npx biome check src/ tests/
npm run build
npx vitest run --coverage

Wire-level probe of both new methods against the built server (the US1/US2 independent tests do this as subprocesses — tests/cli.test.ts):

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"root_path":"'"$PWD"'"}}' \
  '{"jsonrpc":"2.0","id":2,"method":"doc_coverage","params":{"root_path":"'"$PWD"'","patterns":["src"]}}' \
  '{"jsonrpc":"2.0","id":3,"method":"cognitive_complexity","params":{"root_path":"'"$PWD"'","patterns":["src"]}}' \
  '{"jsonrpc":"2.0","id":4,"method":"shutdown","params":{}}' \
  | node dist/main.js --stdio

doc_coverage must return symbols rows whose kind values all belong to the closed set (function/type/constant/variable/class/method), with documented flags and doc_snippet present iff non-empty; cognitive_complexity must return functions rows carrying the function identity key. Acceptance fixtures: tests/doc-coverage.test.ts pins exact symbols output for documented/undocumented symbol fixtures; tests/cognitive.test.ts pins the normative FR-010 table of hand-computed SonarSource values (empty body → 0, nested ifs, logical sequences, recursion, labeled breaks, folding).

Real-client interop (dogfooding): gaze docscan ./... --analyzer=<wrapper> consumes doc_coverage over this repo; gaze crap/gaze quality ./... --analyzer=<wrapper> exercise complexity, coverage, and test_mapping. Note the installed gaze dev build carries a known gaze-side json:"name" struct mismatch that blocks its cognitive enrichment — reading-stone's rows are contract-correct per protocol.md v1.2.0; see Known Issues.

How to Demo

  1. Build and run the stdio probe from How to Test against node dist/main.js --stdio.
  2. Point out the initialize response now advertises doc_coverage: true and cognitive_complexity: true, and the reserved -32601 set is exactly {analyze, stream}.
  3. Show doc_coverage rows: every kind from the closed set, documented reflecting attached JSDoc, doc_snippet carrying the first summary line.
  4. Show cognitive_complexity rows keyed by function with hand-computed SonarSource scores (nesting, sequences, recursion, labeled breaks).
  5. Dogfood close: gaze docscan ./... --analyzer=<wrapper> over this repo reports 666 symbols at 85.6% documented.

Key Files Changed

AGENTS.md                                          |    8 +-
NOTICE                                             |    5 +-
README.md                                          |   54 +-
openspec/specs/protocol/spec.md                    |    8 +-
openspec/specs/server/spec.md                      |    4 +-
specs/005-doc-cognitive-methods/checklists/requirements.md | 49 +
specs/005-doc-cognitive-methods/plan.md            |  169 ++
specs/005-doc-cognitive-methods/spec.md            |  160 ++
specs/005-doc-cognitive-methods/tasks.md           |  272 +++
src/cognitive.ts                                   |  547 ++++++
src/doc-coverage.ts                                |  693 ++++++++
src/extract.ts                                     |   14 +-
src/index.ts                                       |   24 +
src/protocol.ts                                    |   52 +-
src/server.ts                                      |   83 +
src/signals/evidence.ts                            |    6 +-
tests/cli.test.ts                                  |  341 +++-
tests/cognitive.test.ts                            | 2066 ++++++++++++++++++++
tests/doc-coverage.test.ts                         | 1531 ++++++++++++++++
tests/extract.test.ts                              |  258 ++-
tests/protocol.test.ts                             |   10 +-
tests/server.test.ts                               |  730 ++++++-
22 files changed, 7029 insertions(+), 55 deletions(-)

Known Issues

Review council verdict: APPROVE WITH ADVISORIES (4/4 reviewers — adversary, architect, curator, guard). All findings are follow-up-scoped; none block this merge:

  • MEDIUM — module boundary: src/doc-coverage.ts imports nextJSDocHost from ./signals/evidence.js, crossing the pipeline-stage boundary that src/internal.ts exists to enforce. Follow-up: hoist nextJSDocHost into src/internal.ts, re-point both consumers, refresh the AGENTS.md structure comment.
  • MEDIUM — DRY (CS-004): the per-method entry scaffold (prepareAnalysis call, -32602 mapping, try/finally dispose) now exists at six sites. Follow-up: extract a withPreparedAnalysis higher-order helper; at minimum migrate the two new sites.
  • MEDIUM — content pipeline: this change hits the analyzer-fleet feature-completeness milestone, triggering the accepted blog-tracking commitment. Post-merge: file a blog-labeled tracking issue in this repo, or explicitly extend the deferral to v0.2.0 via Release v0.2.0: bin alias, README completion, end-to-end conformance #7.
  • LOW — doc_snippet length: doc_snippet carries the first JSDoc summary line with no length cap (spec-conformant; transitively bounded by the 16 MiB per-file read budget). Wire-contract hardening candidate for a future protocol revision.
  • LOW — research citations: spec 005 deliberately omits the research companion (rationale at tasks.md:9 and tasks.md:268), so R1–R15 citations resolve only to plan.md prose. Post-merge: land the research companion or reword citations to resolvable anchors.
  • LOW — upstream gaze bug (cross-repo): the installed gaze dev build tags its cognitive struct field json:"name" while protocol.md v1.2.0 pins functions[].function, so gaze's enrichment and --max-cognitive-complexity gate cannot match reading-stone's contract-correct rows. Reading-stone needs no change; follow-up: file the upstream report on unbound-force/gaze.
  • LOW — plan.md companion tree: plan.md's structure tree lists five companion artifacts that were never materialized (documented in tasks.md). Documentation follow-up.

This PR was generated by /uf.finale (AI-assisted).

@jflowers jflowers left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review Council: APPROVE WITH ADVISORIES

4/4 reviewers approved (adversary, architect, curator, guard); 8 findings — 3 MEDIUM, 5 LOW — all follow-up-scoped, none blocking. Full dispatch: correlation 971ee54a-7f10-4275-9af9-f30652455961, head 2c437f1.

CI Status

Check Status
test (22) PASS
test (24) PASS

Both check-suite jobs ran the full gate set (npm ci, biome, tsc build, vitest+coverage at the protected 85% thresholds) against the PR head.

Advisories not anchored inline

  • MEDIUM — content-pipeline (divisor-curator): This change completes the analyzer-fleet protocol surface (the final two optional methods plus capability flips), which triggers the accepted blog-tracking commitment. Live verification shows no blog-labeled tracking issue exists — only #6 and #7 are open, and #7 carries release engineering only. File the tracking issue referencing this PR, or record a deferral extension in issue text; an unrecorded extension recurs the same gap.
  • LOW — spec metadata (divisor-architect, divisor-guard): specs/005-doc-cognitive-methods/plan.md's documentation tree lists five companion artifacts (research.md, data-model.md, quickstart.md, contracts/) that were never created; the disclosure lives only in tasks.md's Prerequisites. An in-place one-line annotation beside the tree resolves it — nothing substantive is missing (R1–R15 live inline in plan.md; FR tables in spec.md).
  • LOW — cross-component (divisor-guard): The cognitive_complexity rows are contract-correct (identity key function per protocol.md v1.2.0, cross-checked against the pinned sibling clone), but the installed gaze dev build tags FunctionCognitiveComplexityData with json:"name", so its enrichment lookup never matches. The upstream report on unbound-force/gaze remains to be filed.

Verdict

APPROVE WITH ADVISORIES — no blocking findings; all advisories are follow-up-scoped and match the PR's documented Known Issues.

This review was generated by /uf.review-pr (AI-assisted).

Comment thread src/doc-coverage.ts
import { collectSources, propertyNameText } from "./extract.js";
import { compareFileLineName } from "./internal.js";
import { derivePackage } from "./models.js";
import { nextJSDocHost } from "./signals/evidence.js";

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This import crosses the pipeline-stage boundary that src/internal.ts exists to enforce: doc-coverage.ts (a top-level method pipeline) now depends on signals/evidence.ts, the classify_signals pipeline's stage module. src/internal.ts's module doc designates it as the shared leaf "so every consumer ... can share these without an import cycle or a layering inversion," and AGENTS.md documents signals/evidence.ts solely as the signal pipeline's RecordEvidence snapshot stage. Hoisting nextJSDocHost (a checker-independent, pure AST host-walk) into src/internal.ts, re-pointing both consumers at the leaf, and refreshing the AGENTS.md structure comment is mechanical and behavior-preserving.

[MEDIUM — module-boundary, divisor-architect]

Comment thread src/cognitive.ts
rows.sort(compareCognitiveRows);
return rows.map(serializeCognitiveRow);
} finally {
if (prepared.context.mode === "program") {

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This entry carries the sixth copy of the per-method scaffold — the prepareAnalysis() call, the -32602 RpcError mapping on the not-ok arm, and the try/finally with conditional context dispose (analysis.ts:441, analysis.ts:531, complexity.ts:109, quality/pipeline.ts:238, cognitive.ts:194, doc-coverage.ts:187). CS-004 [MUST] requires identical or nearly identical logic in more than two locations to be extracted into a shared abstraction. A withPreparedAnalysis(rootPath, patterns, stderr, fn) higher-order helper preserves per-handler ownership while sharing only the mechanical wrapper; migrating at least the two new sites keeps this diff confined.

[MEDIUM — DRY CS-004, divisor-architect]

Comment thread src/doc-coverage.ts
/**
* The FR-003 snippet rule over one rendered JSDoc description: the first
* non-empty line that is not a block-tag line (a line whose first token
* begins with @), trimmed of surrounding whitespace; undefined when no

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

docSnippetOf returns the first non-empty non-tag JSDoc line with no length cap, and serializeSymbolRow passes it to the wire unchanged — the only effective bound is safeio's 16 MiB per-file cap. The amplification is proportional and bounded, so this is a hardening gap rather than a vulnerability, but doc_snippet is the largest verbatim-untrusted-source passthrough in the wire surface, and protocol v1.2.0's sibling guidance recommends keeping opaque detail payloads under 1KB. Wire-contract hardening candidate for a future protocol revision.

[LOW — adversarial-input, divisor-adversary]

## Completeness

- [x] CHK001 Every functional requirement (FR-001 through FR-015) is traceable to at least one user story's acceptance scenarios or the shared-pipeline section that the existing methods already established.
- [x] CHK002 All user stories have at least 5 acceptance scenarios each (US1: 6, US2: 4, US3: 5, US4: 6), written in Given/When/Then form or the normative-fixture form US4 requires.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This checked criterion contradicts its own enumeration: it asserts "at least 5 acceptance scenarios each" while listing US2 at 4 (spec.md carries four US2 scenarios: row model/envelope, extraction parity, request/error parity, mode parity). The scenario coverage itself is adequate for US2's wire contract; the defect is the internally inconsistent checked quality-gate item, which weakens the checklist's value as a review artifact.

[LOW — spec-consistency, divisor-guard]

@jflowers
jflowers merged commit 043e1fc into zero-dot-force:main Nov 1, 2026
2 checks passed
@jflowers
jflowers deleted the 005-doc-cognitive-methods branch November 15, 2026 21:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

doc_coverage and cognitive_complexity methods

1 participant