@owlmeans/planning 0.1.18-rc.8 → 0.1.18

package/src/errors.ts

@@ -206,6 +206,72 @@ export class PlanningScopeMismatch extends PlanningError {
   }
 }
 
+/**
+ * A data-defined schema write lost its compare-and-set: the layer's record is not at the version
+ * the write replaces. Re-read the layer and retry.
+ */
+export class SchemaConflict extends PlanningError {
+  public static override typeName: string = `${PlanningError.typeName}SchemaConflict`
+  /** The stored record moved past the expected version: answered 409. */
+  public static httpStatus = 409
+
+  constructor(message: string = 'error') {
+    super(`schema-conflict:${message}`)
+    this.type = SchemaConflict.typeName
+  }
+}
+
+/** A flow cannot be retired while a live type of an affected layer still resolves it. */
+export class SchemaInUse extends PlanningError {
+  public static override typeName: string = `${PlanningError.typeName}SchemaInUse`
+  /** Other declarations still depend on the key: answered 409. */
+  public static httpStatus = 409
+
+  constructor(message: string = 'error') {
+    super(`schema-in-use:${message}`)
+    this.type = SchemaInUse.typeName
+  }
+}
+
+/**
+ * The key is registered in code and does not declare itself `overridable` — or it is a project
+ * or specification type, which only code declares.
+ */
+export class SchemaSealed extends PlanningError {
+  public static override typeName: string = `${PlanningError.typeName}SchemaSealed`
+  /** The key cannot be declared as data: answered 422. */
+  public static httpStatus = 422
+
+  constructor(message: string = 'error') {
+    super(`schema-sealed:${message}`)
+    this.type = SchemaSealed.typeName
+  }
+}
+
+/** A data-defined declaration fails its closed-form checks. */
+export class SchemaInvalid extends PlanningError {
+  public static override typeName: string = `${PlanningError.typeName}SchemaInvalid`
+  /** The declaration's content is refused: answered 422. */
+  public static httpStatus = 422
+
+  constructor(message: string = 'error') {
+    super(`schema-invalid:${message}`)
+    this.type = SchemaInvalid.typeName
+  }
+}
+
+/** The request's access does not grant the write (creating or deleting a project, defining schemas). */
+export class PlanningForbidden extends PlanningError {
+  public static override typeName: string = `${PlanningError.typeName}Forbidden`
+  /** The caller lacks the grant the write needs: answered 403. */
+  public static httpStatus = 403
+
+  constructor(message: string = 'error') {
+    super(`forbidden:${message}`)
+    this.type = PlanningForbidden.typeName
+  }
+}
+
 /** The store behind this type cannot do what was asked (a foreign provider without a log). */
 export class PlanningUnsupported extends PlanningError {
   public static override typeName: string = `${PlanningError.typeName}Unsupported`
@@ -234,4 +300,9 @@ ResilientError.registerErrorClass(WorkcardConflict)
 ResilientError.registerErrorClass(CommitTimeout)
 ResilientError.registerErrorClass(CommitFailed)
 ResilientError.registerErrorClass(PlanningScopeMismatch)
+ResilientError.registerErrorClass(SchemaConflict)
+ResilientError.registerErrorClass(SchemaInUse)
+ResilientError.registerErrorClass(SchemaSealed)
+ResilientError.registerErrorClass(SchemaInvalid)
+ResilientError.registerErrorClass(PlanningForbidden)
 ResilientError.registerErrorClass(PlanningUnsupported)

package/src/helpers/app/consts.local.ts

@@ -0,0 +1,5 @@
+/** The kinds an application declares properties for, in merge order. */
+export const APP_KINDS = ['type', 'flow', 'card'] as const
+
+/** The only keywords a kind's declaration may carry — a merge by name honours nothing else. */
+export const APP_SCHEMA_KEYS = new Set(['type', 'properties', 'required'])

package/src/helpers/app/types.ts

@@ -0,0 +1,54 @@
+import type { AnySchema } from 'ajv'
+import type { PlanningSchemaKind } from '../../consts.js'
+import type { AnyTypeSchema, PlanningAppDeclarations } from '../../types.js'
+
+/** The declarations whose properties a definition carries in its `app` bag. */
+export type PlanningAppBagKind = PlanningSchemaKind.Type | PlanningSchemaKind.Flow
+
+/**
+ * The application's pregenerated planning properties: the `app` bag of every type and flow
+ * declaration, and the base `fields` of every card — declared in code, beside the custom fields a
+ * data-defined type gives its cards.
+ */
+export interface AppSchemaHelper {
+  /**
+   * Merge declarations in the order given — a planning service passes its own `schemas.app` first,
+   * then every plugin's in plugin order (`order` ascending, registration order among equals). Per
+   * kind (`type`, `flow`, `card`): `properties` are united, a later declaration of a name replacing
+   * the earlier one whole; `required` is the union. `undefined` when no source declares anything.
+   *
+   * @throws {SchemaInvalid} a malformed source
+   */
+  merge: (sources: ReadonlyArray<PlanningAppDeclarations | undefined>) => PlanningAppDeclarations | undefined
+  /**
+   * The closed form of declarations: per kind only `type` (`'object'`), `properties` (names without
+   * `.` or `$`) and `required` (each name declared), and — outside a browser document — a schema that
+   * compiles. A page never compiles: a strict `script-src` refuses code generation, and what a page
+   * registers its server compiled when it registered it.
+   *
+   * @throws {SchemaInvalid} `app:<kind>:…`
+   */
+  assertDeclarations: (app: PlanningAppDeclarations) => void
+  /**
+   * The schema a definition's `app` bag must match: the declared kind closed over its properties
+   * (`additionalProperties: false`). `undefined` when the kind is not declared.
+   */
+  bagSchemaOf: (app: PlanningAppDeclarations | undefined, kind: PlanningAppBagKind) => AnySchema | undefined
+  /**
+   * Check a declaration's `app` bag: refused when the kind is undeclared and the bag is present;
+   * matched against {@link bagSchemaOf} otherwise (an absent bag is `{}`, so a required property
+   * makes the bag mandatory).
+   *
+   * @throws {SchemaInvalid} `<kind>:<key>:app:…`
+   */
+  assertBag: (kind: PlanningAppBagKind, key: string, bag: unknown, app?: PlanningAppDeclarations) => void
+  /**
+   * The schema a type's `fields` validate against. Without base card fields, or for a project or
+   * specification type, it is the type's own `fields` object itself. Otherwise the type's schema
+   * stays the root (so its `#/…` references still resolve) and gains: each base name in its
+   * top-level `properties` as `{}` when it does not declare it (its `additionalProperties` never
+   * refuses a base field; its own declaration of the name still applies and may narrow it), and the
+   * base object schema appended to its `allOf`.
+   */
+  fieldsSchemaOf: (type: AnyTypeSchema, app?: PlanningAppDeclarations) => AnySchema
+}

package/src/helpers/app.ts

@@ -0,0 +1,158 @@
+import type { AnySchema, ValidateFunction } from 'ajv'
+import { PlanningSchemaKind, WorkcardKind } from '../consts.js'
+import { SchemaInvalid } from '../errors.js'
+import type { PlanningAppDeclarations, PlanningAppSchema } from '../types.js'
+import type { AppSchemaHelper, PlanningAppBagKind } from './app/types.js'
+import { APP_KINDS, APP_SCHEMA_KEYS } from './app/consts.local.js'
+import { makeAjv, validateHelper } from './validate.js'
+
+const messageOf = (error: unknown): string => error instanceof Error ? error.message : `${error}`
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  value != null && typeof value === 'object' && !Array.isArray(value)
+
+export const createAppSchemaHelper = (): AppSchemaHelper => {
+  // Keyed by the declared kind object a registry keeps — a fresh ajv per entry, so a replaced
+  // declaration leaves nothing compiled behind.
+  const bags = new WeakMap<PlanningAppSchema, ValidateFunction>()
+
+  // A page never compiles: under a strict `script-src` Ajv's code generation is refused, and the
+  // declarations a page registers are its server's, compiled there when they were registered.
+  const compiles = (): boolean => typeof (globalThis as { document?: unknown }).document === 'undefined'
+
+  const objectSchemaOf = (declared: PlanningAppSchema): Record<string, unknown> => ({
+    type: 'object',
+    properties: declared.properties,
+    ...((declared.required?.length ?? 0) > 0 ? { required: [...declared.required!] } : {}),
+  })
+
+  const declaredOf = (app: PlanningAppDeclarations | undefined, kind: PlanningAppBagKind): PlanningAppSchema | undefined =>
+    kind === PlanningSchemaKind.Type ? app?.type : app?.flow
+
+  const assertDeclarations: AppSchemaHelper['assertDeclarations'] = app => {
+    if (!isObject(app)) {
+      throw new SchemaInvalid('app:declarations')
+    }
+    const kinds: readonly string[] = APP_KINDS
+    const stranger = Object.keys(app).find(key => !kinds.includes(key))
+    if (stranger != null) {
+      throw new SchemaInvalid(`app:kind:${stranger}`)
+    }
+    for (const kind of APP_KINDS) {
+      const declared: unknown = app[kind]
+      if (declared == null) {
+        continue
+      }
+      if (!isObject(declared)) {
+        throw new SchemaInvalid(`app:${kind}:schema`)
+      }
+      const keyword = Object.keys(declared).find(key => !APP_SCHEMA_KEYS.has(key))
+      if (keyword != null) {
+        throw new SchemaInvalid(`app:${kind}:keyword:${keyword}`)
+      }
+      if (declared.type != null && declared.type !== 'object') {
+        throw new SchemaInvalid(`app:${kind}:type`)
+      }
+      if (!isObject(declared.properties)) {
+        throw new SchemaInvalid(`app:${kind}:properties`)
+      }
+      const names = Object.keys(declared.properties)
+      const badName = names.find(name => name === '' || name.includes('.') || name.includes('$'))
+      if (badName != null) {
+        throw new SchemaInvalid(`app:${kind}:name:${badName}`)
+      }
+      const required: unknown = declared.required
+      if (required != null && (!Array.isArray(required) || required.some(name => typeof name !== 'string'))) {
+        throw new SchemaInvalid(`app:${kind}:required`)
+      }
+      const missing = (required as string[] | undefined)?.find(name => !names.includes(name))
+      if (missing != null) {
+        throw new SchemaInvalid(`app:${kind}:required:${missing}`)
+      }
+      if (compiles()) {
+        try {
+          makeAjv().compile(objectSchemaOf(declared as unknown as PlanningAppSchema))
+        } catch (error) {
+          throw new SchemaInvalid(`app:${kind}:${messageOf(error)}`)
+        }
+      }
+    }
+  }
+
+  const merge: AppSchemaHelper['merge'] = sources => {
+    const merged: PlanningAppDeclarations = {}
+    for (const source of sources) {
+      if (source == null) {
+        continue
+      }
+      assertDeclarations(source)
+      for (const kind of APP_KINDS) {
+        const next = source[kind]
+        if (next == null) {
+          continue
+        }
+        const current = merged[kind]
+        const required = [...new Set([...(current?.required ?? []), ...(next.required ?? [])])]
+        merged[kind] = {
+          type: 'object',
+          properties: { ...current?.properties, ...structuredClone(next.properties) },
+          ...(required.length > 0 ? { required } : {}),
+        }
+      }
+    }
+
+    return Object.keys(merged).length > 0 ? merged : undefined
+  }
+
+  const bagSchemaOf: AppSchemaHelper['bagSchemaOf'] = (app, kind) => {
+    const declared = declaredOf(app, kind)
+
+    return declared == null ? undefined : { ...objectSchemaOf(declared), additionalProperties: false }
+  }
+
+  const assertBag: AppSchemaHelper['assertBag'] = (kind, key, bag, app) => {
+    const declared = declaredOf(app, kind)
+    if (declared == null) {
+      if (bag != null) {
+        throw new SchemaInvalid(`${kind}:${key}:app:undeclared`)
+      }
+      return
+    }
+    const keys = validateHelper.invalidFieldKeys(bag)
+    if (keys.length > 0) {
+      throw new SchemaInvalid(`${kind}:${key}:app:keys:${keys.join(',')}`)
+    }
+    let validate = bags.get(declared)
+    if (validate == null) {
+      validate = makeAjv().compile(bagSchemaOf(app, kind) as object)
+      bags.set(declared, validate)
+    }
+    if (!validate(bag ?? {})) {
+      throw new SchemaInvalid(`${kind}:${key}:app:${validateHelper.ajvErrorText(validate.errors)}`)
+    }
+  }
+
+  const fieldsSchemaOf: AppSchemaHelper['fieldsSchemaOf'] = (type, app) => {
+    const base = app?.card
+    const own: AnySchema = type.fields
+    if (base == null || type.kind !== WorkcardKind.Card) {
+      return own
+    }
+    const declared = objectSchemaOf(base)
+    if (!isObject(own)) {
+      return own === false ? false : declared
+    }
+    // The type's schema stays the root, so its own `#/…` references keep resolving.
+    const admitted = Object.fromEntries(Object.keys(base.properties).map(name => [name, {}]))
+
+    return {
+      ...own,
+      properties: { ...admitted, ...(isObject(own.properties) ? own.properties : {}) },
+      allOf: [...(Array.isArray(own.allOf) ? own.allOf : []), declared],
+    }
+  }
+
+  return { merge, assertDeclarations, bagSchemaOf, assertBag, fieldsSchemaOf }
+}
+
+export const appSchemaHelper = createAppSchemaHelper()

package/src/helpers/apply/consts.local.ts

@@ -0,0 +1,10 @@
+/** Never written by a transition's `changes`: the fold takes them from the transition itself. */
+export const IDENTITY_KEYS = new Set(['id', 'kind', 'type', 'entityId', 'seq', 'head', 'createdAt'])
+
+/** Cannot be cleared: a record without them is not a record. */
+export const REQUIRED_KEYS = new Set([
+  ...IDENTITY_KEYS, 'title', 'parents', 'status', 'intrinsic', 'flows', 'labels', 'fields',
+])
+
+/** Merged shallowly into the card's own map rather than replacing it. */
+export const MERGED_KEYS = new Set(['fields', 'flows'])

package/src/helpers/apply/types.ts

@@ -0,0 +1,32 @@
+import type { Relationship, Transition, Workcard } from '../../types.js'
+
+/** The pure fold — the card and its edges after one transition. */
+export interface ApplyHelper {
+  /**
+   * THE fold: the card after one transition. Pure, total, no I/O — every store (memory, Mongo, a
+   * client mirror) folds with this and nothing else, so one log always means one card.
+   *
+   * - An already-applied transition (`seq <= card.seq`) returns the card unchanged: re-folding is
+   *   safe.
+   * - Anything but the next seq (`card.seq + 1`, or 1 for a create with no card) is refused with
+   *   `PlanningError('fold:out-of-order')`.
+   * - The log is replayed as written: a transition the executor would refuse today (an update naming
+   *   `createdBy`, appended before that refusal existed) still folds. Guards live at admission.
+   * - `create` builds the whole record from `changes` plus the transition's identity; `delete`
+   *   answers `null`; `link`/`unlink` only move `seq`/`head`/`updatedAt` (the edges are
+   *   {@link ApplyHelper.applyRelationship}'s); `update`/`transit` write `changes` — `fields` and
+   *   `flows` merge, everything else replaces — and clear `unset`.
+   * - Every result has `seq = transition.seq`, `head = max(head, seq)`, `updatedAt = transition.at`.
+   *
+   * @throws {PlanningError} `planning:fold:out-of-order:…`
+   */
+  applyTransition: <T extends Workcard = Workcard>(card: T | null | undefined, transition: Transition) => T | null
+  /**
+   * The relationships after one transition. Pure and total, like {@link ApplyHelper.applyTransition}.
+   *
+   * `create` adds its `links`, `link` adds its `link`, `unlink` removes the matching edge, and a
+   * `delete` removes every edge touching the card. An edge that already exists is kept as it is, so
+   * re-folding adds nothing. Every other action answers the list unchanged. Always a new array.
+   */
+  applyRelationship: (links: Relationship[], transition: Transition) => Relationship[]
+}