@ecoma-io/archkeep 0.15.0 → 0.16.1

package/src/providers/native/graph.mjs

@@ -232,3 +232,61 @@ export function buildNativeGraph({
     ...(exemptedFiles && exemptedFiles.length > 0 ? { exemptedFiles } : {}),
   };
 }
+
+/**
+ * Folds manifest-resolver records — `{source, target, sourceFile, type}` from
+ * `../../graph/create-dependencies.mjs`'s `resolveDeclaredManifestEdges` —
+ * into an already-built graph's `dependencies`, in place. The callers are the
+ * graph assemblies that have no plugin host to draw these edges for them:
+ * this module's own `buildGraph` (the CLI's native branch and this package's
+ * language-server index), the Moon branch of both, and the language server's
+ * Nx-shaped index. On the CLI's Nx branch the polyglot plugin registers into
+ * Nx's own graph computation instead — `resolvePolyglotDependencies` there,
+ * these same resolvers — so that face arrives with the edges already drawn.
+ *
+ * Deduplication is by `(source, target, type)`, the same key `buildDependencies`
+ * dedupes import sites by and the same key the JSON envelope flattens on, so a
+ * dependency witnessed by BOTH tracks — a written `using` and the
+ * `<ProjectReference>` for it, a Kotlin import and the Gradle `project(":x")`
+ * — carries one record, exactly as one witnessed by two imports does. The
+ * resolvers iterate only the workspace's own projects and resolve every target
+ * against that same project list, so source and target are nodes of the graph
+ * this fold serves by construction; no membership check is taken here, because
+ * one that skipped would be the silent direction — an edge dropped for not
+ * being a node is a finding unreported, where a mismatch between the merged
+ * records and the graph's nodes is a caller bug that should surface.
+ *
+ * @param {{nodes: Record<string, object>, dependencies?: Record<string, {source: string, target: string, type: string}[]>}} graph
+ *   Mutated in place.
+ * @param {{source: string, target: string, sourceFile?: string, type: string}[]} records
+ * @returns {{nodes: Record<string, object>, dependencies: Record<string, {source: string, target: string, type: string}[]>}} The same graph.
+ */
+export function mergeDeclaredEdges(graph, records) {
+  // Null-prototype for the same reason `buildDependencies` above uses one:
+  // every key is a project name this package does not control.
+  const dependencies = graph.dependencies ?? Object.create(null);
+  graph.dependencies = dependencies;
+  const seen = new Set();
+  for (const list of Object.values(dependencies)) {
+    for (const edge of list ?? []) {
+      seen.add(JSON.stringify([edge.source, edge.target, edge.type]));
+    }
+  }
+  for (const record of records) {
+    const key = JSON.stringify([record.source, record.target, record.type]);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    (dependencies[record.source] ??= []).push({
+      source: record.source,
+      target: record.target,
+      type: record.type,
+    });
+  }
+  // The cast is the post-condition the signature promises: the fold above
+  // guarantees `dependencies` exists on the graph it returns, but the
+  // parameter's declared type — which admits a graph arriving without one —
+  // is what `graph` carries here.
+  return /** @type {{nodes: Record<string, object>, dependencies: Record<string, {source: string, target: string, type: string}[]>}} */ (
+    graph
+  );
+}

package/src/providers/native/model.mjs

@@ -195,10 +195,66 @@ export const DEFAULT_MANIFEST_NAMES = Object.freeze([
   "go.mod",
   "Cargo.toml",
   "pyproject.toml",
+  // Maven: every tracked root pom.xml anchors a project (ADR 0005). Identity
+  // is `(groupId, artifactId)` read by `../../analysis/jvm/maven.mjs`; the
+  // name follows the same precedence as every other inferred manifest, so
+  // pom-discovered projects land on their directory basename unless a
+  // declared row names them.
+  "pom.xml",
+  // Gradle: settings.gradle / settings.gradle.kts anchors a Gradle build
+  // (ADR 0005 Decision 2). Identity is the root project name and included
+  // projects from the settings file; edges are read from build.gradle /
+  // build.gradle.kts by `../../analysis/jvm/gradle.mjs`. The settings file
+  // is the discovery manifest — it defines the reactor structure — while
+  // the build files hold the dependency declarations.
+  "settings.gradle",
+  "settings.gradle.kts",
+  // .NET/C#: every tracked root .csproj anchors a project (ADR 0006). Identity
+  // is the project name read by `../../analysis/dotnet/csproj.mjs`; the
+  // name follows the same precedence as every other inferred manifest, so
+  // csproj-discovered projects land on their directory basename unless a
+  // declared row names them.
+  "*.csproj",
 ]);
 
 const PROJECT_TYPES = ["app", "lib", "e2e"];
 
