@intentius/chant 0.124.30 → 0.124.32

package/src/workspace/ci-run-index.schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/ci-run-index/v1/ci-run-index.schema.json",
+  "title": "chant ci run index",
+  "description": "The runs the chant runner has run, kept at <report-url>/runs/index.json (#4098, epic #4101) so a reader outside CI finds them without a forge or a workflow file. `chant ci run` adds an entry to the front after each job settles when --report-url is set, so the list is newest first, and keeps the newest 200 entries unless --run-index-limit says otherwise. `chant ci runs --json` prints the same document. An entry's `key` is the folder the job's report is under, below the report URL. The update is a read, a change and a write of the whole file, through the same s3:// and file:// paths the report upload uses; a file:// write goes through a temporary name and a rename. Two runners updating one index at once can lose an entry. That is out of scope, because `chant ci serve` is one host. Version 1 of the workspace read contract. Readers ignore fields they do not know; a field is only ever added within a version. Written by chant 0.124.31 and newer. Added within contract 1 at chant 0.124.32: an entry's signer (#4156) and exitCode (#4165); an entry from an older chant lacks them.",
+  "type": "object",
+  "required": ["$schema", "contract", "chant", "updated", "runs"],
+  "properties": {
+    "$schema": { "const": "https://intentius.io/chant/schemas/workspace/ci-run-index/v1/ci-run-index.schema.json" },
+    "contract": { "const": 1 },
+    "chant": { "type": "string", "description": "The chant that last wrote the index." },
+    "updated": { "type": "string", "description": "When the index was last written." },
+    "runs": {
+      "type": "array",
+      "description": "Newest first, at most the limit the writer was given (200 by default).",
+      "items": { "$ref": "#/$defs/run" }
+    }
+  },
+  "$defs": {
+    "run": {
+      "type": "object",
+      "required": ["job", "pr", "commit", "status", "started", "ended", "runId", "key", "runOrigin"],
+      "if": { "properties": { "status": { "const": "fail" } } },
+      "then": { "required": ["failure"], "properties": { "failure": { "type": "object" } } },
+      "properties": {
+        "job": { "enum": ["plan", "apply"] },
+        "pr": { "type": ["integer", "null"], "minimum": 1, "description": "The pull or merge request number: the one the job's report names, else --pr. null when neither has one." },
+        "commit": { "type": "string", "pattern": "^[0-9a-f]{40,64}$", "description": "The full commit the job ran at." },
+        "status": { "enum": ["ok", "fail"] },
+        "failure": {
+          "type": "object",
+          "required": ["code"],
+          "description": "Present when status is fail. The same code the run record's failure carries: setup-failed, build-failed, a report's refusal or status, or command-failed.",
+          "properties": { "code": { "type": "string" } }
+        },
+        "member": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,39}$", "description": "The workspace member whose pipeline the job ran for. Absent outside a member." },
+        "started": { "type": "string", "description": "ISO-8601 instant the job started." },
+        "ended": { "type": "string", "description": "ISO-8601 instant the job settled." },
+        "runId": { "type": "string", "description": "The Op run id, as in the run ledger on chant/lifecycle." },
+        "key": { "type": "string", "description": "reportKey(pr, commit): <pr>/<commit>, with /<member> after for a member, and unknown for a missing pr. The job's report is <report-url>/<key>/pr-<job>.json." },
+        "signer": { "type": ["string", "null"], "description": "Added within contract 1 by #4156, written by chant 0.124.32 and newer. The runner whose key signed the run's record, or null for an unsigned run. Signing is optional, and an unsigned run is listed like any other." },
+        "exitCode": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Added within contract 1 by #4165, written by chant 0.124.32 and newer. The code chant ci run exited with for the job: 0 for a passed job, else the command's own code when it is 1 to 255, such as 3 for a plan that moved after review or a wave waiting at its gate, else 1. A reader tells a held run from a failed one by it when the report carries no refusal. An entry from an older chant lacks it." },
+        "runOrigin": {
+          "type": "object",
+          "required": ["forge"],
+          "description": "Where the run says it ran. { forge: \"chant\" } for a job the chant runner ran. From chant 0.124.32 a forge job that runs chant ci run names the forge's run (#4156): forge github (GitHub and Forgejo) or gitlab, with repo, url, jobId and attempt when the forge gives them.",
+          "properties": { "forge": { "type": "string" }, "repo": { "type": "string" }, "url": { "type": "string" }, "jobId": { "type": "string" }, "attempt": { "type": "integer", "minimum": 1 } }
+        }
+      }
+    }
+  }
+}

