@terreno/blocks 57.10.1

package/src/asks/validateResponse.ts

@@ -0,0 +1,341 @@
+import {
+  type AskErrorDraft,
+  type AskValidationError,
+  finalizeAskErrors,
+  formatAskPath,
+  issuesToAskErrors,
+  quoteValue,
+} from "./errors";
+import {acceptedFileMimeTypes, base64ByteLength, fileTooLargeDraft, parseAskDataUrl} from "./files";
+import {checkFormValue, isBlankFormValue} from "./formValues";
+import {ASK_LIMITS} from "./limits";
+import {
+  type Ask,
+  type AskKind,
+  askAllowsDecline,
+  askResponseSchema,
+  type ChoiceAskInput,
+  choiceAnswerSchema,
+  choiceSelectionBounds,
+  confirmAnswerSchema,
+  type FilesAskInput,
+  type FormAskInput,
+  filesAnswerSchema,
+  filesCountBounds,
+  formAnswerEnvelopeSchema,
+  type MarkdownAskInput,
+  markdownAnswerSchema,
+  markdownLengthBounds,
+} from "./schema";
+
+const countText = (count: number): string => (count === 1 ? "1 option" : `${count} options`);
+
+/** "exactly 2 options", "1 to 3 options", or "at most 3 options". */
+const boundsText = ({max, min}: {max: number; min: number}): string => {
+  if (min === max) {
+    return `exactly ${countText(min)}`;
+  }
+  if (min === 0) {
+    return `at most ${countText(max)}`;
+  }
+  return `${min} to ${countText(max)}`;
+};
+
+const selectionCountDraft = ({
+  count,
+  hasOther,
+  input,
+}: {
+  count: number;
+  hasOther: boolean;
+  input: ChoiceAskInput;
+}): AskErrorDraft => {
+  const bounds = choiceSelectionBounds(input);
+  if (input.select === "one") {
+    return {
+      code: "SELECTION_COUNT",
+      fix: "Send exactly one option id in content.selected.",
+      message: `Choose exactly one option; the answer selects ${count}.`,
+      segments: ["content", "selected"],
+    };
+  }
+  const otherNote = input.allowOther === true ? " Other counts as one choice." : "";
+  return {
+    code: "SELECTION_COUNT",
+    fix: `Send ${boundsText(bounds)} in content.selected.${otherNote}`,
+    message: `Choose ${boundsText(bounds)}; the answer selects ${count}${hasOther ? ", counting Other" : ""}.`,
+    segments: ["content", "selected"],
+  };
+};
+
+const validateChoiceAnswer = (input: ChoiceAskInput, content: unknown): AskErrorDraft[] => {
+  const parsed = choiceAnswerSchema.safeParse(content);
+  if (!parsed.success) {
+    return issuesToAskErrors({issues: parsed.error.issues, prefix: ["content"], root: content});
+  }
+  const {other, selected} = parsed.data;
+  const drafts: AskErrorDraft[] = [];
+  const isOtherAllowed = input.allowOther === true;
+  if (other !== undefined && !isOtherAllowed) {
+    drafts.push({
+      code: "OTHER_NOT_ALLOWED",
+      fix: "Remove content.other and pick from the options.",
+      message: "This ask does not accept an Other answer.",
+      segments: ["content", "other"],
+    });
+  }
+  const hasOther = other !== undefined && isOtherAllowed;
+  const count = selected.length + (hasOther ? 1 : 0);
+  const {max, min} = choiceSelectionBounds(input);
+  if (count < min || count > max) {
+    drafts.push(selectionCountDraft({count, hasOther, input}));
+  }
+  const offeredIds = new Set(input.options.map((option) => option.id));
+  const firstIndexById = new Map<string, number>();
+  selected.forEach((id, index) => {
+    const firstIndex = firstIndexById.get(id);
+    if (firstIndex !== undefined) {
+      drafts.push({
+        code: "DUPLICATE_ID",
+        fix: "List each option id in content.selected once.",
+        message: `${quoteValue(id)} is already selected at ${formatAskPath(["content", "selected", firstIndex])}.`,
+        segments: ["content", "selected", index],
+      });
+      return;
+    }
+    firstIndexById.set(id, index);
+    if (offeredIds.has(id)) {
+      return;
+    }
+    drafts.push({
+      code: "OPTION_NOT_OFFERED",
+      fix: "Use the id of one of the ask's options.",
+      message: `${quoteValue(id)} is not one of the offered options.`,
+      segments: ["content", "selected", index],
+    });
+  });
+  return drafts;
+};
+
+const validateConfirmAnswer = (content: unknown): AskErrorDraft[] => {
+  const parsed = confirmAnswerSchema.safeParse(content);
+  if (parsed.success) {
+    return [];
+  }
+  return issuesToAskErrors({issues: parsed.error.issues, prefix: ["content"], root: content});
+};
+
+const characters = (count: number): string => (count === 1 ? "1 character" : `${count} characters`);
+
+/**
+ * The text must fit the ask's bounds, and `changed` must say truthfully whether it differs from
+ * the draft, so the agent can trust `changed: false` to mean the user approved the draft as is.
+ */
+const markdownTooLong = (length: number, max: number): AskErrorDraft => ({
+  code: "TOO_LONG",
+  fix: `Shorten content.markdown to ${characters(max)} or fewer.`,
+  message: `The text is ${characters(length)}, but this ask allows at most ${max}.`,
+  segments: ["content", "markdown"],
+});
+
+const isMarkdownTooLong = ({code, segments}: AskErrorDraft): boolean =>
+  code === "TOO_LONG" &&
+  segments.length === 2 &&
+  segments[0] === "content" &&
+  segments[1] === "markdown";
+
+const validateMarkdownAnswer = (input: MarkdownAskInput, content: unknown): AskErrorDraft[] => {
+  const {max, min} = markdownLengthBounds(input);
+  const parsed = markdownAnswerSchema.safeParse(content);
+  if (!parsed.success) {
+    const sent =
+      typeof content === "object" && content !== null
+        ? (content as {markdown?: unknown}).markdown
+        : undefined;
+    const length = typeof sent === "string" ? sent.length : 0;
+    // The schema's 20,000 cap fires before the ask's own maxLength, so the fix names the tighter one.
+    return issuesToAskErrors({issues: parsed.error.issues, prefix: ["content"], root: content}).map(
+      (draft) => (isMarkdownTooLong(draft) ? markdownTooLong(length, max) : draft)
+    );
+  }
+  const {changed, markdown} = parsed.data;
+  const drafts: AskErrorDraft[] = [];
+  if (markdown.length > max) {
+    drafts.push(markdownTooLong(markdown.length, max));
+  }
+  const visibleLength = markdown.trim().length;
+  if (visibleLength < min) {
+    drafts.push({
+      code: "TOO_SHORT",
+      fix: `Write at least ${characters(min)} in content.markdown.`,
+      message: `The text is ${characters(visibleLength)}, but this ask needs at least ${min}.`,
+      segments: ["content", "markdown"],
+    });
+  }
+  const isChanged = markdown !== (input.initial ?? "");
+  if (changed !== isChanged) {
+    drafts.push({
+      code: "CHANGED_MISMATCH",
+      fix: `Set content.changed to ${String(isChanged)}.`,
+      message: isChanged
+        ? "The text differs from the draft, but changed is false."
+        : "The text is the same as the draft, but changed is true.",
+      segments: ["content", "changed"],
+    });
+  }
+  return drafts;
+};
+
+/**
+ * Every value must belong to a field, every required field needs a non-blank value, and every
+ * value must be one its field accepts. A blank value on an optional field counts as unanswered.
+ */
+const validateFormAnswer = (input: FormAskInput, content: unknown): AskErrorDraft[] => {
+  const parsed = formAnswerEnvelopeSchema.safeParse(content);
+  if (!parsed.success) {
+    return issuesToAskErrors({issues: parsed.error.issues, prefix: ["content"], root: content});
+  }
+  const {values} = parsed.data;
+  const fieldIds = new Set(input.fields.map((field) => field.id));
+  const drafts: AskErrorDraft[] = Object.keys(values)
+    .filter((id) => !fieldIds.has(id))
+    .map((id) => ({
+      code: "UNKNOWN_KEY",
+      fix: `Remove ${quoteValue(id)} from content.values.`,
+      message: `${quoteValue(id)} is not the id of any field in this form.`,
+      segments: ["content", "values", id],
+    }));
+  for (const field of input.fields) {
+    const segments = ["content", "values", field.id];
+    const value = Object.hasOwn(values, field.id) ? values[field.id] : undefined;
+    if (value === undefined || isBlankFormValue(value)) {
+      if (field.required === true) {
+        drafts.push({
+          code: "REQUIRED_FIELD",
+          fix: `Fill in ${quoteValue(field.label)} (content.values.${field.id}).`,
+          message: `${quoteValue(field.label)} is required.`,
+          segments,
+        });
+      }
+      continue;
+    }
+    drafts.push(...checkFormValue({field, isDefault: false, segments, value}));
+  }
+  return drafts;
+};
+
+const fileCountText = (count: number): string => (count === 1 ? "1 file" : `${count} files`);
+
+const fileBoundsText = ({max, min}: {max: number; min: number}): string =>
+  min === max ? `exactly ${fileCountText(min)}` : `${min} to ${fileCountText(max)}`;
+
+/**
+ * The count must fit the ask, each declared type must be one `accept` allows, each file must fit
+ * the per-file cap, and a data URL's media type must be the declared type. The server then checks
+ * the bytes themselves with `checkAskFileBytes`.
+ */
+const validateFilesAnswer = (
+  input: FilesAskInput,
+  content: unknown,
+  maxFileSizeBytes: number
+): AskErrorDraft[] => {
+  const parsed = filesAnswerSchema.safeParse(content);
+  if (!parsed.success) {
+    return issuesToAskErrors({issues: parsed.error.issues, prefix: ["content"], root: content});
+  }
+  const {files} = parsed.data;
+  const drafts: AskErrorDraft[] = [];
+  const bounds = filesCountBounds(input);
+  if (files.length < bounds.min || files.length > bounds.max) {
+    drafts.push({
+      code: "FILE_COUNT",
+      fix: `Send ${fileBoundsText(bounds)} in content.files.`,
+      message: `This ask takes ${fileBoundsText(bounds)}; the answer has ${files.length}.`,
+      segments: ["content", "files"],
+    });
+  }
+  const accepted: readonly string[] = acceptedFileMimeTypes(input.accept);
+  files.forEach((file, index) => {
+    const segments = ["content", "files", index];
+    if (!accepted.includes(file.mimeType)) {
+      drafts.push({
+        code: "FILE_TYPE_NOT_ACCEPTED",
+        fix: `Send a file of type ${accepted.join(", ")}.`,
+        message: `${quoteValue(file.filename)} is ${file.mimeType}, which this ask does not accept.`,
+        segments: [...segments, "mimeType"],
+      });
+    }
+    const dataUrl = file.url === undefined ? undefined : parseAskDataUrl(file.url);
+    const size = dataUrl === undefined ? file.size : base64ByteLength(dataUrl.base64);
+    if (Math.max(size, file.size) > maxFileSizeBytes) {
+      drafts.push(
+        fileTooLargeDraft({
+          maxFileSizeBytes,
+          segments: [...segments, "size"],
+          size: Math.max(size, file.size),
+        })
+      );
+    }
+    if (dataUrl !== undefined && dataUrl.mediaType !== file.mimeType) {
+      drafts.push({
+        code: "MIME_MISMATCH",
+        fix: `Make the data URL's media type ${file.mimeType}, or declare ${dataUrl.mediaType}.`,
+        message: `The data URL holds ${dataUrl.mediaType}, but the file is declared as ${file.mimeType}.`,
+        segments: [...segments, "url"],
+      });
+    }
+  });
+  return drafts;
+};
+
+/**
+ * Checks a user's answer against the ask it answers. The client runs it before enabling Submit and
+ * the server runs it before resuming the turn. Returns no errors when the answer is valid.
+ * `maxFileSizeBytes` is the host's per-file cap for `files` answers (10 MB by default).
+ */
+export const validateAskResponse = ({
+  input,
+  kind,
+  maxFileSizeBytes = ASK_LIMITS.files.defaultMaxFileSizeBytes,
+  response,
+}: {
+  input: Ask["input"];
+  kind: AskKind;
+  maxFileSizeBytes?: number;
+  response: unknown;
+}): AskValidationError[] => {
+  const ask = {input, kind} as Ask;
+  const envelope = askResponseSchema.safeParse(response);
+  if (!envelope.success) {
+    return finalizeAskErrors(issuesToAskErrors({issues: envelope.error.issues, root: response}));
+  }
+  const answer = envelope.data;
+  if (answer.action === "cancel") {
+    return [];
+  }
+  if (answer.action === "decline") {
+    if (askAllowsDecline(ask)) {
+      return [];
+    }
+    return [
+      {
+        code: "DECLINE_NOT_ALLOWED",
+        fix: 'Answer with action "accept".',
+        message: "This ask cannot be skipped.",
+        path: "action",
+      },
+    ];
+  }
+  switch (ask.kind) {
+    case "choice":
+      return finalizeAskErrors(validateChoiceAnswer(ask.input, answer.content));
+    case "confirm":
+      return finalizeAskErrors(validateConfirmAnswer(answer.content));
+    case "markdown":
+      return finalizeAskErrors(validateMarkdownAnswer(ask.input, answer.content));
+    case "form":
+      return finalizeAskErrors(validateFormAnswer(ask.input, answer.content));
+    case "files":
+      return finalizeAskErrors(validateFilesAnswer(ask.input, answer.content, maxFileSizeBytes));
+  }
+};

