Guidance for coding agents working in this repository. CLAUDE.md imports this file, so Claude Code, Codex and anything else that reads AGENTS.md all get the same instructions — keep this file self-contained and edit it here rather than adding a second copy.
WordPress plugin (Equalize Digital) for in-post accessibility scanning and WCAG auditing, powered by axe-core with custom rules. Free version on WordPress.org; Pro adds features.
- PHP ≥ 7.4 — no PHP 8-only syntax. WP minimum: see
readme.txt. - Text domain:
accessibility-checker - Namespaces: PSR-4
EqualizeDigital\AccessibilityChecker\→includes/classes/,…\Admin\→admin/. Legacy classmap:admin/,includes/classes/,includes/deprecated/. Main class:EDAC\Inc\Plugin(includes/classes/class-plugin.php). - Prefixes: constants
EDAC_/EDACP_; hooks, options, globalsedac_/edacp_(pro). Never add unprefixed ones. - Pro gating:
edac_is_pro()— requiresEDACP_VERSIONdefined andEDAC_KEY_VALIDdefined + truthy (set from theedacp_license_statusoption).
npm run build | dev # webpack prod / watch
npm run lint # phpcs + eslint + stylelint (all three)
npm run lint:php[:fix] # phpcs / phpcbf
npm run lint:js[:fix] # wp-scripts eslint
npm run lint:css[:fix] # wp-scripts stylelint
npm run phpstan
npm run test:jest
npm run test:php # set up docker WP test env (once/refresh)
npm run test:php:run # run PHPUnit in container
npm run test:php:coverage # PHPUnit with clover + html coverage
npm run test:php:stop
docker compose exec phpunit vendor/bin/phpunit --filter <name> # single test
npm run dist # distribution zip (swaps composer to no-dev; don't run casually)
composer generate-hooks-docs # regenerate docs/hooks.md
composer lint # parallel-lint syntax checknpm install runs postinstall → patch-package && ./scripts/prepare.sh.
accessibility-checker.php— constants, composer autoload,new Plugin(), requires legacy procedural files inincludes/(helper-functions.php,options-page.php, …). Admin vs frontend split viais_admin(). Also definesedac_register_rules().includes/classes/—Rules/,Fixes/,Blocks/,Capabilities/,Shortcodes/,MyDot/,SystemInfo/,WPCLI/, plus legacyclass-*.phpat the top level (class-plugin.php,class-rest-api.php,class-summary-generator.php,class-simplified-summary.php,class-admin-toolbar.php,class-enqueue-frontend.php,class-lazyload-filter.php,class-accessibility-statement.php).admin/— legacyclass-*.php=EDAC\Admin; PSR-4 CamelCase =EqualizeDigital\…\Admin\. Subdirectories:AdminPage/,site-health/,opt-in/,css/,js/.partials/— PHP templates.src/→ webpack →build/, one bundle per entry:admin,editorApp,pageScanner(scan engine),frontendHighlighterApp,frontendFixes,emailOptIn,sidebar,issueModal,sharedComponents,srOnlyFormat,simplifiedSummaryBlock.src/common/holds shared code but is not itself an entry.@wordpress/*packages are externalized inwebpack.config.js.
Rules run client-side via a customized axe-core scan (src/pageScanner). Each rule has a JS rule definition, one or more JS checks, and a PHP Rule class carrying the user-facing metadata (title, summary, how-to-fix, WCAG mapping, severity).
edac_register_rules()→RuleRegistry::load_rules()(loads everything inRules/Rule/, each aRuleInterface), filterable byedac_filter_register_rules.- Fixes register on
plugins_loadedpriority 20; code adding fixes must hook below 20. - A JS rule's
idmust equal its PHP ruleslug, exactly — otherwise results never map to the metadata. IDs aresnake_case; filenames arekebab-case.
Adding a rule example_rule touches five places:
src/pageScanner/rules/example-rule.js— default-exports an axe rule object:id,selector,excludeHidden,tags,all/any/none,metadata.src/pageScanner/checks/example-check.js— default-exports{ id, evaluate( node ) }.evaluateruns per matched node on every scan, so keep it fast and hoist constant lookups out of loops.src/pageScanner/config/rules.js— import both, add the rule torulesArrayand the check tochecksArray.customRuleIdsArrayderives fromrulesArray; stock axe-core rules live instandardRuleIdsArrayinstead.includes/classes/Rules/Rule/ExampleRule.php— implementsRuleInterfacewith staticget_rule(): array. Copy an existing rule (e.g.ImgAltEmptyRule.php) for the exact shape. Key fields:slug(= the JSid),rule_type(error/warning),ruleset => 'js',wcag,severity(1–4, lower = more severe),affected_disabilities(constants fromAffectedDisabilities), plustitle,summary,summary_plural,why_it_matters,how_to_fix,references,info_url.includes/classes/Rules/RuleRegistry.php— add the class to the$rule_classesarray.
Then: Jest tests in tests/jest/rules/ — one file per rule, importing the rule from ../../../src/pageScanner/rules/<rule>.js and its check file or files from ../../../src/pageScanner/checks/ by their actual paths. Do not derive the check name from the rule: most don't match (possible-heading.js uses checks/paragraph-styled-as-header.js) and one rule can use several checks. Checks have no test directory of their own; a check is covered through its rule's test. Cover both fixtures that should flag and ones that should pass — false-positive regressions are the common failure here. Name the file in camelCase after the rule file you changed (src/pageScanner/rules/img-alt-empty.js → tests/jest/rules/imgAltEmpty.test.js). Not every existing rule test matches its source file name, so never infer coverage from a filename match. tests/phpunit/RegisterRulesTest.php validates rule definitions if you touched PHP metadata. npm run build before the rule appears on a running site.
Fixable issues are a separate system: includes/classes/Fixes/ (FixesManager, FixInterface) plus front-end JS in src/frontendFixes/. A rule does not need a fix.
- PHP: WPCS + WordPress-VIP-Go (
phpcs.xml). Tabs. Full docblocks. New classes: PSR-4 CamelCase; register hooks ininit()/init_hooks(), never in constructors (legacy violators exist — don't copy, don't refactor unprompted). - JS:
@wordpress/eslint-plugin. Tabs. React insidebar/,issueModal/,sharedComponents/. - i18n: every user-facing string translatable,
accessibility-checkerdomain, escaped on output;// translators:comment on every sprintf placeholder. JS:wp.i18n. - UI must meet WCAG 2.1 AA: focus management, keyboard nav, ARIA, semantic HTML.
Which checks apply:
| Change | Run |
|---|---|
JS in src/ |
npm run test:jest, npm run lint:js |
| CSS/SCSS | npm run lint:css |
| PHP anywhere | PHPUnit (docker), npm run lint:php, npm run phpstan |
| Rule metadata (PHP Rule classes) | PHPUnit RegisterRulesTest, plus Jest if the JS side changed |
| Hooks added/renamed | composer generate-hooks-docs — verify-hooks-docs.yml runs it weekly and opens a PR if docs/hooks.md is stale; no check fails |
- PHPUnit runs in docker against the WP test suite:
npm run test:phponce to set up, thentest:php:run,test:php:stop. Tests intests/phpunit/; PSR-4 helpers underEqualizeDigital\AccessibilityChecker\Tests\TestHelpers\. - Jest config at
tests/jest/jest.config.js.@wordpress/*imports need explicitmoduleNameMapperentries — a missing one surfaces as "Cannot find module '@wordpress/…'", and the mapper regexes must be anchored to avoid subpath mismatches. - Jest tests live beside their area:
tests/jest/rules/(pageScanner rules),tests/jest/pageScanner/(context.test.jsandhelpers/), and same-named directories for the othersrc/entries —admin,emailOptIn,frontendFixes,frontendHighlighterApp,issueModal,sharedComponents,simplifiedSummaryBlock. Shared helpers and fixtures:tests/jest/helpers/,tests/jest/utils/,tests/jest/__mocks__/,tests/jest/mock-assets/.testMatchis**/*.test.js. - E2E: Playwright specs in
tests/e2e/run against WordPress Playground (npm run test:e2e; needs Chrome, Node 22/24, and a freshnpm run build). CI runs them only via the manuale2e-tests.ymlworkflow. Seetests/e2e/README.md. - Bug fixes need a regression test. Run the checks covering your change before pushing.
- CI mirrors local:
phpunit.yml,jest-tests.yml,lint-php.yml,lint-js.yml,cs.yml,code-coverage-and-coveralls.yml,verify-hooks-docs.yml,deploy-on-release-*. If CI fails where local passed, check the PHP-version matrix first —verify-hooks-docs.ymlonly opens a PR, so it can never be the red job.
- Base branch for feature/fix PRs:
develop(notmain). Releases go throughrelease/x.y.zbranches. - Branch names:
<firstname>/<linear-id>-<kebab-slug>for Linear-tracked work,<firstname>/no-issue/<slug>otherwise. Automation usesautomation/…orclaude/…. - Conventional commits (
fix:,feat:,perf:,refactor:,chore:,docs:,test:). Imperative, lower-case after the prefix, no trailing period. - PR title when Linear-tracked:
PRO-1234: fix: <description>. Fill in the checklist in.github/PULL_REQUEST_TEMPLATE.md— link the issue and cover the change with tests. - Wait for CI to go green, CodeRabbit's check included, before treating a PR as review-ready.
- Review comments: reply to each one you act on with the commit hash and a one-line description of the fix. Disagree in a reply with reasoning rather than silently. Never resolve a thread without a reply.
- Commit lock files only when changing dependencies.