knodin 0.7.5 → 0.8.2

package/dist/src/engine/sarif-import.js

@@ -0,0 +1,341 @@
+/**
+ * Bounded SARIF import.
+ *
+ * SARIF (OASIS "Static Analysis Results Interchange Format") is what most
+ * analyzers can emit — Salesforce Code Analyzer, ESLint, Semgrep, CodeQL, PMD,
+ * Trivy. Importing the format rather than any one tool's native output means one
+ * reader covers all of them.
+ *
+ * Findings are NOT graph facts. knodin resolves references from source; a
+ * finding is somebody else's judgement about a location. It is stored in its own
+ * table, tagged with the tool that produced it, and never merged into symbols or
+ * references. What the graph adds is the join: a finding on a hub matters more
+ * than the same finding on a leaf, and only the graph knows which is which.
+ *
+ * Everything here is bounded and fail-closed, matching the SCIP importer: a file
+ * over the byte ceiling, a malformed document, or a finding count over the cap
+ * is refused rather than partially applied.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { compareBytes } from "../compare.js";
+// Calibrated against real output rather than guessed: one Salesforce Code
+// Analyzer run over a mid-sized org (pmd + regex + retire-js) produced a 97 MB
+// SARIF log with ~75k findings. A 64 MB ceiling would have refused it.
+export const SARIF_DEFAULT_LIMITS = {
+    maxBytes: 256 * 1024 * 1024,
+    maxFindings: 250_000,
+    timeoutMs: 60_000,
+};
+/**
+ * The ceiling knodin cannot raise. `JSON.parse` needs the document as a single
+ * string and V8 caps string length at 2^29 - 24 bytes on 64-bit, so a log past
+ * this size cannot be read whole regardless of the configured limit. Kept
+ * slightly under the hard maximum to leave room for decoding overhead.
+ */
+const MAX_PARSEABLE_BYTES = 512 * 1024 * 1024;
+/** Byte counts appear in operator-facing errors, so render them readably. */
+function formatBytes(value) {
+    if (value < 1024)
+        return `${value} bytes`;
+    const units = ["KiB", "MiB", "GiB"];
+    let scaled = value / 1024;
+    let unit = 0;
+    while (scaled >= 1024 && unit < units.length - 1) {
+        scaled /= 1024;
+        unit++;
+    }
+    return `${scaled.toFixed(1)} ${units[unit]}`;
+}
+/** SARIF level is optional; analyzers often carry severity on the rule instead. */
+function normalizeLevel(value) {
+    if (value === "error" || value === "warning" || value === "note" || value === "none")
+        return value;
+    // SARIF's own default when level is absent and no rule default applies.
+    return "warning";
+}
+/**
+ * Resolves a SARIF artifact location to a repository-relative POSIX path.
+ *
+ * SARIF permits `file:///abs/path`, a bare absolute path, or a path relative to
+ * some base URI. Anything landing outside the repository is rejected: a findings
+ * file is external input, and a `../` escape must not attach a finding to a path
+ * the caller never indexed.
+ */
+function resolveArtifactPath(repoRoot, uri, uriBase) {
+    if (!uri)
+        return null;
+    let raw = uri;
+    if (raw.startsWith("file://")) {
+        try {
+            raw = decodeURIComponent(new URL(raw).pathname);
+        }
+        catch {
+            return null;
+        }
+    }
+    else {
+        try {
+            raw = decodeURIComponent(raw);
+        }
+        catch {
+            // Not percent-encoded; use as-is.
+        }
+    }
+    // A relative uri may be anchored by an originalUriBaseId value.
+    const anchor = uriBase && path.isAbsolute(uriBase) ? uriBase : repoRoot;
+    const candidate = path.isAbsolute(raw) ? raw : path.resolve(anchor, raw);
+    // Compare real paths. The analyzer may have recorded a route through a
+    // symlink — /var vs /private/var on macOS, or a symlinked checkout — and a
+    // textual prefix check would reject those valid locations. Resolving also
+    // means a symlink pointing outside the repository is still caught, because
+    // the real path is what gets compared.
+    let resolved = path.resolve(candidate);
+    try {
+        resolved = fs.realpathSync(resolved);
+    }
+    catch {
+        // Not on disk: the analyzer may report a file since deleted. Keep the
+        // lexically resolved path so containment is still enforced below.
+    }
+    if (resolved !== repoRoot && !resolved.startsWith(`${repoRoot}${path.sep}`))
+        return null;
+    const relative = path.relative(repoRoot, resolved);
+    if (!relative || relative.startsWith(".."))
+        return null;
+    return relative.split(path.sep).join("/");
+}
+/** Collects `originalUriBaseId` -> absolute path, used to anchor relative uris. */
+function readUriBases(run) {
+    const bases = new Map();
+    const raw = run.originalUriBaseIds;
+    if (!raw || typeof raw !== "object")
+        return bases;
+    for (const [id, entry] of Object.entries(raw)) {
+        const uri = entry?.uri;
+        if (typeof uri !== "string")
+            continue;
+        let value = uri;
+        if (value.startsWith("file://")) {
+            try {
+                value = decodeURIComponent(new URL(value).pathname);
+            }
+            catch {
+                continue;
+            }
+        }
+        bases.set(id, value);
+    }
+    return bases;
+}
+/** Rule metadata by id, so a finding can inherit a helpUri it does not carry. */
+function readRuleHelp(run) {
+    const help = new Map();
+    const driver = run.tool?.driver;
+    const rules = driver?.rules;
+    if (!Array.isArray(rules))
+        return help;
+    for (const rule of rules) {
+        const id = rule.id;
+        const uri = rule.helpUri;
+        if (typeof id === "string" && typeof uri === "string")
+            help.set(id, uri);
+    }
+    return help;
+}
+/** Stable order so repeated imports of an unchanged log agree exactly. */
+function compareFindings(left, right) {
+    if (left.filePath !== right.filePath)
+        return compareBytes(left.filePath, right.filePath);
+    if (left.startLine !== right.startLine)
+        return left.startLine - right.startLine;
+    return compareBytes(left.ruleId, right.ruleId);
+}
+/**
+ * Builds one finding from a SARIF result, or null when the result cannot be
+ * placed inside the repository. The caller counts those rather than guessing
+ * at a path.
+ */
+function readResult(result, context) {
+    const location = Array.isArray(result.locations) ? result.locations[0] : undefined;
+    const physical = location
+        ?.physicalLocation;
+    const artifact = physical?.artifactLocation;
+    const uri = typeof artifact?.uri === "string" ? artifact.uri : "";
+    const baseId = typeof artifact?.uriBaseId === "string" ? artifact.uriBaseId : undefined;
+    // Spec says uriBaseId is a key into originalUriBaseIds. Salesforce Code
+    // Analyzer instead puts the absolute workspace path there directly and
+    // omits originalUriBaseIds entirely, so accept either form.
+    const base = baseId ? (context.uriBases.get(baseId) ?? baseId) : undefined;
+    const filePath = resolveArtifactPath(context.repoRoot, uri, base);
+    if (!filePath)
+        return null;
+    const region = (physical?.region ?? {});
+    const startLine = Number.isInteger(region.startLine) ? region.startLine : 1;
+    const startColumn = Number.isInteger(region.startColumn) ? region.startColumn : 1;
+    const ruleIdRaw = result.ruleId;
+    const ruleId = typeof ruleIdRaw === "string" && ruleIdRaw ? ruleIdRaw : "unknown-rule";
+    const messageText = result.message?.text;
+    const helpUri = context.ruleHelp.get(ruleId);
+    return {
+        ruleId,
+        tool: context.tool,
+        level: normalizeLevel(result.level),
+        message: typeof messageText === "string" ? messageText : "",
+        filePath,
+        startLine,
+        startColumn,
+        // SARIF omits end positions for single-point results; collapse to start.
+        endLine: Number.isInteger(region.endLine) ? region.endLine : startLine,
+        endColumn: Number.isInteger(region.endColumn) ? region.endColumn : startColumn,
+        ...(helpUri ? { helpUri } : {}),
+    };
+}
+/**
+ * Validates the input against the size ceilings and parses it, returning the
+ * SARIF runs. Every refusal names the flag and a value that would admit the
+ * input, because a ceiling the operator cannot move is just a failure.
+ */
+function readRuns(displayPath, inputPath, size, maxBytes) {
+    if (size > maxBytes)
+        throw new Error(`knodin index --sarif: ${displayPath} is ${formatBytes(size)}, over the ` +
+            `${formatBytes(maxBytes)} ceiling. Raise it with ` +
+            `--sarif-max-bytes ${size}, or narrow the analysis that produced the log.`);
+    // A ceiling knodin cannot raise. JSON.parse needs the whole document as one
+    // string, and V8 refuses strings beyond roughly 512 MiB, so a larger log
+    // fails inside readFileSync no matter what --sarif-max-bytes says. Saying so
+    // is more useful than letting "Invalid string length" surface.
+    if (size > MAX_PARSEABLE_BYTES)
+        throw new Error(`knodin index --sarif: ${displayPath} is ${formatBytes(size)}, beyond the ` +
+            `${formatBytes(MAX_PARSEABLE_BYTES)} limit this runtime can parse as one document. ` +
+            `Raising --sarif-max-bytes will not help. Split the analysis by rule selector or ` +
+            `workspace and import each log, which is additive across tools.`);
+    let document;
+    try {
+        document = JSON.parse(fs.readFileSync(inputPath, "utf8"));
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        // A resource failure is not a malformed document, and reporting it as one
+        // sends the reader to inspect a file that is probably fine.
+        if (error instanceof RangeError || /heap|memory|string length/i.test(detail))
+            throw new Error(`knodin index --sarif: ran out of memory reading ${displayPath} ` +
+                `(${formatBytes(size)}). The document is held whole while parsing, so this is a ` +
+                `runtime limit rather than a knodin one. Retry with a larger heap, for example ` +
+                `NODE_OPTIONS=--max-old-space-size=8192, or split the analysis into several logs.`);
+        throw new Error(`knodin index --sarif: ${displayPath} is not valid JSON (${detail})`);
+    }
+    const runs = document?.runs;
+    if (!Array.isArray(runs))
+        throw new Error("knodin index --sarif: input has no runs array; not a SARIF log");
+    return runs;
+}
+/** Applies the defaults for any ceiling the caller left unset. */
+function resolveLimits(options) {
+    return {
+        maxBytes: options.maxBytes ?? SARIF_DEFAULT_LIMITS.maxBytes,
+        maxFindings: options.maxFindings ?? SARIF_DEFAULT_LIMITS.maxFindings,
+        timeoutMs: options.timeoutMs ?? SARIF_DEFAULT_LIMITS.timeoutMs,
+    };
+}
+/**
+ * Reads one SARIF run into findings, or null when the value is not a run that
+ * carries results at all.
+ *
+ * `skipped` counts results whose location could not be placed inside the
+ * repository; the caller reports that total rather than discarding it.
+ *
+ * `budget.carried` is how many findings earlier runs already contributed, so
+ * the ceiling can be enforced against the running total from inside the loop.
+ * It is checked on every finding rather than once per run because the ceiling
+ * exists to stop the work, not to report on it afterwards: a SARIF log commonly
+ * holds exactly one run, so a per-run check would only fire once the entire log
+ * was already accumulated — the case the ceiling is there to prevent.
+ */
+function readRun(rawRun, repoRoot, budget) {
+    if (!rawRun || typeof rawRun !== "object")
+        return null;
+    const run = rawRun;
+    const results = run.results;
+    if (!Array.isArray(results))
+        return null;
+    const driverName = run.tool?.driver?.name;
+    const tool = typeof driverName === "string" && driverName ? driverName : "unknown";
+    const context = {
+        repoRoot,
+        tool,
+        uriBases: readUriBases(run),
+        ruleHelp: readRuleHelp(run),
+    };
+    const findings = [];
+    let skipped = 0;
+    for (const rawResult of results) {
+        if (!rawResult || typeof rawResult !== "object")
+            continue;
+        const finding = readResult(rawResult, context);
+        // A finding we cannot place inside the repository is counted, not guessed at.
+        if (!finding) {
+            skipped++;
+            continue;
+        }
+        findings.push(finding);
+        if (budget.carried + findings.length > budget.maxFindings)
+            throw new Error(`knodin index --sarif: more than ${budget.maxFindings.toLocaleString()} findings. ` +
+                `Raise it with --sarif-max-findings, or narrow the analysis that produced the log.`);
+    }
+    return { tool, findings, skipped };
+}
+/**
+ * Reads and validates a SARIF log, returning findings resolved against the
+ * repository. Throws rather than returning partial facts.
+ */
+export function readSarifLog(repoPath, options) {
+    const started = Date.now();
+    const limits = resolveLimits(options);
+    const repoRoot = fs.realpathSync(path.resolve(repoPath));
+    const inputPath = path.resolve(options.path);
+    const stat = fs.statSync(inputPath, { throwIfNoEntry: false });
+    if (!stat?.isFile())
+        throw new Error(`knodin index --sarif: ${options.path} is not a file`);
+    const runs = readRuns(options.path, inputPath, stat.size, limits.maxBytes);
+    const findings = [];
+    const tools = new Set();
+    const rules = new Set();
+    const files = new Set();
+    let skippedUnresolved = 0;
+    for (const rawRun of runs) {
+        if (Date.now() - started > limits.timeoutMs)
+            throw new Error(`knodin index --sarif: exceeded the ${limits.timeoutMs}ms read budget. ` +
+                `Raise it with --sarif-timeout-ms.`);
+        // readRun enforces the findings ceiling against this running total as it
+        // reads, so it throws on the offending finding rather than after the run.
+        const run = readRun(rawRun, repoRoot, {
+            carried: findings.length,
+            maxFindings: limits.maxFindings,
+        });
+        if (!run)
+            continue;
+        skippedUnresolved += run.skipped;
+        // A tool is only recorded once it has placed a finding, so a run that
+        // resolved nothing does not advertise coverage it did not deliver.
+        if (run.findings.length === 0)
+            continue;
+        tools.add(run.tool);
+        for (const finding of run.findings) {
+            findings.push(finding);
+            rules.add(finding.ruleId);
+            files.add(finding.filePath);
+        }
+    }
+    findings.sort(compareFindings);
+    return {
+        inputPath,
+        bytes: stat.size,
+        tools: [...tools].sort(compareBytes),
+        rules: rules.size,
+        files: files.size,
+        findings,
+        skippedUnresolved,
+        elapsedMs: Date.now() - started,
+    };
+}