package/src/blocksDocParity.test.ts

@@ -0,0 +1,21 @@
+import {describe, expect, it} from "bun:test";
+import {readFileSync} from "node:fs";
+import {join} from "node:path";
+
+import {BLOCK_ERROR_CODES, BLOCK_WARNING_CODES} from "./errors";
+
+const reference = readFileSync(
+  join(import.meta.dir, "..", "..", "docs", "reference", "blocks.md"),
+  "utf8"
+);
+
+describe("blocks reference parity", () => {
+  it("names every error and warning code", () => {
+    for (const code of Object.keys(BLOCK_ERROR_CODES)) {
+      expect(reference).toContain(`\`${code}\``);
+    }
+    for (const code of Object.keys(BLOCK_WARNING_CODES)) {
+      expect(reference).toContain(`\`${code}\``);
+    }
+  });
+});

package/src/cli.test.ts

@@ -0,0 +1,134 @@
+import {describe, expect, it} from "bun:test";
+import {join} from "node:path";
+
+import {launchBlocksCli, runBlocksCli} from "./cli";
+
+const validFixture = join(import.meta.dir, "fixtures", "valid", "prose.yaml");
+const invalidFixture = join(import.meta.dir, "fixtures", "invalid", "unknown-key.yaml");
+
+describe("terreno-blocks validate", () => {
+  it("exits 0 for a valid file and 1 for an invalid file", async () => {
+    const valid = Bun.spawn(["bun", join(import.meta.dir, "cli.ts"), "validate", validFixture], {
+      stderr: "pipe",
+      stdout: "pipe",
+    });
+    expect(await valid.exited).toBe(0);
+    expect(await new Response(valid.stdout).text()).toBe("");
+
+    const invalid = Bun.spawn(
+      ["bun", join(import.meta.dir, "cli.ts"), "validate", invalidFixture],
+      {stderr: "pipe", stdout: "pipe"}
+    );
+    expect(await invalid.exited).toBe(1);
+    const report = await new Response(invalid.stdout).text();
+    expect(report).toContain("blocks[0].color  UNKNOWN_KEY  ");
+    expect(report).toContain(" — ");
+  });
+
+  it("reads stdin when the path is -", () => {
+    const result = runBlocksCli(["validate", "-"], {
+      readFile: () => {
+        throw new Error("readFile should not run");
+      },
+      readStdin: () => "v: 1\nblocks:\n  - type: divider\n",
+    });
+    expect(result).toEqual({code: 0, stderr: "", stdout: ""});
+  });
+
+  it("prints the file error, a non-document, and a field error", () => {
+    const missing = runBlocksCli(["validate", "missing.yaml"], {
+      readFile: () => {
+        throw new Error("ENOENT");
+      },
+      readStdin: () => "",
+    });
+    expect(missing).toEqual({code: 1, stderr: "ENOENT\n", stdout: ""});
+
+    const unnamed = runBlocksCli(["validate", "missing.yaml"], {
+      readFile: () => {
+        throw "nope";
+      },
+      readStdin: () => "",
+    });
+    expect(unnamed.stderr).toBe("Could not read the file.\n");
+
+    const prose = runBlocksCli(["validate", "note.txt"], {
+      readFile: () => "hello",
+      readStdin: () => "",
+    });
+    expect(prose.code).toBe(1);
+    expect(prose.stdout).toContain("NOT_A_DOCUMENT");
+
+    const invalid = runBlocksCli(["validate", "bad.yaml"], {
+      readFile: () => "v: 1\nblocks:\n  - type: heading\n    text: Hi\n    color: red\n",
+      readStdin: () => "",
+    });
+    expect(invalid.code).toBe(1);
+    expect(invalid.stdout).toContain("UNKNOWN_KEY");
+    expect(invalid.stdout).toContain(" — ");
+  });
+
+  it("runs from the installed bin name and writes both streams", () => {
+    const run = (argv1: string, args: string[]): {code: number; stderr: string; stdout: string} => {
+      const stdout: string[] = [];
+      const stderr: string[] = [];
+      const originalArgv = process.argv;
+      const originalExit = process.exit;
+      const originalStdout = process.stdout.write;
+      const originalStderr = process.stderr.write;
+      process.argv = ["bun", argv1, ...args];
+      process.stdout.write = ((chunk: string | Uint8Array) => {
+        stdout.push(String(chunk));
+        return true;
+      }) as typeof process.stdout.write;
+      process.stderr.write = ((chunk: string | Uint8Array) => {
+        stderr.push(String(chunk));
+        return true;
+      }) as typeof process.stderr.write;
+      let code = 0;
+      process.exit = ((status?: number) => {
+        code = status ?? 0;
+        throw new Error("exit");
+      }) as typeof process.exit;
+      try {
+        launchBlocksCli(argv1);
+      } catch (error) {
+        if (!(error instanceof Error) || error.message !== "exit") {
+          throw error;
+        }
+      } finally {
+        process.argv = originalArgv;
+        process.exit = originalExit;
+        process.stdout.write = originalStdout;
+        process.stderr.write = originalStderr;
+      }
+      return {code, stderr: stderr.join(""), stdout: stdout.join("")};
+    };
+
+    const invalid = run("terreno-blocks", ["validate", invalidFixture]);
+    expect(invalid.code).toBe(1);
+    expect(invalid.stdout).toContain("UNKNOWN_KEY");
+
+    const usage = run("cli.js", ["nope"]);
+    expect(usage.code).toBe(1);
+    expect(usage.stderr).toContain("Usage: terreno-blocks validate");
+
+    const valid = run("cli.ts", ["validate", validFixture]);
+    expect(valid).toEqual({code: 0, stderr: "", stdout: ""});
+
+    const stdin = run("terreno-blocks", ["validate", "-"]);
+    expect(stdin.code).toBe(1);
+    expect(stdin.stdout).toContain("NOT_A_DOCUMENT");
+
+    expect(run("bun", ["validate", validFixture])).toEqual({code: 0, stderr: "", stdout: ""});
+  });
+
+  it("exits 1 when the command is not validate", () => {
+    const result = runBlocksCli(["nope"], {
+      readFile: () => "",
+      readStdin: () => "",
+    });
+    expect(result.code).toBe(1);
+    expect(result.stderr).toContain("Usage: terreno-blocks validate");
+  });
+});

