@restforgejs/platform 5.1.0 → 5.1.4

package/generators/lib/data/push-runner.js

@@ -0,0 +1,382 @@
+'use strict';
+
+/**
+ * push-runner — Business logic command `data push` (append-only, amandemen A6).
+ *
+ * Push bersifat append-only: tidak ada pilihan mode. Mode `upsert`/`replace`
+ * di-descope dari v1 (User konfirmasi 2026-06-03), sehingga flag `--mode`/`--force`
+ * dihapus dari contract dan runner tidak lagi membaca/memvalidasi keduanya.
+ *
+ * `run()` adalah dispatcher (single vs all-tables); `runOne(ir, ctx)` mengeksekusi
+ * push satu tabel dan mengelola executor-nya sendiri (Phase 03, data-pull-push-v2).
+ *
+ * Alur dispatcher `run()`:
+ *   1. Resolve config DB tujuan (config-resolver) → loadConfig (dbschema-kit/connection); SEKALI.
+ *   2. Validasi mutual-exclusive (sebelum load SDF / koneksi DB): tepat satu dari
+ *      --table / --all-tables (keduanya / tidak keduanya → exit 2).
+ *   3. Load SDF SEKALI → Map<qualifiedName, IR> (sdf-reader).
+ *   4a. Jalur --table:      findTableOrThrow → runOne(ir, ctx) → ringkasan single (regresi nol).
+ *   4b. Jalur --all-tables: topoSortByFk(models) → urutan parent→child (table-order); siklus →
+ *       warning stderr + fallback urutan deklarasi. Loop FAIL-FAST (Q3); tabel tanpa file
+ *       input di-SKIP (warning stderr, catat di skipped[], lanjut) → runOne per IR → agregat.
+ *
+ * Alur `runOne(ir, ctx)` (per tabel; metadata kolom/namespace/PK murni dari SDF IR):
+ *   a. Derive nama file dari SDF (aturan IDENTIK pull): {cwd}/{input}/{qualifiedName}.json.
+ *      File tidak ada → exit 1. Baca + parseEnvelope + validateEnvelope (shape invalid → exit 1).
+ *   b. Column match vs SDF (BUKAN introspeksi DB): tiap envelope.columns[].name harus ada
+ *      di SDF dan tipe konsisten. Mismatch → exit 1. No-PK guard (exit 1).
+ *   c. Connect (db-executor) + validasi identifier tabel/kolom (anti-injection).
+ *   d. INSERT batch + commit per batch: tiap nilai di-decode (value-codec) per dialect tujuan,
+ *      INSERT parameterized per baris dirakit via dialect helper (placeholder) dan dijalankan
+ *      via executeTransaction (commit per batch). Append: konflik PK = error DB (exit 3).
+ *   e. Disconnect (selalu, di finally).
+ *
+ * Exit code: 0 sukses; 1 operational (file tidak ada, envelope invalid, column mismatch
+ * vs SDF, no-PK anomali); 2 usage/precondition (--config wajib, mutual-exclusive, tabel
+ * tak terdaftar/ambigu di SDF); 3 database error (koneksi maupun INSERT, termasuk konflik
+ * PK pada append). Handler tidak memanggil process.exit() sendiri.
+ *
+ * @module generators/lib/data/push-runner
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { resolveConfig, printDefaultConfigWarning } = require('../utils/config-resolver');
+const { loadConfig } = require('../dbschema-kit/connection');
+const {
+    loadSdf,
+    findTableOrThrow,
+    irToColumns,
+    getNamespace,
+    getPrimaryKey
+} = require('./sdf-reader');
+const { createDialect, validateIdentifier, placeholder } = require('./dialect-kit');
+const { createExecutor } = require('./db-executor');
+const { decodeValue } = require('./value-codec');
+const { parseEnvelope, validateEnvelope } = require('./envelope');
+const { topoSortByFk } = require('./table-order');
+
+const DEFAULT_BATCH_SIZE = 1000;
+
+/**
+ * Buat Error dengan exitCode terlampir (override default dispatcher).
+ * @param {string} message
+ * @param {number} exitCode
+ * @returns {Error}
+ */
+function failWith(message, exitCode) {
+    const err = new Error(message);
+    err.exitCode = exitCode;
+    return err;
+}
+
+/**
+ * Petakan `config.dialect` internal ke bentuk DB_TYPE kanonik untuk output.
+ *
+ * `loadConfig` memetakan `DB_TYPE=postgresql` menjadi `dialect='postgres'`; output
+ * push (`target_dialect`) memakai bentuk kanonik `postgresql`, konsisten dengan
+ * `source_dialect` pull (pull-runner.canonicalSourceDialect). Dialect lain identik.
+ *
+ * @param {string} dialect - config.dialect ('postgres'|'mysql'|'oracle'|'sqlite')
+ * @returns {string} 'postgresql'|'mysql'|'oracle'|'sqlite'
+ */
+function canonicalTargetDialect(dialect) {
+    return dialect === 'postgres' ? 'postgresql' : dialect;
+}
+
+/**
+ * Normalisasi nilai integer non-negatif dari flag.
+ * @param {*} value
+ * @param {number|null} fallback
+ * @returns {number|null}
+ */
+function normalizeInt(value, fallback) {
+    if (typeof value === 'number' && Number.isFinite(value) && value >= 0) {
+        return Math.trunc(value);
+    }
+    return fallback;
+}
+
+/**
+ * Validasi tiap kolom envelope terhadap metadata SDF (tanpa menyentuh DB).
+ *
+ * Setiap `envelope.columns[].name` wajib terdeklarasi di SDF dengan tipe canonical
+ * yang konsisten. Kolom SDF yang tidak muncul di envelope diperbolehkan (akan
+ * memakai default/NULL DB pada INSERT). Mismatch (kolom tak dikenal di SDF, atau
+ * tipe berbeda) → throw exitCode=1.
+ *
+ * @param {Array<{name: string, type: string}>} envelopeColumns
+ * @param {Array<{name: string, type: string}>} sdfColumns
+ * @param {string} tableName - untuk pesan error
+ * @returns {Array<{name: string, type: string}>} kolom yang akan di-INSERT (urutan envelope)
+ * @throws {Error} exitCode=1 bila ada kolom tak dikenal atau tipe berbeda
+ */
+function matchColumns(envelopeColumns, sdfColumns, tableName) {
+    const sdfByName = new Map(sdfColumns.map((c) => [c.name, c]));
+    const insertColumns = [];
+    for (const ec of envelopeColumns) {
+        const sc = sdfByName.get(ec.name);
+        if (!sc) {
+            throw failWith(
+                `Column '${ec.name}' in envelope is not declared in SDF for table '${tableName}'.`,
+                1
+            );
+        }
+        if (sc.type !== ec.type) {
+            throw failWith(
+                `Column '${ec.name}' type mismatch for table '${tableName}': envelope '${ec.type}' vs SDF '${sc.type}'.`,
+                1
+            );
+        }
+        insertColumns.push({ name: ec.name, type: ec.type });
+    }
+    return insertColumns;
+}
+
+/**
+ * Push satu tabel SDF dari file envelope JSON `<input>/<qualifiedName>.json` ke DB.
+ *
+ * Mengelola executor-nya sendiri (buat → disconnect di finally) agar isolasi
+ * per-tabel jelas dan jalur --all-tables dapat memanggilnya berulang tanpa kebocoran
+ * koneksi. Metadata kolom, namespace, dan PK murni dari IR.
+ *
+ * @param {Object} ir - IR model SDF satu tabel
+ * @param {Object} ctx - konteks resolusi sekali-pakai
+ * @param {Object} ctx.config - config DB hasil loadConfig
+ * @param {string} ctx.targetDialect - dialect kanonik (untuk output, dirakit caller)
+ * @param {Object} ctx.args - argumen ter-parse (storage-path, batch-size)
+ * @param {string} ctx.cwd - working directory
+ * @returns {Promise<{table: string, rows: number, committed_batches: number}>}
+ */
+async function runOne(ir, ctx) {
+    const { config, args, cwd } = ctx;
+
+    const sdfColumns = irToColumns(ir);
+    const { qualifiedName } = getNamespace(ir);
+    const rawPk = getPrimaryKey(ir);
+    const pk = Array.isArray(rawPk) ? rawPk : [];
+
+    // ── a. Derive nama file dari SDF (aturan IDENTIK pull) + baca envelope ─────────
+    // Nama file = {input}/{qualifiedName}.json, turunan murni dari SDF (bukan --table
+    // mentah). Konsisten dengan pull (lihat phase-02b Keputusan K2): tabel ber-schema
+    // → `<schema>.<table>.json`; tanpa schema → `<table>.json`. Single-table:
+    // file-not-found = exit 1 (tak berubah). Jalur --all-tables menyaring file-missing
+    // SEBELUM memanggil runOne (skip-missing), jadi guard ini hanya tercapai pada single.
+    const inputDir = path.resolve(cwd, args['storage-path']);
+    const inFile = path.join(inputDir, `${qualifiedName}.json`);
+    if (!fs.existsSync(inFile)) {
+        const rel = path.relative(cwd, inFile).split(path.sep).join('/');
+        throw failWith(`Input file not found: ${rel}`, 1);
+    }
+
+    let envelope;
+    try {
+        const raw = fs.readFileSync(inFile, 'utf8');
+        envelope = validateEnvelope(parseEnvelope(raw));
+    } catch (e) {
+        // parseEnvelope/validateEnvelope sudah ber-exitCode=1; baca file gagal lain → 1.
+        if (Number.isInteger(e.exitCode)) throw e;
+        throw failWith(`Failed to read envelope '${path.relative(cwd, inFile).split(path.sep).join('/')}': ${e.message}`, 1);
+    }
+
+    // ── b. Column match vs SDF (tanpa introspeksi DB) + no-PK guard ──────────────
+    const insertColumns = matchColumns(envelope.columns, sdfColumns, ir.tableName);
+
+    // No-PK = anomali: schema-validator MEWAJIBKAN primary key, jadi IR yang lolos load
+    // SDF pasti punya PK. Bila tetap kosong (mis. IR diinjeksi), gagal jelas lebih aman.
+    // Selaras pull-runner (phase-02b Keputusan K3).
+    if (pk.length === 0) {
+        throw failWith(`Table '${ir.tableName}' has no primary key in SDF (unexpected)`, 1);
+    }
+
+    // ── c. Validasi identifier (anti-injection) + siapkan executor ───────────────
+    const dialect = createDialect(config.dialect);
+    validateIdentifier(dialect, qualifiedName);
+    for (const col of insertColumns) validateIdentifier(dialect, col.name);
+
+    const batchSize = normalizeInt(args['batch-size'], DEFAULT_BATCH_SIZE) || DEFAULT_BATCH_SIZE;
+    const executor = createExecutor(config);
+
+    // ── d. INSERT batch + commit per batch ───────────────────────────────────────
+    // INSERT parameterized per-baris (dirakit via dialect.placeholder), dijalankan
+    // per batch dalam SATU executeTransaction → commit per batch. Pilihan per-baris
+    // (bukan multi-row VALUES) menjaga paritas lintas-dialect: Oracle tidak mendukung
+    // `VALUES (..),(..)` multi-row. Kegagalan satu batch me-rollback batch tsb.;
+    // batch sebelumnya tetap ter-commit (risiko partial, didokumentasikan Poin 5/8).
+    const colList = insertColumns.map((c) => c.name).join(', ');
+    const valuesClause = insertColumns.map((_, i) => placeholder(dialect, i + 1)).join(', ');
+    const insertSql = `INSERT INTO ${qualifiedName} (${colList}) VALUES (${valuesClause})`;
+
+    let rowCount = 0;
+    let committedBatches = 0;
+    try {
+        const rows = envelope.rows;
+        for (let start = 0; start < rows.length; start += batchSize) {
+            const slice = rows.slice(start, start + batchSize);
+            const queries = slice.map((row) => ({
+                sql: insertSql,
+                params: insertColumns.map((c) => decodeValue(row[c.name], c.type, config.dialect))
+            }));
+            await executor.executeTransaction(queries);
+            committedBatches += 1;
+            rowCount += slice.length;
+        }
+    } catch (e) {
+        // exitCode yang sudah di-set dipertahankan; selain itu error lapisan DB
+        // (connect/INSERT, termasuk konflik PK pada append) dipetakan ke exit 3.
+        if (Number.isInteger(e.exitCode)) throw e;
+        throw failWith(`Database error during push: ${e.message}`, 3);
+    } finally {
+        try { await executor.disconnect(); } catch (_e) { /* ignore */ }
+    }
+
+    // ── e. Ringkasan per-tabel (tanpa command/target_dialect; dirakit caller) ─────
+    return {
+        table: ir.tableName,
+        rows: rowCount,
+        committed_batches: committedBatches
+    };
+}
+
+/**
+ * Jalankan command `data push` (dispatcher: single-table vs --all-tables, append-only).
+ * @param {Object} args - argumen ter-parse dari contract
+ * @returns {Promise<Object>} ringkasan single { command, table, rows, target_dialect, committed_batches }
+ *   atau agregat { command, all_tables, table_count, total_rows, tables: [...], skipped: [...] }
+ */
+async function run(args) {
+    const cwd = process.cwd();
+
+    // ── 1. Resolve config DB tujuan (SEKALI) ─────────────────────────────────────
+    const resolved = resolveConfig(args.config, cwd);
+    if (!resolved) {
+        process.stderr.write(
+            "Tip: set a default with 'npx restforge config set-default --config=<file>' to omit --config in future runs\n"
+        );
+        throw failWith('--config=<file> is required.', 2);
+    }
+    if (resolved.source === 'default') {
+        printDefaultConfigWarning(resolved.defaultName);
+    }
+
+    let config;
+    try {
+        config = loadConfig(resolved.path);
+    } catch (e) {
+        throw failWith(e.message, 2);
+    }
+
+    // ── 2. Validasi mutual-exclusive --table / --all-tables (SEBELUM SDF/DB) ──────
+    // Arg-parser tidak punya mekanisme XOR lintas-flag (hanya `required` per-flag),
+    // sehingga "tepat satu" ditegakkan di sini. Exit 2 (precondition/usage). Identik
+    // pull-runner Phase 02.
+    const hasTable = args.table != null && args.table !== '';
+    const hasAll = args['all-tables'] === true;
+    if (hasTable && hasAll) {
+        throw failWith('Specify exactly one of --table or --all-tables.', 2);
+    }
+    if (!hasTable && !hasAll) {
+        throw failWith('Specify either --table=<name> or --all-tables.', 2);
+    }
+
+    // ── 3. Load SDF (SEKALI) ─────────────────────────────────────────────────────
+    const schemaPath = args['schema-path'];
+    const absSchemaPath = path.resolve(cwd, schemaPath);
+    let models;
+    try {
+        models = loadSdf(absSchemaPath);
+    } catch (e) {
+        // Error baca SDF (path tidak ada, parse gagal) = operational.
+        throw failWith(e.message, 1);
+    }
+
+    const ctx = {
+        config,
+        targetDialect: canonicalTargetDialect(config.dialect),
+        args,
+        cwd
+    };
+
+    // ── 4a. Jalur --table (single; regresi nol) ──────────────────────────────────
+    if (hasTable) {
+        const ir = findTableOrThrow(models, args.table); // throw exitCode=2 bila tak terdaftar/ambigu
+        const per = await runOne(ir, ctx);
+        const summary = {
+            command: 'push',
+            table: per.table,
+            rows: per.rows,
+            target_dialect: ctx.targetDialect,
+            committed_batches: per.committed_batches
+        };
+
+        if (args.json === true) {
+            process.stdout.write(JSON.stringify(summary) + '\n');
+        } else {
+            process.stdout.write(
+                `Pushed ${per.rows} rows to ${per.table} (dialect: ${ctx.targetDialect}, batches: ${per.committed_batches})\n`
+            );
+        }
+        return summary;
+    }
+
+    // ── 4b. Jalur --all-tables (topo-sort FK parent→child, fail-fast Q3, skip-missing) ──
+    // Urutan push diturunkan dari FK SDF: parent (tabel direferensikan) SEBELUM child
+    // agar INSERT child tidak melanggar FK constraint. Siklus → fallback urutan deklarasi.
+    const { ordered, cycle } = topoSortByFk(models);
+    if (cycle) {
+        process.stderr.write('FK cycle detected; falling back to declaration order\n');
+    }
+
+    // Skip-missing HANYA di --all-tables: tabel tanpa file input dilewati (warning +
+    // catat), bukan error. Catatan (Phase 05): bila parent di-skip namun child ada,
+    // INSERT child dapat melanggar FK → muncul sebagai DB error exit 3 (fail-fast).
+    const inputDir = path.resolve(cwd, args['storage-path']);
+    const tables = [];
+    const skipped = [];
+    let totalRows = 0;
+
+    for (const ir of ordered) {
+        const { qualifiedName } = getNamespace(ir);
+        const inFile = path.join(inputDir, `${qualifiedName}.json`);
+        if (!fs.existsSync(inFile)) {
+            process.stderr.write(`Skipped ${ir.tableName}: input file not found\n`);
+            skipped.push(ir.tableName);
+            continue;
+        }
+
+        const per = await runOne(ir, ctx); // fail-fast (Q3)
+        tables.push(per);
+        totalRows += per.rows;
+        if (args.json !== true) {
+            process.stdout.write(
+                `Pushed ${per.rows} rows to ${per.table} (dialect: ${ctx.targetDialect}, batches: ${per.committed_batches})\n`
+            );
+        }
+    }
+
+    const aggregate = {
+        command: 'push',
+        all_tables: true,
+        table_count: tables.length,
+        total_rows: totalRows,
+        tables,
+        skipped
+    };
+
+    if (args.json === true) {
+        process.stdout.write(JSON.stringify(aggregate) + '\n');
+    } else {
+        process.stdout.write(
+            `Done: ${tables.length} tables, ${totalRows} rows total (skipped: ${skipped.length})\n`
+        );
+    }
+
+    return aggregate;
+}
+
+module.exports = {
+    run,
+    // Diekspor untuk reuse/test internal.
+    _internal: { runOne, matchColumns, normalizeInt, canonicalTargetDialect }
+};

