@crombolo/schema 0.0.0-stage → 0.9.1

package/src/validate.ts

@@ -0,0 +1,242 @@
+/**
+ * Whole-set validation. Every problem is reported, not just the first, because
+ * a person fixing a schema wants the full list.
+ */
+import { SYSTEM_MEDIA_TYPES, SYSTEM_MEMBER_TYPE } from '@crombolo/data'
+import {
+  BUILTIN_DATA_TYPE_ALIASES,
+  checkSystemContentTypeFile,
+  declaredProperties,
+  SYSTEM_CONTENT_TYPE_ALIASES,
+  SYSTEM_MEDIA_TYPE_ALIASES,
+} from './builtin.ts'
+import {
+  allProperties,
+  type SchemaContentType,
+  type SchemaProblem,
+  type SchemaSet,
+  TYPE_KIND_FILES,
+} from './model.ts'
+import { type ValidateFormsOptions, validateForms } from './validate-forms.ts'
+
+export interface ValidateOptions extends ValidateFormsOptions {
+  /** Template aliases that exist as view files; omit to skip template checks. */
+  componentAliases?: ReadonlySet<string>
+}
+
+const VERSION = /^\d+(\.\d+)*$/
+
+export function validateSchemaSet(set: SchemaSet, options: ValidateOptions = {}): SchemaProblem[] {
+  const problems: SchemaProblem[] = []
+  const add = (file: string, path: string, message: string) =>
+    problems.push({ file, path, message })
+
+  if (!VERSION.test(set.version))
+    add('schema/schema.toml', 'schema.version', `"${set.version}" is not a dotted number`)
+
+  const dataTypeAliases = new Set(BUILTIN_DATA_TYPE_ALIASES)
+  const seenDataTypes = new Set<string>()
+  for (const d of set.dataTypes) {
+    const file = `schema/data-types/${d.alias}`
+    if (seenDataTypes.has(d.alias))
+      add(file, 'data-type.alias', `duplicate data type alias "${d.alias}"`)
+    seenDataTypes.add(d.alias)
+    dataTypeAliases.add(d.alias)
+    if (d.since && !VERSION.test(d.since))
+      add(file, 'data-type.since', `"${d.since}" is not a dotted number`)
+  }
+
+  // Both kinds share one alias space (Umbraco's content_type.alias is unique);
+  // compositions and allowed children stay within a kind.
+  const typeAliases = new Set<string>()
+  const keys = new Map<string, string>()
+  const kinds: Array<{ types: readonly SchemaContentType[]; header: string; dir: string }> = [
+    { types: set.contentTypes, ...TYPE_KIND_FILES.document },
+    { types: set.mediaTypes ?? [], ...TYPE_KIND_FILES.media },
+    { types: set.memberTypes ?? [], ...TYPE_KIND_FILES.member },
+  ]
+  for (const { types, header, dir } of kinds) {
+    for (const t of types) {
+      const file = `schema/${dir}/${t.alias}`
+      // A system type's alias belongs to it; a file may override it only by its key.
+      const system = SYSTEM_MEDIA_TYPES.find((s) => s.alias.toLowerCase() === t.alias.toLowerCase())
+      if (system && (dir !== 'media-types' || (t.key && t.key.toLowerCase() !== system.key)))
+        add(
+          file,
+          `${header}.alias`,
+          `"${t.alias}" is the system media type ${system.alias}; choose another alias, or override ${system.alias} with key "${system.key}"`,
+        )
+      const isSystemMember = t.alias.toLowerCase() === SYSTEM_MEMBER_TYPE.alias.toLowerCase()
+      if (
+        isSystemMember &&
+        (dir !== 'member-types' || (t.key && t.key.toLowerCase() !== SYSTEM_MEMBER_TYPE.key))
+      )
+        add(
+          file,
+          `${header}.alias`,
+          `"${t.alias}" is the built-in member type; choose another alias, or override it with key "${SYSTEM_MEMBER_TYPE.key}"`,
+        )
+      if (typeAliases.has(t.alias))
+        add(file, `${header}.alias`, `duplicate type alias "${t.alias}"`)
+      typeAliases.add(t.alias)
+      if (t.key) {
+        const owner = keys.get(t.key)
+        if (owner) add(file, `${header}.key`, `key already used by "${owner}"`)
+        keys.set(t.key, t.alias)
+      }
+      if (t.since && !VERSION.test(t.since))
+        add(file, `${header}.since`, `"${t.since}" is not a dotted number`)
+      const propertyAliases = new Set<string>()
+      for (const p of allProperties(t)) {
+        const path = `property "${p.alias}"`
+        if (dir !== 'member-types' && (p.memberCanView || p.memberCanEdit || p.sensitive))
+          add(file, path, 'member-can-view, member-can-edit and sensitive belong to member types')
+        if (propertyAliases.has(p.alias)) add(file, path, 'duplicate property alias')
+        propertyAliases.add(p.alias)
+        if (!dataTypeAliases.has(p.type)) add(file, `${path}.type`, `unknown data type "${p.type}"`)
+        if (p.key) {
+          const owner = keys.get(p.key)
+          if (owner) add(file, `${path}.key`, `key already used by "${owner}"`)
+          keys.set(p.key, `${t.alias}.${p.alias}`)
+        }
+        if (p.since && !VERSION.test(p.since))
+          add(file, `${path}.since`, `"${p.since}" is not a dotted number`)
+        if (p.variesByCulture && !t.variesByCulture)
+          add(
+            file,
+            `${path}.varies-by-culture`,
+            'the type does not vary by culture, so the property cannot',
+          )
+      }
+      // An element type is a property bag with no URL, so the things a route needs
+      // do not apply to it. A media-type file rejects these outright because they
+      // are not in its vocabulary at all; here they are valid keys made invalid by
+      // `is-element`, so the rule lives at this level rather than in the parser.
+      // Silently ignoring them is worse: the file says one thing and the editor
+      // another.
+      if (t.isElement) {
+        if (t.components.length > 0)
+          add(file, `${header}.components`, 'an element type has no component: it is never routed')
+        if (t.defaultComponent)
+          add(
+            file,
+            `${header}.default-component`,
+            'an element type has no template: it is never routed',
+          )
+        if (t.allowAtRoot)
+          add(
+            file,
+            `${header}.allow-at-root`,
+            'an element type is not created in the content tree; use allow-in-library',
+          )
+        if (t.allowChildren.length > 0)
+          add(
+            file,
+            `${header}.allow-children`,
+            'an element type has no children: it is not in the content tree',
+          )
+      }
+      if (t.defaultComponent && !t.components.includes(t.defaultComponent))
+        add(file, `${header}.default-component`, `"${t.defaultComponent}" is not in components`)
+      if (options.componentAliases) {
+        for (const alias of t.components)
+          if (!options.componentAliases.has(alias))
+            add(file, `${header}.components`, `no components/${alias}.tsx`)
+      }
+    }
+
+    // References between types, once every alias is known. First occurrence wins,
+    // so a duplicate alias (already reported) cannot shadow the real definition.
+    const byAlias = new Map<string, SchemaContentType>()
+    for (const t of types) if (!byAlias.has(t.alias)) byAlias.set(t.alias, t)
+    // System types exist whether or not a file defines them.
+    const known = (alias: string) =>
+      byAlias.has(alias) ||
+      (dir === TYPE_KIND_FILES.media.dir && SYSTEM_MEDIA_TYPE_ALIASES.has(alias)) ||
+      (dir === TYPE_KIND_FILES.document.dir && SYSTEM_CONTENT_TYPE_ALIASES.has(alias))
+    for (const t of types) {
+      const file = `schema/${dir}/${t.alias}`
+      if (dir === TYPE_KIND_FILES.document.dir)
+        for (const message of checkSystemContentTypeFile(t)) add(file, header, message)
+      for (const c of t.compositions) {
+        if (!known(c)) add(file, `${header}.compositions`, `unknown type "${c}"`)
+        // Values are stored by the property's own variance, so a culture-varying
+        // field on a type that does not vary would split one page's value by language.
+        const composed = byAlias.get(c)
+        if (
+          composed &&
+          !t.variesByCulture &&
+          declaredProperties(composed).some((p) => p.variesByCulture)
+        )
+          add(
+            file,
+            `${header}.compositions`,
+            `"${c}" has fields that vary by culture, so this type must vary by culture too`,
+          )
+      }
+      for (const c of t.allowChildren)
+        if (!known(c)) add(file, `${header}.allow-children`, `unknown type "${c}"`)
+      if (t.collection && !dataTypeAliases.has(t.collection))
+        add(file, `${header}.collection`, `unknown data type "${t.collection}"`)
+    }
+    for (const t of types) {
+      const cycle = findCompositionCycle(t.alias, byAlias)
+      if (cycle)
+        add(
+          `schema/${dir}/${t.alias}`,
+          `${header}.compositions`,
+          `composition cycle: ${cycle.join(' -> ')}`,
+        )
+    }
+  }
+
+  const defaults = set.languages.filter((l) => l.default)
+  if (set.languages.length > 0 && defaults.length !== 1)
+    add(
+      'schema/languages.toml',
+      'language',
+      `exactly one language must be default; found ${defaults.length}`,
+    )
+  const isos = new Set<string>()
+  for (const l of set.languages) {
+    if (isos.has(l.iso.toLowerCase()))
+      add('schema/languages.toml', `language "${l.iso}"`, 'duplicate language')
+    isos.add(l.iso.toLowerCase())
+  }
+  for (const l of set.languages) {
+    if (l.fallback && !isos.has(l.fallback.toLowerCase()))
+      add(
+        'schema/languages.toml',
+        `language "${l.iso}".fallback`,
+        `unknown language "${l.fallback}"`,
+      )
+  }
+  // Forms are validated against the types they reach into, so this happens
+  // after the type aliases are known.
+  problems.push(
+    ...validateForms(set.forms ?? [], {
+      ...options,
+      contentTypeAliases:
+        options.contentTypeAliases ?? new Set(set.contentTypes.map((t) => t.alias)),
+    }),
+  )
+  return problems
+}
+
+function findCompositionCycle(
+  start: string,
+  byAlias: Map<string, { compositions: string[] }>,
+): string[] | undefined {
+  const walk = (alias: string, trail: string[]): string[] | undefined => {
+    if (trail.includes(alias)) return [...trail.slice(trail.indexOf(alias)), alias]
+    const type = byAlias.get(alias)
+    if (!type) return undefined
+    for (const next of type.compositions) {
+      const found = walk(next, [...trail, alias])
+      if (found) return found
+    }
+    return undefined
+  }
+  const found = walk(start, [])
+  return found && found[0] === start ? found : undefined
+}

