goldenmatch 0.1.0

package/tests/unit/salesforce-connector.test.ts

@@ -0,0 +1,148 @@
+import {
+  describe,
+  it,
+  expect,
+  vi,
+  beforeEach,
+  afterEach,
+} from "vitest";
+import { createSalesforceConnector } from "../../src/node/connectors/salesforce.js";
+
+let fetchMock: ReturnType<typeof vi.fn>;
+
+beforeEach(() => {
+  fetchMock = vi.fn();
+  vi.stubGlobal("fetch", fetchMock);
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+function jsonResponse(body: unknown): Response {
+  return {
+    ok: true,
+    status: 200,
+    text: async () => "",
+    json: async () => body,
+  } as Response;
+}
+
+describe("createSalesforceConnector", () => {
+  it("returns connector with name 'salesforce'", () => {
+    const c = createSalesforceConnector({
+      instanceUrl: "https://example.my.salesforce.com",
+      accessToken: "token",
+    });
+    expect(c.name).toBe("salesforce");
+    expect(typeof c.connect).toBe("function");
+    expect(typeof c.read).toBe("function");
+    expect(typeof c.close).toBe("function");
+  });
+
+  it("read() before connect() throws 'Not connected'", async () => {
+    const c = createSalesforceConnector({
+      instanceUrl: "https://example.my.salesforce.com",
+      // no accessToken
+    });
+    await expect(c.read({ table: "Account" })).rejects.toThrow(/not connected/i);
+  });
+
+  it("connect() does OAuth password grant", async () => {
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        access_token: "TOKEN_123",
+        instance_url: "https://x.my.salesforce.com",
+      }),
+    );
+    const c = createSalesforceConnector({
+      instanceUrl: "https://example.my.salesforce.com",
+      clientId: "cid",
+      clientSecret: "secret",
+      username: "u",
+      password: "p",
+      securityToken: "tok",
+    });
+    await c.connect();
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const url = fetchMock.mock.calls[0]![0] as string;
+    expect(url).toContain("/services/oauth2/token");
+    const init = fetchMock.mock.calls[0]![1] as RequestInit;
+    expect(init.method).toBe("POST");
+    // Body should contain combined password+token
+    expect(String(init.body)).toContain("password=ptok");
+  });
+
+  it("connect() with pre-issued accessToken is no-op (no fetch)", async () => {
+    const c = createSalesforceConnector({
+      instanceUrl: "https://example.my.salesforce.com",
+      accessToken: "preissued",
+    });
+    await c.connect();
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("read() with object query builds SOQL and fetches paginated results", async () => {
+    // First page returns nextRecordsUrl; second page returns final.
+    fetchMock
+      .mockResolvedValueOnce(
+        jsonResponse({
+          records: [{ Id: "001A", Name: "Acme" }],
+          done: false,
+          nextRecordsUrl: "/services/data/v61.0/query/01g0000NEXT",
+        }),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse({
+          records: [{ Id: "001B", Name: "Beta" }],
+          done: true,
+        }),
+      );
+
+    const c = createSalesforceConnector({
+      instanceUrl: "https://example.my.salesforce.com",
+      accessToken: "TOKEN",
+    });
+    const rows = await c.read({ table: "Account", columns: ["Id", "Name"], limit: 10 });
+    expect(rows.length).toBe(2);
+    expect(rows[0]!.Id).toBe("001A");
+    expect(rows[1]!.Id).toBe("001B");
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+
+    const firstUrl = fetchMock.mock.calls[0]![0] as string;
+    expect(firstUrl).toContain("/services/data/v61.0/query");
+    expect(firstUrl).toContain("Id%2CName"); // url-encoded comma
+    expect(firstUrl).toContain("LIMIT%2010"); // encodeURIComponent uses %20 for space
+
+    const secondUrl = fetchMock.mock.calls[1]![0] as string;
+    expect(secondUrl).toContain("01g0000NEXT");
+  });
+
+  it("read() with raw SOQL string passes it through", async () => {
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({ records: [{ Id: "X" }], done: true }),
+    );
+    const c = createSalesforceConnector({
+      instanceUrl: "https://example.my.salesforce.com",
+      accessToken: "T",
+    });
+    const rows = await c.read("SELECT Id FROM Account WHERE Name = 'Foo'");
+    expect(rows.length).toBe(1);
+    const url = fetchMock.mock.calls[0]![0] as string;
+    expect(url).toContain("WHERE%20Name");
+  });
+
+  it("read() throws on non-2xx response", async () => {
+    fetchMock.mockResolvedValueOnce({
+      ok: false,
+      status: 401,
+      text: async () => "Unauthorized",
+      json: async () => ({}),
+    } as Response);
+    const c = createSalesforceConnector({
+      instanceUrl: "https://example.my.salesforce.com",
+      accessToken: "T",
+    });
+    await expect(c.read({ table: "Account" })).rejects.toThrow(/Salesforce query failed/);
+  });
+});

