@pathmx/core 0.5.0

package/publish/model.ts

@@ -0,0 +1,58 @@
+export const PUBLICATION_VERSION = 3 as const
+
+export type PublicationRepresentation = Readonly<{
+  type: "html" | "markdown" | "file"
+  artifact: string
+  contentType: string
+  default?: true
+  accept?: string
+  alternatePath?: string
+  headers?: Readonly<Record<string, string>>
+}>
+
+export type PublicationRoute = Readonly<{
+  pathname: string
+  type: "page" | "source" | "asset" | "artifact"
+  sourcePath?: string
+  representations: readonly PublicationRepresentation[]
+}>
+
+export type PublicationManifest = Readonly<{
+  version: typeof PUBLICATION_VERSION
+  /** Deterministic Merkle root of the canonical route contract and artifacts. */
+  build: string
+  origin: string
+  /** Normalized public mount path. `/` means the origin root. */
+  basePath: string
+  routes: readonly PublicationRoute[]
+  artifacts: readonly PublicationArtifactRecord[]
+}>
+
+export type PublicationArtifactRecord = Readonly<{
+  path: string
+  contentType: string
+  size: number
+  /** Stable cache identity; HTML is fingerprinted before its leaf is embedded. */
+  leaf: string
+}>
+
+export type PublicationStoredBody = Readonly<{
+  size: number
+  read: () => Promise<Blob>
+}>
+
+/** Adapter-owned staging whose writes remain private until adapter commit. */
+export type PublicationStore = Readonly<{
+  put: (path: string, body: Blob) => Promise<PublicationStoredBody>
+}>
+
+export type PublicationArtifact = PublicationArtifactRecord &
+  Readonly<{
+    /** Reusable adapter reader that does not depend on live Engine state. */
+    read: () => Promise<Blob>
+  }>
+
+export type PublicationBundle = Readonly<{
+  manifest: PublicationManifest
+  artifacts: readonly PublicationArtifact[]
+}>

package/publish/plan.ts