package/src/value-migrations.ts

@@ -0,0 +1,122 @@
+/**
+ * Value migrations: one construct for a site's `schema/migrations/*.ts` and
+ * for the converters the framework ships. `convert` returns the new value —
+ * or, for a split, an object keyed by target property — and throws to say a
+ * value needs a person. docs/10, "Site-authored value migrations".
+ */
+import { existsSync, readdirSync } from 'node:fs'
+import { basename, join } from 'node:path'
+
+export interface ValueMigrationContext {
+  documentKey: string
+  culture: string | null
+  segment: string | null
+}
+
+export interface ValueMigration {
+  /** Ledger name; the file name by default. */
+  id: string
+  /** True when the definition named itself; the loader keeps such an id. */
+  explicitId?: boolean
+  /** Applies from this schema version on; informational. */
+  since?: string
+  from: { type: string; property: string }
+  to: Array<{ property: string }>
+  convert(value: unknown, context: ValueMigrationContext): unknown
+}
+
+export interface ValueMigrationDefinition {
+  id?: string
+  since?: string
+  from: { type: string; property: string }
+  to: { property: string } | Array<{ property: string }>
+  convert(value: unknown, context: ValueMigrationContext): unknown
+}
+
+export function defineValueMigration(definition: ValueMigrationDefinition): ValueMigration {
+  const to = Array.isArray(definition.to) ? definition.to : [definition.to]
+  if (to.length === 0) throw new Error('a value migration needs at least one target property')
+  const migration: ValueMigration = {
+    id:
+      definition.id ??
+      `${definition.from.type}.${definition.from.property}->${to.map((t) => t.property).join('+')}`,
+    explicitId: definition.id !== undefined,
+    from: definition.from,
+    to,
+    convert: definition.convert,
+  }
+  if (definition.since) migration.since = definition.since
+  return migration
+}
+
+/** Normalises `convert`'s result to one value per target property. */
+export function outputsOf(migration: ValueMigration, result: unknown): Map<string, unknown> {
+  const out = new Map<string, unknown>()
+  if (migration.to.length === 1) {
+    const single = migration.to[0]?.property as string
+    const record = result as Record<string, unknown> | null
+    out.set(
+      single,
+      record && typeof record === 'object' && !Array.isArray(record) && single in record
+        ? record[single]
+        : result,
+    )
+    return out
+  }
+  const record = (result ?? {}) as Record<string, unknown>
+  for (const target of migration.to) out.set(target.property, record[target.property] ?? null)
+  return out
+}
+
+/** Every `schema/migrations/*.ts` default export, sorted by file name. */
+export async function loadValueMigrations(schemaDir: string): Promise<ValueMigration[]> {
+  const dir = join(schemaDir, 'migrations')
+  if (!existsSync(dir)) return []
+  const out: ValueMigration[] = []
+  for (const name of readdirSync(dir)
+    .filter((n) => /\.(ts|js)$/.test(n))
+    .sort()) {
+    const module = (await import(join(dir, name))) as {
+      default?: ValueMigration | ValueMigrationDefinition
+    }
+    const value = module.default
+    if (!value) throw new Error(`schema/migrations/${name} has no default export`)
+    const migration =
+      'id' in value && Array.isArray((value as ValueMigration).to)
+        ? (value as ValueMigration)
+        : defineValueMigration(value as ValueMigrationDefinition)
+    if (!migration.explicitId) migration.id = basename(name).replace(/\.(ts|js)$/, '')
+    out.push(migration)
+  }
+  return out
+}
+
+/** A framework converter between two property editors' stored formats. */
+export interface ValueConverter {
+  from: string
+  to: string
+  convert(value: unknown, context: ValueMigrationContext): unknown
+}
+
+const converters = new Map<string, ValueConverter>()
+const key = (from: string, to: string) => `${from}->${to}`
+
+export function registerConverter(converter: ValueConverter): void {
+  converters.set(key(converter.from, converter.to), converter)
+}
+
+export function findConverter(from: string, to: string): ValueConverter | undefined {
+  if (from === to) return { from, to, convert: (v) => v }
+  return converters.get(key(from, to))
+}
+
+// Editors whose stored text is the same shape: a plain copy converts.
+for (const [from, to] of [
+  ['Umbraco.TextBox', 'Umbraco.TextArea'],
+  ['Umbraco.TextArea', 'Umbraco.TextBox'],
+  ['Umbraco.TextBox', 'Umbraco.RichText'],
+  ['Umbraco.TextArea', 'Umbraco.RichText'],
+  ['Umbraco.TextBox', 'Umbraco.Label'],
+]) {
+  registerConverter({ from: from as string, to: to as string, convert: (v) => v })
+}

