|
| 1 | +--- |
| 2 | +name: ccusage-rust |
| 3 | +description: Guides ccusage Rust implementation work. Use when editing rust/crates, native packaging, Rust performance, parser/module layout, pricing embedding, or Rust/TypeScript parity. |
| 4 | +paths: |
| 5 | + - 'rust/**/*.rs' |
| 6 | + - 'rust/**/*.toml' |
| 7 | + - 'rust/**/build.rs' |
| 8 | +globs: 'rust/**/*.rs,rust/**/*.toml,rust/**/build.rs' |
| 9 | +--- |
| 10 | + |
| 11 | +# ccusage Rust |
| 12 | + |
| 13 | +Use this skill for the native Rust CLI under `rust/crates/ccusage` and `rust/crates/ccusage-terminal`. |
| 14 | + |
| 15 | +## Source Parity |
| 16 | + |
| 17 | +Rust must match the TypeScript implementation on `origin/main` unless the user explicitly scopes a behavior change. Before implementing or refactoring an agent, inspect the corresponding TypeScript adapter: |
| 18 | + |
| 19 | +```sh |
| 20 | +git ls-tree -r --name-only origin/main apps/ccusage/src/adapter |
| 21 | +git show origin/main:apps/ccusage/src/adapter/<agent>/index.ts |
| 22 | +git show origin/main:apps/ccusage/src/adapter/<agent>/parser.ts |
| 23 | +git show origin/main:apps/ccusage/src/adapter/<agent>/paths.ts |
| 24 | +``` |
| 25 | + |
| 26 | +Preserve report semantics, JSON fields, table columns, progress/spinner text, agent grouping, date filtering, `--offline`, `CLAUDE_CONFIG_DIR`, and source-specific environment variables. |
| 27 | + |
| 28 | +## Module Layout |
| 29 | + |
| 30 | +Do not keep growing `main.rs` or single large adapter files. Mirror the TypeScript responsibility boundaries where practical: |
| 31 | + |
| 32 | +- `adapter/<agent>/mod.rs` - public adapter surface and command wiring. |
| 33 | +- `adapter/<agent>/paths.rs` - environment variables, defaults, and path discovery. |
| 34 | +- `adapter/<agent>/parser.rs` - raw record parsing and token/model mapping. |
| 35 | +- `adapter/<agent>/loader.rs` - file walking, SQLite reads, dedupe, and date filtering entry points. |
| 36 | +- `adapter/<agent>/report.rs` - JSON/table row shaping when agent-specific. |
| 37 | +- shared modules stay in `types.rs`, `summary.rs`, `output.rs`, `pricing.rs`, `progress.rs`, and `date_utils.rs`. |
| 38 | + |
| 39 | +Keep public `pub(crate)` surfaces narrow. Prefer moving tests with the code they exercise instead of leaving all Rust tests in `main.rs`. |
| 40 | + |
| 41 | +When splitting large Rust modules or removing duplication, use the `reduce-similarities` skill, which runs `similarity-rs` for `.rs` files. |
| 42 | + |
| 43 | +## Pricing Embedding |
| 44 | + |
| 45 | +TypeScript uses build/macro-time pricing snapshots. Rust should not rely on a manually edited `claude-pricing.json` as the only embedded source. |
| 46 | + |
| 47 | +When changing pricing: |
| 48 | + |
| 49 | +- Prefer a `build.rs` step that fetches LiteLLM `model_prices_and_context_window.json` into `OUT_DIR`. |
| 50 | +- Keep a checked-in fallback snapshot so offline builds and network failures still work. |
| 51 | +- Load the generated build-time snapshot first, then fallback pricing, then runtime fetch when not `--offline`. |
| 52 | +- Add tests for embedded/offline pricing and context limits. |
| 53 | + |
| 54 | +## Performance |
| 55 | + |
| 56 | +Read the local Rust Performance Book clone before non-trivial optimization: |
| 57 | + |
| 58 | +```text |
| 59 | +/Users/ryoppippi/ghq/github.com/nnethercote/perf-book/src/profiling.md |
| 60 | +/Users/ryoppippi/ghq/github.com/nnethercote/perf-book/src/io.md |
| 61 | +/Users/ryoppippi/ghq/github.com/nnethercote/perf-book/src/heap-allocations.md |
| 62 | +/Users/ryoppippi/ghq/github.com/nnethercote/perf-book/src/parallelism.md |
| 63 | +/Users/ryoppippi/ghq/github.com/nnethercote/perf-book/src/type-sizes.md |
| 64 | +``` |
| 65 | + |
| 66 | +Profile before committing an optimization. Validate with end-to-end `hyperfine` and JSON/table parity, not only microbenchmarks. |
| 67 | + |
| 68 | +For ccusage workloads, check: |
| 69 | + |
| 70 | +- I/O count and buffering before CPU-only tweaks. |
| 71 | +- Avoid unnecessary `String` allocation and cloning on hot paths; prefer borrowed `&str`, `Arc<str>`, or typed summaries where ownership is needed. |
| 72 | +- Avoid returning large intermediate object vectors when worker-side aggregation or typed transfer payloads can preserve output. |
| 73 | +- Use parallelism only when it improves end-to-end command time on real fixture shapes. |
| 74 | +- Keep binary size visible when adding dependencies or enabling features. |
| 75 | + |
| 76 | +## Validation |
| 77 | + |
| 78 | +Use the `ccusage-testing` skill for Rust test commands. For perf or parity work, compare against `origin/main` TypeScript output for a stable fixture window before changing behavior. |
0 commit comments