@cratis/scene.engine 4.25.0 → 4.27.0

package/sampleData/generateSample.ts

@@ -0,0 +1,156 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SampleFieldKind, SampleShape, SampleShapeField } from '@cratis/scene.model';
+import { inferSampleFieldKind } from './inferSampleFieldKind';
+import { SampleLocale, sampleLocaleFor } from './sampleLocales';
+import { SampleRandom, rowSeed } from './SampleRandom';
+
+/** The seed used when none is given, so previews are stable without any configuration. */
+export const defaultSampleSeed = 1;
+
+/** How many rows are generated when no count is given. */
+export const defaultSampleRowCount = 5;
+
+/** The most rows one call generates. */
+export const maximumSampleRowCount = 1000;
+
+/** Days since 1970-01-01 of 2024-01-01, the anchor generated dates count forward from. */
+const anchorDay = 19723;
+
+/** Generated dates fall within this many days after the anchor. */
+const dateSpanDays = 731;
+
+/**
+ * Generates `rowCount` rows of a shape, deterministically for a seed: the same shape, seed, row count and
+ * locale yield the same rows (byte-identical once serialized) in the C# and TypeScript engines.
+ *
+ * Each row has its own generator (see {@link rowSeed}), so row `i` is the same however many rows are asked
+ * for. Within a row the fields are generated in declaration order. A nullable field first draws whether it is
+ * null (one in five is) and then always draws its value, so the sequence never depends on nullability
+ * outcomes. Values follow the field's kind and locale; enum fields only ever produce one of their values,
+ * dates stay within 2024-2025 and amounts have two decimals.
+ *
+ * @param shape The shape to generate rows for.
+ * @param seed The seed; defaults to {@link defaultSampleSeed}.
+ * @param rowCount The number of rows; defaults to {@link defaultSampleRowCount}, clamped to `[0, 1000]`.
+ * @param locale The BCP 47 locale tag selecting names, cities and formats; unknown tags use the default pool.
+ */
+export function generateSample(shape: SampleShape, seed?: number, rowCount?: number, locale?: string): Record<string, unknown>[] {
+    const count = Math.min(Math.max(Math.trunc(rowCount ?? defaultSampleRowCount), 0), maximumSampleRowCount);
+    const effectiveSeed = (seed ?? defaultSampleSeed) >>> 0;
+    const pool = sampleLocaleFor(locale);
+    const rows: Record<string, unknown>[] = [];
+
+    for (let index = 0; index < count; index++) {
+        const random = new SampleRandom(rowSeed(effectiveSeed, shape.name, index));
+        const row: Record<string, unknown> = {};
+        for (const field of shape.fields) {
+            const isNull = field.nullable === true && random.nextInt(5) === 0;
+            const value = generateValue(field, inferSampleFieldKind(field), random, pool);
+            row[field.name] = isNull ? null : value;
+        }
+        rows.push(row);
+    }
+
+    return rows;
+}
+
+function generateValue(field: SampleShapeField, kind: SampleFieldKind, random: SampleRandom, pool: SampleLocale): unknown {
+    switch (kind) {
+        case SampleFieldKind.Id:
+            return generateId(random);
+        case SampleFieldKind.Name:
+            return `${random.pick(pool.firstNames)} ${random.pick(pool.lastNames)}`;
+        case SampleFieldKind.Company:
+            return random.pick(pool.companies);
+        case SampleFieldKind.Email: {
+            const first = random.pick(pool.firstNames);
+            const last = random.pick(pool.lastNames);
+            return `${slug(first)}.${slug(last)}@${random.pick(pool.domains)}`;
+        }
+        case SampleFieldKind.Phone:
+            return [...pool.phoneTemplate].map(character => (character === '#' ? String(random.nextInt(10)) : character)).join('');
+        case SampleFieldKind.City:
+            return random.pick(pool.cities);
+        case SampleFieldKind.Text: {
+            const words = Array.from({ length: 3 + random.nextInt(4) }, () => random.pick(pool.words));
+            return capitalize(words.join(' '));
+        }
+        case SampleFieldKind.WholeNumber: {
+            const [low, high] = range(field.min, field.max, 0, 1000, Math.trunc);
+            return low + random.nextInt(high - low + 1);
+        }
+        case SampleFieldKind.Amount: {
+            const [low, high] = range(field.min, field.max, 10, 5000, value => Math.floor(value * 100 + 0.5));
+            return (low + random.nextInt(high - low + 1)) / 100;
+        }
+        case SampleFieldKind.Boolean:
+            return random.nextInt(2) === 1;
+        case SampleFieldKind.Date:
+            return formatDay(anchorDay + random.nextInt(dateSpanDays));
+        case SampleFieldKind.DateTime: {
+            const day = anchorDay + random.nextInt(dateSpanDays);
+            const seconds = random.nextInt(86400);
+            return `${formatDay(day)}T${pad(Math.floor(seconds / 3600))}:${pad(Math.floor(seconds / 60) % 60)}:${pad(seconds % 60)}Z`;
+        }
+        case SampleFieldKind.Enum:
+            return field.enumValues !== undefined && field.enumValues !== null && field.enumValues.length > 0 ? random.pick(field.enumValues) : null;
+        default:
+            return null;
+    }
+}
+
+function range(min: number | undefined, max: number | undefined, defaultMin: number, defaultMax: number, convert: (value: number) => number): [number, number] {
+    const low = convert(min ?? defaultMin);
+    const high = convert(max ?? defaultMax);
+    return high < low ? [high, low] : [low, high];
+}
+
+function generateId(random: SampleRandom): string {
+    const a = random.next();
+    const b = ((random.next() & 0xFFFF0FFF) | 0x00004000) >>> 0;
+    const c = ((random.next() & 0x3FFFFFFF) | 0x80000000) >>> 0;
+    const d = random.next();
+    return `${hex(a, 8)}-${hex(b >>> 16, 4)}-${hex(b & 0xFFFF, 4)}-${hex(c >>> 16, 4)}-${hex(c & 0xFFFF, 4)}${hex(d, 8)}`;
+}
+
+const transliterations = new Map<string, string>([['æ', 'ae'], ['ø', 'o'], ['å', 'a'], ['ä', 'a'], ['ö', 'o'], ['ü', 'u'], ['ß', 'ss'], ['é', 'e']]);
+
+function slug(text: string): string {
+    let result = '';
+    for (const character of text.toLowerCase()) {
+        const mapped = transliterations.get(character) ?? character;
+        for (const part of mapped) {
+            if ((part >= 'a' && part <= 'z') || (part >= '0' && part <= '9')) result += part;
+        }
+    }
+    return result;
+}
+
+function capitalize(text: string): string {
+    const first = text.charAt(0);
+    return first >= 'a' && first <= 'z' ? first.toUpperCase() + text.slice(1) : text;
+}
+
+function hex(value: number, digits: number): string {
+    return (value >>> 0).toString(16).padStart(digits, '0');
+}
+
+function pad(value: number): string {
+    return value < 10 ? `0${value}` : String(value);
+}
+
+/** Formats days since 1970-01-01 as `yyyy-MM-dd` (Howard Hinnant's civil-from-days). */
+function formatDay(days: number): string {
+    const shifted = days + 719468;
+    const era = Math.floor(shifted / 146097);
+    const dayOfEra = shifted - era * 146097;
+    const yearOfEra = Math.floor((dayOfEra - Math.floor(dayOfEra / 1460) + Math.floor(dayOfEra / 36524) - Math.floor(dayOfEra / 146096)) / 365);
+    const dayOfYear = dayOfEra - (365 * yearOfEra + Math.floor(yearOfEra / 4) - Math.floor(yearOfEra / 100));
+    const monthPrime = Math.floor((5 * dayOfYear + 2) / 153);
+    const day = dayOfYear - Math.floor((153 * monthPrime + 2) / 5) + 1;
+    const month = monthPrime < 10 ? monthPrime + 3 : monthPrime - 9;
+    const year = yearOfEra + era * 400 + (month <= 2 ? 1 : 0);
+    return `${String(year).padStart(4, '0')}-${pad(month)}-${pad(day)}`;
+}

