@edoxen/browser 0.1.0

package/src/data/lint.spec.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest'
+import { buildProject, type Decision, type Meeting } from '@edoxen/edoxen'
+
+import { lintProject } from './lint.js'
+
+function decision(urn: string, extra: Partial<Decision> = {}): Decision {
+  return {
+    identifier: [{ prefix: 'TEST', number: urn }],
+    kind: 'resolution',
+    urn,
+    localizations: [{ language_code: 'eng', title: urn }],
+    ...extra,
+  } as Decision
+}
+
+function meeting(urn: string, extra: Partial<Meeting> = {}): Meeting {
+  return {
+    identifier: [{ prefix: 'TEST', number: urn }],
+    type: 'plenary',
+    urn,
+    ...extra,
+  } as Meeting
+}
+
+describe('lintProject', () => {
+  it('returns ok=true with no findings for clean data', () => {
+    const project = buildProject({
+      decisions: [decision('urn:test:1')],
+      meetings: [],
+    })
+    const report = lintProject(project)
+    expect(report.ok).toBe(true)
+    expect(report.findings).toEqual([])
+  })
+
+  it('flags duplicate decision URNs as errors', () => {
+    const project = buildProject({
+      decisions: [decision('urn:test:dup'), decision('urn:test:dup')],
+    })
+    const report = lintProject(project)
+    expect(report.ok).toBe(false)
+    expect(report.findings.some((f) => f.code === 'DUPLICATE_DECISION_URN')).toBe(true)
+  })
+
+  it('warns on relations pointing to unknown decisions', () => {
+    const project = buildProject({
+      decisions: [
+        decision('urn:test:1', {
+          relations: [{ source: { prefix: 'TEST', number: '1' }, destination: { prefix: 'TEST', number: 'missing' }, type: 'cites' }],
+        }),
+      ],
+    })
+    const report = lintProject(project)
+    expect(report.ok).toBe(true)
+    expect(report.findings.some((f) => f.code === 'BROKEN_DECISION_RELATION')).toBe(true)
+  })
+
+  it('warns when a decision references an unknown meeting date', () => {
+    const project = buildProject({
+      decisions: [
+        decision('urn:test:1', { meeting: { date: '2024-06-15' } }),
+      ],
+      meetings: [meeting('urn:test:m1', { date_range: { start: '2024-06-15', end: '2024-06-15' } })],
+    })
+    const report = lintProject(project)
+    expect(report.findings.some((f) => f.code === 'ORPHAN_DECISION_MEETING')).toBe(true)
+  })
+
+  it('does not flag a decision whose meeting date matches a real meeting', () => {
+    const project = buildProject({
+      decisions: [
+        decision('urn:test:1', { meeting: { date: '2024-06-15' } }),
+      ],
+      meetings: [meeting('urn:test:meeting-1', { urn: '2024-06-15', date_range: { start: '2024-06-15', end: '2024-06-15' } })],
+    })
+    const report = lintProject(project)
+    expect(report.findings.some((f) => f.code === 'ORPHAN_DECISION_MEETING')).toBe(false)
+  })
+})

package/src/data/lint.ts

