chore: scaffold plugin entrypoint and tooling

[justlevine]

What

This PR scaffolds the plugins tooling and development/test environment. More specifically:

• phpcs with VIPCS + Slevomat + Plugin Check rulesets
• phpstan level 8
• phpunit running on wp-env with codecoverage.
• prettier running via @wordpress/scripts

CI/CD has been set up:

• test.yml - for PR linting/testing. Includes annotations + artifacts for human + 🤖 review
• copilot-setup-steps.yml for agentic developer environment.

Additionally, the root-level ./abilities-api.php was created with the requisite plugin headers for activation, as well as some other standard config files.

Note

This PR is based on #3 solely so there is code to test this PR against. However, we can easily rebase and apply this first if we want to get our tooling in place.
As a result there are some incongruencies with decision made in #3. Those differences are not important unless explicitly mentioned later

Why

Minimum PHP v7.4

Regardless of when it comes to WordPress. PHP 7.4 gives us access to better and easier tooling, and a prereq for most other things we wanna do. Considering we're going the canonical route anyway until merge, it seems pointless to handcuff us at this point.

Note

For illustration, PHPCS and PHPStan are currently set to use PHP 7.2 as a minimum, just to highlight what we're already violating by writing code like we're not in the aughts.
Edit 13 Aug: Bumped to 7.4

Strict PHPCS / PHPStan Rulesets

