@intentius/chant 0.79.0 → 0.81.0

package/src/workspace/records-cli.ts

@@ -0,0 +1,198 @@
+/**
+ * `chant workspace records --kind <path> [--current] [--at <rev>] [--base <rev>]
+ * [--require attested] [--json]`, the first-test slice of the records query
+ * (#2546, #2536), with each record's provenance level (#2547).
+ *
+ * It reads every record the kind file locates and prints them, with reason
+ * codes for any that are invalid. An invalid record never fails the command:
+ * the exit code is 0 whenever the read itself worked. Only a kind, schema or
+ * revision that cannot be read exits 1.
+ *
+ * It needs no `chant.workspace.json`. The kind is passed explicitly, so
+ * nothing is inferred (#2525 rule 1).
+ */
+
+import { realpathSync } from "node:fs";
+import { relative } from "node:path";
+import { formatError } from "../cli/format";
+import type { CommandContext } from "../cli/registry";
+import { gitRevisionSource, gitRoot, resolveRevision, workingTreeSource } from "./record-source";
+import { loadRecordKind, readRecords, RecordReadError, type ReadErrorCode, type RecordEntry } from "./records";
+import { activeAttestors, type ProvenanceLevel } from "./trust/attestor";
+import { policyAtBase, recordProvenance, resolveBase, type BaseSource, type RecordProvenance } from "./trust/provenance";
+
+/** The version of the `records` output this chant writes. */
+export const RECORDS_CONTRACT_VERSION = 1;
+
+/** `$id` of the JSON Schema for the `--json` output, shipped beside this file. */
+export const RECORDS_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/records/v1/records.schema.json";
+
+const USAGE = "chant workspace records --kind <kind file> [--current] [--at <rev>] [--base <rev>] [--require attested] [--json]";
+
+/** Exit code when the read worked and a record falls below `--require`. */
+export const EXIT_BELOW_REQUIRED = 2;
+
+export interface RecordsQuery {
+  kind: string;
+  current?: boolean;
+  at?: string;
+  /** The revision the trust policy is read at (#2547). Defaults to the target branch tip. */
+  base?: string;
+  /** Where `kind` is resolved from and the repository is found. */
+  cwd: string;
+}
+
+/** A record as the output carries it: the entry plus its provenance (#2547). */
+export type RecordView = RecordEntry & { provenance: RecordProvenance };
+
+/** Where provenance was judged from (#2547). */
+export interface TrustView {
+  /** The full commit id the policy was read at, or null when there is no base. */
+  base: string | null;
+  baseFrom: BaseSource | null;
+  /** Whether a signers file exists at base. False means every record is `unattested`. */
+  active: boolean;
+  signersPath: string;
+  problems: string[];
+}
+
+/** The `records` output: a result, or a failure with one error code. */
+export type RecordsDocument =
+  | {
+      $schema: string;
+      contract: number;
+      kind: { name: string; schema: string; file: string };
+      at: string | null;
+      current: boolean;
+      trust: TrustView;
+      records: RecordView[];
+      summary: { total: number; valid: number; invalid: number; superseded: number };
+    }
+  | { $schema: string; contract: number; error: { code: ReadErrorCode; message: string } };
+
+/** Run the query and build the document `--json` prints. Never throws a {@link RecordReadError}. */
+export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument> {
+  // git reports its top through symlinks resolved (/var is /private/var on
+  // macOS), so the directory has to be too, or record paths leave the repository.
+  const cwd = realpathOr(query.cwd);
+  const top = gitRoot(cwd);
+  const root = top ?? cwd;
+  try {
+    const loaded = await loadRecordKind(query.kind, cwd);
+    let at: string | null = null;
+    let source = workingTreeSource(root);
+    if (query.at !== undefined) {
+      if (!top) throw new RecordReadError("not-a-git-repository", "--at reads git objects, and this directory is not in a git repository");
+      at = resolveRevision(top, query.at);
+      source = gitRevisionSource(top, at);
+    }
+    const result = await readRecords(loaded, { root, source, current: !!query.current });
+    // Provenance, judged by the policy at base and never by the tree read (#2547).
+    const base = top ? resolveBase(top, query.base) : { commit: null, from: null };
+    const policy = top ? policyAtBase(top, base) : policyAtBase(root, base);
+    const provenance = recordProvenance({
+      repo: top,
+      policy,
+      at,
+      paths: result.records.map((r) => r.path),
+      attestors: policy.active ? await activeAttestors() : [],
+    });
+    return {
+      $schema: RECORDS_OUTPUT_SCHEMA_ID,
+      contract: RECORDS_CONTRACT_VERSION,
+      kind: {
+        name: loaded.kind.name,
+        schema: loaded.kind.schema.id,
+        file: relative(root, loaded.file).split("\\").join("/"),
+      },
+      at,
+      current: !!query.current,
+      trust: { base: base.commit, baseFrom: base.from, active: policy.active, signersPath: policy.signersPath, problems: policy.problems },
+      records: result.records.map((r) => ({ ...r, provenance: provenance.get(r.path)! })),
+      summary: result.summary,
+    };
+  } catch (err) {
+    if (!(err instanceof RecordReadError)) throw err;
+    return { $schema: RECORDS_OUTPUT_SCHEMA_ID, contract: RECORDS_CONTRACT_VERSION, error: { code: err.code, message: err.message } };
+  }
+}
+
+export async function runWorkspaceRecords(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  if (!args.kind) {
+    console.error(formatError({ message: "--kind <kind file> is required", hint: USAGE }));
+    return 1;
+  }
+  if (args.require !== undefined && args.require !== "attested") {
+    console.error(formatError({ message: `--require takes one level, attested, not ${JSON.stringify(args.require)}`, hint: USAGE }));
+    return 1;
+  }
+  const doc = await queryRecords({ kind: args.kind, current: args.current, at: args.at, base: args.base, cwd: process.cwd() });
+  if (args.json) {
+    console.log(JSON.stringify(doc, null, 2));
+  } else if ("error" in doc) {
+    console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));
+  } else {
+    console.log(formatRecords(doc.records, doc.summary, doc.at));
+  }
+  if ("error" in doc) return 1;
+  if (args.require) {
+    const below = belowRequired(doc.records, args.require);
+    if (below.length > 0) {
+      console.error(
+        formatError({
+          message: `${below.length} of ${doc.records.length} records are not ${args.require}: ${below
+            .slice(0, 5)
+            .map((r) => `${r.path} (${r.provenance.level})`)
+            .join(", ")}${below.length > 5 ? ", ..." : ""}`,
+          hint: doc.trust.active ? "run with --json to see each record's reason" : `there is no signers file (${doc.trust.signersPath}) at base`,
+        }),
+      );
+      return EXIT_BELOW_REQUIRED;
+    }
+  }
+  return 0;
+}
+
+function realpathOr(dir: string): string {
+  try {
+    return realpathSync(dir);
+  } catch {
+    return dir;
+  }
+}
+
+/** Records whose provenance falls below `required`. Only `attested` can be required. */
+export function belowRequired(records: RecordView[], required: ProvenanceLevel): RecordView[] {
+  return records.filter((r) => r.provenance.level !== required);
+}
+
+function formatRecords(records: RecordView[], summary: { total: number; valid: number; invalid: number; superseded: number }, at: string | null): string {
+  const lines: string[] = [];
+  const idWidth = Math.max(2, ...records.map((r) => (r.id ?? "-").length));
+  const stateWidth = Math.max(5, ...records.map((r) => (r.state ?? "-").length));
+  for (const r of records) {
+    const title = typeof r.data?.title === "string" ? r.data.title : r.path;
+    const flag = r.valid ? "" : "  INVALID";
+    const superseded = r.supersededBy ? `  superseded by ${r.supersededBy}` : "";
+    const attested = r.provenance.level === "attested" ? `  attested by ${r.provenance.principal}` : "";
+    lines.push(`${(r.id ?? "-").padEnd(idWidth)}  ${(r.state ?? "-").padEnd(stateWidth)}  ${title}${superseded}${attested}${flag}`);
+    for (const reason of r.reasons) lines.push(`${" ".repeat(idWidth + 2)}${reason.code}: ${reason.message} (${r.path})`);
+  }
+  lines.push(
+    `${summary.total} records${at ? ` at ${at.slice(0, 8)}` : ""}: ${summary.valid} valid, ${summary.invalid} invalid, ${summary.superseded} superseded`,
+  );
+  return lines.join("\n");
+}
+
+/** `chant workspace <anything else>`. */
+export async function runWorkspaceUnknown(ctx: CommandContext): Promise<number> {
+  const sub = ctx.args.path && ctx.args.path !== "." ? ctx.args.path : "";
+  console.error(
+    formatError({
+      message: sub ? `Unknown workspace subcommand: ${sub}` : "chant workspace needs a subcommand",
+      hint: `Workspace subcommands: audit, build, check, graph, init, lineage, lint, ls, records, status, upgrade, verify. Run "chant --help" for their options.`,
+    }),
+  );
+  return 1;
+}

