@ecoma-io/archkeep 0.18.0 → 0.18.1

package/cli.mjs

@@ -93,6 +93,11 @@
  */
 import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+/*** @type {{name: string, version: string}} */
+const { name: TOOL_NAME, version: TOOL_VERSION } = require("./package.json");
 
 import { containmentViolation } from "./src/containment.mjs";
 import { UsageError } from "./src/errors.mjs";
@@ -2541,9 +2546,10 @@ const DELTA_FLAG_HELP = Object.freeze([
     key: "capture",
     arg: "",
     describe: Object.freeze([
-      "Write an evidence snapshot of the current tree",
+      "Print an evidence snapshot of the current tree",
       "(raw import records, graph, coverage, policy",
-      "fingerprint) for a later delta run to compare against",
+      "fingerprint) for a later delta run to compare against.",
+      "Without --output, the snapshot goes to stdout.",
     ]),
   }),
   Object.freeze({
@@ -3621,10 +3627,15 @@ export async function runCli(argv, env) {
   // one root-marker read and a clean run pays none.
   const help = () => usage(optionsForUsage(cwd));
 
+  // --help and --version are universal flags, handled before command dispatch.
   if (argv[0] === "--help" || argv[0] === "-h") {
     env.out(help());
     return EXIT.ok;
   }
+  if (argv[0] === "--version" || argv[0] === "-v") {
+    env.out(`${TOOL_NAME} ${TOOL_VERSION}`);
+    return EXIT.ok;
+  }
 
   const [maybeCommand, ...maybeRest] = argv;
   let commandName;
@@ -3635,6 +3646,11 @@ export async function runCli(argv, env) {
   } else if (Object.hasOwn(COMMANDS, maybeCommand)) {
     commandName = maybeCommand;
     rest = maybeRest;
+    // Subcommand --help: show the main help without "unknown option" error.
+    if (rest.includes("--help") || rest.includes("-h")) {
+      env.out(help());
+      return EXIT.ok;
+    }
   } else if (
     maybeCommand !== "" &&
     existsSync(isAbsolute(maybeCommand) ? maybeCommand : join(cwd, maybeCommand))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecoma-io/archkeep",
-  "version": "0.18.0",
+  "version": "0.18.1",
   "description": "Architecture enforcement for polyglot repositories — dependency graphs and module boundaries for Go, Rust, Python, TypeScript, JavaScript, Vue, Java and Kotlin",
   "keywords": [
     "architecture",

package/src/commands/diff.mjs

@@ -114,6 +114,21 @@ export function parseBaseline(text, path) {
     );
   }
 
+  if (!envelope.command) {
+    throw new Error(
+      `archkeep: the baseline snapshot at '${path}' has no 'command' field — it is not a ` +
+        `'graph' envelope. diff requires a graph snapshot (from 'graph --format json'). ` +
+        `For delta evidence snapshots use 'delta <snapshot>'.`,
+    );
+  }
+
+  if (envelope.command !== "graph") {
+    throw new Error(
+      `archkeep: the baseline snapshot at '${path}' is a '${envelope.command}' envelope, not a ` +
+        `'graph' envelope — diff requires a graph snapshot as its baseline`,
+    );
+  }
+
   // A consumer that reads a schemaVersion it does not recognise should refuse
   // to parse the rest (`docs/reference/json-output.md`). This tool IS that
   // consumer when reading a baseline — a future schema version could change
@@ -127,13 +142,6 @@ export function parseBaseline(text, path) {
     );
   }
 
-  if (envelope.command !== "graph") {
-    throw new Error(
-      `archkeep: the baseline snapshot at '${path}' is a '${envelope.command}' envelope, not a ` +
-        `'graph' envelope — diff requires a graph snapshot as its baseline`,
-    );
-  }
-
   if (!envelope.coverage?.complete) {
     throw new Error(
       `archkeep: the baseline snapshot at '${path}' has incomplete coverage — every "removed" ` +

package/src/commands/explain.mjs

@@ -97,6 +97,7 @@ import {
   resolveDecisionRef,
   stripAdrPrefix,
 } from "../governance/adr-registry.mjs";
+import { isAbsolute, relative, resolve, sep } from "node:path";
 
 /**
  * Parses a `file:line:column` site string into its components.
@@ -354,6 +355,16 @@ export function explainCommand(site, commandContext, config, options = {}) {
 
   const parsed = parseSite(site);
 
+  // Normalize the site's sourceFile to a workspace-relative path so it
+  // matches the analysis record's sourceFile field (contract.md: workspace-relative).
+  // Handles: absolute paths, cwd-relative paths, and backslash separators.
+  const rawFile = parsed.sourceFile;
+  const normalizedFile = isAbsolute(rawFile)
+    ? relative(root, rawFile)
+    : relative(root, resolve(root, rawFile));
+  // Normalize backslash separators (Windows paths) to forward slashes.
+  parsed.sourceFile = sep === "\\" ? normalizedFile.replaceAll("\\", "/") : normalizedFile;
+
   const notAnalyzed = commandContext.analysis.failures
     .filter(isWholeFileFailure)
     .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));

package/src/commands/rules.mjs

@@ -84,7 +84,9 @@ function loadCatalog(catalogPath, cwd) {
 
   if (!existsSync(resolvedPath)) {
     throw new Error(
-      `catalog not found at ${catalogPath} — install @ecoma-io/archkeep-rules or use --catalog to point to a catalog.json file`,
+      `catalog not found at ${catalogPath} — install @ecoma-io/archkeep-rules ` +
+        `(\`npm install -D @ecoma-io/archkeep-rules\`) or use --catalog to point to a ` +
+        `catalog.json file`,
     );
   }