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.