@herbertgao/pi-extensions 2026.8.6 → 2026.8.7

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-await-expression-member-js.yml

@@ -1,9 +1,20 @@
 id: no-await-expression-member-js
 language: JavaScript
 severity: hint
-message: "Unnecessary parentheses around await — write await expr.prop directly"
+message: "(await expr).prop — do not rewrite to await expr.prop (that reads .prop off the unresolved promise). Keep the parens, or destructure first: const x = await expr; x.prop"
 note: |
-  (await expr).prop can be written as await expr.prop — the parens are redundant.
+  `(await expr).prop` awaits `expr` first, THEN reads `.prop` off the
+  resolved value. `await expr.prop` is NOT equivalent: `.` binds
+  tighter than `await`, so it reads `.prop` off the still-pending
+  Promise first (almost always `undefined`, since Promise objects
+  don't have arbitrary properties) and only then awaits that.
+  The rule previously told the caller to make this exact swap — bad
+  advice that fabricates a bug at every fix site (#1806 audit). The
+  correct move is either to keep the parenthesized form as-is (it's
+  already correct, just not "unnecessary") or to destructure into a
+  named variable first: `const resolved = await expr; resolved.prop`.
+  There's no autofix here on purpose — which form reads better is a
+  judgment call, not a mechanical rewrite.
   Exception: (await import(...)).prop is the standard dynamic import pattern.
 rule:
   pattern: "(await $EXPR).$PROP"

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-await-expression-member.yml

@@ -1,9 +1,20 @@
 id: no-await-expression-member
 language: TypeScript
 severity: hint
-message: "Unnecessary parentheses around await — write await expr.prop directly"
+message: "(await expr).prop — do not rewrite to await expr.prop (that reads .prop off the unresolved promise). Keep the parens, or destructure first: const x = await expr; x.prop"
 note: |
-  (await expr).prop can be written as await expr.prop — the parens are redundant.
+  `(await expr).prop` awaits `expr` first, THEN reads `.prop` off the
+  resolved value. `await expr.prop` is NOT equivalent: `.` binds
+  tighter than `await`, so it reads `.prop` off the still-pending
+  Promise first (almost always `undefined`, since Promise objects
+  don't have arbitrary properties) and only then awaits that.
+  The rule previously told the caller to make this exact swap — bad
+  advice that fabricates a bug at every fix site (#1806 audit). The
+  correct move is either to keep the parenthesized form as-is (it's
+  already correct, just not "unnecessary") or to destructure into a
+  named variable first: `const resolved = await expr; resolved.prop`.
+  There's no autofix here on purpose — which form reads better is a
+  judgment call, not a mechanical rewrite.
   Exception: (await import(...)).prop is the standard dynamic import pattern.
 rule:
   pattern: "(await $EXPR).$PROP"

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-bare-host-path-in-win32-branch.yml

@@ -1,6 +1,8 @@
 id: no-bare-host-path-in-win32-branch
 language: TypeScript
 severity: warning
+metadata:
+  category: pi-lens-self-scan
 message: "Use win32 path operations inside a branch committed to Windows path semantics"
 note: |
   A branch guarded by isWindowsPath/isFullyQualifiedWin32 has committed to

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-bare-object-param.yml

@@ -0,0 +1,60 @@
+id: no-bare-object-param
+language: TypeScript
+severity: error
+metadata:
+  category: pi-lens-self-scan
+message: "Parameter typed bare 'object' — guarantees nothing about shape, use Record<string, unknown> or a real interface"
+note: |
+  `object` only tells the compiler "not a primitive" — it doesn't
+  guarantee any property exists, so every consumer still has to cast
+  or reach for `as` before doing anything useful. Use
+  `Record<string, unknown>` for an open bag of properties, or a real
+  interface/type when the shape is known.
+
+  Scope: direct annotations only — a parameter (required or optional)
+  whose type annotation is exactly the bare `object` keyword, matched
+  structurally at the `predefined_type` leaf so it fires the same way
+  whether the parameter sits in a function declaration, an arrow
+  function, a class method, an interface method signature, or a
+  function-type alias (all four share the same
+  `required_parameter`/`optional_parameter` -> `type_annotation` ->
+  `predefined_type` shape in tree-sitter-typescript). Anti-slop's
+  transitive-alias-resolution half (flag a parameter typed with an
+  alias that itself resolves to bare `object`) is intentionally
+  dropped — that needs same-file symbol lookup ast-grep doesn't do.
+  A union member (`object | null`) or an array element (`object[]`)
+  is NOT flagged: the type_annotation's only content must be the bare
+  keyword, so wrapping it in anything else takes it out of scope
+  rather than risk a wider, noisier match than the direct case calls
+  for. Capitalized `Object` is a different node kind (`type_identifier`,
+  not `predefined_type`) and was never in scope.
+
+  No JS variant: JavaScript has no type annotations, so this pattern
+  has nothing to match there (same call as no-unknown-laundering.yml).
+
+  FP-scan (napi engine, every .ts/.tsx file under clients/ and tests/,
+  998 files): exactly one hit, `clients/host-ports.ts:8` —
+  `export type HostLogSink = (entry: object) => void;`. That's a
+  function-type alias, confirming the rule does cover function-type
+  parameters, not just declarations/methods. Fixed in the same PR by
+  narrowing to `Record<string, unknown>`: `HostLogSink` feeds
+  `NdjsonLogger.log(obj: unknown)` through the host's log sink, and
+  every real log record is a structured key/value bag, not an opaque
+  non-primitive — `Record<string, unknown>` says that honestly without
+  over-committing to a fixed shape. Zero hits remained after the fix,
+  so severity stays at `warning` rather than `hint`.
+
+  2026-08-19 (refs #1718): promoted `warning` -> `error` as part of the
+  anti-slop pattern adoption. Re-ran the FP scan on the current tree
+  (clients/ + tests/, same napi engine): still 0 hits. A zero-violation
+  rule costs nothing to run at `error`, and it stays free only if
+  promoted before someone writes the first one.
+rule:
+  kind: predefined_type
+  regex: "^object$"
+  inside:
+    kind: type_annotation
+    inside:
+      any:
+        - kind: required_parameter
+        - kind: optional_parameter

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-chained-type-assertions.yml

@@ -1,21 +1,66 @@
 id: no-chained-type-assertions
 language: TypeScript
-severity: warning
+severity: error
+metadata:
+  category: pi-lens-self-scan
 message: "Chained type assertion (x as A as B) — stacking assertions with no runtime check between them"
 note: |
   `x as A as B` stacks two assertions with no runtime check between
   them, so the compiler can't verify either hop. Narrow with a type
   guard, or assert once to the type you actually need. `as const`
   chains are allowed — they don't launder the value's type, they just
-  freeze a literal. `as unknown as B` chains are also allowed: routing
-  a cast through `unknown` (rather than through an unrelated concrete
-  type) is the standard, TypeScript-endorsed way to perform a cast that
-  the compiler can't otherwise verify as safe — see no-as-any.yml's own
-  note, which recommends this exact form as the safe replacement for
-  `as any`. An FP-scan of the pi-lens codebase found 22 chained-assertion
-  hits and all 22 were `as unknown as`; none were a genuine two
-  concrete-type stack.
+  freeze a literal.
+
+  2026-08-19 (refs #1718): promoted `warning` -> `error` and DROPPED the
+  `as unknown as $B` exemption as part of adopting anti-slop's
+  `no-chained-type-assertions` at its upstream strictness for the
+  shipped catalog. anti-slop's own rule (dmmulroy/anti-slop,
+  src/rules/no-chained-type-assertions.ts) treats `as unknown as` as a
+  forbidden chain too — routing a cast through `unknown` still discards
+  the original type's evidence, it just discards it in two hops instead
+  of one. The earlier note here argued `as unknown as` was the
+  TypeScript-endorsed safe-cast idiom (no-as-any.yml's own
+  recommendation) and cited a 22-hit FP scan where every chained-assertion
+  hit in pi-lens's own tree was that form — that FP-load argument is
+  still true, but it is an argument for pi-lens's OWN code, and this
+  catalog ships to other repositories. Users get the stricter upstream
+  form; pi-lens's own ~22 `as unknown as` chains stay non-conforming
+  until #1718 designs a self-scan baseline (or a follow-up narrows this
+  rule back down) — the same trade the audit made for every hint-tier
+  row in this PR: adopt the useful pattern for the product without
+  forcing pi-lens's own history to retroactively conform in the same PR.
+
+  2026-08-20 (review round, refs #1718): `error` severity is semantic-
+  blocking (ast-grep-napi.ts:699) with no independent escape valve — a
+  caller who follows the sibling `require-safety-comment-for-as-unknown-as.yml`
+  hint and adds a `SAFETY:` comment still hit a hard block, because the
+  two rules were wired independently. Fixed by giving THIS rule its own
+  `SAFETY:` exemption for the `as unknown as` arm specifically (the same
+  relational check — `follows`/`inside` a preceding comment matching
+  `SAFETY\s*:` — as the sibling hint rule, so a commented site satisfies
+  both at once). A genuine two-concrete-type chain (`x as A as B`, no
+  `unknown` hop) gets NO escape valve: that shape has no legitimate
+  reading upstream or here, so it stays hard-blocked. The two rules are
+  now a coherent pair: an uncommented `as unknown as` chain is a hard
+  error; a `SAFETY:`-commented one is clean; the hint rule keeps
+  teaching the convention on every OTHER assertion form.
+
+  2026-08-20 (refs #1727, #1777): the `as unknown as` arm is REMOVED from
+  this rule and delegated wholly to
+  `require-safety-comment-for-as-unknown-as.yml`, which was promoted to
+  `error` in the same change. The two rules previously matched the exact
+  same site list — verified identical on four corpora (16/16 pi-lens
+  `clients/`, 182/182 pi core, 194/194 opencode, and 1803 of this rule's
+  1849 oh-my-pi hits) — so every uncommented `x as unknown as T` raised
+  TWO diagnostics for one defect, one of them semantic-blocking. They now
+  partition the space: that rule owns the `unknown` hop and carries the
+  `SAFETY:` escape valve; this rule owns the concrete `x as A as B`
+  chain, which keeps NO escape valve because it has no legitimate
+  reading. Residual census for the concrete arm alone (2026-08-20):
+  pi-lens 0, pi core 0, opencode 0, oh-my-pi 46. Tagged
+  `metadata.category: pi-lens-self-scan` so CI holds pi-lens's own tree
+  at that zero.
 rule:
-  pattern: $X as $A as $B
-  not:
-    pattern: "$X as unknown as $B"
+  all:
+    - pattern: $X as $A as $B
+    - not: { pattern: $X as unknown as $B }

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-compile-call.yml

@@ -9,12 +9,70 @@ note: |
   `compile(source, ...)` with non-literal source compiles arbitrary code
   that may be executed later. If `source` is user-controlled, this is
   a code injection vulnerability.
-  Pattern: matches any compile(...) call. The fixture validates whether
-  the source is a static string vs dynamic — for the lint, we warn on
-  every compile() (safe static compiles are rare and easy to refactor
-  to a module-level constant).
+
+  Static/trusted source is suppressed (the rule's original ship still
+  described this design in prose but the shipped pattern matched every
+  compile() call unconditionally — #1806 audit: 3 FP hits, all in an
+  eval runner's `ast.parse` → `compile` pipeline). A source is trusted
+  when it is:
+    - a string literal (`compile('print(1)', ...)`);
+    - the direct result of an `ast.<method>(...)` call
+      (`compile(ast.parse(source), ...)`); or
+    - a variable of the SAME name assigned from `ast.<method>(...)`
+      SOMEWHERE in the nearest enclosing function
+      (`module = ast.parse(source); compile(module, ...)`).
+  The third case covers the common "parse once, compile the tree"
+  idiom (including intermediate `ast.Module`/`ast.Expression`
+  reconstructions built from an already-parsed tree) without full
+  dataflow analysis. It is honestly a same-scope, same-name,
+  ANY-ORDER heuristic, not real reaching-definitions: it does not
+  check that the `ast.<method>(...)` assignment happens BEFORE the
+  `compile()` call, so a later reassignment to untrusted input
+  (`module = ast.parse(source); module = user_input;
+  compile(module, ...)`) is a known, accepted miss (fixture pins it
+  under `valid:` with an explanatory comment — ast-grep's relational
+  rules can't express statement ordering, only ancestor/descendant/
+  sibling-existence). Anything else (a bare identifier with no such
+  assignment anywhere in scope, string concatenation, a call to
+  something other than `ast.*`) is still flagged.
+
+  2026-08-20 (review round, refs #1806): two follow-up fixes.
+  (1) The "same function" scope was `inside: {stopBy: end, kind:
+  function_definition}`, which climbs the WHOLE ancestor chain and
+  matches the first function_definition ANYWHERE above — including an
+  outer function, past a nested one. A nested function whose own
+  parameter happens to share a name with an outer function's
+  `ast.parse`-derived variable (shadowing, not the same binding) was
+  wrongly trusted. Bounded to the NEAREST enclosing function with
+  `stopBy: {kind: function_definition}` on the `inside` ascent itself
+  (same boundary-rule shape used to scope `no-return-value-in-generator`
+  in this PR's first round) — it stops climbing at the first
+  function_definition found instead of continuing past it.
+  (2) `pattern: compile($SRC, $$$REST)` has a literal comma in its
+  source text, so it never matched the single-argument form
+  `compile(user_input)` — a silent arity regression from the original
+  `compile($$$ARGS)` (any arity). Restored via an explicit `compile($SRC)`
+  alternative, mirroring the `$DB.query($SQL)` / `$DB.query($SQL, $$$REST)`
+  two-arity shape already used in `no-sql-in-code`.
 rule:
-  pattern: compile($$$ARGS)
+  any:
+    - pattern: compile($SRC)
+    - pattern: compile($SRC, $$$REST)
+constraints:
+  SRC:
+    not:
+      any:
+        - kind: string
+        - pattern: ast.$METHOD($$$A)
+        - all:
+            - kind: identifier
+            - inside:
+                stopBy:
+                  kind: function_definition
+                kind: function_definition
+                has:
+                  stopBy: end
+                  pattern: $SRC = ast.$METHOD($$$A)
 has_fix: false
 tags:
   - python

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-dupe-class-members.yml

@@ -9,12 +9,40 @@ rule:
         - inside:
             field: name
             matches: is-class-members
-            precedes:
-              stopBy: end
-              all:
-                - matches: is-class-members
-                - has:
-                    matches: accessor-name
+            any:
+              # 2026-08-20 (review round, refs #1806): staticness must be
+              # compared BETWEEN the pair, not blanket-exempted. A static
+              # member and a same-named instance member live in separate
+              # namespaces (`ClassName.foo` vs `instance.foo`) — no
+              # overwrite, correctly exempt. Two static members (or two
+              # instance members) with the same name DO collide — the
+              # original review-round fix over-corrected by excluding
+              # ANY static-enclosed accessor from pairing at all, which
+              # silently dropped the rule's core case
+              # (`static foo(){} static foo(){}`, the exact silent
+              # overwrite this rule exists to catch). These two arms
+              # require the anchor and its paired duplicate to agree on
+              # staticness: a static anchor only pairs with a later
+              # static member, a non-static anchor only pairs with a
+              # later non-static member.
+              - all:
+                  - matches: is-static-member
+                  - precedes:
+                      stopBy: end
+                      all:
+                        - matches: is-static-member
+                        - has:
+                            matches: accessor-name
+              - all:
+                  - not:
+                      matches: is-static-member
+                  - precedes:
+                      stopBy: end
+                      all:
+                        - not:
+                            matches: is-static-member
+                        - has:
+                            matches: accessor-name
     - matches: member-name
       all:
         - not:
@@ -33,13 +61,21 @@ rule:
 utils:
   duplicate-field:
     matches: is-class-members
+    not:
+      # Anchored on the member's own text (which starts at its first
+      # modifier keyword), not on the single nearest-preceding-sibling
+      # token. `follows: pattern: $$ACCESS` only ever binds the LAST
+      # modifier before the name — for `static async foo() {}` that is
+      # "async", so a `not: regex: static` check nested under that
+      # follows clause never sees "static" and the escape valve never
+      # fires (#1806 audit: 3 FP hits, static factory + same-named
+      # instance method both flagged as duplicates).
+      regex: '^static\b'
     has:
       matches: member-name
       any:
         - follows:
             pattern: $$ACCESS
-            not:
-              regex: static
           not:
             regex: constructor
         - not:
@@ -51,6 +87,14 @@ utils:
     matches: member-name
     follows:
       pattern: $$ACCESS
+  is-static-member:
+    # Anchored on the member's own text (which starts at its first
+    # modifier keyword), not on the single nearest-preceding-sibling
+    # token — see the `duplicate-field` comment below for why
+    # `follows: pattern: $$ACCESS` can't be trusted to see "static"
+    # once another modifier (e.g. "async") sits closer to the name.
+    matches: is-class-members
+    regex: '^static\b'
   is-class-members:
     any:
       - kind: method_definition

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-inner-html-js.yml

@@ -6,8 +6,33 @@ note: |
   innerHTML and outerHTML can introduce XSS vulnerabilities when used with
   user-supplied data. Use textContent for plain text or a library like DOMPurify
   for sanitized HTML.
+
+  The assignment forms (`$EL.innerHTML = $VAL` / `$EL.outerHTML = $VAL`)
+  are NOT flagged when `$VAL` is a plain string literal or a template
+  literal with no `${...}` substitution — clearing a node
+  (`el.innerHTML = ''`) or setting static markup
+  (`el.innerHTML = "<hr>"`) can't carry injected content, since the
+  right-hand side is fixed at author time. Before this constraint every
+  literal assignment matched too, which is why 8/8 sampled hits in the
+  audit corpus were this exact "clear/reset" idiom (#1806). A dynamic
+  value (an identifier, a call, or a template literal with a
+  substitution) is still flagged — that's the actual injection surface.
+  `insertAdjacentHTML(...)` keeps its original unconditional match: its
+  argument shape (`position, html`) doesn't fit the same RHS-literal
+  check cleanly, and the issue that drove this fix was specifically the
+  assignment forms.
 rule:
   any:
-    - pattern: $EL.innerHTML = $$$
-    - pattern: $EL.outerHTML = $$$
+    - pattern: $EL.innerHTML = $VAL
+    - pattern: $EL.outerHTML = $VAL
     - pattern: $EL.insertAdjacentHTML($$$)
+constraints:
+  VAL:
+    not:
+      any:
+        - kind: string
+        - all:
+            - kind: template_string
+            - not:
+                has:
+                  kind: template_substitution

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-inner-html.yml

@@ -6,8 +6,33 @@ note: |
   innerHTML and outerHTML can introduce XSS vulnerabilities when used with
   user-supplied data. Use textContent for plain text or a library like DOMPurify
   for sanitized HTML.
+
+  The assignment forms (`$EL.innerHTML = $VAL` / `$EL.outerHTML = $VAL`)
+  are NOT flagged when `$VAL` is a plain string literal or a template
+  literal with no `${...}` substitution — clearing a node
+  (`el.innerHTML = ''`) or setting static markup
+  (`el.innerHTML = "<hr>"`) can't carry injected content, since the
+  right-hand side is fixed at author time. Before this constraint every
+  literal assignment matched too, which is why 8/8 sampled hits in the
+  audit corpus were this exact "clear/reset" idiom (#1806). A dynamic
+  value (an identifier, a call, or a template literal with a
+  substitution) is still flagged — that's the actual injection surface.
+  `insertAdjacentHTML(...)` keeps its original unconditional match: its
+  argument shape (`position, html`) doesn't fit the same RHS-literal
+  check cleanly, and the issue that drove this fix was specifically the
+  assignment forms.
 rule:
   any:
-    - pattern: $EL.innerHTML = $$$
-    - pattern: $EL.outerHTML = $$$
+    - pattern: $EL.innerHTML = $VAL
+    - pattern: $EL.outerHTML = $VAL
     - pattern: $EL.insertAdjacentHTML($$$)
+constraints:
+  VAL:
+    not:
+      any:
+        - kind: string
+        - all:
+            - kind: template_string
+            - not:
+                has:
+                  kind: template_substitution

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-known-value-widening.yml

@@ -0,0 +1,71 @@
+id: no-known-value-widening
+language: TypeScript
+severity: hint
+message: "const initialized from an object literal, widened by a Record<...> annotation — prefer inference or 'satisfies'"
+note: |
+  Narrowed port of dmmulroy/anti-slop's `no-known-value-widening`
+  (src/rules/no-known-value-widening.ts, MIT). Upstream is a full
+  data-flow rule: it resolves `const` variable references transitively,
+  walks return statements, assignments, property definitions, and type
+  assertions, and flags ANY syntactically-known value (object/array/
+  function/literal, or a stable `const` binding that resolves to one)
+  flowing into an explicitly broad target type (`unknown`, `object`, an
+  open `Record<...>`/mapped-type dictionary, or an anonymous object
+  type). None of that data-flow — resolving a variable back to its
+  declaration, walking a return path — is something ast-grep's
+  structural matcher does; building a fake version of it would be
+  exactly the "vacuous guard" failure mode this repo's own review
+  process screens for.
+
+  This port keeps ONE syntactically self-contained sub-case: a `const`
+  declared with an object-literal initializer AND a `Record<K, V>`
+  annotation, matched in the same statement (`const x: Record<K, V> =
+  { ... }`). That is exactly what the 2026-08-19 audit measured (87
+  hits repo-wide vs. only 30 `satisfies` uses) and is the shape upstream
+  cites as the primary example: the object literal's own key/value
+  types are already known at the declaration site, and `Record<K, V>`
+  throws that evidence away in favor of a uniform key type — `satisfies
+  Record<K, V>` (or no annotation at all, letting inference stand) keeps
+  the literal's precise keys and value types AND still gets the
+  dictionary-shape check.
+
+  Everything else upstream covers — return-type widening, assignment
+  widening, transitively-resolved `const` references, `as`/type-literal
+  targets — is out of scope for this port. Shipped at `hint`: this is a
+  readability/precision rule, not a defect-prevention one (this repo's
+  audit explicitly ranked it below the top 5 for that reason), and an
+  annotated `Record<K, V>` initializer is frequently deliberate (a
+  lookup table whose value type is genuinely uniform across keys).
+  Self-scan note: do NOT try to make pi-lens's own tree clean against
+  this rule; the adopting PR records the 2026-08-19 hit count instead.
+
+  2026-08-20 (refs #1727, #1777): CONSIDERED for promotion to `error`,
+  KEPT at `hint`. AGENTS.md's severity policy admits a rule to `error`
+  only with a documented zero-false-positive audit, and `error` is the
+  only tier that maps to semantic `blocking`, so promoting it stops an
+  agent mid-turn on any file carrying a hit. Four-corpus census, ast-grep
+  CLI 0.45:
+
+  | corpus | hits |
+  |---|---:|
+  | pi-lens `clients/` | 90 |
+  | pi-lens `tests/` | 55 |
+  | pi core `packages/` | 74 (64 outside test paths) |
+  | opencode `packages/` | 193 (173) |
+  | oh-my-pi `packages/` | 828 (687) |
+
+  Verdict: no structural narrowing found. Every one of the 90 `clients/`
+  hits is a module-level lookup table whose value type genuinely IS
+  uniform (`LANGUAGE_TO_GRAMMAR`, `DELIVERY_SURFACES`, `EMOJI`,
+  `TREE_SITTER_EXT_TO_LANG`) — the exact deliberate use this note already
+  names. `Record<K, V>` on a lookup table and `Record<K, V>` on a value
+  whose keys were known and thrown away are the SAME syntax; the
+  difference is intent, which no relational constraint can read. Splitting
+  by `export const` at module scope versus a local `const` was probed and
+  rejected: it would encode "module-level tables are fine" as a rule of
+  the language, which it is not. Promotion needs a `satisfies` migration
+  of pi-lens's own tables, not a rule change.
+rule:
+  pattern:
+    context: "const $NAME: Record<$K, $V> = { $$$PROPS };"
+    selector: variable_declarator