package/sampleData/index.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './SampleRandom';
+export * from './sampleLocales';
+export * from './inferSampleFieldKind';
+export * from './generateSample';
+export * from './SampleDataResolution';
+export * from './findSampleDataSet';
+export * from './resolveSampleData';
+export * from './sampleDataRules';
+export * from './validateSampleDataPack';
+export * from './validateSampleDataSelection';
+export * from './SampleDataPackSource';
+export * from './validateSampleDataPackages';
+export * from './describeSampleDataCatalog';
+export * from './findSampleRowLiterals';

package/sampleData/inferSampleFieldKind.ts

@@ -0,0 +1,64 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SampleFieldKind, SampleShapeField } from '@cratis/scene.model';
+
+const typeKinds = new Map<string, SampleFieldKind>([
+    ['guid', SampleFieldKind.Id],
+    ['uuid', SampleFieldKind.Id],
+    ['int', SampleFieldKind.WholeNumber],
+    ['int16', SampleFieldKind.WholeNumber],
+    ['int32', SampleFieldKind.WholeNumber],
+    ['int64', SampleFieldKind.WholeNumber],
+    ['short', SampleFieldKind.WholeNumber],
+    ['long', SampleFieldKind.WholeNumber],
+    ['integer', SampleFieldKind.WholeNumber],
+    ['number', SampleFieldKind.WholeNumber],
+    ['decimal', SampleFieldKind.Amount],
+    ['double', SampleFieldKind.Amount],
+    ['float', SampleFieldKind.Amount],
+    ['single', SampleFieldKind.Amount],
+    ['money', SampleFieldKind.Amount],
+    ['currency', SampleFieldKind.Amount],
+    ['bool', SampleFieldKind.Boolean],
+    ['boolean', SampleFieldKind.Boolean],
+    ['date', SampleFieldKind.Date],
+    ['dateonly', SampleFieldKind.Date],
+    ['datetime', SampleFieldKind.DateTime],
+    ['datetimeoffset', SampleFieldKind.DateTime],
+    ['timestamp', SampleFieldKind.DateTime],
+]);
+
+const nameKinds: [string[], SampleFieldKind][] = [
+    [['email'], SampleFieldKind.Email],
+    [['phone', 'mobile'], SampleFieldKind.Phone],
+    [['company', 'organization', 'organisation'], SampleFieldKind.Company],
+    [['city', 'town'], SampleFieldKind.City],
+    [['product', 'item', 'title', 'subject', 'description'], SampleFieldKind.Text],
+    [['name', 'customer', 'assignee', 'owner', 'author', 'contact', 'manager', 'employee'], SampleFieldKind.Name],
+];
+
+/**
+ * The kind of value to generate for a field. An explicit `kind` wins; otherwise a field with `enumValues` is
+ * an enum, a recognised `type` decides, and failing that the field's name does (an `Id` suffix, `email`,
+ * `phone`, `company`, `city`, person-like names), with free text as the fallback. A trailing `?` on the type
+ * is ignored and type names compare case-insensitively.
+ */
+export function inferSampleFieldKind(field: SampleShapeField): SampleFieldKind {
+    if (field.kind !== undefined && field.kind !== null) return field.kind as SampleFieldKind;
+    if (field.enumValues !== undefined && field.enumValues !== null && field.enumValues.length > 0) return SampleFieldKind.Enum;
+
+    let type = (field.type ?? '').trim().toLowerCase();
+    if (type.endsWith('?')) type = type.slice(0, -1);
+    const byType = typeKinds.get(type);
+    if (byType !== undefined) return byType;
+
+    const name = field.name ?? '';
+    const lower = name.toLowerCase();
+    if (lower === 'id' || (name.length > 2 && name.endsWith('Id'))) return SampleFieldKind.Id;
+    for (const [fragments, kind] of nameKinds) {
+        if (fragments.some(fragment => lower.includes(fragment))) return kind;
+    }
+
+    return SampleFieldKind.Text;
+}

