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

elspais/sponsors/__init__.py

@@ -0,0 +1,432 @@
+"""
+elspais.sponsors - Sponsor/associated repository configuration loading.
+
+Provides functions for loading sponsor configurations from YAML files
+and resolving sponsor spec directories.
+"""
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class Sponsor:
+    """
+    Represents a sponsor/associated repository configuration.
+
+    Attributes:
+        name: Sponsor name (e.g., "callisto")
+        code: Short code used in requirement IDs (e.g., "CAL")
+        enabled: Whether this sponsor is enabled for scanning
+        path: Default path relative to project root
+        spec_path: Spec directory within sponsor path (e.g., "spec")
+        local_path: Override path for local development (from .local.yml)
+    """
+
+    name: str
+    code: str
+    enabled: bool = True
+    path: str = ""
+    spec_path: str = "spec"
+    local_path: Optional[str] = None
+
+
+@dataclass
+class SponsorsConfig:
+    """
+    Container for sponsor configuration.
+
+    Attributes:
+        sponsors: List of Sponsor objects
+        config_file: Path to the sponsors config file
+        local_dir: Default base directory for sponsor repos
+    """
+
+    sponsors: List[Sponsor] = field(default_factory=list)
+    config_file: str = ""
+    local_dir: str = "sponsor"
+
+
+def parse_yaml(content: str) -> Dict[str, Any]:
+    """
+    Parse simple YAML content into a dictionary.
+
+    This is a zero-dependency YAML parser that handles basic structures:
+    - Key-value pairs
+    - Nested dictionaries
+    - Lists of dictionaries
+    - Strings, booleans, numbers
+
+    Args:
+        content: YAML file content
+
+    Returns:
+        Parsed dictionary
+    """
+    result: Dict[str, Any] = {}
+    current_key: Optional[str] = None
+    current_list: Optional[List[Dict]] = None
+    current_dict: Optional[Dict[str, Any]] = None
+    list_key: Optional[str] = None
+    indent_stack: List[tuple] = []  # (indent_level, container)
+
+    lines = content.split("\n")
+
+    for line in lines:
+        # Skip empty lines and comments
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+
+        # Calculate indent level
+        indent = len(line) - len(line.lstrip())
+
+        # Handle list item (starts with -)
+        if stripped.startswith("- "):
+            item_content = stripped[2:].strip()
+
+            # List item with inline key-value (e.g., "- name: value")
+            if ":" in item_content:
+                if current_list is None:
+                    current_list = []
+                    if current_key:
+                        result[current_key] = current_list
+                current_dict = {}
+                current_list.append(current_dict)
+
+                # Parse the key-value on the same line
+                key, value = item_content.split(":", 1)
+                key = key.strip()
+                value = value.strip()
+                if value:
+                    current_dict[key] = _parse_yaml_value(value)
+            continue
+
+        # Handle key-value pair
+        if ":" in stripped:
+            key, value = stripped.split(":", 1)
+            key = key.strip()
+            value = value.strip()
+
+            if value:
+                # Inline value
+                parsed_value = _parse_yaml_value(value)
+                if current_dict is not None and indent > 0:
+                    current_dict[key] = parsed_value
+                else:
+                    result[key] = parsed_value
+            else:
+                # Nested structure starts
+                current_key = key
+                if current_dict is not None and indent > 0:
+                    # Nested dict within list item
+                    pass
+                else:
+                    # Top-level or second-level key
+                    current_list = None
+                    current_dict = None
+
+    return result
+
+
+def _parse_yaml_value(value: str) -> Any:
+    """Parse a YAML value string."""
+    value = value.strip()
+
+    # Remove quotes if present
+    if (value.startswith('"') and value.endswith('"')) or (
+        value.startswith("'") and value.endswith("'")
+    ):
+        return value[1:-1]
+
+    # Boolean
+    if value.lower() == "true":
+        return True
+    if value.lower() == "false":
+        return False
+
+    # Integer
+    if re.match(r"^-?\d+$", value):
+        return int(value)
+
+    # Float
+    if re.match(r"^-?\d+\.\d+$", value):
+        return float(value)
+
+    return value
+
+
+def load_sponsors_yaml(yaml_path: Path) -> Dict[str, Any]:
+    """
+    Load sponsors configuration from a YAML file.
+
+    Handles the nested structure:
+    ```yaml
+    sponsors:
+      local:
+        - name: callisto
+          code: CAL
+          enabled: true
+          path: sponsor/callisto
+          spec_path: spec
+    ```
+
+    Args:
+        yaml_path: Path to the sponsors YAML file
+
+    Returns:
+        Dictionary with sponsor configuration
+    """
+    if not yaml_path.exists():
+        return {}
+
+    content = yaml_path.read_text(encoding="utf-8")
+    return _parse_sponsors_yaml(content)
+
+
+def _parse_sponsors_yaml(content: str) -> Dict[str, Any]:
+    """
+    Parse sponsors YAML content with proper handling of nested lists.
+
+    Args:
+        content: YAML file content
+
+    Returns:
+        Parsed dictionary with sponsors configuration
+    """
+    result: Dict[str, Any] = {"sponsors": {}}
+    current_section = None
+    current_list_key = None
+    current_list: List[Dict] = []
+    current_item: Optional[Dict] = None
+    current_dict_key = None  # For override files: sponsors: callisto: ...
+
+    lines = content.split("\n")
+
+    for line in lines:
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+
+        indent = len(line) - len(line.lstrip())
+
+        # Top-level key (sponsors:)
+        if indent == 0 and stripped.endswith(":"):
+            current_section = stripped[:-1]
+            if current_section not in result:
+                result[current_section] = {}
+            current_list_key = None
+            current_dict_key = None
+            current_item = None
+            continue
+
+        # Second-level key (local:, or sponsor name for overrides)
+        if indent == 2 and ":" in stripped:
+            key, value = stripped.split(":", 1)
+            key = key.strip()
+            value = value.strip()
+
+            if not value:
+                # Could be list (local:) or dict (callisto:) - depends on following content
+                current_list_key = key
+                current_list = []
+                current_dict_key = key
+                # Initialize as empty dict for now, will be replaced with list if needed
+                if current_section:
+                    result[current_section][key] = {}
+            else:
+                # Simple key-value at second level
+                if current_section:
+                    if current_section not in result:
+                        result[current_section] = {}
+                    result[current_section][key] = _parse_yaml_value(value)
+            current_item = None
+            continue
+
+        # List item start (- name: value)
+        if stripped.startswith("- "):
+            item_content = stripped[2:].strip()
+            current_item = {}
+
+            # Convert dict to list if this is our first list item
+            if current_list_key and current_section:
+                if not isinstance(result[current_section].get(current_list_key), list):
+                    result[current_section][current_list_key] = current_list
+
+            current_list.append(current_item)
+
+            if ":" in item_content:
+                key, value = item_content.split(":", 1)
+                current_item[key.strip()] = _parse_yaml_value(value.strip())
+            continue
+
+        # Item property (within a list item)
+        if indent >= 6 and ":" in stripped and current_item is not None:
+            key, value = stripped.split(":", 1)
+            current_item[key.strip()] = _parse_yaml_value(value.strip())
+            continue
+
+        # Third-level key-value for override files (sponsors: callisto: local_path: ...)
+        if indent == 4 and ":" in stripped and current_section and current_dict_key:
+            key, value = stripped.split(":", 1)
+            key = key.strip()
+            value = value.strip()
+
+            if value:
+                # This is a property of the dict entry
+                if isinstance(result[current_section].get(current_dict_key), dict):
+                    result[current_section][current_dict_key][key] = _parse_yaml_value(value)
+
+    return result
+
+
+def load_sponsors_config(
+    config: Dict[str, Any],
+    base_path: Optional[Path] = None,
+) -> SponsorsConfig:
+    """
+    Load sponsor configurations from config files.
+
+    Reads the main sponsors config file and applies local overrides.
+
+    Args:
+        config: Main elspais configuration dictionary
+        base_path: Base path to resolve relative paths (defaults to cwd)
+
+    Returns:
+        SponsorsConfig with loaded sponsors
+    """
+    if base_path is None:
+        base_path = Path.cwd()
+
+    sponsors_config = SponsorsConfig()
+
+    # Get sponsors section from config
+    sponsors_section = config.get("sponsors", {})
+    config_file = sponsors_section.get("config_file", "")
+    sponsors_config.config_file = config_file
+    sponsors_config.local_dir = sponsors_section.get("local_dir", "sponsor")
+
+    if not config_file:
+        return sponsors_config
+
+    # Load main sponsors config
+    config_path = base_path / config_file
+    main_config = load_sponsors_yaml(config_path)
+
+    # Load local overrides if present
+    local_config_path = config_path.with_suffix(".local.yml")
+    local_overrides = load_sponsors_yaml(local_config_path)
+
+    # Parse sponsors from config
+    sponsors_data = main_config.get("sponsors", {})
+
+    # Handle "local" list format (the standard structure)
+    sponsor_list = []
+    if isinstance(sponsors_data, dict):
+        # Check for "local" key containing list
+        if "local" in sponsors_data and isinstance(sponsors_data["local"], list):
+            sponsor_list = sponsors_data["local"]
+
+    # Apply local overrides
+    local_sponsors = local_overrides.get("sponsors", {})
+
+    for sponsor_data in sponsor_list:
+        name = sponsor_data.get("name", "")
+        if not name:
+            continue
+
+        # Check for local override
+        local_path = None
+        if name in local_sponsors:
+            local_override = local_sponsors[name]
+            if isinstance(local_override, dict):
+                local_path = local_override.get("local_path")
+
+        sponsor = Sponsor(
+            name=name,
+            code=sponsor_data.get("code", ""),
+            enabled=sponsor_data.get("enabled", True),
+            path=sponsor_data.get("path", ""),
+            spec_path=sponsor_data.get("spec_path", "spec"),
+            local_path=local_path,
+        )
+        sponsors_config.sponsors.append(sponsor)
+
+    return sponsors_config
+
+
+def resolve_sponsor_spec_dir(
+    sponsor: Sponsor,
+    config: SponsorsConfig,
+    base_path: Optional[Path] = None,
+) -> Optional[Path]:
+    """
+    Resolve the spec directory path for a sponsor.
+
+    Checks local_path override first, then default path.
+
+    Args:
+        sponsor: Sponsor configuration
+        config: Overall sponsors configuration
+        base_path: Base path to resolve relative paths (defaults to cwd)
+
+    Returns:
+        Path to sponsor spec directory, or None if not found
+    """
+    if base_path is None:
+        base_path = Path.cwd()
+
+    if not sponsor.enabled:
+        return None
+
+    # Check local_path override first
+    if sponsor.local_path:
+        spec_dir = Path(sponsor.local_path) / sponsor.spec_path
+        if not spec_dir.is_absolute():
+            spec_dir = base_path / spec_dir
+        if spec_dir.exists() and spec_dir.is_dir():
+            return spec_dir
+
+    # Fall back to default path
+    if sponsor.path:
+        spec_dir = base_path / sponsor.path / sponsor.spec_path
+        if spec_dir.exists() and spec_dir.is_dir():
+            return spec_dir
+
+    # Try local_dir / name / spec_path
+    spec_dir = base_path / config.local_dir / sponsor.name / sponsor.spec_path
+    if spec_dir.exists() and spec_dir.is_dir():
+        return spec_dir
+
+    return None
+
+
+def get_sponsor_spec_directories(
+    config: Dict[str, Any],
+    base_path: Optional[Path] = None,
+) -> List[Path]:
+    """
+    Get all sponsor spec directories from configuration.
+
+    Args:
+        config: Main elspais configuration dictionary
+        base_path: Base path to resolve relative paths (defaults to cwd)
+
+    Returns:
+        List of existing sponsor spec directory paths
+    """
+    if base_path is None:
+        base_path = Path.cwd()
+
+    sponsors_config = load_sponsors_config(config, base_path)
+    spec_dirs = []
+
+    for sponsor in sponsors_config.sponsors:
+        spec_dir = resolve_sponsor_spec_dir(sponsor, sponsors_config, base_path)
+        if spec_dir:
+            spec_dirs.append(spec_dir)
+
+    return spec_dirs

