oma-coding-agent 1.1.4

package/src/discovery/builtin-defaults.ts

@@ -0,0 +1,39 @@
+/**
+ * Builtin Defaults Provider
+ *
+ * Ships a curated set of default rules (mostly TTSR conventions) embedded into
+ * the binary. Registered at the lowest priority so any user/project/tool rule
+ * with the same `name` overrides the bundled copy (first-wins dedup by name).
+ *
+ * Users disable bundled rules three ways:
+ *   - flip `ttsr.builtinRules` off (drops the whole set),
+ *   - list a name in `ttsr.disabledRules` (drops one rule),
+ *   - define a same-named rule in any higher-priority source (overrides it).
+ * The first two are enforced in `bucketRules` (see capability/rule-buckets.ts).
+ */
+import { registerProvider } from "../capability";
+import { BUILTIN_DEFAULTS_PROVIDER_ID, type Rule, ruleCapability } from "../capability/rule";
+import type { LoadContext, LoadResult } from "../capability/types";
+import { BUILTIN_RULE_SOURCES } from "./builtin-rules";
+import { buildRuleFromMarkdown, createSourceMeta } from "./helpers";
+
+const DISPLAY_NAME = "Builtin Defaults";
+// Lowest priority: every other rule provider wins a name conflict.
+const PRIORITY = 1;
+
+async function loadRules(_ctx: LoadContext): Promise<LoadResult<Rule>> {
+	const items = BUILTIN_RULE_SOURCES.map(({ name, content }) => {
+		const virtualPath = `${BUILTIN_DEFAULTS_PROVIDER_ID}:${name}.md`;
+		const source = createSourceMeta(BUILTIN_DEFAULTS_PROVIDER_ID, virtualPath, "user");
+		return buildRuleFromMarkdown(name, content, virtualPath, source, { ruleName: name });
+	});
+	return { items };
+}
+
+registerProvider<Rule>(ruleCapability.id, {
+	id: BUILTIN_DEFAULTS_PROVIDER_ID,
+	displayName: DISPLAY_NAME,
+	description: "Default rules shipped with the agent (disable via ttsr.builtinRules / ttsr.disabledRules)",
+	priority: PRIORITY,
+	load: loadRules,
+});

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

@@ -0,0 +1,63 @@
+/**
+ * Bundled default rules shipped with the coding agent.
+ *
+ * Each markdown source is embedded via `with { type: "text" }` so it survives
+ * `bun build --compile` (the compiled binary ships no loose rule files; only
+ * the embedded text). The native source/tarball installs read the same modules.
+ *
+ * Registered by the lowest-priority `builtin-defaults` rule provider so any
+ * user/project/tool rule with the same name overrides the bundled copy.
+ */
+
+import noHallucinatedApis from "./low-end/no-hallucinated-apis.md" with { type: "text" };
+import noHallucinatedPaths from "./low-end/no-hallucinated-paths.md" with { type: "text" };
+import noPrematureCompletion from "./low-end/no-premature-completion.md" with { type: "text" };
+import rsBoxLeak from "./rs-box-leak.md" with { type: "text" };
+import rsFuturePrelude from "./rs-future-prelude.md" with { type: "text" };
+import rsLazylock from "./rs-lazylock.md" with { type: "text" };
+import rsMatchErgonomics from "./rs-match-ergonomics.md" with { type: "text" };
+import rsParkingLot from "./rs-parking-lot.md" with { type: "text" };
+import rsResultType from "./rs-result-type.md" with { type: "text" };
+import tsBareCatch from "./ts-bare-catch.md" with { type: "text" };
+import tsImportType from "./ts-import-type.md" with { type: "text" };
+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 tsNoInlineCastAccess from "./ts-no-inline-cast-access.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). */
+export interface BuiltinRuleSource {
+	name: string;
+	content: string;
+}
+
+/** All bundled default rules, ordered by name. */
+export const BUILTIN_RULE_SOURCES: readonly BuiltinRuleSource[] = [
+	{ name: "rs-box-leak", content: rsBoxLeak },
+	{ name: "rs-future-prelude", content: rsFuturePrelude },
+	{ name: "rs-lazylock", content: rsLazylock },
+	{ name: "rs-match-ergonomics", content: rsMatchErgonomics },
+	{ name: "rs-parking-lot", content: rsParkingLot },
+	{ name: "rs-result-type", content: rsResultType },
+	{ name: "ts-bare-catch", content: tsBareCatch },
+	{ name: "ts-import-type", content: tsImportType },
+	{ name: "ts-no-any", content: tsNoAny },
+	{ name: "ts-no-deprecated-leftovers", content: tsNoDeprecatedLeftovers },
+	{ name: "ts-no-dynamic-import", content: tsNoDynamicImport },
+	{ name: "ts-no-inline-cast-access", content: tsNoInlineCastAccess },
+	{ 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 },
+	{ name: "no-hallucinated-paths", content: noHallucinatedPaths },
+	{ name: "no-hallucinated-apis", content: noHallucinatedApis },
+	{ name: "no-premature-completion", content: noPrematureCompletion },
+];

