@intentius/chant 0.13.1 → 0.15.0

package/src/cli/commands/lint.ts

@@ -1,11 +1,15 @@
 import { resolve, join } from "path";
 import { readFileSync, writeFileSync, readdirSync, statSync } from "fs";
-import { runLint } from "../../lint/engine";
+import { runLint, parseDisableComments } from "../../lint/engine";
 import type { LintRule, LintDiagnostic, LintFix } from "../../lint/rule";
 import { loadPlugins, resolveProjectLexicons } from "../plugins";
 import { formatStylish, formatJson, formatSarif } from "../reporters/stylish";
 import { loadLocalRules } from "../../lint/rule-loader";
 import { loadCoreRules } from "../../lint/rules/index";
+import { loadComponentChecks } from "../../lint/rules/comp/index";
+import { runComponentChecks, type ComponentCheckDiagnostic } from "../../lint/component-checks";
+import { buildCapabilityRegistry } from "../../components/capability-plugin-loader";
+import type { RollbackPolicy } from "../../components/capability";
 import { rule } from "../../lint/declarative";
 import { watchDirectory, formatTimestamp, formatChangedFiles } from "../watch";
 import { formatError, formatInfo } from "../format";
@@ -203,6 +207,126 @@ function getDefaultRules(
   return { rules, ruleOptions };
 }
 
+/**
+ * Run the COMP* composition checks (#562) over the discovered `Component`
+ * graph and convert their results into plain `LintDiagnostic`s so they merge
+ * into the same `chant lint` output (stylish/json/sarif) and the same
+ * error-count gating as every COR/EVL diagnostic.
+ *
+ * These checks operate on the whole discovered component graph, not one
+ * `ts.SourceFile`, so they carry no real line/column — reported at `1:1` in
+ * the file the component was declared in (matching COR009's whole-file
+ * diagnostic convention, see ../../lint/rules/file-declarable-limit.ts).
+ * Config severity overrides (`lint.rules["COMP001"]`, including `"off"`) are
+ * honored the same way `getDefaultRules` honors them for AST rules. Only the
+ * *file-level* disable directive form (`// chant-disable` /
+ * `// chant-disable COMP004 -- reason`, anywhere in the file) is honored —
+ * `-line`/`-next-line` need an exact line to match against, which a
+ * whole-component diagnostic does not have; see
+ * docs/lint-rules/composition.mdx for this documented limitation.
+ */
+/**
+ * Build the registry-derived context composition checks need — the set of
+ * capability kinds registered for this project (core's starter set plus the
+ * active lexicons' leaves, e.g. `cfn-deploy` when `lexicons: ["aws"]`) and each
+ * verb's rollback disposition — so COMP005/COMP003 read real registry facts
+ * rather than hard-coding verb lists. A verb's rollback policy is its own
+ * declaration (`rollbackPolicy`), else derived: a paired `rollback` method is
+ * `"native"`, everything else `"none-by-design"`. Tolerant: any failure (an
+ * unresolvable lexicon, a config-less directory) returns `undefined` fields,
+ * letting the checks fall back to core's starter set.
+ */
+async function resolveRegistryContext(
+  infraPath: string,
+): Promise<{ knownKinds?: ReadonlySet<string>; rollbackPolicies?: ReadonlyMap<string, RollbackPolicy> }> {
+  try {
+    const lexicons = await resolveProjectLexicons(infraPath).catch(() => [] as string[]);
+    const registry = await buildCapabilityRegistry({ lexicons });
+    const kinds = registry.kinds();
+    const rollbackPolicies = new Map<string, RollbackPolicy>();
+    for (const kind of kinds) {
+      const capability = registry.resolve(kind);
+      rollbackPolicies.set(kind, capability.rollbackPolicy ?? (capability.rollback ? "native" : "none-by-design"));
+    }
+    return { knownKinds: new Set(kinds), rollbackPolicies };
+  } catch {
+    return {};
+  }
+}
+
+async function runComponentCheckDiagnostics(
+  infraPath: string,
+): Promise<{ diagnostics: LintDiagnostic[]; suppressed: Array<LintDiagnostic & { reason?: string }> }> {
+  const config = loadConfig(infraPath);
+  const checks = loadComponentChecks();
+  const allCheckIds = new Set(checks.map((c) => c.id));
+
+  const registryContext = await resolveRegistryContext(infraPath);
+  const raw = await runComponentChecks(infraPath, checks, registryContext);
+
+  const fileDirectivesCache = new Map<string, ReturnType<typeof parseDisableComments>>();
+  const fileLevelDisable = (
+    file: string,
+    checkId: string,
+  ): { suppressed: boolean; reason?: string } => {
+    let directives = fileDirectivesCache.get(file);
+    if (!directives) {
+      let content = "";
+      try {
+        content = readFileSync(file, "utf-8");
+      } catch {
+        // File may be unreadable (e.g. a synthetic discovery-error path) — no directives to honor.
+      }
+      directives = parseDisableComments(content);
+      fileDirectivesCache.set(file, directives);
+    }
+
+    for (const directive of directives) {
+      if (directive.type !== "file") continue;
+      if (!directive.ruleIds) return { suppressed: true, reason: directive.reason };
+      if (directive.ruleIds.some((id) => allCheckIds.has(id) || id === "COMP000") && directive.ruleIds.includes(checkId)) {
+        return { suppressed: true, reason: directive.reason };
+      }
+    }
+    return { suppressed: false };
+  };
+
+  const toLintDiagnostic = (d: ComponentCheckDiagnostic, severity: LintDiagnostic["severity"]): LintDiagnostic => ({
+    file: d.file,
+    line: 1,
+    column: 1,
+    ruleId: d.checkId,
+    severity,
+    message: d.message,
+  });
+
+  const diagnostics: LintDiagnostic[] = [];
+  const suppressed: Array<LintDiagnostic & { reason?: string }> = [];
+
+  for (const d of raw) {
+    // Discovery errors (COMP000) always surface at error severity — not user-configurable.
+    let severity = d.severity;
+    if (d.checkId !== "COMP000") {
+      const configValue = config.rules?.[d.checkId];
+      if (configValue !== undefined) {
+        const parsed = parseRuleConfig(configValue);
+        if (parsed.severity === "off") continue;
+        severity = parsed.severity;
+      }
+    }
+
+    const disable = fileLevelDisable(d.file, d.checkId);
+    const diagnostic = toLintDiagnostic(d, severity);
+    if (disable.suppressed) {
+      suppressed.push({ ...diagnostic, reason: disable.reason });
+    } else {
+      diagnostics.push(diagnostic);
+    }
+  }
+
+  return { diagnostics, suppressed };
+}
+
 /**
  * Apply fixes to a file
  */
