@oh-my-pi/pi-coding-agent 15.10.3 → 15.10.5

package/src/config/model-registry.ts

@@ -96,8 +96,8 @@ const STARTUP_MODEL_CACHE_PROVIDER_IDS: readonly string[] = [
 ];
 
 import type { ApiKeyResolver } from "@oh-my-pi/pi-ai";
-import { registerOAuthProvider, unregisterOAuthProviders } from "@oh-my-pi/pi-ai/utils/oauth";
-import type { OAuthCredentials, OAuthLoginCallbacks } from "@oh-my-pi/pi-ai/utils/oauth/types";
+import { registerOAuthProvider, unregisterOAuthProviders } from "@oh-my-pi/pi-ai/oauth";
+import type { OAuthCredentials, OAuthLoginCallbacks } from "@oh-my-pi/pi-ai/oauth/types";
 import { isRecord, logger } from "@oh-my-pi/pi-utils";
 import { parseModelString, resolveProviderModelReference } from "../config/model-resolver";
 import { isValidThemeColor, type ThemeColor } from "../modes/theme/theme";
@@ -922,6 +922,9 @@ export class ModelRegistry {
 	#runtimeProviderOverrides: Map<string, ProviderOverride> = new Map();
 	#runtimeProvidersBySource: Map<string, Set<string>> = new Map();
 	#runtimeProviderSourceByName: Map<string, string> = new Map();
+	// Runtime model managers registered by extensions via fetchDynamicModels.
+	// Keyed by provider name; use the same SQLite cache path as builtins.
+	#runtimeModelManagers: Map<string, { options: ModelManagerOptions<Api>; sourceId: string }> = new Map();
 	#rebuildPending: boolean = false;
 	#rebuildSuspended: number = 0;
 
@@ -999,6 +1002,27 @@ export class ModelRegistry {
 		}
 	}
 
+	/**
+	 * Discover models for providers registered at runtime via `fetchDynamicModels`
+	 * (extension providers). Merges the discovered catalog into the existing model
+	 * set without reloading static models, so dynamically-discovered models from
+	 * other providers are preserved. No-op when no runtime providers are registered.
+	 *
+	 * Drives the same SQLite model cache as built-in providers, so the default
+	 * `online-if-uncached` strategy fetches at most once per cache TTL (24 h).
+	 */
+	async refreshRuntimeProviders(strategy: ModelRefreshStrategy = "online-if-uncached"): Promise<void> {
+		if (this.#runtimeModelManagers.size === 0) {
+			return;
+		}
+		this.#suspendRebuild();
+		try {
+			await this.#refreshRuntimeDiscoveries(strategy, new Set(this.#runtimeModelManagers.keys()));
+		} finally {
+			this.#resumeRebuild();
+		}
+	}
+
 	#reloadStaticModels(): void {
 		const currentMtime = this.#modelsConfigFile.getMtimeMs();
 		if (currentMtime !== null && currentMtime === this.#lastStaticLoadMtime) {
@@ -1665,6 +1689,10 @@ export class ModelRegistry {
 			}
 			options.push(descriptor.createOptions(key));
 		}
+		// Append runtime model managers registered by extensions via fetchDynamicModels.
+		for (const { options: managerOpts } of this.#runtimeModelManagers.values()) {
+			options.push(managerOpts);
+		}
 		return options;
 	}
 
@@ -2396,6 +2424,7 @@ export class ModelRegistry {
 		this.#runtimeProviderApiKeys.delete(providerName);
 		this.#runtimeProviderOverrides.delete(providerName);
 		this.#runtimeModelOverlays = this.#runtimeModelOverlays.filter(overlay => overlay.provider !== providerName);
+		this.#runtimeModelManagers.delete(providerName);
 		this.authStorage.removeConfigApiKey(providerName);
 	}
 
@@ -2559,6 +2588,47 @@ export class ModelRegistry {
 			return;
 		}
 
