knodin 0.5.0

package/dist/src/competitive-manifest.js

@@ -0,0 +1,330 @@
+const bunHarness = (script) => ({ output }) => ["bun", `scripts/${script}`, output];
+export const COMPETITIVE_MANIFEST = [
+    {
+        id: "gitnexus",
+        name: "GitNexus",
+        version: "1.6.9",
+        roadmap: ["C2", "C4", "C5", "C6", "C7", "C8", "C9", "C10", "C24", "C25", "C26"],
+        baseline: "gitnexus-vs-knodin.raw.json",
+        requirements: [
+            { type: "command", value: "gitnexus" },
+            { type: "command", value: "bun" },
+        ],
+        versionCommand: ["gitnexus", "--version"],
+        prepare: [["gitnexus", "analyze"]],
+        command: bunHarness("gitnexus-bakeoff.ts"),
+    },
+    {
+        id: "codegraph",
+        name: "CodeGraph",
+        version: "1.5.0",
+        roadmap: ["C2", "C3", "C11", "C24", "C25"],
+        baseline: "codegraph-vs-knodin.raw.json",
+        requirements: [
+            { type: "command", value: "codegraph" },
+            { type: "command", value: "bun" },
+        ],
+        versionCommand: ["codegraph", "--version"],
+        command: bunHarness("codegraph-bakeoff.ts"),
+    },
+    {
+        id: "code-review-graph",
+        name: "code-review-graph",
+        version: "2.3.7",
+        roadmap: ["C3", "C5", "C11", "C12", "C15", "C17", "C24", "C26"],
+        baseline: "code-review-graph-vs-knodin.raw.json",
+        requirements: [
+            { type: "command", value: "code-review-graph" },
+            { type: "command", value: "bun" },
+        ],
+        versionCommand: ["code-review-graph", "--version"],
+        prepare: [["code-review-graph", "build"]],
+        command: bunHarness("code-review-graph-bakeoff.ts"),
+    },
+    {
+        id: "graphify",
+        name: "Graphify",
+        version: "0.9.23",
+        roadmap: ["C2", "C3", "C11", "C12", "C13", "C17", "C24", "C26"],
+        baseline: "graphify-vs-knodin.raw.json",
+        requirements: [
+            { type: "command", value: "graphify" },
+            { type: "command", value: "graphify-mcp" },
+            { type: "command", value: "bun" },
+        ],
+        versionCommand: ["graphify", "--version"],
+        prepare: [
+            ["graphify", "extract", ".", "--code-only", "--no-cluster"],
+            ["graphify", "cluster-only", ".", "--no-label", "--no-viz"],
+        ],
+        command: bunHarness("graphify-bakeoff.ts"),
+        caseMappings: [
+            {
+                idPattern: "^neighbors-calls-(?:path|default)$",
+                useCase: "direct call neighbors",
+                mode: "warm",
+                scope: {
+                    competitorOperation: "get_neighbors",
+                    knodinOperation: "query:traverse",
+                    dimensions: ["target", "direction=both", "relation=call", "depth=1", "items=200"],
+                },
+                budgets: { bytes: null, tokens: null, items: 200 },
+                reason: "Both sides return direct inbound and outbound call neighbors for createEngine.",
+                oracleId: "contains-create-engine",
+            },
+        ],
+    },
+    {
+        id: "serena",
+        name: "Serena",
+        version: "1.6.2.dev0",
+        roadmap: ["C11", "C12", "C15", "C24", "C25"],
+        baseline: "serena-vs-knodin.raw.json",
+        requirements: [
+            { type: "command", value: "serena" },
+            { type: "command", value: "bun" },
+        ],
+        versionCommand: ["serena", "--version"],
+        command: ({ output, fixture }) => ["bun", "scripts/serena-bakeoff.ts", fixture, output],
+    },
+    {
+        id: "codebase-memory",
+        name: "codebase-memory-mcp",
+        version: "0.9.0",
+        roadmap: ["C4", "C10", "C11", "C12", "C13", "C16", "C24", "C25", "C26"],
+        baseline: "codebase-memory-vs-knodin.raw.json",
+        requirements: [
+            { type: "command", value: "codebase-memory-mcp" },
+            { type: "command", value: "bun" },
+        ],
+        versionCommand: ["codebase-memory-mcp", "--version"],
+        command: bunHarness("codebase-memory-bakeoff.ts"),
+        caseMappings: [
+            {
+                idPattern: "^search-graph-e0-c0$",
+                useCase: "bounded graph search",
+                mode: "warm",
+                scope: {
+                    competitorOperation: "search_graph",
+                    knodinOperation: "search",
+                    dimensions: ["query=create engine", "offset=0", "items=10", "connected=false"],
+                },
+                budgets: { bytes: null, tokens: null, items: 10 },
+                reason: "Both sides run the same unexpanded first-page query with the same item limit.",
+                oracleId: "contains-create-engine",
+            },
+            {
+                idPattern: "^trace-(?:inbound|outbound|both)-calls-r0-t1$",
+                useCase: "typed call traversal",
+                mode: "warm",
+                scope: {
+                    competitorOperation: "trace_path",
+                    knodinOperation: "query:traverse",
+                    dimensions: [
+                        "target=createEngine",
+                        "direction",
+                        "relation=call",
+                        "depth=3",
+                        "include_tests=true",
+                    ],
+                },
+                budgets: { bytes: null, tokens: null, items: 100 },
+                reason: "Both sides use the same target, direction, call relation, depth, and test scope.",
+                oracleId: "contains-create-engine",
+            },
+            {
+                idPattern: "^architecture-(?:languages|packages|entry_points|hotspots|boundaries|layers)$",
+                useCase: "single architecture facet",
+                mode: "warm",
+                scope: {
+                    competitorOperation: "get_architecture",
+                    knodinOperation: "query:architecture_overview",
+                    dimensions: ["one named facet", "repository scope", "source inclusion=metadata"],
+                },
+                budgets: { bytes: null, tokens: null, items: null },
+                reason: "Each row requests one architecture facet that knodin supports independently.",
+                oracleId: "architecture-facet",
+            },
+        ],
+    },
+    {
+        id: "grepai",
+        name: "grepai",
+        version: "0.35.0",
+        roadmap: ["C3", "C11", "C12", "C16", "C17", "C24"],
+        baseline: "grepai-vs-knodin.raw.json",
+        requirements: [
+            { type: "command", value: "grepai" },
+            { type: "command", value: "bun" },
+        ],
+        versionCommand: ["grepai", "version"],
+        command: bunHarness("grepai-bakeoff.ts"),
+        caseMappings: [
+            {
+                idPattern: "^status-json-v0$",
+                useCase: "cached index status",
+                mode: "warm",
+                scope: {
+                    competitorOperation: "grepai_index_status",
+                    knodinOperation: "status:cached",
+                    dimensions: ["cached summary", "repository scope", "non-verbose"],
+                },
+                budgets: { bytes: null, tokens: null, items: null },
+                reason: "Both sides return a cached, non-deep index status summary.",
+                oracleId: "contains-index",
+            },
+            {
+                idPattern: "^search-json-c0-l(?:1|5|20)-all$",
+                useCase: "bounded semantic search",
+                mode: "warm",
+                scope: {
+                    competitorOperation: "grepai_search",
+                    knodinOperation: "search",
+                    dimensions: ["query=index freshness reconciliation", "repository scope", "items"],
+                },
+                budgets: { bytes: null, tokens: null, items: null },
+                reason: "Both sides use the same semantic query, repository scope, and row limit.",
+                oracleId: "contains-index",
+            },
+            {
+                idPattern: "^grepai_trace_(?:callers|callees)-json-c0$",
+                useCase: "direct call neighbors",
+                mode: "warm",
+                scope: {
+                    competitorOperation: "grepai_trace_callers|grepai_trace_callees",
+                    knodinOperation: "query:callers_of|callees_of",
+                    dimensions: ["target=createEngine", "direction", "depth=1", "relation=call"],
+                },
+                budgets: { bytes: null, tokens: null, items: null },
+                reason: "Both sides return the same direct call-neighbor direction for createEngine.",
+                oracleId: "contains-create-engine",
+            },
+        ],
+    },
+    {
+        id: "repomix",
+        name: "Repomix",
+        version: "1.17.0",
+        roadmap: ["C3", "C14", "C24"],
+        baseline: "repomix-vs-knodin.raw.json",
+        requirements: [
+            { type: "command", value: "repomix" },
+            { type: "command", value: "bun" },
+        ],
+        versionCommand: ["repomix", "--version"],
+        command: ({ output, fixture }) => ["bun", "scripts/repomix-bakeoff.ts", fixture, output],
+        caseMappings: [
+            {
+                idPattern: "^pack-(?:xml|markdown|json)-c0$",
+                useCase: "two-file context pack",
+                mode: "warm",
+                scope: {
+                    competitorOperation: "pack_codebase",
+                    knodinOperation: "pack:export",
+                    dimensions: ["format", "two includes", "test exclusion", "compression=false"],
+                },
+                budgets: { bytes: null, tokens: null, items: 2 },
+                reason: "Both sides pack the same two full files in the same supported format without compression.",
+                oracleId: "pack-two-files",
+            },
+            {
+                idPattern: "^read-(?:xml|markdown|json)-c0-(?:all|head|middle)$",
+                useCase: "bounded packed artifact read",
+                mode: "warm",
+                scope: {
+                    competitorOperation: "read_repomix_output",
+                    knodinOperation: "pack:read",
+                    dimensions: ["same saved artifact", "same inclusive line range"],
+                },
+                budgets: { bytes: null, tokens: null, items: null },
+                reason: "Both sides read the same inclusive range from their immediately preceding pack.",
+                oracleId: "packed-read",
+            },
+            {
+                idPattern: "^grep-(?:xml|markdown|json)-c0-i(?:0|1)-x0$",
+                useCase: "exact packed artifact grep",
+                mode: "warm",
+                scope: {
+                    competitorOperation: "grep_repomix_output",
+                    knodinOperation: "pack:grep",
+                    dimensions: ["same saved artifact", "same regex", "same case mode", "context=0"],
+                },
+                budgets: { bytes: null, tokens: null, items: null },
+                reason: "Both sides grep their equivalent packs with the same expression and no context lines.",
+                oracleId: "grep-create-engine",
+            },
+        ],
+    },
+    {
+        id: "aider",
+        name: "Aider repo-map",
+        version: "0.86.2",
+        roadmap: ["C3", "C14", "C24"],
+        baseline: "aider-vs-knodin.raw.json",
+        requirements: [
+            { type: "command", value: "aider" },
+            { type: "command", value: "bun" },
+        ],
+        versionCommand: ["aider", "--version"],
+        command: bunHarness("aider-repomap-bakeoff.ts"),
+    },
+    {
+        id: "code2prompt",
+        name: "code2prompt",
+        version: "4.2.0",
+        roadmap: ["C3", "C5", "C14", "C24"],
+        baseline: "code2prompt-vs-knodin.raw.json",
+        requirements: [
+            { type: "command", value: "code2prompt" },
+            { type: "command", value: "bun" },
+        ],
+        versionCommand: ["code2prompt", "--version"],
+        command: bunHarness("code2prompt-bakeoff.ts"),
+        caseMappings: [
+            {
+                idPattern: "^format-(?:markdown|json|xml)-l(?:0|1)-t0-a0-c1$",
+                useCase: "two-file context pack",
+                mode: "warm",
+                scope: {
+                    competitorOperation: "code2prompt",
+                    knodinOperation: "pack:export",
+                    dimensions: [
+                        "format",
+                        "line numbers",
+                        "directory tree=false",
+                        "relative paths",
+                        "two includes",
+                    ],
+                },
+                budgets: { bytes: null, tokens: null, items: 2 },
+                reason: "Both sides pack the same two files with matching format, line, tree, and path settings.",
+                oracleId: "pack-two-files",
+            },
+        ],
+    },
+    {
+        id: "claude-context",
+        name: "claude-context-mcp",
+        version: "0.1.15",
+        roadmap: ["C11", "C12", "C16", "C24"],
+        baseline: "claude-context-vs-knodin.raw.json",
+        requirements: [
+            { type: "command", value: "claude-context-mcp" },
+            { type: "command", value: "bun" },
+            { type: "tcp", host: "127.0.0.1", port: 11434, label: "Ollama" },
+            { type: "tcp", host: "127.0.0.1", port: 19530, label: "Milvus" },
+        ],
+        versionCommand: ["bun", "pm", "ls", "-g"],
+        command: ({ output, fixture }) => ["bun", "scripts/claude-context-bakeoff.ts", fixture, output],
+    },
+    {
+        id: "mcp-codebase-index",
+        name: "mcp-codebase-index",
+        version: "1.6.0",
+        roadmap: ["C16", "C24"],
+        baseline: "mcp-codebase-index-blocker.raw.json",
+        requirements: [{ type: "command", value: "mcp-codebase-index" }],
+        versionCommand: ["bun", "pm", "ls", "-g"],
+        blocker: "Mandatory hosted Gemini embeddings violate the local-only protocol.",
+    },
+];