package/src/version.ts

@@ -0,0 +1,53 @@
+/**
+ * The site's schema version, and what a change does to it.
+ *
+ * A developer owns this number when schema arrives by deploy. When an editor
+ * changes a type on a running site the number still has to move, for two
+ * reasons: `compareStates` reads it first, so it is how other nodes learn they
+ * are behind, and a production sync refuses a changed hash at an unchanged
+ * version — the guard that makes silent drift impossible.
+ *
+ * How far it moves is decided by the same check that gates an upgrade, so the
+ * number means something: a major says content had to be converted to get here.
+ */
+import type { ChangeClass } from './check.ts'
+
+/** `1.4.2` → `[1, 4, 2]`, tolerant of a short or over-long version. */
+function parts(version: string): [number, number, number] {
+  // `??` will not do: parseInt('') is NaN, which is neither null nor undefined,
+  // and `NaN + 1` would spread through the whole version.
+  const at = (index: number): number => {
+    const parsed = Number.parseInt(version.split('.')[index] ?? '', 10)
+    return Number.isFinite(parsed) ? parsed : 0
+  }
+  return [at(0), at(1), at(2)]
+}
+
+/**
+ * The version a change should land on.
+ *
+ * - `breaking` — a property's editor changed under live content, or a type with
+ *   content was removed: **major**, because getting here converted data.
+ * - `data-requiring` — a new mandatory property, or a value migration to run:
+ *   **minor**. Content has to be filled in, but nothing was lost.
+ * - `additive` — a new type or property: **minor**.
+ * - `none` — nothing to apply, so nothing to bump.
+ *
+ * A major resets what is below it, as semver does, so 1.4.2 breaking is 2.0.0
+ * rather than 2.4.2.
+ */
+export function nextSchemaVersion(current: string, classification: ChangeClass): string {
+  const [major, minor, patch] = parts(current)
+  switch (classification) {
+    case 'breaking':
+      return `${major + 1}.0.0`
+    case 'data-requiring':
+    case 'additive':
+      return `${major}.${minor + 1}.0`
+    default:
+      return `${major}.${minor}.${patch}`
+  }
+}
+
+/** Whether a classification moves the version at all. */
+export const bumps = (classification: ChangeClass): boolean => classification !== 'none'

