@intentius/chant 0.13.1 → 0.15.0

package/src/cli/handlers/components.ts

@@ -0,0 +1,404 @@
+/**
+ * `chant components` handlers — release ledger + status surface (#568, epic
+ * #551 "Build & deploy observability").
+ *
+ * Two subcommands:
+ *  - `chant components release record` — append one immutable release record
+ *    to the `chant/lifecycle` orphan branch (../../lifecycle/release-ledger.ts).
+ *    A deploy composition calls this (typically from a `Verify` phase, or the
+ *    CI job that ran `chant build --components --generate <lexicon>`) once
+ *    the artifact digest, git sha, and run id are known.
+ *  - `chant components status [env]` — the status surface: joins the release
+ *    ledger against live evidence (`lifecycle diff --live` + ownership,
+ *    reused via `buildChangeSet`) by digest, and reports what's built vs
+ *    what's deployed where, flagging unrecorded deploys and drift.
+ *
+ * `componentBom`/`build.reproducibility` (#614) resolve to real data as of
+ * #609: for every recorded digest in an environment's ledger, this handler
+ * looks up the persisted `BuildArchiveManifest` that produced it
+ * (`findBuildManifestByArtifactDigest`, ../../lifecycle/build-ledger-
+ * store.ts) and derives `buildsByDigest`/`componentBomByDigest` from it via
+ * `buildLedgerEntries`/`componentBomSummary` — the same derivation
+ * `build-ledger.test.ts` already exercises directly, now fed by a real
+ * manifest instead of a hand-built one. A digest with no persisted manifest
+ * (predates #609, or was recorded via `chant components release` alone with
+ * no corresponding build) simply has no entry in either map, so `build`/
+ * `componentBom` fall back to `null` exactly as before — no regression for
+ * ledgers with no persisted manifests at all.
+ */
+import { resolve } from "node:path";
+import { getHeadCommit, fetchLifecycle, pushLifecycle, StaleLifecycleBranchError } from "../../lifecycle/git";
+import {
+  appendReleaseRecord,
+  readReleaseLedger,
+  listReleaseEnvironments,
+  InvalidReleaseRecordError,
+} from "../../lifecycle/release-ledger";
+import { reconcileStatus, liveEvidenceFromChangeSet, compareAcrossEnvironments } from "../../lifecycle/status";
+import { buildChangeSet } from "../../lifecycle/change-set";
+import { buildLedgerEntries, componentBomSummary, type BuildLedgerEntry } from "../../lifecycle/build-ledger";
+import { findBuildManifestByArtifactDigest } from "../../lifecycle/build-ledger-store";
+import type { ComponentBomSummary } from "../../lifecycle/build-ledger";
+import { loadChantConfig } from "../../config";
+import { build } from "../../build";
+import { discoverComponents } from "../../components/discover";
+import { formatError, formatWarning, formatSuccess, formatBold } from "../format";
+import type { CommandContext } from "../registry";
+import type { ResourceMetadata } from "../../lexicon";
+
+/**
+ * chant components release <env> --component <name> --digest <sha256:...>
+ *   [--git-sha <sha>] [--run-id <id>] [--actor <name>]
+ *
+ * `--git-sha` defaults to the current HEAD commit (`git rev-parse HEAD`);
+ * `--run-id` defaults to common CI run-id env vars
+ * (`GITHUB_RUN_ID`/`CI_PIPELINE_ID`) or a locally generated id; `--actor`
+ * defaults to common CI actor env vars
+ * (`GITHUB_ACTOR`/`GITLAB_USER_LOGIN`/`USER`) but must resolve to *something*
+ * — an unattributed release record defeats the point of a release ledger, so
+ * this is the one field with no silent fallback to a placeholder.
+ *
+ * The timestamp is always a real `new Date()` taken here, at record time —
+ * never threaded in from elsewhere and never mocked in production code, per
+ * #568: "the session cannot call Date.now() in some contexts; take the
+ * timestamp from the environment/CLI at record time."
+ */
+export async function runComponentsReleaseRecord(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const environment = args.extraPositional;
+  if (!environment) {
+    console.error(formatError({
+      message: "Environment is required: chant components release <env> --component <name> --digest <sha256:...>",
+    }));
+    return 1;
+  }
+
+  const component = args.component;
+  const digest = args.digest;
+  if (!component || !digest) {
+    console.error(formatError({
+      message: "--component and --digest are required",
+      hint: "chant components release <env> --component <name> --digest <sha256:...> [--git-sha <sha>] [--run-id <id>] [--actor <name>]",
+    }));
+    return 1;
+  }
+
+  const gitSha = args.gitSha ?? (await getHeadCommit().catch(() => undefined));
+  const runId = args.runId ?? process.env.GITHUB_RUN_ID ?? process.env.CI_PIPELINE_ID ?? `local-${Date.now()}`;
+  const actor = args.actor ?? process.env.GITHUB_ACTOR ?? process.env.GITLAB_USER_LOGIN ?? process.env.USER;
+
+  if (!gitSha) {
+    console.error(formatError({ message: "Could not resolve --git-sha (not in a git repo?) — pass it explicitly." }));
+    return 1;
+  }
+  if (!actor) {
+    console.error(formatError({
+      message: "Could not resolve --actor from the environment",
+      hint: "Pass --actor explicitly, or set GITHUB_ACTOR / GITLAB_USER_LOGIN / USER.",
+    }));
+    return 1;
+  }
+
+  const timestamp = new Date().toISOString();
+
+  try {
+    const { commit, record } = await appendReleaseRecord({
+      component,
+      env: environment,
+      digest,
+      gitSha,
+      runId,
+      timestamp,
+      actor,
+    });
+    await pushLifecycle();
+    if (args.json) {
+      console.log(JSON.stringify(record, null, 2));
+    } else {
+      console.error(formatSuccess(
+        `Recorded release: ${formatBold(component)}@${environment} -> ${digest} (commit ${commit.slice(0, 7)})`,
+      ));
+    }
+    return 0;
+  } catch (err) {
+    if (err instanceof InvalidReleaseRecordError) {
+      console.error(formatError({ message: err.message }));
+      return 1;
+    }
+    if (err instanceof StaleLifecycleBranchError) {
+      console.error(formatError({
+        message: err.message,
+        hint: `Pull and retry: \`git fetch origin chant/lifecycle:chant/lifecycle\` && \`chant components release ${environment} --component ${component} --digest ${digest}\`.`,
+      }));
+      return 1;
+    }
+    throw err;
+  }
+}
+
+/** One row of `chant components status` JSON output. */
+interface StatusJsonRow {
+  component: string;
+  env: string;
+  recorded: {
+    digest: string;
+    gitSha: string;
+    runId: string;
+    timestamp: string;
+    actor: string;
+  } | null;
+  build: {
+    manifestDigest: string;
+    referrers: string[];
+    /** SBOM summary for this digest (#606), when one was generated and is discoverable — archive-carried or referrer-projected. `null` when neither source has one (e.g. the component opted out, or has no built artifact). */
+    sbom: { mediaType: string; packageCount?: number; generator?: string; source: string } | null;
+    /** This artifact's own honest, per-artifact reproducibility record (#614) — `null` when none is recorded. */
+    reproducibility: { basis: string; verifyBy?: string } | null;
+  } | null;
+  /**
+   * Component-level BOM aggregation summary (#614), when the recorded
+   * digest's build archive manifest is available — resolved from the
+   * persisted manifest store (#609, ../../lifecycle/build-ledger-store.ts)
+   * by digest. `null` when unavailable (no manifest was ever persisted for
+   * this digest — it predates #609, or was recorded via `chant components
+   * release` alone with no corresponding `chant build`/`run`) or when the
+   * manifest carries no BOM at all.
+   */
+  componentBom: {
+    leaves: Array<{ path: string; bomKind: string; subjectDigest?: string; mediaType: string; packageCount?: number; generator?: string }>;
+    totalPackageCount: number;
+    isAssembly: boolean;
+  } | null;
+  reconciliation: string;
+  detail: string;
+}
+
+/**
+ * chant components status [env] [--live] [--json] [--compare-to <env>]
+ *
+ * Answers "what's built" and "what's deployed where," joined by digest.
+ * Without `--live`, reports the release ledger alone (recorded vs unrecorded
+ * is meaningless without live evidence, so every recorded row reports
+ * `unknown` reconciliation — still useful as a pure ledger read). With
+ * `--live`, joins against `lifecycle diff --live` + ownership (reusing
+ * `buildChangeSet`, the same classification `lifecycle plan` already
+ * trusts) to flag unrecorded deploys and drift.
+ *
+ * Omitting `<env>` reports every environment that has release records.
+ * `--compare-to <env>` answers the single-query cross-environment question
+ * the epic names explicitly: "which build is in `<env>`, and is it the one
+ * tested in `<compare-to>`."
+ */
+export async function runComponentsStatus(ctx: CommandContext): Promise<number> {
+  const { args, plugins, serializers } = ctx;
+  const requestedEnv = args.extraPositional;
+
+  await fetchLifecycle();
+
+  const environments = requestedEnv ? [requestedEnv] : await listReleaseEnvironments();
+  if (environments.length === 0) {
+    console.error(formatWarning({
+      message: requestedEnv
+        ? `No release records found for environment "${requestedEnv}"`
+        : "No release records found in any environment",
+    }));
+    return args.json ? (console.log(JSON.stringify([])), 0) : 0;
+  }
+
+  // Discover components (best-effort) so a live/owned-but-never-recorded
+  // component still gets a row, not just those that appear in the ledger.
+  const { config } = await loadChantConfig(resolve("."));
+  const discovery = await discoverComponents(resolve(args.src ?? config.sourceDir ?? "."));
+  const allComponents = [...discovery.components.keys()];
+
+  // Component -> live entity/resource name(s) it owns (#598), when declared
+  // explicitly via `Component.liveNames`. Components with no `liveNames`
+  // simply have no entry here, so `liveEvidenceFromChangeSet` falls back to
+  // the name == entity join — no regression for the pilot components.
+  const liveNameMapping = new Map<string, string[] | undefined>();
+  for (const [name, discovered] of discovery.components) {
+    if (discovered.component.liveNames?.length) {
+      liveNameMapping.set(name, discovered.component.liveNames);
+    }
+  }
+
+  const allRows: StatusJsonRow[] = [];
+  const ledgerByEnv = new Map<string, Awaited<ReturnType<typeof readReleaseLedger>>>();
+
+  for (const environment of environments) {
+    const ledger = await readReleaseLedger(environment);
+    ledgerByEnv.set(environment, ledger);
+    if (ledger.malformed > 0) {
+      console.error(formatWarning({ message: `${environment}: skipped ${ledger.malformed} malformed ledger line(s)` }));
+    }
+
+    let liveEvidence;
+    if (args.live) {
+      const targetSerializers = serializers;
+      const buildResult = await build(resolve(args.src ?? config.sourceDir ?? "."), targetSerializers);
+      const merged: { env: string; entries: import("../../lifecycle/change-set").ChangeSetEntry[] } = { env: environment, entries: [] };
+      for (const plugin of plugins) {
+        if (!plugin.describeResources) continue;
+        const declared = new Set<string>();
+        const entities = new Map<string, { entityType: string; props: Record<string, unknown> }>();
+        for (const [name, entity] of buildResult.entities) {
+          if (entity.lexicon === plugin.name) {
+            declared.add(name);
+            entities.set(name, {
+              entityType: entity.entityType,
+              props: ("props" in entity && entity.props != null ? entity.props : {}) as Record<string, unknown>,
+            });
+          }
+        }
+        let observedNow: Record<string, ResourceMetadata>;
+        try {
+          observedNow = await plugin.describeResources({ environment, buildOutput: "", entityNames: Array.from(declared), entities });
+        } catch (err) {
+          console.error(formatWarning({ message: `${plugin.name}: describeResources failed — ${err instanceof Error ? err.message : String(err)}` }));
+          continue;
+        }
+        const cs = buildChangeSet(environment, { declared, observedNow, observedThen: undefined });
+        merged.entries.push(...cs.entries);
+      }
+      liveEvidence = liveEvidenceFromChangeSet(merged, liveNameMapping);
+    }
+
+    // #609: resolve the persisted build manifest behind each recorded digest
+    // (if any) so `build`/`componentBom` are real queries, not always null.
+    const buildsByDigest = new Map<string, BuildLedgerEntry>();
+    const componentBomByDigest = new Map<string, ComponentBomSummary>();
+    const recordedDigests = new Set(ledger.records.map((r) => r.digest));
+    for (const digest of recordedDigests) {
+      const manifest = await findBuildManifestByArtifactDigest(digest);
+      if (!manifest) continue;
+
+      const bom = componentBomSummary(manifest);
+      if (bom) componentBomByDigest.set(digest, bom);
+
+      const ledgerEntries = await buildLedgerEntries(manifest);
+      const entry = ledgerEntries.find((e) => e.digest === digest);
+      if (entry) buildsByDigest.set(digest, entry);
+    }
+
+    const rows = reconcileStatus(environment, ledger.records, {
+      liveEvidence,
+      allComponents,
+      buildsByDigest,
+      componentBomByDigest,
+    });
+
+    for (const row of rows) {
+      allRows.push({
+        component: row.component,
+        env: row.env,
+        recorded: row.recorded
+          ? {
+              digest: row.recorded.digest,
+              gitSha: row.recorded.gitSha,
+              runId: row.recorded.runId,
+              timestamp: row.recorded.timestamp,
+              actor: row.recorded.actor,
+            }
+          : null,
+        build: row.build
+          ? {
+              manifestDigest: row.build.manifestDigest,
+              referrers: row.build.referrers.map((r) => r.kind),
+              sbom: row.build.sbom
+                ? {
+                    mediaType: row.build.sbom.mediaType,
+                    packageCount: row.build.sbom.packageCount,
+                    generator: row.build.sbom.generator,
+                    source: row.build.sbom.source,
+                  }
+                : null,
+              reproducibility: row.build.reproducibility
+                ? { basis: row.build.reproducibility.basis, verifyBy: row.build.reproducibility.verifyBy }
+                : null,
+            }
+          : null,
+        componentBom: row.componentBom
+          ? {
+              leaves: row.componentBom.leaves.map((l) => ({
+                path: l.path,
+                bomKind: l.bomKind,
+                subjectDigest: l.subjectDigest,
+                mediaType: l.mediaType,
+                packageCount: l.packageCount,
+                generator: l.generator,
+              })),
+              totalPackageCount: row.componentBom.totalPackageCount,
+              isAssembly: row.componentBom.isAssembly,
+            }
+          : null,
+        reconciliation: row.reconciliation,
+        detail: row.detail,
+      });
+    }
+  }
+
+  // `--compare-to` — single-query cross-env digest comparison, per component.
+  let comparisons: ReturnType<typeof compareAcrossEnvironments>[] | undefined;
+  if (args.compareTo && requestedEnv) {
+    const otherLedger = ledgerByEnv.get(args.compareTo) ?? (await readReleaseLedger(args.compareTo));
+    const componentsToCompare = new Set([...allRows.map((r) => r.component)]);
+    comparisons = [...componentsToCompare].sort().map((component) =>
+      compareAcrossEnvironments(
+        component,
+        { name: requestedEnv, records: ledgerByEnv.get(requestedEnv)?.records ?? [] },
+        { name: args.compareTo!, records: otherLedger.records },
+      ),
+    );
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify(comparisons ? { rows: allRows, comparisons } : allRows, null, 2));
+    return 0;
+  }
+
+  console.log(
+    formatBold("COMPONENT".padEnd(24)) +
+    formatBold("ENV".padEnd(12)) +
+    formatBold("DIGEST".padEnd(20)) +
+    formatBold("STATUS".padEnd(14)) +
+    formatBold("DETAIL"),
+  );
+  console.log("-".repeat(110));
+  for (const row of allRows) {
+    const digestShort = row.recorded ? row.recorded.digest.slice(0, 19) : "-";
+    console.log(
+      row.component.padEnd(24) +
+      row.env.padEnd(12) +
+      digestShort.padEnd(20) +
+      row.reconciliation.padEnd(14) +
+      row.detail,
+    );
+  }
+
+  if (comparisons) {
+    console.log(`\n${formatBold(`Cross-check: ${requestedEnv} vs ${args.compareTo}`)}`);
+    for (const c of comparisons) {
+      const verdict = c.same ? "same build" : "DIFFERENT builds";
+      console.log(`  ${c.component}: ${c.digestA ?? "(none)"} vs ${c.digestB ?? "(none)"} — ${verdict}`);
+    }
+  }
+
+  const unrecordedCount = allRows.filter((r) => r.reconciliation === "unrecorded").length;
+  const driftedCount = allRows.filter((r) => r.reconciliation === "drifted").length;
+  if (unrecordedCount === 0 && driftedCount === 0) {
+    console.error(formatSuccess(`No unrecorded deploys or drift across ${allRows.length} row(s)`));
+  } else {
+    console.error(formatWarning({ message: `${unrecordedCount} unrecorded, ${driftedCount} drifted` }));
+  }
+
+  return 0;
+}
+
+/** Fallback for `chant components` with no/unknown subcommand. */
+export async function runComponentsUnknown(ctx: CommandContext): Promise<number> {
+  console.error(formatError({
+    message: `Unknown components subcommand: ${ctx.args.path}`,
+    hint: "Available: chant components status [env], chant components release <env>",
+  }));
+  return 1;
+}

