knodin 0.7.4 → 0.7.6

package/dist/src/engine/embeddings.js

@@ -1,193 +0,0 @@
-/**
- * Local-only by design (ADR 003, "Future Considerations" section,
- * docs/adr/003-local-semantic-search.md): a cloud embedding provider
- * (OpenAI/Google/MiniMax, as some competitors offer) was evaluated and
- * deliberately deferred, not merely unbuilt. knodin's core positioning is
- * zero-auth/local-first/no-egress — sending symbol text to a cloud API for
- * embedding would break that guarantee for every indexed repo, not just tune
- * a knob. If ever added, it must be opt-in with `local` staying the default,
- * and reads as a natural pro-tier feature precisely because enabling it is a
- * deliberate trade against this file's local/no-egress guarantee.
- */
-import os from "node:os";
-import path from "node:path";
-let embedderPromise = null;
-let embedderOverride = null;
-const embedderProgressListeners = new Set();
-let embedderReady = false;
-const EMBEDDING_DIMENSIONS = 384;
-const DEFAULT_MODEL_REMOTE_HOST = "https://huggingface.co/";
-/**
- * One machine-level model cache shared by every repository and every installed
- * knodin version. An explicit override makes managed/offline environments and
- * the clean-package acceptance gate deterministic.
- */
-export function getModelCacheDirectory(options = {}) {
-    const environment = options.env ?? process.env;
-    const override = environment.KNODIN_MODEL_CACHE?.trim();
-    if (override)
-        return path.resolve(override);
-    const platform = options.platform ?? process.platform;
-    const home = options.home ?? os.homedir();
-    if (platform === "win32") {
-        return path.join(environment.LOCALAPPDATA || path.join(home, "AppData", "Local"), "knodin", "models");
-    }
-    if (platform === "darwin")
-        return path.join(home, "Library", "Caches", "knodin", "models");
-    return path.join(environment.XDG_CACHE_HOME || path.join(home, ".cache"), "knodin", "models");
-}
-/**
- * Remote model origin used only when the shared machine cache is cold.
- * The default remains the public Hugging Face Hub; managed environments may
- * point at an approved mirror without changing where model files are cached.
- */
-export function getModelRemoteHost(environment = process.env) {
-    const configured = environment.KNODIN_MODEL_HOST?.trim() || DEFAULT_MODEL_REMOTE_HOST;
-    let parsed;
-    try {
-        parsed = new URL(configured);
-    }
-    catch {
-        throw new Error(`KNODIN_MODEL_HOST must be an absolute HTTP(S) URL: ${configured}`);
-    }
-    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
-        throw new Error(`KNODIN_MODEL_HOST must use HTTP(S): ${configured}`);
-    }
-    parsed.hash = "";
-    parsed.search = "";
-    return parsed.href.endsWith("/") ? parsed.href : `${parsed.href}/`;
-}
-/**
- * Number of times the real ONNX model pipeline has actually been loaded in this
- * process. Observability only — it never changes embedding behavior. The test
- * suite uses it to guarantee that non-model suites keep the deterministic test
- * embedder installed and never fall through to native model initialization
- * (which, repeated across a long-lived worker, is what C50 removes).
- */
-let realEmbedderLoadCount = 0;
-/** Returns how many times the real ONNX pipeline has loaded in this process. */
-export function getRealEmbedderLoadCount() {
-    return realEmbedderLoadCount;
-}
-/**
- * Overrides the embedding pipeline (e.g. with a fast mock in tests). Pass `null`
- * to clear the override and fall back to the real lazily-loaded model.
- */
-export function setEmbedder(pipeline) {
-    embedderOverride = pipeline;
-    embedderPromise = null;
-    embedderReady = pipeline !== null;
-}
-/**
- * Release the native ONNX model session if one was loaded, freeing its resident
- * memory. Best-effort and test-facing: the single long-lived test worker
- * (isolate:false) otherwise keeps the ~model resident for the whole run, bloating
- * the process so later subprocess-spawning tests fork slowly. The dedicated
- * embedding spec calls this in teardown once its real-model assertions are done.
- * A no-op when only a mock embedder (or nothing) has been used.
- */
-export async function disposeEmbedder() {
-    const pending = embedderPromise;
-    embedderPromise = null;
-    embedderReady = false;
-    if (!pending)
-        return;
-    try {
-        const pipe = (await pending);
-        if (typeof pipe.dispose === "function")
-            await pipe.dispose();
-    }
-    catch {
-        /* best-effort native teardown; never fail a test on dispose */
-    }
-}
-/**
- * Lazy-loads and caches the local embedding pipeline.
- * Uses a lightweight, high-performance 384-dimension model (all-MiniLM-L6-v2)
- * running in-process via ONNX Runtime Web.
- * Uses dynamic imports to keep CLI and MCP server startup latency near-zero.
- */
-export function getEmbedder(onProgress) {
-    if (embedderOverride) {
-        onProgress?.({ status: "ready", name: "local test embedder" });
-        return Promise.resolve(embedderOverride);
-    }
-    if (onProgress && embedderReady)
-        onProgress({ status: "ready", name: "Xenova/all-MiniLM-L6-v2" });
-    else if (onProgress)
-        embedderProgressListeners.add(onProgress);
-    if (!embedderPromise) {
-        embedderPromise = (async () => {
-            try {
-                const { env, pipeline } = await import("@huggingface/transformers");
-                env.cacheDir = getModelCacheDirectory();
-                env.remoteHost = getModelRemoteHost();
-                const notify = (event) => {
-                    for (const listener of embedderProgressListeners) {
-                        try {
-                            listener(event);
-                        }
-                        catch {
-                            /* Observability must not alter model initialization. */
-                        }
-                    }
-                };
-                notify({ status: "loading", name: "Xenova/all-MiniLM-L6-v2" });
-                const pipe = await pipeline("feature-extraction", "Xenova/all-MiniLM-L6-v2", {
-                    progress_callback: notify,
-                });
-                realEmbedderLoadCount++;
-                embedderReady = true;
-                notify({ status: "ready", name: "Xenova/all-MiniLM-L6-v2" });
-                embedderProgressListeners.clear();
-                return pipe;
-            }
-            catch (error) {
-                embedderPromise = null; // Reset promise so we can retry on next call
-                embedderProgressListeners.clear();
-                console.error("Failed to initialize Hugging Face embedding pipeline:", error);
-                throw error;
-            }
-        })();
-    }
-    return embedderPromise;
-}
-/**
- * Generates a normalized Float32Array embedding (384 dimensions) for a given text block.
- */
-export async function generateEmbeddings(texts, onModelProgress) {
-    if (texts.length === 0)
-        return [];
-    const extractor = await getEmbedder(onModelProgress);
-    const result = await extractor([...texts], { pooling: "mean", normalize: true });
-    const data = result.data instanceof Float32Array ? result.data : Float32Array.from(result.data);
-    const dims = result.dims;
-    if (dims?.length !== 2 || dims[0] !== texts.length || dims[1] !== EMBEDDING_DIMENSIONS) {
-        throw new Error(`Unexpected batched embedding shape: expected [${texts.length}, ${EMBEDDING_DIMENSIONS}], got ${JSON.stringify(dims)}`);
-    }
-    const dimension = dims[1];
-    if (data.length !== texts.length * dimension) {
-        throw new Error(`Unexpected batched embedding data length: expected ${texts.length * dimension}, got ${data.length}`);
-    }
-    return texts.map((_, index) => data.slice(index * dimension, (index + 1) * dimension));
-}
-/** Compatibility wrapper used by query-time search. */
-export async function generateEmbedding(text) {
-    return (await generateEmbeddings([text]))[0];
-}
-/**
- * Computes the cosine similarity between two normalized Float32Arrays.
- * Since the vectors are pre-normalized, the cosine similarity simplifies
- * to the mathematical dot product: sum(u_i * v_i).
- */
-export function computeSimilarity(queryVec, targetVec) {
-    if (queryVec.length !== targetVec.length) {
-        throw new Error(`Embedding dimension mismatch: query has ${queryVec.length} dims, target has ${targetVec.length}`);
-    }
-    let dotProduct = 0;
-    const len = queryVec.length;
-    for (let i = 0; i < len; i++) {
-        dotProduct += queryVec[i] * targetVec[i];
-    }
-    return dotProduct;
-}

