Complete REUSE-WP-0005: registry federation and relation graphs

Add federation manifest and schema, federation compose and graph CLI commands,
relation cycle/reference checks, federated index and Mermaid graph artifacts,
RegistryFederation guide, and CI validation updates.

reuse_surface/cli.py

@@ -10,6 +10,8 @@ import yaml
 from jsonschema import Draft202012Validator
 
 from reuse_surface.catalog import write_catalog
+from reuse_surface.federation import write_federated_index
+from reuse_surface.graph import check_relations, render_mermaid, write_graph
 from reuse_surface.overlaps import find_overlaps
 from reuse_surface.registry import (
     ROOT,
@@ -54,6 +56,8 @@ def cmd_validate(args: argparse.Namespace) -> int:
     if not target:
         index = load_index()
         warnings.extend(_check_index_drift(paths, index))
+        if args.relations:
+            warnings.extend(check_relations())
 
     for warning in warnings:
         print(f"warning: {warning}", file=sys.stderr)
@@ -140,6 +144,35 @@ def cmd_overlaps(args: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_federation_compose(args: argparse.Namespace) -> int:
+    try:
+        target, warnings = write_federated_index()
+    except (FileNotFoundError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    for warning in warnings:
+        print(f"warning: {warning}", file=sys.stderr)
+    import yaml
+
+    data = yaml.safe_load(target.read_text(encoding="utf-8"))
+    count = len(data.get("capabilities", []))
+    print(f"ok: wrote {target.relative_to(ROOT)} ({count} capabilities)")
+    return 0
+
+
+def cmd_graph(args: argparse.Namespace) -> int:
+    warnings = check_relations() if args.check else []
+    content = render_mermaid()
+    if args.stdout:
+        print(content, end="")
+    else:
+        path = write_graph()
+        print(f"ok: wrote {path.relative_to(ROOT)}")
+    for warning in warnings:
+        print(f"warning: {warning}", file=sys.stderr)
+    return 0
+
+
 def cmd_catalog(args: argparse.Namespace) -> int:
     index = load_index()
     indexed_entries = _load_indexed_entries()
@@ -199,8 +232,20 @@ def main(argv: list[str] | None = None) -> int:
         nargs="?",
         help="optional capability markdown file; defaults to all entries",
     )
+    validate.add_argument(
+        "--relations",
+        action="store_true",
+        help="check relation cycles and broken references",
+    )
     validate.set_defaults(func=cmd_validate)
 
+    federation = subparsers.add_parser(
+        "federation", help="federation index operations"
+    )
+    federation_sub = federation.add_subparsers(dest="federation_command", required=True)
+    compose = federation_sub.add_parser("compose", help="compose federated index")
+    compose.set_defaults(func=cmd_federation_compose)
+
     query = subparsers.add_parser("query", help="query capability index")
     query.add_argument("--discovery-min")
     query.add_argument("--availability-min")
@@ -234,6 +279,19 @@ def main(argv: list[str] | None = None) -> int:
     )
     catalog.set_defaults(func=cmd_catalog)
 
+    graph = subparsers.add_parser("graph", help="generate relation graph")
+    graph.add_argument(
+        "--stdout",
+        action="store_true",
+        help="print Mermaid to stdout instead of writing docs/graph/",
+    )
+    graph.add_argument(
+        "--check",
+        action="store_true",
+        help="report depends_on cycles and broken relation references",
+    )
+    graph.set_defaults(func=cmd_graph)
+
     args = parser.parse_args(argv)
     return args.func(args)