@intentius/chant 0.124.13 → 0.124.15

package/dist/workspace/intent-cli.js

@@ -0,0 +1,263 @@
+/**
+ * `chant workspace graph --intent <path[:start-end]|path#symbol> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]`
+ * (#2651, #3034): the intent graph over one region (`intent.ts`), printed as JSON
+ * with `--json` or as a walk, one line per node, in the order of #2650
+ * section B: the region, its decisions, their artifacts, the commits, and the
+ * findings, then why the region is like this: who made its current lines and
+ * the decisions governing it, most relevant first. Under each decision come the commits made inside its window, and
+ * when any of them is not the decision's own work, the question #2650 B puts
+ * to the person about it (#2656). Without `--kind`, the walk reads every
+ * record kind the declaration names (#2680).
+ */
+import { resolve } from "node:path";
+import { formatError } from "../cli/format.js";
+import { intentRecord } from "./intent-record.js";
+import { intentGraph } from "./intent.js";
+const USAGE = "chant workspace graph --intent <path[:start-end]|path#symbol> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]";
+const RECORD_USAGE = "chant workspace graph --intent --record <id> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]";
+function edgesFrom(doc, from, kind) {
+    return doc.edges.filter((e) => e.from === from && e.kind === kind);
+}
+function ofKind(doc, kind) {
+    return doc.nodes.filter((n) => n.kind === kind);
+}
+const short = (sha) => (sha ? sha.slice(0, 8) : "none");
+/** What the walk asks about a commit made inside a decision's window that is not the decision's own work (#2650 B4, step 5). */
+export const IN_WINDOW_QUESTION = "is this drift, a superseding decision nobody wrote down, or the decision being wrong?";
+/** The commits inside a decision's window, under its line, then the question once when any is not its own work. */
+function withinLines(doc, d) {
+    const within = doc.edges.filter((e) => e.kind === "within" && e.to === d.id);
+    const out = [];
+    for (const e of within) {
+        const c = doc.nodes.find((n) => n.kind === "commit" && n.id === e.from);
+        if (!c)
+            continue;
+        const unit = edgesFrom(doc, c.id, "produced-by")
+            .map((p) => doc.nodes.find((n) => n.id === p.to))
+            .map((n) => (n && "ref" in n ? n.ref : undefined))
+            .filter(Boolean);
+        const carried = (c.joins?.records ?? []).filter((r) => r.node !== null).map((r) => `${r.kind}:${r.id}`);
+        const item = c.joins?.lease?.item;
+        if (item && !carried.some((r) => r.endsWith(`:${item}`)))
+            carried.push(`lease on ${item}`);
+        const by = unit.length > 0 ? `unit ${unit.join(", ")}` : carried.length > 0 ? `carries ${carried.join(", ")}` : "no unit";
+        const label = e.state === "decided" ? "decided " : "within  ";
+        out.push(`  ${label}  ${short(c.sha)} ${c.subject}; ${by}${e.state === "decided" ? `, ${d.record}'s own work` : `, in ${d.record}'s window and not its work`}`);
+    }
+    if (within.some((e) => e.state === "decided-by-window"))
+        out.push(`  ask       ${IN_WINDOW_QUESTION}`);
+    return out;
+}
+function decisionLine(d) {
+    const via = d.constrains.length > 0 ? d.constrains.map((c) => `${c.entry} (${c.granularity})`).join(", ") : "through supersession only";
+    const by = d.decided_by ? `, decided by ${d.decided_by}${d.decided_on ? ` on ${d.decided_on}` : ""}` : "";
+    const decidedIn = d.decidedIn ? ` in ${short(d.decidedIn.sha)}` : "";
+    const reviews = `${d.reviews.agree} agree, ${d.reviews.dissent} dissent, ${d.reviews.abstain} abstain`;
+    const superseded = d.supersededBy ? `, superseded by ${d.supersededBy}` : "";
+    return `decision  ${d.record} ${d.state ?? "stateless"}${superseded}: ${d.title ?? d.path}; constrains ${via}${by}${decidedIn}; ${reviews}; ${d.provenance.level}${d.valid ? "" : `; invalid: ${d.reasons.map((r) => r.code).join(", ")}`}`;
+}
+/** A work item, then the commits made inside its window (#2683). */
+function workLines(doc, w) {
+    const via = w.constrains.length > 0 ? w.constrains.map((c) => `${c.entry} (${c.granularity})`).join(", ") : "through a link only";
+    const implemented = w.implements.length > 0 ? `; implements ${w.implements.map((d) => `${d.id} (${d.state ?? "unknown"})`).join(", ")}` : "";
+    const readiness = w.ready ? "; ready" : w.blockedBy.length > 0 ? `; blocked by ${w.blockedBy.map((b) => `${b.id} (${b.state ?? "unknown"})`).join(", ")}` : "";
+    const owner = w.owner ? `, owned by ${w.owner}` : "";
+    const from = w.source ? `; from ${w.source.finding} on ${w.source.region}` : "";
+    const out = [`work      ${w.record} ${w.state ?? "stateless"}${owner}: ${w.title ?? w.path}; constrains ${via}${implemented}${readiness}${from}`];
+    for (const e of doc.edges.filter((x) => x.kind === "within" && x.to === w.id)) {
+        const c = doc.nodes.find((n) => n.kind === "commit" && n.id === e.from);
+        if (c)
+            out.push(`  worked    ${short(c.sha)} ${c.subject}; in ${w.record}'s window`);
+    }
+    for (const x of w.warnings)
+        out.push(`  warning   ${x.code}: ${x.message}`);
+    return out;
+}
+function artifactLine(doc, a) {
+    const by = doc.edges
+        .filter((e) => e.kind === "pins" && e.to === a.id)
+        .map((e) => `${e.from.slice(e.from.indexOf("/") + 1)} at ${short(e.pinnedSha256)} (${e.pinState})`);
+    return `artifact  ${a.path} ${a.pinState}; pinned by ${by.join(", ")}; now ${short(a.currentSha256)}`;
+}
+/** What chant's own trailers on a commit say (#3149), one line each. */
+function joinLines(j) {
+    if (!j)
+        return [];
+    const out = [];
+    if (j.agent)
+        out.push(`  agent     ${j.agent}`);
+    if (j.lease)
+        out.push(`  lease     ${j.lease.token}${j.lease.item ? ` on ${j.lease.item}` : ", no lease history names it"}`);
+    for (const r of j.records)
+        out.push(`  record    ${r.kind}:${r.id}${r.node ? "" : ", in no kind read"}`);
+    if (j.applied)
+        out.push(`  applied   by ${j.applied.by}${j.applied.at ? ` at ${j.applied.at}` : ""}${j.applied.commit ? `, ${short(j.applied.commit)}` : ""}`);
+    return out;
+}
+function commitLine(doc, c) {
+    const lines = c.lines && c.lines.length > 0 ? `, lines ${c.lines.map((l) => (l.start === l.end ? `${l.start}` : `${l.start}-${l.end}`)).join(", ")}` : "";
+    const out = [`commit    ${short(c.sha)} ${c.date.slice(0, 10)} ${c.author.name}: ${c.subject}${lines}; ${c.signature.level}`];
+    for (const e of edgesFrom(doc, c.id, "produced-by")) {
+        const unit = doc.nodes.find((n) => n.id === e.to);
+        out.push(`  unit      ${unit && "ref" in unit ? unit.ref : e.to}`);
+        for (const s of edgesFrom(doc, e.to, "serves"))
+            out.push(`  contract  ${s.to.slice("contract:".length)}`);
+        for (const s of edgesFrom(doc, e.to, "cites-evidence"))
+            out.push(`  evidence  ${s.to.slice("evidence:".length)}`);
+    }
+    out.push(...joinLines(c.joins));
+    if (c.squash) {
+        const s = c.squash;
+        out.push(`  squash    #${s.pullRequest}${s.followed ? `: ${s.commits.length} original ${s.commits.length === 1 ? "commit" : "commits"} from ${s.ref}${s.fetched ? ", fetched" : ""}` : ", not followed"}`);
+        for (const o of s.commits) {
+            const carried = [...o.joins.records.map((r) => `${r.kind}:${r.id}`), ...(o.joins.lease ? [`lease ${o.joins.lease.token}`] : []), ...(o.joins.run ? [`run ${o.joins.run}`] : [])];
+            out.push(`  original  ${short(o.sha)} ${o.subject}; ${o.signature.level}${carried.length > 0 ? `; ${carried.join(", ")}` : ""}`);
+        }
+    }
+    for (const e of edgesFrom(doc, c.id, "made-by")) {
+        const r = doc.nodes.find((n) => n.kind === "run" && n.id === e.to);
+        if (!r)
+            continue;
+        const what = r.recorded ? `${[r.harness?.name, r.model].filter(Boolean).join("/") || "no model recorded"}${r.by ? ` for ${r.by}` : ""}${r.cost ? `, ${r.cost.amount} ${r.cost.currency}` : ", unpriced"}` : "not in the run ledger";
+        const content = e.kind !== "made-by"
+            ? ""
+            : e.joinedBy.includes("patch-id")
+                ? `; joined by content${e.recordedAs ? `, as ${short(e.recordedAs)}` : ""}`
+                : e.joinedBy.length === 1 && e.joinedBy[0] === "squash"
+                    ? `; through the squash, by ${(e.via ?? []).map(short).join(", ")}`
+                    : "";
+        out.push(`  run       ${r.run}: ${what}${content}`);
+    }
+    return out;
+}
+const span = (l) => (l.start === l.end ? `${l.start}` : `${l.start}-${l.end}`);
+/** Why the region is like this (#3034): the decisions most relevant first, then who made each span of its current lines, then the gaps. */
+export function whyLines(doc, why) {
+    const out = [];
+    const record = (id) => {
+        const n = doc.nodes.find((x) => x.id === id);
+        return n && (n.kind === "decision" || n.kind === "work") ? n.record : id;
+    };
+    const runLabel = (id) => {
+        const r = doc.nodes.find((n) => n.kind === "run" && n.id === id);
+        if (!r)
+            return id;
+        const what = [r.harness?.name, r.model].filter(Boolean).join("/");
+        return `${r.run}${what ? ` (${what})` : r.recorded ? "" : " (not in the run ledger)"}${r.unit ? ` on ${r.unit}` : ""}`;
+    };
+    out.push(`why       ${why.explained ? "explained" : "unexplained"}${why.lines ? `, lines ${span(why.lines)}` : ""}`);
+    for (const d of why.decisions) {
+        out.push(`  decision  ${record(d.decision)} ${d.relevance}${d.lines > 0 ? `, ${d.lines} ${d.lines === 1 ? "line" : "lines"}` : ""}${d.current ? "" : ", superseded"}${d.closed ? ", closed" : ""}`);
+    }
+    for (const b of why.blame) {
+        const by = b.runs.length > 0 ? `; ${b.runs.map(runLabel).join(", ")}${b.narrowedBy ? " (by its hunks)" : ""}${b.joinedBy?.includes("patch-id") ? " (joined by content)" : ""}${b.via && b.via.length > 0 ? ` (squashed from ${b.via.map(short).join(", ")})` : ""}` : b.sha ? "; no run" : "";
+        out.push(`  lines     ${span(b)} ${b.sha ? short(b.sha) : "uncommitted"}${by}`);
+    }
+    for (const g of why.gaps)
+        out.push(`  gap       ${g.code}: ${g.message}${g.lines ? ` (lines ${g.lines.map(span).join(", ")})` : ""}`);
+    return out;
+}
+/** The walk as text, one line each, in the order of #2650 section B. */
+export function formatIntent(doc) {
+    const out = [];
+    const region = doc.nodes.find((n) => n.id === doc.region);
+    if (region?.kind === "region") {
+        const lines = region.lines ? `:${region.lines.start}${region.lines.end === region.lines.start ? "" : `-${region.lines.end}`}` : "";
+        const where = doc.at ? `at ${short(doc.at)}` : "in the working tree";
+        const symbol = region.symbol ? `#${region.symbol.name} (${region.symbol.kind} ${region.symbol.qualified}, lines ${region.lines ? span(region.lines) : "none"})` : lines;
+        out.push(`region    ${region.path}${symbol} (${region.type}, member ${region.member ?? "none"}${region.generated ? ", generated" : ""}) ${where}${region.node ? `, from node ${region.node}` : ""}`);
+    }
+    const files = ofKind(doc, "file");
+    if (files.length > 0)
+        out.push(`files     ${files.length} under the region, ${files.filter((f) => f.generated).length} generated`);
+    for (const d of ofKind(doc, "decision"))
+        out.push(decisionLine(d), ...withinLines(doc, d));
+    for (const w of ofKind(doc, "work"))
+        out.push(...workLines(doc, w));
+    for (const a of ofKind(doc, "artifact"))
+        out.push(artifactLine(doc, a));
+    for (const c of ofKind(doc, "commit"))
+        out.push(...commitLine(doc, c));
+    for (const l of ofKind(doc, "link")) {
+        const r = l.row;
+        out.push(`link      ${r.consumer} reads ${"producer" in r ? `${r.producer} ${r.output}` : r.input} (${r.status})`);
+    }
+    for (const f of ofKind(doc, "finding")) {
+        const by = f.addressedBy && f.addressedBy.length > 0 ? `; addressed by ${f.addressedBy.map((w) => `${w.id} (${w.state ?? "unknown"})`).join(", ")}` : "";
+        out.push(`finding   ${f.code}: ${f.message}${by}`);
+    }
+    for (const r of doc.reasons)
+        out.push(`reason    ${r.code}: ${r.message}`);
+    if (doc.why)
+        out.push(...whyLines(doc, doc.why));
+    const kinds = doc.kinds.length === 0 ? "; no --kind, so no decisions were read" : "";
+    const work = ofKind(doc, "work").length;
+    out.push(`${doc.summary.commits} commits, ${doc.summary.decisions} decisions, ${work > 0 ? `${work} work ${work === 1 ? "item" : "items"}, ` : ""}${doc.summary.artifacts} artifacts, ${doc.summary.findings} findings${kinds}`);
+    return out.join("\n");
+}
+/** The record walk as text: the record, its window, then each commit with its bucket, and the counts. */
+export function formatIntentRecord(doc) {
+    const r = doc.record;
+    const out = [`record    ${r.record} ${r.state ?? "stateless"}${r.supersededBy ? `, superseded by ${r.supersededBy}` : ""}: ${r.title ?? r.path}`];
+    out.push(`window    ${doc.window.from ? `from ${short(doc.window.from)}` : "no history"}${doc.window.until ? ` until ${short(doc.window.until)}` : ""}${r.decidedIn ? `; decided in ${short(r.decidedIn.sha)} ${r.decidedIn.date.slice(0, 10)}: ${r.decidedIn.subject}` : "; not decided in the history read"}`);
+    for (const c of r.constrains)
+        out.push(`entry     ${c.entry}${c.walked ? "" : c.exists === false ? " (not in the tree read)" : " (not walked)"}`);
+    for (const c of doc.commits) {
+        const why = c.bucket === "own"
+            ? c.unit !== null
+                ? `unit ${c.unit}`
+                : `carries ${[...(c.joins?.records ?? []).filter((x) => x.node !== null).map((x) => `${x.kind}:${x.id}`), ...(c.joins?.lease?.item ? [`lease on ${c.joins.lease.item}`] : [])].join(", ")}`
+            : c.bucket === "worked"
+                ? `worked by ${c.workedBy.map((w) => w.record).join(", ")}`
+                : c.bucket === "within-other"
+                    ? `within ${c.alsoWithin.map((w) => w.record).join(", ")}`
+                    : "nothing else accounts for it";
+        const runs = (c.runs ?? []).map((r) => `run ${r.id}${r.model ? ` (${r.model})` : ""}${r.joinedBy?.includes("squash") && !r.joinedBy.some((j) => j !== "squash") ? " through the squash" : ""}`).join(", ");
+        const squash = c.squash ? `; squash of #${c.squash.pullRequest}${c.squash.followed ? `, ${c.squash.commits.length} original ${c.squash.commits.length === 1 ? "commit" : "commits"}` : ", not followed"}` : "";
+        out.push(`${c.bucket.padEnd(12)} ${short(c.sha)} ${c.date.slice(0, 10)} ${c.subject}; ${why}${runs ? `; ${runs}` : ""}${squash}; ${c.files.join(", ") || c.entries.join(", ")}`);
+    }
+    for (const x of doc.reasons)
+        out.push(`reason    ${x.code}: ${x.message}`);
+    const n = doc.counts;
+    out.push(`${n.commits} commits in the window: ${n.own} own, ${n.worked} worked, ${n.withinOther} within another record's window, ${n.unexplained} unexplained; ${n.outsideWindow} outside it`);
+    return out.join("\n");
+}
+async function runRecord(ctx, cwd, kinds) {
+    const { args } = ctx;
+    const { doc, failed } = await intentRecord({ cwd, record: args.record, at: args.at, kinds: kinds?.map((k) => resolve(k)), followSquash: args.followSquash });
+    if (args.json)
+        console.log(JSON.stringify(doc, null, 2));
+    if ("error" in doc) {
+        console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: RECORD_USAGE }));
+        return 1;
+    }
+    if (!args.json)
+        console.log(formatIntentRecord(doc));
+    return failed ? 1 : 0;
+}
+export async function runWorkspaceIntent(ctx, cwd) {
+    const { args } = ctx;
+    if (args.record !== undefined) {
+        if (args.intent) {
+            console.error(formatError({ message: "--record walks a record, so --intent takes no region with it", hint: RECORD_USAGE }));
+            return 1;
+        }
+        return runRecord(ctx, cwd, args.kinds ?? (args.kind !== undefined ? [args.kind] : undefined));
+    }
+    if (!args.intent) {
+        console.error(formatError({ message: "--intent needs a region: a path, path:line, path:start-end or path#symbol", hint: USAGE }));
+        return 1;
+    }
+    // No --kind: undefined, so the walk reads the kinds the declaration names (#2680).
+    const kinds = args.kinds ?? (args.kind !== undefined ? [args.kind] : undefined);
+    const { doc, failed } = await intentGraph({ cwd, region: args.intent, at: args.at, kinds: kinds?.map((k) => resolve(k)), followSquash: args.followSquash });
+    if (args.json)
+        console.log(JSON.stringify(doc, null, 2));
+    if ("error" in doc) {
+        console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));
+        return 1;
+    }
+    if (!args.json)
+        console.log(formatIntent(doc));
+    return failed ? 1 : 0;
+}

