dravix-agent 0.1.0

package/dist/policy.d.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+export declare const PolicySchema: z.ZodObject<{
+    block: z.ZodDefault<z.ZodEffects<z.ZodUnion<[z.ZodArray<z.ZodString, "many">, z.ZodNull]>, string[], string[] | null>>;
+    warn: z.ZodDefault<z.ZodEffects<z.ZodUnion<[z.ZodArray<z.ZodString, "many">, z.ZodNull]>, string[], string[] | null>>;
+    ignore: z.ZodDefault<z.ZodEffects<z.ZodUnion<[z.ZodArray<z.ZodString, "many">, z.ZodNull]>, string[], string[] | null>>;
+}, "strict", z.ZodTypeAny, {
+    warn: string[];
+    ignore: string[];
+    block: string[];
+}, {
+    warn?: string[] | null | undefined;
+    ignore?: string[] | null | undefined;
+    block?: string[] | null | undefined;
+}>;
+export type Policy = z.infer<typeof PolicySchema>;
+/** Compiled policy: pre-normalized sets for O(1) lookup. */
+export interface CompiledPolicy {
+    block: Set<string>;
+    warn: Set<string>;
+    ignore: Set<string>;
+    /** Original source path (or null for the empty/default policy). */
+    sourcePath: string | null;
+}
+export declare const EMPTY_POLICY: CompiledPolicy;
+/** Canonicalise a CWE id or rule id: uppercase, strip a leading ``CWE-``
+ * so both ``"CWE-89"`` and ``"89"`` collapse to the same key. Rule ids
+ * (anything not numeric) stay as-is but lowercased for case-insensitive
+ * matching against engine rule ids. */
+export declare function normalizeKey(s: string): string;
+/** Does a finding's CWE or rule_id match any key in ``keys``?
+ *
+ * - CWE match: exact normalized equality (``"89"`` vs ``"89"``).
+ * - Rule id match: exact normalized equality OR ``keys`` entry is a
+ *   prefix followed by ``.*`` (e.g. ``"semgrep.*"`` matches every
+ *   semgrep rule). The ``.*`` suffix is the only wildcard form we
+ *   support — we explicitly avoid full regex to keep YAML editable
+ *   without escaping pitfalls.
+ */
+export declare function findingMatches(cwe: string | undefined, ruleId: string, keys: Set<string>): boolean;
+export declare function policyPath(projectRoot: string): string;
+/** Load and compile the project's policy. Returns ``EMPTY_POLICY`` when:
+ *   - the file doesn't exist (most projects),
+ *   - the file fails to parse / validate (we log a warning and refuse to
+ *     apply a partial policy — better to be uniformly default than half-on).
+ *
+ * Never throws.
+ */
+export declare function loadPolicy(projectRoot: string): CompiledPolicy;
+/** Generate a starter template the user can drop into their repo. */
+export declare function policyTemplate(): string;
+//# sourceMappingURL=policy.d.ts.map

package/dist/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"AA+BA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAmBxB,eAAO,MAAM,YAAY;;;;;;;;;;;;EAId,CAAC;AACZ,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAElD,4DAA4D;AAC5D,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACnB,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAClB,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACpB,mEAAmE;IACnE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,eAAO,MAAM,YAAY,EAAE,cAK1B,CAAC;AAIF;;;uCAGuC;AACvC,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAM9C;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,GAChB,OAAO,CAiBT;AAID,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc,CA0D9D;AAED,qEAAqE;AACrE,wBAAgB,cAAc,IAAI,MAAM,CA2BvC"}

package/dist/policy.js

