feat: Support file path references in validate-dsl (#37)

This commit adds support for cross-document references using relative
file paths in addition to module IDs, resolving issue #36.

**Problem:**
The DSL validator could not resolve references like `./ADR-011.md`
that use relative file paths instead of module IDs. This caused
validation failures even when the referenced documents existed and
were in scope.

**Root Cause:**
- Reference extractor classified file paths as module_reference
- `_extract_module_id()` stripped `.md` → `./ADR-011`
- Registry lookup by ID failed (registry only had `ADR-011`)
- No fallback to file path resolution

**Solution:**
1. Added `get_module_by_file()` to IDRegistry for file path lookups
2. Added `_is_file_path()` to detect path-style references
3. Added `_resolve_by_file_path()` to resolve relative paths
4. Updated `_resolve_module_reference()` to try file path resolution
   when direct ID lookup fails

**Testing:**
- Added comprehensive test case reproducing the issue
- Test creates ADRs with file path cross-references
- All 275 tests pass

**Impact:**
This enables spec-check to work with real-world specification
repositories that follow standard markdown linking conventions
(file paths), not just module ID references.

Fixes #36

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <noreply@anthropic.com>

Author: calvingiles

spec_check/dsl/id_registry.py

@@ -173,6 +173,37 @@ def get_class(self, class_id: str) -> ClassInstance | None:
         """Get a class instance by ID."""
         return self.classes.get(class_id)
 
+    def get_module_by_file(self, file_path: Path) -> ModuleInstance | None:
+        """
+        Get a module instance by its file path.
+
+        This enables resolving cross-document references that use relative file paths
+        instead of module IDs (e.g., './011-deployment-architecture.md' → 'ADR-011').
+
+        Args:
+            file_path: Absolute or relative path to the module file
+
+        Returns:
+            ModuleInstance if found, None otherwise
+        """
+        # Resolve to absolute path for comparison
+        try:
+            target_path = file_path.resolve()
+        except (OSError, RuntimeError):
+            # Path doesn't exist or can't be resolved
+            return None
+
+        # Search all registered modules for matching file path
+        for module in self.modules.values():
+            try:
+                if module.file_path.resolve() == target_path:
+                    return module
+            except (OSError, RuntimeError):
+                # Module file path can't be resolved, skip it
+                continue
+
+        return None
+
     def find_class_in_module(self, class_id: str, module_id: str) -> ClassInstance | None:
         """
         Find a class instance within a specific module.

spec_check/dsl/reference_resolver.py

@@ -123,9 +123,13 @@ def _resolve_module_reference(
                 error=f"Could not extract module ID from target: {reference.link_target}",
             )
 
-        # Look up in registry
+        # Try to look up by module ID first
         target_module = self.registry.get_module(target_id)
 
+        # If not found by ID and target looks like a file path, try file path resolution
+        if not target_module and self._is_file_path(target_id):
+            target_module = self._resolve_by_file_path(reference.source_file, target_id)
+
         if not target_module:
             # Check if there are similar IDs (for helpful error messages)
             suggestions = self._find_similar_module_ids(target_id)
@@ -269,6 +273,50 @@ def validate_cardinality(
 
         return violations
 
+    def _is_file_path(self, target: str) -> bool:
+        """
+        Check if a target looks like a file path rather than a module ID.
+
+        File paths typically contain:
+        - Directory separators (/ or \\)
+        - Relative path indicators (./ or ../)
+        - File extensions before they're stripped
+
+        Args:
+            target: The target string (already processed by _extract_module_id)
+
+        Returns:
+            True if target looks like a file path
+        """
+        # Check for path separators or relative path indicators
+        return "/" in target or "\\" in target or target.startswith(".")
+
+    def _resolve_by_file_path(self, source_file: Path, target_path: str) -> ModuleInstance | None:
+        """
+        Resolve a module reference using a file path.
+
+        Converts a relative file path like './011-deployment-architecture'
+        to an absolute path and looks it up in the registry.
+
+        Args:
+            source_file: Path to the source file containing the reference
+            target_path: Relative or absolute file path to the target (without .md extension)
+
+        Returns:
+            ModuleInstance if found, None otherwise
+        """
+        # Add back the .md extension that was stripped by _extract_module_id
+        if not target_path.endswith(".md"):
+            target_path_with_ext = target_path + ".md"
+        else:
+            target_path_with_ext = target_path
+
+        # Resolve relative to source file's directory
+        target_file = source_file.parent / target_path_with_ext
+
+        # Look up by file path in registry
+        return self.registry.get_module_by_file(target_file)
+
     def _extract_module_id(self, link_target: str) -> str | None:
         """Extract module ID from link target."""
         # Remove .md extension

tests/test_dsl_coverage.py

@@ -348,6 +348,71 @@ def test_reference_cardinality_validation(self, tmp_path):
         # Should have an error about missing "addresses" reference
         assert any("addresses" in msg.lower() for msg in error_messages)
 
+    def test_file_path_reference_resolution(self, tmp_path):
+        """Test resolving cross-document references using file paths.
+
+        This test reproduces issue #36 where validate-dsl cannot resolve
+        references that use relative file paths instead of module IDs.
+
+        ADR documents often link to each other using standard markdown
+        file path links like './011-deployment-architecture.md' which should
+        resolve to module ID 'ADR-011'.
+        """
+        (tmp_path / "specs" / "architecture").mkdir(parents=True)
+
+        # Create first ADR with a known module ID (using correct pattern ADR-NNN.md)
+        adr_011 = tmp_path / "specs" / "architecture" / "ADR-011.md"
+        adr_011.write_text("""# ADR-011: Deployment Architecture
+
+## Status
+Accepted
+
+## Context
+Deployment architecture decisions.
+
+## Decision
+Use cloud infrastructure.
+
+## Consequences
+Improved scalability.
+""")
+
+        # Create second ADR that references the first using a file path
+        adr_015 = tmp_path / "specs" / "architecture" / "ADR-015.md"
+        adr_015.write_text("""# ADR-015: Developer Access Control Strategy
+
+## Status
+Accepted
+
+## Context
+Access control strategy.
+
+## Decision
+Implement RBAC.
+
+## Adheres To
+- [ADR-011: Deployment Architecture](./ADR-011.md)
+
+## Consequences
+Better security.
+""")
+
+        registry = SpecTypeRegistry.load_builtin_types()
+        validator = DSLValidator(registry)
+
+        # Before the fix, this fails with:
+        # Module reference './ADR-011' not found
+        result = validator.validate(tmp_path / "specs")
+
+        assert result is not None
+
+        # The file path reference should resolve successfully
+        # Check that there's no error about './ADR-011' not being found
+        error_messages = [e.message for e in result.errors]
+        assert not any("'./ADR-011'" in msg for msg in error_messages), (
+            f"File path reference should resolve, but got errors: {error_messages}"
+        )
+
 
 class TestRegistryLoading:
     """Test registry loading."""