archstrict 0.0.0 → 0.1.0

package/dist/rules/cycles.js

@@ -0,0 +1,257 @@
+import { withPointerSpecs } from "../config-pointer.js";
+const BECAUSE = "modules that import each other cannot be reasoned about, tested, or replaced independently";
+const STALE_BECAUSE = "an ignoredCycles entry naming no real cycle hides nothing - it is dead configuration, not a decision anyone can still judge";
+// A pair is lopsided when its minority direction is small in absolute
+// terms (survey: 1-3 edges covers ~63% of real minority sides) AND
+// dominated in relative terms (majority at least 3x minority) - see the
+// header comment above for why both conditions are required together.
+const MINORITY_MAX_EDGES = 3;
+const MAJORITY_MIN_RATIO = 3;
+// Real, project-relative file edges named in a lopsided pair's do: are
+// capped at 5, so a pathological future change to the threshold above
+// can't grow this list without bound. In practice the cap never binds
+// today: the minority side has at most MINORITY_MAX_EDGES edges, deduped
+// by (fromFile, resolvedFile) pair, so the displayed list is never
+// longer than 3.
+const MINORITY_FILE_EDGES_SHOWN = 5;
+// All real value edges (not type-only, already excludes same-module
+// edges via crossModuleEdges), grouped by ordered (from, to) module
+// pair - undeduped, unlike buildAdjacency's adjacency list, because a
+// lopsided-pair judgment needs the true edge count, not one
+// representative edge.
+function valueEdgesByOrderedPair(graph) {
+    const map = new Map();
+    for (const edge of graph.crossModuleEdges) {
+        if (edge.isTypeOnly)
+            continue;
+        const key = `${edge.fromModule}->${edge.toModule}`;
+        const list = map.get(key) ?? [];
+        list.push(edge);
+        map.set(key, list);
+    }
+    return map;
+}
+// The most lopsided pair among a component's members that has edges in
+// both directions, or undefined when none qualifies. Iterates pairs in
+// sorted module-name order and only replaces the running best on a
+// strictly higher ratio, so a tie keeps the alphabetically first pair -
+// a stable, deterministic tie-break, so re-running `check` always names
+// the same pair for the same graph. Ratios are compared by cross
+// multiplication, not floats, since edge counts are always small
+// integers and this must stay exact.
+function findMostLopsidedPair(component, edgesByPair) {
+    const sorted = [...component].sort();
+    let best;
+    for (let i = 0; i < sorted.length; i++) {
+        for (let j = i + 1; j < sorted.length; j++) {
+            const a = sorted[i];
+            const b = sorted[j];
+            const aToB = edgesByPair.get(`${a}->${b}`) ?? [];
+            const bToA = edgesByPair.get(`${b}->${a}`) ?? [];
+            if (aToB.length === 0 || bToA.length === 0)
+                continue; // not a pair with edges in both directions
+            const [minorityFrom, minorityTo, minorityEdges, majorityCount] = aToB.length <= bToA.length ? [a, b, aToB, bToA.length] : [b, a, bToA, aToB.length];
+            const minorityCount = minorityEdges.length;
+            if (minorityCount > MINORITY_MAX_EDGES)
+                continue;
+            if (majorityCount < minorityCount * MAJORITY_MIN_RATIO)
+                continue;
+            if (best === undefined || majorityCount * best.minorityEdges.length > best.majorityCount * minorityCount) {
+                best = { minorityFrom, minorityTo, minorityEdges, majorityCount };
+            }
+        }
+    }
+    return best;
+}
+function lopsidedDo(pair, relativePath) {
+    const fileEdges = [...new Set(pair.minorityEdges.map((e) => `${relativePath(e.fromFile)} -> ${relativePath(e.resolvedFile)}`))].sort().slice(0, MINORITY_FILE_EDGES_SHOWN).join(", ");
+    return `remove the ${pair.minorityEdges.length} import(s) from ${pair.minorityFrom} to ${pair.minorityTo} (${pair.minorityTo} imports ${pair.minorityFrom} ${pair.majorityCount} times, so ${pair.minorityFrom} -> ${pair.minorityTo} is likely the unintended direction): ${fileEdges}`;
+}
+// Smaller (fromFile, line, column) wins, by plain code-unit path compare -
+// a total order independent of which edge the walk happened to visit
+// first, so the SAME representative edge is picked for a given (from, to)
+// module pair regardless of walk order (module-graph.ts's own edge build
+// makes no promise about that order - see its own header).
+function isEarlierEdge(a, b) {
+    if (a.fromFile !== b.fromFile)
+        return a.fromFile < b.fromFile;
+    if (a.fromPosition.line !== b.fromPosition.line)
+        return a.fromPosition.line < b.fromPosition.line;
+    return a.fromPosition.column < b.fromPosition.column;
+}
+function buildAdjacency(graph) {
+    const representativeByPair = new Map();
+    for (const edge of graph.crossModuleEdges) {
+        if (edge.isTypeOnly)
+            continue; // decision above: type-only edges don't count for cycles
+        const to = edge.toModule;
+        const pairKey = `${edge.fromModule}->${to}`;
+        const existing = representativeByPair.get(pairKey);
+        if (existing === undefined || isEarlierEdge(edge, existing.edge)) {
+            representativeByPair.set(pairKey, { from: edge.fromModule, to, edge });
+        }
+    }
+    const adjacency = new Map();
+    for (const { from, to, edge } of representativeByPair.values()) {
+        const list = adjacency.get(from) ?? [];
+        list.push({ to, edge });
+        adjacency.set(from, list);
+    }
+    // Sorted by target module name - shortestCycleFrom's own BFS explores
+    // each node's neighbors in this list's order, so a tie between two
+    // equally short paths must also not depend on edge walk order. The
+    // reported cycle (which module, which file, which line) must be the
+    // same every run on the same graph, not an accident of file walk order.
+    for (const list of adjacency.values())
+        list.sort((a, b) => (a.to < b.to ? -1 : a.to > b.to ? 1 : 0));
+    return adjacency;
+}
+// Tarjan's algorithm: strongly connected components of size > 1 are cycles
+// (a module-level self-loop cannot occur here — crossModuleEdges already
+// excludes same-module edges).
+function stronglyConnectedComponents(nodes, adjacency) {
+    let index = 0;
+    const indices = new Map();
+    const lowlinks = new Map();
+    const onStack = new Set();
+    const stack = [];
+    const components = [];
+    function strongconnect(v) {
+        indices.set(v, index);
+        lowlinks.set(v, index);
+        index++;
+        stack.push(v);
+        onStack.add(v);
+        for (const { to: w } of adjacency.get(v) ?? []) {
+            if (!indices.has(w)) {
+                strongconnect(w);
+                lowlinks.set(v, Math.min(lowlinks.get(v), lowlinks.get(w)));
+            }
+            else if (onStack.has(w)) {
+                lowlinks.set(v, Math.min(lowlinks.get(v), indices.get(w)));
+            }
+        }
+        if (lowlinks.get(v) === indices.get(v)) {
+            const component = [];
+            let w;
+            do {
+                w = stack.pop();
+                onStack.delete(w);
+                component.push(w);
+            } while (w !== v);
+            components.push(component);
+        }
+    }
+    for (const node of nodes) {
+        if (!indices.has(node))
+            strongconnect(node);
+    }
+    return components;
+}
+// Shortest simple cycle that visits `start`, using only edges within
+// `component` (BFS over paths, since module graphs are small — v0 does not
+// need this to scale past a few dozen modules).
+function shortestCycleFrom(start, component, adjacency) {
+    const queue = [{ node: start, path: [start], edges: [] }];
+    while (queue.length > 0) {
+        const { node, path, edges } = queue.shift();
+        for (const { to, edge } of adjacency.get(node) ?? []) {
+            if (!component.has(to))
+                continue;
+            if (to === start)
+                return { modules: [...path, start], edges: [...edges, edge] };
+            if (path.includes(to))
+                continue; // simple cycle only; don't revisit a node
+            queue.push({ node: to, path: [...path, to], edges: [...edges, edge] });
+        }
+    }
+    // Invariant, not error handling: every node in a strongly connected
+    // component of size > 1 lies on some cycle within it, so this branch is
+    // unreachable for a genuine SCC. It only fires if `component` was built
+    // wrong (e.g. from a stale or mismatched adjacency).
+    throw new Error(`no cycle found from ${start} within its own strongly connected component`);
+}
+// Reports at `firstEdge.fromFile` - one arbitrary edge inside the cycle,
+// not the cycle's own identity (this file's header comment on
+// fingerprints has more). "Any file" in the sense that a `check <file>`
+// run's own focus could name any module in a cycle, or none - and the
+// SCC computation itself has no per-file shortcut (a cycle is a property
+// of the whole component, not of one edge), so this rule always runs its
+// current, whole-project logic; runRules narrows its OWN returned
+// violations down to the focus file afterward, the same as it does for
+// every rule this file doesn't itself scope.
+export function checkCycles(graph, config) {
+    const adjacency = buildAdjacency(graph);
+    const nodes = [...graph.modules.keys()];
+    const components = stronglyConnectedComponents(nodes, adjacency).filter((c) => c.length > 1);
+    const ignoredCycles = config?.ignoredCycles ?? [];
+    const valueEdgesByPair = valueEdgesByOrderedPair(graph);
+    const violations = [];
+    for (const component of components) {
+        const memberSet = new Set(component);
+        // A pair named in either order is ignored the moment both its modules
+        // are in the same component - the whole component, not just that one
+        // edge, since a cycle spanning more than two modules is one finding
+        // either way (this rule reports one violation per component already).
+        const ignored = ignoredCycles.some(([a, b]) => memberSet.has(a) && memberSet.has(b));
+        if (ignored)
+            continue;
+        const sorted = [...component].sort();
+        const anchor = sorted[0];
+        const { modules, edges } = shortestCycleFrom(anchor, new Set(component), adjacency);
+        const firstEdge = edges[0];
+        const fileChain = edges
+            .map((e) => `${graph.relativePath(e.fromFile)} -> ${graph.relativePath(e.resolvedFile)}`)
+            .join(", ");
+        const breakCycleDo = `break the cycle at ${graph.relativePath(firstEdge.fromFile)} -> ${graph.relativePath(firstEdge.resolvedFile)} (module ${modules[0]} -> ${modules[1]}), or merge the modules involved - real import chain: ${fileChain}`;
+        // A lopsided pair's minority edges are the likely accident and the
+        // cheap fix, so they lead the do:; the general break-the-cycle advice
+        // stays as the fallback for when that guess is wrong.
+        const lopsided = findMostLopsidedPair(component, valueEdgesByPair);
+        const doText = lopsided === undefined
+            ? breakCycleDo
+            : `${lopsidedDo(lopsided, graph.relativePath)}; alternatively, ${breakCycleDo}`;
+        violations.push({
+            rule: "cycle",
+            path: firstEdge.fromFile,
+            line: firstEdge.fromPosition.line,
+            column: firstEdge.fromPosition.column,
+            evidence: modules.join(" -> "),
+            because: BECAUSE,
+            do: doText,
+            todoModule: anchor,
+        });
+    }
+    return violations;
+}
+// Reports at `config.configPath` - a fact about `ignoredCycles` itself,
+// not about any one file's own edge - so a `check <file>` run only ever
+// keeps this rule's own finding when `focus` is the config file; runRules'
+// own end-of-call filter (not this function) is what narrows it down.
+//
+// A declared pair not found together in any real strongly connected
+// component at all (ignored or not) is stale - checked against every
+// component, not just the ignored ones, since a pair that never cycled in
+// the first place is just as stale as one that used to but no longer does.
+export function checkStaleCycleExceptions(graph, config) {
+    const adjacency = buildAdjacency(graph);
+    const nodes = [...graph.modules.keys()];
+    const components = stronglyConnectedComponents(nodes, adjacency).filter((c) => c.length > 1);
+    const componentSets = components.map((c) => new Set(c));
+    const violations = [];
+    for (const [entryIndex, [a, b]] of (config.ignoredCycles ?? []).entries()) {
+        const stillCycles = componentSets.some((members) => members.has(a) && members.has(b));
+        if (stillCycles)
+            continue;
+        violations.push(withPointerSpecs({
+            rule: "stale-cycle-exception",
+            path: config.configPath,
+            line: 1,
+            column: 1,
+            evidence: `ignoredCycles entry ['${a}', '${b}'] names no real cycle`,
+            because: STALE_BECAUSE,
+            do: `remove ['${a}', '${b}'] from ignoredCycles in archstrict.config.ts`,
+        }, [{ pointer: `ignoredCycles[${entryIndex}]`, role: "fired" }]));
+    }
+    return violations;
+}

