@pathmx/core 0.5.0

package/server/routes.ts

@@ -0,0 +1,202 @@
+import type { Engine } from "../host/engine.ts"
+import type { Plugin, ServerRoute } from "../plugins/types.ts"
+import { createServerContext } from "./context.ts"
+import { protocolRoute } from "./protocols.ts"
+
+type RegisteredRoute = ServerRoute & {
+  plugin: string
+  relative: string
+  prefix?: string
+}
+
+const API_ROOT = "/api"
+
+const METHOD_ORDER = [
+  "GET",
+  "HEAD",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+  "OPTIONS",
+] as const
+const ROUTE_METHODS = new Set([
+  "GET",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+  "OPTIONS",
+  "*",
+])
+
+function canonicalRoutePath(path: string) {
+  if (path.startsWith("/") || path.includes("?") || path.includes("#")) {
+    throw new Error(`Invalid server route path: ${path}`)
+  }
+  const wildcard = path === "*" || path.endsWith("/*")
+  const base = path === "*" ? "" : wildcard ? path.slice(0, -2) : path
+  if (base.includes("*") || base.includes("\\") || /%2f|%5c/i.test(base)) {
+    throw new Error(`Invalid server route path: ${path}`)
+  }
+  const mounted = `${API_ROOT}/${base}`
+  const url = new URL(mounted, "http://pathmx.local")
+  if (
+    url.pathname !== mounted ||
+    url.search ||
+    url.hash ||
+    base.split("/").includes("..")
+  ) {
+    throw new Error(`Invalid server route path: ${path}`)
+  }
+  return wildcard ? (base ? `${base}/*` : "*") : base
+}
+
+function mountedRoute(plugin: string, path: string) {
+  const suffix = path ? `/${path}` : ""
+  return `${API_ROOT}/${plugin}${suffix}`
+}
+
+function relativeRequestPath(plugin: string, pathname: string) {
+  const root = `${API_ROOT}/${plugin}`
+  return pathname === root ? "" : pathname.slice(root.length + 1)
+}
+
+function prefixFor(path: string) {
+  return path.endsWith("/*") ? path.slice(0, -1) : undefined
+}
+
+function methodsOverlap(a: ServerRoute["method"], b: ServerRoute["method"]) {
+  return a === "*" || b === "*" || a === b
+}
+
+function pathsOverlap(a: RegisteredRoute, b: RegisteredRoute) {
+  const aPrefix = a.prefix
+  const bPrefix = b.prefix
+  if (!aPrefix && !bPrefix) return a.path === b.path
+  if (aPrefix && bPrefix) {
+    return aPrefix.startsWith(bPrefix) || bPrefix.startsWith(aPrefix)
+  }
+  if (aPrefix) return b.path.startsWith(aPrefix)
+  if (bPrefix) return a.path.startsWith(bPrefix)
+  return false
+}
+
+function overlapMessage(a: RegisteredRoute, b: RegisteredRoute) {
+  return `Overlapping server routes: ${a.method} ${a.path} (${a.plugin}) and ${b.method} ${b.path} (${b.plugin})`
+}
+
+function withoutBody(response: Response) {
+  return new Response(null, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers,
+  })
+}
+
+export class ServerRouteRegistry {
+  private routes: RegisteredRoute[] = []
+  private exact = new Map<string, RegisteredRoute[]>()
+  private prefixes: RegisteredRoute[] = []
+
+  prepare(plugin: Plugin) {
+    const pending = (plugin.routes ?? []).map((route) => {
+      if (!ROUTE_METHODS.has(route.method)) {
+        throw new Error(`Invalid server route method: ${route.method}`)
+      }
+      const relative = canonicalRoutePath(route.path)
+      const path = mountedRoute(plugin.id, relative)
+      return {
+        ...route,
+        path,
+        relative,
+        plugin: plugin.id,
+        prefix: prefixFor(path),
+      } satisfies RegisteredRoute
+    })
+    const candidates = [...this.routes]
+    for (const route of pending) {
+      for (const existing of candidates) {
+        if (
+          pathsOverlap(route, existing) &&
+          (route.path !== existing.path ||
+            methodsOverlap(route.method, existing.method))
+        ) {
+          throw new Error(overlapMessage(existing, route))
+        }
+      }
+      candidates.push(route)
+    }
+    return pending
+  }
+
+  register(routes: readonly RegisteredRoute[]) {
+    for (const route of routes) {
+      this.routes.push(route)
+      if (route.prefix) {
+        this.prefixes.push(route)
+        continue
+      }
+      const exact = this.exact.get(route.path) ?? []
+      exact.push(route)
+      this.exact.set(route.path, exact)
+    }
+  }
+
+  async dispatch(
+    request: Request,
+    url: URL,
+    app: Engine,
+    publicUrl: URL = url,
+  ) {
+    const pathname = protocolRoute(url.pathname) ?? url.pathname
+    const exact = this.exact.get(pathname)
+    const matches = exact ? [...exact] : []
+    if (!exact) {
+      for (const route of this.prefixes) {
+        const prefix = route.prefix
+        if (prefix && pathname.startsWith(prefix)) matches.push(route)
+      }
+    }
+    if (!matches.length) return
+
+    const method = request.method.toUpperCase()
+    const route = matches.find(
+      (candidate) =>
+        candidate.method === "*" ||
+        candidate.method === method ||
+        (method === "HEAD" && candidate.method === "GET"),
+    )
+    if (!route) {
+      const allowed = new Set(
+        matches.flatMap((candidate) =>
+          candidate.method === "GET" ? ["GET", "HEAD"] : [candidate.method],
+        ),
+      )
+      return new Response("Method Not Allowed", {
+        status: 405,
+        headers: {
+          Allow: METHOD_ORDER.filter((candidate) =>
+            allowed.has(candidate),
+          ).join(", "),
+        },
+      })
+    }
+
+    const response = await app.perf.measureAsync(
+      `route.${route.plugin}`,
+      async () =>
+        route.handle(
+          createServerContext(
+            app,
+            route.plugin,
+            relativeRequestPath(route.plugin, pathname),
+            request,
+            publicUrl,
+          ),
+        ),
+      route.path,
+    )
+    return method === "HEAD" ? withoutBody(response) : response
+  }
+}

