@intentius/chant 0.124.13 → 0.124.14

package/dist/pr-loop.js

@@ -0,0 +1,203 @@
+/**
+ * The pull-request loop (#3183): plan the members a change reaches, show the
+ * plan on the pull request, and apply it on merge only when the plan is the
+ * one a reviewer approved.
+ *
+ * `chant components pr-plan` and `chant components pr-apply` run it, and the
+ * generated CI for GitHub, GitLab and Forgejo calls them
+ * (`components/pr-pipeline.ts`). This module holds the parts that need no
+ * runner: the gate's names, the report both commands write, the pull-request
+ * note rendered from it and the status line. terragucci reads the report and
+ * renders the note from one bundled file with no TypeScript toolchain
+ * (#3421), so this imports `./change-set` and `./plan-summary` and nothing
+ * else; `pr-loop-bundle.test.ts` holds that.
+ *
+ * ## What the gate binds
+ *
+ * One gate per pull request: op `pr-<number>`, gate `pr-apply` unless the
+ * pipeline names another. It binds the digest of the change-set document over
+ * every planned member (`changeSetDocumentDigest`, #3181): the set digest a
+ * gated wave binds over its members (#3049), and the document's entries, holes
+ * and side effects with it (#3555). A reviewer approves it with `chant
+ * approve pr-<number> pr-apply --plan <digest>`. The op carries the number so
+ * that one pull request's approval never answers another's, and the gate name
+ * stays fixed so a workspace can require signed approvals for it under
+ * `identity.gates` (#3163).
+ *
+ * On merge the apply plans the same members again, before anything applies,
+ * and decides the gate against the new digest. The same plan applies; a moved
+ * plan stops with both digests named and nothing applied.
+ *
+ * ## Inside a workspace member
+ *
+ * Each workspace member that generates the pipeline (#3465) runs its own
+ * plan and apply on the same pull request, so each keeps its own gate, note
+ * and statuses: op `pr-<number>-<member>`, the note marker and the status
+ * contexts carry the member's name. The gate name stays the same, so one
+ * `identity.gates` entry covers every member.
+ */
+import { GITHUB_COMMENT_LIMIT, groupChangeSet, renderPlanSummaryMarkdown } from "./plan-summary.js";
+/** The schema a pull-request report names in `$schema`. */
+export const PR_REPORT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/pr-report/v1/pr-report.schema.json";
+/** The read-contract version the report follows. */
+export const PR_REPORT_CONTRACT = 1;
+/** The gate a pull request's apply waits on, unless the pipeline names another. */
+export const PR_APPLY_GATE = "pr-apply";
+/**
+ * The op a pull request's gate is recorded under: `pr-<number>`, or
+ * `pr-<number>-<member>` for a workspace member's pipeline (#3465).
+ */
+export function prOp(pr, member) {
+    return member ? `pr-${pr}-${member}` : `pr-${pr}`;
+}
+/** Whether `op` is a pull request's gate op, with or without a member. Member names follow the declaration's name pattern. */
+export const PR_GATE_OP = /^pr-\d+(?:-[a-z0-9][a-z0-9-]*)?$/;
+/** The hidden line that marks the pull request's note, one per environment and, in a workspace, per member. */
+export function prNoteMarker(env, member) {
+    return member ? `<!-- chant-pr:${env}:${member} -->` : `<!-- chant-pr:${env} -->`;
+}
+/** The status contexts the two stages set on the commit. */
+export const PR_STATUS_CONTEXTS = { plan: "chant/plan", apply: "chant/apply" };
+/** A stage's status context: `chant/plan`, or `chant/plan/<member>` for a workspace member's pipeline. */
+export function prStatusContext(stage, member) {
+    return member ? `${PR_STATUS_CONTEXTS[stage]}/${member}` : PR_STATUS_CONTEXTS[stage];
+}
+/** The counts a member's entries add up to. */
+export function memberCounts(doc, member) {
+    const by = doc.summary.byMember[member] ?? {};
+    const n = (a) => by[a] ?? 0;
+    return { create: n("create"), update: n("update"), replace: n("replace"), delete: n("delete") };
+}
+/** The approve command a reviewer runs for this report's digest. */
+export function prApproveCommand(report, approver = "<you>") {
+    return `chant approve ${report.op} ${report.gate} --plan ${report.digest} --approver ${approver} --sign`;
+}
+/**
+ * The refusal when the approved digest is not the planned one: both digests,
+ * that nothing applied, and how to close it.
+ */
+export function describePlanChanged(report) {
+    return (`The plan changed after review, so nothing was applied. ` +
+        `approved: ${report.approval.approved ?? "(none)"}; planned now: ${report.digest}. ` +
+        `Read the new plan, and if it is right, approve it: ${prApproveCommand(report)}; then run the apply again.`);
+}
+const short = (sha) => sha.slice(0, 12);
+const code = (s) => "`" + s.replaceAll("`", "'") + "`";
+const STATUS_WORDS = {
+    planned: "planned",
+    "plan-failed": "plan failed",
+    applied: "applied",
+    failed: "apply failed",
+    blocked: "blocked",
+};
+function headline(report) {
+    const n = report.members.length;
+    const members = `${n} member${n === 1 ? "" : "s"}`;
+    switch (report.status) {
+        case "nothing":
+            return "Nothing to plan: no component deploys what this change touches.";
+        case "planned":
+            return `Planned ${members}.`;
+        case "plan-failed":
+            return `Planning failed for ${report.members.filter((m) => m.status === "plan-failed").length} of ${members}, so nothing can apply.`;
+        case "applied":
+            return `Applied ${members}.`;
+        case "failed":
+            return `The apply failed: ${report.members.filter((m) => m.status === "failed").length} failed, ${report.members.filter((m) => m.status === "applied").length} applied.`;
+        case "refused":
+            return "The apply refused.";
+    }
+}
+function approvalLines(report, approver) {
+    const a = report.approval;
+    if (report.status === "nothing")
+        return [];
+    if (a.status === "approved")
+        return [`Approved by ${(a.approvedBy ?? []).map(code).join(", ")} for this digest.`];
+    const lines = a.status === "changed"
+        ? [`An approval stands for ${code(a.approved ?? "(none)")}, not for this digest: the plan changed since it was approved.`]
+        : ["Not approved yet."];
+    if (report.stage === "plan" && report.status === "planned") {
+        lines.push("", "A reviewer who approved this pull request approves the plan with:", "", "```", prApproveCommand(report, approver), "```", "", "It applies on merge if the plan is still this one. If it moved, the apply refuses and names both digests.");
+    }
+    return lines;
+}
+/**
+ * The pull-request note: the stage's headline, a row per member, the digest
+ * and the approval, then the grouped plan summary (#3188) in whatever room
+ * `limit` leaves. The note starts with {@link prNoteMarker}, so the same
+ * comment is updated by every push and by the apply.
+ */
+export function renderPrNote(report, options = {}) {
+    const limit = options.limit ?? GITHUB_COMMENT_LIMIT;
+    const out = [
+        prNoteMarker(report.env, report.member),
+        `### chant ${report.stage === "plan" ? "plan" : "apply"} for ${code(report.env)}${report.member ? ` in member ${code(report.member)}` : ""}`,
+        "",
+        `${headline(report)} Head ${code(short(report.head))}, measured from ${code(short(report.base))}.`,
+    ];
+    if (report.message)
+        out.push("", `> ${report.message.split("\n").join("\n> ")}`);
+    if (report.resumed && report.resumed.applied.length > 0) {
+        out.push("", `Resumed under the same approval: ${report.resumed.applied.map(code).join(", ")} applied in an earlier attempt and did not run again.`);
+    }
+    if (report.members.length > 0) {
+        out.push("", "| Member | Component | Status | Create | Update | Replace | Delete |", "|---|---|---|---:|---:|---:|---:|");
+        for (const m of report.members) {
+            const status = STATUS_WORDS[m.status] + (m.inputsMoved?.length ? `, inputs from ${m.inputsMoved.join(", ")} moved` : "");
+            out.push(`| ${code(m.member)} | ${m.component} | ${status} | ${m.counts.create} | ${m.counts.update} | ${m.counts.replace} | ${m.counts.delete} |`);
+        }
+        if (report.members.some((m) => m.inputsMoved?.length)) {
+            out.push("", "A member whose inputs moved applied the plan it was approved with. The next run plans it against the new values.");
+        }
+    }
+    if (report.selection.unclaimed.length > 0) {
+        out.push("", `Changed, and deployed by no component: ${report.selection.unclaimed.map(code).join(", ")}.`);
+    }
+    if (report.status !== "nothing") {
+        out.push("", `Plan digest: ${code(report.digest)}`, "", ...approvalLines(report, options.approver ?? "<you>"));
+    }
+    const head = out.join("\n") + "\n";
+    if (report.status === "nothing" || report.changeSet.members.length === 0)
+        return head;
+    const room = limit - [...head].length - 1;
+    if (room < 400)
+        return head;
+    return head + "\n" + renderPlanSummaryMarkdown(groupChangeSet(report.changeSet), { limit: room, command: "chant change-set summary .chant/pr/change-set.json" });
+}
+/** A commit status's description, at most 140 characters (GitHub's limit). */
+export function prStatusDescription(report) {
+    const n = report.members.length;
+    const sum = report.members.reduce((acc, m) => ({ change: acc.change + m.counts.create + m.counts.update + m.counts.replace, destroy: acc.destroy + m.counts.delete + m.counts.replace }), { change: 0, destroy: 0 });
+    const digest = report.digest ? `; plan ${report.digest.replace(/^(?:jcs1-)?sha256:/, "").slice(0, 12)}` : "";
+    let text;
+    switch (report.status) {
+        case "nothing":
+            text = "nothing to plan";
+            break;
+        case "planned":
+            text = `${n} member${n === 1 ? "" : "s"}: ${sum.change} to change, ${sum.destroy} to destroy or replace${digest}`;
+            break;
+        case "plan-failed":
+            text = `a member failed to plan${digest}`;
+            break;
+        case "applied":
+            text = `applied ${n} member${n === 1 ? "" : "s"}${digest}`;
+            break;
+        case "failed":
+            text = `apply failed for ${report.members.filter((m) => m.status === "failed").map((m) => m.member).join(", ")}`;
+            break;
+        case "refused":
+            text = `refused: ${report.refusal === "plan-changed" ? "the plan changed after review" : report.refusal === "not-a-reviewer" ? "the approver has not approved the pull request" : report.refusal === "no-pull-request" ? "no pull request merged this commit" : "the plan is not approved"}`;
+            break;
+    }
+    return text.length > 140 ? text.slice(0, 137) + "..." : text;
+}
+/** The commit status state for a report: success, failure, or pending while it waits on approval. */
+export function prStatusState(report) {
+    if (report.status === "planned" || report.status === "applied" || report.status === "nothing")
+        return "success";
+    if (report.status === "refused" && report.refusal === "not-approved")
+        return "pending";
+    return "failure";
+}

