docsgov 0.1.0

package/dist/dedup/report/text.js

@@ -0,0 +1,251 @@
+// Renders a dedup Report as plain text. Ported from
+// internal/dedup/report/text.go.
+//
+// Render returns the structured Report as a string. The Go signature was
+// Render(w io.Writer, r, cfg) error, accumulating the first write error; here
+// we build the output in memory and return it (matching the existing TS report
+// port in ../../report, which also returns a string). The only Go caller wrote
+// to os.Stdout, which the TS CLI does as process.stdout.write(Render(...)). The
+// in-memory builder never fails, so there is no error return.
+//
+// The output format is byte-matched to the Go binary's output (and ultimately
+// the Python POC's dedup.py output): the golden-test oracle compares it
+// byte-for-byte. No color/styling is involved — this is plain text, so there is
+// no TTY-dependent path to guard.
+import { QuoteHeading } from "./quote.js";
+import { formatFloat2 } from "./floatfmt.js";
+/**
+ * Render returns the duplicate-detection report as text, using cfg for
+ * formatting (separator, wrap columns). Mirrors Go's report.Render.
+ */
+export function Render(r, cfg) {
+    if (r.HighGroups.length === 0 &&
+        r.MaybePairs.length === 0 &&
+        r.PartialOverlaps.length === 0) {
+        return "No duplicate documentation concepts found.\n";
+    }
+    const p = new Printer(cfg);
+    // Header.
+    p.printf(`Duplicate documentation concepts found: ${r.HighGroups.length}\n`);
+    if (r.MaybePairs.length > 0) {
+        p.printf(`Possible pairs needing review: ${r.MaybePairs.length}\n`);
+    }
+    p.print("\n");
+    const sep = p.cfg.separator + "\n\n";
+    // High-confidence groups.
+    for (let gi = 0; gi < r.HighGroups.length; gi++) {
+        if (gi > 0) {
+            p.print(sep);
+        }
+        p.renderGroup(gi + 1, r.HighGroups[gi]);
+    }
+    // Possible pairs.
+    if (r.MaybePairs.length > 0) {
+        if (r.HighGroups.length > 0) {
+            p.print(sep);
+        }
+        p.print("Possible pairs (manual review)\n\n");
+        for (let pi = 0; pi < r.MaybePairs.length; pi++) {
+            if (pi > 0) {
+                p.print(sep);
+            }
+            p.renderPair(pi + 1, r.MaybePairs[pi]);
+        }
+    }
+    // Partial overlaps (L5 block-level findings).
+    if (r.PartialOverlaps.length > 0) {
+        if (r.HighGroups.length > 0 || r.MaybePairs.length > 0) {
+            p.print(sep);
+        }
+        p.print("Partial overlaps (manual review)\n\n");
+        for (let ci = 0; ci < r.PartialOverlaps.length; ci++) {
+            if (ci > 0) {
+                p.print(sep);
+            }
+            p.renderCluster(ci + 1, r.PartialOverlaps[ci]);
+        }
+    }
+    return p.out;
+}
+// Printer accumulates the rendered output. (Go: printer over an io.Writer.)
+class Printer {
+    out = "";
+    cfg;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    print(s) {
+        this.out += s;
+    }
+    printf(s) {
+        this.out += s;
+    }
+    renderGroup(n, grp) {
+        this.printf(`[Group ${n}] ${grp.Canonical.Heading}\n`);
+        this.printf(`Confidence: ${grp.Confidence}\n`);
+        this.printf(`Recommended action: ${grp.Action}\n\n`);
+        this.print("Canonical candidate:\n");
+        this.printf(`  ${grp.Canonical.FilePath}#${grp.Canonical.Anchor}\n`);
+        this.printf(`  (lines ${grp.Canonical.StartLine}-${grp.Canonical.EndLine})\n`);
+        if (grp.Canonical.InboundCount > 0) {
+            this.printf(`  inbound links: ${grp.Canonical.InboundCount}\n`);
+        }
+        this.emitPreview(grp.Canonical.Preview, "  ");
+        this.print("\n");
+        this.print("Duplicate sections:\n");
+        for (let mi = 0; mi < grp.Members.length; mi++) {
+            const m = grp.Members[mi];
+            this.printf(`  ${mi + 1}. ${m.FilePath}#${m.Anchor}\n`);
+            this.printf(`     Heading: ${m.Heading}\n`);
+            this.printf(`     Similarity: ${formatFloat2(m.Similarity)}\n`);
+            if (m.ExactMatch) {
+                this.print("     (prose is byte-identical to canonical after normalization)\n");
+            }
+            this.print("     Reason:\n");
+            for (const reason of m.Reasons) {
+                this.printf(`       - ${reason}\n`);
+            }
+            this.emitPreview(m.Preview, "     ");
+        }
+        this.print("\n");
+        this.print("Suggested replacement:\n");
+        this.printf(`  Keep the canonical section in ${grp.Canonical.FilePath}.\n`);
+        this.print("  Replace duplicated sections with short summaries and links to:\n");
+        this.printf(`  ${grp.Canonical.FilePath}#${grp.Canonical.Anchor}\n\n`);
+    }
+    renderPair(n, pair) {
+        this.printf(`[Pair ${n}] similarity ${formatFloat2(pair.Similarity)}\n`);
+        // canonical line (10 chars for "  canonical?  ").
+        this.printf(`  canonical?  ${pair.Canonical.FilePath}#${pair.Canonical.Anchor}\n`);
+        // heading repr: exactly 14 spaces indent.
+        this.printf(`              (${QuoteHeading(pair.Canonical.Heading)})\n`);
+        this.emitPreview(pair.Canonical.Preview, "    ");
+        this.printf(`  candidate   ${pair.Candidate.FilePath}#${pair.Candidate.Anchor}\n`);
+        this.printf(`              (${QuoteHeading(pair.Candidate.Heading)})\n`);
+        this.emitPreview(pair.Candidate.Preview, "    ");
+        for (const reason of pair.Reasons) {
+            this.printf(`    - ${reason}\n`);
+        }
+        this.print("\n");
+    }
+    renderCluster(n, cl) {
+        // Header: kind + exact/cosine indicator.
+        if (cl.Exact) {
+            this.printf(`[Cluster ${n}] ${cl.Kind}  identical (verbatim)\n`);
+        }
+        else {
+            this.printf(`[Cluster ${n}] ${cl.Kind}  cosine=${formatFloat2(cl.Similarity)}\n`);
+        }
+        // Informational tag: distinct file count from locations.
+        if (cl.Informational) {
+            const fileSet = new Set();
+            for (const loc of cl.Locations) {
+                fileSet.add(loc.FilePath);
+            }
+            this.printf(`  appears in ${fileSet.size} files — likely intentional; consider a shared snippet\n`);
+        }
+        // Each location.
+        for (const loc of cl.Locations) {
+            this.printf(`  ${loc.FilePath}  (lines ${loc.StartLine}-${loc.EndLine})\n`);
+            this.printf(`     Heading: ${loc.Heading}\n`);
+        }
+        this.print("\n");
+    }
+    // emitPreview writes the word-wrapped preview lines.
+    // If preview is empty, writes "(no prose content)".
+    emitPreview(preview, indent) {
+        if (preview === "") {
+            this.printf(`${indent}Preview: (no prose content)\n`);
+            return;
+        }
+        // Word-wrap at cfg.wrap_cols columns with the initial indent including
+        // "Preview: ".
+        const initialIndent = indent + "Preview: ";
+        const subseqIndent = indent + "         ";
+        const lines = wordWrap(preview, this.cfg.wrap_cols, initialIndent, subseqIndent);
+        for (const line of lines) {
+            this.printf(`${line}\n`);
+        }
+    }
+}
+// wordWrap wraps text at width columns, matching Python's textwrap.wrap and the
+// Go port's behaviour. initialIndent is prepended to the first line,
+// subsequentIndent to subsequent lines.
+//
+// Byte-for-byte note: Go measures width in BYTES (len() over UTF-8), not runes
+// or UTF-16 units. byteLen() below replicates that so multi-byte previews wrap
+// at the same column boundaries Go produces.
+export function wordWrap(text, width, initialIndent, subseqIndent) {
+    const words = fields(text);
+    if (words.length === 0) {
+        return [];
+    }
+    const lines = [];
+    let currentIndent = initialIndent;
+    let sb = currentIndent;
+    let lineLen = byteLen(currentIndent);
+    for (let i = 0; i < words.length; i++) {
+        const w = words[i];
+        let addLen = byteLen(w);
+        if (i > 0) {
+            addLen++; // space
+        }
+        if (lineLen > byteLen(currentIndent) && lineLen + addLen > width) {
+            // Flush line and start new.
+            lines.push(sb);
+            currentIndent = subseqIndent;
+            sb = currentIndent;
+            lineLen = byteLen(currentIndent);
+            sb += w;
+            lineLen += byteLen(w);
+        }
+        else {
+            if (lineLen > byteLen(currentIndent)) {
+                sb += " ";
+                lineLen++;
+            }
+            sb += w;
+            lineLen += byteLen(w);
+        }
+    }
+    if (sb.length > 0) {
+        lines.push(sb);
+    }
+    return lines;
+}
+// byteLen returns the UTF-8 byte length of s, matching Go's len(string).
+function byteLen(s) {
+    return Buffer.byteLength(s, "utf8");
+}
+// goSpace is exactly Go's unicode.IsSpace codepoint set. It differs from JS's
+// regex \s by including U+0085 (NEL) and excluding U+FEFF (ZWNBSP/BOM), so we
+// match Go's strings.Fields tokenization rather than relying on \s.
+const goSpace = new Set([
+    0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x20, 0x85, 0xa0, 0x1680, 0x2000, 0x2001,
+    0x2002, 0x2003, 0x2004, 0x2005, 0x2006, 0x2007, 0x2008, 0x2009, 0x200a,
+    0x2028, 0x2029, 0x202f, 0x205f, 0x3000,
+]);
+// fields splits s around runs of Go-whitespace, dropping empty tokens.
+// Equivalent to Go's strings.Fields. Iterates by codepoint so astral whitespace
+// (none in goSpace today, but the iteration is codepoint-correct regardless) is
+// handled as a single separator.
+function fields(s) {
+    const out = [];
+    let cur = "";
+    for (const ch of s) {
+        const c = ch.codePointAt(0);
+        if (goSpace.has(c)) {
+            if (cur !== "") {
+                out.push(cur);
+                cur = "";
+            }
+        }
+        else {
+            cur += ch;
+        }
+    }
+    if (cur !== "") {
+        out.push(cur);
+    }
+    return out;
+}

