@intentius/chant 0.101.0 → 0.102.0

package/src/op/activities/apply.ts

@@ -21,6 +21,14 @@
  * per-resource `gcpApply` and the fly lexicon's `flyApply`, which never had a
  * CLI in the path to begin with: gcp maps each CNRM kind to its REST API
  * itself, and fly speaks the Machines API (flaps) directly, no flyctl.
+ * `grafana` joined later (#3011): the grafana lexicon's `grafanaApply`, which
+ * writes folders, library panels and dashboards over Grafana's HTTP API.
+ * `clickhouse` joined after it (#3208): the sql lexicon's `clickhouseApply`,
+ * which sends a ClickHouse server the CREATE and ALTER statements a build's
+ * classified changes need, over its HTTP interface. `postgres` joined after
+ * that (#3280): the sql lexicon's `postgresApply`, which sends a Postgres
+ * server the statements a build's classified changes need, grouped into
+ * transactions, with `CONCURRENTLY` statements outside them.
  * **The dispatcher stayed here**, because "which
  * mechanism applies this target" is not any one product's knowledge — and
  * because the activity keeps its name, its arguments and its place in
@@ -40,7 +48,7 @@ import { importLexiconPackage } from "../../lexicon-module";
 const execAsync = promisify(exec);
 
 /** The native apply mechanism for a target. */
-export type ApplyTarget = "cloudformation" | "kubectl" | "arm" | "kustomize" | "gcp" | "fly";
+export type ApplyTarget = "cloudformation" | "kubectl" | "arm" | "kustomize" | "gcp" | "fly" | "grafana" | "clickhouse" | "postgres";
 
 /**
  * How apply treats resources no longer declared.
@@ -52,7 +60,16 @@ export type ApplyTarget = "cloudformation" | "kubectl" | "arm" | "kustomize" | "
  *   ownership label (via the gcp lexicon's `gcpApply` — only kinds it can
  *   list; the rest are reported not-prunable), `fly` prunes machines by the
  *   metadata marker and the metadata-less types (volumes/ips/certs/secrets)
- *   app-scoped under a managed app (via the fly lexicon's `flyApply`), and
+ *   app-scoped under a managed app (via the fly lexicon's `flyApply`),
+ *   `grafana` prunes dashboards and folders by the ownership labels (via the
+ *   grafana lexicon's `grafanaApply`; library panels, Grafana 11 and a project
+ *   with no ownership stack are reported not-prunable), `clickhouse` drops
+ *   tables, views and databases whose comment carries the project's marker
+ *   (via the sql lexicon's `clickhouseApply`; a project with no ownership
+ *   stack is reported not-prunable), `postgres` drops the objects in the
+ *   declared schemas whose comment carries the project's marker (via the sql
+ *   lexicon's `postgresApply`; never an object another tool keeps, and a
+ *   project with no ownership stack is reported not-prunable), and
  *   `cloudformation` is bounded by the stack — which holds, because a
  *   resource CFN did not create is not in the stack.
  * - `gated` — same delete scope as `owned-only`, but an approval gate precedes
@@ -66,7 +83,11 @@ export interface NativeApplyArgs {
   target: ApplyTarget;
   /** Environment. What it means is per target: the CFN stack name on
    * `cloudformation`, the ARM resource group on `arm`, the chant environment
-   * on `kubectl`/`kustomize`. On `gcp` and `fly` it is a log label only — the
+   * on `kubectl`/`kustomize`, and on `grafana` the chant environment whose
+   * `grafana.profiles.<env>` names the Grafana to write to, and on
+   * `clickhouse` and `postgres` the chant environment whose
+   * `sql.profiles.<env>` names the server. On `gcp` and
+   * `fly` it is a log label only — the
    * gcp applier resolves the project (`GOOGLE_CLOUD_PROJECT` env / CNRM
    * annotation) and endpoint (`GCP_ENDPOINT_URL` env) itself, and the fly
    * applier resolves its endpoint (`FLY_FLAPS_BASE_URL` env) and token
@@ -74,7 +95,9 @@ export interface NativeApplyArgs {
   env: string;
   /** Built manifest/template path. Default per target ({@link defaultOutput}):
    * `dist` (a dir) for kubectl, `template.json` (a file) for
-   * CloudFormation/ARM, `dist/gcp.yaml` for gcp, `dist/fly.json` for fly. */
+   * CloudFormation/ARM, `dist/gcp.yaml` for gcp, `dist/fly.json` for fly,
+   * `dist/grafana.json` (the build index) for grafana, `dist/schema.json`
+   * (the sql lexicon's build output) for clickhouse and postgres. */
   output?: string;
   /** Delete handling. Default: never. */
   deleteMode?: DeleteMode;
@@ -182,6 +205,57 @@ export type FlyApplier = (
   signal?: AbortSignal,
 ) => Promise<ApplyResult>;
 
+/**
+ * The grafana lexicon's API applier, as this module needs to call it (#3011):
+ * `grafanaApply` composed with the lexicon's own `toApplyResult` projection,
+ * so what crosses this seam is core's versioned apply envelope (#1446).
+ *
+ * `environment` selects `grafana.profiles.<environment>` (else `GRAFANA_URL`
+ * with `GRAFANA_TOKEN`), the binding observe and export use. The ownership
+ * marker is not passed: `grafanaApply` reads `ownership` from the project's
+ * `chant.config.ts` itself, and a prune without a stack declines as
+ * not-prunable rather than delete another project's dashboards.
+ */
+export type GrafanaApplier = (
+  args: {
+    indexPath: string;
+    environment?: string;
+    prune?: boolean;
+  },
+  signal?: AbortSignal,
+) => Promise<ApplyResult>;
+
+/**
+ * The sql lexicon's ClickHouse applier, as this module needs to call it
+ * (#3208): `clickhouseApply` composed with the lexicon's own `toApplyResult`
+ * projection, so what crosses this seam is core's versioned apply envelope
+ * (#1446). A rebuild-class change rides it as NOT-ATTEMPTED.
+ *
+ * `environment` selects `sql.profiles.<environment>` (else `CLICKHOUSE_URL`),
+ * the binding observe and import use. The ownership marker is not passed:
+ * `clickhouseApply` reads `ownership` from the project's `chant.config.ts`.
+ */
+export type ClickHouseApplier = (
+  args: {
+    buildPath: string;
+    environment?: string;
+    prune?: boolean;
+  },
+  signal?: AbortSignal,
+) => Promise<ApplyResult>;
+
+/**
+ * The sql lexicon's Postgres applier, as this module needs to call it
+ * (#3280): `postgresApply` composed with the lexicon's own `toApplyResult`,
+ * the same seam as {@link ClickHouseApplier}. An expand-and-contract change
+ * and a rolled-back transaction's objects ride it as NOT-ATTEMPTED.
+ *
+ * `environment` selects `sql.profiles.<environment>` (else `POSTGRES_URL`).
+ * The ownership marker and the timeouts are not passed: `postgresApply`
+ * reads `ownership` and the profile from the project's `chant.config.ts`.
+ */
+export type PostgresApplier = ClickHouseApplier;
+
 /**
  * The aws lexicon's CloudFormation applier, as this module needs to call it
  * (#1449). Structural, like {@link K8sApplier} and {@link AzureApplier}.
@@ -363,6 +437,102 @@ async function loadFlyApplier(): Promise<FlyApplier> {
   return async (args, signal) => toApplyResult(await flyApply(args, signal));
 }
 
+/**
+ * Load the grafana lexicon's `grafanaApply` (#3011). Same variable-specifier
+ * trick as {@link loadK8sApplier}, for the same reason. The activities subpath,
+ * not the package root or `op/builders`: those hold the typed step builder,
+ * while the activity itself (and its `toApplyResult`) lives here.
+ */
+async function loadGrafanaApplier(): Promise<GrafanaApplier> {
+  const spec = "@intentius/chant-lexicon-grafana/op/activities";
+  type GrafanaModule = {
+    grafanaApply?: (args: Parameters<GrafanaApplier>[0], signal?: AbortSignal) => Promise<unknown>;
+    toApplyResult?: (result: unknown) => ApplyResult;
+  };
+  let mod: GrafanaModule;
+  try {
+    mod = (await importLexiconPackage(spec)) as GrafanaModule;
+  } catch (err) {
+    throw new Error(
+      `apply target "grafana" needs @intentius/chant-lexicon-grafana, which could not be loaded ` +
+        `(${err instanceof Error ? err.message : String(err)}). Grafana applies go through the grafana ` +
+        `lexicon's API applier (chant #2948); install the grafana lexicon and list it in chant.config.ts.`,
+    );
+  }
+  const { grafanaApply, toApplyResult } = mod;
+  if (typeof grafanaApply !== "function") {
+    throw new Error(
+      "the installed @intentius/chant-lexicon-grafana exports no grafanaApply — it predates chant #2948",
+    );
+  }
+  if (typeof toApplyResult !== "function") {
+    throw new Error(
+      "the installed @intentius/chant-lexicon-grafana exports no toApplyResult — it predates chant #2948",
+    );
+  }
+  return async (args, signal) => toApplyResult(await grafanaApply(args, signal));
+}
+
+/**
+ * Load the sql lexicon's `clickhouseApply` (#3208). Same variable-specifier
+ * trick as {@link loadK8sApplier}, for the same reason.
+ */
+async function loadClickHouseApplier(): Promise<ClickHouseApplier> {
+  const spec = "@intentius/chant-lexicon-sql/op/activities";
+  type SqlModule = {
+    clickhouseApply?: (args: Parameters<ClickHouseApplier>[0], signal?: AbortSignal) => Promise<unknown>;
+    toApplyResult?: (result: unknown) => ApplyResult;
+  };
+  let mod: SqlModule;
+  try {
+    mod = (await importLexiconPackage(spec)) as SqlModule;
+  } catch (err) {
+    throw new Error(
+      `apply target "clickhouse" needs @intentius/chant-lexicon-sql, which could not be loaded ` +
+        `(${err instanceof Error ? err.message : String(err)}). ClickHouse applies go through the sql ` +
+        `lexicon's applier (chant #3208); install the sql lexicon and list it in chant.config.ts.`,
+    );
+  }
+  const { clickhouseApply, toApplyResult } = mod;
+  if (typeof clickhouseApply !== "function") {
+    throw new Error("the installed @intentius/chant-lexicon-sql exports no clickhouseApply — it predates chant #3208");
+  }
+  if (typeof toApplyResult !== "function") {
+    throw new Error("the installed @intentius/chant-lexicon-sql exports no toApplyResult — it predates chant #3208");
+  }
+  return async (args, signal) => toApplyResult(await clickhouseApply(args, signal));
+}
+
+/**
+ * Load the sql lexicon's `postgresApply` (#3280). Same variable-specifier
+ * trick as {@link loadK8sApplier}, for the same reason.
+ */
+async function loadPostgresApplier(): Promise<PostgresApplier> {
+  const spec = "@intentius/chant-lexicon-sql/op/activities";
+  type SqlModule = {
+    postgresApply?: (args: Parameters<PostgresApplier>[0], signal?: AbortSignal) => Promise<unknown>;
+    toApplyResult?: (result: unknown) => ApplyResult;
+  };
+  let mod: SqlModule;
+  try {
+    mod = (await importLexiconPackage(spec)) as SqlModule;
+  } catch (err) {
+    throw new Error(
+      `apply target "postgres" needs @intentius/chant-lexicon-sql, which could not be loaded ` +
+        `(${err instanceof Error ? err.message : String(err)}). Postgres applies go through the sql ` +
+        `lexicon's applier (chant #3280); install the sql lexicon and list it in chant.config.ts.`,
+    );
+  }
+  const { postgresApply, toApplyResult } = mod;
+  if (typeof postgresApply !== "function") {
+    throw new Error("the installed @intentius/chant-lexicon-sql exports no postgresApply — it predates chant #3280");
+  }
+  if (typeof toApplyResult !== "function") {
+    throw new Error("the installed @intentius/chant-lexicon-sql exports no toApplyResult — it predates chant #3208");
+  }
+  return async (args, signal) => toApplyResult(await postgresApply(args, signal));
+}
+
 /**
  * Load the aws lexicon's `awsApply` (#1449). Same variable-specifier trick as
  * {@link loadK8sApplier}, for the same reason.
@@ -418,8 +588,11 @@ async function loadAwsRollback(): Promise<AwsRollback> {
  * manifests), so `dist`; kustomize's "output" is the kustomization DIRECTORY
  * the render reads. The file targets take the file their lexicon's build
  * conventionally emits: `template.json` for CloudFormation/ARM, `dist/gcp.yaml`
- * (the CNRM manifest) for gcp, `dist/fly.json` (the serialized plan) for fly.
- * Pure — exported for testing.
+ * (the CNRM manifest) for gcp, `dist/fly.json` (the serialized plan) for fly,
+ * `dist/grafana.json` (the index the grafana serializer writes, with the
+ * dashboard files beside it) for grafana, `dist/schema.json` (the sql
+ * lexicon's build output) for clickhouse and postgres. Pure — exported for
+ * testing.
  */
 export function defaultOutput(target: ApplyTarget): string {
   switch (target) {
@@ -430,6 +603,11 @@ export function defaultOutput(target: ApplyTarget): string {
       return "dist/gcp.yaml";
     case "fly":
       return "dist/fly.json";
+    case "grafana":
+      return "dist/grafana.json";
+    case "clickhouse":
+    case "postgres":
+      return "dist/schema.json";
     default:
       return "template.json";
   }
@@ -469,7 +647,9 @@ function collapseEnvelope(envelope: ApplyResult, label: string): NativeApplyResu
  * Apply declared source to the cloud via the target's native mechanism.
  * Deletes (when enabled) ride that mechanism's own delete path — marker-scoped
  * on `kubectl`, tag-scoped on `arm`, label-scoped on `gcp`, marker- and
- * app-scoped on `fly`, and stack-scoped on `cloudformation`, where the deploy
+ * app-scoped on `fly`, label-scoped on `grafana`, comment-marker-scoped on
+ * `clickhouse` and `postgres`, and stack-scoped on
+ * `cloudformation`, where the deploy
  * itself removes resources dropped from the template and `deleteMode` changes
  * nothing: a resource CFN did not create is not in the stack. See
  * {@link DeleteMode}.
@@ -477,7 +657,7 @@ function collapseEnvelope(envelope: ApplyResult, label: string): NativeApplyResu
  * The appliers are injectable so this dispatcher can be tested without the
  * product lexicons present; production resolves them through
  * {@link loadK8sApplier} / {@link loadAzureApplier} / {@link loadAwsApplier} /
- * {@link loadGcpApplier} / {@link loadFlyApplier}.
+ * {@link loadGcpApplier} / {@link loadFlyApplier} / {@link loadGrafanaApplier}.
  */
 export async function nativeApply(
   args: NativeApplyArgs,
@@ -488,6 +668,9 @@ export async function nativeApply(
   awsApplier?: AwsApplier,
   gcpApplier?: GcpApplier,
   flyApplier?: FlyApplier,
+  grafanaApplier?: GrafanaApplier,
+  clickhouseApplier?: ClickHouseApplier,
+  postgresApplier?: PostgresApplier,
 ): Promise<NativeApplyResult> {
   const output = args.output ?? defaultOutput(args.target);
   const deleteMode = args.deleteMode ?? "never";
@@ -568,6 +751,45 @@ export async function nativeApply(
     return collapseEnvelope(envelope, args.env);
   }
 
+  if (args.target === "grafana") {
+    // grafana (#3011): the grafana lexicon's API applier. Unlike gcp and fly,
+    // env is not just a label here: it selects `grafana.profiles.<env>`, the
+    // Grafana observe and export already read. The ownership marker comes from
+    // the project's chant.config.ts inside grafanaApply.
+    const apply = grafanaApplier ?? (await loadGrafanaApplier());
+    const envelope = await apply(
+      { indexPath: output, environment: args.env, prune: deleteMode !== "never" },
+      signal,
+    );
+    // No binding or a refused token rides the envelope as NOT-ATTEMPTED for
+    // every resource, as do library panels and anything else prune could
+    // not consider.
+    return collapseEnvelope(envelope, args.env);
+  }
+
+  if (args.target === "clickhouse") {
+    // clickhouse (#3208): the sql lexicon's applier. env selects
+    // `sql.profiles.<env>`, the server observe and import read; the marker
+    // comes from the project's chant.config.ts inside clickhouseApply.
+    const apply = clickhouseApplier ?? (await loadClickHouseApplier());
+    const envelope = await apply({ buildPath: output, environment: args.env, prune: deleteMode !== "never" }, signal);
+    // A refused rebuild and a column drop an additive apply withholds ride the
+    // envelope as NOT-ATTEMPTED, so an Op can gate on them.
+    return collapseEnvelope(envelope, args.env);
+  }
+
+  if (args.target === "postgres") {
+    // postgres (#3280): the sql lexicon's applier. env selects
+    // `sql.profiles.<env>`; the marker and the lock and statement timeouts
+    // come from the project's chant.config.ts inside postgresApply.
+    const apply = postgresApplier ?? (await loadPostgresApplier());
+    const envelope = await apply({ buildPath: output, environment: args.env, prune: deleteMode !== "never" }, signal);
+    // A refused expand-and-contract change, a column drop an additive apply
+    // withholds, and the objects of a rolled-back transaction ride the
+    // envelope as NOT-ATTEMPTED, so an Op can gate on them.
+    return collapseEnvelope(envelope, args.env);
+  }
+
   // cloudformation (#1449): the aws lexicon's native applier. env is the stack
   // name and output the template path; endpoint resolution (#1694) and
   // capability derivation (#980) are awsApply's own, so nothing else is passed.

package/src/op/activities/index.ts

@@ -70,6 +70,9 @@ export type {
   AzureApplier,
   GcpApplier,
   FlyApplier,
+  GrafanaApplier,
+  ClickHouseApplier,
+  PostgresApplier,
   AwsApplier,
   AwsRollback,
 } from "./apply";

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

@@ -18,23 +18,37 @@ import type { UpgradeCheckResult } from "../../codegen/pinned-upgrade";
 import type { RollingUpgradeResult } from "../../codegen/rolling-upgrade";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { writeFileSync, readFileSync } from "node:fs";
+import { writeFileSync, readFileSync, mkdirSync } from "node:fs";
 
 // ── Classification ────────────────────────────────────────────────────
 
 describe("pinned vs rolling classification", () => {
-  test("pinned lexicons", () => {
-    for (const l of ["k8s", "gcp", "docker", "gitlab"] as const) {
-      expect(isPinned(l)).toBe(true);
+  const pin = {
+    file: "src/pin.ts",
+    pattern: /V = "(.+)"/,
+    replace: (v: string) => `V = "${v}"`,
+    upstream: { owner: "o", repo: "r", kind: "releases" as const },
+  };
+
+  test("pinned lexicons are any whose plugin declares upstreamPin", async () => {
+    const loadPin = vi.fn(async () => pin);
+    for (const l of ["k8s", "gcp", "docker", "gitlab", "sql", "k3s", "cedar"]) {
+      expect(await isPinned(l, "/x", loadPin)).toBe(true);
       expect(isRolling(l)).toBe(false);
     }
   });
 
-  test("rolling lexicons", () => {
+  test("a lexicon without a pin is not pinned", async () => {
+    expect(await isPinned("helm", "/x", async () => null)).toBe(false);
+  });
+
+  test("rolling lexicons", async () => {
+    const loadPin = vi.fn(async () => null);
     for (const l of ["aws", "azure", "github"] as const) {
       expect(isRolling(l)).toBe(true);
-      expect(isPinned(l)).toBe(false);
+      expect(await isPinned(l, "/x", loadPin)).toBe(false);
     }
+    expect(loadPin).not.toHaveBeenCalled();
   });
 });
 
@@ -389,6 +403,86 @@ describe("lexiconUpgrade breakage handling", () => {
 
 // ── out-of-scope rejection ────────────────────────────────────────────
 
+describe("discovered pinned lexicons (#3266)", () => {
+  const pin = {
+    file: "src/pin.ts",
+    pattern: /V = "(.+)"/,
+    replace: (v: string) => `V = "${v}"`,
+    upstream: { owner: "o", repo: "r", kind: "releases" as const },
+  };
+
+  test("a lexicon with a declared pin reaches the pinned check and opens a PR", async () => {
+    const checkPinned: CheckPinnedFn = vi.fn(async () => pinnedResult());
+    const applyBump = vi.fn(async () => ({ filePath: "/x/src/pin.ts" }));
+    const { gh } = recordingGh();
+    const dir = join(tmpdir(), `chant-3266-${process.pid}`);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "package.json"), JSON.stringify({ version: "0.1.0" }));
+    const r = await lexiconUpgrade({
+      lexicon: "k3s",
+      lexiconDir: dir,
+      mode: "pull-request",
+      _loadPin: async () => pin,
+      _checkPinned: checkPinned,
+      _applyBump: applyBump,
+      _bumpPackageVersion: vi.fn(),
+      _gh: gh,
+    });
+    expect(checkPinned).toHaveBeenCalledOnce();
+    expect(applyBump).toHaveBeenCalledWith("k3s", dir, "v1.33.0");
+    expect(r.hasUpgrade).toBe(true);
+  });
+
+  test("a lexicon with no pin and not rolling is rejected", async () => {
+    await expect(
+      lexiconUpgrade({ lexicon: "helm", mode: "report", _loadPin: async () => null }),
+    ).rejects.toThrow(/not supported/);
+  });
+
+  test("a discovered pin reaches the real check when none is injected", async () => {
+    const loadPin = vi.fn(async () => pin);
+    // The real checkPinnedUpgrade loads the pin itself; an empty dir has no
+    // plugin, so it reports the fetch error rather than throwing "not supported".
+    const r = await lexiconUpgrade({
+      lexicon: "sql",
+      lexiconDir: join(tmpdir(), "chant-3266-none"),
+      mode: "report",
+      _loadPin: loadPin,
+    });
+    expect(loadPin).toHaveBeenCalledOnce();
+    expect(r.validationOk).toBe(false);
+  });
+
+  test("an alsoMoves pin is report-only: newer version and manual step, no bump, no git", async () => {
+    const manual = pinnedResult({
+      validation: null,
+      from: "25.8.1.1-lts",
+      to: "26.3.1.1-lts",
+      manualPin: { file: "src/spec/pin.ts", instructions: "move CLICKHOUSE_IMAGE_DIGEST too" },
+    });
+    const applyBump = vi.fn();
+    const { gh, calls } = recordingGh();
+    for (const mode of ["report", "issue", "pull-request"] as const) {
+      const r = await lexiconUpgrade({
+        lexicon: "sql",
+        mode,
+        _checkPinned: vi.fn(async () => manual),
+        _applyBump: applyBump,
+        _gh: gh,
+      });
+      expect(r.hasUpgrade).toBe(true);
+      expect(r.mode).toBe("report");
+      expect(r.prUrl).toBeUndefined();
+      expect(r.issueUrl).toBeUndefined();
+      expect(r.summary).toContain("26.3.1.1-lts");
+      expect(r.summary).toContain("move CLICKHOUSE_IMAGE_DIGEST too");
+      expect(r.summary).toContain("src/spec/pin.ts");
+    }
+    expect(applyBump).not.toHaveBeenCalled();
+    expect(calls).toHaveLength(0);
+  });
+});
+
 describe("out-of-scope lexicons", () => {
   test("helm/forgejo throw", async () => {
     for (const l of ["helm", "forgejo"]) {
@@ -585,3 +679,63 @@ describe("lexiconUpgrade pull-request mode: package.json version bump", () => {
     }
   });
 });
+
+describe("a lexicon with several pins (#3288)", () => {
+  const manual = (pin: string, from: string, to: string): UpgradeCheckResult =>
+    pinnedResult({ pin, validation: null, from, to, manualPin: { file: "src/spec/postgres-pin.ts", instructions: `move the ${pin} digest too` } });
+  const current = (pin: string, v: string): UpgradeCheckResult => pinnedResult({ pin, validation: null, hasUpgrade: false, from: v, to: v });
+
+  test("every pin is reported; manual pins stay report-only in every mode", async () => {
+    const results = [current("clickhouse", "26.8.15.10"), manual("postgres-17", "17.11", "17.12"), manual("postgres-14", "14.24", "14.25")];
+    const applyBump = vi.fn();
+    const { gh, calls } = recordingGh();
+    for (const mode of ["report", "issue", "pull-request"] as const) {
+      const r = await lexiconUpgrade({ lexicon: "sql", mode, _checkPinned: vi.fn(async () => results), _applyBump: applyBump, _gh: gh });
+      expect(r.hasUpgrade).toBe(true);
+      expect(r.mode).toBe("report");
+      expect(r.summary).toContain("## Lexicon upgrade: sql (clickhouse)");
+      expect(r.summary).toContain("## Lexicon upgrade: sql (postgres-17)");
+      expect(r.summary).toContain("move the postgres-17 digest too");
+      expect(r.summary).toContain("move the postgres-14 digest too");
+    }
+    expect(applyBump).not.toHaveBeenCalled();
+    expect(calls).toHaveLength(0);
+  });
+
+  test("no pin has an upgrade: nothing to do", async () => {
+    const r = await lexiconUpgrade({
+      lexicon: "sql",
+      _checkPinned: vi.fn(async () => [current("clickhouse", "1.0"), current("postgres-18", "18.6")]),
+    });
+    expect(r.hasUpgrade).toBe(false);
+    expect(r.validationOk).toBe(true);
+  });
+
+  test("the pin label is forwarded to the check", async () => {
+    const check = vi.fn(async () => [current("postgres-16", "16.15")]);
+    await lexiconUpgrade({ lexicon: "sql", pin: "postgres-16", _checkPinned: check });
+    expect(check).toHaveBeenCalledWith(expect.objectContaining({ lexicon: "sql", pin: "postgres-16" }));
+  });
+
+  test("a rewritable pin leads: the PR branch, title and bump name the pin", async () => {
+    const results = [manual("clickhouse", "1.0", "2.0"), pinnedResult({ pin: "postgres-17", from: "17.11", to: "17.12" })];
+    const applyBump = vi.fn(async () => ({ filePath: "/x/pin.ts" }));
+    const { gh, calls } = recordingGh();
+    const dir = join(tmpdir(), `chant-3288-${process.pid}`);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "package.json"), JSON.stringify({ version: "0.1.0" }));
+    await lexiconUpgrade({
+      lexicon: "sql",
+      mode: "pull-request",
+      lexiconDir: dir,
+      _checkPinned: vi.fn(async () => results),
+      _applyBump: applyBump,
+      _bumpPackageVersion: vi.fn(() => "/x/package.json"),
+      _gh: gh,
+    });
+    expect(applyBump).toHaveBeenCalledWith("sql", dir, "17.12", "postgres-17");
+    expect(calls.some((c) => c.includes("lexicon-upgrade/sql-postgres-17"))).toBe(true);
+    expect(upgradeBranchName("sql", "postgres-17")).toBe("lexicon-upgrade/sql-postgres-17");
+    expect(upgradePrTitle("sql", "17.11", "17.12", "postgres-17")).toBe("feat(sql): upgrade postgres-17 17.11 to 17.12");
+  });
+});