package/dist/project-codegen.js

@@ -0,0 +1,191 @@
+/**
+ * Project-local code generation: typed code a lexicon generates into the
+ * project from sources the project declares in `chant.config.ts` (a CRD file,
+ * a Helm chart), as opposed to the types a lexicon ships in its package.
+ *
+ * The split of work:
+ *
+ * - A lexicon implements {@link ProjectCodegen} (the plugin's
+ *   `projectCodegen()` hook). It says what its declared inputs are
+ *   ({@link ProjectCodegen.inputs}, offline), renders files from them
+ *   ({@link ProjectCodegen.generate}, may fetch), and optionally reads its own
+ *   committed output back when a build starts ({@link ProjectCodegen.load}).
+ * - Core owns the output directory, writes the files, and records a digest of
+ *   the inputs beside them in {@link STAMP_FILE}. `chant generate` is the only
+ *   writer.
+ * - Every build compares the inputs' digest with the recorded one before it
+ *   serializes ({@link checkProjectCodegen}, wired in through the build-root
+ *   contributors in ./cli/plugins.ts). A mismatch fails the build. The build
+ *   never fetches and never regenerates, so it stays offline and the committed
+ *   output is what a fresh clone typechecks against.
+ *
+ * Output lives in `<codegen.outDir>/<lexicon>/`, default `src/generated/<lexicon>/`,
+ * relative to the directory holding `chant.config.*`.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { canonicalJson } from "./effect-receipt.js";
+import { GENERATED_MARKER } from "./discovery/files.js";
+/** Default output directory, relative to the project root. */
+export const DEFAULT_CODEGEN_OUT_DIR = "src/generated";
+/** The file core writes beside a lexicon's generated files: the inputs digest and the file list. */
+export const STAMP_FILE = "chant-codegen.json";
+/**
+ * Header for generated TypeScript. It carries discovery's generated-file
+ * marker (`./discovery/files.ts`), so the build and `chant lint` do not treat
+ * the generated module as authored source; project files still import it.
+ */
+export const GENERATED_TS_HEADER = `// ${GENERATED_MARKER}. Run \`chant generate\` to update.`;
+/** Resolve the output root (`codegen.outDir`, default {@link DEFAULT_CODEGEN_OUT_DIR}) against the project root. */
+export function resolveCodegenRoot(projectRoot, config) {
+    const codegen = config.codegen;
+    const outDir = typeof codegen?.outDir === "string" && codegen.outDir.length > 0 ? codegen.outDir : DEFAULT_CODEGEN_OUT_DIR;
+    return resolve(projectRoot, outDir);
+}
+/** The context for one lexicon. */
+export function projectCodegenContext(lexicon, projectRoot, config) {
+    return { projectRoot, config, outDir: join(resolveCodegenRoot(projectRoot, config), lexicon) };
+}
+/** `sha256:<hex>` of a JSON value's canonical form. */
+export function digestInputs(inputs) {
+    return `sha256:${createHash("sha256").update(canonicalJson(inputs)).digest("hex")}`;
+}
+/** Read a lexicon's stamp, or `undefined` when it has none (or it does not parse). */
+export function readStamp(outDir) {
+    const path = join(outDir, STAMP_FILE);
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof parsed.inputs !== "string" || !Array.isArray(parsed.files))
+            return undefined;
+        return { inputs: parsed.inputs, files: parsed.files.filter((f) => typeof f === "string") };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * `chant generate` for one lexicon: render its files, write them, delete
+ * files a previous run wrote that this one did not, and record the stamp.
+ * With nothing declared, a previous run's output is removed.
+ */
+export async function generateProjectCode(plugin, projectRoot, config, options = {}) {
+    const codegen = plugin.projectCodegen?.();
+    if (!codegen)
+        return undefined;
+    const ctx = projectCodegenContext(plugin.name, projectRoot, config);
+    const previous = readStamp(ctx.outDir);
+    const inputs = await codegen.inputs(ctx);
+    if (inputs === undefined) {
+        if (!previous)
+            return { lexicon: plugin.name, outDir: ctx.outDir, status: "none", files: [], summary: [] };
+        removeFiles(ctx.outDir, [...previous.files, STAMP_FILE]);
+        return { lexicon: plugin.name, outDir: ctx.outDir, status: "removed", files: previous.files, summary: [] };
+    }
+    const output = await codegen.generate({ ...ctx, ...(options.fetch ? { fetch: options.fetch } : {}) });
+    const files = Object.keys(output.files).sort();
+    for (const file of files) {
+        const target = safeJoin(ctx.outDir, file);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, output.files[file]);
+    }
+    if (previous) {
+        const keep = new Set(files);
+        removeFiles(ctx.outDir, previous.files.filter((f) => !keep.has(f)));
+    }
+    const stamp = { inputs: digestInputs(inputs), files };
+    mkdirSync(ctx.outDir, { recursive: true });
+    writeFileSync(join(ctx.outDir, STAMP_FILE), JSON.stringify(stamp, null, 2) + "\n");
+    return { lexicon: plugin.name, outDir: ctx.outDir, status: "written", files, summary: output.summary ?? [] };
+}
+/**
+ * Whether a lexicon's committed output matches its declared inputs. Offline.
+ *
+ * - `none`: nothing declared, nothing generated.
+ * - `current`: the recorded digest matches and every recorded file exists.
+ * - `missing`: sources are declared and there is no output (or a recorded file is gone).
+ * - `drift`: the declared sources changed since the output was generated.
+ * - `orphan`: nothing is declared any more, but generated output remains.
+ */
+export async function checkProjectCodegen(plugin, projectRoot, config) {
+    const codegen = plugin.projectCodegen?.();
+    if (!codegen)
+        return { status: "none" };
+    const ctx = projectCodegenContext(plugin.name, projectRoot, config);
+    const where = displayPath(projectRoot, ctx.outDir);
+    const stamp = readStamp(ctx.outDir);
+    const inputs = await codegen.inputs(ctx);
+    if (inputs === undefined) {
+        if (!stamp)
+            return { status: "none" };
+        return {
+            status: "orphan",
+            message: `${where} holds generated ${plugin.name} code, but chant.config declares no ${plugin.name} sources for it. Run \`chant generate\` to remove it.`,
+        };
+    }
+    if (!stamp) {
+        return {
+            status: "missing",
+            message: `chant.config declares ${plugin.name} sources to generate, but ${where} has no generated code. Run \`chant generate\` and commit the result.`,
+        };
+    }
+    const absent = stamp.files.filter((f) => !existsSync(safeJoin(ctx.outDir, f)));
+    if (absent.length > 0) {
+        return {
+            status: "missing",
+            message: `generated ${plugin.name} file(s) missing from ${where}: ${absent.join(", ")}. Run \`chant generate\` and commit the result.`,
+        };
+    }
+    if (stamp.inputs !== digestInputs(inputs)) {
+        return {
+            status: "drift",
+            message: `generated ${plugin.name} code in ${where} is out of date: its declared sources changed since it was generated. Run \`chant generate\` and commit the result.`,
+        };
+    }
+    return { status: "current" };
+}
+/**
+ * The build's side of project codegen for one plugin: check the committed
+ * output against the declared inputs, throw on any mismatch, and let the
+ * lexicon load its output when it is current. Called once per top-level
+ * build, before serialization.
+ */
+export async function prepareProjectCodegen(plugin, projectRoot, config) {
+    const check = await checkProjectCodegen(plugin, projectRoot, config);
+    if ("message" in check)
+        throw new Error(check.message);
+    if (check.status === "none")
+        return;
+    await plugin.projectCodegen?.().load?.(projectCodegenContext(plugin.name, projectRoot, config));
+}
+function removeFiles(outDir, files) {
+    for (const file of files) {
+        rmSync(safeJoin(outDir, file), { force: true });
+    }
+    pruneEmptyDirs(outDir);
+}
+/** Remove empty directories under (and including) `dir`. */
+function pruneEmptyDirs(dir) {
+    if (!existsSync(dir))
+        return;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isDirectory())
+            pruneEmptyDirs(join(dir, entry.name));
+    }
+    if (readdirSync(dir).length === 0)
+        rmdirSync(dir);
+}
+/** Join a recorded relative path onto `outDir`, refusing one that escapes it. */
+function safeJoin(outDir, file) {
+    const target = resolve(outDir, file);
+    if (isAbsolute(file) || (target !== outDir && !target.startsWith(outDir + sep))) {
+        throw new Error(`generated file path "${file}" is outside ${outDir}`);
+    }
+    return target;
+}
+function displayPath(projectRoot, path) {
+    const rel = relative(projectRoot, path);
+    return rel === "" ? "." : rel.split(sep).join("/");
+}

