Skip to content

Commit c5ed0a6

Browse files
Ed-MarcavageEd-Marcavage
committed
Adds Agentic JSDoc generation
1 parent ea8cfb3 commit c5ed0a6

18 files changed

+3420
-0
lines changed

‎.github/workflows/jsdoc-automation.yml

+81
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
name: JSDoc Automation
2+
3+
on:
4+
workflow_dispatch:
5+
inputs:
6+
pull_number:
7+
description: 'Pull Request Number (if not provided, scans root_directory) - PR must be merged to develop branch'
8+
required: false
9+
type: string
10+
root_directory:
11+
description: 'Only scans files in this directory (relative to repository root, e.g., packages/core/src)'
12+
required: true
13+
default: 'packages/core/src/test_resources'
14+
type: string
15+
excluded_directories:
16+
description: 'Directories to exclude from scanning (comma-separated, relative to root_directory)'
17+
required: true
18+
default: 'node_modules,dist,test'
19+
type: string
20+
reviewers:
21+
description: 'Pull Request Reviewers (comma-separated GitHub usernames)'
22+
required: true
23+
default: ''
24+
type: string
25+
26+
jobs:
27+
generate-docs:
28+
runs-on: ubuntu-latest
29+
30+
env:
31+
GITHUB_ACCESS_TOKEN: ${{ secrets.GH_PAT }}
32+
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
33+
34+
steps:
35+
- name: Checkout repository
36+
uses: actions/checkout@v4
37+
with:
38+
fetch-depth: 0
39+
40+
- name: Setup Node.js
41+
uses: actions/setup-node@v4
42+
with:
43+
node-version: '23'
44+
45+
- name: Install pnpm
46+
uses: pnpm/action-setup@v2
47+
with:
48+
version: 8
49+
run_install: false
50+
51+
- name: Update lockfile
52+
working-directory: packages/jsdoc-automation
53+
run: |
54+
echo "Updating lockfile..."
55+
pnpm install --no-frozen-lockfile
56+
git config --global user.email "github-actions[bot]@users.noreply.github.com"
57+
git config --global user.name "github-actions[bot]"
58+
git add pnpm-lock.yaml
59+
git commit -m "chore: update pnpm lockfile" || echo "No changes to commit"
60+
git push || echo "No changes to push"
61+
62+
- name: Install root dependencies
63+
run: pnpm install --no-frozen-lockfile
64+
65+
- name: Install package dependencies
66+
working-directory: packages/jsdoc-automation
67+
run: pnpm install --no-frozen-lockfile
68+
69+
- name: Run documentation generator
70+
working-directory: packages/jsdoc-automation
71+
run: |
72+
echo "Node version: $(node --version)"
73+
echo "NPM version: $(npm --version)"
74+
echo "Directory contents:"
75+
ls -la
76+
NODE_OPTIONS='--experimental-vm-modules --no-warnings' pnpm start
77+
env:
78+
INPUT_ROOT_DIRECTORY: ${{ inputs.root_directory }}
79+
INPUT_PULL_NUMBER: ${{ inputs.pull_number }}
80+
INPUT_EXCLUDED_DIRECTORIES: ${{ inputs.excluded_directories }}
81+
INPUT_REVIEWERS: ${{ inputs.reviewers }}

‎packages/jsdoc-automation/.gitignore

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Dependencies
2+
node_modules
3+
.pnpm-store
4+
5+
# Build outputs
6+
dist
7+
build
8+
9+
# Environment variables
10+
.env
11+
.env.local
12+
.env.*.local
13+
14+
# Logs
15+
*.log
16+
npm-debug.log*
17+
pnpm-debug.log*
18+
19+
# Editor directories
20+
.idea
21+
.vscode
22+
*.suo
23+
*.ntvs*
24+
*.njsproj
25+
*.sln

‎packages/jsdoc-automation/README.md

