ci: check the packed package without a checkout - #1767

The check Stage 2 exists for. A new `package-check` job downloads the tarball
uploaded by node26, installs it as a real dependency, and type-checks every
declaration the package ships.

Deliberately not built through `toSteps`: that helper injects
`actions/checkout`, and the missing checkout is the whole point. With no
repository on the runner there is no tsconfig.json up the tree to inherit, no
node_modules to resolve into, and no source file that can stand in for a
declaration the tarball omits, so the job sees what a consumer sees.

Four properties decide whether it can fail at all, and each is asserted:
declarations are enumerated from the installed artifact rather than a written
list, so a module that gains a private type module later is checked without the
job being edited; skipLibCheck stays at its false default; the file list is
non-empty, which is the one way the job could look healthy while checking
nothing; and the compiler is the package's own pin, read out of the packed
package.json, since without a checkout there is no lockfile and the registry
would otherwise decide the verdict.

Ran the emitted script verbatim against a real tarball rather than trusting the
generator: 395 declarations, TypeScript 7.0.2 resolved from the packed pin,
exit 0. Removing the 16 private.d.ts leaves 379 and still exits 0, so the
exclusion in the next step is safe; appending a dangling private import to one
packed declaration exits 2 with TS2307. The job is green today because nothing
is excluded yet — its value appears when the negation lands, which is why the
guard comes first.

The proof kills five mutants: a checkout step, a dropped needs edge, a needs
edge pointing at a job that does not produce the artifact, skipLibCheck true,
and a dropped empty-list guard.

Two existing assertions moved, both by design rather than accommodation. The
job count is 13 -> 14, and jobNeeds asserted no job ordered itself; that guard
fired exactly when its first consumer arrived and now pins one ordering edge,
so a second stays a deliberate change.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LqeS5t2ZKkSu3chRPMXR7n

Three review findings, all correct.

The script hard-coded node_modules/functionalscript. `fjs ci` is a public
command that generates workflows for other projects, and the proof already
exercises a package named other-package, so for them the check would fail on a
missing directory — or worse, silently validate a `functionalscript` dependency
that happens to be installed instead of the artifact just built. That is a
plausible wrong answer where DESIGN.md §10 requires a refusal. The package
directory is now derived from the tarball, by reading back the single
dependency `npm install ./*.tgz` writes.

Verified by building a second tarball named other-package and running the
emitted script against it: resolves other-package, finds its declaration, exit
0. Against this repository's own tarball: 395 declarations, TypeScript 7.0.2,
exit 0. A package with no compiler pin exits non-zero rather than installing a
floating compiler.

The regex `/^=/` is gone, and not by rewriting it: npm accepts the `=7.0.2`
range verbatim, so the stripping was never needed. fjs/AGENTS.md forbids
regular expressions; the fix removes the reason for one rather than the syntax.

Adding a job changes the workflow `fjs ci` emits for every caller, which is a
behavior change for users of the package rather than an internal refactor, so
this adds the changelog entry it needs.

The proof now pins the derivation and asserts the hard-coded name is absent, so
the regression cannot come back quietly.

Changelog: changelog/unreleased/1767.md

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LqeS5t2ZKkSu3chRPMXR7n

Three more review findings, all correct.

The module header lacked @module. fjs/AGENTS.md §2 requires it on every
module.* entry point, and all five sibling fjs/ci modules carry one; #1756
removed the tag from non-module files, not from these.

The proof lived in the parent. fjs/ci/deno, fjs/ci/nix and fjs/ci/node all have
co-located proofs, so the precedent is the opposite of what I assumed. The job's
own shape is now proved in fjs/ci/package/proof.f.mjs, and the parent keeps only
what the assembled workflow can show: that the job is wired in, and that the job
it waits for is really the one that uploads — an edge pointing at a job that
never produces the artifact would satisfy the ordering and still never run.

