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
44 changes: 43 additions & 1 deletion hydra-gates/scripts/lib/check_openregister_contract_parity.py
Original file line number Diff line number Diff line change
Expand Up @@ -40,10 +40,16 @@
A repo with no lib/Contract/ does not own the contract and is skipped; it is not
judged, so it is not reported as a pass.

Only OpenRegister publishes this contract, so only OpenRegister is judged. Other
apps may keep their own interfaces in lib/Contract/ (opencatalogi does), and
comparing those against hydra-gates/contracts/ reports drift in a contract they
do not own. The repository is identified by `<id>` in appinfo/info.xml, with the
composer package name as the fallback when info.xml is absent or unreadable.

Exit codes
0 the copies agree
1 they differ -- see the FAIL lines
3 no lib/Contract/ -- this repo does not own the contract
3 not applicable: no lib/Contract/, or the repository is not OpenRegister
4 lib/Contract/ exists but no shipped copy was found in any of the three
locations. NOT a pass: nothing was verified.

Expand All @@ -54,7 +60,9 @@

from __future__ import annotations

import json
import sys
import xml.etree.ElementTree as ET
from pathlib import Path

# Where each copy lives, relative to the repository root.
Expand All @@ -78,6 +86,29 @@
RUNNER_DIR = Path(__file__).resolve().parent.parent.parent / "contracts"


# The app that publishes the contract, as named by appinfo/info.xml and composer.
OWNER_APP_ID = "openregister"


def _app_identity(root: Path) -> tuple[str | None, str]:
"""Return (app id, where it was read) from info.xml, else from composer.json."""
try:
app_id = ET.parse(root / "appinfo" / "info.xml").getroot().findtext("id")
except (OSError, ET.ParseError):
app_id = None
if app_id and app_id.strip():
return app_id.strip(), "appinfo/info.xml <id>"

try:
name = json.loads((root / "composer.json").read_text(encoding="utf-8")).get("name")
except (OSError, ValueError, AttributeError):
name = None
if isinstance(name, str) and name.strip():
return name.strip().rsplit("/", 1)[-1], "composer.json name"

return None, "no appinfo/info.xml <id> and no composer.json name"


def _php_files(directory: Path) -> dict[str, Path]:
"""Map basename -> path for every .php file directly in `directory`."""
if not directory.is_dir():
Expand All @@ -104,6 +135,17 @@ def main(argv: list[str]) -> int:
print("checked 0 file(s)")
return 3

app_id, source = _app_identity(root)
if app_id != OWNER_APP_ID:
print(
f"SKIP lib/Contract/ here is this app's own, not the OpenRegister "
f"contract (app id {app_id or 'unknown'}, from {source}). Only "
f"{OWNER_APP_ID} publishes the contract, so there is nothing to "
"keep in step."
)
print("checked 0 file(s)")
return 3

# Order matters. The consumer's own vendor/ wins when it exists, so an app
# that pins an older hydra-gates is judged against the version it actually
# installs. Only then fall back to the copy shipped with this script.
Expand Down
71 changes: 71 additions & 0 deletions hydra-gates/scripts/lib/test_gate67_contract_parity_scope.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
#!/usr/bin/env bash
# Gate 67 scope — only OpenRegister is judged.
#
# Any app may keep its own interfaces in lib/Contract/. The gate compares that
# directory with hydra-gates/contracts/, which is OpenRegister's published
# contract, so in any other app it reports drift the app neither owns nor can
# fix. The foreign-app tree proves the gate says NOT APPLICABLE there, and the
# composer-only tree proves that OpenRegister named only by composer.json is
# still judged.
#
# SPDX-FileCopyrightText: 2026 Conduction B.V. <info@conduction.nl>
# SPDX-License-Identifier: EUPL-1.2
set -uo pipefail

HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
CHECKER="${HERE}/check_openregister_contract_parity.py"
RUNNER="${HERE}/../run-hydra-gates.sh"
FIXTURES="${HERE}/../test-fixtures/gate-acceptance/openregister-contract-parity"

fails=0

