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

package/src/ir.ts

@@ -0,0 +1,318 @@
+import type {
+  AnchorLockFile,
+  AnchorResolverRegistry,
+  AnchorString,
+  ExecuteConfig,
+  Executor,
+  Finding,
+  ResolutionStatus,
+  RunResult,
+  ServiceToken,
+  SourceReader,
+} from './contracts.ts'
+
+export const IR_VERSION = 1
+
+export type RendererId = string
+
+export interface MdastNode {
+  type: string
+  children?: MdastNode[]
+  value?: string
+  [key: string]: unknown
+}
+
+export interface SourcePos {
+  file: string
+  line: number
+  endLine?: number
+}
+
+export interface IRDocument {
+  ir: typeof IR_VERSION
+  meta: {
+    title: string
+    entry: string
+    lang?: string
+    translationOf?: { entry: string, digest: string }
+    [key: string]: unknown
+  }
+  config: {
+    plugins: string[]
+    presmium: Record<string, unknown>
+    renderers: Record<RendererId, Record<string, unknown>>
+    execute?: ExecuteConfig
+    translations?: Record<string, string>
+  }
+  sections: IRSection[]
+  diagnostics: Finding[]
+}
+
+export interface IRSection {
+  id: string
+  index: number
+  title: string
+  depth: number
+  source: SourcePos
+  steps: number
+  stepMap?: number[]
+  hints: Record<RendererId, Record<string, unknown>>
+  config?: Record<string, Record<string, unknown>>
+  blocks: IRBlock[]
+  audience?: string[]
+}
+
+export type BlockRole = 'visual' | 'narration'
+
+export interface IRBlock {
+  id: string
+  role: BlockRole
+  at: number
+  until?: number
+  span?: number
+  only?: RendererId[]
+  audience?: string[]
+  source: SourcePos
+  node: IRNode
+}
+
+export type IRNode = MarkdownNode | CodeNode | ComponentNode
+
+export interface MarkdownNode {
+  type: 'markdown'
+  mdast: MdastNode
+  reveal?: 'items'
+}
+
+export interface CodeOrigin {
+  anchor: AnchorString
+  file: string
+  startLine: number
+  endLine: number
+  pin?: string
+  permalink?: string
+  status: ResolutionStatus
+  units?: Record<string, { startLine: number; endLine: number }>
+  drift?: 'synced' | 'drifted'
+}
+
+export interface RunSpec {
+  lang: string
+  args?: Record<string, string>
+  stdin?: string
+  timeoutMs?: number
+  executor?: string
+  when: 'compile' | 'live' | 'both'
+  session?: string
+}
+
+export interface RecordedRun extends RunResult {
+  cacheKey: string
+}
+
+export interface CodeVariant {
+  label: string
+  value: string
+  permalink?: string
+  startLine?: number
+  endLine?: number
+}
+
+export interface CodeNode {
+  type: 'code'
+  lang: string
+  value: string
+  title?: string
+  origin?: CodeOrigin
+  highlight?: number[][]
+  run?: RunSpec
+  outputs?: RecordedRun[]
+  variants?: CodeVariant[]
+  echo?: false
+}
+
+export interface ComponentNode {
+  type: 'component'
+  plugin: string
+  name: string
+  props: Record<string, unknown>
+  children?: IRBlock[]
+  fallback?: MdastNode
+  assets?: Record<string, string>
+  layer?: 'overlay'
+}
+
+export type DirectiveOptionType = 'string' | 'number' | 'boolean' | 'list'
+
+export interface DirectiveInput {
+  name: string
+  arg?: string
+  options: Record<string, unknown>
+  body: string
+}
+
+export interface DirectiveContext {
+  file: string
+  deckDir: string
+  workspaceRoot: string
+  lang?: string
+  config: Record<string, unknown>
+  source: SourcePos
+  parse(markdown: string): MdastNode
+  report(finding: Finding): void
+  watch(...files: string[]): void
+}
+
+export interface DirectiveResult {
+  node: IRNode
+  role?: BlockRole
+  span?: number
+}
+
+export interface RoleInput {
+  name: string
+  value: string
+  options: Record<string, unknown>
+}
+
+export interface RoleSpec {
+  name: string
+  options?: Record<string, DirectiveOptionType>
+  children?(input: RoleInput, ctx: DirectiveContext): MdastNode[]
+}
+
+export interface PresmiumRoleNode extends MdastNode {
+  type: 'presmiumRole'
+  plugin: string
+  name: string
+  options: Record<string, unknown>
+  children: MdastNode[]
+}
+
+export interface DirectiveSpec {
+  name: string
+  arg?: boolean | 'anchor'
+  body?: boolean
+  options?: Record<string, DirectiveOptionType>
+  toIR(input: DirectiveInput, ctx: DirectiveContext): DirectiveResult | Promise<DirectiveResult>
+}
+
+export interface RunCache {
+  get(key: string): RecordedRun | undefined
+  set(key: string, run: RecordedRun): void
+}
+
+export interface PassContext {
+  deckDir: string
+  workspaceRoot: string
+  lang?: string
+  src: SourceReader
+  resolvers: AnchorResolverRegistry
+  lock: AnchorLockFile
+  executors: Executor[]
+  cache: RunCache
+  config: Record<string, unknown>
+  configFor(section: IRSection): Record<string, unknown>
+  report(finding: Finding): void
+  watch(...files: string[]): void
+  service?<T>(token: ServiceToken<T>): T | undefined
+}
+
+export interface IRPass {
+  name: string
+  order?: number
+  after?: 'execute'
+  run(doc: IRDocument, ctx: PassContext): void | Promise<void>
+}
+
+export type Support = 'full' | 'degraded' | 'none'
+
+export interface RenderContext {
+  deckDir: string
+  workspaceRoot: string
+  outDir: string
+  workDir: string
+  config: Record<string, unknown>
+  extensions: RendererExtension[]
+  plugins: string[]
+  pluginDirs: Record<string, string>
+  lang?: string
+  renderers: RendererId[]
+  base: string
+  vitePlugins: unknown[]
+  extensionFor(node: ComponentNode): ((node: ComponentNode, block: IRBlock) => unknown) | undefined
+  portable(value: unknown, from: string): unknown
+  localAsset(source: SourcePos, url: string): LocalAsset | undefined
+  documentLink?(source: SourcePos, url: string): DocumentLink | undefined
+  report(finding: Finding): void
+  service?<T>(token: ServiceToken<T>): T | undefined
+  translations?: { lang: string, doc: IRDocument }[]
+  server?: { url: string }
+  preview?: { origins: string[] }
+}
+
+export interface LocalAsset {
+  file: string
+  name: string
+  directory?: boolean
+}
+
+export interface DocumentLink {
+  dir: string
+  fragment?: string
+}
+
+export interface RenderOutput {
+  outDir: string
+  skipped: { section: string; block: string; reason: string }[]
+}
+
+export interface RenderDevServer {
+  url: string
+  update(doc: IRDocument): Promise<void>
+  close(): Promise<void>
+}
+
+export interface Renderer {
+  id: RendererId
+  site?: boolean
+  support(node: IRNode, extensions: RendererExtension[]): Support
+  prepare?(doc: IRDocument, ctx: RenderContext): Promise<void>
+  build(doc: IRDocument, ctx: RenderContext): Promise<RenderOutput>
+  dev?(doc: IRDocument, ctx: RenderContext): Promise<RenderDevServer>
+  buildSite?(site: SiteSpec, ctx: RenderContext): Promise<RenderOutput>
+  devSite?(site: SiteSpec, ctx: RenderContext, compile: (dir: string) => Promise<IRDocument>): Promise<SiteDevServer>
+}
+
+export interface SiteDocument {
+  dir: string
+  title: string
+  lang?: string
+  tags?: string[]
+  doc?: IRDocument
+  translations?: { lang: string, doc: IRDocument }[]
+}
+
+export interface SiteSpec {
+  title: string
+  documents: SiteDocument[]
+  home?: string
+  config: Record<string, unknown>
+}
+
+export interface SiteDevServer {
+  url: string
+  update(dir: string, doc: IRDocument): Promise<void>
+  close(): Promise<void>
+}
+
+export type ComponentRenderer = (node: ComponentNode, block: IRBlock, ctx: RenderContext) => unknown
+
+export interface RendererContribution {
+  components?: Record<string, ComponentRenderer>
+}
+
+export interface RendererExtension {
+  plugin: string
+  components?: Record<string, (node: ComponentNode, block: IRBlock) => unknown>
+}

