@wahack/pi-coding-agent 15.11.0

package/src/discovery/builtin-rules/ts-import-type.md

@@ -0,0 +1,42 @@
+---
+description: "Use `import type`, not `import('pkg').Type` in type positions"
+condition: "import\\("
+scope: "tool:edit(*.ts), tool:edit(*.tsx), tool:write(*.ts), tool:write(*.tsx)"
+---
+
+Use top-level `import type` declarations for type-only dependencies. NEVER write `import("pkg").Type` inside source annotations.
+
+## Why
+
+- Top-level imports expose dependencies immediately.
+- Import sorting and deduplication can manage them.
+- Signatures stay readable and reviewable.
+- Re-exports do not inherit noisy inline paths.
+
+## Avoid
+
+```typescript
+// Bad — inline imports hide dependencies in signatures.
+function run(client: import("some-sdk").Client, input: import("zod/v4").infer<Schema>): Promise<Output>;
+
+// Bad — annotations become path dumps.
+const options: import("some-sdk/config").ClientOptions = { ... };
+```
+
+## Use
+
+```typescript
+import type { Client } from "some-sdk";
+import type { ClientOptions } from "some-sdk/config";
+import type { infer as Infer } from "zod/v4";
+
+function run(client: Client, input: Infer<Schema>): Promise<Output>;
+const options: ClientOptions = { ... };
+```
+
+## Exceptions
+
+- Ambient `.d.ts` globals that must not become modules.
+- Generated files whose generator owns import management.
+
+In normal `.ts` / `.tsx` source, use `import type`.

package/src/discovery/builtin-rules/ts-no-any.md

@@ -0,0 +1,56 @@
+---
+description: "Never use `any` in TypeScript annotations or assertions — use `unknown`, generics, or the actual type"
+condition: ": any|as any"
+scope: "tool:edit(*.ts), tool:edit(*.tsx), tool:write(*.ts), tool:write(*.tsx)"
+---
+
+Never use `: any` or `as any`. They disable type checking exactly where the boundary needs precision.
+
+## Use instead
+
+- `unknown` for unvalidated input.
+- A domain type when the shape is known.
+- A generic when the caller supplies the shape.
+- A type guard when runtime checks establish shape.
+- `satisfies` for object literals that must match a contract.
+
+## Parameters and returns
+
+```typescript
+// Bad
+function readId(value: any): any {
+	return value.id;
+}
+
+// Good — validate unknown input.
+function readId(value: unknown): string | undefined {
+	if (value && typeof value === "object" && "id" in value) {
+		const candidate = (value as { id: unknown }).id;
+		return typeof candidate === "string" ? candidate : undefined;
+	}
+}
+```
+
+## Assertions
+
+```typescript
+// Bad
+const root = document.getElementById("root") as any;
+root.innerText = "ready";
+
+// Good
+const root = document.getElementById("root") as HTMLElement | null;
+root?.innerText = "ready";
+```
+
+## Object literals
+
+```typescript
+// Bad
+const config = { port: 3000 } as any as ServerConfig;
+
+// Good
+const config = { port: 3000 } satisfies ServerConfig;
+```
+
+If a library boundary truly requires an unchecked cast, use `as unknown as T` with a short reason. Never leave a bare `any`.

package/src/discovery/builtin-rules/ts-no-deprecated-leftovers.md

@@ -0,0 +1,44 @@
+---
+description: "Do not leave `@deprecated` shims behind after refactors — update call sites and remove the old API"
+condition: "@deprecated"
+scope: "tool:edit(*.ts), tool:edit(*.tsx), tool:write(*.ts), tool:write(*.tsx)"
+---
+
+Do not use `@deprecated` as a substitute for finishing a refactor. If an API is obsolete inside the code you control, update every call site and remove the old name in the same change.
+
+## Why
+
+- Deprecated aliases keep two contracts alive.
+- Future maintainers must preserve behavior nobody should call.
+- Tests can pass while production code keeps using the old path.
+- The next refactor has to unwind both the real API and the compatibility layer.
+
+## Avoid
+
+```typescript
+// Bad — leaves a stale compatibility name instead of finishing the cutover.
+/** @deprecated Use loadSettings instead. */
+export const loadConfig = loadSettings;
+
+// Bad — preserves an obsolete wrapper after callers can be updated.
+/** @deprecated Use createClient instead. */
+export function makeClient(options: ClientOptions): Client {
+	return createClient(options);
+}
+```
+
+## Use
+
+```typescript
+// Update all imports and call sites to the durable name.
+export function loadSettings(path: string): Settings { ... }
+export function createClient(options: ClientOptions): Client { ... }
+```
+
+## Exceptions
+
+- Public package APIs with a documented migration window.
+- Third-party declarations where the deprecated marker reflects an external contract.
+- Tests that intentionally verify deprecated API behavior during a supported transition.
+
+If an exception applies, state the external compatibility requirement. Otherwise, finish the refactor and delete the deprecated symbol.