package/dist/rules/deprecated.js

@@ -0,0 +1,67 @@
+// Responsibility: rule 5, deprecated edges. archstrict.config.ts's
+// `deprecated` list records a from/to module edge with a declared `count`
+// and a mandatory `because`. The edge's actual count must never increase
+// (a real failure); a decrease only prompts updating `count` downward (an
+// informational suggestion, not a failure) — tach's deprecated-dependency
+// idea (warn, don't forbid) with "must not grow" added on top.
+// Boundary: pure predicate over a ModuleGraph and a Config. No I/O, no
+// output formatting. Does not suppress rule 1: a deprecated edge that also
+// bypasses its target's public surface is still a rule-1 violation —
+// deprecated means "shrinking," not "exempt from every other rule."
+import { assertDeprecatedModulesExist } from "../config.js";
+import { withPointerSpecs } from "../config-pointer.js";
+// A deprecated edge's own count is the number of import/export/dynamic-
+// import statements between the two named modules — what a reader would
+// count by hand — not the number of distinct files involved. import type
+// counts (same reasoning as rule 1: it still reaches the target module,
+// even for a type alone).
+function countEdges(graph, from, to) {
+    return graph.crossModuleEdges.filter((e) => e.fromModule === from && e.toModule === to).length;
+}
+// Both `violations` and `suggestions` report at `config.configPath` (a
+// declared from/to module pair's own actual count, not a single edge's
+// own file) - this rule always runs fully regardless of a `check <file>`
+// run's own focus, and `assertDeprecatedModulesExist`'s own validation
+// must run every time either way. runRules' own end-of-call filter keeps
+// or drops the returned VIOLATIONS depending on whether focus names the
+// config file - but never touches `suggestions`, which stays the full,
+// whole-project list on every run: `filterToFile` (check.ts) only ever
+// narrows `CheckResult.violations`, never `.suggestions`.
+export function checkDeprecatedEdges(graph, config) {
+    // Validated up front, same reasoning as assertKindPatternsSupported: a
+    // config error must not depend on which branch of this function happens
+    // to run first.
+    assertDeprecatedModulesExist(graph, config);
+    const violations = [];
+    const suggestions = [];
+    for (const [entryIndex, entry] of (config.deprecated ?? []).entries()) {
+        const actual = countEdges(graph, entry.from, entry.to);
+        if (actual > entry.count) {
+            violations.push(withPointerSpecs({
+                rule: "deprecated-edge-increased",
+                path: config.configPath,
+                line: 1,
+                column: 1,
+                evidence: `${entry.from} -> ${entry.to}: declared count ${entry.count}, actual ${actual}`,
+                because: entry.because,
+                do: `reduce ${entry.from} -> ${entry.to} back to ${entry.count} edges, or raise count in archstrict.config.ts and record why the increase was accepted`,
+            }, [{ pointer: `deprecated[${entryIndex}].count`, role: "fired" }]));
+        }
+        else if (actual > 0 && actual < entry.count) {
+            // actual === 0 is not reported here at all: the edge is gone
+            // entirely, not merely smaller, which is rule 4's more specific
+            // "this deprecation is now moot" case (checkEmptyRuleSet), not a
+            // count to update.
+            suggestions.push({
+                rule: "deprecated-edge-decreased",
+                path: config.configPath,
+                line: 1,
+                column: 1,
+                evidence: `${entry.from} -> ${entry.to}: declared count ${entry.count}, actual ${actual}`,
+                because: entry.because,
+                do: `update count to ${actual} for ${entry.from} -> ${entry.to} in archstrict.config.ts`,
+            });
+        }
+    }
+    return { violations, suggestions };
+}

