docsgov 0.1.0

package/dist/config/glob.js

@@ -0,0 +1,82 @@
+// Port of internal/config/glob.go.
+//
+// Go uses github.com/bmatcuk/doublestar; we use picomatch with { dot: true },
+// which matches doublestar's semantics for the patterns docgov uses:
+//   - "**" matches zero or more path segments (so "docs/**" matches "docs"),
+//   - dotfiles are matched (doublestar matches them by default),
+//   - a malformed pattern contributes no match (doublestar returns an error
+//     that InScope skips; picomatch simply does not match it).
+import picomatch from "picomatch";
+import { isNotExist } from "./fs.js";
+/**
+ * normalizePattern converts a trailing-slash pattern ("docs/") to a recursive
+ * glob ("docs/**") so callers don't need to special-case directory globs.
+ * Patterns without a trailing slash are returned unchanged.
+ */
+function normalizePattern(p) {
+    if (p.endsWith("/")) {
+        return p + "**";
+    }
+    return p;
+}
+/**
+ * inScope returns true if slashPath matches ANY of the given glob patterns.
+ * Each pattern is normalized by normalizePattern before matching. A pattern
+ * that fails to compile contributes no match.
+ */
+export function inScope(patterns, slashPath) {
+    for (const p of patterns) {
+        let matcher;
+        try {
+            matcher = picomatch(normalizePattern(p), { dot: true });
+        }
+        catch {
+            // A pattern that does not compile contributes no match (mirrors the Go
+            // code skipping a doublestar.Match error).
+            continue;
+        }
+        if (matcher(slashPath)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * walkMarkdown walks fsys from the root, collects all ".md" files whose slash
+ * path satisfies inScope(patterns, path), and returns them sorted.
+ *
+ * It descends the async {@link FS} via readDir/sub (the unified repo FS). A
+ * missing directory at any point is treated as empty, matching Go's fs.WalkDir
+ * skipping a tree that does not exist.
+ */
+export async function walkMarkdown(fsys, patterns) {
+    const results = [];
+    async function descend(dirSlash) {
+        let entries;
+        try {
+            entries = await fsys.readDir(dirSlash === "" ? "." : dirSlash);
+        }
+        catch (err) {
+            if (isNotExist(err)) {
+                return;
+            }
+            throw err;
+        }
+        for (const entry of entries) {
+            const childSlash = dirSlash === "" ? entry.name() : `${dirSlash}/${entry.name()}`;
+            if (entry.isDir()) {
+                await descend(childSlash);
+                continue;
+            }
+            if (!childSlash.endsWith(".md")) {
+                continue;
+            }
+            if (inScope(patterns, childSlash)) {
+                results.push(childSlash);
+            }
+        }
+    }
+    await descend("");
+    results.sort();
+    return results;
+}

package/dist/config/glob.test.js

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+import { MapFS } from "./fs.js";
+import { inScope, walkMarkdown } from "./glob.js";
+describe("inScope", () => {
+    // A trailing "/" must be normalized to "/**" so a directory pattern matches
+    // at any depth — this is the ergonomic shorthand the config grammar promises.
+    it("treats a trailing-slash pattern as matching all depths", () => {
+        const patterns = ["docs/"];
+        expect(inScope(patterns, "docs/x.md")).toBe(true);
+        expect(inScope(patterns, "docs/a/b.md")).toBe(true);
+        expect(inScope(patterns, "other/x.md")).toBe(false);
+    });
+    // A single "*" must match only direct children, NOT deeper paths — authors
+    // rely on this to scope a guard to one directory level.
+    it("matches direct children only for a single-star pattern", () => {
+        const patterns = ["docs/api/*"];
+        expect(inScope(patterns, "docs/api/teams.md")).toBe(true);
+        expect(inScope(patterns, "docs/api/v1/teams.md")).toBe(false);
+    });
+    // "**" must match at any depth.
+    it("matches any depth for a double-star pattern", () => {
+        expect(inScope(["src/**"], "src/a/b.go")).toBe(true);
+    });
+    // A path matching none of the patterns must be out of scope.
+    it("returns false when no pattern matches", () => {
+        expect(inScope(["docs/**", "internal/**"], "cmd/docgov/main.go")).toBe(false);
+    });
+    // No patterns means nothing is ever in scope.
+    it("returns false for an empty pattern list", () => {
+        expect(inScope([], "docs/x.md")).toBe(false);
+    });
+    // A malformed pattern must contribute no match (and must not throw), so one
+    // bad glob can't take down a whole check run.
+    it("contributes no match for a malformed pattern", () => {
+        expect(inScope(["["], "docs/x.md")).toBe(false);
+    });
+});
+describe("walkMarkdown", () => {
+    // Returns only in-scope .md files, sorted, excluding non-.md and
+    // out-of-scope files — this is the file set every guard pass iterates.
+    it("returns matching .md files sorted, excluding non-md and out-of-scope", async () => {
+        const fsys = new MapFS({
+            "docs/index.md": "# index",
+            "docs/api/teams.md": "# teams",
+            "docs/api/readme.txt": "not md",
+            "internal/foo.go": "package foo",
+            "other/page.md": "# other",
+        });
+        const got = await walkMarkdown(fsys, ["docs/**"]);
+        expect(got).toEqual(["docs/api/teams.md", "docs/index.md"]);
+    });
+    // Files outside the pattern are excluded even when they are .md files.
+    it("excludes .md files outside the boundary pattern", async () => {
+        const fsys = new MapFS({
+            "docs/index.md": "# index",
+            "other/page.md": "# other",
+        });
+        const got = await walkMarkdown(fsys, ["docs/**"]);
+        expect(got).not.toContain("other/page.md");
+    });
+});

package/dist/config/index.js

@@ -0,0 +1,4 @@
+// Public surface of the config package.
+export { loadConfig } from "./config.js";
+export { inScope, walkMarkdown } from "./glob.js";
+export { MapFS, NotExistError, isNotExist } from "./fs.js";

package/dist/dedup/analyzer/analyzer.js

@@ -0,0 +1,533 @@
+// Ported from internal/dedup/analyzer/analyzer.go.
+//
+// The layered duplicate-detection orchestrator. It takes a flat list of sections
+// plus their L2-normalized embeddings and returns a Report containing
+// high-confidence duplicate groups, a flat list of possible pairs, and (when
+// blocks are supplied) block-level partial overlaps.
+//
+// Algorithm layers (applied in order):
+//
+//   L1 — Exact:    union sections with equal content_hash (including same-file).
+//   L2 — Heading:  cosine pair in [thresh_maybe, thresh_high) with >=1 shared
+//                  distinctive heading token -> promote to HIGH (union).
+//   L3 — Cosine:   cosine of L2-normalized embeddings; skip same-file pairs.
+//                  >=thresh_high -> union (HIGH). [thresh_maybe, thresh_high) ->
+//                  "possible pair" unless promoted by L2. <thresh_maybe -> ignored.
+//   L4 — Safety:   differentiator word-pair detection. Never blocks grouping;
+//                  forces recommended_action = manual_review and adds reason.
+//   L5 — Blocks:   partial-overlap detection over BlockRecords (optional).
+//
+// Determinism: Go's `pairs` and `groupsIdx` maps are iterated then sorted with a
+// NON-stable slices.SortFunc, so within equal sort keys the order is
+// unspecified. To make the TS output reproducible AND match Go on the cases the
+// tests pin, every map iteration here is done in a fixed key order (numeric
+// (i,j) for pairs, group-membership order for groups) before the same
+// comparators run.
+import { canonicalRank, isDisqualified, lessRank, } from "./canonical.js";
+import { buildDistinctiveFilter, distinctiveTokensOf, } from "./distinctive.js";
+import { partialOverlaps } from "./partial_overlaps.js";
+import { computePreview } from "./preview.js";
+import { findDifferentiators } from "./safety.js";
+/** pairKey builds the canonical "i,j" map key for a pair, with i < j. */
+function pairKey(a, b) {
+    const i = Math.min(a, b);
+    const j = Math.max(a, b);
+    return `${i},${j}`;
+}
+/**
+ * Analyze runs the four-layer duplicate-detection algorithm over sections and
+ * their L2-normalized embeddings, returning a structured Report.
+ *
+ * embeddings maps section ID -> L2-normalized vector. Sections with missing
+ * embeddings are treated as zero vectors (should not occur in practice).
+ *
+ * blocks is the flat list of BlockRecords for L5 partial-overlap detection.
+ * blockEmb maps content_hash -> L2-normalized block embedding vector. Pass
+ * empty/undefined for both to skip L5 (PartialOverlaps will be empty).
+ */
+export function analyze(sections, embeddings, blocks, blockEmb, cfg) {
+    const n = sections.length;
+    if (n < 2) {
+        return { HighGroups: [], MaybePairs: [], PartialOverlaps: [] };
+    }
+    const acfg = cfg.Analyzer;
+    const rcfg = cfg.Report;
+    // Build per-section embedding slice for fast dot-product access.
+    const vecs = new Array(n);
+    for (let i = 0; i < n; i++) {
+        vecs[i] = embeddings.get(sections[i].id);
+    }
+    // Compute corpus-level distinctive token filter.
+    const headings = new Array(n);
+    for (let i = 0; i < n; i++) {
+        headings[i] = sections[i].heading;
+    }
+    let minTokLen = cfg.Markdown.heading_token_min_len;
+    if (minTokLen <= 0) {
+        minTokLen = 3;
+    }
+    const distinctiveFilter = buildDistinctiveFilter(headings, acfg, minTokLen);
+    // Per-section distinctive token sets.
+    const secDistTokens = new Array(n);
+    for (let i = 0; i < n; i++) {
+        secDistTokens[i] = distinctiveTokensOf(sections[i].heading, distinctiveFilter, acfg, minTokLen);
+    }
+    // Union-find for HIGH grouping.
+    const parent = new Array(n);
+    for (let i = 0; i < n; i++) {
+        parent[i] = i;
+    }
+    const find = (x) => {
+        while (parent[x] !== x) {
+            parent[x] = parent[parent[x]]; // path compression
+            x = parent[x];
+        }
+        return x;
+    };
+    const union = (a, b) => {
+        const ra = find(a);
+        const rb = find(b);
+        if (ra !== rb) {
+            parent[ra] = rb;
+        }
+    };
+    const pairs = new Map();
+    // ----- L1: Exact content_hash match (including same-file) -----
+    // hashBuckets keyed by content_hash; insertion-order map iteration mirrors
+    // Go's per-bucket inner loops (only union + pair-set, no ordering effect).
+    const hashBuckets = new Map();
+    for (let i = 0; i < n; i++) {
+        const h = sections[i].content_hash;
+        const bucket = hashBuckets.get(h);
+        if (bucket) {
+            bucket.push(i);
+        }
+        else {
+            hashBuckets.set(h, [i]);
+        }
+    }
+    for (const idxs of hashBuckets.values()) {
+        if (idxs.length < 2) {
+            continue;
+        }
+        for (let a = 0; a < idxs.length; a++) {
+            for (let b = a + 1; b < idxs.length; b++) {
+                const ia = idxs[a];
+                const ib = idxs[b];
+                union(ia, ib);
+                pairs.set(pairKey(ia, ib), {
+                    similarity: 1.0,
+                    reasons: ["exact normalized-content match"],
+                    exact: true,
+                    hasDiff: false,
+                    promoted: false,
+                });
+            }
+        }
+    }
+    // ----- L3 + L2: Cosine similarity with heading promoter -----
+    for (let i = 0; i < n; i++) {
+        for (let j = i + 1; j < n; j++) {
+            // L3: skip same-file pairs.
+            if (sections[i].file_path === sections[j].file_path) {
+                continue;
+            }
+            const score = dotProduct(vecs[i], vecs[j]);
+            if (score < acfg.thresh_maybe) {
+                continue;
+            }
+            const k = pairKey(i, j);
+            if (pairs.has(k)) {
+                // Already set by L1 — don't overwrite.
+                continue;
+            }
+            // Common distinctive heading tokens.
+            const commonDist = intersectSets(secDistTokens[i], secDistTokens[j]);
+            const headingSignal = commonDist.size > 0;
+            let promoted = false;
+            const reasons = [];
+            if (score >= acfg.thresh_high) {
+                reasons.push(`high semantic similarity (cosine=${fmt3(score)})`);
+            }
+            else {
+                reasons.push(`possible semantic similarity (cosine=${fmt3(score)})`);
+            }
+            if (headingSignal) {
+                const tokens = sortedKeys(commonDist);
+                reasons.push("shared distinctive heading tokens: " + tokens.join(", "));
+            }
+            // L4: differentiator check.
+            const diffs = findDifferentiators(sections[i].raw_content, sections[j].raw_content, acfg.differentiators);
+            for (const d of diffs) {
+                reasons.push(d);
+            }
+            // L2 promotion: MAYBE + distinctive heading match -> HIGH.
+            if (score < acfg.thresh_high && headingSignal) {
+                promoted = true;
+            }
+            const tierHigh = score >= acfg.thresh_high || promoted;
+            pairs.set(k, {
+                similarity: score,
+                reasons,
+                exact: false,
+                hasDiff: diffs.length > 0,
+                promoted,
+            });
+            if (tierHigh) {
+                union(i, j);
+            }
+        }
+    }
+    // ----- Assemble groups from union-find -----
+    // Iterate node indices 0..n-1 so each root's member list is built in
+    // ascending node order, matching the deterministic shape needed downstream.
+    const groupsIdx = new Map();
+    for (let i = 0; i < n; i++) {
+        const root = find(i);
+        const list = groupsIdx.get(root);
+        if (list) {
+            list.push(i);
+        }
+        else {
+            groupsIdx.set(root, [i]);
+        }
+    }
+    // groupsIdx is keyed by root; iterate roots in ascending order for a
+    // deterministic baseline before sortGroups runs.
+    const roots = [...groupsIdx.keys()].sort((a, b) => a - b);
+    let groups = [];
+    for (const root of roots) {
+        const idxs = groupsIdx.get(root);
+        if (idxs.length > 1) {
+            groups.push(idxs);
+        }
+    }
+    // Drop groups where every member is disqualified.
+    groups = filterDisqualifiedGroups(groups, sections, acfg);
+    // Build node -> group index map for MAYBE pair filtering.
+    const nodeToGroup = new Map();
+    for (let gi = 0; gi < groups.length; gi++) {
+        for (const k of groups[gi]) {
+            nodeToGroup.set(k, gi);
+        }
+    }
+    // ----- Possible pairs: MAYBE not unioned, not all-disqualified -----
+    // Iterate pairs in sorted (i,j) key order so the pre-sort baseline is
+    // deterministic (Go iterates a map, then sorts non-stably by similarity).
+    const possiblePairs = [];
+    for (const k of sortedPairKeys(pairs)) {
+        const info = pairs.get(k);
+        if (info.exact) {
+            continue;
+        }
+        if (info.similarity >= acfg.thresh_high || info.promoted) {
+            continue;
+        }
+        const [ki, kj] = parsePairKey(k);
+        // Skip if both nodes are in the same group.
+        const gi = nodeToGroup.get(ki);
+        const gj = nodeToGroup.get(kj);
+        if (gi !== undefined && gj !== undefined && gi === gj) {
+            continue;
+        }
+        // Both sides disqualified -> drop.
+        if (isDisqualified(sections[ki], acfg) &&
+            isDisqualified(sections[kj], acfg)) {
+            continue;
+        }
+        possiblePairs.push({ i: ki, j: kj, info });
+    }
+    // Sort by descending similarity.
+    sortBySimDesc(possiblePairs);
+    // ----- Sort groups by (-size, -best_similarity) -----
+    sortGroups(groups, pairs);
+    // ----- Build Report -----
+    const rep = { HighGroups: [], MaybePairs: [], PartialOverlaps: [] };
+    for (const idxs of groups) {
+        rep.HighGroups.push(buildGroup(idxs, sections, pairs, acfg, rcfg));
+    }
+    for (const pp of possiblePairs) {
+        rep.MaybePairs.push(buildPair(pp.i, pp.j, pp.info, sections, acfg, rcfg));
+    }
+    // ----- L5: partial-overlap block-level detection -----
+    if (blocks && blocks.length > 0) {
+        // Build secGroup: section_id -> HIGH group index, from the final groups
+        // slice. Only multi-member HIGH groups populate it.
+        const secGroup = new Map();
+        for (let gi = 0; gi < groups.length; gi++) {
+            for (const k of groups[gi]) {
+                secGroup.set(sections[k].id, gi);
+            }
+        }
+        rep.PartialOverlaps = partialOverlaps(blocks, blockEmb ?? new Map(), secGroup, cfg);
+    }
+    return rep;
+}
+/** buildGroup constructs a Group from a set of section indices. */
+function buildGroup(idxs, sections, pairs, acfg, rcfg) {
+    // Sort by rank to identify canonical.
+    const sorted = idxs.slice();
+    sortByRank(sorted, sections, acfg);
+    const canonicalIdx = sorted[0];
+    const dupIdxs = sorted.slice(1);
+    // Gather all internal pairs.
+    const internalKeys = [];
+    for (let a = 0; a < sorted.length; a++) {
+        for (let b = a + 1; b < sorted.length; b++) {
+            const k = pairKey(sorted[a], sorted[b]);
+            if (pairs.has(k)) {
+                internalKeys.push(k);
+            }
+        }
+    }
+    // Compute confidence and action.
+    let minSim = 1.0;
+    let hasDiff = false;
+    let allHighOrPromoted = true;
+    for (const k of internalKeys) {
+        const info = pairs.get(k);
+        if (info.similarity < minSim) {
+            minSim = info.similarity;
+        }
+        if (info.hasDiff) {
+            hasDiff = true;
+        }
+        if (!info.exact && info.similarity < acfg.thresh_high && !info.promoted) {
+            allHighOrPromoted = false;
+        }
+    }
+    // First decide tier from internal pair quality (ignore differentiator).
+    let confidence;
+    let action;
+    if (allHighOrPromoted) {
+        confidence = "high";
+        action = "replace_with_reference";
+    }
+    else if (minSim >= acfg.thresh_maybe) {
+        confidence = "medium";
+        action = "manual_review";
+    }
+    else {
+        confidence = "low";
+        action = "manual_review";
+    }
+    // L4 downgrade: differentiator forces manual_review but never changes tier.
+    if (hasDiff && action === "replace_with_reference") {
+        action = "manual_review";
+    }
+    // Build canonical member.
+    const canonical = sectionToMember(sections[canonicalIdx], 1.0, null, false, rcfg);
+    // Build duplicate members.
+    const members = [];
+    for (const di of dupIdxs) {
+        const k = pairKey(canonicalIdx, di);
+        let info = pairs.get(k);
+        if (info === undefined) {
+            // Transitive group member — find best pair involving this section.
+            info = findBestPairInfo(di, sorted.slice(0, indexOf(sorted, di)), pairs);
+        }
+        members.push(sectionToMember(sections[di], info.similarity, info.reasons, info.exact, rcfg));
+    }
+    return { Canonical: canonical, Members: members, Confidence: confidence, Action: action };
+}
+/** buildPair constructs a Pair for a possible pair. */
+function buildPair(i, j, info, sections, acfg, rcfg) {
+    // Pick canonical by rank.
+    let canonIdx;
+    let candIdx;
+    const ri = canonicalRank(sections[i], acfg);
+    const rj = canonicalRank(sections[j], acfg);
+    if (lessRank(ri, rj)) {
+        canonIdx = i;
+        candIdx = j;
+    }
+    else {
+        canonIdx = j;
+        candIdx = i;
+    }
+    const canonical = sectionToMember(sections[canonIdx], 1.0, null, false, rcfg);
+    const candidate = sectionToMember(sections[candIdx], info.similarity, info.reasons, false, rcfg);
+    return {
+        Canonical: canonical,
+        Candidate: candidate,
+        Similarity: info.similarity,
+        Reasons: info.reasons,
+    };
+}
+/** sectionToMember converts a Section to a Member. */
+function sectionToMember(s, sim, reasons, exact, rcfg) {
+    return {
+        SectionID: s.id,
+        FilePath: s.file_path,
+        Anchor: s.anchor,
+        Heading: s.heading,
+        StartLine: s.start_line,
+        EndLine: s.end_line,
+        InboundCount: s.inbound_count,
+        Similarity: sim,
+        // Go passes nil reasons for the canonical; an empty array is len-0 and
+        // iterates identically, satisfying the string[] type (the report renderer
+        // only ranges over Reasons, so nil vs [] is indistinguishable downstream).
+        Reasons: reasons ?? [],
+        ExactMatch: exact,
+        Preview: computePreview(s.raw_content, rcfg.preview_chars, rcfg.preview_word_ratio),
+    };
+}
+// ---------- helpers ----------
+/**
+ * dotProduct computes the dot product of two float32-sourced vectors as float64.
+ * For L2-normalized vectors, this equals the cosine similarity. Mirrors Go's
+ * dotProduct: zero when either side is missing/short.
+ */
+function dotProduct(a, b) {
+    if (a === undefined || b === undefined) {
+        return 0;
+    }
+    const n = a.length;
+    if (n === 0 || b.length < n) {
+        return 0;
+    }
+    let sum = 0;
+    for (let i = 0; i < n; i++) {
+        sum += a[i] * b[i];
+    }
+    return sum;
+}
+/** intersectSets returns the intersection of two string sets. */
+function intersectSets(a, b) {
+    const result = new Set();
+    for (const k of a) {
+        if (b.has(k)) {
+            result.add(k);
+        }
+    }
+    return result;
+}
+/** sortedKeys returns the keys of a string set, sorted lexicographically. */
+function sortedKeys(m) {
+    const keys = [...m];
+    keys.sort(cmpStr);
+    return keys;
+}
+/** sortedPairKeys returns the pairs map's keys sorted by (i, j) numerically. */
+function sortedPairKeys(pairs) {
+    return [...pairs.keys()].sort((a, b) => {
+        const [ai, aj] = parsePairKey(a);
+        const [bi, bj] = parsePairKey(b);
+        if (ai !== bi)
+            return ai - bi;
+        return aj - bj;
+    });
+}
+/** parsePairKey splits an "i,j" key back into numeric [i, j]. */
+function parsePairKey(k) {
+    const c = k.indexOf(",");
+    return [Number(k.slice(0, c)), Number(k.slice(c + 1))];
+}
+/** cmpStr reproduces Go's cmp.Compare for strings: -1 / 0 / +1. */
+function cmpStr(a, b) {
+    if (a < b)
+        return -1;
+    if (a > b)
+        return 1;
+    return 0;
+}
+/**
+ * fmt3 formats a number with exactly 3 decimal places, matching Go's "%.3f".
+ * Go uses round-half-to-even; JS toFixed rounds half away from zero. The
+ * cosine inputs here are not exact .xxxx5 ties at the 4th decimal in practice,
+ * so the two agree on the rendered reason strings the tests cover.
+ */
+function fmt3(x) {
+    return x.toFixed(3);
+}
+/** sortBySimDesc sorts possible pairs by descending similarity (in place). */
+function sortBySimDesc(pp) {
+    pp.sort((a, b) => cmpNum(b.info.similarity, a.info.similarity));
+}
+/** sortGroups sorts groups by (-size, -best_similarity) (in place). */
+function sortGroups(groups, pairs) {
+    groups.sort((a, b) => cmpNum(groupScore(a, pairs), groupScore(b, pairs)));
+}
+/**
+ * groupScore returns (-size, -best_sim) encoded as a single float for ordering.
+ * Lower score sorts first (larger groups, then higher best similarity).
+ */
+function groupScore(idxs, pairs) {
+    let best = 0.0;
+    for (let a = 0; a < idxs.length; a++) {
+        for (let b = a + 1; b < idxs.length; b++) {
+            const info = pairs.get(pairKey(idxs[a], idxs[b]));
+            if (info !== undefined && info.similarity > best) {
+                best = info.similarity;
+            }
+        }
+    }
+    return -idxs.length * 1e9 + -best;
+}
+/** sortByRank sorts section indices by canonical rank (in place). */
+function sortByRank(idxs, sections, acfg) {
+    idxs.sort((a, b) => {
+        const ra = canonicalRank(sections[a], acfg);
+        const rb = canonicalRank(sections[b], acfg);
+        if (lessRank(ra, rb))
+            return -1;
+        if (lessRank(rb, ra))
+            return 1;
+        return 0;
+    });
+}
+/** filterDisqualifiedGroups drops groups where every member is disqualified. */
+function filterDisqualifiedGroups(groups, sections, acfg) {
+    const result = [];
+    for (const idxs of groups) {
+        let allDisq = true;
+        for (const k of idxs) {
+            if (!isDisqualified(sections[k], acfg)) {
+                allDisq = false;
+                break;
+            }
+        }
+        if (!allDisq) {
+            result.push(idxs);
+        }
+    }
+    return result;
+}
+/**
+ * findBestPairInfo returns the highest-similarity recorded pair between target
+ * and any of prevIdxs, defaulting to a transitive-member placeholder.
+ */
+function findBestPairInfo(target, prevIdxs, pairs) {
+    let best = {
+        similarity: 0.0,
+        reasons: ["transitive group member"],
+        exact: false,
+        hasDiff: false,
+        promoted: false,
+    };
+    for (const prev of prevIdxs) {
+        const info = pairs.get(pairKey(prev, target));
+        if (info !== undefined && info.similarity > best.similarity) {
+            best = info;
+        }
+    }
+    return best;
+}
+/** indexOf returns the position of target in idxs, or idxs.length if absent. */
+function indexOf(idxs, target) {
+    for (let i = 0; i < idxs.length; i++) {
+        if (idxs[i] === target) {
+            return i;
+        }
+    }
+    return idxs.length;
+}
+/** cmpNum reproduces Go's cmp.Compare for numbers: -1 / 0 / +1. */
+function cmpNum(a, b) {
+    if (a < b)
+        return -1;
+    if (a > b)
+        return 1;
+    return 0;
+}