stapes-adsa 1.0.0

package/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: adsa
+description: Apply ADSA (Adaptive Dual-System Architecture) fast/slow path splitting to TypeScript code. Use when designing or reviewing a function, module, or service that has a decision point which could be cheap (cache, regex, JWT verify) vs expensive (DB, network, FS), when adding observability for fast_path_rate, or when fixing a "this should be fast but it isn't" performance bug. Triggers on phrases like "ADSA", "fast path", "slow path", "fast/slow", "router between", "cache vs compute", "the slow path is too slow", "permission check", "auth lookup", "validation rule", "rate limit", "ingestion pipeline". Outputs the four-field log contract {adsa_path, adsa_area, adsa_reason?, adsa_save_pct?}. Pairs with `stapes-adsa` (the AST linter) for automated enforcement.
+---
+
+# ADSA — Adaptive Dual-System Architecture
+
+ADSA is a thinking pattern. Every code path is either **fast** (cheap, deterministic, no I/O) or **slow** (full context, expensive). Routing between them is explicit. The path taken is logged.
+
+This skill is the framework reference. The linter (`stapes-adsa` on npm) enforces it.
+
+## The four-question self-assessment
+
+Before writing a function, code path, or service, ask:
+
+1. **Does this code make a decision based on input?**
+2. **Is there a cheap way to make that decision?** (cache, JWT, regex, simple calc, type check)
+3. **Is a minority of cases that need the expensive path?**
+4. **Would logging the path taken help observability?**
+
+If 2 or more are YES — apply ADSA. Structure the code as `FastPath → Router → SlowPath → UnifiedOutput + log(adsa_path)`.
+
+## The four-field log contract
+
+Every ADSA-coded path emits one structured log line at the moment routing happens:
+
+```json
+{
+  "adsa_path": "fast" | "slow",
+  "adsa_area": "<scope>",
+  "adsa_reason": "<why this path>",          // optional
+  "adsa_save_pct": 0..100                     // optional, percentage saved vs slow
+}
+```
+
+Field rules:
+
+| Field | Required | Values | Notes |
+|---|---|---|---|
+| `adsa_path` | yes | `"fast"` \| `"slow"` | Case-sensitive. Other values fail the linter. |
+| `adsa_area` | yes | string | Scope. Use directory or module name. |
+| `adsa_reason` | no | string | Human-readable why. No PII. |
+| `adsa_save_pct` | no | number 0..100 | Saved fraction vs the slow path. |
+
+Log schema violations are blocked by `stapes-adsa check log-schema`.
+
+## Path markers (optional, for linter detection)
+
+You can declare a path explicitly so the linter can verify it:
+
+| Marker | Form | Effect |
+|---|---|---|
+| JSDoc tag | `/** @adsa:fast */` or `/** @adsa:slow */` | Function classified |
+| Inline comment | `// adsa:fast` immediately preceding | Function classified |
+| Name suffix | `verifyFast`, `resolveSlow`, `lookupCacheFast` | Function classified |
+
+If no marker is present, the linter applies a heuristic (async + >5 body lines → candidate slow path).
+
+## Worked examples
+
+### 1. Auth — the most common ADSA case
+
+```ts
+import { withAdsaLogging } from "stapes-adsa/lib/instrument";
+
+// FAST: verify JWT signature. Pure. No I/O.
+function verifyTokenFast(token: string): UserClaims | null {
+  try {
+    return jwt.verify(token, PUBLIC_KEY) as UserClaims;
+  } catch {
+    return null;
+  }
+}
+
+// SLOW: full session resolution. Hits DB.
+async function resolveSessionSlow(claims: UserClaims): Promise<Session> {
+  return db.sessions.findUnique({ where: { userId: claims.sub } });
+}
+
+// Router
+export async function authenticate(token: string) {
+  return withAdsaLogging({
+    area: "auth",
+    predicate: async () => verifyTokenFast(token),  // fast path
+    slowPath: async () => {
+      const claims = jwt.decode(token);              // decode only, still cheap
+      if (!claims) throw new AuthError("invalid");
+      return resolveSessionSlow(claims as UserClaims);
+    },
+  });
+}
+```
+
+Why: `verifyTokenFast` needs no I/O. It runs in microseconds. The 99% of tokens that are valid JWTs never touch the DB. The slow path runs only on tokens that fail signature verification.
+
+### 2. Cache — wrap a lookup
+
+```ts
+async function getUserPermissions(userId: string): Promise<Permission[]> {
+  return withAdsaLogging({
+    area: "permission",
+    predicate: async () => cache.get(`perms:${userId}`),     // fast: in-memory hit
+    slowPath: async () => {
+      const perms = await db.permissions.findMany({ where: { userId } });
+      cache.set(`perms:${userId}`, perms, { ttl: 60 });
+      return perms;
+    },
+  });
+}
+```
+
+Why: when the cache hits, the function returns in single-digit microseconds and emits `adsa_path: "fast"`. When the cache misses, it computes, sets the cache, and emits `adsa_path: "slow"`. The fast-path-rate metric becomes the cache hit ratio.
+
+### 3. Search — Meilisearch vs DB
+
+```ts
+async function searchProducts(query: string): Promise<Hit[]> {
+  return withAdsaLogging({
+    area: "search",
+    predicate: async () => meili.index("products").search(query, { limit: 20 }),
+    slowPath: async () => db.products.findMany({ where: { name: { contains: query } } }),
+  });
+}
+```
+
+Why: Meilisearch handles typo-tolerance, ranking, and facet aggregation in one shot. The DB fallback exists for index-stale or empty-index cases. The log line tells ops which path the request took.
+
+### 4. Rate limit — Redis counter vs request rejection
+
+```ts
+async function checkRateLimit(userId: string): Promise<boolean> {
+  return withAdsaLogging({
+    area: "rate-limit",
+    predicate: async () => {
+      const count = await redis.incr(`rl:${userId}`);
+      if (count === 1) await redis.expire(`rl:${userId}`, 60);
+      return count <= 100;
+    },
+    // slow path: degrade to memory-only counter if Redis is down
+    slowPath: async () => memCounter.incr(userId) <= 100,
+  });
+}
+```
+
+Why: Redis is fast but still I/O. The fast path is the normal operation. The slow path is a degraded mode that runs only when Redis is unavailable — and logs it so ops sees the degradation.
+
+## Anti-patterns
+
+- **Uniformly cheap code.** Don't apply ADSA to a pure function with no decision point. Over-engineering.
+- **Uniformly expensive code.** If every call hits the DB, splitting fast/slow is the wrong split. Use caching or batching instead.
+- **PII in `adsa_reason`.** The reason field is logged to your observability stack. Treat it as user-visible.
+- **Logging on the wrong side.** Emit `adsa_path` once, at the routing point. Don't log inside the slow path's I/O calls.
+- **Silent failures.** The router must surface the fast/slow distinction in both the response shape and the log. A failure mode that returns success without distinguishing fast/slow is a bug.
+
+## Self-assessment output (fire at task start)
+
+When this skill is loaded, the next user-visible line should be one of:
+
+```
+ADSA: YES — fast/slow split in [paths] | NO — monolithic OK
+```
+
+Followed by the framework's coverage summary across the four areas:
+
+| Area | Fast Path | Slow Path |
+|---|---|---|
+| Auth | JWT verify, claim extract | DB session lookup |
+| Cache | In-memory hit | DB/API call + cache set |
+| Search | Meilisearch query | DB full-text scan |
+| Permissions | Role bit, cached perm | RBAC/ACL gRPC |
+| Validation | Regex, literal check | Rule engine, external policy |
+| Data ingestion | Single write/read | Multi-step transform, enrichment |
+| Rate limiting | In-memory counter | Distributed counter (Redis) |
+| Config / flags | Local eval | Remote config service |
+
+## Pairing with `stapes-adsa`
+
+This skill is the framework reference. The linter is the enforcement:
+
+```bash
+npx stapes-adsa --root .          # scan, exit 1 on block
+npx stapes-adsa --json            # agent-friendly output
+npx stapes-adsa --init            # install pre-commit hook
+npx stapes-adsa --fix             # dry-run safe auto-fixes
+npx stapes-adsa --fix-confirm     # apply safe auto-fixes
+```
+
+The linter catches:
+
+| Check | What it catches |
+|---|---|
+| `slow-path-no-log` | Function marked slow without `{adsa_path: "slow"}` log |
+| `fast-path-with-io` | Function marked fast that contains network/db/cache/fs/queue calls |
+| `decision-router` | Function marked fast with an if/else where one branch does I/O |
+| `async-no-log` | Async function >5 lines without an `{adsa_path}` log line |
+| `log-schema` | Invalid `{adsa_path}` value, missing `adsa_area`, unknown `adsa_*` field |
+
+Use the linter in pre-commit + CI. Use this skill when designing the structure.