@@ -0,0 +1,77 @@
+import type { EdoxenProject } from '@edoxen/edoxen'
+
+export type LintSeverity = 'error' | 'warning'
+
+export interface LintFinding {
+  readonly code: string
+  readonly severity: LintSeverity
+  readonly message: string
+}
+
+export interface LintReport {
+  readonly findings: readonly LintFinding[]
+  readonly ok: boolean
+}
+
+function uniq<T>(values: Iterable<T>): T[] {
+  return [...new Set(values)]
+}
+
+function decisionIdentifierKey(d: { identifier?: { prefix: string; number: string }[] }): string {
+  const head = d.identifier?.[0]
+  return head ? `${head.prefix}-${head.number}` : ''
+}
+
+export function lintProject(project: EdoxenProject): LintReport {
+  const findings: LintFinding[] = []
+
+  const urnCounts = new Map<string, number>()
+  for (const d of project.decisions) {
+    if (!d.urn) continue
+    urnCounts.set(d.urn, (urnCounts.get(d.urn) ?? 0) + 1)
+  }
+  for (const [urn, count] of urnCounts) {
+    if (count > 1) {
+      findings.push({
+        code: 'DUPLICATE_DECISION_URN',
+        severity: 'error',
+        message: `Decision URN ${urn} appears ${count} times`,
+      })
+    }
+  }
+
+  const decisionIds = new Set<string>()
+  for (const d of project.decisions) {
+    const key = decisionIdentifierKey(d)
+    if (key) decisionIds.add(key)
+  }
+  for (const d of project.decisions) {
+    for (const r of d.relations ?? []) {
+      const key = decisionIdentifierKey({ identifier: [r.destination] })
+      if (key && !decisionIds.has(key)) {
+        findings.push({
+          code: 'BROKEN_DECISION_RELATION',
+          severity: 'warning',
+          message: `Decision ${d.urn} references unknown decision ${key}`,
+        })
+      }
+    }
+  }
+
+  const meetingUrns = new Set(project.meetings.map((m) => m.urn).filter((u): u is string => Boolean(u)))
+  for (const d of project.decisions) {
+    const meetingDate = d.meeting?.date
+    if (meetingDate && !meetingUrns.has(meetingDate) && !project.meetingByUrn(meetingDate)) {
+      findings.push({
+        code: 'ORPHAN_DECISION_MEETING',
+        severity: 'warning',
+        message: `Decision ${d.urn} references unknown meeting key ${meetingDate}`,
+      })
+    }
+  }
+
+  return {
+    findings: uniq(findings),
+    ok: !findings.some((f) => f.severity === 'error'),
+  }
+}

package/src/data/load.spec.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+
+import { loadAll } from './load.js'
+import type { DataConfig } from '../config/schema.js'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const fixtures = resolve(here, '../../test/fixtures')
+
+function dataConfig(decisions = './decisions', meetings?: string): DataConfig {
+  return {
+    decisions: resolve(fixtures, decisions),
+    ...(meetings ? { meetings: resolve(fixtures, meetings) } : {}),
+  }
+}
+
+describe('loadAll', () => {
+  it('loads every decision from a directory of fixtures', async () => {
+    const result = await loadAll(dataConfig())
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    expect(result.value.decisions?.decisions.length).toBe(2)
+    expect(result.value.decisions?.decisions[0]?.urn).toBe('urn:test:resolution:1')
+  })
+
+  it('returns ok with no meetings when none requested', async () => {
+    const result = await loadAll(dataConfig())
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    expect(result.value.meetings).toBeUndefined()
+  })
+
+  it('loads meetings when configured', async () => {
+    const result = await loadAll(dataConfig('./decisions', './meetings'))
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    expect(result.value.meetings?.meetings.length).toBe(2)
+    expect(result.value.meetings?.meetings[0]?.urn).toBe('urn:test:meeting:2024')
+  })
+
+  it('reports a structured error when the decisions path does not exist', async () => {
+    const result = await loadAll(dataConfig('./missing-decisions'))
+    expect(result.ok).toBe(false)
+    if (result.ok) return
+    expect(result.error.length).toBeGreaterThanOrEqual(1)
+    expect(result.error[0]?.source).toBe('decisions')
+    expect(result.error[0]?.path).toMatch(/missing-decisions$/)
+    expect(result.error[0]?.cause).toBeInstanceOf(Error)
+  })
+
+  it('reports one error per failing source', async () => {
+    const result = await loadAll(dataConfig('./missing-decisions', './missing-meetings'))
+    expect(result.ok).toBe(false)
+    if (result.ok) return
+    expect(result.error.map((e) => e.source).sort()).toEqual(['decisions', 'meetings'])
+  })
+})

package/src/data/load.ts

