@wildo-ai/saas-website 1.1.1

package/src/schemas/__tests__/structured-data-reconciliation.test.ts

@@ -0,0 +1,543 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  reconcileStructuredDataAgainstCatalog,
+  type StructuredDataCatalogEntry,
+  type StructuredDataReconciliationFinding,
+} from '../structured-data/structured-data-reconciliation.shared';
+
+function createCatalogEntry(
+  entry: Partial<StructuredDataCatalogEntry> & Pick<StructuredDataCatalogEntry, '@type'>,
+): StructuredDataCatalogEntry {
+  return {
+    requiredFields: [],
+    optionalFields: [],
+    deprecatedFields: [],
+    recommendOptionals: false,
+    ...entry,
+  };
+}
+
+function findFinding(
+  findings: readonly StructuredDataReconciliationFinding[],
+  kind: StructuredDataReconciliationFinding['kind'],
+): StructuredDataReconciliationFinding | undefined {
+  return findings.find((finding) => finding.kind === kind);
+}
+
+describe('reconcileStructuredDataAgainstCatalog', () => {
+  it('reports duplicate catalog entries as catalog-override findings and still validates with last-wins semantics', () => {
+    const result = reconcileStructuredDataAgainstCatalog({
+      catalog: [
+        createCatalogEntry({
+          '@type': 'Product',
+          requiredFields: ['name'],
+        }),
+        createCatalogEntry({
+          '@type': 'Product',
+          requiredFields: ['sku'],
+        }),
+      ],
+      pages: [
+        {
+          ref: 'pricing',
+          routePath: '/pricing',
+          sectionRefs: ['pricing-card'],
+        },
+      ],
+      sections: [
+        {
+          sectionRef: 'pricing-card',
+          getStructuredData: () => ({
+            '@type': 'Product',
+            sku: 'pro',
+          }),
+        },
+      ],
+    });
+
+    expect(findFinding(result.findings, 'catalog-override')).toMatchObject({
+      kind: 'catalog-override',
+      entityType: 'Product',
+      count: 2,
+    });
+    expect(
+      result.findings.some(
+        (finding) => finding.kind === 'spec-violation' && finding.code === 'missing-required-field',
+      ),
+    ).toBe(false);
+  });
+
+  it('reports catalog-miss findings when a section emits an unknown @type', () => {
+    const result = reconcileStructuredDataAgainstCatalog({
+      catalog: [createCatalogEntry({ '@type': 'Product' })],
+      pages: [
+        {
+          ref: 'pricing',
+          routePath: '/pricing',
+          sectionRefs: ['pricing-card'],
+        },
+      ],
+      sections: [
+        {
+          sectionRef: 'pricing-card',
+          getStructuredData: () => ({
+            '@type': 'SoftwareApplication',
+            name: 'Wonder Todos',
+          }),
+        },
+      ],
+    });
+
+    expect(findFinding(result.findings, 'catalog-miss')).toMatchObject({
+      kind: 'catalog-miss',
+      pageRef: 'pricing',
+      routePath: '/pricing',
+      sectionRef: 'pricing-card',
+      entityType: 'SoftwareApplication',
+    });
+  });
+
+  it('validates page-level structured-data payloads alongside section payloads', () => {
+    const result = reconcileStructuredDataAgainstCatalog({
+      catalog: [
+        createCatalogEntry({
+          '@type': 'BlogPosting',
+          requiredFields: ['headline'],
+        }),
+      ],
+      pages: [
+        {
+          ref: 'blog-post',
+          routePath: '/blog/example',
+          sectionRefs: [],
+        },
+      ],
+      sections: [],
+      pagePayloads: [
+        {
+          pageRef: 'blog-post',
+          routePath: '/blog/example',
+          sourceRef: 'page:blog-post:example',
+          payloads: {
+            '@type': 'BlogPosting',
+            headline: 'Example post',
+          },
+        },
+      ],
+    });
+
+    expect(result.findings).toEqual([]);
+    expect(result.pages).toEqual([
+      {
+        pageRef: 'blog-post',
+        routePath: '/blog/example',
+        payloadCount: 1,
+        findingCount: 0,
+      },
+    ]);
+  });
+
+  it('isolates page-level payload validation by concrete routePath for templated pages', () => {
+    const result = reconcileStructuredDataAgainstCatalog({
+      catalog: [
+        createCatalogEntry({
+          '@type': 'Review',
+          requiredFields: ['itemReviewed'],
+        }),
+        createCatalogEntry({
+          '@type': 'Product',
+          requiredFields: ['name'],
+        }),
+      ],
+      pages: [
+        {
+          ref: 'blog-post',
+          routePath: '/blog/[slug]',
+          sectionRefs: [],
+        },
+      ],
+      sections: [],
+      pagePayloads: [
+        {
+          pageRef: 'blog-post',
+          routePath: '/blog/a',
+          sourceRef: 'page:blog-post:a',
+          payloads: {
+            '@type': 'Review',
+            itemReviewed: {
+              '@id': 'https://example.test/blog/b#product',
+            },
+          },
+        },
+        {
+          pageRef: 'blog-post',
+          routePath: '/blog/b',
+          sourceRef: 'page:blog-post:b',
+          payloads: {
+            '@type': 'Product',
+            '@id': 'https://example.test/blog/b#product',
+            name: 'Post B product',
+          },
+        },
+      ],
+    });
+
+    expect(result.findings).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          kind: 'cross-entity-reference-drift',
+          routePath: '/blog/a',
+          missingReferenceId: 'https://example.test/blog/b#product',
+        }),
+      ]),
+    );
+    expect(result.pages.map((page) => page.routePath)).toEqual(['/blog/a', '/blog/b']);
+  });
+
+  it('merges templated section payloads into each concrete page-level route', () => {
+    const result = reconcileStructuredDataAgainstCatalog({
+      catalog: [
+        createCatalogEntry({
+          '@type': 'Review',
+          requiredFields: ['itemReviewed'],
+        }),
+        createCatalogEntry({
+          '@type': 'Product',
+          requiredFields: ['name'],
+        }),
+      ],
+      pages: [
+        {
+          ref: 'blog-post',
+          routePath: '/blog/[slug]',
+          sectionRefs: ['blog-product'],
+        },
+      ],
+      sections: [
+        {
+          sectionRef: 'blog-product',
+          getStructuredData: () => ({
+            '@type': 'Product',
+            '@id': 'https://example.test/blog/a#product',
+            name: 'Post A product',
+          }),
+        },
+      ],
+      pagePayloads: [
+        {
+          pageRef: 'blog-post',
+          routePath: '/blog/a',
+          sourceRef: 'page:blog-post:a',
+          payloads: {
+            '@type': 'Review',
+            itemReviewed: {
+              '@id': 'https://example.test/blog/a#product',
+            },
+          },
+        },
+      ],
+    });
+
+    expect(result.findings).toEqual([]);
+    expect(result.pages).toEqual([
+      {
+        pageRef: 'blog-post',
+        routePath: '/blog/a',
+        payloadCount: 2,
+        findingCount: 0,
+      },
+    ]);
+  });
+
+  it('keeps templated section payloads when page-level payload routePath is omitted', () => {
+    const result = reconcileStructuredDataAgainstCatalog({
+      catalog: [
+        createCatalogEntry({
+          '@type': 'Review',
+          requiredFields: ['itemReviewed'],
+        }),
+        createCatalogEntry({
+          '@type': 'Product',
+          requiredFields: ['name'],
+        }),
+      ],
+      pages: [
+        {
+          ref: 'blog-post',
+          routePath: '/blog/[slug]',
+          sectionRefs: ['blog-product'],
+        },
+      ],
+      sections: [
+        {
+          sectionRef: 'blog-product',
+          getStructuredData: () => ({
+            '@type': 'Product',
+            '@id': 'https://example.test/blog/template#product',
+            name: 'Template product',
+          }),
+        },
+      ],
+      pagePayloads: [
+        {
+          pageRef: 'blog-post',
+          sourceRef: 'page:blog-post:template',
+          payloads: {
+            '@type': 'Review',
+            itemReviewed: {
+              '@id': 'https://example.test/blog/template#product',
+            },
+          },
+        },
+      ],
+    });
+
+    expect(result.findings).toEqual([]);
+    expect(result.pages).toEqual([
+      {
+        pageRef: 'blog-post',
+        routePath: '/blog/[slug]',
+        payloadCount: 2,
+        findingCount: 0,
+      },
+    ]);
+  });
+
+  it('does not validate templated section payloads twice when collection findings also exist', () => {
+    const result = reconcileStructuredDataAgainstCatalog({
+      catalog: [
+        createCatalogEntry({
+          '@type': 'Product',
+          requiredFields: ['name'],
+        }),
+      ],
+      pages: [
+        {
+          ref: 'blog-post',
+          routePath: '/blog/[slug]',
+          sectionRefs: ['missing-section', 'blog-product'],
+        },
+      ],
+      sections: [
+        {
+          sectionRef: 'blog-product',
+          getStructuredData: () => ({
+            '@type': 'Product',
+            '@id': 'https://example.test/blog/a#product',
+          }),
+        },
+      ],
+      pagePayloads: [
+        {
+          pageRef: 'blog-post',
+          routePath: '/blog/a',
+          sourceRef: 'page:blog-post:a',
+          payloads: {
+            '@type': 'Product',
+            '@id': 'https://example.test/blog/a#page-product',
+            name: 'Page product',
+          },
+        },
+      ],
+    });
+
+    const missingNameFindings = result.findings.filter(
+      (finding) =>
+        finding.kind === 'spec-violation'
+        && finding.code === 'missing-required-field'
+        && finding.field === 'name',
+    );
+    expect(missingNameFindings).toHaveLength(1);
+    expect(result.pages).toEqual([
+      {
+        pageRef: 'blog-post',
+        routePath: '/blog/[slug]',
+        payloadCount: 0,
+        findingCount: 1,
+      },
+      {
+        pageRef: 'blog-post',
+        routePath: '/blog/a',
+        payloadCount: 2,
+        findingCount: 1,
+      },
+    ]);
+  });
+
+  it('reports page-level payloads that reference no supplied page manifest', () => {
+    const result = reconcileStructuredDataAgainstCatalog({
+      catalog: [createCatalogEntry({ '@type': 'BlogPosting' })],
+      pages: [],
+      sections: [],
+      pagePayloads: [
+        {
+          pageRef: 'missing-page',
+          routePath: '/missing',
+          sourceRef: 'page:missing',
+          payloads: {
+            '@type': 'BlogPosting',
+          },
+        },
+      ],
+    });
+
+    expect(result.findings).toEqual([
+      expect.objectContaining({
+        kind: 'spec-violation',
+        code: 'orphan-page-payload',
+        pageRef: 'missing-page',
+        routePath: '/missing',
+        sectionRef: 'page:missing',
+      }),
+    ]);
+  });
+
+  it('reports missing required fields as spec-violation findings', () => {
+    const result = reconcileStructuredDataAgainstCatalog({
+      catalog: [
+        createCatalogEntry({
+          '@type': 'Product',
+          requiredFields: ['name', 'offers'],
+        }),
+      ],
+      pages: [
+        {
+          ref: 'pricing',
+          routePath: '/pricing',
+          sectionRefs: ['pricing-card'],
+        },
+      ],
+      sections: [
+        {
+          sectionRef: 'pricing-card',
+          getStructuredData: () => ({
+            '@type': 'Product',
+            name: 'Wonder Todos Pro',
+          }),
+        },
+      ],
+    });
+
+    expect(result.findings).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          kind: 'spec-violation',
+          code: 'missing-required-field',
+          field: 'offers',
+          entityType: 'Product',
+        }),
+      ]),
+    );
+  });
+
+  it('reports deprecated-field usage when emitted payloads still include deprecated catalog fields', () => {
+    const result = reconcileStructuredDataAgainstCatalog({
+      catalog: [
+        createCatalogEntry({
+          '@type': 'Article',
+          deprecatedFields: [
+            {
+              field: 'dateCreated',
+              replacedBy: 'datePublished',
+              deprecatedSince: '2026-04-17',
+            },
+          ],
+        }),
+      ],
+      pages: [
+        {
+          ref: 'blog',
+          routePath: '/blog/example',
+          sectionRefs: ['blog-body'],
+        },
+      ],
+      sections: [
+        {
+          sectionRef: 'blog-body',
+          getStructuredData: () => ({
+            '@type': 'Article',
+            dateCreated: '2026-04-17',
+          }),
+        },
+      ],
+    });
+
+    expect(findFinding(result.findings, 'deprecated-field')).toMatchObject({
+      kind: 'deprecated-field',
+      entityType: 'Article',
+      field: 'dateCreated',
+      replacedBy: 'datePublished',
+      deprecatedSince: '2026-04-17',
+    });
+  });
+
+  it('reports cross-entity reference drift when payloads point at missing @id targets', () => {
+    const result = reconcileStructuredDataAgainstCatalog({
+      catalog: [
+        createCatalogEntry({
+          '@type': 'Review',
+          requiredFields: ['itemReviewed'],
+        }),
+      ],
+      pages: [
+        {
+          ref: 'reviews',
+          routePath: '/reviews',
+          sectionRefs: ['review-card'],
+        },
+      ],
+      sections: [
+        {
+          sectionRef: 'review-card',
+          getStructuredData: () => ({
+            '@type': 'Review',
+            itemReviewed: {
+              '@id': 'https://example.com/#product-missing',
+            },
+          }),
+        },
+      ],
+    });
+
+    expect(findFinding(result.findings, 'cross-entity-reference-drift')).toMatchObject({
+      kind: 'cross-entity-reference-drift',
+      entityType: 'Review',
+      missingReferenceId: 'https://example.com/#product-missing',
+    });
+  });
+
+  it('fails closed on missing section registrations and invalid getStructuredData payload shapes', () => {
+    const result = reconcileStructuredDataAgainstCatalog({
+      catalog: [createCatalogEntry({ '@type': 'Product' })],
+      pages: [
+        {
+          ref: 'pricing',
+          routePath: '/pricing',
+          sectionRefs: ['missing-section', 'invalid-section'],
+        },
+      ],
+      sections: [
+        {
+          sectionRef: 'invalid-section',
+          getStructuredData: () => 'not-an-object',
+        },
+      ],
+    });
+
+    expect(result.findings).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          kind: 'spec-violation',
+          code: 'missing-section-definition',
+          sectionRef: 'missing-section',
+        }),
+        expect.objectContaining({
+          kind: 'spec-violation',
+          code: 'invalid-payload-shape',
+          sectionRef: 'invalid-section',
+        }),
+      ]),
+    );
+  });
+});

