@intentius/chant 0.53.0 → 0.54.0

package/src/lifecycle/release-ledger.test.ts

@@ -11,6 +11,7 @@ import {
   InvalidReleaseRecordError,
   latestPerComponent,
   recordsForDigest,
+  resolveRunId,
   type ReleaseRecord,
   type ReleaseRecordInput,
 } from "./release-ledger";
@@ -234,4 +235,67 @@ describe("release-ledger", () => {
       expect(found.every((r) => r.digest === "sha256:shared")).toBe(true);
     });
   });
+
+  describe("resolveRunId (#2045)", () => {
+    test("GitHub Actions env resolves id + origin together, with repo and run url", () => {
+      const env = {
+        GITHUB_RUN_ID: "18234771902",
+        GITHUB_REPOSITORY: "INTENTIUS/chant",
+        GITHUB_SERVER_URL: "https://github.com",
+      };
+      expect(resolveRunId(undefined, env)).toEqual({
+        runId: "18234771902",
+        runOrigin: {
+          forge: "github",
+          repo: "INTENTIUS/chant",
+          url: "https://github.com/INTENTIUS/chant/actions/runs/18234771902",
+        },
+      });
+    });
+
+    test("a Forgejo instance resolves through the same env contract to its own host", () => {
+      const env = {
+        GITHUB_RUN_ID: "42",
+        GITHUB_REPOSITORY: "intentius/loomster",
+        GITHUB_SERVER_URL: "https://forge.example.dev",
+      };
+      expect(resolveRunId(undefined, env).runOrigin!.url).toBe("https://forge.example.dev/intentius/loomster/actions/runs/42");
+    });
+
+    test("GitLab CI env records the project path and takes CI_PIPELINE_URL verbatim", () => {
+      const env = {
+        CI_PIPELINE_ID: "991",
+        CI_PROJECT_PATH: "group/app",
+        CI_PIPELINE_URL: "https://gitlab.com/group/app/-/pipelines/991",
+      };
+      expect(resolveRunId(undefined, env)).toEqual({
+        runId: "991",
+        runOrigin: { forge: "gitlab", repo: "group/app", url: "https://gitlab.com/group/app/-/pipelines/991" },
+      });
+    });
+
+    test("outside CI the mint says local in a field, not only in the id's spelling", () => {
+      const { runId, runOrigin } = resolveRunId(undefined, {});
+      expect(runId).toMatch(/^local-\d+$/);
+      expect(runOrigin).toEqual({ forge: "local" });
+    });
+
+    test("an explicit id gets an origin only when it matches what the environment advertises", () => {
+      const env = { GITHUB_RUN_ID: "42", GITHUB_REPOSITORY: "o/r", GITHUB_SERVER_URL: "https://github.com" };
+      expect(resolveRunId("42", env).runOrigin?.forge).toBe("github");
+      expect(resolveRunId("something-else", env).runOrigin).toBeUndefined();
+    });
+
+    test("a record carrying runOrigin round-trips through the ledger", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const input = makeInput({
+          runOrigin: { forge: "github", repo: "o/r", url: "https://github.com/o/r/actions/runs/1" },
+        });
+        await appendReleaseRecord(input, { cwd: dir });
+        const { records } = await readReleaseLedger("prod", { cwd: dir });
+        expect(records[0].runOrigin).toEqual(input.runOrigin);
+      });
+    });
+  });
 });

package/src/lifecycle/release-ledger.ts

@@ -31,6 +31,25 @@
 import { sortedJsonReplacer } from "../utils";
 import { appendReleaseRecordLine, readReleaseLedgerLines, listLedgerEnvironments as gitListLedgerEnvironments } from "./git";
 
+/**
+ * The id space a `ReleaseRecord.runId` lives in, and how to reach the run
+ * (#2045).
+ */
+export interface RunOrigin {
+  /**
+   * Which id space minted `runId`: `github` (a GitHub Actions run id — also
+   * the spelling Forgejo Actions uses, since it implements the same env
+   * contract; `url` disambiguates the actual host), `gitlab` (a CI pipeline
+   * id), `op` (an orchestrator/Op run id), or `local` (minted on the machine
+   * that ran the deploy, resolvable nowhere).
+   */
+  forge: "github" | "gitlab" | "op" | "local";
+  /** Repo/project slug on the forge (`GITHUB_REPOSITORY` / `CI_PROJECT_PATH`), when the environment named one. */
+  repo?: string;
+  /** Resolved link to the run, when the environment provided enough to build one. */
+  url?: string;
+}
+
 /**
  * One immutable deploy record: `(component, env, artifact digest, git sha,
  * run id, timestamp, actor)`, referencing the build archive by digest — the
@@ -54,8 +73,19 @@ export interface ReleaseRecord {
   digest: string;
   /** Git commit SHA the deploy was built from. */
   gitSha: string;