package/sampleData/resolveSampleData.ts

@@ -0,0 +1,96 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SampleDataPack } from '@cratis/scene.model';
+import { generateSample } from './generateSample';
+import { defaultSampleLocale } from './sampleLocales';
+import { findSampleDataSet } from './findSampleDataSet';
+import { SampleDataContext, SampleDataDiagnostic, SampleDataRequest, SampleDataResolution } from './SampleDataResolution';
+
+/**
+ * Resolves the rows to show for a read model or shape at design or preview time, by the order of spec §11.2:
+ *
+ * 1. the pack bound to the target (`profile.sampleData.bindings`, a rare override);
+ * 2. the application's active pack: the UI profile's `sampleData.activePack`, chosen once for the whole
+ *    application, or the session-only override (`context.sessionActivePack`) the preview strip sets;
+ * 3. the default pack of the blueprint the template came from (`blueprintDefaultPack`);
+ * 4. generated data typed by field kind ({@link generateSample}), when the request carries a shape.
+ *
+ * A pack supplies rows when it has a set for the target, by an explicit `shape → read model` mapping or else by
+ * name ({@link findSampleDataSet}). A rung that cannot supply rows falls through to the next; an unknown pack
+ * id, or a bound pack without the target's shape, is reported in `diagnostics` (an active or blueprint pack
+ * that merely lacks the shape is normal and not reported). The locale carried is the supplying pack's; for
+ * generated data it is the first existing bound, active or blueprint pack's, else `context.locale`.
+ *
+ * Outside design and preview (`context.isDesignOrPreview` not true) nothing resolves (spec SD6).
+ */
+export function resolveSampleData(request: SampleDataRequest, context: SampleDataContext): SampleDataResolution {
+    const target = request.target ?? request.shape?.name ?? '';
+    const fallbackLocale = context.locale ?? defaultSampleLocale;
+    const diagnostics: SampleDataDiagnostic[] = [];
+
+    if (context.isDesignOrPreview !== true) {
+        return { source: 'disabled', locale: fallbackLocale, rows: [], diagnostics };
+    }
+
+    const packs = context.packs ?? [];
+    const selection = context.profile?.sampleData;
+    const mappings = selection?.mappings ?? [];
+    const find = (id: string | null | undefined): SampleDataPack | undefined => (id === undefined || id === null ? undefined : packs.find(pack => pack.id === id));
+    const missing = (id: string, role: string): void => {
+        diagnostics.push({ code: 'packNotFound', message: `The ${role} sample data pack '${id}' is not available` });
+    };
+
+    const bindingPackId = (selection?.bindings ?? []).find(binding => binding.target === target)?.pack;
+    const bindingPack = find(bindingPackId);
+    if (bindingPackId !== undefined && bindingPack === undefined) {
+        missing(bindingPackId, `bound`);
+    } else if (bindingPack !== undefined) {
+        const set = findSampleDataSet(bindingPack, target, mappings);
+        if (set !== undefined) return fromSet('binding', bindingPack, set.shape, set.rows, diagnostics);
+        diagnostics.push({ code: 'shapeNotInPack', message: `The bound sample data pack '${bindingPack.id}' has no rows for '${target}'` });
+    }
+
+    const sessionPackId = context.sessionActivePack;
+    const chosenPackId = sessionPackId !== undefined ? sessionPackId : selection?.activePack;
+    const activePackId = chosenPackId === '' ? undefined : chosenPackId;
+    const activePack = find(activePackId);
+    if (activePackId !== undefined && activePackId !== null && activePack === undefined) {
+        missing(activePackId, 'active');
+    } else if (activePack !== undefined) {
+        const set = findSampleDataSet(activePack, target, mappings);
+        if (set !== undefined) return fromSet('activePack', activePack, set.shape, set.rows, diagnostics);
+    }
+
+    const blueprintPackId = context.blueprintDefaultPack;
+    const blueprintPack = find(blueprintPackId);
+    if (blueprintPackId !== undefined && blueprintPackId !== null && blueprintPack === undefined) {
+        missing(blueprintPackId, 'blueprint default');
+    } else if (blueprintPack !== undefined) {
+        const set = findSampleDataSet(blueprintPack, target, mappings);
+        if (set !== undefined) return fromSet('blueprintDefault', blueprintPack, set.shape, set.rows, diagnostics);
+    }
+
+    const locale = bindingPack?.locale ?? activePack?.locale ?? blueprintPack?.locale ?? fallbackLocale;
+    if (request.shape === undefined) {
+        return { source: 'none', locale, shape: target, rows: [], diagnostics };
+    }
+
+    return {
+        source: 'generated',
+        locale,
+        shape: request.shape.name,
+        rows: generateSample(request.shape, context.seed, context.rowCount, locale),
+        diagnostics,
+    };
+}
+
+function fromSet(
+    source: 'binding' | 'activePack' | 'blueprintDefault',
+    pack: SampleDataPack,
+    shape: string,
+    rows: Record<string, unknown>[],
+    diagnostics: SampleDataDiagnostic[],
+): SampleDataResolution {
+    return { source, pack: pack.id, locale: pack.locale, shape, rows: structuredClone(rows), diagnostics };
+}