expect() {
local tree="$1" want_rc="$2" want_fails="$3" why="$4"
local out rc got

out="$(python3 "${CHECKER}" "${FIXTURES}/${tree}" 2>&1)"
rc=$?
got="$(printf '%s\n' "${out}" | grep -c '^FAIL ')"

if [ "${rc}" -ne "${want_rc}" ] || [ "${got}" -ne "${want_fails}" ]; then
echo "FAIL ${tree}: expected rc=${want_rc} with ${want_fails} finding(s), got rc=${rc} with ${got}"
echo " ${why}"
printf '%s\n' "${out}" | sed 's/^/ | /'
fails=$((fails + 1))
return
fi

# The runner reads a missing terminal line as a crash, so every exit must print it.
if ! printf '%s\n' "${out}" | grep -qE '^checked [0-9]+ file\(s\)$'; then
echo "FAIL ${tree}: the checker never printed 'checked N file(s)', so the runner would report a crash"
fails=$((fails + 1))
return
fi

echo "ok ${tree}: rc=${rc}, ${got} finding(s) — ${why}"
}

expect planted 1 3 "openregister with three kinds of drift is judged"
expect clean 0 0 "openregister with byte-identical copies passes"
expect foreign-app 3 0 "another app's own lib/Contract/ is NOT APPLICABLE, even when it differs"
expect composer-only 1 1 "openregister named only by composer.json is still judged"

# Through the real runner: the verdict must be NOT APPLICABLE and say why.
logs="$(mktemp -d "${TMPDIR:-/tmp}/hydra-gate67.XXXXXXXX")"
line="$(HYDRA_GATE_LOG_DIR="${logs}" bash "${RUNNER}" "${FIXTURES}/foreign-app" 2>&1 \
| grep -m1 -E '^\[gate-67\] ')"
rm -rf "${logs}"
case "${line}" in
*"NOT APPLICABLE"*"this app's own, not the OpenRegister contract"*)
echo "ok runner over foreign-app: ${line:0:110}" ;;
*)
echo "FAIL runner over foreign-app: wanted NOT APPLICABLE with the app's-own reason, got: ${line:-<no gate-67 line>}"
fails=$((fails + 1)) ;;
esac

if [ "${fails}" -ne 0 ]; then
echo "gate-67 scope: ${fails} case(s) failed"
exit 1
fi

