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