@ecoma-io/archkeep 0.13.0

package/src/rules/messages.mjs

@@ -0,0 +1,73 @@
+/**
+ * The fifteen violation messages, and the renderer that fills them.
+ *
+ * Every string below is a verbatim copy of `meta.messages` in
+ * `@nx/eslint-plugin`'s `enforce-module-boundaries` rule, and every key is that
+ * rule's `messageId` spelled exactly. The ids are the contract: a differential
+ * test can put this engine's verdict beside ESLint's for the same import and
+ * compare ids, which is the only way to know the two agree rather than merely
+ * both being red. `src/rules/upstream.integration.test.mjs` reads the installed
+ * plugin's source and fails when a copy here drifts from it.
+ *
+ * Copied rather than imported, and rather than derived: this
+ * project may import Node built-ins and `typescript` only (`../../AGENTS.md`),
+ * and importing the plugin would pull `@nx/devkit` — a project graph read — into
+ * a layer whose whole point is being pure. The value is intrinsic to a fixed
+ * external contract, it lives in exactly this one place, and the integration
+ * test is what keeps the copy honest.
+ */
+
+/**
+ * `messageId` → the template ESLint would render, `{{placeholder}}`s intact.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export const MESSAGES = Object.freeze({
+  noRelativeOrAbsoluteImportsAcrossLibraries: `Projects cannot be imported by a relative or absolute path, and must begin with a npm scope`,
+  noRelativeOrAbsoluteExternals: `External resources cannot be imported using a relative or absolute path`,
+  noCircularDependencies: `Circular dependency between "{{sourceProjectName}}" and "{{targetProjectName}}" detected: {{path}}\n\nCircular file chain:\n{{filePaths}}`,
+  noSelfCircularDependencies: `Projects should use relative imports to import from other files within the same project. Use "./path/to/file" instead of import from "{{imp}}"`,
+  noImportsOfApps: "Imports of apps are forbidden",
+  noImportsOfE2e: "Imports of e2e projects are forbidden",
+  noImportOfNonBuildableLibraries:
+    "Buildable libraries cannot import or export from non-buildable libraries",
+  noImportsOfLazyLoadedLibraries: `Static imports of lazy-loaded libraries are forbidden.\n\nLibrary "{{targetProjectName}}" is lazy-loaded in these files:\n{{filePaths}}`,
+  projectWithoutTagsCannotHaveDependencies: `A project without tags matching at least one constraint cannot depend on any libraries`,
+  bannedExternalImportsViolation: `A project tagged with "{{sourceTag}}" is not allowed to import "{{imp}}"`,
+  nestedBannedExternalImportsViolation: `A project tagged with "{{sourceTag}}" is not allowed to import "{{imp}}". Nested import found at {{childProjectName}}`,
+  noTransitiveDependencies: `Only packages defined in the "package.json" can be imported. Transitive or unresolvable dependencies are not allowed.`,
+  onlyTagsConstraintViolation: `A project tagged with "{{sourceTag}}" can only depend on libs tagged with {{tags}}`,
+  emptyOnlyTagsConstraintViolation: `A project tagged with "{{sourceTag}}" cannot depend on any libs with tags`,
+  notTagsConstraintViolation: `A project tagged with "{{sourceTag}}" can not depend on libs tagged with {{tags}}\n\nViolation detected in:\n{{projects}}`,
+});
+
+/** Every `messageId` this engine can produce — the checklist, as data. */
+export const MESSAGE_IDS = Object.freeze(Object.keys(MESSAGES));
+
+/**
+ * Renders a message the way ESLint's own reporter does: `{{key}}` (whitespace
+ * around the key tolerated) is replaced by `data[key]`, and a placeholder with
+ * no matching key is LEFT IN PLACE rather than blanked. That last part is
+ * deliberate upstream and worth keeping — a message reading `{{tags}}` tells a
+ * reader the rule forgot to pass data, where an empty string reads as a rule
+ * that found nothing to say.
+ *
+ * @param {string} messageId One of `MESSAGE_IDS`.
+ * @param {Record<string, string|number>} [data] Interpolation values.
+ * @returns {string}
+ * @throws {Error} for an unknown id — a typo in a rule must not ship a
+ *   violation whose text is the id itself.
+ */
+export function renderMessage(messageId, data = {}) {
+  const template = MESSAGES[messageId];
+  if (template === undefined) {
+    throw new Error(
+      `archkeep: no message template for '${messageId}' — ` +
+        `ids must match @nx/enforce-module-boundaries exactly (one of ${MESSAGE_IDS.join(", ")})`,
+    );
+  }
+  return template.replace(/\{\{([^{}]+?)\}\}/gu, (placeholder, key) => {
+    const name = key.trim();
+    return name in data ? String(data[name]) : placeholder;
+  });
+}

