#!/usr/bin/env node const fs = require("fs"); const path = require("path"); const { pathToFileURL } = require("url"); const ROOT = path.resolve(__dirname, ".."); const DOCS_JSON_PATH = path.join(ROOT, "docs.json"); const ROOT_INDEX_PATH = path.join(ROOT, "index.mdx"); const SITEMAP_PATH = path.join(ROOT, "sitemap.xml"); const SITEMAP_MODULE_URL = pathToFileURL( path.join(__dirname, "generate-seo-sitemap.mjs") ).href; const LIVE_BASE_URL = process.env.SEO_AUDIT_BASE_URL; const LIVE_PAGE_SAMPLES = { ja: "/ja/account-deletion", en: "/en/account-deletion", ko: "/ko/account-deletion", zh: "/zh/account-deletion", "zh-tw": "/zh-tw/account-deletion", }; const NON_TIER_LIVE_SAMPLE = "/de/account-deletion"; const HIGH_IMPACT_SLUGS = new Set([ "index", "support", "pricing", "plan-changes", "release-notes", ]); const SITEMAP_CLUSTER_SAMPLES = ["account-deletion", "support", "pricing", "release-notes"]; const EXPLICIT_REDIRECTS = new Map([ ["/", "/ja"], ["/index", "/ja"], ["/zh-TW", "/zh-tw"], ["/zh-TW/:slug", "/zh-tw/:slug"], ["/de/user-vs-guest", "/en/user-vs-guest"], ["/de/pricing", "/en/pricing"], ["/de/free-plan", "/en/free-plan"], ["/de/free-trial", "/en/free-trial"], ["/de/contract-procedures", "/en/contract-procedures"], ["/it/user-vs-guest", "/en/user-vs-guest"], ["/it/pricing", "/en/pricing"], ["/it/free-plan", "/en/free-plan"], ["/it/free-trial", "/en/free-trial"], ["/it/contract-procedures", "/en/contract-procedures"], ]); function fail(message) { console.error(`ERROR: ${message}`); process.exitCode = 1; } function normalizeRoute(value) { if (!value || value === "/") return "/"; return `/${value}`.replace(/\/+/g, "/"); } function pathnameFromUrlish(value, baseUrl) { try { return new URL(value, baseUrl).pathname.replace(/\/+$/, "") || "/"; } catch { return normalizeRoute(value).replace(/\/+$/, "") || "/"; } } function collectNavPages(node, pages = []) { if (!node) return pages; if (Array.isArray(node)) { for (const item of node) collectNavPages(item, pages); return pages; } if (typeof node === "string") { pages.push(node); return pages; } if (typeof node !== "object") return pages; if (typeof node.href === "string") pages.push(node.href); if (Array.isArray(node.pages)) collectNavPages(node.pages, pages); for (const key of ["groups", "tabs", "languages", "versions", "dropdowns", "anchors", "products"]) { if (Array.isArray(node[key])) collectNavPages(node[key], pages); } return pages; } function routeKeyFromNavHref(href) { if (href === "index") return "/"; const normalized = normalizeRoute(href); return normalized.replace(/\/index$/, "") || "/"; } function slugFromRoute(route) { const [, locale, ...rest] = route.split("/"); if (!locale) return "index"; return rest.join("/") || "index"; } function buildEntryMap(entries) { return new Map(entries.map((entry) => [entry.route, entry])); } function parseSitemapXml(xml, baseUrl) { const entries = []; for (const match of xml.matchAll(/([\s\S]*?)<\/url>/g)) { const block = match[1]; const loc = block.match(/([^<]+)<\/loc>/i)?.[1]; if (!loc) continue; const alternates = [...block.matchAll(/]+hreflang="([^"]+)"[^>]+href="([^"]+)"/gi)].map( ([, hreflang, href]) => ({ hreflang, href, route: pathnameFromUrlish(href, baseUrl), }) ); entries.push({ loc, route: pathnameFromUrlish(loc, baseUrl), alternates, }); } return entries; } function ensureSampleClusters(entryMap, tier1Locales, hreflangs, baseUrl) { for (const slug of SITEMAP_CLUSTER_SAMPLES) { const availableRoutes = tier1Locales.map((locale) => slug === "index" ? `/${locale}` : `/${locale}/${slug}` ); const existingRoutes = availableRoutes.filter((route) => entryMap.has(route)); if (existingRoutes.length === 0) { fail(`Missing sitemap cluster for ${slug}`); continue; } const xDefaultRoute = existingRoutes.find((route) => route.startsWith("/ja")) ?? existingRoutes.find((route) => route.startsWith("/en")) ?? existingRoutes[0]; for (const route of existingRoutes) { const entry = entryMap.get(route); const alternateMap = new Map(entry.alternates.map((alternate) => [alternate.hreflang, alternate])); for (const candidateRoute of existingRoutes) { const locale = candidateRoute.split("/")[1]; const expectedHreflang = hreflangs[locale]; const alternate = alternateMap.get(expectedHreflang); if (!alternate) { fail(`Missing hreflang ${expectedHreflang} for ${route} in sitemap`); continue; } if (alternate.route !== candidateRoute) { fail( `Expected hreflang ${expectedHreflang} for ${route} to target ${candidateRoute}, got ${alternate.route}` ); } } const xDefault = alternateMap.get("x-default"); if (!xDefault) { fail(`Missing x-default alternate for ${route} in sitemap`); } else if (xDefault.route !== xDefaultRoute) { fail(`Expected x-default for ${route} to target ${xDefaultRoute}, got ${xDefault.route}`); } if (!entry.loc.startsWith(baseUrl)) { fail(`Sitemap loc must use ${baseUrl}: ${entry.loc}`); } } } } function canonicalFromHtml(html) { return ( html.match(/]+rel=["']canonical["'][^>]+href=["']([^"']+)["']/i)?.[1] ?? html.match(/]+href=["']([^"']+)["'][^>]+rel=["']canonical["']/i)?.[1] ); } function descriptionFromHtml(html) { return ( html.match(/]+name=["']description["'][^>]+content=["']([^"']*)["']/i)?.[1] ?? html.match(/]+content=["']([^"']*)["'][^>]+name=["']description["']/i)?.[1] ); } function robotsNoindexInHtml(html) { return ( /]+name=["']robots["'][^>]+content=["'][^"']*noindex/i.test(html) || /]+content=["'][^"']*noindex[^"']*["'][^>]+name=["']robots["']/i.test(html) ); } async function runLiveChecks(baseUrl, tier1Locales, hreflangs, expectedEntryMap) { for (const route of ["/", "/index"]) { const response = await fetch(`${baseUrl}${route}`, { redirect: "manual" }); if (![301, 302, 307, 308].includes(response.status)) { fail(`Expected ${route} to redirect from ${baseUrl}, got ${response.status}`); continue; } const location = pathnameFromUrlish(response.headers.get("location"), baseUrl); if (location !== "/ja") { fail(`Expected ${route} to redirect to /ja, got ${location}`); } } for (const route of ["/ja", "/en", "/ko", "/zh", "/zh-tw"]) { const response = await fetch(`${baseUrl}${route}`, { redirect: "manual" }); if (response.status !== 200) { fail(`Expected ${route} to return 200 from ${baseUrl}, got ${response.status}`); } } for (const route of ["/ja/index", "/en/index", "/ko/index", "/zh/index", "/zh-tw/index"]) { const response = await fetch(`${baseUrl}${route}`, { redirect: "manual" }); if (![301, 302, 307, 308].includes(response.status)) { fail(`Expected ${route} to redirect from ${baseUrl}, got ${response.status}`); continue; } const location = pathnameFromUrlish(response.headers.get("location"), baseUrl); const expected = route.replace(/\/index$/, ""); if (location !== expected) { fail(`Expected ${route} to redirect to ${expected}, got ${location}`); } } const sitemapResponse = await fetch(`${baseUrl}/sitemap.xml`); if (sitemapResponse.status !== 200) { fail(`Expected /sitemap.xml to return 200 from ${baseUrl}, got ${sitemapResponse.status}`); } else { const xml = await sitemapResponse.text(); if (!xml.includes('xmlns:xhtml="http://www.w3.org/1999/xhtml"')) { fail("Live sitemap.xml is missing the xhtml namespace"); } const liveEntries = parseSitemapXml(xml, baseUrl); const liveEntryMap = buildEntryMap(liveEntries); for (const entry of liveEntries) { const prefix = entry.route.split("/")[1] || ""; if (!tier1Locales.includes(prefix)) { fail(`Non-tier locale URL found in live sitemap: ${entry.route}`); } } ensureSampleClusters(liveEntryMap, tier1Locales, hreflangs, "https://manual.voiceping.net"); for (const route of expectedEntryMap.keys()) { if (!liveEntryMap.has(route)) { fail(`Live sitemap is missing ${route}`); } } } for (const route of Object.values(LIVE_PAGE_SAMPLES)) { const response = await fetch(`${baseUrl}${route}`); if (response.status !== 200) { fail(`Expected ${route} to return 200 from ${baseUrl}, got ${response.status}`); continue; } const html = await response.text(); const title = html.match(/]*>(.*?)<\/title>/is)?.[1]?.trim(); const description = descriptionFromHtml(html); const canonical = canonicalFromHtml(html); if (!title) { fail(`Title is missing for ${route}`); } if (!description) { fail(`Description is missing for ${route}`); } if (!canonical) { fail(`Canonical is missing for ${route}`); } else if (pathnameFromUrlish(canonical, baseUrl) !== route) { fail(`Canonical for ${route} should resolve to itself, got ${canonical}`); } } const nonTierResponse = await fetch(`${baseUrl}${NON_TIER_LIVE_SAMPLE}`); if (nonTierResponse.status !== 200) { fail( `Expected non-tier sample ${NON_TIER_LIVE_SAMPLE} to return 200 from ${baseUrl}, got ${nonTierResponse.status}` ); } else { const html = await nonTierResponse.text(); if (!robotsNoindexInHtml(html)) { fail(`Expected ${NON_TIER_LIVE_SAMPLE} to emit robots noindex`); } } } async function main() { const seoModule = await import(SITEMAP_MODULE_URL); const { DEFAULT_BASE_URL, NON_TIER_LOCALES, TIER1_HREFLANGS, TIER1_LOCALES, generateSitemapXml, listContentFiles, parseFrontmatter, routeFromFile, } = seoModule; if (fs.existsSync(ROOT_INDEX_PATH)) { fail("Root index.mdx should be removed so / can redirect permanently to /ja"); } const docsConfig = JSON.parse(fs.readFileSync(DOCS_JSON_PATH, "utf8")); if (!docsConfig.navigation || !Array.isArray(docsConfig.navigation.tabs)) { fail("docs.json must use navigation.tabs"); } const contentFiles = listContentFiles(ROOT); const fileRoutes = new Set(contentFiles.map((filePath) => routeFromFile(filePath, ROOT))); for (const locale of TIER1_LOCALES) { if (!fileRoutes.has(`/${locale}`)) { fail(`Tier 1 locale root is missing: /${locale}`); } } const navPages = collectNavPages(docsConfig.navigation.tabs); for (const href of navPages) { if (typeof href !== "string") continue; const route = routeKeyFromNavHref(href); if (route === "/") { fail("Navigation must not link the root homepage; use /ja instead"); continue; } if (!fileRoutes.has(route)) { fail(`Navigation references a missing page: ${href}`); } } for (const filePath of contentFiles) { const relPath = path.relative(ROOT, filePath).replaceAll(path.sep, "/"); const route = routeFromFile(filePath, ROOT); const prefix = route.split("/")[1] || ""; const raw = fs.readFileSync(filePath, "utf8"); const frontmatter = parseFrontmatter(raw); const slug = slugFromRoute(route); if (!frontmatter.title) { fail(`Missing title in ${relPath}`); } if (!frontmatter.description) { fail(`Missing description in ${relPath}`); } if (raw.includes("/zh-TW/")) { fail(`Uppercase zh-TW route found in ${relPath}`); } if (NON_TIER_LOCALES.includes(prefix) && frontmatter.noindex !== "true") { fail(`Non-tier locale page must include noindex: true in ${relPath}`); } if ( TIER1_LOCALES.includes(prefix) && HIGH_IMPACT_SLUGS.has(slug) && Array.from(frontmatter.description).length < 30 ) { fail(`Tier 1 high-impact description is too short in ${relPath}`); } if ( [ "/de/pricing", "/de/free-plan", "/de/free-trial", "/de/contract-procedures", "/de/user-vs-guest", "/it/pricing", "/it/free-plan", "/it/free-trial", "/it/contract-procedures", "/it/user-vs-guest", ].some((needle) => raw.includes(needle)) ) { fail(`Legacy broken de/it pricing-plan link still present in ${relPath}`); } } const redirects = new Map( (docsConfig.redirects || []).map((item) => [ normalizeRoute(item.source), normalizeRoute(item.destination), ]) ); for (const [source, destination] of EXPLICIT_REDIRECTS) { if (redirects.get(source) !== destination) { fail(`Missing redirect ${source} -> ${destination}`); } } if (!fs.existsSync(SITEMAP_PATH)) { fail("sitemap.xml is missing; run npm run seo:sitemap"); } else { const actualXml = fs.readFileSync(SITEMAP_PATH, "utf8"); const expectedXml = generateSitemapXml(DEFAULT_BASE_URL, ROOT); if (actualXml !== expectedXml) { fail("sitemap.xml is out of date; run npm run seo:sitemap"); } if (!actualXml.includes('xmlns:xhtml="http://www.w3.org/1999/xhtml"')) { fail("sitemap.xml must include the xhtml namespace"); } const entries = parseSitemapXml(actualXml, DEFAULT_BASE_URL); const entryMap = buildEntryMap(entries); for (const entry of entries) { const prefix = entry.route.split("/")[1] || ""; if (!TIER1_LOCALES.includes(prefix)) { fail(`Non-tier locale URL found in sitemap.xml: ${entry.route}`); } } ensureSampleClusters(entryMap, TIER1_LOCALES, TIER1_HREFLANGS, DEFAULT_BASE_URL); } if (process.argv.includes("--live")) { if (!LIVE_BASE_URL) { fail("Set SEO_AUDIT_BASE_URL to a deployed preview or production URL before running --live"); process.exit(process.exitCode || 1); } const expectedEntries = parseSitemapXml( generateSitemapXml("https://manual.voiceping.net", ROOT), "https://manual.voiceping.net" ); const expectedEntryMap = buildEntryMap(expectedEntries); try { await runLiveChecks( LIVE_BASE_URL.replace(/\/+$/, ""), TIER1_LOCALES, TIER1_HREFLANGS, expectedEntryMap ); } catch (error) { fail(`Live audit failed against ${LIVE_BASE_URL}: ${error.message}`); } } if (process.exitCode) process.exit(process.exitCode); console.log( `SEO audit passed${process.argv.includes("--live") ? ` against ${LIVE_BASE_URL}` : ""}.` ); } main().catch((error) => { fail(error.message); process.exit(process.exitCode || 1); });