rewrite tool
Use rewrite to apply a structural replacement across files. It previews the
matches of query, asks the user to confirm, and only then writes the replacement with
xpd run --update-all. xpd does not check a rewrite or mark it safe the way it does a rule fix.
rewrite(query, paths=null)- May change files
- May overwrite what is there
- A second call may do more
- Stays inside the project
Tags: fix, structure.
Description
Section titled “Description”The server gives the agent this description of the tool.
Preview a structural rewrite, ask for confirmation, then apply it to project files.
Arguments
Section titled “Arguments”Type: object. Required.
The pattern or kind to find, and the rewrite template that replaces it.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
query.pattern |
string or null | no | null |
AST pattern with $VARIABLE captures. |
query.kind |
string or null | no | null |
Syntax kind instead of a pattern. |
query.language |
string or null | no | null |
The language of the pattern, such as python. Default: each file's extension. |
query.selector |
string or null | no | null |
The kind of the part of the pattern that is the match. |
query.rewrite |
string or null | no | null |
Replacement template to preview. |
Type: list of string or null. Optional, default null.
Files or folders inside the project root. Default: the whole root.
Result
Section titled “Result”The 17 fields of the result
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
result |
list of object | yes | ||
result[].text |
string | yes | ||
result[].file |
string | yes | ||
result[].language |
string | yes | ||
result[].range |
object | yes | ||
result[].range.byteOffset |
object | yes | ||
result[].range.byteOffset.start |
integer | yes | ||
result[].range.byteOffset.end |
integer | yes | ||
result[].range.start |
object | yes | ||
result[].range.start.line |
integer | yes | ||
result[].range.start.column |
integer | yes | ||
result[].range.end |
object | yes | ||
result[].range.end.line |
integer | yes | ||
result[].range.end.column |
integer | yes | ||
result[].replacement |
string or null | no | null |
|
result[].replacementOffsets |
object or null | no | null |
|
result[].metaVariables |
object | no |
Example
Section titled “Example”On samples/bad.py, the user declined the question, so the tool wrote nothing and
returned the preview. The match below is shown without its offsets.
{"query":{"pattern":"pd.merge($$$A)","rewrite":"df.merge(other, on=\"k\")","language":"python"},"paths":["samples/bad.py"]}[{"text":"pd.merge(df, other, on=\"k\")","file":"samples/bad.py","replacement":"df.merge(other, on=\"k\")","lines":"m = pd.merge(df, other, on=\"k\")"}]Errors
Section titled “Errors”A query without a rewrite template fails with "Provide a rewrite template." The other
errors are those of query.