package/src/cli.ts

@@ -0,0 +1,65 @@
+#!/usr/bin/env bun
+
+import {readFileSync} from "node:fs";
+import {basename} from "node:path";
+
+import {parseBlocks} from "./parse";
+import {validateBlocks} from "./validate";
+
+const usage = "Usage: terreno-blocks validate <file | ->\n";
+
+const formatError = (error: {code: string; fix: string; message: string; path: string}): string =>
+  `${error.path}  ${error.code}  ${error.message} — ${error.fix}`;
+
+export const runBlocksCli = (
+  argv: readonly string[],
+  input: {readFile: (path: string) => string; readStdin: () => string}
+): {code: number; stderr: string; stdout: string} => {
+  const [command, target, extra] = argv;
+  if (command !== "validate" || target === undefined || extra !== undefined) {
+    return {code: 1, stderr: usage, stdout: ""};
+  }
+  let text: string;
+  try {
+    text = target === "-" ? input.readStdin() : input.readFile(target);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Could not read the file.";
+    return {code: 1, stderr: `${message}\n`, stdout: ""};
+  }
+  const parsed = parseBlocks(text);
+  if (!parsed.ok) {
+    return {code: 1, stderr: "", stdout: `${parsed.errors.map(formatError).join("\n")}\n`};
+  }
+  const validated = validateBlocks(parsed.value);
+  if (!validated.ok) {
+    return {code: 1, stderr: "", stdout: `${validated.errors.map(formatError).join("\n")}\n`};
+  }
+  const warnings =
+    validated.warnings.length === 0 ? "" : `${validated.warnings.map(formatError).join("\n")}\n`;
+  return {code: 0, stderr: "", stdout: warnings};
+};
+
+const main = (): void => {
+  const result = runBlocksCli(process.argv.slice(2), {
+    readFile: (path) => readFileSync(path, "utf8"),
+    readStdin: () => readFileSync(0, "utf8"),
+  });
+  if (result.stdout !== "") {
+    process.stdout.write(result.stdout);
+  }
+  if (result.stderr !== "") {
+    process.stderr.write(result.stderr);
+  }
+  process.exit(result.code);
+};
+
+/** Runs validate when the process was started as the `terreno-blocks` bin. */
+export const launchBlocksCli = (argv1: string | undefined): void => {
+  const entry = basename(argv1 ?? "");
+  // npm links the bin as `terreno-blocks`, so argv[1] is that name rather than cli.js.
+  if (entry === "cli.ts" || entry === "cli.js" || entry === "terreno-blocks") {
+    main();
+  }
+};
+
+launchBlocksCli(process.argv[1]);

