#!/usr/bin/env python3 from __future__ import annotations import argparse import json import pathlib import subprocess import sys from dataclasses import dataclass from typing import Any ROOT = pathlib.Path(__file__).resolve().parents[1] DEFAULT_SOURCE_ROOT = ROOT / ".operator-source-repos" / "d-cloud" @dataclass(frozen=True) class SourceCheck: path: str contains: tuple[str, ...] description: str @dataclass(frozen=True) class DCloudContract: slug: str repo_dir: str expected_repo_suffix: str expected_fat_route: str expected_probe_endpoint: str expected_probe_method: str expected_probe_request_json: dict[str, Any] | None source_checks: tuple[SourceCheck, ...] CONTRACTS = ( DCloudContract( slug="dcloud_embodied_annotation", repo_dir="robo_annotation_backend", expected_repo_suffix="/d-cloud/robo_annotation_backend", expected_fat_route="/api/annoMidwareApi/api/v1", expected_probe_endpoint="/api/annoMidwareApi/api/v1/me", expected_probe_method="GET", expected_probe_request_json=None, source_checks=( SourceCheck("pegasus/api/auth.py", ('@router.get("/me")',), "annotation service exposes GET /me"), SourceCheck( "pegasus/deps.py", ('Header(alias="d-user-id")', 'Header(alias="org-symbol")', 'Header(alias="sourceapp")'), "annotation service requires D-Cloud identity headers", ), SourceCheck("docs/apis.md", ("`/me`",), "annotation API docs include /me identity contract"), ), ), DCloudContract( slug="dcloud_data_generation", repo_dir="data_generation", expected_repo_suffix="/d-cloud/data_generation", expected_fat_route="/api/generationApi", expected_probe_endpoint="/api/generationApi/imgGeneration/tasks", expected_probe_method="POST", expected_probe_request_json={"currentPage": 1, "keyword": "", "pageSize": 10}, source_checks=( SourceCheck("initialize/server.go", ('r.Group("/generationApi")',), "generation service registers /generationApi"), SourceCheck( "api/img_generation.go", ('apiGroup.Group("/imgGeneration")', 'imgGenerationGroup.POST("/tasks", h.ListTasks)'), "generation service exposes POST /imgGeneration/tasks", ), SourceCheck( "common/middleware/request.go", ('GetHeader("d-user-id")', 'GetHeader("sourceapp")'), "generation service reads D-Cloud identity headers", ), ), ), ) def normalize_repo_url(value: str) -> str: return value.strip().removesuffix(".git").rstrip("/") def git_head(repo: pathlib.Path) -> str: if not (repo / ".git").exists(): return "" result = subprocess.run( ["git", "-C", str(repo), "rev-parse", "--short", "HEAD"], text=True, capture_output=True, check=False, ) return result.stdout.strip() if result.returncode == 0 else "" def load_operator_metadata(slug: str) -> dict[str, Any]: path = ROOT / "backend" / "operators" / "builtin" / slug / "operator.json" try: payload = json.loads(path.read_text(encoding="utf-8")) except FileNotFoundError as exc: raise SystemExit(f"operator metadata is missing: {path}") from exc except json.JSONDecodeError as exc: raise SystemExit(f"operator metadata is invalid JSON: {path}: {exc}") from exc if not isinstance(payload, dict): raise SystemExit(f"operator metadata must be a JSON object: {path}") return payload def metadata_value(payload: dict[str, Any], *path: str) -> Any: value: Any = payload for key in path: if not isinstance(value, dict): return None value = value.get(key) return value def check_file_contains(repo: pathlib.Path, check: SourceCheck) -> dict[str, Any]: path = repo / check.path if not path.is_file(): return { "name": check.description, "status": "failed", "path": check.path, "message": "source file is missing", } text = path.read_text(encoding="utf-8", errors="replace") missing = [needle for needle in check.contains if needle not in text] if missing: return { "name": check.description, "status": "failed", "path": check.path, "message": "source file does not contain the required contract markers", "missingMarkers": missing, } return {"name": check.description, "status": "passed", "path": check.path} def check_contract(source_root: pathlib.Path, contract: DCloudContract) -> dict[str, Any]: metadata = load_operator_metadata(contract.slug) external_api = metadata_value(metadata, "externalApi") if not isinstance(external_api, dict): external_api = {} probe = external_api.get("acceptanceProbe") if not isinstance(probe, dict): probe = {} repo = source_root / contract.repo_dir checks: list[dict[str, Any]] = [] source_repo = normalize_repo_url(str(external_api.get("sourceRepo", ""))) checks.append( { "name": "operator metadata source repo", "status": "passed" if source_repo.endswith(contract.expected_repo_suffix) else "failed", "expectedSuffix": contract.expected_repo_suffix, "actual": source_repo, } ) fat_route = str(external_api.get("fatRoute", "")).strip() checks.append( { "name": "operator metadata FAT route", "status": "passed" if fat_route == contract.expected_fat_route else "failed", "expected": contract.expected_fat_route, "actual": fat_route, } ) probe_endpoint = str(probe.get("endpoint", "")).strip() checks.append( { "name": "acceptance probe endpoint", "status": "passed" if probe_endpoint == contract.expected_probe_endpoint else "failed", "expected": contract.expected_probe_endpoint, "actual": probe_endpoint, } ) probe_method = (str(probe.get("method", "")).strip() or "POST").upper() checks.append( { "name": "acceptance probe method", "status": "passed" if probe_method == contract.expected_probe_method else "failed", "expected": contract.expected_probe_method, "actual": probe_method, } ) probe_request_json = probe.get("requestJson") if "requestJson" in probe else None checks.append( { "name": "acceptance probe request JSON", "status": "passed" if probe_request_json == contract.expected_probe_request_json else "failed", "expected": contract.expected_probe_request_json, "actual": probe_request_json, } ) if not repo.is_dir(): checks.append( { "name": "source repository checkout", "status": "failed", "path": str(repo), "message": "clone the source repo before running this check", } ) else: checks.append({"name": "source repository checkout", "status": "passed", "path": str(repo), "head": git_head(repo)}) checks.extend(check_file_contains(repo, check) for check in contract.source_checks) status = "passed" if all(item["status"] == "passed" for item in checks) else "failed" return {"slug": contract.slug, "status": status, "repoDir": contract.repo_dir, "checks": checks} def main() -> int: parser = argparse.ArgumentParser(description="Verify D-Cloud operator metadata against checked out source repos.") parser.add_argument("--source-root", default=str(DEFAULT_SOURCE_ROOT), help="directory containing d-cloud source repo checkouts") parser.add_argument("--json", action="store_true", help="emit JSON output") args = parser.parse_args() source_root = pathlib.Path(args.source_root).expanduser().resolve() results = [check_contract(source_root, contract) for contract in CONTRACTS] status = "passed" if all(item["status"] == "passed" for item in results) else "failed" payload = {"status": status, "sourceRoot": str(source_root), "contracts": results} if args.json: print(json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True)) else: for result in results: print(f"{result['slug']}: {result['status']}") for check in result["checks"]: print(f" - {check['status']}: {check['name']}") return 0 if status == "passed" else 1 if __name__ == "__main__": sys.exit(main())