@@ -0,0 +1,300 @@
+import { mapConcurrent } from "./concurrent.ts"
+import { artifactLeaf, publicationRoot } from "./identity.ts"
+import {
+  PUBLICATION_VERSION,
+  type PublicationArtifact,
+  type PublicationArtifactRecord,
+  type PublicationManifest,
+  type PublicationRepresentation,
+  type PublicationRoute,
+  type PublicationStore,
+} from "./model.ts"
+
+type ArtifactInput = Readonly<{
+  path: string
+  contentType: string
+  size?: number
+  read: () => Promise<Blob>
+}>
+
+type PlannedArtifact = {
+  path: string
+  contentType: string
+  size?: number
+  leaf?: string
+  read: () => Promise<Blob>
+}
+
+const OMITTED_HEADERS = new Set([
+  "content-length",
+  "content-type",
+  "date",
+  "server-timing",
+  "set-cookie",
+  "transfer-encoding",
+])
+
+type MutableRoute = {
+  pathname: string
+  type: PublicationRoute["type"]
+  sourcePath?: string
+  representations: PublicationRepresentation[]
+}
+
+export class PublicationError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "PublicationError"
+  }
+}
+
+export function comparePaths(left: string, right: string) {
+  return left < right ? -1 : left > right ? 1 : 0
+}
+
+export function canonicalPublishedPath(value: string) {
+  if (!value.startsWith("/") || value.includes("?") || value.includes("#")) {
+    throw new PublicationError(`Invalid publication route: ${value}`)
+  }
+  const url = new URL(value, "https://pathmx.local")
+  if (url.pathname !== value || value.split("/").includes("..")) {
+    throw new PublicationError(`Invalid publication route: ${value}`)
+  }
+  return value
+}
+
+export function canonicalBasePath(value = "/") {
+  const path = canonicalPublishedPath(value || "/")
+  if (path !== "/" && path.endsWith("/")) {
+    throw new PublicationError(
+      `Publication base path must not end with a slash: ${value}`,
+    )
+  }
+  return path
+}
+
+export function mountedPublishedPath(basePath: string, pathname: string) {
+  const canonical = canonicalPublishedPath(pathname)
+  if (basePath === "/") return canonical
+  return canonical === "/" ? basePath : `${basePath}${canonical}`
+}
+
+export function pageArtifact(pathname: string) {
+  const page =
+    pathname === "/"
+      ? "index.html"
+      : `${pathname.replace(/^\/+|\/+$/g, "")}/index.html`
+  return `.pathmx/artifacts/pages/${page}`
+}
+
+export function exactArtifact(pathname: string) {
+  const path = pathname.replace(/^\/+/, "")
+  if (!path)
+    throw new PublicationError(`Route requires an artifact: ${pathname}`)
+  return path
+}
+
+export function responseHeaders(response: Response) {
+  const entries = [...response.headers]
+    .filter(([name]) => !OMITTED_HEADERS.has(name.toLowerCase()))
+    .sort(([left], [right]) => comparePaths(left, right))
+  return entries.length ? Object.freeze(Object.fromEntries(entries)) : undefined
+}
+
+export function fileRepresentation(
+  artifact: string,
+  contentType: string,
+  headers?: Readonly<Record<string, string>>,
+): PublicationRepresentation {
+  return Object.freeze({
+    type: "file",
+    default: true,
+    artifact,
+    contentType: contentType || "application/octet-stream",
+    ...(headers ? { headers } : {}),
+  })
+}
+
+export class PublicationPlan {
+  private routes = new Map<string, MutableRoute>()
+  private artifacts = new Map<string, PlannedArtifact>()
+
+  hasRoute(pathname: string) {
+    return this.routes.has(pathname)
+  }
+
+  addRoute(route: MutableRoute) {
+    if (this.routes.has(route.pathname)) {
+      throw new PublicationError(
+        `Duplicate publication route: ${route.pathname}`,
+      )
+    }
+    this.routes.set(route.pathname, route)
+  }
+
+  addArtifact(artifact: ArtifactInput) {
+    if (this.artifacts.has(artifact.path)) {
+      throw new PublicationError(
+        `Duplicate publication artifact: ${artifact.path}`,
+      )
+    }
+    this.artifacts.set(artifact.path, {
+      path: artifact.path,
+      contentType: artifact.contentType,
+      size: artifact.size,
+      read: artifact.read,
+    })
+  }
+
+  async materialize(store: PublicationStore) {
+    const pending = this.sortedArtifacts().filter(
+      (artifact) => artifact.leaf === undefined,
+    )
+    await mapConcurrent(pending, (artifact) =>
+      this.materializeArtifact(artifact, store),
+    )
+  }
+
+  async stagePage(path: string, store: PublicationStore) {
+    const artifact = this.requireArtifact(path)
+    if (artifact.leaf !== undefined) {
+      throw new PublicationError(`Page artifact was already staged: ${path}`)
+    }
+    const body = await artifact.read()
+    artifact.leaf = await artifactLeaf(
+      artifact.path,
+      artifact.contentType,
+      body,
+    )
+    await this.storeStampedPage(artifact, body, store)
+  }
+
+  buildRoot(origin: URL, basePath: string) {
+    return publicationRoot(
+      origin,
+      basePath,
+      this.routeList(),
+      this.artifactRecordList(),
+    )
+  }
+
+  pageLeaves() {
+    const artifacts = new Map(
+      this.artifactRecordList().map((artifact) => [artifact.path, artifact]),
+    )
+    return Object.freeze(
+      Object.fromEntries(
+        this.routeList()
+          .filter((route) => route.type === "page")
+          .map((route) => {
+            const path = route.representations.find(
+              (representation) => representation.type === "html",
+            )?.artifact
+            const artifact = path ? artifacts.get(path) : undefined
+            if (!artifact) {
+              throw new PublicationError(
+                `Page route has no HTML artifact leaf: ${route.pathname}`,
+              )
+            }
+            return [route.pathname, artifact.leaf]
+          }),
+      ),
+    )
+  }
+
+  manifest(build: string, origin: URL, basePath: string): PublicationManifest {
+    return Object.freeze({
+      version: PUBLICATION_VERSION,
+      build,
+      origin: origin.origin,
+      basePath,
+      routes: Object.freeze(this.routeList()),
+      artifacts: Object.freeze(this.artifactRecordList()),
+    })
+  }
+
+  private routeList() {
+    return [...this.routes.values()]
+      .sort((left, right) => comparePaths(left.pathname, right.pathname))
+      .map((route) =>
+        Object.freeze({
+          ...route,
+          representations: Object.freeze([...route.representations]),
+        }),
+      )
+  }
+
+  artifactList(): PublicationArtifact[] {
+    return this.sortedArtifacts().map((artifact) => {
+      if (artifact.size === undefined) {
+        throw new PublicationError(
+          `Publication artifact was not fingerprinted: ${artifact.path}`,
+        )
+      }
+      if (artifact.leaf === undefined) {
+        throw new PublicationError(
+          `Publication artifact has no leaf: ${artifact.path}`,
+        )
+      }
+      return Object.freeze({
+        path: artifact.path,
+        contentType: artifact.contentType,
+        size: artifact.size,
+        leaf: artifact.leaf,
+        read: artifact.read,
+      })
+    })
+  }
+
+  private artifactRecordList(): PublicationArtifactRecord[] {
+    return this.artifactList().map(({ read: _, ...artifact }) => artifact)
+  }
+
+  private requireArtifact(path: string) {
+    const artifact = this.artifacts.get(path)
+    if (!artifact) throw new PublicationError(`Missing artifact: ${path}`)
+    return artifact
+  }
+
+  private async materializeArtifact(
+    artifact: PlannedArtifact,
+    store: PublicationStore,
+  ) {
+    if (artifact.leaf !== undefined) return
+    const body = await artifact.read()
+    const leaf = await artifactLeaf(artifact.path, artifact.contentType, body)
+    const stored = await store.put(artifact.path, body)
+    artifact.size = stored.size
+    artifact.leaf = leaf
+    artifact.read = stored.read
+  }
+
+  private async storeStampedPage(
+    artifact: PlannedArtifact,
+    source: Blob,
+    store: PublicationStore,
+  ) {
+    if (!artifact.leaf) {
+      throw new PublicationError(`Missing artifact leaf: ${artifact.path}`)
+    }
+    const html = await source.text()
+    if (!html.includes("<html")) {
+      throw new PublicationError(
+        `HTML artifact has no document root: ${artifact.path}`,
+      )
+    }
+    const body = new Blob(
+      [html.replace("<html", `<html data-pmx-page="${artifact.leaf}"`)],
+      { type: artifact.contentType },
+    )
+    const stored = await store.put(artifact.path, body)
+    artifact.size = stored.size
+    artifact.read = stored.read
+  }
+
+  private sortedArtifacts() {
+    return [...this.artifacts.values()].sort((left, right) =>
+      comparePaths(left.path, right.path),
+    )
+  }
+}

