@vijaypjavvadi/bdd2pw 3.10.0 → 4.0.0

package/dist/data/dataLoader.js

@@ -0,0 +1,339 @@
+"use strict";
+/**
+ * v4.0.0 — DataLoader.
+ *
+ * Reads CSV / JSON / XLSX into a normalized `DataRow[]` for injection
+ * into Scenario Outline Examples tables.
+ *
+ * Normalization contract:
+ *   - All values are coerced to strings (Gherkin Examples tables are
+ *     always string-typed; the test code does the parsing).
+ *   - Headers are trimmed; empty headers are rejected up-front so the
+ *     placeholder-to-column matching downstream is deterministic.
+ *   - Empty rows (all-blank cells) are dropped silently — they're
+ *     a frequent artifact of hand-edited CSVs.
+ *
+ * Format detection is by file extension. .xlsx loading is lazy via
+ * the `xlsx` optional dep — if missing, the user gets a clear
+ * `npm install xlsx` error instead of a module-resolution crash.
+ *
+ * Error model: every loader function throws `DataLoaderError` with
+ * a human-readable message. The orchestrator in `scaffold()` catches
+ * this and surfaces it as a `ReviewItem` so the failure shows up in
+ * BDD_REVIEW.md alongside other diagnostics — not just on stderr.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataLoaderError = void 0;
+exports.loadDataFile = loadDataFile;
+exports.parseCsv = parseCsv;
+exports.parseJson = parseJson;
+exports.parseXlsx = parseXlsx;
+exports.validateColumnsForPlaceholders = validateColumnsForPlaceholders;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+class DataLoaderError extends Error {
+    constructor(message, file) {
+        super(message);
+        this.file = file;
+        this.name = "DataLoaderError";
+    }
+}
+exports.DataLoaderError = DataLoaderError;
+/**
+ * Entry point. Routes by extension to the right parser.
+ *
+ * @param filePath  Absolute or relative path to a .csv / .json / .xlsx file.
+ * @returns         Array of rows, each a string-keyed dict.
+ * @throws DataLoaderError on any read / parse / shape error.
+ */
+function loadDataFile(filePath) {
+    const abs = path.resolve(filePath);
+    if (!fs.existsSync(abs)) {
+        throw new DataLoaderError(`Data file not found: ${filePath}`, filePath);
+    }
+    const ext = path.extname(abs).toLowerCase();
+    switch (ext) {
+        case ".csv":
+            return parseCsv(fs.readFileSync(abs, "utf-8"), filePath);
+        case ".json":
+            return parseJson(fs.readFileSync(abs, "utf-8"), filePath);
+        case ".xlsx":
+        case ".xls":
+            return parseXlsx(abs, filePath);
+        default:
+            throw new DataLoaderError(`Unsupported data file extension "${ext}". Supported: .csv, .json, .xlsx`, filePath);
+    }
+}
+/**
+ * CSV parser — RFC 4180 compliant for the practical subset:
+ *   - Quoted fields with embedded commas
+ *   - Quoted fields with embedded newlines
+ *   - Escaped quotes (`""` inside a quoted field)
+ *   - Mixed CRLF / LF line endings
+ *
+ * Does NOT delegate to papaparse — keeping this dependency-free since
+ * the format is small enough to handle inline and we want bdd2pw to
+ * scaffold without an `npm install` step on the user's machine.
+ */
+function parseCsv(text, fileLabel) {
+    // Strip UTF-8 BOM if present. PowerShell's `Out-File -Encoding utf8`
+    // adds one by default, as do several Windows editors. Without this
+    // strip, the first header gets a U+FEFF prefix and downstream column
+    // matching silently fails.
+    if (text.charCodeAt(0) === 0xfeff)
+        text = text.slice(1);
+    // Normalize line endings, drop a trailing newline if present.
+    const normalized = text.replace(/\r\n?/g, "\n").replace(/\n$/, "");
+    if (normalized.length === 0) {
+        throw new DataLoaderError("CSV file is empty", fileLabel);
+    }
+    const lines = [];
+    let current = [];
+    let field = "";
+    let inQuotes = false;
+    let i = 0;
+    while (i < normalized.length) {
+        const c = normalized[i];
+        if (inQuotes) {
+            if (c === '"') {
+                if (normalized[i + 1] === '"') {
+                    field += '"';
+                    i += 2;
+                    continue;
+                }
+                inQuotes = false;
+                i += 1;
+                continue;
+            }
+            field += c;
+            i += 1;
+        }
+        else {
+            if (c === '"') {
+                inQuotes = true;
+                i += 1;
+            }
+            else if (c === ",") {
+                current.push(field);
+                field = "";
+                i += 1;
+            }
+            else if (c === "\n") {
+                current.push(field);
+                field = "";
+                lines.push(current);
+                current = [];
+                i += 1;
+            }
+            else {
+                field += c;
+                i += 1;
+            }
+        }
+    }
+    // Flush last field + last row.
+    current.push(field);
+    lines.push(current);
+    if (lines.length < 2) {
+        throw new DataLoaderError("CSV must have at least a header row and one data row", fileLabel);
+    }
+    const headers = lines[0].map((h) => h.trim());
+    validateHeaders(headers, fileLabel);
+    const rows = [];
+    for (let r = 1; r < lines.length; r++) {
+        const cells = lines[r];
+        if (isBlankRow(cells))
+            continue;
+        const row = {};
+        for (let c = 0; c < headers.length; c++) {
+            row[headers[c]] = (cells[c] ?? "").trim();
+        }
+        rows.push(row);
+    }
+    if (rows.length === 0) {
+        throw new DataLoaderError("CSV had a header row but no non-empty data rows", fileLabel);
+    }
+    return rows;
+}
+/**
+ * JSON parser — accepts either:
+ *   1. Array of objects: `[{a:1,b:2}, {a:3,b:4}]` — most natural shape.
+ *   2. Object with `rows`: `{rows: [{...}, {...}]}` — useful for files
+ *      that also carry metadata (generator seed, source URL, etc).
+ *
+ * Numbers and booleans are stringified for Gherkin Examples compatibility.
+ * Null values become empty strings.
+ */
+function parseJson(text, fileLabel) {
+    // Strip UTF-8 BOM (see parseCsv for rationale).
+    if (text.charCodeAt(0) === 0xfeff)
+        text = text.slice(1);
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new DataLoaderError(`JSON parse error: ${msg}`, fileLabel);
+    }
+    let raw;
+    if (Array.isArray(parsed)) {
+        raw = parsed;
+    }
+    else if (parsed &&
+        typeof parsed === "object" &&
+        Array.isArray(parsed.rows)) {
+        raw = parsed.rows;
+    }
+    else {
+        throw new DataLoaderError('JSON must be an array of objects OR an object with a "rows" array', fileLabel);
+    }
+    if (raw.length === 0) {
+        throw new DataLoaderError("JSON contained zero rows", fileLabel);
+    }
+    const rows = [];
+    let headersSeen = null;
+    for (const item of raw) {
+        if (!item || typeof item !== "object" || Array.isArray(item)) {
+            throw new DataLoaderError(`Every JSON row must be a plain object; got: ${JSON.stringify(item)?.slice(0, 80)}`, fileLabel);
+        }
+        const obj = item;
+        const row = {};
+        for (const [k, v] of Object.entries(obj)) {
+            row[k] = v === null || v === undefined ? "" : String(v);
+        }
+        if (!headersSeen) {
+            headersSeen = new Set(Object.keys(row));
+            validateHeaders(Array.from(headersSeen), fileLabel);
+        }
+        rows.push(row);
+    }
+    return rows;
+}
+/**
+ * XLSX parser — uses the optional `xlsx` dep. Reads the FIRST sheet
+ * only; users with multi-sheet workbooks should export the sheet they
+ * want to CSV.
+ *
+ * Lazy-loaded so users who never use XLSX don't need the dep installed.
+ */
+function parseXlsx(absPath, fileLabel) {
+    let xlsx;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        xlsx = require("xlsx");
+    }
+    catch {
+        throw new DataLoaderError("xlsx package not installed. Run: npm install xlsx", fileLabel);
+    }
+    const wb = xlsx.readFile(absPath);
+    const firstSheetName = wb.SheetNames[0];
+    if (!firstSheetName) {
+        throw new DataLoaderError("XLSX has no sheets", fileLabel);
+    }
+    const sheet = wb.Sheets[firstSheetName];
+    // sheet_to_json with header:1 returns array of arrays — we then
+    // promote first row to headers ourselves so the validation flow
+    // matches the CSV path exactly.
+    const aoa = xlsx.utils.sheet_to_json(sheet, {
+        header: 1,
+        defval: "",
+        blankrows: false,
+        raw: false,
+    });
+    if (aoa.length < 2) {
+        throw new DataLoaderError("XLSX must have at least a header row and one data row", fileLabel);
+    }
+    const headers = aoa[0].map((h) => String(h ?? "").trim());
+    validateHeaders(headers, fileLabel);
+    const rows = [];
+    for (let r = 1; r < aoa.length; r++) {
+        const cells = aoa[r];
+        if (isBlankRow(cells.map((c) => String(c ?? ""))))
+            continue;
+        const row = {};
+        for (let c = 0; c < headers.length; c++) {
+            row[headers[c]] = String(cells[c] ?? "").trim();
+        }
+        rows.push(row);
+    }
+    if (rows.length === 0) {
+        throw new DataLoaderError("XLSX had a header row but no non-empty data rows", fileLabel);
+    }
+    return rows;
+}
+// --- helpers ----------------------------------------------------------------
+function validateHeaders(headers, fileLabel) {
+    if (headers.length === 0) {
+        throw new DataLoaderError("No headers found", fileLabel);
+    }
+    const blanks = headers
+        .map((h, i) => (h.length === 0 ? i : -1))
+        .filter((i) => i >= 0);
+    if (blanks.length > 0) {
+        throw new DataLoaderError(`Header row has blank column(s) at index: ${blanks.join(", ")}`, fileLabel);
+    }
+    const seen = new Set();
+    const dupes = [];
+    for (const h of headers) {
+        if (seen.has(h))
+            dupes.push(h);
+        seen.add(h);
+    }
+    if (dupes.length > 0) {
+        throw new DataLoaderError(`Duplicate header(s): ${[...new Set(dupes)].join(", ")}`, fileLabel);
+    }
+}
+function isBlankRow(cells) {
+    return cells.every((c) => (c ?? "").toString().trim() === "");
+}
+/**
+ * Validates that the loaded data rows have every column the Scenario
+ * Outline placeholders reference. Returns the list of missing column
+ * names; empty array means OK.
+ *
+ * Called by the scaffold orchestrator after parsing the .feature file.
+ * If anything is missing, the orchestrator surfaces it as a
+ * `ReviewItem` and skips Examples injection for that scenario rather
+ * than producing a broken spec.
+ */
+function validateColumnsForPlaceholders(rows, placeholders) {
+    if (rows.length === 0)
+        return placeholders;
+    const presentColumns = new Set(Object.keys(rows[0]));
+    return placeholders.filter((p) => !presentColumns.has(p));
+}
+//# sourceMappingURL=dataLoader.js.map