package/server/serve.ts

@@ -0,0 +1,5 @@
+import { join } from "node:path"
+import { startServer } from "../cli/serve.ts"
+
+const PATHS_ROOT = join(import.meta.dir, "..", "..", "paths")
+await startServer({ root: PATHS_ROOT })

package/server/watch.ts

@@ -0,0 +1,120 @@
+import watcher from "@parcel/watcher"
+import { realpathSync } from "node:fs"
+import { relative } from "node:path"
+import type { Engine } from "../host/engine.ts"
+import { SourceDiagnosticError } from "../source-diagnostic.ts"
+import { CssImportIndex } from "./css-imports.ts"
+
+type UnresolvedLink = {
+  source: string
+  href: string
+  target?: string
+}
+
+function unresolvedLinks(app: Engine) {
+  const unresolved = new Map<string, UnresolvedLink>()
+  for (const edge of app.graph.unresolvedLinks()) {
+    const key = `${edge.from}\0${edge.href}`
+    unresolved.set(key, {
+      source: edge.from,
+      href: edge.href,
+      target: edge.to,
+    })
+  }
+  return unresolved
+}
+
+function reportLinkChanges(
+  app: Engine,
+  previous?: ReadonlyMap<string, UnresolvedLink>,
+) {
+  const current = unresolvedLinks(app)
+  for (const [key, link] of current) {
+    if (previous?.has(key)) continue
+    app.log.warn("link.unresolved", link)
+  }
+  if (previous) {
+    for (const [key, link] of previous) {
+      if (current.has(key)) continue
+      app.log.info("link.resolved", { source: link.source, href: link.href })
+    }
+  }
+  return current
+}
+
+export function watchPaths(app: Engine, root: string) {
+  const base = realpathSync(root)
+  const cssImports = new CssImportIndex()
+  let queue = Promise.resolve()
+  let unresolved = reportLinkChanges(app)
+
+  const indexStylesheet = async (rel: string) => {
+    const path = app.repo.graphPath(rel)
+    const storagePath = app.repo.storagePath(path)
+    if (!storagePath) return cssImports.replace(path)
+    try {
+      cssImports.replace(
+        path,
+        await app.environment.storage.readText(storagePath),
+      )
+    } catch {
+      cssImports.replace(path)
+    }
+  }
+
+  const initializeStylesheets = async () => {
+    const files = [...(await app.environment.storage.list(base))].filter(
+      (file) => file.endsWith(".css"),
+    )
+    for (let start = 0; start < files.length; start += 16) {
+      await Promise.all(files.slice(start, start + 16).map(indexStylesheet))
+    }
+  }
+
+  const enqueue = (work: () => Promise<void>) => {
+    queue = queue.then(work).catch((error: Error) => {
+      if (error instanceof SourceDiagnosticError) {
+        app.log.error("source.invalid", error.diagnostic)
+        return
+      }
+      app.log.error("watch.error", { message: error.message })
+    })
+  }
+
+  const subscription = initializeStylesheets().then(() =>
+    watcher.subscribe(base, (error, events) => {
+      if (error) {
+        app.log.error("watch.error", { message: error.message })
+        return
+      }
+      enqueue(async () => {
+        const changedStyles = new Set<string>()
+        for (const event of events) {
+          const rel = relative(base, event.path)
+          if (!rel || rel.startsWith("..")) continue
+          app.log.debug("watch", { file: rel, type: event.type })
+          if (rel.endsWith(".md")) await app.syncFromStorage(rel)
+          else if (rel.endsWith(".css")) {
+            await indexStylesheet(rel)
+            for (const path of cssImports.affected(app.repo.graphPath(rel))) {
+              changedStyles.add(path)
+            }
+          } else if (rel.endsWith(".js")) app.invalidateAsset(rel)
+        }
+        if (changedStyles.size) app.invalidateAssets(changedStyles)
+        unresolved = reportLinkChanges(app, unresolved)
+      })
+    }),
+  )
+  subscription.catch((error: Error) =>
+    app.log.error("watch.error", { message: error.message }),
+  )
+
+  return {
+    subscription,
+    async close() {
+      const sub = await subscription.catch(() => undefined)
+      await sub?.unsubscribe()
+    },
+  }
+}

