opencode-arch 1.0.0__py3-none-any.whl

opencode_arch/cli/confidence.py

@@ -0,0 +1,66 @@
+"""CLI confidence visualization command."""
+from __future__ import annotations
+from pathlib import Path
+
+
+def run_confidence(repo_path: str) -> str:
+    """Run confidence analysis and return formatted output."""
+    root = Path(repo_path)
+    model_file = root / ".architecture-model.yaml"
+    if not model_file.exists():
+        model_file = root / ".architecture-model-extracted.yaml"
+    if not model_file.exists():
+        return "Error: No model found. Run extraction first."
+
+    try:
+        from architecture_model.core.parser import load_model
+        from architecture_model.core.confidence import (
+            compute_model_confidence,
+            aggregate_block_confidence,
+            model_confidence_summary,
+        )
+
+        model = load_model(model_file)
+        compute_model_confidence(model)
+        blocks = aggregate_block_confidence(model)
+        summary = model_confidence_summary(model)
+    except Exception as e:
+        return f"Error computing confidence: {e}"
+
+    lines = []
+    lines.append(f"# Confidence Report: {model.meta.project}")
+    lines.append(f"Overall: {summary['overall']:.0%} | "
+                 f"High (>=80%): {summary['high_confidence']} | "
+                 f"Low (<30%): {summary['low_confidence']} | "
+                 f"Total: {summary['total_entities']}")
+    lines.append("")
+
+    lines.append(f"{'Block':<12} {'Avg':>6} {'Min':>6} {'Max':>6} {'Count':>6}")
+    lines.append("-" * 42)
+    for block_id in sorted(blocks.keys()):
+        b = blocks[block_id]
+        lines.append(f"{block_id:<12} {b['avg_confidence']:>5.0%} {b['min_confidence']:>5.0%} {b['max_confidence']:>5.0%} {b['entity_count']:>6}")
+
+    lines.append("")
+
+    if summary["gaps"]:
+        lines.append("## Top Gaps (lowest confidence)")
+        for gap in summary["gaps"]:
+            lines.append(f"  {gap['id']:<12} {gap['name']:<25} {gap['confidence']:.0%}")
+
+    lines.append("")
+    lines.append("## Entity Detail")
+    for comp in model.entities.components:
+        missing = []
+        if not comp.contract:
+            missing.append("contract")
+        if not comp.pattern:
+            missing.append("pattern")
+        if not comp.signatures:
+            missing.append("signatures")
+        if not comp.test_contracts:
+            missing.append("tests")
+        gaps_str = ", ".join(missing) if missing else "-"
+        lines.append(f"  {comp.id:<12} {comp.name:<25} {comp.confidence:>5.0%}  gaps: {gaps_str}")
+
+    return "\n".join(lines)

opencode_arch/cli/docs.py

