Skip to content

docs: say what @effect/docgen 0.5.2 actually loads in pnpm-workspace.yaml - #346

Merged
thomasfosterau merged 1 commit into
trunkfrom
issue-343-docgen-ts-comments
Oct 15, 2026
Merged

thomasfosterau merged 1 commit into
trunkfrom
issue-343-docgen-ts-comments

Conversation

@thomasfosterau

@thomasfosterau thomasfosterau commented Oct 15, 2026 •

Copy link
Copy Markdown
Owner

Summary

This PR fixes three comments in pnpm-workspace.yaml. They said @effect/docgen drives TypeScript through the JS API and so sees the TS6 side of the split. The pinned version, 0.5.2, never loads the typescript package. The PR changes comments only: the docgen version, the peer rule and the lockfile stay as they are.

Refs #343 (#343 stays open: its second done-when item, the owner's decisions on the docgen 4.x move and on AGENTS.md lines 9/34, is not done by this PR)

  • The @effect/docgen catalog entry now says what 0.5.x actually does:
    • its bin.cjs bundles TypeScript 5.5.2 (through ts-morph) to parse src/;
    • it type-checks the examples with the tsc on PATH, which is native TS7 under vp run;
    • it runs the examples under tsx;
    • it prepends import * as assert from 'assert' to any example that uses assert..
  • The typescript (TS6 alias) catalog entry no longer lists docgen as a JS-API consumer. It names scripts/docgen-class-examples.ts (import ts from "typescript"), which does load the alias.
  • The "@effect/docgen>typescript": "6" peer rule now says what it is for. It only satisfies pnpm's peer-range check, because 0.5.x declares typescript ^5.2.2 and never loads it. The comment also says when the rule can be dropped.

Evidence (details in #343):

  • npm pack @effect/docgen@0.5.2 in a fresh directory gives a single bin.cjs that inlines @ts-morph/common@0.24.0/dist/typescript.js (version = "5.5.2") and contains no require("typescript").
  • runTscOnExamples spawns tsc, and runTsxOnExamples spawns tsx.
  • A full docgen run with a Module._load hook made no request for the typescript package. The only TypeScript-related request was the bundled compiler's optional @microsoft/typescript-etw probe.

Verification

Run in order on a fresh clone. Every gate passed.

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

Changeset

None. The PR changes only comments in pnpm-workspace.yaml, which is tooling, not published behaviour.

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

Notes

These are left for the owner (see #343):

🤖 Generated with Claude Code

https://claude.ai/code/session_01MbvVf1RHTwKCbEw9dyn3Aa


Generated by Claude Code


Generated by Claude Code

…yaml

docgen 0.5.2's bin.cjs bundles TypeScript 5.5.2 (via ts-morph) and never
requires the `typescript` package; it type-checks examples with the `tsc`
on PATH and runs them under `tsx`. Correct the three comments that said it
drives the TS6 alias through the JS API, and say the peer rule only
satisfies pnpm's range check.

Refs #343

Claude-Session: https://claude.ai/code/session_01MbvVf1RHTwKCbEw9dyn3Aa
Co-Authored-By: Claude <noreply@anthropic.com>
@thomasfosterau
thomasfosterau merged commit ecddfa8 into trunk Oct 15, 2026
1 check passed
@thomasfosterau
thomasfosterau deleted the issue-343-docgen-ts-comments branch October 15, 2026 02:00
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.

2 participants