package/src/workspace/ci-run-index.test.ts

@@ -0,0 +1,392 @@
+/**
+ * #4098: the run index `chant ci run --report-url` keeps at the report URL.
+ *
+ * The runs are real `ci run` jobs in a temp repository with a stub chant and
+ * a file:// report URL in another temp directory. The jobs do not push, so
+ * nothing reaches chant/lifecycle or a remote. No test makes a network call.
+ */
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { afterAll, describe, expect, test } from "vitest";
+import { cleanScratch, contract, declaration, git, repoFixture, scratchDir, validSchema, writeFiles } from "./__fixtures__/contract-repo";
+import { ciJobExitCode, ciRun } from "./ci-run";
+import { readCiSecrets } from "./ci-secrets";
+import {
+  addRunEntry,
+  CI_RUN_INDEX_KEY,
+  CI_RUN_INDEX_LIMIT,
+  CI_RUN_INDEX_SCHEMA_ID,
+  formatCiRunIndex,
+  readCiRunIndex,
+  updateCiRunIndex,
+  type CiRunIndex,
+  type CiRunIndexEntry,
+} from "./ci-run-index";
+import { parseReportUrl, reportGet, reportKey, type ReportTarget } from "../pr-report-url";
+import schema from "./ci-run-index.schema.json";
+
+afterAll(cleanScratch);
+
+const JOB_IMAGE = "chant-ci-run-index-test:local";
+const HOST = { PATH: process.env.PATH, HOME: process.env.HOME, GITHUB_TOKEN: "t", GITHUB_REPOSITORY: "acme/estate" };
+
+/** The repository every test starts from, built once: one member, and two commits. */
+const repoTemplate = repoFixture(() => {
+  const root = scratchDir("chant-ci-run-index-template-");
+  git(root, "init", "-q");
+  git(root, "symbolic-ref", "HEAD", "refs/heads/main");
+  git(root, "config", "user.name", "t");
+  git(root, "config", "user.email", "t@example.com");
+  writeFiles(root, {
+    "chant.workspace.json": declaration([{ name: "app", dir: "app", kind: "other", because: "the app" }]),
+    ".gitignore": ".chant/pr/\n",
+    "app/a.txt": "a\n",
+  });
+  const commit = (msg: string) => {
+    execFileSync("git", ["-c", "commit.gpgsign=false", "add", "-A"], { cwd: root, stdio: "ignore" });
+    execFileSync("git", ["-c", "commit.gpgsign=false", "commit", "-q", "-m", msg], { cwd: root, stdio: "ignore" });
+    return git(root, "rev-parse", "HEAD");
+  };
+  commit("init");
+  writeFiles(root, { "app/a.txt": "b\n" });
+  commit("change");
+  return root;
+}, "chant-ci-run-index-");
+
+/** A repository with one member, and a stub chant that writes the report FAKE_REPORT gives it and exits $FAKE_EXIT. */
+function workspace(): { app: string; base: string; sha: string; chant: string } {
+  const root = repoTemplate();
+  const base = git(root, "rev-parse", "HEAD~1");
+  const sha = git(root, "rev-parse", "HEAD");
+  const file = join(scratchDir("chant-ci-run-index-bin-"), "chant");
+  writeFileSync(
+    file,
+    [
+      "#!/bin/sh",
+      "mkdir -p .chant/pr",
+      'if [ -n "$FAKE_REPORT" ]; then printf "%s" "$FAKE_REPORT" > ".chant/pr/$2.json"; else echo "{}" > ".chant/pr/$2.json"; fi',
+      'exit "${FAKE_EXIT:-0}"',
+      "",
+    ].join("\n"),
+  );
+  chmodSync(file, 0o755);
+  return { app: join(root, "app"), base, sha, chant: file };
+}
+
+const reportsDir = () => scratchDir("chant-ci-run-index-reports-");
+const urlOf = (dir: string) => pathToFileURL(dir).href;
+const indexOf = (dir: string): CiRunIndex => JSON.parse(readFileSync(join(dir, CI_RUN_INDEX_KEY), "utf-8"));
+
+const { expectValid } = contract(schema);
+
+async function job(w: ReturnType<typeof workspace>, dir: string, over: Partial<Parameters<typeof ciRun>[0]> & { hostEnv?: Record<string, string | undefined> } = {}) {
+  return ciRun({
+    image: JOB_IMAGE,
+    cwd: w.app,
+    job: "plan",
+    env: "prod",
+    forge: "forgejo",
+    base: w.base,
+    pr: 7,
+    chant: w.chant,
+    hostEnv: HOST,
+    push: false,
+    output: join(scratchDir("chant-ci-run-index-out-"), "pr"),
+    loop: { reportUrl: urlOf(dir) },
+    ...over,
+  });
+}
+
+const ENTRY: CiRunIndexEntry = {
+  job: "plan",
+  pr: 1,
+  commit: "a".repeat(40),
+  status: "ok",
+  started: "2026-10-18T12:00:00.000Z",
+  ended: "2026-10-18T12:00:01.000Z",
+  runId: "r0",
+  key: reportKey(1, "a".repeat(40)),
+  runOrigin: { forge: "chant" },
+};
+
+describe("the ci-run-index schema (#4098)", () => {
+  test("is a valid schema with the contract's id", () => {
+    expect(validSchema(schema)).toBe(true);
+    expect(schema.$id).toBe(CI_RUN_INDEX_SCHEMA_ID);
+  });
+
+  test("a failed entry without a failure code does not validate", () => {
+    const doc = { $schema: CI_RUN_INDEX_SCHEMA_ID, contract: 1, chant: "0.124.30", updated: "2026-10-18T12:00:00.000Z", runs: [{ ...ENTRY, status: "fail" }] };
+    expect(contract(schema).validate(doc)).toBe(false);
+    expectValid({ ...doc, runs: [{ ...ENTRY, status: "fail", failure: { code: "command-failed" } }] });
+  });
+
+  test("exitCode is an integer from 0 to 255, and an index whose older entries lack it validates (#4165)", () => {
+    const doc = { $schema: CI_RUN_INDEX_SCHEMA_ID, contract: 1, chant: "0.124.32", updated: "2026-10-18T12:00:00.000Z" };
+    // A newer entry beside two from chant 0.124.31, which wrote neither signer nor exitCode.
+    expectValid({ ...doc, runs: [{ ...ENTRY, runId: "r2", signer: null, exitCode: 0 }, { ...ENTRY, runId: "r1" }, { ...ENTRY, status: "fail", failure: { code: "command-failed" } }] });
+    for (const exitCode of [-1, 256, 1.5, "3"]) expect(contract(schema).validate({ ...doc, runs: [{ ...ENTRY, exitCode }] })).toBe(false);
+  });
+});
+
+describe("chant ci run with --report-url keeps the run index (#4098)", () => {
+  test("the index is created, grows newest first, carries every field and validates", async () => {
+    const w = workspace();
+    const dir = reportsDir();
+    const plan = await job(w, dir, { runId: "run-plan" });
+    expect(plan.status).toBe("ok");
+    expect(plan.warnings).toEqual([]);
+    const apply = await job(w, dir, { job: "apply", pr: undefined, runId: "run-apply", hostEnv: { ...HOST, FAKE_REPORT: JSON.stringify({ pr: 7, status: "applied" }) }, passEnv: ["FAKE_REPORT"] });
+    expect(apply.status).toBe("ok");
+
+    const index = indexOf(dir);
+    expectValid(index);
+    expect(index.runs.map((r) => r.runId)).toEqual(["run-apply", "run-plan"]);
+    expect(index.runs[1]).toEqual({
+      job: "plan",
+      pr: 7,
+      commit: w.sha,
+      status: "ok",
+      started: plan.record.started,
+      ended: plan.record.ended,
+      runId: "run-plan",
+      key: `7/${w.sha}/app`,
+      member: "app",
+      runOrigin: { forge: "chant" },
+      // #4156: no key, and the run is listed all the same, with no signer.
+      signer: null,
+      // #4165: the code ci run exited with.
+      exitCode: 0,
+    });
+    // The apply found its pull request in its own report.
+    expect(index.runs[0]).toMatchObject({ job: "apply", pr: 7, key: `7/${w.sha}/app` });
+    expect(readdirSync(join(dir, "runs"))).toEqual(["index.json"]);
+    expect(formatCiRunIndex(index).split("\n")).toHaveLength(2);
+  });
+
+  test("a job with no pull request is keyed unknown", async () => {
+    const w = workspace();
+    const dir = reportsDir();
+    await job(w, dir, { job: "apply", pr: undefined, runId: "r-apply" });
+    const [run] = indexOf(dir).runs;
+    expect(run).toMatchObject({ pr: null, key: `unknown/${w.sha}/app` });
+    expectValid(indexOf(dir));
+  });
+
+  test("the index keeps the newest entries up to the limit", async () => {
+    const w = workspace();
+    const dir = reportsDir();
+    for (const n of [1, 2, 3]) await job(w, dir, { runId: `run-${n}`, runIndexLimit: 2 });
+    expect(indexOf(dir).runs.map((r) => r.runId)).toEqual(["run-3", "run-2"]);
+    expect(CI_RUN_INDEX_LIMIT).toBe(200);
+  });
+
+  test("a failed job carries its failure code", async () => {
+    const w = workspace();
+    const dir = reportsDir();
+    const failed = await job(w, dir, { runId: "run-fail", hostEnv: { ...HOST, FAKE_EXIT: "3" }, passEnv: ["FAKE_EXIT"] });
+    expect(failed.status).toBe("fail");
+    const [run] = indexOf(dir).runs;
+    expect(run).toMatchObject({ status: "fail", failure: { code: "command-failed" }, runId: "run-fail", exitCode: 3 });
+    expectValid(indexOf(dir));
+
+    const refused = await job(w, dir, {
+      job: "apply",
+      runId: "run-refused",
+      hostEnv: { ...HOST, FAKE_EXIT: "1", FAKE_REPORT: JSON.stringify({ pr: 7, status: "refused", refusal: "not-approved" }) },
+      passEnv: ["FAKE_EXIT", "FAKE_REPORT"],
+    });
+    expect(refused.status).toBe("fail");
+    expect(indexOf(dir).runs[0]).toMatchObject({ failure: { code: "not-approved" }, exitCode: 1 });
+  });
+
+  test("each entry records the code ci run exited with: 0, 1, and 3 for a moved plan or a waiting wave (#4165)", async () => {
+    const w = workspace();
+    const dir = reportsDir();
+    const run = (runId: string, exit: string, report: object) =>
+      job(w, dir, { job: "apply", runId, hostEnv: { ...HOST, FAKE_EXIT: exit, FAKE_REPORT: JSON.stringify({ pr: 7, ...report }) }, passEnv: ["FAKE_EXIT", "FAKE_REPORT"] });
+    const passed = await run("run-ok", "0", { status: "applied" });
+    const failed = await run("run-failed", "1", { status: "failed" });
+    const moved = await run("run-moved", "3", { status: "refused", refusal: "plan-changed", message: "the plan changed after review" });
+    const waiting = await run("run-waiting", "3", { status: "waiting", waves: [{ wave: 2, status: "waiting" }] });
+    expect([passed, failed, moved, waiting].map((r) => ciJobExitCode(r))).toEqual([0, 1, 3, 3]);
+    const index = indexOf(dir);
+    expectValid(index);
+    expect(index.runs.map((r) => [r.runId, r.status, r.exitCode])).toEqual([
+      ["run-waiting", "fail", 3],
+      ["run-moved", "fail", 3],
+      ["run-failed", "fail", 1],
+      ["run-ok", "ok", 0],
+    ]);
+    expect(index.runs[1]!.failure).toEqual({ code: "plan-changed" });
+  });
+
+  test("a fail with no code from its command, or one outside 1 to 255, is 1, and a pass is 0 (#4165)", () => {
+    expect(ciJobExitCode({ status: "fail" })).toBe(1);
+    expect(ciJobExitCode({ status: "fail", exitCode: 0 })).toBe(1);
+    expect(ciJobExitCode({ status: "fail", exitCode: 300 })).toBe(1);
+    expect(ciJobExitCode({ status: "ok", exitCode: 3 })).toBe(0);
+  });
+
+  test("a secret the job's report names as its failure never reaches the index (#4096)", async () => {
+    const w = workspace();
+    const dir = reportsDir();
+    const SECRET = "s3cret-pass-1";
+    const secretsFile = join(scratchDir("chant-ci-run-index-secrets-"), "secrets.env");
+    writeFileSync(secretsFile, `DB_PASSWORD=${SECRET}\n`, { mode: 0o600 });
+    const leaky = join(scratchDir("chant-ci-run-index-bin-"), "chant");
+    writeFileSync(
+      leaky,
+      [
+        "#!/bin/sh",
+        "mkdir -p .chant/pr",
+        // The refusal becomes the index's failure code, and the message and output carry the secret too.
+        'printf \'{"stage":"apply","pr":7,"status":"refused","refusal":"denied-%s","message":"failed with %s"}\' "$DB_PASSWORD" "$DB_PASSWORD" > .chant/pr/pr-apply.json',
+        'echo "login refused for $DB_PASSWORD" >&2',
+        "exit 3",
+        "",
+      ].join("\n"),
+    );
+    chmodSync(leaky, 0o755);
+    const r = await job(w, dir, { job: "apply", chant: leaky, runId: "run-leak", secrets: readCiSecrets(secretsFile) });
+    expect(r.status).toBe("fail");
+    const text = readFileSync(join(dir, CI_RUN_INDEX_KEY), "utf-8");
+    expect(text).not.toContain(SECRET);
+    expect(indexOf(dir).runs[0]).toMatchObject({ status: "fail", failure: { code: "denied-***" } });
+    expectValid(indexOf(dir));
+  });
+
+  test("a corrupt index is replaced with a warning and the job stays ok", async () => {
+    const w = workspace();
+    const dir = reportsDir();
+    mkdirSync(join(dir, "runs"));
+    writeFileSync(join(dir, CI_RUN_INDEX_KEY), "{ not json");
+    const r = await job(w, dir, { runId: "run-after-corrupt" });
+    expect(r.status).toBe("ok");
+    expect(r.warnings).toHaveLength(1);
+    expect(r.warnings[0]).toMatch(/run index at .*runs\/index\.json is replaced, since it is not JSON/);
+    expect(indexOf(dir).runs.map((x) => x.runId)).toEqual(["run-after-corrupt"]);
+    expectValid(indexOf(dir));
+  });
+
+  test("an index that cannot be read or written warns and leaves the job ok", async () => {
+    const w = workspace();
+    const dir = reportsDir();
+    // A file where the runs folder goes: the index can be neither read nor written.
+    writeFileSync(join(dir, "runs"), "in the way");
+    const r = await job(w, dir, { runId: "run-blocked" });
+    expect(r.status).toBe("ok");
+    expect(r.warnings).toHaveLength(1);
+    expect(r.warnings[0]).toMatch(/could not read the run index at .*, so it is not updated/);
+    expect(readFileSync(join(dir, "runs"), "utf-8")).toBe("in the way");
+  });
+
+  test("a report URL that does not parse warns, and without --report-url nothing is written", async () => {
+    const w = workspace();
+    const bad = await job(w, reportsDir(), { loop: { reportUrl: "ftp://example.invalid/x" } });
+    expect(bad.status).toBe("ok");
+    expect(bad.warnings[0]).toMatch(/the run index is not updated: --report-url ftp/);
+    const dir = reportsDir();
+    const none = await job(w, dir, { loop: {} });
+    expect(none.warnings).toEqual([]);
+    expect(existsSync(join(dir, "runs"))).toBe(false);
+  });
+});
+
+describe("updating the index", () => {
+  const target = (dir: string): ReportTarget => parseReportUrl(urlOf(dir)) as ReportTarget;
+
+  test("an upload error warns and nothing throws", async () => {
+    const warnings: string[] = [];
+    await updateCiRunIndex({
+      target: target(reportsDir()),
+      entry: ENTRY,
+      warn: (m) => warnings.push(m),
+      put: async () => {
+        throw new Error("aws s3 cp exited 1: AccessDenied");
+      },
+    });
+    expect(warnings).toEqual([expect.stringMatching(/could not write the run index at .*: aws s3 cp exited 1: AccessDenied/)]);
+  });
+
+  test("a read error other than a missing object leaves the index alone", async () => {
+    const warnings: string[] = [];
+    let wrote = false;
+    await updateCiRunIndex({
+      target: target(reportsDir()),
+      entry: ENTRY,
+      warn: (m) => warnings.push(m),
+      get: async () => {
+        throw new Error("aws s3 cp exited 1: AccessDenied");
+      },
+      put: async () => {
+        wrote = true;
+      },
+    });
+    expect(wrote).toBe(false);
+    expect(warnings[0]).toMatch(/could not read the run index/);
+  });
+
+  test("an index of a newer contract is left as it is", async () => {
+    const warnings: string[] = [];
+    let wrote = false;
+    await updateCiRunIndex({
+      target: target(reportsDir()),
+      entry: ENTRY,
+      warn: (m) => warnings.push(m),
+      get: async () => JSON.stringify({ contract: 2, runs: [] }),
+      put: async () => {
+        wrote = true;
+      },
+    });
+    expect(wrote).toBe(false);
+    expect(warnings[0]).toMatch(/is contract 2, which this chant does not write/);
+  });
+
+  test("updates in one process take turns, and a run id is kept once", async () => {
+    const dir = reportsDir();
+    const warn = (m: string) => {
+      throw new Error(m);
+    };
+    await Promise.all([1, 2, 3, 4].map((n) => updateCiRunIndex({ target: target(dir), entry: { ...ENTRY, runId: `r${n}` }, warn })));
+    expect(indexOf(dir).runs.map((r) => r.runId).sort()).toEqual(["r1", "r2", "r3", "r4"]);
+    await updateCiRunIndex({ target: target(dir), entry: { ...ENTRY, runId: "r2", status: "fail", failure: { code: "x" } }, warn });
+    const runs = indexOf(dir).runs;
+    expect(runs).toHaveLength(4);
+    expect(runs[0]).toMatchObject({ runId: "r2", status: "fail" });
+    expect(addRunEntry([ENTRY], { ...ENTRY, runId: "r9" }, 1).map((r) => r.runId)).toEqual(["r9"]);
+  });
+
+  test("the file write goes through a rename, so no temporary file is left", async () => {
+    const dir = reportsDir();
+    await updateCiRunIndex({ target: target(dir), entry: ENTRY, warn: () => {} });
+    expect(readdirSync(join(dir, "runs"))).toEqual(["index.json"]);
+  });
+
+  test("readCiRunIndex reads what was written, null for none, and says why for a bad one", async () => {
+    const dir = reportsDir();
+    expect(await readCiRunIndex(target(dir))).toBeNull();
+    await updateCiRunIndex({ target: target(dir), entry: ENTRY, warn: () => {} });
+    expect((await readCiRunIndex(target(dir)))?.runs).toEqual([ENTRY]);
+    writeFileSync(join(dir, CI_RUN_INDEX_KEY), "nope");
+    await expect(readCiRunIndex(target(dir))).rejects.toThrow(/is unusable: it is not JSON/);
+  });
+
+  test("an s3 get treats a missing object as none, with a stub in place of the AWS CLI", async () => {
+    const s3 = parseReportUrl("s3://bucket/prefix") as ReportTarget;
+    const calls: string[][] = [];
+    const absent = reportGet(s3, async (args) => {
+      calls.push(args);
+      throw new Error("aws s3 cp exited 1: An error occurred (404) when calling the HeadObject operation: Key not found");
+    });
+    expect(await absent(CI_RUN_INDEX_KEY)).toBeNull();
+    expect(calls[0]).toEqual(["s3", "cp", "s3://bucket/prefix/runs/index.json", "-", "--only-show-errors"]);
+    const denied = reportGet(s3, async () => {
+      throw new Error("aws s3 cp exited 1: AccessDenied");
+    });
+    await expect(denied(CI_RUN_INDEX_KEY)).rejects.toThrow(/AccessDenied/);
+  });
+});

