Skip to content

fix(hydra-gates): find controllers, services and jobs anywhere under lib/, and follow renames in gate 122 - #905

Merged
rubenvdlinde merged 7 commits into
mainfrom
fix/gates-moved-controllers-and-renames
Nov 5, 2026
Merged

rubenvdlinde merged 7 commits into
mainfrom
fix/gates-moved-controllers-and-renames

Conversation

@rubenvdlinde

Copy link
Copy Markdown
Contributor

Several hydra gates assume that controllers, services and background jobs live in lib/Controller, lib/Service and lib/BackgroundJob. openregister#5519 starts moving classes into component directories (lib/Search/<layer>/). After that move, these gates stop opening the moved classes and still print PASS. This PR makes them find those classes anywhere under lib/, and fixes the two related problems the same move exposed.

What changes

Routed controllers (gates 5, 7, 9, 14, 30, 49). A new helper, scripts/lib/controller_resolver.py, resolves every route controller name in appinfo/routes.php the way Nextcloud does: through appinfo/class-aliases.json and the PSR-4 map in composer.json. A moved controller that keeps its old route name through a class alias is now found and judged.

  • Gate 5 now fails when a routed controller is declared by no file under lib/. Before, it parked such routes as "not judged" and passed.
  • A diff that moves or deletes a controller, or changes the class aliases or composer.json, puts every route back in scope for gates 5 and 14.
  • Gates 7, 9, 14 and 49 read every Controller directory under lib/ plus the routed controllers found elsewhere.
  • Gate 30 no longer requires a lib/Controller directory.

Services and jobs (gates 3, 6, 8, 57). These read lib/<Role> plus every lib/**/<Role> directory.

The other gates with the same assumption:

  • gate 6 _is_routed: resolves the route table through controller_resolver. Before, a controller reached through an alias or a Settings\ route name was reported as an orphan.
  • gate 16 BACKEND_DIRS and gate 97's forbidden-caller list: each layer applies at lib/ and one component level down.
  • gate 25: any Controller directory under lib/, plus every resolved route target, counts as a controller.
  • gate 48: diffs controllers anywhere under lib/, with -M, so a dropped #[NoCSRFRequired] in a moved controller is still seen.
  • gate 111: also reads lib/<Component>/Service/Flow/Nodes/.

Gate 122 ratchet. The ratchet read a renamed file's added lines by its new path only, so every line of a moved file counted as new. On #5519 that produced 71 false duplicate findings. Added lines now come from a rename-aware diff against the old path. A pure move adds nothing, and an edit inside a moved file still counts.

Gate 67 contracts. contracts/EmailLinkReaderInterface.php has been on main since 29 Oct and shipped in v1.19.0, and gate 67 passes on #5519 in CI. The local failure comes from openregister's composer.lock pinning hydra-gates v1.18.0, so the fix there is a lock bump. The file was still missing from the README table, the test-bootstrap guard and the Psalm stubs. This PR adds it to all three, plus a test that keeps them in step with contracts/.

Behaviour changes to be aware of

  • Gate 5 now fails on a routed controller that no file under lib/ declares. It does so on a full run, and on a diff that touches routes, class aliases, composer.json or a controller's location. Before, it only listed such routes as not judged (the split made in gate-5 (route-auth): false positive on ADR-040 AppHost apps, and it is not diff-scoped #153). It still never counts them as a missing auth attribute, and gate 14 already failed the same routes.
  • Gate 14 invariant 1 now also opens controllers outside lib/Controller/, such as lib/AppHost/Controller/. It can therefore report unrouted Response methods there that it never saw before.

