shadowjoin 0.0.0-stage → 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,87 @@
+/** 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;
+}
+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[];
+    warnings: string[];
+    rulesApplied: string[];
+}

package/dist/types.js

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

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "shadowjoin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Measure the matches your exact join is silently dropping. Runs a shadow matcher alongside your real join key and reports a verified floor on lost matches, plus the normalization rule that would recover each one.",
+  "keywords": [
+    "entity-resolution",
+    "record-linkage",
+    "data-quality",
+    "fuzzy-matching",
+    "deduplication",
+    "pair-completeness",
+    "join",
+    "postgres",
+    "csv",
+    "mcp",
+    "data-validation",
+    "recall"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "shadowjoin": "dist/cli.js",
+    "shadowjoin-mcp": "dist/mcp.js"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./mcp": "./dist/mcp.js",
+    "./adapters/postgres": "./dist/adapters/postgres.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "SKILL.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test test/",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": ">=1",
+    "pg": ">=8"
+  },
+  "peerDependenciesMeta": {
+    "pg": {
+      "optional": true
+    },
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "@types/node": "^22.0.0",
+    "@types/pg": "^8.23.1",
+    "typescript": "^5.6.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/harsh-chandak/shadowjoin.git"
+  },
+  "homepage": "https://github.com/harsh-chandak/shadowjoin#readme",
+  "author": "Harsh N. Chandak",
+  "bugs": {
+    "url": "https://github.com/harsh-chandak/shadowjoin/issues"
+  }
+}