@restforgejs/platform 4.1.1 → 4.3.1

package/generators/lib/payload/schema-diff.js

@@ -0,0 +1,277 @@
+'use strict';
+
+/**
+ * Schema Diff - Shared payload-vs-database comparison
+ *
+ * Module ini ekstraksi logic dari `SchemaValidator` di payload-runner.js untuk
+ * dipakai bersama oleh `endpoint create` (validasi pre-codegen) tanpa mengikat
+ * caller ke seluruh ergonomi `payload diff` command (mis. summary console output
+ * yang fokus ke batch validation).
+ *
+ * Audit-column-awareness:
+ *   Default behavior `runtime` adalah inject 4 kolom audit (`created_at`,
+ *   `created_by`, `updated_at`, `updated_by`) ke INSERT/UPDATE saat
+ *   `payload.auditColumns` tidak di-set `false`/`null`. Fungsi ini meng-compute
+ *   effective field list (eksplisit + audit) dan men-flag kolom audit yang
+ *   *required* tapi tidak ada di database secara eksplisit, sehingga error
+ *   runtime "column does not exist" dapat di-detect saat generate-time.
+ *
+ * @module lib/payload/schema-diff
+ */
+
+const { resolveEffectiveFieldList, resolveAuditColumnNames, DEFAULT_AUDIT_COLUMNS } = require('../utils/audit-columns');
+
+const DEFAULT_EXCLUDED_COLUMNS = DEFAULT_AUDIT_COLUMNS;
+
+/**
+ * Normalisasi tipe dari fieldValidation payload ke kategori yang sama dengan
+ * `normalizeDatabaseType`. Dipakai untuk men-detect type drift antara payload
+ * dan database.
+ *
+ * @param {Object} validation - Entry dari payload.fieldValidation
+ * @returns {string|null}
+ */
+function normalizePayloadValidationType(validation) {
+    if (!validation) return null;
+    const t = (validation.type || '').toLowerCase();
+    switch (t) {
+        case 'uuid': return 'uuid';
+        case 'integer': return 'integer';
+        case 'number': return 'numeric';
+        case 'boolean': return 'boolean';
+        case 'date': return 'date';
+        case 'datetime': return 'timestamp';
+        case 'string': return 'varchar';
+        case 'json':
+        case 'array': return 'json';
+        default: return t || null;
+    }
+}
+
+/**
+ * Normalisasi tipe data database ke kategori umum untuk perbandingan
+ * (mirror dari SchemaValidator.normalizeType di payload-runner.js).
+ *
+ * @param {string} dataType
+ * @param {string} udtName
+ * @param {Object} col
+ * @returns {string}
+ */
+function normalizeDatabaseType(dataType, udtName, col) {
+    const dt = (dataType || '').toLowerCase();
+    const udt = (udtName || '').toLowerCase();
+
+    if (dt === 'uuid' || udt === 'uuid') return 'uuid';
+    if (dt === 'boolean' || udt === 'bool') return 'boolean';
+
+    if (['integer', 'bigint', 'smallint', 'serial', 'bigserial', 'smallserial',
+         'int', 'tinyint', 'mediumint'].includes(dt) ||
+        ['int4', 'int8', 'int2', 'serial4', 'serial8', 'serial2'].includes(udt)) {
+        return 'integer';
+    }
+
+    if (['numeric', 'decimal', 'real', 'double precision', 'float', 'double'].includes(dt) ||
+        ['numeric', 'float4', 'float8'].includes(udt)) {
+        return 'numeric';
+    }
+
+    if (['character varying', 'varchar', 'varchar2', 'nvarchar2', 'nvarchar'].includes(dt)) return 'varchar';
+    if (['text', 'clob', 'nclob', 'longtext', 'mediumtext', 'tinytext'].includes(dt)) return 'text';
+    if (['char', 'character', 'nchar'].includes(dt)) return 'char';
+
+    if (dt === 'date') return 'date';
+    if (dt === 'datetime') return 'timestamp';
+    if (dt.startsWith('timestamp')) return 'timestamp';
+    if (dt.startsWith('time')) return 'time';
+
+    if (['json', 'jsonb'].includes(dt) || ['json', 'jsonb'].includes(udt)) return 'json';
+
+    return dt || 'unknown';
+}
+
+/**
+ * Bandingkan satu payload dengan schema database aktual.
+ *
+ * Mode strict ini audit-column-aware:
+ *   - tidak men-skip kolom audit default dari sisi "added" (kolom audit yang
+ *     di-required oleh payload tapi tidak ada di database dilaporkan sebagai
+ *     `auditMissing`).
+ *   - compute removed = field di payload (eksplisit) yang tidak ada di database
+ *   - compute typeChanges = field yang ada di payload + database tapi tipenya
+ *     beda (pakai `fieldValidation` di payload sebagai source of truth)
+ *
+ * Dipakai bersama oleh endpoint create, payload validate, payload diff, dan
+ * payload sync sebagai source of truth tunggal untuk drift detection.
+ *
+ * @param {Object} payload - Processed payload object
+ * @param {Object} db - DatabaseIntrospector terkoneksi
+ * @returns {Promise<{
+ *   tableName: string,
+ *   status: 'ok' | 'drift' | 'error',
+ *   removed: Array<{ column: string, source: 'payload' | 'audit' }>,
+ *   added: Array<{ column: string, type: string, nullable: boolean }>,
+ *   typeChanges: Array<{ column: string, payloadType: string, databaseType: string }>,
+ *   auditMissing: string[],
+ *   summary: string
+ * }>}
+ */
+async function compareSchemaStrict(payload, db) {
+    const tableName = payload.tableName;
+    const result = {
+        tableName,
+        status: 'ok',
+        removed: [],
+        added: [],
+        typeChanges: [],
+        auditMissing: [],
+        summary: ''
+    };
+
+    const dbColumns = await db.getDetailedColumnInfo(tableName);
+    if (!Array.isArray(dbColumns) || dbColumns.length === 0) {
+        result.status = 'error';
+        result.summary = `Table "${tableName}" not found in database`;
+        return result;
+    }
+
+    const dbColumnSet = new Set(dbColumns.map(c => c.column_name));
+    const dbColumnList = dbColumns.map(c => c.column_name);
+    const dbColumnMap = {};
+    for (const col of dbColumns) {
+        dbColumnMap[col.column_name] = col;
+    }
+
+    const { explicit, audit } = resolveEffectiveFieldList(payload);
+
+    const explicitSet = new Set(explicit);
+    for (const field of explicit) {
+        if (!dbColumnSet.has(field)) {
+            result.removed.push({ column: field, source: 'payload' });
+        }
+    }
+
+    for (const auditCol of audit) {
+        if (!dbColumnSet.has(auditCol)) {
+            result.auditMissing.push(auditCol);
+        }
+    }
+
+    for (const dbCol of dbColumns) {
+        const name = dbCol.column_name;
+        if (explicitSet.has(name)) continue;
+        if (DEFAULT_EXCLUDED_COLUMNS.includes(name)) continue;
+        if (audit.includes(name)) continue;
+        result.added.push({
+            column: name,
+            type: normalizeDatabaseType(dbCol.data_type, dbCol.udt_name, dbCol),
+            nullable: dbCol.is_nullable === 'YES'
+        });
+    }
+
+    // Type drift: hanya untuk field yang ada di kedua sisi DAN punya entry
+    // di payload.fieldValidation. Tanpa fieldValidation, type drift tidak bisa
+    // di-detect (payload tidak men-claim tipe spesifik).
+    const validationMap = {};
+    if (Array.isArray(payload.fieldValidation)) {
+        for (const fv of payload.fieldValidation) {
+            if (fv && fv.name) validationMap[fv.name] = fv;
+        }
+    }
+    for (const field of explicit) {
+        const dbCol = dbColumnMap[field];
+        if (!dbCol) continue;
+        const validation = validationMap[field];
+        if (!validation) continue;
+
+        const dbType = normalizeDatabaseType(dbCol.data_type, dbCol.udt_name, dbCol);
+        const payloadType = normalizePayloadValidationType(validation);
+        if (!payloadType) continue;
+
+        if (dbType !== payloadType) {
+            result.typeChanges.push({
+                column: field,
+                payloadType,
+                databaseType: dbType
+            });
+        }
+    }
+
+    const driftCount = result.removed.length + result.added.length
+        + result.auditMissing.length + result.typeChanges.length;
+    if (driftCount > 0) {
+        result.status = 'drift';
+        const parts = [];
+        if (result.removed.length > 0) parts.push(`${result.removed.length} payload field(s) missing from database`);
+        if (result.typeChanges.length > 0) parts.push(`${result.typeChanges.length} type change(s)`);
+        if (result.added.length > 0) parts.push(`${result.added.length} new database column(s) not in payload`);
+        if (result.auditMissing.length > 0) parts.push(`${result.auditMissing.length} audit column(s) required but missing`);
+        result.summary = parts.join(', ');
+    } else {
+        result.summary = 'Schema is in sync';
+    }
+
+    result.totalColumnsChecked = dbColumnList.length;
+    return result;
+}
+
+/**
+ * Format drift result ke output console untuk endpoint create.
+ * Format mengikuti spec phase-01-implementation.md:
+ *   [-] kolom_a  (in payload, not in database)
+ *   [+] kolom_b  (in database, not in payload)
+ *   [+] created_at, ... (required by auditColumns=true, not in database)
+ *
+ * @param {Object} comparison - Hasil compareSchemaStrict()
+ * @param {Object} options
+ * @param {string} options.payloadFileName - Nama file payload (untuk resolution message)
+ * @param {string} options.tableName - Nama table
+ * @returns {string[]} Lines untuk di-print
+ */
+function formatDriftReport(comparison, options = {}) {
+    const lines = [];
+    const payloadFile = options.payloadFileName || comparison.tableName;
+    const tableName = comparison.tableName;
+
+    lines.push('  [BLOCKED] Payload-database drift detected:');
+
+    for (const item of comparison.removed) {
+        lines.push(`    [-] ${item.column.padEnd(12)} (in payload, not in database)`);
+    }
+
+    if (Array.isArray(comparison.typeChanges)) {
+        for (const item of comparison.typeChanges) {
+            lines.push(`    [~] ${item.column.padEnd(12)} (type: ${item.payloadType} -> ${item.databaseType})`);
+        }
+    }
+
+    for (const item of comparison.added) {
+        lines.push(`    [+] ${item.column.padEnd(12)} (in database, not in payload)`);
+    }
+
+    if (comparison.auditMissing.length > 0) {
+        const cols = comparison.auditMissing.join(', ');
+        lines.push(`    [+] ${cols}`);
+        lines.push('                     (required by auditColumns=true, not in database)');
+    }
+
+    lines.push('');
+    lines.push('  Resolution:');
+    lines.push(`    1. Run: npx restforge payload sync --table=${tableName} --config=<ENV>`);
+    if (comparison.auditMissing.length > 0) {
+        lines.push(`    2. Add audit columns to schema OR set "auditColumns": false in payload/${payloadFile}`);
+        lines.push('    3. Re-run endpoint create after resolving');
+    } else {
+        lines.push('    2. Tambah kolom missing ke schema untuk match dengan payload');
+        lines.push('    3. Re-run endpoint create after resolving');
+    }
+
+    return lines;
+}
+
+module.exports = {
+    DEFAULT_EXCLUDED_COLUMNS,
+    normalizeDatabaseType,
+    normalizePayloadValidationType,
+    compareSchemaStrict,
+    formatDriftReport
+};