archstrict 0.0.0 → 0.2.0

package/dist/verbs/init.js

@@ -0,0 +1,538 @@
+// Responsibility: the `init` verb. On a fresh project (no
+// archstrict.config.ts yet), walks the project's own real files with
+// check's own eligibility rule (module-graph.ts's listAnalyzedFiles) and
+// declares one module per top-level directory that holds an analyzed .ts
+// file, and one single-file module per loose top-level .ts file - so every
+// file the first `check` analyzes already belongs to exactly one module,
+// by construction. On a re-run, init never touches an existing config: it
+// only re-reads it and regenerates archstrict.types.ts (the ModuleName
+// union) from its own declaredModules names.
+// Boundary: file I/O, argument parsing, and text generation only. Grouping
+// files into modules and naming them is module-candidates.ts's job (a pure
+// function of the file list); init only decides WHICH files and anchors
+// that function sees, and writes what it returns.
+//
+// Singletons over one catch-all module or a menu of shapes: a project
+// whose first init already covers every analyzed file needs no
+// uncovered-module violation todo could never freeze away (an unfreezable
+// violation, since a file matching no module has no module directory to
+// freeze it into) - the trap an inventory-only design (declare directories,
+// leave loose files uncovered) falls into on a real, unconventional
+// codebase. A single catch-all module for every loose file was rejected
+// too: it produces a degenerate public surface (every loose file's own
+// exports at once) and a glob whose own base directory is the project
+// root, which - with a real node_modules present - puts node_modules
+// itself inside rule 6's own type-leak boundary.
+import { existsSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { ANALYZED_EXTENSIONS, DEFAULT_SURFACE, listAnalyzedFiles, moduleForDeclaredFile, toProjectRelativePosix, } from "../module-graph.js";
+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";
+const DO_CHECK = "archstrict check";
+// The re-run's own uncovered-file scan: every analyzed file the config's
+// own exclude and declaredModules leave uncovered, grouped and named the
+// same way rule 3's do: and a fresh init's own groups are - so pasting
+// every line this prints, verbatim, leaves 0 uncovered-module (Hegel P7).
+// `moduleForDeclaredFile` is the exact predicate buildModuleGraph itself
+// uses to decide `outsideFiles` (module-graph.ts's own prepareGraph), so
+// this list agrees with what the next real check would report, without
+// building a whole ts.Program just to ask that question.
+function uncoveredGroups(projectRoot, declaredModules, exclude, surface) {
+    const files = listAnalyzedFiles(projectRoot, exclude, declaredModules, surface);
+    const uncovered = files.filter((f) => moduleForDeclaredFile(f, projectRoot, declaredModules) === undefined);
+    const rel = uncovered.map((f) => toProjectRelativePosix(f, projectRoot));
+    return suggestUncovered(rel, declaredModules);
+}
+function fail(message, doText) {
+    throw new ReportError(message, doText);
+}
+// A name must be near-universally non-source across ordinary TypeScript
+// projects, not merely something one specific project happened to use
+// (docs/, migrations/, and this project's own plugin/skills directories
+// are real source in some real projects, so they stay out) - init only
+// ever excludes a name from this list when it finds a real top-level
+// directory of that name on disk, never blindly. dist/ is deliberately
+// absent: listAnalyzedFiles already drops every path with a dist segment,
+// so a "dist/**" exclude entry would change nothing real, only add a line
+// nobody ever needs to remove.
+const NOISE_DIR_CANDIDATES = ["test", "tests", "example", "examples", "spike", "build", "coverage", "fixtures", "e2e", "tmp"];
+const OWN_FILES = ["archstrict.config.ts", "archstrict.types.ts"];
+// tsc's own default `include` already skips every hidden path; ts.sys's
+// own readDirectory does not, which floods a first check with files from
+// tool-state directories (.git, an editor's own cache) that were never
+// really project source. These two patterns are the same on every
+// machine (unlike naming a specific hidden directory found on disk, which
+// would put a local, one-machine name into a committed config) - one for
+// a hidden directory at the project root, one for a hidden directory at
+// any deeper level.
+const HIDDEN_EXCLUDE = [".*/**", "**/.*/**"];
+// A colocated test file imports across module boundaries as a fixture.
+// Measured across 50 popular TypeScript codebases: about 7.6% of public-
+// surface-bypass findings trace to one of these three naming conventions
+// alone (*.test.ts, *.spec.ts, __tests__/) - a separate, larger share
+// traces to a test/ or tests/ directory (init excludes a top-level one as
+// noise) - and roughly two of every five
+// test files sit beside the production file they test, not in a
+// directory of their own. So init excludes each real test-file naming
+// convention it finds on disk, the same never-blindly discipline
+// NOISE_DIR_CANDIDATES already follows.
+// One entry per (test|spec) suffix crossed with every analyzed extension,
+// plus the `__tests__/` directory convention. `root` and `nested` are
+// always both added: compileGlob's own `**/` needs a literal slash, so
+// `**/*.test.ts` alone never matches a file sitting at the project root
+// (see HIDDEN_EXCLUDE's own two-pattern split, the same reason).
+const TEST_FILE_EXCLUDE_CANDIDATES = [
+    ...["test", "spec"].flatMap((suffix) => ANALYZED_EXTENSIONS.map((ext) => ({
+        label: `*.${suffix}${ext}`,
+        root: `*.${suffix}${ext}`,
+        nested: `**/*.${suffix}${ext}`,
+    }))),
+    { label: "__tests__/", root: "__tests__/**", nested: "**/__tests__/**" },
+];
+// Which real test-file conventions the walk found, and how many analyzed
+// files (root or nested) each one matches - computed against `files`
+// BEFORE these globs are folded into the exclude used for grouping, since
+// that's the file set the convention needs to be real against. Never
+// blind: a convention this project never used (say, `.spec.cts` in a
+// project with no `.cts` file at all) adds nothing.
+function findTestFileExcludes(files) {
+    const result = [];
+    for (const c of TEST_FILE_EXCLUDE_CANDIDATES) {
+        const rootTest = compileGlob(c.root).test;
+        const nestedTest = compileGlob(c.nested).test;
+        const fileCount = files.filter((f) => rootTest(f) || nestedTest(f)).length;
+        if (fileCount > 0)
+            result.push({ label: c.label, exclude: [c.root, c.nested], fileCount });
+    }
+    return result;
+}
+function isRealDirectory(path) {
+    return existsSync(path) && statSync(path).isDirectory();
+}
+function findNoiseDirs(projectRoot, keptOpen) {
+    // A container named on the command line is real source the caller
+    // asked to open, never treated as noise - `archstrict init test` opens
+    // test/ and does not also exclude it.
+    // Matched against the exact entries readdirSync returns, not
+    // existsSync(join(projectRoot, name)) - existsSync resolves through a
+    // case-insensitive filesystem, so a real `Test/` would otherwise match
+    // the candidate name "test" and init would exclude a directory that
+    // isn't there under that spelling (and declare it a module too, since
+    // the walk itself finds "Test/" by its real name).
+    const onDisk = new Set(readdirSync(projectRoot));
+    return NOISE_DIR_CANDIDATES.filter((name) => name !== keptOpen && onDisk.has(name) && statSync(join(projectRoot, name)).isDirectory());
+}
+// The argument table's own syntax rules - stripping a trailing "/*" or
+// "/", rejecting a leftover glob character, a leftover "/", a hidden name,
+// or a name init never analyzes anyway. Applied on every run, fresh or
+// re-run: a re-run ignores a valid directory argument (see the re-run
+// section below), but a syntactically invalid one is still an error, not
+// silently ignored. Returns "" for "no container" (the project root
+// alone), and undefined when no argument was given at all.
+//
+// `verb` names the command in every message and `do:` line - "init" by
+// default, so init's own text stays byte-identical. recommend reuses this
+// same walk for its own directory argument (no config yet, so no
+// declaredModules to fall back on) and passes "recommend" instead, so a
+// bad argument there is never told to run a command that isn't the one
+// the reader typed.
+export function normalizeDirArg(raw, verb = "init") {
+    if (raw === undefined)
+        return undefined;
+    if (raw === "." || raw === "./" || raw === "*")
+        return "";
+    const doVerb = `archstrict ${verb}`;
+    const stripped = raw.replace(/\/\*$/, "").replace(/\/+$/, "");
+    if (/[*?[\]{}]/.test(stripped))
+        fail(`${verb} takes a directory name, not the glob '${raw}'`, doVerb);
+    if (stripped.includes("/"))
+        fail(`${verb} takes one top-level directory name, not '${raw}'`, doVerb);
+    if (stripped.startsWith(".")) {
+        fail(`${verb} does not open the hidden directory '${stripped}': the exclude that init writes skips hidden directories`, doVerb);
+    }
+    if (stripped === "node_modules" || stripped === "dist") {
+        fail(`${verb} does not open '${stripped}': check never analyzes it`, doVerb);
+    }
+    return stripped;
+}
+function plural(n, one, many) {
+    return `${n} ${n === 1 ? one : many}`;
+}
+function countLabel(groups) {
+    const dirs = groups.filter((g) => g.kind === "dir").length;
+    const files = groups.filter((g) => g.kind === "file").length;
+    return `${plural(dirs, "directory", "directories")}, ${plural(files, "file", "files")}`;
+}
+const q = JSON.stringify;
+function configText(opened, containerGroups, topGroups, exclude, noiseDirs, testFileExcludes) {
+    const lines = [];
+    if (containerGroups.length > 0) {
+        lines.push(`    // Each directory and TypeScript source file directly in ${opened}/.`);
+        lines.push(...containerGroups.map((g) => `    ${declaredModuleEntryText(g.entry)},`));
+    }
+    if (topGroups.length > 0) {
+        lines.push(opened !== ""
+            ? `    // Each other top-level directory that holds TypeScript source, and each top-level TypeScript source file.`
+            : `    // Each top-level directory that holds TypeScript source, and each top-level TypeScript source file.`);
+        lines.push(...topGroups.map((g) => `    ${declaredModuleEntryText(g.entry)},`));
+    }
+    const noiseComment = noiseDirs.length > 0
+        ? `\n  // - common noise directories that init found on disk (${noiseDirs.join(", ")}).\n  //   Remove one of these entries if that directory holds module content.`
+        : "";
+    const testComment = testFileExcludes.length > 0
+        ? `\n  // - colocated test files, found on disk (${testFileExcludes.map((t) => t.label).join(", ")}).\n  //   A test file imports across modules as a fixture; boundary rules read production code.\n  //   Remove both matching entries below (root and nested form) if that file must stay analyzed.`
+        : "";
+    return `import type { Config } from "./archstrict.types.js";
+
+// Public surface: other modules may import a directory module only through
+// its own surface file (named by \`surface\` below), or through the files its own
+// package.json exports map names. An import that reaches any other file in
+// the directory is a violation. A directory module with no such file is
+// entirely private. A module whose glob names one file is that file, so its
+// entry names the file itself as its surface.
+export default {
+  schemaVersion: ${SCHEMA_VERSION},
+  surface: [${DEFAULT_SURFACE.map((s) => q(s)).join(", ")}],
+  // Kept out of analysis entirely:
+  // - archstrict's own two files, which are never module content;
+  // - hidden directories at any depth (.git, tool state), which tsc's own
+  //   default include also skips;${noiseComment}${testComment}
+  exclude: [
+${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. 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. This inventory is not a target architecture: name seams that change together, then add edges",
+} satisfies Config;
+`;
+}
+function generatedFileContents(moduleNames) {
+    const union = moduleNames.length > 0 ? moduleNames.map((n) => JSON.stringify(n)).join(" | ") : "never";
+    return `// Generated by archstrict init from archstrict.config.ts's own
+// declaredModules. Do not edit this file directly: after adding, removing,
+// or renaming a declaredModules entry, run archstrict init again to
+// regenerate this union to match.
+export type ModuleName = ${union};
+
+// configPath is added by the loader, not written here - a config file
+// cannot know its own path.
+export type Config = {
+  // The schema this config was written for. ${SCHEMA_VERSION} is the only
+  // value archstrict reads. Omit it and the loader treats the file as
+  // schema ${SCHEMA_VERSION}.
+  schemaVersion?: ${SCHEMA_VERSION};
+  surface?: string | readonly string[];
+  deprecated?: readonly {
+    from: ModuleName;
+    to: ModuleName;
+    count: number;
+    because: string;
+  }[];
+  // Module names whose todo entries may only shrink, never gain a new one.
+  // check reports any existing entry for one of these modules as a
+  // violation in its own right.
+  strict?: readonly ModuleName[];
+  // A specific known cycle (naming any two modules in it, in either
+  // order) exempted from rule 2 - an entry naming a pair no longer in any
+  // real cycle is itself flagged (stale-cycle-exception).
+  ignoredCycles?: readonly (readonly [string, string])[];
+  // An analysis boundary narrower than the whole project - not yet read
+  // by any rule or verb (declared here for forward compatibility; wiring
+  // it in is separate, later work).
+  scope?: string;
+  // Glob patterns kept out of analysis entirely - not a member of any
+  // module, not a source of edges, not a target either. init writes one
+  // default: this project's own root-level files (archstrict.config.ts,
+  // archstrict.types.ts) are never module content.
+  exclude?: readonly string[];
+  // glob -> tags, most-specific-glob-wins. Independent of declaredModules
+  // below - tags classify any file; declaredModules says which files form
+  // an enforced module boundary.
+  classify?: readonly { glob: string; tags: readonly string[] }[];
+  // Ambient tagging by directory-name segment: the nearest path segment
+  // matching one of \`names\`, walking from the file outward, becomes
+  // \`\${tagNamespace}:\${name}\`. Independent of \`classify\` above - a file
+  // can carry tags from both mechanisms at once.
+  classifyByDirectoryName?: {
+    tagNamespace: string;
+    names: readonly string[];
+  };
+  // Declared modules - the source of truth for module boundaries.
+  // \`surface\` may itself be a glob (a module's public surface can be
+  // more than one file).
+  declaredModules: readonly {
+    name: ModuleName;
+    // 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
+    // module's own root is derived back to source instead, falling back
+    // to this project's own top-level surface default otherwise.
+    surface?: string | readonly string[];
+    // Rule 1's own "friend" exception: \`file\` (relative to this module,
+    // may itself be a glob) is public to exactly the importers \`from\`
+    // (a project-relative glob) matches, private to everyone else -
+    // unlike \`surface\`, which is public to every importer equally.
+    friends?: readonly { file: string; from: string; because: string }[];
+  }[];
+  // A directory that must hold no code at all (archspec's own
+  // "empty component" idea) - a violation is any file matching the glob.
+  mustBeEmpty?: readonly { glob: string; because: string }[];
+  // The constraint engine: allowDeny/order/point rules over classify
+  // tags, generalizing the fixed module vocabulary above. \`allowDeny\`'s
+  // own \`exceptions\`: a from/to glob or tag-predicate pair that overrides
+  // that rule either way for one specific edge - \`point\` has no
+  // exceptions of its own, its from/to predicates already being as
+  // explicit as a rule gets.
+  edges?: {
+    allowDeny?: readonly {
+      source: string;
+      targetNamespace: string;
+      allow?: readonly string[];
+      deny?: readonly string[];
+      exceptions?: readonly { from: string; to: string; because: string }[];
+      edgeType?: "value" | "type" | "both";
+      importForm?: "static" | "dynamic" | "both";
+      because: string;
+    }[];
+    order?: readonly {
+      tagNamespace: string;
+      within?: string;
+      sequence: Record<string, readonly string[]>;
+      direction: "downward-only";
+      edgeType?: "value" | "type" | "both";
+      importForm?: "static" | "dynamic" | "both";
+      because: string;
+    }[];
+    point?: readonly {
+      from: string | { tags: readonly string[]; exclude?: { tags: readonly string[] } };
+      to: string | { tags: readonly string[] };
+      edgeType?: "value" | "type" | "both";
+      importForm?: "static" | "dynamic" | "both";
+      because: string;
+    }[];
+  };
+  because: string;
+};
+`;
+}
+// The fresh-run walk: find every analyzed file under the seeded exclude,
+// group it under the opened container (if any) plus the project root, and
+// name every group - module-candidates.ts owns the grouping/naming rule
+// itself, this only decides which files and anchors it sees.
+// Exported so recommend's own no-config path can build a graph from the
+// same groups and globs init would write, without writing any file - a
+// second, independent walk could disagree with init about which files
+// exist and how they group. `verb` names the command in every error and
+// `do:` line here too, the same reason normalizeDirArg takes it.
+export function freshRun(projectRoot, dir, verb = "init") {
+    const explicit = dir !== undefined;
+    const want = dir ?? "src";
+    const noiseDirs = findNoiseDirs(projectRoot, want);
+    const baseExclude = [...OWN_FILES, ...HIDDEN_EXCLUDE, ...noiseDirs.map((n) => `${n}/**`)];
+    // The test-file scan runs against the file set noise/hidden excludes
+    // leave behind, BEFORE folding its own globs in - findTestFileExcludes
+    // needs to see a real *.test.ts to decide the convention is real, and
+    // that file would otherwise already be gone.
+    const preTestFiles = listAnalyzedFiles(projectRoot, baseExclude).map((f) => toProjectRelativePosix(f, projectRoot));
+    const testFileExcludes = findTestFileExcludes(preTestFiles);
+    const exclude = [...baseExclude, ...testFileExcludes.flatMap((t) => t.exclude)];
+    // Project-relative, POSIX-separated: every anchor, glob, and stdout path
+    // below is project-relative too, and listAnalyzedFiles itself returns
+    // absolute, platform-separated paths (the same shape a real TypeScript
+    // program's own file names take). Re-scanned with the full exclude
+    // (noise, hidden, AND test-file globs) so a colocated test file is
+    // gone from grouping too, not just from this convention's own count.
+    const files = listAnalyzedFiles(projectRoot, exclude).map((f) => toProjectRelativePosix(f, projectRoot));
+    let opened = "";
+    let rootLabel;
+    if (want !== "") {
+        const holds = files.some((f) => f.startsWith(`${want}/`));
+        if (holds) {
+            opened = want;
+        }
+        else if (explicit) {
+            fail(`'${want}' is not a top-level directory that holds a .ts file check analyzes`, `archstrict ${verb}`);
+        }
+        else {
+            rootLabel = isRealDirectory(join(projectRoot, want))
+                ? `top level; ${want}/ holds no .ts file`
+                : `top level; there is no ${want}/ directory`;
+        }
+    }
+    else {
+        rootLabel = "top level";
+    }
+    const anchors = opened === "" ? [""] : ["", opened];
+    const groups = nameCandidates(groupAnalyzedFiles(files, anchors), new Set());
+    if (groups.length === 0) {
+        // Every analyzed .ts file the plain walk (no noise exclude applied)
+        // finds is inside a noise directory, or there is none at all. In the
+        // first case, naming that directory ("archstrict init test") is a
+        // real fix - opening it declares its files as modules instead of
+        // excluding them. In the second, there is nothing on disk to open.
+        const beforeNoiseExclude = listAnalyzedFiles(projectRoot, [...OWN_FILES, ...HIDDEN_EXCLUDE]).map((f) => toProjectRelativePosix(f, projectRoot));
+        const openable = noiseDirs.find((n) => beforeNoiseExclude.some((f) => f.startsWith(`${n}/`)));
+        fail(`found no .ts file to declare as a module in ${projectRoot} (init skips node_modules/, dist/, hidden directories, noise directories, and colocated test files)`, openable !== undefined
+            ? `archstrict ${verb} ${openable}`
+            : `add a .ts source file outside those directories, then run archstrict ${verb}`);
+    }
+    const containerGroups = groups.filter((g) => g.anchor !== "");
+    const topGroups = groups.filter((g) => g.anchor === "");
+    return {
+        opened,
+        rootLabel,
+        noiseDirs,
+        testFileExcludes,
+        exclude,
+        containerGroups,
+        topGroups,
+        declaredModules: [...containerGroups, ...topGroups].map((g) => g.entry),
+    };
+}
+// The root-level hidden directories that hold at least one analyzed file -
+// used only for the stdout line naming them, never for anything the
+// generated config depends on (the committed hidden-directory exclude
+// patterns are fixed and machine-independent; see HIDDEN_EXCLUDE's own
+// comment). A second scan, leaving the two hidden patterns out of the
+// exclude list, is simpler than teaching the first scan to also report
+// what it's about to exclude.
+function findHiddenTopDirs(projectRoot, noiseDirs) {
+    const files = listAnalyzedFiles(projectRoot, [...OWN_FILES, ...noiseDirs.map((n) => `${n}/**`)]).map((f) => toProjectRelativePosix(f, projectRoot));
+    const names = new Set();
+    for (const f of files) {
+        const [first] = f.split("/");
+        if (first !== undefined && first.startsWith(".") && f.includes("/"))
+            names.add(first);
+    }
+    return [...names].sort();
+}
+export async function init(projectRoot, rawDir) {
+    const dir = normalizeDirArg(rawDir);
+    const configPath = join(projectRoot, "archstrict.config.ts");
+    const generatedPath = join(projectRoot, "archstrict.types.ts");
+    const configWritten = !existsSync(configPath);
+    const messageLines = [];
+    if (!configWritten) {
+        // A re-run never touches the config, and never runs the fresh-run
+        // walk at all - only its own syntax is validated above; a re-run has
+        // nowhere to open a container into anyway, since the config on disk
+        // already says what's declared.
+        messageLines.push(`${configPath} already exists, left untouched`);
+        const notes = [];
+        if (dir !== undefined) {
+            const note = `the directory argument applies only when init writes a new archstrict.config.ts`;
+            messageLines.push(note);
+            notes.push(note);
+        }
+        const config = await loadConfig(configPath, undefined, DO_INIT);
+        // `?? []` is for the type checker, not runtime defense: loadConfig
+        // itself now rejects any loaded config whose declaredModules is
+        // missing, non-array, or holds a malformed entry, so this line never
+        // actually sees a bad shape. Config's own `declaredModules` field
+        // stays typed optional regardless (other Config values exist that
+        // never went through loadConfig), so the fallback keeps typechecking.
+        const moduleNames = [...new Set((config.declaredModules ?? []).map((m) => m.name))].sort();
+        writeFileSync(generatedPath, generatedFileContents(moduleNames));
+        messageLines.push(`wrote ${generatedPath}: ${plural(moduleNames.length, "module name", "module names")}, read from archstrict.config.ts`);
+        const groups = uncoveredGroups(projectRoot, config.declaredModules ?? [], config.exclude ?? [], config.surface ?? DEFAULT_SURFACE);
+        let doText = DO_CHECK;
+        if (groups.length > 0) {
+            const totalFiles = groups.reduce((sum, g) => sum + g.fileCount, 0);
+            messageLines.push(`not covered by any declaredModules entry: ${plural(totalFiles, "path", "paths")} (check reports each file in them as uncovered-module)`);
+            for (const g of groups) {
+                messageLines.push(g.kind === "dir" ? `  ${g.rel}/ (${plural(g.fileCount, "file", "files")})` : `  ${g.rel}`);
+                messageLines.push(`    declare: ${declaredModuleEntryText(g.entry)},`);
+                messageLines.push(`    or exclude: ${JSON.stringify(g.excludeGlob)},`);
+            }
+            doText =
+                "add each declare line above to declaredModules in archstrict.config.ts, or its exclude line to exclude if that path is not module content; then run archstrict init";
+        }
+        return {
+            configPath,
+            generatedPath,
+            configWritten,
+            opened: "",
+            moduleNames,
+            hiddenDirs: [],
+            noiseDirs: [],
+            testFileExcludes: [],
+            uncovered: groups,
+            notes,
+            messageLines,
+            doText,
+        };
+    }
+    const { opened, rootLabel, noiseDirs, testFileExcludes, exclude, containerGroups, topGroups } = freshRun(projectRoot, dir);
+    writeFileSync(configPath, configText(opened, containerGroups, topGroups, exclude, noiseDirs, testFileExcludes));
+    const config = await loadConfig(configPath, undefined, DO_INIT);
+    const moduleNames = [...new Set((config.declaredModules ?? []).map((m) => m.name))].sort();
+    writeFileSync(generatedPath, generatedFileContents(moduleNames));
+    messageLines.push(`wrote ${configPath}`, `wrote ${generatedPath}`);
+    const allGroups = [...containerGroups, ...topGroups];
+    messageLines.push(`declared ${plural(allGroups.length, "module", "modules")}, one per directory that holds TypeScript source and one per TypeScript source file:`);
+    if (opened !== "")
+        messageLines.push(`  ${opened}/: ${countLabel(containerGroups)}`);
+    if (topGroups.length > 0) {
+        const label = opened !== "" ? `outside ${opened}/` : rootLabel;
+        const names = topGroups.map((g) => g.entry.name).join(", ");
+        messageLines.push(`  ./ (${label}): ${countLabel(topGroups)}: ${names}`);
+    }
+    const hiddenDirs = findHiddenTopDirs(projectRoot, noiseDirs);
+    if (hiddenDirs.length > 0) {
+        messageLines.push(`excluded ${plural(hiddenDirs.length, "hidden directory", "hidden directories")} that ${hiddenDirs.length === 1 ? "holds" : "hold"} TypeScript source: ${hiddenDirs.map((n) => `${n}/`).join(", ")}`);
+    }
+    if (noiseDirs.length > 0) {
+        messageLines.push(`excluded ${plural(noiseDirs.length, "noise directory", "noise directories")} found on disk: ${noiseDirs.map((n) => `${n}/`).join(", ")}`);
+    }
+    if (testFileExcludes.length > 0) {
+        const parts = testFileExcludes.map((t) => `${t.label} (${plural(t.fileCount, "file", "files")})`).join(", ");
+        messageLines.push(`excluded ${plural(testFileExcludes.length, "test-file pattern", "test-file patterns")} found on disk: ${parts}`);
+    }
+    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 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,
+        configWritten,
+        opened,
+        moduleNames,
+        hiddenDirs,
+        noiseDirs,
+        testFileExcludes,
+        uncovered: [], // a fresh run's own groups always cover every analyzed file, by construction
+        notes,
+        messageLines,
+        doText: DO_CHECK,
+    };
+}

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 };
+}