Crossed sourced from existing WordPress/* feature/canonical plugins, with the goal to be:

• Strict: Enables both humans and 🤖 to write quality code w.o. slowing down a senior developer on the basic/unimportant.
• Autofixable: Non WPCS-required and other opinionated checks should save time and cognitive load.
• Enforcable: Runs on CI/CD with annotations for users and 🤖, so issues arent missed. As committers we can always decide to ignore a smell or instance thereof.

That said, beyond the strictness and auto-enforcement, I don't feel too strongly about the formatting smells. Figure it's easier to remove/disable a rule when we see its effects on real-world code.

V0.0.1

I'm a big believer in semver. More so in the world of 🤖 that need to be able to vectorize the relevant compatible documentation. Starting a 0.0.1 gives us time and runway to keep breaking things without making the marketers in control of WP's versioning system uncomfortable, and lets us cut a "real" 0.1.0 when we're ready for users to start playing with things / spending time on explicit bugfix releases. (For WCUS maybe?)

./abilities-api.php

I know there's been a recent push from some contributors to start using a generic plugin.php entrypoint or similar , but ultimately that's not the usual plugin convention, and it's not where 🤖 know to look without unnecessary direction. 🤷

How

• See CONTRIBUTING.md#local-setup for a full walkthrough on the different commands/tech used in this PR.

To Test

1. Load the developer environment

   # switch to node 20
   nvm use
   
   # install the npm deps
   npm install
   
   # Start the test container
   npm run wp-env start

   Now you should be able to open the dashboard at http://localhost:8888/wp-admin/ (u: admin, p: password), and see the plugin activated.

   

2. Test lint/format commands

   # Should see some PHPCS smells from `/src`
   npm run lint:php
   
   # Should see some PHPStan smells from `src
   npm run lint:php:stan
   
   # Check the diff after this command to see what gets autofixed by PHPCS
   npm run lint:php:fix
   
   # Prettier should be clean ✔️
   npm run lint:js

3. Test PHPUnit with codecoverage.

   # restart wp-env with xdebug
   npm run wp-env stop
   npm run env start -- --xdebug=coverage
   
   # Run the tests
   npm run test:php

   Check tests/output/html for the coverage report:

   

Tip

To view the CI/CD, check report from the downstream PR: https://github.com/justlevine/abilities-api/actions/runs/16850315095

Beyond the Scope

• Other repo scaffolding steps ( Issue/PR templates, SECURITY.md, etc)
• Applying fixes to existing code
• Decisions regarding: namespaces, prefixes, slugs, architecture or anything

Next Steps

• Create a codecov for this repo and add the CODECOV_TOKEN action secret to the repo.
• Decide on PHP 7.4 vs 7.2
• Decide to merge this before or after Implement server-side registry for Abilities API  #3
• Apply to https://github.com/WordPress/mcp-adapter/pull/2/files

[justlevine]

Tests are running here since I dont have repo permissions: https://github.com/justlevine/abilities-api/pull/1/checks

Need fix the paths to the generated coverage report, but other than that everything is working as expected.

[justlevine]

CI is working with annotations and coverage artifacts: https://github.com/justlevine/abilities-api/actions/runs/16843071679

[gziolo]

Overall makes sense. We need to figure out how to update the domain checks in the static analysis that is expected to land in WP core as it should use the default domain like in Gutenberg.

[gziolo]

Thank you so much for working on it!

CI is working with annotations and coverage artifacts: https://github.com/justlevine/abilities-api/actions/runs/16843071679

I see that all unit tests pass. This is great 😄

We need to agree on the minimum required PHP version, as this will broadly inform how we fix reported code quality concerns.

[gziolo]

Decide on PHP 7.4 vs 7.2
Decide to merge this before or after Implement server-side registry for Abilities API #3

I'm fine using PHP 7.4 here if that's what every repo coming from the AI team uses. It won't be that much work to update code between 7.2 and 7.4 and then the other way around when moving code to WP core.

It also makes sense to land this PR first to trunk to enable CI check so we ensure that the code we land passes all the checks, and we can enforce that through the repository configuration.

[gziolo]

I landed #3, which triggered GitHub automations, and accidentally closed this PR after the target branch got deleted 😅

I'll try to fix it by reopening and changing the base branch. However, it will likely require a rebase to remove my commits from the list of changes in this PR.

[justlevine]

@gziolo squash rebased on trunk.

Should I handle the remediations here (to make the rules/diff more revieweable) or a follow-up pr (so we can at least get this merged?)

[gziolo]

How are CI checks looking with the current state of the PR and with all the changes that landed in trunk? How much could we enforce at this stage? @emdashcodes had to duplicate unit tests setup in #6, so that's something we definitely want to have as soon as possible, enabled as a mandatory CI check.

I'm happy to land the PR in the current shape and continue with follow-up PRs, as it's a bit of a hassle at the moment. Please keep in mind that I'm not an expert in setting up PHP tooling, but it's something that members of the AI team can help to iron out later.

[Copilot]

Pull Request Overview

This PR scaffolds a comprehensive development and testing environment for the Abilities API plugin, setting up essential tooling and infrastructure. It establishes coding standards, static analysis, automated testing, and CI/CD workflows to ensure code quality and maintainability.

Key changes include:

• Development tooling setup with PHPCS, PHPStan, PHPUnit, and Prettier configurations
• CI/CD workflows for automated testing and code quality checks
• WordPress plugin structure with proper headers and entry point
• Local development environment configuration using wp-env

Reviewed Changes

Copilot reviewed 16 out of 21 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
abilities-api.php	Main plugin entry point with standard WordPress plugin headers and file includes
composer.json	PHP dependency management with dev tools for code quality and testing
package.json	Node.js dependencies and npm scripts for development workflow
phpcs.xml.dist	Comprehensive PHP coding standards configuration with WordPress, VIP, and Slevomat rules
phpstan.neon.dist	Static analysis configuration set to level 8 with WordPress-specific settings
phpunit.xml.dist	PHPUnit configuration with code coverage reporting setup
tests/bootstrap.php	PHPUnit test bootstrap file for WordPress integration
.wp-env.json	Local development environment configuration for wp-env
.github/workflows/test.yml	CI/CD workflow for running PHPCS, PHPStan, and PHPUnit tests
.github/workflows/copilot-setup-steps.yml	GitHub Copilot integration workflow for development environment setup

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[justlevine]

@gziolo PHPUnit is working, feel free to trigger the CI on this PR to see or check on https://github.com/justlevine/abilities-api/actions/runs/16938522056/job/48001025979?pr=1

Follow-up PRs to address the PHPStan/PHPCS smells inbound

[gziolo]

Let's get this in and continue refinements in the follow-up PR so we can start using unit test integration with CI.

[gziolo]

Unit tests pass on trunk, but static checks need more work:

[gziolo]

Landed another follow-up:

• Adjust directory structure to align with WP core #12

There is only one issue left which is probably tricky to enforce with the PHP support matrix we have:

When I add type hint mixed there is a different error reported:

I would appreciate some help here. That's the last CI job that fails and therefore is optional, everything else is now required to pass before merging the PR 🎉

[gziolo]

One additional note. CI checks don't run on trunk for some reason:

[justlevine]

Great work - I'll take a look when I start my morning at the rest of those!

[gziolo]

I opened issue to make it easier to coordinate remaining tasks:

• Scaffold repository tooling #13

I still need check config files and list exceptions used so we can decide whether to keep them or harden checks.