@hraness/dawg 0.2.0 → 0.3.0

package/core/sdk/eval.ts

@@ -0,0 +1,257 @@
+/**
+ * Evaluates a project's `song.ts` in a sandboxed Bun subprocess and parses
+ * the result from `unknown` into a validated `TrackScore`.
+ *
+ * The child runs `eval-child.ts` with a scrubbed environment, the project as
+ * its working directory, no native addons or auto-install, a 10 second
+ * budget and a 1 MiB output bound. Anything it prints that is not the
+ * expected JSON line is a diagnostic.
+ */
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { decodeLoopDocument } from "../loop.ts";
+import { ScoreValidationError, TrackScore } from "../score.ts";
+
+export const EVAL_TIMEOUT_MS = 10_000;
+export const EVAL_MAX_OUTPUT_BYTES = 1024 * 1024;
+
+/** A problem in a project file; `file` is project-relative when known. */
+export type Diagnostic = Readonly<{
+  message: string;
+  file?: string;
+  line?: number;
+  col?: number;
+}>;
+
+export type EvalResult =
+  | Readonly<{ ok: true; score: TrackScore; ms: number }>
+  | Readonly<{ ok: false; diagnostics: readonly Diagnostic[]; ms: number }>;
+
+/** How the evaluator starts its child; tests inject a scripted one. */
+export type EvalSpawn = (
+  args: readonly string[],
+  options: Readonly<{
+    cwd: string;
+    env: Readonly<Record<string, string>>;
+    timeoutMs: number;
+    maxOutputBytes: number;
+  }>,
+) => Promise<
+  Readonly<{ code: number; stdout: string; stderr: string; killed: boolean }>
+>;
+
+export type EvalOptions = Readonly<{
+  spawn?: EvalSpawn;
+  timeoutMs?: number;
+}>;
+
+const CHILD = join(dirname(fileURLToPath(import.meta.url)), "eval-child.ts");
+
+/** Evaluates `<project>/song.ts`; never throws for project errors. */
+export async function evaluateProject(
+  project: string,
+  options: EvalOptions = {},
+): Promise<EvalResult> {
+  const started = performance.now();
+  const spawn = options.spawn ?? bunSpawn;
+  const env: Record<string, string> = {};
+  for (const key of ["PATH", "HOME", "TMPDIR"]) {
+    const value = process.env[key];
+    if (value !== undefined) env[key] = value;
+  }
+  env.NO_COLOR = "1";
+  const done = (result: EvalResult): EvalResult => result;
+  let run: Awaited<ReturnType<EvalSpawn>>;
+  try {
+    run = await spawn(
+      [
+        process.execPath,
+        "--no-addons",
+        "--no-install",
+        "--smol",
+        CHILD,
+        project,
+      ],
+      {
+        cwd: project,
+        env,
+        timeoutMs: options.timeoutMs ?? EVAL_TIMEOUT_MS,
+        maxOutputBytes: EVAL_MAX_OUTPUT_BYTES,
+      },
+    );
+  } catch (error) {
+    return done(
+      failure(started, [{ message: `could not start bun: ${text(error)}` }]),
+    );
+  }
+  if (run.killed)
+    return done(
+      failure(started, [
+        {
+          file: "song.ts",
+          message: "evaluation timed out (10 s); song.ts must be pure",
+        },
+      ]),
+    );
+  const line = lastJsonLine(run.stdout);
+  if (line === undefined) {
+    const detail = (run.stderr || run.stdout)
+      .trim()
+      .split("\n")
+      .slice(0, 8)
+      .join("\n");
+    return done(
+      failure(started, [
+        {
+          file: "song.ts",
+          message: detail
+            ? `evaluation exited with code ${run.code}: ${detail}`
+            : `evaluation exited with code ${run.code}`,
+        },
+      ]),
+    );
+  }
+  return done(parseChildOutput(line, started));
+}
+
+/** Parses the child's JSON line from `unknown`; exported for tests. */
+export function parseChildOutput(
+  line: string,
+  started = performance.now(),
+): EvalResult {
+  let value: unknown;
+  try {
+    value = JSON.parse(line);
+  } catch {
+    return failure(started, [
+      { file: "song.ts", message: "evaluation printed invalid JSON" },
+    ]);
+  }
+  if (typeof value !== "object" || value === null)
+    return failure(started, [
+      { file: "song.ts", message: "evaluation printed no result" },
+    ]);
+  const record = value as Record<string, unknown>;
+  if (record.ok !== true) {
+    const error =
+      typeof record.error === "object" && record.error !== null
+        ? (record.error as Record<string, unknown>)
+        : {};
+    const diagnostic: {
+      message: string;
+      file?: string;
+      line?: number;
+      col?: number;
+    } = {
+      message:
+        typeof error.message === "string" && error.message.length > 0
+          ? error.message.slice(0, 2000)
+          : "song.ts threw",
+    };
+    if (typeof error.file === "string")
+      diagnostic.file = error.file.slice(0, 512);
+    if (typeof error.line === "number" && Number.isInteger(error.line))
+      diagnostic.line = error.line;
+    if (typeof error.col === "number" && Number.isInteger(error.col))
+      diagnostic.col = error.col;
+    return failure(started, [diagnostic]);
+  }
+  try {
+    const score = decodeLoopDocument(record.score);
+    return { ok: true, score, ms: elapsed(started) };
+  } catch (error) {
+    return failure(started, [
+      {
+        file: "song.ts",
+        message:
+          error instanceof ScoreValidationError
+            ? `invalid score: ${error.message}`
+            : `invalid score: ${text(error)}`,
+      },
+    ]);
+  }
+}
+
+/** `file:line:col message` for humans; file-less diagnostics print the message alone. */
+export function formatDiagnostic(diagnostic: Diagnostic): string {
+  if (!diagnostic.file) return diagnostic.message;
+  const where =
+    diagnostic.line === undefined
+      ? diagnostic.file
+      : `${diagnostic.file}:${diagnostic.line}:${diagnostic.col ?? 1}`;
+  return `${where} ${diagnostic.message}`;
+}
+
+function failure(
+  started: number,
+  diagnostics: readonly Diagnostic[],
+): EvalResult {
+  return {
+    ok: false,
+    diagnostics: Object.freeze(diagnostics.map((d) => Object.freeze({ ...d }))),
+    ms: elapsed(started),
+  };
+}
+
+function elapsed(started: number): number {
+  return Math.round(performance.now() - started);
+}
+
+function text(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function lastJsonLine(stdout: string): string | undefined {
+  const lines = stdout.split("\n").map((line) => line.trim());
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    const line = lines[index]!;
+    if (line.startsWith('{"ok":')) return line;
+  }
+  return undefined;
+}
+
+/** Default spawner: `Bun.spawn` with the given env only (no inheritance). */
+export const bunSpawn: EvalSpawn = async (args, options) => {
+  const child = Bun.spawn([...args], {
+    cwd: options.cwd,
+    env: options.env,
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  let killed = false;
+  const timer = setTimeout(() => {
+    killed = true;
+    child.kill();
+  }, options.timeoutMs);
+  const read = async (stream: ReadableStream<Uint8Array> | null) => {
+    if (!stream) return "";
+    const chunks: Uint8Array[] = [];
+    let total = 0;
+    const reader = stream.getReader();
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done || !value) break;
+      if (total + value.byteLength > options.maxOutputBytes) {
+        killed = true;
+        child.kill();
+        break;
+      }
+      chunks.push(value);
+      total += value.byteLength;
+    }
+    reader.releaseLock();
+    return Buffer.concat(chunks).toString("utf8");
+  };
+  try {
+    const [stdout, stderr, code] = await Promise.all([
+      read(child.stdout),
+      read(child.stderr),
+      child.exited,
+    ]);
+    return { code, stdout, stderr, killed };
+  } finally {
+    clearTimeout(timer);
+  }
+};

