Setup GitHub actions to check documentation files #1603

henriquemoody · 2026-01-12T14:06:53Z

No description provided.

codecov · 2026-01-12T14:08:03Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.46%. Comparing base (cd96d01) to head (d2ea08d).

Additional details and impacted files

@@            Coverage Diff            @@
##               main    #1603   +/-   ##
=========================================
  Coverage     97.46%   97.46%           
  Complexity      991      991           
=========================================
  Files           211      211           
  Lines          2292     2292           
=========================================
  Hits           2234     2234           
  Misses           58       58

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

When we make changes to the category of a rule, it's easy to forget to update overall list of rules. This commit a GitHub actions that will run a console command to check if the documentation it up-to-date. The job will fail when we need to change the document, but the console command will fix the issues, so there isn't a lot of friction there.

When we make changes to the code, renaming variables, or adding parameters to a validator, it's easy to forget to update the documentation. This commit will create a console command that will automatically update the headers of each validator documentation file, so it matches the constructor of the validator itself. With this change, we avoid having a disparity between the documentation and the code.

This commit ensures that if validator A has a direct link to validator B, validator B will have a direct link to validator A too. We are already doing that, but this commit will add a GitHub action with a command that will fail if there are any changes required.

We don't often change the tempaltes of validators, but when we do it's extremely important that the documentation of the validators match the exact template the validator has. This commit will create a console command to the GitHub workflow that will ensure that the documentation of validators are always aligned with the templates they have.

Copilot

Pull request overview

This pull request sets up GitHub Actions to automatically check documentation files and refactors the documentation generation system. The PR replaces a single monolithic UpdateDocLinksCommand with four specialized commands that each handle a specific aspect of documentation generation: validator headers, index, related validators, and templates. It also introduces new Markdown\Builder and Markdown\Differ classes to provide better tooling for generating and comparing markdown content.

Changes:

Introduced new markdown generation infrastructure with Builder and Differ classes
Replaced UpdateDocLinksCommand with four specialized commands for different documentation aspects
Added GitHub Actions workflow to validate documentation files on CI
Updated numerous validator documentation files with corrected parameter names, type annotations, and formatting

Reviewed changes

Copilot reviewed 57 out of 58 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
src-dev/Markdown/Differ.php	New class for generating colored diffs of markdown content
src-dev/Markdown/Builder.php	New class providing a fluent API for building markdown documents
src-dev/Commands/DocsValidatorsTemplatesCommand.php	New command to update validator template tables in documentation
src-dev/Commands/DocsValidatorsRelatedCommand.php	New command to update related validator links in documentation
src-dev/Commands/DocsValidatorsListCommand.php	New command to generate the index of validators by category
src-dev/Commands/DocsValidatorsHeadersCommand.php	New command to update validator function signatures in documentation
src-dev/Commands/UpdateDocLinksCommand.php	Removed old monolithic documentation update command
composer.json	Added sebastian/diff dependency and new composer scripts for documentation commands
bin/console	Updated to register new documentation commands with Differ dependency
docs/validators/*.md	Updated validator documentation with corrected signatures, parameter names, and formatting
docs/validators/index.md	Updated index page with new title and removed duplicate Type validator entries
docs/index.md	Updated link to new validators index location
docs/getting-started.md	Updated link to new validators index location
README.md	Updated link to new validators index location
.github/workflows/continuous-integration-docs.yml	New workflow to validate documentation files
.github/workflows/continuous-integration-code.yml	Renamed workflow title for clarity

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-12T14:14:46Z

src-dev/Commands/DocsValidatorsTemplatesCommand.php

+            return Command::SUCCESS;
+        }
+
+        $output->writeln(sprintf('<comment>Changed needed in %d files.</comment>', count($diffs)));


Typo in the output message: "Changed needed" should be "Changes needed".

Copilot · 2026-01-12T14:14:47Z

src-dev/Commands/DocsValidatorsRelatedCommand.php

+            return Command::SUCCESS;
+        }
+
+        $output->writeln(sprintf('<comment>Changed needed in %d files.</comment>', count($diffs)));


Typo in the output message: "Changed needed" should be "Changes needed".

Copilot · 2026-01-12T14:14:47Z

src-dev/Commands/DocsValidatorsHeadersCommand.php

+            return Command::SUCCESS;
+        }
+
+        $output->writeln(sprintf('<comment>Changed needed in %d files.</comment>', count($diffs)));


Typo in the output message: "Changed needed" should be "Changes needed".

Copilot · 2026-01-12T14:14:47Z

src-dev/Commands/DocsValidatorsHeadersCommand.php

+        if (!$reflection->isDefaultValueAvailable()) {
+            return ['optional' => true] + $parameter;


Redundant condition check. The condition !$reflection->isDefaultValueAvailable() is checked at lines 240 and 248, with the first check already returning early if true. The second check at line 248 will always be false at this point, making it dead code.

Copilot · 2026-01-12T14:14:47Z

src-dev/Commands/DocsValidatorsHeadersCommand.php

+    /** @return Parameter|null */
+    private function getParameter(ReflectionParameter $reflection): array|null


