fix(docs): report a missing node type registry instead of failing as a defect

scripts/check_node_types.py

@@ -2,17 +2,34 @@
 """Validate docs/node-types.md against the host node type registry."""
 from __future__ import annotations
 
+import os
 import pathlib
 import sys
 
 
 ROOT = pathlib.Path(__file__).resolve().parents[1]
 MONOREPO = ROOT.parent
 NODE_TYPES_MD = ROOT / "node-types.md"
+REGISTRY_PATH = MONOREPO / "urirun" / "adapters" / "python"
+
+
+class RegistryUnavailable(RuntimeError):
+    """The sibling urirun checkout this check reads is not present."""
 
 
 def _load_registry_ids() -> tuple[list[str], dict[str, str]]:
-    sys.path.insert(0, str(MONOREPO / "urirun" / "adapters" / "python"))
+    # The registry lives in the sibling urirun checkout, so this check can only
+    # run inside the monorepo layout. An isolated clone - a CI checkout of this
+    # repository on its own - has no urirun, and the import raised
+    # ModuleNotFoundError, failing `make test` for a reason that has nothing to
+    # do with the documentation being checked. It now reports the environment
+    # limit as one instead of letting it masquerade as a documentation defect.
+    if not (REGISTRY_PATH / "urirun" / "host" / "node_types.py").is_file():
+        raise RegistryUnavailable(
+            f"node type registry not found at {REGISTRY_PATH}; "
+            "this check needs the sibling urirun checkout"
+        )
+    sys.path.insert(0, str(REGISTRY_PATH))
     from urirun.host.node_types import NODE_TYPE_ALIASES, NODE_TYPE_PROFILES  # noqa: PLC0415
 
     ids = [str(item["id"]) for item in NODE_TYPE_PROFILES]
@@ -25,7 +42,18 @@ def _load_registry_ids() -> tuple[list[str], dict[str, str]]:
 
 
 def main() -> int:
-    ids, aliases = _load_registry_ids()
+    try:
+        ids, aliases = _load_registry_ids()
+    except RegistryUnavailable as exc:
+        # Skipping is the honest outcome, and it is stated rather than implied.
+        # Set DOCS_REQUIRE_NODE_TYPE_REGISTRY=1 where the registry must be
+        # present - a monorepo pipeline - so its absence is a failure there.
+        print(f"SKIP: {exc}")
+        if os.environ.get("DOCS_REQUIRE_NODE_TYPE_REGISTRY") == "1":
+            print("FAIL: DOCS_REQUIRE_NODE_TYPE_REGISTRY=1 but the registry is unavailable")
+            return 1
+        return 0
+
     text = NODE_TYPES_MD.read_text(encoding="utf-8")
     errors = 0
     for node_type in ids: