926e6a0dd4
feat: TOML Part 2 — user-global config, shadow warning, rtk init templates, 4 new built-in filters ( #351 )
...
* docs: update module count to 58 (toml_filter + verify_cmd)
* docs: bump version refs to 0.27.1, fix module count to 59
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com >
* feat: TOML DSL PR 2 — user-global config, shadow warning, init templates, 4 new filters
- toml_filter: add ~/.config/rtk/filters.toml (priority 2, between project and built-in)
- toml_filter: shadow warning when match_command overlaps a Rust-handled command
- init: rtk init generates .rtk/filters.toml template (local) and ~/.config/rtk/filters.toml (global)
- builtin_filters: add pre-commit, helm, gcloud, ansible-playbook (46/46 inline tests)
- README: add "Custom Filters" section with lookup table, primitives, examples, built-in list
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com >
* feat(filters): add quarto-render, pnpm-build, trunk-build from rtk discover data (52/52 tests)
* feat(filters): add docker-inspect, sops, docker-compose-ps built-in filters
Resolves issues #279 , #277 , #276 as TOML-native filters (no Rust required).
- docker-inspect: strip_ansi + truncate_lines_at=120 + max_lines=60
- sops: strip_ansi + strip_lines_matching blank lines + max_lines=40
- docker-compose-ps: strip_ansi + truncate_lines_at=120 + max_lines=40
6 inline tests added (2 per filter), all passing.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com >
* refactor(filters): split monolithic builtin_filters.toml into 28 individual files
Replace the 848-line src/builtin_filters.toml monolith with individual
files under src/filters/<name>.toml (1 filter + tests per file).
Files are concatenated alphabetically by build.rs at compile time into
OUT_DIR/builtin_filters.toml, then embedded via a BUILTIN_TOML constant
in toml_filter.rs. The build step validates TOML syntax and detects
duplicate filter names across files.
Benefits:
- Zero merge conflicts when multiple PRs add filters (different files)
- Clear PR diffs: "+1 file of 30 lines" vs "+30 lines in 850-line file"
- Easy onboarding: copy any .toml, rename, edit 3 fields — done
- Build-time TOML validation catches syntax errors before tests run
Changes:
- build.rs (new): concat + validate src/filters/*.toml
- Cargo.toml: add [build-dependencies] toml = "0.8"
- src/filters/*.toml (28 files): split from monolith
- src/filters/README.md (new): contributor guide
- src/toml_filter.rs: BUILTIN_TOML const + 5 include_str replacements
- src/builtin_filters.toml: deleted
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com >
* test(filters): add 5 new unit tests for multi-file architecture + wget filter
Unit tests added (toml_filter.rs):
- test_builtin_toml_has_schema_version: ensures build.rs injects schema_version
- test_builtin_all_expected_filters_present: guards against accidental file deletion
- test_builtin_filter_count: exact count check (fails if filter added/removed without update)
- test_builtin_all_filters_have_inline_tests: prevents shipping filters with no tests
- test_new_filter_discoverable_after_concat: simulates build.rs concat, verifies lookup
New built-in filter:
- src/filters/wget.toml: compact wget download output (strips connection/resolution
noise, short-circuits on 'saved [' to 'ok (downloaded)', 2 inline tests)
Test results: 661/661 unit tests, 60/60 inline TOML filter tests
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com >
* docs: add filter-workflow.md with Mermaid diagrams
Build pipeline + runtime lookup priority, both as Mermaid flowcharts.
Shows the full path from src/filters/*.toml to binary to execution.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com >
* fix: remove dead TOML filters — wget, git-checkout, git-merge, git-remote, cargo-run
These filters were never reachable: Clap routes rtk git/cargo commands
to their dedicated Rust modules before run_fallback is called. The TOML
engine only fires for unknown commands. Shipping dead filters gives false
confidence (inline tests pass, but filters never activate in production).
Also fixes P1-1 from the PR #386 review: wget was in RUST_HANDLED_COMMANDS
and the shadow warning fired at compile time but did not block the build.
Removed: cargo-run.toml, git-checkout.toml, git-merge.toml,
git-remote.toml, wget.toml
Updated test guards: count 29→24, expected list -5 names,
concat test 30→25.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com >
* fix: remove 3 dead TOML filters + update guards (PR #351 )
docker-inspect, docker-compose-ps, and pnpm-build are handled by
container.rs and pnpm_cmd.rs before run_fallback is reached — their
TOML filters never fire. Remove the files to avoid false documentation.
Update toml_filter.rs guards: expected list -3 names, count 24→21,
concat test 25→22. Update CONTRIBUTING.md example count to match.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com >
* fix: rebase on PR #349 — apply regex anchors, make on_empty, build.rs clippy, docs macOS path
- Add (\\s|$) word-boundary anchors to 6 tofu/mix match_command regexes
(tofu-plan, tofu-init, tofu-validate, tofu-fmt, mix-format, mix-compile)
- Add on_empty = "make: ok" to make.toml + update existing empty-output test
- Fix build.rs clippy: map_or(false, ...) → is_some_and(..)
- Add macOS alt path note to filter-workflow.md Mermaid diagram
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com >
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com >
2026-03-10 11:02:18 +01:00
521eb1b9bc
docs(tracking): complete API documentation + rustdoc comments
...
Add comprehensive documentation for tracking.rs public APIs:
**New Files:**
- docs/tracking.md (12 pages)
- Architecture & data flow
- All public APIs (12 methods, 7 types)
- Usage examples (basic, CI/CD, dashboards, Rust lib)
- JSON/CSV export schemas
- Database schema & migrations
- Integration examples (GitHub Actions, Python, Rust)
- Security, performance, troubleshooting
- claudedocs/TRACKING_DOCUMENTATION.md
- Documentation summary & metrics
**Updated Files:**
- src/tracking.rs
- Module-level docs (//!)
- Comprehensive doc comments (///) for all public APIs
- Examples with error handling
- Deprecation notices for legacy functions
- README.md
- Pointer to docs/tracking.md after rtk gain section
**Coverage:**
- 7 public structs documented
- 12 public methods documented
- 3 utility functions documented
- 20+ code examples
- 3 integration examples (CI/CD, dashboards, Rust lib)
- JSON/CSV/SQL schemas
**Testing:**
- All 6 tracking tests still pass
- 100% coverage maintained
Closes gap: CLI was documented, but public APIs were not.
Now fully documented for external integration (CI/CD, dashboards, Rust lib usage).
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com >
2026-02-03 11:22:20 +01:00
76703ca3f5
feat: add comprehensive temporal audit system for token savings analytics
...
Implement day-by-day, week-by-week, and monthly breakdowns with JSON/CSV export
capabilities for in-depth token savings analysis and reporting.
New Features:
- Daily breakdown (--daily): Complete day-by-day statistics without 30-day limit
- Weekly breakdown (--weekly): Sunday-to-Saturday week aggregations with date ranges
- Monthly breakdown (--monthly): Calendar month aggregations (YYYY-MM format)
- Combined view (--all): All temporal breakdowns in single output
- JSON export (--format json): Structured data for APIs, dashboards, scripts
- CSV export (--format csv): Tabular data for Excel, Google Sheets, data science
Technical Implementation:
- src/tracking.rs: Add DayStats, WeekStats, MonthStats structures with Serialize
- src/tracking.rs: Implement get_all_days(), get_by_week(), get_by_month() SQL queries
- src/main.rs: Extend Commands::Gain with --daily, --weekly, --monthly, --all, --format flags
- src/gain.rs: Add print_daily_full(), print_weekly(), print_monthly() display functions
- src/gain.rs: Implement export_json() and export_csv() for data export
Documentation:
- docs/AUDIT_GUIDE.md: Comprehensive guide with examples, workflows, integrations
- README.md: Update Data section with new audit commands and export formats
- claudedocs/audit-feature-summary.md: Technical summary and implementation details
Database Scope:
- Global machine storage: ~/.local/share/rtk/history.db
- Shared across all projects, worktrees, and Claude sessions
- 90-day retention policy with automatic cleanup
- SQLite with indexed timestamp for fast aggregations
Use Cases:
- Trend analysis: identify daily/weekly patterns in token usage
- Cost reporting: monthly savings reports for budget tracking
- Data science: export CSV/JSON for pandas, R, Excel analysis
- Dashboards: integrate JSON export with Chart.js, D3.js, Grafana
- CI/CD: automated weekly/monthly savings reports via GitHub Actions
Examples:
rtk gain --daily # Day-by-day breakdown
rtk gain --weekly # Weekly aggregations
rtk gain --all # All breakdowns combined
rtk gain --all --format json | jq . # JSON export with jq
rtk gain --all --format csv # CSV for Excel/analysis
Backwards Compatibility:
- All existing flags (--graph, --history, --quota) preserved
- Default behavior unchanged (summary view)
- No database migration required
- Zero breaking changes
Performance:
- Efficient SQL aggregations with timestamp index
- No impact on rtk command execution speed
- Instant queries even with 90 days of data
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com >
2026-01-30 11:12:45 +01:00
Florian BRUNIAUX