mortctl 0.1.0

package/src/types.ts

@@ -0,0 +1,216 @@
+/**
+ * Mortgage underwriting types for mortctl
+ */
+
+/** Loan program types */
+export type LoanProgram = 
+  | 'conventional'
+  | 'fha'
+  | 'va'
+  | 'usda'
+  | 'jumbo'
+  | 'non-qm';
+
+/** Property types */
+export type PropertyType =
+  | 'single-family'
+  | 'condo'
+  | 'townhouse'
+  | 'multi-family-2'
+  | 'multi-family-3'
+  | 'multi-family-4'
+  | 'manufactured'
+  | 'coop';
+
+/** Occupancy types */
+export type OccupancyType = 
+  | 'primary'
+  | 'second-home'
+  | 'investment';
+
+/** Loan purpose */
+export type LoanPurpose = 
+  | 'purchase'
+  | 'rate-term-refi'
+  | 'cash-out-refi';
+
+/** Amortization type */
+export type AmortizationType =
+  | 'fixed'
+  | 'arm-5-1'
+  | 'arm-7-1'
+  | 'arm-10-1'
+  | 'interest-only';
+
+/**
+ * Conforming loan limits by year and area
+ * 2026 limits (estimated based on trends)
+ */
+export interface LoanLimits {
+  /** Standard conforming limit (baseline counties) */
+  baseline: number;
+  /** High-cost area ceiling */
+  highCost: number;
+  /** FHA floor */
+  fhaFloor: number;
+  /** FHA ceiling */
+  fhaCeiling: number;
+}
+
+/**
+ * LTV calculation result
+ */
+export interface LtvResult {
+  /** Loan-to-value ratio (primary mortgage only) */
+  ltv: number;
+  /** Combined loan-to-value (includes second liens) */
+  cltv: number;
+  /** Home equity combined LTV (includes HELOCs) */
+  hcltv: number;
+  /** Whether PMI is required */
+  pmiRequired: boolean;
+  /** Estimated PMI amount (monthly) */
+  estimatedPmi?: number;
+  /** When PMI can be removed (at what LTV) */
+  pmiRemovalLtv?: number;
+}
+
+/**
+ * PMI calculation inputs
+ */
+export interface PmiInputs {
+  /** LTV percentage */
+  ltv: number;
+  /** Credit score */
+  creditScore: number;
+  /** Loan amount */
+  loanAmount: number;
+  /** Loan term in years */
+  termYears?: number;
+  /** Property type */
+  propertyType?: PropertyType;
+  /** Occupancy */
+  occupancy?: OccupancyType;
+}
+
+/**
+ * PMI calculation result
+ */
+export interface PmiResult {
+  /** Whether PMI is required */
+  required: boolean;
+  /** Monthly PMI amount */
+  monthlyAmount: number;
+  /** Annual PMI amount */
+  annualAmount: number;
+  /** PMI rate (percentage of loan) */
+  ratePercent: number;
+  /** LTV at which PMI can be cancelled */
+  cancellationLtv: number;
+  /** Estimated months until cancellation (based on normal amortization) */
+  monthsToCancel?: number;
+}
+
+/**
+ * Loan eligibility result
+ */
+export interface EligibilityResult {
+  /** Program name */
+  program: LoanProgram;
+  /** Whether eligible */
+  eligible: boolean;
+  /** Reasons if not eligible */
+  reasons?: string[];
+  /** Warnings/conditions */
+  warnings?: string[];
+  /** Maximum loan amount for this program */
+  maxLoanAmount?: number;
+  /** Minimum down payment required */
+  minDownPayment?: number;
+  /** Estimated rate adjustment vs baseline */
+  rateAdjustment?: number;
+}
+
+/**
+ * Complete loan scenario
+ */
+export interface LoanScenario {
+  /** Purchase price or appraised value */
+  propertyValue: number;
+  /** Down payment amount */
+  downPayment: number;
+  /** Base loan amount */
+  loanAmount: number;
+  /** Second lien amount (if any) */
+  secondLien?: number;
+  /** HELOC amount (if any) */
+  heloc?: number;
+  /** Interest rate */
+  interestRate: number;
+  /** Loan term in years */
+  termYears: number;
+  /** Credit score */
+  creditScore: number;
+  /** Property type */
+  propertyType: PropertyType;
+  /** Occupancy */
+  occupancy: OccupancyType;
+  /** Loan purpose */
+  purpose: LoanPurpose;
+  /** Number of units (for multi-family) */
+  units?: number;
+  /** County for loan limits */
+  county?: string;
+  /** State */
+  state?: string;
+  /** First-time homebuyer */
+  firstTimeHomebuyer?: boolean;
+  /** Veteran status (for VA) */
+  veteran?: boolean;
+  /** Rural location (for USDA) */
+  rural?: boolean;
+  /** Annual property taxes */
+  propertyTaxes?: number;
+  /** Annual homeowners insurance */
+  homeownersInsurance?: number;
+  /** Monthly HOA */
+  hoaDues?: number;
+}
+
+/**
+ * Monthly payment breakdown
+ */
+export interface PaymentBreakdown {
+  /** Principal and interest */
+  principalAndInterest: number;
+  /** Property taxes (monthly) */
+  propertyTaxes: number;
+  /** Homeowners insurance (monthly) */
+  homeownersInsurance: number;
+  /** PMI/MIP (if applicable) */
+  mortgageInsurance: number;
+  /** HOA dues */
+  hoaDues: number;
+  /** Total PITI + HOA */
+  totalPayment: number;
+}
+
+/**
+ * Full underwriting analysis
+ */
+export interface UnderwritingAnalysis {
+  /** Loan scenario */
+  scenario: LoanScenario;
+  /** LTV analysis */
+  ltv: LtvResult;
+  /** Payment breakdown */
+  payment: PaymentBreakdown;
+  /** Program eligibility for each program */
+  eligibility: EligibilityResult[];
+  /** Best recommended program */
+  recommendedProgram?: LoanProgram;
+  /** Risk flags */
+  riskFlags: string[];
+  /** Recommendations */
+  recommendations: string[];
+}