echo "gate-67 scope: all cases behaved"
5 changes: 4 additions & 1 deletion hydra-gates/scripts/run-hydra-gates.sh
Original file line number Diff line number Diff line change
Expand Up @@ -11140,7 +11140,10 @@ if ! grep -qE '^checked [0-9]+ file\(s\)$' "${_orcp_log}" 2>/dev/null; then
elif [ "${_orcp_rc}" -eq 0 ]; then
_pass 67 "openregister-contract-parity"
elif [ "${_orcp_rc}" -eq 3 ]; then
_skip 67 "openregister-contract-parity" na "no lib/Contract/ — this repo does not own the OpenRegister contract, so it has nothing to keep in step."
# Two reasons share code 3: no lib/Contract/, or a lib/Contract/ that is
# another app's own. The checker's SKIP line says which.
_orcp_why=$(grep -m1 '^SKIP ' "${_orcp_log}" 2>/dev/null | sed 's/^SKIP //')
_skip 67 "openregister-contract-parity" na "${_orcp_why:-this repo does not own the OpenRegister contract, so it has nothing to keep in step.}"
elif [ "${_orcp_rc}" -eq 4 ]; then
_skip 67 "openregister-contract-parity" na "lib/Contract/ exists but no shipped copy was found to compare it against. NOT a pass — nothing was verified."
else
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
<?xml version="1.0"?>
<info>
<id>openregister</id>
<name>openregister</name>
</info>
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
{
"name": "conductionnl/openregister"
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
<?php

declare(strict_types=1);

namespace OCA\OpenRegister\Contract;

/**
* Fixture stand-in for the published entity contract.
*/
interface ObjectEntityInterface {

/**
* The object's UUID.
*
* @return string|null
*/
public function getUuid(): ?string;
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
<?php

declare(strict_types=1);

namespace OCA\OpenRegister\Contract;

/**
* Fixture stand-in for the published contract.
*
* Deliberately NOT the real file: the gate compares two copies against each
* other, never against a hard-coded expectation, so any pair works and the
* fixture stays readable.
*/
interface ObjectServiceInterface {

/**
* Find a single object.
*
* @param string|int $id The object id or UUID.
*
* @return ObjectEntityInterface|null The object, or null.
*/
public function find(string|int $id): ?ObjectEntityInterface;
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
<?php

declare(strict_types=1);

namespace OCA\OpenRegister\Contract;

/**
* Fixture stand-in for the published entity contract.
*/
interface ObjectEntityInterface {

/**
* The object's UUID.
*
* @return string|null
*/
public function getUuid(): ?string;
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
<?php

declare(strict_types=1);

namespace OCA\OpenRegister\Contract;

/**
* Fixture stand-in for the published contract.
*
* Deliberately NOT the real file: the gate compares two copies against each
* other, never against a hard-coded expectation, so any pair works and the
* fixture stays readable.
*/
interface ObjectServiceInterface {

/**
* Find a single object.
*
* @param string|int $id The object id or UUID.
*
* @return ObjectEntityInterface|null The object, or null.
*/
public function find(string|int $id): ?ObjectEntityInterface;

/**
* A method the canonical copy does not declare.
*
* @return int The count.
*/
public function count(): int;
}
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,17 @@
# expectation, so any pair works — and a fixture that tracked the real contract
# would need updating every time the contract grew, which is how a fixture
# quietly stops being run.
#
# planted/ and clean/ carry appinfo/info.xml <id>openregister</id>, because the
# gate judges only the app that publishes the contract. Two more trees cover the
# identity check and are run by scripts/lib/test_gate67_contract_parity_scope.sh,
# since this matrix only reads planted/ and clean/:
#
# foreign-app/ <id>opencatalogi</id> with a lib/Contract/ that differs from
# the shipped copy. NOT APPLICABLE: that directory is the
# app's own, and comparing it reports drift it cannot fix.
# composer-only/ no info.xml, openregister named by composer.json, with a
# drifted file. Still FAIL, so the fallback keeps judging.
gate 67 hydra-gate-openregister-contract-parity.log FAIL PASS Contract/ObjectServiceInterface.php
gate 67 hydra-gate-openregister-contract-parity.log FAIL PASS OrphanInterface.php
gate 67 hydra-gate-openregister-contract-parity.log FAIL PASS Contract/UnshippedInterface.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
<?xml version="1.0"?>
<info>
<id>opencatalogi</id>
<name>opencatalogi</name>
</info>
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
<?php

declare(strict_types=1);

namespace OCA\OpenCatalogi\Contract;

/**
* Fixture stand-in for an app's own contract, unrelated to OpenRegister's.
*/
interface AppIdentity {

/**
* The app's id.
*
* @return string
*/
public function getAppId(): string;
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
<?php

declare(strict_types=1);

namespace OCA\OpenRegister\Contract;

/**
* Fixture stand-in for the published contract.
*
* Deliberately NOT the real file: the gate compares two copies against each
* other, never against a hard-coded expectation, so any pair works and the
* fixture stays readable.
*/
interface ObjectServiceInterface {

/**
* Find a single object.
*
* @param string|int $id The object id or UUID.
*
* @return ObjectEntityInterface|null The object, or null.
*/
public function find(string|int $id): ?ObjectEntityInterface;
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
<?php

declare(strict_types=1);

namespace OCA\OpenRegister\Contract;

/**
* Fixture stand-in for the published entity contract.
*/
interface ObjectEntityInterface {

/**
* The object's UUID.
*
* @return string|null
*/
public function getUuid(): ?string;
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
<?php

declare(strict_types=1);

namespace OCA\OpenRegister\Contract;

/**
* Fixture stand-in for the published contract.
*
* Deliberately NOT the real file: the gate compares two copies against each
* other, never against a hard-coded expectation, so any pair works and the
* fixture stays readable.
*/
interface ObjectServiceInterface {

/**
* Find a single object.
*
* @param string|int $id The object id or UUID.
*
* @return ObjectEntityInterface|null The object, or null.
*/
public function find(string|int $id): ?ObjectEntityInterface;

/**
* A method the canonical copy does not declare.
*
* @return int The count.
*/
public function count(): int;
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
<?xml version="1.0"?>
<info>
<id>openregister</id>
<name>openregister</name>
</info>
Loading