package/src/schemas/blog/blog-post-frontmatter.shared.schemas.ts

@@ -0,0 +1,111 @@
+import { z } from 'zod';
+
+import { AvailableLanguage } from '@wildo-ai/saas-models/public-runtime';
+
+/**
+ * @wildo_source:part:start saas.website.blog.frontmatter facet:layer:shared facet:family:website
+ *
+ * `BlogPostFrontmatter` — the YAML frontmatter contract every blog
+ * post MDX file under `examples/<app>/website/src/content/blog/<locale>/`
+ * MUST satisfy.
+ *
+ * **Q16=B context**: blogs are authored as full per-locale MDX files
+ * (one MDX per (slug, locale) pair), NOT as label-pack-keyed content.
+ * The frontmatter therefore carries strings directly (`title`,
+ * `summary`) rather than label keys — there is no shared
+ * label-pack-driven authoring surface for blog content. This is
+ * intentional: blog copy is long-form and locale-divergent; forcing
+ * it through a structural label-pack would either inflate the pack
+ * or fragment the prose.
+ *
+ * **Field rationale**:
+ *
+ * - `title` — REQUIRED. Renders into `<title>`, `og:title`, and the
+ *   in-page H1. Authored as a direct string, deliberately.
+ * - `summary` — REQUIRED. Renders into `<meta name="description">`,
+ *   `og:description`, and listing-card descriptions. Direct string.
+ * - `slug` — REQUIRED. URL slug (lowercase kebab-case). Brand prevents
+ *   accidental swap with `WebsitePageRef` (same shape, different role).
+ * - `locale` — REQUIRED. The post's locale. Drives the URL prefix
+ *   (`/<locale>/blog/<slug>`) and `<html lang>`. Cross-locale
+ *   correspondence is established by sharing the `slug` across
+ *   per-locale MDX files (e.g. `en/why-context.md` and
+ *   `fr/why-context.md` are the same post in two locales).
+ * - `publishedAt` — REQUIRED. ISO-8601 date-time string. Renders into
+ *   `og:article:published_time` and the listing-card date label.
+ *   Stored as string (not `z.coerce.date`) because YAML frontmatter
+ *   parsers preserve the original string and the SEO emitters need
+ *   the original ISO formatting (no Date.toISOString() round-trip
+ *   loss).
+ * - `authorRef` — REQUIRED. Identifier of the author resolved by the
+ *   consumer's author registry (typically a `src/content/authors/<ref>.ts`
+ *   file). Brand keeps it distinct from page/section refs.
+ * - `tags` — REQUIRED, possibly empty. Lowercase kebab-case tag
+ *   identifiers. Drives `og:article:tag` and the listing-page facets.
+ * - `coverImageUrl` — OPTIONAL. CDN URL for the blog post hero image
+ *   and `og:image`.
+ *
+ * **Why a separate file from the page-manifest**: a blog post is NOT
+ * a `WebsitePageManifest` (no React `pageComponent` to mount — the
+ * MDX file IS the content). The Astro adapter emits one MDX route
+ * per post via `content collections`, with `BlogPostFrontmatter`
+ * driving the route generation and the SEO emission.
+ */
+const _BlogPostSlugSchema = z
+  .string()
+  .min(1, { error: 'BlogPostSlug must not be empty' })
+  .max(96, { error: 'BlogPostSlug must be at most 96 characters' })
+  .regex(
+    /^[a-z][a-z0-9-]*$/,
+    { error: 'BlogPostSlug must be lowercase kebab-case starting with a letter' },
+  )
+  .brand<'BlogPostSlug'>();
+
+export const BlogPostSlugSchema: typeof _BlogPostSlugSchema = _BlogPostSlugSchema;
+
+export type BlogPostSlug = z.infer<typeof _BlogPostSlugSchema>;
+
+const _BlogAuthorRefSchema = z
+  .string()
+  .min(1, { error: 'BlogAuthorRef must not be empty' })
+  .max(64, { error: 'BlogAuthorRef must be at most 64 characters' })
+  .regex(
+    /^[a-z][a-z0-9-]*$/,
+    { error: 'BlogAuthorRef must be lowercase kebab-case starting with a letter' },
+  )
+  .brand<'BlogAuthorRef'>();
+
+export const BlogAuthorRefSchema: typeof _BlogAuthorRefSchema = _BlogAuthorRefSchema;
+
+export type BlogAuthorRef = z.infer<typeof _BlogAuthorRefSchema>;
+
+const _BlogPostTagSchema = z
+  .string()
+  .min(1, { error: 'BlogPostTag must not be empty' })
+  .max(48, { error: 'BlogPostTag must be at most 48 characters' })
+  .regex(
+    /^[a-z][a-z0-9-]*$/,
+    { error: 'BlogPostTag must be lowercase kebab-case starting with a letter' },
+  )
+  .brand<'BlogPostTag'>();
+
+export const BlogPostTagSchema: typeof _BlogPostTagSchema = _BlogPostTagSchema;
+
+export type BlogPostTag = z.infer<typeof _BlogPostTagSchema>;
+
+const _BlogPostFrontmatterSchema = z.object({
+  title: z.string().min(1, { error: 'title must not be empty' }).max(200, { error: 'title must be at most 200 characters' }),
+  summary: z.string().min(1, { error: 'summary must not be empty' }).max(400, { error: 'summary must be at most 400 characters' }),
+  slug: _BlogPostSlugSchema,
+  locale: z.enum(AvailableLanguage),
+  publishedAt: z.iso.datetime({ error: 'publishedAt must be an ISO-8601 datetime string' }),
+  authorRef: _BlogAuthorRefSchema,
+  tags: z.array(_BlogPostTagSchema),
+  coverImageUrl: z.url({ error: 'coverImageUrl must be a valid URL' }).optional(),
+});
+
+export const BlogPostFrontmatterSchema: typeof _BlogPostFrontmatterSchema =
+  _BlogPostFrontmatterSchema;
+
+export type BlogPostFrontmatter = z.infer<typeof _BlogPostFrontmatterSchema>;
+/** @wildo_source:part:end saas.website.blog.frontmatter */