@intentius/chant 0.13.0 → 0.15.0

package/src/cli/commands/audit.ts

@@ -8,7 +8,7 @@
 import { existsSync, statSync, writeFileSync } from "fs";
 import { auditFiles, type AuditInput, type AuditFinding, type ChecksProvider } from "../../audit/core";
 import { discoverByDetection, classifyFiles, loadAuditPlugins, AUDIT_LEXICONS } from "../../audit/discover";
-import { RULE_CATALOG } from "../../audit/catalog";
+import { RULE_CATALOG, resolveAuditCatalog, type RuleMeta } from "../../audit/catalog";
 import { renderMarkdown } from "../../audit/report";
 import { renderHtml, type ReportTheme } from "../../audit/report-html";
 import { buildReportJson, type AuditSnapshot } from "../../audit/report-model";
@@ -88,12 +88,12 @@ function githubToken(env: NodeJS.ProcessEnv = process.env): string | undefined {
   return env.GITHUB_TOKEN ?? env.CHANT_AUDIT_GITHUB_TOKEN;
 }
 
-function isMergeWorthy(f: AuditFinding): boolean {
-  return RULE_CATALOG[f.checkId]?.tier === "merge-worthy";
+function isMergeWorthy(f: AuditFinding, catalog: Record<string, RuleMeta> = RULE_CATALOG): boolean {
+  return catalog[f.checkId]?.tier === "merge-worthy";
 }
 
-function exitCodeFor(findings: AuditFinding[], failOn: AuditFailOn): number {
-  if (failOn === "merge-worthy") return findings.some(isMergeWorthy) ? 1 : 0;
+function exitCodeFor(findings: AuditFinding[], failOn: AuditFailOn, catalog: Record<string, RuleMeta> = RULE_CATALOG): number {
+  if (failOn === "merge-worthy") return findings.some((f) => isMergeWorthy(f, catalog)) ? 1 : 0;
   if (failOn === "warning") {
     return findings.some((f) => f.severity === "error" || f.severity === "warning") ? 1 : 0;
   }
@@ -116,12 +116,12 @@ export function coverageNotes(inputs: AuditInput[]): string[] {
   return notes;
 }
 
-function renderStylish(findings: AuditFinding[], scanned: string[], notes: string[]): string {
+function renderStylish(findings: AuditFinding[], scanned: string[], notes: string[], catalog: Record<string, RuleMeta> = RULE_CATALOG): string {
   const lines: string[] = [];
   for (const note of notes) lines.push(`Note: ${note}`);
   if (notes.length > 0) lines.push("");
-  const mw = findings.filter(isMergeWorthy);
-  const ro = findings.filter((f) => !isMergeWorthy(f));
+  const mw = findings.filter((f) => isMergeWorthy(f, catalog));
+  const ro = findings.filter((f) => !isMergeWorthy(f, catalog));
   lines.push(
     `Audited ${scanned.length} file${scanned.length === 1 ? "" : "s"} — ` +
       `${findings.length} finding${findings.length === 1 ? "" : "s"} ` +
@@ -132,7 +132,7 @@ function renderStylish(findings: AuditFinding[], scanned: string[], notes: strin
     lines.push("", title);
     for (const f of list) {
       const where = f.entity ? `${f.file} (${f.entity})` : f.file;
-      const title = RULE_CATALOG[f.checkId]?.title ?? f.checkId;
+      const title = catalog[f.checkId]?.title ?? f.checkId;
       lines.push(`  [${f.checkId}] ${f.severity}  ${where}  — ${title}`);
     }
   };
@@ -141,10 +141,10 @@ function renderStylish(findings: AuditFinding[], scanned: string[], notes: strin
   return lines.join("\n");
 }
 
-function renderSarif(findings: AuditFinding[]): string {
+function renderSarif(findings: AuditFinding[], catalog: Record<string, RuleMeta> = RULE_CATALOG): string {
   const ruleIds = [...new Set(findings.map((f) => f.checkId))].sort();
   const rules = ruleIds.map((id) => {
-    const m = RULE_CATALOG[id];
+    const m = catalog[id];
     return {
       id,
       name: m?.title ?? id,
@@ -255,7 +255,12 @@ export async function auditCommand(options: AuditCommandOptions): Promise<AuditC
     const msg = err instanceof Error ? err.message : String(err);
     return { success: false, output: "", findings: [], scanned, exitCode: 1, error: msg };
   }
-  if (tier === "merge-worthy") findings = findings.filter(isMergeWorthy);
+  // Resolve the audit catalog once, aggregating the audited lexicons' own
+  // metadata over core's static catalog (#687). The lexicons are already loaded
+  // by `auditFiles` above, so this is cheap.
+  const catalog = await resolveAuditCatalog([...new Set(inputs.map((i) => i.lexicon))]);
+
+  if (tier === "merge-worthy") findings = findings.filter((f) => isMergeWorthy(f, catalog));
   const notes = coverageNotes(inputs);
 
   // Diff-bearing renderers (markdown, html) need action SHAs / image digests
@@ -299,25 +304,25 @@ export async function auditCommand(options: AuditCommandOptions): Promise<AuditC
   switch (format) {
     case "json": {
       const snapshot = await buildSnapshot(options, scanned, isUrl);
-      output = JSON.stringify(buildReportJson(findings, { snapshot, toolVersion: options.toolVersion }), null, 2);
+      output = JSON.stringify(buildReportJson(findings, { snapshot, toolVersion: options.toolVersion, catalog }), null, 2);
       break;
     }
     case "sarif":
-      output = renderSarif(findings);
+      output = renderSarif(findings, catalog);
       break;
     case "markdown":
-      output = renderMarkdown(findings, { target: options.path, files, resolveSha, resolveDigest, notes });
+      output = renderMarkdown(findings, { target: options.path, files, resolveSha, resolveDigest, notes, catalog });
       break;
     case "html": {
       const snapshot = await buildSnapshot(options, scanned, isUrl);
-      output = renderHtml(findings, { files, resolveSha, resolveDigest, notes, snapshot, theme: options.theme, template: options.template });
+      output = renderHtml(findings, { files, resolveSha, resolveDigest, notes, snapshot, theme: options.theme, template: options.template, catalog });
       break;
     }
     default:
-      output = renderStylish(findings, scanned, notes);
+      output = renderStylish(findings, scanned, notes, catalog);
   }
 
-  const exitCode = exitCodeFor(findings, failOn);
+  const exitCode = exitCodeFor(findings, failOn, catalog);
   if (options.output) {
     try {
       writeFileSync(options.output, output);

package/src/cli/commands/component-lint.test.ts

@@ -0,0 +1,158 @@
+/**
+ * `chant lint` end-to-end integration for the COMP* composition checks
+ * (#562, epic #551) — confirms `lintCommand` itself (not just
+ * `runComponentChecks` in isolation, see
+ * ../../lint/rules/comp/comp.test.ts) merges COMP* diagnostics into its
+ * output, gates the build at error severity the same way COR/EVL rules do,
+ * honors config severity overrides (including "off"), and honors the
+ * file-level `chant-disable` directive form.
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { lintCommand, type LintOptions } from "./lint";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+const COMPONENT_MODULE_SPECIFIER = JSON.stringify(
+  new URL("../../components/component.ts", import.meta.url).pathname,
+);
+
+function componentSource(body: string): string {
+  return `import type { Component } from ${COMPONENT_MODULE_SPECIFIER};\nimport { phase } from ${COMPONENT_MODULE_SPECIFIER};\n\n${body}\n`;
+}
+
+describe("chant lint: COMP* composition checks (#562)", () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `chant-comp-lint-test-${Date.now()}-${Math.random()}`);
+    await mkdir(testDir, { recursive: true });
+    process.env.NO_COLOR = "1";
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+    delete process.env.NO_COLOR;
+  });
+
+  test("a clean component (no *.component.ts issues) lints with no COMP diagnostics", async () => {
+    await writeFile(
+      join(testDir, "orders-table.component.ts"),
+      componentSource(
+        `export const ordersTable: Component = {\n` +
+          `  name: "orders-table",\n` +
+          `  archetype: "infra",\n` +
+          `  dependsOn: [],\n` +
+          `  deploy: [phase("Apply", [{ kind: "cfn-deploy", template: "archive:orders-table.template.json" }])],\n` +
+          `};\n`,
+      ),
+    );
+
+    const result = await lintCommand({ path: testDir, format: "stylish" } satisfies LintOptions);
+    expect(result.diagnostics.filter((d) => d.ruleId.startsWith("COMP"))).toHaveLength(0);
+  });
+
+  test("a raw shell step with no reason fails the lint at error severity (COMP006), gating the build like a COR* error", async () => {
+    await writeFile(
+      join(testDir, "legacy.component.ts"),
+      componentSource(
+        `export const legacyTool: Component = {\n` +
+          `  name: "legacy-tool",\n` +
+          `  archetype: "infra",\n` +
+          `  dependsOn: [],\n` +
+          `  deploy: [phase("Apply", [{ kind: "shell", cmd: "./deploy.sh" }])],\n` +
+          `};\n`,
+      ),
+    );
+
+    const result = await lintCommand({ path: testDir, format: "stylish" } satisfies LintOptions);
+    expect(result.success).toBe(false);
+    const hit = result.diagnostics.find((d) => d.ruleId === "COMP006");
+    expect(hit).toBeDefined();
+    expect(hit!.severity).toBe("error");
+    expect(result.errorCount).toBeGreaterThan(0);
+  });
+
+  test("a chant-disable COMP006 file-level directive suppresses the diagnostic", async () => {
+    await writeFile(
+      join(testDir, "legacy.component.ts"),
+      `// chant-disable COMP006 -- vendor CLI, tracked in TICKET-123\n` +
+        componentSource(
+          `export const legacyTool: Component = {\n` +
+            `  name: "legacy-tool",\n` +
+            `  archetype: "infra",\n` +
+            `  dependsOn: [],\n` +
+            `  deploy: [phase("Apply", [{ kind: "shell", cmd: "./deploy.sh" }])],\n` +
+            `};\n`,
+        ),
+    );
+
+    const result = await lintCommand({ path: testDir, format: "stylish" } satisfies LintOptions);
+    expect(result.diagnostics.some((d) => d.ruleId === "COMP006")).toBe(false);
+    expect(result.success).toBe(true);
+  });
+
+  test("a bare chant-disable (no rule ids) suppresses every COMP diagnostic for that file", async () => {
+    await writeFile(
+      join(testDir, "legacy.component.ts"),
+      `// chant-disable\n` +
+        componentSource(
+          `export const legacyTool: Component = {\n` +
+            `  name: "legacy-tool",\n` +
+            `  archetype: "infra",\n` +
+            `  dependsOn: [],\n` +
+            `  deploy: [phase("Apply", [{ kind: "shell", cmd: "./deploy.sh" }])],\n` +
+            `};\n`,
+        ),
+    );
+
+    const result = await lintCommand({ path: testDir, format: "stylish" } satisfies LintOptions);
+    expect(result.diagnostics.filter((d) => d.ruleId.startsWith("COMP"))).toHaveLength(0);
+  });
+
+  test("chant.config.ts can turn a COMP rule off entirely", async () => {
+    await writeFile(
+      join(testDir, "legacy.component.ts"),
+      componentSource(
+        `export const legacyTool: Component = {\n` +
+          `  name: "legacy-tool",\n` +
+          `  archetype: "infra",\n` +
+          `  dependsOn: [],\n` +
+          `  deploy: [phase("Apply", [{ kind: "shell", cmd: "./deploy.sh" }])],\n` +
+          `};\n`,
+      ),
+    );
+    await writeFile(
+      join(testDir, "chant.config.json"),
+      JSON.stringify({ rules: { COMP006: "off" } }),
+    );
+
+    const result = await lintCommand({ path: testDir, format: "stylish" } satisfies LintOptions);
+    expect(result.diagnostics.some((d) => d.ruleId === "COMP006")).toBe(false);
+  });
+
+  test("chant.config.ts can downgrade a COMP rule to warning, so it no longer fails the build", async () => {
+    await writeFile(
+      join(testDir, "legacy.component.ts"),
+      componentSource(
+        `export const legacyTool: Component = {\n` +
+          `  name: "legacy-tool",\n` +
+          `  archetype: "infra",\n` +
+          `  dependsOn: [],\n` +
+          `  deploy: [phase("Apply", [{ kind: "shell", cmd: "./deploy.sh" }])],\n` +
+          `};\n`,
+      ),
+    );
+    await writeFile(
+      join(testDir, "chant.config.json"),
+      JSON.stringify({ rules: { COMP006: "warning" } }),
+    );
+
+    const result = await lintCommand({ path: testDir, format: "stylish" } satisfies LintOptions);
+    const hit = result.diagnostics.find((d) => d.ruleId === "COMP006");
+    expect(hit).toBeDefined();
+    expect(hit!.severity).toBe("warning");
+    expect(result.success).toBe(true);
+  });
+});

package/src/cli/commands/doctor.test.ts

@@ -1,8 +1,33 @@
 import { describe, test, expect } from "vitest";
 import { doctorCommand } from "./doctor";
 import { withTestDir } from "@intentius/chant-test-utils";
-import { writeFileSync, mkdirSync } from "fs";
-import { join } from "path";
+import { writeFileSync, mkdirSync, rmSync, existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+/**
+ * Root `node_modules/` — where a bare `@intentius/chant-capability-<name>`
+ * specifier actually resolves from from within this package (dynamic
+ * `import()` in ../../components/capability-plugin-loader.ts resolves
+ * relative to the importing module, not to whatever `testDir` a doctor test
+ * points `doctorCommand` at). Used below to install a throwaway, genuinely
+ * malformed capability package for the duration of one test, then remove it.
+ */
+const repoNodeModules = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "..", "..", "node_modules");
+
+/** Write a minimal CJS/ESM-agnostic package under `@intentius/chant-capability-<name>` in the real node_modules, for exercising the doctor's capability-plugin check end to end. Caller must remove it (see `finally` blocks below). */
+function installFakeCapabilityPackage(name: string, indexSource: string): string {
+  const pkgDir = join(repoNodeModules, "@intentius", `chant-capability-${name}`);
+  mkdirSync(pkgDir, { recursive: true });
+  writeFileSync(join(pkgDir, "package.json"), JSON.stringify({ name: `@intentius/chant-capability-${name}`, version: "1.0.0", type: "module", main: "index.js" }));
+  writeFileSync(join(pkgDir, "index.js"), indexSource);
+  return pkgDir;
+}
+
+function removeFakeCapabilityPackage(name: string): void {
+  const pkgDir = join(repoNodeModules, "@intentius", `chant-capability-${name}`);
+  if (existsSync(pkgDir)) rmSync(pkgDir, { recursive: true, force: true });
+}
 
 describe("doctorCommand", () => {
   test("config-exists fails when no config file present", async () => {
@@ -236,4 +261,93 @@ describe("doctorCommand", () => {
       expect(check!.status).toBe("pass");
     });
   });
+
+  // ── Capability plugin checks (#559, epic #551) ─────────────────────────
+
+  test("capability plugin check fails when the named package cannot be found", async () => {
+    await withTestDir(async (testDir) => {
+      writeFileSync(
+        join(testDir, "chant.config.json"),
+        JSON.stringify({ capabilities: ["nonexistent-capability-package"] }),
+      );
+      const report = await doctorCommand(testDir);
+      const check = report.checks.find((c) => c.name === "capability-nonexistent-capability-package");
+      expect(check).toBeDefined();
+      expect(check!.status).toBe("fail");
+      expect(check!.message).toContain("could not be loaded");
+      expect(report.success).toBe(false);
+    });
+  });
+
+  test("capability plugin check fails for a malformed package (no CapabilityPlugin export)", async () => {
+    installFakeCapabilityPackage("broken", "export const notAPlugin = { oops: true };\n");
+    try {
+      await withTestDir(async (testDir) => {
+        writeFileSync(
+          join(testDir, "chant.config.json"),
+          JSON.stringify({ capabilities: ["broken"] }),
+        );
+        const report = await doctorCommand(testDir);
+        const check = report.checks.find((c) => c.name === "capability-broken");
+        expect(check).toBeDefined();
+        expect(check!.status).toBe("fail");
+        expect(check!.message).toMatch(/could not be loaded|does not export/);
+        expect(report.success).toBe(false);
+      });
+    } finally {
+      removeFakeCapabilityPackage("broken");
+    }
+  });
+
+  test("capability plugin check fails when capabilities() is not a function (malformed shape)", async () => {
+    installFakeCapabilityPackage(
+      "half-broken",
+      "export const plugin = { name: 'half-broken', version: '1.0.0', capabilities: 'not-a-function' };\n",
+    );
+    try {
+      await withTestDir(async (testDir) => {
+        writeFileSync(
+          join(testDir, "chant.config.json"),
+          JSON.stringify({ capabilities: ["half-broken"] }),
+        );
+        const report = await doctorCommand(testDir);
+        const check = report.checks.find((c) => c.name === "capability-half-broken");
+        expect(check).toBeDefined();
+        expect(check!.status).toBe("fail");
+      });
+    } finally {
+      removeFakeCapabilityPackage("half-broken");
+    }
+  });
+
+  test("capability plugin check passes for a well-formed package", async () => {
+    installFakeCapabilityPackage(
+      "good",
+      "export const plugin = { name: 'good', version: '1.0.0', capabilities: () => [{ kind: 'demo-verb', run: async () => ({}) }] };\n",
+    );
+    try {
+      await withTestDir(async (testDir) => {
+        writeFileSync(
+          join(testDir, "chant.config.json"),
+          JSON.stringify({ capabilities: ["good"] }),
+        );
+        const report = await doctorCommand(testDir);
+        const check = report.checks.find((c) => c.name === "capability-good");
+        expect(check).toBeDefined();
+        expect(check!.status).toBe("pass");
+        expect(check!.message).toContain("1 capability(ies) registered");
+      });
+    } finally {
+      removeFakeCapabilityPackage("good");
+    }
+  });
+
+  test("no capability checks are added when config.capabilities is absent", async () => {
+    await withTestDir(async (testDir) => {
+      writeFileSync(join(testDir, "chant.config.json"), "{}");
+      const report = await doctorCommand(testDir);
+      const capabilityChecks = report.checks.filter((c) => c.name.startsWith("capability-"));
+      expect(capabilityChecks.length).toBe(0);
+    });
+  });
 });

package/src/cli/commands/doctor.ts

@@ -5,6 +5,8 @@ import { fileURLToPath } from "url";
 import { checkVersionCompatibility } from "../../lexicon-manifest";
 import { debug } from "../debug";
 import { loadPlugins, resolveProjectLexicons } from "../plugins";
+import { loadCapabilityPlugin } from "../../components/capability-plugin-loader";
+import { isCapabilityPlugin } from "../../components/capability-plugin";
 
 export interface DoctorCheck {
   name: string;
@@ -221,6 +223,50 @@ export async function doctorCommand(path: string): Promise<DoctorReport> {
     debug("skills check failed:", e);
   }
 
+  // Check: Capability plugin packages (#559, epic #551) — each name in
+  // config.capabilities must load and satisfy the CapabilityPlugin contract
+  // (../../components/capability-plugin.ts). A malformed capability package
+  // (missing/broken `capabilities()`, or the package failing to resolve at
+  // all) is reported as a `fail`, mirroring how a missing lexicon type
+  // directory fails above rather than warning.
+  const capabilityNames = config?.capabilities as string[] | undefined;
+  if (capabilityNames && Array.isArray(capabilityNames)) {
+    for (const name of capabilityNames) {
+      try {
+        const plugin = await loadCapabilityPlugin(name);
+        if (!isCapabilityPlugin(plugin)) {
+          checks.push({
+            name: `capability-${name}`,
+            status: "fail",
+            message: `Capability plugin "${name}" does not satisfy the CapabilityPlugin contract (missing name/version/capabilities())`,
+          });
+          continue;
+        }
+        const capabilities = plugin.capabilities();
+        if (!Array.isArray(capabilities)) {
+          checks.push({
+            name: `capability-${name}`,
+            status: "fail",
+            message: `Capability plugin "${name}": capabilities() did not return an array`,
+          });
+          continue;
+        }
+        checks.push({
+          name: `capability-${name}`,
+          status: "pass",
+          message: `${capabilities.length} capability(ies) registered`,
+        });
+      } catch (e) {
+        debug(`capability plugin check failed for ${name}:`, e);
+        checks.push({
+          name: `capability-${name}`,
+          status: "fail",
+          message: `Capability plugin "${name}" could not be loaded: ${e instanceof Error ? e.message : String(e)}`,
+        });
+      }
+    }
+  }
+
   return {
     checks,
     success: checks.every(c => c.status !== "fail"),

package/src/cli/commands/lexicon-rolling-upgrade.ts

@@ -0,0 +1,198 @@
+/**
+ * `chant dev rolling-upgrade <lexicon-dir>` command implementation.
+ *
+ * Detects rolling-spec drift for the aws, azure, and github lexicons. These
+ * lexicons pin no version constant — "latest" is fetched on every regen. This
+ * command regenerates from current-latest, diffs the produced API surface
+ * against the committed baseline (surface.snapshot.json), and REPORTS the
+ * result. It is a dry run: it never opens a PR, updates a branch, or writes the
+ * baseline. PR automation and scheduling live in #527.
+ *
+ * The PR label an eventual automation would apply is derived from severity:
+ *   additive → `minor`, breaking → `major`. This command only prints it.
+ */
+
+import { existsSync } from "fs";
+import { resolve } from "path";
+import {
+  checkRollingUpgrade,
+  type RollingUpgradeResult,
+} from "../../codegen/rolling-upgrade";
+
+// ── Types ─────────────────────────────────────────────────────────────
+
+export interface RollingUpgradeCliOptions {
+  /** Resolved path to the lexicon directory. */
+  lexiconDir: string;
+  /** Force re-fetch of the upstream spec (bypass cache). */
+  force?: boolean;
+  /** Print subprocess output while running. */
+  verbose?: boolean;
+}
+
+// ── Main entry ────────────────────────────────────────────────────────
+
+/**
+ * Run the rolling-upgrade check and return the result.
+ * Returns a synthetic failed result when the directory is missing.
+ */
+export async function runRollingUpgrade(
+  opts: RollingUpgradeCliOptions,
+): Promise<RollingUpgradeResult> {
+  const dir = resolve(opts.lexiconDir);
+
+  if (!existsSync(dir)) {
+    return {
+      lexicon: "aws",
+      hasUpgrade: false,
+      severity: "none",
+      delta: { added: [], changed: [], removed: [], severity: "none" },
+      deltaText: "",
+      validationOk: false,
+      failures: [{ step: "setup", output: `Lexicon directory not found: ${dir}` }],
+      apiVersionDelta: [],
+      freshSnapshot: null,
+    };
+  }
+
+  return checkRollingUpgrade({
+    lexiconDir: dir,
+    force: opts.force,
+    verbose: opts.verbose,
+  });
+}
+
+/**
+ * Map surface severity to the semver PR label an upgrade would carry.
+ * additive → minor, breaking → major, none → none.
+ */
+export function severityToLabel(severity: RollingUpgradeResult["severity"]): string {
+  if (severity === "breaking") return "major";
+  if (severity === "additive") return "minor";
+  return "none";
+}
+
+// ── Human-readable output ─────────────────────────────────────────────
+
+const COLORS = {
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  red: "\x1b[31m",
+  gray: "\x1b[90m",
+  bold: "\x1b[1m",
+  reset: "\x1b[0m",
+};
+
+function useColors(): boolean {
+  return !process.env.NO_COLOR && process.stdout.isTTY !== false;
+}
+
+function c(text: string, code: string): string {
+  return useColors() ? `${code}${text}${COLORS.reset}` : text;
+}
+
+/**
+ * Print the rolling-upgrade result to stdout.
+ */
+export function printRollingUpgradeResult(result: RollingUpgradeResult, json: boolean): void {
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          lexicon: result.lexicon,
+          hasUpgrade: result.hasUpgrade,
+          severity: result.severity,
+          label: severityToLabel(result.severity),
+          validationOk: result.validationOk,
+          delta: result.delta,
+          apiVersionDelta: result.apiVersionDelta,
+          failures: result.failures,
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  console.log(c(`Rolling upgrade check: ${result.lexicon}`, COLORS.bold));
+  console.log("");
+
+  // Surface delta — the review payload
+  if (result.deltaText) {
+    console.log(result.deltaText);
+  } else {
+    console.log(c("No surface changes.", COLORS.green));
+  }
+
+  // azure API-version delta
+  if (result.apiVersionDelta.length > 0) {
+    console.log("");
+    console.log(c(`API version changes (${result.apiVersionDelta.length}):`, COLORS.bold));
+    for (const v of result.apiVersionDelta) {
+      const arrow =
+        v.kind === "added"
+          ? `+ ${v.provider} (${v.after})`
+          : v.kind === "removed"
+            ? `- ${v.provider} (was ${v.before})`
+            : `~ ${v.provider}: ${v.before} -> ${v.after}`;
+      console.log(`  ${arrow}`);
+    }
+  }
+
+  // Failures
+  if (result.failures.length > 0) {
+    console.log("");
+    console.log(c(`${result.failures.length} step(s) failed:`, COLORS.bold));
+    for (const f of result.failures) {
+      console.log(
+        c(
+          `  FAIL [${f.step}]${f.exitCode !== undefined ? ` (exit ${f.exitCode})` : ""}`,
+          COLORS.red,
+        ),
+      );
+      if (f.output) {
+        const indented = f.output
+          .split("\n")
+          .map((l) => `       ${l}`)
+          .join("\n");
+        console.log(c(indented, COLORS.gray));
+      }
+    }
+  }
+
+  console.log("");
+
+  // Decision line
+  const severityColor =
+    result.severity === "breaking"
+      ? COLORS.red
+      : result.severity === "additive"
+        ? COLORS.yellow
+        : COLORS.green;
+
+  const label = severityToLabel(result.severity);
+  const validationLabel = result.validationOk
+    ? c("ok", COLORS.green)
+    : c("FAILED", COLORS.red);
+
+  console.log(
+    `Upgrade: ${result.hasUpgrade}  Severity: ${c(result.severity, severityColor)}  ` +
+      `Label: ${label}  Validation: ${validationLabel}`,
+  );
+
+  if (result.hasUpgrade && result.validationOk) {
+    console.log(
+      c(
+        `A PR would be opened: chore(${result.lexicon}): regen from latest spec [${label}]`,
+        COLORS.gray,
+      ),
+    );
+  } else if (result.hasUpgrade && !result.validationOk) {
+    console.log(
+      c("Surface moved but validation failed — no PR; surfaces as a report/issue (#527).", COLORS.yellow),
+    );
+  } else {
+    console.log(c("No surface change — no PR.", COLORS.gray));
+  }
+}