Complete the Budget Buddy demo workflow

[SQLtattoo]

Summary

Complete the Budget Buddy reference workflow so the training repository has a tested end state for the GH-300 demonstrations.

• Harden budget calculations and edge-case handling.
• Validate transaction data and confine file access to the configured data directory.
• Replace quadratic duplicate detection with single-pass counting and aggregation.
• Improve data-table sorting, pagination, and state validation.
• Add CSV export, merchant summaries, and a ranked top-merchants report section.
• Expand tests across calculations, processing, file I/O, tables, logging, and report orchestration.
• Refresh CI, Docker, editor configuration, trainer guidance, and user documentation.

Implementation decisions

• Keep numeric budget logic in BudgetCalculator and transaction shaping in TransactionProcessor to preserve clear module ownership.
• Validate imported records at the file boundary and prevent paths from escaping the configured base directory.
• Rank merchants by total expense with deterministic name-based tie ordering.
• Preserve logger-based application output and existing public entry points.
• Retain the demo branch's removal of explicit starter-issue hints while adding the reusable change workflow.

Tests

• ./.venv/Scripts/python.exe -m coverage erase
• ./.venv/Scripts/python.exe -m pytest -q
• 87 tests passed
• 99.75% total coverage, exceeding the 90% gate

Risks

• This is a broad reference-state update across application code, tests, CI, Docker, and training documentation, so reviewers should verify that the walkthrough still matches the intended teaching sequence.
• The completed implementation intentionally resolves workshop starter issues; merging it into main changes the baseline from an immature demo app to the completed reference state.
• Raising the coverage gate to 90% may expose failures when future changes add untested paths.

Notes

The runtime-generated data/exported_transactions.csv is intentionally excluded from version control.

[SQLtattoo]

@copilot resolve the merge conflicts in this pull request

[Copilot]

@copilot resolve the merge conflicts in this pull request

Resolved via merge commit 31d16d7. Only conflict was a trivial rename (AGENT.md → AGENTS.md); test suite still passes (87 passed, 99.75% coverage).

[Copilot]

🟡 Changes recommended

TransactionProcessor.validate_transaction() currently allows non-finite amounts (e.g., infinity), which can incorrectly treat invalid transactions as valid.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This pull request updates Budget Buddy to the completed reference workflow used for GH-300 training demos, adding defensive validation, new report features, improved performance characteristics, and a near-complete pytest suite with an enforced 90% coverage gate.

Changes:

• Hardened core app behavior: validated transaction processing, safer file I/O confined to a base directory, and completed budget-calculation edge-case handling.
• Added user-facing/reporting features: CSV export, merchant summaries/top-merchants ranking, and improved table search/sort/pagination behavior.
• Expanded automated tests broadly and raised the coverage threshold to --cov-fail-under=90, plus refreshed docs/CI/Docker/editor settings to match the reference state.

Tests (as reported in PR description): 87 tests passed; 99.75% total coverage.
Remaining risk: Broad cross-cutting changes; the starter-to-reference reset workflow (reset_for_demo.ps1) should be re-verified end-to-end for trainer delivery.

File summaries

File	Description
TRANSFORMATION_GUIDE.md	Notes that the repo is at the target state and points to reset script for workshop delivery.
README.md	Updates documentation to reflect the completed reference state and export/top-merchants behavior.
QUICK_REFERENCE.md	Replaces “intentional issues” list with a completed reference-state checklist.
INTENTIONAL_ISSUES.md	Converts starter-issue list into a resolved-issues record and coverage status summary.
CHANGELOG.md	Records the reference-state feature/completeness changes and the raised coverage gate.
DEMO_SCRIPT.md	Adjusts trainer guidance to explicitly reset to starter state for the intended teaching sequence.
AGENTS.md	Adds critical workflow expectations and additional agent guidance.
pytest.ini	Raises coverage gate from 30% to 90%.
.vscode/settings.json	Configures VS Code to run pytest and disables unittest discovery.
.github/workflows/ci.yml	Completes CI workflow to set up Python, install deps, and run pytest.
.github/copilot-instructions.md	Adds a reusable “Change Workflow” and emphasizes docstrings for public functions.
Dockerfile	Completes container build/run steps for the app.
main.py	Adds CSV export, top-merchants section, and updated completion logging.
calculator.py	Implements edge-case-safe calculations and completes forecast/budget-check helpers.
data_processor.py	Refactors to validated, linear-time processing; adds sorting, alerts, and merchant ranking.
data_table.py	Improves defensive copies, search/sort interactions, and validation for sorting/pagination helpers.
file_handler.py	Adds safe path resolution, structured validation for CSV/JSON I/O, and CSV writing support.
tests/test_budget_calculator.py	Adds extensive calculator edge-case and history tests.
tests/test_transaction_processor.py	Adds tests for validation, duplicates, grouping, sorting, alerts, and merchant ranking.
tests/test_file_handler.py	Adds tests for CSV/JSON validation, safe paths, and CSV writing constraints.
tests/test_logger.py	Adds coverage for nested log-file creation and UTF-8 writes.
tests/test_data_table.py	Adds comprehensive tests for search/sort/pagination/state and helper functions.
tests/test_main.py	Adds orchestration/report tests including export and logging behavior.

Review details

• Files reviewed: 23/23 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.