package/src/cli/handlers/dev.ts

@@ -46,10 +46,69 @@ export async function runDevCheckLexicon(ctx: CommandContext): Promise<number> {
   return result.tier1Pass ? 0 : 1;
 }
 
+export async function runDevSurfaceDiff(ctx: CommandContext): Promise<number> {
+  const dir = ctx.args.extraPositional ?? ".";
+  const { runSurfaceDiff, printSurfaceDiffResult } = await import("../commands/lexicon-surface-diff");
+  const result = await runSurfaceDiff({
+    lexiconDir: resolve(dir),
+    force: ctx.args.force,
+    verbose: ctx.args.verbose,
+    runExamples: ctx.args.runExamples,
+    pinnedDigestPath: ctx.args.pinnedDigest,
+    // --check never writes; it verifies the committed baseline is in sync.
+    updateSnapshot: ctx.args.check ? false : ctx.args.updateSnapshot,
+    bump: ctx.args.bump,
+  });
+  printSurfaceDiffResult(result, ctx.args.format === "json");
+  // --check: fail if regen failed OR the fresh surface drifted from the
+  // committed baseline (stale/hand-edited baseline, or pin bumped without
+  // updating it). Meaningful for pinned lexicons — a fresh regen at the pinned
+  // version must equal the baseline. #545.
+  if (ctx.args.check) {
+    if (!result.ok) return 1;
+    if (result.changed) {
+      console.error(
+        `Baseline out of sync: ${dir}/surface.snapshot.json differs from a fresh regen. ` +
+          `Re-baseline with: chant dev surface-diff ${dir} --update-snapshot --bump`,
+      );
+      return 1;
+    }
+    return 0;
+  }
+  return result.ok ? 0 : 1;
+}
+
+export async function runDevPinnedUpgrade(ctx: CommandContext): Promise<number> {
+  const dir = ctx.args.extraPositional ?? ".";
+  const { runPinnedUpgrade, printPinnedUpgradeResult } = await import("../commands/pinned-upgrade");
+  const result = await runPinnedUpgrade({
+    lexiconDir: resolve(dir),
+    force: ctx.args.force,
+    verbose: ctx.args.verbose,
+  });
+  printPinnedUpgradeResult(result, ctx.args.format === "json");
+  // Exit non-zero when the upstream query failed or the regen validation broke.
+  if (result.fetchError) return 1;
+  if (result.validation && !result.validation.ok) return 1;
+  return 0;
+}
+
+export async function runDevRollingUpgrade(ctx: CommandContext): Promise<number> {
+  const dir = ctx.args.extraPositional ?? ".";
+  const { runRollingUpgrade, printRollingUpgradeResult } = await import("../commands/lexicon-rolling-upgrade");
+  const result = await runRollingUpgrade({
+    lexiconDir: resolve(dir),
+    force: ctx.args.force,
+    verbose: ctx.args.verbose,
+  });
+  printRollingUpgradeResult(result, ctx.args.format === "json");
+  return result.validationOk ? 0 : 1;
+}
+
 export async function runDevUnknown(ctx: CommandContext): Promise<number> {
   console.error(formatError({
     message: `Unknown dev subcommand: ${ctx.args.path}`,
-    hint: "Available: chant dev generate, chant dev publish, chant dev onboard, chant dev check-lexicon",
+    hint: "Available: chant dev generate, chant dev publish, chant dev onboard, chant dev check-lexicon, chant dev surface-diff, chant dev pinned-upgrade, chant dev rolling-upgrade",
   }));
   return 1;
 }

