archstrict 0.0.0 → 0.2.0

package/dist/verbs/fix.js

@@ -0,0 +1,170 @@
+// Responsibility: plan type re-exports and keep each surface edit only after real rule verification.
+// Boundary: fixes surface files only; preserves frozen violations and leaves internal declarations unchanged.
+import ts from "typescript";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, relative, resolve, sep } from "node:path";
+import { prepareGraph } from "../module-graph.js";
+import { createWarmGraph } from "../warm-graph.js";
+import { fingerprintOf, relativizeForTodo } from "../todo-store.js";
+import { loadConfig, runRules, applyTodo, filterToFile } from "./check.js";
+import { resolveWriteTarget, writeTarget } from "./agents.js";
+import { createConfigLocator } from "../config-pointer.js";
+// A bare interface or type can leak through an inferred return type without its declaring file ever exporting it.
+// Re-exporting that declaration produces TS2459, but the surface's new export name can make the type-leak rule report success.
+// Verification runs architecture rules, not a full semantic-diagnostics pass, so this guard must reject the declaration before any write.
+function exportedFromInternal(graph, leak) {
+    const source = graph.program.getSourceFile(leak.internalFile);
+    const symbol = source === undefined ? undefined : graph.checker.getSymbolAtLocation(source);
+    return symbol !== undefined && graph.checker.getExportsOfModule(symbol).some(entry => entry.name === leak.internalType);
+}
+export async function fix(projectRoot, file, dryRun = false) {
+    const result = { fixed: [], planned: [], unfixable: [], reverted: [] };
+    const focus = file === undefined ? undefined : resolve(projectRoot, file);
+    if (focus !== undefined && !existsSync(focus))
+        return result;
+    const config = await loadConfig(resolve(projectRoot, "archstrict.config.ts"));
+    const configLocator = createConfigLocator(config);
+    // 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 warm = createWarmGraph();
+    let graph = warm.refresh(options);
+    // fingerprintOf needs a project-relative path (see todo-store.ts's own
+    // relativizeForTodo) - a live violation's own `path`/`target` is always
+    // absolute. Reads `graph` fresh on every call (not captured once): the
+    // graph is reassigned after each write below, but `options.projectRoot`
+    // never changes, so relativePath's own output stays consistent across
+    // the reassignment.
+    const keyOf = (v) => fingerprintOf(relativizeForTodo(v, graph.relativePath));
+    const notesSeen = new Set();
+    const evaluate = () => {
+        const evaluated = applyTodo(graph, config, runRules(graph, config, { configLocator }), { configLocator });
+        for (const note of graph.programNotes)
+            notesSeen.add(note);
+        return evaluated;
+    };
+    const baseline = evaluate();
+    const baselineKeys = new Set(baseline.violations.map(keyOf));
+    const scoped = focus === undefined ? baseline : filterToFile(baseline, focus);
+    const files = new Map();
+    for (const violation of scoped.violations) {
+        if (violation.rule !== "type-leak")
+            continue;
+        const group = files.get(violation.path) ?? [];
+        group.push(violation);
+        files.set(violation.path, group);
+    }
+    const prepared = prepareGraph(options);
+    const host = ts.createCompilerHost(prepared.compilerOptions);
+    for (const [path, leaks] of files) {
+        const declarations = new Map();
+        for (const { leak } of leaks) {
+            if (leak === undefined)
+                continue;
+            const sources = declarations.get(leak.internalType) ?? new Set();
+            sources.add(leak.internalFile);
+            declarations.set(leak.internalType, sources);
+        }
+        // Rule 6 checks exported names, so one re-export can make two distinct declarations with the same name appear fixed.
+        // Consumers of the other declaration would receive the wrong type. A partial fix cannot resolve which declaration should own the name.
+        // Leave the whole file unchanged until a human resolves the collision, including the otherwise fixable leaks.
+        const collisions = [...declarations].filter(([, sources]) => sources.size > 1);
+        if (collisions.length > 0) {
+            const reason = collisions.map(([name, sources]) => `name collision for '${name}' in ${[...sources].sort().join(", ")}; rename by hand`).join("; ");
+            for (const violation of leaks)
+                result.unfixable.push({ path, type: violation.leak?.internalType ?? "unknown", reason });
+            continue;
+        }
+        const groups = new Map();
+        const targeted = new Set();
+        for (const violation of leaks) {
+            const leak = violation.leak;
+            if (leak === undefined) {
+                result.unfixable.push({ path, type: "unknown", reason: "structured leak information is unavailable" });
+                continue;
+            }
+            if (!exportedFromInternal(graph, leak)) {
+                result.unfixable.push({ path, type: leak.internalType,
+                    reason: `the internal declaration itself is not exported from its own file '${leak.internalFile}' - add export to its declaration first, or fix by hand` });
+                continue;
+            }
+            const rel = relative(dirname(path), leak.internalFile).split(sep).join("/").replace(/(?:\.d)?\.[cm]?tsx?$/, "");
+            const base = rel.startsWith("../") ? rel : `./${rel}`;
+            // A formatted relative path can still fail under the compiler's extension and module resolution rules.
+            // Require the real resolver to confirm the exact internal file before emitting a specifier that only appears correct.
+            const specifier = [`${base}.js`, base, `${base}.ts`].find(candidate => ts.resolveModuleName(candidate, path, prepared.compilerOptionsForFile(path), host).resolvedModule?.resolvedFileName === leak.internalFile);
+            if (specifier === undefined) {
+                result.unfixable.push({ path, type: leak.internalType, reason: `no candidate specifier resolves to '${leak.internalFile}'` });
+                continue;
+            }
+            const names = groups.get(specifier) ?? new Set();
+            names.add(leak.internalType);
+            groups.set(specifier, names);
+            targeted.add(keyOf(violation));
+        }
+        const lines = [...groups.keys()].sort().map(specifier => `export type { ${[...groups.get(specifier)].sort().join(", ")} } from ${JSON.stringify(specifier)};`);
+        if (lines.length === 0)
+            continue;
+        if (dryRun) {
+            result.planned.push({ path, lines });
+            continue;
+        }
+        // A re-export can remove a type leak while crossing a module boundary that the project's tag rules forbid.
+        // Compare the full violation set with baselineKeys: the regression can appear elsewhere, even when every targeted leak disappears.
+        // Restore the original bytes on failure so a locally successful type fix cannot leave a new architecture violation behind.
+        const target = resolveWriteTarget(path);
+        const original = readFileSync(target);
+        const firstNewline = original.indexOf(10);
+        const newline = firstNewline > 0 && original[firstNewline - 1] === 13 ? "\r\n" : "\n";
+        const separator = original.length > 0 && original[original.length - 1] !== 10 ? newline : "";
+        const updated = Buffer.concat([original, Buffer.from(separator + lines.join(newline) + newline)]);
+        let failure;
+        try {
+            writeTarget(target, updated);
+            graph = warm.refresh(options);
+            const after = evaluate();
+            if (after.violations.some(v => v.rule === "type-leak" && v.path === path && targeted.has(keyOf(v)))) {
+                failure = "verification still reports a targeted type leak";
+            }
+            else if (after.violations.some(v => !baselineKeys.has(keyOf(v)))) {
+                failure = "verification reports a new violation";
+            }
+        }
+        catch (error) {
+            failure = `verification or write failed: ${error instanceof Error ? error.message : String(error)}`;
+        }
+        if (failure !== undefined) {
+            // A failure that blocks the first write can also block the revert at the same path.
+            // Preserve both failures so the report does not imply that restoration succeeded.
+            try {
+                writeTarget(target, original);
+            }
+            catch (error) {
+                failure += `; revert failed: ${error instanceof Error ? error.message : String(error)}`;
+            }
+            graph = warm.refresh(options);
+            result.reverted.push({ path, reason: failure });
+        }
+        else {
+            result.fixed.push({ path, lines });
+        }
+    }
+    if (notesSeen.size > 0)
+        result.notes = [...notesSeen];
+    return result;
+}
+export function formatFixText(result) {
+    const lines = [];
+    for (const category of ["fixed", "planned"]) {
+        for (const entry of result[category])
+            lines.push(`${category}: ${entry.path}`, ...entry.lines);
+    }
+    for (const entry of result.unfixable)
+        lines.push(`unfixable: ${entry.path} (${entry.type}): ${entry.reason}`);
+    for (const entry of result.reverted)
+        lines.push(`reverted: ${entry.path}: ${entry.reason}`);
+    lines.push(`fixed: ${result.fixed.length}; planned: ${result.planned.length}; unfixable: ${result.unfixable.length}; reverted: ${result.reverted.length}`);
+    for (const note of result.notes ?? [])
+        lines.push(`note: ${note}`);
+    return lines.join("\n") + "\n";
+}

