@wildo-ai/saas-website 1.1.1

package/dist/esm/schemas/validators/label-pack.validator.js

@@ -0,0 +1,100 @@
+/**
+ * Pure label-pack validator. Cross-references the keys declared by
+ * every section across every page manifest against the keys present
+ * in the supplied pack.
+ *
+ * **Algorithm**:
+ *   1. Walk every manifest's `sectionRefs` and look up
+ *      `expectedKeysBySectionRef.get(sectionRef)`. Sections whose ref
+ *      appears in a manifest but is missing from the map are
+ *      surfaced as a separate diagnostic (`unmappedSectionRefs`); the
+ *      validator does NOT silently treat an unmapped section as
+ *      "no expected keys".
+ *   2. Add every page's `metaLabelKeys.titleKey` and
+ *      `metaLabelKeys.descriptionKey` to the expected set (these are
+ *      page-level keys, not section-scoped).
+ *   3. `missing` = expected ∖ pack-keys.
+ *   4. `orphaned` = pack-keys ∖ expected.
+ *   5. Both lists are sorted lexicographically for deterministic
+ *      diagnostic output.
+ *
+ * **Why `unmappedSectionRefs` is a third bucket** (not folded into
+ * `missing`): "I don't know what keys this section needs" is a
+ * different failure mode from "I know the section needs `headline`
+ * and you didn't provide it". The first is a build-pipeline
+ * configuration bug (the collector didn't see the section); the
+ * second is a content authoring bug. Keeping them distinct makes the
+ * diagnostic actionable.
+ *
+ * **Pure / no I/O**: the validator does not read files, does not boot
+ * React, does not require Astro. It accepts already-parsed data
+ * structures and returns a result object. This keeps it usable from:
+ *   - the Astro build hook (Phase 5),
+ *   - the `wildo website audit` CLI (Phase 7),
+ *   - companion subprocesses,
+ *   - unit tests.
+ *
+ * @param manifests Every `WebsitePageManifest` registered on the site.
+ *                  Typically `WebsiteRootConfig.pageManifests`.
+ * @param expectedKeysBySectionRef Map from sectionRef to the fully-
+ *                                  composed keys that section commits to.
+ * @param pack The locale's loaded label pack.
+ * @param chromeLabelKeys OPTIONAL. The fully-composed keys read by
+ *                        site-wide chrome (header / footer / any slot
+ *                        rendered outside a section context). Declared
+ *                        on `WebsiteRootConfig.chromeLabelKeys` because
+ *                        chrome cannot register `expectedLabelKeys` via
+ *                        `defineWebsiteSection` (it lives outside the
+ *                        page+section context). Without this list, every
+ *                        `website.chrome.*` entry would surface as an
+ *                        orphan warning on every build. Defaults to `[]`
+ *                        — sites with no chrome label reads omit the
+ *                        argument entirely.
+ * @returns `LabelPackValidationResult` with three diagnostic buckets:
+ *          `missing` (hard error), `orphaned` (soft warning), and
+ *          `unmappedSectionRefs` (build-pipeline configuration bug).
+ */
+export function validateLabelPackAgainstManifest(manifests, expectedKeysBySectionRef, pack, chromeLabelKeys = []) {
+    const expected = new Set();
+    const unmappedRefs = new Set();
+    for (const manifest of manifests) {
+        expected.add(manifest.metaLabelKeys.titleKey);
+        expected.add(manifest.metaLabelKeys.descriptionKey);
+        for (const sectionRef of manifest.sectionRefs) {
+            const sectionKeys = expectedKeysBySectionRef.get(sectionRef);
+            if (sectionKeys === undefined) {
+                unmappedRefs.add(sectionRef);
+                continue;
+            }
+            for (const key of sectionKeys) {
+                expected.add(key);
+            }
+        }
+    }
+    for (const chromeKey of chromeLabelKeys) {
+        expected.add(chromeKey);
+    }
+    const packKeys = new Set(Object.keys(pack));
+    const missing = [];
+    for (const key of expected) {
+        if (!packKeys.has(key)) {
+            missing.push(key);
+        }
+    }
+    const orphaned = [];
+    for (const key of packKeys) {
+        if (!expected.has(key)) {
+            orphaned.push(key);
+        }
+    }
+    missing.sort();
+    orphaned.sort();
+    const unmappedSectionRefs = [...unmappedRefs].sort();
+    return {
+        missing: missing,
+        orphaned,
+        unmappedSectionRefs: unmappedSectionRefs,
+    };
+}
+/** @wildo_source:part:end saas.website.label-pack.validator */
+//# sourceMappingURL=label-pack.validator.js.map

