@lincyaw/compiler 0.0.0-stage → 1.0.0-rc.1

package/src/plugins.ts

@@ -0,0 +1,221 @@
+import { existsSync, readFileSync, realpathSync } from 'node:fs'
+import { readdir, readFile } from 'node:fs/promises'
+import { dirname, isAbsolute, join, resolve } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { errorMessage, isRecord, kernelIncompatibility } from '@lincyaw/kernel'
+import type { PresmiumNodePlugin, Severity } from '@lincyaw/kernel'
+import { createJiti } from 'jiti'
+import { satisfies, validRange } from 'semver'
+import { exports as resolveExports } from 'resolve.exports'
+
+export const NODE_PLUGIN_EXPORT = './presmium'
+
+export interface LoadedPlugin {
+  name: string
+  dir: string
+  plugin?: PresmiumNodePlugin
+  entry?: string
+}
+
+export interface PluginProblem {
+  name: string
+  severity: Severity
+  message: string
+}
+
+const BUNDLED = new Set(['@lincyaw/web', '@lincyaw/render-slides', '@lincyaw/render-notebook'])
+
+export interface PluginSources {
+  workspaceRoot: string
+  listed: string[]
+  bundled?: string
+}
+
+const jiti = createJiti(import.meta.url)
+
+export async function loadPlugin(name: string, deckDir: string, sources?: PluginSources): Promise<{ loaded?: LoadedPlugin, problem?: PluginProblem }> {
+  const problem = (severity: Severity, message: string): PluginProblem => ({ name, severity, message })
+  const dir = findPackageDir(name, resolve(deckDir)) ?? bundledDir(name, sources)
+  if (!dir) return { problem: problem('error', `cannot load plugin "${name}": package not found from ${deckDir}`) }
+  return loadFrom(name, dir, problem)
+}
+
+function bundledDir(name: string, sources?: PluginSources): string | undefined {
+  if (!sources?.bundled) return undefined
+  return BUNDLED.has(name) || dependsOn(sources.bundled, name) ? findPackageDir(name, sources.bundled) : undefined
+}
+
+function dependsOn(dir: string, name: string): boolean {
+  try {
+    const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as { dependencies?: Record<string, string> }
+    return Object.hasOwn(pkg.dependencies ?? {}, name)
+  } catch {
+    return false
+  }
+}
+
+interface PluginPackage {
+  name?: unknown
+  version?: unknown
+  exports?: Record<string, unknown>
+  peerDependencies?: Record<string, unknown>
+}
+
+const PRESMIUM_SCOPE = '@lincyaw/'
+
+// The official plugins were named after Slidev's addons; a headmatter that still lists them gets the current packages.
+const LEGACY_PLUGIN = '@lincyaw/slidev-addon-'
+const PLUGIN = '@lincyaw/addon-'
+
+/** A plugin's package as the headmatter lists it, under its current name. */
+export function currentPluginName(name: string): string {
+  return name.startsWith(LEGACY_PLUGIN) ? PLUGIN + name.slice(LEGACY_PLUGIN.length) : name
+}
+
+// Plugins whose work the viewer does itself (the slides' host adapter, Slidev's); a headmatter may still list them.
+const RETIRED_PLUGINS: ReadonlySet<string> = new Set(['@lincyaw/addon-core'])
+
+export function isRetiredPlugin(name: string): boolean {
+  return RETIRED_PLUGINS.has(currentPluginName(name))
+}
+
+/** The plugins a headmatter lists, under their current names, the retired ones left out. */
+export function listedPlugins(names: readonly string[]): string[] {
+  return names.filter(name => !isRetiredPlugin(name)).map(currentPluginName)
+}
+
+const COMPILER_DIR = fileURLToPath(new URL('..', import.meta.url))
+const COMPILER_PACKAGE = JSON.parse(readFileSync(join(COMPILER_DIR, 'package.json'), 'utf8')) as { name: string, version: string }
+
+function peerIncompatibility(pkg: PluginPackage, dir: string): string | undefined {
+  const problems: string[] = []
+  for (const [dependency, range] of Object.entries(pkg.peerDependencies ?? {})) {
+    if (!dependency.startsWith(PRESMIUM_SCOPE) || typeof range !== 'string' || /^[a-z]+:/i.test(range)) continue
+    const installed = installedVersion(dependency, dir)
+    if (installed === undefined) continue
+    if (validRange(range) === null) problems.push(`its peer dependency ${dependency} has an invalid range "${range}"`)
+    else if (!satisfies(installed, range, { includePrerelease: true })) problems.push(`it needs ${dependency} ${range} (peerDependencies), and ${installed} is installed`)
+  }
+  return problems.length > 0 ? problems.join('; ') : undefined
+}
+
+function installedVersion(name: string, dir: string): string | undefined {
+  const found = findPackageDir(name, dir) ?? (name === COMPILER_PACKAGE.name ? COMPILER_DIR : findPackageDir(name, COMPILER_DIR))
+  if (!found) return undefined
+  const { version } = JSON.parse(readFileSync(join(found, 'package.json'), 'utf8')) as { version?: unknown }
+  return typeof version === 'string' ? version : undefined
+}
+
+async function loadFrom(name: string, dir: string, problem: (severity: Severity, message: string) => PluginProblem): Promise<{ loaded?: LoadedPlugin, problem?: PluginProblem }> {
+  try {
+    const pkg = JSON.parse(await readFile(join(dir, 'package.json'), 'utf8')) as PluginPackage
+    const peers = peerIncompatibility(pkg, dir)
+    if (peers) {
+      const label = typeof pkg.name === 'string' ? ` (${pkg.name}${typeof pkg.version === 'string' ? ` ${pkg.version}` : ''})` : ''
+      return { problem: problem('error', `plugin "${name}"${label} is not loaded: ${peers}`) }
+    }
+    const target = exportTarget(pkg, dir)
+    if (!target) return { loaded: { name, dir } }
+    const file = fileURLToPath(new URL(target, pathToFileURL(`${dir}/`)))
+    if (!existsSync(file)) {
+      return { loaded: { name, dir }, problem: problem('warning', `plugin "${name}": ${NODE_PLUGIN_EXPORT} points to missing file ${target}; only its components are used`) }
+    }
+    const plugin = await jiti.import(file, { default: true })
+    if (!isNodePlugin(plugin)) throw new Error(`default export of ${NODE_PLUGIN_EXPORT} is not a PresmiumNodePlugin`)
+    const incompatible = plugin.kernel === undefined ? undefined : kernelIncompatibility(plugin.kernel)
+    if (incompatible) {
+      const version = plugin.version ? ` ${plugin.version}` : ''
+      return { problem: problem('error', `plugin "${name}" (${plugin.id}${version}) is not loaded: ${incompatible}`) }
+    }
+    return { loaded: { name, dir, plugin, entry: file } }
+  } catch (error) {
+    return { problem: problem('error', `cannot load plugin "${name}": ${errorMessage(error)}`) }
+  }
+}
+
+export async function loadPlugins(deckDir: string, names: string[], sources?: PluginSources): Promise<{ plugins: LoadedPlugin[], problems: PluginProblem[] }> {
+  const plugins: LoadedPlugin[] = []
+  const problems: PluginProblem[] = []
+  for (const name of names) {
+    const { loaded, problem } = await loadPlugin(name, deckDir, sources)
+    if (loaded) plugins.push(loaded)
+    if (problem) problems.push(problem)
+  }
+  return { plugins, problems }
+}
+
+export async function loadOperatorPlugins(sources: PluginSources): Promise<{ plugins: LoadedPlugin[], problems: PluginProblem[] }> {
+  const plugins: LoadedPlugin[] = []
+  const problems: PluginProblem[] = []
+  for (const name of listedPlugins(sources.listed)) {
+    const dir = findPackageDir(name, resolve(sources.workspaceRoot), false) ?? bundledDir(name, sources)
+    if (!dir) {
+      problems.push({ name, severity: 'error', message: `operator plugin "${name}" (settings.presmium.workspace.plugins) is not installed at the workspace root ${sources.workspaceRoot}` })
+      continue
+    }
+    const { loaded, problem } = await loadFrom(name, dir, (severity, message) => ({ name, severity, message }))
+    if (problem) problems.push(problem)
+    if (loaded?.plugin?.operator === true) plugins.push(loaded)
+  }
+  return { plugins, problems }
+}
+
+export const DECK_PLUGIN = 'deck'
+
+const COMPONENT = /^[^.]+\.(?:[jt]sx?)$/
+
+export async function directoryComponents(dir: string): Promise<string[]> {
+  const files = await readdir(join(dir, 'components')).catch(() => [])
+  return files.filter(f => COMPONENT.test(f)).map(f => f.replace(/\.[^.]+$/, '')).sort()
+}
+
+export function pluginId(plugin: LoadedPlugin): string {
+  return plugin.plugin?.id ?? plugin.name
+}
+
+export function findPackageDir(name: string, from: string, up = true): string | undefined {
+  if (name.startsWith('.') || isAbsolute(name)) {
+    const dir = resolve(from, name)
+    return existsSync(join(dir, 'package.json')) ? dir : undefined
+  }
+  for (let d = from; ; d = dirname(d)) {
+    const dir = join(d, 'node_modules', name)
+    if (existsSync(join(dir, 'package.json'))) return realpathSync(dir)
+    if (!up || dirname(d) === d) return undefined
+  }
+}
+
+function exportTarget(pkg: PluginPackage, dir: string): string | undefined {
+  let targets: string[] | void
+  try {
+    targets = resolveExports(pkg, NODE_PLUGIN_EXPORT)
+  } catch {
+    // A package with no matching Node export still contributes its components.
+    return undefined
+  }
+  if (!targets?.length) return undefined
+  const base = pathToFileURL(`${dir}/`)
+  for (const target of targets) {
+    const path = target.split(/[?#]/, 1)[0]!
+    if (!path.startsWith('./') || /%2f|%5c/i.test(path)) continue
+    try {
+      const segments = path.slice(2).split(/[\\/]/).map(decodeURIComponent)
+      if (segments.some(segment => /^(?:\.{1,2}|node_modules)$/i.test(segment))) continue
+      const normalized = new URL(target, base)
+      if (!normalized.href.startsWith(base.href)) continue
+      return target
+    } catch {
+      // Invalid URL encoding cannot name a package file; arrays may provide another target.
+    }
+  }
+  throw new Error(`${NODE_PLUGIN_EXPORT} has no valid package-relative Node target`)
+}
+
+function isNodePlugin(value: unknown): value is PresmiumNodePlugin {
+  if (!isRecord(value) || typeof value.id !== 'string') return false
+  const lists = ['resolvers', 'checks', 'directives', 'passes', 'executors', 'roles', 'tools'] as const
+  const renderer = value.renderer
+  return lists.every(key => value[key] === undefined || Array.isArray(value[key]))
+    && ['version', 'kernel'].every(key => value[key] === undefined || typeof value[key] === 'string')
+    && (renderer === undefined || (isRecord(renderer) && typeof renderer.id === 'string' && typeof renderer.build === 'function'))
+}

package/src/references.ts

@@ -0,0 +1,53 @@
+import { irBlocks, nodeMdast } from '@lincyaw/kernel'
+import type { Finding, IRDocument, MdastNode, SourcePos } from '@lincyaw/kernel'
+import type { GenericParent } from 'myst-common'
+import { normalizeLabel } from 'myst-common'
+import { enumerateTargetsTransform, ReferenceState } from 'myst-transforms'
+
+type Reference = Parameters<ReferenceState['resolveReferenceContent']>[0]
+const IMPLICIT_TARGETS = new Set(['container', 'mathGroup', 'math', 'heading', 'proof'])
+
+export function resolveReferences(doc: IRDocument, report: (finding: Finding) => void): void {
+  const references: { node: MdastNode, source: SourcePos }[] = []
+  for (const section of doc.sections) {
+    for (const block of irBlocks(section.blocks)) {
+      for (const tree of nodeMdast(block.node)) collectReferences(tree, block.source, references)
+    }
+  }
+  const state = new ReferenceState(doc.meta.entry)
+  const targets: MdastNode[] = []
+  for (const section of doc.sections) {
+    targets.push({ type: 'heading', depth: Math.max(section.depth, 1), ...normalizeLabel(section.id), children: [{ type: 'text', value: section.title }] })
+    for (const block of irBlocks(section.blocks)) {
+      if (block.node.type === 'markdown') for (const child of block.node.mdast.children ?? []) collectTargets(child, targets)
+    }
+  }
+  enumerateTargetsTransform({ type: 'root', children: targets } as GenericParent, { state })
+
+  for (const { node: reference, source } of references) {
+    const resolved = { ...reference } as Reference
+    state.resolveReferenceContent(resolved)
+    if (!resolved.resolved) {
+      report({
+        checkId: 'presmium.references',
+        severity: 'warning',
+        message: `{${String(reference.kind ?? 'ref')}} target "${String(reference.label ?? reference.identifier)}" not found`,
+        source: { file: source.file, line: source.line },
+      })
+    } else if (!reference.children?.length) {
+      reference.children = resolved.children as MdastNode[]
+    }
+  }
+}
+
+function collectReferences(node: MdastNode, source: SourcePos, into: { node: MdastNode, source: SourcePos }[]): void {
+  if (node.type === 'crossReference') into.push({ node, source })
+  else for (const child of node.children ?? []) collectReferences(child, source, into)
+}
+
+function collectTargets(node: MdastNode, into: MdastNode[]): void {
+  // Keep target subtrees intact, including containers' subfigures and math groups.
+  // Unlabelled prose cannot change the enumeration or reference state.
+  if (node.identifier || node.enumerated || IMPLICIT_TARGETS.has(node.type)) into.push(node)
+  else for (const child of node.children ?? []) collectTargets(child, into)
+}

package/src/renderers.ts

@@ -0,0 +1,195 @@
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { errorMessage, findComponentRenderer, isRecord } from '@lincyaw/kernel'
+import type { BoundRendererExtension, ComponentNode, ComponentRenderer, Exporter, Finding, IRBlock, IRDocument, NodeVitePlugin, RenderContext, RenderOutput, Renderer } from '@lincyaw/kernel'
+import { documentLink, publishedAsset } from './assets.ts'
+import type { Compilation, Compiler } from './compiler.ts'
+import { portable } from './paths.ts'
+import { loadPlugin, pluginId } from './plugins.ts'
+import type { LoadedPlugin } from './plugins.ts'
+import { compileTranslations } from './translations.ts'
+import type { CompiledTranslation } from './translations.ts'
+import { viewFor } from './views.ts'
+
+export const DEFAULT_RENDERER_PACKAGES: Record<string, string> = {
+  web: '@lincyaw/web',
+  slides: '@lincyaw/render-slides',
+  notebook: '@lincyaw/render-notebook',
+}
+
+export const WEB = 'web'
+
+export interface InstalledRenderer {
+  renderer: Renderer
+  package: string
+  /** The exporters of the renderer's package, with its configuration in the document. */
+  exporters: DocumentExporter[]
+}
+
+/** An exporter a document can use, with its plugin's configuration in the document. */
+export interface DocumentExporter {
+  exporter: Exporter
+  config: Record<string, unknown>
+}
+
+function exportersOf(compilation: Compilation, loaded: LoadedPlugin): DocumentExporter[] {
+  const config = compilation.doc.config.presmium[pluginId(loaded)]
+  return (loaded.plugin?.exporters ?? []).map(exporter => ({ exporter, config: isRecord(config) ? config : {} }))
+}
+
+/** The renderers of one build or dev, and the base path of each. */
+export interface RenderRun {
+  ids: string[]
+  bases: Map<string, string>
+}
+
+async function installedRenderers(compilation: Compilation): Promise<{ renderers: Map<string, InstalledRenderer>, missing: Map<string, string> }> {
+  const renderers = new Map<string, InstalledRenderer>()
+  const missing = new Map<string, string>()
+  for (const loaded of compilation.plugins) {
+    const { name, plugin } = loaded
+    if (plugin?.renderer && !renderers.has(plugin.renderer.id)) renderers.set(plugin.renderer.id, { renderer: plugin.renderer, package: name, exporters: exportersOf(compilation, loaded) })
+  }
+  const config = compilation.doc.config.renderers
+  for (const id of new Set([...Object.keys(DEFAULT_RENDERER_PACKAGES), ...Object.keys(config)])) {
+    if (renderers.has(id)) continue
+    const pkg = typeof config[id]?.package === 'string' ? config[id].package as string : DEFAULT_RENDERER_PACKAGES[id]
+    if (!pkg) {
+      missing.set(id, 'no package provides it; set renderers.<id>.package')
+      continue
+    }
+    const { loaded, problem } = await loadPlugin(pkg, compilation.deckDir, compilation.pluginSources)
+    const renderer = loaded?.plugin?.renderer
+    if (loaded && renderer?.id === id) renderers.set(id, { renderer, package: pkg, exporters: exportersOf(compilation, loaded) })
+    else missing.set(id, problem?.message ?? `package ${pkg} provides no renderer "${id}"`)
+  }
+  return { renderers, missing }
+}
+
+export async function selectRenderers(compilation: Compilation, to?: string[]): Promise<{ selected: InstalledRenderer[], findings: Finding[] }> {
+  const { renderers, missing } = await installedRenderers(compilation)
+  const configured = Object.keys(compilation.doc.config.renderers)
+  const ids = to ?? (configured.length > 0 ? configured : [...renderers.keys()])
+  const findings: Finding[] = []
+  const selected: InstalledRenderer[] = []
+  for (const id of ids) {
+    const found = renderers.get(id)
+    if (found) selected.push(found)
+    else findings.push(renderFinding(compilation, to ? 'error' : 'warning', `renderer ${id} is not installed: ${missing.get(id) ?? 'unknown renderer id'}`))
+  }
+  return { selected, findings }
+}
+
+/** The exporters of the document's plugins and of its renderers' packages; one id once, the plugins' first. */
+export async function documentExporters(compilation: Compilation): Promise<DocumentExporter[]> {
+  const { selected } = await selectRenderers(compilation)
+  const found = new Map<string, DocumentExporter>()
+  for (const own of [...compilation.plugins.flatMap(loaded => exportersOf(compilation, loaded)), ...selected.flatMap(installed => installed.exporters)]) {
+    if (!found.has(own.exporter.id)) found.set(own.exporter.id, own)
+  }
+  return [...found.values()]
+}
+
+export function configuredBase(value: unknown): string | undefined {
+  if (typeof value !== 'string' || !value.trim()) return undefined
+  const path = value.trim().replace(/^\/+|\/+$/g, '')
+  return path ? `/${path}/` : '/'
+}
+
+/** With `shared`, site renderers without a configured base share the output under `/<id>/`. */
+export function planRenderRun(compilation: Compilation, selected: InstalledRenderer[], shared: boolean, base?: string): RenderRun {
+  const renderers = selected.map(({ renderer }) => renderer)
+  const configured = new Map(renderers.map(({ id }) => [id, configuredBase(compilation.doc.config.renderers[id]?.base)]))
+  const sites = renderers.filter(renderer => renderer.site)
+  const together = shared && sites.length > 1 && sites.every(({ id }) => configured.get(id) === undefined)
+  const run: RenderRun = {
+    ids: renderers.map(({ id }) => id),
+    bases: new Map(renderers.map(({ id, site }) => [id, configured.get(id) ?? (together && site ? `/${id}/` : '/')])),
+  }
+  const given = configuredBase(base)
+  if (given) for (const id of run.ids) run.bases.set(id, given)
+  return run
+}
+
+export async function translationsFor(compilation: Compilation, run: RenderRun, compilers?: Map<string, Compiler>): Promise<{ translations: CompiledTranslation[], views: NonNullable<RenderContext['translations']>, findings: Finding[] }> {
+  if (!run.ids.includes(WEB) || !compilation.doc.config.translations) return { translations: [], views: [], findings: [] }
+  const { translations, findings } = await compileTranslations(compilation, compilers)
+  return { translations, views: translations.map(({ lang, doc }) => ({ lang, doc: viewFor(doc, WEB) })), findings }
+}
+
+export async function writeIR(doc: IRDocument, outDir: string): Promise<string> {
+  const file = join(outDir, 'ir.json')
+  await mkdir(outDir, { recursive: true })
+  await writeFile(file, `${JSON.stringify(doc, null, 2)}\n`)
+  return file
+}
+
+export function renderContext(compilation: Compilation, id: string, outDir: string, workDir: string, run: RenderRun, findings: Finding[], server?: { url: string }): RenderContext {
+  const { deckDir, workspaceRoot, doc } = compilation
+  const config = doc.config.renderers[id]
+  const report = (finding: Finding) => {
+    const located = { ...finding, source: finding.source ?? { file: compilation.entry, line: 1 } }
+    if (!findings.some(f => JSON.stringify(f) === JSON.stringify(located))) findings.push(located)
+  }
+  const ctx: RenderContext = {
+    deckDir,
+    workspaceRoot,
+    outDir,
+    workDir,
+    config: isRecord(config) ? config : {},
+    extensions: [],
+    plugins: doc.config.plugins,
+    pluginDirs: Object.fromEntries(compilation.plugins.map(loaded => [loaded.name, loaded.dir])),
+    lang: doc.meta.lang,
+    renderers: run.ids,
+    base: run.bases.get(id) ?? '/',
+    nodeVitePlugins: nodeVitePlugins(compilation),
+    extensionFor: node => findComponentRenderer(node, ctx.extensions),
+    portable: (value, from) => portable(value, from, workspaceRoot),
+    localAsset: (source, url) => publishedAsset(compilation, source, url, report),
+    documentLink: (source, url) => documentLink(compilation, source, url),
+    report,
+    service: compilation.service,
+    ...server ? { server } : {},
+  }
+  const bind = (render: ComponentRenderer) => (node: ComponentNode, block: IRBlock) => render(node, block, ctx)
+  ctx.extensions = compilation.plugins.flatMap((loaded): BoundRendererExtension[] => {
+    const contribution = loaded.plugin?.rendererExtensions?.[id]
+    if (!contribution) return []
+    const components = contribution.components && Object.fromEntries(Object.entries(contribution.components).map(([name, render]) => [name, bind(render)]))
+    return [{ plugin: pluginId(loaded), ...components ? { components } : {} }]
+  })
+  return ctx
+}
+
+/** The Node entries of the plugins whose browser parts need them (run-time files, document modules), with their configuration. */
+export function nodeVitePlugins(compilation: Pick<Compilation, 'plugins' | 'doc'>): NodeVitePlugin[] {
+  return compilation.plugins.flatMap((loaded) => {
+    const plugin = loaded.plugin
+    if (!loaded.entry || !(plugin?.assets || plugin?.documentModules)) return []
+    const config = compilation.doc.config.presmium[pluginId(loaded)]
+    return [{ id: pluginId(loaded), entry: loaded.entry, config: isRecord(config) ? config : {} }]
+  })
+}
+
+export function unsupportedBlocks(doc: IRDocument, renderer: Renderer, extensions: BoundRendererExtension[]): RenderOutput['skipped'] {
+  const skipped: RenderOutput['skipped'] = []
+  const visit = (section: string, blocks: IRBlock[]) => {
+    for (const block of blocks) {
+      let support
+      try {
+        support = renderer.support(block.node, extensions)
+      } catch {
+        support = 'none'
+      }
+      if (support === 'none') skipped.push({ section, block: block.id, reason: `${block.node.type} node not supported by ${renderer.id}` })
+      else if (block.node.type === 'component' && block.node.children) visit(section, block.node.children)
+    }
+  }
+  for (const section of doc.sections) visit(section.id, section.blocks)
+  return skipped
+}
+
+export function renderFinding(compilation: Compilation, severity: Finding['severity'], message: string): Finding {
+  return { checkId: 'presmium.render', severity, message, source: { file: compilation.entry, line: 1 } }
+}

package/src/sections.ts

@@ -0,0 +1,24 @@
+import type { MdastNode } from '@lincyaw/kernel'
+
+export function plainText(node: MdastNode): string {
+  if (typeof node.value === 'string' && !node.children) return node.value
+  return (node.children ?? []).map(plainText).join('')
+}
+
+/**
+ * The section ID a heading's text gives. Unlike the kernel's urlSlug, other characters are dropped rather than
+ * replaced, and only spaces, `_` and `-` become `-`; the IDs of existing documents depend on this rule.
+ */
+export function sectionSlug(text: string): string {
+  return text.normalize('NFKC').toLowerCase()
+    .replace(/[^\p{L}\p{N}\s_-]/gu, '')
+    .trim()
+    .replace(/[\s_-]+/g, '-') || 'section'
+}
+
+export function unique(id: string, used: Set<string>): string {
+  let result = id
+  for (let n = 2; used.has(result); n++) result = `${id}-${n}`
+  used.add(result)
+  return result
+}

package/src/serve.ts

@@ -0,0 +1,95 @@
+import { createReadStream, existsSync } from 'node:fs'
+import { createServer } from 'node:http'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { AddressInfo } from 'node:net'
+import { basename, join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import contentDisposition from 'content-disposition'
+import cors from 'cors'
+import send from 'send'
+
+export type ServedExtra = { file: string, type?: string } | { body: string | Uint8Array, type: string }
+
+export interface StaticServer {
+  url: string
+  close(): Promise<void>
+}
+
+export interface ServeDirectoryOptions {
+  base?: string
+  extra?: Record<string, ServedExtra>
+  /** The origins whose pages may read the files (CORS), e.g. a video's captions from another origin's page. */
+  origins?: string[]
+}
+
+/**
+ * Serves the files of `root` below `base` on a loopback port, and `extra` at their paths. The files go through `send`
+ * (Express's): their types, ranges (a video's player seeks so), validators and conditional requests as HTTP defines them;
+ * `?download` asks for one as an attachment (`content-disposition`), and `origins` may read them (`cors`).
+ */
+export async function serveDirectory(root: string, options: ServeDirectoryOptions = {}): Promise<StaticServer> {
+  const dir = resolve(root)
+  const base = options.base ?? '/'
+  const missing = (response: ServerResponse) => {
+    const page = join(dir, '404.html')
+    response.writeHead(404, existsSync(page) ? { 'Content-Type': 'text/html; charset=utf-8' } : {})
+    if (existsSync(page)) createReadStream(page).pipe(response)
+    else response.end()
+  }
+  const failed = (response: ServerResponse) => (error: { status?: number }) => {
+    if (response.headersSent) return response.destroy()
+    if (error.status === 404) return missing(response)
+    response.writeHead(error.status ?? 500)
+    response.end()
+  }
+  const shared = options.origins?.length ? cors({ origin: options.origins }) : undefined
+  const attached = (request: { url?: string }, file: string) => (response: ServerResponse) => {
+    if (new URL(request.url ?? '/', 'http://localhost').searchParams.has('download')) response.setHeader('Content-Disposition', contentDisposition(basename(file)))
+  }
+  const answer = (request: IncomingMessage, response: ServerResponse) => {
+    const path = new URL(request.url ?? '/', 'http://localhost').pathname
+    let decoded: string
+    try {
+      decoded = decodeURIComponent(path)
+    } catch {
+      response.writeHead(400)
+      response.end()
+      return
+    }
+    const extra = options.extra?.[decoded]
+    if (extra && 'body' in extra) {
+      response.writeHead(200, { 'Content-Type': extra.type })
+      response.end(extra.body)
+      return
+    }
+    if (extra) {
+      if (extra.type) response.setHeader('Content-Type', extra.type)
+      send(request, pathToFileURL(extra.file).pathname, { root: '/', dotfiles: 'allow' }).on('error', failed(response)).pipe(response)
+      return
+    }
+    if (!path.startsWith(base)) return missing(response)
+    send(request, path.slice(base.length - 1), { root: dir })
+      .on('error', failed(response))
+      .on('headers', attached(request, decoded))
+      // A directory's address without its slash: to the one with it, whose index.html is served.
+      .on('directory', () => {
+        response.writeHead(301, { Location: `${path}/${new URL(request.url ?? '/', 'http://localhost').search}` })
+        response.end()
+      })
+      .pipe(response)
+  }
+  const server = createServer((request, response) => {
+    if (shared) shared(request, response, () => answer(request, response))
+    else answer(request, response)
+  })
+  await new Promise<void>(done => server.listen(0, '127.0.0.1', done))
+  return {
+    url: `http://127.0.0.1:${(server.address() as AddressInfo).port}`,
+    close: () => new Promise((done) => {
+      server.close(() => done())
+      server.closeAllConnections()
+    }),
+  }
+}
+
+export { playwrightChromium } from '@lincyaw/kernel/node'

package/src/source-lines.ts

@@ -0,0 +1,47 @@
+import { readFileSync } from 'node:fs'
+import type { SourcePos } from '@lincyaw/kernel'
+import { withoutBom } from './frontmatter.ts'
+
+export type LineFinder = (source: SourcePos, needles: string[]) => number
+
+/** Finds the first line of a source span that contains one of the needles; reads each file once. */
+export function lineFinder(): LineFinder {
+  const files = new Map<string, string[]>()
+  return (source, needles) => {
+    let lines = files.get(source.file)
+    if (!lines) {
+      try {
+        lines = readFileSync(source.file, 'utf8').split(/\r?\n/)
+      } catch {
+        lines = []
+      }
+      files.set(source.file, lines)
+    }
+    for (let line = source.line; line <= Math.min(source.endLine ?? source.line, lines.length); line++) {
+      if (needles.some(needle => needle && lines[line - 1]!.includes(needle))) return line
+    }
+    return source.line
+  }
+}
+
+/** The first line of the span that contains the text, or the span's first line. */
+export function lineContaining(source: SourcePos, text: string): number {
+  return lineFinder()(source, [text])
+}
+
+/** The 1-based line of the text that contains the needle, or 1. */
+export function textLine(text: string, needle: string): number {
+  return firstLineWith(text.split(/\r?\n/), needle)
+}
+
+/** The line of the headmatter that contains the needle, or 1. */
+export function frontmatterLine(text: string, needle: string): number {
+  const lines = withoutBom(text).split(/\r?\n/)
+  const end = lines.indexOf('---', 1)
+  return firstLineWith(lines.slice(0, end < 0 ? undefined : end), needle)
+}
+
+function firstLineWith(lines: string[], needle: string): number {
+  const index = lines.findIndex(line => line.includes(needle))
+  return index < 0 ? 1 : index + 1
+}