@dsdenes/devboard 0.1.560 → 0.1.562

package/server/records.test.ts

@@ -0,0 +1,180 @@
+import { fixtureRecord } from "./fixtures/adr-source";
+import { afterAll, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { readRecords } from "./records";
+
+const temporaryDirectories: string[] = [];
+const TEMP_ROOT = join(import.meta.dir, "..", ".tmp");
+
+async function temporaryDirectory() {
+  await mkdir(TEMP_ROOT, { recursive: true });
+  const directory = await mkdtemp(join(TEMP_ROOT, "records-"));
+  temporaryDirectories.push(directory);
+  return directory;
+}
+
+afterAll(async () => {
+  await Promise.all(
+    temporaryDirectories.map((directory) => rm(directory, { recursive: true, force: true })),
+  );
+});
+
+describe("readRecords", () => {
+  test("reads the title and status from the frontmatter", async () => {
+    const directory = await temporaryDirectory();
+    await writeFile(join(directory, "0001-example.md"), fixtureRecord("0001-example.md", "Example record"));
+
+    const [record] = (await readRecords(directory)).records;
+
+    expect(record).toEqual({
+      file: "0001-example.md",
+      title: "Example record",
+      status: "Accepted",
+      pending: false,
+      summary: "",
+    });
+  });
+
+  test("summarizes the first paragraph of the Decision section", async () => {
+    const directory = await temporaryDirectory();
+    await writeFile(
+      join(directory, "0007-decision.md"),
+      fixtureRecord(
+        "0007-decision.md",
+        "A decision",
+        "accepted",
+        [
+          "## Context",
+          "",
+          "This must not be the summary.",
+          "",
+          "## Decision",
+          "",
+          "Use the `boring` runtime for **every** service.",
+          "The second sentence stays in the summary.",
+          "",
+          "## Consequences",
+          "",
+          "Ignored.",
+        ].join("\n"),
+      ),
+    );
+
+    const [record] = (await readRecords(directory)).records;
+
+    expect(record?.summary).toBe(
+      "Use the boring runtime for every service. The second sentence stays in the summary.",
+    );
+  });
+
+  test("shortens a long decision paragraph at a word boundary", async () => {
+    const directory = await temporaryDirectory();
+    const paragraph = `${"word ".repeat(80)}end.`;
+    await writeFile(
+      join(directory, "0008-long.md"),
+      fixtureRecord("0008-long.md", "Long", "proposed", `## Decision\n\n${paragraph}\n`),
+    );
+
+    const [record] = (await readRecords(directory)).records;
+
+    expect(record?.summary.length).toBeLessThanOrEqual(281);
+    expect(record?.summary.endsWith("…")).toBe(true);
+    expect(record?.summary.startsWith("word word")).toBe(true);
+  });
+
+  test("marks draft and proposed records as pending", async () => {
+    const directory = await temporaryDirectory();
+    await writeFile(join(directory, "0001-draft.md"), fixtureRecord("0001-draft.md", "Draft", "draft"));
+    await writeFile(
+      join(directory, "0002-proposed.md"),
+      fixtureRecord("0002-proposed.md", "Proposed", "proposed"),
+    );
+    await writeFile(join(directory, "0003-accepted.md"), fixtureRecord("0003-accepted.md", "Accepted"));
+    await writeFile(
+      join(directory, "0004-rejected.md"),
+      fixtureRecord("0004-rejected.md", "Rejected", "rejected"),
+    );
+    await writeFile(
+      join(directory, "0005-deprecated.md"),
+      fixtureRecord("0005-deprecated.md", "Deprecated", "deprecated"),
+    );
+
+    const list = await readRecords(directory);
+
+    expect(list.records.map((record) => [record.file, record.status, record.pending])).toEqual([
+      ["0001-draft.md", "Draft", true],
+      ["0002-proposed.md", "Proposed", true],
+      ["0003-accepted.md", "Accepted", false],
+      ["0004-rejected.md", "Rejected", false],
+      ["0005-deprecated.md", "Deprecated", false],
+    ]);
+    expect(list.next).toBe("0001-draft.md");
+  });
+
+  test("leaves a file without valid frontmatter out of the list, pending set and next", async () => {
+    const directory = await temporaryDirectory();
+    await writeFile(join(directory, "0001-invalid.md"), "# Invalid\n\nNo frontmatter here.\n");
+    await writeFile(join(directory, "0002-valid.md"), fixtureRecord("0002-valid.md", "Valid", "proposed"));
+
+    const list = await readRecords(directory);
+
+    expect(list.records.map((record) => record.file)).toEqual(["0002-valid.md"]);
+    expect(list.next).toBe("0002-valid.md");
+  });
+
+  test("orders records by file name and marks the lowest pending record as next", async () => {
+    const directory = await temporaryDirectory();
+    await writeFile(
+      join(directory, "0002-second.md"),
+      fixtureRecord("0002-second.md", "Second", "proposed"),
+    );
+    await writeFile(join(directory, "0001-first.md"), fixtureRecord("0001-first.md", "First"));
+    await writeFile(
+      join(directory, "0003-third.md"),
+      fixtureRecord("0003-third.md", "Third", "proposed"),
+    );
+    await writeFile(join(directory, "notes.txt"), "not a record");
+
+    const list = await readRecords(directory);
+
+    expect(list.records.map((record) => record.file)).toEqual([
+      "0001-first.md",
+      "0002-second.md",
+      "0003-third.md",
+    ]);
+    expect(list.next).toBe("0002-second.md");
+  });
+
+  test("returns null next when every record is resolved", async () => {
+    const directory = await temporaryDirectory();
+    await writeFile(join(directory, "0001-first.md"), fixtureRecord("0001-first.md", "First"));
+
+    const list = await readRecords(directory);
+
+    expect(list.records).toHaveLength(1);
+    expect(list.next).toBeNull();
+  });
+
+  test("reflects records added and removed between reads", async () => {
+    const directory = await temporaryDirectory();
+    await writeFile(join(directory, "0001-first.md"), fixtureRecord("0001-first.md", "First"));
+
+    expect((await readRecords(directory)).next).toBeNull();
+
+    await writeFile(
+      join(directory, "0002-added.md"),
+      fixtureRecord("0002-added.md", "Added", "proposed"),
+    );
+    expect((await readRecords(directory)).next).toBe("0002-added.md");
+
+    await rm(join(directory, "0002-added.md"));
+    expect((await readRecords(directory)).next).toBeNull();
+  });
+
+  test("treats an absent record directory as an empty list", async () => {
+    const directory = join(await temporaryDirectory(), "removed");
+
+    expect(await readRecords(directory)).toEqual({ records: [], next: null });
+  });
+});

package/server/records.ts

@@ -0,0 +1,99 @@
+import { basename } from "node:path";
+import { lintCorpus, type Adr } from "@adrkit/core";
+
+export interface AdrRecord {
+  file: string;
+  title: string;
+  status: string;
+  pending: boolean;
+  /** The first paragraph of the Decision section, shortened for the record dropdown. */
+  summary: string;
+}
+
+export interface AdrList {
+  records: AdrRecord[];
+  next: string | null;
+}
+
+const HEADING_PATTERN = /^#{1,6}\s+(.+?)\s*$/;
+const DECISION_HEADING = /^decision$/i;
+const SUMMARY_LIMIT = 280;
+
+/** Collapses the first decision paragraph to the short form the dropdown shows. */
+function summarizeDecision(paragraph: string[]): string {
+  if (paragraph.length === 0) return "";
+  const text = paragraph
+    .join(" ")
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1")
+    .replace(/[`*_]/g, "")
+    .replace(/^[-+]\s+/, "")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (text.length <= SUMMARY_LIMIT) return text;
+  const cut = text.slice(0, SUMMARY_LIMIT);
+  const boundary = cut.lastIndexOf(" ");
+  return `${(boundary > 0 ? cut.slice(0, boundary) : cut).replace(/[.,;:!?-]+$/, "")}…`;
+}
+
+/** Reads the first paragraph under the record's Decision heading. */
+function readDecision(lines: string[]): string {
+  let inDecision = false;
+  let started = false;
+  const paragraph: string[] = [];
+
+  for (const line of lines) {
+    const heading = HEADING_PATTERN.exec(line)?.[1];
+    if (heading !== undefined) {
+      if (DECISION_HEADING.test(heading)) {
+        inDecision = true;
+        continue;
+      }
+      if (inDecision) break;
+      continue;
+    }
+    if (!inDecision) continue;
+
+    if (line.trim().length === 0) {
+      if (started) break;
+      continue;
+    }
+    started = true;
+    paragraph.push(line.trim());
+  }
+
+  return summarizeDecision(paragraph);
+}
+
+/** Projects one adrkit record onto the interface's record contract. */
+export function recordFromAdr(adr: Adr): AdrRecord {
+  const { status } = adr.frontmatter;
+  return {
+    file: basename(adr.path),
+    title: adr.frontmatter.title,
+    // The interface renders a capitalized status; adrkit stores the lowercase enum.
+    status: status.charAt(0).toUpperCase() + status.slice(1),
+    pending: status === "draft" || status === "proposed",
+    summary: readDecision(adr.body.split(/\r?\n/)),
+  };
+}
+
+/** Reads the corpus through adrkit and lists only the records it accepts. */
+export async function readRecords(directory: string): Promise<AdrList> {
+  let records: Adr[];
+  try {
+    ({ records } = await lintCorpus({ dir: directory }));
+  } catch (error) {
+    // An implementation reset removes the record directory. An absent
+    // directory is an empty record set, not a read failure.
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return { records: [], next: null };
+    }
+    throw error;
+  }
+
+  const list = records.map(recordFromAdr).sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
+  return {
+    records: list,
+    next: list.find((record) => record.pending)?.file ?? null,
+  };
+}