@vectoriox/iox-ui 5.26.0 → 5.27.0

package/src/generation-core/templates.ts

@@ -0,0 +1,60 @@
+import type { DesignChoices } from '@vectoriox/iox-ui/design-core';
+
+import { ContentTypePlan, DataSourcePlan, GlobalSlot, PagePlan, SiteBusiness, SitePlan, SitePlanSourceKind, SITE_PLAN_VERSION } from './site-plan.model';
+import { SPEC_SITE_TEMPLATES } from './site-spec.generated';
+
+/** A site structure the wizard offers (contract `site.templates`). A template is a Site Plan without the
+ *  customer's part — the business and the look — which `planFromTemplate` adds. */
+export interface SiteTemplate {
+    readonly id: string;
+    readonly version: number;
+    readonly label: string;
+    readonly blurb: string;
+    readonly bestFor: ReadonlyArray<string>;
+    readonly contentTypes: ReadonlyArray<ContentTypePlan>;
+    readonly dataSources: ReadonlyArray<DataSourcePlan>;
+    readonly pages: ReadonlyArray<PagePlan>;
+    readonly globals: Readonly<Record<`${GlobalSlot}`, string>>;
+}
+
+export const SITE_TEMPLATES: Readonly<Record<string, SiteTemplate>> = SPEC_SITE_TEMPLATES;
+
+export enum SiteTemplateId {
+    Studio = 'studio',
+}
+
+export const STUDIO_TEMPLATE: SiteTemplate = SITE_TEMPLATES[SiteTemplateId.Studio];
+
+export interface TemplatePlanInput {
+    business: SiteBusiness;
+    design: DesignChoices;
+    /** Keys of the template's OPTIONAL pages to leave out (the wizard's Pages step). */
+    omitPages?: ReadonlyArray<string>;
+}
+
+export class SiteTemplateError extends Error {}
+
+const clone = <T>(value: T): T => JSON.parse(JSON.stringify(value)) as T;
+
+/**
+ * The template as a Site Plan (`source.kind: template`), with the customer's business and look. A
+ * required page cannot be left out, and an unknown key is refused — nothing is guessed.
+ */
+export function planFromTemplate(template: SiteTemplate, input: TemplatePlanInput): SitePlan {
+    const omit = new Set(input.omitPages ?? []);
+    for (const key of omit) {
+        const page = template.pages.find(p => p.key === key);
+        if (!page) throw new SiteTemplateError(`template ${template.id} has no page "${key}"`);
+        if (page.required) throw new SiteTemplateError(`page "${key}" of template ${template.id} is required`);
+    }
+    return {
+        version: SITE_PLAN_VERSION,
+        source: { kind: SitePlanSourceKind.Template, templateId: template.id, templateVersion: template.version },
+        business: clone(input.business),
+        design: clone(input.design),
+        contentTypes: clone(template.contentTypes),
+        dataSources: clone(template.dataSources),
+        pages: clone(template.pages.filter(p => !omit.has(p.key))),
+        globals: clone(template.globals),
+    };
+}

package/src/generation-core/validate-site-plan.ts

