goldenpipe 0.1.0

package/dist/cli.js

@@ -0,0 +1,1053 @@
+#!/usr/bin/env node
+import { writeFileSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { Command } from 'commander';
+import { TabularData, scanData, severityLabel } from 'goldencheck/core';
+import { TransformEngine } from 'goldenflow/core';
+import { makeConfig, dedupe, makeMatchkeyConfig, makeMatchkeyField, makeBlockingConfig } from 'goldenmatch/core';
+
+// src/core/models.ts
+var StageStatus = {
+  SUCCESS: "success",
+  SKIPPED: "skipped",
+  FAILED: "failed"
+};
+var PipeStatus = {
+  SUCCESS: "success",
+  PARTIAL: "partial",
+  FAILED: "failed"
+};
+function makePipeContext(input) {
+  return {
+    df: input?.df ?? null,
+    artifacts: input?.artifacts ?? {},
+    metadata: input?.metadata ?? {},
+    timing: input?.timing ?? {},
+    reasoning: input?.reasoning ?? {},
+    stageConfig: input?.stageConfig ?? {}
+  };
+}
+function makeStageSpec(input) {
+  if (typeof input === "string") {
+    return { use: input, needs: [], onError: "continue", config: {} };
+  }
+  return {
+    ...input.name !== void 0 ? { name: input.name } : {},
+    use: input.use,
+    needs: input.needs ?? [],
+    ...input.skipIf !== void 0 ? { skipIf: input.skipIf } : {},
+    onError: input.onError ?? "continue",
+    config: input.config ?? {}
+  };
+}
+function makePipelineConfig(input) {
+  return {
+    pipeline: input.pipeline,
+    ...input.source !== void 0 ? { source: input.source } : {},
+    ...input.output !== void 0 ? { output: input.output } : {},
+    stages: input.stages,
+    decisions: input.decisions ?? []
+  };
+}
+
+// src/core/columnContext.ts
+var ColumnType = {
+  NAME: "name",
+  EMAIL: "email",
+  PHONE: "phone",
+  DATE: "date",
+  GEO: "geo",
+  ADDRESS: "address",
+  ZIP: "zip",
+  IDENTIFIER: "identifier",
+  NUMERIC: "numeric",
+  STRING: "string"};
+var CardinalityBand = {
+  UNSET: "",
+  LOW: "low",
+  MID: "mid",
+  HIGH: "high",
+  SKIP: "skip"
+};
+var MIN_CONFIDENCE = 0.3;
+var IDENTIFIER_TYPES = /* @__PURE__ */ new Set([
+  ColumnType.NAME,
+  ColumnType.EMAIL,
+  ColumnType.PHONE
+]);
+var NEVER_IDENTIFIER_TYPES = /* @__PURE__ */ new Set([
+  ColumnType.DATE,
+  ColumnType.NUMERIC,
+  ColumnType.IDENTIFIER
+]);
+function makeColumnContext(input) {
+  const ctx = {
+    name: input.name,
+    inferredType: input.inferredType ?? ColumnType.STRING,
+    nullRate: input.nullRate ?? 0,
+    cardinality: input.cardinality ?? 0,
+    isIdentifier: input.isIdentifier ?? false,
+    transformsApplied: input.transformsApplied ?? [],
+    findings: input.findings ?? [],
+    confidence: input.confidence ?? 0.5,
+    cardinalityBand: input.cardinalityBand ?? CardinalityBand.UNSET
+  };
+  if (!ctx.name) {
+    throw new Error("ColumnContext.name must be non-empty");
+  }
+  if (!(ctx.nullRate >= 0 && ctx.nullRate <= 1)) {
+    throw new Error(`nullRate must be in [0, 1], got ${ctx.nullRate}`);
+  }
+  if (ctx.cardinality < 0) {
+    throw new Error(`cardinality must be >= 0, got ${ctx.cardinality}`);
+  }
+  if (!(ctx.confidence >= 0 && ctx.confidence <= 1)) {
+    throw new Error(`confidence must be in [0, 1], got ${ctx.confidence}`);
+  }
+  return ctx;
+}
+var NAME_PATTERNS = /(^name$|first.?name|last.?name|full.?name|fname|lname|surname|given.?name|middle)/i;
+var EMAIL_PATTERNS = /(email|e.?mail|email.?addr)/i;
+var PHONE_PATTERNS = /(phone|tel|mobile|fax|cell)/i;
+var ZIP_PATTERNS = /(zip|postal|postcode|zip.?code)/i;
+var ADDRESS_PATTERNS = /(address|street|addr|line.?1|line.?2)/i;
+var GEO_PATTERNS = /(city|^state$|state.?cd|^country$|province|region|county)/i;
+var DATE_PATTERNS = /(date|_dt$|_date$|registr|created|updated|birth.?d|dob)/i;
+var ID_PATTERNS = /(^id$|^key$|^code$|^sku$|_id$|_key$)/i;
+function classifyByName(colName) {
+  if (DATE_PATTERNS.test(colName)) return ColumnType.DATE;
+  if (EMAIL_PATTERNS.test(colName)) return ColumnType.EMAIL;
+  if (ZIP_PATTERNS.test(colName)) return ColumnType.ZIP;
+  if (GEO_PATTERNS.test(colName)) return ColumnType.GEO;
+  if (ADDRESS_PATTERNS.test(colName)) return ColumnType.ADDRESS;
+  if (PHONE_PATTERNS.test(colName)) return ColumnType.PHONE;
+  if (NAME_PATTERNS.test(colName)) return ColumnType.NAME;
+  if (ID_PATTERNS.test(colName)) return ColumnType.IDENTIFIER;
+  return null;
+}
+function normalizeDtype(rawType) {
+  const t = rawType.toLowerCase().trim();
+  if (t.includes("int") || t.includes("float")) return ColumnType.NUMERIC;
+  if (t.includes("date") || t.includes("time")) return ColumnType.DATE;
+  if (t.includes("bool")) return ColumnType.STRING;
+  return ColumnType.STRING;
+}
+function computeCardinalityBands(contexts) {
+  const stringContexts = contexts.filter(
+    (c) => c.inferredType !== ColumnType.NUMERIC && c.inferredType !== ColumnType.DATE
+  );
+  if (stringContexts.length < 3) {
+    return;
+  }
+  const cardinalities = stringContexts.map((c) => c.cardinality).sort((a, b) => a - b);
+  const n = cardinalities.length;
+  const q1 = cardinalities[Math.floor(n / 4)];
+  const q3 = cardinalities[Math.floor(3 * n / 4)];
+  for (const ctx of contexts) {
+    if (ctx.inferredType === ColumnType.NUMERIC || ctx.inferredType === ColumnType.DATE) {
+      ctx.cardinalityBand = CardinalityBand.SKIP;
+      continue;
+    }
+    if (ctx.cardinality <= q1) {
+      ctx.cardinalityBand = CardinalityBand.LOW;
+    } else if (ctx.cardinality >= q3) {
+      ctx.cardinalityBand = CardinalityBand.HIGH;
+    } else {
+      ctx.cardinalityBand = CardinalityBand.MID;
+    }
+  }
+}
+function applyCardinalitySignal(contexts) {
+  for (const ctx of contexts) {
+    if (NEVER_IDENTIFIER_TYPES.has(ctx.inferredType)) {
+      ctx.isIdentifier = false;
+      continue;
+    }
+    const hasNameSignal = IDENTIFIER_TYPES.has(ctx.inferredType);
+    const band = ctx.cardinalityBand;
+    if (hasNameSignal && band === CardinalityBand.MID) {
+      ctx.isIdentifier = true;
+      ctx.confidence = Math.min(ctx.confidence + 0.15, 1);
+    } else if (hasNameSignal && band === CardinalityBand.LOW) {
+      ctx.isIdentifier = false;
+      ctx.confidence = Math.max(ctx.confidence - 0.2, MIN_CONFIDENCE);
+    } else if (hasNameSignal && band === CardinalityBand.HIGH) {
+      ctx.isIdentifier = true;
+      ctx.confidence = Math.min(ctx.confidence + 0.05, 1);
+    } else if (!hasNameSignal && band === CardinalityBand.MID) {
+      if (ctx.inferredType === ColumnType.STRING) {
+        ctx.isIdentifier = true;
+        ctx.confidence = 0.5;
+      }
+    } else if (!hasNameSignal && band === CardinalityBand.LOW) {
+      ctx.isIdentifier = false;
+    } else if (!hasNameSignal && band === CardinalityBand.HIGH) {
+      ctx.isIdentifier = false;
+    }
+    if (ctx.nullRate > 0.3 && ctx.isIdentifier) {
+      ctx.confidence = Math.max(ctx.confidence - 0.1, MIN_CONFIDENCE);
+    }
+  }
+}
+function buildContextsFromCheck(findings, columnProfiles) {
+  if (!columnProfiles || columnProfiles.length === 0) {
+    return [];
+  }
+  const contexts = /* @__PURE__ */ new Map();
+  for (const cp of columnProfiles) {
+    let semanticType = classifyByName(cp.name);
+    if (!semanticType) {
+      semanticType = normalizeDtype(cp.inferredType ?? "string");
+    }
+    const ctx = makeColumnContext({
+      name: cp.name,
+      inferredType: semanticType,
+      nullRate: cp.nullPct ?? 0,
+      cardinality: cp.uniqueCount ?? 0,
+      isIdentifier: IDENTIFIER_TYPES.has(semanticType),
+      confidence: semanticType !== ColumnType.STRING ? 0.8 : 0.4
+    });
+    contexts.set(cp.name, ctx);
+  }
+  const contextList = [...contexts.values()];
+  computeCardinalityBands(contextList);
+  applyCardinalitySignal(contextList);
+  for (const f of findings) {
+    const colName = f.column;
+    if (!colName || !contexts.has(colName)) continue;
+    const ctx = contexts.get(colName);
+    const check = f.check ?? "";
+    const message = String(f.message ?? "").slice(0, 80);
+    ctx.findings.push(`${check}: ${message}`);
+  }
+  return contextList;
+}
+function enrichContextsFromFlow(contexts, records) {
+  if (!records) return;
+  const lookup = new Map(contexts.map((c) => [c.name, c]));
+  for (const record of records) {
+    const colName = record.column;
+    const transform = record.transform;
+    const affected = record.affectedRows ?? 0;
+    if (!colName || !lookup.has(colName)) continue;
+    const ctx = lookup.get(colName);
+    if (affected > 0 && transform) {
+      ctx.transformsApplied.push(transform);
+    }
+    if (transform && transform.toLowerCase().includes("date")) {
+      ctx.inferredType = ColumnType.DATE;
+      ctx.isIdentifier = false;
+      ctx.confidence = 0.95;
+    }
+  }
+}
+function distinctNonNull(rows, col) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const row of rows) {
+    const v = row[col];
+    if (v === null || v === void 0 || v === "") continue;
+    seen.add(v);
+  }
+  return seen.size;
+}
+function nullRateOf(rows, col) {
+  if (rows.length === 0) return 1;
+  let nulls = 0;
+  for (const row of rows) {
+    const v = row[col];
+    if (v === null || v === void 0 || v === "") nulls += 1;
+  }
+  return nulls / rows.length;
+}
+
+// src/core/engine/registry.ts
+var StageRegistry = class {
+  stages = /* @__PURE__ */ new Map();
+  /** Register a stage under its `info.name`. */
+  register(stage2) {
+    this.stages.set(stage2.info.name, stage2);
+  }
+  /** Retrieve a stage by name. Throws if not found. */
+  get(name) {
+    const stage2 = this.stages.get(name);
+    if (stage2 === void 0) {
+      throw new Error(`Stage '${name}' not found in registry`);
+    }
+    return stage2;
+  }
+  /** True when a stage with this name is registered. */
+  has(name) {
+    return this.stages.has(name);
+  }
+  /** Return `{ name: StageInfo }` for all registered stages. */
+  listAll() {
+    const out = {};
+    for (const [name, s] of this.stages) {
+      out[name] = s.info;
+    }
+    return out;
+  }
+};
+
+// src/core/engine/resolver.ts
+var WiringError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "WiringError";
+  }
+};
+var Resolver = {
+  /**
+   * Resolve a config + registry into an ordered ExecutionPlan. Auto-prepends
+   * the built-in `load` stage when available and validates that every stage's
+   * `consumes` is produced by an earlier stage.
+   */
+  resolve(config, registry) {
+    const plan = { stages: [] };
+    const availableArtifacts = /* @__PURE__ */ new Set();
+    if (registry.has("load")) {
+      const load = registry.get("load");
+      plan.stages.push({
+        name: "load",
+        stage: load,
+        spec: makeStageSpec("load"),
+        config: {}
+      });
+      for (const p of load.info.produces) availableArtifacts.add(p);
+    } else {
+      availableArtifacts.add("df");
+    }
+    for (const rawSpec of config.stages) {
+      const spec = makeStageSpec(rawSpec);
+      const stageObj = registry.get(spec.use);
+      const name = spec.name ?? stageObj.info.name;
+      for (const dep of stageObj.info.consumes) {
+        if (!availableArtifacts.has(dep)) {
+          throw new WiringError(
+            `Stage '${name}' consumes '${dep}' but no prior stage produces it. Available: ${[...availableArtifacts].sort().join(", ")}`
+          );
+        }
+      }
+      plan.stages.push({ name, stage: stageObj, spec, config: spec.config });
+      for (const p of stageObj.info.produces) availableArtifacts.add(p);
+    }
+    return plan;
+  }
+};
+
+// src/core/engine/router.ts
+var Router = {
+  /**
+   * Apply a Decision (skip / abort / insert) to the remaining stages and
+   * return the new remaining list. Records `decision.reason` in
+   * `ctx.reasoning._router`.
+   */
+  apply(decision, remaining, ctx, registry) {
+    if (decision.reason) {
+      ctx.reasoning["_router"] = decision.reason;
+    }
+    if (decision.abort) {
+      ctx.reasoning["_router"] = `ABORT: ${decision.reason}`;
+      return [];
+    }
+    let next = remaining;
+    if (decision.skip.length > 0) {
+      const skipSet = new Set(decision.skip);
+      next = next.filter((s) => !skipSet.has(s.name));
+    }
+    if (decision.insert.length > 0) {
+      const inserted = [];
+      for (const name of decision.insert) {
+        const stageObj = registry.get(name);
+        inserted.push({
+          name,
+          stage: stageObj,
+          spec: makeStageSpec(name),
+          config: {}
+        });
+      }
+      next = [...inserted, ...next];
+    }
+    return next;
+  }
+};
+
+// src/core/engine/runner.ts
+function isFalsy(value) {
+  if (value === null || value === void 0) return true;
+  if (value === false || value === 0 || value === "") return true;
+  if (Array.isArray(value)) return value.length === 0;
+  if (value instanceof Map || value instanceof Set) return value.size === 0;
+  if (typeof value === "object") return Object.keys(value).length === 0;
+  return false;
+}
+var Runner = class {
+  constructor(registry) {
+    this.registry = registry;
+  }
+  registry;
+  /** Execute an ExecutionPlan against a PipeContext, returning per-stage results. */
+  async run(plan, ctx) {
+    const results = {};
+    let remaining = [...plan.stages];
+    while (remaining.length > 0) {
+      const planned = remaining.shift();
+      if (planned.spec.skipIf) {
+        const artifact = ctx.artifacts[planned.spec.skipIf];
+        if (isFalsy(artifact)) {
+          results[planned.name] = { status: StageStatus.SKIPPED };
+          ctx.reasoning[planned.name] = `Skipped: artifact '${planned.spec.skipIf}' is missing/falsy`;
+          continue;
+        }
+      }
+      const start = performance.now();
+      try {
+        ctx.stageConfig = planned.config;
+        await planned.stage.validate(ctx);
+        const result = await planned.stage.run(ctx);
+        ctx.timing[planned.name] = (performance.now() - start) / 1e3;
+        results[planned.name] = result;
+        if (result.decision != null) {
+          remaining = Router.apply(result.decision, remaining, ctx, this.registry);
+        }
+      } catch (e) {
+        ctx.timing[planned.name] = (performance.now() - start) / 1e3;
+        const message = e instanceof Error ? e.message : String(e);
+        results[planned.name] = { status: StageStatus.FAILED, error: message };
+        ctx.reasoning[planned.name] = `Failed: ${message}`;
+        if (planned.spec.onError === "abort") {
+          break;
+        }
+      }
+    }
+    return results;
+  }
+};
+
+// src/core/engine/reporter.ts
+var Reporter = {
+  build(ctx, stages) {
+    const entries = Object.entries(stages);
+    const errors = entries.filter(([, r]) => r.status === StageStatus.FAILED && r.error).map(([name, r]) => `${name}: ${r.error}`);
+    const skipped = entries.filter(([, r]) => r.status === StageStatus.SKIPPED).map(([name]) => name);
+    const nonSkip = entries.map(([, r]) => r.status).filter((s) => s !== StageStatus.SKIPPED);
+    let status;
+    if (nonSkip.length === 0) {
+      status = PipeStatus.SUCCESS;
+    } else if (nonSkip.every((s) => s === StageStatus.FAILED)) {
+      status = PipeStatus.FAILED;
+    } else if (nonSkip.every((s) => s === StageStatus.SUCCESS)) {
+      status = PipeStatus.SUCCESS;
+    } else {
+      status = PipeStatus.PARTIAL;
+    }
+    return {
+      status,
+      source: typeof ctx.metadata["source"] === "string" ? ctx.metadata["source"] : "",
+      inputRows: typeof ctx.metadata["input_rows"] === "number" ? ctx.metadata["input_rows"] : 0,
+      stages,
+      artifacts: { ...ctx.artifacts },
+      skipped,
+      errors,
+      reasoning: { ...ctx.reasoning },
+      timing: { ...ctx.timing }
+    };
+  }
+};
+
+// src/core/adapters/load.ts
+var LoadStage = {
+  info: { name: "load", produces: ["df"], consumes: [] },
+  validate(_ctx) {
+  },
+  async run(_ctx) {
+    return { status: StageStatus.SUCCESS };
+  },
+  rollback: null
+};
+function normalizeFinding(f) {
+  return {
+    severity: severityLabel(f.severity).toLowerCase(),
+    check: f.check,
+    column: f.column,
+    message: f.message
+  };
+}
+function toColumnProfileLike(cp) {
+  return {
+    name: cp.name,
+    inferredType: cp.inferredType,
+    nullPct: cp.nullPct,
+    uniqueCount: cp.uniqueCount
+  };
+}
+var ScanStage = {
+  info: { name: "goldencheck.scan", produces: ["findings", "profile"], consumes: ["df"] },
+  validate(ctx) {
+    if (ctx.df === null) {
+      throw new Error("ScanStage: no df in context");
+    }
+  },
+  async run(ctx) {
+    const rows = ctx.df ?? [];
+    const data = new TabularData(rows);
+    const stageCfg = ctx.stageConfig;
+    const opts = stageCfg && Object.keys(stageCfg).length > 0 ? stageCfg : void 0;
+    const result = scanData(data, opts);
+    const findings = result.findings.map(normalizeFinding);
+    const columnProfiles = result.profile.columns;
+    ctx.artifacts["findings"] = findings;
+    ctx.artifacts["profile"] = result.profile;
+    try {
+      const profileLikes = columnProfiles.map(toColumnProfileLike);
+      const findingLikes = findings.map((f) => ({
+        column: f.column,
+        check: f.check,
+        message: f.message
+      }));
+      ctx.artifacts["column_contexts"] = buildContextsFromCheck(findingLikes, profileLikes);
+    } catch {
+      ctx.artifacts["column_contexts"] = [];
+    }
+    return { status: StageStatus.SUCCESS };
+  },
+  rollback: null
+};
+var TransformStage = {
+  info: { name: "goldenflow.transform", produces: ["df", "manifest"], consumes: ["df"] },
+  validate(ctx) {
+    if (ctx.df === null) {
+      throw new Error("TransformStage: no df in context");
+    }
+  },
+  async run(ctx) {
+    const rows = ctx.df ?? [];
+    const stageCfg = ctx.stageConfig;
+    const config = stageCfg && Object.keys(stageCfg).length > 0 ? stageCfg : void 0;
+    const engine = new TransformEngine(config);
+    const result = engine.transformDf(rows);
+    ctx.df = [...result.rows];
+    ctx.artifacts["manifest"] = result.manifest;
+    const contexts = ctx.artifacts["column_contexts"];
+    if (Array.isArray(contexts)) {
+      try {
+        const records = result.manifest.records.map((r) => ({
+          column: r.column,
+          transform: r.transform,
+          affectedRows: r.affectedRows
+        }));
+        enrichContextsFromFlow(contexts, records);
+      } catch {
+      }
+    }
+    return { status: StageStatus.SUCCESS };
+  },
+  rollback: null
+};
+function castRowsToString(rows) {
+  return rows.map((row) => {
+    const out = {};
+    for (const [k, v] of Object.entries(row)) {
+      out[k] = v === null || v === void 0 ? "" : String(v);
+    }
+    return out;
+  });
+}
+var DedupeStage = {
+  info: { name: "goldenmatch.dedupe", produces: ["clusters", "golden"], consumes: ["df"] },
+  validate(ctx) {
+    if (ctx.df === null) {
+      throw new Error("DedupeStage: no df in context");
+    }
+  },
+  async run(ctx) {
+    const rows = castRowsToString(ctx.df ?? []);
+    ctx.df = rows;
+    const stageCfg = ctx.stageConfig;
+    let config = null;
+    if (stageCfg && Object.keys(stageCfg).length > 0) {
+      config = makeConfig(stageCfg);
+    } else {
+      const contexts = ctx.artifacts["column_contexts"];
+      if (Array.isArray(contexts) && contexts.length > 0) {
+        config = buildConfigFromContexts(contexts, rows);
+      }
+    }
+    const result = config !== null ? await dedupe(rows, { config }) : await dedupe(rows);
+    ctx.artifacts["clusters"] = result.clusters;
+    ctx.artifacts["golden"] = result.goldenRecords;
+    ctx.artifacts["unique"] = result.unique;
+    ctx.artifacts["dupes"] = result.dupes;
+    ctx.artifacts["match_stats"] = result.stats;
+    ctx.artifacts["scored_pairs"] = result.scoredPairs;
+    const mks = config?.matchkeys;
+    if (mks && mks.length > 0) {
+      ctx.artifacts["matchkey_used"] = mks[0].name;
+    }
+    return { status: StageStatus.SUCCESS };
+  },
+  rollback: null
+};
+function buildConfigFromContexts(contexts, rows) {
+  const nameCols = contexts.filter(
+    (c) => c.inferredType === ColumnType.NAME && c.isIdentifier
+  );
+  const emailCols = contexts.filter((c) => c.inferredType === ColumnType.EMAIL);
+  const geoCols = contexts.filter((c) => c.inferredType === ColumnType.GEO);
+  const matchkeys = [];
+  for (const col of emailCols) {
+    matchkeys.push(
+      makeMatchkeyConfig({
+        name: `exact_${col.name}`,
+        type: "exact",
+        fields: [makeMatchkeyField({ field: col.name, transforms: ["lowercase", "strip"], scorer: "exact" })]
+      })
+    );
+  }
+  if (nameCols.length > 0) {
+    const fuzzyFields = nameCols.map(
+      (col) => makeMatchkeyField({
+        field: col.name,
+        scorer: "jaro_winkler",
+        weight: 1,
+        transforms: ["lowercase", "strip"]
+      })
+    );
+    matchkeys.push(
+      makeMatchkeyConfig({
+        name: "fuzzy_names",
+        type: "weighted",
+        threshold: 0.85,
+        fields: fuzzyFields
+      })
+    );
+  }
+  if (matchkeys.length === 0) {
+    let stringCols = contexts.filter(
+      (c) => c.inferredType === ColumnType.STRING || c.inferredType === ColumnType.NAME
+    );
+    if (rows.length > 0) {
+      const minCardinality = Math.max(10, Math.floor(rows.length * 0.05));
+      stringCols = stringCols.filter((c) => distinctNonNull(rows, c.name) >= minCardinality);
+    }
+    const fallbackFields = stringCols.slice(0, 3).map(
+      (col) => makeMatchkeyField({
+        field: col.name,
+        scorer: "jaro_winkler",
+        weight: 1,
+        transforms: ["lowercase", "strip"]
+      })
+    );
+    if (fallbackFields.length > 0) {
+      matchkeys.push(
+        makeMatchkeyConfig({
+          name: "fuzzy_fallback",
+          type: "weighted",
+          threshold: 0.85,
+          fields: fallbackFields
+        })
+      );
+    }
+  }
+  if (matchkeys.length === 0) {
+    return null;
+  }
+  let bestGeo = null;
+  if (geoCols.length > 0 && rows.length > 0) {
+    const maxNullRate = 0.2;
+    const geoCandidates = [];
+    for (const g of geoCols) {
+      if (nullRateOf(rows, g.name) <= maxNullRate) {
+        geoCandidates.push([g.name, distinctNonNull(rows, g.name)]);
+      }
+    }
+    if (geoCandidates.length > 0) {
+      geoCandidates.sort((a, b) => a[1] - b[1]);
+      bestGeo = geoCandidates[0][0];
+    }
+  }
+  const makeBlocking = (primaryFields, recallName, withGeo = false) => {
+    const passes = [
+      { fields: primaryFields, transforms: ["lowercase", "strip"] }
+    ];
+    if (withGeo) {
+      passes.push({ fields: primaryFields, transforms: ["lowercase", "substring:0:3"] });
+    }
+    passes.push({ fields: [recallName], transforms: ["lowercase", "soundex"] });
+    return makeBlockingConfig({
+      strategy: "multi_pass",
+      keys: [passes[0]],
+      passes,
+      maxBlockSize: 500,
+      skipOversized: true
+    });
+  };
+  let blocking = null;
+  const lastNameCols = nameCols.filter((c) => c.name.toLowerCase().includes("last"));
+  if (lastNameCols.length > 0) {
+    const bestName = lastNameCols[0].name;
+    blocking = bestGeo ? makeBlocking([bestGeo, bestName], bestName, true) : makeBlocking([bestName], bestName);
+  } else if (nameCols.length > 0) {
+    const bestName = nameCols[0].name;
+    if (bestGeo) {
+      blocking = makeBlocking([bestGeo, bestName], bestName, true);
+    } else {
+      blocking = makeBlockingConfig({
+        strategy: "static",
+        keys: [{ fields: [bestName], transforms: ["lowercase", "soundex"] }],
+        maxBlockSize: 500,
+        skipOversized: true
+      });
+    }
+  }
+  if (!blocking && bestGeo && matchkeys.length > 0) {
+    const fuzzyMks = matchkeys.filter((mk) => mk.type === "weighted");
+    const first = fuzzyMks[0];
+    if (first && first.fields.length > 0) {
+      const anchor = first.fields[0].field;
+      blocking = makeBlocking([bestGeo, anchor], anchor, true);
+    }
+  }
+  if (!blocking) {
+    blocking = makeBlockingConfig({ keys: [], autoSuggest: true });
+  }
+  return makeConfig({ matchkeys, blocking });
+}
+
+// src/core/adapters/index.ts
+function buildDefaultRegistry() {
+  const registry = new StageRegistry();
+  registry.register(LoadStage);
+  registry.register(ScanStage);
+  registry.register(TransformStage);
+  registry.register(DedupeStage);
+  return registry;
+}
+
+// src/core/pipeline.ts
+var DEFAULT_STAGE_ORDER = [
+  "goldencheck.scan",
+  "goldenflow.transform",
+  "goldenmatch.dedupe"
+];
+var Pipeline = class {
+  config;
+  registry;
+  constructor(options) {
+    this.config = options?.config;
+    this.registry = options?.registry ?? buildDefaultRegistry();
+  }
+  /** Run the pipeline on an array of rows. */
+  async run(rows, source = "<rows>") {
+    const ctx = makePipeContext({
+      df: [...rows],
+      metadata: { source, input_rows: rows.length }
+    });
+    const config = this.config ?? this.autoConfig();
+    let plan;
+    try {
+      plan = Resolver.resolve(config, this.registry);
+    } catch (e) {
+      const message = e instanceof Error ? e.message : String(e);
+      return {
+        status: PipeStatus.FAILED,
+        source,
+        inputRows: rows.length,
+        stages: {},
+        artifacts: {},
+        skipped: [],
+        errors: [`Pipeline resolution failed: ${message}`],
+        reasoning: {},
+        timing: {}
+      };
+    }
+    const runner = new Runner(this.registry);
+    const stages = await runner.run(plan, ctx);
+    return Reporter.build(ctx, stages);
+  }
+  /** Build the default check→flow→dedupe config from the available stages. */
+  autoConfig() {
+    const available = this.registry.listAll();
+    const stages = DEFAULT_STAGE_ORDER.filter((name) => name in available).map(
+      (name) => makeStageSpec(name)
+    );
+    return makePipelineConfig({ pipeline: "auto", stages });
+  }
+};
+function parseCsv(content) {
+  const records = parseRecords(content);
+  if (records.length === 0) return [];
+  const headers = records[0];
+  const rows = [];
+  for (let i = 1; i < records.length; i++) {
+    const values = records[i];
+    if (values.length === 1 && values[0] === "") continue;
+    const row = {};
+    for (let c = 0; c < headers.length; c++) {
+      row[headers[c]] = c < values.length ? values[c] : "";
+    }
+    rows.push(row);
+  }
+  return rows;
+}
+function readCsv(path) {
+  const content = readFileSync(path, "utf8");
+  return parseCsv(content);
+}
+function parseRecords(content) {
+  const records = [];
+  let field = "";
+  let record = [];
+  let inQuotes = false;
+  let i = 0;
+  const n = content.length;
+  const pushField = () => {
+    record.push(field);
+    field = "";
+  };
+  const pushRecord = () => {
+    pushField();
+    records.push(record);
+    record = [];
+  };
+  while (i < n) {
+    const ch = content[i];
+    if (inQuotes) {
+      if (ch === '"') {
+        if (i + 1 < n && content[i + 1] === '"') {
+          field += '"';
+          i += 2;
+          continue;
+        }
+        inQuotes = false;
+        i += 1;
+        continue;
+      }
+      field += ch;
+      i += 1;
+      continue;
+    }
+    if (ch === '"') {
+      inQuotes = true;
+      i += 1;
+      continue;
+    }
+    if (ch === ",") {
+      pushField();
+      i += 1;
+      continue;
+    }
+    if (ch === "\r") {
+      if (i + 1 < n && content[i + 1] === "\n") i += 1;
+      pushRecord();
+      i += 1;
+      continue;
+    }
+    if (ch === "\n") {
+      pushRecord();
+      i += 1;
+      continue;
+    }
+    field += ch;
+    i += 1;
+  }
+  if (field !== "" || record.length > 0) {
+    pushRecord();
+  }
+  return records;
+}
+async function loadConfig(path) {
+  let parse;
+  try {
+    const yamlMod = await import('yaml');
+    parse = yamlMod.parse;
+  } catch {
+    throw new Error(
+      "YAML support requires the optional `yaml` peer dependency. Run: npm install yaml"
+    );
+  }
+  let content;
+  try {
+    content = readFileSync(path, "utf8");
+  } catch {
+    throw new Error(`Config file not found: ${path}`);
+  }
+  const raw = parse(content);
+  return normalizeConfig(raw);
+}
+function normalizeConfig(raw) {
+  if (raw === null || typeof raw !== "object") {
+    throw new Error("Pipeline config must be a mapping");
+  }
+  const obj = raw;
+  if (typeof obj["pipeline"] !== "string") {
+    throw new Error("Pipeline config must have a string 'pipeline' field");
+  }
+  const rawStages = obj["stages"] ?? [];
+  if (!Array.isArray(rawStages)) {
+    throw new Error(`'stages' must be a list, got: ${typeof rawStages}`);
+  }
+  const stages = [];
+  for (const s of rawStages) {
+    if (typeof s === "string") {
+      stages.push(makeStageSpec(s));
+    } else if (s !== null && typeof s === "object") {
+      const so = s;
+      if (!("use" in so) && !("name" in so)) {
+        throw new Error(`Stage spec must have 'use' field: ${JSON.stringify(s)}`);
+      }
+      const use = so["use"] ?? so["name"];
+      stages.push(
+        makeStageSpec({
+          use,
+          ...typeof so["name"] === "string" ? { name: so["name"] } : {},
+          ...Array.isArray(so["needs"]) ? { needs: so["needs"] } : {},
+          ...typeof so["skip_if"] === "string" ? { skipIf: so["skip_if"] } : {},
+          ...typeof so["skipIf"] === "string" ? { skipIf: so["skipIf"] } : {},
+          ...so["on_error"] === "abort" || so["on_error"] === "continue" ? { onError: so["on_error"] } : {},
+          ...so["onError"] === "abort" || so["onError"] === "continue" ? { onError: so["onError"] } : {},
+          ...so["config"] !== null && typeof so["config"] === "object" ? { config: so["config"] } : {}
+        })
+      );
+    } else {
+      throw new Error(`Invalid stage spec: ${JSON.stringify(s)}`);
+    }
+  }
+  return makePipelineConfig({
+    pipeline: obj["pipeline"],
+    ...typeof obj["source"] === "string" ? { source: obj["source"] } : {},
+    ...typeof obj["output"] === "string" ? { output: obj["output"] } : {},
+    stages,
+    ...Array.isArray(obj["decisions"]) ? { decisions: obj["decisions"] } : {}
+  });
+}
+
+// src/node/run.ts
+async function run(source, options) {
+  let rows;
+  try {
+    rows = readCsv(source);
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    return {
+      status: PipeStatus.FAILED,
+      source,
+      inputRows: 0,
+      stages: {},
+      artifacts: {},
+      skipped: [],
+      errors: [`Failed to load data: ${message}`],
+      reasoning: {},
+      timing: {}
+    };
+  }
+  let config;
+  const cfgOpt = options?.config;
+  if (typeof cfgOpt === "string") {
+    config = await loadConfig(cfgOpt);
+  } else if (cfgOpt !== void 0) {
+    config = cfgOpt;
+  }
+  const pipe = new Pipeline(config !== void 0 ? { config } : {});
+  return pipe.run(rows, source);
+}
+
+// src/cli.ts
+var VERSION = "0.1.0";
+function printResult(result, verbose) {
+  process.stdout.write(`GoldenPipe: ${result.source}
+`);
+  process.stdout.write("Stage                     Status     Details\n");
+  for (const [name, sr] of Object.entries(result.stages)) {
+    const details = sr.error ?? "";
+    process.stdout.write(`${name.padEnd(25)} ${sr.status.padEnd(10)} ${details}
+`);
+  }
+  process.stdout.write(
+    `
+${result.status.toUpperCase()} | ${result.inputRows} rows | ${result.source}
+`
+  );
+  if (result.errors.length > 0) {
+    process.stdout.write("\nErrors:\n");
+    for (const e of result.errors) process.stdout.write(`  - ${e}
+`);
+  }
+  if (verbose) {
+    const reasoning = Object.entries(result.reasoning).filter(([k]) => !k.startsWith("_"));
+    if (reasoning.length > 0) {
+      process.stdout.write("\nReasoning:\n");
+      for (const [k, v] of reasoning) process.stdout.write(`  ${k}: ${v}
+`);
+    }
+    const timing = Object.entries(result.timing);
+    if (timing.length > 0) {
+      process.stdout.write("\nTiming:\n");
+      for (const [k, v] of timing) process.stdout.write(`  ${k}: ${v.toFixed(2)}s
+`);
+    }
+  }
+}
+var program = new Command().name("goldenpipe-js").description("GoldenPipe: Golden Suite orchestrator (TypeScript)").version(VERSION);
+program.command("run <source>").description("Run a pipeline on a CSV data file").option("-c, --config <path>", "Pipeline YAML config").option("-v, --verbose", "Show reasoning and timing").action(async (source, opts) => {
+  const result = await run(source, opts.config !== void 0 ? { config: opts.config } : {});
+  printResult(result, opts.verbose ?? false);
+  if (result.status === "failed") process.exitCode = 1;
+});
+program.command("stages").description("List all registered stages").action(() => {
+  const reg = buildDefaultRegistry();
+  const all = reg.listAll();
+  process.stdout.write("Registered stages\n");
+  process.stdout.write("Name                       Produces             Consumes\n");
+  for (const [name, info] of Object.entries(all).sort()) {
+    process.stdout.write(
+      `${name.padEnd(26)} ${info.produces.join(", ").padEnd(20)} ${info.consumes.join(", ")}
+`
+    );
+  }
+  process.stdout.write(`
+${Object.keys(all).length} stage(s) found
+`);
+});
+program.command("validate").description("Dry-run wiring validation without executing").requiredOption("-c, --config <path>", "Pipeline YAML config").action(async (opts) => {
+  try {
+    const cfg = await loadConfig(opts.config);
+    const reg = buildDefaultRegistry();
+    const plan = Resolver.resolve(cfg, reg);
+    process.stdout.write(`Valid -- ${plan.stages.length} stages resolved
+`);
+    for (const s of plan.stages) process.stdout.write(`  ${s.name}
+`);
+  } catch (e) {
+    if (e instanceof WiringError) {
+      process.stderr.write(`Wiring Error: ${e.message}
+`);
+    } else {
+      const message = e instanceof Error ? e.message : String(e);
+      process.stderr.write(`Error: ${message}
+`);
+    }
+    process.exitCode = 1;
+  }
+});
+program.command("init").description("Generate a starter goldenpipe.yml from registered stages").option("-d, --dir <dir>", "Directory to create config in", ".").action((opts) => {
+  const reg = buildDefaultRegistry();
+  const all = reg.listAll();
+  const lines = ["pipeline: my-pipeline", "stages:"];
+  for (const name of Object.keys(all).sort()) {
+    if (name === "load") continue;
+    lines.push(`  - ${name}`);
+  }
+  const out = join(opts.dir, "goldenpipe.yml");
+  writeFileSync(out, lines.join("\n") + "\n");
+  process.stdout.write(`Created ${out}
+`);
+});
+program.parseAsync(process.argv).catch((e) => {
+  const message = e instanceof Error ? e.message : String(e);
+  process.stderr.write(`${message}
+`);
+  process.exitCode = 1;
+});
+//# sourceMappingURL=cli.js.map
+//# sourceMappingURL=cli.js.map