Wire universe_locations into Validator for cross-universe reference diagnostics

When the compiler encounters a cross-universe FQUN reference to an
unconfigured universe, it now emits an ExternalUniverseNotConfiguredDiagnostic
instead of raising NotImplementedError. The local deps config is passed as an
immutable mapping through the validation frame so it can vary per sub-project.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: mkanat

define/compiler/config.py

@@ -1,5 +1,6 @@
 """Project configuration loading and validation."""
 
+import types
 from pathlib import Path, PurePosixPath
 
 import protovalidate
@@ -51,13 +52,16 @@ def project_config() -> config_pb2.ProjectConfigFile:
     return _load_config(CONFIG_PATH, config_pb2.ProjectConfigFile)
 
 
-def local_deps_config() -> dict[str, PurePosixPath]:
+_EMPTY_DEPS: types.MappingProxyType[str, PurePosixPath] = types.MappingProxyType({})
+
+
+def local_deps_config() -> types.MappingProxyType[str, PurePosixPath]:
     """Load and validate the local dependency overrides from the current directory.
 
-    Returns a mapping from universe name to relative path.
+    Returns an immutable mapping from universe name to relative path.
     """
     if not LOCAL_DEPS_PATH.exists():
-        return {}
+        return _EMPTY_DEPS
     result = _load_config(LOCAL_DEPS_PATH, local_pb2.LocalDepsFile)
     deps: dict[str, PurePosixPath] = {}
     for dep in result.deps.local:
@@ -67,4 +71,4 @@ def local_deps_config() -> dict[str, PurePosixPath]:
                 [f'deps.local: duplicate universe_name "{dep.universe_name}"'],
             )
         deps[dep.universe_name] = PurePosixPath(dep.path)
-    return deps
+    return types.MappingProxyType(deps)

define/compiler/diagnostics.py

@@ -301,3 +301,16 @@ class ReferencedFileNotFoundDiagnostic(Diagnostic):
 
     file_path: str
     message_format: ClassVar[str] = "there is no file '{file_path}' in this project"
+
+
+@dataclass
+class ExternalUniverseNotConfiguredDiagnostic(Diagnostic):
+    """Diagnostic for when a cross-universe reference targets an unconfigured universe."""
+
+    universe: str
+    current_universe_name: str
+    message_format: ClassVar[str] = (
+        "universe '{universe}' is not configured as a dependency "
+        "of this universe ({current_universe_name}); "
+        "add it to .define/deps/local.defcl"
+    )

define/compiler/driver.py

