docs: improve TypeDoc configuration and build process #642
Conversation
|
Caution Review failedThe pull request is closed. WalkthroughDocs tooling migrated to Bun, TypeDoc typings tightened with a TypedocConfig alias and Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor Dev as Developer
participant Shell as Shell
participant Bun as Bun Runtime
participant TypeDoc as TypeDoc (bun -b typedoc)
participant FS as Filesystem
Dev->>Shell: npm run docs:api (invokes bun ./update-api-index.ts)
Shell->>Bun: spawn bun ./update-api-index.ts
Note right of Bun: script gated by import.meta.main
Bun->>TypeDoc: bun -b typedoc --excludeInternal --options ./typedoc.config.ts
TypeDoc-->>FS: write API markdown files
TypeDoc-->>Bun: exit status
rect rgba(230,245,255,0.5)
Note right of Bun: updateApiIndex()
Bun->>FS: Bun.file(api/index.md).text() (read)
Bun->>FS: Bun.write(api/index.md, updated) (write)
end
rect rgba(240,255,230,0.5)
Note right of Bun: updateConstsPage()
Bun->>FS: Bun.file(api/consts/index.md).text() (read)
Bun->>FS: Bun.write(api/consts/index.md, injectedDisclaimerIfMissing) (write)
end
alt updateApiIndex failure
Bun-->>Dev: log error and exit(1)
else updateConsts failure
Bun-->>Dev: log error (continue)
end
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (2)
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. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Summary of Changes
Hello @ryoppippi, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!
This pull request significantly upgrades the documentation generation pipeline by integrating TypeScript for TypeDoc configuration and leveraging Bun for build scripts. These changes aim to improve type safety, boost build performance, and streamline the developer experience, aligning the documentation process with modern development practices and the project's TypeScript-first approach.
Highlights
- TypeDoc Configuration Migration: The TypeDoc configuration file has been converted from JavaScript (
.mjs) to TypeScript (.ts), enhancing type safety and developer experience with proper type checking and IntelliSense. - Bun Integration for Documentation Builds: The documentation API build script (
docs:api) now utilizes Bun, replacing Node.js for potentially faster script execution and improved performance in the build process. - Dependency Updates: Required Bun and React type dependencies have been added to support the new TypeDoc configuration and Bun-based build process.
- PNPM Workspace Configuration: The PNPM workspace configuration has been updated to enable
catalogMode: strictandshellEmulator: true, improving workspace management and consistency.
Using Gemini Code Assist
The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.
Invoking Gemini
You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.
| Feature | Command | Description |
|---|---|---|
| Code Review | /gemini review |
Performs a code review for the current pull request in its current state. |
| Pull Request Summary | /gemini summary |
Provides a summary of the current pull request in its current state. |
| Comment | @gemini-code-assist | Responds in comments when explicitly tagged, both in pull request comments and review comments. |
| Help | /gemini help |
Displays a list of available commands. |
Customization
To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.
Limitations & Feedback
Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.
You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.
Footnotes
-
Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩
ryoppippi
changed the title
Deploying with
|
| Status | Name | Latest Commit | Updated (UTC) |
|---|---|---|---|
| ✅ Deployment successful! View logs |
ccusage-guide | f65c653 | Sep 18 2025, 05:01 PM |
commit: |
ryoppippi
force-pushed
the
ts-typedoc
branch
from
9ce01a7 to
1ff839d
Compare
There was a problem hiding this comment.
Code Review
This pull request is a great enhancement to the documentation build process. The migration from a JavaScript-based TypeDoc configuration to TypeScript (typedoc.config.ts) significantly improves type safety and maintainability. Integrating Bun for running the build scripts is a smart move for performance. The changes are well-structured and clearly follow the PR's objectives. I have one minor suggestion to improve error handling in the build script, but overall, this is a solid contribution.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (9)
docs/typedoc.config.ts (2)
2-3: Use double quotes per repo ESLint rule for TS files.Type-only imports look good; switch to double quotes to match guidelines.
Apply:
-import type { TypeDocOptions } from 'typedoc' -import type { PluginOptions } from 'typedoc-plugin-markdown' +import type { TypeDocOptions } from "typedoc"; +import type { PluginOptions } from "typedoc-plugin-markdown";
6-6: Optional: type the VitePress theme options instead of ad‑hocdocsRoot.If
typedoc-vitepress-themeexposes its option types, prefer intersecting those here instead of{ docsRoot?: string }to retain type safety on future options.docs/package.json (1)
36-41: Bun devEngine: good. Ensure the CI tooling honorsdevEnginesor install Bun explicitly.Some CI providers ignore custom fields; make sure your workflow installs Bun if
devEnginesisn’t enforced.docs/update-api-index.ts (5)
24-24: Prefer@praha/byethrowover raw try/catch; also avoidconsoleper docs script rules.Wrap IO with
Result.try()and use the project logger (or add an eslint-disable if logger wiring isn’t available yet).Apply:
- let content = await Bun.file(apiIndexPath).text(); + const readIndex = await Result.try(() => Bun.file(apiIndexPath).text()); + if (Result.isFailure(readIndex)) { + logger.error({ err: readIndex.error, apiIndexPath }, "Failed to read API index"); + process.exit(1); + } + let content = readIndex.value; - await Bun.write(apiIndexPath, content); - console.log('✅ Updated API index with module descriptions'); + const writeIndex = await Result.try(() => Bun.write(apiIndexPath, content)); + if (Result.isFailure(writeIndex)) { + logger.error({ err: writeIndex.error, apiIndexPath }, "Failed to write API index"); + process.exit(1); + } + logger.success("✅ Updated API index with module descriptions");Add imports (top of file):
import { Result } from "@praha/byethrow"; // Replace with your shared logger import { logger } from "../logger.ts"; // adjust pathIf logger isn’t available yet, minimally annotate:
- console.log('✅ Updated API index with module descriptions'); + // eslint-disable-next-line no-console + console.log("✅ Updated API index with module descriptions");Also applies to: 38-40
51-51: Apply the same Result/logger pattern to the consts page updater and dropconsole.*.Keep behavior (don’t exit on failure), but avoid
consoleuse.Apply:
- let content = await Bun.file(constsIndexPath).text(); + const readConsts = await Result.try(() => Bun.file(constsIndexPath).text()); + if (Result.isFailure(readConsts)) { + logger.warn({ err: readConsts.error, constsIndexPath }, "Consts page missing or unreadable"); + return; + } + let content = readConsts.value; - await Bun.write(constsIndexPath, content); - console.log('✅ Updated constants page with disclaimer'); + const writeConsts = await Result.try(() => Bun.write(constsIndexPath, content)); + if (Result.isFailure(writeConsts)) { + logger.warn({ err: writeConsts.error, constsIndexPath }, "Failed to update consts page"); + return; + } + logger.success("✅ Updated constants page with disclaimer"); - console.error('❌ Failed to update constants page:', error); + logger.warn({ err: error, constsIndexPath }, "❌ Failed to update constants page");Also applies to: 65-67, 69-71
34-36: Escape dynamic strings in the RegExp to avoid mismatches (e.g.,\_consts).Currently
${module}can contain backslashes and other meta characters. Escape both module and linkPath before building the pattern.Use:
const escapeRegExp = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); const oldPattern = new RegExp( `\\|\\s*\\[${escapeRegExp(module)}\\]\\(${escapeRegExp(linkPath)}\\)\\s*\\|\\s*-\\s*\\|`, "g", );
7-8: Style: use double quotes in TS files.Switch single quotes to double quotes per repo rule.
74-76: Typedoc invocation: OK; consider logging the command output or duration.Optional: wrap with a small timer and log via
loggerfor traceability.pnpm-workspace.yaml (1)
72-75: Enabling pre/post scripts and keepingminimumReleaseAge: OK.Ensure CI explicitly sets
PNPM_ENABLE_PREPOST_SCRIPTS=trueif needed.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
pnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (4)
docs/package.json(2 hunks)docs/typedoc.config.ts(2 hunks)docs/update-api-index.ts(6 hunks)pnpm-workspace.yaml(2 hunks)
🧰 Additional context used
📓 Path-based instructions (3)
docs/**/*.{ts,js,mjs,cjs}
📄 CodeRabbit inference engine (docs/CLAUDE.md)
Do not use console.log in documentation scripts; use appropriate logging instead
Files:
docs/typedoc.config.tsdocs/update-api-index.ts
**/*.{ts,tsx}
📄 CodeRabbit inference engine (CLAUDE.md)
**/*.{ts,tsx}: Use ESLint formatting with tab indentation and double quotes
Do not use console.log; use logger.ts instead (only allow via explicit eslint-disable if unavoidable)
Always use Node.js path utilities (path, fs, URL) for file paths for cross-platform compatibility
Use .ts extensions for local file imports (e.g., import { foo } from "./utils.ts")
Prefer @praha/byethrow Result type over traditional try/catch for error handling
Wrap throwable operations with Result.try() and check with Result.isFailure()/Result.isSuccess()
Favor early returns for failures (e.g., if (Result.isFailure(r)) return/continue) over ternaries
Keep traditional try/catch only for complex file I/O or legacy code that’s hard to refactor
Use in-source testing via if (import.meta.vitest != null) blocks; tests live in the same files as source
Vitest globals are enabled—use describe, it, expect without imports
Never use await import() dynamic imports anywhere; especially never in Vitest test blocks
All tests must use current Claude 4 model names (Sonnet and Opus) matching LiteLLM’s pricing database
Model naming must follow claude-{model-type}-{generation}-{date} (e.g., claude-sonnet-4-20250514)
Verify new model names exist in LiteLLM before adding tests; failures often indicate missing pricing entries
Files:
docs/typedoc.config.tsdocs/update-api-index.ts
**/package.json
📄 CodeRabbit inference engine (CLAUDE.md)
Add dependencies as devDependencies unless explicitly required otherwise
Files:
docs/package.json
🧠 Learnings (2)
📚 Learning: 2025-09-17T18:28:29.654Z
Learnt from: CR
PR: ryoppippi/ccusage#0
File: CLAUDE.md:0-0
Timestamp: 2025-09-17T18:28:29.654Z
Learning: Use pnpm scripts: test (vitest, no watch), format (ESLint fix), typecheck (TS), build (tsdown), release (full workflow)
Applied to files:
docs/package.jsonpnpm-workspace.yaml
📚 Learning: 2025-09-17T18:29:15.753Z
Learnt from: CR
PR: ryoppippi/ccusage#0
File: apps/mcp/CLAUDE.md:0-0
Timestamp: 2025-09-17T18:29:15.753Z
Learning: After code changes, always run `pnpm run format`, `pnpm typecheck`, and `pnpm run test` in parallel
Applied to files:
docs/update-api-index.ts
🪛 GitHub Actions: CI
docs/update-api-index.ts
[error] 24-24: TS2868: Cannot find name 'Bun'. Do you need to install type definitions for Bun? Try npm i --save-dev @types/bun and then add 'bun' to the types field in your tsconfig.
[error] 38-38: TS2868: Cannot find name 'Bun'. Do you need to install type definitions for Bun? Try npm i --save-dev @types/bun and then add 'bun' to the types field in your tsconfig.
[error] 51-51: TS2868: Cannot find name 'Bun'. Do you need to install type definitions for Bun? Try npm i --save-dev @types/bun and then add 'bun' to the types field in your tsconfig.
[error] 65-65: TS2868: Cannot find name 'Bun'. Do you need to install type definitions for Bun? Try npm i --save-dev @types/bun and then add 'bun' to the types field in your tsconfig.
[error] 75-75: TS2868: Cannot find name 'Bun'. Do you need to install type definitions for Bun? Try npm i --save-dev @types/bun and then add 'bun' to the types field in your tsconfig.
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Workers Builds: ccusage-guide
🔇 Additional comments (5)
docs/typedoc.config.ts (1)
50-50: Nice use ofsatisfiesfor config shape validation.This ensures drift is caught at compile time. LGTM.
docs/update-api-index.ts (2)
1-1: Shebang for Bun looks good.No action needed.
24-24: Fix CI TS errors: add Bun types.Once
bunis added totypesin tsconfig, these should pass. See package.json comment for verification script.Also applies to: 38-38, 51-51, 65-65, 75-75
pnpm-workspace.yaml (2)
6-6: catalogMode: strict — good for supply-chain hygiene.No action.
69-69: Keep@types/react— required by docsFound evidence: pnpm-workspace.yaml has
'@types/react': ^19.1.13(line 69); docs/package.json lists"@types/react"and pnpm-lock shows vitepress / @docsearch/react depend on it. Leave as-is unless the docs package drops all React/MDX usage.
| "deploy": "wrangler deploy", | ||
| "dev": "pnpm run docs:api && cp ../apps/ccusage/config-schema.json public/config-schema.json && vitepress dev", | ||
| "docs:api": "./update-api-index.ts", | ||
| "docs:api": "bun ./update-api-index.ts", |
There was a problem hiding this comment.
🧩 Analysis chain
Switching docs:api to Bun is fine; ensure CI has Bun installed.
CI error shows missing Bun types in TS, not the runtime; still, confirm CI runner has Bun v1.2.x available for this script.
Run:
🏁 Script executed:
#!/bin/bash
set -euo pipefail
bun --version || echo "Bun not installed on CI PATH"Length of output: 70
CI missing Bun — install Bun v1.2.x or revert docs:api
Running bun --version on the CI PATH returned "command not found". docs/package.json (line 11) uses Bun: "docs:api": "bun ./update-api-index.ts". Add a CI step to install Bun v1.2.x before running this script, or change the script back to a Node-based invocation.
🤖 Prompt for AI Agents
In docs/package.json around line 11, the npm script "docs:api": "bun
./update-api-index.ts" requires Bun but CI PATH lacks it; either add a CI step
to install and export Bun v1.2.x (pin to v1.2.x) before running this script in
your workflow (e.g., install Bun, add it to PATH) or change the script back to a
Node-based invocation so it works without Bun; update the relevant CI workflow
file to perform the install (or update the package.json script to use node)
accordingly.
|
|
||
| async function updateApiIndex() { | ||
| const apiIndexPath = join(process.cwd(), 'api', 'index.md'); | ||
| const apiIndexPath = join(import.meta.dirname, 'api', 'index.md'); |
There was a problem hiding this comment.
Bug: import.meta.dirname is non‑standard. Use Bun’s import.meta.dir with Node fallback.
This can throw at runtime when join() receives undefined. Fix both path resolutions.
Apply:
-const apiIndexPath = join(import.meta.dirname, 'api', 'index.md');
+const apiIndexPath = join(
+ typeof import.meta.dir === "string"
+ ? import.meta.dir
+ : fileURLToPath(new URL(".", import.meta.url)),
+ "api",
+ "index.md",
+);
-const constsIndexPath = join(import.meta.dirname, 'api', 'consts', 'index.md');
+const constsIndexPath = join(
+ typeof import.meta.dir === "string"
+ ? import.meta.dir
+ : fileURLToPath(new URL(".", import.meta.url)),
+ "api",
+ "consts",
+ "index.md",
+);Add import (top of file):
import { fileURLToPath } from "node:url";Also applies to: 48-48
🤖 Prompt for AI Agents
In docs/update-api-index.ts around lines 21 and 48, replace use of the
non‑standard import.meta.dirname with a Bun-aware fallback: add the import
"fileURLToPath" from "node:url" at the top of the file, then resolve a directory
variable that uses import.meta.dir if present (Bun) otherwise uses
fileURLToPath(import.meta.url) to derive the directory; finally use that
resolved directory variable when calling join(...) for both path resolutions so
join never receives undefined.
Summary
Enhance TypeDoc configuration and documentation build process with TypeScript support and Bun integration.
What Changed
typedoc.config.mjstotypedoc.config.tswith proper TypeScript typesWhy
Testing
Summary by CodeRabbit
Documentation
Chores