@lzehrung/codegraph 2.1.0

package/dist/indexer/build-cache/project-snapshot.js

@@ -0,0 +1,928 @@
+import fsp from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import { brotliCompressSync, brotliDecompressSync, constants as zlibConstants } from "node:zlib";
+import path from "node:path";
+import { buildGraphAdjacency } from "../../graphs/adjacency.js";
+import { buildReferenceCandidateIndex } from "../reference-candidates.js";
+import { BloomFilter, BloomFilterCache } from "../../util/bloomFilter.js";
+import { summarizeAnalysis } from "../../analysisSummary.js";
+import { fileIdentityKey, isFilePathWithinRoot, normalizePath } from "../../util/paths.js";
+import { getNativeRuntimeFingerprint } from "../../native/treeSitterNative.js";
+import { SymbolKind } from "../types.js";
+import { buildSymbolGraph, } from "../../graphs/symbol-graph.js";
+import { getImplementationFingerprint, normalizeGraphOptions } from "./options.js";
+import { cacheRoot } from "./module-cache.js";
+const SNAPSHOT_SYMBOL_KINDS = new Set(Object.values(SymbolKind));
+const PROJECT_SNAPSHOT_VERSION = 4;
+const BLOOM_FILTER_MIN_SIZE = 1_000;
+const BLOOM_FILTER_MAX_SIZE = 1_000_000;
+const BLOOM_FILTER_MIN_HASH_COUNT = 1;
+const BLOOM_FILTER_MAX_HASH_COUNT = 10;
+const DETAILED_SYMBOL_GRAPH_SNAPSHOT_VERSION = 2;
+const DETAILED_SYMBOL_GRAPH_SNAPSHOT_FILENAME = "detailed-symbol-graph.json";
+const SNAPSHOT_TEMP_RETENTION_MS = 24 * 60 * 60 * 1_000;
+const SNAPSHOT_TEMP_SUFFIX = ".tmp";
+const MAX_SNAPSHOT_CACHE_ENTRIES = 32;
+const parsedSnapshotCache = new Map();
+const detailedSymbolGraphCache = new Map();
+export function projectSnapshotFilesSignature(entries) {
+    const hash = createHash("sha256");
+    for (const [file, entry] of [...entries.entries()].sort(([left], [right]) => compareSnapshotPath(left, right))) {
+        hash.update(file);
+        hash.update("\0");
+        hash.update(entry.sig);
+        hash.update("\0");
+        hash.update(entry.gitSig ?? "");
+        hash.update("\0");
+        hash.update(entry.sqlCorpusSig ?? "");
+        hash.update("\0");
+    }
+    return hash.digest("hex");
+}
+export function createProjectSnapshotIdentity(filesSignature, opts) {
+    const hash = createHash("sha256");
+    hash.update("project-index-snapshot-identity-v2");
+    hash.update("\0");
+    hash.update(filesSignature);
+    hash.update("\0");
+    hash.update(JSON.stringify(normalizeGraphOptions(opts?.graph)));
+    hash.update("\0");
+    hash.update(getNativeRuntimeFingerprint(opts?.native));
+    hash.update("\0");
+    hash.update(getImplementationFingerprint());
+    return hash.digest("hex");
+}
+function serializedProjectRoot(projectRoot) {
+    return normalizePath(path.resolve(projectRoot));
+}
+function projectRootMatches(projectRoot, storedProjectRoot) {
+    return fileIdentityKey(path.resolve(projectRoot)) === fileIdentityKey(path.resolve(storedProjectRoot));
+}
+function compareSnapshotPath(left, right) {
+    if (left < right)
+        return -1;
+    if (left > right)
+        return 1;
+    return 0;
+}
+function sameSnapshotFileIdentity(left, right) {
+    return left.size === right.size && left.mtimeMs === right.mtimeMs && left.ctimeMs === right.ctimeMs;
+}
+async function snapshotFileIdentity(snapshotPath) {
+    const stat = await fsp.stat(snapshotPath);
+    return {
+        size: stat.size,
+        mtimeMs: stat.mtimeMs,
+        ctimeMs: stat.ctimeMs,
+    };
+}
+async function fsyncSnapshotFile(snapshotPath) {
+    const handle = await fsp.open(snapshotPath, "r+");
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+function isSnapshotTempName(name, snapshotName) {
+    const prefix = `.${snapshotName}.`;
+    if (!name.startsWith(prefix) || !name.endsWith(SNAPSHOT_TEMP_SUFFIX))
+        return false;
+    const marker = name.slice(prefix.length, -SNAPSHOT_TEMP_SUFFIX.length);
+    return /^\d+\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u.test(marker);
+}
+async function cleanupStaleSnapshotTemps(snapshotPath) {
+    let entries;
+    try {
+        entries = await fsp.readdir(path.dirname(snapshotPath), { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    const cutoff = Date.now() - SNAPSHOT_TEMP_RETENTION_MS;
+    const snapshotName = path.basename(snapshotPath);
+    for (const entry of entries) {
+        if (!entry.isFile() || !isSnapshotTempName(entry.name, snapshotName))
+            continue;
+        const candidate = path.join(path.dirname(snapshotPath), entry.name);
+        try {
+            const stat = await fsp.lstat(candidate);
+            if (stat.mtimeMs > cutoff)
+                continue;
+            await fsp.rm(candidate, { force: true });
+        }
+        catch {
+            // Abandoned snapshot cleanup must not block a cache write.
+        }
+    }
+}
+async function writeSnapshotAtomically(snapshotPath, data) {
+    await fsp.mkdir(path.dirname(snapshotPath), { recursive: true });
+    await cleanupStaleSnapshotTemps(snapshotPath);
+    let tempPath = path.join(path.dirname(snapshotPath), `.${path.basename(snapshotPath)}.${process.pid}.${randomUUID()}${SNAPSHOT_TEMP_SUFFIX}`);
+    try {
+        await fsp.writeFile(tempPath, data, { flag: "wx" });
+        await fsyncSnapshotFile(tempPath);
+        await fsp.rename(tempPath, snapshotPath);
+        tempPath = undefined;
+    }
+    finally {
+        if (tempPath) {
+            await fsp.rm(tempPath, { force: true }).catch(() => undefined);
+        }
+    }
+}
+function setBoundedSnapshotCache(cache, key, value) {
+    cache.delete(key);
+    cache.set(key, value);
+    while (cache.size > MAX_SNAPSHOT_CACHE_ENTRIES) {
+        const oldestKey = cache.keys().next().value;
+        if (oldestKey === undefined)
+            break;
+        cache.delete(oldestKey);
+    }
+}
+function materializeDetailedSymbolGraph(payload) {
+    const graph = structuredClone(payload);
+    return {
+        nodes: new Map(graph.nodes.map((node) => [node.id, node])),
+        edges: graph.edges,
+    };
+}
+function decodeSnapshotPayload(compressed) {
+    return JSON.parse(brotliDecompressSync(compressed).toString("utf8"));
+}
+async function readParsedSnapshot(snapshotPath) {
+    const before = await snapshotFileIdentity(snapshotPath);
+    const cached = parsedSnapshotCache.get(snapshotPath);
+    if (cached && sameSnapshotFileIdentity(cached.identity, before)) {
+        setBoundedSnapshotCache(parsedSnapshotCache, snapshotPath, cached);
+        return { identity: cached.identity, payload: decodeSnapshotPayload(cached.compressed) };
+    }
+    const compressed = Buffer.from(await fsp.readFile(snapshotPath));
+    const payload = decodeSnapshotPayload(compressed);
+    const after = await snapshotFileIdentity(snapshotPath);
+    const entry = { identity: before, compressed };
+    if (sameSnapshotFileIdentity(before, after)) {
+        setBoundedSnapshotCache(parsedSnapshotCache, snapshotPath, entry);
+    }
+    else {
+        parsedSnapshotCache.delete(snapshotPath);
+    }
+    return { identity: before, payload };
+}
+function projectIndexManifestEntries(entries) {
+    return new Map(Array.from(entries, ([file, entry]) => [
+        file,
+        {
+            sig: entry.sig,
+            ...(entry.gitSig ? { gitSig: entry.gitSig } : {}),
+        },
+    ]));
+}
+export async function tryLoadProjectIndexSnapshot(projectRoot, opts, manifestEntries) {
+    const filesSignature = projectSnapshotFilesSignature(manifestEntries);
+    if ((opts?.cache ?? "off") !== "disk")
+        return null;
+    try {
+        const rawPayload = (await readParsedSnapshot(projectSnapshotPath(projectRoot, opts))).payload;
+        const nativeRuntimeFingerprint = getNativeRuntimeFingerprint(opts?.native);
+        const implementationFingerprint = getImplementationFingerprint();
+        if (!isProjectIndexSnapshotPayload(rawPayload) ||
+            rawPayload.filesSignature !== filesSignature ||
+            !projectRootMatches(projectRoot, rawPayload.projectRoot) ||
+            rawPayload.nativeMode !== normalizedSnapshotNativeMode(opts?.native) ||
+            rawPayload.nativeRuntimeFingerprint !== nativeRuntimeFingerprint ||
+            rawPayload.implementationFingerprint !== implementationFingerprint) {
+            return null;
+        }
+        // Payload is freshly JSON.parsed from memoized compressed bytes (no deep clone).
+        const payload = rawPayload;
+        const graph = {
+            nodes: new Set(payload.graph.nodes),
+            edges: payload.graph.edges,
+        };
+        const modules = new Map(payload.modules.map((moduleIndex) => [fileIdentityKey(moduleIndex.file), moduleIndex]));
+        const shouldHydrateBloomFilters = opts?.useBloomFilters ?? true;
+        const index = {
+            graph,
+            graphAdjacency: buildGraphAdjacency(graph),
+            modules,
+            byFile: modules,
+            projectRoot: serializedProjectRoot(projectRoot),
+            ...(payload.nativeMode ? { nativeMode: payload.nativeMode } : {}),
+            exportCache: new Map(),
+            scopeCache: new Map(),
+            ...(shouldHydrateBloomFilters && payload.bloomFilters
+                ? { bloomFilters: deserializeBloomFilterCache(payload.bloomFilters) }
+                : {}),
+            ...(payload.projectFiles ? { projectFiles: payload.projectFiles } : {}),
+            referenceCandidates: buildReferenceCandidateIndex(modules),
+            ...(opts?.cache ? { cacheMode: opts.cache, cacheRootDir: cacheRoot(projectRoot, opts) } : {}),
+            manifestEntries: projectIndexManifestEntries(manifestEntries),
+            projectSnapshotIdentity: createProjectSnapshotIdentity(filesSignature, opts),
+        };
+        return {
+            index: {
+                ...index,
+                ...(payload.analysis ? { analysis: payload.analysis } : {}),
+            },
+            ...(payload.analysisReport ? { analysisReport: payload.analysisReport } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Load only the bloom-filter section of the last-written project snapshot, without requiring
+ * the whole snapshot to match this build's files signature or native runtime fingerprint.
+ * Bloom filters are a pure function of a file's text, so a filter persisted for a given file
+ * is safe to reuse after its snapshot's root and implementation fingerprints are validated.
+ * Only the bloom section is then read, so a corrupt payload is rejected without walking
+ * `graph.edges` / `modules`. Returns `null` when disk caching is off, `useBloomFilters` is
+ * disabled, or no valid snapshot with bloom data exists.
+ */
+export async function tryLoadPersistedBloomFilters(projectRoot, opts) {
+    if ((opts?.cache ?? "off") !== "disk" || (opts?.useBloomFilters ?? true) === false)
+        return null;
+    try {
+        const payload = (await readParsedSnapshot(projectSnapshotPath(projectRoot, opts))).payload;
+        const bloomFilters = persistedBloomFiltersFromSnapshot(payload, projectRoot);
+        if (!bloomFilters)
+            return null;
+        return deserializeBloomFilterCache(bloomFilters);
+    }
+    catch {
+        return null;
+    }
+}
+/** Light validation for bloom hydration: snapshot version, root identity, and bloom section only. */
+function persistedBloomFiltersFromSnapshot(value, projectRoot) {
+    if (!value || typeof value !== "object")
+        return null;
+    const payload = value;
+    if (payload.version !== PROJECT_SNAPSHOT_VERSION ||
+        typeof payload.projectRoot !== "string" ||
+        !projectRootMatches(projectRoot, payload.projectRoot) ||
+        payload.implementationFingerprint !== getImplementationFingerprint()) {
+        return null;
+    }
+    if (!isSerializedBloomFilterRecord(payload.bloomFilters))
+        return null;
+    return payload.bloomFilters;
+}
+export async function writeProjectIndexSnapshot(projectRoot, opts, index, filesSignature) {
+    const projectSnapshotIdentity = createProjectSnapshotIdentity(filesSignature, opts);
+    const serializedBloomFilters = index.bloomFilters
+        ? serializeBloomFilterCache(index.bloomFilters, Array.from(index.byFile.values(), (module) => module.file))
+        : undefined;
+    const snapshotAnalysisReport = analysisReportFromBuildReport(index.buildReport);
+    const snapshotAnalysis = index.buildReport ? summarizeAnalysis({ index, report: index.buildReport }) : index.analysis;
+    const payload = {
+        version: PROJECT_SNAPSHOT_VERSION,
+        filesSignature,
+        projectRoot: serializedProjectRoot(projectRoot),
+        nativeRuntimeFingerprint: getNativeRuntimeFingerprint(opts?.native),
+        implementationFingerprint: getImplementationFingerprint(),
+        graph: {
+            nodes: [...index.graph.nodes],
+            edges: index.graph.edges,
+        },
+        modules: [...index.byFile.values()],
+        ...(normalizedSnapshotNativeMode(index.nativeMode)
+            ? { nativeMode: normalizedSnapshotNativeMode(index.nativeMode) }
+            : {}),
+        ...(index.projectFiles ? { projectFiles: index.projectFiles } : {}),
+        ...(serializedBloomFilters ? { bloomFilters: serializedBloomFilters } : {}),
+        ...(snapshotAnalysis ? { analysis: snapshotAnalysis } : {}),
+        ...(snapshotAnalysisReport ? { analysisReport: snapshotAnalysisReport } : {}),
+    };
+    try {
+        const snapshotPath = projectSnapshotPath(projectRoot, opts);
+        const compressed = brotliCompressSync(JSON.stringify(payload), {
+            params: { [zlibConstants.BROTLI_PARAM_QUALITY]: 4 },
+        });
+        await writeSnapshotAtomically(snapshotPath, compressed);
+        const identity = await snapshotFileIdentity(snapshotPath);
+        setBoundedSnapshotCache(parsedSnapshotCache, snapshotPath, { identity, compressed });
+        index.projectSnapshotIdentity = projectSnapshotIdentity;
+    }
+    catch {
+        delete index.projectSnapshotIdentity;
+        // Snapshot writes are an optimization; cache write failures must not fail indexing.
+    }
+}
+function projectSnapshotPath(projectRoot, opts) {
+    return path.join(cacheRoot(projectRoot, opts), "project-index-snapshot.json");
+}
+export async function tryLoadDetailedSymbolGraphSnapshot(projectRoot, opts, index) {
+    if ((opts?.cache ?? "off") !== "disk" || !index.projectSnapshotIdentity)
+        return null;
+    try {
+        const snapshotPath = detailedSymbolGraphSnapshotPath(projectRoot, opts);
+        const observedIdentity = await snapshotFileIdentity(snapshotPath);
+        const cached = detailedSymbolGraphCache.get(snapshotPath);
+        if (cached &&
+            cached.projectSnapshotIdentity === index.projectSnapshotIdentity &&
+            sameSnapshotFileIdentity(cached.identity, observedIdentity)) {
+            setBoundedSnapshotCache(detailedSymbolGraphCache, snapshotPath, cached);
+            return materializeDetailedSymbolGraph(cached.graph);
+        }
+        const parsed = await readParsedSnapshot(snapshotPath);
+        const payload = parsed.payload;
+        if (!isDetailedSymbolGraphSnapshotPayload(payload) ||
+            !projectRootMatches(projectRoot, payload.projectRoot) ||
+            payload.implementationFingerprint !== getImplementationFingerprint() ||
+            payload.projectSnapshotIdentity !== index.projectSnapshotIdentity) {
+            return null;
+        }
+        const graph = materializeDetailedSymbolGraph(payload.graph);
+        if (!(await isDetailedSymbolGraphCompatibleWithProject(projectRoot, index, graph))) {
+            return null;
+        }
+        const identity = await snapshotFileIdentity(snapshotPath);
+        if (!sameSnapshotFileIdentity(parsed.identity, identity))
+            return null;
+        setBoundedSnapshotCache(detailedSymbolGraphCache, snapshotPath, {
+            identity,
+            projectSnapshotIdentity: index.projectSnapshotIdentity,
+            graph: payload.graph,
+        });
+        return graph;
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeDetailedSymbolGraphSnapshot(projectRoot, opts, index, graph) {
+    if ((opts?.cache ?? "off") !== "disk" || !index.projectSnapshotIdentity)
+        return;
+    const payload = {
+        version: DETAILED_SYMBOL_GRAPH_SNAPSHOT_VERSION,
+        projectRoot: serializedProjectRoot(projectRoot),
+        implementationFingerprint: getImplementationFingerprint(),
+        graphHash: detailedSymbolGraphContentHash(index.projectSnapshotIdentity, graph),
+        projectSnapshotIdentity: index.projectSnapshotIdentity,
+        graph: {
+            nodes: [...graph.nodes.values()],
+            edges: graph.edges,
+        },
+    };
+    try {
+        const snapshotPath = detailedSymbolGraphSnapshotPath(projectRoot, opts);
+        parsedSnapshotCache.delete(snapshotPath);
+        detailedSymbolGraphCache.delete(snapshotPath);
+        const compressed = brotliCompressSync(JSON.stringify(payload), {
+            params: { [zlibConstants.BROTLI_PARAM_QUALITY]: 4 },
+        });
+        await writeSnapshotAtomically(snapshotPath, compressed);
+        const identity = await snapshotFileIdentity(snapshotPath);
+        const cachedPayload = structuredClone(payload);
+        setBoundedSnapshotCache(parsedSnapshotCache, snapshotPath, { identity, compressed });
+        setBoundedSnapshotCache(detailedSymbolGraphCache, snapshotPath, {
+            identity,
+            projectSnapshotIdentity: index.projectSnapshotIdentity,
+            graph: cachedPayload.graph,
+        });
+    }
+    catch {
+        // Detailed graph persistence is an optimization; source parsing remains authoritative.
+    }
+}
+function detailedSymbolGraphSnapshotPath(projectRoot, opts) {
+    const root = path.resolve(cacheRoot(projectRoot, opts));
+    const snapshotPath = path.resolve(root, DETAILED_SYMBOL_GRAPH_SNAPSHOT_FILENAME);
+    if (!isFilePathWithinRoot(root, snapshotPath)) {
+        throw new Error(`Detailed symbol graph snapshot escaped cache root: ${snapshotPath}`);
+    }
+    return snapshotPath;
+}
+function detailedSymbolGraphContentHash(projectSnapshotIdentity, graph) {
+    const hash = createHash("sha256");
+    hash.update(projectSnapshotIdentity);
+    hash.update("\0");
+    hash.update(JSON.stringify({
+        nodes: [...graph.nodes.values()],
+        edges: graph.edges,
+    }));
+    return hash.digest("hex");
+}
+function isDetailedSymbolGraphSnapshotPayload(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const payload = value;
+    if (payload.version !== DETAILED_SYMBOL_GRAPH_SNAPSHOT_VERSION ||
+        typeof payload.projectRoot !== "string" ||
+        typeof payload.implementationFingerprint !== "string" ||
+        !/^[a-f0-9]{64}$/.test(payload.implementationFingerprint) ||
+        typeof payload.projectSnapshotIdentity !== "string" ||
+        !/^[a-f0-9]{64}$/.test(payload.projectSnapshotIdentity) ||
+        typeof payload.graphHash !== "string" ||
+        !/^[a-f0-9]{64}$/.test(payload.graphHash) ||
+        !payload.graph ||
+        !Array.isArray(payload.graph.nodes) ||
+        !payload.graph.nodes.every(isSymbolNode) ||
+        !Array.isArray(payload.graph.edges) ||
+        !payload.graph.edges.every(isSymbolEdge)) {
+        return false;
+    }
+    // `graphHash` is still written at snapshot-write time (its format is validated above) but
+    // no longer re-verified here on load: recomputing it means re-stringifying the whole
+    // graph and re-hashing it, measured at ~36ms on an 11MB sidecar, and it is a
+    // self-consistency check on this file's own bytes, not a check against the current
+    // project. The atomic temp-file-then-rename write (`writeDetailedSymbolGraphSnapshot`
+    // below) already rules out a torn/partial write, and
+    // `isDetailedSymbolGraphCompatibleWithProject` independently re-derives and compares
+    // every node's semantic fields (name, kind, complexity, docstring, lineSpan) against the
+    // current index, which catches tampered or corrupted graph content this hash would have
+    // caught too -- so the hash added no protection the other checks do not already provide.
+    return new Set(payload.graph.nodes.map((node) => node.id)).size === payload.graph.nodes.length;
+}
+function isSymbolNode(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const node = value;
+    return (typeof node.id === "string" &&
+        !!node.id &&
+        typeof node.file === "string" &&
+        !!node.file &&
+        typeof node.name === "string" &&
+        !!node.name &&
+        isSymbolNodeKind(node.kind) &&
+        (node.docstring === undefined || typeof node.docstring === "string") &&
+        isOptionalNonnegativeInteger(node.lineSpan) &&
+        isOptionalNonnegativeFiniteNumber(node.complexity) &&
+        (node.visibility === undefined || isSymbolVisibility(node.visibility)) &&
+        (node.implementationTarget === undefined || typeof node.implementationTarget === "boolean") &&
+        isOptionalNonnegativeInteger(node.memberArity));
+}
+function isSymbolNodeKind(value) {
+    return (value === "function" ||
+        value === "class" ||
+        value === "variable" ||
+        value === "interface" ||
+        value === "type" ||
+        value === "default" ||
+        value === "table" ||
+        value === "view" ||
+        value === "index" ||
+        value === "constraint" ||
+        value === "routine" ||
+        value === "import" ||
+        value === "namespaceImport");
+}
+function isSymbolVisibility(value) {
+    return value === "public" || value === "private" || value === "protected" || value === "internal";
+}
+function isOptionalNonnegativeInteger(value) {
+    return value === undefined || (typeof value === "number" && Number.isInteger(value) && value >= 0);
+}
+function isOptionalNonnegativeFiniteNumber(value) {
+    return value === undefined || (typeof value === "number" && Number.isFinite(value) && value >= 0);
+}
+function isDetailedRange(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const range = value;
+    if (!isDetailedPosition(range.start) || !isDetailedPosition(range.end))
+        return false;
+    if (range.start.index !== undefined && range.end.index !== undefined) {
+        return range.start.index <= range.end.index;
+    }
+    if (range.start.line !== range.end.line)
+        return range.start.line <= range.end.line;
+    return range.start.column <= range.end.column;
+}
+function isDetailedPosition(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const position = value;
+    return (typeof position.line === "number" &&
+        Number.isInteger(position.line) &&
+        position.line >= 0 &&
+        typeof position.column === "number" &&
+        Number.isInteger(position.column) &&
+        position.column >= 0 &&
+        (position.index === undefined ||
+            (typeof position.index === "number" && Number.isInteger(position.index) && position.index >= 0)));
+}
+function isSymbolEdge(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const edge = value;
+    return (typeof edge.from === "string" &&
+        typeof edge.to === "string" &&
+        (edge.label === undefined || typeof edge.label === "string") &&
+        (edge.site === undefined ||
+            (!!edge.site &&
+                typeof edge.site === "object" &&
+                typeof edge.site.file === "string" &&
+                !!edge.site.file &&
+                isDetailedRange(edge.site.range))));
+}
+async function isDetailedSymbolGraphCompatibleWithProject(projectRoot, index, graph) {
+    const normalizedRoot = path.resolve(projectRoot);
+    const indexedFiles = new Set([...index.byFile.keys()]);
+    for (const node of graph.nodes.values()) {
+        const normalizedFile = normalizePath(node.file);
+        if (!indexedFiles.has(fileIdentityKey(normalizedFile)) ||
+            !isFilePathWithinRoot(normalizedRoot, normalizedFile) ||
+            !node.id.startsWith(`${normalizedFile}::`)) {
+            return false;
+        }
+    }
+    for (const edge of graph.edges) {
+        if (!graph.nodes.has(edge.from) || !graph.nodes.has(edge.to))
+            return false;
+        if (edge.site) {
+            const normalizedSiteFile = normalizePath(edge.site.file);
+            if (!indexedFiles.has(fileIdentityKey(normalizedSiteFile)) ||
+                !isFilePathWithinRoot(normalizedRoot, normalizedSiteFile)) {
+                return false;
+            }
+        }
+    }
+    const base = await buildSymbolGraph(index);
+    if (graph.nodes.size !== base.nodes.size)
+        return false;
+    for (const [id, expected] of base.nodes) {
+        const actual = graph.nodes.get(id);
+        if (!actual ||
+            actual.file !== expected.file ||
+            actual.name !== expected.name ||
+            actual.kind !== expected.kind ||
+            actual.docstring !== expected.docstring ||
+            actual.lineSpan !== expected.lineSpan ||
+            actual.complexity !== expected.complexity) {
+            return false;
+        }
+    }
+    return sameSymbolEdgeMultiset(base.edges, graph.edges);
+}
+function sameSymbolEdgeMultiset(expected, actual) {
+    if (expected.length !== actual.length)
+        return false;
+    const counts = new Map();
+    for (const edge of expected) {
+        const key = serializedSymbolEdge(edge);
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    for (const edge of actual) {
+        const key = serializedSymbolEdge(edge);
+        const remaining = counts.get(key);
+        if (remaining === undefined)
+            return false;
+        if (remaining === 1)
+            counts.delete(key);
+        else
+            counts.set(key, remaining - 1);
+    }
+    return !counts.size;
+}
+function serializedSymbolEdge(edge) {
+    return JSON.stringify({
+        from: edge.from,
+        to: edge.to,
+        label: edge.label,
+        site: edge.site
+            ? {
+                file: edge.site.file,
+                range: {
+                    start: {
+                        line: edge.site.range.start.line,
+                        column: edge.site.range.start.column,
+                        ...(edge.site.range.start.index !== undefined ? { index: edge.site.range.start.index } : {}),
+                    },
+                    end: {
+                        line: edge.site.range.end.line,
+                        column: edge.site.range.end.column,
+                        ...(edge.site.range.end.index !== undefined ? { index: edge.site.range.end.index } : {}),
+                    },
+                },
+            }
+            : undefined,
+    });
+}
+function normalizedSnapshotNativeMode(nativeMode) {
+    if (nativeMode === undefined || nativeMode === "auto")
+        return undefined;
+    return nativeMode;
+}
+function isSnapshotNativeMode(value) {
+    return value === "auto" || value === "on" || value === "off";
+}
+function isProjectFileInfo(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const projectFile = value;
+    return (typeof projectFile.path === "string" &&
+        (projectFile.kind === "file" || projectFile.kind === "dir") &&
+        isProjectFileType(projectFile.type) &&
+        isProjectFileRole(projectFile.role) &&
+        typeof projectFile.projectRoot === "string" &&
+        (projectFile.name === undefined || typeof projectFile.name === "string"));
+}
+function isProjectFileType(value) {
+    return (value === "node" ||
+        value === "typescript" ||
+        value === "python" ||
+        value === "rust" ||
+        value === "go" ||
+        value === "maven" ||
+        value === "gradle" ||
+        value === "dotnet" ||
+        value === "ruby" ||
+        value === "php" ||
+        value === "swift" ||
+        value === "native" ||
+        value === "ide");
+}
+function isProjectFileRole(value) {
+    return value === "manifest" || value === "lockfile" || value === "config" || value === "solution" || value === "ide";
+}
+function isProjectIndexSnapshotPayload(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const payload = value;
+    return (payload.version === PROJECT_SNAPSHOT_VERSION &&
+        typeof payload.filesSignature === "string" &&
+        typeof payload.projectRoot === "string" &&
+        typeof payload.nativeRuntimeFingerprint === "string" &&
+        typeof payload.implementationFingerprint === "string" &&
+        /^[a-f0-9]{64}$/.test(payload.implementationFingerprint) &&
+        !!payload.graph &&
+        Array.isArray(payload.graph.nodes) &&
+        payload.graph.nodes.every((node) => typeof node === "string") &&
+        Array.isArray(payload.graph.edges) &&
+        payload.graph.edges.every(isGraphEdge) &&
+        Array.isArray(payload.modules) &&
+        payload.modules.every(isModuleIndex) &&
+        (payload.nativeMode === undefined || isSnapshotNativeMode(payload.nativeMode)) &&
+        (payload.bloomFilters === undefined || isSerializedBloomFilterRecord(payload.bloomFilters)) &&
+        (payload.analysis === undefined || isAnalysisSummary(payload.analysis)) &&
+        (payload.analysisReport === undefined || isSnapshotAnalysisReport(payload.analysisReport)) &&
+        (payload.projectFiles === undefined ||
+            (Array.isArray(payload.projectFiles) && payload.projectFiles.every(isProjectFileInfo))));
+}
+function analysisReportFromBuildReport(report) {
+    if (!report?.backend && !report?.graph) {
+        return undefined;
+    }
+    return {
+        ...(report.backend ? { backend: report.backend } : {}),
+        ...(report.graph ? { graph: report.graph } : {}),
+    };
+}
+function isSnapshotAnalysisReport(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const report = value;
+    return ((report.backend === undefined || isBackendReport(report.backend)) &&
+        (report.graph === undefined || isGraphReport(report.graph)));
+}
+function isBackendReport(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const report = value;
+    return (!!report.native &&
+        isNativeBackendReport(report.native) &&
+        (report.parser === undefined || isParserBackendDegradationReport(report.parser)));
+}
+function isNativeBackendReport(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const report = value;
+    return (typeof report.available === "boolean" &&
+        typeof report.enabled === "boolean" &&
+        Array.isArray(report.supportedLanguageIds) &&
+        report.supportedLanguageIds.every((languageId) => typeof languageId === "string") &&
+        typeof report.filesUsed === "number" &&
+        typeof report.filesFellBack === "number" &&
+        isUnknownRecord(report.fallbackReasons) &&
+        isUnknownRecord(report.byLanguage) &&
+        Array.isArray(report.errors));
+}
+function isParserBackendDegradationReport(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const report = value;
+    return typeof report.total === "number" && isNumberRecord(report.byLanguage) && Array.isArray(report.files);
+}
+function isGraphReport(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const report = value;
+    return !!report.fallbackImportExtraction && isFallbackImportExtractionReport(report.fallbackImportExtraction);
+}
+function isFallbackImportExtractionReport(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const report = value;
+    return (typeof report.total === "number" &&
+        isNumberRecord(report.byLanguage) &&
+        isUnknownRecord(report.files) &&
+        (report.byReason === undefined || isNumberRecord(report.byReason)));
+}
+function isUnknownRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function isNumberRecord(value) {
+    return isUnknownRecord(value) && Object.values(value).every((entry) => typeof entry === "number");
+}
+function isAnalysisSummary(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const summary = value;
+    return ((summary.mode === "semantic" || summary.mode === "mixed" || summary.mode === "reduced") &&
+        (summary.backend === "native" ||
+            summary.backend === "mixed" ||
+            summary.backend === "graph-only" ||
+            summary.backend === "unknown") &&
+        typeof summary.parserDegradedFiles === "number" &&
+        typeof summary.fallbackImportExtractionFiles === "number" &&
+        typeof summary.nativeFilesUsed === "number" &&
+        typeof summary.nativeFilesFellBack === "number" &&
+        typeof summary.label === "string");
+}
+function serializeBloomFilterCache(cache, files) {
+    const serialized = {};
+    for (const file of files) {
+        const filter = cache.get(file);
+        if (!filter)
+            continue;
+        const metadata = filter.getMetadata();
+        serialized[file] = {
+            size: metadata.size,
+            hashCount: metadata.hashCount,
+            bitsBase64: filter.toBuffer().toString("base64"),
+        };
+    }
+    return Object.keys(serialized).length ? serialized : undefined;
+}
+function deserializeBloomFilterCache(serialized) {
+    const cache = new BloomFilterCache();
+    for (const [file, filter] of Object.entries(serialized)) {
+        cache.set(file, BloomFilter.fromBuffer(Buffer.from(filter.bitsBase64, "base64"), filter.size, filter.hashCount));
+    }
+    return cache;
+}
+function isSerializedBloomFilterRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    return Object.values(value).every(isSerializedBloomFilter);
+}
+function isSerializedBloomFilter(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const filter = value;
+    if (typeof filter.size !== "number" ||
+        !Number.isInteger(filter.size) ||
+        filter.size < BLOOM_FILTER_MIN_SIZE ||
+        filter.size > BLOOM_FILTER_MAX_SIZE ||
+        typeof filter.hashCount !== "number" ||
+        !Number.isInteger(filter.hashCount) ||
+        filter.hashCount < BLOOM_FILTER_MIN_HASH_COUNT ||
+        filter.hashCount > BLOOM_FILTER_MAX_HASH_COUNT ||
+        typeof filter.bitsBase64 !== "string") {
+        return false;
+    }
+    const maxBytes = Math.ceil(filter.size / 8);
+    const maxBase64Length = Math.ceil(maxBytes / 3) * 4;
+    return filter.bitsBase64.length === maxBase64Length;
+}
+function isModuleIndex(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const moduleIndex = value;
+    return (typeof moduleIndex.file === "string" &&
+        Array.isArray(moduleIndex.locals) &&
+        moduleIndex.locals.every(isSymbolDef) &&
+        Array.isArray(moduleIndex.imports) &&
+        moduleIndex.imports.every(isImportBinding) &&
+        Array.isArray(moduleIndex.exports) &&
+        moduleIndex.exports.every(isExportEntry));
+}
+function isSymbolDef(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const symbol = value;
+    return (typeof symbol.file === "string" &&
+        typeof symbol.localName === "string" &&
+        isSymbolKind(symbol.kind) &&
+        isRange(symbol.range) &&
+        (symbol.docstring === undefined || typeof symbol.docstring === "string") &&
+        (symbol.lineSpan === undefined || typeof symbol.lineSpan === "number") &&
+        (symbol.complexity === undefined || typeof symbol.complexity === "number"));
+}
+function isImportBinding(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const binding = value;
+    if (typeof binding.from !== "string" ||
+        !isResolvedImportTarget(binding.resolved) ||
+        !isOptionalBoolean(binding.typeOnly) ||
+        !isImportMechanism(binding.mechanism) ||
+        !isResolvedType(binding.resolvedType) ||
+        !isOptionalNumber(binding.confidence)) {
+        return false;
+    }
+    if (binding.kind === "default")
+        return typeof binding.local === "string";
+    if (binding.kind === "named") {
+        return (typeof binding.local === "string" &&
+            typeof binding.imported === "string" &&
+            (binding.phpImportType === undefined ||
+                binding.phpImportType === "class" ||
+                binding.phpImportType === "function" ||
+                binding.phpImportType === "const"));
+    }
+    if (binding.kind === "namespace")
+        return typeof binding.localNS === "string";
+    return binding.kind === "star";
+}
+function isExportEntry(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const entry = value;
+    if (entry.type === "local")
+        return typeof entry.exportedAs === "string" && isSymbolDef(entry.target);
+    if (entry.type === "reexport") {
+        return (typeof entry.exportedAs === "string" &&
+            typeof entry.fromModule === "string" &&
+            typeof entry.sourceSpecifier === "string" &&
+            (entry.moduleSpecifier === undefined || typeof entry.moduleSpecifier === "string") &&
+            isOptionalBoolean(entry.typeOnly));
+    }
+    if (entry.type === "namespaceReexport") {
+        return (typeof entry.exportedAs === "string" &&
+            typeof entry.fromModule === "string" &&
+            (entry.moduleSpecifier === undefined || typeof entry.moduleSpecifier === "string") &&
+            isOptionalBoolean(entry.typeOnly));
+    }
+    if (entry.type === "exportStar") {
+        return (typeof entry.fromModule === "string" &&
+            typeof entry.sourceSpecifier === "string" &&
+            (entry.moduleSpecifier === undefined || typeof entry.moduleSpecifier === "string") &&
+            isOptionalBoolean(entry.typeOnly));
+    }
+    return false;
+}
+function isResolvedImportTarget(value) {
+    if (value === undefined || typeof value === "string")
+        return true;
+    return Boolean(value && typeof value === "object" && typeof value.external === "string");
+}
+function isImportMechanism(value) {
+    return value === undefined || value === "es" || value === "cjs" || value === "python" || value === "php";
+}
+function isResolvedType(value) {
+    return value === undefined || value === "heuristic" || value === "precise";
+}
+function isOptionalBoolean(value) {
+    return value === undefined || typeof value === "boolean";
+}
+function isOptionalNumber(value) {
+    return value === undefined || typeof value === "number";
+}
+function isSymbolKind(value) {
+    return SNAPSHOT_SYMBOL_KINDS.has(value);
+}
+function isRange(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const range = value;
+    return isPos(range.start) && isPos(range.end);
+}
+function isPos(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const pos = value;
+    return (typeof pos.line === "number" &&
+        typeof pos.column === "number" &&
+        (pos.index === undefined || typeof pos.index === "number"));
+}
+function isGraphEdge(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const edge = value;
+    const resolved = edge.resolved;
+    return (typeof edge.from === "string" &&
+        isEdgeTo(edge.to) &&
+        typeof edge.raw === "string" &&
+        (edge.typeOnly === undefined || typeof edge.typeOnly === "boolean") &&
+        (resolved === undefined || resolved === "heuristic" || resolved === "precise") &&
+        (edge.confidence === undefined || typeof edge.confidence === "number"));
+}
+function isEdgeTo(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const edgeTo = value;
+    if (edgeTo.type === "file")
+        return typeof edgeTo.path === "string";
+    if (edgeTo.type === "external")
+        return typeof edgeTo.name === "string";
+    return false;
+}
+//# sourceMappingURL=project-snapshot.js.map