Add SEO release safety gates

Author: Fred

.github/workflows/deploy-cloudflare-pages.yml

@@ -26,11 +26,17 @@ jobs:
       - name: Check out repository
         if: ${{ env.CLOUDFLARE_API_TOKEN != '' }}
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
 
       - name: Run SEO regression checks
         if: ${{ env.CLOUDFLARE_API_TOKEN != '' }}
         run: node scripts/seo-regression.mjs
 
+      - name: Enforce safe release size and sitemap dates
+        if: ${{ env.CLOUDFLARE_API_TOKEN != '' }}
+        run: node scripts/release-safety.mjs
+
       - name: Deploy production site
         if: ${{ env.CLOUDFLARE_API_TOKEN != '' }}
         uses: cloudflare/wrangler-action@v3

SEO_RELEASE_CHECKLIST.md

@@ -0,0 +1,38 @@
+# SEO Release Safety Checklist
+
+Use this checklist before changes to indexable pages, navigation, redirects, or sitemap data.
+
+## Release rules
+
+1. Keep each commit to 12 or fewer HTML pages.
+2. Do not combine homepage or generator-page changes with broad article updates.
+3. Keep canonical URLs extensionless and on `https://global-address.com`.
+4. Update a sitemap `lastmod` only when that exact page changed.
+5. Keep the homepage order: address generator H1, country generators, supporting QA content.
+6. Do not change the homepage title, H1, canonical, URL structure, and navigation in the same release.
+7. Wait at least 7 days after a major search-facing change before another broad change.
+
+## Required verification
+
+Run both checks before deployment:
+
+```sh
+node scripts/seo-regression.mjs
+node scripts/release-safety.mjs
+```
+
+After deployment, verify:
+
+- `/`, generator pages, `/guides`, `/sitemap.xml`, and `/robots.txt` return HTTP 200.
+- `www`, `.html`, and `/index` variants redirect once to the canonical URL.
+- Search Console URL Inspection reports the intended canonical for the homepage.
+- Compare 24-hour and 7-day impressions before making another search-facing change.
+
+## Recovery rule
+
+If daily impressions fall by more than 50% for two consecutive complete days:
+
+1. Freeze content, title, URL, canonical, and navigation changes.
+2. Compare the last production commit with the previous stable commit.
+3. Fix only confirmed technical defects.
+4. Do not publish batches of new pages while recovery is being measured.

scripts/release-safety.mjs

