@owlmeans/client-planning 0.1.18-rc.8 → 0.1.18

package/src/validation/consts.ts

@@ -0,0 +1,289 @@
+/** Draft 7 vocabulary, plus AJV's $defs spelling. Other vocabularies fail closed. */
+export const FIELD_SCHEMA_KEYWORDS = new Set([
+  '$id', '$schema', '$ref', '$comment', '$defs', 'definitions', 'type', 'nullable', 'const', 'enum',
+  'required', 'properties', 'patternProperties', 'additionalProperties', 'propertyNames',
+  'minProperties', 'maxProperties', 'dependencies', 'items', 'additionalItems', 'contains',
+  'minItems', 'maxItems', 'uniqueItems', 'minimum', 'maximum', 'exclusiveMinimum',
+  'exclusiveMaximum', 'multipleOf', 'minLength', 'maxLength', 'pattern', 'format',
+  'allOf', 'anyOf', 'oneOf', 'not', 'if', 'then', 'else', 'title', 'description', 'default',
+  'examples', 'readOnly', 'writeOnly', 'contentMediaType', 'contentEncoding',
+])
+export const FIELD_SCHEMA_MAPS = new Set(['properties', 'patternProperties', 'definitions', '$defs'])
+export const FIELD_SCHEMA_ARRAYS = new Set(['allOf', 'anyOf', 'oneOf'])
+export const FIELD_SCHEMA_CHILDREN = new Set([
+  'additionalProperties', 'propertyNames', 'additionalItems', 'contains', 'not', 'if', 'then', 'else',
+])
+export const FIELD_SCHEMA_ANNOTATIONS = new Set([
+  '$comment', 'title', 'description', 'default', 'examples', 'readOnly', 'writeOnly',
+  'contentMediaType', 'contentEncoding',
+])
+export const FIELD_SCHEMA_DRAFTS = new Set([
+  'http://json-schema.org/draft-07/schema', 'http://json-schema.org/draft-07/schema#',
+  'https://json-schema.org/draft-07/schema', 'https://json-schema.org/draft-07/schema#',
+])
+/** Reserved predicates never replace cfworker's own global format definitions. */
+export const FIELD_FORMAT_PREFIX = 'owlmeans-planning:'
+export const MAX_FIELD_ERRORS = 64
+export const MAX_FIELD_ERROR_PATH = 512
+export const REQUIRED_ERROR_PREFIX = 'Instance does not have required property "'
+export const REQUIRED_ERROR_SUFFIX = '".'
+export const FIELD_ERROR_WRAPPERS = new Set(['properties', 'patternProperties', 'items', '$ref', 'allOf', 'if'])
+export const FIELD_ERROR_MESSAGES: Readonly<Record<string, string>> = {
+  required: 'A required field is missing', type: 'The field has an invalid type',
+  enum: 'Choose one of the allowed values', const: 'The field must match its fixed value',
+  format: 'The field has an invalid format', pattern: 'The field does not match its required pattern',
+  additionalProperties: 'This field is not allowed', additionalItems: 'This item is not allowed',
+  minimum: 'The value is below its minimum', maximum: 'The value exceeds its maximum',
+  exclusiveMinimum: 'The value must exceed its minimum', exclusiveMaximum: 'The value must be below its maximum',
+  multipleOf: 'The value is not an allowed multiple', minLength: 'The value is too short',
+  maxLength: 'The value is too long', minItems: 'There are too few items', maxItems: 'There are too many items',
+  uniqueItems: 'Items must be distinct', minProperties: 'There are too few fields', maxProperties: 'There are too many fields',
+}
+
+/**
+ * The JSON Schema draft-07 meta-schema a field schema is checked against — ajv's own
+ * `refs/json-schema-draft-07.json`, kept here as data. Importing that file directly needs a JSON
+ * import attribute in Node, and a bundler that also meets ajv's own attribute-less `require` of the
+ * same file refuses the two (Rollup: "import attributes for the same module are always consistent").
+ */
+export const JSON_SCHEMA_DRAFT_07: Readonly<Record<string, unknown>> = Object.freeze({
+  '$schema': 'http://json-schema.org/draft-07/schema#',
+  '$id': 'http://json-schema.org/draft-07/schema#',
+  'title': 'Core schema meta-schema',
+  'definitions': {
+    'schemaArray': {
+      'type': 'array',
+      'minItems': 1,
+      'items': {
+        '$ref': '#'
+      }
+    },
+    'nonNegativeInteger': {
+      'type': 'integer',
+      'minimum': 0
+    },
+    'nonNegativeIntegerDefault0': {
+      'allOf': [
+        {
+          '$ref': '#/definitions/nonNegativeInteger'
+        },
+        {
+          'default': 0
+        }
+      ]
+    },
+    'simpleTypes': {
+      'enum': [
+        'array',
+        'boolean',
+        'integer',
+        'null',
+        'number',
+        'object',
+        'string'
+      ]
+    },
+    'stringArray': {
+      'type': 'array',
+      'items': {
+        'type': 'string'
+      },
+      'uniqueItems': true,
+      'default': []
+    }
+  },
+  'type': [
+    'object',
+    'boolean'
+  ],
+  'properties': {
+    '$id': {
+      'type': 'string',
+      'format': 'uri-reference'
+    },
+    '$schema': {
+      'type': 'string',
+      'format': 'uri'
+    },
+    '$ref': {
+      'type': 'string',
+      'format': 'uri-reference'
+    },
+    '$comment': {
+      'type': 'string'
+    },
+    'title': {
+      'type': 'string'
+    },
+    'description': {
+      'type': 'string'
+    },
+    'default': true,
+    'readOnly': {
+      'type': 'boolean',
+      'default': false
+    },
+    'examples': {
+      'type': 'array',
+      'items': true
+    },
+    'multipleOf': {
+      'type': 'number',
+      'exclusiveMinimum': 0
+    },
+    'maximum': {
+      'type': 'number'
+    },
+    'exclusiveMaximum': {
+      'type': 'number'
+    },
+    'minimum': {
+      'type': 'number'
+    },
+    'exclusiveMinimum': {
+      'type': 'number'
+    },
+    'maxLength': {
+      '$ref': '#/definitions/nonNegativeInteger'
+    },
+    'minLength': {
+      '$ref': '#/definitions/nonNegativeIntegerDefault0'
+    },
+    'pattern': {
+      'type': 'string',
+      'format': 'regex'
+    },
+    'additionalItems': {
+      '$ref': '#'
+    },
+    'items': {
+      'anyOf': [
+        {
+          '$ref': '#'
+        },
+        {
+          '$ref': '#/definitions/schemaArray'
+        }
+      ],
+      'default': true
+    },
+    'maxItems': {
+      '$ref': '#/definitions/nonNegativeInteger'
+    },
+    'minItems': {
+      '$ref': '#/definitions/nonNegativeIntegerDefault0'
+    },
+    'uniqueItems': {
+      'type': 'boolean',
+      'default': false
+    },
+    'contains': {
+      '$ref': '#'
+    },
+    'maxProperties': {
+      '$ref': '#/definitions/nonNegativeInteger'
+    },
+    'minProperties': {
+      '$ref': '#/definitions/nonNegativeIntegerDefault0'
+    },
+    'required': {
+      '$ref': '#/definitions/stringArray'
+    },
+    'additionalProperties': {
+      '$ref': '#'
+    },
+    'definitions': {
+      'type': 'object',
+      'additionalProperties': {
+        '$ref': '#'
+      },
+      'default': {}
+    },
+    'properties': {
+      'type': 'object',
+      'additionalProperties': {
+        '$ref': '#'
+      },
+      'default': {}
+    },
+    'patternProperties': {
+      'type': 'object',
+      'additionalProperties': {
+        '$ref': '#'
+      },
+      'propertyNames': {
+        'format': 'regex'
+      },
+      'default': {}
+    },
+    'dependencies': {
+      'type': 'object',
+      'additionalProperties': {
+        'anyOf': [
+          {
+            '$ref': '#'
+          },
+          {
+            '$ref': '#/definitions/stringArray'
+          }
+        ]
+      }
+    },
+    'propertyNames': {
+      '$ref': '#'
+    },
+    'const': true,
+    'enum': {
+      'type': 'array',
+      'items': true,
+      'minItems': 1,
+      'uniqueItems': true
+    },
+    'type': {
+      'anyOf': [
+        {
+          '$ref': '#/definitions/simpleTypes'
+        },
+        {
+          'type': 'array',
+          'items': {
+            '$ref': '#/definitions/simpleTypes'
+          },
+          'minItems': 1,
+          'uniqueItems': true
+        }
+      ]
+    },
+    'format': {
+      'type': 'string'
+    },
+    'contentMediaType': {
+      'type': 'string'
+    },
+    'contentEncoding': {
+      'type': 'string'
+    },
+    'if': {
+      '$ref': '#'
+    },
+    'then': {
+      '$ref': '#'
+    },
+    'else': {
+      '$ref': '#'
+    },
+    'allOf': {
+      '$ref': '#/definitions/schemaArray'
+    },
+    'anyOf': {
+      '$ref': '#/definitions/schemaArray'
+    },
+    'oneOf': {
+      '$ref': '#/definitions/schemaArray'
+    },
+    'not': {
+      '$ref': '#'
+    }
+  },
+  'default': true
+})

