Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions hydra-gates/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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

Expand All @@ -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';
Expand Down Expand Up @@ -274,6 +276,7 @@ the autoloader is precisely the defect this change removed.
<file name="vendor/conduction/hydra-gates/hydra-gates/contracts/ObjectEntityInterface.php" />
<file name="vendor/conduction/hydra-gates/hydra-gates/contracts/RegisterSlugResolverInterface.php" />
<file name="vendor/conduction/hydra-gates/hydra-gates/contracts/RegisterSlugResolution.php" />
<file name="vendor/conduction/hydra-gates/hydra-gates/contracts/EmailLinkReaderInterface.php" />
</stubs>
```

Expand Down
45 changes: 33 additions & 12 deletions hydra-gates/scripts/lib/check_contract_coverage.py
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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*.

Expand Down Expand Up @@ -465,15 +479,15 @@ 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.

Each dict: {ref, controller_path, method, url, contract_status, reason}.
"""
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():
Expand All @@ -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:
Expand All @@ -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
Expand Down Expand Up @@ -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]:
Expand All @@ -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]]:
Expand All @@ -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:
Expand Down Expand Up @@ -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(
Expand All @@ -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)
Expand Down
30 changes: 21 additions & 9 deletions hydra-gates/scripts/lib/check_flow_node_taxonomy.py
Original file line number Diff line number Diff line change
Expand Up @@ -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/<Component>/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.
Expand All @@ -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)
Expand Down
26 changes: 24 additions & 2 deletions hydra-gates/scripts/lib/check_orphan_auth.py
Original file line number Diff line number Diff line change
Expand Up @@ -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


# ---------------------------------------------------------------------------
Expand Down Expand Up @@ -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
Expand All @@ -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:
Expand All @@ -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
Expand Down
17 changes: 13 additions & 4 deletions hydra-gates/scripts/lib/check_sig_maintainability.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down
31 changes: 21 additions & 10 deletions hydra-gates/scripts/lib/check_spec_coverage.py
Original file line number Diff line number Diff line change
Expand Up @@ -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/<Layer>/ or one
component down at lib/<Component>/<Layer>/ (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+)*"
Expand Down Expand Up @@ -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)


Expand Down Expand Up @@ -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("*"):
Expand All @@ -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):
Expand Down Expand Up @@ -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):
Expand Down Expand Up @@ -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):
Expand Down
Loading
Loading