@crewhaus/report-writer 0.1.4 → 0.1.5

package/dist/index.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Catalog R-orch `report-writer` — Section 23 RES.
+ *
+ * Assembles a research run's markdown + JSON report from:
+ *   - the goal,
+ *   - the planner's sub-questions,
+ *   - one answer per branch,
+ *   - the citation tracker.
+ *
+ * Citation numbering is the load-bearing detail: numbers are assigned by
+ * URL on first appearance (NOT by the order the agent emitted citations
+ * within a branch), so a re-run that takes a slightly different path
+ * but ends up with the same citation set produces a byte-identical
+ * citation block — the smoke's "deterministic ordering" assertion.
+ *
+ * The markdown report is structured for terminal `less` reading:
+ *   # <goal>
+ *
+ *   ## <sub-question 1>
+ *   <answer 1, with [N] markers>
+ *
+ *   ## <sub-question 2>
+ *   <answer 2, with [N] markers>
+ *
+ *   ## Citations
+ *   [1] <url>
+ *       <snippet>
+ *   [2] <url>
+ *       <snippet>
+ *
+ * The JSON report carries the same data programmatically so studio /
+ * downstream consumers don't have to re-parse markdown.
+ */
+import type { Citation } from "@crewhaus/citation-tracker";
+export type BranchAnswer = {
+    readonly question: string;
+    readonly answer: string;
+    /** URLs the agent emitted citations against during this branch. */
+    readonly citationUrls: ReadonlyArray<string>;
+};
+export type Report = {
+    readonly markdown: string;
+    readonly json: ReportJson;
+};
+export type ReportJson = {
+    readonly version: 1;
+    readonly goal: string;
+    readonly subAnswers: ReadonlyArray<{
+        readonly question: string;
+        readonly answer: string;
+        readonly citationNumbers: ReadonlyArray<number>;
+    }>;
+    readonly citations: ReadonlyArray<NumberedCitation>;
+    readonly generatedAt: string;
+};
+export type NumberedCitation = {
+    readonly number: number;
+    readonly url: string;
+    readonly snippet: string;
+    readonly sha256: string;
+    readonly retrievedAt: string;
+};
+export type WriteReportArgs = {
+    readonly goal: string;
+    readonly branches: ReadonlyArray<BranchAnswer>;
+    /** Append-ordered list of citations from the tracker. */
+    readonly citations: ReadonlyArray<Citation>;
+    readonly now?: () => Date;
+};
+export declare function writeReport(args: WriteReportArgs): Report;

package/dist/index.js

@@ -0,0 +1,77 @@
+/**
+ * Number citations by URL on first appearance. Same URL appearing in
+ * multiple branches reuses the first-assigned number; the snippet text
+ * for the numbered entry comes from the FIRST citation against that URL.
+ */
+function numberCitations(citations) {
+    const numberByUrl = new Map();
+    const numbered = [];
+    for (const c of citations) {
+        if (numberByUrl.has(c.url))
+            continue;
+        const n = numberByUrl.size + 1;
+        numberByUrl.set(c.url, n);
+        numbered.push({
+            number: n,
+            url: c.url,
+            snippet: c.snippet,
+            sha256: c.sha256,
+            retrievedAt: c.retrievedAt,
+        });
+    }
+    return { numbered, numberByUrl };
+}
+function citationNumbersForBranch(branch, numberByUrl) {
+    const seen = new Set();
+    const out = [];
+    for (const url of branch.citationUrls) {
+        const n = numberByUrl.get(url);
+        if (n === undefined)
+            continue;
+        if (seen.has(n))
+            continue;
+        seen.add(n);
+        out.push(n);
+    }
+    out.sort((a, b) => a - b);
+    return out;
+}
+function renderMarkdown(args) {
+    const lines = [];
+    lines.push(`# ${args.goal}`);
+    lines.push("");
+    for (const b of args.branches) {
+        lines.push(`## ${b.question}`);
+        lines.push("");
+        lines.push(b.answer.trim());
+        lines.push("");
+    }
+    if (args.numbered.length > 0) {
+        lines.push("## Citations");
+        lines.push("");
+        for (const c of args.numbered) {
+            lines.push(`[${c.number}] ${c.url}`);
+            const trimmed = c.snippet.trim().replace(/\n+/g, " ");
+            lines.push(`    ${trimmed}`);
+        }
+    }
+    return `${lines.join("\n").trimEnd()}\n`;
+}
+export function writeReport(args) {
+    const { numbered, numberByUrl } = numberCitations(args.citations);
+    const subAnswers = args.branches.map((b) => ({
+        question: b.question,
+        answer: b.answer,
+        citationNumbers: citationNumbersForBranch(b, numberByUrl),
+    }));
+    const now = args.now ?? (() => new Date());
+    const json = {
+        version: 1,
+        goal: args.goal,
+        subAnswers,
+        citations: numbered,
+        generatedAt: now().toISOString(),
+    };
+    const markdown = renderMarkdown({ goal: args.goal, branches: args.branches, numbered });
+    return { markdown, json };
+}