package/tests/unit/scorer.test.ts

@@ -0,0 +1,301 @@
+import { describe, it, expect } from "vitest";
+import {
+  scoreField,
+  scorePair,
+  findExactMatches,
+  findFuzzyMatches,
+  jaro,
+  jaroWinkler,
+  levenshteinDistance,
+  levenshteinSimilarity,
+  tokenSortRatio,
+  soundexMatch,
+  diceCoefficient,
+  jaccardSimilarity,
+  ensembleScore,
+  scoreMatrix,
+  applyTransform,
+} from "../../src/core/index.js";
+import type { MatchkeyConfig, MatchkeyField, Row } from "../../src/core/index.js";
+
+describe("jaro / jaroWinkler", () => {
+  it("jaro MARTHA ~= MARHTA matches Python (0.9444)", () => {
+    expect(jaro("MARTHA", "MARHTA")).toBeCloseTo(0.9444, 4);
+  });
+
+  it("jaroWinkler MARTHA ~= MARHTA matches Python (0.9611)", () => {
+    expect(jaroWinkler("MARTHA", "MARHTA")).toBeCloseTo(0.9611, 4);
+  });
+
+  it("jaroWinkler DIXON / DICKSONX matches Python (0.8133)", () => {
+    expect(jaroWinkler("DIXON", "DICKSONX")).toBeCloseTo(0.8133, 4);
+  });
+
+  it("jaroWinkler JELLYFISH / SMELLYFISH matches Python (0.8963)", () => {
+    expect(jaroWinkler("JELLYFISH", "SMELLYFISH")).toBeCloseTo(0.8963, 4);
+  });
+
+  it("jaro identical -> 1.0", () => {
+    expect(jaro("hello", "hello")).toBe(1.0);
+  });
+
+  it("jaro empty -> 0", () => {
+    expect(jaro("", "hello")).toBe(0.0);
+  });
+});
+
+describe("levenshtein", () => {
+  it("kitten -> sitting is distance 3", () => {
+    expect(levenshteinDistance("kitten", "sitting")).toBe(3);
+  });
+
+  it("identical distance 0", () => {
+    expect(levenshteinDistance("abc", "abc")).toBe(0);
+  });
+
+  it("empty -> len", () => {
+    expect(levenshteinDistance("", "abc")).toBe(3);
+  });
+
+  it("similarity 1.0 for identical", () => {
+    expect(levenshteinSimilarity("abc", "abc")).toBe(1.0);
+  });
+
+  it("kitten/sitting similarity matches Python (1 - 3/7 = 0.5714)", () => {
+    expect(levenshteinSimilarity("kitten", "sitting")).toBeCloseTo(0.5714, 4);
+  });
+
+  it("saturday/sunday similarity matches Python (1 - 3/8 = 0.6250)", () => {
+    expect(levenshteinSimilarity("saturday", "sunday")).toBeCloseTo(0.625, 4);
+  });
+});
+
+describe("tokenSortRatio (rapidfuzz-compatible)", () => {
+  it("John Smith / Smith John -> 1.0 (same token set)", () => {
+    expect(tokenSortRatio("John Smith", "Smith John")).toBe(1.0);
+  });
+
+  it("New York Mets / Mets New York -> 1.0", () => {
+    expect(tokenSortRatio("New York Mets", "Mets New York")).toBe(1.0);
+  });
+
+  it("John Smith / Smith Johnson matches Indel ratio (0.8696)", () => {
+    // sorted: "john smith" (10) vs "johnson smith" (13)
+    // indel distance = 3 (insert s, o, n), 1 - 3/23 = 20/23 ≈ 0.8696
+    expect(tokenSortRatio("John Smith", "Smith Johnson")).toBeCloseTo(0.8696, 4);
+  });
+
+  it("lowercases before sorting (case-insensitive)", () => {
+    expect(tokenSortRatio("John SMITH", "smith JOHN")).toBe(1.0);
+  });
+
+  it("strips punctuation (rapidfuzz preprocessing)", () => {
+    expect(tokenSortRatio("John, Smith!", "smith john.")).toBe(1.0);
+  });
+
+  it("different tokens return < 1", () => {
+    expect(tokenSortRatio("John", "Jane")).toBeLessThan(1.0);
+  });
+});
+
+describe("soundexMatch", () => {
+  it("Robert/Rupert same code -> 1.0 (both R163)", () => {
+    expect(soundexMatch("Robert", "Rupert")).toBe(1.0);
+  });
+
+  it("Smith/Smyth same code -> 1.0 (both S530)", () => {
+    expect(soundexMatch("Smith", "Smyth")).toBe(1.0);
+  });
+
+  it("Smith/Doe -> 0", () => {
+    expect(soundexMatch("Smith", "Doe")).toBe(0.0);
+  });
+});
+
+describe("ensembleScore", () => {
+  it("identical strings -> 1", () => {
+    expect(ensembleScore("hello", "hello")).toBe(1.0);
+  });
+
+  it("returns at least jaro_winkler", () => {
+    const jw = jaroWinkler("Smith", "Smyth");
+    const en = ensembleScore("Smith", "Smyth");
+    expect(en).toBeGreaterThanOrEqual(jw);
+  });
+});
+
+describe("dice / jaccard (bloom filter hex)", () => {
+  it("dice of identical bloom filters -> 1.0", () => {
+    const bloom = applyTransform("hello", "bloom_filter");
+    expect(bloom).not.toBe(null);
+    expect(diceCoefficient(bloom!, bloom!)).toBe(1.0);
+  });
+
+  it("jaccard of identical -> 1.0", () => {
+    const bloom = applyTransform("hello", "bloom_filter");
+    expect(jaccardSimilarity(bloom!, bloom!)).toBe(1.0);
+  });
+
+  it("all-zero filters -> 0", () => {
+    // 256 bits / 8 = 32 bytes, so 64 hex chars
+    const zero = "0".repeat(64);
+    expect(diceCoefficient(zero, zero)).toBe(0.0);
+    expect(jaccardSimilarity(zero, zero)).toBe(0.0);
+  });
+});
+
+describe("scoreField", () => {
+  it("exact a==a -> 1.0", () => {
+    expect(scoreField("a", "a", "exact")).toBe(1.0);
+  });
+
+  it("exact a!=b -> 0.0", () => {
+    expect(scoreField("a", "b", "exact")).toBe(0.0);
+  });
+
+  it("returns null if either input is null", () => {
+    expect(scoreField(null, "a", "exact")).toBe(null);
+    expect(scoreField("a", null, "jaro_winkler")).toBe(null);
+    expect(scoreField(null, null, "exact")).toBe(null);
+  });
+
+  it("unknown scorer throws", () => {
+    expect(() => scoreField("a", "b", "fake_scorer")).toThrow();
+  });
+
+  it("jaro_winkler returns similarity", () => {
+    const s = scoreField("abc", "abc", "jaro_winkler");
+    expect(s).toBe(1.0);
+  });
+
+  it("levenshtein", () => {
+    const s = scoreField("abc", "abc", "levenshtein");
+    expect(s).toBe(1.0);
+  });
+
+  it("token_sort", () => {
+    const s = scoreField("a b", "b a", "token_sort");
+    expect(s).toBe(1.0);
+  });
+
+  it("token_sort strips punctuation and lowercases (rapidfuzz parity)", () => {
+    // "John, Smith!" vs "smith john." → both sort to "john smith" → 1.0
+    expect(scoreField("John, Smith!", "smith john.", "token_sort")).toBe(1.0);
+  });
+});
+
+describe("scorePair - weighted fields", () => {
+  it("weighted aggregation of fields", () => {
+    const rowA: Row = { name: "John", city: "NYC" };
+    const rowB: Row = { name: "John", city: "NYC" };
+    const fields: MatchkeyField[] = [
+      { field: "name", transforms: [], scorer: "jaro_winkler", weight: 1.0 },
+      { field: "city", transforms: [], scorer: "exact", weight: 1.0 },
+    ];
+    expect(scorePair(rowA, rowB, fields)).toBe(1.0);
+  });
+
+  it("returns 0 when weightSum=0 (all fields null)", () => {
+    const rowA: Row = { name: null };
+    const rowB: Row = { name: null };
+    const fields: MatchkeyField[] = [
+      { field: "name", transforms: [], scorer: "jaro_winkler", weight: 1.0 },
+    ];
+    expect(scorePair(rowA, rowB, fields)).toBe(0);
+  });
+
+  it("weighted average of partial matches", () => {
+    const rowA: Row = { name: "John", city: "NYC" };
+    const rowB: Row = { name: "John", city: "LA" };
+    const fields: MatchkeyField[] = [
+      { field: "name", transforms: [], scorer: "exact", weight: 1.0 },
+      { field: "city", transforms: [], scorer: "exact", weight: 1.0 },
+    ];
+    // (1.0 * 1 + 0.0 * 1) / 2 = 0.5
+    expect(scorePair(rowA, rowB, fields)).toBe(0.5);
+  });
+});
+
+describe("findExactMatches", () => {
+  it("groups by matchkey column", () => {
+    const rows: Row[] = [
+      { __row_id__: 0, email: "a@x.com" },
+      { __row_id__: 1, email: "a@x.com" },
+      { __row_id__: 2, email: "b@x.com" },
+    ];
+    const mk: MatchkeyConfig = {
+      name: "email",
+      type: "exact",
+      fields: [{ field: "email", transforms: [], scorer: "exact", weight: 1.0 }],
+    };
+    const pairs = findExactMatches(rows, mk);
+    expect(pairs.length).toBe(1);
+    expect(pairs[0]!.idA).toBe(0);
+    expect(pairs[0]!.idB).toBe(1);
+    expect(pairs[0]!.score).toBe(1.0);
+  });
+
+  it("returns empty for 0 or 1 rows", () => {
+    const mk: MatchkeyConfig = {
+      name: "email",
+      type: "exact",
+      fields: [{ field: "email", transforms: [], scorer: "exact", weight: 1.0 }],
+    };
+    expect(findExactMatches([], mk)).toEqual([]);
+    expect(findExactMatches([{ __row_id__: 0, email: "a" }], mk)).toEqual([]);
+  });
+
+  it("skips rows where matchkey field is null", () => {
+    const rows: Row[] = [
+      { __row_id__: 0, email: null },
+      { __row_id__: 1, email: null },
+      { __row_id__: 2, email: "x@x.com" },
+    ];
+    const mk: MatchkeyConfig = {
+      name: "email",
+      type: "exact",
+      fields: [{ field: "email", transforms: [], scorer: "exact", weight: 1.0 }],
+    };
+    const pairs = findExactMatches(rows, mk);
+    expect(pairs.length).toBe(0);
+  });
+});
+
+describe("findFuzzyMatches", () => {
+  it("NxN scoring within block", () => {
+    const rows: Row[] = [
+      { __row_id__: 0, name: "Jon Smith" },
+      { __row_id__: 1, name: "John Smith" },
+      { __row_id__: 2, name: "Zeke Xavier" },
+    ];
+    const mk: MatchkeyConfig = {
+      name: "name_fuzzy",
+      type: "weighted",
+      threshold: 0.7,
+      fields: [{ field: "name", transforms: [], scorer: "jaro_winkler", weight: 1.0 }],
+    };
+    const pairs = findFuzzyMatches(rows, mk);
+    // Jon/John should match; Zeke should not match either
+    const hasPair01 = pairs.some((p) => p.idA === 0 && p.idB === 1);
+    expect(hasPair01).toBe(true);
+  });
+
+  it("empty if fewer than 2 rows", () => {
+    const mk: MatchkeyConfig = {
+      name: "f",
+      type: "weighted",
+      threshold: 0.85,
+      fields: [{ field: "name", transforms: [], scorer: "jaro_winkler", weight: 1.0 }],
+    };
+    expect(findFuzzyMatches([], mk)).toEqual([]);
+  });
+});
+
+describe("scoreMatrix", () => {
+  it("symmetric with 0 diagonal", () => {
+    const m = scoreMatrix(["abc", "abd", "xyz"], "jaro_winkler");
+    expect(m.length).toBe(3);
+    expect(m[0]![0]).toBe(0); // diagonal
+    expect(m[0]![1]).toBe(m[1]![0]); // symmetric
+  });
+});