package/dist/project-root.js

@@ -0,0 +1,74 @@
+import { existsSync } from "fs";
+import { dirname, join, resolve } from "path";
+/** Walk up from `startDir` (inclusive) to the nearest chant config or project boundary. See {@link ProjectConfigSearch}. */
+export function findProjectConfig(startDir) {
+    const resolvedStart = resolve(startDir);
+    let dir = resolvedStart;
+    for (;;) {
+        const tsPath = join(dir, "chant.config.ts");
+        if (existsSync(tsPath))
+            return { dir, configPath: tsPath };
+        const jsonPath = join(dir, "chant.config.json");
+        if (existsSync(jsonPath))
+            return { dir, configPath: jsonPath };
+        if (existsSync(join(dir, ".git")) || existsSync(join(dir, "package.json"))) {
+            return { dir };
+        }
+        const parent = dirname(dir);
+        if (parent === dir) {
+            // Filesystem root, no config, no boundary ever seen — give up rather
+            // than adopting "/" as the project root (see the module doc above).
+            return { dir: resolvedStart };
+        }
+        dir = parent;
+    }
+}
+/**
+ * Walk up from `startDir` to the nearest ancestor holding a chant project
+ * config (`chant.config.ts` or `chant.config.json`), the `.git`/`package.json`
+ * project boundary, or `startDir` itself when neither is found. Thin wrapper
+ * over {@link findProjectConfig} for callers that only need the directory
+ * (e.g. `chant lint`'s rule/plugin resolution, which just needs *a* stable
+ * root to resolve relative paths against).
+ */
+export function findProjectRoot(startDir) {
+    return findProjectConfig(startDir).dir;
+}
+/** The two names a workspace declaration may have (#2524 D1). */
+export const WORKSPACE_DECLARATION_FILES = ["chant.workspace.json", "chant.workspace.jsonc"];
+/**
+ * Walk up from `startDir` (inclusive) to the nearest `chant.workspace.json` or
+ * `chant.workspace.jsonc` (#2524 D1). The walk stops at the git root, the first
+ * directory holding `.git`, after checking it. Outside a git repository only
+ * `startDir` itself is checked, so a stray declaration in an unrelated
+ * ancestor is never picked up.
+ *
+ * It only tests whether files exist and loads nothing else, so a level-0
+ * command can afford to call it. {@link findProjectConfig} is unchanged and
+ * never looks at a declaration.
+ */
+export function findWorkspaceRoot(startDir) {
+    const start = resolve(startDir);
+    let top;
+    for (let dir = start;; dir = dirname(dir)) {
+        if (existsSync(join(dir, ".git"))) {
+            top = dir;
+            break;
+        }
+        if (dirname(dir) === dir)
+            break;
+    }
+    for (let dir = start;; dir = dirname(dir)) {
+        const [json, jsonc] = WORKSPACE_DECLARATION_FILES.map((name) => join(dir, name));
+        const hasJson = existsSync(json);
+        const hasJsonc = existsSync(jsonc);
+        if (hasJson && hasJsonc)
+            return { dir, file: json, conflicting: jsonc };
+        if (hasJson)
+            return { dir, file: json };
+        if (hasJsonc)
+            return { dir, file: jsonc };
+        if (top === undefined || dir === top || dirname(dir) === dir)
+            return undefined;
+    }
+}

