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

package/src/forbid.ts

@@ -0,0 +1,82 @@
+import { irBlocks, isRecord, mdastText } from '@lincyaw/kernel'
+import type { Finding, IRBlock, MdastNode, SourcePos } from '@lincyaw/kernel'
+import { lineFinder } from './links.ts'
+import type { PublishInput } from './links.ts'
+import { viewFor } from './renderers.ts'
+
+export function checkForbidden(input: PublishInput, headmatter: Record<string, unknown>): Finding[] {
+  const given = isRecord(headmatter.checks) ? headmatter.checks.forbid : undefined
+  if (given === undefined) return []
+  const line = lineFinder()
+  const at = (needle: string): SourcePos => ({ file: input.entry, line: line({ file: input.entry, line: 1, endLine: Number.MAX_SAFE_INTEGER }, [needle]) })
+  if (!Array.isArray(given) || !given.every(item => typeof item === 'string')) {
+    return [{ checkId: 'presmium.forbid', severity: 'error', message: 'checks.forbid must be a list of regular expressions', source: at('forbid') }]
+  }
+  const findings: Finding[] = []
+  const patterns: { text: string, pattern: RegExp }[] = []
+  for (const text of given) {
+    try {
+      patterns.push({ text, pattern: new RegExp(text, 'g') })
+    } catch (error) {
+      findings.push({ checkId: 'presmium.forbid', severity: 'error', message: `checks.forbid: ${(error as Error).message}`, source: at(text) })
+    }
+  }
+
+  const hits = new Map<string, { source: SourcePos, match: string, pattern: string, renderers: string[] }>()
+  for (const renderer of input.renderers) {
+    const view = viewFor(input.doc, renderer)
+    const texts = view.sections.flatMap(section => [
+      { source: section.source, text: section.title },
+      ...[...irBlocks(section.blocks)].map(block => ({ source: block.source, text: blockText(block) })),
+    ])
+    for (const { source, text } of texts) {
+      for (const { text: name, pattern } of patterns) {
+        for (const [match] of text.matchAll(pattern)) {
+          if (!match) continue
+          const key = `${source.file}\0${source.line}\0${name}\0${match}`
+          const hit = hits.get(key)
+          if (hit && !hit.renderers.includes(renderer)) hit.renderers.push(renderer)
+          else if (!hit) hits.set(key, { source, match, pattern: name, renderers: [renderer] })
+        }
+      }
+    }
+  }
+  for (const { source, match, pattern, renderers } of hits.values()) {
+    findings.push({
+      checkId: 'presmium.forbid',
+      severity: 'error',
+      message: `"${match}" matches ${pattern} of checks.forbid${renderers.length < input.renderers.length ? ` (in ${renderers.join(', ')})` : ''}`,
+      source: { file: source.file, line: line(source, [match]) },
+    })
+  }
+  return findings
+}
+
+function blockText(block: IRBlock): string {
+  const { node } = block
+  switch (node.type) {
+    case 'markdown': return `${mdastText(node.mdast)}\n${targets(node.mdast).join('\n')}`
+    case 'code': return [node.title ?? '', node.value, ...(node.variants ?? []).map(variant => variant.value), ...(node.outputs ?? []).flatMap(outputText)].join('\n')
+    case 'component': return [...propText(node.props), ...node.fallback ? [mdastText(node.fallback)] : []].join('\n')
+  }
+}
+
+function targets(node: MdastNode): string[] {
+  const own = node.type === 'html' ? node.value : node.url
+  return [...typeof own === 'string' ? [own] : [], ...(node.children ?? []).flatMap(targets)]
+}
+
+function outputText(run: NonNullable<Extract<IRBlock['node'], { type: 'code' }>['outputs']>[number]): string[] {
+  return [run.stdout, run.stderr, ...(run.outputs ?? []).flatMap((output) => {
+    if (output.output_type === 'stream') return [output.text]
+    if (output.output_type === 'error') return [output.evalue, ...output.traceback]
+    return Object.entries(output.data).flatMap(([type, value]) => (type.startsWith('text/') || type === 'application/json' ? propText(value) : []))
+  })]
+}
+
+function propText(value: unknown): string[] {
+  if (typeof value === 'string') return [value]
+  if (Array.isArray(value)) return value.flatMap(propText)
+  if (value && typeof value === 'object') return Object.values(value).flatMap(propText)
+  return []
+}

package/src/host.ts

