Claude Update Config Parameters Docs #5
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 config parameters 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_body=Update config parameters 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 }} |