Tests

  • test_gate_component_dirs.sh (new) runs the real runner over fixture repositories. Their controller, services and job sit only under lib/Search/. It includes the failing-first case: a routed controller outside lib/Controller with no auth attribute must fail gate 5. Against the main runner it fails 22 of 25 assertions; the 3 that pass are negative guards. Against this branch it passes 25 of 25.
  • Unit tests, each failing first against main:
    • gate 122: a move adds nothing; a worsened unit or a new clone in a moved file still counts
    • controller resolver
    • gate 6: alias and Settings\ routes
    • gate 16: component scope
    • gate 25: moved endpoint
    • gate 97: new suite
    • gate 111: component node directory
    • gate 67: contracts documentation
      Full helper suite (tests/run-helper-suites.sh, 145 suites, with ajv on NODE_PATH): 143 green.
    • test_gate_a11y_helper_wiring.sh and test_gate_route_auth.sh each went red once in that loaded run. Both pass when run alone. The a11y suite also passed in the previous full run.
    • Without ajv locally, test_check_connections_declaration.js, test_gate116_connections_declaration_scope.sh and test_gate_45_to_55_acceptance.sh are red on main too. All three pass with ajv.
  • Three route suites now expect gate 5 to fail on an unfound controller: test_gate_route_auth.sh, test_gate_fq_route_names.sh and test_gate_route_registration.sh. They still assert that it is never counted as a missing auth attribute.
  • Proof against openregister#5519, --scope-to-diff --base origin/development, run with both the main runner and this branch:
    • #5519 as it is. Gate 122 goes from FAIL with 71 findings to PASS: 34 changed units checked, 265 inherited. Every other verdict is unchanged; gate 67 passes on both.
    • #5519 plus the 10 Search controllers moved to lib/Search/Controller (a local commit made with scripts/component-move.py, not pushed). On main, gate 5 lists 47 routes as not judged and prints PASS, and gate 122 fails with 88. On this branch, gate 5 judges all 10 moved controllers with 0 not judged and passes, gate 14 opens all 10, and gate 122 passes.

AI assistance: prepared with Claude Code.

…lib/

Gates 5, 7, 9, 14 and 49 located controllers in lib/Controller only, and
gates 3, 6, 8 and 57 listed only lib/Service and lib/BackgroundJob. After a
component move (openregister#5519 puts classes in lib/Search/<layer>/) the
moved classes were no longer opened and the gates still printed PASS.

- controller_resolver.py resolves every route controller name the way
  Nextcloud does, through appinfo/class-aliases.json and the PSR-4 map in
  composer.json, so a moved controller that keeps its route name is found.
- Gate 5 fails when a routed controller is declared by no file under lib/,
  instead of parking the route as not judged. A diff that moves or deletes a
  controller, or changes the class aliases or composer.json, puts every
  route back in scope for gates 5 and 14.
- The role gates read lib/<Role> plus every lib/**/<Role> directory, and the
  controller gates also read the routed controllers the resolver found.

Assisted-by: ClaudeCode:claude-opus-5-5
The ratchet diffed a renamed file by its new path only, so every line of a
moved file counted as added and existing clones came back as new findings
(71 on openregister#5519). The added lines of a renamed file now come from a
rename-aware diff against its old path: a pure move adds nothing, and an
edit inside a moved file still counts.

Assisted-by: ClaudeCode:claude-opus-5-5
…tracts

The file ships in contracts/ since v1.19.0 but was missing from the README
table, the test-bootstrap guard and the Psalm stubs a consumer copies. A test
now keeps those three lists in step with contracts/.

Assisted-by: ClaudeCode:claude-opus-5-5
…directories

The same lib/<Role> assumption sat in seven more places, each of which goes
blind or false-red when a component layout moves classes to
lib/<Component>/<Role>/:

- gate 6 matched a routed controller action by its file path only, so a
  controller reached through a class alias or a Settings\ route was reported
  as an orphan; the route table is now resolved through controller_resolver.
- gate 16 (BACKEND_DIRS) and gate 97 (forbidden elevation callers) apply each
  layer at lib/ and one component level down.
- gate 25 treats any Controller directory under lib/, and every file the
  route table resolves to, as a controller.
- gate 30 no longer needs a lib/Controller directory to run.
- gate 48 diffs controllers anywhere under lib/ with -M, so a dropped
  #[NoCSRFRequired] in a moved controller is still seen.
- gate 111 reads lib/<Component>/Service/Flow/Nodes/ as well.

Assisted-by: ClaudeCode:claude-opus-5-5
…cable reason

Assisted-by: ClaudeCode:claude-opus-5-5
…ontroller

A routed controller that no file under lib/ declares now fails gate 5 under
its own rule (routed-controller-not-found) instead of being listed as not
judged. The suites keep asserting that it is never counted as a missing auth
attribute. Gate 14's invariant 1 now also opens lib/AppHost/Controller/, so
the renamed-method fixture reports the rename once per invariant.

Assisted-by: ClaudeCode:claude-opus-5-5
ShellCheck SC2016 flagged four single-quoted fixtures that hold PHP
variables. A quoted heredoc keeps the text literal without a disable.

Assisted-by: ClaudeCode:claude-opus-5-5
@rubenvdlinde
rubenvdlinde merged commit 33ed358 into main Nov 5, 2026
27 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant