@intentius/chant 0.61.0 → 0.63.0

package/src/op/activities/lexicon-upgrade.test.ts

@@ -9,6 +9,7 @@ import {
   buildUpgradeSummary,
   computeBumpedVersion,
   bumpPackageJsonVersion,
+  lexiconUpgradeIssueMarker,
   type CheckPinnedFn,
   type CheckRollingFn,
   type BumpPackageVersionFn,
@@ -223,21 +224,105 @@ describe("lexiconUpgrade report mode", () => {
 
 // ── issue mode ────────────────────────────────────────────────────────
 
+describe("lexiconUpgradeIssueMarker (#2297)", () => {
+  test("deterministic per lexicon, and distinct across lexicons", () => {
+    expect(lexiconUpgradeIssueMarker("k8s")).toBe("<!-- chant-lexicon-upgrade:k8s -->");
+    expect(lexiconUpgradeIssueMarker("k8s")).toBe(lexiconUpgradeIssueMarker("k8s"));
+    expect(lexiconUpgradeIssueMarker("k8s")).not.toBe(lexiconUpgradeIssueMarker("aws"));
+  });
+});
+
 describe("lexiconUpgrade issue mode", () => {
-  test("opens an issue for a ready upgrade", async () => {
+  test("outside any known CI job, falls back to gh's own ambient gh issue create, marker-prefixed", async () => {
     const checkPinned: CheckPinnedFn = vi.fn(async () => pinnedResult());
     const { gh, calls } = recordingGh();
 
-    const r = await lexiconUpgrade({
-      lexicon: "gcp",
-      mode: "issue",
-      _checkPinned: checkPinned,
-      _gh: gh,
+    vi.stubEnv("GITHUB_REPOSITORY", "");
+    try {
+      const r = await lexiconUpgrade({
+        lexicon: "gcp",
+        mode: "issue",
+        _checkPinned: checkPinned,
+        _gh: gh,
+      });
+
+      expect(r.issueUrl).toBe("https://gh/issue/1");
+      expect(calls.some((c) => c.includes("gh issue create"))).toBe(true);
+      expect(calls.some((c) => c.includes("gh pr create"))).toBe(false);
+      expect(calls.some((c) => c.includes("<!-- chant-lexicon-upgrade:gcp -->"))).toBe(true);
+    } finally {
+      vi.unstubAllEnvs();
+    }
+  });
+
+  test("on a GitHub Actions job (GITHUB_REPOSITORY set), opens the sticky issue via gh api (#2297)", async () => {
+    const checkPinned: CheckPinnedFn = vi.fn(async () => pinnedResult());
+    const calls: Array<{ cmd: string; env?: NodeJS.ProcessEnv }> = [];
+    const gh = vi.fn(async (cmd: string, opts?: { env?: NodeJS.ProcessEnv }) => {
+      calls.push({ cmd, env: opts?.env });
+      if (cmd.includes("--paginate")) return { stdout: "", stderr: "" }; // no owned issue yet
+      if (cmd.includes("--method POST")) return { stdout: "https://github.com/acme/infra/issues/11\n", stderr: "" };
+      return { stdout: "", stderr: "" };
     });
 
-    expect(r.issueUrl).toBe("https://gh/issue/1");
-    expect(calls.some((c) => c.includes("gh issue create"))).toBe(true);
-    expect(calls.some((c) => c.includes("gh pr create"))).toBe(false);
+    vi.stubEnv("GITHUB_REPOSITORY", "acme/infra");
+    vi.stubEnv("GITHUB_API_URL", "");
+    vi.stubEnv("CHANT_FORGEJO_TOKEN", "");
+    vi.stubEnv("GH_TOKEN", "ghs-workflow");
+    try {
+      const r = await lexiconUpgrade({
+        lexicon: "gcp",
+        mode: "issue",
+        _checkPinned: checkPinned,
+        _gh: gh,
+      });
+
+      expect(r.issueUrl).toBe("https://github.com/acme/infra/issues/11");
+      expect(calls.some((c) => c.cmd.includes("gh issue create"))).toBe(false);
+      const post = calls.find((c) => c.cmd.includes("--method POST"));
+      expect(post?.cmd).toContain("https://api.github.com/repos/acme/infra/issues");
+      expect(post?.cmd).toContain("<!-- chant-lexicon-upgrade:gcp -->");
+      // #2320: the shared `postOrUpdateGithubIssue` resolves the credential
+      // and hands it to the runner, so this caller gets the same forwarding
+      // reconcilePr's issue mode does rather than leaving `gh` to guess.
+      for (const call of calls) expect(call.env?.GH_TOKEN).toBe("ghs-workflow");
+    } finally {
+      vi.unstubAllEnvs();
+    }
+  });
+
+  test("a re-run on a GitHub Actions job PATCHes the issue it already owns (#2297)", async () => {
+    const checkPinned: CheckPinnedFn = vi.fn(async () => pinnedResult());
+    const calls: Array<{ cmd: string; env?: NodeJS.ProcessEnv }> = [];
+    const gh = vi.fn(async (cmd: string, opts?: { env?: NodeJS.ProcessEnv }) => {
+      calls.push({ cmd, env: opts?.env });
+      if (cmd.includes("--paginate")) return { stdout: "11\n", stderr: "" }; // marker search found issue 11
+      if (cmd.includes("--method PATCH")) return { stdout: "https://github.com/acme/infra/issues/11\n", stderr: "" };
+      return { stdout: "", stderr: "" };
+    });
+
+    vi.stubEnv("GITHUB_REPOSITORY", "acme/infra");
+    vi.stubEnv("GITHUB_API_URL", "");
+    // The cross-instance case (#2320): a Forgejo token that must outrank the
+    // job's own `github.token`, on the path that used to forward neither.
+    vi.stubEnv("CHANT_FORGEJO_TOKEN", "forgejo-cross-instance");
+    vi.stubEnv("GH_TOKEN", "ghs-this-instance-only");
+    try {
+      const r = await lexiconUpgrade({
+        lexicon: "gcp",
+        mode: "issue",
+        _checkPinned: checkPinned,
+        _gh: gh,
+      });
+
+      expect(r.issueUrl).toBe("https://github.com/acme/infra/issues/11");
+      expect(calls.some((c) => c.cmd.includes("--method POST"))).toBe(false);
+      expect(calls.some((c) => c.cmd.includes("gh issue create"))).toBe(false);
+      const patch = calls.find((c) => c.cmd.includes("--method PATCH"));
+      expect(patch?.env?.GH_TOKEN).toBe("forgejo-cross-instance");
+    } finally {
+      vi.unstubAllEnvs();
+    }
   });
 });
 
@@ -260,21 +345,26 @@ describe("lexiconUpgrade breakage handling", () => {
     );
     const { gh, calls } = recordingGh();
 
-    const r = await lexiconUpgrade({
-      lexicon: "k8s",
-      mode: "pull-request",
-      _checkPinned: checkPinned,
-      _gh: gh,
-    });
-
-    expect(r.validationOk).toBe(false);
-    expect(r.issueUrl).toBe("https://gh/issue/1");
-    expect(r.prUrl).toBeUndefined();
-    // must NOT open a PR, must NOT push
-    expect(calls.some((c) => c.includes("gh pr create"))).toBe(false);
-    expect(calls.some((c) => c.includes("gh issue create"))).toBe(true);
-    // the issue body carries the failure diff
-    expect(r.summary).toContain("type error");
+    vi.stubEnv("GITHUB_REPOSITORY", "");
+    try {
+      const r = await lexiconUpgrade({
+        lexicon: "k8s",
+        mode: "pull-request",
+        _checkPinned: checkPinned,
+        _gh: gh,
+      });
+
+      expect(r.validationOk).toBe(false);
+      expect(r.issueUrl).toBe("https://gh/issue/1");
+      expect(r.prUrl).toBeUndefined();
+      // must NOT open a PR, must NOT push
+      expect(calls.some((c) => c.includes("gh pr create"))).toBe(false);
+      expect(calls.some((c) => c.includes("gh issue create"))).toBe(true);
+      // the issue body carries the failure diff
+      expect(r.summary).toContain("type error");
+    } finally {
+      vi.unstubAllEnvs();
+    }
   });
 
   test("upstream fetch error surfaces as a non-upgrade report, never a PR", async () => {
@@ -473,20 +563,25 @@ describe("lexiconUpgrade pull-request mode: package.json version bump", () => {
       return { stdout: "", stderr: "" };
     });
 
-    const r = await lexiconUpgrade({
-      lexicon: "aws",
-      mode: "pull-request",
-      _checkRolling: checkRolling,
-      _bumpPackageVersion: bumpFn,
-      _gh: gh,
-    });
-
-    // Rolling drift → issue, never a baseline-only PR, a branch push, or a bump.
-    expect(r.mode).toBe("issue");
-    expect(r.issueUrl).toBe("https://gh/issue/9");
-    expect(calls.some((c) => c.includes("gh issue create"))).toBe(true);
-    expect(calls.some((c) => c.includes("gh pr create"))).toBe(false);
-    expect(calls.some((c) => c.startsWith("git "))).toBe(false);
-    expect(bumpFn).not.toHaveBeenCalled();
+    vi.stubEnv("GITHUB_REPOSITORY", "");
+    try {
+      const r = await lexiconUpgrade({
+        lexicon: "aws",
+        mode: "pull-request",
+        _checkRolling: checkRolling,
+        _bumpPackageVersion: bumpFn,
+        _gh: gh,
+      });
+
+      // Rolling drift → issue, never a baseline-only PR, a branch push, or a bump.
+      expect(r.mode).toBe("issue");
+      expect(r.issueUrl).toBe("https://gh/issue/9");
+      expect(calls.some((c) => c.includes("gh issue create"))).toBe(true);
+      expect(calls.some((c) => c.includes("gh pr create"))).toBe(false);
+      expect(calls.some((c) => c.startsWith("git "))).toBe(false);
+      expect(bumpFn).not.toHaveBeenCalled();
+    } finally {
+      vi.unstubAllEnvs();
+    }
   });
 });

package/src/op/activities/lexicon-upgrade.ts

@@ -28,6 +28,7 @@ import { join } from "node:path";
 import type { UpgradeCheckResult, LexiconId } from "../../codegen/pinned-upgrade";
 import type { RollingUpgradeResult, RollingLexicon } from "../../codegen/rolling-upgrade";
 import { bumpForSeverity, bumpPackageJsonVersion } from "../../codegen/version-bump";
+import { postOrUpdateGithubIssue } from "./reconcile";
 
 export { bumpPackageJsonVersion };
 
@@ -94,7 +95,7 @@ export interface LexiconUpgradeResult {
   semverLabel: SemverLabel | null;
   /** URL of the opened/updated PR (pull-request mode). */
   prUrl?: string;
-  /** URL of the opened issue (issue mode). */
+  /** URL of the opened or edited issue (issue mode; sticky per lexicon, #2297). */
   issueUrl?: string;
   /** Full markdown summary, used as PR/issue body or printed in report mode. */
   summary: string;
@@ -119,8 +120,21 @@ export type CheckRollingFn = (opts: {
   verbose?: boolean;
 }) => Promise<RollingUpgradeResult>;
 
-/** Minimal shell-exec interface for gh/git invocations. */
-export type GhRunner = (cmd: string) => Promise<{ stdout: string; stderr: string }>;
+/**
+ * Minimal shell-exec interface for gh/git invocations.
+ *
+ * `opts` carries the environment `postOrUpdateGithubIssue` resolves the issue
+ * credential into (chant #2320) — the same `GhExec` shape reconcile.ts
+ * declares, so the two stay one signature and this can keep being passed
+ * straight through. Every other call site here forwards nothing and passes
+ * nothing. A mock runner is free to ignore the argument; the default one
+ * hands it to `execAsync`, which is what makes CHANT_FORGEJO_TOKEN actually
+ * reach `gh` on a cross-instance Forgejo run.
+ */
+export type GhRunner = (
+  cmd: string,
+  opts?: { env?: NodeJS.ProcessEnv },
+) => Promise<{ stdout: string; stderr: string }>;
 
 /** Applies a pinned version bump permanently (no revert). Async (core loads the lexicon's pin descriptor); a sync mock is also accepted. */
 export type ApplyBumpFn = (
@@ -282,7 +296,53 @@ function shellQuote(s: string): string {
   return `'${s.replace(/'/g, "'\\''")}'`;
 }
 
-const defaultGh: GhRunner = async (cmd) => execAsync(cmd);
+const defaultGh: GhRunner = async (cmd, opts) => execAsync(cmd, { ...opts });
+
+/**
+ * The hidden marker that makes this lexicon's upgrade-status issue findable
+ * across re-runs (#2297): written as the issue body's first line, matched by
+ * `startswith` — the same recipe reconcile.ts's `issueMarker` names for a
+ * reconcile finding, kept as its own function because the two activities own
+ * different issues. Keyed on `lexicon`, not on the validation outcome: a
+ * lexicon has one upgrade-status issue that flips between "validation
+ * failed" and "upgrade ready" as reality changes, rather than a second issue
+ * for the other outcome. `lexicon` is a closed set of known identifiers
+ * (see `SupportedLexicon`), so unlike `issueMarker` this needs no slugifying.
+ */
+export function lexiconUpgradeIssueMarker(lexicon: SupportedLexicon): string {
+  return `<!-- chant-lexicon-upgrade:${lexicon} -->`;
+}
+
+/**
+ * Open or update this lexicon's upgrade-status issue (#2297). On a GitHub
+ * Actions or Forgejo Actions job (`GITHUB_REPOSITORY` set) this is
+ * `postOrUpdateGithubIssue`'s sticky recipe from reconcile.ts: find the OPEN
+ * issue already carrying this lexicon's marker, edit it, open one only when
+ * there is none — see that function's own doc comment for the search
+ * mechanism and the close decision (never closed here either). Outside any
+ * known CI job, falls back to `gh`'s own ambient `gh issue create`, still
+ * marker-prefixed so a later CI run finds and edits it instead of opening a
+ * second one.
+ */
+async function postLexiconIssue(
+  lexicon: SupportedLexicon,
+  title: string,
+  body: string,
+  gh: GhRunner,
+): Promise<string> {
+  const marker = lexiconUpgradeIssueMarker(lexicon);
+  const repo = process.env.GITHUB_REPOSITORY;
+  if (repo) {
+    // `postOrUpdateGithubIssue` resolves the token itself and hands it back
+    // through `gh`'s second argument (#2320), so this runner has to forward
+    // what it is given rather than dropping it — see `GhRunner`.
+    return postOrUpdateGithubIssue(repo, marker, title, body, gh);
+  }
+  const { stdout } = await gh(
+    `gh issue create --title ${shellQuote(title)} --body ${shellQuote(`${marker}\n\n${body}`)}`,
+  );
+  return stdout.trim();
+}
 
 // ── PR idempotency helpers ────────────────────────────────────────────
 
@@ -384,6 +444,12 @@ async function getRealApplyBump(): Promise<ApplyBumpFn> {
  *   - Semver label: "minor" (additive) or "breaking" (changed/removed).
  *   - Validation failure falls back to issue mode.
  *
+ * In issue mode (#2297): one OPEN issue per lexicon, found by a hidden
+ * marker and edited in place on every re-run — the same sticky recipe
+ * reconcile.ts's `issue` mode uses, via the shared `postOrUpdateGithubIssue`.
+ * Never closed by this activity; see that function's doc comment for the
+ * close decision, which applies here unchanged.
+ *
  * Never auto-merges or auto-publishes.
  */
 export async function lexiconUpgrade(args: LexiconUpgradeArgs): Promise<LexiconUpgradeResult> {
@@ -493,16 +559,14 @@ export async function lexiconUpgrade(args: LexiconUpgradeArgs): Promise<LexiconU
     const effectiveMode: LexiconUpgradeMode = mode === "pull-request" ? "issue" : mode;
     if (effectiveMode === "issue") {
       const title = `chore(${lexicon}): spec upgrade validation failed`;
-      const { stdout } = await gh(
-        `gh issue create --title ${shellQuote(title)} --body ${shellQuote(summary)}`,
-      );
+      const issueUrl = await postLexiconIssue(lexicon, title, summary, gh);
       return {
         lexicon,
         mode,
         hasUpgrade: true,
         deltaText,
         semverLabel,
-        issueUrl: stdout.trim(),
+        issueUrl,
         summary,
         validationOk: false,
       };
@@ -543,16 +607,14 @@ export async function lexiconUpgrade(args: LexiconUpgradeArgs): Promise<LexiconU
   }
 
   if (effectiveMode === "issue") {
-    const { stdout } = await gh(
-      `gh issue create --title ${shellQuote(title)} --body ${shellQuote(summary)}`,
-    );
+    const issueUrl = await postLexiconIssue(lexicon, title, summary, gh);
     return {
       lexicon,
       mode: effectiveMode,
       hasUpgrade: true,
       deltaText,
       semverLabel,
-      issueUrl: stdout.trim(),
+      issueUrl,
       summary,
       validationOk: true,
     };

package/src/op/activities/lifecycle.ts

@@ -1,5 +1,6 @@
 import { exec } from "node:child_process";
 import { promisify } from "node:util";
+import { computePlanDigest } from "../../lifecycle/plan-digest";
 
 const execAsync = promisify(exec);
 
@@ -39,6 +40,40 @@ export interface LifecycleDiffResult {
    * `chant lifecycle diff --live`).
    */
   drifted: boolean;
+  /**
+   * This diff's identity (#2300) — the change set `chant lifecycle diff`
+   * reported, hashed. `ApplyOp` hands it to its gate step's `plan`, so an
+   * approval binds to the change set the approver read rather than to the
+   * next run of the Op.
+   *
+   * Computed over {@link normalizeDiffChangeSet}'s canonical form of
+   * `output`, so incidental whitespace does not read as a changed plan, while
+   * any added, removed or reworded row does.
+   */
+  planDigest: string;
+}
+
+/**
+ * The change set half of a `chant lifecycle diff` render, canonicalised for
+ * digesting (#2300).
+ *
+ * The diff render is line-oriented: section headers and the resource rows
+ * under them. Two runs over an unchanged environment print the same lines, so
+ * the lines are the change set. Normalising is deliberately minimal — CRLF to
+ * LF, trailing whitespace off each line, blank lines dropped — because
+ * anything more aggressive would start discarding rows, and a digest that
+ * discards rows is a digest that approves changes nobody saw.
+ *
+ * Unlike a terraform plan there is no timestamp to strip: the diff render
+ * carries none. If one is ever added it has to be dropped here, or every
+ * approval would be stale the moment it was written.
+ */
+export function normalizeDiffChangeSet(output: string): string[] {
+  return output
+    .replace(/\r\n/g, "\n")
+    .split("\n")
+    .map((line) => line.replace(/\s+$/, ""))
+    .filter((line) => line !== "");
 }
 
 /**
@@ -59,6 +94,20 @@ function detectDrift(output: string): boolean {
   return DRIFT_HEADERS.some((h) => output.includes(`${h} (`) || output.includes(`\n${h}`));
 }
 
+/**
+ * The identity of one `chant lifecycle diff` result (#2300). The environment
+ * and the `--live` flag are hashed alongside the change set because they say
+ * what the change set is *of*: the same rows against `staging` are not an
+ * approval to apply against `prod`.
+ */
+function lifecycleDiffDigest(args: LifecycleDiffArgs, output: string): string {
+  return computePlanDigest("lifecycle-diff", {
+    env: args.env,
+    live: args.live === true,
+    changeSet: normalizeDiffChangeSet(output),
+  });
+}
+
 /**
  * Run `chant lifecycle diff <env>` and return the output + structured drift
  * flag. Read-only; intended for use inside watch/observation Ops.
@@ -75,11 +124,11 @@ export async function lifecycleDiff(args: LifecycleDiffArgs, signal?: AbortSigna
     const { stdout, stderr } = await execAsync(`chant lifecycle diff ${args.env}${liveFlag}`, { signal });
     const output = `${stdout}${stderr}`.trim();
     if (output) console.log(output);
-    return { output, exitCode: 0, drifted: detectDrift(output) };
+    return { output, exitCode: 0, drifted: detectDrift(output), planDigest: lifecycleDiffDigest(args, output) };
   } catch (err) {
     const e = err as { code?: number; stdout?: string; stderr?: string };
     const output = `${e.stdout ?? ""}${e.stderr ?? ""}`.trim();
     if (output) console.error(output);
-    return { output, exitCode: e.code ?? 1, drifted: detectDrift(output) };
+    return { output, exitCode: e.code ?? 1, drifted: detectDrift(output), planDigest: lifecycleDiffDigest(args, output) };
   }
 }