@@ -0,0 +1,201 @@
+/**
+ * Policy-as-code — per-project ``aegis.policy.yml``.
+ *
+ * Teams declare three CWE lists at the project root and Aegis applies them
+ * in the orchestrator's final risk-decision step:
+ *
+ *   block:  [CWE-89, CWE-78, ...]   # always block — overrides confidence/severity
+ *   warn:   [CWE-704, CWE-369, ...] # warn but never block — downgrades a "block" decision
+ *   ignore: [CWE-1395, ...]         # drop the finding entirely (won't appear in the report)
+ *
+ * Precedence (highest first):
+ *   1. ignore   — finding is removed before anything else looks at it
+ *   2. block    — final action forced to "block" regardless of risk score
+ *   3. warn     — if risk decision would have been "block", downgrade to "warn"
+ *   4. (none)   — default risk scoring applies
+ *
+ * The same CWE in multiple lists is a CONFIG ERROR — we log a warning and
+ * apply the strictest (ignore > block > warn).
+ *
+ * **Where the file lives:** ``<project_root>/aegis.policy.yml``. Optional —
+ * if absent, behaviour is unchanged (no policy applied). Per-project so a
+ * monorepo with multiple sub-projects can have different policies.
+ *
+ * **CWE normalization:** both ``"CWE-89"`` and ``"89"`` accepted; both
+ * cwe and rule_id paths checked. Rule-id matches via prefix (`semgrep.*`
+ * matches all semgrep findings).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { z } from "zod";
+import { getLogger } from "./util/logger.js";
+const log = getLogger("aegis.policy");
+// ── Schema ────────────────────────────────────────────────────────────────
+const CweOrRule = z.string().min(1).max(120);
+// Accept null (YAML's "empty value" — e.g. `ignore:` with no items below)
+// as equivalent to an empty list. Without this, `parseYaml` produces
+// `{ignore: null}` and zod's `.default([])` doesn't fire (it only fires
+// on `undefined`), so the whole policy is rejected and silently empty.
+const StringList = z
+    .union([z.array(CweOrRule), z.null()])
+    .transform((v) => v ?? [])
+    .default([]);
+export const PolicySchema = z.object({
+    block: StringList,
+    warn: StringList,
+    ignore: StringList,
+}).strict();
+export const EMPTY_POLICY = {
+    block: new Set(),
+    warn: new Set(),
+    ignore: new Set(),
+    sourcePath: null,
+};
+// ── Normalization ─────────────────────────────────────────────────────────
+/** Canonicalise a CWE id or rule id: uppercase, strip a leading ``CWE-``
+ * so both ``"CWE-89"`` and ``"89"`` collapse to the same key. Rule ids
+ * (anything not numeric) stay as-is but lowercased for case-insensitive
+ * matching against engine rule ids. */
+export function normalizeKey(s) {
+    const trimmed = s.trim();
+    if (/^\d+$/.test(trimmed))
+        return trimmed; // "89"
+    const m = trimmed.match(/^cwe-(\d+)$/i);
+    if (m)
+        return m[1]; // "CWE-89" → "89"
+    return trimmed.toLowerCase(); // rule id like "semgrep.python.sql-injection"
+}
+/** Does a finding's CWE or rule_id match any key in ``keys``?
+ *
+ * - CWE match: exact normalized equality (``"89"`` vs ``"89"``).
+ * - Rule id match: exact normalized equality OR ``keys`` entry is a
+ *   prefix followed by ``.*`` (e.g. ``"semgrep.*"`` matches every
+ *   semgrep rule). The ``.*`` suffix is the only wildcard form we
+ *   support — we explicitly avoid full regex to keep YAML editable
+ *   without escaping pitfalls.
+ */
+export function findingMatches(cwe, ruleId, keys) {
+    if (keys.size === 0)
+        return false;
+    if (cwe) {
+        const n = normalizeKey(cwe);
+        if (keys.has(n))
+            return true;
+    }
+    const ruleNorm = normalizeKey(ruleId);
+    if (keys.has(ruleNorm))
+        return true;
+    // Prefix wildcard: any key ending in ".*" matches when ruleNorm starts
+    // with the prefix (no dot stuffing — exact dotted prefix).
+    for (const k of keys) {
+        if (k.endsWith(".*")) {
+            const prefix = k.slice(0, -2);
+            if (ruleNorm === prefix || ruleNorm.startsWith(prefix + "."))
+                return true;
+        }
+    }
+    return false;
+}
+// ── Loading ───────────────────────────────────────────────────────────────
+export function policyPath(projectRoot) {
+    return join(projectRoot, "aegis.policy.yml");
+}
+/** Load and compile the project's policy. Returns ``EMPTY_POLICY`` when:
+ *   - the file doesn't exist (most projects),
+ *   - the file fails to parse / validate (we log a warning and refuse to
+ *     apply a partial policy — better to be uniformly default than half-on).
+ *
+ * Never throws.
+ */
+export function loadPolicy(projectRoot) {
+    const p = policyPath(projectRoot);
+    if (!existsSync(p))
+        return EMPTY_POLICY;
+    let raw;
+    try {
+        raw = readFileSync(p, "utf8");
+    }
+    catch (err) {
+        log.warn("policy: read failed", { path: p, err: String(err) });
+        return EMPTY_POLICY;
+    }
+    let yaml;
+    try {
+        yaml = parseYaml(raw);
+    }
+    catch (err) {
+        log.warn("policy: YAML parse failed", { path: p, err: String(err) });
+        return EMPTY_POLICY;
+    }
+    // Empty file → empty policy (not an error).
+    if (yaml === null || yaml === undefined)
+        return { ...EMPTY_POLICY, sourcePath: p };
+    const parsed = PolicySchema.safeParse(yaml);
+    if (!parsed.success) {
+        log.warn("policy: schema validation failed", {
+            path: p,
+            err: parsed.error.issues[0]?.message ?? "?",
+        });
+        return EMPTY_POLICY;
+    }
+    const policy = parsed.data;
+    const block = new Set(policy.block.map(normalizeKey));
+    const warn = new Set(policy.warn.map(normalizeKey));
+    const ignore = new Set(policy.ignore.map(normalizeKey));
+    // Conflict detection: a CWE in multiple lists is almost always a typo —
+    // log it and apply strictest (ignore > block > warn).
+    for (const k of block) {
+        if (ignore.has(k)) {
+            log.warn("policy: conflict — entry is both block and ignore; treating as ignore", { key: k });
+            block.delete(k);
+        }
+    }
+    for (const k of warn) {
+        if (ignore.has(k)) {
+            log.warn("policy: conflict — entry is both warn and ignore; treating as ignore", { key: k });
+            warn.delete(k);
+        }
+        else if (block.has(k)) {
+            log.warn("policy: conflict — entry is both warn and block; treating as block", { key: k });
+            warn.delete(k);
+        }
+    }
+    log.debug("policy loaded", {
+        path: p,
+        block: block.size,
+        warn: warn.size,
+        ignore: ignore.size,
+    });
+    return { block, warn, ignore, sourcePath: p };
+}
+/** Generate a starter template the user can drop into their repo. */
+export function policyTemplate() {
+    return [
+        "# Aegis-v2 policy — per-project overrides for finding severity / blocking.",
+        "# https://aegis-v2.example/docs/policy",
+        "#",
+        "# Keys: CWE ids (CWE-89 or 89) OR rule-ids (semgrep.python.sql-injection",
+        "# OR a prefix wildcard like joern.*). Precedence: ignore > block > warn.",
+        "",
+        "block:",
+        "  # SQL injection — always block, no exceptions",
+        "  - CWE-89",
+        "  # OS command injection",
+        "  - CWE-78",
+        "  # Hardcoded credentials",
+        "  - CWE-798",
+        "",
+        "warn:",
+        "  # Float-money rounding is real but rarely critical — warn, don't block",
+        "  - CWE-704",
+        "  # Division-by-zero — surface, don't block (often defensive)",
+        "  - CWE-369",
+        "",
+        "ignore:",
+        "  # Specific rule IDs the team has reviewed + decided to suppress",
+        "  # Example: every semgrep.test-helper.* finding",
+        "  # - semgrep.test-helper.*",
+    ].join("\n");
+}
+//# sourceMappingURL=policy.js.map

