@hraness/dawg 0.2.0 → 0.3.0

package/src/project/init.ts

@@ -0,0 +1,253 @@
+/**
+ * Project layout on disk:
+ *
+ *   dawg.json              project marker: format and SDK major
+ *   tsconfig.json          strict, `"dawg"` → `.dawg/sdk/v1.ts`
+ *   song.ts                `export default song({ ..., tracks: [...] })`
+ *   tracks/<slug>/track.ts one `track({...})` per track (+ `samples/`)
+ *   .dawg/sdk/v1.ts        vendored SDK, refreshed when the shipped copy is newer
+ *   .dawg/sdk/tsconfig.json compiler options the root config extends
+ *   .dawg/tsbuild/         incremental typecheck state
+ *   .dawg/sync.json        hashes of files dawg wrote (echo suppression)
+ *
+ * `initProject` is idempotent, writes only under `dir`, and reports each
+ * file it created or refreshed exactly once.
+ */
+
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const PROJECT_FILE = "dawg.json";
+export const PROJECT_FORMAT = "dawg.project/v1";
+export const SDK_RELATIVE_PATH = ".dawg/sdk/v1.ts";
+export const SDK_TSCONFIG_RELATIVE_PATH = ".dawg/sdk/tsconfig.json";
+
+/** The SDK source dawg ships (`core/sdk/v1.ts`). */
+export const SHIPPED_SDK_PATH = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "..",
+  "core",
+  "sdk",
+  "v1.ts",
+);
+
+export type ProjectManifest = Readonly<{ format: string; sdk: number }>;
+
+export type InitResult = Readonly<{
+  /** Project-relative paths created or refreshed, in write order. */
+  wrote: readonly string[];
+  /** SDK version now vendored in the project. */
+  sdkVersion: string;
+}>;
+
+const SDK_TSCONFIG = `${JSON.stringify(
+  {
+    compilerOptions: {
+      target: "ES2022",
+      module: "ESNext",
+      moduleResolution: "Bundler",
+      strict: true,
+      noUncheckedIndexedAccess: true,
+      noEmit: true,
+      skipLibCheck: true,
+      allowImportingTsExtensions: true,
+      types: [],
+    },
+  },
+  null,
+  2,
+)}\n`;
+
+const ROOT_TSCONFIG = `${JSON.stringify(
+  {
+    extends: "./.dawg/sdk/tsconfig.json",
+    compilerOptions: { paths: { dawg: ["./.dawg/sdk/v1.ts"] } },
+    include: ["song.ts", "tracks/**/*.ts", ".dawg/sdk/*.ts"],
+  },
+  null,
+  2,
+)}\n`;
+
+const EMPTY_SONG = `import { song } from "dawg";
+
+export default song({
+  tempo: 120,
+  meter: [4, 4],
+  bars: 4,
+  tracks: [],
+});
+`;
+
+const GITIGNORE_LINES = [".dawg/*", "!.dawg/sdk/"];
+
+/** True when `dir` holds a `dawg.json`. */
+export async function isProject(dir: string): Promise<boolean> {
+  return (await readManifest(dir)) !== undefined;
+}
+
+/** Parses `dawg.json` from unknown; undefined when absent or unreadable. */
+export async function readManifest(
+  dir: string,
+): Promise<ProjectManifest | undefined> {
+  let text: string;
+  try {
+    text = await readFile(join(dir, PROJECT_FILE), "utf8");
+  } catch {
+    return undefined;
+  }
+  if (text.length > 4096) return undefined;
+  try {
+    const value: unknown = JSON.parse(text);
+    if (typeof value !== "object" || value === null) return undefined;
+    const record = value as Record<string, unknown>;
+    if (record.format !== PROJECT_FORMAT) return undefined;
+    if (typeof record.sdk !== "number" || !Number.isInteger(record.sdk))
+      return undefined;
+    return Object.freeze({ format: PROJECT_FORMAT, sdk: record.sdk });
+  } catch {
+    return undefined;
+  }
+}
+
+/** Version string declared by an SDK source file, or undefined. */
+export function sdkVersionOf(source: string): string | undefined {
+  const match = source.match(/SDK_VERSION = "(\d+)\.(\d+)\.(\d+)"/);
+  return match ? `${match[1]}.${match[2]}.${match[3]}` : undefined;
+}
+
+function newer(candidate: string, current: string | undefined): boolean {
+  if (current === undefined) return true;
+  const a = candidate.split(".").map(Number);
+  const b = current.split(".").map(Number);
+  if (a[0] !== b[0]) return false; // a different major is never auto-applied
+  for (let index = 1; index < 3; index += 1)
+    if (a[index]! !== b[index]!) return a[index]! > b[index]!;
+  return false;
+}
+
+export type InitOptions = Readonly<{
+  /** SDK source to vendor; defaults to the shipped `core/sdk/v1.ts`. */
+  sdkSource?: string;
+}>;
+
+/**
+ * Creates or refreshes the project in `dir`. Existing `song.ts`,
+ * `tsconfig.json`, `.gitignore` entries and `dawg.json` are left alone;
+ * the vendored SDK is replaced only by a newer copy of the same major.
+ */
+export async function initProject(
+  dir: string,
+  options: InitOptions = {},
+): Promise<InitResult> {
+  const wrote: string[] = [];
+  const sdkSource =
+    options.sdkSource ?? (await readFile(SHIPPED_SDK_PATH, "utf8"));
+  const shippedVersion = sdkVersionOf(sdkSource);
+  if (!shippedVersion) throw new Error("shipped SDK has no SDK_VERSION");
+  const major = Number(shippedVersion.split(".")[0]);
+
+  await mkdir(join(dir, ".dawg", "sdk"), { recursive: true });
+  await mkdir(join(dir, "tracks"), { recursive: true });
+
+  const vendored = await readOptional(join(dir, SDK_RELATIVE_PATH));
+  const vendoredVersion =
+    vendored === undefined ? undefined : sdkVersionOf(vendored);
+  let sdkVersion = vendoredVersion ?? shippedVersion;
+  if (vendored === undefined || newer(shippedVersion, vendoredVersion)) {
+    await writeAtomic(join(dir, SDK_RELATIVE_PATH), sdkSource);
+    wrote.push(SDK_RELATIVE_PATH);
+    sdkVersion = shippedVersion;
+  }
+  if (
+    (await readOptional(join(dir, SDK_TSCONFIG_RELATIVE_PATH))) !== SDK_TSCONFIG
+  ) {
+    await writeAtomic(join(dir, SDK_TSCONFIG_RELATIVE_PATH), SDK_TSCONFIG);
+    wrote.push(SDK_TSCONFIG_RELATIVE_PATH);
+  }
+  if ((await readManifest(dir)) === undefined) {
+    await writeAtomic(
+      join(dir, PROJECT_FILE),
+      `${JSON.stringify({ format: PROJECT_FORMAT, sdk: major }, null, 2)}\n`,
+    );
+    wrote.push(PROJECT_FILE);
+  }
+  if ((await readOptional(join(dir, "tsconfig.json"))) === undefined) {
+    await writeAtomic(join(dir, "tsconfig.json"), ROOT_TSCONFIG);
+    wrote.push("tsconfig.json");
+  }
+  if ((await readOptional(join(dir, "song.ts"))) === undefined) {
+    await writeAtomic(join(dir, "song.ts"), EMPTY_SONG);
+    // Recorded as dawg-written so the first window lets the session win.
+    await writeAtomic(
+      join(dir, ".dawg", "sync.json"),
+      `${JSON.stringify(
+        {
+          files: {
+            "song.ts": createHash("sha256").update(EMPTY_SONG).digest("hex"),
+          },
+        },
+        null,
+        2,
+      )}\n`,
+    );
+    wrote.push("song.ts");
+  }
+  const gitignore = (await readOptional(join(dir, ".gitignore"))) ?? "";
+  const present = new Set(gitignore.split("\n").map((line) => line.trim()));
+  const missing = GITIGNORE_LINES.filter((line) => !present.has(line));
+  if (missing.length > 0) {
+    const prefix =
+      gitignore.length === 0 || gitignore.endsWith("\n") ? "" : "\n";
+    await writeAtomic(
+      join(dir, ".gitignore"),
+      `${gitignore}${prefix}${missing.join("\n")}\n`,
+    );
+    wrote.push(".gitignore");
+  }
+  return Object.freeze({ wrote: Object.freeze(wrote), sdkVersion });
+}
+
+/** `dawg init [dir]`: creates the project and prints what it wrote. */
+export async function runInitCommand(
+  argv: readonly string[],
+  cwd: string,
+  stdout: { write(text: string): unknown },
+  stderr: { write(text: string): unknown },
+): Promise<number> {
+  const target =
+    argv[1] && !argv[1].startsWith("--") ? resolve(cwd, argv[1]) : cwd;
+  try {
+    const result = await initProject(target);
+    if (result.wrote.length === 0)
+      stdout.write(`project up to date (sdk ${result.sdkVersion})\n`);
+    else for (const path of result.wrote) stdout.write(`wrote ${path}\n`);
+    return 0;
+  } catch (error) {
+    stderr.write(
+      `init failed: ${error instanceof Error ? error.message : String(error)}\n`,
+    );
+    return 1;
+  }
+}
+
+async function readOptional(path: string): Promise<string | undefined> {
+  try {
+    return await readFile(path, "utf8");
+  } catch {
+    return undefined;
+  }
+}
+
+/** Temp file + rename so a reader never sees a partial file. */
+export async function writeAtomic(
+  path: string,
+  contents: string,
+): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  const temporary = `${path}.${process.pid}.tmp`;
+  await writeFile(temporary, contents, "utf8");
+  await rename(temporary, path);
+}

