@owlmeans/planning 0.1.18-rc.2 → 0.1.18-rc.21

package/src/helpers/scoped.ts

@@ -0,0 +1,257 @@
+import { memoHelper } from '@owlmeans/context'
+import { PlanningSchemaKind, SchemaOrigin, WorkcardKind } from '../consts.js'
+import { PlanningUnsupported, SchemaInvalid, SchemaSealed } from '../errors.js'
+import { makeSchemaRegistry } from '../registry.js'
+import { StatusFlowSchemaSchema, WorkcardTypeSchemaSchema } from '../schemas.js'
+import type {
+  AnyTypeSchema, PlanningSchemaBundle, PlanningSchemaRegistry, SchemaScope, ScopedSchemaBundle,
+  ScopedSchemaRecord, ScopedSchemaRegistry, StatusFlowSchema, WorkcardTypeSchema,
+} from '../types.js'
+import type { ScopedSchemaHelper } from './scoped/types.js'
+import type { Candidate, Resolved } from './types.local.js'
+import { makeAjv, validateHelper } from './validate.js'
+
+const messageOf = (error: unknown): string => error instanceof Error ? error.message : `${error}`
+
+export const createScopedSchemaHelper = (): ScopedSchemaHelper => {
+  const checkers = memoHelper.once(() => {
+    const ajv = makeAjv()
+    return { flow: ajv.compile(StatusFlowSchemaSchema), type: ajv.compile(WorkcardTypeSchemaSchema) }
+  })
+
+  const schemaRecordKey = (record: Pick<ScopedSchemaRecord, 'entityId' | 'project' | 'kind' | 'key'>): string =>
+    `${record.entityId}\u0000${record.project ?? ''}\u0000${record.kind}\u0000${record.key}`
+
+  const schemaKeyOf = (kind: PlanningSchemaKind, definition: WorkcardTypeSchema | StatusFlowSchema): string =>
+    kind === PlanningSchemaKind.Type ? (definition as WorkcardTypeSchema).type : (definition as StatusFlowSchema).id
+
+  const openType = (type: AnyTypeSchema): boolean => type.kind === WorkcardKind.Card && type.overridable === true
+
+  const assertOverridable = (
+    code: Pick<PlanningSchemaRegistry, 'has' | 'type' | 'flows'>, kind: PlanningSchemaKind, key: string
+  ): void => {
+    if (kind === PlanningSchemaKind.Type) {
+      if (code.has(key) && !openType(code.type(key))) {
+        throw new SchemaSealed(`type:${key}`)
+      }
+      return
+    }
+    const flow = code.flows().find(entry => entry.id === key)
+    if (flow != null && flow.overridable !== true) {
+      throw new SchemaSealed(`flow:${key}`)
+    }
+  }
+
+  const assertFlowSchema = (flow: StatusFlowSchema): void => {
+    const validate = checkers().flow
+    if (!validate(flow)) {
+      throw new SchemaInvalid(`flow:${(flow as Partial<StatusFlowSchema>)?.id ?? ''}:${validateHelper.ajvErrorText(validate.errors)}`)
+    }
+    const keys = new Set<string>()
+    for (const status of flow.statuses) {
+      if (keys.has(status.key)) {
+        throw new SchemaInvalid(`flow:${flow.id}:status-repeated:${status.key}`)
+      }
+      keys.add(status.key)
+    }
+    for (const rule of flow.transitions) {
+      if (!keys.has(rule.to)) {
+        throw new SchemaInvalid(`flow:${flow.id}:${rule.name}:to:${rule.to}`)
+      }
+      if (typeof rule.from === 'string') {
+        if (rule.from !== '*') {
+          throw new SchemaInvalid(`flow:${flow.id}:${rule.name}:from:${rule.from}`)
+        }
+        continue
+      }
+      const unknown = rule.from.find(status => !keys.has(status))
+      if (unknown != null) {
+        throw new SchemaInvalid(`flow:${flow.id}:${rule.name}:from:${unknown}`)
+      }
+    }
+  }
+
+  const assertTypeSchema = (
+    type: WorkcardTypeSchema, flows: Pick<PlanningSchemaRegistry, 'flow'>
+  ): void => {
+    const validate = checkers().type
+    if (!validate(type)) {
+      throw new SchemaInvalid(`type:${(type as Partial<WorkcardTypeSchema>)?.type ?? ''}:${validateHelper.ajvErrorText(validate.errors)}`)
+    }
+    if (type.kind !== WorkcardKind.Card) {
+      throw new SchemaInvalid(`type:${type.type}:kind:${type.kind}`)
+    }
+    try {
+      makeAjv().compile(type.fields)
+    } catch (error) {
+      throw new SchemaInvalid(`type:${type.type}:fields:${messageOf(error)}`)
+    }
+    const seen = new Set<string>()
+    for (const id of type.flows) {
+      if (seen.has(id)) {
+        throw new SchemaInvalid(`type:${type.type}:flow-repeated:${id}`)
+      }
+      seen.add(id)
+      try {
+        flows.flow(id)
+      } catch {
+        throw new SchemaInvalid(`type:${type.type}:flow:${id}`)
+      }
+    }
+  }
+
+  const resolveKind = <T extends WorkcardTypeSchema | StatusFlowSchema | AnyTypeSchema>(
+    kind: PlanningSchemaKind,
+    code: readonly T[],
+    keyOf: (definition: T) => string,
+    open: (definition: T) => boolean,
+    valid: (definition: T) => boolean,
+    layers: { entity: readonly ScopedSchemaRecord[], project: readonly ScopedSchemaRecord[] },
+  ): Resolved<T> => {
+    const coded = new Map(code.map(definition => [keyOf(definition), definition]))
+    const byKey = (records: readonly ScopedSchemaRecord[]) => new Map(records
+      .filter(record => record.kind === kind)
+      .map(record => [record.key, record] as const)
+      .filter(([key, record]) => {
+        const definition = record.definition as T
+        return valid(definition) && keyOf(definition) === key
+      }))
+    const entity = byKey(layers.entity)
+    const project = byKey(layers.project)
+    const added = [...new Set([...entity.keys(), ...project.keys()])].filter(key => !coded.has(key)).sort()
+
+    const stamped = (record: ScopedSchemaRecord): T => ({ ...(record.definition as T), version: record.version })
+    const result: Resolved<T> = { definitions: [], origins: {}, retired: [] }
+    for (const key of [...coded.keys(), ...added]) {
+      const declared = coded.get(key)
+      const candidates: Candidate<T>[] = []
+      if (declared == null || open(declared)) {
+        const own = project.get(key)
+        if (own != null) {
+          candidates.push({ origin: SchemaOrigin.Project, definition: stamped(own), retired: own.retired === true })
+        }
+        const shared = entity.get(key)
+        if (shared != null) {
+          candidates.push({ origin: SchemaOrigin.Entity, definition: stamped(shared), retired: shared.retired === true })
+        }
+      }
+      if (declared != null) {
+        candidates.push({ origin: SchemaOrigin.Code, definition: declared, retired: false })
+      }
+      // A retired record gives way to a live declaration below it; only when every layer holding the
+      // key retired it does the key resolve retired — still there for the cards that use it.
+      const chosen = candidates.find(candidate => !candidate.retired) ?? candidates[0]
+      if (chosen == null) {
+        continue
+      }
+      result.definitions.push(chosen.definition)
+      result.origins[key] = chosen.origin
+      if (chosen.retired) {
+        result.retired.push(key)
+      }
+    }
+
+    return result
+  }
+
+  const resolveScopedBundle = (
+    code: PlanningSchemaBundle, records: readonly ScopedSchemaRecord[], scope: SchemaScope & { revision?: number }
+  ): ScopedSchemaBundle => {
+    const mine = records.filter(record => record.entityId === scope.entityId)
+    const layers = {
+      entity: mine.filter(record => record.project == null),
+      project: scope.project == null ? [] : mine.filter(record => record.project === scope.project),
+    }
+    const types = resolveKind<AnyTypeSchema>(
+      PlanningSchemaKind.Type, code.types, type => type.type, openType,
+      type => type != null && typeof type.type === 'string' && type.kind === WorkcardKind.Card, layers,
+    )
+    const flows = resolveKind<StatusFlowSchema>(
+      PlanningSchemaKind.Flow, code.flows, flow => flow.id, flow => flow.overridable === true,
+      flow => flow != null && typeof flow.id === 'string', layers,
+    )
+
+    return structuredClone({
+      version: code.version,
+      types: types.definitions,
+      flows: flows.definitions,
+      scope: scope.project == null ? { entityId: scope.entityId } : { entityId: scope.entityId, project: scope.project },
+      revision: scope.revision ?? 0,
+      origins: { types: types.origins, flows: flows.origins },
+      retired: { types: types.retired, flows: flows.retired },
+    })
+  }
+
+  const scopedRegistryOf = (bundle: ScopedSchemaBundle): ScopedSchemaRegistry => {
+    const base = makeSchemaRegistry(bundle)
+    const kept = structuredClone(bundle)
+    const refuse = (): never => {
+      throw new PlanningUnsupported('schemas:read-only')
+    }
+    const originsOf = (kind: PlanningSchemaKind) =>
+      kind === PlanningSchemaKind.Type ? kept.origins?.types : kept.origins?.flows
+    const retiredOf = (kind: PlanningSchemaKind) =>
+      kind === PlanningSchemaKind.Type ? kept.retired?.types : kept.retired?.flows
+
+    return {
+      ...base,
+      registerType: refuse,
+      registerFlow: refuse,
+      load: refuse,
+      scope: kept.scope ?? { entityId: '' },
+      revision: kept.revision ?? 0,
+      originOf: (kind, key) => originsOf(kind)?.[key]
+        ?? ((kind === PlanningSchemaKind.Type ? base.has(key) : base.flows().some(flow => flow.id === key))
+          ? SchemaOrigin.Code
+          : undefined),
+      isRetired: (kind, key) => retiredOf(kind)?.includes(key) === true,
+      bundle: () => structuredClone(kept),
+    }
+  }
+
+  const flowInUse = (bundle: ScopedSchemaBundle, flow: string): string | undefined => {
+    if (bundle.retired?.flows.includes(flow) !== true) {
+      return undefined
+    }
+
+    return bundle.types.find(type => bundle.retired?.types.includes(type.type) !== true && type.flows.includes(flow))?.type
+  }
+
+  return {
+    schemaRecordKey, schemaKeyOf, assertOverridable, assertFlowSchema, assertTypeSchema, resolveScopedBundle,
+    scopedRegistryOf, flowInUse,
+  }
+}
+
+export const scopedSchemaHelper = createScopedSchemaHelper()
+
+/** @deprecated compat:factory-refactor — use `scopedSchemaHelper.schemaRecordKey(…)` */
+export const schemaRecordKey = (record: Pick<ScopedSchemaRecord, 'entityId' | 'project' | 'kind' | 'key'>): string =>
+  scopedSchemaHelper.schemaRecordKey(record)
+
+/** @deprecated compat:factory-refactor — use `scopedSchemaHelper.schemaKeyOf(…)` */
+export const schemaKeyOf = (kind: PlanningSchemaKind, definition: WorkcardTypeSchema | StatusFlowSchema): string =>
+  scopedSchemaHelper.schemaKeyOf(kind, definition)
+
+/** @deprecated compat:factory-refactor — use `scopedSchemaHelper.assertOverridable(…)` */
+export const assertOverridable = (
+  code: Pick<PlanningSchemaRegistry, 'has' | 'type' | 'flows'>, kind: PlanningSchemaKind, key: string
+): void => scopedSchemaHelper.assertOverridable(code, kind, key)
+
+/** @deprecated compat:factory-refactor — use `scopedSchemaHelper.assertFlowSchema(…)` */
+export const assertFlowSchema = (flow: StatusFlowSchema): void => scopedSchemaHelper.assertFlowSchema(flow)
+
+/** @deprecated compat:factory-refactor — use `scopedSchemaHelper.assertTypeSchema(…)` */
+export const assertTypeSchema = (type: WorkcardTypeSchema, flows: Pick<PlanningSchemaRegistry, 'flow'>): void =>
+  scopedSchemaHelper.assertTypeSchema(type, flows)
+
+/** @deprecated compat:factory-refactor — use `scopedSchemaHelper.resolveScopedBundle(…)` */
+export const resolveScopedBundle = (
+  code: PlanningSchemaBundle, records: readonly ScopedSchemaRecord[], scope: SchemaScope & { revision?: number }
+): ScopedSchemaBundle => scopedSchemaHelper.resolveScopedBundle(code, records, scope)
+
+/** @deprecated compat:factory-refactor — use `scopedSchemaHelper.scopedRegistryOf(…)` */
+export const scopedRegistryOf = (bundle: ScopedSchemaBundle): ScopedSchemaRegistry => scopedSchemaHelper.scopedRegistryOf(bundle)
+
+/** @deprecated compat:factory-refactor — use `scopedSchemaHelper.flowInUse(…)` */
+export const flowInUse = (bundle: ScopedSchemaBundle, flow: string): string | undefined => scopedSchemaHelper.flowInUse(bundle, flow)

