@ecoma-io/archkeep 0.14.0 → 0.16.0

package/src/commands/trajectory.mjs

@@ -0,0 +1,437 @@
+/**
+ * The `trajectory` command: which deterministic signals moved across a
+ * snapshot history, aggregated over every observation the directory holds.
+ *
+ * `history <dir>` answers "what happened at each transition" — one record per
+ * consecutive pair, each classified by the signals it carries. `trajectory
+ * <dir>` reads the same directory through the same reader and the same
+ * transition classifier (`./history.mjs`'s `readSnapshots` and
+ * `classifyTransition`) and answers the question an event list cannot:
+ * **over the whole series, which signals fired how often, what did the graph
+ * gain and lose in total, and what persisted through every observation.**
+ *
+ * ## What a trend means here — and what it does not
+ *
+ * A trend is a count or a set that changed over an ORDERED sequence of
+ * observations. It is never a judgment: nothing here scores the architecture,
+ * weights a signal, or decides whether more edges or fewer violations is
+ * "better". Every number is either read off stored bytes or derived from them
+ * by a stated rule; a human or an agent decides what the facts mean. Doctrine
+ * owns that split (`../../../../docs/doctrine/architecture-authority.md`):
+ * this command produces evidence, never a verdict — it is descriptive, and it
+ * never exits 1.
+ *
+ * ## The observation basis
+ *
+ * One observation is ONE stored `graph --format json` snapshot — a capture
+ * point. Snapshot capture deduplicates unchanged architectures, so the number
+ * of observations is the number of recorded states, NOT a count of commits,
+ * days, or captures attempted (`../../../../docs/usage/history.md`). The
+ * result names its basis explicitly (`observations.basis`), and no field
+ * converts observations into any unit of time.
+ *
+ * ## Stable identity, proven not guessed
+ *
+ * Persistence claims are only as honest as the identity beneath them. Both
+ * identities here are ones `diff` already defines and uses (`./diff.mjs`): a
+ * project IS its `name`, an edge IS its `(source, target, type)` triple
+ * (`edgeIdentityKey`). Nothing weaker — no array index, no display order, no
+ * line number — participates in any cross-observation claim.
+ *
+ * Findings have NO stable identity in stored snapshots, because a snapshot
+ * carries no findings at all — only the graph and the policy fingerprint
+ * (the disclosure `./history.mjs` states). So this command reports NO
+ * violation-level trajectory: no introduced/resolved/persisting counts for
+ * boundary violations can be reconstructed from stored evidence, and
+ * inventing one would fabricate persistence for facts the snapshots never
+ * held. `delta` classifies real violations between two live points;
+ * `debt` ages today's ledger facts across snapshots. Neither job is repeated
+ * here under a second definition of time.
+ *
+ * ## Unknown evidence never becomes zero
+ *
+ * The empty-result invariant (`../../../../AGENTS.md`) applied to an
+ * aggregate: a value this history cannot establish reads `null` beside an
+ * explicit reason, never as a clean zero. Three cases, all loud:
+ *
+ * - **No transitions derivable** — a directory with ONE snapshot yields no
+ *   consecutive pair, so `available` is `false`, `unavailableReason` is
+ *   `"insufficient_history"`, and every derived number is `null`. Reporting
+ *   delta 0 there would claim stability over a history that cannot show
+ *   movement.
+ * - **Incomparable metadata** — a fingerprint or a provenance on one side of
+ *   a pair only. `snapshot-meta.mjs` refuses to call that "the same", and so
+ *   does this aggregation: such a transition counts under
+ *   `signals.incomparable` (and its specific disclosure), and — stricter than
+ *   `history`'s per-transition label, which keeps the note beside the record —
+ *   it does NOT count as `unchanged`. An aggregate has no notes line to carry
+ *   the disclosure, so the exclusion is the disclosure.
+ * - **An unreadable or malformed snapshot** stops the whole run (exit 3,
+ *   through `readSnapshots`), never silently drops out of the aggregate —
+ *   a missing observation must not read as a quiet one.
+ *
+ * An empty directory is refused outright, exactly like `history` and `debt`
+ * refuse it: zero observations is no record at all, not a clean trajectory.
+ *
+ * ## Determinism and complexity
+ *
+ * Pure function of the snapshot bytes: plain `<` string comparison everywhere,
+ * fixed key insertion order, no clock, no locale. Complexity is linear in the
+ * input — O(N) classification passes over N snapshots, each O(P + E) in the
+ * projects and edges those two snapshots hold, plus one linear persistence
+ * sweep over every project and edge ever seen. There is no pairwise
+ * O(N²) comparison and no re-analysis of source files: everything is read
+ * from stored envelopes.
+ *
+ * What it needs from its caller is a workspace root context (for the
+ * envelope's workspace header and the directory-containment check — the
+ * trajectory itself never touches the live graph) and the directory path.
+ * It does not print, and it does not decide the process's exit code —
+ * `../../cli.mjs` owns those (`./README.md`).
+ */
+import { jsonEnvelope, renderJson } from "../report/json.mjs";
+import { formatTrajectoryReport } from "../report/trajectory-text.mjs";
+import { edgeIdentityKey } from "./diff.mjs";
+import { classifyTransition, readSnapshots } from "./history.mjs";
+import { resolveProvenance } from "./provenance.mjs";
+
+/**
+ * What one observation is. Stated as a value rather than left implicit, so a
+ * consumer reading `observations: 12` knows exactly what was counted — and
+ * what was not (commits, days, capture attempts).
+ */
+const OBSERVATION_BASIS = "graph_snapshots";
+
+/**
+ * The reason `available` is `false` for a one-snapshot history. A named
+ * constant in the envelope, so a consumer branches on a documented value
+ * rather than on prose.
+ */
+export const INSUFFICIENT_HISTORY = "insufficient_history";
+
+/**
+ * The derived-number block for one structural axis (projects keyed by name,
+ * edges keyed by `edgeIdentityKey`). Fields ending in `Events` count
+ * transition EVENTS — cumulative add/remove occurrences, which can exceed the
+ * endpoint movement when an entity churns (add → remove → add is two added
+ * events, one removed, and equal first/current sets). The endpoint fields
+ * compare FIRST and LAST observation sets only:
+ *
+ * - `introduced` — present in the last observation, absent from the first.
+ * - `resolved` — present in the first observation, absent from the last.
+ * - `persistent` — present in EVERY observation, first through last.
+ * - `delta` — `current − first`.
+ *
+ * Every derived field is `null` when the history holds fewer than two
+ * observations — unavailable is never folded into a zero.
+ *
+ * @typedef {object} TrajectoryAxis
+ * @property {number} first Projects/edges in the first observation.
+ * @property {number} current Projects/edges in the last observation.
+ * @property {number|null} delta
+ * @property {number|null} addedEvents
+ * @property {number|null} removedEvents
+ * @property {number|null} changedEvents Projects only: metadata churn
+ *   (tags/type/root changes per `computeDiff`). Edges carry no changed-event
+ *   count — a type flip IS a removal plus an addition under the triple
+ *   identity (`./diff.mjs`).
+ * @property {number|null} introduced
+ * @property {number|null} resolved
+ * @property {number|null} persistent
+ */
+
+/**
+ * Aggregates the deterministic trajectory over an ordered snapshot set.
+ * Pure: same bytes in, same object out. All keys are always present — shape
+ * never depends on history content (E-F05); unavailable values are `null`
+ * with `available`/`unavailableReason` saying why.
+ *
+ * @param {{name: string, path: string, envelope: object, id: string}[]} files
+ *   From `readSnapshots(dir)`, in history order.
+ * @returns {{observations: {count: number, basis: string,
+ *   first: string|null, last: string|null, withProvenance: number,
+ *   dirtyProvenance: number}, available: boolean, unavailableReason: string|null,
+ *   transitions: {count: number, architecture: number, policy: number,
+ *     provider: number, codeDrift: number, incomparable: number, unchanged: number},
+ *   disclosures: {policyOneSided: number, provenanceOneSided: number, crossRepo: number},
+ *   projects: TrajectoryAxis, edges: TrajectoryAxis}}
+ */
+export function computeTrajectory(files) {
+  const n = files.length;
+  const available = n >= 2;
+
+  // Per-observation facts, straight off the envelopes — no pairing needed.
+  let withProvenance = 0;
+  let dirtyProvenance = 0;
+  for (const file of files) {
+    const provenance = file.envelope.workspace.provenance ?? null;
+    if (provenance !== null) withProvenance += 1;
+    if (provenance?.dirty === true) dirtyProvenance += 1;
+  }
+
+  /** @type {{count: number, architecture: number, policy: number, provider: number,
+        codeDrift: number, incomparable: number, unchanged: number}} */
+  const transitions = {
+    count: 0,
+    architecture: 0,
+    policy: 0,
+    provider: 0,
+    codeDrift: 0,
+    incomparable: 0,
+    unchanged: 0,
+  };
+  const disclosures = { policyOneSided: 0, provenanceOneSided: 0, crossRepo: 0 };
+
+  // Cumulative transition events, accumulated while classifying. Kept as
+  // scalars rather than deferred to a second pass — one walk over the pairs.
+  let addedProjectEvents = 0;
+  let removedProjectEvents = 0;
+  let changedProjectEvents = 0;
+  let addedEdgeEvents = 0;
+  let removedEdgeEvents = 0;
+
+  // Persistence sets: entity key → number of observations containing it.
+  // Built once per axis in the same walk that reads each snapshot's members,
+  // so cost stays linear in the total snapshot content.
+  /** @type {Map<string, number>} */
+  const projectPresence = new Map();
+  /** @type {Map<string, number>} */
+  const edgePresence = new Map();
+
+  let firstProjects = null;
+  let lastProjects = null;
+  let firstEdges = null;
+  let lastEdges = null;
+
+  for (let i = 0; i < n; i++) {
+    const file = files[i];
+    const projectKeys = new Set(file.envelope.result.projects.map((p) => p.name));
+    // Project identity is the name — the same key `computeDiff` indexes by
+    // (`./diff.mjs`). Edge identity is the `(source, target, type)` triple,
+    // shared through `edgeIdentityKey` so both commands answer "same edge?"
+    // from one definition.
+    const edgeKeys = new Set(file.envelope.result.dependencies.map(edgeIdentityKey));
+
+    for (const key of projectKeys) projectPresence.set(key, (projectPresence.get(key) ?? 0) + 1);
+    for (const key of edgeKeys) edgePresence.set(key, (edgePresence.get(key) ?? 0) + 1);
+
+    if (i === 0) {
+      firstProjects = projectKeys;
+      firstEdges = edgeKeys;
+    }
+    if (i === n - 1) {
+      lastProjects = projectKeys;
+      lastEdges = edgeKeys;
+    }
+
+    if (i + 1 < n) {
+      const { record, meta } = classifyTransition(file, files[i + 1]);
+      transitions.count += 1;
+      if (record.architectureChanged) transitions.architecture += 1;
+      if (record.policyChanged === true) transitions.policy += 1;
+      if (record.providerChanged) transitions.provider += 1;
+      if (record.codeDrift) transitions.codeDrift += 1;
+
+      // The asymmetric-evidence cases, counted from `meta` itself — never
+      // parsed back out of the record's prose notes.
+      if (meta.policyOneSided) disclosures.policyOneSided += 1;
+      if (meta.provenanceOneSided) disclosures.provenanceOneSided += 1;
+      if (meta.crossRepo) disclosures.crossRepo += 1;
+      const incomparable = meta.policyOneSided || meta.provenanceOneSided;
+      if (incomparable) transitions.incomparable += 1;
+
+      // `unchanged` is deliberately STRICTER than the label `history`'s text
+      // renderer prints for the same transition: an aggregate has no
+      // per-transition note to disclose "one side carried no fingerprint",
+      // so a pair whose metadata could not be compared cannot land in the
+      // bucket whose plain meaning is "checked, nothing moved".
+      if (
+        !record.architectureChanged &&
+        !record.providerChanged &&
+        record.policyChanged !== true &&
+        !record.codeDrift &&
+        !incomparable
+      ) {
+        transitions.unchanged += 1;
+      }
+
+      if (record.changes) {
+        addedProjectEvents += record.changes.addedProjects.length;
+        removedProjectEvents += record.changes.removedProjects.length;
+        changedProjectEvents += record.changes.changedProjects.length;
+        addedEdgeEvents += record.changes.addedEdges.length;
+        removedEdgeEvents += record.changes.removedEdges.length;
+      }
+    }
+  }
+
+  /**
+   * Counts entities of `presence` that appeared in ALL `n` observations.
+   * Only meaningful when `n >= 2`; the caller nulls it otherwise.
+   *
+   * @param {Map<string, number>} presence
+   * @returns {number}
+   */
+  const persistentCount = (presence) => {
+    let count = 0;
+    for (const seen of presence.values()) if (seen === n) count += 1;
+    return count;
+  };
+
+  /**
+   * The endpoint-set movement between the first and last observation.
+   *
+   * @param {Set<string>|null} first
+   * @param {Set<string>|null} current
+   * @returns {{introduced: number, resolved: number}}
+   */
+  const endpointMovement = (first, current) => {
+    let introduced = 0;
+    for (const key of current) if (!first.has(key)) introduced += 1;
+    let resolved = 0;
+    for (const key of first) if (!current.has(key)) resolved += 1;
+    return { introduced, resolved };
+  };
+
+  const projectMovement =
+    available && firstProjects !== null && lastProjects !== null
+      ? endpointMovement(firstProjects, lastProjects)
+      : null;
+  const edgeMovement =
+    available && firstEdges !== null && lastEdges !== null
+      ? endpointMovement(firstEdges, lastEdges)
+      : null;
+
+  /** @type {TrajectoryAxis} */
+  const projects = {
+    first: firstProjects === null ? 0 : firstProjects.size,
+    current: lastProjects === null ? 0 : lastProjects.size,
+    delta: available ? lastProjects.size - firstProjects.size : null,
+    addedEvents: available ? addedProjectEvents : null,
+    removedEvents: available ? removedProjectEvents : null,
+    changedEvents: available ? changedProjectEvents : null,
+    introduced: available ? projectMovement.introduced : null,
+    resolved: available ? projectMovement.resolved : null,
+    persistent: available ? persistentCount(projectPresence) : null,
+  };
+  /** @type {TrajectoryAxis} */
+  const edges = {
+    first: firstEdges === null ? 0 : firstEdges.size,
+    current: lastEdges === null ? 0 : lastEdges.size,
+    delta: available ? lastEdges.size - firstEdges.size : null,
+    addedEvents: available ? addedEdgeEvents : null,
+    removedEvents: available ? removedEdgeEvents : null,
+    // No `changedEvents` on this axis: under the triple identity an edge
+    // type flip is already a removal plus an addition (`./diff.mjs`).
+    changedEvents: null,
+    introduced: available ? edgeMovement.introduced : null,
+    resolved: available ? edgeMovement.resolved : null,
+    persistent: available ? persistentCount(edgePresence) : null,
+  };
+
+  return {
+    observations: {
+      count: n,
+      basis: OBSERVATION_BASIS,
+      first: n > 0 ? files[0].name : null,
+      last: n > 0 ? files[n - 1].name : null,
+      withProvenance,
+      dirtyProvenance,
+    },
+    available,
+    unavailableReason: available ? null : INSUFFICIENT_HISTORY,
+    transitions,
+    disclosures,
+    projects,
+    edges,
+  };
+}
+
+/**
+ * Runs the `trajectory` command: reads the snapshot directory, aggregates the
+ * deterministic trajectory, and builds the report.
+ *
+ * Unlike `debt`, no boundary law is loaded: the fingerprints being compared
+ * travel INSIDE the snapshots, so the law a run judges is the law each
+ * observation was captured under — there is no `--config` override because
+ * there is no current-law input to override with.
+ *
+ * @param {string} dir Absolute path to the history directory.
+ * @param {object} commandContext From `resolveCommandContext` — used for the
+ *   envelope's workspace header and `readSnapshots`' containment check. The
+ *   trajectory itself never touches the live graph.
+ * @param {{io?: {readSnapshots?: Function, resolveProvenance?: Function}}} [options]
+ *   Injectable IO so a test drives the aggregation without the filesystem or
+ *   git, mirroring `./history.mjs`'s seam.
+ * @returns {{status: "ok", trajectory: object, coverage: object,
+ *   report: {text: string, json: string}}}
+ * @throws {Error} when the directory contains no snapshots or a snapshot
+ *   cannot be read or validated (exit-3 class, via `readSnapshots` and the
+ *   same refusal `history`/`debt` make).
+ */
+export function trajectoryCommand(dir, commandContext, options = {}) {
+  const { root, provider, marker } = commandContext;
+  const io = options.io ?? {};
+
+  const read = (io.readSnapshots ?? readSnapshots)(dir, root);
+
+  if (read.files.length === 0) {
+    // An empty directory is not a clean trajectory — it is no record at all.
+    // Zero observations would read as "nothing ever changed", a claim about a
+    // history that does not exist. Same refusal, word for word in spirit, as
+    // `./history.mjs` and `./debt.mjs` make.
+    throw new Error(
+      `archkeep: the history directory '${dir}' contains no snapshots — there is no history to ` +
+        `aggregate. Capture one first with 'archkeep history <dir> --capture' (or point the ` +
+        `command at the directory where you keep graph snapshots).`,
+    );
+  }
+
+  const result = computeTrajectory(read.files);
+  const full = { dir, ...result };
+
+  const lastSnapshot = read.files[read.files.length - 1].envelope;
+  const coverage = {
+    complete: true,
+    projects: lastSnapshot.result.projects.length,
+    analyzedFiles: lastSnapshot.coverage.analyzedFiles,
+    imports: lastSnapshot.coverage.imports,
+    notAnalyzed: [],
+    blindSpots: [],
+    notes: [
+      `counts are snapshot-relative: ${result.observations.count} observation${
+        result.observations.count === 1 ? "" : "s"
+      } are stored graph snapshots — capture points, not commits, days, or captures attempted`,
+      "rule-impact cannot be recomputed from stored snapshots — snapshots carry the graph and " +
+        "the policy fingerprint, not the constraint table or import sites, so no violation-level " +
+        "trajectory is reported. Run `delta` between two live points, or `check` at any commit.",
+    ],
+  };
+
+  const envelope = jsonEnvelope({
+    command: "trajectory",
+    context: {
+      root,
+      provider,
+      marker,
+      // The same field every other envelope carries — THIS run's git origin,
+      // not the head snapshot's (`workspace.provenance` means one thing across
+      // the whole envelope surface; `docs/reference/json-output.md`).
+      provenance: (io.resolveProvenance ?? resolveProvenance)(root),
+    },
+    status: "ok",
+    exitCode: 0,
+    coverage,
+    result: full,
+  });
+
+  return {
+    status: "ok",
+    trajectory: full,
+    coverage,
+    report: {
+      text: formatTrajectoryReport({ trajectory: full, coverage }),
+      json: renderJson(envelope),
+    },
+  };
+}

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