finctl - Mortgage Financial Calculator CLI

A TypeScript CLI tool for calculating qualifying income and debt-to-income ratios for mortgage underwriting, following Fannie Mae Selling Guide standards.

Features

• Income Calculation: W-2 employment, self-employment (Form 1084), and other income sources
• DTI Calculation: Front-end and back-end ratios with loan program compliance checks
• Multiple Output Formats: JSON, table, and CSV
• Full Borrower Analysis: Combined income and DTI analysis
• MCP-Ready: Can be wrapped as MCP tools for AI agent integration

Installation

# Install dependencies
npm install

# Build the project
npm run build

# Link for local testing
npm link

# Or run directly with ts-node
npx ts-node src/index.ts --help

Usage

Income Calculations

W-2 Employment Income

# Basic salary
finctl income w2 --base 85000

# With overtime and bonus
finctl income w2 --base 85000 --overtime 12000 --bonus 8000

# With 2-year history (recommended)
finctl income w2 \
  --base 85000 --overtime 12000 --bonus 8000 \
  --year2-base 82000 --year2-overtime 10000 --year2-bonus 7000

# Table format output
finctl income w2 --base 96000 --format table

Example Output:

═══════════════════════════════════════════════════════════════
INCOME CALCULATION
═══════════════════════════════════════════════════════════════

Method: W-2 Employment Income

Monthly Income:  $8,000.00
Annual Income:   $96,000.00

BREAKDOWN:
───────────────────────────────────────────────────────────────
  Base Salary                                     $96,000.00

═══════════════════════════════════════════════════════════════

Self-Employment Income (Form 1084)

# Basic self-employment income
finctl income self-emp --year1 120000 --year2 95000

# With add-backs and adjustments
finctl income self-emp \
  --year1 120000 \
  --year2 95000 \
  --depreciation 15000 \
  --amortization 5000 \
  --meals 3000

Key Features:

• Applies depreciation, depletion, and amortization add-backs
• Subtracts 50% of meals & entertainment
• Calculates 2-year average
• Handles declining income scenarios

Other Income Sources

# Social Security income
finctl income other \
  --type social-security \
  --amount 2400 \
  --frequency monthly \
  --continuance 999

# Pension income
finctl income other \
  --type pension \
  --amount 36000 \
  --frequency annual \
  --continuance 10

From JSON File

finctl income file -f examples/income-w2.json --format table

Example JSON:

{
  "sources": [
    {
      "type": "w2",
      "employer": "Acme Corp",
      "base": 85000,
      "overtime": 12000,
      "bonus": 8000,
      "year2": {
        "base": 82000,
        "overtime": 10000,
        "bonus": 7000
      }
    }
  ]
}

DTI Calculations

Quick DTI Check

finctl dti \
  --income 8500 \
  --principal 1200 \
  --interest 800 \
  --taxes 400 \
  --insurance 150 \
  --debt "Auto loan:450:36" \
  --debt "Credit card:150" \
  --format table

Debt Format: "Description:Payment[:RemainingPayments[:Balance[:Type]]]"

Example Output:

═══════════════════════════════════════════════════════════════
DEBT-TO-INCOME RATIO CALCULATION
═══════════════════════════════════════════════════════════════

Front-End Ratio (Housing):   30.0%
Back-End Ratio (Total DTI):  37.1%

Total Housing Expense:      $2,550.00
Total Debt Payments:        $600.00
Total Monthly Obligations:  $3,150.00

LOAN PROGRAM COMPLIANCE:
───────────────────────────────────────────────────────────────
Conventional: ✓ PASS (≤45% back-end)
FHA:          ✓ PASS (≤31% front, ≤43% back)
VA:           ✓ PASS (≤41% back-end)

From JSON File

finctl dti -f examples/dti-example.json --format table

Example JSON:

{
  "monthlyIncome": 8500,
  "housing": {
    "principal": 1200,
    "interest": 800,
    "taxes": 400,
    "insurance": 150,
    "hoa": 200,
    "pmi": 85
  },
  "debts": [
    {
      "name": "Auto Loan",
      "payment": 450,
      "remaining": 36,
      "balance": 15000,
      "type": "installment"
    },
    {
      "name": "Student Loan",
      "payment": 0,
      "balance": 50000,
      "type": "student-loan"
    }
  ]
}

Full Borrower Analysis

finctl analyze -f examples/full-analysis.json --format table

Combines income calculation and DTI analysis with compliance checks and estimated max purchase price.

Calculation Rules

Income Calculation

1. Declining Income: If Year 1 < Year 2, use Year 1 only (most recent)
2. Variable Income: Use 2-year average for OT/bonus/commission if stable or increasing
3. Self-Employment: Apply Form 1084 methodology with add-backs and subtractions
4. Continuance: Income must continue for at least 3 years to qualify

DTI Calculation

1. Revolving Debt: Use minimum payment or 5% of balance, whichever is higher
2. Student Loans:
   • If deferred: use 1% of balance
   • If payment < 1% of balance: use 1% of balance
   • Otherwise: use actual payment
3. 10-Month Rule: Exclude installment debts with ≤10 payments remaining
4. Compliance Thresholds:
   • Conventional: 45% back-end (28% front-end guideline)
   • FHA: 31% front-end, 43% back-end
   • VA: 41% back-end (no front-end limit)

Output Formats

JSON (Default)

finctl income w2 --base 85000 --format json

Machine-readable format for integration with other tools.

Table

finctl income w2 --base 85000 --format table

Human-readable formatted output for terminal display.

CSV

finctl income w2 --base 85000 --format csv

Spreadsheet-compatible format.

Development

Run Tests

npm test

Run Tests in Watch Mode

npm run test:watch

Build

npm run build

Lint

npm run lint

Project Structure

finctl/
├── src/
│   ├── index.ts          # CLI entry point
│   ├── commands/
│   │   ├── income.ts     # Income calculation command
│   │   ├── dti.ts        # DTI calculation command
│   │   └── analyze.ts    # Full analysis command
│   └── lib/
│       ├── income.ts     # Income calculation logic
│       ├── dti.ts        # DTI calculation logic
│       ├── formatters.ts # Output formatting
│       └── types.ts      # TypeScript interfaces
├── tests/
│   ├── income.test.ts    # Income tests
│   └── dti.test.ts       # DTI tests
├── examples/             # Example JSON files
├── package.json
├── tsconfig.json
└── jest.config.js

Examples

See the examples/ directory for sample JSON files:

• income-w2.json - W-2 employment income
• income-mixed.json - Combined W-2 and self-employment
• dti-example.json - DTI calculation with multiple debts
• full-analysis.json - Complete borrower analysis

License

Apache-2.0 © Satyan Avatara