package/sampleData/sampleDataRules.ts

@@ -0,0 +1,30 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** A pack id: lower-case letters and digits in groups separated by `.`, `_` or `-` (`crm-nordic-smb`). */
+export const sampleDataIdPattern = /^[a-z0-9]+([._-][a-z0-9]+)*$/;
+
+/** A BCP 47 style locale tag: a 2-3 letter language followed by alphanumeric subtags (`nb-NO`, `en-GB`, `zh-Hant-TW`). */
+export const sampleDataLocalePattern = /^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$/;
+
+/** The owner of a pack the author created. */
+export const userSampleDataOwner = 'user';
+
+/** The prefix of the owner of a pack a blueprint ships (`blueprint:crm`). */
+export const blueprintSampleDataOwnerPrefix = 'blueprint:';
+
+/** Whether an owner is `user` or `blueprint:<id>` with a non-empty id. */
+export function isValidSampleDataOwner(owner: string | undefined): boolean {
+    if (owner === undefined || owner === null) return false;
+    return owner === userSampleDataOwner || (owner.startsWith(blueprintSampleDataOwnerPrefix) && owner.length > blueprintSampleDataOwnerPrefix.length && owner.trim() === owner);
+}
+
+/** The path separator, built from its code so the seam rule against route literals (I4) does not mistake it for a URL. */
+const pathSeparator = String.fromCharCode(47);
+
+/** Whether a package-relative pack path is `sampleData/<name>.json` with no `..`, `\\` or nested leading `/`. */
+export function isValidSampleDataPath(path: string | undefined): boolean {
+    if (path === undefined || path === null) return false;
+    if (!path.startsWith('sampleData/') || !path.endsWith('.json') || path.length <= 'sampleData/.json'.length) return false;
+    return !path.includes('..') && !path.includes('\\') && !path.split(pathSeparator).includes('');
+}