package/dist/data/dataLoader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataLoader.js","sourceRoot":"","sources":["../../src/data/dataLoader.ts"],"names":[],"mappings":"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"}

package/dist/data/examplesInjector.d.ts

@@ -0,0 +1,64 @@
+/**
+ * v4.0.0 — ExamplesInjector.
+ *
+ * Mutates a parsed `FeatureIR` in place by replacing the `examples`
+ * array on every Scenario Outline with externally-sourced rows
+ * (from a CSV/JSON/XLSX file via DataLoader, or from a synthetic
+ * generator via SynthGenerator).
+ *
+ * Design decisions (locked in during v4.0.0 planning):
+ *
+ * 1. External rows OVERRIDE inline Examples entirely. Inline Examples
+ *    in the .feature file become the no-data fallback. When --data is
+ *    passed, every Scenario Outline gets its examples swapped.
+ *
+ * 2. Scenarios without Outline syntax (no <placeholder>) are skipped.
+ *    A vanilla Scenario doesn't care about data injection.
+ *
+ * 3. If a scenario's placeholders reference columns NOT present in
+ *    the data, that scenario is LEFT ALONE (keeps inline Examples)
+ *    and the gap is logged as a `ReviewItem` so BDD_REVIEW.md surfaces
+ *    the mismatch. Partial column overrides are not supported on
+ *    purpose — they produce confusing test output.
+ *
+ * 4. On synth-generator failure (LLM down, schema invalid, Faker
+ *    missing), we leave inline Examples in place and surface a
+ *    `ReviewItem` warning. Same graceful-degradation philosophy as
+ *    the LLM-fallback failure mode.
+ */
+import type { FeatureIR, ReviewItem, ScenarioIR } from "../types";
+import type { DataRow } from "./dataLoader";
+/**
+ * Discover the placeholder names referenced anywhere in a scenario's
+ * step text. Gherkin syntax: `<name>` substitutes a value from the
+ * row keyed by `name`.
+ *
+ * Returns a deduped, sorted list. Empty list = vanilla Scenario, not
+ * an Outline.
+ */
+export declare function extractPlaceholders(scenario: ScenarioIR): string[];
+/**
+ * Inject `rows` into every Scenario Outline of `feature`. Returns
+ * a report describing what was swapped and what was skipped (so the
+ * caller can emit `ReviewItem`s and pino logs).
+ *
+ * Mutates `feature` in place — the caller passes the already-parsed
+ * IR and gets back a mutation summary.
+ */
+export interface InjectionReport {
+    totalScenarios: number;
+    swappedScenarios: number;
+    skippedScenarios: Array<{
+        name: string;
+        reason: string;
+    }>;
+    rowsPerSwap: number;
+}
+export declare function injectExamples(feature: FeatureIR, rows: DataRow[]): InjectionReport;
+/**
+ * Convert an `InjectionReport` into `ReviewItem`s ready to push onto
+ * the scaffold's review queue. One info line per swap, one warning
+ * per skip whose reason indicates a real misconfiguration (missing
+ * columns) — skips for "vanilla Scenario" or "zero rows" are info-only.
+ */
+export declare function reportToReviewItems(report: InjectionReport, source: string): ReviewItem[];