package/dist/policy.js.map

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

package/dist/risk.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Risk scoring + action mapping.
+ *
+ * Inputs: a set of `Finding` (already validated by zod).
+ * Output: an `Action` — `allow` | `warn` | `block` — plus the *driving* finding
+ * (for messages/audit) and a one-line summary suitable for stderr.
+ *
+ * The mapping is intentionally simple and lives in ONE function so we can tune
+ * thresholds in A/B without touching engines.
+ */
+import { Finding } from "./findings.js";
+export type Action = "allow" | "warn" | "block";
+export interface ActionDecision {
+    action: Action;
+    driving: Finding | null;
+    summary: string;
+    blockCount: number;
+    warnCount: number;
+    totalFindings: number;
+}
+/**
+ * `confidence × severity_weight` is the score; thresholds:
+ *   ≥ 0.85 with severity ≥ high  → block
+ *   ≥ 0.60 with severity ≥ medium → warn
+ *   else → allow
+ */
+export declare function scoreOne(f: Finding): Action;
+export declare function decide(findings: ReadonlyArray<Finding>): ActionDecision;
+/** Exit code for the Claude-Code hook protocol — 0 allow/warn, 2 block. */
+export declare function exitCodeFor(action: Action): 0 | 2;
+//# sourceMappingURL=risk.d.ts.map

