@herbertgao/pi-extensions 2026.8.4 → 2026.8.6

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

@@ -0,0 +1,13 @@
+id: no-reflect-get-js
+language: JavaScript
+severity: warning
+message: "Reflect.get(obj, key) — use a typed property access (obj.prop or obj[key]) instead"
+note: |
+  Reflect.get reaches for reflection where a typed property access
+  already works. Prefer dot or bracket access.
+
+  Scoped to the 2-argument form only — see no-reflect-get.yml's note:
+  the 3-argument receiver-forwarding form is the standard Proxy `get`
+  trap idiom.
+rule:
+  pattern: Reflect.get($OBJ, $KEY)

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

@@ -0,0 +1,16 @@
+id: no-reflect-get
+language: TypeScript
+severity: warning
+message: "Reflect.get(obj, key) — use a typed property access (obj.prop or obj[key]) instead"
+note: |
+  Reflect.get reaches for reflection where a typed property access
+  already works. Prefer dot or bracket access.
+
+  Scoped to the 2-argument form only. The 3-argument form
+  (`Reflect.get(target, key, receiver)`) is the standard, correct way to
+  forward a `receiver` inside a Proxy `get` trap — an FP-scan of the
+  pi-lens codebase found 2 hits, both inside a Proxy trap using the
+  3-argument receiver-forwarding form, so that arity is excluded rather
+  than allowlisted by call site.
+rule:
+  pattern: Reflect.get($OBJ, $KEY)

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

@@ -0,0 +1,27 @@
+id: no-unknown-laundering
+language: TypeScript
+severity: warning
+message: "type alias to bare 'unknown' — give the alias real shape or inline 'unknown' at the one call site that needs it"
+note: |
+  `type X = unknown` adds a name but zero type information — every
+  consumer of X still has to narrow from scratch, so the alias only
+  launders the fact that nothing was typed. Give it real shape, or drop
+  the alias and let the (rare) genuine unknown-input site say so
+  directly.
+
+  FP-scan finding (pi-lens codebase, clients/ tools/ mcp/ index.ts):
+  the originally proposed wider fan-out — bare `unknown` return types,
+  `unknown` parameters, and `Record<string, unknown>` / index-signature
+  dictionaries — was dropped from this rule. Each of those arms fired
+  overwhelmingly on legitimate, idiomatic TypeScript already in this
+  codebase: `unknown` parameters on type-guard/validator functions
+  (`errorMessage(err: unknown)`, `asRecord(value: unknown)`), `unknown`
+  return types on parsers and a `ProxyHandler.get` trap (whose signature
+  TypeScript itself requires), and `Record<string, unknown>` on
+  telemetry/metadata bags (`metadata?: Record<string, unknown>`). A
+  declared `unknown` at those positions is the CORRECT contract — it
+  forces the caller to narrow — so it is not syntactically distinguishable
+  from a laundered one; only `type X = unknown` stayed a reliable
+  precision signal (zero hits in the same scan).
+rule:
+  pattern: "type $T = unknown"

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