package/dist/src/engine/file-walker.js

@@ -1,43 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import { isIndexablePath } from "./prune.js";
-function comparePaths(left, right) {
-    return left < right ? -1 : left > right ? 1 : 0;
-}
-/**
- * Deterministically enumerate regular files beneath a repository without
- * following symlinks. Directory pruning happens before descent so dependency,
- * build, VCS, worktree, and local graph state never incur a recursive scan.
- */
-export function walkRepoFiles(repoPath, options = {}) {
-    const root = path.resolve(repoPath);
-    const pending = [{ absolute: root, relative: "" }];
-    const files = [];
-    while (pending.length > 0) {
-        const directory = pending.pop();
-        if (!directory)
-            break;
-        let entries;
-        try {
-            entries = fs.readdirSync(directory.absolute, { withFileTypes: true });
-        }
-        catch {
-            continue;
-        }
-        entries.sort((left, right) => comparePaths(left.name, right.name));
-        for (const entry of entries) {
-            const relative = directory.relative ? `${directory.relative}/${entry.name}` : entry.name;
-            if (!isIndexablePath(relative))
-                continue;
-            const absolute = path.join(directory.absolute, entry.name);
-            if (entry.isDirectory()) {
-                pending.push({ absolute, relative });
-            }
-            else if (entry.isFile() && (options.accept?.(relative) ?? true)) {
-                files.push(relative);
-            }
-        }
-    }
-    files.sort(comparePaths);
-    return options.limit === undefined ? files : files.slice(0, Math.max(0, options.limit));
-}

