@glw907/cairn-cms 0.68.0 → 0.76.0

package/src/lib/content/schema.ts

@@ -1,163 +0,0 @@
-// cairn-cms: the concept schema primitive (schema-source-of-truth design). One field
-// declaration yields a plain-data field projection for the editor form, a generated validator,
-// and an inferred frontmatter type. Plan 1 builds the additive primitive; the adapter-contract
-// cutover and the typed reads are Plan 2.
-import { compilePattern, dateBoundsError, patternError, stringLengthError } from './field-rules.js';
-import type { FrontmatterField, ImageValue, ValidationResult } from './types.js';
-import { validateFields } from './validate.js';
-
-/** The validate input the cairn adapter takes: the raw frontmatter and the body. */
-export interface StandardInput {
-  frontmatter: Record<string, unknown>;
-  body: string;
-}
-
-/**
- * A minimal local copy of the Standard Schema v1 interface (https://standardschema.dev), so the
- *  schema is a drop-in where the ecosystem accepts a validator, with no runtime dependency.
- */
-export interface StandardSchemaV1<Input = unknown, Output = Input> {
-  readonly '~standard': {
-    readonly version: 1;
-    readonly vendor: string;
-    readonly validate: (value: unknown) => StandardResult<Output>;
-    readonly types?: { readonly input: Input; readonly output: Output };
-  };
-}
-type StandardResult<Output> =
-  | { readonly value: Output; readonly issues?: undefined }
-  | { readonly issues: ReadonlyArray<{ readonly message: string; readonly path?: ReadonlyArray<PropertyKey> }> };
-
-/**
- * Map one field descriptor to the TS type of its normalized value. text, textarea, and date
- *  normalize to a string; a closed-vocabulary `tags` field to the option-union array; an `image`
- *  field to its nested object.
- */
-type FieldValue<K extends FrontmatterField> = K extends { type: 'boolean' }
-  ? boolean
-  : K extends { type: 'image' }
-    ? ImageValue
-    : K extends { type: 'tags'; options: readonly (infer O extends string)[] }
-      ? O[]
-      : K extends { type: 'tags' | 'freetags' }
-        ? string[]
-        : string;
-
-/** Flatten an intersection into a single readable object type. */
-type Prettify<T> = { [K in keyof T]: T[K] } & {};
-
-/**
- * The normalized frontmatter type inferred from a field tuple. A field declared
- *  `required: true` is a required key; every other field is optional.
- */
-export type InferFields<F extends readonly FrontmatterField[]> = Prettify<
-  { [K in F[number] as K extends { required: true } ? K['name'] : never]: FieldValue<K> } & {
-    [K in F[number] as K extends { required: true } ? never : K['name']]?: FieldValue<K>;
-  }
->;
-
-/**
- * A concept's schema: the plain-data field projection, the generated validator, and the
- *  Standard Schema conformance property.
- */
-export interface ConceptSchema<F extends readonly FrontmatterField[] = readonly FrontmatterField[]> {
-  /** The declared fields as plain serializable data, for the editor form. */
-  readonly fields: FrontmatterField[];
-  /** Validate raw frontmatter, returning field-keyed errors or the normalized data. */
-  validate(frontmatter: Record<string, unknown>, body: string): ValidationResult;
-  /** Standard Schema v1 conformance, for ecosystem interop. A thin adapter over `validate`. */
-  readonly '~standard': StandardSchemaV1<StandardInput, InferFields<F>>['~standard'];
-}
-
-/** Extract the inferred frontmatter type from a `ConceptSchema`. */
-export type Infer<S> = S extends ConceptSchema<infer F> ? InferFields<F> : never;
-
-// Enforce the declarative per-field rules on an already-coerced value. Rules run only on a
-// present, non-empty string value, so an absent optional field is never flagged. The first
-// failing rule per field wins, so the author sees one clear message at a time.
-function applyRules(field: FrontmatterField, value: unknown, errors: Record<string, string>, patterns: Map<string, RegExp>): void {
-  if (typeof value !== 'string' || value === '') return;
-  if (field.type === 'text' || field.type === 'textarea') {
-    const lengthError = stringLengthError(value, field, field.label);
-    if (lengthError != null) errors[field.name] = lengthError;
-    else {
-      const formatError = patternError(value, patterns.get(field.name), field.label);
-      if (formatError != null) errors[field.name] = formatError;
-    }
-  } else if (field.type === 'date') {
-    const boundsError = dateBoundsError(value, field, field.label);
-    if (boundsError != null) errors[field.name] = boundsError;
-  }
-}
-
-/**
- * Options for `defineFields`. `refine` runs after the per-field rules pass, for cross-field and
- *  body-dependent checks. It is validation-only: it returns field-keyed errors to merge, or
- *  nothing, and never transforms the data.
- */
-export interface DefineFieldsOptions<F extends readonly FrontmatterField[]> {
-  refine?: (data: InferFields<F>, body: string) => Record<string, string> | undefined;
-}
-
-// Compile each declared text/textarea pattern once, so a malformed pattern fails loudly at
-// declaration (a site config error) instead of throwing from inside validate() on every save.
-function compilePatterns(fields: FrontmatterField[]): Map<string, RegExp> {
-  const compiled = new Map<string, RegExp>();
-  for (const field of fields) {
-    if ((field.type === 'text' || field.type === 'textarea') && field.pattern != null) {
-      compiled.set(field.name, compilePattern(field.pattern, field.name));
-    }
-  }
-  return compiled;
-}
-
-// True when an image field feeds the social card: an explicit `seo: true`, or the back-compat
-// default that the field named `image` is the SEO image. The SEO unify (Task 4) reads this flag.
-function isSeoImage(field: FrontmatterField): boolean {
-  return field.type === 'image' && (field.seo === true || (field.seo === undefined && field.name === 'image'));
-}
-
-// A concept declares at most one SEO image field, so the social card is unambiguous. More than one
-// is a site config error: a hero named `cover` plus an explicit `seo` on another, or two explicit
-// `seo` fields. Fail loudly at declaration rather than emit a silent or wrong og:image.
-function checkSeoImageFields(fields: FrontmatterField[]): void {
-  const seo = fields.filter(isSeoImage);
-  if (seo.length > 1) {
-    const names = seo.map((field) => `"${field.name}"`).join(', ');
-    throw new Error(
-      `cairn: a concept declares at most one SEO image field, but found ${seo.length} (${names}). ` +
-        'Set seo: false on all but one, or rename the extra image fields so only one feeds the social card.',
-    );
-  }
-}
-
-/** Declare a concept's fields once. Returns the schema's faces derived from that one declaration. */
-export function defineFields<const F extends readonly FrontmatterField[]>(
-  fields: F,
-  options: DefineFieldsOptions<F> = {},
-): ConceptSchema<F> {
-  const list = [...fields] as FrontmatterField[];
-  const patterns = compilePatterns(list);
-  checkSeoImageFields(list);
-  const validate = (frontmatter: Record<string, unknown>, body: string): ValidationResult => {
-    const base = validateFields(list, frontmatter);
-    if (!base.ok) return base;
-    const errors: Record<string, string> = {};
-    for (const field of list) applyRules(field, base.data[field.name], errors, patterns);
-    if (Object.keys(errors).length > 0) return { ok: false, errors };
-    const refined = options.refine?.(base.data as InferFields<F>, body);
-    return refined && Object.keys(refined).length > 0 ? { ok: false, errors: refined } : base;
-  };
-  const standard: StandardSchemaV1<StandardInput, InferFields<F>>['~standard'] = {
-    version: 1,
-    vendor: 'cairn',
-    validate: (value) => {
-      const { frontmatter = {}, body = '' } = (value ?? {}) as Partial<StandardInput>;
-      const result = validate(frontmatter ?? {}, body ?? '');
-      return result.ok
-        ? { value: result.data as InferFields<F> }
-        : { issues: Object.entries(result.errors).map(([field, message]) => ({ message, path: [field] })) };
-    },
-  };
-  return { fields: list, validate, '~standard': standard };
-}

