@dsdenes/devboard 0.1.560 → 0.1.562

package/client/lib/dependency-diagram.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, test } from "bun:test";
+import { dependencyChart, dependencyEdges } from "./dependency-diagram";
+
+describe("dependency edges", () => {
+  test("reads directed records and sorts them by both endpoints", () => {
+    expect(
+      dependencyEdges([
+        { from: "Orders", to: "Checkout" },
+        { from: "Checkout", to: "Orders" },
+      ]),
+    ).toEqual([
+      { from: "Checkout", to: "Orders" },
+      { from: "Orders", to: "Checkout" },
+    ]);
+  });
+
+  test("drops malformed, blank, self, and repeated edges", () => {
+    expect(
+      dependencyEdges([
+        { from: " Checkout ", to: " Orders " },
+        { from: "Checkout", to: "Orders" },
+        { from: "Orders", to: "Orders" },
+        { from: "", to: "Orders" },
+        { from: "Orders" },
+        "Checkout -> Orders",
+        null,
+      ]),
+    ).toEqual([{ from: "Checkout", to: "Orders" }]);
+  });
+
+  test("reads nothing from a non-list value", () => {
+    expect(dependencyEdges(null)).toEqual([]);
+    expect(dependencyEdges({ from: "Checkout", to: "Orders" })).toEqual([]);
+  });
+});
+
+describe("dependency chart", () => {
+  test("draws every context and each directed edge", () => {
+    expect(
+      dependencyChart(
+        ["Checkout", "Orders"],
+        [
+          { from: "Checkout", to: "Orders" },
+          { from: "Orders", to: "Billing" },
+        ],
+      ),
+    ).toBe(
+      [
+        "flowchart LR",
+        '  n0["Checkout"]',
+        '  n1["Orders"]',
+        '  n2["Billing"]',
+        "  n0 --> n1",
+        "  n1 --> n2",
+      ].join("\n"),
+    );
+  });
+
+  test("keeps a context label from injecting Mermaid syntax", () => {
+    const hostile = 'Checkout"] --> Billing["x';
+    expect(dependencyChart([hostile, "Safe"], [{ from: "Safe", to: hostile }])).toBe(
+      [
+        "flowchart LR",
+        '  n0["Checkout#quot;] --> Billing[#quot;x"]',
+        '  n1["Safe"]',
+        "  n1 --> n0",
+      ].join("\n"),
+    );
+  });
+
+  test("keeps isolated contexts beside the recorded edges", () => {
+    expect(
+      dependencyChart(["Orders", "Shipping"], [{ from: "Checkout", to: "Orders" }]),
+    ).toBe(
+      [
+        "flowchart LR",
+        '  n0["Orders"]',
+        '  n1["Shipping"]',
+        '  n2["Checkout"]',
+        "  n2 --> n0",
+      ].join("\n"),
+    );
+  });
+
+  test("has nothing to draw without a recorded edge", () => {
+    expect(dependencyChart(["Orders"], [])).toBeNull();
+    expect(dependencyChart([], [])).toBeNull();
+    expect(dependencyChart(["  "], [])).toBeNull();
+  });
+});

package/client/lib/dependency-diagram.ts

