@wildo-ai/saas-website 1.1.1

package/src/schemas/structured-data/website-structured-data.shared.schemas.ts

@@ -0,0 +1,62 @@
+/**
+ * @wildo_source:part:start saas.website.structured-data.payload-shape facet:layer:shared facet:family:website
+ *
+ * `WebsiteStructuredDataPayload` — the runtime JSON-LD object shape returned
+ * by a section's `getStructuredData()` and serialized into one
+ * `<script type="application/ld+json">` block per payload.
+ *
+ * **Layering note** — the payload type is defined HERE (in the
+ * website runtime) rather than imported from the specification package because
+ * runtime rendering must remain independent from companion semantics. The
+ * application's Schema.org catalog describes the same vocabulary (per-`@type`
+ * required / optional / deprecated fields); the two contracts are structurally
+ * compatible by design but independently owned.
+ *
+ * **Authoring contract**:
+ *
+ * - `@type` REQUIRED — the Schema.org entity kind (`'Article'`,
+ *   `'BlogPosting'`, `'FAQPage'`, …). Typed as a free-form `string`
+ *   here (not a closed enum) so app-side catalog extensions
+ *   (e.g. `'SoftwareApplication'`, custom Schema.org-extension
+ *   `@type`s) are emittable without a saas-website release. The
+ *   companion's catalog reconciliation surface validates the
+ *   `@type` value against the merged engine + app catalog.
+ * - `@id?` OPTIONAL — a stable URI identifying the entity. Used for
+ *   cross-referencing on the same page (e.g. `Article.publisher`
+ *   referencing the page-level `Organization` via `@id`). The
+ *   renderer uses `@id` for deduplication: two payloads with the
+ *   same `@id` collapse into one emitted block (last-wins).
+ * - `@context?` OPTIONAL — the JSON-LD vocabulary URL. The renderer
+ *   auto-injects `'https://schema.org'` when omitted; the field is
+ *   exposed so consumers CAN override (Schema.org payload extended
+ *   with a custom vocabulary).
+ * - All other fields are pass-through `unknown` — the catalog
+ *   describes the FIELD NAMES per `@type`; the per-field SHAPE
+ *   (e.g. `Article.author` is a `Person | Organization`) is locked
+ *   at the section's payload-builder TS-side.
+ */
+export interface WebsiteStructuredDataPayload {
+  '@type': string;
+  '@id'?: string;
+  '@context'?: string | Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+/**
+ * Convenience union for `getStructuredData()` return types.
+ *
+ * A section may emit:
+ *   - a single payload (most common — `FAQPage` for an FAQ section);
+ *   - a fixed-length tuple of payloads (e.g. pricing emits `Product +
+ *     AggregateOffer` together);
+ *   - `null` / `undefined` when the section has no contribution for
+ *     the current state (e.g. an empty FAQ list);
+ *   - an empty array (semantically equivalent to `null`; the renderer
+ *     short-circuits both).
+ */
+export type WebsiteStructuredDataReturn =
+  | WebsiteStructuredDataPayload
+  | readonly WebsiteStructuredDataPayload[]
+  | null
+  | undefined;
+/** @wildo_source:part:end saas.website.structured-data.payload-shape */

package/src/schemas/validators/label-pack.validator.ts

@@ -0,0 +1,201 @@
+import type { WebsiteLabelKey } from '../label-keys/website-label-key.schemas';
+import type { WebsitePageManifest } from '../manifests/website-page-manifest.shared.schemas';
+import type { WebsiteSectionRef } from '../refs/section-ref.schemas';
+
+/**
+ * @wildo_source:part:start saas.website.label-pack.validator facet:layer:shared facet:family:website
+ *
+ * `LabelPack` — flat string→string map keyed by fully-composed
+ * `WebsiteLabelKey` (e.g. `"website.landing.hero.headline"` →
+ * `"Welcome to Wonder Todos"`). One pack per locale, loaded by the
+ * Astro adapter in Phase 5 from `website/src/i18n/<locale>.json`.
+ *
+ * Stored as a plain `Record<string, string>` rather than
+ * `Record<WebsiteLabelKey, string>` because runtime JSON parses to
+ * `Record<string, string>` and re-branding every key on load would
+ * cost O(N) parses per label-pack with no observable benefit (the
+ * validator below validates the keys against the manifest contract,
+ * which is the only meaningful guarantee).
+ */
+export type LabelPack = Record<string, string>;
+
+/**
+ * Map from a section's `WebsiteSectionRef` to the fully-composed label
+ * keys that section's `defineWebsiteSection({ expectedLabelKeys })`
+ * declared. Built either:
+ *   - **statically** at the site-config level (consumer hands the
+ *     validator a literal map collected from imported sections), or
+ *   - **at build time** by the Phase 5 collector
+ *     (`collect-expected-label-keys.ts`) walking every manifest's
+ *     `pageComponent` to discover the `defineWebsiteSection` calls
+ *     it composes.
+ *
+ * The validator itself is build-source-agnostic — it validates whatever
+ * map it is given against the manifest registry.
+ */
+export type ExpectedLabelKeysBySectionRef = Map<WebsiteSectionRef, readonly WebsiteLabelKey[]>;
+
+/**
+ * Output of `validateLabelPackAgainstManifest`. Three flat lists, no
+ * grouping by page/section because the diagnostics CLI / build-time
+ * reporter wants a single sorted list per failure category.
+ *
+ * **Type-precision rationale** for the three lists:
+ *
+ * - `missing` is `WebsiteLabelKey[]`: every entry was originally declared
+ *   in a section's `expectedLabelKeys`, which means it has already been
+ *   parsed through `WebsiteLabelKeySchema` at section-definition time —
+ *   the brand carries here legitimately.
+ * - `orphaned` is `string[]`: entries come from `Object.keys(pack)`,
+ *   i.e. arbitrary keys present in the loaded JSON. They have NOT been
+ *   parsed through `WebsiteLabelKeySchema` (in fact, malformed pack
+ *   keys are a common cause of orphans — typos, prefix mistakes,
+ *   missing segments). Branding these would be a type-system lie that
+ *   would let downstream code feed an orphan key into a
+ *   `WebsiteLabelKey`-typed API and blow up at runtime.
+ * - `unmappedSectionRefs` is `WebsiteSectionRef[]`: entries come from
+ *   `manifest.sectionRefs`, which were already parsed through
+ *   `WebsiteSectionRefSchema`.
+ */
+export interface LabelPackValidationResult {
+  /**
+   * Keys the manifest commits to (declared in any section's
+   * `expectedLabelKeys`) but absent from the provided pack. A non-empty
+   * `missing` list is a HARD ERROR — the build MUST fail.
+   */
+  missing: WebsiteLabelKey[];
+  /**
+   * Raw pack keys NOT declared by any section in any manifest. A
+   * non-empty `orphaned` list is a SOFT WARNING — orphaned keys are
+   * usually stale entries left behind by a section rename or deletion,
+   * and surfacing them eagerly keeps the pack lean. The build does NOT
+   * fail on orphaned keys (a consumer might author keys for a section
+   * they haven't shipped yet).
+   *
+   * Typed `string[]` (NOT `WebsiteLabelKey[]`) because pack keys
+   * have not been validated against `WebsiteLabelKeySchema`.
+   */
+  orphaned: string[];
+  /**
+   * Sections referenced by a manifest's `sectionRefs[]` whose
+   * `expectedLabelKeys` could not be resolved (the section was missing
+   * from the `expectedKeysBySectionRef` map). This is a build-pipeline
+   * configuration bug (the collector failed to discover the section's
+   * `defineWebsiteSection` call) — distinct from `missing`, which is a
+   * content authoring bug.
+   */
+  unmappedSectionRefs: WebsiteSectionRef[];
+}
+
+/**
+ * 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: readonly WebsitePageManifest[],
+  expectedKeysBySectionRef: ExpectedLabelKeysBySectionRef,
+  pack: LabelPack,
+  chromeLabelKeys: readonly WebsiteLabelKey[] = [],
+): LabelPackValidationResult {
+  const expected = new Set<string>();
+  const unmappedRefs = new Set<string>();
+
+  for (const manifest of manifests) {
+    expected.add(manifest.metaLabelKeys.titleKey as unknown as string);
+    expected.add(manifest.metaLabelKeys.descriptionKey as unknown as string);
+
+    for (const sectionRef of manifest.sectionRefs) {
+      const sectionKeys = expectedKeysBySectionRef.get(sectionRef);
+      if (sectionKeys === undefined) {
+        unmappedRefs.add(sectionRef as unknown as string);
+        continue;
+      }
+      for (const key of sectionKeys) {
+        expected.add(key as unknown as string);
+      }
+    }
+  }
+
+  for (const chromeKey of chromeLabelKeys) {
+    expected.add(chromeKey as unknown as string);
+  }
+
+  const packKeys = new Set(Object.keys(pack));
+
+  const missing: string[] = [];
+  for (const key of expected) {
+    if (!packKeys.has(key)) {
+      missing.push(key);
+    }
+  }
+
+  const orphaned: string[] = [];
+  for (const key of packKeys) {
+    if (!expected.has(key)) {
+      orphaned.push(key);
+    }
+  }
+
+  missing.sort();
+  orphaned.sort();
+  const unmappedSectionRefs = [...unmappedRefs].sort();
+
+  return {
+    missing: missing as WebsiteLabelKey[],
+    orphaned,
+    unmappedSectionRefs: unmappedSectionRefs as unknown as WebsiteSectionRef[],
+  };
+}
+/** @wildo_source:part:end saas.website.label-pack.validator */