Pi Lens Write Ast Grep Rule

Writing a pi-lens ast-grep Rule

Drop path: rules/ast-grep-rules/rules/<id>.yml
Same id as a built-in overrides it. Multiple rules per file: separate with ---.

Minimal template

id: no-foo-bar
language: TypeScript        # PascalCase — see languages below
severity: warning           # error | warning | hint | info — pick by evidence, see below
message: "Avoid foo.bar() — use baz() instead"
note: |
  Longer explanation / fix guidance here.
rule:
  pattern: foo.bar($ARG)

Pick the severity by the evidence behind the rule, not by feel:

• error — only with a documented zero-false-positive audit in the note. Only error maps to semantic blocking and stops a turn.
• warning — a real finding with a known, bounded false-positive rate.
• hint / info — style opinions. They render as advisory text, never block, and lose the report budget to warnings when a report is capped.

Full policy and the error-promotion procedure: AGENTS.md's "Severity policy (#1777)" section. Read it before shipping anything above warning.

Before promoting to error

Three things must all be true, and the rule's note must record them:

1. A multi-corpus false-positive census, not a single-tree count. Run the rule over pi-lens's clients//tests/ plus at least one real external codebase of the kind the rule targets, classify every hit, and put the table in the note.
2. Structural narrowing before exemption. Suppress a legitimate idiom with a relational constraint (inside/has/follows, scoped path globs), not with prose telling readers to ignore the hit. Narrow first — don't reach for a lower tier as the easy way out. no-non-null-assertion was demoted to hint (0124608a), then reverted back to warning once the same false positives were closed with a structural exclusion instead (b3e1fd79).
3. Self-scan wiring. Tag the rule metadata.category: pi-lens-self-scan so npm run astgrep:self-scan holds this tree at zero in CI. An error rule that never runs against pi-lens's own source is an unaudited claim.

If the post-narrowing residual is still tens of legitimate hits, stop and report the numbers instead of shipping at error.

Language values

TypeScript JavaScript Python Go Rust Java C Cpp CSharp Kotlin Ruby Php

Rule conditions

rule:
  pattern: foo($X)          # ast-grep pattern — $X single, $$$ARGS multi
  kind: call_expression     # AST node kind (alternative to pattern)
  regex: "secret|token"     # regex on node text
  has:                      # descendant must match
    pattern: await $$$
  not:
    kind: comment
  any:
    - pattern: foo($X)
    - pattern: bar($X)
  all:
    - pattern: $OBJ.send($$$)
    - not: { kind: await_expression }

Relational & constraint conditions — all supported (native napi, #206)

The runner matches every rule through napi's native engine (root.findAll({rule, constraints})), fed by a faithful js-yaml parse. The full ast-grep grammar works — nest freely; nothing is silently skipped:

rule:
  kind: call_expression
  inside:                     # ancestor must match
    kind: function_declaration
    stopBy: end               # ↑ search ALL ancestors (default is direct parent)
  has:                        # descendant must match (default: DIRECT child)
    field: arguments          # field constraints work
  follows:                    # immediately-preceding sibling
    pattern: const $X = $V
constraints:                  # metavariable regex constraints work
  X:
    regex: "Error$"

⚠ has/inside default to the immediate child/parent (stopBy: neighbor). For a recursive descendant/ancestor search add stopBy: end. This is the #1 migration gotcha — see the has note in reference.md.

⚠ stopBy: end alone is not a boundary. It's a search-depth control — how far the walk searches — not a stop condition; the any: kind list only decides what CAN satisfy the match, not where the walk halts. To scope a relation to the nearest enclosing function (or any other boundary), give stopBy its own rule. See "Scoping to the nearest enclosing X" in reference.md (#1794 F1 — this bug shipped twice in one window).

YAML quoting — REQUIRED (js-yaml will reject the rule otherwise)

The parser is a real YAML parser, so unquoted special chars throw and the rule is silently dropped:

❌ message: !!value to coerce boolean    # `!!` is a YAML tag → js-yaml THROWS, rule dropped
✅ message: "!!value to coerce boolean"
❌ message: foo: bar baz                  # bare `:` → parsed as a nested mapping
✅ message: "foo: bar baz"
   Quote any scalar starting with  ! & * ? | > % @ `  or containing  : #
   Quote keyword-like kinds:  kind: "true"   (bare `true` becomes a boolean → invalid kind)

Gotchas

❌ Overly broad patterns — filtered out automatically
   $VAR  $NAME  $_  $X  $EXPR  (single bare metavar)

❌ PascalCase language is required
   language: typescript  →  language: TypeScript

❌ $VAR inside strings — matches literal "$VAR", not a metavar
   "from $PATH"  →  use tree-sitter or grep instead

✅ Test in playground: https://ast-grep.github.io/playground.html
✅ Schema + autocomplete: rules/ast-grep-rules/rule-schema.json
✅ Docs: docs/custom-rules.md