@owlmeans/planning 0.1.18-rc.0

package/src/helpers/query.ts

@@ -0,0 +1,345 @@
+import type { Criteria, ListOptions, ResourceRecord, Sort } from '@owlmeans/resource'
+import { IntrinsicStatus, WorkcardKind } from '../consts.js'
+import { PlanningError } from '../errors.js'
+import type {
+  IntrinsicCounts, ListWire, PlanningScope, RelationshipQuery, RelationshipQueryWire, RelationshipWhere,
+  Specification, SpecificationQuery, SpecificationQueryWire, SummaryQuery, SummaryQueryWire, SummaryView,
+  TransitionQuery, TransitionQueryWire, TransitionWhere, Workcard, WorkcardQuery, WorkcardQueryWire,
+} from '../types.js'
+
+type Scope = Pick<PlanningScope, 'entityId'>
+
+const clean = <T extends object>(record: T): T =>
+  Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined)) as T
+
+/** `%`, `_` and `\` are wildcards/escapes to `$ilike`; a search text means them literally. */
+const escapeLike = (text: string): string => text.replace(/[\\%_]/g, char => `\\${char}`)
+
+/**
+ * `WorkcardQuery` → `Criteria<Workcard>` — the ONE translation every store answers, so a query
+ * means the same thing in memory, in Mongo and in a client mirror.
+ *
+ * `entityId` always comes from the scope (a query that forgot it would be a cross-tenant read);
+ * `undefined` values are omitted. Paging and sorting are {@link listOptionsOf}'s.
+ */
+export const criteriaOf = (query?: WorkcardQuery | null, scope?: Scope): Criteria<Workcard> => {
+  const where: Record<string, unknown> = {
+    entityId: scope?.entityId,
+    kind: query?.kind,
+    type: query?.type,
+    status: query?.status,
+    intrinsic: query?.intrinsic,
+    code: query?.code,
+    parent: query?.parent,
+    parents: query?.within != null ? { $contains: query.within } : undefined,
+    labels: query?.labels != null ? { $overlaps: query.labels } : undefined,
+    id: query?.ids != null ? { $in: query.ids } : undefined,
+    category: query?.category,
+    updatedAt: query?.updatedSince != null ? { $gte: query.updatedSince } : undefined,
+  }
+  if (query?.flow != null) {
+    where[`flows.${query.flow.id}`] = query.flow.status
+  }
+  for (const [key, value] of Object.entries(query?.fields ?? {})) {
+    if (value !== undefined) {
+      where[`fields.${key}`] = value
+    }
+  }
+  if (query?.q != null && query.q !== '') {
+    const like = `%${escapeLike(query.q)}%`
+    where.$or = [
+      { title: { $ilike: like } },
+      { description: { $ilike: like } },
+      { code: { $startsWith: query.q } },
+    ]
+  }
+
+  return clean(where) as Criteria<Workcard>
+}
+
+/** Paging and sorting out of a query. `size: 0` (no limit) survives. */
+export const listOptionsOf = <T extends ResourceRecord>(query?: ListOptions<T> | null): ListOptions<T> => clean({
+  page: query?.page,
+  size: query?.size,
+  sort: query?.sort,
+})
+
+/** The criteria over a parent's specifications. */
+export const specCriteriaOf = (
+  parent: string, query?: SpecificationQuery | null, scope?: Scope
+): Criteria<Specification> => clean({
+  entityId: scope?.entityId,
+  kind: WorkcardKind.Specification,
+  parent,
+  category: query?.category,
+}) as Criteria<Specification>
+
+export const linkWhereOf = (query: RelationshipQuery | null | undefined, scope: Scope): RelationshipWhere => clean({
+  entityId: scope.entityId,
+  from: query?.from,
+  to: query?.to,
+  type: query?.type,
+})
+
+export const transitionWhereOf = (query: TransitionQuery | null | undefined, scope: Scope): TransitionWhere => clean({
+  entityId: scope.entityId,
+  card: query?.card,
+  project: query?.project,
+  sinceSeq: query?.sinceSeq,
+  action: query?.action,
+  state: query?.state,
+})
+
+const emptyCounts = (): IntrinsicCounts => ({
+  total: 0, [IntrinsicStatus.Planned]: 0, [IntrinsicStatus.InProgress]: 0, [IntrinsicStatus.Closed]: 0,
+})
+
+/** Counts of DIRECT children (`card.parent`) per parent, by intrinsic state. No key for a parent with none. */
+export const summaryOf = (cards: Workcard[], parents: string[]): SummaryView => cards.reduce<SummaryView>(
+  (view, card) => {
+    if (card.parent == null || !parents.includes(card.parent)) {
+      return view
+    }
+    const counts = view[card.parent] ?? emptyCounts()
+    counts.total += 1
+    counts[card.intrinsic] = (counts[card.intrinsic] ?? 0) + 1
+    view[card.parent] = counts
+    return view
+  }, {}
+)
+
+// ─── Wire encoding ───────────────────────────────────────────────────────────────────────────────
+
+/** A list as one query value: comma-joined, or JSON when an element itself holds a comma. */
+export const encodeList = (value?: string | readonly string[] | null): string | undefined => {
+  if (value == null) {
+    return undefined
+  }
+  if (typeof value === 'string') {
+    return encodeList([value])
+  }
+  if (value.length === 0) {
+    return undefined
+  }
+
+  return value.some(entry => entry.includes(',') || entry.startsWith('['))
+    ? JSON.stringify(value)
+    : value.join(',')
+}
+
+/** Every entry of a list query value, whatever shape the transport left it in. */
+export const decodeList = (value: unknown, key: string = 'list'): string[] | undefined => {
+  if (value == null || value === '') {
+    return undefined
+  }
+  if (Array.isArray(value)) {
+    const entries = value.filter(entry => entry != null && entry !== '').map(entry => `${entry}`)
+    return entries.length > 0 ? entries : undefined
+  }
+  if (typeof value !== 'string') {
+    return [`${value}`]
+  }
+  if (value.startsWith('[')) {
+    const parsed: unknown = (() => {
+      try {
+        return JSON.parse(value)
+      } catch {
+        throw new PlanningError(`malformed:query:${key}`)
+      }
+    })()
+    return Array.isArray(parsed) ? parsed.map(entry => `${entry}`) : undefined
+  }
+  const entries = value.split(',').map(entry => entry.trim()).filter(entry => entry !== '')
+
+  return entries.length > 0 ? entries : undefined
+}
+
+/** A list decoded to a bare value when it holds one — the same criteria either way. */
+const decodeOneOrMany = <T extends string>(value: unknown, key: string): T | T[] | undefined => {
+  const entries = decodeList(value, key) as T[] | undefined
+  return entries == null ? undefined : entries.length === 1 ? entries[0] : entries
+}
+
+const encodeJson = (value: unknown): string | undefined => value == null ? undefined : JSON.stringify(value)
+
+const decodeJson = <T>(value: unknown, key: string): T | undefined => {
+  if (value == null || value === '') {
+    return undefined
+  }
+  if (typeof value !== 'string') {
+    return value as T
+  }
+  try {
+    return JSON.parse(value) as T
+  } catch {
+    throw new PlanningError(`malformed:query:${key}`)
+  }
+}
+
+const decodeNumber = (value: unknown, key: string): number | undefined => {
+  if (value == null || value === '') {
+    return undefined
+  }
+  const number = typeof value === 'number' ? value : Number(value)
+  if (Number.isNaN(number)) {
+    throw new PlanningError(`malformed:query:${key}`)
+  }
+
+  return number
+}
+
+const decodeBoolean = (value: unknown): boolean | undefined =>
+  value == null || value === '' ? undefined : value === true || value === 'true' || value === '1'
+
+const decodeText = (value: unknown): string | undefined =>
+  value == null || value === '' ? undefined : `${Array.isArray(value) ? value[0] : value}`
+
+/** `[{ field: 'order' }, { field: 'updatedAt', order: 'desc' }]` ⇄ `order,-updatedAt`. */
+export const encodeSort = <T>(sort?: Sort<T>[] | null): string | undefined =>
+  sort == null || sort.length === 0 ? undefined : sort.map(entry => typeof entry === 'string'
+    ? entry
+    : `${entry.order === 'desc' ? '-' : ''}${entry.field}`).join(',')
+
+export const decodeSort = <T>(value: unknown): Sort<T>[] | undefined => {
+  if (value == null || value === '') {
+    return undefined
+  }
+  const entries: unknown[] = Array.isArray(value) ? value : typeof value === 'string' ? value.split(',') : [value]
+  const sort = entries.flatMap((entry): Sort<T>[] => {
+    if (typeof entry !== 'string') {
+      return entry != null && typeof entry === 'object' && 'field' in entry ? [entry as Sort<T>] : []
+    }
+    const field = entry.trim()
+    if (field === '' || field === '-') {
+      return []
+    }
+    return field.startsWith('-')
+      ? [{ field: field.slice(1) as Sort<T> & string, order: 'desc' } as Sort<T>]
+      : [field as Sort<T>]
+  })
+
+  return sort.length > 0 ? sort : undefined
+}
+
+const encodeListOptions = (query?: ListOptions<any> | null): ListWire => clean({
+  page: query?.page,
+  size: query?.size,
+  sort: encodeSort(query?.sort),
+})
+
+const decodeListOptions = <T>(wire: Record<string, unknown>): ListOptions<T> => clean({
+  page: decodeNumber(wire.page, 'page'),
+  size: decodeNumber(wire.size, 'size'),
+  sort: decodeSort<T>(wire.sort),
+})
+
+const asRecord = (wire: unknown): Record<string, unknown> =>
+  wire != null && typeof wire === 'object' ? wire as Record<string, unknown> : {}
+
+export const encodeWorkcardQuery = (query?: WorkcardQuery | null): WorkcardQueryWire => clean({
+  ...encodeListOptions(query),
+  kind: encodeList(query?.kind),
+  type: encodeList(query?.type),
+  parent: query?.parent,
+  within: query?.within,
+  status: encodeList(query?.status),
+  intrinsic: encodeList(query?.intrinsic),
+  flow: encodeJson(query?.flow),
+  labels: encodeList(query?.labels),
+  code: encodeList(query?.code),
+  ids: encodeList(query?.ids),
+  fields: query?.fields != null && Object.keys(query.fields).length > 0 ? encodeJson(query.fields) : undefined,
+  q: query?.q,
+  category: encodeList(query?.category),
+  updatedSince: query?.updatedSince,
+})
+
+/** @throws {PlanningError} `malformed:query:<key>` for a value that does not decode */
+export const decodeWorkcardQuery = (wire?: WorkcardQueryWire | WorkcardQuery | null): WorkcardQuery => {
+  const value = asRecord(wire)
+  return clean({
+    ...decodeListOptions<Workcard>(value),
+    kind: decodeOneOrMany<WorkcardKind>(value.kind, 'kind'),
+    type: decodeOneOrMany(value.type, 'type'),
+    parent: decodeText(value.parent),
+    within: decodeText(value.within),
+    status: decodeOneOrMany(value.status, 'status'),
+    intrinsic: decodeOneOrMany<IntrinsicStatus>(value.intrinsic, 'intrinsic'),
+    flow: decodeJson<WorkcardQuery['flow']>(value.flow, 'flow'),
+    labels: decodeList(value.labels, 'labels'),
+    code: decodeOneOrMany(value.code, 'code'),
+    ids: decodeList(value.ids, 'ids'),
+    fields: decodeJson<Record<string, unknown>>(value.fields, 'fields'),
+    q: decodeText(value.q),
+    category: decodeOneOrMany(value.category, 'category'),
+    updatedSince: decodeText(value.updatedSince),
+  })
+}
+
+export const encodeSummaryQuery = (query: SummaryQuery): SummaryQueryWire => clean({
+  parents: encodeList(query.parents) ?? '',
+  kind: query.kind,
+  type: encodeList(query.type),
+})
+
+export const decodeSummaryQuery = (wire?: SummaryQueryWire | SummaryQuery | null): SummaryQuery => {
+  const value = asRecord(wire)
+  return clean({
+    parents: decodeList(value.parents, 'parents') ?? [],
+    kind: decodeText(value.kind) as WorkcardKind | undefined,
+    type: decodeOneOrMany(value.type, 'type'),
+  })
+}
+
+export const encodeTransitionQuery = (query?: TransitionQuery | null): TransitionQueryWire => clean({
+  ...encodeListOptions(query),
+  card: query?.card,
+  project: query?.project,
+  sinceSeq: query?.sinceSeq,
+  action: encodeList(query?.action),
+  state: query?.state,
+})
+
+export const decodeTransitionQuery = (wire?: TransitionQueryWire | TransitionQuery | null): TransitionQuery => {
+  const value = asRecord(wire)
+  return clean({
+    ...decodeListOptions(value),
+    card: decodeText(value.card),
+    project: decodeText(value.project),
+    sinceSeq: decodeNumber(value.sinceSeq, 'sinceSeq'),
+    action: decodeOneOrMany(value.action, 'action'),
+    state: decodeText(value.state),
+  }) as TransitionQuery
+}
+
+export const encodeSpecificationQuery = (query?: SpecificationQuery | null): SpecificationQueryWire => clean({
+  ...encodeListOptions(query),
+  category: encodeList(query?.category),
+  all: query?.all,
+})
+
+export const decodeSpecificationQuery = (wire?: SpecificationQueryWire | SpecificationQuery | null): SpecificationQuery => {
+  const value = asRecord(wire)
+  return clean({
+    ...decodeListOptions<Specification>(value),
+    category: decodeOneOrMany(value.category, 'category'),
+    all: decodeBoolean(value.all),
+  })
+}
+
+export const encodeRelationshipQuery = (query?: RelationshipQuery | null): RelationshipQueryWire => clean({
+  ...encodeListOptions(query),
+  from: encodeList(query?.from),
+  to: encodeList(query?.to),
+  type: encodeList(query?.type),
+})
+
+export const decodeRelationshipQuery = (wire?: RelationshipQueryWire | RelationshipQuery | null): RelationshipQuery => {
+  const value = asRecord(wire)
+  return clean({
+    ...decodeListOptions(value),
+    from: decodeOneOrMany(value.from, 'from'),
+    to: decodeOneOrMany(value.to, 'to'),
+    type: decodeOneOrMany(value.type, 'type'),
+  }) as RelationshipQuery
+}

