goldenmatch 0.1.0

package/src/node/tui/index.ts

@@ -0,0 +1,6 @@
+/**
+ * index.ts -- TUI module entry point.
+ */
+
+export { startTui } from "./app.js";
+export type { TuiOptions } from "./app.js";

package/src/node/tui/widgets.ts

@@ -0,0 +1,128 @@
+/**
+ * widgets.ts -- Optional ink ecosystem addon loaders.
+ *
+ * Each addon (ink-table, ink-select-input, ink-text-input, ink-spinner,
+ * ink-gradient) is an optional peer dependency. We provide a uniform
+ * mechanism to try-load them so callers can render rich UI when installed
+ * and fall back to plain `ink.Text` / `ink.Box` output otherwise.
+ *
+ * Two loading styles are provided:
+ *   - `tryLoad<T>(name)`: synchronous `require`-based load. Works for CJS
+ *     packages (ink-select-input, ink-text-input, ink-spinner, ink-gradient
+ *     in older versions).
+ *   - `loadAddons()`: async dynamic `import()` load. Works for ESM-only
+ *     packages (ink-table v3+).
+ *
+ * Both return `null` for a missing package rather than throwing, so the
+ * caller can branch on presence.
+ */
+
+import { createRequire } from "node:module";
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+const require = createRequire(import.meta.url);
+
+/**
+ * Synchronously try to require a package. Returns `null` if the package is
+ * not installed (or fails to load for any reason).
+ */
+export function tryLoad<T = any>(name: string): T | null {
+  try {
+    return require(name) as T;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Lazy-getter bag of synchronously-loaded ink addons. Each access retries
+ * the require in case the environment changed, but most callers will prefer
+ * `loadAddons()` (async) since ink-table is ESM-only.
+ */
+export const inkAddons = {
+  get table(): any {
+    return tryLoad("ink-table");
+  },
+  get selectInput(): any {
+    return tryLoad("ink-select-input");
+  },
+  get textInput(): any {
+    return tryLoad("ink-text-input");
+  },
+  get spinner(): any {
+    return tryLoad("ink-spinner");
+  },
+  get gradient(): any {
+    return tryLoad("ink-gradient");
+  },
+};
+
+/**
+ * Collected addon components, each either the default export of its package
+ * or `null` if the package isn't installed.
+ */
+export interface LoadedAddons {
+  Table: any | null;
+  SelectInput: any | null;
+  TextInput: any | null;
+  Spinner: any | null;
+  Gradient: any | null;
+}
+
+/**
+ * Asynchronously load all optional ink addons via dynamic `import()`.
+ *
+ * Uses `import()` rather than `require()` because ink-table v3+ ships as
+ * ESM-only and cannot be loaded from CJS. The other addons work either
+ * way; we standardise on import for consistency.
+ *
+ * Any addon that fails to load (missing package, import error, etc.) is
+ * silently set to `null`. Callers should branch on each field.
+ */
+export async function loadAddons(): Promise<LoadedAddons> {
+  const addons: LoadedAddons = {
+    Table: null,
+    SelectInput: null,
+    TextInput: null,
+    Spinner: null,
+    Gradient: null,
+  };
+
+  // Wrap each import in its own try so a single missing addon doesn't
+  // poison the others.
+  try {
+    const mod: any = await import("ink-table" as string);
+    addons.Table = mod.default ?? mod;
+  } catch {
+    /* optional */
+  }
+  try {
+    const mod: any = await import("ink-select-input" as string);
+    addons.SelectInput = mod.default ?? mod;
+  } catch {
+    /* optional */
+  }
+  try {
+    const mod: any = await import("ink-text-input" as string);
+    addons.TextInput = mod.default ?? mod;
+  } catch {
+    /* optional */
+  }
+  try {
+    const mod: any = await import("ink-spinner" as string);
+    addons.Spinner = mod.default ?? mod;
+  } catch {
+    /* optional */
+  }
+  try {
+    const mod: any = await import("ink-gradient" as string);
+    addons.Gradient = mod.default ?? mod;
+  } catch {
+    /* optional */
+  }
+
+  return addons;
+}
+
+/* eslint-enable @typescript-eslint/no-explicit-any */

package/tests/parity/scorer-ground-truth.test.ts

@@ -0,0 +1,118 @@
+/**
+ * Python parity ground-truth for every scorer.
+ *
+ * Each row: (scorer, input_a, input_b, python_score).
+ * Tolerance: 1e-4 (four decimal places) — tight enough to catch a real
+ * bug but loose enough to survive last-digit floating-point drift.
+ *
+ * The canonical Jaro-Winkler reference values (MARTHA/MARHTA = 0.9611,
+ * DIXON/DICKSONX = 0.8133, etc.) come from Winkler's original paper and
+ * are reproduced by rapidfuzz, jellyfish, and every other mainstream
+ * implementation. Other values (token_sort, levenshtein) are computed
+ * from their well-defined formulas:
+ *   - Levenshtein similarity: 1 - dist / max(|a|, |b|)
+ *   - Indel similarity (rapidfuzz token_sort base): 1 - d_indel / (|a| + |b|)
+ *   - Soundex match: 1.0 iff soundex codes match
+ *
+ * To regenerate / extend: run the equivalent Python via
+ *   from rapidfuzz.fuzz import token_sort_ratio
+ *   from rapidfuzz.distance import JaroWinkler, Levenshtein, Indel
+ * and paste the results below.
+ */
+import { describe, it, expect } from "vitest";
+import {
+  scoreField,
+  jaro,
+  diceCoefficient,
+  jaccardSimilarity,
+} from "../../src/core/index.js";
+
+type Case = readonly [scorer: string, a: string, b: string, expected: number];
+
+const CASES: readonly Case[] = [
+  // Jaro-Winkler — canonical reference values from Winkler's paper
+  ["jaro_winkler", "MARTHA", "MARHTA", 0.9611],
+  ["jaro_winkler", "DIXON", "DICKSONX", 0.8133],
+  ["jaro_winkler", "JELLYFISH", "SMELLYFISH", 0.8963],
+  ["jaro_winkler", "DWAYNE", "DUANE", 0.84],
+  ["jaro_winkler", "abc", "abc", 1.0],
+  ["jaro_winkler", "", "", 1.0],
+  ["jaro_winkler", "abc", "", 0.0],
+  // John/Jon: jaro = (3/4 + 3/3 + 1)/3 = 11/12 = 0.9167; prefix=3, jw = 0.9167 + 3*0.1*(1-0.9167) = 0.9333
+  ["jaro_winkler", "John", "Jon", 0.9333],
+
+  // Levenshtein similarity (1 - dist/max_len)
+  ["levenshtein", "kitten", "sitting", 0.5714], // 1 - 3/7
+  ["levenshtein", "saturday", "sunday", 0.625], // 1 - 3/8
+  ["levenshtein", "abc", "abc", 1.0],
+  ["levenshtein", "", "", 1.0],
+  ["levenshtein", "abc", "xyz", 0.0],
+
+  // token_sort via rapidfuzz Indel ratio, with lowercase + strip-nonalnum preprocessing
+  ["token_sort", "New York Mets", "Mets New York", 1.0],
+  // "john smith" (10) vs "johnson smith" (13): indel dist = 3 (insert 's','o','n')
+  // similarity = 1 - 3/23 = 20/23 ≈ 0.8696
+  ["token_sort", "John Smith", "Smith Johnson", 0.8696],
+  ["token_sort", "the quick brown fox", "fox quick the brown", 1.0],
+  ["token_sort", "a b c", "c b a", 1.0],
+  ["token_sort", "John, Smith!", "smith john.", 1.0], // strips punctuation
+  ["token_sort", "John SMITH", "smith john", 1.0], // lowercases
+
+  // Exact
+  ["exact", "abc", "abc", 1.0],
+  ["exact", "abc", "xyz", 0.0],
+
+  // Soundex
+  ["soundex_match", "Robert", "Rupert", 1.0], // both R163
+  ["soundex_match", "Robert", "Smith", 0.0],
+  ["soundex_match", "Smith", "Smyth", 1.0], // both S530
+];
+
+describe("scorer Python parity (4-decimal tolerance)", () => {
+  for (const [scorer, a, b, expected] of CASES) {
+    it(`${scorer}(${JSON.stringify(a)}, ${JSON.stringify(b)}) ≈ ${expected}`, () => {
+      const actual = scoreField(a, b, scorer);
+      expect(actual).not.toBeNull();
+      expect(actual as number).toBeCloseTo(expected, 4);
+    });
+  }
+});
+
+describe("jaro parity (not exposed via scoreField)", () => {
+  it("jaro(MARTHA, MARHTA) ≈ 0.9444", () => {
+    expect(jaro("MARTHA", "MARHTA")).toBeCloseTo(0.9444, 4);
+  });
+});
+
+// Bloom-filter scorers — dice / jaccard. Not Python-sourced since Python's
+// implementation is trivial (bitwise ops on CLK bitvectors); we lock behavior
+// on hand-computed edge cases.
+describe("bloom-filter similarity sanity", () => {
+  it("identical bloom filters score 1.0 (dice)", () => {
+    const hex = "ff00ff00";
+    expect(diceCoefficient(hex, hex)).toBe(1.0);
+  });
+
+  it("identical bloom filters score 1.0 (jaccard)", () => {
+    const hex = "ff00ff00";
+    expect(jaccardSimilarity(hex, hex)).toBe(1.0);
+  });
+
+  it("non-overlapping bloom filters score 0.0 (dice)", () => {
+    expect(diceCoefficient("ff00", "00ff")).toBe(0.0);
+  });
+
+  it("non-overlapping bloom filters score 0.0 (jaccard)", () => {
+    expect(jaccardSimilarity("ff00", "00ff")).toBe(0.0);
+  });
+
+  it("half-overlap: ff00 vs ffff -> dice = 2*8/(8+16) = 0.6667", () => {
+    // ff00 has 8 bits set; ffff has 16 bits; intersection = 8
+    // dice = 2*8 / (8+16) = 16/24 = 0.6667
+    expect(diceCoefficient("ff00", "ffff")).toBeCloseTo(0.6667, 4);
+  });
+
+  it("half-overlap: ff00 vs ffff -> jaccard = 8/16 = 0.5", () => {
+    expect(jaccardSimilarity("ff00", "ffff")).toBeCloseTo(0.5, 4);
+  });
+});

package/tests/smoke.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from "vitest";
+import {
+  dedupe,
+  scoreField,
+  scorePair,
+  applyTransform,
+  applyTransforms,
+  buildClusters,
+  UnionFind,
+  scoreStrings,
+} from "../src/core/index.js";
+
+describe("smoke", () => {
+  it("imports work", () => {
+    expect(typeof dedupe).toBe("function");
+    expect(typeof scoreField).toBe("function");
+    expect(typeof scorePair).toBe("function");
+    expect(typeof applyTransform).toBe("function");
+    expect(typeof applyTransforms).toBe("function");
+    expect(typeof buildClusters).toBe("function");
+    expect(typeof UnionFind).toBe("function");
+    expect(typeof scoreStrings).toBe("function");
+  });
+
+  it("basic dedupe works end-to-end", () => {
+    const rows = [
+      { id: 1, name: "John Smith", email: "john@example.com", zip: "12345" },
+      { id: 2, name: "Jon Smith", email: "jon@example.com", zip: "12345" },
+      { id: 3, name: "Jane Doe", email: "jane@example.com", zip: "54321" },
+    ];
+    const result = dedupe(rows, {
+      fuzzy: { name: 0.7 },
+      blocking: ["zip"],
+      threshold: 0.7,
+    });
+    expect(result.stats.totalRecords).toBe(3);
+  });
+
+  it("scoreStrings returns a number between 0 and 1", () => {
+    const s = scoreStrings("hello", "hello");
+    expect(s).toBe(1.0);
+    const s2 = scoreStrings("hello", "world");
+    expect(s2).toBeGreaterThanOrEqual(0);
+    expect(s2).toBeLessThanOrEqual(1);
+  });
+});

package/tests/unit/a2a-server.test.ts

@@ -0,0 +1,175 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import type { Server } from "node:http";
+import { startA2aServer, AGENT_CARD } from "../../src/node/a2a/server.js";
+
+let server: Server;
+let baseUrl: string;
+
+beforeAll(async () => {
+  server = startA2aServer({ port: 0, host: "127.0.0.1" });
+  await new Promise<void>((resolveFn) => {
+    if (server.listening) {
+      resolveFn();
+      return;
+    }
+    server.once("listening", () => resolveFn());
+  });
+  const addr = server.address();
+  const port =
+    typeof addr === "object" && addr !== null && "port" in addr ? addr.port : 8200;
+  baseUrl = `http://127.0.0.1:${port}`;
+});
+
+afterAll(async () => {
+  if (server) {
+    await new Promise<void>((resolveFn, rejectFn) => {
+      server.close((err) => (err ? rejectFn(err) : resolveFn()));
+    });
+  }
+});
+
+describe("A2A agent card (exported constant)", () => {
+  it("has name, description, version, provider, skills", () => {
+    expect(typeof AGENT_CARD.name).toBe("string");
+    expect(typeof AGENT_CARD.description).toBe("string");
+    expect(typeof AGENT_CARD.version).toBe("string");
+    expect(AGENT_CARD.provider).toBeDefined();
+    expect(typeof AGENT_CARD.provider.organization).toBe("string");
+    expect(Array.isArray(AGENT_CARD.skills)).toBe(true);
+  });
+
+  it("has at least 5 skills", () => {
+    expect(AGENT_CARD.skills.length).toBeGreaterThanOrEqual(5);
+  });
+
+  it("every skill has name, description, inputModes, outputModes", () => {
+    for (const skill of AGENT_CARD.skills) {
+      expect(typeof skill.name).toBe("string");
+      expect(skill.name.length).toBeGreaterThan(0);
+      expect(typeof skill.description).toBe("string");
+      expect(Array.isArray(skill.inputModes)).toBe(true);
+      expect(skill.inputModes.length).toBeGreaterThan(0);
+      expect(Array.isArray(skill.outputModes)).toBe(true);
+      expect(skill.outputModes.length).toBeGreaterThan(0);
+    }
+  });
+});
+
+describe("A2A server HTTP endpoints", () => {
+  it("GET /.well-known/agent.json returns the AgentCard", async () => {
+    const res = await fetch(baseUrl + "/.well-known/agent.json");
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      name: string;
+      description: string;
+      version: string;
+      provider: { organization: string };
+      skills: Array<{
+        name: string;
+        description: string;
+        inputModes: string[];
+        outputModes: string[];
+      }>;
+    };
+    expect(body.name).toBe("goldenmatch-js");
+    expect(typeof body.description).toBe("string");
+    expect(typeof body.version).toBe("string");
+    expect(body.provider.organization).toBe("goldenmatch");
+    expect(body.skills.length).toBeGreaterThanOrEqual(5);
+    for (const skill of body.skills) {
+      expect(typeof skill.name).toBe("string");
+      expect(typeof skill.description).toBe("string");
+      expect(Array.isArray(skill.inputModes)).toBe(true);
+      expect(Array.isArray(skill.outputModes)).toBe(true);
+    }
+  });
+
+  it("POST /tasks with skill=dedupe completes and returns result", async () => {
+    const res = await fetch(baseUrl + "/tasks", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        skill: "dedupe",
+        input: {
+          rows: [
+            { email: "a@x.com", name: "Alice" },
+            { email: "a@x.com", name: "A." },
+            { email: "b@x.com", name: "Bob" },
+          ],
+          exact: ["email"],
+        },
+      }),
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      id: string;
+      status: string;
+      skill: string;
+      result?: unknown;
+    };
+    expect(typeof body.id).toBe("string");
+    expect(body.id.length).toBeGreaterThan(0);
+    expect(body.skill).toBe("dedupe");
+    expect(["completed", "running", "pending"]).toContain(body.status);
+    if (body.status === "completed") {
+      expect(body.result).toBeDefined();
+    }
+  });
+
+  it("GET /tasks/{id} returns task status after creation", async () => {
+    const postRes = await fetch(baseUrl + "/tasks", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        skill: "score",
+        input: { a: "John", b: "Jon", scorer: "jaro_winkler" },
+      }),
+    });
+    const postBody = (await postRes.json()) as { id: string };
+    expect(typeof postBody.id).toBe("string");
+
+    const getRes = await fetch(baseUrl + "/tasks/" + postBody.id);
+    expect(getRes.status).toBe(200);
+    const getBody = (await getRes.json()) as { id: string; status: string; skill: string };
+    expect(getBody.id).toBe(postBody.id);
+    expect(getBody.skill).toBe("score");
+    expect(["completed", "running", "pending", "failed"]).toContain(getBody.status);
+  });
+
+  it("GET /tasks/nonexistent returns 404", async () => {
+    const res = await fetch(baseUrl + "/tasks/does-not-exist-xyz");
+    expect(res.status).toBe(404);
+    const body = (await res.json()) as { error: string };
+    expect(typeof body.error).toBe("string");
+  });
+
+  it("POST /tasks with unknown skill returns failed task (or error)", async () => {
+    const res = await fetch(baseUrl + "/tasks", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ skill: "not_a_real_skill", input: {} }),
+    });
+    // Implementation returns 200 with status=failed. Some implementations use 400.
+    expect([200, 400]).toContain(res.status);
+    const body = (await res.json()) as {
+      status?: string;
+      error?: string;
+    };
+    // Either body.error is set or body.status === "failed".
+    const hasFailure =
+      (typeof body.error === "string" && body.error.length > 0) ||
+      body.status === "failed";
+    expect(hasFailure).toBe(true);
+  });
+
+  it("POST /tasks without skill returns 400", async () => {
+    const res = await fetch(baseUrl + "/tasks", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ input: {} }),
+    });
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: string };
+    expect(typeof body.error).toBe("string");
+  });
+});