package/dist/workspace/intent-joins.js

@@ -0,0 +1,201 @@
+/**
+ * The commit-join hook of the intent graph (#2651; #2650 C1 and C13).
+ *
+ * Commits, decisions and artifacts come from core. Units of work, contracts
+ * and evidence come from a plugin, such as a workspace's own development
+ * model, because core ships no model of them (#2555, "Core ships no decision
+ * kind"). A kind file passed to `chant workspace graph --intent --kind <file>`
+ * supplies them through one export, `commitJoins`, in one of two forms:
+ *
+ * - A function `commitJoins(commit, context)` that returns the unit, contract
+ *   and evidence for one commit, or nothing. It is given the commit's sha,
+ *   subject, body, author, date and trailers, and a context whose `read(path)`
+ *   returns a file and whose `list(dir)` lists a directory, both in the tree
+ *   read (#2663). With `list` a plugin can find the record that names a
+ *   commit, such as a unit record whose `result.commit` is the commit's sha,
+ *   so the commit needs no trailer at all.
+ * - Data, which core interprets with no plugin code: the trailer keys that
+ *   name a unit, a contract or evidence, the record paths to read for each
+ *   (`units/{id}.json`), and the trailer keys that claim authorship. Every
+ *   value of the evidence trailer is read; a unit or contract trailer gives
+ *   its first value, since a commit has one unit and one contract.
+ *
+ * Either way core never parses a plugin's own trailer or record format: it
+ * reads the trailers git reports and hands them over, and a key means
+ * something only because a kind file said so.
+ *
+ * Two parts of a join's answer carry meaning core acts on (#2656). A unit or
+ * contract may list `decisions`, the ids of the decision records it carries
+ * out; a commit whose unit or contract names a decision is that decision's own
+ * work. The function form may also return `findings`, each a code in the
+ * kind's own namespace (`plugin:<name>:<code>`), a message and the refs it is
+ * about, which the graph carries as finding nodes. That is how a plugin says
+ * what it knows and core does not, such as a contract whose criteria changed
+ * in a commit that names no decision.
+ *
+ * `<name>` is the kind's name by default: its record kind's name, or the
+ * file's name without `.kind.mjs`. A kind file may name its findings itself
+ * with a sibling export, `commitJoinsName` (#2663), so joins that live beside
+ * a record kind called `decision` can still report `plugin:acme:<code>`. It is
+ * a sibling export rather than a property because the data form is a closed
+ * object whose keys are all joins, and a function's `name` property is
+ * already its own name.
+ */
+import { z } from "zod";
+import { isPluginCode } from "./reason-codes.js";
+const trailerKey = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9-]*$/, "a trailer key holds letters, digits and dashes");
+const recordPath = z.string().min(1).refine((p) => p.includes("{id}") && !p.startsWith("/") && !p.split("/").includes(".."), "a record path is relative to the workspace root and holds {id}");
+/** The data form of `commitJoins`. */
+export const commitJoinsDataSchema = z
+    .object({
+    /** The trailer whose value is the id of the unit, contract or evidence. */
+    trailers: z.object({ unit: trailerKey.optional(), contract: trailerKey.optional(), evidence: trailerKey.optional() }).strict(),
+    /** Where each is recorded, from the workspace root, with `{id}` for the id. A JSON file there adds its fields. */
+    records: z.object({ unit: recordPath.optional(), contract: recordPath.optional(), evidence: recordPath.optional() }).strict().optional(),
+    /** Trailer keys that claim authorship, checked against the commit's provenance. */
+    authorship: z.array(trailerKey).optional(),
+})
+    .strict();
+/** What a `commitJoinsName` may be: the `<name>` of `plugin:<name>:<code>`. */
+const JOINS_NAME = /^[^:\s]+$/;
+/**
+ * Read a kind module's `commitJoins` export and its `commitJoinsName`.
+ * Undefined when it has no `commitJoins`; a string when either is malformed,
+ * or when it names findings it has no joins for.
+ */
+export function readCommitJoins(mod) {
+    const value = mod.commitJoins;
+    const name = mod.commitJoinsName;
+    if (value === undefined)
+        return name === undefined ? undefined : "commitJoinsName: a kind file with no commitJoins has no findings to name";
+    if (name !== undefined && (typeof name !== "string" || !JOINS_NAME.test(name)))
+        return "commitJoinsName: a string with no colon or space, the <name> of plugin:<name>:<code>";
+    const named = name === undefined ? {} : { name: name };
+    if (typeof value === "function")
+        return { form: "function", join: value, ...named };
+    const parsed = commitJoinsDataSchema.safeParse(value);
+    if (!parsed.success)
+        return parsed.error.issues.map((i) => `commitJoins${i.path.length ? `.${i.path.join(".")}` : ""}: ${i.message}`).join("; ");
+    return { form: "data", data: parsed.data, ...named };
+}
+/** Every value of trailer `key`, trimmed, without empty ones or repeats, compared without case as git does. */
+export function trailerValues(trailers, key) {
+    const want = key.toLowerCase();
+    const out = [];
+    for (const [k, values] of Object.entries(trailers)) {
+        if (k.toLowerCase() !== want)
+            continue;
+        for (const v of values) {
+            const t = v.trim();
+            if (t && !out.includes(t))
+                out.push(t);
+        }
+    }
+    return out;
+}
+/** The first value of trailer `key`, compared without case as git does. */
+export function trailerValue(trailers, key) {
+    return trailerValues(trailers, key)[0];
+}
+/** Whether the commit carries trailer `key`. */
+export function hasTrailer(trailers, key) {
+    const want = key.toLowerCase();
+    return Object.keys(trailers).some((k) => k.toLowerCase() === want);
+}
+function recordFields(template, id, context) {
+    if (!template)
+        return {};
+    const text = context.read(template.split("{id}").join(id));
+    if (text === undefined)
+        return {};
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`${template.split("{id}").join(id)} is not JSON`);
+    }
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return {};
+    const { id: _id, ...rest } = value;
+    return rest;
+}
+/** Interpret the data form for one commit. Throws when a named record can't be read as JSON. */
+export function joinByData(data, commit, context) {
+    const out = {};
+    const entity = (part, id) => ({ ...recordFields(data.records?.[part], id, context), id });
+    for (const part of ["unit", "contract"]) {
+        const key = data.trailers[part];
+        const id = key ? trailerValue(commit.trailers, key) : undefined;
+        if (id)
+            out[part] = entity(part, id);
+    }
+    // Each value of the evidence trailer is one piece of evidence (#2663).
+    const evidence = data.trailers.evidence ? trailerValues(commit.trailers, data.trailers.evidence) : [];
+    if (evidence.length > 0)
+        out.evidence = evidence.map((id) => entity("evidence", id));
+    const claimed = (data.authorship ?? []).filter((k) => hasTrailer(commit.trailers, k));
+    if (claimed.length > 0)
+        out.authorship = claimed;
+    return out;
+}
+/** The record ids a unit or contract says it carries out: its `decisions` field, when that is a list of strings. */
+export function entityDecisions(entity) {
+    const list = entity?.decisions;
+    return Array.isArray(list) ? list.filter((d) => typeof d === "string" && d !== "") : [];
+}
+/**
+ * Run a kind's joins for one commit, checking what a function returns.
+ * `name` is the namespace its findings' codes must use: the kind file's
+ * `commitJoinsName`, or else the kind's name.
+ */
+export async function runCommitJoins(joins, commit, context, name) {
+    if (joins.form === "data")
+        return joinByData(joins.data, commit, context);
+    const result = await joins.join(commit, context);
+    if (result === null || result === undefined)
+        return {};
+    if (typeof result !== "object")
+        throw new Error("commitJoins returned something that is not an object");
+    const entity = (v, what) => {
+        if (v === undefined || v === null)
+            return undefined;
+        if (typeof v !== "object" || Array.isArray(v) || typeof v.id !== "string" || v.id === "") {
+            throw new Error(`commitJoins returned a ${what} with no string id`);
+        }
+        return v;
+    };
+    const out = {};
+    const unit = entity(result.unit, "unit");
+    const contract = entity(result.contract, "contract");
+    if (unit)
+        out.unit = unit;
+    if (contract)
+        out.contract = contract;
+    if (result.evidence !== undefined && result.evidence !== null) {
+        const list = Array.isArray(result.evidence) ? result.evidence : [result.evidence];
+        out.evidence = list.map((e) => entity(e, "evidence")).filter(Boolean);
+    }
+    if (result.authorship !== undefined) {
+        if (!Array.isArray(result.authorship) || !result.authorship.every((k) => typeof k === "string"))
+            throw new Error("commitJoins returned authorship that is not a list of trailer keys");
+        out.authorship = result.authorship;
+    }
+    if (result.findings !== undefined && result.findings !== null) {
+        if (!Array.isArray(result.findings))
+            throw new Error("commitJoins returned findings that are not a list");
+        out.findings = result.findings.map((f) => {
+            if (f === null || typeof f !== "object" || Array.isArray(f))
+                throw new Error("commitJoins returned a finding that is not an object");
+            const { code, message, refs } = f;
+            if (!isPluginCode(code, name))
+                throw new Error(`commitJoins returned the finding code ${JSON.stringify(code)}, and a plugin's codes are plugin:${name}:<code>, with <code> in lower case words joined by dashes`);
+            if (typeof message !== "string" || message === "")
+                throw new Error(`commitJoins returned the finding ${code} with no message`);
+            if (refs !== undefined && (!Array.isArray(refs) || !refs.every((r) => typeof r === "string")))
+                throw new Error(`commitJoins returned the finding ${code} with refs that are not a list of strings`);
+            return { code, message, refs: refs ?? [] };
+        });
+    }
+    return out;
+}