Skip to content

Commit bb33a2f

Browse files
adamfriadamfri
authored
Merge 64bd7dc into e3ed400 
2 parents e3ed400 + 64bd7dc commit bb33a2f

File tree

1 file changed

+153
-0
lines changed

1 file changed

+153
-0
lines changed

‎.github/workflows/claude-docs-drafter.yml‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
name: Claude Docs Drafter
2+
3+
on:
4+
pull_request:
5+
types: [opened, synchronize]
6+
paths:
7+
- "src/modules/**"
8+
- "src/client.types.ts"
9+
- "src/types.ts"
10+
11+
jobs:
12+
claude-docs-draft:
13+
if: |
14+
github.actor != 'github-actions[bot]' &&
15+
github.actor != 'claude-code[bot]' &&
16+
github.actor != 'claude[bot]' &&
17+
github.actor != 'claude'
18+
19+
runs-on: ubuntu-latest
20+
permissions:
21+
contents: read
22+
pull-requests: write
23+
issues: write
24+
id-token: write
25+
26+
steps:
27+
- name: Checkout repository
28+
uses: actions/checkout@v4
29+
with:
30+
fetch-depth: 0
31+
32+
- name: Run Claude Docs Drafter
33+
timeout-minutes: 10
34+
id: claude-docs-drafter
35+
uses: anthropics/claude-code-action@v1
36+
with:
37+
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
38+
use_sticky_comment: true
39+
claude_args: |
40+
--model claude-sonnet-4-20250514
41+
--json-schema '{"type":"object","properties":{"needs_docs":{"type":"boolean","description":"true if the PR has public APIs that need new or improved JSDoc"}},"required":["needs_docs"]}'
42+
43+
prompt: |
44+
You are a documentation drafter for the Base44 JavaScript SDK.
45+
46+
## Your task
47+
48+
1. Read the documentation skill file at `.claude/skills/sdk-docs-writing/SKILL.md`. Follow its rules exactly.
49+
2. Look at the changes in this PR (the diff of files under `src/modules/`, `src/client.types.ts`, and `src/types.ts`).
50+
3. Identify any **new or modified public APIs** (interfaces, types, methods, properties) that are missing JSDoc or have incomplete JSDoc according to the skill's rules.
51+
4. Check the existing `.types.ts` files in `src/modules/` and the generated docs in `docs/content/` to understand the established patterns and voice. Your suggestions must match these patterns.
52+
53+
## How to report
54+
55+
Post a **single PR comment** with the following structure:
56+
57+
### 📝 Documentation Draft
58+
59+
**Summary**
60+
A brief overview of what new or changed public APIs were found in this PR and whether they need documentation. If everything is already documented, say so.
61+
62+
**Draft JSDoc**
63+
For each public API that is missing or has incomplete JSDoc, provide the complete suggested JSDoc block. Group suggestions by file. Use this format:
64+
65+
---
66+
67+
#### `src/modules/example.types.ts`
68+
69+
**`ExampleModule.myMethod`** — *New method, missing JSDoc entirely.*
70+
71+
```typescript
72+
/**
73+
* Does something useful.
74+
*
75+
* @param id - The unique identifier. Defaults to `undefined`.
76+
* @returns Promise resolving to the result object.
77+
*
78+
* @example
79+
* ```typescript
80+
* // Basic usage
81+
* const result = await base44.example.myMethod('abc');
82+
* ```
83+
*
84+
* @example
85+
* ```typescript
86+
* // With error handling
87+
* try {
88+
* const result = await base44.example.myMethod('abc');
89+
* } catch (error) {
90+
* console.error('Failed:', error);
91+
* }
92+
* ```
93+
*/
94+
myMethod(id: string): Promise<Result>;
95+
```
96+
97+
---
98+
99+
Include the original method/property signature at the bottom of each code block so the developer can see exactly where the JSDoc should be placed.
100+
101+
**Checklist**
102+
End with this checklist for the developer and tech writer to verify:
103+
- [ ] JSDoc completeness (description, `@param`, `@returns`, `@example`)
104+
- [ ] `@internal` on implementation-only exports
105+
- [ ] New types added to `types-to-expose.json` if needed
106+
- [ ] Helper types added to `appended-articles.json` if needed
107+
- [ ] Examples use `base44.` call path and are valid TypeScript
108+
109+
## Structured output
110+
111+
You MUST return a structured output with the field `needs_docs`.
112+
- Set `needs_docs` to `true` if you found any public APIs that need new or improved JSDoc.
113+
- Set `needs_docs` to `false` if every public API already has complete, correct JSDoc and you have no suggestions.
114+
115+
## Rules
116+
- Do NOT commit any changes to the PR branch. Only comment.
117+
- Do NOT modify any files. You are read-only.
118+
- Be specific and actionable. Don't give vague advice.
119+
- For each suggestion, briefly state why it's needed (new API, missing `@example`, incomplete `@param` tags, etc.).
120+
- Match the tone and style of existing JSDoc in the codebase.
121+
- If a public API already has complete, correct JSDoc, skip it — don't suggest changes for the sake of it.
122+
123+
- name: Add docs-draft label
124+
if: success() && fromJSON(steps.claude-docs-drafter.outputs.structured_output).needs_docs == true
125+
uses: actions/github-script@v7
126+
with:
127+
script: |
128+
// Create the label if it doesn't exist yet
129+
try {
130+
await github.rest.issues.getLabel({
131+
owner: context.repo.owner,
132+
repo: context.repo.repo,
133+
name: 'docs-draft'
134+
});
135+
} catch (e) {
136+
if (e.status === 404) {
137+
await github.rest.issues.createLabel({
138+
owner: context.repo.owner,
139+
repo: context.repo.repo,
140+
name: 'docs-draft',
141+
color: '1D76DB',
142+
description: 'PR has auto-drafted documentation suggestions'
143+
});
144+
}
145+
}
146+
147+
// Add the label to the PR
148+
await github.rest.issues.addLabels({
149+
owner: context.repo.owner,
150+
repo: context.repo.repo,
151+
issue_number: context.issue.number,
152+
labels: ['docs-draft']
153+
});

0 commit comments

Comments
 (0)