Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
146 lines (107 loc) · 4.72 KB

CONTRIBUTING.md

File metadata and controls

146 lines (107 loc) · 4.72 KB

Contributing to ledger-converter

Contributions are welcome! This document covers how to contribute, including how to pair with an AI assistant like Claude.

Getting Started

  1. Clone the repository
  2. Install Bun
  3. Run the test suite: 
    bun test
  4. Try the sample files: 
    bun qif-to-ledger.ts -a "Assets:Checking" examples/sample.qif
bun csv-to-ledger.ts -a "Assets:Checking" examples/sample.csv
bun ledger-converter-tui.ts

Project Structure

├── *-to-ledger.ts, ledger-converter*.ts  # Entry points (compilable to binaries)
├── cli/
│   ├── arg_parser.ts   # CLI argument parsing
│   ├── help.ts         # Help text for CLI tools
│   ├── tui.ts          # TUI utilities (prompts, colors, spinner)
│   └── types.ts        # Shared types
├── utils/
│   ├── qif_parser.ts       # QIF file parsing
│   ├── qif_parser.test.ts  # QIF parser tests
│   ├── csv_parser.ts       # CSV file parsing
│   ├── csv_parser.test.ts  # CSV parser tests
│   └── ledger_converter.ts # Ledger format conversion
└── examples/           # Sample files for testing

Making Changes

  1. Make your changes
  2. Run the test suite: bun test
  3. Test with the sample files in examples/
  4. Update documentation if adding new features
  5. Commit with a descriptive message

Pairing with Claude

This project was developed in collaboration with Claude, Anthropic's AI assistant. Claude can help with:

  • Understanding the codebase
  • Implementing new features
  • Debugging issues
  • Writing documentation

Tips for AI-Assisted Development

When working with Claude on this project:

  1. Share context: Point Claude to relevant files or describe the feature you're working on
  2. Use the sample files: examples/sample.qif and examples/sample.csv are useful for testing
  3. Test incrementally: Have Claude verify changes work before moving on

For AI Assistants

The following section contains guidance for AI assistants (like Claude) contributing to this project.

Testing the TUI

The interactive TUI (ledger-converter-tui.ts) requires TTY input and cannot be tested directly from a non-interactive shell. Use tmux to test the TUI:

The TUI defaults to sample files (examples/sample.qif or examples/sample.csv), so you can press Enter to accept defaults.

# Start TUI in a tmux session
tmux new-session -d -s tui-test -x 80 -y 24 'bun ledger-converter-tui.ts'

# Wait for startup
sleep 1

# Capture current screen
tmux capture-pane -t tui-test -p

# Send keystrokes (Enter accepts defaults, including sample file paths)
tmux send-keys -t tui-test Enter    # Select QIF format
tmux send-keys -t tui-test Enter    # Accept default: examples/sample.qif
tmux send-keys -t tui-test Enter    # Accept default: Assets:Checking

# Capture output after interaction
sleep 0.5
tmux capture-pane -t tui-test -p

# Clean up when done
tmux kill-session -t tui-test

Key tmux commands:

Command Purpose
tmux send-keys -t <session> Enter Press Enter
tmux send-keys -t <session> 'text' Type text
tmux send-keys -t <session> Up / Down Arrow keys
tmux send-keys -t <session> Escape Press Escape (go back)
tmux capture-pane -t <session> -p Capture current screen output

Code Organization

  • Entry points (*-to-ledger.ts, ledger-converter*.ts): Keep minimal, delegate to utilities
  • cli/: User interface code (arguments, help, TUI)
  • utils/: Core parsing and conversion logic (no UI dependencies)

Documentation Patterns

When updating documentation:

  • Update header comments in source files to list all entry points
  • Keep help text in cli/help.ts synchronized with README
  • Include sample file examples in "Try it" sections

Testing Changes

# Run the test suite (always do this first)
bun test

# Test CLI entry points with sample files
bun qif-to-ledger.ts -a "Assets:Checking" examples/sample.qif
bun csv-to-ledger.ts -a "Assets:Checking" examples/sample.csv
bun ledger-converter.ts -a "Assets:Checking" -i qif examples/sample.qif

# Test help output
bun qif-to-ledger.ts --help

# Test TUI (use tmux as described above)

# Compile binaries to verify build works
bun build --compile --outfile=ledger-converter-tui ledger-converter-tui.ts

Test Suite

Tests are located alongside the source files in utils/:

  • utils/qif_parser.test.ts - QIF parser tests (date formats, amounts, splits)
  • utils/csv_parser.test.ts - CSV parser tests (quoted fields, date formats, debit/credit)

When adding new parsing functionality, add corresponding tests. Bun's test runner automatically discovers *.test.ts files.