@@ -0,0 +1,94 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+
+const maxHtmlFilesPerCommit = 12;
+const [baseRef = "HEAD^", headRef = "HEAD"] = process.argv.slice(2);
+const criticalFiles = new Set([
+  "index.html",
+  "us-address-generator.html",
+  "japan-address-generator.html",
+  "uk-address-generator.html",
+  "korea-address-generator.html",
+  "eu-address-generator.html",
+  "southeast-asia-address-generator.html",
+  "guides.html",
+]);
+
+function git(args, options = {}) {
+  return execFileSync("git", args, {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    ...options,
+  }).trim();
+}
+
+function hasParentCommit() {
+  try {
+    git(["rev-parse", "--verify", baseRef]);
+    git(["rev-parse", "--verify", headRef]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function parseSitemap(xml) {
+  const entries = new Map();
+  for (const block of xml.matchAll(/<url>([\s\S]*?)<\/url>/g)) {
+    const location = block[1].match(/<loc>([^<]+)<\/loc>/)?.[1];
+    const lastmod = block[1].match(/<lastmod>([^<]+)<\/lastmod>/)?.[1];
+    if (location) entries.set(location, lastmod);
+  }
+  return entries;
+}
+
+function fileForLocation(location) {
+  const path = new URL(location).pathname;
+  if (path === "/") return "index.html";
+  if (path === "/en/") return "en/index.html";
+  return `${path.slice(1)}.html`;
+}
+
+if (!hasParentCommit()) {
+  console.log("Release safety checks skipped because no parent commit is available.");
+  process.exit(0);
+}
+
+const changedFiles = git(["diff", "--name-only", baseRef, headRef])
+  .split("\n")
+  .filter(Boolean);
+const changedHtml = changedFiles.filter((file) => file.endsWith(".html"));
+
+assert.ok(
+  changedHtml.length <= maxHtmlFilesPerCommit,
+  `Release changes ${changedHtml.length} HTML pages. Split the update into batches of ${maxHtmlFilesPerCommit} or fewer so search impact can be measured and rolled back safely.`,
+);
+
+const changedCritical = changedHtml.filter((file) => criticalFiles.has(file));
+assert.ok(
+  !(changedCritical.length > 0 && changedHtml.length > 3),
+  `Critical search pages (${changedCritical.join(", ")}) cannot ship in the same commit as a broad ${changedHtml.length}-page update.`,
+);
+
+if (changedFiles.includes("sitemap.xml")) {
+  const previousSitemap = parseSitemap(git(["show", `${baseRef}:sitemap.xml`]));
+  const currentSitemap = parseSitemap(git(["show", `${headRef}:sitemap.xml`]));
+  const changedLastmodLocations = [];
+
+  for (const [location, lastmod] of currentSitemap) {
+    if (previousSitemap.get(location) !== lastmod) changedLastmodLocations.push(location);
+  }
+
+  const unrelatedLastmod = changedLastmodLocations.filter(
+    (location) => !changedHtml.includes(fileForLocation(location)),
+  );
+  assert.deepEqual(
+    unrelatedLastmod,
+    [],
+    `Sitemap lastmod changed without matching page content changes: ${unrelatedLastmod.join(", ")}`,
+  );
+}
+
+console.log(
+  `Release safety checks passed (${changedHtml.length} HTML files changed; limit ${maxHtmlFilesPerCommit}).`,
+);

scripts/seo-regression.mjs

@@ -1,8 +1,72 @@
 import assert from "node:assert/strict";
 import { readFile } from "node:fs/promises";
+import { execFileSync } from "node:child_process";
 import { onRequest } from "../functions/_middleware.js";
 
 const origin = "https://global-address.com";
+const excludedHtml = new Set(["404.html", "baidu_verify_codeva-DlQjPzG0IB.html"]);
+const criticalPages = {
+  "index.html": {
+    title: "地址生成器 - 免费生成多国随机地址、姓名和电话",
+    canonical: `${origin}/`,
+    h1: "地址生成器",
+  },
+  "us-address-generator.html": {
+    title: "美国地址生成器 - 随机美国地址 | Global Address Generator",
+    canonical: `${origin}/us-address-generator`,
+    h1: "美国地址生成器",
+  },
+  "japan-address-generator.html": {
+    title: "日本地址随机生成器 - Global Address Generator",
+    canonical: `${origin}/japan-address-generator`,
+    h1: "日本地址随机生成器",
+  },
+  "uk-address-generator.html": {
+    title: "英国地址生成器 - Global Address Generator",
+    canonical: `${origin}/uk-address-generator`,
+    h1: "随机生成英国地址",
+  },
+  "korea-address-generator.html": {
+    title: "韩国地址生成器 - Global Address Generator",
+    canonical: `${origin}/korea-address-generator`,
+    h1: "随机生成韩国地址",
+  },
+  "eu-address-generator.html": {
+    title: "欧盟国家地址生成器 - Global Address Generator",
+    canonical: `${origin}/eu-address-generator`,
+    h1: "随机生成欧盟国家地址",
+  },
+  "southeast-asia-address-generator.html": {
+    title: "东南亚地址生成器 - Global Address Generator",
+    canonical: `${origin}/southeast-asia-address-generator`,
+    h1: "随机生成东南亚国家地址",
+  },
+  "guides.html": {
+    title: "地址知识中心 - 美国地址生成器",
+    canonical: `${origin}/guides`,
+    h1: "地址知识中心",
+  },
+};
+
+function trackedHtmlFiles() {
+  return execFileSync("git", ["ls-files", "*.html"], { encoding: "utf8" })
+    .trim()
+    .split("\n")
+    .filter(Boolean)
+    .filter((file) => !excludedHtml.has(file));
+}
+
+function canonicalPathForFile(file) {
+  if (file === "index.html") return "/";
+  if (file === "en/index.html") return "/en/";
+  return `/${file.replace(/\.html$/, "")}`;
+}
+
+function matchText(html, pattern, label) {
+  const match = html.match(pattern);
+  assert.ok(match, `${label} must exist`);
+  return match[1].replace(/<[^>]+>/g, "").trim();
+}
 
 async function middlewareResult(path, hostname = "global-address.com") {
   return onRequest({
@@ -51,4 +115,64 @@ assert.match(
   "sitemap must include the canonical homepage",
 );
 
-console.log(`SEO regression checks passed (${redirectCases.length + 4} assertions groups).`);
+const sitemapLocations = [...sitemap.matchAll(/<loc>([^<]+)<\/loc>/g)].map((match) => match[1]);
+assert.equal(new Set(sitemapLocations).size, sitemapLocations.length, "sitemap URLs must be unique");
+
+for (const location of sitemapLocations) {
+  const url = new URL(location);
+  assert.equal(url.origin, origin, `sitemap URL must use the canonical origin: ${location}`);
+  assert.ok(!url.pathname.endsWith(".html"), `sitemap URL must be extensionless: ${location}`);
+  assert.ok(!url.pathname.endsWith("/index"), `sitemap URL must not expose index paths: ${location}`);
+}
+
+const htmlFiles = trackedHtmlFiles();
+const expectedLocations = new Set(htmlFiles.map((file) => `${origin}${canonicalPathForFile(file)}`));
+assert.deepEqual(
+  new Set(sitemapLocations),
+  expectedLocations,
+  "sitemap must contain every indexable HTML page exactly once",
+);
+
+for (const file of htmlFiles) {
+  const html = await readFile(new URL(`../${file}`, import.meta.url), "utf8");
+  const canonical = matchText(
+    html,
+    /<link\s+rel="canonical"\s+href="([^"]+)"/i,
+    `${file} canonical`,
+  );
+  assert.equal(
+    canonical,
+    `${origin}${canonicalPathForFile(file)}`,
+    `${file} canonical must match its extensionless URL`,
+  );
+  assert.doesNotMatch(html, /<meta\s+name="robots"\s+content="[^"]*noindex/i, `${file} must remain indexable`);
+
+  for (const hrefMatch of html.matchAll(/href="([^"]+)"/g)) {
+    const href = hrefMatch[1];
+    if (href.startsWith("./") || href.startsWith("/")) {
+      assert.ok(!/\.html(?:[?#]|$)/.test(href), `${file} contains a legacy internal .html link: ${href}`);
+      assert.ok(!/(?:^|\/)index(?:[?#]|$)/.test(href), `${file} contains a legacy internal index link: ${href}`);
+    }
+  }
+}
+
+for (const [file, expected] of Object.entries(criticalPages)) {
+  const html = await readFile(new URL(`../${file}`, import.meta.url), "utf8");
+  assert.equal(matchText(html, /<title>([^<]+)<\/title>/i, `${file} title`), expected.title);
+  assert.equal(
+    matchText(html, /<link\s+rel="canonical"\s+href="([^"]+)"/i, `${file} canonical`),
+    expected.canonical,
+  );
+  assert.equal(matchText(html, /<h1[^>]*>([\s\S]*?)<\/h1>/i, `${file} h1`), expected.h1);
+}
+
+const homeH1Position = home.indexOf('<h1 id="pageTitle">地址生成器</h1>');
+const countrySectionPosition = home.indexOf('<section id="countries"');
+const qaLabPosition = home.indexOf('<section class="reference-section qa-promo"');
+assert.ok(homeH1Position >= 0, "homepage must keep the address generator H1");
+assert.ok(countrySectionPosition > homeH1Position, "country generators must follow the homepage H1");
+assert.ok(qaLabPosition > countrySectionPosition, "QA Lab must not appear before the country generators");
+
+console.log(
+  `SEO regression checks passed (${htmlFiles.length} indexable pages, ${sitemapLocations.length} sitemap URLs).`,
+);