custom-rules.md

Custom Rules

pi-lens picks up project-local and user-level rules automatically alongside its built-ins. Drop YAML files in the right directory and they are active on the next file dispatch — no config required.

For the full list of bundled rules per language, see the generated catalogs: ast-grep_rules_catalog.md and tree-sitter_rules_catalog.md.

Quick start

your-project/
  rules/
    tree-sitter-queries/
      typescript/
        my-rule.yml        ← tree-sitter rule, loaded alongside built-ins
    ast-grep-rules/
      rules/
        my-rule.yml        ← ast-grep rule, overrides built-in with same id

Both rule families are fingerprinted by relative path and contents, so in-place edits, renames, additions, and removals are picked up without a restart, even when mtimes are preserved.

When an edit takes effect

A per-file dispatch reads the rule corpus fresh every time: its cache key is a content fingerprint of every rule file the language's rule set is built from, so an edit, addition, or removal is live on the next dispatched file.

Whole-project surfaces — a project scan and a structural search — reuse a corpus fingerprint computed once per turn, so a rule edit lands on the next turn, or immediately if any file is dispatched in between (a dispatch republishes the fresh fingerprint for the rest of that turn). This is what keeps a warm scan at the cost of a string comparison instead of re-reading every rule file on every call.

User-level rules

Rules shared across projects live under the relocatable machine-data directory: <PI_LENS_HOME>/rules/ (or the platform default pi-lens directory when PI_LENS_HOME is unset). Use the same tree-sitter-queries/ and ast-grep-rules/ layout shown above. Precedence is project > user > bundled; when rule IDs collide, the higher tier wins and the lower definition is shadowed from execution. User rules are part of the same fingerprints as project rules, so they follow the same timing above.

---

Tree-sitter queries

Drop path

<project-root>/rules/tree-sitter-queries/<language>/<rule-id>.yml

Valid <language> directory names: typescript javascript tsx python go rust java csharp kotlin ruby cpp c css php plsql abap cobol

Project rules and built-in rules are merged — both run on every matching file.

Disabling a built-in

Rename the language directory with a -disabled suffix to exclude all rules in it from dispatch (they still load for tests):

rules/tree-sitter-queries/typescript-disabled/

There is currently no per-rule disable mechanism; if you need to suppress one built-in rule, copy the directory, remove the file, and rename appropriately.

YAML schema

See rules/tree-sitter-queries/rule-schema.json for a machine-readable schema (works with the VS Code YAML extension).

Field	Required	Type	Notes
id	✅	string	Unique across all rules for this language
query	✅	string (block |)	Tree-sitter S-expression; capture names use @UPPER_SNAKE
name	—	string	Human-readable; defaults to id
severity	—	error | warning | info	Defaults to warning
category	—	string	Defaults to "general"
language	—	string	Inferred from directory name; override only if the file lives in a shared dir
message	—	string	Shown inline; defaults to "Pattern: <id>"
description	—	string (block |)	Extended explanation shown in the detail view
metavars	—	string[]	Capture names to surface as evidence; auto-extracted from @VAR patterns if omitted
predicates	—	Predicate[]	Native tree-sitter predicates (run in WASM, faster than post-filters)
inline_tier	—	blocking | warning | review	Override dispatch tier for this rule
defect_class	—	string	e.g. injection, xss, logic
confidence	—	low | medium | high
tags	—	string[]	e.g. [security, owasp-top-10]
cwe	—	string[]	e.g. [CWE-89]
owasp	—	string[]
has_fix	—	boolean	Defaults to false
fix_action	—	string	Short label for the fix suggestion
examples	—	{bad?, good?}	Code strings shown in docs

Predicate shape:

predicates:
  - type: eq          # or: match, any-of
    var: "@FUNC_NAME"
    value: "dangerousMethod"

Example

id: no-sync-fs-in-request
name: Synchronous fs call inside request handler
severity: warning
category: performance
language: typescript
message: "Synchronous fs call blocks the event loop — use the async variant"

