stapes-adsa 1.0.0

package/dist/checks/decision-router.js.map

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

package/dist/checks/fast-path-with-io.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Check #2 — fast-path-with-io
+ *
+ * A function is explicitly marked as a fast path (via @adsa:fast JSDoc,
+ * // adsa:fast inline comment, or `Fast`/`FastPath` name suffix)
+ * but its body contains an I/O call per IO_CALLEE_PATTERNS.
+ *
+ * This is the single biggest ADSA violation: the "cache" that calls
+ * `fetch()`, the "permission check" that hits the DB, the "validation"
+ * that makes an RPC. A fast path must be pure — no I/O.
+ *
+ * Severity: block.
+ * Fix: none. Extracting the I/O call into a separate slow path is a
+ * refactor, not a mechanical insertion. The runner will refuse to
+ * auto-fix this check (SPEC.md invariant #7).
+ */
+import type { CheckResult } from "../types.js";
+import { AnyFunction } from "../ast.js";
+export declare function checkFastPathWithIo(file: string, functions: AnyFunction[]): CheckResult;

package/dist/checks/fast-path-with-io.js

@@ -0,0 +1,58 @@
+/**
+ * Check #2 — fast-path-with-io
+ *
+ * A function is explicitly marked as a fast path (via @adsa:fast JSDoc,
+ * // adsa:fast inline comment, or `Fast`/`FastPath` name suffix)
+ * but its body contains an I/O call per IO_CALLEE_PATTERNS.
+ *
+ * This is the single biggest ADSA violation: the "cache" that calls
+ * `fetch()`, the "permission check" that hits the DB, the "validation"
+ * that makes an RPC. A fast path must be pure — no I/O.
+ *
+ * Severity: block.
+ * Fix: none. Extracting the I/O call into a separate slow path is a
+ * refactor, not a mechanical insertion. The runner will refuse to
+ * auto-fix this check (SPEC.md invariant #7).
+ */
+import { SyntaxKind } from "ts-morph";
+import { truncate } from "../util.js";
+import { containsIoCall, getAdsaPathMarker } from "../ast.js";
+import { startColumn } from "../column.js";
+export function checkFastPathWithIo(file, functions) {
+    const findings = [];
+    for (const fn of functions) {
+        const marker = getAdsaPathMarker(fn);
+        if (marker !== "fast")
+            continue;
+        if (!containsIoCall(fn, "log"))
+            continue;
+        const name = getFnName(fn);
+        const line = fn.getStartLineNumber();
+        const column = startColumn(fn);
+        findings.push({
+            check: "fast-path-with-io",
+            file,
+            line,
+            column,
+            message: `Fast path "${name || "<anonymous>"}" performs I/O — fast paths must be pure (no network/db/cache/fs/queue)`,
+            severity: "block",
+            evidence: truncate(`function ${name}() { /* I/O inside fast path */ }`),
+        });
+    }
+    return {
+        name: "fast-path-with-io",
+        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=fast-path-with-io.js.map

package/dist/checks/fast-path-with-io.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fast-path-with-io.js","sourceRoot":"","sources":["../../src/checks/fast-path-with-io.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAA0C,UAAU,EAAE,MAAM,UAAU,CAAC;AAG9E,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAe,cAAc,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC3E,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,MAAM,UAAU,mBAAmB,CACjC,IAAY,EACZ,SAAwB;IAExB,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,KAAK,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,iBAAiB,CAAC,EAAE,CAAC,CAAC;QACrC,IAAI,MAAM,KAAK,MAAM;YAAE,SAAS;QAChC,IAAI,CAAC,cAAc,CAAC,EAAE,EAAE,KAAK,CAAC;YAAE,SAAS;QAEzC,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;QAE/B,QAAQ,CAAC,IAAI,CAAC;YACZ,KAAK,EAAE,mBAAmB;YAC1B,IAAI;YACJ,IAAI;YACJ,MAAM;YACN,OAAO,EAAE,cAAc,IAAI,IAAI,aAAa,yEAAyE;YACrH,QAAQ,EAAE,OAAO;YACjB,QAAQ,EAAE,QAAQ,CAAC,YAAY,IAAI,mCAAmC,CAAC;SACxE,CAAC,CAAC;IACL,CAAC;IACD,OAAO;QACL,IAAI,EAAE,mBAAmB;QACzB,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/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Check registry.
+ *
+ * The runner imports `CHECKS` and dispatches each one against every
+ * scanned file. Adding a new check = add an entry here + write the file.
+ */
+import { Project, SourceFile } from "ts-morph";
+import type { CheckResult } from "../types.js";
+export interface Check {
+    name: string;
+    description: string;
+    defaultEnabled: boolean;
+    severityDefault: "block" | "warn";
+    /** Run this check against one source file. */
+    run: (sf: SourceFile) => CheckResult;
+}
+export declare const CHECKS: ReadonlyArray<Check>;
+export declare function getCheck(name: string): Check | undefined;
+export declare function listCheckNames(): string[];
+/** Project factory — kept here so the runner and CLI share the same config. */
+export declare function createProject(): Project;

package/dist/checks/index.js

@@ -0,0 +1,90 @@
+/**
+ * Check registry.
+ *
+ * The runner imports `CHECKS` and dispatches each one against every
+ * scanned file. Adding a new check = add an entry here + write the file.
+ */
+import { Project } from "ts-morph";
+import { iterFunctions } from "../ast.js";
+import { normalizePath } from "../util.js";
+import { checkSlowPathNoLog } from "./slow-path-no-log.js";
+import { checkFastPathWithIo } from "./fast-path-with-io.js";
+import { checkDecisionRouter } from "./decision-router.js";
+import { checkAsyncNoLog } from "./async-no-log.js";
+import { checkLogSchema } from "./log-schema.js";
+export const CHECKS = [
+    {
+        name: "slow-path-no-log",
+        description: "Function marked slow (JSDoc, inline comment, or name suffix) without {adsa_path: \"slow\"} log emission",
+        defaultEnabled: true,
+        severityDefault: "warn",
+        run: (sf) => {
+            const functions = Array.from(iterFunctions(sf));
+            const r = checkSlowPathNoLog(normalizePath(sf.getFilePath()), functions);
+            return r;
+        },
+    },
+    {
+        name: "fast-path-with-io",
+        description: "Function marked fast (JSDoc, inline comment, or name suffix) that contains I/O (network/db/cache/fs/queue)",
+        defaultEnabled: true,
+        severityDefault: "block",
+        run: (sf) => {
+            const functions = Array.from(iterFunctions(sf));
+            const r = checkFastPathWithIo(normalizePath(sf.getFilePath()), functions);
+            return r;
+        },
+    },
+    {
+        name: "decision-router",
+        description: "Function marked fast with an if/else where one branch contains I/O — implicit fast/slow split hiding inside a conditional",
+        defaultEnabled: true,
+        severityDefault: "warn",
+        run: (sf) => {
+            const functions = Array.from(iterFunctions(sf));
+            const r = checkDecisionRouter(normalizePath(sf.getFilePath()), functions);
+            return r;
+        },
+    },
+    {
+        name: "async-no-log",
+        description: "Async function with >5 body lines and no {adsa_path: ...} log emission — likely a slow path not declaring itself",
+        defaultEnabled: true,
+        severityDefault: "warn",
+        run: (sf) => {
+            const functions = Array.from(iterFunctions(sf));
+            const r = checkAsyncNoLog(normalizePath(sf.getFilePath()), functions);
+            return r;
+        },
+    },
+    {
+        name: "log-schema",
+        description: "Validate {adsa_path, adsa_area} log object literals against the four-field contract",
+        defaultEnabled: true,
+        severityDefault: "block",
+        run: (sf) => checkLogSchema(sf),
+    },
+];
+export function getCheck(name) {
+    return CHECKS.find((c) => c.name === name);
+}
+export function listCheckNames() {
+    return CHECKS.map((c) => c.name);
+}
+/** ts-morph ESNext target enum value (ScriptTarget.ESNext = 99). */
+const ESNEXT_TARGET = 99;
+/** Project factory — kept here so the runner and CLI share the same config. */
+export function createProject() {
+    return new Project({
+        useInMemoryFileSystem: false,
+        skipAddingFilesFromTsConfig: true,
+        skipFileDependencyResolution: true,
+        compilerOptions: {
+            target: ESNEXT_TARGET,
+            allowJs: false,
+            skipLibCheck: true,
+            strict: false,
+        },
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/checks/index.js.map

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

package/dist/checks/log-schema.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Check #5 — adsa-log-schema
+ *
+ * Every `{adsa_path: ...}` object literal in the codebase must conform
+ * to the four-field contract:
+ *
+ *   Required:  {adsa_path: "fast" | "slow", adsa_area: <string>}
+ *   Optional:  {adsa_reason: <string>, adsa_save_pct: <number 0..100>}
+ *   Forbidden: any other keys with the `adsa_` prefix
+ *
+ * "log call" = the call shape described in ast.ts (log/logger/console/... callee).
+ *
+ * Severity: block for required-field violations, warn for unknown adsa_ keys.
+ * Fix: none.
+ */
+import { SourceFile } from "ts-morph";
+import type { CheckResult } from "../types.js";
+export declare function checkLogSchema(sf: SourceFile): CheckResult;

package/dist/checks/log-schema.js

@@ -0,0 +1,124 @@
+/**
+ * Check #5 — adsa-log-schema
+ *
+ * Every `{adsa_path: ...}` object literal in the codebase must conform
+ * to the four-field contract:
+ *
+ *   Required:  {adsa_path: "fast" | "slow", adsa_area: <string>}
+ *   Optional:  {adsa_reason: <string>, adsa_save_pct: <number 0..100>}
+ *   Forbidden: any other keys with the `adsa_` prefix
+ *
+ * "log call" = the call shape described in ast.ts (log/logger/console/... callee).
+ *
+ * Severity: block for required-field violations, warn for unknown adsa_ keys.
+ * Fix: none.
+ */
+import { SyntaxKind, } from "ts-morph";
+import { truncate } from "../util.js";
+import { LOG_REQUIRED_FIELDS, LOG_OPTIONAL_FIELDS, ADSA_PATH_VALUES, } from "../patterns.js";
+export function checkLogSchema(sf) {
+    const findings = [];
+    const file = sf.getBaseName() ?? "<unknown>";
+    for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+        const ce = call;
+        if (!isLogCallee(ce))
+            continue;
+        const args = ce.getArguments();
+        for (const arg of args) {
+            if (!arg.isKind(SyntaxKind.ObjectLiteralExpression))
+                continue;
+            validateObjectLiteral(arg, file, findings);
+        }
+    }
+    return {
+        name: "log-schema",
+        findings,
+        filesScanned: 1,
+        durationMs: 0,
+    };
+}
+function isLogCallee(ce) {
+    const text = ce.getExpression().getText();
+    return /\b(log|logger|console|pino|winston|bunyan)(\.|\(|$)/i.test(text);
+}
+function validateObjectLiteral(ol, file, findings) {
+    // Only inspect objects that contain an adsa_path property — otherwise
+    // it's just a regular log call and not in scope.
+    const present = new Map();
+    let hasAdsaPath = false;
+    for (const prop of ol.getProperties()) {
+        if (!prop.isKind(SyntaxKind.PropertyAssignment))
+            continue;
+        const pa = prop;
+        const name = pa.getName();
+        present.set(name, pa);
+        if (name === "adsa_path")
+            hasAdsaPath = true;
+    }
+    if (!hasAdsaPath)
+        return;
+    // Required fields
+    for (const required of LOG_REQUIRED_FIELDS) {
+        if (!present.has(required)) {
+            const line = ol.getStartLineNumber();
+            findings.push({
+                check: "log-schema",
+                file,
+                line,
+                column: 1,
+                message: `adsa log object is missing required field "${required}"`,
+                severity: "block",
+                evidence: truncate(ol.getText()),
+            });
+        }
+    }
+    // Enum check on adsa_path
+    const adsaPathProp = present.get("adsa_path");
+    if (adsaPathProp) {
+        const init = adsaPathProp.getInitializer();
+        if (init && init.isKind(SyntaxKind.StringLiteral)) {
+            const v = init.getLiteralText();
+            if (!ADSA_PATH_VALUES.includes(v)) {
+                findings.push({
+                    check: "log-schema",
+                    file,
+                    line: adsaPathProp.getStartLineNumber(),
+                    column: 1,
+                    message: `adsa_path must be "fast" or "slow" (got "${v}")`,
+                    severity: "block",
+                    evidence: truncate(adsaPathProp.getText()),
+                });
+            }
+        }
+        else if (init && !init.isKind(SyntaxKind.StringLiteral)) {
+            findings.push({
+                check: "log-schema",
+                file,
+                line: adsaPathProp.getStartLineNumber(),
+                column: 1,
+                message: `adsa_path must be a string literal`,
+                severity: "block",
+                evidence: truncate(adsaPathProp.getText()),
+            });
+        }
+    }
+    // Forbidden adsa_ prefix keys not in the contract
+    for (const key of present.keys()) {
+        if (!key.startsWith("adsa_"))
+            continue;
+        if (LOG_REQUIRED_FIELDS.includes(key))
+            continue;
+        if (LOG_OPTIONAL_FIELDS.includes(key))
+            continue;
+        findings.push({
+            check: "log-schema",
+            file,
+            line: present.get(key).getStartLineNumber(),
+            column: 1,
+            message: `Unknown adsa_ field "${key}" — not in the four-field contract`,
+            severity: "warn",
+            evidence: truncate(present.get(key).getText()),
+        });
+    }
+}
+//# sourceMappingURL=log-schema.js.map

package/dist/checks/log-schema.js.map

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

package/dist/checks/slow-path-no-log.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Check #1 — slow-path-no-log
+ *
+ * A function is explicitly marked as a slow path (via @adsa:slow JSDoc,
+ * // adsa:slow inline comment, or `Slow`/`SlowPath` name suffix)
+ * but its body does not emit a log call with `{adsa_path: "slow", ...}`.
+ *
+ * Without that log line, the path is invisible in observability — the
+ * fast_path_rate metric becomes meaningless.
+ *
+ * Severity: warn.
+ * Fix: insert the missing log line at the top of the body.
+ */
+import type { CheckResult } from "../types.js";
+import { AnyFunction } from "../ast.js";
+export declare function checkSlowPathNoLog(file: string, functions: AnyFunction[]): CheckResult;

package/dist/checks/slow-path-no-log.js

@@ -0,0 +1,71 @@
+/**
+ * Check #1 — slow-path-no-log
+ *
+ * A function is explicitly marked as a slow path (via @adsa:slow JSDoc,
+ * // adsa:slow inline comment, or `Slow`/`SlowPath` name suffix)
+ * but its body does not emit a log call with `{adsa_path: "slow", ...}`.
+ *
+ * Without that log line, the path is invisible in observability — the
+ * fast_path_rate metric becomes meaningless.
+ *
+ * Severity: warn.
+ * Fix: insert the missing 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 { getAdsaPathMarker, hasAdsaLogCall, } from "../ast.js";
+export function checkSlowPathNoLog(file, functions) {
+    const findings = [];
+    for (const fn of functions) {
+        const marker = getAdsaPathMarker(fn);
+        if (marker !== "slow")
+            continue;
+        if (hasAdsaLogCall(fn))
+            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 insertColumn = body ? 1 : 1;
+        const area = inferAdsaArea(file);
+        // Expression-bodied arrows cannot be safely auto-fixed.
+        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: insertColumn,
+            };
+        findings.push({
+            check: "slow-path-no-log",
+            file,
+            line,
+            column,
+            message: `Function "${name || "<anonymous>"}" marked slow has no {adsa_path: "slow"} log emission`,
+            severity: "warn",
+            evidence: truncate(`async function ${name}() { /* slow path, no log */ }`),
+            suggestedFix: fix,
+        });
+    }
+    return {
+        name: "slow-path-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=slow-path-no-log.js.map

package/dist/checks/slow-path-no-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slow-path-no-log.js","sourceRoot":"","sources":["../../src/checks/slow-path-no-log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;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,cAAc,GACf,MAAM,WAAW,CAAC;AAEnB,MAAM,UAAU,kBAAkB,CAChC,IAAY,EACZ,SAAwB;IAExB,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,KAAK,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,iBAAiB,CAAC,EAAE,CAAC,CAAC;QACrC,IAAI,MAAM,KAAK,MAAM;YAAE,SAAS;QAChC,IAAI,cAAc,CAAC,EAAE,CAAC;YAAE,SAAS;QAEjC,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,YAAY,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAClC,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;QAEjC,wDAAwD;QACxD,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,YAAY;aACrB,CAAC;QAEN,QAAQ,CAAC,IAAI,CAAC;YACZ,KAAK,EAAE,kBAAkB;YACzB,IAAI;YACJ,IAAI;YACJ,MAAM;YACN,OAAO,EAAE,aAAa,IAAI,IAAI,aAAa,uDAAuD;YAClG,QAAQ,EAAE,MAAM;YAChB,QAAQ,EAAE,QAAQ,CAAC,kBAAkB,IAAI,gCAAgC,CAAC;YAC1E,YAAY,EAAE,GAAG;SAClB,CAAC,CAAC;IACL,CAAC;IACD,OAAO;QACL,IAAI,EAAE,kBAAkB;QACxB,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/cli.d.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * stapes-adsa CLI entry point.
+ *
+ * Subcommands and flags:
+ *   (default)            run all enabled checks
+ *   --check <name>       run a single check by name
+ *   --list               list check names and exit
+ *   --strict             treat warnings as blocks
+ *   --json               emit the v1 JSON shape on stdout; stderr is empty
+ *   --no-color           disable ANSI colour in human output
+ *   --fix                dry-run: report what would be auto-fixed
+ *   --fix-confirm        apply the safe auto-fixes
+ *   --init               install the pre-commit hook (idempotent)
+ *   --uninstall          remove the pre-commit hook
+ *   --root <path>        project root (default: cwd)
+ *   --version
+ *   --help
+ *
+ * Exit codes per SPEC.md invariant #3:
+ *   0 clean (or warn-only without --strict)
+ *   1 blocked findings (or warn under --strict)
+ *   2 invalid args / runtime error
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+/**
+ * stapes-adsa CLI entry point.
+ *
+ * Subcommands and flags:
+ *   (default)            run all enabled checks
+ *   --check <name>       run a single check by name
+ *   --list               list check names and exit
+ *   --strict             treat warnings as blocks
+ *   --json               emit the v1 JSON shape on stdout; stderr is empty
+ *   --no-color           disable ANSI colour in human output
+ *   --fix                dry-run: report what would be auto-fixed
+ *   --fix-confirm        apply the safe auto-fixes
+ *   --init               install the pre-commit hook (idempotent)
+ *   --uninstall          remove the pre-commit hook
+ *   --root <path>        project root (default: cwd)
+ *   --version
+ *   --help
+ *
+ * Exit codes per SPEC.md invariant #3:
+ *   0 clean (or warn-only without --strict)
+ *   1 blocked findings (or warn under --strict)
+ *   2 invalid args / runtime error
+ */
+import { readFileSync } from "node:fs";
+import { Command } from "commander";
+import { run, formatHuman } from "./runner.js";
+import { applyFixes } from "./fix.js";
+import { installHook, uninstallHook } from "./hook-install.js";
+import { CHECKS, listCheckNames } from "./checks/index.js";
+import { NAME_COL_WIDTH, SEVERITY_COL_WIDTH } from "./util.js";
+const COLORS = {
+    red: (s) => `${s}`,
+    green: (s) => `${s}`,
+    yellow: (s) => `${s}`,
+    cyan: (s) => `${s}`,
+    dim: (s) => `${s}`,
+};
+const program = new Command();
+program
+    .name("stapes-adsa")
+    .description("AST-based ADSA (Adaptive Dual-System Architecture) linter for TypeScript. " +
+    "Flags slow paths without logging, fast paths doing I/O, decision points without routing, " +
+    "async boundaries missing the adsa_path log line, and invalid log shapes.")
+    .version(readVersion())
+    .option("--root <path>", "project root", process.cwd())
+    .option("--check <name>", "run a single check by name (repeatable)", collect, [])
+    .option("--strict", "treat warnings as blocks", false)
+    .option("--json", "emit JSON on stdout (stable v1 schema)", false)
+    .option("--no-color", "disable ANSI colour in human output")
+    .option("--fix", "dry-run: report auto-fixable findings", false)
+    .option("--fix-confirm", "apply safe auto-fixes", false)
+    .option("--init", "install the pre-commit hook (idempotent)", false)
+    .option("--uninstall", "remove the pre-commit hook", false)
+    .option("--list", "list available check names", false)
+    .exitOverride();
+try {
+    program.parse(process.argv);
+}
+catch (err) {
+    // Commander throws on --help / --version (exitCode 0) and on unknown
+    // args (exitCode 1). Forward the code; emit message on stderr.
+    const code = err.exitCode ?? 2;
+    const msg = err.message ?? "";
+    if (msg)
+        process.stderr.write(msg + "\n");
+    process.exit(code === 0 ? 0 : 2);
+}
+const opts = program.opts();
+function collect(value, prev) {
+    return prev.concat([value]);
+}
+// --list — exit early, no scan.
+if (opts.list) {
+    for (const c of CHECKS) {
+        const sev = c.severityDefault === "block" ? "block" : "warn";
+        const on = c.defaultEnabled ? "on " : "off";
+        const line = `  ${c.name.padEnd(NAME_COL_WIDTH)} [${on}] [${sev.padEnd(SEVERITY_COL_WIDTH)}]  ${c.description}`;
+        process.stdout.write(line + "\n");
+    }
+    process.exit(0);
+}
+// --init / --uninstall — operate on the hook, no scan.
+if (opts.init) {
+    try {
+        const r = installHook(opts.root);
+        const msg = `[${r.status}] hook at ${r.hookPath}`;
+        if (opts.json) {
+            process.stdout.write(JSON.stringify({ op: "init", ...r }) + "\n");
+        }
+        else {
+            process.stdout.write(msg + "\n");
+        }
+        process.exit(0);
+    }
+    catch (err) {
+        if (opts.json) {
+            process.stdout.write(JSON.stringify({ op: "init", error: err.message }) + "\n");
+            process.exit(2);
+        }
+        process.stderr.write(err.message + "\n");
+        process.exit(2);
+    }
+}
+if (opts.uninstall) {
+    const r = uninstallHook(opts.root);
+    if (opts.json) {
+        process.stdout.write(JSON.stringify({ op: "uninstall", ...r }) + "\n");
+    }
+    else {
+        process.stdout.write(`[${r.status}] hook at ${r.hookPath}\n`);
+    }
+    process.exit(0);
+}
+// Validate --check names up front.
+if (opts.check.length > 0) {
+    const known = new Set(listCheckNames());
+    const unknown = opts.check.filter((n) => !known.has(n));
+    if (unknown.length > 0) {
+        const msg = `unknown check name(s): ${unknown.join(", ")}. Run --list to see available.`;
+        if (opts.json) {
+            process.stdout.write(JSON.stringify({ error: msg }) + "\n");
+        }
+        else {
+            process.stderr.write(msg + "\n");
+        }
+        process.exit(2);
+    }
+}
+// Run.
+let report;
+try {
+    report = run({
+        root: opts.root,
+        checks: opts.check.length > 0 ? opts.check : undefined,
+        strict: opts.strict,
+    });
+}
+catch (err) {
+    if (opts.json) {
+        process.stdout.write(JSON.stringify({ error: err.message }) + "\n");
+        process.exit(2);
+    }
+    process.stderr.write(err.message + "\n");
+    process.exit(2);
+}
+// --fix / --fix-confirm.
+if (opts.fix || opts.fixConfirm) {
+    const fixReport = applyFixes(report.findings, {
+        write: Boolean(opts.fixConfirm),
+    });
+    if (opts.json) {
+        process.stdout.write(JSON.stringify({ ...report, fix: fixReport }) + "\n");
+    }
+    else {
+        process.stdout.write(`fix dry-run: ${fixReport.applied + fixReport.skipped + fixReport.failed} candidate(s)\n` +
+            `  would-apply: ${fixReport.applied + fixReport.skipped}  (run --fix-confirm to apply)\n` +
+            `  failed:      ${fixReport.failed}\n`);
+    }
+    // Exit code stays the same as the run report.
+    process.exit(report.exitCode);
+}
+// Output.
+if (opts.json) {
+    process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+    process.exit(report.exitCode);
+}
+else {
+    process.stdout.write(formatHuman(report) + "\n");
+    process.exit(report.exitCode);
+}
+// --- helpers ---
+function readVersion() {
+    try {
+        const pkgPath = new URL("../package.json", import.meta.url);
+        const raw = readFileSync(pkgPath.pathname, "utf8");
+        const pkg = JSON.parse(raw);
+        return pkg.version;
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+// Silence unused-import warnings for COLORS in --json mode.
+void COLORS;
+//# sourceMappingURL=cli.js.map