package/src/helpers/specification/types.ts

@@ -0,0 +1,26 @@
+import type { AnyTypeSchema, PlanningSchemaRegistry, Specification, SpecificationSlot, Workcard } from '../../types.js'
+
+/** The slot and revision rules of the documents a parent card carries. */
+export interface SpecificationHelper {
+  /** The slot a parent type declares for a category. */
+  slotOf: (type: AnyTypeSchema, category: string) => SpecificationSlot | undefined
+  isRevisioned: (slot?: SpecificationSlot | null) => boolean
+  bodyCharsOf: (body?: string | null) => number | undefined
+  /** The revision a write lands as: 1 for a new document, current + 1 after, none when unrevisioned. */
+  nextRevision: (current: Pick<Specification, 'revision'> | null | undefined, slot?: SpecificationSlot | null) => number | undefined
+  /**
+   * The current document of a category among a parent's specifications: the highest revision, then
+   * the most recently updated. `null` when the category has none.
+   */
+  currentSpecification: (specs: Workcard[], category: string) => Specification | null
+  /**
+   * The specification type a new document of a slot is created with: the slot's own `type`, else
+   * the only registered specification type, else the one sharing the parent type's prefix
+   * (`viable:project` → `viable:spec`).
+   *
+   * @throws {UnknownWorkcardType} when none or several candidates remain
+   */
+  specificationTypeOf: (
+    registry: Pick<PlanningSchemaRegistry, 'types'>, parentType: string, slot?: SpecificationSlot | null
+  ) => string
+}

