can1357
78428b58b4
- Enhanced chunk-edit documentation with guidance on selecting narrowest regions to prevent accidental attribute/decorator loss.
7.5 KiB
7.5 KiB
Edits files via syntax-aware chunks. Run read(path="file.ts") first. The edit selector is a chunk path, optionally qualified with a region.
For leaf chunks (fields, variants, single-line items), @body falls back to the full chunk.
Important: append/prepend without a @region inserts outside the chunk. To add children inside a class, struct, enum, or function body, use @body:
class_Foo@body+append→ adds inside the class before}class_Foo@body+prepend→ adds inside the class after{class_Foo+append→ adds after the entire class (after})
Replace a whole chunk (rename a function):
{ "sel": "fn_createCounter#PQQY", "op": "replace", "content": "function makeCounter(start: number): Counter {\n\tconst c = new Counter();\n\tc.value = start;\n\treturn c;\n}\n" }
Result — the entire chunk is rewritten:
function makeCounter(start: number): Counter {
const c = new Counter();
c.value = start;
return c;
}
Tip: Prefer the narrowest edit that covers your change. If only the body is changing, use
@bodyinstead of replacing the whole chunk — this avoids accidentally dropping or duplicating surrounding attributes, decorators, and doc comments.
Replace a method body (@body):
{ "sel": "class_Counter.fn_increment#NQWY@body", "op": "replace", "content": "this.value += 1;\nconsole.log('incremented to', this.value);\n" }
Result — only the body changes, signature and braces are kept:
increment(): void {
this.value += 1;
console.log('incremented to', this.value);
}
Replace a function header (@head — signature and doc comment):
{ "sel": "fn_createCounter#PQQY@head", "op": "replace", "content": "/** Creates a counter with the given start value. */\nfunction createCounter(initial: number, label?: string): Counter {\n" }
Result — adds a doc comment and updates the signature, body untouched:
/** Creates a counter with the given start value. */
function createCounter(initial: number, label?: string): Counter {
const counter = new Counter();
counter.value = initial;
return counter;
}
Insert before a chunk (before):
{ "sel": "fn_createCounter", "op": "before", "content": "/** Factory function below. */\n" }
Result — a comment is inserted before the function:
/** Factory function below. */
function createCounter(initial: number): Counter {
Insert after a chunk (after):
{ "sel": "enum_Status", "op": "after", "content": "\nfunction isActive(s: Status): boolean {\n\treturn s === Status.Active;\n}\n" }
Result — a new function appears after the enum:
enum Status {
Active = "ACTIVE",
Paused = "PAUSED",
Stopped = "STOPPED",
}
function isActive(s: Status): boolean {
return s === Status.Active;
}
function createCounter(initial: number): Counter {
Prepend inside a container (@body + prepend):
{ "sel": "class_Counter@body", "op": "prepend", "content": "label: string = 'default';\n\n" }
Result — a new field is added at the top of the class body, before existing members:
class Counter {
label: string = 'default';
value: number = 0;
Append inside a container (@body + append):
{ "sel": "class_Counter@body", "op": "append", "content": "\nreset(): void {\n\tthis.value = 0;\n}\n" }
Result — a new method is added at the end of the class body, before the closing }:
toString(): string {
return `Counter(${this.value})`;
}
reset(): void {
this.value = 0;
}
}
Delete a chunk (replace with empty content):
{ "sel": "class_Counter.fn_toString#ZQZP", "op": "replace", "content": "" }
Result — the method is removed from the class.
- Indentation rules (important):
- Use
\tfor each indent level. The tool converts tabs to the file's actual style (2-space, 4-space, etc.). - Do NOT include the chunk's base indentation — only indent relative to the region's opening level.
- For
@bodyof a function: write at column 0, e.g."return x;\n". The tool adds the correct base indent. - For
@head: write at the chunk's own depth. A class member's head uses"/** doc */\nstart(): void {". - For a top-level item: start at zero indent. Write
"function foo() {\n\treturn 1;\n}\n". - The tool strips common leading indentation from your content as a safety net, so accidental over-indentation is corrected.
- Use