fix(gate-14): stop flattening namespaced route names; understand a DI-bound fully-qualified controller

[rubenvdlinde]

What this fixes

gate-14 route-reachability reported 6 findings on opencatalogi origin/development (9e63d9f3), all false:

lib/Controller/OCAOpenCatalogiAppHostControllerGenericDashboardController.php route='OCAOpenCatalogiAppHostControllerGenericDashboard#catchAll' rule=controller-class-not-found
… same for GenericDashboard#page, GenericHealth#index, GenericMetrics#index, GenericPreferences#getPreference, GenericPreferences#setPreference

Two defects, stacked. The outer one hid the inner one.

1. read without -r — every namespaced route name was flattened

Both route gates read appinfo/routes.php through while IFS='#' read ctrl method. read performs backslash removal, so

route name in the file	what the resolver actually received
OCA\OpenCatalogi\AppHost\Controller\GenericDashboard	OCAOpenCatalogiAppHostControllerGenericDashboard
Settings\LlmSettings	SettingsLlmSettings

$ printf 'OCA\\Foo\\Bar#page\n' | while IFS='#' read    a b; do echo "[$a]"; done
[OCAFooBar]
$ printf 'OCA\\Foo\\Bar#page\n' | while IFS='#' read -r a b; do echo "[$a]"; done
[OCA\Foo\Bar]

Consequence: _ctrl_path_from_name's Settings\Foo -> lib/Controller/Settings/FooController.php branch — documented since the day it was written — had never once been reached from either gate. openregister's 55 Settings\… routes all resolved to non-existent flattened paths.

2. A fully-qualified route name was not a shape any helper understood

Un-flattened, opencatalogi's names are FQCNs under the app's own namespace, bound in lib/AppInfo/Application.php:

// appinfo/routes.php
['name' => 'OCA\OpenCatalogi\AppHost\Controller\GenericDashboard#page', 'url' => '/', 'verb' => 'GET'],

// lib/AppInfo/Application.php
$context->registerService(
    'OCA\\OpenCatalogi\\AppHost\\Controller\\GenericDashboardController',
    static fn ($c) => new GenericDashboardController(appName: self::APP_ID, request: $c->get('OCP\\IRequest'))
);

That binding is the only thing that can make the route work. From /var/www/html/lib/private/AppFramework/App.php in a live NC 33 container (docker exec procest-cilocal-nc awk '/public static function main/,/^\t}/' …):

