feat(docs): comprehensive VitePress documentation setup#134
feat(docs): comprehensive VitePress documentation setup#134ryoppippi wants to merge 565 commits into
Conversation
Replace hardcoded FIVE_HOURS_MS constant with SESSION_DURATION_MS to better reflect Claude Code official billing session terminology. This aligns with Anthropic documented 5-hour session billing cycles and makes the code more semantically clear about what the time period represents. The constant value remains unchanged (5 * 60 * 60 * 1000 = 18000000ms) but the name now accurately describes it as a session duration rather than just five hours.
Rename five-hour-blocks.internal.ts to session-blocks.internal.ts and corresponding test file to better reflect Claude Code session terminology. Update all import statements across the codebase to reference the new file names. Files renamed: - five-hour-blocks.internal.ts → session-blocks.internal.ts - five-hour-blocks.internal.test.ts → session-blocks.internal.test.ts Updated imports in: - data-loader.ts - commands/blocks.ts - session-blocks.internal.test.ts
Update type definition from FiveHourBlock to SessionBlock throughout the session-blocks.internal.ts file to better reflect Claude Code session terminology. This change aligns the type name with Anthropic official billing session concept rather than just describing the duration. All function signatures and variable declarations within the file have been updated to use the new SessionBlock type.
Update all imports and function calls to use new SessionBlock terminology: - loadFiveHourBlockData → loadSessionBlockData - FiveHourBlock → SessionBlock - identifyFiveHourBlocks → identifySessionBlocks Updated files: - data-loader.ts: function name and return type - commands/blocks.ts: import, function calls, and type annotations This completes the transition from FiveHour terminology to Session terminology in the core data handling logic.
Update command descriptions and user messages to use "session" terminology instead of "5-hour" references: - Command descriptions: "5-hour billing blocks" → "session billing blocks" - Error messages: "No active 5-hour block found" → "No active session block found" - UI titles: "5-Hour Block Status" → "Session Block Status" - Report headers: "5-Hour Blocks" → "Session Blocks" Updated in commands/blocks.ts and mcp.ts to provide consistent user-facing terminology that aligns with Claude Code official session concept.
Update all test files to use new session terminology: - FIVE_HOURS_MS → SESSION_DURATION_MS - FiveHourBlock → SessionBlock - loadFiveHourBlockData → loadSessionBlockData - identifyFiveHourBlocks → identifySessionBlocks This fixes compilation errors after refactoring to session-based naming convention. All test logic remains the same, only terminology has been updated to match the new API.
refactor: rename five-hour terminology to session terminology
- Add DEFAULT_SESSION_DURATION_HOURS constant (5 hours) - Update identifySessionBlocks to accept optional sessionDurationHours parameter - Update createBlock and createGapBlock to use configurable duration - Add sessionDurationHours to LoadOptions type in data-loader - Pass session duration through loadSessionBlockData to identifySessionBlocks This change maintains backward compatibility by using 5 hours as the default session duration when no custom value is provided.
- Test custom session durations (1h, 2h, 2.5h, 3h, 24h, 0.5h) - Test gap block creation with custom durations - Test edge cases (exactly equal durations, fractional hours) - Test backward compatibility (default 5h behavior) - All tests verify correct block creation, gap detection, and timing Covers various scenarios to ensure robust session block identification with configurable durations across different time ranges.
feat: add configurable session length to blocks command
Add comprehensive JSDoc documentation for: - Cost calculation modes and sort order types in types.internal.ts - Shared CLI argument definitions in shared-args.internal.ts - LiteLLM pricing URL constant in consts.internal.ts These foundational types and constants are used throughout the application and benefit from clear documentation explaining their purpose and usage.
Add JSDoc documentation for: - Logger instance and console.log export in logger.ts - Token calculation and aggregation functions in calculate-cost.ts These utility functions are fundamental building blocks used across the application for logging and cost calculations.
Add JSDoc documentation for: - Number, currency, and model name formatting functions in utils.internal.ts - ResponsiveTable class and helper methods in utils.table.ts These utilities handle data presentation and table rendering with responsive design for different terminal widths.
Add comprehensive JSDoc documentation for PricingFetcher class: - Class overview and Disposable pattern implementation - Model pricing fetching and caching methods - Cost calculation functions with detailed parameter documentation The PricingFetcher is critical for accurate cost calculations from LiteLLM pricing data with fallback matching for model names.
Add JSDoc documentation for pricing mismatch detection: - Threshold constants and type definitions for discrepancy tracking - Functions to detect and analyze pricing mismatches between pre-calculated costs and token-based calculations - Comprehensive reporting functionality for debugging cost differences This helps developers and users identify and troubleshoot pricing calculation inconsistencies in usage data.
Add comprehensive JSDoc documentation for session block management: - Type definitions for usage entries, blocks, and projections - Block identification and creation algorithms - Burn rate calculation and usage projection functions - Recent block filtering for time-based analysis Session blocks are core to billing period analysis and represent 5-hour usage windows with gap detection and projection capabilities.
Add JSDoc documentation for core data loading functionality: - Valibot schemas for usage data validation - Type definitions for daily, monthly, and session usage - Data loading functions with filtering and aggregation - Claude data directory path resolution and cost calculation modes The data loader is the foundation of the application, handling JSONL file processing, deduplication, and cost calculation integration.
Add JSDoc documentation for command line interface: - Main command setup and subcommand mapping in commands/index.ts - Session blocks command with formatting and parsing utilities - Constants for display thresholds and terminal width handling These command modules provide the user-facing CLI interface with responsive display formatting and comprehensive usage reporting.
docs: add comprehensive JSDoc documentation for all functions and types
…ev.20250614.1 (#86) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
- Replace @types/bun with vitest@^3.2.4 and @vitest/ui@^3.2.4 - Update test script from bun test to vitest run - Update release script to use vitest run instead of bun test - Add test:ui script for vitest UI - Remove test:dev script (not needed) This is the first step in migrating from bun test to vitest for better testing experience and modern tooling.
- Create vitest.config.ts with TypeScript support - Configure test environment for Node.js - Set up test file patterns and exclusions - Enable environment variable mocking capabilities - Configure coverage reporting with v8 provider - Set appropriate test timeouts and pool configuration This configuration provides a solid foundation for migrating from bun test to vitest with enhanced testing features.
- Enable vitest globals in vitest.config.ts - Add vitest/globals types to tsconfig.json - Remove explicit imports from calculate-cost.test.ts and data-loader.test.ts - Keep all test logic identical for compatibility - Tests now use global describe, it, expect functions Core test files (calculate-cost.test.ts and data-loader.test.ts) are now fully migrated and working with vitest. Remaining 5 test files still need import migration.
- Remove bun:test imports from 5 remaining test files: - data-loader-deduplication.test.ts - debug.test.ts - pricing-fetcher.test.ts - session-blocks.internal.test.ts - utils.internal.test.ts - All test files now use vitest globals (describe, it, test, expect) - All 164 tests pass successfully with vitest - Maintain identical test logic and behavior Migration from bun test to vitest is now complete for all test files.
- Replace manual beforeEach/afterEach env var management with vi.stubEnv - Use vi.unstubAllEnvs() for cleaner test isolation - Leverage vitest proper environment variable stubbing capabilities - Simplify test setup while maintaining comprehensive coverage - Fix TypeScript assertion for undefined env variable handling - All 164 tests continue to pass with improved testing approach Vitest environment variable mocking provides better isolation and cleaner test code compared to manual process.env manipulation.
- Change from bun test to bun run test in documentation - Clarify that tests now use vitest instead of bun:test - Maintain consistency with package.json scripts configuration
- Change from bun run report to bun run start for consistency - Align with actual package.json script configuration
- Install vitepress-plugin-mermaid@^2.0.17 dependency - Configure Mermaid plugin in VitePress config with withMermaid wrapper - Enable Mermaid diagram rendering in markdown files This fixes the issue where Mermaid diagrams were not rendering in the introduction page
Add DeepWiki and Package Stats links to the existing Links dropdown in the VitePress header navigation: - DeepWiki: Additional documentation resource - Package Stats: NPM download metrics from TanStack These links were extracted from the README badges to provide users with quick access to external resources.
Reduce README from 616 to 62 lines following tsdown minimalist approach - Keep only essential information: installation, basic usage, features - Remove detailed configuration, examples, and MCP setup - Add clear link to full documentation site - Maintain visual identity with logo and badges - Focus on getting users started quickly
Images were already moved to docs/assets/ in commit 9e1a7c0 but duplicates remained in docs root directory
Update screenshot path to use assets/ directory
Auto-formatted by lint-staged
Add documentation guidelines for screenshot placement in docs
Add comprehensive documentation for using ccusage as a library - Create new guide page explaining library usage with TypeScript examples - Cover installation, basic usage, cost calculation, and MCP integration - Include practical examples for web dashboards and custom reports - Add library usage page to VitePress sidebar in Integration section - Provide clear API reference links for detailed documentation
Move screenshot.png, logo.png, blocks-live.png, and mcp-claude-desktop.avif to docs/public/ for proper VitePress asset handling. These files were previously in docs/assets/ which is not the conventional location for public assets in VitePress documentation sites.
Delete docs/assets/ directory and all its contents (blocks-live.png, logo.png, logo.svg, mcp-claude-desktop.avif, screenshot.png) as these assets have been moved to docs/public/ which is the correct location for VitePress public assets. The docs/assets/ directory was incorrectly used and should be docs/public/ for proper static asset serving.
Update image references in documentation files to use new /screenshot.png, /blocks-live.png, and /mcp-claude-desktop.avif paths instead of /assets/ prefix. This fixes broken image links after moving assets from docs/assets/ to docs/public/ directory. Updated files: index.md, daily-reports.md, live-monitoring.md, and mcp-server.md.
Update jsdelivr CDN URLs in README.md to point to docs/public/ instead of docs/assets/ for logo.svg and screenshot.png. This ensures the README displays correct images after asset reorganization. The CDN will serve files from the new docs/public/ location which is the proper directory for VitePress public assets.
Restore the original inspiration and acknowledgments section that was missing from the docs. This includes: - Thanks to @milliondev for the original concept - Sponsors section with GitHub sponsors integration - Star History chart for project growth tracking
Add back the Sponsors and Star History sections to the main README file while keeping the detailed acknowledgments in the docs directory
Split sponsors and star history into a dedicated sponsors page while keeping acknowledgments focused on project inspiration
Move acknowledgments to the introduction page and remove separate acknowledgments file for better content organization
- Remove non-existent /api/types link causing 404 errors - Replace hardcoded sidebar with generated typedoc-sidebar.json - Add module descriptions to API index via post-processing - Include _consts.ts in TypeDoc generation for constants reference - Add disclaimer noting constants are not exported in public API
- Fix post-processing script to handle _consts module correctly - Add proper description for constants with export disclaimer - Fix script logic to prevent duplicate disclaimers
Document that block boundaries are calculated in UTC for consistent behavior across time zones References commit b8b871c which changed floorToHour to use setUTCMinutes instead of setMinutes
ryoppippi
force-pushed
the
docs/vitepress-setup
branch
from
30098cc to
169b7cc
Compare
- Remove all generated API documentation files from git - Add api/ directory to .gitignore to prevent future tracking - TypeDoc generated files should not be version controlled
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (7)
docs/api/data-loader/type-aliases/DateFilter.md (1)
5-7: Update type definition to match documented properties.The type alias is still defined as a generic
object, but the properties table shows specificsince?anduntil?string properties. This inconsistency needs to be resolved.-type DateFilter = object; +type DateFilter = { + since?: string; + until?: string; +};docs/api/calculate-cost/functions/createTotalsObject.md (1)
6-7: Add missing parameter type annotation.The function signature is missing the TypeScript type annotation for the
totalsparameter, which should beTokenTotalsaccording to the parameters table.-function createTotalsObject(totals): TotalsObject; +function createTotalsObject(totals: TokenTotals): TotalsObject;docs/guide/daily-reports.md (1)
175-178: Add note for cross-platform portability
The commanddate -d '7 days ago' +%Y%m%dis a GNU extension unavailable on macOS/BSD. Suggest adding a macOS alternative (e.g.,date -v-7d +%Y%m%d).docs/.vitepress/config.ts (1)
125-128: Fix TypeScript unsafe call errors on plugin configurations.The TypeScript compiler is still flagging unsafe calls on the plugin functions. This is the same issue identified in previous reviews.
As mentioned in the previous review, add explicit type annotations to resolve the
ts/no-unsafe-callandts/no-unsafe-member-accesserrors:-import { defineConfig } from 'vitepress'; +import { defineConfig } from 'vitepress'; +import type { Plugin as VitePlugin } from 'vite'; vite: { - plugins: [ - groupIconVitePlugin(), - ...llmstxt(), - ], + plugins: [ + groupIconVitePlugin() as VitePlugin, + ...(llmstxt() as VitePlugin[]), + ], }, markdown: { config(md) { - md.use(groupIconMdPlugin); + md.use(groupIconMdPlugin as any); }, },Also applies to: 132-134
docs/guide/monthly-reports.md (1)
63-63: Add cross-platform compatibility note for date command.The
date -dcommand used in the example is GNU-specific and won't work on macOS/BSD systems.Add a note about cross-platform alternatives:
# Show last 6 months ccusage monthly --since $(date -d '6 months ago' +%Y%m%d) + +# On macOS, use: +# ccusage monthly --since $(date -v-6m +%Y%m%d)Or provide a more portable solution using a specific date.
docs/guide/configuration.md (1)
167-177: MCP Server Configuration JSON
Replace hard tabs with spaces in the JSON code blocks to resolve MarkdownLintMD010errors, as flagged in previous rounds.docs/guide/mcp-server.md (1)
132-140: JSON Snippet Indentation
Replace hard tabs with spaces in the JSON code blocks to satisfy MarkdownLintMD010, as noted in prior reviews.
🧹 Nitpick comments (20)
src/commands/blocks.ts (1)
1-1: Remove redundant import.The
SessionBlocktype is already imported on line 11 from the same module. This duplicate import is unnecessary and should be removed for cleanliness.-import type { SessionBlock } from '../_session-blocks.ts';docs/api/calculate-cost/functions/createTotalsObject.md (1)
9-9: Fix grammar in function description.The phrase "a complete totals object" is grammatically incorrect since "totals" is plural.
-Creates a complete totals object by adding total token count to existing totals +Creates a complete totals object by adding total token count to existing totalsOr:
-Creates a complete totals object by adding total token count to existing totals +Creates complete totals object by adding total token count to existing totalsdocs/guide/sponsors.md (1)
1-24: LGTM! Well-structured sponsorship page.The sponsorship page is well-organized with proper GitHub Sponsors integration and a nice adaptive star history chart. The content encourages community support effectively.
Minor style suggestion: Consider hyphenating "open source" to "open-source" when used as a compound adjective:
-support the development of ccusage and other open source projects +support the development of ccusage and other open-source projectsdocs/api/calculate-cost/index.md (2)
1-2: Consider removing manual breadcrumb
VitePress provides built-in sidebar and page title support; you can remove the manual[ccusage](../index.md) / calculate-costbreadcrumb and configuresidebaror front-mattertitle/sidebarPositioninstead.
19-19: Fix article–noun agreement in function description
LanguageTool flags “Creates a complete totals object” as using a plural noun with “a.” Consider revising to “Creates a totals object by adding total token counts to existing totals.”docs/guide/library-usage.md (2)
60-61: Replace hard tabs with spaces
Several code examples contain hard tabs, triggeringMD010 no-hard-tabs. Replace tabs with consistent spaces in these blocks to satisfy markdownlint and improve readability.Also applies to: 74-74, 106-107, 117-117, 119-123, 125-125, 135-140
109-110: Ensure consistent module imports
In “Creating Custom Reports,” you import from the package root ('ccusage'), but prior examples use submodule paths. For clarity, importloadSessionDatafrom'ccusage/data-loader'andcalculateTotalsfrom'ccusage/calculate-cost'.docs/guide/daily-reports.md (2)
3-3: Verify image path for screenshot
The asset path/screenshot.pngmay not resolve under VitePress’s base; consider using a relative path (e.g.,./screenshot.png) or adjusting yourvitepress.config.jsbasesetting.
125-130: Unify JSON property names across docs
The daily JSON example uses"totalCost", whereas the dedicated JSON Output guide uses"costUSD". Align on a single property name for consistency.docs/guide/session-reports.md (2)
11-19: Consistent Language Identifiers
Consider adding a language identifier (e.g.,text) to the fenced block for the ASCII report and table output to ensure proper rendering and syntax highlighting.- ``` + ```text
114-151: JSON Output Example
The JSON output block is well-formatted and complete. You may want to annotate it withjsonfor syntax highlighting consistency:- ``` + ```jsondocs/guide/blocks-reports.md (2)
11-19: Example Output Framing
The ASCII frame and table provide a strong visual example. Consider labelling these fences withtextorconsolefor clarity:- ``` + ```text
176-203: JSON Output Section
The JSON example is accurate. To improve readability, ensure the code fence is tagged withjson.- ``` + ```jsondocs/guide/live-monitoring.md (3)
27-30: Visual Example
The duplicate image reference could be streamlined or replaced with a unique screenshot to avoid redundancy.
63-68: Tip Block Formatting
The code fence inside the tip block is untyped; addingbashortextwill ensure consistent syntax highlighting.
229-233: Fenced Code Language Identifier
Add a language identifier (e.g.,text) to the troubleshooting output block to avoid markdownlint MD040.- ``` + ```textdocs/guide/mcp-server.md (1)
9-13: Starting Instructions
The stdio and HTTP transport examples are clearly separated. Consider adding a comma for smoother reading:“The stdio transport is ideal for local integration, where the client directly spawns the process.”
docs/guide/cost-modes.md (3)
39-48: Specify a language for plain-text output snippets.The triple-backtick fences around the ASCII tables lack a language tag, which can hinder syntax highlighting. Consider using
textorconsole, e.g.:- ``` + ```text ┌──────────────┬─────────────┬────────┬─────────┬────────────┐ ... └──────────────┴─────────────┴────────┴─────────┴────────────┘ - ``` + ```Also applies to: 75-83, 110-118
148-149: Vary phrasing to avoid repetition.The sentence “You want to verify Claude’s official cost calculations:” echoes earlier lines. Rephrase to something like:
“Confirm official cost values provided by Claude Code:”
247-250: Refine bullet for “Maximum accuracy.”The bullet “Maximum accuracy — Best available cost information” could read more dynamically, for example:
“Maximum accuracy — Provides the most precise cost data available”
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📥 Commits
Reviewing files that changed from the base of the PR and between b2dfb165513e2486b704978e61d804a2aef830e3 and 169b7cca1ece5d9be4ff75f8d12a50aa9145e225.
⛔ Files ignored due to path filters (6)
bun.lockis excluded by!**/*.lockdocs/public/blocks-live.pngis excluded by!**/*.pngdocs/public/favicon.svgis excluded by!**/*.svgdocs/public/logo.pngis excluded by!**/*.pngdocs/public/logo.svgis excluded by!**/*.svgdocs/public/screenshot.pngis excluded by!**/*.png
📒 Files selected for processing (100)
CLAUDE.md(1 hunks)README.md(3 hunks)docs/.gitignore(1 hunks)docs/.vitepress/config.ts(1 hunks)docs/api/calculate-cost/functions/calculateTotals.md(1 hunks)docs/api/calculate-cost/functions/createTotalsObject.md(1 hunks)docs/api/calculate-cost/functions/getTotalTokens.md(1 hunks)docs/api/calculate-cost/index.md(1 hunks)docs/api/consts/index.md(1 hunks)docs/api/consts/variables/BLOCKS_COMPACT_WIDTH_THRESHOLD.md(1 hunks)docs/api/consts/variables/BLOCKS_DEFAULT_TERMINAL_WIDTH.md(1 hunks)docs/api/consts/variables/BLOCKS_WARNING_THRESHOLD.md(1 hunks)docs/api/consts/variables/CLAUDE_CONFIG_DIR_ENV.md(1 hunks)docs/api/consts/variables/CLAUDE_PROJECTS_DIR_NAME.md(1 hunks)docs/api/consts/variables/DEBUG_MATCH_THRESHOLD_PERCENT.md(1 hunks)docs/api/consts/variables/DEFAULT_CLAUDE_CODE_PATH.md(1 hunks)docs/api/consts/variables/DEFAULT_CLAUDE_CONFIG_PATH.md(1 hunks)docs/api/consts/variables/DEFAULT_RECENT_DAYS.md(1 hunks)docs/api/consts/variables/DEFAULT_REFRESH_INTERVAL_SECONDS.md(1 hunks)docs/api/consts/variables/LITELLM_PRICING_URL.md(1 hunks)docs/api/consts/variables/MAX_REFRESH_INTERVAL_SECONDS.md(1 hunks)docs/api/consts/variables/MCP_DEFAULT_PORT.md(1 hunks)docs/api/consts/variables/MIN_REFRESH_INTERVAL_SECONDS.md(1 hunks)docs/api/consts/variables/USAGE_DATA_GLOB_PATTERN.md(1 hunks)docs/api/consts/variables/USER_HOME_DIR.md(1 hunks)docs/api/data-loader/functions/calculateCostForEntry.md(1 hunks)docs/api/data-loader/functions/createUniqueHash.md(1 hunks)docs/api/data-loader/functions/formatDate.md(1 hunks)docs/api/data-loader/functions/formatDateCompact.md(1 hunks)docs/api/data-loader/functions/getClaudePaths.md(1 hunks)docs/api/data-loader/functions/getDefaultClaudePath.md(1 hunks)docs/api/data-loader/functions/getEarliestTimestamp.md(1 hunks)docs/api/data-loader/functions/loadDailyUsageData.md(1 hunks)docs/api/data-loader/functions/loadMonthlyUsageData.md(1 hunks)docs/api/data-loader/functions/loadSessionBlockData.md(1 hunks)docs/api/data-loader/functions/loadSessionData.md(1 hunks)docs/api/data-loader/functions/sortFilesByTimestamp.md(1 hunks)docs/api/data-loader/index.md(1 hunks)docs/api/data-loader/type-aliases/DailyUsage.md(1 hunks)docs/api/data-loader/type-aliases/DateFilter.md(1 hunks)docs/api/data-loader/type-aliases/LoadOptions.md(1 hunks)docs/api/data-loader/type-aliases/ModelBreakdown.md(1 hunks)docs/api/data-loader/type-aliases/MonthlyUsage.md(1 hunks)docs/api/data-loader/type-aliases/SessionUsage.md(1 hunks)docs/api/data-loader/type-aliases/UsageData.md(1 hunks)docs/api/data-loader/variables/dailyUsageSchema.md(1 hunks)docs/api/data-loader/variables/modelBreakdownSchema.md(1 hunks)docs/api/data-loader/variables/monthlyUsageSchema.md(1 hunks)docs/api/data-loader/variables/sessionUsageSchema.md(1 hunks)docs/api/data-loader/variables/usageDataSchema.md(1 hunks)docs/api/debug/functions/detectMismatches.md(1 hunks)docs/api/debug/functions/printMismatchReport.md(1 hunks)docs/api/debug/index.md(1 hunks)docs/api/index.md(1 hunks)docs/api/index/index.md(1 hunks)docs/api/logger/index.md(1 hunks)docs/api/logger/variables/log.md(1 hunks)docs/api/logger/variables/logger.md(1 hunks)docs/api/mcp/functions/createMcpHttpApp.md(1 hunks)docs/api/mcp/functions/createMcpServer.md(1 hunks)docs/api/mcp/functions/startMcpServerStdio.md(1 hunks)docs/api/mcp/index.md(1 hunks)docs/api/pricing-fetcher/classes/PricingFetcher.md(1 hunks)docs/api/pricing-fetcher/index.md(1 hunks)docs/api/typedoc-sidebar.json(1 hunks)docs/guide/blocks-reports.md(1 hunks)docs/guide/configuration.md(1 hunks)docs/guide/cost-modes.md(1 hunks)docs/guide/custom-paths.md(1 hunks)docs/guide/daily-reports.md(1 hunks)docs/guide/getting-started.md(1 hunks)docs/guide/index.md(1 hunks)docs/guide/installation.md(1 hunks)docs/guide/json-output.md(1 hunks)docs/guide/library-usage.md(1 hunks)docs/guide/live-monitoring.md(1 hunks)docs/guide/mcp-server.md(1 hunks)docs/guide/monthly-reports.md(1 hunks)docs/guide/related-projects.md(1 hunks)docs/guide/session-reports.md(1 hunks)docs/guide/sponsors.md(1 hunks)docs/index.md(1 hunks)docs/index.ts(1 hunks)docs/package.json(1 hunks)docs/tsconfig.json(1 hunks)docs/typedoc.config.mjs(1 hunks)docs/update-api-index.mjs(1 hunks)docs/wrangler.jsonc(1 hunks)eslint.config.js(1 hunks)package.json(1 hunks)src/_macro.ts(1 hunks)src/calculate-cost.ts(1 hunks)src/commands/blocks.ts(2 hunks)src/data-loader.ts(2 hunks)src/debug.ts(1 hunks)src/index.ts(1 hunks)src/logger.ts(1 hunks)src/mcp.ts(1 hunks)src/pricing-fetcher.ts(1 hunks)typedoc.json(1 hunks)
✅ Files skipped from review due to trivial changes (27)
- docs/api/consts/variables/MCP_DEFAULT_PORT.md
- docs/api/consts/variables/DEFAULT_RECENT_DAYS.md
- docs/api/consts/variables/DEFAULT_REFRESH_INTERVAL_SECONDS.md
- eslint.config.js
- docs/api/consts/variables/BLOCKS_COMPACT_WIDTH_THRESHOLD.md
- docs/api/consts/variables/MAX_REFRESH_INTERVAL_SECONDS.md
- docs/api/consts/variables/BLOCKS_DEFAULT_TERMINAL_WIDTH.md
- docs/api/consts/variables/MIN_REFRESH_INTERVAL_SECONDS.md
- docs/api/consts/variables/USER_HOME_DIR.md
- docs/api/consts/variables/DEFAULT_CLAUDE_CODE_PATH.md
- docs/api/consts/variables/DEBUG_MATCH_THRESHOLD_PERCENT.md
- docs/api/data-loader/functions/sortFilesByTimestamp.md
- docs/api/pricing-fetcher/index.md
- docs/api/data-loader/type-aliases/MonthlyUsage.md
- docs/api/consts/variables/DEFAULT_CLAUDE_CONFIG_PATH.md
- docs/api/consts/variables/CLAUDE_CONFIG_DIR_ENV.md
- docs/api/data-loader/type-aliases/DailyUsage.md
- src/index.ts
- docs/api/consts/variables/USAGE_DATA_GLOB_PATTERN.md
- docs/api/consts/variables/CLAUDE_PROJECTS_DIR_NAME.md
- docs/api/consts/variables/BLOCKS_WARNING_THRESHOLD.md
- docs/api/data-loader/type-aliases/UsageData.md
- docs/api/data-loader/functions/loadSessionBlockData.md
- docs/api/consts/variables/LITELLM_PRICING_URL.md
- docs/api/consts/index.md
- docs/guide/related-projects.md
- docs/package.json
🚧 Files skipped from review as they are similar to previous changes (51)
- docs/api/index/index.md
- docs/api/data-loader/functions/formatDate.md
- docs/api/logger/variables/logger.md
- docs/api/data-loader/functions/loadDailyUsageData.md
- docs/api/data-loader/type-aliases/SessionUsage.md
- src/debug.ts
- docs/api/data-loader/functions/loadSessionData.md
- docs/tsconfig.json
- src/calculate-cost.ts
- src/mcp.ts
- docs/api/debug/functions/detectMismatches.md
- docs/api/data-loader/functions/getClaudePaths.md
- docs/api/data-loader/functions/loadMonthlyUsageData.md
- docs/api/data-loader/functions/getDefaultClaudePath.md
- CLAUDE.md
- docs/api/debug/index.md
- docs/api/mcp/functions/createMcpHttpApp.md
- docs/api/mcp/functions/createMcpServer.md
- docs/api/mcp/functions/startMcpServerStdio.md
- docs/api/data-loader/type-aliases/ModelBreakdown.md
- docs/wrangler.jsonc
- docs/api/data-loader/functions/getEarliestTimestamp.md
- docs/.gitignore
- docs/api/logger/index.md
- src/logger.ts
- docs/api/index.md
- docs/api/calculate-cost/functions/getTotalTokens.md
- docs/api/data-loader/functions/formatDateCompact.md
- docs/api/debug/functions/printMismatchReport.md
- docs/api/typedoc-sidebar.json
- docs/api/mcp/index.md
- docs/api/data-loader/functions/createUniqueHash.md
- docs/index.md
- docs/api/data-loader/variables/dailyUsageSchema.md
- docs/api/calculate-cost/functions/calculateTotals.md
- package.json
- docs/api/data-loader/variables/monthlyUsageSchema.md
- docs/api/logger/variables/log.md
- docs/api/data-loader/functions/calculateCostForEntry.md
- docs/api/data-loader/type-aliases/LoadOptions.md
- src/data-loader.ts
- typedoc.json
- README.md
- docs/api/data-loader/variables/sessionUsageSchema.md
- src/pricing-fetcher.ts
- docs/api/data-loader/variables/usageDataSchema.md
- docs/guide/installation.md
- docs/api/data-loader/index.md
- docs/api/pricing-fetcher/classes/PricingFetcher.md
- docs/typedoc.config.mjs
- docs/api/data-loader/variables/modelBreakdownSchema.md
🧰 Additional context used
🪛 LanguageTool
docs/guide/index.md
[style] ~92-~92: This adverb was used twice in the sentence. Consider removing one of them or replacing them with a synonym.
Context: ...t Limitations - Local Files Only - Only analyzes data from your current machine...
(ADVERB_REPETITION_PREMIUM)
docs/guide/blocks-reports.md
[typographical] ~121-~121: If specifying a range, consider using an en dash instead of a hyphen.
Context: ...eatures: - Real-time updates every 1-60 seconds (configurable) - **Automatic to...
(HYPHEN_TO_EN)
[uncategorized] ~343-~343: Although a hyphen is possible, it is not necessary in a compound modifier in which the first word is an adverb that ends in ‘ly’.
Context: ...ated by calendar date - Monthly Reports - Monthly usage summaries - [Session R...
(HYPHENATED_LY_ADVERB_ADJECTIVE)
docs/api/calculate-cost/functions/createTotalsObject.md
[grammar] ~9-~9: The plural noun “totals” cannot be used with the article “a”. Did you mean “a complete total” or “complete totals”?
Context: ...ect(totals): TotalsObject; ``` Creates a complete totals object by adding total token count to e...
(A_NNS)
docs/api/calculate-cost/index.md
[grammar] ~19-~19: The plural noun “totals” cannot be used with the article “a”. Did you mean “a complete total” or “complete totals”?
Context: ...ctions/createTotalsObject.md) | Creates a complete totals object by adding total token count to e...
(A_NNS)
docs/api/data-loader/type-aliases/DateFilter.md
[misspelling] ~15-~15: Use “an” instead of ‘a’ if the following word starts with a vowel sound, e.g. ‘an article’, ‘an hour’.
Context: ...Property | Type | | ------ | ------ | | since? | string | |...
(EN_A_VS_AN)
[misspelling] ~16-~16: Use “an” instead of ‘a’ if the following word starts with a vowel sound, e.g. ‘an article’, ‘an hour’.
Context: ...id="since"> since? | string | | until? | string |
(EN_A_VS_AN)
docs/guide/configuration.md
[uncategorized] ~144-~144: Possible missing preposition found.
Context: ...rks with restricted internet access - Corporate environments - Behind firewalls or pr...
(AI_HYDRA_LEO_MISSING_IN)
[style] ~150-~150: This adverb was used twice in the sentence. Consider removing one of them or replacing them with a synonym.
Context: ...Limitations - Claude models only - Only supports Claude models (Opus, Sonnet, e...
(ADVERB_REPETITION_PREMIUM)
[uncategorized] ~152-~152: Possible missing preposition found.
Context: ...on't get latest pricing information - New models - May not support newly releas...
(AI_HYDRA_LEO_MISSING_OF)
docs/guide/cost-modes.md
[style] ~149-~149: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...# Scenario 3: Billing Verification You want to verify Claude's official cost calculati...
(REP_WANT_TO_VB)
[uncategorized] ~248-~248: Possible missing preposition found.
Context: ... - Combining old and new usage data - Maximum accuracy - Best available cost inform...
(AI_HYDRA_LEO_MISSING_TO)
docs/guide/custom-paths.md
[uncategorized] ~142-~142: Possible missing comma found.
Context: ...ucture Invalid paths are automatically skipped with debug information available. ## C...
(AI_HYDRA_LEO_MISSING_COMMA)
docs/guide/daily-reports.md
[uncategorized] ~189-~189: Although a hyphen is possible, it is not necessary in a compound modifier in which the first word is an adverb that ends in ‘ly’.
Context: ... ## Related Commands - Monthly Reports - Aggregate by month - [Session Report...
(HYPHENATED_LY_ADVERB_ADJECTIVE)
docs/guide/getting-started.md
[uncategorized] ~72-~72: Although a hyphen is possible, it is not necessary in a compound modifier in which the first word is an adverb that ends in ‘ly’.
Context: ...e these features: 1. Monthly Reports - See usage aggregated by month 2. *...
(HYPHENATED_LY_ADVERB_ADJECTIVE)
docs/guide/json-output.md
[uncategorized] ~148-~148: Loose punctuation mark.
Context: ...criptions ### Common Fields - models: Array of Claude model names used - `inp...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~160-~160: Loose punctuation mark.
Context: ...fic Fields #### Daily Reports - date: Date in YYYY-MM-DD format #### Monthly...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~164-~164: Loose punctuation mark.
Context: ... format #### Monthly Reports - month: Month in YYYY-MM format #### Session R...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~168-~168: Loose punctuation mark.
Context: ...ormat #### Session Reports - session: Session identifier - lastActivity: Da...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~173-~173: Loose punctuation mark.
Context: ...ion #### Blocks Reports - blockStart: ISO timestamp of block start - `blockEn...
(UNLIKELY_OPENING_PUNCTUATION)
docs/guide/live-monitoring.md
[typographical] ~67-~67: If specifying a range, consider using an en dash instead of a hyphen.
Context: ...ctive monitoring during heavy usage - 5-10 seconds: For casual monitoring or slo...
(HYPHEN_TO_EN)
docs/guide/mcp-server.md
[uncategorized] ~15-~15: Possible missing comma found.
Context: ... The stdio transport is ideal for local integration where the client directly spawns the pr...
(AI_HYDRA_LEO_MISSING_COMMA)
[uncategorized] ~212-~212: Loose punctuation mark.
Context: ...ables as the CLI: - CLAUDE_CONFIG_DIR: Specify custom Claude data directory pa...
(UNLIKELY_OPENING_PUNCTUATION)
docs/guide/session-reports.md
[uncategorized] ~260-~260: Although a hyphen is possible, it is not necessary in a compound modifier in which the first word is an adverb that ends in ‘ly’.
Context: ...ge aggregated by date - Monthly Reports - Monthly summaries - [Blocks Reports]...
(HYPHENATED_LY_ADVERB_ADJECTIVE)
docs/guide/sponsors.md
[uncategorized] ~13-~13: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...rt the development of ccusage and other open source projects. ## Star History <a href="ht...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
🪛 ESLint
docs/.vitepress/config.ts
[error] 7-7: Unsafe call of a(n) error type typed value.
(ts/no-unsafe-call)
[error] 7-7: Unsafe call of a(n) error type typed value.
(ts/no-unsafe-call)
[error] 127-127: Unsafe call of a(n) error type typed value.
(ts/no-unsafe-call)
[error] 128-128: Unsafe spread of an error typed value in an array.
(ts/no-unsafe-assignment)
[error] 128-128: Unsafe call of a(n) error type typed value.
(ts/no-unsafe-call)
[error] 134-134: Unsafe call of a(n) any typed value.
(ts/no-unsafe-call)
[error] 134-134: Unsafe member access .use on an any value.
(ts/no-unsafe-member-access)
docs/index.ts
[error] 3-3: Unsafe return of a value of type error.
(ts/no-unsafe-return)
[error] 3-3: Unsafe construction of a(n) error type typed value.
(ts/no-unsafe-call)
🪛 markdownlint-cli2 (0.17.2)
docs/guide/configuration.md
192-192: Hard tabs
Column: 1
(MD010, no-hard-tabs)
193-193: Hard tabs
Column: 1
(MD010, no-hard-tabs)
194-194: Hard tabs
Column: 1
(MD010, no-hard-tabs)
195-195: Hard tabs
Column: 1
(MD010, no-hard-tabs)
196-196: Hard tabs
Column: 1
(MD010, no-hard-tabs)
197-197: Hard tabs
Column: 1
(MD010, no-hard-tabs)
198-198: Hard tabs
Column: 1
(MD010, no-hard-tabs)
199-199: Hard tabs
Column: 1
(MD010, no-hard-tabs)
200-200: Hard tabs
Column: 1
(MD010, no-hard-tabs)
208-208: Hard tabs
Column: 1
(MD010, no-hard-tabs)
209-209: Hard tabs
Column: 1
(MD010, no-hard-tabs)
210-210: Hard tabs
Column: 1
(MD010, no-hard-tabs)
211-211: Hard tabs
Column: 1
(MD010, no-hard-tabs)
212-212: Hard tabs
Column: 1
(MD010, no-hard-tabs)
213-213: Hard tabs
Column: 1
(MD010, no-hard-tabs)
214-214: Hard tabs
Column: 1
(MD010, no-hard-tabs)
docs/guide/library-usage.md
60-60: Hard tabs
Column: 1
(MD010, no-hard-tabs)
61-61: Hard tabs
Column: 1
(MD010, no-hard-tabs)
74-74: Hard tabs
Column: 1
(MD010, no-hard-tabs)
106-106: Hard tabs
Column: 1
(MD010, no-hard-tabs)
107-107: Hard tabs
Column: 1
(MD010, no-hard-tabs)
117-117: Hard tabs
Column: 1
(MD010, no-hard-tabs)
119-119: Hard tabs
Column: 1
(MD010, no-hard-tabs)
120-120: Hard tabs
Column: 1
(MD010, no-hard-tabs)
121-121: Hard tabs
Column: 1
(MD010, no-hard-tabs)
122-122: Hard tabs
Column: 1
(MD010, no-hard-tabs)
123-123: Hard tabs
Column: 1
(MD010, no-hard-tabs)
125-125: Hard tabs
Column: 1
(MD010, no-hard-tabs)
135-135: Hard tabs
Column: 1
(MD010, no-hard-tabs)
136-136: Hard tabs
Column: 1
(MD010, no-hard-tabs)
138-138: Hard tabs
Column: 1
(MD010, no-hard-tabs)
139-139: Hard tabs
Column: 1
(MD010, no-hard-tabs)
140-140: Hard tabs
Column: 1
(MD010, no-hard-tabs)
docs/guide/live-monitoring.md
229-229: Fenced code blocks should have a language specified
null
(MD040, fenced-code-language)
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: Workers Builds: ccusage-guide
🔇 Additional comments (16)
src/_macro.ts (1)
5-7: Excellent refactoring of import statements.The separation of type-only imports (
ModelPricing) from runtime imports (modelPricingSchema) follows TypeScript best practices and improves code clarity. This change correctly distinguishes between compile-time types and runtime values, which can also help with bundle optimization.docs/index.ts (1)
1-5: LGTM! Simple fetch handler implementation.This is a clean, minimal fetch handler that returns a Response with the project name. The ESLint warnings about unsafe types appear to be false positives - the Response constructor is a standard Web API.
docs/guide/getting-started.md (1)
1-128: Great introductory guide
The “Getting Started” document is well-structured with clear prerequisites and examples for multiple runtimes. No issues found.docs/guide/json-output.md (1)
1-302: Comprehensive JSON output documentation
Clear structure, correct code/JSON examples, and accurate sectioning for enabling and consuming JSON output.docs/update-api-index.mjs (1)
1-84: LGTM! Well-structured post-processing script.The script is well-designed with:
- Proper async/await usage and error handling
- Clear separation of concerns between API index and constants page updates
- Appropriate use of process.exit(1) for critical failures while allowing non-critical failures to continue
- Good logging with emoji indicators for user feedback
The implementation correctly handles the special case for
_constsmodule linking and includes safeguards against duplicate content insertion.docs/guide/custom-paths.md (1)
1-431: Excellent comprehensive documentation for custom paths configuration.This guide provides thorough coverage of:
- Multiple path configuration scenarios
- Shell integration examples
- MCP server integration
- Comprehensive troubleshooting section
- Performance considerations for different use cases
The examples are practical and cover real-world scenarios like team environments, development vs production, and historical analysis.
docs/guide/index.md (1)
1-104: Outstanding introduction guide with clear value proposition.This guide effectively:
- Clearly explains the problem ccusage solves
- Provides a comprehensive feature overview
- Includes helpful visual workflow diagram
- Addresses privacy and security concerns upfront
- Sets appropriate expectations with limitations section
- Provides clear next steps for users
The structure and content make it easy for new users to understand the tool's purpose and benefits.
docs/guide/session-reports.md (2)
1-4: Documentation Clarity and Structure
Header and introduction clearly state the purpose of session reports. The structure follows other guides in this directory and will integrate smoothly into the sidebar navigation.
52-67: Command Options Grouping
The sections for date filtering and sort order are concise and well-organized. Linking example flags directly to their descriptions makes this easy to follow.docs/guide/blocks-reports.md (2)
1-4: Guide Introduction
The overview of 5-hour billing windows is clear and parallels the session reports guide. Good alignment with the billing concept.
38-57: Block Status Indicators
The list of status symbols and their meanings is exhaustive and consistent with the CLI output.docs/guide/configuration.md (3)
9-17: Environment Variable Examples
The single and multiple directory snippets clearly demonstrate how to setCLAUDE_CONFIG_DIRfor both scenarios.
33-41: Default Directory Detection
The priority list and info box succinctly explain the migration from legacy to new paths, covering backward compatibility nicely.
81-88: Debug Options
Including both pricing mismatch and sample discrepancy flags gives users the tools they need for deeper troubleshooting.docs/guide/live-monitoring.md (1)
19-26: Feature Highlights
The real-time updates list is concise, captures all key metrics, and aligns perfectly with the CLI feature set.docs/guide/mcp-server.md (1)
209-216: Environment Variable Documentation
The explanation ofCLAUDE_CONFIG_DIRhere is consistent with the configuration guide and reinforces uniform behavior across CLI tools.
There was a problem hiding this comment.
🛠️ Refactor suggestion
Add VitePress frontmatter for proper page metadata.
To ensure the page renders with the correct title, sidebar order, and other VitePress settings, include a YAML frontmatter block at the top, for example:
---
title: "Cost Modes"
description: "Overview of the auto, calculate, and display cost calculation modes in ccusage."
sidebarPosition: 3
---🤖 Prompt for AI Agents
In docs/guide/cost-modes.md at the beginning of the file (lines 1 to 4), add a
YAML frontmatter block to define the page metadata for VitePress. Include fields
such as title, description, and sidebarPosition to ensure proper rendering and
navigation order. Place the frontmatter block at the very top of the file before
any other content.
169b7cc to
215fcd0
Compare
There was a problem hiding this comment.
Pull Request Overview
Sets up a new VitePress-based documentation site with auto-generated API docs, moves README content into structured guides, and adds monorepo support for building and linting docs.
- Convert repository to a Bun workspace and add a
docspackage with VitePress - Introduce TypeDoc and plugin configurations for markdown API output
- Add JSDoc fileoverview comments to all source modules for proper API generation and update build/lint scripts
Reviewed Changes
Copilot reviewed 98 out of 107 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| typedoc.json | Configuration for TypeDoc entry points and output folder |
| docs/typedoc.config.mjs | Typedoc plugin setup for VitePress theme |
| package.json | Added docs workspace, build/deploy scripts |
| eslint.config.js | Ignore generated docs in linting |
| src/logger.ts | Add fileoverview JSDoc and reorganize consola imports |
| src/pricing-fetcher.ts | Add fileoverview JSDoc and split type/schema imports |
| src/_macro.ts | Add fileoverview JSDoc and split type/schema imports |
| docs/api/data-loader/index.md | Deprecation note for getDefaultClaudePath link |
Comments suppressed due to low confidence (1)
docs/api/data-loader/index.md:28
- [nitpick] The strikethrough in
~~getDefaultClaudePath~~may not render correctly in navigation—consider using plain text for the link and marking deprecation in the description.
| [~~getDefaultClaudePath~~](functions/getDefaultClaudePath.md) | Default path for Claude data directory Uses environment variable CLAUDE_CONFIG_DIR if set, otherwise defaults to ~/.claude |
There was a problem hiding this comment.
[nitpick] Consider combining the two imports from 'consola' into a single statement for clarity: import consola, { type ConsolaInstance } from 'consola';
| import type { ConsolaInstance } from 'consola'; | |
| import { consola } from 'consola'; | |
| import consola, { type ConsolaInstance } from 'consola'; |
There was a problem hiding this comment.
[nitpick] You could consolidate the imports from './_types.ts' into one statement: import modelPricingSchema, { type ModelPricing } from './_types.ts';
There was a problem hiding this comment.
[nitpick] Consider combining the two imports from './_types.ts' into a single line: import modelPricingSchema, { type ModelPricing } from './_types.ts';
There was a problem hiding this comment.
[nitpick] The 'docs/docs/**' ignore pattern may be a typo—consider using a single 'docs/**' pattern or adjust to the specific directories you intend to exclude.
Summary
This PR sets up a comprehensive VitePress documentation site for ccusage, moving away from a single large README to a well-structured, searchable documentation website.
🔧 Technical Changes
📚 Documentation Structure
Guide Section
API Reference
Enhanced Features
🚀 Benefits
🔗 Migration Notes
🧪 Testing
📦 Dependencies
This establishes a professional documentation foundation that can grow with the project and provides an excellent developer experience.
Summary by CodeRabbit
New Features
ccusagetool, including guides on installation, configuration, usage reports (daily, monthly, session, blocks), cost modes, JSON output, live monitoring, MCP server integration, and custom data paths.Documentation
.gitignoreand workspace configuration for documentation management.Chores