@@ -0,0 +1,50 @@
+import {
+  loadDecisions,
+  loadMeetings,
+  type LoadedDecisions,
+  type LoadedMeetings,
+} from '@edoxen/edoxen'
+
+import type { DataConfig } from '../config/schema.js'
+
+export interface LoadedData {
+  decisions?: LoadedDecisions
+  meetings?: LoadedMeetings
+}
+
+export type DataSource = 'decisions' | 'meetings'
+
+export interface LoadError {
+  readonly source: DataSource
+  readonly path: string
+  readonly cause: Error
+}
+
+export type LoadResult =
+  | { readonly ok: true; readonly value: LoadedData }
+  | { readonly ok: false; readonly error: LoadError[] }
+
+function wrapError(source: DataSource, path: string, e: unknown): LoadError {
+  return { source, path, cause: e instanceof Error ? e : new Error(String(e)) }
+}
+
+export async function loadAll(data: DataConfig): Promise<LoadResult> {
+  const errors: LoadError[] = []
+  const out: LoadedData = {}
+
+  try {
+    out.decisions = await loadDecisions(data.decisions)
+  } catch (e) {
+    errors.push(wrapError('decisions', data.decisions, e))
+  }
+
+  if (data.meetings) {
+    try {
+      out.meetings = await loadMeetings(data.meetings)
+    } catch (e) {
+      errors.push(wrapError('meetings', data.meetings, e))
+    }
+  }
+
+  return errors.length === 0 ? { ok: true, value: out } : { ok: false, error: errors }
+}

package/src/data/prepare.spec.ts

@@ -0,0 +1,137 @@
+import { describe, expect, it } from 'vitest'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+
+import { loadAll } from './load.js'
+import { validateAll } from './validate.js'
+import { buildProjectFromLoaded } from './project.js'
+import { prepareDecisionsList, prepareMeetingsList, preparePayloads } from './prepare.js'
+import type { DataConfig } from '../config/schema.js'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const fixtures = resolve(here, '../../test/fixtures')
+
+const cfg: DataConfig = {
+  decisions: resolve(fixtures, './decisions'),
+  meetings: resolve(fixtures, './meetings'),
+}
+
+describe('validateAll', () => {
+  it('returns valid=true for clean fixtures', async () => {
+    const loaded = await loadAll(cfg)
+    if (!loaded.ok) throw new Error('load failed')
+    const report = await validateAll(loaded.value)
+    expect(report.valid).toBe(true)
+  })
+
+  it('returns the per-source ValidateResult for inspection', async () => {
+    const loaded = await loadAll(cfg)
+    if (!loaded.ok) throw new Error('load failed')
+    const report = await validateAll(loaded.value)
+    expect(report.decisions?.valid).toBe(true)
+    expect(report.meetings?.valid).toBe(true)
+  })
+})
+
+describe('buildProjectFromLoaded', () => {
+  it('joins decisions + meetings + committee into an EdoxenProject', async () => {
+    const loaded = await loadAll(cfg)
+    if (!loaded.ok) throw new Error('load failed')
+    const project = buildProjectFromLoaded(loaded.value)
+    expect(project.decisions.length).toBe(2)
+    expect(project.meetings.length).toBe(2)
+    expect(project.committee).toBeNull()
+  })
+})
+
+describe('prepareDecisionsList', () => {
+  it('produces a list sorted by date descending', async () => {
+    const loaded = await loadAll(cfg)
+    if (!loaded.ok) throw new Error('load failed')
+    const project = buildProjectFromLoaded(loaded.value)
+    const payload = prepareDecisionsList(project)
+    expect(payload.items.map((i) => i.urn)).toEqual([
+      'urn:test:resolution:1',
+      'urn:test:resolution:2',
+    ])
+  })
+
+  it('derives identifier from prefix + number', async () => {
+    const loaded = await loadAll(cfg)
+    if (!loaded.ok) throw new Error('load failed')
+    const payload = prepareDecisionsList(buildProjectFromLoaded(loaded.value))
+    expect(payload.items[0]?.identifier).toBe('TEST-1')
+  })
+
+  it('surfaces body_type for join against cfg.bodies', async () => {
+    const loaded = await loadAll(cfg)
+    if (!loaded.ok) throw new Error('load failed')
+    const payload = prepareDecisionsList(buildProjectFromLoaded(loaded.value))
+    expect(payload.items.every((i) => i.bodyType === 'committee')).toBe(true)
+    expect(payload.facets.bodies).toEqual(['committee'])
+  })
+
+  it('exposes year + kind facets from the data', async () => {
+    const loaded = await loadAll(cfg)
+    if (!loaded.ok) throw new Error('load failed')
+    const payload = prepareDecisionsList(buildProjectFromLoaded(loaded.value))
+    expect(payload.facets.years).toEqual([2023, 2024])
+    expect(payload.facets.kinds).toEqual(['recommendation', 'resolution'])
+  })
+
+  it('carries meetingUrn (meeting date key) for back-links to /meetings/[urn]', async () => {
+    const loaded = await loadAll(cfg)
+    if (!loaded.ok) throw new Error('load failed')
+    const payload = prepareDecisionsList(buildProjectFromLoaded(loaded.value))
+    expect(payload.items[0]?.meetingUrn).toBe('2024-06-15')
+  })
+})
+
+describe('prepareMeetingsList', () => {
+  it('produces a list sorted by start date descending', async () => {
+    const loaded = await loadAll(cfg)
+    if (!loaded.ok) throw new Error('load failed')
+    const payload = prepareMeetingsList(buildProjectFromLoaded(loaded.value))
+    expect(payload.items.map((i) => i.urn)).toEqual([
+      'urn:test:meeting:2024',
+      'urn:test:meeting:2023',
+    ])
+  })
+
+  it('exposes decade + body + country facets', async () => {
+    const loaded = await loadAll(cfg)
+    if (!loaded.ok) throw new Error('load failed')
+    const payload = prepareMeetingsList(buildProjectFromLoaded(loaded.value))
+    expect(payload.facets.decades).toEqual([2020])
+    expect(payload.facets.bodies).toEqual(['committee'])
+    expect(payload.facets.countries).toEqual(['DE', 'FR'])
+  })
+
+  it('exposes year + city for display', async () => {
+    const loaded = await loadAll(cfg)
+    if (!loaded.ok) throw new Error('load failed')
+    const payload = prepareMeetingsList(buildProjectFromLoaded(loaded.value))
+    expect(payload.items[0]?.year).toBe(2024)
+    expect(payload.items[0]?.city).toBe('CNSHA')
+  })
+})
+
+describe('preparePayloads', () => {
+  it('returns both list payloads in one call', async () => {
+    const loaded = await loadAll(cfg)
+    if (!loaded.ok) throw new Error('load failed')
+    const payloads = preparePayloads(buildProjectFromLoaded(loaded.value))
+    expect(payloads.decisionsList.items.length).toBe(2)
+    expect(payloads.meetingsList.items.length).toBe(2)
+  })
+
+  it('exposes decisionByUrn and meetingByUrn maps for detail pages', async () => {
+    const loaded = await loadAll(cfg)
+    if (!loaded.ok) throw new Error('load failed')
+    const payloads = preparePayloads(buildProjectFromLoaded(loaded.value))
+    expect(payloads.decisionByUrn['urn:test:resolution:1']).toBeDefined()
+    expect(payloads.decisionByUrn['urn:test:resolution:1']?.body_type).toBe('committee')
+    expect(payloads.meetingByUrn['urn:test:meeting:2024']).toBeDefined()
+    expect(payloads.meetingByUrn['urn:test:meeting:2024']?.city).toBe('CNSHA')
+  })
+})

