new tool
Use new to create a rule project, a rule, an empty test case or a utility without
prompts, as xpd new does with --yes. item.entity says what to create, and
the other fields of item are the answers that xpd new would otherwise ask for.
new(item)- May change files
- May overwrite what is there
- A second call with the same arguments changes nothing more
- Stays inside the project
Tags: authoring, rules.
Description
Section titled “Description”The server gives the agent this description of the tool.
Create a project, rule, empty case template or shared utility without prompts.
Arguments
Section titled “Arguments”Type: object. Required.
What to create, and the answers that xpd new would otherwise ask for.
The 19 fields of `item`
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
item.entity |
"project", "rule", "test", "util" |
yes | What to create. | |
item.name |
string or null | no | null |
The rule's name or <pack>/<name>, the test's rule id, or the utility's name. |
item.directory |
string | no | "." |
The project folder, which holds sgconfig.yml, relative to the project root. |
item.language |
string or null | no | null |
The language of a structural rule or a utility. |
item.pack |
string or null | no | null |
The pack the rule belongs to, or the pack a new project declares. |
item.pattern |
string or null | no | null |
The code to find, with $X for any one node and $$$X for any number of them. |
item.message |
string or null | no | null |
What the issue says. It may name the pattern's variables. |
item.severity |
"error", "warning", "info", "hint" or null |
no | null |
Default: warning. |
item.note |
string or null | no | null |
A longer explanation, for the rule's note and its Markdown. |
item.rewrite |
string or null | no | null |
The code that replaces a match, with the pattern's variables. |
item.fix_safety |
"safe", "unsafe" or null |
no | null |
Whether the fix keeps the code's behavior. Required with rewrite. |
item.since |
string or null | no | null |
The first version of the pack's library the rule applies to. |
item.until |
string or null | no | null |
The first version of the pack's library the rule no longer applies to. |
item.holds |
list of string | no | Proofs as VAR={kind: call}. | |
item.unless_holds |
list of string | no | Drop a match when the variable holds a value of this shape, as VAR={kind: call}. | |
item.unless_imported |
string or null | no | null |
Silence the rule in a file that imports a module with a module-level statement of this shape. |
item.public_id |
string or null | no | null |
The id that issues show, for one of several rule variants. |
item.with_test |
boolean | no | false |
Also create an empty test case. |
item.every_file |
boolean | no | false |
Run a pack this call adds on every Python file, not only on files that import its module. |
Result
Section titled “Result”| Field | Type | Required | Default | Description |
|---|---|---|---|---|
createdFiles |
list of string | yes | ||
modifiedFiles |
list of string | no |
Example
Section titled “Example”The first call makes a project with the pack team in the server's root, here /tmp/project.
{"item":{"entity":"project","pack":"team"}}{"createdFiles":["/tmp/project/sgconfig.yml","/tmp/project/xpd.yml","..."],"modifiedFiles":[],"item":"project"}The second call adds a rule with its Markdown and an empty test case.
{"item":{"entity":"rule","name":"team/no-print","pattern":"print($X)","message":"Use the project logger.","with_test":true}}{"createdFiles":["/tmp/project/rules/team/no-print.yml","/tmp/project/rules/team/no-print.md","/tmp/project/rule-tests/team/no-print-test.yml"],"modifiedFiles":[],"item":"rule","id":"team/no-print"}Errors
Section titled “Errors”A missing value fails as it does with xpd new --yes, and so does a rule that exists already.
Nothing is written then. A directory outside the project root fails before xpd runs.