package/dist/src/competitive-measurement.js

@@ -0,0 +1,183 @@
+import childProcess from "node:child_process";
+import fs from "node:fs";
+/**
+ * Twenty warm observations are the minimum that gives nearest-rank p95 a
+ * distinct tail observation instead of aliasing a three-sample median.
+ */
+export const MIN_WARM_SAMPLES = 20;
+export const DEFAULT_WARMUP_COUNT = 3;
+export const DEFAULT_COLD_SAMPLES = 5;
+export const DEFAULT_CALL_TIMEOUT_MS = 30_000;
+function percentile(sorted, fraction) {
+    const index = Math.max(0, Math.ceil(fraction * sorted.length) - 1);
+    return sorted[index];
+}
+export function summarizeLatencySamples(mode, samplesMs, warmupCount) {
+    if (!Number.isInteger(warmupCount) || warmupCount < 0)
+        throw new Error("Warm-up count must be a non-negative integer");
+    if (samplesMs.length === 0)
+        throw new Error("At least one latency sample is required");
+    if (mode === "warm" && samplesMs.length < MIN_WARM_SAMPLES) {
+        throw new Error(`Warm measurements require at least ${MIN_WARM_SAMPLES} samples for a meaningful p95`);
+    }
+    if (samplesMs.some((sample) => !Number.isFinite(sample) || sample < 0))
+        throw new Error("Latency samples must be finite non-negative numbers");
+    const raw = [...samplesMs];
+    const sorted = [...raw].sort((left, right) => left - right);
+    const p50Ms = percentile(sorted, 0.5);
+    return {
+        mode,
+        warmupCount,
+        sampleCount: raw.length,
+        samplesMs: raw,
+        p50Ms,
+        p95Ms: percentile(sorted, 0.95),
+        minMs: sorted[0],
+        maxMs: sorted.at(-1),
+        medianMs: p50Ms,
+    };
+}
+export async function sampleOperation(operation, options) {
+    const mode = options.mode ?? "warm";
+    const warmupCount = mode === "warm" ? (options.warmupCount ?? DEFAULT_WARMUP_COUNT) : 0;
+    const sampleCount = options.sampleCount ?? (mode === "warm" ? MIN_WARM_SAMPLES : DEFAULT_COLD_SAMPLES);
+    let value;
+    const call = async (kind, index) => {
+        const timeoutMs = options.timeoutMs ?? DEFAULT_CALL_TIMEOUT_MS;
+        let timer;
+        try {
+            return await Promise.race([
+                operation(),
+                new Promise((_, reject) => {
+                    timer = setTimeout(async () => {
+                        try {
+                            if (options.onTimeout)
+                                await options.onTimeout(kind, index);
+                            else
+                                reapDescendants(process.pid);
+                        }
+                        catch {
+                            // Cleanup failure must not replace or strand the timeout result.
+                        }
+                        finally {
+                            reject(new Error(`Competitive ${kind} call ${index + 1} timed out after ${timeoutMs}ms`));
+                        }
+                    }, timeoutMs);
+                    timer.unref?.();
+                }),
+            ]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    };
+    for (let index = 0; index < warmupCount; index++) {
+        await options.beforeSample?.("warmup", index);
+        value = await call("warmup", index);
+    }
+    const samplesMs = [];
+    for (let index = 0; index < sampleCount; index++) {
+        await options.beforeSample?.("sample", index);
+        const startedAt = performance.now();
+        value = await call("sample", index);
+        samplesMs.push(Number((performance.now() - startedAt).toFixed(3)));
+    }
+    return {
+        value: value,
+        measurement: summarizeLatencySamples(mode, samplesMs, warmupCount),
+    };
+}
+export function reapDescendants(rootPid) {
+    const output = childProcess.spawnSync("ps", ["-axo", "pid=,ppid="]).stdout.toString();
+    const processes = output
+        .split("\n")
+        .map((line) => line.trim().split(/\s+/).map(Number))
+        .filter(([pid, parentPid]) => Number.isInteger(pid) && Number.isInteger(parentPid));
+    const descendants = new Set([rootPid]);
+    for (let changed = true; changed;) {
+        changed = false;
+        for (const [pid, parentPid] of processes) {
+            if (!descendants.has(pid) && descendants.has(parentPid)) {
+                descendants.add(pid);
+                changed = true;
+            }
+        }
+    }
+    descendants.delete(rootPid);
+    for (const signal of ["-TERM", "-KILL"]) {
+        for (const pid of [...descendants].reverse()) {
+            childProcess.spawnSync("/bin/kill", [signal, String(pid)]);
+        }
+    }
+}
+export function createCheckpointingResults(outputPath) {
+    const results = [];
+    results.push = (...items) => {
+        const length = Array.prototype.push.apply(results, items);
+        const temporary = `${outputPath}.partial-${process.pid}`;
+        fs.writeFileSync(temporary, `${JSON.stringify({
+            schemaVersion: 2,
+            status: "partial",
+            terminal: false,
+            partial: true,
+            generatedAt: new Date().toISOString(),
+            results,
+        }, null, 2)}\n`);
+        fs.renameSync(temporary, outputPath);
+        return length;
+    };
+    return results;
+}
+function emptyOwner() {
+    return { rssBytes: 0, pids: [] };
+}
+export function attributeProcessTree(processes, rootPid, patterns, phase, rootOwner = "harness") {
+    const descendants = new Set([rootPid]);
+    for (let changed = true; changed;) {
+        changed = false;
+        for (const process of processes) {
+            if (!descendants.has(process.pid) && descendants.has(process.parentPid)) {
+                descendants.add(process.pid);
+                changed = true;
+            }
+        }
+    }
+    const result = {
+        phase,
+        harness: emptyOwner(),
+        knodin: emptyOwner(),
+        competitor: emptyOwner(),
+        unknown: emptyOwner(),
+    };
+    for (const process of processes) {
+        if (!descendants.has(process.pid))
+            continue;
+        const owner = process.pid === rootPid
+            ? rootOwner
+            : patterns.knodin.some((pattern) => pattern.test(process.command))
+                ? "knodin"
+                : patterns.competitor.some((pattern) => pattern.test(process.command))
+                    ? "competitor"
+                    : "unknown";
+        result[owner].rssBytes += process.rssBytes;
+        result[owner].pids.push(process.pid);
+    }
+    return result;
+}
+export function mergeResourcePeaks(left, right) {
+    const merged = {
+        phase: right.phase,
+        harness: emptyOwner(),
+        knodin: emptyOwner(),
+        competitor: emptyOwner(),
+        unknown: emptyOwner(),
+    };
+    for (const owner of ["harness", "knodin", "competitor", "unknown"]) {
+        merged[owner] =
+            right[owner].rssBytes >= left[owner].rssBytes
+                ? { ...right[owner], pids: [...right[owner].pids] }
+                : { ...left[owner], pids: [...left[owner].pids] };
+    }
+    return merged;
+}