compctl 0.1.0

package/src/commands/trid.ts

@@ -0,0 +1,64 @@
+/**
+ * compctl trid command - Check TRID timing compliance
+ */
+
+import { Command } from 'commander';
+import { checkTridTiming } from '../lib/checks';
+
+export function createTridCommand(): Command {
+  const trid = new Command('trid')
+    .description('Check TRID timing compliance')
+    .requiredOption('--app-date <date>', 'Application date (YYYY-MM-DD)')
+    .option('--le-date <date>', 'Loan Estimate disclosure date')
+    .option('--cd-date <date>', 'Closing Disclosure date')
+    .option('--closing-date <date>', 'Scheduled closing date')
+    .option('--format <type>', 'Output format (json|table)', 'table')
+    .action(async (options) => {
+      const result = checkTridTiming({
+        applicationDate: options.appDate,
+        leDisclosureDate: options.leDate,
+        cdDisclosureDate: options.cdDate,
+        closingDate: options.closingDate,
+      });
+
+      if (options.format === 'json') {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log('═══════════════════════════════════════════════════════════════');
+        console.log('TRID TIMING COMPLIANCE');
+        console.log('═══════════════════════════════════════════════════════════════');
+        console.log('');
+        console.log(`Application Date:   ${result.applicationDate}`);
+        if (result.leDisclosureDate) console.log(`LE Disclosure:      ${result.leDisclosureDate}`);
+        if (result.cdDisclosureDate) console.log(`CD Disclosure:      ${result.cdDisclosureDate}`);
+        if (result.closingDate) console.log(`Closing Date:       ${result.closingDate}`);
+        console.log('');
+        console.log('STATUS');
+        console.log('───────────────────────────────────────────────────────────────');
+        const leStatus = result.leCompliant ? '✓ COMPLIANT' : '✗ NON-COMPLIANT';
+        const cdStatus = result.cdCompliant ? '✓ COMPLIANT' : '✗ NON-COMPLIANT';
+        console.log(`Loan Estimate:      ${leStatus}`);
+        if (result.daysUntilLeDeadline) {
+          console.log(`  Days until deadline: ${result.daysUntilLeDeadline}`);
+        }
+        console.log(`Closing Disclosure: ${cdStatus}`);
+        if (result.daysUntilCdDeadline) {
+          console.log(`  Days until deadline: ${result.daysUntilCdDeadline}`);
+        }
+        
+        if (result.findings.length > 0) {
+          console.log('');
+          console.log('FINDINGS');
+          console.log('───────────────────────────────────────────────────────────────');
+          for (const f of result.findings) {
+            const icon = f.severity === 'critical' ? '🚨' : f.severity === 'major' ? '⚠' : 'ℹ';
+            console.log(`${icon} [${f.code}] ${f.description}`);
+            if (f.remediation) console.log(`   → ${f.remediation}`);
+          }
+        }
+        console.log('═══════════════════════════════════════════════════════════════');
+      }
+    });
+
+  return trid;
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+/**
+ * compctl - Lending compliance checks
+ * Part of the LendCtl Suite
+ */
+
+import { Command } from 'commander';
+import { createTridCommand } from './commands/trid';
+import { createAtrCommand } from './commands/atr';
+import { createAdverseCommand } from './commands/adverse';
+
+const program = new Command();
+
+program
+  .name('compctl')
+  .description('Lending compliance checks (TRID, ATR/QM, HMDA, ECOA) - part of the LendCtl Suite')
+  .version('0.1.0');
+
+program.addCommand(createTridCommand());
+program.addCommand(createAtrCommand());
+program.addCommand(createAdverseCommand());
+
+program.parse();
+
+export * from './lib/checks';
+export * from './types';

package/src/lib/checks.ts

@@ -0,0 +1,279 @@
+/**
+ * Compliance check implementations
+ */
+
+import { LoanData, TridTiming, AtrQmResult, Finding, ComplianceCheck, AdverseActionNotice } from '../types';
+
+/**
+ * Check TRID timing requirements
+ */
+export function checkTridTiming(data: {
+  applicationDate: string;
+  leDisclosureDate?: string;
+  cdDisclosureDate?: string;
+  closingDate?: string;
+}): TridTiming {
+  const findings: Finding[] = [];
+  const appDate = new Date(data.applicationDate);
+  const today = new Date();
+  
+  // LE must be provided within 3 business days of application
+  const leDeadline = addBusinessDays(appDate, 3);
+  const daysUntilLeDeadline = businessDaysBetween(today, leDeadline);
+  
+  let leCompliant = true;
+  if (data.leDisclosureDate) {
+    const leDate = new Date(data.leDisclosureDate);
+    if (leDate > leDeadline) {
+      leCompliant = false;
+      findings.push({
+        code: 'TRID-LE-001',
+        severity: 'critical',
+        description: 'Loan Estimate not provided within 3 business days',
+        remediation: 'Issue LE immediately and document reason for delay',
+      });
+    }
+  } else if (daysUntilLeDeadline < 0) {
+    leCompliant = false;
+    findings.push({
+      code: 'TRID-LE-002',
+      severity: 'critical',
+      description: 'Loan Estimate deadline has passed',
+      remediation: 'Issue LE immediately',
+    });
+  }
+
+  // CD must be provided at least 3 business days before closing
+  let cdCompliant = true;
+  let daysUntilCdDeadline: number | undefined;
+  
+  if (data.closingDate) {
+    const closingDate = new Date(data.closingDate);
+    const cdDeadline = subtractBusinessDays(closingDate, 3);
+    daysUntilCdDeadline = businessDaysBetween(today, cdDeadline);
+    
+    if (data.cdDisclosureDate) {
+      const cdDate = new Date(data.cdDisclosureDate);
+      if (cdDate > cdDeadline) {
+        cdCompliant = false;
+        findings.push({
+          code: 'TRID-CD-001',
+          severity: 'critical',
+          description: 'Closing Disclosure not provided 3 business days before closing',
+          remediation: 'Reschedule closing or document consumer waiver',
+        });
+      }
+    } else if (daysUntilCdDeadline !== undefined && daysUntilCdDeadline < 0) {
+      cdCompliant = false;
+      findings.push({
+        code: 'TRID-CD-002',
+        severity: 'critical',
+        description: 'CD deadline has passed for scheduled closing',
+        remediation: 'Issue CD immediately or reschedule closing',
+      });
+    }
+  }
+
+  return {
+    applicationDate: data.applicationDate,
+    leDisclosureDate: data.leDisclosureDate,
+    cdDisclosureDate: data.cdDisclosureDate,
+    closingDate: data.closingDate,
+    leCompliant,
+    cdCompliant,
+    daysUntilLeDeadline: daysUntilLeDeadline > 0 ? daysUntilLeDeadline : undefined,
+    daysUntilCdDeadline: daysUntilCdDeadline !== undefined && daysUntilCdDeadline > 0 ? daysUntilCdDeadline : undefined,
+    findings,
+  };
+}
+
+/**
+ * Check ATR/QM requirements
+ */
+export function checkAtrQm(loan: LoanData): AtrQmResult {
+  const findings: Finding[] = [];
+  const riskyFeatures: string[] = [];
+  
+  // Check for risky features that disqualify QM
+  if (loan.negativeAmortization) {
+    riskyFeatures.push('Negative amortization');
+  }
+  if (loan.interestOnly) {
+    riskyFeatures.push('Interest-only payments');
+  }
+  if (loan.balloonPayment) {
+    riskyFeatures.push('Balloon payment');
+  }
+  if (loan.prepaymentPenalty) {
+    riskyFeatures.push('Prepayment penalty');
+  }
+  if (loan.termMonths > 360) {
+    riskyFeatures.push('Term exceeds 30 years');
+  }
+
+  // Points and fees limit (3% for loans >= $100k)
+  const pointsAndFeesLimit = loan.loanAmount >= 100000 
+    ? loan.loanAmount * 0.03 
+    : Math.min(loan.loanAmount * 0.03, 3000);
+  
+  const pointsAndFeesExceeded = loan.pointsAndFees > pointsAndFeesLimit;
+  if (pointsAndFeesExceeded) {
+    riskyFeatures.push('Points and fees exceed limit');
+    findings.push({
+      code: 'QM-PF-001',
+      severity: 'critical',
+      description: `Points and fees ($${loan.pointsAndFees}) exceed ${(pointsAndFeesLimit).toFixed(0)} limit`,
+      remediation: 'Reduce fees or document as non-QM',
+    });
+  }
+
+  // DTI check
+  const dtiLimit = 43;
+  const dtiExceeded = loan.dti > dtiLimit;
+  if (dtiExceeded) {
+    findings.push({
+      code: 'QM-DTI-001',
+      severity: 'major',
+      description: `DTI (${loan.dti}%) exceeds QM safe harbor limit (${dtiLimit}%)`,
+      remediation: 'May still qualify with AUS approval or as non-QM',
+    });
+  }
+
+  // Determine QM status
+  const hasRiskyFeatures = riskyFeatures.length > 0;
+  let isQm = !hasRiskyFeatures && !pointsAndFeesExceeded;
+  let qmType: AtrQmResult['qmType'];
+
+  if (isQm) {
+    if (loan.dti <= 43) {
+      qmType = 'safe-harbor';
+    } else {
+      qmType = 'rebuttable-presumption';
+      isQm = true; // Still QM but not safe harbor
+    }
+  } else {
+    qmType = 'non-qm';
+  }
+
+  return {
+    isQm,
+    qmType,
+    dti: loan.dti,
+    dtiLimit,
+    pointsAndFees: loan.pointsAndFees,
+    pointsAndFeesLimit,
+    hasRiskyFeatures,
+    riskyFeatures,
+    findings,
+  };
+}
+
+/**
+ * Check ECOA compliance and generate adverse action notice
+ */
+export function checkEcoa(loan: LoanData, decision: 'approved' | 'denied' | 'countered', reasons?: string[]): ComplianceCheck {
+  const findings: Finding[] = [];
+  const warnings: string[] = [];
+
+  if (decision === 'denied' || decision === 'countered') {
+    if (!reasons || reasons.length === 0) {
+      findings.push({
+        code: 'ECOA-AA-001',
+        severity: 'critical',
+        description: 'Adverse action requires specific reasons',
+        remediation: 'Provide specific reasons for denial',
+      });
+    } else if (reasons.length > 4) {
+      warnings.push('Best practice: limit adverse action reasons to 4 primary factors');
+    }
+  }
+
+  return {
+    regulation: 'ECOA',
+    passed: findings.filter(f => f.severity === 'critical').length === 0,
+    findings,
+    warnings,
+    recommendations: ['Document all adverse action reasons contemporaneously'],
+  };
+}
+
+/**
+ * Generate ECOA-compliant adverse action notice
+ */
+export function generateAdverseAction(
+  applicantName: string,
+  applicationDate: string,
+  creditorName: string,
+  creditorAddress: string,
+  reasons: string[]
+): AdverseActionNotice {
+  return {
+    applicantName,
+    applicationDate,
+    decisionDate: new Date().toISOString().split('T')[0],
+    creditorName,
+    creditorAddress,
+    reasons: reasons.slice(0, 4), // Max 4 reasons
+    ecoaNotice: `The federal Equal Credit Opportunity Act prohibits creditors from discriminating against credit applicants on the basis of race, color, religion, national origin, sex, marital status, age (provided the applicant has the capacity to enter into a binding contract); because all or part of the applicant's income derives from any public assistance program; or because the applicant has in good faith exercised any right under the Consumer Credit Protection Act. The federal agency that administers compliance with this law concerning this creditor is: Consumer Financial Protection Bureau, 1700 G Street NW, Washington, DC 20552.`,
+    fcraNotice: `You have the right to obtain a free copy of your credit report from the credit reporting agency that provided information used in this decision. You also have the right to dispute the accuracy or completeness of any information in your credit report.`,
+  };
+}
+
+/**
+ * Standard adverse action reasons
+ */
+export const ADVERSE_ACTION_REASONS = [
+  'Credit score does not meet minimum requirements',
+  'Debt-to-income ratio exceeds guidelines',
+  'Insufficient credit history',
+  'Delinquent past or present credit obligations',
+  'Collection action or judgment',
+  'Bankruptcy',
+  'Insufficient income for amount requested',
+  'Unable to verify employment',
+  'Unable to verify income',
+  'Length of employment',
+  'Insufficient property value',
+  'Property type not eligible',
+  'Loan-to-value ratio exceeds guidelines',
+  'Unacceptable collateral',
+  'Unable to verify residence',
+  'Temporary or irregular employment',
+];
+
+// Helper functions
+function addBusinessDays(date: Date, days: number): Date {
+  const result = new Date(date);
+  let added = 0;
+  while (added < days) {
+    result.setDate(result.getDate() + 1);
+    if (result.getDay() !== 0 && result.getDay() !== 6) {
+      added++;
+    }
+  }
+  return result;
+}
+
+function subtractBusinessDays(date: Date, days: number): Date {
+  const result = new Date(date);
+  let subtracted = 0;
+  while (subtracted < days) {
+    result.setDate(result.getDate() - 1);
+    if (result.getDay() !== 0 && result.getDay() !== 6) {
+      subtracted++;
+    }
+  }
+  return result;
+}
+
+function businessDaysBetween(start: Date, end: Date): number {
+  let count = 0;
+  const current = new Date(start);
+  while (current < end) {
+    if (current.getDay() !== 0 && current.getDay() !== 6) {
+      count++;
+    }
+    current.setDate(current.getDate() + 1);
+  }
+  return count;
+}

package/src/types.ts

@@ -0,0 +1,115 @@
+/**
+ * Compliance types for compctl
+ */
+
+/** Regulation identifiers */
+export type Regulation = 
+  | 'TRID' | 'ATR_QM' | 'HMDA' | 'ECOA' | 'RESPA' 
+  | 'TILA' | 'FCRA' | 'UDAAP' | 'SCRA' | 'FLOOD';
+
+/** Compliance check result */
+export interface ComplianceCheck {
+  regulation: Regulation;
+  passed: boolean;
+  findings: Finding[];
+  warnings: string[];
+  recommendations: string[];
+}
+
+/** Individual finding */
+export interface Finding {
+  code: string;
+  severity: 'critical' | 'major' | 'minor' | 'info';
+  description: string;
+  remediation?: string;
+}
+
+/** TRID timing check */
+export interface TridTiming {
+  applicationDate: string;
+  leDisclosureDate?: string;
+  cdDisclosureDate?: string;
+  closingDate?: string;
+  leCompliant: boolean;
+  cdCompliant: boolean;
+  daysUntilLeDeadline?: number;
+  daysUntilCdDeadline?: number;
+  findings: Finding[];
+}
+
+/** ATR/QM check result */
+export interface AtrQmResult {
+  isQm: boolean;
+  qmType?: 'safe-harbor' | 'rebuttable-presumption' | 'non-qm';
+  dti: number;
+  dtiLimit: number;
+  pointsAndFees: number;
+  pointsAndFeesLimit: number;
+  hasRiskyFeatures: boolean;
+  riskyFeatures: string[];
+  findings: Finding[];
+}
+
+/** HMDA LAR data */
+export interface HmdaLarData {
+  loanId: string;
+  actionTaken: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+  actionTakenDate: string;
+  loanType: 1 | 2 | 3 | 4;
+  loanPurpose: 1 | 2 | 31 | 32 | 4 | 5;
+  lienStatus: 1 | 2;
+  loanAmount: number;
+  combinedLtv?: number;
+  interestRate?: number;
+  rateSpread?: number;
+  hoepaStatus: 1 | 2 | 3;
+  propertyType: 1 | 2 | 3;
+  constructionMethod: 1 | 2;
+  occupancyType: 1 | 2 | 3;
+  propertyValue?: number;
+  applicantEthnicity: string[];
+  applicantRace: string[];
+  applicantSex: 1 | 2 | 3 | 4;
+  applicantAge?: number;
+  income?: number;
+  creditScore?: number;
+  dti?: number;
+  ausResult?: string;
+}
+
+/** Adverse action reasons */
+export interface AdverseActionNotice {
+  applicantName: string;
+  applicationDate: string;
+  decisionDate: string;
+  creditorName: string;
+  creditorAddress: string;
+  reasons: string[];
+  ecoaNotice: string;
+  fcraNotice?: string;
+}
+
+/** Loan data for compliance checks */
+export interface LoanData {
+  loanId: string;
+  applicationDate: string;
+  loanAmount: number;
+  propertyValue: number;
+  interestRate: number;
+  termMonths: number;
+  monthlyPayment: number;
+  dti: number;
+  ltv: number;
+  creditScore: number;
+  pointsAndFees: number;
+  prepaymentPenalty?: boolean;
+  negativeAmortization?: boolean;
+  interestOnly?: boolean;
+  balloonPayment?: boolean;
+  armFeatures?: { initialRate: number; margin: number; caps: number[] };
+  borrowerIncome: number;
+  propertyType: string;
+  occupancy: string;
+  loanPurpose: string;
+  loanType: string;
+}

package/tests/checks.test.ts

@@ -0,0 +1,159 @@
+import { checkTridTiming, checkAtrQm, checkEcoa, generateAdverseAction } from '../src/lib/checks';
+import { LoanData } from '../src/types';
+
+describe('checkTridTiming', () => {
+  it('should pass when LE provided in time', () => {
+    const today = new Date();
+    const appDate = new Date();
+    appDate.setDate(today.getDate() - 1);
+    
+    const result = checkTridTiming({
+      applicationDate: appDate.toISOString().split('T')[0],
+      leDisclosureDate: today.toISOString().split('T')[0],
+    });
+    
+    expect(result.leCompliant).toBe(true);
+  });
+
+  it('should track application date', () => {
+    const result = checkTridTiming({
+      applicationDate: '2026-02-26',
+    });
+    
+    expect(result.applicationDate).toBe('2026-02-26');
+  });
+});
+
+describe('checkAtrQm', () => {
+  const baseLoan: LoanData = {
+    loanId: 'TEST-001',
+    applicationDate: '2026-02-26',
+    loanAmount: 300000,
+    propertyValue: 375000,
+    interestRate: 6.5,
+    termMonths: 360,
+    monthlyPayment: 1896,
+    dti: 35,
+    ltv: 80,
+    creditScore: 720,
+    pointsAndFees: 5000,
+    borrowerIncome: 100000,
+    propertyType: 'single-family',
+    occupancy: 'primary',
+    loanPurpose: 'purchase',
+    loanType: 'conventional',
+  };
+
+  it('should identify QM safe harbor for compliant loan', () => {
+    const result = checkAtrQm(baseLoan);
+    expect(result.isQm).toBe(true);
+    expect(result.qmType).toBe('safe-harbor');
+  });
+
+  it('should flag negative amortization as risky', () => {
+    const loan = { ...baseLoan, negativeAmortization: true };
+    const result = checkAtrQm(loan);
+    expect(result.isQm).toBe(false);
+    expect(result.riskyFeatures).toContain('Negative amortization');
+  });
+
+  it('should flag interest-only as risky', () => {
+    const loan = { ...baseLoan, interestOnly: true };
+    const result = checkAtrQm(loan);
+    expect(result.isQm).toBe(false);
+    expect(result.riskyFeatures).toContain('Interest-only payments');
+  });
+
+  it('should flag balloon payment as risky', () => {
+    const loan = { ...baseLoan, balloonPayment: true };
+    const result = checkAtrQm(loan);
+    expect(result.isQm).toBe(false);
+    expect(result.riskyFeatures).toContain('Balloon payment');
+  });
+
+  it('should flag excessive points and fees', () => {
+    const loan = { ...baseLoan, pointsAndFees: 15000 }; // 5% of $300k
+    const result = checkAtrQm(loan);
+    expect(result.isQm).toBe(false);
+    expect(result.findings.some(f => f.code === 'QM-PF-001')).toBe(true);
+  });
+
+  it('should flag term over 30 years', () => {
+    const loan = { ...baseLoan, termMonths: 480 }; // 40 years
+    const result = checkAtrQm(loan);
+    expect(result.riskyFeatures).toContain('Term exceeds 30 years');
+  });
+
+  it('should identify rebuttable presumption for high DTI', () => {
+    const loan = { ...baseLoan, dti: 45 };
+    const result = checkAtrQm(loan);
+    expect(result.isQm).toBe(true);
+    expect(result.qmType).toBe('rebuttable-presumption');
+  });
+});
+
+describe('checkEcoa', () => {
+  const baseLoan: LoanData = {
+    loanId: 'TEST-001',
+    applicationDate: '2026-02-26',
+    loanAmount: 300000,
+    propertyValue: 375000,
+    interestRate: 6.5,
+    termMonths: 360,
+    monthlyPayment: 1896,
+    dti: 35,
+    ltv: 80,
+    creditScore: 720,
+    pointsAndFees: 5000,
+    borrowerIncome: 100000,
+    propertyType: 'single-family',
+    occupancy: 'primary',
+    loanPurpose: 'purchase',
+    loanType: 'conventional',
+  };
+
+  it('should require reasons for denial', () => {
+    const result = checkEcoa(baseLoan, 'denied');
+    expect(result.passed).toBe(false);
+    expect(result.findings.some(f => f.code === 'ECOA-AA-001')).toBe(true);
+  });
+
+  it('should pass with reasons provided', () => {
+    const result = checkEcoa(baseLoan, 'denied', ['DTI too high', 'Credit score']);
+    expect(result.passed).toBe(true);
+  });
+
+  it('should pass for approvals', () => {
+    const result = checkEcoa(baseLoan, 'approved');
+    expect(result.passed).toBe(true);
+  });
+});
+
+describe('generateAdverseAction', () => {
+  it('should generate complete notice', () => {
+    const notice = generateAdverseAction(
+      'John Smith',
+      '2026-02-26',
+      'ABC Mortgage',
+      '123 Main St',
+      ['DTI exceeds limit', 'Credit score too low']
+    );
+
+    expect(notice.applicantName).toBe('John Smith');
+    expect(notice.reasons.length).toBe(2);
+    expect(notice.ecoaNotice).toContain('Equal Credit Opportunity Act');
+    expect(notice.fcraNotice).toContain('credit report');
+  });
+
+  it('should limit reasons to 4', () => {
+    const notice = generateAdverseAction(
+      'John Smith',
+      '2026-02-26',
+      'ABC Mortgage',
+      '123 Main St',
+      ['Reason 1', 'Reason 2', 'Reason 3', 'Reason 4', 'Reason 5', 'Reason 6']
+    );
+
+    expect(notice.reasons.length).toBe(4);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}