Skip to content

xpd new rule

Create a rule from a pattern, with the Markdown that explains it beside the rule file Use xpd new rule to add a rule, with the Markdown that explains it beside the rule file. A rule in a pack is a Python rule named <pack>/<name>, and runs only on the files that import the pack's module. A rule outside a pack is a plain rule for the language that --language names.

A rule needs a --pattern and a --message, and --fix needs --fix-safety. Before it writes the rule file, new checks that both xpd check and ast-grep scan can read the rule. It never overwrites a rule file.

Terminal window
$ xpd new project --pack team --yes --format json | jq -c .item
"project"
$ xpd new rule team/no-print --pattern 'print($X)' --message 'Use the project logger.' --with-test --yes
Created rule team/no-print
created /tmp/project/rules/team/no-print.yml
created /tmp/project/rules/team/no-print.md
created /tmp/project/rule-tests/team/no-print-test.yml

The rule's Markdown goes to rules/team/no-print.md, the same place where xpd's own packs keep the text of their rule pages.

Terminal window
xpd new rule [OPTIONS] [NAME]

xpd new rule --help ends with these lines.

Examples:
xpd new rule team/no-iterrows --pattern '$DF.iterrows()' --message 'Loop over columns.' --yes
xpd new rule old-api --pack team --pattern 'lib.old($X)' --fix 'lib.new($X)' \
--fix-safety safe --until 2.0 --message 'old was removed in 2.0.' --yes
xpd new rule unwrap --language rust --pattern '$X.unwrap()' --message 'Handle the error.' --yes

<NAME>

The rule's name, or <pack>/<name>.

--pack <MODULE>

The pack the rule belongs to. A pack that xpd.yml lacks is added to it.

--every-file

Run a pack this command adds on every Python file.

-l, --language <LANGUAGE>

The language of a structural rule. A pack's rules are Python.

Also written --lang.

Values: bash, c, cpp, csharp, css, dart, elixir, go, haskell, hcl, html, java, javascript, json, kotlin, lua, markdown, nix, php, python, ruby, rust, scala, solidity, swift, tsx, typescript, yaml, zig.

-p, --pattern <PATTERN>

The code to find, with $X for any one node and $$$X for any number of them.

-m, --message <MESSAGE>

What the issue says. It may name the pattern's variables, as $X.

--severity <SEVERITY>

Default: warning.

Values: error, warning, info, hint.

--note <NOTE>

A longer explanation, for the rule's note and its Markdown.

--fix <FIX>

The code that replaces a match, with the pattern's variables.

--fix-safety <FIX_SAFETY>

Whether the fix keeps the code's behavior. xpd check --fix applies safe fixes, and --unsafe-fixes adds the unsafe ones. Required with --fix.

Values: safe, unsafe.

--since <VERSION>

The first version of the pack's library the rule applies to.

--until <VERSION>

The first version of the pack's library the rule no longer applies to.

--holds <VAR=RULE>

Keep a match only when the variable holds a value of the rule's shape, as VAR='{kind: call}'.

Give it more than once to pass several values.

--unless-holds <VAR=RULE>

Drop a match when the variable holds a value of the rule's shape.

Give it more than once to pass several values.

--unless-imported <RULE>

Silence the rule in a file that imports a module with a module-level statement of the rule's shape.

--public-id <ID>

The id that issues show, for one of several variants of a rule with their own ids, such as two rules for the releases before and after a version.

--with-test

Also create an empty test case for the rule.

--directory <DIR>

The project folder, which holds sgconfig.yml. Nothing is written outside it. Default: the nearest folder at or above the current one with sgconfig.yml, or the current folder for a new project.

-y, --yes

Never ask. Fail when a required flag is missing.

--format <FORMAT>

Print the result as text, or as JSON with createdFiles and modifiedFiles.

Default: text.

Values: text, json.