fix(release): synchronize SDK install docs

tools/release/sync-release-pr.mjs

@@ -66,6 +66,36 @@ const EXTENSION_EVIDENCE_SUMMARY_PATH = path.join(
   "src/extensions/generated/docs/extension-evidence.json",
 );
 const EXTENSION_MODEL_CHECK_PATH = "src/extensions/tools/check-extension-model.mjs";
+export const SDK_INSTALL_VERSION_RULES = Object.freeze([
+  {
+    product: "oliphaunt-swift",
+    file: "src/docs/content/sdk/swift/index.mdx",
+    prefix: '.package(url: "https://github.com/f0rr0/oliphaunt.git", from: "',
+    suffix: '")',
+  },
+  {
+    product: "oliphaunt-swift",
+    file: "src/docs/content/sdk/swift/guide.mdx",
+    prefix: '.package(url: "https://github.com/f0rr0/oliphaunt.git", from: "',
+    suffix: '")',
+  },
+  {
+    product: "oliphaunt-swift",
+    file: "src/sdks/swift/README.md",
+    prefix: '.package(url: "https://github.com/f0rr0/oliphaunt.git", exact: "',
+    suffix: '")',
+  },
+  ...[
+    "src/docs/content/sdk/kotlin/index.mdx",
+    "src/docs/content/sdk/kotlin/guide.mdx",
+    "src/sdks/kotlin/README.md",
+  ].map((file) => ({
+    product: "oliphaunt-kotlin",
+    file,
+    prefix: 'implementation("dev.oliphaunt:oliphaunt-android:',
+    suffix: '")',
+  })),
+]);
 
 function fail(message) {
   console.error(`${PREFIX}: ${message}`);
@@ -459,6 +489,32 @@ function syncElectronExampleDependencies(changes, { write }) {
   }
 }
 
