archstrict 0.1.0 → 0.2.0

package/dist/verbs/init.js

@@ -29,6 +29,7 @@ import { ANALYZED_EXTENSIONS, DEFAULT_SURFACE, listAnalyzedFiles, moduleForDecla
 import { groupAnalyzedFiles, nameCandidates, declaredModuleEntryText, suggestUncovered, } from "../module-candidates.js";
 import { compileGlob } from "../classify.js";
 import { SCHEMA_VERSION } from "../config.js";
+import { dominantByFiles } from "./map-shape.js";
 import { ReportError } from "../report-error.js";
 import { loadConfig } from "./check.js";
 const DO_INIT = "archstrict init";
@@ -206,13 +207,16 @@ ${exclude.map((e) => `    ${q(e)},`).join("\n")}
   ],
   // init declared one module per directory that holds TypeScript source and
   // one per TypeScript source file, so every file that check analyzes
-  // belongs to exactly one module. Merge, rename, or remove entries freely:
+  // belongs to exactly one module. This inventory is not a target
+  // architecture: group files that change together (glob may be an array of
+  // file paths in one directory), split a directory that holds unrelated
+  // seams, then add an edges rule. Merge, rename, or remove entries freely:
   // init never rewrites this file. After an edit, run archstrict init to
   // regenerate archstrict.types.ts.
   declaredModules: [
 ${lines.join("\n")}
   ],
