@contentful/experience-design-system-types 2.42.1-dev-build-f69db6bf.0 → 2.43.0-alpha.0

package/dist/src/cdf/property-validation.js

@@ -0,0 +1,211 @@
+import { CDF_PROPERTY_TYPES, CDF_PROPERTY_CATEGORIES } from './vocabularies.js';
+import { childPath, cloneJson, jsonValueIssue, own } from '../property-contract/json-value.js';
+import { validateTargetDefinition } from '../property-contract/target-definition.js';
+import { SourceInputAssociationSchema } from '../source-input-association.js';
+import { finiteValuesIssue } from './finite-values.js';
+const targetTypes = {
+    string: 'String',
+    number: 'Number',
+    boolean: 'Boolean',
+    array: 'Array',
+    record: 'Record',
+    richtext: 'String',
+    media: 'String',
+    link: 'String',
+    token: 'String',
+    Integer: 'Integer',
+    DateTime: 'DateTime',
+    Literal: 'Literal',
+    RichText: 'RichText',
+    JSON: 'JSON',
+    ResourceLink: 'ResourceLink',
+    DiscriminatedUnion: 'DiscriminatedUnion',
+};
+export function cdfToTarget(d) {
+    const t = { type: targetTypes[d.$type] };
+    if (own(d, '$required'))
+        t.required = d.$required;
+    if (own(d, '$description'))
+        t.description = d.$description;
+    if (own(d, '$default'))
+        t.defaultValue = d.$default;
+    if (d.$values)
+        t.values = d.$values;
+    if (own(d, 'value'))
+        t.value = d.value;
+    if (d.valueType)
+        t.valueType = cdfToTarget(d.valueType);
+    if (d.discriminator !== undefined)
+        t.discriminator = d.discriminator;
+    if (d.members)
+        t.members = d.members.map(cdfToTarget);
+    if (d.allowedResources)
+        t.allowedResources = d.allowedResources;
+    if (d.$items)
+        t.items = cdfToTarget(d.$items);
+    if (d.$fields)
+        t.fields = Object.fromEntries(Object.entries(d.$fields).map(([key, field]) => [key, cdfToTarget(field)]));
+    return t;
+}
+/** Decode complete target metadata without narrowing it to a type name. */
+export function targetToCDF(d) {
+    const types = {
+        String: 'string',
+        Number: 'number',
+        Boolean: 'boolean',
+        Array: 'array',
+        Record: 'record',
+        Integer: 'Integer',
+        DateTime: 'DateTime',
+        Literal: 'Literal',
+        RichText: 'RichText',
+        JSON: 'JSON',
+        ResourceLink: 'ResourceLink',
+        DiscriminatedUnion: 'DiscriminatedUnion',
+    };
+    const field = { $type: types[d.type] };
+    if (own(d, 'required'))
+        field.$required = d.required;
+    if (own(d, 'description'))
+        field.$description = d.description;
+    if (own(d, 'defaultValue'))
+        field.$default = cloneJson(d.defaultValue);
+    if (d.values)
+        field.$values = cloneJson(d.values);
+    if (d.items)
+        field.$items = targetToCDF(d.items);
+    if (d.fields)
+        field.$fields = Object.fromEntries(Object.entries(d.fields).map(([key, child]) => [key, targetToCDF(child)]));
+    if (own(d, 'value'))
+        field.value = cloneJson(d.value);
+    if (d.valueType)
+        field.valueType = targetToCDF(d.valueType);
+    if (d.discriminator !== undefined)
+        field.discriminator = d.discriminator;
+    if (d.members)
+        field.members = d.members.map(targetToCDF);
+    if (d.allowedResources)
+        field.allowedResources = cloneJson(d.allowedResources);
+    return field;
+}
+/** All recursive grammar children retain their exact paths, including exclusive members. */
+export function cdfDefinitionChildren(definition) {
+    return [
+        ...(definition.$items ? [{ definition: definition.$items, path: '/$items' }] : []),
+        ...(definition.valueType ? [{ definition: definition.valueType, path: '/valueType' }] : []),
+        ...Object.entries(definition.$fields ?? {}).map(([key, field]) => ({
+            definition: field,
+            path: childPath('/$fields', key),
+        })),
+        ...(definition.members ?? []).map((member, index) => ({ definition: member, path: '/members/' + index })),
+    ];
+}
+export function containsCDFDefinitionType(definition, type) {
+    return (definition.$type === type ||
+        cdfDefinitionChildren(definition).some((child) => containsCDFDefinitionType(child.definition, type)));
+}
+export function validateCDFProperty(input, requireCategory = true) {
+    const unsafe = jsonValueIssue(input);
+    if (unsafe)
+        return { valid: false, issues: [unsafe] };
+    const issues = [];
+    const walk = (value, path, root, depth) => {
+        if (depth > 64 || !value || typeof value !== 'object' || Array.isArray(value)) {
+            issues.push({ path, message: 'Expected bounded property definition' });
+            return;
+        }
+        const d = value;
+        const add = (key, message) => issues.push({ path: childPath(path, key), message });
+        if (!CDF_PROPERTY_TYPES.includes(d.$type)) {
+            add('$type', 'Unknown CDF type');
+            return;
+        }
+        if ((root && requireCategory) || own(d, '$category'))
+            if (!CDF_PROPERTY_CATEGORIES.includes(d.$category))
+                add('$category', 'Unknown category');
+        const allowed = new Set(['$type', '$category', '$description', '$required', '$default', '$values']);
+        if (root)
+            allowed.add('$sourceInput');
+        if (own(d, '$sourceInput') &&
+            !SourceInputAssociationSchema.safeParse(d.$sourceInput).success)
+            add('$sourceInput', 'Invalid source input association');
+        if (d.$type === 'array')
+            allowed.add('$items');
+        if (d.$type === 'record')
+            allowed.add('$fields');
+        if (['Integer', 'DateTime', 'Literal', 'RichText', 'JSON', 'ResourceLink', 'DiscriminatedUnion'].includes(d.$type) &&
+            d.$category !== undefined &&
+            d.$category !== 'content')
+            add('$category', 'Richer representations require content category');
+        if (d.$type === 'Literal') {
+            allowed.add('value');
+            allowed.add('valueType');
+            walk(d.valueType, childPath(path, 'valueType'), false, depth + 1);
+        }
+        if (d.$type === 'ResourceLink')
+            allowed.add('allowedResources');
+        if (d.$type === 'DiscriminatedUnion') {
+            allowed.add('discriminator');
+            allowed.add('members');
+            if (!Array.isArray(d.members))
+                add('members', 'Expected complete union members');
+            else
+                d.members.forEach((member, index) => walk(member, childPath(childPath(path, 'members'), index), false, depth + 1));
+        }
+        if (d.$type === 'token') {
+            allowed.add('$token.kind');
+            allowed.add('$token.allowed');
+        }
+        for (const key of Object.keys(d))
+            if (!allowed.has(key))
+                add(key, 'Unexpected property metadata');
+        if (own(d, '$description') && typeof d.$description !== 'string')
+            add('$description', 'Expected string');
+        if (own(d, '$values')) {
+            if (!Array.isArray(d.$values))
+                add('$values', 'Expected array');
+            else {
+                const issue = finiteValuesIssue(d.$type, d.$values);
+                if (issue)
+                    issues.push({
+                        path: issue.index === undefined
+                            ? childPath(path, '$values')
+                            : childPath(childPath(path, '$values'), issue.index),
+                        message: issue.message,
+                    });
+            }
+        }
+        if (own(d, '$required') && typeof d.$required !== 'boolean')
+            add('$required', 'Expected boolean');
+        if (own(d, '$token.kind') && typeof d['$token.kind'] !== 'string')
+            add('$token.kind', 'Expected string');
+        if (own(d, '$token.allowed') &&
+            (!Array.isArray(d['$token.allowed']) || !d['$token.allowed'].every((v) => typeof v === 'string')))
+            add('$token.allowed', 'Expected string paths');
+        if (d.$type === 'array')
+            walk(d.$items, childPath(path, '$items'), false, depth + 1);
+        if (d.$type === 'record') {
+            if (!d.$fields ||
+                typeof d.$fields !== 'object' ||
+                Array.isArray(d.$fields) ||
+                Object.keys(d.$fields).length === 0)
+                add('$fields', 'Expected nonempty field dictionary');
+            else
+                for (const [key, field] of Object.entries(d.$fields))
+                    walk(field, childPath(childPath(path, '$fields'), key), false, depth + 1);
+        }
+    };
+    walk(input, '', true, 0);
+    if (!issues.length) {
+        for (const issue of validateTargetDefinition(cdfToTarget(input)).issues)
+            issues.push({
+                path: issue.path
+                    .replace(/\/defaultValue(?=\/|$)/g, '/$default')
+                    .replace(/\/items(?=\/|$)/g, '/$items')
+                    .replace(/\/fields(?=\/|$)/g, '/$fields')
+                    .replace(/\/values(?=\/|$)/g, '/$values'),
+                message: issue.message,
+            });
+    }
+    return { valid: !issues.length, issues };
+}