package/src/cli/handlers/graph.ts

@@ -12,22 +12,67 @@ import { lintCommand } from "../commands/lint";
 import { readFileSync } from "node:fs";
 import { formatError, formatWarning, formatBold } from "../format";
 import type { CommandContext } from "../registry";
+import { computeComponentGraph } from "../../components/cli-support";
 
 /**
  * `chant graph` — the Op dependency graph by default; `--stacks` renders the
  * cross-stack apply-ordering graph (edges, order, waves) chant computes from
- * cross-lexicon references; `--format ir|mermaid` emits the lint-gated
- * entity-graph IR (or a Mermaid flowchart of it) for diagrams (#493/#496).
+ * cross-lexicon references; `--components` (#560) renders the same
+ * order/waves shape for discovered `Component` declarations, from their
+ * `dependsOn`; `--format ir|mermaid` emits the lint-gated entity-graph IR (or
+ * a Mermaid flowchart of it) for diagrams (#493/#496).
  */
 export async function runGraph(ctx: CommandContext): Promise<number> {
   const viewFormats = ["ir", "mermaid", "dot", "layout"] as const;
   if ((viewFormats as readonly string[]).includes(ctx.args.format)) {
     return runGraphView(ctx, ctx.args.format as (typeof viewFormats)[number]);
   }
+  if (ctx.args.components) return runComponentGraph(ctx);
   if (ctx.args.stacks) return runStackGraph(ctx);
   return runOpGraph();
 }
 
