chore(ci): move the engine version constant with the pins in vendor upgrades

sg-detect.cjs --write and vale-upgrade-detect.cjs --write now also rewrite
AST_GREP_VERSION / VALE_VERSION in packages/cli/src/rules/capabilities.ts,
via a new bumpVersionConstant in pin-bump.cjs that anchors on the exact
declaration line, fails unless it is found exactly once, and leaves every
other byte alone. Vale's constant takes the base version the binary
reports, not the stamped npm version.

engine-version-consistency.test.ts holds the constant to the pins, so a
bot commit that moved only the pins failed Validate by construction
(#368). The test stays; the bot commit becomes consistent.

Author: theCodeDrift

.github/scripts/pin-bump.cjs

@@ -76,4 +76,59 @@ function bumpPins(source, { pattern, from, to }) {
   return { source: bumped, count };
 }
 
-module.exports = { bumpPins, escapeLiteral };
+/**
+ * Move one `export const NAME = "…";` declaration to a new version, in the
+ * TypeScript source text of `packages/cli/src/rules/capabilities.ts`.
+ *
+ * WHY THIS IS PART OF THE BUMP. `capabilities.ts` publishes `AST_GREP_VERSION`
+ * and `VALE_VERSION` by hand, and `test/engine-version-consistency.test.ts`
+ * asserts they agree with the pins. That test is deliberate and the constant
+ * is deliberately NOT derived from package.json (its docblock says why), so a
+ * bot commit that moves the pins and not the constant fails Validate BY
+ * CONSTRUCTION. That is what happened on taskless/cli#368: the base of a stack
+ * was red before anyone had looked at it, and the child (#372) had to carry
+ * the constant along with the real work. The bot moves both now, so the
+ * consistency test is what it was meant to be — a check on humans, not a
+ * scheduled failure.
+ *
+ * WHY TEXT AGAIN. The same reason as `bumpPins`: the file is prettier-formatted
+ * and the diff a reviewer reads should be one string. The match is anchored on
+ * the whole declaration line, so a mention of the name in a docblock or a
+ * `{@link VALE_VERSION}` is not a candidate.
+ *
+ * WHY EXACTLY ONE. Zero means the declaration moved or was renamed and the
+ * workflow would otherwise push a commit the consistency test rejects — the
+ * failure this exists to remove. Two means the anchor is no longer specific,
+ * and rewriting both would be a guess. Either is a failed run.
+ *
+ * @param source  the capabilities.ts text
+ * @param name    the exported constant, e.g. `VALE_VERSION`
+ * @param to      the version to write. For Vale this is the BASE version the
+ *                binary reports (`3.22.0`), not the stamped npm version.
+ * @returns the rewritten source and the version the declaration held before
+ */
+function bumpVersionConstant(source, { name, to }) {
+  if (!/^[A-Z][A-Z0-9_]*$/.test(String(name))) {
+    throw new Error(
+      `the constant name must be an UPPER_SNAKE identifier, got ${JSON.stringify(name)}`
+    );
+  }
+  const matcher = new RegExp(
+    `^(export const ${name} = ")([^"\\n]*)(";)$`,
+    "gm"
+  );
+  const matches = [...source.matchAll(matcher)];
+  if (matches.length !== 1) {
+    throw new Error(
+      `expected exactly one \`export const ${name} = "…";\` declaration, found ${matches.length}`
+    );
+  }
+  const [match] = matches;
+  const [whole, head, from, tail] = match;
+  const at = match.index;
+  const bumped =
+    source.slice(0, at) + head + to + tail + source.slice(at + whole.length);
+  return { source: bumped, from };
+}
+
+module.exports = { bumpPins, bumpVersionConstant, escapeLiteral };

.github/scripts/pin-bump.test.cjs

@@ -14,7 +14,7 @@
 const test = require("node:test");
 const assert = require("node:assert/strict");
 
-const { bumpPins } = require("./pin-bump.cjs");
+const { bumpPins, bumpVersionConstant } = require("./pin-bump.cjs");
 
 /** The boundary-aware pattern sg-detect.cjs enumerates its pins with. */
 const AST_GREP = /^@ast-grep\/cli(-|$)/;
@@ -114,3 +114,86 @@ test("a stateful /g pattern is refused rather than silently skipping pins", () =
     /must not be \/g/
   );
 });