@@ -39,6 +39,7 @@ def validate_program(
         return validator.Validator().parse_and_validate_program(
             path=resolved_path,
             expected_universe_name=self.project_config.project.universe_name or "",
+            universe_locations=config.local_deps_config(),
         )
 
     @staticmethod

define/compiler/driver_integration_test.py

@@ -207,6 +207,9 @@
 
 # Key: path relative to PROJECTS_ROOT / "invalid" (as posix string)
 EXPECTED_PROJECT_DIAGNOSTICS: dict[str, list[type[diagnostics.Diagnostic]]] = {
+    "global_name_walk/cross_fqun_missing_universe": [
+        diagnostics.ExternalUniverseNotConfiguredDiagnostic,
+    ],
     "global_name_walk/missing": [diagnostics.ReferencedFileNotFoundDiagnostic],
     "global_name_walk/wrong_type": [
         diagnostics.ReferencedGlobalNameWrongTypeDiagnostic,

define/compiler/validator.py

@@ -7,6 +7,10 @@
 from collections import ChainMap, OrderedDict
 from dataclasses import dataclass
 from functools import cached_property
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
 
 from lark import exceptions as lark_exceptions
 
@@ -125,6 +129,7 @@ class _ValidationFrame:
     diagnostics: list[diagnostics.Diagnostic]
     expected_definition_path: pathlib.PurePosixPath | None
     expected_universe_name: str | None
+    universe_locations: Mapping[str, pathlib.PurePosixPath]
 
 
 class Validator:
@@ -138,6 +143,7 @@ def __init__(self):
         self._seen_global_definitions: dict[str, ast.QualityDefinition] = {}
         self._validation_frames: list[_ValidationFrame] = []
         self._reference_not_found_paths: set[pathlib.PurePosixPath] = set()
+        self._unknown_universes: set[str] = set()
 
     @cached_property
     def _parser(self) -> parser.Parser:
@@ -148,9 +154,14 @@ def parse_and_validate_program(
         self,
         path: pathlib.PurePath,
         expected_universe_name: str | None = None,
+        universe_locations: Mapping[str, pathlib.PurePosixPath] | None = None,
     ) -> list[ValidationResult]:
         """Parse, transform, and validate all reached files from one entrypoint."""
-        self._parse_validate_and_collect(path, expected_universe_name)
+        self._parse_validate_and_collect(
+            path,
+            expected_universe_name,
+            universe_locations if universe_locations is not None else {},
+        )
         return [
             result
             for result in self.results_by_path.values()
@@ -164,7 +175,8 @@ def parse_and_validate_program(
     def _parse_and_validate_file(
         self,
         path: pathlib.PurePath,
-        expected_universe_name: str | None = None,
+        expected_universe_name: str | None,
+        universe_locations: Mapping[str, pathlib.PurePosixPath],
     ) -> ValidationResult:
         """Parse, transform, and validate one Define file."""
         # Ensure Windows-style paths are converted to POSIX paths for
@@ -201,13 +213,15 @@ def _parse_and_validate_file(
             program=program,
             expected_definition_path=expected_definition_path,
             expected_universe_name=expected_universe_name,
+            universe_locations=universe_locations,
         )
         return run.complete(validation_diagnostics)
 
     def _parse_validate_and_collect(
         self,
         path: pathlib.PurePath,
         expected_universe_name: str | None,
+        universe_locations: Mapping[str, pathlib.PurePosixPath],
     ) -> None:
         """Parse/validate one file once and append its result in encounter order."""
         logical_path = pathlib.PurePosixPath(path.as_posix())
@@ -217,6 +231,7 @@ def _parse_validate_and_collect(
         result = self._parse_and_validate_file(
             path=logical_path,
             expected_universe_name=expected_universe_name,
+            universe_locations=universe_locations,
         )
         self.results_by_path[logical_path] = result
 
@@ -245,6 +260,7 @@ def validate(
         program: ast.Program,
         expected_definition_path: pathlib.PurePosixPath | None = None,
         expected_universe_name: str | None = None,
+        universe_locations: Mapping[str, pathlib.PurePosixPath] | None = None,
     ) -> list[diagnostics.Diagnostic]:
         """Validate all semantic rules and return collected diagnostics.
 
@@ -258,11 +274,17 @@ def validate(
             expected_universe_name: Optional FQUN string from the project config.
                 When provided, validates that each definition's FQUN matches this
                 value. When None, skips FQUN matching validation.
+            universe_locations: Mapping from universe name to local path for
+                configured external dependencies. Defaults to no configured
+                dependencies.
         """
         frame = _ValidationFrame(
             diagnostics=[],
             expected_definition_path=expected_definition_path,
             expected_universe_name=expected_universe_name,
+            universe_locations=universe_locations
+            if universe_locations is not None
+            else {},
         )
         self._validation_frames.append(frame)
         try:
@@ -444,6 +466,23 @@ def _load_global_name_reference(
         reference = typed_global_name.global_name
         expected_type = typed_global_name.type_name
         if reference.fqun is not None:
+            canonical = reference.fqun.canonical
+            if canonical not in self._frame.universe_locations:
+                if canonical not in self._unknown_universes:
+                    expected = self._frame.expected_universe_name
+                    if expected is None:
+                        raise ValueError(
+                            "expected_universe_name must be set for cross-universe references"
+                        )
+                    self._unknown_universes.add(canonical)
+                    self._diagnostics.append(
+                        diagnostics.ExternalUniverseNotConfiguredDiagnostic(
+                            position=reference.fqun.position,
+                            universe=canonical,
+                            current_universe_name=expected,
+                        )
+                    )
+                return
             raise NotImplementedError(
                 "Global-reference file walking for FQUN references is not implemented."
             )
@@ -453,6 +492,7 @@ def _load_global_name_reference(
         self._parse_validate_and_collect(
             path=referenced_file,
             expected_universe_name=self._frame.expected_universe_name,
+            universe_locations=self._frame.universe_locations,
         )
 
         referenced_result = self.results_by_path[referenced_file]

define/compiler/validator_test.py

@@ -809,3 +809,53 @@ def test_local_name_position(self):
         assert len(ln_diags) == 1
         assert ln_diags[0].position.line == 2
         assert ln_diags[0].position.column == 23
+
+
+class TestCrossUniverseReference:
+    def test_unknown_universe_emits_diagnostic(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ):
+        source = (
+            "define the potential position<mv:define-lang.org:my_universe:/test> {\n"
+            "it may only contain dimension points where {\n"
+            "it has the position<other.example.com:other_universe:/target>.\n"
+            "}\n"
+            "}\n"
+        )
+        source_path = tmp_path / "test.def"
+        _ = source_path.write_text(source, encoding="utf-8")
+        monkeypatch.chdir(tmp_path)
+        results = validator.Validator().parse_and_validate_program(
+            Path("test.def"),
+            expected_universe_name="mv:define-lang.org:my_universe",
+        )
+        assert len(results) == 1
+        diags = results[0].diagnostics
+        assert len(diags) == 1
+        assert isinstance(diags[0], diagnostics.ExternalUniverseNotConfiguredDiagnostic)
+        assert diags[0].universe == "other.example.com:other_universe"
+        assert diags[0].current_universe_name == "mv:define-lang.org:my_universe"
+
+    def test_duplicate_unknown_universe_emits_one_diagnostic(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ):
+        source = (
+            "define the potential position<mv:define-lang.org:my_universe:/test> {\n"
+            "it may only contain dimension points where {\n"
+            "it has the position<other.example.com:other_universe:/target>.\n"
+            "it has the position<other.example.com:other_universe:/another>.\n"
+            "}\n"
+            "}\n"
+        )
+        source_path = tmp_path / "test.def"
+        _ = source_path.write_text(source, encoding="utf-8")
+        monkeypatch.chdir(tmp_path)
+        results = validator.Validator().parse_and_validate_program(
+            Path("test.def"),
+            expected_universe_name="mv:define-lang.org:my_universe",
+        )
+        assert len(results) == 1
+        diags = results[0].diagnostics
+        assert len(diags) == 1
+        assert isinstance(diags[0], diagnostics.ExternalUniverseNotConfiguredDiagnostic)
+        assert diags[0].universe == "other.example.com:other_universe"