@herbertgao/pi-extensions 2026.8.6 → 2026.8.8

package/node_modules/pi-lens/scripts/lib/warm-loader-cache.mjs

@@ -0,0 +1,285 @@
+/**
+ * Pure helpers for `scripts/warm-loader-cache.mjs` (#1926).
+ *
+ * pi loads an extension through jiti (`createJiti(..., { moduleCache: false,
+ * alias: … })` in `@earendil-works/pi-coding-agent`'s
+ * `dist/core/extensions/loader.js`). jiti transforms the entry with Babel and
+ * stores the result in a filesystem cache. pi-lens's `dist/index.js` is a ~4MB
+ * esbuild bundle, so that transform costs seconds: the first session after a
+ * `git:` install or update measured 4847ms of `module import`, against a 138ms
+ * steady state once the cache is warm (#1926 field report).
+ *
+ * The fix is to pay that transform at install time instead of in the first
+ * interactive session. `prepare` already builds `dist/`, so the last step of
+ * the chain runs the same transform through the same jiti, writing the same
+ * cache file pi will later read.
+ *
+ * WHY THE WARM PRODUCES A HIT FOR THE REAL LOADER
+ *
+ * jiti keys a cache entry on the transformed file, not on the jiti instance
+ * (see `getCache` in `jiti/dist/jiti.cjs`):
+ *
+ *   <basename(dirname(file))>-<basename(file) up to the first dot>
+ *   + "+map" if sourceMaps + ".i" if interopDefault
+ *   + "." + md5(file).slice(0, 8)
+ *   + ".mjs" for an async import, ".cjs" otherwise
+ *
+ * and it validates the stored body against a trailing
+ * ` /* v<TRANSFORM_VERSION>-<md5(source).slice(0,16)> *\/` marker. So the warm
+ * has to agree with pi on three things only: the absolute path of the entry,
+ * the cache directory, and the transform itself. Everything else — the alias
+ * map, `moduleCache`, which package the jiti instance was created from — is
+ * outside the key AND outside the transform. Measured, not assumed: running
+ * this warm over the dogfood install's `dist/index.js` produced a cache file
+ * byte-identical to the one pi had written, both with pi's alias map and with
+ * no alias map at all.
+ *
+ * The marker is also the safety net. If pi ships a jiti whose transform version
+ * or Babel output differs, pi recomputes the marker, does not match, and simply
+ * re-transforms. A mismatched warm costs the install a few seconds and buys
+ * nothing; it can never hand pi the wrong code.
+ */
+
+import { createHash, getFips } from "node:crypto";
+
+/**
+ * Mirror of jiti's `utils_hash`: md5 truncated to `length` hex characters, or
+ * sha256 where FIPS mode forbids md5. jiti makes the same substitution, so the
+ * two agree on every machine.
+ *
+ * @param {string} text
+ * @param {number} [length]
+ * @returns {string}
+ */
+export function jitiHash(text, length = 8) {
+	let fips = false;
+	try {
+		fips = Boolean(getFips?.());
+	} catch {
+		fips = false;
+	}
+	return createHash(fips ? "sha256" : "md5")
+		.update(text)
+		.digest("hex")
+		.slice(0, length);
+}
+
+/**
+ * The cache file jiti writes for an async import of `entry`.
+ *
+ * Mirror of jiti's `getCache` naming:
+ * `<basename(dirname(file))>-<basename up to the first dot>.<hash(file)>.mjs`.
+ * jiti hashes the POSIX-normalised absolute path, so the separators are
+ * converted here. The drive-letter case is left exactly as the caller resolved
+ * it, because jiti does not touch it either. Verified against pi's own cache
+ * directory: the md5 of the dogfood install's forward-slashed entry path,
+ * truncated to 8 characters, is the `db18768f` in the
+ * `dist-index.db18768f.mjs` pi had already written.
+ *
+ * @param {string} entry absolute path to the extension entry
+ * @returns {string}
+ */
+export function expectedCacheFileName(entry) {
+	const posix = entry.split("\\").join("/");
+	const segments = posix.split("/");
+	const base = segments.pop() ?? posix;
+	const parent = segments.pop() ?? "";
+	const dot = base.indexOf(".");
+	const stem = dot <= 0 ? base : base.slice(0, dot);
+	return `${parent}-${stem}.${jitiHash(posix)}.mjs`;
+}
+
+/**
+ * Did the warm actually leave a cache entry pi can use?
+ *
+ * Elapsed time is not evidence. jiti can return from an import having written
+ * nothing, and every such path exits 0:
+ *
+ *   - the cache directory is not writable. jiti's `prepareCacheDir` catches
+ *     that, sets `fsCache` to false, and transforms in memory from then on.
+ *   - the entry imported natively and nothing needed transforming. For an
+ *     async-imported ESM `.js` file jiti's `evalModule` attempts a native
+ *     import UNCONDITIONALLY, and only falls back to the transform when that
+ *     import rejects. So the cache exists at all because native import fails in
+ *     a real `--omit=dev` install, where the host-provided specifiers do not
+ *     resolve. That is the same reason pi's own load transforms the bundle,
+ *     which is why the warm and pi agree — but it is a property of the
+ *     environment, not of this script.
+ *   - a cache entry exists but does not match the source. jiti validates the
+ *     body against a trailing version-and-source-hash marker, so a stale or
+ *     truncated file is a miss for pi and the session pays the transform.
+ *
+ * Checking the file is what turns "the import returned" into "the warm's own
+ * jiti cached this entry, with these versions". It is not a promise about pi:
+ * pi-side drift shows up as a version delta between this record and pi's, which
+ * is a thing to read from the log, not something an install can detect.
+ * An absent entry always warrants a look, never a shrug.
+ *
+ * @param {object} args
+ * @param {string} args.cacheDir
+ * @param {string} args.fileName
+ * @param {string} args.source contents of the entry, for the marker check
+ * @param {object} args.fsDeps
+ * @param {(p: string) => boolean} args.fsDeps.existsSync
+ * @param {(p: string) => string} args.fsDeps.readFileSync
+ * @param {(p: string) => boolean} args.fsDeps.isWritable
+ * @returns {{ok: boolean, reason: string | null, transformVersion: string | null}}
+ */
+export function verifyCacheEntry({ cacheDir, fileName, source, fsDeps }) {
+	const file = `${cacheDir}/${fileName}`;
+	if (!fsDeps.existsSync(file)) {
+		if (!fsDeps.isWritable(cacheDir)) {
+			return {
+				ok: false,
+				reason: `cache directory is not writable: ${cacheDir}`,
+				transformVersion: null,
+			};
+		}
+		// Deliberately generic. Several routes end here — a native import that
+		// needed no transform, a transform that threw before the write — and this
+		// check cannot tell them apart, so it does not name one.
+		return {
+			ok: false,
+			reason: `no cache entry was written: ${fileName}`,
+			transformVersion: null,
+		};
+	}
+	let body;
+	try {
+		body = fsDeps.readFileSync(file);
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		return {
+			ok: false,
+			reason: `cache entry unreadable: ${message}`,
+			transformVersion: null,
+		};
+	}
+	const marker = /\/\* v([^-\s]+)-([0-9a-f]+) \*\/\s*$/.exec(body);
+	if (!marker) {
+		return {
+			ok: false,
+			reason: "cache entry has no jiti version marker — pi will re-transform",
+			transformVersion: null,
+		};
+	}
+	if (marker[2] !== jitiHash(source, marker[2].length)) {
+		return {
+			ok: false,
+			reason:
+				"cache entry does not match the built entry — pi will re-transform",
+			transformVersion: marker[1],
+		};
+	}
+	return { ok: true, reason: null, transformVersion: marker[1] };
+}
+
+/**
+ * Mirror of jiti's `prepareCacheDir` fallback branch.
+ *
+ * jiti picks `<dir of the file that created the jiti instance>/node_modules/
+ * .cache/jiti` when that `node_modules` exists, and `<tmpdir>/jiti` otherwise.
+ * pi creates its instance from `dist/core/extensions/loader.js` inside the
+ * installed `@earendil-works/pi-coding-agent`, which has no `node_modules`
+ * sibling, so pi always lands on the tmpdir branch. The warm therefore passes
+ * `<tmpdir>/jiti` EXPLICITLY rather than letting jiti derive a directory from
+ * this repo's layout: `scripts/` has no `node_modules` sibling today, but a
+ * script moved one level up would silently start filling a private cache that
+ * pi never reads.
+ *
+ * The TMPDIR dance below is jiti's, kept verbatim so the two agree on machines
+ * where TMPDIR is set to the current directory.
+ *
+ * @param {object} deps
+ * @param {() => string} deps.tmpdir
+ * @param {Record<string, string | undefined>} deps.env
+ * @param {() => string} deps.cwd
+ * @param {(a: string, b: string) => string} deps.join
+ * @returns {string}
+ */
+export function resolveJitiCacheDir({ tmpdir, env, cwd, join }) {
+	let dir = tmpdir();
+	if (env.TMPDIR && dir === cwd() && !env.JITI_RESPECT_TMPDIR_ENV) {
+		const saved = env.TMPDIR;
+		delete env.TMPDIR;
+		dir = tmpdir();
+		env.TMPDIR = saved;
+	}
+	return join(dir, "jiti");
+}
+
+/**
+ * Alias every host-provided specifier to a path that cannot exist.
+ *
+ * The warm only needs the TRANSFORM of `dist/index.js`; jiti writes the cache
+ * entry before it evaluates the module. Evaluation then walks the bundle's
+ * external imports, none of which resolve outside pi. Pointing the
+ * host-provided ones at a stub makes that walk stop at the first one instead of
+ * resolving unrelated packages first, so the warm does the least work it can
+ * and always ends the same way. Derived from the shared host-provided list so
+ * it cannot drift from what `bundle-dist.mjs` keeps external.
+ *
+ * @param {readonly string[]} hostProvidedPackages
+ * @returns {Record<string, string>}
+ */
+export function buildStubAliases(hostProvidedPackages) {
+	/** @type {Record<string, string>} */
+	const alias = {};
+	for (const name of hostProvidedPackages) {
+		alias[name] = STUB_TARGET;
+	}
+	return alias;
+}
+
+/** A path no filesystem resolves, so aliased imports fail immediately. */
+export const STUB_TARGET = "/__pi-lens-warm-cache-stub__";
+
+/**
+ * Decide whether the warm can run, and say why not when it cannot.
+ *
+ * Every reason is a skip, never a failure: `prepare` also builds `dist/` and
+ * downloads grammars, and those steps MUST fail loudly. Cache warming is an
+ * optimisation, so it runs last and reports rather than throws — the same
+ * posture as `scripts/setup-git-hooks.mjs` (#1804).
+ *
+ * @param {object} state
+ * @param {Record<string, string | undefined>} state.env
+ * @param {boolean} state.distEntryExists
+ * @param {boolean} state.jitiResolvable
+ * @returns {string | null} skip reason, or null to proceed
+ */
+export function warmSkipReason({ env, distEntryExists, jitiResolvable }) {
+	const optOut = env.PI_LENS_SKIP_WARM_CACHE;
+	if (typeof optOut === "string" && optOut.length > 0) {
+		return "PI_LENS_SKIP_WARM_CACHE is set";
+	}
+	if (!distEntryExists) {
+		return "dist/index.js is missing — nothing to warm";
+	}
+	if (!jitiResolvable) {
+		// jiti is an optionalDependency, so `--omit=optional` (or a failed
+		// optional install) legitimately leaves it absent.
+		return "jiti is not installed — install ran without optional dependencies";
+	}
+	return null;
+}
+
+/**
+ * Keep the install log bounded: one line per install, newest last.
+ *
+ * @param {string[]} existingLines
+ * @param {string} line
+ * @param {number} [max]
+ * @returns {string[]}
+ */
+export function appendBounded(
+	existingLines,
+	line,
+	max = INSTALL_LOG_MAX_LINES,
+) {
+	const lines = [...existingLines.filter((l) => l.trim().length > 0), line];
+	return lines.slice(Math.max(0, lines.length - max));
+}
+
+/** Cap for `~/.pi-lens/install.log`. */
+export const INSTALL_LOG_MAX_LINES = 100;

package/node_modules/pi-lens/scripts/warm-loader-cache.mjs

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+// scripts/warm-loader-cache.mjs (#1926)
+//
+// Pay pi's jiti transform of dist/index.js at install time, so no interactive
+// session pays it.
+//
+// pi loads an extension with jiti, which Babel-transforms the entry and caches
+// the result under <tmpdir>/jiti. pi-lens's entry is a ~4MB esbuild bundle, so
+// the transform is the dominant startup cost exactly once per build: the first
+// session after a `git:` install or update measured 4847ms of `module import`,
+// against 138ms once the cache is warm. `prepare` has just built that bundle,
+// so this script transforms it through the same jiti and writes the same cache
+// entry pi will read.
+//
+// See scripts/lib/warm-loader-cache.mjs for why the entry this writes is the
+// entry pi reads — the cache key, the transform-version marker that makes a
+// mismatch a miss instead of a corruption, and the measurement that proved the
+// output byte-identical to pi's own.
+//
+// POSTURE: best-effort, last in the chain, always exit 0. `prepare` also runs
+// `build:dist` and `download-grammars`, which consumers depend on and which
+// MUST fail loudly. A cache warm is an optimisation and must never share their
+// failure path — the same split `scripts/setup-git-hooks.mjs` makes (#1804).
+import * as fs from "node:fs";
+import { createRequire } from "node:module";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { HOST_PROVIDED_PACKAGES } from "./lib/host-provided-deps.mjs";
+import {
+	appendBounded,
+	buildStubAliases,
+	expectedCacheFileName,
+	resolveJitiCacheDir,
+	verifyCacheEntry,
+	warmSkipReason,
+} from "./lib/warm-loader-cache.mjs";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const require = createRequire(import.meta.url);
+
+function log(message) {
+	process.stderr.write(`[warm-loader-cache] ${message}\n`);
+}
+
+/**
+ * Append one JSONL record to ~/.pi-lens/install.log.
+ *
+ * pi's install output scrolls away, so without this there is no record that the
+ * warm ran, was skipped, or failed. One bounded line per install keeps the
+ * question answerable after the fact. `PI_LENS_INSTALL_LOG` redirects the file,
+ * which is how the tests read the record back.
+ */
+function record(entry) {
+	try {
+		const override = process.env.PI_LENS_INSTALL_LOG;
+		const file =
+			typeof override === "string" && override.length > 0
+				? override
+				: path.join(os.homedir(), ".pi-lens", "install.log");
+		fs.mkdirSync(path.dirname(file), { recursive: true });
+		const existing = fs.existsSync(file)
+			? fs.readFileSync(file, "utf8").split("\n")
+			: [];
+		const line = JSON.stringify({
+			ts: new Date().toISOString(),
+			event: "warm_loader_cache",
+			...entry,
+		});
+		fs.writeFileSync(file, `${appendBounded(existing, line).join("\n")}\n`);
+	} catch {
+		// The log is diagnostic. Losing it must not change the install outcome.
+	}
+}
+
+/** Entries pi will load, read from the manifest rather than hardcoded. */
+function extensionEntries() {
+	try {
+		const pkg = JSON.parse(
+			fs.readFileSync(path.join(root, "package.json"), "utf8"),
+		);
+		return (pkg.pi?.extensions ?? []).map((entry) => path.resolve(root, entry));
+	} catch {
+		return [];
+	}
+}
+
+async function loadCreateJiti() {
+	// `jiti/static` is the subpath pi's loader imports, and it is export-mapped
+	// for `import` only — `require.resolve` reports it as not exported. Resolve
+	// it the ESM way, and fall back to the package root for older runtimes.
+	for (const specifier of ["jiti/static", "jiti"]) {
+		try {
+			const url = import.meta.resolve
+				? import.meta.resolve(specifier)
+				: pathToFileURL(require.resolve(specifier)).href;
+			const mod = await import(url);
+			if (typeof mod.createJiti === "function") return mod.createJiti;
+		} catch {
+			// Try the next specifier; absence is a skip, not a failure.
+		}
+	}
+	return undefined;
+}
+
+/**
+ * The installed jiti's version, so a host jiti bump — which changes the marker
+ * and silently turns every warm into a cold session — is diagnosable from the
+ * record rather than from a bisect.
+ */
+function jitiVersion() {
+	try {
+		const url = import.meta.resolve
+			? import.meta.resolve("jiti/package.json")
+			: pathToFileURL(require.resolve("jiti/package.json")).href;
+		return JSON.parse(fs.readFileSync(fileURLToPath(url), "utf8")).version;
+	} catch {
+		return null;
+	}
+}
+
+/** Real-filesystem probes for `verifyCacheEntry`. */
+const fsDeps = {
+	existsSync: (p) => fs.existsSync(p),
+	readFileSync: (p) => fs.readFileSync(p, "utf8"),
+	isWritable: (p) => {
+		try {
+			fs.accessSync(p, fs.constants.W_OK);
+			return true;
+		} catch {
+			return false;
+		}
+	},
+};
+
+export async function main() {
+	const entries = extensionEntries();
+	const createJiti = await loadCreateJiti();
+	const skip = warmSkipReason({
+		env: process.env,
+		distEntryExists:
+			entries.length > 0 && entries.every((e) => fs.existsSync(e)),
+		jitiResolvable: typeof createJiti === "function",
+	});
+	if (skip) {
+		log(`skipped: ${skip}`);
+		record({ status: "skipped", reason: skip });
+		return;
+	}
+
+	const cacheDir = resolveJitiCacheDir({
+		tmpdir: os.tmpdir,
+		env: process.env,
+		cwd: process.cwd,
+		join: path.join,
+	});
+	const alias = buildStubAliases(HOST_PROVIDED_PACKAGES);
+	const version = jitiVersion();
+
+	for (const entry of entries) {
+		const started = Date.now();
+		const cacheFile = expectedCacheFileName(entry);
+		const jiti = createJiti(pathToFileURL(entry).href, {
+			// Mirror pi's loader: no in-process module cache, aliases present.
+			// Neither affects the transform or the cache key, but staying close to
+			// pi's call keeps the two easy to compare.
+			moduleCache: false,
+			fsCache: cacheDir,
+			alias,
+		});
+		try {
+			// jiti writes the cache entry BEFORE it evaluates the module, so the
+			// warm is complete even though evaluation then fails on the first
+			// host-provided import — those only resolve inside pi.
+			await jiti.import(entry, { default: true });
+		} catch {
+			// Expected. Evaluation is not the goal; the transform is.
+		}
+		const ms = Date.now() - started;
+		const relative = path.relative(root, entry);
+
+		// The import returning proves nothing. Several exit-0 paths leave no usable
+		// entry — an unwritable cache directory, an import that never reached the
+		// transform, a stale file that fails jiti's marker check — so read the file
+		// back before claiming anything was cached.
+		const verdict = verifyCacheEntry({
+			cacheDir,
+			fileName: cacheFile,
+			source: fs.readFileSync(entry, "utf8"),
+			fsDeps,
+		});
+		const common = {
+			entry: relative,
+			ms,
+			cacheDir,
+			cacheFile,
+			jitiVersion: version,
+		};
+		if (verdict.ok) {
+			log(`warmed ${relative} in ${ms}ms (cache: ${cacheDir}/${cacheFile})`);
+			record({
+				status: "warmed",
+				...common,
+				transformVersion: verdict.transformVersion,
+			});
+			continue;
+		}
+		log(`not cached: ${relative} after ${ms}ms — ${verdict.reason}`);
+		record({ status: "not_cached", ...common, reason: verdict.reason });
+	}
+}
+
+/**
+ * Run `work`, absorbing any failure. Exported so a test can inject a throwing
+ * body and assert the process still exits 0 and still leaves a record.
+ */
+export async function run(work = main) {
+	try {
+		await work();
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		log(`failed: ${message}`);
+		record({ status: "failed", reason: message });
+	}
+}
+
+const invokedPath = process.argv[1];
+const invokedDirectly =
+	typeof invokedPath === "string" &&
+	pathToFileURL(path.resolve(invokedPath)).href === import.meta.url;
+if (invokedDirectly) {
+	await run();
+}

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