package/src/rules/reachability.mjs

@@ -0,0 +1,224 @@
+/**
+ * Who can reach whom in the project graph — the traversal two different rules
+ * need, so it lives beside neither of them.
+ *
+ * `noCircularDependencies` asks whether a path leads from the import's target
+ * back to its source, and `notDependOnLibsWithTags` asks which tagged projects
+ * are reachable FROM the target (upstream checks the whole transitive closure,
+ * not just the project being imported — see `../rules/tags.mjs`). Both are the
+ * same reachability question, and a second copy of it in the second rule is how
+ * two answers to one question start disagreeing.
+ *
+ * Ported from `@nx/eslint-plugin`'s `utils/graph-utils`, including the exact
+ * traversal order of `getPath`: the path it returns is interpolated into the
+ * `noCircularDependencies` message, so a different-but-equally-valid path would
+ * make a differential comparison against ESLint fail on text alone.
+ *
+ * Upstream caches the matrix on a module-level `reach` object keyed by graph
+ * identity. This builds it once per `evaluate` call and hands it down instead:
+ * a module-level cache in a module advertised as pure functions is state a
+ * caller cannot see, and the tool's second surface (a language server holding
+ * several graph revisions) is exactly where that bites.
+ */
+
+/**
+ * The adjacency list and full reachability matrix of a graph's PROJECT nodes.
+ * External (npm) nodes are excluded, as upstream excludes them: `adjList` only
+ * takes an edge whose target is a project node.
+ *
+ * @param {object} graph
+ * @returns {{ adjList: Record<string, string[]>, matrix: Record<string, Record<string, boolean>> }}
+ */
+export function buildReachability(graph) {
+  // Bound once so the membership test below asks the SAME map `nodes` was
+  // derived from, and so a graph that is only a shape (`buildReachability({})`)
+  // still answers instead of throwing.
+  const nodeMap = graph.nodes ?? {};
+  const nodes = Object.keys(nodeMap);
+  // Null-prototype for the same reason `../providers/native/graph.mjs` uses
+  // them: every key here is a project NAME, and project names come from the
+  // graph the caller built from attacker-controlled manifests — a plain `{}`
+  // would let a project literally named `__proto__` repoint the map's OWN
+  // prototype instead of adding an entry. The project then vanishes from the
+  // closure: `adjList["__proto__"]` reads the poisoned prototype (a Node
+  // object), `.filter`/`.push` are not functions, and the whole reachability
+  // walk throws `TypeError: adjList[current].filter is not a function` —
+  // exactly the diagnostic an LSP editor published in place of a boundary
+  // verdict. The matrix ROWS need the same protection as the outer maps: a
+  // row that is a plain `{}` reads `matrix[start][adj]` truthy whenever `adj`
+  // is `__proto__` (the inherited accessor answers `Object.prototype`), so the
+  // walk's `continue` skips the hop AND the write `matrix[start][__proto__]`
+  // is a no-op — one poisoned name silently cancels the whole walk through it.
+  /** @type {Record<string, string[]>} */
+  const adjList = Object.create(null);
+  /** @type {Record<string, Record<string, boolean>>} */
+  const matrix = Object.create(null);
+  for (const name of nodes) {
+    adjList[name] = [];
+    // Null-prototype rows: `matrix[name]` is keyed by project NAME too, and a
+    // project named `__proto__` must be a real, own, enumerable entry in it —
+    // the closure depends on both the read and the write behaving like any
+    // other project name (`Object.create(null)`'s absence of the inherited
+    // `__proto__` accessor is what makes the assignment add an entry instead
+    // of no-op on the prototype setter).
+    matrix[name] = Object.create(null);
+  }
+  for (const [source, dependencies] of Object.entries(graph.dependencies ?? {})) {
+    // Upstream indexes `adjList[dependency.source]` unguarded and throws on a
+    // dependency whose source is not a node. Skipping is the defensive
+    // difference: a graph half-built by a caller must not crash the enforcer
+    // into reporting nothing at all.
+    if (!adjList[source]) continue;
+    for (const dependency of dependencies ?? []) {
+      // `Object.hasOwn`, never `nodeMap[target]`: the caller's node map is
+      // usually a plain object (`JSON.parse` of `nx graph --file=`), so a
+      // truthiness test on it answers `constructor`, `toString`, `valueOf`,
+      // `hasOwnProperty` and `__proto__` from `Object.prototype` and admits an
+      // edge to a project that does not exist. That is not a quiet
+      // over-approximation here, it is a crash: `adjList` is null-prototype (by
+      // design, just above), so the phantom name gets pushed as a neighbour and
+      // then `adjList["constructor"]` reads back `undefined` on the very next
+      // hop — measured, `TypeError: adjList[current] is not iterable`, which
+      // takes down every rule that needs the closure and publishes a stack
+      // trace where a boundary verdict belonged. The `__proto__` sibling was
+      // already pinned; these four were not, because the prototype answers for
+      // them through inheritance rather than through the `__proto__` accessor.
+      if (Object.hasOwn(nodeMap, dependency.target)) adjList[source].push(dependency.target);
+    }
+  }
+  // Upstream's `traverse` is recursive; this is the same depth-first closure
+  // with an explicit stack, so a deep graph cannot overflow the call stack.
+  for (const start of nodes) {
+    const stack = [start];
+    matrix[start][start] = true;
+    while (stack.length > 0) {
+      const current = stack.pop();
+      for (const adj of adjList[current]) {
+        if (matrix[start][adj]) continue;
+        matrix[start][adj] = true;
+        stack.push(adj);
+      }
+    }
+  }
+  return { adjList, matrix };
+}
+
+/**
+ * Is `target` reachable from `source`? A project always reaches itself, which
+ * is what makes `findDependenciesWithTags` include the imported project itself.
+ *
+ * @param {{matrix: Record<string, Record<string, boolean>>}} reach
+ * @param {string} sourceProjectName
+ * @param {string} targetProjectName
+ * @returns {boolean}
+ */
+export function pathExists(reach, sourceProjectName, targetProjectName) {
+  if (sourceProjectName === targetProjectName) return true;
+  return !!reach.matrix[sourceProjectName]?.[targetProjectName];
+}
+
+/**
+ * The nodes on a path from `sourceProjectName` to `targetProjectName`, or `[]`
+ * when none exists.
+ *
+ * Ported move for move from upstream, `queue.pop()` included — that turns the
+ * nominal breadth-first queue into a depth-first walk, and the resulting path
+ * is what the circular-dependency message prints.
+ *
+ * @returns {object[]} project nodes, source first.
+ */
+export function getPath(reach, graph, sourceProjectName, targetProjectName) {
+  if (sourceProjectName === targetProjectName) return [];
+  const { adjList, matrix } = reach;
+  let path = [];
+  const queue = [[sourceProjectName, path]];
+  const visited = [sourceProjectName];
+
+  while (queue.length > 0) {
+    const [current, p] = queue.pop();
+    path = [...p, current];
+    if (current === targetProjectName) break;
+    if (!adjList[current]) break;
+    adjList[current]
+      .filter((adj) => visited.indexOf(adj) === -1)
+      .filter((adj) => matrix[adj]?.[targetProjectName])
+      .forEach((adj) => {
+        visited.push(adj);
+        queue.push([adj, [...path]]);
+      });
+  }
+  return path.length > 1 ? path.map((n) => graph.nodes[n]) : [];
+}
+
+/**
+ * The cycle an import would close: a path from the TARGET back to the SOURCE.
+ * Empty when the import creates no cycle.
+ *
+ * The direction is the subtle half. The edge being judged is source → target;
+ * a cycle exists only if the graph already carries a way back, so upstream asks
+ * for the reverse path and never adds the new edge to the graph first.
+ */
+export function checkCircularPath(reach, graph, sourceProject, targetProject) {
+  // `Object.hasOwn` for the same reason `buildReachability` above uses it: this
+  // guard exists to refuse a target the graph does not contain, and a
+  // truthiness test on a plain node map answers `constructor`/`toString` and
+  // friends from `Object.prototype` — so the guard let exactly the names it was
+  // written to stop walk straight past it.
+  if (!Object.hasOwn(graph.nodes ?? {}, targetProject.name)) return [];
+  return getPath(reach, graph, targetProject.name, sourceProject.name);
+}
+
+/**
+ * Does any consecutive pair on this path appear in the ignore map? Checked
+ * pairwise rather than end to end, so ignoring one hop excuses every cycle
+ * running through it.
+ *
+ * @param {{name: string}[]} circularPath
+ * @param {Map<string, Set<string>>} ignored
+ * @returns {boolean}
+ */
+export function circularPathHasPair(circularPath, ignored) {
+  if (circularPath.length < 2) return false;
+  for (let i = 0; i < circularPath.length - 1; i++) {
+    if (ignored.get(circularPath[i].name)?.has(circularPath[i + 1].name)) return true;
+  }
+  return false;
+}
+
+/**
+ * Expands `ignoredCircularDependencies` pairs into the symmetric map the
+ * pairwise check reads. Both directions are recorded, because upstream records
+ * both: ignoring `[a, b]` excuses `a → b` and `b → a`.
+ *
+ * @param {[string, string][]} ignoredCircularDependencies
+ * @param {object} graph
+ * @param {(patterns: string[], nodes: object) => string[]} findMatchingProjects
+ *   Injected rather than imported so this module keeps knowing only about
+ *   graphs; `../config.mjs` has already rejected any pattern the matcher cannot
+ *   reproduce, so a throw from here means validation was skipped.
+ * @returns {Map<string, Set<string>>}
+ */
+export function expandIgnoredCircularDependencies(
+  ignoredCircularDependencies,
+  graph,
+  findMatchingProjects,
+) {
+  const allowed = new Map();
+  const add = (from, to) => {
+    if (!allowed.has(from)) allowed.set(from, new Set());
+    allowed.get(from).add(to);
+  };
+  for (const [a, b] of ignoredCircularDependencies) {
+    const setA = findMatchingProjects([a], graph.nodes);
+    const setB = findMatchingProjects([b], graph.nodes);
+    for (const projectA of setA) {
+      if (!allowed.has(projectA)) allowed.set(projectA, new Set());
+      for (const projectB of setB) add(projectA, projectB);
+    }
+    for (const projectB of setB) {
+      if (!allowed.has(projectB)) allowed.set(projectB, new Set());
+      for (const projectA of setA) add(projectB, projectA);
+    }
+  }
+  return allowed;
+}

