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.
$ 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 --yesCreated 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.ymlThe 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.
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.' --yesArguments
Section titled “Arguments”<NAME>
Section titled “<NAME>”<NAME>
The rule's name, or <pack>/<name>.
Options
Section titled “Options”--pack
Section titled “--pack”--pack <MODULE>
The pack the rule belongs to. A pack that xpd.yml lacks is added to it.
--every-file
Section titled “--every-file”--every-file
Run a pack this command adds on every Python file.
--language
Section titled “--language”-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.
--pattern
Section titled “--pattern”-p, --pattern <PATTERN>
The code to find, with $X for any one node and $$$X for any number of them.
--message
Section titled “--message”-m, --message <MESSAGE>
What the issue says. It may name the pattern's variables, as $X.
--severity
Section titled “--severity”--severity <SEVERITY>
Default: warning.
Values: error, warning, info, hint.
--note
Section titled “--note”--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
Section titled “--fix-safety”--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
Section titled “--since”--since <VERSION>
The first version of the pack's library the rule applies to.
--until
Section titled “--until”--until <VERSION>
The first version of the pack's library the rule no longer applies to.
--holds
Section titled “--holds”--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
Section titled “--unless-holds”--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
Section titled “--unless-imported”--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
Section titled “--public-id”--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
Section titled “--with-test”--with-test
Also create an empty test case for the rule.
--directory
Section titled “--directory”--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
Section titled “--format”--format <FORMAT>
Print the result as text, or as JSON with createdFiles and modifiedFiles.
Default: text.
Values: text, json.