package/sampleData/sampleLocales.ts

@@ -0,0 +1,91 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** The value pools and formats generated data draws from for one locale. */
+export interface SampleLocale {
+    firstNames: string[];
+    lastNames: string[];
+    companies: string[];
+    cities: string[];
+    domains: string[];
+    /** `#` is replaced by a random digit. */
+    phoneTemplate: string;
+    words: string[];
+}
+
+const englishWords = ['review', 'quarterly', 'update', 'invoice', 'customer', 'delivery', 'schedule', 'renewal', 'report', 'follow', 'up', 'meeting'];
+
+const locales = new Map<string, SampleLocale>(Object.entries({
+    'en-GB': {
+        firstNames: ['Oliver', 'Amelia', 'George', 'Isla', 'Harry', 'Ava', 'Jack', 'Freya', 'Arthur', 'Poppy'],
+        lastNames: ['Smith', 'Jones', 'Taylor', 'Brown', 'Wilson', 'Evans', 'Thomas', 'Roberts', 'Walker', 'Wright'],
+        companies: ['Northgate Ltd', 'Albion Supplies Ltd', 'Thames Logistics Ltd', 'Pennine Foods Ltd', 'Harbour Digital Ltd', 'Cotswold Tools Ltd'],
+        cities: ['London', 'Manchester', 'Leeds', 'Bristol', 'Glasgow', 'Cardiff', 'Sheffield', 'Newcastle'],
+        domains: ['example.co.uk', 'example.org.uk', 'sample.co.uk'],
+        phoneTemplate: '+44 7### ######',
+        words: englishWords,
+    },
+    'en-US': {
+        firstNames: ['James', 'Emma', 'Michael', 'Olivia', 'William', 'Sophia', 'Benjamin', 'Mia', 'Henry', 'Grace'],
+        lastNames: ['Johnson', 'Miller', 'Davis', 'Garcia', 'Anderson', 'Martin', 'Clark', 'Lewis', 'Young', 'Hall'],
+        companies: ['Summit Supply Inc', 'Bluebird Software Inc', 'Redwood Freight Inc', 'Lakeside Foods Inc', 'Cardinal Tools Inc', 'Pioneer Digital Inc'],
+        cities: ['New York', 'Chicago', 'Austin', 'Seattle', 'Denver', 'Boston', 'Atlanta', 'Portland'],
+        domains: ['example.com', 'example.net', 'sample.com'],
+        phoneTemplate: '+1 (555) ###-####',
+        words: englishWords,
+    },
+    'nb-NO': {
+        firstNames: ['Lars', 'Ingrid', 'Ola', 'Kari', 'Henrik', 'Sigrid', 'Magnus', 'Åse', 'Bjørn', 'Mari'],
+        lastNames: ['Hansen', 'Johansen', 'Olsen', 'Larsen', 'Andersen', 'Pedersen', 'Nilsen', 'Kristiansen', 'Berg', 'Haugen'],
+        companies: ['Fjordline AS', 'Nordlys Handel AS', 'Fjellvik Maskin AS', 'Bergen Logistikk AS', 'Havbruk Partner AS', 'Skagerrak Digital AS'],
+        cities: ['Oslo', 'Bergen', 'Trondheim', 'Stavanger', 'Tromsø', 'Drammen', 'Kristiansand', 'Ålesund'],
+        domains: ['eksempel.no', 'prove.no', 'demo.no'],
+        phoneTemplate: '+47 9## ## ###',
+        words: ['gjennomgang', 'kvartal', 'oppdatering', 'faktura', 'kunde', 'levering', 'avtale', 'fornyelse', 'rapport', 'oppfølging', 'møte', 'bestilling'],
+    },
+    'sv-SE': {
+        firstNames: ['Erik', 'Astrid', 'Lars', 'Maja', 'Anders', 'Elsa', 'Johan', 'Linnéa', 'Gustav', 'Åsa'],
+        lastNames: ['Andersson', 'Johansson', 'Karlsson', 'Nilsson', 'Eriksson', 'Larsson', 'Olsson', 'Persson', 'Svensson', 'Gustafsson'],
+        companies: ['Norrlands Handel AB', 'Östersund Teknik AB', 'Göta Logistik AB', 'Skärgården Livs AB', 'Malmö Digital AB', 'Vättern Verktyg AB'],
+        cities: ['Stockholm', 'Göteborg', 'Malmö', 'Uppsala', 'Västerås', 'Örebro', 'Linköping', 'Umeå'],
+        domains: ['exempel.se', 'prov.se', 'demo.se'],
+        phoneTemplate: '+46 70 ### ## ##',
+        words: ['granskning', 'kvartal', 'uppdatering', 'faktura', 'kund', 'leverans', 'avtal', 'förnyelse', 'rapport', 'uppföljning', 'möte', 'beställning'],
+    },
+    'de-DE': {
+        firstNames: ['Lukas', 'Anna', 'Felix', 'Marie', 'Jonas', 'Sophie', 'Maximilian', 'Lena', 'Paul', 'Jördis'],
+        lastNames: ['Müller', 'Schmidt', 'Schneider', 'Fischer', 'Weber', 'Meyer', 'Wagner', 'Becker', 'Schulz', 'Hoffmann'],
+        companies: ['Rheinwerk GmbH', 'Nordsee Handel GmbH', 'Isar Logistik GmbH', 'Schwarzwald Technik GmbH', 'Elbe Digital GmbH', 'Bayern Werkzeug GmbH'],
+        cities: ['Berlin', 'Hamburg', 'München', 'Köln', 'Frankfurt', 'Stuttgart', 'Düsseldorf', 'Leipzig'],
+        domains: ['beispiel.de', 'muster.de', 'demo.de'],
+        phoneTemplate: '+49 151 ########',
+        words: ['prüfung', 'quartal', 'aktualisierung', 'rechnung', 'kunde', 'lieferung', 'vertrag', 'verlängerung', 'bericht', 'nachfassen', 'termin', 'bestellung'],
+    },
+} as Record<string, SampleLocale>));
+
+const languageDefaults = new Map<string, string>([
+    ['en', 'en-GB'],
+    ['nb', 'nb-NO'],
+    ['nn', 'nb-NO'],
+    ['no', 'nb-NO'],
+    ['sv', 'sv-SE'],
+    ['de', 'de-DE'],
+]);
+
+/** The locale used when a tag matches no pool. */
+export const defaultSampleLocale = 'en-GB';
+
+/** The locale tags with their own pools. */
+export const sampleLocaleTags: string[] = [...locales.keys()];
+
+/**
+ * Resolves a BCP 47 tag to a pool: the exact tag (language lower case, region upper case), else the
+ * language's default pool, else {@link defaultSampleLocale}.
+ */
+export function sampleLocaleFor(tag: string | undefined): SampleLocale {
+    const parts = (tag ?? '').trim().split('-');
+    const language = parts[0].toLowerCase();
+    const region = parts.length > 1 ? parts[1].toUpperCase() : '';
+    const exact = region === '' ? undefined : locales.get(`${language}-${region}`);
+    return exact ?? locales.get(languageDefaults.get(language) ?? defaultSampleLocale)!;
+}