package/src/helpers/specification.ts

@@ -0,0 +1,65 @@
+import { WorkcardKind } from '../consts.js'
+import { UnknownWorkcardType } from '../errors.js'
+import type {
+  AnyTypeSchema, PlanningSchemaRegistry, Specification, SpecificationSlot, Workcard,
+} from '../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 isRevisioned = (slot?: SpecificationSlot | null): boolean => slot?.revisioned === true
+
+export 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 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(':')) : ''
+
+/**
+ * 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
+  }
+
+  throw new UnknownWorkcardType(`specification:${parentType}:${slot?.category ?? ''}`)
+}

package/src/helpers/status.ts

@@ -0,0 +1,117 @@
+import { ANY_STATUS, INTRINSIC_ORDER, IntrinsicPolicy, IntrinsicStatus } from '../consts.js'
+import { PlanningError, UnknownStatusFlow } from '../errors.js'
+import type {
+  AnyTypeSchema, PlanningSchemaRegistry, StatusDefinition, StatusFlowSchema, StatusTransitionRule,
+} from '../types.js'
+
+type FlowLookup = Pick<PlanningSchemaRegistry, 'flow'>
+
+/** The primary flow id of a type — `flows[0]`. @throws {UnknownStatusFlow} when it declares none */
+export const primaryFlowOf = (type: AnyTypeSchema): string => {
+  const primary = type.flows[0]
+  if (primary == null) {
+    throw new UnknownStatusFlow(`${type.type}:primary`)
+  }
+
+  return primary
+}
+
+export const flowIdsOf = (type: AnyTypeSchema): string[] => [...type.flows]
+
+export const statusDefinitionOf = (flow: StatusFlowSchema, status: string): StatusDefinition | undefined =>
+  flow.statuses.find(definition => definition.key === status)
+
+/** The intrinsic state a status maps onto, or `undefined` for a status the flow does not declare. */
+export const intrinsicOf = (flow: StatusFlowSchema, status: string): IntrinsicStatus | undefined =>
+  statusDefinitionOf(flow, status)?.intrinsic
+
+/** The status marked `initial`, else the first one. @throws {PlanningError} for a flow with none */
+export const initialStatusOf = (flow: StatusFlowSchema): string => {
+  const status = flow.statuses.find(definition => definition.initial === true) ?? flow.statuses[0]
+  if (status == null) {
+    throw new PlanningError(`flow-empty:${flow.id}`)
+  }
+
+  return status.key
+}
+
+export const isTerminal = (flow: StatusFlowSchema, status: string): boolean =>
+  statusDefinitionOf(flow, status)?.terminal === true
+
+const fromMatches = (rule: StatusTransitionRule, status: string): boolean =>
+  rule.from === ANY_STATUS || (Array.isArray(rule.from) && rule.from.includes(status))
+
+/**
+ * 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.
+ */
+export const ruleOf = (
+  flow: StatusFlowSchema, transition: string, from: string
+): StatusTransitionRule | undefined => {
+  const named = flow.transitions.filter(rule => rule.name === transition)
+
+  return named.find(rule => rule.from !== ANY_STATUS && fromMatches(rule, from))
+    ?? named.find(rule => rule.from === ANY_STATUS)
+}
+
+export const canTransit = (flow: StatusFlowSchema, transition: string, from: string): boolean =>
+  ruleOf(flow, transition, from) != null
+
+/**
+ * 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.
+ */
+export const transitionsFrom = (
+  flow: StatusFlowSchema, status: string, opts?: { explicit?: boolean }
+): StatusTransitionRule[] => {
+  const names = [...new Set(flow.transitions.map(rule => rule.name))]
+
+  return names.map(name => ruleOf(flow, name, status))
+    .filter((rule): rule is StatusTransitionRule => rule != null)
+    .filter(rule => opts?.explicit !== true || rule.explicit === true)
+}
+
+/**
+ * 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}
+ */
+export const initialFlowsOf = (
+  type: AnyTypeSchema, registry: FlowLookup, status?: string
+): Record<string, string> => {
+  const primary = primaryFlowOf(type)
+
+  return Object.fromEntries(type.flows.map(id => [
+    id, id === primary && status != null ? status : initialStatusOf(registry.flow(id)),
+  ]))
+}
+
+/**
+ * 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}
+ */
+export const resolveIntrinsic = (
+  type: AnyTypeSchema, flows: Record<string, string>, registry: FlowLookup
+): IntrinsicStatus => {
+  const read = (id: string): IntrinsicStatus => {
+    const status = flows[id]
+    return status == null
+      ? IntrinsicStatus.Planned
+      : intrinsicOf(registry.flow(id), status) ?? IntrinsicStatus.Planned
+  }
+
+  if (type.intrinsic !== IntrinsicPolicy.All) {
+    return read(primaryFlowOf(type))
+  }
+
+  return type.flows.map(read).reduce<IntrinsicStatus>(
+    (least, intrinsic) => INTRINSIC_ORDER[intrinsic] < INTRINSIC_ORDER[least] ? intrinsic : least,
+    IntrinsicStatus.Closed
+  )
+}

