@restforgejs/platform 4.1.1 → 4.3.1

package/generators/lib/dbschema-kit/diff-reporter.js

@@ -0,0 +1,272 @@
+'use strict';
+
+/**
+ * Diff Reporter — format delta dari diff-engine menjadi output human-readable
+ * plain text atau JSON object. Reporter tidak melakukan I/O sendiri; caller
+ * yang memutuskan untuk write ke stdout atau file.
+ *
+ * Exit code semantic:
+ *   0 — no drift
+ *   1 — drift detected
+ *   2 — error (di-set oleh caller, bukan oleh reporter ini)
+ *
+ * @module lib/dbschema-kit/diff-reporter
+ */
+
+// ─────────────────────────────────────────────────────────────
+// Format helpers
+// ─────────────────────────────────────────────────────────────
+
+function formatFieldSignature(f) {
+    if (!f) return '(unknown)';
+    const parts = [];
+    if (f.type !== undefined) {
+        if (f.type === 'string' && f.length !== undefined) {
+            parts.push(`${f.type}(${f.length})`);
+        } else if (f.type === 'decimal' && f.precision !== undefined && f.scale !== undefined) {
+            parts.push(`${f.type}(${f.precision},${f.scale})`);
+        } else {
+            parts.push(String(f.type));
+        }
+    }
+    parts.push(f.nullable === false ? 'NOT NULL' : 'NULL');
+    return parts.join(' ');
+}
+
+function formatFieldLine(f) {
+    return `    - ${f.name}  (${formatFieldSignature(f)})`;
+}
+
+function formatColumns(cols) {
+    if (!Array.isArray(cols) || cols.length === 0) return '(empty)';
+    return cols.join(', ');
+}
+
+function formatFkLine(fk) {
+    if (!fk) return '    - (invalid)';
+    const refCol = fk.references ? `.${fk.references}` : '';
+    const actions = [];
+    if (fk.onDelete && fk.onDelete !== 'restrict') {
+        actions.push(`ON DELETE ${String(fk.onDelete).toUpperCase()}`);
+    }
+    if (fk.onUpdate && fk.onUpdate !== 'restrict') {
+        actions.push(`ON UPDATE ${String(fk.onUpdate).toUpperCase()}`);
+    }
+    const actionStr = actions.length > 0 ? `  [${actions.join(', ')}]` : '';
+    return `    - ${fk.localKey} -> ${fk.target}${refCol}${actionStr}`;
+}
+
+function formatFkMismatchedLine(fk) {
+    if (!fk) return '    - (invalid)';
+    const refCol = fk.references ? `.${fk.references}` : '';
+    const lines = [`    - ${fk.localKey} -> ${fk.target}${refCol}`];
+    if (Array.isArray(fk.reasons)) {
+        for (const r of fk.reasons) {
+            lines.push(`        ${r}`);
+        }
+    }
+    return lines.join('\n');
+}
+
+function formatCheckValue(value) {
+    if (Array.isArray(value)) {
+        const items = value.map((v) => (typeof v === 'string' ? `'${v}'` : String(v)));
+        return `[${items.join(', ')}]`;
+    }
+    if (typeof value === 'string') return `'${value}'`;
+    if (value === null || value === undefined) return 'null';
+    return String(value);
+}
+
+function formatCheckLine(c) {
+    if (!c) return '    - (invalid)';
+    if (c._unparsable) return `    - (unparsable) ${c.expression}`;
+    return `    - ${c.field}: ${c.op} ${formatCheckValue(c.value)}`;
+}
+
+// ─────────────────────────────────────────────────────────────
+// Section builders (human format)
+// ─────────────────────────────────────────────────────────────
+
+function buildFieldsSection(fields) {
+    const lines = ['Fields:'];
+
+    lines.push('  + Only in SDF:');
+    if (fields.onlyInSdf.length === 0) {
+        lines.push('    (none)');
+    } else {
+        for (const f of fields.onlyInSdf) lines.push(formatFieldLine(f));
+    }
+
+    lines.push('  - Only in DB:');
+    if (fields.onlyInDb.length === 0) {
+        lines.push('    (none)');
+    } else {
+        for (const f of fields.onlyInDb) lines.push(formatFieldLine(f));
+    }
+
+    lines.push('  ~ Mismatched:');
+    if (fields.mismatched.length === 0) {
+        lines.push('    (none)');
+    } else {
+        for (const m of fields.mismatched) {
+            lines.push(`    - ${m.name}`);
+            for (const r of m.reasons) {
+                lines.push(`        ${r}`);
+            }
+        }
+    }
+
+    return lines;
+}
+
+function buildPrimaryKeySection(pk) {
+    const lines = ['Primary Key:'];
+    if (pk.match) {
+        const cols = pk.sdf.length === 0 ? '(none)' : pk.sdf.join(', ');
+        lines.push(`  Match: ${cols}`);
+    } else {
+        lines.push(`  Mismatch:`);
+        lines.push(`    SDF: ${formatColumns(pk.sdf)}`);
+        lines.push(`    DB:  ${formatColumns(pk.db)}`);
+    }
+    return lines;
+}
+
+function buildCollectionSection(label, coll, formatter, mismatchedFormatter) {
+    const isEmpty = coll.onlyInSdf.length === 0 && coll.onlyInDb.length === 0 && coll.mismatched.length === 0;
+    if (isEmpty) {
+        return [`${label}: (no drift)`];
+    }
+
+    const lines = [`${label}:`];
+    lines.push('  + Only in SDF:');
+    if (coll.onlyInSdf.length === 0) {
+        lines.push('    (none)');
+    } else {
+        for (const it of coll.onlyInSdf) lines.push(formatter(it));
+    }
+    lines.push('  - Only in DB:');
+    if (coll.onlyInDb.length === 0) {
+        lines.push('    (none)');
+    } else {
+        for (const it of coll.onlyInDb) lines.push(formatter(it));
+    }
+    lines.push('  ~ Mismatched:');
+    if (coll.mismatched.length === 0) {
+        lines.push('    (none)');
+    } else {
+        const useMismatch = typeof mismatchedFormatter === 'function' ? mismatchedFormatter : formatter;
+        for (const it of coll.mismatched) lines.push(useMismatch(it));
+    }
+    return lines;
+}
+
+function formatColumnItem(item) {
+    const cols = Array.isArray(item.columns) ? item.columns.join(', ') : '(empty)';
+    return `    - ${cols}`;
+}
+
+function buildTableReport(delta, idx, total) {
+    const lines = [];
+    const banner = `Drift Report: ${delta.tableName} (${idx}/${total} table compared)`;
+    lines.push(banner);
+    lines.push('='.repeat(Math.max(banner.length, 30)));
+    lines.push('');
+
+    if (!delta.hasDrift) {
+        lines.push('No drift detected. SDF and database are in sync.');
+        return lines;
+    }
+
+    lines.push(...buildFieldsSection(delta.fields));
+    lines.push('');
+    lines.push(...buildPrimaryKeySection(delta.primaryKey));
+    lines.push('');
+    lines.push(...buildCollectionSection('Indexes', delta.indexes, formatColumnItem));
+    lines.push('');
+    lines.push(...buildCollectionSection('Uniques', delta.uniques, formatColumnItem));
+    lines.push('');
+    lines.push(...buildCollectionSection('Foreign Keys', delta.foreignKeys, formatFkLine, formatFkMismatchedLine));
+    if (delta.checks) {
+        lines.push('');
+        lines.push(...buildCollectionSection('Checks', delta.checks, formatCheckLine));
+    }
+
+    return lines;
+}
+
+// ─────────────────────────────────────────────────────────────
+// Public API: human / json / exit code
+// ─────────────────────────────────────────────────────────────
+
+function reportHuman(deltas) {
+    const arr = Array.isArray(deltas) ? deltas : [];
+    const total = arr.length;
+    const tablesWithDrift = arr.filter((d) => d && d.hasDrift).length;
+    const tablesClean = total - tablesWithDrift;
+
+    const lines = [];
+    if (total === 0) {
+        lines.push('No tables compared. Schema set is empty.');
+        lines.push('Exit code: 0');
+        return lines.join('\n');
+    }
+
+    for (let i = 0; i < arr.length; i++) {
+        const delta = arr[i];
+        lines.push(...buildTableReport(delta, i + 1, total));
+        if (i < arr.length - 1) {
+            lines.push('');
+            lines.push('');
+        }
+    }
+
+    lines.push('');
+    lines.push(`Summary: ${tablesWithDrift} table${tablesWithDrift === 1 ? '' : 's'} with drift, ${tablesClean} clean`);
+    const exitCode = tablesWithDrift > 0 ? 1 : 0;
+    lines.push(`Exit code: ${exitCode}`);
+
+    return lines.join('\n');
+}
+
+function reportJson(deltas) {
+    const arr = Array.isArray(deltas) ? deltas : [];
+    const tablesWithDrift = arr.filter((d) => d && d.hasDrift).length;
+    const tablesClean = arr.length - tablesWithDrift;
+    const exitCode = tablesWithDrift > 0 ? 1 : 0;
+
+    return {
+        version: '1.0',
+        summary: {
+            totalTables: arr.length,
+            tablesWithDrift,
+            tablesClean,
+            exitCode
+        },
+        tables: arr.map((d) => {
+            const out = {
+                tableName: d.tableName,
+                hasDrift: d.hasDrift,
+                fields: d.fields,
+                primaryKey: d.primaryKey,
+                indexes: d.indexes,
+                uniques: d.uniques,
+                foreignKeys: d.foreignKeys
+            };
+            if (d.checks) out.checks = d.checks;
+            return out;
+        })
+    };
+}
+
+function getExitCode(deltas) {
+    const arr = Array.isArray(deltas) ? deltas : [];
+    return arr.some((d) => d && d.hasDrift) ? 1 : 0;
+}
+
+module.exports = {
+    reportHuman,
+    reportJson,
+    getExitCode
+};

