archstrict 0.1.0 → 0.2.0

package/dist/module-candidates.js

@@ -12,7 +12,7 @@
 // caller (init's own walk, or a config-vs-graph consistency check) already
 // decided that and hands this module the resulting file list, anchor set,
 // and the config's own declaredModules (for the `taken`-name check).
-import { moduleGlobBaseDir } from "./module-graph.js";
+import { moduleGlobBaseDir, moduleGlobList } from "./module-graph.js";
 const byteSort = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
 // Groups analyzed files by their nearest anchor: for a file `f`, the
 // longest anchor that contains it. A file sitting directly in its anchor is
@@ -89,15 +89,22 @@ export function declaredModuleEntryText(entry) {
 // as `taken` names. Anchors are the project root plus the parent directory
 // of each existing entry's own glob base - the same depth a fresh init
 // itself would have grouped that entry at, computed by string ops alone
-// (moduleGlobBaseDir already strips the glob down to its literal prefix;
-// only its own parent directory is needed here, not whether that prefix
-// names a real file or directory on disk).
+// (moduleGlobBaseDir strips the glob down to its literal prefix; only
+// that prefix's parent directory is the anchor, and a file list
+// contributes one anchor per path).
 export function suggestUncovered(uncoveredRelFiles, declaredModules) {
     const anchors = new Set([""]);
     for (const dm of declaredModules) {
-        const base = moduleGlobBaseDir(dm.glob);
-        const slash = base.lastIndexOf("/");
-        anchors.add(slash === -1 ? "" : base.slice(0, slash));
+        // The parent of each glob's literal base, the same depth a fresh init
+        // groups at. A directory glob `src/app/**` anchors at `src`, so a
+        // sibling directory is its own group. A file glob `src/sqlite.ts`
+        // anchors at `src`, so the file itself is a file group. A file list
+        // anchors at the shared directory, once per path.
+        for (const glob of moduleGlobList(dm.glob)) {
+            const base = moduleGlobBaseDir(glob);
+            const slash = base.lastIndexOf("/");
+            anchors.add(slash === -1 ? "" : base.slice(0, slash));
+        }
     }
     const taken = new Set(declaredModules.map((dm) => dm.name));
     return nameCandidates(groupAnalyzedFiles(uncoveredRelFiles, [...anchors]), taken);

package/dist/module-graph.js

@@ -54,9 +54,11 @@ import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "n
 import { dirname, join, relative, sep } from "node:path";
 import { builtinModules } from "node:module";
 import { compileGlob, mostSpecificMatch } from "./classify.js";
+import { ReportError } from "./report-error.js";
 import { buildTypeClosure, computeSyntacticNamedDeclarations } from "./type-closure.js";
-import { checkTypeLeaks } from "./rules/type-leak.js";
+import { checkTypeLeaks } from "./type-leak.js";
 import { makeProjectRelativePosix } from "./project-path.js";
+import { forcedBasesOf, gitignoreStackAbove, isPathGitignored, nextIgnoreState, withGitignoreFile } from "./gitignore.js";
 // A node builtin (`fs`, `node:fs`, ...) never has a real resolvedModule:
 // ts.resolveModuleName looks for an actual file, but @types/node's ambient
 // `declare module "node:fs"` is resolved by the checker's own ambient-module
@@ -122,6 +124,58 @@ export function moduleGlobBaseDir(glob) {
     const prefix = firstWildcard === -1 ? glob : glob.slice(0, firstWildcard);
     return prefix.replace(/\/+$/, "");
 }
+export function moduleGlobList(glob) {
+    return typeof glob === "string" ? [glob] : glob;
+}
+// The directory a surface or friend path resolves against. A directory
+// glob's own base (`src/build/**` -> `src/build`). A file glob's parent
+// (`src/build/plan.ts` -> `src/build`), so several files in one flat
+// directory share it. Syntactic: it does not look at the disk, because a
+// file the change set has not written yet still belongs to that directory.
+export function globResolutionDir(glob) {
+    const base = moduleGlobBaseDir(glob);
+    if (glob.includes("*"))
+        return base;
+    const slash = base.lastIndexOf("/");
+    return slash === -1 ? "" : base.slice(0, slash);
+}
+// The shared resolution directory, or undefined when the list is empty or
+// the globs name more than one directory. One directory per entry is the
+// rule: a module that spans directories is several entries.
+export function sharedGlobResolutionDir(glob) {
+    const globs = moduleGlobList(glob);
+    if (globs.length === 0)
+        return undefined;
+    const dir = globResolutionDir(globs[0]);
+    for (const entry of globs) {
+        if (globResolutionDir(entry) !== dir)
+            return undefined;
+    }
+    return dir;
+}
+export function declaredModuleMembership(declaredModules) {
+    return declaredModules.flatMap((dm) => moduleGlobList(dm.glob).map((glob) => ({ glob, value: dm.name })));
+}
+function joinPosix(dir, relativePath) {
+    const joined = dir === "" ? relativePath : `${dir}/${relativePath}`;
+    return joined.replace(/\/{2,}/g, "/").replace(/^\//, "");
+}
+// A single glob keeps today's file-or-directory root. Several globs must
+// share one resolution directory; the caller uses that directory for
+// surface and friends, and each glob's own base as a type-leak root.
+function moduleGlobShape(dm) {
+    const globs = moduleGlobList(dm.glob);
+    if (globs.length === 0) {
+        throw new ReportError(`declared module '${dm.name}' has an empty glob list`, `give '${dm.name}' a glob string or a non-empty array of paths in one directory, in archstrict.config.ts, then run archstrict check`);
+    }
+    if (globs.length === 1)
+        return { kind: "single", glob: globs[0] };
+    const dir = sharedGlobResolutionDir(dm.glob);
+    if (dir === undefined) {
+        throw new ReportError(`declared module '${dm.name}' lists globs that do not share one directory`, `list only files in one directory, or use one declaredModules entry per directory, in archstrict.config.ts, then run archstrict check`);
+    }
+    return { kind: "many", dir, globs };
+}
 function pathIsFile(path) {
     try {
         return statSync(path).isFile();
@@ -206,10 +260,20 @@ export function surfaceGlobsFor(dm, projectRoot, globalDefaultSurface,
 // See moduleRelativeDir's own comment - simulate's overlay build passes
 // one here so a change set's own new file classifies correctly.
 fileExists = pathIsFile) {
-    const moduleDir = join(projectRoot, moduleGlobBaseDir(dm.glob));
+    const shape = moduleGlobShape(dm);
+    // A file list does not derive a surface from a package.json sitting in
+    // the shared directory. That derivation belongs to a directory module,
+    // whose glob is one directory. A seam lists its surface by hand, or
+    // takes the project default (index.ts in that directory).
+    if (shape.kind === "many") {
+        const surface = dm.surface ?? globalDefaultSurface;
+        const entries = Array.isArray(surface) ? surface : [surface];
+        return entries.map((s) => joinPosix(shape.dir, s));
+    }
+    const moduleDir = join(projectRoot, moduleGlobBaseDir(shape.glob));
     const surface = effectiveSurface(dm, moduleDir, globalDefaultSurface);
     const entries = Array.isArray(surface) ? surface : [surface];
-    return entries.map((s) => moduleRelativeGlob(projectRoot, dm.glob, s, fileExists));
+    return entries.map((s) => moduleRelativeGlob(projectRoot, shape.glob, s, fileExists));
 }
 function surfaceGlobsAllowingDts(declaredModules, projectRoot, globalDefaultSurface) {
     return declaredModules
@@ -502,7 +566,18 @@ function readDirEntries(dir) {
 // calls this replaces took about 41 ms; this one recursive descent takes
 // about 23 ms - roughly 1.8x faster, from walking every directory once
 // instead of four times.
-function walkProjectTree(projectRoot, excludeGlobs, dtsSurfaceGlobs, analysisOnly = false, relativePath = makeProjectRelativePosix(projectRoot)) {
+//
+// A gitignored path is not project source (scratch corpora, build output,
+// local caches), so it leaves the analyzed list and the non-TS count, the
+// same two outputs config.exclude governs. It stays in the resolvable set
+// and the package.json list: a checked-in file can import gitignored
+// codegen output, and the resolution fingerprint must still see it appear
+// or vanish. Under `analysisOnly` nothing else is collected, so an ignored
+// directory is not entered at all - unless a declared module's base lies
+// inside it, since a declared module is the explicit request to analyze
+// an ignored path (see gitignore.ts's nextIgnoreState).
+function walkProjectTree(projectRoot, excludeGlobs, dtsSurfaceGlobs, analysisOnly = false, relativePath = makeProjectRelativePosix(projectRoot), declaredBases = []) {
+    const forced = forcedBasesOf(declaredBases);
     const analyzedFiles = [];
     let nonTsSourceFileCount = 0;
     const resolvableFiles = [];
@@ -510,8 +585,17 @@ function walkProjectTree(projectRoot, excludeGlobs, dtsSurfaceGlobs, analysisOnl
     const nodeModulesDirs = [];
     const distDirs = [];
     const visited = new Set();
-    function visit(dir) {
+    function visit(dir, dirState, inherited) {
         const { files, dirs } = readDirEntries(dir);
+        let stack = inherited;
+        if (dirState === "kept" && files.some((entry) => entry.name === ".gitignore")) {
+            try {
+                stack = withGitignoreFile(stack, relativePath(dir), readFileSync(join(dir, ".gitignore"), "utf8"));
+            }
+            catch {
+                // An unreadable .gitignore ignores nothing, like any unreadable file here.
+            }
+        }
         for (const entry of files) {
             const full = join(dir, entry.name);
             if (entry.name === "package.json" && !analysisOnly)
@@ -519,6 +603,8 @@ function walkProjectTree(projectRoot, excludeGlobs, dtsSurfaceGlobs, analysisOnl
             if (!analysisOnly && isResolvableFile(entry.name))
                 resolvableFiles.push(full);
             const rel = relativePath(full);
+            if (nextIgnoreState(dirState, stack, rel, false, forced.bases) === "ignored")
+                continue;
             if (excludeGlobs.some((glob) => compileGlob(glob).test(rel)))
                 continue;
             if (NON_TS_SOURCE_EXTENSIONS.some((ext) => entry.name.endsWith(ext))) {
@@ -544,16 +630,22 @@ function walkProjectTree(projectRoot, excludeGlobs, dtsSurfaceGlobs, analysisOnl
                     distDirs.push(full);
                 continue; // never entered by this pass, unconditionally
             }
+            const rel = relativePath(full);
+            const state = nextIgnoreState(dirState, stack, rel, true, forced.bases);
+            if (state === "ignored" && analysisOnly && !forced.ancestors.has(rel))
+                continue;
             if (visited.has(real))
                 continue;
             visited.add(real);
-            visit(full);
+            visit(full, state, stack);
         }
     }
     const rootReal = realDirOf(projectRoot);
     if (rootReal !== undefined)
         visited.add(rootReal);
-    visit(projectRoot);
+    // The project root itself is never tested against a pattern: a root the
+    // caller pointed at is analyzed even when it sits inside an ignored path.
+    visit(projectRoot, "kept", gitignoreStackAbove(projectRoot));
     // The second pass: every dist/ directory the first pass met, walked
     // separately for the resolvable set, the package.json list, and the
     // node_modules directory list only - never the analyzed list or the
@@ -591,6 +683,12 @@ function walkProjectTree(projectRoot, excludeGlobs, dtsSurfaceGlobs, analysisOnl
     }
     return { analyzedFiles, nonTsSourceFileCount, resolvableFiles, packageJsonFiles, nodeModulesDirs };
 }
+// Each declared module's literal base (see moduleGlobBaseDir): the walk
+// keeps a gitignored path at or under one, since declaring a module there
+// is the project's explicit request to analyze it.
+function declaredBasesOf(declaredModules) {
+    return declaredModules.flatMap((dm) => moduleGlobList(dm.glob).map(moduleGlobBaseDir));
+}
 export function listAnalyzedFiles(projectRoot, excludeGlobs, declaredModules = [], globalDefaultSurface = DEFAULT_SURFACE) {
     // Computed once for the whole scan, not once per .d.ts candidate file:
     // surfaceGlobsAllowingDts itself derives every module's own surface from
@@ -613,7 +711,7 @@ export function listAnalyzedFiles(projectRoot, excludeGlobs, declaredModules = [
     // tree, plus the resolvable/package.json/node_modules collection) on
     // any project that has one.
     const dtsSurfaceGlobs = surfaceGlobsAllowingDts(declaredModules, projectRoot, globalDefaultSurface);
-    return walkProjectTree(projectRoot, excludeGlobs, dtsSurfaceGlobs, true).analyzedFiles;
+    return walkProjectTree(projectRoot, excludeGlobs, dtsSurfaceGlobs, true, undefined, declaredBasesOf(declaredModules)).analyzedFiles;
 }
 // A proposed new path has never passed through walkProjectTree.
 // Export the eligibility predicate so callers can ask whether that path
@@ -621,7 +719,7 @@ export function listAnalyzedFiles(projectRoot, excludeGlobs, declaredModules = [
 // rules separate from directory traversal lets both paths agree before
 // the proposed file exists on disk.
 export function isEligibleSourceFile(file, projectRoot, excludeGlobs, declaredModules, globalDefaultSurface) {
-    return isEligibleSourceFileWithDtsGlobs(file, projectRoot, excludeGlobs, surfaceGlobsAllowingDts(declaredModules, projectRoot, globalDefaultSurface));
+    return isEligibleSourceFileWithDtsGlobs(file, projectRoot, excludeGlobs, surfaceGlobsAllowingDts(declaredModules, projectRoot, globalDefaultSurface)) && !isPathGitignored(projectRoot, toProjectRelativePosix(file, projectRoot), forcedBasesOf(declaredBasesOf(declaredModules)).bases);
 }
 // Shared core: takes the already-derived .d.ts-allowing surface globs
 // rather than declaredModules directly, so a caller scanning many files at
@@ -646,20 +744,29 @@ function buildDeclaredModules(projectRoot, declaredModules, allFiles, globalDefa
     // for a proposed file the same way it already is for one that exists.
     const allFilesSet = new Set(allFiles);
     const existsForClassification = (path) => allFilesSet.has(path) || pathIsFile(path);
-    const membership = declaredModules.map((dm) => ({ glob: dm.glob, value: dm.name }));
+    const membership = declaredModuleMembership(declaredModules);
     const modules = new Map(declaredModules.map((dm) => {
-        const dir = join(projectRoot, moduleGlobBaseDir(dm.glob));
+        const shape = moduleGlobShape(dm);
+        const dir = join(projectRoot, shape.kind === "single" ? moduleGlobBaseDir(shape.glob) : shape.dir);
+        const boundaryRoots = shape.kind === "single"
+            ? [dir]
+            : shape.globs.map((glob) => join(projectRoot, moduleGlobBaseDir(glob)));
         return [
             dm.name,
             {
                 name: dm.name,
                 dir,
-                rootIsFile: existsForClassification(dir),
+                rootIsFile: shape.kind === "single" && existsForClassification(dir),
+                boundaryRoots,
                 files: [],
                 surfaceFiles: [],
-                surfaceName: effectiveSurface(dm, dir, globalDefaultSurface),
+                surfaceName: shape.kind === "single"
+                    ? effectiveSurface(dm, dir, globalDefaultSurface)
+                    : (dm.surface ?? globalDefaultSurface),
                 friends: (dm.friends ?? []).map((f) => ({
-                    fileGlob: moduleRelativeGlob(projectRoot, dm.glob, f.file, existsForClassification),
+                    fileGlob: shape.kind === "single"
+                        ? moduleRelativeGlob(projectRoot, shape.glob, f.file, existsForClassification)
+                        : joinPosix(shape.dir, f.file),
                     from: f.from,
                     because: f.because,
                 })),
@@ -693,7 +800,7 @@ function buildDeclaredModules(projectRoot, declaredModules, allFiles, globalDefa
 }
 export function moduleForDeclaredFile(filePath, projectRoot, declaredModules) {
     const rel = toProjectRelativePosix(filePath, projectRoot);
-    return mostSpecificMatch(rel, declaredModules.map((dm) => ({ glob: dm.glob, value: dm.name })), (a, b) => a === b);
+    return mostSpecificMatch(rel, declaredModuleMembership(declaredModules), (a, b) => a === b);
 }
 // parseJsonConfigFileContent's real job (`include`/`exclude` -> a file
 // list) is work this function throws away: it returns only `.options`.
@@ -823,7 +930,7 @@ export function prepareGraph(options) {
     // at no extra walk cost to a caller (simulate, fix, search) that never
     // touches them.
     const dtsSurfaceGlobs = surfaceGlobsAllowingDts(declaredModules, projectRoot, surface);
-    const tree = walkProjectTree(projectRoot, exclude, dtsSurfaceGlobs, false, relativePath);
+    const tree = walkProjectTree(projectRoot, exclude, dtsSurfaceGlobs, false, relativePath, declaredBasesOf(declaredModules));
     let rootNames = tree.analyzedFiles;
     if (options.fileListOverride)
         rootNames = options.fileListOverride(rootNames);
@@ -839,7 +946,7 @@ export function prepareGraph(options) {
     // answer. Safe for the lifetime of one prepareGraph call: projectRoot
     // and declaredModules are both fixed for that call.
     const moduleForFileCache = new Map();
-    const membership = declaredModules.map((dm) => ({ glob: dm.glob, value: dm.name }));
+    const membership = declaredModuleMembership(declaredModules);
     const resolveModuleForFile = (filePath) => {
         if (moduleForFileCache.has(filePath))
             return moduleForFileCache.get(filePath);
@@ -1632,7 +1739,7 @@ const CODE_VERSION_HASH = (() => {
 const TYPESCRIPT_VERSION = ts.version;
 function cacheMetadata(projectRoot, options) {
     const packages = [join(projectRoot, "package.json"), ...options.declaredModules
-            .map((dm) => join(projectRoot, moduleGlobBaseDir(dm.glob), "package.json"))];
+            .flatMap((dm) => moduleGlobList(dm.glob).map((glob) => join(projectRoot, moduleGlobBaseDir(glob), "package.json")))];
     const lock = ["package-lock.json", "pnpm-lock.yaml", "yarn.lock", "bun.lock"]
         .map((name) => join(projectRoot, name)).find((path) => existsSync(path));
     if (lock !== undefined)

package/dist/rules/constraints.js

@@ -172,7 +172,9 @@ export function computeAllowDeny(graph, config, focus) {
             const targetValues = [...targetTags].filter((t) => t.startsWith(namespacePrefix));
             if (targetValues.length === 0)
                 return; // no tag in this namespace: not this rule's concern
-            evaluatedCounts[i]++; // this rule genuinely had a real edge to judge, whatever the verdict below
+            // Not `!++`: Babel 8 rejects an UpdateExpression whose argument is a
+            // non-null assertion, and the instrumenter builds exactly that.
+            evaluatedCounts[i] = evaluatedCounts[i] + 1; // this rule genuinely had a real edge to judge, whatever the verdict below
             let violatingTag;
             if (rule.allow !== undefined) {
                 const allowed = new Set(rule.allow.map((v) => `${namespacePrefix}${v}`));
@@ -308,7 +310,7 @@ function computeOrder(graph, config, focus) {
                 return; // this within-value has no declared sequence at all: out of scope, not an error
             assertSequenceListsValue(rule, withinValue, sequence, sourceLayer);
             assertSequenceListsValue(rule, withinValue, sequence, targetLayer);
-            evaluatedCounts[i]++; // this rule genuinely had a real edge, within a real declared sequence, to judge
+            evaluatedCounts[i] = evaluatedCounts[i] + 1; // this rule genuinely had a real edge, within a real declared sequence, to judge
             const sourceIndex = sequence.indexOf(sourceLayer.slice(namespacePrefix.length));
             const targetIndex = sequence.indexOf(targetLayer.slice(namespacePrefix.length));
             // "downward-only": a source may depend on its own layer or one
@@ -372,7 +374,7 @@ function computePoint(graph, config, focus) {
                 return;
             if (!matchesPredicate(rule.from, sourceRel, sourceTags))
                 return;
-            evaluatedCounts[i]++;
+            evaluatedCounts[i] = evaluatedCounts[i] + 1;
             if (!matchesPredicate(rule.to, targetRel, targetTags))
                 return;
             if (focus !== undefined && edge.fromFile !== focus)

package/dist/rules/cycles.js

@@ -67,6 +67,27 @@ function lopsidedDo(pair, relativePath) {
     const fileEdges = [...new Set(pair.minorityEdges.map((e) => `${relativePath(e.fromFile)} -> ${relativePath(e.resolvedFile)}`))].sort().slice(0, MINORITY_FILE_EDGES_SHOWN).join(", ");
     return `remove the ${pair.minorityEdges.length} import(s) from ${pair.minorityFrom} to ${pair.minorityTo} (${pair.minorityTo} imports ${pair.minorityFrom} ${pair.majorityCount} times, so ${pair.minorityFrom} -> ${pair.minorityTo} is likely the unintended direction): ${fileEdges}`;
 }
+// Edges named per side are capped: a side with dozens of imports is named
+// by its count and first few edges, which is enough to find it.
+const SIDE_FILE_EDGES_SHOWN = 3;
+function sideEdges(edges, relativePath) {
+    const unique = [...new Set(edges.map((e) => `${relativePath(e.fromFile)} -> ${relativePath(e.resolvedFile)}`))].sort();
+    const more = unique.length > SIDE_FILE_EDGES_SHOWN ? ` (and ${unique.length - SIDE_FILE_EDGES_SHOWN} more)` : "";
+    return unique.slice(0, SIDE_FILE_EDGES_SHOWN).join(", ") + more;
+}
+// The two moves a rearchitecting pass uses on a two-module cycle: extract
+// a shared contract, or invert the dependency. Checking the plan with
+// simulate first is named here because a move that only relocates the
+// cycle is common, and simulate shows it without touching the tree.
+function twoModuleDo(a, b, edgesByPair, relativePath) {
+    const aToB = edgesByPair.get(`${a}->${b}`) ?? [];
+    const bToA = edgesByPair.get(`${b}->${a}`) ?? [];
+    return `${a} imports ${b} ${aToB.length} time(s): ${sideEdges(aToB, relativePath)}; ` +
+        `${b} imports ${a} ${bToA.length} time(s): ${sideEdges(bToA, relativePath)}; ` +
+        `either extract the part both sides use into a leaf module that ${a} and ${b} both import, ` +
+        `or pass the dependency in from the side that owns it, so the other side stops importing it; ` +
+        `run archstrict simulate on the planned change first`;
+}
 // Smaller (fromFile, line, column) wins, by plain code-unit path compare -
 // a total order independent of which edge the walk happened to visit
 // first, so the SAME representative edge is picked for a given (from, to)
@@ -208,9 +229,16 @@ export function checkCycles(graph, config) {
         // cheap fix, so they lead the do:; the general break-the-cycle advice
         // stays as the fallback for when that guess is wrong.
         const lopsided = findMostLopsidedPair(component, valueEdgesByPair);
+        // A two-module cycle has one known pair of sides, so its do: can name
+        // the edges on each side and the two restructuring moves that remove a
+        // direction for good. A longer cycle keeps the general advice: which
+        // pair to restructure is a judgment the shortest cycle alone cannot make.
+        const generalDo = component.length === 2
+            ? twoModuleDo(sorted[0], sorted[1], valueEdgesByPair, graph.relativePath)
+            : breakCycleDo;
         const doText = lopsided === undefined
-            ? breakCycleDo
-            : `${lopsidedDo(lopsided, graph.relativePath)}; alternatively, ${breakCycleDo}`;
+            ? generalDo
+            : `${lopsidedDo(lopsided, graph.relativePath)}; alternatively, ${generalDo}`;
         violations.push({
             rule: "cycle",
             path: firstEdge.fromFile,

package/dist/todo-store.js

@@ -13,7 +13,7 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { isAbsolute, join } from "node:path";
 import ts from "typescript";
-import { REFERENCED_BY_MARKER } from "./rules/type-leak.js";
+import { REFERENCED_BY_MARKER } from "./type-leak.js";
 import { ReportError } from "./report-error.js";
 import { toProjectRelativePosix } from "./module-graph.js";
 // Identity for a violation across runs: rule, importing path, and the

package/dist/type-closure.js

@@ -479,7 +479,7 @@ export function buildTypeClosure(inputs) {
     // is dispatched. module-graph.ts's own safety net (a resolution failure
     // rule 6 itself reports while walking the closure Program this
     // function's own output becomes a root list for - see
-    // rules/type-leak.ts's own ReportUnresolvedReference) is a separate
+    // type-leak.ts's own ReportUnresolvedReference) is a separate
     // pass over the real Program, not this syntactic walk; a net built from
     // the same rules it is meant to catch a gap in could never fire.
     //

package/dist/{rules/type-leak.js → type-leak.js}

@@ -19,9 +19,12 @@
 // rather than a separate rule each).
 // Boundary: pure predicate over a ModuleGraph (its shared program and
 // checker) and a boundary root. No I/O, no output formatting.
+// Lives next to the graph builder, not under src/rules: module-graph.ts
+// calls checkTypeLeaks while it builds the closure. A rules-module home
+// would make that call a cycle with every other rule that reads the graph.
 import ts from "typescript";
 import { relative } from "node:path";
-import { declarationKey, sourceFileKey } from "../type-closure.js";
+import { declarationKey, sourceFileKey } from "./type-closure.js";
 function declaredIn(symbol) {
     return symbol.getDeclarations()?.[0]?.getSourceFile().fileName;
 }
@@ -493,6 +496,21 @@ function groupByInternalType(findings, surfacePath) {
     }
     return groups;
 }
+// Two leaks look alike in evidence but need different fixes. A type this
+// module owns needs only a name on this surface. A type owned by a module
+// with no surface cannot get a public name from this surface at all: that
+// module needs a surface, or this surface must stop exposing the type.
+// Any other owner (a module with a surface that does not name the type,
+// or a file no module declares) keeps the general three-way advice.
+function leakDo(moduleName, group, relativeInternalFile, owner, modules, exportsShown) {
+    if (owner === moduleName) {
+        return `'${group.type}' belongs to module '${moduleName}': export '${group.type}' by name from ${group.path} (it's declared in ${relativeInternalFile})`;
+    }
+    if (owner !== undefined && (modules.get(owner)?.surfaceFiles.length ?? 0) === 0) {
+        return `${exportsShown} reaches '${group.type}', owned by module '${owner}', which has no surface: give '${owner}' a surface that exports '${group.type}', or drop ${exportsShown} from this surface`;
+    }
+    return `export '${group.type}' by name from ${group.path} (it's declared in ${relativeInternalFile}), change the referencing exports to not expose it, or add ${relativeInternalFile} to this module's own surface`;
+}
 export function checkTypeLeaks(graph, options = {}) {
     // Forces graph.program/graph.checker first (as this always did): on a
     // graph whose Program was not built yet, that is what populates
@@ -505,13 +523,23 @@ export function checkTypeLeaks(graph, options = {}) {
     // Every declared module's own directory, not the whole project root -
     // see detectTypeLeaks' own comment on why a single, broad boundary was
     // measured wrong.
-    const moduleBoundaries = [...graph.modules.values()].map((m) => m.dir);
+    // boundaryRoots, when present, is the multi-file seam's own files.
+    // Falling back to dir keeps a caller that built a module the old way
+    // (one root, the directory or the single file) on the same answer.
+    const moduleBoundaries = [...graph.modules.values()].flatMap((m) => m.boundaryRoots ?? [m.dir]);
     // Every declaration named by ANY declared module's own surface, computed
     // once for the whole check (not per module): a type a consumer can
     // already import from module B is not a leak in module A's surface
     // either - see collectNamedDeclarations' own header comment.
     const allSurfaceFiles = [...graph.modules.values()].flatMap((m) => m.surfaceFiles);
     const namedDeclarations = collectNamedDeclarations(graph.program, graph.checker, allSurfaceFiles, options.report);
+    // Which declared module owns each analyzed file, for the do: line: a
+    // type owned by this module needs only a name on this surface, while a
+    // type owned by a module with no surface cannot get one from here.
+    const ownerOf = new Map();
+    for (const [name, module] of graph.modules)
+        for (const file of module.files ?? [])
+            ownerOf.set(file, name);
     for (const [name, module] of graph.modules) {
         // The focused Program owns only one module's surface closure. Walking other
         // modules is refused because their absent source files cannot give safe results.
@@ -552,7 +580,7 @@ export function checkTypeLeaks(graph, options = {}) {
                 column: group.column,
                 evidence: `'${group.type}', declared in '${relativeInternalFile}', is never exported by name from module '${name}'${REFERENCED_BY_MARKER}${shown}${more}`,
                 because: BECAUSE,
-                do: `export '${group.type}' by name from ${group.path} (it's declared in ${relativeInternalFile}), change the referencing exports to not expose it, or add ${relativeInternalFile} to this module's own surface`,
+                do: leakDo(name, group, relativeInternalFile, ownerOf.get(group.file), graph.modules, shown + more),
                 todoModule: name,
                 leak: { internalType: group.type, internalFile: group.file, exportedAs: names },
             });

package/dist/verbs/check.js

@@ -7,7 +7,8 @@
 import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { resolve, sep } from "node:path";
 import ts from "typescript";
-import { buildModuleGraphForRules } from "../module-graph.js";
+import { buildModuleGraphForRules, globResolutionDir } from "../module-graph.js";
+import { dominantBypassModule, dominantBypassSentence } from "./map-shape.js";
 import { assertEdgesShapeValid, assertGlobsSupported, assertSchemaVersion, describeShape } from "../config.js";
 import { ReportError } from "../report-error.js";
 import { checkPublicSurfaceBypass } from "../rules/public-surface.js";
@@ -15,7 +16,7 @@ import { checkCycles, checkStaleCycleExceptions, } from "../rules/cycles.js";
 import { checkUncoveredModules } from "../rules/uncovered.js";
 import { checkEmptyRuleSet } from "../rules/empty-rule.js";
 import { checkDeprecatedEdges, } from "../rules/deprecated.js";
-import { checkTypeLeaks } from "../rules/type-leak.js";
+import { checkTypeLeaks } from "../type-leak.js";
 import { checkMustBeEmpty } from "../rules/must-be-empty.js";
 import { checkAllowDeny, checkEdgesCoverage, checkOrder, checkPoint, } from "../rules/constraints.js";
 import { checkConfigMeaning } from "../rules/config-meaning.js";
@@ -26,6 +27,16 @@ export function formatConfigPointerLines(config) {
     const pointers = Array.isArray(config) ? config : [config];
     return pointers.map((pointer) => `  config: ${pointer.path}:${pointer.line}:${pointer.column} ${pointer.pointer} (${pointer.role})`);
 }
+export const NO_EDGES_SUMMARY = "this config freezes today's import graph, not a target architecture; no edges rule is configured yet";
+export const NO_EDGES_DO = [
+    "archstrict recommend",
+    "archstrict hotspots",
+    "read node_modules/archstrict/skills/archstrict/references/rearchitect.md",
+];
+function hasEdgesRule(config) {
+    const edges = config.edges;
+    return (edges?.allowDeny?.length ?? 0) + (edges?.order?.length ?? 0) + (edges?.point?.length ?? 0) > 0;
+}
 // declaredModules replaces modules/kinds as the required field, the same
 // class of config error as a missing kinds used to be: check/todo build
 // their graph from declaredModules unconditionally now, so a config
@@ -129,9 +140,15 @@ function assertDeclaredModulesShapeValid(configPath, raw, verb) {
             throw new ReportError(`${configPath} field 'declaredModules[${i}].name' must be a non-empty string, not ${describeShape(name)}`, `give 'declaredModules[${i}]' a non-empty string 'name' in ${configPath}, then run ${verb}`);
         }
         const glob = entry.glob;
-        if (typeof glob !== "string") {
-            throw new ReportError(`${configPath} field 'declaredModules[${i}].glob' must be a string, not ${describeShape(glob)}`, `give 'declaredModules[${i}]' a string 'glob' in ${configPath}, then run ${verb}`);
+        if (typeof glob === "string")
+            return;
+        if (Array.isArray(glob) && glob.length > 0 && glob.every((item) => typeof item === "string" && item.length > 0)) {
+            const dir = globResolutionDir(glob[0]);
+            if (glob.every((item) => globResolutionDir(item) === dir))
+                return;
+            throw new ReportError(`${configPath} field 'declaredModules[${i}].glob' lists paths that do not share one directory`, `list only files in one directory, or use one declaredModules entry per directory, in ${configPath}, then run ${verb}`);
         }
+        throw new ReportError(`${configPath} field 'declaredModules[${i}].glob' must be a string or a non-empty array of strings, not ${describeShape(glob)}`, `give 'declaredModules[${i}]' a string 'glob', or an array of file paths in one directory, in ${configPath}, then run ${verb}`);
     });
 }
 function allProjectRelativeFiles(graph) {
@@ -688,6 +705,22 @@ export async function check(projectRoot, focusFile, options = {}) {
         includeFrozen: options.frozen,
     });
     const focused = focusFile === undefined ? result : filterToFile(result, focusFile);
+    if (focusFile === undefined && !hasEdgesRule(config)) {
+        focused.nextSteps = { summary: NO_EDGES_SUMMARY, do: [...NO_EDGES_DO] };
+    }
+    // Count bypasses before todo suppression, so a project that already froze
+    // the mega-module still hears that the freeze recorded one bucket.
+    if (focusFile === undefined) {
+        const bypassesByModule = new Map();
+        for (const violation of evaluated.violations) {
+            if (violation.rule !== "public-surface-bypass" || !("todoModule" in violation))
+                continue;
+            bypassesByModule.set(violation.todoModule, (bypassesByModule.get(violation.todoModule) ?? 0) + 1);
+        }
+        const dominant = dominantBypassModule([...graph.modules.values()].map((module) => ({ name: module.name, files: module.files.length })), bypassesByModule);
+        if (dominant !== undefined)
+            focused.dominantModule = dominant;
+    }
     return applyFilters(focused, options);
 }
 // The output must always carry: rule id, path:line:col, evidence, because,
@@ -738,6 +771,16 @@ const UNGROUPED_MODULE = "<project>";
 // root cause (no module in the project chose a surface at all), which "add
 // a surface file" fixes project-wide, not one violation at a time.
 const SURFACE_LESS_NOTE_THRESHOLD = 0.8;
+function dominantModuleLines(result) {
+    const dominant = result.dominantModule;
+    if (dominant === undefined)
+        return [];
+    return [
+        `note: ${dominantBypassSentence(dominant)}. Freezing them records one bucket, and hotspots then report one score.`,
+        `do: split '${dominant.name}' into directories that change together before archstrict todo`,
+        "do: archstrict recommend",
+    ];
+}
 function surfaceLessNote(result) {
     const missing = new Set(result.modulesWithoutSurfaceNames);
     const bypasses = result.violations.filter((violation) => violation.rule === "public-surface-bypass");
@@ -852,7 +895,7 @@ function groupedViolationLines(result) {
     const ordered = groupViolations(result.violations);
     const lines = [
         `violations: ${result.violations.length} in ${ordered.length} group${ordered.length === 1 ? "" : "s"}`,
-        ...surfaceLessNote(result),
+        ...(result.dominantModule !== undefined ? dominantModuleLines(result) : surfaceLessNote(result)),
     ];
     if (ordered.length === 1) {
         appendSingleGroupDetail(lines, ordered[0]);
@@ -907,8 +950,9 @@ export function formatText(result) {
     const lines = result.violations.length <= 20
         ? result.violations.flatMap(formatViolation)
         : groupedViolationLines(result);
-    if (result.violations.length <= 20)
-        lines.push(...surfaceLessNote(result));
+    if (result.violations.length <= 20) {
+        lines.push(...(result.dominantModule !== undefined ? dominantModuleLines(result) : surfaceLessNote(result)));
+    }
     for (const s of result.suggestions) {
         lines.push(`[${s.rule}] ${s.path}:${s.line}:${s.column}`);
         lines.push(`  ${s.evidence}`);
@@ -937,6 +981,13 @@ export function formatText(result) {
     lines.push(`todo: ${result.todo}`);
     for (const note of result.notes ?? [])
         lines.push(`note: ${note}`);
+    // Before the finding's own do: line, so the last line stays the one
+    // concrete action for this run's findings.
+    if (result.nextSteps !== undefined) {
+        lines.push(`summary: ${result.nextSteps.summary}`);
+        for (const step of result.nextSteps.do)
+            lines.push(`do: ${step}`);
+    }
     // A do: line only when there is a concrete next action - a clean
     // check has none, and telling the reader to re-run the command that
     // just produced this clean result is circular, unlike every other
@@ -950,6 +1001,9 @@ export function formatText(result) {
     if (result.violations.some((v) => v.rule === "uncovered-module")) {
         lines.push(`do: add each uncovered-module file to declaredModules or exclude in archstrict.config.ts, then run archstrict check`);
     }
+    else if (result.dominantModule !== undefined && result.violations.some((v) => v.rule !== "config-meaning" && !v.frozen)) {
+        lines.push(`do: split module '${result.dominantModule.name}' before archstrict todo`);
+    }
     else if (result.violations.some((v) => v.rule !== "config-meaning" && !v.frozen)) {
         lines.push(`do: archstrict todo`);
     }