package/src/lib/content/validate.ts

@@ -1,90 +0,0 @@
-// cairn-cms: the field-driven baseline validator. A site's `validate` calls this for the
-// required-and-coerce baseline, then layers any bespoke rules on top, so the per-site
-// validator stays thin (engine-fat rule). Saving runs the concept's validator on the
-// server before any commit; invalid input bounces to the form (spec §7.4).
-import type { FrontmatterField, ImageValue, ValidationResult } from './types.js';
-import { dateInputValue, isCalendarDate } from './frontmatter.js';
-
-/**
- * Validate raw frontmatter against a field list. Required text and date fields must be
- * non-empty; required tag fields must be non-empty lists. A present boolean coerces to `true`
- * and an unchecked one is omitted; a present tag field coerces to a string array and an empty
- * one is omitted, so validated data carries no key for an absent tag field (`tags` or `freetags`).
- * The delivery read model
- * (`ContentSummary.tags`) fills that case with an empty array; the two layers differ on purpose.
- * An empty optional text or date field is omitted, so the normalized data
- * carries only meaningful values and committed frontmatter stays minimal. Returns the
- * normalized data, or field-keyed errors when any required field is empty.
- *
- * Frontmatter may arrive from the edit form (all string values) or from `parseMarkdown`,
- * where gray-matter turns an unquoted YAML date into a JS `Date`. The `date` case coerces a
- * `Date` to `YYYY-MM-DD` so a valid parsed date is not mistaken for an empty one.
- */
-export function validateFields(
-  fields: FrontmatterField[],
-  frontmatter: Record<string, unknown>,
-): ValidationResult {
-  const data: Record<string, unknown> = {};
-  const errors: Record<string, string> = {};
-  for (const field of fields) {
-    const value = frontmatter[field.name];
-    switch (field.type) {
-      case 'boolean':
-        // Absent or unchecked means false; omit it so a published file carries no draft: false noise.
-        if (value === true) data[field.name] = true;
-        break;
-      case 'tags':
-      case 'freetags': {
-        const list = Array.isArray(value) ? value.map(String) : [];
-        if (field.required && list.length === 0) errors[field.name] = `${field.label} is required`;
-        else if (field.type === 'tags') {
-          const unknown = list.find((tag) => !field.options.includes(tag));
-          if (unknown !== undefined) errors[field.name] = `${field.label} contains an unknown value: ${unknown}`;
-        }
-        if (list.length > 0) data[field.name] = list;
-        break;
-      }
-      case 'image': {
-        // A hero is the nested object { src, alt, caption }. Normalize a well-formed value (default
-        // a missing alt to empty, since alt is debt and never a save block), and drop the key when
-        // src is empty or absent. A malformed value (a string, or an object without a string src)
-        // drops the key rather than throwing, so a hand-edit never breaks a save.
-        let src = '';
-        if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
-          const obj = value as Record<string, unknown>;
-          src = typeof obj.src === 'string' ? obj.src.trim() : '';
-          if (src !== '') {
-            const normalized: ImageValue = {
-              src,
-              alt: typeof obj.alt === 'string' ? obj.alt : '',
-            };
-            const caption = typeof obj.caption === 'string' ? obj.caption.trim() : '';
-            if (caption !== '') normalized.caption = caption;
-            // An explicit decorative choice carries through; it is never required and never a save
-            // block. A missing or non-boolean value drops the key, like a blank caption.
-            if (obj.decorative === true) normalized.decorative = true;
-            data[field.name] = normalized;
-          }
-        }
-        // A required image needs a src (the presence check), like the other arms; alt is never
-        // required, since alt is debt. The inferred type makes a required image non-optional, so the
-        // validator must enforce it or a save could omit it against the type.
-        if (field.required && src === '') errors[field.name] = `${field.label} is required`;
-        break;
-      }
-      case 'date': {
-        const text = value instanceof Date ? dateInputValue(value) : typeof value === 'string' ? value.trim() : '';
-        if (field.required && text === '') errors[field.name] = `${field.label} is required`;
-        else if (text !== '' && !isCalendarDate(text)) errors[field.name] = `${field.label} must be a valid date (YYYY-MM-DD)`;
-        if (text !== '') data[field.name] = text;
-        break;
-      }
-      default: {
-        const text = typeof value === 'string' ? value.trim() : '';
-        if (field.required && text === '') errors[field.name] = `${field.label} is required`;
-        if (text !== '') data[field.name] = text;
-      }
-    }
-  }
-  return Object.keys(errors).length > 0 ? { ok: false, errors } : { ok: true, data };
-}