package/src/discovery/builtin-rules/ts-no-dynamic-import.md

@@ -0,0 +1,39 @@
+---
+description: "Do not use `await import()` — use static imports unless dynamic loading is unavoidable"
+condition: "await import\\("
+scope: "tool:edit(*.ts), tool:edit(*.tsx), tool:write(*.ts), tool:write(*.tsx)"
+---
+
+Use static imports for modules known at author time. Reach for `await import()` only when the module specifier is genuinely runtime-selected.
+
+## Why
+
+- Static imports fail during build, not under load.
+- Bundlers, type checkers, and tree shakers see them.
+- The dependency graph remains reviewable.
+- Consumers keep precise module types without casts.
+
+## Avoid
+
+```typescript
+// Bad — the module path is a literal.
+const { createClient } = await import("some-sdk");
+
+// Bad — dynamic import followed by a shape assertion.
+const mod = (await import("./known-module")) as { run?: unknown };
+```
+
+## Use
+
+```typescript
+import { createClient } from "some-sdk";
+import { run } from "./known-module";
+```
+
+## Exceptions
+
+- Plugin loading from a runtime registry.
+- Platform-specific modules that do not exist everywhere.
+- Test cases that intentionally exercise module loading boundaries.
+
+Exception? Add a short comment naming why static import cannot work.

package/src/discovery/builtin-rules/ts-no-return-type.md

@@ -0,0 +1,45 @@
+---
+description: "Do not use `ReturnType<typeof fn>` — name the type explicitly"
+condition: "ReturnType<"
+scope: "tool:edit(*.ts), tool:edit(*.tsx), tool:write(*.ts), tool:write(*.tsx)"
+---
+
+Do not publish contracts through `ReturnType<typeof fn>`. Name the type at the module that owns the value and import that name at consumers.
+
+## Why
+
+- Named types document the contract directly.
+- Consumers stop coupling to implementation helpers.
+- JSDoc and changelog notes attach to the exported type.
+- Type errors point at the intended API boundary.
+
+## Avoid
+
+```typescript
+// Bad — opaque and coupled to implementation names.
+type Config = Awaited<ReturnType<typeof loadConfig>>;
+type Message = ReturnType<typeof buildMessage>["message"];
+let service: ReturnType<typeof createService> | undefined;
+```
+
+## Use
+
+```typescript
+// In the module that owns the function:
+export interface LoadedConfig {
+	path: string;
+	values: Record<string, unknown>;
+}
+
+export function loadConfig(path: string): Promise<LoadedConfig> { ... }
+
+// At the consumer:
+import type { LoadedConfig } from "./config";
+```
+
+## Exceptions
+
+- Timer handles: `ReturnType<typeof setTimeout>` / `setInterval`.
+- Generic type utilities where the function is a type parameter.
+
+Concrete function? Export a concrete type.

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-no-tiny-functions.md

