elspais 0.9.1__py3-none-any.whl

elspais/mcp/context.py

@@ -0,0 +1,171 @@
+"""
+elspais.mcp.context - Workspace context for MCP server.
+
+Manages workspace state including configuration, requirements cache,
+and content rules.
+"""
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from elspais.config.loader import find_config_file, get_spec_directories, load_config
+from elspais.core.content_rules import load_content_rules
+from elspais.core.models import ContentRule, Requirement
+from elspais.core.parser import RequirementParser
+from elspais.core.patterns import PatternConfig
+
+
+@dataclass
+class WorkspaceContext:
+    """
+    Manages workspace state for MCP server operations.
+
+    Provides caching of parsed requirements and access to configuration,
+    content rules, and other workspace resources.
+    """
+
+    working_dir: Path
+    config: Dict[str, Any] = field(default_factory=dict)
+    _requirements_cache: Optional[Dict[str, Requirement]] = field(default=None, repr=False)
+    _parser: Optional[RequirementParser] = field(default=None, repr=False)
+
+    @classmethod
+    def from_directory(cls, directory: Path) -> "WorkspaceContext":
+        """
+        Initialize context from a working directory.
+
+        Loads configuration from .elspais.toml if found.
+
+        Args:
+            directory: Working directory path
+
+        Returns:
+            Initialized WorkspaceContext
+        """
+        directory = directory.resolve()
+        config_path = find_config_file(directory)
+
+        if config_path:
+            config = load_config(config_path)
+        else:
+            # Use defaults
+            from elspais.config.defaults import DEFAULT_CONFIG
+            config = DEFAULT_CONFIG.copy()
+
+        return cls(working_dir=directory, config=config)
+
+    def get_requirements(self, force_refresh: bool = False) -> Dict[str, Requirement]:
+        """
+        Get all parsed requirements, with caching.
+
+        Args:
+            force_refresh: If True, ignore cache and re-parse
+
+        Returns:
+            Dict mapping requirement IDs to Requirement objects
+        """
+        if self._requirements_cache is None or force_refresh:
+            self._requirements_cache = self._parse_requirements()
+        return self._requirements_cache
+
+    def get_requirement(self, req_id: str) -> Optional[Requirement]:
+        """
+        Get a single requirement by ID.
+
+        Args:
+            req_id: Requirement ID (e.g., "REQ-p00001")
+
+        Returns:
+            Requirement if found, None otherwise
+        """
+        requirements = self.get_requirements()
+        return requirements.get(req_id)
+
+    def get_content_rules(self) -> List[ContentRule]:
+        """
+        Get all configured content rules.
+
+        Returns:
+            List of ContentRule objects
+        """
+        return load_content_rules(self.config, self.working_dir)
+
+    def search_requirements(
+        self,
+        query: str,
+        field: str = "all",
+        regex: bool = False,
+    ) -> List[Requirement]:
+        """
+        Search requirements by pattern.
+
+        Args:
+            query: Search query string
+            field: Field to search - "all", "id", "title", "body", "assertions"
+            regex: If True, treat query as regex pattern
+
+        Returns:
+            List of matching requirements
+        """
+        requirements = self.get_requirements()
+        results = []
+
+        if regex:
+            pattern = re.compile(query, re.IGNORECASE)
+        else:
+            pattern = re.compile(re.escape(query), re.IGNORECASE)
+
+        for req in requirements.values():
+            if self._matches(req, pattern, field):
+                results.append(req)
+
+        return results
+
+    def invalidate_cache(self) -> None:
+        """Clear cached requirements (call after edits)."""
+        self._requirements_cache = None
+
+    def _parse_requirements(self) -> Dict[str, Requirement]:
+        """Parse requirements from spec directories."""
+        if self._parser is None:
+            pattern_config = PatternConfig.from_dict(self.config.get("patterns", {}))
+            self._parser = RequirementParser(pattern_config)
+
+        spec_dirs = get_spec_directories(None, self.config, self.working_dir)
+        skip_files = self.config.get("spec", {}).get("skip_files", [])
+
+        all_requirements: Dict[str, Requirement] = {}
+
+        for spec_dir in spec_dirs:
+            if spec_dir.exists():
+                requirements = self._parser.parse_directory(spec_dir, skip_files=skip_files)
+                all_requirements.update(requirements)
+
+        return all_requirements
+
+    def _matches(self, req: Requirement, pattern: re.Pattern, field: str) -> bool:
+        """Check if requirement matches search pattern."""
+        if field == "id":
+            return bool(pattern.search(req.id))
+        elif field == "title":
+            return bool(pattern.search(req.title))
+        elif field == "body":
+            return bool(pattern.search(req.body))
+        elif field == "assertions":
+            for assertion in req.assertions:
+                if pattern.search(assertion.text):
+                    return True
+            return False
+        else:  # "all"
+            if pattern.search(req.id):
+                return True
+            if pattern.search(req.title):
+                return True
+            if pattern.search(req.body):
+                return True
+            for assertion in req.assertions:
+                if pattern.search(assertion.text):
+                    return True
+            return False