package/dist/ast.d.ts

@@ -0,0 +1,55 @@
+/**
+ * AST helpers shared across checks.
+ *
+ * All checks operate on `ts-morph` SourceFile nodes. These helpers
+ * extract the ADSA-relevant signals:
+ *
+ *   - `getFunctionName`            — name for marker regex matching
+ *   - `getAdsaPathMarker`          — "fast" | "slow" | undefined, from JSDoc/name/comment
+ *   - `isAsyncFunction`            — function is declared `async`
+ *   - `hasAdsaLogCall`             — body contains a log call with {adsa_path: "fast"|"slow"}
+ *   - `containsIoCall`             — body contains a callee matching IO_CALLEE_PATTERNS
+ *   - `iterFunctions`              — walk all function-like nodes in a source file
+ */
+import { ArrowFunction, FunctionDeclaration, FunctionExpression, MethodDeclaration, SourceFile } from "ts-morph";
+/** A function-like node we care about. */
+export type AnyFunction = FunctionDeclaration | MethodDeclaration | FunctionExpression | ArrowFunction;
+/**
+ * Get the textual name of a function. Anonymous arrows return "".
+ */
+export declare function getFunctionName(fn: AnyFunction): string;
+/**
+ * Read the ADSA path marker attached to a function.
+ *
+ * Resolution order (most explicit wins):
+ *   1. JSDoc tag `@adsa:fast` / `@adsa:slow`
+ *   2. Inline comment `// adsa:fast` / `// adsa:slow` immediately preceding
+ *   3. Function name suffix `Fast` / `Slow`
+ *
+ * Returns undefined when no marker is present.
+ */
+export declare function getAdsaPathMarker(fn: AnyFunction): "fast" | "slow" | undefined;
+/** True if the function is declared `async`. */
+export declare function isAsyncFunction(fn: AnyFunction): boolean;
+/**
+ * True if the function body contains a log call with an `{adsa_path: "fast"|"slow"}` shape.
+ *
+ * "log call" = a CallExpression whose callee identifier / member name matches
+ *   ./^log(_|$)|logger|console$|pino|winston|bunyan/i
+ *
+ * The first object-literal argument is inspected for an `adsa_path` property
+ * with a string-literal value of "fast" or "slow".
+ */
+export declare function hasAdsaLogCall(fn: AnyFunction): boolean;
+/**
+ * True if the function body contains an I/O call per IO_CALLEE_PATTERNS.
+ *
+ * `ignoreCallee` allows a check to skip its own log emission when scanning.
+ */
+export declare function containsIoCall(fn: AnyFunction, ignoreCallee?: string): boolean;
+/**
+ * Walk every function-like node in a SourceFile. Yields each one exactly once.
+ */
+export declare function iterFunctions(sf: SourceFile): Generator<AnyFunction>;
+/** Count lines in a function body (approximate; uses node text). */
+export declare function functionLineCount(fn: AnyFunction): number;