package/dist/rules/empty-rule.js

@@ -0,0 +1,101 @@
+// Responsibility: rule 4, the empty rule set (ArchUnitTS's Empty Test
+// Protection). A configured rule that matches zero real things must not
+// look like a pass — the same "a zero can look like success when it is
+// really an omission" principle as rule 3, from the other direction: rule
+// 3 is "a file no declared module covers is a failure"; this is "a
+// declaration (a module, or a classify glob) that covers no real file is
+// a failure". Also reports allow lists that cover every real target value.
+// Boundary: a config-vs-graph consistency check, not an edge check. No
+// I/O, no output formatting.
+import { assertDeprecatedModulesExist } from "../config.js";
+import { compileGlob } from "../classify.js";
+import {} from "../module-graph.js";
+import { checkEdgesCoverage, checkExhaustiveAllow } from "./constraints.js";
+import { withPointerSpecs } from "../config-pointer.js";
+const BECAUSE = "a rule that checks nothing must not look like a pass";
+function violation(config, evidence, doText, pointer) {
+    return withPointerSpecs({
+        rule: "empty-rule-set",
+        path: config.configPath,
+        line: 1,
+        column: 1,
+        evidence,
+        because: BECAUSE,
+        do: doText,
+    }, [{ pointer, role: "fired" }]);
+}
+// Every finding here reports at `config.configPath` (see the Violation
+// type's own comment above) - a config-vs-graph consistency fact, never a
+// single file's own edge - so this rule always runs its current,
+// whole-config logic regardless of a `check <file>` run's own focus;
+// runRules' own end-of-call filter (not this function) is what keeps or
+// drops it depending on whether focus names the config file itself.
+export function checkEmptyRuleSet(graph, config) {
+    // Validated up front, same reasoning as ever: a config error must not
+    // depend on which branch runs first.
+    assertDeprecatedModulesExist(graph, config);
+    // No modules at all: not "a rule matched zero", but "nothing to check" -
+    // reported the same way (a violation, not a thrown error) so it fits
+    // the same 0-is-a-result shape as everything else `check` reports.
+    // Returned immediately rather than falling through to the classify loop
+    // below: with zero modules, every classify glob trivially matches
+    // nothing that belongs to any module either, so the loop would add one
+    // redundant violation per entry, all restating the same root cause.
+    if (graph.modules.size === 0) {
+        return [
+            violation(config, "no modules declared in declaredModules", "add at least one declaredModules entry in archstrict.config.ts", "declaredModules"),
+        ];
+    }
+    const violations = [];
+    // Every classify glob must match at least one real, in-scope file - the
+    // classification-layer's own version of "a kind that matches no
+    // module": a glob that matches nothing is a config typo or a stale
+    // entry, either way a rule that checks nothing must not look like a
+    // pass.
+    const allFiles = [...graph.modules.values()].flatMap((m) => m.files).concat(graph.outsideFiles);
+    for (const [entryIndex, entry] of (config.classify ?? []).entries()) {
+        const glob = compileGlob(entry.glob);
+        const matchesAny = allFiles.some((file) => glob.test(graph.relativePath(file)));
+        if (!matchesAny) {
+            violations.push(violation(config, `classify glob '${entry.glob}' matches no file in scope`, `remove this classify entry from archstrict.config.ts, or point its glob at real files`, `classify[${entryIndex}]`));
+        }
+    }
+    // A deprecated edge whose actual count has fallen to zero is not merely
+    // smaller (rule 5's "update count" suggestion) — the edge is gone
+    // entirely, so the entry itself is moot and checks nothing. Rule 5
+    // deliberately does not report this case (its own header explains why),
+    // so it belongs here instead: an empty-rule-set violation, not a count
+    // to shrink.
+    for (const [entryIndex, entry] of (config.deprecated ?? []).entries()) {
+        const actual = graph.crossModuleEdges.filter((e) => e.fromModule === entry.from && e.toModule === entry.to).length;
+        if (actual === 0) {
+            violations.push(violation(config, `deprecated edge '${entry.from} -> ${entry.to}' (declared count ${entry.count}) no longer exists`, `remove the '${entry.from} -> ${entry.to}' entry from deprecated in archstrict.config.ts`, `deprecated[${entryIndex}]`));
+        }
+    }
+    // An allowDeny/order/point rule whose own source/target combination
+    // never applies to any real edge in the graph is the constraint
+    // engine's own version of the same idea: a rule that structurally
+    // cannot fire must not look like a clean pass. This only catches the
+    // zero case. For an allow list, a genuine pass also needs a real target
+    // value outside the list, after the source-group exemption. Otherwise,
+    // the list guarantees a pass; the exhaustive-list check reports it below.
+    // rules.md explains why a nonzero clean result still needs a positive
+    // control, which these checks cannot replace.
+    const coverageIndices = { allowDeny: 0, order: 0, point: 0 };
+    for (const c of checkEdgesCoverage(graph, config)) {
+        const entryIndex = coverageIndices[c.kind]++;
+        if (c.evaluated === 0) {
+            violations.push(violation(config, `${c.kind} rule '${c.identifier}' matches no real edge in scope`, `remove or correct this ${c.kind} entry in archstrict.config.ts's edges - its own source/target never applies to any real edge this project has (a workspace-sibling import may resolve as an external package rather than a project tag; see rules.md)`, `edges.${c.kind}[${entryIndex}]`));
+        }
+    }
+    for (const { identifier, rule } of checkExhaustiveAllow(graph, config)) {
+        const entryIndex = (config.edges?.allowDeny ?? []).indexOf(rule);
+        violations.push(withPointerSpecs({
+            rule: "exhaustive-allow-list", path: config.configPath, line: 1, column: 1,
+            evidence: `allowDeny rule '${identifier}' allows every real target value with allow ${JSON.stringify(rule.allow)}`,
+            because: rule.because,
+            do: `narrow the allow list for '${identifier}' in archstrict.config.ts to a genuine subset of real target values, or remove the rule if it should forbid nothing today`,
+        }, [{ pointer: `edges.allowDeny[${entryIndex}].allow`, role: "fired" }]));
+    }
+    return violations;
+}