package/src/workspace/records-contract.test.ts

@@ -0,0 +1,93 @@
+/**
+ * The read contract for `chant workspace records --json` (#2536): the output
+ * schema is a valid draft 2020-12 document, its closed code lists match the
+ * code, and real output validates against it. The reference workspace (#2543)
+ * doesn't exist yet, so the chant repo's own decision files stand in for it.
+ */
+
+import { cpSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import Ajv2020 from "ajv/dist/2020";
+import { afterAll, describe, expect, test } from "vitest";
+import { queryRecords, RECORDS_CONTRACT_VERSION, RECORDS_OUTPUT_SCHEMA_ID, type RecordsDocument } from "./records-cli";
+import { READ_ERROR_CODES, RECORD_REASON_CODES } from "./records";
+import schema from "./records.schema.json";
+import { PROVENANCE_LEVELS } from "./trust/attestor";
+
+const REPO = join(import.meta.dirname, "..", "..", "..", "..");
+const KIND = "docs/design/decisions/decision.kind.mjs";
+
+const ajv = new Ajv2020({ strict: true, allErrors: true });
+const validate = ajv.compile(schema);
+
+function expectValid(doc: RecordsDocument): void {
+  const ok = validate(doc);
+  expect(ok, JSON.stringify(validate.errors, null, 2)).toBe(true);
+}
+
+const scratch: string[] = [];
+afterAll(() => {
+  for (const d of scratch) rmSync(d, { recursive: true, force: true });
+});
+
+/** A directory holding a copy of the decisions, kind and schema, outside any git repository. */
+function copyDecisions(): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-records-contract-")));
+  scratch.push(root);
+  mkdirSync(join(root, "docs", "design"), { recursive: true });
+  cpSync(join(REPO, "docs", "design", "decisions"), join(root, "docs", "design", "decisions"), { recursive: true });
+  return root;
+}
+
+describe("records output schema", () => {
+  test("is a valid draft 2020-12 document with the published $id", () => {
+    expect(schema.$schema).toBe("https://json-schema.org/draft/2020-12/schema");
+    expect(ajv.validateSchema(schema)).toBe(true);
+    expect(schema.$id).toBe(RECORDS_OUTPUT_SCHEMA_ID);
+    expect(RECORDS_CONTRACT_VERSION).toBe(1);
+  });
+
+  test("lists exactly the reason and error codes the code can return", () => {
+    expect(schema.$defs.reason.properties.code.enum).toEqual([...RECORD_REASON_CODES]);
+    expect(schema.$defs.failure.properties.error.properties.code.enum).toEqual([...READ_ERROR_CODES]);
+  });
+
+  test("lists exactly the provenance levels (#2547)", () => {
+    expect(schema.$defs.provenance.properties.level.enum).toEqual([...PROVENANCE_LEVELS]);
+  });
+
+  test("the chant repo's decisions validate, current and not", async () => {
+    for (const current of [false, true]) {
+      const doc = await queryRecords({ kind: KIND, current, cwd: REPO });
+      expectValid(doc);
+      expect("error" in doc).toBe(false);
+    }
+  });
+
+  test("invalid records validate, each with its reason", async () => {
+    const root = copyDecisions();
+    const dir = join(root, "docs", "design", "decisions");
+    writeFileSync(join(dir, "ws-001-trust-root.md"), "no front matter\n");
+    writeFileSync(join(dir, "ws-900-extra.md"), "---\nid: \"ws-900\"\nstate: \"decided\"\n---\n");
+    const doc = await queryRecords({ kind: KIND, cwd: root });
+    expectValid(doc);
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(doc.at).toBeNull();
+    expect(doc.summary.invalid).toBe(2);
+  });
+
+  test("every failure validates with its code", async () => {
+    const root = copyDecisions();
+    const docs = [
+      await queryRecords({ kind: "missing.kind.mjs", cwd: root }),
+      await queryRecords({ kind: KIND, at: "HEAD", cwd: root }),
+    ];
+    for (const doc of docs) expectValid(doc);
+    expect(docs.map((d) => ("error" in d ? d.error.code : "ok"))).toEqual(["kind-unreadable", "not-a-git-repository"]);
+  });
+
+  test("a document mixing records and an error is refused", () => {
+    expect(validate({ $schema: RECORDS_OUTPUT_SCHEMA_ID, contract: 1, error: { code: "revision-unknown", message: "x" }, records: [] })).toBe(false);
+  });
+});