@@ -0,0 +1,56 @@
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { CheckRegistry, errorMessage, irBlocks } from '@lincyaw/kernel'
+import type { CheckContext, Finding, RunResult } from '@lincyaw/kernel'
+import { frontmatterLine } from './compiler.ts'
+import type { Compilation } from './compiler.ts'
+import { build } from './renderers.ts'
+import type { BuildReport } from './renderers.ts'
+
+export function checkContext(compilation: Compilation): CheckContext {
+  return {
+    deckDir: compilation.deckDir,
+    workspaceRoot: compilation.workspaceRoot,
+    headmatter: compilation.frontmatter,
+    src: compilation.src,
+    resolvers: compilation.resolvers,
+    lock: compilation.lock.toJSON(),
+    ir: compilation.doc,
+    service: compilation.service,
+  }
+}
+
+export async function pluginChecks(compilation: Compilation, options: { externalLinks?: boolean } = {}): Promise<Finding[]> {
+  const { entry } = compilation
+  const text = await readFile(entry, 'utf8').catch(() => '')
+  const at = (name: string) => ({ file: entry, line: frontmatterLine(text, name) })
+  const checks = new CheckRegistry()
+  const places = new Map<string, Finding['source']>()
+  const findings: Finding[] = []
+  for (const { name, plugin } of compilation.plugins) {
+    for (const check of plugin?.checks ?? []) {
+      try {
+        checks.register(check)
+        places.set(check.id, at(name))
+      } catch (error) {
+        findings.push({ checkId: 'presmium.plugins', severity: 'error', message: `plugin "${name}": ${errorMessage(error)}`, source: at(name) })
+      }
+    }
+  }
+  for (const finding of await checks.run(checkContext(compilation))) {
+    findings.push(finding.source ? finding : { ...finding, source: places.get(finding.checkId) ?? { file: entry, line: 1 } })
+  }
+  findings.push(...await compilation.publishChecks({ externalLinks: options.externalLinks }))
+  return findings
+}
+
+export async function runBlock(compilation: Compilation, target: { section: string, block: string }, signal?: AbortSignal): Promise<RunResult> {
+  const section = compilation.doc.sections.find(s => s.id === target.section)
+  const block = section && [...irBlocks(section.blocks)].find(b => b.id === target.block)
+  if (!block || block.node.type !== 'code') throw new Error(`no code block ${target.section}/${target.block}`)
+  return compilation.run(block.node, signal)
+}
+
+export function buildView(compilation: Compilation, options: { to?: string[], outDir?: string } = {}): Promise<BuildReport> {
+  return build(compilation, { outDir: options.outDir ?? join(compilation.deckDir, 'dist'), to: options.to })
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+export { audienceView } from './audience.ts'
+export { Compiler, DECK_ENTRY, frontmatterLine, resolveEntry, sortFindings, workspacePlugins } from './compiler.ts'
+export type { Compilation, CompilerOptions } from './compiler.ts'
+export { BUILTIN_DIRECTIVE_INFO, COMMON_DIRECTIVE_OPTIONS, RUN_OPTION } from './directives.ts'
+export type { DirectiveInfo, DirectiveOptionInfo } from './directives.ts'
+export type { RunStats } from './execute.ts'
+export { buildView, checkContext, runBlock } from './host.ts'
+export { portable, relativeIR } from './paths.ts'
+export { findPackageDir, loadPlugins, pluginId } from './plugins.ts'
+export type { LoadedPlugin, PluginProblem, PluginSources } from './plugins.ts'
+export { directoryAsset, fileHash, inside, lineOf, publishesDirectory } from './published.ts'
+export { build, dev, prepare, viewFor } from './renderers.ts'
+export type { BuildOptions, BuildReport } from './renderers.ts'
+export { playwrightChromium, serveDirectory } from './serve.ts'
+export type { ServedExtra, StaticServer } from './serve.ts'
+export { operatorDir, operatorPlugins, pluginLogger, WORKSPACE_CONFIG, workspaceSettings } from './settings.ts'
+export type { OperatorSettings } from './settings.ts'
+export { readFrontmatter } from './source.ts'
+export { compileTranslations } from './translations.ts'
+export type { CompiledTranslation } from './translations.ts'

package/src/links.ts

@@ -0,0 +1,203 @@
+import { execFile, spawnSync } from 'node:child_process'
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { basename, dirname, extname, join, relative, resolve, sep } from 'node:path'
+import { htmlAttributes, irBlocks, isRecord } from '@lincyaw/kernel'
+import type { Finding, IRBlock, IRDocument, MdastNode, SourcePos } from '@lincyaw/kernel'
+import { BUILTIN_DIRECTIVES } from './blocks.ts'
+import { inside, publishesDirectory, unpublishedDirectory } from './published.ts'
+import { viewFor } from './renderers.ts'
+import { plainText, slugify, splitSections } from './sections.ts'
+import { Parser, readFrontmatter } from './source.ts'
+
+export interface PublishInput {
+  doc: IRDocument
+  entry: string
+  deckDir: string
+  workspaceRoot: string
+  renderers: string[]
+}
+
+const REMOTE = /^(?:[a-z][a-z\d+.-]*:|\/\/)/i
+const EXTERNAL = /^https?:\/\//i
+const URL_ATTRIBUTES = new Set(['href', 'src', 'poster'])
+const ID_ATTRIBUTES = new Set(['id', 'name'])
+const LINKED = new Set(['link', 'image', 'definition', 'card'])
+
+interface Problem {
+  source: SourcePos
+  url: string
+  message: string
+  renderers: string[]
+}
+
+export async function checkLinks(input: PublishInput, options: { externalLinks?: boolean } = {}): Promise<Finding[]> {
+  const problems = new Map<string, Problem>()
+  const external = new Map<string, SourcePos>()
+  const documents = new Map<string, Promise<Set<string>>>()
+  for (const renderer of input.renderers) {
+    const view = viewFor(input.doc, renderer)
+    const anchors = documentAnchors(view)
+    for (const section of view.sections) {
+      for (const block of irBlocks(section.blocks)) {
+        for (const url of blockUrls(block)) {
+          if (EXTERNAL.test(url)) {
+            if (!external.has(url)) external.set(url, block.source)
+            continue
+          }
+          const message = await linkProblem(url, block.source, input, anchors, documents)
+          if (!message) continue
+          const key = `${block.source.file}\0${block.source.line}\0${url}`
+          const known = problems.get(key)
+          if (known) known.renderers.push(renderer)
+          else problems.set(key, { source: block.source, url, message, renderers: [renderer] })
+        }
+      }
+    }
+  }
+  const line = lineFinder()
+  const findings = [...problems.values()].map(({ source, url, message, renderers }): Finding => ({
+    checkId: 'presmium.links',
+    severity: 'error',
+    message: `${message}${renderers.length < input.renderers.length ? ` (in ${renderers.join(', ')})` : ''}`,
+    source: { file: source.file, line: line(source, needles(url)) },
+  }))
+  if (options.externalLinks) findings.push(...await externalLinks(external, input.entry, line))
+  return findings
+}
+
+function blockUrls(block: IRBlock): string[] {
+  const { node } = block
+  const urls: string[] = []
+  const walk = (mdast: MdastNode) => {
+    if (LINKED.has(mdast.type) && typeof mdast.url === 'string') urls.push(mdast.url)
+    if (mdast.type === 'html' && typeof mdast.value === 'string') {
+      for (const { value } of htmlAttributes(mdast.value, URL_ATTRIBUTES)) urls.push(value)
+    }
+    mdast.children?.forEach(walk)
+  }
+  if (node.type === 'markdown') walk(node.mdast)
+  if (node.type === 'component') {
+    if (node.fallback) walk(node.fallback)
+    for (const url of Object.values(node.assets ?? {})) urls.push(url)
+  }
+  return urls.map(url => url.trim()).filter(Boolean)
+}
+
+async function linkProblem(url: string, source: SourcePos, input: PublishInput, anchors: Set<string>, documents: Map<string, Promise<Set<string>>>): Promise<string | undefined> {
+  if (REMOTE.test(url)) return undefined
+  const hash = url.indexOf('#')
+  const fragment = hash < 0 ? '' : decode(url.slice(hash + 1))
+  const path = decode((hash < 0 ? url : url.slice(0, hash)).replace(/\?.*$/s, ''))
+  if (!path) return fragment && !anchors.has(fragment) ? `#${fragment} is no section, block, label or heading of the deck` : undefined
+  const file = path.startsWith('/') ? join(input.deckDir, 'public', path) : resolve(dirname(source.file), path)
+  if (!inside(file, input.workspaceRoot)) return `${path} lies outside the repository: it cannot be published`
+  if (!existsSync(file)) return `${path}: no such file`
+  const hidden = publishesDirectory(file, input.deckDir) ? unpublishedDirectory(file, input.deckDir) : undefined
+  if (hidden) return `${path}: ${hidden}`
+  if (!fragment) return undefined
+  const entry = statSync(file).isDirectory() ? join(file, 'lecture.md') : file
+  if (extname(entry) !== '.md' || !existsSync(entry)) return undefined
+  if (entry === input.entry) return anchors.has(fragment) ? undefined : `${path}#${fragment}: #${fragment} is no section, block, label or heading of the deck`
+  if (!documents.has(entry)) documents.set(entry, sourceAnchors(entry))
+  return (await documents.get(entry)!).has(fragment) ? undefined : `${path}#${fragment}: no section, block, label or heading of ${relative(input.workspaceRoot, entry).split(sep).join('/')} has the id ${fragment}`
+}
+
+function documentAnchors(doc: IRDocument): Set<string> {
+  const anchors = new Set<string>()
+  for (const section of doc.sections) {
+    anchors.add(section.id)
+    for (const block of irBlocks(section.blocks)) {
+      anchors.add(block.id)
+      const { node } = block
+      if (node.type === 'markdown') mdastAnchors(node.mdast, anchors)
+      if (node.type === 'component' && node.fallback) mdastAnchors(node.fallback, anchors)
+    }
+  }
+  return anchors
+}
+
+function mdastAnchors(node: MdastNode, anchors: Set<string>): void {
+  for (const key of ['identifier', 'label', 'html_id'] as const) if (typeof node[key] === 'string' && node[key]) anchors.add(node[key] as string)
+  if (node.type === 'footnoteDefinition' && typeof node.identifier === 'string') anchors.add(`fn-${node.identifier}`)
+  if (node.type === 'heading') anchors.add(slugify(plainText(node)))
+  if (node.type === 'mystDirective' && isRecord(node.options) && typeof node.options.label === 'string') anchors.add(node.options.label)
+  if (node.type === 'html' && typeof node.value === 'string') {
+    for (const { value } of htmlAttributes(node.value, ID_ATTRIBUTES)) if (value) anchors.add(value)
+  }
+  node.children?.forEach(child => mdastAnchors(child, anchors))
+}
+
+async function sourceAnchors(entry: string): Promise<Set<string>> {
+  const anchors = new Set<string>()
+  try {
+    const parser = new Parser(new Map([...BUILTIN_DIRECTIVES]))
+    const { children } = await parser.expand(entry)
+    const text = readFileSync(entry, 'utf8')
+    const headmatter = readFrontmatter(text)
+    const depth = Number.isInteger(headmatter.sectionDepth) && (headmatter.sectionDepth as number) >= 1 ? headmatter.sectionDepth as number : 2
+    const title = typeof headmatter.title === 'string' ? headmatter.title : basename(dirname(entry))
+    for (const section of splitSections(children, { entry, title, sectionDepth: depth }, () => {})) anchors.add(section.id)
+    for (const node of children) mdastAnchors(node, anchors)
+  } catch {
+  }
+  return anchors
+}
+
+async function externalLinks(urls: Map<string, SourcePos>, entry: string, line: LineFinder): Promise<Finding[]> {
+  if (urls.size === 0) return []
+  const at = { file: entry, line: 1 }
+  if (spawnSync('lychee', ['--version'], { stdio: 'ignore' }).error) {
+    return [{ checkId: 'presmium.links', severity: 'info', message: `lychee is not installed: ${urls.size === 1 ? 'the external link was' : `the ${urls.size} external links were`} not checked (install lychee, https://lychee.cli.rs, to check them)`, source: at }]
+  }
+  const output = await new Promise<{ stdout: string, error?: Error }>((done) => {
+    const child = execFile('lychee', ['--format', 'json', '--no-progress', '-'], { maxBuffer: 64 << 20 }, (error, stdout) => done({ stdout, ...error ? { error } : {} }))
+    child.stdin?.on('error', () => {})
+    child.stdin?.end(`${[...urls.keys()].join('\n')}\n`)
+  })
+  let report: unknown
+  try {
+    report = JSON.parse(output.stdout)
+  } catch {
+    return [{ checkId: 'presmium.links', severity: 'warning', message: `lychee did not check the external links: ${output.error?.message ?? 'it printed no report'}`, source: at }]
+  }
+  const failed = isRecord(report) ? [report.fail_map, report.error_map].flatMap(map => (isRecord(map) ? Object.values(map).flat() : [])) : []
+  return failed.flatMap((item): Finding[] => {
+    if (!isRecord(item) || typeof item.url !== 'string') return []
+    const source = urls.get(item.url) ?? urls.get(item.url.replace(/\/$/, '')) ?? at
+    const status = isRecord(item.status) && typeof item.status.text === 'string' ? item.status.text : 'failed'
+    return [{ checkId: 'presmium.links', severity: 'warning', message: `${item.url}: ${status}`, source: { file: source.file, line: line(source, [item.url]) } }]
+  })
+}
+
+function needles(url: string): string[] {
+  return [...new Set([url, decode(url)])]
+}
+
+export type LineFinder = (source: SourcePos, needles: string[]) => number
+
+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
+  }
+}
+
+function decode(text: string): string {
+  try {
+    return decodeURIComponent(text)
+  } catch {
+    return text
+  }
+}