package/dist/verbs/hotspots.js

@@ -0,0 +1,261 @@
+// Responsibility: combine Git change history with the current module graph and debt.
+// Boundary: this verb reports evidence; it does not choose or apply a refactor.
+import { execFileSync, spawn } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { createInterface } from "node:readline";
+import { resolve } from "node:path";
+import { compileGlob } from "../classify.js";
+import { buildModuleGraphForRules, moduleForDeclaredFile } from "../module-graph.js";
+import { applyTodo, loadConfig, readCurrentTodo, runRules } from "./check.js";
+function pairKey(a, b) {
+    return a < b ? `${a}\0${b}` : `${b}\0${a}`;
+}
+export function coChangeCount(commits, a, b) {
+    let count = 0;
+    for (const commit of commits) {
+        const modules = new Set(commit);
+        if (modules.has(a) && modules.has(b))
+            count++;
+    }
+    return count;
+}
+export function summarizeCommitHistory(moduleNames, commits) {
+    const commitsByModule = new Map(moduleNames.map((name) => [name, 0]));
+    const linesByModule = new Map(moduleNames.map((name) => [name, 0]));
+    const pairCounts = new Map();
+    for (const commit of commits) {
+        const names = [...commit.modules].sort();
+        for (const name of names) {
+            commitsByModule.set(name, (commitsByModule.get(name) ?? 0) + 1);
+            linesByModule.set(name, (linesByModule.get(name) ?? 0) + (commit.linesByModule.get(name) ?? 0));
+        }
+        for (let i = 0; i < names.length; i++) {
+            for (let j = i + 1; j < names.length; j++) {
+                const key = pairKey(names[i], names[j]);
+                pairCounts.set(key, (pairCounts.get(key) ?? 0) + 1);
+            }
+        }
+    }
+    const pairs = [...pairCounts.entries()].map(([key, coChanges]) => {
+        const [moduleA, moduleB] = key.split("\0");
+        return {
+            moduleA,
+            moduleB,
+            coChanges,
+            shareOfA: coChanges / commitsByModule.get(moduleA),
+            shareOfB: coChanges / commitsByModule.get(moduleB),
+        };
+    });
+    return { commitsByModule, linesByModule, pairs };
+}
+function countRules(rules) {
+    const counts = {};
+    for (const rule of rules)
+        counts[rule] = (counts[rule] ?? 0) + 1;
+    return Object.fromEntries(Object.entries(counts).sort(([a], [b]) => a.localeCompare(b)));
+}
+function graphBoundaries(graph) {
+    const boundaries = new Set();
+    for (const edge of graph.crossModuleEdges) {
+        if (edge.toModule !== undefined)
+            boundaries.add(pairKey(edge.fromModule, edge.toModule));
+    }
+    return boundaries;
+}
+function fanByModule(graph) {
+    const incoming = new Map();
+    const outgoing = new Map();
+    for (const name of graph.modules.keys()) {
+        incoming.set(name, new Set());
+        outgoing.set(name, new Set());
+    }
+    for (const edge of graph.crossModuleEdges) {
+        if (edge.toModule === undefined)
+            continue;
+        outgoing.get(edge.fromModule)?.add(edge.toModule);
+        incoming.get(edge.toModule)?.add(edge.fromModule);
+    }
+    return {
+        fanIn: new Map([...incoming].map(([name, modules]) => [name, modules.size])),
+        fanOut: new Map([...outgoing].map(([name, modules]) => [name, modules.size])),
+    };
+}
+function gitValue(root, args) {
+    try {
+        return execFileSync("git", args, { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+function isAnalyzedSource(path) {
+    return /\.(?:ts|tsx|mts|cts)$/.test(path) && !/\.d\.(?:ts|mts|cts)$/.test(path);
+}
+async function readGitHistory(projectRoot, since, moduleForPath) {
+    if (gitValue(projectRoot, ["rev-parse", "--is-inside-work-tree"]) !== "true") {
+        return { available: false, shallow: false, commits: [], note: "Git history is unavailable because this project is not in a Git repository." };
+    }
+    const shallow = gitValue(projectRoot, ["rev-parse", "--is-shallow-repository"]) === "true";
+    const prefix = gitValue(projectRoot, ["rev-parse", "--show-prefix"]) ?? "";
+    const args = ["log", "--numstat", "--no-renames", "--format=%x1e%H"];
+    if (since !== undefined) {
+        const isRef = gitValue(projectRoot, ["rev-parse", "--verify", "--quiet", `${since}^{commit}`]) !== undefined;
+        args.push(isRef ? `${since}..HEAD` : `--since=${since}`);
+    }
+    args.push("--", ".");
+    const child = spawn("git", args, { cwd: projectRoot, stdio: ["ignore", "pipe", "pipe"] });
+    const stderr = [];
+    child.stderr.on("data", (chunk) => stderr.push(chunk));
+    const commits = [];
+    let current;
+    const lines = createInterface({ input: child.stdout, crlfDelay: Infinity });
+    for await (const line of lines) {
+        if (line.startsWith("\u001e")) {
+            if (current !== undefined && current.modules.size > 0)
+                commits.push(current);
+            current = { modules: new Set(), linesByModule: new Map() };
+            continue;
+        }
+        if (current === undefined || line.length === 0)
+            continue;
+        const firstTab = line.indexOf("\t");
+        const secondTab = line.indexOf("\t", firstTab + 1);
+        if (firstTab === -1 || secondTab === -1)
+            continue;
+        let path = line.slice(secondTab + 1);
+        if (prefix !== "") {
+            if (!path.startsWith(prefix))
+                continue;
+            path = path.slice(prefix.length);
+        }
+        const moduleName = moduleForPath(path);
+        if (moduleName === undefined)
+            continue;
+        const added = Number(line.slice(0, firstTab));
+        const deleted = Number(line.slice(firstTab + 1, secondTab));
+        const changed = Number.isFinite(added) && Number.isFinite(deleted) ? added + deleted : 0;
+        current.modules.add(moduleName);
+        current.linesByModule.set(moduleName, (current.linesByModule.get(moduleName) ?? 0) + changed);
+    }
+    if (current !== undefined && current.modules.size > 0)
+        commits.push(current);
+    const exitCode = await new Promise((accept) => child.once("close", accept));
+    if (exitCode !== 0)
+        throw new Error(Buffer.concat(stderr).toString("utf8").trim() || "git log failed");
+    const note = shallow
+        ? "Git history is limited because this is a shallow clone."
+        : commits.length < 2
+            ? "Git history has fewer than two relevant commits, so change coupling is limited."
+            : null;
+    return { available: true, shallow, commits, note };
+}
+export async function hotspots(projectRoot, since) {
+    const configPath = resolve(projectRoot, "archstrict.config.ts");
+    const config = await loadConfig(configPath, undefined, "archstrict hotspots");
+    config.configPath = realpathSync(configPath);
+    const graph = buildModuleGraphForRules({
+        projectRoot,
+        declaredModules: config.declaredModules,
+        exclude: config.exclude,
+        surface: config.surface,
+    });
+    const evaluated = runRules(graph, config, { afterTypeLeak: () => graph.releaseProgram() });
+    const active = applyTodo(graph, config, evaluated);
+    const activeByModule = new Map();
+    for (const violation of active.violations) {
+        if (!("todoModule" in violation) || typeof violation.todoModule !== "string")
+            continue;
+        const rules = activeByModule.get(violation.todoModule) ?? [];
+        rules.push(violation.rule);
+        activeByModule.set(violation.todoModule, rules);
+    }
+    const excluded = (config.exclude ?? []).map(compileGlob);
+    const moduleCache = new Map();
+    const moduleForPath = (path) => {
+        if (moduleCache.has(path))
+            return moduleCache.get(path);
+        let name;
+        if (isAnalyzedSource(path)
+            && path !== "archstrict.types.ts"
+            && !path.endsWith("archstrict.todo.json")
+            && !excluded.some((glob) => glob.test(path))) {
+            name = moduleForDeclaredFile(resolve(projectRoot, path), projectRoot, config.declaredModules);
+        }
+        moduleCache.set(path, name);
+        return name;
+    };
+    const history = await readGitHistory(projectRoot, since, moduleForPath);
+    const summary = summarizeCommitHistory([...graph.modules.keys()], history.commits);
+    const fan = fanByModule(graph);
+    const boundaries = graphBoundaries(graph);
+    const currentTodo = readCurrentTodo(graph);
+    const modules = [...graph.modules.values()].map((module) => {
+        const commits = summary.commitsByModule.get(module.name) ?? 0;
+        const fanIn = fan.fanIn.get(module.name) ?? 0;
+        return {
+            name: module.name,
+            commits,
+            changedLines: summary.linesByModule.get(module.name) ?? 0,
+            fanIn,
+            fanOut: fan.fanOut.get(module.name) ?? 0,
+            frozenDebtByRule: countRules((currentTodo.entriesByModule.get(module.name) ?? []).map((entry) => entry.rule)),
+            activeViolationsByRule: countRules(activeByModule.get(module.name) ?? []),
+            score: commits * fanIn,
+            // `--module` scopes the whole rule set to one module; a single file
+            // inside it (the earlier form) is not a module-level drill-down and
+            // can miss the violations that made the module a hotspot. `--frozen`
+            // surfaces that module's todo-matched debt alongside its live
+            // violations, instead of sending the reader to its todo JSON by hand.
+            do: `archstrict check --frozen --module ${module.name}`,
+        };
+    }).sort((a, b) => b.score - a.score || b.commits - a.commits || a.name.localeCompare(b.name));
+    const pairs = summary.pairs.map((pair) => {
+        const boundary = boundaries.has(pairKey(pair.moduleA, pair.moduleB));
+        return { ...pair, boundary, hotspot: boundary && (pair.shareOfA >= 0.5 || pair.shareOfB >= 0.5) };
+    }).sort((a, b) => b.coChanges - a.coChanges || a.moduleA.localeCompare(b.moduleA) || a.moduleB.localeCompare(b.moduleB));
+    return {
+        history: { available: history.available, shallow: history.shallow, commits: history.commits.length, since: since ?? null, note: history.note },
+        units: { commits: "commits", changedLines: "added plus deleted lines", shares: "fraction of module commits" },
+        exclusions: ["paths outside analysis", "archstrict todo files", "archstrict.types.ts"],
+        modules,
+        pairs,
+    };
+}
+function percentage(share) {
+    return `${Math.round(share * 100)}%`;
+}
+function ruleCountsText(counts) {
+    const entries = Object.entries(counts);
+    return entries.length === 0 ? "none" : entries.map(([rule, count]) => `${rule}=${count}`).join(", ");
+}
+export function formatHotspotsText(result) {
+    const lines = [
+        "Hotspot modules (top 10)",
+        "Read this as: score combines change frequency with the number of modules that depend on a module.",
+    ];
+    if (result.history.note !== null)
+        lines.push(`History: ${result.history.note}`);
+    for (const module of result.modules.slice(0, 10)) {
+        lines.push(`  ${module.name}: score ${module.score}; ${module.commits} commits; ${module.changedLines} changed lines; fan-in ${module.fanIn}; fan-out ${module.fanOut}`);
+        lines.push(`    frozen debt: ${ruleCountsText(module.frozenDebtByRule)}; active: ${ruleCountsText(module.activeViolationsByRule)}`);
+    }
+    lines.push("", "Co-change pairs (top 10)");
+    lines.push("Read this as: a boundary hotspot changes together in at least half of either module's commits and has a current dependency edge.");
+    for (const pair of result.pairs.slice(0, 10)) {
+        const marker = pair.hotspot ? "boundary hotspot" : pair.boundary ? "boundary" : "no boundary edge";
+        lines.push(`  ${pair.moduleA} <-> ${pair.moduleB}: ${pair.coChanges} commits; ${percentage(pair.shareOfA)} of ${pair.moduleA}; ${percentage(pair.shareOfB)} of ${pair.moduleB}; ${marker}`);
+    }
+    lines.push("", `Excluded from history: ${result.exclusions.join(", ")}.`);
+    // At most two lines: the top module (the score's own drill-down), and, when
+    // one exists, the top boundary-hotspot pair. `check --frozen` now reads a
+    // pair's frozen debt through the same rule/module filters as a live
+    // violation, so the drill-down names that command instead of the todo
+    // JSON files it used to send the reader to open by hand.
+    if (result.modules.length > 0)
+        lines.push(`do: ${result.modules[0].do}`);
+    const pair = result.pairs.find((candidate) => candidate.hotspot);
+    if (pair !== undefined) {
+        lines.push(`do: read node_modules/archstrict/skills/archstrict/references/rearchitect.md, then run archstrict check --frozen --module ${pair.moduleA} and archstrict check --frozen --module ${pair.moduleB}`);
+    }
+    return `${lines.join("\n")}\n`;
+}