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

elspais/trace_view/generators/base.py

@@ -0,0 +1,329 @@
+# Implements: REQ-tv-p00001 (TraceViewGenerator)
+"""
+elspais.trace_view.generators.base - Base generator for trace-view.
+
+Provides the main TraceViewGenerator class that orchestrates
+requirement parsing, implementation scanning, and output generation.
+"""
+
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from elspais.config.loader import find_config_file, load_config, get_spec_directories
+from elspais.config.defaults import DEFAULT_CONFIG
+from elspais.core.parser import RequirementParser
+from elspais.core.patterns import PatternConfig
+from elspais.core.git import get_git_changes, GitChangeInfo
+
+from elspais.trace_view.models import TraceViewRequirement, GitChangeInfo as TVGitChangeInfo
+from elspais.trace_view.scanning import scan_implementation_files
+from elspais.trace_view.coverage import (
+    calculate_coverage,
+    generate_coverage_report,
+    get_implementation_status,
+)
+from elspais.trace_view.generators.csv import generate_csv, generate_planning_csv
+from elspais.trace_view.generators.markdown import generate_markdown
+
+
+class TraceViewGenerator:
+    """Generates traceability matrices.
+
+    This is the main entry point for generating traceability reports.
+    Supports multiple output formats: markdown, html, csv.
+
+    Args:
+        spec_dir: Path to the spec directory containing requirement files
+        impl_dirs: List of directories to scan for implementation references
+        sponsor: Sponsor name for sponsor-specific reports
+        mode: Report mode ('core', 'sponsor', 'combined')
+        repo_root: Repository root path for relative path calculation
+        associated_repos: List of associated repo dicts for multi-repo scanning
+        config: Optional pre-loaded configuration dict
+    """
+
+    # Version number - increment with each change
+    VERSION = 17
+
+    def __init__(
+        self,
+        spec_dir: Optional[Path] = None,
+        impl_dirs: Optional[List[Path]] = None,
+        sponsor: Optional[str] = None,
+        mode: str = "core",
+        repo_root: Optional[Path] = None,
+        associated_repos: Optional[list] = None,
+        config: Optional[dict] = None,
+    ):
+        self.spec_dir = spec_dir
+        self.requirements: Dict[str, TraceViewRequirement] = {}
+        self.impl_dirs = impl_dirs or []
+        self.sponsor = sponsor
+        self.mode = mode
+        self.repo_root = repo_root or (spec_dir.parent if spec_dir else Path.cwd())
+        self.associated_repos = associated_repos or []
+        self._base_path = ""
+        self._config = config
+        self._git_info: Optional[TVGitChangeInfo] = None
+
+    def generate(
+        self,
+        format: str = "markdown",
+        output_file: Optional[Path] = None,
+        embed_content: bool = False,
+        edit_mode: bool = False,
+        review_mode: bool = False,
+        quiet: bool = False,
+    ) -> str:
+        """Generate traceability matrix in specified format.
+
+        Args:
+            format: Output format ('markdown', 'html', 'csv')
+            output_file: Path to write output (default: traceability_matrix.{ext})
+            embed_content: If True, embed full requirement content in HTML
+            edit_mode: If True, include edit mode UI in HTML output
+            review_mode: If True, include review mode UI in HTML output
+            quiet: If True, suppress progress messages
+
+        Returns:
+            The generated content as a string
+        """
+        # Initialize git state
+        self._init_git_state(quiet)
+
+        # Parse requirements
+        if not quiet:
+            print(f"Scanning for requirements...")
+        self._parse_requirements(quiet)
+
+        if not self.requirements:
+            if not quiet:
+                print("Warning: No requirements found")
+            return ""
+
+        if not quiet:
+            print(f"Found {len(self.requirements)} requirements")
+
+        # Pre-detect cycles and mark affected requirements
+        self._detect_and_mark_cycles(quiet)
+
+        # Scan implementation files
+        if self.impl_dirs:
+            if not quiet:
+                print("Scanning implementation files...")
+            scan_implementation_files(
+                self.requirements,
+                self.impl_dirs,
+                self.repo_root,
+                self.mode,
+                self.sponsor,
+                quiet=quiet,
+            )
+
+        if not quiet:
+            print(f"Generating {format.upper()} traceability matrix...")
+
+        # Determine output path and extension
+        if format == "html":
+            ext = ".html"
+        elif format == "csv":
+            ext = ".csv"
+        else:
+            ext = ".md"
+
+        if output_file is None:
+            output_file = Path(f"traceability_matrix{ext}")
+
+        # Calculate relative path for links
+        self._calculate_base_path(output_file)
+
+        # Generate content
+        if format == "html":
+            from elspais.trace_view.html import HTMLGenerator
+
+            html_gen = HTMLGenerator(
+                requirements=self.requirements,
+                base_path=self._base_path,
+                mode=self.mode,
+                sponsor=self.sponsor,
+                version=self.VERSION,
+                repo_root=self.repo_root,
+            )
+            content = html_gen.generate(
+                embed_content=embed_content, edit_mode=edit_mode, review_mode=review_mode
+            )
+        elif format == "csv":
+            content = generate_csv(self.requirements)
+        else:
+            content = generate_markdown(self.requirements, self._base_path)
+
+        # Write output file
+        output_file.write_text(content)
+        if not quiet:
+            print(f"Traceability matrix written to: {output_file}")
+
+        return content
+
+    def _init_git_state(self, quiet: bool = False):
+        """Initialize git state for requirement status detection."""
+        try:
+            git_changes = get_git_changes(self.repo_root)
+
+            # Convert to trace_view GitChangeInfo
+            self._git_info = TVGitChangeInfo(
+                uncommitted_files=git_changes.uncommitted_files,
+                untracked_files=git_changes.untracked_files,
+                branch_changed_files=git_changes.branch_changed_files,
+                committed_req_locations=git_changes.committed_req_locations,
+            )
+
+            # Report uncommitted changes
+            if not quiet and git_changes.uncommitted_files:
+                spec_uncommitted = [
+                    f for f in git_changes.uncommitted_files if f.startswith("spec/")
+                ]
+                if spec_uncommitted:
+                    print(f"Uncommitted spec files: {len(spec_uncommitted)}")
+
+            # Report branch changes vs main
+            if not quiet and git_changes.branch_changed_files:
+                spec_branch = [
+                    f for f in git_changes.branch_changed_files if f.startswith("spec/")
+                ]
+                if spec_branch:
+                    print(f"Spec files changed vs main: {len(spec_branch)}")
+
+        except Exception as e:
+            # Git state is optional - continue without it
+            if not quiet:
+                print(f"Warning: Could not get git state: {e}")
+            self._git_info = None
+
+    def _parse_requirements(self, quiet: bool = False):
+        """Parse all requirements using elspais parser directly."""
+        # Load config if not provided
+        if self._config is None:
+            config_path = find_config_file(self.repo_root)
+            if config_path and config_path.exists():
+                self._config = load_config(config_path)
+            else:
+                self._config = DEFAULT_CONFIG
+
+        # Get spec directories
+        spec_dirs = get_spec_directories(self.spec_dir, self._config)
+        if not spec_dirs:
+            return
+
+        # Parse requirements using elspais parser
+        pattern_config = PatternConfig.from_dict(self._config.get("patterns", {}))
+        spec_config = self._config.get("spec", {})
+        no_reference_values = spec_config.get("no_reference_values")
+        skip_files = spec_config.get("skip_files", [])
+
+        parser = RequirementParser(pattern_config, no_reference_values=no_reference_values)
+        parse_result = parser.parse_directories(spec_dirs, skip_files=skip_files)
+
+        roadmap_count = 0
+        conflict_count = 0
+        cycle_count = 0
+
+        for req_id, core_req in parse_result.items():
+            # Wrap in TraceViewRequirement
+            tv_req = TraceViewRequirement.from_core(core_req, git_info=self._git_info)
+
+            if tv_req.is_roadmap:
+                roadmap_count += 1
+            if tv_req.is_conflict:
+                conflict_count += 1
+                if not quiet:
+                    print(f"   Warning: Conflict: {req_id} conflicts with {tv_req.conflict_with}")
+
+            # Store by short ID (without REQ- prefix)
+            self.requirements[tv_req.id] = tv_req
+
+        if not quiet:
+            if roadmap_count > 0:
+                print(f"   Found {roadmap_count} roadmap requirements")
+            if conflict_count > 0:
+                print(f"   Found {conflict_count} conflicts")
+            if cycle_count > 0:
+                print(f"   Found {cycle_count} requirements in dependency cycles")
+
+    def _detect_and_mark_cycles(self, quiet: bool = False):
+        """Detect and mark requirements that are part of dependency cycles."""
+        # Simple cycle detection using DFS
+        visited = set()
+        rec_stack = set()
+        cycle_members = set()
+
+        def dfs(req_id: str, path: List[str]) -> bool:
+            if req_id in rec_stack:
+                # Found cycle - mark all members in the cycle path
+                cycle_start = path.index(req_id)
+                for member in path[cycle_start:]:
+                    cycle_members.add(member)
+                return True
+
+            if req_id in visited:
+                return False
+
+            visited.add(req_id)
+            rec_stack.add(req_id)
+
+            req = self.requirements.get(req_id)
+            if req:
+                for parent_id in req.implements:
+                    # Normalize parent_id
+                    parent_id = parent_id.replace("REQ-", "")
+                    if parent_id in self.requirements:
+                        if dfs(parent_id, path + [req_id]):
+                            cycle_members.add(req_id)
+
+            rec_stack.remove(req_id)
+            return False
+
+        # Run DFS from each requirement
+        for req_id in self.requirements:
+            if req_id not in visited:
+                dfs(req_id, [])
+
+        # Clear implements for cycle members so they appear as orphaned
+        cycle_count = 0
+        for req_id in cycle_members:
+            if req_id in self.requirements:
+                req = self.requirements[req_id]
+                if req.implements:
+                    # Modify the underlying core requirement
+                    req.core.implements = []
+                    cycle_count += 1
+
+        if not quiet and cycle_count > 0:
+            print(f"   Warning: {cycle_count} requirements marked as cyclic (shown as orphaned items)")
+
+    def _calculate_base_path(self, output_file: Path):
+        """Calculate relative path from output file location to repo root."""
+        try:
+            output_dir = output_file.resolve().parent
+            repo_root = self.repo_root.resolve()
+
+            try:
+                rel_path = output_dir.relative_to(repo_root)
+                depth = len(rel_path.parts)
+                if depth == 0:
+                    self._base_path = ""
+                else:
+                    self._base_path = "../" * depth
+            except ValueError:
+                self._base_path = f"file://{repo_root}/"
+        except Exception:
+            self._base_path = "../"
+
+    def generate_planning_csv(self) -> str:
+        """Generate planning CSV with actionable requirements."""
+        get_status = lambda req_id: get_implementation_status(self.requirements, req_id)
+        calc_coverage = lambda req_id: calculate_coverage(self.requirements, req_id)
+        return generate_planning_csv(self.requirements, get_status, calc_coverage)
+
+    def generate_coverage_report(self) -> str:
+        """Generate coverage report showing implementation status."""
+        return generate_coverage_report(self.requirements)