package/dist/project-validation.js

@@ -0,0 +1,50 @@
+import { existsSync } from "fs";
+import { join } from "path";
+/**
+ * Validate project structure.
+ *
+ * Checks that required files and directories exist for a chant project.
+ *
+ * @param projectDir - Root directory of the chant project
+ * @param lexicons - Lexicon names from config (e.g. ["aws"])
+ */
+export function validateProjectStructure(projectDir, lexicons = []) {
+    const issues = [];
+    // Check for config file
+    const hasTsConfig = existsSync(join(projectDir, "chant.config.ts"));
+    const hasJsonConfig = existsSync(join(projectDir, "chant.config.json"));
+    if (!hasTsConfig && !hasJsonConfig) {
+        issues.push({
+            severity: "warning",
+            message: "No chant config found. Run \"chant init\" to create one.",
+        });
+    }
+    // Check for src directory
+    if (!existsSync(join(projectDir, "src"))) {
+        issues.push({
+            severity: "warning",
+            message: "No src/ directory found.",
+        });
+    }
+    // Check for .chant/types/core/
+    if (!existsSync(join(projectDir, ".chant", "types", "core", "index.d.ts"))) {
+        issues.push({
+            severity: "warning",
+            message: "Core types not installed in .chant/types/core/. Run \"chant update\" to sync.",
+        });
+    }
+    // Check for lexicon type stubs
+    for (const lexicon of lexicons) {
+        const lexiconDir = join(projectDir, ".chant", "types", `lexicon-${lexicon}`);
+        if (!existsSync(lexiconDir)) {
+            issues.push({
+                severity: "warning",
+                message: `Lexicon types not installed for "${lexicon}". Run "chant update" to sync.`,
+            });
+        }
+    }
+    return {
+        valid: issues.every((i) => i.severity !== "error"),
+        issues,
+    };
+}

