@kr78/pi-coding-agent 17.2.10

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

@@ -0,0 +1,66 @@
+---
+description: "Never use `any` in TypeScript annotations or assertions — use `unknown`, generics, a schema parse at trust boundaries, or the actual type"
+condition: ": any|as any"
+scope: "tool:edit(*.ts), tool:edit(*.tsx), tool:write(*.ts), tool:write(*.tsx)"
+interruptMode: never
+---
+
+Never use `: any` or `as any`. They disable type checking exactly where the boundary needs precision.
+
+## Use instead
+
+- `unknown` for unvalidated input.
+- A schema parse (Zod, Valibot, …; e.g. Zod v4 when it is already in the project) for untrusted or external input — validate once, then consume a typed value.
+- 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.id; // `in` narrowing types this as unknown — no cast needed
+		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;
+```
+
+## Choosing: guard vs schema vs unchecked cast
+
+| Situation | Reach for |
+| --- | --- |
+| Data from outside your control — network/RPC, parsed JSON, config files, env vars, CLI/IPC, persisted blobs — or a shape reused across the codebase | **Schema parse** (Zod/Valibot/…): runtime validation, typed output, and a clear error on bad shape |
+| In-process value the compiler merely lost track of — an `unknown` from a generic, a union to discriminate, a one-off read of a field or two | **Type guard** (`in` / `typeof`): no dependency, but it only checks what you write, so keep the checked surface small |
+| You genuinely know more than the compiler *and* a runtime check is impossible or meaningless — a well-known DOM node (`as HTMLElement`), structurally-identical types inference can't unify, a library type that is wrong or unexpressible, `as const` | **Unchecked cast** (`as` / `as unknown as T`): assign to a named const with a one-line reason; never for raw external input |
+
+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,45 @@
+---
+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)"
+interruptMode: never
+---
+
+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,40 @@
+---
+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)"
+interruptMode: never
+---
+
+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-inline-cast-access.md

@@ -0,0 +1,56 @@
+---
+description: "Don't assert an inline object type and immediately read a property — `(x as { y: T }).y` trusts an unchecked shape; validate with a schema parse at trust boundaries, narrow with `in`/`typeof`, or use a validated named type"
+scope: "tool:edit(*.{ts,tsx,mts,cts}), tool:write(*.{ts,tsx,mts,cts})"
+interruptMode: never
+astCondition:
+  - "($X as { $$$BODY }).$PROP"
+  - "($X as { $$$BODY })?.$PROP"
+  - "($X as { $$$BODY })[$IDX]"
+---
+
+**Don't assert an inline object type just to read a property.** `(value as { content: unknown }).content` fabricates a shape the compiler never verified, then trusts it for exactly one access. If `value` isn't that shape, the read is silently wrong and no type error ever fires.
+
+## Why it's wrong
+
+- The cast is an unchecked assertion — it suppresses the type error instead of proving the shape.
+- It localizes the lie to one expression, so the next reader can't tell whether the value was ever validated.
+- It almost always stands in for the real fix: runtime narrowing or a validated type at the boundary.
+
+## Avoid
+
+```ts
+const content = (value as { content: unknown }).content;
+const id = (resp as { data: { id: string } }).data.id;
+const name = (payload as { name?: string })?.name;
+const flag = (opts as { enabled: boolean })["enabled"];
+```
+
+## Use
+
+Prefer a schema parse at the boundary when a validator is available — validate
+once, then read from a fully typed value:
+
+```ts
+import { type } from "@oh-my-pi/omptype";
+
+const Resp = type({ data: { id: "string" } });
+
+const resp = Resp.assert(raw); // throws on bad input; resp.data.id is typed string
+const id = resp.data.id;
+```
+
+For a one-off read of a single field, narrow with `in` / `typeof` so the access is actually checked — TypeScript infers `unknown` for the property after `"content" in value`:
+
+```ts
+if (value && typeof value === "object" && "content" in value) {
+	const content = value.content; // unknown — validate before use
+}
+```
+
+## Choosing: guard vs schema vs unchecked cast
+
+| Situation | Reach for |
+| --- | --- |
+| Data from outside your control — network/RPC, parsed JSON, config files, env vars, CLI/IPC, persisted blobs — or a shape reused across the codebase | **Schema parse** (Zod/Valibot/…): runtime validation, typed output, and a clear error on bad shape |
+| In-process value the compiler merely lost track of — an `unknown` from a generic, a union to discriminate, a one-off read of a field or two | **Type guard** (`in` / `typeof`): no dependency, but it only checks what you write, so keep the checked surface small |
+| You genuinely know more than the compiler *and* a runtime check is impossible or meaningless — a well-known DOM node (`as HTMLElement`), structurally-identical types inference can't unify, a library type that's wrong or unexpressible, `as const` | **Unchecked cast** (`as`): assign to a named const with a one-line reason; never for raw external input, never inlined into a member access |

package/src/discovery/builtin-rules/ts-no-local-is-record.md

@@ -0,0 +1,48 @@
+---
+description: "Never use isRecord"
+condition:
+  - "\\bfunction\\s+isRecord(?:\\s*<[^>]*>)?\\s*\\("
+  - "\\b(?:const|let|var)\\s+isRecord\\b\\s*(?::[\\s\\S]{0,300}?)?=\\s*(?:async\\s+)?(?:function\\b|(?:<[^>\\n]*>\\s*)?(?:\\([^)]*\\)|[A-Za-z_$][\\w$]*)\\s*(?::[\\s\\S]{0,300}?)?=>)"
+scope: "tool:edit(*.{ts,tsx,mts,cts}), tool:write(*.{ts,tsx,mts,cts})"
+interruptMode: never
+---
+
+## Why it's wrong
+
+- A `Record<string, unknown>` guard proves only an object, not its fields.
+- It's either unnecessarily complicated, or not strong enough.
+- Repeated guards hide the actual data contract from readers and TypeScript.
+
+## Use
+
+`isRecord` narrows values to `Record<string, unknown>`; each field remains `unknown`.
+
+For network, config, IPC, persisted, or reused data shapes, parse once at the boundary with the project's schema validator and consume its named output type:
+
+```typescript
+const Config = z.object({ retries: z.number().int().nonnegative() });
+type Config = z.infer<typeof Config>;
+
+const config = Config.parse(raw);
+```
+
+If the runtime shape is uncertain, check the properties you use with `typeof`, `Array.isArray`, `in`, or a discriminant. If an existing invariant guarantees the shape, assert the named type at that boundary instead of duplicating a guard:
+
+```typescript
+const config = value as Config;
+```
+
+## Avoid
+
+```typescript
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+	value !== null && typeof value === "object";
+```
+
+## Exceptions
+
+A standalone package without a shared type-guard module may define its single canonical guard. Export it from the package's type-guard module; never recreate it at individual call sites.

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)"
+interruptMode: never
+---
+
+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
+
+- 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: "(?m)\\{\\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,66 @@
+---
+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)"
+interruptMode: never
+---
+
+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`.