Skip to content

docs(#108,#109): pin replace-body body rules and quote the import spec example - #124

Merged
bigknoxy merged 1 commit into
mainfrom
fix/108-109-quickref-docs
Aug 19, 2026
Merged

docs(#108,#109): pin replace-body body rules and quote the import spec example#124
bigknoxy merged 1 commit into
mainfrom
fix/108-109-quickref-docs

Conversation

@bigknoxy

Copy link
Copy Markdown
Owner

Problem

Two invocation rules were discoverable only by experiment, and both fail in ways an agent cannot see:

#108replace-body owns the braces and the indentation of the body it writes. Passing them back is accepted, and the result still parses:

argument result
return a * 2; return a * 2;
{ return a * 2; } { return a * 2; } — a nested block, the old body gone but replaced by a block
return a * 2; return a * 2; — double-indented

The quickref described the argument as "New body (or @file)".

#109 — the quickref's add-import example was '{ Foo } from ./bar'. The spec is parsed as source, so the unquoted path is a PARSE_ERROR when copied.

Fix

  • --help text for <new-body> / --new-body now says "statements only — no braces, no indentation"; <import-spec> / --import-spec now shows the quoted form. Quickref regenerated.
  • Two new gotcha sections in docs/CLI-QUICKREF.md, each with a ✅/❌ pair and the multi-line re-indentation behaviour spelled out.
  • README command table rows for both commands.

Verification

  • tests/quickref-body-import-contract.test.ts — 8 tests. Four pin the actual replace-body bytes (bare, braced, pre-indented, multi-line), two pin quoted-vs-unquoted add-import (PARSE_ERROR, file untouched), two assert the quickref itself states the rules and that from ./bar appears only on a ❌ line.
  • Falsified against main: the two doc-assertion tests fail (the behaviour tests pass, as expected — this is a documentation defect, not a behaviour one).
  • Full suite 853 pass / 0 fail. bun run lint:docs clean.

Closes #108
Closes #109

🤖 Generated with Claude Code

…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
bigknoxy force-pushed the fix/108-109-quickref-docs branch from 13ca4a4 to ceec165 Compare August 19, 2026 19:14
@bigknoxy
bigknoxy merged commit c970f9e into main Aug 19, 2026
4 checks passed
@bigknoxy
bigknoxy deleted the fix/108-109-quickref-docs branch August 19, 2026 19:15
@bigknoxy

Copy link
Copy Markdown
Owner Author

🎉 This PR is included in version 4.4.15 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[P3] CLI-QUICKREF add-import example is unquoted and produces PARSE_ERROR [P3] replace-body indentation contract is undocumented

1 participant