The psalm type annotation for Parameter specifies this is an array with specific keys, but the method signature returns array|null. This should be documented as Parameter|null to match the psalm type defined in the docblock.

Copilot · 2026-01-12T14:14:49Z

src-dev/Commands/DocsValidatorsHeadersCommand.php

+        return $contracts;
+    }
+
+    /** @param Parameter $parameters */


The parameter documentation @param Parameter $parameters is incorrect. The parameter is named $parameters (plural) but the type annotation suggests it's a single Parameter (which is an array). The documentation should be @param array<Parameter> or the parameter name should be singular.

Copilot · 2026-01-12T14:14:49Z

src-dev/Commands/DocsValidatorsTemplatesCommand.php

+        $output->writeln(sprintf('<comment>Changed needed in %d files.</comment>', count($diffs)));
+        $output->writeln(implode(PHP_EOL, $diffs));
+
+        return Command::FAILURE;


The command returns Command::FAILURE when changes are needed (line 69), which is semantically incorrect. A failure status should indicate an error in execution, not that the documentation needs updating. This will cause CI to fail when documentation updates are detected, which may be the intended behavior for validation purposes, but the naming and messaging are misleading. Consider using a clearer approach or documenting this behavior.

Copilot · 2026-01-12T14:14:49Z

src-dev/Commands/DocsValidatorsHeadersCommand.php

+        $output->writeln(sprintf('<comment>Changed needed in %d files.</comment>', count($diffs)));
+        $output->writeln(implode(PHP_EOL, $diffs));
+
+        return Command::FAILURE;


The command returns Command::FAILURE when changes are needed (line 87), which is semantically incorrect. A failure status should indicate an error in execution, not that the documentation needs updating. This will cause CI to fail when documentation updates are detected, which may be the intended behavior for validation purposes, but the naming and messaging are misleading. Consider using a clearer approach or documenting this behavior.

Copilot · 2026-01-12T14:14:49Z

src-dev/Commands/DocsValidatorsListCommand.php

+        $output->writeln($diff);
+        $output->writeln('<comment>Changes needed.</comment>');
+
+        return Command::FAILURE;


The command returns Command::FAILURE when changes are needed (line 90), which is semantically incorrect. A failure status should indicate an error in execution, not that the documentation needs updating. This will cause CI to fail when documentation updates are detected, which may be the intended behavior for validation purposes, but the naming and messaging are misleading. Consider using a clearer approach or documenting this behavior.

Copilot · 2026-01-12T14:14:50Z

src-dev/Markdown/Differ.php

+                match ($matches[1]) {
+                    '+' => 'green',
+                    '-' => 'red',
+                    '@@' => 'cyan',
+                },


Missing default case in match expression. The match expression handles '+', '-', and '@@' cases but doesn't include a default case. If $matches[1] contains an unexpected value, this will throw an UnhandledMatchError. Consider adding a default case or validating the input before the match expression.

henriquemoody force-pushed the housekeeping/docs branch from 79a8cea to 7a1aa61 Compare January 12, 2026 14:08

henriquemoody added 4 commits January 12, 2026 07:08

henriquemoody force-pushed the housekeeping/docs branch from 7a1aa61 to d2ea08d Compare January 12, 2026 14:09

henriquemoody requested a review from Copilot January 12, 2026 14:09

Copilot started reviewing on behalf of henriquemoody January 12, 2026 14:09 View session

Copilot AI reviewed Jan 12, 2026

View reviewed changes

		if (!$reflection->isDefaultValueAvailable()) {
		return ['optional' => true] + $parameter;

		/** @return Parameter\|null */
		private function getParameter(ReflectionParameter $reflection): array\|null

Setup GitHub actions to check documentation files #1603

Are you sure you want to change the base?

Setup GitHub actions to check documentation files #1603

Uh oh!

Conversation

henriquemoody commented Jan 12, 2026

Uh oh!

codecov bot commented Jan 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 12, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

codecov bot commented Jan 12, 2026 •

edited

Loading