package/src/kernel.ts

@@ -0,0 +1,177 @@
+import { KERNEL_VERSION } from './contracts.ts'
+import type {
+  EnvironmentSpec,
+  EventBus,
+  KernelEvent,
+  Logger,
+  PluginContext,
+  PluginDefinition,
+  PluginReport,
+  PresentationMode,
+  ServiceToken,
+  StartReport,
+} from './contracts.ts'
+import { errorMessage } from './errors.ts'
+import { createEventBus } from './events.ts'
+import { prefixed } from './logging.ts'
+import { ServiceRegistry } from './services.ts'
+
+export interface KernelOptions {
+  mode: PresentationMode
+  config?: Record<string, unknown>
+  log?: Logger
+  events?: EventBus
+  environments?: Record<string, EnvironmentSpec>
+}
+
+export class Kernel {
+  readonly version = KERNEL_VERSION
+  readonly mode: PresentationMode
+  readonly services = new ServiceRegistry()
+  readonly events: EventBus
+  #log: Logger
+  #config: Record<string, unknown>
+  #environments?: Readonly<Record<string, EnvironmentSpec>>
+  #plugins: PluginDefinition[] = []
+  #state: 'idle' | 'starting' | 'started' | 'disposed' = 'idle'
+  #report?: StartReport
+
+  constructor(options: KernelOptions) {
+    this.mode = options.mode
+    this.#config = options.config ?? {}
+    this.#environments = options.environments && Object.freeze({ ...options.environments })
+    this.#log = options.log ?? console
+    this.events = options.events ?? createEventBus((error, event) => {
+      this.#log.error(`[presmium] handler for "${event.type}" threw`, error)
+    })
+  }
+
+  register(plugin: PluginDefinition): void {
+    if (this.#state !== 'idle') throw new Error(`cannot register ${plugin.manifest.id}: kernel already started`)
+    if (this.#plugins.some(p => p.manifest.id === plugin.manifest.id)) {
+      throw new Error(`plugin ${plugin.manifest.id} is already registered`)
+    }
+    this.#plugins.push(plugin)
+  }
+
+  provide<T>(token: ServiceToken<T>, impl: T): void {
+    this.services.provide(token, impl)
+  }
+
+  getService<T>(token: ServiceToken<T>): T | undefined {
+    return this.services.tryGet(token)
+  }
+
+  report(): StartReport | undefined {
+    return this.#report
+  }
+
+  async start(): Promise<StartReport> {
+    if (this.#state !== 'idle') throw new Error('kernel already started')
+    this.#state = 'starting'
+    const plan = this.services.plan(this.#plugins.map(p => p.manifest), this.version)
+    const reports = new Map<string, PluginReport>()
+    for (const [id, reason] of plan.excluded) reports.set(id, this.#disable(id, reason))
+
+    const order: string[] = []
+    for (const id of plan.order) {
+      const plugin = this.#plugins.find(p => p.manifest.id === id)!
+      const unavailable = (plugin.manifest.requires ?? []).filter(r => !this.services.has(r.token))
+      const missing = unavailable.map(r => r.token.id)
+      if (unavailable.some(r => !r.optional)) {
+        const required = unavailable.filter(r => !r.optional).map(r => r.token.id)
+        reports.set(id, this.#disable(id, `missing required services: ${required.join(', ')}`, missing))
+        continue
+      }
+      order.push(id)
+      reports.set(id, await this.#setup(plugin, missing))
+    }
+
+    this.#report = { order, plugins: this.#plugins.map(p => reports.get(p.manifest.id)!), cycles: plan.cycles }
+    this.#state = 'started'
+    return this.#report
+  }
+
+  async dispose(): Promise<void> {
+    if (this.#state === 'disposed') return
+    this.#state = 'disposed'
+    const running = new Set(
+      this.#report?.plugins.filter(r => r.status === 'started' || r.status === 'degraded').map(r => r.id),
+    )
+    for (const id of [...(this.#report?.order ?? [])].reverse()) {
+      if (!running.has(id)) continue
+      const plugin = this.#plugins.find(p => p.manifest.id === id)!
+      try {
+        await plugin.dispose?.()
+      } catch (error) {
+        this.#log.error(`[presmium] ${id} dispose failed`, error)
+      }
+      this.services.revoke(id)
+    }
+  }
+
+  async #setup(plugin: PluginDefinition, missing: string[]): Promise<PluginReport> {
+    const { id, provides = [] } = plugin.manifest
+    try {
+      await plugin.setup(this.#context(plugin))
+      const unprovided = provides.filter(t => this.services.owner(t) !== id).map(t => t.id)
+      if (unprovided.length > 0) throw new Error(`declared but did not provide: ${unprovided.join(', ')}`)
+    } catch (error) {
+      this.services.revoke(id)
+      const reason = errorMessage(error)
+      this.#log.error(`[presmium] ${id} failed to start`, error)
+      this.#emit({ type: 'kernel.plugin.failed', payload: { id, error: reason } })
+      return { id, status: 'failed', reason }
+    }
+    if (missing.length > 0) {
+      this.#log.warn(`[presmium] ${id} started without optional services: ${missing.join(', ')}`)
+      this.#emit({ type: 'kernel.plugin.degraded', payload: { id, missing } })
+      return { id, status: 'degraded', reason: `optional services unavailable: ${missing.join(', ')}`, missing }
+    }
+    this.#emit({ type: 'kernel.plugin.started', payload: { id } })
+    return { id, status: 'started' }
+  }
+
+  #disable(id: string, reason: string, missing?: string[]): PluginReport {
+    this.#log.warn(`[presmium] ${id} disabled: ${reason}`)
+    this.#emit({ type: 'kernel.plugin.disabled', payload: { id, reason } })
+    return missing ? { id, status: 'disabled', reason, missing } : { id, status: 'disabled', reason }
+  }
+
+  #emit(event: KernelEvent): void {
+    this.events.emit(event)
+  }
+
+  #context(plugin: PluginDefinition): PluginContext {
+    const { id, provides = [], requires = [] } = plugin.manifest
+    const declared = new Set([...requires.map(r => r.token.id), ...provides.map(t => t.id)])
+    const assertDeclared = (token: ServiceToken<unknown>) => {
+      if (!declared.has(token.id)) throw new Error(`${id} did not declare service ${token.id} in its manifest`)
+    }
+    return {
+      config: pluginConfig(this.#config[id]),
+      mode: this.mode,
+      provide: (token, impl) => {
+        if (!provides.some(t => t.id === token.id)) {
+          throw new Error(`${id} provides ${token.id} without declaring it in manifest.provides`)
+        }
+        this.services.provide(token, impl, id)
+      },
+      get: token => {
+        assertDeclared(token)
+        return this.services.get(token)
+      },
+      tryGet: token => {
+        assertDeclared(token)
+        return this.services.tryGet(token)
+      },
+      events: this.events,
+      log: prefixed(this.#log, id),
+      ...this.#environments ? { environments: this.#environments } : {},
+    }
+  }
+}
+
+function pluginConfig(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) ? { ...value } : {}
+}

package/src/lock.ts

@@ -0,0 +1,85 @@
+import { isRenderable } from './contracts.ts'
+import type { AnchorLockFile, RecordedAnchor, Resolution } from './contracts.ts'
+import { errorMessage } from './errors.ts'
+
+export const ANCHOR_LOCK_PATH = '.presmium/anchors.lock.json'
+
+export class AnchorLock {
+  #anchors = new Map<string, RecordedAnchor>()
+
+  private constructor(anchors: Iterable<[string, RecordedAnchor]>) {
+    for (const [anchor, recorded] of anchors) this.set(anchor, recorded)
+  }
+
+  static empty(): AnchorLock {
+    return new AnchorLock([])
+  }
+
+  static from(file: AnchorLockFile): AnchorLock {
+    return new AnchorLock(Object.entries(file.anchors))
+  }
+
+  static parse(text: string | undefined): AnchorLock {
+    if (text === undefined || text.trim() === '') return AnchorLock.empty()
+    let data: unknown
+    try {
+      data = JSON.parse(text)
+    } catch (error) {
+      throw new Error(`invalid anchor lock: ${errorMessage(error)}`)
+    }
+    return AnchorLock.from(validate(data))
+  }
+
+  get size(): number {
+    return this.#anchors.size
+  }
+
+  get(anchor: string): RecordedAnchor | undefined {
+    return this.#anchors.get(anchor)
+  }
+
+  set(anchor: string, recorded: RecordedAnchor): void {
+    this.#anchors.set(anchor, { fingerprint: recorded.fingerprint, file: recorded.file, startLine: recorded.startLine })
+  }
+
+  record(anchor: string, resolution: Resolution): boolean {
+    const { location, fingerprint } = resolution
+    if (!isRenderable(resolution) || !location || !fingerprint) return false
+    this.set(anchor, { fingerprint, file: location.file, startLine: location.startLine })
+    return true
+  }
+
+  retain(anchors: Iterable<string>): void {
+    const keep = new Set(anchors)
+    for (const anchor of [...this.#anchors.keys()]) {
+      if (!keep.has(anchor)) this.#anchors.delete(anchor)
+    }
+  }
+
+  toJSON(): AnchorLockFile {
+    const keys = [...this.#anchors.keys()].sort()
+    return { version: 1, anchors: Object.fromEntries(keys.map(k => [k, this.#anchors.get(k)!])) }
+  }
+
+  serialize(): string {
+    return `${JSON.stringify(this.toJSON(), null, 2)}\n`
+  }
+}
+
+function validate(data: unknown): AnchorLockFile {
+  if (!isObject(data) || data.version !== 1 || !isObject(data.anchors)) {
+    throw new Error('invalid anchor lock: expected { "version": 1, "anchors": { ... } }')
+  }
+  for (const [anchor, record] of Object.entries(data.anchors)) {
+    const valid = isObject(record)
+      && typeof record.fingerprint === 'string' && record.fingerprint !== ''
+      && typeof record.file === 'string'
+      && Number.isInteger(record.startLine) && (record.startLine as number) >= 1
+    if (!valid) throw new Error(`invalid anchor lock: bad record for "${anchor}"`)
+  }
+  return data as unknown as AnchorLockFile
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}

package/src/logging.ts

@@ -0,0 +1,11 @@
+import type { Logger } from './contracts.ts'
+
+export function prefixed(log: Logger, id: string): Logger {
+  const tag = `[${id}]`
+  return {
+    debug: (...args) => log.debug(tag, ...args),
+    info: (...args) => log.info(tag, ...args),
+    warn: (...args) => log.warn(tag, ...args),
+    error: (...args) => log.error(tag, ...args),
+  }
+}