package/generators/lib/data/sdf-reader.js

@@ -0,0 +1,132 @@
+'use strict';
+
+/**
+ * sdf-reader — Sumber metadata tabel untuk `data pull` / `data push`.
+ *
+ * Seluruh metadata (daftar kolom, tipe canonical, nullable, primary key composite)
+ * dibaca murni dari SDF IR (Schema Definition File), TANPA introspeksi DB. Modul ini
+ * mereuse loader existing `dbschema-kit/loader` dan tidak membuka koneksi database.
+ *
+ * Keputusan arah: amandemen A2 (SDF sebagai sumber kebenaran tabel) dan A3 (deteksi
+ * binary by-omission — SDF hanya bisa menyimpan 10 tipe canonical, jadi kolom binary
+ * mustahil muncul). Lihat docs/plan/data-pull-push/data-pull-push-09-amendments.md.
+ *
+ * @module generators/lib/data/sdf-reader
+ */
+
+const { loadSchemaPath } = require('../dbschema-kit/loader');
+
+/**
+ * Muat SDF dari file atau folder menjadi Map<qualifiedName, IR>.
+ *
+ * Delegasi langsung ke loader existing — tidak ada introspeksi DB. `schemaPath`
+ * boleh menunjuk satu file `.js` atau folder berisi banyak file SDF.
+ *
+ * @param {string} schemaPath - Path ke file atau folder SDF
+ * @returns {Map<string, Object>} Map qualifiedName → IR model
+ */
+function loadSdf(schemaPath) {
+  return loadSchemaPath(schemaPath);
+}
+
+/**
+ * Cari satu IR dari Map hasil loadSdf berdasarkan argumen tabel.
+ *
+ * Urutan pencocokan:
+ *   1. Match eksak via qualifiedName (key Map) → selalu satu entry, tidak ambigu.
+ *   2. Match via `ir.tableName` (arg tanpa schema). Bila cocok dengan LEBIH DARI SATU
+ *      entry (nama tabel sama di schema berbeda), arg dianggap ambigu → throw exitCode=2
+ *      yang meminta bentuk qualified `schema.table`.
+ *
+ * Mereuse pola table-guard di cli/schema/apply.js:303-314. Bila tidak ditemukan,
+ * throw Error dengan `err.exitCode = 2` (precondition) — penolakan terjadi SEBELUM
+ * koneksi DB dibuka oleh caller.
+ *
+ * @param {Map<string, Object>} models - Hasil loadSdf
+ * @param {string} tableArg - Nilai flag --table
+ * @returns {Object} IR model yang cocok
+ * @throws {Error} exitCode=2 bila tabel tidak terdaftar ATAU ambigu lintas-schema
+ */
+function findTableOrThrow(models, tableArg) {
+  // 1. Match eksak via qualifiedName (key Map) — kunci Map unik, selalu satu entry.
+  if (models.has(tableArg)) {
+    return models.get(tableArg);
+  }
+
+  // 2. Match via tableName tanpa schema — bisa lebih dari satu bila nama tabel sama
+  //    di schema berbeda.
+  const byTableName = [];
+  for (const ir of models.values()) {
+    if (ir.tableName === tableArg) {
+      byTableName.push(ir);
+    }
+  }
+
+  if (byTableName.length === 1) {
+    return byTableName[0];
+  }
+  if (byTableName.length > 1) {
+    const err = new Error(
+      `Table '${tableArg}' is ambiguous across schemas; specify 'schema.table'.`
+    );
+    err.exitCode = 2;
+    throw err;
+  }
+
+  const err = new Error(`Table '${tableArg}' not found in SDF.`);
+  err.exitCode = 2;
+  throw err;
+}
+
+/**
+ * Transformasi IR menjadi array kolom envelope.
+ *
+ * Murni in-memory, tanpa I/O. Urutan kolom mengikuti urutan deklarasi field di SDF
+ * (`Object.keys(ir.fields)`).
+ *
+ * @param {Object} ir - IR model dari SDF
+ * @returns {Array<{name: string, type: string, nullable: boolean, primary_key: boolean}>}
+ */
+function irToColumns(ir) {
+  const primaryKey = Array.isArray(ir.primaryKey) ? ir.primaryKey : [];
+  return Object.keys(ir.fields).map((name) => {
+    const field = ir.fields[name];
+    return {
+      name,
+      type: field.type,
+      nullable: field.notnull !== true,
+      primary_key: primaryKey.includes(name)
+    };
+  });
+}
+
+/**
+ * Ambil namespace (schema DB) dari IR.
+ *
+ * @param {Object} ir - IR model dari SDF
+ * @returns {{schemaName: (string|null), qualifiedName: string}}
+ */
+function getNamespace(ir) {
+  return {
+    schemaName: ir.schemaName || null,
+    qualifiedName: ir.qualifiedName || ir.tableName
+  };
+}
+
+/**
+ * Ambil daftar primary key (mendukung composite).
+ *
+ * @param {Object} ir - IR model dari SDF
+ * @returns {string[]} Array nama kolom primary key
+ */
+function getPrimaryKey(ir) {
+  return ir.primaryKey;
+}
+
+module.exports = {
+  loadSdf,
+  findTableOrThrow,
+  irToColumns,
+  getNamespace,
+  getPrimaryKey
+};