+		if (config.fetchDynamicModels) {
+			const fetcher = config.fetchDynamicModels;
+			const providerBaseUrl = config.baseUrl ?? "";
+			const providerApi = config.api;
+			const providerHeaders = config.headers;
+			const providerApiKey = config.apiKey;
+			const providerAuthHeader = config.authHeader;
+			const providerCompat = config.compat;
+			const managerOptions: ModelManagerOptions<Api> = {
+				providerId: providerName as Parameters<typeof createModelManager>[0]["providerId"],
+				staticModels: [],
+				cacheDbPath: this.#cacheDbPath,
+				cacheTtlMs: 24 * 60 * 60 * 1000,
+				dynamicModelsAuthoritative: true,
+				fetchDynamicModels: async () => {
+					const apiKey = await this.authStorage.peekApiKey(providerName);
+					const resolvedKey = isAuthenticated(apiKey) ? apiKey : undefined;
+					const modelDefs = await fetcher(resolvedKey);
+					const results: Model<Api>[] = [];
+					for (const modelDef of modelDefs) {
+						const overlay = buildCustomModelOverlay(
+							providerName,
+							modelDef.baseUrl ?? providerBaseUrl,
+							modelDef.api ?? providerApi,
+							providerHeaders,
+							providerApiKey,
+							providerAuthHeader,
+							providerCompat,
+							undefined,
+							modelDef as CustomModelDefinitionLike,
+						);
+						if (overlay) results.push(finalizeCustomModel(overlay, { useDefaults: true }));
+					}
+					return results;
+				},
+			};
+			this.#runtimeModelManagers.set(providerName, { options: managerOptions, sourceId: sourceId ?? "" });
+			// Discovery is driven by refreshRuntimeProviders() after the drain — not
+			// here, so registration has no network side effect and callers can await.
+		}
+
 		if (
 			config.baseUrl ||
 			config.headers ||
@@ -2636,6 +2706,15 @@ export interface ProviderConfigInput {
 		getApiKey?(credentials: OAuthCredentials): string;
 		modifyModels?(models: Model<Api>[], credentials: OAuthCredentials): Model<Api>[];
 	};
+	/**
+	 * Async factory that fetches the live model list from the provider endpoint.
+	 * When present, the result is run through the same SQLite model-cache as
+	 * built-in providers (keyed by provider name, default 24 h TTL).
+	 * The factory receives the resolved API key (undefined when unauthenticated).
+	 */
+	fetchDynamicModels?: (
+		apiKey: string | undefined,
+	) => Promise<readonly NonNullable<ProviderConfigInput["models"]>[number][]>;
 	models?: Array<{
 		id: string;
 		name: string;

package/src/debug/index.ts

@@ -204,7 +204,7 @@ export class DebugSelectorComponent extends Container {
 			this.ctx.statusContainer.clear();
 
 			const block = new TranscriptBlock();
-			block.addChild(new Text(theme.fg("success", `${theme.status.success} Performance report saved`), 1, 0));
+			block.addChild(new Text(theme.fg("success", `+ Performance report saved`), 1, 0));
 			block.addChild(new Text(theme.fg("dim", formatFileHyperlink(result.path)), 1, 0));
 			block.addChild(new Text(theme.fg("dim", `Files: ${result.files.length}`), 1, 0));
 			this.ctx.present(block);
@@ -261,7 +261,7 @@ export class DebugSelectorComponent extends Container {
 			this.ctx.statusContainer.clear();
 
 			const block = new TranscriptBlock();
-			block.addChild(new Text(theme.fg("success", `${theme.status.success} Report bundle saved`), 1, 0));
+			block.addChild(new Text(theme.fg("success", `+ Report bundle saved`), 1, 0));
 			block.addChild(new Text(theme.fg("dim", formatFileHyperlink(result.path)), 1, 0));
 			block.addChild(new Text(theme.fg("dim", `Files: ${result.files.length}`), 1, 0));
 			this.ctx.present(block);
@@ -298,7 +298,7 @@ export class DebugSelectorComponent extends Container {
 			this.ctx.statusContainer.clear();
 
 			const block = new TranscriptBlock();
-			block.addChild(new Text(theme.fg("success", `${theme.status.success} Memory report saved`), 1, 0));
+			block.addChild(new Text(theme.fg("success", `+ Memory report saved`), 1, 0));
 			block.addChild(new Text(theme.fg("dim", formatFileHyperlink(result.path)), 1, 0));
 			block.addChild(new Text(theme.fg("dim", `Files: ${result.files.length}`), 1, 0));
 			this.ctx.present(block);
@@ -480,11 +480,7 @@ export class DebugSelectorComponent extends Container {
 
 			this.ctx.present([
 				new Spacer(1),
-				new Text(
-					theme.fg("success", `${theme.status.success} Cleared ${result.removed} artifact directories`),
-					1,
-					0,
-				),
+				new Text(theme.fg("success", `- Cleared ${result.removed} artifact directories`), 1, 0),
 			]);
 		} catch (err) {
 			loader.stop();

package/src/discovery/at-imports.ts

@@ -0,0 +1,273 @@
+/**
+ * @-import expansion for context files (AGENTS.md / CLAUDE.md / GEMINI.md / …).
+ *
+ * Other coding agents (Claude Code, Goose, Cline, …) treat `@path/to/file`
+ * references inside their markdown memory files as inline includes. omp
+ * loads the same files in their native shape, so this module performs the
+ * same expansion before content lands in the system prompt.
+ *
+ * Semantics mirror Claude Code's documented behavior:
+ * - `@` must sit at start of line or after whitespace (so `git@github.com`
+ *   and `user@example.com` are not treated as imports).
+ * - Relative paths resolve against the importing file's directory, not the
+ *   working directory.
+ * - `~/...` resolves to the user's home directory.
+ * - Imports inside fenced code blocks (` ``` ` / `~~~`) and inline code
+ *   spans (`` `…` ``) are preserved verbatim so technical examples like
+ *   `npm install @types/node` survive intact.
+ * - Recursive imports are followed up to {@link MAX_AT_IMPORT_DEPTH} hops;
+ *   cycles are broken silently.
+ * - When the referenced file cannot be read, the original `@token` is
+ *   left untouched and a debug log is emitted.
+ *
+ * @see https://docs.claude.com/en/docs/claude-code/memory#import-additional-files
+ */
+import * as os from "node:os";
+import * as path from "node:path";
+import { logger } from "@oh-my-pi/pi-utils";
+import { readFile } from "../capability/fs";
+
+/** Maximum number of recursive `@`-import hops. Matches Claude Code's documented cap. */
+export const MAX_AT_IMPORT_DEPTH = 5;
+
+/**
+ * Matches a candidate `@import` token: a leading boundary (start-of-string
+ * or single whitespace char) and a token whose first character is path-like.
+ *
+ * The boundary character is captured separately so the slice arithmetic in
+ * {@link expandLine} aligns with the `@` position, not the whitespace.
+ */
+const AT_IMPORT_REGEX = /(^|[ \t])@([./~A-Za-z0-9_-][^\s]*)/g;
+
+/**
+ * Trailing characters stripped from a captured path token: sentence-ending
+ * punctuation, closing brackets, quotes. A lone trailing period is treated
+ * as sentence grammar (e.g. `See @AGENTS.md.`) — legitimate file extensions
+ * still match because the stripped set is anchored at the very end of the
+ * token, so `@AGENTS.md` keeps the `.md` (the `d` is not in the set).
+ */
+const TRAILING_PUNCT = /[.,;:!?)\]}"']+$/;
+
+export interface ExpandAtImportsOptions {
+	/** Maximum hop depth (default: {@link MAX_AT_IMPORT_DEPTH}). */
+	maxDepth?: number;
+	/** Override the home directory used to resolve `~/...` (default: `os.homedir()`). */
+	home?: string;
+}
+
+/**
+ * Expand `@path/to/file` references in `content` against `filePath`'s directory.
+ *
+ * Returns the expanded text. When no imports match, the original string is
+ * returned unchanged.
+ */
+export async function expandAtImports(
+	content: string,
+	filePath: string,
+	options: ExpandAtImportsOptions = {},
+): Promise<string> {
+	const maxDepth = options.maxDepth ?? MAX_AT_IMPORT_DEPTH;
+	const home = options.home ?? os.homedir();
+	const absoluteSource = path.resolve(filePath);
+	const visited = new Set<string>([absoluteSource]);
+	return await expand(content, path.dirname(absoluteSource), 0, maxDepth, home, visited);
+}
+
+async function expand(
+	content: string,
+	baseDir: string,
+	depth: number,
+	maxDepth: number,
+	home: string,
+	visited: Set<string>,
+): Promise<string> {
+	if (depth >= maxDepth) return content;
+
+	const segments = splitMarkdownSegments(content);
+	const out: string[] = [];
+	for (const segment of segments) {
+		if (segment.kind === "code") {
+			out.push(segment.text);
+			continue;
+		}
+		out.push(await expandTextSegment(segment.text, baseDir, depth, maxDepth, home, visited));
+	}
+	return out.join("");
+}
+
+async function expandTextSegment(
+	text: string,
+	baseDir: string,
+	depth: number,
+	maxDepth: number,
+	home: string,
+	visited: Set<string>,
+): Promise<string> {
+	const lines = text.split("\n");
+	for (let i = 0; i < lines.length; i++) {
+		lines[i] = await expandLine(lines[i], baseDir, depth, maxDepth, home, visited);
+	}
+	return lines.join("\n");
+}
+
+async function expandLine(
+	line: string,
+	baseDir: string,
+	depth: number,
+	maxDepth: number,
+	home: string,
+	visited: Set<string>,
+): Promise<string> {
+	if (!line.includes("@")) return line;
+
+	const matches: Array<{ start: number; end: number; importPath: string }> = [];
+	for (const m of line.matchAll(AT_IMPORT_REGEX)) {
+		const matchIndex = m.index ?? 0;
+		const leading = m[1];
+		const rawToken = m[2];
+		const atPos = matchIndex + leading.length;
+		if (isInsideInlineCode(line, atPos)) continue;
+
+		const trimmedToken = rawToken.replace(TRAILING_PUNCT, "");
+		if (trimmedToken.length === 0) continue;
+
+		matches.push({
+			start: atPos,
+			end: atPos + 1 + trimmedToken.length,
+			importPath: trimmedToken,
+		});
+	}
+
+	if (matches.length === 0) return line;
+
+	const parts: string[] = [];
+	let cursor = 0;
+	for (const m of matches) {
+		parts.push(line.slice(cursor, m.start));
+		const expanded = await resolveAndExpand(m.importPath, baseDir, depth, maxDepth, home, visited);
+		parts.push(expanded ?? line.slice(m.start, m.end));
+		cursor = m.end;
+	}
+	parts.push(line.slice(cursor));
+	return parts.join("");
+}
+
+async function resolveAndExpand(
+	importPath: string,
+	baseDir: string,
+	depth: number,
+	maxDepth: number,
+	home: string,
+	visited: Set<string>,
+): Promise<string | null> {
+	const resolved = resolveImportPath(importPath, baseDir, home);
+	if (visited.has(resolved)) {
+		logger.debug("@-import: skipping cyclic include", { path: resolved });
+		return null;
+	}
+
+	const content = await readFile(resolved);
+	if (content === null) {
+		logger.debug("@-import: file not found", { path: resolved });
+		return null;
+	}
+
+	// Visited is shared across the whole expansion tree to break cycles,
+	// even cycles that span multiple importing files.
+	visited.add(resolved);
+	return await expand(content, path.dirname(resolved), depth + 1, maxDepth, home, visited);
+}
+
+function resolveImportPath(importPath: string, baseDir: string, home: string): string {
+	if (importPath === "~") return path.resolve(home);
+	if (importPath.startsWith("~/")) return path.resolve(home, importPath.slice(2));
+	if (path.isAbsolute(importPath)) return path.resolve(importPath);
+	return path.resolve(baseDir, importPath);
+}
+
+interface MarkdownSegment {
+	kind: "text" | "code";
+	text: string;
+}
+
+/**
+ * Split markdown into alternating text/code segments by tracking fenced
+ * code blocks. Inline code spans are handled per-line by {@link isInsideInlineCode}.
+ *
+ * A fence is recognized as a line whose first non-whitespace run is three or
+ * more backticks (or tildes). The closing fence must use the same character
+ * with at least as many marks as the opener.
+ */
+function splitMarkdownSegments(content: string): MarkdownSegment[] {
+	const segments: MarkdownSegment[] = [];
+	const lines = content.split("\n");
+	let buffer: string[] = [];
+	let bufferKind: MarkdownSegment["kind"] = "text";
+	let fenceChar = "";
+	let fenceLen = 0;
+
+	const flush = (): void => {
+		if (buffer.length === 0) return;
+		segments.push({ kind: bufferKind, text: buffer.join("") });
+		buffer = [];
+	};
+
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		const isLast = i === lines.length - 1;
+		// Re-attach each line's trailing newline so adjacent segments
+		// concatenate without losing the boundary `\n`.
+		const lineText = isLast ? line : `${line}\n`;
+		const fence = matchFence(line);
+
+		if (fence && bufferKind === "text") {
+			flush();
+			bufferKind = "code";
+			buffer.push(lineText);
+			fenceChar = fence.char;
+			fenceLen = fence.len;
+		} else if (fence && bufferKind === "code" && fence.char === fenceChar && fence.len >= fenceLen) {
+			buffer.push(lineText);
+			flush();
+			bufferKind = "text";
+			fenceChar = "";
+			fenceLen = 0;
+		} else {
+			buffer.push(lineText);
+		}
+
+		if (isLast) flush();
+	}
+	return segments;
+}
+
+function matchFence(line: string): { char: string; len: number } | null {
+	let i = 0;
+	while (i < line.length && (line[i] === " " || line[i] === "\t")) i++;
+	const char = line[i];
+	if (char !== "`" && char !== "~") return null;
+	let len = 0;
+	while (i + len < line.length && line[i + len] === char) len++;
+	if (len < 3) return null;
+	return { char, len };
+}
+
+/**
+ * Returns `true` when `position` falls inside an unclosed inline-code span on
+ * this line. Implemented as a backtick-parity scan so it handles repeated
+ * delimiters like `` `` literal ` backtick `` `` correctly enough for the
+ * "@-imports inside `code` should not expand" case.
+ */
+function isInsideInlineCode(line: string, position: number): boolean {
+	let inSpan = false;
+	let i = 0;
+	while (i < position && i < line.length) {
+		if (line[i] === "`") {
+			while (i < line.length && line[i] === "`") i++;
+			inSpan = !inSpan;
+		} else {
+			i++;
+		}
+	}
+	return inSpan;
+}

package/src/discovery/builtin-rules/index.ts

@@ -20,8 +20,10 @@ import tsNoAny from "./ts-no-any.md" with { type: "text" };
 import tsNoDeprecatedLeftovers from "./ts-no-deprecated-leftovers.md" with { type: "text" };
 import tsNoDynamicImport from "./ts-no-dynamic-import.md" with { type: "text" };
 import tsNoReturnType from "./ts-no-return-type.md" with { type: "text" };
+import tsNoTestTimers from "./ts-no-test-timers.md" with { type: "text" };
 import tsNoTinyFunctions from "./ts-no-tiny-functions.md" with { type: "text" };
 import tsPromiseWithResolvers from "./ts-promise-with-resolvers.md" with { type: "text" };
+import tsRedundantClearGuard from "./ts-redundant-clear-guard.md" with { type: "text" };
 import tsSetMap from "./ts-set-map.md" with { type: "text" };
 
 /** A bundled rule's stable name and raw markdown (frontmatter + body). */
@@ -44,7 +46,9 @@ export const BUILTIN_RULE_SOURCES: readonly BuiltinRuleSource[] = [
 	{ name: "ts-no-deprecated-leftovers", content: tsNoDeprecatedLeftovers },
 	{ name: "ts-no-dynamic-import", content: tsNoDynamicImport },
 	{ name: "ts-no-return-type", content: tsNoReturnType },
+	{ name: "ts-no-test-timers", content: tsNoTestTimers },
 	{ name: "ts-no-tiny-functions", content: tsNoTinyFunctions },
 	{ name: "ts-promise-with-resolvers", content: tsPromiseWithResolvers },
+	{ name: "ts-redundant-clear-guard", content: tsRedundantClearGuard },
 	{ name: "ts-set-map", content: tsSetMap },
 ];

package/src/discovery/builtin-rules/ts-no-test-timers.md

@@ -0,0 +1,55 @@
+---
+description: Do not use real timers (Bun.sleep, setTimeout, setInterval) in tests — drive time with fake timers instead
+condition:
+  - "Bun\\.sleep\\("
+  - "\\bsetInterval\\("
+  - "\\bsetTimeout\\("
+scope: "tool:edit(*.test.ts), tool:write(*.test.ts)"
+interruptMode: never
+---
+
+**Do not reach for real wall-clock timers in test files.** `Bun.sleep(...)`, `setTimeout(...)`, and `setInterval(...)` tie a test's duration to real time: they slow the suite on every run, and any delay tuned to "long enough" eventually races on a loaded machine and flakes.
+
+## Why it's wrong
+
+- Real delays add fixed latency to every invocation; CI pays it on every run.
+- A sleep sized to mask a race is a guess — the race resurfaces under load.
+- A fixed wait hides *what* you are waiting for, so a failure points at a timeout instead of the real cause.
+
+## Avoid
+
+```typescript
+test("debounce fires once", async () => {
+	const fn = debounce(handler, 100);
+	fn();
+	await Bun.sleep(150); // real delay — slow and timing-dependent
+	expect(handler).toHaveBeenCalledTimes(1);
+});
+```
+
+## Use
+
+Drive time deterministically with fake timers:
+
+```typescript
+import { expect, test, vi } from "bun:test";
+
+test("debounce fires once", () => {
+	vi.useFakeTimers();
+	const fn = debounce(handler, 100);
+	fn();
+	vi.advanceTimersByTime(150); // advance the clock, no real wait
+	expect(handler).toHaveBeenCalledTimes(1);
+});
+```
+
+When the code under test resolves a promise or emits an event, await that signal directly instead of guessing a duration:
+
+```typescript
+await once(emitter, "done"); // await the real event
+const value = await pending; // await the promise the code already exposes
+```
+
+## Exceptions
+
+An integration test that deliberately exercises real timer behavior against the platform clock may need a genuine delay. Keep it rare, and add a short comment naming why deterministic time control will not work.

package/src/discovery/builtin-rules/ts-redundant-clear-guard.md

@@ -0,0 +1,75 @@
+---
+description: Do not guard clearTimeout/clearInterval/clearImmediate with a truthiness or null/undefined check — they accept null and undefined
+scope: "tool:edit(*.{ts,tsx,js,jsx,mts,cts,mjs,cjs}), tool:write(*.{ts,tsx,js,jsx,mts,cts,mjs,cjs})"
+interruptMode: never
+astCondition:
+  - "if ($X) clearTimeout($X)"
+  - "if ($X) { clearTimeout($X) }"
+  - "if ($X) clearInterval($X)"
+  - "if ($X) { clearInterval($X) }"
+  - "if ($X) clearImmediate($X)"
+  - "if ($X) { clearImmediate($X) }"
+  - "if ($X !== null) clearTimeout($X)"
+  - "if ($X !== null) { clearTimeout($X) }"
+  - "if ($X !== null) clearInterval($X)"
+  - "if ($X !== null) { clearInterval($X) }"
+  - "if ($X !== null) clearImmediate($X)"
+  - "if ($X !== null) { clearImmediate($X) }"
+  - "if ($X != null) clearTimeout($X)"
+  - "if ($X != null) { clearTimeout($X) }"
+  - "if ($X != null) clearInterval($X)"
+  - "if ($X != null) { clearInterval($X) }"
+  - "if ($X != null) clearImmediate($X)"
+  - "if ($X != null) { clearImmediate($X) }"
+  - "if ($X !== undefined) clearTimeout($X)"
+  - "if ($X !== undefined) { clearTimeout($X) }"
+  - "if ($X !== undefined) clearInterval($X)"
+  - "if ($X !== undefined) { clearInterval($X) }"
+  - "if ($X !== undefined) clearImmediate($X)"
+  - "if ($X !== undefined) { clearImmediate($X) }"
+  - "if ($X != undefined) clearTimeout($X)"
+  - "if ($X != undefined) { clearTimeout($X) }"
+  - "if ($X != undefined) clearInterval($X)"
+  - "if ($X != undefined) { clearInterval($X) }"
+  - "if ($X != undefined) clearImmediate($X)"
+  - "if ($X != undefined) { clearImmediate($X) }"
+---
+
+**Do not guard `clearTimeout` / `clearInterval` / `clearImmediate` with a truthiness or `null`/`undefined` check.** Per the WHATWG/Node timers spec these functions are no-ops when handed `null`, `undefined`, or any value that doesn't correspond to a live timer. The guard adds a redundant branch that the reader must still reason about.
+
+## Why it's wrong
+
+- The branch can never change behavior — clearing a missing/`null`/`undefined` handle does nothing.
+- Extra branches inflate the code and hide the one line that matters.
+- It signals a misunderstanding of the timer API to future readers.
+
+## Avoid
+
+```ts
+if (this.timer) clearTimeout(this.timer);
+if (handle !== null) clearInterval(handle);
+if (id != undefined) {
+	clearImmediate(id);
+}
+```
+
+## Use
+
+```ts
+clearTimeout(this.timer);
+clearInterval(handle);
+clearImmediate(id);
+```
+
+## When a guard *is* warranted
+
+Keep the check only when the body does more than clear — e.g. it also reassigns the handle or runs other cleanup:
+
+```ts
+if (this.timer) {
+	clearTimeout(this.timer);
+	this.timer = undefined; // extra work → guard is not purely redundant
+}
+```
+
+This rule only fires when the clear call is the sole statement in the guarded branch, so those legitimate cases are left alone.

package/src/discovery/helpers.ts

@@ -163,7 +163,7 @@ export function buildRuleFromMarkdown(
 	},
 ): Rule {
 	const { frontmatter, body } = parseFrontmatter(content, { source: filePath });
-	const { condition, scope } = parseRuleConditionAndScope(frontmatter as RuleFrontmatter);
+	const { condition, astCondition, scope } = parseRuleConditionAndScope(frontmatter as RuleFrontmatter);
 
 	let globs: string[] | undefined;
 	if (Array.isArray(frontmatter.globs)) {
@@ -186,6 +186,7 @@ export function buildRuleFromMarkdown(
 		alwaysApply: frontmatter.alwaysApply === true,
 		description: typeof frontmatter.description === "string" ? frontmatter.description : undefined,
 		condition,
+		astCondition,
 		scope,
 		interruptMode,
 		_source: source,