@zalkera/client 0.24.2 → 0.24.4

package/bin/check-aeo-surfaces.mjs

@@ -188,7 +188,8 @@ function isInternalHost(host) {
  *   이미 적어 두었다.
  */
 function embeddedIPv4(host) {
-    // ⚠ `::` 는 **접두가 없는** 형태라 마지막에 둔다 — 앞에 두면 `::ffff:` 를 그것으로 먼저 삼킨다.
+    // `::` 는 **접두가 없는** 형태라 마지막에 둔다. (JS 정규식 교대는 백트래킹하므로 앞에 둬도
+    // 결과는 같다 — 실측으로 7개 프로브 전부 동일. 읽는 사람이 「좁은 것부터」로 읽게 두는 배치다.)
     const PREFIX = "(?:::ffff:|64:ff9b::|::)";
     const dotted = new RegExp(`^${PREFIX}(\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3})$`, "i").exec(host);
     if (dotted) return dotted[1];

package/bin/validate-storefront.mjs

@@ -1926,17 +1926,29 @@ function echoValue(value) {
  * 위치(`at position N` · `line L column C`)는 남긴다 — 고치는 사람이 어디를 볼지 알아야 한다.
  * 그 숫자는 내용이 아니다.
  */
+/**
+ * JSON 의 **구조 문자**. 이것만 반려문에 실어도 내용이 새지 않는다 — 값에는 못 나오는 글자들이다
+ * (따옴표 안이면 파싱이 안 깨지고, 깨졌다는 것은 그 자리가 구조라는 뜻이다).
+ */
+const STRUCTURAL_JSON = new Set([",", ":", "{", "}", "[", "]", '"', "'", " ", "\t", "\n", "\r"]);
+
 function parseWhere(error) {
     const raw = String(error?.message ?? "");
     const where = /(?:at position \d+(?:\s*\(line \d+ column \d+\))?|line \d+ column \d+)/.exec(raw);
-    // ⚠ **어느 글자에서 걸렸는지만** 남긴다. Node 는 그 글자를 따옴표로 싸서 주는데, 그 한 글자는
-    //    구조 정보(쉼표·중괄호)이지 내용이 아니다. 그 **뒤**에 붙는 `..."조각"` 이 위험한 부분이다.
-    const token = /^Unexpected token ('.'|".")/.exec(raw);
-    const head = token
-        ? `예상하지 못한 글자 ${token[1]}`
-        : /Unexpected end of JSON input/.test(raw)
-          ? "내용이 도중에 끝났습니다"
-          : "형식이 올바르지 않습니다";
+    // ⚠ **걸린 글자는 구조 문자일 때만 싣는다.** 「그 한 글자는 구조 정보이지 내용이 아니다」는
+    //    **거짓이다** — 값이 따옴표 없이 적혀 있으면 그 글자는 **값의 첫 글자**다(실측: 시크릿을
+    //    비인용으로 두면 그 첫 글자가 반려문에 실린다). 회당 한 글자라도 여기서 내보내지 않는다.
+    //    구조 문자면 그대로 두는 이유: 「쉼표가 하나 더 있습니다」는 고치는 사람에게 실제로 쓸모가 있다.
+    const token = /^Unexpected token ('(.)'|"(.)")/.exec(raw);
+    const glyph = token ? (token[2] ?? token[3]) : null;
+    const head =
+        glyph !== null && STRUCTURAL_JSON.has(glyph)
+            ? `예상하지 못한 글자 '${glyph}'`
+            : glyph !== null
+              ? "값이 따옴표 없이 적혀 있거나 표기가 잘못됐습니다"
+              : /Unexpected end of JSON input/.test(raw)
+                ? "내용이 도중에 끝났습니다"
+                : "형식이 올바르지 않습니다";
     return where ? `${head} (${where[0]})` : head;
 }
 
@@ -2957,15 +2969,52 @@ function checkSectionCoverage() {
     const src = readSafe(rendererPath, "섹션 렌더러 계약 검사");
     if (src === null) return;
     const cases = new Set([...src.matchAll(/case\s+"([A-Z_]+)"/g)].map((m) => m[1]));
-    const missing = contract.map((c) => c.type).filter((t) => !cases.has(t));
+
+    // ⚠ **계약 전량이 아니라 「이 사이트가 실제로 쓰는 타입」을 잰다.**
+    //
+    //   전량을 재면 **계약에 타입이 하나 추가되는 순간** 그것을 안 그리는 기존 사이트가 전부
+    //   관문에서 막힌다(`servingSink` 는 관문 모드에서 error 다). 계약이 약속한 「타입 추가는
+    //   구 스토어프론트를 깨지 않는다」와 정면으로 어긋나고, 실제로 막히는 시점은 그 사이트가
+    //   새 client 를 받는 때라 원인을 되짚기도 어렵다.
+    //
+    //   여기서 잡아야 하는 사고는 「콘솔에서 넣었는데 화면에 안 나온다」이고, 그것은 **콘텐츠가
+    //   그 타입을 쓸 때만** 성립한다. 어휘 전량 커버는 팩 정본이 자기 시험으로 지킬 일이다.
+    const known = new Set(contract.map((c) => c.type));
+    const used = usedSectionTypes(repoRootDir).filter((t) => known.has(t));
+    const missing = [...new Set(used)].filter((t) => !cases.has(t));
     if (missing.length > 0) {
         servingSink().push(
-            `[C2] SectionRenderer 가 계약의 ${missing.join("·")} 를 안 그린다 — 미지 타입은 조용히 스킵되므로 ` +
-                `콘솔에서 넣어도 화면에 안 나온다. case 를 추가하거나, 의도적 미지원이면 그 사유를 커밋에 남겨라.`,
+            `[C2] SectionRenderer 가 콘텐츠가 쓰는 ${missing.join("·")} 를 안 그린다 — 미지 타입은 조용히 ` +
+                `스킵되므로 콘솔에서 넣어도 화면에 안 나온다. case 를 추가하거나, 의도적 미지원이면 그 사유를 커밋에 남겨라.`,
         );
     }
 }
 
+/**
+ * `content/pages/*.json` 이 실제로 쓰는 섹션 타입.
+ *
+ * 못 읽거나 깨진 파일은 **여기서 말하지 않는다** — N2·N4 가 그 일을 한다. 이 함수는 「무엇을
+ * 쓰는가」만 답하고, 모르면 조용히 뺀다(모르는 것을 「쓴다」고 세면 없는 결함을 만든다).
+ */
+function usedSectionTypes(repoRoot) {
+    const out = [];
+    for (const file of contentPageFiles(repoRoot)) {
+        let page;
+        try {
+            page = JSON.parse(readFileSync(file, "utf8"));
+        } catch {
+            continue;
+        }
+        const sections = page?.sections;
+        if (!Array.isArray(sections)) continue;
+        for (const section of sections) {
+            const type = section?.type;
+            if (typeof type === "string" && type.trim() !== "") out.push(type.trim());
+        }
+    }
+    return out;
+}
+
 /*
  * ── N1~N5 : 콘텐츠 파일 계약 ────────────────────────────────────────────────
  *

package/package.json

@@ -1,75 +1,75 @@
 {
-    "name": "@zalkera/client",
-    "version": "0.24.2",
-    "description": "zalkera 헤드리스 CMS 공개 API 클라이언트 (테넌트 사이트용)",
-    "license": "MIT",
-    "author": "Credium Co., Ltd.",
-    "type": "module",
-    "publishConfig": {
-        "access": "public"
+  "name": "@zalkera/client",
+  "version": "0.24.4",
+  "description": "zalkera 헤드리스 CMS 공개 API 클라이언트 (테넌트 사이트용)",
+  "license": "MIT",
+  "author": "Credium Co., Ltd.",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "zalkera",
+    "headless",
+    "commerce",
+    "cms",
+    "api-client",
+    "sdk"
+  ],
+  "homepage": "https://zalkera.com",
+  "files": [
+    "dist",
+    "llms.txt",
+    "contracts",
+    "bin/validate-storefront.mjs",
+    "bin/check-aeo-surfaces.mjs",
+    "lib",
+    "!dist/*.map"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "zalkera-aeo-check": "./bin/check-aeo-surfaces.mjs",
+    "zalkera-validate": "./bin/validate-storefront.mjs"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
     },
-    "keywords": [
-        "zalkera",
-        "headless",
-        "commerce",
-        "cms",
-        "api-client",
-        "sdk"
-    ],
-    "homepage": "https://zalkera.com",
-    "files": [
-        "dist",
-        "llms.txt",
-        "contracts",
-        "bin/validate-storefront.mjs",
-        "bin/check-aeo-surfaces.mjs",
-        "lib",
-        "!dist/*.map"
-    ],
-    "main": "./dist/index.cjs",
-    "module": "./dist/index.js",
-    "types": "./dist/index.d.ts",
-    "bin": {
-        "zalkera-aeo-check": "./bin/check-aeo-surfaces.mjs",
-        "zalkera-validate": "./bin/validate-storefront.mjs"
-    },
-    "exports": {
-        ".": {
-            "import": {
-                "types": "./dist/index.d.ts",
-                "default": "./dist/index.js"
-            },
-            "require": {
-                "types": "./dist/index.d.cts",
-                "default": "./dist/index.cjs"
-            }
-        },
-        "./contracts/aeo-surface-guarantees.json": "./contracts/aeo-surface-guarantees.json",
-        "./bin/check-aeo-surfaces.mjs": "./bin/check-aeo-surfaces.mjs",
-        "./bin/validate-storefront.mjs": "./bin/validate-storefront.mjs",
-        "./lib/site-crawl.mjs": "./lib/site-crawl.mjs"
-    },
-    "scripts": {
-        "build": "tsup",
-        "dev": "tsup --watch",
-        "typecheck": "tsc --noEmit",
-        "test": "vitest run",
-        "test:watch": "vitest",
-        "prepublishOnly": "npm run build && npm run check:tarball && npm run format:check && npm run typecheck && npm test && npm run check:published",
-        "check:published": "node scripts/check-published-drift.mjs",
-        "format": "prettier --write \"src/**/*.ts\" \"scripts/**/*.mjs\" \"bin/**/*.mjs\"",
-        "format:check": "prettier --check \"src/**/*.ts\" \"scripts/**/*.mjs\" \"bin/**/*.mjs\"",
-        "check:tarball": "node scripts/check-tarball.mjs"
-    },
-    "engines": {
-        "node": ">=18"
-    },
-    "devDependencies": {
-        "@types/node": "^22.10.2",
-        "prettier": "^3.9.6",
-        "tsup": "^8.3.5",
-        "typescript": "^5.7.2",
-        "vitest": "^2.1.8"
-    },
-    "sideEffects": false
+    "./contracts/aeo-surface-guarantees.json": "./contracts/aeo-surface-guarantees.json",
+    "./bin/check-aeo-surfaces.mjs": "./bin/check-aeo-surfaces.mjs",
+    "./bin/validate-storefront.mjs": "./bin/validate-storefront.mjs",
+    "./lib/site-crawl.mjs": "./lib/site-crawl.mjs"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build && npm run check:tarball && npm run format:check && npm run typecheck && npm test && npm run check:published",
+    "check:published": "node scripts/check-published-drift.mjs",
+    "format": "prettier --write \"src/**/*.ts\" \"scripts/**/*.mjs\" \"bin/**/*.mjs\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"scripts/**/*.mjs\" \"bin/**/*.mjs\"",
+    "check:tarball": "node scripts/check-tarball.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "prettier": "^3.9.6",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "sideEffects": false
 }