opencode-arch 1.0.0__py3-none-any.whl

opencode_arch/artifacts/templates.py

@@ -0,0 +1,444 @@
+"""Artifact template definitions.
+
+Each template describes HOW to generate a specific SE documentation artifact:
+- What sections it has
+- What model/manifest data feeds each section
+- What instructions the LLM follows for each section
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class TemplateSection:
+    """A single section within an artifact template."""
+
+    heading: str  # e.g. "## Overview", "## Endpoints"
+    source: str  # which model/manifest data feeds this section
+    instructions: str  # LLM instructions for generating this section content
+
+
+@dataclass
+class ArtifactTemplate:
+    """Full template for generating one artifact."""
+
+    artifact_id: str  # matches ArtifactSpec.id from selector.py
+    filename: str  # output filename, e.g. "api-reference.md"
+    sections: list[TemplateSection]
+    system_prompt: str  # role/context prompt for the LLM
+
+
+# ---------------------------------------------------------------------------
+# Template Definitions — one per artifact in ARTIFACT_REGISTRY
+# ---------------------------------------------------------------------------
+
+TEMPLATES: dict[str, ArtifactTemplate] = {
+    "system-overview": ArtifactTemplate(
+        artifact_id="system-overview",
+        filename="system-overview.md",
+        system_prompt=(
+            "You are a technical writer documenting a software system's architecture. "
+            "Write clear, precise documentation based on the provided architecture model data."
+        ),
+        sections=[
+            TemplateSection(
+                heading="## System Purpose",
+                source="meta",
+                instructions=(
+                    "Describe what this system does based on the project metadata. "
+                    "State the project name and its primary purpose."
+                ),
+            ),
+            TemplateSection(
+                heading="## Architecture Overview",
+                source="layers",
+                instructions=(
+                    "Describe the high-level architecture using the layer structure. "
+                    "If no layers, describe based on component organization."
+                ),
+            ),
+            TemplateSection(
+                heading="## Key Components",
+                source="components",
+                instructions=(
+                    "List and briefly describe each major component, its role, "
+                    "and technology."
+                ),
+            ),
+            TemplateSection(
+                heading="## Key Relationships",
+                source="relationships",
+                instructions=(
+                    "Describe how components interact, using the relationship data."
+                ),
+            ),
+        ],
+    ),
+    "component-catalog": ArtifactTemplate(
+        artifact_id="component-catalog",
+        filename="component-catalog.md",
+        system_prompt=(
+            "You are a technical writer creating a component reference catalog. "
+            "Be precise and include all components with their details."
+        ),
+        sections=[
+            TemplateSection(
+                heading="## Components",
+                source="components",
+                instructions=(
+                    "For each component, document: name, kind, layer, status, files, "
+                    "and responsibilities. Use a consistent format."
+                ),
+            ),
+            TemplateSection(
+                heading="## Component Dependencies",
+                source="relationships",
+                instructions=(
+                    "Document depends-on relationships between components "
+                    "as a dependency list."
+                ),
+            ),
+        ],
+    ),
+    "api-reference": ArtifactTemplate(
+        artifact_id="api-reference",
+        filename="api-reference.md",
+        system_prompt=(
+            "You are a technical writer creating API documentation. "
+            "Focus on precision — exact endpoint paths, methods, data formats."
+        ),
+        sections=[
+            TemplateSection(
+                heading="## Interfaces",
+                source="interfaces",
+                instructions=(
+                    "For each interface, document: name, type, protocol, provider, "
+                    "consumer, endpoints, and data format."
+                ),
+            ),
+            TemplateSection(
+                heading="## Data Contracts",
+                source="interfaces",
+                instructions=(
+                    "Document the data schemas and contracts for each interface."
+                ),
+            ),
+        ],
+    ),
+    "capability-map": ArtifactTemplate(
+        artifact_id="capability-map",
+        filename="capability-map.md",
+        system_prompt=(
+            "You are a technical writer documenting system capabilities. "
+            "Focus on WHAT the system can do, not HOW."
+        ),
+        sections=[
+            TemplateSection(
+                heading="## Capabilities",
+                source="capabilities",
+                instructions=(
+                    "List each capability with its priority, requirements, "
+                    "and which components realize it."
+                ),
+            ),
+            TemplateSection(
+                heading="## Capability-Component Mapping",
+                source="relationships",
+                instructions=(
+                    "Show which components realize which capabilities "
+                    "using relationship data."
+                ),
+            ),
+        ],
+    ),
+    "behavior-flows": ArtifactTemplate(
+        artifact_id="behavior-flows",
+        filename="behavior-flows.md",
+        system_prompt=(
+            "You are a technical writer documenting system workflows and behaviors. "
+            "Describe step-by-step flows clearly."
+        ),
+        sections=[
+            TemplateSection(
+                heading="## Behaviors",
+                source="behaviors",
+                instructions=(
+                    "For each behavior, document: trigger, actor, preconditions, "
+                    "steps, postconditions, pattern type."
+                ),
+            ),
+            TemplateSection(
+                heading="## Interaction Sequences",
+                source="behaviors",
+                instructions=(
+                    "Describe the sequence of interactions for key behaviors."
+                ),
+            ),
+        ],
+    ),
+    "constraint-register": ArtifactTemplate(
+        artifact_id="constraint-register",
+        filename="constraint-register.md",
+        system_prompt=(
+            "You are a technical writer documenting non-functional requirements "
+            "and design constraints."
+        ),
+        sections=[
+            TemplateSection(
+                heading="## Constraints",
+                source="constraints",
+                instructions=(
+                    "For each constraint, document: type, metric, threshold, rationale."
+                ),
+            ),
+            TemplateSection(
+                heading="## Constraint Allocation",
+                source="relationships",
+                instructions=(
+                    "Show which components are constrained by which constraints."
+                ),
+            ),
+        ],
+    ),
+    "dependency-graph": ArtifactTemplate(
+        artifact_id="dependency-graph",
+        filename="dependency-graph.md",
+        system_prompt=(
+            "You are a technical writer documenting system dependencies and coupling."
+        ),
+        sections=[
+            TemplateSection(
+                heading="## Direct Dependencies",
+                source="relationships",
+                instructions=(
+                    "List all depends-on relationships. Group by source component."
+                ),
+            ),
+            TemplateSection(
+                heading="## Dependency Analysis",
+                source="relationships",
+                instructions=(
+                    "Identify highly-coupled components, potential circular "
+                    "dependencies, and suggest improvements."
+                ),
+            ),
+        ],
+    ),
+    "layer-architecture": ArtifactTemplate(
+        artifact_id="layer-architecture",
+        filename="layer-architecture.md",
+        system_prompt=(
+            "You are a technical writer documenting the layered architecture "
+            "of the system."
+        ),
+        sections=[
+            TemplateSection(
+                heading="## Layers",
+                source="layers",
+                instructions=(
+                    "For each layer, document: name, order, technology stack, "
+                    "directories, and contained components."
+                ),
+            ),
+            TemplateSection(
+                heading="## Layer Interactions",
+                source="relationships",
+                instructions=(
+                    "Describe how layers communicate. Note any violations "
+                    "of layer ordering."
+                ),
+            ),
+        ],
+    ),
+    "deployment-view": ArtifactTemplate(
+        artifact_id="deployment-view",
+        filename="deployment-view.md",
+        system_prompt=(
+            "You are a technical writer documenting deployment topology "
+            "and operational concerns."
+        ),
+        sections=[
+            TemplateSection(
+                heading="## Deployment Units",
+                source="components",
+                instructions=(
+                    "Group components by their deployment unit (layer + kind). "
+                    "Describe what gets deployed together."
+                ),
+            ),
+            TemplateSection(
+                heading="## Operational Requirements",
+                source="constraints",
+                instructions=(
+                    "List performance, reliability, and operational constraints "
+                    "relevant to deployment."
+                ),
+            ),
+        ],
+    ),
+    "integration-guide": ArtifactTemplate(
+        artifact_id="integration-guide",
+        filename="integration-guide.md",
+        system_prompt=(
+            "You are a technical writer creating integration documentation "
+            "for developers connecting to this system."
+        ),
+        sections=[
+            TemplateSection(
+                heading="## Available Interfaces",
+                source="interfaces",
+                instructions=(
+                    "List all interfaces available for integration with protocol "
+                    "and data format details."
+                ),
+            ),
+            TemplateSection(
+                heading="## Integration Patterns",
+                source="components",
+                instructions=(
+                    "Describe recommended patterns for integrating with "
+                    "each component."
+                ),
+            ),
+            TemplateSection(
+                heading="## Authentication & Constraints",
+                source="constraints",
+                instructions=(
+                    "Document security constraints and authentication requirements."
+                ),
+            ),
+        ],
+    ),
+    "test-strategy": ArtifactTemplate(
+        artifact_id="test-strategy",
+        filename="test-strategy.md",
+        system_prompt=(
+            "You are a technical writer documenting the testing approach "
+            "for this system."
+        ),
+        sections=[
+            TemplateSection(
+                heading="## Test Inventory",
+                source="manifest.tests",
+                instructions=(
+                    "Summarize the test files, count, and coverage distribution "
+                    "across components."
+                ),
+            ),
+            TemplateSection(
+                heading="## Testing Approach",
+                source="components",
+                instructions=(
+                    "For each component, describe the testing strategy based on "
+                    "its kind and responsibilities."
+                ),
+            ),
+        ],
+    ),
+    "metrics-dashboard": ArtifactTemplate(
+        artifact_id="metrics-dashboard",
+        filename="metrics-dashboard.md",
+        system_prompt=(
+            "You are a technical writer summarizing code quality metrics."
+        ),
+        sections=[
+            TemplateSection(
+                heading="## Code Metrics",
+                source="manifest.metrics",
+                instructions=(
+                    "Present the metrics data: lines of code, complexity, "
+                    "file counts, module counts."
+                ),
+            ),
+            TemplateSection(
+                heading="## Quality Assessment",
+                source="manifest.metrics",
+                instructions=(
+                    "Assess overall code health based on the metrics. "
+                    "Note any concerning areas."
+                ),
+            ),
+        ],
+    ),
+}
+
+
+# ---------------------------------------------------------------------------
+# Per-Capability API Detail Template
+# ---------------------------------------------------------------------------
+
+API_DETAIL_TEMPLATE = ArtifactTemplate(
+    artifact_id="api-detail",
+    filename="api-detail-{cap_id}.md",  # placeholder — resolved per capability
+    system_prompt=(
+        "You are a senior systems engineer writing detailed API documentation for a "
+        "single capability within a software architecture. Write precise, implementation-"
+        "grounded documentation. Include exact function signatures, parameters, return "
+        "types, algorithm steps, and behavioral sequences. Use tables and code blocks. "
+        "Do NOT hallucinate — only document what is present in the provided data."
+    ),
+    sections=[
+        TemplateSection(
+            heading="## Overview",
+            source="capability_detail",
+            instructions=(
+                "Create a summary table with: ID, F-Block, Priority, Status, "
+                "Realized by (component + source path), Constraints, Actor. "
+                "Then one sentence describing the capability's purpose."
+            ),
+        ),
+        TemplateSection(
+            heading="## Primary API",
+            source="capability_detail",
+            instructions=(
+                "For each public function in the realizing component, document: "
+                "full signature, parameters (with types and defaults), return type, "
+                "algorithm steps (numbered), and example usage. Use the function "
+                "signatures, body_hints, and constants from the provided data."
+            ),
+        ),
+        TemplateSection(
+            heading="## Supporting Functions",
+            source="capability_detail",
+            instructions=(
+                "Document internal/helper functions. Show how they support the "
+                "primary API. Include signatures and brief descriptions."
+            ),
+        ),
+        TemplateSection(
+            heading="## Behavioral View",
+            source="capability_detail",
+            instructions=(
+                "For each related behavior, document: trigger, preconditions, "
+                "step sequence (as numbered list and ASCII sequence diagram), "
+                "postconditions, and exit codes/error handling."
+            ),
+        ),
+        TemplateSection(
+            heading="## Relationship Graph",
+            source="capability_detail",
+            instructions=(
+                "Show the capability's relationship neighborhood as an ASCII "
+                "diagram. Include: realizes, depends-on, exposes, constrained-by."
+            ),
+        ),
+        TemplateSection(
+            heading="## Data Contracts",
+            source="capability_detail",
+            instructions=(
+                "Document input/output data formats for interfaces. Include "
+                "return type fields as tables. Reference test contracts as "
+                "behavioral expectations."
+            ),
+        ),
+    ],
+)
+
+
+def get_template(artifact_id: str) -> ArtifactTemplate | None:
+    """Look up template by artifact ID. Returns None if not found."""
+    if artifact_id.startswith("api-detail-"):
+        return API_DETAIL_TEMPLATE
+    return TEMPLATES.get(artifact_id)

opencode_arch/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI for opencode-arch."""

