claude-update-config-parameters-docs.yml

name: "Claude Update Config Parameters Docs"

on:
  workflow_dispatch:
  workflow_call:

permissions:
  contents: read

jobs:
  fix:
    name: "Update Config Parameters Docs"
    runs-on: "ubuntu-latest"
    timeout-minutes: 60
    permissions:
      contents: read
      issues: read
      pull-requests: write

    steps:
      - name: Harden the runner (Audit all outbound calls)
        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

      - name: "Checkout phpstan-dist"
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          ref: 2.2.x
          repository: phpstan/phpstan

      - name: "Checkout phpstan-src"
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          ref: 2.2.x
          repository: phpstan/phpstan-src
          path: __phpstan-src

      - name: "Install Claude Code"
        run: npm install -g @anthropic-ai/claude-code

      - name: "Run Claude Code"
        env:
          CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          GH_TOKEN: ${{ secrets.PHPSTAN_BOT_FORK_TOKEN }}
        run: |
          git config user.name "phpstan-bot"
          git config user.email "ondrej+phpstanbot@mirtes.cz"

          claude --model claude-opus-4-6 \
          --dangerously-skip-permissions \
          -p "$(cat << 'PROMPT_EOF'

          You are a documentation agent for PHPStan. Your job is to find configuration parameters that exist in the schema but lack user-facing documentation, and to write documentation for them.

          ## Source files

          - **Parameter schema**: `__phpstan-src/conf/parametersSchema.neon` (phpstan-src repo)
          - **Config reference docs**: `website/src/config-reference.md` (checked out from `phpstan/phpstan`)
          - **Source code for research**: `__phpstan-src/src/`, `__phpstan-src/conf/`, and `__phpstan-src/tests/` directories (phpstan-src repo)

          ## Task

          ### Step 1: Read both files

          1. Read `__phpstan-src/conf/parametersSchema.neon` from the workspace
          2. Read `website/src/config-reference.md` from the workspace

          ### Step 2: Identify user-facing parameters from the schema

          Extract all parameter names from `parametersSchema.neon`. Note that some parameters are nested inside `structure()` blocks — these use dotted paths in the user's `phpstan.neon`. For example, the schema has:

          ```neon
          exceptions: structure([
              implicitThrows: bool(),
              check: structure([
                  missingCheckedExceptionInThrows: bool(),
                  tooWideThrowType: bool(),
                  throwTypeCovariance: bool(),
                  tooWideImplicitThrowType: bool()
              ])
          ])
          ```

          This means the user-facing parameters are `exceptions.implicitThrows`, `exceptions.check.missingCheckedExceptionInThrows`, `exceptions.check.tooWideThrowType`, etc. Similarly, `cache` has sub-keys like `cache.nodesByStringCountMax`. Make sure to extract ALL nested parameters, not just top-level ones.

          **Skip these entirely:**

          - The entire `featureToggles` section and all its sub-parameters
          - Everything after the `# playground mode` comment — these are internal/irrelevant:
            - `sourceLocatorPlaygroundMode`
            - Nette parameters: `debugMode`, `productionMode`, `tempDir`, `__validate`
            - DerivativeContainerFactory internals: `additionalConfigFiles`, `generateBaselineFile`, `analysedPaths`, `allConfigFiles`, `composerAutoloaderProjectPaths`, `analysedPathsFromConfig`, `usedLevel`, `cliAutoloadFile`
            - Editor mode internals: `singleReflectionFile`, `singleReflectionInsteadOfFile`

          Also skip these internal parameters that users should not configure directly:
          - `strictRulesInstalled`, `deprecationRulesInstalled` (set by installing packages, not by users)
          - `cliArgumentsVariablesRegistered` (internal CLI flag)
          - `rootDir`, `currentWorkingDirectory` (auto-detected, not user-configurable)
          - `sysGetTempDir` (internal)
          - `parametersNotInvalidatingCache` (internal)
          - `env` (internal environment variable mapping)

          Also skip these level-only parameters — they exist purely to be toggled by rule levels in `conf/config.level*.neon` and are not configured by users directly:
          - `checkThisOnly` (level 2)
          - `checkMaybeUndefinedVariables` (level 1)
          - `checkExtraArguments` (level 1)
          - `reportMagicMethods` (level 1)
          - `reportMagicProperties` (level 1)
          - `checkClassCaseSensitivity` (level 2)
          - `checkPhpDocMissingReturn` (level 2)
          - `checkPhpDocMethodSignatures` (level 3)
          - `checkAdvancedIsset` (level 4)
          - `checkFunctionArgumentTypes` (level 5)
          - `checkArgumentsPassedByReference` (level 5)
          - `checkMissingVarTagTypehint` (level 6)
          - `checkMissingTypehints` (level 6)
          - `checkUnionTypes` (level 7)
          - `reportMaybes` (level 7)
          - `checkNullables` (level 8)
          - `checkExplicitMixed` (level 9)
          - `checkImplicitMixed` (level 10)

          ### Step 3: Determine which parameters are undocumented

          Check which parameter names from the schema do NOT appear as documented parameters in `config-reference.md`. A parameter counts as "documented" if it appears as a heading (`###`), in a config key listing, or is explained in a section body.

          Check ALL non-skipped parameters from the schema against the documentation. Do not look at git history or diffs — compare the entire `parametersSchema.neon` against `config-reference.md` and document every undocumented parameter you find.

          If there are no undocumented parameters, stop and report that all parameters are documented. Do not create a PR.

          ### Step 4: Research each undocumented parameter

          For each undocumented parameter, investigate what it does by reading files from the workspace (phpstan-src):

          1. **Search the source code** in `__phpstan-src/src/` for where the parameter is used. Look for the parameter name in PHP files — it will typically appear in a service constructor or be read from the DI container.
          2. **Check level configs** in `__phpstan-src/conf/config.level*.neon` to see which level enables the parameter and what its default value is.
          3. **Check `__phpstan-src/conf/config.neon`** for the parameter's default value.
          4. **Look at related rules and tests** to understand the behavior. Check `__phpstan-src/tests/` for test data files that exercise the parameter.
          5. **Check if phpstan-strict-rules sets it** by searching for the parameter name in the codebase and noting if strict-rules is mentioned.

          ### Step 5: Write documentation

          Edit the existing `website/src/config-reference.md` file to add the new documentation. Do NOT overwrite the file — use targeted edits to insert new parameter sections in the correct locations.

          **Place each parameter in the correct existing section:**
          - Boolean flags that enable stricter checks → "Stricter analysis" section (as `###` sub-headings)
          - Parameters related to parallel processing → "Parallel processing" section
          - Parameters related to caching → "Caching" section
          - Other general settings → "Miscellaneous parameters" section
          - Parameters related to exceptions → "Exceptions" section

          **Follow the existing documentation conventions exactly:**

          For parameters in "Stricter analysis", use this format:

          ```
          ### `parameterName`

          **default**: `value` ([strict-rules](https://github.com/phpstan/phpstan-strict-rules) sets it to `otherValue`)

          When set to `true/false`, it [concise description of what changes].
          ```

          Include a short PHP code example only if it helps illustrate the behavior clearly. Keep descriptions concise — one or two sentences is ideal.

          If the parameter was introduced in a specific PHPStan version (not 1.0), add a version badge:

          ```html
          <div class="text-xs inline-block border border-green-600 text-green-600 bg-green-100 rounded px-1 mb-4">Available in PHPStan X.Y</div>
          ```

          For parameters in "Miscellaneous parameters", use:

          ```
          ### `parameterName`

          **default**: `value`

          Description of what the parameter does.
          ```

            ## Step 6: Write a summary

            After completing the fix, write two files:

            1. /tmp/commit-message.txt - A concise commit message (first line: short summary under 72 chars, then a blank line, then a few bullet points describing key changes). Example:
               Update error docs - added new `new.trait` identifier

              More detailed description of the commit
            2. /tmp/pr-description.md - A pull request description in this format:
               What was the work involved in updating the docs.

            These files are critical - they will be used for the commit message and PR description.

          PROMPT_EOF
          )"

      - name: "Read Claude's summary"
        id: claude-summary
        run: |
          if [ -f /tmp/commit-message.txt ]; then
            delimiter="EOF_$(openssl rand -hex 16)"
            {
              echo "commit_message<<${delimiter}"
              cat /tmp/commit-message.txt
              echo "${delimiter}"
            } >> "$GITHUB_OUTPUT"
          else
            echo "commit_message=Update error identifiers docs" >> "$GITHUB_OUTPUT"
          fi

          if [ -f /tmp/pr-description.md ]; then
            delimiter="EOF_$(openssl rand -hex 16)"
            {
              echo "pr_body<<${delimiter}"
              cat /tmp/pr-description.md
              echo "${delimiter}"
            } >> "$GITHUB_OUTPUT"
          else
            echo "pr_bodyUpdate error identifiers docs" >> "$GITHUB_OUTPUT"
          fi

      - name: "Delete __phpstan-src"
        run: "rm -r __phpstan-src"

      - name: "Create Pull Request"
        id: create-pr
        uses: peter-evans/create-pull-request@c0f553fe549906ede9cf27b5156039d195d2ece0 # v8.1.0
        with:
          branch-token: ${{ secrets.PHPSTAN_BOT_FORK_TOKEN }}
          token: ${{ secrets.PHPSTAN_BOT_PR_TOKEN }}
          push-to-fork: phpstan-bot/phpstan
          branch-suffix: random
          delete-branch: true
          base: 2.2.x
          title: "Update Config Parameters Docs"
          body: ${{ steps.claude-summary.outputs.pr_body }}
          committer: "phpstan-bot <ondrej+phpstanbot@mirtes.cz>"
          commit-message: ${{ steps.claude-summary.outputs.commit_message }}