fix(extract): check every document before writing, including targets they share (#43)

[adrianbrowning]

Closes #43

Summary

Previously, extract with several documents planned and wrote one document at a time. Now every document is checked before any is written:

 mdcode extract a.md b.md
-  for each document: plan → write
+  validateDocuments(a.md, b.md, "extract")
+    validate() each document              # the same rules extract() enforces
+    sharedTargetErrors(results)           # blocks in different documents, one resolved target
+  any error → report all, write nothing
+  for each document: extract() → write

• sharedTargetErrors() (in validate.ts) groups blocks from different documents by resolved target, so src/x.ts and ./src/../src/x.ts are one file. It applies the existing targetConflict() rule, now generalised: only distinct region= values in one language may share a file. Each error carries its document. Blocks already invalid in their own document are left out, so nothing is reported twice.
• mdcode validate --for extract with several documents runs the same check and marks those blocks valid: false.
• Answers to the issue's open questions:
  • A run that fails the check now stops before any write. That matches how a single-document refusal already works.
  • validate --for extract runs the cross-document check too, so it's still a faithful preflight.

Evidence

docs/a.md → src/x.ts; docs/b.md → src/y.ts and src/x.ts:

• Before: extract exited 2 and wrote src/x.ts (a.md's version) and src/y.ts, then skipped b.md's src/x.ts with "exists… Use --force". Which version won depended on document order. validate --for extract passed both documents (exit 0).
• After: extract exits 1 and writes nothing:

  Error: docs/a.md: line 1: src/x.ts: blocks at docs/a.md:1, docs/b.md:5 all write this file, but not every one declares region=; …
  Error: docs/b.md: line 5: src/x.ts: blocks at docs/a.md:1, docs/b.md:5 all write this file, but not every one declares region=; …
  Nothing was written for any of the 2 documents.
  

  validate --for extract exits 1 with an ambiguous_target error for each document.

New tests in packages/usage/tests/validate.test.ts → "extract across several documents":

• validate reports the shared target across documents, including a differently spelled path, with document set and valid: false.
• extract writes nothing when two documents write one file, not even the unrelated src/y.ts.
• extract writes nothing when a later document breaks a rule of its own. Before, docs/a.md was already written.
• Distinct regions of one language across documents are allowed: both regions land in one file.
• A repeated region=, or different languages, across documents are refused, and the messages are checked exactly.

pnpm check passes (pre-push).

Merge Danger

Door: two-way

Blast Radius: extract

Multi-document extract runs that used to finish with extract_skipped (exit 2) now refuse up front (exit 1). That includes anonymous blocks: two documents that each produce block-1.sh now conflict, and --ignore-anonymous avoids it. Single-document runs are unchanged. The bump file is marked minor.

[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

• cross-document-targets.md (view diff) (edit)

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

---

This comment is maintained by bumpy.

[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