package/package.json

@@ -1,19 +1,22 @@
 {
   "name": "@crewhaus/report-writer",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "type": "module",
   "description": "Markdown + JSON report assembly from citations + branch answers (Section 23 RES)",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "scripts": {
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/citation-tracker": "0.1.4",
-    "@crewhaus/errors": "0.1.4"
+    "@crewhaus/citation-tracker": "0.1.5",
+    "@crewhaus/errors": "0.1.5"
   },
   "license": "Apache-2.0",
   "author": {
@@ -33,5 +36,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["src", "README.md", "LICENSE", "NOTICE"]
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
 }

package/src/index.test.ts

@@ -1,107 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import type { Citation } from "@crewhaus/citation-tracker";
-import { writeReport } from "./index.js";
-
-function citation(url: string, snippet: string, branchId?: string): Citation {
-  return {
-    version: 1,
-    url,
-    snippet,
-    retrievedAt: "2026-05-08T00:00:00.000Z",
-    sha256: "0".repeat(64),
-    ...(branchId !== undefined ? { branchId } : {}),
-  };
-}
-
-describe("writeReport", () => {
-  test("numbers citations by URL on first appearance", () => {
-    const citations: Citation[] = [
-      citation("https://a.example.com", "snippet A"),
-      citation("https://b.example.com", "snippet B"),
-      citation("https://a.example.com", "snippet A again"),
-    ];
-    const r = writeReport({
-      goal: "g",
-      branches: [
-        {
-          question: "q1",
-          answer: "answer 1",
-          citationUrls: ["https://a.example.com", "https://b.example.com"],
-        },
-      ],
-      citations,
-    });
-    expect(r.json.citations.map((c) => `${c.number}:${c.url}`)).toEqual([
-      "1:https://a.example.com",
-      "2:https://b.example.com",
-    ]);
-    // Branch's citationNumbers are sorted, with same-URL collapsed.
-    expect(r.json.subAnswers[0]?.citationNumbers).toEqual([1, 2]);
-  });
-
-  test("re-running with identical citation set produces byte-identical citation blocks (deterministic ordering)", () => {
-    const citationsA: Citation[] = [
-      citation("https://a.example.com", "snip a"),
-      citation("https://b.example.com", "snip b"),
-      citation("https://c.example.com", "snip c"),
-    ];
-    const citationsB: Citation[] = [...citationsA];
-    const ra = writeReport({
-      goal: "g",
-      branches: [{ question: "q1", answer: "ans", citationUrls: ["https://a.example.com"] }],
-      citations: citationsA,
-      now: () => new Date("2026-01-01T00:00:00Z"),
-    });
-    const rb = writeReport({
-      goal: "g",
-      branches: [{ question: "q1", answer: "ans", citationUrls: ["https://a.example.com"] }],
-      citations: citationsB,
-      now: () => new Date("2026-01-01T00:00:00Z"),
-    });
-    // Citation block (JSON-side): identical.
-    expect(JSON.stringify(ra.json.citations)).toBe(JSON.stringify(rb.json.citations));
-    // Markdown citation footer: identical.
-    const footer = (s: string): string => s.split("## Citations")[1] ?? "";
-    expect(footer(ra.markdown)).toBe(footer(rb.markdown));
-  });
-
-  test("markdown structure: goal H1, sub-question H2 per branch, citations footer", () => {
-    const r = writeReport({
-      goal: "Top risks of crews",
-      branches: [
-        { question: "What are the technical risks?", answer: "answer 1", citationUrls: [] },
-        { question: "What are the operational risks?", answer: "answer 2", citationUrls: [] },
-      ],
-      citations: [],
-    });
-    expect(r.markdown).toMatch(/^# Top risks of crews\n/);
-    expect(r.markdown).toContain("## What are the technical risks?");
-    expect(r.markdown).toContain("## What are the operational risks?");
-    // No citations footer when there are zero citations.
-    expect(r.markdown.includes("## Citations")).toBe(false);
-  });
-
-  test("produces a stable JSON shape (snapshot-friendly)", () => {
-    const r = writeReport({
-      goal: "G",
-      branches: [{ question: "Q", answer: "A", citationUrls: ["https://x"] }],
-      citations: [citation("https://x", "snip")],
-      now: () => new Date("2026-01-01T00:00:00Z"),
-    });
-    expect(r.json).toEqual({
-      version: 1,
-      goal: "G",
-      subAnswers: [{ question: "Q", answer: "A", citationNumbers: [1] }],
-      citations: [
-        {
-          number: 1,
-          url: "https://x",
-          snippet: "snip",
-          sha256: "0".repeat(64),
-          retrievedAt: "2026-05-08T00:00:00.000Z",
-        },
-      ],
-      generatedAt: "2026-01-01T00:00:00.000Z",
-    });
-  });
-});

package/src/index.ts

@@ -1,162 +0,0 @@
-/**
- * Catalog R-orch `report-writer` — Section 23 RES.
- *
- * Assembles a research run's markdown + JSON report from:
- *   - the goal,
- *   - the planner's sub-questions,
- *   - one answer per branch,
- *   - the citation tracker.
- *
- * Citation numbering is the load-bearing detail: numbers are assigned by
- * URL on first appearance (NOT by the order the agent emitted citations
- * within a branch), so a re-run that takes a slightly different path
- * but ends up with the same citation set produces a byte-identical
- * citation block — the smoke's "deterministic ordering" assertion.
- *
- * The markdown report is structured for terminal `less` reading:
- *   # <goal>
- *
- *   ## <sub-question 1>
- *   <answer 1, with [N] markers>
- *
- *   ## <sub-question 2>
- *   <answer 2, with [N] markers>
- *
- *   ## Citations
- *   [1] <url>
- *       <snippet>
- *   [2] <url>
- *       <snippet>
- *
- * The JSON report carries the same data programmatically so studio /
- * downstream consumers don't have to re-parse markdown.
- */
-import type { Citation } from "@crewhaus/citation-tracker";
-
-export type BranchAnswer = {
-  readonly question: string;
-  readonly answer: string;
-  /** URLs the agent emitted citations against during this branch. */
-  readonly citationUrls: ReadonlyArray<string>;
-};
-
-export type Report = {
-  readonly markdown: string;
-  readonly json: ReportJson;
-};
-
-export type ReportJson = {
-  readonly version: 1;
-  readonly goal: string;
-  readonly subAnswers: ReadonlyArray<{
-    readonly question: string;
-    readonly answer: string;
-    readonly citationNumbers: ReadonlyArray<number>;
-  }>;
-  readonly citations: ReadonlyArray<NumberedCitation>;
-  readonly generatedAt: string;
-};
-
-export type NumberedCitation = {
-  readonly number: number;
-  readonly url: string;
-  readonly snippet: string;
-  readonly sha256: string;
-  readonly retrievedAt: string;
-};
-
-export type WriteReportArgs = {
-  readonly goal: string;
-  readonly branches: ReadonlyArray<BranchAnswer>;
-  /** Append-ordered list of citations from the tracker. */
-  readonly citations: ReadonlyArray<Citation>;
-  readonly now?: () => Date;
-};
-
-/**
- * Number citations by URL on first appearance. Same URL appearing in
- * multiple branches reuses the first-assigned number; the snippet text
- * for the numbered entry comes from the FIRST citation against that URL.
- */
-function numberCitations(citations: ReadonlyArray<Citation>): {
-  numbered: NumberedCitation[];
-  numberByUrl: Map<string, number>;
-} {
-  const numberByUrl = new Map<string, number>();
-  const numbered: NumberedCitation[] = [];
-  for (const c of citations) {
-    if (numberByUrl.has(c.url)) continue;
-    const n = numberByUrl.size + 1;
-    numberByUrl.set(c.url, n);
-    numbered.push({
-      number: n,
-      url: c.url,
-      snippet: c.snippet,
-      sha256: c.sha256,
-      retrievedAt: c.retrievedAt,
-    });
-  }
-  return { numbered, numberByUrl };
-}
-
-function citationNumbersForBranch(
-  branch: BranchAnswer,
-  numberByUrl: Map<string, number>,
-): number[] {
-  const seen = new Set<number>();
-  const out: number[] = [];
-  for (const url of branch.citationUrls) {
-    const n = numberByUrl.get(url);
-    if (n === undefined) continue;
-    if (seen.has(n)) continue;
-    seen.add(n);
-    out.push(n);
-  }
-  out.sort((a, b) => a - b);
-  return out;
-}
-
-function renderMarkdown(args: {
-  goal: string;
-  branches: ReadonlyArray<BranchAnswer>;
-  numbered: ReadonlyArray<NumberedCitation>;
-}): string {
-  const lines: string[] = [];
-  lines.push(`# ${args.goal}`);
-  lines.push("");
-  for (const b of args.branches) {
-    lines.push(`## ${b.question}`);
-    lines.push("");
-    lines.push(b.answer.trim());
-    lines.push("");
-  }
-  if (args.numbered.length > 0) {
-    lines.push("## Citations");
-    lines.push("");
-    for (const c of args.numbered) {
-      lines.push(`[${c.number}] ${c.url}`);
-      const trimmed = c.snippet.trim().replace(/\n+/g, " ");
-      lines.push(`    ${trimmed}`);
-    }
-  }
-  return `${lines.join("\n").trimEnd()}\n`;
-}
-
-export function writeReport(args: WriteReportArgs): Report {
-  const { numbered, numberByUrl } = numberCitations(args.citations);
-  const subAnswers = args.branches.map((b) => ({
-    question: b.question,
-    answer: b.answer,
-    citationNumbers: citationNumbersForBranch(b, numberByUrl),
-  }));
-  const now = args.now ?? (() => new Date());
-  const json: ReportJson = {
-    version: 1,
-    goal: args.goal,
-    subAnswers,
-    citations: numbered,
-    generatedAt: now().toISOString(),
-  };
-  const markdown = renderMarkdown({ goal: args.goal, branches: args.branches, numbered });
-  return { markdown, json };
-}