archstrict 0.0.0 → 0.1.0

package/dist/verbs/init.js

@@ -0,0 +1,522 @@
+// 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 { 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. 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",
+} 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;
+    glob: 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. 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 .`;
+        messageLines.push(note);
+        notes.push(note);
+    }
+    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,
+    };
+}