Skip to content

docs(AGENTS): say what vp run docgen runs and with which tsc - #298

Merged
thomasfosterau merged 1 commit into
trunkfrom
issue-290-agents-docgen
Oct 9, 2026
Merged

thomasfosterau merged 1 commit into
trunkfrom
issue-290-agents-docgen

Conversation

@thomasfosterau

Copy link
Copy Markdown
Owner

Summary

Applies the AGENTS.md wording proposed in #290, which the owner approved on 2026-10-09 (latest comment on #290). The text is verbatim, including the optional line-9 change. CLAUDE.md is still a symlink to AGENTS.md. Nothing else in AGENTS.md changed.

Closes #290

Claims checked against trunk (2521e53) before editing

  • Which tsc docgen spawns. @effect/docgen 0.5.2 (node_modules/@effect/docgen/bin.cjs, runTscOnExamples) runs make47("tsc", "--noEmit", "--project", <outDir>/examples/tsconfig.json), so it uses whatever tsc is on PATH. Under vp, command -v tsc resolves to node_modules/.bin/tsc, and tsc --version reports Version 7.0.2+effect-tsgo.0.47.2.
  • Parse vs. examples options. docgen.json sets both parseCompilerOptions (ts-morph/TS6 parse) and examplesCompilerOptions (written into the examples tsconfig). Each one includes "types": ["node"].
  • Class-level examples (chore: check and run the class-level examples docgen skips #289). On trunk the docgen task in vite.config.ts is docgen && tsx scripts/docgen-class-examples.ts. That runner calls spawnSync("tsc", ["--noEmit", "--project", …]) and then tsx, using the same PATH lookup and only examplesCompilerOptions. In this branch's gate run it printed 10 class example(s) found and every class example compiled and ran.
  • What docgen collects. docgen's getExampleFiles collects examples from modules, class methods and static methods, interfaces, type aliases, constants, functions and namespaces. It does not collect them from the class declaration itself or from properties.
  • Property-level examples (chore: docgen also skips @example on class properties #288). These are still unchecked. chore: docgen also skips @example on class properties #288 is open, and the runner reads only the class's own doc comment.

No claim was wrong or stale, so I made no adjustments.

Before / after

Line 9 (end of the TS7 bullet):

Before: TS6 (tsc6, the JS compiler) is only what the JS-API consumers — @effect/docgen, the tsdown declaration bundler, the editor language service — load.

After: TS6 (tsc6, the JS compiler) is only what the JS-API consumers — @effect/docgen's parse, the tsdown declaration bundler, the editor language service — load.

Line 23 (first sentence; the rest of the paragraph is unchanged):

Before: @effect/docgen doesn't just type-check JSDoc @example blocks — it compiles them as ESM and runs them (vp run docgen).

After: vp run docgen doesn't just type-check JSDoc @example blocks — it compiles them as ESM and runs them. @effect/docgen covers the examples on modules, functions, constants, types, namespaces and class methods. The task's second sub-task, scripts/docgen-class-examples.ts, covers the @example in a class's own doc comment, which docgen skips (#276). Neither covers an @example on a class property or constructor yet (#288).

Line 34:

Before: Docgen drives TypeScript through the JS API, so it sees the TS6 side of the split with its own compiler options (docgen.json; types: ["node"] is explicit because TypeScript 6 no longer auto-includes @types).

After: Docgen parses src/ through the TypeScript JS API, so its parse sees the TS6 side of the split, under parseCompilerOptions in docgen.json. It compiles the examples by spawning the tsc on PATH, which under vp run is the native TS7 tsc, under examplesCompilerOptions. The class-example runner spawns the same tsc. types: ["node"] is explicit in both option sets because TypeScript 6 no longer auto-includes @types.

Line 85:

Before: - vp run docgen — type-check and execute every JSDoc @example; generate the API docs under docs/.

After: - vp run docgen — type-check and execute every JSDoc @example (class-property examples excepted, #288); generate the API docs under docs/.

Verification

All gates ran in this order on a fresh clone at the head commit, and each one passed.

  • pnpm install --frozen-lockfile: pass
  • vp run build: pass (✔ Build complete)
  • vp check: pass (All 183 files are correctly formatted; Found 0 errors, warnings only from the existing warn tier)
  • vp run check (sources, type-level tests, examples, emitted declarations): pass (check: every type gate green)
  • vp run -r test:unit: pass (root 42 files / 2492 tests; examples 2/41, 2/45, 4/54)
  • vp run docgen (every JSDoc @example compiled and executed): pass (docgen-class-examples: every class example compiled and ran)
  • fallow audit --format json --quiet --explain --gate-marker agent: "verdict":"pass"
  • fallow audit --base origin/trunk: pass (✓ No issues in 1 changed file)

Changeset

None. This change touches only AGENTS.md and leaves the published package's behaviour unchanged.

  • A changeset under .changeset/ for every change to published behaviour (not applicable)

Notes

These are for the owner. Neither one led to a change in the approved text:

🤖 Generated with Claude Code


Generated by Claude Code

Apply the owner-approved wording from #290 to the docgen section,
the TS6 bullet and the Commands entry: docgen parses `src/` with the
TS6 JS API under `parseCompilerOptions` but compiles examples with the
`tsc` on PATH (native TS7 under `vp run`) under
`examplesCompilerOptions`; class-level examples are covered by
`scripts/docgen-class-examples.ts` (#276); class-property examples are
still unchecked (#288).

Closes #290

Claude-Session: https://claude.ai/code/session_0187g2QpzaHqEzX8GJxiJBVc
Co-Authored-By: Claude <noreply@anthropic.com>
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.

docs: AGENTS.md docgen section is inaccurate (class examples, TS6 claim)

2 participants