elspais/trace_view/__init__.py

@@ -0,0 +1,54 @@
+# Implements: REQ-int-d00001-A (trace_view package at src/elspais/trace_view/)
+"""
+elspais.trace_view - Interactive traceability matrix generation.
+
+This package provides enhanced traceability features including:
+- Interactive HTML generation with collapsible hierarchies
+- Implementation file scanning
+- Git state tracking (uncommitted, modified, moved files)
+- Review system with comment threads and approval workflows
+
+Optional dependencies:
+- pip install elspais[trace-view] for HTML generation (requires jinja2)
+- pip install elspais[trace-review] for review server (requires flask)
+"""
+
+from elspais.trace_view.models import TraceViewRequirement, TestInfo, GitChangeInfo
+from elspais.trace_view.generators.base import TraceViewGenerator
+
+__all__ = [
+    "TraceViewRequirement",
+    "TestInfo",
+    "GitChangeInfo",
+    "TraceViewGenerator",
+    "generate_markdown",
+    "generate_csv",
+    "generate_html",
+]
+
+
+def generate_markdown(requirements, **kwargs):
+    """Generate Markdown traceability matrix."""
+    from elspais.trace_view.generators.markdown import generate_markdown as _gen
+    return _gen(requirements, **kwargs)
+
+
+def generate_csv(requirements, **kwargs):
+    """Generate CSV traceability matrix."""
+    from elspais.trace_view.generators.csv import generate_csv as _gen
+    return _gen(requirements, **kwargs)
+
+
+def generate_html(requirements, **kwargs):
+    """Generate interactive HTML traceability matrix.
+
+    Requires jinja2: pip install elspais[trace-view]
+    """
+    try:
+        from elspais.trace_view.html import HTMLGenerator
+    except ImportError as e:
+        raise ImportError(
+            "HTML generation requires Jinja2. "
+            "Install with: pip install elspais[trace-view]"
+        ) from e
+    return HTMLGenerator(requirements, **kwargs).generate()

