amortizy 1.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '098cde951446da868e5cc5790b832794a09dd7ba991ffb34125f02053e59489e'
-  data.tar.gz: 923b3440f1046b7c0c92483997c24934623f234c5e47f78333b9d87ca8536bfa
+  metadata.gz: 00f0ccad91127633326557a81254c429737b526a834bb18de2235b842390f7ef
+  data.tar.gz: fcf4c2b4d999c1c276446fb36ea85984c7d380b4819b9592f55afcdb405985d2
 SHA512:
-  metadata.gz: 01c8a63684018625527eb633d6b7febc03b92d37ed20221b6138dc66080908ba4d5a0ef4649ae65172cbe67a9d1cb6c455ad70d95804ef9b64e9df083c75ec1b
-  data.tar.gz: d57d565cf0631f7f7016776111b1c1fe680549ae1a7583f30ba2c0cdf7b44bf2650e029a43e1593368f162c9209c1c5bca2d93c3eb5e7e95e96c98571b5d2de8
+  metadata.gz: 73e33d2c4a0ee6f0ab15d9618d4aa53df5bbbe16608630f125dac377e674e82bf8c576362e492257692c928b6ec0328781cd91c752a57b8d55c36946154fb804
+  data.tar.gz: 0c9e25aabdceee720c8fb6fcf2367b101fbce214642e4be84022f0ea2ca166478ea2bbeb190018bca41c03fe63b5e87963e5c79f1fc23b4b333cea71d72d8314

data/CHANGELOG.md

@@ -1,5 +1,170 @@
-## [Unreleased]
+# Changelog
 
-## [0.1.0] - 2025-12-02
+All notable changes to this project will be documented in this file.
 