+/**
+ * The deliberate default for `projects.infer.exclude` — the anchor-exclusion
+ * half of the phantom-project policy (issue #371): a tracked manifest inside a
+ * directory that is documentation or test data about the workspace, rather
+ * than a part of it, never anchors an inferred project, because inference over
+ * it would judge a phantom as real. `docs/`, `fixtures/` and `__fixtures__/`
+ * as whole path segments are the complete set: those three names mean "data
+ * about the tree" in every convention this package has measured, and a name
+ * like `examples/` was deliberately left OFF it — example projects are
+ * commonly real, built, governed code, so excluding them by name would be the
+ * same over-broad-by-name error the `obj`/`bin` half of the same issue
+ * repudiated (`./discover.mjs`'s `isDotnetGeneratedOutput`).
+ *
+ * Two facts make this exclusion safe rather than a silent hole:
+ *
+ * - `projects.declared` is exempt — a workspace with a real project under one
+ *   of these paths declares it, and declaration is the authoritative channel
+ *   inference never touches.
+ * - A dropped anchor's analyzable files do not vanish silently: they surface
+ *   through `./coverage.mjs`'s unclaimed-file judgment as whole-file failures
+ *   until the workspace either declares the project or records a reasoned
+ *   `coverage.exempt` row — which is the loud, explicit opt-in for "this
+ *   directory is fixture data".
+ *
+ * An explicit `exclude` list REPLACES this default (the `tsc` convention for
+ * the same field): a workspace that names its own list takes over the whole
+ * decision, `exclude: []` included — that spelling is the documented opt-out.
+ *
+ * @see DEFAULT_MANIFEST_NAMES
+ */
+export const DEFAULT_INFER_EXCLUDE = Object.freeze([
+  "**/docs/**",
+  "**/fixtures/**",
+  "**/__fixtures__/**",
+]);
+
 /** @type {(value: unknown) => value is Record<string, unknown>} */
 const isPlainObject = (value) =>
   typeof value === "object" && value !== null && !Array.isArray(value);
