refactor(core): retire superseded report and scanner APIs

[makoMakoGo]

背景

关联 #176 的 B 部分。

这一部分不是编译器可以直接证明的私有死代码，而是已经偏离当前架构的公开表面：部分 API 因为是 pub 而不会触发 dead-code 警告，部分字段仍被写入却没有活跃读取者，还有两个 Graph 入口对同一聚合算法承诺了不同的定价失败语义。

本 PR 以当前 adapter + bounded fold 管线为唯一架构事实，删除旧中心 scanner 和中间投影包装器，并把 Graph 统一成一个 usage-first 公共入口。相关 breaking 决策记录在 docs/adr/0027-current-source-discovery-and-graph-semantics.md。

主要变化

1. Graph 只保留一个公开语义

• 删除 generate_local_graph_report，统一使用 generate_graph。
• token/model/source 数据是权威事实，pricing 只是派生成本投影；定价初始化失败不再导致整个 Graph 失败。
• 定价解析顺序保持明确：
  1. 同一进程内复用已初始化的 PricingService；
  2. 使用一小时 TTL 内的磁盘定价缓存；
  3. 缓存缺失或过期时尝试在线刷新；
  4. 刷新失败但存在旧缓存时使用旧缓存；
  5. 无任何可用定价时仍保留全部 token，无法定价的 cost 为 0.0。
• Graph JSON 新增 data.meta.pricingStatus，可能值为：

状态	含义
available	定价正常初始化且没有诊断。
availableWithWarnings	定价可用，但存在非致命诊断。
cachedFallback	在线刷新失败，明确使用旧缓存。
unavailable	刷新失败且无缓存；usage 仍完整返回。

• 存在诊断时输出 data.meta.pricingDiagnostics，CLI 同时写入 stderr；失败不会被伪装成静默成功。
• TUI 和 Graph 共用 core 的 PricingStatus 分类，删除 CLI 内重复枚举和判断逻辑。

2. 移除整个 legacy ScanResult API

旧路径由中央 scanner 发现所有文件和数据库，再写入 ScanResult。当前生产路径已经是：选择 adapters → 每个 adapter 发现自己的 source unit → parse/fold。Kilo、Goose、Kiro 等旧 DB 字段仍会被旧 scanner 写入，但活跃 adapter 从不读取。

本 PR 删除：

• ScanResult；
• scan_all_clients_with_scanner_settings；
• scan_all_clients_with_env_strategy；
• 已失去准确职责边界的 ScannerError；
• 只验证旧 driver 的测试和辅助代码。

仍保留并继续测试生产代码实际使用的扫描能力：ScannerSettings、scan_directory、extra-dir 解析、OpenCode DB 发现/合并和 source inspection 所需的路径解析函数。Kilo、Goose、Kiro、Hermes、Zed 等路径现在只有各自 adapter 一个发现权威。

3. 删除其余过时公开包装器

删除表面	当前替代边界
UsageDataWithDiagnostics 及 load_*usage_data*_with_diagnostics	当前 TUI 单次 fold 使用 load_prepared_tui_bundle_with_diagnostics；普通调用使用具体 report API。
UsageAccumulatorWithDiagnostics 及对应 loader	TuiBundleWithDiagnostics 是当前 usage + sessions + source-space 边界。
load_usage_data	使用具体 report API 或当前 TUI bundle。
WeekdayBucket、aggregate_by_weekday	仓内无消费者，不再保留假想公共投影。
parse_claude_file_with_cache*	使用 parse_claude_file / parse_claude_file_with_home；父级 cache 继续留在 resolver-aware 内部路径。

显式返回全部 UnifiedMessage 的 raw-message API 保留不变，因为 materialize messages 本身就是它们的公开契约，而不是旧架构泄漏。

4. 更新性能测量接口

• scripts/measure-scan-performance.sh 改为读取当前 report envelope 的 metadata.processingTimeMs，不再读取已经不存在的顶层字段。
• 新增可选 time-metrics|graph report 参数，让 Graph 复用同一套 warm-up、处理时间、wall/user/sys 和 max RSS 口径。
• 更新脚本测试，覆盖真实 envelope、Graph 参数转发、非法 report 和非数字 timing。