package/src/discovery/builtin-rules/low-end/no-hallucinated-apis.md

@@ -0,0 +1,14 @@
+---
+description: "Enforce tool usage for code operations"
+condition: "(?:函数|function|API|模块|module|类|class)"
+scope: "text"
+interruptMode: "always"
+---
+
+When referencing code elements, you MUST use the appropriate tools:
+
+- Use `search` to find functions, classes, or modules
+- Use `lsp` to get code intelligence
+- Use `read` to examine source files
+
+NEVER claim something exists or doesn't exist without using tools to verify.

package/src/discovery/builtin-rules/low-end/no-hallucinated-paths.md

@@ -0,0 +1,14 @@
+---
+description: "Enforce tool usage for file operations"
+condition: "(?:文件|file|路径|path|目录|directory)"
+scope: "text"
+interruptMode: "always"
+---
+
+When referencing files or paths, you MUST use the appropriate tools:
+
+- Use `read` to check if a file exists and read its contents
+- Use `find` to locate files
+- Use `search` to find content within files
+
+NEVER claim a file exists or doesn't exist without using tools to verify.

package/src/discovery/builtin-rules/low-end/no-premature-completion.md

@@ -0,0 +1,14 @@
+---
+description: "Enforce thorough task completion"
+condition: "(?:完成|done|complete|finished|结束)"
+scope: "text"
+interruptMode: "always"
+---
+
+Before claiming a task is complete, you MUST:
+
+1. List the steps you took
+2. Show evidence from tool outputs
+3. Verify the result matches the request
+
+NEVER claim completion without evidence.

package/src/discovery/builtin-rules/rs-box-leak.md

@@ -0,0 +1,48 @@
+---
+description: Never use Box::leak - it intentionally leaks memory
+condition: "Box::leak"
+scope: "tool:edit(*.rs), tool:write(*.rs)"
+---
+
+Never use `Box::leak` to satisfy a lifetime. It intentionally leaks the allocation for the rest of the process.
+
+## Why
+
+- The allocation is never freed.
+- It hides ownership bugs.
+- It turns lifetime errors into process lifetime growth.
+- It makes tests pass while production memory grows.
+
+## Use instead
+
+| Need | Use |
+| --- | --- |
+| Shared async/thread data | `Arc<T>` or owned values |
+| Global lazy state | `LazyLock<T>` or `OnceLock<T>` |
+| Text escaping a scope | `String` / `Arc<str>` |
+| `'static` callback | `move` closure with owned captures |
+| FFI pointer | Explicit owner that frees on drop |
+
+## Examples
+
+```rust
+// Bad — leaking to manufacture 'static.
+fn label(id: u64) -> &'static str {
+    Box::leak(Box::new(format!("item_{id}")))
+}
+
+// Good — return owned data.
+fn label(id: u64) -> String {
+    format!("item_{id}")
+}
+
+// Bad — leaking before spawn.
+let state = Box::leak(Box::new(state));
+tokio::spawn(async move { use_state(state) });
+
+// Good — share owned state.
+let state = Arc::new(state);
+tokio::spawn(async move { use_state(&state) });
+```
+
+If `Box::leak` looks necessary, fix ownership instead.