The compiler pin was the substantive one. Reading devDependencies.typescript
gives a dependency specification, not a resolved version: this repository pins
=7.0.2, but a project writing ^7.0.0 would have had npm choose, which is exactly
the determinism the checkout-less job exists to preserve. The script now
compares the installed version against the literal pin and refuses when they
differ.

That case is worse than it looks, and the test shows why: ^7.0.0 installs 7.0.2
today, so a range is indistinguishable from an exact pin until the day the
registry publishes 7.0.3 and the verdict moves with no change to the package.
Verified: ^7.0.0 exits non-zero, =7.0.2 exits 0 at 396 declarations, and a
second tarball named other-package still resolves and passes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LqeS5t2ZKkSu3chRPMXR7n

Simplicity over the narrower case. `npm install "packed@file:$(ls *.tgz)"`
installs the tarball under a fixed directory name, so every later step names it
literally: the name derivation and the $GITHUB_ENV hand-off both go away, and no
value crosses a step boundary any more.

Nothing is baked into the generated workflow that package.json can change, so a
version bump still regenerates nothing — which the derived name also achieved,
but this achieves it with less machinery.

What an alias gives up is recorded next to it rather than left in a review
thread: a package that imports itself by name, legal once `exports` is declared,
does not resolve under a different directory name, so such a package would fail
a check a real consumer passes. Nothing here self-references, and the comment
says to revisit if that changes.

Re-verified end to end on the four emitted steps: this repository's tarball
passes at 396 declarations, a tarball named other-package passes at 1 — the
alias makes genericity structural rather than derived — and failures still
attribute per step, a range pin at the compiler step and a dangling declaration
at the type-check step with TS2307.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LqeS5t2ZKkSu3chRPMXR7n

The steps were unreadable because they did work that belongs in the generator.
Thirty lines of run: script become eight.

set -eu is gone. GitHub runs run: steps as `bash -e`, so -e was already there,
and -u guarded unset variables only while a value crossed steps through
$GITHUB_ENV; nothing crosses now. Verified by running the emitted steps under
`bash -e`: failures still propagate and still land in the right step.

The compiler version moves to fjs/ci/config, beside the bun, deno, node and
wasmtime pins. That deletes the whole of the second step: reading the pin out of
the packed package.json at run time, installing it, re-reading what was actually
installed, and stripping a leading `=` through an environment variable to
compare the two. All of it existed to establish a version this repository
already states, and now states in the one place tool versions live. One line
remains.

This changes what the pin means, which is worth saying plainly: the check now
installs the version this repository pins rather than the one the artifact
declares. For a package generated by `fjs ci` elsewhere that is the CI tool's
compiler, exactly as the node, deno and bun versions in the same file already
are. It also removes the range hole by construction — a config constant cannot
be a floating range without that being a visible change here.

Also enumerates *.d.cts, so "every declaration the package ships" is true for a
package that ships CommonJS declarations, and requires exactly one archive, so
which package is under test is never ambiguous.

Verified end to end on the emitted steps: 396 declarations and TypeScript 7.0.2
for this package, a .d.cts-only package enumerated and checked, two archives
refused, and a dangling declaration still failing at the type-check step with
TS2307.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LqeS5t2ZKkSu3chRPMXR7n

tsc splits an @response file on whitespace, so a declaration under a directory
with a space in its name was read as two root files. Reproduced before fixing:
a package shipping "space dir/a.d.ts" failed with TS6053 "File 'dir/a.d.ts' not
found" — a valid package rejected by the check rather than by its own contents.

find -printf '"%p"\n' quotes each path. One flag, no extra command: the same
package now passes, this repository's 396 declarations are unchanged, and a
dangling private import is still caught with TS2307.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LqeS5t2ZKkSu3chRPMXR7n

Review found the compiler pin living in two unlinked places — fjs/ci/config and
package.json — with a proof that could not see them disagree, because it
imported the same constant the generator interpolated and so compared a value
with itself. Setting the config constant to =5.9.3 left the suite green and the
job installing the wrong compiler: silent at both layers, unlike every earlier
gap in this series.