package/src/workspace/ci-run-index.ts

@@ -0,0 +1,206 @@
+/**
+ * The run index (#4098, epic #4101): where the chant runner says which jobs it
+ * ran, at the `--report-url` root, for behold and the demo kiosk to find runs
+ * without a forge or a workflow file.
+ *
+ * ```
+ * <url>/runs/index.json
+ * ```
+ *
+ * One document, `ci-run-index/v1` (`ci-run-index.schema.json`). Each settled
+ * `chant ci run` job with `--report-url` set adds an entry to its front, so
+ * the newest run is first, and the list is cut to the newest `limit` entries,
+ * 200 by default. An entry's `key` is the folder the job's report went to
+ * (`reportKey`, `<pr>/<commit>`), so a reader goes from the index to
+ * `<url>/<key>/pr-<job>.json`.
+ *
+ * The update reads the index, changes it and writes it back through the same
+ * `file://` and `s3://` paths the report upload uses (pr-report-url.ts). A
+ * `file://` write goes through a temporary name and a rename. Two runners
+ * updating one index at once can lose an entry, and that is out of scope:
+ * `chant ci serve` is one host. Within one process the updates for one URL
+ * take turns, so `ci serve --max-jobs 2` does not race itself.
+ *
+ * An index that can't be parsed is replaced with a warning. An index this
+ * chant can't read for any other reason, or a newer contract, is left alone
+ * with a warning. Nothing here fails a job.
+ */
+
+import type { RunOrigin } from "../lifecycle/release-ledger";
+import type { CommandContext } from "../cli/registry";
+import { formatError } from "../cli/format";
+import { reportUrlOf } from "./ci-report-url";
+import { parseReportUrl, reportGet, reportPut, type ReportGet, type ReportPut, type ReportTarget } from "../pr-report-url";
+import { readerVersion } from "./declaration";
+
+export const CI_RUN_INDEX_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/ci-run-index/v1/ci-run-index.schema.json";
+export const CI_RUN_INDEX_CONTRACT = 1;
+/** The first chant that writes the index. */
+export const CI_RUN_INDEX_FLOOR = "0.124.31";
+/** Where the index is kept, below the report URL. */
+export const CI_RUN_INDEX_KEY = "runs/index.json";
+/** How many entries the index keeps unless told otherwise. */
+export const CI_RUN_INDEX_LIMIT = 200;
+
+/** One job the runner ran. */
+export interface CiRunIndexEntry {
+  job: "plan" | "apply";
+  /** The pull request, or null when the job found none. */
+  pr: number | null;
+  commit: string;
+  status: "ok" | "fail";
+  /** Why a failed job failed: the `failure.code` of its run record. */
+  failure?: { code: string };
+  member?: string;
+  started: string;
+  ended: string;
+  runId: string;
+  /** The folder the job's report is under, below the report URL: `<pr>/<commit>[/<member>]`. */
+  key: string;
+  runOrigin: RunOrigin;
+  /**
+   * The runner whose key signed the run's record, or null for an unsigned
+   * run (#4156). Written by chant 0.124.32 and newer; an entry from an older
+   * chant lacks it.
+   */
+  signer?: string | null;
+  /**
+   * The code `chant ci run` exited with for the job: 0, its command's own
+   * code such as 3 for a moved plan or a waiting wave, else 1 (#4165).
+   * Written by chant 0.124.32 and newer; an entry from an older chant lacks it.
+   */
+  exitCode?: number;
+}
+
+export interface CiRunIndex {
+  $schema: typeof CI_RUN_INDEX_SCHEMA_ID;
+  contract: typeof CI_RUN_INDEX_CONTRACT;
+  chant: string;
+  /** When the index was last written. */
+  updated: string;
+  /** Newest first. */
+  runs: CiRunIndexEntry[];
+}
+
+const messageOf = (err: unknown): string => (err instanceof Error ? err.message : String(err));
+
+/** The index as `text` holds it, or why it can't be used: `corrupt` is replaced, `newer` is left alone. */
+export function parseCiRunIndex(text: string): { index: CiRunIndex } | { corrupt: string } | { newer: number } {
+  let doc: unknown;
+  try {
+    doc = JSON.parse(text);
+  } catch (err) {
+    return { corrupt: `it is not JSON (${messageOf(err)})` };
+  }
+  if (doc === null || typeof doc !== "object" || Array.isArray(doc)) return { corrupt: "it is not an object" };
+  const d = doc as { contract?: unknown; runs?: unknown };
+  if (typeof d.contract === "number" && d.contract > CI_RUN_INDEX_CONTRACT) return { newer: d.contract };
+  if (d.contract !== CI_RUN_INDEX_CONTRACT) return { corrupt: "it is not a ci-run-index document" };
+  if (!Array.isArray(d.runs)) return { corrupt: "it has no runs list" };
+  const runs = d.runs.filter((r): r is CiRunIndexEntry => r !== null && typeof r === "object" && typeof (r as { runId?: unknown }).runId === "string");
+  return { index: { ...(doc as CiRunIndex), runs } };
+}
+
+/** `entry` at the front of `runs`, replacing an entry with its run id, cut to the newest `limit`. */
+export function addRunEntry(runs: readonly CiRunIndexEntry[], entry: CiRunIndexEntry, limit: number): CiRunIndexEntry[] {
+  return [entry, ...runs.filter((r) => r.runId !== entry.runId)].slice(0, limit);
+}
+
+/** The turn each index URL is waiting for, so updates in one process run one after another. */
+const turns = new Map<string, Promise<void>>();
+
+/**
+ * Add `entry` to the index at `target`. Never throws: a problem is a warning
+ * and the index stays as it was, or is replaced when it was unreadable JSON.
+ */
+export function updateCiRunIndex(input: {
+  target: ReportTarget;
+  entry: CiRunIndexEntry;
+  limit?: number;
+  warn: (message: string) => void;
+  now?: () => Date;
+  put?: ReportPut;
+  get?: ReportGet;
+}): Promise<void> {
+  const where = `${input.target.url}/${CI_RUN_INDEX_KEY}`;
+  const put = input.put ?? reportPut(input.target);
+  const get = input.get ?? reportGet(input.target);
+  const limit = Math.max(1, Math.floor(input.limit ?? CI_RUN_INDEX_LIMIT));
+  const work = async (): Promise<void> => {
+    let runs: CiRunIndexEntry[] = [];
+    try {
+      const text = await get(CI_RUN_INDEX_KEY);
+      if (text !== null) {
+        const parsed = parseCiRunIndex(text);
+        if ("corrupt" in parsed) input.warn(`the run index at ${where} is replaced, since ${parsed.corrupt}`);
+        else if ("newer" in parsed) return input.warn(`the run index at ${where} is contract ${parsed.newer}, which this chant does not write; it is left as it is`);
+        else runs = parsed.index.runs;
+      }
+    } catch (err) {
+      return input.warn(`could not read the run index at ${where}, so it is not updated: ${messageOf(err)}`);
+    }
+    const index: CiRunIndex = {
+      $schema: CI_RUN_INDEX_SCHEMA_ID,
+      contract: CI_RUN_INDEX_CONTRACT,
+      chant: readerVersion(),
+      updated: (input.now?.() ?? new Date()).toISOString(),
+      runs: addRunEntry(runs, input.entry, limit),
+    };
+    try {
+      await put(CI_RUN_INDEX_KEY, JSON.stringify(index, null, 2) + "\n", "application/json");
+    } catch (err) {
+      input.warn(`could not write the run index at ${where}: ${messageOf(err)}`);
+    }
+  };
+  const previous = turns.get(where) ?? Promise.resolve();
+  const next = previous.then(work, work);
+  const settled = next.catch(() => undefined);
+  turns.set(where, settled);
+  void settled.then(() => {
+    if (turns.get(where) === settled) turns.delete(where);
+  });
+  return next.catch((err) => input.warn(`could not update the run index at ${where}: ${messageOf(err)}`));
+}
+
+/** The index at `target`, or null when none is there. Throws a line a person can read when it can't be read. */
+export async function readCiRunIndex(target: ReportTarget, get: ReportGet = reportGet(target)): Promise<CiRunIndex | null> {
+  const where = `${target.url}/${CI_RUN_INDEX_KEY}`;
+  const text = await get(CI_RUN_INDEX_KEY);
+  if (text === null) return null;
+  const parsed = parseCiRunIndex(text);
+  if ("corrupt" in parsed) throw new Error(`the run index at ${where} is unusable: ${parsed.corrupt}`);
+  if ("newer" in parsed) throw new Error(`the run index at ${where} is contract ${parsed.newer}; this chant reads contract ${CI_RUN_INDEX_CONTRACT}`);
+  return parsed.index;
+}
+
+/** The text `chant ci runs` prints: one line per run, newest first. */
+export function formatCiRunIndex(index: CiRunIndex): string {
+  if (index.runs.length === 0) return "no runs in the index";
+  return index.runs
+    .map((r) => {
+      const pr = r.pr === null ? "no PR" : `PR ${r.pr}`;
+      const why = r.status === "fail" ? ` (${r.failure?.code ?? "failed"})` : "";
+      return `${r.ended}  ${r.job.padEnd(5)}  ${r.status}${why}  ${pr}  ${r.commit.slice(0, 12)}  ${r.runId}  ${r.key}${r.signer ? `  signed by ${r.signer}` : ""}`;
+    })
+    .join("\n");
+}
+
+const RUNS_USAGE = "chant ci runs [--report-url <s3://<bucket>/<prefix> | file://<directory>>] [--json]";
+
+/** `chant ci runs` (#4098): list the index at the report URL. */
+export async function runCiRuns(ctx: CommandContext): Promise<number> {
+  try {
+    // #4160: without --report-url, the declaration's ci.reportUrl.
+    const raw = await reportUrlOf(ctx.args.reportUrl, process.cwd());
+    if (!raw) throw new Error("--report-url names where the index is kept, unless the workspace declares ci.reportUrl");
+    const target = parseReportUrl(raw);
+    if ("error" in target) throw new Error(target.error);
+    const index = await readCiRunIndex(target);
+    if (index === null) throw new Error(`there is no run index at ${target.url}/${CI_RUN_INDEX_KEY}`);
+    console.log(ctx.args.json ? JSON.stringify(index, null, 2) : formatCiRunIndex(index));
+    return 0;
+  } catch (err) {
+    console.error(formatError({ message: `chant ci runs: ${messageOf(err)}`, hint: RUNS_USAGE }));
+    return 1;
+  }
+}