package/dist/risk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"risk.d.ts","sourceRoot":"","sources":["../src/risk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,OAAO,EAAgB,MAAM,eAAe,CAAC;AAEtD,MAAM,MAAM,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AAEhD,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;CACvB;AAkBD;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAO3C;AAED,wBAAgB,MAAM,CAAC,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,cAAc,CAgCvE;AAwBD,2EAA2E;AAC3E,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,CAAC,GAAG,CAAC,CAEjD"}

package/dist/risk.js

@@ -0,0 +1,92 @@
+/**
+ * Risk scoring + action mapping.
+ *
+ * Inputs: a set of `Finding` (already validated by zod).
+ * Output: an `Action` — `allow` | `warn` | `block` — plus the *driving* finding
+ * (for messages/audit) and a one-line summary suitable for stderr.
+ *
+ * The mapping is intentionally simple and lives in ONE function so we can tune
+ * thresholds in A/B without touching engines.
+ */
+import { severityRank } from "./findings.js";
+/** Single critical rules that *always* block, regardless of confidence. */
+const ALWAYS_BLOCK_ENGINES_RULES = [
+    // any secret detection at any confidence
+    ["secret-scan", /.*/],
+    // confirmed taint-sink reachability from Pysa
+    ["pysa", /.*reach.*/i],
+];
+function shouldAlwaysBlock(f) {
+    if (f.severity === "critical" && f.confidence >= 0.7)
+        return true;
+    for (const [engine, rule] of ALWAYS_BLOCK_ENGINES_RULES) {
+        if (f.engine === engine && rule.test(f.rule_id))
+            return true;
+    }
+    return false;
+}
+/**
+ * `confidence × severity_weight` is the score; thresholds:
+ *   ≥ 0.85 with severity ≥ high  → block
+ *   ≥ 0.60 with severity ≥ medium → warn
+ *   else → allow
+ */
+export function scoreOne(f) {
+    if (shouldAlwaysBlock(f))
+        return "block";
+    const sev = severityRank(f.severity);
+    // sev: 0=info 1=low 2=medium 3=high 4=critical
+    if (sev >= 3 && f.confidence >= 0.85)
+        return "block";
+    if (sev >= 2 && f.confidence >= 0.6)
+        return "warn";
+    return "allow";
+}
+export function decide(findings) {
+    let action = "allow";
+    let driving = null;
+    let blockCount = 0;
+    let warnCount = 0;
+    // Highest-severity findings first so `driving` carries the most relevant one.
+    const sorted = [...findings].sort((a, b) => severityRank(b.severity) - severityRank(a.severity) ||
+        b.confidence - a.confidence);
+    for (const f of sorted) {
+        const per = scoreOne(f);
+        if (per === "block") {
+            blockCount++;
+            if (action !== "block") {
+                action = "block";
+                driving = f;
+            }
+        }
+        else if (per === "warn") {
+            warnCount++;
+            if (action === "allow") {
+                action = "warn";
+                driving = f;
+            }
+        }
+    }
+    const summary = formatSummary(action, driving, blockCount, warnCount, findings.length);
+    return { action, driving, summary, blockCount, warnCount, totalFindings: findings.length };
+}
+function formatSummary(action, driving, blockCount, warnCount, total) {
+    if (action === "allow") {
+        return total === 0
+            ? "ALLOW — no findings."
+            : `ALLOW — ${total} low-confidence finding(s), none meet block/warn threshold.`;
+    }
+    if (action === "warn") {
+        const ref = driving ? `${driving.engine}:${driving.rule_id}` : "n/a";
+        return `WARN — ${warnCount} warning(s); top: ${ref} (${driving?.severity}, conf=${driving?.confidence.toFixed(2)})`;
+    }
+    // block
+    const ref = driving ? `${driving.engine}:${driving.rule_id}` : "n/a";
+    const cwe = driving?.cwe ? ` [${driving.cwe}]` : "";
+    return `BLOCK — ${blockCount} blocking finding(s); top: ${ref}${cwe} (${driving?.severity}, conf=${driving?.confidence.toFixed(2)})`;
+}
+/** Exit code for the Claude-Code hook protocol — 0 allow/warn, 2 block. */
+export function exitCodeFor(action) {
+    return action === "block" ? 2 : 0;
+}
+//# sourceMappingURL=risk.js.map