package/source/blocks.ts

@@ -0,0 +1,71 @@
+import { parseLinkFragments } from "./markdown/links.ts"
+import { parseMarkdownLists } from "./markdown/lists.ts"
+import { scanMarkdownStructure } from "./markdown/scan.ts"
+import type { PathMXYaml } from "../environment.ts"
+import { SourceDiagnosticError } from "../source-diagnostic.ts"
+import type { Source, SourceNode } from "./source.ts"
+import {
+  splitTopmatter,
+  type Topmatter,
+  YamlMapParseError,
+} from "./topmatter.ts"
+
+export type SourceBlock = SourceNode
+
+function authoredType(data: Topmatter) {
+  return typeof data.type === "string" && data.type.trim()
+    ? data.type.trim()
+    : "block"
+}
+
+function authoredId(data: Topmatter) {
+  return typeof data.id === "string" && data.id.trim()
+    ? data.id.trim()
+    : undefined
+}
+
+export function createBlock(
+  parent: Source,
+  ordinal: number,
+  content: string,
+  topmatter: Topmatter = {},
+  yaml?: PathMXYaml,
+): SourceBlock {
+  let split: ReturnType<typeof splitTopmatter>
+  try {
+    split = splitTopmatter(content, yaml)
+  } catch (error) {
+    if (!(error instanceof YamlMapParseError)) throw error
+    throw new SourceDiagnosticError({
+      source: parent.path,
+      plugin: "source",
+      message: `Invalid Block topmatter in ${parent.path} (block ${ordinal + 1}): ${error.message}`,
+    })
+  }
+  const data = { ...split.data, ...topmatter }
+  const body = split.body.trim()
+  const id = authoredId(data) ?? `block-${ordinal}`
+  const structure = scanMarkdownStructure(body)
+  let listStructure: ReturnType<typeof parseMarkdownLists> | undefined
+  const parseListStructure = () => (listStructure ??= parseMarkdownLists(body))
+
+  return {
+    id,
+    path: `${parent.path}#${id}`,
+    type: authoredType(data),
+    data,
+    links: parseLinkFragments(structure.linkFragments),
+    headings: structure.headings,
+    fences: structure.fences,
+    /** Lists are cached only when a plugin asks for their structure. */
+    get lists() {
+      return parseListStructure().lists
+    },
+    /** Tasks share the lazy list parse instead of rescanning Markdown. */
+    get tasks() {
+      return parseListStructure().tasks
+    },
+    content,
+    body,
+  }
+}

package/source/format.ts