package/publish/validate.ts

@@ -0,0 +1,150 @@
+import type { Engine } from "../host/engine.ts"
+import { interpolateText } from "../source/index.ts"
+import { publicPath } from "../server/router.ts"
+import type {
+  PublicationArtifact,
+  PublicationBundle,
+  PublicationRoute,
+} from "./model.ts"
+import { mountedPublishedPath, PublicationError } from "./plan.ts"
+
+const NETWORK_URL = /^(?:[a-z][a-z\d+.-]*:|\/\/)/i
+
+function htmlArtifact(
+  route: PublicationRoute,
+  artifacts: ReadonlyMap<string, PublicationArtifact>,
+) {
+  const path = route.representations.find(
+    (representation) => representation.type === "html",
+  )?.artifact
+  return path ? artifacts.get(path) : undefined
+}
+
+function internalPath(value: string, route: string, origin: string) {
+  if (NETWORK_URL.test(value.trim())) return
+  try {
+    const url = new URL(value, new URL(route, origin))
+    return url.origin === origin ? url.pathname : undefined
+  } catch {
+    return
+  }
+}
+
+function unresolvedPaths(
+  app: Engine,
+  route: PublicationRoute,
+  origin: string,
+  basePath: string,
+) {
+  const source = route.sourcePath
+    ? app.repo.atPath(route.sourcePath)
+    : undefined
+  if (!source) return new Set<string>()
+  const canonicalRoute = app.isPage(source) ? publicPath(source) : source.path
+  return new Set(
+    app.graph
+      .linksFrom(source.path)
+      .filter((edge) => edge.type === "unresolved")
+      .map((edge) => {
+        const pathname = internalPath(
+          interpolateText(edge.href, source.data),
+          canonicalRoute,
+          origin,
+        )
+        return pathname ? mountedPublishedPath(basePath, pathname) : undefined
+      })
+      .filter((path): path is string => path != null),
+  )
+}
+
+/** Validate that exported HTML depends only on materialized public routes. */
+export async function validatePublication(
+  app: Engine,
+  publication: PublicationBundle,
+) {
+  const routes = new Set(
+    publication.manifest.routes.flatMap((route) => {
+      const path = internalPath(
+        route.pathname,
+        "/",
+        publication.manifest.origin,
+      )
+      return path ? [path] : []
+    }),
+  )
+  const artifacts = new Map(
+    publication.artifacts.map((artifact) => [artifact.path, artifact]),
+  )
+  const issues: string[] = []
+
+  for (const route of publication.manifest.routes) {
+    const artifact = htmlArtifact(route, artifacts)
+    if (!artifact) continue
+    const unresolved = unresolvedPaths(
+      app,
+      route,
+      publication.manifest.origin,
+      publication.manifest.basePath,
+    )
+    const html = await (await artifact.read()).text()
+    app.environment.rewriteHtml(html, [
+      [
+        "a[href], link[href], script[src], img[src], source[src], form",
+        {
+          element(element) {
+            const attribute =
+              element.getAttribute("href") != null ? "href" : "src"
+            const value = element.getAttribute(attribute)
+            if (value) {
+              const pathname = internalPath(
+                value,
+                route.pathname,
+                publication.manifest.origin,
+              )
+              if (
+                pathname &&
+                !routes.has(pathname) &&
+                !unresolved.has(pathname)
+              ) {
+                issues.push(
+                  `${route.pathname}: ${attribute} references unpublished route ${pathname}`,
+                )
+              }
+            }
+
+            if (element.tagName !== "form") return
+            const method = (
+              element.getAttribute("method") || "get"
+            ).toLowerCase()
+            const action = element.getAttribute("action") || route.pathname
+            const pathname = internalPath(
+              action,
+              route.pathname,
+              publication.manifest.origin,
+            )
+            if (method === "get") {
+              if (pathname && !routes.has(pathname)) {
+                issues.push(
+                  `${route.pathname}: GET form references unpublished route ${pathname}`,
+                )
+              }
+            } else if (pathname) {
+              issues.push(
+                `${route.pathname}: ${method.toUpperCase()} form requires server route ${pathname}`,
+              )
+            }
+          },
+        },
+      ],
+    ])
+  }
+
+  if (issues.length) {
+    throw new PublicationError(
+      `Static publication contains unavailable routes:\n${[...new Set(issues)]
+        .sort()
+        .map((issue) => `- ${issue}`)
+        .join("\n")}`,
+    )
+  }
+}

