archstrict 0.0.0 → 0.1.0

package/dist/edge-cache.js

@@ -0,0 +1,530 @@
+// Responsibility: store and validate a per-file, incrementally-updatable
+// snapshot of each analyzed file's own syntactic import walk, module
+// augmentations, and resolved specifiers. Shards avoid whole-cache I/O.
+// Boundary: cache failures fall back to analysis; this module never parses
+// a file or resolves an import itself - module-graph.ts owns both, and
+// hands this module only the results to persist or read back.
+//
+// On-disk layout: one header file (`edges.json`, at the path the caller
+// passes) plus a fixed SHARD_COUNT of shard files beside it, under an
+// `edges/` directory. A file's own shard is `shardIndexForRelativePath` of
+// its path relative to the project root - stable across runs and across
+// which files happen to exist, so a build only ever touches the shards
+// whose own membership or content actually changed. The header records
+// each shard's file name and a sha256 of its exact on-disk bytes; a reader
+// that finds a shard missing, unreadable, or hash-mismatched treats only
+// that shard's own files as a cache miss (re-walked and re-resolved by
+// module-graph.ts's own per-file loop) - never the rest of the cache, and
+// never an error.
+//
+// Each shard's own JSON is a compact encoding, not one object per file:
+// a `paths` string table (each path stored relative to the project root,
+// via node:path's own relative result - reversible for a resolved file
+// outside the root too, since the result can carry leading `..` segments),
+// a `specifiers` string table, a
+// `packageNames` string table, and one array-of-indexes tuple per file
+// (never an object keyed by that file's own path). Each file's own
+// `resolutions` are encoded inline, aligned by position with that file's
+// own `imports` (never as a second object keyed by specifier) - a `null`
+// slot is exactly the imports this project's own walk never gives a
+// resolutions entry to (a node builtin), not "unresolved" (which encodes
+// as `0`, distinct from `null`).
+//
+// Correctness contract - every input that can change a resolved edge, and
+// where it is covered:
+// - A file's own text (syntax, imports, exports, `require(...)`) - covered
+//   by that file's own mtimeMs+size (module-graph.ts's own reparse gate).
+//   Limit: an edit that keeps the exact same byte size AND whose mtime is
+//   restored (or never advances - some filesystems and some tools truncate
+//   mtime precision) is invisible to this gate; nothing else in this
+//   fingerprint covers it either.
+// - The nearest package.json "type" a file resolves under (decides
+//   ESM-vs-CJS `impliedNodeFormat`, which each of that file's own imports'
+//   `mode` is derived from) - covered by each file's own `impliedNodeFormat`
+//   field, recomputed every build with no parse needed
+//   (ts.getImpliedNodeFormatForFile reads only package.json), and compared
+//   against the stored value.
+// - The nearest tsconfig's own effective compiler options (module,
+//   moduleResolution, paths, ...) - covered by each file's own
+//   `optionsIndex` into `optionsTable` below, recomputed every build the
+//   same cheap way (module-graph.ts's own per-directory
+//   `compilerOptionsForFile` cache) and compared against the stored value.
+//   A file whose `impliedNodeFormat` or `optionsIndex` changed is reparsed
+//   exactly like a file whose own text changed, without dropping the whole
+//   cache.
+// - Which files are analyzed at all (a file added, deleted, or renamed) -
+//   covered by `resolutionFingerprint`'s own `filesHash`, the sorted
+//   analyzed-file list hashed once, not embedded per file. A file moving
+//   into or out of a declared module is a different input: `filesHash`
+//   does not move for it (the file was already analyzed either way) -
+//   covered instead by each file's own per-specifier resolution record,
+//   resolved (never assumed unresolved) the moment a record is missing
+//   for a specifier this build now has a reason to ask about - see
+//   module-graph.ts's own per-file loop.
+// - Every package.json under the project root outside node_modules (its
+//   own `exports`/`imports` map, or a plain `main`/`type`) - covered by
+//   `resolutionFingerprint`'s own `packages` map (path -> mtime).
+// - Every file outside node_modules with a resolvable extension
+//   (.ts/.tsx/.mts/.cts/.d.ts/.d.mts/.d.cts/.js/.mjs/.cjs/.jsx/.json),
+//   analyzed or not, excluded or not, in dist/ or not - a specifier can
+//   resolve to any of these, and only its existence (never its content)
+//   matters - covered by `resolutionFingerprint`'s own
+//   `resolvableFilesHash`.
+// - The lockfile in use (which real dependency version - and so which
+//   real files - a bare specifier resolves to) - covered by
+//   `resolutionFingerprint`'s own `lockPath`/`lockMtime`, the nearest
+//   lockfile found at the project root or any ancestor directory.
+// - Every node_modules directory on the path module resolution actually
+//   walks (the project root's own, and each ancestor's, up to the nearest
+//   lockfile's own directory or the filesystem root) - covered by
+//   `resolutionFingerprint`'s own `nodeModules` map, one entry per such
+//   directory, each a map of top-level package name to that package's own
+//   package.json mtime (read after following a symlink, so `npm link` and
+//   a workspace's own symlinked sibling both count). Limit: an edit made
+//   directly to an already-installed package's own file (not its
+//   package.json) is invisible to this map, and to every other input this
+//   fingerprint reads - deleting node_modules/.cache/archstrict is the
+//   only way to force a rebuild for that case.
+// - Every distinct effective compiler-options object across the project -
+//   covered by `optionsTable` (hashed once per distinct object, not once
+//   per file) folded into `resolutionFingerprint`.
+// - This project's own built code (module-graph.js, edge-cache.js) and
+//   the installed typescript's own version - a local build with a
+//   changed walker or resolver, or a different typescript resolving the
+//   same specifiers differently, produces entries the old combination
+//   never would have; covered by `codeVersionHash` and `typescriptVersion`,
+//   together with `archstrictVersion`, any one mismatch dropping the
+//   whole cache.
+// - Which shard a given file's own entry landed in, and whether that
+//   shard's own bytes on disk still match what this cache last wrote -
+//   covered by the header's own per-shard content hash (above); a shard
+//   whose file is missing or whose hash no longer matches contributes no
+//   entries at all, which module-graph.ts's own per-file loop already
+//   treats exactly like a brand-new file (no old entry -> reparse and
+//   re-resolve), scoped to that one shard's own files.
+// A file whose own reparse gate holds AND whose `resolutionFingerprint`
+// still matches reuses its stored `resolutions` outright, with no
+// `ts.resolveModuleName` call at all - the common, nothing-changed case a
+// `check` hook run hits on every keystroke that isn't an import edit.
+// A changed `resolutionFingerprint` alone (nothing in this file's own
+// reparse gate) re-resolves every specifier project-wide, from each file's
+// own already-cached `imports` - no file is reparsed just for that. Every
+// walked file gets a resolution record for every one of its own
+// specifiers, whether or not it currently belongs to a declared module,
+// and a specifier with no record is resolved rather than assumed
+// unresolved - see module-graph.ts's own per-file loop for why.
+// `fromModule`/`toModule`/`externalPackage` are never stored here: they
+// depend on the current `declaredModules` alone, which a graph build
+// already has in hand for free, and storing them would mean invalidating
+// this whole cache on every config edit instead of none.
+import { readFileSync, mkdirSync, writeFileSync, renameSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { makeAbsolutePosix, makeProjectRelativePosix } from "./project-path.js";
+// Bumped whenever the on-disk shape (header or shard encoding) changes -
+// an old cache is then a silent miss (parseHeader rejects the unknown
+// schema number), never a crash on a shape this code no longer produces.
+export const CACHE_SCHEMA = 11;
+// Fixed, not derived from project size - see this module's own header.
+// module-graph.ts's own per-file loop marks a shard dirty by this same
+// function; both sides agree only because they share it.
+export const SHARD_COUNT = 64;
+export function shardIndexForRelativePath(relativePath) {
+    const digest = createHash("sha256").update(relativePath).digest();
+    return digest.readUInt32BE(0) % SHARD_COUNT;
+}
+export function resolutionKey(imp) {
+    return `${imp.specifier}\u0000${imp.mode ?? ""}`;
+}
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function strings(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function isMode(value) {
+    return value === undefined || (typeof value === "number" && Number.isInteger(value));
+}
+function isImportRecord(value) {
+    if (!record(value) || !record(value.fromPosition))
+        return false;
+    return typeof value.specifier === "string" && typeof value.isTypeOnly === "boolean" && typeof value.isDynamic === "boolean" &&
+        isMode(value.mode) &&
+        [value.fromPosition.line, value.fromPosition.column].every((n) => Number.isInteger(n) && Number(n) > 0);
+}
+function isModuleAugmentationSpecifier(value) {
+    return record(value) && typeof value.specifier === "string" && isMode(value.mode);
+}
+function isResolution(value) {
+    if (value === "unresolved")
+        return true;
+    return record(value) && typeof value.resolvedFile === "string" &&
+        (value.isExternalLibraryImport === undefined || value.isExternalLibraryImport === true) &&
+        (value.packageName === undefined || typeof value.packageName === "string");
+}
+function isFileEntry(value) {
+    if (!record(value))
+        return false;
+    if (typeof value.mtimeMs !== "number" || !Number.isFinite(value.mtimeMs))
+        return false;
+    if (typeof value.size !== "number" || !Number.isFinite(value.size))
+        return false;
+    if (!Number.isInteger(value.optionsIndex) || Number(value.optionsIndex) < 0)
+        return false;
+    if (!isMode(value.impliedNodeFormat))
+        return false;
+    if (!Array.isArray(value.imports) || !value.imports.every(isImportRecord))
+        return false;
+    if (!Number.isInteger(value.unsupportedSyntaxCount) || Number(value.unsupportedSyntaxCount) < 0)
+        return false;
+    if (typeof value.isScript !== "boolean" || typeof value.hasAmbientDeclarations !== "boolean" ||
+        typeof value.hasModuleAugmentation !== "boolean")
+        return false;
+    if (!Array.isArray(value.moduleAugmentationSpecifiers) ||
+        !value.moduleAugmentationSpecifiers.every(isModuleAugmentationSpecifier) ||
+        value.hasModuleAugmentation !== (value.moduleAugmentationSpecifiers.length > 0))
+        return false;
+    if (value.unreadable !== undefined && value.unreadable !== true)
+        return false;
+    if (!record(value.resolutions) || !Object.values(value.resolutions).every(isResolution))
+        return false;
+    return true;
+}
+function isShardHeaderEntry(value) {
+    return record(value) && typeof value.file === "string" && typeof value.hash === "string";
+}
+function parseHeader(value) {
+    if (!record(value) || value.schema !== CACHE_SCHEMA)
+        return undefined;
+    if (typeof value.archstrictVersion !== "string" || typeof value.codeVersionHash !== "string" ||
+        typeof value.typescriptVersion !== "string" || !strings(value.optionsTable) ||
+        typeof value.resolutionFingerprint !== "string")
+        return undefined;
+    if (!Array.isArray(value.shards) || value.shards.length !== SHARD_COUNT ||
+        !value.shards.every((s) => s === null || isShardHeaderEntry(s)))
+        return undefined;
+    return {
+        archstrictVersion: value.archstrictVersion, codeVersionHash: value.codeVersionHash,
+        typescriptVersion: value.typescriptVersion, optionsTable: value.optionsTable,
+        resolutionFingerprint: value.resolutionFingerprint, shards: value.shards,
+    };
+}
+const FLAG_IS_SCRIPT = 1;
+const FLAG_HAS_AMBIENT_DECLARATIONS = 2;
+const FLAG_UNREADABLE = 4;
+const FLAG_HAS_MODULE_AUGMENTATION = 8;
+function makeStringTable() {
+    const table = [];
+    const indexByValue = new Map();
+    return { table, index: (value) => {
+            let idx = indexByValue.get(value);
+            if (idx === undefined) {
+                idx = table.length;
+                table.push(value);
+                indexByValue.set(value, idx);
+            }
+            return idx;
+        } };
+}
+// One shard's own entries, sorted by relative path - deterministic bytes
+// for the same content, so a rewrite that changes nothing produces the
+// same hash (and so `writeEdgeCache` can tell "unchanged" from "changed"
+// without a byte compare).
+function encodeShard(entries, relativePath) {
+    const paths = makeStringTable();
+    const specifiers = makeStringTable();
+    const packageNames = makeStringTable();
+    const encodeResolution = (res) => {
+        if (res === "unresolved")
+            return 0;
+        return [paths.index(relativePath(res.resolvedFile)), res.isExternalLibraryImport ? 1 : 0,
+            res.packageName === undefined ? null : packageNames.index(res.packageName)];
+    };
+    const files = [];
+    for (const relPath of [...entries.keys()].sort()) {
+        const entry = entries.get(relPath);
+        const flags = (entry.isScript ? FLAG_IS_SCRIPT : 0) | (entry.hasAmbientDeclarations ? FLAG_HAS_AMBIENT_DECLARATIONS : 0) |
+            (entry.unreadable ? FLAG_UNREADABLE : 0) | (entry.hasModuleAugmentation ? FLAG_HAS_MODULE_AUGMENTATION : 0);
+        const encodedImports = entry.imports.map((imp) => {
+            const key = resolutionKey(imp);
+            const res = Object.hasOwn(entry.resolutions, key) ? entry.resolutions[key] : undefined;
+            return [
+                specifiers.index(imp.specifier), imp.fromPosition.line, imp.fromPosition.column,
+                imp.isTypeOnly ? 1 : 0, imp.isDynamic ? 1 : 0, imp.mode ?? null,
+                res === undefined ? null : encodeResolution(res),
+            ];
+        });
+        const encodedModuleAugmentations = entry.moduleAugmentationSpecifiers.map((augmentation) => [specifiers.index(augmentation.specifier), augmentation.mode ?? null]);
+        files.push([
+            paths.index(relPath), entry.mtimeMs, entry.size, entry.optionsIndex,
+            entry.impliedNodeFormat ?? null, entry.unsupportedSyntaxCount, flags, encodedImports, encodedModuleAugmentations,
+        ]);
+    }
+    return { paths: paths.table, specifiers: specifiers.table, packageNames: packageNames.table, files };
+}
+// The exact inverse of encodeShard - `undefined` means the shard's own
+// JSON does not have this module's own shape (a version mismatch that
+// slipped past the header's schema check, or a hand-edited file); the
+// caller then drops the whole shard, never a single bad file inside it,
+// matching the header's own hash check (also whole-shard).
+function decodeShard(raw, restoreAbsolutePath, optionsCount) {
+    if (!record(raw))
+        return undefined;
+    const { paths, specifiers, packageNames, files } = raw;
+    if (!strings(paths) || !strings(specifiers) || !strings(packageNames) || !Array.isArray(files))
+        return undefined;
+    const result = new Map();
+    for (const tuple of files) {
+        if (!Array.isArray(tuple) || tuple.length !== 9)
+            return undefined;
+        const [pathIdx, mtimeMs, size, optionsIndex, impliedRaw, unsupportedSyntaxCount, flags, importsRaw, augmentationsRaw] = tuple;
+        if (!Number.isInteger(pathIdx) || pathIdx < 0 || pathIdx >= paths.length)
+            return undefined;
+        if (!Number.isInteger(optionsIndex) || optionsIndex < 0 || optionsIndex >= optionsCount)
+            return undefined;
+        if (!isMode(impliedRaw === null ? undefined : impliedRaw))
+            return undefined;
+        if (typeof flags !== "number")
+            return undefined;
+        if (!Array.isArray(importsRaw))
+            return undefined;
+        if (!Array.isArray(augmentationsRaw))
+            return undefined;
+        const imports = [];
+        const resolutions = {};
+        let ok = true;
+        for (const impTuple of importsRaw) {
+            if (!ok)
+                break;
+            if (!Array.isArray(impTuple) || impTuple.length !== 7) {
+                ok = false;
+                break;
+            }
+            const [specIdx, line, column, isTypeOnly, isDynamic, modeRaw, resRaw] = impTuple;
+            if (!Number.isInteger(specIdx) || specIdx < 0 || specIdx >= specifiers.length) {
+                ok = false;
+                break;
+            }
+            const mode = (modeRaw === null ? undefined : modeRaw);
+            const imp = {
+                specifier: specifiers[specIdx],
+                fromPosition: { line: line, column: column },
+                isTypeOnly: isTypeOnly === 1, isDynamic: isDynamic === 1, mode,
+            };
+            if (!isImportRecord(imp)) {
+                ok = false;
+                break;
+            }
+            imports.push(imp);
+            if (resRaw === null)
+                continue;
+            let resolution;
+            if (resRaw === 0)
+                resolution = "unresolved";
+            else if (Array.isArray(resRaw) && resRaw.length === 3) {
+                const [resPathIdx, isExternal, packageNameIdx] = resRaw;
+                if (!Number.isInteger(resPathIdx) || resPathIdx < 0 || resPathIdx >= paths.length) {
+                    ok = false;
+                    break;
+                }
+                if (packageNameIdx !== null && (!Number.isInteger(packageNameIdx) || packageNameIdx < 0 || packageNameIdx >= packageNames.length)) {
+                    ok = false;
+                    break;
+                }
+                resolution = {
+                    resolvedFile: restoreAbsolutePath(paths[resPathIdx]),
+                    ...(isExternal === 1 ? { isExternalLibraryImport: true } : {}),
+                    ...(packageNameIdx !== null ? { packageName: packageNames[packageNameIdx] } : {}),
+                };
+            }
+            else {
+                ok = false;
+                break;
+            }
+            if (!isResolution(resolution)) {
+                ok = false;
+                break;
+            }
+            resolutions[resolutionKey(imp)] = resolution;
+        }
+        if (!ok)
+            return undefined;
+        const moduleAugmentationSpecifiers = [];
+        for (const augmentationTuple of augmentationsRaw) {
+            if (!Array.isArray(augmentationTuple) || augmentationTuple.length !== 2)
+                return undefined;
+            const [specifierIdx, modeRaw] = augmentationTuple;
+            if (!Number.isInteger(specifierIdx) || specifierIdx < 0 ||
+                specifierIdx >= specifiers.length || !isMode(modeRaw === null ? undefined : modeRaw))
+                return undefined;
+            moduleAugmentationSpecifiers.push({
+                specifier: specifiers[specifierIdx],
+                mode: (modeRaw === null ? undefined : modeRaw),
+            });
+        }
+        const entry = {
+            mtimeMs: mtimeMs, size: size, optionsIndex: optionsIndex,
+            ...(impliedRaw !== null ? { impliedNodeFormat: impliedRaw } : {}),
+            imports, unsupportedSyntaxCount: unsupportedSyntaxCount,
+            isScript: (flags & FLAG_IS_SCRIPT) !== 0,
+            hasAmbientDeclarations: (flags & FLAG_HAS_AMBIENT_DECLARATIONS) !== 0,
+            hasModuleAugmentation: (flags & FLAG_HAS_MODULE_AUGMENTATION) !== 0,
+            moduleAugmentationSpecifiers,
+            ...((flags & FLAG_UNREADABLE) !== 0 ? { unreadable: true } : {}),
+            resolutions,
+        };
+        if (!isFileEntry(entry))
+            return undefined;
+        result.set(restoreAbsolutePath(paths[pathIdx]), entry);
+    }
+    return result;
+}
+// Reads the header, then each shard it names, one at a time - never the
+// whole cache as one string (this module's own header). A shard that is
+// missing, hash-mismatched, or fails to decode contributes no entries and
+// is never an error; the header itself failing to parse (an unknown
+// schema, or any other malformed shape) is the one case that misses the
+// whole cache.
+export function readEdgeCache(path, projectRoot) {
+    let headerRaw;
+    try {
+        headerRaw = JSON.parse(readFileSync(path).toString("utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    const header = parseHeader(headerRaw);
+    if (header === undefined)
+        return undefined;
+    const dir = dirname(path);
+    const files = {};
+    const restoreAbsolutePath = makeAbsolutePosix(projectRoot);
+    for (const shardEntry of header.shards) {
+        if (shardEntry === null)
+            continue;
+        let buf;
+        try {
+            buf = readFileSync(join(dir, shardEntry.file));
+        }
+        catch {
+            continue;
+        }
+        if (createHash("sha256").update(buf).digest("hex") !== shardEntry.hash)
+            continue;
+        let raw;
+        try {
+            raw = JSON.parse(buf.toString("utf8"));
+        }
+        catch {
+            continue;
+        }
+        const decoded = decodeShard(raw, restoreAbsolutePath, header.optionsTable.length);
+        if (decoded === undefined)
+            continue;
+        for (const [absPath, entry] of decoded)
+            files[absPath] = entry;
+    }
+    return {
+        schema: CACHE_SCHEMA, archstrictVersion: header.archstrictVersion, codeVersionHash: header.codeVersionHash,
+        typescriptVersion: header.typescriptVersion, optionsTable: header.optionsTable,
+        resolutionFingerprint: header.resolutionFingerprint, files, shards: header.shards,
+    };
+}
+// Writes only the shards that actually need it, then the header last (so
+// a process killed mid-write leaves the header pointing at shards that
+// are each internally consistent, never a header naming a shard this
+// write never finished).
+//
+// `forceAll`: true the moment `archstrictVersion`/`codeVersionHash`/
+// `typescriptVersion` mismatched, or the resolution fingerprint moved -
+// either one can change every file's own entry, so every shard that has
+// any current file is rewritten regardless of `dirtyPaths`.
+// `dirtyPaths`/`deletedPaths`: every file whose own entry changed this
+// build (reparsed or re-resolved) or disappeared - each marks its own
+// shard for a rewrite; every other shard's own header line is copied
+// forward from `oldShards` untouched (no read of its own bytes, no
+// rewrite).
+export function writeEdgeCache(path, projectRoot, cache, oldShards, dirtyPaths, deletedPaths, forceAll) {
+    const dir = dirname(path);
+    const shardsDir = join(dir, "edges");
+    const relativePath = makeProjectRelativePosix(projectRoot);
+    const groups = new Map();
+    for (const [absPath, entry] of Object.entries(cache.files)) {
+        const relPath = relativePath(absPath);
+        const idx = shardIndexForRelativePath(relPath);
+        let group = groups.get(idx);
+        if (group === undefined) {
+            group = new Map();
+            groups.set(idx, group);
+        }
+        group.set(relPath, entry);
+    }
+    const dirtyShards = new Set();
+    for (const absPath of dirtyPaths)
+        dirtyShards.add(shardIndexForRelativePath(relativePath(absPath)));
+    for (const absPath of deletedPaths)
+        dirtyShards.add(shardIndexForRelativePath(relativePath(absPath)));
+    try {
+        mkdirSync(shardsDir, { recursive: true });
+    }
+    catch { /* best-effort; each shard write below no-ops on failure too */ }
+    const shards = [];
+    for (let i = 0; i < SHARD_COUNT; i++) {
+        const group = groups.get(i);
+        if (group === undefined) {
+            shards.push(null);
+            continue;
+        }
+        const oldEntry = oldShards?.[i] ?? null;
+        // A group with files but no prior header line can only happen for a
+        // shard this build must write anyway (forceAll, or every one of its
+        // files freshly dirty) - defended here too, so a bug in that
+        // reasoning loses no data silently.
+        const mustRewrite = forceAll || dirtyShards.has(i) || oldEntry === null;
+        if (!mustRewrite) {
+            shards.push(oldEntry);
+            continue;
+        }
+        const file = `edges/${i}.json`;
+        const json = JSON.stringify(encodeShard(group, relativePath));
+        const hash = createHash("sha256").update(json).digest("hex");
+        const fullPath = join(dir, file);
+        const temporary = `${fullPath}.${randomUUID()}.tmp`;
+        try {
+            writeFileSync(temporary, json, { flag: "wx" });
+            renameSync(temporary, fullPath);
+            shards.push({ file, hash });
+        }
+        catch {
+            // A read-only shard directory must not prevent a fresh analysis
+            // result - the next successful write replaces this line too.
+            shards.push(null);
+        }
+        finally {
+            try {
+                rmSync(temporary, { force: true });
+            }
+            catch { /* best-effort cleanup on read-only filesystems */ }
+        }
+    }
+    const header = {
+        schema: CACHE_SCHEMA, archstrictVersion: cache.archstrictVersion, codeVersionHash: cache.codeVersionHash,
+        typescriptVersion: cache.typescriptVersion, optionsTable: cache.optionsTable,
+        resolutionFingerprint: cache.resolutionFingerprint, shards,
+    };
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(temporary, JSON.stringify(header), { flag: "wx" });
+        renameSync(temporary, path);
+    }
+    catch {
+        // A read-only cache directory must not prevent a fresh analysis result.
+    }
+    finally {
+        try {
+            rmSync(temporary, { force: true });
+        }
+        catch { /* best-effort cleanup on read-only filesystems */ }
+    }
+}

package/dist/mcp-server.js

@@ -0,0 +1,111 @@
+// Responsibility: expose architecture queries through the MCP protocol.
+// Boundary: delegates rule evaluation to verbs and retains one warm graph per server.
+// McpServer's registration helpers typically expect zod input schemas. These inputs
+// are simple enough for manual validation, so Server uses raw JSON Schema instead.
+// This avoids a second direct dependency: zod remains an SDK dependency, not a project import.
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { createWarmGraph } from "./warm-graph.js";
+import { check } from "./verbs/check.js";
+import { rules } from "./verbs/rules.js";
+import { search } from "./verbs/search.js";
+import { simulate } from "./verbs/simulate.js";
+const tools = [
+    { name: "check", description: "Check project architecture, optionally focused on one file.",
+        inputSchema: { type: "object", properties: { file: { type: "string" } }, additionalProperties: false } },
+    { name: "rules", description: "Show the rules that govern a path.",
+        inputSchema: { type: "object", properties: { path: { type: "string" } }, required: ["path"], additionalProperties: false } },
+    { name: "search", description: "Search public exports by name.",
+        inputSchema: { type: "object", properties: { query: { type: "string" } }, required: ["query"], additionalProperties: false } },
+    { name: "simulate", description: "Check a proposed change set in memory. A change to the project's archstrict.config.ts previews a proposed config.",
+        inputSchema: { type: "object", properties: { changes: { type: "array", items: {
+                        type: "object", properties: { path: { type: "string" }, content: { type: ["string", "null"] } },
+                        required: ["path", "content"], additionalProperties: false,
+                    } } }, required: ["changes"], additionalProperties: false } },
+];
+// The declared inputSchema supports client discovery; the low-level SDK does not
+// enforce it before this handler runs. A client can skip validation, so these
+// simple fields need manual checks without another schema library.
+function stringField(args, field) {
+    const value = args[field];
+    if (typeof value !== "string")
+        throw new TypeError(`${field} must be a string`);
+    return value;
+}
+export function createArchstrictMcpServer(projectRoot) {
+    // One server spans many calls in the same process, unlike a one-shot CLI invocation.
+    // Retain each file's import records across refresh calls; a new holder per call would lose that reuse.
+    const warm = createWarmGraph();
+    const server = new Server({ name: "archstrict", version: "0.0.0" }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, () => ({ tools }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        // A failed call must leave the session available for later calls. Convert bad input,
+        // config-load failures, and invalid paths into tool errors the agent can read as data.
+        // Keep rejected promises inside this handler rather than letting them escape through the transport.
+        try {
+            const args = request.params.arguments ?? {};
+            // Discovery lists allowed tools and keys, but clients can send others.
+            // Reject them here rather than trusting the advertised schema.
+            const tool = tools.find(tool => tool.name === request.params.name);
+            if (tool === undefined)
+                throw new TypeError(`Unknown tool: ${request.params.name}`);
+            for (const key of Object.keys(args)) {
+                if (!Object.hasOwn(tool.inputSchema.properties ?? {}, key))
+                    throw new TypeError(`Unexpected argument: ${key}`);
+            }
+            let result;
+            switch (request.params.name) {
+                case "check":
+                    // Agents can check after every edit, as the PostToolUse hook does, so parsed-source reuse matters here.
+                    // Rules already uses a lighter graph builder without a type checker.
+                    // Search keeps its separate cold, one-shot design. Simulate reads
+                    // the disk cache without persisting its in-memory proposal.
+                    result = await check(projectRoot, args.file === undefined ? undefined : stringField(args, "file"), { buildGraph: warm.refresh });
+                    break;
+                case "rules":
+                    result = await rules(projectRoot, stringField(args, "path"));
+                    break;
+                case "search":
+                    result = await search(projectRoot, stringField(args, "query"));
+                    break;
+                case "simulate": {
+                    // Clients can also bypass the nested change schema. Check each entry by hand
+                    // so malformed paths or content cannot reach the simulation as trusted values.
+                    if (!Array.isArray(args.changes))
+                        throw new TypeError("changes must be an array");
+                    const changes = args.changes.map((change) => {
+                        if (typeof change !== "object" || change === null || Array.isArray(change)) {
+                            throw new TypeError("Each change must be an object");
+                        }
+                        const entry = change;
+                        if (Object.keys(entry).some(key => key !== "path" && key !== "content")) {
+                            throw new TypeError("Each change must contain only path and content");
+                        }
+                        const path = stringField(entry, "path");
+                        if (entry.content !== null && typeof entry.content !== "string") {
+                            throw new TypeError("content must be a string or null");
+                        }
+                        return { path, content: entry.content };
+                    });
+                    result = await simulate(projectRoot, changes);
+                    break;
+                }
+                default:
+                    throw new TypeError(`Unknown tool: ${request.params.name}`);
+            }
+            return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        }
+        catch (error) {
+            return { isError: true, content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }] };
+        }
+    });
+    return server;
+}
+// The CLI and plugin wrapper need identical server construction and stdio setup.
+// A shared entry point keeps those callers aligned when startup behavior changes.
+export async function startArchstrictMcpServer(projectRoot) {
+    const server = createArchstrictMcpServer(projectRoot);
+    await server.connect(new StdioServerTransport());
+    return server;
+}