@ecoma-io/archkeep 0.13.0

package/src/providers/native/discover.mjs

@@ -0,0 +1,431 @@
+/**
+ * Declared ∪ inferred project discovery over a `archkeep.json`-rooted
+ * workspace — no Nx, no `project.json` requirement, no assumption about
+ * directory layout.
+ *
+ * Two sources merge into one project list, declared winning field-by-field:
+ * every `projects.declared` row names a project outright, and every tracked
+ * manifest matching `projects.infer` (`project.json`, `package.json`, `go.mod`,
+ * `Cargo.toml`, `pyproject.toml` unless the model says otherwise) contributes
+ * one more UNLESS its directory is already a declared root. Name precedence
+ * reproduces Nx's own exactly — `discoverProjects` in `../../lsp/workspace-index.mjs`
+ * is the oracle: `config.name ?? packageName ?? directoryBasename` — so a tree
+ * that used to run Nx and now runs `archkeep.json` names its projects the same
+ * way it always did.
+ *
+ * Tags are a UNION, never a precedence: a project's own declared tags, every
+ * `projectRules` row whose `match` covers its root, and its `project.json`
+ * tags if it has one, all merge — sorted, deduplicated, with provenance kept
+ * on the side (`tagOrigins`) rather than inside the tag list itself, because a
+ * tag can arrive from more than one source and the rule engine
+ * (`../../rules/tags.mjs`) only ever needs to know a project HAS a tag, never
+ * where it came from.
+ *
+ * `nodeTypeOf` and `PROJECT_CONFIG_FILE` live here rather than in
+ * `../../lsp/workspace-index.mjs`, which used to define them: this module is
+ * the promotion target (`../../../AGENTS.md`, "`src/providers/` is the layer
+ * that supplies a graph to `evaluate()`"), and `../../lsp/workspace-index.mjs`
+ * now imports both from here. Defining them there instead would mean
+ * importing `../../lsp/workspace-index.mjs` from this module — which imports
+ * `../../workspace.mjs`, which loads the TypeScript compiler at module scope
+ * (`../../process.mjs`'s header) — for two functions that need nothing beyond
+ * a string.
+ */
+import { fileFailure } from "../../analysis/source-util.mjs";
+import { parseNxJson } from "../../nx-json.mjs";
+import { projectPatternError } from "../../rules/match.mjs";
+import { matchesGlob } from "./model.mjs";
+
+/** The file Nx reads to learn a project exists — and so does this. */
+export const PROJECT_CONFIG_FILE = "project.json";
+
+/**
+ * Nx's own `getProjectType`, reproduced over the same inputs.
+ *
+ * Reproduced rather than reached, unlike `../../nx-json.mjs`'s parser: Nx
+ * keeps this one as a module-private function of `normalize-project-nodes`,
+ * which exports two other names and not this. What makes reproducing it safe
+ * is that the rule is Nx's own convention — the `-e2e` suffix is a naming Nx
+ * defines, never one this workspace supplies — so nothing here assumes
+ * anything about the tree it runs over.
+ *
+ * The filesystem fallbacks Nx applies when `projectType` is absent are NOT
+ * reproduced. Nx probes for `tsconfig.lib.json`, `tsconfig.app.json` and a
+ * `package.json` entry point; a project that states no `projectType` lands on
+ * `lib` here. That direction is the safe one: `lib` is the only type with no
+ * blanket import ban, so a mis-typed project is judged by its tags rather than
+ * refused outright by a rule that never should have fired.
+ *
+ * @param {string} name
+ * @param {string|undefined} projectType From `project.json`.
+ * @returns {"app"|"e2e"|"lib"}
+ */
+export function nodeTypeOf(name, projectType) {
+  if (projectType === "application") {
+    return name.endsWith("-e2e") || name === "e2e" ? "e2e" : "app";
+  }
+  return "lib";
+}
+
+/** The directory part of a workspace-relative path; `""` at the tree root. */
+const directoryOf = (file) => {
+  const slash = file.lastIndexOf("/");
+  return slash === -1 ? "" : file.slice(0, slash);
+};
+
+/** `root`'s own basename, Nx's own fallback when nothing else names a project. */
+const basenameOf = (root) => (root === "" ? "" : root.slice(root.lastIndexOf("/") + 1));
+
+/**
+ * `project.json` at `projectRoot`, parsed the same JSONC-tolerant way
+ * `../../nx-json.mjs` reads every other config this package trusts —
+ * `../../lsp/workspace-index.mjs` reads its own copy of `project.json` the
+ * same way, so a trailing comma or a comment that Nx itself accepts is not a
+ * reason for this provider to disagree with it.
+ *
+ * `.json` is not an analyzable extension (`../../analysis/analyze.mjs`'s
+ * `LANGUAGE_BY_EXTENSION`), so `../../workspace.mjs`'s own analysis pass never
+ * looks at this file and never reports it broken — a `project.json` this
+ * function cannot parse would otherwise cost its project every field the
+ * manifest carries (`tags`, `type`, `implicitDependencies`) with nothing
+ * anywhere naming why, which is exactly the silent hole
+ * `../../../../../AGENTS.md`'s invariant refuses. So a parse failure is returned
+ * here as a `failure` (a `fileFailure`, the same whole-file record shape a
+ * language analyzer produces for an unreadable file) rather than swallowed:
+ * the project still keeps its row — `discoverNativeProjects` below, same as
+ * before — but the caller surfaces the broken manifest as its own finding.
+ *
+ * The same refusal applies to a null read of a TRACKED manifest: the reader
+ * (`../../commands/context.mjs`'s `readWorkspaceRoot`, `../../lsp/workspace-index.mjs`'s
+ * `readWorkspaceFile`) already refuses a containment escape — a tracked symlink
+ * whose realpath leaves the workspace — by returning null. Treating that null
+ * as "no manifest" would silently re-read the project as named by its
+ * directory basename, outside bytes purged but the wrong verdict still clean.
+ * So a tracked manifest that reads null is surfaced as a `fileFailure`, the
+ * identical loud shape a parse failure gets (`../../containment.mjs`, the
+ * read-side G-10 closure).
+ *
+ * @param {string} projectRoot Workspace-relative project root (`""` for the
+ *   workspace root itself).
+ * @param {(path: string) => string|null} readFile
+ * @param {(path: string) => boolean} isTracked Whether `path` (workspace-relative)
+ *   is in the tracked file list.
+ * @returns {{manifest: {name?: string, tags?: string[], projectType?: string, implicitDependencies?: string[]}|undefined, failure: object|undefined}}
+ */
+function readProjectManifest(projectRoot, readFile, isTracked) {
+  const path = projectRoot === "" ? PROJECT_CONFIG_FILE : `${projectRoot}/${PROJECT_CONFIG_FILE}`;
+  const text = readFile(path);
+  if (text === null) {
+    // A null read is "no such file" only when the tree does not track one; a
+    // tracked manifest that cannot be read was refused (containment) or is
+    // missing from the working tree — either way the project must not silently
+    // fall back to its basename.
+    if (isTracked(path)) {
+      return { manifest: undefined, failure: fileFailure(path, "could not be read") };
+    }
+    return { manifest: undefined, failure: undefined };
+  }
+  try {
+    return { manifest: parseNxJson(text), failure: undefined };
+  } catch (cause) {
+    return {
+      manifest: undefined,
+      failure: fileFailure(path, `could not be parsed as JSON: ${cause?.message ?? cause}`),
+    };
+  }
+}
+
+/**
+ * `package.json`'s `name` at `root` — the second rung of the name-precedence
+ * ladder — read the same JSONC-tolerant way `project.json` is
+ * (`readProjectManifest` above), not with a bare `JSON.parse`.
+ *
+ * This is not a formality: Nx itself resolves a `package.json` project node's
+ * name through `readJsonFile` → `parseJson` — measured against the installed
+ * `nx`, `dist/plugins/package-json.js`'s `createNodeFromPackageJson` reads
+ * every tracked `package.json` that way, the same `jsonc-parser` Nx reads
+ * `nx.json` and `project.json` with — even though `npm install` itself is
+ * strict JSON about the same file. `../../lsp/workspace-index.mjs`'s
+ * `discoverProjects`, the oracle this module's own header cites for name
+ * precedence, reads `package.json` through that same reader
+ * (`parseProjectJson`, its local name for `parseNxJson`) for exactly that
+ * reason. A bare `JSON.parse` here would read a `package.json` carrying a
+ * trailing comma or a `//` comment as unparseable while Nx reads it fine,
+ * naming the project differently than Nx does for a config Nx accepts.
+ *
+ * A `package.json` that will not parse even with that reader is surfaced as a
+ * `fileFailure`, never swallowed into "no name": falling back to the
+ * directory basename here would cost the project its real identity with
+ * nothing anywhere naming why — an import that targets it by name would
+ * resolve as external rather than cross-project, unnoticed. The same silent
+ * hole `readProjectManifest`'s own header describes for `project.json`.
+ *
+ * @param {string} projectRoot Workspace-relative project root (`""` for the
+ *   workspace root itself).
+ * @param {(path: string) => string|null} readFile
+ * @param {(path: string) => boolean} isTracked Whether `path` (workspace-relative)
+ *   is in the tracked file list.
+ * @returns {{name: string|undefined, failure: object|undefined}}
+ */
+function readPackageName(projectRoot, readFile, isTracked) {
+  const path = projectRoot === "" ? "package.json" : `${projectRoot}/package.json`;
+  const text = readFile(path);
+  if (text === null) {
+    // The same tracked-but-unreadable rule `readProjectManifest` applies: a
+    // null read is "no package.json" only when the tree tracks none.
+    if (isTracked(path)) {
+      return { name: undefined, failure: fileFailure(path, "could not be read") };
+    }
+    return { name: undefined, failure: undefined };
+  }
+  try {
+    const parsed = parseNxJson(text);
+    return {
+      name: typeof parsed?.name === "string" ? parsed.name : undefined,
+      failure: undefined,
+    };
+  } catch (cause) {
+    return {
+      name: undefined,
+      failure: fileFailure(path, `could not be parsed as JSON: ${cause?.message ?? cause}`),
+    };
+  }
+}
+
+/**
+ * Every workspace-relative directory `projects.infer` covers: a tracked
+ * manifest's own directory, when its basename is in `infer.manifests` and its
+ * path matches `infer.include` and none of `infer.exclude`.
+ *
+ * @param {{files: string[], infer: {manifests: string[], include: string[], exclude: string[]}}} args
+ * @returns {Set<string>}
+ */
+function inferProjectRoots({ files, infer }) {
+  const roots = new Set();
+  for (const file of files) {
+    const base = file.slice(file.lastIndexOf("/") + 1);
+    if (!infer.manifests.includes(base)) continue;
+    if (!infer.include.some((pattern) => matchesGlob(file, pattern))) continue;
+    if (infer.exclude.some((pattern) => matchesGlob(file, pattern))) continue;
+    roots.add(directoryOf(file));
+  }
+  return roots;
+}
+
+/**
+ * Declared ∪ inferred discovery, tag union, and every discovery-time defect
+ * `archkeep.json` can state that does not hold up against the tree: a declared
+ * root with no tracked file under it, a `projectRules` row matching no
+ * project, two projects resolving to the same name, and a workspace
+ * describing zero projects at all.
+ *
+ * Every one of those throws — a defect in the model IS a "could not reach a
+ * verdict" failure (`../../../../../AGENTS.md`, "An empty result is a claim, not a
+ * shrug"): a `projectRules` row that silently matched nothing would report a
+ * clean workspace exactly like one where every project really does carry the
+ * tag, and the two are not the same fact.
+ *
+ * @param {{root: string, files: string[], readFile: (path: string) => string|null, model: object}} args
+ *   `model` is a `NativeModel` from `./model.mjs`.
+ * @returns {{projects: {name: string, root: string, type: "app"|"e2e"|"lib", tags: string[], tagOrigins: Record<string, string[]>, implicitDependencies: string[], targets: string[]}[], failures: object[]}}
+ * @throws {Error} named `archkeep: archkeep.json describes a workspace that does not match the tree`.
+ */
+export function discoverNativeProjects({ root, files, readFile, model }) {
+  const violations = [];
+  const failures = [];
+  const declaredByRoot = new Map();
+  for (const row of model.projects.declared) {
+    if (declaredByRoot.has(row.root)) {
+      violations.push(`projects.declared: two rows declare the same root '${row.root}'`);
+      continue;
+    }
+    declaredByRoot.set(row.root, row);
+  }
+
+  for (const declaredRoot of declaredByRoot.keys()) {
+    // Strict containment only: `file === declaredRoot` used to also pass, so
+    // a tracked FILE sharing its exact path with a declared root (a
+    // `README.md` sitting where a project's directory ought to be, say)
+    // could back a root that names no real directory at all. Only a file
+    // genuinely inside the root's directory counts.
+    const hasFile =
+      declaredRoot === "" || files.some((file) => file.startsWith(`${declaredRoot}/`));
+    if (!hasFile) {
+      violations.push(
+        `projects.declared: root '${declaredRoot}' has no tracked file under it — nothing in ` +
+          `the tree backs this project`,
+      );
+    }
+  }
+
+  const inferredRoots = model.projects.infer
+    ? inferProjectRoots({ files, infer: model.projects.infer })
+    : new Set();
+
+  const allRoots = new Set([...declaredByRoot.keys(), ...inferredRoots]);
+
+  const resolved = [];
+  for (const projectRoot of allRoots) {
+    const declared = declaredByRoot.get(projectRoot);
+    const isTracked = (path) => files.includes(path);
+    const { manifest, failure } = readProjectManifest(projectRoot, readFile, isTracked);
+    if (failure) failures.push(failure);
+    // Read unconditionally, not only when `project.json` is absent: a
+    // `project.json` that EXISTS but omits `name` is still a truthy
+    // `manifest`, and `manifest?.name` alone is `undefined` in that case —
+    // gating this read on `manifest` being falsy skipped `package.json`
+    // entirely for that project, landing straight on the directory basename
+    // and skipping the middle rung of the precedence chain below.
+    // `../../lsp/workspace-index.mjs`'s `discoverProjects` — the oracle this
+    // module's own header names for this exact precedence — reads
+    // `package.json` the same unconditional way for the same reason.
+    const { name: packageName, failure: packageFailure } = readPackageName(
+      projectRoot,
+      readFile,
+      isTracked,
+    );
+    if (packageFailure) failures.push(packageFailure);
+    // Nx's own precedence, reproduced exactly (`../../lsp/workspace-index.mjs`,
+    // `discoverProjects`): a declared name, then `project.json`'s, then
+    // `package.json`'s, then the directory basename.
+    const name = declared?.name ?? manifest?.name ?? packageName ?? basenameOf(projectRoot);
+    if (typeof name !== "string" || name === "") {
+      violations.push(
+        `projects: no name resolves for the project at root '${projectRoot}' — declare a ` +
+          `'name' for it in projects.declared`,
+      );
+      continue;
+    }
+
+    // Null-prototype: every key here is a TAG, and tags are workspace text —
+    // `archkeep.json`'s `projects.declared[].tags`, a `projectRules` row, a
+    // tracked `project.json` — so a pull request can name one `toString`,
+    // `constructor`, `valueOf`, `hasOwnProperty` or `__proto__`. On a plain
+    // `{}` the `??=` below finds an inherited member instead of `undefined`,
+    // keeps it, and calls `.add` on it: measured, `TypeError:
+    // tagOrigins[tag].add is not a function`, printed verbatim with no
+    // `archkeep:` prefix, no file and no row, on the exit-3 path.
+    //
+    // The near miss is worse than the bug, which is why this is
+    // `Object.create(null)` and not a plain assignment: `Object.keys({__proto__:
+    // new Set()})` is `[]`, so "fixing" the crash by writing the key onto a
+    // plain object would repoint that object's prototype and the tag would
+    // VANISH from `Object.keys(tagOrigins).sort()` below — a project silently
+    // carrying one fewer tag than it declared, which is every tag-keyed rule
+    // (`../../rules/tags.mjs`) quietly not applying to it. With a null
+    // prototype the `??=` sees a real `undefined`, the `Set` is stored as an
+    // own enumerable entry, and the tag reaches both `tags` and `tagOrigins`
+    // exactly like any other spelling. (`Object.fromEntries` at the bottom of
+    // this loop defines own properties, so it carries such a key through
+    // unchanged.)
+    const tagOrigins = /** @type {Record<string, Set<string>>} */ (Object.create(null));
+    const addTags = (tags, origin) => {
+      for (const tag of tags ?? []) {
+        (tagOrigins[tag] ??= new Set()).add(origin);
+      }
+    };
+    addTags(declared?.tags, "declared");
+    addTags(manifest?.tags, "project.json");
+    for (const [index, rule] of model.projectRules.entries()) {
+      if (matchesGlob(projectRoot, rule.match)) addTags(rule.tags, `projectRules[${index}]`);
+    }
+
+    // Spec D6: every `projectRules` row whose `match` covers this root and
+    // states a `type` gets a vote, and the votes must agree. `.find()` used
+    // to take the first match and ignore the rest, so reordering two rows in
+    // `archkeep.json` — a change that should never affect a verdict — could
+    // silently flip a project's type and, with it, which import-ban rules
+    // apply to it. A tie (every voting row names the SAME type) is fine and
+    // resolves to that type; only disagreement is fatal.
+    const typeVotes = model.projectRules
+      .map((rule, index) => ({ rule, index }))
+      .filter(({ rule }) => rule.type && matchesGlob(projectRoot, rule.match));
+    const distinctTypes = new Set(typeVotes.map(({ rule }) => rule.type));
+    if (distinctTypes.size > 1) {
+      violations.push(
+        `projectRules: ${typeVotes.map(({ index }) => `[${index}]`).join(", ")} disagree on ` +
+          `'${projectRoot}'s type (${[...distinctTypes].join(" vs. ")}) — every projectRules ` +
+          `row matching one project must agree on its type`,
+      );
+      continue;
+    }
+    const type =
+      declared?.type ?? typeVotes[0]?.rule.type ?? nodeTypeOf(name, manifest?.projectType);
+
+    // A manifest-sourced implicitDependencies entry gets the same pattern
+    // check `./model.mjs`'s `declaredProjectViolations` already runs on a
+    // declared row's own list — the same matcher `./graph.mjs`'s
+    // `buildDependencies` will eventually call
+    // (`../../rules/match.mjs`'s `findMatchingProjects`) — so a pattern it
+    // cannot resolve is a discovery-time defect named against this project,
+    // never a silently dropped edge at graph-build time.
+    for (const pattern of manifest?.implicitDependencies ?? []) {
+      const error = projectPatternError(pattern);
+      if (error) {
+        violations.push(
+          `${projectRoot}/${PROJECT_CONFIG_FILE}: implicitDependencies entry '${pattern}': ${error}`,
+        );
+      }
+    }
+
+    const implicitDependencies = [
+      ...new Set([
+        ...(declared?.implicitDependencies ?? []),
+        ...(manifest?.implicitDependencies ?? []),
+      ]),
+    ];
+
+    resolved.push({
+      name,
+      root: projectRoot,
+      type: /** @type {"app"|"e2e"|"lib"} */ (type),
+      tags: Object.keys(tagOrigins).sort(),
+      tagOrigins: Object.fromEntries(
+        Object.entries(tagOrigins).map(([tag, origins]) => [tag, [...origins].sort()]),
+      ),
+      implicitDependencies,
+      // `targets` names target NAMES only — see `./model.mjs`'s
+      // `declaredProjectViolations` for the shape validated, and
+      // `./graph.mjs`'s `buildNativeGraph` for how each name becomes a
+      // synthesized `{executor: "archkeep:declared"}` entry. `project.json`
+      // is not a source: this provider never reads its real target
+      // definitions, only whether `archkeep.json` declared the project has
+      // one.
+      targets: declared?.targets ?? [],
+    });
+  }
+
+  const seenNames = new Map();
+  for (const project of resolved) {
+    if (seenNames.has(project.name)) {
+      violations.push(
+        `projects: '${project.name}' names both '${seenNames.get(project.name)}' and ` +
+          `'${project.root}' — every project must resolve to a unique name`,
+      );
+      continue;
+    }
+    seenNames.set(project.name, project.root);
+  }
+
+  model.projectRules.forEach((rule, index) => {
+    if (!resolved.some((project) => matchesGlob(project.root, rule.match))) {
+      violations.push(`projectRules[${index}]: '${rule.match}' matches no discovered project`);
+    }
+  });
+
+  if (violations.length === 0 && resolved.length === 0) {
+    violations.push(
+      "projects: this workspace describes zero projects — declare at least one in " +
+        "projects.declared, or let projects.infer find one",
+    );
+  }
+
+  if (violations.length > 0) {
+    throw new Error(
+      `archkeep: ${root}/archkeep.json describes a workspace that does not match the tree:\n  ` +
+        violations.join("\n  "),
+    );
+  }
+
+  return { projects: resolved, failures };
+}