package/query/candidate-index.ts

@@ -0,0 +1,101 @@
+import type { Source, SourceBlock } from "../source/index.ts"
+
+type CandidateSelector = Readonly<{
+  type?: string
+  has: readonly string[]
+}>
+
+export type IndexedBlock = Readonly<{
+  source: Source
+  block: SourceBlock
+}>
+
+/** @internal Minimal candidate indexes shared by the built-in query roots. */
+export class QueryIndex {
+  private sources = new Set<Source>()
+  private sourcesByPath = new Map<string, Source>()
+  private sourcesByType = new Map<string, Set<Source>>()
+  private sourcesByProp = new Map<string, Set<Source>>()
+  private blocks = new Set<IndexedBlock>()
+  private blocksBySource = new Map<string, IndexedBlock[]>()
+  private blocksByType = new Map<string, Set<IndexedBlock>>()
+  private blocksByProp = new Map<string, Set<IndexedBlock>>()
+
+  replace(source: Source, registeredProps: ReadonlySet<string>) {
+    this.delete(source.path)
+    this.sources.add(source)
+    this.sourcesByPath.set(source.path, source)
+    this.add(this.sourcesByType, source.type, source)
+    for (const prop of Object.keys(source.data)) {
+      if (registeredProps.has(prop)) this.add(this.sourcesByProp, prop, source)
+    }
+
+    const blocks = source.blocks.map((block) =>
+      Object.freeze({ source, block }),
+    )
+    this.blocksBySource.set(source.path, blocks)
+    for (const indexed of blocks) {
+      this.blocks.add(indexed)
+      this.add(this.blocksByType, indexed.block.type, indexed)
+      for (const prop of Object.keys(indexed.block.data)) {
+        if (registeredProps.has(prop)) {
+          this.add(this.blocksByProp, prop, indexed)
+        }
+      }
+    }
+  }
+
+  delete(sourcePath: string) {
+    const source = this.sourcesByPath.get(sourcePath)
+    if (source) {
+      this.sources.delete(source)
+      this.sourcesByPath.delete(sourcePath)
+      this.remove(this.sourcesByType, source.type, source)
+      for (const prop of Object.keys(source.data)) {
+        this.remove(this.sourcesByProp, prop, source)
+      }
+    }
+    for (const indexed of this.blocksBySource.get(sourcePath) ?? []) {
+      this.blocks.delete(indexed)
+      this.remove(this.blocksByType, indexed.block.type, indexed)
+      for (const prop of Object.keys(indexed.block.data)) {
+        this.remove(this.blocksByProp, prop, indexed)
+      }
+    }
+    this.blocksBySource.delete(sourcePath)
+  }
+
+  sourceCandidates(selector: CandidateSelector) {
+    let candidates: Iterable<Source> = selector.type
+      ? (this.sourcesByType.get(selector.type) ?? [])
+      : this.sources
+    for (const prop of selector.has) {
+      const matching = this.sourcesByProp.get(prop) ?? new Set<Source>()
+      candidates = [...candidates].filter((source) => matching.has(source))
+    }
+    return candidates
+  }
+
+  blockCandidates(selector: CandidateSelector) {
+    let candidates: Iterable<IndexedBlock> = selector.type
+      ? (this.blocksByType.get(selector.type) ?? [])
+      : this.blocks
+    for (const prop of selector.has) {
+      const matching = this.blocksByProp.get(prop) ?? new Set<IndexedBlock>()
+      candidates = [...candidates].filter((block) => matching.has(block))
+    }
+    return candidates
+  }
+
+  private add<T>(map: Map<string, Set<T>>, key: string, value: T) {
+    const values = map.get(key) ?? new Set<T>()
+    values.add(value)
+    map.set(key, values)
+  }
+
+  private remove<T>(map: Map<string, Set<T>>, key: string, value: T) {
+    const values = map.get(key)
+    values?.delete(value)
+    if (values?.size === 0) map.delete(key)
+  }
+}