package/tests/calculations.test.ts

@@ -0,0 +1,154 @@
+import {
+  calculateLtv,
+  calculatePmi,
+  calculateMonthlyPayment,
+  calculatePaymentBreakdown,
+  getConformingLimit,
+  calculateFhaMip,
+  calculateVaFundingFee,
+  LOAN_LIMITS_2026,
+} from '../src/lib/calculations';
+import { LoanScenario } from '../src/types';
+
+describe('calculateMonthlyPayment', () => {
+  it('should calculate correct P&I for 30-year loan', () => {
+    const payment = calculateMonthlyPayment(300000, 6.5, 30);
+    expect(payment).toBeCloseTo(1896.20, 0);
+  });
+
+  it('should calculate correct P&I for 15-year loan', () => {
+    const payment = calculateMonthlyPayment(300000, 6.0, 15);
+    expect(payment).toBeCloseTo(2531.57, 0);
+  });
+
+  it('should handle 0% interest', () => {
+    const payment = calculateMonthlyPayment(120000, 0, 30);
+    expect(payment).toBeCloseTo(333.33, 0);
+  });
+});
+
+describe('calculateLtv', () => {
+  it('should calculate LTV correctly', () => {
+    const result = calculateLtv(400000, 320000);
+    expect(result.ltv).toBe(80);
+    expect(result.pmiRequired).toBe(false);
+  });
+
+  it('should identify PMI required above 80%', () => {
+    const result = calculateLtv(400000, 380000);
+    expect(result.ltv).toBe(95);
+    expect(result.pmiRequired).toBe(true);
+  });
+
+  it('should calculate CLTV with second lien', () => {
+    const result = calculateLtv(400000, 320000, 40000);
+    expect(result.ltv).toBe(80);
+    expect(result.cltv).toBe(90);
+  });
+
+  it('should calculate HCLTV with HELOC', () => {
+    const result = calculateLtv(400000, 320000, 0, 50000);
+    expect(result.ltv).toBe(80);
+    expect(result.hcltv).toBe(92.5);
+  });
+});
+
+describe('calculatePmi', () => {
+  it('should return no PMI for 80% LTV', () => {
+    const result = calculatePmi({ ltv: 80, creditScore: 720, loanAmount: 320000 });
+    expect(result.required).toBe(false);
+    expect(result.monthlyAmount).toBe(0);
+  });
+
+  it('should calculate PMI for 95% LTV', () => {
+    const result = calculatePmi({ ltv: 95, creditScore: 720, loanAmount: 380000 });
+    expect(result.required).toBe(true);
+    expect(result.monthlyAmount).toBeGreaterThan(0);
+    expect(result.cancellationLtv).toBe(78);
+  });
+
+  it('should have lower PMI for higher credit scores', () => {
+    const low = calculatePmi({ ltv: 90, creditScore: 680, loanAmount: 360000 });
+    const high = calculatePmi({ ltv: 90, creditScore: 760, loanAmount: 360000 });
+    expect(high.monthlyAmount).toBeLessThan(low.monthlyAmount);
+  });
+});
+
+describe('getConformingLimit', () => {
+  it('should return baseline for standard county', () => {
+    const limit = getConformingLimit(undefined, 1);
+    expect(limit).toBe(LOAN_LIMITS_2026.baseline);
+  });
+
+  it('should return high-cost limit for high-cost county', () => {
+    const limit = getConformingLimit('Los Angeles, CA', 1);
+    expect(limit).toBe(LOAN_LIMITS_2026.highCost);
+  });
+
+  it('should apply unit multipliers', () => {
+    const oneUnit = getConformingLimit(undefined, 1);
+    const twoUnit = getConformingLimit(undefined, 2);
+    expect(twoUnit).toBeGreaterThan(oneUnit);
+    expect(twoUnit).toBeCloseTo(oneUnit * 1.28, -2);
+  });
+});
+
+describe('calculateFhaMip', () => {
+  it('should calculate upfront MIP at 1.75%', () => {
+    const result = calculateFhaMip(300000, 96.5, 30);
+    expect(result.upfront).toBe(5250);
+  });
+
+  it('should calculate annual MIP based on LTV and term', () => {
+    const highLtv = calculateFhaMip(300000, 95, 30);
+    const lowLtv = calculateFhaMip(300000, 85, 30);
+    expect(highLtv.annualRate).toBeGreaterThan(lowLtv.annualRate);
+  });
+});
+
+describe('calculateVaFundingFee', () => {
+  it('should calculate lower fee with down payment', () => {
+    const noDown = calculateVaFundingFee(300000, 0, true);
+    const withDown = calculateVaFundingFee(300000, 10, true);
+    expect(withDown).toBeLessThan(noDown);
+  });
+
+  it('should calculate higher fee for subsequent use', () => {
+    const first = calculateVaFundingFee(300000, 0, true);
+    const subsequent = calculateVaFundingFee(300000, 0, false);
+    expect(subsequent).toBeGreaterThan(first);
+  });
+});
+
+describe('calculatePaymentBreakdown', () => {
+  const scenario: LoanScenario = {
+    propertyValue: 400000,
+    loanAmount: 320000,
+    downPayment: 80000,
+    interestRate: 6.5,
+    termYears: 30,
+    creditScore: 720,
+    propertyType: 'single-family',
+    occupancy: 'primary',
+    purpose: 'purchase',
+  };
+
+  it('should calculate all payment components', () => {
+    const breakdown = calculatePaymentBreakdown(scenario);
+    expect(breakdown.principalAndInterest).toBeGreaterThan(0);
+    expect(breakdown.propertyTaxes).toBeGreaterThan(0);
+    expect(breakdown.homeownersInsurance).toBeGreaterThan(0);
+    expect(breakdown.totalPayment).toBeGreaterThan(breakdown.principalAndInterest);
+  });
+
+  it('should not include PMI at 80% LTV', () => {
+    const breakdown = calculatePaymentBreakdown(scenario);
+    expect(breakdown.mortgageInsurance).toBe(0);
+  });
+
+  it('should include PMI above 80% LTV', () => {
+    const highLtvScenario = { ...scenario, loanAmount: 380000, downPayment: 20000 };
+    const breakdown = calculatePaymentBreakdown(highLtvScenario);
+    expect(breakdown.mortgageInsurance).toBeGreaterThan(0);
+  });
+});

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"]
+}