diff --git a/.intent/review-state.json b/.intent/review-state.json index a7a27c5..809241e 100644 --- a/.intent/review-state.json +++ b/.intent/review-state.json @@ -294,6 +294,18 @@ "evidence": [ "update-readme-action.test.ts (8 tests) passes against a local bare repository and a stand-in gh: PR holds only the two documents update wrote; sources untouched; caller checkout unchanged; rerun pushes nothing; refresh on main's new tip; behind checkout still bases on tip; in-sync closes the PR; unreadable file= opens nothing; branch==base exits 2. check-sync-action.test.ts (8 tests) still passes after moving its helpers to .github/actions/shared/mdcode.mjs." ] + }, + "source:.out-of-scope/extract-shrink-guard.md": { + "fingerprint": "b32c01d95ab489e49413e956f1cbb7e37fcd0474debe8d0925484b8a6db57d3b", + "snapshot": { + ".out-of-scope/extract-shrink-guard.md": "76388d6ffa05e0454781cc47a685bcf9b9e9d6c9837d8575857f3519d0ed452c" + }, + "head": "238c32e5534770f961ab48e46c81674d88bec474", + "outcome": "no-change", + "reason": "Adds .out-of-scope/extract-shrink-guard.md, a triage record of a rejected enhancement (#25). It documents existing extract behaviour and changes no skill guidance.", + "evidence": [ + "Changed: .out-of-scope/extract-shrink-guard.md at 238c32e5534770f961ab48e46c81674d88bec474" + ] } } } diff --git a/.out-of-scope/extract-shrink-guard.md b/.out-of-scope/extract-shrink-guard.md new file mode 100644 index 0000000..05028b0 --- /dev/null +++ b/.out-of-scope/extract-shrink-guard.md @@ -0,0 +1,37 @@ +# Extract shrink guard + +`mdcode extract` does not refuse, or ask for an extra flag, when a write would make an existing file +smaller. + +## Why this is out of scope + +The idea came from #21. There, a plain `extract` on a README whose blocks were excerpts +(`file=… region=…`) replaced 27 real source files with just those excerpts, and a "refuse writes that +shrink a file" check would have caught every one. That data loss is now prevented by what `extract` +writes, not by a size check: + +- A block with `region=` is spliced into the existing file. Code outside the region, and regions the + Markdown doesn't mention, are kept. +- Ambiguous mappings, such as several blocks for one file without distinct `region=` values, broken + markers or unsafe paths, are refused before anything is written. +- Without `--force`, an existing file whose block has no `region=` is never overwritten; it is + skipped and `extract` exits 2. + +That leaves one way to shrink a file: `extract --force` on a whole-file block, where the block is the +entire file. `--force` already is the explicit opt-in to replace an existing file with the block's +contents. A shrink guard there would only mean a second flag (`--force --allow-shrink`) for the same +intent, and a block that legitimately removes code is exactly the case `--force` is for. + +To see what `--force` would change before running it, use the check, which writes nothing: + +```bash +mdcode extract --check --force README.md +# ✗ Out of sync: line 3: src/whole.ts differs from this block; extract would overwrite it +``` + +Splices that make a region shorter are ordinary code edits, so any threshold there (bytes, lines or a +ratio) would refuse normal changes or let real loss through. + +## Prior requests + +- #25: "extract: refuse writes that would shrink an existing file unless --force", split out of #21