@@ -264,6 +388,15 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
     suppressed = result.suppressed;
   }
 
+  // Run the COMP* composition checks (#562) over the discovered `Component`
+  // graph and merge them into the same diagnostics/suppressed lists — a
+  // structurally distinct check family (whole-project, post-discovery,
+  // see ../../lint/component-checks.ts) but the same `chant lint` output and
+  // the same error-severity gating as every COR/EVL diagnostic.
+  const componentResult = await runComponentCheckDiagnostics(infraPath);
+  diagnostics.push(...componentResult.diagnostics);
+  suppressed.push(...componentResult.suppressed);
+
   // Apply fixes if requested
   if (options.fix) {
     // Group fixes by file
@@ -303,6 +436,14 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
       diagnostics = postResult.diagnostics;
       suppressed = postResult.suppressed;
     }
+
+    // COMP* checks have no `.fix` (nothing above could have touched a
+    // `*.component.ts` file on their behalf), but a fix applied to another
+    // rule could still be in the same file a component was discovered from —
+    // re-run for consistency with the AST re-lint above.
+    const postComponentResult = await runComponentCheckDiagnostics(infraPath);
+    diagnostics.push(...postComponentResult.diagnostics);
+    suppressed.push(...postComponentResult.suppressed);
   }
 
   // Count errors and warnings

package/src/cli/commands/pinned-upgrade.ts

