Skip to content

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.

The server gives the agent this description of the tool.

Preview a structural rewrite, ask for confirmation, then apply it to project files.

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.

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

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\")"}]

A query without a rewrite template fails with "Provide a rewrite template." The other errors are those of query.