@accounter/server 0.0.9-alpha-20251231123714-6cdd9de71b4672d74ece5d34c438d162987b2c93 → 0.0.9-alpha-20251231163357-33d4c33fec5e21dad2e04d1f293f6248d2550588

package/dist/server/src/demo-fixtures/validate-demo-data.js

@@ -0,0 +1,117 @@
+/**
+ * Demo Data Validation Script
+ *
+ * Validates the integrity of seeded demo data with comprehensive ledger validation.
+ *
+ * Validation Checks:
+ * - Admin business entity exists
+ * - Charge count matches expected
+ * - Ledger records for each use-case:
+ *   - Per-record internal balance (FR1)
+ *   - Aggregate balance (FR2)
+ *   - Entity-level balance (FR3)
+ *   - No orphaned amounts (FR4)
+ *   - Positive amounts only (FR5)
+ *   - Foreign currency consistency (FR6)
+ *   - Valid dates (FR7)
+ *   - Record count matches (FR8)
+ *
+ * Exit codes:
+ * - 0: All validations passed
+ * - 1: Validation errors found or database connection failed
+ */
+import { config } from 'dotenv';
+import pg from 'pg';
+import { getAllUseCases } from './use-cases/index.js';
+import { validateLedgerRecords } from './validators/ledger-validators.js';
+config({
+    path: '../../.env',
+});
+const DEFAULT_CURRENCY = 'ILS';
+const BALANCE_TOLERANCE = 0.005;
+/**
+ * Main validation function - connects to DB and runs all checks
+ */
+async function validateDemoData() {
+    const client = new pg.Client({
+        user: process.env.POSTGRES_USER,
+        password: process.env.POSTGRES_PASSWORD,
+        host: process.env.POSTGRES_HOST,
+        port: parseInt(process.env.POSTGRES_PORT || '5432'),
+        database: process.env.POSTGRES_DB,
+        ssl: process.env.POSTGRES_SSL === '1',
+    });
+    const errors = [];
+    try {
+        await client.connect();
+        // 1. Admin business exists
+        const adminCheck = await client.query(`SELECT id FROM accounter_schema.financial_entities WHERE type = 'business' AND name = 'Accounter Admin Business'`);
+        if (adminCheck.rows.length === 0) {
+            errors.push('Admin business entity missing');
+        }
+        // 2. Use-case charge count reconciliation
+        const useCases = getAllUseCases();
+        const expectedChargeCount = useCases.reduce((sum, uc) => sum + uc.fixtures.charges.length, 0);
+        const actualChargeCount = await client.query(`SELECT COUNT(*) FROM accounter_schema.charges`);
+        if (parseInt(actualChargeCount.rows[0].count) !== expectedChargeCount) {
+            errors.push(`Charge count mismatch: expected ${expectedChargeCount}, got ${actualChargeCount.rows[0].count}`);
+        }
+        // 3. Comprehensive ledger validation for all use-cases with expectations (FR9)
+        const useCasesWithExpectations = useCases.filter(uc => uc.expectations);
+        console.log(`\nValidating ledger records for ${useCasesWithExpectations.length} use-case(s)...`);
+        let ledgerRecordsExist = false;
+        for (const useCase of useCasesWithExpectations) {
+            // Get all charges for this use-case
+            const chargeIds = useCase.fixtures.charges.map(c => c.id);
+            // Fetch all ledger records for these charges
+            const ledgerRecords = await client.query(`SELECT * FROM accounter_schema.ledger_records WHERE charge_id = ANY($1) ORDER BY created_at`, [chargeIds]);
+            if (ledgerRecords.rows.length === 0) {
+                // Ledger generation is separate from seeding - this is expected
+                console.log(`  ⚠ ${useCase.id}: no ledger records (ledger generation not run)`);
+                continue;
+            }
+            ledgerRecordsExist = true;
+            // Create validation context
+            const context = {
+                useCaseId: useCase.id,
+                defaultCurrency: DEFAULT_CURRENCY,
+                tolerance: BALANCE_TOLERANCE,
+            };
+            // Run comprehensive validation
+            const validationErrors = validateLedgerRecords(ledgerRecords.rows, useCase.expectations.ledgerRecordCount, context);
+            errors.push(...validationErrors);
+            // Log progress
+            if (validationErrors.length === 0) {
+                console.log(`  ✓ ${useCase.id} (${ledgerRecords.rows.length} records)`);
+            }
+            else {
+                console.log(`  ✗ ${useCase.id} (${validationErrors.length} error(s))`);
+            }
+        }
+        if (!ledgerRecordsExist) {
+            console.log('  ℹ️  Ledger records not found. Run ledger generation to create and validate ledger entries.');
+        }
+        // 4. VAT row present (percentage stored as decimal 0.17 for 17%)
+        const vatCheck = await client.query(`SELECT 1 FROM accounter_schema.vat_value WHERE percentage = 0.17`);
+        if (vatCheck.rows.length === 0) {
+            errors.push('VAT default (17%) missing');
+        }
+        // Report errors or success
+        if (errors.length > 0) {
+            console.error('❌ Validation failed:');
+            for (const err of errors)
+                console.error(`  - ${err}`);
+            process.exit(1);
+        }
+        console.log('✅ Demo data validation passed');
+    }
+    catch (error) {
+        console.error('❌ Validation error:', error);
+        process.exit(1);
+    }
+    finally {
+        await client.end();
+    }
+}
+validateDemoData();
+//# sourceMappingURL=validate-demo-data.js.map