package/dist/risk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"risk.js","sourceRoot":"","sources":["../src/risk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAW,YAAY,EAAE,MAAM,eAAe,CAAC;AAatD,2EAA2E;AAC3E,MAAM,0BAA0B,GAAoC;IAClE,yCAAyC;IACzC,CAAC,aAAa,EAAE,IAAI,CAAC;IACrB,8CAA8C;IAC9C,CAAC,MAAM,EAAE,YAAY,CAAC;CACvB,CAAC;AAEF,SAAS,iBAAiB,CAAC,CAAU;IACnC,IAAI,CAAC,CAAC,QAAQ,KAAK,UAAU,IAAI,CAAC,CAAC,UAAU,IAAI,GAAG;QAAE,OAAO,IAAI,CAAC;IAClE,KAAK,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,0BAA0B,EAAE,CAAC;QACxD,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC;YAAE,OAAO,IAAI,CAAC;IAC/D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,CAAU;IACjC,IAAI,iBAAiB,CAAC,CAAC,CAAC;QAAE,OAAO,OAAO,CAAC;IACzC,MAAM,GAAG,GAAG,YAAY,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IACrC,+CAA+C;IAC/C,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,UAAU,IAAI,IAAI;QAAE,OAAO,OAAO,CAAC;IACrD,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,UAAU,IAAI,GAAG;QAAE,OAAO,MAAM,CAAC;IACnD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,QAAgC;IACrD,IAAI,MAAM,GAAW,OAAO,CAAC;IAC7B,IAAI,OAAO,GAAmB,IAAI,CAAC;IACnC,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,SAAS,GAAG,CAAC,CAAC;IAElB,8EAA8E;IAC9E,MAAM,MAAM,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC,IAAI,CAC/B,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACP,YAAY,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,QAAQ,CAAC;QACnD,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAC9B,CAAC;IAEF,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;QACxB,IAAI,GAAG,KAAK,OAAO,EAAE,CAAC;YACpB,UAAU,EAAE,CAAC;YACb,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;gBACvB,MAAM,GAAG,OAAO,CAAC;gBACjB,OAAO,GAAG,CAAC,CAAC;YACd,CAAC;QACH,CAAC;aAAM,IAAI,GAAG,KAAK,MAAM,EAAE,CAAC;YAC1B,SAAS,EAAE,CAAC;YACZ,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;gBACvB,MAAM,GAAG,MAAM,CAAC;gBAChB,OAAO,GAAG,CAAC,CAAC;YACd,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACvF,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC;AAC7F,CAAC;AAED,SAAS,aAAa,CACpB,MAAc,EACd,OAAuB,EACvB,UAAkB,EAClB,SAAiB,EACjB,KAAa;IAEb,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;QACvB,OAAO,KAAK,KAAK,CAAC;YAChB,CAAC,CAAC,sBAAsB;YACxB,CAAC,CAAC,WAAW,KAAK,6DAA6D,CAAC;IACpF,CAAC;IACD,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QACtB,MAAM,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;QACrE,OAAO,UAAU,SAAS,qBAAqB,GAAG,KAAK,OAAO,EAAE,QAAQ,UAAU,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;IACtH,CAAC;IACD,QAAQ;IACR,MAAM,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;IACrE,MAAM,GAAG,GAAG,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACpD,OAAO,WAAW,UAAU,8BAA8B,GAAG,GAAG,GAAG,KAAK,OAAO,EAAE,QAAQ,UAAU,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;AACvI,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,WAAW,CAAC,MAAc;IACxC,OAAO,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACpC,CAAC"}