The fix is not a better assertion. It is having one place. The generator already
reads Cargo.toml, so it now reads package.json and takes devDependencies
.typescript from there. The config constant is gone, and with it the thing that
could drift. Changing the pin now changes ci.yml, which node26's existing
regeneration check already guards.

The proof supplies its own pin, one no configuration holds, so finding it proves
the value came from the parameter rather than from a constant compared with
itself.

Without a pin the check cannot run deterministically, so it is not generated
rather than run against a compiler nobody chose; a proof covers each shape that
means "no pin", which is also what keeps branch coverage at 100%.

Comments no longer travel into the emitted commands: ci.yml is output, and the
reasoning belongs in the generator that a maintainer reads. The archive-count
guard goes too — two archives already make npm's spec malformed and fail
loudly, so it only restated a failure that happens anyway.

Verified: 396 declarations and TypeScript 7.0.2 from package.json's own pin, a
dangling private import still TS2307 at the type-check step, 3478/3478, coverage
100%, round-trip clean.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LqeS5t2ZKkSu3chRPMXR7n

Two commands shared a step for no reason: `npm init` and `npm install` are
separate things, and the split exists so a failure names what failed. Every step
is now one command, six in all.

The response file is gone with it. `find -print0` and `xargs -0` hand the paths
to tsc as arguments, so a space or a quote in a path survives without quoting or
escaping — review found both cases, and this removes the mechanism rather than
patching it twice. The empty-list guard stays as its own step: tsc does exit
non-zero on no arguments, but by printing usage, which says nothing about why.

The compiler pin must now be exact. A range such as ^7.0.0 lets a later registry
release change the verdict with no change here, which is the one thing running
without a checkout is meant to prevent. Relaxing the pin drops the job from the
generated workflow — a visible diff in review rather than a quiet loss of
checking.

Verified on the emitted steps: 396 declarations and TypeScript 7.0.2, a
directory named `we"ird dir` with both a space and a quote now passes where the
response file would have split it, and a dangling private import still fails the
type-check step. 3480/3480, coverage 100%, round-trip clean.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LqeS5t2ZKkSu3chRPMXR7n

startsWith('=') was the wrong shape rather than the wrong constant: `=7.x`,
`=7.0`, `=7.0.2 || 8.x` all pass a prefix test and are all ranges npm resolves
against the registry, which is exactly what running without a checkout is meant
to rule out.

The pin must now be `=MAJOR.MINOR.PATCH` and nothing else — three dot-separated
runs of digits after the sign. No regex; the repository forbids them and the
check is two lines without one.

It rejects a prerelease pin too, which is stricter than npm needs. That is the
right way to be wrong here: the cost is the job disappearing from ci.yml, a
visible diff in review, rather than a check that silently stops meaning
anything.

The validator caught the proof's own fixture, which used =9.9.9-run. Nine
rejection cases now cover the shapes that pass a prefix test, which is also what
keeps branch coverage at 100%.

This closes the class rather than patching another instance of it: the previous
three rounds each fixed one spelling of "not really pinned".

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LqeS5t2ZKkSu3chRPMXR7n

The package check walked the artifact with `find`, guarded the result with
`test -s`, and fed it to `tsc` through `xargs -0`. A `tsconfig.json` with an
`include` pattern does all three, and does them better:

- No path passes through the shell, so a space or a quote in a directory name
  has nothing to survive. The `-print0`/`xargs -0` pairing existed only to carry
  bytes safely across that boundary; there is no boundary now.
- An empty match is TS18003, which names the pattern that found nothing. The
  `test -s` guard could only say that a file was empty.
- `.d.cts` and `.d.mts` need no enumerating: `include` selects every extension
  the compiler reads, so a package shipping a form we did not list is covered
  rather than skipped.

