@lincyaw/compiler 1.0.0-rc.0 → 1.0.0-rc.1

package/src/sections.ts

@@ -1,89 +1,15 @@
-import type { Finding, MdastNode, SourcePos } from '@lincyaw/kernel'
-import { fileOf, lineOf, sourceOf } from './source.ts'
-
-export interface RawSection {
-  id: string
-  title: string
-  depth: number
-  source: SourcePos
-  nodes: MdastNode[]
-}
-
-export interface SplitOptions {
-  entry: string
-  title: string
-  sectionDepth: number
-}
-
-interface Draft extends Omit<RawSection, 'id'> {
-  label?: string
-  titled?: boolean
-}
-
-export function splitSections(nodes: MdastNode[], options: SplitOptions, report: (finding: Finding) => void): RawSection[] {
-  const drafts: Draft[] = []
-  let opened = false
-
-  for (const node of nodes) {
-    const current = drafts.at(-1)
-    const depth = node.type === 'heading' && typeof node.depth === 'number' ? node.depth : undefined
-    if (depth !== undefined && depth <= options.sectionDepth && (depth === options.sectionDepth || opened || drafts[0]?.titled)) {
-      opened = true
-      const label = current ? takeLabel(current.nodes) : undefined
-      drafts.push({ label, title: plainText(node), depth, source: sourceOf(node, options.entry), nodes: [] })
-      continue
-    }
-    if (opened && current) {
-      current.nodes.push(node)
-      continue
-    }
-    const cover = current ?? { title: options.title, depth: 0, source: sourceOf(node, options.entry), nodes: [] }
-    if (!current) drafts.push(cover)
-    if (depth !== undefined && depth < options.sectionDepth && !cover.titled) {
-      cover.titled = true
-      cover.label = takeLabel(cover.nodes)
-      cover.title = plainText(node)
-      cover.source = sourceOf(node, options.entry)
-      continue
-    }
-    cover.nodes.push(node)
-  }
-
-  const cover = drafts[0]
-  if (cover?.depth === 0 && !cover.titled && cover.nodes.length === 0) drafts.shift()
-
-  const used = new Set<string>()
-  const labelled = new Set<Draft>()
-  for (const draft of drafts) {
-    if (!draft.label) continue
-    if (used.has(draft.label)) {
-      report({ checkId: 'presmium.sections', severity: 'error', message: `duplicate section label (${draft.label})=`, source: draft.source })
-      continue
-    }
-    used.add(draft.label)
-    labelled.add(draft)
-  }
-  return drafts.map((draft): RawSection => {
-    const { title, depth, source, nodes } = draft
-    const ends = nodes.filter(n => fileOf(n, options.entry) === source.file).map(n => lineOf(n)?.endLine ?? 0)
-    const id = labelled.has(draft) ? draft.label! : unique(draft.label ?? slugify(title), used)
-    return { id, title, depth, source: { ...source, endLine: Math.max(source.line, ...ends) }, nodes }
-  })
-}
-
-function takeLabel(nodes: MdastNode[]): string | undefined {
-  const last = nodes.at(-1)
-  if (last?.type !== 'mystTarget' || typeof last.label !== 'string') return undefined
-  nodes.pop()
-  return last.label
-}
+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('')
 }
 