@@ -0,0 +1,51 @@
+---
+description: "Do not extract 1-2 line functions that only wrap an expression — inline them"
+condition: "\\{\\s*return [^;{}\\n]+;?\\s*\\}|\\b(?:const|let|var)\\s+[\\w$]+\\s*=\\s*(\\([^)]*\\)|[a-zA-Z_$][\\w$]*)\\s*=>\\s*[^{\\n]+$"
+scope: "tool:edit(*.ts), tool:edit(*.tsx), tool:write(*.ts), tool:write(*.tsx)"
+interruptMode: never
+---
+
+Do not extract a function whose whole body is one expression or one `return`. Inline it unless the name creates a durable contract.
+
+## Why
+
+- One-line wrappers hide no real behavior.
+- Readers must jump to verify trivial code.
+- The signature freezes a shape too early.
+- Search and type flow work better with inline expressions.
+
+## Avoid
+
+```typescript
+// Bad — pure rename, no behavior added.
+function isEmpty(value: string): boolean {
+	return value.length === 0;
+}
+
+const getDisplayName = (user: User) => user.profile.displayName;
+
+function double(value: number) {
+	return value * 2;
+}
+
+if (isEmpty(name)) { ... }
+```
+
+## Use
+
+```typescript
+if (name.length === 0) { ... }
+const displayName = user.profile.displayName;
+const doubled = value * 2;
+```
+
+## Allowed tiny functions
+
+- Three or more call sites need lockstep behavior.
+- Exported name represents a stable domain concept.
+- Callback identity matters.
+- Type guard preserves narrowing.
+- Public API, test seam, or DI boundary needs indirection.
+- Names a non-obvious formula or magic-constant computation that the inlined expression would not explain on its own.
+
+If none apply, inline it.

package/src/discovery/builtin-rules/ts-promise-with-resolvers.md

@@ -0,0 +1,65 @@
+---
+description: Use Promise.withResolvers() instead of new Promise() constructor
+condition: "new Promise\\("
+scope: "tool:edit(*.ts), tool:edit(*.tsx), tool:write(*.ts), tool:write(*.tsx)"
+---
+
+Use `Promise.withResolvers()` instead of `new Promise((resolve, reject) => ...)`. It keeps control flow linear and exposes typed resolver functions without callback nesting.
+
+## Basic operation
+
+```typescript
+// Bad
+function delay(ms: number): Promise<void> {
+	return new Promise(resolve => {
+		setTimeout(resolve, ms);
+	});
+}
+
+// Good
+function delay(ms: number): Promise<void> {
+	const { promise, resolve } = Promise.withResolvers<void>();
+	setTimeout(resolve, ms);
+	return promise;
+}
+```
+
+## Event-based completion
+
+```typescript
+// Bad
+function waitForEvent(emitter: EventEmitter, event: string): Promise<unknown> {
+	return new Promise((resolve, reject) => {
+		emitter.once(event, resolve);
+		emitter.once("error", reject);
+	});
+}
+
+// Good
+function waitForEvent(emitter: EventEmitter, event: string): Promise<unknown> {
+	const { promise, resolve, reject } = Promise.withResolvers<unknown>();
+	emitter.once(event, resolve);
+	emitter.once("error", reject);
+	return promise;
+}
+```
+
+## Stored resolver
+
+```typescript
+class Gate {
+	#promise: Promise<void>;
+	#resolve: () => void;
+
+	constructor() {
+		const { promise, resolve } = Promise.withResolvers<void>();
+		this.#promise = promise;
+		this.#resolve = resolve;
+	}
+
+	open(): void { this.#resolve(); }
+	wait(): Promise<void> { return this.#promise; }
+}
+```
+
+Use the constructor only when an API specifically requires the executor form.

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/builtin-rules/ts-set-map.md

@@ -0,0 +1,28 @@
+---
+description: Prefer Record<K, V> for small static literals; use Set/Map for anything dynamic
+condition: "\\bnew\\s+(Set|Map)\\b"
+scope: "tool:edit(**/*.{ts,tsx}), tool:write(**/*.{ts,tsx})"
+interruptMode: never
+---
+
+Use `Record<K, V>` / `Record<K, true>` for small, static string-keyed lookup tables.
+
+Use `Set` / `Map` when keys are dynamic, non-string, inserted or deleted at runtime, or when code needs `.size`, `.clear()`, stable insertion order, or iterator APIs.
+
+```typescript
+// Static literal → Record
+const LABEL_BY_KIND: Record<string, string> = {
+	text: "Text",
+	json: "JSON",
+	binary: "Binary",
+};
+
+// Dynamic membership → Set
+const seen = new Set<string>();
+for (const item of items) {
+	if (seen.has(item.id)) continue;
+	seen.add(item.id);
+}
+```
+
+Small fixed table? `Record`. Runtime collection? `Set` / `Map`.