package/src/helpers/validate.ts

@@ -0,0 +1,107 @@
+import { Ajv } from 'ajv'
+import type { ErrorObject, ValidateFunction } from 'ajv'
+import formatsPlugin from 'ajv-formats'
+import { SpecificationFormat, WorkcardKind } from '../consts.js'
+import { FieldsInvalid, PlanningError } from '../errors.js'
+import { AnyWorkcardSchema, SpecificationSchema, WorkcardSchema } from '../schemas.js'
+import type { PlanningSchemaRegistry, SpecificationSlot, Workcard } from '../types.js'
+
+/** The ajv every planning validation compiles with: lenient about unknown keywords, all errors, formats. */
+export const makeAjv = (): Ajv => {
+  const ajv = new Ajv({ strict: false, allErrors: true })
+  formatsPlugin(ajv as any)
+
+  return ajv
+}
+
+let shared: Ajv | undefined
+const ajvOf = (): Ajv => shared ??= makeAjv()
+
+const compiled = new Map<object, ValidateFunction>()
+const compile = (schema: object): ValidateFunction => {
+  let validate = compiled.get(schema)
+  if (validate == null) {
+    validate = ajvOf().compile(schema)
+    compiled.set(schema, validate)
+  }
+
+  return validate
+}
+
+/** One line per ajv error: `/path message`. */
+export const ajvErrorText = (errors?: ErrorObject[] | null): string =>
+  (errors ?? []).map(error => `${error.instancePath === '' ? '/' : error.instancePath} ${error.message ?? 'invalid'}`)
+    .join('; ')
+
+/** Keys holding `.` or `$` at any depth — a document store cannot hold them. */
+export const invalidFieldKeys = (fields: unknown, path: string = ''): string[] => {
+  if (fields == null || typeof fields !== 'object') {
+    return []
+  }
+  if (Array.isArray(fields)) {
+    return fields.flatMap((entry, index) => invalidFieldKeys(entry, `${path}${index}.`))
+  }
+
+  return Object.entries(fields).flatMap(([key, value]) => [
+    ...(key.includes('.') || key.includes('$') ? [`${path}${key}`] : []),
+    ...invalidFieldKeys(value, `${path}${key}.`),
+  ])
+}
+
+/**
+ * Check `fields` against the type's schema, and its keys against the store rule.
+ *
+ * @throws {FieldsInvalid}
+ */
+export const validateFields = (
+  registry: Pick<PlanningSchemaRegistry, 'validator'>, type: string, fields: Record<string, unknown>
+): void => {
+  const keys = invalidFieldKeys(fields)
+  if (keys.length > 0) {
+    throw new FieldsInvalid(`keys:${keys.join(',')}`)
+  }
+  const validate = registry.validator(type)
+  if (!validate(fields)) {
+    throw new FieldsInvalid(`${type}:${ajvErrorText(validate.errors)}`)
+  }
+}
+
+/**
+ * Check a whole record: its shape by kind, then its `fields` by type.
+ *
+ * @throws {PlanningError} `malformed:card:…` for a shape fault
+ * @throws {FieldsInvalid}
+ */
+export const validateCard = (card: Workcard, registry: Pick<PlanningSchemaRegistry, 'validator'>): void => {
+  const validate = compile(card.kind === WorkcardKind.Specification
+    ? SpecificationSchema
+    : card.kind === WorkcardKind.Card || card.kind === WorkcardKind.Project ? WorkcardSchema : AnyWorkcardSchema)
+  if (!validate(card)) {
+    throw new PlanningError(`malformed:card:${ajvErrorText(validate.errors)}`)
+  }
+  validateFields(registry, card.type, card.fields)
+}
+
+/**
+ * Check a document body against its slot: a JSON slot must parse, and match the slot's schema when
+ * it declares one.
+ *
+ * @throws {FieldsInvalid}
+ */
+export const validateSpecificationBody = (slot: SpecificationSlot, body?: string | null): void => {
+  if (body == null || slot.format !== SpecificationFormat.Json) {
+    return
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(body)
+  } catch {
+    throw new FieldsInvalid(`body:${slot.category}:not-json`)
+  }
+  if (slot.schema != null && typeof slot.schema === 'object') {
+    const validate = compile(slot.schema)
+    if (!validate(parsed)) {
+      throw new FieldsInvalid(`body:${slot.category}:${ajvErrorText(validate.errors)}`)
+    }
+  }
+}