elspais/trace_view/generators/csv.py

@@ -0,0 +1,122 @@
+"""
+elspais.trace_view.generators.csv - CSV generation.
+
+Provides functions to generate CSV traceability matrices and planning exports.
+"""
+
+import csv
+from io import StringIO
+from typing import Callable, Dict
+
+from elspais.trace_view.models import TraceViewRequirement
+
+
+def generate_csv(requirements: Dict[str, TraceViewRequirement]) -> str:
+    """Generate CSV traceability matrix.
+
+    Args:
+        requirements: Dict mapping requirement ID to TraceViewRequirement
+
+    Returns:
+        CSV string with columns: Requirement ID, Title, Level, Status,
+        Implements, Traced By, File, Line, Implementation Files
+    """
+    output = StringIO()
+    writer = csv.writer(output)
+
+    # Header
+    writer.writerow(
+        [
+            "Requirement ID",
+            "Title",
+            "Level",
+            "Status",
+            "Implements",
+            "Traced By",
+            "File",
+            "Line",
+            "Implementation Files",
+        ]
+    )
+
+    # Sort requirements by ID
+    sorted_reqs = sorted(requirements.values(), key=lambda r: r.id)
+
+    for req in sorted_reqs:
+        # Compute children (traced by) dynamically
+        children = [r.id for r in requirements.values() if req.id in r.implements]
+
+        # Format implementation files as "file:line" strings
+        impl_files_str = (
+            ", ".join([f"{path}:{line}" for path, line in req.implementation_files])
+            if req.implementation_files
+            else "-"
+        )
+
+        writer.writerow(
+            [
+                req.id,
+                req.title,
+                req.level,
+                req.status,
+                ", ".join(req.implements) if req.implements else "-",
+                ", ".join(sorted(children)) if children else "-",
+                req.display_filename,
+                req.line_number,
+                impl_files_str,
+            ]
+        )
+
+    return output.getvalue()
+
+
+def generate_planning_csv(
+    requirements: Dict[str, TraceViewRequirement],
+    get_implementation_status: Callable[[str], str],
+    calculate_coverage: Callable[[str], dict],
+) -> str:
+    """Generate CSV for sprint planning (actionable items only).
+
+    Args:
+        requirements: Dict mapping requirement ID to TraceViewRequirement
+        get_implementation_status: Function that takes req_id and returns status string
+        calculate_coverage: Function that takes req_id and returns coverage dict
+
+    Returns:
+        CSV with columns: REQ ID, Title, Level, Status, Impl Status, Coverage, Code Refs
+        Includes only actionable items (Active or Draft status, not deprecated)
+    """
+    output = StringIO()
+    writer = csv.writer(output)
+
+    # Header
+    writer.writerow(
+        ["REQ ID", "Title", "Level", "Status", "Impl Status", "Coverage", "Code Refs"]
+    )
+
+    # Filter to actionable requirements (Active or Draft status)
+    actionable_reqs = [
+        req for req in requirements.values() if req.status in ["Active", "Draft"]
+    ]
+
+    # Sort by ID
+    actionable_reqs.sort(key=lambda r: r.id)
+
+    for req in actionable_reqs:
+        impl_status = get_implementation_status(req.id)
+        coverage = calculate_coverage(req.id)
+        code_refs = len(req.implementation_files)
+
+        writer.writerow(
+            [
+                req.id,
+                req.title,
+                req.level,
+                req.status,
+                impl_status,
+                f"{coverage['traced']}/{coverage['children']}",
+                code_refs,
+            ]
+        )
+
+    return output.getvalue()

