@intentius/chant 0.79.0 → 0.81.0

package/src/workspace/template-manifest.ts

@@ -0,0 +1,221 @@
+/**
+ * Template parameters (#2627, #2524 D9): `chant.template.json` at a
+ * template's root declares the parameters `chant init --from` takes and the
+ * files they are substituted into.
+ *
+ * ```json
+ * {
+ *   "parameters": {
+ *     "name": { "type": "string", "default": "Reference app", "pattern": "^[A-Za-z0-9][A-Za-z0-9 ._-]*$" }
+ *   },
+ *   "files": ["app/src/server.mjs"]
+ * }
+ * ```
+ *
+ * A listed file carries `{{chant:<name>}}` where the value goes. The `chant:`
+ * prefix keeps the placeholder apart from TypeScript template literals
+ * (`${x}`), GitHub and Forgejo expressions (`${{ x }}`) and Handlebars or
+ * Mustache (`{{x}}`), so a template can hold any of those in a listed file.
+ * Only listed files are substituted, the value is inserted as written, and a
+ * placeholder naming an undeclared parameter is an error in the template.
+ *
+ * The manifest is JSON and read as data: no template code runs at init or
+ * upgrade. It is template metadata, like `.chant/migrations/`, so it is not
+ * copied into the project. The values used are recorded in the lineage's
+ * `parameters`, and `chant workspace upgrade` substitutes them again into both
+ * the merge base and the target version, so an unedited file carrying a value
+ * still has its recorded hash.
+ *
+ * `hostBound` is declared and validated but not acted on yet: recording a
+ * value per host belongs to export and import (#2552). A host-bound value is
+ * recorded in `parameters` like any other until then.
+ */
+
+import { posix } from "node:path";
+import { z } from "zod";
+import { LockError } from "./lineage-lock";
+import { MIGRATIONS_DIR } from "./lineage-migrations";
+
+/** The manifest's path, relative to the template's root (the `#<member>` directory, when one is given). */
+export const TEMPLATE_MANIFEST = "chant.template.json";
+
+const PARAM_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** `{{chant:<name>}}`. */
+const PLACEHOLDER = /\{\{chant:([A-Za-z_][A-Za-z0-9_]*)\}\}/g;
+
+export function placeholder(name: string): string {
+  return `{{chant:${name}}}`;
+}
+
+const ParameterSchema = z
+  .object({
+    type: z.literal("string"),
+    default: z.string().optional(),
+    /** A regular expression every value must match, checked before substitution. */
+    pattern: z.string().optional(),
+    /** The value differs per host (#2524 D9). Recorded per host once #2552 lands. */
+    hostBound: z.boolean().optional(),
+    description: z.string().optional(),
+  })
+  .strict();
+export type TemplateParameter = z.infer<typeof ParameterSchema>;
+
+const ManifestSchema = z
+  .object({
+    $comment: z.string().optional(),
+    parameters: z.record(z.string(), ParameterSchema),
+    files: z.array(z.string().min(1)),
+  })
+  .strict();
+export type TemplateManifest = z.infer<typeof ManifestSchema>;
+
+function has(obj: object, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+
+export class TemplateParameterError extends LockError {
+  override name = "TemplateParameterError";
+}
+
+/**
+ * Read the manifest from a template's files, or null when it has none.
+ * Throws on a manifest that is not valid JSON or does not match the schema.
+ */
+export function readManifest(files: Map<string, Buffer>): TemplateManifest | null {
+  const data = files.get(TEMPLATE_MANIFEST);
+  if (!data) return null;
+  let raw: unknown;
+  try {
+    raw = JSON.parse(data.toString("utf-8"));
+  } catch (err) {
+    throw new TemplateParameterError(`${TEMPLATE_MANIFEST} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const parsed = ManifestSchema.safeParse(raw);
+  if (!parsed.success) {
+    throw new TemplateParameterError(
+      `invalid ${TEMPLATE_MANIFEST}: ${parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`,
+    );
+  }
+  const manifest = parsed.data;
+  for (const [name, p] of Object.entries(manifest.parameters)) {
+    if (!PARAM_NAME.test(name)) {
+      throw new TemplateParameterError(`invalid ${TEMPLATE_MANIFEST}: parameter name "${name}" is not a letter or _ followed by letters, digits or _`);
+    }
+    if (p.pattern !== undefined) {
+      try {
+        new RegExp(p.pattern, "u");
+      } catch {
+        throw new TemplateParameterError(`invalid ${TEMPLATE_MANIFEST}: parameters.${name}.pattern is not a regular expression`);
+      }
+      if (p.default !== undefined) checkValue(name, p, p.default, "its default");
+    }
+  }
+  for (const f of manifest.files) {
+    const norm = posix.normalize(f);
+    if (norm !== f || f.startsWith("/") || f.startsWith("../") || f === TEMPLATE_MANIFEST || f.startsWith(`${MIGRATIONS_DIR}/`)) {
+      throw new TemplateParameterError(`invalid ${TEMPLATE_MANIFEST}: files lists "${f}", which is not a normalised path to a template file`);
+    }
+  }
+  return manifest;
+}
+
+function checkValue(name: string, p: TemplateParameter, value: string, what: string): void {
+  if (p.pattern !== undefined && !new RegExp(p.pattern, "u").test(value)) {
+    throw new TemplateParameterError(`parameter ${name}: ${what} ${JSON.stringify(value)} does not match ${p.pattern}`);
+  }
+}
+
+/**
+ * Parse `--param name=value` arguments (split at the first `=`). A name given
+ * twice is refused rather than silently taking the last value.
+ */
+export function parseParamArgs(args: readonly string[]): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const arg of args) {
+    const eq = arg.indexOf("=");
+    if (eq <= 0) throw new TemplateParameterError(`--param ${arg}: expected <name>=<value>`);
+    const name = arg.slice(0, eq);
+    if (has(out, name)) throw new TemplateParameterError(`--param ${name} is given twice`);
+    out[name] = arg.slice(eq + 1);
+  }
+  return out;
+}
+
+function declaredList(manifest: TemplateManifest | null): string {
+  const names = manifest ? Object.keys(manifest.parameters).sort() : [];
+  return names.length > 0 ? `declared: ${names.join(", ")}` : "the template declares none";
+}
+
+/**
+ * The value of every declared parameter: the given value, or the default.
+ * Refuses an undeclared name (listing the declared ones), a parameter with no
+ * value and no default, and a value that does not match its pattern.
+ */
+export function resolveParameters(manifest: TemplateManifest | null, given: Record<string, string>): Record<string, string> {
+  const declared = manifest?.parameters ?? {};
+  const unknown = Object.keys(given).filter((n) => !has(declared, n)).sort();
+  if (unknown.length > 0) {
+    throw new TemplateParameterError(`unknown parameter${unknown.length > 1 ? "s" : ""} ${unknown.join(", ")} (${declaredList(manifest)})`);
+  }
+  const values: Record<string, string> = {};
+  const missing: string[] = [];
+  for (const name of Object.keys(declared).sort()) {
+    const p = declared[name];
+    const value = has(given, name) ? given[name] : p.default;
+    if (value === undefined) {
+      missing.push(name);
+      continue;
+    }
+    checkValue(name, p, value, has(given, name) ? "the value" : "its default");
+    values[name] = value;
+  }
+  if (missing.length > 0) {
+    throw new TemplateParameterError(
+      `parameter${missing.length > 1 ? "s" : ""} ${missing.join(", ")} ${missing.length > 1 ? "have" : "has"} no default; pass ${missing.map((n) => `--param ${n}=<value>`).join(" ")}`,
+    );
+  }
+  return values;
+}
+
+/**
+ * The template's files as the project gets them: the manifest removed, and
+ * each listed file with its placeholders replaced. A listed file that is
+ * missing, or a placeholder naming no declared parameter, is refused.
+ */
+export function substituteParameters(
+  files: Map<string, Buffer>,
+  manifest: TemplateManifest | null,
+  values: Record<string, string>,
+): Map<string, Buffer> {
+  const out = new Map(files);
+  out.delete(TEMPLATE_MANIFEST);
+  if (!manifest) return out;
+  for (const path of manifest.files) {
+    const data = out.get(path);
+    if (!data) throw new TemplateParameterError(`${TEMPLATE_MANIFEST} lists ${path}, which is not in the template`);
+    const text = data.toString("utf-8");
+    const replaced = text.replace(PLACEHOLDER, (_m, name: string) => {
+      if (!has(values, name)) {
+        throw new TemplateParameterError(`${path} has ${placeholder(name)}, but ${TEMPLATE_MANIFEST} declares no parameter ${name}`);
+      }
+      return values[name];
+    });
+    if (replaced !== text) out.set(path, Buffer.from(replaced, "utf-8"));
+  }
+  return out;
+}
+
+/**
+ * The values an upgrade substitutes into a version of the template: the
+ * recorded value of every parameter that version declares, and the default of
+ * one it adds. A recorded parameter the version no longer declares is dropped.
+ */
+export function carryParameters(manifest: TemplateManifest | null, recorded: Record<string, unknown>): Record<string, string> {
+  const declared = manifest?.parameters ?? {};
+  const given: Record<string, string> = {};
+  for (const [name, value] of Object.entries(recorded)) {
+    if (has(declared, name) && typeof value === "string") given[name] = value;
+  }
+  return resolveParameters(manifest, given);
+}

package/src/workspace/tree.ts

@@ -0,0 +1,132 @@
+/**
+ * The files a workspace read looks at: the working tree, or one commit's git
+ * objects (`--at <rev>`, #2524 D15). Reading a revision needs no checkout and
+ * no network; the whole tree is listed once from the local object store.
+ *
+ * Paths are relative to the tree's root, `/`-separated, and `""` is the root.
+ */
+
+import { execFileSync } from "node:child_process";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+export interface WorkspaceTree {
+  /** Appended to messages, such as " at 91c7547e". Empty for the working tree. */
+  label: string;
+  /** Whether `path` is a file, a directory, or missing. */
+  stat(path: string): "file" | "dir" | undefined;
+  /** The names of the entries directly inside directory `path`, or undefined when it is missing. */
+  list(path: string): { name: string; type: "file" | "dir" }[] | undefined;
+  /** The text of the file at `path`. Throws when it can't be read. */
+  read(path: string): string;
+}
+
+/** Join tree-relative path parts, leaving out `""` and `"."`. */
+export function joinPath(...parts: string[]): string {
+  return parts.filter((p) => p !== "" && p !== ".").join("/");
+}
+
+/** The working tree under `root`. */
+export function workingTree(root: string): WorkspaceTree {
+  return {
+    label: "",
+    stat(path) {
+      try {
+        const s = statSync(join(root, path));
+        return s.isDirectory() ? "dir" : s.isFile() ? "file" : undefined;
+      } catch {
+        return undefined;
+      }
+    },
+    list(path) {
+      let dirents;
+      try {
+        dirents = readdirSync(join(root, path), { withFileTypes: true });
+      } catch {
+        return undefined;
+      }
+      const out: { name: string; type: "file" | "dir" }[] = [];
+      for (const d of dirents) {
+        let type: "file" | "dir" | undefined = d.isDirectory() ? "dir" : d.isFile() ? "file" : undefined;
+        if (!type && d.isSymbolicLink()) {
+          try {
+            const s = statSync(join(root, path, d.name));
+            type = s.isDirectory() ? "dir" : s.isFile() ? "file" : undefined;
+          } catch {
+            // A dangling link is no entry.
+          }
+        }
+        if (type) out.push({ name: d.name, type });
+      }
+      return out;
+    },
+    read(path) {
+      return readFileSync(join(root, path), "utf-8");
+    },
+  };
+}
+
+function git(cwd: string, args: string[]): string {
+  return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 512 * 1024 * 1024 });
+}
+
+/** The top of the git repository holding `cwd`, or undefined outside one. */
+export function gitTop(cwd: string): string | undefined {
+  try {
+    return git(cwd, ["rev-parse", "--show-toplevel"]).trim();
+  } catch {
+    return undefined;
+  }
+}
+
+/** The full commit id `rev` names in the repository at `top`, or undefined. */
+export function resolveCommit(top: string, rev: string): string | undefined {
+  if (rev.startsWith("-")) return undefined;
+  try {
+    return git(top, ["rev-parse", "--verify", "--quiet", `${rev}^{commit}`]).trim();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The tree of `commit` in the repository at `top`, rooted at `prefix` (a
+ * directory relative to `top`, `""` for the top itself).
+ */
+export function gitTree(top: string, commit: string, prefix = ""): WorkspaceTree {
+  const entries = new Map<string, "file" | "dir">([["", "dir"]]);
+  const children = new Map<string, { name: string; type: "file" | "dir" }[]>([["", []]]);
+  const out = git(top, ["ls-tree", "-r", "-t", "-z", "--full-tree", commit]);
+  for (const line of out.split("\0")) {
+    if (!line) continue;
+    const tab = line.indexOf("\t");
+    const type = line.slice(0, tab).split(" ")[1];
+    const full = line.slice(tab + 1);
+    let path: string;
+    if (prefix === "") path = full;
+    else if (full.startsWith(`${prefix}/`)) path = full.slice(prefix.length + 1);
+    else continue;
+    const kind = type === "tree" ? "dir" : type === "blob" ? "file" : undefined;
+    if (!kind) continue;
+    entries.set(path, kind);
+    const slash = path.lastIndexOf("/");
+    const parent = slash < 0 ? "" : path.slice(0, slash);
+    if (!children.has(parent)) children.set(parent, []);
+    children.get(parent)!.push({ name: path.slice(slash + 1), type: kind });
+    if (kind === "dir" && !children.has(path)) children.set(path, []);
+  }
+  return {
+    label: ` at ${commit.slice(0, 8)}`,
+    stat: (path) => entries.get(path),
+    list: (path) => (entries.get(path) === "dir" ? [...(children.get(path) ?? [])] : undefined),
+    read(path) {
+      if (entries.get(path) !== "file") throw new Error(`${path} is not a file${` at ${commit.slice(0, 8)}`}`);
+      return git(top, ["cat-file", "blob", `${commit}:${joinPath(prefix, path)}`]);
+    },
+  };
+}
+
+/** Directory names a workspace walk never enters. */
+export function skippedDir(name: string): boolean {
+  return name === "node_modules" || name.startsWith(".");
+}

package/src/workspace/trust/attestor.ts

@@ -0,0 +1,93 @@
+/**
+ * Attestors and provenance levels (#2524 D5).
+ *
+ * An attestor answers one question about a commit: does it carry an
+ * attestation that the policy read at base accepts? Concrete attestors are
+ * plugins. Core ships the contract and the first one, ssh-signed commits
+ * (./ssh-commit.ts). Plugin attestors will arrive the way kinds do, through
+ * `workspaceKinds` (#2525 rule 5), once the declaration can name them (#2534,
+ * #2535); until then {@link registerAttestor} is the entry point.
+ *
+ * What counts as proof: a signature the attestor checked against a key the
+ * base policy lists. Never a trailer, a typed-in name, an author field or an
+ * environment variable.
+ */
+
+import { UNATTESTED_APPROVER } from "../../lifecycle/gate-origin";
+import type { TrustPolicy } from "./policy";
+
+/**
+ * How far a record's authorship is established. The list is closed and
+ * ordered from strongest to weakest; a gate may require `attested`.
+ *
+ * - `attested`: an attestor verified a signature by a signer the base policy lists.
+ * - `attested-unverifiable-here`: there is a signature, but nothing here can
+ *   check it (a signature format no attestor handles, or a missing tool).
+ * - `adopted`: not attested, but inside a commit range the base policy admits.
+ * - `unattested`: none of the above. The same word, with the same meaning, as
+ *   the approver a gate resolution records when its channel cannot attest to a
+ *   name (#2384, {@link UNATTESTED_APPROVER}); D5 keeps that meaning.
+ */
+export const PROVENANCE_LEVELS = ["attested", "attested-unverifiable-here", "adopted", UNATTESTED_APPROVER] as const;
+export type ProvenanceLevel = (typeof PROVENANCE_LEVELS)[number];
+
+/** What one attestor says about one commit. */
+export interface CommitAttestation {
+  level: "attested" | "attested-unverifiable-here" | "unattested";
+  /** The attestor that gave this answer. */
+  attestor: string;
+  /** The principal whose key verified, when `attested`. */
+  principal?: string;
+  /** The key's fingerprint, when known. */
+  key?: string;
+  /** Why the level is what it is, in a sentence. */
+  reason: string;
+}
+
+/** Read access to the repository an attestor checks. */
+export interface AttestorContext {
+  /** The repository's top directory. */
+  repo: string;
+  /** The policy read at base. */
+  policy: TrustPolicy;
+}
+
+/** A commit attestor. Plugins implement this. */
+export interface CommitAttestor {
+  /** A stable name, such as `ssh-commit`. */
+  readonly name: string;
+  attestCommit(ctx: AttestorContext, commit: string): CommitAttestation;
+}
+
+const registered: CommitAttestor[] = [];
+
+/** Add an attestor. Later registrations are asked after earlier ones. */
+export function registerAttestor(attestor: CommitAttestor): void {
+  if (!registered.some((a) => a.name === attestor.name)) registered.push(attestor);
+}
+
+/** Remove every attestor registered by {@link registerAttestor}. For tests. */
+export function resetAttestors(): void {
+  registered.length = 0;
+}
+
+/**
+ * Ask each attestor in turn. The first `attested` answer wins; otherwise
+ * `attested-unverifiable-here` beats `unattested`, so a signature nobody here
+ * can check is still reported as there.
+ */
+export function attestCommit(ctx: AttestorContext, commit: string, attestors: readonly CommitAttestor[]): CommitAttestation {
+  let best: CommitAttestation | undefined;
+  for (const a of attestors) {
+    const r = a.attestCommit(ctx, commit);
+    if (r.level === "attested") return r;
+    if (!best || (best.level === "unattested" && r.level === "attested-unverifiable-here")) best = r;
+  }
+  return best ?? { level: "unattested", attestor: "none", reason: "no attestor is registered" };
+}
+
+/** The attestors in use: the built-in ones first, then any registered. */
+export async function activeAttestors(): Promise<CommitAttestor[]> {
+  const { sshCommitAttestor } = await import("./ssh-commit");
+  return [sshCommitAttestor, ...registered.filter((a) => a.name !== sshCommitAttestor.name)];
+}