@@ -62,6 +62,8 @@ Use these instead of writing raw YAML:
 
 `hasKind` and `hasDescendantKind` are mutually exclusive on both tools — combining them errors.
 
+⚠ `insideKind` searches ALL ancestors (`stopBy: end`) with no boundary of its own — on a deeply nested file it can escalate past the enclosing function you meant and match against an unrelated outer scope; scope with `paths` or a raw YAML `rule:` with its own `stopBy` boundary if that matters.
+
 ```
 # console.log only inside functions
 ast_grep_search pattern="console.log($MSG)" lang="typescript" insideKind="function_declaration"

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

@@ -13,7 +13,7 @@ Same `id` as a built-in overrides it. Multiple rules per file: separate with `--
 ```yaml
 id: no-foo-bar
 language: TypeScript        # PascalCase — see languages below
-severity: warning           # error | warning | info
+severity: warning           # error | warning | hint | info — pick by evidence, see below
 message: "Avoid foo.bar() — use baz() instead"
 note: |
   Longer explanation / fix guidance here.
@@ -21,6 +21,39 @@ 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`
@@ -69,6 +102,13 @@ constraints:                  # metavariable regex constraints work
 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
@@ -104,13 +144,50 @@ The parser is a real YAML parser, so unquoted special chars throw and the rule i
 
 `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
+them), scoping a relation to the nearest enclosing node with a `stopBy`
+boundary rule, 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.
 
+## Testing a suppression
+
+Every relational suppression (a `has`/`inside`/`not` exclusion for a
+legitimate idiom) needs two fixtures per bound metavariable, not one:
+
+1. **A same-binding valid case** — the idiom the exclusion is meant to
+   suppress, with the metavariable bound consistently (same receiver, same
+   key).
+2. **A mutation-guard invalid case** — the same shape with the binding
+   broken: a different key, a different receiver, or a boundary-crossing
+   lookalike (the guard lives in the wrong scope). This proves the
+   exclusion checks the BINDING, not just the pattern's presence somewhere
+   in the file.
+
+`rules/ast-grep-rules/rule-tests/no-non-null-assertion-test.yml` is the model: alongside the
+get-after-has/pop-after-length valid cases, it fixtures a different-key
+guard, a different-map guard, and an outer-function guard that must NOT
+suppress an inner closure — each one red if the corresponding binding check
+is deleted.
+
+Corpus silence is not evidence. A valve with zero corpus hits needs
+adversarial fixtures MORE, not less — `redundant-unsafe-function` targets
+Rust, so it has no pi-lens corpus to census against, and its `# Safety`
+valve still shipped an unbounded backward scan that over-suppressed real
+detections, caught only by adversarial fixtures in review (`00284bcc`). A
+documented blind spot (an idiom the rule knowingly can't distinguish from a
+bug) becomes an `invalid`-direction fixture with a comment naming the gap,
+never silence.
+
+Regenerate the catalog doc with `npm run docs:rule-catalogs` after adding or
+changing a rule — never hand-edit the generated catalog.
+
 ## Validating a candidate rule against the REAL engine (not the warm MCP cache)
 
