@restforgejs/platform 4.1.1 → 4.3.1

package/generators/lib/migration/audit-table-runner.js

@@ -1,215 +1,213 @@
-/**
- * Audit Table Runner
- *
- * Mengeksekusi DDL audit table ke database yang dituju.
- * Bersifat idempotent (table existing tidak menyebabkan error).
- *
- * Failure mode:
- * - Connection gagal (timeout/auth) → warning + dry-run mode (return status,
- *   tidak throw). Generator boleh lanjut karena migration bisa dijalankan
- *   manual via file SQL yang ditulis.
- * - DDL gagal setelah connection sukses → throw, generator abort.
- *
- * Reference: docs/todo/todo-fieldprotection-concurrency-by-design.md (Bagian 3, 6.4)
- *
- * @module lib/migration/audit-table-runner
- */
-
-const fs = require('fs');
-const path = require('path');
-const { generateAuditTableMigration } = require('./audit-table-generator');
-
-/**
- * Jalankan migration audit table.
- *
- * @param {string} tableName - Nama tabel sumber
- * @param {string} dialect - 'postgres' | 'mysql' | 'oracle'
- * @param {Object|null} connectionInfo - Connection info { host, port, user, password, database, connectString? }.
- *                                       Jika null → dry-run mode (file SQL tetap ditulis).
- * @param {Object} [options]
- * @param {string} [options.projectRoot=process.cwd()] - Root project untuk menulis migrations/audit/
- * @param {Object} [options.logger=console] - Logger dengan method info/warn/error
- * @returns {Promise<{status: string, sqlPath: string, auditTable: string}>}
- *          status: 'created' | 'exists' | 'dry-run' | 'connection-failed'
- */
-async function runAuditMigration(tableName, dialect, connectionInfo, options = {}) {
-  const projectRoot = options.projectRoot || process.cwd();
-  const logger = options.logger || console;
-  const auditTable = `${tableName}_audit`;
-  const sql = generateAuditTableMigration(tableName, dialect);
-
-  const sqlPath = writeMigrationFile(projectRoot, auditTable, sql);
-  logger.info(`[restforge] audit migration written: ${path.relative(projectRoot, sqlPath)}`);
-
-  if (!connectionInfo) {
-    logger.warn(`[restforge] audit migration skipped — database connection not configured`);
-    return { status: 'dry-run', sqlPath, auditTable };
-  }
-
-  let connection;
-  try {
-    connection = await connectToDatabase(dialect, connectionInfo);
-  } catch (err) {
-    logger.warn(`[restforge] audit migration skipped — connection failed: ${err.message}`);
-    return { status: 'connection-failed', sqlPath, auditTable };
-  }
-
-  try {
-    const existed = await auditTableExists(connection, dialect, auditTable, connectionInfo);
-    await executeMigration(connection, dialect, sql);
-    logger.info(existed
-      ? `[restforge] audit table exists: ${auditTable}`
-      : `[restforge] audit table created: ${auditTable}`);
-    return { status: existed ? 'exists' : 'created', sqlPath, auditTable };
-  } catch (err) {
-    logger.error(`[restforge] audit migration failed: ${err.message}`);
-    throw err;
-  } finally {
-    await closeConnection(connection, dialect);
-  }
-}
-
-function writeMigrationFile(projectRoot, auditTable, sql) {
-  const migrationsDir = path.join(projectRoot, 'migrations', 'audit');
-  fs.mkdirSync(migrationsDir, { recursive: true });
-  const sqlPath = path.join(migrationsDir, `${auditTable}.sql`);
-  fs.writeFileSync(sqlPath, sql + '\n', 'utf8');
-  return sqlPath;
-}
-
-async function connectToDatabase(dialect, connectionInfo) {
-  if (dialect === 'postgres') {
-    const { Client } = require('pg');
-    const client = new Client({
-      host: connectionInfo.host,
-      port: connectionInfo.port,
-      user: connectionInfo.user,
-      password: connectionInfo.password,
-      database: connectionInfo.database
-    });
-    await client.connect();
-    return client;
-  }
-
-  if (dialect === 'mysql') {
-    const mysql = require('mysql2/promise');
-    return await mysql.createConnection({
-      host: connectionInfo.host,
-      port: connectionInfo.port,
-      user: connectionInfo.user,
-      password: connectionInfo.password,
-      database: connectionInfo.database,
-      multipleStatements: true
-    });
-  }
-
-  if (dialect === 'oracle') {
-    const oracledb = require('oracledb');
-    return await oracledb.getConnection({
-      user: connectionInfo.user,
-      password: connectionInfo.password,
-      connectString: connectionInfo.connectString
-        || `${connectionInfo.host}:${connectionInfo.port}/${connectionInfo.database}`
-    });
-  }
-
-  throw new Error(`connectToDatabase: unsupported dialect '${dialect}'`);
-}
-
-async function closeConnection(connection, dialect) {
-  if (!connection) return;
-  try {
-    if (dialect === 'oracle') {
-      await connection.close();
-    } else {
-      await connection.end();
-    }
-  } catch (_err) {
-    // ignore close error — primary action sudah selesai
-  }
-}
-
-async function auditTableExists(connection, dialect, auditTable, connectionInfo) {
-  if (dialect === 'postgres') {
-    const { rows } = await connection.query(
-      `SELECT 1 FROM information_schema.tables
-       WHERE table_schema = current_schema() AND table_name = $1
-       LIMIT 1`,
-      [auditTable]
-    );
-    return rows.length > 0;
-  }
-
-  if (dialect === 'mysql') {
-    const [rows] = await connection.query(
-      `SELECT 1 FROM information_schema.tables
-       WHERE table_schema = ? AND table_name = ?
-       LIMIT 1`,
-      [connectionInfo.database, auditTable]
-    );
-    return rows.length > 0;
-  }
-
-  if (dialect === 'oracle') {
-    const result = await connection.execute(
-      `SELECT 1 FROM user_tables WHERE table_name = :name`,
-      { name: auditTable.toUpperCase() }
-    );
-    return result.rows && result.rows.length > 0;
-  }
-
-  return false;
-}
-
-async function executeMigration(connection, dialect, sql) {
-  if (dialect === 'postgres') {
-    // pg client mendukung multiple statement dalam satu query() tanpa params
-    await connection.query(sql);
-    return;
-  }
-
-  if (dialect === 'mysql') {
-    // mysql2 dengan multipleStatements: true
-    await connection.query(sql);
-    return;
-  }
-
-  if (dialect === 'oracle') {
-    // Oracle PL/SQL anonim dipisahkan oleh '/' di line tersendiri.
-    // oracledb.execute() menerima satu statement per call.
-    const blocks = splitOraclePlsqlBlocks(sql);
-    for (const block of blocks) {
-      const trimmed = block.trim();
-      if (trimmed === '') continue;
-      await connection.execute(trimmed);
-    }
-    return;
-  }
-
-  throw new Error(`executeMigration: unsupported dialect '${dialect}'`);
-}
-
-function splitOraclePlsqlBlocks(sql) {
-  // Pisahkan blok PL/SQL berdasarkan baris yang isinya hanya '/'
-  const lines = sql.split(/\r?\n/);
-  const blocks = [];
-  let current = [];
-  for (const line of lines) {
-    if (line.trim() === '/') {
-      if (current.length > 0) {
-        blocks.push(current.join('\n'));
-        current = [];
-      }
-    } else {
-      current.push(line);
-    }
-  }
-  if (current.length > 0 && current.join('').trim() !== '') {
-    blocks.push(current.join('\n'));
-  }
-  return blocks;
-}
-
-module.exports = {
-  runAuditMigration
-};
+/**
+ * Audit Table Runner
+ *
+ * Mengeksekusi DDL audit table ke database yang dituju.
+ * Bersifat idempotent (table existing tidak menyebabkan error).
+ *
+ * Failure mode:
+ * - Connection gagal (timeout/auth) → warning + dry-run mode (return status,
+ *   tidak throw). Generator boleh lanjut karena migration bisa dijalankan
+ *   manual via file SQL yang ditulis.
+ * - DDL gagal setelah connection sukses → throw, generator abort.
+ *
+ * @module lib/migration/audit-table-runner
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { generateAuditTableMigration } = require('./audit-table-generator');
+
+/**
+ * Jalankan migration audit table.
+ *
+ * @param {string} tableName - Nama tabel sumber
+ * @param {string} dialect - 'postgres' | 'mysql' | 'oracle'
+ * @param {Object|null} connectionInfo - Connection info { host, port, user, password, database, connectString? }.
+ *                                       Jika null → dry-run mode (file SQL tetap ditulis).
+ * @param {Object} [options]
+ * @param {string} [options.projectRoot=process.cwd()] - Root project untuk menulis migrations/audit/
+ * @param {Object} [options.logger=console] - Logger dengan method info/warn/error
+ * @returns {Promise<{status: string, sqlPath: string, auditTable: string}>}
+ *          status: 'created' | 'exists' | 'dry-run' | 'connection-failed'
+ */
+async function runAuditMigration(tableName, dialect, connectionInfo, options = {}) {
+  const projectRoot = options.projectRoot || process.cwd();
+  const logger = options.logger || console;
+  const auditTable = `${tableName}_audit`;
+  const sql = generateAuditTableMigration(tableName, dialect);
+
+  const sqlPath = writeMigrationFile(projectRoot, auditTable, sql);
+  logger.info(`[restforge] audit migration written: ${path.relative(projectRoot, sqlPath)}`);
+
+  if (!connectionInfo) {
+    logger.warn(`[restforge] audit migration skipped — database connection not configured`);
+    return { status: 'dry-run', sqlPath, auditTable };
+  }
+
+  let connection;
+  try {
+    connection = await connectToDatabase(dialect, connectionInfo);
+  } catch (err) {
+    logger.warn(`[restforge] audit migration skipped — connection failed: ${err.message}`);
+    return { status: 'connection-failed', sqlPath, auditTable };
+  }
+
+  try {
+    const existed = await auditTableExists(connection, dialect, auditTable, connectionInfo);
+    await executeMigration(connection, dialect, sql);
+    logger.info(existed
+      ? `[restforge] audit table exists: ${auditTable}`
+      : `[restforge] audit table created: ${auditTable}`);
+    return { status: existed ? 'exists' : 'created', sqlPath, auditTable };
+  } catch (err) {
+    logger.error(`[restforge] audit migration failed: ${err.message}`);
+    throw err;
+  } finally {
+    await closeConnection(connection, dialect);
+  }
+}
+
+function writeMigrationFile(projectRoot, auditTable, sql) {
+  const migrationsDir = path.join(projectRoot, 'migrations', 'audit');
+  fs.mkdirSync(migrationsDir, { recursive: true });
+  const sqlPath = path.join(migrationsDir, `${auditTable}.sql`);
+  fs.writeFileSync(sqlPath, sql + '\n', 'utf8');
+  return sqlPath;
+}
+
+async function connectToDatabase(dialect, connectionInfo) {
+  if (dialect === 'postgres') {
+    const { Client } = require('pg');
+    const client = new Client({
+      host: connectionInfo.host,
+      port: connectionInfo.port,
+      user: connectionInfo.user,
+      password: connectionInfo.password,
+      database: connectionInfo.database
+    });
+    await client.connect();
+    return client;
+  }
+
+  if (dialect === 'mysql') {
+    const mysql = require('mysql2/promise');
+    return await mysql.createConnection({
+      host: connectionInfo.host,
+      port: connectionInfo.port,
+      user: connectionInfo.user,
+      password: connectionInfo.password,
+      database: connectionInfo.database,
+      multipleStatements: true
+    });
+  }
+
+  if (dialect === 'oracle') {
+    const oracledb = require('oracledb');
+    return await oracledb.getConnection({
+      user: connectionInfo.user,
+      password: connectionInfo.password,
+      connectString: connectionInfo.connectString
+        || `${connectionInfo.host}:${connectionInfo.port}/${connectionInfo.database}`
+    });
+  }
+
+  throw new Error(`connectToDatabase: unsupported dialect '${dialect}'`);
+}
+
+async function closeConnection(connection, dialect) {
+  if (!connection) return;
+  try {
+    if (dialect === 'oracle') {
+      await connection.close();
+    } else {
+      await connection.end();
+    }
+  } catch (_err) {
+    // ignore close error — primary action sudah selesai
+  }
+}
+
+async function auditTableExists(connection, dialect, auditTable, connectionInfo) {
+  if (dialect === 'postgres') {
+    const { rows } = await connection.query(
+      `SELECT 1 FROM information_schema.tables
+       WHERE table_schema = current_schema() AND table_name = $1
+       LIMIT 1`,
+      [auditTable]
+    );
+    return rows.length > 0;
+  }
+
+  if (dialect === 'mysql') {
+    const [rows] = await connection.query(
+      `SELECT 1 FROM information_schema.tables
+       WHERE table_schema = ? AND table_name = ?
+       LIMIT 1`,
+      [connectionInfo.database, auditTable]
+    );
+    return rows.length > 0;
+  }
+
+  if (dialect === 'oracle') {
+    const result = await connection.execute(
+      `SELECT 1 FROM user_tables WHERE table_name = :name`,
+      { name: auditTable.toUpperCase() }
+    );
+    return result.rows && result.rows.length > 0;
+  }
+
+  return false;
+}
+
+async function executeMigration(connection, dialect, sql) {
+  if (dialect === 'postgres') {
+    // pg client mendukung multiple statement dalam satu query() tanpa params
+    await connection.query(sql);
+    return;
+  }
+
+  if (dialect === 'mysql') {
+    // mysql2 dengan multipleStatements: true
+    await connection.query(sql);
+    return;
+  }
+
+  if (dialect === 'oracle') {
+    // Oracle PL/SQL anonim dipisahkan oleh '/' di line tersendiri.
+    // oracledb.execute() menerima satu statement per call.
+    const blocks = splitOraclePlsqlBlocks(sql);
+    for (const block of blocks) {
+      const trimmed = block.trim();
+      if (trimmed === '') continue;
+      await connection.execute(trimmed);
+    }
+    return;
+  }
+
+  throw new Error(`executeMigration: unsupported dialect '${dialect}'`);
+}
+
+function splitOraclePlsqlBlocks(sql) {
+  // Pisahkan blok PL/SQL berdasarkan baris yang isinya hanya '/'
+  const lines = sql.split(/\r?\n/);
+  const blocks = [];
+  let current = [];
+  for (const line of lines) {
+    if (line.trim() === '/') {
+      if (current.length > 0) {
+        blocks.push(current.join('\n'));
+        current = [];
+      }
+    } else {
+      current.push(line);
+    }
+  }
+  if (current.length > 0 && current.join('').trim() !== '') {
+    blocks.push(current.join('\n'));
+  }
+  return blocks;
+}
+
+module.exports = {
+  runAuditMigration
+};

