@ecoma-io/archkeep 0.15.0 → 0.16.0

package/src/governance/profile-registry.mjs

@@ -342,7 +342,6 @@ export function loadProfileRegistry(
   if (violations.length > 0) {
     throw new Error(`archkeep: ${path} is malformed:\n  ${violations.join("\n  ")}`);
   }
-  /** @type {{profiles: object[]}} */ (parsed);
   return parsed;
 }
 

package/src/graph/create-dependencies.mjs

@@ -1,5 +1,5 @@
 /**
- * The graph layer: cross-project EDGES for Go, Rust, and Python, in the shape
+ * The graph layer: cross-project EDGES for Go, Rust, Python, Java, and C#/\.NET, in the shape
  * Nx's `createDependencies` hook returns. Nothing else — nodes still come from
  * each project's hand-written `project.json`, and targets are never inferred
  * (`packages/archkeep/AGENTS.md`).
@@ -14,33 +14,94 @@
  *
  * Each resolver reads tracked manifests and sources statically (regex for Go
  * imports, smol-toml for Cargo/pyproject manifests) so the graph computes
- * without any language toolchain installed. A workspace with no Go/Rust/Python
- * projects pays nothing: every resolver keys off `<projectRoot>/<manifest>`
- * existing in the project's tracked files. A resolver may THROW instead of
- * returning — the Python one does, for a declared path dependency it cannot
- * attribute to any project (`../analysis/python.mjs` header) — and the throw
- * is deliberate: edges and an error are the only two outputs this hook has,
- * and an edge quietly missing from the graph is the failure mode this plugin
- * exists to close.
+ * without any language toolchain installed. A workspace with no Go/Rust/Python/
+ * Java/C# projects pays nothing: every resolver keys off what it reads existing in
+ * the project's tracked files.
  *
- * Resolver contract (kept identical across languages, see `../analysis/*.mjs`):
- *   resolve(projects, filesOf, readFile) -> [{ source, target, sourceFile, type }]
+ * ## The hook's failure posture (#364)
+ *
+ * Edges and a throw are the only two outputs this hook has, and every
+ * manifest reader and name index throws for the states its funnel
+ * classifies as could-not-complete — the same failure lists the CLI turns
+ * into exit 3: the Maven, Gradle and .csproj models, the JVM package index,
+ * the C# namespace index, the Go module map and the Rust crate map
+ * (`../analysis/source-util.mjs`'s `refuseUnreadTree`).
+ * Nx wraps a throwing hook's error and fails the whole graph computation —
+ * measured against nx 23.1.1, which also has a dedicated `ProcessDependenciesError`
+ * for the event and whose daemon refuses with an error rather than serving a
+ * stale graph — so the throw is a designed-for channel, and `nx affected`
+ * fails loudly on a broken reactor instead of under-selecting on it.
+ *
+ * The boundary: manifests and workspace-wide name indexes throw — one
+ * unreadable entry corrupts resolution for every project that names that
+ * identity, arbitrarily far from the file, so the failure cannot be
+ * attributed to the file's own edges — while per-source import reads keep
+ * the null-read posture the hook's `readFile` states below (a dropped source
+ * loses only its own edges; a dropped manifest or index entry loses
+ * everyone's). Python's dangling-path throw is the precedent that predates
+ * the rule; its malformed-TOML tolerance stays the documented exception its
+ * own header pins (`../analysis/python.mjs`).
+ *
+ * Resolver contract (see `../analysis/*.mjs`): every resolver returns raw Nx
+ * edges — { source, target, sourceFile, type } and nothing else. Go, Rust and
+ * Python take `resolve(projects, filesOf, readFile)`; the C# and JVM halves
+ * instead take ONE workspace-shaped object (`{ projects, filesOf, readFile }`),
+ * because everything they read is `perWorkspace`-memoized on that object — the
+ * C# namespace index, the JVM package index, the Maven and Gradle models — and
+ * a resolver destructuring its own arguments would have to build a fresh
+ * object per call, defeating the memo (#363: three builds of the same index
+ * per run).
  */
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { containmentViolation } from "../containment.mjs";
+import { resolveCsharpDependencies } from "../analysis/csharp.mjs";
+import { resolveCsprojDependencies, dotnetManifestFailures } from "../analysis/dotnet/csproj.mjs";
 import { resolveGoDependencies } from "../analysis/go.mjs";
+import { resolveJavaDependencies } from "../analysis/java.mjs";
+import { resolveKotlinDependencies } from "../analysis/kotlin.mjs";
+import { resolveMavenDependencies, mavenManifestFailures } from "../analysis/jvm/maven.mjs";
+import { resolveGradleDependencies, gradleManifestFailures } from "../analysis/jvm/gradle.mjs";
+import { dotnetIndexFailures } from "../analysis/dotnet/namespaces.mjs";
 import { resolvePythonDependencies } from "../analysis/python.mjs";
 import { resolveRustDependencies } from "../analysis/rust.mjs";
 import { resolveOptions } from "../options.mjs";
 
 /** Pure core over an abstract workspace; injectable for tests. */
 export function resolvePolyglotDependencies(projects, filesOf, readFile) {
+  // The C# and JVM halves read the same tree through ONE workspace-shaped
+  // object: their memoized reads (namespace index, package index, Maven and
+  // Gradle models) all key on the object itself, so every resolver handed the
+  // same one shares a single build of each — and the memoized read behind the
+  // object means no file's content is fetched twice on one graph computation.
+  // The positional resolvers (Go, Rust, Python) hold no such memo, so they
+  // keep taking the three values directly.
+  const reads = new Map();
+  const sharedWorkspace = {
+    projects,
+    filesOf,
+    readFile: (path) => {
+      if (!reads.has(path)) reads.set(path, readFile(path));
+      return reads.get(path);
+    },
+  };
   const deps = [
     ...resolveGoDependencies(projects, filesOf, readFile),
     ...resolveRustDependencies(projects, filesOf, readFile),
     ...resolvePythonDependencies(projects, filesOf, readFile),
+    ...resolveJavaDependencies(sharedWorkspace),
+    ...resolveKotlinDependencies(sharedWorkspace),
+    ...resolveCsharpDependencies(sharedWorkspace),
+    // Manifest edges for .csproj trees: ProjectReference resolution,
+    // independent of (and complementary to) the source-track edges above.
+    ...resolveCsprojDependencies(sharedWorkspace),
+    // Manifest edges for Maven/Gradle trees: the identity-anchor half of JVM
+    // support, independent of (and complementary to) the import edges above
+    // — a declared-but-unused dependency and an undeclared-but-imported one
+    // are both findings.
+    ...resolveMavenDependencies(sharedWorkspace),
+    ...resolveGradleDependencies(sharedWorkspace),
   ];
   // One edge per (source, target, sourceFile) — a Go project importing a
   // sibling from ten files yields ten sourceFile-attributed edges upstream
@@ -54,6 +115,64 @@ export function resolvePolyglotDependencies(projects, filesOf, readFile) {
   });
 }
 