-  /** Orchestrator run identifier (a `DriverRunResult`/Op run id, or a CI run id in generate mode) — the pointer back into the deploy event log. */
+  /** Orchestrator run identifier (a `DriverRunResult`/Op run id, or a CI run id in generate mode) — the pointer back into the deploy event log. Which id space it lives in, and how to follow it, is `runOrigin`'s job (#2045). */
   runId: string;
+  /**
+   * Where `runId` can be resolved (#2045). A bare `runId` names a run in one
+   * of several mutually incompatible id spaces — a GitHub Actions run id, a
+   * GitLab pipeline id, an Op run id, a locally minted id — and without this
+   * a reader can tell them apart only by inference from whoever wrote the
+   * record. Written at record time from the same environment the id came
+   * from, so the two cannot skew. Optional: records written before this
+   * field existed, and callers passing an id whose origin they did not
+   * declare, simply have none.
+   */
+  runOrigin?: RunOrigin;
   /**
    * When this record was written. The caller supplies this — the session
    * cannot call `Date.now()` reliably in every context, so the CLI resolves
@@ -132,6 +162,54 @@ export function validateReleaseRecord(record: Partial<ReleaseRecord>): string[]
 /** Input a caller supplies to record one deploy — `version` is filled in, everything else is required (see `ReleaseRecord`). */
 export type ReleaseRecordInput = Omit<ReleaseRecord, "version">;
 
+/**
+ * Resolve a run id and its origin from the same environment, in one step, so
+ * the two cannot skew (#2045). Resolution order mirrors what
+ * `chant components release` always did — explicit id, then
+ * `GITHUB_RUN_ID`, then `CI_PIPELINE_ID`, then a locally minted
+ * `local-<ms>` — but now each source also names its id space:
+ *
+ *  - the GitHub path records `repo` (`GITHUB_REPOSITORY`) and builds the run
+ *    `url` from `GITHUB_SERVER_URL` — which also makes a Forgejo instance's
+ *    runs resolvable, since Forgejo Actions implements the same env contract;
+ *  - the GitLab path records `repo` (`CI_PROJECT_PATH`) and takes
+ *    `CI_PIPELINE_URL` verbatim;
+ *  - the local mint says `local` in a field instead of only in the id's
+ *    spelling.
+ *
+ * An explicit id still gets an origin when it matches the id the environment
+ * itself is advertising (a CI job passing `--run-id $GITHUB_RUN_ID`);
+ * otherwise the caller's id is recorded without one — guessing an origin the
+ * caller did not state would be exactly the inference this field exists to
+ * remove.
+ */
+export function resolveRunId(
+  explicit?: string,
+  env: NodeJS.ProcessEnv = process.env,
+): { runId: string; runOrigin?: RunOrigin } {
+  const githubOrigin = (id: string): RunOrigin => ({
+    forge: "github",
+    ...(env.GITHUB_REPOSITORY ? { repo: env.GITHUB_REPOSITORY } : {}),
+    ...(env.GITHUB_SERVER_URL && env.GITHUB_REPOSITORY
+      ? { url: `${env.GITHUB_SERVER_URL}/${env.GITHUB_REPOSITORY}/actions/runs/${id}` }
+      : {}),
+  });
+  const gitlabOrigin = (): RunOrigin => ({
+    forge: "gitlab",
+    ...(env.CI_PROJECT_PATH ? { repo: env.CI_PROJECT_PATH } : {}),
+    ...(env.CI_PIPELINE_URL ? { url: env.CI_PIPELINE_URL } : {}),
+  });
+
+  if (explicit) {
+    if (env.GITHUB_RUN_ID && explicit === env.GITHUB_RUN_ID) return { runId: explicit, runOrigin: githubOrigin(explicit) };
+    if (env.CI_PIPELINE_ID && explicit === env.CI_PIPELINE_ID) return { runId: explicit, runOrigin: gitlabOrigin() };
+    return { runId: explicit };
+  }
+  if (env.GITHUB_RUN_ID) return { runId: env.GITHUB_RUN_ID, runOrigin: githubOrigin(env.GITHUB_RUN_ID) };
+  if (env.CI_PIPELINE_ID) return { runId: env.CI_PIPELINE_ID, runOrigin: gitlabOrigin() };
+  return { runId: `local-${Date.now()}`, runOrigin: { forge: "local" } };
+}
+
 /**
  * Append one immutable release record to the `<env>` ledger on the
  * `chant/lifecycle` orphan branch. Throws `InvalidReleaseRecordError` before

package/src/op/activity-contract.ts

@@ -75,6 +75,18 @@ export interface ActivityContract<Args = unknown, Return = unknown> {
    * per #1290 — a later step's reference into this one's output.
    */
   returns?: z.ZodType<Return>;