query: |
  (call_expression
    function: (member_expression
      object: (identifier) @FS
      property: (property_identifier) @METHOD)
    (#eq? @FS "fs")
    (#match? @METHOD "^(readFileSync|writeFileSync|existsSync|statSync)$"))

metavars:
  - FS
  - METHOD

has_fix: false
tags:
  - performance
  - nodejs
examples:
  bad: |
    const data = fs.readFileSync(path, "utf-8");
  good: |
    const data = await fs.promises.readFile(path, "utf-8");

---

Ast-grep rules

Drop path

<project-root>/rules/ast-grep-rules/rules/<language-or-group>/<rule-id>.yml

Rule discovery is recursive and accepts .yml or .yaml. The shared raw-LSP/NAPI precedence is project primary rules, project secondary CodeRabbit rules, bundled native rules, then bundled CodeRabbit rules. A higher-precedence rule shadows a lower-precedence rule with the same id; duplicate IDs within one source layer are blocking configuration errors rather than silently selecting one definition.

YAML schema

See rules/ast-grep-rules/rule-schema.json for a machine-readable schema.

Field	Required	Type	Notes
id	✅	string
rule	✅	RuleCondition	At least one of pattern, kind, regex, has, any, all, not
language	—	string	See valid values below
severity	—	error | warning | info
message	—	string
note	—	string (block |)	Extended guidance shown in the detail view
fix	—	string	Suggested replacement
metadata.weight	—	number	Priority weight
metadata.category	—	string
constraints	—	Record<string, {regex}>	Metavariable regex — KEY: { regex: "..." } narrows what $KEY will match. Supported by the napi engine + the ast-grep CLI/LSP.

Valid language values: TypeScript JavaScript Python Go Rust Java C Cpp CSharp Kotlin Ruby Php (Note: PascalCase, unlike tree-sitter directory names which are lowercase.)

RuleCondition fields:

Field	Notes
pattern	Ast-grep pattern syntax. Accepts BOTH a string shorthand (foo($A)) AND the rich object form ({context, selector}) — the rich form matches a specific AST kind inside a syntactic context snippet. Avoid single-metavariable string patterns like $VAR (too broad).
kind	AST node kind name
regex	Regex match against node text
has	Nested condition — node must have a descendant matching (default = direct child)
any	Array — node matches if any item matches (OR)
all	Array — node matches only if all items match (AND)
not	Negation condition
inside	Ancestor must match (default = direct parent; pair with stopBy: end to walk all ancestors)
follows	Immediately-preceding sibling must match
precedes	Immediately-following sibling must match
stopBy	neighbor (default — direct parent/child/sibling) or end (walk to root/leaves)
field	Field name constraint (e.g. field: name on an import specifier)
nthChild	Match only the Nth child of its parent

All of these are supported by the in-process napi runner (#206) and the ast-grep CLI / LSP — the runner delegates matching to napi's native engine (root.findAll({rule})), the same Rust core the CLI and LSP use.

Example

id: no-process-exit-in-library
language: TypeScript
severity: warning
message: "process.exit() in library code terminates the host process"
note: |
  Library code should throw an error or return a result code instead of
  calling process.exit(). The caller decides whether to exit.

  BAD:  process.exit(1)
  GOOD: throw new Error("fatal condition")
rule:
  pattern: process.exit($CODE)

---

Multiple rules per file

Ast-grep rule files support multiple YAML documents separated by ---:

id: rule-one
language: TypeScript
severity: warning
message: "First rule"
rule:
  pattern: somePattern($A)
---
id: rule-two
language: TypeScript
severity: error
message: "Second rule"
rule:
  pattern: otherPattern($B)

Tree-sitter query files are one rule per file.

---

Validation

Run the built-in type-check against your rules to surface YAML parse errors before committing:

# type-check only (no emit) — errors in rule files show up via the loader path
npx tsc --noEmit

For richer editor feedback (autocomplete, hover docs), point the VS Code YAML extension at the bundled schemas:

// .vscode/settings.json
{
  "yaml.schemas": {
    "./rules/tree-sitter-queries/rule-schema.json": "rules/tree-sitter-queries/**/*.yml",
    "./rules/ast-grep-rules/rule-schema.json": "rules/ast-grep-rules/rules/*.yml"
  }
}