package/dist/src/engine/scip-import.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { compareBytes } from "../compare.js";
 export const SCIP_DEFAULT_LIMITS = {
     maxBytes: 64 * 1024 * 1024,
     maxFiles: 10_000,
@@ -16,7 +17,7 @@ function fail(message) {
 }
 function checkDeadline() {
     if (performance.now() > activeDeadline)
-        fail(`import exceeded ${activeTimeoutMs} ms limit`);
+        fail(`import exceeded the ${activeTimeoutMs} ms limit. Raise it with --scip-timeout-ms.`);
 }
 function readVarint(bytes, offset) {
     let value = 0;
@@ -245,7 +246,8 @@ function parseMetadata(index) {
         return [];
     const name = strings(toolInfo, 1)[0];
     const version = strings(toolInfo, 2)[0];
-    return name ? [`${name}${version ? `@${version}` : ""}`] : [];
+    const suffix = version ? `@${version}` : "";
+    return name ? [`${name}${suffix}`] : [];
 }
 export function readScipIndex(repoPath, options) {
     const started = performance.now();
@@ -272,15 +274,21 @@ export function readScipIndex(repoPath, options) {
     }
     if (!inputStat.isFile() || inputStat.isSymbolicLink())
         fail("input must be a regular repository file");
+    // A ceiling nobody can raise is just a failure, so name the flag and a value
+    // that would admit this file.
     if (inputStat.size > limits.maxBytes)
-        fail(`input exceeds ${limits.maxBytes} byte limit`);
+        fail(`input is ${inputStat.size.toLocaleString()} bytes, over the ` +
+            `${limits.maxBytes.toLocaleString()} byte limit. Raise it with ` +
+            `--scip-max-bytes ${inputStat.size}, or narrow the indexer that produced this file.`);
     const bytes = fs.readFileSync(inputPath);
     const index = new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
     const documents = [];
     let parsedFacts = 0;
     const documentCount = countLengthDelimitedFields(index, 2, limits.maxFiles);
     if (documentCount > limits.maxFiles)
-        fail(`index exceeds ${limits.maxFiles} file limit`);
+        fail(`index covers ${documentCount.toLocaleString()} files, over the ` +
+            `${limits.maxFiles.toLocaleString()} file limit. Raise it with ` +
+            `--scip-max-files ${documentCount}, or narrow the indexer that produced this file.`);
     for (const message of messages(index, 2)) {
         const filePath = safeRelativePath(resolvedRepo, strings(message, 1)[0] ?? "");
         const sourceStat = fs.statSync(path.join(resolvedRepo, filePath));
@@ -289,18 +297,21 @@ export function readScipIndex(repoPath, options) {
         const occurrenceCount = countLengthDelimitedFields(message, 2, limits.maxFacts - parsedFacts);
         parsedFacts += occurrenceCount;
         if (parsedFacts > limits.maxFacts)
-            fail(`index exceeds ${limits.maxFacts} fact limit`);
+            fail(`index exceeds the ${limits.maxFacts.toLocaleString()} fact limit. ` +
+                `Raise it with --scip-max-facts, or narrow the indexer that produced this file.`);
         const symbolCount = countLengthDelimitedFields(message, 3, limits.maxFacts - parsedFacts);
         parsedFacts += symbolCount;
         if (parsedFacts > limits.maxFacts)
-            fail(`index exceeds ${limits.maxFacts} fact limit`);
+            fail(`index exceeds the ${limits.maxFacts.toLocaleString()} fact limit. ` +
+                `Raise it with --scip-max-facts, or narrow the indexer that produced this file.`);
         const occurrenceMessages = messages(message, 2);
         const symbolMessages = messages(message, 3);
         for (const symbolMessage of symbolMessages) {
             const remainingRelationships = Math.floor((limits.maxFacts - parsedFacts) / 4);
             parsedFacts += countLengthDelimitedFields(symbolMessage, 4, remainingRelationships) * 4;
             if (parsedFacts > limits.maxFacts)
-                fail(`index exceeds ${limits.maxFacts} fact limit`);
+                fail(`index exceeds the ${limits.maxFacts.toLocaleString()} fact limit. ` +
+                    `Raise it with --scip-max-facts, or narrow the indexer that produced this file.`);
         }
         documents.push({
             filePath,
@@ -389,17 +400,21 @@ export function readScipIndex(repoPath, options) {
         fail(`index exceeds ${limits.maxFacts} fact limit`);
     if (performance.now() - started > limits.timeoutMs)
         fail(`import exceeded ${limits.timeoutMs} ms limit`);
+    // Byte order: imported facts are persisted and compared across runs, so their
+    // order has to be a function of the bytes rather than of host collation.
+    symbols.sort((a, b) => compareBytes(a.filePath, b.filePath) || a.startLine - b.startLine);
+    references.sort((a, b) => compareBytes(a.callerFile, b.callerFile) ||
+        a.line - b.line ||
+        compareBytes(a.calleeSymbol, b.calleeSymbol));
     const result = {
         inputPath: inputRelative.replaceAll("\\", "/"),
         bytes: inputStat.size,
         files: documents.length,
         facts: factCount,
-        languages: [...new Set(documents.map((document) => document.language))].sort(),
-        indexers: parseMetadata(index).sort(),
-        symbols: symbols.sort((a, b) => a.filePath.localeCompare(b.filePath) || a.startLine - b.startLine),
-        references: references.sort((a, b) => a.callerFile.localeCompare(b.callerFile) ||
-            a.line - b.line ||
-            a.calleeSymbol.localeCompare(b.calleeSymbol)),
+        languages: [...new Set(documents.map((document) => document.language))].sort(compareBytes),
+        indexers: parseMetadata(index).sort(compareBytes),
+        symbols,
+        references,
         elapsedMs: Math.round((performance.now() - started) * 1000) / 1000,
     };
     activeDeadline = Number.POSITIVE_INFINITY;

package/dist/src/engine/source-policy.js

@@ -37,6 +37,22 @@ const SOURCE_EXTENSIONS = new Set([
     ".hcl",
     ".dockerfile",
     ".lsif",
+    // Documentation participates as a link-only graph: doc-to-doc and doc-to-code
+    // edges, no symbols. Without it, "which docs describe this subsystem" and
+    // "which docs point at code that no longer exists" are unanswerable.
+    ".md",
+    ".mdx",
+    // CI pipeline definitions participate as link-only template references.
+    ".yml",
+    ".yaml",
+    // The .NET build graph: project-to-project references across services.
+    ".csproj",
+    ".sln",
+    ".props",
+    ".targets",
+    // Razor views/components: the C# members in their @code/@functions blocks.
+    ".cshtml",
+    ".razor",
 ]);
 function isSalesforceBundleMarkup(normalized) {
     return (/^force-app\/main\/default\/lwc\/([A-Za-z][A-Za-z0-9_]*)\/\1\.(?:html|css)$/.test(normalized) ||

package/dist/src/engine/state-paths.js

@@ -0,0 +1,175 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/**
+ * Resolves where a repository's knodin state (graph database, wiki, hook
+ * scaffolding) lives.
+ *
+ * A normal checkout keeps its state in-tree at `<repo>/.knodin`, unchanged from
+ * the original hardcoded behaviour. A *mirror* — a read-only shallow clone of a
+ * repository the user never checked out themselves — keeps its state outside the
+ * clone entirely, so that a refetch can discard and replace the source tree
+ * without destroying a graph that took minutes to build.
+ *
+ * Mirror layout, rooted at {@link mirrorRoot}:
+ *
+ * ```
+ * <root>/registry.json      the mirror index
+ * <root>/.staging/<id>      in-progress clones, renamed into place on success
+ * <root>/<id>/source        the shallow clone
+ * <root>/<id>/state         db.sqlite, wiki/, and friends
+ * <root>/<id>/README        marker: local edits here are discarded on refresh
+ * ```
+ *
+ * Every consumer must route through {@link resolveStateDir} /
+ * {@link resolveDbPath} rather than rebuilding `path.join(repo, ".knodin")`
+ * inline, or mirrors silently read from the wrong location.
+ */
+/** Directory name holding the shallow clone inside a mirror entry. */
+export const MIRROR_SOURCE_DIR = "source";
+/** Directory name holding graph state inside a mirror entry. */
+export const MIRROR_STATE_DIR = "state";
+/** In-tree state directory name for a normal checkout. */
+export const IN_TREE_STATE_DIR = ".knodin";
+const REGISTRY_VERSION = 1;
+const EMPTY_REGISTRY = { version: REGISTRY_VERSION, mirrors: [] };
+/**
+ * Root for all mirror storage. Defaults to `~/.knodin/mirrors` rather than an
+ * XDG data directory: a mirror costs minutes of indexing to rebuild, so it needs
+ * to sit somewhere the user will actually notice and can audit with
+ * `knodin remote list`. `KNODIN_MIRROR_ROOT` overrides it.
+ */
+export function mirrorRoot() {
+    const override = process.env.KNODIN_MIRROR_ROOT;
+    return override ? path.resolve(override) : path.join(os.homedir(), ".knodin", "mirrors");
+}
+/** Path to the mirror registry document. */
+export function mirrorRegistryPath() {
+    return path.join(mirrorRoot(), "registry.json");
+}
+/** Root for in-progress clones, renamed into place only once complete. */
+export function mirrorStagingRoot() {
+    return path.join(mirrorRoot(), ".staging");
+}
+/** Entry root for one mirror: the parent of both `source/` and `state/`. */
+export function mirrorEntryPath(identity) {
+    return path.join(mirrorRoot(), identity);
+}
+/** Absolute path to a mirror's shallow clone. */
+export function mirrorSourcePath(identity) {
+    return path.join(mirrorEntryPath(identity), MIRROR_SOURCE_DIR);
+}
+/** Absolute path to a mirror's graph state directory. */
+export function mirrorStatePath(identity) {
+    return path.join(mirrorEntryPath(identity), MIRROR_STATE_DIR);
+}
+let cache = null;
+function isMirrorRecord(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const record = value;
+    return (typeof record.identity === "string" &&
+        typeof record.url === "string" &&
+        typeof record.path === "string" &&
+        typeof record.fetchedAt === "string" &&
+        typeof record.sha === "string");
+}
+function indexByPath(registry) {
+    const byPath = new Map();
+    for (const record of registry.mirrors)
+        byPath.set(path.resolve(record.path), record);
+    return byPath;
+}
+/**
+ * Reads the mirror registry, memoized against the file's mtime and size so a
+ * mirror added by a concurrent `knodin remote add` is picked up without paying a
+ * JSON parse on every path resolution.
+ *
+ * The memo key is (mtimeMs, size), which is a heuristic rather than a guarantee:
+ * an out-of-process write landing in the same millisecond AND producing the same
+ * byte length would not invalidate it. Accepted deliberately — that requires a
+ * concurrent edit of identical length within one millisecond, the in-process
+ * writer drops the memo explicitly, and the cost of being wrong is one stale
+ * read, not corruption. Recorded so it reads as a decision, not an oversight.
+ *
+ * A missing or corrupt registry reads as empty. That is deliberate too: it
+ * degrades to "no mirrors configured", which routes every repository to its
+ * in-tree state — the pre-existing behaviour — rather than failing a query
+ * outright.
+ */
+export function readMirrorRegistry() {
+    const file = mirrorRegistryPath();
+    let stat;
+    try {
+        stat = fs.statSync(file);
+    }
+    catch {
+        cache = null;
+        return EMPTY_REGISTRY;
+    }
+    if (cache?.mtimeMs === stat.mtimeMs && cache?.size === stat.size)
+        return cache.registry;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        const mirrors = typeof parsed === "object" &&
+            parsed !== null &&
+            Array.isArray(parsed.mirrors)
+            ? parsed.mirrors.filter(isMirrorRecord)
+            : [];
+        const registry = { version: REGISTRY_VERSION, mirrors };
+        cache = { mtimeMs: stat.mtimeMs, size: stat.size, registry, byPath: indexByPath(registry) };
+        return registry;
+    }
+    catch {
+        cache = null;
+        return EMPTY_REGISTRY;
+    }
+}
+/** Persists the registry and drops the memo so the next read reloads it. */
+export function writeMirrorRegistry(registry) {
+    const file = mirrorRegistryPath();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const document = { version: REGISTRY_VERSION, mirrors: registry.mirrors };
+    fs.writeFileSync(file, `${JSON.stringify(document, null, 2)}\n`);
+    cache = null;
+}
+/** Clears the in-process registry memo. Test seam. */
+export function __resetMirrorRegistryCache() {
+    cache = null;
+}
+/**
+ * Returns the mirror record whose clone is at `repoPath`, if any. Matching is on
+ * the resolved path, so a caller passing a relative or unnormalized path still
+ * resolves correctly.
+ */
+export function lookupMirror(repoPath) {
+    readMirrorRegistry();
+    return cache?.byPath.get(path.resolve(repoPath));
+}
+/** True when `repoPath` is a registered read-only mirror clone. */
+export function isMirror(repoPath) {
+    return lookupMirror(repoPath) !== undefined;
+}
+/**
+ * Directory holding knodin state for `repoPath`: in-tree `.knodin` for a normal
+ * checkout, an out-of-tree sibling of the clone for a mirror.
+ */
+export function resolveStateDir(repoPath) {
+    const resolved = path.resolve(repoPath);
+    const mirror = lookupMirror(resolved);
+    if (mirror)
+        return mirrorStatePath(mirror.identity);
+    return path.join(resolved, IN_TREE_STATE_DIR);
+}
+/** Graph database path for `repoPath`. */
+export function resolveDbPath(repoPath) {
+    return path.join(resolveStateDir(repoPath), "db.sqlite");
+}
+/**
+ * Whether opening an index for `repoPath` may write to the repository itself —
+ * false for mirrors, whose source tree is replaced wholesale on refresh and must
+ * stay byte-identical to the remote in the meantime.
+ */
+export function mayWriteToRepository(repoPath) {
+    return !isMirror(repoPath);
+}