package/query/dependency-index.ts

@@ -0,0 +1,99 @@
+export type QueryInvalidation = Readonly<{
+  key: string
+  actors?: readonly string[]
+}>
+
+function actorScope(actor: string) {
+  return `actor:${actor}`
+}
+
+function scopeActor(scope: string) {
+  return scope.startsWith("actor:") ? scope.slice("actor:".length) : undefined
+}
+
+/** Per-viewer dependency graph for composed and Plugin-derived queries. */
+export class QueryDependencyIndex {
+  private byPlan = new Map<string, Map<string, Set<string>>>()
+  private byDependency = new Map<string, Map<string, Set<string>>>()
+
+  constructor(private maxScopesPerPlan: number) {}
+
+  replace(plan: string, scope: string, dependencies: Set<string>) {
+    const scopes = this.byPlan.get(plan) ?? new Map<string, Set<string>>()
+    const current = scopes.get(scope) ?? new Set<string>()
+    scopes.delete(scope)
+    scopes.set(scope, new Set(dependencies))
+    this.byPlan.set(plan, scopes)
+    for (const dependency of current) {
+      if (!dependencies.has(dependency)) this.unlink(dependency, plan, scope)
+    }
+    for (const dependency of dependencies) {
+      if (!current.has(dependency)) this.link(dependency, plan, scope)
+    }
+    while (scopes.size > this.maxScopesPerPlan) {
+      const oldest = scopes.keys().next().value as string | undefined
+      if (oldest === undefined) break
+      this.deleteScope(plan, oldest)
+    }
+  }
+
+  deleteScope(plan: string, scope: string) {
+    const scopes = this.byPlan.get(plan)
+    const removed = scopes?.get(scope)
+    if (!scopes || !removed) return
+    scopes.delete(scope)
+    for (const dependency of removed) this.unlink(dependency, plan, scope)
+    if (scopes.size === 0) this.byPlan.delete(plan)
+  }
+
+  clear(plan: string, actors?: readonly string[]) {
+    const scopes = actors
+      ? actors.map(actorScope)
+      : [...(this.byPlan.get(plan)?.keys() ?? [])]
+    for (const scope of scopes) this.deleteScope(plan, scope)
+  }
+
+  hasDependents(dependency: string) {
+    return this.byDependency.has(dependency)
+  }
+
+  dependentsOf(
+    dependency: string,
+    actors?: readonly string[],
+  ): QueryInvalidation[] {
+    const invalidations: QueryInvalidation[] = []
+    for (const [key, scopes] of this.byDependency.get(dependency) ?? []) {
+      if (actors) {
+        const affected = actors.filter((actor) => scopes.has(actorScope(actor)))
+        if (affected.length) invalidations.push({ key, actors: affected })
+        continue
+      }
+      if (scopes.has("anonymous")) {
+        invalidations.push({ key })
+        continue
+      }
+      const affected = [...scopes].flatMap((scope) => {
+        const actor = scopeActor(scope)
+        return actor ? [actor] : []
+      })
+      if (affected.length) invalidations.push({ key, actors: affected })
+    }
+    return invalidations
+  }
+
+  private link(dependency: string, plan: string, scope: string) {
+    const plans = this.byDependency.get(dependency) ?? new Map()
+    const scopes = plans.get(plan) ?? new Set<string>()
+    scopes.add(scope)
+    plans.set(plan, scopes)
+    this.byDependency.set(dependency, plans)
+  }
+
+  private unlink(dependency: string, plan: string, scope: string) {
+    const plans = this.byDependency.get(dependency)
+    const scopes = plans?.get(plan)
+    scopes?.delete(scope)
+    if (scopes?.size === 0) plans?.delete(plan)
+    if (plans?.size === 0) this.byDependency.delete(dependency)
+  }
+}