+  /**
+   * Names of top-level args whose values identify what the activity's effect
+   * touches in the estate (#2022) — an entity id, a resource address, a
+   * target endpoint — as opposed to scope (`env`, a stack name) or mechanics
+   * (a timeout, a mode). op.json's IR resolves these per step into
+   * `OpIRActivityStep.entities`, so a renderer can join a step to the estate
+   * nodes it touches instead of inventing joins off scope fields. Optional
+   * and partial by design, like the contract itself: an activity whose
+   * touched set is not spelled in its args (e.g. an applier that derives
+   * stack members internally) simply declares none.
+   */
+  entities?: string[];
 }
 
 /** Declare an activity contract. */
@@ -82,12 +94,14 @@ export function activityContract<ArgsSchema extends z.ZodTypeAny, ReturnSchema e
   name: string,
   args: ArgsSchema,
   returns?: ReturnSchema,
+  opts?: { entities?: string[] },
 ): ActivityContract<z.infer<ArgsSchema>, ReturnSchema extends z.ZodTypeAny ? z.infer<ReturnSchema> : unknown> {
   return {
     [CONTRACT_BRAND]: true,
     name,
     args,
     ...(returns ? { returns } : {}),
+    ...(opts?.entities && opts.entities.length > 0 ? { entities: opts.entities } : {}),
   } as ActivityContract<z.infer<ArgsSchema>, ReturnSchema extends z.ZodTypeAny ? z.infer<ReturnSchema> : unknown>;
 }
 

package/src/terraform/manifest.test.ts

@@ -3,10 +3,12 @@ import { mkdtempSync, rmSync, writeFileSync } from "fs";
 import { tmpdir } from "os";
 import { join } from "path";
 import {
+  CARVE_MANIFEST_VERSION,
   carveManifestPath,
   listCarveManifests,
   readCarveManifest,
   resolveCarveManifest,
+  resolveManifestFilePath,
   updateCarveManifest,
   writeCarveManifest,
   type CarveManifest,
@@ -89,6 +91,56 @@ describe("carve manifest", () => {
     });
   });
 