// first try $controllerName then go for \OCA\AppName\Controller\$controllerName
try {
    $controller = $container->get($controllerName);
} catch (QueryException $e) {
    if (str_contains($controllerName, '\\Controller\\')) {
        // This is from a global registered app route that is not enabled.
        [/*OC(A)*/, $app, /* Controller/Name*/] = explode('\\', $controllerName, 3);
        throw new HintException('App ' . strtolower($app) . ' is not enabled');
    }
    …
    $controllerName = $appNameSpace . '\\Controller\\' . $controllerName;

The literal lookup happens first, and for a name containing \Controller\ the fallback does not rewrite anything — it throws. RouteParser::buildControllerName() only does underScoreToCamelCase(ucfirst($controller)) . 'Controller', so the backslashes reach the container untouched.

Neither existing helper could see this, each for its own correct reason:

• _apphost_serves is keyed on the five short slugs Bootstrap::register() aliases (dashboard). The route name is the whole class.
• _di_binds_controller takes a file path and rebuilds <app_ns>\Controller\… from it. Fed the flattened name it reconstructed OCA\OpenCatalogi\Controller\OCAOpenCatalogiAppHostControllerGenericDashboardController, which matches nothing.

The change

• read -r in gate-5 and gate-14.
• _ctrl_path_from_name maps a name fully qualified under the app's own namespace to its PSR-4 path (OCA\<App>\ → lib/), so a leaf that genuinely ships such a class is opened and judged rather than being unresolvable. It also now turns every namespace separator into a path separator, not just the last — AppHost\Controller\GenericHealth used to produce lib/Controller/AppHost\Controller/GenericHealthController.php, a path with a literal backslash that can never exist.
• New _di_binds_fq_controller, sharing the needle matcher with _di_binds_controller through a new _app_php_binds_class. The _HYDRA_DI_NEEDLE environment technique is preserved verbatim (awk -v runs escape processing and silently destroys the \\ pairs).

What still FAILS — the invariant is intact

Not a wildcard, and not "a route name with backslashes is unverifiable, skip it" — that would retire reachability for every namespaced route in the fleet, silently. The evidence demanded is exactly what _di_binds_controller already demands: the exact escaped literal within a few lines of a registerService/registerServiceAlias call in lib/AppInfo/Application.php.

An unbound fully-qualified route still fails, and the fixture proves it:

lib/AppHost/Controller/GenericGadgetController.php route='OCA\Fixture\AppHost\Controller\GenericGadget#run' rule=controller-class-not-found

Also scoped to the app's own namespace on purpose: OCA\SomeOtherApp\… is a class this repo does not own and cannot vouch for, so it is left to fail.

Measured before / after — full-tree

opencatalogi origin/development (9e63d9f3) — 64 gate verdicts captured on both arms and diffed; after normalising the per-run /tmp/hydra-gates.XXXX log-dir token, exactly one line differs:

before: [gate-14] route-reachability: FAIL — 6 unrouted method(s) or wrong-target route(s) — see LOGDIR/hydra-gate-route-reachability.log
after:  [gate-14] route-reachability: PASS

gate-5 stays PASS on both arms with the same 6 NOT-JUDGED entries; only their stated reason improves, from … is not present in this repository; controller class UNRESOLVED to served by the OpenRegister AppHost generic controller (ADR-040). Runner exit code 12 → 11.

Fleet, same A/B (origin/main worktree vs this branch):

repo	gate-14 before	gate-14 after
opencatalogi	FAIL — 6	PASS
hermiq	FAIL — 6	PASS
openregister	FAIL — 53	FAIL — 2

openregister's remaining 2 are a different, still-open false positive (see below). gate-5 on openregister goes 11 → 12 findings — both arms already FAIL, and the extra one is a true finding the gate was blind to because the name was flattened:

lib/Controller/Settings/FileSettingsController.php:323 method=getFileExtractionStats rule=missing-auth-attribute

Can-fail proof

hydra-gates/scripts/lib/test_gate_fq_route_names.sh (13 assertions, auto-discovered by tests/run-helper-suites.sh) with both arms: fq-bound → gate-14 PASS, fq-unbound → gate-14 FAIL.

Stashing only the run-hydra-gates.sh change and re-running the new suite — exit code read directly, not through a pipe:

$ git stash push -- hydra-gates/scripts/run-hydra-gates.sh
$ bash hydra-gates/scripts/lib/test_gate_fq_route_names.sh; echo "EXIT=$?"
FAIL — fq-bound: DI-bound fully-qualified routes are not reachability findings — wanted PASS, got: [gate-14] route-reachability: FAIL — 4 unrouted method(s) or wrong-target route(s)
FAIL — fq-bound: a FLATTENED route name (OCAFixture…) reappeared — read -r regressed
FAIL — fq-bound: Settings\Widget resolves to lib/Controller/Settings/, not the flattened path — unexpected log line: lib/Controller/SettingsWidgetController.php route='SettingsWidget#show' rule=controller-class-not-found
FAIL — fq-bound: gate-5 states the DI-bound generic was NOT JUDGED rather than dropping it — …
FAIL — fq-unbound: gate-14 names the unbound class at its PSR-4 path, with the route name intact — … log was: lib/Controller/OCAFixtureAppHostControllerGenericDashboardController.php route='OCAFixtureAppHostControllerGenericDashboard#catchAll' rule=controller-class-not-found|…
FAIL — fq-unbound: the DI-bound GenericDashboardController is NOT reported alongside the unbound one
FAIL — fq-unbound: the DI-bound GenericHealthController is NOT reported alongside the unbound one
FAIL — fq-unbound: a Settings\ route whose method is absent is reported as method-not-found, not class-not-found
FAIL — fq-unbound: expected 2 findings, got 6
== summary ==
   passed: 4
   failed: 9
EXIT=1

The positive-control arm goes red for the right reason: rule=controller-class-not-found on the bound fixture, on flattened OCAFixture… names — the exact opencatalogi shape. With the change restored it is 13/13 green.

Regression harness, all read directly:

bash hydra-gates/tests/run-helper-suites.sh   -> EXIT=0   (28 passed, 2 quarantined, 0 failed)
bash hydra-gates/tests/test-hydra-gates-bin.sh -> EXIT=0
bash hydra-gates/scripts/lib/test_gate_route_auth.sh -> EXIT=0 (30/30, unchanged)

Known remaining false positive — NOT fixed here

openregister names two routes with a relative namespace and binds them verbatim:

// appinfo/routes.php
['name' => 'AppHost\Controller\GenericHealth#index',  …]
// lib/AppInfo/Application.php
$context->registerService('AppHost\\Controller\\GenericHealthController', …);

_di_binds_fq_controller is deliberately scoped to OCA\<App>\…, so these two are still reported. They were reported before this PR too (as part of the 53), so this is not a regression — but it is the same class of defect one step over, and it wants a decision rather than a silent widening. Flagging rather than fixing.