@restforgejs/platform 4.2.8 → 4.3.1

package/generators/scripts/validate-catalog.js

@@ -1,430 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * RESTForge - Field Validation Catalog Sync Validator
- *
- * Cross-check catalog metadata vs spec doc and template implementation
- * to detect drift between three artifacts:
- *
- *   1. Catalog data    : generators/lib/templates/field-validation-catalog.js
- *   2. Spec doc        : <repo-root>/docs/schema-reference/feat-field-validation.md
- *                        (belum tersedia di v3 baseline — siapkan placeholder
- *                        bila Level 4 cross-check ingin diaktifkan)
- *   3. Template engine : generators/lib/templates/postgres-template.js  (PG = primary)
- *                        generators/lib/templates/{mysql,oracle,sqlite}-template.js (best-effort)
- *
- * Usage (jalankan dari folder packages/platform):
- *   node generators/scripts/validate-catalog.js [--strict] [--quiet]
- *
- * Exit codes:
- *   0 = no issues, or only warnings (default)
- *   1 = errors found, or warnings found in --strict mode
- *
- * @module scripts/validate-catalog
- */
-
-const fs = require('fs');
-const path = require('path');
-
-// ============================================================================
-// CONFIG
-// ============================================================================
-
-const CATALOG_PATH = path.join(__dirname, '..', 'lib', 'templates', 'field-validation-catalog.js');
-const PG_TEMPLATE_PATH = path.join(__dirname, '..', 'lib', 'templates', 'postgres-template.js');
-// Spec doc lives at <repo-root>/docs/schema-reference/feat-field-validation.md (v3 layout).
-// __dirname = packages/platform/generators/scripts → naik 4 level untuk reach repo root.
-// CATATAN v3: file ini belum tersedia di baseline; Level 4 cross-check akan report
-// "Spec doc file not found" sampai placeholder/spec disiapkan di lokasi ini.
-const SPEC_DOC_PATH = path.join(__dirname, '..', '..', '..', '..', 'docs', 'schema-reference', 'feat-field-validation.md');
-
-const SECONDARY_TEMPLATES = [
-    { name: 'MySQL', path: path.join(__dirname, '..', 'lib', 'templates', 'mysql-template.js') },
-    { name: 'Oracle', path: path.join(__dirname, '..', 'lib', 'templates', 'oracle-template.js') },
-    { name: 'SQLite', path: path.join(__dirname, '..', 'lib', 'templates', 'sqlite-template.js') }
-];
-
-// ============================================================================
-// REPORTING
-// ============================================================================
-
-const report = {
-    errors: [],
-    warnings: [],
-    info: []
-};
-
-function err(msg) { report.errors.push(msg); }
-function warn(msg) { report.warnings.push(msg); }
-function info(msg) { report.info.push(msg); }
-
-// ============================================================================
-// PARSE ARGUMENTS
-// ============================================================================
-
-function parseArgs() {
-    const args = process.argv.slice(2);
-    return {
-        strict: args.includes('--strict'),
-        quiet: args.includes('--quiet')
-    };
-}
-
-// ============================================================================
-// LEVEL 1: CATALOG SCHEMA INTEGRITY
-// ============================================================================
-
-function checkCatalogStructure(catalog) {
-    const requiredKeys = ['schemaVersion', 'source', 'types', 'constraints', 'formatPresets', 'auditColumns', 'messageOverridePattern'];
-    for (const key of requiredKeys) {
-        if (!(key in catalog)) {
-            err(`Catalog missing required top-level key: '${key}'`);
-        }
-    }
-    if (!Array.isArray(catalog.types)) err('catalog.types must be an array');
-    if (!Array.isArray(catalog.constraints)) err('catalog.constraints must be an array');
-    if (!Array.isArray(catalog.formatPresets)) err('catalog.formatPresets must be an array');
-    if (typeof catalog.auditColumns !== 'object' || catalog.auditColumns === null) err('catalog.auditColumns must be an object');
-    if (typeof catalog.messageOverridePattern !== 'object' || catalog.messageOverridePattern === null) err('catalog.messageOverridePattern must be an object');
-}
-
-function checkTypesIntegrity(types) {
-    const requiredFields = ['name', 'description', 'databaseTypes', 'exampleValue', 'applicableConstraints'];
-    const seen = new Set();
-
-    for (const t of types) {
-        for (const f of requiredFields) {
-            if (!(f in t)) err(`Type '${t.name || '<unknown>'}' missing field: '${f}'`);
-        }
-        if (seen.has(t.name)) err(`Duplicate type name: '${t.name}'`);
-        seen.add(t.name);
-
-        if (!Array.isArray(t.databaseTypes)) err(`Type '${t.name}': databaseTypes must be array`);
-        if (!Array.isArray(t.applicableConstraints)) err(`Type '${t.name}': applicableConstraints must be array`);
-    }
-}
-
-function checkConstraintsIntegrity(constraints) {
-    const requiredFields = ['name', 'valueType', 'description', 'scope', 'applicableTypes', 'messageOverrideKey', 'example'];
-    const validScopes = ['general', 'string', 'number', 'date', 'boolean', 'array', 'json', 'uuid'];
-    const validValueTypes = ['boolean', 'integer', 'number', 'string', 'array', 'object', 'any'];
-
-    const nameScopeKeys = new Set();
-
-    for (const c of constraints) {
-        for (const f of requiredFields) {
-            if (!(f in c)) err(`Constraint '${c.name || '<unknown>'}' missing field: '${f}'`);
-        }
-        if (!validScopes.includes(c.scope)) {
-            err(`Constraint '${c.name}': invalid scope '${c.scope}' (must be one of: ${validScopes.join(', ')})`);
-        }
-        if (!validValueTypes.includes(c.valueType)) {
-            err(`Constraint '${c.name}': invalid valueType '${c.valueType}' (must be one of: ${validValueTypes.join(', ')})`);
-        }
-        if (!Array.isArray(c.applicableTypes)) {
-            err(`Constraint '${c.name}': applicableTypes must be array`);
-        }
-
-        // Composite key (name + scope) — same name can appear with different scopes (e.g. 'format' for string and date)
-        const key = `${c.name}@${c.scope}`;
-        if (nameScopeKeys.has(key)) {
-            err(`Duplicate constraint: '${c.name}' with scope '${c.scope}'`);
-        }
-        nameScopeKeys.add(key);
-    }
-}
-
-function checkFormatPresetsIntegrity(formatPresets) {
-    const seen = new Set();
-    for (const p of formatPresets) {
-        if (!p.name) err('Format preset missing name');
-        if (!p.description) err(`Format preset '${p.name}' missing description`);
-        if (seen.has(p.name)) err(`Duplicate format preset: '${p.name}'`);
-        seen.add(p.name);
-    }
-}
-
-function checkAuditColumnsIntegrity(auditColumns) {
-    const required = ['managedColumns', 'validValues', 'rejectedValues', 'errorMessage'];
-    for (const f of required) {
-        if (!(f in auditColumns)) err(`auditColumns missing field: '${f}'`);
-    }
-    if (!Array.isArray(auditColumns.managedColumns)) err('auditColumns.managedColumns must be array');
-    if (!Array.isArray(auditColumns.validValues)) err('auditColumns.validValues must be array');
-    if (!Array.isArray(auditColumns.rejectedValues)) err('auditColumns.rejectedValues must be array');
-}
-
-// ============================================================================
-// LEVEL 2: INTERNAL CROSS-REFERENCE
-// ============================================================================
-
-function checkCrossReferences(catalog) {
-    const typeNames = new Set(catalog.types.map(t => t.name));
-    const constraintNames = new Set(catalog.constraints.map(c => c.name));
-
-    // 1. Each type's applicableConstraints must reference real constraints
-    for (const t of catalog.types) {
-        for (const cName of t.applicableConstraints) {
-            if (!constraintNames.has(cName)) {
-                err(`Type '${t.name}': references non-existent constraint '${cName}' in applicableConstraints`);
-            }
-        }
-    }
-
-    // 2. Each constraint's applicableTypes must reference real types (or "all")
-    for (const c of catalog.constraints) {
-        for (const tName of c.applicableTypes) {
-            if (tName === 'all') continue;
-            if (!typeNames.has(tName)) {
-                err(`Constraint '${c.name}@${c.scope}': references non-existent type '${tName}' in applicableTypes`);
-            }
-        }
-    }
-
-    // 3. Bidirectional consistency: if constraint X applies to type Y, then type Y should list X in applicableConstraints
-    for (const c of catalog.constraints) {
-        const targets = c.applicableTypes.includes('all')
-            ? Array.from(typeNames)
-            : c.applicableTypes;
-        for (const tName of targets) {
-            const t = catalog.types.find(x => x.name === tName);
-            if (!t) continue;
-            if (!t.applicableConstraints.includes(c.name)) {
-                warn(`Bidirectional drift: constraint '${c.name}@${c.scope}' applicable to '${tName}', but type '${tName}' does not list it in applicableConstraints`);
-            }
-        }
-    }
-
-    // 4. messageOverrideKey naming convention
-    for (const c of catalog.constraints) {
-        if (c.messageOverrideKey === null) continue;
-        const expected = c.name + 'Message';
-        if (c.messageOverrideKey !== expected) {
-            warn(`Constraint '${c.name}@${c.scope}': messageOverrideKey '${c.messageOverrideKey}' does not match convention '${expected}'`);
-        }
-    }
-}
-
-// ============================================================================
-// LEVEL 3: TEMPLATE IMPLEMENTATION (PostgreSQL = primary)
-// ============================================================================
-
-function checkPgTemplateImplementation(catalog) {
-    if (!fs.existsSync(PG_TEMPLATE_PATH)) {
-        err(`PostgreSQL template not found: ${PG_TEMPLATE_PATH}`);
-        return;
-    }
-
-    const tpl = fs.readFileSync(PG_TEMPLATE_PATH, 'utf8');
-
-    // Constraints that are sanitization or marker only — not validated as runtime check
-    // (still listed in catalog for completeness)
-    const NON_VALIDATABLE = new Set([
-        'unique',         // database-level
-        'default',        // pre-validation injection
-        'primaryKey',     // structural
-        'autoGenerate',   // pre-validation injection
-        'nullable',       // structural
-        'patternMessage', // override key, not validatable itself
-        'scale',          // schema-level (DDL)
-        'precision',      // schema-level (DDL)
-        'schema',         // not yet enforced at runtime
-        'strict'          // not yet enforced at runtime
-    ]);
-
-    // Constraint names that PG template should reference (e.g. constraints.required, constraints.minLength)
-    const constraintNames = new Set(catalog.constraints.map(c => c.name));
-
-    for (const cName of constraintNames) {
-        if (NON_VALIDATABLE.has(cName)) continue;
-        // Look for constraints.<name> or constraints['<name>']
-        const pattern = new RegExp(`constraints\\.${cName}\\b|constraints\\[['"]${cName}['"]\\]`);
-        if (!pattern.test(tpl)) {
-            warn(`PG template: constraint '${cName}' declared in catalog but not referenced in postgres-template.js`);
-        }
-    }
-
-    // Verify type-specific dispatcher methods exist
-    const typeMethods = {
-        string: '_validateStringConstraints',
-        integer: '_validateNumberConstraints',
-        decimal: '_validateNumberConstraints',
-        number: '_validateNumberConstraints',
-        boolean: '_validateBooleanConstraints',
-        date: '_validateDateConstraints',
-        datetime: '_validateDateConstraints',
-        timestamp: '_validateDateConstraints',
-        uuid: '_validateUuidConstraints',
-        array: '_validateArrayConstraints',
-        json: '_validateJsonConstraints'
-    };
-
-    for (const [typeName, methodName] of Object.entries(typeMethods)) {
-        const typeInCatalog = catalog.types.find(t => t.name === typeName);
-        if (!typeInCatalog) continue;
-        if (!tpl.includes(methodName)) {
-            warn(`PG template: type '${typeName}' declared in catalog but dispatcher method '${methodName}' not found`);
-        }
-    }
-
-    // Verify format presets are referenced
-    // Match: 'email', "email", or email: (object key)
-    for (const preset of catalog.formatPresets) {
-        const pattern = new RegExp(`['"]${preset.name}['"]|\\b${preset.name}\\s*:`);
-        if (!pattern.test(tpl)) {
-            warn(`PG template: format preset '${preset.name}' declared in catalog but not referenced`);
-        }
-    }
-}
-
-function checkSecondaryTemplates(catalog) {
-    for (const tplDef of SECONDARY_TEMPLATES) {
-        if (!fs.existsSync(tplDef.path)) {
-            info(`${tplDef.name} template not found, skipping: ${tplDef.path}`);
-            continue;
-        }
-        const tpl = fs.readFileSync(tplDef.path, 'utf8');
-        const hasValidationMethod = tpl.includes('validateFieldConstraints');
-        if (!hasValidationMethod) {
-            info(`${tplDef.name} template: no full validation engine (this is by design — only PG has full implementation currently)`);
-        } else {
-            info(`${tplDef.name} template: has validateFieldConstraints — consider running similar checks`);
-        }
-    }
-}
-
-// ============================================================================
-// LEVEL 4: SPEC DOCUMENT (best-effort textual check)
-// ============================================================================
-
-function checkSpecDocReferences(catalog) {
-    if (!fs.existsSync(SPEC_DOC_PATH)) {
-        warn(`Spec doc not found: ${SPEC_DOC_PATH}`);
-        return;
-    }
-
-    const doc = fs.readFileSync(SPEC_DOC_PATH, 'utf8');
-
-    // Check that each constraint name appears in the spec doc
-    for (const c of catalog.constraints) {
-        const pattern = new RegExp(`\\b${c.name}\\b`);
-        if (!pattern.test(doc)) {
-            warn(`Spec doc: constraint '${c.name}@${c.scope}' not referenced in feat-field-validation.md`);
-        }
-    }
-
-    // Check that each type name appears in the spec doc
-    for (const t of catalog.types) {
-        const pattern = new RegExp(`\\b${t.name}\\b`);
-        if (!pattern.test(doc)) {
-            warn(`Spec doc: type '${t.name}' not referenced in feat-field-validation.md`);
-        }
-    }
-
-    // Check that each format preset appears
-    for (const p of catalog.formatPresets) {
-        const pattern = new RegExp(`format:\\s*${p.name}|format\\s*=\\s*["']${p.name}["']|\\b${p.name}\\b`);
-        if (!pattern.test(doc)) {
-            warn(`Spec doc: format preset '${p.name}' not referenced in feat-field-validation.md`);
-        }
-    }
-}
-
-// ============================================================================
-// MAIN
-// ============================================================================
-
-function printReport(quiet) {
-    const lines = [];
-
-    lines.push('');
-    lines.push('================================================================');
-    lines.push('  Field Validation Catalog Sync Validator');
-    lines.push('================================================================');
-    lines.push('');
-
-    if (report.errors.length > 0) {
-        lines.push(`ERRORS (${report.errors.length}):`);
-        for (const e of report.errors) lines.push(`  [X] ${e}`);
-        lines.push('');
-    }
-
-    if (report.warnings.length > 0) {
-        lines.push(`WARNINGS (${report.warnings.length}):`);
-        for (const w of report.warnings) lines.push(`  [!] ${w}`);
-        lines.push('');
-    }
-
-    if (!quiet && report.info.length > 0) {
-        lines.push(`INFO (${report.info.length}):`);
-        for (const i of report.info) lines.push(`  [i] ${i}`);
-        lines.push('');
-    }
-
-    lines.push('----------------------------------------------------------------');
-    lines.push('  Summary');
-    lines.push('----------------------------------------------------------------');
-    lines.push(`  Errors  : ${report.errors.length}`);
-    lines.push(`  Warnings: ${report.warnings.length}`);
-    lines.push(`  Info    : ${report.info.length}`);
-    lines.push('');
-
-    if (report.errors.length === 0 && report.warnings.length === 0) {
-        lines.push('  Status: PASS — catalog, spec doc, and PG template are in sync.');
-    } else if (report.errors.length === 0) {
-        lines.push('  Status: PASS WITH WARNINGS — review warnings above.');
-    } else {
-        lines.push('  Status: FAIL — fix errors before commit.');
-    }
-    lines.push('');
-
-    console.log(lines.join('\n'));
-}
-
-function main() {
-    const opts = parseArgs();
-
-    let catalog;
-    try {
-        ({ FIELD_VALIDATION_CATALOG: catalog } = require(CATALOG_PATH));
-    } catch (e) {
-        console.error(`Failed to load catalog from ${CATALOG_PATH}`);
-        console.error(e.message);
-        process.exit(1);
-    }
-
-    info(`Catalog loaded from: ${path.relative(process.cwd(), CATALOG_PATH)}`);
-    info(`Schema version: ${catalog.schemaVersion}`);
-    info(`Types: ${catalog.types.length}, Constraints: ${catalog.constraints.length}, Format presets: ${catalog.formatPresets.length}`);
-
-    // Level 1: structure
-    checkCatalogStructure(catalog);
-    checkTypesIntegrity(catalog.types);
-    checkConstraintsIntegrity(catalog.constraints);
-    checkFormatPresetsIntegrity(catalog.formatPresets);
-    checkAuditColumnsIntegrity(catalog.auditColumns);
-
-    // Stop early if structural errors — cross-ref checks will be misleading
-    if (report.errors.length > 0) {
-        printReport(opts.quiet);
-        process.exit(1);
-    }
-
-    // Level 2: cross-reference
-    checkCrossReferences(catalog);
-
-    // Level 3: template implementation
-    checkPgTemplateImplementation(catalog);
-    checkSecondaryTemplates(catalog);
-
-    // Level 4: spec doc
-    checkSpecDocReferences(catalog);
-
-    printReport(opts.quiet);
-
-    if (report.errors.length > 0) process.exit(1);
-    if (opts.strict && report.warnings.length > 0) process.exit(1);
-    process.exit(0);
-}
-
-main();