package/src/discovery/builtin-rules/rs-future-prelude.md

@@ -0,0 +1,23 @@
+---
+description: Use Future not std::future::Future - it's in the prelude
+condition: "std::future::Future"
+scope: "tool:edit(*.rs), tool:write(*.rs)"
+---
+
+Use `Future` directly instead of `std::future::Future` in type positions.
+
+Rust 2024 includes `Future` in the standard prelude. Older editions can import it once with `use std::future::Future;`. Repeating the fully qualified path makes signatures harder to read without adding safety.
+
+## Examples
+
+```rust
+// Bad — fully qualified in every signature.
+fn fetch() -> impl std::future::Future<Output = Result<Data>> { ... }
+fn poll(fut: Pin<&mut dyn std::future::Future<Output = i32>>) { ... }
+
+// Good — use the prelude or one import.
+fn fetch() -> impl Future<Output = Result<Data>> { ... }
+fn poll(fut: Pin<&mut dyn Future<Output = i32>>) { ... }
+```
+
+Pre-2024 edition? Add `use std::future::Future;` at the top.

package/src/discovery/builtin-rules/rs-lazylock.md

@@ -0,0 +1,51 @@
+---
+description: Prefer std::sync::LazyLock over OnceLock and once_cell
+condition:
+  - "once_cell::"
+  - "OnceLock::new"
+scope: "tool:edit(*.rs), tool:write(*.rs)"
+---
+
+Prefer `std::sync::LazyLock` over `OnceLock` and the `once_cell` crate when the initializer is known at declaration time.
+
+`LazyLock` stores the cell and initializer together. There is no separate `init()` function, no repeated `get_or_init`, and no missing initialization path.
+
+## once_cell → std
+
+```rust
+// Before
+use once_cell::sync::Lazy;
+static CONFIG: Lazy<String> = Lazy::new(|| "value".to_string());
+
+// After
+use std::sync::LazyLock;
+static CONFIG: LazyLock<String> = LazyLock::new(|| "value".to_string());
+```
+
+## OnceLock → LazyLock
+
+```rust
+// Before — fixed initializer hidden in accessor.
+use std::sync::OnceLock;
+static SETTINGS: OnceLock<Settings> = OnceLock::new();
+fn settings() -> &'static Settings {
+    SETTINGS.get_or_init(Settings::load)
+}
+
+// After — initializer lives with the static.
+use std::sync::LazyLock;
+static SETTINGS: LazyLock<Settings> = LazyLock::new(Settings::load);
+```
+
+## Keep OnceLock when runtime input is required
+
+```rust
+use std::sync::OnceLock;
+static DATABASE: OnceLock<Database> = OnceLock::new();
+
+fn init_database(url: &str) {
+    let _ = DATABASE.set(Database::connect(url));
+}
+```
+
+Do not add `once_cell` for new code. Use the standard library equivalent.

package/src/discovery/builtin-rules/rs-match-ergonomics.md

@@ -0,0 +1,67 @@
+---
+description: Use match ergonomics instead of ref/ref mut patterns
+condition:
+  - "\\(ref mut "
+  - "\\(ref [a-z_]"
+scope: "tool:edit(*.rs), tool:write(*.rs)"
+---
+
+Use match ergonomics instead of explicit `ref` / `ref mut` patterns. Borrow the scrutinee and let bindings receive references.
+
+## Shared references
+
+```rust
+// Before
+match value {
+    Some(ref item) => println!("{item}"),
+    None => {}
+}
+
+// After
+match &value {
+    Some(item) => println!("{item}"),
+    None => {}
+}
+
+if let Some(item) = &value {
+    println!("{item}");
+}
+```
+
+## Mutable references
+
+```rust
+// Before
+match value {
+    Some(ref mut item) => *item += 1,
+    None => {}
+}
+
+// After
+match &mut value {
+    Some(item) => *item += 1,
+    None => {}
+}
+
+if let Some(item) = &mut value {
+    *item += 1;
+}
+```
+
+## Result
+
+```rust
+// Before
+match result {
+    Ok(ref data) => println!("{data}"),
+    Err(ref err) => eprintln!("{err}"),
+}
+
+// After
+match &result {
+    Ok(data) => println!("{data}"),
+    Err(err) => eprintln!("{err}"),
+}
+```
+
+Modern Rust rarely needs `ref` in patterns. Borrow the value being matched.

