@intentius/chant 0.85.0 → 0.87.0

package/src/workspace/composites.test.ts

@@ -7,7 +7,7 @@
  * (`read-contract.test.ts`).
  */
 
-import { writeFileSync } from "node:fs";
+import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { afterAll, describe, expect, test } from "vitest";
 import type { GraphIR, IRNode } from "../graph-ir";
@@ -18,6 +18,7 @@ import {
   COMPOSITES_ERROR_CODES,
   COMPOSITES_OUTPUT_SCHEMA_ID,
   COMPOSITES_REASON_CODES,
+  COMPOSITES_RUNTIME_REASON_CODES,
   compositeInstances,
   joinComponents,
   workspaceComposites,
@@ -54,6 +55,9 @@ const componentIr = (components: { name: string; composites?: string[]; archetyp
     { groups: { byWave: { "wave-1": components.map((c) => c.name) } } },
   );
 
+/** The built-in runtime every component has. */
+const local = (name: string) => ({ name: "local", lexicon: null, default: true, command: `chant run --components ${name}` });
+
 /**
  * app declares three instances and exports ImageUri; delivery links to it and
  * declares two components; jobs declares an instance and a component of its
@@ -106,6 +110,7 @@ describe("composites output schema", () => {
     expect(schema.$defs.failure.properties.error.properties.code.enum).toEqual([...COMPOSITES_ERROR_CODES]);
     expect(COMPOSITES_ERROR_CODES).toEqual(GRAPH_ERROR_CODES);
     expect(schema.$defs.member.properties.reason.oneOf[1].properties!.code.enum).toEqual([...MEMBER_RUN_REASON_CODES]);
+    expect(schema.$defs.member.properties.runtimeReasons.items.properties.code.enum).toEqual([...COMPOSITES_RUNTIME_REASON_CODES]);
   });
 });
 
@@ -117,7 +122,7 @@ describe("the join", () => {
       { ...composite("a/billingTable", "Table", "a/billing"), member: "a" },
     ],
   });
-  const component = (member: string, name: string, composites: string[] | null = null): ComponentEntry => ({ id: `${member}/${name}`, name, member, archetype: null, composites, file: null });
+  const component = (member: string, name: string, composites: string[] | null = null): ComponentEntry => ({ id: `${member}/${name}`, name, member, archetype: null, composites, file: null, runtimes: [] });
 
   test("an instance carries every kind and lexicon of its nodes", () => {
     expect(instances.map((i) => [i.id, i.instance, i.kinds, i.lexicons])).toEqual([
@@ -160,9 +165,9 @@ describe("chant workspace graph --composites on a built workspace", () => {
       ["docs", "skipped", "kind-not-run"],
     ]);
     expect(g.components).toEqual([
-      { id: "delivery/edge", name: "edge", member: "delivery", archetype: "infra", composites: ["StaticSite"], file: "delivery/src/edge.component.ts" },
-      { id: "delivery/loom-backend", name: "loom-backend", member: "delivery", archetype: "service", composites: null, file: "delivery/src/loom-backend.component.ts" },
-      { id: "jobs/queue-runner", name: "queue-runner", member: "jobs", archetype: null, composites: ["WorkQueue", "CacheCluster"], file: "jobs/src/queue-runner.component.ts" },
+      { id: "delivery/edge", name: "edge", member: "delivery", archetype: "infra", composites: ["StaticSite"], file: "delivery/src/edge.component.ts", runtimes: [local("edge")] },
+      { id: "delivery/loom-backend", name: "loom-backend", member: "delivery", archetype: "service", composites: null, file: "delivery/src/loom-backend.component.ts", runtimes: [local("loom-backend")] },
+      { id: "jobs/queue-runner", name: "queue-runner", member: "jobs", archetype: null, composites: ["WorkQueue", "CacheCluster"], file: "jobs/src/queue-runner.component.ts", runtimes: [local("queue-runner")] },
     ]);
     const rows = Object.fromEntries(g.composites.map((c) => [c.id, c]));
     expect(Object.keys(rows)).toEqual(["app/backend", "app/cache", "app/site", "jobs/queue"]);
@@ -242,3 +247,88 @@ describe("why the list is empty", () => {
     expect("error" in doc && doc.error.code).toBe("declaration-missing");
   });
 });
+
+/** A lexicon module: a LexiconPlugin export, with `opRuntime` when `runtime` says what it hosts. */
+function lexiconModule(name: string, runtime: "components" | "ops" | "none"): string {
+  const opRuntime =
+    runtime === "none"
+      ? ""
+      : `opRuntime: { name: ${JSON.stringify(name)}, start: async () => { throw new Error("stub"); }${runtime === "components" ? ", runComponents: async () => ({ success: true })" : ""} },`;
+  return `const noop = async () => {};
+export const plugin = { name: ${JSON.stringify(name)}, serializer: {}, generate: noop, validate: noop, coverage: noop, package: noop, ${opRuntime} };
+`;
+}
+
+describe("the runtimes each component can deploy on (#2674)", () => {
+  /** delivery configures four lexicons: one hosts component runs, one hosts only Op runs, one hosts nothing, one can't load. */
+  function hosting(): string {
+    const root = fixture();
+    writeFileSync(
+      join(root, "delivery", "chant.config.ts"),
+      `export default {
+  lexicons: [
+    { name: "fleet", module: "./lexicons/fleet.ts" },
+    { name: "oponly", module: "./lexicons/oponly.ts" },
+    { name: "plain", module: "./lexicons/plain.ts" },
+    { name: "gone", module: "./lexicons/gone.ts" },
+  ],
+};
+`,
+    );
+    mkdirSync(join(root, "delivery", "lexicons"));
+    writeFileSync(join(root, "delivery", "lexicons", "fleet.ts"), lexiconModule("fleet", "components"));
+    writeFileSync(join(root, "delivery", "lexicons", "oponly.ts"), lexiconModule("oponly", "ops"));
+    writeFileSync(join(root, "delivery", "lexicons", "plain.ts"), lexiconModule("plain", "none"));
+    return root;
+  }
+
+  test("local is the default, and a configured lexicon whose opRuntime hosts component runs is listed with its --on line", async () => {
+    const g = result((await workspaceComposites({ cwd: hosting() })).doc);
+    expectValid(g);
+    const edge = g.components.find((c) => c.id === "delivery/edge")!;
+    expect(edge.runtimes).toEqual([
+      { name: "local", lexicon: null, default: true, command: "chant run --components edge" },
+      { name: "fleet", lexicon: "fleet", default: false, command: "chant run --components edge --on fleet" },
+    ]);
+    expect(g.components.find((c) => c.id === "delivery/loom-backend")!.runtimes.map((r) => r.command)).toEqual([
+      "chant run --components loom-backend",
+      "chant run --components loom-backend --on fleet",
+    ]);
+    // jobs configures no lexicon, so only local.
+    expect(g.components.find((c) => c.id === "jobs/queue-runner")!.runtimes).toEqual([local("queue-runner")]);
+    const delivery = g.members.find((m) => m.name === "delivery")!;
+    expect(delivery.runtimeReasons.map((r) => r.code)).toEqual(["runtimes-lexicon-unreadable"]);
+    expect(delivery.runtimeReasons[0].message).toContain('lexicon "gone"');
+    expect(g.members.find((m) => m.name === "docs")!.runtimeReasons).toEqual([]);
+  });
+
+  test("a member whose config can't be read lists local only, with a reason", async () => {
+    const root = fixture();
+    writeFileSync(join(root, "jobs", "chant.config.ts"), 'throw new Error("no config here");\nexport default {};\n');
+    const { doc, failed } = await workspaceComposites({ cwd: root, loadPlugin: async () => { throw new Error("not called"); } });
+    const g = result(doc);
+    expectValid(g);
+    expect(failed).toBe(false);
+    const jobs = g.members.find((m) => m.name === "jobs")!;
+    expect(jobs.runtimeReasons).toEqual([{ code: "runtimes-config-unreadable", message: expect.stringContaining("no config here") }]);
+    expect(g.components.find((c) => c.id === "jobs/queue-runner")!.runtimes).toEqual([local("queue-runner")]);
+  });
+
+  test("the plugin loader decides from opRuntime.runComponents alone", async () => {
+    const root = fixture();
+    writeFileSync(join(root, "jobs", "chant.config.ts"), 'export default { lexicons: ["hosted", "bare"] };\n');
+    const g = result(
+      (
+        await workspaceComposites({
+          cwd: root,
+          loadPlugin: async (name) => (name === "hosted" ? { opRuntime: { runComponents: () => undefined } } : {}),
+        })
+      ).doc,
+    );
+    expectValid(g);
+    expect(g.components.find((c) => c.id === "jobs/queue-runner")!.runtimes.map((r) => [r.name, r.lexicon, r.default])).toEqual([
+      ["local", null, true],
+      ["hosted", "hosted", false],
+    ]);
+  });
+});

package/src/workspace/composites.ts

@@ -28,6 +28,10 @@
  *
  * Each member runs under its own toolchain, as for `workspace graph`, and at
  * the same revision with `--at`. Nothing is written and no listener starts.
+ *
+ * Each component also lists the runtimes it can deploy on (#2674,
+ * `runtimes.ts`): `local`, and each lexicon its member configures that hosts
+ * `chant run --components`, with the command line for each.
  */
 
 import { formatError } from "../cli/format";
@@ -40,6 +44,7 @@ import type { LinkRow } from "./links";
 import { emitDocument, type UnitResult } from "./member-commands";
 import { readerVersion, type ErrorLocation, type WorkspaceErrorCode } from "./declaration";
 import type { ReasonCode } from "./reason-codes";
+import { componentRuntimes, readRuntimesIn, RUNTIME_REASON_CODES, type ComponentRuntime, type MemberRuntimes, type PluginLoader, type RuntimeReason } from "./runtimes";
 
 /** `$id` of the JSON Schema for the document, shipped beside this file. */
 export const COMPOSITES_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/composites/v1/composites.schema.json";
@@ -61,6 +66,9 @@ export const COMPOSITES_REASON_CODES = [
 ] as const satisfies readonly ReasonCode[];
 export type CompositesReasonCode = (typeof COMPOSITES_REASON_CODES)[number];
 
+/** Why a member's runtimes are only `local`, or leave out a lexicon its config lists (#2674). Closed. */
+export const COMPOSITES_RUNTIME_REASON_CODES = RUNTIME_REASON_CODES;
+
 export interface CompositesMember {
   name: string;
   dir: string;
@@ -69,6 +77,8 @@ export interface CompositesMember {
   status: "read" | "skipped" | "failed";
   reason: MemberReason | null;
   chant: string | null;
+  /** Why its components' runtimes leave something out: its config, or a lexicon, couldn't be read. Empty for a member not of kind chant. */
+  runtimeReasons: RuntimeReason[];
 }
 
 export interface ComponentEntry {
@@ -82,6 +92,8 @@ export interface ComponentEntry {
   composites: string[] | null;
   /** The component's file from the workspace root, when the member's chant names it. */
   file: string | null;
+  /** The runtimes it can deploy on: `local` first, then each hosting lexicon its member configures. */
+  runtimes: ComponentRuntime[];
 }
 
 export interface ComponentMatch {
@@ -133,7 +145,7 @@ export interface CompositesResult {
 }
 
 /** Read one member's component graph run into components, or the reason it can't be read. */
-function readComponents(member: string, dir: string, run: UnitResult): { components: ComponentEntry[] } | { reason: MemberReason } {
+function readComponents(member: string, dir: string, run: UnitResult, runtimes: MemberRuntimes | undefined): { components: ComponentEntry[] } | { reason: MemberReason } {
   if (run.exitCode !== 0) {
     const tail = run.stderr.trim().split("\n").slice(-5).join("\n");
     return { reason: { code: "command-failed", message: `chant graph --components exited ${run.exitCode}${tail ? `: ${tail}` : ""}` } };
@@ -153,6 +165,7 @@ function readComponents(member: string, dir: string, run: UnitResult): { compone
       archetype: typeof attrs.archetype === "string" ? attrs.archetype : null,
       composites: composites && composites.length > 0 ? composites : null,
       file: file ? (dir === "." ? file : `${dir}/${file}`) : null,
+      runtimes: componentRuntimes(n.id, runtimes),
     });
   }
   return { components };
@@ -220,16 +233,24 @@ export function joinComponents(instances: CompositeInstanceRow[], components: Co
   });
 }
 
-function memberEntry(m: ComposedMember, componentReason: MemberReason | null): CompositesMember {
+function memberEntry(m: ComposedMember, componentReason: MemberReason | null, runtimes: MemberRuntimes | undefined): CompositesMember {
   const reason = m.reason ?? componentReason;
   const status = m.status === "composed" ? (componentReason ? "failed" : "read") : m.status;
-  return { name: m.name, dir: m.dir, kind: m.kind, status, reason, chant: m.chant };
+  return { name: m.name, dir: m.dir, kind: m.kind, status, reason, chant: m.chant, runtimeReasons: runtimes?.reasons ?? [] };
 }
 
 /** Read the workspace's composites and components, and build the document. Never throws a `WorkspaceReadError`. */
-export async function workspaceComposites(query: Omit<GraphQuery, "kind" | "components">): Promise<CompositesResult> {
+export async function workspaceComposites(query: Omit<GraphQuery, "kind" | "components" | "inTree"> & { loadPlugin?: PluginLoader }): Promise<CompositesResult> {
   const head: Head = { $schema: COMPOSITES_OUTPUT_SCHEMA_ID, contract: COMPOSITES_CONTRACT_VERSION, chant: readerVersion() };
-  const { doc: graph, failed, components: runs } = await workspaceGraph({ ...query, components: true });
+  let runtimes = new Map<string, MemberRuntimes>();
+  const { loadPlugin, ...graphQuery } = query;
+  const { doc: graph, failed, components: runs } = await workspaceGraph({
+    ...graphQuery,
+    components: true,
+    inTree: async (root, members) => {
+      runtimes = await readRuntimesIn(root, members, loadPlugin);
+    },
+  });
   if ("error" in graph) return { doc: { ...head, error: graph.error }, failed: true };
 
   const byMember = new Map((runs ?? []).map((r) => [r.unit.member, r]));
@@ -240,13 +261,13 @@ export async function workspaceComposites(query: Omit<GraphQuery, "kind" | "comp
     const run = m.status === "composed" ? byMember.get(m.name) : undefined;
     let reason: MemberReason | null = null;
     if (run) {
-      const read = readComponents(m.name, m.dir, run);
+      const read = readComponents(m.name, m.dir, run, runtimes.get(m.name));
       if ("reason" in read) {
         reason = read.reason;
         componentsFailed = true;
       } else components.push(...read.components);
     }
-    members.push(memberEntry(m, reason));
+    members.push(memberEntry(m, reason, runtimes.get(m.name)));
   }
   components.sort((a, b) => a.id.localeCompare(b.id));
 

package/src/workspace/conformance/__fixture__/app/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "app",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "The reader conformance workspace's product: the handler of a small web app."
+}

package/src/workspace/conformance/__fixture__/app/src/server.mjs

@@ -0,0 +1,29 @@
+// The reader conformance workspace's product (#2679): the request handler of
+// a small web app, with no dependencies. The suite reads
+// `graph --intent app/src/server.mjs:19`, so line 19 is the home page's
+// status line, as it is in chant's reference-workspace/app/src/server.mjs.
+// Nothing here opens a port: chant's own packages never listen (#2657), and
+// this file ships in one.
+
+/** The app's display name. */
+export const APP_NAME = "Conformance app";
+
+/** The home page. */
+export const HOME = `<!doctype html>
+<html lang="en">
+<head><meta charset="utf-8"><title>${APP_NAME}</title></head>
+<body>
+<header><h1>${APP_NAME}</h1></header>
+<main>
+<!-- the status line -->
+<p id="status">Running.</p>
+</main>
+</body>
+</html>
+`;
+
+/** Answer one request with a status and a body. */
+export function handle(url) {
+  if (url === "/healthz") return { status: 200, type: "application/json", body: JSON.stringify({ ok: true }) };
+  return { status: 200, type: "text/html; charset=utf-8", body: HOME };
+}

package/src/workspace/conformance/__fixture__/decisions/decision.kind.mjs

@@ -0,0 +1,32 @@
+// The decision record kind (#2555), data only: no imports, no code.
+//
+// chant workspace records --kind decisions/decision.kind.mjs --current --json
+//
+// A copy of docs/design/decisions/decision.kind.mjs in the chant repo, with
+// decision.schema.json beside it, so a workspace made from this one reads its
+// decisions without the chant repo. chant's test/reference-workspace.test.ts fails
+// when this kind's data or the schema drifts from chant's.
+export const recordKind = {
+  name: "decision",
+  location: { dir: ".", match: "^[a-z][a-z0-9]{0,15}-[0-9]{3,}-.+\\.md$" },
+  format: "markdown-front-matter",
+  schema: { id: "urn:intentius:chant:decision:1", path: "decision.schema.json" },
+  idField: "id",
+  stateField: "state",
+  states: ["proposed", "decided", "ratified", "superseded", "withdrawn"],
+  // Sealed once reached (#2555).
+  closedStates: ["ratified", "superseded"],
+  supersedes: { field: "supersedes", key: "decision" },
+  // A supersedes link takes effect under an equal or stricter approval rule
+  // (#2524 D4): from a record ranked above 0 and at least as high as the one it
+  // names. A decided record supersedes a decided or proposed one, a ratified
+  // record supersedes any, and a proposed or withdrawn record none.
+  approval: { proposed: 0, withdrawn: 0, decided: 1, ratified: 2, superseded: 2 },
+  // Evidence entries with a path pin a workspace file by the hash of its bytes (#2549).
+  pins: { field: "evidence" },
+  // member:<name> and path:<path> entries are the record's links in workspace graph (#2549).
+  constrains: { field: "constrains" },
+  // Verdicts, and the field naming the decider, for each record's digest and
+  // quorum (#2671, #2672).
+  reviews: { field: "reviews", decider: "decided_by" },
+};