@@ -0,0 +1,333 @@
+"""SE Document generation orchestrator."""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+from architecture_model import load_model, generate_manifest
+from architecture_model.core.types import ArchitectureModel
+
+from opencode_arch.artifacts import select_artifacts, assemble_artifact_context, TEMPLATES, get_template, ArtifactSpec, format_capability_detail_context, API_DETAIL_TEMPLATE
+from opencode_arch.runner.base import RunnerBackend, RunResult
+
+
+@dataclass
+class DocsResult:
+    """Result of a docs generation run."""
+    generated: list[str]       # artifact IDs that were generated
+    failed: list[str]          # artifact IDs that failed
+    output_dir: str            # path to output directory
+    time_seconds: float        # total time taken
+    error: str | None = None   # top-level error if whole run failed
+
+
+async def run_docs_generate(
+    repo_path: Path,
+    runner: RunnerBackend,
+    output_dir: Path | None = None,
+    artifact_filter: list[str] | None = None,
+    model_path: Path | None = None,
+) -> DocsResult:
+    """Generate SE documentation for a project.
+
+    Flow:
+    1. Load model from project (or model_path override)
+    2. Generate manifest via generate_manifest()
+    3. Call select_artifacts(model, manifest) to determine what to generate
+    4. If artifact_filter provided, intersect with selected artifacts
+    5. For each artifact:
+       a. Get template from TEMPLATES[artifact_id]
+       b. Assemble context via assemble_artifact_context(template, model, manifest)
+       c. Build full prompt (context + generation instructions)
+       d. Call runner.run(prompt, str(repo_path))
+       e. Write result to output_dir/filename
+    6. Generate index.md linking all artifacts
+    7. Return DocsResult
+    """
+    start_time = time.time()
+    repo_path = Path(repo_path).resolve()
+
+    # Determine output directory
+    if output_dir is None:
+        output_dir = repo_path / "docs" / "se"
+    else:
+        output_dir = Path(output_dir)
+
+    # Step 1: Load model
+    try:
+        if model_path:
+            model = load_model(Path(model_path))
+        else:
+            default_model_path = repo_path / ".architecture-model.yaml"
+            if default_model_path.exists():
+                model = load_model(default_model_path)
+            else:
+                elapsed = time.time() - start_time
+                return DocsResult(
+                    generated=[],
+                    failed=[],
+                    output_dir=str(output_dir),
+                    time_seconds=elapsed,
+                    error="No architecture model found. Run extraction first.",
+                )
+    except Exception as e:
+        elapsed = time.time() - start_time
+        return DocsResult(
+            generated=[],
+            failed=[],
+            output_dir=str(output_dir),
+            time_seconds=elapsed,
+            error=f"Failed to load model: {e}",
+        )
+
+    # Step 2: Generate manifest (best-effort)
+    manifest = None
+    try:
+        manifest = generate_manifest(repo_path)
+    except Exception:
+        pass  # Manifest is optional — select_artifacts handles None
+
+    # Step 3: Select artifacts
+    try:
+        selected = select_artifacts(model, manifest)
+    except Exception as e:
+        elapsed = time.time() - start_time
+        return DocsResult(
+            generated=[],
+            failed=[],
+            output_dir=str(output_dir),
+            time_seconds=elapsed,
+            error=f"Failed to select artifacts: {e}",
+        )
+
+    # Step 4: Filter if requested
+    if artifact_filter:
+        selected = [s for s in selected if s.id in artifact_filter]
+
+    # Ensure output dir exists
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    # Step 5: Generate each artifact
+    generated: list[str] = []
+    failed: list[str] = []
+    generated_artifacts: list[tuple[str, str]] = []  # (artifact_id, filename)
+
+    for spec in selected:
+        # Per-capability API detail artifacts use specialized context
+        if spec.id.startswith("api-detail-"):
+            cap_id = spec.id.replace("api-detail-", "").upper()
+            template = API_DETAIL_TEMPLATE
+            filename = f"api-detail-{cap_id.lower()}.md"
+
+            # Assemble capability-specific context
+            try:
+                cap_context = format_capability_detail_context(cap_id, model, manifest)
+            except Exception:
+                failed.append(spec.id)
+                continue
+
+            # Build prompt with template structure + capability data
+            prompt = _build_capability_detail_prompt(template, cap_context, spec.name)
+
+            # Call runner
+            try:
+                result = await runner.run(prompt, str(repo_path))
+            except Exception:
+                failed.append(spec.id)
+                continue
+
+            if not result.success:
+                failed.append(spec.id)
+                continue
+
+            _write_artifact(output_dir, filename, spec.id, result.output)
+            generated.append(spec.id)
+            generated_artifacts.append((spec.id, filename))
+            continue
+
+        # Standard artifacts
+        template = TEMPLATES.get(spec.id)
+        if template is None:
+            template = get_template(spec.id)
+        if template is None:
+            failed.append(spec.id)
+            continue
+
+        # Assemble context
+        try:
+            context = assemble_artifact_context(template, model, manifest)
+        except Exception:
+            failed.append(spec.id)
+            continue
+
+        # Build prompt
+        prompt = _build_generation_prompt(context, spec.id)
+
+        # Call runner
+        try:
+            result = await runner.run(prompt, str(repo_path))
+        except Exception:
+            failed.append(spec.id)
+            continue
+
+        if not result.success:
+            failed.append(spec.id)
+            continue
+
+        # Write artifact
+        _write_artifact(output_dir, template.filename, spec.id, result.output)
+        generated.append(spec.id)
+        generated_artifacts.append((spec.id, template.filename))
+
+    # Step 6: Write index
+    if generated_artifacts:
+        _write_index(output_dir, generated_artifacts)
+
+    elapsed = time.time() - start_time
+    return DocsResult(
+        generated=generated,
+        failed=failed,
+        output_dir=str(output_dir),
+        time_seconds=elapsed,
+    )
+
+
+async def run_docs_list(
+    repo_path: Path,
+    model_path: Path | None = None,
+) -> list[dict[str, str]]:
+    """List which artifacts would be generated for a project.
+
+    Returns list of dicts: [{"id": ..., "name": ..., "category": ..., "priority": ...}]
+    No runner needed — just model analysis.
+    """
+    repo_path = Path(repo_path).resolve()
+
+    # Load model
+    if model_path:
+        model = load_model(Path(model_path))
+    else:
+        default_model_path = repo_path / ".architecture-model.yaml"
+        model = load_model(default_model_path)
+
+    # Generate manifest (best-effort)
+    manifest = None
+    try:
+        manifest = generate_manifest(repo_path)
+    except Exception:
+        pass
+
+    # Select artifacts
+    selected = select_artifacts(model, manifest)
+
+    return [
+        {
+            "id": spec.id,
+            "name": spec.name,
+            "category": spec.category,
+            "priority": str(spec.priority),
+        }
+        for spec in selected
+    ]
+
+
+def _build_generation_prompt(context: str, template_artifact_id: str) -> str:
+    """Build the full prompt sent to the agent.
+
+    Format includes context from assemble_artifact_context followed by
+    task instructions for the agent.
+    """
+    return (
+        f"---\n"
+        f"{context}\n"
+        f"\n"
+        f"---\n"
+        f"TASK: Generate the '{template_artifact_id}' documentation artifact.\n"
+        f"\n"
+        f"Write a complete, well-structured markdown document. Use the DATA sections above\n"
+        f"as your source of truth. Do NOT invent information not present in the data.\n"
+        f"\n"
+        f"Output ONLY the markdown content, no code fences or explanations.\n"
+        f"---\n"
+    )
+
+
+def _build_capability_detail_prompt(template, cap_context: str, cap_name: str) -> str:
+    """Build the prompt for a per-capability API detail artifact.
+
+    Uses the API_DETAIL_TEMPLATE sections as instructions, with the
+    capability-specific context as the grounding data.
+    """
+    sections_instructions = "\n".join(
+        f"  {s.heading}: {s.instructions}"
+        for s in template.sections
+    )
+
+    return (
+        f"---\n"
+        f"SYSTEM: {template.system_prompt}\n"
+        f"\n"
+        f"## Architecture Model Data for: {cap_name}\n\n"
+        f"{cap_context}\n"
+        f"\n"
+        f"---\n"
+        f"TASK: Generate a detailed API documentation file for this capability.\n"
+        f"\n"
+        f"Required sections:\n"
+        f"{sections_instructions}\n"
+        f"\n"
+        f"Write a complete, well-structured markdown document. Use the DATA above\n"
+        f"as your source of truth. Include exact function signatures, parameters,\n"
+        f"return types, algorithm steps, and behavioral sequences.\n"
+        f"Do NOT invent information not present in the data.\n"
+        f"\n"
+        f"Output ONLY the markdown content, no code fences or explanations.\n"
+        f"---\n"
+    )
+
+
+def _write_artifact(output_dir: Path, filename: str, artifact_id: str, content: str):
+    """Write generated artifact with frontmatter.
+
+    Prepends YAML frontmatter with artifact_id, timestamp, and generator.
+    """
+    timestamp = datetime.now(timezone.utc).isoformat()
+    frontmatter = (
+        f"---\n"
+        f"artifact_id: {artifact_id}\n"
+        f"generated_at: {timestamp}\n"
+        f"generator: opencode-arch-docs\n"
+        f"---\n"
+    )
+    filepath = output_dir / filename
+    filepath.write_text(frontmatter + content)
+
+
+def _write_index(output_dir: Path, generated_artifacts: list[tuple[str, str]]):
+    """Write index.md linking all generated artifacts.
+
+    generated_artifacts: list of (artifact_id, filename) tuples
+    """
+    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S UTC")
+
+    lines = [
+        "# SE Documentation Index",
+        "",
+        f"Generated: {timestamp}",
+        "",
+        "## Artifacts",
+        "",
+        "| Artifact | File | Category |",
+        "|----------|------|----------|",
+    ]
+
+    for artifact_id, filename in generated_artifacts:
+        # Use artifact_id as the display name
+        name = artifact_id.replace("-", " ").title()
+        lines.append(f"| {name} | [{filename}](./{filename}) | {artifact_id} |")
+
+    lines.append("")
+    index_path = output_dir / "index.md"
+    index_path.write_text("\n".join(lines))

