archstrict 0.0.0 → 0.2.0

package/dist/rules/public-surface.js

@@ -0,0 +1,100 @@
+// Responsibility: rule 1, the public-surface bypass. A module is private by
+// default, the same posture Bazel's build visibility takes: an import from
+// outside a module that reaches a file other than that module's configured
+// public surface is a violation, and a module with no surface file present
+// is entirely private, so every external import into it violates.
+// This counts a type-only (`import type`) edge the same as a value edge:
+// reaching an internal file for its types alone still reaches past the
+// public surface (module-graph.ts's own header has the contrasting
+// decision for cycles).
+// Boundary: pure predicate over a ModuleGraph's cross-module edges. No I/O,
+// no output formatting (that is the `check` verb's job), no todo handling
+// (that is `todo`'s job).
+import { compileGlob } from "../classify.js";
+import {} from "../module-graph.js";
+const BECAUSE = "a module's public surface is its only public surface; everything else is private";
+// A friend exception (ArchUnit's term): the target file is public to
+// exactly the importers `from` matches, private to everyone else - unlike
+// `surface`, which is public to every importer equally. Checked only once
+// a bypass candidate is already known (surface itself didn't match), the
+// same order rule 1's own violation-vs-suppression logic already follows.
+function isExemptedByFriend(edge, targetModule, relativePath) {
+    const targetRel = relativePath(edge.resolvedFile);
+    const fromRel = relativePath(edge.fromFile);
+    return targetModule.friends.some((friend) => compileGlob(friend.fileGlob).test(targetRel) && compileGlob(friend.from).test(fromRel));
+}
+// Every violation this rule returns is reported at `edge.fromFile` (the
+// importing file) - never at the target module's own directory or any
+// other file. `focus`, when given, is check()'s own realpath'd target for
+// a `check <file>` run: filtering `graph.crossModuleEdges` down to the
+// ones whose `fromFile` is that exact file, before this rule ever builds a
+// Violation object (evidence/do strings, both built by concatenation, are
+// this rule's own real cost on a large project), gives back exactly the
+// set `filterToFile` would keep from the unscoped result - the same
+// (edge -> violation) mapping runs either way, only over fewer edges.
+// `edge.fromFile` is compared directly, not through `resolve()`: every
+// file in `graph.crossModuleEdges` is already an absolute, real path (the
+// module graph builds it that way), the same invariant `filterToFile`
+// itself already trusts before comparing a violation's own `path`.
+export function checkPublicSurfaceBypass(graph, focus) {
+    const violations = [];
+    const edges = focus === undefined ? graph.crossModuleEdges : graph.crossModuleEdges.filter((e) => e.fromFile === focus);
+    for (const edge of edges) {
+        const targetModule = graph.modules.get(edge.toModule);
+        if (targetModule === undefined)
+            continue; // resolved outside any module; not this rule's concern
+        if (targetModule.surfaceFiles.includes(edge.resolvedFile))
+            continue; // reached the public surface itself
+        if (isExemptedByFriend(edge, targetModule, graph.relativePath))
+            continue;
+        violations.push(violationFor(edge, targetModule.name, targetModule.surfaceFiles, targetModule.surfaceName, 
+        // A file module has nowhere to "add a index.ts". The relative path
+        // is the file the glob already names, so the fix can point at it.
+        targetModule.rootIsFile ? graph.relativePath(targetModule.dir) : undefined));
+    }
+    // `graph.crossModuleEdges` 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
+    // so this rule's own output stays stable regardless of it, by the same
+    // (path, line, column) a reader would scan a file top to bottom.
+    // Code-unit order (`<`/`>`), not localeCompare: a locale-aware compare
+    // can order the same two paths differently on different machines.
+    return violations.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0) || a.line - b.line || a.column - b.column);
+}
+function violationFor(edge, targetModuleName, surfaceFiles, surface, 
+// Set when the module root is a file. Undefined for a directory module,
+// whose remediation still names `<module>/<surface>`.
+fileModuleRel) {
+    const surfaceList = Array.isArray(surface) ? surface : [surface];
+    // Singular reads exactly as before (existing messages, unchanged);
+    // plural names every real, configured entry point instead of picking
+    // one arbitrarily.
+    const surfaceDisplay = surfaceList.join(", ");
+    const addArticle = surfaceList.length === 1 ? "a" : "one of";
+    const importTargets = surfaceList.map((s) => `${targetModuleName}/${s}`).join(", ");
+    const evidence = surfaceFiles.length === 0
+        ? `'${edge.specifier}' resolved to module '${targetModuleName}', which has no ${surfaceDisplay}`
+        : `'${edge.specifier}' resolved to a file inside module '${targetModuleName}' other than its ${surfaceDisplay}`;
+    // `<module>/` is a directory. A glob that names one file has no such
+    // directory, so the fix names that file instead of telling the reader
+    // to add a surface file inside the module name.
+    const doText = fileModuleRel !== undefined
+        ? surfaceFiles.length === 0
+            ? `set surface on '${targetModuleName}' to match ${fileModuleRel}, or stop importing it; this module is that file, not a directory`
+            : `import from ${fileModuleRel} instead, or add the needed export there`
+        : surfaceFiles.length === 0
+            ? `add ${addArticle} ${surfaceDisplay} to ${targetModuleName}/ naming what it exports`
+            : `import from ${importTargets} instead, or add the needed export there`;
+    return {
+        rule: "public-surface-bypass",
+        path: edge.fromFile,
+        line: edge.fromPosition.line,
+        column: edge.fromPosition.column,
+        evidence,
+        because: BECAUSE,
+        do: doText,
+        todoModule: targetModuleName,
+        specifier: edge.specifier,
+        target: edge.resolvedFile,
+    };
+}

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