package/dist/server/src/demo-fixtures/validate-demo-data.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-demo-data.js","sourceRoot":"","sources":["../../../../src/demo-fixtures/validate-demo-data.ts"],"names":[],"mappings":"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"}

package/dist/server/src/demo-fixtures/validators/ledger-validators.d.ts

@@ -0,0 +1,349 @@
+import type { LedgerRecord, ValidationContext } from './types.js';
+/**
+ * Parse a numeric amount from a string, handling null/undefined values
+ *
+ * PostgreSQL returns numeric values as strings when queried via pg driver.
+ * This utility safely converts them to numbers for arithmetic operations.
+ *
+ * @param value - The string value to parse (may be null or undefined)
+ * @returns The parsed number, or 0 if value is null/undefined/invalid
+ *
+ * @example
+ * parseAmount('100.50') // 100.50
+ * parseAmount(null)     // 0
+ * parseAmount('invalid') // 0
+ */
+export declare function parseAmount(value: string | null | undefined): number;
+/**
+ * Check if two numeric values are balanced within a tolerance
+ *
+ * Uses tolerance-based comparison to handle floating-point arithmetic
+ * imprecision. Two values are considered balanced if their absolute
+ * difference is less than or equal to the tolerance.
+ *
+ * @param a - First value to compare
+ * @param b - Second value to compare
+ * @param tolerance - Maximum acceptable difference (default: 0.005)
+ * @returns True if values are balanced within tolerance, false otherwise
+ *
+ * @example
+ * isBalanced(100, 100)       // true
+ * isBalanced(100, 100.004, 0.005) // true
+ * isBalanced(100, 102, 0.005)     // false
+ */
+export declare function isBalanced(a: number, b: number, tolerance?: number): boolean;
+/**
+ * Validate per-record internal balance (FR1)
+ *
+ * Ensures each ledger record is internally balanced according to double-entry
+ * bookkeeping principles: total debits must equal total credits within tolerance.
+ * Also detects empty records where all amounts are zero.
+ *
+ * This is a fundamental validation that must pass for every record individually
+ * before aggregate-level validations can be meaningful.
+ *
+ * @param records - Array of ledger records to validate
+ * @param context - Validation context containing use-case ID and tolerance
+ * @returns Array of error messages (empty if all records are valid)
+ *
+ * Functional Requirement: FR1 - Per-Record Internal Balance
+ * - Rule: (debit_local_amount1 + debit_local_amount2) == (credit_local_amount1 + credit_local_amount2)
+ * - Tolerance: Specified in context (typically ±0.005 for accounting rounding)
+ * - Also implements FR10: Empty Ledger Detection
+ *
+ * @example
+ * const errors = validateRecordInternalBalance(records, {
+ *   useCaseId: 'monthly-expense',
+ *   defaultCurrency: 'ILS',
+ *   tolerance: 0.005
+ * });
+ * // Returns: [] if valid, or error messages like:
+ * // ["monthly-expense - Record 0 (uuid-123): internal imbalance (debit=100.00, credit=99.98)"]
+ */
+export declare function validateRecordInternalBalance(records: LedgerRecord[], context: ValidationContext): string[];
+/**
+ * Validate aggregate balance across all records (FR2)
+ *
+ * Validates that the sum of all debits equals the sum of all credits across
+ * all ledger records for a use-case. This is the second level of validation
+ * (after per-record balance) and ensures the entire ledger set balances.
+ *
+ * This refactors and enhances the existing aggregate balance validation logic
+ * that was previously only applied to a single use-case. The new implementation
+ * applies to all use-cases with expectations.
+ *
+ * @param records - Array of ledger records to validate
+ * @param context - Validation context containing use-case ID and tolerance
+ * @returns Array of error messages (empty if aggregate is balanced)
+ *
+ * Functional Requirement: FR2 - Aggregate Balance Validation
+ * - Rule: Σ(all debits) == Σ(all credits)
+ * - Tolerance: Specified in context (typically ±0.005)
+ * - Enhancement: Now applies to ALL use-cases, not just first one
+ *
+ * @example
+ * const errors = validateAggregateBalance(records, {
+ *   useCaseId: 'monthly-expense',
+ *   defaultCurrency: 'ILS',
+ *   tolerance: 0.005
+ * });
+ * // Returns: [] if valid, or error like:
+ * // ["monthly-expense: aggregate ledger not balanced (debit 1000.00, credit 999.50)"]
+ */
+export declare function validateAggregateBalance(records: LedgerRecord[], context: ValidationContext): string[];
+/**
+ * Validate entity-level balance (FR3)
+ *
+ * Validates that each financial entity's net position across all ledger records
+ * balances to zero (or within tolerance). This is the third level of validation
+ * in the hierarchy:
+ * 1. Per-record balance (FR1) - each record internally balanced
+ * 2. Aggregate balance (FR2) - all records collectively balanced
+ * 3. Entity balance (FR3) - each entity's position balanced across records
+ *
+ * In double-entry bookkeeping, every entity that appears in the ledger should
+ * have a net zero position when considering all transactions. If an entity has
+ * debits totaling $500 across various records, it should also have credits
+ * totaling $500 across those same or other records.
+ *
+ * @param records - Array of ledger records to validate
+ * @param context - Validation context containing use-case ID and tolerance
+ * @returns Array of error messages (empty if all entities are balanced)
+ *
+ * Functional Requirement: FR3 - Entity-Level Balance Validation
+ * - Rule: For each entity, Σ(debits) - Σ(credits) ≈ 0
+ * - Tolerance: Specified in context (typically ±0.005)
+ * - Tracks: debit/credit amounts across all 4 entity fields per record
+ *
+ * Implementation:
+ * - Accumulates debits and credits per entity across all records
+ * - Calculates net balance (totalDebit - totalCredit) for each entity
+ * - Validates net balance is within tolerance of zero
+ *
+ * @example
+ * const errors = validateEntityBalance(records, {
+ *   useCaseId: 'monthly-expense',
+ *   defaultCurrency: 'ILS',
+ *   tolerance: 0.005
+ * });
+ * // Returns: [] if valid, or errors like:
+ * // ["monthly-expense: Entity entity-123 unbalanced (net=50.00, debit=150.00, credit=100.00, records=3)"]
+ */
+export declare function validateEntityBalance(records: LedgerRecord[], context: ValidationContext): string[];
+/**
+ * Validate ledger record count (FR8)
+ *
+ * Validates that the actual number of ledger records matches the expected count
+ * specified in the use-case expectations. This ensures data completeness and
+ * detects cases where records may be missing or extra records were created.
+ *
+ * This enhances the existing record count validation by applying it to all
+ * use-cases systematically rather than ad-hoc checks.
+ *
+ * @param records - Array of ledger records to validate
+ * @param expectedCount - Expected number of ledger records for this use-case
+ * @param context - Validation context containing use-case ID
+ * @returns Array of error messages (empty if count matches)
+ *
+ * Functional Requirement: FR8 - Record Count Validation
+ * - Rule: Actual record count must match expected count exactly
+ * - Enhancement: Future support for minimum count validation for cases
+ *   where ledger generation may create additional balancing entries
+ *
+ * @example
+ * const errors = validateRecordCount(records, 24, {
+ *   useCaseId: 'monthly-expense',
+ *   defaultCurrency: 'ILS',
+ *   tolerance: 0.005
+ * });
+ * // Returns: [] if count matches, or error like:
+ * // ["monthly-expense: ledger record count mismatch (expected 24, got 23)"]
+ */
+export declare function validateRecordCount(records: LedgerRecord[], expectedCount: number, context: ValidationContext): string[];
+/**
+ * Validate all amounts are positive (FR5)
+ *
+ * Ensures data integrity by validating that all amount fields contain
+ * non-negative values. Negative amounts are not allowed in the ledger
+ * system as they violate accounting principles where debits and credits
+ * must always be positive or zero.
+ *
+ * This validation checks all 8 amount fields per record:
+ * - Local amounts: debit_local_amount1/2, credit_local_amount1/2
+ * - Foreign amounts: debit_foreign_amount1/2, credit_foreign_amount1/2
+ *
+ * @param records - Array of ledger records to validate
+ * @param context - Validation context containing use-case ID
+ * @returns Array of error messages (empty if all amounts are non-negative)
+ *
+ * Functional Requirement: FR5 - Positive Amount Validation
+ * - Checks all amount fields for negative values
+ * - Reports specific field and value for any negative amounts found
+ *
+ * @example
+ * const errors = validatePositiveAmounts(records, {
+ *   useCaseId: 'monthly-expense',
+ *   defaultCurrency: 'ILS',
+ *   tolerance: 0.005
+ * });
+ * // Returns: [] if valid, or errors like:
+ * // ["monthly-expense - Record 0 (uuid-123): negative amount in debit_local_amount1 (-100.00)"]
+ */
+export declare function validatePositiveAmounts(records: LedgerRecord[], context: ValidationContext): string[];
+/**
+ * Validate dates (FR7)
+ *
+ * Ensures all ledger records have valid invoice_date and value_date fields
+ * within acceptable ranges. Proper date validation is critical for:
+ * - Financial reporting accuracy
+ * - Tax compliance and audit trails
+ * - Chronological transaction ordering
+ * - Preventing data entry errors
+ *
+ * Validation rules:
+ * - Both invoice_date and value_date must be present (not null)
+ * - Both dates must be valid Date objects (not NaN)
+ * - Both dates must fall within the range 2020-01-01 to 2030-12-31
+ *
+ * @param records - Array of ledger records to validate
+ * @param context - Validation context containing use-case ID
+ * @returns Array of error messages (empty if all dates are valid)
+ *
+ * Functional Requirement: FR7 - Date Validation
+ * - Checks for missing dates (null values)
+ * - Checks for invalid dates (parse errors)
+ * - Checks for dates outside reasonable business range
+ *
+ * @example
+ * const errors = validateDates(records, {
+ *   useCaseId: 'monthly-expense',
+ *   defaultCurrency: 'ILS',
+ *   tolerance: 0.005
+ * });
+ * // Returns: [] if valid, or errors like:
+ * // ["monthly-expense - Record 0 (uuid-123): missing invoice_date"]
+ * // ["monthly-expense - Record 1 (uuid-456): invoice_date out of range (1999-01-01T00:00:00.000Z)"]
+ */
+export declare function validateDates(records: LedgerRecord[], context: ValidationContext): string[];
+/**
+ * Validate foreign currency handling (FR6)
+ *
+ * Ensures proper handling of foreign currency transactions by validating:
+ * 1. Currency field consistency with foreign amount fields
+ * 2. Presence of foreign amounts when currency is not the default (ILS)
+ * 3. Absence of foreign amounts when currency is the default (ILS)
+ * 4. Reasonableness of implied exchange rates between local and foreign amounts
+ *
+ * Foreign currency validation is critical for:
+ * - Accurate financial reporting in multi-currency environments
+ * - Compliance with international accounting standards
+ * - Detection of data entry errors in currency conversion
+ * - Prevention of fraudulent or suspicious exchange rate manipulation
+ *
+ * Exchange rate validation:
+ * - Implied rate = local_amount / foreign_amount
+ * - Rate must be between 0.1 and 10.0 to be considered reasonable
+ * - Rates outside this range likely indicate data entry errors
+ *
+ * @param records - Array of ledger records to validate
+ * @param context - Validation context containing use-case ID and default currency
+ * @returns Array of error messages (empty if all currency handling is valid)
+ *
+ * Functional Requirement: FR6 - Foreign Currency Validation
+ * - Validates currency field matches foreign amount presence/absence
+ * - Checks exchange rate consistency within reasonable bounds
+ * - Applies to all 4 amount pairs (debit1, debit2, credit1, credit2)
+ *
+ * @example
+ * const errors = validateForeignCurrency(records, {
+ *   useCaseId: 'monthly-expense',
+ *   defaultCurrency: 'ILS',
+ *   tolerance: 0.005
+ * });
+ * // Returns: [] if valid, or errors like:
+ * // ["monthly-expense - Record 0 (uuid-123): foreign currency (USD) but no foreign amounts"]
+ * // ["monthly-expense - Record 1 (uuid-456): local currency (ILS) but has foreign amounts"]
+ * // ["monthly-expense - Record 2 (uuid-789): suspicious exchange rate in debit1 (rate=15.2000)"]
+ */
+export declare function validateForeignCurrency(records: LedgerRecord[], context: ValidationContext): string[];
+/**
+ * Validate no orphaned amounts (FR4)
+ *
+ * Ensures data integrity by validating that every non-zero amount field has
+ * a corresponding entity reference. This prevents "orphaned" amounts that
+ * cannot be attributed to any financial entity.
+ *
+ * An "orphaned amount" is a ledger entry where an amount value exists but
+ * its corresponding entity field is null. This violates double-entry
+ * bookkeeping principles where every amount must be associated with an entity.
+ *
+ * Rules enforced:
+ * - Primary fields (entity1): If amount > 0, entity must be present
+ * - Secondary fields (entity2): If entity is null, amount must also be null
+ *
+ * @param records - Array of ledger records to validate
+ * @param context - Validation context containing use-case ID
+ * @returns Array of error messages (empty if no orphaned amounts found)
+ *
+ * Functional Requirement: FR4 - Orphaned Amount Detection
+ * - Checks all 4 amount/entity pairs per record
+ * - Detects amounts without entities
+ * - Detects secondary fields that should be null
+ *
+ * @example
+ * const errors = validateNoOrphanedAmounts(records, {
+ *   useCaseId: 'monthly-expense',
+ *   defaultCurrency: 'ILS',
+ *   tolerance: 0.005
+ * });
+ * // Returns: [] if valid, or errors like:
+ * // ["monthly-expense - Record 0 (uuid-123): orphaned amount in debit_local_amount1/debit_entity1 (100.00 without entity)"]
+ */
+export declare function validateNoOrphanedAmounts(records: LedgerRecord[], context: ValidationContext): string[];
+/**
+ * Master validation function - runs all validators (FR1-FR10)
+ *
+ * Orchestrates comprehensive ledger validation by executing all individual
+ * validation functions in a logical sequence. This is the main entry point
+ * for validating a complete set of ledger records for a use-case.
+ *
+ * Validation hierarchy:
+ * 1. Per-record validation (FR1, FR10) - Each record is internally balanced
+ * 2. Aggregate validation (FR2) - Total debits equal total credits
+ * 3. Entity validation (FR3) - Each entity's position balances
+ * 4. Data integrity (FR4, FR5) - No orphaned amounts, all amounts positive
+ * 5. Business rules (FR6, FR7) - Foreign currency and date validation
+ * 6. Structural validation (FR8) - Record count matches expectations
+ *
+ * This function implements NFR2 (Error Reporting): Collects ALL errors before
+ * failing (no fail-fast), allowing comprehensive error discovery in a single run.
+ *
+ * @param records - Array of ledger records to validate
+ * @param expectedRecordCount - Expected number of ledger records for this use-case
+ * @param context - Validation context containing use-case ID, currency, and tolerance
+ * @returns Array of all error messages from all validators (empty if fully valid)
+ *
+ * Functional Requirements Implemented:
+ * - FR1: Per-Record Internal Balance
+ * - FR2: Aggregate Balance Validation
+ * - FR3: Entity-Level Balance Validation
+ * - FR4: Orphaned Amount Detection
+ * - FR5: Positive Amount Validation
+ * - FR6: Foreign Currency Validation
+ * - FR7: Date Validation
+ * - FR8: Record Count Validation
+ * - FR10: Empty Ledger Detection (within FR1)
+ *
+ * @example
+ * const errors = validateLedgerRecords(records, 24, {
+ *   useCaseId: 'monthly-expense',
+ *   defaultCurrency: 'ILS',
+ *   tolerance: 0.005
+ * });
+ * if (errors.length > 0) {
+ *   console.error('Validation failed:', errors);
+ * } else {
+ *   console.log('All validations passed');
+ * }
+ */
+export declare function validateLedgerRecords(records: LedgerRecord[], expectedRecordCount: number, context: ValidationContext): string[];