package/sampleData/validateSampleDataPack.ts

@@ -0,0 +1,48 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SampleDataPack } from '@cratis/scene.model';
+import { isValidSampleDataOwner, sampleDataIdPattern, sampleDataLocalePattern } from './sampleDataRules';
+
+/**
+ * Checks a pack's schema: an id of the allowed form, a title, a well-formed locale tag, an owner that is
+ * `user` or `blueprint:<id>`, and sets with a shape each, none repeated. The C# engine
+ * (`SampleDataValidation.ValidatePack`) reports the same problems in the same order; both are asserted against
+ * `sample-data-resolution-fixtures.json`.
+ */
+export function validateSampleDataPack(pack: SampleDataPack): string[] {
+    const problems: string[] = [];
+    const id = pack.id ?? '';
+    const label = id.trim() === '' ? 'Sample data pack' : `Sample data pack '${id}'`;
+
+    if (id.trim() === '') {
+        problems.push('Sample data pack declares no id');
+    } else if (!sampleDataIdPattern.test(id)) {
+        problems.push(`${label} declares an invalid id; use lower-case letters, digits and '.', '_' or '-' separators`);
+    }
+
+    if ((pack.title ?? '').trim() === '') problems.push(`${label} declares no title`);
+
+    if ((pack.locale ?? '').trim() === '') {
+        problems.push(`${label} declares no locale`);
+    } else if (!sampleDataLocalePattern.test(pack.locale)) {
+        problems.push(`${label} declares an invalid locale '${pack.locale}'`);
+    }
+
+    if (!isValidSampleDataOwner(pack.owner)) {
+        problems.push(`${label} declares owner '${pack.owner ?? ''}', which is neither 'user' nor 'blueprint:<id>'`);
+    }
+
+    const seen = new Set<string>();
+    for (const set of pack.sets ?? []) {
+        if ((set.shape ?? '').trim() === '') {
+            problems.push(`${label} declares a set without a shape`);
+        } else if (seen.has(set.shape)) {
+            problems.push(`${label} declares shape '${set.shape}' more than once`);
+        } else {
+            seen.add(set.shape);
+        }
+    }
+
+    return problems;
+}

