@intentius/chant 0.82.0 → 0.84.0

package/src/workspace/lineage-check.ts

@@ -1,5 +1,5 @@
 /**
- * `chant workspace check [--at <rev>] [--json] [--format stylish|json|sarif] [--generated]`:
+ * `chant workspace check [--at <rev>] [--json] [--format stylish|json|sarif] [--generated] [--kind <kind file>]`:
  * the lineage checks (#2550, D9), and the declaration checks (#2535, D16)
  * when a declaration sits between the current directory and the git root.
  *
@@ -10,7 +10,9 @@
  * check. The declaration checks report `WSP` findings through lint's
  * reporters (`./checks.ts`), and cover member ledgers (#2538), recorded
  * pipelines (#2542) and generated files (#2541) as well as the declaration
- * itself (#2641). `--generated` runs each declared generator too.
+ * itself (#2641). `--generated` runs each declared generator too. `--kind`
+ * reads a record kind's records and reports the files they pin by hash that
+ * have changed since (#2549).
  *
  * `chant workspace upgrade` runs the same checks in its staging worktree
  * before it reaches its gate.
@@ -23,6 +25,7 @@ import type { CommandContext } from "../cli/registry";
 import type { LintDiagnostic, LintRule } from "../lint/rule";
 import { findWorkspaceRoot } from "../project-root";
 import type { DeclarationCheckReport } from "./checks";
+import type { RecordFacts } from "./checks/records";
 import { LOCK_FILE, LockError, parseLock, readLock } from "./lineage-lock";
 import type { ReasonCode } from "./reason-codes";
 import type { WorkspaceTree } from "./tree";
@@ -81,7 +84,7 @@ export function findingKey(f: CheckFinding): string {
   return `${f.code}\0${f.scope ?? ""}\0${f.path ?? ""}`;
 }
 
-const USAGE = "chant workspace check [--at <rev>] [--json] [--format stylish|json|sarif] [--generated]";
+const USAGE = "chant workspace check [--at <rev>] [--json] [--format stylish|json|sarif] [--generated] [--kind <kind file>]";
 const FORMATS = ["stylish", "json", "sarif"] as const;
 
 /** A lock finding as a lint diagnostic, for `--format json` and `--format sarif`. */
@@ -142,7 +145,7 @@ export type CheckDocument =
  * to `cwd`. `runGenerators` is `--generated`; with `at` it does nothing,
  * since the member facts describe the working tree, not the revision.
  */
