feat(extract)!: extract blocks without file= only with --update-source (#26)

[adrianbrowning]

Closes #26

Summary

extract now writes only blocks that have file=. A block without file= (an anonymous block) becomes a file only with --update-source, which also writes the generated file= back into the Markdown, so no extracted file is left linked to nothing.

 mdcode extract README.md
-  every untagged block → block-<N>.<ext> beside the README
+  only file= blocks; untagged blocks are skipped
 mdcode extract --update-source README.md
   untagged blocks → block-<N>.<ext>, and file=block-<N>.<ext> added in the Markdown   (unchanged)
-mdcode extract --ignore-anonymous …            (removed: skipping is the default)
-mdcode validate --for extract --ignore-anonymous …

• Library: ExtractOptions.ignoreAnonymous and ValidateOptions.ignoreAnonymous are removed. updateSource decides whether anonymous blocks are extracted. validate() for extract gains updateSource, and without it reports anonymous blocks with path: null. --strict still flags them as missing_file_metadata.
• No partial writes: with several documents, the check that runs over all of them before anything is written now receives --update-source. So two documents that would both write block-1.sh are still refused before anything is written.
• examples/ci/validate-snippets.mjs: runnable blocks rarely have file=, so it now pipes each document to extract --update-source on stdin. The user's Markdown is never rewritten; the updated Markdown comes back in the JSON result, which the script ignores. An unreadable document is still reported as io_error.
• check-sync action: drops its ignore-anonymous input.
• Docs: the package README (extract rules, --update-source, the "Skip Anonymous Blocks" section removed, flags, JSON notes, API reference, and a breaking-change entry under Changes from Earlier Versions), CLI examples, the Agent Skill and the Intent records are updated. A pending bump file that mentioned ignoreAnonymous no longer does.
• Release: the bump is minor, which in 0.x means breaking. It should merge before 🐸 Versioned release #27 so it ships in 0.1.0.

Evidence

Each of the brief's acceptance criteria, against the built CLI:

Case	Before (main)	After
extract README.md with a.js plus untagged sh and json blocks	wrote block-2.sh, block-3.json	exit 0, wrote only a.js
extract --update-source --force README.md	writes block files, adds file=	same: block-2.sh, block-3.json, both file= added
extract a.md b.md, each with one untagged sh block	exit 1, ambiguous_target on block-1.sh	exit 0, "No code blocks with file metadata found." for each, nothing written
…the same with --update-source --json		exit 1, ambiguous_target for both documents, no files written, both documents unchanged
extract --ignore-anonymous / validate --for extract --ignore-anonymous	accepted	error: unknown option '--ignore-anonymous', exit 1
extract({ source, ignoreAnonymous: true }) in TypeScript	allowed	TS2353

• Tests:
  • New: extract.test.ts "skips blocks without file= unless updateSource names them in the markdown".
  • Changed: validate.test.ts now counts generated names only with updateSource.
  • Updated for the new default: the usage tests for the JSON contract, validate --for extract, the --meta table and check-sync.
  • Replaced: the test of combining --update-source with --ignore-anonymous now tests combining --update-source with --check.
• Checks: pnpm check passes (pre-push). pnpm docs:examples runs the README's 6 anonymous runnable blocks through the new validate-snippets path, and intent maintainer check --base origin/main shows 0 pending.

Merge Danger

Door: two-way

Blast Radius: extract users

Scripts that relied on plain extract writing untagged blocks get nothing for them now. They need --update-source, which also edits their Markdown. Anyone passing --ignore-anonymous or ignoreAnonymous gets an unknown-option error or a type error until they drop it. That's documented in Changes from Earlier Versions and the bump file.

[github-actions]

⚠️ ESLint Check Warnings

Click to see details

Style

> mdcode@0.0.1 lint:s /home/runner/work/mdcode-ts/mdcode-ts
> pnpm -r lint:s

Scope: 2 of 3 workspace projects
packages/mdcode lint:s$ eslint --config .eslintrc.style.json "src/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/mdcode lint:s: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/mdcode lint:s: Done
packages/usage lint:s$ eslint --config .eslintrc.style.json "{tests,fixtures,examples}/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/usage lint:s: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/usage lint:s: Done

Correctness

> mdcode@0.0.1 lint:esl /home/runner/work/mdcode-ts/mdcode-ts
> pnpm -r lint:esl

Scope: 2 of 3 workspace projects
packages/mdcode lint:esl$ eslint "src/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/mdcode lint:esl: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/mdcode lint:esl: Done
packages/usage lint:esl$ eslint "{tests,fixtures,examples}/**/*.{j,t}s{,x}" --cache --max-warnings=0
packages/usage lint:esl: [baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: 'npm i baseline-browser-mapping@latest -D'
packages/usage lint:esl: Done

View workflow run

[github-actions]

The changes in this PR will be included in the next version bump.

Minor releases

• mdcode-ts 0.0.4 → 0.1.0

Bump files in this PR

• library-cli-boundary.md (view diff) (edit)
• anonymous-only-with-update-source.md (view diff) (edit)

Click here if you want to add another bump file to this PR

---

This comment is maintained by bumpy.