package/generators/lib/payload/endpoint-schema-validator.js

@@ -0,0 +1,171 @@
+'use strict';
+
+/**
+ * Endpoint Schema Validator
+ *
+ * Orchestrator untuk validasi schema database saat `endpoint create` dijalankan.
+ * Module ini:
+ *   1. Resolve --config file (via config-resolver)
+ *   2. Load config + connect ke database (via DatabaseIntrospector)
+ *   3. Compare payload-vs-database menggunakan compareSchemaStrict
+ *   4. Map hasil ke exit-code semantics:
+ *        - clean schema -> return { status: 'ok' }
+ *        - drift detected -> throw error dengan exitCode=1 + formatted report
+ *        - connection fail -> throw error dengan exitCode=3
+ *        - usage error -> throw error dengan exitCode=2 (di-handle caller via validateContract)
+ *
+ * Module ini sengaja decoupled dari PayloadGenerator agar tidak ikut menjalankan
+ * payload regenerate/sync flow.
+ *
+ * @module lib/payload/endpoint-schema-validator
+ */
+
+const { DatabaseIntrospector } = require('../utils/database-introspector');
+const { resolveConfig, printDefaultConfigWarning } = require('../utils/config-resolver');
+const { compareSchemaStrict, formatDriftReport } = require('./schema-diff');
+
+/**
+ * Buat Error object dengan property `exitCode` agar cli-entry dapat
+ * forward exit code spesifik.
+ *
+ * @param {string} message
+ * @param {number} exitCode
+ * @returns {Error}
+ */
+function createExitError(message, exitCode) {
+    const err = new Error(message);
+    err.exitCode = exitCode;
+    err.isSchemaValidationError = true;
+    return err;
+}
+
+/**
+ * Jalankan validasi schema untuk satu payload + table sebelum codegen.
+ *
+ * @param {Object} options
+ * @param {Object} options.payload - Processed payload object (harus punya tableName)
+ * @param {string} options.payloadFileName - Nama file payload untuk pesan error
+ * @param {string} options.configArg - Nilai flag --config dari CLI
+ * @param {boolean} options.skipSchemaCheck - true bila --skip-schema-check di-set
+ * @param {string} [options.workingDir] - cwd, default process.cwd()
+ * @param {Function} [options.IntrospectorClass] - Override untuk testing
+ * @returns {Promise<{
+ *   status: 'ok' | 'skipped',
+ *   reason?: string,
+ *   columnsChecked?: number
+ * }>}
+ * @throws {Error} Dengan property exitCode (1=drift, 2=usage, 3=connection)
+ */
+async function validateEndpointSchema(options) {
+    const {
+        payload,
+        payloadFileName,
+        configArg,
+        skipSchemaCheck,
+        workingDir,
+        IntrospectorClass
+    } = options;
+
+    if (!payload || !payload.tableName) {
+        throw createExitError('Payload missing tableName — cannot run schema validation', 2);
+    }
+
+    if (skipSchemaCheck) {
+        return { status: 'skipped', reason: '--skip-schema-check active' };
+    }
+
+    const resolved = resolveConfig(configArg, workingDir || process.cwd());
+    if (!resolved) {
+        const lines = [
+            'Error: --config is required for schema validation',
+            'Usage: npx restforge endpoint create --project=<P> --name=<N> --payload=<F> --config=<ENV> [--force=true] [--skip-schema-check]'
+        ];
+        throw createExitError(lines.join('\n'), 2);
+    }
+
+    if (resolved.source === 'default') {
+        printDefaultConfigWarning(resolved.defaultName);
+    }
+
+    const IntroCtor = IntrospectorClass || DatabaseIntrospector;
+    const db = new IntroCtor({ quiet: true });
+
+    const loaded = db.loadConfig(resolved.path);
+    if (!loaded) {
+        throw createExitError(
+            buildConnectionErrorMessage(`Cannot load config file: ${resolved.path}`),
+            3
+        );
+    }
+
+    let connected = false;
+    try {
+        connected = await db.connect();
+    } catch (e) {
+        try { await db.close(); } catch (_e) { /* ignore */ }
+        throw createExitError(
+            buildConnectionErrorMessage(e.message || String(e)),
+            3
+        );
+    }
+
+    if (!connected) {
+        try { await db.close(); } catch (_e) { /* ignore */ }
+        throw createExitError(
+            buildConnectionErrorMessage('database not reachable'),
+            3
+        );
+    }
+
+    let comparison;
+    try {
+        comparison = await compareSchemaStrict(payload, db);
+    } finally {
+        try { await db.close(); } catch (_e) { /* ignore */ }
+    }
+
+    if (comparison.status === 'error') {
+        const lines = [
+            'Schema Validation:',
+            `  [ERROR] ${comparison.summary}`,
+            '  Endpoint generation blocked.',
+            '',
+            '  Workarounds:',
+            '    1. Verify the table exists in the database',
+            '    2. Use --skip-schema-check to bypass validation (NOT recommended for production)'
+        ];
+        throw createExitError(lines.join('\n'), 3);
+    }
+
+    if (comparison.status === 'drift') {
+        const driftLines = formatDriftReport(comparison, {
+            payloadFileName,
+            tableName: payload.tableName
+        });
+        const lines = ['Schema Validation:', ...driftLines, '', 'Endpoint generation blocked due to schema drift'];
+        throw createExitError(lines.join('\n'), 1);
+    }
+
+    return {
+        status: 'ok',
+        columnsChecked: comparison.totalColumnsChecked || 0
+    };
+}
+
+function buildConnectionErrorMessage(reason) {
+    const lines = [
+        'Schema Validation:',
+        `  [ERROR] Cannot connect to database: ${reason}`,
+        '  Endpoint generation blocked.',
+        '',
+        '  Workarounds:',
+        '    1. Verify db-connection.env is correct and database is reachable',
+        '    2. Use --skip-schema-check to bypass validation (NOT recommended for production)'
+    ];
+    return lines.join('\n');
+}
+
+module.exports = {
+    validateEndpointSchema,
+    createExitError
+};