@curiousnerd/keel 0.1.0

package/dist/analyze/index.js

@@ -0,0 +1,28 @@
+import { isPathSuppressed, locationFile } from "../suppress.js";
+import { detectDrift } from "./drift.js";
+import { detectDocDrift } from "./docDrift.js";
+import { detectLibConflicts } from "./libConflicts.js";
+import { detectDuplication } from "./duplication.js";
+import { detectNearDuplication } from "./nearDup.js";
+import { scoreFindings } from "./score.js";
+import { loadCapabilityBuckets } from "./shared.js";
+const NO_SUPPRESSIONS = { buckets: new Set(), paths: [] };
+/** Run every v0 engine against the Facts + Claims, applying suppressions. */
+export function analyze(facts, claims, config, suppressions = NO_SUPPRESSIONS) {
+    const buckets = loadCapabilityBuckets();
+    const ignoreBuckets = new Set([...config.libConflicts.ignoreBuckets, ...suppressions.buckets]);
+    let findings = [
+        ...detectDrift(claims, facts, buckets),
+        ...detectDocDrift(facts, config),
+        ...detectLibConflicts(facts, ignoreBuckets, buckets),
+        ...detectDuplication(facts),
+    ];
+    if (config.duplication.near.enabled) {
+        findings.push(...detectNearDuplication(facts, config.duplication.near.threshold));
+    }
+    // `.keelignore` path rules drop any located finding in a matching file.
+    findings = findings.filter((f) => !(f.location && isPathSuppressed(suppressions, locationFile(f.location))));
+    const { score, breakdown } = scoreFindings(findings);
+    return { findings, score, breakdown };
+}
+//# sourceMappingURL=index.js.map

package/dist/analyze/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/analyze/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAqB,MAAM,gBAAgB,CAAC;AACnF,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAQpD,MAAM,eAAe,GAAiB,EAAE,OAAO,EAAE,IAAI,GAAG,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;AAExE,6EAA6E;AAC7E,MAAM,UAAU,OAAO,CACrB,KAAY,EACZ,MAAc,EACd,MAAkB,EAClB,eAA6B,eAAe;IAE5C,MAAM,OAAO,GAAG,qBAAqB,EAAE,CAAC;IACxC,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,YAAY,CAAC,aAAa,EAAE,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;IAE/F,IAAI,QAAQ,GAAc;QACxB,GAAG,WAAW,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC;QACtC,GAAG,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC;QAChC,GAAG,kBAAkB,CAAC,KAAK,EAAE,aAAa,EAAE,OAAO,CAAC;QACpD,GAAG,iBAAiB,CAAC,KAAK,CAAC;KAC5B,CAAC;IACF,IAAI,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;QACpC,QAAQ,CAAC,IAAI,CAAC,GAAG,qBAAqB,CAAC,KAAK,EAAE,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;IACpF,CAAC;IAED,wEAAwE;IACxE,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,IAAI,gBAAgB,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAE7G,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;IACrD,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;AACxC,CAAC"}

package/dist/analyze/libConflicts.d.ts

@@ -0,0 +1,9 @@
+import type { Facts, Finding } from "../types.js";
+import { type CapabilityBuckets } from "./shared.js";
+/**
+ * Flag capability buckets where 2+ competing packages are actually imported.
+ * Evaluated per language, so a JS http client and a Python one are never
+ * reported as one conflict. Reports per-package file counts so an intentional
+ * migration is obvious.
+ */
+export declare function detectLibConflicts(facts: Facts, ignoreBuckets: Set<string>, buckets?: CapabilityBuckets): Finding[];

package/dist/analyze/libConflicts.js