package/dist/rules/moves.js

@@ -0,0 +1,79 @@
+// Responsibility: propose ranked moves for existing tag-boundary violations using the real graph and config.
+// Boundary: decorates existing findings; never emits violations or applies edits.
+// Retag moves are deferred: shared classification globs can affect sibling files and every rule that uses those tags.
+// Such moves need a broader verification pass than these local proposals.
+import { classifyFile, classifyByDirectoryName } from "../classify.js";
+import {} from "../module-graph.js";
+import { computeAllowDeny, checkExhaustiveAllow, isExemptedByGlobPair, targetTagsInGraph } from "./constraints.js";
+export function computeMoves(violation, graph, config, context) {
+    if (violation.rule !== "tag-boundary")
+        return undefined;
+    const { edge, ruleIndex, violatingTag } = context;
+    const rules = config.edges?.allowDeny ?? [];
+    const rule = rules[ruleIndex];
+    if (!rule)
+        return undefined;
+    const prefix = `${rule.targetNamespace}:`;
+    const legal = rule.allow !== undefined ? new Set(rule.allow.map(value => `${prefix}${value}`)) :
+        new Set([...targetTagsInGraph(graph, config)].filter(tag => tag.startsWith(prefix) && tag !== rule.source &&
+            !(rule.deny ?? []).includes(tag.slice(prefix.length))));
+    // Use public surfaces as import targets; a module's full file list includes private implementation files.
+    // Proposing those files could trade a tag-boundary violation for the public-surface-bypass violation that rule 1 detects.
+    const surfaces = new Set();
+    for (const module of graph.modules?.values() ?? []) {
+        const tags = new Set(classifyByDirectoryName(graph.relativePath(module.dir), config.classifyByDirectoryName));
+        for (const surface of module.surfaceFiles) {
+            for (const tag of classifyFile(graph.relativePath(surface), config))
+                tags.add(tag);
+        }
+        if ([...tags].some(tag => legal.has(tag))) {
+            for (const surface of module.surfaceFiles)
+                surfaces.add(graph.relativePath(surface));
+        }
+    }
+    const moves = [];
+    if (surfaces.size > 0)
+        moves.push({ kind: "reroute", verified: false,
+            do: `consider importing from these public surfaces: ${JSON.stringify([...surfaces].sort())}; confirm the needed symbol is available` });
+    const from = graph.relativePath(edge.fromFile);
+    const to = edge.externalPackage === undefined ? graph.relativePath(edge.resolvedFile) : undefined;
+    // compileGlob treats a literal star as a wildcard and provides no escape mechanism.
+    // Such a path could silently exempt other pairs; omit the move rather than promise an exact exception we cannot guarantee.
+    if (to !== undefined && !from.includes("*") && !to.includes("*")) {
+        const entry = { from, to, because: "<author must state a real reason>" };
+        moves.push({ kind: "exception", widens: true,
+            verified: isExemptedByGlobPair(edge, [...rule.exceptions ?? [], entry], graph.relativePath),
+            do: `add ${JSON.stringify(entry)} to exceptions for allowDeny entry ${ruleIndex}; this exempts only this one edge pair` });
+    }
+    const value = violatingTag.slice(prefix.length);
+    const modified = rule.allow !== undefined ? { ...rule, allow: [...rule.allow, value] } :
+        { ...rule, deny: (rule.deny ?? []).filter(item => item !== value) };
+    // Verify widening with the real constraint and exhaustive-list checks; a shallow config copy preserves the caller's rules.
+    // This follows the empirical verification policy: a property test checks that expanding allow cannot add denied edges instead of assuming it.
+    const hypothetical = { ...config, edges: { ...config.edges,
+            allowDeny: rules.map((entry, index) => index === ruleIndex ? modified : entry) } };
+    const before = computeAllowDeny(graph, config).matches;
+    const after = computeAllowDeny(graph, hypothetical).matches;
+    const sameEdgeRule = (a, b) => a.edge === b.edge && a.ruleIndex === b.ruleIndex;
+    // Keep last-resort moves visible and name new findings from either check in creates.
+    // Hiding an imperfect option would conceal a real choice; labeling its consequences lets the reader assess it honestly.
+    const creates = new Set(after.filter(match => !before.some(old => sameEdgeRule(old, match))).map(match => match.violation.rule));
+    const beforeExhaustive = checkExhaustiveAllow(graph, config);
+    for (const finding of checkExhaustiveAllow(graph, hypothetical)) {
+        const index = hypothetical.edges.allowDeny.indexOf(finding.rule);
+        if (!beforeExhaustive.some(old => rules.indexOf(old.rule) === index && old.ruleId === finding.ruleId))
+            creates.add(finding.ruleId);
+    }
+    const move = {
+        kind: rule.allow !== undefined ? "widen-allow" : "widen-deny", widens: true,
+        // One import can carry several tags in the same namespace, such as synthesized pkg: tags.
+        // Admitting one value can leave another forbidden, so a proposed widening does not automatically verify the edge.
+        verified: !after.some(match => match.edge === edge && match.ruleIndex === ruleIndex),
+        do: rule.allow !== undefined ? `add ${JSON.stringify(value)} to allow for allowDeny entry ${ruleIndex}` :
+            `remove ${JSON.stringify(value)} from deny for allowDeny entry ${ruleIndex}`,
+    };
+    if (creates.size > 0)
+        move.creates = [...creates].sort();
+    moves.push(move);
+    return moves;
+}

package/dist/rules/must-be-empty.js

@@ -0,0 +1,52 @@
+// Responsibility: config.mustBeEmpty - archspec's own "empty component"
+// concept (a directory a team decided must hold no code at all, e.g.
+// vanilla_rails's own convention that app/services stays empty when a
+// project deliberately keeps rich models instead of service objects).
+// Distinct from rule 4 (empty-rule-set): that rule flags a RULE that
+// structurally cannot match anything; this one flags a real FILE existing
+// where the config says none should. A violation is any file matching the
+// glob at all - 0 matches is a clean pass, not silence, the same
+// convention every other rule here follows.
+// Boundary: pure predicate over a file list and a Config. No I/O of its
+// own (the caller supplies which files exist), no output formatting.
+import { compileGlob } from "../classify.js";
+import { withPointerSpecs } from "../config-pointer.js";
+// Reports at `file` (each entry's own path) - independent per file, unlike
+// uncovered-module's own grouping/naming: whether one file matches a
+// `mustBeEmpty` glob never depends on any other file in `files`. So a
+// `check <file>` run's own caller (runRules) can safely narrow `files`
+// down to just the focus file before calling this rule at all, and get
+// exactly the same result as running the whole list and filtering
+// afterward - the narrowing happens in runRules, not in this file.
+//
+// `files`: every real, project-root-relative (forward-slash) path this
+// config's own analysis scope covers - the caller decides what that scope
+// is (declared modules' own files, or a project's whole file list); this
+// rule only tests each one against every `mustBeEmpty` glob.
+export function checkMustBeEmpty(files, config) {
+    const entries = config.mustBeEmpty ?? [];
+    if (entries.length === 0)
+        return [];
+    const violations = [];
+    for (const [entryIndex, entry] of entries.entries()) {
+        const glob = compileGlob(entry.glob);
+        // `files` is not a promise about order (module membership is built
+        // walking rootNames order - a directory scan, not a promise about
+        // reading order across files) - sorted here so two files matching the
+        // same entry come out in a stable order regardless of it.
+        for (const file of [...files].sort()) {
+            if (!glob.test(file))
+                continue;
+            violations.push(withPointerSpecs({
+                rule: "must-be-empty",
+                path: file,
+                line: 1,
+                column: 1,
+                evidence: `'${file}' matches '${entry.glob}', which must stay empty`,
+                because: entry.because,
+                do: `move '${file}' out of '${entry.glob}', or drop this mustBeEmpty entry in archstrict.config.ts if the restriction no longer applies`,
+            }, [{ pointer: `mustBeEmpty[${entryIndex}]`, role: "fired" }]));
+        }
+    }
+    return violations;
+}