elspais/trace_view/generators/markdown.py

@@ -0,0 +1,175 @@
+"""
+elspais.trace_view.generators.markdown - Markdown generation.
+
+Provides functions to generate markdown traceability matrices.
+"""
+
+import sys
+from datetime import datetime
+from typing import Dict, List, Optional
+
+from elspais.trace_view.models import TraceViewRequirement
+from elspais.trace_view.coverage import count_by_level, find_orphaned_requirements
+
+
+def generate_legend_markdown() -> str:
+    """Generate markdown legend section.
+
+    Returns:
+        Markdown string with legend explaining symbols
+    """
+    return """## Legend
+
+**Requirement Status:**
+- Active requirement
+- Draft requirement
+- Deprecated requirement
+
+**Traceability:**
+- Has implementation file(s)
+- No implementation found
+
+**Interactive (HTML only):**
+- Expandable (has child requirements)
+- Collapsed (click to expand)
+"""
+
+
+def generate_markdown(
+    requirements: Dict[str, TraceViewRequirement],
+    base_path: str = "",
+) -> str:
+    """Generate markdown traceability matrix.
+
+    Args:
+        requirements: Dict mapping requirement ID to TraceViewRequirement
+        base_path: Base path for links (e.g., '../' for files in subdirectory)
+
+    Returns:
+        Complete markdown traceability matrix
+    """
+    lines = []
+    lines.append("# Requirements Traceability Matrix")
+    lines.append(f"\n**Generated**: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    lines.append(f"**Total Requirements**: {len(requirements)}\n")
+
+    # Summary by level (using active counts, excluding deprecated)
+    by_level = count_by_level(requirements)
+    lines.append("## Summary\n")
+    lines.append(f"- **PRD Requirements**: {by_level['active']['PRD']}")
+    lines.append(f"- **OPS Requirements**: {by_level['active']['OPS']}")
+    lines.append(f"- **DEV Requirements**: {by_level['active']['DEV']}\n")
+
+    # Add legend
+    lines.append(generate_legend_markdown())
+
+    # Full traceability tree
+    lines.append("## Traceability Tree\n")
+
+    # Start with top-level PRD requirements
+    prd_reqs = [req for req in requirements.values() if req.level == "PRD"]
+    prd_reqs.sort(key=lambda r: r.id)
+
+    for prd_req in prd_reqs:
+        lines.append(
+            format_req_tree_md(
+                prd_req, requirements, indent=0, ancestor_path=[], base_path=base_path
+            )
+        )
+
+    # Orphaned ops/dev requirements
+    orphaned = find_orphaned_requirements(requirements)
+    if orphaned:
+        lines.append("\n## Orphaned Requirements\n")
+        lines.append("*(Requirements not linked from any parent)*\n")
+        for req in orphaned:
+            lines.append(
+                f"- **REQ-{req.id}**: {req.title} ({req.level}) - {req.display_filename}"
+            )
+
+    return "\n".join(lines)
+
+
+def format_req_tree_md(
+    req: TraceViewRequirement,
+    requirements: Dict[str, TraceViewRequirement],
+    indent: int,
+    ancestor_path: Optional[List[str]] = None,
+    base_path: str = "",
+) -> str:
+    """Format requirement and its children as markdown tree.
+
+    Args:
+        req: The requirement to format
+        requirements: Dict mapping requirement ID to TraceViewRequirement
+        indent: Current indentation level
+        ancestor_path: List of requirement IDs in the current traversal path (for cycle detection)
+        base_path: Base path for links
+
+    Returns:
+        Formatted markdown string
+    """
+    if ancestor_path is None:
+        ancestor_path = []
+
+    # Cycle detection: check if this requirement is already in our traversal path
+    if req.id in ancestor_path:
+        cycle_path = ancestor_path + [req.id]
+        cycle_str = " -> ".join([f"REQ-{rid}" for rid in cycle_path])
+        print(f"Warning: CYCLE DETECTED: {cycle_str}", file=sys.stderr)
+        return (
+            "  " * indent
+            + f"- **CYCLE DETECTED**: REQ-{req.id} (path: {cycle_str})"
+        )
+
+    # Safety depth limit
+    MAX_DEPTH = 50
+    if indent > MAX_DEPTH:
+        print(f"Warning: MAX DEPTH ({MAX_DEPTH}) exceeded at REQ-{req.id}", file=sys.stderr)
+        return "  " * indent + f"- **MAX DEPTH EXCEEDED**: REQ-{req.id}"
+
+    lines = []
+    prefix = "  " * indent
+
+    # Format current requirement
+    status_indicator = {
+        "Active": "[Active]",
+        "Draft": "[Draft]",
+        "Deprecated": "[Deprecated]",
+    }
+    indicator = status_indicator.get(req.status, "[?]")
+
+    # Create link to source file with REQ anchor
+    if req.external_spec_path:
+        req_link = f"[REQ-{req.id}](file://{req.external_spec_path}#REQ-{req.id})"
+    else:
+        spec_subpath = "spec/roadmap" if req.is_roadmap else "spec"
+        req_link = f"[REQ-{req.id}]({base_path}{spec_subpath}/{req.file_path.name}#REQ-{req.id})"
+
+    lines.append(
+        f"{prefix}- {indicator} **{req_link}**: {req.title}\n"
+        f"{prefix}  - Level: {req.level} | Status: {req.status}\n"
+        f"{prefix}  - File: {req.display_filename}:{req.line_number}"
+    )
+
+    # Format implementation files as nested list with clickable links
+    if req.implementation_files:
+        lines.append(f"{prefix}  - **Implemented in**:")
+        for file_path, line_num in req.implementation_files:
+            # Create markdown link to file with line number anchor
+            link = f"[{file_path}:{line_num}]({base_path}{file_path}#L{line_num})"
+            lines.append(f"{prefix}    - {link}")
+
+    # Find and format children
+    children = [r for r in requirements.values() if req.id in r.implements]
+    children.sort(key=lambda r: r.id)
+
+    if children:
+        # Add current req to path before recursing into children
+        current_path = ancestor_path + [req.id]
+        for child in children:
+            lines.append(
+                format_req_tree_md(child, requirements, indent + 1, current_path, base_path)
+            )
+
+    return "\n".join(lines)

elspais/trace_view/html/__init__.py

@@ -0,0 +1,31 @@
+# Implements: REQ-int-d00002-B (HTML generation requires jinja2)
+"""
+elspais.trace_view.html - Interactive HTML generation.
+
+Requires: pip install elspais[trace-view]
+"""
+
+def _check_jinja2():
+    try:
+        import jinja2  # noqa: F401
+        return True
+    except ImportError:
+        return False
+
+
+JINJA2_AVAILABLE = _check_jinja2()
+
+if JINJA2_AVAILABLE:
+    from elspais.trace_view.html.generator import HTMLGenerator
+    __all__ = ["HTMLGenerator", "JINJA2_AVAILABLE"]
+else:
+    __all__ = ["JINJA2_AVAILABLE"]
+
+    class HTMLGenerator:
+        """Placeholder when jinja2 is not installed."""
+
+        def __init__(self, *args, **kwargs):
+            raise ImportError(
+                "HTMLGenerator requires Jinja2. "
+                "Install with: pip install elspais[trace-view]"
+            )