package/dist/stats.d.ts

@@ -0,0 +1,72 @@
+export type Verdict = "allow" | "warn" | "block";
+/** Shape we parse out of each audit row — matches what ``appendAudit``
+ * writes in src/orchestrator.ts. Tolerate extra fields. */
+export interface AuditRow {
+    ts: string;
+    file: string;
+    lang?: string;
+    action: Verdict;
+    duration_ms: number;
+    truncated?: boolean;
+    n_findings?: number;
+    n_block?: number;
+    n_warn?: number;
+    driving?: {
+        engine?: string;
+        rule_id?: string;
+        severity?: string;
+        confidence?: number;
+        cwe?: string;
+    } | null;
+}
+export interface StatsReport {
+    source: string;
+    total_runs: number;
+    since: string | null;
+    until: string | null;
+    verdict_distribution: Record<Verdict, {
+        count: number;
+        pct: number;
+    }>;
+    latency_ms: {
+        p50: number;
+        p95: number;
+        p99: number;
+        max: number;
+        mean: number;
+    };
+    truncated_count: number;
+    truncated_pct: number;
+    findings_per_run: {
+        mean: number;
+        max: number;
+    };
+    top_engines: Array<{
+        engine: string;
+        count: number;
+    }>;
+    top_rules: Array<{
+        rule_id: string;
+        count: number;
+    }>;
+    top_files: Array<{
+        file: string;
+        blocks: number;
+        runs: number;
+    }>;
+}
+export declare function auditPath(projectRoot: string): string;
+/** Read all audit rows. Skips malformed lines silently. Never throws. */
+export declare function loadAuditRows(projectRoot: string): AuditRow[];
+/** Parse a `--since` value: ``N{d|h|m}`` (relative) or an ISO 8601
+ * timestamp (absolute). Returns the epoch ms cutoff, or null when the
+ * value is unparseable (caller treats null as "all-time"). */
+export declare function parseSince(since: string | undefined | null): number | null;
+interface ComputeOpts {
+    sinceMs?: number | null;
+    topN?: number;
+}
+export declare function computeStats(rows: AuditRow[], opts?: ComputeOpts): StatsReport;
+export declare function formatHuman(s: StatsReport): string;
+export {};
+//# sourceMappingURL=stats.d.ts.map

package/dist/stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats.d.ts","sourceRoot":"","sources":["../src/stats.ts"],"names":[],"mappings":"AAkCA,MAAM,MAAM,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AAEjD;2DAC2D;AAC3D,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,GAAG,CAAC,EAAE,MAAM,CAAC;KACd,GAAG,IAAI,CAAC;CACV;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,oBAAoB,EAAE,MAAM,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtE,UAAU,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACjF,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAChD,WAAW,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtD,SAAS,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrD,SAAS,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClE;AAID,wBAAgB,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,yEAAyE;AACzE,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,QAAQ,EAAE,CA8B7D;AAID;;8DAE8D;AAC9D,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAa1E;AAID,UAAU,WAAW;IACnB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,WAAW,CAqF9E;AAQD,wBAAgB,WAAW,CAAC,CAAC,EAAE,WAAW,GAAG,MAAM,CA2ClD"}