package/generators/lib/dbschema-kit/emitters/alter-table.js

@@ -0,0 +1,275 @@
+'use strict';
+
+/**
+ * ALTER TABLE Emitters — generate dialect-aware DDL fragments untuk apply-engine.
+ *
+ * Lingkup:
+ *   - ADD COLUMN <name> <type> [NULL|NOT NULL] [DEFAULT ...]
+ *   - DROP COLUMN <name>
+ *   - ALTER/MODIFY COLUMN <name> ... (length / nullable; type change defer)
+ *   - CREATE INDEX
+ *   - DROP INDEX (dialect-aware)
+ *   - ADD CONSTRAINT UNIQUE
+ *   - DROP CONSTRAINT
+ *
+ * Konvensi penamaan constraint/index reuse `naming.js` (generateConstraintName,
+ * deriveCompositeShortName) agar nama yang di-emit identik dengan create-table
+ * dan create-index. Output adalah string single-statement tanpa trailing
+ * semicolon (apply-executor / statement-splitter yang menangani separator).
+ *
+ * SQLite tidak mendukung ALTER COLUMN / DROP COLUMN (legacy mode). Modul ini
+ * tetap mendukung ADD COLUMN dan CREATE INDEX/DROP INDEX untuk sqlite; semua
+ * operasi MODIFY column dan DROP COLUMN harus dicegah di apply-engine sebelum
+ * sampai ke emitter.
+ *
+ * @module lib/dbschema-kit/emitters/alter-table
+ */
+
+const { generateConstraintName, deriveCompositeShortName } = require('../naming');
+
+// ─────────────────────────────────────────────────────────────
+// ADD COLUMN
+// ─────────────────────────────────────────────────────────────
+
+function emitAddColumn(tableIR, fieldName, field, dialect) {
+    if (!tableIR || typeof tableIR.tableName !== 'string') {
+        throw new Error('emitAddColumn: tableIR with tableName is required');
+    }
+    if (typeof fieldName !== 'string' || fieldName === '') {
+        throw new Error('emitAddColumn: fieldName must be a non-empty string');
+    }
+    if (!field || typeof field !== 'object') {
+        throw new Error(`emitAddColumn: field definition required for '${fieldName}'`);
+    }
+    const tableIdentifier = dialect.formatTableIdentifier(tableIR);
+    const column = dialect.quoteIdentifier(fieldName);
+    const typeFrag = dialect.mapType(field);
+    const parts = [column, typeFrag];
+    if (field.notnull === true) {
+        parts.push('NOT NULL');
+    }
+    if (field.default !== undefined && field.autoUpdate !== true) {
+        parts.push(`DEFAULT ${dialect.formatDefault(field.default)}`);
+    }
+
+    if (dialect.name === 'oracle') {
+        // Oracle membungkus column definition di dalam parentheses untuk ADD,
+        // konvensi yang juga mendukung multi-column add bila diperlukan nanti.
+        return `ALTER TABLE ${tableIdentifier} ADD (${parts.join(' ')})`;
+    }
+    return `ALTER TABLE ${tableIdentifier} ADD COLUMN ${parts.join(' ')}`;
+}
+
+// ─────────────────────────────────────────────────────────────
+// DROP COLUMN
+// ─────────────────────────────────────────────────────────────
+
+function emitDropColumn(tableIR, fieldName, dialect) {
+    if (!tableIR || typeof tableIR.tableName !== 'string') {
+        throw new Error('emitDropColumn: tableIR with tableName is required');
+    }
+    if (typeof fieldName !== 'string' || fieldName === '') {
+        throw new Error('emitDropColumn: fieldName must be a non-empty string');
+    }
+    if (dialect.name === 'sqlite') {
+        throw new Error(
+            `emitDropColumn: sqlite does not support DROP COLUMN reliably (requires table rebuild). ` +
+            `Filter DROP COLUMN operations in apply-engine before calling emitter.`
+        );
+    }
+    const tableIdentifier = dialect.formatTableIdentifier(tableIR);
+    const column = dialect.quoteIdentifier(fieldName);
+    if (dialect.name === 'oracle') {
+        return `ALTER TABLE ${tableIdentifier} DROP (${column})`;
+    }
+    return `ALTER TABLE ${tableIdentifier} DROP COLUMN ${column}`;
+}
+
+// ─────────────────────────────────────────────────────────────
+// MODIFY COLUMN (length / nullable)
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Generate ALTER COLUMN statement(s) untuk modifikasi length / nullable.
+ *
+ * Modify ini bersifat dialect-specific. Type change TIDAK di-handle (defer).
+ *
+ * @param {Object} tableIR - { tableName, schemaName? }
+ * @param {string} fieldName
+ * @param {Object} sdfField - target shape (type, length, notnull, dll.)
+ * @param {Object} options - { changeNullable: boolean, changeLength: boolean }
+ * @param {Object} dialect - dialect adapter
+ * @returns {string[]} array of ALTER statement (postgres bisa multiple,
+ *                    mysql/oracle satu statement MODIFY)
+ */
+function emitModifyColumn(tableIR, fieldName, sdfField, options, dialect) {
+    if (!tableIR || typeof tableIR.tableName !== 'string') {
+        throw new Error('emitModifyColumn: tableIR with tableName is required');
+    }
+    if (typeof fieldName !== 'string' || fieldName === '') {
+        throw new Error('emitModifyColumn: fieldName must be a non-empty string');
+    }
+    if (!sdfField || typeof sdfField !== 'object') {
+        throw new Error(`emitModifyColumn: sdfField required for '${fieldName}'`);
+    }
+    const changeNullable = options && options.changeNullable === true;
+    const changeLength = options && options.changeLength === true;
+    if (!changeNullable && !changeLength) {
+        return [];
+    }
+
+    if (dialect.name === 'sqlite') {
+        throw new Error(
+            `emitModifyColumn: sqlite does not support ALTER COLUMN. ` +
+            `Filter modify operations in apply-engine before calling emitter.`
+        );
+    }
+
+    const tableIdentifier = dialect.formatTableIdentifier(tableIR);
+    const column = dialect.quoteIdentifier(fieldName);
+
+    if (dialect.name === 'postgres') {
+        const out = [];
+        if (changeLength) {
+            const typeFrag = dialect.mapType(sdfField);
+            out.push(`ALTER TABLE ${tableIdentifier} ALTER COLUMN ${column} TYPE ${typeFrag}`);
+        }
+        if (changeNullable) {
+            if (sdfField.notnull === true) {
+                out.push(`ALTER TABLE ${tableIdentifier} ALTER COLUMN ${column} SET NOT NULL`);
+            } else {
+                out.push(`ALTER TABLE ${tableIdentifier} ALTER COLUMN ${column} DROP NOT NULL`);
+            }
+        }
+        return out;
+    }
+
+    if (dialect.name === 'mysql') {
+        const typeFrag = dialect.mapType(sdfField);
+        const parts = [column, typeFrag];
+        if (sdfField.notnull === true) parts.push('NOT NULL');
+        else parts.push('NULL');
+        return [`ALTER TABLE ${tableIdentifier} MODIFY COLUMN ${parts.join(' ')}`];
+    }
+
+    if (dialect.name === 'oracle') {
+        const typeFrag = dialect.mapType(sdfField);
+        const parts = [column, typeFrag];
+        if (sdfField.notnull === true) parts.push('NOT NULL');
+        else parts.push('NULL');
+        return [`ALTER TABLE ${tableIdentifier} MODIFY (${parts.join(' ')})`];
+    }
+
+    throw new Error(`emitModifyColumn: unsupported dialect '${dialect.name}'`);
+}
+
+// ─────────────────────────────────────────────────────────────
+// CREATE / DROP INDEX
+// ─────────────────────────────────────────────────────────────
+
+function deriveIndexName(tableName, columns, dialect) {
+    const composite = Array.isArray(columns) && columns.length > 1;
+    const suffix = composite
+        ? deriveCompositeShortName(columns, dialect.maxIdentifierLength)
+        : columns[0];
+    return generateConstraintName('idx', tableName, suffix, dialect.maxIdentifierLength);
+}
+
+function emitCreateIndex(tableIR, columns, dialect) {
+    if (!tableIR || typeof tableIR.tableName !== 'string') {
+        throw new Error('emitCreateIndex: tableIR with tableName is required');
+    }
+    if (!Array.isArray(columns) || columns.length === 0) {
+        throw new Error('emitCreateIndex: columns must be a non-empty array');
+    }
+    const tableIdentifier = dialect.formatTableIdentifier(tableIR);
+    const name = deriveIndexName(tableIR.tableName, columns, dialect);
+    const colList = columns.map((c) => dialect.quoteIdentifier(c)).join(', ');
+    return `CREATE INDEX ${dialect.quoteIdentifier(name)} ON ${tableIdentifier} (${colList})`;
+}
+
+function emitDropIndex(tableIR, columns, dialect, options) {
+    if (!tableIR || typeof tableIR.tableName !== 'string') {
+        throw new Error('emitDropIndex: tableIR with tableName is required');
+    }
+    if (!Array.isArray(columns) || columns.length === 0) {
+        throw new Error('emitDropIndex: columns must be a non-empty array');
+    }
+    const explicitName = options && typeof options.name === 'string' && options.name.length > 0
+        ? options.name
+        : null;
+    const name = explicitName || deriveIndexName(tableIR.tableName, columns, dialect);
+    const quotedName = dialect.quoteIdentifier(name);
+    const tableIdentifier = dialect.formatTableIdentifier(tableIR);
+
+    switch (dialect.name) {
+        case 'postgres':
+        case 'sqlite':
+            // PG/SQLite: DROP INDEX adalah top-level object, tidak butuh ON clause.
+            return `DROP INDEX ${quotedName}`;
+        case 'mysql':
+            // MySQL: DROP INDEX adalah operasi pada table, butuh ON.
+            return `DROP INDEX ${quotedName} ON ${tableIdentifier}`;
+        case 'oracle':
+            // Oracle: DROP INDEX adalah top-level object.
+            return `DROP INDEX ${quotedName}`;
+        default:
+            throw new Error(`emitDropIndex: unsupported dialect '${dialect.name}'`);
+    }
+}
+
+// ─────────────────────────────────────────────────────────────
+// ADD / DROP UNIQUE CONSTRAINT
+// ─────────────────────────────────────────────────────────────
+
+function deriveUniqueConstraintName(tableName, columns, dialect) {
+    const suffix = columns.length > 1
+        ? deriveCompositeShortName(columns, dialect.maxIdentifierLength)
+        : columns[0];
+    return generateConstraintName('uq', tableName, suffix, dialect.maxIdentifierLength);
+}
+
+function emitAddUnique(tableIR, columns, dialect) {
+    if (!tableIR || typeof tableIR.tableName !== 'string') {
+        throw new Error('emitAddUnique: tableIR with tableName is required');
+    }
+    if (!Array.isArray(columns) || columns.length === 0) {
+        throw new Error('emitAddUnique: columns must be a non-empty array');
+    }
+    const tableIdentifier = dialect.formatTableIdentifier(tableIR);
+    const name = deriveUniqueConstraintName(tableIR.tableName, columns, dialect);
+    const colList = columns.map((c) => dialect.quoteIdentifier(c)).join(', ');
+    return `ALTER TABLE ${tableIdentifier} ADD CONSTRAINT ${dialect.quoteIdentifier(name)} UNIQUE (${colList})`;
+}
+
+function emitDropUnique(tableIR, columns, dialect, options) {
+    if (!tableIR || typeof tableIR.tableName !== 'string') {
+        throw new Error('emitDropUnique: tableIR with tableName is required');
+    }
+    if (!Array.isArray(columns) || columns.length === 0) {
+        throw new Error('emitDropUnique: columns must be a non-empty array');
+    }
+    const explicitName = options && typeof options.name === 'string' && options.name.length > 0
+        ? options.name
+        : null;
+    const name = explicitName || deriveUniqueConstraintName(tableIR.tableName, columns, dialect);
+    const tableIdentifier = dialect.formatTableIdentifier(tableIR);
+
+    if (dialect.name === 'mysql') {
+        // MySQL menyimpan UNIQUE sebagai index, syntax DROP INDEX adalah idiomatic.
+        return `ALTER TABLE ${tableIdentifier} DROP INDEX ${dialect.quoteIdentifier(name)}`;
+    }
+    return `ALTER TABLE ${tableIdentifier} DROP CONSTRAINT ${dialect.quoteIdentifier(name)}`;
+}
+
+module.exports = {
+    emitAddColumn,
+    emitDropColumn,
+    emitModifyColumn,
+    emitCreateIndex,
+    emitDropIndex,
+    emitAddUnique,
+    emitDropUnique,
+    deriveIndexName,
+    deriveUniqueConstraintName
+};