@ecoma-io/archkeep 0.13.0

package/src/lsp/boundary-config.mjs

@@ -0,0 +1,225 @@
+/**
+ * The workspace's boundary law, read by a process that outlives edits to it.
+ *
+ * `../config.mjs` already loads and validates that file, and this module reuses
+ * its pure validators (`policyKeyViolations`, `policyFrom`) rather than
+ * restating what a well-formed policy looks like — one answer to "is this
+ * table well-formed", shared by every dialect and every face. What it does NOT
+ * reuse is `loadBoundaryConfig`/`loadBoundaryConfigFile` themselves, and for
+ * the `.mjs`/`.js` dialect the reason is one line of ESM semantics: `import()`
+ * memoises a module URL for the life of the process. A CLI run imports the
+ * config once and exits, so memoisation is invisible there. A language server
+ * runs for hours across edits to that very file, and a second `import()` of
+ * the same URL would hand back the constraint table as it was when the editor
+ * opened — the editor would then re-diagnose every file against a config that
+ * no longer exists, which is precisely the failure re-diagnosing on a config
+ * change is meant to prevent.
+ *
+ * So the `.mjs`/`.js` URL carries a revision the caller controls. The `.json`
+ * dialect needs no such trick — `readFile` reads whatever is on disk at the
+ * moment it is called, with no module cache in the way — so `revision` is
+ * accepted for both dialects (one entry point, one signature) but only spent
+ * on the one that needs it. The inline form spends it least of all: it arrives
+ * as an object `./server.mjs` already re-read from `archkeep.json`, so there is
+ * no read here to make stale.
+ *
+ * A THIRD dialect exists — `../config.mjs`'s ESLint flat-config reader
+ * (`../eslint-config.mjs`), which the CLI and Nx-plugin faces both read
+ * (`docs/concepts/policies.md`) — and this server does not read it yet. That
+ * reader resolves the workspace's own installed `@nx/eslint-plugin` and has
+ * no notion of a revisioned `import()` to defeat this process's module cache
+ * across edits; wiring both mechanisms together belongs to the milestone that
+ * actually adds live ESLint-dialect support to the editor, not to this one.
+ * Until then, an `eslint.config.*` or legacy `.eslintrc*` `boundaryConfig` is
+ * refused BY NAME below — on basename, before the extension dispatch ever
+ * runs — rather than reaching `readModulePolicy`'s bare `import()` and
+ * failing on an unrelated "not a module object" a reader could not connect
+ * back to "this is an ESLint config".
+ */
+import { existsSync } from "node:fs";
+import { readFile as readFileFromDisk } from "node:fs/promises";
+import { basename, extname, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { containmentViolation } from "../containment.mjs";
+import {
+  ESLINT_FLAT_CONFIG_BASENAME,
+  LEGACY_ESLINTRC_BASENAME,
+  policyFrom,
+  policyKeyViolations,
+} from "../config.mjs";
+import { ARCHKEEP_MODEL_FILE } from "../providers/native/model.mjs";
+
+/**
+ * Loads and validates the `.mjs`/`.js` dialect through a revisioned `import()`
+ * — see this module's header for why the revision exists.
+ *
+ * The top-level exports carry the same key law `../config.mjs`'s
+ * `loadModulePolicy` applies: an export beyond the four this loader reads is
+ * refused by name, through the same `policyKeyViolations` the `.json` arm and
+ * the CLI both use — a config the CLI refuses must not load clean in the editor
+ * and re-paint every open file against a typo'd, no-op law.
+ *
+ * @param {string} path Absolute path of the config file.
+ * @param {string|number} revision Busts the ESM module cache across edits.
+ * @returns {Promise<{ depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[] }>}
+ * @throws {Error} when the file is missing, unloadable, or malformed.
+ */
+async function readModulePolicy(path, revision) {
+  const url = `${pathToFileURL(path).href}?revision=${encodeURIComponent(String(revision))}`;
+  let module;
+  try {
+    module = await import(url);
+  } catch (cause) {
+    throw new Error(`archkeep: cannot load ${path}: ${cause?.message ?? cause}`, { cause });
+  }
+  return policyFrom(module, path, policyKeyViolations(module, { allowSchema: false }));
+}
+
+/**
+ * Loads and validates the `.json` dialect: plain `JSON.parse`, never JSONC —
+ * `../config.mjs`'s `loadJsonPolicy` documents why, and this is the same
+ * check, reached through the same two exported validators rather than a
+ * second copy of either.
+ *
+ * @param {string} path Absolute path of the config file.
+ * @param {(path: string, encoding: "utf8") => Promise<string>} readFile
+ *   Injected so a test can drive this without a real file — see
+ *   `readBoundaryConfig` below.
+ * @returns {Promise<{ depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[] }>}
+ * @throws {Error} when the file is missing, unreadable, not valid JSON, or
+ *   malformed — either by `../config.mjs`'s `findBoundaryConfigViolations` or
+ *   by carrying a top-level key none of those rules knows about.
+ */
+async function readJsonPolicy(path, readFile) {
+  let text;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (cause) {
+    throw new Error(`archkeep: cannot load ${path}: ${cause?.message ?? cause}`, { cause });
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (cause) {
+    throw new Error(`archkeep: cannot load ${path}: ${cause?.message ?? cause}`, { cause });
+  }
+  return policyFrom(parsed, path, policyKeyViolations(parsed, { allowSchema: true }));
+}
+
+/**
+ * Loads and validates the boundary config at `workspaceRoot`.
+ *
+ * Basename is tested FIRST, exactly the same two patterns and the same order
+ * `../config.mjs`'s `loadBoundaryConfigFile` uses, and for the identical
+ * reason: both an `eslint.config.*` name and a legacy `.eslintrc*` name are
+ * `.mjs`/`.js`-extensioned (or extensionless) often enough that reaching the
+ * extension dispatch first would either half-work or fail on a message that
+ * never mentions ESLint. Only once neither basename matches does the
+ * extension decide between `.mjs`/`.js` (`readModulePolicy`) and `.json`
+ * (`readJsonPolicy`); anything else is refused by name, in a message that
+ * does not contain the words "cannot load" — a `boundaryConfig` misspelt to a
+ * `.yaml` or `.toml` extension is a naming mistake, not a missing or
+ * unreadable file, and the two must read as different problems. This server
+ * used to only ever recognise the `.mjs`/`.js` spelling — a `.json`
+ * `boundaryConfig` reached `readModulePolicy`'s bare `import()`, which Node
+ * refuses for JSON with `ERR_IMPORT_ATTRIBUTE_MISSING`, a message that names
+ * an import-attributes problem rather than the missing dialect support that
+ * was the real cause.
+ *
+ * The ESLint dialect itself is refused rather than read — see this module's
+ * header for why this server does not (yet) reuse `../eslint-config.mjs`.
+ *
+ * @param {string} workspaceRoot Absolute path of the tree being judged — never
+ *   derived from this file's own location, for the reason `../config.mjs`
+ *   states: pointed at a consumer's tree, the tool's own directory and the
+ *   workspace's root are in different trees.
+ * @param {string|number} revision Anything that changes when the file should be
+ *   re-read. Spent only by the `.mjs`/`.js` arm — see this module's header.
+ * @param {string|object} boundaryConfig The config's filename in this
+ *   workspace, resolved from the plugin's options by the server that owns the
+ *   session — or, on a native root that carries its law on `archkeep.json`
+ *   itself, that inline policy object, validated and returned with no file
+ *   read at all (the first branch of the body says why none is needed).
+ * @param {{readFile?: (path: string, encoding: "utf8") => Promise<string>}} [io]
+ *   Injectable read, used only by the `.json` dialect, defaulting to
+ *   `node:fs/promises`'s `readFile`.
+ * @returns {Promise<{depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[]}>}
+ *   `suppressions` is `[]` when the config declares none; `fitness` and
+ *   `customRules` are present only when the policy declares them, the same
+ *   absent-is-a-decision shape `../config.mjs`'s `policyFrom` returns to
+ *   every other face. This server READS both and evaluates neither — a
+ *   fitness function and a custom rule are per-run workspace judgments, not
+ *   per-file diagnostics — so what it owes them is to load them and to fail
+ *   loudly on a row it cannot read.
+ * @throws {Error} when `boundaryConfig` names the ESLint flat-config dialect
+ *   or a legacy `.eslintrc*` file (this reader does not read either yet — see
+ *   above), or — for a dialect it does read — when the file is missing,
+ *   unloadable, or malformed, or names an extension neither dialect reads, or
+ *   — for the inline form — when the policy object is malformed. The same
+ *   contract `loadBoundaryConfigFile` has, for the same reason: an enforcer
+ *   that starts with no rules enforces nothing and says nothing.
+ */
+export async function readBoundaryConfig(
+  workspaceRoot,
+  revision,
+  boundaryConfig,
+  { readFile = readFileFromDisk } = {},
+) {
+  // An inline policy is DATA, not a path, so every mechanic below it is moot:
+  // there is no name to resolve, nothing to contain, no dialect to dispatch on,
+  // and no module cache for `revision` to defeat. `./server.mjs`'s
+  // `readWorkspaceOptions` has already re-read this object out of
+  // `archkeep.json` for the current revision, and that file is watched
+  // unconditionally by `watchedFilesFor`, so an edit to the law arrives here as
+  // a different object rather than as a file this function would have to
+  // re-read.
+  //
+  // It is still validated rather than trusted. `../providers/native/model.mjs`
+  // checked it at load, which makes this the second pass over a table small
+  // enough to review by eye — cheap, and the alternative is a face that
+  // enforces whatever its caller hands it. `allowSchema` matches the `.json`
+  // arm below because the inline form accepts `$schema` for the same
+  // editor-validation reason a policy file does.
+  if (typeof boundaryConfig !== "string") {
+    return policyFrom(
+      boundaryConfig,
+      `the inline policy on ${ARCHKEEP_MODEL_FILE}'s boundaryConfig at ${workspaceRoot}`,
+      policyKeyViolations(boundaryConfig, { allowSchema: true }),
+    );
+  }
+  const path = `${workspaceRoot.replace(/\/$/, "")}/${boundaryConfig}`;
+  // Resolved ONCE, and the IDENTICAL string feeds the containment check and
+  // the read below. The law name is tree-derived (`nx.json`/`archkeep.json`
+  // options), so a tracked symlink in an intermediate component of it would
+  // hand outside constraint rows in as the workspace's law — the same read
+  // escape `../config.mjs`'s `loadBoundaryConfig` now refuses; this is that
+  // check held on the language-server face. Resolving first is the
+  // resolve-first contract `../containment.mjs`'s `containsDotDot` refusal
+  // exists for: a `..` in the raw name would be normalised away for the check
+  // while the read still followed it (`../containment.mjs`, read-side G-10).
+  const resolved = resolve(path);
+  if (existsSync(workspaceRoot)) {
+    const violation = containmentViolation(workspaceRoot, resolved);
+    if (violation !== null) {
+      throw new Error(`archkeep: cannot load ${path}: ${violation}`);
+    }
+  }
+  const name = basename(resolved);
+  if (ESLINT_FLAT_CONFIG_BASENAME.test(name) || LEGACY_ESLINTRC_BASENAME.test(name)) {
+    throw new Error(
+      `archkeep: ${path} names an ESLint config (${name}) as boundaryConfig — the language ` +
+        "server reads only the .mjs/.js and .json policy-file dialects for now, not ESLint's " +
+        "flat-config dialect the CLI and Nx-plugin faces also read " +
+        "(../../../../docs/reference/policy-schema.md). Point boundaryConfig at an .mjs, .js, or .json " +
+        "boundary-law file to use it from the editor.",
+    );
+  }
+  const extension = extname(resolved);
+  if (extension === ".mjs" || extension === ".js") return readModulePolicy(resolved, revision);
+  if (extension === ".json") return readJsonPolicy(resolved, readFile);
+  throw new Error(
+    `archkeep: ${path} names an unsupported boundaryConfig extension '${extension || "(none)"}' — ` +
+      `expected .mjs, .js, or .json`,
+  );
+}

package/src/lsp/diagnose.mjs

@@ -0,0 +1,202 @@
+/**
+ * One document in, the diagnostics an editor should show for it out.
+ *
+ * ## The single invariant this module exists to hold
+ *
+ * **An empty diagnostic list must mean "no violation", and nothing else.**
+ *
+ * An editor draws no marker for a file whose diagnostics are `[]`, and a
+ * developer reads no marker as "checked, clean". So every way this pipeline can
+ * fail to reach a verdict has to end in a diagnostic instead of in an empty
+ * list: a config that will not load, a workspace index that cannot be built, a
+ * language whose analyzer does not exist yet, an analyzer that threw, a rule
+ * engine that threw, a parse failure the analyzer recorded as data.
+ *
+ * The return type is what makes that checkable rather than merely intended.
+ * `analyzed` is `true` on exactly ONE path — the one where the analyzer
+ * returned, the rule engine returned, AND the tree they were compared against
+ * was read whole — and the caller is expected to refuse to publish an empty
+ * list unless it is `true`. Two guards for one invariant is deliberate: this
+ * module makes the promise, and `./server.mjs` verifies it before the bytes
+ * leave the process.
+ *
+ * ## The third way to reach a wrong verdict, which is not a failure at all
+ *
+ * The two guards above watch a pipeline that ran. They cannot see a pipeline
+ * that ran correctly over the wrong tree: a `project.json` the index could not
+ * read takes its project out of the graph, an import into it then resolves as
+ * an external package, the rule engine's npm branch returns before any tag
+ * check runs, and every function on the path returns normally with nothing to
+ * report. `analyzed: true` would be an honest answer from a pipeline handed bad
+ * input, and it would publish `[]` over a real violation. So the input is
+ * checked too: `indexGaps` reports what the index could not read, and while it
+ * reports anything this module does not call a document analyzed.
+ *
+ * ## The one empty-and-clean case, stated so it is not mistaken for a hole
+ *
+ * A file whose extension no analyzer claims — `README.md`, `project.json`, an
+ * `.svg` — returns `analyzed: true` with no diagnostics. That is the analysis
+ * contract's own answer ("an unknown extension is a no-op, not an error"), and
+ * it is a real verdict: a file with no imports this tool can see crosses no
+ * boundary. The same is true of a file inside no project, which the rule engine
+ * places outside the boundary system entirely.
+ */
+import { analyzeFile } from "../analysis/analyze.mjs";
+import { projectOwning } from "../analysis/source-util.mjs";
+import { declaredEdgeViolationsForCheck } from "../commands/edge-constraints.mjs";
+import { evaluate } from "../rules/index.mjs";
+
+import {
+  analysisFailedDiagnostic,
+  documentLines,
+  failureDiagnostic,
+  incompleteIndexDiagnostic,
+  violationDiagnostic,
+} from "./diagnostics.mjs";
+import { indexGaps } from "./workspace-index.mjs";
+
+/**
+ * The diagnostics for one document, and whether a verdict was actually reached.
+ *
+ * @param {object} request
+ * @param {string} request.sourceFile Workspace-relative path of the document.
+ * @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
+ *   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
+ *   verdict.
+ * @param {{depConstraints: object[], options: object}} request.config
+ * @returns {{analyzed: boolean, diagnostics: object[]}} `analyzed: false`
+ *   always comes with at least one diagnostic.
+ */
+export function diagnoseDocument({ sourceFile, text, index, config }) {
+  const lines = documentLines(text);
+
+  // What the tree was missing when it was indexed. First in the list and first
+  // in the function, because it qualifies every other line the document gets:
+  // the rules below ran, and they ran against this.
+  const gaps = indexGaps(index);
+  const prelude = gaps.length === 0 ? [] : [incompleteIndexDiagnostic(gaps, lines)];
+  const wholeTree = gaps.length === 0;
+
+  let analysis;
+  try {
+    analysis = analyzeFile({ sourceFile, text, workspace: index.workspace });
+  } catch (cause) {
+    // The dispatcher throws for a language its extension table claims and no
+    // analyzer implements. That is the scaffold staying loud, and it must stay
+    // loud here too rather than becoming a green file.
+    return {
+      analyzed: false,
+      diagnostics: [...prelude, analysisFailedDiagnostic(reasonOf(cause), lines)],
+    };
+  }
+
+  // Recorded failures come next, and they are published whether or not the
+  // rule pass below succeeds: they are the part of the file that was NOT
+  // judged, and a reader needs that before they read what was.
+  const diagnostics = [
+    ...prelude,
+    ...analysis.failures.map((failure) => failureDiagnostic(failure, lines)),
+  ];
+
+  // The engine derives its evidence index from exactly the records it is
+  // handed (`../rules/index.mjs`'s `createContext`), so this run is handed
+  // more than one document's worth: the whole tree's retained disk sites
+  // (`./workspace-index.mjs` keeps them on the index for this) MINUS this
+  // document's own — its stale disk copy, which the live buffer below replaces
+  // — plus the fresh records for the buffer text. Evidence rules then cite the
+  // same backing files `lattice check` cites: without the retained sites,
+  // `noImportsOfLazyLoadedLibraries`' file list and `noCircularDependencies`'
+  // per-hop lists came out empty in the editor whenever the backing import
+  // lived in a file nobody had open, while `check` printed them — two faces of
+  // one analysis disagreeing about the same tree.
+  const combinedSites = [
+    ...(index.importSites ?? []).filter((site) => site.sourceFile !== sourceFile),
+    ...analysis.imports,
+  ];
+  // Computed once, before the run: a violation about a file that is neither
+  // this document nor one of the files handed to the engine means the engine
+  // and this caller disagree about which tree they are discussing (guarded
+  // below). No caching beyond what the declared-edge fold further down already
+  // does: `evaluate()` already ran once per diagnosis, and the added cost of
+  // this change is exactly the larger array it now receives.
+  const handedFiles = new Set(combinedSites.map((site) => site.sourceFile));
+
+  let violations;
+  try {
+    violations = evaluate(combinedSites, index.graph, config);
+  } catch (cause) {
+    diagnostics.push(analysisFailedDiagnostic(reasonOf(cause), lines));
+    return { analyzed: false, diagnostics };
+  }
+
+  for (const violation of violations) {
+    if (violation.sourceFile === sourceFile) {
+      diagnostics.push(violationDiagnostic(violation, lines));
+      continue;
+    }
+    // A violation about another HANDED file belongs to that file's own
+    // diagnosis and is dropped here — the engine judged every site it was
+    // given, so foreign-file verdicts are expected output now. One naming a
+    // file that was NOT handed over is different: no site produced it, so
+    // engine and caller are discussing different trees, and the verdict for
+    // this file cannot be trusted.
+    if (!handedFiles.has(violation.sourceFile)) {
+      diagnostics.push(
+        analysisFailedDiagnostic(
+          `the rule engine returned a violation for '${violation.sourceFile}' while judging ` +
+            `'${sourceFile}'; the verdict for this file cannot be trusted`,
+          lines,
+        ),
+      );
+      return { analyzed: false, diagnostics };
+    }
+  }
+
+  // The edges `evaluate()` structurally cannot reach. An `implicit` edge — an
+  // Nx/`archkeep.json` `implicitDependencies` declaration — has no import site
+  // behind it, so it never becomes an `importSites` record for the rule engine
+  // to iterate. The CLI judges exactly those edges itself
+  // (`../commands/edge-constraints.mjs`'s `declaredEdgeViolationsForCheck`,
+  // `cli.mjs check`), and without the same fold here the editor would paint a
+  // file clean while `check` exits 1 over the same declared edge — the
+  // boundary rule that never runs, dressed as a clean tree. Only the violations
+  // whose SOURCE project owns this document are reported: a declared edge names
+  // a project, not a file, and the whole-file range below is the project-level
+  // finding this file is the stand-in for.
+  const sourceOwner = projectOwning(index.workspace?.projects ?? [], sourceFile)?.name;
+  if (sourceOwner !== undefined) {
+    // `declaredEdgeViolationsForCheck` rebuilds reachability and walks every
+    // dependency list — an O(V+E) cost that would otherwise be paid on every
+    // `didChange` keystroke of every open document. The index is revision-keyed
+    // (a fresh object per rebuilt index), so a WeakMap on index identity is a
+    // cache that is correct by construction — same index, same graph — and the
+    // constraint table rides the same revision (`config` is rebuilt alongside
+    // the index), so the pair `(index, depConstraints)` is stable until the
+    // tree moves, then cold again.
+    let entry = declaredEdgeViolationCache.get(index);
+    if (entry === undefined || entry.depConstraints !== config.depConstraints) {
+      entry = {
+        depConstraints: config.depConstraints,
+        violations: declaredEdgeViolationsForCheck(index.graph, config.depConstraints),
+      };
+      declaredEdgeViolationCache.set(index, entry);
+    }
+    for (const violation of entry.violations) {
+      if (violation.source !== sourceOwner) continue;
+      diagnostics.push(violationDiagnostic({ ...violation, line: null, column: null }, lines));
+    }
+  }
+
+  return { analyzed: wholeTree, diagnostics };
+}
+
+/** One `declaredEdgeViolationsForCheck` computation per `(index, depConstraints)` pair. */
+const declaredEdgeViolationCache = new WeakMap();
+
+/** An Error's message, or whatever was thrown, as text a reader can act on. */
+const reasonOf = (cause) => cause?.message ?? String(cause);

package/src/lsp/diagnostics.mjs

@@ -0,0 +1,241 @@
+/**
+ * Analysis records and rule verdicts, rendered as LSP `Diagnostic` objects.
+ *
+ * ## The coordinate conversion is the whole reason this module exists
+ *
+ * The analysis contract is **1-based** in both axes, because that is what a
+ * `file:line:column` terminal report wants (`../analysis/contract.md`). The
+ * Language Server Protocol is **0-based** in both axes. One subtraction stands
+ * between the two, and getting it wrong does not fail loudly: every diagnostic
+ * still appears, one line above or below the import it is about, and every
+ * developer who follows it edits the wrong line. So the conversion lives in one
+ * exported function with its own tests rather than inline at three call sites.
+ *
+ * The column axis needs no re-encoding to go with the subtraction. The contract
+ * counts UTF-16 code units from the start of the line (`../analysis/source-util.mjs`),
+ * and `positionEncoding` defaults to `utf-16` in the protocol, so the two axes
+ * already measure the same unit. A server that negotiated `utf-8` positions
+ * would have to re-encode here; this one advertises none, which leaves the
+ * default in force.
+ *
+ * ## Two kinds of diagnostic, and why the difference is visible in `code`
+ *
+ * A **violation** carries the upstream `messageId` as its `code`, which is what
+ * lets a reader match this server's verdict against the one
+ * `@nx/enforce-module-boundaries` gives for the same import.
+ *
+ * A **failure** — a file that could not be parsed, read, or resolved — carries
+ * `ANALYSIS_FAILURE_CODE`, deliberately not one of `MESSAGE_IDS`. The
+ * distinction is the point: a consumer must be able to tell "a rule found
+ * something" from "no rule could look", and a shared code would collapse them.
+ */
+import { MESSAGE_IDS } from "../rules/messages.mjs";
+
+import { DIAGNOSTIC_SEVERITY, SERVER_INFO } from "./protocol.mjs";
+
+/**
+ * The `source` field on every diagnostic this server publishes — what an editor
+ * prints beside the message to say which tool spoke. Taken from the server's
+ * own identity so the two can never disagree.
+ */
+export const DIAGNOSTIC_SOURCE = SERVER_INFO.name;
+
+/**
+ * The `code` on a diagnostic that reports the ABSENCE of a verdict rather than
+ * a verdict. Named to be impossible to mistake for a rule id, and asserted
+ * against `MESSAGE_IDS` at load so a future upstream id cannot silently collide
+ * with it.
+ */
+export const ANALYSIS_FAILURE_CODE = "analysisFailure";
+
+if (MESSAGE_IDS.includes(ANALYSIS_FAILURE_CODE)) {
+  throw new Error(
+    `archkeep: '${ANALYSIS_FAILURE_CODE}' is now an upstream messageId, so a ` +
+      `diagnostic reporting a failed analysis is indistinguishable from a rule verdict. ` +
+      `Rename the failure code.`,
+  );
+}
+
+/**
+ * A document's lines, as the position axes count them.
+ *
+ * Split on `\n` alone: the contract puts a `\r` at the END of the preceding
+ * line and never at the start of the next one, so a CRLF file reports the same
+ * columns as an LF one. Splitting on both would shift every column on every
+ * line of a CRLF file by nothing and every line index by one — the same
+ * off-by-one this module exists to prevent, arriving through the back door.
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function documentLines(text) {
+  return text.split("\n");
+}
+
+const clamp = (value, low, high) => Math.max(low, Math.min(value, high));
+
+/** Quote characters a specifier can be written between, in any language here. */
+const QUOTES = new Set(['"', "'", "`"]);
+
+/**
+ * The LSP range covering the import at a 1-based `(line, column)`.
+ *
+ * Three things happen here, and each is a decision:
+ *
+ * 1. **The subtraction.** 1-based in, 0-based out, both axes.
+ * 2. **The width comes from the document, not from the record.** The analyzers
+ *    point at the start of the written specifier — which for TypeScript and Go
+ *    is the OPENING QUOTE and for Rust and Python is the first character of the
+ *    path itself. Reading the character actually at the start settles which,
+ *    instead of this module carrying a per-language table that would have to be
+ *    updated with every new analyzer.
+ * 3. **Everything is clamped to the line.** A record can outrun its line
+ *    legitimately: Rust collapses a `use` path wrapped across several lines
+ *    into one specifier. A range past the end of a line is out of spec, and
+ *    clients differ on whether they drop such a diagnostic or clip it — a
+ *    dropped diagnostic is silence, which this server may not produce.
+ *
+ * @param {{line: number|null, column: number|null, specifier?: string}} at
+ * @param {string[]} lines From `documentLines`.
+ * @returns {{start: {line: number, character: number}, end: {line: number, character: number}}}
+ */
+export function rangeAt(at, lines) {
+  // A failure about the file as a whole carries no position (`contract.md`
+  // fixes it as an explicit `null`). It gets the first line, whole: a
+  // zero-width range at the origin renders as an invisible caret in most
+  // editors, and an invisible report of "this file was not checked" is the one
+  // outcome this server is written to avoid.
+  if (at.line === null || at.line === undefined) {
+    return {
+      start: { line: 0, character: 0 },
+      end: { line: 0, character: lines[0]?.length ?? 0 },
+    };
+  }
+
+  const line = clamp(at.line - 1, 0, Math.max(lines.length - 1, 0));
+  const text = lines[line] ?? "";
+  const startCharacter = clamp((at.column ?? 1) - 1, 0, text.length);
+  const specifier = at.specifier ?? "";
+  const quoted = QUOTES.has(text[startCharacter]);
+  const width = quoted ? specifier.length + 2 : specifier.length;
+  const endCharacter = clamp(startCharacter + width, startCharacter, text.length);
+
+  return {
+    start: { line, character: startCharacter },
+    end: { line, character: endCharacter },
+  };
+}
+
+/**
+ * One boundary violation as a diagnostic.
+ *
+ * Severity is `error`, matching what `@nx/enforce-module-boundaries` reports
+ * for the same import in this workspace's ESLint config. A boundary violation
+ * downgraded to a warning here would make the same import red in a JS file and
+ * yellow in a Go one, for no reason a reader could discover.
+ *
+ * @param {object} violation A `Violation` from `../rules/`.
+ * @param {string[]} lines
+ * @returns {object} LSP `Diagnostic`.
+ */
+export function violationDiagnostic(violation, lines) {
+  return {
+    range: rangeAt(violation, lines),
+    severity: DIAGNOSTIC_SEVERITY.error,
+    code: violation.messageId,
+    source: DIAGNOSTIC_SOURCE,
+    message: violation.message,
+  };
+}
+
+/**
+ * One analysis failure as a diagnostic.
+ *
+ * Severity is `warning` rather than `error`, and the reason is what the two
+ * words mean to a reader: an error says "this import is wrong", a warning here
+ * says "this file's imports were not all judged". Neither is silence, which is
+ * the only property that must hold. The message says so in words, because a
+ * severity alone does not tell a developer that the verdict is missing.
+ *
+ * @param {object} failure An `AnalysisFailure` from `../analysis/`.
+ * @param {string[]} lines
+ * @returns {object} LSP `Diagnostic`.
+ */
+export function failureDiagnostic(failure, lines) {
+  return {
+    range: rangeAt(failure, lines),
+    severity: DIAGNOSTIC_SEVERITY.warning,
+    code: ANALYSIS_FAILURE_CODE,
+    source: DIAGNOSTIC_SOURCE,
+    message:
+      `Module boundaries were not fully checked here: ${failure.reason}. ` +
+      `Imports this server could not read are not covered by the verdict below.`,
+  };
+}
+
+/**
+ * How many gaps one diagnostic names before it counts the rest.
+ *
+ * A message is read or it is skipped, and a list of forty paths is skipped. Five
+ * is enough to start on and short enough to finish; the count that follows says
+ * the rest are there.
+ */
+const NAMED_GAP_LIMIT = 5;
+
+/**
+ * A diagnostic for a verdict computed against an INCOMPLETE project graph.
+ *
+ * Different from `analysisFailedDiagnostic` in exactly the way that matters to
+ * a reader: a rule pass did run over this document and what it found is below.
+ * What is missing is part of the tree it was compared against, so the verdict
+ * can be short a violation it had no way to see. Severity is `warning` for the
+ * same reason `failureDiagnostic` is — "not all judged", not "this is wrong".
+ *
+ * One diagnostic carries every gap. One per gap would scale the marker count
+ * with the breakage, and a developer who has just broken one `project.json`
+ * would meet a wall of identical warnings on a file that has nothing to do
+ * with it.
+ *
+ * @param {string[]} gaps From `./workspace-index.mjs`' `indexGaps`.
+ * @param {string[]} lines
+ * @returns {object} LSP `Diagnostic`.
+ */
+export function incompleteIndexDiagnostic(gaps, lines) {
+  const named = gaps.slice(0, NAMED_GAP_LIMIT);
+  const remaining = gaps.length - named.length;
+  return {
+    range: rangeAt({ line: null, column: null }, lines),
+    severity: DIAGNOSTIC_SEVERITY.warning,
+    code: ANALYSIS_FAILURE_CODE,
+    source: DIAGNOSTIC_SOURCE,
+    message:
+      `Module boundaries were checked against an INCOMPLETE view of this workspace, so the ` +
+      `verdict for this file can be missing violations it had no way to see: ` +
+      `${named.join("; ")}${remaining > 0 ? `; and ${remaining} more` : ""}. ` +
+      `Fix what is named here and every open file is re-checked against the whole tree.`,
+  };
+}
+
+/**
+ * A diagnostic for a document the server could not analyze AT ALL — the config
+ * would not load, the workspace index could not be built, an analyzer threw.
+ *
+ * This is the diagnostic that makes "no diagnostics" mean "no violations". Its
+ * severity is `error`: the file's boundary verdict is not merely incomplete, it
+ * is absent, and an editor showing nothing would be showing a clean file.
+ *
+ * @param {string} reason
+ * @param {string[]} lines
+ * @returns {object} LSP `Diagnostic`.
+ */
+export function analysisFailedDiagnostic(reason, lines) {
+  return {
+    range: rangeAt({ line: null, column: null }, lines),
+    severity: DIAGNOSTIC_SEVERITY.error,
+    code: ANALYSIS_FAILURE_CODE,
+    source: DIAGNOSTIC_SOURCE,
+    message:
+      `Module boundaries could not be checked for this file: ${reason}. ` +
+      `This is NOT a clean result — no rule ran.`,
+  };
+}