@intentius/chant 0.84.0 → 0.86.0

package/src/components/cli-support.test.ts

@@ -389,6 +389,22 @@ export const backup =
     expect(result.composites?.["aws-plane"]).toEqual(["ArtifactBucket", "OperatorRole"]);
     expect(result.composites?.plain).toBeUndefined();
   });
+
+  test("carries each component's archetype, declared or inferred (#2662)", async () => {
+    await writeFile(
+      join(testDir, "lib.component.ts"),
+      `export const lib = { name: "lib", archetype: "service", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "shell", reason: "test" }] }] };`,
+    );
+    await writeFile(
+      join(testDir, "plain.component.ts"),
+      `export const plain = { name: "plain", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "shell", reason: "test" }] }] };`,
+    );
+
+    const result = await computeComponentGraph(testDir);
+
+    expect(result.success).toBe(true);
+    expect(result.archetypes).toEqual({ lib: "service", plain: "infra" });
+  });
 });
 
 // ── runComponents (#585) ─────────────────────────────────────────────────────

package/src/components/cli-support.ts

@@ -25,7 +25,7 @@
 import { lexiconModulePath, lexiconNames } from "../lexicon-module";
 import { discoverComponents } from "./discover";
 import type { BuildParamProvenance } from "../provenance";
-import { projectToJson, type Archetype } from "./component";
+import { inferArchetype, projectToJson, type Archetype } from "./component";
 import {
   resolveComponentGraph,
   runInterpretDriver,
@@ -152,6 +152,10 @@ export interface ComponentGraphResult {
    * entirely rather than defaulting to a guess; a consumer with no entry here
    * keeps applying its own naming-convention default. */
   composites?: Record<string, string[]>;
+  /** Component name → its archetype, declared or inferred from the composition
+   * (`inferArchetype`), so a reader can label a component without its source
+   * (#2662). */
+  archetypes?: Record<string, Archetype>;
   error?: string;
 }
 
@@ -187,7 +191,9 @@ export async function computeComponentGraph(
   // component name → declared composite kind(s) (#1492), only for components
   // that declared them — no identity fallback (see ComponentGraphResult doc).
   const composites: Record<string, string[]> = {};
+  const archetypes: Record<string, Archetype> = {};
   for (const [name, discovered] of result.components) {
+    archetypes[name] = discovered.component.archetype ?? inferArchetype(discovered.component);
     files[name] = relative(path, discovered.filePath);
     const declared = discovered.component.liveNames;
     liveNames[name] = declared && declared.length > 0 ? [...declared] : [name];
@@ -201,7 +207,7 @@ export async function computeComponentGraph(
     for (const c of driverComponents) {
       for (const dep of c.dependsOn ?? []) edges.push({ from: c.name, to: dep });
     }
-    return { success: true, order, waves, edges, files, liveNames, composites };
+    return { success: true, order, waves, edges, files, liveNames, composites, archetypes };
   } catch (err) {
     if (err instanceof UnknownDependencyError || err instanceof DependencyCycleError) {
       return { success: false, order: [], waves: [], edges: [], error: err.message };

package/src/composite.ts

@@ -71,6 +71,15 @@ export function isCompositeInstance(value: unknown): value is CompositeInstance
   );
 }
 
+/**
+ * Type guard: is this value a composite definition, what `Composite()` and
+ * `withDefaults()` return? A lexicon's composite catalog test uses it to find
+ * the composites a module exports (#2662).
+ */
+export function isCompositeDefinition(value: unknown): value is CompositeDefinition<unknown> {
+  return typeof value === "function" && typeof (value as { compositeName?: unknown }).compositeName === "string";
+}
+
 /**
  * Global registry of composite definitions.
  */

package/src/lexicon.ts

@@ -28,6 +28,7 @@ import type { BehaviourKinds } from "./behaviour-kinds";
 import type { DisruptionQuery, DisruptionVerdict } from "./lifecycle/disruption";
 import type { OwnerChainVerdict } from "./owner-chain";
 import type { CommandGroup } from "./cli/command-group";
+import type { Archetype } from "./components/component";
 
 // Re-exported so a lexicon that hosts Op runs (#2121) can type its
 // `opRuntime` from the same entry it imports the plugin contract from.
@@ -929,6 +930,45 @@ export interface AuditEntitiesInput {
   baseDir?: string;
 }
 
+/**
+ * One parameter of a composite, read from the composite's declared props type
+ * (#2662).
+ */
+export interface CompositeParam {
+  /** The prop name as a caller writes it. */
+  name: string;
+  /** The declared TypeScript type, as source text (long inline types are shortened). */
+  type: string;
+  /** False when the prop is optional. */
+  required: boolean;
+  /** The prop's JSDoc summary, when it has one. */
+  description?: string;
+}
+
+/**
+ * A composite this lexicon exports, as static catalog data (#2662).
+ *
+ * The catalog is what `chant serve mcp` answers "what composites do you have
+ * for aws?" from: the `composites` tool, the `chant://composites` resource and
+ * `search` results of kind `composite` all read it, and none of them calls a
+ * provider. A lexicon writes it once, from source, and a test in the lexicon
+ * holds it to the composites the package actually exports.
+ */
+export interface CompositeEntry {
+  /** The exported name a caller imports (an alias gets its own entry). */
+  name: string;
+  /** The lexicon that exports it. */
+  lexicon: string;
+  /** One line saying what it builds. */
+  description: string;
+  /** Resource kinds (the lexicon's class names) its members are, nested composites flattened. */
+  bundles: string[];
+  /** Its props, from the declared props type. */
+  params: CompositeParam[];
+  /** The component archetype that ships it, when that is known. */
+  archetype?: Archetype;
+}
+
 export interface LexiconPlugin {
   // ── Required ──────────────────────────────────────────────
   /** Human-readable name (e.g. "aws", "gcp") */
@@ -1212,6 +1252,13 @@ export interface LexiconPlugin {
   /** Generate documentation pages */
   docs?(options?: { verbose?: boolean }): Promise<void>;
 
+  /**
+   * The composites this lexicon exports, as static data (#2662). Read by the
+   * MCP `composites` tool, the `chant://composites` resource and `search`.
+   * Omit for a lexicon that exports no composites.
+   */
+  composites?(): CompositeEntry[];
+
   // MCP
   /** Return MCP tool contributions */
   mcpTools?(): McpToolContribution[];

package/src/lifecycle/gate-ledger.ts

@@ -47,6 +47,9 @@ import type { GateApprover, GatePolicyDecision, ResolvedGateApproval } from "../
 import { readBlobFromPath, readPathSha, readBlobBySha, writeBlobToPath, RefCASConflictError } from "./git";
 
 const DIR = "_gates";
+
+/** The directory on the `chant/lifecycle` branch that holds gate ledgers, under a member's prefix when it has one. */
+export const GATES_DIR = DIR;
 const APPEND_RETRY_ATTEMPTS = 5;
 
 /**
@@ -350,7 +353,18 @@ export async function readGateLedger(
 ): Promise<{ resolutions: GateResolutionRecord[]; pending: PendingGateRecord[]; malformed: number }> {
   const content = await readBlobFromPath(DIR, filename(op), opts);
   if (!content) return { resolutions: [], pending: [], malformed: 0 };
+  return parseGateLedger(content);
+}
 
+/**
+ * Split the text of one gate ledger file into its two kinds of line, oldest
+ * first, the way {@link readGateLedger} reads it. Exported for a reader that
+ * fetches the file itself, such as `chant workspace status` (#2674), which
+ * reads every member's ledger by its full path from the workspace root.
+ */
+export function parseGateLedger(
+  content: string,
+): { resolutions: GateResolutionRecord[]; pending: PendingGateRecord[]; malformed: number } {
   const lines = content.split("\n").map((l) => l.trim()).filter(Boolean);
   const resolutions: GateResolutionRecord[] = [];
   const pending: PendingGateRecord[] = [];

package/src/workspace/__fixtures__/contract-repo.ts

@@ -98,3 +98,20 @@ case "$1" in
   *) echo "Error: Unknown command: $1" >&2; exit 1 ;;
 esac
 `;
+
+/**
+ * A chant older than `workspace member-run` that answers from files (#2662):
+ * `chant graph --components` prints the member's `components.json`, or an
+ * empty IR when there is none, and plain `chant graph` prints `ir.json`. A
+ * `components.json` holding `FAIL` makes the component graph exit 1.
+ */
+export const FAKE_FILE_GRAPH_CHANT = `#!/bin/sh
+[ "$1" = graph ] || { echo "Error: Unknown command: $1" >&2; exit 1; }
+case " $* " in
+  *" --components "*)
+    if [ ! -f components.json ]; then printf '{"version":1,"nodes":[],"edges":[],"groups":{}}\\n'
+    elif grep -q FAIL components.json; then echo "Error: component discovery failed" >&2; exit 1
+    else cat components.json; fi ;;
+  *) cat ir.json ;;
+esac
+`;

package/src/workspace/__fixtures__/sessions.ts

@@ -0,0 +1,66 @@
+/**
+ * A repository with the reference workspace's decisions and design member,
+ * and helpers that write sessions and review entries into it, for the
+ * session and records --since tests (#2673).
+ */
+
+import { cpSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { sessionSeal } from "../record-sessions";
+import { commitAll, git, REPO, scratchDir } from "./contract-repo";
+
+export const SESSIONS_KIND = "design/sessions/session.kind.mjs";
+export const DECISIONS_KIND = "decisions/decision.kind.mjs";
+
+/** A git repository holding a copy of the reference workspace's decisions and design member. */
+export function sessionsRepo(): string {
+  const root = scratchDir("chant-sessions-");
+  for (const d of ["decisions", "design"]) cpSync(join(REPO, "reference-workspace", d), join(root, d), { recursive: true });
+  git(root, "init", "-q");
+  commitAll(root, "reference");
+  return root;
+}
+
+/** A session file's text, sealed when it is closed. */
+export function sessionText(s: { id: string; state: "open" | "closed"; verdicts?: { record: string; principal: string; verdict: string }[]; agenda?: string[] }): string {
+  const lines = [
+    "---",
+    "schema: 1",
+    `id: "${s.id}"`,
+    `title: "Session ${s.id}"`,
+    `state: "${s.state}"`,
+    "agenda:",
+    ...(s.agenda ?? ["ref-001"]).map((r) => `  - record: "${r}"`),
+    "attendance:",
+    '  - principal: "lex00"',
+    '    class: "person"',
+    '  - principal: "alice"',
+    '    class: "person"',
+    '  - principal: "helper"',
+    '    class: "agent"',
+    'opened: "2026-09-24T18:00:00Z"',
+    `closed: ${s.state === "closed" ? '"2026-09-24T19:00:00Z"' : "null"}`,
+    ...(s.verdicts?.length
+      ? ["verdicts:", ...s.verdicts.flatMap((v) => [`  - record: "${v.record}"`, `    principal: "${v.principal}"`, `    verdict: "${v.verdict}"`])]
+      : ["verdicts: []"]),
+    ...(s.state === "closed" ? ['closed_digest: "SEAL"'] : []),
+    "---",
+    "",
+    `# Session ${s.id}`,
+    "",
+  ];
+  const text = lines.join("\n");
+  return s.state === "closed" ? text.replace('"SEAL"', `"${sessionSeal(text, "closed_digest")}"`) : text;
+}
+
+/** Rewrite ref-001 with the given review entries, each naming `session`. */
+export function reviewed(root: string, reviewers: string[], session: string, state = "decided"): void {
+  const file = join(root, "decisions", "ref-001-how-the-app-is-deployed.md");
+  const reviews = reviewers.map((r) => `  - reviewer: "${r}"\n    verdict: "agree"\n    on: "2026-09-24"\n    session: "${session}"`).join("\n");
+  writeFileSync(
+    file,
+    readFileSync(file, "utf-8")
+      .replace(/^state: .*$/m, `state: "${state}"`)
+      .replace(/^reviews: .*$/m, reviewers.length ? `reviews:\n${reviews}` : "reviews: []"),
+  );
+}

package/src/workspace/checks/records.ts

@@ -13,6 +13,7 @@
  * | WSP112 | a pinned file that does not exist |
  * | WSP113 | a pinned file that a superseding record pins at the old hash: the artifact did not follow the decision |
  * | WSP114 | the records of `--kind` can't be read (fixed) |
+ * | WSP115 | a record kind the declaration names is missing or does not load as one (fixed, #2680) |
  */
 
 import type { WorkspaceCheck, WorkspaceDiagnostic } from "../checks";
@@ -80,4 +81,22 @@ export const RECORD_CHECKS: readonly WorkspaceCheck[] = [
       return [{ checkId: this.id, severity: this.severity, message: `--kind ${facts.kind}: ${facts.error.code}: ${facts.error.message}`, pointer: "" }];
     },
   },
+  {
+    id: "WSP115",
+    name: "record-kind-unloadable",
+    description: "Every record kind the declaration names is a file that exports a valid recordKind, with the schema it names.",
+    severity: "error",
+    configurable: false,
+    check(ctx) {
+      return (ctx.facts?.declaredKinds ?? [])
+        .filter((k) => k.reason !== null)
+        .map((k) => ({
+          checkId: this.id,
+          severity: this.severity,
+          message: `${k.declared.member === null ? "the workspace" : `member ${k.declared.member}`} declares the record kind ${k.declared.kind}, which can't be loaded: ${k.reason!.code}: ${k.reason!.message}`,
+          ...(k.declared.member !== null ? { entity: k.declared.member } : {}),
+          pointer: `${k.declared.pointer}/kind`,
+        }));
+    },
+  },
 ];