@@ -0,0 +1,204 @@
+/**
+ * `chant dev pinned-upgrade <lexicon-dir>` command implementation.
+ *
+ * Detects whether a pinned-version lexicon (k8s, gcp, docker, gitlab) has a
+ * newer stable upstream release. When it does, it dry-run bumps the pinned
+ * version constant, regenerates + surface-diffs (via #524's regenLexicon), then
+ * reverts the bump — leaving the working tree unchanged.
+ *
+ * This command only REPORTS. Branch/PR automation lives in #527.
+ */
+
+import { existsSync } from "fs";
+import { basename, resolve } from "path";
+import {
+  checkPinnedUpgrade,
+  type LexiconId,
+  type UpgradeCheckResult,
+} from "../../codegen/pinned-upgrade";
+
+const PINNED_LEXICONS: readonly LexiconId[] = ["k8s", "gcp", "docker", "gitlab"];
+
+export interface PinnedUpgradeOptions {
+  /** Resolved path to the lexicon directory. */
+  lexiconDir: string;
+  /** Explicit lexicon id; inferred from the directory name when omitted. */
+  lexicon?: LexiconId;
+  /** Force re-fetch of the upstream spec during regen. */
+  force?: boolean;
+  /** Print subprocess output while running. */
+  verbose?: boolean;
+}
+
+/**
+ * Infer the lexicon id from a directory name. Returns null when the directory
+ * basename is not one of the pinned lexicons.
+ */
+export function inferLexicon(lexiconDir: string): LexiconId | null {
+  const name = basename(lexiconDir);
+  return (PINNED_LEXICONS as readonly string[]).includes(name) ? (name as LexiconId) : null;
+}
+
+/**
+ * Map a regen severity to a semver review label.
+ * additive → "minor"; breaking → "major"; none → "none".
+ */
+export function semverLabel(result: UpgradeCheckResult): "minor" | "major" | "none" {
+  const sev = result.validation?.severity;
+  if (sev === "breaking") return "major";
+  if (sev === "additive") return "minor";
+  return "none";
+}
+
+/**
+ * Run the pinned-upgrade check and return the structured result.
+ * Never throws — a missing dir or an unrecognised lexicon becomes a fetchError.
+ */
+export async function runPinnedUpgrade(opts: PinnedUpgradeOptions): Promise<UpgradeCheckResult> {
+  const dir = resolve(opts.lexiconDir);
+
+  const lexicon = opts.lexicon ?? inferLexicon(dir);
+  if (!lexicon) {
+    return {
+      lexicon: "k8s",
+      hasUpgrade: false,
+      from: "(unknown)",
+      to: null,
+      validation: null,
+      fetchError: `Not a pinned lexicon directory: ${dir}. Expected one of: ${PINNED_LEXICONS.join(", ")}.`,
+    };
+  }
+
+  if (!existsSync(dir)) {
+    return {
+      lexicon,
+      hasUpgrade: false,
+      from: "(unknown)",
+      to: null,
+      validation: null,
+      fetchError: `Lexicon directory not found: ${dir}`,
+    };
+  }
+
+  return checkPinnedUpgrade({
+    lexiconDir: dir,
+    lexicon,
+    force: opts.force,
+    verbose: opts.verbose,
+  });
+}
+
+// ── 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 pinned-upgrade result. `json` emits a machine-readable object.
+ */
+export function printPinnedUpgradeResult(result: UpgradeCheckResult, json: boolean): void {
+  const label = semverLabel(result);
+
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          lexicon: result.lexicon,
+          hasUpgrade: result.hasUpgrade,
+          from: result.from,
+          to: result.to,
+          semver: label,
+          severity: result.validation?.severity ?? "none",
+          changed: result.validation?.changed ?? false,
+          delta: result.validation?.delta ?? null,
+          validationOk: result.validation?.ok ?? null,
+          failures: result.validation?.failures ?? [],
+          fetchError: result.fetchError,
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  if (result.fetchError) {
+    console.log(c(`[${result.lexicon}] error: ${result.fetchError}`, COLORS.red));
+    return;
+  }
+
+  if (!result.hasUpgrade) {
+    console.log(
+      c(`[${result.lexicon}] up to date`, COLORS.green) +
+        `  pinned=${result.from}` +
+        (result.to ? ` latest=${result.to}` : ""),
+    );
+    return;
+  }
+
+  // Upgrade available
+  console.log(
+    c(`[${result.lexicon}] upgrade available`, COLORS.bold) +
+      `  ${result.from} -> ${result.to}`,
+  );
+
+  const v = result.validation;
+  if (v) {
+    // Surface delta
+    if (v.deltaText) {
+      console.log("");
+      console.log(v.deltaText);
+    } else if (v.changed) {
+      console.log("  Surface changed (no baseline to diff against).");
+    } else {
+      console.log("  No surface changes.");
+    }
+
+    // Failures
+    if (v.failures.length > 0) {
+      console.log("");
+      console.log(c(`  ${v.failures.length} validation step(s) failed:`, COLORS.bold));
+      for (const f of v.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("");
+  const labelColor =
+    label === "major" ? COLORS.red : label === "minor" ? COLORS.yellow : COLORS.green;
+  const validationLabel = v
+    ? v.ok
+      ? c("ok", COLORS.green)
+      : c("FAILED", COLORS.red)
+    : c("skipped", COLORS.gray);
+  console.log(
+    `Validation: ${validationLabel}  Semver: ${c(label, labelColor)}  ${result.from} -> ${result.to}`,
+  );
+}

package/src/cli/handlers/build.ts

@@ -1,11 +1,68 @@
+import { writeFileSync, mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
 import { buildCommand, buildCommandWatch, printErrors, printWarnings, resolveBuildFormat } from "../commands/build";
-import { formatError, formatInfo } from "../format";
+import { formatError, formatInfo, formatSuccess, formatBold } from "../format";
 import type { CommandContext } from "../registry";
+import { generateComponentsPipeline } from "../../components/cli-support";
+
+/**
+ * `chant build --components --generate <lexicon>` — generate mode (#563,
+ * epic #551 Phase 3). Discovers `Component` declarations under `args.path`
+ * and synthesizes a thin CI pipeline for `lexicon` instead of running a
+ * normal lexicon build: no entity discovery, no serializers, no post-synth
+ * checks — those apply to lexicon resources, which is a different input to
+ * a different command path (`chant build` without `--components`).
+ */
+async function runGenerateComponents(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const lexicon = args.generate as string;
+
+  // Which lexicons support generate mode is a property of the loaded lexicon
+  // plugins (those implementing `generateComponentPipeline`, #688), not a
+  // hard-coded core list — `generateComponentsPipeline` returns a descriptive
+  // error when the target lexicon has no generator.
+  const result = await generateComponentsPipeline(args.path, lexicon, {
+    env: args.env,
+  });
+
+  if (!result.success) {
+    console.error(formatError({ message: result.error ?? "Failed to generate CI pipeline from components" }));
+    return 1;
+  }
+
+  const yaml = result.yaml ?? "";
+  if (args.format === "json") {
+    console.log(JSON.stringify({ stages: result.stages, jobs: result.jobs, yaml }, null, 2));
+  } else if (args.output) {
+    const outputPath = resolve(args.output);
+    mkdirSync(dirname(outputPath), { recursive: true });
+    writeFileSync(outputPath, yaml);
+  } else {
+    console.log(yaml);
+  }
+
+  if (args.verbose || args.output) {
+    console.error(
+      formatSuccess(
+        `Generated ${formatBold(lexicon)} pipeline: ${formatBold(String(result.jobs?.length ?? 0))} job(s) across ${formatBold(String(result.stages?.length ?? 0))} wave(s)`,
+      ),
+    );
+  }
+
+  return 0;
+}
 
 export async function runBuild(ctx: CommandContext): Promise<number> {
   const { args, plugins } = ctx;
   let { serializers } = ctx;
 
+  // Generate mode (#563): synthesize CI YAML from components instead of
+  // running a normal lexicon build. Checked first since it does not need
+  // `serializers`/lexicon resources at all.
+  if (args.components && args.generate) {
+    return runGenerateComponents(ctx);
+  }
+
   // Filter to a single lexicon when --lexicon is specified
   if (args.lexicon) {
     serializers = serializers.filter((s) => s.name === args.lexicon);