elspais 0.11.1__py3-none-any.whl → 0.43.5__py3-none-any.whl

elspais/graph/deserializer.py

@@ -0,0 +1,248 @@
+"""DomainDeserializer - Abstract controller for text domain deserialization.
+
+This module provides the infrastructure for deserializing text from
+various sources (files, stdin, CLI args) into parsed content.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Iterator, Protocol, runtime_checkable
+
+from elspais.graph.parsers import ParseContext, ParsedContent, ParserRegistry
+
+
+@dataclass
+class DomainContext:
+    """Context for a source being deserialized.
+
+    Attributes:
+        source_type: Type of source ("file", "stdin", "cli").
+        source_id: Identifier for the source (file path, etc.).
+        metadata: Additional metadata about the source.
+    """
+
+    source_type: str
+    source_id: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ParsedContentWithContext(ParsedContent):
+    """ParsedContent with source context attached.
+
+    Extends ParsedContent to include the DomainContext from which
+    the content was parsed.
+    """
+
+    source_context: DomainContext | None = None
+
+
+@runtime_checkable
+class DomainDeserializer(Protocol):
+    """Protocol for domain deserializers.
+
+    Deserializers iterate over sources and use parsers to extract
+    structured content.
+    """
+
+    def iterate_sources(self) -> Iterator[tuple[DomainContext, str]]:
+        """Iterate over sources, yielding context and content.
+
+        Yields:
+            Tuples of (DomainContext, content_string).
+        """
+        ...
+
+    def deserialize(self, registry: ParserRegistry) -> Iterator[ParsedContentWithContext]:
+        """Deserialize all sources using the parser registry.
+
+        Args:
+            registry: ParserRegistry with registered parsers.
+
+        Yields:
+            ParsedContentWithContext for each parsed region.
+        """
+        ...
+
+
+class DomainFile:
+    """Deserializer for files and directories.
+
+    Can deserialize:
+    - A single file
+    - All matching files in a directory
+    """
+
+    def __init__(
+        self,
+        path: Path | str,
+        patterns: list[str] | None = None,
+        recursive: bool = False,
+        skip_dirs: list[str] | None = None,
+        skip_files: list[str] | None = None,
+    ) -> None:
+        """Initialize file deserializer.
+
+        Args:
+            path: Path to file or directory.
+            patterns: Glob patterns for directory (default: ["*.md"]).
+            recursive: Whether to search recursively.
+            skip_dirs: Directory names to skip (e.g., ["roadmap", "reference"]).
+            skip_files: File names to skip (e.g., ["README.md", "INDEX.md"]).
+        """
+        self.path = Path(path)
+        self.patterns = patterns or ["*.md"]
+        self.recursive = recursive
+        self.skip_dirs = skip_dirs or []
+        self.skip_files = skip_files or []
+
+    def _should_skip(self, file_path: Path) -> bool:
+        """Check if a file should be skipped based on skip_dirs and skip_files.
+
+        Args:
+            file_path: Path to check.
+
+        Returns:
+            True if the file should be skipped.
+        """
+        # Check if file name matches skip_files
+        if file_path.name in self.skip_files:
+            return True
+
+        # Check if any parent directory matches skip_dirs
+        # Get path relative to base to check directory names
+        try:
+            rel_path = file_path.relative_to(self.path)
+            # Check each part of the relative path (excluding the file name)
+            for part in rel_path.parts[:-1]:
+                if part in self.skip_dirs:
+                    return True
+        except ValueError:
+            # file_path is not relative to self.path, check absolute path parts
+            for part in file_path.parts:
+                if part in self.skip_dirs:
+                    return True
+
+        return False
+
+    def iterate_sources(self) -> Iterator[tuple[DomainContext, str]]:
+        """Iterate over file sources.
+
+        Yields:
+            Tuples of (DomainContext, file_content).
+        """
+        if self.path.is_file():
+            if not self._should_skip(self.path):
+                yield self._read_file(self.path)
+        elif self.path.is_dir():
+            for pattern in self.patterns:
+                if self.recursive:
+                    file_iter = self.path.rglob(pattern)
+                else:
+                    file_iter = self.path.glob(pattern)
+
+                for file_path in sorted(file_iter):
+                    if file_path.is_file() and not self._should_skip(file_path):
+                        yield self._read_file(file_path)
+
+    def _read_file(self, file_path: Path) -> tuple[DomainContext, str]:
+        """Read a file and create context.
+
+        Args:
+            file_path: Path to file.
+
+        Returns:
+            Tuple of (DomainContext, content).
+        """
+        content = file_path.read_text(encoding="utf-8")
+        ctx = DomainContext(
+            source_type="file",
+            source_id=str(file_path),
+            metadata={"path": file_path},
+        )
+        return ctx, content
+
+    def deserialize(self, registry: ParserRegistry) -> Iterator[ParsedContentWithContext]:
+        """Deserialize files using parser registry.
+
+        Args:
+            registry: ParserRegistry with registered parsers.
+
+        Yields:
+            ParsedContentWithContext for each parsed region.
+        """
+        for ctx, content in self.iterate_sources():
+            # Convert content to lines
+            lines = [(i + 1, line) for i, line in enumerate(content.split("\n"))]
+
+            # Create parse context
+            parse_ctx = ParseContext(
+                file_path=ctx.source_id,
+                config=ctx.metadata,
+            )
+
+            # Parse and yield with context
+            for parsed in registry.parse_all(lines, parse_ctx):
+                yield ParsedContentWithContext(
+                    content_type=parsed.content_type,
+                    start_line=parsed.start_line,
+                    end_line=parsed.end_line,
+                    raw_text=parsed.raw_text,
+                    parsed_data=parsed.parsed_data,
+                    source_context=ctx,
+                )
+
+
+class DomainStdio:
+    """Deserializer for stdin content."""
+
+    def __init__(self, content: str, source_id: str = "<stdin>") -> None:
+        """Initialize stdin deserializer.
+
+        Args:
+            content: Content read from stdin.
+            source_id: Identifier for the source.
+        """
+        self.content = content
+        self.source_id = source_id
+
+    def iterate_sources(self) -> Iterator[tuple[DomainContext, str]]:
+        """Yield the stdin content.
+
+        Yields:
+            Single tuple of (DomainContext, content).
+        """
+        ctx = DomainContext(
+            source_type="stdin",
+            source_id=self.source_id,
+        )
+        yield ctx, self.content
+
+    def deserialize(self, registry: ParserRegistry) -> Iterator[ParsedContentWithContext]:
+        """Deserialize stdin using parser registry.
+
+        Args:
+            registry: ParserRegistry with registered parsers.
+
+        Yields:
+            ParsedContentWithContext for each parsed region.
+        """
+        for ctx, content in self.iterate_sources():
+            lines = [(i + 1, line) for i, line in enumerate(content.split("\n"))]
+
+            parse_ctx = ParseContext(
+                file_path=ctx.source_id,
+                config={},
+            )
+
+            for parsed in registry.parse_all(lines, parse_ctx):
+                yield ParsedContentWithContext(
+                    content_type=parsed.content_type,
+                    start_line=parsed.start_line,
+                    end_line=parsed.end_line,
+                    raw_text=parsed.raw_text,
+                    parsed_data=parsed.parsed_data,
+                    source_context=ctx,
+                )

elspais/graph/factory.py

@@ -0,0 +1,284 @@
+"""Graph Factory - Shared utility for building TraceGraph from spec files.
+
+This module provides a single entry point for all commands to build a TraceGraph
+from configuration and spec directories. Commands should use this instead of
+implementing their own file reading logic.
+"""
+
+from __future__ import annotations
+
+from glob import glob
+from pathlib import Path
+from typing import Any
+
+from elspais.associates import get_associate_spec_directories
+from elspais.config import get_config, get_ignore_config, get_spec_directories
+from elspais.graph.builder import GraphBuilder, TraceGraph
+from elspais.graph.deserializer import DomainFile
+from elspais.graph.parsers import ParserRegistry
+from elspais.graph.parsers.code import CodeParser
+from elspais.graph.parsers.journey import JourneyParser
+from elspais.graph.parsers.requirement import RequirementParser
+from elspais.graph.parsers.results import JUnitXMLParser, PytestJSONParser
+from elspais.graph.parsers.test import TestParser
+from elspais.utilities.patterns import PatternConfig
+from elspais.utilities.reference_config import ReferenceResolver
+
+
+def _find_repo_root(spec_dir: Path) -> Path | None:
+    """Find the repository root containing .elspais.toml for a spec directory.
+
+    Walks up the directory tree looking for .elspais.toml.
+
+    Args:
+        spec_dir: The spec directory path
+
+    Returns:
+        Path to repo root, or None if not found
+    """
+    current = spec_dir.resolve()
+    while current != current.parent:
+        if (current / ".elspais.toml").exists():
+            return current
+        current = current.parent
+    return None
+
+
+def _create_registry_for_spec_dir(
+    spec_dir: Path,
+    default_pattern_config: PatternConfig,
+    default_reference_resolver: ReferenceResolver,
+) -> ParserRegistry:
+    """Create a parser registry for a spec directory.
+
+    If the spec directory is in a different repo (has its own .elspais.toml),
+    loads that repo's config and creates a registry with its pattern config
+    and reference resolver. Otherwise uses the defaults.
+
+    Args:
+        spec_dir: The spec directory path
+        default_pattern_config: The default pattern config from main repo
+        default_reference_resolver: The default reference resolver from main repo
+
+    Returns:
+        ParserRegistry configured for this spec directory
+    """
+    registry = ParserRegistry()
+
+    # Check if this spec dir is in a different repo with its own config
+    repo_root = _find_repo_root(spec_dir)
+    if repo_root:
+        config_path = repo_root / ".elspais.toml"
+        if config_path.exists():
+            repo_config = get_config(config_path, repo_root)
+            patterns_dict = repo_config.get("patterns", {})
+            pattern_config = PatternConfig.from_dict(patterns_dict)
+            # Build reference resolver from this repo's config
+            reference_resolver = ReferenceResolver.from_config(repo_config.get("references", {}))
+            registry.register(RequirementParser(pattern_config))
+            registry.register(JourneyParser())
+            registry.register(CodeParser(pattern_config, reference_resolver))
+            registry.register(TestParser(pattern_config, reference_resolver))
+            return registry
+
+    # Fall back to defaults
+    registry.register(RequirementParser(default_pattern_config))
+    registry.register(JourneyParser())
+    registry.register(CodeParser(default_pattern_config, default_reference_resolver))
+    registry.register(TestParser(default_pattern_config, default_reference_resolver))
+    return registry
+
+
+def build_graph(
+    config: dict[str, Any] | None = None,
+    spec_dirs: list[Path] | None = None,
+    config_path: Path | None = None,
+    repo_root: Path | None = None,
+    scan_code: bool = True,
+    scan_tests: bool = True,
+    scan_sponsors: bool = True,
+) -> TraceGraph:
+    """Build a TraceGraph from spec directories.
+
+    This is the standard way for commands to obtain a TraceGraph.
+    It handles:
+    - Configuration loading (auto-discovery or explicit)
+    - Spec directory resolution
+    - Sponsor/associate spec directory resolution
+    - Parser registration
+    - Graph construction
+    - Code and test directory scanning (configurable)
+
+    Args:
+        config: Pre-loaded config dict (optional).
+        spec_dirs: Explicit spec directories (optional).
+        config_path: Path to config file (optional).
+        repo_root: Repository root for relative paths (defaults to cwd).
+        scan_code: Whether to scan code directories from traceability.scan_patterns.
+        scan_tests: Whether to scan test directories from testing.test_dirs.
+        scan_sponsors: Whether to scan sponsor/associate spec directories.
+
+    Returns:
+        Complete TraceGraph with all requirements linked.
+
+    Priority:
+        spec_dirs > config > config_path > defaults
+    """
+    # Default repo_root
+    if repo_root is None:
+        repo_root = Path.cwd()
+
+    # 1. Resolve configuration
+    if config is None:
+        config = get_config(config_path, repo_root)
+
+    # 2. Resolve spec directories
+    if spec_dirs is None:
+        spec_dirs = get_spec_directories(None, config, repo_root)
+
+    # 2b. Add sponsor/associate spec directories if enabled
+    if scan_sponsors:
+        sponsor_dirs = get_associate_spec_directories(config, repo_root)
+        spec_dirs = list(spec_dirs) + sponsor_dirs
+
+    # 3. Create default pattern config and reference resolver
+    default_pattern_config = PatternConfig.from_dict(config.get("patterns", {}))
+    default_reference_resolver = ReferenceResolver.from_config(config.get("references", {}))
+
+    # Registry for code files (code parser only)
+    code_registry = ParserRegistry()
+    code_registry.register(CodeParser(default_pattern_config, default_reference_resolver))
+
+    # Registry for test files (test parser only)
+    test_registry = ParserRegistry()
+    test_registry.register(TestParser(default_pattern_config, default_reference_resolver))
+
+    # 4. Build graph from all spec directories
+    builder = GraphBuilder(repo_root=repo_root)
+
+    # Get ignore configuration for filtering spec files
+    ignore_config = get_ignore_config(config)
+
+    # Get skip configuration (legacy, for backward compatibility)
+    spec_config = config.get("spec", {})
+    skip_dirs = spec_config.get("skip_dirs", [])
+    skip_files = spec_config.get("skip_files", [])
+
+    for spec_dir in spec_dirs:
+        # Create registry with appropriate pattern config for this spec dir
+        # (uses sponsor repo's config if applicable)
+        spec_registry = _create_registry_for_spec_dir(
+            spec_dir, default_pattern_config, default_reference_resolver
+        )
+
+        # Get file patterns from config
+        file_patterns = spec_config.get("patterns", ["*.md"])
+        domain_file = DomainFile(
+            spec_dir,
+            patterns=file_patterns,
+            recursive=True,
+            skip_dirs=skip_dirs,
+            skip_files=skip_files,
+        )
+
+        for parsed_content in domain_file.deserialize(spec_registry):
+            # Check if source should be ignored using [ignore].spec patterns
+            source_path = parsed_content.source_context.metadata.get("path")
+            if source_path and ignore_config.should_ignore(source_path, scope="spec"):
+                continue
+            builder.add_parsed_content(parsed_content)
+
+    # 5. Scan code directories from traceability.scan_patterns
+    if scan_code:
+        traceability_config = config.get("traceability", {})
+        scan_patterns = traceability_config.get("scan_patterns", [])
+
+        for pattern in scan_patterns:
+            # Resolve glob pattern relative to repo_root
+            matched_files = glob(str(repo_root / pattern), recursive=True)
+            for file_path in matched_files:
+                path = Path(file_path)
+                if path.is_file():
+                    domain_file = DomainFile(path)
+                    for parsed_content in domain_file.deserialize(code_registry):
+                        builder.add_parsed_content(parsed_content)
+
+    # 6. Scan test directories from testing config
+    if scan_tests:
+        testing_config = config.get("testing", {})
+        if testing_config.get("enabled", False):
+            test_dirs = testing_config.get("test_dirs", [])
+            test_patterns = testing_config.get("patterns", ["*_test.*", "test_*.*"])
+
+            for dir_pattern in test_dirs:
+                # Resolve glob pattern to get directories
+                matched_dirs = glob(str(repo_root / dir_pattern), recursive=True)
+                for dir_path in matched_dirs:
+                    path = Path(dir_path)
+                    if path.is_dir():
+                        domain_file = DomainFile(
+                            path,
+                            patterns=test_patterns,
+                            recursive=True,
+                        )
+                        for parsed_content in domain_file.deserialize(test_registry):
+                            builder.add_parsed_content(parsed_content)
+
+            # 6b. Scan test result files (JUnit XML, pytest JSON)
+            result_files = testing_config.get("result_files", [])
+            if result_files:
+                # Create parsers for result files (these have a different interface)
+                junit_parser = JUnitXMLParser(
+                    pattern_config=default_pattern_config,
+                    reference_resolver=default_reference_resolver,
+                    base_path=repo_root,
+                )
+                pytest_parser = PytestJSONParser(
+                    pattern_config=default_pattern_config,
+                    reference_resolver=default_reference_resolver,
+                    base_path=repo_root,
+                )
+
+                for file_pattern in result_files:
+                    # Resolve glob pattern relative to repo_root
+                    matched_files = glob(str(repo_root / file_pattern), recursive=True)
+                    for file_path in matched_files:
+                        path = Path(file_path)
+                        if path.is_file():
+                            content = path.read_text(encoding="utf-8")
+                            source_path = str(path)
+
+                            # Choose parser based on file extension
+                            results = []
+                            if path.suffix.lower() == ".xml":
+                                results = junit_parser.parse(content, source_path)
+                            elif path.suffix.lower() == ".json":
+                                results = pytest_parser.parse(content, source_path)
+
+                            # Convert results to ParsedContent for the builder
+                            for result in results:
+                                from elspais.graph.deserializer import (
+                                    DomainContext,
+                                    ParsedContentWithContext,
+                                )
+
+                                ctx = DomainContext(
+                                    source_type="file",
+                                    source_id=source_path,
+                                    metadata={"path": path},
+                                )
+
+                                parsed_content = ParsedContentWithContext(
+                                    content_type="test_result",
+                                    start_line=1,
+                                    end_line=1,
+                                    raw_text="",
+                                    parsed_data=result,
+                                    source_context=ctx,
+                                )
+                                builder.add_parsed_content(parsed_content)
+
+    return builder.build()
+
+
+__all__ = ["build_graph"]

elspais/graph/metrics.py

@@ -0,0 +1,127 @@
+"""Coverage metrics data structures.
+
+This module defines the data structures for centralized coverage tracking:
+- CoverageSource: Enum indicating where coverage originated
+- CoverageContribution: A single coverage claim on an assertion
+- RollupMetrics: Aggregated metrics for a requirement node
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class CoverageSource(Enum):
+    """Source type for coverage contributions.
+
+    Different sources have different confidence levels:
+    - DIRECT: High confidence - TEST validates or CODE implements assertion
+    - EXPLICIT: High confidence - REQ implements specific assertion(s) via syntax
+    - INFERRED: Review recommended - REQ implements parent REQ (claims all assertions)
+    """
+
+    DIRECT = "direct"  # TEST/CODE validates/implements assertion
+    EXPLICIT = "explicit"  # REQ implements specific assertions (e.g., REQ-100-A-B)
+    INFERRED = "inferred"  # REQ implements parent REQ (all assertions implied)
+
+
+@dataclass
+class CoverageContribution:
+    """A single coverage contribution to an assertion.
+
+    Tracks which node claims to cover an assertion and how.
+
+    Attributes:
+        source_id: ID of the node providing coverage (TEST, CODE, or REQ)
+        source_type: How the coverage was determined
+        assertion_label: The assertion label being covered (e.g., "A", "B")
+    """
+
+    source_id: str
+    source_type: CoverageSource
+    assertion_label: str
+
+
+@dataclass
+class RollupMetrics:
+    """Aggregated coverage metrics for a requirement.
+
+    Computed once during graph annotation and stored in node._metrics.
+    Provides both aggregate counts and per-assertion detail.
+
+    Attributes:
+        total_assertions: Number of assertions in this requirement
+        covered_assertions: Number with at least one coverage contributor
+        direct_covered: Assertions covered by TEST or CODE nodes
+        explicit_covered: Assertions covered by REQ with assertion syntax
+        inferred_covered: Assertions covered by REQ without assertion syntax
+        coverage_pct: Percentage of assertions covered (0-100)
+        assertion_coverage: Map of assertion label to coverage contributors
+        direct_tested: Assertions covered specifically by TEST nodes
+        validated: Assertions with passing TEST_RESULTs
+        has_failures: True if any TEST_RESULT is failed/error
+    """
+
+    total_assertions: int = 0
+    covered_assertions: int = 0
+    direct_covered: int = 0
+    explicit_covered: int = 0
+    inferred_covered: int = 0
+    coverage_pct: float = 0.0
+    assertion_coverage: dict[str, list[CoverageContribution]] = field(default_factory=dict)
+    # Test-specific metrics
+    direct_tested: int = 0  # Assertions with TEST coverage (not CODE)
+    validated: int = 0  # Assertions with passing TEST_RESULTs
+    has_failures: bool = False  # Any TEST_RESULT failed?
+
+    def add_contribution(self, contribution: CoverageContribution) -> None:
+        """Add a coverage contribution for an assertion.
+
+        Args:
+            contribution: The coverage contribution to add.
+        """
+        label = contribution.assertion_label
+        if label not in self.assertion_coverage:
+            self.assertion_coverage[label] = []
+        self.assertion_coverage[label].append(contribution)
+
+    def finalize(self) -> None:
+        """Compute aggregate counts after all contributions are added.
+
+        Call this after adding all contributions to update the aggregate
+        counts (covered_assertions, direct_covered, etc.) and coverage_pct.
+        """
+        if self.total_assertions == 0:
+            return
+
+        # Track unique assertions by coverage source type
+        direct_labels: set[str] = set()
+        explicit_labels: set[str] = set()
+        inferred_labels: set[str] = set()
+
+        for label, contributions in self.assertion_coverage.items():
+            for contrib in contributions:
+                if contrib.source_type == CoverageSource.DIRECT:
+                    direct_labels.add(label)
+                elif contrib.source_type == CoverageSource.EXPLICIT:
+                    explicit_labels.add(label)
+                elif contrib.source_type == CoverageSource.INFERRED:
+                    inferred_labels.add(label)
+
+        # Count assertions with any coverage
+        all_covered = direct_labels | explicit_labels | inferred_labels
+        self.covered_assertions = len(all_covered)
+        self.direct_covered = len(direct_labels)
+        self.explicit_covered = len(explicit_labels)
+        self.inferred_covered = len(inferred_labels)
+
+        # Compute percentage
+        self.coverage_pct = (self.covered_assertions / self.total_assertions) * 100
+
+
+__all__ = [
+    "CoverageSource",
+    "CoverageContribution",
+    "RollupMetrics",
+]