archstrict 0.0.0 → 0.1.0

package/dist/verbs/rules.js

@@ -0,0 +1,188 @@
+// Responsibility: describe a current or proposed path using the project's config.
+// Boundary: projects source-side constraints; actual target evaluation remains with check.
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { classifyFile, compileGlob } from "../classify.js";
+import { buildModuleGraphForRules, DEFAULT_SURFACE, moduleForDeclaredFile, surfaceGlobsFor, toProjectRelativePosix } from "../module-graph.js";
+import { checkMustBeEmpty } from "../rules/must-be-empty.js";
+import { uncoveredViolationFor } from "../rules/uncovered.js";
+import { groupForRelFile, suggestUncovered } from "../module-candidates.js";
+import { assertSequenceListsValue, formatPredicate, matchesPredicate, sequenceFor } from "../rules/constraints.js";
+import { formatConfigPointerLines, loadConfig } from "./check.js";
+import { createConfigLocator, locateViolation } from "../config-pointer.js";
+// The graph uses real paths. Resolve existing ancestors so new paths also
+// agree with it through directory symlinks, including macOS temporary roots.
+function canonicalPath(path) {
+    const missing = [];
+    let ancestor = path;
+    while (!existsSync(ancestor)) {
+        const parent = dirname(ancestor);
+        missing.unshift(relative(parent, ancestor));
+        ancestor = parent;
+    }
+    return join(realpathSync(ancestor), ...missing);
+}
+// Shares module-candidates.ts's grouping/naming with check's own
+// checkUncoveredModules, so a queried path's `do:` names the identical
+// entry check would report for that same file (rules.test.ts checks this
+// directly). A planned (not yet existing) path was never in
+// graph.outsideFiles, so it's appended to the file list groupAnalyzedFiles
+// sees - otherwise a lone planned file in an empty directory would be
+// missing from its own group entirely.
+function uncoveredViolationForQuery(resolvedPath, rel, exists, module, excluded, graph, config) {
+    if (excluded)
+        return undefined;
+    const isUncovered = exists ? graph.outsideFiles.includes(resolvedPath) : module === undefined;
+    if (!isUncovered)
+        return undefined;
+    const outsideRelFiles = graph.outsideFiles.map(graph.relativePath);
+    const relFiles = exists ? outsideRelFiles : [...outsideRelFiles, rel];
+    const groups = suggestUncovered(relFiles, config.declaredModules ?? []);
+    return uncoveredViolationFor(resolvedPath, graph.rootDir, groupForRelFile(rel, groups));
+}
+export async function rules(projectRoot, path) {
+    const root = realpathSync(projectRoot);
+    const resolvedPath = canonicalPath(resolve(path));
+    const rel = toProjectRelativePosix(resolvedPath, root);
+    if (rel === ".." || rel.startsWith("../") || isAbsolute(rel)) {
+        throw new Error(`rules ${path}: path is outside project root '${root}'`);
+    }
+    const config = await loadConfig(resolve(root, "archstrict.config.ts"));
+    const configLocator = createConfigLocator(config);
+    const graph = buildModuleGraphForRules({ projectRoot: root, declaredModules: config.declaredModules, exclude: config.exclude, surface: config.surface });
+    const exists = existsSync(resolvedPath);
+    const excluded = (config.exclude ?? []).some((glob) => compileGlob(glob).test(rel));
+    let module;
+    let isSurfaceFile = false;
+    if (exists) {
+        const owner = [...graph.modules.values()].find((m) => m.files.includes(resolvedPath));
+        module = owner?.name;
+        isSurfaceFile = owner?.surfaceFiles.includes(resolvedPath) ?? false;
+    }
+    else {
+        module = moduleForDeclaredFile(resolvedPath, root, config.declaredModules ?? []);
+        const declaration = config.declaredModules?.find((dm) => dm.name === module);
+        if (declaration !== undefined) {
+            isSurfaceFile = surfaceGlobsFor(declaration, root, config.surface ?? DEFAULT_SURFACE)
+                .some((glob) => compileGlob(glob).test(rel));
+        }
+    }
+    const modules = [...graph.modules.values()].sort((a, b) => a.name.localeCompare(b.name));
+    const sourceTags = classifyFile(rel, config);
+    const tags = [...sourceTags].sort();
+    const allowDenyConstraints = (config.edges?.allowDeny ?? [])
+        .filter((rule) => tags.includes(rule.source))
+        .map((rule) => ({
+        source: rule.source,
+        targetNamespace: rule.targetNamespace,
+        allow: rule.allow ? [...rule.allow] : undefined,
+        deny: rule.deny ? [...rule.deny] : undefined,
+        sameGroupExempt: true,
+        exceptionsFromP: (rule.exceptions ?? []).filter((ex) => compileGlob(ex.from).test(rel))
+            .map((ex) => ({ to: ex.to, because: ex.because })),
+        edgeType: rule.edgeType ?? "both",
+        importForm: rule.importForm ?? "both",
+        because: rule.because,
+    }));
+    const orderConstraints = [];
+    for (const rule of config.edges?.order ?? []) {
+        const ownLayerTag = [...sourceTags].find((tag) => tag.startsWith(`${rule.tagNamespace}:`));
+        if (ownLayerTag === undefined)
+            continue;
+        let withinValue;
+        if (rule.within !== undefined) {
+            const withinTag = [...sourceTags].find((tag) => tag.startsWith(`${rule.within}:`));
+            if (withinTag === undefined)
+                continue;
+            withinValue = withinTag.slice(rule.within.length + 1);
+        }
+        const sequence = sequenceFor(rule, withinValue);
+        if (sequence === undefined)
+            continue;
+        // Detect the same configuration error as check before an edge exists:
+        // the queried path's own layer must already be placed in its sequence.
+        assertSequenceListsValue(rule, withinValue, sequence, ownLayerTag);
+        const ownLayer = ownLayerTag.slice(rule.tagNamespace.length + 1);
+        const idx = sequence.indexOf(ownLayer);
+        orderConstraints.push({
+            tagNamespace: rule.tagNamespace,
+            within: rule.within,
+            ownLayer,
+            sequence: [...sequence],
+            // computeOrder permits targetIndex <= sourceIndex (downward-only),
+            // so this prefix includes the queried path's own layer.
+            mayDependOn: sequence.slice(0, idx + 1),
+            edgeType: rule.edgeType ?? "both",
+            importForm: rule.importForm ?? "both",
+            because: rule.because,
+        });
+    }
+    const pointConstraints = (config.edges?.point ?? [])
+        .filter((rule) => matchesPredicate(rule.from, rel, new Set(tags)))
+        .map((rule) => ({
+        identifier: `${formatPredicate(rule.from)} -> ${formatPredicate(rule.to)}`,
+        forbiddenTo: formatPredicate(rule.to),
+        edgeType: rule.edgeType ?? "both",
+        importForm: rule.importForm ?? "both",
+        because: rule.because,
+    }));
+    const mustBeEmptyViolation = excluded ? undefined : checkMustBeEmpty([rel], config)[0];
+    const uncoveredViolation = uncoveredViolationForQuery(resolvedPath, rel, exists, module, excluded, graph, config);
+    return {
+        allowDenyConstraints,
+        orderConstraints,
+        pointConstraints,
+        path: resolvedPath,
+        exists,
+        excluded,
+        module,
+        tags,
+        isSurfaceFile,
+        importableFrom: modules.filter((m) => m.name !== module && m.surfaceFiles.length > 0)
+            .map((m) => ({ module: m.name, surfaceFiles: m.surfaceFiles })),
+        friendAccess: modules.flatMap((m) => m.friends
+            .filter((friend) => compileGlob(friend.from).test(rel))
+            .map((friend) => ({ module: m.name, file: friend.fileGlob, from: friend.from, because: friend.because }))),
+        mustBeEmptyViolation: mustBeEmptyViolation === undefined
+            ? undefined
+            : locateViolation(mustBeEmptyViolation, config, configLocator),
+        uncoveredViolation: uncoveredViolation === undefined
+            ? undefined
+            : locateViolation(uncoveredViolation, config, configLocator),
+    };
+}
+export function formatRulesText(result) {
+    const lines = [];
+    if (result.excluded)
+        lines.push("excluded - out of scope, none of the following apply");
+    lines.push(`path: ${result.path}`, `exists: ${result.exists}`, `excluded: ${result.excluded ? "yes" : "no"}`, `module: ${result.module ?? "(none)"}`, `tags: ${result.tags.length > 0 ? result.tags.join(", ") : "(none)"}`, `surface file: ${result.isSurfaceFile ? "yes" : "no"}`, `must-be-empty: ${result.excluded ? "out of scope" : result.mustBeEmptyViolation ? "violation" : "ok"}`);
+    for (const violation of [result.mustBeEmptyViolation, result.uncoveredViolation]) {
+        if (violation === undefined)
+            continue;
+        lines.push(`[${violation.rule}] ${violation.path}:${violation.line}:${violation.column}`, `  evidence: ${violation.evidence}`, `  because: ${violation.because}`);
+        lines.push(...formatConfigPointerLines(violation.config));
+        lines.push(`  do: ${violation.do}`);
+    }
+    lines.push(`importable from:${result.importableFrom.length === 0 ? " (none)" : ""}`);
+    for (const entry of result.importableFrom) {
+        for (const file of entry.surfaceFiles)
+            lines.push(`  ${entry.module} -> ${file}`);
+    }
+    lines.push(`friend access:${result.friendAccess.length === 0 ? " (none)" : ""}`);
+    for (const entry of result.friendAccess) {
+        lines.push(`  ${entry.module} -> ${entry.file}`, `    from: ${entry.from}`, `    because: ${entry.because}`);
+    }
+    lines.push(`allowDeny constraints:${result.allowDenyConstraints.length === 0 ? " (none)" : ""}`);
+    for (const entry of result.allowDenyConstraints) {
+        lines.push(`  source: ${entry.source}`, `  target namespace: ${entry.targetNamespace}`, `  allow: ${entry.allow === undefined ? "(unset)" : JSON.stringify(entry.allow)}`, `  deny: ${entry.deny === undefined ? "(unset)" : JSON.stringify(entry.deny)}`, `  same group exempt: ${entry.sameGroupExempt}`, `  exceptions from path: ${entry.exceptionsFromP.length === 0 ? "(none)" : JSON.stringify(entry.exceptionsFromP)}`, `  edge type: ${entry.edgeType}`, `  import form: ${entry.importForm}`, `  because: ${entry.because}`);
+    }
+    lines.push(`order constraints:${result.orderConstraints.length === 0 ? " (none)" : ""}`);
+    for (const entry of result.orderConstraints) {
+        lines.push(`  tag namespace: ${entry.tagNamespace}`, `  within: ${entry.within ?? "(unscoped)"}`, `  own layer: ${entry.ownLayer}`, `  sequence: ${JSON.stringify(entry.sequence)}`, `  may depend on: ${JSON.stringify(entry.mayDependOn)}`, `  edge type: ${entry.edgeType}`, `  import form: ${entry.importForm}`, `  because: ${entry.because}`);
+    }
+    lines.push(`point constraints:${result.pointConstraints.length === 0 ? " (none)" : ""}`);
+    for (const entry of result.pointConstraints) {
+        lines.push(`  identifier: ${entry.identifier}`, `  forbidden to: ${entry.forbiddenTo}`, `  edge type: ${entry.edgeType}`, `  import form: ${entry.importForm}`, `  because: ${entry.because}`);
+    }
+    return lines.join("\n") + "\n";
+}