package/dist/esm/schemas/validators/label-pack.validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"label-pack.validator.js","sourceRoot":"","sources":["../../../../../src/schemas/validators/label-pack.validator.ts"],"names":[],"mappings":"AAyFA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,MAAM,UAAU,gCAAgC,CAC9C,SAAyC,EACzC,wBAAuD,EACvD,IAAe,EACf,kBAA8C,EAAE;IAEhD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IACnC,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;IAEvC,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,aAAa,CAAC,QAA6B,CAAC,CAAC;QACnE,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,aAAa,CAAC,cAAmC,CAAC,CAAC;QAEzE,KAAK,MAAM,UAAU,IAAI,QAAQ,CAAC,WAAW,EAAE,CAAC;YAC9C,MAAM,WAAW,GAAG,wBAAwB,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YAC7D,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;gBAC9B,YAAY,CAAC,GAAG,CAAC,UAA+B,CAAC,CAAC;gBAClD,SAAS;YACX,CAAC;YACD,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;gBAC9B,QAAQ,CAAC,GAAG,CAAC,GAAwB,CAAC,CAAC;YACzC,CAAC;QACH,CAAC;IACH,CAAC;IAED,KAAK,MAAM,SAAS,IAAI,eAAe,EAAE,CAAC;QACxC,QAAQ,CAAC,GAAG,CAAC,SAA8B,CAAC,CAAC;IAC/C,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAE5C,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACvB,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACvB,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IAED,OAAO,CAAC,IAAI,EAAE,CAAC;IACf,QAAQ,CAAC,IAAI,EAAE,CAAC;IAChB,MAAM,mBAAmB,GAAG,CAAC,GAAG,YAAY,CAAC,CAAC,IAAI,EAAE,CAAC;IAErD,OAAO;QACL,OAAO,EAAE,OAA4B;QACrC,QAAQ;QACR,mBAAmB,EAAE,mBAAqD;KAC3E,CAAC;AACJ,CAAC;AACD,+DAA+D","sourcesContent":["import type { WebsiteLabelKey } from '../label-keys/website-label-key.schemas';\nimport type { WebsitePageManifest } from '../manifests/website-page-manifest.shared.schemas';\nimport type { WebsiteSectionRef } from '../refs/section-ref.schemas';\n\n/**\n * @wildo_source:part:start saas.website.label-pack.validator facet:layer:shared facet:family:website\n *\n * `LabelPack` — flat string→string map keyed by fully-composed\n * `WebsiteLabelKey` (e.g. `\"website.landing.hero.headline\"` →\n * `\"Welcome to Wonder Todos\"`). One pack per locale, loaded by the\n * Astro adapter in Phase 5 from `website/src/i18n/<locale>.json`.\n *\n * Stored as a plain `Record<string, string>` rather than\n * `Record<WebsiteLabelKey, string>` because runtime JSON parses to\n * `Record<string, string>` and re-branding every key on load would\n * cost O(N) parses per label-pack with no observable benefit (the\n * validator below validates the keys against the manifest contract,\n * which is the only meaningful guarantee).\n */\nexport type LabelPack = Record<string, string>;\n\n/**\n * Map from a section's `WebsiteSectionRef` to the fully-composed label\n * keys that section's `defineWebsiteSection({ expectedLabelKeys })`\n * declared. Built either:\n *   - **statically** at the site-config level (consumer hands the\n *     validator a literal map collected from imported sections), or\n *   - **at build time** by the Phase 5 collector\n *     (`collect-expected-label-keys.ts`) walking every manifest's\n *     `pageComponent` to discover the `defineWebsiteSection` calls\n *     it composes.\n *\n * The validator itself is build-source-agnostic — it validates whatever\n * map it is given against the manifest registry.\n */\nexport type ExpectedLabelKeysBySectionRef = Map<WebsiteSectionRef, readonly WebsiteLabelKey[]>;\n\n/**\n * Output of `validateLabelPackAgainstManifest`. Three flat lists, no\n * grouping by page/section because the diagnostics CLI / build-time\n * reporter wants a single sorted list per failure category.\n *\n * **Type-precision rationale** for the three lists:\n *\n * - `missing` is `WebsiteLabelKey[]`: every entry was originally declared\n *   in a section's `expectedLabelKeys`, which means it has already been\n *   parsed through `WebsiteLabelKeySchema` at section-definition time —\n *   the brand carries here legitimately.\n * - `orphaned` is `string[]`: entries come from `Object.keys(pack)`,\n *   i.e. arbitrary keys present in the loaded JSON. They have NOT been\n *   parsed through `WebsiteLabelKeySchema` (in fact, malformed pack\n *   keys are a common cause of orphans — typos, prefix mistakes,\n *   missing segments). Branding these would be a type-system lie that\n *   would let downstream code feed an orphan key into a\n *   `WebsiteLabelKey`-typed API and blow up at runtime.\n * - `unmappedSectionRefs` is `WebsiteSectionRef[]`: entries come from\n *   `manifest.sectionRefs`, which were already parsed through\n *   `WebsiteSectionRefSchema`.\n */\nexport interface LabelPackValidationResult {\n  /**\n   * Keys the manifest commits to (declared in any section's\n   * `expectedLabelKeys`) but absent from the provided pack. A non-empty\n   * `missing` list is a HARD ERROR — the build MUST fail.\n   */\n  missing: WebsiteLabelKey[];\n  /**\n   * Raw pack keys NOT declared by any section in any manifest. A\n   * non-empty `orphaned` list is a SOFT WARNING — orphaned keys are\n   * usually stale entries left behind by a section rename or deletion,\n   * and surfacing them eagerly keeps the pack lean. The build does NOT\n   * fail on orphaned keys (a consumer might author keys for a section\n   * they haven't shipped yet).\n   *\n   * Typed `string[]` (NOT `WebsiteLabelKey[]`) because pack keys\n   * have not been validated against `WebsiteLabelKeySchema`.\n   */\n  orphaned: string[];\n  /**\n   * Sections referenced by a manifest's `sectionRefs[]` whose\n   * `expectedLabelKeys` could not be resolved (the section was missing\n   * from the `expectedKeysBySectionRef` map). This is a build-pipeline\n   * configuration bug (the collector failed to discover the section's\n   * `defineWebsiteSection` call) — distinct from `missing`, which is a\n   * content authoring bug.\n   */\n  unmappedSectionRefs: WebsiteSectionRef[];\n}\n\n/**\n * Pure label-pack validator. Cross-references the keys declared by\n * every section across every page manifest against the keys present\n * in the supplied pack.\n *\n * **Algorithm**:\n *   1. Walk every manifest's `sectionRefs` and look up\n *      `expectedKeysBySectionRef.get(sectionRef)`. Sections whose ref\n *      appears in a manifest but is missing from the map are\n *      surfaced as a separate diagnostic (`unmappedSectionRefs`); the\n *      validator does NOT silently treat an unmapped section as\n *      \"no expected keys\".\n *   2. Add every page's `metaLabelKeys.titleKey` and\n *      `metaLabelKeys.descriptionKey` to the expected set (these are\n *      page-level keys, not section-scoped).\n *   3. `missing` = expected ∖ pack-keys.\n *   4. `orphaned` = pack-keys ∖ expected.\n *   5. Both lists are sorted lexicographically for deterministic\n *      diagnostic output.\n *\n * **Why `unmappedSectionRefs` is a third bucket** (not folded into\n * `missing`): \"I don't know what keys this section needs\" is a\n * different failure mode from \"I know the section needs `headline`\n * and you didn't provide it\". The first is a build-pipeline\n * configuration bug (the collector didn't see the section); the\n * second is a content authoring bug. Keeping them distinct makes the\n * diagnostic actionable.\n *\n * **Pure / no I/O**: the validator does not read files, does not boot\n * React, does not require Astro. It accepts already-parsed data\n * structures and returns a result object. This keeps it usable from:\n *   - the Astro build hook (Phase 5),\n *   - the `wildo website audit` CLI (Phase 7),\n *   - companion subprocesses,\n *   - unit tests.\n *\n * @param manifests Every `WebsitePageManifest` registered on the site.\n *                  Typically `WebsiteRootConfig.pageManifests`.\n * @param expectedKeysBySectionRef Map from sectionRef to the fully-\n *                                  composed keys that section commits to.\n * @param pack The locale's loaded label pack.\n * @param chromeLabelKeys OPTIONAL. The fully-composed keys read by\n *                        site-wide chrome (header / footer / any slot\n *                        rendered outside a section context). Declared\n *                        on `WebsiteRootConfig.chromeLabelKeys` because\n *                        chrome cannot register `expectedLabelKeys` via\n *                        `defineWebsiteSection` (it lives outside the\n *                        page+section context). Without this list, every\n *                        `website.chrome.*` entry would surface as an\n *                        orphan warning on every build. Defaults to `[]`\n *                        — sites with no chrome label reads omit the\n *                        argument entirely.\n * @returns `LabelPackValidationResult` with three diagnostic buckets:\n *          `missing` (hard error), `orphaned` (soft warning), and\n *          `unmappedSectionRefs` (build-pipeline configuration bug).\n */\nexport function validateLabelPackAgainstManifest(\n  manifests: readonly WebsitePageManifest[],\n  expectedKeysBySectionRef: ExpectedLabelKeysBySectionRef,\n  pack: LabelPack,\n  chromeLabelKeys: readonly WebsiteLabelKey[] = [],\n): LabelPackValidationResult {\n  const expected = new Set<string>();\n  const unmappedRefs = new Set<string>();\n\n  for (const manifest of manifests) {\n    expected.add(manifest.metaLabelKeys.titleKey as unknown as string);\n    expected.add(manifest.metaLabelKeys.descriptionKey as unknown as string);\n\n    for (const sectionRef of manifest.sectionRefs) {\n      const sectionKeys = expectedKeysBySectionRef.get(sectionRef);\n      if (sectionKeys === undefined) {\n        unmappedRefs.add(sectionRef as unknown as string);\n        continue;\n      }\n      for (const key of sectionKeys) {\n        expected.add(key as unknown as string);\n      }\n    }\n  }\n\n  for (const chromeKey of chromeLabelKeys) {\n    expected.add(chromeKey as unknown as string);\n  }\n\n  const packKeys = new Set(Object.keys(pack));\n\n  const missing: string[] = [];\n  for (const key of expected) {\n    if (!packKeys.has(key)) {\n      missing.push(key);\n    }\n  }\n\n  const orphaned: string[] = [];\n  for (const key of packKeys) {\n    if (!expected.has(key)) {\n      orphaned.push(key);\n    }\n  }\n\n  missing.sort();\n  orphaned.sort();\n  const unmappedSectionRefs = [...unmappedRefs].sort();\n\n  return {\n    missing: missing as WebsiteLabelKey[],\n    orphaned,\n    unmappedSectionRefs: unmappedSectionRefs as unknown as WebsiteSectionRef[],\n  };\n}\n/** @wildo_source:part:end saas.website.label-pack.validator */\n"]}