package/sampleData/validateSampleDataPackages.ts

@@ -0,0 +1,79 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { PackageKind } from '@cratis/scene.model';
+import { SampleDataPackSource } from './SampleDataPackSource';
+import { isValidSampleDataOwner, isValidSampleDataPath, sampleDataIdPattern, sampleDataLocalePattern } from './sampleDataRules';
+import { validateSampleDataPack } from './validateSampleDataPack';
+
+/**
+ * Checks the sample data the given packages ship, in package then reference order: only a Blueprint package may
+ * ship packs; each reference needs a valid id, a title, a locale tag and a `sampleData/*.json` path, with no id
+ * or path repeated; and each loaded pack must be valid, match its reference's id and locale, be owned by a
+ * blueprint, and be one the manifest references. The C# engine (`SampleDataValidation.ValidatePackages`)
+ * reports the same problems in the same order.
+ */
+export function validateSampleDataPackages(sources: readonly SampleDataPackSource[]): string[] {
+    const problems: string[] = [];
+
+    for (const source of sources) {
+        const manifest = source.manifest;
+        const references = manifest.sampleData ?? [];
+        const owner = `Package '${manifest.name}'`;
+
+        if (references.length > 0 && manifest.kind !== PackageKind.Blueprint) {
+            problems.push(`${owner} ships sample data but is not a Blueprint package`);
+        }
+
+        const ids = new Set<string>();
+        const paths = new Set<string>();
+        for (const reference of references) {
+            const label = `${owner} sample data pack '${reference.id ?? ''}'`;
+            if ((reference.id ?? '').trim() === '') {
+                problems.push(`${owner} declares a sample data pack without an id`);
+            } else if (!sampleDataIdPattern.test(reference.id)) {
+                problems.push(`${label} has an invalid id`);
+            } else if (ids.has(reference.id)) {
+                problems.push(`${label} is declared more than once`);
+            } else {
+                ids.add(reference.id);
+            }
+
+            if ((reference.title ?? '').trim() === '') problems.push(`${label} declares no title`);
+
+            if ((reference.locale ?? '').trim() === '') {
+                problems.push(`${label} declares no locale`);
+            } else if (!sampleDataLocalePattern.test(reference.locale)) {
+                problems.push(`${label} declares an invalid locale '${reference.locale}'`);
+            }
+
+            if (!isValidSampleDataPath(reference.path)) {
+                problems.push(`${label} declares path '${reference.path ?? ''}', which is not 'sampleData/<name>.json'`);
+            } else if (paths.has(reference.path)) {
+                problems.push(`${label} reuses the path '${reference.path}'`);
+            } else {
+                paths.add(reference.path);
+            }
+        }
+
+        for (const pack of source.packs ?? []) {
+            const label = `${owner} sample data pack '${pack.id ?? ''}'`;
+            problems.push(...validateSampleDataPack(pack));
+            const reference = references.find(candidate => candidate.id === pack.id);
+            if (reference === undefined) {
+                problems.push(`${label} is not referenced by the package's sampleData`);
+                continue;
+            }
+
+            if (reference.locale !== pack.locale) {
+                problems.push(`${label} has locale '${pack.locale}' but its reference declares '${reference.locale}'`);
+            }
+
+            if (isValidSampleDataOwner(pack.owner) && pack.owner === 'user') {
+                problems.push(`${label} must be owned by a blueprint, not 'user'`);
+            }
+        }
+    }
+
+    return problems;
+}

