archstrict 0.0.0 → 0.1.0

package/dist/rules/uncovered.js

@@ -0,0 +1,75 @@
+// Responsibility: rule 3, uncovered files (deptrac's --fail-on-uncovered,
+// generalized to v1's file-glob model). A real, in-scope file matching no
+// declared module fails the check - the implementation of the project's
+// own rule that a zero must never look like success when it is really an
+// omission (a check that silently skipped a file must not look like that
+// file passed). Under v0's directory-based discovery this was "a module
+// no kind names"; under v1's glob-based declaredModules, the same idea is
+// simpler and needs no pattern-matching of its own: module-graph.ts's own
+// `outsideFiles` already tracks exactly this (a file in scope, matching no
+// declared module) - this rule only reports it as a violation, one per
+// file, instead of silence.
+// Boundary: pure predicate over a ModuleGraph. No I/O, no output formatting;
+// grouping the uncovered files into one paste-ready declaredModules
+// suggestion per directory (or per loose file) is module-candidates.ts's
+// job, shared with init's re-run and `archstrict rules <path>` so all three
+// print the identical entry text for the same file.
+import {} from "../module-graph.js";
+import { groupForRelFile, suggestUncovered, suggestionDoText } from "../module-candidates.js";
+const BECAUSE = "a file matching no declared module is unchecked, not passing";
+// `group` is the caller's own suggestion for this file (from
+// `suggestUncovered`/`groupForRelFile`) - a bare declaredModules entry with
+// no `surface` would make a single-file module entirely private (its
+// default surface, index.ts, resolves to a different file), so the do:
+// text always carries the file's own name as `surface` for a file group.
+export function uncoveredViolationFor(file, rootDir, group) {
+    // `path` stays absolute (a location every other rule's own `path`
+    // points at) - only the glob suggested in `do` needs to be
+    // project-relative, since that's a value meant to be pasted directly
+    // into declaredModules[].glob or exclude, both of which are always
+    // project-relative (config.md).
+    return {
+        rule: "uncovered-module",
+        path: file,
+        line: 1,
+        column: 1,
+        evidence: `'${file}' is in scope but matches no declared module`,
+        because: BECAUSE,
+        do: suggestionDoText(group),
+    };
+}
+// Every violation this rule returns is reported at `file` itself - any
+// outside file at all, not one fixed path the way config.configPath-only
+// rules report - but unlike rule 1's edges, an outside file's own
+// naming/grouping (`suggestUncovered`, `nameCandidates`) is NOT
+// independent per file: a group's own name can depend on colliding with
+// ANOTHER group's on-disk name (module-candidates.ts's own
+// `nameCandidates`), computed over every outside file at once. Narrowing
+// `relFiles` down to just the focus file before grouping would compute
+// that collision check against the wrong, smaller universe and could
+// silently pick a different (wrong) name than the unscoped run - so
+// `suggestUncovered` still runs over the WHOLE `relFiles` list regardless
+// of `focus`, the same full-graph computation checkCycles also keeps.
+// `focus`, when given, only skips building a Violation object (and its
+// evidence/do strings) for a file whose own path isn't the focus file -
+// `file` is already an absolute, real path (module-graph.ts's own
+// `outsideFiles`), so it's compared directly, the same invariant rule 1's
+// own comment documents.
+export function checkUncoveredModules(graph, config, focus) {
+    const relFiles = graph.outsideFiles.map(graph.relativePath);
+    const groups = suggestUncovered(relFiles, config.declaredModules ?? []);
+    // `graph.outsideFiles` follows the edge build's own walk order (rootNames
+    // order - a directory scan, not a promise about reading order across
+    // files), not a promise about output order - sorted here by path so
+    // this rule's own output stays stable regardless of it.
+    return graph.outsideFiles.flatMap((file, i) => {
+        if (focus !== undefined && file !== focus)
+            return [];
+        const group = groupForRelFile(relFiles[i], groups);
+        // Every file in `relFiles` was grouped by the same call, so a match
+        // always exists - `suggestUncovered` never drops a file it was given.
+        return [uncoveredViolationFor(file, graph.rootDir, group)];
+        // Code-unit order (`<`/`>`), not localeCompare: a locale-aware compare
+        // can order the same two paths differently on different machines.
+    }).sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}

package/dist/todo-migration.js

@@ -0,0 +1,112 @@
+// Responsibility: reads the per-module todo layout archstrict wrote before
+// the single-file archstrict.todo.json existed - one archstrict.todo.json
+// inside each directory module, one <file>.archstrict.todo.json beside each
+// single-file module, and a root .archstrict-todo-initialized marker - so
+// todo.ts can fold it into the new file once, and check.ts can still pass
+// on a project that adopted archstrict under the old layout and hasn't run
+// `archstrict todo` since.
+// Boundary: reading and detecting the OLD layout only. The new layout
+// lives in todo-store.ts, which this module depends on but never the
+// reverse. Slated for removal once the old layout is old enough that no
+// adopted project could still be on it - the first release after this one.
+import { existsSync, readFileSync, statSync, unlinkSync } from "node:fs";
+import { basename, dirname, isAbsolute, join } from "node:path";
+import { toProjectRelativePosix } from "./module-graph.js";
+import { todoFilePath } from "./todo-store.js";
+export const LEGACY_MARKER_NAME = ".archstrict-todo-initialized";
+function legacyMarkerPath(projectRoot) {
+    return join(projectRoot, LEGACY_MARKER_NAME);
+}
+function pathIsFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+// Mirrors the pre-migration `todoPath`: a directory module keeps its todo
+// inside itself; a single-file module (the glob names one file, with no
+// directory of its own to hold a sibling archstrict.todo.json) keeps it
+// beside the file, named from the file's own basename.
+function legacyModuleTodoPath(moduleDir) {
+    if (pathIsFile(moduleDir))
+        return join(dirname(moduleDir), `${basename(moduleDir)}.archstrict.todo.json`);
+    return join(moduleDir, "archstrict.todo.json");
+}
+// A legacy entry's own stored `path` (and, for public-surface-bypass,
+// `target`) is project-relative UNLESS it was frozen by an archstrict old
+// enough to have stored the raw absolute form - normalized here the same
+// way the pre-migration readTodo already did, so a file this old still
+// matches today's algorithm without a dedicated migration step of its own.
+function normalizeLegacyEntry(entry, projectRoot) {
+    const path = isAbsolute(entry.path) ? toProjectRelativePosix(entry.path, projectRoot) : entry.path;
+    const target = entry.target !== undefined && isAbsolute(entry.target)
+        ? toProjectRelativePosix(entry.target, projectRoot)
+        : entry.target;
+    return target === undefined ? { ...entry, path } : { ...entry, path, target };
+}
+function readLegacyModuleTodo(moduleDir, projectRoot) {
+    const p = legacyModuleTodoPath(moduleDir);
+    if (!existsSync(p))
+        return [];
+    const entries = JSON.parse(readFileSync(p, "utf8")).entries;
+    // Old entries carried a `fingerprint` field that today's shape drops
+    // (todo-store.ts's own comment on why it's no longer stored) - stripped
+    // here rather than carried forward into the new file.
+    return entries.map((e) => {
+        const { fingerprint: _fingerprint, ...rest } = e;
+        return normalizeLegacyEntry(rest, projectRoot);
+    });
+}
+// `moduleDirs` - a Map<name, dir> - comes from the live module graph (the
+// caller already built one for `check`/`todo`'s own run), not from
+// re-declaring modules here: a module renamed or removed since the old
+// layout was written is exactly the case this function cannot help with
+// (see entriesByModule's own comment), and the caller decides what happens
+// to entries under a name this run no longer declares.
+export function readLegacyTodoState(projectRoot, moduleDirs) {
+    // A module whose own glob covers the project root itself (e.g. "**")
+    // has its legacy per-module path (join(dir, "archstrict.todo.json"))
+    // equal to the new single file's own path - todo-store.ts's own
+    // readTodoFile already treats a file at this path with no schemaVersion
+    // as "the new shape isn't present" and returns undefined so this
+    // function runs at all. That file must never be queued for deletion:
+    // freezeOrPrune writes the migrated, schema-versioned content to this
+    // SAME path before deleteLegacyTodoFiles ever runs, and deleting it
+    // afterward would erase the migration this run just did, not an old
+    // file left behind by it.
+    const newFilePath = todoFilePath(projectRoot);
+    const entriesByModule = new Map();
+    const filesToDelete = [];
+    // Counts every legacy file FOUND, even the one colliding path excluded
+    // from filesToDelete above - `present` must stay true for that case too
+    // (the project genuinely was on the old layout), not fall back to only
+    // filesToDelete's own length, which the collision deliberately excludes.
+    let legacyFilesFound = 0;
+    for (const [name, dir] of moduleDirs) {
+        const p = legacyModuleTodoPath(dir);
+        if (!existsSync(p))
+            continue;
+        legacyFilesFound++;
+        if (p !== newFilePath)
+            filesToDelete.push(p);
+        const entries = readLegacyModuleTodo(dir, projectRoot);
+        if (entries.length > 0)
+            entriesByModule.set(name, entries);
+    }
+    const marker = legacyMarkerPath(projectRoot);
+    const markerPresent = existsSync(marker);
+    if (markerPresent)
+        filesToDelete.push(marker);
+    return { entriesByModule, filesToDelete, present: markerPresent || legacyFilesFound > 0 };
+}
+// Deletes every legacy file this run found, once the new single file has
+// already been written - never before, so a crash between the two leaves
+// the old layout still fully readable rather than silently dropping debt.
+export function deleteLegacyTodoFiles(files) {
+    for (const f of files) {
+        if (existsSync(f))
+            unlinkSync(f);
+    }
+}