+  test("records file paths relative to its own directory, so the tree can move (#2039)", () => {
+    withDir((dir) => {
+      const m = manifest("aws_s3_bucket.assets");
+      m.emit = { source: "tfstate", files: [join(dir, "src", "assets.ts")], at: "t" };
+      m.bridge = {
+        written: [join(dir, "aws_s3_bucket-assets-runbook.md"), join(dir, "..", "api.tf")],
+        appliedInPlace: false,
+        patch: join(dir, "aws_s3_bucket-assets-bridge.patch"),
+        at: "t",
+      };
+      const path = writeCarveManifest(dir, m);
+      const read = readCarveManifest(path)!;
+      expect(read.version).toBe(CARVE_MANIFEST_VERSION);
+      expect(read.emit!.files).toEqual([join("src", "assets.ts")]);
+      expect(read.bridge!.written).toEqual(["aws_s3_bucket-assets-runbook.md", join("..", "api.tf")]);
+      expect(read.bridge!.patch).toBe("aws_s3_bucket-assets-bridge.patch");
+      // `from`/`statePath` locate the estate, a tree the manifest does not
+      // travel with — they stay absolute.
+      expect(read.from).toBe("/estate");
+    });
+  });
+
+  test("resolveManifestFilePath joins relative entries and passes absolute (v1) entries through", () => {
+    expect(resolveManifestFilePath("/moved/carveout", join("src", "assets.ts"))).toBe(join("/moved/carveout", "src", "assets.ts"));
+    expect(resolveManifestFilePath("/moved/carveout", "/original/carveout/src/assets.ts")).toBe("/original/carveout/src/assets.ts");
+  });
+
+  test("reads a version-1 manifest (absolute paths) and migrates it on update", () => {
+    withDir((dir) => {
+      const path = carveManifestPath(dir, "aws_s3_bucket.assets");
+      const v1: CarveManifest = {
+        ...manifest("aws_s3_bucket.assets"),
+        version: 1,
+        emit: { source: "tfstate", files: [join(dir, "src", "assets.ts")], at: "t" },
+      };
+      writeFileSync(path, JSON.stringify(v1, null, 2) + "\n");
+      // Readable as-is, absolute paths intact.
+      expect(readCarveManifest(path)!.emit!.files).toEqual([join(dir, "src", "assets.ts")]);
+
+      // Any update rewrites the whole manifest to the version-2 contract.
+      updateCarveManifest(dir, "aws_s3_bucket.assets", {
+        bridge: { written: [join(dir, "runbook.md")], appliedInPlace: false, at: "t" },
+      });
+      const migrated = readCarveManifest(path)!;
+      expect(migrated.version).toBe(CARVE_MANIFEST_VERSION);
+      expect(migrated.emit!.files).toEqual([join("src", "assets.ts")]);
+      expect(migrated.bridge!.written).toEqual(["runbook.md"]);
+    });
+  });
+
   test("update patches an existing manifest and no-ops on a missing one", () => {
     withDir((dir) => {
       expect(updateCarveManifest(dir, "aws_s3_bucket.assets", { bridge: { written: [], appliedInPlace: false, at: "t" } })).toBeUndefined();

package/src/terraform/manifest.ts

@@ -9,14 +9,23 @@
  */
 
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "fs";
-import { join } from "path";
+import { isAbsolute, join, relative } from "path";
 import type { CarveReport } from "./carve";
 import type { OwnershipMarker } from "../ownership";
 
 export const CARVE_MANIFEST_SUFFIX = ".carve.json";
 
+/**
+ * Version 2 (#2039): `emit.files`, `bridge.written`, `bridge.patch` and
+ * `apply.stampedFiles` are recorded relative to the manifest's own directory,
+ * so the manifest stays true when the tree is copied, moved, or checked out
+ * elsewhere. Version-1 manifests recorded them absolute; readers resolve
+ * either through `resolveManifestFilePath`.
+ */
+export const CARVE_MANIFEST_VERSION = 2;
+
 export interface CarveManifest {
-  version: 1;
+  version: 1 | 2;
   /** Terraform address of the carved resource, e.g. `aws_s3_bucket.assets`. */
   target: string;
   /** Terraform resource type, when known. */
@@ -30,7 +39,13 @@ export interface CarveManifest {
   /** Recorded by `carve emit`. */
   emit?: {
     source: "tfstate" | "live";
-    /** Emitted chant source file path(s). */
+    /**
+     * Emitted chant source file path(s), relative to the manifest's directory
+     * (absolute in version-1 manifests). The manifest sits at the scaffolded
+     * project's root, so these are also project-root-relative — the same base
+     * `chant graph --format ir` uses for `sourceLoc.file`, which is the join
+     * from a carved Terraform address to the chant entity it became (#2040).
+     */
     files: string[];
     /**
      * Deferred outbound inputs declared as build parameters in the emitted
@@ -53,9 +68,10 @@ export interface CarveManifest {
   };
   /** Recorded by `carve bridge`. */
   bridge?: {
+    /** Files written, relative to the manifest's directory (absolute in version-1 manifests). */
     written: string[];
     appliedInPlace: boolean;
-    /** The git-applyable `.patch` carrying the whole survivor edit. */
+    /** The git-applyable `.patch` carrying the whole survivor edit, relative to the manifest's directory (absolute in version-1 manifests). */
     patch?: string;
     /** Carved addresses whose own `.tf` block the rewrites remove (#998). */
     excised?: string[];
@@ -65,7 +81,7 @@ export interface CarveManifest {
   apply?: {
     marker: OwnershipMarker;
     ownershipTags: Record<string, string>;
-    /** Emitted files the marker was stamped into (`--write-source`). */
+    /** Emitted files the marker was stamped into (`--write-source`), relative to the manifest's directory (absolute in version-1 manifests). */
     stampedFiles?: string[];
     at: string;
   };
@@ -81,20 +97,62 @@ export function carveManifestPath(outDir: string, target: string): string {
   return join(outDir, `${carveSlug(target)}${CARVE_MANIFEST_SUFFIX}`);
 }
 
+/**
+ * Relative-to-`outDir` spelling of a recorded file path. Absolute entries
+ * (the run-time spelling every step naturally produces, and every version-1
+ * manifest on disk) are rewritten; already-relative entries pass through.
+ */
+function relativizePath(outDir: string, p: string): string {
+  return isAbsolute(p) ? relative(outDir, p) : p;
+}
+
+/**
+ * Normalize a manifest to the version-2 on-disk contract: recorded file
+ * paths relative to the manifest's own directory (#2039). `from` and
+ * `statePath` stay absolute — they locate the Terraform estate, a different
+ * tree the manifest does not travel with.
+ */
+function normalizeManifest(outDir: string, manifest: CarveManifest): CarveManifest {
+  const out: CarveManifest = { ...manifest, version: CARVE_MANIFEST_VERSION };
+  if (manifest.emit) {
+    out.emit = { ...manifest.emit, files: manifest.emit.files.map((f) => relativizePath(outDir, f)) };
+  }
+  if (manifest.bridge) {
+    out.bridge = {
+      ...manifest.bridge,
+      written: manifest.bridge.written.map((f) => relativizePath(outDir, f)),
+      ...(manifest.bridge.patch !== undefined ? { patch: relativizePath(outDir, manifest.bridge.patch) } : {}),
+    };
+  }
+  if (manifest.apply?.stampedFiles) {
+    out.apply = { ...manifest.apply, stampedFiles: manifest.apply.stampedFiles.map((f) => relativizePath(outDir, f)) };
+  }
+  return out;
+}
+
+/**
+ * Resolve a manifest-recorded file path against the manifest's directory.
+ * Absolute paths (version-1 manifests) pass through untouched, so both
+ * on-disk spellings read the same.
+ */
+export function resolveManifestFilePath(manifestDir: string, p: string): string {
+  return isAbsolute(p) ? p : join(manifestDir, p);
+}
+
 /** Write (or overwrite) a manifest into the output dir. Returns the path. */
 export function writeCarveManifest(outDir: string, manifest: CarveManifest): string {
   mkdirSync(outDir, { recursive: true });
   const path = carveManifestPath(outDir, manifest.target);
-  writeFileSync(path, JSON.stringify(manifest, null, 2) + "\n");
+  writeFileSync(path, JSON.stringify(normalizeManifest(outDir, manifest), null, 2) + "\n");
   return path;
 }
 
-/** Read a manifest, or null when absent/unreadable/not a v1 manifest. */
+/** Read a manifest, or null when absent/unreadable/not a known-version manifest. */
 export function readCarveManifest(path: string): CarveManifest | null {
   if (!existsSync(path)) return null;
   try {
     const parsed = JSON.parse(readFileSync(path, "utf-8")) as CarveManifest;
-    if (parsed?.version !== 1) return null;
+    if (parsed?.version !== 1 && parsed?.version !== 2) return null;
     if (typeof parsed.target !== "string" || typeof parsed.boundary !== "object") return null;
     return parsed;
   } catch {
@@ -147,7 +205,11 @@ export function resolveCarveManifest(outDir: string, select?: string): ResolvedM
   return { manifest: manifests[0].manifest, path: manifests[0].path };
 }
 
-/** Read-modify-write a section of an existing manifest. No-op when absent. */
+/**
+ * Read-modify-write a section of an existing manifest. No-op when absent.
+ * The whole manifest is re-normalized on write, so updating a version-1
+ * manifest also migrates its recorded paths to the relative contract.
+ */
 export function updateCarveManifest(
   outDir: string,
   target: string,
@@ -157,6 +219,6 @@ export function updateCarveManifest(
   const manifest = readCarveManifest(path);
   if (!manifest) return undefined;
   Object.assign(manifest, patch);
-  writeFileSync(path, JSON.stringify(manifest, null, 2) + "\n");
+  writeFileSync(path, JSON.stringify(normalizeManifest(outDir, manifest), null, 2) + "\n");
   return path;
 }