package/generators/lib/data/table-order.js

@@ -0,0 +1,126 @@
+'use strict';
+
+/**
+ * table-order — Topological sort tabel SDF berdasarkan foreign key (parent→child).
+ *
+ * `data push` bersifat append (INSERT), sehingga tabel CHILD (pemilik kolom FK)
+ * wajib di-push SETELAH tabel PARENT (tabel yang direferensikan), agar INSERT child
+ * tidak melanggar FK constraint. Helper ini menurunkan urutan tersebut MURNI dari
+ * IR SDF, tanpa I/O maupun koneksi DB.
+ *
+ * Edge dipungut dari `ir.fields[<col>].fk.table` (arah: parent SEBELUM child). FK
+ * target selalu nama tabel polos (shorthand `fk:` tidak mendukung lintas-schema —
+ * lihat phase-00-discovery Deliverable 1), jadi pemetaan `fk.table → IR` dilakukan
+ * via index `tableName → IR`.
+ *
+ * Penanganan kasus tepi:
+ *   - Self-FK (`fk.table === ir.tableName`)          → edge diabaikan (bukan siklus).
+ *   - Target tak dikenal (tak ada di `models`, R2)    → edge diabaikan (jangan crash).
+ *   - `tableName` duplikat antar-schema (R1)          → ambiguous; edge yang menunjuk
+ *     nama itu diabaikan (no-edge). v2 berasumsi single-namespace.
+ *   - Siklus FK (R5)                                  → `cycle:true`; `ordered` =
+ *     urutan deklarasi (insertion order Map). Runner mencetak warning + fallback.
+ *
+ * @module generators/lib/data/table-order
+ */
+
+/**
+ * Identitas node = qualifiedName (kunci unik Map). `tableName` bisa duplikat antar
+ * schema, sehingga tidak aman dipakai sebagai identitas node.
+ * @param {Object} ir
+ * @returns {string}
+ */
+function nodeKeyOf(ir) {
+  return ir.qualifiedName || ir.tableName;
+}
+
+/**
+ * Urutkan tabel secara topologis berdasarkan FK (Kahn's algorithm).
+ *
+ * @param {Map<string, Object>} models - Map<qualifiedName, IR> hasil loadSdf.
+ * @returns {{ ordered: Object[], cycle: boolean }} `ordered` = IR parent→child
+ *   (atau urutan deklarasi bila siklus); `cycle` = true bila siklus terdeteksi.
+ */
+function topoSortByFk(models) {
+  const irs = [...models.values()];
+
+  // Index tableName → IR. Bila >1 IR berbagi tableName (duplikat antar-schema, R1),
+  // nama itu ambiguous: edge yang menargetkannya akan diabaikan (no-edge).
+  const byTableName = new Map();
+  const ambiguous = new Set();
+  for (const ir of irs) {
+    const tn = ir.tableName;
+    if (byTableName.has(tn)) {
+      ambiguous.add(tn);
+    } else {
+      byTableName.set(tn, ir);
+    }
+  }
+
+  // Graph: node = nodeKey (qualifiedName). `indegree` = jumlah parent; `children`
+  // = parentKey → Set<childKey>. Inisialisasi semua node dengan indegree 0.
+  const indegree = new Map();
+  const children = new Map();
+  for (const ir of irs) {
+    indegree.set(nodeKeyOf(ir), 0);
+    children.set(nodeKeyOf(ir), new Set());
+  }
+
+  // Pungut edge unik (parent → child) dari fk.table tiap field.
+  for (const childIr of irs) {
+    const childKey = nodeKeyOf(childIr);
+    for (const fieldName of Object.keys(childIr.fields)) {
+      const field = childIr.fields[fieldName];
+      const fk = field && field.fk;
+      if (!fk || !fk.table) continue;
+
+      const parentName = fk.table; // nama tabel polos
+
+      // Self-FK → bukan siklus, abaikan edge.
+      if (parentName === childIr.tableName) continue;
+      // Target tak dikenal (SDF parsial, R2) → abaikan edge.
+      if (!byTableName.has(parentName)) continue;
+      // Duplikat antar-schema (R1) → ambiguous, perlakukan sebagai no-edge.
+      if (ambiguous.has(parentName)) continue;
+
+      const parentKey = nodeKeyOf(byTableName.get(parentName));
+      // Self lewat qualifiedName (defensif) → abaikan.
+      if (parentKey === childKey) continue;
+
+      // Edge ganda (mis. dua kolom FK ke tabel sama) dihitung sekali.
+      if (!children.get(parentKey).has(childKey)) {
+        children.get(parentKey).add(childKey);
+        indegree.set(childKey, indegree.get(childKey) + 1);
+      }
+    }
+  }
+
+  // Kahn: antrekan node indegree 0 dalam URUTAN DEKLARASI (insertion order Map),
+  // proses children juga dalam urutan penyisipan (= urutan deklarasi child), agar
+  // hasil deterministik dan stabil untuk tabel tanpa FK.
+  const irByKey = new Map(irs.map((ir) => [nodeKeyOf(ir), ir]));
+  const queue = [];
+  for (const ir of irs) {
+    if (indegree.get(nodeKeyOf(ir)) === 0) queue.push(nodeKeyOf(ir));
+  }
+
+  const orderedKeys = [];
+  while (queue.length > 0) {
+    const key = queue.shift();
+    orderedKeys.push(key);
+    for (const childKey of children.get(key)) {
+      const next = indegree.get(childKey) - 1;
+      indegree.set(childKey, next);
+      if (next === 0) queue.push(childKey);
+    }
+  }
+
+  // Bila tidak semua node ter-emit, ada siklus (R5): fallback urutan deklarasi.
+  if (orderedKeys.length !== irs.length) {
+    return { ordered: irs.slice(), cycle: true };
+  }
+
+  return { ordered: orderedKeys.map((key) => irByKey.get(key)), cycle: false };
+}
+
+module.exports = { topoSortByFk };