Controller Enumeration

Observed across the plugins audited to date, there are exactly two paths that together cover every layout seen in the wild:

Default order

1. Try glob first — it’s faster and produces a cleaner inventory.
2. Fall back to grep if glob returns zero hits (or clearly undercounts against what you see in the plugin’s public documentation / admin UI).

Running both and de-duplicating is legal; it catches monorepos that have some controllers under the standard layout and others under a package directory.

Glob — standard layout

What you’ll see in repos that match this convention:

• WooPayments (Automattic/woocommerce-payments) — every controller under includes/admin/class-wc-rest-payments-*-controller.php plus some under includes/reports/.
• WooCommerce core’s internal REST controllers use the same pattern.

If glob returns 5+ hits, it’s almost always the complete inventory. If it returns 0-2, fall through to grep.

Grep — universal fallback

For each hit:

1. Open the file.
2. Walk up to the enclosing class declaration.
3. Record (class, file, route, callback, permission_callback).

This path matters because it’s the only one that finds controllers in non-standard locations:

• WooCommerce Subscriptions — controllers live under includes/api/ and includes/api/legacy/. The standard WooPayments glob returns zero; grep is mandatory.
• Jetpack Forms (and most Jetpack packages) — controllers live under projects/packages/<name>/src/ with no conventional filename. Grep is again mandatory.
• Custom plugin layouts — anything with src/Rest/, lib/rest/, api/v1/, etc. Grep catches them all.

Inherited routes

A controller can extend a base class in a different repo — typically the parent plugin (for extensions built on top of another plugin) or WordPress core itself (for plugins extending WP_REST_Posts_Controller or other core REST bases). The parent::register_routes() dispatch appears in the extending plugin’s source, but the literal register_rest_route( call lives in the parent. WooCommerce extensions extending WC_REST_Orders_Controller, plugins built on Jetpack package REST classes, and CPT plugins inheriting from WP_REST_Posts_Controller all hit this pattern.

Handling:

• Record the route on the child class (that’s where the plugin’s REST surface actually exposes it).
• Set backing.route_registration_line: null and backing.callback_line: null in the audit schema.
• Add backing.inherited_from: "<parent FQCN>" so downstream skills can tell the inheritance case from a plain missing line number.
• Consider running grep against the parent repo too when you need to confirm the callback’s request handling — inherited callbacks behave as whatever the parent defines, not what the plugin repo documents.

See audit-schema.md for the exact field shapes.

Exhaustiveness is the goal

The “Controller Inventory” table in the audit doc must list every controller the enumeration found — not just ones backing proposed abilities. A reviewer asking “why isn’t controller X in the MVP?” should be able to point at the inventory and see the explicit answer (usually: “excluded from MVP because…” or “surfaced as a gap because…”).

If your inventory has 3 entries and the plugin clearly exposes more, either the enumeration is incomplete (re-run grep with broader patterns) or you’re filtering the inventory instead of the proposal list. Fix the inventory first; filter after.

Escalation

If neither glob nor grep produces a complete inventory — for example a plugin that registers routes dynamically from config or via a factory that does not contain a literal register_rest_route( string — document the enumeration gap in “Notes and Surprises”, and extend this reference with the new pattern once understood.