package/src/validation/types.ts

@@ -0,0 +1,18 @@
+export interface PlanningFieldError {
+  /** Decoded field path; a required-property error includes the missing property's name. */
+  path: string
+  keyword: string
+  schemaPath: string
+  /** A bounded explanation which does not include the submitted value. */
+  message: string
+}
+
+export interface PlanningFieldValidation {
+  valid: boolean
+  errors: PlanningFieldError[]
+}
+
+export interface PlanningFieldValidator {
+  /** Validate without coercion, defaults, removal, code generation or network reference loading. */
+  validateFields: (fields: Record<string, unknown>) => PlanningFieldValidation
+}

package/src/validation.ts

@@ -0,0 +1,140 @@
+import { dereference, format, validate as interpret, Validator } from '@cfworker/json-schema'
+import type { OutputUnit, Schema } from '@cfworker/json-schema'
+import type { AnySchema, Format } from 'ajv'
+import formatsPlugin from 'ajv-formats'
+import type { FormatName } from 'ajv-formats'
+import { SchemaInvalid } from '@owlmeans/planning'
+import type { PlanningFieldError, PlanningFieldValidation, PlanningFieldValidator } from './validation/types.js'
+import {
+  FIELD_ERROR_MESSAGES, FIELD_ERROR_WRAPPERS, FIELD_FORMAT_PREFIX, FIELD_SCHEMA_ANNOTATIONS, FIELD_SCHEMA_ARRAYS,
+  FIELD_SCHEMA_CHILDREN, FIELD_SCHEMA_DRAFTS, FIELD_SCHEMA_KEYWORDS, FIELD_SCHEMA_MAPS,
+  JSON_SCHEMA_DRAFT_07, MAX_FIELD_ERRORS, MAX_FIELD_ERROR_PATH, REQUIRED_ERROR_PREFIX, REQUIRED_ERROR_SUFFIX,
+} from './validation/consts.js'
+
+/**
+ * Interpret the exact served field schema under a strict script-src policy. The vocabulary is
+ * Draft 7/$defs/nullable with AJV reference-sibling semantics and its full string-format predicates.
+ * Unsupported dialects/extensions, numeric formats and multipleOf schemas refuse
+ * during preparation; the server's AJV remains the authoritative validator.
+ */
+export const makePlanningFieldValidator = (fieldsSchema: AnySchema): PlanningFieldValidator => {
+  const invalid = (path: string, keyword: string): never => {
+    throw new SchemaInvalid(`client:fields:${keyword}:${path.slice(0, MAX_FIELD_ERROR_PATH)}`)
+  }
+  const pointer = (part: string): string => part.replaceAll('~', '~0').replaceAll('/', '~1')
+  const nodes = new Map<Schema, string>()
+  const meta = new Validator(structuredClone(JSON_SCHEMA_DRAFT_07) as Schema, '7', false)
+
+  const prepare = (source: unknown, path: string): Schema | boolean => {
+    if (typeof source === 'boolean') return source
+    if (source == null || typeof source !== 'object' || Array.isArray(source)) return invalid(path, 'schema')
+    const checked = meta.validate(source)
+    if (!checked.valid) return invalid(`${path}${checked.errors[0]?.instanceLocation.slice(1) ?? ''}`, 'malformed')
+    const node: Schema = {}
+    nodes.set(node, path)
+    for (const [key, value] of Object.entries(source)) {
+      const next = `${path}/${pointer(key)}`
+      if (!FIELD_SCHEMA_KEYWORDS.has(key) && !key.startsWith('x-')) invalid(next, 'unsupported-keyword')
+      if (FIELD_SCHEMA_ANNOTATIONS.has(key) || key.startsWith('x-')) continue
+      if (key === 'nullable') continue
+      if (key === '$schema' && !FIELD_SCHEMA_DRAFTS.has(String(value))) invalid(next, 'unsupported-draft')
+      // The interpreters disagree on floating tolerance and large/scientific-notation quotients.
+      if (key === 'multipleOf') invalid(next, 'unsupported-multipleOf')
+      if (key === 'format') {
+        let definition: Format
+        try { definition = formatsPlugin.get(value as FormatName, 'full') }
+        catch { return invalid(next, 'unsupported-format') }
+        if (typeof definition === 'object' && !(definition instanceof RegExp) && definition.type === 'number') {
+          invalid(next, 'unsupported-numeric-format')
+        }
+        if (typeof definition === 'object' && !(definition instanceof RegExp) && 'async' in definition && definition.async === true) {
+          invalid(next, 'unsupported-async-format')
+        }
+        const guard = typeof definition === 'object' && !(definition instanceof RegExp) ? definition.validate : definition
+        const predicate = typeof guard === 'string' ? new RegExp(guard, 'u') : guard
+        const name = `${FIELD_FORMAT_PREFIX}${String(value)}`
+        format[name] ??= input => predicate === true || (predicate instanceof RegExp ? predicate.test(input)
+          : (predicate as (value: string) => boolean)(input)) === true
+        node.format = name
+      } else if (FIELD_SCHEMA_MAPS.has(key)) {
+        if (value == null || typeof value !== 'object' || Array.isArray(value)) invalid(next, 'malformed')
+        node[key] = Object.fromEntries(Object.entries(value as Record<string, unknown>)
+          .map(([name, child]) => [name, prepare(child, `${next}/${pointer(name)}`)]))
+      } else if (FIELD_SCHEMA_ARRAYS.has(key) || (key === 'items' && Array.isArray(value))) {
+        node[key] = (value as unknown[]).map((child, index) => prepare(child, `${next}/${index}`))
+      } else if (FIELD_SCHEMA_CHILDREN.has(key) || key === 'items') {
+        node[key] = prepare(value, next)
+      } else if (key === 'dependencies') {
+        ;(node as Record<string, unknown>)[key] = Object.fromEntries(Object.entries(value as Record<string, unknown>)
+          .map(([name, child]) => [name, Array.isArray(child) ? child : prepare(child, `${next}/${pointer(name)}`)]))
+      } else { node[key] = structuredClone(value) }
+    }
+    if ('nullable' in source) {
+      const nullable = (source as Schema).nullable
+      if (typeof nullable !== 'boolean' || node.type == null) invalid(`${path}/nullable`, 'malformed')
+      const kinds = Array.isArray(node.type) ? node.type : [node.type!]
+      if (nullable) node.type = [...new Set([...kinds, 'null' as const])]
+      else if (kinds.includes('null')) invalid(`${path}/nullable`, 'malformed')
+    }
+    return node
+  }
+  const schema = prepare(fieldsSchema, '#')
+  let lookup: Record<string, Schema | boolean>
+  try { lookup = dereference(schema) }
+  catch { return invalid('#', 'invalid-reference') }
+  for (const [node, path] of nodes) {
+    if (node.$ref != null && lookup[node.__absolute_ref__!] === undefined) invalid(`${path}/$ref`, 'missing-reference')
+  }
+  const complete = new Set<Schema>()
+  const visiting = new Set<Schema>()
+  const checkReferences = (node: Schema | boolean): void => {
+    if (typeof node === 'boolean' || complete.has(node)) return
+    if (visiting.has(node)) invalid(nodes.get(node) ?? '#', 'cyclic-reference')
+    visiting.add(node)
+    if (node.$ref != null) checkReferences(lookup[node.__absolute_ref__!]!)
+    // These evaluate the same instance; properties/items make productive recursive schemas.
+    for (const key of ['allOf', 'anyOf', 'oneOf']) (node[key] as Array<Schema | boolean> | undefined)?.forEach(checkReferences)
+    for (const key of ['not', 'if', 'then', 'else']) if (node[key] != null) checkReferences(node[key])
+    for (const child of Object.values(node.dependencies ?? {})) if (!Array.isArray(child)) checkReferences(child)
+    visiting.delete(node)
+    complete.add(node)
+  }
+  nodes.forEach((_path, node) => checkReferences(node))
+
+  const fieldError = (error: OutputUnit): PlanningFieldError => {
+    const parts = error.instanceLocation.slice(1).replace(/^\//, '').split('/').filter(Boolean)
+      .map(part => part.replaceAll('~1', '/').replaceAll('~0', '~'))
+    if (error.keyword === 'required' && error.error.startsWith(REQUIRED_ERROR_PREFIX) && error.error.endsWith(REQUIRED_ERROR_SUFFIX)) {
+      parts.push(error.error.slice(REQUIRED_ERROR_PREFIX.length, -REQUIRED_ERROR_SUFFIX.length))
+    }
+    return { path: parts.join('.').slice(0, MAX_FIELD_ERROR_PATH), keyword: error.keyword,
+      schemaPath: error.keywordLocation.slice(0, MAX_FIELD_ERROR_PATH),
+      message: FIELD_ERROR_MESSAGES[error.keyword] ?? 'The field does not match its definition' }
+  }
+  const jsonErrors = (value: unknown, path: string, active: Set<object>): PlanningFieldError[] => {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean'
+      || (typeof value === 'number' && Number.isFinite(value))) return []
+    if (typeof value !== 'object' || active.has(value)) return [{ path, keyword: 'json', schemaPath: '#', message: 'Use a JSON value' }]
+    const plain = Array.isArray(value) || Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null
+    if (!plain) return [{ path, keyword: 'json', schemaPath: '#', message: 'Use a JSON value' }]
+    active.add(value)
+    const errors = Object.entries(value).flatMap(([key, child]) => [
+      ...(!Array.isArray(value) && (key.includes('.') || key.includes('$'))
+        ? [{ path: [path, key].filter(Boolean).join('.'), keyword: 'field-key', schemaPath: '#', message: 'This field name is not allowed' }] : []),
+      ...jsonErrors(child, [path, key].filter(Boolean).join('.'), active),
+    ])
+    active.delete(value)
+    return errors
+  }
+  const validateFields = (fields: Record<string, unknown>): PlanningFieldValidation => {
+    const unsafe = jsonErrors(fields, '', new Set())
+    if (unsafe.length > 0) return { valid: false, errors: unsafe.slice(0, MAX_FIELD_ERRORS)
+      .map(error => ({ ...error, path: error.path.slice(0, MAX_FIELD_ERROR_PATH) })) }
+    // Only the guarded Draft 7 vocabulary reaches this engine. This mode, unlike its '7' mode,
+    // also enforces sibling keywords beside $ref, as the native planning AJV does.
+    const result = interpret(fields, schema, '2019-09', lookup, false)
+    const errors = result.errors.filter(error => !FIELD_ERROR_WRAPPERS.has(error.keyword))
+    return { valid: result.valid, errors: (errors.length > 0 ? errors : result.errors).slice(0, MAX_FIELD_ERRORS).map(fieldError) }
+  }
+  return { validateFields }
+}