+92
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# Codebase Documentation
2+
- https://github.com/ai16z/eliza/issues/1110
3+
4+
## Set up
5+
- Set GH_PAT & OPENAI_API_KEY in github actions as env variables
6+
7+
## Summary
8+
- To only scan files in a PR, ensure the files have been merged into the base branch (defaults to develop), and provide the PR number in the github Action input
9+
- `root_directory` is still enforced when scanning a PR
10+
- To scan a provided directory set `root_directory` and leave the PR number empty
11+
12+
## GitHub Workflow Automation
13+
14+
The codebase includes a GitHub Actions workflow (`JSDoc Automation`) that allows triggering the documentation generation process with custom parameters. The workflow is defined in the `.github/workflows` directory.
15+
16+
# Workflow Dispatch Inputs
17+
18+
The workflow can be triggered manually using the `workflow_dispatch` event, which accepts the following inputs:
19+
20+
- `pull_number` (optional): The pull request number to generate documentation for.
21+
- if not provided, the `root_directory` will be scanned
22+
- PR must be merged to develop/main branch
23+
24+
- `root_directory` (required): Only scans files in this directory.
25+
- Description: Target directory relative to repository root (e.g., packages/core/src)
26+
- Default: `packages/core/src/test_resources` - arbitrarily chose this because its small
27+
28+
- `excluded_directories` (required): Directories to exclude from scanning.
29+
- Description: Comma-separated list of directories to exclude, relative to root_directory
30+
- Default: 'node_modules,dist,test'
31+
32+
- `reviewers` (required): Pull Request Reviewers.
33+
- Description: Comma-separated list of GitHub usernames
34+
- Default: ''
35+
36+
### Config File
37+
The `src/Configuration.ts` handles configuration loading from environment variables with fallback to YAML workflow files.
38+
39+
#### Default Values
40+
41+
- **Repository**: ai16z/eliza
42+
- **Branch**: develop
43+
- **Commit Message**: "Generated JSDoc comments"
44+
- **PR Title**: "JSDoc Generation"
45+
- **PR Description**: "Automated JSDoc generation for the codebase"
46+
- **PR Labels**: ["documentation", "automated-pr"]
47+
- **Excluded Directories**: ["node_modules", "dist", "test"]
48+
- **Excluded Files**: ["index.d.ts"]
49+
50+
51+
### Environment Variables
52+
53+
The following environment variables need to be added to the GitHub repository secrets:
54+
55+
- `GH_PAT`: Personal Access Token with sufficient permissions to create branches, commit changes, and create pull requests in the repository.
56+
- `OPENAI_API_KEY`: API key for accessing the OpenAI chat API used by the `AIService` to generate comments.
57+
58+
# Codebase Documentation
59+
60+
## `JsDocGenerator` Class
61+
The `JsDocGenerator` class is responsible for generating JSDoc comments for code snippets and classes. It uses the `AIService` to generate comments based on the code provided.
62+
63+
## `TypeScriptFileIdentifier` Class
64+
The `TypeScriptFileIdentifier` class handles identifying and retrieving TypeScript files from a specified directory. It checks file extensions to determine if a file is a TypeScript file.
65+
66+
## `TypeScriptParser` Class
67+
The `TypeScriptParser` class parses TypeScript files using the `@typescript-eslint/parser`. It generates an abstract syntax tree (AST) representation of the parsed content.
68+
69+
## `DocumentationGenerator` Class
70+
The `DocumentationGenerator` class orchestrates the generation of JSDoc documentation for a codebase. It traverses the directory, identifies TypeScript files, parses them, analyzes existing JSDoc comments, generates missing comments using the `JsDocGenerator`, and updates the files with the generated documentation. It also handles creating git branches, committing changes, and creating pull requests.
71+
72+
## `JsDocAnalyzer` Class
73+
The `JsDocAnalyzer` class analyzes JSDoc comments in TypeScript code. It traverses the AST and identifies nodes that should have JSDoc comments. It also provides methods to check if a node is a class node and retrieve JSDoc comments associated with a node.
74+
75+
## `AIService` Class
76+
The `AIService` class is a service for interacting with the OpenAI chat API. It uses the `ChatOpenAI` class from the `@langchain/openai` package to generate comments based on provided prompts.
77+
78+
## `DirectoryTraversal` Class
79+
The `DirectoryTraversal` class handles traversing directories and files. It can traverse based on provided PR files or scan all files in a root directory. It filters files based on excluded directories and file extensions.
80+
81+
## `GitManager` Class
82+
The `GitManager` class manages operations related to interacting with a Git repository using the GitHub API. It can retrieve files in a pull request, create branches, commit files, and create pull requests.
83+
84+
## `Configuration` Class
85+
The `Configuration` class represents a configuration object that holds various settings for a project. It can load configuration data from a JSON file and save the current configuration data to a file.
86+
87+
## `Main` Function
88+
The `main` function is the entry point of the documentation generation process. It creates instances of necessary classes, loads the configuration, retrieves files from a pull request if specified, traverses the directory, parses TypeScript files, analyzes JSDoc comments, and generates documentation using the `DocumentationGenerator`. It also handles error logging.
89+
90+
## Prompt Template Locations:
91+
- DocumentationGenerator
92+
- JsDocGenerator

‎packages/jsdoc-automation/package.json

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
{
2+
"type": "module",
3+
"name": "plugin-audix",
4+
"version": "1.0.0",
5+
"description": "",
6+
"main": "index.ts",
7+
"scripts": {
8+
"start": "NODE_OPTIONS='--loader ts-node/esm' node src/index.ts",
9+
"test": "echo \"Error: no test specified\" && exit 1",
10+
"clean": "rm -rf node_modules dist"
11+
},
12+
"keywords": [],
13+
"author": "",
14+
"license": "MIT",
15+
"dependencies": {
16+
"@langchain/openai": "^0.3.16",
17+
"@octokit/rest": "^21.0.2",
18+
"@types/node": "^20.11.0",
19+
"dotenv": "^16.4.7",
20+
"langchain": "^0.3.7",
21+
"@typescript-eslint/parser": "6.18.1",
22+
"@typescript-eslint/types": "6.18.1",
23+
"@typescript-eslint/typescript-estree": "6.18.1",
24+
"yaml": "^2.3.4"
25+
},
26+
"devDependencies": {
27+
"ts-node": "^10.9.2",
28+
"typescript": "5.3.3"
29+
}
30+
}

0 commit comments

Comments
 (0)