package/dist/dedup/report/text.test.js

@@ -0,0 +1,420 @@
+// Behavior-encoding tests for the dedup report renderer, ported from
+// internal/dedup/report/text_test.go (and quote.go's locked rules).
+//
+// WHY this output is pinned so tightly: Render's text is compared BYTE-FOR-BYTE
+// by the dedup golden-test oracle against the Go binary's output. A drift in
+// section ordering, separators, indentation, the %.2f similarity rounding, the
+// QuoteHeading repr, or the wrap math would silently break oracle parity. Each
+// test below encodes one such invariant and asserts the exact string, not a
+// loose contains() where the Go test was loose only because Go could not easily
+// assert the whole stanza.
+import { describe, it, expect } from "vitest";
+import { Render, QuoteHeading } from "./index.js";
+import { Default } from "../config.js";
+const cfg = Default().Report;
+// emptyReport is the zero-value Report (Go: &dedup.Report{}). All three slices
+// are empty, exercising the "no findings" path.
+function emptyReport() {
+    return { HighGroups: [], MaybePairs: [], PartialOverlaps: [] };
+}
+// makeSimpleMember mirrors the Go fixture of the same name.
+function makeSimpleMember(id, fp, anchor, heading, exact) {
+    return {
+        SectionID: id,
+        FilePath: fp,
+        Anchor: anchor,
+        Heading: heading,
+        StartLine: 1,
+        EndLine: 10,
+        InboundCount: 0,
+        Similarity: 0.95,
+        Reasons: ["high semantic similarity (cosine=0.950)"],
+        ExactMatch: exact,
+        Preview: "This is the preview content of the section.",
+    };
+}
+function makeSimpleHighReport() {
+    const canonical = makeSimpleMember("id1", "docs/concepts/a.md", "lifecycle", "Order Lifecycle", false);
+    canonical.Similarity = 1.0;
+    const member = makeSimpleMember("id2", "docs/design/b.md", "lifecycle", "Order Lifecycle", true);
+    return {
+        HighGroups: [
+            {
+                Canonical: canonical,
+                Members: [member],
+                Confidence: "high",
+                Action: "replace_with_reference",
+            },
+        ],
+        MaybePairs: [],
+        PartialOverlaps: [],
+    };
+}
+function makeSimpleMaybeReport() {
+    const canonical = makeSimpleMember("id1", "docs/concepts/a.md", "lifecycle", "Order Lifecycle", false);
+    canonical.Similarity = 1.0;
+    const candidate = makeSimpleMember("id2", "docs/design/b.md", "lifecycle-2", "Order Lifecycle Guide", false);
+    candidate.Similarity = 0.89;
+    return {
+        HighGroups: [],
+        MaybePairs: [
+            {
+                Canonical: canonical,
+                Candidate: candidate,
+                Similarity: 0.89,
+                Reasons: ["possible semantic similarity (cosine=0.890)"],
+            },
+        ],
+        PartialOverlaps: [],
+    };
+}
+// makeReportWithGroupsAndPairs returns a Report with nGroups HIGH groups and
+// nPairs MAYBE pairs. Mirrors the Go fixture (ids use 'a'+i suffixes).
+function makeReportWithGroupsAndPairs(nGroups, nPairs) {
+    const r = { HighGroups: [], MaybePairs: [], PartialOverlaps: [] };
+    for (let i = 0; i < nGroups; i++) {
+        const suffix = String.fromCharCode("a".charCodeAt(0) + i);
+        const canonical = makeSimpleMember("can" + suffix, "docs/concepts/file.md", "section", "Section Heading", false);
+        canonical.Similarity = 1.0;
+        const member = makeSimpleMember("mem" + suffix, "docs/design/file.md", "section", "Section Heading", false);
+        r.HighGroups.push({
+            Canonical: canonical,
+            Members: [member],
+            Confidence: "high",
+            Action: "replace_with_reference",
+        });
+    }
+    for (let i = 0; i < nPairs; i++) {
+        const suffix = String.fromCharCode("a".charCodeAt(0) + i);
+        const canonical = makeSimpleMember("pcan" + suffix, "docs/concepts/file.md", "pair-section", "Pair Section", false);
+        canonical.Similarity = 1.0;
+        const candidate = makeSimpleMember("pcand" + suffix, "docs/design/file.md", "pair-section", "Pair Section Variant", false);
+        candidate.Similarity = 0.89;
+        r.MaybePairs.push({
+            Canonical: canonical,
+            Candidate: candidate,
+            Similarity: 0.89,
+            Reasons: ["possible semantic similarity (cosine=0.890)"],
+        });
+    }
+    return r;
+}
+// ---------- QuoteHeading ----------
+// WHY: the heading repr is embedded in pair stanzas and is part of the
+// byte-exact output. Each case locks one escaping rule from quote.go's contract.
+describe("QuoteHeading", () => {
+    it("ascii with no specials is wrapped in single quotes only", () => {
+        // No escapes -> just surrounding quotes; a regression that over-escaped
+        // would corrupt every plain heading in the report.
+        expect(QuoteHeading("Order Lifecycle")).toBe("'Order Lifecycle'");
+    });
+    it("escapes an embedded single quote", () => {
+        // The wrapping quote is single-quote, so an inner ' must be backslashed or
+        // the repr would be unbalanced.
+        expect(QuoteHeading("It's a heading")).toBe("'It\\'s a heading'");
+    });
+    it("escapes backslashes", () => {
+        // A literal backslash must double so the repr round-trips like Python's.
+        expect(QuoteHeading("Path\\To\\File")).toBe("'Path\\\\To\\\\File'");
+    });
+    it("escapes control chars below 0x20 (tab -> \\t)", () => {
+        // Control chars are escaped so a stray tab cannot disturb the fixed-column
+        // layout of the stanza.
+        expect(QuoteHeading("Head\ting")).toBe("'Head\\ting'");
+    });
+    it("escapes DEL (0x7f) as \\x7f", () => {
+        // DEL is the one >= 0x20 ASCII char that is still escaped.
+        expect(QuoteHeading("Head\x7fing")).toBe("'Head\\x7fing'");
+    });
+    it("passes CJK through literally, NOT as \\uXXXX", () => {
+        // The locked rule (plan §366): non-ASCII bytes are verbatim so CJK docs read
+        // naturally. Escaping them would diverge from the Go/POC output byte-for-byte.
+        expect(QuoteHeading("補貨單流程")).toBe("'補貨單流程'");
+    });
+});
+// ---------- Render: no findings ----------
+describe("Render no findings", () => {
+    it("returns the exact single-line no-findings message", () => {
+        // A clean doc tree must produce this exact line (and nothing else) so the
+        // CLI's empty-report path stays diffable and the exit code logic upstream
+        // sees no groups.
+        expect(Render(emptyReport(), cfg)).toBe("No duplicate documentation concepts found.\n");
+    });
+});
+// ---------- Render: header counts ----------
+describe("Render header", () => {
+    it("renders both the group count and the pairs count", () => {
+        const out = Render(makeReportWithGroupsAndPairs(2, 3), cfg);
+        expect(out).toContain("Duplicate documentation concepts found: 2");
+        expect(out).toContain("Possible pairs needing review: 3");
+    });
+    it("omits the pairs line when there are zero pairs", () => {
+        // WHY: the pairs count line is conditional; emitting "needing review: 0"
+        // would be noise and would not match Go.
+        const out = Render(makeReportWithGroupsAndPairs(1, 0), cfg);
+        expect(out).not.toContain("Possible pairs needing review");
+    });
+});
+// ---------- Render: group stanza ----------
+describe("Render group stanza", () => {
+    it("contains every labelled section of a high-confidence group", () => {
+        const out = Render(makeSimpleHighReport(), cfg);
+        for (const c of [
+            "[Group 1]",
+            "Confidence: high",
+            "Recommended action: replace_with_reference",
+            "Canonical candidate:",
+            "Duplicate sections:",
+            "Suggested replacement:",
+        ]) {
+            expect(out).toContain(c);
+        }
+    });
+    it("separates consecutive groups with the configured separator", () => {
+        // The separator delimits stanzas; without it two groups would visually merge
+        // and the oracle diff would fail.
+        const out = Render(makeReportWithGroupsAndPairs(2, 0), cfg);
+        expect(out).toContain("\n---\n");
+    });
+    it("renders the full group stanza byte-for-byte", () => {
+        // The contains() checks above mirror the Go test's looseness, but the oracle
+        // is byte-exact — this pins the WHOLE stanza so any indentation / line-order
+        // / similarity-format regression fails here, not silently in the golden run.
+        const out = Render(makeSimpleHighReport(), cfg);
+        const want = "Duplicate documentation concepts found: 1\n" +
+            "\n" +
+            "[Group 1] Order Lifecycle\n" +
+            "Confidence: high\n" +
+            "Recommended action: replace_with_reference\n" +
+            "\n" +
+            "Canonical candidate:\n" +
+            "  docs/concepts/a.md#lifecycle\n" +
+            "  (lines 1-10)\n" +
+            "  Preview: This is the preview content of the section.\n" +
+            "\n" +
+            "Duplicate sections:\n" +
+            "  1. docs/design/b.md#lifecycle\n" +
+            "     Heading: Order Lifecycle\n" +
+            "     Similarity: 0.95\n" +
+            "     (prose is byte-identical to canonical after normalization)\n" +
+            "     Reason:\n" +
+            "       - high semantic similarity (cosine=0.950)\n" +
+            "     Preview: This is the preview content of the section.\n" +
+            "\n" +
+            "Suggested replacement:\n" +
+            "  Keep the canonical section in docs/concepts/a.md.\n" +
+            "  Replace duplicated sections with short summaries and links to:\n" +
+            "  docs/concepts/a.md#lifecycle\n" +
+            "\n";
+        expect(out).toBe(want);
+    });
+    it("emits the exact-match note when ExactMatch is set", () => {
+        const out = Render(makeSimpleHighReport(), cfg);
+        expect(out).toContain("prose is byte-identical to canonical after normalization");
+    });
+    it("never prints 'inbound links: 0' for a zero-inbound canonical", () => {
+        // The inbound-links line is conditional on a positive count; printing 0
+        // would diverge from Go.
+        const out = Render(makeSimpleHighReport(), cfg);
+        expect(out).not.toContain("inbound links: 0");
+    });
+});
+// ---------- Render: pair stanza ----------
+describe("Render pair stanza", () => {
+    it("indents the heading repr line exactly 14 spaces", () => {
+        // The locked format is "              ({heading!r})" with 14 leading spaces;
+        // this column count is part of the byte-exact contract.
+        const out = Render(makeSimpleMaybeReport(), cfg);
+        const lines = out.split("\n");
+        let found14 = false;
+        for (const line of lines) {
+            if (line.startsWith("              (") && line.endsWith(")")) {
+                found14 = true;
+                let spaces = 0;
+                for (const ch of line) {
+                    if (ch === " ") {
+                        spaces++;
+                    }
+                    else {
+                        break;
+                    }
+                }
+                expect(spaces).toBe(14);
+            }
+        }
+        expect(found14).toBe(true);
+    });
+    it("renders the heading repr via QuoteHeading byte-equal (CJK + quote cases)", () => {
+        // WHY: a typo in the `              (%s)` format would slip through an
+        // indentation-only check. Using a CJK heading and a quote-containing heading
+        // makes QuoteHeading's output non-trivially distinct from the raw heading.
+        const canonical = makeSimpleMember("id1", "docs/a.md", "lifecycle", "補貨單流程", false);
+        canonical.Similarity = 1.0;
+        const candidate = makeSimpleMember("id2", "docs/b.md", "flow", "It's the flow", false);
+        candidate.Similarity = 0.89;
+        const r = {
+            HighGroups: [],
+            MaybePairs: [
+                {
+                    Canonical: canonical,
+                    Candidate: candidate,
+                    Similarity: 0.89,
+                    Reasons: ["possible semantic similarity (cosine=0.890)"],
+                },
+            ],
+            PartialOverlaps: [],
+        };
+        const out = Render(r, cfg);
+        expect(out).toContain("              (" + QuoteHeading("補貨單流程") + ")");
+        expect(out).toContain("              (" + QuoteHeading("It's the flow") + ")");
+    });
+    it("renders the full pair stanza byte-for-byte", () => {
+        // Pins the whole MAYBE-pair output, including the 14-space heading indent,
+        // the 4-space preview indent, the "canonical?" / "candidate" labels, the
+        // %.2f similarity (0.89), and the reason bullet.
+        const out = Render(makeSimpleMaybeReport(), cfg);
+        const want = "Duplicate documentation concepts found: 0\n" +
+            "Possible pairs needing review: 1\n" +
+            "\n" +
+            "Possible pairs (manual review)\n" +
+            "\n" +
+            "[Pair 1] similarity 0.89\n" +
+            "  canonical?  docs/concepts/a.md#lifecycle\n" +
+            "              ('Order Lifecycle')\n" +
+            "    Preview: This is the preview content of the section.\n" +
+            "  candidate   docs/design/b.md#lifecycle-2\n" +
+            "              ('Order Lifecycle Guide')\n" +
+            "    Preview: This is the preview content of the section.\n" +
+            "    - possible semantic similarity (cosine=0.890)\n" +
+            "\n";
+        expect(out).toBe(want);
+    });
+});
+// ---------- Render: PartialOverlaps (L5 clusters) ----------
+describe("Render partial overlaps", () => {
+    it("renders an exact cluster's kind and both locations, with no cosine", () => {
+        const r = {
+            HighGroups: [],
+            MaybePairs: [],
+            PartialOverlaps: [
+                {
+                    Kind: "prose",
+                    ContentHash: "abc123",
+                    Similarity: 1.0,
+                    Exact: true,
+                    Informational: false,
+                    Locations: [
+                        { FilePath: "docs/a.md", Heading: "Background", StartLine: 5, EndLine: 12 },
+                        { FilePath: "docs/b.md", Heading: "Intro", StartLine: 20, EndLine: 27 },
+                    ],
+                },
+            ],
+        };
+        const out = Render(r, cfg);
+        expect(out).toContain("Partial overlaps");
+        expect(out).toContain("prose");
+        expect(out).toContain("docs/a.md");
+        expect(out).toContain("docs/b.md");
+        expect(out).toContain("5");
+        expect(out).toContain("12");
+        expect(out).toContain("20");
+        expect(out).toContain("27");
+        // Exact cluster must NOT render a cosine value.
+        expect(out).not.toContain("cosine=");
+        // Non-informational cluster must NOT show the intentional tag.
+        expect(out).not.toContain("likely intentional");
+    });
+    it("renders the full exact cluster stanza byte-for-byte", () => {
+        // Pins the "identical (verbatim)" header and the per-location lines so a
+        // header-format or line-range regression fails here.
+        const r = {
+            HighGroups: [],
+            MaybePairs: [],
+            PartialOverlaps: [
+                {
+                    Kind: "prose",
+                    ContentHash: "abc123",
+                    Similarity: 1.0,
+                    Exact: true,
+                    Informational: false,
+                    Locations: [
+                        { FilePath: "docs/a.md", Heading: "Background", StartLine: 5, EndLine: 12 },
+                        { FilePath: "docs/b.md", Heading: "Intro", StartLine: 20, EndLine: 27 },
+                    ],
+                },
+            ],
+        };
+        const out = Render(r, cfg);
+        const want = "Duplicate documentation concepts found: 0\n" +
+            "\n" +
+            "Partial overlaps (manual review)\n" +
+            "\n" +
+            "[Cluster 1] prose  identical (verbatim)\n" +
+            "  docs/a.md  (lines 5-12)\n" +
+            "     Heading: Background\n" +
+            "  docs/b.md  (lines 20-27)\n" +
+            "     Heading: Intro\n" +
+            "\n";
+        expect(out).toBe(want);
+    });
+    it("renders a cosine cluster's similarity value as cosine=0.96", () => {
+        // WHY: 0.96 is a %.2f format check on a non-exact cluster header.
+        const r = {
+            HighGroups: [],
+            MaybePairs: [],
+            PartialOverlaps: [
+                {
+                    Kind: "prose",
+                    ContentHash: "",
+                    Similarity: 0.96,
+                    Exact: false,
+                    Informational: false,
+                    Locations: [
+                        { FilePath: "docs/x.md", Heading: "Sec X", StartLine: 1, EndLine: 5 },
+                        { FilePath: "docs/y.md", Heading: "Sec Y", StartLine: 10, EndLine: 14 },
+                    ],
+                },
+            ],
+        };
+        const out = Render(r, cfg);
+        expect(out).toContain("cosine=0.96");
+    });
+    it("renders the informational tag with the distinct file count", () => {
+        // The boilerplate tag counts DISTINCT files (a Set), here 6, and includes
+        // the shared-snippet hint. The em dash is part of the byte-exact string.
+        const cl = {
+            Kind: "prose",
+            ContentHash: "def456",
+            Similarity: 1.0,
+            Exact: true,
+            Informational: true,
+            Locations: [
+                { FilePath: "docs/a.md", Heading: "Note", StartLine: 3, EndLine: 8 },
+                { FilePath: "docs/b.md", Heading: "Note", StartLine: 3, EndLine: 8 },
+                { FilePath: "docs/c.md", Heading: "Note", StartLine: 3, EndLine: 8 },
+                { FilePath: "docs/d.md", Heading: "Note", StartLine: 3, EndLine: 8 },
+                { FilePath: "docs/e.md", Heading: "Note", StartLine: 3, EndLine: 8 },
+                { FilePath: "docs/f.md", Heading: "Note", StartLine: 3, EndLine: 8 },
+            ],
+        };
+        const out = Render({ HighGroups: [], MaybePairs: [], PartialOverlaps: [cl] }, cfg);
+        expect(out).toContain("likely intentional");
+        expect(out).toContain("6 files");
+        expect(out).toContain("consider a shared snippet");
+        // Pin the exact informational line including the em dash.
+        expect(out).toContain("  appears in 6 files — likely intentional; consider a shared snippet\n");
+    });
+    it("treats an empty PartialOverlaps slice as byte-identical to none", () => {
+        // WHY: the section header is gated on length > 0; an explicit empty slice
+        // must not emit a spurious "Partial overlaps" header. The Go test compared a
+        // base report (no field set) against one with an explicit []; both empty
+        // here, so the output must be identical.
+        const base = makeReportWithGroupsAndPairs(1, 1);
+        const withEmpty = {
+            HighGroups: base.HighGroups,
+            MaybePairs: base.MaybePairs,
+            PartialOverlaps: [],
+        };
+        expect(Render(withEmpty, cfg)).toBe(Render(base, cfg));
+    });
+});

package/dist/dedup/report_types.js

@@ -0,0 +1,8 @@
+// Top-level result/report types for the dedup facade.
+//
+// Ported from internal/dedup/report_types.go. The Go file re-declared these as
+// type aliases (`type Report = deduptypes.Report`) to break the facade ↔
+// analyzer import cycle; the leaf deduptypes package owns the real definitions.
+// In TS the same shapes are re-exported from ../deduptypes so callers (cmd, the
+// dedup/report subpackage) can import them from the package root.
+export {};

package/dist/dedup/sectionid/index.js

@@ -0,0 +1 @@
+export { derive } from "./sectionid.js";