archstrict 0.0.0 → 0.2.0

package/dist/config.js

@@ -0,0 +1,194 @@
+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()) {
+        const glob = mod?.glob;
+        if (Array.isArray(glob)) {
+            for (const [j, entry] of glob.entries()) {
+                assertGlobSupported(configPath, `declaredModules[${i}].glob[${j}]`, entry, verb);
+            }
+        }
+        else {
+            assertGlobSupported(configPath, `declaredModules[${i}].glob`, 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);
+    }
+}