@pathmx/core 0.5.0

package/schema/registry.ts

@@ -0,0 +1,642 @@
+import type { ActionContribution } from "../actions/actions.ts"
+import type {
+  ApplicationSchema,
+  BlockType,
+  DataProp,
+  NodeSchema,
+  NodeType,
+  NodeTypeDefinition,
+  QuerySchema,
+  SchemaContribution,
+  SourceType,
+} from "./model.ts"
+import type { QueryContribution } from "../query/model.ts"
+import {
+  formatSchemaIssues,
+  requireStandardJsonSchema,
+  type PathMXDataSchema,
+  type StandardSchemaV1,
+} from "./standard.ts"
+import type { Source, SourceNode } from "../source/index.ts"
+import { SourceDiagnosticError } from "../source-diagnostic.ts"
+
+const NODE_TYPE_ID = /^[a-z0-9]+(?:[/-][a-z0-9]+)*$/
+const MEMBER_ID = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/
+
+type JsonSchema = Readonly<Record<string, unknown>>
+
+type TypeContribution = Readonly<{
+  type: string
+  plugin: string
+  definition: NodeTypeDefinition
+  inputJsonSchema?: JsonSchema
+  outputJsonSchema?: JsonSchema
+}>
+
+type PropContribution = DataProp
+
+export type RegisteredQuery = Readonly<{
+  id: string
+  name: string
+  plugin: string
+  definition: QueryContribution
+  input?: JsonSchema
+  output: JsonSchema
+}>
+
+export type PreparedSchema = Readonly<{
+  sources: readonly TypeContribution[]
+  blocks: readonly TypeContribution[]
+  props: readonly PropContribution[]
+  queries: readonly RegisteredQuery[]
+  actions: readonly (readonly [string, ActionContribution])[]
+}>
+
+function compareText(left: string, right: string) {
+  return left < right ? -1 : left > right ? 1 : 0
+}
+
+function titleCase(type: string) {
+  const name = type.split("/").at(-1) ?? type
+  return name
+    .replace(/[-_]+/g, " ")
+    .replace(/\b\w/g, (character) => character.toUpperCase())
+}
+
+function normalizedText(value: unknown, field: string, owner: string) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`${owner} ${field} must be a non-empty string.`)
+  }
+  return value.trim()
+}
+
+function prepareType(
+  node: "Source" | "Block",
+  plugin: string,
+  type: string,
+  definition: NodeTypeDefinition,
+): TypeContribution {
+  if (!NODE_TYPE_ID.test(type)) {
+    throw new Error(`Plugin ${plugin} has an invalid ${node} type: ${type}`)
+  }
+  if (!definition || typeof definition !== "object") {
+    throw new Error(`Plugin ${plugin} ${node} type ${type} must be an object.`)
+  }
+  const owner = `${plugin}:${type}`
+  const schemaSubject = `Plugin ${plugin} ${node} type ${type} schema`
+  const input = definition.schema
+    ? requireStandardJsonSchema(definition.schema, "input", schemaSubject)
+    : undefined
+  const output = definition.schema
+    ? requireStandardJsonSchema(definition.schema, "output", schemaSubject)
+    : undefined
+  const normalized = Object.freeze({
+    ...(definition.label !== undefined
+      ? { label: normalizedText(definition.label, "label", owner) }
+      : {}),
+    ...(definition.description !== undefined
+      ? {
+          description: normalizedText(
+            definition.description,
+            "description",
+            owner,
+          ),
+        }
+      : {}),
+    ...(definition.icon !== undefined
+      ? { icon: normalizedText(definition.icon, "icon", owner) }
+      : {}),
+    ...(definition.color !== undefined
+      ? { color: normalizedText(definition.color, "color", owner) }
+      : {}),
+    ...(definition.schema ? { schema: definition.schema } : {}),
+  })
+  if (!Object.keys(normalized).length) {
+    throw new Error(
+      `Plugin ${plugin} ${node} type ${type} must contribute presentation or a schema.`,
+    )
+  }
+  return Object.freeze({
+    type,
+    plugin,
+    definition: normalized,
+    ...(input ? { inputJsonSchema: input } : {}),
+    ...(output ? { outputJsonSchema: output } : {}),
+  })
+}
+
+function prepareProp(
+  plugin: string,
+  name: string,
+  schema: PathMXDataSchema,
+): PropContribution {
+  if (!MEMBER_ID.test(name)) {
+    throw new Error(`Plugin ${plugin} has an invalid data prop: ${name}`)
+  }
+  const subject = `Plugin ${plugin} data prop ${name}`
+  const input = requireStandardJsonSchema(schema, "input", subject)
+  const output = requireStandardJsonSchema(schema, "output", subject)
+  return Object.freeze({
+    name,
+    plugin,
+    schema,
+    inputJsonSchema: input,
+    outputJsonSchema: output,
+  })
+}
+
+function prepareQuery(
+  plugin: string,
+  name: string,
+  definition: QueryContribution,
+): RegisteredQuery {
+  if (!MEMBER_ID.test(name)) {
+    throw new Error(`Plugin ${plugin} has an invalid query name: ${name}`)
+  }
+  if (!definition || typeof definition !== "object") {
+    throw new Error(`Plugin query ${plugin}:${name} must be an object.`)
+  }
+  if (typeof definition.resolve !== "function") {
+    throw new Error(`Plugin query ${plugin}:${name} must define resolve().`)
+  }
+  const id = `${plugin}:${name}`
+  const output = requireStandardJsonSchema(
+    definition.output,
+    "output",
+    `Plugin query ${id} output`,
+  )
+  const input = definition.input
+    ? requireStandardJsonSchema(
+        definition.input,
+        "input",
+        `Plugin query ${id} input`,
+      )
+    : undefined
+  return Object.freeze({
+    id,
+    name,
+    plugin,
+    definition,
+    ...(input ? { input } : {}),
+    output,
+  })
+}
+
+function prepareAction(
+  plugin: string,
+  name: string,
+  action: ActionContribution,
+) {
+  if (!MEMBER_ID.test(name)) {
+    throw new Error(`Plugin ${plugin} has an invalid Action name: ${name}`)
+  }
+  if (typeof action !== "function") {
+    throw new Error(`Plugin Action ${plugin}:${name} must be a function.`)
+  }
+  if (action.input) {
+    requireStandardJsonSchema(
+      action.input,
+      "input",
+      `Plugin Action ${plugin}:${name} input`,
+    )
+  }
+  if (action.output) {
+    requireStandardJsonSchema(
+      action.output,
+      "output",
+      `Plugin Action ${plugin}:${name} output`,
+    )
+  }
+  return Object.freeze([`${plugin}:${name}`, action] as const)
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return (
+    value != null &&
+    (typeof value === "object" || typeof value === "function") &&
+    typeof (value as { then?: unknown }).then === "function"
+  )
+}
+
+function validate(
+  source: Source,
+  node: SourceNode,
+  plugin: string,
+  subject: string,
+  schema: StandardSchemaV1,
+  value: unknown,
+) {
+  const result = schema["~standard"].validate(value)
+  const pending = isPromiseLike(result)
+  if (pending) void Promise.resolve(result).catch(() => undefined)
+  const message = pending
+    ? "application schemas must validate authored data synchronously"
+    : result.issues?.length
+      ? formatSchemaIssues(result.issues)
+      : undefined
+  return message
+    ? new SourceDiagnosticError({
+        source: source.path,
+        plugin,
+        message: `Invalid ${subject} on ${node.path}: ${message}`,
+      })
+    : undefined
+}
+
+function report(
+  error: SourceDiagnosticError | undefined,
+  onError?: (error: unknown) => boolean,
+) {
+  if (error && !onError?.(error)) throw error
+}
+
+/** Ordered Plugin Schema registry and canonical Source/Block data validator. */
+export class SchemaRegistry {
+  private sourceContributions = new Map<string, TypeContribution[]>()
+  private blockContributions = new Map<string, TypeContribution[]>()
+  private sourceDescriptors = new Map<string, SourceType>()
+  private blockDescriptors = new Map<string, BlockType>()
+  private observedSourceDescriptors = new Map<string, SourceType>()
+  private observedBlockDescriptors = new Map<string, BlockType>()
+  private propContributions = new Map<string, PropContribution>()
+  private queryContributions = new Map<string, RegisteredQuery>()
+  private queryReferences = new WeakMap<object, RegisteredQuery>()
+  private queryDescriptions = new Map<string, QuerySchema>()
+
+  prepare(plugin: string, contribution?: SchemaContribution): PreparedSchema {
+    const sources = Object.entries(contribution?.sources ?? {}).map(
+      ([type, definition]) => prepareType("Source", plugin, type, definition),
+    )
+    const blocks = Object.entries(contribution?.blocks ?? {}).map(
+      ([type, definition]) => prepareType("Block", plugin, type, definition),
+    )
+    const props = Object.entries(contribution?.props ?? {}).map(
+      ([name, schema]) => prepareProp(plugin, name, schema),
+    )
+    const queries = Object.entries(contribution?.query ?? {}).map(
+      ([name, definition]) => prepareQuery(plugin, name, definition),
+    )
+    const actions = Object.entries(contribution?.actions ?? {}).map(
+      ([name, action]) => prepareAction(plugin, name, action),
+    )
+    for (const prop of props) {
+      const existing = this.propContributions.get(prop.name)
+      if (existing) {
+        throw new Error(
+          `Data prop ${prop.name} is already owned by Plugin ${existing.plugin}.`,
+        )
+      }
+    }
+    for (const query of queries) {
+      if (this.queryContributions.has(query.id)) {
+        throw new Error(`Duplicate Plugin query: ${query.id}`)
+      }
+    }
+    return Object.freeze({
+      sources: Object.freeze(sources),
+      blocks: Object.freeze(blocks),
+      props: Object.freeze(props),
+      queries: Object.freeze(queries),
+      actions: Object.freeze(actions),
+    })
+  }
+
+  register(prepared: PreparedSchema) {
+    this.registerTypes(
+      prepared.sources,
+      this.sourceContributions,
+      this.sourceDescriptors,
+    )
+    this.registerTypes(
+      prepared.blocks,
+      this.blockContributions,
+      this.blockDescriptors,
+    )
+    for (const contribution of prepared.props) {
+      this.propContributions.set(contribution.name, contribution)
+    }
+    for (const query of prepared.queries) {
+      this.queryContributions.set(query.id, query)
+      this.queryReferences.set(query.definition, query)
+      this.queryDescriptions.set(
+        query.id,
+        Object.freeze({
+          id: query.id,
+          plugin: query.plugin,
+          ...(query.definition.input
+            ? {
+                input: query.definition.input,
+                inputJsonSchema: query.input,
+              }
+            : {}),
+          output: query.definition.output,
+          outputJsonSchema: query.output,
+        }),
+      )
+    }
+  }
+
+  private registerTypes(
+    contributions: readonly TypeContribution[],
+    byType: Map<string, TypeContribution[]>,
+    descriptors: Map<string, NodeType>,
+  ) {
+    for (const contribution of contributions) {
+      const definitions = byType.get(contribution.type)
+      if (definitions) definitions.push(contribution)
+      else byType.set(contribution.type, [contribution])
+      descriptors.delete(contribution.type)
+    }
+  }
+
+  sourceType(sourceOrType: SourceNode | string) {
+    const type =
+      typeof sourceOrType === "string" ? sourceOrType : sourceOrType.type
+    return this.typeDescriptor(
+      type,
+      this.sourceContributions,
+      this.sourceDescriptors,
+      this.observedSourceDescriptors,
+    )
+  }
+
+  sourceTypes() {
+    return this.typeDescriptors(
+      this.sourceContributions,
+      this.observedSourceDescriptors,
+      (type) => this.sourceType(type),
+    )
+  }
+
+  blockType(blockOrType: SourceNode | string) {
+    const type =
+      typeof blockOrType === "string" ? blockOrType : blockOrType.type
+    return this.typeDescriptor(
+      type,
+      this.blockContributions,
+      this.blockDescriptors,
+      this.observedBlockDescriptors,
+    )
+  }
+
+  blockTypes() {
+    return this.typeDescriptors(
+      this.blockContributions,
+      this.observedBlockDescriptors,
+      (type) => this.blockType(type),
+    )
+  }
+
+  private typeDescriptor(
+    type: string,
+    contributionsByType: Map<string, TypeContribution[]>,
+    descriptors: Map<string, NodeType>,
+    observed: Map<string, NodeType>,
+  ) {
+    const contributions = contributionsByType.get(type)
+    if (!contributions?.length) return this.observedType(type, observed)
+    let descriptor = descriptors.get(type)
+    if (descriptor) return descriptor
+    let label: string | undefined
+    let description: string | undefined
+    let icon: string | undefined
+    let color: string | undefined
+    for (const { definition } of contributions) {
+      label = definition.label ?? label
+      description = definition.description ?? description
+      icon = definition.icon ?? icon
+      color = definition.color ?? color
+    }
+    descriptor = Object.freeze({
+      type,
+      label: label ?? titleCase(type),
+      ...(description ? { description } : {}),
+      icon: icon ?? "file-text",
+      color: color ?? "slate",
+      origin: "defined",
+      plugins: Object.freeze([
+        ...new Set(contributions.map((contribution) => contribution.plugin)),
+      ]),
+    })
+    descriptors.set(type, descriptor)
+    return descriptor
+  }
+
+  private typeDescriptors(
+    contributions: Map<string, TypeContribution[]>,
+    observed: Map<string, NodeType>,
+    resolve: (type: string) => NodeType,
+  ) {
+    const types = new Set([...contributions.keys(), ...observed.keys()])
+    return Object.freeze([...types].sort(compareText).map(resolve))
+  }
+
+  sourceSchemas(sourceOrType: SourceNode | string) {
+    const type =
+      typeof sourceOrType === "string" ? sourceOrType : sourceOrType.type
+    return this.schemas(type, this.sourceContributions)
+  }
+
+  blockSchemas(blockOrType: SourceNode | string) {
+    const type =
+      typeof blockOrType === "string" ? blockOrType : blockOrType.type
+    return this.schemas(type, this.blockContributions)
+  }
+
+  private schemas(
+    type: string,
+    contributionsByType: Map<string, TypeContribution[]>,
+  ) {
+    return Object.freeze(
+      (contributionsByType.get(type) ?? []).flatMap((contribution) =>
+        contribution.definition.schema
+          ? [
+              Object.freeze({
+                plugin: contribution.plugin,
+                schema: contribution.definition.schema,
+                inputJsonSchema: contribution.inputJsonSchema!,
+                outputJsonSchema: contribution.outputJsonSchema!,
+              }) satisfies NodeSchema,
+            ]
+          : [],
+      ),
+    )
+  }
+
+  prop(name: string) {
+    return this.propContributions.get(name)
+  }
+
+  props(node?: SourceNode) {
+    const definitions = node
+      ? Object.keys(node.data).flatMap((key) => {
+          const prop = this.propContributions.get(key)
+          return prop ? [prop] : []
+        })
+      : [...this.propContributions.values()]
+    return Object.freeze(
+      definitions.sort((left, right) => compareText(left.name, right.name)),
+    )
+  }
+
+  has(node: SourceNode, prop: string) {
+    return this.propContributions.has(prop) && Object.hasOwn(node.data, prop)
+  }
+
+  value(node: SourceNode, prop: string) {
+    return this.has(node, prop) ? node.data[prop] : undefined
+  }
+
+  registeredQuery(reference: string | QueryContribution) {
+    return typeof reference === "string"
+      ? this.queryContributions.get(reference)
+      : this.queryReferences.get(reference)
+  }
+
+  queries() {
+    return Object.freeze(
+      [...this.queryContributions.values()].sort((left, right) =>
+        compareText(left.id, right.id),
+      ),
+    )
+  }
+
+  querySchema(id: string) {
+    return this.queryDescriptions.get(id)
+  }
+
+  querySchemas() {
+    return Object.freeze(
+      [...this.queryDescriptions.values()].sort((left, right) =>
+        compareText(left.id, right.id),
+      ),
+    )
+  }
+
+  sourceTypeContributions(type?: string) {
+    return type
+      ? Object.freeze([...(this.sourceContributions.get(type) ?? [])])
+      : Object.freeze([...this.sourceContributions.values()].flat())
+  }
+
+  blockTypeContributions(type?: string) {
+    return type
+      ? Object.freeze([...(this.blockContributions.get(type) ?? [])])
+      : Object.freeze([...this.blockContributions.values()].flat())
+  }
+
+  sourceDataSchemas(type?: string) {
+    return Object.freeze(
+      this.sourceTypeContributions(type).flatMap((entry) =>
+        entry.outputJsonSchema ? [entry.outputJsonSchema] : [],
+      ),
+    )
+  }
+
+  blockDataSchemas(type?: string) {
+    return Object.freeze(
+      this.blockTypeContributions(type).flatMap((entry) =>
+        entry.outputJsonSchema ? [entry.outputJsonSchema] : [],
+      ),
+    )
+  }
+
+  propDataSchema(name: string) {
+    return this.propContributions.get(name)?.outputJsonSchema
+  }
+
+  index(source: Source, onError?: (error: unknown) => boolean) {
+    this.sourceType(source)
+    for (const { plugin, definition } of this.sourceContributions.get(
+      source.type,
+    ) ?? []) {
+      if (!definition.schema) continue
+      report(
+        validate(
+          source,
+          source,
+          plugin,
+          `${source.type} Source`,
+          definition.schema,
+          source.data,
+        ),
+        onError,
+      )
+    }
+
+    for (const block of source.blocks) {
+      this.blockType(block)
+      for (const { plugin, definition } of this.blockContributions.get(
+        block.type,
+      ) ?? []) {
+        if (!definition.schema) continue
+        report(
+          validate(
+            source,
+            block,
+            plugin,
+            `${block.type} Block`,
+            definition.schema,
+            block.data,
+          ),
+          onError,
+        )
+      }
+    }
+
+    if (!this.propContributions.size) return
+    for (const node of [source, ...source.blocks]) {
+      for (const key of Object.keys(node.data)) {
+        const prop = this.propContributions.get(key)
+        if (!prop) continue
+        report(
+          validate(
+            source,
+            node,
+            prop.plugin,
+            `${key} prop`,
+            prop.schema,
+            node.data[key],
+          ),
+          onError,
+        )
+      }
+    }
+  }
+
+  private observedType(type: string, observed: Map<string, NodeType>) {
+    let descriptor = observed.get(type)
+    if (!descriptor) {
+      descriptor = Object.freeze({
+        type,
+        label: titleCase(type),
+        icon: "file-text",
+        color: "slate",
+        origin: "observed",
+        plugins: Object.freeze([]),
+      })
+      observed.set(type, descriptor)
+    }
+    return descriptor
+  }
+}
+
+/** @internal Expose only stable Schema queries outside the Plugin host. */
+export function applicationSchemaView(
+  registry: SchemaRegistry,
+): ApplicationSchema {
+  return Object.freeze({
+    sourceType: registry.sourceType.bind(registry),
+    sourceTypes: registry.sourceTypes.bind(registry),
+    blockType: registry.blockType.bind(registry),
+    blockTypes: registry.blockTypes.bind(registry),
+    sourceSchemas: registry.sourceSchemas.bind(registry),
+    blockSchemas: registry.blockSchemas.bind(registry),
+    query: registry.querySchema.bind(registry),
+    queries: registry.querySchemas.bind(registry),
+    prop: registry.prop.bind(registry),
+    props: registry.props.bind(registry),
+    has: registry.has.bind(registry),
+    value: registry.value.bind(registry),
+  })
+}