ref-agents 1.0.0__py3-none-any.whl

ref_agents/tools/dependency_graph.py

@@ -0,0 +1,272 @@
+"""Dependency Graph Generator for REF Agents.
+
+Scans REQ.md files, extracts depends_on/blocks fields,
+and generates Mermaid diagrams + JSON for sequencing engine.
+"""
+
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import structlog
+
+logger = structlog.get_logger(__name__)
+
+# Regex patterns for REQ.md parsing
+STORY_ID_PATTERN = re.compile(r"#\s*Requirement:\s*\[([A-Z]+-\d+)\]")
+STATUS_PATTERN = re.compile(r"\*\*Status:\*\*\s*(\w+(?:\s+\w+)?)")
+DEPENDS_ON_PATTERN = re.compile(r"\|\s*Depends On\s*\|\s*([A-Z]+-\d+)\s*\|")
+BLOCKS_PATTERN = re.compile(r"\|\s*Blocks\s*\|\s*([A-Z]+-\d+)\s*\|")
+
+
+@dataclass
+class StoryNode:
+    """Represents a story in the dependency graph."""
+
+    story_id: str
+    status: str = "Draft"
+    depends_on: list[str] = field(default_factory=list)
+    blocks: list[str] = field(default_factory=list)
+    file_path: str = ""
+
+    def to_dict(self) -> dict[str, str | list[str]]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "story_id": self.story_id,
+            "status": self.status,
+            "depends_on": self.depends_on,
+            "blocks": self.blocks,
+            "file_path": self.file_path,
+        }
+
+
+@dataclass
+class DependencyGraph:
+    """Dependency graph containing all story nodes."""
+
+    nodes: dict[str, StoryNode] = field(default_factory=dict)
+    errors: list[str] = field(default_factory=list)
+
+    def add_node(self, node: StoryNode) -> None:
+        """Add a story node to the graph."""
+        self.nodes[node.story_id] = node
+
+    def get_node(self, story_id: str) -> StoryNode | None:
+        """Get a node by story ID."""
+        return self.nodes.get(story_id)
+
+    def to_json(self) -> str:
+        """Serialize graph to JSON."""
+        data = {
+            "nodes": {sid: node.to_dict() for sid, node in self.nodes.items()},
+            "edges": self._get_edges(),
+        }
+        return json.dumps(data, indent=2)
+
+    def _get_edges(self) -> list[dict[str, str]]:
+        """Extract all dependency edges."""
+        edges = []
+        for node in self.nodes.values():
+            for dep in node.depends_on:
+                edges.append({"from": dep, "to": node.story_id, "type": "depends_on"})
+            for blocked in node.blocks:
+                edges.append({"from": node.story_id, "to": blocked, "type": "blocks"})
+        return edges
+
+    def to_mermaid(self) -> str:
+        """Generate Mermaid diagram."""
+        lines = ["graph LR"]
+
+        for node in self.nodes.values():
+            style = _get_status_style(node.status)
+            lines.append(f"    {node.story_id}{style}")
+
+        for node in self.nodes.values():
+            for dep in node.depends_on:
+                if dep in self.nodes:
+                    lines.append(f"    {dep} --> {node.story_id}")
+
+        return "\n".join(lines)
+
+
+def _get_status_style(status: str) -> str:
+    """Get Mermaid node style based on status."""
+    status_lower = status.lower()
+    if status_lower == "done":
+        return ":::done"
+    if status_lower in ("in progress", "in development"):
+        return ":::inprogress"
+    if status_lower == "blocked":
+        return ":::blocked"
+    return ""
+
+
+def parse_req_file(file_path: Path) -> StoryNode | None:
+    """Parse a REQ.md file and extract story metadata.
+
+    Args:
+        file_path: Path to REQ.md file.
+
+    Returns:
+        StoryNode if valid, None if parsing fails.
+    """
+    try:
+        content = file_path.read_text(encoding="utf-8")
+    except OSError as e:
+        logger.warning("req_file_read_error", file=str(file_path), error=str(e))
+        return None
+
+    # Extract story ID
+    story_match = STORY_ID_PATTERN.search(content)
+    if not story_match:
+        logger.warning(
+            "no_story_id_found",
+            file=str(file_path),
+            expected_format="# Requirement: [STORY-001] Title",
+        )
+        return None
+
+    story_id = story_match.group(1)
+
+    # Extract status
+    status_match = STATUS_PATTERN.search(content)
+    status = status_match.group(1) if status_match else "Draft"
+
+    # Extract dependencies
+    depends_on = DEPENDS_ON_PATTERN.findall(content)
+    blocks = BLOCKS_PATTERN.findall(content)
+
+    return StoryNode(
+        story_id=story_id,
+        status=status,
+        depends_on=depends_on,
+        blocks=blocks,
+        file_path=str(file_path),
+    )
+
+
+def scan_requirements_directory(directory: str | Path) -> DependencyGraph:
+    """Scan directory for REQ.md files and build dependency graph.
+
+    Args:
+        directory: Path to requirements directory.
+
+    Returns:
+        DependencyGraph with all stories and dependencies.
+    """
+    graph = DependencyGraph()
+    dir_path = Path(directory)
+
+    if not dir_path.exists():
+        graph.errors.append(f"Directory not found: {directory}")
+        return graph
+
+    # Find all requirement files: REQ-*.md, req-*.md, STORY-*.md, EPIC-*.md
+    req_files = (
+        list(dir_path.rglob("*REQ*.md"))
+        + list(dir_path.rglob("*req*.md"))
+        + list(dir_path.rglob("STORY-*.md"))
+        + list(dir_path.rglob("EPIC-*.md"))
+    )
+    req_files = list(set(req_files))  # Deduplicate
+
+    for req_file in req_files:
+        node = parse_req_file(req_file)
+        if node:
+            graph.add_node(node)
+        else:
+            graph.errors.append(
+                f"Skipped {req_file.name} — no story ID found. "
+                f"Expected heading: `# Requirement: [STORY-001] Title`"
+            )
+
+    logger.info(
+        "dependency_scan_complete",
+        files_scanned=len(req_files),
+        stories_found=len(graph.nodes),
+    )
+
+    return graph
+
+
+def generate_dependency_graph(directory: str) -> str:
+    """Generate dependency graph artifact.
+
+    Args:
+        directory: Path to requirements directory.
+
+    Returns:
+        Status message with artifact location.
+    """
+    graph = scan_requirements_directory(directory)
+
+    # Fatal errors (e.g. directory not found) block output
+    fatal_errors = [e for e in graph.errors if e.startswith("Directory not found")]
+    if fatal_errors:
+        return f"Errors during scan: {fatal_errors}"
+
+    if not graph.nodes:
+        parse_hints = [e for e in graph.errors if "Skipped" in e]
+        hint_block = "\n".join(f"  • {h}" for h in parse_hints)
+        return (
+            f"No parseable story files found in {directory}.\n\n"
+            f"Expected file format:\n"
+            f"  # Requirement: [STORY-001] Title\n"
+            f"  **Status:** Ready\n"
+            f"  ## User Story\n"
+            f"  As a user...\n"
+            f"  ## Acceptance Criteria\n"
+            f"  1. Given...\n\n"
+            + (
+                f"Files found but skipped:\n{hint_block}"
+                if hint_block
+                else "No .md files found."
+            )
+        )
+
+    # Generate Mermaid markdown
+    mermaid_content = f"""# Dependency Graph
+
+*Auto-generated by dependency_graph.py*
+
+## Story Dependencies
+
+```mermaid
+{graph.to_mermaid()}
+```
+
+## Style Legend
+
+- Default: Draft/Pending
+- `:::done`: Completed
+- `:::inprogress`: In Progress
+- `:::blocked`: Blocked
+
+## Raw Data
+
+```json
+{graph.to_json()}
+```
+"""
+
+    # Write artifact
+    output_path = Path(directory) / "DEPENDENCY_GRAPH.md"
+    try:
+        output_path.write_text(mermaid_content, encoding="utf-8")
+        return f"Generated: `{output_path}` ({len(graph.nodes)} stories)"
+    except OSError as e:
+        return f"Failed to write artifact: {e}"
+
+
+def get_graph_json(directory: str) -> str:
+    """Get dependency graph as JSON for sequencing engine.
+
+    Args:
+        directory: Path to requirements directory.
+
+    Returns:
+        JSON string with graph data.
+    """
+    graph = scan_requirements_directory(directory)
+    return graph.to_json()