package/dist/data/examplesInjector.js

@@ -0,0 +1,149 @@
+"use strict";
+/**
+ * v4.0.0 — ExamplesInjector.
+ *
+ * Mutates a parsed `FeatureIR` in place by replacing the `examples`
+ * array on every Scenario Outline with externally-sourced rows
+ * (from a CSV/JSON/XLSX file via DataLoader, or from a synthetic
+ * generator via SynthGenerator).
+ *
+ * Design decisions (locked in during v4.0.0 planning):
+ *
+ * 1. External rows OVERRIDE inline Examples entirely. Inline Examples
+ *    in the .feature file become the no-data fallback. When --data is
+ *    passed, every Scenario Outline gets its examples swapped.
+ *
+ * 2. Scenarios without Outline syntax (no <placeholder>) are skipped.
+ *    A vanilla Scenario doesn't care about data injection.
+ *
+ * 3. If a scenario's placeholders reference columns NOT present in
+ *    the data, that scenario is LEFT ALONE (keeps inline Examples)
+ *    and the gap is logged as a `ReviewItem` so BDD_REVIEW.md surfaces
+ *    the mismatch. Partial column overrides are not supported on
+ *    purpose — they produce confusing test output.
+ *
+ * 4. On synth-generator failure (LLM down, schema invalid, Faker
+ *    missing), we leave inline Examples in place and surface a
+ *    `ReviewItem` warning. Same graceful-degradation philosophy as
+ *    the LLM-fallback failure mode.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractPlaceholders = extractPlaceholders;
+exports.injectExamples = injectExamples;
+exports.reportToReviewItems = reportToReviewItems;
+/**
+ * Discover the placeholder names referenced anywhere in a scenario's
+ * step text. Gherkin syntax: `<name>` substitutes a value from the
+ * row keyed by `name`.
+ *
+ * Returns a deduped, sorted list. Empty list = vanilla Scenario, not
+ * an Outline.
+ */
+function extractPlaceholders(scenario) {
+    const found = new Set();
+    const re = /<([A-Za-z_][\w-]*)>/g;
+    for (const step of scenario.steps) {
+        let m;
+        while ((m = re.exec(step.text)) !== null)
+            found.add(m[1]);
+        // Also scan doc-string and data-table arguments.
+        if (typeof step.argument === "string") {
+            while ((m = re.exec(step.argument)) !== null)
+                found.add(m[1]);
+        }
+        else if (Array.isArray(step.argument)) {
+            for (const row of step.argument) {
+                for (const cell of row) {
+                    while ((m = re.exec(cell)) !== null)
+                        found.add(m[1]);
+                }
+            }
+        }
+    }
+    // Also walk the existing examples table headers, since some
+    // scenarios reference a placeholder only via the row title and not
+    // in step text. (Rare, but legal Gherkin.)
+    if (scenario.examples && scenario.examples.length > 0) {
+        for (const k of Object.keys(scenario.examples[0])) {
+            // Headers don't need a `< >` wrapper in the parsed IR — we
+            // include them so column matching is symmetric with whatever
+            // the .feature file declared.
+            found.add(k);
+        }
+    }
+    return Array.from(found).sort();
+}
+function injectExamples(feature, rows) {
+    const report = {
+        totalScenarios: feature.scenarios.length,
+        swappedScenarios: 0,
+        skippedScenarios: [],
+        rowsPerSwap: rows.length,
+    };
+    if (rows.length === 0) {
+        // Nothing to inject — leave inline Examples untouched.
+        for (const s of feature.scenarios) {
+            report.skippedScenarios.push({
+                name: s.name,
+                reason: "data file had zero rows",
+            });
+        }
+        return report;
+    }
+    const dataColumns = new Set(Object.keys(rows[0]));
+    for (const scenario of feature.scenarios) {
+        const placeholders = extractPlaceholders(scenario);
+        if (placeholders.length === 0) {
+            // Vanilla Scenario — no placeholders, no injection needed.
+            report.skippedScenarios.push({
+                name: scenario.name,
+                reason: "vanilla Scenario (no <placeholders>)",
+            });
+            continue;
+        }
+        const missing = placeholders.filter((p) => !dataColumns.has(p));
+        if (missing.length > 0) {
+            report.skippedScenarios.push({
+                name: scenario.name,
+                reason: `data file is missing column(s): ${missing.join(", ")}`,
+            });
+            continue;
+        }
+        // Swap. Keep only the columns the scenario actually references —
+        // extra columns in the data file are silently dropped per
+        // scenario, so a single 50-column data file can feed many narrow
+        // scenarios without each one pulling in noise.
+        scenario.examples = rows.map((row) => {
+            const filtered = {};
+            for (const p of placeholders)
+                filtered[p] = row[p];
+            return filtered;
+        });
+        report.swappedScenarios += 1;
+    }
+    return report;
+}
+/**
+ * Convert an `InjectionReport` into `ReviewItem`s ready to push onto
+ * the scaffold's review queue. One info line per swap, one warning
+ * per skip whose reason indicates a real misconfiguration (missing
+ * columns) — skips for "vanilla Scenario" or "zero rows" are info-only.
+ */
+function reportToReviewItems(report, source) {
+    const items = [];
+    if (report.swappedScenarios > 0) {
+        items.push({
+            severity: "info",
+            message: `Data injection from ${source}: swapped Examples in ${report.swappedScenarios}/${report.totalScenarios} scenario(s), ${report.rowsPerSwap} rows each.`,
+        });
+    }
+    for (const skip of report.skippedScenarios) {
+        const isMisconfig = skip.reason.startsWith("data file is missing");
+        items.push({
+            severity: isMisconfig ? "warn" : "info",
+            message: `Data injection skipped scenario "${skip.name}": ${skip.reason}`,
+        });
+    }
+    return items;
+}
+//# sourceMappingURL=examplesInjector.js.map

