@elytracms/core 0.0.6

package/dist/cms-core/validate-document.js

@@ -0,0 +1,871 @@
+import { documentKey } from './documents';
+import { readAssetId, readDocumentRef } from './envelopes';
+import { isFieldLocalized, resolveField } from './localization';
+import { hasParentCycle, parentRelationField } from './hierarchy';
+import { cmsIssue } from './issues';
+/** Build a `DocumentStore` from a flat list of documents. */
+export function createDocumentStore(docs) {
+    const byKey = new Map();
+    const issues = [];
+    for (const doc of docs) {
+        const key = documentKey(doc);
+        if (byKey.has(key)) {
+            issues.push(cmsIssue({
+                code: 'duplicate-document',
+                message: `Duplicate document "${doc.id}" in collection "${doc.collection}".`,
+                path: ['documents', key],
+                collectionId: doc.collection,
+                documentId: doc.id,
+            }));
+            continue;
+        }
+        byKey.set(key, doc);
+    }
+    return {
+        issues,
+        has: (ref) => byKey.has(documentKey(ref)),
+        get: (ref) => byKey.get(documentKey(ref)),
+        list: () => [...byKey.values()],
+    };
+}
+function isEmpty(value) {
+    if (value === undefined || value === null)
+        return true;
+    if (typeof value === 'string')
+        return value.length === 0;
+    if (Array.isArray(value))
+        return value.length === 0;
+    // EC-253: a plain object with no keys is empty — so a required `object` field
+    // whose value is `{}` is flagged missing. Object-shaped values that DO carry
+    // keys (relation refs `{collection,id}`, rich-text envelopes) are never empty.
+    if (isPlainObject(value))
+        return Object.keys(value).length === 0;
+    return false;
+}
+/** A non-null, non-array object — the shape an `object` field value takes (EC-253). */
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Whether a value must still be validated even though {@link isEmpty} is true
+ * (EC-253). A PRESENT plain object of an `object` field is validated even with no
+ * keys, so its required subfields surface (`{}` is not the same as absent); every
+ * other empty/absent value has nothing to validate — `required` owns presence.
+ */
+function isPresentObjectValue(field, value) {
+    return field.type === 'object' && isPlainObject(value);
+}
+// EC-277: relation values are self-typed (`{ type:'reference', collection, id }`);
+// `readDocumentRef` unwraps that AND legacy bare `{ collection, id }` (lazy-on-read).
+const coerceRef = readDocumentRef;
+function validateScalarType(ctx, issues) {
+    const { field, value, path, collection, documentId } = ctx;
+    const bad = (detail) => issues.push(cmsIssue({
+        code: 'invalid-field-value',
+        message: `Field "${field.name}" ${detail}.`,
+        path,
+        collectionId: collection.id,
+        documentId,
+        meta: { field: field.name, type: field.type },
+    }));
+    switch (field.type) {
+        case 'text':
+            if (typeof value !== 'string')
+                bad('expects a string');
+            break;
+        case 'richText':
+            // A rich-text value is either a plain string (CMS markdown/HTML) or the
+            // structured @elytracms/rich-text storage envelope (an object) carrying
+            // formatting + composition embeds (EC-159/EC-189). Mirrors the prop-side
+            // `checkScalarType`; deep validation is delegated (the renderer parse guard
+            // + the injected rich-text-embed validator).
+            if (typeof value !== 'string' && !(typeof value === 'object' && value !== null)) {
+                bad('expects rich-text content (a string or a rich-text value)');
+            }
+            break;
+        case 'number':
+            if (typeof value !== 'number' || Number.isNaN(value))
+                bad('expects a number');
+            break;
+        case 'boolean':
+            if (typeof value !== 'boolean')
+                bad('expects a boolean');
+            break;
+        case 'date':
+            // Accept ISO date strings or epoch numbers; reject anything unparseable.
+            if (typeof value === 'string') {
+                if (Number.isNaN(Date.parse(value)))
+                    bad('expects a valid date string');
+            }
+            else if (typeof value !== 'number') {
+                bad('expects a date (ISO string or epoch number)');
+            }
+            break;
+        case 'select': {
+            const allowed = new Set(field.options.map((o) => o.value));
+            const values = field.multiple ? (Array.isArray(value) ? value : [value]) : [value];
+            for (const v of values) {
+                if (typeof v !== 'string' || !allowed.has(v)) {
+                    bad(`has value "${String(v)}" not among its options`);
+                }
+            }
+            break;
+        }
+        case 'object':
+            // EC-253: only the TOP-LEVEL shape is checked here (an array of objects for
+            // `many`, a single object for `one`); recursion into the subfields lives in
+            // `validateObject`, which skips malformed items this already reported.
+            if (field.cardinality === 'many') {
+                if (!Array.isArray(value) || value.some((item) => !isPlainObject(item))) {
+                    bad('expects a list of objects');
+                }
+            }
+            else if (!isPlainObject(value)) {
+                bad('expects an object');
+            }
+            break;
+        case 'relation':
+        case 'asset':
+        case 'blocks':
+            // Validated structurally elsewhere (targets / composition), not as scalars.
+            break;
+        default: {
+            // Exhaustiveness: a new field type must add a case above (EC-253).
+            const _exhaustive = field;
+            void _exhaustive;
+        }
+    }
+}
+/**
+ * Validate a `blocks` composition field value via the injected callback (EC-188).
+ * The composition tree is validated against the field's `allow` vocabulary + the
+ * component registry by the studio-supplied `validateComposition`; each finding is
+ * wrapped into a field-keyed issue so it surfaces inline like any other field
+ * error. A no-op when the field is not a `blocks` field or no validator is wired
+ * (e.g. headless contexts without a registry).
+ */
+function validateBlocks(ctx, issues, validateComposition) {
+    if (ctx.field.type !== 'blocks' || !validateComposition)
+        return;
+    const { field, value, path, collection, documentId } = ctx;
+    for (const finding of validateComposition(value, field)) {
+        issues.push(cmsIssue({
+            code: 'invalid-field-value',
+            severity: finding.severity ?? 'error',
+            message: `Field "${field.name}": ${finding.message}`,
+            path,
+            collectionId: collection.id,
+            documentId,
+            meta: {
+                field: field.name,
+                type: 'blocks',
+                ...(finding.nodePath ? { nodePath: finding.nodePath } : {}),
+            },
+        }));
+    }
+}
+/**
+ * Validate the composition embeds inside a `richText` field value via the injected
+ * callback (EC-189). A rich-text value may carry `componentEmbed` nodes, each
+ * holding a single `ComponentNode` constrained by the field's `allow` vocabulary —
+ * the SAME leash a `blocks` field uses, applied to prose embeds. The studio-supplied
+ * `validateRichTextEmbeds` walks the embeds and validates each via
+ * `validateCompositionValue`; each finding is wrapped into a field-keyed issue,
+ * carrying the rich-text node path. A no-op when the field is not `richText` or no
+ * validator is wired (e.g. headless contexts without a registry).
+ */
+function validateRichTextEmbeds(ctx, issues, validateRichText) {
+    if (ctx.field.type !== 'richText' || !validateRichText)
+        return;
+    const { field, value, path, collection, documentId } = ctx;
+    for (const finding of validateRichText(value, field)) {
+        issues.push(cmsIssue({
+            code: 'invalid-field-value',
+            severity: finding.severity ?? 'error',
+            message: `Field "${field.name}": ${finding.message}`,
+            path,
+            collectionId: collection.id,
+            documentId,
+            meta: {
+                field: field.name,
+                type: 'richText',
+                ...(finding.nodePath ? { nodePath: finding.nodePath } : {}),
+            },
+        }));
+    }
+}
+function validateConstraints(ctx, issues) {
+    const { field, value, path, collection, documentId } = ctx;
+    const rules = field.validation;
+    if (!rules)
+        return;
+    const push = (detail) => issues.push(cmsIssue({
+        code: 'invalid-field-value',
+        message: `Field "${field.name}" ${detail}.`,
+        path,
+        collectionId: collection.id,
+        documentId,
+        meta: { field: field.name },
+    }));
+    if (typeof value === 'string') {
+        if (rules.min !== undefined && value.length < rules.min)
+            push(`is shorter than min length ${rules.min}`);
+        if (rules.max !== undefined && value.length > rules.max)
+            push(`is longer than max length ${rules.max}`);
+        if (rules.pattern !== undefined) {
+            let re;
+            try {
+                re = new RegExp(rules.pattern);
+            }
+            catch {
+                re = undefined;
+            }
+            if (re && !re.test(value))
+                push(`does not match pattern ${rules.pattern}`);
+        }
+    }
+    else if (typeof value === 'number') {
+        if (rules.min !== undefined && value < rules.min)
+            push(`is less than min ${rules.min}`);
+        if (rules.max !== undefined && value > rules.max)
+            push(`is greater than max ${rules.max}`);
+    }
+    else if (Array.isArray(value)) {
+        if (rules.min !== undefined && value.length < rules.min)
+            push(`has fewer than ${rules.min} items`);
+        if (rules.max !== undefined && value.length > rules.max)
+            push(`has more than ${rules.max} items`);
+    }
+}
+function validateRelation(ctx, issues) {
+    const { field, value, path, collection, registry, store, documentId } = ctx;
+    if (field.type !== 'relation')
+        return;
+    if (!registry.has(field.target)) {
+        issues.push(cmsIssue({
+            code: 'unknown-relation-target',
+            message: `Relation field "${field.name}" targets unknown collection "${field.target}".`,
+            path,
+            collectionId: collection.id,
+            documentId,
+            meta: { field: field.name, target: field.target },
+        }));
+        return;
+    }
+    const refs = Array.isArray(value) ? value : value === undefined || value === null ? [] : [value];
+    if (field.cardinality === 'one' && Array.isArray(value) && value.length > 1) {
+        issues.push(cmsIssue({
+            code: 'cardinality-violation',
+            message: `Relation field "${field.name}" is single-valued but has ${value.length} targets.`,
+            path,
+            collectionId: collection.id,
+            documentId,
+            meta: { field: field.name, cardinality: 'one' },
+        }));
+    }
+    refs.forEach((raw, i) => {
+        const ref = coerceRef(raw);
+        if (!ref) {
+            issues.push(cmsIssue({
+                code: 'invalid-field-value',
+                message: `Relation field "${field.name}" holds a value that is not a document reference.`,
+                path: [...path, i],
+                collectionId: collection.id,
+                documentId,
+                meta: { field: field.name },
+            }));
+            return;
+        }
+        if (ref.collection !== field.target) {
+            issues.push(cmsIssue({
+                code: 'unknown-relation-target',
+                message: `Relation field "${field.name}" points at collection "${ref.collection}" but targets "${field.target}".`,
+                path: [...path, i],
+                collectionId: collection.id,
+                documentId,
+                meta: { field: field.name, target: field.target, got: ref.collection },
+            }));
+            return;
+        }
+        if (store) {
+            const target = store.get(ref);
+            if (!target) {
+                issues.push(cmsIssue({
+                    code: 'unknown-relation-target',
+                    message: `Relation field "${field.name}" references missing document "${ref.id}" in "${ref.collection}".`,
+                    path: [...path, i],
+                    collectionId: collection.id,
+                    documentId,
+                    meta: { field: field.name, target: ref.collection, id: ref.id },
+                }));
+            }
+            else if (ctx.isSourcePublished && !ctx.isPublished(ref)) {
+                // EC-173 weak-reference aftermath: the source is published but the
+                // target is not, so published delivery serves the declared fallback
+                // for this reference. Explicit and visible — but a warning, never an
+                // error: weak references must not block saving or re-publishing the
+                // source. Re-publishing the target clears it.
+                issues.push(cmsIssue({
+                    code: 'unpublished-relation-target',
+                    severity: 'warning',
+                    message: `Relation field "${field.name}" references unpublished document "${ref.id}" in "${ref.collection}" — the published site shows a fallback there.`,
+                    path: [...path, i],
+                    collectionId: collection.id,
+                    documentId,
+                    meta: { field: field.name, target: ref.collection, id: ref.id },
+                }));
+            }
+        }
+    });
+}
+function validateAsset(ctx, issues) {
+    const { field, value, path, collection, registry, store, documentId } = ctx;
+    if (field.type !== 'asset')
+        return;
+    const assetCollections = registry.assetCollections();
+    if (assetCollections.length === 0) {
+        issues.push(cmsIssue({
+            code: 'invalid-field-config',
+            message: `Asset field "${field.name}" requires an asset collection, but none is registered.`,
+            path,
+            collectionId: collection.id,
+            documentId,
+            meta: { field: field.name },
+        }));
+        return;
+    }
+    const ids = Array.isArray(value) ? value : value === undefined || value === null ? [] : [value];
+    if (field.cardinality === 'one' && Array.isArray(value) && value.length > 1) {
+        issues.push(cmsIssue({
+            code: 'cardinality-violation',
+            message: `Asset field "${field.name}" is single-valued but has ${value.length} targets.`,
+            path,
+            collectionId: collection.id,
+            documentId,
+            meta: { field: field.name, cardinality: 'one' },
+        }));
+    }
+    ids.forEach((rawValue, i) => {
+        // An asset value is the id of a document in some asset collection — self-typed
+        // (`{ type:'asset', id }`) or legacy bare id (EC-277 lazy-on-read).
+        const raw = readAssetId(rawValue);
+        if (raw === undefined) {
+            issues.push(cmsIssue({
+                code: 'invalid-field-value',
+                message: `Asset field "${field.name}" expects an asset id.`,
+                path: [...path, i],
+                collectionId: collection.id,
+                documentId,
+                meta: { field: field.name },
+            }));
+            return;
+        }
+        // Asset existence is checked against the asset library when the caller
+        // supplies an oracle (assets live in their own repository, not as CMS
+        // documents — EC-212 follow-up); otherwise it falls back to the document
+        // store (fixtures that model assets as documents). With neither, existence
+        // is simply not checked (`undefined` → skip), never wrongly flagged.
+        const exists = ctx.assetExists
+            ? ctx.assetExists(raw)
+            : store
+                ? assetCollections.some((c) => store.has({ collection: c.id, id: raw }))
+                : undefined;
+        if (exists === false) {
+            issues.push(cmsIssue({
+                code: 'unknown-asset',
+                message: `Asset field "${field.name}" references unknown asset "${raw}".`,
+                path: [...path, i],
+                collectionId: collection.id,
+                documentId,
+                meta: { field: field.name, asset: raw },
+            }));
+        }
+    });
+}
+/**
+ * Validate an `object` / repeater field value (EC-253) by recursing into each
+ * item's subfields. `cardinality: 'many'` is an array of objects (each item keyed
+ * by index in the path); `'one'` is a single object. Malformed items (already
+ * reported by {@link validateScalarType}) are skipped. The same {@link FieldCtx}
+ * (registry/store/asset oracle) is threaded so nested relation/asset subfields get
+ * the same target-existence checks they would at the top level.
+ */
+function validateObject(ctx, issues, v) {
+    const { field } = ctx;
+    if (field.type !== 'object')
+        return;
+    const items = field.cardinality === 'many' ? (Array.isArray(ctx.value) ? ctx.value : []) : [ctx.value];
+    items.forEach((item, index) => {
+        if (!isPlainObject(item))
+            return;
+        const itemPath = field.cardinality === 'many' ? [...ctx.path, index] : ctx.path;
+        for (const sub of field.fields) {
+            const subValue = item[sub.name];
+            const subPath = [...itemPath, sub.name];
+            if (isEmpty(subValue)) {
+                if (sub.validation?.required) {
+                    issues.push(cmsIssue({
+                        code: 'missing-required-field',
+                        message: `Required field "${sub.name}" is missing.`,
+                        path: subPath,
+                        collectionId: ctx.collection.id,
+                        documentId: ctx.documentId,
+                        meta: { field: sub.name },
+                    }));
+                    continue;
+                }
+                // EC-253 (C1): an optional but PRESENT nested object still recurses so its
+                // own required subfields surface; any other empty/absent value is skipped.
+                if (!isPresentObjectValue(sub, subValue))
+                    continue;
+            }
+            validateFieldValue({ ...ctx, field: sub, value: subValue, path: subPath }, issues, v);
+        }
+    });
+}
+/**
+ * Run every per-field validator for one field/value/path. The single dispatch
+ * point shared by the document loop and the {@link validateObject} recursion, so
+ * a subfield is validated exactly as a top-level field would be (EC-253).
+ */
+function validateFieldValue(ctx, issues, v) {
+    validateScalarType(ctx, issues);
+    validateConstraints(ctx, issues);
+    validateRelation(ctx, issues);
+    validateAsset(ctx, issues);
+    validateBlocks(ctx, issues, v.validateComposition);
+    validateRichTextEmbeds(ctx, issues, v.validateRichText);
+    validateObject(ctx, issues, v);
+}
+/**
+ * Validate a document against its collection (EC-016/017/018). Returns structured
+ * issues; never throws. Checks unknown collection, missing required fields,
+ * scalar type correctness, declared constraints, relation targets, asset
+ * references, and required localized values across configured locales.
+ */
+export function validateDocument(registry, doc, options = {}) {
+    const issues = [];
+    const collection = registry.get(doc.collection);
+    const basePath = ['documents', documentKey(doc)];
+    if (!collection) {
+        issues.push(cmsIssue({
+            code: 'unknown-collection',
+            message: `Document "${doc.id}" references unknown collection "${doc.collection}".`,
+            path: basePath,
+            documentId: doc.id,
+            meta: { collection: doc.collection },
+        }));
+        return issues;
+    }
+    const { store, localeConfig, validateComposition } = options;
+    const validateRichText = options.validateRichTextEmbeds;
+    // EC-224: published-ness is the version pointer, supplied by the caller. With
+    // no predicate, nothing is treated as published (the EC-173 warning is inert).
+    const isPublished = options.isPublished ?? (() => false);
+    const isSourcePublished = isPublished({ collection: doc.collection, id: doc.id });
+    for (const field of collection.fields) {
+        const fieldPath = [...basePath, 'values', field.name];
+        const localized = isFieldLocalized(collection, field.name);
+        // Determine the locales over which we validate this field's value.
+        const locales = localized && localeConfig ? localeConfig.locales : [localeConfig?.default ?? '*'];
+        const defaultLocale = localeConfig
+            ? doc.defaultLocale ?? localeConfig.default
+            : undefined;
+        for (const locale of locales) {
+            // The fallback-resolved value (what would render) is used for type/constraint
+            // checks; the *raw* per-locale value drives the localized-required check so we
+            // can distinguish "genuinely missing" from "satisfied via default-locale fallback".
+            const resolved = localized
+                ? localeConfig
+                    ? resolveField(collection, doc, field.name, locale, localeConfig).value
+                    : doc.localized?.[locale]?.[field.name]
+                : doc.values[field.name];
+            const rawLocaleValue = localized ? doc.localized?.[locale]?.[field.name] : resolved;
+            const path = localized ? [...basePath, 'localized', locale, field.name] : fieldPath;
+            // Required check.
+            if (field.validation?.required) {
+                if (!localized) {
+                    if (isEmpty(resolved)) {
+                        issues.push(cmsIssue({
+                            code: 'missing-required-field',
+                            message: `Required field "${field.name}" is missing.`,
+                            path,
+                            collectionId: collection.id,
+                            documentId: doc.id,
+                            meta: { field: field.name },
+                        }));
+                        continue;
+                    }
+                }
+                else {
+                    const isDefault = locale === defaultLocale;
+                    if (isDefault && isEmpty(rawLocaleValue)) {
+                        // A required localized field MUST have a value in the default locale —
+                        // it is the fallback source for every other locale. Missing here is an
+                        // error (no fallback can rescue it).
+                        issues.push(cmsIssue({
+                            code: 'missing-localized-value',
+                            message: `Required localized field "${field.name}" is missing for the default locale "${locale}".`,
+                            path,
+                            collectionId: collection.id,
+                            documentId: doc.id,
+                            meta: { field: field.name, locale },
+                        }));
+                    }
+                    else if (!isDefault && isEmpty(rawLocaleValue) && isEmpty(resolved)) {
+                        // Non-default locale missing AND no fallback value available.
+                        issues.push(cmsIssue({
+                            code: 'missing-localized-value',
+                            severity: 'warning',
+                            message: `Localized field "${field.name}" has no value for locale "${locale}" and no fallback.`,
+                            path,
+                            collectionId: collection.id,
+                            documentId: doc.id,
+                            meta: { field: field.name, locale },
+                        }));
+                    }
+                    if (isEmpty(resolved))
+                        continue;
+                }
+            }
+            if (isEmpty(resolved) && !isPresentObjectValue(field, resolved))
+                continue;
+            const value = resolved;
+            const ctx = {
+                collection,
+                field,
+                value,
+                path,
+                registry,
+                store,
+                documentId: doc.id,
+                isSourcePublished,
+                isPublished,
+                assetExists: options.assetExists,
+            };
+            validateFieldValue(ctx, issues, { validateComposition, validateRichText });
+        }
+    }
+    // EC-218: a `parent` self-relation must not form a cycle. Needs the store to
+    // walk the chain (other documents); the walk is cycle-safe, so this only
+    // reports — it never loops. Only checked when the collection declares a parent
+    // self-relation and a store is supplied.
+    if (store && parentRelationField(collection)) {
+        if (hasParentCycle(doc, (id) => store.get({ collection: collection.id, id }))) {
+            issues.push(cmsIssue({
+                code: 'hierarchy-cycle',
+                message: `Document "${doc.id}" is its own ancestor — the parent chain forms a cycle.`,
+                path: [...basePath, 'values', 'parent'],
+                collectionId: collection.id,
+                documentId: doc.id,
+                meta: { field: 'parent' },
+            }));
+        }
+    }
+    return issues;
+}
+/** Validate every document in a list against the registry. */
+export function validateDocuments(registry, docs, options = {}) {
+    return docs.flatMap((d) => validateDocument(registry, d, options));
+}
+// --- EC-190: props as fields -------------------------------------------------
+// Component props are field-defs (the same vocabulary as document fields). The
+// helpers below are the prop-side mirror of the document validators: pure,
+// store-free type/constraint checks plus a prop-keyed `validateComponentProps`.
+// They share field-type semantics with the document path; `fields.test.ts`
+// guards against drift between the two.
+/**
+ * Pure scalar/structural type check for a field value (EC-190). Returns a human
+ * detail string when the value is the wrong shape for the field type, or null
+ * when it is acceptable. Existence checks (relation/asset targets) are NOT done
+ * here — they need a document store. Assumes a present value (the `required`
+ * check owns presence).
+ */
+export function checkScalarType(field, value) {
+    switch (field.type) {
+        case 'text':
+            return typeof value === 'string' ? null : 'expects a string';
+        case 'richText':
+            // A rich-text value is either a plain string (CMS markdown/HTML) or the
+            // structured @elytracms/rich-text storage envelope (an object) used by the
+            // canvas RichText component. Deep validation is delegated (the renderer's
+            // parse guard / a future injected rich-text validator, mirroring blocks).
+            return typeof value === 'string' || (typeof value === 'object' && value !== null)
+                ? null
+                : 'expects rich-text content (a string or a rich-text value)';
+        case 'number':
+            return typeof value === 'number' && !Number.isNaN(value) ? null : 'expects a number';
+        case 'boolean':
+            return typeof value === 'boolean' ? null : 'expects a boolean';
+        case 'date':
+            if (typeof value === 'string') {
+                return Number.isNaN(Date.parse(value)) ? 'expects a valid date string' : null;
+            }
+            return typeof value === 'number' ? null : 'expects a date (ISO string or epoch number)';
+        case 'select': {
+            const allowed = new Set(field.options.map((o) => o.value));
+            const values = field.multiple ? (Array.isArray(value) ? value : [value]) : [value];
+            for (const v of values) {
+                if (typeof v !== 'string' || !allowed.has(v)) {
+                    return `has value "${String(v)}" not among its options`;
+                }
+            }
+            return null;
+        }
+        case 'object':
+            // EC-253: top-level shape only (deep subfield validation lives in
+            // `validateComponentProps`, which needs the same per-field machinery).
+            if (field.cardinality === 'many') {
+                return Array.isArray(value) && value.every((item) => isPlainObject(item))
+                    ? null
+                    : 'expects a list of objects';
+            }
+            return isPlainObject(value) ? null : 'expects an object';
+        case 'relation':
+        case 'asset':
+        case 'blocks':
+            // relation / asset / blocks are validated structurally, not as scalars.
+            return null;
+        default: {
+            // Exhaustiveness: a new field type must add a case above (EC-253).
+            const _exhaustive = field;
+            void _exhaustive;
+            return null;
+        }
+    }
+}
+/**
+ * Pure declarative-constraint check (min/max/pattern) for a field value (EC-190).
+ * Returns the list of human detail strings for each violation (empty = valid).
+ * Mirrors `validateConstraints` without the issue-construction coupling.
+ */
+export function checkConstraints(field, value) {
+    const out = [];
+    const rules = field.validation;
+    if (!rules)
+        return out;
+    if (typeof value === 'string') {
+        if (rules.min !== undefined && value.length < rules.min)
+            out.push(`is shorter than min length ${rules.min}`);
+        if (rules.max !== undefined && value.length > rules.max)
+            out.push(`is longer than max length ${rules.max}`);
+        if (rules.pattern !== undefined) {
+            let re;
+            try {
+                re = new RegExp(rules.pattern);
+            }
+            catch {
+                re = undefined;
+            }
+            if (re && !re.test(value))
+                out.push(`does not match pattern ${rules.pattern}`);
+        }
+    }
+    else if (typeof value === 'number') {
+        if (rules.min !== undefined && value < rules.min)
+            out.push(`is less than min ${rules.min}`);
+        if (rules.max !== undefined && value > rules.max)
+            out.push(`is greater than max ${rules.max}`);
+    }
+    else if (Array.isArray(value)) {
+        if (rules.min !== undefined && value.length < rules.min)
+            out.push(`has fewer than ${rules.min} items`);
+        if (rules.max !== undefined && value.length > rules.max)
+            out.push(`has more than ${rules.max} items`);
+    }
+    return out;
+}
+function checkRelationStructure(field, value) {
+    const out = [];
+    if (field.cardinality === 'one' && Array.isArray(value) && value.length > 1) {
+        out.push(`is single-valued but has ${value.length} targets`);
+    }
+    const refs = Array.isArray(value) ? value : [value];
+    for (const raw of refs) {
+        const ref = coerceRef(raw);
+        if (!ref)
+            out.push('holds a value that is not a document reference');
+        else if (ref.collection !== field.target) {
+            out.push(`points at collection "${ref.collection}" but targets "${field.target}"`);
+        }
+    }
+    return out;
+}
+function checkAssetStructure(field, value) {
+    const out = [];
+    if (field.cardinality === 'one' && Array.isArray(value) && value.length > 1) {
+        out.push(`is single-valued but has ${value.length} targets`);
+    }
+    const ids = Array.isArray(value) ? value : [value];
+    for (const raw of ids) {
+        if (typeof raw !== 'string')
+            out.push('expects an asset id string');
+    }
+    return out;
+}
+/**
+ * Build a pure, store-free validator for a single field-def's value (EC-190).
+ * Used by the renderer (invalid static prop → EC-015 visible fallback) and the
+ * inspector. Returns true when the value is structurally acceptable for the field
+ * type; absent values (undefined/null/'') are acceptable — the `required` check
+ * owns presence. Relation/asset existence and composition depth are validated
+ * elsewhere (they need a store / registry).
+ */
+export function fieldValueValidator(field) {
+    return (value) => {
+        if (isEmpty(value))
+            return true;
+        return checkScalarType(field, value) === null && checkConstraints(field, value).length === 0;
+    };
+}
+/**
+ * Lint a field-def used as a component prop (EC-190): document-only attributes
+ * (`filterable`, `validation.unique`) make no sense on a prop and surface as
+ * structured issues, never silently ignored. Returns [] for a valid prop
+ * field-def.
+ */
+export function assertPropFieldDef(field) {
+    const issues = [];
+    if (field.filterable) {
+        issues.push(cmsIssue({
+            code: 'invalid-field-config',
+            message: `Component prop "${field.name}" declares "filterable", which only applies to document fields.`,
+            path: ['props', field.name],
+            meta: { field: field.name },
+        }));
+    }
+    if (field.validation?.unique) {
+        issues.push(cmsIssue({
+            code: 'invalid-field-config',
+            message: `Component prop "${field.name}" declares "unique", which only applies across a collection's documents.`,
+            path: ['props', field.name],
+            meta: { field: field.name },
+        }));
+    }
+    // EC-253: a nested object prop's subfields are props too — lint them as well, so
+    // a `filterable`/`unique` buried inside a repeater is surfaced, not silently kept.
+    if (field.type === 'object') {
+        for (const sub of field.fields)
+            issues.push(...assertPropFieldDef(sub));
+    }
+    return issues;
+}
+/**
+ * Validate a component's static prop values against its prop field-defs (EC-190).
+ * The prop-side mirror of `validateDocument`: the same per-field type / constraint
+ * / relation-structure / asset-structure / blocks checks, keyed by prop name,
+ * MINUS collection-scoped concerns (uniqueness, filterability, localization) and
+ * store-backed existence (relation/asset target *existence* is a where-used /
+ * reference-integrity concern handled in EC-190 slice 6). Returns structured
+ * issues; never throws. The inspector surfaces these inline exactly like document
+ * field issues.
+ */
+/**
+ * Validate one prop value against its field-def, recursing into `object` subfields
+ * (EC-253). The prop-side mirror of {@link validateFieldValue}: pure type +
+ * constraint + relation/asset-structure + composition checks, keyed by `path`.
+ * Shared by the top-level loop and the object recursion so a repeater item's
+ * subfields are validated exactly as a top-level prop would be.
+ */
+function validatePropFieldValue(field, value, path, options, issues) {
+    const push = (detail, code = 'invalid-field-value') => issues.push(cmsIssue({ code, message: `Prop "${field.name}" ${detail}.`, path, meta: { field: field.name } }));
+    if (isEmpty(value)) {
+        if (field.validation?.required) {
+            issues.push(cmsIssue({
+                code: 'missing-required-field',
+                message: `Required prop "${field.name}" is missing.`,
+                path,
+                meta: { field: field.name },
+            }));
+            return;
+        }
+        // EC-253 (C1): an optional but PRESENT object prop still recurses so its own
+        // required subfields surface; any other empty/absent value has nothing to check.
+        if (!isPresentObjectValue(field, value))
+            return;
+    }
+    const typeErr = checkScalarType(field, value);
+    if (typeErr)
+        push(typeErr);
+    for (const detail of checkConstraints(field, value))
+        push(detail);
+    if (field.type === 'relation') {
+        for (const detail of checkRelationStructure(field, value))
+            push(detail);
+    }
+    else if (field.type === 'asset') {
+        for (const detail of checkAssetStructure(field, value))
+            push(detail);
+    }
+    else if (field.type === 'blocks' && options.validateComposition) {
+        for (const finding of options.validateComposition(value, field)) {
+            issues.push(cmsIssue({
+                code: 'invalid-field-value',
+                severity: finding.severity ?? 'error',
+                message: `Prop "${field.name}": ${finding.message}`,
+                path,
+                meta: {
+                    field: field.name,
+                    type: 'blocks',
+                    ...(finding.nodePath ? { nodePath: finding.nodePath } : {}),
+                },
+            }));
+        }
+    }
+    else if (field.type === 'richText' && options.validateRichTextEmbeds) {
+        // EC-189: validate the composition embeds carried by a richText prop value
+        // (e.g. the RichText primitive's `content`) against the prop's `allow`.
+        for (const finding of options.validateRichTextEmbeds(value, field)) {
+            issues.push(cmsIssue({
+                code: 'invalid-field-value',
+                severity: finding.severity ?? 'error',
+                message: `Prop "${field.name}": ${finding.message}`,
+                path,
+                meta: {
+                    field: field.name,
+                    type: 'richText',
+                    ...(finding.nodePath ? { nodePath: finding.nodePath } : {}),
+                },
+            }));
+        }
+    }
+    else if (field.type === 'object') {
+        // EC-253: recurse into each item's subfields, mirroring the document path.
+        const items = field.cardinality === 'many' ? (Array.isArray(value) ? value : []) : [value];
+        items.forEach((item, index) => {
+            if (!isPlainObject(item))
+                return;
+            const itemPath = field.cardinality === 'many' ? [...path, index] : path;
+            for (const sub of field.fields) {
+                validatePropFieldValue(sub, item[sub.name], [...itemPath, sub.name], options, issues);
+            }
+        });
+    }
+}
+export function validateComponentProps(fieldDefs, props, options = {}) {
+    const issues = [];
+    for (const field of fieldDefs) {
+        issues.push(...assertPropFieldDef(field));
+        validatePropFieldValue(field, props[field.name], ['props', field.name], options, issues);
+    }
+    return issues;
+}
+/** Resolve a relation value into the referenced documents (EC-017). */
+export function resolveRelation(store, value) {
+    const raws = Array.isArray(value) ? value : value === undefined || value === null ? [] : [value];
+    const out = [];
+    for (const raw of raws) {
+        const ref = coerceRef(raw);
+        if (!ref)
+            continue;
+        const doc = store.get(ref);
+        if (doc)
+            out.push(doc);
+    }
+    return out;
+}
+/** Build a flat values bag (non-localized only) — convenience for tests/consumers. */
+export function plainValues(doc) {
+    return { ...doc.values };
+}
+//# sourceMappingURL=validate-document.js.map