@cratis/scene.engine 4.25.0 → 4.26.0

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;
+}