package/dist/ast.js

@@ -0,0 +1,186 @@
+/**
+ * AST helpers shared across checks.
+ *
+ * All checks operate on `ts-morph` SourceFile nodes. These helpers
+ * extract the ADSA-relevant signals:
+ *
+ *   - `getFunctionName`            — name for marker regex matching
+ *   - `getAdsaPathMarker`          — "fast" | "slow" | undefined, from JSDoc/name/comment
+ *   - `isAsyncFunction`            — function is declared `async`
+ *   - `hasAdsaLogCall`             — body contains a log call with {adsa_path: "fast"|"slow"}
+ *   - `containsIoCall`             — body contains a callee matching IO_CALLEE_PATTERNS
+ *   - `iterFunctions`              — walk all function-like nodes in a source file
+ */
+import { SyntaxKind, } from "ts-morph";
+import { ADSA_FAST_TAG, ADSA_SLOW_TAG, ADSA_INLINE_FAST, ADSA_INLINE_SLOW, FAST_NAME_REGEX, SLOW_NAME_REGEX, IO_CALLEE_PATTERNS, } from "./patterns.js";
+/**
+ * Get the textual name of a function. Anonymous arrows return "".
+ */
+export function getFunctionName(fn) {
+    if (fn.isKind(SyntaxKind.FunctionDeclaration)) {
+        return fn.getName() ?? "";
+    }
+    if (fn.isKind(SyntaxKind.MethodDeclaration)) {
+        return fn.getName();
+    }
+    const parent = fn.getParent();
+    if (parent && parent.isKind(SyntaxKind.VariableDeclaration)) {
+        return parent.getName();
+    }
+    return "";
+}
+/**
+ * Read the ADSA path marker attached to a function.
+ *
+ * Resolution order (most explicit wins):
+ *   1. JSDoc tag `@adsa:fast` / `@adsa:slow`
+ *   2. Inline comment `// adsa:fast` / `// adsa:slow` immediately preceding
+ *   3. Function name suffix `Fast` / `Slow`
+ *
+ * Returns undefined when no marker is present.
+ */
+export function getAdsaPathMarker(fn) {
+    // 1. JSDoc tags
+    for (const tag of collectJsDocTags(fn)) {
+        const t = tag.getText();
+        if (t.includes(ADSA_FAST_TAG))
+            return "fast";
+        if (t.includes(ADSA_SLOW_TAG))
+            return "slow";
+    }
+    // 2. Inline leading comment
+    const leading = fn.getLeadingCommentRanges() ?? [];
+    for (const range of leading) {
+        const text = range.getText();
+        if (ADSA_INLINE_FAST.test(text))
+            return "fast";
+        if (ADSA_INLINE_SLOW.test(text))
+            return "slow";
+    }
+    // 3. Name pattern
+    const name = getFunctionName(fn);
+    if (!name)
+        return undefined;
+    if (FAST_NAME_REGEX.test(name))
+        return "fast";
+    if (SLOW_NAME_REGEX.test(name))
+        return "slow";
+    return undefined;
+}
+/** Collect all JSDoc tag nodes attached to a function, or its container. */
+function collectJsDocTags(fn) {
+    const tags = [];
+    for (const jsdoc of fn.getJsDocs()) {
+        tags.push(...jsdoc.getTags());
+    }
+    return tags;
+}
+/** True if the function is declared `async`. */
+export function isAsyncFunction(fn) {
+    return fn.isAsync();
+}
+/**
+ * True if the function body contains a log call with an `{adsa_path: "fast"|"slow"}` shape.
+ *
+ * "log call" = a CallExpression whose callee identifier / member name matches
+ *   ./^log(_|$)|logger|console$|pino|winston|bunyan/i
+ *
+ * The first object-literal argument is inspected for an `adsa_path` property
+ * with a string-literal value of "fast" or "slow".
+ */
+export function hasAdsaLogCall(fn) {
+    let found = false;
+    fn.forEachDescendant((node) => {
+        if (found)
+            return;
+        if (!node.isKind(SyntaxKind.CallExpression))
+            return;
+        const call = node;
+        if (!isLogCallee(call))
+            return;
+        const args = call.getArguments();
+        for (const arg of args) {
+            if (arg.isKind(SyntaxKind.ObjectLiteralExpression)) {
+                if (objectLiteralHasAdsaPath(arg)) {
+                    found = true;
+                    return;
+                }
+            }
+        }
+    });
+    return found;
+}
+/** True if the callee of `call` looks like a logging function. */
+function isLogCallee(call) {
+    const expr = call.getExpression();
+    const text = expr.getText();
+    return /\b(log|logger|console|pino|winston|bunyan)(\.|\(|$)/i.test(text);
+}
+/** True if the object literal contains `adsa_path: "fast"|"slow"`. */
+function objectLiteralHasAdsaPath(ol) {
+    for (const prop of ol.getProperties()) {
+        if (!prop.isKind(SyntaxKind.PropertyAssignment))
+            continue;
+        const pa = prop;
+        if (pa.getName() !== "adsa_path")
+            continue;
+        const init = pa.getInitializer();
+        if (!init)
+            return false;
+        if (init.isKind(SyntaxKind.StringLiteral)) {
+            const v = init.getLiteralText();
+            return v === "fast" || v === "slow";
+        }
+        return false;
+    }
+    return false;
+}
+/**
+ * True if the function body contains an I/O call per IO_CALLEE_PATTERNS.
+ *
+ * `ignoreCallee` allows a check to skip its own log emission when scanning.
+ */
+export function containsIoCall(fn, ignoreCallee) {
+    let found = false;
+    fn.forEachDescendant((node) => {
+        if (found)
+            return;
+        if (!node.isKind(SyntaxKind.CallExpression))
+            return;
+        const call = node;
+        const calleeText = call.getExpression().getText();
+        if (ignoreCallee && calleeText === ignoreCallee)
+            return;
+        const fullText = call.getText();
+        for (const rx of IO_CALLEE_PATTERNS) {
+            if (rx.test(fullText) || rx.test(calleeText)) {
+                found = true;
+                return;
+            }
+        }
+    });
+    return found;
+}
+/**
+ * Walk every function-like node in a SourceFile. Yields each one exactly once.
+ */
+export function* iterFunctions(sf) {
+    for (const node of sf.getDescendantsOfKind(SyntaxKind.FunctionDeclaration)) {
+        yield node;
+    }
+    for (const node of sf.getDescendantsOfKind(SyntaxKind.MethodDeclaration)) {
+        yield node;
+    }
+    for (const node of sf.getDescendantsOfKind(SyntaxKind.FunctionExpression)) {
+        yield node;
+    }
+    for (const node of sf.getDescendantsOfKind(SyntaxKind.ArrowFunction)) {
+        yield node;
+    }
+}
+/** Count lines in a function body (approximate; uses node text). */
+export function functionLineCount(fn) {
+    const text = fn.getBody()?.getText() ?? fn.getText();
+    return text.split("\n").length;
+}
+//# sourceMappingURL=ast.js.map

package/dist/ast.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast.js","sourceRoot":"","sources":["../src/ast.ts"],"names":[],"mappings":"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"}

package/dist/checks/async-no-log.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Check #4 — async-no-log
+ *
+ * An async function whose body is non-trivial (>5 lines), does not
+ * already have a `@adsa:slow` marker, and does not emit a log call
+ * with `{adsa_path: "slow", ...}`. Such a function is a "candidate"
+ * slow path that has not declared itself.
+ *
+ * This is a heuristic — small async helpers (e.g. `async function id(x)
+ * { return x }`) are excluded by the line-count gate. The intent is
+ * to surface the common case of "I wrote an async function, it does
+ * real work, but I forgot to log which path it is."
+ *
+ * Severity: warn.
+ * Fix: insert the slow-path log line at the top of the body.
+ */
+import type { CheckResult } from "../types.js";
+import { AnyFunction } from "../ast.js";
+export declare function checkAsyncNoLog(file: string, functions: AnyFunction[]): CheckResult;

package/dist/checks/async-no-log.js

@@ -0,0 +1,77 @@
+/**
+ * Check #4 — async-no-log
+ *
+ * An async function whose body is non-trivial (>5 lines), does not
+ * already have a `@adsa:slow` marker, and does not emit a log call
+ * with `{adsa_path: "slow", ...}`. Such a function is a "candidate"
+ * slow path that has not declared itself.
+ *
+ * This is a heuristic — small async helpers (e.g. `async function id(x)
+ * { return x }`) are excluded by the line-count gate. The intent is
+ * to surface the common case of "I wrote an async function, it does
+ * real work, but I forgot to log which path it is."
+ *
+ * Severity: warn.
+ * Fix: insert the slow-path log line at the top of the body.
+ */
+import { SyntaxKind } from "ts-morph";
+import { inferAdsaArea, truncate } from "../util.js";
+import { startColumn } from "../column.js";
+import { functionLineCount, getAdsaPathMarker, hasAdsaLogCall, isAsyncFunction, } from "../ast.js";
+/** Minimum body lines to count as a non-trivial async function. */
+const MIN_BODY_LINES = 5;
+export function checkAsyncNoLog(file, functions) {
+    const findings = [];
+    for (const fn of functions) {
+        if (!isAsyncFunction(fn))
+            continue;
+        if (functionLineCount(fn) < MIN_BODY_LINES)
+            continue;
+        if (hasAdsaLogCall(fn))
+            continue;
+        if (getAdsaPathMarker(fn) === "fast")
+            continue;
+        const name = getFnName(fn);
+        const line = fn.getStartLineNumber();
+        const column = startColumn(fn);
+        const body = fn.getBody();
+        const insertLine = body ? body.getStartLineNumber() : line + 1;
+        const area = inferAdsaArea(file);
+        const isExpressionBody = fn.isKind(SyntaxKind.ArrowFunction) &&
+            !fn.getBody().isKind(SyntaxKind.Block);
+        const fix = isExpressionBody
+            ? undefined
+            : {
+                description: `Insert slow-path log emission at top of ${name || "anonymous"}`,
+                replacement: `log.info({ adsa_path: "slow", adsa_area: "${area}" });\n`,
+                line: insertLine,
+                column: 1,
+            };
+        findings.push({
+            check: "async-no-log",
+            file,
+            line,
+            column,
+            message: `Async function "${name || "<anonymous>"}" has no {adsa_path: "slow"} log emission — likely a slow path that is not declaring itself`,
+            severity: "warn",
+            evidence: truncate(`async function ${name}() { /* ${functionLineCount(fn)} lines, no log */ }`),
+            suggestedFix: fix,
+        });
+    }
+    return {
+        name: "async-no-log",
+        findings,
+        filesScanned: 1,
+        durationMs: 0,
+    };
+}
+function getFnName(fn) {
+    if (fn.isKind(SyntaxKind.FunctionDeclaration)) {
+        return fn.getName() ?? "";
+    }
+    if (fn.isKind(SyntaxKind.MethodDeclaration)) {
+        return fn.getName();
+    }
+    return "";
+}
+//# sourceMappingURL=async-no-log.js.map

package/dist/checks/async-no-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-no-log.js","sourceRoot":"","sources":["../../src/checks/async-no-log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAyD,UAAU,EAAE,MAAM,UAAU,CAAC;AAG7F,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAEL,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,eAAe,GAChB,MAAM,WAAW,CAAC;AAEnB,mEAAmE;AACnE,MAAM,cAAc,GAAG,CAAC,CAAC;AAEzB,MAAM,UAAU,eAAe,CAC7B,IAAY,EACZ,SAAwB;IAExB,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,KAAK,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC;QAC3B,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC;YAAE,SAAS;QACnC,IAAI,iBAAiB,CAAC,EAAE,CAAC,GAAG,cAAc;YAAE,SAAS;QACrD,IAAI,cAAc,CAAC,EAAE,CAAC;YAAE,SAAS;QACjC,IAAI,iBAAiB,CAAC,EAAE,CAAC,KAAK,MAAM;YAAE,SAAS;QAE/C,MAAM,IAAI,GAAG,SAAS,CAAC,EAAE,CAAC,CAAC;QAC3B,MAAM,IAAI,GAAG,EAAE,CAAC,kBAAkB,EAAE,CAAC;QACrC,MAAM,MAAM,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;QAC/B,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC;QAC1B,MAAM,UAAU,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC;QAC/D,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;QAEjC,MAAM,gBAAgB,GACpB,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,aAAa,CAAC;YACnC,CAAE,EAAoB,CAAC,OAAO,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QAE5D,MAAM,GAAG,GAA6B,gBAAgB;YACpD,CAAC,CAAC,SAAS;YACX,CAAC,CAAC;gBACE,WAAW,EAAE,2CAA2C,IAAI,IAAI,WAAW,EAAE;gBAC7E,WAAW,EAAE,6CAA6C,IAAI,SAAS;gBACvE,IAAI,EAAE,UAAU;gBAChB,MAAM,EAAE,CAAC;aACV,CAAC;QAEN,QAAQ,CAAC,IAAI,CAAC;YACZ,KAAK,EAAE,cAAc;YACrB,IAAI;YACJ,IAAI;YACJ,MAAM;YACN,OAAO,EAAE,mBAAmB,IAAI,IAAI,aAAa,6FAA6F;YAC9I,QAAQ,EAAE,MAAM;YAChB,QAAQ,EAAE,QAAQ,CAAC,kBAAkB,IAAI,WAAW,iBAAiB,CAAC,EAAE,CAAC,qBAAqB,CAAC;YAC/F,YAAY,EAAE,GAAG;SAClB,CAAC,CAAC;IACL,CAAC;IACD,OAAO;QACL,IAAI,EAAE,cAAc;QACpB,QAAQ;QACR,YAAY,EAAE,CAAC;QACf,UAAU,EAAE,CAAC;KACd,CAAC;AACJ,CAAC;AAED,SAAS,SAAS,CAAC,EAAe;IAChC,IAAI,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,mBAAmB,CAAC,EAAE,CAAC;QAC9C,OAAQ,EAA0B,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC;IACrD,CAAC;IACD,IAAI,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,iBAAiB,CAAC,EAAE,CAAC;QAC5C,OAAQ,EAAwB,CAAC,OAAO,EAAE,CAAC;IAC7C,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/checks/decision-router.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Check #3 — decision-point-no-router
+ *
+ * A function marked fast has an `if` statement whose condition references
+ * one of the function's parameters, and one of the branches contains
+ * an I/O call. This is the pattern where the implicit fast/slow split
+ * is hiding inside a conditional — the fast path is doing I/O on one
+ * branch without declaring itself.
+ *
+ * Severity: warn.
+ * Fix: none. Splitting the function into an explicit fast/slow pair
+ * is a refactor.
+ */
+import type { CheckResult } from "../types.js";
+import { AnyFunction } from "../ast.js";
+export declare function checkDecisionRouter(file: string, functions: AnyFunction[]): CheckResult;

package/dist/checks/decision-router.js

@@ -0,0 +1,112 @@
+/**
+ * Check #3 — decision-point-no-router
+ *
+ * A function marked fast has an `if` statement whose condition references
+ * one of the function's parameters, and one of the branches contains
+ * an I/O call. This is the pattern where the implicit fast/slow split
+ * is hiding inside a conditional — the fast path is doing I/O on one
+ * branch without declaring itself.
+ *
+ * Severity: warn.
+ * Fix: none. Splitting the function into an explicit fast/slow pair
+ * is a refactor.
+ */
+import { SyntaxKind, } from "ts-morph";
+import { truncate } from "../util.js";
+import { getAdsaPathMarker } from "../ast.js";
+import { IO_CALLEE_PATTERNS } from "../patterns.js";
+import { startColumn } from "../column.js";
+export function checkDecisionRouter(file, functions) {
+    const findings = [];
+    for (const fn of functions) {
+        const marker = getAdsaPathMarker(fn);
+        if (marker !== "fast")
+            continue;
+        const params = collectParamNames(fn);
+        if (params.size === 0)
+            continue;
+        const ifStatements = fn.getDescendantsOfKind(SyntaxKind.IfStatement);
+        for (const ifStmt of ifStatements) {
+            if (!ifTestReferencesParam(ifStmt, params))
+                continue;
+            const consequentIo = ifContainsIo(ifStmt.getThenStatement());
+            const alternateIo = ifStmt.getElseStatement() != null
+                ? ifContainsIo(ifStmt.getElseStatement())
+                : false;
+            if (!consequentIo && !alternateIo)
+                continue;
+            const name = getFnName(fn);
+            const line = ifStmt.getStartLineNumber();
+            const column = startColumn(ifStmt);
+            findings.push({
+                check: "decision-router",
+                file,
+                line,
+                column,
+                message: `Fast path "${name || "<anonymous>"}" has an implicit fast/slow split — extract the I/O branch into a separate slow path`,
+                severity: "warn",
+                evidence: truncate(ifStmt.getText()),
+            });
+        }
+    }
+    return {
+        name: "decision-router",
+        findings,
+        filesScanned: 1,
+        durationMs: 0,
+    };
+}
+function collectParamNames(fn) {
+    const names = new Set();
+    for (const p of fn.getParameters()) {
+        names.add(p.getName());
+    }
+    return names;
+}
+function ifTestReferencesParam(ifStmt, params) {
+    const test = ifStmt.getExpression();
+    // forEachDescendant does not visit the root; check the root first so
+    // simple `if (paramName)` cases are caught.
+    if (test.isKind(SyntaxKind.Identifier)) {
+        if (params.has(test.getText()))
+            return true;
+    }
+    let referenced = false;
+    test.forEachDescendant((node) => {
+        if (referenced)
+            return;
+        if (node.isKind(SyntaxKind.Identifier)) {
+            const id = node;
+            if (params.has(id.getText()))
+                referenced = true;
+        }
+    });
+    return referenced;
+}
+function ifContainsIo(stmt) {
+    let found = false;
+    stmt.forEachDescendant((node) => {
+        if (found)
+            return;
+        if (!node.isKind(SyntaxKind.CallExpression))
+            return;
+        const text = node.getText();
+        for (const rx of IO_CALLEE_PATTERNS) {
+            if (rx.test(text)) {
+                found = true;
+                return;
+            }
+        }
+    });
+    return found;
+}
+function getFnName(fn) {
+    if (fn.isKind(SyntaxKind.FunctionDeclaration)) {
+        return fn.getName() ?? "";
+    }
+    if (fn.isKind(SyntaxKind.MethodDeclaration)) {
+        return fn.getName();
+    }
+    return "";
+}
+//# sourceMappingURL=decision-router.js.map