Repository navigation
docs: use ESA npm tag in generated install instructions - #3742
rachitm022 wants to merge 2 commits into
Conversation
| symlinkSync(path.join(ROOT, 'compliance', 'cache'), path.join(worktree, 'compliance', 'cache'), 'dir'); | ||
|
|
||
| const originalVersion = JSON.parse(readFileSync(path.join(worktree, 'package.json'), 'utf8')).version; | ||
| run('npm', ['run', 'generate-agent-docs']); |
There was a problem hiding this comment.
Medium: This pre-changeset version assertion hardcodes @beta, coupling it to the current 17.0.0-beta.22 base. .changeset/pre.json is already on tag esa, so the first release in this lane lands 17.0.0-esa.N on main. From that point every subsequent run branches from an esa-versioned base, generate-agent-docs emits @adcp/sdk@adcp-3.3-esa, and this line fails. Derive the expected tag from originalVersion (read before changeset version) instead of pinning @beta — the esa branch at L150-155 already does the robust thing conditionally.
There was a problem hiding this comment.
Ladon verdict: Approve
Approve — ESA-lane prep PR, clean with one non-blocking medium.
The core change in scripts/generate-agent-docs.ts maps the prerelease tag esa → dist-tag adcp-3.3-esa while preserving existing @beta and stable (major.minor) behavior — logic is correct. The empty changeset is appropriate: a doc-generation script with no published-artifact impact (not under src/lib/**, bin/**, build-affecting scripts/** in a changeset-relevant way, or a package.json files path) does not require a release entry, so the changeset-vs-wire-impact gate is not triggered.
Medium findings
- test/release-version-docs.test.js:139 — Pre-version assertion hardcodes
@beta; will fail once the first esa release lands on main (base version becomes-esa.N). Prefer deriving the expected tag fromoriginalVersion. Worth fixing but not blocking.
Decision path: no critical/high findings (row 1 n/a); gated_paths false (row 2 n/a); high_risk false (rows 3/5 n/a); single medium is test/correctness category, not data-loss/schema/infra (row 4 n/a); no prior escalation (row 6 n/a); no no-auto-approve team match (row 7 n/a); only 1 medium finding, well under the 3-medium threshold (row 8 n/a). Falls through to row 9 → approve.
Medium findings
- test/release-version-docs.test.js:139 — Pre-version assertion hardcodes @beta, breaks once esa lane lands on main
There was a problem hiding this comment.
Ladon verdict: Approve
Approve.
Clean, minimal fix to the doc-generator script. scripts/generate-agent-docs.ts:590-592 factors out the prerelease tag and remaps only esa → adcp-3.3-esa; beta and stable install strings are unchanged, so the generated npm install @adcp/sdk@... line (L624) now matches the real ESA npm dist-tag instead of the non-existent @esa. The new test adds worktree pre/post-changeset version assertions covering both @beta and @adcp-3.3-esa.
Checked:
- No critical/high/medium findings from the reviewer.
- Empty changeset is correct: this is a doc-generator script that does not alter published runtime (
src/lib/**/bin/**/ publishedfilesuntouched), so changeset-vs-wire-impact rule does not require a bump. - No witness-not-translator, version-pathway, or transport-client concerns — no wire-shape code touched.
- high_risk false; gated_paths false; no no-auto-approve team match; no prior decision.
Decision table: none of rows 1–8 fire (no findings, no gates) → row 9 approve.
Non-blocking nit (not tracked): adcp-3.3-esa hard-codes the 3.3 train rather than deriving from ADCP_VERSION — will need a touch if the ESA train advances.
Summary
The generated
llms.txtfor the ESA prerelease currently recommendsnpm install @adcp/sdk@esa. The17.x-esarelease workflow publishes under theadcp-3.3-esanpm tag, so the generated instruction would fail after release.Map only the
esaprerelease identifier to the configured npm tag. Beta and stable install instructions keep their existing behavior. An empty changeset keeps this documentation generator fix out of the release version calculation.Verification
node --test test/release-version-docs.test.js— 4 passed; release simulation checks both@betaand@adcp-3.3-esa.npm run generate-agent-docsandnpm run ci:docs-check— checked-in beta docs are current; the release simulation regenerates ESA docs.npm run typechecknpx prettier --check scripts/generate-agent-docs.ts test/release-version-docs.test.jsnpx changeset status --since=origin/17.x-esaThis should merge into
17.x-esabefore the generated version PR #3741; Changesets can then refresh that PR with the correct install command. This PR does not publish a package.