@goodbones/core 0.1.0-beta.1

package/src/manifest/compile.ts

@@ -0,0 +1,1011 @@
+import {
+  type ExportRule,
+  type GraphConfig,
+  type ImportRule,
+  type MemberRule,
+  OPEN_LAYOUT,
+  type StructureFolder,
+  type StructureNaming,
+  type StructureParity,
+  type StructureRoot,
+  type SurfaceRule,
+} from "../domain/architecture-config.js";
+import { anchored, type CaptureIndex, globToRegexSource, prefixed } from "./glob.js";
+import {
+  globsOf,
+  type ImportsSpec,
+  type Manifest,
+  type ManifestNode,
+  type NamingSpec,
+} from "./manifest.js";
+
+// The manifest is the authoring surface; these flat rules are the machine's.
+// Lowering rather than interpreting keeps one evaluator, one probe mechanism and
+// one set of semantics — the tree only decides what gets written.
+export type LoweredRules = {
+  readonly imports: ReadonlyArray<ImportRule>;
+  readonly exports: ReadonlyArray<ExportRule>;
+  readonly members: ReadonlyArray<MemberRule>;
+  readonly surface: ReadonlyArray<SurfaceRule>;
+  readonly graph: GraphConfig;
+  // The nodes that said "not tightened yet", by name — the adoption backlog,
+  // and what `limits` puts a ceiling on.
+  readonly adoption: {
+    readonly unrestricted: ReadonlyArray<string>;
+    readonly partial: ReadonlyArray<string>;
+  };
+  readonly structure: {
+    readonly roots: ReadonlyArray<StructureRoot>;
+    readonly folders: ReadonlyArray<StructureFolder>;
+    readonly parity: ReadonlyArray<StructureParity>;
+    readonly naming: ReadonlyArray<StructureNaming>;
+  };
+};
+
+const FOLDER_KEY = /\/$/;
+
+// The marker an open folder's allowlist carries: it admits any name, so it has
+// no layout policy to prove.
+export const ANY_FILE = OPEN_LAYOUT;
+
+// The `from` side of a rule that applies to every file, wherever the repository
+// happens to keep its packages.
+const EVERY_FILE = "";
+
+// A key may name several patterns that share one node: the four `*-ops`
+// stereotypes carry identical policy, and saying it once is the point of writing
+// the architecture as a tree.
+const ALTERNATIVE = /\s*\|\s*/;
+
+const isFolderKey = (key: string): boolean => FOLDER_KEY.test(key);
+
+const stripSlash = (key: string): string => key.replace(FOLDER_KEY, "");
+
+// Split first, then strip: `"http/ | cli/"` carries a trailing slash on every
+// alternative, not only the last one.
+const alternativesOf = (key: string): ReadonlyArray<string> =>
+  key
+    .split(ALTERNATIVE)
+    .map(stripSlash)
+    .filter((one) => one !== "");
+
+const expandAliases = (glob: string, aliases: Readonly<Record<string, string>>): string => {
+  for (const [alias, target] of Object.entries(aliases)) {
+    if (glob === alias) return target;
+    if (glob.startsWith(`${alias}/`)) return target + glob.slice(alias.length);
+  }
+  return glob;
+};
+
+type Frame = {
+  // Regex source for this node's own path, unanchored.
+  readonly pathSource: string;
+  // Glob for this node's path, used to synthesise probes.
+  readonly pathGlob: string;
+  readonly captures: CaptureIndex;
+  readonly nextGroup: number;
+  // Accumulated down the tree. `reset` is the only thing that clears it.
+  readonly allow: ReadonlyArray<string>;
+  // Third-party packages, by name, accumulated and reset the same way. Kept
+  // apart from `allow` because a package is judged by its name and never by
+  // where the language's resolver found it.
+  readonly externals: ReadonlyArray<string>;
+  readonly importsMessage: string;
+  // Inherited like the allowlist: a tier states its naming convention once.
+  readonly naming: NamingSpec | undefined;
+};
+
+// What lowering needs to know about a language: which scope ids name it, and
+// what a source file of it is called. Structurally a `Language`, so the host
+// passes its packs straight through; declared here so this tier never names
+// the port.
+export type ProbeLanguage = {
+  readonly id: string;
+  readonly extensions: ReadonlyArray<string>;
+};
+
+// A probe is the node's own path with its wildcards filled in, so a rule is
+// proven against the shape it was written for and nobody hand-writes one.
+const PROBE_WORDS = ["alpha", "beta", "gamma", "delta"];
+
+const probePathOf = (pathGlob: string, leaf: string): string => {
+  let word = 0;
+  const filled = pathGlob
+    .replace(/\{[a-zA-Z][a-zA-Z0-9]*\}/g, () => {
+      const value = PROBE_WORDS[word % PROBE_WORDS.length] ?? "alpha";
+      word += 1;
+      return value;
+    })
+    .replace(/\*\*/g, "deep")
+    .replace(/\*/g, "zz");
+  if (leaf === "") return filled;
+  return filled === "" ? leaf : `${filled}/${leaf}`;
+};
+
+// The probe name must satisfy the rule's own `match`, or the rule cannot report
+// it and the vacuity check fires on a healthy rule.
+const probeMemberName = (match: string | ReadonlyArray<string> | undefined): string => {
+  if (match === undefined) return "zzProbeMember";
+  const first = globsOf(match)[0] ?? "";
+  return `${first
+    // A character class stands for one character, so the probe uses the first
+    // one it admits: `use[A-Z]*` has to be proven with `useA…`, not `use[A-Z]…`.
+    .replace(/\[\^?([^\]])[^\]]*\]/g, "$1")
+    .replace(/\*/g, "")}ZzProbe`;
+};
+
+// Each convention pairs the shape a name must have with a name that does not
+// have it, so the rule's probe is generated rather than written.
+const CONVENTIONS: Readonly<
+  Record<string, { readonly source: string; readonly violating: string; readonly shape: string }>
+> = {
+  "kebab-case": {
+    source: "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+    violating: "zzProbeStray",
+    shape: "lowercase words joined by hyphens",
+  },
+  camelCase: {
+    source: "^[a-z][a-zA-Z0-9]*$",
+    violating: "zz-probe-stray",
+    shape: "a lowercase first word, then capitalised ones, with no separators",
+  },
+  PascalCase: {
+    source: "^[A-Z][a-zA-Z0-9]*$",
+    violating: "zz-probe-stray",
+    shape: "capitalised words with no separators",
+  },
+  snake_case: {
+    source: "^[a-z0-9]+(?:_[a-z0-9]+)*$",
+    violating: "zzProbeStray",
+    shape: "lowercase words joined by underscores",
+  },
+};
+
+// The folder's file list already enforces the stereotype suffix; a naming rule
+// is about the concept name in front of it, so the message says which part it
+// is talking about.
+const namingMessageOf = (spec: NamingSpec, subject: "file" | "folder"): string => {
+  const what =
+    subject === "folder" ? "This folder's name" : "The concept name in front of the stereotype";
+  if (typeof spec === "string") {
+    return `${what} is ${spec} here — ${CONVENTIONS[spec]?.shape ?? ""}.`;
+  }
+  if (spec.message !== undefined) return spec.message;
+  if ("like" in spec) {
+    return "A file here is named after its folder, so its concept name is the folder's own.";
+  }
+  return `${what} matches /${spec.regex}/ here.`;
+};
+
+// A custom convention still owes a counter-example. If none of these fails it,
+// the pattern admits every name and the rule could never report anything —
+// which is the vacuity this package refuses to load.
+const VIOLATING_CANDIDATES = ["zzProbeStray", "zz-probe-stray", "ZZ_PROBE_STRAY", "zz probe.stray"];
+
+const violatingSampleFor = (spec: NamingSpec, ruleName: string): string => {
+  if (typeof spec === "string") {
+    const convention = CONVENTIONS[spec];
+    if (convention === undefined) throw new Error(`unknown naming convention "${spec}"`);
+    return convention.violating;
+  }
+  if ("like" in spec) return "zzprobestray";
+  const matcher = new RegExp(spec.regex);
+  const found = VIOLATING_CANDIDATES.find((candidate) => !matcher.test(candidate));
+  if (found === undefined) {
+    throw new Error(
+      `naming rule "${ruleName}" states /${spec.regex}/, which admits every name this ` +
+        `compiler can think of. A convention nothing can violate is a rule that never reports.`,
+    );
+  }
+  return found;
+};
+
+// The probe is the node's own probe path with the subject replaced by a name the
+// convention rejects — located by matching, so the compiler never has to reason
+// about which segment of a glob the subject came from.
+const namingProbeOf = (
+  patternSource: string,
+  subject: number,
+  probe: string,
+  violating: string,
+): string => {
+  const found = new RegExp(patternSource, "d").exec(probe);
+  const span = found?.indices?.[subject];
+  if (span === undefined) return probe;
+  return probe.slice(0, span[0]) + violating + probe.slice(span[1]);
+};
+
+type Denial = {
+  readonly match: string;
+  readonly matchNot: ReadonlyArray<string>;
+  readonly except: ReadonlyArray<string>;
+  readonly message: string;
+  // A concrete path the denial matches, so its probe aims at the shape it was
+  // written for rather than at one generic target for every denial.
+  readonly probe: string;
+};
+
+const mergeImports = (
+  frame: Frame,
+  spec: ImportsSpec | undefined,
+  aliases: Readonly<Record<string, string>>,
+  captures: CaptureIndex,
+  nextGroup: number,
+): Pick<Frame, "allow" | "externals" | "importsMessage"> & {
+  readonly deny: ReadonlyArray<Denial>;
+} => {
+  if (spec === undefined) {
+    return {
+      allow: frame.allow,
+      externals: frame.externals,
+      deny: [],
+      importsMessage: frame.importsMessage,
+    };
+  }
+
+  const compileAllow = (glob: string): string =>
+    prefixed(
+      globToRegexSource(expandAliases(glob, aliases), captures, { declaring: false, nextGroup })
+        .source,
+    );
+
+  const own = globsOf(spec.allow ?? []).map(compileAllow);
+  const external = spec.external ?? [];
+  const deny = (spec.deny ?? []).flatMap((entry) =>
+    globsOf(entry.match).map((glob) => ({
+      match: compileAllow(glob),
+      matchNot: globsOf(entry.matchNot ?? []).map(compileAllow),
+      except: globsOf(entry.except ?? []).map(compileAllow),
+      message: entry.message,
+      probe: probePathOf(expandAliases(glob, aliases), ""),
+    })),
+  );
+
+  // `reset` drops inherited ALLOWANCES only. A prohibition always accumulates, so
+  // resetting can never make a subtree quieter than its ancestors — the direction
+  // a mistake here would be dangerous in.
+  const dropping = spec.reset === true || spec.unrestricted === true;
+  return {
+    allow: dropping ? own : [...frame.allow, ...own],
+    externals: dropping ? external : [...frame.externals, ...external],
+    // Only what this node declares. A prohibition is emitted once, over its whole
+    // subtree, so descendants neither re-emit it nor can escape it — which is
+    // what makes `reset` structurally unable to make a subtree quieter.
+    deny,
+    importsMessage: spec.message ?? frame.importsMessage,
+  };
+};
+
+export const lowerManifest = (
+  manifest: Manifest,
+  languages: ReadonlyArray<ProbeLanguage> = [],
+): LoweredRules => {
+  const aliases = manifest.aliases ?? {};
+
+  // The extension a synthetic probe file carries: the first extension of the
+  // language whose scope covers the probe's folder. A probe is matched by its
+  // folder, so the extension only makes it a file that language would have —
+  // which matters exactly when an allowlist admits `**/*.<ext>`, and would
+  // otherwise pass its probe while admitting every file.
+  const extensionFor = (folder: string): string => {
+    const scope = manifest.resolve.scopes.find((one) =>
+      new RegExp(one.files).test(`${folder}/zzprobe`),
+    );
+    const language = languages.find((one) => one.id === scope?.language);
+    return language?.extensions[0] ?? "";
+  };
+
+  // A synthetic file inside a folder glob: the folder with its wildcards filled,
+  // then the stem, then whatever extension the folder's language uses.
+  const probeIn = (folderGlob: string, stem: string): string =>
+    probePathOf(folderGlob, `${stem}${extensionFor(probePathOf(folderGlob, ""))}`);
+
+  // A synthetic file somewhere no node governs, written like a file of the
+  // language at `likeFolder` so that it is refused by a rule about that
+  // language's files and not merely by one about its own folder.
+  const probeOutside = (stem: string, likeFolder = "packages/zzprobe"): string =>
+    `packages/zzprobe/${stem}${extensionFor(likeFolder)}`;
+
+  // The folder layout rule must be proven with a basename the folder rejects.
+  // What that is depends on what the folder admits: a stray with the language's
+  // own extension is a file a folder admitting every such file is happy with.
+  const strayBasenameFor = (
+    admitted: ReadonlyArray<string>,
+    extension: string,
+    ruleName: string,
+  ): string => {
+    const candidates = [`zzprobe-stray${extension}`, "zzprobe-stray", "zzprobe.stray.zz"];
+    const rejected = candidates.find(
+      (candidate) => !admitted.some((pattern) => new RegExp(pattern).test(candidate)),
+    );
+    if (rejected === undefined) {
+      throw new Error(
+        `"${ruleName}" admits every file name this compiler can think of, so it enumerates ` +
+          `nothing. A folder that does not police its file names is \`layout: "open"\`; say so.`,
+      );
+    }
+    return rejected;
+  };
+  const imports: Array<ImportRule> = [];
+  const exports: Array<ExportRule> = [];
+  const members: Array<MemberRule> = [];
+  const surface: Array<SurfaceRule> = [];
+  const unrestrictedNodes: Array<string> = [];
+  const partialNodes: Array<string> = [];
+  const roots: Array<StructureRoot> = [];
+  const folders: Array<StructureFolder> = [];
+  const parity: Array<StructureParity> = [];
+  const namingRules: Array<StructureNaming> = [];
+
+  const walk = (
+    key: string,
+    node: ManifestNode,
+    parent: Frame,
+    name: string,
+    siblings: ReadonlyArray<string>,
+  ): void => {
+    const literalSiblings = siblings
+      .filter((sibling) => sibling !== key)
+      .flatMap(alternativesOf)
+      .filter((sibling) => !/[*{]/.test(sibling));
+    const alternatives = alternativesOf(key).map((one) => expandAliases(one, aliases));
+    const [first = ""] = alternatives;
+
+    if (node.partial === true) partialNodes.push(name);
+    if (node.imports?.unrestricted === true) unrestrictedNodes.push(name);
+    if (alternatives.length > 1 && alternatives.some((one) => one.includes("{"))) {
+      throw new Error(
+        `key "${key}" both names several patterns and declares a capture. A capture has to come ` +
+          `from one place, so give the capturing pattern its own key.`,
+      );
+    }
+    // The probe, the path and every descendant hang off the first alternative;
+    // the rest only widen what the pattern matches.
+    const joinedGlob = parent.pathGlob === "" ? first : `${parent.pathGlob}/${first}`;
+    const compiledFirst = globToRegexSource(first, parent.captures, {
+      declaring: true,
+      nextGroup: parent.nextGroup,
+    });
+    const compiled =
+      alternatives.length === 1
+        ? compiledFirst
+        : {
+            captures: compiledFirst.captures,
+            source: `(?:${alternatives
+              .map(
+                (one) =>
+                  globToRegexSource(one, parent.captures, {
+                    declaring: false,
+                    nextGroup: parent.nextGroup,
+                  }).source,
+              )
+              .join("|")})`,
+          };
+    // `(?!domain-services$|ports$)` — written by the compiler, from the fact that
+    // those keys are siblings of this one.
+    const guarded =
+      literalSiblings.length > 0 && /[*{]/.test(first)
+        ? `(?!(?:${literalSiblings.map((one) => one.replace(/[.+^$()|[\]\\*?{}]/g, "\\$&")).join("|")})(?:/|$))${compiled.source}`
+        : compiled.source;
+    const pathSource = parent.pathSource === "" ? guarded : `${parent.pathSource}/${guarded}`;
+    const nextGroup =
+      parent.nextGroup +
+      (Object.keys(compiled.captures).length - Object.keys(parent.captures).length);
+
+    const merged = mergeImports(parent, node.imports, aliases, compiled.captures, nextGroup);
+    const ownDenials = merged.deny;
+    const frame: Frame = {
+      pathSource,
+      pathGlob: joinedGlob,
+      captures: compiled.captures,
+      nextGroup,
+      allow: merged.allow,
+      externals: merged.externals,
+      importsMessage: merged.importsMessage,
+      naming: node.name ?? parent.naming,
+    };
+
+    const isFolder = isFolderKey(key) || node.children !== undefined;
+    const selfPattern = anchored(pathSource);
+
+    // Naming, in two shapes. A folder judges its own segment (when its key
+    // declares a capture) and the concept name of every file directly inside
+    // it; a file node judges what its own `*` matched, which is where "named
+    // after its folder" lives.
+    //
+    // A file's concept name is its basename up to the FIRST dot, not what a `*`
+    // matched: the key `*-live.<ext>` matches `todos.repository-live.<ext>`, whose
+    // wildcard spans a stereotype segment as well as the concept.
+    const naming = frame.naming;
+    if (naming !== undefined) {
+      const declaredHere = Object.keys(compiled.captures).filter(
+        (one) => parent.captures[one] === undefined,
+      );
+      const lastDeclared = declaredHere[declaredHere.length - 1];
+      const isLike = typeof naming === "object" && "like" in naming;
+
+      const emit = (
+        ruleName: string,
+        patterns: ReadonlyArray<string>,
+        subject: number,
+        probe: string,
+        sameAs?: number,
+        judging: "file" | "folder" = "file",
+      ): void => {
+        namingRules.push({
+          name: ruleName,
+          message: namingMessageOf(naming, judging),
+          probe: {
+            path:
+              sameAs === undefined
+                ? namingProbeOf(
+                    patterns[0] ?? "",
+                    subject,
+                    probe,
+                    violatingSampleFor(naming, ruleName),
+                  )
+                : probe,
+          },
+          file: patterns,
+          subject,
+          ...(sameAs === undefined
+            ? {
+                convention:
+                  typeof naming === "string"
+                    ? (CONVENTIONS[naming]?.source ?? "")
+                    : "regex" in naming
+                      ? naming.regex
+                      : "",
+              }
+            : { sameAs }),
+        });
+      };
+
+      if (isFolder && !isLike) {
+        if (lastDeclared !== undefined) {
+          const subject = compiled.captures[lastDeclared];
+          if (subject !== undefined) {
+            emit(
+              `${name}/naming-folder`,
+              [prefixed(`${pathSource}/`)],
+              subject,
+              probeIn(joinedGlob, "zzprobe"),
+              undefined,
+              "folder",
+            );
+          }
+        }
+        emit(
+          `${name}/naming`,
+          [anchored(`${pathSource}/([^/.]+)[^/]*`)],
+          nextGroup,
+          probeIn(joinedGlob, "zzprobe"),
+        );
+      }
+
+      if (!isFolder && isLike) {
+        const namingCompiled = alternatives.map((one) =>
+          globToRegexSource(one, parent.captures, {
+            declaring: true,
+            nextGroup: parent.nextGroup,
+            capturing: true,
+          }),
+        );
+        const [firstNaming] = namingCompiled;
+        const subject = firstNaming?.wildcards[firstNaming.wildcards.length - 1];
+        const sameAs =
+          typeof naming === "object" && "like" in naming
+            ? parent.captures[naming.like.replace(/[{}]/g, "")]
+            : undefined;
+        if (typeof naming === "object" && "like" in naming && sameAs === undefined) {
+          throw new Error(
+            `naming at "${key}" is like ${naming.like}, which no ancestor path declares.`,
+          );
+        }
+        if (subject !== undefined && sameAs !== undefined) {
+          emit(
+            `${name}/naming`,
+            namingCompiled.map((one) =>
+              anchored(
+                parent.pathSource === "" ? one.source : `${parent.pathSource}/${one.source}`,
+              ),
+            ),
+            subject,
+            probePathOf(joinedGlob, ""),
+            sameAs,
+          );
+        }
+      }
+    }
+
+    const childEntries = Object.entries(node.children ?? {});
+    // The nearest descendants — at any depth — that state their own import
+    // policy. A folder's allowlist covers its whole subtree except these, and
+    // each of them emits a rule over its own subtree in turn. Descent stops at a
+    // node that overrides, because everything below it is that node's business.
+    const overridingDescendants = (
+      from: ManifestNode,
+      atPath: string,
+      atCaptures: CaptureIndex,
+      atGroup: number,
+    ): ReadonlyArray<string> =>
+      Object.entries(from.children ?? {}).flatMap(([childKey, child]) =>
+        alternativesOf(childKey).flatMap((one) => {
+          // `declaring` because a folder key may itself name a capture
+          // (`{subdomain}/`). The extra group is harmless in an exclusion, which
+          // is matched on its own rather than substituted into.
+          const childCompiled = globToRegexSource(one, atCaptures, {
+            declaring: true,
+            nextGroup: atGroup,
+          });
+          const source = `${atPath}/${childCompiled.source}`;
+          const childGroup =
+            atGroup + (Object.keys(childCompiled.captures).length - Object.keys(atCaptures).length);
+          if (child.imports !== undefined) {
+            return [isFolderKey(childKey) ? prefixed(`${source}/`) : anchored(source)];
+          }
+          return isFolderKey(childKey)
+            ? overridingDescendants(child, source, childCompiled.captures, childGroup)
+            : [];
+        }),
+      );
+
+    const overridingChildren = overridingDescendants(
+      node,
+      pathSource,
+      compiled.captures,
+      nextGroup,
+    );
+
+    if (isFolder) {
+      const childKeys = childEntries;
+      const fileKeys = childKeys.filter(([childKey]) => !isFolderKey(childKey));
+      if (node.partial !== true) {
+        const ruleName = `${name}/layout`;
+        // An open folder still CLAIMS its folder — otherwise no rule governs
+        // it and the taxonomy root fires — it just admits any file name.
+        const admitted =
+          node.layout === "open"
+            ? [ANY_FILE]
+            : fileKeys.flatMap(([childKey]) =>
+                alternativesOf(childKey).map((one) =>
+                  anchored(
+                    globToRegexSource(one, compiled.captures, { declaring: false, nextGroup })
+                      .source,
+                  ),
+                ),
+              );
+        const folderProbe = probePathOf(joinedGlob, "");
+        const stray =
+          node.layout === "open"
+            ? `zzprobe-stray${extensionFor(folderProbe)}`
+            : strayBasenameFor(admitted, extensionFor(folderProbe), ruleName);
+        folders.push({
+          name: ruleName,
+          message: node.message ?? "This folder does not admit that file.",
+          probe: { path: probePathOf(joinedGlob, stray) },
+          folder: selfPattern,
+          files: admitted,
+        });
+      }
+      const siblingKeys = childKeys.map(([childKey]) => childKey);
+      for (const [childKey, child] of childKeys) {
+        walk(childKey, child, frame, `${name}/${alternativesOf(childKey)[0] ?? ""}`, siblingKeys);
+      }
+    }
+
+    // Outbound. One allowlist stands in for every "may not reach X" rule that
+    // would otherwise be written separately and far from here.
+    //
+    // Import policy belongs to a folder, so it lowers once per folder — matching
+    // that folder's direct children — rather than once per file kind inside it.
+    // A file node emits its own only when it says something its folder did not.
+    const emitsOwnImports = isFolder ? node.imports !== undefined : node.imports !== undefined;
+    const scope = isFolder ? prefixed(`${pathSource}/`) : selfPattern;
+    const scopeProbe = isFolder ? probeIn(joinedGlob, "zzprobe") : probePathOf(joinedGlob, "");
+    // The folder a probe of this node sits in, for "a file of the same language".
+    const ownFolder = isFolder
+      ? probePathOf(joinedGlob, "")
+      : probePathOf(joinedGlob, "").replace(/\/[^/]*$/, "");
+
+    const admitsEverything = frame.allow.some((pattern) => pattern === "^.*" || pattern === "^");
+    const hasAllowlist =
+      (frame.allow.length > 0 || frame.externals.length > 0) && !admitsEverything;
+
+    if (emitsOwnImports && node.imports?.unrestricted !== true && !hasAllowlist) {
+      throw new Error(
+        `"${name}" states an \`imports\` policy with no allowlist. If that is deliberate — the ` +
+          `tier is not tightened yet and only its prohibitions apply — say \`unrestricted: true\`, ` +
+          `so the gap is a sentence someone wrote rather than an omission nobody noticed.`,
+      );
+    }
+
+    if (emitsOwnImports) {
+      const exemptions = overridingChildren.length > 0 ? { fromNot: overridingChildren } : {};
+
+      if (hasAllowlist) {
+        imports.push({
+          name: `${name}/imports`,
+          message: frame.importsMessage,
+          probe: { from: scopeProbe, to: probeOutside("nowhere", ownFolder) },
+          from: scope,
+          ...exemptions,
+          toNot: [...frame.allow],
+          ...(frame.externals.length > 0 ? { externals: [...frame.externals] } : {}),
+        });
+      }
+    }
+
+    // Prohibitions are emitted once, over this node's whole subtree, and carry no
+    // exemptions: a node cannot opt out of an ancestor's prohibition.
+    for (const [index, denial] of ownDenials.entries()) {
+      imports.push({
+        name: `${name}/deny-${String(index)}`,
+        message: denial.message,
+        probe: { from: scopeProbe, to: denial.probe },
+        from: isFolder ? prefixed(`${pathSource}/`) : selfPattern,
+        ...(denial.except.length > 0 ? { fromNot: [...denial.except] } : {}),
+        to: denial.match,
+        ...(denial.matchNot.length > 0 ? { toNot: [...denial.matchNot] } : {}),
+      });
+    }
+
+    // Inbound. "This file is private to X" belongs beside the file, not in a
+    // distant rule whose `from` side grows an exclusion for every new caller.
+    if (node.importedBy !== undefined) {
+      // An `importedBy` allowlist is matched against the IMPORTER, while the
+      // captures on this node were declared by the TARGET's path — so a
+      // `{capture}` here has nothing to resolve against and would compile to a
+      // pattern that never matches, silently over-reporting. Refuse it rather
+      // than emit a rule whose exemptions do not work.
+      for (const allowed of globsOf(node.importedBy.allow)) {
+        const referenced = allowed.match(/\{[a-zA-Z][a-zA-Z0-9]*\}/g) ?? [];
+        if (referenced.length > 0) {
+          throw new Error(
+            `"${name}" allows ${referenced.join(", ")} in importedBy, but a capture from this ` +
+              `node's own path cannot be used there: importedBy patterns are matched against the ` +
+              `importing file, and ${referenced[0] ?? ""} was declared by this file's path. Use a ` +
+              `wildcard (the barrel rules are what stop another module reaching in), or move the ` +
+              `restriction to that importer's own node as an \`imports\` allowlist.`,
+          );
+        }
+      }
+      const asTarget = (glob: string) =>
+        prefixed(
+          globToRegexSource(expandAliases(glob, aliases), compiled.captures, {
+            declaring: false,
+            nextGroup,
+          }).source,
+        );
+      // On a folder the restriction covers the whole subtree — "a module is
+      // private" is a statement about everything under it, not about the folder
+      // node itself.
+      const exempt = globsOf(node.importedBy.matchNot ?? []).map((glob) =>
+        anchored(
+          `${pathSource}/${globToRegexSource(glob, compiled.captures, { declaring: false, nextGroup }).source}`,
+        ),
+      );
+      imports.push({
+        name: `${name}/imported-by`,
+        message: node.importedBy.message,
+        probe: { from: probeOutside("outsider", ownFolder), to: scopeProbe },
+        from: EVERY_FILE,
+        fromNot: globsOf(node.importedBy.allow).map(asTarget),
+        to: isFolder ? prefixed(`${pathSource}/`) : selfPattern,
+        ...(exempt.length > 0 ? { toNot: exempt } : {}),
+      });
+    }
+
+    for (const [index, spec] of (node.members ?? []).entries()) {
+      const asRegex = (globs: string | ReadonlyArray<string>) =>
+        globsOf(globs).map((one) =>
+          anchored(
+            globToRegexSource(one, compiled.captures, { declaring: false, nextGroup }).source,
+          ),
+        );
+      members.push({
+        name: `${name}/members-${String(index)}`,
+        message: spec.message,
+        // An authored probe replaces the synthetic site: the name is the one
+        // the author says the snippet declares, and the declaration is the
+        // parser's to find.
+        probe:
+          spec.probe === undefined
+            ? {
+                from: scopeProbe,
+                name: probeMemberName(spec.match),
+                ...(spec.in === undefined ? {} : { in: "ZzProbeRepositoryShape" }),
+                ...(spec.declares?.[0] === undefined ? {} : { declares: spec.declares[0] }),
+              }
+            : { from: scopeProbe, name: spec.probe.name, source: spec.probe.source },
+        // On a folder the rule covers the subtree, as `imports` does — a
+        // vocabulary is a statement about every file in a tier. Selecting the
+        // folder's own path instead governed no file, and the probe, a folder
+        // path, passed regardless.
+        from: scope,
+        subject: spec.subject,
+        ...(spec.in === undefined ? {} : { in: asRegex(spec.in) }),
+        ...(spec.declares === undefined ? {} : { declares: [...spec.declares] }),
+        ...(spec.match === undefined ? {} : { match: asRegex(spec.match) }),
+        ...(spec.matchNot === undefined ? {} : { matchNot: asRegex(spec.matchNot) }),
+        ...(spec.allow === undefined ? {} : { allow: asRegex(spec.allow) }),
+      });
+    }
+
+    for (const [index, spec] of (node.surface ?? []).entries()) {
+      const ruleName = `${name}/surface-${String(index)}`;
+      const asName = (globs: string | ReadonlyArray<string>) =>
+        globsOf(globs).map((one) =>
+          anchored(
+            globToRegexSource(one, compiled.captures, { declaring: false, nextGroup }).source,
+          ),
+        );
+      const asPath = (glob: string) =>
+        prefixed(
+          globToRegexSource(expandAliases(glob, aliases), compiled.captures, {
+            declaring: false,
+            nextGroup,
+          }).source,
+        );
+
+      const demands = [spec.allow, spec.convention, spec.count].filter(
+        (one) => one !== undefined,
+      ).length;
+      if (demands > 1) {
+        throw new Error(
+          `surface rule "${ruleName}" states more than one of allow, convention and count. ` +
+            `A rule makes one demand; write one entry per demand.`,
+        );
+      }
+
+      const kind = spec.kinds?.[0] ?? "named";
+      const conventionSource =
+        spec.convention === undefined
+          ? undefined
+          : typeof spec.convention === "string"
+            ? CONVENTIONS[spec.convention]?.source
+            : spec.convention.regex;
+
+      // The synthetic probe: one site the rule must reject, or for `count`, a
+      // surface of the wrong size. A count nothing can violate — no minimum, no
+      // maximum — is a rule that never reports, and is refused here.
+      const siteName =
+        kind === "default"
+          ? "default"
+          : kind === "namespace"
+            ? "*"
+            : spec.convention !== undefined
+              ? violatingSampleFor(spec.convention, ruleName)
+              : probeMemberName(spec.match);
+      const oneSite = {
+        name: siteName,
+        kind,
+        ...(spec.declares?.[0] === undefined ? {} : { declares: spec.declares[0] }),
+        ...(spec.reexport === undefined ? {} : { reexport: spec.reexport }),
+      };
+      const probeSites = (): ReadonlyArray<typeof oneSite> => {
+        if (spec.count === undefined) return [oneSite];
+        const min = spec.count.min ?? 0;
+        if (min > 0) return [];
+        if (spec.count.max === undefined) {
+          throw new Error(
+            `surface rule "${ruleName}" states a count with no minimum and no maximum, ` +
+              `which nothing can violate.`,
+          );
+        }
+        return Array.from({ length: spec.count.max + 1 }, (_, i) => ({
+          ...oneSite,
+          name: `${siteName}${String(i)}`,
+        }));
+      };
+
+      surface.push({
+        name: ruleName,
+        message: spec.message,
+        probe:
+          spec.probe === undefined
+            ? { from: scopeProbe, sites: probeSites() }
+            : { from: scopeProbe, source: spec.probe.source },
+        from: scope,
+        ...(spec.except === undefined ? {} : { fromNot: globsOf(spec.except).map(asPath) }),
+        ...(spec.kinds === undefined ? {} : { kinds: [...spec.kinds] }),
+        ...(spec.declares === undefined ? {} : { declares: [...spec.declares] }),
+        ...(spec.reexport === undefined ? {} : { reexport: spec.reexport }),
+        ...(spec.match === undefined ? {} : { match: asName(spec.match) }),
+        ...(spec.matchNot === undefined ? {} : { matchNot: asName(spec.matchNot) }),
+        ...(spec.forbid === undefined ? {} : { forbid: spec.forbid }),
+        ...(spec.allow === undefined ? {} : { allow: asName(spec.allow) }),
+        ...(conventionSource === undefined ? {} : { convention: conventionSource }),
+        ...(spec.count === undefined ? {} : { count: spec.count }),
+      });
+    }
+
+    if (node.requires !== undefined && node.requires.length > 0) {
+      const exempt = (node.requiresNot ?? []).map(
+        (basename) =>
+          `/${globToRegexSource(basename, compiled.captures, { declaring: false, nextGroup }).source}$`,
+      );
+      parity.push({
+        name: `${name}/requires`,
+        message: node.message ?? "This file needs its sibling.",
+        probe: { path: probePathOf(joinedGlob, "") },
+        file: selfPattern,
+        ...(exempt.length > 0 ? { fileNot: exempt } : {}),
+        requires: [...node.requires],
+      });
+    }
+  };
+
+  const emptyFrame: Frame = {
+    pathSource: "",
+    pathGlob: "",
+    captures: {},
+    nextGroup: 1,
+    allow: [],
+    externals: [],
+    importsMessage: "This import is not on this folder's allowlist.",
+    naming: undefined,
+  };
+
+  // Repo-wide prohibitions: `from` is every file, so no tier can be written
+  // that escapes them.
+  const globalFrame: Frame = { ...emptyFrame };
+  for (const [index, denial] of mergeImports(
+    globalFrame,
+    { unrestricted: true, deny: manifest.deny ?? [] },
+    aliases,
+    {},
+    1,
+  ).deny.entries()) {
+    imports.push({
+      name: `repo/deny-${String(index)}`,
+      message: denial.message,
+      probe: { from: probeOutside("anywhere"), to: denial.probe },
+      from: EVERY_FILE,
+      ...(denial.except.length > 0 ? { fromNot: [...denial.except] } : {}),
+      to: denial.match,
+      ...(denial.matchNot.length > 0 ? { toNot: [...denial.matchNot] } : {}),
+    });
+  }
+
+  for (const [key, node] of Object.entries(manifest.tree)) {
+    // A taxonomy root is a region whose folders are enumerated. A key naming a
+    // single file has no folders to deny, and an open tree governs every folder
+    // it contains — neither has anything for a root to catch.
+    if ((isFolderKey(key) || node.children !== undefined) && node.layout !== "open")
+      roots.push({
+        name: `${stripSlash(key)}/taxonomy`,
+        message:
+          node.message ??
+          "This folder is not part of the taxonomy. Declare it in the manifest deliberately, or move the file into the folder that owns it.",
+        probe: { path: probeIn(`${expandAliases(stripSlash(key), aliases)}/zzprobe`, "stray") },
+        path: prefixed(
+          globToRegexSource(
+            expandAliases(stripSlash(key), aliases),
+            {},
+            {
+              declaring: true,
+              nextGroup: 1,
+            },
+          ).source,
+        ),
+      });
+    walk(
+      key,
+      node,
+      emptyFrame,
+      stripSlash(key)
+        .replace(/[^a-zA-Z0-9]+/g, "-")
+        .replace(/^-|-$/g, ""),
+      Object.keys(manifest.tree),
+    );
+  }
+
+  for (const rule of manifest.exports ?? []) {
+    const asPattern = (glob: string) =>
+      prefixed(
+        globToRegexSource(expandAliases(glob, aliases), {}, { declaring: false, nextGroup: 1 })
+          .source,
+      );
+    // The synthetic probe is a binding of the rule's first kind. A default
+    // binding is only ever named `default` and a namespace one `*`, so a rule
+    // that lists `symbols` alongside those kinds cannot cover its probe — and
+    // is refused at load, which is right: it could never fire on such a form.
+    const kind = rule.kinds?.[0] ?? "named";
+    const symbol =
+      rule.probe?.symbol ??
+      (kind === "namespace" ? "*" : kind === "default" ? "default" : rule.symbols?.[0]) ??
+      "zzProbeSymbol";
+    exports.push({
+      name: rule.name,
+      message: rule.message,
+      probe: {
+        from: probeOutside("anywhere"),
+        to: probePathOf(expandAliases(globsOf(rule.module)[0] ?? "", aliases), ""),
+        symbol,
+        kind,
+        ...(rule.probe === undefined ? {} : { source: rule.probe.source }),
+      },
+      from: EVERY_FILE,
+      ...(rule.except === undefined ? {} : { fromNot: globsOf(rule.except).map(asPattern) }),
+      to: globsOf(rule.module).map(asPattern),
+      ...(rule.symbols === undefined ? {} : { symbols: [...rule.symbols] }),
+      ...(rule.kinds === undefined ? {} : { kinds: [...rule.kinds] }),
+      ...(rule.fix === undefined ? {} : { fix: rule.fix }),
+    });
+  }
+
+  // Graph rules pass through with their globs resolved, and a probe built from
+  // the shape each is about: two files importing each other, a file nothing
+  // imports, a direct edge from `from` to `to` that touches no `via`.
+  const asGraphPattern = (glob: string) =>
+    prefixed(
+      globToRegexSource(expandAliases(glob, aliases), {}, { declaring: false, nextGroup: 1 })
+        .source,
+    );
+  const asGraphPatterns = (globs: string | ReadonlyArray<string> | undefined) =>
+    globs === undefined ? undefined : globsOf(globs).map(asGraphPattern);
+  // A synthetic file inside a graph scope. A glob whose last segment names a
+  // file shape (`src/**/*.<ext>`) is filled in place and keeps its extension; a
+  // folder glob (`src/**`) gets a file of its language's added beneath it.
+  const probeFileIn = (globs: string | ReadonlyArray<string>, stem: string): string => {
+    const glob = expandAliases(globsOf(globs)[0] ?? "", aliases);
+    const at = glob.lastIndexOf("/");
+    const last = glob.slice(at + 1);
+    if (!last.includes(".")) return probeIn(glob, stem);
+    return probePathOf(
+      at === -1 ? "" : glob.slice(0, at),
+      last.replace(/\{[a-zA-Z][a-zA-Z0-9]*\}|\*+/g, stem),
+    );
+  };
+  const graph: GraphConfig = {
+    cycles: (manifest.graph?.cycles ?? []).map((rule) => {
+      const a = probeFileIn(rule.within, "zz-alpha");
+      const b = probeFileIn(rule.within, "zz-beta");
+      return {
+        name: rule.name,
+        message: rule.message,
+        probe: {
+          edges: [
+            [a, b],
+            [b, a],
+          ],
+        },
+        within: globsOf(rule.within).map(asGraphPattern),
+        ...(rule.withinNot === undefined
+          ? {}
+          : { withinNot: asGraphPatterns(rule.withinNot) ?? [] }),
+      };
+    }),
+    orphans: (manifest.graph?.orphans ?? []).map((rule) => ({
+      name: rule.name,
+      message: rule.message,
+      probe: { edges: [], files: [probeFileIn(rule.within, "zz-orphan")] },
+      within: globsOf(rule.within).map(asGraphPattern),
+      ...(rule.withinNot === undefined ? {} : { withinNot: asGraphPatterns(rule.withinNot) ?? [] }),
+      entry: globsOf(rule.entry).map(asGraphPattern),
+    })),
+    reach: (manifest.graph?.reach ?? []).map((rule) => ({
+      name: rule.name,
+      message: rule.message,
+      probe: {
+        edges: [[probeFileIn(rule.from, "zz-origin"), probeFileIn(rule.to, "zz-target")]],
+      },
+      from: globsOf(rule.from).map(asGraphPattern),
+      ...(rule.fromNot === undefined ? {} : { fromNot: asGraphPatterns(rule.fromNot) ?? [] }),
+      to: globsOf(rule.to).map(asGraphPattern),
+      ...(rule.toNot === undefined ? {} : { toNot: asGraphPatterns(rule.toNot) ?? [] }),
+      ...(rule.via === undefined ? {} : { via: asGraphPatterns(rule.via) ?? [] }),
+    })),
+  };
+
+  return {
+    imports,
+    exports,
+    members,
+    surface,
+    graph,
+    adoption: { unrestricted: unrestrictedNodes, partial: partialNodes },
+    structure: { roots, folders, parity, naming: namingRules },
+  };
+};