@@ -0,0 +1,75 @@
+import { scalarText } from "./discover-format";
+
+/** One directed architecture edge: `from` depends on `to`. */
+export interface DependencyEdge {
+  from: string;
+  to: string;
+}
+
+/**
+ * Reads the recorded `architecture.dependencies` value into the directed edges
+ * a diagram can draw. The server rejects anything this function would drop, so
+ * the filtering only keeps a stale or hand-edited sheet from breaking the
+ * page: blank fields, self-edges, malformed records, and repeated edges are
+ * ignored.
+ */
+export function dependencyEdges(value: unknown): DependencyEdge[] {
+  if (!Array.isArray(value)) return [];
+  const seen = new Set<string>();
+  const edges: DependencyEdge[] = [];
+  for (const record of value) {
+    if (typeof record !== "object" || record === null || Array.isArray(record)) continue;
+    const fields = record as Record<string, unknown>;
+    const from = scalarText(fields.from).trim();
+    const to = scalarText(fields.to).trim();
+    if (from.length === 0 || to.length === 0 || from === to) continue;
+    const key = `${from}\u0000${to}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    edges.push({ from, to });
+  }
+  edges.sort((left, right) => {
+    const byFrom = left.from.localeCompare(right.from);
+    return byFrom !== 0 ? byFrom : left.to.localeCompare(right.to);
+  });
+  return edges;
+}
+
+function mermaidLabel(text: string): string {
+  return text.replace(/"/g, "#quot;").replace(/[\r\n]+/g, " ").trim();
+}
+
+/**
+ * Builds a Mermaid flowchart for the bounded contexts and the recorded
+ * dependencies. Returns null when there is nothing to draw. Node ids are
+ * generated, so a context name can never inject Mermaid syntax.
+ */
+export function dependencyChart(
+  contextNames: string[],
+  edges: DependencyEdge[],
+): string | null {
+  if (edges.length === 0) return null;
+  const labels = new Map<string, string>();
+  for (const name of contextNames) {
+    const label = name.trim();
+    if (label.length > 0 && !labels.has(label)) labels.set(label, `n${labels.size}`);
+  }
+  for (const edge of edges) {
+    for (const name of [edge.from, edge.to]) {
+      if (!labels.has(name)) labels.set(name, `n${labels.size}`);
+    }
+  }
+  if (labels.size === 0) return null;
+
+  const lines = ["flowchart LR"];
+  for (const [label, id] of labels) {
+    lines.push(`  ${id}["${mermaidLabel(label)}"]`);
+  }
+  for (const edge of edges) {
+    const from = labels.get(edge.from);
+    const to = labels.get(edge.to);
+    if (from === undefined || to === undefined) continue;
+    lines.push(`  ${from} --> ${to}`);
+  }
+  return lines.join("\n");
+}

package/client/lib/discover-format.test.ts

@@ -0,0 +1,265 @@
+import { describe, expect, test } from "bun:test";
+import {
+  commandAlias,
+  conceptSignificance,
+  conceptUsage,
+  filterContexts,
+  glossaryHasSignificance,
+  implementedTiers,
+  pyramidHappyPathCount,
+  pyramidTiers,
+  relativeTime,
+  SIGNIFICANCE_FLOOR,
+} from "./discover-format";
+import type { Concept, Glossary, GlossarySignificance, GlossaryUsage, Leaf } from "./types";
+
+function concept(id: string, status: string, label: string): Concept {
+  return {
+    id,
+    prefLabels: [{ language: "en", text: label }],
+    altLabels: [],
+    definitions: [{ language: "en", text: `${label} definition.` }],
+    status,
+    origin: "owner",
+    kind: "entity",
+    grounding: [],
+  };
+}
+
+const glossary: Glossary = {
+  boundedContext: "orders",
+  titles: [{ language: "en", text: "Orders" }],
+  concepts: [
+    concept("page-action", "confirmed", "Page Action"),
+    concept("order-total", "confirmed", "Order Total"),
+    concept("option", "confirmed", "Option"),
+    concept("unscored-term", "confirmed", "Unscored Term"),
+    concept("stale-term", "invalidated", "Stale Term"),
+  ],
+};
+
+/** Deliberately inverted: the generic term is used most and scores lowest. */
+const usage: GlossaryUsage = {
+  orders: {
+    "page-action": { count: 9, files: 3, examples: ["PageAction", "getPageActions"] },
+    "order-total": { count: 1, files: 1, examples: ["orderTotal"] },
+    option: { count: 999, files: 40, examples: ["option"] },
+    "unscored-term": { count: 3, files: 1, examples: ["unscoredTerm"] },
+    "stale-term": { count: 20, files: 4, examples: ["staleTerm"] },
+  },
+};
+
+const significance: GlossarySignificance = {
+  orders: {
+    "order-total": { score: 90, reason: "The order total is the domain's central value." },
+    "page-action": { score: 60, reason: "Page actions drive the order workflow." },
+    option: { score: 10, reason: "A framework option token, not a domain term." },
+  },
+};
+
+const ids = (contexts: Glossary[]) =>
+  contexts.flatMap((context) => context.concepts.map((entry) => entry.id));
+
+describe("glossary significance", () => {
+  test("lists a high-score term with one use ahead of a low-score term with 999 uses", () => {
+    expect(conceptUsage(usage, "orders", "option").count).toBe(999);
+    expect(conceptUsage(usage, "orders", "order-total").count).toBe(1);
+
+    const contexts = filterContexts([glossary], {
+      search: "",
+      significantOnly: true,
+      floor: SIGNIFICANCE_FLOOR,
+      significance,
+    });
+    expect(ids(contexts)).toEqual(["order-total", "page-action", "unscored-term"]);
+  });
+
+  test("reveals the low-score term when the significant-only filter is cleared", () => {
+    const contexts = filterContexts([glossary], {
+      search: "",
+      significantOnly: false,
+      floor: SIGNIFICANCE_FLOOR,
+      significance,
+    });
+    expect(ids(contexts)).toEqual([
+      "order-total",
+      "page-action",
+      "option",
+      "unscored-term",
+    ]);
+    expect(ids(filterContexts([glossary], { search: "", significantOnly: true, floor: 0, significance })))
+      .toEqual(["order-total", "page-action", "option", "unscored-term"]);
+  });
+
+  test("never lists an invalidated term and breaks a tie by the displayed term label", () => {
+    const tied: GlossarySignificance = {
+      orders: {
+        "page-action": { score: 70, reason: "One evidence line." },
+        "order-total": { score: 70, reason: "One evidence line." },
+      },
+    };
+    const contexts = filterContexts([glossary], {
+      search: "",
+      significantOnly: true,
+      floor: SIGNIFICANCE_FLOOR,
+      significance: tied,
+    });
+    expect(ids(contexts)).toEqual(["order-total", "page-action", "option", "unscored-term"]);
+    expect(ids(contexts)).not.toContain("stale-term");
+  });
+
+  test("composes the floor with the search", () => {
+    expect(
+      ids(
+        filterContexts([glossary], {
+          search: "total",
+          significantOnly: true,
+          floor: SIGNIFICANCE_FLOOR,
+          significance,
+        }),
+      ),
+    ).toEqual(["order-total"]);
+    expect(
+      filterContexts([glossary], {
+        search: "option",
+        significantOnly: true,
+        floor: SIGNIFICANCE_FLOOR,
+        significance,
+      }),
+    ).toEqual([]);
+    expect(
+      ids(
+        filterContexts([glossary], {
+          search: "option",
+          significantOnly: false,
+          floor: SIGNIFICANCE_FLOOR,
+          significance,
+        }),
+      ),
+    ).toEqual(["option"]);
+  });
+
+  test("hides nothing when no concept is scored", () => {
+    expect(glossaryHasSignificance([glossary], significance)).toBe(true);
+    expect(glossaryHasSignificance([glossary], {})).toBe(false);
+
+    const contexts = filterContexts([glossary], {
+      search: "",
+      significantOnly: true,
+      floor: SIGNIFICANCE_FLOOR,
+      significance: {},
+    });
+    expect(ids(contexts)).toEqual([
+      "option",
+      "order-total",
+      "page-action",
+      "unscored-term",
+    ]);
+    for (const context of contexts) {
+      for (const entry of context.concepts) {
+        expect(conceptSignificance({}, context.boundedContext, entry.id)).toBeUndefined();
+      }
+    }
+  });
+
+  test("reports the measured usage the term page keeps", () => {
+    expect(conceptUsage(usage, "orders", "page-action")).toEqual({
+      count: 9,
+      files: 3,
+      examples: ["PageAction", "getPageActions"],
+    });
+    expect(conceptUsage(usage, "orders", "missing")).toEqual({
+      count: 0,
+      files: 0,
+      examples: [],
+    });
+  });
+});
+
+describe("test levels", () => {
+  const levels: Leaf = {
+    value: [
+      { level: "contract", tests: "0", happyPath: "0", command: "npm run test:contract" },
+      { level: "unit", tests: "118", happyPath: "92", command: "npm run test:unit" },
+      { level: "integration", tests: "4", happyPath: "1", command: "node --test" },
+    ],
+    evidence: ["package.json"],
+    confidence: "observed",
+  };
+
+  test("lists a level only when it carries a test", () => {
+    expect(pyramidTiers(levels).map((tier) => tier.level)).toEqual([
+      "unit",
+      "integration",
+      "contract",
+    ]);
+    expect(implementedTiers(pyramidTiers(levels)).map((tier) => tier.level)).toEqual([
+      "unit",
+      "integration",
+    ]);
+  });
+
+  test("keeps an unparsable count out of the implemented levels", () => {
+    const unknown: Leaf = {
+      value: [{ level: "unit", tests: "unknown" }],
+      evidence: ["package.json"],
+      confidence: "observed",
+    };
+    expect(implementedTiers(pyramidTiers(unknown))).toEqual([]);
+  });
+
+  test("sums happy-path counts only across implemented levels", () => {
+    const tiers = implementedTiers(pyramidTiers(levels));
+    expect(tiers.map((tier) => [tier.level, tier.tests, tier.happyPath, tier.command])).toEqual([
+      ["unit", "118", "92", "npm run test:unit"],
+      ["integration", "4", "1", "node --test"],
+    ]);
+    expect(pyramidHappyPathCount(tiers)).toEqual({ happy: 93, tests: 122 });
+  });
+
+  test("refuses a happy-path total when a level never reported one", () => {
+    const partial: Leaf = {
+      value: [
+        { level: "unit", tests: "10", happyPath: "6" },
+        { level: "integration", tests: "2" },
+      ],
+      evidence: ["package.json"],
+      confidence: "observed",
+    };
+    expect(pyramidHappyPathCount(implementedTiers(pyramidTiers(partial)))).toBeNull();
+  });
+
+  test("prefers the manifest's declaration for a recorded command", () => {
+    const aliases = [
+      { command: "node --test test/*.test.js", alias: "npm test" },
+      { command: "node --test test/unit/*.js", alias: "npm run test:unit" },
+    ];
+    expect(commandAlias(aliases, "node --test test/*.test.js")).toBe("npm test");
+    expect(commandAlias(aliases, " node  --test   test/unit/*.js ")).toBe("npm run test:unit");
+    expect(commandAlias(aliases, "pytest tests")).toBe("pytest tests");
+    expect(commandAlias(undefined, "pytest tests")).toBe("pytest tests");
+  });
+});
+
+describe("relative time", () => {
+  const started = "2026-10-27T10:00:00.000Z";
+  const at = Date.parse(started);
+
+  test("reads a recent start as just now", () => {
+    expect(relativeTime(started, at + 5_000)).toBe("just now");
+    expect(relativeTime(started, at - 30_000)).toBe("just now");
+  });
+
+  test("names the elapsed minutes, hours, and days", () => {
+    expect(relativeTime(started, at + 60_000)).toBe("a minute ago");
+    expect(relativeTime(started, at + 5 * 60_000)).toBe("5 minutes ago");
+    expect(relativeTime(started, at + 3 * 3_600_000)).toBe("3 hours ago");
+    expect(relativeTime(started, at + 30 * 3_600_000)).toBe("yesterday");
+    expect(relativeTime(started, at + 5 * 86_400_000)).toBe("5 days ago");
+  });
+
+  test("returns nothing for a timestamp it cannot read", () => {
+    expect(relativeTime("", at)).toBe("");
+    expect(relativeTime("not a date", at)).toBe("");
+  });
+});