+/**
+ * The manifest-track edges in one list — `<ProjectReference>` (plus
+ * `<Using Include>`) for .NET trees, Maven coordinate matching and Gradle
+ * `project(":x")` for JVM ones. `resolvePolyglotDependencies` above already
+ * folds these into the Nx plugin hook's answer; the CLI's native and Moon
+ * branches and the language server's index build their graphs from import
+ * sites alone, with no plugin host to call the hook, so they fold this list
+ * themselves (`../providers/native/graph.mjs`'s `mergeDeclaredEdges`) — the
+ * two-track contract of `../../../../docs/adr/0006-dotnet-language-integration.md`
+ * (Decision 3) and `../../../../docs/adr/0005-jvm-language-integration.md`
+ * (Decision 4) names no face it does not hold on.
+ *
+ * Each resolver refuses — throws — on exactly the failure list its
+ * `*ManifestFailures` twin reports from the same memoized model
+ * (`../../analysis/source-util.mjs`'s `perWorkspace` memoizes on the
+ * workspace object, so twin calls share one build): a caller that has found
+ * `mavenManifestFailures`/`gradleManifestFailures`/`dotnetManifestFailures`/
+ * `dotnetIndexFailures` empty on THIS workspace cannot hit the throw.
+ *
+ * @param {object} workspace The shared workspace-shaped object.
+ * @returns {{source: string, target: string, sourceFile: string, type: string}[]}
+ */
+export function resolveDeclaredManifestEdges(workspace) {
+  return [
+    ...resolveCsprojDependencies(workspace),
+    ...resolveMavenDependencies(workspace),
+    ...resolveGradleDependencies(workspace),
+  ];
+}
+
+/**
+ * The could-not-complete failures behind `resolveDeclaredManifestEdges`'s
+ * refusal — the four manifest and index failure lists folded into one. A
+ * caller uses this list twice: folded into its own whole-file failure
+ * reporting, and as the no-throw guard for the edge call — each resolver
+ * refuses on exactly the failures its `*ManifestFailures` twin reports from
+ * the same memoized model, so an empty list here makes
+ * `resolveDeclaredManifestEdges` unable to throw on this workspace. Both
+ * halves of that sentence live beside each other here so the identity cannot
+ * drift between a caller that forgets to report and one that skips the guard.
+ *
+ * `jvmIndexFailures` and `pythonUnmodelledFailures` are deliberately absent:
+ * no resolver here reads the JVM package index or refuses on Python's
+ * unmodelled posture, so neither is a condition of the no-throw guarantee —
+ * callers keep those lists flowing through their own funnels.
+ *
+ * @param {object} workspace The shared workspace-shaped object.
+ * @returns {{sourceFile: string, reason: string}[]}
+ */
+export function resolveDeclaredManifestFailures(workspace) {
+  return [
+    ...mavenManifestFailures(workspace),
+    ...gradleManifestFailures(workspace),
+    ...dotnetManifestFailures(workspace),
+    ...dotnetIndexFailures(workspace),
+  ];
+}
+
 /**
  * The Nx hook.
  *
@@ -81,10 +200,14 @@ export const createDependencies = (options, context) => {
     // attacker-supplied the moment a PR adds a tracked path. A tracked symlink
     // whose realpath leaves the workspace would draw a dependency edge from
     // outside bytes into `nx affected`'s graph; refusing (null) drops the
-    // read so the file produces no edge (the `resolvePolyglotDependencies`
-    // contract is a null read = no edge, not a throw — this hook cannot exit
-    // non-zero by design). A plugin that never resolves outside bytes stays
-    // silent-green only when the bytes are really inside (`../containment.mjs`).
+    // read. For a SOURCE file an import walk reads, that is the end of it:
+    // null read = no edge, the file's own edges and nothing wider. For a
+    // MANIFEST or an index-feeding file (a pom, a settings or build file, a
+    // .csproj, a .java/.kt/.cs a name index reads), the reader records the
+    // null read as a could-not-complete failure and its resolver throws on
+    // it — the posture this file's header owns (#364). A plugin that never
+    // resolves outside bytes stays silent-green only when the bytes are
+    // really inside (`../containment.mjs`).
     if (containmentViolation(context.workspaceRoot, abs) !== null) return null;
     try {
       return readFileSync(abs, "utf8");

package/src/lsp/diagnose.mjs

@@ -63,7 +63,7 @@ import { indexGaps } from "./workspace-index.mjs";
  * @param {string} request.text Its current contents — the editor's buffer, not
  *   what is on disk. Diagnosing the saved file would answer a question nobody
  *   asked while the developer is looking at their unsaved edit.
- * @param {{workspace: object, graph: object, skippedProjects?: object[], fileFailures?: object[], importSites?: object[], nativeMarker?: boolean, nativeModelFailure?: string|null, moonModelFailure?: string|null, nxModelFailure?: string|null, workspaceLayoutFailure?: string|null}} request.index
+ * @param {{workspace: object, graph: object, skippedProjects?: object[], fileFailures?: object[], importSites?: object[], duplicateProjects?: object[], nativeMarker?: boolean, nativeModelFailure?: string|null, moonModelFailure?: string|null, nxModelFailure?: string|null, workspaceLayoutFailure?: string|null}} request.index
  *   From `./workspace-index.mjs`. `importSites` is the whole tree's retained
  *   analysis output — the evidence half of the run below; absent (an index
  *   built before it existed) reads as none, which degrades evidence, never a

package/src/lsp/server.mjs

@@ -43,7 +43,11 @@ import {
   readMoonOptions,
   readPluginOptions,
 } from "../options.mjs";
-import { moonMarkerAt } from "../providers/moon.mjs";
+import {
+  MOON_ALT_WORKSPACE_MARKER,
+  MOON_WORKSPACE_MARKER,
+  moonMarkerAt,
+} from "../providers/moon.mjs";
 import { ARCHKEEP_MODEL_FILE, loadNativeModel } from "../providers/native/model.mjs";
 
 import { readBoundaryConfig } from "./boundary-config.mjs";
@@ -82,6 +86,88 @@ const MFE_CONFIG_FILES = Object.freeze([
   "module-federation.config.ts",
 ]);
 
+/**
+ * The manifests the non-TypeScript halves of the project graph are read from —
+ * the finite names each provider decides projects and edges by.
+ *
+ * This list carried none of them, and that was the defect #410 reports: the
+ * watched set described the TypeScript-side configuration only, while on a Go,
+ * Rust, Python, JVM or Moon workspace the graph itself is read from manifests.
+ * `textDocument/didSave` invalidates the whole session only when
+ * `touchesWatchedFile` matches this list, so saving an edited `go.mod`
+ * republished the manifest alone and left every open verdict answering from
+ * the graph as it was at index time — a module added to the workspace stayed
+ * invisible, the rules judged against a graph that no longer matched disk, and
+ * the affected files went on publishing `[]`, which reads as "no violation"
+ * (`../../../../AGENTS.md`). Only an unrelated watched edit or an editor
+ * restart rebuilt the graph.
+ *
+ * What reads each entry:
+ *
+ * - `go.mod` — the module path `../analysis/go.mjs`'s `resolveGoDependencies`
+ *   resolves Go imports against, and the anchor
+ *   `../providers/native/model.mjs`'s `DEFAULT_MANIFEST_NAMES` infers Go
+ *   projects from. Renaming a module in the editor re-points or drops every
+ *   edge into that project at the next index build; this entry is what makes
+ *   the next index build happen.
+ * - `go.work` — the use list deciding which Go modules the workspace's own
+ *   tooling builds (`../go-work.mjs`'s parser): the same module set the Go
+ *   analysis models, so a save of it is a graph-shaping edit on the same terms
+ *   as a `go.mod`.
+ * - `Cargo.toml` — crate identity, `[workspace]` membership and dependency
+ *   declarations (`../analysis/rust.mjs`). One basename covers the root
+ *   manifest and every member's, the reach `**\/package.json` already has.
+ * - `pyproject.toml` — the package names and `sources` tables
+ *   `../analysis/python.mjs` resolves Python imports against.
+ * - `pom.xml` — Maven identity and dependency edges
+ *   (`../analysis/jvm/maven.mjs`), and a project anchor in
+ *   `DEFAULT_MANIFEST_NAMES`.
+ * - `settings.gradle` / `settings.gradle.kts` — the reactor structure
+ *   `../analysis/jvm/gradle.mjs` reads Gradle identity from.
+ * - `build.gradle` / `build.gradle.kts` — the dependency declarations the same
+ *   module reads Gradle EDGES from, which is why they sit beside the settings
+ *   file that anchors the reactor rather than instead of it.
+ * - `moon.yml` and the two `workspace.yml` spellings — the Moon provider
+ *   derives its whole graph from `moon project-graph --json`
+ *   (`../providers/moon.mjs`'s `readProjectGraph`), which reads the tree's
+ *   `moon.yml` files for ids, tags and `dependsOn`, under the workspace whose
+ *   marker the two imported constants name. They are imported rather than
+ *   spelled out so the watched set follows Moon's own directory conventions
+ *   instead of a second copy of them.
+ *
+ * `*.csproj` is deliberately absent although `DEFAULT_MANIFEST_NAMES` carries
+ * it: that entry is a glob PATTERN, and the reach this list's entries get —
+ * `touchesWatchedFile`'s workspace-relative suffix comparison, mirrored by the
+ * `**\/<entry>` glob `registerFileWatchers` registers — covers exact names and
+ * directory-prefixed names only. A pattern entry would register `**\/*.csproj`,
+ * a watcher that fires, while the suffix match could never answer it: a
+ * notification path that looks covered and is not, which is the silent
+ * direction in the one list whose job is noticing. The list carries only names
+ * it can fire on.
+ *
+ * The entries are unconditional rather than provider-selected, for the same
+ * reason `archkeep.json` is: which manifests shape a root's graph can move
+ * under a running session — a `go.mod` appearing beside `nx.json` — and a
+ * watch list fixed to the provider the session started with is this same
+ * stale-graph hole one step out. The cost of an entry a TypeScript-only
+ * workspace never matches is one glob; the failure it buys out is a graph the
+ * editor never re-reads.
+ */
+const POLYGLOT_GRAPH_MANIFESTS = Object.freeze([
+  "go.mod",
+  "go.work",
+  "Cargo.toml",
+  "pyproject.toml",
+  "pom.xml",
+  "settings.gradle",
+  "settings.gradle.kts",
+  "build.gradle",
+  "build.gradle.kts",
+  "moon.yml",
+  MOON_WORKSPACE_MARKER,
+  MOON_ALT_WORKSPACE_MARKER,
+]);
+
 /**
  * The files whose content changes the verdict for files that did not change,
  * given the options this session resolved.
@@ -150,6 +236,15 @@ const MFE_CONFIG_FILES = Object.freeze([
  * takes a project's NAME when its `project.json` states none, so an edit to it
  * can move a project in the graph and not only waive something in it.
  *
+ * The polyglot graph manifests are here for that same argument one level out,
+ * at the place a project comes into existence at all: on a Go, Rust, Python,
+ * JVM or Moon root the graph itself is read from manifests this list used to
+ * carry none of, so saving an edited one republished the manifest alone and
+ * left every verdict answering from the graph as it was at index time. Which
+ * names, and which module reads each, is `POLYGLOT_GRAPH_MANIFESTS`'s own
+ * comment — the roster is not restated here, because two rosters are two
+ * chances to drift.
+ *
  * Those three are PER-PROJECT paths rather than workspace-root singletons, and
  * they need no new mechanism for it: `registerFileWatchers` gives every entry
  * the glob `**\/<entry>` and `touchesWatchedFile` matches the same reach — an
@@ -209,6 +304,7 @@ export function watchedFilesFor(options, { unresolved = false } = {}) {
     ARCHKEEP_MODEL_FILE,
     PACKAGE_MANIFEST_FILE,
     ...MFE_CONFIG_FILES,
+    ...POLYGLOT_GRAPH_MANIFESTS,
   ]);
 }
 

package/src/lsp/workspace-index.mjs

@@ -126,7 +126,11 @@ import {
   createWorkspace,
   listTrackedFiles,
 } from "../workspace.mjs";
-import { buildDependencies } from "../providers/native/graph.mjs";
+import { buildDependencies, mergeDeclaredEdges } from "../providers/native/graph.mjs";
+import {
+  resolveDeclaredManifestEdges,
+  resolveDeclaredManifestFailures,
+} from "../graph/create-dependencies.mjs";
 import { nodeTypeOf, PROJECT_CONFIG_FILE } from "../providers/native/discover.mjs";
 import { ARCHKEEP_MODEL_FILE } from "../providers/native/model.mjs";
 import { nativeProvider } from "../providers/native/index.mjs";
@@ -249,7 +253,14 @@ export function discoverProjects({ files, readFile }) {
  * reads it unguarded and an absent list is not the same fact as an empty one.
  *
  * @param {{name: string, root: string, config: object}[]} projects
- * @returns {Record<string, object>}
+ * @returns {{nodes: Record<string, object>, duplicateProjects: {name: string, roots: string[]}[]}}
+ *   `duplicateProjects` names every name two or more projects resolved to and
+ *   every root that claimed it (#375): a silent `nodes[name] = …` overwrite
+ *   drops the shadowed project from the graph, its files match no root, and
+ *   the editor publishes no diagnostics for real boundary crossings — the
+ *   exact silent direction `../../../../AGENTS.md`'s invariant refuses. The
+ *   first project still wins in `nodes` (the index stays usable); the caller
+ *   publishes the collision through `indexGaps`.
  */
 export function buildNodes(projects) {
   // Null-prototype for the same reason `../providers/native/graph.mjs` and
@@ -264,14 +275,36 @@ export function buildNodes(projects) {
   // has no inherited `__proto__` accessor to collide with, so the name behaves
   // like every other project name: a real, own, enumerable entry.
   const nodes = Object.create(null);
+  /** @type {Map<string, string>} name → root of the first project that claimed it. */
+  const seenNames = new Map();
+  /** @type {Map<string, string[]>} name → every root that resolved to it, for names claimed twice or more. */
+  const duplicateMap = new Map();
+
   for (const { name, root, config } of projects) {
+    if (seenNames.has(name)) {
+      // Duplicate name detected — record it for loud reporting
+      if (!duplicateMap.has(name)) {
+        duplicateMap.set(name, [seenNames.get(name)]);
+      }
+      duplicateMap.get(name).push(root);
+      // Skip adding the duplicate to nodes — first project wins
+      continue;
+    }
+    seenNames.set(name, root);
     nodes[name] = {
       name,
       type: nodeTypeOf(name, config.projectType),
       data: { ...config, root, tags: config.tags ?? [] },
     };
   }
-  return nodes;
+
+  // Convert the duplicate map to the expected output format
+  const duplicateProjects = [];
+  for (const [name, roots] of duplicateMap.entries()) {
+    duplicateProjects.push({ name, roots });
+  }
+
+  return { nodes, duplicateProjects };
 }
 
 /**
@@ -293,10 +326,12 @@ export function buildNodes(projects) {
  *   filesystem existence (the marker is a directory, which `readFileAt`
  *   cannot answer) and the provider's one-call graph reader, both injectable
  *   for the same reason `listFiles` is.
- * @returns {{root: string, files: string[], workspace: object, graph: object, skippedProjects: object[], fileFailures: object[], importSites: object[], nativeMarker: boolean, nativeModelFailure: string|null, moonModelFailure: string|null, nxModelFailure: string|null, workspaceLayoutFailure: string|null}}
+ * @returns {{root: string, files: string[], workspace: object, graph: object, skippedProjects: object[], fileFailures: object[], importSites: object[], duplicateProjects: {name: string, roots: string[]}[], nativeMarker: boolean, nativeModelFailure: string|null, moonModelFailure: string|null, nxModelFailure: string|null, workspaceLayoutFailure: string|null}}
  *   `importSites` is the whole tree's analysis output, retained past the graph
  *   build for the rule engine's evidence index — see this module header's "Why
- *   the whole tree's import sites stay on the index".
+ *   the whole tree's import sites stay on the index". `duplicateProjects` is
+ *   the Nx-shaped branch's own (#375): empty everywhere but that branch, which
+ *   is the only one that resolves names from `project.json` files itself.
  * @throws {Error} when the file list cannot be obtained. Loud on purpose: an
  *   index built from no files would put every file in no project, and a file in
  *   no project has no boundary to cross — a clean report, produced by not
@@ -359,7 +394,7 @@ export function buildWorkspaceIndex({
   }
 
   const { projects, skipped } = discoverProjects({ files, readFile });
-  const nodes = buildNodes(projects);
+  const { nodes, duplicateProjects } = buildNodes(projects);
   // The same Module Federation fact the CLI path computes, from the same
   // predicate (`../workspace.mjs` → `annotateMFERemotes`): a CLI verdict and an
   // editor verdict on the same import must match, and the field failing closed
@@ -394,6 +429,18 @@ export function buildWorkspaceIndex({
 
   const { importSites, fileFailures } = analyzeTrackedFiles({ files, workspace });
 
+  // The manifest track — Maven, Gradle, csproj — draws its edges here too.
+  // The CLI's Nx face gets them from the polyglot plugin inside Nx's own
+  // graph computation; this index has no plugin host, so it folds the same
+  // resolvers' records itself (`../graph/create-dependencies.mjs`), the way
+  // the native and Moon branches below do. The failure list doubles as the
+  // no-throw guard (that module's `resolveDeclaredManifestFailures` — each
+  // resolver refuses on exactly the failures its `*ManifestFailures` twin
+  // reports, same memoized model) and joins `fileFailures`, so a manifest
+  // the index cannot read is a named gap on every document rather than
+  // silently missing edges.
+  const manifestRefusalFailures = resolveDeclaredManifestFailures(workspace);
+
   // `nx.json`'s `workspaceLayout` reaches the rule engine here the same way
   // `../providers/nx.mjs`'s `readProjectGraph` merges it onto the graph it
   // returns to `cli.mjs` — see that function's own doc for why a merge step
@@ -454,21 +501,27 @@ export function buildWorkspaceIndex({
         `workspace, whose projects are declared in package.json, yields none`
       : null;
 
+  const graph = {
+    nodes,
+    dependencies: buildDependencies({ importSites, nodes, projectOf }),
+    ...(workspaceLayout === undefined ? {} : { workspaceLayout }),
+  };
+  if (manifestRefusalFailures.length === 0) {
+    mergeDeclaredEdges(graph, resolveDeclaredManifestEdges(workspace));
+  }
+
   return {
     root,
     files,
     workspace,
-    graph: {
-      nodes,
-      dependencies: buildDependencies({ importSites, nodes, projectOf }),
-      ...(workspaceLayout === undefined ? {} : { workspaceLayout }),
-    },
+    graph,
     skippedProjects: skipped,
-    fileFailures,
+    fileFailures: [...fileFailures, ...manifestRefusalFailures],
     // Retained past the graph build — the evidence half of `evaluate()`'s
     // input (`./diagnose.mjs` composes its run from these). See this module
     // header's "Why the whole tree's import sites stay on the index".
     importSites,
+    duplicateProjects,
     nativeMarker: false,
     nativeModelFailure: null,
     moonModelFailure: null,
@@ -570,6 +623,7 @@ function buildNativeWorkspaceIndex({ root, files, readFile, tsConfig }) {
       // was read — and an empty list is the honest answer, not a missing field
       // every consumer would have to guard against.
       importSites: [],
+      duplicateProjects: [],
       nativeMarker: true,
       nativeModelFailure: cause?.message ?? String(cause),
       moonModelFailure: null,
@@ -605,9 +659,26 @@ function buildNativeWorkspaceIndex({ root, files, readFile, tsConfig }) {
   // reports the same way: an unowned file is analyzed by nothing and judged
   // by nothing, which is exactly the hole `../providers/native/coverage.mjs`'s
   // own header names.
-  const fileFailures = [...discovered.failures, ...analysisFailures];
+  const manifestRefusalFailures = resolveDeclaredManifestFailures(workspace);
+  const fileFailures = [
+    ...discovered.failures,
+    ...analysisFailures,
+    // The manifest track's own could-not-complete failures, in the same
+    // whole-file shape — an unreadable pom/build.gradle/.csproj is a file
+    // this index could not analyze, exactly like the ones above.
+    ...manifestRefusalFailures,
+  ];
 
   const graph = nativeProvider.buildGraph({ discovered, importSites });
+  // The manifest track's edges fold in after the import sites — no plugin
+  // host exists on this branch to draw them (`../graph/create-dependencies.mjs`
+  // names the faces that route through the Nx hook instead). The failure list
+  // above doubles as the no-throw guard: each resolver refuses on exactly the
+  // failures its `*ManifestFailures` twin reports from the same memoized model.
+  if (manifestRefusalFailures.length === 0) {
+    mergeDeclaredEdges(graph, resolveDeclaredManifestEdges(workspace));
+  }
+
   // The same Module Federation and `package.json` facts the Nx branch and
   // `../../cli.mjs`'s native branch both compute, from the same shared
   // functions (`../workspace.mjs`) — a CLI verdict and an editor verdict on
@@ -626,6 +697,7 @@ function buildNativeWorkspaceIndex({ root, files, readFile, tsConfig }) {
     // input (`./diagnose.mjs` composes its run from these), on this branch
     // exactly as on the Nx-shaped one.
     importSites,
+    duplicateProjects: [],
     nativeMarker: true,
     nativeModelFailure: null,
     moonModelFailure: null,
@@ -673,6 +745,7 @@ function buildMoonWorkspaceIndex({ root, files, readFile, tsConfig, readGraph })
       // empty list is the honest answer, not a missing field every consumer
       // would have to guard against.
       importSites: [],
+      duplicateProjects: [],
       nativeMarker: false,
       nativeModelFailure: null,
       moonModelFailure: cause?.message ?? String(cause),
@@ -704,17 +777,29 @@ function buildMoonWorkspaceIndex({ root, files, readFile, tsConfig, readGraph })
     projectOf: (file) => projectOfFile.get(file),
   });
 
+  // The manifest track folds in after the import sites, for the same
+  // no-face-qualifier reason the CLI's Moon branch states at its own fold —
+  // Moon has no plugin hook to draw declared edges either. The failure list
+  // doubles as the no-throw guard and joins `fileFailures`, so an
+  // unreadable pom/build.gradle/.csproj is a named gap rather than silently
+  // missing edges.
+  const manifestRefusalFailures = resolveDeclaredManifestFailures(workspace);
+  if (manifestRefusalFailures.length === 0) {
+    mergeDeclaredEdges(graph, resolveDeclaredManifestEdges(workspace));
+  }
+
   return {
     root,
     files,
     workspace,
     graph,
     skippedProjects: [],
-    fileFailures,
+    fileFailures: [...fileFailures, ...manifestRefusalFailures],
     // Retained past the graph build — the evidence half of `evaluate()`'s
     // input (`./diagnose.mjs` composes its run from these), on this branch
     // exactly as on the other two.
     importSites,
+    duplicateProjects: [],
     nativeMarker: false,
     nativeModelFailure: null,
     moonModelFailure: null,
@@ -799,12 +884,13 @@ function buildMoonWorkspaceIndex({ root, files, readFile, tsConfig, readGraph })
  *
  * Each sentence names a path, so the diagnostic says which file to open.
  *
- * @param {{skippedProjects?: {file: string, reason: string}[], fileFailures?: {sourceFile: string, reason: string}[], nativeModelFailure?: string|null, moonModelFailure?: string|null, nxModelFailure?: string|null, workspaceLayoutFailure?: string|null}} index
+ * @param {{skippedProjects?: {file: string, reason: string}[], fileFailures?: {sourceFile: string, reason: string}[], duplicateProjects?: {name: string, roots: string[]}[], nativeModelFailure?: string|null, moonModelFailure?: string|null, nxModelFailure?: string|null, workspaceLayoutFailure?: string|null}} index
  * @returns {string[]}
  */
 export function indexGaps({
   skippedProjects = [],
   fileFailures = [],
+  duplicateProjects = [],
   nativeModelFailure = null,
   moonModelFailure = null,
   nxModelFailure = null,
@@ -840,6 +926,11 @@ export function indexGaps({
             `so imports across a non-default apps/libs boundary are judged against the default layout ` +
             `instead of the one this workspace declared`,
         ]),
+    ...duplicateProjects.map(
+      ({ name, roots }) =>
+        `multiple projects resolve to the name '${name}': ${roots.map((r) => `'${r}'`).join(" and ")} — ` +
+        `only the first is indexed; files in the shadowed projects will show no diagnostics`,
+    ),
     ...skippedProjects.map(
       ({ file, reason }) =>
         `${file} ${firstLine(reason)}, so that project is missing from the graph entirely`,

package/src/options.mjs

@@ -182,12 +182,20 @@ export function resolveOptions(rawOptions) {
  * This plugin's own entry in an `nx.json` `plugins` array, in either form Nx
  * accepts: a bare string, or `{plugin, options}`.
  *
- * Matched on the specifier's TAIL rather than by equality, because the same
- * plugin is named three legitimate ways — `@ecoma-io/archkeep/nx` once it
- * resolves from the registry, `./packages/archkeep/nx.mjs` inside this
- * repository, and a path with or without the `.mjs` in a workspace that
- * vendored it. Requiring one spelling would make the options invisible in the
- * other two, and invisible options mean the defaults — silently.
+ * Matched by exact package specifier or relative/aliased path, never by bare
+ * suffix. The three legitimate spellings this plugin recognizes are:
+ *
+ * - `@ecoma-io/archkeep/nx` — the full package specifier from npm
+ * - `archkeep/nx` — the bare shorthand (accepted for backward compatibility)
+ * - `./packages/archkeep/nx.mjs`, `../../node_modules/@ecoma-io/archkeep/nx`,
+ *   or other relative/aliased spellings of the same package
+ *
+ * A third-party plugin whose specifier happens to end with `/archkeep/nx`
+ * (e.g., `vendor-archkeep/nx`, `@other-scope/archkeep/nx`) is NOT claimed:
+ * such a package has its own options schema and this plugin must neither
+ * validate it nor read it. The suffix-only match that existed before would
+ * claim those options, validate them against this plugin's schema, and throw
+ * on any unknown key — a false violation on a stranger's configuration.
  *
  * The bare package specifier (`@ecoma-io/archkeep`, with no `/nx`) does NOT
  * match: that resolves to the engine entry, which exports neither `name` nor
@@ -202,7 +210,22 @@ function namesThisPlugin(entry) {
     typeof entry === "string" ? entry : /** @type {{ plugin?: unknown }} */ (entry)?.plugin;
   if (typeof specifier !== "string") return false;
   const withoutExt = specifier.replace(/\.mjs$/u, "");
-  return withoutExt === "archkeep/nx" || withoutExt.endsWith("/archkeep/nx");
+
+  // Exact match against this package's own specifier
+  if (withoutExt === "@ecoma-io/archkeep/nx" || withoutExt === "archkeep/nx") {
+    return true;
+  }
+
+  // Match relative/aliased spellings of the same package (e.g.,
+  // `./packages/archkeep/nx.mjs`, `../../node_modules/@ecoma-io/archkeep/nx`).
+  // These paths start with `./` or `../` and end with `/archkeep/nx`,
+  // which distinguishes them from third-party packages like `vendor-archkeep/nx`.
+  const isRelativePath = withoutExt.startsWith("./") || withoutExt.startsWith("../");
+  if (isRelativePath && withoutExt.endsWith("/archkeep/nx")) {
+    return true;
+  }
+
+  return false;
 }
 
 /**