@velumo/compiler 0.1.0-beta.0

package/src/index.ts

@@ -0,0 +1,730 @@
+import { createHash } from "node:crypto";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, extname, isAbsolute, relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import ts from "typescript";
+import type {
+  Asset,
+  VelumoConfig,
+  Fragment,
+  Layer,
+  Manifest,
+  SlideEntry,
+} from "@velumo/core";
+import { deck, markdown, scene, slide, validateManifest } from "@velumo/core";
+
+export class DeckCompilerError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "DeckCompilerError";
+  }
+}
+
+export interface DeckValidationResult {
+  readonly valid: boolean;
+  readonly errors: readonly string[];
+  readonly warnings: readonly string[];
+}
+
+export interface LoadedVelumoConfig {
+  readonly configPath: string;
+  readonly projectRoot: string;
+  readonly config: VelumoConfig;
+  readonly entryPath?: string;
+  readonly outDir?: string;
+}
+
+function compilerCacheRoot(): string {
+  return resolve(process.cwd(), "node_modules", ".cache", "velumo", "compiler");
+}
+
+function cachePathForEntry(entryPath: string, source: string): string {
+  const hash = createHash("sha256")
+    .update(entryPath)
+    .update("\0")
+    .update(source)
+    .digest("hex");
+
+  return resolve(compilerCacheRoot(), `${hash}.mjs`);
+}
+
+function transpileEntry(entryPath: string, source: string): string {
+  const output = ts.transpileModule(source, {
+    fileName: entryPath,
+    compilerOptions: {
+      target: ts.ScriptTarget.ES2022,
+      module: ts.ModuleKind.ES2022,
+      moduleResolution: ts.ModuleResolutionKind.NodeNext,
+      esModuleInterop: true,
+      strict: true,
+    },
+  });
+
+  return output.outputText;
+}
+
+function selectDeckExport(moduleExports: Record<string, unknown>): unknown {
+  if (Object.hasOwn(moduleExports, "default")) {
+    return moduleExports.default;
+  }
+
+  return moduleExports.deck;
+}
+
+function selectConfigExport(moduleExports: Record<string, unknown>): unknown {
+  return Object.hasOwn(moduleExports, "default")
+    ? moduleExports.default
+    : undefined;
+}
+
+async function importTranspiledModule(
+  entryPath: string,
+  source: string,
+): Promise<Record<string, unknown>> {
+  const compiledPath = cachePathForEntry(entryPath, source);
+  await mkdir(dirname(compiledPath), { recursive: true });
+  await writeFile(compiledPath, transpileEntry(entryPath, source));
+
+  return import(pathToFileURL(compiledPath).href) as Promise<
+    Record<string, unknown>
+  >;
+}
+
+function isPreservedAssetSource(src: string): boolean {
+  return (
+    isAbsolute(src) ||
+    src.startsWith("/") ||
+    src.startsWith("http://") ||
+    src.startsWith("https://") ||
+    src.startsWith("data:") ||
+    src.startsWith("blob:")
+  );
+}
+
+function resolveAssetSource(entryPath: string, asset: Asset): Asset {
+  if (isPreservedAssetSource(asset.src)) {
+    return asset;
+  }
+
+  return {
+    ...asset,
+    src: resolve(dirname(entryPath), asset.src),
+  };
+}
+
+function resolveRelativeAssets(
+  manifest: Manifest,
+  entryPath: string,
+): Manifest {
+  if (manifest.assets === undefined) {
+    return manifest;
+  }
+
+  return {
+    ...manifest,
+    assets: manifest.assets.map((asset) =>
+      resolveAssetSource(entryPath, asset),
+    ),
+  };
+}
+
+export async function compileDeck(entryPath: string): Promise<Manifest> {
+  const resolvedEntryPath = resolve(entryPath);
+  let source: string;
+
+  try {
+    source = await readFile(resolvedEntryPath, "utf8");
+  } catch {
+    throw new DeckCompilerError(`deck entry not found: ${resolvedEntryPath}`);
+  }
+
+  const moduleExports = await importTranspiledModule(resolvedEntryPath, source);
+  const candidate = selectDeckExport(moduleExports);
+  const validation = validateManifest(candidate);
+
+  if (!validation.valid) {
+    throw new DeckCompilerError(
+      `invalid deck export: ${validation.errors.join("; ")}`,
+    );
+  }
+
+  return resolveRelativeAssets(candidate as Manifest, resolvedEntryPath);
+}
+
+export async function loadConfig(
+  configPath: string,
+): Promise<LoadedVelumoConfig> {
+  const resolvedConfigPath = resolve(configPath);
+  let source: string;
+
+  try {
+    source = await readFile(resolvedConfigPath, "utf8");
+  } catch {
+    throw new DeckCompilerError(`config not found: ${resolvedConfigPath}`);
+  }
+
+  const moduleExports = await importTranspiledModule(
+    resolvedConfigPath,
+    source,
+  );
+  const candidate = selectConfigExport(moduleExports);
+
+  if (!isRecord(candidate)) {
+    throw new DeckCompilerError(
+      `invalid config default export: ${resolvedConfigPath}`,
+    );
+  }
+
+  const projectRoot = dirname(resolvedConfigPath);
+  const entry = candidate.entry;
+  const outDir = candidate.outDir;
+  const runtime = candidate.runtime;
+  const exportOptions = candidate.export;
+
+  if (entry !== undefined && typeof entry !== "string") {
+    throw new DeckCompilerError(
+      `invalid config field "entry" in ${resolvedConfigPath}`,
+    );
+  }
+
+  if (outDir !== undefined && typeof outDir !== "string") {
+    throw new DeckCompilerError(
+      `invalid config field "outDir" in ${resolvedConfigPath}`,
+    );
+  }
+
+  if (runtime !== undefined && !isRecord(runtime)) {
+    throw new DeckCompilerError(
+      `invalid config field "runtime" in ${resolvedConfigPath}`,
+    );
+  }
+
+  if (exportOptions !== undefined && !isRecord(exportOptions)) {
+    throw new DeckCompilerError(
+      `invalid config field "export" in ${resolvedConfigPath}`,
+    );
+  }
+
+  return {
+    configPath: resolvedConfigPath,
+    projectRoot,
+    config: candidate as VelumoConfig,
+    ...(entry === undefined ? {} : { entryPath: resolve(projectRoot, entry) }),
+    ...(outDir === undefined ? {} : { outDir: resolve(projectRoot, outDir) }),
+  };
+}
+
+const knownLayerTypes = new Set([
+  "html",
+  "markdown",
+  "canvas2d",
+  "three",
+  "hud",
+  "fx",
+  "audio",
+  "video",
+  "debug",
+]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isPathInside(parentPath: string, candidatePath: string): boolean {
+  const relativePath = relative(parentPath, candidatePath);
+
+  return (
+    relativePath === "" ||
+    (!relativePath.startsWith("..") && !isAbsolute(relativePath))
+  );
+}
+
+function isSkippedAssetSource(src: string, entryPath: string): boolean {
+  return (
+    src.startsWith("http://") ||
+    src.startsWith("https://") ||
+    src.startsWith("data:") ||
+    src.startsWith("blob:") ||
+    (src.startsWith("/") && !isPathInside(dirname(entryPath), src))
+  );
+}
+
+async function loadManifestForValidation(entryPath: string): Promise<Manifest> {
+  const extension = extname(entryPath);
+
+  if (extension === ".ts" || extension === ".tsx") {
+    return compileDeck(entryPath);
+  }
+
+  if (extension === ".md" || extension === ".markdown") {
+    return compileMarkdownDeck(entryPath);
+  }
+
+  if (extension !== ".json") {
+    throw new DeckCompilerError(
+      `unsupported deck entry extension: ${extension}`,
+    );
+  }
+
+  try {
+    return JSON.parse(await readFile(entryPath, "utf8")) as Manifest;
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new DeckCompilerError(`invalid JSON manifest: ${entryPath}`);
+    }
+
+    throw new DeckCompilerError(`deck entry not found: ${entryPath}`);
+  }
+}
+
+function collectValidationWarnings(manifest: Manifest): string[] {
+  const warnings: string[] = [];
+
+  if (!Array.isArray(manifest.slides)) {
+    return warnings;
+  }
+
+  manifest.slides.forEach((slideEntry, slideIndex) => {
+    if (!isRecord(slideEntry) || !Array.isArray(slideEntry.layers)) {
+      return;
+    }
+
+    slideEntry.layers?.forEach((layerEntry, layerIndex) => {
+      if (!isRecord(layerEntry) || typeof layerEntry.type !== "string") {
+        return;
+      }
+
+      if (!knownLayerTypes.has(layerEntry.type)) {
+        warnings.push(
+          `unknown layer type: ${layerEntry.type} at slides[${slideIndex}].layers[${layerIndex}]`,
+        );
+      }
+    });
+  });
+
+  return warnings;
+}
+
+function collectCompilerValidationErrors(manifest: Manifest): string[] {
+  const errors: string[] = [];
+  const seenSlideIds = new Set<string>();
+
+  if (!Array.isArray(manifest.slides)) {
+    return errors;
+  }
+
+  if (manifest.slides.length === 0) {
+    errors.push("slides must contain at least one slide or scene");
+  }
+
+  manifest.slides.forEach((slideEntry, slideIndex) => {
+    if (!isRecord(slideEntry)) {
+      return;
+    }
+
+    if (typeof slideEntry.id !== "string") {
+      return;
+    }
+
+    if (seenSlideIds.has(slideEntry.id)) {
+      errors.push(`duplicate slide id: ${slideEntry.id}`);
+    }
+
+    seenSlideIds.add(slideEntry.id);
+
+    if (!Array.isArray(slideEntry.cues)) {
+      return;
+    }
+
+    slideEntry.cues.forEach((cueEntry, cueIndex) => {
+      if (!isRecord(cueEntry)) {
+        return;
+      }
+
+      if (
+        typeof cueEntry.time !== "number" ||
+        !Number.isFinite(cueEntry.time)
+      ) {
+        errors.push(
+          `slides[${slideIndex}].cues[${cueIndex}].time must be a finite number`,
+        );
+      }
+    });
+  });
+
+  return errors;
+}
+
+async function collectAssetErrors(
+  manifest: Manifest,
+  entryPath: string,
+): Promise<string[]> {
+  const errors: string[] = [];
+
+  if (!Array.isArray(manifest.assets)) {
+    return errors;
+  }
+
+  for (const assetEntry of manifest.assets) {
+    if (!isRecord(assetEntry) || typeof assetEntry.src !== "string") {
+      continue;
+    }
+
+    if (isSkippedAssetSource(assetEntry.src, entryPath)) {
+      continue;
+    }
+
+    const assetPath = isAbsolute(assetEntry.src)
+      ? assetEntry.src
+      : resolve(dirname(entryPath), assetEntry.src);
+
+    try {
+      await access(assetPath);
+    } catch {
+      errors.push(`missing asset: ${assetEntry.src}`);
+    }
+  }
+
+  return errors;
+}
+
+export async function validateDeck(
+  entryPath: string,
+): Promise<DeckValidationResult> {
+  const resolvedEntryPath = resolve(entryPath);
+
+  try {
+    const manifest = await loadManifestForValidation(resolvedEntryPath);
+    const baseline = validateManifest(manifest);
+    const errors = [
+      ...baseline.errors,
+      ...collectCompilerValidationErrors(manifest),
+      ...(await collectAssetErrors(manifest, resolvedEntryPath)),
+    ];
+    const warnings = collectValidationWarnings(manifest);
+
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings,
+    };
+  } catch (error) {
+    return {
+      valid: false,
+      errors: [
+        error instanceof Error ? error.message : "unknown validation error",
+      ],
+      warnings: [],
+    };
+  }
+}
+
+interface Line {
+  readonly text: string;
+  readonly number: number;
+}
+
+interface SlideSection {
+  readonly lines: readonly Line[];
+  readonly startLine: number;
+}
+
+interface DirectiveBlock {
+  readonly content: string;
+  readonly endIndex: number;
+}
+
+function parseFrontmatter(lines: readonly Line[]): {
+  readonly metadata: Record<string, string>;
+  readonly bodyStartIndex: number;
+} {
+  if (lines[0]?.text.trim() !== "---") {
+    return { metadata: {}, bodyStartIndex: 0 };
+  }
+
+  const endIndex = lines.findIndex(
+    (line, index) => index > 0 && line.text.trim() === "---",
+  );
+
+  if (endIndex === -1) {
+    throw new DeckCompilerError("frontmatter starting on line 1 is not closed");
+  }
+
+  return {
+    metadata: parseFrontmatterLines(lines.slice(1, endIndex)),
+    bodyStartIndex: endIndex + 1,
+  };
+}
+
+function parseFrontmatterLines(lines: readonly Line[]): Record<string, string> {
+  const metadata: Record<string, string> = {};
+
+  for (const line of lines) {
+    const separatorIndex = line.text.indexOf(":");
+
+    if (separatorIndex > 0) {
+      metadata[line.text.slice(0, separatorIndex).trim()] = line.text
+        .slice(separatorIndex + 1)
+        .trim();
+    }
+  }
+
+  return metadata;
+}
+
+function splitSlideSections(
+  lines: readonly Line[],
+  startIndex: number,
+): readonly SlideSection[] {
+  const sections: SlideSection[] = [];
+  let sectionLines: Line[] = [];
+  let startLine = lines[startIndex]?.number ?? 1;
+
+  for (const line of lines.slice(startIndex)) {
+    if (line.text.trim() === "---") {
+      sections.push({ lines: sectionLines, startLine });
+      sectionLines = [];
+      startLine = line.number + 1;
+      continue;
+    }
+
+    sectionLines.push(line);
+  }
+
+  sections.push({ lines: sectionLines, startLine });
+  return sections;
+}
+
+function trimLines(lines: readonly Line[]): readonly Line[] {
+  let start = 0;
+  let end = lines.length;
+
+  while (start < end && lines[start].text.trim() === "") {
+    start += 1;
+  }
+
+  while (end > start && lines[end - 1].text.trim() === "") {
+    end -= 1;
+  }
+
+  return lines.slice(start, end);
+}
+
+function textFromLines(lines: readonly Line[]): string {
+  return trimLines(lines)
+    .map((line) => line.text)
+    .join("\n");
+}
+
+function firstHeading(lines: readonly Line[]): Line | undefined {
+  return lines.find((line) => /^# (.+)$/.test(line.text));
+}
+
+function slugFromHeading(heading: string): string {
+  return heading
+    .replace(/^#\s+/, "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+function parseDirectiveAttributes(source: string): Record<string, string> {
+  const attributes: Record<string, string> = {};
+
+  for (const match of source.matchAll(/([A-Za-z0-9_-]+)="([^"]*)"/g)) {
+    attributes[match[1]] = match[2];
+  }
+
+  return attributes;
+}
+
+function readDirectiveBlock(
+  lines: readonly Line[],
+  startIndex: number,
+  name: string,
+): DirectiveBlock {
+  const contentLines: Line[] = [];
+
+  for (let index = startIndex + 1; index < lines.length; index += 1) {
+    if (lines[index].text.trim() === ":::") {
+      return {
+        content: textFromLines(contentLines),
+        endIndex: index,
+      };
+    }
+
+    contentLines.push(lines[index]);
+  }
+
+  throw new DeckCompilerError(
+    `${name} directive starting on line ${lines[startIndex].number} is not closed`,
+  );
+}
+
+function parseSceneSection(
+  section: SlideSection,
+  lines: readonly Line[],
+): SlideEntry {
+  const openingLine = lines[0];
+  const attributes = parseDirectiveAttributes(openingLine.text);
+  const block = readDirectiveBlock(lines, 0, "scene");
+  const contentLines = block.content.split("\n").map((text, index) => ({
+    text,
+    number: openingLine.number + 1 + index,
+  }));
+  const heading = firstHeading(contentLines);
+
+  if (!heading) {
+    throw new DeckCompilerError(
+      `empty slide starting on line ${section.startLine}`,
+    );
+  }
+
+  const content = textFromLines(contentLines);
+  const duration =
+    attributes.duration === undefined ? undefined : Number(attributes.duration);
+
+  if (duration !== undefined && !Number.isFinite(duration)) {
+    throw new DeckCompilerError(
+      `scene duration on line ${openingLine.number} must be a finite number`,
+    );
+  }
+
+  return scene(slugFromHeading(heading.text), {
+    ...(duration === undefined ? {} : { duration }),
+    layers: [markdown(content)],
+  });
+}
+
+function parseNormalSlide(
+  section: SlideSection,
+  lines: readonly Line[],
+): SlideEntry {
+  const visibleLines: Line[] = [];
+  const extraLayers: Layer[] = [];
+  const fragments: Fragment[] = [];
+  let notes: string | undefined;
+  let fragmentCount = 0;
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    const trimmed = line.text.trim();
+
+    if (trimmed === ":::notes") {
+      const block = readDirectiveBlock(lines, index, "notes");
+      notes = block.content;
+      index = block.endIndex;
+      continue;
+    }
+
+    if (trimmed === ":::fragment") {
+      const block = readDirectiveBlock(lines, index, "fragment");
+      fragmentCount += 1;
+      const id = `fragment-${fragmentCount}`;
+      extraLayers.push(markdown(block.content, { id }));
+      fragments.push({ id, layerId: id });
+      index = block.endIndex;
+      continue;
+    }
+
+    if (trimmed.startsWith(":::fx ")) {
+      const attributes = parseDirectiveAttributes(trimmed);
+      const { type, ...rest } = attributes;
+      extraLayers.push({
+        type: "fx",
+        props: {
+          ...(type === undefined ? {} : { effect: type }),
+          ...rest,
+        },
+      });
+      continue;
+    }
+
+    visibleLines.push(line);
+  }
+
+  const heading = firstHeading(visibleLines);
+  const content = textFromLines(visibleLines);
+
+  if (!heading || content.trim() === "") {
+    throw new DeckCompilerError(
+      `empty slide starting on line ${section.startLine}`,
+    );
+  }
+
+  return slide(slugFromHeading(heading.text), {
+    layers: [markdown(content), ...extraLayers],
+    ...(fragments.length === 0 ? {} : { fragments }),
+    ...(notes === undefined ? {} : { notes }),
+  });
+}
+
+function parseSlideSection(section: SlideSection): SlideEntry {
+  const lines = trimLines(section.lines);
+
+  if (lines.length === 0) {
+    throw new DeckCompilerError(
+      `empty slide starting on line ${section.startLine}`,
+    );
+  }
+
+  if (lines[0].text.trim().startsWith(":::scene ")) {
+    return parseSceneSection(section, lines);
+  }
+
+  return parseNormalSlide(section, lines);
+}
+
+function assertUniqueMarkdownSlideIds(slides: readonly SlideEntry[]): void {
+  const seen = new Set<string>();
+
+  for (const slideEntry of slides) {
+    if (seen.has(slideEntry.id)) {
+      throw new DeckCompilerError(`duplicate slide id: ${slideEntry.id}`);
+    }
+
+    seen.add(slideEntry.id);
+  }
+}
+
+export async function compileMarkdownDeck(
+  entryPath: string,
+): Promise<Manifest> {
+  const resolvedEntryPath = resolve(entryPath);
+  let source: string;
+
+  try {
+    source = await readFile(resolvedEntryPath, "utf8");
+  } catch {
+    throw new DeckCompilerError(
+      `markdown deck entry not found: ${resolvedEntryPath}`,
+    );
+  }
+
+  const lines = source.split(/\r?\n/).map((text, index) => ({
+    text,
+    number: index + 1,
+  }));
+  const { metadata, bodyStartIndex } = parseFrontmatter(lines);
+  const slides = splitSlideSections(lines, bodyStartIndex).map(
+    parseSlideSection,
+  );
+
+  assertUniqueMarkdownSlideIds(slides);
+
+  const manifest = deck({
+    title: metadata.title ?? "Untitled Deck",
+    slides,
+    ...(metadata.theme === undefined ? {} : { theme: { id: metadata.theme } }),
+  });
+  const validation = validateManifest(manifest);
+
+  if (!validation.valid) {
+    throw new DeckCompilerError(
+      `invalid markdown deck: ${validation.errors.join("; ")}`,
+    );
+  }
+
+  return manifest;
+}