tokf CLAUDE.md

tokf — Development Guidelines

Project Philosophy

tokf is an open source project built for the community. We are not looking for profits — this exists for open source sake. Every decision should prioritize:

• End-user experience — whether the user is a human or an LLM, the tool should be intuitive, fast, and transparent about what it's doing.
• Visibility — users should always understand what tokf is doing. Stderr notes, --timing, --verbose flags. Never hide behavior.
• Transparency — clear error messages, honest documentation, no dark patterns.

Commits

Use Conventional Commits strictly:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types: feat, fix, refactor, test, docs, chore, ci, perf, build

Scopes: config, filter, runner, output, cli, hook, tracking, history

Examples:

• feat(filter): implement skip/keep line filtering
• fix(config): handle missing optional fields in git-status.toml
• test(filter): add fixtures for cargo-test failure case
• ci: add clippy and fmt checks to GitHub Actions

Keep commits atomic — one logical change per commit. Don't bundle unrelated changes.

Code Quality

Testing

• Minimum 80% coverage, target 90%.
• Every module gets unit tests. Every filter gets integration tests with fixture data.
• Fixture-driven: save real command outputs as .txt files in tests/fixtures/. Tests load fixtures, apply filters, assert on output. No dependency on external tools in tests.
• Declarative filter tests: place test cases in a <stem>_test/ directory adjacent to the filter TOML (e.g. filters/git/push_test/ next to filters/git/push.toml). Each case is a TOML file with name, inline or fixture, exit_code, and [[expect]] blocks. Run with tokf verify. Every filter in the stdlib must have a _test/ suite — CI enforces this with tokf verify --require-all.
• Run cargo test after every meaningful change. Tests must pass before committing.