Six steps become five, and three external tools become none. Root AGENTS.md §6
asks for an established tool that parses what it checks rather than a pattern
that approximates one; here the tool that does the checking also does the
finding.

`exclude` is emptied because the default excludes `node_modules`, the only place
the artifact exists. `skipLibCheck` is stated rather than left at its default —
it is the one option whose flip leaves the job green having opened nothing, and
the proof pins it.

`fjs/ci/README.md` said the built-in command does not read `package.json`. Since
the compiler pin moved out of the config constant, it does; the paragraph now
says what it reads and what an inexact pin costs.

Verified by running the emitted steps verbatim against real tarballs: 396
declarations checked, identical to the previous pipeline; a declaration
referencing a module the tarball does not carry fails with TS2307; the same
break passes silently under skipLibCheck true; a `.d.cts` under a directory
named `we"ird dir` is enumerated; a package shipping no declarations exits 2
with TS18003.

3479/3479, coverage 100%, workflow regenerates clean.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LqeS5t2ZKkSu3chRPMXR7n

REVIEW.md: "where does this knowledge live once the pull request is merged? In
the diff, in the design document, or in a todo/ issue. Only 'in the review
thread' is wrong: it is the one place the answer will not survive." Nine
findings on #1767 were answered only in threads. The answers move here.

In the generator, next to the decision each explains:

- Why tsc enumerates rather than a shell walk, with the three defects the
  find/test/xargs version had — including xargs' finite command buffer
  splitting a large package into separate programs, which was silent. Written
  as "do not go back", because the pipeline reads like the more explicit
  choice.
- Why `**` rather than a list of declaration extensions, and what that costs:
  a package shipping sources and no declarations has a nonempty root set, so
  TS18003 cannot fire.
- Why npm, npx and tsc are the tools that remain under AGENTS.md §6.
- Why there is no guard against a second .tgz.

In `fjs/ci/README.md`, the `package/` module joins the file list, stating the
question a reader asks first: why the one job built without `toSteps`, and what
a checkout would do to it.

In a new `fjs/ci/todo/package-check-unsupported-package-shapes.md`, the three
declined findings — typesVersions, refusing a project with no exact pin, and a
package shipping sources — with what each would cost to build and what has to
be true before it is worth building. They are one question, and it is the
question `node26-typedef-gate-reaches-consumers.md` already asks about another
job, so the two are linked.

No generated output changes: `ci.yml` is byte-identical, which is the point of
keeping the explanations in the source rather than in the emitted commands.

3479/3479, coverage 100%, tsc clean.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LqeS5t2ZKkSu3chRPMXR7n

npm's `**` walks into a dot-prefixed name and TypeScript's does not. `files`
therefore publishes `.d/x.d.ts` and a lone `include` of `**/*` left it
unchecked — silently, and even when it is the package's own `types` entry
point. Reproduced with a package whose `types` is a broken `.hidden/b.d.ts`:
installed, never loaded, job green.

Two patterns naming a dot segment explicitly close the shapes anyone ships:
`**/.*` for a dot-named file, `**/.*/**/*` for anything under a dot-named
directory at any depth. Verified all four arrangements enumerated — visible,
dot-named file, top-level dot directory, nested dot directory — and the
reproduction now fails with TS2307 on the file it was skipping. The real
package is unchanged at 396 declarations, exit 0.

Unlike the other package-shape findings this one was reachable rather than
structural: nothing here ships a dot-prefixed path today, but `files` would
publish one.

The fix is honest about its limit rather than claiming completeness. Two dot
segments in a row still escape, because the inner `**` has to cross the second,
and a pattern per arrangement of dots does not converge. Closing it properly
means reading the installed tree's real names, which is a tool walking the tree
and so the AGENTS.md §6 conversation. Recorded as issue 3 in
fjs/ci/todo/package-check-unsupported-package-shapes.md, with that condition
stated.

3479/3479, coverage 100%, tsc clean.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LqeS5t2ZKkSu3chRPMXR7n