package/src/rules/specifiers.mjs

@@ -0,0 +1,300 @@
+/**
+ * The rules decided on the raw import specifier — the text as written, before
+ * anything resolves it.
+ *
+ * Four of the fifteen violations live here, and they are the reason the
+ * analysis record keeps `specifier` verbatim instead of collapsing to a graph
+ * edge (`../analysis/contract.md`, "superset of a graph edge"): the projects
+ * involved can be entirely correct while the SPELLING is the violation.
+ *
+ * Upstream uses two relative-path predicates that differ by two characters, in
+ * different places, deliberately or otherwise:
+ *
+ *   isRelative(s)      './' or '../'                       — used to decide
+ *                      whether a specifier is a path worth resolving
+ *   isRelativePath(s)  '.', '..', './' or '../'            — used to decide
+ *                      whether an unresolvable import is a path at all, and
+ *                      whether a self-import is spelled relatively
+ *
+ * A bare `.` or `..` is therefore a path to one and a package name to the
+ * other, and collapsing them changes which rule fires on `import x from ".."`.
+ * Only the first lives here. The second was a question about SPELLING, and
+ * spelling is per-language: `.`, `..`, `./`, `../` is JavaScript's shape, while
+ * Rust spells the same idea `crate::`/`self::`/`super::` and Python spells it
+ * `.mod`/`..pkg`. It moved to the layer that knows which language it is reading
+ * — every record now carries `spelling` (`../analysis/contract.md`), and
+ * `isRelativePath`'s text lives on as `specifierSpelling` in
+ * `../analysis/typescript.mjs`, applied to the family it was written for.
+ *
+ * `isRelative` stays because its caller below is path ARITHMETIC rather than a
+ * judgement about spelling: it joins the specifier onto the source file's
+ * directory, which only a filesystem path can survive.
+ */
+import { posix } from "node:path";
+import { isBuiltin } from "node:module";
+
+import { assertMatchableSpecifier, mapGlobToRegExp } from "./match.mjs";
+import { findConstraintsFor } from "./tags.mjs";
+import { pathExists } from "./reachability.mjs";
+
+/**
+ * Nx's default `workspaceLayout`. Applied when the graph does not carry one,
+ * because upstream applies exactly this default when `nx.json` omits the key —
+ * the value is intrinsic to the upstream contract, not a preference of ours, and
+ * getting it wrong changes which imports count as "absolute into another
+ * project".
+ */
+export const DEFAULT_WORKSPACE_LAYOUT = Object.freeze({ libsDir: "libs", appsDir: "apps" });
+
+/** `./x` or `../x` — upstream's `isRelative`, from `runtime-lint-utils`. */
+export function isRelative(s) {
+  return s.startsWith("./") || s.startsWith("../");
+}
+
+/**
+ * The package a specifier belongs to: `@scope/pkg` for `@scope/pkg/deep/path`,
+ * `pkg` for `pkg/deep/path`. Port of nx's `getPackageNameFromImportPath`.
+ */
+export function getPackageNameFromImportPath(importExpression) {
+  if (importExpression.startsWith("@")) {
+    return importExpression.split("/").slice(0, 2).join("/");
+  }
+  return importExpression.split("/")[0];
+}
+
+/**
+ * Node built-ins, including the experimental ones Nx lists explicitly.
+ *
+ * `node:module`'s `isBuiltin` is the same function Nx calls, so the answer
+ * agrees by construction rather than by a list we would have to maintain. It is
+ * a Node built-in itself, so importing it keeps this layer's "built-ins only"
+ * rule intact and adds no I/O — the check is a table lookup.
+ *
+ * It answers for NODE, and this engine also judges Go, Rust and Python. A Go
+ * import of `net/http` reduces to the package `net`, which Node also has, so it
+ * is treated as a built-in here. The only consequence is that
+ * `banTransitiveDependencies` does not fire on it — the direction that produces
+ * no false alarm, and `bannedExternalImports` still sees it (see `./index.mjs`,
+ * which synthesises an external node for an external record whose specifier
+ * names a package; a path names none and gets none).
+ */
+export function isBuiltinModuleImport(importExpr) {
+  const packageName = getPackageNameFromImportPath(importExpr);
+  return isBuiltin(packageName) || packageName === "node:sqlite";
+}
+
+/** Nx's `normalizeProjectRoot`: `''` is the workspace root, trailing `/` goes. */
+export function normalizeProjectRoot(root) {
+  const value = root === "" ? "." : root;
+  return value && value.endsWith("/") ? value.substring(0, value.length - 1) : value;
+}
+
+/**
+ * `projectRoot → projectName`, the map every path lookup walks.
+ *
+ * @param {Record<string, {data: {root: string}}>} nodes
+ * @returns {Map<string, string>}
+ */
+export function createProjectRootMappings(nodes) {
+  const mappings = new Map();
+  for (const [name, node] of Object.entries(nodes)) {
+    mappings.set(normalizeProjectRoot(node.data.root), name);
+  }
+  return mappings;
+}
+
+/**
+ * The project owning a workspace-relative path, by walking up its directories
+ * until one is a project root. Port of nx's `findProjectForPath`, with POSIX
+ * path semantics fixed in — the analysis contract states every path it emits is
+ * workspace-relative and `/`-separated, so there is no platform to detect.
+ *
+ * @returns {string|undefined} project name.
+ */
+export function findProjectForPath(filePath, projectRootMappings) {
+  let currentPath = filePath;
+  for (; currentPath !== posix.dirname(currentPath); currentPath = posix.dirname(currentPath)) {
+    const found = projectRootMappings.get(currentPath);
+    if (found) return found;
+  }
+  return projectRootMappings.get(currentPath);
+}
+
+/**
+ * Is this specifier an absolute path into another project — `libs/foo/bar`,
+ * `/apps/baz`? Port of `isAbsoluteImportIntoAnotherProject`.
+ *
+ * Note what it does NOT do: it never checks that the path lands in a different
+ * project than the source. Writing `libs/foo/x` from inside `libs/foo` is
+ * reported too, because the spelling is the violation.
+ */
+export function isAbsoluteImportIntoAnotherProject(
+  imp,
+  workspaceLayout = DEFAULT_WORKSPACE_LAYOUT,
+) {
+  return (
+    imp.startsWith(`${workspaceLayout.libsDir}/`) ||
+    imp.startsWith(`/${workspaceLayout.libsDir}/`) ||
+    imp.startsWith(`${workspaceLayout.appsDir}/`) ||
+    imp.startsWith(`/${workspaceLayout.appsDir}/`)
+  );
+}
+
+/**
+ * The project a relative specifier points into, by path arithmetic alone — no
+ * extension probing, no `exports` conditions, exactly as upstream does it. A
+ * relative import is judged on where its text lands in the tree, so it needs no
+ * module resolver and this layer stays free of one.
+ *
+ * @returns {string|undefined} project name.
+ */
+export function getTargetProjectBasedOnRelativeImport(imp, sourceFile, projectRootMappings) {
+  if (!isRelative(imp)) return undefined;
+  const resolved = posix.normalize(posix.join(posix.dirname(sourceFile), imp));
+  // Upstream resolves against an absolute workspace root, so a specifier
+  // climbing out of the workspace clamps at `/` and then produces a nonsense
+  // relative path. Here it stays visible as a leading `..`, and nothing outside
+  // the workspace can be in a project — so there is no target, which is the
+  // same verdict by a route that cannot accidentally match a project.
+  if (resolved === ".." || resolved.startsWith("../")) return undefined;
+  return findProjectForPath(resolved, projectRootMappings);
+}
+
+/**
+ * Does this constraint ban this external import? Port of
+ * `isConstraintBanningProject`, whose three steps each hide something:
+ *
+ * 1. The constraint only speaks about imports OF THIS PACKAGE. `imp` must be
+ *    the package name itself or a path under it, otherwise the row is silent —
+ *    which is what makes `nestedBannedExternalImportsViolation` so hard to
+ *    trigger (see `hasBannedDependencies`).
+ * 2. `bannedExternalImports` is matched with `mapGlobToRegExp` against the FULL
+ *    specifier, so `@scope/pkg/*` bans the deep paths while leaving the entry
+ *    point importable, and `@scope/pkg*` bans both.
+ * 3. `allowedExternalImports` is an allowlist evaluated with `.every()`: an
+ *    import is banned when it matches NONE of the entries. Two consequences —
+ *    an absent list bans nothing (`undefined?.every` short-circuits), and an
+ *    EMPTY list `[]` bans every import of the package, because `[].every()` is
+ *    `true`. The empty case reads like "no restrictions" and means the opposite.
+ *
+ * This is the door where a specifier meets a pattern the consumer wrote, and
+ * so where the specifier's LENGTH is bounded — `./match.mjs`'s
+ * `MAX_SPECIFIER_LENGTH` carries the measurement and
+ * `assertMatchableSpecifier` the reason it throws instead of returning
+ * `false`. The bound is checked before the package test rather than after,
+ * because the question it answers is not "does this row speak about this
+ * import" but "can this import be judged at all": a specifier this engine
+ * declines to match is unjudged wherever it appears, and an unjudged site
+ * reported as clean is the one outcome `../../../../AGENTS.md` ranks below a
+ * wrong answer.
+ *
+ * @returns {boolean}
+ */
+export function isConstraintBanningProject(externalProject, constraint, imp) {
+  assertMatchableSpecifier(imp, "import specifier judged against the constraint table");
+  const { allowedExternalImports, bannedExternalImports } = constraint;
+  const { packageName } = externalProject.data;
+  if (imp !== packageName && !imp.startsWith(`${packageName}/`)) return false;
+  if (bannedExternalImports?.some((definition) => mapGlobToRegExp(definition).test(imp))) {
+    return true;
+  }
+  return Boolean(
+    allowedExternalImports?.every(
+      (definition) => !imp.startsWith(packageName) || !mapGlobToRegExp(definition).test(imp),
+    ),
+  );
+}
+
+/**
+ * The first constraint (matching the source project) that bans this external
+ * import, or `undefined`.
+ *
+ * Upstream re-derives the source-matching filter inline here; it is
+ * `findConstraintsFor` spelled a second way, so this calls the one
+ * implementation rather than keeping a second that could drift. `find`, not
+ * `filter`: one violation is reported, naming the first row that objects.
+ */
+export function hasBannedImport(sourceProject, targetProject, depConstraints, imp) {
+  return findConstraintsFor(depConstraints, sourceProject).find((constraint) =>
+    isConstraintBanningProject(targetProject, constraint, imp),
+  );
+}
+
+/**
+ * Every external dependency reachable from `source`, including its own.
+ * Only computed when `checkNestedExternalImports` is on.
+ *
+ * @returns {{source: string, target: string, type?: string}[]}
+ */
+export function findTransitiveExternalDependencies(graph, reach, source) {
+  if (!graph.externalNodes) return [];
+  const externalDependencies = [];
+  // Both maps are keyed by NAME — project names in `dependencies`, package
+  // names in `externalNodes` — and both arrive as plain objects from
+  // `JSON.parse` of `nx graph --file=`, so every lookup below is an
+  // `Object.hasOwn` membership test rather than an index-and-hope. A project
+  // literally named `constructor`, `toString`, `valueOf`, `hasOwnProperty` or
+  // `__proto__` is otherwise answered by `Object.prototype`, and both reads
+  // break loudly and uselessly: `dependencies["constructor"]` yields the
+  // `Object` constructor FUNCTION, which `?? []` does not replace (a function
+  // is not nullish) and `for…of` then rejects — measured, `TypeError: function
+  // is not iterable` — while `externalNodes["toString"]` classifies a real
+  // internal project as an external package and hands it to
+  // `isConstraintBanningProject`, which destructures `.data` off
+  // `Function.prototype.toString` and throws. An enforcer that throws reports
+  // nothing at all, which `../../AGENTS.md` ranks below a wrong answer.
+  const dependencies = graph.dependencies ?? {};
+  for (const projectName of Object.keys(graph.nodes)) {
+    if (!pathExists(reach, source.name, projectName)) continue;
+    if (!Object.hasOwn(dependencies, projectName)) continue;
+    for (const dependency of dependencies[projectName] ?? []) {
+      if (Object.hasOwn(graph.externalNodes, dependency.target)) {
+        externalDependencies.push(dependency);
+      }
+    }
+  }
+  return externalDependencies;
+}
+
+/**
+ * The nested external dependencies this constraint bans, as
+ * `[externalNode, violatingSourceNode, constraint]` triples.
+ *
+ * **Read the `imp` argument carefully.** It is the specifier of the import
+ * being judged — which, at this point in the pipeline, resolves to a PROJECT,
+ * not to any of the external packages being scanned. `isConstraintBanningProject`
+ * returns false immediately unless that specifier is the nested package's name
+ * or a path under it, so this fires only where a project's import alias and a
+ * transitively-reachable package name coincide. That is upstream's behaviour in
+ * `@nx/eslint-plugin` 23.1.1, reproduced rather than corrected: this engine's
+ * contract is to agree with ESLint's verdict, and a "fixed" version here would
+ * report violations ESLint does not, breaking the parity that makes the two
+ * comparable. It is recorded as a finding instead.
+ */
+export function hasBannedDependencies(externalDependencies, graph, constraint, imp) {
+  // Exported, so it is reachable with a list this module did not build — the
+  // membership guard belongs here too, not only in
+  // `findTransitiveExternalDependencies` above. Same failure either way: an
+  // inherited `Object.prototype` member reaching `isConstraintBanningProject`
+  // is destructured for `.data` and throws, and a checker that throws reports
+  // nothing.
+  //
+  // BOTH maps, for the same reason and by the same test. `nodes` is read by
+  // `dependency.source` and its value becomes the violation's
+  // `childProjectName` (`./index.mjs`), so a source named `constructor` or
+  // `toString` yields a `Function` where a project node belongs and the report
+  // names `Object` — a project no workspace has — while an absent `nodes`
+  // throws on the index. A project genuinely named `constructor` is an OWN key
+  // and still answers here; only the inherited phantoms are dropped, and a
+  // phantom source names no project to report against.
+  const externalNodes = graph.externalNodes ?? {};
+  const nodes = graph.nodes ?? {};
+  return externalDependencies
+    .filter(
+      (dependency) =>
+        Object.hasOwn(externalNodes, dependency.target) &&
+        Object.hasOwn(nodes, dependency.source) &&
+        isConstraintBanningProject(externalNodes[dependency.target], constraint, imp),
+    )
+    .map((dep) => [externalNodes[dep.target], nodes[dep.source], constraint]);
+}