package/src/project/sync.ts

@@ -0,0 +1,432 @@
+/**
+ * Two-way sync between the project files and the session score.
+ *
+ * files → score: a change to `song.ts` or `tracks/<slug>/track.ts` (fs.watch
+ * plus a slow poll, debounced 150 ms) evaluates the project, adopts the
+ * session's note ids, diffs against the current score and commits one
+ * `files.apply` revision through the session port. A failed evaluation is
+ * reported as a card and leaves the score alone.
+ *
+ * score → files: a new score revision reprints the project and writes only
+ * the files whose bytes differ. Files whose last evaluation already equals
+ * the score are never rewritten, so an author's own formatting survives.
+ *
+ * Echo suppression: `.dawg/sync.json` records the hash of every file dawg
+ * wrote; a watcher event whose file still hashes the same is ignored, in
+ * this window and every other one.
+ */
+
+import { createHash } from "node:crypto";
+import { watch, type FSWatcher } from "node:fs";
+import { readdir, readFile, rm, stat } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  adoptNoteIds,
+  applyScoreOperations,
+  diffScores,
+} from "../../core/diff.ts";
+import { encodeLoop } from "../../core/loop.ts";
+import type { ScoreOperation, TrackScore } from "../../core/score.ts";
+import {
+  evaluateProject,
+  formatDiagnostic,
+  type Diagnostic,
+  type EvalResult,
+} from "../../core/sdk/eval.ts";
+import { printProject } from "../../core/sdk/print.ts";
+import { writeAtomic } from "./init.ts";
+import { typecheckProject, type TypecheckResult } from "./typecheck.ts";
+
+export const SYNC_DEBOUNCE_MS = 150;
+export const SYNC_POLL_MS = 1_500;
+const SYNC_STATE_FILE = ".dawg/sync.json";
+const MAX_TRACKED_FILES = 512;
+
+/** Header indicator state: `types ✓` or `types ✗ N`. */
+export type TypesState = Readonly<{ ok: boolean; errors: number }>;
+
+/** Result of reconciling an evaluated score with the session score. */
+export type FilesApplyPlan = Readonly<{
+  /** The session score after the file change, with session note ids kept. */
+  next: TrackScore;
+  operations: readonly ScoreOperation[];
+}>;
+
+/**
+ * Pure core of files → score: adopts `current`'s note ids into `evaluated`
+ * and returns the operations (and resulting score) that bring `current` to
+ * it. Empty `operations` means the files already match the score.
+ */
+export function applyFiles(
+  current: TrackScore,
+  evaluated: TrackScore,
+): FilesApplyPlan {
+  const target = adoptNoteIds(current, evaluated);
+  const operations = diffScores(current, target);
+  const next =
+    operations.length === 0
+      ? current
+      : applyScoreOperations(current, operations);
+  return Object.freeze({ next, operations });
+}
+
+/** What the sync needs from its window. */
+export type SyncHost = Readonly<{
+  project: string;
+  /** Current session score. */
+  current(): TrackScore;
+  /**
+   * Commits the plan as one `files.apply` revision. Resolves with the
+   * score the session now holds (it may be ahead after a rebase).
+   */
+  commit(plan: FilesApplyPlan, summary: string): Promise<TrackScore>;
+  card(
+    text: string,
+    tone: "info" | "success" | "warning" | "error",
+    hint?: string,
+  ): void;
+  types(state: TypesState): void;
+}>;
+
+export type SyncOptions = Readonly<{
+  evaluate?: (project: string) => Promise<EvalResult>;
+  typecheck?: (project: string) => Promise<TypecheckResult>;
+  debounceMs?: number;
+  pollMs?: number;
+  /** Disable fs.watch and polling (tests drive `checkFiles` directly). */
+  watch?: boolean;
+}>;
+
+export type ProjectSync = Readonly<{
+  /** Call when the session score changed (local edit or another window). */
+  scoreChanged(score: TrackScore): void;
+  /**
+   * Evaluate the files now (debounce skipped); resolves when applied with a
+   * one-line outcome (`applied from files · 1 note`, `files rejected · …`,
+   * `files match the score`), the last one when nothing changed since.
+   */
+  checkFiles(): Promise<string>;
+  /** Reprint now (debounce skipped); resolves when written. */
+  flushScore(): Promise<void>;
+  stop(): Promise<void>;
+}>;
+
+type SyncState = { files: Record<string, string> };
+
+export function startProjectSync(
+  host: SyncHost,
+  options: SyncOptions = {},
+): ProjectSync {
+  const evaluate =
+    options.evaluate ?? ((project: string) => evaluateProject(project));
+  const typecheck =
+    options.typecheck ?? ((project: string) => typecheckProject(project));
+  const debounceMs = options.debounceMs ?? SYNC_DEBOUNCE_MS;
+  const project = host.project;
+  const statePath = join(project, SYNC_STATE_FILE);
+  /** Hashes of the project files as of the last successful evaluation. */
+  let seen = new Map<string, string>();
+  /** Outcome of the last evaluation, returned when the files did not change. */
+  let lastOutcome = "files match the score";
+  /** Encoded score the files were last known to equal. */
+  let filesEqual = "";
+  let lastRejection = "";
+  let stopped = false;
+  let queue: Promise<void> = Promise.resolve();
+  let fileTimer: ReturnType<typeof setTimeout> | undefined;
+  let scoreTimer: ReturnType<typeof setTimeout> | undefined;
+  let pendingScore: TrackScore | undefined;
+  let watchers: FSWatcher[] = [];
+  let poll: ReturnType<typeof setInterval> | undefined;
+
+  const enqueue = <T>(task: () => Promise<T>): Promise<T> => {
+    const run = queue.then(task, task);
+    queue = run.then(
+      () => undefined,
+      () => undefined,
+    );
+    return run;
+  };
+
+  const readState = async (): Promise<SyncState> => {
+    try {
+      const value: unknown = JSON.parse(await readFile(statePath, "utf8"));
+      if (typeof value !== "object" || value === null) return { files: {} };
+      const files = (value as Record<string, unknown>).files;
+      if (typeof files !== "object" || files === null) return { files: {} };
+      const out: Record<string, string> = {};
+      for (const [path, hash] of Object.entries(
+        files as Record<string, unknown>,
+      ))
+        if (
+          typeof hash === "string" &&
+          /^[0-9a-f]{64}$/.test(hash) &&
+          path.length < 512
+        )
+          out[path] = hash;
+      return { files: out };
+    } catch {
+      return { files: {} };
+    }
+  };
+  const writeState = (state: SyncState) =>
+    writeAtomic(statePath, `${JSON.stringify(state, null, 2)}\n`);
+
+  /**
+   * Evaluates the files. In `files-win` mode (edits) the result is committed;
+   * in `score-wins` mode (startup with unchanged files) a difference reprints
+   * the files from the score instead.
+   */
+  const checkFilesNow = async (
+    mode: "files-win" | "score-wins" = "files-win",
+  ): Promise<string> => {
+    if (stopped) return lastOutcome;
+    const current = await hashProject(project);
+    if (mode === "files-win" && sameHashes(current, seen)) return lastOutcome;
+    const result = await evaluate(project);
+    if (!result.ok) {
+      const text = result.diagnostics.map(formatDiagnostic).join("; ");
+      if (text !== lastRejection) {
+        lastRejection = text;
+        host.card(
+          `files rejected · ${firstLine(text)}`,
+          "error",
+          "fix the file to apply",
+        );
+      }
+      void runTypecheck();
+      return (lastOutcome = `files rejected · ${text}`);
+    }
+    lastRejection = "";
+    seen = current;
+    const plan = applyFiles(host.current(), result.score);
+    if (plan.operations.length === 0) {
+      filesEqual = encodeLoop(host.current());
+      void runTypecheck();
+      return (lastOutcome = "files match the score");
+    }
+    if (mode === "score-wins") {
+      pendingScore = host.current();
+      await flushScoreNow();
+      void runTypecheck();
+      return (lastOutcome = "files reprinted from the score");
+    }
+    const summary = summarize(plan.operations);
+    try {
+      const committed = await host.commit(plan, summary);
+      filesEqual = encodeLoop(committed);
+      host.card(`applied from files · ${summary}`, "success");
+      lastOutcome = `applied from files · ${summary}`;
+    } catch (error) {
+      host.card(
+        `files not applied · ${firstLine(error instanceof Error ? error.message : String(error))}`,
+        "warning",
+      );
+      lastOutcome = `files not applied · ${error instanceof Error ? error.message : String(error)}`;
+    }
+    void runTypecheck();
+    return lastOutcome;
+  };
+
+  const flushScoreNow = async (): Promise<void> => {
+    if (stopped || !pendingScore) return;
+    const score = pendingScore;
+    pendingScore = undefined;
+    const encoded = encodeLoop(score);
+    if (encoded === filesEqual) return;
+    const printed = printProject(score);
+    const state = await readState();
+    const files = { ...state.files };
+    const expected = new Set(printed.files.map((file) => file.path));
+    const hashes = new Map<string, string>();
+    for (const file of printed.files) {
+      const hash = sha256(file.text);
+      hashes.set(file.path, hash);
+      const existing = await readOptional(join(project, file.path));
+      if (existing === file.text) continue;
+      await writeAtomic(join(project, file.path), file.text);
+      files[file.path] = hash;
+    }
+    // Track files we printed earlier for tracks that no longer exist.
+    for (const [path, hash] of Object.entries(state.files)) {
+      if (expected.has(path) || !path.startsWith("tracks/")) continue;
+      const existing = await readOptional(join(project, path));
+      if (existing !== undefined && sha256(existing) === hash)
+        await rm(join(project, path), { force: true });
+      delete files[path];
+    }
+    await writeState({ files });
+    seen = await hashProject(project);
+    filesEqual = encoded;
+  };
+
+  let typecheckRunning = false;
+  let typecheckAgain = false;
+  const runTypecheck = async (): Promise<void> => {
+    if (stopped) return;
+    if (typecheckRunning) {
+      typecheckAgain = true;
+      return;
+    }
+    typecheckRunning = true;
+    try {
+      const result = await typecheck(project);
+      host.types({ ok: result.ok, errors: result.diagnostics.length });
+    } catch {
+      host.types({ ok: false, errors: 1 });
+    } finally {
+      typecheckRunning = false;
+      if (typecheckAgain) {
+        typecheckAgain = false;
+        void runTypecheck();
+      }
+    }
+  };
+
+  const scheduleFiles = () => {
+    if (stopped) return;
+    if (fileTimer) clearTimeout(fileTimer);
+    fileTimer = setTimeout(() => {
+      fileTimer = undefined;
+      void enqueue(() => checkFilesNow("files-win"));
+    }, debounceMs);
+  };
+
+  if (options.watch !== false) {
+    const onEvent = (_event: string, filename: string | Buffer | null) => {
+      const name = filename === null ? "" : String(filename);
+      if (name && !isProjectSource(name)) return;
+      scheduleFiles();
+    };
+    try {
+      watchers.push(watch(project, { persistent: false }, onEvent));
+      watchers.push(
+        watch(
+          join(project, "tracks"),
+          { persistent: false, recursive: true },
+          onEvent,
+        ),
+      );
+    } catch {
+      watchers.forEach((watcher) => watcher.close());
+      watchers = [];
+    }
+    poll = setInterval(
+      () => void enqueue(() => checkFilesNow("files-win")),
+      options.pollMs ?? SYNC_POLL_MS,
+    );
+    poll.unref?.();
+  }
+  // Startup: files edited since dawg last wrote them (or never recorded)
+  // win; otherwise the session score wins and reprints what files lack.
+  void enqueue(async () => {
+    const state = await readState();
+    const current = await hashProject(project);
+    const edited =
+      current.size === 0 ||
+      [...current].some(([path, hash]) => state.files[path] !== hash);
+    await checkFilesNow(edited ? "files-win" : "score-wins");
+  });
+
+  return Object.freeze({
+    scoreChanged(score: TrackScore) {
+      if (stopped) return;
+      pendingScore = score;
+      if (scoreTimer) clearTimeout(scoreTimer);
+      scoreTimer = setTimeout(() => {
+        scoreTimer = undefined;
+        void enqueue(flushScoreNow);
+      }, debounceMs);
+    },
+    checkFiles: () => enqueue(() => checkFilesNow("files-win")),
+    flushScore: () => enqueue(flushScoreNow),
+    async stop() {
+      stopped = true;
+      if (fileTimer) clearTimeout(fileTimer);
+      if (scoreTimer) clearTimeout(scoreTimer);
+      if (poll) clearInterval(poll);
+      watchers.forEach((watcher) => watcher.close());
+      watchers = [];
+      await queue.catch(() => undefined);
+    },
+  });
+}
+
+/** Project-relative source paths: `song.ts` and each track file under `tracks/`. */
+export async function projectSourceFiles(project: string): Promise<string[]> {
+  const files = ["song.ts"];
+  let dirs: string[] = [];
+  try {
+    dirs = (await readdir(join(project, "tracks"), { withFileTypes: true }))
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .sort();
+  } catch {
+    dirs = [];
+  }
+  for (const dir of dirs.slice(0, MAX_TRACKED_FILES)) {
+    const path = `tracks/${dir}/track.ts`;
+    try {
+      if ((await stat(join(project, path))).isFile()) files.push(path);
+    } catch {
+      // A directory without a track file (samples only) is not a source.
+    }
+  }
+  return files;
+}
+
+function isProjectSource(name: string): boolean {
+  return (
+    name === "song.ts" || /(^|\/)track\.ts$/.test(name) || !name.includes(".")
+  );
+}
+
+async function hashProject(project: string): Promise<Map<string, string>> {
+  const out = new Map<string, string>();
+  for (const path of await projectSourceFiles(project)) {
+    const text = await readOptional(join(project, path));
+    if (text !== undefined) out.set(path, sha256(text));
+  }
+  return out;
+}
+
+function sameHashes(a: Map<string, string>, b: Map<string, string>): boolean {
+  if (a.size !== b.size) return false;
+  for (const [path, hash] of a) if (b.get(path) !== hash) return false;
+  return true;
+}
+
+function sha256(text: string): string {
+  return createHash("sha256").update(text).digest("hex");
+}
+
+async function readOptional(path: string): Promise<string | undefined> {
+  try {
+    return await readFile(path, "utf8");
+  } catch {
+    return undefined;
+  }
+}
+
+function firstLine(text: string): string {
+  const line = text.split("\n")[0] ?? "";
+  return line.length > 120 ? `${line.slice(0, 119)}…` : line;
+}
+
+/** `2 notes, 1 track` style summary of a plan for the activity card. */
+export function summarize(operations: readonly ScoreOperation[]): string {
+  const counts = new Map<string, number>();
+  for (const op of operations) {
+    const key = op.type.endsWith("Note")
+      ? "note"
+      : op.type.endsWith("Track")
+        ? "track"
+        : "setting";
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  return [...counts.entries()]
+    .map(([key, count]) => `${count} ${key}${count === 1 ? "" : "s"}`)
+    .join(", ");
+}
+
+export type { Diagnostic };