package/src/data/prepare.ts

@@ -0,0 +1,199 @@
+import type {
+  Action,
+  Approval,
+  Consideration,
+  Decision,
+  EdoxenProject,
+  LocalizedString,
+  Meeting,
+  StructuredIdentifier,
+} from '@edoxen/edoxen'
+
+export interface DecisionListItem {
+  readonly urn: string
+  readonly identifier: string
+  readonly title: string
+  readonly kind: string
+  readonly dates: readonly { readonly type: string; readonly date: string }[]
+  readonly meetingUrn?: string
+  readonly bodyType?: string
+}
+
+export interface DecisionListFacets {
+  readonly years: readonly number[]
+  readonly kinds: readonly string[]
+  readonly bodies: readonly string[]
+  readonly meetingUrns: readonly string[]
+}
+
+export interface DecisionListPayload {
+  readonly items: readonly DecisionListItem[]
+  readonly facets: DecisionListFacets
+}
+
+export interface MeetingListItem {
+  readonly urn: string
+  readonly identifier: string
+  readonly title: string
+  readonly startDate?: string
+  readonly endDate?: string
+  readonly year?: number
+  readonly bodyType?: string
+  readonly city?: string
+  readonly countryCode?: string
+  readonly status?: string
+}
+
+export interface MeetingListFacets {
+  readonly decades: readonly number[]
+  readonly bodies: readonly string[]
+  readonly countries: readonly string[]
+}
+
+export interface MeetingListPayload {
+  readonly items: readonly MeetingListItem[]
+  readonly facets: MeetingListFacets
+}
+
+export interface PagePayloads {
+  readonly decisionsList: DecisionListPayload
+  readonly meetingsList: MeetingListPayload
+  readonly decisionByUrn: Readonly<Record<string, Decision>>
+  readonly meetingByUrn: Readonly<Record<string, Meeting>>
+}
+
+function formatIdentifier(ids: readonly StructuredIdentifier[] | undefined): string {
+  if (!ids || ids.length === 0) return ''
+  const head = ids[0]
+  if (!head) return ''
+  return `${head.prefix}-${head.number}`
+}
+
+function primaryValue(list: readonly LocalizedString[] | undefined, fallback: string): string {
+  const first = list?.[0]?.value
+  return first && first.length > 0 ? first : fallback
+}
+
+function meetingKeyOf(d: Decision): string | undefined {
+  return d.meeting?.date ?? d.meeting?.venue
+}
+
+function effectiveYearOf(d: Decision): number | null {
+  for (const dt of d.dates ?? []) {
+    const v = dt.date
+    if (typeof v === 'string' && v.length >= 4) {
+      const year = Number(v.slice(0, 4))
+      if (Number.isInteger(year)) return year
+    }
+  }
+  return null
+}
+
+function yearOfMeeting(m: Meeting): number | null {
+  const start = m.date_range?.start
+  if (typeof start !== 'string' || start.length < 4) return null
+  const year = Number(start.slice(0, 4))
+  return Number.isInteger(year) ? year : null
+}
+
+function decadeOf(year: number): number {
+  return Math.floor(year / 10) * 10
+}
+
+function uniqSorted(values: Iterable<string>): readonly string[] {
+  const set = new Set<string>()
+  for (const v of values) if (v && v.length > 0) set.add(v)
+  return [...set].sort()
+}
+
+function uniqSortedNumbers(values: Iterable<number>): readonly number[] {
+  const set = new Set<number>()
+  for (const v of values) if (Number.isFinite(v)) set.add(v)
+  return [...set].sort((a, b) => a - b)
+}
+
+function toDecisionListItem(d: Decision): DecisionListItem {
+  const meetingKey = meetingKeyOf(d)
+  return {
+    urn: d.urn ?? '',
+    identifier: formatIdentifier(d.identifier),
+    title: primaryValue(d.title, d.urn ?? formatIdentifier(d.identifier)),
+    kind: d.kind ?? '',
+    dates: (d.dates ?? []).map((dt) => ({ type: dt.type ?? '', date: dt.date ?? '' })),
+    meetingUrn: meetingKey,
+    bodyType: d.body_type,
+  }
+}
+
+function toMeetingListItem(m: Meeting): MeetingListItem {
+  const year = yearOfMeeting(m)
+  return {
+    urn: m.urn ?? '',
+    identifier: formatIdentifier(m.identifier),
+    title: primaryValue(m.title, m.urn ?? formatIdentifier(m.identifier)),
+    startDate: m.date_range?.start,
+    endDate: m.date_range?.end,
+    year: year ?? undefined,
+    bodyType: m.body_type,
+    city: m.city,
+    countryCode: m.country_code,
+    status: m.status,
+  }
+}
+
+export function prepareDecisionsList(project: EdoxenProject): DecisionListPayload {
+  const items = [...project.decisions]
+    .map(toDecisionListItem)
+    .sort((a, b) => (b.dates[0]?.date ?? '').localeCompare(a.dates[0]?.date ?? ''))
+
+  return {
+    items,
+    facets: {
+      years: uniqSortedNumbers(project.decisions.map((d) => effectiveYearOf(d) ?? -1).filter((y) => y > 0)),
+      kinds: uniqSorted(project.decisions.map((d) => d.kind ?? '')),
+      bodies: uniqSorted(project.decisions.map((d) => d.body_type ?? '')),
+      meetingUrns: uniqSorted(project.decisions.map((d) => meetingKeyOf(d) ?? '')),
+    },
+  }
+}
+
+export function prepareMeetingsList(project: EdoxenProject): MeetingListPayload {
+  const items = [...project.meetings]
+    .map(toMeetingListItem)
+    .sort((a, b) => (b.startDate ?? '').localeCompare(a.startDate ?? ''))
+
+  const decadesSet = new Set<number>()
+  for (const m of project.meetings) {
+    const y = yearOfMeeting(m)
+    if (y !== null) decadesSet.add(decadeOf(y))
+  }
+
+  return {
+    items,
+    facets: {
+      decades: uniqSortedNumbers(decadesSet),
+      bodies: uniqSorted(project.meetings.map((m) => m.body_type ?? '')),
+      countries: uniqSorted(project.meetings.map((m) => m.country_code ?? '')),
+    },
+  }
+}
+
+export function preparePayloads(project: EdoxenProject): PagePayloads {
+  const decisionByUrn: Record<string, Decision> = {}
+  for (const d of project.decisions) {
+    if (d.urn) decisionByUrn[d.urn] = d
+  }
+  const meetingByUrn: Record<string, Meeting> = {}
+  for (const m of project.meetings) {
+    if (m.urn) meetingByUrn[m.urn] = m
+  }
+
+  return {
+    decisionsList: prepareDecisionsList(project),
+    meetingsList: prepareMeetingsList(project),
+    decisionByUrn,
+    meetingByUrn,
+  }
+}
+
+export type { Action, Approval, Consideration }