package/dist/verbs/search.js

@@ -0,0 +1,109 @@
+// Responsibility: rank public surface exports by name-token overlap with a query.
+// Boundary: reads declared modules; does not search private declarations or change project files.
+import { resolve } from "node:path";
+import ts from "typescript";
+import { buildModuleGraphForRules } from "../module-graph.js";
+import { loadConfig } from "./check.js";
+// Punctuation alone leaves JSONConfig as one token. These transitions separate
+// lowercase from uppercase and an acronym from the next word without splitting its letters.
+// Thus parseJSONConfig becomes ["parse", "json", "config"], not separate acronym letters.
+export function tokenize(text) {
+    return text.replace(/([a-z])([A-Z])/g, "$1 $2")
+        .replace(/([A-Z])([A-Z][a-z])/g, "$1 $2")
+        .split(/[^a-zA-Z0-9]+/).filter(Boolean).map(token => token.toLowerCase());
+}
+function kindOf(symbol) {
+    if (symbol.flags & ts.SymbolFlags.Function)
+        return "function";
+    if (symbol.flags & ts.SymbolFlags.Class)
+        return "class";
+    if (symbol.flags & ts.SymbolFlags.Interface)
+        return "interface";
+    if (symbol.flags & ts.SymbolFlags.TypeAlias)
+        return "type-alias";
+    if (symbol.flags & ts.SymbolFlags.Enum)
+        return "enum";
+    if (symbol.flags & ts.SymbolFlags.Variable)
+        return "variable";
+    if (symbol.flags & ts.SymbolFlags.Module)
+        return "namespace";
+    return "other";
+}
+// Interfaces and type aliases have no value type; they need getDeclaredTypeOfSymbol.
+// Enums also use their declared type here, rather than their runtime value type.
+// Functions, classes, variables, and namespaces backed by source files need
+// getTypeOfSymbolAtLocation to describe the exported value.
+// A namespace Foo {} block has neither supported shape cheaply available here.
+// An empty signature avoids a guess about that block's type.
+function signatureOf(checker, target, kind) {
+    const declaration = target.declarations?.[0];
+    if (declaration === undefined)
+        return "";
+    if (kind === "interface" || kind === "type-alias" || kind === "enum") {
+        return checker.typeToString(checker.getDeclaredTypeOfSymbol(target));
+    }
+    if (kind === "function" || kind === "class" || kind === "variable" ||
+        (kind === "namespace" && ts.isSourceFile(declaration))) {
+        return checker.typeToString(checker.getTypeOfSymbolAtLocation(target, declaration));
+    }
+    return "";
+}
+export async function search(projectRoot, query) {
+    const queryTokens = tokenize(query);
+    if (queryTokens.length === 0)
+        throw new Error("archstrict search: query must contain at least one word");
+    const config = await loadConfig(resolve(projectRoot, "archstrict.config.ts"));
+    // loadConfig already guarantees declaredModules is a well-shaped array
+    // (assertDeclaredModulesShapeValid) - see check.ts's own comment.
+    const options = { projectRoot, declaredModules: config.declaredModules, exclude: config.exclude, surface: config.surface };
+    const graph = buildModuleGraphForRules(options);
+    const checker = graph.checker;
+    const matches = [];
+    for (const module of graph.modules.values()) {
+        for (const surfacePath of module.surfaceFiles) {
+            const sf = graph.program.getSourceFile(surfacePath);
+            if (sf === undefined)
+                continue;
+            const moduleSymbol = checker.getSymbolAtLocation(sf);
+            if (moduleSymbol === undefined)
+                continue;
+            for (const exportSymbol of checker.getExportsOfModule(moduleSymbol)) {
+                const name = exportSymbol.name;
+                const tokens = tokenize(name);
+                const score = queryTokens.filter(queryToken => tokens.some(token => token.includes(queryToken) || queryToken.includes(token))).length / queryTokens.length;
+                if (score === 0)
+                    continue;
+                // Public surfaces commonly re-export names from internal files. getExportsOfModule
+                // returns Alias symbols for those names; their flags would give a generic kind.
+                // Resolve the underlying symbol first so the kind describes the actual export.
+                let target = exportSymbol;
+                if (target.flags & ts.SymbolFlags.Alias)
+                    target = checker.getAliasedSymbol(target);
+                const kind = target.flags & ts.SymbolFlags.Alias ? "other" : kindOf(target);
+                // typeToString can expose an internal declaring path through typeof import("...")
+                // for export * as ns or a const that holds an imported module.
+                // Output must identify the module and its public surface, not that internal file.
+                // enclosingDeclaration was rejected: it makes the path relative but retains the reference.
+                // Apply replacement to every kind: a function's return object can contain the same type.
+                const signature = signatureOf(checker, target, kind)
+                    .replace(/import\("[^"]*"(?:\s*,\s*\{[^)]*\})?\)/g, 'import("<module>")');
+                // The surface path gives an agent a legal import destination. The internal
+                // declaring path would invite the public-surface bypass that rule 1 rejects.
+                matches.push({ module: module.name, surface: graph.relativePath(surfacePath),
+                    name, kind, signature, score });
+            }
+        }
+    }
+    matches.sort((a, b) => b.score - a.score || a.module.localeCompare(b.module) || a.name.localeCompare(b.name));
+    // Search presents the best ranked matches with a visible total count.
+    // A top-K limit serves that query; recommend instead reports its whole candidate set.
+    const shown = matches.slice(0, 20);
+    const notes = graph.programNotes;
+    return { query, total: matches.length, shown: shown.length, matches: shown, ...(notes.length > 0 ? { notes: [...notes] } : {}) };
+}
+export function formatSearchText(result) {
+    return [`${result.total} matches for "${result.query}" (showing ${result.shown})`,
+        ...result.matches.map(match => `${match.module} :: ${match.name} (${match.kind}) - ${match.signature}  [score ${match.score.toFixed(2)}]`),
+        ...(result.notes ?? []).map(note => `note: ${note}`),
+    ].join("\n") + "\n";
+}

package/dist/verbs/simulate.js

@@ -0,0 +1,220 @@
+// Responsibility: compare proposed source and config changes with the current project through the full rule pipeline.
+// Boundary: all changes stay in memory; the baseline and archstrict.todo.json remain inputs from disk.
+import { existsSync, realpathSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import ts from "typescript";
+import { buildModuleGraphForRules, DEFAULT_SURFACE, isEligibleSourceFile, isResolvableFile, prepareGraph } from "../module-graph.js";
+import { fingerprintOf, relativizeForTodo } from "../todo-store.js";
+import { applyTodo, formatText, loadConfig, runRules } from "./check.js";
+import { createConfigLocator } from "../config-pointer.js";
+// A proposed file can belong to a directory that does not exist yet.
+// realpathSync would throw for that file or directory. Resolve only the
+// nearest existing ancestor, then append the missing segments to preserve
+// canonical paths through existing symlinks.
+function canonicalChangePath(projectRoot, path) {
+    const absolute = resolve(projectRoot, path);
+    const missing = [basename(absolute)];
+    let ancestor = dirname(absolute);
+    while (!existsSync(ancestor)) {
+        missing.unshift(basename(ancestor));
+        const parent = dirname(ancestor);
+        if (parent === ancestor)
+            throw new Error(`cannot resolve change path: ${path}`);
+        ancestor = parent;
+    }
+    return join(realpathSync(ancestor), ...missing);
+}
+function overlayHost(options, changes) {
+    const host = ts.createCompilerHost(options);
+    const getSourceFile = host.getSourceFile.bind(host);
+    const readFile = host.readFile.bind(host);
+    const fileExists = host.fileExists.bind(host);
+    const directoryExists = host.directoryExists.bind(host);
+    const getDirectories = host.getDirectories.bind(host);
+    // Module resolution can probe directoryExists and getDirectories before
+    // it reads a file. File overrides alone cannot resolve an import into a
+    // new directory. Include the parents of each added or modified file so
+    // the compiler can reach files that exist only in the overlay.
+    const directories = new Map();
+    for (const [file, content] of changes) {
+        if (content === null)
+            continue;
+        let directory = dirname(file);
+        if (!directories.has(directory))
+            directories.set(directory, new Set());
+        while (dirname(directory) !== directory) {
+            const parent = dirname(directory);
+            if (!directories.has(parent))
+                directories.set(parent, new Set());
+            directories.get(parent).add(basename(directory));
+            directory = parent;
+        }
+    }
+    host.getSourceFile = (file, languageVersion, onError, shouldCreateNewSourceFile) => {
+        const content = changes.get(resolve(file));
+        if (content === null)
+            return undefined;
+        if (content !== undefined)
+            return ts.createSourceFile(file, content, languageVersion);
+        return getSourceFile(file, languageVersion, onError, shouldCreateNewSourceFile);
+    };
+    host.readFile = file => {
+        const content = changes.get(resolve(file));
+        return content === null ? undefined : content ?? readFile(file);
+    };
+    host.fileExists = file => {
+        const content = changes.get(resolve(file));
+        return content === undefined ? fileExists(file) : content !== null;
+    };
+    host.directoryExists = directory => directories.has(resolve(directory)) || directoryExists(directory);
+    host.getDirectories = directory => [...new Set([
+            ...(directoryExists(directory) ? getDirectories(directory) : []),
+            ...(directories.get(resolve(directory)) ?? []),
+        ])];
+    return host;
+}
+function surfaceModuleForPath(graph, path) {
+    for (const module of graph.modules.values()) {
+        if (module.surfaceFiles.includes(path))
+            return module.name;
+    }
+    return undefined;
+}
+function evaluate(graph, config, locator, focusPaths) {
+    if (focusPaths === undefined) {
+        const result = applyTodo(graph, config, runRules(graph, config, { configLocator: locator }), { configLocator: locator });
+        graph.releaseProgram();
+        return result.violations;
+    }
+    const violations = new Map();
+    for (const focus of focusPaths) {
+        const focusedTypeLeakModule = surfaceModuleForPath(graph, focus);
+        const skipTypeLeak = focusedTypeLeakModule === undefined;
+        const result = applyTodo(graph, config, runRules(graph, config, { configLocator: locator, focus, focusedTypeLeakModule, skipTypeLeak }), { configLocator: locator, focus, skipStaleCheckForRules: skipTypeLeak ? ["type-leak"] : [] });
+        graph.releaseProgram();
+        // fingerprintOf needs a project-relative path (see todo-store.ts's own
+        // relativizeForTodo) - a live violation's own `path`/`target` is
+        // always absolute, so every key computed from one must relativize
+        // first, the same as todo.ts's freeze/prune and check.ts's own
+        // matching already do.
+        for (const violation of result.violations) {
+            violations.set(fingerprintOf(relativizeForTodo(violation, graph.relativePath)), violation);
+        }
+    }
+    return [...violations.values()];
+}
+export async function simulate(projectRoot, changes, simulateOptions = {}) {
+    projectRoot = realpathSync(projectRoot);
+    const configPath = canonicalChangePath(projectRoot, "archstrict.config.ts");
+    const beforeConfig = await loadConfig(configPath);
+    let proposedSource;
+    const contents = new Map();
+    for (const change of changes) {
+        if (typeof change?.path !== "string" || change.path.length === 0 ||
+            (change.content !== null && typeof change.content !== "string")) {
+            throw new Error("each change must have a nonempty path and string or null content");
+        }
+        const path = canonicalChangePath(projectRoot, change.path);
+        if (contents.has(path))
+            throw new Error(`duplicate change path: ${change.path}`);
+        if (path === configPath) {
+            if (change.content === null)
+                throw new Error("cannot delete archstrict.config.ts");
+            proposedSource = change.content;
+        }
+        contents.set(path, change.content);
+    }
+    // The baseline must reflect disk, while every after-side rule uses the proposed config.
+    const afterConfig = proposedSource === undefined ? beforeConfig : await loadConfig(configPath, proposedSource);
+    // loadConfig already guarantees declaredModules is a well-shaped array
+    // (assertDeclaredModulesShapeValid) - see check.ts's own comment.
+    const options = { projectRoot, declaredModules: beforeConfig.declaredModules, exclude: beforeConfig.exclude, surface: beforeConfig.surface };
+    const prepared = prepareGraph(options);
+    const baseline = buildModuleGraphForRules(options);
+    const beforeLocator = createConfigLocator(beforeConfig);
+    const mode = simulateOptions.wholeProject ? "whole-project" : "scoped";
+    const focusPaths = simulateOptions.wholeProject ? undefined : [...contents.keys()];
+    const before = evaluate(baseline, beforeConfig, beforeLocator, focusPaths);
+    const added = new Set();
+    const deleted = new Set();
+    for (const [file, content] of contents) {
+        if (content === null)
+            deleted.add(file);
+        else if (!existsSync(file))
+            added.add(file);
+    }
+    const host = overlayHost(prepared.compilerOptions, contents);
+    // A second preparation keeps rootNames, modules, surfaceFiles, and
+    // resolvers consistent through the same computations as a real build.
+    // Manual reconstruction missed new surface files and admitted excluded
+    // files as roots. Adjust the input list and let preparation derive the
+    // metadata again, without changes to the baseline's module objects.
+    const listOverride = (realFiles) => [...new Set([
+            ...realFiles.filter(file => !deleted.has(file)),
+            ...[...added].filter(isResolvableFile),
+        ])];
+    const graphOptions = {
+        projectRoot, declaredModules: afterConfig.declaredModules, exclude: afterConfig.exclude,
+        surface: afterConfig.surface,
+        fileListOverride: (realFiles) => [...new Set([
+                ...realFiles.filter(file => !deleted.has(file)),
+                ...[...added].filter(file => isEligibleSourceFile(file, projectRoot, afterConfig.exclude ?? [], afterConfig.declaredModules, afterConfig.surface ?? DEFAULT_SURFACE)),
+            ])],
+        resolvableFileListOverride: listOverride,
+    };
+    const simulatedPrepared = prepareGraph(graphOptions);
+    const graph = buildModuleGraphForRules(graphOptions, { host, dirtyFiles: new Set(contents.keys()), persistCache: false });
+    // graph.edges above already came from this same `host` (buildPreparedGraph's
+    // own per-file walk reads through it, then drops each SourceFile once
+    // walked - it never keeps one around to inspect). This does not force
+    // `graph.program`: rule 6's own Program holds only the type-reachable
+    // closure from every module's surface (type-closure.ts), a smaller file
+    // list than the simulation's own, so an ordinary change outside that
+    // closure would misread here as a host bug that never happened.
+    // Instead this calls `host.getSourceFile` directly - the same function
+    // a real `ts.createProgram` call uses to load a file's text - for
+    // every change, and compares its own text with the change's own
+    // content: a deleted file must read back as absent there, and every
+    // other change's real SourceFile text must equal what this call asked
+    // to write.
+    const languageVersion = simulatedPrepared.compilerOptions.target ?? ts.ScriptTarget.ESNext;
+    for (const [file, content] of contents) {
+        const source = host.getSourceFile(file, languageVersion);
+        if (content === null ? source !== undefined : (source === undefined || source.text !== content)) {
+            throw new Error(`internal simulation error: overlay mismatch for ${file}`);
+        }
+    }
+    const afterLocator = createConfigLocator(afterConfig, proposedSource);
+    const after = evaluate(graph, afterConfig, afterLocator, focusPaths);
+    // Both graphs share the same (realpath'd) projectRoot, so `baseline`'s
+    // and `graph`'s own relativePath agree on every real file either could
+    // name - either one relativizes either side's violations correctly.
+    // fingerprintOf itself needs a project-relative path (see
+    // todo-store.ts's own relativizeForTodo); a live violation's own
+    // `path`/`target` is always absolute.
+    const keyOf = (v) => fingerprintOf(relativizeForTodo(v, baseline.relativePath));
+    const beforeFingerprints = new Set(before.map(keyOf));
+    const afterFingerprints = new Set(after.map(keyOf));
+    return {
+        mode,
+        added: after.filter(violation => !beforeFingerprints.has(keyOf(violation))),
+        resolved: before.filter(violation => !afterFingerprints.has(keyOf(violation))),
+        unchangedCount: before.filter(violation => afterFingerprints.has(keyOf(violation))).length,
+    };
+}
+export function formatSimulateText(result) {
+    const render = (violations) => {
+        const report = {
+            violations, suggestions: [], modules: 0, modulesWithoutSurface: 0, modulesWithoutSurfaceNames: [], edges: 0, outsideFiles: 0,
+            nonTsSourceFiles: 0,
+            unresolvedSpecifiers: 0, unresolvedSpecifierBreakdown: [], unsupportedSyntax: 0, typeLeaks: 0,
+            todo: 0, edgeRuleCoverage: [],
+        };
+        const text = formatText(report);
+        // Keep the shared violation rendering, but omit counts that describe a full check rather than a change set.
+        return text.slice(0, text.lastIndexOf("\nmodules:") + 1);
+    };
+    return `mode: ${result.mode}\nadded: ${result.added.length}; resolved: ${result.resolved.length}; unchanged: ${result.unchangedCount}\n` +
+        (result.added.length ? `added violations:\n${render(result.added)}` : "") +
+        (result.resolved.length ? `resolved violations:\n${render(result.resolved)}` : "");
+}