@ecoma-io/archkeep 0.18.1 → 0.20.0

package/README.md

@@ -220,12 +220,10 @@ Exit codes: 0 clean — and every selected file was analyzed; 1 findings;
 ([exit-codes.md](https://github.com/ecoma-io/archkeep/blob/main/docs/reference/exit-codes.md) ·
 [ci.md](https://github.com/ecoma-io/archkeep/blob/main/docs/usage/ci.md)).
 
-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`,
 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 23-command surface are in the
+`context` and the rest of the 24-command surface are in the
 [CLI reference](https://github.com/ecoma-io/archkeep/blob/main/docs/reference/cli.md).
 
 ## Documentation map

package/cli.mjs

@@ -115,7 +115,7 @@ import { adrCommand } from "./src/commands/adr.mjs";
 import { decisionsCommand } from "./src/commands/decisions.mjs";
 import { diffCommand } from "./src/commands/diff.mjs";
 import { captureDelta, deltaCommand } from "./src/commands/delta.mjs";
-import { discoverCommand } from "./src/commands/discover.mjs";
+import { discoverCommand, proposalToIntent } from "./src/commands/discover.mjs";
 import { driftCommand } from "./src/commands/drift.mjs";
 import { fitnessCommand } from "./src/commands/fitness.mjs";
 import { reconcileCommand } from "./src/commands/reconcile.mjs";
@@ -129,6 +129,7 @@ import { reportCommand } from "./src/commands/report.mjs";
 import { debtCommand } from "./src/commands/debt.mjs";
 import { explainCommand } from "./src/commands/explain.mjs";
 import { impactCommand } from "./src/commands/impact.mjs";
+import { scenarioCommand } from "./src/commands/scenario.mjs";
 import { provenanceCommand } from "./src/commands/provenance-command.mjs";
 import {
   rulesAddCommand,
@@ -1547,6 +1548,72 @@ async function runImpact(options, { cwd, env }) {
   // Impact is descriptive: 0 when it completes, never 1.
   return EXIT.ok;
 }
+/**
+ * `scenario`'s `run`: resolves the command context, reads the scenario file,
+ * drives `scenarioCommand`, writes the report, and returns the exit code.
+ *
+ * The project name is the single positional argument. `--scenario-file` names
+ * the JSON scenario description. `--config` is accepted, same as `check`,
+ * because the constraint-impact analysis depends on which boundary law is in
+ * effect.
+ *
+ * @param {{format: string, output: string|null, config: string|null, scenarioFile: string|null, paths: string[]}} options
+ * @param {{cwd: string, env: {out: Function, err: Function, readGraph?: Function, listFiles?: Function}}} runContext
+ * @returns {Promise<number>}
+ */
+async function runScenario(options, { cwd, env }) {
+  if (options.paths.length !== 1) {
+    env.err(
+      `archkeep: scenario takes exactly one positional argument (the project name); ` +
+        `got ${options.paths.length}`,
+    );
+    return EXIT.usage;
+  }
+
+  if (!options.scenarioFile) {
+    env.err("archkeep: scenario requires --scenario-file <file>");
+    return EXIT.usage;
+  }
+
+  const projectName = options.paths[0];
+  const scenarioFilePath = resolve(cwd, options.scenarioFile);
+
+  let scenarioJson;
+  try {
+    scenarioJson = readFileSync(scenarioFilePath, "utf-8");
+  } catch (error) {
+    env.err(`archkeep: cannot read scenario file "${options.scenarioFile}": ${error.message}`);
+    return EXIT.usage;
+  }
+
+  let result;
+  try {
+    const commandContext = resolveCommandContext(
+      { cwd },
+      { readGraph: env.readGraph, listFiles: env.listFiles },
+    );
+
+    const { config } = await resolvePolicy(options, commandContext, cwd);
+
+    result = scenarioCommand(projectName, scenarioJson, commandContext, config);
+  } catch (error) {
+    const usageError = error instanceof UsageError;
+    env.err(String(error?.message ?? error));
+    return usageError ? EXIT.usage : EXIT.error;
+  }
+
+  const report = options.format === "json" ? result.report.json : result.report.text;
+
+  if (options.output) {
+    if (!writeOutputReport(options.output, report, env, cwd, options.config)) return EXIT.error;
+    env.err(`archkeep: scenario for "${projectName}" complete → ${options.output}`);
+  } else {
+    env.out(report);
+  }
+
+  // Scenario is descriptive: 0 when it completes, never 1.
+  return EXIT.ok;
+}
 
 /**
  * `explain`'s `run`: resolves the command context, loads the boundary config,
@@ -2212,7 +2279,7 @@ async function runDebt(options, { cwd, env }) {
  * graph. `--propose` is opt-in: a proposal is a suggestion, and a workspace
  * that does not ask for one must not get one.
  *
- * @param {{format: string, output: string|null, propose: boolean, paths: string[]}} options
+ * @param {{format: string, output: string|null, propose: boolean, writeIntent: string|null, paths: string[]}} options
  * @param {{cwd: string, env: {out: Function, err: Function, readGraph?: Function, listFiles?: Function}}} runContext
  * @returns {Promise<number>}
  */
@@ -2222,6 +2289,11 @@ async function runDiscover(options, { cwd, env }) {
     return EXIT.usage;
   }
 
+  if (options.writeIntent && !options.propose) {
+    env.err("archkeep: --write-intent requires --propose");
+    return EXIT.usage;
+  }
+
   let result;
   try {
     const commandContext = resolveCommandContext(
@@ -2257,6 +2329,17 @@ async function runDiscover(options, { cwd, env }) {
     env.out(report);
   }
 
+  if (options.writeIntent) {
+    try {
+      const intentJson = JSON.stringify(proposalToIntent(result.proposal), null, 2) + "\n";
+      writeFileSync(options.writeIntent, intentJson, "utf-8");
+      env.err(`archkeep: proposed architecture written to ${options.writeIntent}`);
+    } catch (error) {
+      env.err(`archkeep: failed to write intent file: ${error.message}`);
+      return EXIT.error;
+    }
+  }
+
   // Discover is descriptive: 0 when it completes, never 1.
   return result.status === "ok" ? EXIT.ok : EXIT.error;
 }
@@ -2709,6 +2792,17 @@ const DISCOVER_FLAG_HELP = Object.freeze([
       "authoritative; nothing is ever written",
     ]),
   }),
+  Object.freeze({
+    flag: "--write-intent",
+    key: "writeIntent",
+    arg: "<file>",
+    describe: Object.freeze([
+      "Write the proposed components and rules to a valid",
+      "architecture-intent.json file. Only valid with --propose;",
+      "the file is a candidate for drift/reconcile and must be",
+      "reviewed before use",
+    ]),
+  }),
   Object.freeze({
     flag: "--format",
     key: "format",
@@ -3108,6 +3202,48 @@ const IMPACT_FLAG_HELP = Object.freeze([
     ]),
   }),
 ]);
+/**
+ * `scenario`'s flags: text or JSON envelope, optional file output, and
+ * `--scenario-file` to specify the scenario input (required). The project
+ * name is positional.
+ *
+ * @type {readonly FlagHelp[]}
+ */
+const SCENARIO_FLAG_HELP = Object.freeze([
+  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: "--config",
+    key: "config",
+    arg: "<file>",
+    describe: Object.freeze([
+      "Read the boundary law from here instead of",
+      "<workspace root>/module-boundaries.config.mjs",
+    ]),
+  }),
+  Object.freeze({
+    flag: "--scenario-file",
+    key: "scenarioFile",
+    arg: "<file>",
+    describe: Object.freeze([
+      "Path to the scenario JSON file describing the",
+      "hypothetical changes to evaluate",
+    ]),
+  }),
+]);
 
 /**
  * `explain`'s flags: text or JSON envelope, optional file output.
@@ -3390,7 +3526,7 @@ const COMMANDS = Object.freeze({
     summary: "Report observed facts, and optionally propose candidate architecture",
     flagHelp: DISCOVER_FLAG_HELP,
     flags: Object.freeze(Object.fromEntries(DISCOVER_FLAG_HELP.map((f) => [f.flag, f.key]))),
-    defaults: Object.freeze({ format: "text", output: null, propose: false }),
+    defaults: Object.freeze({ format: "text", output: null, propose: false, writeIntent: null }),
     formats: DESCRIBABLE_FORMATS,
     booleans: Object.freeze(["propose"]),
     run: runDiscover,
@@ -3513,6 +3649,16 @@ const COMMANDS = Object.freeze({
     formats: DESCRIBABLE_FORMATS,
     run: runImpact,
   }),
+  scenario: Object.freeze({
+    name: "scenario",
+    args: "<project>",
+    summary: "Evaluate a hypothetical change against the current workspace",
+    flagHelp: SCENARIO_FLAG_HELP,
+    flags: Object.freeze(Object.fromEntries(SCENARIO_FLAG_HELP.map((f) => [f.flag, f.key]))),
+    defaults: Object.freeze({ format: "text", output: null, config: null, scenarioFile: null }),
+    formats: DESCRIBABLE_FORMATS,
+    run: runScenario,
+  }),
   explain: Object.freeze({
     name: "explain",
     args: "<file:line:column>",

package/commands.mjs

@@ -54,4 +54,6 @@ export {
   rulesVerifyCommand,
 } from "./src/commands/rules.mjs";
 
+export { parseScenarioInput, scenarioCommand } from "./src/commands/scenario.mjs";
+
 export { UsageError } from "./src/errors.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecoma-io/archkeep",
-  "version": "0.18.1",
+  "version": "0.20.0",
   "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/analysis/kotlin.mjs

@@ -95,6 +95,58 @@ export function parseKotlinImportSites(kotlinText) {
  */
 const importableNameOf = (name) => (name.endsWith(".*") ? name.slice(0, -2) : name);
 
+/**
+ * Kotlin malformation detection: an `import` keyword whose body never reaches
+ * its terminator before a `{` (on the same line) or EOF is a whole-file
+ * failure — without it, a file truncated inside an import would parse as
+ * importing nothing, with no failure record and a clean verdict over the hole
+ * (#419, the same pattern as `javaImportMalformations` adapted for Kotlin's
+ * newline-terminated imports).
+ *
+ * Kotlin imports are terminated by `\n`, `;`, `}`, or EOF — unlike Java where
+ * every import MUST end with `;`. So the scan includes `\n` as a valid
+ * terminator: a `{` is only a malformation when it arrives on the same line
+ * as the import head, before any newline does.
+ *
+ * @param {string} kotlinText Raw file contents.
+ * @returns {string[]} Reasons, at most one per malformation kind.
+ */
+export function kotlinImportMalformations(kotlinText) {
+  const source = maskKotlinComments(kotlinText);
+  const KOTLIN_IMPORT_HEAD = /(?:^\uFEFF?|[\n;])[ \t]*(?:import[ \t]+)/gu;
+  /** @type {string[]} */
+  const reasons = [];
+  // `\n`, `;`, and `{` ascend with the text, so one shared cursor walks all
+  // three in a single pass — the same shape the Java scan uses, but with `\n`
+  // included because Kotlin's import syntax allows newline termination.
+  const terminators = [...source.matchAll(/[\n;{]/g)];
+  let cursor = 0;
+  for (const m of source.matchAll(KOTLIN_IMPORT_HEAD)) {
+    const at = m.index + m[0].length;
+    while (cursor < terminators.length && terminators[cursor].index < at) cursor += 1;
+    const next = terminators[cursor];
+    // A `{` before any `\n` or `;` means the import and a body opener share a
+    // line, which is never valid Kotlin. No terminator at all (EOF) is also a
+    // truncation. A `\n` or `;` is a clean terminator.
+    if (next === undefined) {
+      const importOffset = m.index + m[0].indexOf("import");
+      reasons.push(
+        "an `import` never reaches its terminator — the file is truncated or malformed, " +
+          `so its imports cannot be read (line ${positionAt(kotlinText, importOffset).line})`,
+      );
+      break;
+    }
+    if (next[0] === "{") {
+      const importOffset = m.index + m[0].indexOf("import");
+      reasons.push(
+        "an `import` and a `{` share a line — the file is malformed, " +
+          `so its imports cannot be read (line ${positionAt(kotlinText, importOffset).line})`,
+      );
+      break;
+    }
+  }
+  return reasons;
+}
 /**
  * Analyzes one `.kt`/`.kts` file. Ambiguity resolves to null WITH a
  * positioned failure naming every claimant, exactly as Java's does — the
@@ -113,6 +165,14 @@ export function analyzeKotlin({ sourceFile, text, workspace }) {
   try {
     const { byName: index } = jvmPackageIndex(workspace);
     const owner = projectOwning(workspace.projects, sourceFile);
+    // A file truncated inside an import used to parse as importing nothing,
+    // with no failure beside the empty result — the clean verdict over it was
+    // the bug (#419). The whole-file shape is what turns the verdict loud:
+    // `check` counts the file toward `unchecked` and refuses to call the run
+    // complete, instead of reporting a hole as a clean file.
+    for (const reason of kotlinImportMalformations(text)) {
+      result.failures.push(fileFailure(sourceFile, reason));
+    }
     for (const site of parseKotlinImportSites(text)) {
       const { line, column } = positionAt(text, site.offset);
       const resolved = resolveJvmSpecifier(site.importableName, { language: "kotlin" }, index);

package/src/analysis/python.mjs

@@ -1155,6 +1155,45 @@ export function parsePythonImportSites(pythonText) {
   return sites.sort((a, b) => a.offset - b.offset);
 }
 
+/**
+ * Python malformation detection: an `import` or `from` keyword whose name
+ * never resolves before EOF, on a line that doesn't continue, is a
+ * whole-file failure — without it, a file truncated inside an import
+ * statement would parse as importing nothing, with no failure record and a
+ * clean verdict over the hole (#419).
+ *
+ * @param {string} pythonText Raw file contents.
+ * @returns {string[]} Reasons, at most one per malformation kind.
+ */
+export function pythonImportMalformations(pythonText) {
+  /** @type {string[]} */
+  const reasons = [];
+  // A bare `import` or `from` at the end of the file, or on a line with
+  // nothing after the keyword, is the common truncation pattern.
+  const TRUNCATED_IMPORT = /^[ \t]*(?:import[ \t]*$|from[ \t]*$)/m;
+  if (TRUNCATED_IMPORT.test(pythonText)) {
+    const m = TRUNCATED_IMPORT.exec(pythonText);
+    const lineStart = pythonText.lastIndexOf("\n", m.index) + 1;
+    const lineNumber = pythonText.slice(0, lineStart).split("\n").length;
+    reasons.push(
+      "an `import` or `from` statement is truncated — the file is malformed, " +
+        `so its imports cannot be read (line ${lineNumber})`,
+    );
+  }
+  // Also detect a `from ... import` that ends without naming what to import.
+  const TRUNCATED_FROM_IMPORT = /^[ \t]*from[ \t]+[\w.]+[ \t]+import[ \t]*$/m;
+  if (TRUNCATED_FROM_IMPORT.test(pythonText)) {
+    const m = TRUNCATED_FROM_IMPORT.exec(pythonText);
+    const lineStart = pythonText.lastIndexOf("\n", m.index) + 1;
+    const lineNumber = pythonText.slice(0, lineStart).split("\n").length;
+    reasons.push(
+      "a `from ... import` statement has no imported names — the file is malformed, " +
+        `so its imports cannot be read (line ${lineNumber})`,
+    );
+  }
+  return reasons;
+}
+
 /**
  * Analyzes one `.py` file.
  *
@@ -1170,92 +1209,104 @@ export function analyzePython({ sourceFile, text, workspace }) {
       ? ownPackageOf(sourceFile, owner.root, directoriesOf.get(owner.name) ?? [])
       : null;
 
-    for (const site of parsePythonImportSites(text)) {
-      const { line, column } = positionAt(text, site.offset);
-      const record = {
-        sourceFile,
-        line,
-        column,
-        specifier: site.specifier,
-        kind: site.kind,
-        spelling: { path: false, relative: isRelativeImport(site.specifier), namesOnly: true },
-        resolved: null,
-      };
-      result.imports.push(record);
-      const fail = (reason) => result.failures.push({ sourceFile, line, column, reason });
-
-      if (site.continuation) {
-        fail(
-          `'${site.specifier}' looks like a \`from\`/\`import\` statement continued across a ` +
-            `backslash-joined line, but does not parse as one once its continuation lines are ` +
-            `joined — this reader cannot say what it imports`,
-        );
-        continue;
-      }
-      if (!site.literal) {
-        fail(
-          `dynamic import of '${site.specifier}' has a non-literal argument, ` +
-            `so its target is not knowable statically`,
-        );
-        continue;
-      }
+    // A file truncated inside an `import` or `from` statement used to parse as
+    // importing nothing — the clean verdict over it was the bug (#419). The
+    // whole-file failure is what turns the verdict loud: `check` counts the
+    // file toward `unchecked` and refuses to call the run complete.
+    const malformations = [...pythonImportMalformations(text)];
+    for (const reason of malformations) {
+      result.failures.push(fileFailure(sourceFile, reason));
+    }
+    // When the file is truncated inside an import statement, no imports at all
+    // can be reliably extracted — a whole-file failure is the only honest answer.
+    if (malformations.length === 0) {
+      for (const site of parsePythonImportSites(text)) {
+        const { line, column } = positionAt(text, site.offset);
+        const record = {
+          sourceFile,
+          line,
+          column,
+          specifier: site.specifier,
+          kind: site.kind,
+          spelling: { path: false, relative: isRelativeImport(site.specifier), namesOnly: true },
+          resolved: null,
+        };
+        result.imports.push(record);
+        const fail = (reason) => result.failures.push({ sourceFile, line, column, reason });
 
-      let absolute = site.specifier;
-      if (site.specifier.startsWith(".")) {
-        if (ownPackage === null) {
+        if (site.continuation) {
           fail(
-            `relative import '${site.specifier}' cannot be resolved: '${sourceFile}' is not on any import root`,
+            `'${site.specifier}' looks like a \`from\`/\`import\` statement continued across a ` +
+              `backslash-joined line, but does not parse as one once its continuation lines are ` +
+              `joined — this reader cannot say what it imports`,
           );
           continue;
         }
-        absolute = resolveRelativeModule(site.specifier, ownPackage);
-        if (absolute === null) {
+        if (!site.literal) {
           fail(
-            `relative import '${site.specifier}' climbs past the top-level package of '${sourceFile}', ` +
-              `which leaves the project's import root — Python rejects it the same way`,
+            `dynamic import of '${site.specifier}' has a non-literal argument, ` +
+              `so its target is not knowable statically`,
           );
           continue;
         }
-      }
 
-      const resolution = resolveModuleName(absolute, byModule);
-      if (resolution === null) {
-        // Reaching no project is only evidence of a PyPI package when every
-        // project's packages are where this reader can see them. Otherwise the
-        // honest answer is that the name is unplaceable — asserting `external`
-        // here is what let a first-party import cross a tag boundary silently.
-        if (unmodelled.length > 0) {
+        let absolute = site.specifier;
+        if (site.specifier.startsWith(".")) {
+          if (ownPackage === null) {
+            fail(
+              `relative import '${site.specifier}' cannot be resolved: '${sourceFile}' is not on any import root`,
+            );
+            continue;
+          }
+          absolute = resolveRelativeModule(site.specifier, ownPackage);
+          if (absolute === null) {
+            fail(
+              `relative import '${site.specifier}' climbs past the top-level package of '${sourceFile}', ` +
+                `which leaves the project's import root — Python rejects it the same way`,
+            );
+            continue;
+          }
+        }
+
+        const resolution = resolveModuleName(absolute, byModule);
+        if (resolution === null) {
+          // Reaching no project is only evidence of a PyPI package when every
+          // project's packages are where this reader can see them. Otherwise the
+          // honest answer is that the name is unplaceable — asserting `external`
+          // here is what let a first-party import cross a tag boundary silently.
+          if (unmodelled.length > 0) {
+            fail(
+              `'${site.specifier}' reaches no project, and this reader cannot conclude it is ` +
+                `external — ${unmodelled
+                  .map(
+                    (entry) =>
+                      `project '${entry.project}' may place its packages where this reader ` +
+                      `cannot look: ${entry.reason}`,
+                  )
+                  .join("; ")}. A first-party package put there would look exactly like this.`,
+            );
+            continue;
+          }
+          record.resolved = {
+            target: null,
+            file: null,
+            external: true,
+            packageName: absolute.split(".")[0],
+          };
+        } else if (resolution.ambiguous) {
           fail(
-            `'${site.specifier}' reaches no project, and this reader cannot conclude it is ` +
-              `external — ${unmodelled
-                .map(
-                  (entry) =>
-                    `project '${entry.project}' may place its packages where this reader ` +
-                    `cannot look: ${entry.reason}`,
-                )
-                .join("; ")}. A first-party package put there would look exactly like this.`,
+            `'${site.specifier}' resolves through the namespace package '${resolution.prefix}', which ` +
+              `${resolution.ambiguous.join(" and ")} both contribute to — Python picks by sys.path order, ` +
+              `which no static reader can know`,
           );
-          continue;
+        } else {
+          record.resolved = {
+            target: resolution.owner.project,
+            file: resolution.owner.file,
+            external: false,
+            packageName: null,
+          };
         }
-        record.resolved = {
-          target: null,
-          file: null,
-          external: true,
-          packageName: absolute.split(".")[0],
-        };
-      } else if (resolution.ambiguous) {
-        fail(
-          `'${site.specifier}' resolves through the namespace package '${resolution.prefix}', which ` +
-            `${resolution.ambiguous.join(" and ")} both contribute to — Python picks by sys.path order, ` +
-            `which no static reader can know`,
-        );
-      } else {
-        record.resolved = {
-          target: resolution.owner.project,
-          file: resolution.owner.file,
-          external: false,
-          packageName: null,
-        };
       }
     }
   } catch (cause) {

package/src/commands/discover.mjs

@@ -72,6 +72,46 @@ export function buildObserved(commandContext) {
   return { projects, edges };
 }
 
+/**
+ * Convert a discovery proposal into an `architecture-intent.json`-compatible
+ * object. The conversion preserves the proposal's structural intent:
+ *
+ * - **Components** (directory groupings of 2+ projects) → `boundaries` entries
+ *   with `directory:` selectors.
+ * - **`noDependency` rules** → `forbidden` entries — cross-component
+ *   dependencies that should not exist.
+ *
+ * Confidence markers and evidence are dropped: the user is expected to review
+ * the output before using it with `drift` or `reconcile`.
+ *
+ * @param {object} proposal The proposal from `evaluateDiscovery`.
+ * @returns {{version: string, boundaries: Array<{name: string, match: string[]}>, forbidden?: Array<{source: string, target: string}>}}
+ */
+export function proposalToIntent(proposal) {
+  const boundaries = (proposal.components?.items ?? []).map((component) => ({
+    name: component.name,
+    match: [`directory:${component.commonDirectory}`],
+  }));
+
+  // `noDependency` rules map to `forbidden` intent rows. The rules array
+  // includes both `noDependency` and `boundary` kinds; only the former
+  // carries source/target project pairs.
+  const forbidden = (proposal.rules?.items ?? [])
+    .filter((rule) => rule.kind === "noDependency")
+    .map((rule) => ({
+      source: rule.source,
+      target: rule.target,
+    }));
+
+  return {
+    version: "1",
+    // Auto-generated header comment is not possible in strict JSON; the
+    // user is expected to review before using with drift/reconcile.
+    boundaries,
+    ...(forbidden.length > 0 ? { forbidden } : {}),
+  };
+}
+
 /**
  * Runs the `discover` command: observes the workspace, optionally proposes the
  * candidate architecture over it, and returns the report.