package/src/discovery/builtin-rules/rs-parking-lot.md

@@ -0,0 +1,44 @@
+---
+description: Use parking_lot instead of std::sync for Mutex/RwLock
+condition:
+  - "\\.lock\\(\\)\\.unwrap\\(\\)"
+  - "\\.read\\(\\)\\.unwrap\\(\\)"
+  - "\\.write\\(\\)\\.unwrap\\(\\)"
+scope: "tool:edit(*.rs), tool:write(*.rs)"
+---
+
+Use `parking_lot::{Mutex, RwLock}` instead of `std::sync::{Mutex, RwLock}` when code immediately unwraps lock results.
+
+## Why
+
+- `lock()`, `read()`, and `write()` return guards directly.
+- No poisoning error path to unwrap.
+- Guards are smaller and faster in common contention cases.
+- The call site shows locking, not error handling boilerplate.
+
+## Migration
+
+```rust
+// Before
+use std::sync::Mutex;
+let data = Mutex::new(Vec::new());
+let guard = data.lock().unwrap();
+
+// After
+use parking_lot::Mutex;
+let data = Mutex::new(Vec::new());
+let guard = data.lock();
+```
+
+## Equivalents
+
+| std::sync | parking_lot |
+| --- | --- |
+| `Mutex<T>` | `Mutex<T>` |
+| `RwLock<T>` | `RwLock<T>` |
+| `Condvar` | `Condvar` |
+| `Once` | `Once` |
+
+## Keep async locks async
+
+Use `tokio::sync::Mutex` / `tokio::sync::RwLock` when a guard is held across `.await` or the lock belongs to async coordination.

package/src/discovery/builtin-rules/rs-result-type.md

@@ -0,0 +1,19 @@
+---
+description: Result type aliases must include a defaulted error type parameter
+condition: "type\\s+Result<[A-Za-z_]\\w*>\\s*="
+scope: "tool:edit(*.rs), tool:write(*.rs)"
+---
+
+`Result` aliases must expose the error type as a defaulted parameter.
+
+```rust
+pub type Result<T, E = anyhow::Error> = std::result::Result<T, E>;
+```
+
+Never write:
+
+```rust
+type Result<T> = std::result::Result<T, anyhow::Error>;
+```
+
+The default keeps common call sites short while preserving escape hatches for precise errors.

package/src/discovery/builtin-rules/ts-bare-catch.md

@@ -0,0 +1,38 @@
+---
+description: Use bare `catch {` when the error binding is unused
+condition: "catch \\(_"
+scope: "tool:edit(*.ts), tool:edit(*.tsx), tool:write(*.ts), tool:write(*.tsx)"
+---
+
+Use bare `catch {}` when the caught value is unused. An underscore-prefixed binding adds noise and still allocates a local name.
+
+## Replace
+
+```typescript
+// Bad
+try {
+	await loadConfig();
+} catch (_err) {
+	return null;
+}
+
+// Good
+try {
+	await loadConfig();
+} catch {
+	return null;
+}
+```
+
+## Keep a real name when used
+
+```typescript
+try {
+	await saveConfig();
+} catch (err) {
+	logger.error("save failed", { err });
+	throw err;
+}
+```
+
+Unused error? Bare `catch`. Used error? Name it for what it carries.

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("arktype").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 "arktype";
+
+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,65 @@
+---
+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)"
+---
+
+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,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.