opencode_arch/cli/docs_validator.py

@@ -0,0 +1,295 @@
+"""Validate generated SE documentation against model and manifest."""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from architecture_model.core.types import ArchitectureModel
+
+
+@dataclass
+class ValidationIssue:
+    """A single validation issue found in a doc artifact."""
+    artifact_id: str       # which artifact had the issue
+    line: int              # line number in the doc (1-indexed, 0 if unknown)
+    issue_type: str        # "invalid_path", "unknown_function", "unknown_component", "stale_reference"
+    message: str           # human-readable description
+    severity: str          # "error" or "warning"
+
+
+@dataclass
+class DocsValidationResult:
+    """Aggregate validation result for all docs."""
+    total_artifacts: int
+    passed: int
+    failed: int
+    issues: list[ValidationIssue] = field(default_factory=list)
+
+    @property
+    def is_valid(self) -> bool:
+        """No errors (warnings are OK)."""
+        return not any(i.severity == "error" for i in self.issues)
+
+
+# File extensions we recognize as code/config paths
+_PATH_EXTENSIONS = (
+    ".py", ".ts", ".js", ".jsx", ".tsx",
+    ".yaml", ".yml", ".json", ".toml",
+    ".cfg", ".ini", ".md", ".rst",
+    ".sh", ".bash", ".sql",
+)
+
+# Regex for backtick-wrapped file paths: must contain a slash or end with known extension
+_FILE_REF_PATTERN = re.compile(
+    r"`([^`\s]+(?:" + "|".join(re.escape(ext) for ext in _PATH_EXTENSIONS) + r"))`"
+)
+
+# Regex for backtick-wrapped function calls: word followed by ()
+_FUNC_REF_PATTERN = re.compile(r"`(\w+)\(\)`")
+
+# Regex for backtick-wrapped PascalCase class names: starts uppercase, has at least one lowercase
+_CLASS_REF_PATTERN = re.compile(r"`([A-Z][a-zA-Z0-9]*)`")
+
+# Regex for component-like IDs (e.g., COMP-1, SVC-1, IF-1, CAP-1)
+_COMPONENT_ID_PATTERN = re.compile(r"\b([A-Z]{2,}-\d+)\b")
+
+
+def validate_docs(
+    docs_dir: Path,
+    model: "ArchitectureModel",
+    manifest: dict | None = None,
+) -> DocsValidationResult:
+    """Validate all markdown files in docs_dir against model and manifest.
+
+    Checks:
+    1. File paths mentioned in docs exist in manifest's file inventory
+    2. Function/class names referenced exist in manifest's AST data
+    3. Component IDs/names referenced match model's components
+    4. Interface names referenced match model's interfaces
+
+    An artifact PASSES if it has no "error" severity issues.
+    """
+    docs_dir = Path(docs_dir)
+    md_files = sorted(docs_dir.glob("*.md"))
+
+    if not md_files:
+        return DocsValidationResult(total_artifacts=0, passed=0, failed=0)
+
+    # Build lookup sets
+    manifest_files = _get_manifest_files(manifest)
+    manifest_symbols = _get_manifest_symbols(manifest)
+    model_ids = _get_model_entity_ids(model)
+
+    all_issues: list[ValidationIssue] = []
+    passed = 0
+    failed = 0
+
+    for md_file in md_files:
+        content = md_file.read_text()
+        artifact_id = _get_artifact_id_from_file(md_file)
+        artifact_issues: list[ValidationIssue] = []
+
+        # Check 1: File path references (only if manifest available)
+        if manifest is not None:
+            file_refs = _extract_file_references(content)
+            for line_no, path_ref in file_refs:
+                if path_ref not in manifest_files:
+                    artifact_issues.append(ValidationIssue(
+                        artifact_id=artifact_id,
+                        line=line_no,
+                        issue_type="invalid_path",
+                        message=f"File path '{path_ref}' not found in manifest",
+                        severity="error",
+                    ))
+
+        # Check 2: Function/class references (only if manifest available)
+        if manifest is not None:
+            code_refs = _extract_code_references(content)
+            for line_no, name_ref in code_refs:
+                if name_ref not in manifest_symbols:
+                    artifact_issues.append(ValidationIssue(
+                        artifact_id=artifact_id,
+                        line=line_no,
+                        issue_type="unknown_function",
+                        message=f"Symbol '{name_ref}' not found in manifest",
+                        severity="warning",
+                    ))
+
+        # Check 3: Component/entity ID references (always check against model)
+        comp_refs = _extract_component_references(content, model)
+        for line_no, comp_ref in comp_refs:
+            if comp_ref not in model_ids:
+                artifact_issues.append(ValidationIssue(
+                    artifact_id=artifact_id,
+                    line=line_no,
+                    issue_type="unknown_component",
+                    message=f"Entity ID '{comp_ref}' not found in model",
+                    severity="error",
+                ))
+
+        all_issues.extend(artifact_issues)
+
+        # Artifact passes if no errors
+        has_errors = any(i.severity == "error" for i in artifact_issues)
+        if has_errors:
+            failed += 1
+        else:
+            passed += 1
+
+    return DocsValidationResult(
+        total_artifacts=len(md_files),
+        passed=passed,
+        failed=failed,
+        issues=all_issues,
+    )
+
+
+def _extract_file_references(content: str) -> list[tuple[int, str]]:
+    """Extract file path references from markdown content.
+
+    Looks for patterns like:
+    - `src/foo/bar.py` (backtick-wrapped paths ending in known extensions)
+    - References to .py, .ts, .js, .yaml, .json, .toml files
+
+    Returns: list of (line_number, path_string)
+    """
+    results = []
+    for line_no, line in enumerate(content.splitlines(), start=1):
+        for match in _FILE_REF_PATTERN.finditer(line):
+            results.append((line_no, match.group(1)))
+    return results
+
+
+def _extract_code_references(content: str) -> list[tuple[int, str]]:
+    """Extract function/class name references from markdown.
+
+    Looks for patterns like:
+    - `function_name()` (backtick-wrapped with parens)
+    - `ClassName` (backtick-wrapped PascalCase)
+
+    Returns: list of (line_number, name_string)
+    """
+    results = []
+    seen_on_line: dict[int, set[str]] = {}
+
+    for line_no, line in enumerate(content.splitlines(), start=1):
+        seen_on_line[line_no] = set()
+
+        # Extract function calls: `name()`
+        for match in _FUNC_REF_PATTERN.finditer(line):
+            name = match.group(1)
+            if name not in seen_on_line[line_no]:
+                results.append((line_no, name))
+                seen_on_line[line_no].add(name)
+
+        # Extract PascalCase class names: `ClassName`
+        for match in _CLASS_REF_PATTERN.finditer(line):
+            name = match.group(1)
+            # Skip if it looks like a file path (already caught by file refs)
+            if "." in name or "/" in name:
+                continue
+            # Must have at least one lowercase letter to be PascalCase
+            if not any(c.islower() for c in name):
+                # All-caps short names (2-3 chars like CLI) are still valid class names
+                if len(name) <= 4:
+                    if name not in seen_on_line[line_no]:
+                        results.append((line_no, name))
+                        seen_on_line[line_no].add(name)
+                continue
+            if name not in seen_on_line[line_no]:
+                results.append((line_no, name))
+                seen_on_line[line_no].add(name)
+
+    return results
+
+
+def _extract_component_references(content: str, model: "ArchitectureModel") -> list[tuple[int, str]]:
+    """Extract component ID/name references that should match the model.
+
+    Looks for known component ID patterns (e.g., COMP-1, SVC-1, IF-1) in text.
+    Returns: list of (line_number, component_ref)
+    """
+    results = []
+    for line_no, line in enumerate(content.splitlines(), start=1):
+        for match in _COMPONENT_ID_PATTERN.finditer(line):
+            results.append((line_no, match.group(1)))
+    return results
+
+
+def _get_manifest_files(manifest: dict | None) -> set[str]:
+    """Get the set of all file paths from manifest.
+
+    Checks manifest["modules"] -> each module has "file" key
+    Also checks manifest.get("files", [])
+    Returns normalized relative paths.
+    """
+    if manifest is None:
+        return set()
+
+    files: set[str] = set()
+
+    # From modules
+    for module in manifest.get("modules", []):
+        if "file" in module:
+            files.add(module["file"])
+
+    # From top-level files list
+    for f in manifest.get("files", []):
+        files.add(f)
+
+    return files
+
+
+def _get_manifest_symbols(manifest: dict | None) -> set[str]:
+    """Get all function/class names from manifest AST data.
+
+    Checks manifest["modules"] -> each module may have "functions", "classes" keys
+    Returns set of symbol names.
+    """
+    if manifest is None:
+        return set()
+
+    symbols: set[str] = set()
+
+    for module in manifest.get("modules", []):
+        for func in module.get("functions", []):
+            symbols.add(func)
+        for cls in module.get("classes", []):
+            symbols.add(cls)
+
+    return symbols
+
+
+def _get_model_entity_ids(model: "ArchitectureModel") -> set[str]:
+    """Get all entity IDs from the architecture model."""
+    return model.all_entity_ids
+
+
+def _get_artifact_id_from_file(filepath: Path) -> str:
+    """Extract artifact_id from file frontmatter or filename.
+
+    Tries to read YAML frontmatter first:
+    ---
+    artifact_id: system-overview
+    ---
+
+    Falls back to: filename without extension (e.g., "system-overview.md" -> "system-overview")
+    """
+    try:
+        content = filepath.read_text()
+        if content.startswith("---\n"):
+            # Try to parse frontmatter
+            parts = content.split("---\n", 2)
+            if len(parts) >= 3:
+                import yaml
+                frontmatter = yaml.safe_load(parts[1])
+                if isinstance(frontmatter, dict) and "artifact_id" in frontmatter:
+                    return frontmatter["artifact_id"]
+    except Exception:
+        pass
+
+    # Fallback to filename without extension
+    return filepath.stem