package/sampleData/validateSampleDataSelection.ts

@@ -0,0 +1,55 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SampleDataPack, SampleDataSelection } from '@cratis/scene.model';
+
+/**
+ * Checks an application's sample data selection against the packs available: the active pack and every bound
+ * pack must exist, mappings and bindings must be complete and not repeated, and one read model must not be fed
+ * by two different shapes. The C# engine (`SampleDataValidation.ValidateSelection`) reports the same problems in
+ * the same order.
+ */
+export function validateSampleDataSelection(selection: SampleDataSelection, packs: readonly SampleDataPack[]): string[] {
+    const problems: string[] = [];
+    const known = new Set(packs.map(pack => pack.id));
+
+    if (selection.activePack !== undefined && selection.activePack !== null && !known.has(selection.activePack)) {
+        problems.push(`The active sample data pack '${selection.activePack}' is not available`);
+    }
+
+    const pairs = new Set<string>();
+    const shapeByReadModel = new Map<string, string>();
+    for (const mapping of selection.mappings ?? []) {
+        if ((mapping.shape ?? '').trim() === '') {
+            problems.push('A sample data mapping declares no shape');
+        } else if ((mapping.readModel ?? '').trim() === '') {
+            problems.push(`The sample data mapping for shape '${mapping.shape}' declares no read model`);
+        } else if (pairs.has(`${mapping.shape}\u0000${mapping.readModel}`)) {
+            problems.push(`The sample data mapping '${mapping.shape}' to '${mapping.readModel}' is declared more than once`);
+        } else {
+            pairs.add(`${mapping.shape}\u0000${mapping.readModel}`);
+            const existing = shapeByReadModel.get(mapping.readModel);
+            if (existing === undefined) {
+                shapeByReadModel.set(mapping.readModel, mapping.shape);
+            } else {
+                problems.push(`The read model '${mapping.readModel}' is mapped from both shape '${existing}' and shape '${mapping.shape}'`);
+            }
+        }
+    }
+
+    const targets = new Set<string>();
+    for (const binding of selection.bindings ?? []) {
+        if ((binding.target ?? '').trim() === '') {
+            problems.push('A sample data binding declares no target');
+        } else if (targets.has(binding.target)) {
+            problems.push(`The sample data target '${binding.target}' is bound more than once`);
+        } else {
+            targets.add(binding.target);
+            if (!known.has(binding.pack)) {
+                problems.push(`The sample data binding for '${binding.target}' names pack '${binding.pack ?? ''}', which is not available`);
+            }
+        }
+    }
+
+    return problems;
+}