Repository navigation
docs(AGENTS): say what vp run docgen runs and with which tsc - #298
Merged
Merged
Conversation
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>
This was referenced Oct 15, 2026
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.
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.mdis still a symlink toAGENTS.md. Nothing else in AGENTS.md changed.Closes #290
Claims checked against trunk (
2521e53) before editingtscdocgen spawns.@effect/docgen0.5.2 (node_modules/@effect/docgen/bin.cjs,runTscOnExamples) runsmake47("tsc", "--noEmit", "--project", <outDir>/examples/tsconfig.json), so it uses whatevertscis onPATH. Undervp,command -v tscresolves tonode_modules/.bin/tsc, andtsc --versionreportsVersion 7.0.2+effect-tsgo.0.47.2.docgen.jsonsets bothparseCompilerOptions(ts-morph/TS6 parse) andexamplesCompilerOptions(written into the examples tsconfig). Each one includes"types": ["node"].docgentask invite.config.tsisdocgen && tsx scripts/docgen-class-examples.ts. That runner callsspawnSync("tsc", ["--noEmit", "--project", …])and thentsx, using the samePATHlookup and onlyexamplesCompilerOptions. In this branch's gate run it printed10 class example(s) foundandevery class example compiled and ran.getExampleFilescollects 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.@exampleon class properties #288). These are still unchecked. chore: docgen also skips@exampleon 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):
Line 23 (first sentence; the rest of the paragraph is unchanged):
Line 34:
Line 85:
Verification
All gates ran in this order on a fresh clone at the head commit, and each one passed.
pnpm install --frozen-lockfile: passvp run build: pass (✔ Build complete)vp check: pass (All 183 files are correctly formatted;Found 0 errors, warnings only from the existingwarntier)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@examplecompiled 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.
.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:
@exampleon class properties #288. Line 23 says neither docgen nor the runner covers an@example"on a class property or constructor yet (chore: docgen also skips@exampleon class properties #288)". That is true, but chore: docgen also skips@exampleon class properties #288 only proposes property examples. docgen 0.5.2 never parses a constructor's JSDoc: it only reads the constructor's signature for the class declaration line. So constructor examples are never published, and line 85 rightly mentions only property examples. When chore: docgen also skips@exampleon class properties #288 lands and its caveats are removed, the constructor part of line 23 will need its own wording or a separate issue.@types" in line 34. This now covers both option sets, andexamplesCompilerOptionsare used by the TS7tsc. The reason is still correct, because TS7 keeps TS6'stypes: []default. I left it as approved.🤖 Generated with Claude Code
Generated by Claude Code