package/src/workspace/checks.test.ts

@@ -58,6 +58,8 @@ describe("the WSP catalog", () => {
       "link-kind-unknown",
       // --kind names a record kind, and records that can't be read check nothing (#2549).
       "records-unreadable",
+      // A declared record kind that doesn't load breaks every reader's default (#2680).
+      "record-kind-unloadable",
     ]);
   });
 

package/src/workspace/checks.ts

@@ -27,6 +27,7 @@
  * | WSP091 to WSP097 | member links (#2539) |
  * | WSP101 to WSP106 | generated files |
  * | WSP111 to WSP114 | records read with `--kind` (#2549) |
+ * | WSP115 | the record kinds the declaration names (#2680) |
  */
 
 import { realpathSync } from "node:fs";
@@ -44,6 +45,7 @@ import { gatherGeneratedFacts, GENERATED_CHECKS, type GeneratedFileFacts } from
 import { gatherLedgerFacts, LEDGER_CHECKS, type MemberLedgerFacts } from "./checks/ledgers";
 import { gatherPipelineFacts, PIPELINE_CHECKS, type MemberPipelineFacts } from "./checks/pipelines";
 import { RECORD_CHECKS, type RecordFacts } from "./checks/records";
+import { loadDeclaredKinds, type DeclaredKind } from "./declared-kinds";
 
 /**
  * What the checks beyond the declaration read, gathered from the checkout
@@ -59,6 +61,8 @@ export interface WorkspaceFacts {
   generated?: readonly GeneratedFileFacts[];
   /** The records of the kind named with `--kind`, with their pins checked (#2549). */
   records?: RecordFacts;
+  /** The record kinds the declaration names, each loaded, or only looked for under `--at` (#2680). */
+  declaredKinds?: readonly DeclaredKind[];
 }
 
 /** What every declaration check reads. */
@@ -444,7 +448,9 @@ export async function runDeclarationChecks(
   }
   const { registry, problems } = loadKindRegistry(declaration.pins, root);
   const gathered = options.gather === false || options.tree ? {} : await gatherWorkspaceFacts(root, declaration, options);
-  const facts: WorkspaceFacts = options.records ? { ...gathered, records: options.records } : gathered;
+  // The declared record kinds load from the working tree; under --at only whether each exists at the revision is checked (#2680).
+  const declaredKinds = options.gather === false ? undefined : await loadDeclaredKinds(declaration, tree, root, { load: !options.tree });
+  const facts: WorkspaceFacts = { ...gathered, ...(options.records ? { records: options.records } : {}), ...(declaredKinds ? { declaredKinds } : {}) };
   const ctx: WorkspaceCheckContext = { declaration, tree, groups, kinds: registry, kindProblems: problems, facts };
   const findings = runWorkspaceChecks(ctx);
   const { active, suppressed } = applyCheckSettings(declaration, findings);