@herbertgao/pi-extensions 2026.8.4 → 2026.8.6

package/node_modules/pi-lens/docs/usage.md

@@ -18,17 +18,34 @@ pi-lens hooks into the pi agent lifecycle:
 
 ## On-write pipeline
 
-For each write/edit, pi-lens runs a language-aware pipeline:
-
-1. Format queue / immediate formatting when configured.
-2. Safe autofix from tools with deterministic fix support.
+For each write/edit, pi-lens runs a language-aware pipeline. Format and safe
+autofix (steps 1–2) run on different schedules depending on the tool:
+
+- **`write`** (new file, full overwrite, bash-authored write): autofix runs
+  immediately, in the same tool result, carrying the fixed file's full content
+  back to the agent when it fits under the per-file cap.
+- **`edit`**: autofix defers to `agent_end`, joining the same per-file queue as
+  deferred formatting; autofix drains before format so the final state is
+  formatter-stable. A `write` followed by an `edit` on the same file in the
+  same turn demotes the write's autofix to deferred too.
+
+1. Format queue / immediate formatting when configured (deferred to
+   `agent_end` for an `edit` even under `--immediate-format`, so it lands
+   after autofix reformats the file).
+2. Safe autofix from tools with deterministic fix support — immediate for
+   `write`, deferred to `agent_end` for `edit` (see above).
 3. LSP file sync and diagnostic wait.
 4. Parallel dispatch runners: LSP, ast-grep, tree-sitter, fact rules, and
-   language-specific linters/security scanners.
+   language-specific linters/security scanners. For a deferred `edit`, these
+   run against the not-yet-autofixed disk state, so a lint finding autofix
+   would have cleared may appear here and resolve itself at `agent_end`.
 5. Cascade diagnostics for likely affected neighbors.
 6. Deduplication and routing to blockers, actionable warnings, or code-quality
    history.
 
