Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions .claude/skills/scaffold/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -164,15 +164,15 @@ For block scaffolds, surface a developer action before testing: "run `npm run bu
| D | Re-run. Confirm that one test passes. |
| E | Loop B-D one test at a time. |
| F | Once green, refactor; re-run. |
| G | Final gates - all must pass: full PHPUnit suite (`npm run test:php`), full Jest suite if JS touched (`npm run test:js`), `composer format` (phpcbf), `composer lint` (phpcs), `composer phpstan` (PHPStan level 5), `npm run lint:js`. Never silence a real phpcs/phpstan finding with a blanket ignore; fix it, or escalate (§8). |
| G | Final gates - all must pass: full PHPUnit suite (`npm run test:php`), full Vitest suite if JS touched (`npm run test:js`), `composer format` (phpcbf), `composer lint` (phpcs), `composer phpstan` (PHPStan level 5), `npm run lint:js`. Never silence a real phpcs/phpstan finding with a blanket ignore; fix it, or escalate (§8). |

Frameworks per kind:

| Kind | Framework |
|---|---|
| `wp/cpt`, `wp/taxonomy`, `wp/cron`, `wp/cli`, `wp/rest`, `wp/shortcode`, `wp/admin-page`, `wp/settings-page`, `wp/user-role`, `wp/registrable` | PHPUnit |
| `wp/block-dynamic` | Jest (edit.js) + PHPUnit (render method) |
| `block/interactive` | Jest + Playwright |
| `wp/block-dynamic` | Vitest + React Testing Library in `test/*.jsdom.test.jsx` + PHPUnit (render method) |
| `wp/block-interactive` | Vitest + Playwright |
| `ci/*` | actionlint + yaml-parse |

### 8. Escalate when stuck - do not guess
Expand Down
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/bug.yml
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ body:
- "Modules and examples (inc/Modules/)"
- "Core services (inc/Core/)"
- "Blocks and assets (src/, webpack, HMR, Tailwind)"
- "Tests and lint (PHPUnit, Jest, PHPCS, PHPStan, ESLint, Stylelint)"
- "Tests and lint (PHPUnit, Vitest, PHPCS, PHPStan, ESLint, Stylelint)"
- "CI workflows"
- Documentation
- Not sure
Expand Down
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/feature.yml
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ body:
- "Modules and examples (inc/Modules/)"
- "Core services (inc/Core/)"
- "Blocks and assets (src/, webpack, HMR, Tailwind)"
- "Tests and lint (PHPUnit, Jest, PHPCS, PHPStan, ESLint, Stylelint)"
- "Tests and lint (PHPUnit, Vitest, PHPCS, PHPStan, ESLint, Stylelint)"
- "CI workflows"
- "AI tooling (AGENTS.md, Claude skills, Copilot prompts)"
- Documentation
Expand Down
16 changes: 16 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,22 @@ updates:
prefix: build
include: scope
versioning-strategy: increase
groups:
# Mixed releases install duplicate copies, which break the block tests.
# @wordpress/theme follows @wordpress/stylelint-config's peer range instead.
wordpress:
patterns:
- '@wordpress/*'
exclude-patterns:
- '@wordpress/theme'
react:
patterns:
- react
- react-dom
vitest:
patterns:
- vitest
- '@vitest/*'
labels:
- Dependencies

Expand Down
2 changes: 1 addition & 1 deletion .github/labels.yml
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,7 @@
description: "Documentation"
- name: "Scope: Tests"
color: "BFDADC"
description: "PHPUnit and Jest suites"
description: "PHPUnit and Vitest suites"