@@ -0,0 +1,23 @@
+id: no-win32-isabsolute-for-qualification
+language: TypeScript
+severity: warning
+message: "Use isFullyQualified for path qualification instead of win32.isAbsolute"
+note: |
+  Qualification must follow the input path's shape. Use clients/path-utils.ts
+  isFullyQualified(), which distinguishes drive-absolute, UNC, rooted-relative,
+  POSIX-absolute, and relative paths across host operating systems. The
+  implementation of isFullyQualified itself is excluded because it is the
+  compatibility seam that owns the win32 parser call.
+
+  SCOPE (review-verified, #1349): direct call forms only --
+  path.win32.isAbsolute(...) and a destructured win32.isAbsolute(...). An
+  ALIASED parser (const w = path.win32; w.isAbsolute(p) -- the shape the
+  actual pre-#1330 defect used) is beyond the engine's reach and stays
+  review-enforced; the fixture file encodes that miss as a documented
+  negative, matching the #1339 precedent.
+ignores:
+  - "**/clients/path-utils.ts"
+rule:
+  any:
+    - pattern: path.win32.isAbsolute($P)
+    - pattern: win32.isAbsolute($P)

package/node_modules/pi-lens/rules/tree-sitter-queries/tsx/no-nested-links.yml

@@ -18,15 +18,13 @@ query: |
   (jsx_element
     open_tag: (jsx_opening_element
       (identifier) @OUTER
-      (#eq? @OUTER "a"))
-    (jsx_element
-      open_tag: (jsx_opening_element
-        (identifier) @INNER
-        (#eq? @INNER "a"))))
+      (#eq? @OUTER "a"))) @OUTER_ELEMENT
 
 metavars:
   - OUTER
-  - INNER
+  - OUTER_ELEMENT
+
+post_filter: no_nested_anchor_chain
 
 tags:
   - correctness

package/node_modules/pi-lens/rules/tree-sitter-queries/typescript/duplicate-function-arg.yml

@@ -22,8 +22,8 @@ description: |
 
 query: |
   (formal_parameters
-    (required_parameter (identifier) @PARAM1)
-    (required_parameter (identifier) @NAME))
+    (_ pattern: (_) @PARAM1)
+    (_ pattern: (_) @NAME))
 
 metavars:
   - PARAM1

package/node_modules/pi-lens/scripts/analyze-pi-lens-logs.mjs

@@ -8,9 +8,11 @@
  *   ~/.pi-lens/cascade*.log          JSONL impact-cascade logs
  *   ~/.pi-lens/read-guard*.log       JSONL read-guard friction logs
  *   ~/.pi-lens/tree-sitter*.log      JSONL structural runner logs
+ *   ~/.pi-lens/extension*.log        JSONL extension diagnostics and console-guard telemetry
  *   ~/.pi-lens/actionable-warnings*.log  JSONL advisory pipeline (inject/suppress)
  *   ~/.pi-lens/ast-grep-tools*.log   JSONL MCP ast-grep search/replace telemetry
  *   ~/.pi-lens/logs/*.jsonl          JSONL diagnostic findings
+ *   ~/.pi-lens/projects/<slug>/worklog.jsonl  JSONL fix worklog (rule/tool/model/provider, #1448)
  */
 
 import fs from "node:fs";
@@ -18,10 +20,12 @@ import os from "node:os";
 import path from "node:path";
 import readline from "node:readline";
 import { fileURLToPath } from "node:url";
+import { minimatch } from "minimatch";
 
 const DEFAULT_ROOT = path.join(os.homedir(), ".pi-lens");
 const DEFAULT_SINCE = "2d";
 const DEFAULT_LIMIT = 12;
+const DEFAULT_EXCLUDE_GLOBS = ["**/AppData/Local/Temp/claude/**", "**/heap-corpus*/**", "**/.plegma/work/**"];
 
 const args = parseArgs(process.argv.slice(2));
 const root = path.resolve(expandHome(args.root ?? DEFAULT_ROOT));
@@ -30,6 +34,10 @@ const limit =
 	Number.parseInt(args.limit ?? `${DEFAULT_LIMIT}`, 10) || DEFAULT_LIMIT;
 const outputJson = Boolean(args.json);
 const includeArchived = Boolean(args.archived);
+const excludeGlobs = [
+	...DEFAULT_EXCLUDE_GLOBS,
+	...(Array.isArray(args.exclude) ? args.exclude : args.exclude ? [args.exclude] : []),
+];
 
 const thresholds = {
 	startupSlowMs: Number.parseInt(args.startupSlowMs ?? "500", 10),
@@ -62,6 +70,7 @@ async function main() {
 		analyzeSessionStart(files.sessionStart, state),
 		analyzeActionableWarnings(files.actionableWarnings, state),
 		analyzeAstGrepTools(files.astGrepTools, state),
+		analyzeWorklog(files.worklog, state),
 	]);
 
 	const report = buildReport(state);
@@ -83,7 +92,14 @@ function parseArgs(argv) {
 			const key = arg.slice(2);
 			const next = argv[i + 1];
 			if (!next || next.startsWith("--")) out[key] = "true";
-			else out[key] = argv[++i];
+			else if (key === "exclude") {
+				const value = argv[++i];
+				out.exclude = out.exclude
+					? Array.isArray(out.exclude)
+						? [...out.exclude, value]
+						: [out.exclude, value]
+					: value;
+			} else out[key] = argv[++i];
 		}
 	}
 	return out;
@@ -125,6 +141,13 @@ function discoverLogFiles(logRoot, archived) {
 		.filter((name) => name.endsWith(".jsonl"))
 		.map((name) => path.join(logsDir, name));
 
+	// worklog.jsonl lives per-project under projects/<slug>/ (getProjectDataDir),
+	// not at the log root — walk one level to find every project's file (#1448).
+	const projectsDir = path.join(logRoot, "projects");
+	const worklogs = safeReaddir(projectsDir)
+		.map((slug) => path.join(projectsDir, slug, "worklog.jsonl"))
+		.filter((file) => fs.existsSync(file));
+
 	const byPrefix = (prefix) =>
 		allRootFiles.filter((file) => {
 			const base = path.basename(file);
@@ -142,6 +165,7 @@ function discoverLogFiles(logRoot, archived) {
 		actionableWarnings: byPrefix("actionable-warnings"),
 		astGrepTools: byPrefix("ast-grep-tools"),
 		diagnostics: dailyLogs,
+		worklog: worklogs,
 	};
 }
 
@@ -158,6 +182,7 @@ function createState(files) {
 		window: { since: since?.toISOString() ?? "all", root },
 		files,
 		parseErrors: counter(),
+		excludedRows: 0,
 		seen: counter(),
 		projects: counter(),
 		smellTotals: counter(),
@@ -248,6 +273,14 @@ function createState(files) {
 			errors: [],
 			slow: [],
 		},
+		worklog: {
+			// key: "<rule>||<model>" (model "" when the entry predates #1448 or the
+			// runtime didn't know it) -> { total, autoFixed }
+			byRuleModel: new Map(),
+			byModel: counter(),
+			byModelAutoFixed: counter(),
+			byProvider: counter(),
+		},
 	};
 }
 
@@ -557,6 +590,10 @@ async function analyzeSessionStart(files, state) {
 			const ts = dateOf(match[1]);
 			if (!inWindow(ts)) return;
 			const message = match[2];
+			if (isExcludedText(message)) {
+				state.excludedRows++;
+				return;
+			}
 			state.seen.inc("sessionstart");
 
 			const cwd = /session_start cwd:\s*(.*)$/.exec(message)?.[1];
@@ -718,17 +755,82 @@ async function analyzeAstGrepTools(files, state) {
 	}
 }
 
+/**
+ * Per-model rollup (#1448): rule × model counts and auto-fixed vs
+ * agent-required rates, from worklog.jsonl's optional `model`/`provider`
+ * fields. Entries predating #1448 (or written outside a live agent turn)
+ * have neither field — bucketed under the empty-string model/provider key so
+ * "unattributed" volume stays visible rather than silently dropped.
+ */
+async function analyzeWorklog(files, state) {
+	for (const file of files) {
+		await forEachJsonLine(file, "worklog", state, (entry) => {
+			const ts = dateOf(entry.timestamp);
+			if (!inWindow(ts)) return;
+			state.seen.inc("worklog");
+			const rule = entry.rule ?? "unknown";
+			const model = entry.model ?? "";
+			const provider = entry.provider ?? "";
+			const key = `${rule}||${model}`;
+			const row = state.worklog.byRuleModel.get(key) ?? {
+				rule,
+				model,
+				total: 0,
+				autoFixed: 0,
+			};
+			row.total += 1;
+			if (entry.autoFixed) row.autoFixed += 1;
+			state.worklog.byRuleModel.set(key, row);
+			state.worklog.byModel.inc(model || "(unknown)");
+			if (entry.autoFixed) state.worklog.byModelAutoFixed.inc(model || "(unknown)");
+			state.worklog.byProvider.inc(provider || "(unknown)");
+		});
+	}
+}
+
 async function forEachJsonLine(file, bucket, state, visitor) {
 	await forEachLine(file, async (line) => {
 		if (!line.trim()) return;
 		try {
-			visitor(JSON.parse(line));
+			const entry = JSON.parse(line);
+			if (isExcludedEntry(entry)) {
+				state.excludedRows++;
+				return;
+			}
+			visitor(entry);
 		} catch {
 			state.parseErrors.inc(`${bucket}:${path.basename(file)}`);
 		}
 	});
 }
 
+function isExcludedEntry(entry) {
+	return pathValues(entry).some((value) =>
+		excludeGlobs.some((glob) =>
+			minimatch(value, glob, { nocase: true, dot: true }),
+		),
+	);
+}
+
+function pathValues(value, key = "") {
+	if (typeof value === "string") {
+		return /(file|path|cwd|root|project)/i.test(key) ? [normalizePath(value)] : [];
+	}
+	if (!value || typeof value !== "object") return [];
+	return Object.entries(value).flatMap(([childKey, child]) =>
+		pathValues(child, childKey),
+	);
+}
+
+function isExcludedText(text) {
+	const cwd = /session_start cwd:\s*(.*)$/.exec(text)?.[1];
+	return cwd
+		? excludeGlobs.some((glob) =>
+				minimatch(normalizePath(cwd), glob, { nocase: true, dot: true }),
+			)
+		: false;
+}
+
 async function forEachLine(file, visitor) {
 	if (!fs.existsSync(file)) return;
 	const rl = readline.createInterface({
@@ -1129,6 +1231,7 @@ function buildReport(state) {
 			Object.entries(state.files).map(([key, list]) => [key, list.length]),
 		),
 		rowsSeen: state.seen.toJSON(),
+		rowsExcluded: state.excludedRows,
 		parseErrors: state.parseErrors.toJSON(),
 		projects: state.projects.top(limit),
 		smells,
@@ -1207,6 +1310,17 @@ function buildReport(state) {
 			errors: state.astGrep.errors.slice(0, limit),
 			slow: state.astGrep.slow.slice(0, limit),
 		},
+		worklog: {
+			byModel: state.worklog.byModel.top(limit * 2),
+			byProvider: state.worklog.byProvider.top(limit * 2),
+			byRuleModel: [...state.worklog.byRuleModel.values()]
+				.map((row) => ({
+					...row,
+					autoFixedRate: row.total ? row.autoFixed / row.total : 0,
+				}))
+				.sort((a, b) => b.total - a.total)
+				.slice(0, limit * 3),
+		},
 	};
 }
 
@@ -1232,6 +1346,7 @@ function printReport(report) {
 			.map(([k, v]) => `${k}=${v}`)
 			.join(", ")}`,
 	);
+	console.log(`${report.rowsExcluded} rows excluded (synthetic corpora)`);
 	if (Object.keys(report.parseErrors).length)
 		console.log(`parse errors: ${JSON.stringify(report.parseErrors)}`);
 
@@ -1344,6 +1459,23 @@ function printReport(report) {
 			`  started=${ws.started} completed=${ws.completed} incomplete=${ws.incomplete} aborted=${ws.aborted} fileTimeouts=${ws.timedOutFilesTotal} (in ${ws.timedOutSweeps} sweeps)`,
 		);
 	}
+	const wl = report.worklog;
+	if (wl && (wl.byModel.length || wl.byRuleModel.length)) {
+		console.log("\nWorklog per-model rollup (#1448)");
+		console.log(
+			`  by model: ${wl.byModel.map((x) => `${x.key}=${x.count}`).join(", ")}`,
+		);
+		if (wl.byProvider.length)
+			console.log(
+				`  by provider: ${wl.byProvider.map((x) => `${x.key}=${x.count}`).join(", ")}`,
+			);
+		console.log("  rule × model (auto-fixed vs agent-required):");
+		for (const row of wl.byRuleModel.slice(0, limit))
+			console.log(
+				`    ${String(row.total).padStart(5)}  ${row.rule} [${row.model || "(unknown)"}]  autoFixed=${row.autoFixed} (${(row.autoFixedRate * 100).toFixed(0)}%)`,
+			);
+	}
+
 	const timeouts = Object.entries(report.latency.phaseTimeouts ?? {});
 	if (timeouts.length) {
 		console.log("\nPhase timeouts");

package/node_modules/pi-lens/skills/pi-lens-ast-grep/SKILL.md

@@ -52,12 +52,15 @@ Use `$$$` when you don't need the captured value; `$$$NAME` when you do.
 
 Use these instead of writing raw YAML:
 
-| Parameter | What it does |
-|---|---|
-| `insideKind` | Only match inside an ancestor of this node kind |
-| `hasKind` | Only match nodes that contain a descendant of this kind |
-| `follows` | Only match nodes preceded by a sibling matching this pattern |
-| `precedes` | Only match nodes followed by a sibling matching this pattern |
+| Parameter | Tool | What it does |
+|---|---|---|
+| `insideKind` | both | Only match inside an ancestor of this node kind (searches ALL ancestors, `stopBy: end`) |
+| `hasKind` | both | Only match nodes whose **immediate child** has this kind (`stopBy: neighbor` — NOT recursive) |
+| `hasDescendantKind` | both | Only match nodes containing this kind **anywhere in their descendants** (`stopBy: end`) — use this instead of `hasKind` when the target isn't a direct child |
+| `follows` | both | Only match nodes preceded by a sibling matching this pattern |
+| `precedes` | both | Only match nodes followed by a sibling matching this pattern |
+
+`hasKind` and `hasDescendantKind` are mutually exclusive on both tools — combining them errors.
 
 ```
 # console.log only inside functions
@@ -152,13 +155,9 @@ Use these as starting points, then scope `paths` tightly.
 
 | Task | Pattern / params |
 |---|---|
-| Find pi lifecycle handlers | `pattern: pi.on($EVENT, $HANDLER)` |
-| Find timers | `pattern: setTimeout($CALLBACK, $$$REST)` or `setInterval($CALLBACK, $$$REST)` |
-| Find immediate/deferred work | `pattern: setImmediate($CALLBACK)` |
-| Find promise callbacks | `pattern: $PROMISE.then($CALLBACK)` / `.catch($CALLBACK)` / `.finally($CALLBACK)` |
 | Find object-literal function dependency by name | `pattern: { resetLSPService: $FN, $$$REST }` |
-| Find fire-and-forget async calls | `pattern: void $CALL` |
 | Find empty catches | `pattern: try { $$$BODY } catch ($ERR) { }` |
+| Find fire-and-forget async calls | `pattern: void $CALL` |
 
 For lifecycle bugs, search first, then use the returned `details.matchLocations[].readSlice` handle for bounded context.
 

package/node_modules/pi-lens/skills/pi-lens-lsp-navigation/SKILL.md

@@ -13,39 +13,39 @@ Use `lsp_diagnostics` before builds/tests or after touching several files:
 
 | Need | Tool call |
 |---|---|
-| Check one file | `lsp_diagnostics({ filePath: "src/file.ts" })` |
-| Check a folder | `lsp_diagnostics({ filePath: "src/", severity: "error" })` |
-| Check exact touched files | `lsp_diagnostics({ filePaths: ["src/a.ts", "src/b.ts"], concurrency: 8 })` |
-| Slow server (Rust, Java) | `lsp_diagnostics({ filePaths: files, waitMs: 2000 })` |
-| Include warnings | `lsp_diagnostics({ filePaths: files, severity: "all" })` |
+| Check one file | `lsp_diagnostics({ path: "src/file.ts" })` |
+| Check a folder | `lsp_diagnostics({ path: "src/", severity: "error" })` |
+| Check exact touched files | `lsp_diagnostics({ paths: ["src/a.ts", "src/b.ts"], concurrency: 8 })` |
+| Slow server (Rust, Java) | `lsp_diagnostics({ paths: files, waitMs: 2000 })` |
+| Include warnings | `lsp_diagnostics({ paths: files, severity: "all" })` |
 
-Prefer explicit `filePaths` batches after multi-file edits — bounded concurrency, no unrelated directory noise.
+Prefer explicit `paths` batches after multi-file edits — bounded concurrency, no unrelated directory noise.
 
 ## Navigation (Code Intelligence)
 
 | Question | Operation | Parameters |
 |---|---|---|
-| Where is this defined? | `definition` | filePath, line, character |
-| Where is this symbol's *type* defined? | `typeDefinition` | filePath, line, character |
-| Where is this declared (vs defined)? | `declaration` | filePath, line, character |
-| Find all usages | `references` | filePath, line, character |
-| What type is this? | `hover` | filePath, line, character |
-| Call signature | `signatureHelp` | filePath, line, character (at arg position) |
-| Symbols in this file | `documentSymbol` | filePath |
-| Find symbol across project | `workspaceSymbol` | query + filePath (strongly recommended) |
-| Quick fixes available | `codeAction` | filePath, line, character, endLine, endCharacter |
-| Rename symbol safely | `rename` | filePath, line, character, newName |
-| Who implements this? | `implementation` | filePath, line, character |
-| Who calls this function? | `prepareCallHierarchy` → `incomingCalls` | filePath, line, character |
-| What does this call? | `prepareCallHierarchy` → `outgoingCalls` | filePath, line, character |
-| What commands does the server offer? | `capabilities` | (optional filePath) — lists advertised commands |
+| Where is this defined? | `definition` | path, line, character |
+| Where is this symbol's *type* defined? | `typeDefinition` | path, line, character |
+| Where is this declared (vs defined)? | `declaration` | path, line, character |
+| Find all usages | `references` | path, line, character |
+| What type is this? | `hover` | path, line, character |
+| Call signature | `signatureHelp` | path, line, character (at arg position) |
+| Symbols in this file | `documentSymbol` | path |
+| Find symbol across project | `workspaceSymbol` | query + path (strongly recommended) |
+| Quick fixes available | `codeAction` | path, line, character, endLine, endCharacter |
+| Rename symbol safely | `rename` | path, line, character, newName |
+| Who implements this? | `implementation` | path, line, character |
+| Who calls this function? | `prepareCallHierarchy` → `incomingCalls` | path, line, character |
+| What does this call? | `prepareCallHierarchy` → `outgoingCalls` | path, line, character |
+| What commands does the server offer? | `capabilities` | (optional path) — lists advertised commands |
 | Run a server command (e.g. organize imports) | `executeCommand` | command (+ commandArguments); dry-run unless `apply:true` |
 
 ## Call Hierarchy Pattern
 
 ```
 // Step 1
-lsp_navigation(operation="prepareCallHierarchy", filePath="src/api.ts", line=42, character=10)
+lsp_navigation(operation="prepareCallHierarchy", path="src/api.ts", line=42, character=10)
 // → returns callHierarchyItem
 
 // Step 2
@@ -56,7 +56,7 @@ lsp_navigation(operation="outgoingCalls", callHierarchyItem=<item from step 1>)
 ## Operational Notes
 
 - **`definition` returns nothing?** The file may not be open/indexed yet. Read it first, then retry.
-- **`workspaceSymbol` empty?** Always pass `filePath`. Unscoped queries are best-effort and frequently return nothing. If TypeScript returns "No Project", open the scoped file first.
+- **`workspaceSymbol` empty?** Always pass `path`. Unscoped queries are best-effort and frequently return nothing. If TypeScript returns "No Project", open the scoped file first.
 - **`references`** — query from the *definition site* for full cross-file coverage; usage-site queries can be partial.
 - **`signatureHelp`** — only valid at call-site argument positions; declaration positions return empty.
 - **`workspaceDiagnostics`** — tracked push snapshot only, not an active check. Use `lsp_diagnostics` when you need fresh results.

package/node_modules/pi-lens/skills/pi-lens-write-ast-grep-rule/SKILL.md

@@ -67,7 +67,7 @@ constraints:                  # metavariable regex constraints work
 
 ⚠ **`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 below.
+gotcha — see the `has` note in `reference.md`.
 
 ## YAML quoting — REQUIRED (js-yaml will reject the rule otherwise)
 
@@ -100,120 +100,14 @@ The parser is a real YAML parser, so unquoted special chars throw and the rule i
 ✅ Docs: docs/custom-rules.md
 ```
 
-## Hard-won gotchas (NAPI runner specifics — verified)
+## Reference doc — read before writing a NAPI-runner-specific or hard-to-express rule
 
-```
-⚠ `has`/`inside` default to DIRECT child/parent — add `stopBy: end` for a recursive search.
-   This cuts BOTH ways, so think about where the target node actually lives:
-   - Target is a grandchild+ → you MUST add `stopBy: end` or the `has` never matches.
-     `switch-without-default` = `switch_statement` not has `switch_default`: the default
-     lives under `switch_body`, so without `stopBy: end` it matches nothing and every
-     switch (even ones WITH a default) is flagged. Same for `nested-ternary` catching a
-     parenthesized `a ? (b ? c : d) : e`.
-   - Target is the direct child → leave it at `neighbor` (default). Adding `stopBy: end`
-     OVER-reports: `throw_statement` has `string` + `stopBy: end` flags `throw new
-     Error("x")` (the string is nested), and `expression_statement` has `new_expression`
-     + `stopBy: end` flags `fn(new Error())` as a discarded error. Keep these direct.
-   napi's `has` never matches the node itself, so a self-referential `kind: X` has
-   `kind: X` (with `stopBy: end`) correctly flags only genuinely-nested X.
-
-✅ Prefer `regex` on the matched node's OWN text over `has` when you only need to
-   inspect the node — avoids recursive-descendant false positives:
-     kind: export_statement
-     regex: '^export\s+(let|var)\b'      # precise; no has-recursion FP
-   (NAPI evaluates `regex` with JS RegExp on node.text() — keep it LINEAR so the
-   detector can't itself ReDoS.)
-
-⚠ String-literal regexes match SOURCE text, not the runtime string value.
-   Inspect the exact node text before writing constraints:
-     ast-grep run --kind string --lang ts sample.ts --json=compact
-   Example: source `"\\|"` is node text `"\\\\|"` in JSON; to match a
-   source-level escaped backslash (`\\`) followed by a non-backslash, the rule
-   regex needs FOUR regex backslashes, preferably in a YAML block scalar:
-     regex: >-
-       ^["'`]\\\\[^\\A-Za-z0-9$]
-   This is how `incomplete-string-escaping` catches both `"\\|"` and
-   `'\\"'`. Avoid shell here-doc probes for this class — shell/JSON escaping
-   can silently eat a backslash and make the rule look broken.
-
-⚠ `-js` twins: remember there are TWO execution surfaces.
-   - ast-grep CLI/LSP language-gates by `language:`. A `language: TypeScript`
-     rule is not enough for standalone `.js` coverage, so shipped user-facing
-     TS/JS rules that should fire under the ast-grep LSP usually need a `-js`
-     twin with `language: JavaScript` plus its own fixture.
-   - the in-process NAPI fallback (`ast-grep-napi.ts`) parses the target file's
-     own grammar and currently runs both TS and JS rules on every jsts file. A
-     grammar-agnostic twin can therefore duplicate in fallback mode.
-   - **Decide explicitly:** if the rule must cover `.js` through the ast-grep
-     CLI/LSP baseline, ship the twin and test both. If a rule is NAPI-only or
-     fallback duplication is unacceptable, fix runner dedup/normalization before
-     relying on a single TypeScript rule for JS coverage.
-   - **Grammar-divergent bodies** still need separate variants regardless:
-     e.g. `no-flag-argument` uses `required_parameter` in TS and
-     `assignment_pattern` in JS.
-
-✅ Node-kind facts (tree-sitter-typescript grammar — NOT the TS compiler / Roslyn):
-   - let / const  → `lexical_declaration`     (var is NOT here)
-   - var          → `variable_declaration`
-   - a regex literal's pattern text  → `regex_pattern`
-   - x[i] index access  → `subscript_expression`   (NOT element_access_expression)
-   - obj.prop access    → `member_expression`      (NOT property_access_expression)
-   - !x / -x / typeof x → `unary_expression`
-   - a ? b : c          → `ternary_expression`
-
-❌ Wrong-grammar kind names = silent dead rule. `element_access_expression`,
-   `property_access_expression`, `binary_operator`, etc. are TS-compiler/Roslyn names, not
-   tree-sitter's. napi REJECTS the whole rule ("invalid kind matcher") so it never runs.
-   Verify a kind exists before shipping:
-     node -e 'import("@ast-grep/napi").then(s=>{const r=s.ts.parse("x[i]").root();
-       const f=(n,k)=>{let c=n.kind()===k?1:0;for(const x of n.children())c+=f(x,k);return c};
-       console.log(f(r,"subscript_expression"))})'   # >0 means the kind is real
-
-✅ Test through the REAL runner from the repo root — it loads the actual shipped
-   rules from rules/ast-grep-rules/rules. Assert on diagnostic `rule` ids:
-     const res = await runner.run(ctx);  // ctx.filePath = temp .ts, cwd = repo
-   For pattern/kind/regex-only rules (CLI-identical semantics) `ast-grep scan` is fine.
-
-✅ Before shipping any text/regex detector, FP-scan the codebase:
-     ast-grep scan -r <rule>.yml clients tools
-   Real safe variants bite (e.g. ReDoS: (ba+)+ is safe — a mandatory prefix makes
-   the partition unique; flag only a single quantified atom inside the group).
-```
-
-## Matching things a pattern can't express (#305)
-
-```
-❌ A parameter default is NOT a `$X = false` pattern. `pattern: $FLAG = false` parses as
-   an `assignment_expression` (statement context) and never matches a function parameter.
-   Match the PARAM NODE + its child literal instead, capturing the name for reuse:
-     # TS grammar
-     - kind: required_parameter
-       all:
-         - has: { field: pattern, pattern: $FLAG }
-         - has: { any: [ { kind: "true" }, { kind: "false" } ] }
-     # JS grammar (assignment_pattern, with fields left/right)
-     - kind: assignment_pattern
-       all:
-         - has: { field: left, pattern: $FLAG }
-         - has: { field: right, any: [ { kind: "true" }, { kind: "false" } ] }
-
-✅ Metavar consistency works ACROSS sibling clauses of an `all` — a metavar bound in one
-   `has` must match the SAME text everywhere it reappears. Use it to CORRELATE nodes, which
-   is what makes a structural rule precise:
-     all:
-       - has: { stopBy: end, kind: required_parameter, has: { field: pattern, pattern: $FLAG } }
-       - has: { stopBy: end, any: [ { pattern: "if ($FLAG) $$$" }, { pattern: "if (!$FLAG) $$$" } ] }
-   This fires ONLY when the function branches on the SAME param it declared boolean — a
-   boolean default that's never branched on, or a branch on a different var, won't match.
-
-❌ Two `has:` keys in one mapping silently OVERWRITE (YAML: last key wins). For multiple
-   descendant constraints use `all:` with a LIST of `has` entries, never repeated `has:`.
-
-✅ Prefer a high-precision structural guard over an unbounded denylist. Message-chain
-   (Demeter) floods on fluent/promise/builder chains; rather than denylist every fluent
-   method name, REQUIRE the chain's first calls to be accessors (`get*`/`is*`/`has*`) via
-   `constraints` regex — promise/fluent/builder methods aren't accessor-named, so they're
-   excluded by construction. Precision over recall.
+`reference.md` (same directory) covers: ReDoS-safe regex authoring, node-text
+string-escape quirks, `has`/`inside` `stopBy` defaults (and when to override
+them), the `-js` twin dedup behavior (#657), boolean-parameter matching
+across the TS/JS grammars, and precision-over-recall heuristics for
+denylist-shaped rules. Read it when a rule isn't matching (or over-matching)
+the way you expect, or before shipping a `regex`/`has`-heavy rule.
 
 ## Validating a candidate rule against the REAL engine (not the warm MCP cache)