package/dist/src/engine/git-history.js

@@ -1,289 +0,0 @@
-import childProcess from "node:child_process";
-import path from "node:path";
-export const DEFAULT_GIT_HISTORY_BOUNDS = Object.freeze({
-    maxCommits: 250,
-    maxFiles: 25,
-    maxRelatedFiles: 100,
-    timeoutMs: 2_000,
-});
-const MAX_GIT_OUTPUT_BYTES = 8 * 1024 * 1024;
-const HISTORY_CACHE_LIMIT = 8;
-const historyCache = new Map();
-const INTERPRETATION = "Co-change and coupling are bounded historical correlation, not evidence of causation, defects, ownership, or required remediation.";
-function positiveBound(value, fallback, name, hardMaximum) {
-    const resolved = value ?? fallback;
-    if (!Number.isSafeInteger(resolved) || resolved < 1 || resolved > hardMaximum) {
-        throw new Error(`git history ${name} must be an integer between 1 and ${hardMaximum}`);
-    }
-    return resolved;
-}
-function resolveBounds(input) {
-    return {
-        maxCommits: positiveBound(input.maxCommits, DEFAULT_GIT_HISTORY_BOUNDS.maxCommits, "maxCommits", 10_000),
-        maxFiles: positiveBound(input.maxFiles, DEFAULT_GIT_HISTORY_BOUNDS.maxFiles, "maxFiles", 1_000),
-        maxRelatedFiles: positiveBound(input.maxRelatedFiles, DEFAULT_GIT_HISTORY_BOUNDS.maxRelatedFiles, "maxRelatedFiles", 10_000),
-        timeoutMs: positiveBound(input.timeoutMs, DEFAULT_GIT_HISTORY_BOUNDS.timeoutMs, "timeoutMs", 30_000),
-    };
-}
-function safeHistoryFile(file) {
-    const normalized = file.replaceAll("\\", "/").replace(/^\.\//, "");
-    if (!normalized ||
-        path.isAbsolute(normalized) ||
-        normalized === ".." ||
-        normalized.startsWith("../")) {
-        throw new Error(`git history file must be repo-relative: ${file}`);
-    }
-    return normalized;
-}
-function failureReason(error) {
-    const failure = error;
-    if (failure.code === "ENOENT")
-        return "git-unavailable";
-    if (failure.code === "ETIMEDOUT" || failure.signal === "SIGTERM" || failure.killed)
-        return "timeout";
-    const message = `${String(failure.message ?? error)}\n${String(failure.stderr ?? "")}`;
-    if (/not a git repository/i.test(message))
-        return "not-a-repository";
-    return "history-command-failed";
-}
-function isUnbornHeadFailure(error) {
-    const failure = error;
-    const diagnostic = `${String(failure.message ?? error)}\n${String(failure.stderr ?? "")}`;
-    return /needed a single revision|ambiguous argument ['"]?HEAD|unknown revision or path/i.test(diagnostic);
-}
-function emptyResult(availability, bounds, commands, omission, files = []) {
-    return {
-        availability,
-        bounds,
-        commands,
-        commitsAnalyzed: 0,
-        filesAnalyzed: files.length,
-        truncated: false,
-        churn: files.map((file) => ({ file, commitCount: 0, commits: [] })),
-        coChange: [],
-        coupling: [],
-        omissions: [omission],
-        interpretation: INTERPRETATION,
-        confidence: availability === "unborn" ? "exact-bounded-git-history" : "unavailable",
-    };
-}
-function parseLog(output) {
-    const commits = [];
-    for (const rawRecord of output.split("\x1e").slice(1)) {
-        const tokens = rawRecord.split("\0").filter(Boolean);
-        const [header, ...changes] = tokens;
-        if (!header)
-            continue;
-        const [hash, parentsText = ""] = header.split("\x1f");
-        const parsedChanges = [];
-        for (let index = 0; index < changes.length;) {
-            const status = (changes[index++] ?? "").trim();
-            if (/^[RC]/.test(status)) {
-                const oldPath = changes[index++];
-                const renamedPath = changes[index++];
-                if (oldPath && renamedPath)
-                    parsedChanges.push({ status, oldPath, path: renamedPath });
-            }
-            else {
-                const changedPath = changes[index++];
-                if (changedPath)
-                    parsedChanges.push({ status, path: changedPath });
-            }
-        }
-        commits.push({ hash, parents: parentsText.split(" ").filter(Boolean), changes: parsedChanges });
-    }
-    return commits;
-}
-/**
- * Collect deterministic, itemized Git-history facts in one bounded history pass.
- * The command receives no user-provided revisions or filesystem paths; `cwd` is
- * the resolved repository and every requested file is validated before launch.
- */
-export function collectGitHistorySignals(repoPath, filePaths, limits = {}) {
-    const bounds = resolveBounds(limits);
-    const requestedAll = [...new Set(filePaths.map(safeHistoryFile))].sort();
-    const requested = requestedAll.slice(0, bounds.maxFiles);
-    const omissions = [];
-    if (requestedAll.length > requested.length) {
-        omissions.push({
-            reason: "file-limit",
-            detail: `${requestedAll.length - requested.length} requested file(s) omitted by maxFiles=${bounds.maxFiles}`,
-        });
-    }
-    let commands = 0;
-    const run = (args) => {
-        commands++;
-        return childProcess.execFileSync("git", args, {
-            cwd: path.resolve(repoPath),
-            encoding: "utf8",
-            stdio: ["ignore", "pipe", "pipe"],
-            timeout: bounds.timeoutMs,
-            maxBuffer: MAX_GIT_OUTPUT_BYTES,
-        });
-    };
-    let head;
-    try {
-        head = run(["rev-parse", "--verify", "HEAD"]).trim();
-    }
-    catch (error) {
-        const reason = failureReason(error);
-        if (reason === "history-command-failed" && isUnbornHeadFailure(error)) {
-            return emptyResult("unborn", bounds, commands, {
-                reason: "unborn-repository",
-                detail: "HEAD does not exist; no historical facts are available",
-            }, requested);
-        }
-        const availability = reason === "git-unavailable"
-            ? "git-unavailable"
-            : reason === "not-a-repository"
-                ? "not-a-repository"
-                : reason === "timeout"
-                    ? "timeout"
-                    : "unavailable";
-        return emptyResult(availability, bounds, commands, {
-            reason,
-            detail: "Git HEAD probe failed; history signals were omitted",
-        });
-    }
-    let shallow = false;
-    try {
-        shallow = run(["rev-parse", "--is-shallow-repository"]).trim() === "true";
-    }
-    catch {
-        // Older Git versions may not expose the probe; bounded history remains usable.
-    }
-    if (shallow) {
-        omissions.push({
-            reason: "shallow-history",
-            detail: "Only commits present in the shallow clone contribute facts",
-        });
-    }
-    const cacheKey = `${path.resolve(repoPath)}\0${head}\0${requestedAll.join("\0")}\0${JSON.stringify(bounds)}`;
-    if (!shallow) {
-        const cached = historyCache.get(cacheKey);
-        if (cached)
-            return structuredClone({ ...cached, commands });
-    }
-    let commits;
-    try {
-        const output = run([
-            "log",
-            `--max-count=${bounds.maxCommits + 1}`,
-            "--find-renames",
-            "--name-status",
-            "-z",
-            "--format=%x1e%H%x1f%P%x00",
-            "--no-decorate",
-        ]);
-        commits = parseLog(output);
-    }
-    catch (error) {
-        const reason = failureReason(error);
-        const availability = reason === "timeout" ? "timeout" : "unavailable";
-        return emptyResult(availability, bounds, commands, {
-            reason,
-            detail: "Bounded Git log failed; history signals were omitted",
-        });
-    }
-    if (commits.length > bounds.maxCommits) {
-        commits = commits.slice(0, bounds.maxCommits);
-        omissions.push({
-            reason: "commit-limit",
-            detail: `Older commits omitted by maxCommits=${bounds.maxCommits}`,
-        });
-    }
-    const aliases = new Map(requested.map((file) => [file, new Set([file])]));
-    const commitsByFile = new Map(requested.map((file) => [file, new Set()]));
-    const shared = new Map();
-    for (const commit of commits) {
-        for (const change of commit.changes) {
-            if (!change.oldPath)
-                continue;
-            for (const aliasSet of aliases.values()) {
-                if (change.status.startsWith("R") && aliasSet.has(change.path))
-                    aliasSet.add(change.oldPath);
-            }
-        }
-        for (const file of requested) {
-            const aliasSet = aliases.get(file) ?? new Set();
-            const touchesTarget = commit.changes.some((change) => [change.path, change.oldPath].some((candidate) => candidate && aliasSet.has(candidate)));
-            if (!touchesTarget)
-                continue;
-            commitsByFile.get(file)?.add(commit.hash);
-            for (const change of commit.changes) {
-                for (const relatedFile of [change.path, change.oldPath]) {
-                    if (!relatedFile || aliasSet.has(relatedFile))
-                        continue;
-                    const key = `${file}\0${relatedFile}`;
-                    let hashes = shared.get(key);
-                    if (!hashes) {
-                        hashes = new Set();
-                        shared.set(key, hashes);
-                    }
-                    hashes.add(commit.hash);
-                }
-            }
-        }
-    }
-    const allCoChange = [...shared.entries()]
-        .map(([key, hashes]) => {
-        const [file, relatedFile] = key.split("\0");
-        return {
-            file,
-            relatedFile,
-            sharedCommitCount: hashes.size,
-            commits: [...hashes].sort(),
-        };
-    })
-        .sort((a, b) => b.sharedCommitCount - a.sharedCommitCount ||
-        a.file.localeCompare(b.file) ||
-        a.relatedFile.localeCompare(b.relatedFile));
-    const coChange = allCoChange.slice(0, bounds.maxRelatedFiles);
-    if (coChange.length < allCoChange.length) {
-        omissions.push({
-            reason: "related-file-limit",
-            detail: `${allCoChange.length - coChange.length} co-change fact(s) omitted by maxRelatedFiles=${bounds.maxRelatedFiles}`,
-        });
-    }
-    const churn = requested.map((file) => {
-        const hashes = [...(commitsByFile.get(file) ?? [])].sort();
-        return { file, commitCount: hashes.length, commits: hashes };
-    });
-    const coupling = coChange.map((fact) => {
-        const fileCommitCount = commitsByFile.get(fact.file)?.size ?? 0;
-        return {
-            file: fact.file,
-            relatedFile: fact.relatedFile,
-            sharedCommitCount: fact.sharedCommitCount,
-            fileCommitCount,
-            ratio: fileCommitCount === 0 ? 0 : Number((fact.sharedCommitCount / fileCommitCount).toFixed(4)),
-        };
-    });
-    const result = {
-        availability: shallow ? "shallow" : "available",
-        bounds,
-        commands,
-        commitsAnalyzed: commits.length,
-        filesAnalyzed: requested.length,
-        truncated: omissions.some((item) => item.reason.endsWith("limit")),
-        churn,
-        coChange,
-        coupling,
-        omissions,
-        interpretation: INTERPRETATION,
-        confidence: "exact-bounded-git-history",
-    };
-    if (!shallow) {
-        historyCache.set(cacheKey, structuredClone(result));
-        while (historyCache.size > HISTORY_CACHE_LIMIT) {
-            const oldest = historyCache.keys().next().value;
-            if (oldest === undefined)
-                break;
-            historyCache.delete(oldest);
-        }
-    }
-    return result;
-}
-export function clearGitHistorySignalCache() {
-    historyCache.clear();
-}