@pathmx/core 0.5.0

package/source/topmatter.ts

@@ -0,0 +1,57 @@
+import type { PathMXYaml } from "../environment.ts"
+
+export type Topmatter = Record<string, unknown>
+
+/** @internal Identifies failures raised while decoding an authored YAML map. */
+export class YamlMapParseError extends Error {
+  constructor(cause: unknown) {
+    super(cause instanceof Error ? cause.message : String(cause), { cause })
+    this.name = "YamlMapParseError"
+  }
+}
+
+export function parseYamlMap(text: string, yaml: PathMXYaml): Topmatter {
+  let parsed: unknown
+  try {
+    parsed = yaml.parse(text)
+  } catch (error) {
+    throw new YamlMapParseError(error)
+  }
+  return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+    ? (parsed as Topmatter)
+    : {}
+}
+
+function emptySplit(body: string) {
+  return { data: {} as Topmatter, body }
+}
+
+/** YAML frontmatter: a leading `---` … `---` map. */
+export function splitFrontmatter(content: string, yaml?: PathMXYaml) {
+  const match = content.match(
+    /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/,
+  )
+  if (!match) return emptySplit(content)
+  if (!yaml) throw new Error("A YAML codec is required to parse frontmatter.")
+  return {
+    data: parseYamlMap(match[1]!, yaml),
+    body: content.slice(match[0].length),
+  }
+}
+
+function startsWithTopmatterKey(comment: string) {
+  const firstContentLine = comment
+    .split(/\r?\n/)
+    .find((line) => line.trim() && !line.trimStart().startsWith("#"))
+  return /^[ \t]*[A-Za-z0-9_.-]+:[ \t]*/.test(firstContentLine ?? "")
+}
+
+/** HTML-comment topmatter: `<!-- id: x -->` or a multiline `<!-- ... -->` YAML map. */
+export function splitTopmatter(content: string, yaml?: PathMXYaml) {
+  const match = content.match(/^\s*<!--([\s\S]*?)-->/)
+  if (!match?.[1] || !startsWithTopmatterKey(match[1])) return emptySplit(content)
+  if (!yaml) throw new Error("A YAML codec is required to parse topmatter.")
+  const data = parseYamlMap(match[1], yaml)
+  if (!Object.keys(data).length) return emptySplit(content)
+  return { data, body: content.slice(match[0].length) }
+}

package/source/utils.ts

@@ -0,0 +1,21 @@
+export type SourcePathNameMeta = Readonly<{
+  name: string
+  typeHint?: string
+  qualifiers: readonly string[]
+}>
+
+// Remove the format extension, then interpret the dot-delimited filename stem
+// as `name[.qualifier...].type`.
+export function parseSourceTypeAndQualifiers(path: string): SourcePathNameMeta {
+  const basename = path.split("/").filter(Boolean).at(-1) ?? path
+  const filenameStem = basename.replace(/\.[^.]+$/, "")
+  const segments = filenameStem.split(".").filter(Boolean)
+  const typeHint = segments.length > 1 ? segments.at(-1) : undefined
+  const qualifiers = segments.length > 2 ? segments.slice(1, -1) : []
+  const name = (segments[0] ?? filenameStem).trim()
+  return {
+    name,
+    typeHint,
+    qualifiers,
+  }
+}

package/source-diagnostic.ts

