@ecoma-io/archkeep 0.15.0 → 0.16.1

package/README.md

@@ -3,7 +3,7 @@
 **Architecture governance for polyglot repositories** — a deterministic
 authority that keeps the architecture your team declared aligned with the code
 your team keeps changing. Dependency graphs and module boundaries for Go, Rust,
-Python, TypeScript, JavaScript and Vue, with Nx and Moon as first-class
+Python, TypeScript, JavaScript, Vue, Java, Kotlin and C#, with Nx and Moon as first-class
 integrations. Coding agents read the same verdicts, machine-readably, through
 the `arch-*` skills. The system boundary — what Archkeep is and what it is not —
 is owned by [architecture-authority.md](https://github.com/ecoma-io/archkeep/blob/main/docs/doctrine/architecture-authority.md).
@@ -182,7 +182,7 @@ a file it cannot edit ([overview.md](https://github.com/ecoma-io/archkeep/blob/m
 
 ## Support
 
-- **Languages** — Go, Rust, Python, TypeScript and JavaScript, and Vue. Analysis
+- **Languages** — Go, Rust, Python, TypeScript and JavaScript, Vue, Java, Kotlin and C#. Analysis
   from source, never a build: nothing shells out to `go`, `cargo`, `uv` or `tsc`
   ([languages.md](https://github.com/ecoma-io/archkeep/blob/main/docs/reference/languages.md)).
 - **Workspaces** — any repository: Nx registers the plugin in `nx.json` and
@@ -225,7 +225,7 @@ Ten minutes end to end, most of it spent deciding what your tags mean:
 Ten minutes end to end, most of it spent deciding what your tags mean:
 [**Getting started →**](https://github.com/ecoma-io/archkeep/blob/main/docs/getting-started/installation.md). `graph`, `diff`,
 `history`, `trajectory`, `evolution`, `drift`, `impact`, `explain`,
-`context` and the rest of the 21-command surface are in the
+`context` and the rest of the 22-command surface are in the
 [CLI reference](https://github.com/ecoma-io/archkeep/blob/main/docs/reference/cli.md).
 
 ## Documentation map

package/cli.mjs

@@ -124,6 +124,12 @@ import { debtCommand } from "./src/commands/debt.mjs";
 import { explainCommand } from "./src/commands/explain.mjs";
 import { impactCommand } from "./src/commands/impact.mjs";
 import { provenanceCommand } from "./src/commands/provenance-command.mjs";
+import {
+  rulesAddCommand,
+  rulesInfoCommand,
+  rulesListCommand,
+  rulesVerifyCommand,
+} from "./src/commands/rules.mjs";
 import { waiversCommand } from "./src/commands/waivers.mjs";
 import { INTENT_FILE, loadIntent } from "./src/architecture-intent/model.mjs";
 import { isProgramEntry } from "./src/entry-point.mjs";
@@ -1674,8 +1680,8 @@ async function runAdr(options, { cwd, env }) {
   const root = resolveWorkspaceRootForUsage(cwd);
   if (root === null) {
     env.err(
-      `archkeep: adr needs a workspace root — no nx.json, archkeep.json, or .moon marker found ` +
-        `walking up from ${cwd}`,
+      `archkeep: adr needs a workspace root — no nx.json, archkeep.json, or ` +
+        `.moon/workspace.yml marker found walking up from ${cwd}`,
     );
     return EXIT.error;
   }
@@ -1707,6 +1713,72 @@ async function runAdr(options, { cwd, env }) {
   return result.status === "ok" ? EXIT.ok : EXIT.error;
 }
 
+/**
+ * `rules`'s `run`: dispatches to the appropriate subcommand (list/info/verify/add),
+ * drives it, writes the report, and returns the exit code.
+ *
+ * @param {{format: string, output: string|null, catalog: string|null, to: string|null, paths: string[]}} options
+ * @param {{cwd: string, env: {out: Function, err: Function}}} runContext
+ * @returns {Promise<number>}
+ */
+async function runRules(options, { cwd, env }) {
+  if (options.paths.length === 0) {
+    env.err(`archkeep: rules requires a subcommand (list, info, verify, or add)`);
+    return EXIT.usage;
+  }
+
+  const subcommand = options.paths[0];
+  const ruleName = options.paths[1];
+
+  const dispatch = {
+    list: rulesListCommand,
+    info: rulesInfoCommand,
+    verify: rulesVerifyCommand,
+    add: rulesAddCommand,
+  }[subcommand];
+
+  if (!dispatch) {
+    env.err(
+      `archkeep: unknown rules subcommand '${subcommand}' — must be list, info, verify, or add`,
+    );
+    return EXIT.usage;
+  }
+
+  if (subcommand === "info" && !ruleName) {
+    env.err(`archkeep: rules info requires a rule name`);
+    return EXIT.usage;
+  }
+
+  if (subcommand === "add" && !ruleName) {
+    env.err(`archkeep: rules add requires a rule name`);
+    return EXIT.usage;
+  }
+
+  let result;
+  try {
+    const commandOptions = { catalog: options.catalog, to: options.to };
+    result = await dispatch(commandOptions, { cwd, ruleName });
+  } catch (error) {
+    env.err(String(error?.message ?? error));
+    return EXIT.error;
+  }
+
+  const report = options.format === "json" ? result.report.json : result.report.text;
+
+  if (options.output) {
+    const reportText = report.endsWith("\n") ? report : `${report}\n`;
+    if (!writeOutputReport(options.output, reportText, env, cwd, null)) return EXIT.error;
+    env.err(`archkeep: rules ${subcommand} complete → ${options.output}`);
+  } else {
+    env.out(report);
+  }
+
+  // Exit codes: 0 for ok, 1 for findings (verify only), 3 for no-verdict
+  if (result.status === "ok") return EXIT.ok;
+  if (result.status === "findings") return EXIT.violations;
+  return EXIT.error;
+}
+
 /**
  * `history`'s `run`: resolves the command context, optionally captures a
  * snapshot of the current workspace, drives `historyCommand`, writes the
@@ -1909,8 +1981,8 @@ async function runEvolution(options, { cwd, env }) {
   const root = findWorkspaceRoot(cwd, WORKSPACE_MARKERS);
   if (root === null) {
     env.err(
-      `archkeep: evolution needs a workspace root — no nx.json, archkeep.json, or .moon marker found ` +
-        `walking up from ${cwd}`,
+      `archkeep: evolution needs a workspace root — no nx.json, archkeep.json, or ` +
+        `.moon/workspace.yml marker found walking up from ${cwd}`,
     );
     return EXIT.error;
   }
@@ -2991,6 +3063,46 @@ const ADR_FLAG_HELP = Object.freeze([
   }),
 ]);
 
+/**
+ * `rules`'s flags: catalog path, format, output, and target directory for add.
+ * The first positional is the subcommand (list/info/verify/add), the second is
+ * the rule name for info and add.
+ *
+ * @type {readonly FlagHelp[]}
+ */
+const RULES_FLAG_HELP = Object.freeze([
+  Object.freeze({
+    flag: "--catalog",
+    key: "catalog",
+    arg: "<path>",
+    describe: Object.freeze([
+      "Path to the catalog file",
+      "(default: node_modules/@ecoma-io/archkeep-rules/catalog.json)",
+    ]),
+  }),
+  Object.freeze({
+    flag: "--format",
+    key: "format",
+    arg: "text|json",
+    describe: Object.freeze([
+      "Terminal report (default) or the versioned JSON envelope",
+      "docs/reference/json-output.md documents",
+    ]),
+  }),
+  Object.freeze({
+    flag: "--output",
+    key: "output",
+    arg: "<file>",
+    describe: Object.freeze(["Write the report to a file instead of stdout"]),
+  }),
+  Object.freeze({
+    flag: "--to",
+    key: "to",
+    arg: "<dir>",
+    describe: Object.freeze(["Target directory for the .wasm file", "(default: tools/rules/)"]),
+  }),
+]);
+
 /**
  * The command table `usage()` and `runCli` both read from — a command added
  * later is a new entry here, not a new branch in either. `args` is the
@@ -3215,6 +3327,16 @@ const COMMANDS = Object.freeze({
     formats: DESCRIBABLE_FORMATS,
     run: runAdr,
   }),
+  rules: Object.freeze({
+    name: "rules",
+    args: "<list|info|verify|add> [<rule-name>]",
+    summary: "List official rules, show details, verify catalog integrity, or add a rule",
+    flagHelp: RULES_FLAG_HELP,
+    flags: Object.freeze(Object.fromEntries(RULES_FLAG_HELP.map((f) => [f.flag, f.key]))),
+    defaults: Object.freeze({ format: "text", output: null, catalog: null, to: null }),
+    formats: DESCRIBABLE_FORMATS,
+    run: runRules,
+  }),
 });
 
 /**

package/commands.mjs

@@ -47,5 +47,11 @@ 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.15.0",
-  "description": "Architecture enforcement for polyglot repositories — dependency graphs and module boundaries for Go, Rust, Python, TypeScript, JavaScript and Vue",
+  "version": "0.16.1",
+  "description": "Architecture enforcement for polyglot repositories — dependency graphs and module boundaries for Go, Rust, Python, TypeScript, JavaScript, Vue, Java and Kotlin",
   "keywords": [
     "architecture",
     "enforcement",
@@ -53,6 +53,7 @@
   },
   "peerDependencies": {
     "@nx/eslint-plugin": ">=21",
+    "fast-xml-parser": "5.11.0",
     "nx": ">=21",
     "typescript": ">=5 <7",
     "vue": ">=3"
@@ -61,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