@@ -0,0 +1,413 @@
+import { flavorPackById, parseHexColor, SPEC_AXES } from '@vectoriox/iox-ui/design-core';
+
+import {
+    BindScope, patternById, patternNeedsBinding, patternOptionalParts, patternScopes, patternSlots, PatternGlobalPosition,
+} from './patterns';
+import {
+    FACT_KEYS, GlobalSlot, PlanDataSourceMode, PlanDataSourceType, RelativeOp, SitePlanSourceKind, SITE_PLAN_VERSION,
+} from './site-plan.model';
+
+/**
+ * The Site Plan validator — the gate in front of the composer. The wizard's plan and (later) the AI's
+ * plan go through the SAME checks: an unknown pattern, a slot the pattern does not declare, a source
+ * that does not exist, a page whose route item cannot be resolved — all refused, with a path, before a
+ * single page is written. It never repairs: a model gets the issues back and rewrites.
+ */
+
+export enum SitePlanIssueCode {
+    /** A value of the wrong type, or a required value missing. */
+    Shape = 'shape',
+    /** A key the plan shape does not have. */
+    UnknownKey = 'unknown-key',
+    Version = 'version',
+    UnknownFlavor = 'unknown-flavor',
+    InvalidDesign = 'invalid-design',
+    MissingBusinessName = 'missing-business-name',
+    UnknownFact = 'unknown-fact',
+    Duplicate = 'duplicate',
+    ReservedAlias = 'reserved-alias',
+    UnknownContentType = 'unknown-content-type',
+    UnknownField = 'unknown-field',
+    UnknownDataSource = 'unknown-data-source',
+    InvalidDataSource = 'invalid-data-source',
+    InvalidRoute = 'invalid-route',
+    Home = 'home',
+    RouteSource = 'route-source',
+    UnknownPattern = 'unknown-pattern',
+    GlobalPattern = 'global-pattern',
+    UnknownSlot = 'unknown-slot',
+    UnknownOptionalPart = 'unknown-optional-part',
+    Binding = 'binding',
+    MissingScope = 'missing-scope',
+}
+
+export interface SitePlanIssue {
+    code: SitePlanIssueCode;
+    /** Where, as a dotted path into the plan (`pages[2].sections[0].binding`). */
+    path: string;
+    message: string;
+}
+
+export interface SitePlanValidation {
+    valid: boolean;
+    issues: SitePlanIssue[];
+}
+
+export class SitePlanError extends Error {
+    constructor(readonly issues: ReadonlyArray<SitePlanIssue>) {
+        super(`invalid site plan: ${issues.map(i => `${i.path}: ${i.message}`).join('; ')}`);
+    }
+}
+
+/** The alias of the static source the composer writes for the navigation (`$navPages`). A plan source
+ *  may not take it. */
+export const NAV_PAGES_ALIAS = 'navPages';
+/** Route-scope aliases (`$route`, `$current`, …) are platform-owned. */
+const RESERVED_PREFIX = '$';
+const ID_FIELD = '_id';
+
+const PLAN_KEYS = ['version', 'source', 'business', 'design', 'contentTypes', 'dataSources', 'pages', 'globals'];
+const BUSINESS_KEYS = ['name', 'tagline', 'facts'];
+const DESIGN_REQUIRED = ['flavorId', 'seed', 'pairId', 'shape', 'density', 'motion', 'pillButtons', 'mode'];
+const DESIGN_KEYS = [...DESIGN_REQUIRED, 'tint', 'fonts'];
+const CONTENT_TYPE_KEYS = ['name', 'label', 'previewTextField', 'previewImageField', 'fields', 'seed'];
+const FIELD_KEYS = ['name', 'type', 'controller', 'required', 'note'];
+const SEED_FIXED_KEYS = ['count', 'sample', 'isPublished'];
+const CMS_SOURCE_KEYS = ['alias', 'type', 'mode', 'contentType', 'limit', 'filterByRouteParam'];
+const RELATIVE_SOURCE_KEYS = ['alias', 'type', 'of', 'op', 'within'];
+const PAGE_KEYS = ['key', 'name', 'route', 'isHome', 'required', 'inNav', 'template', 'routeSource', 'sections'];
+const SECTION_KEYS = ['pattern', 'slots', 'binding', 'without'];
+const GLOBAL_POSITION: Readonly<Record<`${GlobalSlot}`, `${PatternGlobalPosition}`>> = {
+    [GlobalSlot.Header]: PatternGlobalPosition.Before,
+    [GlobalSlot.Footer]: PatternGlobalPosition.After,
+};
+const ROUTE = /^\/(?:(?:[a-z0-9]+(?:-[a-z0-9]+)*|:[a-zA-Z_][a-zA-Z0-9_]*)(?:\/(?:[a-z0-9]+(?:-[a-z0-9]+)*|:[a-zA-Z_][a-zA-Z0-9_]*))*)?$/;
+const ROUTE_PARAM = /:([a-zA-Z_][a-zA-Z0-9_]*)/g;
+
+type Obj = Record<string, unknown>;
+
+const isObject = (v: unknown): v is Obj => !!v && typeof v === 'object' && !Array.isArray(v);
+const isNonEmptyString = (v: unknown): v is string => typeof v === 'string' && v.trim() !== '';
+const has = (table: object, key: string) => Object.prototype.hasOwnProperty.call(table, key);
+const at = (path: string, key: string) => (path ? `${path}.${key}` : key);
+
+/** The `:param` names of a route, in order. */
+export function routeParams(route: string): string[] {
+    return [...route.matchAll(ROUTE_PARAM)].map(m => m[1]);
+}
+
+class Collector {
+    readonly issues: SitePlanIssue[] = [];
+    add(code: SitePlanIssueCode, path: string, message: string): void {
+        this.issues.push({ code, path, message });
+    }
+    keys(obj: Obj, allowed: ReadonlyArray<string>, path: string): void {
+        for (const key of Object.keys(obj)) if (!allowed.includes(key)) this.add(SitePlanIssueCode.UnknownKey, at(path, key), `"${key}" is not part of the plan shape`);
+    }
+    string(obj: Obj, key: string, path: string, required = true): string | null {
+        const v = obj[key];
+        if (v === undefined && !required) return null;
+        if (!isNonEmptyString(v)) {
+            this.add(SitePlanIssueCode.Shape, at(path, key), 'must be a non-empty string');
+            return null;
+        }
+        return v;
+    }
+    boolean(obj: Obj, key: string, path: string): void {
+        if (obj[key] !== undefined && typeof obj[key] !== 'boolean') this.add(SitePlanIssueCode.Shape, at(path, key), 'must be a boolean');
+    }
+    array(obj: Obj, key: string, path: string): unknown[] {
+        const v = obj[key];
+        if (!Array.isArray(v)) {
+            this.add(SitePlanIssueCode.Shape, at(path, key), 'must be an array');
+            return [];
+        }
+        return v;
+    }
+    unique(values: Array<string | null>, path: (i: number) => string, what: string): void {
+        const seen = new Set<string>();
+        values.forEach((v, i) => {
+            if (v === null) return;
+            if (seen.has(v)) this.add(SitePlanIssueCode.Duplicate, path(i), `${what} "${v}" is used twice`);
+            seen.add(v);
+        });
+    }
+}
+
+function validateSource(c: Collector, source: unknown): void {
+    if (!isObject(source)) return c.add(SitePlanIssueCode.Shape, 'source', 'must be an object');
+    if (source['kind'] === SitePlanSourceKind.Template) {
+        c.keys(source, ['kind', 'templateId', 'templateVersion'], 'source');
+        c.string(source, 'templateId', 'source');
+        if (!Number.isInteger(source['templateVersion'])) c.add(SitePlanIssueCode.Shape, 'source.templateVersion', 'must be an integer');
+    } else if (source['kind'] === SitePlanSourceKind.Ai) {
+        c.keys(source, ['kind', 'runId'], 'source');
+        c.string(source, 'runId', 'source');
+    } else {
+        c.add(SitePlanIssueCode.Shape, 'source.kind', `must be "${SitePlanSourceKind.Template}" or "${SitePlanSourceKind.Ai}"`);
+    }
+}
+
+function validateBusiness(c: Collector, business: unknown): void {
+    if (!isObject(business)) return c.add(SitePlanIssueCode.Shape, 'business', 'must be an object');
+    c.keys(business, BUSINESS_KEYS, 'business');
+    if (!isNonEmptyString(business['name'])) c.add(SitePlanIssueCode.MissingBusinessName, 'business.name', 'the business name is required');
+    if (business['tagline'] !== undefined && typeof business['tagline'] !== 'string') c.add(SitePlanIssueCode.Shape, 'business.tagline', 'must be a string');
+    const facts = business['facts'];
+    if (facts === undefined) return;
+    if (!isObject(facts)) return c.add(SitePlanIssueCode.Shape, 'business.facts', 'must be an object');
+    for (const [key, value] of Object.entries(facts)) {
+        if (!(FACT_KEYS as ReadonlyArray<string>).includes(key)) c.add(SitePlanIssueCode.UnknownFact, `business.facts.${key}`, `"${key}" is not a fact (${FACT_KEYS.join(', ')})`);
+        else if (typeof value !== 'string') c.add(SitePlanIssueCode.Shape, `business.facts.${key}`, 'must be a string');
+    }
+}
+
+function validateDesign(c: Collector, design: unknown): void {
+    if (!isObject(design)) return c.add(SitePlanIssueCode.Shape, 'design', 'must be an object');
+    c.keys(design, DESIGN_KEYS, 'design');
+    for (const key of DESIGN_REQUIRED) if (design[key] === undefined) c.add(SitePlanIssueCode.Shape, `design.${key}`, 'is required');
+    const pack = flavorPackById(typeof design['flavorId'] === 'string' ? design['flavorId'] : null);
+    if (design['flavorId'] !== undefined && (!pack || pack.id !== design['flavorId'])) {
+        c.add(SitePlanIssueCode.UnknownFlavor, 'design.flavorId', `"${String(design['flavorId'])}" is not a flavor`);
+    }
+    const bad = (key: string, why: string) => c.add(SitePlanIssueCode.InvalidDesign, `design.${key}`, why);
+    if (design['seed'] !== undefined && (typeof design['seed'] !== 'string' || !parseHexColor(design['seed']))) bad('seed', 'must be a #rrggbb colour');
+    if (design['pairId'] !== undefined && pack && !pack.pairs.some(p => p.id === design['pairId'])) bad('pairId', `is not a font pairing of ${pack.id}`);
+    const axis = (key: string, table: object) => {
+        if (design[key] !== undefined && (typeof design[key] !== 'string' || !has(table, design[key] as string))) bad(key, `must be one of ${Object.keys(table).join(', ')}`);
+    };
+    axis('shape', SPEC_AXES.shapes);
+    axis('density', SPEC_AXES.densities);
+    axis('motion', SPEC_AXES.motions);
+    axis('tint', SPEC_AXES.tints);
+    if (design['mode'] !== undefined && !(SPEC_AXES.modes as ReadonlyArray<unknown>).includes(design['mode'])) bad('mode', `must be one of ${SPEC_AXES.modes.join(', ')}`);
+    if (design['pillButtons'] !== undefined && typeof design['pillButtons'] !== 'boolean') bad('pillButtons', 'must be a boolean');
+    if (design['fonts'] !== undefined && !isObject(design['fonts'])) bad('fonts', 'must be an object');
+}
+
+interface ContentTypeInfo { fields: Set<string>; }
+
+function validateContentTypes(c: Collector, list: unknown[]): Map<string, ContentTypeInfo> {
+    const types = new Map<string, ContentTypeInfo>();
+    list.forEach((raw, i) => {
+        const path = `contentTypes[${i}]`;
+        if (!isObject(raw)) return c.add(SitePlanIssueCode.Shape, path, 'must be an object');
+        c.keys(raw, CONTENT_TYPE_KEYS, path);
+        const name = c.string(raw, 'name', path);
+        c.string(raw, 'label', path);
+        const fields = c.array(raw, 'fields', path);
+        const names: Array<string | null> = fields.map((f, j) => {
+            const fp = `${path}.fields[${j}]`;
+            if (!isObject(f)) { c.add(SitePlanIssueCode.Shape, fp, 'must be an object'); return null; }
+            c.keys(f, FIELD_KEYS, fp);
+            c.string(f, 'type', fp);
+            c.string(f, 'controller', fp);
+            c.boolean(f, 'required', fp);
+            return c.string(f, 'name', fp);
+        });
+        c.unique(names, j => `${path}.fields[${j}].name`, 'field');
+        const fieldSet = new Set(names.filter((n): n is string => !!n));
+        for (const key of ['previewTextField', 'previewImageField']) {
+            const v = c.string(raw, key, path, false);
+            if (v && !fieldSet.has(v)) c.add(SitePlanIssueCode.UnknownField, `${path}.${key}`, `"${v}" is not a field of ${name}`);
+        }
+        const seed = raw['seed'];
+        if (seed !== undefined) {
+            if (!isObject(seed)) c.add(SitePlanIssueCode.Shape, `${path}.seed`, 'must be an object');
+            else {
+                if (!Number.isInteger(seed['count']) || (seed['count'] as number) < 0) c.add(SitePlanIssueCode.Shape, `${path}.seed.count`, 'must be a whole number');
+                for (const key of ['sample', 'isPublished']) if (typeof seed[key] !== 'boolean') c.add(SitePlanIssueCode.Shape, `${path}.seed.${key}`, 'must be a boolean');
+                for (const key of Object.keys(seed)) {
+                    if (!SEED_FIXED_KEYS.includes(key) && !fieldSet.has(key)) c.add(SitePlanIssueCode.UnknownField, `${path}.seed.${key}`, `"${key}" is not a field of ${name}`);
+                }
+            }
+        }
+        if (name && types.has(name)) c.add(SitePlanIssueCode.Duplicate, `${path}.name`, `content type "${name}" is used twice`);
+        else if (name) types.set(name, { fields: fieldSet });
+    });
+    return types;
+}
+
+interface SourceInfo { type: string; mode?: string; contentType?: string; routeParam?: string; of?: string; op?: string; }
+
+function validateDataSources(c: Collector, list: unknown[], types: Map<string, ContentTypeInfo>): Map<string, SourceInfo> {
+    const sources = new Map<string, SourceInfo>();
+    list.forEach((raw, i) => {
+        const path = `dataSources[${i}]`;
+        if (!isObject(raw)) return c.add(SitePlanIssueCode.Shape, path, 'must be an object');
+        const alias = c.string(raw, 'alias', path);
+        if (alias && (alias.startsWith(RESERVED_PREFIX) || alias === NAV_PAGES_ALIAS)) {
+            c.add(SitePlanIssueCode.ReservedAlias, `${path}.alias`, `"${alias}" is reserved for the platform`);
+        }
+        if (raw['type'] === PlanDataSourceType.Cms) {
+            c.keys(raw, CMS_SOURCE_KEYS, path);
+            const mode = raw['mode'];
+            if (mode !== PlanDataSourceMode.Query && mode !== PlanDataSourceMode.Single) c.add(SitePlanIssueCode.InvalidDataSource, `${path}.mode`, `must be "${PlanDataSourceMode.Query}" or "${PlanDataSourceMode.Single}"`);
+            const contentType = c.string(raw, 'contentType', path);
+            const type = contentType ? types.get(contentType) : undefined;
+            if (contentType && !type) c.add(SitePlanIssueCode.UnknownContentType, `${path}.contentType`, `no content type "${contentType}" in the plan`);
+            if (raw['limit'] !== undefined && (!Number.isInteger(raw['limit']) || (raw['limit'] as number) < 1)) c.add(SitePlanIssueCode.InvalidDataSource, `${path}.limit`, 'must be a positive whole number');
+            let routeParam: string | undefined;
+            const byRoute = raw['filterByRouteParam'];
+            if (byRoute !== undefined) {
+                if (!isObject(byRoute)) c.add(SitePlanIssueCode.Shape, `${path}.filterByRouteParam`, 'must be an object');
+                else {
+                    c.keys(byRoute, ['field', 'routeParam'], `${path}.filterByRouteParam`);
+                    const field = c.string(byRoute, 'field', `${path}.filterByRouteParam`);
+                    routeParam = c.string(byRoute, 'routeParam', `${path}.filterByRouteParam`) ?? undefined;
+                    if (field && type && field !== ID_FIELD && !type.fields.has(field)) c.add(SitePlanIssueCode.UnknownField, `${path}.filterByRouteParam.field`, `"${field}" is not a field of ${contentType}`);
+                    if (mode !== PlanDataSourceMode.Single) c.add(SitePlanIssueCode.InvalidDataSource, `${path}.filterByRouteParam`, 'only a single source is looked up by a route param');
+                }
+            }
+            if (alias && !sources.has(alias)) sources.set(alias, { type: PlanDataSourceType.Cms, mode: mode as string, contentType: contentType ?? undefined, routeParam });
+        } else if (raw['type'] === PlanDataSourceType.Relative) {
+            c.keys(raw, RELATIVE_SOURCE_KEYS, path);
+            c.string(raw, 'of', path);
+            c.string(raw, 'within', path);
+            if (!(Object.values(RelativeOp) as unknown[]).includes(raw['op'])) c.add(SitePlanIssueCode.InvalidDataSource, `${path}.op`, `must be one of ${Object.values(RelativeOp).join(', ')}`);
+            if (alias && !sources.has(alias)) sources.set(alias, { type: PlanDataSourceType.Relative, of: raw['of'] as string, op: raw['op'] as string });
+        } else {
+            c.add(SitePlanIssueCode.InvalidDataSource, `${path}.type`, `must be "${PlanDataSourceType.Cms}" or "${PlanDataSourceType.Relative}"`);
+        }
+    });
+    c.unique(list.map(r => (isObject(r) && isNonEmptyString(r['alias']) ? r['alias'] : null)), i => `dataSources[${i}].alias`, 'alias');
+    // A relative source locates its subject (a single item) within a collection of the SAME type.
+    list.forEach((raw, i) => {
+        if (!isObject(raw) || raw['type'] !== PlanDataSourceType.Relative) return;
+        const of = sources.get(raw['of'] as string);
+        const within = sources.get(raw['within'] as string);
+        if (!of || of.type !== PlanDataSourceType.Cms || of.mode !== PlanDataSourceMode.Single) c.add(SitePlanIssueCode.UnknownDataSource, `dataSources[${i}].of`, 'must name a single cms source of the plan');
+        if (!within || within.type !== PlanDataSourceType.Cms || within.mode !== PlanDataSourceMode.Query) c.add(SitePlanIssueCode.UnknownDataSource, `dataSources[${i}].within`, 'must name a list (query) cms source of the plan');
+        if (of?.contentType && within?.contentType && of.contentType !== within.contentType) c.add(SitePlanIssueCode.InvalidDataSource, `dataSources[${i}]`, `${raw['of']} and ${raw['within']} are different content types`);
+    });
+    return sources;
+}
+
+function validatePages(c: Collector, list: unknown[], types: Map<string, ContentTypeInfo>, sources: Map<string, SourceInfo>): void {
+    const homes: number[] = [];
+    list.forEach((raw, i) => {
+        const path = `pages[${i}]`;
+        if (!isObject(raw)) return c.add(SitePlanIssueCode.Shape, path, 'must be an object');
+        c.keys(raw, PAGE_KEYS, path);
+        c.string(raw, 'key', path);
+        c.string(raw, 'name', path);
+        for (const key of ['isHome', 'required', 'inNav']) c.boolean(raw, key, path);
+        const route = c.string(raw, 'route', path);
+        if (route && !ROUTE.test(route)) c.add(SitePlanIssueCode.InvalidRoute, `${path}.route`, `"${route}" is not a route (/lowercase-words, :params)`);
+        if (raw['isHome'] === true) {
+            homes.push(i);
+            if (route !== '/') c.add(SitePlanIssueCode.Home, `${path}.route`, 'the home page lives at /');
+        } else if (route === '/') c.add(SitePlanIssueCode.Home, `${path}.isHome`, 'the page at / is the home page');
+
+        const params = route ? routeParams(route) : [];
+        const template = c.string(raw, 'template', path, false);
+        const routeSourceAlias = c.string(raw, 'routeSource', path, false);
+        const routeSource = routeSourceAlias ? sources.get(routeSourceAlias) : undefined;
+        const routeSourceOk = !!routeSource && routeSource.type === PlanDataSourceType.Cms && routeSource.mode === PlanDataSourceMode.Single;
+        if (template && !types.has(template)) c.add(SitePlanIssueCode.UnknownContentType, `${path}.template`, `no content type "${template}" in the plan`);
+        if (params.length > 1) c.add(SitePlanIssueCode.InvalidRoute, `${path}.route`, 'a template page has one route param');
+        if (params.length && !routeSourceAlias) c.add(SitePlanIssueCode.RouteSource, `${path}.routeSource`, `a route with :${params[0]} names the source that reads it`);
+        if (routeSourceAlias) {
+            if (!routeSourceOk) {
+                c.add(SitePlanIssueCode.RouteSource, `${path}.routeSource`, `"${routeSourceAlias}" must be a single cms source of the plan`);
+            } else {
+                if (!params.length || routeSource!.routeParam !== params[0]) c.add(SitePlanIssueCode.RouteSource, `${path}.routeSource`, `"${routeSourceAlias}" is not looked up by this route's param`);
+                if (template && routeSource!.contentType !== template) c.add(SitePlanIssueCode.RouteSource, `${path}.template`, `"${routeSourceAlias}" reads ${routeSource!.contentType}, not ${template}`);
+            }
+        }
+
+        c.array(raw, 'sections', path).forEach((s, j) => {
+            const sp = `${path}.sections[${j}]`;
+            if (!isObject(s)) return c.add(SitePlanIssueCode.Shape, sp, 'must be an object');
+            c.keys(s, SECTION_KEYS, sp);
+            const patternId = c.string(s, 'pattern', sp);
+            const pattern = patternById(patternId);
+            if (patternId && !pattern) return c.add(SitePlanIssueCode.UnknownPattern, `${sp}.pattern`, `no pattern "${patternId}"`);
+            if (!pattern) return;
+            if (pattern.global) c.add(SitePlanIssueCode.GlobalPattern, `${sp}.pattern`, `"${patternId}" is a header/footer pattern (globals)`);
+            const slots = s['slots'];
+            if (slots !== undefined) {
+                if (!isObject(slots)) c.add(SitePlanIssueCode.Shape, `${sp}.slots`, 'must be an object');
+                else {
+                    const declared = patternSlots(pattern);
+                    for (const [slot, value] of Object.entries(slots)) {
+                        if (!declared.includes(slot)) c.add(SitePlanIssueCode.UnknownSlot, `${sp}.slots.${slot}`, `"${patternId}" has no slot "${slot}" (${declared.join(', ') || 'none'})`);
+                        else if (typeof value !== 'string') c.add(SitePlanIssueCode.Shape, `${sp}.slots.${slot}`, 'must be a string');
+                    }
+                }
+            }
+            const without = s['without'];
+            if (without !== undefined) {
+                const parts = patternOptionalParts(pattern);
+                if (!Array.isArray(without)) c.add(SitePlanIssueCode.Shape, `${sp}.without`, 'must be an array');
+                else without.forEach((w, k) => {
+                    if (!parts.includes(w as string)) c.add(SitePlanIssueCode.UnknownOptionalPart, `${sp}.without[${k}]`, `"${patternId}" has no optional part "${String(w)}"`);
+                });
+            }
+            const binding = c.string(s, 'binding', sp, false);
+            if (patternNeedsBinding(pattern)) {
+                if (!binding) c.add(SitePlanIssueCode.Binding, `${sp}.binding`, `"${patternId}" repeats the section's binding — name a list source`);
+                else {
+                    const src = sources.get(binding);
+                    if (!src) c.add(SitePlanIssueCode.UnknownDataSource, `${sp}.binding`, `no data source "${binding}"`);
+                    else if (src.type !== PlanDataSourceType.Cms || src.mode !== PlanDataSourceMode.Query) c.add(SitePlanIssueCode.Binding, `${sp}.binding`, `"${binding}" is not a list source`);
+                }
+            } else if (binding) c.add(SitePlanIssueCode.Binding, `${sp}.binding`, `"${patternId}" repeats nothing — it takes no binding`);
+
+            // A pattern reading the route item needs a routeSource (an INVALID one is reported above, once).
+            const scopes = patternScopes(pattern);
+            const readsRoute = scopes.has(BindScope.Route) || scopes.has(BindScope.Next);
+            if (readsRoute && !routeSourceAlias) {
+                c.add(SitePlanIssueCode.MissingScope, `${sp}.pattern`, `"${patternId}" reads the route item — the page needs a routeSource`);
+            }
+            if (scopes.has(BindScope.Next) && routeSourceOk && !nextSourceOf(sources, routeSourceAlias as string)) {
+                c.add(SitePlanIssueCode.MissingScope, `${sp}.pattern`, `"${patternId}" reads the next item — the plan needs a ${RelativeOp.SiblingsNext} source of ${routeSourceAlias}`);
+            }
+        });
+    });
+    c.unique(list.map(p => (isObject(p) && isNonEmptyString(p['key']) ? p['key'] : null)), i => `pages[${i}].key`, 'page key');
+    c.unique(list.map(p => (isObject(p) && isNonEmptyString(p['route']) ? p['route'] : null)), i => `pages[${i}].route`, 'route');
+    if (homes.length !== 1) c.add(SitePlanIssueCode.Home, 'pages', `exactly one page is the home page (found ${homes.length})`);
+}
+
+/** The plan's `$siblings.next` source of `routeSource` — what a pattern's `next.*` reads. */
+export function nextSourceOf(sources: Map<string, { type: string; of?: string; op?: string }>, routeSource: string): string | null {
+    for (const [alias, s] of sources) if (s.type === PlanDataSourceType.Relative && s.of === routeSource && s.op === RelativeOp.SiblingsNext) return alias;
+    return null;
+}
+
+function validateGlobals(c: Collector, globals: unknown): void {
+    if (!isObject(globals)) return c.add(SitePlanIssueCode.Shape, 'globals', 'must be an object');
+    c.keys(globals, Object.values(GlobalSlot), 'globals');
+    for (const slot of Object.values(GlobalSlot)) {
+        const id = c.string(globals, slot, 'globals');
+        const pattern = patternById(id);
+        if (id && !pattern) c.add(SitePlanIssueCode.UnknownPattern, `globals.${slot}`, `no pattern "${id}"`);
+        else if (pattern && pattern.global !== GLOBAL_POSITION[slot]) c.add(SitePlanIssueCode.GlobalPattern, `globals.${slot}`, `"${id}" is not a ${slot} pattern`);
+    }
+}
+
+/** Check a Site Plan against the plan shape and the pattern library. Never throws, never repairs. */
+export function validateSitePlan(plan: unknown): SitePlanValidation {
+    const c = new Collector();
+    if (!isObject(plan)) {
+        c.add(SitePlanIssueCode.Shape, '', 'a site plan is an object');
+        return { valid: false, issues: c.issues };
+    }
+    c.keys(plan, PLAN_KEYS, '');
+    if (plan['version'] !== SITE_PLAN_VERSION) c.add(SitePlanIssueCode.Version, 'version', `must be "${SITE_PLAN_VERSION}"`);
+    validateSource(c, plan['source']);
+    validateBusiness(c, plan['business']);
+    validateDesign(c, plan['design']);
+    const types = validateContentTypes(c, c.array(plan, 'contentTypes', ''));
+    const sources = validateDataSources(c, c.array(plan, 'dataSources', ''), types);
+    validatePages(c, c.array(plan, 'pages', ''), types, sources);
+    validateGlobals(c, plan['globals']);
+    return { valid: c.issues.length === 0, issues: c.issues };
+}
+
+/** Throw a `SitePlanError` carrying every issue unless the plan is valid. */
+export function assertValidSitePlan(plan: unknown): void {
+    const result = validateSitePlan(plan);
+    if (!result.valid) throw new SitePlanError(result.issues);
+}