同机性能对比

基线是本机从当前 personal/local-clients HEAD 5c009d75eda7c70905b26c77805835b0e9a4699f 编译并安装的 /home/travis/.local/bin/tokscale；候选使用本 PR 的 release build。两者在同一 WSL2 主机、同一份实时本地语料上连续测量，每组先 warm-up 一次，再取 3 次中位数。Graph 使用 TOKSCALE_PRICING_CACHE_ONLY=1 排除网络波动。

Probe	main：处理 / wall / RSS	PR：处理 / wall / RSS	处理变化	RSS 变化	回归上限
Claude + Codex + OpenCode	6111 ms / 6.11 s / 49164 KiB	5853 ms / 5.86 s / 49012 KiB	-4.2%	-0.3%	6723 ms / 6.73 s / 54081 KiB
Kilo + Goose + Kiro	26 ms / 0.03 s / 17228 KiB	23 ms / 0.02 s / 16992 KiB	-11.5%	-1.4%	32 ms / 0.05 s / 18951 KiB
Graph：Claude + Codex + OpenCode	6099 ms / 6.25 s / 57308 KiB	6025 ms / 6.03 s / 57340 KiB	-1.2%	+0.06%	6709 ms / 6.88 s / 63039 KiB

所有候选中位数均低于预设回归上限。此次删除的大部分代码不在生产热路径，因此不宣称运行时性能优化；Graph RSS 的 +32 KiB 属于噪声级变化。

release 二进制从 19,823,032 增至 19,825,016 bytes（+1,984 bytes，+0.01%）。旧公开函数原本已可被 LTO 从 CLI 二进制剔除，新加入的 Graph pricing 状态和诊断抵消了源码删除带来的体积变化。

完整原始样本、测量契约和门槛见 docs/performance/2026-07-21-public-surface-cleanup.md。

验证

• cargo fmt --all -- --check
• cargo clippy --workspace --all-targets -- -D warnings
• TOKSCALE_CONFIG_DIR=/tmp/tokscale-b-cleanup-tests cargo test --workspace --no-fail-fast
• bash scripts/test-measure-scan-performance.sh
• git diff --check

以上检查全部通过；workspace 测试无失败，两个需要真实外部 catalog 的用例保持 ignored。

Summary by CodeRabbit

• 新功能

  • graph 输出新增定价状态与诊断信息。
  • 定价不可用时仍保留 token 用量，并支持旧缓存回退。
  • 新增按时段聚合用量的能力。

• 改进

  • 优化客户端与 OpenCode 数据发现及错误处理。
  • 性能测量工具支持 graph 报告模式，并统一读取处理耗时。

• 文档

  • 补充定价降级行为、图表语义及性能测量说明。

• 清理

  • 移除过时的公开接口与按星期聚合功能。

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 9d935d90-6a2c-4fba-ad4c-8b5cd109bf9c

📥 Commits

Reviewing files that changed from the base of the PR and between 79f705c and 14c15ef.

📒 Files selected for processing (18)

• crates/tokscale-cli/src/commands/clients.rs
• crates/tokscale-cli/src/commands/graph.rs
• crates/tokscale-cli/src/tui/app.rs
• crates/tokscale-cli/tests/cli_tests.rs
• crates/tokscale-core/src/aggregate/graph_result.rs
• crates/tokscale-core/src/aggregate/mod.rs
• crates/tokscale-core/src/aggregate/tui.rs
• crates/tokscale-core/src/lib.rs
• crates/tokscale-core/src/lib_tests.rs
• crates/tokscale-core/src/pricing/mod.rs
• crates/tokscale-core/src/scanner.rs
• crates/tokscale-core/src/sessions/claudecode.rs
• docs/adr/0027-current-source-discovery-and-graph-semantics.md
• docs/cli.md
• docs/performance/2026-07-10-scan-rss-optimization.md
• docs/performance/2026-07-21-public-surface-cleanup.md
• scripts/measure-scan-performance.sh
• scripts/test-measure-scan-performance.sh