# release-please adds "autorelease: pending" to its release pull request and
# finds the merged one to tag by it, then swaps it for "autorelease: tagged".
Expand Down
2 changes: 1 addition & 1 deletion .github/prompts/scaffold.prompt.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ Apply project-sampled conventions (class suffix, sub-namespace, vendor prefix, b
- `ai.wiring`: for each snippet, place after its anchor (or last sampled occurrence), show file + line + rendered snippet, get consent, insert idempotently.

### 7. TDD loop (mandatory)
Tests before implementation, no exceptions. A. Expand the engine stub into the full suite from §4; strip every `markTestIncomplete`. B. Run `composer test` (PHP) / `npm run test:js` (JS); expect red. C. Implement just enough to flip ONE test green. D. Re-run. E. Loop B-D one test at a time. F. Refactor, re-run. G. Final gates: full PHPUnit, full Jest if JS touched, PHP compliance (§7a), `npm run lint:js`. For blocks, surface `npm run build` as a developer action before testing.
Tests before implementation, no exceptions. A. Expand the engine stub into the full suite from §4; strip every `markTestIncomplete`. B. Run `composer test` (PHP) / `npm run test:js` (JS); expect red. C. Implement just enough to flip ONE test green. D. Re-run. E. Loop B-D one test at a time. F. Refactor, re-run. G. Final gates: full PHPUnit, full Vitest if JS touched, PHP compliance (§7a), `npm run lint:js`. For blocks, surface `npm run build` as a developer action before testing. Name editor tests `test/*.jsdom.test.jsx`.

### 7a. PHP compliance (required, on changed PHP)
Write compliant PHP up front (`declare( strict_types = 1 );`, short arrays, full types, prefixed globals, `@package`/`@since`, `static::`). Then: `composer format` (phpcbf) → `composer lint` (phpcs, `rtCampWP` ruleset) → `composer phpstan` (level 5). Resolve every finding in the generated code. Never silence a real issue with a blanket `phpcs:ignore`/`@phpstan-ignore`; if a fix is unclear or changes behaviour/API, STOP and ask.
Expand Down
3 changes: 3 additions & 0 deletions .github/workflows/test-measure.yml
Original file line number Diff line number Diff line change
Expand Up @@ -38,5 +38,8 @@ jobs:
test-php-exclude: '[]'
lint-js-files-command: npm run lint:js:files
lint-css-files-command: npm run lint:css:files
# The defaults add Jest's --ci and --cacheDirectory, which Vitest rejects.
test-js-command: npm run test:js
test-js-cache: false
# No tokens: every rtCamp dependency is public and the shared workflow falls
# back to GITHUB_TOKEN. A PAT here breaks all dist downloads once it expires.
2 changes: 1 addition & 1 deletion .lintstagedrc.js
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
module.exports = {
'**/*.php': [ 'npm run lint:php' ],
'**/*.js': [ 'npm run lint:js:files' ],
'**/*.{js,jsx}': [ 'npm run lint:js:files' ],
'**/*.{css,scss}': [ 'npm run lint:css:files' ],
'package.json': [ 'npm run lint:package-json' ],
};
1 change: 1 addition & 0 deletions .stylelintrc.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
"extends": "@rtcamp/stylelint-config",
"ignoreFiles": [
"**/*.js",
"**/*.jsx",
"**/*.json",
"**/*.php"
],
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,7 @@ inc/ # PSR-4 root: Project_Name\Features\ → inc/
└── Cache/ Transients/
src/{blocks,css,js}/ # editable sources → assets/build/ (generated)
templates/ # theme-overridable PHP templates
tests/{php,js}/ # PHPUnit (mirrors inc/) and Jest
tests/{php,js}/ # PHPUnit (mirrors inc/) and Vitest
bin/ # init wrapper, scaffold config, block scaffolder, helper scripts
docs/ # these guides; docs/internal/ is for skeleton maintainers
.github/ # CI caller, issue/PR templates, Copilot instructions and prompts
Expand Down
19 changes: 12 additions & 7 deletions bin/block-scaffold/block.js
Original file line number Diff line number Diff line change
Expand Up @@ -223,15 +223,20 @@ const getBlockTemplateFiles = ( blockDirName ) => {
const copyTemplateFiles = ( blockDirName, blockPath, blockFiles ) => {
try {
const blockDir = `${ blockPath }/${ blockDirName }`;
if ( ! fs.existsSync( blockDir ) ) {
fs.mkdirSync( blockDir );
if ( fs.existsSync( blockDir ) ) {
console.log(
info.error(
`${ blockDir } already exists. Choose another slug.`
)
);
return process.exit( 1 );
}
fs.mkdirSync( blockDir );
for ( const file of blockFiles ) {
const fileName = path.basename( file, '.mustache' );
const filePath = `${ blockDir }/${ fileName }`;
if ( ! fs.existsSync( filePath ) ) {
fs.copyFileSync( file, filePath );
}
fs.copyFileSync(
file,
`${ blockDir }/${ path.basename( file, '.mustache' ) }`
);
}
return blockDir;
} catch ( err ) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ import save from './save';
*/
registerBlockType( '{{namespace}}/{{slug}}', {
/**
* @see ./edit.js
* @see ./edit.jsx
*/
edit: Edit,
/**
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ import Edit from './edit';
*/
registerBlockType( '{{namespace}}/{{slug}}', {
/**
* @see ./edit.js
* @see ./edit.jsx
*/
edit: Edit,
/*
Expand Down
4 changes: 2 additions & 2 deletions bin/block-scaffold/templates/static-block/index.js.mustache
Original file line number Diff line number Diff line change
Expand Up @@ -30,11 +30,11 @@ import save from './save';
*/
registerBlockType( '{{namespace}}/{{slug}}', {
/**
* @see ./edit.js
* @see ./edit.jsx
*/
edit: Edit,
/**
* @see ./save.js
* @see ./save.jsx
*/
save,
} );
2 changes: 1 addition & 1 deletion docs/features.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ These stay in every project, whichever example sets you remove. Most are thin pl
| Encryption | `inc/Core/Encryption.php`, `Util::encryption()` | `Encryptor` ([utilities](https://github.com/rtCamp/wp-primitives/blob/v2.0.0/docs/utilities.md#encryptor)) | Define `ACME_CONTENT_FEATURES_ENCRYPTION_KEY` in `wp-config.php` first; without it, calls throw. `Util::encryption()->encrypt( $secret )` / `->decrypt()`. |
| Activation and i18n | `inc/Core/PluginSetup.php` | `Registrable` | Stores `acme_content_features_version` on activation, unschedules the example cron job on deactivation, loads the text domain from `languages/`. |
| Helpers | `inc/Helpers/Util.php` | — | Accessors for the shared services above, plus `get_data()` (reads `inc/data/<slug>.php`), `is_production()` and `is_mobile()`. |
| Quality checks | `tests/`, `phpcs.xml.dist`, `phpstan.neon.dist`, `eslint.config.mjs`, `.stylelintrc.json` | Shared `rtcamp/wp-phpcs`, `rtcamp/wp-phpstan`, `@rtcamp/eslint-config`, `@rtcamp/stylelint-config` | PHPUnit (one test per module), PHPCS, PHPStan level 5, ESLint, Stylelint, Jest. See [Check a change](local-development.md#check-a-change). |
| Quality checks | `tests/`, `phpcs.xml.dist`, `phpstan.neon.dist`, `eslint.config.mjs`, `.stylelintrc.json` | Shared `rtcamp/wp-phpcs`, `rtcamp/wp-phpstan`, `@rtcamp/eslint-config`, `@rtcamp/stylelint-config` | PHPUnit (one test per module), PHPCS, PHPStan level 5, ESLint, Stylelint, Vitest. See [Check a change](local-development.md#check-a-change). |

The shared services (`Assets`, `Templates`, `Components`, `Logger`, `Encryption`) implement `Shareable`, so the `Loader` keeps one instance in `Main`'s container. Why that is preferred over singletons is explained in the framework's [sharing vs. singletons](https://github.com/rtCamp/wp-primitives/blob/v2.0.0/docs/architecture.md#sharing-vs-singletons).

Expand Down
5 changes: 3 additions & 2 deletions docs/internal/maintenance.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,10 +99,11 @@ The release pull request is opened with `GITHUB_TOKEN`, so GitHub starts no work
| --- | --- | --- |
| `rtcamp/wp-primitives` | `composer.json` (`^2.0`), `composer.lock` | Run `composer update rtcamp/wp-primitives -W`, then `npm run sync-ai` to refresh the generated instructions. Update every pinned docs link (`grep -rn "wp-primitives/blob/v" README.md DEVELOPMENT.md docs`) to the new tag, and review the framework's changelog for anything the examples or docs must follow. |
| `@rtcamp/wp-tooling`, lint configs | `package.json` (`^` ranges on the npm registry), `package-lock.json` | Run `npm update @rtcamp/wp-tooling` (and the configs) to move the lock, then re-run init and scaffold validation. |
| `webpack-dev-server` | `package.json` (`6.0.0` in `devDependencies`, and `overrides` pointing at it) | Pinned below 6.1.0, whose client compares the dev server's combined hash from the two `--experimental-modules` compilers strictly against the page's own hash, so the block editor reloads in a loop under `npm start`. The `overrides` entry alone would nest the pin under `@wordpress/scripts`, where `webpack-cli` cannot find it, so both lines stay. Remove both once a release after 6.1.0 handles multi-compiler hashes, then check that an edit to a block's `edit.js` hot-applies without a reload. |
| `webpack-dev-server` | `package.json` (`6.0.0` in `devDependencies`, and `overrides` pointing at it) | Pinned below 6.1.0, whose client compares the dev server's combined hash from the two `--experimental-modules` compilers strictly against the page's own hash, so the block editor reloads in a loop under `npm start`. The `overrides` entry alone would nest the pin under `@wordpress/scripts`, where `webpack-cli` cannot find it, so both lines stay. Remove both once a release after 6.1.0 handles multi-compiler hashes, then check that an edit to a block's `edit.jsx` hot-applies without a reload. |
| Coding standards | `composer.json` (`rtcamp/wp-phpcs`, `rtcamp/wp-phpstan`) | `composer update rtcamp/wp-phpcs rtcamp/wp-phpstan`; fix or baseline new findings in a separate commit. |
| Shared CI | `.github/workflows/test-measure.yml` (`@v1`) | `@v1` moves to compatible v1.x releases on its own. For a new major version, move the ref and check the input names against the new `wp-ci.yml`. |
| `@wordpress/theme` | `package.json` (`4.0.0`, dev dependency) | It is there only as the peer `@wordpress/stylelint-config` needs (`^3.0.0 \|\| ^4.0.0`). `legacy-peer-deps` in `.npmrc` skips peers, so without this entry Stylelint loads the 2.3.0 the editor packages hoist and crashes reading its design tokens. The editor packages keep their own nested copies. Bump it together with `@wordpress/stylelint-config`, inside that package's peer range, and run `npm run lint:css`. |
| `@wordpress/*` packages | `package.json` (exact pins), grouped in `.github/dependabot.yml` | Keep them on one release. The JS tests import them from `node_modules`, and a second copy of `@wordpress/blocks`, `@wordpress/hooks` or `@wordpress/private-apis` breaks block registration and private-API unlocking. After a bump, run `npm dedupe`, check that `npm ls @wordpress/blocks @wordpress/private-apis` lists one version of each, and run `npm run test:js`. |
| `@wordpress/theme` | `package.json` (`4.0.0`, dev dependency) | It is there only as the peer `@wordpress/stylelint-config` needs (`^3.0.0 \|\| ^4.0.0`), and is left out of the Dependabot `@wordpress` group for that reason. `legacy-peer-deps` in `.npmrc` skips peers, so without this entry Stylelint loads the copy the editor packages hoist, outside that range (2.3.0 crashed reading its design tokens). The editor packages keep their own nested copies. Bump it together with `@wordpress/stylelint-config`, inside that package's peer range, and run `npm run lint:css`. |
| Docs builder | `.github/workflows/documentation.yml` (pinned SHA) | See [Documentation publishing](#documentation-publishing). |

Also keep the plugin header's `Tested up to` in step with the newest WordPress version in the CI matrix.
Expand Down
4 changes: 3 additions & 1 deletion docs/local-development.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ composer lint # PHPCS (rtCampWP ruleset)
composer format # PHPCBF: auto-fix what PHPCS can
composer phpstan # PHPStan level 5

# JavaScript, CSS and package.json. An initialized plugin has no Jest tests until you add one.
# JavaScript, CSS and package.json. Vitest runs tests under src/ and tests/js/; *.jsdom.test.jsx files get a DOM.
npm run test:js
npm run lint:js
npm run lint:css
Expand All @@ -76,6 +76,8 @@ npm run wp-env start -- --xdebug=coverage
npm run test:php:coverage
```

For JavaScript, `npm run test:js:coverage` writes `tests/logs/lcov.info` and an HTML report in `tests/logs/lcov-report/`.

> Use the explicit commands above rather than `npm test` or `npm run lint`. Their `test:*` / `lint:*` wildcards also match the watch, coverage and `:fix` scripts, so they neither terminate cleanly nor stay read-only. See [maintenance known gaps](internal/maintenance.md#known-gaps).

CI runs the same checks through [`.github/workflows/test-measure.yml`](../.github/workflows/test-measure.yml): lint, JS tests, the PHP × WordPress test matrix (edit `php-versions` / `wp-versions` there) and the build, each gated on which files changed. The jobs themselves live in [wp-shared-workflows](https://github.com/rtCamp/wp-shared-workflows).
Expand Down
2 changes: 1 addition & 1 deletion eslint.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
* rtCamp shared ESLint flat config.
*
* Extends @rtcamp/eslint-config (which bundles @wordpress/eslint-plugin,
* eslint-comments, and the jest config for test files). Only the
* eslint-comments, and the Vitest rules for test files). Only the
* project-specific ignores are layered on top.
*/
import rtCampConfig from '@rtcamp/eslint-config';
Expand Down
Loading
Loading