+Live-binary discipline (AGENTS.md shape 16) applies here too: verify parsing
+and match behavior against a real `ast-grep` run before you write it into a
+rule note or a test fixture — a hand-written fixture pins a guess, not a fact.
+
 ```
 
 # inspect how a PATTERN parses → find the node kind you actually need

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

@@ -92,6 +92,47 @@ grammars, and precision-over-recall heuristics for denylist-shaped rules.
    the partition unique; flag only a single quantified atom inside the group).
 ```
 
+## Scoping to the nearest enclosing X (#1794 F1)
+
+`stopBy` controls how far the ancestor/descendant walk searches. It is not a
+stop CONDITION. An `any:` kind list inside `inside`/`has` decides which
+nodes the walk is ALLOWED to match — it does not tell the walk where to
+halt. `stopBy: end` alone searches every ancestor up to the file root, so a
+guard several scopes out can suppress a finding inside an unrelated closure.
+
+To scope a relation to the nearest enclosing function (or any other
+boundary), give `stopBy` its OWN rule — the same kind list used as the
+match target — so the walk stops at the first satisfying ancestor and can
+never escalate past it:
+
+```yaml
+inside:
+  stopBy:                       # the BOUNDARY: halts the walk here
+    any:
+      - kind: function_declaration
+      - kind: method_definition
+      - kind: arrow_function
+      - kind: function_expression
+  any:                          # the MATCH TARGET: same list, different job
+    - kind: function_declaration
+    - kind: method_definition
+    - kind: arrow_function
+    - kind: function_expression
+  has:
+    stopBy: end
+    pattern: $M.has($K)
+```
+
+This is the fix for #1794 F1: an earlier `no-non-null-assertion` exclusion
+used `stopBy: end` with only the `any:` kind list as the match target, so a
+`.has()`/`.length` guard in an OUTER function suppressed a closure's `!`
+several scopes in. The same defect shape — `stopBy: end` mistaken for a
+boundary — shipped twice in the same 2026-08-20 window: once here, and once
+in `redundant-unsafe-function`'s `# Safety` valve (an unbounded backward
+comment scan, fixed in `00284bcc`). See
+`rules/ast-grep-rules/rules/no-non-null-assertion.yml` for the full working
+rule.
+
 ## Matching things a pattern can't express (#305)
 
 ```