ref_agents/tools/discovery_audit.py

@@ -0,0 +1,372 @@
+"""REF Discovery Audit Tool.
+
+Post-completion verification for discovery artifacts.
+Checks existence, placement, and content compliance.
+
+Usage:
+    from ref_agents.tools.discovery_audit import audit_discovery
+    result = audit_discovery("/path/to/project")
+"""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import structlog
+
+from ref_agents.tool_names import TOOL_SCAN_HEALTH
+
+logger = structlog.get_logger(__name__)
+
+
+@dataclass
+class AuditCheck:
+    """Single audit check result."""
+
+    name: str
+    passed: bool
+    message: str
+
+
+@dataclass
+class AuditResult:
+    """Complete audit result."""
+
+    status: str  # "PASS" or "FAIL"
+    checks: list[AuditCheck] = field(default_factory=list)
+    remediation: list[str] = field(default_factory=list)
+
+    @property
+    def passed_count(self) -> int:
+        return sum(1 for c in self.checks if c.passed)
+
+    @property
+    def failed_count(self) -> int:
+        return sum(1 for c in self.checks if not c.passed)
+
+
+def _check_artifact_existence(root: Path) -> list[AuditCheck]:
+    """Check required artifacts exist.
+
+    Args:
+        root: Project root directory.
+
+    Returns:
+        List of audit checks.
+    """
+    checks: list[AuditCheck] = []
+
+    required = {
+        "codemap/CODE_MAP.md": "Root codemap meta-map",
+        "FEATURES.md": "Features manifest",
+        "AGENTS.md": "AI protocol file",
+        "docs/ARCHITECTURE.md": "Architecture documentation",
+        "docs/EXTERNAL_DEPS.md": "External dependencies",
+        "docs/TECH_DEBT.md": "Technical debt registry",
+        "ref-reports/context_graph.json": "Context graph for dashboard",
+    }
+
+    for path, desc in required.items():
+        full_path = root / path
+        exists = full_path.exists()
+        checks.append(
+            AuditCheck(
+                name=f"artifact_{path.replace('/', '_')}",
+                passed=exists,
+                message=f"{desc}: {'✅ Found' if exists else '❌ Missing'}",
+            )
+        )
+
+    # Check codemap has package maps
+    codemap_dir = root / "codemap"
+    if codemap_dir.exists():
+        package_maps = list(codemap_dir.glob("*.md"))
+        # Exclude meta-map
+        package_maps = [p for p in package_maps if p.name != "CODE_MAP.md"]
+        has_package_maps = len(package_maps) > 0
+        checks.append(
+            AuditCheck(
+                name="codemap_package_maps",
+                passed=has_package_maps,
+                message=f"Package codemaps: {'✅ ' + str(len(package_maps)) + ' found' if has_package_maps else '❌ None found'}",
+            )
+        )
+
+    return checks
+
+
+def _check_placement_validation(root: Path) -> list[AuditCheck]:
+    """Check artifacts are in correct locations.
+
+    Args:
+        root: Project root directory.
+
+    Returns:
+        List of audit checks.
+    """
+    checks: list[AuditCheck] = []
+
+    # Should NOT be at root
+    misplaced_at_root = [
+        ("ARCHITECTURE.md", "docs/ARCHITECTURE.md"),
+        ("EXTERNAL_DEPS.md", "docs/EXTERNAL_DEPS.md"),
+        ("EXTERNAL_APIS.md", "docs/EXTERNAL_DEPS.md"),
+    ]
+
+    for src, expected in misplaced_at_root:
+        src_path = root / src
+        if src_path.exists():
+            checks.append(
+                AuditCheck(
+                    name=f"misplaced_{src}",
+                    passed=False,
+                    message=f"⚠️ `{src}` at root should be at `{expected}`",
+                )
+            )
+
+    # Should NOT have unknown/ directory
+    unknown_dir = root / "ref-reports" / "unknown"
+    if unknown_dir.exists():
+        checks.append(
+            AuditCheck(
+                name="unknown_directory",
+                passed=False,
+                message="❌ `ref-reports/unknown/` exists - indicates agent routing issue",
+            )
+        )
+    else:
+        checks.append(
+            AuditCheck(
+                name="unknown_directory",
+                passed=True,
+                message="✅ No `unknown/` directory in ref-reports",
+            )
+        )
+
+    # CODE_MAP.md should NOT be scattered in source dirs
+    scattered_codemaps: list[Path] = []
+    for codemap in root.rglob("CODE_MAP.md"):
+        # Skip if in codemap/ directory
+        if "codemap" in codemap.parts:
+            continue
+        # Skip if in docs/
+        if "docs" in codemap.parts:
+            continue
+        # This is a scattered codemap
+        scattered_codemaps.append(codemap)
+
+    if scattered_codemaps:
+        checks.append(
+            AuditCheck(
+                name="scattered_codemaps",
+                passed=False,
+                message=f"⚠️ Found {len(scattered_codemaps)} CODE_MAP.md in source dirs (should be in codemap/)",
+            )
+        )
+
+    return checks
+
+
+def _check_content_validation(root: Path) -> list[AuditCheck]:
+    """Check artifact content meets requirements.
+
+    Args:
+        root: Project root directory.
+
+    Returns:
+        List of audit checks.
+    """
+    checks: list[AuditCheck] = []
+
+    # AGENTS.md must contain fix workflow
+    agents_path = root / "AGENTS.md"
+    if agents_path.exists():
+        content = agents_path.read_text(encoding="utf-8")
+        has_workflow = "forensic_engineer" in content and "strategist" in content
+        checks.append(
+            AuditCheck(
+                name="agents_fix_workflow",
+                passed=has_workflow,
+                message=f"AGENTS.md fix workflow: {'✅ Present' if has_workflow else '❌ Missing mandatory workflow'}",
+            )
+        )
+
+    # FEATURES.md must have at least 1 feature
+    features_path = root / "FEATURES.md"
+    if features_path.exists():
+        content = features_path.read_text(encoding="utf-8")
+        has_features = "|" in content and "Feature" in content
+        checks.append(
+            AuditCheck(
+                name="features_content",
+                passed=has_features,
+                message=f"FEATURES.md content: {'✅ Has features' if has_features else '❌ No features listed'}",
+            )
+        )
+
+    # Codemaps must have Purpose section
+    codemap_dir = root / "codemap"
+    if codemap_dir.exists():
+        package_maps = [p for p in codemap_dir.glob("*.md") if p.name != "CODE_MAP.md"]
+        if package_maps:
+            sample = package_maps[0]
+            content = sample.read_text(encoding="utf-8")
+            has_purpose = "## Purpose" in content
+            checks.append(
+                AuditCheck(
+                    name="codemap_purpose_section",
+                    passed=has_purpose,
+                    message=f"Codemap purpose sections: {'✅ Present' if has_purpose else '❌ Missing'}",
+                )
+            )
+
+    return checks
+
+
+def _generate_remediation(result: AuditResult, root: Path) -> list[str]:
+    """Generate remediation steps for failed checks.
+
+    Args:
+        result: Audit result with checks.
+        root: Project root.
+
+    Returns:
+        List of remediation commands/steps.
+    """
+    remediation: list[str] = []
+
+    for check in result.checks:
+        if check.passed:
+            continue
+
+        if "codemap" in check.name and "Missing" in check.message:
+            remediation.append("Run: generate_codemaps()")
+
+        if "FEATURES" in check.message and "Missing" in check.message:
+            remediation.append("Run: generate_features_file()")
+
+        if "AGENTS" in check.message and "Missing" in check.message:
+            remediation.append("Run: generate_agents_file()")
+
+        if "TECH_DEBT" in check.message:
+            remediation.append(
+                f"Run: {TOOL_SCAN_HEALTH.format(directory='.')} to generate docs/TECH_DEBT.md"
+            )
+
+        if "context_graph" in check.name:
+            remediation.append("Run: populate_context_graph()")
+
+        if "misplaced" in check.name:
+            remediation.append(
+                f"Run: {TOOL_SCAN_HEALTH.format(directory='.')} to relocate artifacts"
+            )
+
+        if "unknown_directory" in check.name and not check.passed:
+            remediation.append("Delete ref-reports/unknown/ and re-run scans")
+
+    return list(set(remediation))  # Dedupe
+
+
+def _check_migration_artifacts(root: Path) -> list[AuditCheck]:
+    """Check migration-specific artifacts exist when migration mode is active.
+
+    Args:
+        root: Project root directory.
+
+    Returns:
+        List of audit checks for migration artifacts.
+    """
+    checks: list[AuditCheck] = []
+
+    md_path = root / "docs" / "MIGRATION_MAP.md"
+    md_exists = md_path.exists() and md_path.stat().st_size > 0
+    checks.append(
+        AuditCheck(
+            name="migration_map_md",
+            passed=md_exists,
+            message=f"docs/MIGRATION_MAP.md: {'✅ Found' if md_exists else '❌ Missing — required in migration mode'}",
+        )
+    )
+
+    json_path = root / "ref-reports" / "migration_map.json"
+    json_exists = False
+    if json_path.exists() and json_path.stat().st_size > 0:
+        try:
+            import json as _json
+
+            _json.loads(json_path.read_text(encoding="utf-8"))
+            json_exists = True
+        except (ValueError, OSError):
+            json_exists = False
+    checks.append(
+        AuditCheck(
+            name="migration_map_json",
+            passed=json_exists,
+            message=f"ref-reports/migration_map.json: {'✅ Found and valid' if json_exists else '❌ Missing or invalid — required in migration mode'}",
+        )
+    )
+
+    return checks
+
+
+def audit_discovery(directory: str) -> str:
+    """Audit discovery artifacts for completeness and compliance.
+
+    Checks:
+    - Artifact existence (codemap/, FEATURES.md, AGENTS.md, etc.)
+    - Placement validation (no misplaced files, no unknown/)
+    - Content validation (required sections present)
+    - Migration artifacts (MIGRATION_MAP.md + migration_map.json) when migration mode active
+
+    Args:
+        directory: Path to project root.
+
+    Returns:
+        Status message with audit results.
+    """
+    root = Path(directory)
+
+    if not root.exists():
+        return f"Error: Directory {directory} does not exist."
+
+    result = AuditResult(status="PASS")
+
+    # Run all checks
+    result.checks.extend(_check_artifact_existence(root))
+    result.checks.extend(_check_placement_validation(root))
+    result.checks.extend(_check_content_validation(root))
+
+    # Migration artifact gate — only when migration mode active
+    from ref_agents.session import SessionManager
+
+    if SessionManager.get().is_migration_mode():
+        result.checks.extend(_check_migration_artifacts(root))
+
+    # Determine overall status
+    if result.failed_count > 0:
+        result.status = "FAIL"
+        result.remediation = _generate_remediation(result, root)
+
+    # Format output
+    status_icon = "✅" if result.status == "PASS" else "❌"
+    output = f"{status_icon} **Discovery Audit: {result.status}**\n\n"
+    output += (
+        f"**Passed:** {result.passed_count} | **Failed:** {result.failed_count}\n\n"
+    )
+
+    output += "## Check Results\n\n"
+    for check in result.checks:
+        output += f"- {check.message}\n"
+
+    if result.remediation:
+        output += "\n## Remediation Steps\n\n"
+        for step in result.remediation:
+            output += f"1. {step}\n"
+
+    logger.info(
+        "discovery_audit_complete",
+        status=result.status,
+        passed=result.passed_count,
+        failed=result.failed_count,
+    )
+
+    return output