@ecoma-io/archkeep 0.14.0 → 0.16.0

package/commands.mjs

@@ -0,0 +1,57 @@
+/**
+ * The command layer's public face — what an integration imports from this
+ * package's `./commands` subpath to run the same commands `cli.mjs` runs,
+ * in-process, without spawning the CLI or parsing its text output.
+ *
+ * It holds no logic on purpose, the same bargain `./nx` (`nx.mjs`) makes: a
+ * named entry that is a re-export, so the command layer can grow under
+ * `src/commands/` without a second copy of any decision appearing beside it.
+ * `cli.mjs` and this file are two faces of one layer — the CLI owns argv,
+ * output destinations and exit codes; an importer of this face owns those for
+ * itself, and gets back exactly what the command functions return: statuses,
+ * payloads and reports, never a printed byte.
+ *
+ * Who this is for: integrations that compose the CLI's verbs programmatically
+ * — `packages/archkeep-mcp`, the agent capability interface, is the first. The
+ * engine primitives (discovery and judgment) remain the root entry
+ * (`index.mjs`); a caller that wants to JUDGE import records itself composes
+ * those, while a caller that wants the CLI's answers — a verdict, an impact
+ * set, an explanation — composes these. The two entries never overlap: a
+ * function exported here is never also exported there, so no integration can
+ * accidentally hold two spellings of one decision.
+ *
+ * The roster is exactly what the first consumer composes, no more — a
+ * function joins it when an integration calls it, never in anticipation of
+ * one. What is deliberately absent: the `run*` drivers and argv parsing
+ * (`cli.mjs` alone owns what a process's stdout and exit code mean), and the
+ * renderers (`src/report/` shapes bytes for humans; an importer reads the
+ * envelopes the commands already return).
+ *
+ * The seams the CLI threads are threaded the same way here: `readGraph` and
+ * `listFiles` are injectable on every entry point that reaches outside the
+ * process, so a caller drives the real analysis, rules and reports over a
+ * fixture tree with neither Nx nor git present.
+ */
+
+export { resolveCommandContext, WORKSPACE_MARKERS } from "./src/commands/context.mjs";
+
+export { resolveDescribedPolicy, resolvePolicy } from "./src/commands/policy.mjs";
+
+export { check } from "./src/commands/check.mjs";
+export { graphCommand } from "./src/commands/graph.mjs";
+export { impactCommand } from "./src/commands/impact.mjs";
+export { explainCommand } from "./src/commands/explain.mjs";
+export { driftCommand } from "./src/commands/drift.mjs";
+export { planContextCommand } from "./src/commands/plan-context-command.mjs";
+export { historyCommand } from "./src/commands/history.mjs";
+export { adrCommand } from "./src/commands/adr.mjs";
+export { discoverCommand } from "./src/commands/discover.mjs";
+export { reconcileCommand } from "./src/commands/reconcile.mjs";
+export {
+  rulesAddCommand,
+  rulesInfoCommand,
+  rulesListCommand,
+  rulesVerifyCommand,
+} from "./src/commands/rules.mjs";
+
+export { UsageError } from "./src/errors.mjs";

package/lsp.mjs

@@ -68,11 +68,24 @@ export function serve(input = process.stdin, output = process.stdout, onExit = n
       return;
     }
     pending = framed.rest;
-    for (const message of framed.messages) server.handle(message);
+    for (const message of framed.messages) {
+      // `handle` is async and owns its own error envelope — a rejection here
+      // is a wiring defect, not a diagnostic. The catch reports it on stderr
+      // (the channel a client surfaces as its server log) instead of letting
+      // it become an unhandled rejection that kills the connection, or
+      // nothing at all, which would read as a clean frame.
+      server
+        .handle(message)
+        .catch((error) => process.stderr.write(`archkeep-lsp: ${error?.message ?? error}\n`));
+    }
   });
   // A client that closed the pipe without saying `exit` did not shut the server
   // down; reporting that as a clean stop would hide a crashed editor.
