@snolla/data 0.0.0-stage → 1.0.7

package/dist/schema/generate.mjs

@@ -0,0 +1,282 @@
+// Canon generators (task:3820; decisions: plan:49 Q2/Q4/Q5).
+//
+// Input: the canon (schema/tables.ts) — the single description of the schema.
+// Output (committed, reviewed, and diffed by the test as a staleness guard):
+//   * schema/generated/kysely-types.ts — the Kysely `Database` types;
+//   * schema/generated/ddl.ts         — per-dialect DDL.
+//
+// Run:  node packages/data/schema/generate.mjs        (writes the artifacts)
+//       node packages/data/schema/generate.mjs --check (exit 1 when stale)
+//
+// Nothing here may embed schema knowledge of its own: the only knowledge is the
+// type mapping table below, and it is pinned by the test against plan:49 Q4.
+import { writeFile, mkdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { canonicalSchema, CANON_TYPES, isSiteScoped } from "./index.js";
+export const DIALECTS = ['postgres', 'mariadb', 'sqlite', 'mssql'];
+// SQL Server is the fourth dialect since the operator made it a cell target (task:3994):
+// bracket quoting and its own type map, nothing else in the canon changes.
+const QUOTE = { postgres: '"', mariadb: '`', sqlite: '"', mssql: ['[', ']'] };
+/** canon type -> dialect type (plan:49 Q4). */
+export const mapType = (column, dialect) => {
+    const table = {
+        uuid: { postgres: 'uuid', mariadb: 'char(36)', sqlite: 'text', mssql: 'uniqueidentifier' },
+        string: {
+            postgres: `varchar(${column.length})`,
+            mariadb: `varchar(${column.length})`,
+            sqlite: 'text',
+            mssql: `nvarchar(${column.length})`,
+        },
+        // SQL Server has no unbounded `text`: `nvarchar(max)` is its equivalent, and the
+        // old `text`/`ntext` types are deprecated (task:3994).
+        text: { postgres: 'text', mariadb: 'mediumtext', sqlite: 'text', mssql: 'nvarchar(max)' },
+        int: { postgres: 'integer', mariadb: 'int', sqlite: 'integer', mssql: 'int' },
+        bigint: { postgres: 'bigint', mariadb: 'bigint', sqlite: 'integer', mssql: 'bigint' },
+        bool: { postgres: 'boolean', mariadb: 'tinyint(1)', sqlite: 'integer', mssql: 'bit' },
+        decimal: {
+            postgres: `numeric(${column.precision},${column.scale})`,
+            mariadb: `decimal(${column.precision},${column.scale})`,
+            mssql: `decimal(${column.precision},${column.scale})`,
+            // SQLite keeps exact decimals as text: there is no decimal type, and
+            // float would lose money. Arithmetic happens in the application.
+            sqlite: 'text',
+        },
+        datetime: { postgres: 'timestamp', mariadb: 'datetime(3)', sqlite: 'text', mssql: 'datetime2(3)' },
+        date: { postgres: 'date', mariadb: 'date', sqlite: 'text', mssql: 'date' },
+        binary: { postgres: 'bytea', mariadb: 'longblob', sqlite: 'blob', mssql: 'varbinary(max)' },
+        // SQL Server has no `json` type; the canon's JSON rides as text (parsed by the codec).
+        json: { postgres: 'jsonb', mariadb: 'json', sqlite: 'text', mssql: 'nvarchar(max)' },
+        enum: { postgres: 'varchar(255)', mariadb: 'varchar(255)', sqlite: 'text', mssql: 'nvarchar(255)' },
+    }[column.type];
+    if (!table)
+        throw new Error(`canon type without a dialect mapping: ${column.type}`);
+    return table[dialect];
+};
+/** canon type -> TypeScript type. Decimals are strings: floats lose money. */
+const tsType = (column) => {
+    const base = {
+        uuid: 'string',
+        string: 'string',
+        text: 'string',
+        int: 'number',
+        bigint: 'string | number | bigint',
+        bool: 'boolean',
+        decimal: 'string',
+        datetime: 'string',
+        date: 'string',
+        binary: 'Uint8Array',
+        json: 'unknown',
+        enum: 'string',
+    }[column.type];
+    if (!base)
+        throw new Error(`canon type without a TS mapping: ${column.type}`);
+    return column.nullable === true ? `${base} | null` : base;
+};
+const q = (dialect, name) => Array.isArray(QUOTE[dialect])
+    ? `${QUOTE[dialect][0]}${name}${QUOTE[dialect][1]}`
+    : `${QUOTE[dialect]}${name}${QUOTE[dialect]}`;
+const booleanLiteral = (dialect, value) => (dialect === 'postgres' ? String(value) : value ? '1' : '0');
+/** The dialects whose DDL can carry a foreign key only as a separate `alter table`. */
+const CONSTRAINT_AFTER_TABLES = new Set(['postgres', 'mariadb', 'mssql']);
+/** Canonical default token -> dialect expression (plan:49 Q4: differences live here). */
+const canonDefault = (dialect, token) => ({
+    now: { postgres: 'now()', mariadb: 'current_timestamp(3)', sqlite: "(datetime('now'))", mssql: 'sysdatetime()' },
+    true: { postgres: 'true', mariadb: '1', sqlite: '1', mssql: '1' },
+    false: { postgres: 'false', mariadb: '0', sqlite: '0', mssql: '0' },
+}[token] ?? { postgres: token, mariadb: token, sqlite: token, mssql: token })[dialect];
+// ---------------------------------------------------------------------------
+// DDL
+// ---------------------------------------------------------------------------
+const softFkComment = (dialect, table, fk) => `-- soft fk: ${table}.${fk.columns.join(', ')} -> ${fk.ref}.${fk.refColumns.join(', ')} ` +
+    `(control-plane link, not enforced in a site database)`;
+const createTable = (dialect, table) => {
+    const lines = [];
+    lines.push(`create table ${q(dialect, table.name)} (`);
+    const parts = [];
+    for (const [name, column] of Object.entries(table.columns)) {
+        let def = `    ${q(dialect, name)} ${mapType(column, dialect)}`;
+        def += column.nullable === true ? ' null' : ' not null';
+        if (column.default !== undefined)
+            def += ` default ${canonDefault(dialect, column.default)}`;
+        // SQLite cannot add a constraint after the fact, so hard FKs are inline.
+        const inline = (table.fks ?? []).filter((fk) => !fk.soft && fk.columns.length === 1 && fk.columns[0] === name);
+        for (const fk of dialect === 'sqlite' ? inline : []) {
+            def += ` references ${q(dialect, fk.ref)} (${fk.refColumns.map((c) => q(dialect, c)).join(', ')})`;
+        }
+        parts.push(def);
+    }
+    const pk = Object.entries(table.columns).filter(([, c]) => c.pk).map(([n]) => q(dialect, n));
+    if (pk.length)
+        parts.push(`    primary key (${pk.join(', ')})`);
+    lines.push(parts.join(',\n'));
+    lines.push(');');
+    return lines.join('\n');
+};
+const createIndexes = (dialect, table) => (table.indexes ?? [])
+    .map((ix) => `create ${ix.unique ? 'unique ' : ''}index ${q(dialect, indexName(`${table.name}_${ix.columns.join('_')}_idx`))} ` +
+    `on ${q(dialect, table.name)} (${ix.columns.map((c) => q(dialect, c)).join(', ')});`)
+    .join('\n');
+const createForeignKeys = (dialect, table) => {
+    if (!CONSTRAINT_AFTER_TABLES.has(dialect))
+        return '';
+    return (table.fks ?? [])
+        .filter((fk) => !fk.soft)
+        .map((fk, i) => {
+        const name = constraintName(table.name, fk, i);
+        return (`alter table ${q(dialect, table.name)} add constraint ${q(dialect, name)} ` +
+            `foreign key (${fk.columns.map((c) => q(dialect, c)).join(', ')}) ` +
+            `references ${q(dialect, fk.ref)} (${fk.refColumns.map((c) => q(dialect, c)).join(', ')});`);
+    })
+        .join('\n');
+};
+/** Postgres refuses identifiers longer than 63 characters; it is the strictest dialect. */
+export const MAX_IDENTIFIER_LENGTH = 63;
+// FNV-1a (32 bit) in base36: a short fingerprint of the full name. Truncation
+// without it collides silently — two long names that differ only after the cut
+// become one name — while the fingerprint keeps names deterministic, so the
+// generated DDL stays diff-stable.
+const fingerprint = (value) => {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < value.length; i += 1) {
+        hash ^= value.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash.toString(36);
+};
+/**
+ * One naming rule for every generated constraint and index. `index`
+ * disambiguates repeated shapes on the same table (the second FK over the same
+ * pair) and keeps the historical suffix; a name over the limit is cut and
+ * fingerprinted instead of silently shortened.
+ */
+export const indexName = (base, index = 0) => {
+    const candidate = index === 0 ? base : `${base}_${index + 1}`;
+    if (candidate.length <= MAX_IDENTIFIER_LENGTH)
+        return candidate;
+    const suffix = `_${fingerprint(candidate)}`;
+    return `${candidate.slice(0, MAX_IDENTIFIER_LENGTH - suffix.length)}${suffix}`;
+};
+export const constraintName = (table, fk, index) => indexName(`FK_${table}_${fk.ref}_${fk.columns.join('_')}`, index);
+export const renderDdlSql = (dialect) => {
+    if (!DIALECTS.includes(dialect))
+        throw new Error(`unknown dialect: ${dialect}`);
+    const parts = [
+        `-- GENERATED from the canonical schema — do not edit; run schema/generate.mjs`,
+        `-- dialect: ${dialect} · canon version: ${canonicalSchema.version} · tables: ${canonicalSchema.tables.length}`,
+    ];
+    if (dialect === 'sqlite') {
+        parts.push('-- SQLite carries foreign keys inline; run the script with foreign_keys=off,');
+        parts.push('-- then enable the pragma once every table exists.');
+    }
+    for (const table of canonicalSchema.tables) {
+        parts.push('', createTable(dialect, table));
+        const indexes = createIndexes(dialect, table);
+        if (indexes)
+            parts.push(indexes);
+    }
+    // Constraints come after every table exists: a canon table may reference a
+    // table that sorts later, and MariaDB/Postgres refuse forward references.
+    for (const table of canonicalSchema.tables) {
+        const fks = createForeignKeys(dialect, table);
+        if (fks)
+            parts.push('', fks);
+        for (const fk of (table.fks ?? []).filter((f) => f.soft))
+            parts.push(softFkComment(dialect, table, fk));
+    }
+    parts.push('');
+    return parts.join('\n');
+};
+export const renderDdlModule = () => {
+    const body = DIALECTS.map((dialect) => `export const ${dialect}: string = ${JSON.stringify(renderDdlSql(dialect))};`).join('\n\n');
+    return [
+        '// GENERATED from the canonical schema — do not edit; run schema/generate.mjs',
+        '//',
+        '// Per-dialect DDL for the whole canon. The migration runner picks the',
+        '// dialect it is connected to (plan:49 Q5); the canon version below is the',
+        '// migration version.',
+        '',
+        `export const CANON_VERSION = ${canonicalSchema.version};`,
+        '',
+        // The dialect list comes from DIALECTS: a hand-written union here drifted
+        // once (mssql rendered, but not in the type) and tsc refused the module.
+        `export type Dialect = ${DIALECTS.map((d) => `'${d}'`).join(' | ')};`,
+        '',
+        // The record comes after the bodies: `{ postgres, ... }` reads the bindings,
+        // so a record above them is a block-scoped use before declaration.
+        body,
+        '',
+        `export const DDL: Record<Dialect, string> = { ${DIALECTS.join(', ')} };`,
+        '',
+    ].join('\n');
+};
+// ---------------------------------------------------------------------------
+// Kysely types
+// ---------------------------------------------------------------------------
+export const renderKyselyTypes = () => {
+    const out = [
+        '// GENERATED from the canonical schema — do not edit; run schema/generate.mjs',
+        '//',
+        '// Row types for Kysely plus the `Database` interface. Decimals and datetimes',
+        '// are strings (exactness first, plan:49 Q4); optional columns admit null.',
+        '',
+    ];
+    for (const table of canonicalSchema.tables) {
+        out.push(`export interface ${table.name}Row {`);
+        for (const [name, column] of Object.entries(table.columns)) {
+            out.push(`    ${name}: ${tsType(column)};`);
+        }
+        out.push('}', '');
+    }
+    out.push('export interface Database {');
+    for (const table of canonicalSchema.tables)
+        out.push(`    ${table.name}: ${table.name}Row;`);
+    out.push('}', '');
+    return out.join('\n');
+};
+export const ARTIFACTS = {
+    'ddl.ts': renderDdlModule,
+    'kysely-types.ts': renderKyselyTypes,
+};
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+const here = path.dirname(fileURLToPath(import.meta.url));
+const outDir = path.join(here, 'generated');
+export const writeAll = async () => {
+    await mkdir(outDir, { recursive: true });
+    for (const [name, render] of Object.entries(ARTIFACTS)) {
+        await writeFile(path.join(outDir, name), render(), 'utf8');
+    }
+};
+const same = (current, wanted) => (current ?? '').replace(/\r\n/g, '\n') === wanted.replace(/\r\n/g, '\n');
+const check = async () => {
+    const stale = [];
+    const targets = Object.entries(ARTIFACTS).map(([name, render]) => [path.join(outDir, name), render, name]);
+    for (const [target, render, name] of targets) {
+        let current = null;
+        try {
+            current = await readFile(target, 'utf8');
+        }
+        catch {
+            /* missing counts as stale */
+        }
+        if (!same(current, render()))
+            stale.push(name);
+    }
+    return stale;
+};
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    if (process.argv.includes('--check')) {
+        const stale = await check();
+        if (stale.length) {
+            console.error(`stale generated artifacts: ${stale.join(', ')} — run schema/generate.mjs`);
+            process.exit(1);
+        }
+        console.log('generated artifacts are up to date');
+    }
+    else {
+        await writeAll();
+        console.log(`wrote ${Object.keys(ARTIFACTS).length} artifacts`);
+    }
+}

package/dist/schema/generated/ddl.d.ts

@@ -0,0 +1,7 @@
+export declare const CANON_VERSION = 1;
+export type Dialect = 'postgres' | 'mariadb' | 'sqlite' | 'mssql';
+export declare const postgres: string;
+export declare const mariadb: string;
+export declare const sqlite: string;
+export declare const mssql: string;
+export declare const DDL: Record<Dialect, string>;