elspais/trace_view/coverage.py

@@ -0,0 +1,183 @@
+"""
+elspais.trace_view.coverage - Coverage calculation for trace-view.
+
+Provides functions to calculate implementation coverage and status
+for requirements.
+"""
+
+from typing import Dict, List, Union
+
+from elspais.trace_view.models import TraceViewRequirement
+
+# Type alias for requirement dict (supports both ID forms)
+ReqDict = Dict[str, TraceViewRequirement]
+
+
+def count_by_level(requirements: ReqDict) -> Dict[str, Dict[str, int]]:
+    """Count requirements by level, both including and excluding Deprecated.
+
+    Args:
+        requirements: Dict mapping requirement ID to TraceViewRequirement
+
+    Returns:
+        Dict with 'active' (excludes Deprecated) and 'all' (includes Deprecated) counts
+        Each contains counts for 'PRD', 'OPS', 'DEV'
+    """
+    counts = {
+        "active": {"PRD": 0, "OPS": 0, "DEV": 0},
+        "all": {"PRD": 0, "OPS": 0, "DEV": 0},
+    }
+    for req in requirements.values():
+        level = req.level
+        counts["all"][level] = counts["all"].get(level, 0) + 1
+        if req.status != "Deprecated":
+            counts["active"][level] = counts["active"].get(level, 0) + 1
+    return counts
+
+
+def find_orphaned_requirements(requirements: ReqDict) -> List[TraceViewRequirement]:
+    """Find requirements not linked from any parent.
+
+    Args:
+        requirements: Dict mapping requirement ID to TraceViewRequirement
+
+    Returns:
+        List of orphaned requirements (non-PRD requirements with no implements)
+    """
+    implemented = set()
+    for req in requirements.values():
+        implemented.update(req.implements)
+
+    orphaned = []
+    for req in requirements.values():
+        # Skip PRD requirements (they're top-level)
+        if req.level == "PRD":
+            continue
+        # Skip if this requirement is implemented by someone
+        if req.id in implemented:
+            continue
+        # Skip if it has no parent (should have one)
+        if not req.implements:
+            orphaned.append(req)
+
+    return sorted(orphaned, key=lambda r: r.id)
+
+
+def calculate_coverage(requirements: ReqDict, req_id: str) -> dict:
+    """Calculate coverage for a requirement.
+
+    Args:
+        requirements: Dict mapping requirement ID to TraceViewRequirement
+        req_id: ID of requirement to calculate coverage for
+
+    Returns:
+        Dict with 'children' (total child count) and 'traced' (children with implementation)
+    """
+    # Find all requirements that implement this requirement (children)
+    children = [r for r in requirements.values() if req_id in r.implements]
+
+    # Count how many children have implementation files or their own children with implementation
+    traced = 0
+    for child in children:
+        child_status = get_implementation_status(requirements, child.id)
+        if child_status in ["Full", "Partial"]:
+            traced += 1
+
+    return {"children": len(children), "traced": traced}
+
+
+def get_implementation_status(requirements: ReqDict, req_id: str) -> str:
+    """Get implementation status for a requirement.
+
+    Args:
+        requirements: Dict mapping requirement ID to TraceViewRequirement
+        req_id: ID of requirement to check
+
+    Returns:
+        'Unimplemented': No children AND no implementation_files
+        'Partial': Some but not all children traced
+        'Full': Has implementation_files OR all children traced
+    """
+    req = requirements.get(req_id)
+    if not req:
+        return "Unimplemented"
+
+    # If requirement has implementation files, it's fully implemented
+    if req.implementation_files:
+        return "Full"
+
+    # Find children
+    children = [r for r in requirements.values() if req_id in r.implements]
+
+    # No children and no implementation files = Unimplemented
+    if not children:
+        return "Unimplemented"
+
+    # Check how many children are traced
+    coverage = calculate_coverage(requirements, req_id)
+
+    if coverage["traced"] == 0:
+        return "Unimplemented"
+    elif coverage["traced"] == coverage["children"]:
+        return "Full"
+    else:
+        return "Partial"
+
+
+def generate_coverage_report(
+    requirements: ReqDict, get_status_fn=None
+) -> str:
+    """Generate text-based coverage report with summary statistics.
+
+    Args:
+        requirements: Dict mapping requirement ID to TraceViewRequirement
+        get_status_fn: Optional function to get implementation status.
+                       If None, uses get_implementation_status.
+
+    Returns:
+        Formatted text report showing:
+        - Total requirements count
+        - Breakdown by level (PRD, OPS, DEV) with percentages
+        - Breakdown by implementation status (Full/Partial/Unimplemented)
+    """
+    if get_status_fn is None:
+        get_status_fn = lambda req_id: get_implementation_status(requirements, req_id)
+
+    lines = []
+    lines.append("=== Coverage Report ===")
+    lines.append(f"Total Requirements: {len(requirements)}")
+    lines.append("")
+
+    # Count by level
+    by_level = {"PRD": 0, "OPS": 0, "DEV": 0}
+    implemented_by_level = {"PRD": 0, "OPS": 0, "DEV": 0}
+
+    for req in requirements.values():
+        level = req.level
+        by_level[level] = by_level.get(level, 0) + 1
+
+        impl_status = get_status_fn(req.id)
+        if impl_status in ["Full", "Partial"]:
+            implemented_by_level[level] = implemented_by_level.get(level, 0) + 1
+
+    lines.append("By Level:")
+    for level in ["PRD", "OPS", "DEV"]:
+        total = by_level[level]
+        implemented = implemented_by_level[level]
+        percentage = (implemented / total * 100) if total > 0 else 0
+        lines.append(f"  {level}: {total} ({percentage:.0f}% implemented)")
+
+    lines.append("")
+
+    # Count by implementation status
+    status_counts = {"Full": 0, "Partial": 0, "Unimplemented": 0}
+    for req in requirements.values():
+        impl_status = get_status_fn(req.id)
+        status_counts[impl_status] = status_counts.get(impl_status, 0) + 1
+
+    lines.append("By Status:")
+    lines.append(f"  Full: {status_counts['Full']}")
+    lines.append(f"  Partial: {status_counts['Partial']}")
+    lines.append(f"  Unimplemented: {status_counts['Unimplemented']}")
+
+    return "\n".join(lines)

elspais/trace_view/generators/__init__.py

@@ -0,0 +1,12 @@
+# Implements: REQ-int-d00001-A (trace_view package structure)
+"""
+elspais.trace_view.generators - Output format generators.
+
+Provides Markdown and CSV generators (no dependencies).
+HTML generator is in the html/ subpackage (requires jinja2).
+"""
+
+from elspais.trace_view.generators.markdown import generate_markdown
+from elspais.trace_view.generators.csv import generate_csv
+
+__all__ = ["generate_markdown", "generate_csv"]