@restforgejs/platform 5.0.9 → 5.1.4

package/generators/lib/payload/payload-runner.js

@@ -93,6 +93,456 @@ if (isCompiledBinary) {
   process.removeAllListeners('warning');
 }
 
+// ============================================================================
+// FOREIGN KEY EXPANSION (payload sync --expand-fk)
+// ============================================================================
+
+/**
+ * Parse string --fk-columns menjadi array spec {table, column, raw}.
+ *
+ * Kontrak: setiap entri WAJIB berbentuk `table.column` (qualified), dipisah
+ * koma. Bentuk polos (tanpa `table.`) ditolak agar tidak ada penebakan tabel
+ * referensi pada kasus multi-FK. Entri duplikat (table.column sama,
+ * case-insensitive) di-dedupe dengan mempertahankan urutan kemunculan pertama.
+ *
+ * @param {string} fkColumnsStr - Nilai flag --fk-columns
+ * @returns {Array<{table: string, column: string, raw: string}>}
+ * @throws {Error} bila kosong atau ada entri yang tidak berbentuk table.column
+ */
+function parseFkColumns(fkColumnsStr) {
+  if (typeof fkColumnsStr !== 'string' || fkColumnsStr.trim().length === 0) {
+    throw new Error(
+      '--fk-columns is required when --expand-fk is set ' +
+      '(format: table.column,table.column)'
+    );
+  }
+
+  const entries = fkColumnsStr.split(',').map(s => s.trim()).filter(Boolean);
+  if (entries.length === 0) {
+    throw new Error('--fk-columns has no usable entries after parsing');
+  }
+
+  const specs = [];
+  const seen = new Set();
+  for (const raw of entries) {
+    const parts = raw.split('.');
+    if (parts.length !== 2 || !parts[0].trim() || !parts[1].trim()) {
+      throw new Error(
+        `Invalid --fk-columns entry "${raw}": each entry must be qualified as table.column`
+      );
+    }
+    const table = parts[0].trim();
+    const column = parts[1].trim();
+    const key = `${table.toLowerCase()}.${column.toLowerCase()}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    specs.push({ table, column, raw });
+  }
+  return specs;
+}
+
+/**
+ * Derive alias tabel secara deterministik: inisial tiap kata yang dipisah
+ * underscore, lowercase. Contoh: `visitors`->`v`, `visitor_categories`->`vc`,
+ * `stock_inbound`->`si`. Schema prefix (mis. `public.`) diabaikan.
+ *
+ * @param {string} tableName
+ * @returns {string}
+ */
+function deriveTableAlias(tableName) {
+  const bare = tableName.includes('.') ? tableName.split('.').pop() : tableName;
+  const parts = String(bare).split('_').filter(Boolean);
+  const initials = parts.map(p => p[0]).join('').toLowerCase();
+  return initials || 't';
+}
+
+/**
+ * Pilih kolom display dari tabel referensi secara heuristik untuk mode
+ * auto-resolve (`--expand-fk` tanpa `--fk-columns`).
+ *
+ * Urutan prioritas (deterministik):
+ *   1. Kolom "name"  : token `name` / `nama`
+ *   2. Kolom "code"  : token `code` / `kode`
+ *   3. Primary key tabel referensi (fallback terakhir)
+ *
+ * Dalam tiap kelompok token, skor: exact match (3) > berakhiran `_<token>` (2)
+ * > mengandung token (1). Skor tertinggi menang; bila seri, kolom yang muncul
+ * lebih dulu di urutan kolom database dipertahankan. Kolom audit default
+ * di-exclude dari kandidat name/code.
+ *
+ * @param {string[]} refColumns - Kolom fisik tabel referensi (urutan database)
+ * @param {string|null} primaryKey - Primary key tabel referensi
+ * @returns {string|null} Nama kolom terpilih, atau null bila tidak ada kandidat
+ */
+function pickDisplayColumn(refColumns, primaryKey) {
+  const cols = (refColumns || []).filter(c => !DEFAULT_AUDIT_COLUMNS.includes(c));
+
+  const bestByTokens = (tokens) => {
+    let best = null;
+    let bestScore = 0;
+    for (const c of cols) {
+      const lc = String(c).toLowerCase();
+      let score = 0;
+      for (const t of tokens) {
+        if (lc === t) score = Math.max(score, 3);
+        else if (lc.endsWith(`_${t}`)) score = Math.max(score, 2);
+        else if (lc.includes(t)) score = Math.max(score, 1);
+      }
+      if (score > bestScore) {
+        bestScore = score;
+        best = c;
+      }
+    }
+    return best;
+  };
+
+  return bestByTokens(['name', 'nama'])
+    || bestByTokens(['code', 'kode'])
+    || primaryKey
+    || null;
+}
+
+/**
+ * Bangun konfigurasi JOIN dari foreign key. Pure (tanpa I/O) agar mudah di-test.
+ * Mengembalikan { updatedPayload, sqlRelPath, sqlContent } atau throw Error pada
+ * kondisi invalid (tabel referensi tidak ada, kolom tidak ditemukan, FK ganda
+ * ke tabel sama, collision output yang tidak dapat di-resolve).
+ *
+ * Aturan output:
+ *   - SELECT base = payload.fieldName yang merupakan kolom fisik base table
+ *     (kolom non-fisik mis. hasil JOIN run sebelumnya dibuang agar idempotent)
+ *   - kolom referensi di-surface dengan prefix alias; bila nama output bentrok
+ *     (dengan kolom base atau kolom referensi lain), output di-prefix nama tabel
+ *     referensi via `AS` (mis. `w.city AS warehouse_city`)
+ *   - LEFT JOIN per tabel referensi yang dipakai, kondisi diturunkan dari FK
+ *   - datatablesQuery & viewQuery -> `file:query/<table>-join.sql`
+ *   - datatablesWhere: pertahankan existing, hapus output lama, sisipkan output
+ *     referensi sebelum entri `"all"`
+ *   - fieldValidation TIDAK disentuh (kolom JOIN bukan kolom fisik)
+ *
+ * @param {Object} payload - Payload saat ini (punya tableName + fieldName)
+ * @param {Array<{table,column,raw}>} fkSpec - hasil parseFkColumns
+ * @param {Array} foreignKeys - hasil db.getForeignKeys(tableName)
+ * @param {Object} refColumnsMap - { refTableLower: string[] kolom fisik referensi }
+ * @param {string[]} baseColumns - kolom fisik base table (non-audit)
+ * @returns {{updatedPayload: Object, sqlRelPath: string, sqlContent: string}}
+ */
+function buildForeignKeyExpansion(payload, fkSpec, foreignKeys, refColumnsMap, baseColumns) {
+  const tableName = payload.tableName;
+
+  // Base fields = fieldName yang benar-benar kolom fisik base table.
+  const basePhysicalLower = new Set((baseColumns || []).map(c => String(c).toLowerCase()));
+  const declaredFields = Array.isArray(payload.fieldName) ? payload.fieldName : [];
+  const baseFields = declaredFields.filter(f => basePhysicalLower.has(String(f).toLowerCase()));
+
+  // Map refTable(lower) -> FK; deteksi FK ganda ke tabel referensi yang sama.
+  const fkByRefTable = new Map();
+  const dupRefTables = new Set();
+  for (const fk of (foreignKeys || [])) {
+    const rt = fk && fk.references && fk.references.table ? String(fk.references.table) : '';
+    if (!rt) continue;
+    const key = rt.toLowerCase();
+    if (fkByRefTable.has(key)) dupRefTables.add(key);
+    else fkByRefTable.set(key, fk);
+  }
+
+  if (fkByRefTable.size === 0) {
+    throw new Error(
+      `Table "${tableName}" has no foreign keys; --expand-fk cannot resolve any reference`
+    );
+  }
+
+  // Alias unik: base dulu, lalu tiap tabel referensi sesuai urutan kemunculan.
+  const usedAliases = new Set();
+  const uniqueAlias = (base) => {
+    let a = base, n = 1;
+    while (usedAliases.has(a)) { n++; a = base + n; }
+    usedAliases.add(a);
+    return a;
+  };
+  const baseAlias = uniqueAlias(deriveTableAlias(tableName));
+
+  const refTableAlias = new Map(); // refKeyLower -> { alias, fk, refTableName }
+  const refSelections = [];        // { alias, column, refTableName }
+  for (const spec of fkSpec) {
+    const key = spec.table.toLowerCase();
+    if (!fkByRefTable.has(key)) {
+      const available = [...fkByRefTable.keys()].join(', ') || '(none)';
+      throw new Error(
+        `Foreign key reference table "${spec.table}" not found for "${tableName}". ` +
+        `Referenced tables available: ${available}`
+      );
+    }
+    if (dupRefTables.has(key)) {
+      throw new Error(
+        `Table "${tableName}" has multiple foreign keys referencing "${spec.table}"; ` +
+        'cannot disambiguate by table name'
+      );
+    }
+
+    const fk = fkByRefTable.get(key);
+    const refTableName = fk.references.table;
+    const refCols = refColumnsMap[key] || refColumnsMap[refTableName] || [];
+    const refColsLower = refCols.map(c => String(c).toLowerCase());
+    if (!refColsLower.includes(spec.column.toLowerCase())) {
+      throw new Error(
+        `Column "${spec.column}" not found in referenced table "${spec.table}". ` +
+        `Available columns: ${refCols.join(', ') || '(none)'}`
+      );
+    }
+
+    if (!refTableAlias.has(key)) {
+      refTableAlias.set(key, {
+        alias: uniqueAlias(deriveTableAlias(refTableName)),
+        fk,
+        refTableName
+      });
+    }
+    refSelections.push({ alias: refTableAlias.get(key).alias, column: spec.column, refTableName });
+  }
+
+  // Output name + collision auto-prefix. Hitung occurrence nama tentatif
+  // (base fields + kolom referensi apa adanya); nama yang muncul >1 kali
+  // di-prefix nama tabel referensi.
+  const nameCount = new Map();
+  const bump = (n) => nameCount.set(n, (nameCount.get(n) || 0) + 1);
+  for (const f of baseFields) bump(f);
+  for (const r of refSelections) bump(r.column);
+
+  const finalNames = new Set(baseFields);
+  const refOutputs = []; // { alias, column, output, refTableName }
+  for (const r of refSelections) {
+    let output = r.column;
+    if ((nameCount.get(r.column) || 0) > 1) {
+      output = `${r.refTableName}_${r.column}`.toLowerCase();
+    }
+    if (finalNames.has(output)) {
+      throw new Error(
+        `Output column "${output}" collides after auto-prefix in expansion for "${tableName}"; ` +
+        'rename the source column or adjust the schema'
+      );
+    }
+    finalNames.add(output);
+    refOutputs.push({ alias: r.alias, column: r.column, output, refTableName: r.refTableName });
+  }
+
+  // SQL build.
+  const baseSelect = baseFields.map(c => `${baseAlias}.${c}`);
+  const refSelect = refOutputs.map(r =>
+    r.output === r.column ? `${r.alias}.${r.column}` : `${r.alias}.${r.column} AS ${r.output}`
+  );
+  const selectItems = [...baseSelect, ...refSelect];
+
+  const sqlLines = selectItems.map((item, idx) => {
+    const prefix = idx === 0 ? 'SELECT ' : '       ';
+    const suffix = idx === selectItems.length - 1 ? '' : ',';
+    return `${prefix}${item}${suffix}`;
+  });
+  sqlLines.push(`FROM ${tableName} ${baseAlias}`);
+  for (const [, info] of refTableAlias) {
+    const localCols = info.fk.columns || [];
+    const refCols = (info.fk.references && info.fk.references.columns) || [];
+    const pairCount = Math.max(localCols.length, refCols.length);
+    const conds = [];
+    for (let i = 0; i < pairCount; i++) {
+      conds.push(`${info.alias}.${refCols[i]} = ${baseAlias}.${localCols[i]}`);
+    }
+    sqlLines.push(`LEFT JOIN ${info.refTableName} ${info.alias} ON ${conds.join(' AND ')}`);
+  }
+  const sqlContent = `${sqlLines.join('\n')}\n`;
+
+  // Mutasi payload.
+  const baseFilename = tableName.replace(/[._]/g, '-');
+  const sqlRelPath = `query/${baseFilename}-join.sql`;
+  const refOutputNames = refOutputs.map(r => r.output);
+
+  const updatedPayload = { ...payload };
+  updatedPayload.fieldName = [
+    ...baseFields,
+    ...refOutputNames
+  ];
+  updatedPayload.datatablesQuery = `file:${sqlRelPath}`;
+  updatedPayload.viewQuery = `file:${sqlRelPath}`;
+
+  let where = Array.isArray(updatedPayload.datatablesWhere)
+    ? updatedPayload.datatablesWhere.slice()
+    : [];
+  where = where.filter(w => !refOutputNames.includes(w));
+  const allIdx = where.indexOf('all');
+  const insertAt = allIdx >= 0 ? allIdx : where.length;
+  where.splice(insertAt, 0, ...refOutputNames);
+  updatedPayload.datatablesWhere = where;
+
+  return { updatedPayload, sqlRelPath, sqlContent };
+}
+
+// ============================================================================
+// SEARCHABLE COLUMNS (datatablesWhere)
+// ============================================================================
+
+// Pola nama kolom yang tidak dijadikan searchable secara default (id + audit/
+// timestamp). Dipakai hanya untuk MEMILIH kolom default, bukan sebagai aturan
+// keras tentang kolom apa yang boleh ada di datatablesWhere.
+const SEARCHABLE_EXCLUDE_PATTERNS = ['_id', '_at', '_by', 'created', 'updated', 'deleted'];
+
+// Tipe data string yang valid untuk pencarian LIKE.
+const SEARCHABLE_STRING_DATA_TYPES = ['character varying', 'varchar', 'text', 'character', 'char'];
+const SEARCHABLE_STRING_UDT = ['varchar', 'text', 'bpchar'];
+
+/**
+ * Kumpulkan nama kolom bertipe string (varchar/text/char) dari detailedColumns.
+ *
+ * detailedColumns sebaiknya sudah di-enrich dengan boolean
+ * (`enrichDetailedColumnsWithBoolean`) agar kolom boolean-marker pada dialect
+ * varchar (mysql/oracle/sqlite) ter-set `data_type='boolean'` dan TIDAK salah
+ * dihitung sebagai string. Hanya kolom bertipe string yang boleh masuk
+ * `datatablesWhere`, sebab runtime membungkus kolom searchable dengan
+ * `upper(col) LIKE upper(?)` yang gagal pada tipe non-text (mis. PostgreSQL
+ * `function upper(integer) does not exist`).
+ *
+ * @param {Array} detailedColumns - Array dari getDetailedColumnInfo() (enriched)
+ * @returns {Set<string>} nama kolom bertipe string
+ */
+function collectStringColumns(detailedColumns) {
+  const set = new Set();
+  for (const col of (detailedColumns || [])) {
+    const dt = String(col.data_type || '').toLowerCase();
+    const udt = String(col.udt_name || '').toLowerCase();
+    if (SEARCHABLE_STRING_DATA_TYPES.includes(dt) || SEARCHABLE_STRING_UDT.includes(udt)) {
+      set.add(col.column_name);
+    }
+  }
+  return set;
+}
+
+/**
+ * Predikat default untuk pemilihan kolom searchable baru: kolom tidak cocok pola
+ * exclude nama (id/audit) DAN bertipe string.
+ *
+ * @param {string} fieldName
+ * @param {Set<string>} stringColumns - hasil collectStringColumns
+ * @returns {boolean}
+ */
+function isDefaultSearchableColumn(fieldName, stringColumns) {
+  const lower = String(fieldName).toLowerCase();
+  if (SEARCHABLE_EXCLUDE_PATTERNS.some(p => lower.includes(p))) return false;
+  return stringColumns.has(fieldName);
+}
+
+// ============================================================================
+// DEFAULT SCOPE (is_active) — built-in untuk payload generate & sync
+// ============================================================================
+
+// Nama kolom penanda aktif. Match exact lowercase (snake_case), konsisten dengan
+// konvensi penamaan RESTForge.
+const IS_ACTIVE_COLUMN = 'is_active';
+
+// Action yang menerima filter is_active otomatis (sesuai catalogs/rdf/default-scope.md;
+// datatables & first sengaja tidak terpengaruh).
+const DEFAULT_SCOPE_ACTIONS = ['lookup', 'read'];
+
+/**
+ * Terapkan/lepas defaultScope berbasis kolom `is_active` secara in-place.
+ *
+ * - hasIsActive true  : pastikan defaultScope.lookup.is_active = true dan
+ *   defaultScope.read.is_active = true (merge, pertahankan key scope lain).
+ * - hasIsActive false : hapus key `is_active` dari lookup/read; bersihkan object
+ *   action yang menjadi kosong; hapus `defaultScope` bila kosong total.
+ *
+ * Hanya menyentuh key `is_active` agar kustomisasi scope lain (mis. tenant_id)
+ * tidak ikut hilang. Pemanggil menentukan `hasIsActive` dari keberadaan kolom
+ * `is_active` di fieldName payload (sekaligus menjamin aturan validator
+ * "kolom defaultScope harus ada di fieldName" terpenuhi).
+ *
+ * @param {Object} payload - Payload yang dimutasi
+ * @param {boolean} hasIsActive - Apakah kolom is_active ada di fieldName
+ * @returns {void}
+ */
+function applyIsActiveDefaultScope(payload, hasIsActive) {
+  if (hasIsActive) {
+    const existing = (payload.defaultScope && typeof payload.defaultScope === 'object'
+      && !Array.isArray(payload.defaultScope))
+      ? payload.defaultScope
+      : {};
+    for (const action of DEFAULT_SCOPE_ACTIONS) {
+      const prev = (existing[action] && typeof existing[action] === 'object'
+        && !Array.isArray(existing[action]))
+        ? existing[action]
+        : {};
+      existing[action] = { ...prev, [IS_ACTIVE_COLUMN]: true };
+    }
+    payload.defaultScope = existing;
+    return;
+  }
+
+  // hasIsActive false -> lepas key is_active.
+  const ds = payload.defaultScope;
+  if (!ds || typeof ds !== 'object' || Array.isArray(ds)) return;
+  for (const action of DEFAULT_SCOPE_ACTIONS) {
+    if (ds[action] && typeof ds[action] === 'object' && !Array.isArray(ds[action])) {
+      delete ds[action][IS_ACTIVE_COLUMN];
+      if (Object.keys(ds[action]).length === 0) delete ds[action];
+    }
+  }
+  if (Object.keys(ds).length === 0) delete payload.defaultScope;
+}
+
+// ============================================================================
+// ADVISORIES (informational) — untuk payload validate
+// ============================================================================
+
+/**
+ * Bangun daftar advisory informational untuk sebuah payload. Advisory bersifat
+ * SARAN tindak lanjut, BUKAN error: tidak memengaruhi verdict (OK/DRIFT/ERROR)
+ * maupun exit code.
+ *
+ * Jenis advisory:
+ *   - fk    : tabel punya foreign key tetapi payload belum men-surface-nya
+ *             sebagai JOIN (tidak ada `viewQuery`). Saran: `payload sync --expand-fk`.
+ *   - scope : kolom `is_active` ada di fieldName tetapi `defaultScope` belum
+ *             memuat `is_active` di lookup & read. Saran: `payload sync`.
+ *
+ * @param {Object} payload
+ * @param {Object} info
+ * @param {Array} info.foreignKeys - hasil db.getForeignKeys(tableName)
+ * @param {boolean} info.hasIsActive - apakah is_active ada di fieldName
+ * @returns {Array<{type: string, table: string, message: string, command: string}>}
+ */
+function buildPayloadAdvisories(payload, info) {
+  const advisories = [];
+  const table = payload.tableName;
+
+  // a. Foreign key belum di-surface sebagai JOIN.
+  const fkCount = Array.isArray(info.foreignKeys) ? info.foreignKeys.length : 0;
+  const usesJoin = typeof payload.viewQuery === 'string' && payload.viewQuery.trim().length > 0;
+  if (fkCount > 0 && !usesJoin) {
+    advisories.push({
+      type: 'fk',
+      table,
+      message: `has ${fkCount} foreign key(s) not surfaced as JOIN`,
+      command: `npx restforge payload sync --table=${table} --expand-fk`
+    });
+  }
+
+  // b. is_active ada tetapi defaultScope belum lengkap.
+  if (info.hasIsActive) {
+    const ds = payload.defaultScope;
+    const scopeComplete = ds && typeof ds === 'object' && !Array.isArray(ds)
+      && ds.lookup && ds.lookup[IS_ACTIVE_COLUMN] === true
+      && ds.read && ds.read[IS_ACTIVE_COLUMN] === true;
+    if (!scopeComplete) {
+      advisories.push({
+        type: 'scope',
+        table,
+        message: 'has is_active but defaultScope is incomplete',
+        command: `npx restforge payload sync --table=${table}`
+      });
+    }
+  }
+
+  return advisories;
+}
+
 
 /**
  * Class untuk Payload Generator (non-interactive only)
@@ -576,7 +1026,10 @@ class PayloadGenerator {
 
         let result;
         if (args.sync) {
-          result = await validator.runSync(targetTable, this);
+          result = await validator.runSync(targetTable, this, {
+            expandFk: args.expandFk === true,
+            fkColumns: args.fkColumns || null
+          });
         } else if (args.diff) {
           result = await validator.runDiff(targetTable);
         } else {
@@ -699,12 +1152,33 @@ class PayloadGenerator {
     const sqlContent = `${sqlLines.join('\n')}\nFROM ${payloadData.tableName} a\n`;
     payloadData.datatablesQuery = `file:query/${sqlFilename}`;
 
-    // Generate searchable columns
-    const excludePatterns = ['_id', '_at', '_by', 'created', 'updated', 'deleted'];
-    payloadData.datatablesWhere = payloadData.fieldName.filter(field => {
-      const fieldLower = field.toLowerCase();
-      return !excludePatterns.some(pattern => fieldLower.includes(pattern));
-    });
+    // Introspeksi tipe & constraint sekali, dipakai untuk searchable columns,
+    // dateTimeFields, fieldValidation, dan uniqueConstraints.
+    let enrichedColumns = null;
+    let columnTypes = null;
+    let constraints = [];
+    if (this.db.pool) {
+      columnTypes = await this.db.getColumnTypes(args.table);
+      const detailedColumns = await this.db.getDetailedColumnInfo(args.table);
+      constraints = await this.db.getConstraints(args.table);
+      const booleanColumns = typeof this.db.getBooleanColumns === 'function'
+        ? await this.db.getBooleanColumns(args.table)
+        : [];
+      enrichedColumns = this.enrichDetailedColumnsWithConstraints(detailedColumns, constraints);
+      enrichedColumns = this.enrichDetailedColumnsWithBoolean(enrichedColumns, booleanColumns);
+    }
+
+    // Generate searchable columns: HANYA kolom bertipe string yang masuk
+    // datatablesWhere (lihat collectStringColumns). Kolom non-string
+    // (integer/numeric/boolean/date/timestamp) di-exclude agar runtime tidak
+    // membentuk upper(col) LIKE upper(?) pada tipe non-text. Pola nama id/audit
+    // tetap di-exclude. Fallback name-only dipakai bila DB tidak terkoneksi.
+    const stringColumns = enrichedColumns ? collectStringColumns(enrichedColumns) : null;
+    payloadData.datatablesWhere = payloadData.fieldName.filter(field =>
+      stringColumns
+        ? isDefaultSearchableColumn(field, stringColumns)
+        : !SEARCHABLE_EXCLUDE_PATTERNS.some(p => field.toLowerCase().includes(p))
+    );
     payloadData.datatablesWhere.push('all');
 
     // Enable all actions
@@ -718,22 +1192,18 @@ class PayloadGenerator {
       read: true
     };
 
+    // Built-in defaultScope: bila tabel punya kolom is_active, tambahkan filter
+    // { is_active: true } untuk action lookup & read (lihat catalogs/rdf/default-scope.md).
+    applyIsActiveDefaultScope(payloadData, payloadData.fieldName.includes(IS_ACTIVE_COLUMN));
+
     // Generate dateTimeFields and fieldValidation
-    if (this.db.pool) {
-      const columnTypes = await this.db.getColumnTypes(args.table);
+    if (enrichedColumns) {
       const dateTimeFields = this.generateDateTimeFields(columnTypes, payloadData.fieldName);
       if (Object.keys(dateTimeFields).length > 0) {
         payloadData.dateTimeFields = dateTimeFields;
       }
 
       // Generate fieldValidation for special fields
-      const detailedColumns = await this.db.getDetailedColumnInfo(args.table);
-      const constraints = await this.db.getConstraints(args.table);
-      const booleanColumns = typeof this.db.getBooleanColumns === 'function'
-        ? await this.db.getBooleanColumns(args.table)
-        : [];
-      let enrichedColumns = this.enrichDetailedColumnsWithConstraints(detailedColumns, constraints);
-      enrichedColumns = this.enrichDetailedColumnsWithBoolean(enrichedColumns, booleanColumns);
       const fieldValidation = this.generateFieldValidation(enrichedColumns, payloadData.fieldName, payloadData.primaryKey);
       if (fieldValidation.length > 0) {
         payloadData.fieldValidation = fieldValidation;
@@ -947,6 +1417,7 @@ class SchemaValidator {
     console.log();
 
     const results = [];
+    const advisories = [];
     let ok = 0, drift = 0, error = 0;
 
     for (const { fileName, payload } of payloads) {
@@ -954,6 +1425,20 @@ class SchemaValidator {
       results.push({ fileName, comparison });
       this.printComparisonResult(comparison, fileName, false);
 
+      // Kumpulkan advisory informational (tidak memengaruhi verdict/exit code).
+      // Dilewati bila tabel tidak ada di database (status error).
+      if (comparison.status !== 'error') {
+        let foreignKeys = [];
+        if (typeof this.db.getForeignKeys === 'function') {
+          try {
+            foreignKeys = await this.db.getForeignKeys(payload.tableName);
+          } catch (_e) { foreignKeys = []; }
+        }
+        const hasIsActive = Array.isArray(payload.fieldName)
+          && payload.fieldName.includes(IS_ACTIVE_COLUMN);
+        advisories.push(...buildPayloadAdvisories(payload, { foreignKeys, hasIsActive }));
+      }
+
       if (comparison.status === 'ok') ok++;
       else if (comparison.status === 'drift') drift++;
       else error++;
@@ -970,9 +1455,19 @@ class SchemaValidator {
     if (error > 0) console.log(`    Error  : ${error}`);
     console.log();
 
+    // Advisories informational (saran tindak lanjut FK & scope), bukan error.
+    if (advisories.length > 0) {
+      console.log('  Advisories (informational, not errors):');
+      for (const a of advisories) {
+        console.log(`    [i] ${a.table}: ${a.message}`);
+        console.log(`        -> ${a.command}`);
+      }
+      console.log();
+    }
+
     if (drift > 0 || error > 0) {
-      console.log('  Use --diff for detailed comparison.');
-      console.log('  Use --sync to update payload files automatically.');
+      console.log("  Use 'npx restforge payload diff' for detailed comparison.");
+      console.log("  Use 'npx restforge payload sync' to update payload files automatically.");
       console.log();
     }
 
@@ -1042,7 +1537,7 @@ class SchemaValidator {
     console.log();
 
     if (drift > 0) {
-      console.log('  Use --sync to update payload files automatically.');
+      console.log("  Use 'npx restforge payload sync' to update payload files automatically.");
       console.log();
     }
 
@@ -1091,15 +1586,43 @@ class SchemaValidator {
    * File lama di-archive sebelum overwrite.
    * @param {string|null} tableName - Nama table spesifik, atau null untuk semua
    * @param {PayloadGenerator} generator - Instance PayloadGenerator untuk re-generate
+   * @param {Object} [options]
+   * @param {boolean} [options.expandFk] - Aktifkan FK JOIN expansion
+   * @param {string} [options.fkColumns] - Daftar kolom referensi `table.column,...`
    * @returns {Promise<Object>} { total, synced, skipped, error }
    */
-  async runSync(tableName, generator) {
+  async runSync(tableName, generator, options = {}) {
+    const expandFk = options.expandFk === true;
+    const fkColumns = options.fkColumns || null;
+
     console.log();
     console.log('='.repeat(60));
     console.log('SCHEMA SYNC - Update Payload from Database');
     console.log('='.repeat(60));
     console.log();
 
+    // Mode expand-fk butuh target tabel tunggal dan --fk-columns yang valid.
+    // Validasi upfront agar gagal cepat dengan pesan jelas.
+    if (expandFk) {
+      if (!tableName) {
+        console.log('  [ERROR] --expand-fk requires --table=<table>');
+        console.log();
+        return { total: 0, synced: 0, skipped: 0, error: 1 };
+      }
+      // --fk-columns bersifat opsional: bila diisi, validasi format upfront;
+      // bila kosong, mode auto-resolve (kolom display dipilih per FK saat
+      // applyForeignKeyExpansion).
+      if (fkColumns) {
+        try {
+          parseFkColumns(fkColumns);
+        } catch (e) {
+          console.log(`  [ERROR] ${e.message}`);
+          console.log();
+          return { total: 0, synced: 0, skipped: 0, error: 1 };
+        }
+      }
+    }
+
     let payloads;
     if (tableName) {
       const found = this.findPayloadForTable(tableName);
@@ -1136,6 +1659,53 @@ class SchemaValidator {
         continue;
       }
 
+      // Mode expand-fk: terapkan konfigurasi JOIN dari foreign key. Berbeda
+      // dari sync biasa, mode ini tetap memproses meski kolom fisik sudah
+      // in-sync (status 'ok'); bila ada drift kolom fisik, rekonsiliasi dulu
+      // lewat regeneratePayload baru ekspansi FK diterapkan di atasnya.
+      if (expandFk) {
+        let workingPayload = payload;
+        if (comparison.status === 'drift') {
+          try {
+            workingPayload = await this.regeneratePayload(payload, comparison, { fileName });
+          } catch (e) {
+            console.log(`  [ERROR]   ${fileName} - physical reconcile failed: ${e.message}`);
+            errorCount++;
+            continue;
+          }
+        }
+
+        let expansion;
+        try {
+          expansion = await this.applyForeignKeyExpansion(workingPayload, fkColumns, { fileName });
+        } catch (e) {
+          console.log(`  [ERROR]   ${fileName} - expand-fk failed: ${e.message}`);
+          errorCount++;
+          continue;
+        }
+
+        const archivePath = this.archiveFile(filePath);
+        console.log(`  [ARCHIVE] ${fileName} -> ${path.basename(archivePath)}`);
+        try {
+          // Tulis file SQL JOIN.
+          const sqlAbsPath = path.join(this.outputDir, expansion.sqlRelPath);
+          const sqlDir = path.dirname(sqlAbsPath);
+          if (!fs.existsSync(sqlDir)) fs.mkdirSync(sqlDir, { recursive: true });
+          fs.writeFileSync(sqlAbsPath, expansion.sqlContent, 'utf8');
+
+          fs.writeFileSync(filePath, JSON.stringify(expansion.updatedPayload, null, 4), 'utf8');
+          console.log(`  [QUERY]   ${path.basename(sqlAbsPath)} written (${expansion.sqlRelPath})`);
+          console.log(`  [SYNCED]  ${fileName} - FK expansion applied (${expansion.updatedPayload.fieldName.length} fields)`);
+          synced++;
+        } catch (e) {
+          // Restore payload lama dari archive jika gagal menulis.
+          fs.renameSync(archivePath, filePath);
+          console.log(`  [ERROR]   ${fileName} - sync failed: ${e.message}`);
+          errorCount++;
+        }
+        continue;
+      }
+
       if (comparison.status === 'ok') {
         console.log(`  [SKIP]    ${fileName} - already in sync`);
         skipped++;
@@ -1177,6 +1747,86 @@ class SchemaValidator {
     return { total: payloads.length, synced, skipped, error: errorCount };
   }
 
+  /**
+   * Terapkan FK JOIN expansion pada sebuah payload. Orkestrasi I/O
+   * (introspeksi FK + kolom tabel referensi) lalu delegasi ke pure builder
+   * `buildForeignKeyExpansion`. Tidak menulis file; caller (runSync) yang
+   * menulis SQL + payload.
+   *
+   * Mode kolom:
+   *   - Eksplisit: `fkColumnsStr` diisi (`table.column,...`) -> dipakai apa adanya.
+   *   - Auto-resolve: `fkColumnsStr` kosong/null -> untuk SETIAP foreign key,
+   *     pilih satu kolom display dari tabel referensi via `pickDisplayColumn`
+   *     (heuristik name/nama -> code/kode -> primary key).
+   *
+   * @param {Object} payload - Payload saat ini (sudah direkonsiliasi kolom fisik bila perlu)
+   * @param {string|null} fkColumnsStr - Nilai --fk-columns (`table.column,...`) atau null untuk auto
+   * @param {Object} [ctx]
+   * @param {string} [ctx.fileName] - Nama file payload untuk konteks pesan
+   * @returns {Promise<{updatedPayload: Object, sqlRelPath: string, sqlContent: string}>}
+   * @throws {Error} bila introspeksi/validasi gagal
+   */
+  async applyForeignKeyExpansion(payload, fkColumnsStr, ctx = {}) {
+    const tableName = payload.tableName;
+
+    const foreignKeys = typeof this.db.getForeignKeys === 'function'
+      ? await this.db.getForeignKeys(tableName)
+      : [];
+    if (!Array.isArray(foreignKeys) || foreignKeys.length === 0) {
+      throw new Error(
+        `Table "${tableName}" has no foreign keys; --expand-fk cannot resolve any reference`
+      );
+    }
+
+    // Kolom fisik base table (buang kolom audit default agar tidak masuk SELECT base).
+    const baseColumns = (await this.db.getColumns(tableName))
+      .filter(c => !DEFAULT_AUDIT_COLUMNS.includes(c));
+
+    const isAuto = typeof fkColumnsStr !== 'string' || fkColumnsStr.trim().length === 0;
+    const refColumnsMap = {};
+    let fkSpec;
+
+    if (isAuto) {
+      // Auto-resolve: satu kolom display per foreign key.
+      fkSpec = [];
+      for (const fk of foreignKeys) {
+        const rt = fk && fk.references && fk.references.table;
+        if (!rt) continue;
+        const key = String(rt).toLowerCase();
+        if (!refColumnsMap[key]) {
+          refColumnsMap[key] = await this.db.getColumns(rt);
+        }
+        const refPk = typeof this.db.getPrimaryKey === 'function'
+          ? await this.db.getPrimaryKey(rt)
+          : null;
+        const display = pickDisplayColumn(refColumnsMap[key], refPk);
+        if (!display) {
+          throw new Error(
+            `Could not auto-resolve a display column for referenced table "${rt}" ` +
+            '(no name/code column and no primary key found). Provide --fk-columns explicitly.'
+          );
+        }
+        fkSpec.push({ table: rt, column: display, raw: `${rt}.${display}` });
+        console.log(`  [AUTO]    ${tableName} -> ${rt}.${display} (display column)`);
+      }
+    } else {
+      // Eksplisit: parse spec lalu fetch kolom tabel referensi yang disebut.
+      fkSpec = parseFkColumns(fkColumnsStr);
+      const neededTables = new Set(fkSpec.map(s => s.table.toLowerCase()));
+      for (const fk of foreignKeys) {
+        const rt = fk && fk.references && fk.references.table;
+        if (!rt) continue;
+        const key = String(rt).toLowerCase();
+        if (!neededTables.has(key)) continue;
+        if (!refColumnsMap[key]) {
+          refColumnsMap[key] = await this.db.getColumns(rt);
+        }
+      }
+    }
+
+    return buildForeignKeyExpansion(payload, fkSpec, foreignKeys, refColumnsMap, baseColumns);
+  }
+
   /**
    * Regenerate payload berdasarkan perubahan yang terdeteksi.
    * Mempertahankan konfigurasi payload lama (action, filters, dll),
@@ -1202,6 +1852,17 @@ class SchemaValidator {
       : [];
     const primaryKey = await this.db.getPrimaryKey(tableName) || oldPayload.primaryKey;
 
+    // Enrich kolom (constraints + boolean) sekali; dipakai untuk searchable
+    // columns (datatablesWhere) dan fieldValidation. tempGenerator menyediakan
+    // method enrich/generate (instance method tanpa state).
+    const tempGenerator = new PayloadGenerator();
+    const booleanColumns = typeof this.db.getBooleanColumns === 'function'
+      ? await this.db.getBooleanColumns(tableName)
+      : [];
+    let enrichedColumns = tempGenerator.enrichDetailedColumnsWithConstraints(detailedColumns, constraints);
+    enrichedColumns = tempGenerator.enrichDetailedColumnsWithBoolean(enrichedColumns, booleanColumns);
+    const stringColumns = collectStringColumns(enrichedColumns);
+
     // Bangun fieldName baru: pertahankan urutan field lama, tambahkan field baru di akhir.
     // Kolom yang sebelumnya dicantumkan user di payload (termasuk kolom audit default)
     // dipertahankan. Kolom audit default yang tidak pernah ada di payload tidak
@@ -1225,26 +1886,42 @@ class SchemaValidator {
     updatedPayload.primaryKey = primaryKey;
     updatedPayload.fieldName = newFieldName;
 
-    // Re-generate datatablesQuery
+    // Re-generate datatablesQuery.
+    // Guard `file:` reference: bila datatablesQuery existing menunjuk ke file
+    // SQL external (mis. hasil --expand-fk: file:query/<table>-join.sql), JANGAN
+    // timpa dengan SQL inline. Kolom JOIN dikelola di file SQL tersebut, dan
+    // menimpanya akan menghapus konfigurasi JOIN sekaligus viewQuery. Hanya
+    // datatablesQuery inline (atau kosong) yang diregenerasi.
     const fieldsStr = newFieldName.join(', ');
-    updatedPayload.datatablesQuery = `select ${fieldsStr} from ${tableName}`;
+    const existingDq = typeof oldPayload.datatablesQuery === 'string'
+      ? oldPayload.datatablesQuery.trim()
+      : '';
+    if (!existingDq.startsWith('file:')) {
+      updatedPayload.datatablesQuery = `select ${fieldsStr} from ${tableName}`;
+    }
 
-    // Re-generate exportQuery jika ada
+    // Re-generate exportQuery jika ada (guard `file:` reference yang sama).
     if (oldPayload.exportQuery) {
-      updatedPayload.exportQuery = `select ${fieldsStr} from ${tableName}`;
+      const existingEq = typeof oldPayload.exportQuery === 'string'
+        ? oldPayload.exportQuery.trim()
+        : '';
+      if (!existingEq.startsWith('file:')) {
+        updatedPayload.exportQuery = `select ${fieldsStr} from ${tableName}`;
+      }
     }
 
-    // Re-generate datatablesWhere: pertahankan yang masih valid, tambahkan field baru yang searchable
+    // Re-generate datatablesWhere. Entri existing dipertahankan hanya bila masih
+    // ada di database DAN bertipe string; kolom non-string (mis. integer/boolean)
+    // dibuang karena memicu error runtime pada upper(col) LIKE upper(?). Pola
+    // nama (id/audit) TIDAK diterapkan ke entri existing agar kustomisasi string
+    // user yang sengaja ditambahkan tetap aman. Kolom baru dari drift ditambahkan
+    // memakai heuristik default penuh (name-exclude + string).
     if (oldPayload.datatablesWhere) {
-      const excludePatterns = ['_id', '_at', '_by', 'created', 'updated', 'deleted'];
       const validWhere = oldPayload.datatablesWhere.filter(
-        w => w === 'all' || newFieldName.includes(w)
+        w => w === 'all' || (newFieldName.includes(w) && stringColumns.has(w))
       );
-      // Tambahkan field baru yang searchable
       for (const col of comparison.added) {
-        const fieldLower = col.column.toLowerCase();
-        const isSearchable = !excludePatterns.some(pattern => fieldLower.includes(pattern));
-        if (isSearchable && !validWhere.includes(col.column)) {
+        if (isDefaultSearchableColumn(col.column, stringColumns) && !validWhere.includes(col.column)) {
           // Sisipkan sebelum 'all'
           const allIdx = validWhere.indexOf('all');
           if (allIdx >= 0) {
@@ -1257,8 +1934,7 @@ class SchemaValidator {
       updatedPayload.datatablesWhere = validWhere;
     }
 
-    // Re-generate dateTimeFields
-    const tempGenerator = new PayloadGenerator();
+    // Re-generate dateTimeFields (tempGenerator & enrichedColumns sudah disiapkan di atas)
     const dateTimeFields = tempGenerator.generateDateTimeFields(columnTypes, newFieldName);
     if (Object.keys(dateTimeFields).length > 0) {
       updatedPayload.dateTimeFields = dateTimeFields;
@@ -1267,11 +1943,6 @@ class SchemaValidator {
     }
 
     // Re-generate fieldValidation
-    const booleanColumns = typeof this.db.getBooleanColumns === 'function'
-      ? await this.db.getBooleanColumns(tableName)
-      : [];
-    let enrichedColumns = tempGenerator.enrichDetailedColumnsWithConstraints(detailedColumns, constraints);
-    enrichedColumns = tempGenerator.enrichDetailedColumnsWithBoolean(enrichedColumns, booleanColumns);
     const fieldValidation = tempGenerator.generateFieldValidation(enrichedColumns, newFieldName, primaryKey);
     if (fieldValidation.length > 0) {
       updatedPayload.fieldValidation = fieldValidation;
@@ -1297,6 +1968,12 @@ class SchemaValidator {
       fileName: options.fileName
     });
 
+    // Built-in defaultScope berbasis is_active: tambahkan filter saat kolom
+    // is_active ada di fieldName, atau lepas saat kolom sudah tidak ada lagi di
+    // tabel (mis. kolom dihapus). Hanya menyentuh key is_active sehingga scope
+    // kustom lain tetap dipertahankan (lihat catalogs/rdf/default-scope.md).
+    applyIsActiveDefaultScope(updatedPayload, newFieldName.includes(IS_ACTIVE_COLUMN));
+
     return updatedPayload;
   }
 
@@ -1371,5 +2048,13 @@ class SchemaValidator {
 
 module.exports = {
   PayloadGenerator,
-  SchemaValidator
+  SchemaValidator,
+  parseFkColumns,
+  deriveTableAlias,
+  pickDisplayColumn,
+  buildForeignKeyExpansion,
+  collectStringColumns,
+  isDefaultSearchableColumn,
+  applyIsActiveDefaultScope,
+  buildPayloadAdvisories
 };