@curiousnerd/keel 0.1.0

package/dist/extract/python.js

@@ -0,0 +1,244 @@
+import { createRequire } from "node:module";
+import Parser from "web-tree-sitter";
+import { sha1 } from "../util/hash.js";
+import { computeFingerprints } from "../util/fingerprint.js";
+import { classifyCasing, emptyNamingStats } from "./naming.js";
+const require = createRequire(import.meta.url);
+let parserPromise = null;
+/** Initialize web-tree-sitter once and load the Python grammar (cached). */
+async function getParser() {
+    if (!parserPromise) {
+        parserPromise = (async () => {
+            await Parser.init();
+            const parser = new Parser();
+            const wasmPath = require.resolve("tree-sitter-wasms/out/tree-sitter-python.wasm");
+            const Python = await Parser.Language.load(wasmPath);
+            parser.setLanguage(Python);
+            return parser;
+        })();
+    }
+    return parserPromise;
+}
+/** Create a Python extractor (loads the grammar on first call, then reuses it). */
+export async function createPythonExtractor() {
+    const parser = await getParser();
+    return {
+        extractFile(content, filePath, minTokens) {
+            const tree = parser.parse(content);
+            try {
+                return {
+                    imports: extractImports(tree.rootNode),
+                    functions: extractFunctions(tree.rootNode, minTokens, filePath),
+                    naming: extractNaming(tree.rootNode),
+                };
+            }
+            finally {
+                tree.delete();
+            }
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Traversal helpers
+// ---------------------------------------------------------------------------
+function* walk(node) {
+    yield node;
+    for (let i = 0; i < node.childCount; i++) {
+        const child = node.child(i);
+        if (child)
+            yield* walk(child);
+    }
+}
+/** Text of the first `identifier` descendant (the top-level name). */
+function firstIdentifier(node) {
+    if (node.type === "identifier")
+        return node.text;
+    for (let i = 0; i < node.childCount; i++) {
+        const child = node.child(i);
+        if (!child)
+            continue;
+        const found = firstIdentifier(child);
+        if (found)
+            return found;
+    }
+    return null;
+}
+/** Top-level module of a dotted name: "os.path" -> "os". */
+const topModule = (dotted) => dotted.split(".")[0] ?? dotted;
+// ---------------------------------------------------------------------------
+// Imports
+// ---------------------------------------------------------------------------
+function extractImports(root) {
+    const facts = [];
+    for (const node of walk(root)) {
+        if (node.type === "import_statement") {
+            // import os, sys   |   import numpy as np
+            for (let i = 0; i < node.namedChildCount; i++) {
+                const child = node.namedChild(i);
+                if (!child)
+                    continue;
+                const nameNode = child.type === "aliased_import" ? child.childForFieldName("name") : child;
+                const id = nameNode ? firstIdentifier(nameNode) : null;
+                if (id) {
+                    facts.push({ specifier: nameNode.text, external: true, packageName: topModule(id), named: [], line: node.startPosition.row + 1 });
+                }
+            }
+        }
+        else if (node.type === "import_from_statement") {
+            // from x.y import a, b   |   from . import c   |   from .mod import d
+            const moduleName = node.childForFieldName("module_name");
+            const relative = !moduleName || moduleName.type === "relative_import" || moduleName.text.startsWith(".");
+            const id = moduleName ? firstIdentifier(moduleName) : null;
+            facts.push({
+                specifier: moduleName?.text ?? ".",
+                external: !relative,
+                packageName: relative || !id ? null : topModule(id),
+                named: [],
+                line: node.startPosition.row + 1,
+            });
+        }
+    }
+    return facts;
+}
+// ---------------------------------------------------------------------------
+// Functions (with normalized body hashing + fingerprints)
+// ---------------------------------------------------------------------------
+/** Collect identifier leaves of a node, skipping comments. */
+function collectLeaves(node, out) {
+    if (node.type === "comment")
+        return;
+    if (node.childCount === 0) {
+        out.push(node);
+        return;
+    }
+    for (let i = 0; i < node.childCount; i++) {
+        const child = node.child(i);
+        if (child)
+            collectLeaves(child, out);
+    }
+}
+/** Names bound locally inside a function: parameters + assignment/for targets. */
+function collectLocals(fn) {
+    const locals = new Set();
+    const params = fn.childForFieldName("parameters");
+    if (params) {
+        for (let i = 0; i < params.namedChildCount; i++) {
+            const id = firstIdentifier(params.namedChild(i));
+            if (id)
+                locals.add(id);
+        }
+    }
+    const body = fn.childForFieldName("body");
+    if (body) {
+        for (const node of walk(body)) {
+            if (node.type === "assignment" || node.type === "augmented_assignment") {
+                const left = node.childForFieldName("left");
+                if (left)
+                    for (const id of identifiersInTarget(left))
+                        locals.add(id);
+            }
+            else if (node.type === "for_statement") {
+                const left = node.childForFieldName("left");
+                if (left)
+                    for (const id of identifiersInTarget(left))
+                        locals.add(id);
+            }
+        }
+    }
+    return locals;
+}
+/** Identifiers bound by an assignment/for target (skips attribute/subscript writes). */
+function identifiersInTarget(target) {
+    if (target.type === "identifier")
+        return [target.text];
+    // tuple/list/pattern_list of identifiers
+    const ids = [];
+    for (let i = 0; i < target.namedChildCount; i++) {
+        const child = target.namedChild(i);
+        if (child.type === "identifier")
+            ids.push(child.text);
+    }
+    return ids;
+}
+/** Normalize a function body into a token stream (locals renamed, members kept). */
+function normalizeBody(body, locals) {
+    const leaves = [];
+    collectLeaves(body, leaves);
+    const tokens = [];
+    const placeholders = new Map();
+    let prevType;
+    for (const leaf of leaves) {
+        const afterDot = prevType === ".";
+        if (leaf.type === "identifier" && !afterDot && locals.has(leaf.text)) {
+            let ph = placeholders.get(leaf.text);
+            if (!ph) {
+                ph = `_v${placeholders.size}`;
+                placeholders.set(leaf.text, ph);
+            }
+            tokens.push(ph);
+        }
+        else {
+            tokens.push(leaf.text);
+        }
+        prevType = leaf.type;
+    }
+    return tokens;
+}
+function extractFunctions(root, minTokens, filePath) {
+    const facts = [];
+    for (const node of walk(root)) {
+        if (node.type !== "function_definition")
+            continue;
+        const nameNode = node.childForFieldName("name");
+        const body = node.childForFieldName("body");
+        if (!body)
+            continue;
+        const tokens = normalizeBody(body, collectLocals(node));
+        const tokenCount = tokens.length;
+        const passesGate = tokenCount >= minTokens;
+        const params = node.childForFieldName("parameters");
+        facts.push({
+            name: nameNode?.text ?? null,
+            filePath,
+            startLine: node.startPosition.row + 1,
+            endLine: node.endPosition.row + 1,
+            bodyHash: passesGate ? sha1(tokens.join(" ")) : null,
+            tokenCount,
+            fingerprints: passesGate ? computeFingerprints(tokens) : [],
+            signature: `(${params ? params.namedChildCount : 0})`,
+        });
+    }
+    return facts;
+}
+// ---------------------------------------------------------------------------
+// Naming
+// ---------------------------------------------------------------------------
+function extractNaming(root) {
+    const stats = emptyNamingStats();
+    const tally = (name) => {
+        if (!name || name.startsWith("_"))
+            return;
+        stats[classifyCasing(name)] += 1;
+    };
+    for (const node of walk(root)) {
+        if (node.type === "function_definition") {
+            tally(node.childForFieldName("name")?.text);
+            const params = node.childForFieldName("parameters");
+            if (params) {
+                for (let i = 0; i < params.namedChildCount; i++) {
+                    const id = firstIdentifier(params.namedChild(i));
+                    if (id && id !== "self" && id !== "cls")
+                        tally(id);
+                }
+            }
+        }
+        else if (node.type === "assignment") {
+            const left = node.childForFieldName("left");
+            if (left)
+                for (const id of identifiersInTarget(left))
+                    tally(id);
+        }
+    }
+    return stats;
+}
+//# sourceMappingURL=python.js.map

package/dist/extract/python.js.map

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

package/dist/extract/scan.d.ts

@@ -0,0 +1,12 @@
+import type { KeelConfig } from "../config.js";
+import { type ExtractOptions, type ExtractResult } from "./index.js";
+export interface ScanOptions extends ExtractOptions {
+    /** Whether Python parsing is allowed (the CLI's --no-python maps to false). */
+    pythonEnabled?: boolean;
+}
+/**
+ * Extract Facts for a repo, loading the Python parser only when the repo
+ * actually contains `.py` files (so JS-only scans pay nothing). Shared by the
+ * CLI and the MCP server.
+ */
+export declare function loadFacts(root: string, config: KeelConfig, opts?: ScanOptions): Promise<ExtractResult>;

package/dist/extract/scan.js

@@ -0,0 +1,16 @@
+import { extract } from "./index.js";
+import { walkSourceFiles } from "./walk.js";
+import { createPythonExtractor } from "./python.js";
+/**
+ * Extract Facts for a repo, loading the Python parser only when the repo
+ * actually contains `.py` files (so JS-only scans pay nothing). Shared by the
+ * CLI and the MCP server.
+ */
+export async function loadFacts(root, config, opts = {}) {
+    const respectGitignore = opts.respectGitignore ?? config.scan.respectGitignore;
+    const pythonEnabled = (opts.pythonEnabled ?? true) && config.python.enabled;
+    const hasPython = pythonEnabled && walkSourceFiles(root, { respectGitignore }).some((p) => p.endsWith(".py"));
+    const pythonExtractor = hasPython ? await createPythonExtractor() : undefined;
+    return extract(root, config, { ...opts, respectGitignore, pythonExtractor });
+}
+//# sourceMappingURL=scan.js.map

package/dist/extract/scan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.js","sourceRoot":"","sources":["../../src/extract/scan.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAA2C,MAAM,YAAY,CAAC;AAC9E,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAOpD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,IAAY,EAAE,MAAkB,EAAE,OAAoB,EAAE;IACtF,MAAM,gBAAgB,GAAG,IAAI,CAAC,gBAAgB,IAAI,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC;IAC/E,MAAM,aAAa,GAAG,CAAC,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC;IAC5E,MAAM,SAAS,GAAG,aAAa,IAAI,eAAe,CAAC,IAAI,EAAE,EAAE,gBAAgB,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;IAC9G,MAAM,eAAe,GAAG,SAAS,CAAC,CAAC,CAAC,MAAM,qBAAqB,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAC9E,OAAO,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,IAAI,EAAE,gBAAgB,EAAE,eAAe,EAAE,CAAC,CAAC;AAC/E,CAAC"}

package/dist/extract/symbols.d.ts

@@ -0,0 +1,9 @@
+import { type SourceFile } from "ts-morph";
+import type { FunctionFact } from "../types.js";
+/**
+ * Extract function/method facts from a source file.
+ * Bodies below `minTokens` significant tokens get a null hash and no
+ * fingerprints (excluded from duplication detection) to avoid flagging
+ * trivial one-liners.
+ */
+export declare function extractFunctions(sourceFile: SourceFile, minTokens: number, filePath: string): FunctionFact[];

package/dist/extract/symbols.js

@@ -0,0 +1,120 @@
+import { Node, SyntaxKind, ts } from "ts-morph";
+import { sha1 } from "../util/hash.js";
+import { computeFingerprints } from "../util/fingerprint.js";
+/** Best-effort human name for a function-like node (null for true anonymous). */
+function functionName(node) {
+    if (Node.isFunctionDeclaration(node) || Node.isMethodDeclaration(node)) {
+        return node.getName() ?? null;
+    }
+    // Function expression / arrow: name comes from how it's bound.
+    const parent = node.getParent();
+    if (Node.isVariableDeclaration(parent)) {
+        const nameNode = parent.getNameNode();
+        return Node.isIdentifier(nameNode) ? nameNode.getText() : null;
+    }
+    if (Node.isPropertyAssignment(parent) || Node.isPropertyDeclaration(parent)) {
+        return parent.getName();
+    }
+    return null;
+}
+/** All identifier texts declared locally (params + locally-declared variables). */
+function collectLocals(node) {
+    const locals = new Set();
+    for (const param of node.getParameters()) {
+        for (const id of param.getNameNode().getDescendantsOfKind(SyntaxKind.Identifier)) {
+            locals.add(id.getText());
+        }
+        if (Node.isIdentifier(param.getNameNode()))
+            locals.add(param.getNameNode().getText());
+    }
+    const body = node.getBody();
+    if (body) {
+        for (const decl of body.getDescendantsOfKind(SyntaxKind.VariableDeclaration)) {
+            const nameNode = decl.getNameNode();
+            if (Node.isIdentifier(nameNode)) {
+                locals.add(nameNode.getText());
+            }
+            else {
+                for (const id of nameNode.getDescendantsOfKind(SyntaxKind.Identifier)) {
+                    locals.add(id.getText());
+                }
+            }
+        }
+    }
+    return locals;
+}
+/**
+ * Normalize a function body into a token stream:
+ *  - comments and whitespace are dropped (scanner skips trivia)
+ *  - local identifiers (params + locals) are renamed to positional placeholders
+ *    so two bodies identical up to local naming hash the same
+ *  - member names after `.`/`?.` are left intact (not treated as locals)
+ *  - literals are kept verbatim, keeping "exact" conservative
+ */
+function normalizeBody(bodyText, locals) {
+    const scanner = ts.createScanner(ts.ScriptTarget.Latest, 
+    /* skipTrivia */ true, ts.LanguageVariant.Standard, bodyText);
+    const tokens = [];
+    const placeholders = new Map();
+    let prevKind;
+    let kind = scanner.scan();
+    while (kind !== ts.SyntaxKind.EndOfFileToken) {
+        const afterDot = prevKind === ts.SyntaxKind.DotToken || prevKind === ts.SyntaxKind.QuestionDotToken;
+        if (kind === ts.SyntaxKind.Identifier) {
+            const text = scanner.getTokenText();
+            if (!afterDot && locals.has(text)) {
+                let ph = placeholders.get(text);
+                if (!ph) {
+                    ph = `_v${placeholders.size}`;
+                    placeholders.set(text, ph);
+                }
+                tokens.push(ph);
+            }
+            else {
+                tokens.push(text);
+            }
+        }
+        else {
+            tokens.push(scanner.getTokenText());
+        }
+        prevKind = kind;
+        kind = scanner.scan();
+    }
+    return tokens;
+}
+/**
+ * Extract function/method facts from a source file.
+ * Bodies below `minTokens` significant tokens get a null hash and no
+ * fingerprints (excluded from duplication detection) to avoid flagging
+ * trivial one-liners.
+ */
+export function extractFunctions(sourceFile, minTokens, filePath) {
+    const nodes = [
+        ...sourceFile.getDescendantsOfKind(SyntaxKind.FunctionDeclaration),
+        ...sourceFile.getDescendantsOfKind(SyntaxKind.MethodDeclaration),
+        ...sourceFile.getDescendantsOfKind(SyntaxKind.FunctionExpression),
+        ...sourceFile.getDescendantsOfKind(SyntaxKind.ArrowFunction),
+    ];
+    const facts = [];
+    for (const node of nodes) {
+        const body = node.getBody();
+        if (!body)
+            continue;
+        const locals = collectLocals(node);
+        const tokens = normalizeBody(body.getText(), locals);
+        const tokenCount = tokens.length;
+        const passesGate = tokenCount >= minTokens;
+        facts.push({
+            name: functionName(node),
+            filePath,
+            startLine: node.getStartLineNumber(),
+            endLine: node.getEndLineNumber(),
+            bodyHash: passesGate ? sha1(tokens.join(" ")) : null,
+            tokenCount,
+            fingerprints: passesGate ? computeFingerprints(tokens) : [],
+            signature: `(${node.getParameters().length})`,
+        });
+    }
+    return facts;
+}
+//# sourceMappingURL=symbols.js.map

package/dist/extract/symbols.js.map

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

package/dist/extract/walk.d.ts

@@ -0,0 +1,10 @@
+/** Directories we never descend into, regardless of .gitignore. */
+export declare const DEFAULT_IGNORE_DIRS: Set<string>;
+export interface WalkOptions {
+    /** Skip files/dirs matched by .gitignore files (root + nested). Default true. */
+    respectGitignore?: boolean;
+}
+/** Enumerate analyzable source files (JS/TS/Python) under `root`. */
+export declare function walkSourceFiles(root: string, opts?: WalkOptions): string[];
+/** Enumerate Markdown documentation files under `root`. */
+export declare function walkMarkdownFiles(root: string, opts?: WalkOptions): string[];

package/dist/extract/walk.js

@@ -0,0 +1,115 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import ignore from "ignore";
+// `ignore` is a CommonJS callable, but NodeNext's types surface it as a
+// namespace, so cast to its real call signature. Runtime is unaffected.
+const createIgnore = ignore;
+/** Directories we never descend into, regardless of .gitignore. */
+export const DEFAULT_IGNORE_DIRS = new Set([
+    "node_modules",
+    ".git",
+    ".keel",
+    "dist",
+    "build",
+    "out",
+    "coverage",
+    ".next",
+    ".turbo",
+    ".cache",
+    // Generated / vendored code — never hand-written, so never our concern.
+    "generated",
+    "__generated__",
+    ".prisma",
+    "vendor",
+]);
+const SOURCE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".py"];
+function isSourceFile(name) {
+    if (name.endsWith(".d.ts"))
+        return false;
+    return SOURCE_EXTENSIONS.some((ext) => name.endsWith(ext));
+}
+function loadLayer(absDir, relDir) {
+    const path = join(absDir, ".gitignore");
+    if (!existsSync(path))
+        return null;
+    try {
+        return { base: relDir, ig: createIgnore().add(readFileSync(path, "utf8")) };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Test a path against every active .gitignore layer. Each layer matches the
+ * path relative to its own directory (git's semantics). Directories are tested
+ * with a trailing slash so directory-only patterns (`dist/`) match.
+ */
+function isIgnored(layers, relPath, isDir) {
+    for (const { base, ig } of layers) {
+        const sub = base ? relPath.slice(base.length + 1) : relPath;
+        if (!sub)
+            continue;
+        if (ig.ignores(isDir ? `${sub}/` : sub))
+            return true;
+    }
+    return false;
+}
+/**
+ * Recursively enumerate files under `root` for which `accept(filename)` is
+ * true, honoring .gitignore. Returns paths relative to `root` with POSIX
+ * separators, sorted.
+ */
+function walk(root, accept, opts) {
+    const respectGitignore = opts.respectGitignore ?? true;
+    const found = [];
+    const recurse = (absDir, relDir, layers) => {
+        let entries;
+        try {
+            entries = readdirSync(absDir);
+        }
+        catch {
+            return; // unreadable directory — skip
+        }
+        // A .gitignore in this directory applies to everything beneath it.
+        let activeLayers = layers;
+        if (respectGitignore) {
+            const layer = loadLayer(absDir, relDir);
+            if (layer)
+                activeLayers = [...layers, layer];
+        }
+        for (const entry of entries) {
+            const abs = join(absDir, entry);
+            const relPath = relDir ? `${relDir}/${entry}` : entry;
+            let stat;
+            try {
+                stat = statSync(abs);
+            }
+            catch {
+                continue; // broken symlink etc.
+            }
+            if (stat.isDirectory()) {
+                if (DEFAULT_IGNORE_DIRS.has(entry) || entry.startsWith("."))
+                    continue;
+                if (respectGitignore && isIgnored(activeLayers, relPath, true))
+                    continue;
+                recurse(abs, relPath, activeLayers);
+            }
+            else if (stat.isFile() && accept(entry)) {
+                if (respectGitignore && isIgnored(activeLayers, relPath, false))
+                    continue;
+                found.push(relPath);
+            }
+        }
+    };
+    recurse(root, "", []);
+    return found.sort();
+}
+/** Enumerate analyzable source files (JS/TS/Python) under `root`. */
+export function walkSourceFiles(root, opts = {}) {
+    return walk(root, isSourceFile, opts);
+}
+/** Enumerate Markdown documentation files under `root`. */
+export function walkMarkdownFiles(root, opts = {}) {
+    return walk(root, (name) => name.endsWith(".md") || name.endsWith(".mdx"), opts);
+}
+//# sourceMappingURL=walk.js.map

package/dist/extract/walk.js.map

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

package/dist/llm/cache.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A tiny content-addressed cache for LLM responses, persisted at
+ * `.keel/llm-cache.json`. Keyed by provider + prompt, so identical requests on
+ * a re-run cost nothing. Disabled (in-memory, never written) under --no-cache.
+ */
+export declare class LLMCache {
+    private readonly enabled;
+    private readonly path;
+    private data;
+    private dirty;
+    constructor(root: string, enabled: boolean);
+    private load;
+    private key;
+    get(providerName: string, prompt: string): string | undefined;
+    set(providerName: string, prompt: string, value: string): void;
+    save(): void;
+}

package/dist/llm/cache.js

@@ -0,0 +1,50 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { sha1 } from "../util/hash.js";
+/**
+ * A tiny content-addressed cache for LLM responses, persisted at
+ * `.keel/llm-cache.json`. Keyed by provider + prompt, so identical requests on
+ * a re-run cost nothing. Disabled (in-memory, never written) under --no-cache.
+ */
+export class LLMCache {
+    enabled;
+    path;
+    data;
+    dirty = false;
+    constructor(root, enabled) {
+        this.enabled = enabled;
+        this.path = join(root, ".keel", "llm-cache.json");
+        this.data = this.load();
+    }
+    load() {
+        if (!this.enabled || !existsSync(this.path))
+            return {};
+        try {
+            return JSON.parse(readFileSync(this.path, "utf8"));
+        }
+        catch {
+            return {};
+        }
+    }
+    key(providerName, prompt) {
+        return sha1(`${providerName}::${prompt}`);
+    }
+    get(providerName, prompt) {
+        if (!this.enabled)
+            return undefined;
+        return this.data[this.key(providerName, prompt)];
+    }
+    set(providerName, prompt, value) {
+        if (!this.enabled)
+            return;
+        this.data[this.key(providerName, prompt)] = value;
+        this.dirty = true;
+    }
+    save() {
+        if (!this.enabled || !this.dirty)
+            return;
+        mkdirSync(dirname(this.path), { recursive: true });
+        writeFileSync(this.path, JSON.stringify(this.data));
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/llm/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/llm/cache.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;AAC1C,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAEvC;;;;GAIG;AACH,MAAM,OAAO,QAAQ;IAOA;IANF,IAAI,CAAS;IACtB,IAAI,CAAyB;IAC7B,KAAK,GAAG,KAAK,CAAC;IAEtB,YACE,IAAY,EACK,OAAgB;QAAhB,YAAO,GAAP,OAAO,CAAS;QAEjC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,gBAAgB,CAAC,CAAC;QAClD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC1B,CAAC;IAEO,IAAI;QACV,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,OAAO,EAAE,CAAC;QACvD,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAA2B,CAAC;QAC/E,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;IAEO,GAAG,CAAC,YAAoB,EAAE,MAAc;QAC9C,OAAO,IAAI,CAAC,GAAG,YAAY,KAAK,MAAM,EAAE,CAAC,CAAC;IAC5C,CAAC;IAED,GAAG,CAAC,YAAoB,EAAE,MAAc;QACtC,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO,SAAS,CAAC;QACpC,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,CAAC;IAED,GAAG,CAAC,YAAoB,EAAE,MAAc,EAAE,KAAa;QACrD,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO;QAC1B,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,GAAG,KAAK,CAAC;QAClD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED,IAAI;QACF,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK;YAAE,OAAO;QACzC,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,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACtD,CAAC;CACF"}

package/dist/llm/claimsFromDocs.d.ts

@@ -0,0 +1,16 @@
+import type { KeelConfig } from "../config.js";
+import type { Claim } from "../types.js";
+import type { LLMProvider } from "./provider.js";
+import type { LLMCache } from "./cache.js";
+/**
+ * Tier 2 of doc/knowledge drift: use the LLM to extract checkable stack claims
+ * from freeform documentation prose. The LLM only turns English into claims —
+ * the deterministic drift engine still does the verifying. Returns [] on any
+ * failure or when no provider is available. Cached by prompt.
+ */
+export declare function extractClaimsFromDocs(root: string, config: KeelConfig, provider: LLMProvider, cache: LLMCache): Promise<Claim[]>;
+/**
+ * Add inferred stack claims that the structured block didn't already cover.
+ * Structured claims always win (a hand-written `## Stack` beats prose inference).
+ */
+export declare function mergeInferredClaims(existing: Claim[], inferred: Claim[]): Claim[];