@@ -702,7 +758,9 @@ export function normalizeNativeModel(raw) {
           : {
               manifests: rawInfer.manifests ?? DEFAULT_MANIFEST_NAMES,
               include: rawInfer.include ?? ["**"],
-              exclude: rawInfer.exclude ?? [],
+              // Replaces, never merges: an explicit list takes over the whole
+              // decision — `DEFAULT_INFER_EXCLUDE`'s doc comment owns the why.
+              exclude: rawInfer.exclude ?? DEFAULT_INFER_EXCLUDE,
             },
     },
     projectRules: /** @type {unknown[]} */ (raw.projectRules ?? []).map((row) => {

package/src/rules/index.mjs

@@ -176,13 +176,18 @@ const isProjectGraphProjectNode = (node) =>
  */
 function spellingOf(site) {
   const spelling = site.spelling;
-  if (typeof spelling?.path !== "boolean" || typeof spelling?.relative !== "boolean") {
+  if (
+    typeof spelling?.path !== "boolean" ||
+    typeof spelling?.relative !== "boolean" ||
+    typeof spelling?.namesOnly !== "boolean"
+  ) {
     throw new Error(
       `archkeep: ${site.sourceFile}:${site.line}:${site.column} imports ` +
         `'${site.specifier}' in a record carrying no \`spelling\` — the analysis contract ` +
-        `requires \`{ path, relative }\` on every import site, because whether a specifier ` +
-        `is a path and whether it stays inside its own project are per-language questions ` +
-        `only the analyzer can answer. See src/analysis/contract.md.`,
+        `requires \`{ path, relative, namesOnly }\` on every import site, because whether a ` +
+        `specifier is a path, whether it stays inside its own project, and whether its ` +
+        `language has any path spelling at all are per-language questions only the analyzer ` +
+        `can answer. See src/analysis/contract.md.`,
     );
   }
   return spelling;
@@ -585,8 +590,18 @@ function* candidateGroupsFor(site, ctx) {
   if (!sourceProject) return;
 
   // Relative and absolute paths are judged on their TEXT, before any resolution:
-  // the projects can be correct and the spelling still be the violation.
-  const absoluteIntoAnotherProject = isAbsoluteImportIntoAnotherProject(imp, ctx.workspaceLayout);
+  // the projects can be correct and the spelling still be the violation. The
+  // absolute half is a JavaScript-family convention — a bare `libs/x` deep
+  // import, a `/libs/x` absolute path — so it stands down entirely where the
+  // analyzer declared the language has no path spelling at all
+  // (`spelling.namesOnly`): a Go module path or a C# namespace beginning
+  // `libs/` is a name, and the name is the only spelling the language has
+  // (#376). The edge such an import resolves to is still judged by every check
+  // below — only this spelling check stands down, so gating it too broadly
+  // (on `spelling.path`, which is false for the bare JS form too) would trade
+  // this loud bug for a silent one against ESLint.
+  const absoluteIntoAnotherProject =
+    !spellingOf(site).namesOnly && isAbsoluteImportIntoAnotherProject(imp, ctx.workspaceLayout);
   let targetProject = absoluteIntoAnotherProject
     ? graph.nodes[findProjectForPath(imp, mappings)]
     : graph.nodes[getTargetProjectBasedOnRelativeImport(imp, site.sourceFile, mappings)];

package/src/rules/reachability.mjs

@@ -140,6 +140,8 @@ export function getPath(reach, graph, sourceProjectName, targetProjectName) {
     if (current === targetProjectName) break;
     if (!adjList[current]) break;
     adjList[current]
+      .slice()
+      .sort()
       .filter((adj) => visited.indexOf(adj) === -1)
       .filter((adj) => matrix[adj]?.[targetProjectName])
       .forEach((adj) => {

package/src/rules/tags.mjs

@@ -165,11 +165,13 @@ export function orphanedNotDependOnTags(depConstraints, graph) {
  * are what the message prints so a reader can see the hop that did it.
  */
 export function findDependenciesWithTags(targetProject, tags, graph, reach) {
-  const reachable = Object.keys(graph.nodes).filter(
-    (projectName) =>
-      pathExists(reach, targetProject.name, projectName) &&
-      tags.some((tag) => hasTag(graph.nodes[projectName], tag)),
-  );
+  const reachable = Object.keys(graph.nodes)
+    .sort()
+    .filter(
+      (projectName) =>
+        pathExists(reach, targetProject.name, projectName) &&
+        tags.some((tag) => hasTag(graph.nodes[projectName], tag)),
+    );
   return reachable.map((project) =>
     targetProject.name === project
       ? [targetProject]

package/src/rules/topology.mjs

@@ -254,13 +254,15 @@ export function circularViolation({
       targetProjectName: targetProject.name,
       path: circularPath.reduce((acc, v) => `${acc} -> ${v.name}`, sourceProject.name),
       filePaths: circularFilePath
+        .map((files) => files.filter((f) => typeof f === "string"))
         .map((files) =>
           files.length > 1
             ? `[${files.map((f) => `\n${spacer}${spacer}${f}`).join(",")}\n${spacer}]`
             : // Upstream indexes `files[0]` unguarded, printing `undefined` for a
-              // hop with no file to blame. Ours can legitimately have none, since
-              // the index only knows the files it was handed.
-              (files[0] ?? ""),
+              // hop with no file to blame. Ours can legitimately have none —
+              // a manifest-declared edge carries no import site — and a blank
+              // bullet names nothing, so the hop says what it is instead.
+              (files[0] ?? "(no source file — a manifest declares this dependency)"),
         )
         .reduce((acc, files) => `${acc}\n- ${files}`, `- ${sourceFile}`),
     },

package/src/workspace.mjs

@@ -28,11 +28,12 @@
  * is the same tracked-file set every resolver in this project already reasons
  * about ("Resolvers read tracked files only", project `AGENTS.md`).
  */
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { dirname, isAbsolute, join, posix, relative, resolve } from "node:path";
 
 import { containmentViolation } from "./containment.mjs";
 import { analyzeFile, languageOf } from "./analysis/analyze.mjs";
+import { basenameMatches } from "./analysis/manifest-util.mjs";
 import { fileFailure, projectOwning } from "./analysis/source-util.mjs";
 import { UsageError } from "./errors.mjs";
 import { parseNxJson } from "./nx-json.mjs";
@@ -57,29 +58,109 @@ export { environmentForTree, runProcess };
  * with a hoisted install, the right one by luck (same reason
  * `loadBoundaryConfig` takes a root — see `config.mjs`).
  *
+ * The walk is bounded by the enclosing git repository: a marker above the top
+ * level `git rev-parse --show-toplevel` names for `from` is tooling state,
+ * not this workspace's root. The case that made the bound necessary is
+ * `~/.moon` — moonrepo's user-level state directory, present on every machine
+ * moonrepo has ever run on (its own documentation puts the shared cache at
+ * `~/.moon/cache/shared`), which a walk reading only directory existence
+ * climbed to from any unmarked directory under the home directory, selecting
+ * `$HOME` as a "Moon workspace" and failing to load
+ * `$HOME/module-boundaries.config.mjs` instead of refusing (#339). The bound
+ * is inclusive: a marker ON the top level is the ordinary case, a repository
+ * that is itself the workspace. With no enclosing repository — or no `git` to
+ * ask — there is no bound, and the walk climbs as far as it did before one
+ * existed; the shape of the Moon markers is what holds the line there.
+ *
  * `markers` defaults to `nx.json` alone, so every existing caller keeps
  * finding exactly the root it found before. A native-provider caller passes
  * `[NX_CONFIG_FILE, ARCHKEEP_MODEL_FILE]` to recognise either root marker in
  * one walk — see `../cli.mjs`, which is the only caller that needs to tell
  * the two apart, and does so by checking which marker(s) the returned
- * directory actually carries.
+ * directory actually carries. A Moon marker names the directory's
+ * `workspace.yml` — the file moonrepo itself requires of a workspace — never
+ * the directory alone (`../providers/moon.mjs`'s `MOON_WORKSPACE_MARKER`):
+ * a bare `.moon` is the user-level state directory again, and directory
+ * presence alone is exactly what selected `$HOME`.
  *
  * @param {string} from Absolute directory to start at.
- * @param {string[]} [markers] Filenames or directory names whose presence
- *   marks a workspace root. `existsSync` works for both — a directory name
- *   like `.moon` is detected the same way a filename like `nx.json` is.
+ * @param {string[]} [markers] Filenames or relative paths whose presence
+ *   marks a workspace root. `existsSync` works for all of them — a relative
+ *   path like `.moon/workspace.yml` is detected the same way a filename like
+ *   `nx.json` is.
+ * @param {{gitTopLevel?: (from: string) => string|null}} [io] The git seam:
+ *   how the walk asks for the enclosing repository's top level, injectable
+ *   for the same reason every spawn here is. The default runs
+ *   `git rev-parse --show-toplevel` through `runProcess` — so ambient
+ *   `GIT_DIR`-style redirects are stripped, the boundary describing the tree
+ *   at `from` rather than whatever repository a hook exported — and answers
+ *   `null` when git cannot (no repository encloses `from`, or git is absent).
+ *   `null` is a missing boundary, never a refusal: the walk then climbs
+ *   unbounded, exactly as it did before the boundary existed.
  * @returns {string|null} Absolute path, or `null` when no ancestor has one.
  */
-export function findWorkspaceRoot(from, markers = [NX_CONFIG_FILE]) {
+export function findWorkspaceRoot(
+  from,
+  markers = [NX_CONFIG_FILE],
+  { gitTopLevel = gitTopLevelOf } = {},
+) {
+  const ceiling = gitTopLevel(resolve(from));
   let current = resolve(from);
   for (;;) {
     if (markers.some((marker) => existsSync(join(current, marker)))) return current;
+    // Inclusive on purpose: the marker check above already ran for the top
+    // level itself, so reaching the ceiling with no marker means no ancestor
+    // within the repository is a workspace root — and every ancestor beyond
+    // it is outside the tree `git ls-files` would answer for.
+    if (ceiling !== null && sameDirectory(current, ceiling)) return null;
     const parent = dirname(current);
     if (parent === current) return null;
     current = parent;
   }
 }
 
+/**
+ * The top level of the git repository enclosing `from` — the ceiling
+ * `findWorkspaceRoot` above stops its walk at.
+ *
+ * `null` when none does or when git cannot answer (absent binary, bare
+ * repository, unreadable `.git`): a boundary that cannot be measured is a
+ * boundary absent, and the walk degrades to its previous unbounded climb
+ * rather than refusing a root it never looked at. A repository git genuinely
+ * cannot read is caught loudly one call later by `listTrackedFiles`, whose
+ * own spawn has no `null` answer.
+ */
+function gitTopLevelOf(from) {
+  try {
+    // `stderr: "ignore"` because a directory no repository encloses is the
+    // COMMON case this probe must answer quietly — git's `fatal: not a git
+    // repository` belongs nowhere near a user's terminal for it.
+    return runProcess("git", ["rev-parse", "--show-toplevel"], from, undefined, {
+      stderr: "ignore",
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Do `a` and `b` name the same directory? `git rev-parse --show-toplevel`
+ * answers a fully resolved path while the walk holds the spelling it was
+ * given — on macOS every `os.tmpdir()` path starts `/var/folders/…`, whose
+ * real spelling is `/private/var/folders/…`, and a plain `===` would let the
+ * ceiling silently never bind there. Doubt answers false: a boundary that
+ * fails to bind is the old walk, while one that binds wrongly refuses a real
+ * workspace.
+ */
+const sameDirectory = (a, b) => {
+  if (a === b) return true;
+  try {
+    return realpathSync(a) === realpathSync(b);
+  } catch {
+    return false;
+  }
+};
+
 /**
  * Every tracked file in the workspace, workspace-relative.
  *
@@ -536,26 +617,34 @@ export function analyzeWorkspace(workspace, files, { analyze = analyzeFile } = {
   return { imports, failures, analyzed: analyzedFiles.length, analyzedFiles };
 }
 
-/** The three polyglot manifests `polyglotManifests` looks for. */
-const POLYGLOT_MANIFEST_NAMES = ["go.mod", "Cargo.toml", "pyproject.toml"];
+/** The polyglot manifests `polyglotManifests` looks for. */
+const POLYGLOT_MANIFEST_NAMES = [
+  "go.mod",
+  "Cargo.toml",
+  "pyproject.toml",
+  "pom.xml",
+  "settings.gradle",
+  "settings.gradle.kts",
+  "*.csproj",
+];
 
 /**
- * Tracked Go, Rust and Python manifests that sit under some project's root —
- * the fact the unregistered-Nx-plugin gap turns on
+ * Tracked Go, Rust, Python, Maven and .NET manifests that sit under some project's
+ * root — the fact the unregistered-Nx-plugin gap turns on
  * (`./commands/context.mjs`'s `pluginGap.manifests` is where a caller reads
  * it, and `./options.mjs`'s `pluginIsRegistered` is the other half of that
- * gap). A workspace running under Nx draws no edge for any of these three
- * languages unless this plugin is registered in `nx.json` — Nx parses only
- * TypeScript and JavaScript imports natively (`../../../AGENTS.md`, "for the
- * other three both go quiet") — so a tracked manifest with no registered
- * plugin is exactly the silent hole that invariant refuses. This function
- * only names the manifests; it does not decide whether the plugin is
- * registered. The pair the gap turns on is wired in twice today:
- * `resolveCommandContext` reads both into its `pluginGap`, which every
- * descriptive command refuses on, while `check` renders the same fact as a
- * `coverageGaps` degraded-coverage note rather than a refusal
- * (`../cli.mjs`) — the checker's own analysis covers what the graph does
- * not, so a note is the right level there.
+ * gap). A workspace running under Nx draws no edge for any of these languages
+ * unless this plugin is registered in `nx.json` — Nx parses only TypeScript
+ * and JavaScript imports natively (`../../../AGENTS.md`, "for the other
+ * three both go quiet") — so a tracked manifest with no registered plugin is
+ * exactly the silent hole that invariant refuses. This function only names
+ * the manifests; it does not decide whether the plugin is registered. The
+ * pair the gap turns on is wired in twice today: `resolveCommandContext`
+ * reads both into its `pluginGap`, which every descriptive command refuses
+ * on, while `check` renders the same fact as a `coverageGaps`
+ * degraded-coverage note rather than a refusal (`../cli.mjs`) — the checker's
+ * own analysis covers what the graph does not, so a note is the right level
+ * there.
  *
  * Root matching mirrors `projectOwning`'s longest-prefix attribution of a
  * source file: a project rooted at the workspace root (`root: ""` or `"."`)
@@ -572,7 +661,10 @@ export function polyglotManifests(tracked, projects) {
   const roots = projects.map((project) => project.root);
   return tracked.filter((file) => {
     const base = file.slice(file.lastIndexOf("/") + 1);
-    if (!POLYGLOT_MANIFEST_NAMES.includes(base)) return false;
+    // Literal-first: four of the five names answer by equality, and only
+    // `*.csproj` reaches the glob — this filter runs once per tracked file
+    // (`./analysis/manifest-util.mjs`'s `basenameMatches` owns why).
+    if (!basenameMatches(base, POLYGLOT_MANIFEST_NAMES, posix.matchesGlob)) return false;
     return roots.some(
       (root) => root === "" || root === "." || file === root || file.startsWith(`${root}/`),
     );