+
+/**
+ * The constant half of the bump. `capabilities.ts` declares `AST_GREP_VERSION`
+ * and `VALE_VERSION` by hand and `engine-version-consistency.test.ts` holds
+ * them to the pins, so a bot commit that moves only the pins is red before
+ * anyone reads it (taskless/cli#368). These pin the rewrite that closes that.
+ */
+const CAPABILITIES = [
+  "/**",
+  " * Pinned against the binary by `test/ast-grep-vendor-contract.test.ts`.",
+  " */",
+  'export const AST_GREP_VERSION = "0.45.3";',
+  "",
+  "/**",
+  " * The Vale release, measured against {@link VALE_VERSION}'s binary.",
+  ' * A literal stamp like "3.21.0-20260915061224" lives in package.json.',
+  " */",
+  'export const VALE_VERSION = "3.21.0";',
+  "",
+  'export const OTHER = "3.21.0";',
+  "",
+].join("\n");
+
+test("the named constant moves to the base version and reports what it held", () => {
+  const { source, from } = bumpVersionConstant(CAPABILITIES, {
+    name: "VALE_VERSION",
+    to: "3.22.0",
+  });
+  assert.equal(from, "3.21.0");
+  assert.match(source, /^export const VALE_VERSION = "3\.22\.0";$/m);
+  // Every other byte survives: the docblock's mention of the old version, the
+  // `{@link}`, and the unrelated constant at the same value.
+  assert.match(source, /"3\.21\.0-20260915061224"/);
+  assert.match(source, /\{@link VALE_VERSION\}/);
+  assert.match(source, /^export const OTHER = "3\.21\.0";$/m);
+  assert.match(source, /^export const AST_GREP_VERSION = "0\.45\.3";$/m);
+  assert.equal(source.split("\n").length, CAPABILITIES.split("\n").length);
+});
+
+test("the ast-grep constant is reached by the same anchor", () => {
+  const { source, from } = bumpVersionConstant(CAPABILITIES, {
+    name: "AST_GREP_VERSION",
+    to: "0.46.0",
+  });
+  assert.equal(from, "0.45.3");
+  assert.match(source, /^export const AST_GREP_VERSION = "0\.46\.0";$/m);
+  assert.match(source, /^export const VALE_VERSION = "3\.21\.0";$/m);
+});
+
+test("a constant already at the target is rewritten to itself", () => {
+  const { source, from } = bumpVersionConstant(CAPABILITIES, {
+    name: "VALE_VERSION",
+    to: "3.21.0",
+  });
+  assert.equal(from, "3.21.0");
+  assert.equal(source, CAPABILITIES);
+});
+
+test("a missing declaration fails the run rather than writing nothing", () => {
+  assert.throws(
+    () =>
+      bumpVersionConstant(CAPABILITIES, {
+        name: "RUFF_VERSION",
+        to: "1.0.0",
+      }),
+    /expected exactly one `export const RUFF_VERSION = "…";` declaration, found 0/
+  );
+});
+
+test("a declaration that appears twice is ambiguous and refused", () => {
+  const doubled = `${CAPABILITIES}export const VALE_VERSION = "3.20.0";\n`;
+  assert.throws(
+    () => bumpVersionConstant(doubled, { name: "VALE_VERSION", to: "3.22.0" }),
+    /found 2/
+  );
+});
+
+test("a name that is not an identifier cannot become a pattern", () => {
+  assert.throws(
+    () => bumpVersionConstant(CAPABILITIES, { name: ".*", to: "3.22.0" }),
+    /UPPER_SNAKE identifier/
+  );
+});

.github/scripts/sg-detect.cjs

@@ -41,8 +41,10 @@
  *            nothing. This is what update-badges.cjs calls.
  *
  *   --write  rewrite every `@ast-grep/cli*` pin in packages/cli/package.json to
