Fix Plugin/Theme header detection in PHP docblocks by richtabor · Pull Request #103 · WordPress/agent-skills

richtabor · 2026-09-07T18:47:32Z

Summary

detectPluginHeaderFromPhpFile and parsePluginHeader failed on standard WordPress plugin headers because the regex required only leading whitespace before the label:

/^\s*Plugin Name:\s*(.+)\s*$/im

A typical header line is * Plugin Name: Foo — the * is not whitespace — so detection returned null / count: 0 for every normal plugin.

Before

contents.match(/^\s*Plugin Name:\s*(.+)\s*$/im)
// Theme Name similarly
new RegExp(`^\\s*${label}:\\s*(.+)\\s*$`, "im")

After

contents.match(/^\s*\*?\s*Plugin Name:\s*(.+)\s*$/im)
contents.match(/^\s*\*?\s*Theme Name:\s*(.+)\s*$/im)
new RegExp(`^\\s*\\*?\\s*${label}:\\s*(.+)\\s*$`, "im")

Optional docblock star keeps bare Plugin Name: / Theme Name: lines working (e.g. theme style.css).

Files

skills/wp-project-triage/scripts/detect_wp_project.mjs
skills/wp-plugin-development/scripts/detect_plugins.mjs

Verification (local fixtures)

Against a docblock-style plugin ( * Plugin Name: WP Hello Plugin):

detect_wp_project → primary: "wp-plugin", detectedPluginName: "WP Hello Plugin"
detect_plugins → count: 1

Against empty non-WP dir: still unknown / count: 0.

Against block theme fixture: still wp-block-theme with detectedThemeName set.

github-actions · 2026-09-07T18:47:40Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: richtabor <richtabor@git.wordpress.org>
Co-authored-by: bgrgicak <berislavgrgicak@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

Standard WordPress plugin headers use docblock lines like ` * Plugin Name: Foo`, where the asterisk is not whitespace. The previous regexes required only leading whitespace before the label, so detectPluginHeaderFromPhpFile and parsePluginHeader missed every normal header. Allow an optional docblock star before Plugin Name, Theme Name, and other plugin header labels.

Copilot

🟢 Approval recommended

The regex updates directly address the documented detection failure mode without introducing incompatible behavior for non-docblock header formats.

Pull request overview

This PR fixes WordPress plugin/theme header detection in the repository’s WP detection scripts by updating the header-matching regexes to support standard docblock formatting (e.g., * Plugin Name: Foo), which previously failed because * is not whitespace.

Changes:

Update plugin header detection in detect_wp_project.mjs to allow an optional docblock * before Plugin Name: / Theme Name:.
Update parsePluginHeader in detect_plugins.mjs to allow an optional docblock * before all supported header labels.

File summaries

File	Description
skills/wp-project-triage/scripts/detect_wp_project.mjs	Adjusts regexes so plugin/theme headers are detected even when written in docblock `* ...` style.
skills/wp-plugin-development/scripts/detect_plugins.mjs	Adjusts per-label header parsing regex to support docblock `*` prefix across all parsed header fields.

Review details

Files reviewed: 2/2 changed files
Comments generated: 0
Review effort level: Lite

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

richtabor · 2026-09-07T18:51:09Z

Found dry-running Agent Plugin packaging: standard docblock Plugin Name headers were invisible to both detectors. Private holding pen already has the same fix (richtabor/agent-plugin 0.3.4). Needs a write-access review to land on trunk so sync does not regress it.

richtabor · 2026-09-07T20:46:36Z

Noting related work in #88 — same root cause (docblock * before header labels). Thank you @Herm71 for digging into that and mirroring core's get_file_data / _cleanup_header_comment approach.

This PR takes a smaller cut for the same bug: optional leading * so the common * Plugin Name: / * Theme Name: form matches, while still allowing bare header lines (e.g. theme style.css). It also applies the same pattern in detect_wp_project.mjs (project triage), which is where we hit this in practice.

Starting here to keep the change minimal.

bgrgicak

Thanks @richtabor!