💤 Files with no reviewable changes (2)

• crates/tokscale-core/src/sessions/claudecode.rs
• crates/tokscale-core/src/aggregate/tui.rs

---

Walkthrough

本次变更统一图生成的定价诊断输出，清理扫描、聚合和旧诊断加载公共 API，并扩展性能测量脚本以支持 graph 报告模式及新的处理时间字段路径。

Changes

图生成与定价诊断

Layer / File(s)	Summary
定价状态与图元数据 crates/tokscale-core/src/pricing/mod.rs, crates/tokscale-core/src/lib.rs, crates/tokscale-core/src/aggregate/graph_result.rs	新增 PricingStatus 分类逻辑；generate_graph 将定价状态和诊断写入 GraphMeta。
CLI 图导出与 TUI 状态 crates/tokscale-cli/src/commands/graph.rs, crates/tokscale-cli/src/tui/app.rs, crates/tokscale-cli/tests/cli_tests.rs	graph 导出定价元数据并将诊断写入 stderr；TUI 改用 core 的共享状态类型，CLI 测试覆盖 unavailable 与 cachedFallback。

公共接口与聚合边界清理

Layer / File(s)	Summary
聚合接口替换 crates/tokscale-core/src/aggregate/*, crates/tokscale-core/src/lib.rs	新增日内时段聚合接口，移除 weekday 聚合接口及其公开导出。
诊断加载边界收敛 crates/tokscale-core/src/lib.rs, crates/tokscale-core/src/lib_tests.rs, crates/tokscale-core/src/sessions/claudecode.rs	移除 usage diagnostics、accumulator diagnostics 和 Claude 缓存包装 API，测试改用 TUI bundle 诊断加载入口。

扫描器错误与发现测试调整

Layer / File(s)	Summary
扫描器错误契约与客户端降级 crates/tokscale-core/src/scanner.rs, crates/tokscale-cli/src/commands/clients.rs	额外扫描路径改用 SessionParseError，clients 对所有发现错误采用 Claude transcripts 降级处理。
发现与 extra dirs 测试重组 crates/tokscale-core/src/scanner.rs	补充 OpenCode 数据库和额外目录解析测试，删除旧 ScanResult 及相关集成测试。

性能报告模式扩展

Layer / File(s)	Summary
报告选择与耗时读取 scripts/measure-scan-performance.sh	支持 time-metrics 和 graph 报告，并从 metadata.processingTimeMs 读取耗时。
性能脚本测试与契约文档 scripts/test-measure-scan-performance.sh, docs/performance/*	测试新增 graph、未知报告和新 JSON 结构覆盖；文档更新测量命令、契约与结果记录。

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant generate_graph
  participant PricingLoader
  participant GraphMeta
  CLI->>generate_graph: generate graph
  generate_graph->>PricingLoader: load pricing with diagnostics
  PricingLoader-->>generate_graph: pricing data and diagnostics
  generate_graph->>GraphMeta: populate pricingStatus and pricingDiagnostics
  GraphMeta-->>CLI: export graph metadata

Loading

Possibly related PRs

• makoMakoGo/tokscale#69：涉及 pricing diagnostics 与 usage diagnostics API。
• makoMakoGo/tokscale#145：涉及 graph 命令的 JSON 元数据输出。
• makoMakoGo/tokscale#59：涉及 weekday 聚合接口及其 re-export。

Poem

小兔抱着诊断跑，
图中状态亮晶晶。
旧接口轻轻挥手，
新时段排成四行。
缓存若旧仍能用，
胡萝卜般稳当当。

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	标题准确概括了此次移除过时报告与扫描 API 的核心重构。
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/cleanup-b-public-surfaces

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codspeed-hq]

Merging this PR will not alter performance

✅ 41 untouched benchmarks

---

_{Comparing codex/cleanup-b-public-surfaces (14c15ef) with personal/local-clients (79f705c)}

[makoMakoGo]

@codex

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Bravo.

Reviewed commit: 14c15efae2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".