Repository navigation
feat: doc_coverage and cognitive_complexity methods (Gaze analyzer protocol v1.2.0) - #18
Conversation
…gnitive_complexity) for issue zero-dot-force#6
…), docCoverage entry (005 T008)
jflowers
left a comment
There was a problem hiding this comment.
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_complexityrows are contract-correct (identity keyfunctionper protocol.md v1.2.0, cross-checked against the pinned sibling clone), but the installed gaze dev build tagsFunctionCognitiveComplexityDatawithjson:"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).
| import { collectSources, propertyNameText } from "./extract.js"; | ||
| import { compareFileLineName } from "./internal.js"; | ||
| import { derivePackage } from "./models.js"; | ||
| import { nextJSDocHost } from "./signals/evidence.js"; |
There was a problem hiding this comment.
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]
| rows.sort(compareCognitiveRows); | ||
| return rows.map(serializeCognitiveRow); | ||
| } finally { | ||
| if (prepared.context.mode === "program") { |
There was a problem hiding this comment.
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]
| /** | ||
| * 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 |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
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]
Summary
Closes #6
Implements the two methods Gaze analyzer protocol v1.2.0 added, completing reading-stone's optional-method surface:
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).documentedis true iff a JSDoc comment is attached to the implementation declaration (overload-aware);doc_snippetis the first non-tag summary line, omitted when empty. Rows are (file, line, name)-ordered and byte-identical across identical requests.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), flatelse, labeledbreak/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.-32602error table; capabilities flipped todoc_coverage: trueandcognitive_complexity: true; the reserved-32601set shrunk to exactly{analyze, stream}.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):
Wire-level probe of both new methods against the built server (the US1/US2 independent tests do this as subprocesses — tests/cli.test.ts):
doc_coveragemust returnsymbolsrows whosekindvalues all belong to the closed set (function/type/constant/variable/class/method), withdocumentedflags anddoc_snippetpresent iff non-empty;cognitive_complexitymust returnfunctionsrows carrying thefunctionidentity key. Acceptance fixtures:tests/doc-coverage.test.tspins exactsymbolsoutput for documented/undocumented symbol fixtures;tests/cognitive.test.tspins 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-sidejson:"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
node dist/main.js --stdio.initializeresponse now advertisesdoc_coverage: trueandcognitive_complexity: true, and the reserved-32601set is exactly{analyze, stream}.doc_coveragerows: everykindfrom the closed set,documentedreflecting attached JSDoc,doc_snippetcarrying the first summary line.cognitive_complexityrows keyed byfunctionwith hand-computed SonarSource scores (nesting, sequences, recursion, labeled breaks).gaze docscan ./... --analyzer=<wrapper>over this repo reports 666 symbols at 85.6% documented.Key Files Changed
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:
src/doc-coverage.tsimportsnextJSDocHostfrom./signals/evidence.js, crossing the pipeline-stage boundary thatsrc/internal.tsexists to enforce. Follow-up: hoistnextJSDocHostintosrc/internal.ts, re-point both consumers, refresh the AGENTS.md structure comment.-32602mapping, try/finally dispose) now exists at six sites. Follow-up: extract awithPreparedAnalysishigher-order helper; at minimum migrate the two new sites.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.doc_snippetcarries 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.R1–R15citations resolve only to plan.md prose. Post-merge: land the research companion or reword citations to resolvable anchors.json:"name"while protocol.md v1.2.0 pinsfunctions[].function, so gaze's enrichment and--max-cognitive-complexitygate cannot match reading-stone's contract-correct rows. Reading-stone needs no change; follow-up: file the upstream report on unbound-force/gaze.This PR was generated by /uf.finale (AI-assisted).