+/**
+ * `chant graph --components` (#560) — dependency order/waves for discovered
+ * `Component` declarations, mirroring `runStackGraph`'s presentation
+ * (waves top-to-bottom, consumer → producer edges) but sourced from
+ * `computeComponentGraph` (../../components/cli-support.ts), which resolves
+ * order purely from each component's flat `dependsOn` list — no AttrRef-style
+ * cross-lexicon inference needed, since a component's dependency is always
+ * an explicit name.
+ */
+async function runComponentGraph(ctx: CommandContext): Promise<number> {
+  const projectPath = resolve(ctx.args.path === "." ? "." : ctx.args.path);
+  const graph = await computeComponentGraph(projectPath);
+
+  if (!graph.success) {
+    console.error(formatError({ message: graph.error ?? "Failed to compute component graph" }));
+    return 1;
+  }
+
+  if (ctx.args.json) {
+    console.log(JSON.stringify(graph, null, 2));
+    return 0;
+  }
+
+  if (graph.order.length === 0) {
+    console.log("No components found");
+    return 0;
+  }
+
+  console.log(formatBold("Deploy order (waves apply top-to-bottom; a wave's components are parallel-safe):"));
+  graph.waves.forEach((wave, i) => console.log(`  ${i + 1}. ${wave.join(", ")}`));
+
+  if (graph.edges.length > 0) {
+    console.log(formatBold("\nDependencies (consumer → producer):"));
+    for (const { from, to } of graph.edges) console.log(`  ${from} → ${to}`);
+  } else {
+    console.log("\nNo cross-component dependencies — all components are independent.");
+  }
+
+  return 0;
+}
+
 /**
  * `chant graph --format ir|mermaid|dot|layout` — build the graph IR (honouring
  * `--detail`) and emit it as JSON, a Mermaid flowchart, Graphviz DOT, or node

package/src/cli/handlers/misc.ts

@@ -4,9 +4,10 @@ import { importCommand, importFromLive, printImportResult } from "../commands/im
 import { auditCommand, printAuditResult, type AuditFormat, type AuditTier, type AuditFailOn } from "../commands/audit";
 import type { ReportTheme } from "../../audit/report-html";
 import type { ResourceSelector } from "../../lexicon";
-import { formatError, formatSuccess, formatWarning } from "../format";
+import { formatError, formatSuccess, formatWarning, formatBold } from "../format";
 import type { CommandContext } from "../registry";
 import { createRequire } from "module";
+import { listComponents, describeComponent } from "../../components/cli-support";
 
 const CHANT_VERSION: string = (() => {
   try {
@@ -84,6 +85,30 @@ export async function runList(ctx: CommandContext): Promise<number> {
     return 1;
   }
 
+  // `chant list --components` (#560) surfaces discovered `Component`
+  // declarations instead of lexicon resources — a distinct entity kind (no
+  // `lexicon`/`entityType`), so it is a separate branch rather than folded
+  // into `listCommand`'s Declarable-shaped `ListEntity` rows.
+  if (args.components) {
+    const result = await listComponents(args.path);
+    if (!result.success) {
+      for (const e of result.errors) console.error(formatError({ message: e }));
+      return 1;
+    }
+    if (listFormat === "json") {
+      console.log(JSON.stringify(result.components, null, 2));
+    } else if (result.components.length === 0) {
+      console.log("No components found.");
+    } else {
+      console.log(formatBold("NAME") + "  " + formatBold("ARCHETYPE") + "  " + formatBold("DEPENDS ON") + "  " + formatBold("PHASES"));
+      for (const c of result.components) {
+        console.log(`${c.name}  ${c.archetype}  ${c.dependsOn.join(", ") || "-"}  ${c.phases.join(", ")}`);
+      }
+    }
+    console.error(formatSuccess(`Found ${formatBold(String(result.components.length))} component(s)`));
+    return 0;
+  }
+
   const result = await listCommand({
     path: args.path,
     format: listFormat,
@@ -112,6 +137,25 @@ export async function runDescribe(ctx: CommandContext): Promise<number> {
     return 1;
   }
 
+  // `chant describe <name> --components` (#560): describe a discovered
+  // `Component` (its full JSON contract projection) rather than a lexicon
+  // resource's resolved props bag.
+  if (args.components) {
+    const result = await describeComponent(args.extraPositional ?? ".", component);
+    if (!result.success || !result.described) {
+      console.log(result.output);
+      return 1;
+    }
+    if (describeFormat === "json") {
+      console.log(JSON.stringify(result.described.json, null, 2));
+    } else {
+      console.log(`${formatBold(result.described.name)}  (${result.described.filePath})`);
+      console.log(JSON.stringify(result.described.json, null, 2));
+    }
+    console.error(formatSuccess(`Described ${formatBold(component)}`));
+    return 0;
+  }
+
   const result = await describeCommand({
     component,
     path: args.extraPositional ?? ".",