-  because: "archstrict init: one module per directory that holds TypeScript source and per TypeScript source file, so the first check covers every file it analyzes",
+  because: "archstrict init: one module per directory that holds TypeScript source and per TypeScript source file, so the first check covers every file it analyzes. This inventory is not a target architecture: name seams that change together, then add edges",
 } satisfies Config;
 `;
 }
@@ -272,7 +276,10 @@ export type Config = {
   // more than one file).
   declaredModules: readonly {
     name: ModuleName;
-    glob: string;
+    // One glob, or several paths that share one directory. An array names
+    // a seam inside a flat directory. Paths in different directories are
+    // a config error; use one entry per directory.
+    glob: string | readonly string[];
     // A single glob, or several - a real package can publish more than
     // one real, differently-shaped public entry point at once. Optional:
     // when absent, a real package.json's own exports map at this
@@ -501,10 +508,19 @@ export async function init(projectRoot, rawDir) {
     }
     const notes = [];
     if (opened !== "" && containerGroups.length > 0 && containerGroups.every((g) => g.kind === "file")) {
-        const note = `${opened}/ holds only files, so each file is its own module. To check ${opened}/ as one module instead (then no import between two of its files is checked): delete archstrict.config.ts, then run archstrict init .`;
+        const note = `${opened}/ holds only files, so each file is its own module and is public as itself. Group files that change together as one module with glob set to an array of those file paths, and name one of them as surface. One module over all of ${opened}/ hides which seams move.`;
         messageLines.push(note);
         notes.push(note);
     }
+    const dominant = dominantByFiles(allGroups.map((group) => ({ name: group.entry.name, files: group.fileCount })));
+    if (dominant !== undefined) {
+        const note = `module '${dominant.name}' holds ${dominant.files} of ${dominant.totalFiles} analyzed files. Split it into directories that change together before archstrict todo, so hotspots stay readable.`;
+        messageLines.push(note);
+        notes.push(note);
+    }
+    const inventoryNote = "this map covers every analyzed file. Name seams that change together, split a directory that holds unrelated seams, then add an edges rule. archstrict recommend proposes both";
+    messageLines.push(inventoryNote);
+    notes.push(inventoryNote);
     return {
         configPath,
         generatedPath,

package/dist/verbs/map-shape.js

@@ -0,0 +1,78 @@
+// Responsibility: name two map shapes that look finished and hide which
+// seams actually move. One module holding almost every file collapses
+// hotspots and a frozen bypass list into one bucket. A file-per-module
+// inventory checks imports between files and still names no growth seam.
+// check, todo, recommend, and init share these thresholds so the note
+// does not drift between verbs. It lives under verbs: the graph builder
+// never calls it, so putting it in core would publish a verb-only helper
+// on the analysis surface.
+// Boundary: pure counts. No config I/O and no graph build.
+// 4/5, the same share check.ts uses for "most bypasses share one cause".
+// Integer math so a real fraction never rounds the wrong way.
+export const DOMINANT_SHARE_NUMERATOR = 4;
+export const DOMINANT_SHARE_DENOMINATOR = 5;
+// Below this, a two-module sample project is not a mega-module, and a
+// handful of bypasses is not a freeze to warn about.
+export const DOMINANT_MIN_FILES = 8;
+export const DOMINANT_MIN_BYPASSES = 8;
+export const FILE_PER_MODULE_MIN = 4;
+export function shareAtLeast(part, total, numerator = DOMINANT_SHARE_NUMERATOR, denominator = DOMINANT_SHARE_DENOMINATOR) {
+    return total > 0 && part * denominator >= total * numerator;
+}
+// The module with the most files, when it holds at least 4/5 of them and
+// at least DOMINANT_MIN_FILES. A tie takes the name that sorts first, so
+// the same counts always name the same module.
+export function dominantByFiles(modules, minFiles = DOMINANT_MIN_FILES) {
+    const totalFiles = modules.reduce((sum, module) => sum + module.files, 0);
+    let best;
+    for (const module of modules) {
+        if (best === undefined
+            || module.files > best.files
+            || (module.files === best.files && module.name < best.name)) {
+            best = module;
+        }
+    }
+    if (best === undefined || best.files < minFiles || !shareAtLeast(best.files, totalFiles))
+        return undefined;
+    return { name: best.name, files: best.files, totalFiles };
+}
+// The file-dominant module, when it also owns at least 4/5 of the
+// public-surface-bypass violations and at least DOMINANT_MIN_BYPASSES of
+// them. Freezing that set records one bucket.
+export function dominantBypassModule(modules, bypassesByModule) {
+    const files = dominantByFiles(modules);
+    if (files === undefined)
+        return undefined;
+    let totalBypasses = 0;
+    for (const count of bypassesByModule.values())
+        totalBypasses += count;
+    const bypasses = bypassesByModule.get(files.name) ?? 0;
+    if (bypasses < DOMINANT_MIN_BYPASSES || !shareAtLeast(bypasses, totalBypasses))
+        return undefined;
+    return { ...files, bypasses, totalBypasses };
+}
+export function dominantBypassSentence(dominant) {
+    return `${dominant.bypasses} of ${dominant.totalBypasses} public-surface-bypass violations target '${dominant.name}', which holds ${dominant.files} of ${dominant.totalFiles} analyzed files`;
+}
+// Single-file modules gathered in one directory, when they are at least
+// 4/5 of the modules and at least FILE_PER_MODULE_MIN of them. Scattered
+// single files across many directories are not this shape.
+export function filePerModuleCluster(modules) {
+    const singles = modules.filter((module) => module.files === 1);
+    if (singles.length < FILE_PER_MODULE_MIN || !shareAtLeast(singles.length, modules.length))
+        return undefined;
+    const byParent = new Map();
+    for (const module of singles)
+        byParent.set(module.parent, (byParent.get(module.parent) ?? 0) + 1);
+    let bestParent = "";
+    let bestCount = -1;
+    for (const [parent, count] of byParent) {
+        if (count > bestCount || (count === bestCount && parent < bestParent)) {
+            bestParent = parent;
+            bestCount = count;
+        }
+    }
+    if (bestCount < FILE_PER_MODULE_MIN || !shareAtLeast(bestCount, modules.length))
+        return undefined;
+    return { parent: bestParent, count: bestCount, total: modules.length };
+}

package/dist/verbs/recommend.js

@@ -5,7 +5,8 @@ import { relative, resolve, sep } from "node:path";
 import { applyTodo, loadConfig, runRules } from "./check.js";
 import { createConfigLocator } from "../config-pointer.js";
 import { fingerprintOf, relativizeForTodo } from "../todo-store.js";
-import { buildModuleGraphForRules, DEFAULT_SURFACE, moduleGlobBaseDir } from "../module-graph.js";
+import { buildModuleGraphForRules, DEFAULT_SURFACE, moduleGlobBaseDir, moduleGlobList } from "../module-graph.js";
+import { dominantByFiles, filePerModuleCluster } from "./map-shape.js";
 // Without a config, recommend previews init's own walk in memory (same
 // argument rules, same groups and globs) instead of running its own
 // single-level "src/*" discovery - the two could disagree about which
@@ -18,6 +19,12 @@ import { freshRun, normalizeDirArg } from "./init.js";
 // (7 covered of 9) never rounds the wrong way against a float constant.
 const SURFACE_COVERAGE_NUMERATOR = 4;
 const SURFACE_COVERAGE_DENOMINATOR = 5;
+function classifyEntries(declaredModules, name, tags) {
+    return moduleGlobList(declaredModules.find((entry) => entry.name === name).glob).map((glob) => ({ glob, tags }));
+}
+function moduleMatchesSegment(declaredModules, name, pattern) {
+    return moduleGlobList(declaredModules.find((entry) => entry.name === name).glob).some((glob) => matchesAnySegment(glob, pattern));
+}
 // Pure and exported so a property test can drive it directly with
 // synthetic importer counts, without building a real filesystem and
 // compiler graph for every case. `counts` must already be sorted densest
@@ -74,6 +81,8 @@ function proposeSurfaces(graph) {
         }
         if (pairs.size === 0)
             continue;
+        const totalFiles = [...graph.modules.values()].reduce((sum, entry) => sum + entry.files.length, 0);
+        const fileDominant = dominantByFiles([...graph.modules.values()].map((entry) => ({ name: entry.name, files: entry.files.length })));
         const candidates = [...importersByFile.entries()]
             .map(([file, importers]) => ({ file: moduleRelative(module, file), importers: importers.size }))
             .sort((a, b) => b.importers - a.importers || (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
@@ -91,7 +100,9 @@ function proposeSurfaces(graph) {
             choices: [
                 `do: set { name: ${JSON.stringify(module.name)}, ..., surface: ${JSON.stringify(proposedSurface)} } in declaredModules to retire ${coveredImports} of ${totalImports} bypasses into '${module.name}', leaving ${totalImports - coveredImports}`,
                 `do: add a barrel file re-exporting from ${proposedSurface[0] ?? "a chosen entry file"}, then name it as this module's surface instead`,