+See [`docs/agent-guide.md`](agent-guide.md#6-auto-format--auto-fix-timing--dont-be-surprised)
+for the consumer-facing version of this routing.
+
 ## Agent tools
 
 pi-lens exposes these high-value tools to agents:
@@ -91,6 +108,8 @@ pi --lens-guard          # Block git commit/push when unresolved blockers exist
 pi --no-opengrep         # Disable the Opengrep security scanner (default-on auxiliary LSP)
 pi --no-read-guard       # Disable the read-before-edit behavior monitor
 pi --lens-turn-summary   # Persist a per-turn summary of diagnostics, autofixes, and autoformats
+pi --lens-compact-tool-line   # Render tool results as one compact, theme-aware line (closes #1327)
+pi --no-lazy-tools       # Keep every pi-lens tool active instead of activating the situational ones on demand
 
 # Actionable warnings (all default off)
 pi --lens-actionable-warnings          # Report fixable warnings at turn end
@@ -141,6 +160,23 @@ second host adapter that calls the same `clients/lens-engine.ts` seam as the pi
 extension. Use `npm run build:dist` after MCP/engine changes so the user-scoped
 server loads fresh compiled code.
 
+Two Claude Code hooks give the MCP mirror the same automatic cadence the pi
+extension has. PostToolUse runs the per-edit pass, `Stop` runs the per-turn one:
+
+```json
+{ "hooks": {
+  "PostToolUse": [
+    { "matcher": "Edit|Write",
+      "hooks": [ { "type": "command", "command": "pi-lens-analyze --hook" } ] } ],
+  "Stop": [
+    { "hooks": [ { "type": "command", "command": "pi-lens-analyze --turn-end", "timeout": 60 } ] } ]
+} }
+```
+
+The `Stop` hook only works against a running MCP server because only that
+process owns the session state and pending turn work. With no warm server the
+turn-end is skipped, not faked: one line on stderr and nothing on stdout.
+
 ## Troubleshooting
 
 - Run `npm run build` before tests after editing TypeScript; tests import

package/node_modules/pi-lens/docs/word-index.md

@@ -42,6 +42,41 @@ HTTPServer    → httpserver, http, server
 each through `splitIdentifier`; queries are tokenized the same way so
 `"authenticate user"` matches `authenticateUser`, `auth_user`, etc.
 
+## Query prefix filters (#1450)
+
+The query string can mix plain terms with composable `key:value` filters,
+parsed by `parseWordIndexQuery` (`clients/word-index.ts`) before tokenization:
+
+- `lang:<kind>` — restrict to a file kind's extensions, drawn from
+  `KIND_EXTENSIONS` (`clients/file-kinds.ts`) — the single source of truth
+  (#894 invariant), so there is no second, hand-maintained language list here.
+- `file:<substr>` — path substring match against the index's own stored path,
+  normalized through `wordIndexKey` (case-folded on win32 only, matching how
+  the index's own path-keyed maps already fold win32 paths, #1025).
+- `ext:<ext>` — literal extension match (`ext:ts` and `ext:.ts` are
+  equivalent).
+- Any filter may be negated with a leading `-` (`-file:test`).
+
+Example: `lang:jsts file:clients/ -file:test rank`. Multiple positive filters
+of the SAME key OR together; different keys AND; negations always subtract.
+Filters are applied as a `fileFilter` predicate BEFORE BM25/priors/centrality
+scoring (same seam as the pre-existing `paths`/`lang` structured options,
+#771), so a surviving file's score is unaffected by filtering. An unrecognized
+`key:` token passes through as an ordinary search term (colon-bearing terms
+like `std::vector`, URLs, and Windows paths search normally). Only a
+recognized key with a bad value — an unrecognized `lang:` kind — throws
+`WordIndexQueryError`
+naming the supported list — never silently falls through as a literal search
+term. Both the pi `symbol_search` tool and the MCP `pilens_symbol_search`
+mirror inherit the syntax for free since both pass their `query` argument
+straight through to `searchWordIndex` (the entry point where parsing happens).
+
+DF-normalization: BM25's per-token `idf` is computed from the FULL,
+unfiltered posting for that token before `fileFilter` is applied per
+candidate file — a filtered query reuses the global, corpus-wide document
+frequency rather than recomputing it over the filtered subset. Documented as
+an acceptable approximation (see the doc comment on `searchWordIndex`).
+
 ## Lifecycle
 
 The index is built/refreshed in **every** startup mode: load the persisted

package/node_modules/pi-lens/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-lens",
-  "version": "3.8.74",
+  "version": "4.0.1",
   "type": "module",
   "description": "Real-time code feedback for pi — LSP, linters, formatters, type-checking, structural analysis & booboo",
   "repository": {
@@ -20,9 +20,9 @@
     "prepare": "npm run build:dist && node scripts/download-grammars.js --core --dest grammars",
     "lint": "tsc --project tsconfig.json",
     "watch": "tsc --watch",
-    "test": "vitest run",
-    "test:unit": "vitest run --ignore tests/index-integration.test.ts --ignore tests/clients/lsp/integration.test.ts",
-    "test:integration": "vitest run tests/index-integration.test.ts tests/clients/lsp/integration.test.ts",
+    "test": "node scripts/with-test-lock.mjs -- vitest run",
+    "test:unit": "node scripts/with-test-lock.mjs -- vitest run",
+    "test:integration": "node scripts/with-test-lock.mjs -- vitest run tests/index-integration.test.ts tests/clients/lsp/integration.test.ts",
     "test:watch": "vitest",
     "check": "node scripts/check-extensions.mjs",
     "selftest:install": "node scripts/install-selftest.mjs",
@@ -34,7 +34,7 @@
     "audit:astgrep-rule-pairs": "node scripts/audit-astgrep-rule-pairs.mjs",
     "audit:playground": "node scripts/playground-verify-rule.mjs",
     "logs:smells": "node scripts/analyze-pi-lens-logs.mjs",
-    "changelog:check": "node scripts/changelog-release.mjs --check",
+    "changelog:check": "node scripts/rollup-changelog.mjs --check",
     "changelog:release": "node scripts/changelog-release.mjs",
     "changelog:extract": "node scripts/changelog-extract.mjs",
     "release:backfill-notes": "node scripts/backfill-github-releases.mjs",
@@ -85,9 +85,9 @@
   "dependencies": {
     "@ast-grep/cli": "^0.45.0",
     "@ast-grep/napi": "^0.45.0",
-    "@earendil-works/pi-tui": "^0.82.1",
+    "@earendil-works/pi-tui": "^0.84.1",
     "js-yaml": "^5.2.2",
-    "minimatch": "^10.2.5",
+    "minimatch": "^10.2.6",
     "pidusage": "^4.0.1",
     "typebox": "^1.0.0",
     "vscode-jsonrpc": "^9.0.0"
@@ -105,7 +105,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.10",
-    "@earendil-works/pi-coding-agent": "^0.82.1",
+    "@earendil-works/pi-coding-agent": "^0.84.1",
     "@types/node": "^26.0.0",
     "@types/pidusage": "^2.0.5",
     "@vitest/coverage-v8": "^4.1.5",
@@ -134,8 +134,8 @@
     ]
   },
   "allowScripts": {
-    "@ast-grep/cli@0.44.1": true,
+    "@ast-grep/cli@0.45.1": true,
     "@google/genai@1.52.0": true,
-    "protobufjs@7.6.4": true
+    "protobufjs@7.6.5": true
   }
 }

package/node_modules/pi-lens/rules/ast-grep-rules/rule-tests/no-bare-except-test.yml

@@ -15,6 +15,55 @@ valid:
         doThing()
     except Exception as e:
         handle(e)
+  - |
+    # dotted/qualified name (#1031)
+    try:
+        doThing()
+    except asyncio.TimeoutError:
+        handle()
+  - |
+    # parenthesized single name (mirrors #1026's tree-sitter spec set)
+    try:
+        doThing()
+    except (ValueError):
+        handle()
+  - |
+    # subscripted generic (#1244)
+    try:
+        doThing()
+    except dict[str, int]:
+        handle()
+  - |
+    # subscripted PEP 654 exception group (#1244)
+    try:
+        doThing()
+    except BaseExceptionGroup[TypeError, ValueError]:
+        handle()
+  - |
+    try:
+        doThing()
+    except ValueError | TypeError:
+        handle()
+  - |
+    try:
+        doThing()
+    except cache[key]:
+        handle()
+  - |
+    try:
+        doThing()
+    except (ValueError,):
+        handle()
+  - |
+    try:
+        doThing()
+    except (mod.E1, E2) as error:
+        handle(error)
+  - |
+    try:
+        doThing()
+    except* ValueError:
+        handle()
 invalid:
   - |
     try:

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

@@ -0,0 +1,87 @@
+id: no-bare-host-path-in-win32-branch
+valid:
+  # DOCUMENTED LIMITATION (#1339 review): the exact pre-fix #1150 shape --
+  # bare dirname in an unguarded helper CALLED FROM the guarded branch.
+  # ast-grep has no cross-function reach, so this is deliberately a
+  # negative fixture; it exists so a future strengthening flips it to a
+  # positive consciously, not accidentally. Review-enforced meanwhile
+  # (AGENTS.md defect-shape 2).
+  - |
+    import * as path from "node:path";
+    import { isWindowsPath } from "./path-utils.js";
+    function resolveNonExisting(filePath: string) {
+      return path.dirname(filePath);
+    }
+    function normalize(filePath: string) {
+      if (isWindowsPath(filePath)) {
+        return resolveNonExisting(filePath);
+      }
+    }
+  - |
+    import * as path from "node:path";
+    import { isWindowsPath } from "./path-utils.js";
+    function f(filePath: string) {
+      if (isWindowsPath(filePath)) {
+        return path.win32.dirname(filePath);
+      }
+      return path.dirname(filePath);
+    }
+  - |
+    import * as path from "node:path";
+    import { isWindowsPath } from "./path-utils.js";
+    function f(filePath: string) {
+      return isWindowsPath(filePath)
+        ? path.win32.basename(filePath)
+        : path.basename(filePath);
+    }
+  - |
+    import { dirname } from "node:path";
+    function f(filePath: string) {
+      if (someOtherPredicate(filePath)) {
+        return dirname(filePath);
+      }
+    }
+invalid:
+  # Fresh probes from the #1339 review, encoded so they stay covered.
+  - |
+    import * as path from "node:path";
+    import { isWindowsPath } from "./path-utils.js";
+    function f(filePath: string) {
+      if (isWindowsPath(filePath)) {
+        for (const part of parts) {
+          const nested = path.join(filePath, part);
+        }
+      }
+    }
+  - |
+    import * as path from "node:path";
+    import { isWindowsPath } from "./path-utils.js";
+    function f(filePath: string) {
+      if (isWindowsPath(filePath)) {
+        return filePath.split(path.sep);
+      }
+    }
+  - |
+    import * as path from "node:path";
+    import { isFullyQualifiedWin32 } from "./path-utils.js";
+    function f(filePath: string, other: boolean) {
+      if (isFullyQualifiedWin32(filePath) && other) {
+        return path.basename(filePath);
+      }
+    }
+  - |
+    import * as path from "node:path";
+    import { isWindowsPath } from "./path-utils.js";
+    function f(filePath: string) {
+      if (isWindowsPath(filePath)) {
+        return path.dirname(filePath);
+      }
+    }
+  - |
+    import { join, sep } from "node:path";
+    import { isFullyQualifiedWin32 } from "./path-utils.js";
+    function f(filePath: string) {
+      if (isFullyQualifiedWin32(filePath)) {
+        return join(filePath, sep);
+      }
+    }

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

@@ -0,0 +1,8 @@
+id: no-chained-type-assertions
+valid:
+  - 'const v = x as A'
+  - 'const w = x as A as const'
+  - 'const u = x as unknown as Foo'
+invalid:
+  - 'const v = x as A as B'
+  - 'const v = foo.bar() as A as B;'

package/node_modules/pi-lens/rules/ast-grep-rules/rule-tests/no-conditional-empty-object-spread-js-test.yml

@@ -0,0 +1,9 @@
+id: no-conditional-empty-object-spread-js
+valid:
+  - 'const o = {...(cond ? {a: 1} : {b: 2})}'
+  - 'const o = {...base}'
+  - 'const o = {...(cond ? extra : other)}'
+invalid:
+  - 'const o = {...(cond ? {} : {x})}'
+  - 'const o = {...(cond ? {y} : {})}'
+  - 'const o = {...cond ? {} : {x}}'

package/node_modules/pi-lens/rules/ast-grep-rules/rule-tests/no-conditional-empty-object-spread-test.yml

@@ -0,0 +1,9 @@
+id: no-conditional-empty-object-spread
+valid:
+  - 'const o = {...(cond ? {a: 1} : {b: 2})}'
+  - 'const o = {...base}'
+  - 'const o = {...(cond ? extra : other)}'
+invalid:
+  - 'const o = {...(cond ? {} : {x})}'
+  - 'const o = {...(cond ? {y} : {})}'
+  - 'const o = {...cond ? {} : {x}}'

package/node_modules/pi-lens/rules/ast-grep-rules/rule-tests/no-nested-links-test.yml

@@ -2,7 +2,17 @@ id: no-nested-links
 valid:
   - '<a href="/x">link</a>'
   - '<a href="/x"><span>nested</span></a>'
+  - '<div><a href="/x">link</a></div>'
+  - '<div><a href="/x">first</a><a href="/y">second</a></div>'
 invalid:
   - '<a href="/x">outer <a href="/y">inner</a></a>'
   - '<a><a>double</a></a>'
-  - '<div><a href="/x">link</a></div>'
+  - '<a href="/x"><span><a href="/y">inner</a></span></a>'
+  - |
+      <a href="/outer">
+        <span>
+          <a href="/middle">
+            <em><a href="/inner">deep</a></em>
+          </a>
+        </span>
+      </a>

package/node_modules/pi-lens/rules/ast-grep-rules/rule-tests/no-raw-json-store-write-test.yml

@@ -0,0 +1,17 @@
+id: no-raw-json-store-write
+valid:
+  - "writeFileAtomic(file, JSON.stringify(data))"
+  - "writeFileSync(file, text)"
+invalid:
+  # #1349 review: encoding/replacer/indent variants are the same raw write.
+  - "writeFileSync(file, JSON.stringify(data), 'utf8')"
+  - "writeFileSync(file, JSON.stringify(data, null, 2))"
+  - "fs.writeFileSync(file, JSON.stringify(data, replacer), { encoding: 'utf8' })"
+  - "writeFileSync(file, JSON.stringify(data))"
+  - "fs.writeFileSync(file, JSON.stringify(data))"
+  - |
+    const payload = JSON.stringify(data)
+    writeFileSync(file, payload)
+  - |
+    const payload = JSON.stringify(data)
+    fs.writeFileSync(file, payload)

package/node_modules/pi-lens/rules/ast-grep-rules/rule-tests/no-reflect-apply-js-test.yml

@@ -0,0 +1,7 @@
+id: no-reflect-apply-js
+valid:
+  - 'fn.apply(obj, args)'
+  - 'fn(...args)'
+invalid:
+  - 'Reflect.apply(fn, obj, args)'
+  - 'const r = Reflect.apply(target[method], target, argumentsList);'

package/node_modules/pi-lens/rules/ast-grep-rules/rule-tests/no-reflect-apply-test.yml

@@ -0,0 +1,7 @@
+id: no-reflect-apply
+valid:
+  - 'fn.apply(obj, args)'
+  - 'fn(...args)'
+invalid:
+  - 'Reflect.apply(fn, obj, args)'
+  - 'const r = Reflect.apply(target[method], target, argumentsList);'

package/node_modules/pi-lens/rules/ast-grep-rules/rule-tests/no-reflect-get-js-test.yml

@@ -0,0 +1,8 @@
+id: no-reflect-get-js
+valid:
+  - 'obj.prop'
+  - 'obj[key]'
+  - 'Reflect.get(target, prop, receiver)'
+invalid:
+  - 'Reflect.get(obj, "key")'
+  - 'const v = Reflect.get(target, prop);'

package/node_modules/pi-lens/rules/ast-grep-rules/rule-tests/no-reflect-get-test.yml

@@ -0,0 +1,8 @@
+id: no-reflect-get
+valid:
+  - 'obj.prop'
+  - 'obj[key]'
+  - 'Reflect.get(target, prop, receiver)'
+invalid:
+  - 'Reflect.get(obj, "key")'
+  - 'const v = Reflect.get(target, prop);'

package/node_modules/pi-lens/rules/ast-grep-rules/rule-tests/no-unknown-laundering-test.yml

@@ -0,0 +1,11 @@
+id: no-unknown-laundering
+valid:
+  - 'const x: unknown = foo()'
+  - 'function f(x: unknown) {}'
+  - 'function isValidPayload(data: unknown): data is Foo { return true; }'
+  - 'function f(cause: unknown) {}'
+  - 'type X = { a: unknown }'
+  - 'type Y = Record<string, unknown>'
+invalid:
+  - 'type X = unknown'
+  - 'type LooseHandler = unknown'

package/node_modules/pi-lens/rules/ast-grep-rules/rule-tests/no-win32-isabsolute-for-qualification-test.yml

@@ -0,0 +1,16 @@
+id: no-win32-isabsolute-for-qualification
+valid:
+  # DOCUMENTED LIMITATION (#1349 review): the aliased parser -- the shape
+  # the actual pre-#1330 defect used -- is beyond ast-grep's reach and is
+  # deliberately a negative; flipping it to invalid requires an engine
+  # capability decision. Review-enforced meanwhile (AGENTS.md shape 2).
+  - |
+    const w = path.win32;
+    if (w.isAbsolute(filePath)) {
+      return true;
+    }
+  - "isFullyQualified(filePath)"
+  - "path.posix.isAbsolute(filePath)"
+invalid:
+  - "path.win32.isAbsolute(filePath)"
+  - "win32.isAbsolute(filePath)"

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

@@ -12,20 +12,8 @@ note: |
   identifier, making it fire only for empty bodies or `pass`/`raise`
   (where there are no function-call identifiers).
 
-  The fixed rule checks the except_clause's direct children for ANY of
-  the three exception-spec shapes (bare identifier `except E`, tuple
-  `except (E, F)`, or `as` pattern `except E as e`). The original missed
-  the tuple and `as_pattern` forms — a tuple like `(ValueError, KeyError)`
-  has no direct `identifier` child (the identifiers are inside the
-  tuple), and `except Exception as e` has `e` as an identifier child
-  even though the type is specified.
+  The rule now matches the grammar's bare `except:` syntax directly, so
+  newly introduced exception-spec node kinds cannot become false positives.
 rule:
   kind: except_clause
-  not:
-    any:
-      - has:
-          kind: identifier
-      - has:
-          kind: tuple
-      - has:
-          kind: as_pattern
+  pattern: "except:"

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

@@ -0,0 +1,25 @@
+id: no-bare-host-path-in-win32-branch
+language: TypeScript
+severity: warning
+message: "Use win32 path operations inside a branch committed to Windows path semantics"
+note: |
+  A branch guarded by isWindowsPath/isFullyQualifiedWin32 has committed to
+  Windows path parsing. Host-default dirname/basename/join/relative/sep
+  follows the process OS and is wrong for a Windows-shaped path on POSIX.
+
+  SCOPE (review-verified, #1339): same-function consequence only. The
+  original #1150 defect — a bare dirname inside an UNGUARDED helper that
+  the guarded branch calls (cross-function) — is NOT reachable by this
+  engine and stays review-enforced via AGENTS.md defect-shape 2. The
+  rule's fixture file encodes that miss as a documented negative; flip it
+  to a positive only if cross-function reach is ever added. What this
+  rule does catch is the in-branch shape (#1152 class).
+rule:
+  all:
+    - kind: if_statement
+    - has:
+        field: condition
+        regex: "\\b(isWindowsPath|isFullyQualifiedWin32)\\s*\\("
+    - has:
+        field: consequence
+        regex: "(?s)\\bpath\\.(dirname|basename|join|relative)\\s*\\(|\\bpath\\.sep\\b|(^|[^.])\\b(dirname|basename|join|relative)\\s*\\("

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

@@ -0,0 +1,21 @@
+id: no-chained-type-assertions
+language: TypeScript
+severity: warning
+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.
+rule:
+  pattern: $X as $A as $B
+  not:
+    pattern: "$X as unknown as $B"

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-conditional-empty-object-spread-js.yml

@@ -0,0 +1,21 @@
+id: no-conditional-empty-object-spread-js
+language: JavaScript
+severity: hint
+message: "Conditional empty-object spread — use an explicit if/else to omit fields"
+note: |
+  `{...(cond ? {} : {x})}` hides field omission behind a ternary — an
+  explicit `if` reads better. Matched structurally (spread of a ternary
+  whose consequence or alternative is an empty object literal), not by
+  exact source text, so it also catches the un-parenthesized form.
+
+  Kept at `hint` to match no-conditional-empty-object-spread.yml — see
+  that rule's note for the FP-scan finding (147 hits, all a deliberate
+  existing idiom).
+rule:
+  kind: spread_element
+  has:
+    stopBy: end
+    kind: ternary_expression
+    any:
+      - has: { field: consequence, stopBy: neighbor, kind: object, regex: '^\{\s*\}$' }
+      - has: { field: alternative, stopBy: neighbor, kind: object, regex: '^\{\s*\}$' }

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-conditional-empty-object-spread.yml

@@ -0,0 +1,29 @@
+id: no-conditional-empty-object-spread
+language: TypeScript
+severity: hint
+message: "Conditional empty-object spread — use an explicit if/else to omit fields"
+note: |
+  `{...(cond ? {} : {x})}` hides field omission behind a ternary — an
+  explicit `if` reads better and lets the object's shape stay typed.
+  Matched structurally (spread of a ternary whose consequence or
+  alternative is an empty object literal), not by exact source text, so
+  it also catches the un-parenthesized and multi-property-spread forms.
+
+  FP-scan finding (pi-lens codebase, clients/ tools/ mcp/ index.ts): 147
+  hits, and every sampled hit is this exact shape used deliberately to
+  build an optional-field object (`...(hit.annotations ? {
+  annotations: hit.annotations } : {})`). That is a real, established
+  idiom here, not a shape mismatch — so the rule stays at `hint` rather
+  than `warning`: still discoverable in a scan, but it does not read as
+  a call to fix 147 existing sites.
+rule:
+  kind: spread_element
+  has:
+    # the ternary sits under a parenthesized_expression when the source
+    # parenthesizes it, so this needs stopBy: end — spread_element's
+    # DIRECT child is not the ternary in that (common) form.
+    stopBy: end
+    kind: ternary_expression
+    any:
+      - has: { field: consequence, stopBy: neighbor, kind: object, regex: '^\{\s*\}$' }
+      - has: { field: alternative, stopBy: neighbor, kind: object, regex: '^\{\s*\}$' }

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-nested-links.yml

@@ -8,6 +8,12 @@ note: |
 rule:
   all:
     - kind: jsx_element
+    - has:
+        field: open_tag
+        kind: jsx_opening_element
+        has:
+          field: name
+          regex: "^a$"
     - has:
         kind: jsx_element
         stopBy: end
@@ -20,6 +26,7 @@ rule:
   not:
     inside:
       kind: jsx_element
+      stopBy: end
       has:
         field: open_tag
         kind: jsx_opening_element

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-raw-json-store-write.yml

@@ -0,0 +1,30 @@
+id: no-raw-json-store-write
+language: TypeScript
+severity: warning
+message: "Use the atomic write seam for JSON stores instead of writeFileSync"
+note: |
+  JSON-backed durable state must be committed through clients/durable-store.ts
+  when read-modify-write isolation is required; that seam publishes through
+  clients/atomic-write.ts. This rule covers the direct
+  writeFileSync(path, JSON.stringify(data)) shape. Build scripts and the
+  installer's wx lock writes are intentionally outside this rule's scope.
+ignores:
+  - "**/clients/atomic-write.ts"
+  - "**/clients/installer/index.ts"
+  - "**/scripts/**"
+rule:
+  any:
+    - pattern: writeFileSync($PATH, JSON.stringify($$$ARGS))
+    - pattern: $FS.writeFileSync($PATH, JSON.stringify($$$ARGS))
+    - pattern: writeFileSync($PATH, JSON.stringify($$$ARGS), $OPTS)
+    - pattern: $FS.writeFileSync($PATH, JSON.stringify($$$ARGS), $OPTS)
+    - kind: expression_statement
+      has:
+        pattern: writeFileSync($PATH, $PAYLOAD)
+      follows:
+        pattern: const $PAYLOAD = JSON.stringify($DATA)
+    - kind: expression_statement
+      has:
+        pattern: $FS.writeFileSync($PATH, $PAYLOAD)
+      follows:
+        pattern: const $PAYLOAD = JSON.stringify($DATA)

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-reflect-apply-js.yml

@@ -0,0 +1,9 @@
+id: no-reflect-apply-js
+language: JavaScript
+severity: warning
+message: "Reflect.apply() — use a typed call (fn.apply(...) or fn(...args)) instead"
+note: |
+  Reflect.apply reaches for reflection where a typed call already works.
+  Prefer Function#apply or a direct call with spread arguments.
+rule:
+  pattern: Reflect.apply($$$ARGS)

package/node_modules/pi-lens/rules/ast-grep-rules/rules/no-reflect-apply.yml

@@ -0,0 +1,9 @@
+id: no-reflect-apply
+language: TypeScript
+severity: warning
+message: "Reflect.apply() — use a typed call (fn.apply(...) or fn(...args)) instead"
+note: |
+  Reflect.apply reaches for reflection where a typed call already works.
+  Prefer Function#apply or a direct call with spread arguments.
+rule:
+  pattern: Reflect.apply($$$ARGS)