package/src/i18n/be.json

@@ -0,0 +1,51 @@
+{
+  "kind": {
+    "card": "Картка",
+    "project": "Праект",
+    "specification": "Спецыфікацыя"
+  },
+  "intrinsic": {
+    "planned": "Запланавана",
+    "in-progress": "У працы",
+    "closed": "Закрыта"
+  },
+  "action": {
+    "create": "Створана",
+    "update": "Абноўлена",
+    "transit": "Статус зменены",
+    "link": "Звязана",
+    "unlink": "Сувязь выдалена",
+    "delete": "Выдалена"
+  },
+  "commit": {
+    "pending": "Захаванне…",
+    "committed": "Захавана",
+    "failed": "Не захавана"
+  },
+  "format": {
+    "markdown": "Markdown",
+    "json": "JSON",
+    "text": "Звычайны тэкст"
+  },
+  "errors": {
+    "PlanningError": "Не ўдалося выканаць запыт планавання",
+    "PlanningErrorWorkcardNotFound": "Гэты элемент не існуе або недаступны вам",
+    "PlanningErrorUnknownWorkcardType": "Гэты тып элемента невядомы",
+    "PlanningErrorUnknownStatusFlow": "Гэты паток статусаў невядомы",
+    "PlanningErrorParentNotFound": "Бацькоўскі элемент не існуе",
+    "PlanningErrorCardTypeNotAllowed": "Элемент гэтага тыпу нельга дадаць сюды",
+    "PlanningErrorRefused": "Змяненне адхілена",
+    "PlanningErrorIllegalTransition": "Такая змена статусу недапушчальная з бягучага статусу",
+    "PlanningErrorFieldsInvalid": "Некаторыя палі маюць недапушчальныя значэнні",
+    "PlanningErrorLabelNotAllowed": "Гэтая метка тут недапушчальная",
+    "PlanningErrorSpecificationSlotUnknown": "Гэты від дакумента тут недапушчальны",
+    "PlanningErrorSpecificationRevisionConflict": "Гэты дакумент ужо існуе — адрэдагуйце яго",
+    "PlanningErrorRelationshipRefused": "Гэтая сувязь недапушчальная",
+    "PlanningErrorCodeTaken": "Гэты код ужо заняты",
+    "PlanningErrorWorkcardConflict": "Хтосьці змяніў гэты элемент за гэты час — абнавіце і паспрабуйце зноў",
+    "PlanningErrorCommitTimeout": "Змяненне яшчэ захоўваецца — праверце крыху пазней",
+    "PlanningErrorCommitFailed": "Не ўдалося захаваць змяненне",
+    "PlanningErrorScopeMismatch": "Гэты элемент не існуе або недаступны вам",
+    "PlanningErrorUnsupported": "Гэтая аперацыя не падтрымліваецца для гэтага элемента"
+  }
+}