@@ -0,0 +1,63 @@
+import type { Log } from "./log.ts"
+
+export type SourceDiagnostic = Readonly<{
+  source: string
+  plugin: string
+  message: string
+}>
+
+export type SourceDiagnosticMode = "throw" | "collect"
+
+/** Expected authoring failure that lint can collect without hiding code bugs. */
+export class SourceDiagnosticError extends Error {
+  readonly diagnostic: SourceDiagnostic
+
+  constructor(diagnostic: SourceDiagnostic) {
+    super(diagnostic.message)
+    this.name = "SourceDiagnosticError"
+    this.diagnostic = diagnostic
+  }
+}
+
+/** Index-time diagnostic policy and stable per-Source results. */
+export class SourceDiagnostics {
+  private sources = new Map<string, Map<string, SourceDiagnostic>>()
+
+  constructor(
+    private mode: SourceDiagnosticMode,
+    private log: Log,
+  ) {}
+
+  delete(sourcePath: string) {
+    this.sources.delete(sourcePath)
+  }
+
+  capture(error: unknown) {
+    if (this.mode !== "collect" || !(error instanceof SourceDiagnosticError)) {
+      return false
+    }
+    const diagnostic = error.diagnostic
+    let source = this.sources.get(diagnostic.source)
+    if (!source) {
+      source = new Map()
+      this.sources.set(diagnostic.source, source)
+    }
+    const key = `${diagnostic.plugin}\0${diagnostic.message}`
+    if (!source.has(key)) {
+      source.set(key, diagnostic)
+      this.log.error("source.invalid", diagnostic)
+    }
+    return true
+  }
+
+  all(): readonly SourceDiagnostic[] {
+    return [...this.sources.values()]
+      .flatMap((source) => [...source.values()])
+      .sort(
+        (a, b) =>
+          a.source.localeCompare(b.source) ||
+          a.plugin.localeCompare(b.plugin) ||
+          a.message.localeCompare(b.message),
+      )
+  }
+}

package/text-file.ts

@@ -0,0 +1,26 @@
+import type { PathMXStorage } from "./environment.ts"
+
+export type TextFileState =
+  Readonly<{ type: "missing" }> | Readonly<{ type: "present"; content: string }>
+
+const missing: TextFileState = Object.freeze({ type: "missing" })
+
+/** Capture the text state used for optimistic storage conflict checks. */
+export async function readTextFileState(
+  storage: PathMXStorage,
+  path: string,
+): Promise<TextFileState> {
+  if (!(await storage.exists(path))) return missing
+  return Object.freeze({
+    type: "present",
+    content: await storage.readText(path),
+  })
+}
+
+export function sameTextFileState(left: TextFileState, right: TextFileState) {
+  return (
+    left.type === right.type &&
+    (left.type === "missing" ||
+      (right.type === "present" && left.content === right.content))
+  )
+}

package/util.ts

@@ -0,0 +1,35 @@
+export function asList(value: unknown) {
+  if (Array.isArray(value)) return value.map(String).filter(Boolean);
+  if (value == null || value === "") return [];
+  return [String(value)];
+}
+
+export function escapeHtml(value: string) {
+  return value
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+}
+
+/** Reverse `escapeHtml`, plus named/numeric character references. */
+export function decodeHtmlEntities(value: string) {
+  if (!value.includes("&")) return value
+  return value
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;|&apos;/g, "'")
+    .replace(/&#x([0-9a-f]+);/gi, (_match, hex: string) =>
+      String.fromCodePoint(parseInt(hex, 16)),
+    )
+    .replace(/&#(\d+);/g, (_match, dec: string) =>
+      String.fromCodePoint(Number(dec)),
+    )
+    .replace(/&amp;/g, "&")
+}
+
+export function fileStem(path: string, suffix: string) {
+  const base = path.split("/").pop() ?? "";
+  return base.endsWith(suffix) ? base.slice(0, -suffix.length) : undefined;
+}

package/view/components.ts