package/tests/unit/ann-blocker.test.ts

@@ -0,0 +1,117 @@
+import { describe, it, expect } from "vitest";
+import {
+  ANNBlocker,
+  cosineSim,
+  euclideanDist,
+} from "../../src/core/index.js";
+
+function vec(...nums: number[]): Float32Array {
+  return new Float32Array(nums);
+}
+
+describe("cosineSim", () => {
+  it("orthogonal vectors -> 0", () => {
+    expect(cosineSim(vec(1, 0, 0), vec(0, 1, 0))).toBe(0);
+  });
+
+  it("identical vectors -> 1", () => {
+    expect(cosineSim(vec(1, 0, 0), vec(1, 0, 0))).toBeCloseTo(1, 6);
+  });
+
+  it("opposite vectors -> -1", () => {
+    expect(cosineSim(vec(1, 0, 0), vec(-1, 0, 0))).toBeCloseTo(-1, 6);
+  });
+
+  it("zero vector -> 0 (no NaN)", () => {
+    expect(cosineSim(vec(0, 0, 0), vec(1, 2, 3))).toBe(0);
+  });
+});
+
+describe("euclideanDist", () => {
+  it("3-4-5 Pythagorean triple", () => {
+    expect(euclideanDist(vec(0, 0), vec(3, 4))).toBeCloseTo(5, 6);
+  });
+
+  it("identical -> 0", () => {
+    expect(euclideanDist(vec(1, 2, 3), vec(1, 2, 3))).toBe(0);
+  });
+
+  it("5-12-13 triple", () => {
+    expect(euclideanDist(vec(0, 0), vec(5, 12))).toBeCloseTo(13, 6);
+  });
+});
+
+describe("ANNBlocker", () => {
+  it("buildIndex then query returns top-K", () => {
+    const blocker = new ANNBlocker({ topK: 2 });
+    const embeddings = [
+      vec(1, 0, 0),
+      vec(0.99, 0.01, 0), // close to 0
+      vec(0, 1, 0),
+      vec(0, 0.98, 0.02), // close to 2
+    ];
+    blocker.buildIndex(embeddings);
+    const pairs = blocker.query(embeddings);
+    // Should pair (0,1) and (2,3) at minimum
+    const pairKeys = new Set(pairs.map((p) => `${p[0]}-${p[1]}`));
+    expect(pairKeys.has("0-1")).toBe(true);
+    expect(pairKeys.has("2-3")).toBe(true);
+  });
+
+  it("indexSize reflects buildIndex", () => {
+    const blocker = new ANNBlocker();
+    expect(blocker.indexSize).toBe(0);
+    blocker.buildIndex([vec(1, 0), vec(0, 1)]);
+    expect(blocker.indexSize).toBe(2);
+  });
+
+  it("addToIndex grows index and returns position", () => {
+    const blocker = new ANNBlocker();
+    blocker.buildIndex([vec(1, 0)]);
+    expect(blocker.indexSize).toBe(1);
+    const pos = blocker.addToIndex(vec(0, 1));
+    expect(pos).toBe(1);
+    expect(blocker.indexSize).toBe(2);
+  });
+
+  it("queryWithScores returns [a, b, score] tuples", () => {
+    const blocker = new ANNBlocker({ topK: 2 });
+    const embeddings = [vec(1, 0), vec(0.99, 0.01), vec(0, 1)];
+    blocker.buildIndex(embeddings);
+    // Use the same array reference to enable self-pair filtering.
+    const scored = blocker.queryWithScores(
+      embeddings as unknown as readonly Float32Array[],
+    );
+    expect(scored.length).toBeGreaterThan(0);
+    for (const [a, b, score] of scored) {
+      expect(typeof a).toBe("number");
+      expect(typeof b).toBe("number");
+      expect(typeof score).toBe("number");
+      // Pairs are canonicalized, so a <= b. Self-pairs are excluded when
+      // the same array reference is used as both index and queries.
+      expect(a).toBeLessThanOrEqual(b);
+    }
+  });
+
+  it("queryOne returns top-K neighbors with scores", () => {
+    const blocker = new ANNBlocker({ topK: 2 });
+    blocker.buildIndex([vec(1, 0), vec(0, 1), vec(0.9, 0.1)]);
+    const top = blocker.queryOne(vec(1, 0));
+    expect(top.length).toBe(2);
+    // Best match should be index 0 (cosine=1)
+    expect(top[0]![0]).toBe(0);
+  });
+
+  it("query on empty index -> empty", () => {
+    const blocker = new ANNBlocker();
+    blocker.buildIndex([]);
+    expect(blocker.query([vec(1, 0)])).toEqual([]);
+  });
+
+  it("euclidean metric still ranks closest first", () => {
+    const blocker = new ANNBlocker({ topK: 1, metric: "euclidean" });
+    blocker.buildIndex([vec(0, 0), vec(10, 10), vec(0.1, 0.1)]);
+    const top = blocker.queryOne(vec(0, 0));
+    expect(top[0]![0]).toBe(0); // self is closest
+  });
+});