elspais/mcp/serializers.py

@@ -0,0 +1,112 @@
+"""
+elspais.mcp.serializers - JSON serialization for MCP responses.
+
+Provides functions to serialize elspais data models to JSON-compatible dicts.
+"""
+
+from typing import Any, Dict, List
+
+from elspais.core.models import Assertion, ContentRule, Requirement
+from elspais.core.rules import RuleViolation
+
+
+def serialize_requirement(req: Requirement) -> Dict[str, Any]:
+    """
+    Serialize a Requirement to a JSON-compatible dict.
+
+    Args:
+        req: Requirement to serialize
+
+    Returns:
+        Dict suitable for JSON serialization
+    """
+    return {
+        "id": req.id,
+        "title": req.title,
+        "level": req.level,
+        "status": req.status,
+        "body": req.body,
+        "implements": req.implements,
+        "assertions": [serialize_assertion(a) for a in req.assertions],
+        "rationale": req.rationale,
+        "hash": req.hash,
+        "file_path": str(req.file_path) if req.file_path else None,
+        "line_number": req.line_number,
+        "subdir": req.subdir,
+        "type_code": req.type_code,
+    }
+
+
+def serialize_requirement_summary(req: Requirement) -> Dict[str, Any]:
+    """
+    Serialize requirement summary (lighter weight, for listings).
+
+    Args:
+        req: Requirement to serialize
+
+    Returns:
+        Dict with summary fields only
+    """
+    return {
+        "id": req.id,
+        "title": req.title,
+        "level": req.level,
+        "status": req.status,
+        "implements": req.implements,
+        "assertion_count": len(req.assertions),
+    }
+
+
+def serialize_assertion(assertion: Assertion) -> Dict[str, Any]:
+    """
+    Serialize an Assertion to a JSON-compatible dict.
+
+    Args:
+        assertion: Assertion to serialize
+
+    Returns:
+        Dict suitable for JSON serialization
+    """
+    return {
+        "label": assertion.label,
+        "text": assertion.text,
+        "is_placeholder": assertion.is_placeholder,
+    }
+
+
+def serialize_violation(violation: RuleViolation) -> Dict[str, Any]:
+    """
+    Serialize a RuleViolation to a JSON-compatible dict.
+
+    Args:
+        violation: RuleViolation to serialize
+
+    Returns:
+        Dict suitable for JSON serialization
+    """
+    return {
+        "rule_name": violation.rule_name,
+        "requirement_id": violation.requirement_id,
+        "message": violation.message,
+        "severity": violation.severity.value,
+        "location": violation.location,
+    }
+
+
+def serialize_content_rule(rule: ContentRule) -> Dict[str, Any]:
+    """
+    Serialize a ContentRule to a JSON-compatible dict.
+
+    Args:
+        rule: ContentRule to serialize
+
+    Returns:
+        Dict suitable for JSON serialization
+    """
+    return {
+        "file_path": str(rule.file_path),
+        "title": rule.title,
+        "content": rule.content,
+        "type": rule.type,
+        "applies_to": rule.applies_to,
+    }

elspais/mcp/server.py