-- Initial release
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.1.0] - 2026-04-20
+
+### Added
+
+#### Commercial Financing Disclosure Module
+- **`Amortizy::Disclosure`** - new class that computes disclosure data elements for
+  closed-end commercial loan transactions per California SB 1235 (Title 10, Chapter 3)
+- **APR calculation** using the actuarial method per Appendix J of Regulation Z
+  (12 CFR Part 1026, section 940) with Newton-Raphson solver and bisection fallback
+- **Finance charge** - total dollar cost of financing including interest and all fees (section 943)
+- **Amount financed** - principal adjusted for prepaid finance charges (section 900(a)(1)(B))
+- **Recipient funds** - net amount disbursed to borrower after third-party payoffs (section 900(a)(26))
+- **Term display** - formatted per regulation: days for terms <= 1 year,
+  years/months for longer terms (section 901(a)(4))
+- **Average monthly cost** - automatically computed for non-monthly payment frequencies (section 910(a)(12))
+- **Prepayment information** - structured data for prepayment penalty disclosures (section 910(a)(8-10))
+- **`#to_h`** - flat hash of all computed values
+- **`#to_labeled_h`** - hash with regulation-correct labels from section 910
+
+#### Design Notes
+- Disclosure class wraps an existing `AmortizationSchedule` — no changes to the engine API
+- Values are jurisdiction-agnostic: computed per the most stringent methodology (California),
+  usable for any state's commercial financing disclosure requirements
+- Origination fee is treated as a prepaid finance charge by default
+- APR rounded to nearest 10 basis points per section 901(a)(5)
+- APR accuracy within 1/8 of 1 percentage point tolerance per section 955
+
+## [2.0.0] - 2026-04-19
+
+### Added
+
+#### Dynamic Payment Engine
+- **Monthly payment frequency** - the most common loan payment type, now supported
+- **Bi-weekly payment frequency** - every 14 days
+- **`num_payments` input** - specify exact payment count instead of term length
+- **Any term length** - no longer restricted to 6, 9, 12, 15, 18 months
+- Dynamic payment count calculation based on frequency and term
+
+#### Public API
+- `#schedule` - returns frozen array of payment hashes (replaces private `generate_schedule_data`)
+- `#summary` - returns hash with loan totals, dates, and payment info
+- `#end_date` - last payment date
+- `#total_interest` - sum of all interest payments
+- `#total_paid` - sum of all payments
+- `#payment_amount` - regular payment amount
+
+#### Code Organization
+- Extracted `ConsoleFormatter` for terminal output
+- Extracted `CsvFormatter` for CSV export
+- Engine class now focused on amortization math only
+
+### Changed
+- `term_months` is now optional (provide `term_months` OR `num_payments`, not both)
+- Removed hardcoded payment count lookup table - all counts calculated dynamically
+- Minimum Ruby version bumped to 3.0
+
+### Breaking Changes
+- `term_months` is no longer a required keyword argument
+- **Daily frequency payment counts changed significantly.** v1.0 used a hardcoded lookup table with business-day-approximate counts (e.g., 248 payments for 12 months). v2.0 calculates dynamically using calendar days (365 for 12 months) unless `bank_days_only: true` is set. This is a ~47% increase in payment count for daily-frequency loans without `bank_days_only`. If your application relied on v1.0 daily payment counts, set `bank_days_only: true` to get business-day counts, or use `num_payments` to specify the exact count.
+- Weekly frequency payment counts may differ by 0-1 due to rounding in dynamic calculation
+- `principal` must now be positive (zero and negative values raise `ArgumentError`)
+
+## [1.0.0] - 2024-12-02
+
+### Added
+
+#### Core Features
+- Initial release of Amortizy gem
+- Daily payment frequency support
+- Weekly payment frequency support
+- Flexible loan terms: 6, 9, 12, 15, and 18 months
+- Simple interest calculation method (accrued daily)
+- Precomputed interest calculation method (fixed per payment)
+
+#### Advanced Loan Features
+- Grace period handling with automatic interest capitalization
+- Interest-only payment periods
+- Origination fee support (added to principal)
+- Additional fee support with three treatment options:
+  - Distributed across all payments
+  - Added to principal upfront
+  - Collected as separate first payment
+
+#### Bank Day Calculations
+- Weekend skipping (Saturday/Sunday)
+- US Federal Reserve holiday support (11 holidays)
+- Automatic weekend observation rules for holidays
+
+#### Output Options
+- Console output with formatted tables
+- CSV export functionality
+- Programmatic access to schedule data
+
+#### Testing
+- Comprehensive RSpec test suite with 29 test cases
+- 100% test pass rate
+- Coverage of all features and edge cases
+
+#### Documentation
+- Complete README with API reference
+- Usage examples for common scenarios
+- Detailed parameter documentation
+- Contributing guidelines
+
+### Dependencies
+- holidays gem (~> 8.0) for federal holiday detection
+- RSpec (~> 3.0) for testing
+
+### Requirements
+- Ruby 2.7 or higher
+
+---
+
+## Version History
+
+### [1.0.0] - 2024-12-02
+Initial public release
+
+---
+
+## Upgrade Guide
+
+### From Pre-release to 1.0.0
+
+If you were testing pre-release versions, upgrade by:
+
+```bash
+gem uninstall amortizy
+gem install amortizy
+```
+
+Or in your Gemfile:
+
+```ruby
+gem 'amortizy', '~> 1.0'
+```
+
+Then run:
+
+```bash
+bundle update amortizy
+```
+
+---
+
+## Future Plans
+
+Potential features for future releases:
+
+- More interest calculation methods
+- Support for additional holiday calendars (state, international)
+- Balloon payment support
+- Variable interest rates
+- Payment modification capabilities
+- Enhanced reporting formats
+
+---
+
+## Links
+
+- [RubyGems](https://rubygems.org/gems/amortizy)
+- [GitHub Repository](https://github.com/zapatify/amortizy)
+- [Issue Tracker](https://github.com/zapatify/amortizy/issues)

data/CONTRIBUTING.md

@@ -0,0 +1,290 @@
+# Contributing to Amortizy
+
+First off, thank you for considering contributing to Amortizy! It's people like you that make Amortizy such a great tool.
+
+## Code of Conduct
+
+This project and everyone participating in it is governed by the principle of respect and professionalism. By participating, you are expected to uphold this standard.
+
+## How Can I Contribute?
+
+### Reporting Bugs
+
+Before creating bug reports, please check the [existing issues](https://github.com/zapatify/amortizy/issues) to avoid duplicates.
+
+When you are creating a bug report, please include as many details as possible:
+
+* **Use a clear and descriptive title**
+* **Describe the exact steps to reproduce the problem**
+* **Provide specific examples** - Include code snippets, loan parameters, or output
+* **Describe the behavior you observed** and what you expected to see
+* **Include your environment details**:
+  - Ruby version (`ruby -v`)
+  - Amortizy version (`gem list amortizy`)
+  - Operating system
+
+**Example Bug Report:**
+
+```
+Title: Grace period interest not capitalizing correctly for weekly frequency
+
+Description:
+When using weekly payment frequency with a 7-day grace period, the interest 
+is not being properly capitalized into the principal.
+
+Steps to Reproduce:
+1. Create schedule with weekly frequency
+2. Set grace_period_days to 7
+3. Generate schedule
+4. Check effective principal
+
+Expected: Principal should increase by ~7 days of interest
+Actual: Principal remains unchanged
+
+Environment:
+- Ruby 3.2.0
+- Amortizy 1.0.0
+- macOS Sonoma
+```
+
+### Suggesting Enhancements
+
+Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion, please include:
+
+* **Use a clear and descriptive title**
+* **Provide a detailed description** of the suggested enhancement
+* **Explain why this enhancement would be useful** to most Amortizy users
+* **List any similar features** in other tools if applicable
+
+**Example Enhancement Request:**
+
+```
+Title: Add monthly payment frequency option
+
+Description:
+Currently Amortizy supports daily and weekly frequencies. Adding monthly 
+would be useful for traditional mortgage-style loans.
+
+Use Case:
+Many personal and business loans use monthly payments. This would make 
+Amortizy useful for a broader range of applications.
+
+Similar Features:
+- Most online loan calculators support monthly
+- Banking systems typically use monthly
+```
+
+### Pull Requests
+
+Pull requests are the best way to propose changes to the codebase.
+
+1. **Fork the repo** and create your branch from `main`
+2. **Make your changes**
+3. **Add tests** if you've added code that should be tested
+4. **Ensure the test suite passes** (`bundle exec rspec`)
+5. **Update documentation** if needed
+6. **Write a clear commit message**
+7. **Open a Pull Request**
+
+#### Pull Request Guidelines
+
+* Follow the existing code style
+* Write clear, descriptive commit messages
+* Include tests for new functionality
+* Update README.md if adding features
+* Update CHANGELOG.md under [Unreleased]
+* Keep PRs focused - one feature/fix per PR
+
+**Example PR Description:**
+
+```
+## Description
+Adds support for bi-weekly payment frequency
+
+## Changes
+- Added :biweekly to frequency validation
+- Updated payment calculations for bi-weekly schedules
+- Added tests for bi-weekly frequency
+- Updated README with bi-weekly examples
+
+## Testing
+- All existing tests pass
+- Added 3 new tests for bi-weekly functionality
+- Manually tested with various loan parameters
+
+## Documentation
+- Updated README.md with bi-weekly examples
+- Updated API reference table
+- Added to CHANGELOG.md
+```
+
+## Development Setup
+
+### Prerequisites
+
+```bash
+# Install Ruby 2.7 or higher
+ruby -v
+
+# Install Bundler
+gem install bundler
+```
+
+### Setup
+
+```bash
+# Clone your fork
+git clone https://github.com/YOUR_USERNAME/amortizy.git
+cd amortizy
+
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Run the CLI
+bundle exec exe/amortizy
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run specific test file
+bundle exec rspec spec/engine_spec.rb
+
+# Run with coverage (if configured)
+COVERAGE=true bundle exec rspec
+```
+
+### Code Style
+
+* Follow Ruby community style guidelines
+* Use 2 spaces for indentation (not tabs)
+* Keep lines under 100 characters when reasonable
+* Use meaningful variable and method names
+* Add comments for complex logic
+
+**Good Example:**
+```ruby
+def calculate_daily_interest(principal, annual_rate)
+  # Convert annual rate to daily and multiply by principal
+  (principal * annual_rate) / 365.0
+end
+```
+
+**Bad Example:**
+```ruby
+def calc(p,r)
+  p*r/365.0 # calculate interest
+end
+```
+
+## Project Structure
+
+```
+amortizy/
+├── lib/
+│   ├── amortizy.rb              # Main entry point
+│   └── amortizy/
+│       ├── version.rb           # Version number
+│       └── engine.rb            # Core logic
+├── spec/
+│   ├── spec_helper.rb           # RSpec configuration
+│   └── engine_spec.rb           # Main test file
+└── amortizy.gemspec             # Gem specification
+```
+
+## Testing Guidelines
+
+### Writing Tests
+
+* Use descriptive test names
+* Follow Arrange-Act-Assert pattern
+* Test both happy paths and edge cases
+* Mock external dependencies when appropriate
+
+**Example Test:**
+```ruby
+describe 'grace period' do
+  it 'capitalizes interest during grace period' do
+    # Arrange
+    schedule = Amortizy::AmortizationSchedule.new(
+      start_date: "2025-01-15",
+      principal: 100000.00,
+      term_months: 12,
+      annual_rate: 10.0,
+      frequency: :daily,
+      grace_period_days: 5
+    )
+    
+    # Act
+    effective_principal = schedule.send(:effective_principal)
+    
+    # Assert
+    expect(effective_principal).to be > 100000.00
+    expect(effective_principal).to be < 100200.00
+  end
+end
+```
+
+## Commit Message Guidelines
+
+Write clear, concise commit messages that explain what and why:
+
+```bash
+# Good commit messages
+git commit -m "Add bi-weekly payment frequency support"
+git commit -m "Fix interest calculation for leap years"
+git commit -m "Update README with precomputed interest examples"
+
+# Bad commit messages
+git commit -m "fix bug"
+git commit -m "updates"
+git commit -m "wip"
+```
+
+For larger commits, use multi-line messages:
+
+```bash
+git commit -m "Add support for adjustable rate mortgages
+
+- Add rate_changes parameter to accept rate change schedule
+- Update interest calculation to handle variable rates
+- Add comprehensive tests for ARM scenarios
+- Update documentation with ARM examples
+
+Closes #42"
+```
+
+## Documentation
+
+When adding features, update:
+
+1. **README.md** - Add usage examples
+2. **CHANGELOG.md** - Add to [Unreleased] section
+3. **Code comments** - Explain complex logic
+4. **RDoc/YARD** - Document public methods (if applicable)
+
+## Release Process
+
+(For maintainers)
+
+1. Update version in `lib/amortizy/version.rb`
+2. Update CHANGELOG.md with release date
+3. Commit changes: `git commit -am "Bump version to X.Y.Z"`
+4. Create tag: `git tag -a vX.Y.Z -m "Version X.Y.Z"`
+5. Push: `git push && git push --tags`
+6. Build: `gem build amortizy.gemspec`
+7. Publish: `gem push amortizy-X.Y.Z.gem`
+
+## Questions?
+
+Feel free to open an issue with the label "question" or reach out to the maintainers.
+
+## Thank You!
+
+Your contributions to open source, large or small, make projects like this possible. Thank you for taking the time to contribute.

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2025 Zapata
+Copyright (c) 2025 Rich Zapata
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal