Skip to content

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.

The server gives the agent this description of the tool.

Create a project, rule, empty case template or shared utility without prompts.

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.
Field Type Required Default Description
createdFiles list of string yes
modifiedFiles list of string no

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"}

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.