- *            the upstream version. `ast-grep-upgrade.yml` then regenerates the
- *            lockfile and opens a pull request.
+ *            the upstream version, and `AST_GREP_VERSION` in
+ *            packages/cli/src/rules/capabilities.ts with it.
+ *            `ast-grep-upgrade.yml` then regenerates the lockfile and the rule
+ *            schema, checks the result, and opens a pull request.
  *
  *            THIS REVERSES AN EARLIER DECISION, deliberately. This script used
  *            to refuse to write on the grounds that a lockfile-touching bump
@@ -84,7 +86,7 @@
 const { appendFileSync, readFileSync, writeFileSync } = require("node:fs");
 const { join } = require("node:path");
 
-const { bumpPins } = require("./pin-bump.cjs");
+const { bumpPins, bumpVersionConstant } = require("./pin-bump.cjs");
 const {
   fetchReleaseByTag,
   formatReleaseNotes,
@@ -101,6 +103,25 @@ const PACKAGE_JSON_PATH = join(
   "package.json"
 );
 
+/**
+ * Where `AST_GREP_VERSION` is declared by hand. `--write` moves it with the
+ * pins, because `test/engine-version-consistency.test.ts` holds the two
+ * together and a bump that moved only the pins failed Validate before anyone
+ * had looked at it (taskless/cli#368, the Vale instance of the same shape).
+ */
+const CAPABILITIES_PATH = join(
+  __dirname,
+  "..",
+  "..",
+  "packages",
+  "cli",
+  "src",
+  "rules",
+  "capabilities.ts"
+);
+
+const VERSION_CONSTANT = "AST_GREP_VERSION";
+
 /** `@ast-grep/cli` itself and its per-platform siblings. */
 const PIN_PATTERN = /^@ast-grep\/cli(-|$)/;
 
@@ -242,6 +263,7 @@ async function main({
   releaseFor = fetchReleaseByTag,
   packageJsonPath = PACKAGE_JSON_PATH,
   packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8")),
+  capabilitiesPath = CAPABILITIES_PATH,
 } = {}) {
   const json = argv.includes("--json");
   const write = argv.includes("--write");
@@ -294,6 +316,19 @@ async function main({
     }
     writeFileSync(packageJsonPath, bumped);
     log(`Rewrote ${count} pins in ${packageJsonPath} to ${upstream}.`);
+
+    // Upstream's own packages, so the constant is the pin verbatim. Rewritten
+    // in the same run as the pins so the bot commit is self-consistent: a
+    // missing declaration throws here, before anything is pushed, rather than
+    // failing Validate later.
+    const { source: constants, from } = bumpVersionConstant(
+      readFileSync(capabilitiesPath, "utf8"),
+      { name: VERSION_CONSTANT, to: upstream }
+    );
+    writeFileSync(capabilitiesPath, constants);
+    log(
+      `Rewrote ${VERSION_CONSTANT} in ${capabilitiesPath}: ${from} -> ${upstream}.`
+    );
   }
 
   // Only the ahead path has a bump to describe. A second request, unlike Vale's

.github/scripts/sg-detect.test.cjs

@@ -26,6 +26,20 @@ const CLI_PACKAGE_JSON = JSON.parse(
   )
 );
 
+/**
+ * A capabilities.ts with the declaration `--write` rewrites, plus the kind of
+ * neighbour it must not touch: the Vale constant, and a docblock naming the
+ * old version.
+ */
+const CAPABILITIES_AT = (version) =>
+  [
+    "/** Measured at 0.45.2; see {@link AST_GREP_VERSION}. */",
+    `export const AST_GREP_VERSION = "${version}";`,
+    "",
+    'export const VALE_VERSION = "3.21.0";',
+    "",
+  ].join("\n");
+
 /** Run main() with the registry stubbed and $GITHUB_OUTPUT captured. */
 async function runDetect({
   upstream,
@@ -34,6 +48,7 @@ async function runDetect({
   argv = [],
   release,
   wantNotes = false,
+  capabilitiesSource = CAPABILITIES_AT("0.45.2"),
 }) {
   const directory = mkdtempSync(join(tmpdir(), "sg-detect-test-"));
   const outputPath = join(directory, "github-output");
@@ -44,6 +59,11 @@ async function runDetect({
   if (packageJsonSource !== undefined) {
     writeFileSync(packageJsonPath, packageJsonSource);
   }
+  // --write also rewrites AST_GREP_VERSION, so the fixture carries a
+  // capabilities.ts of its own for the same reason. The committed one is
+  // never written to here either.
+  const capabilitiesPath = join(directory, "capabilities.ts");
+  writeFileSync(capabilitiesPath, capabilitiesSource);
   const previous = process.env.GITHUB_OUTPUT;
   const releasesFetched = [];
   process.env.GITHUB_OUTPUT = outputPath;
@@ -57,6 +77,7 @@ async function runDetect({
       },
       packageJsonPath,
       packageJson,
+      capabilitiesPath,
     });
     const outputs = Object.fromEntries(
       readFileSync(outputPath, "utf8")
@@ -81,12 +102,14 @@ async function runDetect({
       packageJsonSource === undefined
         ? undefined
         : readFileSync(packageJsonPath, "utf8");
+    const capabilitiesWritten = readFileSync(capabilitiesPath, "utf8");
     return {
       comparison,
       outputs,
       notesWritten,
       releasesFetched,
       packageJsonWritten,
+      capabilitiesWritten,
     };
   } finally {
     if (previous === undefined) {
@@ -289,7 +312,7 @@ const sourcePinnedAt = (version) =>
   )}\n`;
 
 test("sg-detect: --write bumps every pin in the file on disk", async () => {
-  const { packageJsonWritten, outputs } = await runDetect({
+  const { packageJsonWritten, capabilitiesWritten, outputs } = await runDetect({
     upstream: "0.45.3",
     packageJson: pinnedAt("0.45.2"),
     packageJsonSource: sourcePinnedAt("0.45.2"),
@@ -299,18 +322,42 @@ test("sg-detect: --write bumps every pin in the file on disk", async () => {
   assert.equal(outputs.update, "true");
   assert.doesNotMatch(packageJsonWritten, /0\.45\.2/);
   assert.equal(packageJsonWritten.match(/0\.45\.3/g).length, 3);
+  // The constant moves with the pins, and nothing around it does. This is
+  // what keeps the bot commit green under engine-version-consistency.test.ts.
+  assert.equal(capabilitiesWritten, CAPABILITIES_AT("0.45.3"));
+  assert.match(capabilitiesWritten, /Measured at 0\.45\.2/);
+  assert.match(capabilitiesWritten, /VALE_VERSION = "3\.21\.0"/);
 });
 
-test("sg-detect: --write leaves the file alone when the pin is current", async () => {
+test("sg-detect: --write leaves the files alone when the pin is current", async () => {
   const before = sourcePinnedAt("0.45.2");
-  const { packageJsonWritten } = await runDetect({
+  const { packageJsonWritten, capabilitiesWritten } = await runDetect({
     upstream: "0.45.2",
     packageJson: pinnedAt("0.45.2"),
     packageJsonSource: before,
     argv: ["--write"],
   });
 
   assert.equal(packageJsonWritten, before);
+  assert.equal(capabilitiesWritten, CAPABILITIES_AT("0.45.2"));
+});
+
+/**
+ * The declaration the workflow depends on has moved or been renamed. Failing
+ * here is the point: pushing the pins without the constant is exactly the
+ * red-by-construction pull request this rewrite exists to end.
+ */
+test("sg-detect: --write fails when AST_GREP_VERSION is not declared once", async () => {
+  await assert.rejects(
+    runDetect({
+      upstream: "0.45.3",
+      packageJson: pinnedAt("0.45.2"),
+      packageJsonSource: sourcePinnedAt("0.45.2"),
+      argv: ["--write"],
+      capabilitiesSource: 'export const VALE_VERSION = "3.21.0";\n',
+    }),
+    /expected exactly one `export const AST_GREP_VERSION = "…";` declaration, found 0/
+  );
 });
 
 /**