chore: add script for generate typedoc declaration json file #2507
Conversation
WalkthroughThe pull request introduces changes to the project's documentation and build process. A new entry was added to the Changes
Poem
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #2507 +/- ##
=======================================
Coverage 68.53% 68.53%
=======================================
Files 957 957
Lines 100057 100041 -16
Branches 8552 8552
=======================================
- Hits 68575 68568 -7
+ Misses 31226 31217 -9
Partials 256 256
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. |
![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 (1)
scripts/typedoc.sh (1)
16-20: Enhance summary output with better formatting and error handling.The summary section needs improvements for better output handling:
Apply these changes:
echo "============" -for f in ${SUCCESS[@]}; do - echo "[typedoc] $f"; +if [ ${#SUCCESS[@]} -eq 0 ]; then + echo "Warning: No TypeDoc files were generated" >&2 + exit 1 +fi + +for f in "${SUCCESS[@]}"; do + echo "[typedoc] Generated: $f" done echo "============" +echo "Successfully generated ${#SUCCESS[@]} TypeDoc files"🧰 Tools
🪛 Shellcheck (0.10.0)
[error] 17-17: Double quote array expansions to avoid re-splitting elements.
(SC2068)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
.gitignore(1 hunks)scripts/typedoc.sh(1 hunks)
✅ Files skipped from review due to trivial changes (1)
- .gitignore
🧰 Additional context used
🪛 Shellcheck (0.10.0)
scripts/typedoc.sh
[error] 1-1: Tips depend on target shell and yours is unknown. Add a shebang or a 'shell' directive.
(SC2148)
[error] 17-17: Double quote array expansions to avoid re-splitting elements.
(SC2068)
⏰ Context from checks skipped due to timeout of 90000ms (3)
- GitHub Check: build (22.x, windows-latest)
- GitHub Check: e2e (22.x)
- GitHub Check: codecov
| for directory in ${ENGINE_PATH}/packages/* | ||
| do | ||
| if [ -d $directory ]; then | ||
| bn=`basename $directory`; | ||
| echo "typedoc compiling $directory" | ||
| npx $TYPEDOC --version | ||
| npx $TYPEDOC --json api/$bn.json --tsconfig $directory/tsconfig.json $directory/src/index.ts; | ||
| SUCCESS+=("api/$bn.json") | ||
| fi | ||
| done |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Improve robustness of package processing.
The main loop needs several improvements for better error handling and robustness:
Apply these changes:
+# Initialize array and create output directory
+declare -a SUCCESS=()
+mkdir -p api
+
-for directory in ${ENGINE_PATH}/packages/*
+for directory in "${ENGINE_PATH}/packages/"*
do
- if [ -d $directory ]; then
- bn=`basename $directory`;
+ if [ -d "$directory" ]; then
+ bn="$(basename "$directory")"
echo "typedoc compiling $directory"
- npx $TYPEDOC --version
- npx $TYPEDOC --json api/$bn.json --tsconfig $directory/tsconfig.json $directory/src/index.ts;
- SUCCESS+=("api/$bn.json")
+ if ! npx "$TYPEDOC" --json "api/${bn}.json" \
+ --tsconfig "${directory}/tsconfig.json" \
+ "${directory}/src/index.ts"; then
+ echo "Error: TypeDoc generation failed for ${bn}" >&2
+ continue
+ fi
+ SUCCESS+=("api/${bn}.json")
fi
done📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| for directory in ${ENGINE_PATH}/packages/* | |
| do | |
| if [ -d $directory ]; then | |
| bn=`basename $directory`; | |
| echo "typedoc compiling $directory" | |
| npx $TYPEDOC --version | |
| npx $TYPEDOC --json api/$bn.json --tsconfig $directory/tsconfig.json $directory/src/index.ts; | |
| SUCCESS+=("api/$bn.json") | |
| fi | |
| done | |
| # Initialize array and create output directory | |
| declare -a SUCCESS=() | |
| mkdir -p api | |
| for directory in "${ENGINE_PATH}/packages/"* | |
| do | |
| if [ -d "$directory" ]; then | |
| bn="$(basename "$directory")" | |
| echo "typedoc compiling $directory" | |
| if ! npx "$TYPEDOC" --json "api/${bn}.json" \ | |
| --tsconfig "${directory}/tsconfig.json" \ | |
| "${directory}/src/index.ts"; then | |
| echo "Error: TypeDoc generation failed for ${bn}" >&2 | |
| continue | |
| fi | |
| SUCCESS+=("api/${bn}.json") | |
| fi | |
| done |
| # generate declaration files via typedoc | ||
|
|
||
| ENGINE_PATH=$(pwd) | ||
|
|
There was a problem hiding this comment.
Add proper script setup and error handling.
The script setup needs several improvements for robustness:
Apply these changes:
+#!/bin/bash
+set -euo pipefail
+
# generate declaration files via typedoc
-ENGINE_PATH=$(pwd)
+ENGINE_PATH="$(pwd)"
+
+# Validate required environment variable
+if [ -z "${TYPEDOC:-}" ]; then
+ echo "Error: TYPEDOC environment variable is not set" >&2
+ exit 1
+fi📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| # generate declaration files via typedoc | |
| ENGINE_PATH=$(pwd) | |
| #!/bin/bash | |
| set -euo pipefail | |
| # generate declaration files via typedoc | |
| ENGINE_PATH="$(pwd)" | |
| # Validate required environment variable | |
| if [ -z "${TYPEDOC:-}" ]; then | |
| echo "Error: TYPEDOC environment variable is not set" >&2 | |
| exit 1 | |
| fi |
🧰 Tools
🪛 Shellcheck (0.10.0)
[error] 1-1: Tips depend on target shell and yours is unknown. Add a shebang or a 'shell' directive.
(SC2148)
| # generate declaration files via typedoc | ||
|
|
||
| ENGINE_PATH=$(pwd) | ||
|
|
||
| for directory in ${ENGINE_PATH}/packages/* | ||
| do | ||
| if [ -d $directory ]; then | ||
| bn=`basename $directory`; | ||
| echo "typedoc compiling $directory" | ||
| npx $TYPEDOC --version | ||
| npx $TYPEDOC --json api/$bn.json --tsconfig $directory/tsconfig.json $directory/src/index.ts; | ||
| SUCCESS+=("api/$bn.json") | ||
| fi | ||
| done | ||
|
|
||
| echo "============" | ||
| for f in ${SUCCESS[@]}; do | ||
| echo "[typedoc] $f"; | ||
| done | ||
| echo "============" |
There was a problem hiding this comment.
💡 Codebase verification
TypeDoc dependency and configuration are missing
The script assumes TypeDoc is available but:
- TypeDoc is not installed as a dependency in any package
- The
$TYPEDOCvariable is undefined - No TypeDoc configuration file exists
This will cause documentation generation to fail. Please:
- Add TypeDoc as a devDependency
- Define the
$TYPEDOCvariable or use direct npx calls - Add TypeDoc configuration
🔗 Analysis chain
Verify TypeDoc setup and configuration.
Please ensure that TypeDoc is properly configured in the project:
Run this script to verify the setup:
🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash
# Check TypeDoc configuration and dependencies
# Check if TypeDoc is in package.json
echo "Checking TypeDoc dependencies..."
jq '.dependencies["typedoc"] // .devDependencies["typedoc"]' package.json
# Check for TypeDoc configuration file
echo -e "\nChecking for TypeDoc configuration..."
if [ -f "typedoc.json" ]; then
cat typedoc.json
else
echo "Warning: No typedoc.json found"
fi
# Check packages structure
echo -e "\nVerifying packages structure..."
fd -t d . packages/ -d 1
Length of output: 692
Script:
#!/bin/bash
# Check workspace and package dependencies
echo "Checking root package.json workspace setup..."
jq '.workspaces' package.json
echo -e "\nChecking for TypeDoc in package package.json files..."
fd package.json packages/ -x jq -c '{name: .name, typedoc: (.dependencies.typedoc // .devDependencies.typedoc)}' {}
echo -e "\nSearching for TYPEDOC variable definition..."
rg "TYPEDOC=" -g '!node_modules'
Length of output: 1207
🧰 Tools
🪛 Shellcheck (0.10.0)
[error] 1-1: Tips depend on target shell and yours is unknown. Add a shebang or a 'shell' directive.
(SC2148)
[error] 17-17: Double quote array expansions to avoid re-splitting elements.
(SC2068)
Please check if the PR fulfills these requirements
What kind of change does this PR introduce? (Bug fix, feature, docs update, ...)
What is the current behavior? (You can also link to an open issue here)
What is the new behavior (if this is a feature change)?
Does this PR introduce a breaking change? (What changes might users need to make in their application due to this PR?)
Other information:
Summary by CodeRabbit
.gitignoreto excludedocs/apidirectorytypedoc.shscript to automate TypeScript documentation generation