claude-docs-drafter.yml

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@11d5960a326750d5838078e36cf38b85af677262 # v4
        with:
          fetch-depth: 0

      - name: Wix gateway proxy (mandatory)
        uses: ./.github/actions/wix-gateway-proxy

      - name: Run Claude Docs Drafter
        timeout-minutes: 10
        id: claude-docs-drafter
        uses: anthropics/claude-code-action@239e3a730883eeb5c53db12b0fc9573b3024b126 # v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          use_sticky_comment: true
          claude_args: |
            --model claude-sonnet-4-6
            --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<Result>;
            ```

            ---

            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@f28e40c7f34bde8b3046d885e986cb6290c5673b # 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']
            });