-  input.on("end", () => server.handle({ jsonrpc: "2.0", method: "exit" }));
+  input.on("end", () => {
+    server
+      .handle({ jsonrpc: "2.0", method: "exit" })
+      .catch((error) => process.stderr.write(`archkeep-lsp: ${error?.message ?? error}\n`));
+  });
   return server;
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ecoma-io/archkeep",
-  "version": "0.14.0",
-  "description": "Architecture enforcement for polyglot repositories — dependency graphs and module boundaries for Go, Rust, Python, TypeScript, JavaScript and Vue",
+  "version": "0.16.0",
+  "description": "Architecture enforcement for polyglot repositories — dependency graphs and module boundaries for Go, Rust, Python, TypeScript, JavaScript, Vue, Java and Kotlin",
   "keywords": [
     "architecture",
     "enforcement",
@@ -28,12 +28,14 @@
   "exports": {
     ".": "./index.mjs",
     "./nx": "./nx.mjs",
+    "./commands": "./commands.mjs",
     "./presets/*.json": "./presets/*.json",
     "./package.json": "./package.json"
   },
   "files": [
     "index.mjs",
     "nx.mjs",
+    "commands.mjs",
     "cli.mjs",
     "lsp.mjs",
     "src/",
@@ -51,6 +53,7 @@
   },
   "peerDependencies": {
     "@nx/eslint-plugin": ">=21",
+    "fast-xml-parser": "5.11.0",
     "nx": ">=21",
     "typescript": ">=5 <7",
     "vue": ">=3"
@@ -59,6 +62,9 @@
     "@nx/eslint-plugin": {
       "optional": true
     },
+    "fast-xml-parser": {
+      "optional": true
+    },
     "nx": {
       "optional": true
     },

package/src/analysis/analyze.mjs

@@ -22,7 +22,10 @@
  * exists. Every other import site keeps naming them from this module.
  */
 
+import { analyzeCSharp } from "./csharp.mjs";
 import { analyzeGo } from "./go.mjs";
+import { analyzeJava } from "./java.mjs";
+import { analyzeKotlin } from "./kotlin.mjs";
 import { analyzePython } from "./python.mjs";
 import { LANGUAGE_BY_EXTENSION, languageOf } from "./registry.mjs";
 import { analyzeRust } from "./rust.mjs";
@@ -78,6 +81,15 @@ export { LANGUAGE_BY_EXTENSION, languageOf };
  *   `./x` and `../x` in JavaScript, `crate::`/`self::`/`super::` and a sibling
  *   crate target of the same Cargo package in Rust, a leading-dot import in
  *   Python. It is the counter-evidence `noSelfCircularDependencies` looks for.
+ * @property {boolean} namesOnly The language's ONLY import spelling is a
+ *   name — a Go module path, a Rust crate, a Python dotted module, a C#
+ *   namespace, a Java or Kotlin package — so no specifier it produces is ever
+ *   a filesystem path, and text beginning `libs/…` or `apps/…` is a name whose
+ *   first segments are those words, not a path into a project. Constant on
+ *   every record one analyzer produces, unlike `path` and `relative`, which
+ *   answer per specifier. `isAbsoluteImportIntoAnotherProject` is gated on it
+ *   (#376): false in the JavaScript family, where a bare `libs/x` is a deep
+ *   import and a `/libs/x` an absolute path.
  */
 
 /**
@@ -170,6 +182,9 @@ const ANALYZER_BY_LANGUAGE = Object.freeze({
   go: analyzeGo,
   rust: analyzeRust,
   python: analyzePython,
+  java: analyzeJava,
+  kotlin: analyzeKotlin,
+  csharp: analyzeCSharp,
 });
 
 /**

package/src/analysis/contract.md

@@ -71,23 +71,40 @@ beats every consumer remembering which convention this tool chose.
 ### How the specifier is spelled is a per-language fact, so the analyzer states it
 
 `specifier` is the raw text; `spelling` is what that text IS in the language it
-was written in. Two bits, because the rules ask two independent questions:
-
-|                                   | `path` | `relative` |
-| --------------------------------- | :----: | :--------: |
-| `./x`, `../x`, `.`, `..` (JS)     |  yes   |    yes     |
-| `/x` (JS)                         |  yes   |     no     |
-| `crate::x`, `self::x`, `super::x` |   no   |    yes     |
-| `rba_desktop_lib::run` from a bin |   no   |    yes     |
-| `.mod`, `..pkg.sub` (Python)      |   no   |    yes     |
-| `react`, `serde`, `example.com/m` |   no   |     no     |
+was written in. Three bits, because the rules ask three independent questions —
+the first two per specifier, the third per language and therefore constant on
+every record one analyzer produces:
+
+|                                   | `path` | `relative` | `namesOnly` |
+| --------------------------------- | :----: | :--------: | :---------: |
+| `./x`, `../x`, `.`, `..` (JS)     |  yes   |    yes     |     no      |
+| `/x` (JS)                         |  yes   |     no     |     no      |
+| `react` (JS, bare)                |   no   |     no     |     no      |
+| `crate::x`, `self::x`, `super::x` |   no   |    yes     |     yes     |
+| `rba_desktop_lib::run` from a bin |   no   |    yes     |     yes     |
+| `.mod`, `..pkg.sub` (Python)      |   no   |    yes     |     yes     |
+| `react`, `serde`, `example.com/m` |   no   |     no     |    yes*     |
+
+\* the last row holds for `serde` and `example.com/m`; a JavaScript `react` is
+`namesOnly: no` — the same text is a package name in one language and a name
+that IS the only spelling in another, which is exactly why the bit rides on the
+record instead of being derived from the text.
 
 `path` says the specifier is a **filesystem path**: resolvable by path
 arithmetic against the importing file, and naming no package. It decides
 whether a specifier may receive a synthesized external node, and which message
 an unresolvable one gets. `relative` says the specifier **reaches inside its
 own project without going out through the project's public name** — the
-counter-evidence `noSelfCircularDependencies` looks for.
+counter-evidence `noSelfCircularDependencies` looks for. `namesOnly` says the
+**language has no path spelling at all** — every specifier it produces is a
+name, so no path-text rule applies to any of them. It gates
+`isAbsoluteImportIntoAnotherProject`, which judges the JavaScript-family
+spellings a bare `libs/x` deep import and a `/libs/x` absolute path: applied to
+a language whose only spelling is the name, it read a Go `module libs/foo`'s
+legal `import "libs/foo/bar"` as an absolute path into a project — an
+unfixable verdict, because the name is the only spelling the language has
+(#376). The edge such an import resolves to is still judged by every rule
+below the spelling check; only the spelling check itself stands down.
 
 **Why the analyzer answers and not the rules.** The rules layer used to derive
 both from the text with one predicate — `.`, `..`, `./`, `../` — which is
@@ -101,10 +118,10 @@ import; the rules layer knows neither, and a language table there would be a
 second registry drifting from `LANGUAGE_BY_EXTENSION`. So the record carries the
 fact and the rule reads it.
 
-The field is **mandatory**, and `evaluate()` throws on a record that omits it
-rather than falling back to the JavaScript shape. A default is how the next
-analyzer inherits this bug silently; a throw is how it is told, once, at the
-first record it produces.
+The field is **mandatory**, and `evaluate()` throws on a record that omits any
+bit of it rather than falling back to the JavaScript shape. A default is how
+the next analyzer inherits this bug silently; a throw is how it is told, once,
+at the first record it produces.
 
 ### Intra-project imports are emitted too
 
@@ -208,9 +225,10 @@ rule cares about, and the pressure to fix it would be an ignore list that
 someone has to keep in sync with reality. An extension with no analyzer simply
 has no imports this tool can see, which is the truth.
 
-The registry is `LANGUAGE_BY_EXTENSION` in `analyze.mjs`, and it is the one
-place an extension is mapped. A language whose analyzer arrives adds itself
-there and nowhere else.
+The registry is `LANGUAGE_BY_EXTENSION` in `registry.mjs` (re-exported by
+`analyze.mjs`, so nothing that imports it from there has to change), and it is
+the one place an extension is mapped. A language whose analyzer arrives adds
+itself there and nowhere else.
 
 ## What an analyzer is handed