package/src/write-forms.ts

@@ -0,0 +1,139 @@
+/**
+ * A form definition → canonical TOML.
+ *
+ * Same contract as `write.ts`: deterministic key order, one layout, and
+ * `parseForm(writeForm(x))` equal to `x`. Held to that by the suite, which is
+ * what lets the backoffice write a file a person will read in a diff.
+ */
+import type {
+  FormCondition,
+  SchemaForm,
+  SchemaFormField,
+  SchemaFormGroup,
+  SchemaFormPage,
+  SchemaFormWorkflow,
+} from '@crombolo/core'
+
+function str(value: string): string {
+  return JSON.stringify(value)
+}
+
+function scalar(value: unknown): string {
+  if (typeof value === 'string') return str(value)
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value)
+  if (Array.isArray(value)) return `[${value.map(scalar).join(', ')}]`
+  if (value === null || value === undefined) return '""'
+  return str(JSON.stringify(value))
+}
+
+/** Workflow settings arrive from the API, so a key may need quoting. */
+function keyOf(key: string): string {
+  return /^[A-Za-z0-9_-]+$/.test(key) ? key : str(key)
+}
+
+function line(out: string[], key: string, value: unknown, when = true): void {
+  if (!when || value === undefined) return
+  out.push(`${keyOf(key)} = ${scalar(value)}`)
+}
+
+/**
+ * The rules on one line, as an array of inline tables.
+ *
+ * A condition is short and reads better as one line than as five tables, and
+ * `[[…rule]]` would otherwise have to be ordered against the sub-tables around
+ * it — which is the kind of TOML that is easy to write and hard to read.
+ */
+function writeCondition(out: string[], header: string, condition: FormCondition): void {
+  out.push('', `[${header}]`)
+  line(out, 'action', condition.action)
+  line(out, 'match', condition.match)
+  const rules = condition.rules.map((rule) => {
+    const parts = [`field = ${str(rule.field)}`, `operator = ${str(rule.operator)}`]
+    if (rule.value !== undefined) parts.push(`value = ${str(rule.value)}`)
+    return `{ ${parts.join(', ')} }`
+  })
+  out.push(`rule = [${rules.join(', ')}]`)
+}
+
+function writeField(out: string[], header: string, field: SchemaFormField): void {
+  out.push('', `[[${header}]]`)
+  line(out, 'key', field.key)
+  line(out, 'alias', field.alias)
+  line(out, 'type', field.type)
+  line(out, 'caption', field.caption)
+  line(out, 'help-text', field.helpText)
+  // Consent defaults to mandatory, so the key is written only when it differs
+  // from what the parser would infer — otherwise a round trip would add it.
+  const mandatoryByDefault = field.type === 'dataConsent'
+  line(out, 'mandatory', field.mandatory, field.mandatory !== mandatoryByDefault)
+  line(out, 'mandatory-message', field.mandatoryMessage)
+  line(out, 'pattern', field.pattern)
+  line(out, 'pattern-message', field.patternMessage)
+  line(out, 'sensitive', true, field.sensitive)
+  line(out, 'css-class', field.cssClass)
+  line(out, 'autocomplete', field.autocomplete)
+  line(out, 'values', field.values, field.values.length > 0)
+  line(out, 'placeholder', field.placeholder)
+  line(out, 'default-value', field.defaultValue)
+  line(out, 'content', field.content)
+  line(out, 'maxlength', field.maxlength)
+  line(out, 'rows', field.rows)
+  line(out, 'min', field.min)
+  line(out, 'max', field.max)
+  line(out, 'step', field.step)
+  line(out, 'accept', field.accept, field.accept.length > 0)
+  line(out, 'max-size-kb', field.maxSizeKb)
+  line(out, 'multiple', field.multiple)
+  if (field.condition) writeCondition(out, `${header}.condition`, field.condition)
+}
+
+function writeGroup(out: string[], header: string, group: SchemaFormGroup): void {
+  out.push('', `[[${header}]]`)
+  line(out, 'caption', group.caption)
+  line(out, 'columns', group.columns, group.columns !== 1)
+  if (group.condition) writeCondition(out, `${header}.condition`, group.condition)
+  for (const field of group.fields) writeField(out, `${header}.field`, field)
+}
+
+function writePage(out: string[], page: SchemaFormPage): void {
+  out.push('', '[[page]]')
+  line(out, 'caption', page.caption)
+  if (page.condition) writeCondition(out, 'page.condition', page.condition)
+  for (const group of page.groups) writeGroup(out, 'page.group', group)
+}
+
+function writeWorkflow(out: string[], workflow: SchemaFormWorkflow): void {
+  out.push('', '[[workflow]]')
+  line(out, 'key', workflow.key)
+  line(out, 'type', workflow.type)
+  line(out, 'name', workflow.name)
+  line(out, 'on', workflow.on, workflow.on !== 'submit')
+  const keys = Object.keys(workflow.settings).sort()
+  if (keys.length > 0) {
+    out.push('', '[workflow.settings]')
+    for (const key of keys) line(out, key, workflow.settings[key])
+  }
+}
+
+export function writeForm(form: SchemaForm): string {
+  const out: string[] = ['[form]']
+  line(out, 'key', form.key)
+  line(out, 'alias', form.alias)
+  line(out, 'name', form.name)
+  line(out, 'notes', form.notes)
+  line(out, 'store-entries', false, !form.storeEntries)
+  line(out, 'requires-approval', true, form.requiresApproval)
+  line(out, 'submit-label', form.submitLabel)
+  line(out, 'next-label', form.nextLabel)
+  line(out, 'previous-label', form.previousLabel)
+  line(out, 'message-on-submit', form.messageOnSubmit)
+  line(out, 'redirect-to', form.redirectTo)
+  line(out, 'theme', form.theme)
+  line(out, 'honeypot', false, !form.honeypot)
+  line(out, 'minimum-submit-seconds', form.minimumSubmitSeconds)
+  line(out, 'max-entries', form.maxEntries)
+  line(out, 'since', form.since)
+  for (const page of form.pages) writePage(out, page)
+  for (const workflow of form.workflows) writeWorkflow(out, workflow)
+  return `${out.join('\n')}\n`
+}