@@ -0,0 +1,339 @@
+"""
+elspais.mcp.server - MCP server implementation.
+
+Creates and runs the MCP server exposing elspais functionality.
+"""
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+try:
+    from mcp.server.fastmcp import FastMCP
+    MCP_AVAILABLE = True
+except ImportError:
+    MCP_AVAILABLE = False
+    FastMCP = None
+
+from elspais.mcp.context import WorkspaceContext
+from elspais.mcp.serializers import (
+    serialize_content_rule,
+    serialize_requirement,
+    serialize_requirement_summary,
+    serialize_violation,
+)
+
+
+def create_server(working_dir: Optional[Path] = None) -> "FastMCP":
+    """
+    Create and configure the MCP server.
+
+    Args:
+        working_dir: Working directory for finding .elspais.toml
+                    Defaults to current working directory
+
+    Returns:
+        Configured FastMCP server instance
+
+    Raises:
+        ImportError: If MCP dependencies are not installed
+    """
+    if not MCP_AVAILABLE:
+        raise ImportError(
+            "MCP dependencies not installed. "
+            "Install with: pip install elspais[mcp]"
+        )
+
+    if working_dir is None:
+        working_dir = Path.cwd()
+
+    # Initialize workspace context
+    ctx = WorkspaceContext.from_directory(working_dir)
+
+    # Create FastMCP server
+    mcp = FastMCP(
+        name="elspais",
+    )
+
+    # Register resources
+    _register_resources(mcp, ctx)
+
+    # Register tools
+    _register_tools(mcp, ctx)
+
+    return mcp
+
+
+def _register_resources(mcp: "FastMCP", ctx: WorkspaceContext) -> None:
+    """Register MCP resources."""
+
+    @mcp.resource("requirements://all")
+    def list_all_requirements() -> str:
+        """
+        Get list of all requirements in the workspace.
+
+        Returns summary information for each requirement including
+        ID, title, level, status, and assertion count.
+        """
+        import json
+        requirements = ctx.get_requirements()
+        return json.dumps({
+            "count": len(requirements),
+            "requirements": [
+                serialize_requirement_summary(req)
+                for req in requirements.values()
+            ]
+        }, indent=2)
+
+    @mcp.resource("requirements://{req_id}")
+    def get_requirement_resource(req_id: str) -> str:
+        """
+        Get detailed information about a specific requirement.
+
+        Returns full requirement data including body, assertions,
+        implements references, and location.
+        """
+        import json
+        req = ctx.get_requirement(req_id)
+        if req is None:
+            return json.dumps({"error": f"Requirement {req_id} not found"})
+        return json.dumps(serialize_requirement(req), indent=2)
+
+    @mcp.resource("requirements://level/{level}")
+    def get_requirements_by_level(level: str) -> str:
+        """Get all requirements of a specific level (PRD, OPS, DEV)."""
+        import json
+        requirements = ctx.get_requirements()
+        filtered = [
+            r for r in requirements.values()
+            if r.level.upper() == level.upper()
+        ]
+        return json.dumps({
+            "level": level,
+            "count": len(filtered),
+            "requirements": [serialize_requirement_summary(r) for r in filtered]
+        }, indent=2)
+
+    @mcp.resource("content-rules://list")
+    def list_content_rules() -> str:
+        """List all configured content rule files."""
+        import json
+        rules = ctx.get_content_rules()
+        return json.dumps({
+            "count": len(rules),
+            "rules": [
+                {
+                    "file": str(r.file_path),
+                    "title": r.title,
+                    "type": r.type,
+                    "applies_to": r.applies_to,
+                }
+                for r in rules
+            ]
+        }, indent=2)
+
+    @mcp.resource("content-rules://{filename}")
+    def get_content_rule(filename: str) -> str:
+        """
+        Get content of a content rule markdown file.
+
+        Content rules are documentation files that describe
+        requirement formats and authoring guidelines.
+        """
+        import json
+        rules = ctx.get_content_rules()
+        for rule in rules:
+            if rule.file_path.name == filename or str(rule.file_path).endswith(filename):
+                return json.dumps(serialize_content_rule(rule), indent=2)
+        return json.dumps({"error": f"Content rule not found: {filename}"})
+
+    @mcp.resource("config://current")
+    def get_current_config() -> str:
+        """Get the current elspais configuration."""
+        import json
+        return json.dumps(ctx.config, indent=2, default=str)
+
+
+def _register_tools(mcp: "FastMCP", ctx: WorkspaceContext) -> None:
+    """Register MCP tools."""
+
+    @mcp.tool()
+    def validate(skip_rules: Optional[List[str]] = None) -> Dict[str, Any]:
+        """
+        Validate all requirements in the workspace.
+
+        Checks format, hierarchy relationships, hashes, and links.
+        Returns violations grouped by severity.
+
+        Args:
+            skip_rules: Optional list of rule names to skip
+        """
+        from elspais.core.rules import RuleEngine, RulesConfig, Severity
+
+        requirements = ctx.get_requirements(force_refresh=True)
+        rules_config = RulesConfig.from_dict(ctx.config.get("rules", {}))
+        engine = RuleEngine(rules_config)
+
+        violations = engine.validate(requirements)
+
+        # Filter by skip_rules
+        if skip_rules:
+            violations = [v for v in violations if v.rule_name not in skip_rules]
+
+        errors = [v for v in violations if v.severity == Severity.ERROR]
+        warnings = [v for v in violations if v.severity == Severity.WARNING]
+
+        return {
+            "valid": len(errors) == 0,
+            "errors": [serialize_violation(v) for v in errors],
+            "warnings": [serialize_violation(v) for v in warnings],
+            "summary": f"{len(errors)} errors, {len(warnings)} warnings in {len(requirements)} requirements"
+        }
+
+    @mcp.tool()
+    def parse_requirement(text: str, file_path: Optional[str] = None) -> Dict[str, Any]:
+        """
+        Parse requirement text and extract structured data.
+
+        Args:
+            text: Markdown text containing one or more requirements
+            file_path: Optional source file path for location info
+        """
+        from elspais.core.parser import RequirementParser
+        from elspais.core.patterns import PatternConfig
+
+        pattern_config = PatternConfig.from_dict(ctx.config.get("patterns", {}))
+        parser = RequirementParser(pattern_config)
+        path = Path(file_path) if file_path else None
+        requirements = parser.parse_text(text, file_path=path)
+
+        return {
+            "count": len(requirements),
+            "requirements": {
+                req_id: serialize_requirement(req)
+                for req_id, req in requirements.items()
+            }
+        }
+
+    @mcp.tool()
+    def search(
+        query: str,
+        field: str = "all",
+        regex: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        Search requirements by pattern.
+
+        Args:
+            query: Search query string
+            field: Field to search - "all", "id", "title", "body", "assertions"
+            regex: If true, treat query as regex pattern
+        """
+        results = ctx.search_requirements(query, field, regex)
+        return {
+            "count": len(results),
+            "query": query,
+            "field": field,
+            "requirements": [serialize_requirement_summary(r) for r in results]
+        }
+
+    @mcp.tool()
+    def get_requirement(req_id: str) -> Dict[str, Any]:
+        """
+        Get complete details for a single requirement.
+
+        Args:
+            req_id: The requirement ID (e.g., "REQ-p00001")
+        """
+        req = ctx.get_requirement(req_id)
+        if req is None:
+            return {"error": f"Requirement {req_id} not found"}
+        return serialize_requirement(req)
+
+    @mcp.tool()
+    def analyze(analysis_type: str = "hierarchy") -> Dict[str, Any]:
+        """
+        Analyze requirement structure.
+
+        Args:
+            analysis_type: One of "hierarchy", "orphans", "coverage"
+        """
+        requirements = ctx.get_requirements()
+
+        if analysis_type == "hierarchy":
+            return _analyze_hierarchy(requirements)
+        elif analysis_type == "orphans":
+            return _analyze_orphans(requirements)
+        elif analysis_type == "coverage":
+            return _analyze_coverage(requirements)
+        else:
+            return {"error": f"Unknown analysis type: {analysis_type}"}
+
+
+def _analyze_hierarchy(requirements: Dict[str, Any]) -> Dict[str, Any]:
+    """Analyze requirement hierarchy."""
+    # Build parent -> children mapping
+    children_map: Dict[str, List[str]] = {}
+    roots = []
+
+    for req in requirements.values():
+        if not req.implements:
+            roots.append(req.id)
+        else:
+            for parent_id in req.implements:
+                if parent_id not in children_map:
+                    children_map[parent_id] = []
+                children_map[parent_id].append(req.id)
+
+    return {
+        "total": len(requirements),
+        "roots": roots,
+        "children_map": children_map,
+    }
+
+
+def _analyze_orphans(requirements: Dict[str, Any]) -> Dict[str, Any]:
+    """Find orphaned requirements."""
+    all_ids = set(requirements.keys())
+    orphans = []
+
+    for req in requirements.values():
+        for parent_id in req.implements:
+            if parent_id not in all_ids:
+                orphans.append({
+                    "id": req.id,
+                    "missing_parent": parent_id,
+                })
+
+    return {
+        "count": len(orphans),
+        "orphans": orphans,
+    }
+
+
+def _analyze_coverage(requirements: Dict[str, Any]) -> Dict[str, Any]:
+    """Analyze requirement coverage by level."""
+    levels: Dict[str, int] = {}
+
+    for req in requirements.values():
+        level = req.level.upper()
+        levels[level] = levels.get(level, 0) + 1
+
+    return {
+        "total": len(requirements),
+        "by_level": levels,
+    }
+
+
+def run_server(
+    working_dir: Optional[Path] = None,
+    transport: str = "stdio",
+) -> None:
+    """
+    Run the MCP server.
+
+    Args:
+        working_dir: Working directory
+        transport: Transport type - "stdio", "sse", or "streamable-http"
+    """
+    mcp = create_server(working_dir)
+    mcp.run(transport=transport)

elspais/testing/__init__.py

@@ -0,0 +1,27 @@
+"""
+elspais.testing - Test mapping and coverage functionality.
+
+This package provides test-to-requirement mapping and coverage analysis:
+- TestingConfig: Configuration for test scanning
+- TestScanner: Scans test files for requirement references
+- ResultParser: Parses JUnit XML and pytest JSON results
+- TestMapper: Orchestrates scanning and result mapping
+"""
+
+from elspais.testing.config import TestingConfig
+from elspais.testing.mapper import RequirementTestData, TestMapper, TestMappingResult
+from elspais.testing.result_parser import ResultParser, TestResult, TestStatus
+from elspais.testing.scanner import TestReference, TestScanResult, TestScanner
+
+__all__ = [
+    "TestingConfig",
+    "TestScanner",
+    "TestScanResult",
+    "TestReference",
+    "ResultParser",
+    "TestResult",
+    "TestStatus",
+    "TestMapper",
+    "TestMappingResult",
+    "RequirementTestData",
+]

elspais/testing/config.py

@@ -0,0 +1,48 @@
+"""
+elspais.testing.config - Configuration for test mapping and coverage.
+
+Provides TestingConfig dataclass for configuring test file scanning
+and result file parsing.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List
+
+
+@dataclass
+class TestingConfig:
+    """
+    Configuration for test mapping and coverage features.
+
+    Attributes:
+        enabled: Whether test mapping is enabled (default: False)
+        test_dirs: Glob patterns for test directories to scan
+        patterns: File patterns to match test files (e.g., "*_test.py")
+        result_files: Glob patterns for test result files (JUnit XML, pytest JSON)
+        reference_patterns: Regex patterns to extract requirement IDs from tests
+    """
+
+    enabled: bool = False
+    test_dirs: List[str] = field(default_factory=list)
+    patterns: List[str] = field(default_factory=list)
+    result_files: List[str] = field(default_factory=list)
+    reference_patterns: List[str] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "TestingConfig":
+        """
+        Create TestingConfig from configuration dictionary.
+
+        Args:
+            data: Dictionary from [testing] config section
+
+        Returns:
+            TestingConfig instance with values from data or defaults
+        """
+        return cls(
+            enabled=data.get("enabled", False),
+            test_dirs=data.get("test_dirs", []),
+            patterns=data.get("patterns", []),
+            result_files=data.get("result_files", []),
+            reference_patterns=data.get("reference_patterns", []),
+        )