@restforgejs/platform 5.1.0 → 5.1.6

package/generators/cli/init.js

@@ -1,97 +1,347 @@
-'use strict';
-
-/**
- * Contract: init (verb global)
- *
- * Generate starter config file di working directory. Membuat
- * `config/db-connection.env` sebagai template starting point.
- *
- * Inline migration v4.0.0: business logic asli dari `init.js` di-inline
- * langsung ke handler. Adapter `process.argv` override dihapus. `process.exit()`
- * di legacy dikonversi menjadi `throw new Error(...)` agar `cli-entry.js` yang
- * handle exit code.
- *
- * Catatan: contract ini global verb (snapshot key = `init`, bukan
- * `<resource>/init`). Struktur file di `generators/cli/init.js` (root cli/
- * directory, bukan subdirectory resource).
- */
-
-const path = require('node:path');
-const fs = require('node:fs');
-const { DB_CONNECTION_ENV_TEMPLATE: TEMPLATE_ENV } = require('../lib/templates/db-connection-env');
-
-module.exports = {
-    verb: 'init',
-    description: 'Generate starter config file (config/db-connection.env) di working directory',
-    category: 'utility',
-    flags: {
-        force: {
-            type: 'boolean',
-            required: false,
-            default: false,
-            description: 'Timpa file existing tanpa konfirmasi'
-        }
-    },
-    examples: [
-        'npx restforge init',
-        'npx restforge init --force'
-    ],
-    async handler(args) {
-        const workingDir = process.cwd();
-
-        console.log('');
-        console.log('RESTForge - Init');
-        console.log('====================');
-        console.log('');
-
-        const files = [
-            {
-                relativePath: path.join('config', 'db-connection.env'),
-                content: TEMPLATE_ENV
-            }
-        ];
-
-        for (const file of files) {
-            file.absolutePath = path.resolve(workingDir, file.relativePath);
-        }
-
-        const existingFiles = files.filter(f => fs.existsSync(f.absolutePath));
-
-        if (existingFiles.length > 0 && !args.force) {
-            console.log('WARNING: The following files already exist:');
-            console.log('');
-            for (const file of existingFiles) {
-                console.log(`  ${file.relativePath}`);
-            }
-            console.log('');
-            console.log('Use --force to overwrite:');
-            console.log('  npx restforge init --force');
-            console.log('');
-            throw new Error(`${existingFiles.length} file(s) already exist. Use --force to overwrite.`);
-        }
-
-        const dirs = [
-            path.resolve(workingDir, 'config')
-        ];
-
-        for (const dir of dirs) {
-            if (!fs.existsSync(dir)) {
-                fs.mkdirSync(dir, { recursive: true });
-            }
-        }
-
-        for (const file of files) {
-            fs.writeFileSync(file.absolutePath, file.content, 'utf8');
-            console.log(`  Created: ${file.relativePath}`);
-        }
-
-        console.log('');
-        console.log('Done! Sample files generated successfully.');
-        console.log('');
-        console.log('Next Steps:');
-        console.log('');
-        console.log('  1. Edit config/db-connection.env');
-        console.log('     Update database credentials (DB_HOST, DB_USER, DB_PASSWORD, DB_NAME)');
-        console.log('');
-    }
-};
+'use strict';
+
+/**
+ * Contract: init (verb global)
+ *
+ * Generate starter config file di working directory. Membuat
+ * `config/<nama-file>.env` sebagai template starting point.
+ *
+ * Dua mode operasi:
+ *   1. Interaktif (default, hanya saat stdin TTY dan TANPA --force):
+ *      dialog konfirmasi gaya fast-track. Meminta input LICENSE, tipe database
+ *      beserta atributnya, dan nama file config (default db-connection.env, bisa
+ *      di-custom). Nilai input di-patch ke template lalu ditulis.
+ *   2. Non-interaktif (saat --force diberikan ATAU stdin bukan TTY):
+ *      menulis template apa adanya ke config/db-connection.env (perilaku legacy).
+ *      Jalur ini dipakai oleh orkestrator (fast-track) dan playbook yang
+ *      memanggil `npx restforge init --force`, sehingga harus tetap deterministik
+ *      tanpa prompt.
+ *
+ * Catatan kompatibilitas: `--force` sengaja mempertahankan semantik non-interaktif
+ * agar pemanggil existing (fast-track.js, restforge-playbook) tidak menggantung.
+ * Tidak ada flag baru ditambahkan sehingga snapshot contract tidak berubah.
+ *
+ * Catatan: contract ini global verb (snapshot key = `init`, bukan
+ * `<resource>/init`). Struktur file di `generators/cli/init.js` (root cli/
+ * directory, bukan subdirectory resource).
+ */
+
+const path = require('node:path');
+const fs = require('node:fs');
+const readline = require('node:readline');
+const { DB_CONNECTION_ENV_TEMPLATE: TEMPLATE_ENV } = require('../lib/templates/db-connection-env');
+
+// ---------------------------------------------------------------------------
+// Default konfigurasi (selaras dengan placeholder pada template db-connection.env)
+// ---------------------------------------------------------------------------
+
+const DEFAULT_CONFIG_FILE = 'db-connection.env';
+
+const DB_DEFAULTS = {
+    LICENSE: 'XXXX-XXXX-XXXX-XXXX',
+    DB_TYPE: 'postgresql',
+    DB_HOST: '127.0.0.1',
+    DB_PORT: '5432',
+    DB_USER: 'postgres',
+    DB_PASSWORD: 'your_password_here',
+    DB_NAME: 'your_database_name',
+    DB_FILE: './data/myapp.db'
+};
+
+// Override DB_PORT/DB_USER/DB_NAME menyesuaikan DB_TYPE yang dipilih; bila tidak
+// terdaftar, fallback ke DB_DEFAULTS (selaras dengan fast-track).
+const DB_TYPE_DEFAULTS = {
+    postgresql: { DB_PORT: '5432', DB_USER: 'postgres' },
+    postgres:   { DB_PORT: '5432', DB_USER: 'postgres' },
+    mysql:      { DB_PORT: '3306', DB_USER: 'root' },
+    oracle:     { DB_PORT: '1521', DB_USER: 'oracle', DB_NAME: 'ORCL' }
+};
+
+const SUPPORTED_DB_TYPES = ['postgresql', 'mysql', 'oracle', 'sqlite'];
+
+// ---------------------------------------------------------------------------
+// Helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Prompter sederhana berbasis readline.question. init interaktif hanya berjalan
+ * pada TTY (lihat handler), sehingga tidak butuh penanganan input pipe seperti
+ * fast-track. `ask` dapat di-inject pada test via test seam.
+ */
+function createPrompter() {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout
+    });
+    const ask = (message) => new Promise((resolve) => {
+        rl.question(message, (answer) => resolve(answer));
+    });
+    return { ask, close: () => rl.close() };
+}
+
+/**
+ * Masking license untuk tampilan review: grup pertama dan terakhir terlihat,
+ * grup tengah disamarkan (mis. `8ECD-****-****-698Q`). Nilai asli tetap dipakai
+ * untuk penulisan file.
+ */
+function maskLicense(license) {
+    if (!license || typeof license !== 'string') return license;
+    const groups = license.split('-');
+    if (groups.length >= 3) {
+        return groups
+            .map((g, i) => (i === 0 || i === groups.length - 1) ? g : '*'.repeat(g.length))
+            .join('-');
+    }
+    if (license.length > 8) {
+        return `${license.slice(0, 4)}${'*'.repeat(license.length - 8)}${license.slice(-4)}`;
+    }
+    return license;
+}
+
+/** Default atribut database berdasarkan DB_TYPE (merge DB_DEFAULTS + override). */
+function dbDefaultsFor(dbType) {
+    const override = DB_TYPE_DEFAULTS[dbType] || {};
+    return { ...DB_DEFAULTS, ...override };
+}
+
+/** Representasi database untuk baris review, berdasarkan konfigurasi input. */
+function describeDatabase(cfg) {
+    if (cfg.DB_TYPE === 'sqlite') return `sqlite @ ${cfg.DB_FILE}`;
+    return `${cfg.DB_TYPE} @ ${cfg.DB_HOST}:${cfg.DB_PORT}/${cfg.DB_NAME}`;
+}
+
+/**
+ * Fase input konfigurasi interaktif: LICENSE lalu tipe database beserta
+ * atributnya. Mengembalikan objek cfg. `ask` di-inject agar dapat diuji.
+ */
+async function collectConfig(ask) {
+    const askField = async (label, def) => {
+        const input = (await ask(`  ${label} (${def}): `)).trim();
+        return input || def;
+    };
+
+    console.log('');
+    console.log('Enter configuration (press Enter to accept the default value):');
+    console.log('');
+
+    const cfg = {};
+
+    // 1) LICENSE
+    cfg.LICENSE = await askField('LICENSE', DB_DEFAULTS.LICENSE);
+
+    // 2) Tipe database + atributnya
+    console.log('');
+    console.log(`  Supported DB_TYPE: ${SUPPORTED_DB_TYPES.join(', ')}`);
+    cfg.DB_TYPE = (await askField('DB_TYPE', DB_DEFAULTS.DB_TYPE)).toLowerCase();
+
+    if (cfg.DB_TYPE === 'sqlite') {
+        console.log('');
+        console.log('  SQLite mode: DB_HOST, DB_PORT, DB_USER, DB_PASSWORD are ignored.');
+        console.log('  The database file path is set in DB_NAME (via DB_FILE).');
+        console.log('');
+        cfg.DB_FILE = await askField('DB_FILE (.db file path)', DB_DEFAULTS.DB_FILE);
+    } else {
+        const d = dbDefaultsFor(cfg.DB_TYPE);
+        cfg.DB_HOST = await askField('DB_HOST', d.DB_HOST);
+        cfg.DB_PORT = await askField('DB_PORT', d.DB_PORT);
+        cfg.DB_USER = await askField('DB_USER', d.DB_USER);
+        cfg.DB_PASSWORD = await askField('DB_PASSWORD', d.DB_PASSWORD);
+        cfg.DB_NAME = await askField('DB_NAME', d.DB_NAME);
+    }
+
+    return cfg;
+}
+
+/** Susun map nilai env yang akan di-patch ke template dari konfigurasi input. */
+function envValuesFromCfg(cfg) {
+    const v = {
+        LICENSE: cfg.LICENSE,
+        DB_TYPE: cfg.DB_TYPE
+    };
+    if (cfg.DB_TYPE === 'sqlite') {
+        // Untuk SQLite, path file disimpan pada DB_NAME (dikonsumsi runtime).
+        v.DB_NAME = cfg.DB_FILE;
+    } else {
+        v.DB_HOST = cfg.DB_HOST;
+        v.DB_PORT = cfg.DB_PORT;
+        v.DB_USER = cfg.DB_USER;
+        v.DB_PASSWORD = cfg.DB_PASSWORD;
+        v.DB_NAME = cfg.DB_NAME;
+    }
+    return v;
+}
+
+/**
+ * Patch VALUE sejumlah KEY pada teks template tanpa mengubah baris lain
+ * (komentar, section Redis/Kafka/dll. tetap utuh). KEY yang belum ada di
+ * template ditambahkan di akhir.
+ */
+function applyConfigToTemplate(template, values) {
+    const eol = template.includes('\r\n') ? '\r\n' : '\n';
+    const lines = template.split(/\r?\n/);
+    const remaining = new Set(Object.keys(values));
+    for (let i = 0; i < lines.length; i++) {
+        const m = lines[i].match(/^(\s*)([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+        if (m && remaining.has(m[2])) {
+            lines[i] = `${m[1]}${m[2]}=${values[m[2]]}`;
+            remaining.delete(m[2]);
+        }
+    }
+    for (const k of remaining) lines.push(`${k}=${values[k]}`);
+    return lines.join(eol);
+}
+
+/** Tulis file config ke config/<configFileName>, buat folder bila perlu. */
+function writeConfigFile(workingDir, configFileName, content) {
+    const configDir = path.resolve(workingDir, 'config');
+    if (!fs.existsSync(configDir)) {
+        fs.mkdirSync(configDir, { recursive: true });
+    }
+    const absolutePath = path.resolve(configDir, configFileName);
+    fs.writeFileSync(absolutePath, content, 'utf8');
+    console.log(`  Created: ${path.join('config', configFileName)}`);
+}
+
+/** Cetak ringkasan akhir + next steps. */
+function printDone(configFileName) {
+    console.log('');
+    console.log('Done! Sample files generated successfully.');
+    console.log('');
+    console.log('Next Steps:');
+    console.log('');
+    console.log(`  1. Edit config/${configFileName}`);
+    console.log('     Update database credentials (DB_HOST, DB_USER, DB_PASSWORD, DB_NAME)');
+    console.log('');
+}
+
+/** Review + konfirmasi sebelum menulis (mode interaktif). */
+async function confirmWrite(ctx, ask) {
+    console.log('');
+    console.log('====================================================');
+    console.log('  Review configuration');
+    console.log('====================================================');
+    console.log(`  License   : ${maskLicense(ctx.cfg.LICENSE)}`);
+    console.log(`  Database  : ${describeDatabase(ctx.cfg)}`);
+    const existsNote = ctx.exists ? '   (EXISTING — will be overwritten)' : '';
+    console.log(`  Target    : config/${ctx.configFileName}${existsNote}`);
+    console.log('');
+    const answer = (await ask('  Write this config? (Y/n): ')).trim().toLowerCase();
+    return !(answer === 'n' || answer === 'no');
+}
+
+/**
+ * Jalur non-interaktif: tulis template apa adanya ke config/db-connection.env.
+ * Mempertahankan perilaku legacy (termasuk guard file existing tanpa --force).
+ */
+function runNonInteractive(workingDir, force) {
+    const configFileName = DEFAULT_CONFIG_FILE;
+    const relativePath = path.join('config', configFileName);
+    const absolutePath = path.resolve(workingDir, relativePath);
+
+    if (fs.existsSync(absolutePath) && !force) {
+        console.log('WARNING: The following files already exist:');
+        console.log('');
+        console.log(`  ${relativePath}`);
+        console.log('');
+        console.log('Use --force to overwrite:');
+        console.log('  npx restforge init --force');
+        console.log('');
+        throw new Error('1 file(s) already exist. Use --force to overwrite.');
+    }
+
+    writeConfigFile(workingDir, configFileName, TEMPLATE_ENV);
+    printDone(configFileName);
+}
+
+/** Jalur interaktif: kumpulkan input, konfirmasi, lalu tulis template ter-patch. */
+async function runInteractive(workingDir, prompter) {
+    const { ask } = prompter;
+
+    // 1) LICENSE + 2) tipe database & atributnya.
+    const cfg = await collectConfig(ask);
+
+    // 3) Nama file config (terakhir; default db-connection.env, bisa di-custom).
+    console.log('');
+    const fnameInput = (await ask(`  Config file name (${DEFAULT_CONFIG_FILE}): `)).trim();
+    // basename untuk mencegah path traversal; nama selalu relatif ke config/.
+    const configFileName = path.basename(fnameInput || DEFAULT_CONFIG_FILE);
+
+    const absolutePath = path.resolve(workingDir, 'config', configFileName);
+    const exists = fs.existsSync(absolutePath);
+
+    const ok = await confirmWrite({ cfg, configFileName, exists }, ask);
+    if (!ok) {
+        console.log('');
+        console.log('  Aborted. No changes were made.');
+        return;
+    }
+
+    const content = applyConfigToTemplate(TEMPLATE_ENV, envValuesFromCfg(cfg));
+    console.log('');
+    writeConfigFile(workingDir, configFileName, content);
+    printDone(configFileName);
+}
+
+// ---------------------------------------------------------------------------
+// Contract
+// ---------------------------------------------------------------------------
+
+module.exports = {
+    verb: 'init',
+    description: 'Generate starter config file (config/db-connection.env) di working directory. Interaktif di terminal; non-interaktif dengan --force',
+    category: 'utility',
+    flags: {
+        force: {
+            type: 'boolean',
+            required: false,
+            default: false,
+            description: 'Timpa file existing tanpa konfirmasi'
+        }
+    },
+    examples: [
+        'npx restforge init',
+        'npx restforge init --force'
+    ],
+    async handler(args) {
+        const workingDir = process.cwd();
+
+        console.log('');
+        console.log('RESTForge - Init');
+        console.log('====================');
+
+        // Interaktif hanya bila TTY dan TANPA --force. `--force` dan konteks
+        // non-TTY (pipe/CI/spawn dari orkestrator) memakai jalur non-interaktif
+        // deterministik agar tidak menggantung menunggu input.
+        const interactive = args.force !== true && Boolean(process.stdin.isTTY);
+
+        if (!interactive) {
+            runNonInteractive(workingDir, args.force === true);
+            return;
+        }
+
+        const prompter = createPrompter();
+        try {
+            await runInteractive(workingDir, prompter);
+        } finally {
+            prompter.close();
+        }
+    }
+};
+
+// Test seam (hanya aktif via env): mengekspos helper internal agar alur
+// interaktif dapat diuji dengan `ask` ter-inject tanpa stdin TTY. Pada
+// penggunaan CLI normal env ini tidak di-set sehingga export tetap contract murni.
+if (process.env.INIT_TEST === '1') {
+    module.exports.__test = {
+        collectConfig,
+        applyConfigToTemplate,
+        envValuesFromCfg,
+        dbDefaultsFor,
+        describeDatabase,
+        maskLicense,
+        confirmWrite,
+        runInteractive,
+        DEFAULT_CONFIG_FILE,
+        SUPPORTED_DB_TYPES
+    };
+}

package/generators/cli/schema/introspect.js

@@ -180,7 +180,7 @@ function parseSchemaFlag(value) {
 }
 
 function resolveMode(args, schemaList, tableQualified) {
-    const out = args.output;
+    const out = args['schema-path'];
     const isDry = args['dry-run'];
 
     if (isDry && !out) {
@@ -200,7 +200,7 @@ function resolveMode(args, schemaList, tableQualified) {
             if (expectedBase !== targetTableName) {
                 return {
                     error: `Single-mode output filename '${path.basename(out)}' does not match --table='${targetTableName}'. ` +
-                        `Use --output=<folder> or rename the file to '${targetTableName}.js'.`
+                        `Use --schema-path=<folder> or rename the file to '${targetTableName}.js'.`
                 };
             }
             return { kind: 'single-file', file: path.resolve(out), table: targetTableName };
@@ -209,7 +209,7 @@ function resolveMode(args, schemaList, tableQualified) {
     }
 
     if (looksLikeJs) {
-        return { error: `Bulk mode requires a folder for --output, got file '${out}'. Specify a folder or add --table=<name>.` };
+        return { error: `Bulk mode requires a folder for --schema-path, got file '${out}'. Specify a folder or add --table=<name>.` };
     }
 
     const isMultiSchema = (args['all-schemas']) || (Array.isArray(schemaList) && schemaList.length > 1);
@@ -242,7 +242,7 @@ module.exports = {
             default: null,
             description: 'File config database (.env). Fallback ke `.restforge/defaults.json` bila tidak disediakan eksplisit (set via `config set-default`)'
         },
-        output: {
+        'schema-path': {
             type: 'string',
             required: true,
             description: 'Folder atau file output schema'
@@ -279,9 +279,9 @@ module.exports = {
         }
     },
     examples: [
-        'npx restforge schema introspect --config=db.env --output=./schema',
-        'npx restforge schema introspect --config=db.env --output=./schema --table=users --dry-run',
-        'npx restforge schema introspect --config=db.env --output=./schema --all-schemas --force'
+        'npx restforge schema introspect --config=db.env --schema-path=./schema',
+        'npx restforge schema introspect --config=db.env --schema-path=./schema --table=users --dry-run',
+        'npx restforge schema introspect --config=db.env --schema-path=./schema --all-schemas --force'
     ],
     async handler(args) {
         const resolvedConfigResult = resolveConfig(args.config, process.cwd());
@@ -291,9 +291,9 @@ module.exports = {
             throw new Error('--config=<file> is required');
         }
 
-        if (!args['dry-run'] && !args.output) {
-            console.error('Error: --output=<path> is required (or use --dry-run to preview to stdout).');
-            throw new Error('--output=<path> is required');
+        if (!args['dry-run'] && !args['schema-path']) {
+            console.error('Error: --schema-path=<path> is required (or use --dry-run to preview to stdout).');
+            throw new Error('--schema-path=<path> is required');
         }
 
         if (resolvedConfigResult.source === 'default') {

package/generators/lib/data/data-scope.js

@@ -0,0 +1,138 @@
+'use strict';
+
+/**
+ * data-scope — Helper bersama untuk scope flags & derivasi path file data.
+ *
+ * Dipakai oleh `data pull` dan `data push` agar kedua command berbagi satu-satunya
+ * sumber kebenaran untuk: (a) parsing `--schema` comma-separated, (b) validasi
+ * "tepat satu" dari `{--table, --schema, --all-schemas}`, (c) derivasi path file
+ * relatif (bersarang per schema vs flat), dan (d) resolusi scope flag → daftar IR.
+ *
+ * Model scope (mirror `schema introspect`, namun "tepat satu" alih-alih kombinasi):
+ *   --table=<name>        → satu IR via findTableOrThrow (qualified/unqualified).
+ *   --schema=<LIST>       → semua IR ber-schemaName ∈ LIST; 0 match = exit 2 (anti-typo).
+ *   --all-schemas         → seluruh IR (boleh kosong → caller tangani sebagai 0 tabel).
+ *
+ * Aturan path seragam (Q2): layout ditentukan MURNI oleh schema tabel di IR.
+ *   ber-schema  → `<schemaName>/<tableName>.json`
+ *   tanpa schema → `<tableName>.json` (flat root)
+ *
+ * Murni in-memory, tanpa I/O maupun koneksi DB.
+ *
+ * @module generators/lib/data/data-scope
+ */
+
+const path = require('path');
+const { findTableOrThrow, getNamespace } = require('./sdf-reader');
+
+/**
+ * Buat Error dengan exitCode terlampir (precondition/usage = 2).
+ * @param {string} message
+ * @param {number} exitCode
+ * @returns {Error}
+ */
+function failWith(message, exitCode) {
+    const err = new Error(message);
+    err.exitCode = exitCode;
+    return err;
+}
+
+/**
+ * Parse flag `--schema` (single atau comma-separated) → array nama schema.
+ *
+ * Selaras pola `schema introspect` (introspect.js:175-180): split koma, trim tiap
+ * elemen, buang elemen kosong. Mengembalikan `null` bila bukan string atau hasil
+ * akhir kosong (mis. `--schema=` atau `--schema=,,`), sehingga caller dapat
+ * memperlakukan "schema tidak disebut" secara seragam.
+ *
+ * @param {*} value - Nilai flag --schema
+ * @returns {string[]|null}
+ */
+function parseSchemaFlag(value) {
+    if (typeof value !== 'string') return null;
+    const parts = value.split(',').map((s) => s.trim()).filter(Boolean);
+    if (parts.length === 0) return null;
+    return parts;
+}
+
+/**
+ * Path file data relatif terhadap storage dir, diturunkan MURNI dari schema IR.
+ *
+ * Satu-satunya titik derivasi nama file untuk pull & push (menghindari drift tiga
+ * titik edit lama). Tabel ber-schema → bersarang `<schemaName>/<tableName>.json`;
+ * tabel tanpa schema → flat `<tableName>.json`. Pemanggil cukup
+ * `path.join(storageDir, relDataFilePath(ir))`.
+ *
+ * @param {Object} ir - IR model SDF satu tabel
+ * @returns {string} Path relatif (memakai separator OS via path.join)
+ */
+function relDataFilePath(ir) {
+    const { schemaName } = getNamespace(ir);
+    return schemaName
+        ? path.join(schemaName, `${ir.tableName}.json`)
+        : `${ir.tableName}.json`;
+}
+
+/**
+ * Tegakkan "tepat satu" dari `{--table, --schema, --all-schemas}`.
+ *
+ * Arg-parser tidak punya mekanisme XOR lintas-flag (hanya `required` per-flag),
+ * sehingga validasi tiga-arah ditegakkan di sini. Dipanggil SEBELUM load SDF /
+ * koneksi DB. Keduanya/lebih maupun tidak ada satupun → exit 2 dengan pesan sama.
+ *
+ * @param {Object} args - argumen ter-parse (args.table, args['all-schemas'])
+ * @param {string[]|null} schemaList - hasil parseSchemaFlag(args.schema)
+ * @throws {Error} exitCode=2 bila BUKAN tepat satu yang aktif
+ */
+function validateScopeFlags(args, schemaList) {
+    const hasTable = args.table != null && args.table !== '';
+    const hasSchema = Array.isArray(schemaList) && schemaList.length > 0;
+    const hasAll = args['all-schemas'] === true;
+
+    const count = (hasTable ? 1 : 0) + (hasSchema ? 1 : 0) + (hasAll ? 1 : 0);
+    if (count !== 1) {
+        throw failWith('Specify exactly one of --table, --schema, or --all-schemas.', 2);
+    }
+}
+
+/**
+ * Resolusi scope flag → daftar IR yang akan diproses (urutan deklarasi Map).
+ *
+ * Mengasumsikan validateScopeFlags() sudah lolos (tepat satu flag aktif).
+ *   --table        → [findTableOrThrow(models, args.table)] (exit 2 bila tak terdaftar/ambigu).
+ *   --schema=<L>   → subset IR ber-schemaName ∈ L; 0 match → exit 2 (sinyal typo).
+ *   --all-schemas  → seluruh IR (boleh kosong → caller perlakukan sebagai 0 tabel, exit 0).
+ *
+ * @param {Map<string, Object>} models - hasil loadSdf
+ * @param {Object} args - argumen ter-parse
+ * @param {string[]|null} schemaList - hasil parseSchemaFlag(args.schema)
+ * @returns {Object[]} array IR sesuai scope
+ * @throws {Error} exitCode=2 (table tak terdaftar/ambigu, atau --schema 0-match)
+ */
+function resolveScope(models, args, schemaList) {
+    const hasTable = args.table != null && args.table !== '';
+    if (hasTable) {
+        return [findTableOrThrow(models, args.table)];
+    }
+
+    if (Array.isArray(schemaList) && schemaList.length > 0) {
+        const set = new Set(schemaList);
+        const subset = [...models.values()].filter((ir) => set.has(getNamespace(ir).schemaName));
+        if (subset.length === 0) {
+            throw failWith(`No tables found for schema(s): ${schemaList.join(', ')}.`, 2);
+        }
+        return subset;
+    }
+
+    // --all-schemas: seluruh tabel (semua schema, termasuk schemaless). Boleh kosong.
+    return [...models.values()];
+}
+
+module.exports = {
+    parseSchemaFlag,
+    relDataFilePath,
+    validateScopeFlags,
+    resolveScope,
+    // Diekspor untuk reuse/test internal.
+    _internal: { failWith }
+};