@mrciphersmith/keryx 0.2.9

package/src/gdgraph/treesitter/grammars.ts

@@ -0,0 +1,110 @@
+// Grammar WASM resolution via the Block 0 Asset Resolver (specification.md §8.1;
+// T-B11, A-1..A-7). Grammar assets are pinned in `.metaproject/assets.lock.json`
+// and resolved (sha256-verified on EVERY load) through `resolveAsset` — a
+// tampered/missing grammar ⇒ `null` ⇒ the capability degrades to the regex
+// fallback (AC1.6). This module NEVER touches the network and imports no optional
+// dependency.
+
+import path from "node:path";
+import { loadAssetsLock, registryFromLock } from "../../assets/lock";
+import { resolveAsset } from "../../assets/resolver";
+
+export type GrammarLanguage = "typescript" | "tsx" | "javascript" | "java" | "python";
+
+// The asset id for a language's grammar in `assets.lock.json`.
+export function grammarAssetId(language: GrammarLanguage): string {
+  return `tree-sitter-${language}`;
+}
+
+// Map an extractor language to its parsed-symbol language tag.
+export function symbolLanguage(language: GrammarLanguage): "typescript" | "javascript" | "java" | "python" {
+  if (language === "javascript") return "javascript";
+  if (language === "python") return "python";
+  if (language === "java") return "java";
+  return "typescript";
+}
+
+export interface ResolvedGrammar {
+  language: GrammarLanguage;
+  path: string;
+}
+
+// Resolve a single grammar to a verified on-disk wasm path, or `null` when the
+// asset is absent / fails checksum. `grammarsPath` (config T1) supplies an
+// optional per-id user override directory of `tree-sitter-<lang>.wasm` files.
+export async function resolveGrammar(
+  cwd: string,
+  language: GrammarLanguage,
+  grammarsPath?: string | null,
+): Promise<ResolvedGrammar | null> {
+  const id = grammarAssetId(language);
+  const lock = await loadAssetsLock(cwd);
+  const overrides = grammarsPath
+    ? { [id]: { path: path.join(grammarsPath, `${id}.wasm`) } }
+    : undefined;
+  const registry = registryFromLock(lock, overrides);
+  const resolved = await resolveAsset(registry, id);
+  if (!resolved) {
+    return null;
+  }
+  return { language, path: resolved.path };
+}
+
+// Resolve every requested grammar that is available. Unavailable ones are
+// skipped (not an error) — the adapter is available when at least one resolves.
+export async function resolveGrammars(
+  cwd: string,
+  languages: GrammarLanguage[],
+  grammarsPath?: string | null,
+): Promise<ResolvedGrammar[]> {
+  const resolved: ResolvedGrammar[] = [];
+  for (const language of languages) {
+    const grammar = await resolveGrammar(cwd, language, grammarsPath);
+    if (grammar) {
+      resolved.push(grammar);
+    }
+  }
+  return resolved;
+}
+
+// Normalize config language strings to supported grammar languages.
+export function toGrammarLanguages(languages: string[]): GrammarLanguage[] {
+  const out: GrammarLanguage[] = [];
+  for (const language of languages) {
+    if (
+      language === "typescript" ||
+      language === "tsx" ||
+      language === "javascript" ||
+      language === "java" ||
+      language === "python"
+    ) {
+      if (!out.includes(language as GrammarLanguage)) {
+        out.push(language as GrammarLanguage);
+      }
+    }
+  }
+  return out;
+}
+
+// Choose the grammar for a source file path.
+export function grammarForFile(file: string, available: GrammarLanguage[]): GrammarLanguage | null {
+  const ext = path.extname(file);
+  const preference: GrammarLanguage[] =
+    ext === ".tsx"
+      ? ["tsx", "typescript"]
+      : ext === ".ts"
+        ? ["typescript"]
+        : ext === ".jsx" || ext === ".js" || ext === ".mjs" || ext === ".cjs"
+          ? ["javascript"]
+          : ext === ".java"
+            ? ["java"]
+            : ext === ".py"
+              ? ["python"]
+              : [];
+  for (const language of preference) {
+    if (available.includes(language)) {
+      return language;
+    }
+  }
+  return null;
+}