package/src/display.test.ts

@@ -0,0 +1,68 @@
+import {describe, expect, it} from "bun:test";
+
+import {blocksPromptSection} from "./prompt";
+import {validateBlocks} from "./validate";
+
+const documentWith = (block: Record<string, unknown>): unknown => {
+  const doc: Record<string, unknown> = {};
+  doc.v = 1;
+  doc.blocks = [block];
+  return doc;
+};
+
+const image = (src: string): unknown => {
+  const block: Record<string, unknown> = {};
+  block.type = "image";
+  block.alt = "Receipt";
+  block.src = src;
+  return documentWith(block);
+};
+
+describe("callout, image, and details", () => {
+  it("accepts a callout, a details block, a data image, and a file ref", () => {
+    const callout: Record<string, unknown> = {};
+    callout.type = "callout";
+    callout.status = "warning";
+    callout.text = "Seats renew on Friday.";
+    const details: Record<string, unknown> = {};
+    details.type = "details";
+    details.title = "Invoice notes";
+    details.text = "Twelve seats, billed monthly.";
+
+    expect(validateBlocks(documentWith(callout)).ok).toBe(true);
+    expect(validateBlocks(documentWith(details)).ok).toBe(true);
+    expect(validateBlocks(image("data:image/png;base64,aaaa")).ok).toBe(true);
+    expect(validateBlocks(image("file:6710c2a4f1")).ok).toBe(true);
+  });
+
+  it("rejects an image without alt", () => {
+    const block: Record<string, unknown> = {};
+    block.type = "image";
+    block.src = "data:image/png;base64,aaaa";
+    const result = validateBlocks(documentWith(block));
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.errors.map((error) => error.code)).toContain("MISSING_REQUIRED");
+    }
+  });
+
+  it("rejects an https image whose host is not listed and accepts a listed host", () => {
+    const blocked = validateBlocks(image("https://evil.test/pixel.png"));
+    const allowed = validateBlocks(image("https://cdn.example.com/pixel.png"), {
+      imageHosts: ["cdn.example.com"],
+    });
+
+    expect(blocked.ok).toBe(false);
+    if (!blocked.ok) {
+      expect(blocked.errors.map((error) => error.code)).toContain("IMAGE_HOST_NOT_ALLOWED");
+    }
+    expect(allowed.ok).toBe(true);
+  });
+
+  it("tells the model which image hosts are allowed", () => {
+    expect(blocksPromptSection()).toContain("Do not emit an https image src");
+    expect(blocksPromptSection()).toContain("callout");
+    expect(blocksPromptSection({imageHosts: ["cdn.example.com"]})).toContain("cdn.example.com");
+  });
+});

package/src/errors.test.ts

@@ -0,0 +1,29 @@
+import {describe, expect, it} from "bun:test";
+
+import {type BlockError, sortBlockErrors} from "./errors";
+
+const error = (path: string, code: BlockError["code"]): BlockError => ({
+  code,
+  fix: "Fix it.",
+  message: "Bad.",
+  path,
+});
+
+describe("sortBlockErrors", () => {
+  it("orders shorter paths first, indexes numerically, and codes alphabetically", () => {
+    const sorted = sortBlockErrors([
+      error("blocks[10].text", "TOO_LONG"),
+      error("blocks[2].text", "MISSING_REQUIRED"),
+      error("blocks[2].text", "INVALID_TYPE"),
+      error("blocks[2]", "UNKNOWN_KEY"),
+      error("blocks.name", "INVALID_ENUM"),
+    ]);
+    expect(sorted.map((item) => `${item.path} ${item.code}`)).toEqual([
+      "blocks[2] UNKNOWN_KEY",
+      "blocks[2].text INVALID_TYPE",
+      "blocks[2].text MISSING_REQUIRED",
+      "blocks[10].text TOO_LONG",
+      "blocks.name INVALID_ENUM",
+    ]);
+  });
+});