knodin 0.5.0

package/dist/src/failure-diagnosis.js

@@ -0,0 +1,590 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { gitExecutable } from "./git-executable.js";
+import { compressOutput, readOutputArtifact } from "./output-compression.js";
+const CODE_EXTENSIONS = [
+    ".tsx",
+    ".jsx",
+    ".java",
+    ".cs",
+    ".go",
+    ".rs",
+    ".py",
+    ".ts",
+    ".js",
+    ".mjs",
+    ".cjs",
+    ".kt",
+    ".kts",
+    ".swift",
+    ".rb",
+    ".php",
+    ".scala",
+    ".c",
+    ".cc",
+    ".cpp",
+    ".h",
+    ".hpp",
+];
+const MAX_ANALYSIS_BYTES = 4 * 1024 * 1024;
+const MAX_SOURCE_FILE_BYTES = 1024 * 1024;
+const MAX_MANIFEST_BYTES = 256 * 1024;
+const MAX_REFERENCE_PATH_CHARS = 4_096;
+const MAX_PATH_SUFFIXES = 64;
+const DEFAULT_CONTEXT_BYTES = 16_384;
+const MAX_CONTEXT_BYTES = 128 * 1024;
+const DEFAULT_DIAGNOSTICS = 10;
+const MAX_DIAGNOSTICS = 50;
+const DEFAULT_RELATIONS = 8;
+const MAX_RELATIONS = 25;
+function integer(name, value, fallback, minimum, maximum) {
+    const resolved = value ?? fallback;
+    if (!Number.isInteger(resolved) || resolved < minimum || resolved > maximum)
+        throw new Error(`knodin diagnose: ${name} must be an integer from ${minimum} to ${maximum}`);
+    return resolved;
+}
+function evidenceLine(value) {
+    const compact = value.trim().replaceAll("\t", " ");
+    return compact.length <= 500 ? compact : `${compact.slice(0, 499)}…`;
+}
+function isPathCharacter(value) {
+    return !" \t\r\n\"'`()[]{}<>|=,".includes(value);
+}
+function skipCharacters(value, cursor, characters) {
+    let next = cursor;
+    while (next < value.length && characters.includes(value[next] ?? ""))
+        next++;
+    return next;
+}
+function readUnsignedInteger(value, cursor) {
+    let next = cursor;
+    while (next < value.length) {
+        const code = value.codePointAt(next) ?? -1;
+        if (code < 48 || code > 57)
+            break;
+        next++;
+    }
+    return {
+        value: next === cursor ? null : Number(value.slice(cursor, next)),
+        next,
+    };
+}
+function locationStart(suffix) {
+    let cursor = skipCharacters(suffix, 0, "\"'),");
+    cursor = skipCharacters(suffix, cursor, " ");
+    if (suffix.startsWith("line ", cursor))
+        cursor += 5;
+    else if (suffix.startsWith(":line ", cursor))
+        cursor += 6;
+    else
+        cursor = skipCharacters(suffix, cursor, ":([]");
+    return skipCharacters(suffix, cursor, " [");
+}
+function parseLocation(value, extensionEnd) {
+    const suffix = value.slice(extensionEnd, extensionEnd + 48).toLowerCase();
+    const line = readUnsignedInteger(suffix, locationStart(suffix));
+    if (line.value === null)
+        return { line: null, column: null };
+    const columnStart = skipCharacters(suffix, line.next, ":, [");
+    const column = readUnsignedInteger(suffix, columnStart);
+    return {
+        line: line.value,
+        column: column.value,
+    };
+}
+function referenceAt(line, lower, cursor) {
+    const extension = CODE_EXTENSIONS.find((candidate) => lower.startsWith(candidate, cursor));
+    if (!extension)
+        return null;
+    const extensionEnd = cursor + extension.length;
+    let start = cursor - 1;
+    while (start >= 0 && isPathCharacter(line[start] ?? ""))
+        start--;
+    let candidate = line.slice(start + 1, extensionEnd);
+    if (candidate.startsWith("file://"))
+        candidate = candidate.slice(7);
+    if (!candidate || candidate === extension || candidate.length > MAX_REFERENCE_PATH_CHARS)
+        return null;
+    const location = parseLocation(line, extensionEnd);
+    return {
+        path: candidate,
+        line: location.line,
+        column: location.column,
+        evidence: evidenceLine(line),
+    };
+}
+/** Extract bounded code-path references without treating free-form error prose as paths. */
+export function extractDiagnosticReferences(text, limit = MAX_DIAGNOSTICS) {
+    const references = [];
+    const seen = new Set();
+    for (const sourceLine of text.split(/\r?\n/)) {
+        const line = sourceLine.slice(0, 32_768);
+        const lower = line.toLowerCase();
+        for (let cursor = 0; cursor < lower.length; cursor++) {
+            const reference = referenceAt(line, lower, cursor);
+            if (!reference)
+                continue;
+            const key = `${reference.path}:${reference.line ?? ""}:${reference.column ?? ""}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            references.push(reference);
+            if (references.length >= limit)
+                return references;
+        }
+    }
+    return references;
+}
+function trackedPath(repo, candidate) {
+    const result = spawnSync(gitExecutable(), ["-C", repo, "ls-files", "--error-unmatch", "--", candidate], {
+        encoding: "utf8",
+        timeout: 3_000,
+        maxBuffer: 64 * 1024,
+    });
+    return result.status === 0;
+}
+function repositorySuffixes(candidate) {
+    const normalized = candidate.replaceAll("\\", "/").replace(/^[A-Za-z]:/, "");
+    const parts = normalized.split("/").filter(Boolean);
+    if (parts.includes(".."))
+        return [];
+    const suffixes = [];
+    for (let index = Math.max(0, parts.length - MAX_PATH_SUFFIXES); index < parts.length; index++) {
+        const suffix = parts.slice(index).join("/");
+        if (suffix)
+            suffixes.push(suffix);
+    }
+    return suffixes;
+}
+function withinRepository(repo, candidate) {
+    const realRepo = fs.realpathSync(repo);
+    const realCandidate = fs.realpathSync(path.join(repo, candidate));
+    const relative = path.relative(realRepo, realCandidate);
+    return relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+function validateTrackedCandidate(repo, candidate) {
+    try {
+        if (!trackedPath(repo, candidate))
+            return { reason: "not-indexed" };
+        return withinRepository(repo, candidate)
+            ? { file: candidate }
+            : { reason: "outside-repository" };
+    }
+    catch {
+        return { reason: "outside-repository" };
+    }
+}
+function basenameCandidates(search, basename) {
+    return [
+        ...new Set(search.results
+            .map(({ filePath }) => filePath)
+            .filter((filePath) => path.posix.basename(filePath) === basename)),
+    ].sort((left, right) => left.localeCompare(right));
+}
+async function resolveReferencePath(graph, repo, reference) {
+    const suffixes = repositorySuffixes(reference.path);
+    if (suffixes.length === 0)
+        return { reason: "outside-repository" };
+    for (const suffix of suffixes) {
+        if (!trackedPath(repo, suffix))
+            continue;
+        return validateTrackedCandidate(repo, suffix);
+    }
+    const basename = path.posix.basename(suffixes[0] ?? "");
+    const stem = basename.slice(0, Math.max(1, basename.lastIndexOf(".")));
+    const search = await graph.search(stem, repo, 100, {
+        includeSource: false,
+        federate: false,
+    });
+    const candidates = basenameCandidates(search, basename);
+    if (candidates.length === 1 && !search.hasMore)
+        return validateTrackedCandidate(repo, candidates[0] ?? "");
+    if (candidates.length > 1 || (search.hasMore && candidates.length > 0))
+        return { reason: "ambiguous", candidates };
+    return { reason: "not-indexed" };
+}
+function owningSymbol(rows, line) {
+    const symbols = rows.filter((row) => row.symbol && row.file && row.line !== undefined && row.endLine !== undefined);
+    if (symbols.length === 0)
+        return null;
+    if (line === null)
+        return [...symbols].sort((left, right) => (left.line ?? 0) - (right.line ?? 0))[0] ?? null;
+    return ([...symbols]
+        .filter((row) => (row.line ?? 0) <= line && (row.endLine ?? 0) >= line)
+        .sort((left, right) => (left.endLine ?? 0) - (left.line ?? 0) - ((right.endLine ?? 0) - (right.line ?? 0)) ||
+        (right.line ?? 0) - (left.line ?? 0))[0] ?? null);
+}
+function relationRows(result, limit) {
+    return result.results
+        .filter((row) => Boolean(row.symbol))
+        .slice(0, limit)
+        .map((row) => ({
+        identity: row.identity ?? null,
+        symbol: row.symbol ?? "",
+        file: row.file ?? null,
+        kind: row.kind ?? null,
+        line: row.line ?? null,
+        confidence: row.impactEdge?.confidence ?? null,
+    }));
+}
+function assignmentValue(line) {
+    const separator = line.indexOf("=");
+    if (separator < 0)
+        return null;
+    const value = line
+        .slice(separator + 1)
+        .trim()
+        .replace(/^["']|["']$/g, "");
+    return value || null;
+}
+function tomlName(content, sections) {
+    let active = false;
+    for (const sourceLine of content.split(/\r?\n/)) {
+        const line = sourceLine.trim();
+        if (line.startsWith("[") && line.endsWith("]")) {
+            active = sections.includes(line.slice(1, -1).trim());
+            continue;
+        }
+        const separator = line.indexOf("=");
+        if (active && separator >= 0 && line.slice(0, separator).trim() === "name")
+            return assignmentValue(line);
+    }
+    return null;
+}
+function xmlElement(content, element) {
+    const open = `<${element}>`;
+    const close = `</${element}>`;
+    const start = content.indexOf(open);
+    if (start < 0)
+        return null;
+    const end = content.indexOf(close, start + open.length);
+    if (end < 0)
+        return null;
+    return content.slice(start + open.length, end).trim() || null;
+}
+function packageName(kind, manifest, content) {
+    if (kind === "npm") {
+        try {
+            const parsed = JSON.parse(content);
+            return typeof parsed.name === "string" && parsed.name ? parsed.name : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    if (kind === "python")
+        return tomlName(content, ["project", "tool.poetry"]);
+    if (kind === "cargo")
+        return tomlName(content, ["package"]);
+    if (kind === "maven") {
+        const parentEnd = content.indexOf("</parent>");
+        return xmlElement(parentEnd >= 0 ? content.slice(parentEnd + "</parent>".length) : content, "artifactId");
+    }
+    if (kind === "go") {
+        const module = content
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .find((line) => line.startsWith("module "));
+        return module?.slice("module ".length).trim() || null;
+    }
+    return path.basename(manifest, path.extname(manifest));
+}
+function dotnetManifest(directory) {
+    let handle;
+    try {
+        handle = fs.opendirSync(directory);
+        for (let seen = 0; seen < 1_024; seen++) {
+            const entry = handle.readSync();
+            if (!entry)
+                break;
+            if (entry.isFile() && entry.name.toLowerCase().endsWith(".csproj"))
+                return entry.name;
+        }
+    }
+    catch {
+        return null;
+    }
+    finally {
+        handle?.closeSync();
+    }
+    return null;
+}
+function preferredPackageKind(file) {
+    const extension = path.extname(file).toLowerCase();
+    if (extension === ".py")
+        return "python";
+    if (extension === ".rs")
+        return "cargo";
+    if (extension === ".go")
+        return "go";
+    if ([".java", ".kt", ".kts"].includes(extension))
+        return "maven";
+    if (extension === ".cs")
+        return "dotnet";
+    if ([".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs"].includes(extension))
+        return "npm";
+    return null;
+}
+function packageCandidate(repo, directory, name, kind) {
+    const manifest = path.posix.join(directory === "." ? "" : directory, name);
+    try {
+        if (!trackedPath(repo, manifest) || !withinRepository(repo, manifest))
+            return null;
+        const stat = fs.statSync(path.join(repo, manifest));
+        if (!stat.isFile() || stat.size > MAX_MANIFEST_BYTES)
+            return null;
+        const content = fs.readFileSync(path.join(repo, manifest), "utf8");
+        return { name: packageName(kind, manifest, content), manifest, kind };
+    }
+    catch {
+        return null;
+    }
+}
+function owningPackage(repo, file) {
+    const preferredKind = preferredPackageKind(file);
+    const manifests = [
+        ["package.json", "npm"],
+        ["pyproject.toml", "python"],
+        ["pom.xml", "maven"],
+        ["Cargo.toml", "cargo"],
+        ["go.mod", "go"],
+    ];
+    manifests.sort((left, right) => Number(right[1] === preferredKind) - Number(left[1] === preferredKind));
+    let directory = path.dirname(file);
+    while (directory !== ".." && !path.isAbsolute(directory)) {
+        const dotnet = preferredKind === "dotnet" ? dotnetManifest(path.join(repo, directory)) : null;
+        const candidates = [...manifests];
+        if (dotnet)
+            candidates.unshift([dotnet, "dotnet"]);
+        for (const [name, kind] of candidates) {
+            const found = packageCandidate(repo, directory, name, kind);
+            if (found)
+                return found;
+        }
+        const parent = path.dirname(directory);
+        if (parent === directory)
+            break;
+        directory = parent;
+    }
+    return null;
+}
+function recentChanges(repo, file, limit) {
+    const result = spawnSync(gitExecutable(), ["-C", repo, "log", `-${limit}`, "--format=%H%x09%aI%x09%an%x09%s", "--", file], { encoding: "utf8", timeout: 5_000, maxBuffer: 128 * 1024 });
+    if (result.status !== 0)
+        return [];
+    return result.stdout
+        .trim()
+        .split("\n")
+        .filter(Boolean)
+        .map((record) => {
+        const [commit = "", at = "", author = "", ...subject] = record.split("\t");
+        return { commit, at, author, subject: subject.join("\t") };
+    });
+}
+function truncateUtf8(value, byteBudget) {
+    if (Buffer.byteLength(value) <= byteBudget)
+        return value;
+    let output = "";
+    let bytes = 0;
+    for (const character of value) {
+        const size = Buffer.byteLength(character);
+        if (bytes + size > byteBudget)
+            break;
+        output += character;
+        bytes += size;
+    }
+    return output;
+}
+function sourceSnippet(repo, file, line, contextLines, remainingBytes) {
+    if (remainingBytes <= 0)
+        return { snippet: null, truncated: true };
+    const absolute = path.join(repo, file);
+    let lines;
+    try {
+        const stat = fs.statSync(absolute);
+        if (!stat.isFile() || stat.size > MAX_SOURCE_FILE_BYTES)
+            return { snippet: null, truncated: true };
+        lines = fs.readFileSync(absolute, "utf8").split(/\r?\n/);
+    }
+    catch {
+        return { snippet: null, truncated: true };
+    }
+    const startLine = Math.max(1, line - contextLines);
+    const endLine = Math.min(lines.length, line + contextLines);
+    const content = lines
+        .slice(startLine - 1, endLine)
+        .map((value, index) => `${startLine + index}: ${value.slice(0, 2_000)}`)
+        .join("\n");
+    const bounded = truncateUtf8(content, remainingBytes);
+    if (!bounded)
+        return { snippet: null, truncated: true };
+    return {
+        snippet: { file, startLine, endLine, content: bounded },
+        truncated: bounded !== content,
+    };
+}
+function diagnosisSource(repo, request) {
+    const sources = [request.artifactId !== undefined, request.text !== undefined].filter(Boolean).length;
+    if (sources !== 1)
+        throw new Error("knodin diagnose requires exactly one of artifactId or text");
+    if (request.artifactId) {
+        const probe = readOutputArtifact(repo, request.artifactId, {
+            byteBudget: MAX_ANALYSIS_BYTES,
+        });
+        const full = probe.complete || probe.range.totalLines <= probe.range.endLine
+            ? probe
+            : readOutputArtifact(repo, request.artifactId, {
+                endLine: probe.range.totalLines,
+                byteBudget: MAX_ANALYSIS_BYTES,
+            });
+        return {
+            kind: "artifact",
+            artifactId: request.artifactId,
+            content: full.content,
+            bytes: full.bytes,
+            complete: full.complete,
+        };
+    }
+    const compressed = compressOutput(repo, {
+        text: request.text,
+        lineBudget: 10_000,
+        byteBudget: MAX_ANALYSIS_BYTES,
+        maxInputBytes: MAX_ANALYSIS_BYTES,
+        retain: false,
+        redactSecrets: true,
+    });
+    return {
+        kind: "text",
+        artifactId: null,
+        content: compressed.content,
+        bytes: compressed.output.bytes,
+        complete: compressed.complete,
+    };
+}
+async function relationsForOwner(graph, repo, file, owner, limit) {
+    if (!owner?.symbol)
+        return { tests: [], upstream: [], downstream: [] };
+    const selector = owner.identity ? { identity: owner.identity, file } : { file };
+    const query = (pattern, options) => graph.query(pattern, owner.symbol ?? "", repo, undefined, limit, pattern === "impact" ? 2 : undefined, undefined, selector, options);
+    const [tests, upstream, downstream] = await Promise.all([
+        query("tests_for"),
+        query("impact", { direction: "upstream", includeTests: true }),
+        query("impact", { direction: "downstream", includeTests: true }),
+    ]);
+    return {
+        tests: relationRows(tests, limit),
+        upstream: relationRows(upstream, limit),
+        downstream: relationRows(downstream, limit),
+    };
+}
+function ownerEvidence(owner) {
+    if (!owner?.symbol)
+        return null;
+    return {
+        identity: owner.identity ?? null,
+        symbol: owner.symbol,
+        kind: owner.kind ?? "unknown",
+        line: owner.line ?? null,
+        endLine: owner.endLine ?? null,
+        signature: owner.signature ?? null,
+        evidenceQuality: owner.evidenceQuality ?? null,
+    };
+}
+async function diagnoseResolvedReference(graph, repo, reference, file, options) {
+    const summary = await graph.query("file_summary", file, repo, undefined, 200);
+    const owner = owningSymbol(summary.results, reference.line);
+    const relationships = await relationsForOwner(graph, repo, file, owner, options.relationLimit);
+    const evidenceLineNumber = reference.line ?? owner?.line ?? 1;
+    return {
+        diagnostic: {
+            reference,
+            file,
+            package: owningPackage(repo, file),
+            owner: ownerEvidence(owner),
+            ...relationships,
+            recentChanges: options.recentCommitLimit > 0 ? recentChanges(repo, file, options.recentCommitLimit) : [],
+        },
+        source: sourceSnippet(repo, file, evidenceLineNumber, options.contextLines, options.remainingContextBytes),
+    };
+}
+function diagnosisLimitations(inputComplete, referenceCount, contextTruncated, freshnessState) {
+    const limitations = [
+        "Static graph relationships and recent commits are diagnostic candidates, not runtime-causality proof.",
+    ];
+    if (!inputComplete)
+        limitations.push(`Only the first ${MAX_ANALYSIS_BYTES} analyzed bytes were available.`);
+    if (referenceCount === 0)
+        limitations.push("No repository-contained code-path reference was detected in the analyzed output.");
+    if (contextTruncated)
+        limitations.push("Source snippets were omitted or shortened to honor the context byte budget.");
+    if (freshnessState !== "fresh")
+        limitations.push(`Graph freshness is ${freshnessState}; refresh before strong claims.`);
+    return limitations;
+}
+function diagnosisStatus(resolvedCount, unresolvedCount, inputComplete, contextTruncated, freshnessState) {
+    if (resolvedCount === 0)
+        return "unresolved";
+    if (unresolvedCount > 0 || !inputComplete || contextTruncated || freshnessState !== "fresh")
+        return "partial";
+    return "resolved";
+}
+export async function diagnoseFailure(graph, repo, request) {
+    const maxDiagnostics = integer("maxDiagnostics", request.maxDiagnostics, DEFAULT_DIAGNOSTICS, 1, MAX_DIAGNOSTICS);
+    const contextLines = integer("contextLines", request.contextLines, 2, 0, 10);
+    const contextByteBudget = integer("contextByteBudget", request.contextByteBudget, DEFAULT_CONTEXT_BYTES, 256, MAX_CONTEXT_BYTES);
+    const relationLimit = integer("relationLimit", request.relationLimit, DEFAULT_RELATIONS, 1, MAX_RELATIONS);
+    const recentCommitLimit = integer("recentCommitLimit", request.recentCommitLimit, 3, 0, 10);
+    const input = diagnosisSource(repo, request);
+    const references = extractDiagnosticReferences(input.content, maxDiagnostics);
+    const diagnostics = [];
+    const unresolved = [];
+    const snippets = [];
+    let contextBytes = 0;
+    let contextTruncated = false;
+    for (const reference of references) {
+        const resolved = await resolveReferencePath(graph, repo, reference);
+        if (!resolved.file) {
+            unresolved.push({
+                reference,
+                reason: resolved.reason ?? "not-indexed",
+                ...(resolved.candidates ? { candidates: resolved.candidates } : {}),
+            });
+            continue;
+        }
+        const resolvedDiagnosis = await diagnoseResolvedReference(graph, repo, reference, resolved.file, {
+            relationLimit,
+            recentCommitLimit,
+            contextLines,
+            remainingContextBytes: contextByteBudget - contextBytes,
+        });
+        if (resolvedDiagnosis.source.snippet) {
+            snippets.push(resolvedDiagnosis.source.snippet);
+            contextBytes += Buffer.byteLength(resolvedDiagnosis.source.snippet.content);
+        }
+        contextTruncated ||= resolvedDiagnosis.source.truncated;
+        diagnostics.push(resolvedDiagnosis.diagnostic);
+    }
+    const health = await graph.status(repo, { audit: "cached" });
+    const status = diagnosisStatus(diagnostics.length, unresolved.length, input.complete, contextTruncated, health.freshness.state);
+    return {
+        schemaVersion: 1,
+        status,
+        input: {
+            kind: input.kind,
+            artifactId: input.artifactId,
+            bytes: input.bytes,
+            complete: input.complete,
+        },
+        diagnostics,
+        unresolved,
+        contextBundle: {
+            byteBudget: contextByteBudget,
+            usedBytes: contextBytes,
+            truncated: contextTruncated,
+            snippets,
+        },
+        freshness: health.freshness,
+        limitations: diagnosisLimitations(input.complete, references.length, contextTruncated, health.freshness.state),
+    };
+}

package/dist/src/fleet.js

@@ -0,0 +1,7 @@
+/**
+ * Deprecated compatibility exports for the `knodin fleet init` alias.
+ *
+ * New implementation code must import from repository-management.ts.
+ * Remove this adapter after two minor releases.
+ */
+export { discoverGitRepositoryPaths as discoverGitWorktrees, formatRepositoryHuman as formatFleetHuman, initializeRepositories as bootstrapFleet, parseFleetInitArgs, } from "./repository-management.js";

package/dist/src/git-executable.js

@@ -0,0 +1,31 @@
+import fs from "node:fs";
+import path from "node:path";
+function executableCandidates() {
+    if (process.platform === "win32") {
+        const roots = [process.env.ProgramFiles, process.env["ProgramFiles(x86)"]].filter((value) => Boolean(value));
+        return roots.flatMap((root) => [
+            path.join(root, "Git", "cmd", "git.exe"),
+            path.join(root, "Git", "bin", "git.exe"),
+        ]);
+    }
+    return ["/usr/bin/git", "/usr/local/bin/git", "/opt/homebrew/bin/git"];
+}
+/**
+ * Resolve Git only from fixed installation locations. This deliberately avoids
+ * executing an attacker-controlled binary from a writable PATH entry.
+ */
+export function gitExecutable() {
+    const executable = executableCandidates().find((candidate) => {
+        try {
+            fs.accessSync(candidate, fs.constants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+    if (!executable) {
+        throw new Error("Git was not found in a trusted installation directory; install Git in a standard system location");
+    }
+    return executable;
+}