-                `do: leave '${module.name}' entirely private and run archstrict todo to freeze its bypasses as debt instead`,
+                fileDominant?.name === module.name
+                    ? `do: split '${module.name}' before archstrict todo: it holds ${fileDominant.files} of ${totalFiles} analyzed files, and freezing its bypasses records one bucket`
+                    : `do: leave '${module.name}' entirely private and run archstrict todo to freeze its bypasses as debt instead`,
             ],
         });
     }
@@ -133,7 +144,7 @@ const PROVE_RULES_DO = "run archstrict simulate --json with a change set that ad
 function partitionClassify(declaredModules, defaultTag, distinguishedNames, distinguishedTag) {
     return [
         { glob: "**", tags: [defaultTag] },
-        ...distinguishedNames.map(name => ({ glob: moduleGlob(declaredModules, name), tags: [distinguishedTag] })),
+        ...distinguishedNames.flatMap(name => classifyEntries(declaredModules, name, [distinguishedTag])),
     ];
 }
 // A general layered-order detector: it does not name a project's own
@@ -191,7 +202,7 @@ function detectLayeredOrder(modules, counts, declaredModules, baseConfig, graph)
         }
     }
     const support = forward / (forward + reverse);
-    const classify = order.map(name => ({ glob: declaredModules.find(d => d.name === name).glob, tags: [`role:${name}`] }));
+    const classify = order.flatMap(name => classifyEntries(declaredModules, name, [`role:${name}`]));
     const because = `${forward} of ${forward + reverse} directed edges between these modules already match this order`;
     const orderRule = { tagNamespace: "role", sequence: { "": order }, direction: "downward-only", because };
     const configFragment = [
@@ -241,13 +252,13 @@ function detectLeafKernels(modules, graph, declaredModules, baseConfig) {
         const inCount = incoming.get(module.name) ?? 0;
         if (inCount === 0 || (outgoing.get(module.name) ?? 0) > 0)
             continue;
-        const glob = declaredModules.find(d => d.name === module.name).glob;
         const tag = `kind:${module.name}`;
+        const classify = classifyEntries(declaredModules, module.name, [tag]);
         const because = `'${module.name}' is imported by ${inCount} real edge(s) and imports no other declared module today`;
         const allowDenyRule = { source: tag, targetNamespace: "kind", allow: [], because };
         const proposedConfig = {
             ...baseConfig,
-            classify: [...(baseConfig.classify ?? []), { glob, tags: [tag] }],
+            classify: [...(baseConfig.classify ?? []), ...classify],
             edges: { ...baseConfig.edges, allowDeny: [...(baseConfig.edges?.allowDeny ?? []), allowDenyRule] },
         };
         proposals.push({
@@ -256,7 +267,7 @@ function detectLeafKernels(modules, graph, declaredModules, baseConfig) {
                 support: 1,
                 evidence: [`'${module.name}': 0 outgoing edges to another declared module; ${inCount} other module(s) import it`],
                 configFragment: [
-                    "classify: [", `  { glob: ${JSON.stringify(glob)}, tags: ${JSON.stringify([tag])} },`, "],",
+                    "classify: [", ...classify.map(c => `  { glob: ${JSON.stringify(c.glob)}, tags: ${JSON.stringify(c.tags)} },`), "],",
                     "edges: { allowDeny: [", `  { source: ${JSON.stringify(tag)}, targetNamespace: "kind", allow: [], because: ${JSON.stringify(because)} },`, "] },",
                 ].join("\n"),
                 addedViolations: countAddedViolations(graph, baseConfig, proposedConfig, "tag-boundary"),
@@ -307,8 +318,16 @@ function moduleSegments(glob) {
 function matchesAnySegment(glob, pattern) {
     return moduleSegments(glob).some(segment => pattern.test(segment));
 }
-function moduleGlob(declaredModules, name) {
-    return declaredModules.find(d => d.name === name).glob;
+function globsOf(declaredModules, name) {
+    return moduleGlobList(declaredModules.find(d => d.name === name).glob);
+}
+function moduleFeatureKey(declaredModules, name) {
+    for (const glob of globsOf(declaredModules, name)) {
+        const key = featureContainerKey(glob);
+        if (key !== undefined)
+            return key;
+    }
+    return undefined;
 }
 // Sums real cross-module edges from every member of `from` to every
 // member of `to` - the shared unit every grouped detector below reads a
@@ -356,7 +375,7 @@ function freeTagNamespace(config, preferred) {
 // sight in a way an arbitrary majority-direction graph is not.
 const APP_SEGMENT_PATTERN = /^(app|apps|cli|cmd)$/;
 function detectAppOverLibrary(modules, counts, declaredModules, baseConfig, graph) {
-    const appNames = modules.filter(m => matchesAnySegment(moduleGlob(declaredModules, m.name), APP_SEGMENT_PATTERN)).map(m => m.name);
+    const appNames = modules.filter(m => moduleMatchesSegment(declaredModules, m.name, APP_SEGMENT_PATTERN)).map(m => m.name);
     const libNames = modules.map(m => m.name).filter(n => !appNames.includes(n));
     if (appNames.length === 0 || libNames.length === 0)
         return undefined;
@@ -475,7 +494,7 @@ function detectExternalPackageConfined(modules, graph, declaredModules, baseConf
 // zero edges either way is not a kept habit, it is silence.
 const TEST_SEGMENT_PATTERN = /^(tests?|__tests__|test-utils|fixtures?|mocks?|helpers?)$/;
 function detectTestCodeIsolation(modules, counts, declaredModules, baseConfig, graph) {
-    const testNames = modules.filter(m => matchesAnySegment(moduleGlob(declaredModules, m.name), TEST_SEGMENT_PATTERN)).map(m => m.name);
+    const testNames = modules.filter(m => moduleMatchesSegment(declaredModules, m.name, TEST_SEGMENT_PATTERN)).map(m => m.name);
     const prodNames = modules.map(m => m.name).filter(n => !testNames.includes(n));
     if (prodNames.length === 0)
         return [];
@@ -524,8 +543,8 @@ function detectTestCodeIsolation(modules, counts, declaredModules, baseConfig, g
 const HOST_SEGMENT_PATTERN = /^(core|host)$/;
 const PLUGIN_SEGMENT_PATTERN = /^(plugins?|extensions?)$/;
 function detectHostPluginInversion(modules, counts, declaredModules, baseConfig, graph) {
-    const hostNames = modules.filter(m => matchesAnySegment(moduleGlob(declaredModules, m.name), HOST_SEGMENT_PATTERN)).map(m => m.name);
-    const pluginNames = modules.filter(m => matchesAnySegment(moduleGlob(declaredModules, m.name), PLUGIN_SEGMENT_PATTERN)).map(m => m.name);
+    const hostNames = modules.filter(m => moduleMatchesSegment(declaredModules, m.name, HOST_SEGMENT_PATTERN)).map(m => m.name);
+    const pluginNames = modules.filter(m => moduleMatchesSegment(declaredModules, m.name, PLUGIN_SEGMENT_PATTERN)).map(m => m.name);
     if (hostNames.length === 0 || pluginNames.length === 0)
         return undefined;
     const pluginToHost = edgesBetweenGroups(counts, pluginNames, hostNames);
@@ -535,8 +554,8 @@ function detectHostPluginInversion(modules, counts, declaredModules, baseConfig,
     const total = pluginToHost + hostToPlugin;
     const ns = freeTagNamespace(baseConfig, "kind");
     const classify = [
-        ...hostNames.map(name => ({ glob: moduleGlob(declaredModules, name), tags: [`${ns}:host`] })),
-        ...pluginNames.map(name => ({ glob: moduleGlob(declaredModules, name), tags: [`${ns}:plugin`] })),
+        ...hostNames.flatMap(name => classifyEntries(declaredModules, name, [`${ns}:host`])),
+        ...pluginNames.flatMap(name => classifyEntries(declaredModules, name, [`${ns}:plugin`])),
     ];
     const because = `plugin -> host: ${pluginToHost} edge(s); host -> plugin: ${hostToPlugin} edge(s)`;
     const allowDenyRule = { source: `${ns}:host`, targetNamespace: ns, deny: ["plugin"], because };
@@ -582,13 +601,13 @@ function featureContainerKey(glob) {
 function detectFeatureIsolation(modules, counts, declaredModules, baseConfig, graph) {
     const groups = new Map();
     for (const module of modules) {
-        const key = featureContainerKey(moduleGlob(declaredModules, module.name));
+        const key = moduleFeatureKey(declaredModules, module.name);
         if (key === undefined)
             continue;
         (groups.get(key) ?? groups.set(key, []).get(key)).push(module.name);
     }
-    const kernelNames = modules.filter(m => matchesAnySegment(moduleGlob(declaredModules, m.name), KERNEL_SEGMENT_PATTERN)
-        && featureContainerKey(moduleGlob(declaredModules, m.name)) === undefined).map(m => m.name);
+    const kernelNames = modules.filter(m => moduleMatchesSegment(declaredModules, m.name, KERNEL_SEGMENT_PATTERN)
+        && moduleFeatureKey(declaredModules, m.name) === undefined).map(m => m.name);
     const proposals = [];
     for (const [, featureNames] of groups) {
         if (featureNames.length < 2 || kernelNames.length === 0)
@@ -603,8 +622,8 @@ function detectFeatureIsolation(modules, counts, declaredModules, baseConfig, gr
         const featureNs = freeTagNamespace(baseConfig, "feature");
         const kernelNs = freeTagNamespace(baseConfig, "kind");
         const classify = [
-            ...featureNames.map(name => ({ glob: moduleGlob(declaredModules, name), tags: [`${featureNs}:${name}`] })),
-            { glob: moduleGlob(declaredModules, kernelName), tags: [`${kernelNs}:shared`] },
+            ...featureNames.flatMap(name => classifyEntries(declaredModules, name, [`${featureNs}:${name}`])),
+            ...classifyEntries(declaredModules, kernelName, [`${kernelNs}:shared`]),
         ];
         const because = `features -> kernel ('${kernelName}'): ${featureToKernel} edge(s); features -> each other: ${crossFeature} edge(s)`;
         const allowDenyRules = featureNames.map(name => ({ source: `${featureNs}:${name}`, targetNamespace: featureNs, allow: [], because }));
@@ -699,6 +718,8 @@ export async function recommend(projectRoot, dir, surface = DEFAULT_SURFACE) {
         counts.set(edge.fromModule, targets);
     }
     const surfaceProposals = proposeSurfaces(graph);
+    // Graph module.dir paths are realpath-resolved, so use the same root for relative paths.
+    const mapNotes = mapNotesFor(graph.rootDir, modules);
     // A placeholder Config for the no-config path (freshRun's own plan, not
     // a file on disk): detectPatterns only ever reads classify/edges/because
     // off it and passes it straight to runRules, which needs a well-formed
@@ -707,7 +728,8 @@ export async function recommend(projectRoot, dir, surface = DEFAULT_SURFACE) {
     const detected = detectPatterns(modules, graph, counts, declaredModules, baseConfig, surfaceProposals);
     return {
         modules: modules.length,
-        proposedClassify: modules.map(module => ({ glob: declaredModules.find(d => d.name === module.name).glob, tags: [`role:${module.name}`] })),
+        mapNotes,
+        proposedClassify: modules.flatMap(module => classifyEntries(declaredModules, module.name, [`role:${module.name}`])),
         detected: detected.length,
         patternProposals: detected.slice(0, PATTERN_PROPOSAL_CAP),
         surfaceProposals,
@@ -721,6 +743,38 @@ export async function recommend(projectRoot, dir, surface = DEFAULT_SURFACE) {
 // project with dozens of modules must not turn one `recommend` run's own
 // text into hundreds of lines; `--json` always carries every module,
 // every candidate, every name.
+function fileModuleParent(projectRoot, module) {
+    const rel = relative(projectRoot, module.dir).split(sep).join("/");
+    const slash = rel.lastIndexOf("/");
+    return slash === -1 ? "." : rel.slice(0, slash);
+}
+function mapNotesFor(projectRoot, modules) {
+    const notes = [];
+    const dominant = dominantByFiles(modules.map((module) => ({ name: module.name, files: module.files.length })));
+    if (dominant !== undefined) {
+        notes.push({
+            kind: "mega-module",
+            evidence: `'${dominant.name}' holds ${dominant.files} of ${dominant.totalFiles} analyzed files. Hotspots and a frozen bypass list then collapse into one bucket.`,
+            do: `split '${dominant.name}' into directories that change together before archstrict todo, and add an edges rule so import direction is checked`,
+        });
+    }
+    // A directory that holds one file is still a directory seam, not a
+    // file-per-module inventory. Only rootIsFile modules count as singles.
+    const cluster = filePerModuleCluster(modules.map((module) => ({
+        files: module.rootIsFile ? 1 : 0,
+        parent: fileModuleParent(projectRoot, module),
+    })));
+    if (cluster !== undefined) {
+        const where = cluster.parent === "." ? "the project root" : `'${cluster.parent}'`;
+        const sampleDir = cluster.parent === "." ? "" : `${cluster.parent}/`;
+        notes.push({
+            kind: "file-per-module",
+            evidence: `${cluster.count} of ${cluster.total} modules are single files under ${where}. Each file is public as itself, so an import between them is checked, but no growth seam is named.`,
+            do: `group files that change together into one module, for example { name: "seam", glob: ["${sampleDir}a.ts", "${sampleDir}b.ts"], surface: "a.ts" }, then add an edges rule. archstrict hotspots shows which files change together once history exists`,
+        });
+    }
+    return notes;
+}
 const TEXT_LIST_CAP = 5;
 // Truncates a comma-separated list to its first `TEXT_LIST_CAP` items,
 // appending how many were left out - `items.length` alone (not a fixed
@@ -769,6 +823,14 @@ export function formatRecommendText(result) {
     const shownSurfaceProposals = result.surfaceProposals.slice(0, TEXT_LIST_CAP);
     return [
         `${result.modules} modules; ${result.detected} pattern(s) detected, ${result.patternProposals.length} shown`,
+        ...(result.mapNotes.length === 0 ? [] : [
+            "",
+            "map:",
+            ...result.mapNotes.flatMap(note => [
+                `  ${note.kind}: ${note.evidence}`,
+                `  do: ${note.do}`,
+            ]),
+        ]),
         ...(result.patternProposals.length === 0 ? [] : [
             "", "pattern proposals, ranked by evidence:",
             ...result.patternProposals.flatMap(proposal => [
@@ -786,12 +848,13 @@ export function formatRecommendText(result) {
             // proposeSurfaces's own `choices`, still complete in JSON).
             "  do: set { name, ..., surface: [...] } in declaredModules, per module below, to retire its listed bypasses",
             "  do: or add a barrel file re-exporting from a chosen entry file, and name that as the module's surface instead",
-            "  do: or leave a module entirely private and run archstrict todo to freeze its bypasses as debt instead",
+            "  do: or leave a small module entirely private and run archstrict todo; split a module that holds most of the files before freezing it",
             ...shownSurfaceProposals.flatMap(proposal => [
                 `  ${proposal.module}: ${quote(proposal.proposedSurface)} covers ${proposal.coveredImports} of ${proposal.totalImports} bypasses, ${proposal.remainingImports} remaining`,
                 ...proposal.candidates.slice(0, SURFACE_CANDIDATE_TEXT_CAP).map(c => `    ${c.file} (${c.importers} importer(s))`),
                 ...(proposal.candidates.length > SURFACE_CANDIDATE_TEXT_CAP ? [`    ... ${proposal.candidates.length - SURFACE_CANDIDATE_TEXT_CAP} more candidate(s); see --json`] : []),
                 `  ${proposal.choices[0]}`,
+                ...(proposal.choices[2]?.startsWith("do: split ") ? [`  ${proposal.choices[2]}`] : []),
             ]),
             ...(result.surfaceProposals.length > TEXT_LIST_CAP ? [`  ... ${result.surfaceProposals.length - TEXT_LIST_CAP} more surface-less module(s); see --json`] : []),
         ]),

package/dist/verbs/todo.js

@@ -16,6 +16,7 @@ import { ReportError } from "../report-error.js";
 import { buildTodoEntry, buildTodoIndex, findMatchingEntry, readTodoFile, writeTodoFile, } from "../todo-store.js";
 import { deleteLegacyTodoFiles, readLegacyTodoState } from "../todo-migration.js";
 import { loadConfig, runRules } from "./check.js";
+import { dominantBypassModule, dominantBypassSentence } from "./map-shape.js";
 function isFreezable(v) {
     return "todoModule" in v;
 }
@@ -145,7 +146,23 @@ export function freezeOrPrune(projectRoot, graph, config, violations) {
     writeTodoFile(rootDir, nextByModule);
     if (legacy !== undefined)
         deleteLegacyTodoFiles(legacy.filesToDelete);
-    return { firstRun, added, pruned };
+    const bypassesByModule = new Map();
+    for (const violation of 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)
+        return { firstRun, added, pruned };
+    return {
+        firstRun,
+        added,
+        pruned,
+        notes: [
+            `${dominantBypassSentence(dominant)}. Freezing them records one bucket. Split '${dominant.name}' into directories that change together before treating this freeze as done.`,
+        ],
+    };
 }
 export async function todo(projectRoot) {
     const configPath = join(projectRoot, "archstrict.config.ts");

package/docs/init-singleton-modules.md

@@ -82,10 +82,15 @@ rules read production code) right beside the pattern it excluded.
 ## Zero-directory and zero-candidate cases
 
 A container holding only loose files (no directories at all) still
-declares one module per file; `init` prints one extra line, naming the
-alternative (checking the whole container as one module instead) without
-writing it - that shape stays a hand-edit, since a `do:` line names one
-action, not a menu.
+declares one module per file. `init` prints a line saying each file is
+public as itself, and that grouping files which change together is a
+`glob` array of those paths with one `surface`. One module over the whole
+container hides which seams move, so the line does not recommend that
+shape. `archstrict init .` can still declare the container as one
+directory module, for a caller who asks for that walk. The `do:` line
+stays `archstrict check`, one action. Every fresh run also prints that
+the map is an inventory: name seams, then add an `edges` rule.
+`archstrict recommend` proposes both.
 
 A project with no analyzed source file anywhere - under the seeded
 exclude - has nothing for `init` to declare. It writes neither file and

package/docs/maintenance.md

@@ -26,11 +26,38 @@ scratch copy of a local clone, converting each project's own real config with th
 [AGENTS.md](../AGENTS.md)'s Commands section for what each requires (a local clone, `pnpm install`
 for the Prisma one) and what each prints.
 
+After `npm run build`, `node dist/cli.js check` analyzes this repository's own `src/` with the root
+`archstrict.config.ts`. A clean run exits 0. `node dist/cli.js todo` creates `archstrict.todo.json`
+on the first run and only prunes it afterward. Modules named in that config's `strict` list cannot
+take on frozen debt. The skill under `skills/archstrict/` is what the package ships; it is not a
+second copy of this config.
+
 `npm run ci:ts7-probe` measures which of the operations rule 6 needs work on whatever typescript 7
 happens to be installed. It never fails; an unsupported operation is the measurement, not an error.
 archstrict itself always analyzes with its own pinned `typescript` dependency, independent of this
 probe.
 
+`npm run mutation` runs Stryker (`stryker run`) with the Vitest runner. It mutates `src/**/*.ts`
+except `src/cli.ts` and `src/mcp-server.ts` — those two are process entry points, and several tests
+drive the built `dist/cli.js` rather than the source file Stryker rewrites. The full set is large
+(the suite is serial, and many tests build a real TypeScript program). A bounded look is
+`npx stryker run --mutate src/<file>.ts`. `coverageAnalysis` stays `perTest`.
+
+That bounded form is the one to use. The full mutate set is thousands of mutants, and the
+Vitest `related` filter still selects most of the suite for a single source file, because tests
+reach that file through other imports. The time goes to the suite — synchronous CLI spawns and
+TypeScript startup — rather than to Stryker's instrumenter.
+
+Stryker copies the project into a sandbox with `copyFile`. That call throws on the directory
+symlinks `hooks` and `mcp`, and it would replace `.claude-plugin/plugin.json` with a regular file.
+`ignorePatterns` leaves those three paths out of the copy. `test/global-setup.ts` recreates the
+symlinks when they are missing, which is a no-op in a normal checkout.
+
+The count increments in `src/rules/constraints.ts` are additions (`x = x! + 1`), not `x!++`.
+The instrumenter's update-operator mutator rebuilds `++`/`--` with Babel's `updateExpression`,
+and Babel 8 rejects a non-null assertion as that argument. Excluding the mutator does not help:
+the mutator still runs, and the throw aborts the run before any mutant is tested.
+
 ## Dependencies and Node.js
 
 Do not add a dependency without the owner's approval. Pin every dependency to an exact version.

package/docs/releasing.md

@@ -45,11 +45,14 @@ to work.
    the `package.json` version. Push the commit and tag. The tag push starts the workflow.
 5. Approve the `publish` environment for that Actions run. The workflow runs `npm ci`, the build,
    typecheck, and tests before `npm publish`. `prepublishOnly` repeats those checks.
-6. Extract only that version's notes. `--notes-file CHANGELOG.md` would include every version.
-   Use `awk '/^## 0.x.0/{in_version=1;next} /^## /{in_version=0} in_version' CHANGELOG.md > notes.md`.
-   Then run `gh release create v0.x.0 --title v0.x.0 --notes-file notes.md`.
+6. After `npm publish` succeeds, the workflow's `release` job creates the GitHub release. It
+   extracts only that version's section from `CHANGELOG.md` (the whole file would carry every
+   version), and it skips a release that already exists, so re-running the tag is safe. If that job
+   fails, extract the section and create the release by hand:
+   `awk '/^## 0.x.0/{in_version=1;next} /^## /{in_version=0} in_version' CHANGELOG.md > notes.md`,
+   then `gh release create v0.x.0 --title v0.x.0 --notes-file notes.md`.
 7. Install or update the skill and plugin for the agents that use this repository, following
    whatever install path Claude Code and the agent's own tooling document for a plugin repository
    at that time; this repository names no fixed install command for that step.
 
-The owner performs the commit, tag, push, environment approval, release creation, and npm publish.
+The owner performs the commit, tag, push, and environment approval. The workflow then publishes to npm and creates the GitHub release.

package/llms.txt

@@ -8,12 +8,18 @@ Agent skill: [skills/archstrict/SKILL.md](skills/archstrict/SKILL.md)
 
 Installed package: `node_modules/archstrict/skills/archstrict/SKILL.md` (this file sits beside it at `node_modules/archstrict/llms.txt`).
 
+## Install
+
+- Every host: `npm install -D archstrict` puts the CLI at `node_modules/.bin/archstrict`.
+- Claude Code: install the plugin from this repository's marketplace with `/plugin marketplace add meganemura/archstrict` and `/plugin install archstrict@archstrict`. The plugin carries the skill, the PreToolUse and PostToolUse edit hooks, and the MCP server.
+- Other agents (Cursor, Codex, cloud agents): `gh skill install meganemura/archstrict archstrict --agent <agent> --scope user` installs the skill once for the user. Copying `skills/archstrict` into every repository duplicates it. `npx archstrict agents` adds the per-project `AGENTS.md` section (a few command lines, separate from the skill). Run `npx archstrict check` in CI, since the edit hooks are Claude Code only.
+
 ## Commands
 
-- `archstrict init [dir] [--json]` — declare one module per top-level directory holding `.ts` and one per loose top-level `.ts` file, so the first `check` covers every file by construction; write `archstrict.types.ts` and, if missing, `archstrict.config.ts` (`schemaVersion: 1`)
+- `archstrict init [dir] [--json]` — declare one module per top-level directory holding `.ts` and one per loose top-level `.ts` file, so the first `check` covers every file by construction; write `archstrict.types.ts` and, if missing, `archstrict.config.ts` (`schemaVersion: 1`). The map is an inventory. Group files that change together (`glob` may be an array of paths in one directory), split a directory that holds almost every file, then add `edges`. `recommend` names a mega-module and a file-per-module inventory.
 - `archstrict check [file] [--json] [--rule <id>] [--module <name>] [--frozen]` — report violations for the whole project; a file argument only scopes the report. Up to 20 violations print in full; more print grouped counts with one example each, plus a `do:` per group. `--rule`/`--module` narrow the printed and JSON violations (repeatable); the exit code reflects the filtered set once a filter is given. `--frozen` also includes todo-matched violations, marked `frozen: true` and exempt from the exit code, so a re-architecting agent can read a module's frozen debt through the same filters instead of opening its todo JSON by hand
 - `archstrict todo [--json]` — freeze current freezable violations on the first run, then only prune
-- `archstrict recommend [dir] [--json]` — `patternProposals`: at most 5 detected boundary patterns (layered order, app over library, leaf/pure kernel, external package confined to one area, test code kept out of production, public-entry-only, host/plugin inversion, feature isolation around a shared kernel), ranked by how strongly the real edges support each, with evidence, a pasteable config fragment, and how many violations adopting it would add today; `surfaceProposals`: for each surface-less module, a ranked list of the files other modules actually import from it and the smallest ranked prefix covering at least 80% of those imports, offered as a `surface` value alongside adding a barrel file or freezing the module private
+- `archstrict recommend [dir] [--json]` — `mapNotes` names a mega-module (one module holds most files) and a file-per-module inventory; `patternProposals`: at most 5 detected boundary patterns (layered order, app over library, leaf/pure kernel, external package confined to one area, test code kept out of production, public-entry-only, host/plugin inversion, feature isolation around a shared kernel), ranked by how strongly the real edges support each, with evidence, a pasteable config fragment, and how many violations adopting it would add today; `surfaceProposals`: for each surface-less module, a ranked list of the files other modules actually import from it and the smallest ranked prefix covering at least 80% of those imports, offered as a `surface` value alongside adding a barrel file or freezing the module private
 - `archstrict hotspots [--since <git ref or date>] [--json]` — combine Git change frequency and co-change with module fan-in, fan-out, frozen debt, and active violations
 
 A config or missing-file failure prints a `do:` line naming the command to run. With `--json` that failure is `{ "error": "<message>", "do": "<command>" }`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archstrict",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "TypeScript module boundary checker: default-private module surfaces, layers, cycles, and a todo freeze that can only shrink.",
   "keywords": [
     "architecture",
@@ -44,6 +44,7 @@
     "build": "tsc -p tsconfig.build.json",
     "dogfood:nukadoko": "npm run build && nuka run features",
     "ci:ts7-probe": "node scripts/probe-typescript7.mjs",
+    "mutation": "stryker run",
     "prepare": "npm run build",
     "prepublishOnly": "npm run build && npm run typecheck && npm test"
   },
@@ -54,9 +55,12 @@
   "devDependencies": {
     "@hegeldev/hegel": "0.4.5",
     "@meganemura/depug": "0.1.3",
+    "@stryker-mutator/core": "10.0.0",
+    "@stryker-mutator/vitest-runner": "10.0.0",
     "@types/node": "26.5.1",
     "@vitest/coverage-v8": "5.0.0",
     "nukadoko": "0.12.0",
+    "stryker-agent-reporter": "0.1.0",
     "vitest": "5.0.0"
   },
   "engines": {