package/src/paths.ts

@@ -0,0 +1,56 @@
+import { existsSync, statSync } from 'node:fs'
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { irBlocks } from '@lincyaw/kernel'
+import type { IRDocument, SourcePos } from '@lincyaw/kernel'
+import { fileHash } from './published.ts'
+
+const REMOTE = /^(?:[a-z][a-z\d+.-]*:|\/\/|#)/i
+
+function inRepository(path: string, root: string): boolean {
+  if (!isAbsolute(path)) return false
+  const rel = relative(root, path)
+  return rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel)
+}
+
+function relativePath(from: string, path: string): string {
+  return relative(from, path).split(sep).join('/') || '.'
+}
+
+export function portable(value: unknown, from: string, root: string): unknown {
+  if (typeof value === 'string') return inRepository(value, root) ? relativePath(from, value) : value
+  if (Array.isArray(value)) return value.map(item => portable(item, from, root))
+  if (value !== null && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, portable(item, from, root)]))
+  return value
+}
+
+export function relativeIR(doc: IRDocument, deckDir: string, workspaceRoot: string): IRDocument {
+  const copy = structuredClone(doc)
+  const source = (pos: SourcePos) => {
+    if (isAbsolute(pos.file)) pos.file = relativePath(deckDir, pos.file)
+  }
+  if (isAbsolute(copy.meta.entry)) copy.meta.entry = relativePath(deckDir, copy.meta.entry)
+  copy.config.presmium = portable(copy.config.presmium, deckDir, workspaceRoot) as IRDocument['config']['presmium']
+  for (const section of copy.sections) {
+    source(section.source)
+    if (section.config) section.config = portable(section.config, deckDir, workspaceRoot) as typeof section.config
+    for (const block of irBlocks(section.blocks)) source(block.source)
+  }
+  for (const finding of copy.diagnostics) {
+    if (finding.source) source(finding.source as SourcePos)
+  }
+  return copy
+}
+
+export function localAsset(deckDir: string, source: SourcePos, url: string): { file: string, name: string } | undefined {
+  if (REMOTE.test(url)) return undefined
+  const path = url.replace(/[?#].*$/s, '')
+  if (!path) return undefined
+  let name = path
+  try {
+    name = decodeURIComponent(path)
+  } catch {
+  }
+  const file = name.startsWith('/') ? join(deckDir, 'public', name) : resolve(dirname(source.file), name)
+  if (!existsSync(file) || !statSync(file).isFile()) return undefined
+  return { file, name: `${fileHash(file).slice(0, 8)}-${basename(file)}` }
+}

package/src/plugins.ts

@@ -0,0 +1,178 @@
+import { existsSync, readFileSync, realpathSync } from 'node:fs'
+import { readdir, readFile } from 'node:fs/promises'
+import { dirname, isAbsolute, join, resolve } from 'node:path'
+import { fileURLToPath } 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'
+
+export const NODE_PLUGIN_EXPORT = './presmium'
+
+export interface LoadedPlugin {
+  name: string
+  dir: string
+  plugin?: PresmiumNodePlugin
+}
+
+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/'
+
+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.exports?.[NODE_PLUGIN_EXPORT])
+    if (!target) return { loaded: { name, dir } }
+    const file = join(dir, target)
+    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 } }
+  } 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 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 = /^[^.]+\.(?:vue|[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(value: unknown): string | undefined {
+  if (typeof value === 'string') return value
+  if (!isRecord(value)) return undefined
+  return exportTarget(value.import) ?? exportTarget(value.node) ?? exportTarget(value.default)
+}
+
+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'))
+}