package/dist/src/cdf/representation-validation.d.ts

@@ -0,0 +1,6 @@
+import type { CDFComponentEntry, CDFValidationError } from './types.js';
+/** Check saved plan integrity and exact physical closure independently of mapper availability. */
+export declare function validateRepresentationClosure(components: Array<{
+    key: string;
+    entry: CDFComponentEntry;
+}>): CDFValidationError[];

package/dist/src/cdf/representation-validation.js

@@ -0,0 +1,182 @@
+import { contentDigest } from '../property-contract/content-digest.js';
+import { childPath, cloneJson, jsonEqual, own } from '../property-contract/json-value.js';
+import { validateRepresentationPlan } from '../property-contract/representation-plan.js';
+/** Check saved plan integrity and exact physical closure independently of mapper availability. */
+export function validateRepresentationClosure(components) {
+    const errors = [];
+    const entries = new Map(components.map((component) => [component.key, component.entry]));
+    const claimed = new Set();
+    const owners = new Set();
+    if (entries.size !== components.length)
+        errors.push({ path: '/', message: 'Duplicate complete component identity' });
+    for (const { key, entry } of components) {
+        for (const [property, plan] of Object.entries(entry.$representationPlans ?? {})) {
+            const path = childPath(childPath(childPath('', key), '$representationPlans'), property);
+            const fail = (message) => {
+                errors.push({ path, message });
+            };
+            try {
+                for (const issue of validateRepresentationPlan(plan, plan.sourceModel, plan.contextSnapshot))
+                    fail(issue.message);
+                if (owners.has(plan.identity.propertyId))
+                    fail('Duplicate representation source owner');
+                owners.add(plan.identity.propertyId);
+                const input = cloneJson(plan);
+                const { id: _id, ...unsigned } = input;
+                for (const generated of unsigned.models) {
+                    delete generated.entry.$model;
+                    for (const slot of Object.values(generated.entry.$slots ?? {}))
+                        if (slot.$modelBinding)
+                            slot.$modelBinding.planId = '';
+                }
+                if (unsigned.attachment?.definition.$modelBinding)
+                    unsigned.attachment.definition.$modelBinding.planId = '';
+                if (contentDigest(unsigned) !== plan.id)
+                    fail('Stale or altered representation plan identity');
+                if (plan.identity.key !== property ||
+                    plan.identity.propertyId !== JSON.stringify([plan.identity.componentId, property]))
+                    fail('Representation property owner disagrees');
+                const graph = plan.logicalGraph;
+                const nodes = new Map(graph.nodes.map((node) => [node.id, node]));
+                const mappings = new Map(plan.mappings.map((mapping) => [mapping.nodeId, mapping]));
+                if (graph.authority !== 'compiler' ||
+                    graph.rootId !== plan.identity.nodeId ||
+                    !nodes.has(graph.rootId) ||
+                    nodes.size !== graph.nodes.length ||
+                    mappings.size !== plan.mappings.length ||
+                    mappings.size !== nodes.size)
+                    fail('Incomplete or duplicate logical source accounting');
+                const reached = new Set();
+                const pending = [graph.rootId];
+                while (pending.length) {
+                    const nodeId = pending.pop();
+                    if (reached.has(nodeId))
+                        continue;
+                    reached.add(nodeId);
+                    const node = nodes.get(nodeId);
+                    if (!node) {
+                        fail('Dangling logical source relationship');
+                        continue;
+                    }
+                    const mapping = mappings.get(nodeId);
+                    if (!mapping ||
+                        mapping.sourceNodeId !== node.sourceNodeId ||
+                        !jsonEqual(mapping.path, node.path) ||
+                        mapping.required !== node.required ||
+                        mapping.readonly !== node.readonly ||
+                        mapping.occurrenceReadonly !== node.occurrenceReadonly ||
+                        mapping.intrinsicReadonly !== node.intrinsicReadonly ||
+                        mapping.nullable !== (node.nullable ?? null) ||
+                        mapping.undefinable !== (node.undefinable ?? null) ||
+                        !jsonEqual(mapping.defaultIntent, node.defaultIntent))
+                        fail('Mapping changes retained source occurrence evidence');
+                    if (mapping?.targetNodeId && !nodes.has(mapping.targetNodeId))
+                        fail('Dangling source mapping target');
+                    if (mapping?.disposition === 'reconstruction') {
+                        const operation = mapping.reconstruction;
+                        if (!operation)
+                            fail('Missing source reconstruction operation');
+                        else if (operation.kind === 'fixed-value') {
+                            if (!node.required ||
+                                node.nullable !== false ||
+                                node.undefinable !== false ||
+                                node.domain.provenance !== 'compiler' ||
+                                node.domain.openness !== 'closed' ||
+                                node.domain.declaredValues.length !== 1 ||
+                                !jsonEqual(node.domain.declaredValues[0], operation.value))
+                                fail('Fixed reconstruction changes the intrinsic source value or presence');
+                        }
+                        else if (operation.kind === 'object-envelope') {
+                            if (node.kind !== 'record' ||
+                                node.fields?.length !== 1 ||
+                                node.fields[0].key !== operation.field ||
+                                node.fields[0].nodeId !== operation.valueNodeId)
+                                fail('Object reconstruction changes source shape');
+                        }
+                        else if (operation.kind === 'ordered-array') {
+                            if (node.kind !== 'array' || node.items?.length !== 1 || node.items[0] !== operation.itemNodeId)
+                                fail('Array reconstruction changes source shape');
+                        }
+                        else if (operation.kind === 'optional-value') {
+                            const values = (node.alternatives ?? []).filter((id) => !['null', 'undefined', 'never'].includes(nodes.get(id)?.kind ?? ''));
+                            if (node.kind !== 'union' || values.length !== 1 || values[0] !== operation.valueNodeId)
+                                fail('Optional reconstruction changes source alternatives');
+                        }
+                        else if (operation.kind === 'empty-value' && operation.state !== node.kind)
+                            fail('Empty reconstruction changes source state');
+                    }
+                    else if (mapping?.reconstruction)
+                        fail('Reconstruction operation has no reconstruction disposition');
+                    pending.push(...(node.fields?.map((field) => field.nodeId) ?? []), ...(node.items ?? []), ...(node.alternatives ?? []), ...(node.indexSignatures?.map((signature) => signature.valueNodeId) ?? []));
+                }
+                if (reached.size !== nodes.size)
+                    fail('Disconnected logical source accounting');
+                if (plan.sdkValid &&
+                    (plan.issues.length ||
+                        plan.mappings.some((mapping) => mapping.disposition === 'held') ||
+                        graph.coverage !== 'complete-within-declared-bound'))
+                    fail('Representation validity contradicts held source evidence');
+                if (plan.kind === 'native') {
+                    if (plan.models.length || plan.attachment || !jsonEqual(entry.$properties[property], plan.nativeDefinition))
+                        fail('Native representation disagrees with the complete component');
+                }
+                else if (!plan.attachment ||
+                    own(entry.$properties, property) ||
+                    !jsonEqual(entry.$slots?.[plan.attachment.slot], plan.attachment.definition))
+                    fail('Model attachment disagrees with the complete component');
+                const models = new Map(plan.models.map((generated) => [generated.key, generated]));
+                if (models.size !== plan.models.length)
+                    fail('Duplicate representation model identity');
+                for (const generated of plan.models) {
+                    const binding = generated.entry.$model;
+                    if (!binding ||
+                        binding.planId !== plan.id ||
+                        binding.componentId !== plan.identity.componentId ||
+                        binding.propertyId !== plan.identity.propertyId ||
+                        binding.nodeId !== generated.nodeId ||
+                        binding.sourceNodeId !== nodes.get(generated.nodeId)?.sourceNodeId)
+                        fail('Model source owner disagrees');
+                    if (!jsonEqual(entries.get(generated.key), generated.entry))
+                        fail('Missing or altered representation model definition');
+                    if (claimed.has(generated.key))
+                        fail('Duplicate representation model owner');
+                    claimed.add(generated.key);
+                    for (const slot of Object.values(generated.entry.$slots ?? {})) {
+                        const owner = slot.$modelBinding;
+                        if (!owner ||
+                            owner.planId !== plan.id ||
+                            owner.componentId !== plan.identity.componentId ||
+                            owner.propertyId !== plan.identity.propertyId ||
+                            owner.sourceNodeId !== nodes.get(owner.nodeId)?.sourceNodeId ||
+                            (slot.$allowedComponents ?? []).some((allowed) => !models.has(allowed)))
+                            fail('Model relationship changes source ownership or closure');
+                    }
+                }
+                const physical = new Set();
+                const dependencies = [...(plan.attachment?.definition.$allowedComponents ?? [])];
+                while (dependencies.length) {
+                    const modelKey = dependencies.pop();
+                    if (physical.has(modelKey))
+                        continue;
+                    physical.add(modelKey);
+                    const generated = models.get(modelKey);
+                    if (!generated) {
+                        fail('Missing representation dependency');
+                        continue;
+                    }
+                    for (const slot of Object.values(generated.entry.$slots ?? {}))
+                        dependencies.push(...(slot.$allowedComponents ?? []));
+                }
+                if (physical.size !== models.size)
+                    fail('Orphan representation dependency');
+            }
+            catch {
+                fail('Malformed complete representation metadata');
+            }
+        }
+    }
+    for (const { key, entry } of components)
+        if (entry.$model && !claimed.has(key))
+            errors.push({ path: childPath('', key), message: 'Model definition has no complete source owner' });
+    return errors;
+}