@intentius/chant 0.79.0 → 0.81.0

package/src/workspace/member-handles.ts

@@ -0,0 +1,228 @@
+/**
+ * A chant member's outputs and parameters, read from its source without
+ * running it (#2539, #2524 D6).
+ *
+ * `chant workspace check` resolves member links in source and never runs
+ * member code, so it can't build a member to learn its outputs. This reader
+ * parses the member's TypeScript files and picks out the two handles a join
+ * uses, the way the graph IR names them (`exports` and `imports`):
+ *
+ * - an output is the name passed to `output(ref, "Name")`, or the binding of
+ *   `export const name = stackOutput(ref)`;
+ * - a parameter is the binding of `export const name = new Parameter(...)`.
+ *
+ * Only calls whose function is imported from `@intentius/chant` or a chant
+ * lexicon count. An output name must be a string literal, or a `const` in the
+ * same file that is one. Any other name can't be read without running the
+ * code, so it is a gap: the member's list of outputs is then incomplete, and a
+ * link to a name the reader didn't find is unresolved rather than missing.
+ *
+ * The reader loads the TypeScript parser and nothing else from the project.
+ */
+
+import * as ts from "typescript";
+import { isInside, type Declaration, type ResolvedGroup } from "./declaration";
+import type { KindRegistry } from "./kinds";
+import { kindHandles, type MemberHandles } from "./links";
+import { joinPath, skippedDir, type WorkspaceTree } from "./tree";
+
+const memberDir = (dir: string) => (dir === "." ? "" : dir);
+
+/** One output or parameter found in source. */
+export interface SourceHandle {
+  name: string;
+  /** Tree-relative file and 1-based line, for messages. */
+  file: string;
+  line: number;
+}
+
+export interface SourceHandles {
+  outputs: SourceHandle[];
+  /** Parameters: the names a consumer reads from outside. */
+  inputs: SourceHandle[];
+  /** Why the list of outputs may be incomplete, one line each. Empty when it is complete. */
+  gaps: string[];
+}
+
+/** Directories inside a member that hold no project source. */
+const NOT_SOURCE = new Set(["dist", "coverage", "generated"]);
+
+const CHANT_MODULE = /^@intentius\/chant(-lexicon-[a-z0-9-]+)?(\/.*)?$/;
+
+function isSourceFile(name: string): boolean {
+  if (!/\.(m?ts|tsx)$/.test(name) || name.endsWith(".d.ts")) return false;
+  if (/\.(test|spec)\.m?tsx?$/.test(name)) return false;
+  return !name.startsWith("chant.config.");
+}
+
+/**
+ * Every source file under `dir` (tree-relative), leaving out `exclude`d
+ * directories (other members, group matches), `node_modules`, dot
+ * directories and build output.
+ */
+function sourceFiles(tree: WorkspaceTree, dir: string, exclude: ReadonlySet<string>): string[] {
+  const out: string[] = [];
+  const walk = (at: string) => {
+    for (const e of tree.list(at) ?? []) {
+      const path = joinPath(at, e.name);
+      if (e.type === "dir") {
+        if (skippedDir(e.name) || NOT_SOURCE.has(e.name) || exclude.has(path)) continue;
+        walk(path);
+      } else if (isSourceFile(e.name)) {
+        out.push(path);
+      }
+    }
+  };
+  walk(dir);
+  return out.sort();
+}
+
+/** The chant functions a file imports, by local name, and the namespaces it imports chant modules as. */
+interface ChantImports {
+  names: Map<string, string>;
+  namespaces: Set<string>;
+}
+
+function chantImports(source: ts.SourceFile): ChantImports {
+  const names = new Map<string, string>();
+  const namespaces = new Set<string>();
+  for (const s of source.statements) {
+    if (!ts.isImportDeclaration(s) || !ts.isStringLiteral(s.moduleSpecifier)) continue;
+    const from = s.moduleSpecifier.text;
+    // The components API has its own stackOutput(stack, name), which reads an output rather than declaring one.
+    if (!CHANT_MODULE.test(from) || from.includes("/components")) continue;
+    const bindings = s.importClause?.namedBindings;
+    if (!bindings) continue;
+    if (ts.isNamespaceImport(bindings)) namespaces.add(bindings.name.text);
+    else for (const el of bindings.elements) names.set(el.name.text, (el.propertyName ?? el.name).text);
+  }
+  return { names, namespaces };
+}
+
+/** The chant function a callee names (`output`, `ns.Parameter`), or undefined. */
+function chantCallee(expr: ts.Expression, imports: ChantImports): string | undefined {
+  if (ts.isIdentifier(expr)) return imports.names.get(expr.text);
+  if (ts.isPropertyAccessExpression(expr) && ts.isIdentifier(expr.expression) && imports.namespaces.has(expr.expression.text)) {
+    return expr.name.text;
+  }
+  return undefined;
+}
+
+/** The top-level `const` initializers of a file, for reading a name held in one. */
+function fileConsts(source: ts.SourceFile): Map<string, ts.Expression> {
+  const consts = new Map<string, ts.Expression>();
+  for (const s of source.statements) {
+    if (!ts.isVariableStatement(s) || (s.declarationList.flags & ts.NodeFlags.Const) === 0) continue;
+    for (const d of s.declarationList.declarations) if (ts.isIdentifier(d.name) && d.initializer) consts.set(d.name.text, d.initializer);
+  }
+  return consts;
+}
+
+/** A string the expression is without running anything, or undefined. */
+function literalString(expr: ts.Expression, consts: Map<string, ts.Expression>, seen = new Set<string>()): string | undefined {
+  if (ts.isStringLiteral(expr) || ts.isNoSubstitutionTemplateLiteral(expr)) return expr.text;
+  if (ts.isParenthesizedExpression(expr) || ts.isAsExpression(expr) || ts.isSatisfiesExpression(expr)) return literalString(expr.expression, consts, seen);
+  if (ts.isIdentifier(expr) && !seen.has(expr.text)) {
+    const init = consts.get(expr.text);
+    if (init) return literalString(init, consts, new Set([...seen, expr.text]));
+  }
+  return undefined;
+}
+
+function isExported(s: ts.Statement): boolean {
+  return (ts.canHaveModifiers(s) ? ts.getModifiers(s) : undefined)?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+}
+
+/** Read one file's outputs and parameters into `out`. */
+function readFile(path: string, text: string, out: SourceHandles): void {
+  const source = ts.createSourceFile(path, text, ts.ScriptTarget.Latest, false);
+  const imports = chantImports(source);
+  if (imports.names.size === 0 && imports.namespaces.size === 0) return;
+  const consts = fileConsts(source);
+  const lineOf = (node: ts.Node) => source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1;
+
+  // Exported bindings: stackOutput outputs and Parameter inputs are named by them.
+  for (const s of source.statements) {
+    if (!ts.isVariableStatement(s) || !isExported(s)) continue;
+    for (const d of s.declarationList.declarations) {
+      if (!ts.isIdentifier(d.name) || !d.initializer) continue;
+      const init = d.initializer;
+      if (ts.isNewExpression(init) && chantCallee(init.expression, imports) === "Parameter") {
+        out.inputs.push({ name: d.name.text, file: path, line: lineOf(d) });
+      } else if (ts.isCallExpression(init) && chantCallee(init.expression, imports) === "stackOutput") {
+        const first = init.arguments[0];
+        if (first && !ts.isStringLiteralLike(first)) out.outputs.push({ name: d.name.text, file: path, line: lineOf(d) });
+      }
+    }
+  }
+
+  // output(ref, "Name") anywhere in the file.
+  const visit = (node: ts.Node) => {
+    if (ts.isCallExpression(node) && chantCallee(node.expression, imports) === "output" && node.arguments.length >= 2) {
+      const name = literalString(node.arguments[1], consts);
+      if (name !== undefined) out.outputs.push({ name, file: path, line: lineOf(node) });
+      else out.gaps.push(`${path}:${lineOf(node)}: an output whose name is not a string literal`);
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+}
+
+/**
+ * Read a chant member's outputs and parameters from the source under `dir`
+ * (tree-relative, `""` for the root), leaving out the `exclude`d directories.
+ * Runs no member code.
+ */
+export function readSourceHandles(tree: WorkspaceTree, dir: string, exclude: ReadonlySet<string> = new Set()): SourceHandles {
+  const out: SourceHandles = { outputs: [], inputs: [], gaps: [] };
+  for (const file of sourceFiles(tree, dir, exclude)) {
+    let text: string;
+    try {
+      text = tree.read(file);
+    } catch {
+      out.gaps.push(`${file}: the file could not be read`);
+      continue;
+    }
+    readFile(file, text, out);
+  }
+  return out;
+}
+
+/**
+ * Every member's handles, read in source for `chant workspace check`. A
+ * `chant` member's outputs and parameters are parsed from its TypeScript
+ * without running it; other kinds expose what the kind and the entry list.
+ * A member whose directory is missing or whose kind is unknown is left out,
+ * so links to it are unresolved.
+ */
+export function sourceMemberHandles(
+  declaration: Declaration,
+  tree: WorkspaceTree,
+  groups: readonly ResolvedGroup[],
+  kinds: KindRegistry,
+): Map<string, MemberHandles> {
+  const out = new Map<string, MemberHandles>();
+  for (const m of declaration.members) {
+    const kind = kinds.get(m.kind);
+    if (!kind || tree.stat(memberDir(m.dir)) !== "dir") continue;
+    const listed = kindHandles(m, kind);
+    if (listed) {
+      out.set(m.name, listed);
+    } else {
+      // Other members' directories and group matches inside this one are not its source.
+      const exclude = new Set<string>();
+      for (const o of declaration.members) if (o !== m && o.dir !== "." && isInside(o.dir, m.dir)) exclude.add(o.dir);
+      for (const g of groups) for (const dir of g.matches) if (isInside(dir, m.dir)) exclude.add(dir);
+      const read = readSourceHandles(tree, memberDir(m.dir), exclude);
+      out.set(m.name, {
+        member: m.name,
+        outputs: read.outputs.map((o) => ({ name: o.name })),
+        inputs: read.inputs.map((i) => ({ name: i.name })),
+        complete: read.gaps.length === 0,
+        why: read.gaps.length === 0 ? null : read.gaps.length === 1 ? read.gaps[0] : `${read.gaps[0]}, and ${read.gaps.length - 1} more`,
+        exposesNone: false,
+      });
+    }
+  }
+  return out;
+}

package/src/workspace/member-pipeline.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Per-member pipelines (#2542): which member a project belongs to, where its
+ * pipeline goes, the command that regenerates it, and the interim record of
+ * generated files (`.chant/generated.json`, until #2541).
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { twoMemberWorkspace } from "./__fixtures__/two-member-workspace";
+import { findWorkspaceRoot } from "../project-root";
+import {
+  GENERATED_RECORD_FILE,
+  memberPipelineFile,
+  planMemberComponentPipeline,
+  planMemberOpPipelines,
+  readGeneratedRecord,
+  recordGeneratedFiles,
+  resolveMemberContext,
+  writeMemberComponentPipeline,
+} from "./member-pipeline";
+
+let repo: string;
+beforeEach(() => {
+  repo = twoMemberWorkspace();
+});
+afterEach(() => {
+  rmSync(repo, { recursive: true, force: true });
+});
+
+function context(dir: string) {
+  const found = findWorkspaceRoot(dir);
+  expect(found).toBeDefined();
+  return resolveMemberContext(dir, found!);
+}
+
+describe("which member a project belongs to", () => {
+  test("the member's directory and anything under it", () => {
+    expect(context(join(repo, "services/api"))?.pipeline).toEqual({ name: "api", dir: "services/api" });
+    expect(context(join(repo, "services/api/src"))?.member.name).toBe("api");
+    expect(context(join(repo, "apps/web"))?.pipeline).toEqual({ name: "web", dir: "apps/web" });
+  });
+
+  test("an example group's match and a directory no member holds are no member", () => {
+    expect(context(join(repo, "examples/demo"))).toBeUndefined();
+    expect(context(repo)).toBeUndefined();
+  });
+
+  test("a root member excludes the other members and the group matches", () => {
+    rmSync(repo, { recursive: true, force: true });
+    repo = twoMemberWorkspace({ root: true });
+    expect(context(repo)?.pipeline).toEqual({ name: "platform", dir: ".", exclude: ["apps/web", "examples/demo", "services/api"] });
+    expect(context(join(repo, "services/api"))?.member.name).toBe("api");
+  });
+
+  test("a workspace below the repository root gives repository-relative directories", () => {
+    rmSync(repo, { recursive: true, force: true });
+    repo = twoMemberWorkspace({ prefix: "estate" });
+    const ctx = context(join(repo, "estate/services/api"));
+    expect(ctx?.pipeline).toEqual({ name: "api", dir: "estate/services/api" });
+    expect(ctx?.repoRoot).toBe(repo);
+  });
+});
+
+describe("the component pipeline's file and command", () => {
+  test("default files are named after the member and the environment, at the forge's path", () => {
+    expect(memberPipelineFile("github", "api", "staging")).toBe(".github/workflows/chant-api-staging.yml");
+    expect(memberPipelineFile("forgejo", "api", "staging")).toBe(".forgejo/workflows/chant-api-staging.yml");
+    expect(memberPipelineFile("gitlab", "api", "staging")).toBe(".gitlab/ci/chant-api-staging.gitlab-ci.yml");
+    expect(memberPipelineFile("jenkins", "api", "staging")).toBeUndefined();
+  });
+
+  test("the plan names the file, and the command runs in the member's directory", () => {
+    const dir = join(repo, "services/api");
+    const plan = planMemberComponentPipeline({ projectDir: dir, found: findWorkspaceRoot(dir)!, lexicon: "github", env: "staging", promoteTo: "prod" })!;
+    expect(plan.file).toBe(".github/workflows/chant-api-staging.yml");
+    expect(plan.target).toBe(join(repo, ".github/workflows/chant-api-staging.yml"));
+    expect(plan.member).toEqual({ name: "api", dir: "services/api", file: ".github/workflows/chant-api-staging.yml" });
+    expect(plan.command).toBe("chant build --components --generate github --env staging --promote-to prod");
+  });
+
+  test("--output keeps the path, relative to the member in the command", () => {
+    const dir = join(repo, "services/api");
+    const plan = planMemberComponentPipeline({
+      projectDir: dir,
+      found: findWorkspaceRoot(dir)!,
+      lexicon: "gitlab",
+      output: join(repo, "ci/api.yml"),
+    })!;
+    expect(plan.file).toBe("ci/api.yml");
+    expect(plan.command).toBe("chant build --components --generate gitlab --env production --output ../../ci/api.yml");
+  });
+
+  test("a forge with no default path needs --output", () => {
+    const dir = join(repo, "services/api");
+    expect(() => planMemberComponentPipeline({ projectDir: dir, found: findWorkspaceRoot(dir)!, lexicon: "jenkins" })).toThrow(/pass --output/);
+  });
+
+  test("writing puts the header on the file and records it under the member", () => {
+    const dir = join(repo, "services/api");
+    const plan = planMemberComponentPipeline({ projectDir: dir, found: findWorkspaceRoot(dir)!, lexicon: "github", env: "staging" })!;
+    writeMemberComponentPipeline(plan, "name: x\n");
+    const written = readFileSync(plan.target, "utf-8");
+    expect(written.split("\n")[0]).toBe(
+      "# Generated by chant — do not edit directly. Regenerate with: chant build --components --generate github --env staging (in the member's directory)",
+    );
+    expect(written.endsWith("name: x\n")).toBe(true);
+    expect(readGeneratedRecord(dir)).toEqual({
+      schema: 1,
+      files: [{ path: ".github/workflows/chant-api-staging.yml", command: "chant build --components --generate github --env staging", env: "staging" }],
+    });
+    expect(existsSync(join(dir, GENERATED_RECORD_FILE))).toBe(true);
+  });
+});
+
+describe("the Op pipelines' directory and command", () => {
+  test("files go to the forge's directory at the repository root", () => {
+    const dir = join(repo, "apps/web");
+    const plan = planMemberOpPipelines({ projectDir: dir, found: findWorkspaceRoot(dir)!, provider: "gitlab", specFile: join(dir, "ops.json") })!;
+    expect(plan.outDir).toBe(join(repo, ".gitlab/ci"));
+    expect(plan.member).toEqual({ name: "web", dir: "apps/web", fileDir: ".gitlab/ci" });
+    expect(plan.command).toBe("chant run --generate gitlab --spec ops.json");
+  });
+});
+
+describe("the generated-file record", () => {
+  test("entries are keyed by path and sorted, so regenerating leaves the file unchanged", () => {
+    const dir = join(repo, "apps/web");
+    recordGeneratedFiles(dir, [{ path: "b.yml", command: "x" }, { path: "a.yml", command: "y" }]);
+    const first = readFileSync(join(dir, GENERATED_RECORD_FILE), "utf-8");
+    recordGeneratedFiles(dir, [{ path: "a.yml", command: "y" }]);
+    expect(readFileSync(join(dir, GENERATED_RECORD_FILE), "utf-8")).toBe(first);
+    expect(readGeneratedRecord(dir).files.map((f) => f.path)).toEqual(["a.yml", "b.yml"]);
+  });
+});

package/src/workspace/member-pipeline.ts

@@ -0,0 +1,317 @@
+/**
+ * Per-member CI pipelines (#2542; #2524 D19, ws-041 and ws-042).
+ *
+ * When `chant build --components --generate` or `chant run --generate` runs
+ * for a project inside a workspace member, the generator is told which
+ * member it is generating for ({@link PipelineMember}). The generated
+ * pipeline is then filtered to the member's paths, its jobs run in the
+ * member's directory, and its file is named after the member so two members
+ * never write the same file.
+ *
+ * Forges read CI files from fixed paths at the repository root, outside any
+ * member's directory. The member whose command generates such a file owns
+ * it (ws-042), and records it in its list of generated files. That list
+ * belongs in the member's `generated` entry in `chant.workspace.json` once
+ * #2541 lands. Until then it is `.chant/generated.json` in the member's
+ * directory ({@link GENERATED_RECORD_FILE}), which `WSP081` reads to allow
+ * one declarer per file (./checks/pipelines.ts).
+ *
+ * The command handlers import this module only after `findWorkspaceRoot`
+ * has found a declaration, so a project outside any workspace never loads it.
+ */
+
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { GENERATED_MARKER } from "../discovery/files";
+import type { PipelineMember } from "../lexicon";
+import type { WorkspaceRootSearch } from "../project-root";
+import { ownerOf, readDeclaration, resolveGroups, rootExclusions, WorkspaceReadError, type Declaration, type Member } from "./declaration";
+import { gitTop, workingTree } from "./tree";
+
+/**
+ * TODO(#2541): the interim home of a member's generated-file list, relative
+ * to the member's directory. #2541 moves the list into the member's entry in
+ * the declaration, and this file goes away.
+ */
+export const GENERATED_RECORD_FILE = ".chant/generated.json";
+
+/** One generated file a member owns. */
+export interface GeneratedFileEntry {
+  /** The file, relative to the repository root, with `/` separators. */
+  path: string;
+  /** The command that regenerates it, run in the member's directory. */
+  command: string;
+  /** The environment the pipeline deploys, for a component pipeline. */
+  env?: string;
+}
+
+export interface GeneratedRecord {
+  schema: 1;
+  files: GeneratedFileEntry[];
+}
+
+/** The member a project belongs to, and where it sits. */
+export interface MemberContext {
+  declaration: Declaration;
+  member: Member;
+  /** Absolute path of the workspace root. */
+  workspaceRoot: string;
+  /** Absolute path of the repository root: the git top, or the workspace root outside git. */
+  repoRoot: string;
+  /** Absolute path of the member's directory. */
+  memberRoot: string;
+  /** What the generators read: name, repository-relative directory and exclusions. */
+  pipeline: PipelineMember;
+}
+
+function real(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve(path);
+  }
+}
+
+/** `path` relative to `from`, `/`-separated, `"."` for `from` itself. */
+function relPath(from: string, path: string): string {
+  const rel = relative(from, path).split(sep).join("/");
+  return rel === "" ? "." : rel;
+}
+
+function joinRel(prefix: string, dir: string): string {
+  if (prefix === ".") return dir;
+  return dir === "." ? prefix : `${prefix}/${dir}`;
+}
+
+/**
+ * The member that owns `projectDir`, given the declaration `findWorkspaceRoot`
+ * found. Undefined when no member owns it: the directory sits in an example
+ * group's match, or outside every member of a workspace with no root member.
+ * Throws `WorkspaceReadError` when the declaration can't be read.
+ */
+export function resolveMemberContext(projectDir: string, found: WorkspaceRootSearch): MemberContext | undefined {
+  const workspaceRoot = real(found.dir);
+  const tree = workingTree(workspaceRoot);
+  const declaration = readDeclaration(tree);
+  const groups = resolveGroups(declaration, tree);
+  const at = relPath(workspaceRoot, real(projectDir));
+  if (at.startsWith("..")) return undefined;
+  const owner = ownerOf(declaration, groups, at);
+  if (!owner || !("member" in owner)) return undefined;
+  const member = owner.member;
+
+  const repoRoot = real(gitTop(workspaceRoot) ?? workspaceRoot);
+  const prefix = relPath(repoRoot, workspaceRoot);
+  const pipeline: PipelineMember = { name: member.name, dir: joinRel(prefix, member.dir) };
+  if (member.dir === ".") {
+    const exclude = rootExclusions(declaration, groups).map((e) => joinRel(prefix, e.dir));
+    if (exclude.length > 0) pipeline.exclude = exclude;
+  }
+  return {
+    declaration,
+    member,
+    workspaceRoot,
+    repoRoot,
+    memberRoot: member.dir === "." ? workspaceRoot : join(workspaceRoot, member.dir),
+    pipeline,
+  };
+}
+
+/** Where each forge reads a member's component pipeline from, relative to the repository root. */
+const PIPELINE_DIRS: Record<string, string> = {
+  github: ".github/workflows",
+  forgejo: ".forgejo/workflows",
+  // GitLab reads only .gitlab-ci.yml, which includes these (`include: local: .gitlab/ci/*.gitlab-ci.yml`).
+  gitlab: ".gitlab/ci",
+};
+
+/** The directory a forge's generated files go in for a member, relative to the repository root, or undefined for a forge chant doesn't know. */
+export function memberPipelineDir(provider: string): string | undefined {
+  return PIPELINE_DIRS[provider];
+}
+
+/**
+ * The default path of a member's component pipeline for one environment,
+ * relative to the repository root: `chant-<member>-<env>.yml` in the forge's
+ * workflow directory, or `.gitlab/ci/chant-<member>-<env>.gitlab-ci.yml`.
+ */
+export function memberPipelineFile(provider: string, member: string, env: string): string | undefined {
+  const dir = PIPELINE_DIRS[provider];
+  if (dir === undefined) return undefined;
+  return `${dir}/chant-${member}-${env}${provider === "gitlab" ? ".gitlab-ci.yml" : ".yml"}`;
+}
+
+/** A repository-relative path for an absolute one. */
+export function repoRelative(ctx: MemberContext, absolute: string): string {
+  return relPath(ctx.repoRoot, resolve(absolute));
+}
+
+/** Read a member's generated-file record, or an empty one. */
+export function readGeneratedRecord(memberRoot: string): GeneratedRecord {
+  const file = join(memberRoot, GENERATED_RECORD_FILE);
+  if (!existsSync(file)) return { schema: 1, files: [] };
+  const parsed = JSON.parse(readFileSync(file, "utf-8")) as Partial<GeneratedRecord>;
+  return { schema: 1, files: Array.isArray(parsed.files) ? parsed.files : [] };
+}
+
+/**
+ * Add or replace entries in a member's generated-file record, keyed by path,
+ * and write it back sorted, so regenerating the same files leaves it
+ * byte-identical.
+ */
+export function recordGeneratedFiles(memberRoot: string, entries: GeneratedFileEntry[]): string {
+  const record = readGeneratedRecord(memberRoot);
+  const byPath = new Map(record.files.map((f) => [f.path, f]));
+  for (const e of entries) byPath.set(e.path, e);
+  const files = [...byPath.values()].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  const file = join(memberRoot, GENERATED_RECORD_FILE);
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify({ schema: 1, files }, null, 2) + "\n");
+  return file;
+}
+
+/** Quote one argument for a recorded command line when it needs it. */
+export function shellArg(arg: string): string {
+  return /^[A-Za-z0-9._\/=:@%+,-]+$/.test(arg) ? arg : `'${arg.replace(/'/g, `'\\''`)}'`;
+}
+
+/** The first line of a member's generated pipeline, naming the command that regenerates it. */
+export function generatedHeader(command: string): string {
+  return `# ${GENERATED_MARKER}. Regenerate with: ${command} (in the member's directory)\n`;
+}
+
+/** What `chant build --components --generate` needs to write a member's pipeline. */
+export interface MemberComponentPlan {
+  ctx: MemberContext;
+  /** Passed to the generator as `options.member`. */
+  member: PipelineMember;
+  /** The pipeline file, relative to the repository root. */
+  file: string;
+  /** The pipeline file's absolute path. */
+  target: string;
+  /** The command that regenerates it, run in the member's directory. */
+  command: string;
+  env: string;
+}
+
+export interface ComponentPlanInput {
+  projectDir: string;
+  found: WorkspaceRootSearch;
+  lexicon: string;
+  /** `--env`, or undefined for the generator's default. */
+  env?: string;
+  promoteTo?: string;
+  /** `--output`, relative to the current directory. */
+  output?: string;
+  params?: string[];
+  paramsFile?: string;
+}
+
+/** The generators' own default environment when `--env` is not given. */
+const DEFAULT_ENV = "production";
+
+/**
+ * Plan a member's component pipeline: which member, which file and which
+ * command. Undefined when the project belongs to no member. Throws with a
+ * readable message when there is no default file for the forge and no
+ * `--output`.
+ */
+export function planMemberComponentPipeline(input: ComponentPlanInput): MemberComponentPlan | undefined {
+  const ctx = resolveMemberContext(input.projectDir, input.found);
+  if (!ctx) return undefined;
+  const env = input.env ?? DEFAULT_ENV;
+  let target: string;
+  if (input.output) {
+    target = resolve(input.output);
+  } else {
+    const file = memberPipelineFile(input.lexicon, ctx.member.name, env);
+    if (file === undefined) {
+      throw new Error(`there is no default pipeline path for ${input.lexicon} in a workspace member; pass --output <file>`);
+    }
+    target = join(ctx.repoRoot, file);
+  }
+  const file = repoRelative(ctx, target);
+
+  const parts = ["chant", "build", "--components", "--generate", input.lexicon, "--env", env];
+  if (input.promoteTo) parts.push("--promote-to", input.promoteTo);
+  for (const p of input.params ?? []) parts.push("--param", p);
+  if (input.paramsFile) parts.push("--params-file", relPath(ctx.memberRoot, resolve(input.paramsFile)));
+  if (input.output) parts.push("--output", relPath(ctx.memberRoot, target));
+
+  return {
+    ctx,
+    member: { ...ctx.pipeline, file },
+    file,
+    target,
+    command: parts.map(shellArg).join(" "),
+    env,
+  };
+}
+
+/** Write a member's pipeline with its header and record it as the member's generated file. */
+export function writeMemberComponentPipeline(plan: MemberComponentPlan, yaml: string): void {
+  mkdirSync(dirname(plan.target), { recursive: true });
+  writeFileSync(plan.target, generatedHeader(plan.command) + yaml);
+  recordGeneratedFiles(plan.ctx.memberRoot, [{ path: plan.file, command: plan.command, env: plan.env }]);
+}
+
+/** What `chant run --generate` needs to write a member's Op pipelines. */
+export interface MemberOpPlan {
+  ctx: MemberContext;
+  member: PipelineMember;
+  /** Absolute directory the files are written to. */
+  outDir: string;
+  command: string;
+}
+
+/** Plan a member's Op pipelines. Undefined when the directory belongs to no member. */
+export function planMemberOpPipelines(input: {
+  projectDir: string;
+  found: WorkspaceRootSearch;
+  provider: string;
+  output?: string;
+  specFile?: string;
+}): MemberOpPlan | undefined {
+  const ctx = resolveMemberContext(input.projectDir, input.found);
+  if (!ctx) return undefined;
+  let outDir: string;
+  if (input.output) {
+    outDir = resolve(input.output);
+  } else {
+    const dir = memberPipelineDir(input.provider);
+    if (dir === undefined) {
+      throw new Error(`there is no default pipeline directory for ${input.provider} in a workspace member; pass --output <dir>`);
+    }
+    outDir = join(ctx.repoRoot, dir);
+  }
+  const parts = ["chant", "run", "--generate", input.provider];
+  if (input.specFile) parts.push("--spec", relPath(ctx.memberRoot, resolve(input.specFile)));
+  if (input.output) parts.push("--output", relPath(ctx.memberRoot, outDir));
+  return {
+    ctx,
+    member: { ...ctx.pipeline, fileDir: repoRelative(ctx, outDir) },
+    outDir,
+    command: parts.map(shellArg).join(" "),
+  };
+}
+
+/** Write a member's Op pipeline files with their header and record them. Returns the paths written, relative to the current directory. */
+export function writeMemberOpPipelines(plan: MemberOpPlan, files: { name: string; yaml: string }[]): string[] {
+  const written: string[] = [];
+  const entries: GeneratedFileEntry[] = [];
+  for (const f of files) {
+    const target = join(plan.outDir, f.name);
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, generatedHeader(plan.command) + f.yaml);
+    entries.push({ path: repoRelative(plan.ctx, target), command: plan.command });
+    written.push(relative(process.cwd(), target) || target);
+  }
+  recordGeneratedFiles(plan.ctx.memberRoot, entries);
+  return written;
+}
+
+/** A message for an error from planning: a declaration error with its file and line, or the error's own message. */
+export function describeError(err: unknown): string {
+  if (err instanceof WorkspaceReadError) return err.describe();
+  return err instanceof Error ? err.message : String(err);
+}