PHPStan Rule Flags Issue-Specific @todo Comments in Drupal CI

A new rule in phpstan-drupal 2.0.12 detects unresolved @todo comments that reference the same Drupal.org issue as an active merge request, preventing them from being merged into code. Introduced by Matt Glaman in a blog post, the rule integrates directly into GitLab CI workflows used on Drupal.org.

The rule, TodoCommentWithIssueUrlRule, scans @todo comments for Drupal.org issue URLs and compares them against the current merge request’s issue identifier. If a comment references the same issue being worked on, it is flagged for resolution before the code is merged.

It supports both drupal.org/i/{nid} and drupal.org/project/{project}/issues/{nid} URL formats. The issue identifier is automatically detected from GitLab CI environment variables such as CI_MERGE_REQUEST_SOURCE_BRANCH_NAME and CI_MERGE_REQUEST_SOURCE_PROJECT_PATH, allowing the rule to operate without manual configuration in merge request pipelines.

When these variables are not available, such as during local development or non-merge pipelines, the rule remains inactive. This ensures that it does not interfere with standard development workflows while still enforcing checks in CI environments.

The rule is not enabled by default and must be explicitly added to a project’s phpstan.neon configuration. Projects using Drupal’s GitLab CI templates require a custom configuration file to include additional rules, as template variables do not support extending the default ruleset directly.

The implementation draws inspiration from staabm/phpstan-todo-by, which manages expiring todos based on time or issue status. However, the current rule focuses specifically on detecting issue-linked todos within Drupal’s contribution workflow.

“When making code changes or fixing issues, it’s easy to leave @todo comments behind,” wrote Glaman in the blog post. “The ones tied to the specific issue you're working on should be resolved before the MR merges.”

The update addresses a recurring problem in collaborative development, where temporary comments tied to specific issues remain in the codebase after the issue is resolved. By enforcing checks at the CI level, the rule shifts responsibility for cleanup from manual review to automated validation.