… security Merges the six commits WordPress/agent-skills trunk was ahead by: - ac16175 Add wp-env skill for local WordPress development (WordPress#38) - ad58e37 Add plugin security guidance for escaping and AJAX (WordPress#63) - f2f6af2 Fix Plugin/Theme header detection in PHP docblocks (WordPress#103) - e9c58d5 Adding reference to webMCP at Playground Skill (WordPress#105) - 9f4a603 chore: refresh upstream indices (WordPress#92) - f1bac1f Add repository-wide CODEOWNERS for agent-skills maintainers (WordPress#108) Conflict resolutions: shared/references/wordpress-core-versions.json Kept ours. api.wordpress.org/core/version-check/1.7 reports 7.1.2 (checked 2026-09-27); upstream's WordPress#92 snapshot stops at 7.1.1. The Gutenberg index merged cleanly: both sides already carry v24.0.0, and v24.1.0 is still at rc.1. skills/wp-project-triage/scripts/detect_wp_project.mjs Kept ours. The fork already fixed WordPress#103's bug with `^[\s*#]*`, which matches every header line upstream's `^\s*\*?\s*` does, plus `#`-led lines. The detect_plugins.mjs half of WordPress#103 merged cleanly; the fork had not fixed that file. Both detectors now report docblock, bare, and non-plugin fixtures correctly. skills/wp-playground/SKILL.md Kept the fork's frontmatter (Use-when opener, 6.9 floor, GPL license) and folded WordPress#105's "WebMCP site tools" into the description. Took WordPress#105's browser-workflow routing bullet in the fork's markdown-link style; it also drops the "Blueprint Editor" claim, which website.md never covered. Clean merges: website.md now routes existing-site work to the new webmcp.md, mcp.md, and sites-api.md references (the WebMCP tool names match packages/playground/mcp in WordPress/wordpress-playground); security.md gains escaping contexts and AJAX handler rules. wp-env arrives exactly as upstream wrote it and is conformed and corrected in the next commit. CODEOWNERS names @WordPress/agent-skills-maintainers, which does not resolve in this fork; kept for tree parity with upstream. The harness is not expected to pass at this commit: wp-env is not yet in the skill inventory and skills/ changed without a version bump. The follow-up commits close both. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Ships the upstream merge and the corrections that followed it: the new wp-env skill (upstream WordPress#38), checked against @wordpress/env 11.16.0 and routed from wordpress-router; WebMCP, Playground MCP, and Sites API routing for wp-playground (WordPress#105); plugin escaping and AJAX guidance (WordPress#63); and the docblock plugin-header fix in detect_plugins.mjs (WordPress#103). The release-conformance gate requires a bump whenever skills/ changes after the last version change, and nine skill files changed since 1.11.0. A new skill makes this a minor release. The manifests now list wp-env. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Copilot AI lite review requested due to automatic review settings September 7, 2026 18:47

richtabor force-pushed the fix/docblock-plugin-header-detect branch from 54a3046 to 563690e Compare September 7, 2026 18:47

Copilot started reviewing on behalf of richtabor September 7, 2026 18:48

View session

richtabor force-pushed the fix/docblock-plugin-header-detect branch from 563690e to a59bbde Compare September 7, 2026 18:48

Copilot AI reviewed Sep 7, 2026

View reviewed changes

richtabor requested a review from jonathanbossenger September 7, 2026 20:44

bgrgicak approved these changes Sep 22, 2026

View reviewed changes

bgrgicak merged commit f2f6af2 into trunk Sep 22, 2026
4 checks passed

bgrgicak deleted the fix/docblock-plugin-header-detect branch September 22, 2026 05:45

Navigation Menu

Repository navigation

Fix Plugin/Theme header detection in PHP docblocks - #103

Fix Plugin/Theme header detection in PHP docblocks#103
bgrgicak merged 1 commit into
trunkfrom
fix/docblock-plugin-header-detect

richtabor commented Sep 7, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Sep 7, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

richtabor commented Sep 7, 2026

Uh oh!

richtabor commented Sep 7, 2026 •

edited

Loading

Uh oh!

bgrgicak left a comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

richtabor commented Sep 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Before

After

Files

Verification (local fixtures)

Uh oh!

github-actions Bot commented Sep 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

richtabor commented Sep 7, 2026

Uh oh!

richtabor commented Sep 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bgrgicak left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

richtabor commented Sep 7, 2026 •

edited

Loading

github-actions Bot commented Sep 7, 2026 •

edited

Loading

richtabor commented Sep 7, 2026 •

edited

Loading