shadowjoin 0.0.0-stage → 0.3.0

package/dist/normalize.js

@@ -0,0 +1,102 @@
+const strip = (re) => (v) => v.replace(re, " ");
+/**
+ * Applied to every candidate key before any optional rule. These are the
+ * transforms that are safe on essentially any text: they never merge values
+ * that a human would read as different entities.
+ */
+export const BASE_RULES = [
+    { id: "casefold", label: "lowercase", apply: (v) => v.toLowerCase(), sql: (e) => `lower(${e})` },
+    {
+        id: "deaccent",
+        label: "unicode NFKD + strip diacritics",
+        apply: (v) => v.normalize("NFKD").replace(/\p{M}+/gu, ""),
+        sql: (e) => `unaccent(${e})`,
+    },
+    { id: "trim", label: "trim and collapse whitespace", apply: (v) => v.replace(/\s+/g, " ").trim(), sql: (e) => `btrim(regexp_replace(${e}, '\\s+', ' ', 'g'))` },
+];
+/**
+ * Each of these is measured INDEPENDENTLY on top of BASE_RULES, so the number
+ * next to a rule is what that rule alone buys you — not an artifact of the
+ * order rules happen to run in.
+ */
+export const OPTIONAL_RULES = [
+    {
+        id: "punctuation",
+        label: "strip punctuation",
+        apply: strip(/[^\p{L}\p{N}\s]+/gu),
+        sql: (e) => `regexp_replace(${e}, '[^[:alnum:][:space:]]+', ' ', 'g')`,
+    },
+    {
+        id: "ampersand",
+        label: "& -> and",
+        apply: (v) => v.replace(/&/g, " and "),
+        sql: (e) => `replace(${e}, '&', ' and ')`,
+    },
+    {
+        id: "leading-zeros",
+        label: "strip leading zeros from numeric tokens",
+        apply: (v) => v.replace(/\b0+(\d)/g, "$1"),
+        sql: (e) => `regexp_replace(${e}, '\\m0+(\\d)', '\\1', 'g')`,
+    },
+    {
+        id: "article",
+        label: "strip a leading article",
+        apply: (v) => v.replace(/^\s*(the|a|an)\s+/i, " "),
+        sql: (e) => `regexp_replace(${e}, '^\\s*(the|a|an)\\s+', ' ', 'i')`,
+    },
+    {
+        id: "corp-suffix",
+        label: "strip corporate suffixes (inc, corp, ltd, plc, gmbh ...)",
+        apply: strip(/\b(incorporated|inc|corporation|corp|company|co|limited|ltd|llc|llp|lp|plc|holdings?|group|gmbh|ag|sa|nv|bv|oyj|ab|as|pte|pty)\b\.?/gi),
+        sql: (e) => `regexp_replace(${e}, '\\m(incorporated|inc|corporation|corp|company|co|limited|ltd|llc|llp|lp|plc|holdings?|group|gmbh|ag|sa|nv|bv|oyj|ab|as|pte|pty)\\M\\.?', ' ', 'gi')`,
+    },
+    {
+        id: "security-boilerplate",
+        label: "strip security/listing boilerplate (common stock, ADS, class A ...)",
+        apply: strip(/\b(common stock|common shares?|ordinary shares?|american depositary (shares?|receipts?)|depositary shares?|class [a-z]\b|series [a-z]\b|when issued|new)\b/gi),
+        sql: (e) => `regexp_replace(${e}, '\\m(common stock|common shares?|ordinary shares?|american depositary (shares?|receipts?)|depositary shares?|class [a-z]\\M|series [a-z]\\M|when issued|new)\\M', ' ', 'gi')`,
+    },
+    {
+        id: "sort-tokens",
+        label: "sort tokens (order-insensitive match)",
+        apply: (v) => v.split(/\s+/).filter(Boolean).sort().join(" "),
+        sql: (e) => `(SELECT string_agg(t, ' ' ORDER BY t) FROM unnest(string_to_array(${e}, ' ')) AS t WHERE t <> '')`,
+    },
+    {
+        id: "despace",
+        label: "remove all whitespace",
+        apply: (v) => v.replace(/\s+/g, ""),
+        sql: (e) => `regexp_replace(${e}, '\\s+', '', 'g')`,
+    },
+];
+export const ALL_RULE_IDS = OPTIONAL_RULES.map((r) => r.id);
+export function rulesByIds(ids) {
+    const index = new Map(OPTIONAL_RULES.map((r) => [r.id, r]));
+    return ids.map((id) => {
+        const rule = index.get(id);
+        if (!rule) {
+            throw new Error(`Unknown rule "${id}". Known rules: ${ALL_RULE_IDS.join(", ")}`);
+        }
+        return rule;
+    });
+}
+/** Apply BASE_RULES, then the supplied rules, in order. */
+export function normalize(value, rules = []) {
+    let out = value;
+    for (const rule of BASE_RULES)
+        out = rule.apply(out);
+    for (const rule of rules)
+        out = rule.apply(out);
+    // Rules insert spaces where they remove things; tidy up so "3m  company" and
+    // "3m company" do not end up as different keys.
+    return out.replace(/\s+/g, " ").trim();
+}
+/** Compose the enabled rules into one Postgres expression over a column. */
+export function toSql(column, rules = []) {
+    let expr = column;
+    for (const rule of BASE_RULES)
+        expr = rule.sql(expr);
+    for (const rule of rules)
+        expr = rule.sql(expr);
+    return expr;
+}

