ddlseed 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ddlseed contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,164 @@
-# Temporary Holding Version
+# ddlseed
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/brianmojena/ddlseed/actions/workflows/ci.yml/badge.svg)](https://github.com/brianmojena/ddlseed/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+![Node](https://img.shields.io/badge/node-%E2%89%A518-brightgreen)
+
+**Deterministic, FK-consistent test data from your SQL schema. One command, zero config, fully offline.**
+
+```
+ddlseed --schema schema.sql --rows 100 --seed 42 --format sql > seed.sql
+```
+
+## The problem it solves
+
+Populating a development database or CI pipeline with test data is a chore:
+
+- **Faker-style libraries** generate realistic values *per column* but leave it to you to
+  keep foreign keys, unique constraints and primary keys consistent across tables.
+- **Snaplet/seed** (the popular schema-aware generator) needs a *live database connection*
+  and writes into it — no way to work offline from a schema dump.
+- **Neosync** is a full platform (Docker, Temporal, Postgres) — heavy infrastructure for a seed file.
+- **Commercial tools** (Seedfast, Mockaroo, Tonic…) are paid SaaS with row limits.
+
+`ddlseed` is the missing middle ground: a single CLI that reads **just your DDL**
+(`CREATE TABLE` statements — no database connection, no server, no accounts) and emits
+**ready-to-load SQL INSERTs, JSON or CSV**, with foreign keys, primary keys, unique
+constraints and NOT NULL respected by construction. Same seed → same data, every time.
+
+## Who it's for
+
+- Backend developers who need realistic local/CI fixtures for a relational schema.
+- Teams that want reproducible seed data in code review (`--seed 42` diffs cleanly).
+- Anyone who has a `.sql` schema dump and no running database (offline, air-gapped, new laptop).
+
+## Installation
+
+Requires Node.js ≥ 18. The only runtime dependency is `@faker-js/faker` (MIT).
+
+**From source** (the package is not yet published to npm):
+
+```bash
+git clone https://github.com/brianmojena/ddlseed.git ddlseed
+cd ddlseed
+npm install
+npm run build
+node dist/cli.js --help          # run it
+npm link                         # optional: exposes `ddlseed` on your PATH
+```
+
+**Once published**, it will be simply:
+
+```bash
+npm install -g ddlseed
+# or run without installing:
+npx ddlseed --help
+```
+
+## Usage
+
+```
+ddlseed --schema <file.sql> [options]
+
+Options:
+  -s, --schema <file>     SQL DDL file with CREATE TABLE statements (required)
+  -n, --rows <n>          Rows per table (default: 50)
+      --seed <n>          Seed for deterministic output (default: 42)
+  -f, --format <fmt>      sql | json | csv | all (default: sql)
+  -o, --out <dir>         Output directory (default: stdout)
+      --dialect <d>       sqlite | postgres | mysql | auto (default: auto)
+      --ref-date <date>   Anchor date for timestamps, ISO 8601 (default: 2026-01-01)
+  -h, --help              Show help
+  -v, --version           Show version
+```
+
+### Examples
+
+```bash
+# 100 rows per table as SQL, written to ./seed (seed.sql + data.json + <table>.csv)
+ddlseed --schema schema.sql --rows 100 --seed 7 --format all --out ./seed
+
+# SQL to stdout, pipe it straight into psql / sqlite3 / mysql
+ddlseed --schema schema.sql --rows 200 | sqlite3 dev.db
+
+# JSON for a REST mock server
+ddlseed --schema schema.sql --format json > fixtures.json
+
+# CSV per table for spreadsheets / BI tools
+ddlseed --schema schema.sql --format csv --out ./csv
+```
+
+### What it understands
+
+- Dialects: **SQLite**, **PostgreSQL** and **MySQL** DDL (auto-detected, override with `--dialect`).
+- `CREATE TABLE` with column-level and table-level constraints:
+  `PRIMARY KEY` (single and composite), `FOREIGN KEY … REFERENCES` (with
+  `ON DELETE/UPDATE` actions), `UNIQUE`, `NOT NULL`, `DEFAULT`, `CHECK` (ignored),
+  `AUTO_INCREMENT` / `AUTOINCREMENT` / `SERIAL` / `GENERATED … AS IDENTITY`,
+  `ENUM('a','b')` and quoted identifiers (`"x"`, `` `x` ``, `[x]`).
+- Comments and other statements (`CREATE INDEX`, `INSERT`, …) are skipped.
+- Self-referencing tables (e.g. `parent_id REFERENCES same_table(id)`) are handled.
+
+### How values are generated
+
+Column values are chosen by a name-then-type heuristic: a column called `email`
+gets a realistic email, `first_name` a person's first name, `price` a decimal,
+`created_at` a recent timestamp; everything else falls back to its SQL type.
+UUIDs, JSON columns, ENUM choices, VARCHAR length limits and NULL probability
+(~10 % on nullable columns) are all respected. Timestamps are anchored to a fixed
+reference date so that the **same seed always produces byte-identical output**.
+
+Output tables are emitted in foreign-key order, wrapped in a transaction —
+the generated `seed.sql` loads cleanly with `PRAGMA foreign_keys = ON`.
+
+## Demo
+
+```bash
+npm install
+npm run demo
+```
+
+generates data for the example blog schema in [`examples/blog.sql`](examples/blog.sql)
+into `demo-out/` and prints a preview. Then try loading it for real:
+
+```bash
+sqlite3 test.db < examples/blog.sql   # SQLite needs JSON→TEXT: see scripts/demo.mjs
+sqlite3 test.db < demo-out/seed.sql
+sqlite3 test.db "SELECT COUNT(*) FROM posts;"
+```
+
+## Development
+
+```bash
+npm install        # install dependencies
+npm run build      # compile TypeScript to dist/
+npm test           # build + run the full test suite (vitest)
+npm run demo       # build + reproducible demo
+```
+
+The test suite (53 tests) covers the parser, dependency ordering, generator
+(FK consistency, uniqueness, determinism), writers, the CLI end-to-end, and an
+**integration test that loads the generated SQL into a real SQLite database**
+(via `node:sqlite`) and asserts zero orphan rows and zero duplicate keys.
+
+## How it compares
+
+| Tool | Works from DDL only (offline) | FK-consistent | Emits SQL/JSON/CSV files | Deterministic | Free & open source | No server |
+| --- | --- | --- | --- | --- | --- | --- |
+| **ddlseed** | ✅ | ✅ | ✅ | ✅ | ✅ MIT | ✅ |
+| faker.js / Mimesis | ❌ (column-level only) | ❌ manual | ❌ you write it | ✅ | ✅ | ✅ |
+| supabase-community/seed | ❌ needs live DB | ✅ | ❌ writes into the DB | ✅ | ✅ | ❌ |
+| shuttle-hq/synth | ❌ handwritten configs | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Neosync | ❌ | ✅ | ✅ | ✅ | ✅ | ❌ Docker+Temporal |
+| Benerator CE | ❌ JDBC + XML | ✅ | ✅ | ✅ | ⚠️ Java+XML | ⚠️ |
+| Seedfast / Mockaroo / Tonic | ⚠️ | ✅ | ✅ | ✅ | ❌ paid SaaS | ❌ |
+
+*Table reflects capabilities as verified in November 2026 — see `docs/DECISION.md` for the full research log.*
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE) — free forever, no accounts, no telemetry, no network calls.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { generateData } from './generator.js';
+import { parseSchema } from './parser.js';
+import { DdlSeedError } from './types.js';
+import { generationOrder } from './generator.js';
+import { toCsv, toCsvAll, toJson, toSql } from './writers.js';
+const VERSION = '0.1.0';
+function usage() {
+    return `ddlseed ${VERSION} — deterministic, FK-consistent test data from your SQL schema.
+
+USAGE
+  ddlseed --schema <file.sql> [options]
+
+OPTIONS
+  -s, --schema <file>     SQL DDL file with CREATE TABLE statements (required)
+  -n, --rows <n>          Rows per table (default: 50)
+      --seed <n>          Seed for deterministic output (default: 42)
+  -f, --format <fmt>      sql | json | csv | all (default: sql)
+  -o, --out <dir>         Output directory (default: stdout)
+      --dialect <d>       sqlite | postgres | mysql | auto (default: auto)
+      --ref-date <date>   Anchor date for timestamps, ISO 8601 (default: 2026-01-01)
+  -h, --help              Show this help
+  -v, --version           Show version
+
+EXAMPLES
+  ddlseed --schema schema.sql --rows 100 --seed 7 --format all --out ./seed
+  ddlseed --schema schema.sql --format sql > seed.sql
+
+Output (with --out): seed.sql, data.json, <table>.csv per table.
+Without --out: the chosen format is printed to stdout.`;
+}
+function parseArgs(argv) {
+    const args = { rows: 50, seed: 42, format: 'sql', help: false, version: false };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        const next = () => {
+            if (i + 1 >= argv.length)
+                throw new DdlSeedError(`Missing value for ${a}`);
+            return argv[++i];
+        };
+        switch (a) {
+            case '-s':
+            case '--schema':
+                args.schema = next();
+                break;
+            case '-n':
+            case '--rows': {
+                const v = Number(next());
+                if (!Number.isInteger(v) || v < 0)
+                    throw new DdlSeedError(`--rows must be a non-negative integer`);
+                args.rows = v;
+                break;
+            }
+            case '--seed': {
+                const v = Number(next());
+                if (!Number.isInteger(v))
+                    throw new DdlSeedError(`--seed must be an integer`);
+                args.seed = v;
+                break;
+            }
+            case '-f':
+            case '--format': {
+                const v = next();
+                if (!['sql', 'json', 'csv', 'all'].includes(v))
+                    throw new DdlSeedError(`--format must be sql, json, csv or all`);
+                args.format = v;
+                break;
+            }
+            case '-o':
+            case '--out':
+                args.out = next();
+                break;
+            case '--dialect': {
+                const v = next();
+                if (!['sqlite', 'postgres', 'mysql', 'auto'].includes(v))
+                    throw new DdlSeedError(`--dialect must be sqlite, postgres, mysql or auto`);
+                args.dialect = v === 'auto' ? undefined : v;
+                break;
+            }
+            case '--ref-date':
+                args.refDate = next();
+                break;
+            case '-h':
+            case '--help':
+                args.help = true;
+                break;
+            case '-v':
+            case '--version':
+                args.version = true;
+                break;
+            default: throw new DdlSeedError(`Unknown option: ${a}\n\n${usage()}`);
+        }
+    }
+    return args;
+}
+function run(args) {
+    if (args.version) {
+        process.stdout.write(`ddlseed ${VERSION}\n`);
+        return;
+    }
+    if (args.help) {
+        process.stdout.write(usage() + '\n');
+        return;
+    }
+    if (!args.schema) {
+        throw new DdlSeedError(`--schema is required.\n\n${usage()}`);
+    }
+    const sql = fs.readFileSync(args.schema, 'utf8');
+    const schema = parseSchema(sql, args.dialect);
+    if (schema.tables.length === 0) {
+        throw new DdlSeedError(`No CREATE TABLE statements found in "${args.schema}".`);
+    }
+    const data = generateData(schema, {
+        rows: args.rows,
+        seed: args.seed,
+        refDate: args.refDate,
+    });
+    if (args.out) {
+        fs.mkdirSync(args.out, { recursive: true });
+        const written = [];
+        if (args.format === 'sql' || args.format === 'all') {
+            const p = path.join(args.out, 'seed.sql');
+            fs.writeFileSync(p, toSql(schema, data, schema.dialect));
+            written.push(p);
+        }
+        if (args.format === 'json' || args.format === 'all') {
+            const p = path.join(args.out, 'data.json');
+            fs.writeFileSync(p, toJson(schema, data));
+            written.push(p);
+        }
+        if (args.format === 'csv' || args.format === 'all') {
+            for (const t of generationOrder(schema)) {
+                const p = path.join(args.out, `${t.name}.csv`);
+                fs.writeFileSync(p, toCsv(schema, data, t));
+                written.push(p);
+            }
+        }
+        process.stderr.write(`ddlseed: ${schema.tables.length} tables, ${args.rows} rows/table ->\n`);
+        for (const p of written)
+            process.stderr.write(`  ${p}\n`);
+        return;
+    }
+    // stdout output
+    if (args.format === 'sql') {
+        process.stdout.write(toSql(schema, data, schema.dialect));
+    }
+    else if (args.format === 'json') {
+        process.stdout.write(toJson(schema, data));
+    }
+    else if (args.format === 'csv') {
+        process.stdout.write(toCsvAll(schema, data));
+    }
+    else {
+        process.stdout.write(toSql(schema, data, schema.dialect));
+    }
+}
+try {
+    run(parseArgs(process.argv.slice(2)));
+}
+catch (err) {
+    const msg = err instanceof DdlSeedError
+        ? err.message
+        : err instanceof Error ? err.message : String(err);
+    process.stderr.write(`ddlseed: error: ${msg}\n`);
+    process.exit(1);
+}

package/dist/generator.d.ts

@@ -0,0 +1,18 @@
+import { Dialect, Row, Schema, TableDef } from './types.js';
+export interface GenerateOptions {
+    /** Rows per table. */
+    rows?: number;
+    /** Seed for deterministic output. Same seed => same data. */
+    seed?: number;
+    /** Anchor date for generated timestamps (determinism). Default: fixed 2026-01-01. */
+    refDate?: Date | string;
+}
+interface ResolvedFk {
+    columns: string[];
+    refTable: TableDef;
+    refColumns: string[];
+}
+export declare function validateSchema(schema: Schema): Map<TableDef, ResolvedFk[]>;
+export declare function generateData(schema: Schema, options?: GenerateOptions): Map<string, Row[]>;
+export declare function generationOrder(schema: Schema): TableDef[];
+export type { Dialect };