package/src/gdgraph/treesitter/no-treesitter-import.test.ts

@@ -0,0 +1,51 @@
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { expect, test } from "bun:test";
+
+// AC1.5 (C0-2): `web-tree-sitter` is imported ONLY via `await import()` inside
+// `src/gdgraph/treesitter/adapter.ts`. This is an ADDITIVE, gdgraph-specific
+// assertion layered on the generic `src/capability/no-optional-imports.test.ts`
+// (which already scans every optionalDependencies package across `src/`).
+
+const SRC_ROOT = fileURLToPath(new URL("../../", import.meta.url));
+const ADAPTER = path.join(SRC_ROOT, "gdgraph", "treesitter", "adapter.ts");
+
+async function tsFiles(dir: string): Promise<string[]> {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const files: string[] = [];
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await tsFiles(full)));
+    } else if (entry.isFile() && entry.name.endsWith(".ts")) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+test("no static import of web-tree-sitter anywhere in src/", async () => {
+  const files = await tsFiles(SRC_ROOT);
+  const staticImport = /\b(?:import|export)\b[^()]*?\bfrom\s*['"]web-tree-sitter['"]|\bimport\s*['"]web-tree-sitter['"]|\brequire\s*\(\s*['"]web-tree-sitter['"]\s*\)/;
+  const violations: string[] = [];
+  for (const file of files) {
+    const content = await readFile(file, "utf8");
+    if (staticImport.test(content)) {
+      violations.push(path.relative(SRC_ROOT, file));
+    }
+  }
+  expect(violations).toEqual([]);
+});
+
+test("adapter declares web-tree-sitter as a lazy optionalDependency, never a static import", async () => {
+  const content = await readFile(ADAPTER, "utf8");
+  // The dep is loaded lazily by the seam (`await import(spec.optionalDependency)`
+  // in capability/seam.ts) using the id the adapter declares here.
+  expect(content).toContain('optionalDependency: "web-tree-sitter"');
+  // The adapter never statically imports the dep (types are structural).
+  expect(/from\s*['"]web-tree-sitter['"]/.test(content)).toBe(false);
+
+  const seam = await readFile(path.join(SRC_ROOT, "capability", "seam.ts"), "utf8");
+  expect(seam).toContain("await import(spec.optionalDependency)");
+});

package/src/gdgraph/treesitter/resolve-calls.test.ts

@@ -0,0 +1,38 @@
+import { expect, test } from "bun:test";
+import { resolveCrossFileCalls } from "./extract";
+import type { CallEdge, SymbolNode } from "../types";
+
+function sym(id: string, name: string, path: string): SymbolNode {
+  return { id, kind: "function", path, name, container: null, startLine: 1, endLine: 2, language: "typescript" };
+}
+function unresolved(from: string, to: string): CallEdge {
+  return { id: `u:${from}=>${to}`, from, to, kind: "unresolved-call", resolved: false };
+}
+
+test("resolves a cross-file member call to a globally-unique symbol", () => {
+  const symbols = [sym("src/a.ts#runPipeline", "runPipeline", "src/a.ts"), sym("src/b.ts#caller", "caller", "src/b.ts")];
+  // caller (in b.ts) calls `TasksApi.runPipeline` — cross-file, unresolved by per-file extraction
+  const calls = [unresolved("src/b.ts#caller", "TasksApi.runPipeline")];
+  const out = resolveCrossFileCalls(symbols, calls);
+  expect(out).toHaveLength(1);
+  expect(out[0]).toMatchObject({ from: "src/b.ts#caller", to: "src/a.ts#runPipeline", kind: "calls", resolved: true });
+});
+
+test("leaves an ambiguous name (multiple defs) unresolved — never guesses", () => {
+  const symbols = [
+    sym("src/a.ts#clonePipeline", "clonePipeline", "src/a.ts"),
+    sym("src/b.ts#clonePipeline", "clonePipeline", "src/b.ts"),
+    sym("src/c.ts#caller", "caller", "src/c.ts"),
+  ];
+  const out = resolveCrossFileCalls(symbols, [unresolved("src/c.ts#caller", "x.clonePipeline")]);
+  expect(out[0]?.kind).toBe("unresolved-call");
+});
+
+test("drops self-edges and passes resolved calls through unchanged", () => {
+  const symbols = [sym("src/a.ts#f", "f", "src/a.ts")];
+  const resolved: CallEdge = { id: "c", from: "src/a.ts#g", to: "src/a.ts#f", kind: "calls", resolved: true };
+  const out = resolveCrossFileCalls(symbols, [unresolved("src/a.ts#f", "f"), resolved]);
+  // the self-call f->f is not added as a resolved edge; the pre-resolved call stays
+  expect(out.some((c) => c.kind === "calls" && c.from === "src/a.ts#f" && c.to === "src/a.ts#f")).toBe(false);
+  expect(out).toContainEqual(resolved);
+});

package/src/gdgraph/types.ts

@@ -0,0 +1,63 @@
+export type GraphNode = {
+  id: string;
+  kind: "file" | "asset";
+  path: string;
+  language: "typescript" | "javascript" | "java" | "python" | "asset";
+};
+
+export type GraphEdge = {
+  id: string;
+  from: string;
+  to: string;
+  kind: "imports" | "asset" | "unresolved";
+  specifier: string;
+};
+
+export type GraphData = {
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+  // B1 symbol layer — present only when tree-sitter enrichment ran and wrote
+  // `storage/symbols.jsonl` / `storage/calls.jsonl`. Missing ⇒ omitted (never an
+  // error; `loadGraph` loads them only if present). File-level consumers ignore
+  // these fields, keeping the legacy graph shape backward-compatible.
+  symbols?: SymbolNode[];
+  calls?: CallEdge[];
+};
+
+// --- B1 symbol layer types (additive; only materialized in symbols.jsonl /
+// calls.jsonl when the `gdgraph.treesitter` capability is active). ---
+
+export type SymbolKind = "function" | "class" | "method" | "interface";
+
+export type SymbolNode = {
+  // "<path>#<Container>.<name>" (+ "@<startLine>" on name collision).
+  id: string;
+  kind: SymbolKind;
+  // Owning file (matches a file GraphNode.path).
+  path: string;
+  name: string;
+  // Enclosing class/namespace, or null.
+  container: string | null;
+  // 1-based; positional, for stable disambiguation.
+  startLine: number;
+  endLine: number;
+  language: "typescript" | "javascript" | "java" | "python";
+  // Rendered for repomap.
+  signature?: string;
+};
+
+export type CallEdge = {
+  id: string;
+  // SymbolNode.id of caller (or file path when caller unknown).
+  from: string;
+  // SymbolNode.id of callee, or raw callee text when unresolved.
+  to: string;
+  // "defines": file → symbol containment.
+  kind: "calls" | "defines" | "unresolved-call";
+  resolved: boolean;
+};
+
+export type SymbolLayer = {
+  symbols: SymbolNode[];
+  calls: CallEdge[];
+};

package/src/gdskills/bundled/rules/core/api-contracts.mdc

@@ -0,0 +1,148 @@
+---
+description: "API contract rules: OpenAPI-first design, semantic versioning, no breaking changes without major version bump, contract testing. Use when designing, modifying, or consuming HTTP APIs."
+alwaysApply: false
+---
+
+# API Contracts
+
+## Purpose
+Prevent silent breaking changes, version drift, and undocumented API behaviour. Enforce OpenAPI-first design and strict versioning discipline.
+
+## When To Apply
+Apply when creating new API endpoints, modifying existing endpoints, changing DTOs/schemas, or writing API client code.
+
+---
+
+## Core Principle: Contract Before Code
+
+The OpenAPI spec (or equivalent schema) is the source of truth. Code is generated from or validated against the spec — not the other way around.
+
+```
+1. Design the endpoint in OpenAPI/schema first
+2. Review the contract for breaking changes
+3. Generate or update types/validators from the spec
+4. Implement the handler
+5. Write contract tests that validate the spec is honoured
+```
+
+---
+
+## Rules
+
+### Rule 1: OpenAPI-First for New Endpoints
+Every new HTTP endpoint MUST have an OpenAPI 3.x definition before the handler is implemented:
+
+```yaml
+# Required fields for every endpoint definition
+paths:
+  /users/{id}:
+    get:
+      operationId: getUser          # unique, stable identifier
+      summary: Get user by ID
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema: { type: string, format: uuid }
+      responses:
+        '200':
+          description: User found
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/User' }
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+```
+
+**Required for every endpoint:**
+- `operationId` (stable, unique)
+- All path/query/header parameters documented
+- All response codes documented (including 4xx, 5xx)
+- Request body schema referenced (not inlined) for reuse
+
+### Rule 2: Semantic Versioning for APIs
+
+| Change Type | Version Impact | Action Required |
+|---|---|---|
+| Add optional field to response | None / patch | Safe — backwards compatible |
+| Add optional field to request | None / patch | Safe — old clients omit it |
+| Add new endpoint | Minor bump | Document in changelog |
+| Make optional field required | **Major bump** | Breaking change |
+| Remove field from response | **Major bump** | Breaking change |
+| Rename field | **Major bump** | Breaking change |
+| Change field type | **Major bump** | Breaking change |
+| Remove endpoint | **Major bump** | Deprecate first, remove in next major |
+
+**Breaking change protocol:**
+1. Add deprecation notice to old version (`deprecated: true` in OpenAPI)
+2. Implement new version at `/v{N+1}/...` or with new operationId
+3. Run old version in parallel for ≥1 release cycle
+4. Remove old version only after clients have migrated
+
+### Rule 3: Contract Testing
+Every public API endpoint MUST have at least one contract test that:
+- Validates the response shape matches the OpenAPI schema
+- Tests the error responses (at minimum: 400, 404, 401 where applicable)
+- Uses schema validation, not string matching
+
+```typescript
+// Example: contract test using a schema validator
+describe('GET /users/:id contract', () => {
+  it('returns User schema on 200', async () => {
+    const res = await request(app).get('/users/valid-id');
+    expect(res.status).toBe(200);
+    expect(res.body).toMatchSchema(UserSchema); // validated against OpenAPI
+  });
+
+  it('returns 404 with NotFound schema on unknown id', async () => {
+    const res = await request(app).get('/users/nonexistent');
+    expect(res.status).toBe(404);
+    expect(res.body).toMatchSchema(NotFoundSchema);
+  });
+});
+```
+
+### Rule 4: No Undocumented Fields
+Every field in a request or response body MUST appear in the schema. Fields not in the schema must be stripped from responses (`additionalProperties: false` in JSON Schema).
+
+### Rule 5: Consistent Error Schema
+All error responses must use the same envelope schema:
+
+```typescript
+interface ApiError {
+  code: string;       // machine-readable, e.g. "USER_NOT_FOUND"
+  message: string;    // human-readable
+  details?: unknown;  // optional structured context
+  requestId: string;  // for traceability
+}
+```
+
+Never return raw Error objects, stack traces, or ORM error messages to API consumers.
+
+### Rule 6: Idempotency Keys for Mutations
+POST/PUT/PATCH endpoints that create or modify state MUST support idempotency via `Idempotency-Key` header or a stable `clientId` in the body. This prevents duplicate operations on network retry.
+
+---
+
+## Iron Laws
+
+**IRON LAW 1: NO breaking change may be deployed without a major version bump and a deprecation period.**
+**IRON LAW 2: The OpenAPI spec is updated BEFORE the implementation — not after as documentation.**
+**IRON LAW 3: Error responses MUST use the standard ApiError envelope — no raw exceptions, no ad-hoc shapes.**
+
+---
+
+## Red Flags — Stop and re-read this rule if you are thinking:
+
+| Rationalization | Why it's wrong |
+|---|---|
+| "It's just adding a field, that's not breaking" | Removing a field later will be breaking — document it now to establish the contract |
+| "The spec can wait, I'll document it later" | Specs written after code document what the code does, not what it should do — bugs get documented too |
+| "Renaming a field is internal, consumers will adapt" | Consumers have no way to know a field was renamed — this silently breaks every client |
+| "I'll use v2 later if needed, for now v1 is fine" | Delaying versioning means v1 can never be changed without breaking consumers |
+| "Contract tests slow down development" | Contract tests catch breaking changes before they reach consumers — not after |
+| "The error format doesn't matter as long as the status code is right" | Status codes alone are insufficient for automated error handling — codes and schemas matter |
+
+**IRON LAW: A BREAKING CHANGE WITHOUT A VERSION BUMP IS A PRODUCTION INCIDENT WAITING TO HAPPEN.**

package/src/gdskills/bundled/rules/core/async-patterns.mdc

@@ -0,0 +1,185 @@
+---
+description: "Async patterns: Promise.all for parallelism, no unhandled rejections, mandatory timeouts for external calls, no blocking the event loop. Use when writing async/await code, parallel operations, or queue consumers."
+alwaysApply: false
+---
+
+# Async Patterns
+
+## Purpose
+Prevent common async pitfalls: sequential execution where parallel is safe, unhandled promise rejections, missing timeouts, and event loop blockage.
+
+## When To Apply
+Apply when writing any `async`/`await` code, calling external services, processing queues, or coordinating multiple async operations.
+
+---
+
+## Rules
+
+### Rule 1: Use Promise.all for Independent Operations
+
+Sequential await for independent operations wastes time. Run them in parallel.
+
+```typescript
+// BAD — sequential: takes 300ms (100 + 100 + 100)
+const user = await fetchUser(id);
+const orders = await fetchOrders(id);
+const prefs = await fetchPreferences(id);
+
+// GOOD — parallel: takes 100ms (max of 100, 100, 100)
+const [user, orders, prefs] = await Promise.all([
+  fetchUser(id),
+  fetchOrders(id),
+  fetchPreferences(id),
+]);
+```
+
+**Rule:** If operation B does not depend on the result of operation A, they MUST run in parallel.
+
+### Rule 2: Use Promise.allSettled When Partial Failure is Acceptable
+
+```typescript
+// BAD — one failure cancels all
+const results = await Promise.all([criticalOp(), optionalOp()]); // if optionalOp rejects, criticalOp result is lost
+
+// GOOD — each result handled independently
+const [critical, optional] = await Promise.allSettled([criticalOp(), optionalOp()]);
+if (critical.status === 'rejected') throw critical.reason;
+if (optional.status === 'rejected') logger.warn('optional failed', optional.reason);
+```
+
+Use `Promise.all` when ALL operations are required. Use `Promise.allSettled` when SOME can fail gracefully.
+
+### Rule 3: Every External Call Has a Timeout
+
+Network calls without timeouts hang indefinitely, blocking resources.
+
+```typescript
+// BAD — hangs forever if service is down
+const response = await fetch('https://api.external.com/data');
+
+// GOOD — fails fast after 5 seconds
+const controller = new AbortController();
+const timeout = setTimeout(() => controller.abort(), 5_000);
+try {
+  const response = await fetch('https://api.external.com/data', { signal: controller.signal });
+  // ...
+} finally {
+  clearTimeout(timeout);
+}
+
+// GOOD — with a utility wrapper
+const response = await fetchWithTimeout('https://api.external.com/data', { timeout: 5_000 });
+```
+
+**Default timeouts:**
+- Internal service calls: 3s
+- External API calls: 10s
+- Long-running operations (file processing, ML): 60s with progress events
+- Database queries: configure at connection pool level
+
+### Rule 4: No Unhandled Promise Rejections
+
+Every promise must have a `.catch()` or be `await`-ed inside a `try/catch`.
+
+```typescript
+// BAD — fire-and-forget without error handling
+sendNotification(userId, message); // rejection is swallowed silently
+
+// BAD — floating promise in Express handler
+app.get('/data', (req, res) => {
+  loadData(); // not awaited, errors don't propagate to response
+  res.json({ ok: true });
+});
+
+// GOOD — fire-and-forget with explicit error handling
+sendNotification(userId, message).catch(err => {
+  logger.error('notification failed', { userId, err });
+});
+
+// GOOD — awaited in async handler
+app.get('/data', async (req, res) => {
+  const data = await loadData();
+  res.json(data);
+});
+```
+
+### Rule 5: No CPU-Blocking Operations on the Event Loop
+
+Operations that block the event loop starve all other concurrent requests:
+- `JSON.parse` / `JSON.stringify` on payloads > 1MB → use streaming
+- Synchronous file reads in hot paths → use `fs.promises.*`
+- CPU-intensive loops → offload to worker threads
+- Synchronous crypto operations → use `crypto.subtle` or async equivalents
+
+```typescript
+// BAD — blocks event loop for large payload
+app.post('/import', (req, res) => {
+  const data = JSON.parse(req.body.payload); // synchronous, large payload blocks
+});
+
+// GOOD — streaming parse
+import { pipeline } from 'stream/promises';
+app.post('/import', async (req, res) => {
+  await pipeline(req, new JSONStreamParser(), new DataProcessor());
+});
+```
+
+### Rule 6: Batch Async Operations with Controlled Concurrency
+
+Running N async operations at once can overwhelm downstream services. Use a concurrency limiter:
+
+```typescript
+// BAD — 1000 parallel requests to an API
+await Promise.all(items.map(item => processItem(item)));
+
+// GOOD — max 10 concurrent operations
+import PLimit from 'p-limit';
+const limit = PLimit(10);
+await Promise.all(items.map(item => limit(() => processItem(item))));
+```
+
+### Rule 7: Async Initialization Pattern
+
+Classes with async setup must not use the constructor for initialization:
+
+```typescript
+// BAD — constructor cannot be async
+class DatabasePool {
+  constructor() {
+    this.pool = await createPool(); // syntax error
+  }
+}
+
+// GOOD — factory method pattern
+class DatabasePool {
+  private constructor(private readonly pool: Pool) {}
+
+  static async create(): Promise<DatabasePool> {
+    const pool = await createPool();
+    return new DatabasePool(pool);
+  }
+}
+const db = await DatabasePool.create();
+```
+
+---
+
+## Iron Laws
+
+**IRON LAW 1: Sequential await for independent operations is a performance bug. Use Promise.all.**
+**IRON LAW 2: Every external HTTP call must have an explicit timeout configured.**
+**IRON LAW 3: A floating promise (not awaited, no .catch) is an unhandled rejection waiting to crash the process.**
+
+---
+
+## Red Flags — Stop and re-read this rule if you are thinking:
+
+| Rationalization | Why it's wrong |
+|---|---|
+| "I'll add a timeout later if it's needed" | Missing timeouts are invisible until a downstream service hangs — add them when the call is written |
+| "The operation is fast, sequential await is fine" | Sequential operations that are "fast" become bottlenecks under load |
+| "I don't need to await this, it's just a side effect" | Fire-and-forget without `.catch` silently loses errors that may indicate data corruption |
+| "Promise.allSettled is verbose, I'll use Promise.all and handle errors in each function" | Promise.all cancels all operations on first rejection — allSettled gives you full control |
+| "Concurrency limiting adds complexity" | Uncontrolled concurrency causes rate limit errors, OOM, and cascading failures downstream |
+
+**IRON LAW: AN ASYNC FUNCTION THAT CAN HANG INDEFINITELY IS A DENIAL-OF-SERVICE VULNERABILITY.**