package/core/sdk/print.ts

@@ -0,0 +1,393 @@
+/**
+ * Deterministic printer: score → `song.ts` + `tracks/<slug>/track.ts`.
+ *
+ * Output is already in prettier's shape (80 columns, double quotes, trailing
+ * commas, two-space indent, objects kept expanded) so formatting it again is
+ * a no-op, and printing the evaluation of a printed project reproduces the
+ * same bytes. Note ids are never printed: `song()` derives them from content.
+ */
+
+import { DRUM_VOICES, isDrumInstrument } from "../drums.ts";
+import { midiToPitch } from "../pitch.ts";
+import {
+  isSamplerInstrument,
+  samplerVoiceSlots,
+  TrackScore,
+  type AutomationPoint,
+  type Note,
+  type SampleRef,
+  type Sampler,
+  type Track,
+} from "../score.ts";
+import { trackSlug } from "../slug.ts";
+import { DEFAULT_HIT_LENGTH, DEFAULT_VELOCITY } from "./v1.ts";
+
+const WIDTH = 80;
+const INDENT = "  ";
+
+/** One file the printer produces, path relative to the project root. */
+export type PrintedFile = Readonly<{ path: string; text: string }>;
+
+/** Everything a project needs for a score: `song.ts` first, then one file per track in score order. */
+export type PrintedProject = Readonly<{
+  files: readonly PrintedFile[];
+  /** Track id → `tracks/<dir>/track.ts`. */
+  trackFiles: ReadonlyMap<string, string>;
+}>;
+
+/** Directory under `tracks/` for each track, unique in score order. */
+export function trackDirectories(
+  score: TrackScore,
+): ReadonlyMap<string, string> {
+  const used = new Set<string>();
+  const out = new Map<string, string>();
+  for (const track of score.tracks) {
+    const base = trackSlug(track.name);
+    let dir = base;
+    for (let n = 2; used.has(dir); n += 1) dir = `${base}-${n}`;
+    used.add(dir);
+    out.set(track.id, dir);
+  }
+  return out;
+}
+
+/** Prints the whole project. Pure; returns frozen data. */
+export function printProject(score: TrackScore): PrintedProject {
+  const dirs = trackDirectories(score);
+  const trackFiles = new Map<string, string>();
+  const files: PrintedFile[] = [
+    Object.freeze({ path: "song.ts", text: printSong(score, dirs) }),
+  ];
+  for (const track of score.tracks) {
+    const path = `tracks/${dirs.get(track.id)!}/track.ts`;
+    trackFiles.set(track.id, path);
+    files.push(Object.freeze({ path, text: printTrack(score, track) }));
+  }
+  return Object.freeze({ files: Object.freeze(files), trackFiles });
+}
+
+const RESERVED = new Set([
+  "break",
+  "case",
+  "catch",
+  "class",
+  "const",
+  "continue",
+  "debugger",
+  "default",
+  "delete",
+  "do",
+  "else",
+  "enum",
+  "export",
+  "extends",
+  "false",
+  "finally",
+  "for",
+  "function",
+  "if",
+  "import",
+  "in",
+  "instanceof",
+  "new",
+  "null",
+  "return",
+  "super",
+  "switch",
+  "this",
+  "throw",
+  "true",
+  "try",
+  "typeof",
+  "var",
+  "void",
+  "while",
+  "with",
+  "yield",
+  "let",
+  "static",
+  "implements",
+  "interface",
+  "package",
+  "private",
+  "protected",
+  "public",
+  "await",
+  "song",
+  "track",
+  "note",
+  "seq",
+  "hit",
+  "hits",
+  "every",
+  "sampler",
+  "slices",
+]);
+
+/** Import identifiers for each track, unique in score order. */
+export function trackIdentifiers(
+  score: TrackScore,
+  dirs: ReadonlyMap<string, string> = trackDirectories(score),
+): ReadonlyMap<string, string> {
+  const used = new Set<string>();
+  const out = new Map<string, string>();
+  for (const track of score.tracks) {
+    let base = dirs.get(track.id)!.replace(/-/g, "_");
+    if (!/^[a-z_]/.test(base) || RESERVED.has(base)) base = `track_${base}`;
+    let name = base;
+    for (let n = 2; used.has(name); n += 1) name = `${base}_${n}`;
+    used.add(name);
+    out.set(track.id, name);
+  }
+  return out;
+}
+
+/** `song.ts` for a score. */
+export function printSong(
+  score: TrackScore,
+  dirs: ReadonlyMap<string, string> = trackDirectories(score),
+): string {
+  const ids = trackIdentifiers(score, dirs);
+  const lines: string[] = ['import { song } from "dawg";'];
+  for (const track of score.tracks)
+    lines.push(
+      `import ${ids.get(track.id)!} from "./tracks/${dirs.get(track.id)!}/track.ts";`,
+    );
+  lines.push("");
+  const entries: string[] = [
+    `tempo: ${num(score.tempoBpm)}`,
+    `meter: [${num(score.beatsPerBar)}, 4]`,
+    `bars: ${num(score.bars)}`,
+  ];
+  if (score.key !== null) entries.push(`key: ${str(score.key)}`);
+  if (score.ticksPerBeat !== 480)
+    entries.push(`ticksPerBeat: ${num(score.ticksPerBeat)}`);
+  entries.push(
+    `tracks: ${list(
+      score.tracks.map((track) => ids.get(track.id)!),
+      INDENT,
+      "tracks: ".length,
+      1,
+    )}`,
+  );
+  lines.push("export default song({");
+  for (const entry of entries) lines.push(`${INDENT}${entry},`);
+  lines.push("});", "");
+  return lines.join("\n");
+}
+
+/** `tracks/<slug>/track.ts` for one track of a score. */
+export function printTrack(score: TrackScore, track: Track): string {
+  const notes = score.notes.filter((note) => note.trackId === track.id);
+  const kit = isDrumInstrument(track.instrument);
+  const voiceSlots =
+    isSamplerInstrument(track.instrument) && track.sampler
+      ? samplerVoiceSlots(track.sampler)
+      : undefined;
+  // Keyed samplers have no slots: their notes print as named pitches.
+  const slots = voiceSlots && voiceSlots.size > 0 ? voiceSlots : undefined;
+  const voiceFor = new Map<number, string>();
+  if (kit) for (const info of DRUM_VOICES) voiceFor.set(info.pitch, info.voice);
+  if (slots) for (const [voice, slot] of slots) voiceFor.set(slot, voice);
+  const used = new Set<string>(["track"]);
+  const printed = notes.map((note) => {
+    const voice = voiceFor.get(note.pitch);
+    if (voice !== undefined) {
+      used.add("hit");
+      return printHit(score, note, voice);
+    }
+    used.add("note");
+    return printNote(score, note, !kit && !slots);
+  });
+  if (track.sampler) used.add("sampler");
+
+  const entries: string[] = [
+    `id: ${str(track.id)}`,
+    `name: ${str(track.name)}`,
+  ];
+  if (track.sampler) {
+    entries.push(`instrument: ${printSampler(track.sampler, INDENT)}`);
+  } else entries.push(`instrument: ${str(track.instrument)}`);
+  if (track.muted) entries.push("muted: true");
+  if (track.solo) entries.push("solo: true");
+  if (track.volume !== 1) entries.push(`volume: ${num(track.volume)}`);
+  if (track.pan !== 0) entries.push(`pan: ${num(track.pan)}`);
+  if (track.filter)
+    entries.push(
+      `filter: ${obj(
+        [
+          ["cutoff", num(track.filter.cutoff)],
+          ["resonance", num(track.filter.resonance)],
+        ],
+        INDENT,
+        "filter: ".length,
+        1,
+      )}`,
+    );
+  if (track.delay)
+    entries.push(
+      `delay: ${obj(
+        [
+          ["beats", num(track.delay.beats)],
+          ["feedback", num(track.delay.feedback)],
+          ["mix", num(track.delay.mix)],
+        ],
+        INDENT,
+        "delay: ".length,
+        1,
+      )}`,
+    );
+  if (track.reverb)
+    entries.push(
+      `reverb: ${obj(
+        [
+          ["mix", num(track.reverb.mix)],
+          ["size", num(track.reverb.size)],
+        ],
+        INDENT,
+        "reverb: ".length,
+        1,
+      )}`,
+    );
+  const lanes: [string, readonly AutomationPoint[] | undefined][] = [
+    ["volume", track.volumeAutomation],
+    ["pan", track.panAutomation],
+    ["filter", track.filterAutomation],
+    ["resonance", track.resonanceAutomation],
+    ["delayFeedback", track.delayFeedbackAutomation],
+    ["delayMix", track.delayMixAutomation],
+  ];
+  const automation = lanes.filter(([, points]) => points && points.length > 0);
+  if (automation.length > 0) {
+    const inner = INDENT + INDENT;
+    const body = automation.map(([lane, points]) => {
+      const items = points!.map(
+        (point) =>
+          `[${num(point.tick / score.ticksPerBeat)}, ${num(point.value)}]`,
+      );
+      // Prettier forces a break on arrays of 2+ arrays that each hold 2+ items.
+      return `${inner}${lane}: ${list(items, inner, `${lane}: `.length, 1, items.length > 1)},`;
+    });
+    entries.push(`automation: {\n${body.join("\n")}\n${INDENT}}`);
+  }
+  entries.push(`notes: ${list(printed, INDENT, "notes: ".length, 1)}`);
+
+  const names = ["track", "note", "seq", "hit", "hits", "every", "sampler"]
+    .filter((name) => used.has(name))
+    .join(", ");
+  const lines = [
+    `import { ${names} } from "dawg";`,
+    "",
+    "export default track({",
+  ];
+  for (const entry of entries) lines.push(`${INDENT}${entry},`);
+  lines.push("});", "");
+  return lines.join("\n");
+}
+
+function printNote(score: TrackScore, note: Note, named: boolean): string {
+  const pitch = named ? str(midiToPitch(note.pitch)) : num(note.pitch);
+  const args = [pitch, num(note.startTick / score.ticksPerBeat)];
+  const length = note.durationTicks / score.ticksPerBeat;
+  if (length !== 1 || note.velocity !== DEFAULT_VELOCITY)
+    args.push(num(length));
+  if (note.velocity !== DEFAULT_VELOCITY) args.push(num(note.velocity));
+  return `note(${args.join(", ")})`;
+}
+
+function printHit(score: TrackScore, note: Note, voice: string): string {
+  const args = [str(voice), num(note.startTick / score.ticksPerBeat)];
+  const length = note.durationTicks / score.ticksPerBeat;
+  if (note.velocity !== DEFAULT_VELOCITY || length !== DEFAULT_HIT_LENGTH)
+    args.push(num(note.velocity));
+  if (length !== DEFAULT_HIT_LENGTH) args.push(num(length));
+  return `hit(${args.join(", ")})`;
+}
+
+function printSampler(sampler: Sampler, indent: string): string {
+  const inner = indent + INDENT;
+  const voices = Object.keys(sampler.voices)
+    .sort()
+    .map((name) => {
+      const key = /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : str(name);
+      return `${inner}${key}: ${printSample(sampler.voices[name]!, inner, `${key}: `.length)},`;
+    });
+  const body = `{\n${voices.join("\n")}\n${indent}}`;
+  if (sampler.mode === "oneshot") return `sampler(${body})`;
+  // Prettier breaks every argument out when an earlier one contains a break.
+  const shifted = `{\n${voices.map((line) => INDENT + line).join("\n")}\n${inner}}`;
+  return `sampler(\n${inner}${shifted},\n${inner}{ mode: ${str(sampler.mode)} },\n${indent})`;
+}
+
+function printSample(ref: SampleRef, indent: string, prefix: number): string {
+  const entries: [string, string][] = [["src", str(ref.src)]];
+  if (ref.root !== undefined)
+    entries.push(["root", str(midiToPitch(ref.root))]);
+  if (ref.begin !== undefined) entries.push(["begin", num(ref.begin)]);
+  if (ref.end !== undefined) entries.push(["end", num(ref.end)]);
+  if (ref.gain !== undefined) entries.push(["gain", num(ref.gain)]);
+  if (ref.speed !== undefined) entries.push(["speed", num(ref.speed)]);
+  if (ref.loop !== undefined) entries.push(["loop", String(ref.loop)]);
+  if (ref.choke !== undefined) entries.push(["choke", str(ref.choke)]);
+  if (entries.length === 1) return str(ref.src);
+  return obj(entries, indent, prefix, 1);
+}
+
+/** Object literal: inline when the line fits, expanded otherwise (prettier keeps both). */
+function obj(
+  entries: readonly (readonly [string, string])[],
+  indent: string,
+  prefix: number,
+  trailing: number,
+): string {
+  const inline = `{ ${entries.map(([k, v]) => `${k}: ${v}`).join(", ")} }`;
+  if (indent.length + prefix + inline.length + trailing <= WIDTH) return inline;
+  const inner = indent + INDENT;
+  return `{\n${entries.map(([k, v]) => `${inner}${k}: ${v},`).join("\n")}\n${indent}}`;
+}
+
+/** Array literal: inline when the line fits (and no forced break), else one item per line. */
+function list(
+  items: readonly string[],
+  indent: string,
+  prefix: number,
+  trailing: number,
+  forceBreak = false,
+): string {
+  if (items.length === 0) return "[]";
+  const inline = `[${items.join(", ")}]`;
+  if (
+    !forceBreak &&
+    !inline.includes("\n") &&
+    indent.length + prefix + inline.length + trailing <= WIDTH
+  )
+    return inline;
+  const inner = indent + INDENT;
+  return `[\n${items.map((item) => `${inner}${item},`).join("\n")}\n${indent}]`;
+}
+
+/** Number the way prettier normalizes literals. */
+export function num(value: number): string {
+  if (!Number.isFinite(value)) throw new RangeError(`cannot print ${value}`);
+  return String(value)
+    .replace(/e\+/, "e")
+    .replace(/^(-?)\./, "$10.");
+}
+
+/** Double-quoted string unless it holds more `"` than `'`, like prettier. */
+export function str(value: string): string {
+  const doubles = (value.match(/"/g) ?? []).length;
+  const singles = (value.match(/'/g) ?? []).length;
+  const quote = doubles > singles ? "'" : '"';
+  const escaped = value
+    .replace(/\\/g, "\\\\")
+    .replace(new RegExp(quote, "g"), `\\${quote}`)
+    .replace(/\n/g, "\\n")
+    .replace(/\r/g, "\\r")
+    .replace(/\t/g, "\\t")
+    .replace(
+      /[\x00-\x1f\u2028\u2029]/g,
+      (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`,
+    );
+  return `${quote}${escaped}${quote}`;
+}