+export function syncSdkInstallDocs(changes, { root = ROOT, write, transitions }) {
+  const transitionsByProduct = new Map(transitions.map((transition) => [transition.product, transition]));
+  for (const rule of SDK_INSTALL_VERSION_RULES) {
+    const transition = transitionsByProduct.get(rule.product);
+    if (transition === undefined) continue;
+    if (transition.before === null) fail(`${rule.product} install docs require a prior release version`);
+    const file = path.join(root, rule.file);
+    const before = `${rule.prefix}${transition.before}${rule.suffix}`;
+    const after = `${rule.prefix}${transition.after}${rule.suffix}`;
+    const text = readText(file);
+    const beforeCount = text.split(before).length - 1;
+    const afterCount = text.split(after).length - 1;
+    if (beforeCount === 0 && afterCount === 1) continue;
+    if (beforeCount !== 1 || afterCount !== 0) {
+      fail(`${rule.file} must contain exactly one ${rule.product} install contract for ${transition.before}`);
+    }
+    writeTextIfChanged(
+      file,
+      text.replace(before, after),
+      changes,
+      `${rule.product} install contract ${transition.before} -> ${transition.after}`,
+      { write },
+    );
+  }
+}
+
 async function syncPnpmTypescriptOptionalRuntimeSpecifiers(changes, { write }) {
   const expectedVersions = {
     ...typescriptOptionalRuntimeVersionsFromPackage(),
@@ -1107,6 +1163,7 @@ async function main(argv) {
   syncExtensionRegistryMetadata(changes, { write });
   await syncNativeToolsOptionalDependencies(changes, { write, transitions });
   syncElectronExampleDependencies(changes, { write });
+  syncSdkInstallDocs(changes, { write, transitions });
   await syncPnpmTypescriptOptionalRuntimeSpecifiers(changes, { write });
   syncCargoPathDependencyPins(changes, { write, transitions });
   syncExampleCargoRegistryPins(changes, { write });
@@ -1157,6 +1214,7 @@ export function releaseDerivedPathInventory() {
     EXTENSION_EVIDENCE_SUMMARY_PATH,
     NATIVE_TOOLS_FACADE_PACKAGE,
     WASIX_TOOLS_FACADE_PACKAGE,
+    ...SDK_INSTALL_VERSION_RULES.map(({ file }) => path.join(ROOT, file)),
     ...compatibilityVersionLinks().map(({ path: pathText }) => path.join(ROOT, pathText)),
     ...exactExtensionReleaseProducts(PREFIX).map((product) => path.join(ROOT, packagePath(product), "release.toml")),
     path.join(ROOT, "src/sdks/js/package.json"),

tools/release/sync-release-pr.test.mjs

@@ -10,7 +10,9 @@ import {
   cargoManifestPaths,
   extensionEvidenceSummaryCommand,
   releaseDerivedPathInventory,
+  SDK_INSTALL_VERSION_RULES,
   sharedContribBootstrapRequired,
+  syncSdkInstallDocs,
   syncExampleCargoManifestText,
   syncLockfile,
 } from "./sync-release-pr.mjs";
@@ -35,6 +37,35 @@ test("release metadata accepts source and normalized local Cargo pins", () => {
   );
 });
 
+test("release sync advances every SDK install contract with its product", (t) => {
+  const root = mkdtempSync(path.join(os.tmpdir(), "oliphaunt-sdk-install-docs-"));
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  const transitions = [
+    { product: "oliphaunt-swift", before: "0.6.1", after: "0.7.0" },
+    { product: "oliphaunt-kotlin", before: "0.1.1", after: "0.2.0" },
+  ];
+  for (const rule of SDK_INSTALL_VERSION_RULES) {
+    const transition = transitions.find(({ product }) => product === rule.product);
+    const file = path.join(root, rule.file);
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, `${rule.prefix}${transition.before}${rule.suffix}\n`);
+  }
+
+  const changes = [];
+  syncSdkInstallDocs(changes, { root, write: true, transitions });
+  assert.deepEqual(
+    changes.map(({ path: file }) => path.relative(root, file)).sort(),
+    SDK_INSTALL_VERSION_RULES.map(({ file }) => file).sort(),
+  );
+  for (const rule of SDK_INSTALL_VERSION_RULES) {
+    const transition = transitions.find(({ product }) => product === rule.product);
+    assert.equal(readFileSync(path.join(root, rule.file), "utf8"), `${rule.prefix}${transition.after}${rule.suffix}\n`);
+  }
+  const checkChanges = [];
+  syncSdkInstallDocs(checkChanges, { root, write: false, transitions });
+  assert.deepEqual(checkChanges, []);
+});
+
 test("shared contrib bootstrap is allowed only from unreleased main state", () => {
   assert.equal(
     sharedContribBootstrapRequired([], () => [{ product: "liboliphaunt-native" }]),

tools/release/verify-release-commit.mjs

@@ -10,7 +10,10 @@ import {
   registryPackageRows,
 } from "./release-artifact-targets.mjs";
 import { compatibilityVersionEntries, loadGraph } from "./release-graph.mjs";
-import { releaseDerivedPathInventory } from "./sync-release-pr.mjs";
+import {
+  releaseDerivedPathInventory,
+  SDK_INSTALL_VERSION_RULES,
+} from "./sync-release-pr.mjs";
 import { RELEASE_PLEASE_BOOTSTRAP_SHA } from "./release-please-bootstrap.mjs";
 
 const TOOL = "verify-release-commit.mjs";
@@ -214,6 +217,10 @@ function derivedVersionRules() {
     }
   }
 
+  for (const { file, product, prefix, suffix } of SDK_INSTALL_VERSION_RULES) {
+    addText(file, { type: "embedded", sourceProduct: product, prefix, suffix });
+  }
+
   for (const { file, versionPaths, sourceProduct, wrapped } of exampleCargoReleaseVersionBindings()) {
     for (const parts of versionPaths) {
       addStructured("toml", file, parts, sourceProduct, wrapped);
@@ -269,6 +276,14 @@ function productTransition(rule, before, after, transitions) {
     : before === transition.before && after === transition.after;
 }
 
+function embeddedTextTransition(rule, before, after, transitions) {
+  const transition = transitions.find(({ product }) => product === rule.sourceProduct);
+  if (transition === undefined) return false;
+  const prior = `${rule.prefix}${transition.before}${rule.suffix}`;
+  const next = `${rule.prefix}${transition.after}${rule.suffix}`;
+  return before.split(prior).length === 2 && after === before.replace(prior, next);
+}
+
 function valueAt(root, parts) {
   let current = root;
   for (const part of parts) {
@@ -444,6 +459,7 @@ function validateTextSemanticDiff({ repo, parent, commit, file, fields, derived,
   ) {
     return;
   }
+  if (derivedRule?.type === "embedded" && embeddedTextTransition(derivedRule, before, after, transitions)) return;
   throw error(`${derived ? "derived file" : "release file"} ${file} contains a non-version semantic change`);
 }