@@ -0,0 +1,164 @@
+import type { PathMXYaml } from "../environment.ts"
+import { splitMarkdownBlocks } from "./markdown/blocks.ts"
+import { splitFrontmatter, splitTopmatter } from "./topmatter.ts"
+import type { Topmatter } from "./topmatter.ts"
+
+export type BlockDraft = {
+  id?: string
+  type?: string
+  data?: Topmatter
+  body?: string
+}
+
+export type BlockUpdate =
+  BlockDraft | ((current: Readonly<BlockDraft>) => BlockDraft)
+
+function compact(data: Topmatter) {
+  return Object.fromEntries(
+    Object.entries(data).filter(
+      ([, value]) => value !== undefined && value !== "",
+    ),
+  )
+}
+
+export function formatFrontmatter(data: Topmatter, yaml: PathMXYaml) {
+  const fields = compact(data)
+  if (!Object.keys(fields).length) return ""
+  return `---\n${yaml.stringify(fields).trimEnd()}\n---\n`
+}
+
+export function formatBlock(block: BlockDraft, yaml: PathMXYaml) {
+  const data = compact({
+    ...block.data,
+    ...(block.id ? { id: block.id } : {}),
+    ...(block.type ? { type: block.type } : {}),
+  })
+  const comment = Object.keys(data).length
+    ? `<!--\n${yaml.stringify(data).trimEnd()}\n-->`
+    : ""
+  const body = (block.body ?? "").trim()
+  return [comment, body].filter(Boolean).join("\n\n")
+}
+
+export function appendBlockSection(
+  content: string,
+  block: BlockDraft,
+  yaml: PathMXYaml,
+) {
+  const { data, body } = splitFrontmatter(content, yaml)
+  const sections = splitMarkdownBlocks(body)
+  sections.push(formatBlock(block, yaml))
+  return joinSections(data, sections, yaml)
+}
+
+function sameTypeIndex(sections: string[], type: string | undefined) {
+  if (!type) return 0
+  const index = sections.findIndex(
+    (section) =>
+      new RegExp(`(?:^|\\n)type:\\s*${type}\\s*$`, "m").test(section) ||
+      section.includes(`<${type}`),
+  )
+  return index === -1 ? sections.length : index
+}
+
+/** Insert a block before the first existing block of the same type (newest first). */
+export function prependBlockSection(
+  content: string,
+  block: BlockDraft,
+  yaml: PathMXYaml,
+) {
+  const { data, body } = splitFrontmatter(content, yaml)
+  const sections = splitMarkdownBlocks(body)
+  sections.splice(
+    sameTypeIndex(sections, block.type),
+    0,
+    formatBlock(block, yaml),
+  )
+  return `${formatFrontmatter(data, yaml)}${sections.join("\n\n---\n\n")}\n`
+}
+
+export function formatNewSource(
+  data: Topmatter,
+  yaml: PathMXYaml,
+  blocks: BlockDraft[] = [],
+) {
+  const front = formatFrontmatter(data, yaml)
+  if (!blocks.length) return front
+  const body = blocks
+    .map((block) => formatBlock(block, yaml))
+    .join("\n\n---\n\n")
+  return `${front}${front ? "\n" : ""}${body}\n`
+}
+
+export function patchFrontmatter(
+  content: string,
+  patch: Topmatter,
+  yaml: PathMXYaml,
+) {
+  const { data, body } = splitFrontmatter(content, yaml)
+  return `${formatFrontmatter({ ...data, ...patch }, yaml)}${body}`
+}
+
+function sectionId(section: string, ordinal: number, yaml: PathMXYaml) {
+  const { data } = splitTopmatter(section, yaml)
+  return typeof data.id === "string" && data.id.trim()
+    ? data.id.trim()
+    : `block-${ordinal}`
+}
+
+function sectionIndex(sections: string[], id: string, yaml: PathMXYaml) {
+  const index = sections.findIndex(
+    (section, ordinal) => sectionId(section, ordinal, yaml) === id,
+  )
+  if (index === -1) throw new Error(`Block not found: ${id}`)
+  return index
+}
+
+function joinSections(data: Topmatter, sections: string[], yaml: PathMXYaml) {
+  const front = formatFrontmatter(data, yaml)
+  if (!sections.length) return front
+  return `${front}${sections.join("\n\n---\n\n")}\n`
+}
+
+/** Merge topmatter into an existing block; replace body when `patch.body` is set. */
+export function updateBlockSection(
+  content: string,
+  id: string,
+  update: BlockUpdate,
+  yaml: PathMXYaml,
+) {
+  const { data, body } = splitFrontmatter(content, yaml)
+  const sections = splitMarkdownBlocks(body)
+  const index = sectionIndex(sections, id, yaml)
+  const current = splitTopmatter(sections[index]!, yaml)
+  const { id: currentId, type: currentType, ...currentData } = current.data
+  const snapshot: BlockDraft = {
+    ...(typeof currentId === "string" ? { id: currentId } : {}),
+    ...(typeof currentType === "string" ? { type: currentType } : {}),
+    data: currentData,
+    body: current.body,
+  }
+  const patch = typeof update === "function" ? update(snapshot) : update
+  sections[index] = formatBlock(
+    {
+      id: patch.id ?? snapshot.id,
+      type: patch.type ?? snapshot.type,
+      data: { ...snapshot.data, ...patch.data },
+      body: patch.body !== undefined ? patch.body : current.body,
+    },
+    yaml,
+  )
+  return joinSections(data, sections, yaml)
+}
+
+export function removeBlockSection(
+  content: string,
+  id: string,
+  yaml: PathMXYaml,
+) {
+  const { data, body } = splitFrontmatter(content, yaml)
+  const sections = splitMarkdownBlocks(body)
+  const index = sectionIndex(sections, id, yaml)
+  sections.splice(index, 1)
+  return joinSections(data, sections, yaml)
+}