package/src/helpers/specification.ts

@@ -3,63 +3,81 @@ import { UnknownWorkcardType } from '../errors.js'
 import type {
   AnyTypeSchema, PlanningSchemaRegistry, Specification, SpecificationSlot, Workcard,
 } from '../types.js'
+import type { SpecificationHelper } from './specification/types.js'
 
-/** The slot a parent type declares for a category. */
-export const slotOf = (type: AnyTypeSchema, category: string): SpecificationSlot | undefined =>
-  type.specifications.find(slot => slot.category === category)
+export const createSpecificationHelper = (): SpecificationHelper => {
+  const slotOf = (type: AnyTypeSchema, category: string): SpecificationSlot | undefined =>
+    type.specifications.find(slot => slot.category === category)
 
-export const isRevisioned = (slot?: SpecificationSlot | null): boolean => slot?.revisioned === true
+  const isRevisioned = (slot?: SpecificationSlot | null): boolean => slot?.revisioned === true
 
-export const bodyCharsOf = (body?: string | null): number | undefined => body == null ? undefined : body.length
+  const bodyCharsOf = (body?: string | null): number | undefined => body == null ? undefined : body.length
 
-/** The revision a write lands as: 1 for a new document, current + 1 after, none when unrevisioned. */
-export const nextRevision = (
-  current: Pick<Specification, 'revision'> | null | undefined, slot?: SpecificationSlot | null
-): number | undefined => isRevisioned(slot) ? (current?.revision ?? 0) + 1 : undefined
-
-/**
- * The current document of a category among a parent's specifications: the highest revision, then
- * the most recently updated. `null` when the category has none.
- */
-export const currentSpecification = (
-  specs: Workcard[], category: string
-): Specification | null => specs
-  .filter((spec): spec is Specification => spec.kind === WorkcardKind.Specification
-    && (spec as Specification).category === category)
-  .reduce<Specification | null>((best, spec) => {
-    if (best == null) {
-      return spec
+  const nextRevision = (
+    current: Pick<Specification, 'revision'> | null | undefined, slot?: SpecificationSlot | null
+  ): number | undefined => isRevisioned(slot) ? (current?.revision ?? 0) + 1 : undefined
+
+  const currentSpecification = (
+    specs: Workcard[], category: string
+  ): Specification | null => specs
+    .filter((spec): spec is Specification => spec.kind === WorkcardKind.Specification
+      && (spec as Specification).category === category)
+    .reduce<Specification | null>((best, spec) => {
+      if (best == null) {
+        return spec
+      }
+      const byRevision = (spec.revision ?? 0) - (best.revision ?? 0)
+      if (byRevision !== 0) {
+        return byRevision > 0 ? spec : best
+      }
+      return (spec.updatedAt ?? spec.createdAt) > (best.updatedAt ?? best.createdAt) ? spec : best
+    }, null)
+
+  const prefixOf = (type: string): string => type.includes(':') ? type.slice(0, type.lastIndexOf(':')) : ''
+
+  const specificationTypeOf = (
+    registry: Pick<PlanningSchemaRegistry, 'types'>, parentType: string, slot?: SpecificationSlot | null
+  ): string => {
+    if (slot?.type != null) {
+      return slot.type
     }
-    const byRevision = (spec.revision ?? 0) - (best.revision ?? 0)
-    if (byRevision !== 0) {
-      return byRevision > 0 ? spec : best
+    const candidates = registry.types().filter(type => type.kind === WorkcardKind.Specification)
+    if (candidates.length === 1) {
+      return candidates[0].type
     }
-    return (spec.updatedAt ?? spec.createdAt) > (best.updatedAt ?? best.createdAt) ? spec : best
-  }, null)
-
-const prefixOf = (type: string): string => type.includes(':') ? type.slice(0, type.lastIndexOf(':')) : ''
-
-/**
- * The specification type a new document of a slot is created with: the slot's own `type`, else
- * the only registered specification type, else the one sharing the parent type's prefix
- * (`viable:project` → `viable:spec`).
- *
- * @throws {UnknownWorkcardType} when none or several candidates remain
- */
-export const specificationTypeOf = (
-  registry: Pick<PlanningSchemaRegistry, 'types'>, parentType: string, slot?: SpecificationSlot | null
-): string => {
-  if (slot?.type != null) {
-    return slot.type
-  }
-  const candidates = registry.types().filter(type => type.kind === WorkcardKind.Specification)
-  if (candidates.length === 1) {
-    return candidates[0].type
-  }
-  const prefixed = candidates.filter(type => prefixOf(type.type) === prefixOf(parentType))
-  if (prefixed.length === 1) {
-    return prefixed[0].type
+    const prefixed = candidates.filter(type => prefixOf(type.type) === prefixOf(parentType))
+    if (prefixed.length === 1) {
+      return prefixed[0].type
+    }
+
+    throw new UnknownWorkcardType(`specification:${parentType}:${slot?.category ?? ''}`)
   }
 
-  throw new UnknownWorkcardType(`specification:${parentType}:${slot?.category ?? ''}`)
+  return { slotOf, isRevisioned, bodyCharsOf, nextRevision, currentSpecification, specificationTypeOf }
 }
+
+export const specificationHelper = createSpecificationHelper()
+
+/** @deprecated compat:factory-refactor — use `specificationHelper.slotOf(…)` */
+export const slotOf = (type: AnyTypeSchema, category: string): SpecificationSlot | undefined =>
+  specificationHelper.slotOf(type, category)
+
+/** @deprecated compat:factory-refactor — use `specificationHelper.isRevisioned(…)` */
+export const isRevisioned = (slot?: SpecificationSlot | null): boolean => specificationHelper.isRevisioned(slot)
+
+/** @deprecated compat:factory-refactor — use `specificationHelper.bodyCharsOf(…)` */
+export const bodyCharsOf = (body?: string | null): number | undefined => specificationHelper.bodyCharsOf(body)
+
+/** @deprecated compat:factory-refactor — use `specificationHelper.nextRevision(…)` */
+export const nextRevision = (
+  current: Pick<Specification, 'revision'> | null | undefined, slot?: SpecificationSlot | null
+): number | undefined => specificationHelper.nextRevision(current, slot)
+
+/** @deprecated compat:factory-refactor — use `specificationHelper.currentSpecification(…)` */
+export const currentSpecification = (specs: Workcard[], category: string): Specification | null =>
+  specificationHelper.currentSpecification(specs, category)
+
+/** @deprecated compat:factory-refactor — use `specificationHelper.specificationTypeOf(…)` */
+export const specificationTypeOf = (
+  registry: Pick<PlanningSchemaRegistry, 'types'>, parentType: string, slot?: SpecificationSlot | null
+): string => specificationHelper.specificationTypeOf(registry, parentType, slot)

package/src/helpers/status/types.ts

@@ -0,0 +1,46 @@
+import type { IntrinsicStatus } from '../../consts.js'
+import type { AnyTypeSchema, StatusDefinition, StatusFlowSchema, StatusTransitionRule } from '../../types.js'
+import type { FlowLookup } from '../types.local.js'
+
+/** The status-flow rules: statuses, the transitions a flow offers, and the intrinsic state. */
+export interface StatusHelper {
+  /** The primary flow id of a type — `flows[0]`. @throws {UnknownStatusFlow} when it declares none */
+  primaryFlowOf: (type: AnyTypeSchema) => string
+  flowIdsOf: (type: AnyTypeSchema) => string[]
+  statusDefinitionOf: (flow: StatusFlowSchema, status: string) => StatusDefinition | undefined
+  /** The intrinsic state a status maps onto, or `undefined` for a status the flow does not declare. */
+  intrinsicOf: (flow: StatusFlowSchema, status: string) => IntrinsicStatus | undefined
+  /** The status marked `initial`, else the first one. @throws {PlanningError} for a flow with none */
+  initialStatusOf: (flow: StatusFlowSchema) => string
+  isTerminal: (flow: StatusFlowSchema, status: string) => boolean
+  /**
+   * The rule a named transition follows from a status.
+   *
+   * A name may be declared several times with different `from` sets; the rule naming the status
+   * explicitly wins, and a `'*'` rule of that name answers only when none does. A status the flow
+   * does NOT declare — a card whose flow changed under it — matches every rule of the name, the first
+   * declared answering: such a card can always move back onto the flow it now runs.
+   */
+  ruleOf: (flow: StatusFlowSchema, transition: string, from: string) => StatusTransitionRule | undefined
+  canTransit: (flow: StatusFlowSchema, transition: string, from: string) => boolean
+  /**
+   * Every transition available from a status, one rule per name (the one `ruleOf` would pick), in
+   * declaration order. `explicit: true` keeps only the rules offered to a person.
+   */
+  transitionsFrom: (flow: StatusFlowSchema, status: string, opts?: { explicit?: boolean }) => StatusTransitionRule[]
+  /**
+   * A new card's status per flow: every flow's initial status, with the primary one overridden by
+   * `status` when the draft names one.
+   *
+   * @throws {UnknownStatusFlow}
+   */
+  initialFlowsOf: (type: AnyTypeSchema, registry: FlowLookup, status?: string) => Record<string, string>
+  /**
+   * The card's intrinsic state over its flows. {@link IntrinsicPolicy.Primary} reads the primary
+   * flow; {@link IntrinsicPolicy.All} takes the least advanced flow. A status the flow does not
+   * declare reads as planned.
+   *
+   * @throws {UnknownStatusFlow}
+   */
+  resolveIntrinsic: (type: AnyTypeSchema, flows: Record<string, string>, registry: FlowLookup) => IntrinsicStatus
+}