package/dist/provenance.js

@@ -0,0 +1,157 @@
+/**
+ * Build provenance: where a declared entity came from in the TypeScript source.
+ *
+ * Stamped during discovery as a non-enumerable, symbol-keyed side channel on the
+ * entity object, so it never serializes into the emitted YAML/JSON — it is build
+ * metadata, not declared configuration. Read it back with {@link getProvenance}.
+ *
+ * Entity-level provenance (which file declared it, and which composite expanded
+ * it) answers "where did this resource come from?", which is the question an
+ * agent asks before changing it. {@link PathOrigin} (chant #1443) answers the
+ * follow-up — "what set THIS field" — for the paths a build can attribute
+ * without guessing. Neither is a YAML-line source map.
+ *
+ * {@link BuildParamProvenance} (chant #1064) is the other half: not "where did
+ * this ENTITY come from" but "what INPUTS was this whole BUILD invoked with" —
+ * the question ambient `process.env` reads used to answer invisibly. See
+ * ../build-params.ts for declaration/resolution and ../build.ts's
+ * `BuildResult.buildParams` for where a build surfaces it.
+ */
+const PROVENANCE = Symbol.for("chant.provenance");
+/** True when `prefix` addresses `path` or an ancestor of it, on a segment boundary. */
+function isPathPrefix(prefix, path) {
+    if (prefix === "")
+        return true;
+    if (!path.startsWith(prefix))
+        return false;
+    if (path.length === prefix.length)
+        return true;
+    const next = path[prefix.length];
+    return next === "." || next === "[";
+}
+/**
+ * Merge provenance onto an entity. Non-enumerable so it is invisible to
+ * serializers and spreads. Existing fields win (`??=`), so the first/most
+ * specific writer — the innermost composite, the declaring file — is kept.
+ */
+export function setProvenance(entity, prov) {
+    var _a;
+    if (!Object.isExtensible(entity))
+        return;
+    const existing = entity[PROVENANCE];
+    if (existing) {
+        existing.sourceFile ?? (existing.sourceFile = prov.sourceFile);
+        existing.composite ?? (existing.composite = prov.composite);
+        existing.compositeInstance ?? (existing.compositeInstance = prov.compositeInstance);
+        existing.compositeCall ?? (existing.compositeCall = prov.compositeCall);
+        if (prov.paths) {
+            existing.paths ?? (existing.paths = {});
+            for (const [path, origin] of Object.entries(prov.paths)) {
+                (_a = existing.paths)[path] ?? (_a[path] = origin);
+            }
+        }
+        return;
+    }
+    Object.defineProperty(entity, PROVENANCE, {
+        value: { ...prov, ...(prov.paths ? { paths: { ...prov.paths } } : {}) },
+        enumerable: false,
+        writable: true,
+        configurable: true,
+    });
+}
+/** Read an entity's build provenance, if any was stamped. */
+export function getProvenance(entity) {
+    return entity[PROVENANCE];
+}
+/**
+ * Record one path's origin, first writer wins — the same rule
+ * {@link setProvenance} applies to entity-level fields, and for the same
+ * reason: expansion runs innermost-composite-first, so the earliest writer is
+ * the most specific one.
+ */
+export function setPathProvenance(entity, path, origin) {
+    setProvenance(entity, { paths: { [path]: origin } });
+}
+/**
+ * An entity's recorded path origins in sorted key order, or `undefined` when
+ * none were recorded. Sorted because a build's outputs are compared byte for
+ * byte and object key order is not something insertion should decide.
+ */
+export function getPathProvenance(entity) {
+    const paths = getProvenance(entity)?.paths;
+    if (!paths)
+        return undefined;
+    const keys = Object.keys(paths).sort();
+    if (keys.length === 0)
+        return undefined;
+    const out = {};
+    for (const key of keys)
+        out[key] = paths[key];
+    return out;
+}
+/**
+ * The origin governing `path` — the longest recorded key that addresses it or
+ * one of its ancestors. See {@link PROVENANCE_PATH_GRAMMAR}.
+ */
+export function originOfPath(paths, path) {
+    if (!paths)
+        return undefined;
+    let best;
+    for (const key of Object.keys(paths)) {
+        if (!isPathPrefix(key, path))
+            continue;
+        if (best === undefined || key.length > best.length)
+            best = key;
+    }
+    return best === undefined ? undefined : paths[best];
+}
+const INTERPOLATION_FIELDS = Symbol.for("chant.interpolationFields");
+/**
+ * For an entity a tagged template built: which of its `props` paths each
+ * interpolation fed, by interpolation index (chant #3212). Element `i` lists
+ * the paths the `i`-th `${...}` landed in, in {@link EntityProvenance.paths}'
+ * grammar (dotted names, no array segments). An interpolation that fed no
+ * field the author typed, such as a reference to another entity, lists none.
+ *
+ * Only the tag can say this. It is the tag that parsed the text, so a
+ * `${props.ttlDays}` inside `TTL ts + INTERVAL ${props.ttlDays} DAY` is known
+ * to have fed `ttl` only there. When a composite factory interpreted at fold
+ * time writes the template, `discovery/fold-import.ts` joins these paths with
+ * the factory parameters each interpolation reads, which is what lets drift on
+ * such a field be reported against the parameter. A tag that never calls this
+ * leaves its fields `unknown`, the honest answer, rather than claiming either.
+ *
+ * Stored like provenance itself: non-enumerable and symbol-keyed, so no
+ * serializer, spread or comparison of the output ever sees it.
+ */
+export function setInterpolationFields(entity, fields) {
+    if (!Object.isExtensible(entity))
+        return;
+    Object.defineProperty(entity, INTERPOLATION_FIELDS, {
+        value: Object.freeze(fields.map((paths) => Object.freeze([...paths]))),
+        enumerable: false,
+        writable: true,
+        configurable: true,
+    });
+}
+/** What {@link setInterpolationFields} recorded on an entity, if anything. */
+export function getInterpolationFields(entity) {
+    return entity[INTERPOLATION_FIELDS];
+}
+/** One-line rendering of an origin, for diff output. */
+export function describePathOrigin(origin) {
+    switch (origin.kind) {
+        case "authored":
+            return "authored";
+        case "composite":
+            return `composite ${origin.composite} (${origin.instance})`;
+        case "build-param":
+            return `param ${origin.params.join(", ")}`;
+        case "composite-parameter":
+            return `composite ${origin.composite} parameter ${origin.parameters.join(", ")}`;
+        case "composite-literal":
+            return `composite ${origin.composite} literal`;
+        case "host":
+            return origin.reason;
+    }
+}