package/src/data/project.ts

@@ -0,0 +1,11 @@
+import { buildProject, type EdoxenProject } from '@edoxen/edoxen'
+
+import type { LoadedData } from './load.js'
+
+export function buildProjectFromLoaded(data: LoadedData): EdoxenProject {
+  return buildProject({
+    decisions: data.decisions?.decisions,
+    meetings: data.meetings?.meetings,
+    committee: data.meetings?.series?.[0] ?? null,
+  })
+}

package/src/data/validate.ts

@@ -0,0 +1,38 @@
+import { validateDecisions, validateMeetings, type ValidateResult } from '@edoxen/edoxen'
+
+import type { LoadedData } from './load.js'
+
+export interface ValidationReport {
+  decisions?: ValidateResult
+  meetings?: ValidateResult
+  valid: boolean
+}
+
+function decisionsCollectionShape(data: NonNullable<LoadedData['decisions']>): unknown {
+  return { metadata: data.metadata, decisions: data.decisions }
+}
+
+function meetingsCollectionShape(data: NonNullable<LoadedData['meetings']>): unknown {
+  const out: Record<string, unknown> = { meetings: data.meetings }
+  if (data.metadata) out.metadata = data.metadata
+  return out
+}
+
+export async function validateAll(data: LoadedData): Promise<ValidationReport> {
+  let valid = true
+  const report: ValidationReport = { valid }
+
+  if (data.decisions) {
+    const result = await validateDecisions(decisionsCollectionShape(data.decisions))
+    report.decisions = result
+    if (!result.valid) valid = false
+  }
+
+  if (data.meetings) {
+    const result = await validateMeetings(meetingsCollectionShape(data.meetings))
+    report.meetings = result
+    if (!result.valid) valid = false
+  }
+
+  return { decisions: report.decisions, meetings: report.meetings, valid }
+}

package/src/errors.ts

@@ -0,0 +1,25 @@
+export type IntegrationStage = 'config' | 'load' | 'validate' | 'build' | 'smoke' | 'lint'
+
+export class EdoxenBrowserError extends Error {
+  override readonly name = 'EdoxenBrowserError'
+  readonly stage: IntegrationStage
+  readonly details: readonly string[]
+
+  constructor(stage: IntegrationStage, message: string, details: readonly string[] = []) {
+    super(message)
+    this.stage = stage
+    this.details = details
+  }
+
+  override toString(): string {
+    const head = `[edoxen:${this.stage}] ${this.message}`
+    if (this.details.length === 0) return head
+    return `${head}\n${this.details.map((d) => `  - ${d}`).join('\n')}`
+  }
+}
+
+export function formatValidationErrors(
+  errors: readonly { readonly path: string; readonly message: string }[],
+): readonly string[] {
+  return errors.map((e) => (e.path ? `${e.path}: ${e.message}` : e.message))
+}