package/dist/scan.d.ts

@@ -0,0 +1,25 @@
+import type { Report, Row } from "./types.js";
+export interface ScanOptions {
+    /** Rule ids to enable. Defaults to every rule. */
+    rules?: string[];
+    /** How many example recoveries to include for human review. Default 20. */
+    maxSamplePairs?: number;
+    /** Replace key values in samples with a short hash. Counts are unaffected. */
+    redactSamples?: boolean;
+    /** Look for trigram neighbours among rows no rule explains. Default true. */
+    nearMisses?: boolean;
+    /** Minimum Dice score for a near miss. Default 0.45. */
+    nearMissThreshold?: number;
+    /** Cap on near misses reported. Default 25. */
+    maxNearMisses?: number;
+    /** Called as each phase begins, so a CLI can show progress. */
+    onPhase?: (label: string) => void;
+}
+/**
+ * Compare an exact join against a shadow matcher and report what the exact
+ * join is losing.
+ *
+ * The figure this produces is a FLOOR. The shadow matcher has unknown recall of
+ * its own, so the true loss is at least this large and may be larger.
+ */
+export declare function scan(left: Row[], right: Row[], options?: ScanOptions): Report;

package/dist/scan.js

@@ -0,0 +1,260 @@
+import { ALL_RULE_IDS, normalize, rulesByIds } from "./normalize.js";
+import { TrigramIndex } from "./similarity.js";
+/** Tickers, SKUs and ids differ cosmetically across sources; compare them loosely. */
+function canonicalTruth(value) {
+    return value.replace(/[^\p{L}\p{N}]+/gu, "").toUpperCase();
+}
+function redact(value) {
+    let h = 2166136261;
+    for (let i = 0; i < value.length; i++) {
+        h ^= value.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return `#${(h >>> 0).toString(16).padStart(8, "0")}`;
+}
+function buildIndex(rows, rules) {
+    const index = new Map();
+    for (const row of rows) {
+        const key = rules === null ? row.key : normalize(row.key, rules);
+        if (!key)
+            continue;
+        const bucket = index.get(key);
+        if (bucket)
+            bucket.push(row);
+        else
+            index.set(key, [row]);
+    }
+    return index;
+}
+function verify(left, candidates) {
+    if (left.truth === undefined)
+        return "unverifiable";
+    const known = candidates.filter((c) => c.truth !== undefined);
+    if (known.length === 0)
+        return "unverifiable";
+    const target = canonicalTruth(left.truth);
+    const agreeing = known.filter((c) => canonicalTruth(c.truth) === target);
+    if (agreeing.length === 0)
+        return "contradicted";
+    if (agreeing.length === known.length)
+        return "verified";
+    return "ambiguous";
+}
+/**
+ * Compare an exact join against a shadow matcher and report what the exact
+ * join is losing.
+ *
+ * The figure this produces is a FLOOR. The shadow matcher has unknown recall of
+ * its own, so the true loss is at least this large and may be larger.
+ */
+export function scan(left, right, options = {}) {
+    const ruleIds = options.rules ?? ALL_RULE_IDS;
+    const rules = rulesByIds(ruleIds);
+    const maxSamples = options.maxSamplePairs ?? 20;
+    const warnings = [];
+    if (left.length === 0 || right.length === 0) {
+        warnings.push("One side of the join is empty; there is nothing to measure.");
+    }
+    const phase = options.onPhase ?? (() => { });
+    // 1. The baseline: the join exactly as it runs today.
+    phase("measuring the join as it runs today");
+    const exactIndex = buildIndex(right, null);
+    const missed = [];
+    let exactMatches = 0;
+    for (const row of left) {
+        if (exactIndex.has(row.key))
+            exactMatches++;
+        else
+            missed.push(row);
+    }
+    // 2. Each rule measured independently against that baseline, so the number
+    //    beside a rule is what the rule alone buys and not a product of ordering.
+    phase(`testing ${rules.length} rules against that baseline`);
+    const attribution = new Map();
+    const byRule = rules.map((rule) => {
+        const index = buildIndex(right, [rule]);
+        let recovered = 0, verified = 0, contradicted = 0, ambiguous = 0;
+        for (const row of missed) {
+            const candidates = index.get(normalize(row.key, [rule]));
+            if (!candidates || candidates.length === 0)
+                continue;
+            recovered++;
+            const verdict = verify(row, candidates);
+            if (verdict === "verified")
+                verified++;
+            else if (verdict === "contradicted")
+                contradicted++;
+            else if (verdict === "ambiguous")
+                ambiguous++;
+            if (!attribution.has(row.id))
+                attribution.set(row.id, { rule: rule.id, candidates });
+        }
+        return { rule: rule.id, label: rule.label, recovered, verified, contradicted, ambiguous };
+    });
+    // 3. Greedy forward selection: which rules, in which order, actually pay.
+    //    Most recoveries need a combination, so per-rule figures alone are not
+    //    enough to act on.
+    phase("selecting the rules worth adopting");
+    const stack = [];
+    const covered = new Set();
+    const chosen = [];
+    let pool = [...rules];
+    while (pool.length > 0) {
+        let best = null;
+        let bestGain = 0;
+        let bestMatched = null;
+        for (const candidate of pool) {
+            const trial = [...chosen, candidate];
+            const index = buildIndex(right, trial);
+            const matched = new Set();
+            for (const row of missed) {
+                if (index.has(normalize(row.key, trial)))
+                    matched.add(row.id);
+            }
+            let gain = 0;
+            for (const id of matched)
+                if (!covered.has(id))
+                    gain++;
+            if (gain > bestGain) {
+                bestGain = gain;
+                best = candidate;
+                bestMatched = matched;
+            }
+        }
+        if (best === null || bestGain === 0)
+            break;
+        chosen.push(best);
+        for (const id of bestMatched)
+            covered.add(id);
+        stack.push({ rule: best.id, label: best.label, marginal: bestGain, cumulative: covered.size });
+        pool = pool.filter((r) => r !== best);
+    }
+    // 4. Attribute what only a COMBINATION explains. The greedy stack is tried
+    //    first, because applying every rule can recover fewer rows than the best
+    //    subset does — over-normalization merges keys that should stay apart.
+    const greedyIndex = buildIndex(right, chosen);
+    for (const row of missed) {
+        if (attribution.has(row.id))
+            continue;
+        const candidates = greedyIndex.get(normalize(row.key, chosen));
+        if (candidates && candidates.length > 0) {
+            attribution.set(row.id, { rule: "combined", candidates });
+        }
+    }
+    const fullIndex = buildIndex(right, rules);
+    let fullStackRecovered = 0;
+    for (const row of missed) {
+        const candidates = fullIndex.get(normalize(row.key, rules));
+        if (candidates && candidates.length > 0) {
+            fullStackRecovered++;
+            if (!attribution.has(row.id))
+                attribution.set(row.id, { rule: "combined", candidates });
+        }
+    }
+    // 5. Tally and collect examples.
+    let verified = 0, contradicted = 0, ambiguous = 0, unverifiable = 0;
+    const samplePairs = [];
+    const missedById = new Map(missed.map((r) => [r.id, r]));
+    for (const [leftId, { rule, candidates }] of attribution) {
+        const row = missedById.get(leftId);
+        const verdict = verify(row, candidates);
+        if (verdict === "verified")
+            verified++;
+        else if (verdict === "contradicted")
+            contradicted++;
+        else if (verdict === "ambiguous")
+            ambiguous++;
+        else
+            unverifiable++;
+        if (samplePairs.length < maxSamples) {
+            const best = candidates[0];
+            samplePairs.push({
+                rule,
+                leftId: row.id,
+                leftKey: options.redactSamples ? redact(row.key) : row.key,
+                rightId: best.id,
+                rightKey: options.redactSamples ? redact(best.key) : best.key,
+                candidates: candidates.length,
+                verification: verdict,
+            });
+        }
+    }
+    const recovered = attribution.size;
+    const unexplained = missed.length - recovered;
+    // 6. The residue. No normalization rule explains these, so look for the
+    //    closest trigram neighbour instead. Reported as advice, never counted:
+    //    a suggestion that has not cleared the rule bar must not move the floor.
+    const nearMisses = [];
+    let noCandidate = 0;
+    if (options.nearMisses !== false && unexplained > 0) {
+        phase(`analysing the ${unexplained} rows no rule explains`);
+        const index = new TrigramIndex(right);
+        const maxNear = options.maxNearMisses ?? 25;
+        for (const row of missed) {
+            if (attribution.has(row.id))
+                continue;
+            const hit = index.best(row.key, { threshold: options.nearMissThreshold ?? 0.45 });
+            if (!hit) {
+                noCandidate++;
+                continue;
+            }
+            if (nearMisses.length < maxNear) {
+                nearMisses.push({
+                    leftId: row.id,
+                    leftKey: options.redactSamples ? redact(row.key) : row.key,
+                    rightId: hit.row.id,
+                    rightKey: options.redactSamples ? redact(hit.row.key) : hit.row.key,
+                    similarity: hit.similarity,
+                    verification: verify(row, [hit.row]),
+                });
+            }
+        }
+    }
+    const pct = (n) => (left.length === 0 ? 0 : Number(((n / left.length) * 100).toFixed(2)));
+    if (rules.length > 1) {
+        warnings.push("Per-rule counts are measured independently against the exact baseline, so they overlap and will not sum to the total.");
+    }
+    if (chosen.length > 0 && chosen.length < rules.length && fullStackRecovered < covered.size) {
+        warnings.push(`Applying every rule recovers ${covered.size - fullStackRecovered} fewer match(es) than the best subset. Over-normalization is costing you matches — rerun with --rules ${chosen.map((r) => r.id).join(",")}`);
+    }
+    if (nearMisses.length > 0) {
+        warnings.push(`${nearMisses.length} unexplained row(s) have a close trigram neighbour. These are suggestions, NOT counted in the floor — confirm them before adding an alias.`);
+    }
+    if (noCandidate > 0) {
+        warnings.push(`${noCandidate} unexplained row(s) have no string similarity to anything on the right (e.g. "Vatican City" vs "Holy See"). No normalization rule will ever recover those; they need an alias table.`);
+    }
+    if (contradicted > 0) {
+        warnings.push(`${contradicted} recovered match(es) are contradicted by ground truth — the shadow matcher is over-merging. Review samplePairs before acting.`);
+    }
+    if (ambiguous > 0) {
+        warnings.push(`${ambiguous} recovered match(es) collapsed onto a key shared by several right-hand rows (e.g. share classes or product variants). These need a tie-breaker, not a normalization rule.`);
+    }
+    if (unverifiable > 0 && verified + contradicted === 0) {
+        warnings.push("No ground truth was supplied, so recoveries are unverified candidates. Supply a `truth` field on both sides to turn this figure into a verified floor.");
+    }
+    return {
+        generatedAt: new Date().toISOString(),
+        leftRows: left.length,
+        rightRows: right.length,
+        exactMatches,
+        exactMatchRate: pct(exactMatches),
+        recovered,
+        unexplained,
+        reachableMatchRate: pct(exactMatches + recovered),
+        lowerBoundLossPct: pct(recovered),
+        byRule: byRule.sort((a, b) => b.recovered - a.recovered),
+        stack,
+        verified,
+        contradicted,
+        ambiguous,
+        unverifiable,
+        precision: verified + contradicted === 0
+            ? null
+            : Number(((verified / (verified + contradicted)) * 100).toFixed(2)),
+        samplePairs,
+        nearMisses,
+        noCandidate,
+        warnings,
+        rulesApplied: ruleIds,
+    };
+}

package/dist/similarity.d.ts

@@ -0,0 +1,34 @@
+import type { Row } from "./types.js";
+/**
+ * Trigram similarity, for the rows no normalization rule explains.
+ *
+ * Implemented in-process rather than delegating to Postgres `pg_trgm`, so the
+ * same residue analysis runs on CSVs, on JSON and on databases that have no
+ * such extension.
+ */
+/** Postgres-style padding so short strings and word starts are weighted sensibly. */
+export declare function trigrams(value: string): Set<string>;
+/** Sørensen–Dice: 2|A∩B| / (|A|+|B|). 1 is identical, 0 shares nothing. */
+export declare function dice(a: Set<string>, b: Set<string>): number;
+export interface NearMissOptions {
+    /** Minimum Dice score to report. Default 0.45. */
+    threshold?: number;
+    /** Cap on candidates scored per unexplained row. Default 200. */
+    maxCandidates?: number;
+}
+export interface NearMissHit {
+    row: Row;
+    similarity: number;
+}
+/**
+ * An inverted trigram index over the right-hand side. Built once, queried per
+ * unexplained row, so cost grows with the residue rather than with every pair.
+ */
+export declare class TrigramIndex {
+    private readonly rows;
+    private readonly postings;
+    private readonly grams;
+    constructor(rows: Row[]);
+    /** Best scoring right-hand row for `key`, or null if nothing clears the bar. */
+    best(key: string, options?: NearMissOptions): NearMissHit | null;
+}

package/dist/similarity.js

@@ -0,0 +1,81 @@
+/**
+ * Trigram similarity, for the rows no normalization rule explains.
+ *
+ * Implemented in-process rather than delegating to Postgres `pg_trgm`, so the
+ * same residue analysis runs on CSVs, on JSON and on databases that have no
+ * such extension.
+ */
+/** Postgres-style padding so short strings and word starts are weighted sensibly. */
+export function trigrams(value) {
+    const padded = `  ${value.trim().toLowerCase()} `;
+    const out = new Set();
+    for (let i = 0; i + 3 <= padded.length; i++)
+        out.add(padded.slice(i, i + 3));
+    return out;
+}
+/** Sørensen–Dice: 2|A∩B| / (|A|+|B|). 1 is identical, 0 shares nothing. */
+export function dice(a, b) {
+    if (a.size === 0 || b.size === 0)
+        return 0;
+    let shared = 0;
+    const [small, large] = a.size <= b.size ? [a, b] : [b, a];
+    for (const g of small)
+        if (large.has(g))
+            shared++;
+    return (2 * shared) / (a.size + b.size);
+}
+/**
+ * An inverted trigram index over the right-hand side. Built once, queried per
+ * unexplained row, so cost grows with the residue rather than with every pair.
+ */
+export class TrigramIndex {
+    rows;
+    postings = new Map();
+    grams = [];
+    constructor(rows) {
+        this.rows = rows;
+        rows.forEach((row, i) => {
+            const g = trigrams(row.key);
+            this.grams.push(g);
+            for (const gram of g) {
+                const bucket = this.postings.get(gram);
+                if (bucket)
+                    bucket.push(i);
+                else
+                    this.postings.set(gram, [i]);
+            }
+        });
+    }
+    /** Best scoring right-hand row for `key`, or null if nothing clears the bar. */
+    best(key, options = {}) {
+        const threshold = options.threshold ?? 0.45;
+        const maxCandidates = options.maxCandidates ?? 200;
+        const query = trigrams(key);
+        // Skipping near-universal trigrams keeps large indexes fast, but on a small
+        // right-hand side every bucket looks universal and the filter would discard
+        // everything. Only apply it once there are enough rows for it to mean something.
+        const universal = this.rows.length >= 20 ? this.rows.length / 2 : Infinity;
+        const overlap = new Map();
+        for (const gram of query) {
+            const bucket = this.postings.get(gram);
+            if (!bucket || bucket.length > universal)
+                continue;
+            for (const i of bucket)
+                overlap.set(i, (overlap.get(i) ?? 0) + 1);
+        }
+        if (overlap.size === 0)
+            return null;
+        // Score the most promising candidates only; shared-gram count bounds Dice.
+        const ranked = [...overlap.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, maxCandidates);
+        let best = null;
+        for (const [i] of ranked) {
+            const score = dice(query, this.grams[i]);
+            if (score >= threshold && (best === null || score > best.similarity)) {
+                best = { row: this.rows[i], similarity: Number(score.toFixed(3)) };
+            }
+        }
+        return best;
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,107 @@
+/** A single record on one side of the join. */
+export interface Row {
+    /** Stable identifier for this row (primary key, line number — anything unique). */
+    id: string;
+    /** The value actually used as the join key today. */
+    key: string;
+    /**
+     * Optional ground truth. When both sides carry it, every recovered match is
+     * verified rather than asserted, and the report gains a precision figure.
+     * In the bundled example this is the ticker symbol.
+     */
+    truth?: string;
+}
+/** A reversible-in-spirit string transform used to build a looser blocking key. */
+export interface Rule {
+    id: string;
+    label: string;
+    apply(value: string): string;
+    /** The same transform as a Postgres expression, so it can be pasted into a pipeline. */
+    sql(expr: string): string;
+}
+export type Verification = "verified" | "contradicted" | "ambiguous" | "unverifiable";
+export interface RuleContribution {
+    rule: string;
+    label: string;
+    /** Rows recovered by BASE + this rule alone, measured against the exact-match baseline. */
+    recovered: number;
+    verified: number;
+    contradicted: number;
+    ambiguous: number;
+}
+/** One step of the greedy stack: the rule, and what adding it actually bought. */
+export interface StackStep {
+    rule: string;
+    label: string;
+    /** Rows recovered by adding this rule that the preceding ones did not already cover. */
+    marginal: number;
+    /** Total rows recovered by this rule plus everything before it. */
+    cumulative: number;
+}
+export interface SamplePair {
+    /** Which rule (or "combined") first explained this recovery. */
+    rule: string;
+    leftId: string;
+    leftKey: string;
+    rightId: string;
+    rightKey: string;
+    /** Number of right-hand rows that collapsed onto the same normalized key. */
+    candidates: number;
+    verification: Verification;
+}
+/**
+ * A row no rule explains, paired with its closest trigram neighbour.
+ *
+ * Deliberately NOT counted in `recovered` or `lowerBoundLossPct`: these are
+ * unverified suggestions below the confidence bar, and letting them inflate the
+ * headline would turn a defensible floor into a guess.
+ */
+export interface NearMiss {
+    leftId: string;
+    leftKey: string;
+    rightId: string;
+    rightKey: string;
+    /** Sørensen-Dice over character trigrams. 1 is identical. */
+    similarity: number;
+    verification: Verification;
+}
+export interface Report {
+    generatedAt: string;
+    leftRows: number;
+    rightRows: number;
+    /** Rows matched by the join exactly as it runs today. */
+    exactMatches: number;
+    exactMatchRate: number;
+    /** Rows the shadow matcher recovered on top of the exact baseline. */
+    recovered: number;
+    /** Recovered rows with no candidate under any enabled rule. */
+    unexplained: number;
+    /** exactMatches + recovered, over leftRows. */
+    reachableMatchRate: number;
+    /**
+     * Lower bound on the share of left rows whose match the exact join is losing.
+     * A FLOOR, not an estimate: the shadow matcher's own recall is unknown, so the
+     * true loss can only be larger.
+     */
+    lowerBoundLossPct: number;
+    byRule: RuleContribution[];
+    /**
+     * Rules in the order worth adopting, chosen greedily by marginal recovery.
+     * This is the actionable half of the report: most recoveries need a
+     * combination, so the individual figures in `byRule` under-state them.
+     */
+    stack: StackStep[];
+    verified: number;
+    contradicted: number;
+    ambiguous: number;
+    unverifiable: number;
+    /** verified / (verified + contradicted), or null when no ground truth was supplied. */
+    precision: number | null;
+    samplePairs: SamplePair[];
+    /** Closest trigram neighbours for rows no rule explains. Advisory, not counted. */
+    nearMisses: NearMiss[];
+    /** Unexplained rows with no trigram neighbour at all — these need an alias table. */
+    noCandidate: number;
+    warnings: string[];
+    rulesApplied: string[];
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/ui.d.ts

@@ -0,0 +1,19 @@
+export declare const isTty: () => boolean;
+export declare function banner(version: string): string;
+export declare function footer(version: string): string;
+/** A spinner that degrades to nothing when it isn't being watched by a human. */
+export declare class Progress {
+    private timer;
+    private frame;
+    private label;
+    private readonly started;
+    private readonly done;
+    start(label: string): void;
+    /** Mark the current step finished and begin the next one. */
+    step(label: string): void;
+    stop(): void;
+    /** Clear the spinner without claiming the step succeeded. */
+    abort(): void;
+    private clear;
+    private paint;
+}