opencode_arch/cli/bench.py

@@ -0,0 +1,25 @@
+"""Bench command - benchmark extraction on multiple repos."""
+from __future__ import annotations
+
+from typing import Any
+
+from opencode_arch.runner.base import RunnerBackend
+from opencode_arch.cli.extract import run_extract
+
+
+async def run_bench(
+    repos: list[str],
+    runner: RunnerBackend,
+    budget: int = 4000,
+    target_score: int = 80,
+) -> list[dict[str, Any]]:
+    """Run extraction benchmark on multiple repositories."""
+    results = []
+    for repo_path in repos:
+        result = await run_extract(
+            repo_path=repo_path, runner=runner,
+            budget=budget, target_score=target_score,
+        )
+        result["repo"] = repo_path
+        results.append(result)
+    return results

opencode_arch/cli/calibrate.py

@@ -0,0 +1,208 @@
+"""Calibration command - spot-check confidence by attempting regeneration."""
+from __future__ import annotations
+
+import ast
+import math
+import random
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from architecture_model.core.types import ArchitectureModel, Component
+
+
+@dataclass
+class CalibrationReport:
+    """Result of a calibration run."""
+
+    components_tested: int
+    correlation: float
+    bands: dict  # confidence_band → regen_success_rate
+    threshold: float  # recommended confidence for safe regeneration
+
+
+def select_calibration_targets(
+    model_or_components, *, n: int = 3, min_confidence: float = 0.7, count: int = 6
+):
+    """Select components for calibration.
+    
+    Supports two calling conventions:
+    - Legacy: select_calibration_targets(model, n=3, min_confidence=0.7) with ArchitectureModel
+    - New: select_calibration_targets(components, count=6) with list[dict]
+    """
+    if isinstance(model_or_components, list):
+        # New dict-based interface (Task 6)
+        components = model_or_components
+        if not components:
+            return []
+        sorted_comps = sorted(components, key=lambda c: c.get("confidence", 0))
+        num = len(sorted_comps)
+        if num <= count:
+            return sorted_comps
+        indices = [round(i * (num - 1) / (count - 1)) for i in range(count)]
+        return [sorted_comps[i] for i in indices]
+    else:
+        # Legacy ArchitectureModel interface
+        model = model_or_components
+        candidates = [c for c in model.entities.components if c.confidence >= min_confidence and c.files]
+        if not candidates:
+            candidates = [c for c in model.entities.components if c.files]
+        random.shuffle(candidates)
+        return candidates[:n]
+
+
+def format_calibration_prompt(comp: Component) -> str:
+    """Format a prompt asking the agent to regenerate a component from its model spec."""
+    sections = []
+    sections.append(f"## Regenerate: {comp.name} ({comp.id})")
+    sections.append("")
+    sections.append(f"**Contract:** {comp.contract or 'Not specified'}")
+    sections.append(f"**Pattern:** {comp.pattern or 'Not specified'}")
+    sections.append(f"**Files:** {', '.join(comp.files)}")
+
+    if comp.responsibilities:
+        sections.append(f"**Responsibilities:** {'; '.join(comp.responsibilities)}")
+
+    if comp.signatures:
+        sections.append("\n**Signatures:**")
+        for sig in comp.signatures:
+            params = ", ".join(sig.params) if sig.params else ""
+            ret = f" -> {sig.returns}" if sig.returns else ""
+            decorators = " ".join(f"@{d}" for d in sig.decorators) + " " if sig.decorators else ""
+            sections.append(f"  {decorators}def {sig.name}({params}){ret}")
+            if sig.body_hint:
+                sections.append(f"    # Hint: {sig.body_hint}")
+
+    if comp.symbols:
+        sections.append("\n**Classes:**")
+        for sym in comp.symbols:
+            bases = f"({', '.join(sym.supers)})" if sym.supers else ""
+            sections.append(f"  class {sym.name}{bases}")
+            if sym.members:
+                for m in sym.members[:10]:
+                    sections.append(f"    - {m}")
+
+    if comp.constants:
+        sections.append("\n**Constants:**")
+        for const in comp.constants:
+            sections.append(f"  {const.name} = {const.value}")
+
+    if comp.test_contracts:
+        sections.append("\n**Expected behavior (from tests):**")
+        for tc in comp.test_contracts[:5]:
+            sections.append(f"  {tc.test_method}: {tc.assertion}")
+
+    sections.append("\n---")
+    sections.append("**Task:** Implement this component using ONLY the specification above.")
+    sections.append("Do NOT read source files. Generate the complete implementation.")
+
+    return "\n".join(sections)
+
+
+def compare_regeneration(original: "str | Path", generated: str) -> dict:
+    """Compare original and generated source code by public API coverage.
+    
+    original can be a string of source code or a Path to a file.
+    """
+    if isinstance(original, Path):
+        original = original.read_text()
+
+    def _extract_names(code: str) -> tuple[set[str], set[str]]:
+        try:
+            tree = ast.parse(code)
+        except SyntaxError:
+            return set(), set()
+        functions = {node.name for node in ast.walk(tree) if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))}
+        classes = {node.name for node in ast.walk(tree) if isinstance(node, ast.ClassDef)}
+        return functions, classes
+
+    orig_funcs, orig_classes = _extract_names(original)
+    gen_funcs, gen_classes = _extract_names(generated)
+
+    func_match = len(orig_funcs & gen_funcs) / len(orig_funcs) if orig_funcs else 1.0
+    class_match = len(orig_classes & gen_classes) / len(orig_classes) if orig_classes else 1.0
+    line_ratio = len(generated.splitlines()) / max(1, len(original.splitlines()))
+
+    covered = orig_funcs & gen_funcs
+    api_coverage = len(covered) / len(orig_funcs) if orig_funcs else 1.0
+
+    return {
+        "function_match": func_match,
+        "class_match": class_match,
+        "line_ratio": line_ratio,
+        "original_functions": len(orig_funcs),
+        "generated_functions": len(gen_funcs),
+        "calibration_score": (func_match * 0.5 + class_match * 0.3 + min(line_ratio, 1.0) * 0.2),
+        "api_coverage": api_coverage,
+        "missing_apis": sorted(orig_funcs - gen_funcs),
+        "extra_apis": sorted(gen_funcs - orig_funcs),
+    }
+
+
+# --- Task 5: Regeneration Proof ---
+
+
+def format_regeneration_prompt(component_context: dict) -> str:
+    """Format a prompt for regenerating a component from model data only."""
+    lines = [
+        "Regenerate this component from model data only, DO NOT read source files.",
+        "",
+        f"# Component: {component_context.get('name', 'Unknown')} ({component_context.get('id', '?')})",
+        "",
+        f"**Contract:** {component_context.get('contract', 'Not specified')}",
+        f"**Pattern:** {component_context.get('pattern', 'Not specified')}",
+    ]
+
+    responsibilities = component_context.get("responsibilities", [])
+    if responsibilities:
+        lines.append("\n**Responsibilities:**")
+        for r in responsibilities:
+            lines.append(f"  - {r}")
+
+    signatures = component_context.get("signatures", [])
+    if signatures:
+        lines.append("\n**Signatures:**")
+        for sig in signatures:
+            params = ", ".join(sig.get("params", []))
+            ret = f" -> {sig['returns']}" if sig.get("returns") else ""
+            lines.append(f"  def {sig['name']}({params}){ret}")
+
+    symbols = component_context.get("symbols", [])
+    if symbols:
+        lines.append("\n**Symbols:**")
+        for sym in symbols:
+            members = ", ".join(sym.get("members", []))
+            lines.append(f"  {sym.get('kind', 'class')} {sym['name']}: [{members}]")
+
+    constants = component_context.get("constants", [])
+    if constants:
+        lines.append("\n**Constants:**")
+        for c in constants:
+            lines.append(f"  {c['name']} = {c['value']}")
+
+    lines.append("\n---")
+    lines.append("Provide the complete Python module output.")
+
+    return "\n".join(lines)
+
+
+
+
+# --- Task 6: Calibration Suite ---
+
+
+def compute_correlation(data: list[dict]) -> float:
+    """Pearson correlation between confidence and regen_quality fields."""
+    if len(data) < 2:
+        return 0.0
+    xs = [d["confidence"] for d in data]
+    ys = [d["regen_quality"] for d in data]
+    n = len(xs)
+    mean_x = sum(xs) / n
+    mean_y = sum(ys) / n
+    num = sum((x - mean_x) * (y - mean_y) for x, y in zip(xs, ys))
+    den_x = math.sqrt(sum((x - mean_x) ** 2 for x in xs))
+    den_y = math.sqrt(sum((y - mean_y) ** 2 for y in ys))
+    if den_x == 0 or den_y == 0:
+        return 0.0
+    return num / (den_x * den_y)