knodin 0.6.0 → 0.7.3

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

@@ -0,0 +1,289 @@
+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();
+}