package/dist/todo-store.js

@@ -0,0 +1,434 @@
+// Responsibility: the on-disk shape of the project's one frozen-violation
+// file (archstrict.todo.json, at the project root) and the identity
+// (fingerprint) that ties a todo entry to a violation across runs. Shared
+// by check.ts (suppresses a violation whose fingerprint is already frozen,
+// and flags a todo entry that matches nothing as stale) and todo.ts
+// (writes the file) so neither has to depend on the other - both depend
+// on this instead.
+// Boundary: file I/O, the single-file shape, and the fingerprint's own
+// definition only. No rule logic, no freeze/prune policy (that's todo.ts's
+// job), no migration policy (that's todo-migration.ts's job, kept out of
+// this file so it can be deleted whole after the first release).
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { isAbsolute, join } from "node:path";
+import ts from "typescript";
+import { REFERENCED_BY_MARKER } from "./rules/type-leak.js";
+import { ReportError } from "./report-error.js";
+import { toProjectRelativePosix } from "./module-graph.js";
+// Identity for a violation across runs: rule, importing path, and the
+// evidence text — no line number (a line moving is not a new violation;
+// archspec's own fingerprint makes the same choice). Three rules replace
+// `path` and/or `evidence` with something narrower, each because the
+// literal field can change for a reason that has nothing to do with
+// whether the underlying debt is still the same edge:
+//
+// "cycle": `path` is `firstEdge.fromFile` — the file of one arbitrary edge
+// in the cycle, an implementation detail of which edge the shortest-path
+// search happened to return first, not the cycle's own identity. The
+// cycle itself (`evidence`, e.g. "a -> b -> c -> a") is the identity; if
+// that one file moved but the same cycle still existed, including `path`
+// would change the fingerprint and the frozen entry would go stale for a
+// cycle that never actually changed.
+//
+// "type-leak": `path` is the surface file whose declaration site sorts
+// earliest among however many surface files the leak's own module has -
+// an accident of which surface file a later one happens to be added
+// alongside, not part of the leak's own identity (module, internal type,
+// and its declaring file already fully identify it, and all three appear
+// in evidence's own stable prefix - see stableEvidence below). A module
+// moving from one surface file to two, with the second sorting earlier,
+// would otherwise re-anchor `path` and stale an unrelated, still-real leak.
+//
+// Every other rule's `path` names the real thing the violation is about
+// (the importing file, or the config file), so only these two are
+// excluded. Hashed so a sortable, stable key is short regardless of how
+// long the evidence text is - buildTodoIndex's own comment covers why
+// matching itself never trusts a stored string.
+//
+// `stableEvidence` additionally strips a rule's own known-mutable slice of
+// `evidence` before it's hashed, for two rules:
+//
+// - "type-leak": evidence embeds a mutable, informational list of every
+//   exported symbol CURRENTLY referencing a leaked internal type, after
+//   REFERENCED_BY_MARKER - not part of the leak's own identity. Without
+//   stripping it, one more real caller of an already-frozen leak appearing
+//   would change the fingerprint and reopen a frozen entry for a leak that
+//   hasn't newly appeared - measured directly: freezing a leak referenced
+//   by one export, then adding a second real export referencing the same
+//   internal type, produced both a stale-todo violation for the old entry
+//   and a fresh, unfrozen one for what is still the same leak.
+// - "tag-order": evidence embeds the full configured sequence
+//   (`(<namespace> sequence: a -> b -> c)`) purely to explain why the edge
+//   is forbidden - a value added anywhere in that sequence, even one this
+//   edge's own two layers never touch, changes the text without changing
+//   which edge is forbidden or why. Stripped back to the sentence naming
+//   the specifier and the two real layers it connects.
+//
+// A fourth rule, public-surface-bypass, doesn't fit this "trim the
+// evidence" shape at all: its evidence names the target module and
+// whether that module has a surface, and BOTH change when that one
+// module (not evidence's own surrounding text) gains a surface - not a
+// mutable suffix to strip, but a different sentence template entirely.
+// See `bypassIdentity` below for why it keys off structured fields
+// instead.
+const TAG_ORDER_SEQUENCE_MARKER = " sequence: ";
+function stableEvidence(rule, evidence) {
+    if (rule === "type-leak") {
+        const i = evidence.indexOf(REFERENCED_BY_MARKER);
+        return i === -1 ? evidence : evidence.slice(0, i);
+    }
+    if (rule === "tag-order") {
+        // rules/constraints.ts's own template puts this clause last, wrapped
+        // in one paren pair with no nested parens - trimming from the LAST
+        // "(" before the marker keeps `sourceLayer -> targetLayer` (still text
+        // before the marker) intact while dropping only the sequence list.
+        const markerAt = evidence.indexOf(TAG_ORDER_SEQUENCE_MARKER);
+        if (markerAt === -1)
+            return evidence;
+        const openParenAt = evidence.lastIndexOf("(", markerAt);
+        return openParenAt === -1 ? evidence : evidence.slice(0, openParenAt).trimEnd();
+    }
+    return evidence;
+}
+function pathExcludedFromKey(rule) {
+    return rule === "cycle" || rule === "type-leak";
+}
+// `path`/`target` MUST be project-relative before either reaches
+// fingerprintOf - never the raw, absolute form a live violation's own
+// `path`/`target` field actually holds. An absolute path is machine- and
+// checkout-specific (a different clone, a different CI runner, even the
+// same machine's own `/tmp` vs `/private/tmp`), so baking one into a key
+// that gets compared across process runs - the whole point of a todo file
+// - would silently stop matching the moment either side ran somewhere
+// else. Every caller (todo.ts's freeze/prune, check.ts's own matching,
+// simulate.ts's and fix.ts's live-vs-live diffing) relativizes through
+// this one function rather than repeating the "only if target is present"
+// check inline.
+export function relativizeForTodo(v, relativePath) {
+    return v.target === undefined
+        ? { ...v, path: relativePath(v.path) }
+        : { ...v, path: relativePath(v.path), target: relativePath(v.target) };
+}
+// public-surface-bypass's own evidence names the target module and
+// whether THAT module has a surface - true facts, but ones that read
+// differently the moment this bypass's own target module gains or loses
+// a surface (or its own `surface` config changes), even though the edge
+// itself (which file imports which file, through which specifier) never
+// moved. specifier/target are edge-intrinsic instead: the same import
+// into the same resolved file is the same debt regardless of what
+// evidence's own sentence says today. Returns undefined for a rule this
+// doesn't apply to, or for an entry migrated from before these fields
+// existed (readTodoFile never invents them).
+function bypassIdentity(v) {
+    if (v.rule !== "public-surface-bypass" || v.specifier === undefined || v.target === undefined)
+        return undefined;
+    return { specifier: v.specifier, target: v.target };
+}
+export function fingerprintOf(v) {
+    const identity = bypassIdentity(v);
+    const key = identity !== undefined
+        ? `${v.rule}\n${v.path}\n${identity.specifier}\n${identity.target}`
+        : pathExcludedFromKey(v.rule)
+            ? `${v.rule}\n${stableEvidence(v.rule, v.evidence)}`
+            : `${v.rule}\n${v.path}\n${stableEvidence(v.rule, v.evidence)}`;
+    return createHash("sha256").update(key).digest("hex").slice(0, 12);
+}
+// Migration only: a public-surface-bypass entry frozen before specifier/
+// target existed carries only the sentence violationFor built. Both of
+// evidence's own sentence shapes ("resolved to module 'm', which has no
+// ..." and "resolved to a file inside module 'm' other than its ...")
+// start with the same quoted specifier, so a small, fixed prefix
+// recovers it without knowing which shape produced this entry. This
+// parse exists only for an old entry with no stored `specifier` - a
+// fresh one always carries the field, and skips it entirely.
+function parseSpecifierFromLegacyBypassEvidence(evidence) {
+    const match = /^'(.+?)' resolved to /.exec(evidence);
+    return match?.[1];
+}
+export function buildTodoIndex(entries) {
+    const byFingerprint = new Map();
+    const byLegacyBypassKey = new Map();
+    for (const entry of entries) {
+        // Keyed by a FRESH recompute from the entry's own stored fields
+        // (already project-relative - readTodoFile normalizes a legacy
+        // absolute one before this ever runs), never by a stored fingerprint
+        // string: this file's own entries carry no such field at all - a
+        // stored copy could only ever drift from what matching actually needs
+        // (today's recompute), and a reader wanting to name an entry uses its
+        // own line in the file (ParsedTodoFile.entryLocation) instead. A value
+        // read from an entry migrated off the old per-module layout would
+        // anyway be a hash of whatever formula was current when it was
+        // frozen, not today's. A rule whose formula hasn't changed recomputes
+        // to the exact same value it always had; a rule whose formula changed
+        // (type-leak's own path exclusion, tag-order's own sequence-display
+        // exclusion) recomputes to the value it always should have had, with
+        // no rule-specific migration needed at all - stableEvidence is a pure
+        // function of the evidence text alone, unaffected by which archstrict
+        // version produced it. Only public-surface-bypass has a real
+        // pre-migration format (no stored specifier/target at all, not just a
+        // different formula over the same fields), which is what
+        // byLegacyBypassKey is for.
+        byFingerprint.set(fingerprintOf(entry), entry);
+        if (entry.rule === "public-surface-bypass" && entry.specifier === undefined) {
+            const specifier = parseSpecifierFromLegacyBypassEvidence(entry.evidence);
+            if (specifier !== undefined)
+                byLegacyBypassKey.set(`${entry.path}\n${specifier}`, entry);
+        }
+    }
+    return { byFingerprint, byLegacyBypassKey };
+}
+export const EMPTY_TODO_INDEX = { byFingerprint: new Map(), byLegacyBypassKey: new Map() };
+// The one place check.ts/todo.ts ask "does some entry in this index still
+// name this live violation" - a fingerprint lookup first (covers every
+// rule, recomputed identically on both sides - see buildTodoIndex's own
+// comment), falling back to the legacy (path, specifier) index only for a
+// public-surface-bypass violation, since that's the only rule with a
+// recorded pre-migration format at all. `relativePath` puts `v`'s own
+// (absolute) path/target into the same project-relative form entries are
+// always stored in, for BOTH branches - the primary lookup needs this
+// exactly as much as the fallback does (fingerprintOf never relativizes
+// on its own; see relativizeForTodo's own comment for why a caller must).
+export function findMatchingEntry(index, v, relativePath) {
+    const relativized = relativizeForTodo(v, relativePath);
+    const exact = index.byFingerprint.get(fingerprintOf(relativized));
+    if (exact !== undefined)
+        return exact;
+    if (relativized.rule !== "public-surface-bypass")
+        return undefined;
+    const identity = bypassIdentity(relativized);
+    if (identity === undefined)
+        return undefined;
+    return index.byLegacyBypassKey.get(`${relativized.path}\n${identity.specifier}`);
+}
+// Builds the on-disk row for a live violation: `path`/`target` relativized,
+// and specifier/target included only when the violation itself carries
+// them (public-surface-bypass). No stored fingerprint (see writeTodoFile's
+// own comment) - a reader that wants one recomputes it with fingerprintOf.
+// Used both to freeze a brand-new entry and to refresh one that survived
+// pruning, so an entry is always in the current format after either verb
+// runs over it, not just at first freeze.
+export function buildTodoEntry(v, relativePath) {
+    const relativized = relativizeForTodo(v, relativePath);
+    const base = { rule: relativized.rule, path: relativized.path, evidence: relativized.evidence };
+    return relativized.specifier !== undefined && relativized.target !== undefined
+        ? { ...base, specifier: relativized.specifier, target: relativized.target }
+        : base;
+}
+export const TODO_FILE_NAME = "archstrict.todo.json";
+// Bumped only if this shape itself ever changes again - readTodoFile
+// refuses a file stamped with a version it doesn't recognize (a newer
+// archstrict wrote it, or a hand edit changed the number) rather than
+// silently misreading it.
+export const TODO_SCHEMA_VERSION = 1;
+export function todoFilePath(projectRoot) {
+    return join(projectRoot, TODO_FILE_NAME);
+}
+function propertyKeyName(name) {
+    return ts.isStringLiteral(name) || ts.isIdentifier(name) ? name.text : undefined;
+}
+function locationOf(source, pos) {
+    const { line, character } = source.getLineAndCharacterOfPosition(pos);
+    return { line: line + 1, column: character + 1 };
+}
+const ENTRY_STRING_FIELDS = ["rule", "path", "evidence", "specifier", "target"];
+// `projectRoot`, when given, normalizes a raw absolute `path`/`target`
+// (a hand-written fixture, or a file from before entries were always
+// stored relative) into the project-relative POSIX form buildTodoEntry
+// always writes today - the same normalization the pre-single-file
+// readTodo already applied on every read, kept here so a caller never has
+// to special-case an absolute entry itself.
+function entryFromObjectLiteral(el, projectRoot) {
+    const fields = {};
+    for (const prop of el.properties) {
+        if (!ts.isPropertyAssignment(prop))
+            continue;
+        const key = propertyKeyName(prop.name);
+        if (key === undefined || !ts.isStringLiteral(prop.initializer))
+            continue;
+        if (ENTRY_STRING_FIELDS.includes(key))
+            fields[key] = prop.initializer.text;
+    }
+    if (fields.rule === undefined || fields.path === undefined || fields.evidence === undefined)
+        return undefined;
+    const path = projectRoot !== undefined && isAbsolute(fields.path) ? toProjectRelativePosix(fields.path, projectRoot) : fields.path;
+    const entry = { rule: fields.rule, path, evidence: fields.evidence };
+    if (fields.specifier !== undefined && fields.target !== undefined) {
+        // `specifier` is an import specifier, never a filesystem path - no
+        // normalization applies to it.
+        entry.specifier = fields.specifier;
+        entry.target = projectRoot !== undefined && isAbsolute(fields.target)
+            ? toProjectRelativePosix(fields.target, projectRoot)
+            : fields.target;
+    }
+    return entry;
+}
+function malformed(path) {
+    return new ReportError(`${path}: not a valid archstrict.todo.json (expected { schemaVersion, modules })`, "restore it from version control, or delete it and run archstrict todo to regenerate it");
+}
+// Parses archstrict.todo.json's own text directly (not JSON.parse, which
+// would give back plain values with no position information at all) -
+// exported so a Hegel round-trip test can feed writeTodoFile's own output
+// straight back in without going through the filesystem.
+export function parseTodoFileText(path, text, projectRoot) {
+    const source = ts.parseJsonText(path, text);
+    const root = source.statements[0]?.expression;
+    if (root === undefined || !ts.isObjectLiteralExpression(root))
+        throw malformed(path);
+    let schemaVersion;
+    const modules = new Map();
+    const moduleKeyLocation = new Map();
+    const entryLocation = new Map();
+    for (const prop of root.properties) {
+        if (!ts.isPropertyAssignment(prop))
+            continue;
+        const key = propertyKeyName(prop.name);
+        if (key === "schemaVersion" && ts.isNumericLiteral(prop.initializer)) {
+            schemaVersion = Number(prop.initializer.text);
+        }
+        else if (key === "modules" && ts.isObjectLiteralExpression(prop.initializer)) {
+            for (const moduleProp of prop.initializer.properties) {
+                if (!ts.isPropertyAssignment(moduleProp))
+                    continue;
+                const name = propertyKeyName(moduleProp.name);
+                if (name === undefined)
+                    continue;
+                moduleKeyLocation.set(name, locationOf(source, moduleProp.name.getStart(source)));
+                const entries = [];
+                if (ts.isArrayLiteralExpression(moduleProp.initializer)) {
+                    for (const el of moduleProp.initializer.elements) {
+                        if (!ts.isObjectLiteralExpression(el))
+                            continue;
+                        const entry = entryFromObjectLiteral(el, projectRoot);
+                        if (entry === undefined)
+                            continue;
+                        entries.push(entry);
+                        entryLocation.set(entry, locationOf(source, el.getStart(source)));
+                    }
+                }
+                modules.set(name, entries);
+            }
+        }
+    }
+    if (schemaVersion === undefined)
+        throw malformed(path);
+    if (schemaVersion !== TODO_SCHEMA_VERSION) {
+        throw new ReportError(`${path}: schemaVersion ${schemaVersion} is not supported (archstrict writes ${TODO_SCHEMA_VERSION})`, "upgrade archstrict, or delete the file and run archstrict todo to regenerate it");
+    }
+    return { schemaVersion, path, modules, moduleKeyLocation, entryLocation };
+}
+export function readTodoFile(projectRoot) {
+    const p = todoFilePath(projectRoot);
+    if (!existsSync(p))
+        return undefined;
+    const text = readFileSync(p, "utf8");
+    // JSON.parse first, ahead of ts.parseJsonText (used below only for
+    // positions): ts.parseJsonText recovers from a syntax error by parsing
+    // whatever prefix it can and returning the rest as an error node, rather
+    // than throwing - exactly the shape an unresolved git merge conflict
+    // marker or a truncated write leaves behind. Silently reading a partial
+    // parse would make `todo` write back only the entries that happened to
+    // survive the truncation, discarding the rest - the one failure mode
+    // this whole layout (one entry per line, so a genuine three-way merge
+    // resolves cleanly) exists to avoid. JSON.parse rejects that same input
+    // outright, so a real syntax error surfaces as a ReportError instead of
+    // silent data loss.
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        throw malformed(p);
+    }
+    // Undefined (not thrown) ONLY for the one shape a legacy file at this
+    // exact path can actually have: { entries: [...] }, no schemaVersion at
+    // all - a module whose own glob covers the project root itself (e.g.
+    // "**") has its legacy per-module path equal to this new file's own
+    // path (todo-store.ts's own todoFilePath and todo-migration.ts's own
+    // legacy path collide there). The caller (todo.ts, check.ts's own
+    // readCurrentTodo) then falls back to todo-migration.ts's own reader,
+    // which recognizes that shape. Anything else missing schemaVersion - a
+    // hand-edited `{ "modules": {...} }` that lost its version, a bare `{}`,
+    // any other malformed object - is NOT silently read as "absent": that
+    // would make the next `todo` run treat it as a genuine first run and
+    // overwrite it, discarding whatever was really there.
+    if (typeof raw === "object" && raw !== null && !("schemaVersion" in raw)
+        && Array.isArray(raw.entries)) {
+        return undefined;
+    }
+    if (typeof raw !== "object" || raw === null || !("schemaVersion" in raw))
+        throw malformed(p);
+    return parseTodoFileText(p, text, projectRoot);
+}
+// Plain code-unit order, never String.prototype.localeCompare: locale
+// collation (accents, case, punctuation folding) depends on the ICU data
+// installed on whichever machine runs `archstrict todo`, so two
+// developers on two locales could write two different byte orderings for
+// the identical entry set - defeating the whole point of a canonical,
+// diffable serialization.
+function codeUnitCompare(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function serializeEntry(entry) {
+    const ordered = entry.specifier !== undefined && entry.target !== undefined
+        ? { rule: entry.rule, path: entry.path, evidence: entry.evidence, specifier: entry.specifier, target: entry.target }
+        : { rule: entry.rule, path: entry.path, evidence: entry.evidence };
+    return JSON.stringify(ordered);
+}
+// The sort that makes two branches touching different modules produce a
+// text diff confined to those modules' own blocks, and two branches that
+// each delete a different entry from the SAME module merge cleanly (each
+// entry is its own line - deleting one line in each branch is an ordinary
+// three-way text merge, not a JSON-structural one): module names in
+// order, then within a module, entries by path, then rule, then
+// fingerprint (the same identity fingerprintOf already gives every entry,
+// reused here purely as a deterministic tiebreak - two entries that share
+// path AND rule but differ in specifier/target, e.g. two distinct
+// public-surface-bypass edges into the same target from the same importer
+// via two different specifiers, would otherwise sort in whatever order
+// they happened to arrive in), then the entry's own serialized line as a
+// final tiebreak (two type-leak entries can share path, rule, AND
+// fingerprint while differing only in evidence's own mutable
+// "referenced by" suffix - stableEvidence strips that suffix before
+// hashing, so it never enters the fingerprint at all).
+function sortedEntries(entries) {
+    return [...entries].sort((a, b) => {
+        return codeUnitCompare(a.path, b.path)
+            || codeUnitCompare(a.rule, b.rule)
+            || codeUnitCompare(fingerprintOf(a), fingerprintOf(b))
+            || codeUnitCompare(serializeEntry(a), serializeEntry(b));
+    });
+}
+// Hand-built, not JSON.stringify(file, null, 2): stringify's own pretty
+// printer wraps one entry object across several lines, which would make a
+// single added or removed field inside one entry look, to a line-based
+// diff/merge, like it touched every entry after it in the same array.
+// One compact JSON object per line keeps a diff (and a merge) confined to
+// exactly the lines that changed.
+export function serializeTodoFile(modulesByName) {
+    const names = [...modulesByName.keys()]
+        .filter((name) => (modulesByName.get(name)?.length ?? 0) > 0)
+        .sort(codeUnitCompare);
+    const lines = ["{", `  "schemaVersion": ${TODO_SCHEMA_VERSION},`, '  "modules": {'];
+    names.forEach((name, moduleIndex) => {
+        const entries = sortedEntries(modulesByName.get(name) ?? []);
+        lines.push(`    ${JSON.stringify(name)}: [`);
+        entries.forEach((entry, entryIndex) => {
+            lines.push(`      ${serializeEntry(entry)}${entryIndex < entries.length - 1 ? "," : ""}`);
+        });
+        lines.push(`    ]${moduleIndex < names.length - 1 ? "," : ""}`);
+    });
+    lines.push("  }", "}");
+    return lines.join("\n") + "\n";
+}
+// Always writes the file, even with an empty module map (a project with
+// no debt after its first run still gets one, so the ratchet's own state
+// - "todo has run" - stays visible on disk instead of looking identical
+// to "todo has never run"). Never deletes it: unlike the old per-module
+// file (which vanished the moment a module's own debt hit zero),
+// existence of the single root file IS the "first run happened" signal
+// now - see todo.ts's own firstRun check, which replaces the old
+// `.archstrict-todo-initialized` marker with this file's own existence.
+export function writeTodoFile(projectRoot, modulesByName) {
+    writeFileSync(todoFilePath(projectRoot), serializeTodoFile(modulesByName));
+}