-export async function runChecks(cwd: string, at?: string, options: { runGenerators?: boolean } = {}): Promise<CheckDocument> {
+export async function runChecks(cwd: string, at?: string, options: { runGenerators?: boolean; kind?: string } = {}): Promise<CheckDocument> {
   // Loaded here, not at the top: `workspace upgrade` imports this module for checkLineage alone.
   const [{ findDeclarationDir, readDeclaration, readerVersion }, { gitTop, gitTree, resolveCommit, workingTree }] = await Promise.all([
     import("./declaration"),
@@ -184,9 +187,11 @@ export async function runChecks(cwd: string, at?: string, options: { runGenerato
   if (found) {
     const { runDeclarationChecks } = await import("./checks");
     const { dir, tree } = found;
+    const records = options.kind !== undefined ? await readRecordFacts(options.kind, cwd, commit) : undefined;
     declaration = await runDeclarationChecks(dir, (file) => relative(cwd, join(dir, file)).split(sep).join("/"), {
       runGenerators: options.runGenerators === true,
       ...(commit !== null ? { tree } : {}),
+      ...(records ? { records } : {}),
     });
     let name: string | null = null;
     try {
@@ -200,6 +205,18 @@ export async function runChecks(cwd: string, at?: string, options: { runGenerato
   return { ...head, at: commit, workspace, ...report, ok, ...(declaration ? { declaration } : {}) };
 }
 
+/** The records of the kind file `kind` for the record checks (#2549), at `commit` or in the working tree. */
+async function readRecordFacts(kind: string, cwd: string, commit: string | null): Promise<RecordFacts> {
+  const [{ readRecordsFor }, { RecordReadError }] = await Promise.all([import("./records-cli"), import("./records")]);
+  try {
+    const read = await readRecordsFor({ kind, cwd, ...(commit !== null ? { at: commit } : {}) });
+    return { kind, records: read.result.records.map((r) => ({ ...r, file: join(read.root, ...r.path.split("/")) })) };
+  } catch (err) {
+    if (!(err instanceof RecordReadError)) throw err;
+    return { kind, error: { code: err.code, message: err.message } };
+  }
+}
+
 export async function runWorkspaceCheck(ctx: CommandContext): Promise<number> {
   const root = process.cwd();
   if (ctx.args.extraPositional) {
@@ -218,7 +235,7 @@ export async function runWorkspaceCheck(ctx: CommandContext): Promise<number> {
     const handed = await handToRootChant(root, ctx.args.at);
     if (handed !== undefined) return handed;
   }
-  const doc = await runChecks(root, ctx.args.at, { runGenerators: ctx.args.generated === true });
+  const doc = await runChecks(root, ctx.args.at, { runGenerators: ctx.args.generated === true, ...(ctx.args.kind !== undefined ? { kind: ctx.args.kind } : {}) });
   if ("error" in doc) {
     if (ctx.args.json || format === "json") console.log(JSON.stringify(doc, null, 2));
     else console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));

package/src/workspace/lineage-init.ts

@@ -36,6 +36,7 @@ import {
 } from "./lineage-lock";
 import { MIGRATIONS_DIR } from "./lineage-migrations";
 import { TEMPLATE_MANIFEST, readManifest, resolveParameters, substituteParameters } from "./template-manifest";
+import { repinSubstituted, type RepinnedRecord } from "./template-pins";
 
 // ── The template spec ────────────────────────────────────────────────────────
 
@@ -413,11 +414,13 @@ export async function initFromCommand(options: InitFromOptions): Promise<InitFro
   // so a refused --param leaves the target untouched.
   let parameters: Record<string, string>;
   let contents: Map<string, Buffer>;
+  let repinned: RepinnedRecord[];
   try {
     const raw = new Map([...fetched.files].map(([path, f]) => [path, f.data]));
     const manifest = readManifest(raw);
     parameters = resolveParameters(manifest, options.params ?? {});
-    contents = substituteParameters(raw, manifest, parameters);
+    // Records that pin a substituted file get its new hash, so a copy's pins hold (#2549).
+    ({ files: contents, repinned } = repinSubstituted(raw, substituteParameters(raw, manifest, parameters), manifest?.files ?? []));
   } catch (err) {
     return { success: false, createdFiles, warnings, error: (err as Error).message };
   }
@@ -442,6 +445,7 @@ export async function initFromCommand(options: InitFromOptions): Promise<InitFro
 
   const common = {
     parameters,
+    ...(repinned.length > 0 ? { repinned: repinned.filter((r) => written.has(r.record)) } : {}),
     migrations: [],
     files: fileEntries(written, declaredFilesAt(targetDir)),
     manualSteps: [],

package/src/workspace/lineage-lock.ts

@@ -133,6 +133,12 @@ const LineageSchema = z
     address: AddressSchema.nullable(),
     /** The parameter values the template was instantiated with. Always empty for vendor scopes. */
     parameters: z.record(z.string(), z.unknown()),
+    /**
+     * Records whose evidence pins were re-pinned to the substituted content
+     * of a parameterised file (#2549): each record's path in the scope, and the
+     * pinned paths. An upgrade re-pins the base and the target the same way.
+     */
+    repinned: z.array(z.object({ record: z.string().min(1), paths: z.array(z.string().min(1)) }).strict()).optional(),
     /** Migrations applied since instantiation (#2550). */
     migrations: z.array(z.string()),
     /** Per file, relative to the scope directory, in sorted order. */
@@ -249,6 +255,7 @@ function canonical(lock: LineageLock): LineageLock {
       ...(s.ref !== undefined ? { ref: s.ref } : {}),
       address: s.address,
       parameters: s.parameters,
+      ...(s.repinned !== undefined ? { repinned: s.repinned } : {}),
       migrations: s.migrations,
       files,
       manualSteps: [...s.manualSteps].sort((a, b) => a.path.localeCompare(b.path)),

package/src/workspace/lineage-upgrade.test.ts

@@ -7,6 +7,7 @@
 
 import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
@@ -455,6 +456,34 @@ describe("chant workspace upgrade with template parameters (#2627)", () => {
     }
   });
 
+  test("a record that pins a substituted file is re-pinned on the base and the target, so it updates with no manual step (#2549)", async () => {
+    const sha = (s: string) => createHash("sha256").update(s).digest("hex");
+    const record = (hash: string) => `---\nschema: 1\nid: "tpl-001"\nevidence:\n  - title: "readme"\n    path: "README.md"\n    sha256: "${hash}"\n---\n`;
+    // A second project, from a v1 whose record pins the template's README.
+    tpl = join(root, "rtpl");
+    proj = join(root, "rproj");
+    mkdirSync(tpl);
+    git(tpl, ["init", "-q", "-b", "main"]);
+    const manifest = JSON.stringify({ parameters: { name: { type: "string", default: "Starter" } }, files: ["README.md"] });
+    release("v1.0.0", { "chant.template.json": manifest, "README.md": "# {{chant:name}}\n", "decisions/tpl-001-x.md": record(sha("# {{chant:name}}\n")) });
+    const made = await initFromCommand({ from: `${tpl}@v1.0.0`, path: proj, params: { name: "Acme" } });
+    expect(made.error).toBeUndefined();
+    expect(read(proj, "decisions/tpl-001-x.md")).toBe(record(sha("# Acme\n")));
+    expect(readLock(proj)!.scopes["."].repinned).toEqual([{ record: "decisions/tpl-001-x.md", paths: ["README.md"] }]);
+    git(proj, ["init", "-q", "-b", "main"]);
+    commitProject("init");
+
+    release("v2.0.0", { "README.md": "# {{chant:name}} v2\n", "decisions/tpl-001-x.md": record(sha("# {{chant:name}} v2\n")) });
+    const staged = await stageUpgrade({ root: proj, to: "v2.0.0", runChant: passing });
+    try {
+      expect(staged.manualSteps).toEqual([]);
+      expect(read(staged.worktreeProject, "decisions/tpl-001-x.md")).toBe(record(sha("# Acme v2\n")));
+      expect(readLock(staged.worktreeProject)!.scopes["."].repinned).toEqual([{ record: "decisions/tpl-001-x.md", paths: ["README.md"] }]);
+    } finally {
+      staged.dispose();
+    }
+  });
+
   test("an upgrade to the same version changes nothing", async () => {
     const staged = await stageUpgrade({ root: proj, to: "v1.0.0", runChant: passing });
     try {

package/src/workspace/lineage-upgrade.ts

@@ -59,6 +59,7 @@ import { mergeFile } from "./lineage-merge";
 import { assertCodeAllowed, planMigrations, runMigration, splitMigrations, type LoadedMigration } from "./lineage-migrations";
 import { applyUpstream, type UpdateResult } from "./lineage-update";
 import { carryParameters, readManifest, substituteParameters } from "./template-manifest";
+import { repinSubstituted, type RepinnedRecord } from "./template-pins";
 
 /** The kind the patch digest is taken under, so it never collides with another kind of plan. */
 export const UPGRADE_PLAN_KIND = "workspace-upgrade";
@@ -184,6 +185,8 @@ interface Upstream {
   tree?: string;
   /** The parameter values substituted into `files` (#2627), for a git or directory source. */
   parameters?: Record<string, string>;
+  /** The records re-pinned to substituted files (#2549). */
+  repinned?: RepinnedRecord[];
   /** The source the lock records after the upgrade, when it moves (a directory source). */
   source?: LineageSource;
 }
@@ -191,13 +194,20 @@ interface Upstream {
 /**
  * The template's files as the project would have them (#2627): the manifest
  * removed and the parameters substituted, with the recorded values and the
- * defaults of parameters this version adds.
+ * defaults of parameters this version adds. Records that pin a substituted
+ * file are re-pinned as init re-pinned them (#2549), for the base and the
+ * target alike, so an unedited record compares equal to its base.
  */
-function instantiate(raw: Map<string, Buffer>, recorded: Record<string, unknown>, label: string): { files: Map<string, Buffer>; parameters: Record<string, string> } {
+function instantiate(
+  raw: Map<string, Buffer>,
+  recorded: Record<string, unknown>,
+  label: string,
+): { files: Map<string, Buffer>; parameters: Record<string, string>; repinned: RepinnedRecord[] } {
   try {
     const manifest = readManifest(raw);
     const parameters = carryParameters(manifest, recorded);
-    return { files: substituteParameters(raw, manifest, parameters), parameters };
+    const { files, repinned } = repinSubstituted(raw, substituteParameters(raw, manifest, parameters), manifest?.files ?? []);
+    return { files, parameters, repinned };
   } catch (err) {
     throw new UpgradeError(`${label}: ${(err as Error).message.replace(/; pass --param .*$/, "")}`);
   }
@@ -264,6 +274,7 @@ function fetchGit(root: string, lineage: Lineage, ref: string): Upstream {
       commit,
       tree: target.tree,
       parameters: instantiated.parameters,
+      repinned: instantiated.repinned,
     };
   } finally {
     rmSync(scratch, { recursive: true, force: true });
@@ -336,6 +347,7 @@ function readDir(root: string, lineage: Lineage, to: string | undefined): Upstre
     migrations: split.migrations,
     modules: split.modules,
     parameters: instantiated.parameters,
+    repinned: instantiated.repinned,
     source: { type: "dir", path: recordedDirPath(target.path, target.abs, root), ...(member ? { member } : {}) },
   };
 }
@@ -561,6 +573,12 @@ export async function stageUpgrade(options: UpgradeOptions): Promise<StagedUpgra
     for (const path of result.written) if (upstream.executable.has(path)) chmodSync(join(scopeDir, path), 0o755);
     if (ref !== undefined) staged.ref = ref;
     if (upstream.parameters) staged.parameters = upstream.parameters;
+    if (upstream.repinned) {
+      // The records this version re-pins, among the files the scope keeps (#2549).
+      const kept = upstream.repinned.filter((r) => staged.files[r.record] !== undefined || existsSync(join(scopeDir, r.record)));
+      if (kept.length > 0) staged.repinned = kept;
+      else delete staged.repinned;
+    }
     if (upstream.commit) staged.address = { ...staged.address!, commit: upstream.commit, tree: upstream.tree };
     if (upstream.source) staged.source = upstream.source;
     writeLock(worktreeProject, next);

package/src/workspace/member-commands.ts

@@ -379,7 +379,7 @@ const USAGE: Record<WorkspaceVerb, string> = {
   build: "chant workspace build [dir] [--member <name>] [-o <dir>] [--format json|yaml] [--env <env>] [--param k=v] [--dry-run]",
   lint: "chant workspace lint [dir] [--member <name>] [--format stylish|json|sarif] [-o <file>] [--fix] [--dry-run]",
   audit: "chant workspace audit [dir] [--member <name>] [--format stylish|json] [-o <file>] [--tier <tier>] [--fail-on <level>] [--dry-run]",
-  graph: "chant workspace graph [dir] [--member <name>] [-o <file>] [--env <env>] [--dry-run]",
+  graph: "chant workspace graph [dir] [--member <name>] [--kind <kind file>] [-o <file>] [--env <env>] [--dry-run]",
 };
 
 export function describePlan(plan: MemberPlan): string {

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

@@ -22,6 +22,8 @@ import { contract, git, REPO, validSchema } from "./__fixtures__/contract-repo";
 import checkSchema from "./check.schema.json";
 import { workspaceGraph } from "./graph-cli";
 import graphSchema from "./graph.schema.json";
+import { intentGraph } from "./intent";
+import intentSchema from "./intent.schema.json";
 import { runChecks } from "./lineage-check";
 import { listWorkspace } from "./ls";
 import lsSchema from "./ls.schema.json";
@@ -35,7 +37,7 @@ import statusSchema from "./status.schema.json";
 const FIXTURE = join(REPO, "reference-workspace");
 const TIMEOUT = 240_000;
 
-const SCHEMAS = { ls: lsSchema, graph: graphSchema, check: checkSchema, status: statusSchema, records: recordsSchema };
+const SCHEMAS = { ls: lsSchema, graph: graphSchema, check: checkSchema, status: statusSchema, records: recordsSchema, intent: intentSchema };
 
 /** This checkout's chant, started the way the CLI starts it, for members with no toolchain of their own. */
 const reader: Toolchain = {
@@ -116,6 +118,19 @@ describe("every schema against the reference workspace (#2543)", () => {
     expect(doc.members.map((m) => m.name)).toEqual(["app", "delivery", "design-client", "design"]);
   });
 
+  test("graph --intent, in the working tree and at HEAD (#2651)", async () => {
+    const { expectValid } = contract(intentSchema);
+    for (const at of [undefined, "HEAD"]) {
+      const { doc, failed } = await intentGraph({ cwd: FIXTURE, region: "app/src/server.mjs:19", at, kinds: ["decisions/decision.kind.mjs"] });
+      expectValid(doc);
+      if ("error" in doc) throw new Error(doc.error.message);
+      expect(failed).toBe(false);
+      expect(doc.workspace).toEqual({ name: "reference", root: "reference-workspace" });
+      expect(doc.at).toBe(at ? head : null);
+      expect(doc.region).toBe("region:app/src/server.mjs:19");
+    }
+  });
+
   test("records, in the working tree and at HEAD", async () => {
     const { expectValid } = contract(recordsSchema);
     for (const at of [undefined, "HEAD"]) {

package/src/workspace/reason-codes.test.ts

@@ -12,10 +12,11 @@ import { REPO } from "./__fixtures__/contract-repo";
 import { MEMBER_RUN_REASON_CODES } from "./compose-graph";
 import { WORKSPACE_ERROR_CODES } from "./declaration";
 import { GRAPH_ERROR_CODES } from "./graph-cli";
+import { INTENT_ERROR_CODES, INTENT_FINDING_CODES, INTENT_REASON_CODES } from "./intent";
 import { CHECK_CODES, CHECK_ERROR_CODES } from "./lineage-check";
 import { GROUP_REASON_CODES, MEMBER_REASON_CODES } from "./ls";
 import { isReasonCode, REASON_CODES, REASONS } from "./reason-codes";
-import { READ_ERROR_CODES, RECORD_REASON_CODES } from "./records";
+import { READ_ERROR_CODES, RECORD_REASON_CODES, RECORD_WARNING_CODES } from "./records";
 import { STATUS_ERROR_CODES, STATUS_REASON_CODES } from "./status";
 
 const HERE = import.meta.dirname;
@@ -31,7 +32,11 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   STATUS_REASON_CODES,
   STATUS_ERROR_CODES,
   RECORD_REASON_CODES,
+  RECORD_WARNING_CODES,
   READ_ERROR_CODES,
+  INTENT_ERROR_CODES,
+  INTENT_FINDING_CODES,
+  INTENT_REASON_CODES,
 };
 
 /** Every string in an `enum` under a property named `code`, anywhere in a schema. */
@@ -93,7 +98,7 @@ describe("the closed list of reason codes", () => {
   });
 
   test("no source file emits a code outside the list", () => {
-    const emitted = /(?:\bcode:\s*|(?:WorkspaceReadError|RecordReadError|StatusError)\(\s*)"([a-z0-9-]+)"/g;
+    const emitted = /(?:\bcode:\s*|(?:WorkspaceReadError|RecordReadError|StatusError|IntentError)\(\s*)"([a-z0-9-]+)"/g;
     let seen = 0;
     for (const file of sourceFiles(HERE)) {
       const text = readFileSync(file, "utf-8");

package/src/workspace/reason-codes.ts

@@ -59,6 +59,11 @@ export const REASONS = {
   "record-id-duplicate": "Another record earlier in path order has the same id.",
   "record-supersedes-unknown": "A supersedes link names an id no record has.",
   "record-supersedes-conflict": "A second closed record supersedes a record another one already superseded.",
+  // A record that is valid but warned about (records, #2549).
+  "asset-drift": "A file the record pins by hash has changed: its bytes no longer hash to the pinned sha256.",
+  "asset-missing": "A file the record pins by hash does not exist in the tree read.",
+  "asset-stale": "A file the record pins is unchanged at the hash a record it supersedes pinned: the decision changed and the artifact did not follow.",
+  "record-supersedes-pending": "A supersedes link from a record whose state is weaker than the record it names, so the link has no effect yet.",
   // A records read that fails (records).
   "kind-unreadable": "The record kind file is missing or could not be imported.",
   "kind-invalid": "The record kind file exports no recordKind, or its shape is wrong.",
@@ -66,6 +71,24 @@ export const REASONS = {
   "schema-id-mismatch": "The schema's $id differs from the id the record kind names.",
   "schema-invalid": "The record schema itself does not compile.",
   "location-missing": "The records directory does not exist, in the tree or at the revision.",
+  // The intent graph (graph --intent, #2651): a read that fails.
+  "intent-region-invalid": "The region's path, or its line range, does not exist in the tree read.",
+  // The intent graph: part of the walk that can't be read. The document is still printed.
+  "intent-history-shallow": "The repository is a shallow clone, so the region's history stops at the clone's boundary.",
+  "intent-plugin-failed": "A kind file's commitJoins, which joins commits to units, contracts and evidence, failed for a commit.",
+  // The intent graph: findings, each a node in the graph.
+  "intent-commit-undecided": "A commit changed the region when no decision constrained it at path granularity.",
+  "intent-commit-bare": "A commit names no unit, no pull request and no decision covering the region at its time.",
+  "intent-pin-drifted": "A decision's pinned artifact no longer hashes to the pin.",
+  "intent-pin-missing": "A decision's pinned artifact does not exist in the tree read.",
+  "intent-artifact-unpinned": "An artifact decisions in the graph pinned, which no current decision pins.",
+  "intent-decision-superseded-live": "Every decision constraining the region is superseded.",
+  "intent-decision-provisional": "The current decisions constraining the region are all in states their kind does not close, such as decided.",
+  "intent-constraint-coarse": "The region is constrained only through its member, not by path.",
+  "intent-constraint-lost": "A decision's path constraint names a path that does not exist in the tree read.",
+  "intent-evidence-unpinned": "A decision's evidence has no hash: a URL, or a path with no sha256.",
+  "intent-trailer-unverified": "A commit carries a trailer a plugin says claims authorship, and the commit is not attested.",
+  "intent-region-unconstrained": "No decision constrains the region at any granularity.",
   // The lineage lock (check).
   "lock-invalid": "The lineage lock can't be read.",
   "manual-step-open": "A scope in the lineage lock has an open manual step.",