package/source/index.ts

@@ -0,0 +1,67 @@
+export {
+  DEFAULT_SOURCE_TYPE,
+  createSource,
+  indexSourceDocument,
+  resolveSourceId,
+  rollupSourceIndexes,
+  sourceIdFromPath,
+  type Source,
+  type SourceNode,
+} from "./source.ts"
+export { createBlock, type SourceBlock } from "./blocks.ts"
+export {
+  assignHeadingIds,
+  collectHeadings,
+  isExternalHref,
+  isFenceClose,
+  matchFenceOpen,
+  parseCodeFences,
+  parseLinkDirective,
+  parseLinks,
+  rewriteLinks,
+  unlinkLinks,
+  splitMarkdownBlocks,
+  type FenceOpen,
+  type LinkDirective,
+  type MarkdownCodeFence,
+  type MarkdownHeading,
+  type MarkdownList,
+  type MarkdownListItem,
+  type MarkdownListLink,
+  type MarkdownListParse,
+  type MarkdownTask,
+  type SourceLink,
+  type SourceLinkKind,
+  type SourceLinkType,
+  markdownListItemLink,
+  parseMarkdownLists,
+} from "./markdown/index.ts"
+export {
+  appendBlockSection,
+  prependBlockSection,
+  removeBlockSection,
+  updateBlockSection,
+  formatBlock,
+  formatFrontmatter,
+  formatNewSource,
+  patchFrontmatter,
+  type BlockDraft,
+  type BlockUpdate,
+} from "./format.ts"
+export { interpolate, interpolateText } from "./interpolate.ts"
+export {
+  deriveBlockMeta,
+  deriveSourceMeta,
+  type BlockMeta,
+  type SourceMeta,
+} from "./meta.ts"
+export {
+  parseYamlMap,
+  splitFrontmatter,
+  splitTopmatter,
+  type Topmatter,
+} from "./topmatter.ts"
+export {
+  parseSourceTypeAndQualifiers,
+  type SourcePathNameMeta,
+} from "./utils.ts"

package/source/interpolate.ts

@@ -0,0 +1,63 @@
+import type { Topmatter } from "./topmatter.ts"
+import { isFenceClose, matchFenceOpen } from "./markdown/fences.ts"
+import { escapeHtml } from "../util.ts"
+
+const TOKEN = /\{\{\s*([A-Za-z_][\w-]*(?:\.[A-Za-z_][\w-]*)*)\s*\}\}/g
+
+function lookup(data: Topmatter, path: string) {
+  let current: unknown = data
+  for (const key of path.split(".")) {
+    if (!current || typeof current !== "object" || Array.isArray(current))
+      return ""
+    current = (current as Record<string, unknown>)[key]
+  }
+  if (
+    typeof current === "string" ||
+    typeof current === "number" ||
+    typeof current === "boolean"
+  ) {
+    return String(current)
+  }
+  return ""
+}
+
+function interpolateLine(line: string, data: Topmatter) {
+  return line.replace(TOKEN, (_match, path: string) =>
+    escapeHtml(lookup(data, path)),
+  )
+}
+
+/**
+ * Fill `{{ key }}` tokens in a plain-text value without HTML-escaping.
+ * For derived values (meta text, attributes) that are escaped at render time.
+ */
+export function interpolateText(text: string, data: Topmatter) {
+  return text.replace(TOKEN, (_match, path: string) => lookup(data, path))
+}
+
+/**
+ * Replace `{{ key }}` / `{{ nested.key }}` from a node's data bag.
+ * Missing paths become `""`. Fenced code is left untouched.
+ */
+export function interpolate(markdown: string, data: Topmatter) {
+  const lines = markdown.split(/\r?\n/)
+  const out: string[] = []
+  let marker: string | undefined
+
+  for (const line of lines) {
+    if (marker) {
+      out.push(line)
+      if (isFenceClose(line, marker)) marker = undefined
+      continue
+    }
+    const fence = matchFenceOpen(line)
+    if (fence) {
+      marker = fence.marker
+      out.push(line)
+      continue
+    }
+    out.push(interpolateLine(line, data))
+  }
+
+  return out.join("\n")
+}