-export function slugify(text: string): string {
+/**
+ * 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()

package/src/serve.ts

@@ -1,35 +1,12 @@
-import { createReadStream, existsSync, statSync } from 'node:fs'
+import { createReadStream, existsSync } from 'node:fs'
 import { createServer } from 'node:http'
-import { createRequire } from 'node:module'
+import type { IncomingMessage, ServerResponse } from 'node:http'
 import type { AddressInfo } from 'node:net'
-import { extname, join, resolve, sep } from 'node:path'
+import { basename, join, resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
-
-const TYPES: Record<string, string> = {
-  '.html': 'text/html; charset=utf-8',
-  '.js': 'text/javascript',
-  '.mjs': 'text/javascript',
-  '.css': 'text/css',
-  '.json': 'application/json',
-  '.svg': 'image/svg+xml',
-  '.png': 'image/png',
-  '.jpg': 'image/jpeg',
-  '.jpeg': 'image/jpeg',
-  '.gif': 'image/gif',
-  '.webp': 'image/webp',
-  '.ico': 'image/x-icon',
-  '.woff': 'font/woff',
-  '.woff2': 'font/woff2',
-  '.wasm': 'application/wasm',
-  '.wav': 'audio/wav',
-  '.ogg': 'audio/ogg',
-  '.webm': 'video/webm',
-  '.m4a': 'audio/mp4',
-  '.mp3': 'audio/mpeg',
-  '.mp4': 'video/mp4',
-  '.vtt': 'text/vtt',
-  '.txt': 'text/plain; charset=utf-8',
-}
+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 }
 
@@ -38,36 +15,72 @@ export interface StaticServer {
   close(): Promise<void>
 }
 
-export async function serveDirectory(root: string, options: { base?: string, extra?: Record<string, ServedExtra> } = {}): Promise<StaticServer> {
+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 server = createServer((request, response) => {
-    let path: string
+  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 {
-      path = decodeURIComponent(new URL(request.url ?? '/', 'http://localhost').pathname)
+      decoded = decodeURIComponent(path)
     } catch {
       response.writeHead(400)
       response.end()
       return
     }
-    const extra = options.extra?.[path]
+    const extra = options.extra?.[decoded]
     if (extra && 'body' in extra) {
       response.writeHead(200, { 'Content-Type': extra.type })
       response.end(extra.body)
       return
     }
-    let file = extra ? extra.file : path.startsWith(base) ? join(dir, path.slice(base.length)) : undefined
-    if (file && !extra && file !== dir && !file.startsWith(dir + sep)) file = undefined
-    if (file && existsSync(file) && statSync(file).isDirectory()) file = join(file, 'index.html')
-    if (!file || !existsSync(file)) {
-      const missing = join(dir, '404.html')
-      response.writeHead(404, existsSync(missing) ? { 'Content-Type': TYPES['.html']! } : {})
-      if (existsSync(missing)) createReadStream(missing).pipe(response)
-      else response.end()
+    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
     }
-    response.writeHead(200, { 'Content-Type': (extra && 'type' in extra && extra.type) || TYPES[extname(file).toLowerCase()] || 'application/octet-stream' })
-    createReadStream(file).pipe(response)
+    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 {
@@ -79,15 +92,4 @@ export async function serveDirectory(root: string, options: { base?: string, ext
   }
 }
 
-export async function playwrightChromium<T = unknown>(deckDir: string, fallbackFrom?: string): Promise<T> {
-  for (const from of [join(deckDir, 'package.json'), ...fallbackFrom ? [fallbackFrom] : []]) {
-    let entry: string
-    try {
-      entry = createRequire(from).resolve('playwright-chromium')
-    } catch {
-      continue
-    }
-    return (await import(pathToFileURL(entry).href) as { chromium: T }).chromium
-  }
-  throw new Error('this needs playwright-chromium, as `slidev export` does: install it in the deck (and its browser with pnpm exec playwright install chromium)')
-}
+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
+}

package/src/translations.ts

@@ -1,24 +1,23 @@
 import { createHash } from 'node:crypto'
 import { readFileSync, realpathSync, statSync } from 'node:fs'
-import { readFile } from 'node:fs/promises'
-import { basename, dirname, isAbsolute, relative, resolve, sep } from 'node:path'
-import { errorMessage, irBlocks, isRecord } from '@lincyaw/kernel'
-import type { Finding, IRDocument } from '@lincyaw/kernel'
+import { basename, dirname, relative, resolve, sep } from 'node:path'
+import { DOCUMENT_ENTRY, errorMessage, isRecord, validateDocument } from '@lincyaw/kernel'
+import type { Finding, IRDocument, TeachingDocument } from '@lincyaw/kernel'
+import { isInside } from '@lincyaw/kernel/node'
 import type { AudienceCompilation, Compilation, Compiler, CompilerOptions } from './compiler.ts'
-import { readFrontmatter } from './source.ts'
 
 const CHECK_ID = 'presmium.translations'
-
-const ORIGINAL_KEYS = ['plugins', 'presmium', 'renderers', 'execute', 'sectionDepth', 'checks']
+const pointerKey = (key: string) => key.replaceAll('~', '~0').replaceAll('/', '~1')
+const sourceAt = (file: string, pointer: string) => ({ file, line: 1, format: 'json' as const, pointer })
 
 export interface TranslationFields {
   translations?: Record<string, string>
   translationOf?: { entry: string, digest: string }
 }
 
-export function translationFields(headmatter: Record<string, unknown>): TranslationFields {
+export function translationFields(metadata: Record<string, unknown>): TranslationFields {
   const fields: TranslationFields = {}
-  const { translations, translationOf } = headmatter
+  const { translations, translationOf } = metadata
   if (isRecord(translations)) {
     const entries = Object.entries(translations).filter((entry): entry is [string, string] => typeof entry[1] === 'string' && entry[1].length > 0)
     if (entries.length > 0) fields.translations = Object.fromEntries(entries)
@@ -35,66 +34,66 @@ export function applyTranslations(doc: IRDocument, fields: TranslationFields, re
   if (fields.translations) staleTranslations(doc, fields.translations).forEach(report)
 }
 
-function body(text: string): string {
-  return text.replace(/^/, '').replace(/^---[ \t]*\r?\n(?:[\s\S]*?\r?\n)?---[ \t]*(?:\r?\n|$)/, '').replace(/\r\n?/g, '\n').trimEnd()
+function documentValue(text: string): TeachingDocument {
+  const checked = validateDocument(JSON.parse(text.replace(/^\uFEFF/, '')))
+  if (!checked.document) throw new Error(checked.issues.map(issue => `${issue.path || '/'}: ${issue.message}`).join('\n'))
+  return checked.document
+}
+
+function sorted(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sorted)
+  if (isRecord(value)) return Object.fromEntries(Object.keys(value).sort().map(key => [key, sorted(value[key])]))
+  return value
+}
+
+/** Translation bookkeeping and JSON formatting do not change the original's content digest. */
+export function documentDigest(document: TeachingDocument): string {
+  const metadata = { ...document.metadata }
+  delete metadata.translations
+  delete metadata.translationOf
+  return createHash('sha256').update(JSON.stringify(sorted({ ...document, metadata }))).digest('hex')
 }
 
 export function originalDigest(doc: IRDocument): string {
-  const files = [doc.meta.entry]
-  for (const section of doc.sections) {
-    for (const { file } of [section.source, ...[...irBlocks(section.blocks)].map(block => block.source)]) if (!files.includes(file)) files.push(file)
-  }
-  const hash = createHash('sha256').update(doc.meta.title)
-  for (const file of files) {
-    let text: string
-    try {
-      text = readFileSync(file, 'utf8')
-    } catch {
-      continue
-    }
-    hash.update('\0').update(body(text))
-  }
-  return hash.digest('hex')
+  return documentDigest(documentValue(readFileSync(doc.meta.entry, 'utf8')))
 }
 
 function translationFile(deckDir: string, entry: string): string | undefined {
   const file = resolve(deckDir, entry)
+  if (basename(file) !== DOCUMENT_ENTRY) return undefined
   try {
-    const rel = relative(realpathSync(deckDir), realpathSync(file))
-    return statSync(file).isFile() && !rel.startsWith(`..${sep}`) && rel !== '..' && !isAbsolute(rel) ? file : undefined
+    return statSync(file).isFile() && isInside(realpathSync(file), realpathSync(deckDir)) ? file : undefined
   } catch {
     return undefined
   }
 }
 
-function lineWith(text: string, needle: string): number {
-  const index = text.split(/\r?\n/).findIndex(line => line.includes(needle))
-  return index < 0 ? 1 : index + 1
-}
-
 function staleTranslations(doc: IRDocument, translations: Record<string, string>): Finding[] {
   const deckDir = dirname(doc.meta.entry)
   const original = basename(doc.meta.entry)
-  const entryText = readFileSync(doc.meta.entry, 'utf8')
   let digest: string | undefined
   const findings: Finding[] = []
   for (const [lang, entry] of Object.entries(translations)) {
     const file = translationFile(deckDir, entry)
     const name = `translation "${lang}" (${entry})`
-    if (!file) {
-      findings.push({ checkId: CHECK_ID, severity: 'warning', message: `${name} not found in the deck's directory`, source: { file: doc.meta.entry, line: lineWith(entryText, entry) } })
+    if (!file || file === doc.meta.entry) {
+      findings.push({ checkId: CHECK_ID, severity: 'warning', message: `${name} must name a distinct ${DOCUMENT_ENTRY} inside the document's directory`, source: sourceAt(doc.meta.entry, `/metadata/translations/${pointerKey(lang)}`) })
       continue
     }
-    const text = readFileSync(file, 'utf8')
-    digest ??= originalDigest(doc)
-    const { translationOf } = translationFields(readFrontmatter(text))
-    const expected = relative(dirname(file), doc.meta.entry).split(sep).join('/')
-    if (!translationOf) {
-      findings.push({ checkId: CHECK_ID, severity: 'warning', message: `${name} records no digest of the original; once it matches the original, add translationOf: { entry: ${expected}, digest: ${digest} } to its headmatter`, source: { file, line: 1 } })
-    } else if (resolve(dirname(file), translationOf.entry) !== doc.meta.entry) {
-      findings.push({ checkId: CHECK_ID, severity: 'warning', message: `${name} names ${translationOf.entry} as its original, not ${original}`, source: { file, line: lineWith(text, 'entry') } })
-    } else if (translationOf.digest !== digest) {
-      findings.push({ checkId: CHECK_ID, severity: 'warning', message: `${name} is out of date: the original changed since digest ${translationOf.digest.slice(0, 12)}…; check the translation against it, then set translationOf.digest to ${digest}`, source: { file, line: lineWith(text, translationOf.digest) } })
+    const at = (pointer: string) => sourceAt(file, pointer)
+    try {
+      digest ??= originalDigest(doc)
+      const { translationOf } = documentValue(readFileSync(file, 'utf8')).metadata
+      const expected = relative(dirname(file), doc.meta.entry).split(sep).join('/')
+      if (!translationOf) {
+        findings.push({ checkId: CHECK_ID, severity: 'warning', message: `${name} records no digest of the original; once it matches the original, set metadata.translationOf to { entry: ${expected}, digest: ${digest} }`, source: at('/metadata') })
+      } else if (resolve(dirname(file), translationOf.entry) !== doc.meta.entry) {
+        findings.push({ checkId: CHECK_ID, severity: 'warning', message: `${name} names ${translationOf.entry} as its original, not ${original}`, source: at('/metadata/translationOf/entry') })
+      } else if (translationOf.digest !== digest) {
+        findings.push({ checkId: CHECK_ID, severity: 'warning', message: `${name} is out of date: the original changed since digest ${translationOf.digest.slice(0, 12)}…; check the translation against it, then set translationOf.digest to ${digest}`, source: at('/metadata/translationOf/digest') })
+      }
+    } catch (error) {
+      findings.push({ checkId: CHECK_ID, severity: 'error', message: `${name} is not a valid teaching document: ${errorMessage(error)}`, source: at('') })
     }
   }
   return findings
@@ -108,7 +107,7 @@ export interface CompiledTranslation {
 }
 
 export async function compileTranslations(compilation: Compilation, compilers = new Map<string, Compiler>()): Promise<{ translations: CompiledTranslation[], findings: Finding[] }> {
-  const { doc, deckDir, frontmatter } = compilation
+  const { doc, deckDir } = compilation
   const translations: CompiledTranslation[] = []
   const findings: Finding[] = []
   const { Compiler } = await import('./compiler.ts')
@@ -116,23 +115,18 @@ export async function compileTranslations(compilation: Compilation, compilers =
   const audience = compilation.audience?.name
   for (const [lang, entry] of Object.entries(doc.config.translations ?? {})) {
     const file = translationFile(deckDir, entry)
-    if (!file) continue
+    if (!file || file === doc.meta.entry) continue
     try {
-      const own = readFrontmatter(await readFile(file, 'utf8'))
-      const headmatter: Record<string, unknown> = { translations: undefined }
-      for (const key of ORIGINAL_KEYS) headmatter[key] = frontmatter[key]
-      if (!(typeof own.lang === 'string' && own.lang.trim())) headmatter.lang = lang
-      if (own.title === undefined) headmatter.title = doc.meta.title
-      const options: CompilerOptions = { ...base, headmatter, deckDir, ...audience ? { audience } : {} }
+      const options: CompilerOptions = { ...base, ...audience ? { audience } : {} }
       const known = compilers.get(file)
-      const same = known && JSON.stringify(known.options.headmatter) === JSON.stringify(headmatter) && known.options.audience === options.audience
+      const same = known && known.options.audience === options.audience
       const compiler = same ? known : new Compiler(file, options)
       compilers.set(file, compiler)
       const translated = await compiler.compile()
       findings.push(...translated.doc.diagnostics)
-      translations.push({ lang, doc: translated.doc, files: [...new Set([...translated.files, ...translated.dependencies.files])], ...translated.audience ? { audience: translated.audience } : {} })
+      translations.push({ lang, doc: translated.doc, files: [...new Set([...translated.sourceFiles, ...translated.inputs.files])], ...translated.audience ? { audience: translated.audience } : {} })
     } catch (error) {
-      findings.push({ checkId: CHECK_ID, severity: 'error', message: `translation "${lang}" (${entry}) could not be compiled: ${errorMessage(error)}`, source: { file, line: 1 } })
+      findings.push({ checkId: CHECK_ID, severity: 'error', message: `translation "${lang}" (${entry}) could not be compiled: ${errorMessage(error)}`, source: sourceAt(file, '') })
     }
   }
   return { translations, findings }

package/src/validate.ts

@@ -66,6 +66,7 @@ function nodeProblem({ node }: IRBlock): string | undefined {
   if (!isRecord(node)) return 'node is missing'
   switch (node.type) {
     case 'markdown':
+      if (node.narration !== undefined && (!isRecord(node.narration) || !['during', 'after'].includes(String(node.narration.mode)))) return 'narration mode must be during or after'
       return isRecord(node.mdast) ? mdastProblem(node.mdast, 'mdast') : 'markdown node needs an mdast tree'
     case 'code':
       if (typeof node.lang !== 'string' || typeof node.value !== 'string') return 'code node needs lang and value'
@@ -77,8 +78,9 @@ function nodeProblem({ node }: IRBlock): string | undefined {
     case 'component':
       if (typeof node.plugin !== 'string' || typeof node.name !== 'string' || node.name === '') return 'component node needs plugin and name'
       if (!isRecord(node.props)) return 'component props must be an object'
-      if (node.fallback !== undefined) return isRecord(node.fallback) ? mdastProblem(node.fallback, 'fallback') : 'component fallback must be mdast'
       if (node.assets !== undefined && !(isRecord(node.assets) && Object.values(node.assets).every(url => typeof url === 'string'))) return 'component assets must map props to URLs'
+      if (node.durations !== undefined && !(Array.isArray(node.durations) && node.durations.every(ms => typeof ms === 'number' && Number.isFinite(ms) && ms >= 0))) return 'component durations must list non-negative milliseconds'
+      if (node.fallback !== undefined) return isRecord(node.fallback) ? mdastProblem(node.fallback, 'fallback') : 'component fallback must be mdast'
       return undefined
     default:
       return `unknown node type ${String((node as { type?: unknown }).type)}`

package/src/views.ts

@@ -0,0 +1,2 @@
+// The document as one renderer sees it; the kernel holds it, as the web form's server needs it too.
+export { viewFor } from '@lincyaw/kernel'

package/src/workspace-settings.ts

@@ -0,0 +1,59 @@
+import { createHash } from 'node:crypto'
+import { existsSync, readFileSync, realpathSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { errorMessage, isRecord } from '@lincyaw/kernel'
+import { isInside } from '@lincyaw/kernel/node'
+import { parse as parseYaml } from 'yaml'
+
+export const WORKSPACE_CONFIG = 'presmium.workspace.yaml'
+
+export type OperatorSettings = Record<string, Record<string, unknown>>
+
+const cached = new Map<string, { settings: OperatorSettings, problem?: string }>()
+
+export function workspaceSettings(root: string): { settings: OperatorSettings, problem?: string } {
+  const file = join(root, WORKSPACE_CONFIG)
+  const known = cached.get(file)
+  if (known) return known
+  let result: { settings: OperatorSettings, problem?: string } = { settings: {} }
+  if (existsSync(file)) {
+    try {
+      const data: unknown = parseYaml(readFileSync(file, 'utf8'))
+      const settings = isRecord(data) && isRecord(data.settings) ? data.settings : {}
+      const renderers = isRecord(data) && isRecord(data.renderers) ? data.renderers : {}
+      for (const [path, value] of [['renderers.lecture', renderers.lecture], ['settings.presmium.lecture', settings['presmium.lecture']]] as const) {
+        if (isRecord(value) && Object.hasOwn(value, 'script')) throw new Error(`${path}.script: External lecture scripts are not supported. Author narration in each document's lecture.json narrations.`)
+      }
+      result = { settings: Object.fromEntries(Object.entries(settings).map(([id, value]) => [id, isRecord(value) ? value : {}])) }
+    } catch (error) {
+      result = { settings: {}, problem: `${file}: ${errorMessage(error)}` }
+    }
+  }
+  cached.set(file, result)
+  return result
+}
+
+export function operatorPlugins(settings: OperatorSettings): string[] {
+  const list = settings['presmium.workspace']?.plugins
+  return Array.isArray(list) ? list.filter((name): name is string => typeof name === 'string' && name.length > 0) : []
+}
+
+function real(path: string): string {
+  try {
+    return realpathSync(path)
+  } catch {
+    return resolve(path)
+  }
+}
+
+export function operatorDir(workspaceRoot: string, given = process.env.PRESMIUM_OPERATOR_DIR): string {
+  const root = real(workspaceRoot)
+  if (given) {
+    const dir = resolve(given)
+    if (isInside(real(dir), root)) throw new Error(`the operator directory ${dir} lies inside the workspace ${root}; it must be outside every workspace`)
+    return dir
+  }
+  const state = process.env.XDG_STATE_HOME || join(homedir(), '.local', 'state')
+  return join(state, 'presmium', 'operator', createHash('sha256').update(root).digest('hex').slice(0, 16))
+}

package/src/workspace.ts

@@ -1,26 +1,36 @@
 import { execFile } from 'node:child_process'
+import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
-import { isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { dirname, join, relative, resolve, sep } from 'node:path'
 import { promisify } from 'node:util'
 import type { SourceReader } from '@lincyaw/kernel'
+import { isInside } from '@lincyaw/kernel/node'
+import { WORKSPACE_CONFIG } from './workspace-settings.ts'
 
 const run = promisify(execFile)
 
-export const COMMIT = /^(?:[\da-f]{40}|[\da-f]{64})$/i
+export const COMMIT_HASH = /^(?:[\da-f]{40}|[\da-f]{64})$/i
 
 export async function findWorkspaceRoot(dir: string): Promise<string> {
-  return run('git', ['rev-parse', '--show-toplevel'], { cwd: dir })
-    .then(({ stdout }) => resolve(stdout.trim()), () => resolve(dir))
+  const start = resolve(dir)
+  const repository = await run('git', ['rev-parse', '--show-toplevel'], { cwd: start })
+    .then(({ stdout }) => resolve(stdout.trim()), () => undefined)
+  for (let current = start; ; current = dirname(current)) {
+    if (existsSync(join(current, WORKSPACE_CONFIG))) return current
+    if (current === repository || dirname(current) === current) break
+  }
+  return repository ?? start
 }
 
 export function createSourceReader(root: string): SourceReader {
   return {
     async read(file, ref) {
-      const rel = relative(root, resolve(root, file))
-      if (rel === '' || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return undefined
+      const path = resolve(root, file)
+      const rel = relative(root, path)
+      if (rel === '' || !isInside(path, root)) return undefined
       if (ref === undefined) return readFile(join(root, rel), 'utf8').catch(() => undefined)
       if (ref.startsWith('-')) return undefined
-      return run('git', ['show', `${ref}:${rel.split(sep).join('/')}`], { cwd: root, maxBuffer: 64 << 20 })
+      return run('git', ['show', `${ref}:./${rel.split(sep).join('/')}`], { cwd: root, maxBuffer: 64 << 20 })
         .then(({ stdout }) => stdout, () => undefined)
     },
   }