package/src/workspace/records.schema.json

@@ -0,0 +1,150 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/records/v1/records.schema.json",
+  "title": "chant workspace records output",
+  "description": "What `chant workspace records --json` prints, version 1 of the read contract for records (#2536). This is the first-test slice (#2546): records are unsealed and there is no workspace declaration yet. Readers ignore fields they do not know; a field is only ever added within a version. The reason and error codes are closed lists: a new code is a new contract version. Contract version 1 is written by chant 0.81.0 and newer; a reader that needs it refuses output whose `contract` it doesn't know. Every code is in the one closed list of `reason-codes.ts`.",
+  "oneOf": [{ "$ref": "#/$defs/result" }, { "$ref": "#/$defs/failure" }],
+  "$defs": {
+    "result": {
+      "description": "The read worked. Exit code 0, even when some records are invalid.",
+      "type": "object",
+      "required": ["$schema", "contract", "kind", "at", "current", "records", "summary"],
+      "properties": {
+        "$schema": { "const": "https://intentius.io/chant/schemas/workspace/records/v1/records.schema.json" },
+        "contract": { "const": 1 },
+        "kind": {
+          "type": "object",
+          "required": ["name", "schema", "file"],
+          "properties": {
+            "name": { "type": "string", "description": "The kind's name, such as \"decision\"." },
+            "schema": { "type": "string", "description": "The `$id` of the schema each record was validated against." },
+            "file": { "type": "string", "description": "The kind file, relative to the repository root, with / separators." }
+          }
+        },
+        "at": {
+          "description": "The full commit id the records were read at (--at), or null for the working tree.",
+          "type": ["string", "null"],
+          "pattern": "^[0-9a-f]{40,64}$"
+        },
+        "error": false,
+        "current": { "type": "boolean", "description": "Whether superseded records were left out (--current)." },
+        "trust": { "$ref": "#/$defs/trust" },
+        "records": {
+          "description": "One entry per file the kind locates, sorted by path.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/record" }
+        },
+        "summary": {
+          "type": "object",
+          "required": ["total", "valid", "invalid", "superseded"],
+          "properties": {
+            "total": { "type": "integer", "minimum": 0, "description": "Entries in records." },
+            "valid": { "type": "integer", "minimum": 0 },
+            "invalid": { "type": "integer", "minimum": 0 },
+            "superseded": { "type": "integer", "minimum": 0, "description": "Records a closed record supersedes, counted before --current leaves them out." }
+          }
+        }
+      }
+    },
+    "record": {
+      "type": "object",
+      "required": ["id", "path", "state", "valid", "reasons", "supersededBy", "data"],
+      "properties": {
+        "id": { "type": ["string", "null"], "description": "Null when the front matter could not be parsed or has no string id." },
+        "path": { "type": "string", "description": "From the repository root, with / separators." },
+        "state": { "type": ["string", "null"], "description": "The state as the record writes it. Supersession is reported in supersededBy, not here." },
+        "valid": { "type": "boolean", "description": "True exactly when reasons is empty." },
+        "reasons": { "type": "array", "items": { "$ref": "#/$defs/reason" } },
+        "supersededBy": {
+          "type": ["string", "null"],
+          "description": "The id of the closed record whose supersedes link replaces this one. Derived from that record's link, never from this record's own fields."
+        },
+        "data": {
+          "type": ["object", "null"],
+          "description": "The front matter as JSON, following the kind's schema when valid is true. Null when it could not be parsed."
+        },
+        "provenance": { "$ref": "#/$defs/provenance" }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "valid": { "const": true } } },
+          "then": { "properties": { "reasons": { "type": "array", "maxItems": 0 }, "data": { "type": "object" }, "id": { "type": "string" } } },
+          "else": { "properties": { "reasons": { "type": "array", "minItems": 1 } } }
+        }
+      ]
+    },
+    "trust": {
+      "description": "Added in contract 1 by #2547. Where provenance was judged from: the policy read at the base revision, never the tree read.",
+      "type": "object",
+      "required": ["base", "baseFrom", "active", "signersPath", "problems"],
+      "properties": {
+        "base": { "type": ["string", "null"], "pattern": "^[0-9a-f]{40,64}$", "description": "The full commit id the policy was read at, or null when there is no base." },
+        "baseFrom": { "enum": ["flag", "origin/HEAD", "main", "master", null], "description": "flag when --base was given; otherwise the target branch that was found." },
+        "active": { "type": "boolean", "description": "Whether a signers file exists at base. False means attestation is off and every record is unattested." },
+        "signersPath": { "type": "string", "description": "The signers file, relative to the repository root." },
+        "problems": { "type": "array", "items": { "type": "string" }, "description": "Why the policy could not be read. Nothing is attested when this is not empty." }
+      }
+    },
+    "provenance": {
+      "description": "Added in contract 1 by #2547. How far the record's authorship is established, judged by the signers at base.",
+      "type": "object",
+      "required": ["level", "commit", "reason"],
+      "properties": {
+        "level": {
+          "enum": ["attested", "attested-unverifiable-here", "adopted", "unattested"],
+          "description": "attested: the last commit to change the file is signed by a signer the policy at base lists. attested-unverifiable-here: it carries a signature nothing here can check. adopted: it lies in a commit range the policy adopts. unattested: none of these, including uncommitted content."
+        },
+        "commit": { "type": ["string", "null"], "pattern": "^[0-9a-f]{40,64}$", "description": "The commit the record's content comes from, or null for uncommitted content." },
+        "attestor": { "type": "string", "description": "The attestor that answered, such as ssh-commit." },
+        "principal": { "type": "string", "description": "The signer, when attested." },
+        "key": { "type": "string", "description": "The signing key's fingerprint, when known." },
+        "reason": { "type": "string" }
+      }
+    },
+    "reason": {
+      "type": "object",
+      "required": ["code", "message"],
+      "properties": {
+        "code": {
+          "enum": [
+            "record-unparseable",
+            "record-schema-invalid",
+            "record-id-duplicate",
+            "record-supersedes-unknown",
+            "record-supersedes-conflict"
+          ]
+        },
+        "message": { "type": "string" }
+      }
+    },
+    "failure": {
+      "description": "The read failed and returned no records. Exit code 1.",
+      "type": "object",
+      "required": ["$schema", "contract", "error"],
+      "properties": {
+        "$schema": { "const": "https://intentius.io/chant/schemas/workspace/records/v1/records.schema.json" },
+        "contract": { "const": 1 },
+        "error": {
+          "type": "object",
+          "required": ["code", "message"],
+          "properties": {
+            "code": {
+              "enum": [
+                "kind-unreadable",
+                "kind-invalid",
+                "schema-unreadable",
+                "schema-id-mismatch",
+                "schema-invalid",
+                "location-missing",
+                "not-a-git-repository",
+                "revision-unknown"
+              ]
+            },
+            "message": { "type": "string" }
+          }
+        },
+        "records": false
+      }
+    }
+  }
+}