Claude Update Error Docs #25
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 Error Docs" | |
| on: | |
| workflow_dispatch: | |
| inputs: | |
| sha: | |
| description: "phpstan/phpstan commit with errorIdentifiers.json change" | |
| required: true | |
| type: string | |
| workflow_call: | |
| inputs: | |
| sha: | |
| description: "phpstan/phpstan commit with errorIdentifiers.json change" | |
| required: true | |
| type: string | |
| permissions: | |
| contents: read | |
| jobs: | |
| fix: | |
| name: "Update Error 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" | |
| uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1 | |
| with: | |
| ref: ${{ inputs.sha }} | |
| repository: phpstan/phpstan | |
| fetch-depth: 10 | |
| - 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 generating documentation pages for PHPStan error identifiers. PHPStan is a PHP static analysis tool that finds bugs in code without running it. Each error identifier (like `argument.type`, `deadCode.unreachable`, `property.notFound`) categorizes a specific type of error. | |
| The goal is to create a markdown file for each identifier in `website/errors/` explaining what the error means, showing a code example, and offering ways to fix it. | |
| ## Step 1: Find what changed | |
| See the checked out commit of the current repository. It should contain changes to `website/src/errorsIdentifiers.json`. See if the diff means any identifier was added or updated. | |
| Read `website/src/errorsIdentifiers.json`. This JSON maps each identifier to its rule classes and source code locations: | |
| ```json | |
| { | |
| "argument.type": { | |
| "PHPStan\\Rules\\Functions\\CallToFunctionParametersRule": { | |
| "phpstan/phpstan-src": [ | |
| "https://github.com/phpstan/phpstan-src/blob/2.2.x/src/Rules/FunctionCallParametersCheck.php#L280" | |
| ] | |
| } | |
| } | |
| } | |
| ``` | |
| Then list existing files in `website/errors/`. Each file is named `<identifier>.md`. | |
| You will document any identifiers that do not have .md file. You will also look if any identifiers involved in the diff of the checked out commit need updating the docs. | |
| ## Step 2: Clone required repositories | |
| Clone only the repositories referenced by the affected identifiers. Extract the branch name from the GitHub URLs (e.g., `blob/2.2.x/` → branch `2.2.x`). | |
| Use shallow clones to save time: | |
| ```bash | |
| git clone --depth 1 --branch <branch> https://github.com/phpstan/<repo>.git /tmp/repos/<repo> | |
| ``` | |
| The possible repositories are: | |
| - `phpstan/phpstan-src` (typically branch `2.2.x`) | |
| - `phpstan/phpstan-strict-rules` | |
| - `phpstan/phpstan-deprecation-rules` | |
| - `phpstan/phpstan-doctrine` | |
| - `phpstan/phpstan-symfony` | |
| - `phpstan/phpstan-phpunit` | |
| - `phpstan/phpstan-nette` | |
| ## Step 3: Research each identifier | |
| For each identifier, gather the information needed to write the documentation. | |
| ### 3a. Read the rule source code | |
| From the JSON URLs, extract the file path and line number. Read the source code around those lines to find: | |
| 1. **Error message**: Look for `RuleErrorBuilder::message('...')` — this is the exact error text PHPStan shows | |
| 2. **Trigger condition**: Read the surrounding `processNode()` method to understand what code pattern causes this error | |
| 3. **Tips**: Look for `->tip('...')` or `->addTip('...')` calls in the same builder chain — these often contain links to blog posts or documentation pages on phpstan.org | |
| 4. **Non-ignorable**: Check for `->nonIgnorable()` in the builder chain | |
| ### 3b. Understand the identifier prefix when source uses `$location->createIdentifier()` | |
| When reading the rule source code in step 3a, check whether the linked source code line uses `$location->createIdentifier()`. If it does, the identifier prefix comes from `ClassNameUsageLocation` in phpstan-src, and the prefix indicates a specific PHP language feature — which may not be obvious from the prefix name alone. | |
| If the source code does **not** use `$location->createIdentifier()`, the prefix is set directly by the rule and typically describes its PHP feature straightforwardly. | |
| Consult the "Identifier prefix reference" section in `website/errors/CLAUDE.md` for the complete prefix-to-PHP-feature mapping tables. | |
| ### 3c. Find test fixtures with code examples | |
| For a rule class like `PHPStan\Rules\Functions\CallToFunctionParametersRule`: | |
| - Test class: `tests/PHPStan/Rules/Functions/CallToFunctionParametersRuleTest.php` | |
| - Test data: `tests/PHPStan/Rules/Functions/data/*.php` | |
| For extension repos (phpstan-doctrine, phpstan-symfony, etc.), the path pattern may differ — check `tests/Rules/` or `tests/` directories. | |
| Read the test class to find which data files trigger this specific identifier. Look for the error message text in the test assertions: | |
| ```php | |
| $this->analyse([__DIR__ . '/data/someFile.php'], [ | |
| ['Error message text', 42], | |
| ]); | |
| ``` | |
| Then read the corresponding data file to extract a minimal code example. | |
| ### 3d. Determine if the error is ignorable | |
| An error identifier is **not ignorable** if: | |
| - The source code uses `->nonIgnorable()` in the error builder chain | |
| - The identifier starts with `phpstan.` (internal PHPStan errors) | |
| - The identifier starts with `phpstanPlayground.` (playground-specific) | |
| All other identifiers are ignorable. | |
| ### 3e. Check for configuration options | |
| Some rules accept constructor parameters from PHPStan configuration. Look at the rule class constructor for injected config values. Cross-reference with `website/src/config-reference.md` to find the documented parameter name. | |
| Examples of configurable rules: | |
| - Rules that check strict types may be controlled by `treatPhpDocTypesAsCertain` | |
| - Dead code rules may be controlled by `checkAlwaysTrueCheckTypeFunctionCall` | |
| - Some rules are only active at certain PHPStan levels | |
| ## Step 4: Generate markdown files | |
| Create `website/errors/` directory if it doesn't exist. | |
| For each identifier, create `website/errors/<identifier>.md` following the file format, content guidelines, and tone described in `website/errors/CLAUDE.md`. Read that file before generating any markdown. | |
| Each file's frontmatter MUST include a `shortDescription` field — one sentence (ending with a period) describing when the error is reported, from a user's perspective. For example: `"Accessing a private property from outside the declaring class."` or `"Loose comparison using == will always evaluate to true."`. This description should capture the essence of the error — what code pattern triggers it — without mentioning PHPStan internals. | |
| ## Step 5: 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_body=Update error identifiers docs" >> "$GITHUB_OUTPUT" | |
| fi | |
| - 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 Error Docs" | |
| body: ${{ steps.claude-summary.outputs.pr_body }} | |
| committer: "phpstan-bot <ondrej+phpstanbot@mirtes.cz>" | |
| commit-message: ${{ steps.claude-summary.outputs.commit_message }} |