diff --git a/.github/workflows/claude-docs-drafter.yml b/.github/workflows/claude-docs-drafter.yml new file mode 100644 index 0000000..eb957a9 --- /dev/null +++ b/.github/workflows/claude-docs-drafter.yml @@ -0,0 +1,153 @@ +name: Claude Docs Drafter + +on: + pull_request: + types: [opened, synchronize] + paths: + - "src/modules/**" + - "src/client.types.ts" + - "src/types.ts" + +jobs: + claude-docs-draft: + if: | + github.actor != 'github-actions[bot]' && + github.actor != 'claude-code[bot]' && + github.actor != 'claude[bot]' && + github.actor != 'claude' + + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: write + issues: write + id-token: write + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 2 + + - name: Run Claude Docs Drafter + timeout-minutes: 10 + id: claude-docs-drafter + uses: anthropics/claude-code-action@v1 + with: + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + use_sticky_comment: true + claude_args: | + --model claude-sonnet-4-20250514 + --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"]}' + + prompt: | + You are a documentation drafter for the Base44 JavaScript SDK. + + ## Your task + + 1. Read the documentation skill file at `.claude/skills/sdk-docs-writing/SKILL.md`. Follow its rules exactly. + 2. Look at the changes in this PR (the diff of files under `src/modules/`, `src/client.types.ts`, and `src/types.ts`). + 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. + 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. + + ## How to report + + Post a **single PR comment** with the following structure: + + ### 📝 Documentation Draft + + **Summary** + 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. + + **Draft JSDoc** + For each public API that is missing or has incomplete JSDoc, provide the complete suggested JSDoc block. Group suggestions by file. Use this format: + + --- + + #### `src/modules/example.types.ts` + + **`ExampleModule.myMethod`** — *New method, missing JSDoc entirely.* + + ```typescript + /** + * Does something useful. + * + * @param id - The unique identifier. Defaults to `undefined`. + * @returns Promise resolving to the result object. + * + * @example + * ```typescript + * // Basic usage + * const result = await base44.example.myMethod('abc'); + * ``` + * + * @example + * ```typescript + * // With error handling + * try { + * const result = await base44.example.myMethod('abc'); + * } catch (error) { + * console.error('Failed:', error); + * } + * ``` + */ + myMethod(id: string): Promise; + ``` + + --- + + 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. + + **Checklist** + End with this checklist for the developer and tech writer to verify: + - [ ] JSDoc completeness (description, `@param`, `@returns`, `@example`) + - [ ] `@internal` on implementation-only exports + - [ ] New types added to `types-to-expose.json` if needed + - [ ] Helper types added to `appended-articles.json` if needed + - [ ] Examples use `base44.` call path and are valid TypeScript + + ## Structured output + + You MUST return a structured output with the field `needs_docs`. + - Set `needs_docs` to `true` if you found any public APIs that need new or improved JSDoc. + - Set `needs_docs` to `false` if every public API already has complete, correct JSDoc and you have no suggestions. + + ## Rules + - Do NOT commit any changes to the PR branch. Only comment. + - Do NOT modify any files. You are read-only. + - Be specific and actionable. Don't give vague advice. + - For each suggestion, briefly state why it's needed (new API, missing `@example`, incomplete `@param` tags, etc.). + - Match the tone and style of existing JSDoc in the codebase. + - If a public API already has complete, correct JSDoc, skip it — don't suggest changes for the sake of it. + + - name: Add docs-draft label + if: success() && fromJSON(steps.claude-docs-drafter.outputs.structured_output).needs_docs == true + uses: actions/github-script@v7 + with: + script: | + // Create the label if it doesn't exist yet + try { + await github.rest.issues.getLabel({ + owner: context.repo.owner, + repo: context.repo.repo, + name: 'docs-draft' + }); + } catch (e) { + if (e.status === 404) { + await github.rest.issues.createLabel({ + owner: context.repo.owner, + repo: context.repo.repo, + name: 'docs-draft', + color: '1D76DB', + description: 'PR has auto-drafted documentation suggestions' + }); + } + } + + // Add the label to the PR + await github.rest.issues.addLabels({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + labels: ['docs-draft'] + });