package/src/providers/native/graph.mjs

@@ -0,0 +1,234 @@
+/**
+ * Import edges and implicit edges, reduced to Nx's own dependency-map shape —
+ * the second half of what `../../lsp/workspace-index.mjs` used to build by
+ * hand, promoted here so a native `archkeep.json` workspace and the language
+ * server share one implementation rather than growing two that drift
+ * (`../../../AGENTS.md`, "`src/providers/` is the layer that supplies a graph
+ * to `evaluate()`").
+ */
+import { findMatchingProjects } from "../../rules/match.mjs";
+
+/**
+ * The dependency map, keyed by source project as Nx keys it.
+ *
+ * Two kinds of edge, and both are Nx's:
+ *
+ * - **Import edges**, from the analysis records. A `dynamic` import site
+ *   becomes a `dynamic` edge, because `noImportsOfLazyLoadedLibraries` is
+ *   decided on exactly that distinction (`../../rules/topology.mjs`).
+ * - **Implicit edges**, from each project's `implicitDependencies`, expanded
+ *   with the SAME matcher Nx uses — reached through `../../rules/match.mjs`
+ *   rather than reimplemented, so a pattern that resolves one way for a
+ *   constraint cannot resolve another way here.
+ *
+ * @param {{importSites: object[], nodes: Record<string, object>, projectOf: (file: string) => string|undefined}} input
+ * @returns {Record<string, {source: string, target: string, type: string}[]>}
+ */
+export function buildDependencies({ importSites, nodes, projectOf }) {
+  // Null-prototype: every key here is a project NAME, and project names come
+  // from `archkeep.json`'s own `projects.declared[].name` or a tracked
+  // manifest's own `name` field — both attacker-supplied the moment a pull
+  // request adds a project called `__proto__`. A plain `{}` literal answers
+  // `dependencies["__proto__"] = […]` by reassigning the object's OWN
+  // prototype rather than adding an entry (`Object.prototype`'s inherited
+  // `__proto__` accessor), so the array this line means to store is silently
+  // discarded and any read of `dependencies["__proto__"]` afterward returns
+  // whatever the prototype now is — not an array, so the very next `.push`
+  // onto it throws `TypeError: … .push is not a function`, taking the whole
+  // graph build down over one project name. `Object.create(null)` has no
+  // inherited `__proto__` accessor to collide with, so the key behaves like
+  // every other project name: a real, own, enumerable entry.
+  /** @type {Record<string, {source: string, target: string, type: string}[]>} */
+  const dependencies = Object.create(null);
+  const seen = new Set();
+  // Nx's own rule for config files, reproduced over the same two dialect
+  // spellings of the workspace-root project's root. `explicit-project-dependencies.js`
+  // (the import-site half of nx's graph construction) drops every edge whose
+  // TARGET is the workspace root, keeping only edges that originate in it —
+  // `if (isRoot(source) || !isRoot(target))` — and names the gap it papers
+  // over in its own TODO: "These edges technically should be allowed but we
+  // need to figure out how to separate config files out from root". The root
+  // project carries the tree's own config files (`eslint.config.*`,
+  // `*.config.ts`, `global-setup.*`), and Nx drops exactly their imported
+  // edges: measured on the code-pushup real tree at the pinned sha, `nx graph`
+  // reports ZERO edges into the root `workspace` node while project-level
+  // config files visibly import the root's — the import site exists, the
+  // target-root edge is what Nx suppresses. So no edge here may point at the
+  // workspace root, or the graph invents dependencies Nx never drew and
+  // `noCircularDependencies` reports cycles that only close through that
+  // node. `scripts/differential-real-trees.mjs`'s ledger carries the
+  // full finding; Nx spells the root `"."` (`isRoot` reads `root === '.'`
+  // verbatim) while this package's native `archkeep.json` dialect spells it
+  // `""` (`./discover.mjs`'s `discoverNativeProjects`), so both are
+  // recognised here rather than one silently differing the other.
+  const isRoot = (name) => {
+    const root = nodes[name]?.data?.root;
+    return root === "" || root === ".";
+  };
+  const add = (source, target, type) => {
+    if (!source || !target || source === target) return;
+    if (!nodes[target]) return;
+    // `JSON.stringify` of the tuple, not a space-joined string: a project name
+    // may contain a space — neither `./model.mjs`'s `declaredProjectViolations`
+    // nor `./discover.mjs`'s manifest-sourced name resolution reject one (only
+    // non-empty is required; npm's own naming rules, which forbid a space, bind
+    // `package.json`'s name and nothing declared in `archkeep.json` directly) —
+    // so `${source} ${target} ${type}` collides whenever a space moves across
+    // the join: source `"a b"` target `"c"` and source `"a"` target `"b c"`
+    // both key to `"a b c static"`, and the second edge silently vanishes as a
+    // false duplicate of the first. A JSON array has no such ambiguity: each
+    // element is individually quoted and escaped.
+    const key = JSON.stringify([source, target, type]);
+    if (seen.has(key)) return;
+    seen.add(key);
+    (dependencies[source] ??= []).push({ source, target, type });
+  };
+
+  for (const site of importSites) {
+    const source = projectOf(site.sourceFile);
+    const target = site.resolved?.target;
+    // The target-root skip, exactly as Nx applies it — and only to IMPORT
+    // edges. Nx's implicit-dependency expansion (`applyImplicitDependencies`)
+    // has no `isRoot` check, so a project.json naming the root as an implicit
+    // dependency still draws the edge there; import sites are the one place
+    // Nx refuses, and they are the one place this loop reproduces it. Keeping
+    // `source->root` without also dropping `root->source` would misread the
+    // real tree the other way (it would be a loud native-extra rather than a
+    // cycle — config files visibly do import INTO the root, so the only
+    // question is which side Nx withholds, and it withholds the target side).
+    if (isRoot(target) && !isRoot(source)) continue;
+    add(source, target, site.kind === "dynamic" ? "dynamic" : "static");
+  }
+  for (const [name, node] of Object.entries(nodes)) {
+    const declared = node.data.implicitDependencies;
+    if (!Array.isArray(declared) || declared.length === 0) continue;
+    // A pattern the matcher rejects is a project-definition problem, and
+    // `findMatchingProjects` throws naming it (`../../rules/match.mjs`). That
+    // throw is left to propagate rather than caught here, for both callers of
+    // this function: `./discover.mjs` validates every native
+    // `implicitDependencies` entry — declared-row (`./model.mjs`'s
+    // `declaredProjectViolations`) and `project.json`-sourced alike — before a
+    // graph is ever built from them, so a native workspace never reaches this
+    // line with a bad pattern in the first place; the throw below is dead code
+    // on that path, not a silent one. `../../lsp/workspace-index.mjs`'s
+    // `project.json` has no such validator, so its build CAN reach here with
+    // one — and letting the exception propagate is the correct answer there
+    // too: `../../lsp/server.mjs`'s `initialize`/`didOpen` handling already
+    // wraps the whole index build in a `.catch()` that turns any thrown error
+    // into a loud "could not analyze" state published to every open document,
+    // exactly the failure mode `../../../AGENTS.md`'s invariant asks for. A
+    // caught-and-dropped edge here used to reach that same bad pattern
+    // silently: the project kept building, one implicit edge simply never
+    // existed, and any boundary violation that edge would have carried read as
+    // a clean workspace instead of one that could not be judged.
+    const expanded = findMatchingProjects(declared, nodes);
+    for (const target of expanded) add(name, target, "implicit");
+  }
+  return dependencies;
+}
+
+/**
+ * The graph `evaluate()` judges, built from discovered native projects and
+ * the import sites analysis found in them.
+ *
+ * Only `data.root` and `data.tags` are written here — the two facts this
+ * provider actually measured (`./discover.mjs`). `entryPoints`,
+ * `declaredPackages` and `mfeRemote` are NOT spread in from `archkeep.json`;
+ * they stay annotator-computed by the same functions the Nx path calls
+ * (`../../workspace.mjs`'s `annotateMFERemotes`/`annotatePackageFacts`,
+ * invoked by the caller afterward — see `../nx.mjs`'s
+ * `ProjectModelProvider` doc for why that split holds for every provider).
+ * `implicitDependencies` rides on `data` too, because `buildDependencies`
+ * above reads it from there — the one field this provider both writes AND
+ * reads back, by the same contract Nx's own `project.json` uses.
+ *
+ * `externalNodes` is never set: `../../rules/specifiers.mjs`'s
+ * `findTransitiveExternalDependencies` already treats an absent
+ * `graph.externalNodes` as "none", and `../../rules/index.mjs`'s
+ * `externalNodeFor` synthesises a node for an external target on demand — a
+ * native provider declaring npm-registry bookkeeping would be a second
+ * source of truth for a fact this package already derives from the analysis
+ * records.
+ *
+ * `data.targets` is synthesised, never measured: `archkeep.json`'s
+ * `projects.declared[].targets` names target NAMES only (spec §5), never an
+ * executor or a config — this provider has no build system to ask for one.
+ * Each declared name becomes `{executor: "archkeep:declared"}`, a non-empty
+ * executor string so `../../rules/topology.mjs`'s `hasBuildExecutor` (which
+ * treats `executor === ''` as "not really buildable") reads it as real,
+ * making `enforceBuildableLibDependency` live on a native tree the same way
+ * it is on an Nx one. An empty `targets` list stays an ABSENT `data.targets`
+ * rather than an empty object, so `hasBuildExecutor`'s own `Boolean(targets
+ * && …)` sees "no targets" for a project that declared none, not a targets
+ * table that happens to match nothing.
+ *
+ * `workspaceLayout` rides on the returned graph OBJECT, never inside a node's
+ * `data` — it is a workspace-wide fact, not a per-project one, and
+ * `../../rules/index.mjs`'s `createContext` reads it with exactly this
+ * fallback: `graph.workspaceLayout ?? DEFAULT_WORKSPACE_LAYOUT`. Passing
+ * `undefined` through (rather than defaulting it here) keeps that the only
+ * place the default is ever applied — see `./model.mjs`'s
+ * `normalizeNativeModel` for why a second default here could drift from it.
+ *
+ * `exemptedFiles` rides the same way — the CONCRETE list of files
+ * `coverage.exempt` removed from coverage (`./coverage.mjs`'s `judgeCoverage`,
+ * threaded through `../index.mjs`'s `buildGraph` from `discovered.exempted`),
+ * never the globs the rows are written with. The rules layer matches import
+ * resolutions against these exact paths (`../../rules/index.mjs`'s
+ * `exemptResolvedFile`, #218), and the guard that keeps a broad row from
+ * becoming a boundary-off switch lives in what `judgeCoverage` already does:
+ * it expands rows over tracked, analyzable, UNOWNED files only, so a
+ * project-owned file cannot enter this list no matter how wide its row is.
+ * Absent when no file was exempted, so a graph with no exemptions stays
+ * byte-identical to one this field never existed on.
+ *
+ * @param {{projects: {name: string, root: string, type: string, tags: string[], implicitDependencies: string[], targets: string[]}[], importSites: object[], projectOf: (file: string) => string|undefined, workspaceLayout?: {appsDir: string, libsDir: string}, exemptedFiles?: string[]}} args
+ * @returns {{nodes: Record<string, object>, dependencies: Record<string, object[]>, workspaceLayout?: {appsDir: string, libsDir: string}, exemptedFiles?: string[]}}
+ */
+export function buildNativeGraph({
+  projects,
+  importSites,
+  projectOf,
+  workspaceLayout,
+  exemptedFiles,
+}) {
+  // Null-prototype for the same reason `buildDependencies` above uses one: a
+  // project literally named `__proto__` is a name this provider does not
+  // control (it comes straight from `archkeep.json` or a tracked manifest), and
+  // a plain `{}` answers `nodes["__proto__"] = …` by repointing the object's
+  // own prototype instead of adding an entry. That project would then vanish
+  // from every `Object.keys(nodes)`/`Object.entries(nodes)` walk in this
+  // module and in `../../rules/`, while `nodes["__proto__"]` kept reading back
+  // truthy — an import INTO it would still resolve as a real target, but the
+  // project's own outgoing edges, its tags, its type would all be invisible to
+  // anything that iterates rather than looks up by name. Silent, and exactly
+  // the shape `../../../AGENTS.md`'s invariant refuses: a workspace with a
+  // `__proto__` project would read as one with fewer projects than it
+  // declared, with no diagnostic naming why.
+  /** @type {Record<string, object>} */
+  const nodes = Object.create(null);
+  for (const project of projects) {
+    nodes[project.name] = {
+      name: project.name,
+      type: project.type,
+      data: {
+        root: project.root,
+        tags: project.tags,
+        implicitDependencies: project.implicitDependencies,
+        ...(project.targets && project.targets.length > 0
+          ? {
+              targets: Object.fromEntries(
+                project.targets.map((name) => [name, { executor: "archkeep:declared" }]),
+              ),
+            }
+          : {}),
+      },
+    };
+  }
+  return {
+    nodes,
+    dependencies: buildDependencies({ importSites, nodes, projectOf }),
+    ...(workspaceLayout ? { workspaceLayout } : {}),
+    ...(exemptedFiles && exemptedFiles.length > 0 ? { exemptedFiles } : {}),
+  };
+}