docs(#108,#109): pin replace-body body rules and quote the import spec example - #124
Merged
Conversation
…c example replace-body owns the braces and the indentation of the body it writes, so a braced or pre-indented argument silently nests a block or double-indents while the file still parses. The quickref described the argument only as "New body". The add-import example showed an unquoted module path, which yields PARSE_ERROR when copied; the spec is parsed as source. Both rules are now in --help, README, and the quickref gotchas, with a correct/incorrect pair each, and pinned by tests/quickref-body-import-contract.test.ts so the docs cannot drift from behaviour. Closes #108 Closes #109 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
bigknoxy
force-pushed
the
fix/108-109-quickref-docs
branch
from
August 19, 2026 19:14
13ca4a4 to
ceec165
Compare
Owner
Author
|
🎉 This PR is included in version 4.4.15 🎉 The release is available on GitHub release Your semantic-release bot 📦🚀 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
Two invocation rules were discoverable only by experiment, and both fail in ways an agent cannot see:
#108 —
replace-bodyowns the braces and the indentation of the body it writes. Passing them back is accepted, and the result still parses:return a * 2;return a * 2;{ return a * 2; }{ return a * 2; }— a nested block, the old body gone but replaced by a blockreturn a * 2;return a * 2;— double-indentedThe quickref described the argument as "New body (or @file)".
#109 — the quickref's
add-importexample was'{ Foo } from ./bar'. The spec is parsed as source, so the unquoted path is aPARSE_ERRORwhen copied.Fix
--helptext for<new-body>/--new-bodynow says "statements only — no braces, no indentation";<import-spec>/--import-specnow shows the quoted form. Quickref regenerated.docs/CLI-QUICKREF.md, each with a ✅/❌ pair and the multi-line re-indentation behaviour spelled out.Verification
tests/quickref-body-import-contract.test.ts— 8 tests. Four pin the actualreplace-bodybytes (bare, braced, pre-indented, multi-line), two pin quoted-vs-unquotedadd-import(PARSE_ERROR, file untouched), two assert the quickref itself states the rules and thatfrom ./barappears only on a ❌ line.main: the two doc-assertion tests fail (the behaviour tests pass, as expected — this is a documentation defect, not a behaviour one).bun run lint:docsclean.Closes #108
Closes #109
🤖 Generated with Claude Code