@zalkera/client 0.11.0 → 0.13.0

package/bin/check-aeo-surfaces.mjs

@@ -0,0 +1,706 @@
+#!/usr/bin/env node
+/**
+ * AEO 보장 표면 검사기 (memo119 §1.3 · T5).
+ *
+ * **개시된 사이트를 크롤해 보장 그래프가 실제로 나오는지 잰다.** 소스를 읽지 않는 것이 요점이다
+ * (오너 전제 C): "이 섹션을 써라"는 디자인 자유를 깎지만 "개시된 페이지에서 이 그래프가 나오는가"는
+ * 아무것도 깎지 않는다. 그래서 이 검사기는 어떤 스택으로 짰든·어떤 섹션을 썼든 묻지 않고, 나온 HTML 만 본다.
+ *
+ * 잣대는 백엔드 정본 `doc/contracts/aeo-surface-guarantees.json` 이고 이 파일은 그 정본의 **집행자**다.
+ * 규범을 여기서 새로 만들지 않는다 — 표에 없는 것은 검사하지 않고, 표에 있는 것은 봐주지 않는다.
+ *
+ * ── 이 파일이 왜 client 패키지에 사는가(memo123 §6.1) ────────────────────────
+ * 원래 이 검사기는 `storefront-template/scripts/` 에 살았다. 그런데 이제 **사람이 CLI 로 치는 것 말고도**
+ * 두 자리에서 돌아야 한다: ⑴ 고객 zip(원래 자리) ⑵ serving-orchestrator 가 발행 직후 자동으로 재는 자리.
+ * ⑵의 실행체는 "외부 의존 0 단일 `server.mjs`"라는 속성을 지켜야 해서 검사기를 자기 안에 넣을 수 없고,
+ * 대신 **툴킷 디렉터리에 `npm i @zalkera/client@<pin>` 해서 그 bin 을 child 로 spawn** 한다.
+ * 사본을 하나 더 두면 두 검사기가 조용히 갈라지므로(`lib/site-crawl.mjs` 의 KDoc 과 같은 논거) 정본을
+ * 여기로 옮기고 template 의 `scripts/check-aeo-surfaces.mjs` 는 이 bin 을 부르는 **얇은 wrapper** 다.
+ *
+ * ── 잣대를 어디서 찾는가(memo122 §1.3-2) ────────────────────────────────────
+ * 이 검사기는 고객 zip 에 실려 나간다. 그런데 **잣대는 실려 나가지 않아서** 고객 기계에서는 기본 경로
+ * (형제 `../backend`)가 없어 exit 2 로 죽어 있었다(2026-07-29 실측). 그래서 해석을 3단으로 둔다:
+ *
+ *   ① `--guarantees <경로>`                       — 명시가 언제나 이긴다
+ *   ② `@zalkera/client/contracts/…`(npm 운반본)   — **고객의 기본 경로**. zip 에 이 의존이 이미 있어
+ *                                                   `npm i` 만 하면 잣대가 따라온다. 이 파일이 그 패키지
+ *                                                   안에 살므로 **자기 패키지의 운반본**이 1순위 후보다
+ *   ③ 형제 `../backend/doc/contracts/…`(정본)     — 우리 개발 체크아웃 관례 폴백
+ *
+ * 정본은 여전히 백엔드 하나이고 ②는 그 **발행 산출물**이다(client 발행 전 `sync-aeo-guarantees.mjs` 가
+ * 바이트 동일을 강제한다). ②로 재는 자리에 ③도 함께 있으면 둘을 비교해 **갈라짐을 경고**한다 — 운반본이
+ * 낡았는데 그걸로 잰 판정을 정본 판정처럼 읽는 것이 이 3단 구조의 유일한 새 위험이라서다.
+ * ③의 후보 자리는 **이 파일 기준과 실행 위치(cwd) 기준 둘 다** 본다: 이 파일이 패키지 안으로 들어오면서
+ * "파일 기준 형제"는 `node_modules/backend` 라는 없는 경로가 됐고, 그것만 보면 개발 체크아웃에서
+ * 드리프트 경고가 조용히 꺼진다(옮기면서 잃을 뻔한 축이라 여기 적어 둔다).
+ *
+ * ── 사용 ────────────────────────────────────────────────────────────────────
+ *   npx zalkera-aeo-check <사이트URL> --category BOOKING [--category BLOG] \
+ *        [--code beauty-nail --version 1.0.0] \
+ *        [--guarantees ../backend/doc/contracts/aeo-surface-guarantees.json] \
+ *        [--out out/aeo-snapshot.json] [--max-pages 60] [--route /추가경로]…
+ *   (스토어프론트 체크아웃·고객 zip 안에서는 `npm run check:aeo -- …` 가 같은 bin 을 부른다)
+ *
+ *   npx zalkera-aeo-check <사이트URL> --site-wide-only
+ *        **보장 주장이 없는 사이트**를 재는 모드(memo123 §6.3 B-1). `--category` 를 요구하지 않고
+ *        siteWide 버킷(robots·sitemap·JSON-LD 절대 URL)만 잰다. 카테고리 required 는 아예 판정하지
+ *        않는다 — 어휘 준수를 주장한 적 없는 사이트에 그 잣대를 들이대는 것은 오너 전제 A(디자인 자유)를
+ *        어기는 일이다. 발행 직후 자동 검사(orchestrator)가 전 사이트에 쓰는 모드가 이것이다.
+ *
+ *   npx zalkera-aeo-check --print-guarantees
+ *        잣대 해석만 해 보고 끝낸다(사이트 크롤 없음·네트워크 불요). 어떤 출처의 어느 rev 로 재는지와
+ *        고를 수 있는 `--category` 목록을 찍는다. `verify-zip.mjs` 가 zip 안에서 이걸 돌려 "검사기가
+ *        살아서 뜨는가"를 기계로 확인한다 — 조용히 죽는 상태가 다시 생기면 zip 게이트가 잡는다.
+ *
+ * 종료코드: 0=required 전부 통과 · 1=보장 미충족(red) · 2=실행 불가(인자·네트워크·표 부재)
+ *
+ * ── red 는 결함 보고이지 실패가 아니다 ──────────────────────────────────────
+ * 이 검사기를 처음 돌리면 **우리 팩부터 red 가 난다**(§0-6 실측: CMS JsonLd 0·상품 목록 라우트 부재·
+ * ItemList 0·openingHours 저장 자리 없음). 그건 검사기가 잘못 만들어진 신호가 아니라 **본보기 정합
+ * 작업(T6)의 지시서**다. 통과시키려고 표를 낮추면 보장이 거짓이 되고, 그 순간 이 파일은 쓸모가 없어진다.
+ *
+ * ── 무엇을 실패로 세지 않는가 ────────────────────────────────────────────────
+ *  · `planned` — 표가 목표로 적어 뒀지만 아직 우리도 못 내는 표면. PLANNED_MISSING 으로 보고만 한다.
+ *  · `conditional` — 섹션이 있을 때만 성립하는 표면(FAQPage). 크롤한 HTML 만으로는 "섹션을 안 썼다"와
+ *    "썼는데 그래프가 없다"를 구분할 수 없으므로, 안 보이면 SKIPPED 다. 못 세는 것을 센 척하지 않는다.
+ *  · `TESTIMONIALS` 의 Review·별점 — 이건 **의도적 부정 보장**이라 없는 것이 정답이고, 오히려 나오면
+ *    실패다(self-serving reviews 정책 위반). 누락으로 잡으면 검사기가 정책을 거꾸로 아는 것이다.
+ */
+import {existsSync, mkdirSync, readFileSync, writeFileSync} from "node:fs";
+import {createRequire} from "node:module";
+import {dirname, join, resolve} from "node:path";
+import {fileURLToPath} from "node:url";
+import {FUNCTIONAL_SEGMENTS, crawlPages, makeClassifier} from "../lib/site-crawl.mjs";
+
+/**
+ * 판정 형식이 바뀌면 올린다 — 스냅샷에 박혀서 "어느 잣대로 잰 판정인가"가 사후에도 남는다.
+ *
+ * 2 = `--site-wide-only` 모드와 스냅샷의 `mode` 필드 추가(memo123 §6.3). 기존 카테고리 판정의 잣대는
+ * 하나도 안 바뀌었지만, 스냅샷 형식에 필드가 늘었고 그 필드를 읽는 소비자(promote 게이트·백엔드 ingest)가
+ * "구판 스냅샷인가"를 이 수로 가른다.
+ */
+const CHECKER_VERSION = 2;
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+// ── 인자 ─────────────────────────────────────────────────────────────────────
+
+const argv = process.argv.slice(2);
+const flag = (name, fallback = undefined) => {
+    const i = argv.indexOf(`--${name}`);
+    return i >= 0 && argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[i + 1] : fallback;
+};
+const flagAll = (name) => {
+    const out = [];
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === `--${name}` && argv[i + 1] && !argv[i + 1].startsWith("--")) out.push(argv[i + 1]);
+    }
+    return out;
+};
+const die = (msg) => {
+    console.error(msg);
+    process.exit(2);
+};
+
+const siteUrl = argv.find((a) => !a.startsWith("--") && /^https?:\/\//.test(a));
+const categories = flagAll("category");
+const printOnly = argv.includes("--print-guarantees");
+/**
+ * 무주장 모드(memo123 §6.3 B-1). **카테고리 판정을 아예 하지 않는다** — 끄는 것이 아니라 안 하는 것이다.
+ * 보장 어휘를 주장한 적 없는 사이트에 그 잣대를 대면, 그 사이트가 어떤 스택으로 짰든 red 가 쏟아지고
+ * 그 red 는 사실이 아니라 **잣대를 잘못 고른 결과**다(오너 전제 A). 그래서 카테고리 축은 판정에서 빠지고
+ * 사이트 축(robots·sitemap·절대 URL)만 남는다 — 그 셋은 어떤 디자인 선택과도 무관한 기계 가독 최소치다.
+ */
+const siteWideOnly = argv.includes("--site-wide-only");
+if (!printOnly && !siteUrl) {
+    die("사용: zalkera-aeo-check <사이트URL> --category <코드> [--category …] [--code …] [--version …] [--out …]\n      무주장 사이트: zalkera-aeo-check <사이트URL> --site-wide-only\n      (잣대 해석만 확인: zalkera-aeo-check --print-guarantees)");
+}
+if (!printOnly && siteWideOnly && categories.length > 0) {
+    // 둘 다 주면 어느 쪽을 원한 것인지 알 수 없다. 조용히 한쪽을 이기게 하면 "쟀다고 생각한 것"과
+    // "잰 것"이 갈라지고, 그 갈라짐은 스냅샷을 봐야만 보인다.
+    die("--site-wide-only 와 --category 는 같이 못 준다 — 카테고리 판정을 하든지, 사이트 축만 재든지 하나다.");
+}
+if (!printOnly && !siteWideOnly && categories.length === 0) {
+    die("--category 가 없다. 보장 주장이 있는 팩이면 그 코드를, 무주장 사이트면 --site-wide-only 를 주십시오.");
+}
+
+// ── 잣대 해석 — 명시 > @zalkera/client 운반본 > 형제 백엔드 정본(파일 머리말 참조) ──
+
+const CARRIED_SPECIFIER = "@zalkera/client/contracts/aeo-surface-guarantees.json";
+/** 이 파일이 사는 패키지 자신의 운반본. bin 으로 돌 때 **가장 확실한 자리**다(해석을 거칠 필요가 없다). */
+const OWN_CARRIED = join(ROOT, "contracts", "aeo-surface-guarantees.json");
+/**
+ * 형제 백엔드 정본 후보. **두 기준점을 다 본다** — 이 파일이 패키지 안으로 들어오면서 파일 기준 형제는
+ * `node_modules/backend` 라는 없는 경로가 됐고, 실행 위치(cwd) 기준이 개발 체크아웃의 실제 형상이다.
+ */
+const SIBLING_CANDIDATES = [...new Set([join(ROOT, ".."), process.cwd()])].map((base) =>
+    join(base, "..", "backend", "doc/contracts/aeo-surface-guarantees.json"),
+);
+const siblingCanonical = () => SIBLING_CANDIDATES.find((p) => existsSync(p)) ?? null;
+const requireFrom = createRequire(import.meta.url);
+
+/**
+ * 설치된 `@zalkera/client` 안의 운반본 경로. **패키지 해석에 맡긴다** — 경로를 손으로 짜면
+ * (`node_modules/@zalkera/client/…`) 워크스페이스 호이스팅·pnpm 링크에서 조용히 빗나간다.
+ * 검사기 자리 기준으로 먼저 찾고, 그래도 없으면 실행 위치 기준으로 한 번 더 본다
+ * (검사기만 다른 데로 복사해 쓰는 경우 — 실제로 그렇게 돌려 본 적이 있다).
+ */
+function resolveCarried() {
+    for (const from of [ROOT, process.cwd()]) {
+        try {
+            return requireFrom.resolve(CARRIED_SPECIFIER, {paths: [from]});
+        } catch {
+            /* 다음 후보 */
+        }
+    }
+    return null;
+}
+
+function resolveGuarantees() {
+    const explicit = flag("guarantees");
+    if (explicit) return {path: resolve(explicit), source: "--guarantees 인자"};
+    if (existsSync(OWN_CARRIED)) return {path: OWN_CARRIED, source: "@zalkera/client 운반본(자기 패키지)"};
+    const carried = resolveCarried();
+    if (carried) return {path: carried, source: `@zalkera/client 운반본(${CARRIED_SPECIFIER})`};
+    const sibling = siblingCanonical();
+    if (sibling) return {path: sibling, source: "형제 백엔드 정본(개발 체크아웃)"};
+    return {path: null, source: null};
+}
+
+/** 패키지 자체는 설치돼 있는가 — "안 깔림"과 "깔렸는데 운반본이 없는 구 버전"은 고칠 방법이 다르다. */
+function clientInstalled() {
+    for (const from of [ROOT, process.cwd()]) {
+        try {
+            requireFrom.resolve("@zalkera/client", {paths: [from]});
+            return true;
+        } catch {
+            /* 다음 후보 */
+        }
+    }
+    return false;
+}
+
+const resolved = resolveGuarantees();
+if (!resolved.path) {
+    die(
+        "보장표(잣대)를 못 찾았다 — 아무 판정도 하지 않는다. 없는 잣대로 통과시키는 것보다 안 재는 편이 정직하다.\n" +
+            "   찾아본 곳:\n" +
+            `   ① --guarantees 인자 — 안 줬다\n` +
+            `   ② ${CARRIED_SPECIFIER} — ${
+                clientInstalled()
+                    ? "@zalkera/client 는 설치돼 있는데 그 안에 보장표가 없다(운반본을 싣지 않는 구 버전 — `npm i @zalkera/client@latest` 로 올리십시오)."
+                    : "@zalkera/client 가 설치돼 있지 않다. 이 디렉터리에서 `npm install` 을 먼저 돌리십시오."
+            }\n` +
+            `   ③ ${SIBLING_CANDIDATES.join(" · ")} — 없다(우리 개발 체크아웃 관례라 고객 기계에는 원래 없다)`,
+    );
+}
+const specPath = resolved.path;
+const themeCode = flag("code", null);
+const themeVersion = flag("version", null);
+const outPath = flag("out", "");
+const maxPages = Number(flag("max-pages", "60"));
+const extraRoutes = flagAll("route");
+
+let specText;
+let spec;
+try {
+    specText = readFileSync(specPath, "utf8");
+    spec = JSON.parse(specText);
+} catch (e) {
+    die(`보장표를 못 읽었다: ${specPath}\n   ${e.message}\n   --guarantees 로 다른 경로를 주십시오.`);
+}
+
+/**
+ * 운반본으로 재는데 정본도 곁에 있으면 대조한다. 갈라져 있으면 **판정 자체가 낡은 잣대의 판정**이므로
+ * 조용히 넘기지 않는다 — 막지는 않는다(정본이 있는 자리는 우리 개발 체크아웃뿐이고, 그때 필요한 것은
+ * 차단이 아니라 "client 발행이 밀렸다"는 신호다).
+ */
+let carriedDrift = null;
+const siblingForDrift = resolved.source?.startsWith("@zalkera/client") ? siblingCanonical() : null;
+if (siblingForDrift) {
+    try {
+        if (readFileSync(siblingForDrift, "utf8") !== specText) {
+            carriedDrift = `운반본이 형제 백엔드 정본과 다르다 — client 발행이 밀렸을 수 있다(${siblingForDrift} 로 재려면 --guarantees 로 지정).`;
+        }
+    } catch {
+        /* 정본을 못 읽으면 대조를 포기한다 — 이 축은 경고이지 게이트가 아니다 */
+    }
+}
+
+const byCategory = new Map((spec.categories ?? []).map((c) => [c.category, c]));
+
+if (printOnly) {
+    console.log(`· 잣대 출처 ${resolved.source}`);
+    console.log(`· 경로 ${specPath}`);
+    console.log(`· 보장표 rev ${spec.contractRev} · 카테고리 ${[...byCategory.keys()].join(", ")}`);
+    if (carriedDrift) console.warn(`⚠️  ${carriedDrift}`);
+    console.log(`· 사이트 축(무주장) 검사 항목 ${(spec.siteWide?.requirements ?? []).map((r) => r.id).join(", ")} — \`--site-wide-only\``);
+    console.log("· 잣대 해석 성공 — 이제 사이트 URL 과 --category(또는 --site-wide-only)를 주면 실제로 잽니다.");
+    process.exit(0);
+}
+
+for (const c of categories) {
+    if (!byCategory.has(c)) {
+        // 표에 없는 이름은 **순수 라벨**이다(예: "미니멀"). 보장 주장이 없으므로 잴 것도 없고,
+        // 억지로 통과시킨 스냅샷을 만들면 promote 게이트가 의미를 잃는다.
+        die(`'${c}' 는 보장표에 없는 이름이라 검사 대상이 아니다(순수 라벨). 등재된 카테고리: ${[...byCategory.keys()].join(", ")}`);
+    }
+}
+
+const origin = new URL(siteUrl).origin;
+const classify = makeClassifier({origin, skipRoutes: new Set()}); // 검사기는 아무것도 공개하지 않는다 — /policies 도 훑는다
+
+// ── JSON-LD 추출 ─────────────────────────────────────────────────────────────
+
+const LD_RE = /<script[^>]+type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi;
+
+/** 한 노드를 그 자신 + 중첩 노드 전부로 편다. `@graph`·배열·중첩 객체를 같은 방식으로 훑는다. */
+function flattenNodes(value, out = []) {
+    if (Array.isArray(value)) {
+        for (const v of value) flattenNodes(v, out);
+        return out;
+    }
+    if (value && typeof value === "object") {
+        if (value["@type"] !== undefined) out.push(value);
+        for (const v of Object.values(value)) flattenNodes(v, out);
+    }
+    return out;
+}
+
+const typesOf = (node) => {
+    const t = node["@type"];
+    return Array.isArray(t) ? t.map(String) : t == null ? [] : [String(t)];
+};
+
+/**
+ * 페이지에서 JSON-LD 를 꺼낸다. 파싱 실패는 **버리지 않고 기록**한다 — 깨진 JSON-LD 는 없는 것보다
+ * 나쁘고(크롤러가 페이지 전체의 구조화 데이터를 버린다), 조용히 넘기면 그 사실이 안 보인다.
+ * `JsonLd.tsx` 가 `<` 를 `<` 로 이스케이프하므로 `</script>` 조기 종료는 나지 않는다.
+ */
+function extractJsonLd(html) {
+    const roots = [];
+    const nodes = [];
+    const malformed = [];
+    LD_RE.lastIndex = 0;
+    let m;
+    while ((m = LD_RE.exec(html)) !== null) {
+        try {
+            const parsed = JSON.parse(m[1]);
+            for (const r of Array.isArray(parsed) ? parsed : [parsed]) roots.push(r);
+            flattenNodes(parsed, nodes);
+        } catch (e) {
+            malformed.push(e.message);
+        }
+    }
+    return {roots, nodes, malformed};
+}
+
+/** 태그를 걷어낸 순수 텍스트. */
+function textOf(html) {
+    return html
+        .replace(/<script[\s\S]*?<\/script>/gi, " ")
+        .replace(/<style[\s\S]*?<\/style>/gi, " ")
+        .replace(/<[^>]+>/g, " ")
+        .replace(/&[a-z#0-9]+;/gi, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+
+/** 지정 태그의 요소를 **내용째** 걷어낸다. 상대하는 마크업이 우리가 낸 것이라(임의 웹이 아니다) 중첩 동명 태그는 없다. */
+function stripElements(html, ...tags) {
+    return tags.reduce((acc, tag) => acc.replace(new RegExp(`<${tag}\\b[^>]*>[\\s\\S]*?<\\/${tag}>`, "gi"), " "), html);
+}
+
+/**
+ * SSR 판정 — **JS 실행 없이 그 페이지의 주제와 본문이 응답에 실려 있는가.**
+ *
+ * 계약이 `cms-page-ssr`·`post-list-ssr` 의 why 에 적은 요구가 그대로 잣대다: "본문이 JS 실행 없이 응답
+ * 본문에 실려야 한다." 그래서 **제목만으로는 통과가 아니다** — 제목 검증으로 줄이면 h1 만 서버에서 그리고
+ * 본문은 클라이언트가 fetch 하는 팩이 보장 배지를 받는다(이 검사기는 티어 B/C 서드파티 팩에 동등 배지를
+ * 주는 유일한 잣대라 그 순간 배지가 거짓이 된다).
+ *
+ * 판정 잣대를 "글자 수 N자 이상"으로 두려다 실측에서 **거짓 red** 를 냈다: 상품 상세가 104자, 글이
+ * 0건인 블로그 목록이 14자였는데 둘 다 서버가 정상 렌더한 페이지였다. 짧은 것은 렌더 실패가 아니라
+ * **콘텐츠가 짧은 것**이고, 그 둘을 길이로는 못 가른다. 그래서 길이가 아니라 **자리**로 가른다:
+ *
+ *  ① `<h1>` 에 글자가 있는가 — 그 페이지가 무엇에 관한 것인지 서버가 이미 말했는가.
+ *     클라이언트에서만 그리는 셸은 여기가 비어 있다(레이아웃의 헤더·푸터에는 h1 이 없다).
+ *  ② 본문 범위에서 **h1 자신을 뺀 잔여**에 글자가 하나라도 있는가. h1 을 빼지 않으면 제목 글자가
+ *     본문으로 세어져 ②가 ①의 되풀이가 된다(실측: `<main><h1>젤 네일</h1><div id="app"/></main>` 통과).
+ *     빈 상태 문구("게시글이 없습니다")는 h1 밖에 있으므로 여전히 통과다 — 그건 데이터가 없는 것이지
+ *     렌더가 없는 것이 아니다. 상품 상세도 h1 밖에 설명·가격이 있어 통과한다.
+ *
+ * 본문 범위는 `<main>` 안쪽이고, `<main>` 이 없으면 **head·header/nav/footer 를 걷어낸 나머지**다.
+ * 문서 전체를 폴백으로 쓰면 `<title>` 과 헤더 내비 글자만으로 셸이 통과한다(실측 확인).
+ *
+ * 그래프를 요구하는 라우트에는 더 강한 증거가 이미 있다 — **JSON-LD 가 원본 응답에 실려 왔다는 사실**
+ * 자체가 서버 렌더의 증명이다. 그래서 이 판정은 그래프가 없는 표면(목록·고정 페이지)에서 주로 일한다.
+ */
+function judgeSsr(html) {
+    const h1 = /<h1[^>]*>([\s\S]*?)<\/h1>/i.exec(html);
+    const h1Text = h1 ? textOf(h1[1]) : "";
+    if (!h1Text) return {ok: false, why: "서버 응답에 글자 있는 <h1> 이 없다(클라이언트에서만 그리는 셸)"};
+    const main = /<main[^>]*>([\s\S]*?)<\/main>/i.exec(html);
+    const scope = main ? main[1] : stripElements(html, "head", "header", "nav", "footer");
+    const bodyText = textOf(stripElements(scope, "h1"));
+    if (!bodyText) {
+        return {
+            ok: false,
+            why: main
+                ? "<main> 에 제목뿐이고 본문이 없다 — 본문을 클라이언트에서 그리는 부분 CSR 이다"
+                : "<main> 이 없고 제목 밖 본문도 응답에 없다 — 클라이언트에서만 그리는 셸이다",
+        };
+    }
+    return {ok: true};
+}
+
+// ── 라우트 해석 ──────────────────────────────────────────────────────────────
+
+const routeDefs = Object.fromEntries(Object.entries(spec.routes ?? {}).filter(([k]) => !k.startsWith("$")));
+
+/**
+ * 예약 세그먼트 — `/{slug}` 인스턴스 후보에서 뺀다. **표에서 유도한다**(하드코딩 2벌 금지):
+ * 다른 라우트들의 리터럴 선두 세그먼트 + 기능 세그먼트 + 식별정보 라우트.
+ */
+const reservedFirstSegments = new Set([...FUNCTIONAL_SEGMENTS, "policies", "contact"]);
+for (const def of Object.values(routeDefs)) {
+    const p = def.path ?? def.pattern ?? "";
+    const first = p.split("/").filter(Boolean)[0];
+    if (first && !first.startsWith("{")) reservedFirstSegments.add(first);
+}
+
+function instanceMatcher(pattern) {
+    const segs = pattern.split("/").filter(Boolean);
+    return (path) => {
+        const got = path.split("/").filter(Boolean);
+        if (got.length !== segs.length) return false;
+        for (let i = 0; i < segs.length; i++) {
+            if (segs[i].startsWith("{")) {
+                if (i === 0 && reservedFirstSegments.has(got[i])) return false;
+            } else if (segs[i] !== got[i]) return false;
+        }
+        return true;
+    };
+}
+
+// ── 크롤 ─────────────────────────────────────────────────────────────────────
+
+/** 표가 요구하는 리터럴 라우트는 링크가 없어도 직접 두드린다 — **라우트 부재가 곧 보장 부재**라서다. */
+const literalRoutes = Object.values(routeDefs)
+    .filter((d) => d.kind === "LITERAL")
+    .map((d) => d.path);
+
+/** 기계용 파일은 크롤러가 페이지로 안 받는다(blocked) — 따로 두드린다. */
+async function fetchText(path) {
+    try {
+        const res = await fetch(origin + path, {headers: {"user-agent": "zalkera-aeo-check"}});
+        return res.ok ? await res.text() : null;
+    } catch {
+        return null;
+    }
+}
+
+console.log(`· 대상 ${siteUrl} · ${siteWideOnly ? "무주장(사이트 축만)" : `카테고리 ${categories.join(", ")}`} · 보장표 rev ${spec.contractRev}`);
+console.log(`· 잣대 출처 ${resolved.source} — ${specPath}`);
+if (carriedDrift) console.warn(`⚠️  ${carriedDrift}`);
+
+const robotsTxt = await fetchText("/robots.txt");
+const sitemapXml = await fetchText("/sitemap.xml");
+const sitemapLocs = new Set(
+    [...(sitemapXml ?? "").matchAll(/<loc>\s*([^<]+?)\s*<\/loc>/gi)].map((m) => {
+        try {
+            return new URL(m[1]).pathname.replace(/\/+$/, "") || "/";
+        } catch {
+            return m[1];
+        }
+    }),
+);
+
+/**
+ * **sitemap 을 크롤 시드로 쓴다.** 링크 추적만으로는 목록 라우트가 없는 사이트에서 상품 상세를 영영 못
+ * 만난다(실측: 상품 5행이 있는데 /products 가 없어 상세가 0건으로 잡혔다) — 그건 목록 부재의 결과이지
+ * 상세 부재가 아닌데 검사기가 둘을 섞어 보고하면 T6 지시서가 흐려진다. sitemap 은 사이트 자신이 신고한
+ * 공개 라우트 목록이라 이 용도의 정당한 출처다. 없으면(sitemap 부재) 링크 추적만으로 돈다.
+ */
+const sitemapSeed = [...sitemapLocs].filter((p) => p.startsWith("/"));
+
+const crawled = await crawlPages({
+    origin,
+    entryPath: new URL(siteUrl).pathname.replace(/\/+$/, "") || "/",
+    extraRoutes: [...literalRoutes, ...sitemapSeed, ...extraRoutes],
+    maxPages,
+    classify,
+    userAgent: "zalkera-aeo-check",
+    onPage: (p) => console.log(`  · 크롤 ${p}`),
+});
+
+if (crawled.pages.size === 0) {
+    die(`크롤한 페이지가 0건이다 — 사이트가 응답하지 않는다.\n${crawled.fetchFailures.map((f) => `   · ${f}`).join("\n")}`);
+}
+
+/** 라우트 → {status, html, ld}. 못 받은 라우트는 여기 없다(= 부재). */
+const seen = new Map();
+for (const [path, html] of crawled.pages) seen.set(path, {html, ld: extractJsonLd(html)});
+
+// ── 판정 ─────────────────────────────────────────────────────────────────────
+
+/** 라우트 이름 → 검사 대상 페이지. LITERAL 은 그 경로, INSTANCE 는 크롤에서 찾은 실물 한 건. */
+function resolveRoute(name) {
+    if (name === "any") return {kind: "ANY"};
+    const def = routeDefs[name];
+    if (!def) return {kind: "UNKNOWN"};
+    if (def.kind === "LITERAL") {
+        const page = seen.get(def.path);
+        return page ? {kind: "PAGE", path: def.path, page} : {kind: "MISSING", path: def.path};
+    }
+    const match = instanceMatcher(def.pattern);
+    for (const [path, page] of seen) if (match(path)) return {kind: "PAGE", path, page};
+    return {kind: "MISSING", path: def.pattern};
+}
+
+const pageHasType = (page, type) => page.ld.nodes.some((n) => typesOf(n).includes(type));
+const anyPageHasType = (type) => [...seen.values()].some((p) => pageHasType(p, type));
+
+/** `requiredChildren` — 그 타입 노드 **안에** 자식 타입이 있는가(Product 안의 Offer 처럼). */
+function nodeContainsType(node, type) {
+    return flattenNodes(node).some((n) => n !== node && typesOf(n).includes(type));
+}
+
+function judgeSurface(surface, bucket) {
+    const base = {id: surface.id, bucket, route: surface.route ?? null, jsonLd: surface.jsonLd ?? []};
+    const target = resolveRoute(surface.route ?? "any");
+
+    if (target.kind === "UNKNOWN") return {...base, status: "ERROR", detail: `모르는 라우트 참조 '${surface.route}'`};
+
+    // 라우트가 없다 = 표면이 없다. 스킵이 아니라 미충족이다.
+    if (target.kind === "MISSING") {
+        return {...base, status: "MISSING_ROUTE", detail: `라우트 부재 — ${target.path} 가 응답하지 않거나 실물이 0건이다`};
+    }
+
+    const types = surface.jsonLd ?? [];
+    const hasType = (t) => (target.kind === "ANY" ? anyPageHasType(t) : pageHasType(target.page, t));
+    const at = target.kind === "ANY" ? "(사이트 어디든)" : target.path;
+
+    // ① JSON-LD 타입 — 배열이면 그중 **하나라도** 있으면 통과(Organization|LocalBusiness|BeautySalon 처럼 좁힘 허용).
+    if (types.length > 0) {
+        const found = types.filter(hasType);
+        if (found.length === 0) {
+            return {...base, at, status: "MISSING_JSONLD", detail: `${at} 에 ${types.join("|")} 그래프가 없다`};
+        }
+        for (const child of surface.requiredChildren ?? []) {
+            const carriers =
+                target.kind === "ANY"
+                    ? [...seen.values()].flatMap((p) => p.ld.nodes)
+                    : target.page.ld.nodes;
+            const ok = carriers.some((n) => found.some((t) => typesOf(n).includes(t)) && nodeContainsType(n, child));
+            if (!ok) {
+                return {...base, at, status: "MISSING_CHILD", detail: `${at} 의 ${found[0]} 안에 ${child} 가 없다`};
+            }
+        }
+    }
+
+    // ①-b 그래프 **속성** 요구(openingHours 처럼 타입이 아니라 필드인 것).
+    if (surface.jsonLdProperty) {
+        const pool = target.kind === "ANY" ? [...seen.values()].flatMap((p) => p.ld.nodes) : target.page.ld.nodes;
+        if (!pool.some((n) => n[surface.jsonLdProperty] != null)) {
+            return {...base, at, status: "MISSING_PROPERTY", detail: `${at} 의 JSON-LD 에 ${surface.jsonLdProperty} 속성이 없다`};
+        }
+    }
+
+    // ② SSR — JS 실행 없이 본문이 실려 있는가.
+    if (surface.ssr && target.kind === "PAGE") {
+        const ssr = judgeSsr(target.page.html);
+        if (!ssr.ok) return {...base, at, status: "NOT_SSR", detail: `${at} — ${ssr.why}`};
+    }
+
+    // ③ 깨진 JSON-LD 는 없는 것보다 나쁘다.
+    if (target.kind === "PAGE" && target.page.ld.malformed.length > 0) {
+        return {...base, at, status: "MALFORMED_JSONLD", detail: `${at} 의 JSON-LD 파싱 실패 ${target.page.ld.malformed.length}건`};
+    }
+
+    return {...base, at, status: "PASS"};
+}
+
+/**
+ * siteWide 요건 — 라우트 축이 아니라 사이트 축이라 판정이 따로 산다.
+ *
+ * `requiredRoutePaths` 가 **null 이면 주장이 없는 것**(무주장 모드)이고, 빈 배열이면 주장은 있는데 그
+ * 라우트가 하나도 안 잡힌 것이다. 둘을 같게 다루면 `SITEMAP_COVERS` 가 "덮을 대상이 0건이라 통과"라는
+ * 공허한 PASS 를 찍는다 — 안 잰 것을 통과로 세지 않는 것이 이 검사기의 규율이다.
+ */
+function judgeSiteWide(req, requiredRoutePaths) {
+    const base = {id: req.id, bucket: "siteWide", check: req.check};
+    if (req.check === "SITEMAP_COVERS" && requiredRoutePaths === null) {
+        return {...base, status: "SKIPPED", detail: "보장 카테고리를 주장하지 않아 sitemap 이 덮어야 할 라우트가 정해지지 않는다"};
+    }
+    switch (req.check) {
+        case "ROBOTS_PRESENT":
+            return robotsTxt == null
+                ? {...base, status: "MISSING", detail: "/robots.txt 가 응답하지 않는다"}
+                : {...base, status: "PASS"};
+        case "SITEMAP_PRESENT":
+            return sitemapXml == null
+                ? {...base, status: "MISSING", detail: "/sitemap.xml 이 응답하지 않는다"}
+                : {...base, status: "PASS"};
+        case "SITEMAP_COVERS": {
+            if (sitemapXml == null) return {...base, status: "MISSING", detail: "sitemap 자체가 없다"};
+            const missing = requiredRoutePaths.filter((p) => !sitemapLocs.has(p));
+            return missing.length
+                ? {...base, status: "MISSING", detail: `sitemap 이 보장 라우트를 안 싣는다 — ${missing.join(", ")}`}
+                : {...base, status: "PASS"};
+        }
+        case "ABSOLUTE_URLS_IN_JSONLD": {
+            const bad = [];
+            for (const [path, page] of seen) {
+                for (const node of page.ld.nodes) {
+                    for (const key of ["url", "item", "@id"]) {
+                        const v = node[key];
+                        if (typeof v === "string" && v && !/^https?:\/\//i.test(v)) bad.push(`${path}: ${key}="${v}"`);
+                    }
+                }
+            }
+            return bad.length
+                ? {...base, status: "RELATIVE_URL", detail: `절대 URL 이 아니다 — ${bad.slice(0, 5).join(" · ")}`}
+                : {...base, status: "PASS"};
+        }
+        default:
+            return {...base, status: "ERROR", detail: `모르는 검사 종류 '${req.check}'`};
+    }
+}
+
+/** 부정 보장 — 나오면 실패다. 없는 것이 정답인 항목이라 '누락'으로 세면 안 된다. */
+function judgeNegative() {
+    const out = [];
+    for (const rule of spec.negative?.forbiddenTypes ?? []) {
+        const hits = [];
+        for (const [path, page] of seen) {
+            const pool = rule.scope === "ROOT_ONLY" ? page.ld.roots : page.ld.nodes;
+            for (const n of pool) {
+                if (n && typeof n === "object" && typesOf(n).includes(rule.type)) hits.push(path);
+            }
+        }
+        out.push(
+            hits.length
+                ? {id: `no-${rule.type}`, bucket: "negative", status: "FORBIDDEN_PRESENT", detail: `${rule.type} 가 나왔다 — ${[...new Set(hits)].join(", ")}`}
+                : {id: `no-${rule.type}`, bucket: "negative", status: "PASS"},
+        );
+    }
+    return out;
+}
+
+// ── 실행 ─────────────────────────────────────────────────────────────────────
+
+const FAIL_STATUSES = new Set(["MISSING_ROUTE", "MISSING_JSONLD", "MISSING_CHILD", "MISSING_PROPERTY", "NOT_SSR", "MALFORMED_JSONLD", "MISSING", "RELATIVE_URL", "FORBIDDEN_PRESENT", "ERROR"]);
+
+const results = [];
+
+if (siteWideOnly) {
+    /**
+     * 무주장 판정 — **사이트 축만**(memo123 §6.3). 카테고리 required·conditional·planned 는 물론
+     * `negative`(부정 보장)도 여기서는 안 잰다: 부정 보장은 "우리 어휘를 쓰는 팩이 자사 별점을 달지
+     * 않는다"는 우리 팩의 규율이고, 남의 사이트가 자기 후기 마크업을 어떻게 다는지는 우리가 판정할
+     * 자리가 아니다(전제 A). B-2 에서 주장 앵커가 생기면 그 사이트에는 잰다.
+     */
+    const surfaces = (spec.siteWide?.requirements ?? []).map((req) => judgeSiteWide(req, null));
+    const failed = surfaces.filter((s) => FAIL_STATUSES.has(s.status));
+    results.push({
+        category: null,
+        label: "사이트 축(무주장)",
+        shipState: null,
+        verdict: failed.length === 0 ? "PASS" : "FAIL",
+        surfaces,
+    });
+}
+
+for (const code of categories) {
+    const cat = byCategory.get(code);
+    const surfaces = [];
+
+    for (const s of cat.required ?? []) surfaces.push(judgeSurface(s, "required"));
+    for (const s of cat.conditional ?? []) {
+        const r = judgeSurface(s, "conditional");
+        // 조건부는 못 찾으면 SKIPPED — "섹션을 안 썼다"와 구별할 수 없다(§EVENT/faq-page why).
+        surfaces.push(r.status === "PASS" ? r : {...r, status: "SKIPPED", detail: `${r.detail ?? ""} (섹션 미사용일 수 있어 실패로 세지 않는다)`.trim()});
+    }
+    for (const s of cat.planned ?? []) {
+        const r = judgeSurface(s, "planned");
+        // planned 는 게이트가 아니라 T6 작업 지시서다.
+        surfaces.push(r.status === "PASS" ? {...r, status: "PLANNED_PRESENT"} : {...r, status: "PLANNED_MISSING", tranche: s.tranche ?? null});
+    }
+
+    // 이 카테고리가 보장하는 라우트의 실제 경로 — sitemap 커버리지 판정 입력.
+    const requiredRoutePaths = [];
+    for (const s of cat.required ?? []) {
+        const t = resolveRoute(s.route ?? "any");
+        if (t.kind === "PAGE") requiredRoutePaths.push(t.path);
+    }
+    for (const req of spec.siteWide?.requirements ?? []) surfaces.push(judgeSiteWide(req, [...new Set(requiredRoutePaths)]));
+    surfaces.push(...judgeNegative());
+
+    const gating = surfaces.filter((s) => s.bucket !== "planned" && s.bucket !== "conditional");
+    const failed = gating.filter((s) => FAIL_STATUSES.has(s.status));
+    results.push({
+        category: code,
+        label: cat.label ?? code,
+        shipState: cat.shipState,
+        verdict: failed.length === 0 ? "PASS" : "FAIL",
+        surfaces,
+    });
+}
+
+const snapshot = {
+    checker: "check-aeo-surfaces.mjs",
+    checkerVersion: CHECKER_VERSION,
+    /**
+     * 무엇을 잰 판정인가. `site-wide-only` 스냅샷은 **카테고리 판정이 아예 없어서** promote 입력으로 쓰면
+     * 보장 분류가 `passedFor` 에서 떨어진다(그게 맞다 — 안 잰 것을 통과로 셀 수 없다). 이 필드는 그 거절이
+     * "미충족"인지 "애초에 다른 검사"인지를 사후에 읽을 수 있게 남기는 자리다.
+     */
+    mode: siteWideOnly ? "site-wide-only" : "category",
+    guaranteesRev: spec.contractRev,
+    // 어느 출처의 잣대로 잰 판정인가 — rev 만으로는 "정본으로 쟀는지 운반본으로 쟀는지"가 안 남는다.
+    guaranteesSource: resolved.source,
+    themeCode,
+    themeVersion,
+    siteUrl,
+    checkedAt: new Date().toISOString(),
+    pagesCrawled: [...seen.keys()].sort(),
+    fetchFailures: crawled.fetchFailures,
+    verdict: results.every((r) => r.verdict === "PASS") ? "PASS" : "FAIL",
+    categories: results,
+};
+
+// ── 보고 ─────────────────────────────────────────────────────────────────────
+
+const MARK = {PASS: "✅", PLANNED_PRESENT: "✅", SKIPPED: "⏭️ ", PLANNED_MISSING: "📋"};
+console.log("");
+for (const r of results) {
+    console.log(`■ ${r.category ? `${r.category}(${r.label})` : r.label} — ${r.verdict}${r.shipState === "BLOCKED" ? " · 진열 차단(DON'T-SHIP)" : ""}`);
+    for (const s of r.surfaces) {
+        const mark = MARK[s.status] ?? "❌";
+        const tail = s.detail ? ` — ${s.detail}` : "";
+        const tranche = s.tranche ? ` [${s.tranche}]` : "";
+        console.log(`   ${mark} ${s.bucket}/${s.id}${tranche}: ${s.status}${tail}`);
+    }
+    console.log("");
+}
+
+if (outPath) {
+    mkdirSync(dirname(resolve(outPath)), {recursive: true});
+    writeFileSync(resolve(outPath), JSON.stringify(snapshot, null, 2) + "\n", "utf8");
+    console.log(`· 검사 스냅샷 → ${outPath}`);
+    console.log(
+        siteWideOnly
+            ? "  이 스냅샷은 **promote 입력이 아니다**(카테고리 판정 0건 — 사이트 축만 잰 결과다)."
+            : "  promote 입력으로 이 파일을 그대로 넘긴다(보장 카테고리 팩은 스냅샷 없이 promote 가 거부된다).",
+    );
+} else if (!siteWideOnly) {
+    console.log("· --out 을 안 줬다 — 스냅샷을 파일로 남겨야 promote 입력으로 쓸 수 있다.");
+}
+
+const planned = results.flatMap((r) => r.surfaces.filter((s) => s.status === "PLANNED_MISSING"));
+if (planned.length) {
+    console.log(`· 예정 표면 ${planned.length}건은 실패가 아니다 — 보장표가 목표로 적어 둔 T6 작업 목록이다.`);
+}
+
+process.exit(snapshot.verdict === "PASS" ? 0 : 1);