@@ -0,0 +1,36 @@
+import { filesByPackage, languagesIn, loadCapabilityBuckets } from "./shared.js";
+const CONFLICT_PENALTY = 6;
+/**
+ * Flag capability buckets where 2+ competing packages are actually imported.
+ * Evaluated per language, so a JS http client and a Python one are never
+ * reported as one conflict. Reports per-package file counts so an intentional
+ * migration is obvious.
+ */
+export function detectLibConflicts(facts, ignoreBuckets, buckets = loadCapabilityBuckets()) {
+    const findings = [];
+    for (const language of languagesIn(facts)) {
+        const byPkg = filesByPackage(facts, language);
+        for (const [bucket, members] of Object.entries(buckets)) {
+            if (ignoreBuckets.has(bucket))
+                continue;
+            const present = members
+                .map((pkg) => ({ pkg, files: byPkg.get(pkg) ?? [] }))
+                .filter((entry) => entry.files.length > 0)
+                .sort((a, b) => b.files.length - a.files.length);
+            if (present.length < 2)
+                continue;
+            const summary = present
+                .map((e) => `${e.pkg} (${e.files.length} file${e.files.length === 1 ? "" : "s"})`)
+                .join(", ");
+            findings.push({
+                kind: "conflict",
+                confidence: "high",
+                title: `${bucket}: ${summary}`,
+                detail: `Multiple ${bucket} libraries are in use. Pick one, or suppress with libConflicts.ignoreBuckets: ["${bucket}"].`,
+                penalty: CONFLICT_PENALTY,
+            });
+        }
+    }
+    return findings;
+}
+//# sourceMappingURL=libConflicts.js.map