package/dist/data/examplesInjector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"examplesInjector.js","sourceRoot":"","sources":["../../src/data/examplesInjector.ts"],"names":[],"mappings":"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"}

package/dist/data/synthGenerator.d.ts

@@ -0,0 +1,71 @@
+/**
+ * v4.0.0 — Synthetic data generator.
+ *
+ * Reads a schema like:
+ *
+ *   {
+ *     "email":       "faker.internet.email",
+ *     "password":    "faker.internet.password",
+ *     "url_fragment": "inventory.html",                  // literal
+ *     "claim_desc":  "llm:auto insurance claim, one sentence"
+ *   }
+ *
+ * Produces N `DataRow`s. Each row's fields are filled by routing the
+ * source string:
+ *
+ *   - "faker.X.Y[.Z]..."  → dynamic dotted-path lookup on faker, called
+ *                            with no args. Standard faker fields cover
+ *                            >95% of test data needs.
+ *   - "llm:<prompt>"      → ONE batched LLM call generates an array of
+ *                            N values for the whole column. Cost-optimal:
+ *                            three LLM-driven fields = three batched
+ *                            calls regardless of row count.
+ *   - anything else       → literal string, same value in every row.
+ *
+ * Determinism: faker is seeded with `opts.seed` (default 42). Same
+ * seed + same schema + same row count = byte-identical output across
+ * runs. LLM fields are NOT deterministic in the same way (temperature
+ * is fixed at 0 but provider sampling has residual nondeterminism),
+ * which is intentional — LLM-generated domain data should look
+ * varied each time you regenerate.
+ *
+ * Why batched LLM calls per column instead of one big call for the
+ * whole table: the prompt stays simple ("generate N car insurance
+ * claim descriptions"), the response stays a flat JSON array (easy
+ * to parse), and a column failure doesn't poison the other columns.
+ */
+import type { DataRow } from "./dataLoader";
+import type { LLMClient } from "../llm/types";
+export interface SynthSchema {
+    /** field name → source spec. See module doc for syntax. */
+    [columnName: string]: string;
+}
+export interface SynthOptions {
+    /** How many rows to generate. */
+    rows: number;
+    /** Faker RNG seed for reproducibility. Default 42. */
+    seed?: number;
+    /**
+     * LLM client to use for "llm:..." fields. Optional — if a schema
+     * has no LLM fields you can omit this. If a schema HAS LLM fields
+     * and this is undefined, those fields will be filled with the
+     * source-string literal as a fallback (visible in output so the
+     * user notices the gap).
+     */
+    llm?: LLMClient;
+    /** Optional schema-relative model override for LLM calls. */
+    llmModel?: string;
+}
+export declare class SynthGeneratorError extends Error {
+    constructor(message: string);
+}
+/**
+ * Generate N rows. Returns `DataRow[]` with the same shape as
+ * `loadDataFile` so downstream Examples injection works identically.
+ */
+export declare function generateSyntheticRows(schema: SynthSchema, opts: SynthOptions): Promise<DataRow[]>;
+/**
+ * Convenience: load a schema JSON from disk and validate it has at
+ * least one column. Throws SynthGeneratorError on any read/parse error.
+ */
+export declare function loadSchema(schemaPath: string): SynthSchema;