package/tests/unit/sensitivity.test.ts

@@ -0,0 +1,154 @@
+import { describe, it, expect } from "vitest";
+import { runSensitivity, stabilityReport } from "../../src/core/sensitivity.js";
+import {
+  makeConfig,
+  makeBlockingConfig,
+  makeMatchkeyConfig,
+  makeMatchkeyField,
+} from "../../src/core/types.js";
+import type { Row } from "../../src/core/types.js";
+
+function makeRows(): Row[] {
+  // 20 rows, five near-duplicate pairs (so threshold sweeps actually change clustering).
+  const rows: Row[] = [];
+  let id = 0;
+  const dupes: Array<[string, string]> = [
+    ["John Smith", "Jon Smith"],
+    ["Mary Jones", "Marie Jones"],
+    ["Alice Brown", "Alicia Brown"],
+    ["Bob Miller", "Robert Miller"],
+    ["Carol Davis", "Caroline Davis"],
+  ];
+  for (const [a, b] of dupes) {
+    rows.push({ __row_id__: id++, name: a });
+    rows.push({ __row_id__: id++, name: b });
+  }
+  // 10 distinct distractors.
+  for (const nm of [
+    "Zygmunt Petrov", "Xiong Wei", "Nakamura Taro", "Kowalski Jan",
+    "Oduya Esther", "Rasmussen Ole", "Tanaka Yui", "Vasquez Maria",
+    "Wojcik Piotr", "Yamamoto Ken",
+  ]) {
+    rows.push({ __row_id__: id++, name: nm });
+  }
+  return rows;
+}
+
+function baselineConfig() {
+  const mk = makeMatchkeyConfig({
+    name: "name_fuzzy",
+    type: "weighted",
+    threshold: 0.85,
+    fields: [
+      makeMatchkeyField({
+        field: "name",
+        scorer: "jaro_winkler",
+        transforms: ["lowercase"],
+      }),
+    ],
+  });
+  const blocking = makeBlockingConfig({
+    strategy: "static",
+    keys: [{ fields: ["name"], transforms: ["lowercase", "substring:0:1"] }],
+  });
+  return makeConfig({ matchkeys: [mk], blocking, threshold: 0.85 });
+}
+
+describe("runSensitivity", () => {
+  it("produces one SweepPoint per value with stats and TWI vs baseline", () => {
+    const rows = makeRows();
+    const cfg = baselineConfig();
+    const result = runSensitivity(rows, cfg, [
+      { path: "threshold", values: [0.75, 0.85, 0.95] },
+    ]);
+    expect(result.points.length).toBe(3);
+    for (const p of result.points) {
+      // Either error path or stats path; in a clean run we expect stats.
+      if (p.error === undefined) {
+        expect(typeof p.stats["totalClusters"]).toBe("number");
+        expect(typeof p.stats["totalRecords"]).toBe("number");
+        // TWI is an optional number in [0, 1]-ish when present.
+        if (p.twi !== undefined) {
+          expect(p.twi).toBeGreaterThanOrEqual(0);
+          expect(p.twi).toBeLessThanOrEqual(1);
+        }
+      }
+    }
+    // Baseline has TWI = 1 by construction.
+    expect(result.baseline.twi).toBe(1.0);
+  });
+
+  it("writes the sweep-param value into each point's params object (dot-path at root)", () => {
+    const rows = makeRows();
+    const cfg = baselineConfig();
+    const result = runSensitivity(rows, cfg, [
+      { path: "threshold", values: [0.7, 0.9] },
+    ]);
+    const values = result.points.map((p) => p.params["threshold"]);
+    expect(values).toEqual([0.7, 0.9]);
+  });
+
+  it("preserves partial results when one point errors", () => {
+    const rows = makeRows();
+    const cfg = baselineConfig();
+    // Inject a non-existent path that will parse fine but using an invalid
+    // matchkey object forces the pipeline to throw.
+    const result = runSensitivity(rows, cfg, [
+      {
+        path: "matchkeys",
+        values: [
+          // Valid: single matchkey -> runs fine
+          [
+            makeMatchkeyConfig({
+              name: "m",
+              type: "weighted",
+              fields: [makeMatchkeyField({ field: "name", scorer: "jaro_winkler" })],
+              threshold: 0.85,
+            }),
+          ],
+          // Invalid: matchkey referring to a non-existent scorer triggers an
+          // exception during scoring for some inputs. Use a malformed shape
+          // that throws early: field array contains non-objects.
+          [
+            {
+              name: "bad",
+              type: "weighted",
+              fields: [null],
+              threshold: 0.85,
+            } as unknown,
+          ],
+        ],
+      },
+    ]);
+    expect(result.points.length).toBe(2);
+    // At least one good point, at least one error point.
+    const errs = result.points.filter((p) => p.error !== undefined);
+    const ok = result.points.filter((p) => p.error === undefined);
+    expect(ok.length).toBeGreaterThanOrEqual(1);
+    expect(errs.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it("empty sweep params yields zero points but still a baseline", () => {
+    const rows = makeRows();
+    const cfg = baselineConfig();
+    const result = runSensitivity(rows, cfg, []);
+    expect(result.points.length).toBe(0);
+    expect(result.baseline.twi).toBe(1.0);
+    expect(result.stable).toBe(true);
+  });
+});
+
+describe("stabilityReport", () => {
+  it("returns a string summarizing the sweep", () => {
+    const rows = makeRows();
+    const cfg = baselineConfig();
+    const result = runSensitivity(rows, cfg, [
+      { path: "threshold", values: [0.85, 0.95] },
+    ]);
+    const report = stabilityReport(result);
+    expect(typeof report).toBe("string");
+    expect(report).toContain("Sensitivity sweep");
+    expect(report).toContain("Points");
+    expect(report).toContain("Stable");
+  });
+});

package/tests/unit/standardize.test.ts

@@ -0,0 +1,84 @@
+import { describe, it, expect } from "vitest";
+import { applyStandardizer, applyStandardization } from "../../src/core/index.js";
+import type { Row } from "../../src/core/index.js";
+
+describe("applyStandardizer", () => {
+  it("email: lowercase and strip", () => {
+    expect(applyStandardizer("  USER@Example.COM  ", "email")).toBe("user@example.com");
+  });
+
+  it("email: invalid returns empty string (null->empty)", () => {
+    expect(applyStandardizer("not-an-email", "email")).toBe("");
+  });
+
+  it("name_proper: JOHN smith -> John Smith", () => {
+    expect(applyStandardizer("JOHN smith", "name_proper")).toBe("John Smith");
+  });
+
+  it("name_proper: hyphenated mary-jane -> Mary-Jane", () => {
+    expect(applyStandardizer("mary-jane", "name_proper")).toBe("Mary-Jane");
+  });
+
+  it("phone: digits only, strips US country code", () => {
+    expect(applyStandardizer("1-800-555-1234", "phone")).toBe("8005551234");
+  });
+
+  it("phone: pure digits retained", () => {
+    expect(applyStandardizer("(415) 555-1234", "phone")).toBe("4155551234");
+  });
+
+  it("zip5: 12345-6789 -> 12345", () => {
+    expect(applyStandardizer("12345-6789", "zip5")).toBe("12345");
+  });
+
+  it("zip5: short padded", () => {
+    expect(applyStandardizer("123", "zip5")).toBe("00123");
+  });
+
+  it("address: MAIN ST -> Main St", () => {
+    expect(applyStandardizer("MAIN ST", "address")).toBe("Main St");
+  });
+
+  it("address: MAIN STREET -> Main St (abbreviated)", () => {
+    expect(applyStandardizer("MAIN STREET", "address")).toBe("Main St");
+  });
+
+  it("state uppercases", () => {
+    expect(applyStandardizer(" ca ", "state")).toBe("CA");
+  });
+
+  it("strip removes whitespace", () => {
+    expect(applyStandardizer("  hello  ", "strip")).toBe("hello");
+  });
+
+  it("unknown standardizer throws", () => {
+    expect(() => applyStandardizer("x", "not-a-thing")).toThrow();
+  });
+});
+
+describe("applyStandardization", () => {
+  it("applies rules dict to rows", () => {
+    const rows: Row[] = [
+      { email: "USER@X.COM", first: "JOHN" },
+    ];
+    const out = applyStandardization(rows, {
+      email: ["email"],
+      first: ["name_proper"],
+    });
+    expect(out[0]!.email).toBe("user@x.com");
+    expect(out[0]!.first).toBe("John");
+  });
+
+  it("leaves nulls as-is", () => {
+    const rows: Row[] = [{ email: null, first: "A" }];
+    const out = applyStandardization(rows, { email: ["email"], first: ["name_proper"] });
+    expect(out[0]!.email).toBe(null);
+    expect(out[0]!.first).toBe("A");
+  });
+
+  it("chains multiple standardizers", () => {
+    const rows: Row[] = [{ first: "  JOHN  " }];
+    const out = applyStandardization(rows, { first: ["strip", "name_proper"] });
+    expect(out[0]!.first).toBe("John");
+  });
+});