package/dist/analyze/libConflicts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"libConflicts.js","sourceRoot":"","sources":["../../src/analyze/libConflicts.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,qBAAqB,EAA0B,MAAM,aAAa,CAAC;AAEzG,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAE3B;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAY,EACZ,aAA0B,EAC1B,UAA6B,qBAAqB,EAAE;IAEpD,MAAM,QAAQ,GAAc,EAAE,CAAC;IAE/B,KAAK,MAAM,QAAQ,IAAI,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1C,MAAM,KAAK,GAAG,cAAc,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QAE9C,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YACxD,IAAI,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC;gBAAE,SAAS;YAExC,MAAM,OAAO,GAAG,OAAO;iBACpB,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;iBACpD,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;iBACzC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YAEnD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;gBAAE,SAAS;YAEjC,MAAM,OAAO,GAAG,OAAO;iBACpB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC;iBACjF,IAAI,CAAC,IAAI,CAAC,CAAC;YACd,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,UAAU;gBAChB,UAAU,EAAE,MAAM;gBAClB,KAAK,EAAE,GAAG,MAAM,KAAK,OAAO,EAAE;gBAC9B,MAAM,EAAE,YAAY,MAAM,mFAAmF,MAAM,KAAK;gBACxH,OAAO,EAAE,gBAAgB;aAC1B,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/analyze/nearDup.d.ts

@@ -0,0 +1,11 @@
+import type { Facts, Finding } from "../types.js";
+/**
+ * Detect near-duplicate functions: pairs whose normalized bodies are at least
+ * `threshold` similar (Jaccard over winnowing fingerprints) but not identical
+ * (exact clones are handled by the duplication engine).
+ *
+ * Findings are produced by greedy matching on descending similarity, so each
+ * function appears in at most one near-dup finding — keeping output readable
+ * even when several functions cluster together.
+ */
+export declare function detectNearDuplication(facts: Facts, threshold: number): Finding[];

package/dist/analyze/nearDup.js

@@ -0,0 +1,67 @@
+import { jaccard } from "../util/fingerprint.js";
+import { buildFunctionIgnoreCheck } from "./shared.js";
+/** Gentle penalty — near-dups are advisory, not high-confidence. */
+const NEAR_PENALTY = 2;
+const key = (fn) => `${fn.filePath}:${fn.startLine}`;
+const label = (fn) => fn.name ?? "(anonymous)";
+/**
+ * Detect near-duplicate functions: pairs whose normalized bodies are at least
+ * `threshold` similar (Jaccard over winnowing fingerprints) but not identical
+ * (exact clones are handled by the duplication engine).
+ *
+ * Findings are produced by greedy matching on descending similarity, so each
+ * function appears in at most one near-dup finding — keeping output readable
+ * even when several functions cluster together.
+ */
+export function detectNearDuplication(facts, threshold) {
+    const isSuppressed = buildFunctionIgnoreCheck(facts);
+    const candidates = [];
+    for (const file of facts.files) {
+        for (const fn of file.functions) {
+            // Named functions only — anonymous callbacks are noise (see duplication.ts).
+            if (fn.bodyHash === null || fn.name === null || fn.fingerprints.length === 0 || isSuppressed(fn))
+                continue;
+            candidates.push({ fn, fp: fn.fingerprints });
+        }
+    }
+    // Compare shorter fingerprint sets first so the size-ratio prune is tight.
+    candidates.sort((a, b) => a.fp.length - b.fp.length);
+    const pairs = [];
+    for (let i = 0; i < candidates.length; i++) {
+        const a = candidates[i];
+        for (let j = i + 1; j < candidates.length; j++) {
+            const b = candidates[j];
+            // Jaccard <= min/max of set sizes; once that bound drops below the
+            // threshold, every later (longer) b can only be worse — stop early.
+            if (a.fp.length / b.fp.length < threshold)
+                break;
+            if (a.fn.bodyHash === b.fn.bodyHash)
+                continue; // identical -> exact engine
+            const sim = jaccard(a.fp, b.fp);
+            if (sim >= threshold)
+                pairs.push({ a: a.fn, b: b.fn, sim });
+        }
+    }
+    pairs.sort((x, y) => y.sim - x.sim);
+    const used = new Set();
+    const findings = [];
+    for (const { a, b, sim } of pairs) {
+        const ka = key(a);
+        const kb = key(b);
+        if (used.has(ka) || used.has(kb))
+            continue;
+        used.add(ka);
+        used.add(kb);
+        const pct = Math.round(sim * 100);
+        findings.push({
+            kind: "dup-near",
+            confidence: "low",
+            title: `${label(a)}() ~${pct}% similar to ${label(b)}()`,
+            detail: `${label(a)} @ ${ka}\n           ${label(b)} @ ${kb}`,
+            location: ka,
+            penalty: NEAR_PENALTY,
+        });
+    }
+    return findings;
+}
+//# sourceMappingURL=nearDup.js.map

package/dist/analyze/nearDup.js.map

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

package/dist/analyze/score.d.ts

@@ -0,0 +1,6 @@
+import type { Finding, ScoreBreakdown } from "../types.js";
+/** Roll findings into per-category penalties and the 0-100 Coherence Score. */
+export declare function scoreFindings(findings: Finding[]): {
+    score: number;
+    breakdown: ScoreBreakdown;
+};

package/dist/analyze/score.js

@@ -0,0 +1,39 @@
+/**
+ * Per-category penalty ceilings. Each category's penalty grows with the number
+ * of issues but saturates toward its cap, so one noisy category can't tank the
+ * whole score — while all three together can still drive it to 0. The ceilings
+ * sum to 100.
+ */
+const CATEGORY_CAP = { drift: 35, conflict: 25, duplication: 40 };
+/**
+ * Saturating curve. Slope is ~1 near the origin (a handful of issues costs
+ * about its raw penalty) and eases toward `cap` as the raw penalty grows, so a
+ * repo with 30 duplicates scores poorly but not identically to one with 300.
+ *   penalty = cap * (1 - e^(-raw / cap))
+ */
+function saturate(raw, cap) {
+    if (raw <= 0)
+        return 0;
+    return Math.round(cap * (1 - Math.exp(-raw / cap)));
+}
+/** Roll findings into per-category penalties and the 0-100 Coherence Score. */
+export function scoreFindings(findings) {
+    const raw = { drift: 0, conflict: 0, duplication: 0 };
+    for (const f of findings) {
+        if (f.kind === "drift")
+            raw.drift += f.penalty;
+        else if (f.kind === "conflict")
+            raw.conflict += f.penalty;
+        else
+            raw.duplication += f.penalty; // dup + dup-near
+    }
+    const breakdown = {
+        drift: saturate(raw.drift, CATEGORY_CAP.drift),
+        conflict: saturate(raw.conflict, CATEGORY_CAP.conflict),
+        duplication: saturate(raw.duplication, CATEGORY_CAP.duplication),
+    };
+    const total = breakdown.drift + breakdown.conflict + breakdown.duplication;
+    const score = Math.max(0, Math.min(100, 100 - total));
+    return { score, breakdown };
+}
+//# sourceMappingURL=score.js.map

package/dist/analyze/score.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"score.js","sourceRoot":"","sources":["../../src/analyze/score.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,YAAY,GAAG,EAAE,KAAK,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE,EAAW,CAAC;AAE3E;;;;;GAKG;AACH,SAAS,QAAQ,CAAC,GAAW,EAAE,GAAW;IACxC,IAAI,GAAG,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IACvB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;AACtD,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,aAAa,CAAC,QAAmB;IAC/C,MAAM,GAAG,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC;IACtD,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,IAAI,CAAC,CAAC,IAAI,KAAK,OAAO;YAAE,GAAG,CAAC,KAAK,IAAI,CAAC,CAAC,OAAO,CAAC;aAC1C,IAAI,CAAC,CAAC,IAAI,KAAK,UAAU;YAAE,GAAG,CAAC,QAAQ,IAAI,CAAC,CAAC,OAAO,CAAC;;YACrD,GAAG,CAAC,WAAW,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,iBAAiB;IACtD,CAAC;IAED,MAAM,SAAS,GAAmB;QAChC,KAAK,EAAE,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,YAAY,CAAC,KAAK,CAAC;QAC9C,QAAQ,EAAE,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,YAAY,CAAC,QAAQ,CAAC;QACvD,WAAW,EAAE,QAAQ,CAAC,GAAG,CAAC,WAAW,EAAE,YAAY,CAAC,WAAW,CAAC;KACjE,CAAC;IACF,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,GAAG,SAAS,CAAC,QAAQ,GAAG,SAAS,CAAC,WAAW,CAAC;IAC3E,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC;IACtD,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;AAC9B,CAAC"}

package/dist/analyze/shared.d.ts

@@ -0,0 +1,19 @@
+import type { Facts, FunctionFact, Language } from "../types.js";
+export type CapabilityBuckets = Record<string, string[]>;
+/** Load the curated capability buckets shipped in data/. */
+export declare function loadCapabilityBuckets(): CapabilityBuckets;
+/**
+ * Map each externally-imported package -> sorted list of files importing it.
+ * Built from *actual imports*, not package.json, so unused/transitive deps
+ * never appear. Pass `language` to restrict to files of one language (so e.g.
+ * a JS http client and a Python one are never mistaken for the same conflict).
+ */
+export declare function filesByPackage(facts: Facts, language?: Language): Map<string, string[]>;
+/** The distinct languages present across the scanned files. */
+export declare function languagesIn(facts: Facts): Language[];
+/**
+ * Build a predicate that reports whether a function is suppressed by an inline
+ * `// keel-ignore` marker on its declaration line or the line directly above.
+ * Shared by the exact and near duplication engines.
+ */
+export declare function buildFunctionIgnoreCheck(facts: Facts): (fn: FunctionFact) => boolean;

package/dist/analyze/shared.js

@@ -0,0 +1,53 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/** Load the curated capability buckets shipped in data/. */
+export function loadCapabilityBuckets() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const path = join(here, "..", "..", "data", "capability-buckets.json");
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+/**
+ * Map each externally-imported package -> sorted list of files importing it.
+ * Built from *actual imports*, not package.json, so unused/transitive deps
+ * never appear. Pass `language` to restrict to files of one language (so e.g.
+ * a JS http client and a Python one are never mistaken for the same conflict).
+ */
+export function filesByPackage(facts, language) {
+    const sets = new Map();
+    for (const file of facts.files) {
+        if (language && file.language !== language)
+            continue;
+        for (const imp of file.imports) {
+            if (!imp.external || !imp.packageName)
+                continue;
+            let set = sets.get(imp.packageName);
+            if (!set)
+                sets.set(imp.packageName, (set = new Set()));
+            set.add(file.path);
+        }
+    }
+    const out = new Map();
+    for (const [pkg, files] of sets)
+        out.set(pkg, [...files].sort());
+    return out;
+}
+/** The distinct languages present across the scanned files. */
+export function languagesIn(facts) {
+    return [...new Set(facts.files.map((f) => f.language))];
+}
+/**
+ * Build a predicate that reports whether a function is suppressed by an inline
+ * `// keel-ignore` marker on its declaration line or the line directly above.
+ * Shared by the exact and near duplication engines.
+ */
+export function buildFunctionIgnoreCheck(facts) {
+    const byPath = new Map();
+    for (const file of facts.files)
+        byPath.set(file.path, new Set(file.ignoreLines));
+    return (fn) => {
+        const lines = byPath.get(fn.filePath);
+        return lines !== undefined && (lines.has(fn.startLine) || lines.has(fn.startLine - 1));
+    };
+}
+//# sourceMappingURL=shared.js.map

package/dist/analyze/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../src/analyze/shared.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAKzC,4DAA4D;AAC5D,MAAM,UAAU,qBAAqB;IACnC,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACrD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,yBAAyB,CAAC,CAAC;IACvE,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAsB,CAAC;AACrE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,KAAY,EAAE,QAAmB;IAC9D,MAAM,IAAI,GAAG,IAAI,GAAG,EAAuB,CAAC;IAC5C,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAC/B,IAAI,QAAQ,IAAI,IAAI,CAAC,QAAQ,KAAK,QAAQ;YAAE,SAAS;QACrD,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAC/B,IAAI,CAAC,GAAG,CAAC,QAAQ,IAAI,CAAC,GAAG,CAAC,WAAW;gBAAE,SAAS;YAChD,IAAI,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;YACpC,IAAI,CAAC,GAAG;gBAAE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC;YACvD,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,GAAG,EAAoB,CAAC;IACxC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI;QAAE,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACjE,OAAO,GAAG,CAAC;AACb,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,WAAW,CAAC,KAAY;IACtC,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;AAC1D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAAY;IACnD,MAAM,MAAM,GAAG,IAAI,GAAG,EAAuB,CAAC;IAC9C,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK;QAAE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;IACjF,OAAO,CAAC,EAAE,EAAE,EAAE;QACZ,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC;QACtC,OAAO,KAAK,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC;IACzF,CAAC,CAAC;AACJ,CAAC"}

package/dist/cache/hashCache.d.ts

@@ -0,0 +1,19 @@
+import type { FileFacts } from "../types.js";
+/**
+ * File-hash keyed cache of extracted FileFacts, persisted at `.keel/cache.json`.
+ * Re-runs on an iterating codebase only re-parse files whose content changed.
+ */
+export declare class HashCache {
+    private readonly path;
+    private data;
+    /** Entries written this run; everything else is pruned on save. */
+    private readonly live;
+    constructor(root: string);
+    private load;
+    /** Return cached facts iff the content hash matches; otherwise undefined. */
+    get(path: string, hash: string): FileFacts | undefined;
+    /** Record facts for this run (also marks the entry live so it survives pruning). */
+    set(path: string, hash: string, facts: FileFacts): void;
+    /** Persist only entries touched this run, pruning deleted files. */
+    save(): void;
+}

package/dist/cache/hashCache.js

@@ -0,0 +1,49 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** Bump when the FileFacts shape changes, to invalidate stale caches. */
+const CACHE_VERSION = 5;
+/**
+ * File-hash keyed cache of extracted FileFacts, persisted at `.keel/cache.json`.
+ * Re-runs on an iterating codebase only re-parse files whose content changed.
+ */
+export class HashCache {
+    path;
+    data;
+    /** Entries written this run; everything else is pruned on save. */
+    live = new Map();
+    constructor(root) {
+        this.path = join(root, ".keel", "cache.json");
+        this.data = this.load();
+    }
+    load() {
+        if (!existsSync(this.path))
+            return { version: CACHE_VERSION, files: {} };
+        try {
+            const parsed = JSON.parse(readFileSync(this.path, "utf8"));
+            if (parsed.version !== CACHE_VERSION)
+                return { version: CACHE_VERSION, files: {} };
+            return parsed;
+        }
+        catch {
+            return { version: CACHE_VERSION, files: {} };
+        }
+    }
+    /** Return cached facts iff the content hash matches; otherwise undefined. */
+    get(path, hash) {
+        const entry = this.data.files[path];
+        return entry && entry.hash === hash ? entry.facts : undefined;
+    }
+    /** Record facts for this run (also marks the entry live so it survives pruning). */
+    set(path, hash, facts) {
+        this.live.set(path, { hash, facts });
+    }
+    /** Persist only entries touched this run, pruning deleted files. */
+    save() {
+        const files = {};
+        for (const [path, entry] of this.live)
+            files[path] = entry;
+        mkdirSync(dirname(this.path), { recursive: true });
+        writeFileSync(this.path, JSON.stringify({ version: CACHE_VERSION, files }));
+    }
+}
+//# sourceMappingURL=hashCache.js.map

package/dist/cache/hashCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hashCache.js","sourceRoot":"","sources":["../../src/cache/hashCache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAG1C,yEAAyE;AACzE,MAAM,aAAa,GAAG,CAAC,CAAC;AAOxB;;;GAGG;AACH,MAAM,OAAO,SAAS;IACH,IAAI,CAAS;IACtB,IAAI,CAAa;IACzB,mEAAmE;IAClD,IAAI,GAAG,IAAI,GAAG,EAA8C,CAAC;IAE9E,YAAY,IAAY;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC;QAC9C,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC1B,CAAC;IAEO,IAAI;QACV,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;QACzE,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAe,CAAC;YACzE,IAAI,MAAM,CAAC,OAAO,KAAK,aAAa;gBAAE,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;YACnF,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;QAC/C,CAAC;IACH,CAAC;IAED,6EAA6E;IAC7E,GAAG,CAAC,IAAY,EAAE,IAAY;QAC5B,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACpC,OAAO,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IAChE,CAAC;IAED,oFAAoF;IACpF,GAAG,CAAC,IAAY,EAAE,IAAY,EAAE,KAAgB;QAC9C,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACvC,CAAC;IAED,oEAAoE;IACpE,IAAI;QACF,MAAM,KAAK,GAAwB,EAAE,CAAC;QACtC,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,IAAI;YAAE,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;QAC3D,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACnD,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;IAC9E,CAAC;CACF"}

package/dist/claims/parseBlock.d.ts

@@ -0,0 +1,4 @@
+import type { KeelConfig } from "../config.js";
+import type { Claims } from "../types.js";
+/** Load and parse claims from the configured context files in `root`. */
+export declare function parseClaims(root: string, config: KeelConfig): Claims;

package/dist/claims/parseBlock.js

@@ -0,0 +1,66 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { lineHasIgnore } from "../suppress.js";
+function sectionOf(heading) {
+    const h = heading.toLowerCase();
+    if (h.includes("constraint"))
+        return "constraints";
+    if (h.includes("stack") || h.includes("tech"))
+        return "stack";
+    return "other";
+}
+/** Normalize a stack key: "Package manager" -> "package manager". */
+function normalizeKey(raw) {
+    return raw.trim().toLowerCase().replace(/\s+/g, " ");
+}
+/** Parse the structured `## Stack` / `## Constraints` blocks from one file. */
+function parseFile(content, source) {
+    const stack = [];
+    const constraints = [];
+    let section = "other";
+    const lines = content.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const heading = /^#{1,6}\s+(.*)$/.exec(line);
+        if (heading) {
+            section = sectionOf(heading[1]);
+            continue;
+        }
+        const bullet = /^\s*[-*]\s+(.*)$/.exec(line);
+        if (!bullet)
+            continue;
+        // Inline suppression: a marker on this line or the line above skips the claim.
+        if (lineHasIgnore(line) || lineHasIgnore(lines[i - 1]))
+            continue;
+        const text = bullet[1].trim();
+        if (section === "stack") {
+            const kv = /^([^:]+):\s*(.+)$/.exec(text);
+            if (kv) {
+                stack.push({ key: normalizeKey(kv[1]), value: kv[2].trim(), source, line: i + 1 });
+            }
+        }
+        else if (section === "constraints") {
+            constraints.push({ key: "constraint", value: text.replace(/`/g, ""), source, line: i + 1 });
+        }
+    }
+    return { stack, constraints };
+}
+/** Load and parse claims from the configured context files in `root`. */
+export function parseClaims(root, config) {
+    const merged = { stack: [], constraints: [] };
+    for (const name of config.claims.sources) {
+        const path = join(root, name);
+        if (!existsSync(path))
+            continue;
+        try {
+            const parsed = parseFile(readFileSync(path, "utf8"), name);
+            merged.stack.push(...parsed.stack);
+            merged.constraints.push(...parsed.constraints);
+        }
+        catch {
+            // unreadable context file — skip
+        }
+    }
+    return merged;
+}
+//# sourceMappingURL=parseBlock.js.map

package/dist/claims/parseBlock.js.map

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

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import pc from "picocolors";
+import { resolve } from "node:path";
+import { loadConfig } from "./config.js";
+import { loadFacts } from "./extract/scan.js";
+import { parseClaims } from "./claims/parseBlock.js";
+import { analyze } from "./analyze/index.js";
+import { loadKeelignore } from "./suppress.js";
+import { renderText, sortFindings, DEFAULT_FINDING_LIMIT } from "./report/text.js";
+import { renderJson } from "./report/json.js";
+import { renderMarkdown, improvementSummary } from "./report/markdown.js";
+import { suggestImprovements } from "./llm/improve.js";
+import { writeFileSync } from "node:fs";
+import { resolveProvider } from "./llm/provider.js";
+import { LLMCache } from "./llm/cache.js";
+import { explainFindings } from "./llm/explain.js";
+import { extractClaimsFromDocs, mergeInferredClaims } from "./llm/claimsFromDocs.js";
+import { startMcpServer } from "./mcp/server.js";
+const program = new Command();
+program
+    .name("keel")
+    .description("A local-first verifier that keeps an AI coding agent honest.")
+    .version("0.0.0");
+program
+    .command("check", { isDefault: true })
+    .description("Scan a repo and report drift, library conflicts, and duplication.")
+    .argument("[path]", "path to the repository to scan", ".")
+    .option("--json", "print the report as JSON")
+    .option("--facts", "print raw extracted Facts as JSON (debug)")
+    .option("-v, --verbose", "show finding details")
+    .option("--limit <n>", "max findings to print in text mode (default 25)", parseInt)
+    .option("--no-cache", "do not read or write the .keel cache (read-only run)")
+    .option("--no-gitignore", "scan files even if they are listed in .gitignore")
+    .option("--no-python", "skip Python files (don't load the Python parser)")
+    .option("--llm", "add plain-language explanations via your claude/codex CLI or an API key")
+    .option("--output-md [file]", "write a full Markdown report to a file (default keel-report.md)")
+    .option("--fail-under <score>", "exit non-zero if the Coherence Score is below this", parseFloat)
+    .action(async (path, opts) => {
+    const root = resolve(path);
+    const config = loadConfig(root);
+    const respectGitignore = opts.gitignore === false ? false : config.scan.respectGitignore;
+    // LLM setup (once) — off by default; powers both Tier-2 doc-claim extraction
+    // and plain-language explanations. Resolved before analyze so inferred claims
+    // can flow through the deterministic drift engine.
+    const llmEnabled = opts.llm === true || config.llm.enabled;
+    const provider = llmEnabled ? await resolveProvider(config) : undefined;
+    const llmCache = llmEnabled ? new LLMCache(root, opts.cache !== false) : undefined;
+    const llmLabel = provider?.name;
+    const t0 = process.hrtime.bigint();
+    const { facts, reused, parsed, skipped, unsupported } = await loadFacts(root, config, {
+        persistCache: opts.cache !== false,
+        respectGitignore,
+        pythonEnabled: opts.python !== false,
+    });
+    let claims = parseClaims(root, config);
+    const suppressions = loadKeelignore(root);
+    let durationMs = Number(process.hrtime.bigint() - t0) / 1e6;
+    // Tier-2 doc drift: extend claims with ones the LLM infers from prose (untimed).
+    if (provider && llmCache) {
+        const inferred = await extractClaimsFromDocs(root, config, provider, llmCache);
+        claims = { ...claims, stack: mergeInferredClaims(claims.stack, inferred) };
+    }
+    const analyzeStart = process.hrtime.bigint();
+    const { findings, score, breakdown } = analyze(facts, claims, config, suppressions);
+    durationMs += Number(process.hrtime.bigint() - analyzeStart) / 1e6;
+    if (opts.facts) {
+        process.stdout.write(JSON.stringify(facts, null, 2) + "\n");
+        return;
+    }
+    const report = {
+        score,
+        breakdown,
+        findings,
+        stats: { filesScanned: facts.files.length, durationMs, costUsd: 0 },
+    };
+    // LLM extras (off by default): per-finding explanations + how-to-improve plan.
+    if (provider && llmCache && findings.length > 0) {
+        const limit = opts.limit && opts.limit > 0 ? opts.limit : DEFAULT_FINDING_LIMIT;
+        await explainFindings(sortFindings(findings).slice(0, limit), provider, llmCache);
+    }
+    let improvement = improvementSummary(report);
+    if (provider && llmCache) {
+        const plan = await suggestImprovements(report, provider, llmCache);
+        if (plan)
+            improvement = plan;
+    }
+    llmCache?.save();
+    // Optional full Markdown report — written to the cwd, never into the scanned repo.
+    let reportFile;
+    if (opts.outputMd !== undefined) {
+        reportFile = typeof opts.outputMd === "string" ? opts.outputMd : "keel-report.md";
+        writeFileSync(resolve(reportFile), renderMarkdown(report, improvement));
+    }
+    if (opts.json) {
+        process.stdout.write(renderJson(report) + "\n");
+        if (reportFile)
+            process.stderr.write(`report written to ${reportFile}\n`);
+    }
+    else {
+        process.stdout.write(renderText(report, { verbose: opts.verbose, limit: opts.limit }) + "\n");
+        if (unsupported > 0) {
+            process.stdout.write(pc.yellow(`  ⚠ ${unsupported} Python file${unsupported === 1 ? "" : "s"} not analyzed`) +
+                pc.dim(" (Python parsing is off — the score reflects only the files keel read)\n"));
+        }
+        if (llmLabel !== undefined) {
+            const note = llmLabel === "off" ? "no provider found — install claude/codex or set an API key" : llmLabel;
+            process.stdout.write(pc.dim(`  llm: ${note}\n`));
+        }
+        const skippedNote = skipped > 0 ? `, skipped ${skipped} generated` : "";
+        process.stdout.write(pc.dim(`  (parsed ${parsed}, cached ${reused}${skippedNote})\n\n`));
+        // When the LLM is on, show how to raise the score (the deterministic
+        // summary is always in the Markdown report; keep the terminal opt-in).
+        if (llmLabel && llmLabel !== "off" && findings.length > 0) {
+            const plain = improvement.replace(/\*\*/g, "").split("\n").map((l) => `  ${l}`).join("\n");
+            process.stdout.write(`  ${pc.bold("How to improve")}\n${pc.dim(plain)}\n\n`);
+        }
+        if (reportFile)
+            process.stdout.write(pc.dim(`  report written to ${reportFile}\n\n`));
+    }
+    if (opts.failUnder !== undefined && score < opts.failUnder) {
+        process.exitCode = 1;
+    }
+});
+program
+    .command("mcp")
+    .description("Run keel as an MCP server (stdio) so an agent can query it before writing code")
+    .argument("[path]", "repository root to serve", ".")
+    .action(async (path) => {
+    await startMcpServer(resolve(path));
+});
+program.parseAsync(process.argv).catch((err) => {
+    process.stderr.write(pc.red(`keel: ${err instanceof Error ? err.message : String(err)}\n`));
+    process.exitCode = 1;
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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