@@ -0,0 +1,499 @@
+import type { Engine } from "../host/engine.ts"
+import { html, stringifyHtml, type Html } from "../html.ts"
+import type {
+  AppContext,
+  AuthoredDataComponent,
+  AnyViewComponent,
+  CompileContext,
+  PageContext,
+  Plugin,
+  ViewComponentUse,
+  ViewContext,
+  ViewVariable,
+} from "../plugins/types.ts"
+import type { Source } from "../source/index.ts"
+import {
+  formatSchemaIssues,
+  requireStandardJsonSchema,
+  type StandardSchemaV1,
+} from "../schema/standard.ts"
+import type { HtmlStringRewrite } from "../environment.ts"
+import { parseHtmlAttributes } from "../html-attributes.ts"
+import {
+  authoredViewTag,
+  compileViewUses,
+  COMPONENT_ORIGIN_ATTR,
+  hasRemainingViewUse,
+  isAuthoredViewTag,
+  isLiterateComponentTag,
+  isViewComponentTag,
+  stampComponentRoot,
+  stripComponentOrigins,
+  ViewComponentSyntax,
+  viewUsePattern,
+  VIEW_NAME_ATTR,
+  VIEW_SLOT_ATTR,
+  VIEW_USE_TAG,
+} from "./syntax.ts"
+
+type RegisteredView = {
+  plugin: string
+  tag: string
+  authoredTag?: string
+  props?: StandardSchemaV1
+  data?: StandardSchemaV1
+  available?: (origin: Source) => boolean
+  compile?: (
+    use: ViewComponentUse,
+    ctx: PageContext,
+    app: AppContext,
+  ) => unknown | Promise<unknown>
+  render: (
+    use: ViewComponentUse,
+    compiled: unknown,
+    ctx: ViewContext,
+    app: AppContext,
+  ) => Html | Promise<Html>
+}
+
+type CompiledView = {
+  marker: string
+  view: RegisteredView
+  use: ViewComponentUse
+  compiled: unknown
+}
+
+type ViewSegment = string | CompiledView
+
+export type CompiledViewPlan = Readonly<{
+  html: string
+  segments: readonly ViewSegment[]
+}>
+
+function viewPlan(
+  html: string,
+  compiled: readonly CompiledView[],
+): CompiledViewPlan {
+  const byMarker = new Map(compiled.map((item) => [item.marker, item]))
+  const segments: ViewSegment[] = []
+  let cursor = 0
+  let found = 0
+  for (const match of html.matchAll(
+    /<template data-pmx-view-slot="[a-z0-9]+-[a-z0-9]+"><\/template>/g,
+  )) {
+    const item = byMarker.get(match[0])
+    if (!item) continue
+    if (match.index > cursor) segments.push(html.slice(cursor, match.index))
+    segments.push(item)
+    cursor = match.index + match[0].length
+    found++
+  }
+  if (found !== compiled.length) {
+    throw new Error("Compiled view slots do not match compiled HTML.")
+  }
+  if (cursor < html.length) segments.push(html.slice(cursor))
+  return { html, segments }
+}
+
+function registeredView(
+  plugin: string,
+  view: AnyViewComponent,
+): RegisteredView {
+  const client = view.client
+  const compile = client
+    ? async (use: ViewComponentUse, ctx: PageContext, app: AppContext) => {
+        const [compiled] = await Promise.all([
+          view.compile?.(use, ctx, app),
+          ctx.addBrowserBundle(client, view.tag),
+        ])
+        return compiled
+      }
+    : view.compile
+  return {
+    plugin,
+    tag: view.tag,
+    authoredTag: authoredViewTag(view.tag),
+    props: view.props,
+    data: view.data,
+    compile,
+    render: (use, compiled, ctx, env) => view.render(use, compiled, ctx, env),
+  }
+}
+
+function registeredVariable(plugin: string, variable: ViewVariable) {
+  const tag = `${variable.namespace}:$variable`
+  const view: RegisteredView = {
+    plugin,
+    tag,
+    render: async (use, _compiled, ctx, env) => {
+      const path = use.props["data-pmx-variable"]?.split(".") ?? []
+      const value = await variable.render(
+        { path, origin: use.origin },
+        ctx,
+        env,
+      )
+      return html`${value}`
+    },
+  }
+  return view
+}
+
+async function validateProps(view: RegisteredView, use: ViewComponentUse) {
+  if (!view.props) return
+  let result = view.props["~standard"].validate(use.props)
+  if (result instanceof Promise) result = await result
+  if (!result.issues) return
+  throw new Error(
+    `Invalid <${view.authoredTag ?? view.tag}> props in ${use.origin.path}: ${formatSchemaIssues(result.issues)}`,
+  )
+}
+
+async function validatedData(view: RegisteredView, data: unknown) {
+  if (!view.data) return data
+  let result = view.data["~standard"].validate(data)
+  if (result instanceof Promise) result = await result
+  if (!result.issues) return result.value
+  throw new Error(
+    `Invalid <${view.authoredTag ?? view.tag}> data: ${formatSchemaIssues(result.issues)}`,
+  )
+}
+
+export class ViewComponentRegistry {
+  private views = new Map<string, RegisteredView>()
+  private authoredViews = new Map<string, RegisteredView>()
+  private variableNamespaces = new Set<string>()
+  private dataViews = new Map<string, RegisteredView & { owner: string }>()
+  private dataViewsByOwner = new Map<string, Set<string>>()
+  private syntax = new ViewComponentSyntax()
+  private generation = 0
+
+  has(tag: string) {
+    return this.views.has(tag) || this.authoredViews.has(tag)
+  }
+
+  compileVariables(markdown: string, _ctx: CompileContext) {
+    return this.syntax.compileVariables(markdown)
+  }
+
+  compileSyntax(markdown: string, ctx: CompileContext) {
+    return this.syntax.compile(markdown, ctx)
+  }
+
+  restoreSyntax(html: string, ctx: CompileContext) {
+    return this.syntax.restore(html, ctx)
+  }
+
+  register(plugin: Plugin) {
+    const pending = new Map<string, RegisteredView>()
+    const pendingAuthored = new Map<string, RegisteredView>()
+    const pendingVariables = new Map<string, RegisteredView>()
+    for (const view of plugin.components ?? []) {
+      const tag = view.tag
+      if (!isViewComponentTag(tag)) {
+        throw new Error(`Invalid View Component tag: ${tag}`)
+      }
+      if (!tag.startsWith(`${plugin.id}:`)) {
+        throw new Error(
+          `View Component <${tag}> must use the ${plugin.id}: namespace.`,
+        )
+      }
+      if (pending.has(tag) || this.views.has(tag)) {
+        throw new Error(`Duplicate View Component tag: ${tag}`)
+      }
+      if (view.data) {
+        requireStandardJsonSchema(
+          view.data,
+          "input",
+          `View Component <${tag}> data`,
+        )
+        requireStandardJsonSchema(
+          view.data,
+          "output",
+          `View Component <${tag}> data`,
+        )
+      }
+      const registered = registeredView(plugin.id, view)
+      const authoredTag = registered.authoredTag!
+      if (!isAuthoredViewTag(authoredTag)) {
+        throw new Error(`Invalid authored View Component tag: ${authoredTag}`)
+      }
+      if (
+        pendingAuthored.has(authoredTag) ||
+        this.authoredViews.has(authoredTag)
+      ) {
+        throw new Error(`Duplicate authored View Component tag: ${authoredTag}`)
+      }
+      pending.set(tag, registered)
+      pendingAuthored.set(authoredTag, registered)
+    }
+    for (const variable of plugin.variables ?? []) {
+      const namespace = variable.namespace
+      if (namespace !== plugin.id) {
+        throw new Error(
+          `View Variable {{ ${namespace}.* }} must use the ${plugin.id} namespace.`,
+        )
+      }
+      if (
+        pendingVariables.has(namespace) ||
+        this.variableNamespaces.has(namespace)
+      ) {
+        throw new Error(`Duplicate View Variable namespace: ${namespace}`)
+      }
+      pendingVariables.set(namespace, registeredVariable(plugin.id, variable))
+    }
+    for (const [tag, view] of pending) this.views.set(tag, view)
+    for (const [tag, view] of pendingAuthored) this.authoredViews.set(tag, view)
+    for (const [namespace, view] of pendingVariables) {
+      this.variableNamespaces.add(namespace)
+      this.views.set(view.tag, view)
+    }
+    this.syntax.registerVariables(
+      [...pendingVariables].map(
+        ([namespace, view]) => [namespace, view.tag] as const,
+      ),
+    )
+  }
+
+  replaceAuthored(sourcePath: string, tags: Iterable<string>) {
+    this.syntax.replaceAuthored(sourcePath, tags)
+  }
+
+  deleteAuthored(sourcePath: string) {
+    this.syntax.deleteAuthored(sourcePath)
+    for (const tag of this.dataViewsByOwner.get(sourcePath) ?? []) {
+      this.dataViews.delete(tag)
+    }
+    this.dataViewsByOwner.delete(sourcePath)
+  }
+
+  replaceData(
+    plugin: string,
+    sourcePath: string,
+    definitions: Iterable<AuthoredDataComponent>,
+  ) {
+    const pending = [...definitions]
+    const tags = new Set<string>()
+    for (const definition of pending) {
+      if (!isLiterateComponentTag(definition.tag)) {
+        throw new Error(`Invalid authored data component: ${definition.tag}`)
+      }
+      if (tags.has(definition.tag)) {
+        throw new Error(`Duplicate authored data component: ${definition.tag}`)
+      }
+      const existing = this.dataViews.get(definition.tag)
+      if (existing && existing.owner !== sourcePath) {
+        throw new Error(
+          `Duplicate authored data component <${definition.tag}> in ${sourcePath} and ${existing.owner}.`,
+        )
+      }
+      tags.add(definition.tag)
+    }
+    for (const tag of this.dataViewsByOwner.get(sourcePath) ?? []) {
+      this.dataViews.delete(tag)
+    }
+    for (const definition of pending) {
+      this.dataViews.set(definition.tag, {
+        plugin,
+        owner: sourcePath,
+        tag: definition.tag,
+        available: definition.available,
+        compile: definition.compile
+          ? (_use, ctx, app) => definition.compile!(_use.origin, ctx, app)
+          : undefined,
+        render: (use, compiled, ctx, app) =>
+          definition.render(
+            use as ViewComponentUse<unknown>,
+            compiled,
+            ctx,
+            app,
+          ),
+      })
+    }
+    this.dataViewsByOwner.set(sourcePath, tags)
+  }
+
+  hasAny(tags: ReadonlySet<string> | undefined) {
+    if (!tags?.size) return false
+    for (const tag of tags) {
+      if (this.authoredViews.has(tag) || this.syntax.has(tag)) return true
+    }
+    return false
+  }
+
+  async prepareData(
+    tag: string,
+    props: Readonly<Record<string, string>>,
+    origin: Source,
+    ctx: PageContext,
+    env: Engine,
+  ) {
+    const view =
+      this.views.get(tag) ??
+      this.authoredViews.get(tag) ??
+      this.dataViews.get(tag)
+    if (!view || view.available?.(origin) === false) {
+      throw new Error(`Unknown data component <${tag}> in ${origin.path}.`)
+    }
+    if (!this.dataViews.has(tag) && !view.data) {
+      throw new Error(
+        `View Component <${view.authoredTag ?? tag}> does not declare data.`,
+      )
+    }
+    const use: ViewComponentUse = { props: Object.freeze({ ...props }), origin }
+    await validateProps(view, use)
+    const compiled = view.compile
+      ? await view.compile(use, ctx, env.appContext(view.plugin))
+      : undefined
+    return Object.freeze({ view, use, compiled })
+  }
+
+  async renderData(
+    prepared: unknown,
+    data: unknown,
+    ctx: ViewContext,
+    env: Engine,
+  ) {
+    const item = prepared as Readonly<{
+      view: RegisteredView
+      use: ViewComponentUse
+      compiled: unknown
+    }>
+    if (!item?.view || !item.use) throw new Error("Invalid prepared component.")
+    const value = await validatedData(item.view, data)
+    const app = env.appContext(item.view.plugin)
+    const rendered = await item.view.render(
+      { ...item.use, data: value } as ViewComponentUse<any>,
+      item.compiled,
+      Object.freeze({ ...ctx, database: app.database }),
+      app,
+    )
+    return stampComponentRoot(
+      stringifyHtml(rendered),
+      item.view.tag,
+      env.environment.rewriteHtml,
+    )
+  }
+
+  stampOrigins(
+    html: string,
+    originPath: string,
+    rewriteHtml: HtmlStringRewrite,
+  ) {
+    return this.syntax.stampOrigins(html, originPath, rewriteHtml)
+  }
+
+  async compile(html: string, source: Source, ctx: PageContext, env: Engine) {
+    html = compileViewUses(html, source.path)
+    if (!html.includes(`<${VIEW_USE_TAG}`)) {
+      return {
+        html: stripComponentOrigins(html),
+        plan: undefined,
+      }
+    }
+
+    const compiledViews: CompiledView[] = []
+    const generation = (this.generation++).toString(36)
+    const pattern = viewUsePattern()
+    let cursor = 0
+    let output = ""
+    let match: RegExpExecArray | null
+    while ((match = pattern.exec(html))) {
+      output += html.slice(cursor, match.index)
+      const attrs = parseHtmlAttributes(match[1])
+      const tag = attrs[VIEW_NAME_ATTR] ?? ""
+      delete attrs[VIEW_NAME_ATTR]
+      const view = this.views.get(tag) ?? this.authoredViews.get(tag)
+      if (!view) {
+        throw new Error(`Unknown View Component <${tag}> in ${source.path}.`)
+      }
+      const originPath = attrs[COMPONENT_ORIGIN_ATTR]
+      delete attrs[COMPONENT_ORIGIN_ATTR]
+      const origin =
+        (originPath && env.appContext(view.plugin).sources.get(originPath)) ||
+        source
+      const use: ViewComponentUse = {
+        props: Object.freeze(attrs),
+        origin,
+      }
+      await validateProps(view, use)
+      const start = performance.now()
+      let compiled: unknown
+      try {
+        compiled = view.compile
+          ? await view.compile(use, ctx, env.appContext(view.plugin))
+          : undefined
+      } finally {
+        env.perf.record(
+          `${view.plugin}.view.compile`,
+          performance.now() - start,
+          `${source.path} <${view.tag}>`,
+        )
+      }
+      const marker = `<template ${VIEW_SLOT_ATTR}="${generation}-${compiledViews.length.toString(36)}"></template>`
+      compiledViews.push({ marker, view, use, compiled })
+      output += marker
+      cursor = pattern.lastIndex
+    }
+    html = output + html.slice(cursor)
+    if (hasRemainingViewUse(html)) {
+      throw new Error(`Invalid compiled View Component use in ${source.path}.`)
+    }
+    html = stripComponentOrigins(html)
+    return {
+      html,
+      plan: compiledViews.length ? viewPlan(html, compiledViews) : undefined,
+    }
+  }
+
+  async renderSegments(
+    html: string,
+    plan: CompiledViewPlan | undefined,
+    ctx: ViewContext,
+    env: Engine,
+  ) {
+    if (!plan) return [html]
+    const pageAt = html.indexOf(plan.html)
+    if (pageAt === -1) {
+      throw new Error("Compiled view page does not match rendered HTML.")
+    }
+    const output: string[] = []
+    if (pageAt) output.push(html.slice(0, pageAt))
+    for (const segment of plan.segments) {
+      if (typeof segment === "string") {
+        output.push(segment)
+        continue
+      }
+      const start = performance.now()
+      let rendered: Html
+      try {
+        const appContext = env.appContext(segment.view.plugin)
+        const viewContext = Object.freeze({
+          ...ctx,
+          database: appContext.database,
+        })
+        rendered = await segment.view.render(
+          segment.use,
+          segment.compiled,
+          viewContext,
+          appContext,
+        )
+      } finally {
+        env.perf.record(
+          `${segment.view.plugin}.view.render`,
+          performance.now() - start,
+          `${ctx.source.path} <${segment.view.tag}>`,
+        )
+      }
+      output.push(
+        stampComponentRoot(
+          stringifyHtml(rendered),
+          segment.view.tag,
+          env.environment.rewriteHtml,
+        ),
+      )
+    }
+    const pageEnd = pageAt + plan.html.length
+    if (pageEnd < html.length) output.push(html.slice(pageEnd))
+    return output
+  }
+}