canopycms 0.0.67-int.90 → 0.0.67

package/dist/validation/entry-validator.d.ts

@@ -7,16 +7,6 @@
  * of server-only imports (node:fs, ContentStore, ContentIdIndex, ...) — it may
  * only depend on config types and other pure modules.
  *
- * What it checks (pure rules — no filesystem access):
- * - required fields are present and non-empty
- * - values match their field type (string/number/boolean/datetime/select/...)
- * - `list` fields hold arrays; non-list fields hold single values
- * - select values are one of the configured options
- * - reference values are well-formed (id string or resolved `{ id }` object)
- *   and non-empty when required
- * - block items resolve to a known template (via the shared `resolveBlockItem`
- *   from field-traversal, so `{ template, value }`-nested fields are validated)
- *
  * Reference EXISTENCE is intentionally NOT checked here: it requires the
  * content ID index (filesystem) and is enforced server-side only, by running
  * `ReferenceValidator` at the write boundary.
@@ -36,6 +26,7 @@ export interface EntryFieldError {
  * as an id string or as a resolved object `{ id, slug, collection, ... }`
  * (content reads resolve references by default). Returns undefined for any
  * other shape.
+ * @internal Exported for tests.
  */
 export declare function referenceValueId(value: unknown): string | undefined;
 /**
@@ -58,24 +49,21 @@ export declare function validateEntryData(fields: EntrySchema, data: Record<stri
 export declare function validateEntryFormValue(fields: EntrySchema, format: ContentFormat | undefined, value: Record<string, unknown>): EntryFieldError[];
 /**
  * Find data keys that have no counterpart in the schema, as canonical field paths
- * (`author.nickname`, `blocks[2].headline`).
- *
- * `validateEntryData` iterates the SCHEMA, so it can only ever report fields the schema knows
- * about. Nothing reported the inverse: rename or reshape a field and the old key persists on
- * disk forever, because the editor's form state is the whole record verbatim and every save
- * posts it back. The only symptom is a component quietly receiving `undefined`.
+ * (`author.nickname`, `blocks[2].headline`). `validateEntryData` iterates the SCHEMA
+ * so it can't report the inverse: rename or reshape a field and the old key persists
+ * on disk forever, since the editor's form state is the whole record verbatim and
+ * every save posts it back — the only symptom is a component quietly receiving
+ * `undefined`.
  *
- * Pure — safe in the browser. Reports rather than rejects: a save carrying a stale key still
- * succeeds (and now the write path even preserves the key and its comments), so this feeds the
+ * Pure — safe in the browser. Reports rather than rejects (a stale key doesn't fail
+ * a save, and the write path now preserves it and its comments), so this feeds the
  * non-blocking `validationWarnings` channel, not the 422 path.
  *
- * Two things it deliberately does not report:
- *
- * - **A container with no fields at all.** `api/content.ts` falls back to `[]` for a collection
- *   with no configured entry type; "no schema" is not "every key is unknown".
- * - **Anything inside a `reference` value.** Reads resolve references by default, so a reference
- *   field's value is `{ ...target data, id, slug, collection, urlPath }`. The traversal only
- *   descends into `object` and `block`, so it never looks inside one.
+ * Deliberately not reported: a container with no fields at all (`api/content.ts`
+ * falls back to `[]` for a collection with no configured entry type — "no schema"
+ * isn't "every key is unknown"), and anything inside a `reference` value (a resolved
+ * reference's value is `{ ...target data, id, slug, collection, urlPath }`; the
+ * traversal only descends into `object` and `block`, so it never looks inside one).
  */
 export declare function findUnknownKeys(fields: EntrySchema, data: Record<string, unknown>): string[];
 /**

package/dist/validation/entry-validator.js

@@ -7,16 +7,6 @@
  * of server-only imports (node:fs, ContentStore, ContentIdIndex, ...) — it may
  * only depend on config types and other pure modules.
  *
- * What it checks (pure rules — no filesystem access):
- * - required fields are present and non-empty
- * - values match their field type (string/number/boolean/datetime/select/...)
- * - `list` fields hold arrays; non-list fields hold single values
- * - select values are one of the configured options
- * - reference values are well-formed (id string or resolved `{ id }` object)
- *   and non-empty when required
- * - block items resolve to a known template (via the shared `resolveBlockItem`
- *   from field-traversal, so `{ template, value }`-nested fields are validated)
- *
  * Reference EXISTENCE is intentionally NOT checked here: it requires the
  * content ID index (filesystem) and is enforced server-side only, by running
  * `ReferenceValidator` at the write boundary.
@@ -52,10 +42,7 @@ function isValidImageCropValue(value) {
 }
 /**
  * Validate a structured `image` field value: `{ src, alt, width?, height?, crop? }`
- * (see `ImageFieldValue` in config/types.ts). `src` and `alt` are required
- * whenever a value is present; `alt` may be an empty string only when the
- * field config sets `altOptional: true`. `width`/`height` must be positive
- * integers when present; `crop` must satisfy the same normalized-rect
+ * (see `ImageFieldValue` in config/types.ts). `crop` must satisfy the same normalized-rect
  * constraints as the transform directive parser (assets/transform-directives.ts).
  */
 function validateImageValue(field, value, path) {
@@ -91,6 +78,7 @@ function validateImageValue(field, value, path) {
  * as an id string or as a resolved object `{ id, slug, collection, ... }`
  * (content reads resolve references by default). Returns undefined for any
  * other shape.
+ * @internal Exported for tests.
  */
 export function referenceValueId(value) {
     if (typeof value === 'string')
@@ -175,7 +163,7 @@ function isEmptyForRequired(field, value) {
 export function validateEntryData(fields, data, pathPrefix = '') {
     const errors = [];
     for (const field of fields) {
-        // Inline groups are transparent to the data — children live at this level.
+        // Inline groups are transparent (walkFields, ./field-traversal) — children live at this level.
         if (field.type === 'group') {
             errors.push(...validateEntryData(field.fields, data, pathPrefix));
             continue;
@@ -190,7 +178,6 @@ export function validateEntryData(fields, data, pathPrefix = '') {
             errors.push({ fieldPath: path, message });
             continue;
         }
-        // Optional and absent: nothing further to check.
         if (value === undefined || value === null)
             continue;
         if (field.type === 'block') {
@@ -244,7 +231,6 @@ export function validateEntryData(fields, data, pathPrefix = '') {
             }
             continue;
         }
-        // Scalar (and list-of-scalar) fields.
         if ('list' in field && field.list) {
             if (!Array.isArray(value)) {
                 errors.push({ fieldPath: path, message: 'Expected a list of values' });
@@ -277,24 +263,21 @@ export function validateEntryFormValue(fields, format, value) {
 }
 /**
  * Find data keys that have no counterpart in the schema, as canonical field paths
- * (`author.nickname`, `blocks[2].headline`).
- *
- * `validateEntryData` iterates the SCHEMA, so it can only ever report fields the schema knows
- * about. Nothing reported the inverse: rename or reshape a field and the old key persists on
- * disk forever, because the editor's form state is the whole record verbatim and every save
- * posts it back. The only symptom is a component quietly receiving `undefined`.
+ * (`author.nickname`, `blocks[2].headline`). `validateEntryData` iterates the SCHEMA
+ * so it can't report the inverse: rename or reshape a field and the old key persists
+ * on disk forever, since the editor's form state is the whole record verbatim and
+ * every save posts it back — the only symptom is a component quietly receiving
+ * `undefined`.
  *
- * Pure — safe in the browser. Reports rather than rejects: a save carrying a stale key still
- * succeeds (and now the write path even preserves the key and its comments), so this feeds the
+ * Pure — safe in the browser. Reports rather than rejects (a stale key doesn't fail
+ * a save, and the write path now preserves it and its comments), so this feeds the
  * non-blocking `validationWarnings` channel, not the 422 path.
  *
- * Two things it deliberately does not report:
- *
- * - **A container with no fields at all.** `api/content.ts` falls back to `[]` for a collection
- *   with no configured entry type; "no schema" is not "every key is unknown".
- * - **Anything inside a `reference` value.** Reads resolve references by default, so a reference
- *   field's value is `{ ...target data, id, slug, collection, urlPath }`. The traversal only
- *   descends into `object` and `block`, so it never looks inside one.
+ * Deliberately not reported: a container with no fields at all (`api/content.ts`
+ * falls back to `[]` for a collection with no configured entry type — "no schema"
+ * isn't "every key is unknown"), and anything inside a `reference` value (a resolved
+ * reference's value is `{ ...target data, id, slug, collection, urlPath }`; the
+ * traversal only descends into `object` and `block`, so it never looks inside one).
  */
 export function findUnknownKeys(fields, data) {
     return traverseFields(fields, data, () => [], '', ({ fields: containerFields, data: record, path }) => {

package/dist/validation/field-traversal.d.ts

@@ -29,7 +29,7 @@ export type FieldVisitor<T> = (context: TraversalContext) => T[];
  * knows about. A container visitor sees the record itself, which is what a check on the data's
  * OWN keys needs (`findUnknownKeys` in entry-validator.ts).
  */
-export interface ContainerContext {
+interface ContainerContext {
     /** The schema fields governing this record. Inline groups are NOT flattened. */
     fields: readonly FieldConfig[];
     /** The data record those fields govern. */
@@ -67,42 +67,15 @@ export declare function resolveBlockItem(blockField: BlockFieldConfig, item: Rec
 /**
  * Recursively traverse fields in data according to schema.
  *
- * This function walks through data following the schema structure, calling
- * the visitor function for each field. It handles:
- * - Simple fields (string, number, boolean, reference, etc.)
- * - Object fields with nested schemas
- * - Block fields (arrays of typed objects with different schemas)
- * - Array fields containing objects with schemas
- *
  * @param fields - The schema fields to traverse
  * @param data - The data object to traverse
  * @param visitor - Function called for each field, returns items to collect
  * @param pathPrefix - Current path prefix for nested fields
  * @param onContainer - Optional, called once per container (this record plus the fields
  *   governing it) before its fields are walked: the top level, each object value, each
- *   object-list item, and each block item's resolved data. Inline groups do NOT fire it — a
- *   group is transparent to the data and shares its parent's record, so its children are already
- *   covered by the parent's container call.
+ *   object-list item, and each block item's resolved data.
  * @returns Array of all items returned by the visitors
- *
- * @example
- * ```ts
- * // Find all reference field values
- * const refs = traverseFields(schema, data, ({ field, value, path }) => {
- *   if (field.type === 'reference') {
- *     return [{ path, ids: Array.isArray(value) ? value : [value] }]
- *   }
- *   return []
- * })
- * ```
  */
 export declare function traverseFields<T>(fields: readonly FieldConfig[], data: Record<string, unknown>, visitor: FieldVisitor<T>, pathPrefix?: string, onContainer?: ContainerVisitor<T>): T[];
-/**
- * Find all fields of a specific type in the data.
- *
- * @param fields - The schema fields
- * @param data - The data to search
- * @param fieldType - The field type to find (e.g., 'reference', 'string')
- * @returns Array of { field, value, path } for matching fields
- */
 export declare function findFieldsByType(fields: readonly FieldConfig[], data: Record<string, unknown>, fieldType: string): TraversalContext[];
+export {};

package/dist/validation/field-traversal.js

@@ -39,34 +39,14 @@ export function resolveBlockItem(blockField, item) {
 /**
  * Recursively traverse fields in data according to schema.
  *
- * This function walks through data following the schema structure, calling
- * the visitor function for each field. It handles:
- * - Simple fields (string, number, boolean, reference, etc.)
- * - Object fields with nested schemas
- * - Block fields (arrays of typed objects with different schemas)
- * - Array fields containing objects with schemas
- *
  * @param fields - The schema fields to traverse
  * @param data - The data object to traverse
  * @param visitor - Function called for each field, returns items to collect
  * @param pathPrefix - Current path prefix for nested fields
  * @param onContainer - Optional, called once per container (this record plus the fields
  *   governing it) before its fields are walked: the top level, each object value, each
- *   object-list item, and each block item's resolved data. Inline groups do NOT fire it — a
- *   group is transparent to the data and shares its parent's record, so its children are already
- *   covered by the parent's container call.
+ *   object-list item, and each block item's resolved data.
  * @returns Array of all items returned by the visitors
- *
- * @example
- * ```ts
- * // Find all reference field values
- * const refs = traverseFields(schema, data, ({ field, value, path }) => {
- *   if (field.type === 'reference') {
- *     return [{ path, ids: Array.isArray(value) ? value : [value] }]
- *   }
- *   return []
- * })
- * ```
  */
 export function traverseFields(fields, data, visitor, pathPrefix = '', onContainer) {
     return walkFields(fields, data, visitor, pathPrefix, onContainer, true);
@@ -92,12 +72,9 @@ function walkFields(fields, data, visitor, pathPrefix, onContainer, fireContaine
             results.push(...walkFields(field.fields, data, visitor, pathPrefix, onContainer, false));
             continue;
         }
-        // Skip undefined/null values for all other field types
         if (value === undefined || value === null)
             continue;
-        // Let visitor handle this field first
         results.push(...visitor({ field, value, path: fieldPath }));
-        // Then recurse into nested structures
         if (field.type === 'object') {
             const objectField = field;
             if (objectField.fields) {
@@ -130,14 +107,6 @@ function walkFields(fields, data, visitor, pathPrefix, onContainer, fireContaine
     }
     return results;
 }
-/**
- * Find all fields of a specific type in the data.
- *
- * @param fields - The schema fields
- * @param data - The data to search
- * @param fieldType - The field type to find (e.g., 'reference', 'string')
- * @returns Array of { field, value, path } for matching fields
- */
 export function findFieldsByType(fields, data, fieldType) {
     return traverseFields(fields, data, (ctx) => {
         if (ctx.field.type === fieldType) {

package/dist/validation/reference-validator.d.ts

@@ -12,30 +12,17 @@ export interface ValidationResult {
 }
 /**
  * ReferenceValidator validates that referenced content IDs exist and match collection constraints.
- *
- * This class provides validation for:
- * - ID format validation (valid short UUID)
- * - ID existence validation (entry actually exists)
- * - Collection constraint validation (entry is in allowed collections)
- *
- * Usage:
- *   const validator = new ReferenceValidator(idIndex, schema)
- *   const result = await validator.validate(entryData)
- *   if (!result.valid) {
- *     console.error('Validation errors:', result.errors)
- *   }
  */
 export declare class ReferenceValidator {
     private idIndex;
     private schema;
     private resolveCollection?;
     /**
-     * @param resolveCollection - Resolves a schema-declared collection name
-     *   (the documented unprefixed form, e.g. 'posts') to its canonical logical
-     *   path (e.g. 'content/posts'), typically `ContentStore.resolveCollectionItem`.
-     *   Keeps the write boundary consistent with reference-option loading: any
-     *   entry the dropdown offers must also pass validation. Without a resolver,
-     *   names are compared as-is against the index's logical collection paths.
+     * @param resolveCollection - Resolves a schema-declared collection name (e.g.
+     *   'posts') to its canonical logical path (e.g. 'content/posts'), typically
+     *   `ContentStore.resolveCollectionItem` — keeps validation consistent with
+     *   reference-option loading, so any entry the dropdown offers also passes.
+     *   Without it, names are compared as-is against the index's logical paths.
      */
     constructor(idIndex: ContentIdIndex, schema: readonly FieldConfig[], resolveCollection?: ((name: string) => string | undefined) | undefined);
     /**
@@ -45,12 +32,6 @@ export declare class ReferenceValidator {
      * allowed collection are allowed.
      */
     private collectionAllowed;
-    /**
-     * Validate all reference fields in the provided data.
-     *
-     * @param data - The entry data to validate
-     * @returns Validation result with any errors found
-     */
     validate(data: Record<string, unknown>): Promise<ValidationResult>;
     /**
      * Validate a single reference ID.

package/dist/validation/reference-validator.js

@@ -4,27 +4,14 @@ import { isValidId } from '../id.js';
 import { findFieldsByType } from './field-traversal.js';
 /**
  * ReferenceValidator validates that referenced content IDs exist and match collection constraints.
- *
- * This class provides validation for:
- * - ID format validation (valid short UUID)
- * - ID existence validation (entry actually exists)
- * - Collection constraint validation (entry is in allowed collections)
- *
- * Usage:
- *   const validator = new ReferenceValidator(idIndex, schema)
- *   const result = await validator.validate(entryData)
- *   if (!result.valid) {
- *     console.error('Validation errors:', result.errors)
- *   }
  */
 export class ReferenceValidator {
     /**
-     * @param resolveCollection - Resolves a schema-declared collection name
-     *   (the documented unprefixed form, e.g. 'posts') to its canonical logical
-     *   path (e.g. 'content/posts'), typically `ContentStore.resolveCollectionItem`.
-     *   Keeps the write boundary consistent with reference-option loading: any
-     *   entry the dropdown offers must also pass validation. Without a resolver,
-     *   names are compared as-is against the index's logical collection paths.
+     * @param resolveCollection - Resolves a schema-declared collection name (e.g.
+     *   'posts') to its canonical logical path (e.g. 'content/posts'), typically
+     *   `ContentStore.resolveCollectionItem` — keeps validation consistent with
+     *   reference-option loading, so any entry the dropdown offers also passes.
+     *   Without it, names are compared as-is against the index's logical paths.
      */
     constructor(idIndex, schema, resolveCollection) {
         this.idIndex = idIndex;
@@ -44,15 +31,8 @@ export class ReferenceValidator {
             return entryCollection === canonical || entryCollection?.startsWith(canonical + '/');
         });
     }
-    /**
-     * Validate all reference fields in the provided data.
-     *
-     * @param data - The entry data to validate
-     * @returns Validation result with any errors found
-     */
     async validate(data) {
         const errors = [];
-        // Use shared field traversal to find all reference fields
         const refContexts = findFieldsByType(this.schema, data, 'reference');
         const refs = refContexts.map((ctx) => ({
             field: ctx.field,
@@ -68,7 +48,6 @@ export class ReferenceValidator {
                 // means "no reference", not a malformed ID.
                 if (id == null || id === '')
                     continue;
-                // Validate ID format
                 if (typeof id !== 'string' || !isValidId(id)) {
                     errors.push({
                         field: field.name,
@@ -78,7 +57,6 @@ export class ReferenceValidator {
                     });
                     continue;
                 }
-                // Validate ID exists
                 const location = this.idIndex.findById(id);
                 if (!location) {
                     errors.push({
@@ -89,7 +67,6 @@ export class ReferenceValidator {
                     });
                     continue;
                 }
-                // Validate location is an entry (not a collection)
                 if (location.type !== 'entry') {
                     errors.push({
                         field: field.name,
@@ -99,7 +76,6 @@ export class ReferenceValidator {
                     });
                     continue;
                 }
-                // Validate collection constraint
                 if (field.collections && field.collections.length > 0) {
                     const allowed = this.collectionAllowed(location.collection, field.collections);
                     if (!allowed) {
@@ -112,7 +88,6 @@ export class ReferenceValidator {
                         continue;
                     }
                 }
-                // Validate entry type constraint
                 if (field.entryTypes && field.entryTypes.length > 0) {
                     const entryType = extractEntryTypeFromFilename(path.basename(location.relativePath));
                     if (!entryType || !field.entryTypes.includes(entryType)) {