package/tests/app.spec.ts

@@ -0,0 +1,72 @@
+import { describe, expect, test } from 'bun:test'
+import { appSchemaHelper, FieldsInvalid, SchemaInvalid, TransitionAction, WorkcardKind } from '@owlmeans/planning'
+import type { PlanningAppDeclarations, PlanningService, WorkcardTypeSchema } from '@owlmeans/planning'
+import { makePlanningFieldValidator } from '../src/index.js'
+import { makeSuite, STORY, STORY_FLOW } from './context.js'
+import type { Suite } from './context.js'
+
+/** A choir: every type says what it is for, every card may carry a part. */
+const APP: PlanningAppDeclarations = {
+  type: { properties: { description: { type: 'string' } } },
+  card: { properties: { part: { type: 'string', enum: ['soprano', 'alto', 'tenor', 'bass'] } } },
+}
+/** What a service serves: the declarations merged (normalized with `type: 'object'`). */
+const SERVED = appSchemaHelper.merge([APP])
+
+const SECTIONAL: WorkcardTypeSchema = {
+  type: 'test:sectional', kind: WorkcardKind.Card, version: 1, flows: [STORY_FLOW], specifications: [],
+  fields: { type: 'object', additionalProperties: false },
+}
+
+const declared = async (opts: Parameters<typeof makeSuite>[0] = {}): Promise<Suite> => {
+  const suite = await makeSuite(opts)
+  ;(suite.server as unknown as { planning: () => PlanningService }).planning().use({ name: 'choir', schemas: { app: APP } })
+
+  return suite
+}
+
+describe('@owlmeans/client-planning — application declarations', () => {
+  test('the served bundle carries them: the registry validates base fields, a form validator takes the same schema', async () => {
+    const suite = await declared()
+    const registry = await suite.client.planning().loadSchemas()
+
+    expect(registry.app()).toEqual(SERVED!)
+    expect(registry.validator(STORY)({ area: 'stage', part: 'alto' })).toBe(true)
+    expect(registry.validator(STORY)({ area: 'stage', part: 'drums' })).toBe(false)
+    const form = makePlanningFieldValidator(registry.fieldsSchema(STORY))
+    expect(form.validateFields({ area: 'stage', part: 'alto' }).valid).toBe(true)
+    expect(form.validateFields({ area: 'stage', part: 'drums' }).valid).toBe(false)
+    expect(form.validateFields({ area: 'stage', colour: 'red' }).valid).toBe(false)
+
+    const project = await suite.project('Spring concert')
+    await expect(suite.planning.execute({
+      card: { kind: WorkcardKind.Card, type: STORY, parent: project.id!, title: 'Warm-up', fields: { part: 'drums' } },
+      action: TransitionAction.Create,
+    }, { wait: true })).rejects.toBeInstanceOf(FieldsInvalid)
+  })
+
+  test('a schemas-only client plugin merges over the served declarations; a malformed one is refused', async () => {
+    const suite = await declared()
+    const service = suite.client.planning()
+    await service.loadSchemas()
+
+    service.use({ name: 'stage', schemas: { app: { card: { properties: { row: { type: 'number' } } } } } })
+    expect(Object.keys(service.schemas.app()?.card?.properties ?? {})).toEqual(['part', 'row'])
+    expect(() => service.use({ name: 'broken', schemas: { app: { card: { properties: { 'a.b': {} } } } } })).toThrow(SchemaInvalid)
+    expect(service.plugins().map(plugin => plugin.name)).toEqual(['stage'])
+    service.use({ name: 'stage' })
+    expect(Object.keys(service.schemas.app()?.card?.properties ?? {})).toEqual(['part'])
+  })
+
+  test('definitions carry a type\'s app bag over the wire; a refused bag crosses as SchemaInvalid', async () => {
+    const suite = await declared({ definitions: true })
+    const definitions = suite.planning.definitions!
+
+    await definitions.define({ types: [{ ...SECTIONAL, app: { description: 'Small groups' } }] })
+    const layer = await definitions.registry()
+    expect((layer.type(SECTIONAL.type) as WorkcardTypeSchema).app).toEqual({ description: 'Small groups' })
+    expect(layer.app()).toEqual(SERVED!)
+    expect(layer.validator(SECTIONAL.type)({ part: 'tenor' })).toBe(true)
+    await expect(definitions.putType({ ...SECTIONAL, version: 2, app: { conductor: 'me' } })).rejects.toBeInstanceOf(SchemaInvalid)
+  })
+})