diff --git a/hydra-gates/README.md b/hydra-gates/README.md
index 2dca8194..2c5a29f7 100644
--- a/hydra-gates/README.md
+++ b/hydra-gates/README.md
@@ -191,6 +191,7 @@ can typehint it under PHPUnit without the OpenRegister app installed:
| `ObjectEntityInterface.php` | interface | the object a read returns |
| `RegisterSlugResolverInterface.php` | interface | finds the slug a register answers to on this instance |
| `RegisterSlugResolution.php` | **final class** | the value `resolve()` returns |
+| `EmailLinkReaderInterface.php` | interface | reads the Nextcloud Mail messages linked to an object |
Each file is a byte-for-byte copy of the same file in openregister's
`lib/Contract/`. No namespace rewrite, no header, no index. Gate 67 fails the
@@ -204,7 +205,8 @@ own `vendor/` copy over the one beside the runner. CI never runs `composer
install` for the gates, so CI goes green as soon as this repo ships the file. A
local checkout with an older release in `vendor/` keeps reporting it as "NOT
shipped" until the lock moves. `RegisterSlugResolution` and `RegisterSlugResolverInterface`
-landed in openregister#3571, here in #739, and first shipped in v1.18.0.
+landed in openregister#3571, here in #739, and first shipped in v1.18.0. `EmailLinkReaderInterface`
+first shipped in v1.19.0, so an openregister lock on v1.18.0 still fails gate 67 locally.
They are **not** autoloaded. This package used to declare
@@ -224,7 +226,7 @@ A consumer that needs these contracts requires them from its own test
bootstrap, behind a guard:
```php
-foreach (['ObjectEntityInterface', 'ObjectServiceInterface', 'RegisterSlugResolution', 'RegisterSlugResolverInterface'] as $contract) {
+foreach (['ObjectEntityInterface', 'ObjectServiceInterface', 'RegisterSlugResolution', 'RegisterSlugResolverInterface', 'EmailLinkReaderInterface'] as $contract) {
$fqcn = '\\OCA\\OpenRegister\\Contract\\' . $contract;
if (interface_exists($fqcn) === false && class_exists($fqcn) === false) {
$shipped = __DIR__ . '/../vendor/conduction/hydra-gates/hydra-gates/contracts/' . $contract . '.php';
@@ -274,6 +276,7 @@ the autoloader is precisely the defect this change removed.
+
```
diff --git a/hydra-gates/scripts/lib/check_contract_coverage.py b/hydra-gates/scripts/lib/check_contract_coverage.py
index 3051c3fd..88e0750b 100644
--- a/hydra-gates/scripts/lib/check_contract_coverage.py
+++ b/hydra-gates/scripts/lib/check_contract_coverage.py
@@ -59,6 +59,7 @@
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from exclusion_reason import exclude_pattern, is_reason_bearing # noqa: E402
from source_scope import php_mask # noqa: E402
+from controller_resolver import route_names_by_file # noqa: E402
GATE_NUM = 25
@@ -170,6 +171,19 @@ def _slug_for_controller(rel_path: str) -> str:
return short[:1].lower() + short[1:]
+def _is_controller_path(rel: str, routed: dict | None = None) -> bool:
+ """A controller file: `*Controller.php` in any Controller directory under
+ lib/, or a file the route table resolves to (controller_resolver.py)."""
+ if routed and os.path.normpath(rel) in routed:
+ return True
+ return rel.startswith("lib/") and rel.endswith("Controller.php") and "/Controller/" in "/" + rel
+
+
+def _routed_files(app_dir: Path, routes: dict) -> dict:
+ """{controller file: {route controller name}} for the route table."""
+ return route_names_by_file(str(app_dir), {ref.split("#", 1)[0] for ref in routes})
+
+
def _entry_span(struct: str, at: int) -> tuple[int, int] | None:
"""The innermost balanced ``[ … ]`` containing offset *at* in *struct*.
@@ -465,7 +479,7 @@ def _contract_status(lines: list[str], decl_idx: int) -> tuple[str, str | None]:
def scan_new_endpoints(
- app_dir: Path, changed: dict[str, set[int]], routes: dict[str, list[str]]
+ app_dir: Path, changed: dict[str, set[int]], routes: dict[str, list[str]], routed: dict | None = None
) -> list[dict]:
"""Return new public endpoints ADDED in the diff that are registered routes.
@@ -473,7 +487,7 @@ def scan_new_endpoints(
"""
out: list[dict] = []
for rel, added in changed.items():
- if not rel.startswith("lib/Controller/") or not rel.endswith("Controller.php"):
+ if not _is_controller_path(rel, routed):
continue
cfile = app_dir / rel
if not cfile.is_file():
@@ -482,7 +496,7 @@ def scan_new_endpoints(
lines = cfile.read_text(encoding="utf-8").splitlines()
except OSError:
continue
- slug = _slug_for_controller(rel)
+ slugs = [_slug_for_controller(rel)] + sorted((routed or {}).get(os.path.normpath(rel), ()))
for idx, line in enumerate(lines):
m = _PHP_PUBLIC_METHOD_RE.match(line)
if not m:
@@ -491,8 +505,8 @@ def scan_new_endpoints(
if decl_line_no not in added:
continue # method declaration not added in this PR
method = m.group("name")
- ref = f"{slug}#{method}"
- if ref not in routes:
+ ref = next((f"{s}#{method}" for s in slugs if f"{s}#{method}" in routes), None)
+ if ref is None:
continue # not a registered route → not a public endpoint
if not _method_is_public_endpoint(lines, idx):
continue # admin-only / no public attribute → out of scope
@@ -916,7 +930,7 @@ def _collect(app_dir: Path, base_ref: str) -> list[dict]:
return []
routes = parse_route_urls(routes_path)
changed = changed_lines(base_ref, app_dir)
- return scan_new_endpoints(app_dir, changed, routes)
+ return scan_new_endpoints(app_dir, changed, routes, _routed_files(app_dir, routes))
def _collect_from(app_dir: Path, changed: dict[str, set[int]]) -> list[dict]:
@@ -929,7 +943,8 @@ def _collect_from(app_dir: Path, changed: dict[str, set[int]]) -> list[dict]:
routes_path = app_dir / "appinfo" / "routes.php"
if not routes_path.is_file():
return []
- return scan_new_endpoints(app_dir, changed, parse_route_urls(routes_path))
+ routes = parse_route_urls(routes_path)
+ return scan_new_endpoints(app_dir, changed, routes, _routed_files(app_dir, routes))
def _all_controller_lines(app_dir: Path) -> dict[str, set[int]]:
@@ -941,10 +956,14 @@ def _all_controller_lines(app_dir: Path) -> dict[str, set[int]]:
introduced it.
"""
out: dict[str, set[int]] = {}
- cdir = app_dir / "lib" / "Controller"
- if not cdir.is_dir():
+ lib = app_dir / "lib"
+ if not lib.is_dir():
return out
- for cfile in cdir.rglob("*Controller.php"):
+ routes_path = app_dir / "appinfo" / "routes.php"
+ routed = _routed_files(app_dir, parse_route_urls(routes_path)) if routes_path.is_file() else {}
+ for cfile in lib.rglob("*.php"):
+ if not _is_controller_path(str(cfile.relative_to(app_dir)), routed):
+ continue
try:
n = len(cfile.read_text(encoding="utf-8").splitlines())
except OSError:
@@ -986,9 +1005,11 @@ def run_gate(app_dir: Path) -> int:
# The scope that matters is CONTROLLER files, not "any file". A diff of
# a hundred docs commits still opens no controller, and reporting PASS
# for it claims a wire contract was checked when none was read.
+ routes_path = app_dir / "appinfo" / "routes.php"
+ routed = _routed_files(app_dir, parse_route_urls(routes_path))
changed = {
rel: lines for rel, lines in changed.items()
- if rel.startswith("lib/Controller/") and rel.endswith("Controller.php")
+ if _is_controller_path(rel, routed)
}
if not changed:
print(
@@ -1007,7 +1028,7 @@ def run_gate(app_dir: Path) -> int:
print(
f"[gate-{GATE_NUM}] contract-coverage: NOT APPLICABLE — "
f"appinfo/routes.php exists but there is no "
- f"lib/Controller/*Controller.php for a route to reach."
+ f"controller under lib/ for a route to reach."
)
return EXIT_NOT_APPLICABLE
endpoints = _collect_from(app_dir, all_lines)
diff --git a/hydra-gates/scripts/lib/check_flow_node_taxonomy.py b/hydra-gates/scripts/lib/check_flow_node_taxonomy.py
index ba88343d..c43e740b 100755
--- a/hydra-gates/scripts/lib/check_flow_node_taxonomy.py
+++ b/hydra-gates/scripts/lib/check_flow_node_taxonomy.py
@@ -102,14 +102,25 @@ def check_file(path: str) -> list[str]:
return findings
+def node_directories(root: str) -> list[str]:
+ """lib/Service/Flow/Nodes/ and, for a component layout, every
+ lib//Service/Flow/Nodes/ that exists."""
+ found = [os.path.join(root, NODE_DIR)]
+ lib = os.path.join(root, "lib")
+ if os.path.isdir(lib):
+ for component in sorted(os.listdir(lib)):
+ found.append(os.path.join(lib, component, "Service", "Flow", "Nodes"))
+ return [d for d in found if os.path.isdir(d)]
+
+
def main() -> int:
"""Run the gate."""
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("root", nargs="?", default=".", help="repository root")
args = parser.parse_args()
- node_dir = os.path.join(args.root, NODE_DIR)
- if not os.path.isdir(node_dir):
+ node_dirs = node_directories(args.root)
+ if not node_dirs:
# NOT APPLICABLE. This repository contributes no flow nodes of its own,
# and a node it contributes from anywhere else is not this gate's
# business — see the scoping note above.
@@ -118,13 +129,14 @@ def main() -> int:
findings = []
inspected = 0
- for name in sorted(os.listdir(node_dir)):
- if not name.endswith(".php"):
- continue
-
- path = os.path.join(node_dir, name)
- inspected += 1
- findings.extend(check_file(path))
+ for node_dir in node_dirs:
+ for name in sorted(os.listdir(node_dir)):
+ if not name.endswith(".php"):
+ continue
+
+ path = os.path.join(node_dir, name)
+ inspected += 1
+ findings.extend(check_file(path))
for line in findings:
print(line)
diff --git a/hydra-gates/scripts/lib/check_orphan_auth.py b/hydra-gates/scripts/lib/check_orphan_auth.py
index f5b596f0..6e53a4ef 100644
--- a/hydra-gates/scripts/lib/check_orphan_auth.py
+++ b/hydra-gates/scripts/lib/check_orphan_auth.py
@@ -88,6 +88,7 @@
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from exclusion_reason import exclude_pattern, is_reason_bearing # noqa: E402
from source_scope import php_mask, script_mask # noqa: E402
+from controller_resolver import Resolver, app_namespace # noqa: E402
# ---------------------------------------------------------------------------
@@ -465,10 +466,30 @@ def _route_prefix(path: str) -> str | None:
return cls[:1].lower() + cls[1:]
-def _is_routed(path: str, method: str, head: str, route_corpus: str) -> bool:
+_ROUTE_PAIR_RE = re.compile(r"['\"]([A-Za-z][A-Za-z0-9_\\]*)\s*#\s*([A-Za-z0-9_]+)['\"]")
+
+
+def _routed_methods_by_file(route_corpus: str) -> dict:
+ """{controller file: {method, ...}} for every `name#method` in the route
+ table, each name resolved to its file by controller_resolver (class
+ aliases and PSR-4), so a controller outside lib/Controller/ is matched."""
+ resolver = Resolver(".", app_namespace("."))
+ cache: dict = {}
+ out: dict = {}
+ for name, method in _ROUTE_PAIR_RE.findall(route_corpus):
+ if name not in cache:
+ cache[name] = resolver.resolve(name)
+ if cache[name]:
+ out.setdefault(os.path.normpath(cache[name]), set()).add(method)
+ return out
+
+
+def _is_routed(path: str, method: str, head: str, route_corpus: str, routed: dict | None = None) -> bool:
"""True when the router — not a `->method(` call — reaches this method."""
if _ROUTE_ATTR_RE.search(head):
return True
+ if routed and method in routed.get(os.path.normpath(os.path.relpath(path)), ()):
+ return True
prefix = _route_prefix(path)
if not prefix:
return False
@@ -483,6 +504,7 @@ def scan_files(files: list[str]) -> list[str]:
"""Return finding lines for the given candidate files."""
corpus = _build_caller_corpus()
route_corpus = _build_route_corpus()
+ routed = _routed_methods_by_file(route_corpus)
findings: list[str] = []
for f in files:
try:
@@ -500,7 +522,7 @@ def scan_files(files: list[str]) -> list[str]:
if caller_re.search(corpus):
continue
# The router is a caller the `lib/`+`src/` corpus cannot contain.
- if _is_routed(f, name, head, route_corpus):
+ if _is_routed(f, name, head, route_corpus, routed):
continue
if _is_excluded(src, line_no):
continue
diff --git a/hydra-gates/scripts/lib/check_sig_maintainability.py b/hydra-gates/scripts/lib/check_sig_maintainability.py
index 1c1446d8..532febc2 100755
--- a/hydra-gates/scripts/lib/check_sig_maintainability.py
+++ b/hydra-gates/scripts/lib/check_sig_maintainability.py
@@ -983,12 +983,21 @@ def cmd_report(args, lizard, jscpd):
# ratchet
# --------------------------------------------------------------------------
-def added_lines(app, base, rel):
- rc, out = git(app, "diff", "-U0", "--no-color", base, "HEAD", "--", rel)
+def added_lines(app, base, rel, old=None):
+ """Lines of `rel` the change added. A renamed file is diffed against its old
+ path, so a pure move adds nothing and only the lines edited in it count."""
+ paths = [old, rel] if old and old != rel else [rel]
+ rc, out = git(app, "diff", "-U0", "--no-color", "-M", "--src-prefix=a/", "--dst-prefix=b/",
+ base, "HEAD", "--", *paths)
lines = set()
+ current = None
for line in out.splitlines():
+ if line.startswith("+++ "):
+ current = line[4:]
+ current = current[2:] if current.startswith("b/") else None
+ continue
m = re.match(r"^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@", line)
- if m:
+ if m and current == rel:
start, count = int(m.group(1)), int(m.group(2) or 1)
lines.update(range(start, start + count))
return lines
@@ -1029,7 +1038,7 @@ def cmd_ratchet(args, lizard, jscpd_exe):
touched_units = 0
added = {}
for rel, (lang, old) in sorted(changed.items()):
- added[rel] = added_lines(app, mb, rel)
+ added[rel] = added_lines(app, mb, rel, old)
head_units = reader.units(rel, lang, read_text(os.path.join(app, rel)))
base_units = {}
if old:
diff --git a/hydra-gates/scripts/lib/check_spec_coverage.py b/hydra-gates/scripts/lib/check_spec_coverage.py
index 832c8d9e..d1c76bdf 100644
--- a/hydra-gates/scripts/lib/check_spec_coverage.py
+++ b/hydra-gates/scripts/lib/check_spec_coverage.py
@@ -186,6 +186,20 @@
)
BACKEND_EXEMPT_DIRS = ("lib/Db", "lib/Migration")
+
+def _is_backend(rel: str) -> bool:
+ """True for PHP under a backend layer directory, at lib// or one
+ component down at lib/// (a component layout such as
+ lib/Search/Service/). The exempt layers stay exempt at either depth."""
+ candidates = [rel]
+ if rel.startswith("lib/"):
+ parts = rel[len("lib/"):].split("/", 1)
+ if len(parts) == 2 and "lib/" + parts[0] not in BACKEND_DIRS + BACKEND_EXEMPT_DIRS:
+ candidates.append("lib/" + parts[1])
+ if any(c.startswith(BACKEND_EXEMPT_DIRS) for c in candidates):
+ return False
+ return any(c.startswith(BACKEND_DIRS) for c in candidates)
+
# `public function foo(` / `protected function foo(` — capture visibility+name.
PHP_METHOD_RE = re.compile(
r"^\s*(?:final\s+|abstract\s+|static\s+)*"
@@ -1095,7 +1109,7 @@ def _substantively_changed_lines(base_text: str, head_text: str, is_php: bool) -
def _is_in_gate_scope(rel: str) -> bool:
"""True if this path is one gate-16 would evaluate at all."""
if rel.endswith(".php"):
- return rel.startswith(BACKEND_DIRS) and not rel.startswith(BACKEND_EXEMPT_DIRS)
+ return _is_backend(rel)
return _is_frontend_in_scope(rel)
@@ -1566,10 +1580,9 @@ def check_frontend_file(rel: str, text: str, added: set[int], findings: list[str
def _iter_in_scope_files(app_dir: Path) -> list[str]:
"""All in-scope backend + frontend files in the repo (full-repo, no diff)."""
rels: list[str] = []
- for d in BACKEND_DIRS:
- base = app_dir / d
- if base.is_dir():
- rels += [str(p.relative_to(app_dir)) for p in base.rglob("*.php")]
+ lib = app_dir / "lib"
+ if lib.is_dir():
+ rels += [rel for rel in (str(p.relative_to(app_dir)) for p in lib.rglob("*.php")) if _is_backend(rel)]
src = app_dir / "src"
if src.is_dir():
for p in src.rglob("*"):
@@ -1596,7 +1609,7 @@ def run_report(app_dir: Path) -> int:
# → every in-scope method is evaluated; @spec / @spec-exclude still skip.
all_lines = set(range(1, len(text.splitlines()) + 2))
if rel.endswith(".php"):
- if rel.startswith(BACKEND_EXEMPT_DIRS) or not rel.startswith(BACKEND_DIRS):
+ if not _is_backend(rel):
continue
check_php_file(rel, text, all_lines, uncovered)
elif _is_frontend_in_scope(rel):
@@ -1628,7 +1641,7 @@ def _uncovered_in_text(rel: str, text: str) -> set[str]:
out: list[str] = []
all_lines = set(range(1, len(text.splitlines()) + 2))
if rel.endswith(".php"):
- if rel.startswith(BACKEND_EXEMPT_DIRS) or not rel.startswith(BACKEND_DIRS):
+ if not _is_backend(rel):
return set()
check_php_file(rel, text, all_lines, out)
elif _is_frontend_in_scope(rel):
@@ -1684,9 +1697,7 @@ def run_gate(app_dir: Path) -> int:
continue
if rel.endswith(".php"):
- if rel.startswith(BACKEND_EXEMPT_DIRS):
- continue
- if not rel.startswith(BACKEND_DIRS):
+ if not _is_backend(rel):
continue
check_php_file(rel, text, added, findings)
elif _is_frontend_in_scope(rel):
diff --git a/hydra-gates/scripts/lib/check_system_elevation.py b/hydra-gates/scripts/lib/check_system_elevation.py
index 7a7ef59b..c3d5abe8 100644
--- a/hydra-gates/scripts/lib/check_system_elevation.py
+++ b/hydra-gates/scripts/lib/check_system_elevation.py
@@ -216,10 +216,26 @@ def _php_files(root: str):
return sorted(found)
+# Directories directly under lib/ that are layers, not components.
+LAYERS = ({p.split('/')[1] for p, _why in FORBIDDEN} | {p.split('/')[1] for p in PERMITTED}
+ | {'AppInfo', 'Db', 'Listener'})
+
+
def _forbidden_reason(rel: str):
- """Why this path may not elevate, or None when it may."""
+ """Why this path may not elevate, or None when it may.
+
+ Each prefix applies at lib/ and one component level down, so a controller
+ moved to lib//Controller/ is forbidden exactly as one in
+ lib/Controller/ is. A first directory that is itself a layer
+ (lib/Service/Flow/...) is not a component.
+ """
+ candidates = [rel]
+ if rel.startswith('lib/'):
+ parts = rel[len('lib/'):].split('/', 1)
+ if len(parts) == 2 and parts[0] not in LAYERS:
+ candidates.append('lib/' + parts[1])
for prefix, why in FORBIDDEN:
- if rel.startswith(prefix):
+ if any(c.startswith(prefix) for c in candidates):
return why
return None
diff --git a/hydra-gates/scripts/lib/controller_resolver.py b/hydra-gates/scripts/lib/controller_resolver.py
new file mode 100644
index 00000000..9e02f937
--- /dev/null
+++ b/hydra-gates/scripts/lib/controller_resolver.py
@@ -0,0 +1,192 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: EUPL-1.2
+"""Resolve the controller names in appinfo/routes.php to the files that serve them.
+
+Usage::
+
+ python3 controller_resolver.py < route-controller-names
+
+Reads one route controller name per line (the part before ``#``) and prints
+``\\t`` per name, where ```` is the tracked PHP file under
+``lib/`` that declares the class Nextcloud instantiates for it, or empty when
+no such file exists. The last line is ``# resolved of ``; a run without
+it did not finish.
+
+A name resolves the way Nextcloud resolves it: ``underScoreToCamelCase(ucfirst(name))
+. 'Controller'``, looked up as given and under ``\\Controller\\``.
+Each candidate class is then followed through the app's class aliases
+(``appinfo/class-aliases.json``, old name => new name) and mapped to a file
+through the PSR-4 map in composer.json, with ``\\`` => ``lib/`` as
+the default. A class whose file does not sit at its PSR-4 path is still found
+through the ``namespace`` and ``class`` declarations of the files under lib/.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+
+NS_RE = re.compile(r"^\s*namespace\s+([A-Za-z0-9_\\]+)\s*;", re.M)
+CLASS_RE = re.compile(r"^\s*(?:(?:final|abstract|readonly)\s+)*class\s+([A-Za-z0-9_]+)", re.M)
+
+
+def psr4_map(root, app_ns):
+ """[(prefix, dir)] longest prefix first."""
+ pairs = []
+ try:
+ with open(os.path.join(root, "composer.json"), encoding="utf-8") as fh:
+ autoload = json.load(fh).get("autoload", {}).get("psr-4", {})
+ for prefix, dirs in autoload.items():
+ for d in dirs if isinstance(dirs, list) else [dirs]:
+ pairs.append((prefix.rstrip("\\") + "\\", d.rstrip("/") + "/"))
+ except (OSError, ValueError, AttributeError):
+ pass
+ if app_ns and not any(p == app_ns + "\\" for p, _d in pairs):
+ pairs.append((app_ns + "\\", "lib/"))
+ return sorted(pairs, key=lambda p: len(p[0]), reverse=True)
+
+
+def class_aliases(root):
+ """{old fqcn: new fqcn} from appinfo/class-aliases.json, if the app has one."""
+ try:
+ with open(os.path.join(root, "appinfo", "class-aliases.json"), encoding="utf-8") as fh:
+ data = json.load(fh)
+ except (OSError, ValueError):
+ return {}
+ entries = data.get("aliases", data) if isinstance(data, dict) else {}
+ out = {}
+ for old, new in entries.items() if isinstance(entries, dict) else []:
+ target = new.get("class") if isinstance(new, dict) else new
+ if isinstance(target, str):
+ out[old.lstrip("\\")] = target.lstrip("\\")
+ return out
+
+
+def declared_classes(root, files):
+ """{fqcn: path} from the namespace and class declarations of `files`."""
+ out = {}
+ for rel in files:
+ try:
+ with open(os.path.join(root, rel), encoding="utf-8", errors="replace") as fh:
+ text = fh.read()
+ except OSError:
+ continue
+ ns = NS_RE.search(text)
+ for m in CLASS_RE.finditer(text):
+ fqcn = (ns.group(1) + "\\" if ns else "") + m.group(1)
+ out.setdefault(fqcn, rel)
+ return out
+
+
+def lib_php_files(root):
+ out = []
+ for base, dirs, files in os.walk(os.path.join(root, "lib")):
+ dirs[:] = [d for d in dirs if d not in ("vendor", "node_modules")]
+ out.extend(os.path.relpath(os.path.join(base, f), root) for f in files if f.endswith(".php"))
+ return sorted(out)
+
+
+def controller_class(name):
+ """Nextcloud's RouteParser::buildControllerName()."""
+ parts = name.split("_")
+ camel = parts[0] + "".join(p[:1].upper() + p[1:] for p in parts[1:])
+ return camel[:1].upper() + camel[1:] + "Controller"
+
+
+class Resolver:
+ def __init__(self, root, app_ns):
+ self.root = root
+ self.app_ns = app_ns.strip("\\")
+ self.psr4 = psr4_map(root, self.app_ns)
+ self.aliases = class_aliases(root)
+ self._declared = None
+
+ def psr4_path(self, fqcn):
+ for prefix, d in self.psr4:
+ if fqcn.startswith(prefix):
+ rel = d + fqcn[len(prefix):].replace("\\", "/") + ".php"
+ if os.path.isfile(os.path.join(self.root, rel)):
+ return rel
+ return None
+
+ def declared(self, fqcn):
+ if self._declared is None:
+ self._declared = declared_classes(self.root, lib_php_files(self.root))
+ return self._declared.get(fqcn)
+
+ def file_of(self, fqcn):
+ seen = set()
+ while fqcn and fqcn not in seen:
+ seen.add(fqcn)
+ path = self.psr4_path(fqcn) or self.declared(fqcn)
+ if path:
+ return path
+ fqcn = self.aliases.get(fqcn)
+ return None
+
+ def candidates(self, name):
+ cls = controller_class(name)
+ out = []
+ if self.app_ns and not cls.startswith(self.app_ns + "\\"):
+ out.append(f"{self.app_ns}\\Controller\\{cls}")
+ if "\\" in cls:
+ out.append(f"{self.app_ns}\\{cls}")
+ out.append(cls)
+ return out
+
+ def resolve(self, name):
+ for fqcn in self.candidates(name):
+ path = self.file_of(fqcn)
+ if path:
+ return path
+ return None
+
+
+def app_namespace(root):
+ """`OCA\\` from lib/AppInfo/Application.php, else appinfo/info.xml, else ''."""
+ try:
+ with open(os.path.join(root, "lib", "AppInfo", "Application.php"), encoding="utf-8", errors="replace") as fh:
+ m = re.search(r"^\s*namespace\s+(OCA\\[A-Za-z0-9_]+)", fh.read(), re.M)
+ if m:
+ return m.group(1)
+ except OSError:
+ pass
+ try:
+ with open(os.path.join(root, "appinfo", "info.xml"), encoding="utf-8", errors="replace") as fh:
+ m = re.search(r"\s*([A-Za-z0-9_]+)\s*", fh.read())
+ if m:
+ return "OCA\\" + m.group(1)
+ except OSError:
+ pass
+ return ""
+
+
+def route_names_by_file(root, names):
+ """{file: {route controller name, ...}} for the names that resolve."""
+ resolver = Resolver(root, app_namespace(root))
+ out = {}
+ for name in set(names):
+ path = resolver.resolve(name)
+ if path:
+ out.setdefault(os.path.normpath(path), set()).add(name)
+ return out
+
+
+def main(argv):
+ if len(argv) != 3:
+ print(__doc__, file=sys.stderr)
+ return 2
+ resolver = Resolver(argv[1], argv[2])
+ names = [n.strip() for n in sys.stdin if n.strip()]
+ found = 0
+ for name in names:
+ path = resolver.resolve(name) or ""
+ found += bool(path)
+ print(f"{name}\t{path}")
+ print(f"# resolved {found} of {len(names)}")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main(sys.argv))
diff --git a/hydra-gates/scripts/lib/test_check_contract_coverage.py b/hydra-gates/scripts/lib/test_check_contract_coverage.py
index d54017e5..b869ca3d 100644
--- a/hydra-gates/scripts/lib/test_check_contract_coverage.py
+++ b/hydra-gates/scripts/lib/test_check_contract_coverage.py
@@ -657,5 +657,34 @@ def test_that_same_shape_still_requires_a_REASON(self):
self.assertIn("thing#destroy", out)
+
+class ContractCoverageComponentLayout(unittest.TestCase):
+ """A controller moved to lib//Controller/ keeps its route name
+ through appinfo/class-aliases.json; its endpoints are still judged."""
+
+ def setUp(self) -> None:
+ self.app = _App()
+ self.addCleanup(self.app.destroy)
+ (self.app.root / "lib/Controller/ThingController.php").unlink()
+ self.app.write("composer.json", '{"autoload": {"psr-4": {"OCA\\\\Fx\\\\": "lib/"}}}')
+ self.app.write("lib/AppInfo/Application.php", "service->isHostAllowed($url)) {
+ throw new \\OCP\\AppFramework\\OCS\\OCSForbiddenException('blocked host');
+ }
+ return new JSONResponse(['ok' => true]);
+ }
+}
+"""
+
+_APP = {
+ "composer.json": '{"autoload": {"psr-4": {"OCA\\\\Fx\\\\": "lib/"}}}',
+ "lib/AppInfo/Application.php": " 60: {nloc(71)} (was {nloc(70)})", out)
+ self.assertIn("FAIL: 1 finding(s)", out)
+
+ def test_a_clone_added_to_a_moved_file_is_new(self):
+ self.move("lib/Service/Legacy.php", "lib/Search/Legacy.php", "OCA\\Fx\\Search")
+ self.edit("class Legacy\n{\n", "class Legacy\n{\n" + php_method("copyThree", lines=1, tag="w").replace(
+ " return 0;", DUP_BLOCK + " return 0;"), rel="lib/Search/Legacy.php")
+ rc, out = self.ratchet()
+ self.assertEqual(rc, 1, out)
+ self.assertIn("duplicated fragment of 6+ lines", out)
+
def test_a_change_with_no_measured_source_is_not_applicable(self):
self.repo.write("README.md", "changed\n")
self.repo.write("tests/Unit/FreshTest.php", php_class("FreshTest", [php_method("t", lines=80)]))
diff --git a/hydra-gates/scripts/lib/test_check_spec_coverage.py b/hydra-gates/scripts/lib/test_check_spec_coverage.py
index 1f7627fa..39cf7593 100644
--- a/hydra-gates/scripts/lib/test_check_spec_coverage.py
+++ b/hydra-gates/scripts/lib/test_check_spec_coverage.py
@@ -1234,5 +1234,35 @@ def test_CONTROL_a_closing_bracket_that_is_not_an_attribute_stops_the_walk(self)
]
self.assertEqual(csc._docblock_block(lines, 5), [])
+
+class ComponentLayoutScope(unittest.TestCase):
+ """A component layout puts the backend layers one level down
+ (lib/Search/Service/); gate 16 judges them as it judges lib/Service/."""
+
+ def test_component_layers_are_in_scope(self):
+ for rel in ("lib/Search/Service/ViewService.php", "lib/Search/Controller/ViewsController.php",
+ "lib/Search/BackgroundJob/ReindexJob.php", "lib/Search/Listener/IndexListener.php"):
+ self.assertTrue(csc._is_in_gate_scope(rel), rel)
+
+ def test_component_exempt_layers_stay_exempt(self):
+ for rel in ("lib/Search/Db/ViewMapper.php", "lib/Search/Migration/Version1.php", "lib/Db/Thing.php"):
+ self.assertFalse(csc._is_in_gate_scope(rel), rel)
+
+ def test_a_layer_is_not_read_as_a_component(self):
+ self.assertTrue(csc._is_in_gate_scope("lib/Service/Thing/Helper.php"))
+ self.assertFalse(csc._is_in_gate_scope("lib/Search/Model/Thing.php"))
+
+ def test_the_full_report_lists_component_files(self):
+ root = Path(tempfile.mkdtemp(prefix="gate16-comp-"))
+ try:
+ (root / "lib/Search/Service").mkdir(parents=True)
+ (root / "lib/Search/Service/ViewService.php").write_text("ctx->runAsSystem(fn () => 1);\n }\n}\n"
+
+
+class ForbiddenCallers(unittest.TestCase):
+ def setUp(self):
+ self.root = tempfile.mkdtemp(prefix="gate97-")
+
+ def tearDown(self):
+ shutil.rmtree(self.root, ignore_errors=True)
+
+ def run_on(self, rel):
+ path = os.path.join(self.root, rel)
+ os.makedirs(os.path.dirname(path), exist_ok=True)
+ with open(path, "w", encoding="utf-8") as fh:
+ fh.write(ELEVATING)
+ buf = io.StringIO()
+ argv = sys.argv
+ sys.argv = ["x", self.root]
+ try:
+ with contextlib.redirect_stdout(buf):
+ rc = cse.main()
+ finally:
+ sys.argv = argv
+ return rc, buf.getvalue()
+
+ def test_a_controller_in_lib_controller_fails(self):
+ rc, out = self.run_on("lib/Controller/ThingController.php")
+ self.assertEqual(rc, 1, out)
+
+ def test_a_controller_in_a_component_directory_fails(self):
+ rc, out = self.run_on("lib/Search/Controller/ThingController.php")
+ self.assertEqual(rc, 1, out)
+ self.assertIn("FAIL lib/Search/Controller/ThingController.php:6", out)
+
+ def test_a_flow_node_in_a_component_directory_fails(self):
+ rc, out = self.run_on("lib/Workflow/Service/Flow/Nodes/SendNode.php")
+ self.assertEqual(rc, 1, out)
+
+ def test_a_background_job_in_a_component_directory_may_elevate(self):
+ rc, out = self.run_on("lib/Search/BackgroundJob/ReindexJob.php")
+ self.assertEqual(rc, 0, out)
+
+ def test_a_controller_directory_two_levels_down_is_not_a_component(self):
+ rc, out = self.run_on("lib/Service/Thing/Controller/Helper.php")
+ self.assertEqual(rc, 0, out)
+
+ def test_a_layer_directory_is_not_read_as_a_component(self):
+ rc, out = self.run_on("lib/Service/Flow/Engine/Runner.php")
+ self.assertEqual(rc, 0, out)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/hydra-gates/scripts/lib/test_controller_resolver.py b/hydra-gates/scripts/lib/test_controller_resolver.py
new file mode 100644
index 00000000..91a19eb7
--- /dev/null
+++ b/hydra-gates/scripts/lib/test_controller_resolver.py
@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: EUPL-1.2
+"""Unit tests for controller_resolver.py: route controller names to files."""
+import json
+import os
+import shutil
+import sys
+import tempfile
+import unittest
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import controller_resolver as cr # noqa: E402
+
+
+class Resolve(unittest.TestCase):
+ def setUp(self):
+ self.root = tempfile.mkdtemp(prefix="ctrl-resolver-")
+ self.write("composer.json", json.dumps({"autoload": {"psr-4": {"OCA\\Fx\\": "lib/"}}}))
+
+ def tearDown(self):
+ shutil.rmtree(self.root, ignore_errors=True)
+
+ def write(self, rel, text):
+ path = os.path.join(self.root, rel)
+ os.makedirs(os.path.dirname(path), exist_ok=True)
+ with open(path, "w", encoding="utf-8") as fh:
+ fh.write(text)
+
+ def ctrl(self, rel, ns, cls):
+ self.write(rel, f"/Service/Flow/Nodes/.
+# The planted tree is copied there, with no lib/Service/ left behind, so a
+# checker that reads lib/Service/Flow/Nodes/ only reports NOT APPLICABLE.
+COMPONENT_ROOT="$(mktemp -d "${TMPDIR:-/tmp}/gate111-component.XXXXXXXX")"
+trap 'rm -rf "${COMPONENT_ROOT}"' EXIT
+mkdir -p "${COMPONENT_ROOT}/component/lib/Workflow/Service/Flow"
+cp -r "${FIXTURES}/planted/lib/Service/Flow/Nodes" "${COMPONENT_ROOT}/component/lib/Workflow/Service/Flow/"
+FIXTURES="${COMPONENT_ROOT}" expect component 1 1 "the planted node under lib/Workflow/Service/Flow/Nodes/ is refused"
+
if [ "${fails}" -ne 0 ]; then
echo "gate-111 acceptance: ${fails} case(s) failed"
exit 1
diff --git a/hydra-gates/scripts/lib/test_gate_component_dirs.sh b/hydra-gates/scripts/lib/test_gate_component_dirs.sh
new file mode 100644
index 00000000..0bebcc0f
--- /dev/null
+++ b/hydra-gates/scripts/lib/test_gate_component_dirs.sh
@@ -0,0 +1,448 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: EUPL-1.2
+#
+# test_gate_component_dirs.sh — the role gates reach controllers, services and
+# background jobs that live in a component directory (lib///)
+# instead of lib/Controller, lib/Service and lib/BackgroundJob.
+#
+# openregister#5519 moved 63 Search classes to lib/Search//. Gates 3,
+# 6, 8 and 57 listed only lib/Service and lib/BackgroundJob, and gates 5, 7, 9
+# and 14 located controllers in lib/Controller only, so the moved classes were
+# no longer opened and the gates still printed PASS. A moved controller keeps
+# its route name through appinfo/class-aliases.json, so the route table no
+# longer spells where the class lives.
+#
+# Every fixture below is built in a fresh git repository and carries its
+# defects ONLY under lib/Search/: there is no lib/Controller, lib/Service or
+# lib/BackgroundJob, so a gate that reads those directories alone finds
+# nothing and its assertion fails.
+#
+# HYDRA_GATES_RUNNER= runs the suite against another runner, which is
+# how its failing-first state is shown against the runner before the fix.
+#
+# Run: bash scripts/lib/test_gate_component_dirs.sh (exit 0 = all green)
+set -uo pipefail
+
+PKG_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/../.." && pwd)"
+RUNNER="${HYDRA_GATES_RUNNER:-${PKG_ROOT}/scripts/run-hydra-gates.sh}"
+
+_fail_n=0
+_pass_n=0
+_ok() { _pass_n=$((_pass_n + 1)); printf 'PASS — %s\n' "$1"; }
+_bad() { _fail_n=$((_fail_n + 1)); printf 'FAIL — %s\n' "$1"; }
+
+_WORK="$(mktemp -d "${TMPDIR:-/tmp}/hydra-gate-compdirs.XXXXXXXX")"
+trap 'rm -rf "${_WORK}"' EXIT
+
+_put() { # , or - to read the content from stdin
+ mkdir -p "$(dirname "$1/$2")"
+ if [ "$3" = - ]; then cat > "$1/$2"; else printf '%s' "$3" > "$1/$2"; fi
+}
+
+_git() { git -C "$1" -c user.email=fixture@example.invalid -c user.name=Fixture "${@:2}" >/dev/null 2>&1; }
+
+# The controller every scenario routes to. `unguarded` is routed and carries
+# no auth attribute (gate 5); `show` is an unguarded #[NoAdminRequired] read
+# by id (gate 7); `adminState` says any user and requires an admin (gate 9);
+# `orphanReport` returns a Response and has no route (gate 14). The last two
+# exist only with =1.
+_controller() { #
+ local _unguarded=""
+ if [ "$2" = "1" ]; then
+ _unguarded='
+ /**
+ * Builds the orphan report.
+ *
+ * @NoAdminRequired
+ *
+ * @return JSONResponse
+ */
+ public function orphanReport(): JSONResponse
+ {
+ return new JSONResponse([]);
+ }
+ /**
+ * Returns the export state, with no auth posture declared.
+ *
+ * @return JSONResponse
+ */
+ public function unguarded(): JSONResponse
+ {
+ return new JSONResponse(["state" => "open"]);
+ }
+'
+ fi
+ cat < \$id, 'secret' => 'exposed']);
+ }
+
+ /**
+ * Reads admin state behind an annotation that contradicts the body.
+ *
+ * @NoAdminRequired
+ *
+ * @return JSONResponse
+ */
+ public function adminState(): JSONResponse
+ {
+ \$this->requireAdmin();
+ return new JSONResponse(['state' => 'ok']);
+ }
+
+${_unguarded}}
+PHP
+}
+
+_routes() { #
+ printf ' ["
+ printf " ['name' => 'thing#show', 'url' => '/api/things/{id}', 'verb' => 'GET'],\n"
+ printf " ['name' => 'thing#adminState', 'url' => '/api/admin-state', 'verb' => 'GET'],\n"
+ [ "$1" = "1" ] && printf " ['name' => 'thing#unguarded', 'url' => '/api/unguarded', 'verb' => 'GET'],\n"
+ printf ' ],\n];\n'
+}
+
+_aliases() {
+ cat <<'JSON'
+{
+ "aliases": {
+ "OCA\\CompFx\\Controller\\ThingController": {"class": "OCA\\CompFx\\Search\\Controller\\ThingController", "eager": false, "service": true}
+ }
+}
+JSON
+}
+
+# _app — the app skeleton plus the Search services and job.
+_app() {
+ local _a="$1"
+ mkdir -p "${_a}"
+ _git "${_a}" init -q .
+ _put "${_a}" appinfo/info.xml '
+compfxComponent FixtureCompFx1.0.0agplConduction
+'
+ _put "${_a}" composer.json '{"name": "conduction/compfx", "autoload": {"psr-4": {"OCA\\CompFx\\": "lib/"}}}
+'
+ _put "${_a}" lib/AppInfo/Application.php 'get("OCA\\CompFx\\Search\\Service\\AuthorizationService");
+ } catch (\Throwable) {
+ return null;
+ }
+ }
+
+ public function mayWrite(string $userId, string $objectId): bool
+ {
+ $auth = $this->getAuthorizationService();
+ if ($auth !== null) {
+ return $auth->check($userId, $objectId);
+ }
+
+ return true;
+ }
+}
+PHP
+ _put "${_a}" lib/Search/Service/TransitionGuard.php - <<'PHP'
+ [runner args...] — the whole run in _OUT, its log dir in _LOGS.
+_OUT="" _LOGS=""
+_run() {
+ local _a="$1"; shift
+ _LOGS="$(mktemp -d "${_WORK}/logs.XXXXXXXX")"
+ _OUT="$(cd "${_a}" && HYDRA_GATE_LOG_DIR="${_LOGS}" bash "${RUNNER}" "$@" "${_a}" 2>&1 < /dev/null || true)"
+ if ! printf '%s' "${_OUT}" | grep -q '^\[hydra-gates\] COVERAGE:'; then
+ _bad "run in ${_a} ABORTED before the summary — verdicts above it are not a result"
+ printf '%s\n' "${_OUT}" | tail -15 | sed 's/^/ /'
+ return 1
+ fi
+}
+
+_expect_gate() { #
+ local _line
+ _line="$(printf '%s' "${_OUT}" | grep -E "^\[gate-$1\] " | head -1)"
+ case "${_line}" in
+ *": $2"*) _ok "$3 — ${_line:0:160}" ;;
+ '') _bad "$3 — gate-$1 emitted no verdict line" ;;
+ *) _bad "$3 — wanted $2, got: ${_line:0:240}" ;;
+ esac
+}
+
+# Some gates write hydra-gate-.log, others a mktemp hydra-gate-.XXXXXX.log.
+_logs_of() { cat "${_LOGS}/hydra-gate-$1".log "${_LOGS}/hydra-gate-$1".*.log 2>/dev/null || true; }
+
+_expect_log() { #
+ if _logs_of "$1" | grep -qF -- "$2"; then
+ _ok "$3"
+ else
+ _bad "$3 — '$2' not in hydra-gate-$1[.*].log: $(_logs_of "$1" | tr '\n' '|' | cut -c1-300)"
+ fi
+}
+
+_expect_no_log() { #
+ if _logs_of "$1" | grep -qF -- "$2"; then
+ _bad "$3 — unexpected: $(_logs_of "$1" | grep -F -- "$2" | head -1)"
+ else
+ _ok "$3"
+ fi
+}
+
+echo "== role gates over lib/// =="
+
+# ---------------------------------------------------------------------------
+# 1. A full run over an app whose controller, services and job all sit under
+# lib/Search/. The controller is reached through its class alias.
+# ---------------------------------------------------------------------------
+A="${_WORK}/aliased"
+_app "${A}"
+_put "${A}" appinfo/routes.php "$(_routes 1)"
+_put "${A}" appinfo/class-aliases.json "$(_aliases)"
+_put "${A}" lib/Search/Controller/ThingController.php "$(_controller 'OCA\CompFx\Search\Controller' 1)"
+_git "${A}" add -A && _git "${A}" commit -q -m base
+if _run "${A}"; then
+ _expect_gate 5 FAIL "gate 5: a routed controller outside lib/Controller without an auth attribute fails"
+ _expect_log route-auth "lib/Search/Controller/ThingController.php" "gate 5 judges lib/Search/Controller/ThingController.php"
+ _expect_log route-auth "method=unguarded rule=missing-auth-attribute" "gate 5 names the unguarded method"
+ _expect_no_log route-auth "method=show " "gate 5 does not flag the annotated show()"
+ _expect_log no-admin-idor "lib/Search/Controller/ThingController.php" "gate 7 opens the controller under lib/Search/Controller"
+ _expect_log semantic-auth "lib/Search/Controller/ThingController.php" "gate 9 opens the controller under lib/Search/Controller"
+ _expect_log route-reachability "method=orphanReport" "gate 14 finds the unrouted method on the moved controller"
+ _expect_no_log route-reachability "method=show " "gate 14 sees thing#show as the moved controller's route"
+ _expect_log unsafe-auth-resolver "lib/Search/Service/PermissionHandler.php" "gate 8 opens lib/Search/Service"
+ _expect_log orphan-auth "lib/Search/Service/TransitionGuard.php" "gate 6 opens lib/Search/Service"
+ _expect_log orphaned-write-capability "lib/Search/Service/LedgerService.php" "gate 57 opens lib/Search/Service"
+ _expect_log stub-scan "lib/Search/BackgroundJob/ReindexJob.php: run() body" "gate 3 judges the run() body of a job under lib/Search/BackgroundJob"
+fi
+
+# ---------------------------------------------------------------------------
+# 2. The same controller with the auth attribute in place: gate 5 judges it
+# and passes, instead of parking it as "not judged".
+# ---------------------------------------------------------------------------
+B="${_WORK}/aliased-clean"
+_app "${B}"
+_put "${B}" appinfo/routes.php "$(_routes 0)"
+_put "${B}" appinfo/class-aliases.json "$(_aliases)"
+_put "${B}" lib/Search/Controller/ThingController.php "$(_controller 'OCA\CompFx\Search\Controller' 0)"
+_git "${B}" add -A && _git "${B}" commit -q -m base
+if _run "${B}"; then
+ _expect_gate 5 PASS "gate 5: annotated routed methods on a moved controller pass"
+ if [ -s "${_LOGS}/hydra-gate-route-auth-unresolved.log" ]; then
+ _bad "gate 5 parked routes as not judged: $(head -1 "${_LOGS}/hydra-gate-route-auth-unresolved.log")"
+ else
+ _ok "gate 5 judged every route (nothing parked as unresolved)"
+ fi
+fi
+
+# ---------------------------------------------------------------------------
+# 3. The controller moved WITHOUT a class alias: nothing answers to
+# OCA\CompFx\Controller\ThingController, so the routes 500. Gate 5 fails
+# loudly instead of filing the routes as "not judged", and gate 14 fails.
+# ---------------------------------------------------------------------------
+C="${_WORK}/unaliased"
+_app "${C}"
+_put "${C}" appinfo/routes.php "$(_routes 0)"
+_put "${C}" lib/Search/Controller/ThingController.php "$(_controller 'OCA\CompFx\Search\Controller' 0)"
+_git "${C}" add -A && _git "${C}" commit -q -m base
+if _run "${C}"; then
+ _expect_gate 5 FAIL "gate 5: a routed controller no file declares fails"
+ _expect_log route-auth-controller-not-found "thing#show rule=routed-controller-not-found" "gate 5 names the route whose controller is missing"
+ _expect_gate 14 FAIL "gate 14: the same route is unreachable"
+fi
+
+# ---------------------------------------------------------------------------
+# 4. Diff scope: a change that moves the controller out of lib/Controller.
+# With the alias the moved routes are judged (not skipped as out of scope);
+# without it the move fails gate 5 and gate 14.
+# ---------------------------------------------------------------------------
+for _variant in with-alias without-alias; do
+ D="${_WORK}/move-${_variant}"
+ _app "${D}"
+ _put "${D}" appinfo/routes.php "$(_routes 0)"
+ _put "${D}" lib/Controller/ThingController.php "$(_controller 'OCA\CompFx\Controller' 0)"
+ _git "${D}" add -A && _git "${D}" commit -q -m base
+ _git "${D}" branch -M base
+ _git "${D}" checkout -q -b change
+ mkdir -p "${D}/lib/Search/Controller"
+ _git "${D}" mv lib/Controller/ThingController.php lib/Search/Controller/ThingController.php
+ sed -i 's/^namespace OCA\\CompFx\\Controller;/namespace OCA\\CompFx\\Search\\Controller;/' "${D}/lib/Search/Controller/ThingController.php"
+ [ "${_variant}" = "with-alias" ] && _put "${D}" appinfo/class-aliases.json "$(_aliases)"
+ _git "${D}" add -A && _git "${D}" commit -q -m move
+ if _run "${D}" --scope-to-diff --base base; then
+ if [ "${_variant}" = "with-alias" ]; then
+ _expect_gate 5 PASS "move with alias: gate 5 judges the moved routes and passes"
+ _expect_gate 14 PASS "move with alias: gate 14 resolves the moved routes"
+ else
+ _expect_gate 5 FAIL "move without alias: gate 5 fails on the orphaned routes"
+ _expect_gate 14 FAIL "move without alias: gate 14 fails on the orphaned routes"
+ fi
+ fi
+done
+
+# ---------------------------------------------------------------------------
+# 5. Gate 30: a monitoring route served by a controller under lib/Search/.
+# With no lib/Controller/ at all, the gate used to report NOT APPLICABLE.
+# ---------------------------------------------------------------------------
+E="${_WORK}/monitoring"
+_app "${E}"
+_put "${E}" appinfo/routes.php " [
+ ['name' => 'probe#index', 'url' => '/api/probe', 'verb' => 'GET'],
+]];
+"
+_put "${E}" appinfo/class-aliases.json '{"aliases": {"OCA\\CompFx\\Controller\\ProbeController": "OCA\\CompFx\\Search\\Controller\\ProbeController"}}
+'
+_put "${E}" lib/Search/Controller/ProbeController.php ' true]);
+ }
+}
+'
+_git "${E}" add -A && _git "${E}" commit -q -m base
+if _run "${E}"; then
+ _expect_gate 30 FAIL "gate 30: a monitoring route on a controller under lib/Search/ without #[PublicPage] fails"
+ _expect_log public-monitoring "lib/Search/Controller/ProbeController.php" "gate 30 names the moved controller"
+fi
+
+# ---------------------------------------------------------------------------
+# 6. Gate 48: #[NoCSRFRequired] dropped from a controller under lib/Search/
+# is a removal; the same controller only MOVED there is not.
+# ---------------------------------------------------------------------------
+_csrf_ctrl() { #
+ cat < \$id]);
+ }
+}
+PHP
+}
+for _variant in dropped moved; do
+ F="${_WORK}/csrf-${_variant}"
+ _app "${F}"
+ _put "${F}" appinfo/routes.php "$(_routes 0)"
+ if [ "${_variant}" = "dropped" ]; then
+ _put "${F}" appinfo/class-aliases.json "$(_aliases)"
+ _put "${F}" lib/Search/Controller/ThingController.php "$(_csrf_ctrl 'OCA\CompFx\Search\Controller' ' #[NoCSRFRequired]')"
+ else
+ _put "${F}" lib/Controller/ThingController.php "$(_csrf_ctrl 'OCA\CompFx\Controller' ' #[NoCSRFRequired]')"
+ fi
+ _git "${F}" add -A && _git "${F}" commit -q -m base
+ _git "${F}" branch -M base
+ _git "${F}" checkout -q -b change
+ if [ "${_variant}" = "dropped" ]; then
+ _put "${F}" lib/Search/Controller/ThingController.php "$(_csrf_ctrl 'OCA\CompFx\Search\Controller' '')"
+ else
+ mkdir -p "${F}/lib/Search/Controller"
+ _git "${F}" mv lib/Controller/ThingController.php lib/Search/Controller/ThingController.php
+ sed -i 's/^namespace OCA\\CompFx\\Controller;/namespace OCA\\CompFx\\Search\\Controller;/' "${F}/lib/Search/Controller/ThingController.php"
+ _put "${F}" appinfo/class-aliases.json "$(_aliases)"
+ fi
+ _git "${F}" add -A && _git "${F}" commit -q -m change
+ if _run "${F}" --scope-to-diff --base base; then
+ if [ "${_variant}" = "dropped" ]; then
+ _expect_gate 48 FAIL "gate 48: #[NoCSRFRequired] dropped under lib/Search/Controller is a removal"
+ else
+ _expect_gate 48 PASS "gate 48: moving a controller with #[NoCSRFRequired] intact is not a removal"
+ fi
+ fi
+done
+
+echo
+echo "test_gate_component_dirs.sh: ${_pass_n} passed, ${_fail_n} failed"
+[ "${_fail_n}" -eq 0 ]
diff --git a/hydra-gates/scripts/lib/test_gate_fq_route_names.sh b/hydra-gates/scripts/lib/test_gate_fq_route_names.sh
index f520a2b7..f91306d3 100755
--- a/hydra-gates/scripts/lib/test_gate_fq_route_names.sh
+++ b/hydra-gates/scripts/lib/test_gate_fq_route_names.sh
@@ -187,9 +187,18 @@ if _run "${FIXTURES}/fq-unbound"; then
_bad "fq-unbound: expected 2 findings, got ${_rr_n}: $(printf '%s' "${_RRLOG}" | tr '\n' '|')"
fi
- # gate-5 must not turn red on any of this: an unresolvable class is a
- # reachability defect, not an auth finding (ConductionNL/.github#153).
- _expect_gate 5 PASS "fq-unbound: the unresolvable class is not an auth finding either"
+ # An unresolvable class is not a missing auth attribute (.github#153), but
+ # it is not a pass either: no auth posture can be judged for a route whose
+ # controller no file declares. gate-5 fails on it under its own rule.
+ _expect_gate 5 FAIL "fq-unbound: gate-5 fails on the route whose controller no file declares"
+ case "$(_gate_line 5)" in
+ *"name a controller no file under lib/ declares"*) _ok "fq-unbound: gate-5 names it as an unfound controller" ;;
+ *) _bad "fq-unbound: gate-5 failed for another reason: $(_gate_line 5)" ;;
+ esac
+ case "$(_gate_line 5)" in
+ *"missing auth attribute"*) _bad "fq-unbound: the unresolvable class was counted as an auth finding" ;;
+ *) _ok "fq-unbound: the unresolvable class is not counted as a missing auth attribute" ;;
+ esac
fi
echo
diff --git a/hydra-gates/scripts/lib/test_gate_route_auth.sh b/hydra-gates/scripts/lib/test_gate_route_auth.sh
index 47298d28..35088a60 100644
--- a/hydra-gates/scripts/lib/test_gate_route_auth.sh
+++ b/hydra-gates/scripts/lib/test_gate_route_auth.sh
@@ -56,6 +56,7 @@ _bad() { _fail_n=$((_fail_n + 1)); printf 'FAIL — %s\n' "$1"; }
_OUT=""
_UNRES=""
_RRLOG=""
+_NOTFOUND=""
_LOGDIR=""
_run() {
local _dir="$1"; shift
@@ -73,6 +74,7 @@ _run() {
_OUT="$(HYDRA_GATE_LOG_DIR="${_logdir}" bash "${RUNNER}" "$@" "${_dir}" 2>&1 || true)"
_UNRES="$(cat "${_logdir}/hydra-gate-route-auth-unresolved.log" 2>/dev/null || true)"
_RRLOG="$(cat "${_logdir}/hydra-gate-route-reachability.log" 2>/dev/null || true)"
+ _NOTFOUND="$(cat "${_logdir}/hydra-gate-route-auth-controller-not-found.log" 2>/dev/null || true)"
_LOGDIR="${_logdir}"
if ! printf '%s' "${_OUT}" | grep -q '^\[hydra-gates\] COVERAGE:'; then
_bad "run in ${_dir} ABORTED before the summary — verdicts above it are not a result"
@@ -202,8 +204,12 @@ fi
# ---------------------------------------------------------------------------
if _run "${FIXTURES}/apphost-unguarded"; then
_expect_gate 5 FAIL "apphost-unguarded fixture: AppHost adoption does NOT exempt the app's own controllers"
- _expect_out 'gate-5 route-auth: 5 routed entr\(ies\) NOT JUDGED' \
+ _expect_out 'gate-5 route-auth: 4 routed entr\(ies\) NOT JUDGED' \
"apphost-unguarded fixture: the AppHost entries are still merely unjudged"
+ _expect_out 'also 1 routed method\(s\) missing auth attribute' \
+ "apphost-unguarded fixture: the unguarded method is still counted beside the unfound controller"
+ _expect_log "${_NOTFOUND}" '^gadget#run rule=routed-controller-not-found' \
+ "apphost-unguarded fixture: gate-5 fails gadget#run as an unfound controller, not the AppHost generics"
# AppHost adoption excuses the FIVE generics and nothing else. `gadget#run`
# names a class nobody provides — still a reachability defect.
_expect_gate 14 FAIL "apphost-unguarded fixture: a NON-generic missing controller is still raised"
@@ -222,9 +228,18 @@ fi
# an auth finding by the gate that cannot see the class.
# ---------------------------------------------------------------------------
if _run "${FIXTURES}/orphan-route"; then
- _expect_gate 5 PASS "orphan-route fixture: an unresolvable class is NOT an auth finding"
- _expect_out 'gate-5 route-auth: 2 routed entr\(ies\) NOT JUDGED' \
- "orphan-route fixture: both unresolvable entries are stated"
+ # An unfound class is not a missing auth attribute (.github#153), and it
+ # is not a pass either: gate-5 fails it under its own rule.
+ _expect_gate 5 FAIL "orphan-route fixture: a route whose controller no file declares fails gate-5"
+ _expect_log "${_NOTFOUND}" '^gadget#run rule=routed-controller-not-found' \
+ "orphan-route fixture: gate-5 names gadget#run as an unfound controller"
+ if printf '%s' "${_OUT}" | grep -E '^\[gate-5\]' | grep -q 'missing auth attribute'; then
+ _bad "orphan-route fixture: the unfound class was counted as a missing auth attribute"
+ else
+ _ok "orphan-route fixture: the unfound class is NOT an auth finding"
+ fi
+ _expect_out 'gate-5 route-auth: 1 routed entr\(ies\) NOT JUDGED' \
+ "orphan-route fixture: the absent method on a real class is still stated as not judged"
_expect_gate 14 FAIL "orphan-route fixture: gate-14 DOES raise the unreachable route"
_expect_log "${_RRLOG}" 'rule=controller-class-not-found' \
"orphan-route fixture: gate-14 log names controller-class-not-found"
@@ -255,7 +270,14 @@ if _run "${FIXTURES}/di-registered-generic"; then
else
_ok "di-registered-generic fixture: the DI-registered generic is NOT reported"
fi
- _expect_gate 5 PASS "di-registered-generic fixture: the absent generic is not an auth finding either"
+ _expect_gate 5 FAIL "di-registered-generic fixture: gadget#run, which nobody provides, fails gate-5"
+ _expect_log "${_NOTFOUND}" '^gadget#run rule=routed-controller-not-found' \
+ "di-registered-generic fixture: gate-5 names gadget#run as an unfound controller"
+ if printf '%s' "${_NOTFOUND}" | grep -q 'genericPreferences'; then
+ _bad "di-registered-generic fixture: the DI-registered generic was reported as unfound"
+ else
+ _ok "di-registered-generic fixture: the DI-registered generic is not reported as unfound"
+ fi
_expect_log "${_UNRES}" 'genericPreferences#getPreference' \
"di-registered-generic fixture: gate-5 states the generic was NOT JUDGED rather than dropping it"
fi
diff --git a/hydra-gates/scripts/lib/test_gate_route_registration.sh b/hydra-gates/scripts/lib/test_gate_route_registration.sh
index d10c2674..d0a89f69 100644
--- a/hydra-gates/scripts/lib/test_gate_route_registration.sh
+++ b/hydra-gates/scripts/lib/test_gate_route_registration.sh
@@ -230,8 +230,13 @@ if _run "${FIXTURES}/psr4-namespaced-controller-missing-method"; then
# THE CONTROL: the conventional sibling in the same repo still resolves.
_expect_not_log "${_RRLOG}" "PingController" \
"psr4-namespaced-controller-missing-method: the conventional ping#index route is unaffected"
- _expect_lines "${_RRLOG}" 1 \
- "psr4-namespaced-controller-missing-method: exactly ONE finding"
+ # Invariant 1 now opens controllers outside lib/Controller/ too, so the
+ # renamed method is ALSO an unrouted Response method on that class: two
+ # findings, one per invariant, both about the rename.
+ _expect_log "${_RRLOG}" "lib/AppHost/Controller/GenericHealthController\.php method=indexRenamed .*rule=missing-route" \
+ "psr4-namespaced-controller-missing-method: the renamed method is reported as unrouted"
+ _expect_lines "${_RRLOG}" 2 \
+ "psr4-namespaced-controller-missing-method: exactly TWO findings (one per invariant)"
fi
# ---------------------------------------------------------------------------
diff --git a/hydra-gates/scripts/lib/test_shipped_contracts_documented.py b/hydra-gates/scripts/lib/test_shipped_contracts_documented.py
new file mode 100644
index 00000000..4f7ab77e
--- /dev/null
+++ b/hydra-gates/scripts/lib/test_shipped_contracts_documented.py
@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: EUPL-1.2
+"""Every shipped OpenRegister contract is named where a consumer looks for it.
+
+Gate 67 keeps hydra-gates/contracts/ byte-identical with openregister's
+lib/Contract/. A consumer wires the files in by hand from the README: the
+table of shipped contracts, the test-bootstrap guard and the Psalm stubs. A
+file shipped in contracts/ but missing there is shipped and still unusable,
+which is how EmailLinkReaderInterface went unlisted after it landed.
+"""
+import os
+import unittest
+
+PKG = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+CONTRACTS = os.path.join(PKG, "contracts")
+
+
+class ShippedContractsDocumented(unittest.TestCase):
+ def setUp(self):
+ with open(os.path.join(PKG, "README.md"), encoding="utf-8") as fh:
+ self.readme = fh.read()
+ self.files = sorted(f for f in os.listdir(CONTRACTS) if f.endswith(".php"))
+
+ def test_the_contract_directory_is_not_empty(self):
+ self.assertIn("EmailLinkReaderInterface.php", self.files)
+ self.assertGreaterEqual(len(self.files), 5)
+
+ def test_every_contract_has_a_row_in_the_table(self):
+ for f in self.files:
+ self.assertIn(f"| `{f}` |", self.readme, f"{f} has no row in the README contracts table")
+
+ def test_every_contract_is_in_the_bootstrap_guard(self):
+ for f in self.files:
+ self.assertIn(f"'{f[:-4]}'", self.readme, f"{f} is missing from the README bootstrap guard")
+
+ def test_every_contract_is_a_psalm_stub(self):
+ for f in self.files:
+ self.assertIn(f"hydra-gates/contracts/{f}\" />", self.readme, f"{f} is missing from the README Psalm stubs")
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/hydra-gates/scripts/run-hydra-gates.sh b/hydra-gates/scripts/run-hydra-gates.sh
index 5fb9d826..442e5b09 100755
--- a/hydra-gates/scripts/run-hydra-gates.sh
+++ b/hydra-gates/scripts/run-hydra-gates.sh
@@ -1495,6 +1495,10 @@ _di_binds_fq_controller() {
# ---------------------------------------------------------------------------
_ctrl_path_from_name() {
local _name="$1"
+ if [ -n "${_HYDRA_ROUTED_CTRL[${_name}]:-}" ]; then
+ echo "${_HYDRA_ROUTED_CTRL[${_name}]}"
+ return 0
+ fi
case "${_name}" in
"${_HYDRA_APP_NS:-__no_app_ns__}"\\*)
# PSR-4: `OCA\\` maps to `lib/`. Strip the app prefix, turn
@@ -1766,6 +1770,117 @@ _head_block() {
_ROUTE_NAME_RX="'name'\s*=>\s*'[A-Za-z][A-Za-z0-9_\\]*#[a-zA-Z0-9_]+'"
_ROUTE_PAIR_RX="[A-Za-z][A-Za-z0-9_\\]*#[a-zA-Z0-9_]+"
+# ---------------------------------------------------------------------------
+# ROUTED CONTROLLERS, WHEREVER THEY LIVE UNDER lib/
+#
+# A routed controller is the class Nextcloud instantiates for a route name,
+# and that class need not sit in lib/Controller/: a component layout moves it
+# to lib//Controller/ and keeps the old name working through a
+# class alias. Measured on openregister#5519: with the Search controllers
+# moved, gate 5 parked 47 routes as "not judged" and still printed PASS, and
+# gates 7 and 14 no longer opened them at all.
+#
+# scripts/lib/controller_resolver.py resolves every route controller name in
+# appinfo/routes.php (plus the AppHost table when the app defers to it) the
+# way Nextcloud does, through appinfo/class-aliases.json and composer.json's
+# PSR-4 map. Run once per run; the answers are read from these tables.
+#
+# _HYDRA_ROUTED_CTRL[] -> file, empty when unresolved
+# _HYDRA_ROUTED_CTRL_FILES -> the resolved files, one per line
+# _HYDRA_CTRL_RESOLVER_OK -> 1 when the resolver finished
+# ---------------------------------------------------------------------------
+declare -A _HYDRA_ROUTED_CTRL=()
+_HYDRA_ROUTED_CTRL_FILES=""
+_HYDRA_CTRL_RESOLVER_OK=0
+if [ -f appinfo/routes.php ]; then
+ _hcr_out=$({
+ grep -oE "${_ROUTE_NAME_RX}" appinfo/routes.php | grep -oE "${_ROUTE_PAIR_RX}"
+ if [ "${_HYDRA_APPHOST_ROUTE_TABLE}" -eq 1 ]; then
+ printf '%s\n' ${_HYDRA_APPHOST_ROUTE_NAMES}
+ fi
+ } | cut -d'#' -f1 | sort -u \
+ | python3 "${SCRIPT_DIR}/lib/controller_resolver.py" . "${_HYDRA_APP_NS}" 2>/dev/null)
+ if printf '%s\n' "${_hcr_out}" | grep -qE '^# resolved [0-9]+ of [0-9]+$'; then
+ _HYDRA_CTRL_RESOLVER_OK=1
+ while IFS=$'\t' read -r _hcr_name _hcr_path; do
+ case "${_hcr_name}" in ''|'#'*) continue ;; esac
+ _HYDRA_ROUTED_CTRL["${_hcr_name}"]="${_hcr_path}"
+ [ -n "${_hcr_path}" ] && _HYDRA_ROUTED_CTRL_FILES="${_HYDRA_ROUTED_CTRL_FILES}${_hcr_path}${_NL}"
+ done <<< "${_hcr_out}"
+ _HYDRA_ROUTED_CTRL_FILES=$(printf '%s' "${_HYDRA_ROUTED_CTRL_FILES}" | sort -u)
+ else
+ echo "[hydra-gates] WARNING: controller_resolver.py did not finish; routed controllers outside lib/Controller/ are located by name only."
+ fi
+fi
+
+# _routed_names_for — the route controller names that resolve to .
+_routed_names_for() {
+ local _k
+ for _k in "${!_HYDRA_ROUTED_CTRL[@]}"; do
+ [ "${_HYDRA_ROUTED_CTRL[${_k}]}" = "$1" ] && printf '%s\n' "${_k}"
+ done
+}
+
+# _lib_dirs_named ... — lib/ plus every tracked directory under
+# lib/ whose last segment is one of , e.g. lib/Search/Service for
+# `Service`. Gates that judge a class role by its directory read their files
+# from these, so a component layout (lib///) is covered.
+_lib_dirs_named() {
+ local _alt _n
+ _alt=$(IFS='|'; printf '%s' "$*")
+ for _n in "$@"; do printf 'lib/%s\n' "${_n}"; done
+ if git -c safe.directory='*' rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+ git -c safe.directory='*' ls-files -- lib 2>/dev/null \
+ | awk -F/ -v re="^(${_alt})$" '{ p = $1; for (i = 2; i < NF; i++) { p = p "/" $i; if ($i ~ re) print p } }'
+ elif [ -d lib ]; then
+ find lib -type d \( -path '*/vendor' -o -path '*/node_modules' \) -prune -o -type d -print 2>/dev/null \
+ | awk -F/ -v re="^(${_alt})$" '$NF ~ re'
+ fi | sort -u
+}
+
+# _enum_role ... — `_enum_tracked` or
+# `_enum_scoped` over every directory `_lib_dirs_named ...` lists.
+_enum_role() {
+ local _mode="$1" _re="$2" _dirs
+ shift 2
+ mapfile -t _dirs < <(_lib_dirs_named "$@")
+ if [ "${_mode}" = "scoped" ]; then
+ _enum_scoped "${_re}" "${_dirs[@]}"
+ else
+ _enum_tracked "${_re}" "${_dirs[@]}"
+ fi
+}
+
+# _enum_controllers — every controller file a controller gate
+# judges: PHP under any Controller directory in lib/, plus every routed
+# controller the resolver found elsewhere. `scoped` keeps those in the diff.
+_enum_controllers() {
+ {
+ if [ "$1" = "scoped" ]; then
+ _enum_role scoped '\.php$' Controller
+ else
+ _enum_role tracked '\.php$' Controller
+ fi
+ printf '%s\n' "${_HYDRA_ROUTED_CTRL_FILES}" | while IFS= read -r _f; do
+ [ -n "${_f}" ] && [ -f "${_f}" ] || continue
+ [ "$1" = "scoped" ] && { _in_scope "${_f}" || continue; }
+ printf '%s\n' "${_f}"
+ done
+ } | sort -u
+}
+
+# 1 when the diff deletes or renames a controller file. The route table is the
+# only place its routes are named, so such a change puts every route back in
+# scope for the route gates: a move that leaves a route pointing nowhere is
+# a 500 at request time.
+_HYDRA_CTRL_MOVED=0
+if [ "${HAVE_DELTA_BASE}" = "1" ] && [ -n "${BASE_REF}" ]; then
+ if git -c safe.directory='*' diff --name-status -M --diff-filter=DR "${BASE_REF}...HEAD" -- lib 2>/dev/null \
+ | awk -F'\t' '{print $2}' | grep -qE 'Controller\.php$'; then
+ _HYDRA_CTRL_MOVED=1
+ fi
+fi
+
_FAILED=0
_EMITTED_GATES=""
# _SKIPPED_GATES holds the gates that skipped for a reason that COUNTS against
@@ -2311,13 +2426,13 @@ fi
# over a comment-masked body with matched braces. Delegation passes; padding
# does not.
_stub_ran=1
-if [ -d lib/BackgroundJob ]; then
+if [ -n "$(_enum_role tracked '\.php$' BackgroundJob | head -1)" ]; then
_stub_helper="${SCRIPT_DIR}/lib/check_stub_run_body.py"
_stub_jobs=()
while IFS= read -r job; do
[ -f "${job}" ] || continue
_stub_jobs+=("${job}")
- done < <(_enum_scoped '\.php$' lib/BackgroundJob)
+ done < <(_enum_role scoped '\.php$' BackgroundJob)
if [ "${#_stub_jobs[@]}" -eq 0 ]; then
: # nothing in scope.
elif [ ! -f "${_stub_helper}" ]; then
@@ -2497,7 +2612,7 @@ while IFS= read -r f; do
fi
fi
done
-done < <(_enum_scoped '\.php$' lib/Service lib/Controller)
+done < <(_enum_role scoped '\.php$' Service Controller)
# AN ARM THAT SILENTLY DID NOT RUN IS NOT A PASS. The caller-identity arm above
# `continue`s on every file whose comment mask cannot be produced, so without
# this the gate would print PASS with one of its four arms switched off and no
@@ -2839,6 +2954,15 @@ if [ -f appinfo/routes.php ]; then
# Touching appinfo/routes.php puts every routed method back in scope.
_ra_routes_touched=0
_in_scope "appinfo/routes.php" && _ra_routes_touched=1
+ _in_scope "appinfo/class-aliases.json" && _ra_routes_touched=1
+ _in_scope "composer.json" && _ra_routes_touched=1
+ [ "${_HYDRA_CTRL_MOVED}" -eq 1 ] && _ra_routes_touched=1
+ # A routed controller no file declares is never a pass: its auth posture
+ # cannot be judged and the route answers 500. Counted apart from the
+ # missing-attribute findings, and judged whenever the route table, the
+ # class map or a controller's location changed (or on a full run).
+ _ra_notfound_log=${HYDRA_GATE_LOG_DIR}/hydra-gate-route-auth-controller-not-found.log
+ : > "${_ra_notfound_log}"
# WHAT THIS GATE READS UNDER --scope-to-diff (2026-09-12). A routed method
# is judged when the diff touched the controller that serves it OR
# appinfo/routes.php itself; routes.php is read in full either way, because
@@ -2871,6 +2995,8 @@ if [ -f appinfo/routes.php ]; then
if _apphost_serves "${ctrl}" || _di_binds_controller "${path}" \
|| _di_binds_fq_controller "${ctrl}"; then
echo "${ctrl}#${method} — served by the OpenRegister AppHost generic controller (ADR-040); its auth attribute lives in the openregister package and is NOT visible from this repository" >> "${_ra_unresolved_log}"
+ elif [ "${_ra_routes_touched}" -eq 1 ]; then
+ echo "${ctrl}#${method} rule=routed-controller-not-found — no file under lib/ declares the class this route instantiates (looked for ${path}, the PSR-4 map and appinfo/class-aliases.json)" >> "${_ra_notfound_log}"
else
echo "${ctrl}#${method} — ${path} is not present in this repository; controller class UNRESOLVED (see gate-14, which owns route reachability)" >> "${_ra_unresolved_log}"
fi
@@ -2938,13 +3064,14 @@ if [ -f appinfo/routes.php ]; then
done < <(grep -oE "${_ROUTE_NAME_RX}" appinfo/routes.php \
| grep -oE "${_ROUTE_PAIR_RX}" | sort -u)
_ra_fail=$(_count '.' "${_ra_log}")
+ _ra_notfound=$(_count '.' "${_ra_notfound_log}")
_ra_unres=$(_count '.' "${_ra_unresolved_log}")
# Stated, never folded into the verdict. Does NOT start with `[gate-` so it
# cannot be mistaken for a verdict line by any `^\[gate-` consumer.
if [ "${_ra_unres}" -gt 0 ]; then
echo "[hydra-gates] gate-5 route-auth: ${_ra_unres} routed entr(ies) NOT JUDGED (controller class unresolvable here) — see ${_ra_unresolved_log}. This is not a pass for them; reachability is gate-14's."
fi
- if [ "${_ra_ran}" -eq 1 ] && [ "${_ra_judged}" -eq 0 ]; then
+ if [ "${_ra_ran}" -eq 1 ] && [ "${_ra_judged}" -eq 0 ] && [ "${_ra_notfound}" -eq 0 ]; then
# An empty scope is not a clean tree — see the gate-1 note. Measured on
# larpingapp: a README-only commit run with --scope-to-diff reported
# `[gate-5] route-auth: PASS` having judged zero routed methods.
@@ -2952,7 +3079,9 @@ if [ -f appinfo/routes.php ]; then
_skip 5 "route-auth" na "0 routed method(s) were judged — appinfo/routes.php is not in this diff and no controller serving a route is either, so under ADR-020 no endpoint's auth posture changed in this PR. ${_ra_unres} entr(ies) were additionally unresolvable here."
fi
if [ "${_ra_ran}" -eq 1 ]; then
- if [ "${_ra_fail}" -eq 0 ]; then
+ if [ "${_ra_notfound}" -gt 0 ]; then
+ _fail 5 "route-auth" "${_ra_notfound} routed entr(ies) name a controller no file under lib/ declares, so their auth posture CANNOT be judged and the route fails at request time — see ${_ra_notfound_log}$([ "${_ra_fail}" -gt 0 ] && printf '; also %s routed method(s) missing auth attribute — see %s' "${_ra_fail}" "${_ra_log}")"
+ elif [ "${_ra_fail}" -eq 0 ]; then
_pass 5 "route-auth"
else
_fail 5 "route-auth" "${_ra_fail} routed method(s) missing auth attribute — see ${_ra_log}"
@@ -2995,7 +3124,7 @@ while IFS= read -r f; do
[ -f "$f" ] || continue
_in_scope "$f" || continue
_oa_files+=("$f")
-done < <(_enum_tracked '\.php$' lib/Service lib/Controller)
+done < <(_enum_role tracked '\.php$' Service Controller)
_oa_ran=1
# An EMPTY scope is not a clean tree. With zero files the log stays empty, the
# count is 0, and the gate used to report PASS having inspected nothing — the
@@ -3114,7 +3243,7 @@ while IFS= read -r f; do
[ -f "$f" ] || continue
_in_scope "$f" || continue
_idor_files+=("$f")
-done < <(_enum_tracked '\.php$' lib/Controller)
+done < <(_enum_controllers tracked)
_idor_ran=1
# See the gate-6 note above: an empty scope inspected nothing, so it cannot be
# a PASS. SKIPPED keeps it out of _EMITTED_GATES and therefore visible in the
@@ -3273,7 +3402,7 @@ while IFS= read -r f; do
[ -f "$f" ] || continue
_in_scope "$f" || continue
_uar_files+=("$f")
-done < <(_enum_tracked '\.php$' lib/Service lib/Controller)
+done < <(_enum_role tracked '\.php$' Service Controller)
_uar_ran=1
_uar_helper="${SCRIPT_DIR}/lib/check_unsafe_auth_resolver.py"
if [ "${#_uar_files[@]}" -eq 0 ]; then
@@ -3333,7 +3462,7 @@ while IFS= read -r f; do
[ -f "$f" ] || continue
_in_scope "$f" || continue
_sem_files+=("$f")
-done < <(_enum_tracked '\.php$' lib/Controller)
+done < <(_enum_controllers tracked)
_sem_ran=1
if [ "${#_sem_files[@]}" -eq 0 ]; then
# An empty scope is not a clean tree — see the gate-1 note.
@@ -3762,7 +3891,7 @@ fi
# pre-22c5625ef). That requires semantic understanding beyond static
# analysis; owned by code-review runtime semantics + ADR-005.
# ---------------------------------------------------------------------------
-if [ -d lib/Controller ] && [ -f appinfo/routes.php ]; then
+if [ -f appinfo/routes.php ] && [ -n "$(_enum_controllers tracked | head -1)" ]; then
_rr_log=${HYDRA_GATE_LOG_DIR}/hydra-gate-route-reachability.log
: > "${_rr_log}"
# One line per route this gate actually judged — see the note at the loop.
@@ -3773,6 +3902,9 @@ if [ -d lib/Controller ] && [ -f appinfo/routes.php ]; then
# invariant 2 — see the scope note at that loop.
_rr_routes_touched=0
_in_scope "appinfo/routes.php" && _rr_routes_touched=1
+ _in_scope "appinfo/class-aliases.json" && _rr_routes_touched=1
+ _in_scope "composer.json" && _rr_routes_touched=1
+ [ "${_HYDRA_CTRL_MOVED}" -eq 1 ] && _rr_routes_touched=1
# WHAT THIS GATE READS UNDER --scope-to-diff (2026-09-12). This gate
# genuinely needs more than the changed files: a route for a changed
# controller method may sit anywhere in appinfo/routes.php, and a changed
@@ -3864,17 +3996,23 @@ if [ -d lib/Controller ] && [ -f appinfo/routes.php ]; then
# Derive the controller route slug — strip lib/Controller/ prefix +
# Controller.php suffix, lowercase the first character. Settings/
# subnamespace becomes `Settings\Foo`.
- _ctrl_short=$(echo "${_ctrl_path}" | sed -e 's|^lib/Controller/||' -e 's|Controller\.php$||')
+ _ctrl_short=$(echo "${_ctrl_path}" | sed -e 's|^lib/Controller/||' -e 's|^lib/||' -e 's|Controller\.php$||')
case "${_ctrl_short}" in
Settings/*) _ctrl_slug="Settings\\$(echo "${_ctrl_short}" | sed 's|^Settings/||')";;
*/*) _ctrl_slug=$(echo "${_ctrl_short}" | sed 's|/|\\|g'); _ctrl_slug=$(echo "${_ctrl_slug}" | awk -F'\\\\' '{for(i=1;i> "${_rr_log}"
fi
done
- done < <(_enum_scoped 'Controller\.php$' lib/Controller)
+ done < <(_enum_controllers scoped | grep -E 'Controller\.php$')
# ---- Invariant 2: every routed entry resolves to a method that exists.
#
@@ -5521,7 +5666,7 @@ if [ -f appinfo/routes.php ]; then
elif [ "${_cc_fail}" -eq 3 ]; then
# EMPTY SCOPE — `na`, not structural (#268). See _skip's header.
_cc_ran=0
- _skip 25 "contract-coverage" na "the diff against '${BASE_REF}' touched NO lib/Controller file, so no endpoint was inspected. Diff-scoped out under ADR-020, exactly as gates 6/7 are for the same diff — not a gap: this PR exposes no new endpoint whose wire contract could be untested. This gate runs on the next PR that touches a controller. See ${_cc_log}."
+ _skip 25 "contract-coverage" na "the diff against '${BASE_REF}' touched NO controller file under lib/, so no endpoint was inspected. Diff-scoped out under ADR-020, exactly as gates 6/7 are for the same diff — not a gap: this PR exposes no new endpoint whose wire contract could be untested. This gate runs on the next PR that touches a controller. See ${_cc_log}."
elif [ "${_cc_fail}" -eq 4 ]; then
_cc_ran=0
_skip 25 "contract-coverage" na "no appinfo/routes.php — this app exposes no routed endpoint whose wire contract could be tested."
@@ -6087,7 +6232,9 @@ _pm_targets=0
_pm_scoped=0
_pm_inspected=0
_pm_absent=0
-if [ -f appinfo/routes.php ] && [ -d lib/Controller ]; then
+_pm_has_ctrl=0
+[ -n "$(_enum_controllers tracked | head -1)" ] && _pm_has_ctrl=1
+if [ -f appinfo/routes.php ] && [ "${_pm_has_ctrl}" -eq 1 ]; then
# Pull every route entry as `nameurlverb`. A route's url and verb
# are part of the evidence now (see (c) above), and grepping the name alone
# cannot see them. Entries are one-per-line in every fleet routes.php, but
@@ -6270,8 +6417,8 @@ elif [ "${_pm_inspected}" -gt 0 ]; then
# as gate-5's NOT-JUDGED line.
echo "[hydra-gates] gate-30 public-monitoring: ${_pm_inspected} monitoring endpoint(s) inspected of ${_pm_candidates} name-matched candidate(s)${_pm_targets:+; ${_pm_targets} scrape target(s)}. See ${_pm_notes} for every candidate this run did NOT judge, and why."
_pass 30 "public-monitoring"
-elif [ ! -f appinfo/routes.php ] || [ ! -d lib/Controller ]; then
- _skip 30 "public-monitoring" na "no appinfo/routes.php + lib/Controller in this repository — there is no routed monitoring endpoint to judge."
+elif [ ! -f appinfo/routes.php ] || [ "${_pm_has_ctrl}" -eq 0 ]; then
+ _skip 30 "public-monitoring" na "no appinfo/routes.php + a controller under lib/ in this repository — there is no routed monitoring endpoint to judge."
elif [ "${_pm_candidates}" -eq 0 ]; then
_skip 30 "public-monitoring" na "appinfo/routes.php declares no route whose name contains metrics/health/liveness/readiness/probe."
elif [ "${_pm_targets}" -eq 0 ]; then
@@ -8551,13 +8698,21 @@ elif [ "${HAVE_DELTA_BASE}" = "1" ]; then
# The pathspec is the SAME STRING the gate itself uses, on purpose: this
# guard cannot drift away from the enumerator it defends without the two
# visibly disagreeing in one file.
- _csrf_cand=$(git diff --name-only "${BASE_REF}...HEAD" -- 'lib/Controller/*.php' 2>/dev/null | grep -c . 2>/dev/null || true)
+ # Controllers anywhere under lib/: every Controller directory, plus the
+ # routed controllers the resolver found elsewhere. `-M` makes a moved
+ # controller a rename rather than a deleted file whose every attribute
+ # line reads as removed.
+ _csrf_paths=('lib/Controller/*.php' ':(glob)lib/**/Controller/**/*.php')
+ while IFS= read -r _f; do
+ [ -n "${_f}" ] && _csrf_paths+=("${_f}")
+ done <<< "${_HYDRA_ROUTED_CTRL_FILES}"
+ _csrf_cand=$(git diff -M --name-only "${BASE_REF}...HEAD" -- "${_csrf_paths[@]}" 2>/dev/null | grep -c . 2>/dev/null || true)
_csrf_cand="${_csrf_cand%%$'\n'*}"
case "${_csrf_cand}" in ''|*[!0-9]*) _csrf_cand=0 ;; esac
if [ "${_csrf_cand}" -eq 0 ]; then
_csrf_ran=0
_csrf_removed=""
- _skip 48 "csrf-cochange" na "the diff against '${BASE_REF}' touches NO lib/Controller/*.php, so there was no controller for a #[NoCSRFRequired] to be dropped FROM — NOT ONE controller line was read by this run. A removal is a property of a change set, and this change set contains no candidate for one. This is NOT a clean bill of health for the app's CSRF posture; it runs on the next change that touches a controller."
+ _skip 48 "csrf-cochange" na "the diff against '${BASE_REF}' touches NO controller (NO lib/Controller/*.php, and none elsewhere under lib/), so there was no controller for a #[NoCSRFRequired] to be dropped FROM — NOT ONE controller line was read by this run. A removal is a property of a change set, and this change set contains no candidate for one. This is NOT a clean bill of health for the app's CSRF posture; it runs on the next change that touches a controller."
elif [ ! -f "${_csrf_helper}" ]; then
# A MISSING HELPER MUST NOT REPORT PASS (#147). Without it the gate
# sees no removals at all and goes green on every diff.
@@ -8582,7 +8737,7 @@ elif [ "${HAVE_DELTA_BASE}" = "1" ]; then
# than a false pass, but the right image is cheap to name.
_csrf_mb=$(git merge-base "${BASE_REF}" HEAD 2>/dev/null || true)
[ -n "${_csrf_mb}" ] || _csrf_mb="${BASE_REF}"
- _csrf_removed=$(git diff -U0 "${BASE_REF}...HEAD" -- 'lib/Controller/*.php' 2>/dev/null \
+ _csrf_removed=$(git diff -M -U0 "${BASE_REF}...HEAD" -- "${_csrf_paths[@]}" 2>/dev/null \
| python3 "${_csrf_helper}" --repo . --base "${_csrf_mb}" 2>"${_csrf_err}")
_csrf_rc=$?
if [ "${_csrf_rc}" -ne 0 ]; then
@@ -8826,7 +8981,7 @@ while IFS= read -r f; do
[ -f "$f" ] || continue
_in_scope "$f" || continue
_cxt_files+=("$f")
-done < <(_enum_tracked '\.php$' lib/Controller)
+done < <(_enum_controllers tracked)
_cxt_rc=0
if [ "${#_cxt_files[@]}" -gt 0 ]; then
# A CRASHED CHECKER MUST NOT REPORT PASS (#147 / #249 / #262). The status
@@ -10312,7 +10467,7 @@ while IFS= read -r f; do
_owc_present=$((_owc_present + 1))
_in_scope "$f" || continue
_owc_files+=("$f")
-done < <(_enum_tracked '\.php$' lib/Service | grep -v '/tests/')
+done < <(_enum_role tracked '\.php$' Service | grep -v '/tests/')
_owc_ran=1
# An unopened scope is not a PASS — see gate 56 above (.github#276).
if [ "${#_owc_files[@]}" -eq 0 ]; then
@@ -12787,7 +12942,7 @@ _fnt_rc=$?
set +e
if [ "${_fnt_rc}" -eq 4 ]; then
- _skip 111 "flow-node-taxonomy" na "this repo ships no lib/Service/Flow/Nodes/, so it contributes no flow node of its own. A node it contributes from ANOTHER repository is deliberately not this gate's business — 38 of 65 step types on a measured instance are, and firing on them would be unfixable from the PR it fired on. See ${_fnt_log}."
+ _skip 111 "flow-node-taxonomy" na "this repo ships no lib/Service/Flow/Nodes/ (nor lib//Service/Flow/Nodes/), so it contributes no flow node of its own. A node it contributes from ANOTHER repository is deliberately not this gate's business — 38 of 65 step types on a measured instance are, and firing on them would be unfixable from the PR it fired on. See ${_fnt_log}."
elif [ "${_fnt_rc}" -eq 0 ]; then
_pass 111 "flow-node-taxonomy"
elif ! _helper_finished "${_fnt_log}" '^checked [0-9]+ flow node'; then
@@ -13895,8 +14050,8 @@ _a11y_has_markup_dir || _declare_na "no src/, templates/ or appinfo/templates/
# `if [ -f appinfo/routes.php ]` — gates 5 25
[ -f appinfo/routes.php ] || _declare_na "no appinfo/routes.php — this repo registers no HTTP routes, so there is no endpoint for this gate to inspect." \
5 25
-# `if [ -d lib/Controller ] && [ -f appinfo/routes.php ]` — gate 14
-{ [ -d lib/Controller ] && [ -f appinfo/routes.php ]; } || _declare_na "no lib/Controller/ and appinfo/routes.php pair — there is no controller-to-route mapping for this gate to resolve." \
+# `if [ -f appinfo/routes.php ] && ` — gate 14
+{ [ -f appinfo/routes.php ] && [ -n "$(_enum_controllers tracked | head -1)" ]; } || _declare_na "no appinfo/routes.php with a controller under lib/ — there is no controller-to-route mapping for this gate to resolve." \
14
# `if [ -f src/manifest.json ]` — gates 15 22 53 68
[ -f src/manifest.json ] || _declare_na "no src/manifest.json — this repo declares no manifest, so there are no pages, widgets or handler references for this gate to inspect." \
diff --git a/hydra-gates/tests/helper-suite-timings.tsv b/hydra-gates/tests/helper-suite-timings.tsv
index ec9065a5..632eb078 100644
--- a/hydra-gates/tests/helper-suite-timings.tsv
+++ b/hydra-gates/tests/helper-suite-timings.tsv
@@ -64,11 +64,13 @@ test_check_spec_coverage.py 0
test_check_stale_fleet_app_id.py 1
test_check_store_and_settings_surface.py 0
test_check_stub_run_body.py 0
+test_check_system_elevation.py 0
test_check_table_headers.py 0
test_check_unclosable_gate.py 0
test_check_unsafe_auth_resolver.py 0
test_check_visual_coverage.py 2
test_checker_patterns_match_documented_shapes.py 1
+test_controller_resolver.py 0
test_detect_redundant_controllers.py 0
test_diff_schema_strictness.js 1
test_exclusion_reason.py 1
@@ -110,6 +112,7 @@ test_gate_a11y_helper_wiring.sh 122
test_gate_a11y_markup_scope.sh 12
test_gate_acceptance_matrix.sh 124
test_gate_base_ref_delivery_channel.sh 14
+test_gate_component_dirs.sh 60
test_gate_crashed_checker_is_not_a_finding.sh 210
test_gate_diff_provenance.sh 20
test_gate_discarded_counts_and_empty_deltas.sh 48
@@ -137,5 +140,6 @@ test_manifest_scope_filter.js 0
test_or_abstraction_exceptions.sh 2
test_or_abstraction_pdok.sh 1
test_php_template_scope.py 0
+test_shipped_contracts_documented.py 0
test_source_scope.py 0
test_vendored_schema_freshness.js 1