archstrict 0.0.0 → 0.1.0

package/dist/config-pointer.js

@@ -0,0 +1,251 @@
+// Responsibility: attach structured config locations to raw violations and
+// resolve each config value path against the config's TypeScript source.
+// Boundary: rule evaluation and report formatting stay in their own modules.
+// Rules can supply an exact index when duplicate config entries need distinct
+// locations; this module owns the fallback selection for other findings.
+import { existsSync, readFileSync } from "node:fs";
+import ts from "typescript";
+export const CONFIG_POINTER_SPECS = Symbol("archstrict.config-pointer-specs");
+function pathParts(pointer) {
+    const parts = [];
+    const pattern = /(?:^|\.)([^.\[\]]+)|\[(\d+)\]/g;
+    for (const match of pointer.matchAll(pattern)) {
+        parts.push(match[2] === undefined ? match[1] : Number(match[2]));
+    }
+    return parts;
+}
+function valueAt(config, pointer) {
+    let value = config;
+    for (const part of pathParts(pointer)) {
+        if (typeof part === "number") {
+            value = Array.isArray(value) ? value[part] : undefined;
+        }
+        else {
+            value = typeof value === "object" && value !== null ? value[part] : undefined;
+        }
+    }
+    if (Array.isArray(value) && value.length > 20) {
+        return [...value.slice(0, 20), `... ${value.length - 20} more`];
+    }
+    return value ?? null;
+}
+export function withPointerSpecs(violation, specs) {
+    Object.defineProperty(violation, CONFIG_POINTER_SPECS, { value: specs });
+    return violation;
+}
+function unwrap(expression) {
+    let current = expression;
+    while (ts.isParenthesizedExpression(current) || ts.isAsExpression(current) || ts.isSatisfiesExpression(current)) {
+        current = current.expression;
+    }
+    return current;
+}
+function propertyName(name) {
+    if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name))
+        return name.text;
+    return undefined;
+}
+function isLiteralPosition(node) {
+    return ts.isObjectLiteralExpression(node) || ts.isArrayLiteralExpression(node) || ts.isStringLiteralLike(node) ||
+        ts.isNumericLiteral(node) || node.kind === ts.SyntaxKind.TrueKeyword || node.kind === ts.SyntaxKind.FalseKeyword ||
+        node.kind === ts.SyntaxKind.NullKeyword;
+}
+function configObject(sourceFile) {
+    for (const statement of sourceFile.statements) {
+        if (ts.isExportAssignment(statement))
+            return unwrap(statement.expression);
+    }
+    return undefined;
+}
+function syntaxAt(root, parts) {
+    let current = root;
+    let nearestLiteral = root;
+    for (const part of parts) {
+        const expression = ts.isExpression(current) ? unwrap(current) : current;
+        let next;
+        if (typeof part === "number" && ts.isArrayLiteralExpression(expression)) {
+            // A spread contributes an unknown number of runtime entries. Once one
+            // appears before this index, syntax indices no longer identify values.
+            if (expression.elements.slice(0, part + 1).some(ts.isSpreadElement))
+                break;
+            next = expression.elements[part];
+        }
+        else if (typeof part === "string" && ts.isObjectLiteralExpression(expression)) {
+            let selected;
+            let selectedIndex = -1;
+            let lastUnknownIndex = -1;
+            expression.properties.forEach((candidate, index) => {
+                if (ts.isSpreadAssignment(candidate)) {
+                    lastUnknownIndex = index;
+                    return;
+                }
+                if (!ts.isPropertyAssignment(candidate) && !ts.isShorthandPropertyAssignment(candidate))
+                    return;
+                const name = propertyName(candidate.name);
+                if (name === undefined)
+                    lastUnknownIndex = index;
+                else if (name === part) {
+                    selected = candidate;
+                    selectedIndex = index;
+                }
+            });
+            // A later spread or computed key can replace the selected runtime
+            // value. The containing object is the nearest reliable literal then.
+            if (selected === undefined || selectedIndex < lastUnknownIndex)
+                break;
+            next = ts.isPropertyAssignment(selected) ? selected.initializer : selected.name;
+        }
+        if (next === undefined)
+            break;
+        current = next;
+        const unwrapped = ts.isExpression(next) ? unwrap(next) : next;
+        if (isLiteralPosition(unwrapped))
+            nearestLiteral = unwrapped;
+    }
+    const selected = ts.isExpression(current) ? unwrap(current) : current;
+    return isLiteralPosition(selected) ? selected : nearestLiteral;
+}
+export function createConfigLocator(config, sourceOverride) {
+    let sourceFile;
+    let root;
+    if (sourceOverride !== undefined || existsSync(config.configPath)) {
+        const source = sourceOverride ?? readFileSync(config.configPath, "utf8");
+        sourceFile = ts.createSourceFile(config.configPath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+        root = configObject(sourceFile);
+    }
+    return {
+        pointer(pointer, role) {
+            let line = 1;
+            let column = 1;
+            if (sourceFile !== undefined && root !== undefined) {
+                const node = syntaxAt(root, pathParts(pointer));
+                const position = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+                line = position.line + 1;
+                column = position.character + 1;
+            }
+            return { path: config.configPath, pointer, value: valueAt(config, pointer), line, column, role };
+        },
+    };
+}
+export function declaredModulePointerForName(config, name) {
+    const index = config.declaredModules?.findIndex((entry) => entry.name === name) ?? -1;
+    return index < 0 ? "declaredModules" : `declaredModules[${index}]`;
+}
+function edgeIdentifier(kind, entry) {
+    if (kind === "allowDeny")
+        return `${entry.source} -> ${entry.targetNamespace}`;
+    if (kind === "order")
+        return `${entry.tagNamespace}${entry.within === undefined ? "" : ` within ${entry.within}`}`;
+    const from = typeof entry.from === "string" ? entry.from : JSON.stringify(entry.from);
+    const to = typeof entry.to === "string" ? entry.to : JSON.stringify(entry.to);
+    return `${from} -> ${to}`;
+}
+function indexByEvidence(entries, predicate) {
+    return entries?.findIndex(predicate) ?? -1;
+}
+function pointerSpecs(violation, config) {
+    if (violation[CONFIG_POINTER_SPECS] !== undefined)
+        return [...violation[CONFIG_POINTER_SPECS]];
+    switch (violation.rule) {
+        case "public-surface-bypass":
+        case "type-leak":
+            return [{ pointer: declaredModulePointerForName(config, violation.todoModule), role: "governs" }];
+        case "uncovered-module":
+            return [{ pointer: "declaredModules", role: "governs" }];
+        case "cycle":
+            return [
+                { pointer: declaredModulePointerForName(config, violation.todoModule), role: "governs" },
+                { pointer: "ignoredCycles", role: "edit-here" },
+            ];
+        case "stale-cycle-exception": {
+            const index = indexByEvidence(config.ignoredCycles, ([a, b]) => violation.evidence.includes(`['${a}', '${b}']`));
+            return [{ pointer: index < 0 ? "ignoredCycles" : `ignoredCycles[${index}]`, role: "fired" }];
+        }
+        case "must-be-empty": {
+            const index = indexByEvidence(config.mustBeEmpty, (entry) => violation.evidence.includes(`'${entry.glob}'`));
+            return [{ pointer: index < 0 ? "mustBeEmpty" : `mustBeEmpty[${index}]`, role: "fired" }];
+        }
+        case "deprecated-edge-increased": {
+            const index = indexByEvidence(config.deprecated, (entry) => violation.evidence.startsWith(`${entry.from} -> ${entry.to}:`));
+            return [{ pointer: index < 0 ? "deprecated" : `deprecated[${index}].count`, role: "fired" }];
+        }
+        case "tag-boundary": {
+            const rules = config.edges?.allowDeny ?? [];
+            const index = rules.findIndex((entry) => violation.because === entry.because && violation.evidence.includes(`from '${entry.source}'`));
+            if (index < 0)
+                return [{ pointer: "edges.allowDeny", role: "fired" }];
+            const rule = rules[index];
+            if (rule.deny !== undefined) {
+                const deniedIndex = rule.deny.findIndex((value) => violation.evidence.includes(`'${rule.targetNamespace}:${value}'`));
+                if (deniedIndex >= 0)
+                    return [
+                        { pointer: `edges.allowDeny[${index}].deny[${deniedIndex}]`, role: "fired" },
+                        { pointer: `edges.allowDeny[${index}].allow`, role: "edit-here" },
+                    ];
+            }
+            return [{ pointer: `edges.allowDeny[${index}].allow`, role: "fired" }];
+        }
+        case "tag-order": {
+            const rules = config.edges?.order ?? [];
+            const index = rules.findIndex((entry) => violation.because === entry.because && violation.evidence.includes(`(${entry.tagNamespace} sequence:`));
+            return [{ pointer: index < 0 ? "edges.order" : `edges.order[${index}].sequence`, role: "fired" }];
+        }
+        case "point-rule": {
+            const rules = config.edges?.point ?? [];
+            const index = rules.findIndex((entry) => violation.because === entry.because &&
+                violation.do.includes(`'${edgeIdentifier("point", entry)}'`));
+            return [{ pointer: index < 0 ? "edges.point" : `edges.point[${index}]`, role: "fired" }];
+        }
+        case "clean-module-has-todo": {
+            const index = config.strict?.findIndex((name) => violation.evidence.includes(`module '${name}'`)) ?? -1;
+            return [{ pointer: index < 0 ? "strict" : `strict[${index}]`, role: "fired" }];
+        }
+        case "stale-todo":
+            return [{ pointer: "declaredModules", role: "governs" }];
+        case "empty-rule-set": {
+            if (violation.evidence === "no modules declared in declaredModules") {
+                return [{ pointer: "declaredModules", role: "fired" }];
+            }
+            const classifyIndex = indexByEvidence(config.classify, (entry) => violation.evidence.includes(`classify glob '${entry.glob}'`));
+            if (classifyIndex >= 0)
+                return [{ pointer: `classify[${classifyIndex}]`, role: "fired" }];
+            const deprecatedIndex = indexByEvidence(config.deprecated, (entry) => violation.evidence.includes(`'${entry.from} -> ${entry.to}'`));
+            if (deprecatedIndex >= 0)
+                return [{ pointer: `deprecated[${deprecatedIndex}]`, role: "fired" }];
+            for (const kind of ["allowDeny", "order", "point"]) {
+                const rules = config.edges?.[kind] ?? [];
+                const index = rules.findIndex((entry) => violation.evidence.includes(`${kind} rule '${edgeIdentifier(kind, entry)}'`));
+                if (index >= 0)
+                    return [{ pointer: `edges.${kind}[${index}]`, role: "fired" }];
+            }
+            return [{ pointer: "edges", role: "fired" }];
+        }
+        case "exhaustive-allow-list": {
+            const rules = config.edges?.allowDeny ?? [];
+            const index = rules.findIndex((entry) => violation.because === entry.because &&
+                violation.evidence.includes(`'${edgeIdentifier("allowDeny", entry)}'`));
+            return [{ pointer: index < 0 ? "edges.allowDeny" : `edges.allowDeny[${index}].allow`, role: "fired" }];
+        }
+        case "config-meaning": {
+            for (const kind of ["allowDeny", "order", "point"]) {
+                const rules = config.edges?.[kind] ?? [];
+                const index = rules.findIndex((entry) => violation.evidence.includes(`${kind} rule (`) && violation.because === entry.because);
+                if (index >= 0)
+                    return [{ pointer: `edges.${kind}[${index}]`, role: "fired" }];
+            }
+            return [{ pointer: "edges", role: "governs" }];
+        }
+        default:
+            return [{ pointer: "declaredModules", role: "governs" }];
+    }
+}
+export function locateViolation(violation, config, locator, specs = pointerSpecs(violation, config)) {
+    const pointers = specs.map(({ pointer, role }) => locator.pointer(pointer, role));
+    const configPointers = pointers.length === 1 ? pointers[0] : pointers;
+    const primary = pointers[0];
+    const position = violation.path === config.configPath ? { line: primary.line, column: primary.column } : {};
+    return { ...violation, ...position, config: configPointers };
+}
+export function locateViolations(violations, config, locator) {
+    return violations.map((violation) => locateViolation(violation, config, locator));
+}

package/dist/config.js

@@ -0,0 +1,186 @@
+import { ReportError } from "./report-error.js";
+// The only schema loadConfig accepts. init writes this value into a new
+// archstrict.config.ts. A config that omits the field is this same schema
+// (the field arrived after the first configs); any other value is a config
+// error, not a silent misread of a future shape.
+export const SCHEMA_VERSION = 1;
+// Checked before required-field validation: a future schema may rename
+// those fields, and the version mismatch is the fact to report first.
+export function assertSchemaVersion(configPath, raw) {
+    if (!("schemaVersion" in raw))
+        return;
+    const version = raw.schemaVersion;
+    if (version === SCHEMA_VERSION)
+        return;
+    throw new ReportError(`${configPath} schemaVersion ${JSON.stringify(version)} is not supported; this archstrict reads schemaVersion ${SCHEMA_VERSION}`, `set schemaVersion to ${SCHEMA_VERSION} in ${configPath}, then run archstrict check`);
+}
+// Throws if any `deprecated` entry names a module that doesn't exist.
+// Shared by rule 4 and rule 5: without a single shared check, the two
+// rules can disagree about the same config. Measured: rule 4's own
+// zero-modules early return skips its `deprecated` loop entirely, so a
+// `deprecated` entry naming a nonexistent module reached rule 4's "count
+// is 0, edge no longer exists" case instead of a config error — a name
+// that never existed is not the same fact as an edge that used to exist
+// and shrank to nothing, and reporting it that way is misleading, not
+// just imprecise.
+export function assertDeprecatedModulesExist(graph, config) {
+    for (const entry of config.deprecated ?? []) {
+        for (const moduleName of [entry.from, entry.to]) {
+            if (!graph.modules.has(moduleName)) {
+                throw new ReportError(`deprecated entry '${entry.from} -> ${entry.to}' names module '${moduleName}', which does not exist`, `declare '${moduleName}' in ${config.configPath}, or remove that deprecated entry, then run archstrict check`);
+            }
+        }
+    }
+}
+// loadConfig reads a real config file with ts.transpileModule (strips
+// types, never fully type-checks - see loadConfig's own comment for why),
+// so a malformed `edges` value is otherwise invisible to both the type
+// system and every rule: writing `edges` as an array instead of the real
+// `{ allowDeny?, order?, point? }` object produces zero rules, zero
+// violations, and - critically - no empty-rule-set violation either
+// (rule 4 has nothing to see, since no rule was ever parsed into
+// existence), indistinguishable from a config that never used `edges` at
+// all. Measured directly, via a fresh agent authoring a real config from
+// scratch: this was the single silent failure among several very similar
+// ones (an `order` entry's own `sequence` written as a flat array instead
+// of `Record<string, string[]>`, a real, unsupported key mistyped onto a
+// rule entry) - the `sequence` case happens to surface today via rule 4's
+// own `evaluated: 0`, but neither it nor an unsupported key should depend
+// on a downstream rule noticing a side effect. A config shape error is a
+// config error, thrown up front, the same as an unsupported `deprecated`
+// entry already is above.
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// Exported: loadConfig's own declaredModules validation (check.ts) needs
+// the same wording for the same kind of shape mismatch, rather than a
+// second, differently-worded describer for the same fact.
+export function describeShape(value) {
+    return Array.isArray(value) ? "an array" : typeof value;
+}
+function assertKnownKeys(value, known, context) {
+    for (const key of Object.keys(value)) {
+        if (!known.includes(key)) {
+            throw new ReportError(`${context} has an unknown field '${key}' - supported fields are ${known.join(", ")}`, `remove '${key}' from ${context} in archstrict.config.ts, then run archstrict check`);
+        }
+    }
+}
+function assertEntries(value, keys, context) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value)) {
+        throw new ReportError(`config.edges.${context} must be an array of entries, not ${describeShape(value)}`, `set config.edges.${context} to an array of entries in archstrict.config.ts, then run archstrict check`);
+    }
+    return value.map((entry, i) => {
+        if (!isPlainObject(entry)) {
+            throw new ReportError(`config.edges.${context}[${i}] must be an object, not ${describeShape(entry)}`, `make config.edges.${context}[${i}] an object in archstrict.config.ts, then run archstrict check`);
+        }
+        assertKnownKeys(entry, keys, `config.edges.${context}[${i}]`);
+        return entry;
+    });
+}
+const ALLOW_DENY_KEYS = [
+    "source",
+    "targetNamespace",
+    "allow",
+    "deny",
+    "exceptions",
+    "edgeType",
+    "importForm",
+    "because",
+];
+const ORDER_KEYS = ["tagNamespace", "within", "sequence", "direction", "edgeType", "importForm", "because"];
+const POINT_KEYS = ["from", "to", "edgeType", "importForm", "because"];
+export function assertEdgesShapeValid(config) {
+    const edges = config.edges;
+    if (edges === undefined)
+        return;
+    if (!isPlainObject(edges)) {
+        throw new ReportError(`config.edges must be an object with allowDeny/order/point fields (e.g. { allowDeny: [...] }), not ${describeShape(edges)}`, "set config.edges to an object with allowDeny, order, and point in archstrict.config.ts, then run archstrict check");
+    }
+    assertKnownKeys(edges, ["allowDeny", "order", "point"], "config.edges");
+    for (const entry of assertEntries(edges.allowDeny, ALLOW_DENY_KEYS, "allowDeny")) {
+        // These shapes cannot reject any edge, even when coverage is nonzero.
+        if (entry.allow === undefined &&
+            (entry.deny === undefined || (Array.isArray(entry.deny) && entry.deny.length === 0))) {
+            throw new Error(`config.edges.allowDeny entry with source '${entry.source}' and targetNamespace '${entry.targetNamespace}' must specify allow or a non-empty deny list`);
+        }
+    }
+    assertEntries(edges.point, POINT_KEYS, "point");
+    for (const entry of assertEntries(edges.order, ORDER_KEYS, "order")) {
+        const sequence = entry.sequence;
+        if (sequence !== undefined && !isPlainObject(sequence)) {
+            throw new ReportError(`an edges.order entry's sequence must be an object keyed by the 'within' scope (e.g. { "": ["a", "b"] }), not ${describeShape(sequence)}`, "set that sequence to an object keyed by the within scope in archstrict.config.ts, then run archstrict check");
+        }
+    }
+}
+// compileGlob (classify.ts) only ever special-cases `*` and `**`; every
+// other character - including brace (`{a,b}`), extglob (`+(a|b)`,
+// `@(...)`, `!(...)`, `?(...)`), `?`, and bracket (`[...]`) syntax a shell
+// or a real glob library would treat specially - falls through its own
+// literal branch, escaped for RegExp use. A config author who writes one
+// of those, expecting shell/minimatch semantics, gets a glob that matches
+// nothing: every file it was meant to cover instead surfaces as
+// uncovered-module, silently, with no hint the glob itself was the
+// problem. Caught here, once, for every field a glob can appear in,
+// rather than as a downstream "why is this file uncovered" mystery.
+//
+// A bare `+` or `@` is left alone (both appear in ordinary literal paths -
+// a scoped package directory name, a filename with a `+` in it); only the
+// bracket/brace/question-mark/bang characters below are checked, and `(`
+// alone already catches the extglob forms (`+(`, `@(`, `!(`, `?(`) without
+// needing to special-case them.
+const UNSUPPORTED_GLOB_PATTERN = /[{}()[\]?!]/;
+function assertGlobSupported(configPath, field, glob, verb) {
+    // A non-string value here is a different validator's problem (shape
+    // checks above, or the field's own type in Config) - this check only
+    // ever looks at strings that already made it this far.
+    if (typeof glob !== "string" || !UNSUPPORTED_GLOB_PATTERN.test(glob))
+        return;
+    throw new ReportError(`${configPath} field '${field}' has an unsupported glob '${glob}' - only '*' (any characters within one path segment) and '**' (any depth, including zero segments) are supported; '{', '}', '(', ')', '[', ']', '?', and '!' all match nothing, including in an extglob form like '+(...)' or '@(...)'`, `rewrite '${field}' in ${configPath} using only * and **, or split it into one entry per directory, in archstrict.config.ts, then run ${verb}`);
+}
+// One entry per glob-bearing field the config schema has (see Config's own
+// fields above). Walked defensively (typeof/Array.isArray guards, not the
+// Config type) because loadConfig calls this on a value ts.transpileModule
+// only stripped types from, never type-checked - a field can hold any
+// runtime shape a hand-written config puts there.
+export function assertGlobsSupported(config, verb) {
+    const configPath = config.configPath;
+    for (const [i, glob] of (config.exclude ?? []).entries()) {
+        assertGlobSupported(configPath, `exclude[${i}]`, glob, verb);
+    }
+    for (const [i, entry] of (config.classify ?? []).entries()) {
+        assertGlobSupported(configPath, `classify[${i}].glob`, entry?.glob, verb);
+    }
+    for (const [i, entry] of (config.mustBeEmpty ?? []).entries()) {
+        assertGlobSupported(configPath, `mustBeEmpty[${i}].glob`, entry?.glob, verb);
+    }
+    for (const [i, mod] of (config.declaredModules ?? []).entries()) {
+        assertGlobSupported(configPath, `declaredModules[${i}].glob`, mod?.glob, verb);
+        const surface = mod?.surface;
+        if (Array.isArray(surface)) {
+            for (const [j, s] of surface.entries()) {
+                assertGlobSupported(configPath, `declaredModules[${i}].surface[${j}]`, s, verb);
+            }
+        }
+        else if (surface !== undefined) {
+            assertGlobSupported(configPath, `declaredModules[${i}].surface`, surface, verb);
+        }
+        for (const [j, friend] of (mod?.friends ?? []).entries()) {
+            assertGlobSupported(configPath, `declaredModules[${i}].friends[${j}].file`, friend?.file, verb);
+            assertGlobSupported(configPath, `declaredModules[${i}].friends[${j}].from`, friend?.from, verb);
+        }
+    }
+    for (const [i, rule] of (config.edges?.allowDeny ?? []).entries()) {
+        for (const [j, exception] of (rule?.exceptions ?? []).entries()) {
+            assertGlobSupported(configPath, `edges.allowDeny[${i}].exceptions[${j}].from`, exception?.from, verb);
+            assertGlobSupported(configPath, `edges.allowDeny[${i}].exceptions[${j}].to`, exception?.to, verb);
+        }
+    }
+    // point's from/to are each either a glob (string) or a tag predicate
+    // (an object) - only the string form is a glob this check applies to.
+    for (const [i, rule] of (config.edges?.point ?? []).entries()) {
+        assertGlobSupported(configPath, `edges.point[${i}].from`, rule?.from, verb);
+        assertGlobSupported(configPath, `edges.point[${i}].to`, rule?.to, verb);
+    }
+}