Snippet fixtures

Each subdirectory here is a small tree of .wyn files that a documented snippet needs in order to compile. Tag the snippet with

<!-- wyn-check: fixture=NAME -->

and scripts/check_snippets.py copies scripts/fixtures/NAME/ into a private temp directory, writes the snippet beside those files as _snippet.wyn, and runs wyn check (and wyn build / wyn run on the --build / --run passes) there. Wyn resolves import from the source file's directory, so the snippet's imports resolve against the fixture.

fixture= composes with the other directives; put the primary directive first, because wyn-check: must be followed immediately by run / continue / skip:

<!-- wyn-check: run fixture=book-modules out="3\n15\n" -->

Why this exists

Before fixtures, every snippet that imported a sibling module or a package failed with Module 'x' not found / Package 'x' not installed. 36 of them did, permanently, which trains everyone to ignore a red gate. The alternative - annotating them all skip - would have hidden real bugs: turning these on immediately caught

• args.get("name") in two places (the package has value, not get),
• Http.respond(fd, 200, "ok") missing its content-type argument,
• a local user = ... colliding with the imported module name user,
• a facade exporting pub fn mean(values: [int]), which the compiler rejects across a flat import.

Two kinds of fixture

Transcribed - the module the page itself shows the reader writing (math_utils, utils-greet, utils-helper, book-modules, book-user-ext, appendix-imports). Keep these in step with the block the page prints.

Signature stubs - the public surface of a real package, with stub bodies (args, aws, web, cool). args is the upstream source verbatim; aws and web are signature-only because vendoring 827 and 219 lines of package implementation into the docs repo buys nothing the gate needs. Each file records how to regenerate it from upstream.

A stub can drift. If a package changes a signature and the stub does not, the gate will pass a snippet the real package would reject. Re-diff the stub against upstream (grep -E '^\s*pub fn' src/<pkg>.wyn) whenever that package releases.

Adding one

1. Create scripts/fixtures/<name>/ with the .wyn files the snippet imports.
2. Check each fixture file compiles on its own: wyn check scripts/fixtures/<name>/*.wyn.
3. Tag the snippet and run scripts/check-snippets.sh --book --run.
4. Mutation-test it: break the snippet's call (wrong arity, wrong type) and confirm the gate goes red. A fixture that cannot fail is not a check.

Note that wyn check does not verify that an imported module actually has the member you called - only --build catches that - so mutation-test with --build as well when the mutation is a bad member name.