Skip to content

Commit 11cfa92

Browse files
ondrejmirtesondrejmirtes
committed
Update Config Parameters Docs workflow
1 parent 04d85e7 commit 11cfa92

1 file changed

Lines changed: 237 additions & 0 deletions

File tree

‎.github/workflows/claude-update-config-parameters-docs.yml‎

Lines changed: 237 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,237 @@
1+
name: "Claude Update Config Parameters Docs"
2+
3+
on:
4+
workflow_dispatch:
5+
workflow_call:
6+
7+
permissions:
8+
contents: read
9+
10+
jobs:
11+
fix:
12+
name: "Update Config Parameters Docs"
13+
runs-on: "ubuntu-latest"
14+
timeout-minutes: 60
15+
permissions:
16+
contents: read
17+
issues: read
18+
pull-requests: write
19+
20+
steps:
21+
- name: Harden the runner (Audit all outbound calls)
22+
uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
23+
with:
24+
egress-policy: audit
25+
26+
- name: "Checkout phpstan-dist"
27+
uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
28+
with:
29+
ref: 2.2.x
30+
repository: phpstan/phpstan
31+
32+
- name: "Checkout phpstan-src"
33+
uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
34+
with:
35+
ref: 2.2.x
36+
repository: phpstan/phpstan-src
37+
path: __phpstan-src
38+
39+
- name: "Install Claude Code"
40+
run: npm install -g @anthropic-ai/claude-code
41+
42+
- name: "Run Claude Code"
43+
env:
44+
CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
45+
GH_TOKEN: ${{ secrets.PHPSTAN_BOT_FORK_TOKEN }}
46+
run: |
47+
git config user.name "phpstan-bot"
48+
git config user.email "ondrej+phpstanbot@mirtes.cz"
49+
50+
claude --model claude-opus-4-6 \
51+
--dangerously-skip-permissions \
52+
-p "$(cat << 'PROMPT_EOF'
53+
54+
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.
55+
56+
## Source files
57+
58+
- **Parameter schema**: `__phpstan-src/conf/parametersSchema.neon` (phpstan-src repo)
59+
- **Config reference docs**: `website/src/config-reference.md` (checked out from `phpstan/phpstan`)
60+
- **Source code for research**: `__phpstan-src/src/`, `__phpstan-src/conf/`, and `__phpstan-src/tests/` directories (phpstan-src repo)
61+
62+
## Task
63+
64+
### Step 1: Read both files
65+
66+
1. Read `__phpstan-src/conf/parametersSchema.neon` from the workspace
67+
2. Read `website/src/config-reference.md` from the workspace
68+
69+
### Step 2: Identify user-facing parameters from the schema
70+
71+
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:
72+
73+
```neon
74+
exceptions: structure([
75+
implicitThrows: bool(),
76+
check: structure([
77+
missingCheckedExceptionInThrows: bool(),
78+
tooWideThrowType: bool(),
79+
throwTypeCovariance: bool(),
80+
tooWideImplicitThrowType: bool()
81+
])
82+
])
83+
```
84+
85+
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.
86+
87+
**Skip these entirely:**
88+
89+
- The entire `featureToggles` section and all its sub-parameters
90+
- Everything after the `# playground mode` comment — these are internal/irrelevant:
91+
- `sourceLocatorPlaygroundMode`
92+
- Nette parameters: `debugMode`, `productionMode`, `tempDir`, `__validate`
93+
- DerivativeContainerFactory internals: `additionalConfigFiles`, `generateBaselineFile`, `analysedPaths`, `allConfigFiles`, `composerAutoloaderProjectPaths`, `analysedPathsFromConfig`, `usedLevel`, `cliAutoloadFile`
94+
- Editor mode internals: `singleReflectionFile`, `singleReflectionInsteadOfFile`
95+
96+
Also skip these internal parameters that users should not configure directly:
97+
- `strictRulesInstalled`, `deprecationRulesInstalled` (set by installing packages, not by users)
98+
- `cliArgumentsVariablesRegistered` (internal CLI flag)
99+
- `rootDir`, `currentWorkingDirectory` (auto-detected, not user-configurable)
100+
- `sysGetTempDir` (internal)
101+
- `parametersNotInvalidatingCache` (internal)
102+
- `env` (internal environment variable mapping)
103+
104+
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:
105+
- `checkThisOnly` (level 2)
106+
- `checkMaybeUndefinedVariables` (level 1)
107+
- `checkExtraArguments` (level 1)
108+
- `reportMagicMethods` (level 1)
109+
- `reportMagicProperties` (level 1)
110+
- `checkClassCaseSensitivity` (level 2)
111+
- `checkPhpDocMissingReturn` (level 2)
112+
- `checkPhpDocMethodSignatures` (level 3)
113+
- `checkAdvancedIsset` (level 4)
114+
- `checkFunctionArgumentTypes` (level 5)
115+
- `checkArgumentsPassedByReference` (level 5)
116+
- `checkMissingVarTagTypehint` (level 6)
117+
- `checkMissingTypehints` (level 6)
118+
- `checkUnionTypes` (level 7)
119+
- `reportMaybes` (level 7)
120+
- `checkNullables` (level 8)
121+
- `checkExplicitMixed` (level 9)
122+
- `checkImplicitMixed` (level 10)
123+
124+
### Step 3: Determine which parameters are undocumented
125+
126+
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.
127+
128+
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.
129+
130+
If there are no undocumented parameters, stop and report that all parameters are documented. Do not create a PR.
131+
132+
### Step 4: Research each undocumented parameter
133+
134+
For each undocumented parameter, investigate what it does by reading files from the workspace (phpstan-src):
135+
136+
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.
137+
2. **Check level configs** in `__phpstan-src/conf/config.level*.neon` to see which level enables the parameter and what its default value is.
138+
3. **Check `__phpstan-src/conf/config.neon`** for the parameter's default value.
139+
4. **Look at related rules and tests** to understand the behavior. Check `__phpstan-src/tests/` for test data files that exercise the parameter.
140+
5. **Check if phpstan-strict-rules sets it** by searching for the parameter name in the codebase and noting if strict-rules is mentioned.
141+
142+
### Step 5: Write documentation
143+
144+
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.
145+
146+
**Place each parameter in the correct existing section:**
147+
- Boolean flags that enable stricter checks → "Stricter analysis" section (as `###` sub-headings)
148+
- Parameters related to parallel processing → "Parallel processing" section
149+
- Parameters related to caching → "Caching" section
150+
- Other general settings → "Miscellaneous parameters" section
151+
- Parameters related to exceptions → "Exceptions" section
152+
153+
**Follow the existing documentation conventions exactly:**
154+
155+
For parameters in "Stricter analysis", use this format:
156+
157+
```
158+
### `parameterName`
159+
160+
**default**: `value` ([strict-rules](https://github.com/phpstan/phpstan-strict-rules) sets it to `otherValue`)
161+
162+
When set to `true/false`, it [concise description of what changes].
163+
```
164+
165+
Include a short PHP code example only if it helps illustrate the behavior clearly. Keep descriptions concise — one or two sentences is ideal.
166+
167+
If the parameter was introduced in a specific PHPStan version (not 1.0), add a version badge:
168+
169+
```html
170+
<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>
171+
```
172+
173+
For parameters in "Miscellaneous parameters", use:
174+
175+
```
176+
### `parameterName`
177+
178+
**default**: `value`
179+
180+
Description of what the parameter does.
181+
```
182+
183+
## Step 6: Write a summary
184+
185+
After completing the fix, write two files:
186+
187+
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:
188+
Update error docs - added new `new.trait` identifier
189+
190+
More detailed description of the commit
191+
2. /tmp/pr-description.md - A pull request description in this format:
192+
What was the work involved in updating the docs.
193+
194+
These files are critical - they will be used for the commit message and PR description.
195+
196+
PROMPT_EOF
197+
)"
198+
199+
- name: "Read Claude's summary"
200+
id: claude-summary
201+
run: |
202+
if [ -f /tmp/commit-message.txt ]; then
203+
delimiter="EOF_$(openssl rand -hex 16)"
204+
{
205+
echo "commit_message<<${delimiter}"
206+
cat /tmp/commit-message.txt
207+
echo "${delimiter}"
208+
} >> "$GITHUB_OUTPUT"
209+
else
210+
echo "commit_message=Update error identifiers docs" >> "$GITHUB_OUTPUT"
211+
fi
212+
213+
if [ -f /tmp/pr-description.md ]; then
214+
delimiter="EOF_$(openssl rand -hex 16)"
215+
{
216+
echo "pr_body<<${delimiter}"
217+
cat /tmp/pr-description.md
218+
echo "${delimiter}"
219+
} >> "$GITHUB_OUTPUT"
220+
else
221+
echo "pr_bodyUpdate error identifiers docs" >> "$GITHUB_OUTPUT"
222+
fi
223+
224+
- name: "Create Pull Request"
225+
id: create-pr
226+
uses: peter-evans/create-pull-request@c0f553fe549906ede9cf27b5156039d195d2ece0 # v8.1.0
227+
with:
228+
branch-token: ${{ secrets.PHPSTAN_BOT_FORK_TOKEN }}
229+
token: ${{ secrets.PHPSTAN_BOT_PR_TOKEN }}
230+
push-to-fork: phpstan-bot/phpstan
231+
branch-suffix: random
232+
delete-branch: true
233+
base: 2.2.x
234+
title: "Update Config Parameters Docs"
235+
body: ${{ steps.claude-summary.outputs.pr_body }}
236+
committer: "phpstan-bot <ondrej+phpstanbot@mirtes.cz>"
237+
commit-message: ${{ steps.claude-summary.outputs.commit_message }}

0 commit comments

Comments
 (0)