archsteer 0.1.0__py3-none-any.whl

archsteer/__init__.py

@@ -0,0 +1,7 @@
+"""ArchSteer — Living Architecture Control Plane for the AI-Dev Era.
+
+One code-derived model (``model.json``) powers every pillar:
+MAP, DOCUMENT, GOVERN, STEER, EVOLVE.
+"""
+
+__version__ = "0.1.0"

archsteer/cli.py

@@ -0,0 +1,383 @@
+"""ArchSteer CLI — every command is a projection of the one shared model.
+
+    archsteer init     scaffold .archsteer/ + seed intent
+    archsteer map      build model.json from source
+    archsteer docs     regenerate living architecture.md
+    archsteer adr      detect structural decisions -> draft ADRs
+    archsteer govern   show conformance / drift
+    archsteer baseline snapshot accepted violations (the ratchet)
+    archsteer check    fail on NET-NEW violations only (CI / pre-commit)
+    archsteer steer    write agent guardrails into CLAUDE.md / AGENTS.md
+    archsteer report   build the self-contained report.html
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import List, Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from archsteer import __version__
+from archsteer.docs import render_architecture_md
+from archsteer.engine.baseline import Baseline
+from archsteer.engine.conformance import ConformanceReport, evaluate
+from archsteer.engine.decisions import DecisionEngine
+from archsteer.engine.evolution import History, compute_feed
+from archsteer.engine.intent import Intent
+from archsteer.engine.mapper import build_model
+from archsteer.engine.model import ArchitectureModel
+from archsteer.report import render_report_html
+from archsteer.steer import AgentSteeringEngine
+from archsteer.workspace import Workspace
+
+app = typer.Typer(add_completion=False, help="ArchSteer — Living Architecture Control Plane.")
+console = Console()
+PACK_DIR = Path(__file__).parent / "packs" / "express_to_next"
+
+
+def _ws(path: Optional[str]) -> Workspace:
+    return Workspace(Path(path or "."))
+
+
+def _require_init(ws: Workspace) -> None:
+    if not ws.initialized:
+        console.print("[red]Not initialized.[/red] Run [bold]archsteer init[/bold] first.")
+        raise typer.Exit(1)
+
+
+def _load_model(ws: Workspace) -> ArchitectureModel:
+    model = ArchitectureModel.load_if_exists(ws.model)
+    if model is None:
+        console.print("[yellow]No model found — run [bold]archsteer map[/bold] first.[/yellow]")
+        raise typer.Exit(1)
+    return model
+
+
+def _conformance(ws: Workspace, model: ArchitectureModel) -> ConformanceReport:
+    """Evaluate intent if present; otherwise return an empty report (X-ray mode)."""
+    intent = Intent.load_if_exists(ws.intent)
+    if intent is None:
+        return ConformanceReport()
+    return evaluate(model, intent)
+
+
+def _record_snapshot(ws: Workspace, model: ArchitectureModel) -> None:
+    conf = _conformance(ws, model)
+    has_intent = ws.intent.exists()
+    History(ws.history_dir).record(
+        model,
+        conformance_score=conf.conformance_score if has_intent else None,
+        drift_score=conf.drift_score if has_intent else None,
+        open_violations=len(conf.all_violations) if has_intent else None,
+    )
+
+
+@app.command()
+def version() -> None:
+    """Print the ArchSteer version."""
+    console.print(f"ArchSteer {__version__}")
+
+
+@app.command()
+def init(path: Optional[str] = typer.Option(None, help="Repo root (default: cwd).")) -> None:
+    """Scaffold .archsteer/ and seed the starter intent + ADRs."""
+    ws = _ws(path)
+    if ws.initialized:
+        console.print(f"[yellow]Already initialized at {ws.dir}[/yellow]")
+        raise typer.Exit(0)
+    ws.dir.mkdir(parents=True, exist_ok=True)
+    ws.adr_dir.mkdir(parents=True, exist_ok=True)
+    shutil.copyfile(PACK_DIR / "architecture.yaml", ws.intent)
+    for adr in (PACK_DIR / "adr").glob("*.md"):
+        shutil.copyfile(adr, ws.adr_dir / adr.name)
+    console.print(f"[green]✓[/green] Initialized [bold]{ws.dir}[/bold]")
+    console.print("  • seeded [cyan]architecture.yaml[/cyan] (Express → Next.js + repository)")
+    console.print("  • seeded baseline ADRs in [cyan].archsteer/adr/[/cyan]")
+    console.print("\nNext: [bold]archsteer map[/bold] then [bold]archsteer report[/bold]")
+
+
+@app.command()
+def map(path: Optional[str] = typer.Option(None, help="Repo root (default: cwd).")) -> None:
+    """Build the architecture model (.archsteer/model.json) from source."""
+    ws = _ws(path)
+    _require_init(ws)
+    if ws.model.exists():
+        shutil.copyfile(ws.model, ws.model_prev)  # keep prior snapshot for `adr`
+    model = build_model(ws.root)
+    model.save(ws.model)
+    _record_snapshot(ws, model)
+    console.print(
+        f"[green]✓[/green] Mapped [bold]{len(model.components)}[/bold] components · "
+        f"layers: {', '.join(sorted(model.get_layers())) or '—'} · "
+        f"data stores: {', '.join(sorted(model.get_all_data_stores())) or '—'}"
+    )
+
+
+@app.command()
+def docs(path: Optional[str] = typer.Option(None)) -> None:
+    """Regenerate living architecture docs (deterministic)."""
+    ws = _ws(path)
+    _require_init(ws)
+    model = _load_model(ws)
+    ws.architecture_md.write_text(render_architecture_md(model), encoding="utf-8")
+    console.print(f"[green]✓[/green] Wrote [bold]{ws.architecture_md}[/bold]")
+
+
+@app.command()
+def adr(path: Optional[str] = typer.Option(None)) -> None:
+    """Detect structural decisions since the last map and draft ADRs."""
+    ws = _ws(path)
+    _require_init(ws)
+    model = _load_model(ws)
+    prev = ArchitectureModel.load_if_exists(ws.model_prev)
+    engine = DecisionEngine(ws.adr_dir)
+    drafts = engine.analyze_diff(prev, model)
+    written = engine.write_drafts(drafts)
+    if not written:
+        console.print("[green]✓[/green] No new architectural decisions to record.")
+        return
+    console.print(f"[yellow]📝 {len(written)} draft ADR(s) need architect review:[/yellow]")
+    for p in written:
+        console.print(f"  • {p.relative_to(ws.root)}")
+
+
+@app.command()
+def govern(path: Optional[str] = typer.Option(None)) -> None:
+    """Show conformance and drift against declared intent."""
+    ws = _ws(path)
+    _require_init(ws)
+    model = _load_model(ws)
+    report = _conformance(ws, model)
+    table = Table(title=f"Conformance — {report.target or ws.root.name}")
+    table.add_column("Rule"); table.add_column("Sev"); table.add_column("Progress", justify="right")
+    table.add_column("Open", justify="right")
+    for r in report.results:
+        table.add_row(r.rule_id, r.severity, f"{r.progress}%", str(len(r.violations)))
+    console.print(table)
+    console.print(
+        f"Overall conformance: [bold]{report.conformance_score}%[/bold] · "
+        f"drift: [bold]{report.drift_score}%[/bold]"
+    )
+
+
+@app.command()
+def baseline(path: Optional[str] = typer.Option(None)) -> None:
+    """Snapshot current violations as accepted debt (the ratchet)."""
+    ws = _ws(path)
+    _require_init(ws)
+    model = _load_model(ws)
+    report = _conformance(ws, model)
+    bl = Baseline.from_report(report)
+    bl.save(ws.baseline)
+    console.print(f"[green]✓[/green] Baselined [bold]{len(bl.fingerprints)}[/bold] existing violation(s).")
+    console.print("New violations will now be blocked by [bold]archsteer check[/bold].")
+
+
+@app.command()
+def check(
+    path: Optional[str] = typer.Option(None),
+    remap: bool = typer.Option(True, help="Rebuild the model before checking."),
+) -> None:
+    """Fail (exit 1) on NET-NEW violations only — for CI / pre-commit."""
+    ws = _ws(path)
+    _require_init(ws)
+    if remap:
+        model = build_model(ws.root)
+        model.save(ws.model)
+    else:
+        model = _load_model(ws)
+    report = _conformance(ws, model)
+    bl = Baseline.load_if_exists(ws.baseline)
+    if bl is None:
+        console.print("[yellow]No baseline — treating ALL violations as net-new.[/yellow]")
+        net_new = report.all_violations
+        fixed = 0
+    else:
+        net_new = bl.net_new(report)
+        fixed = bl.fixed(report)
+    if fixed:
+        console.print(f"[green]↑ {fixed} baselined violation(s) resolved — nice.[/green]")
+    blocking = [v for v in net_new if v.severity == "error"]
+    for v in net_new:
+        tag = "[red]✗[/red]" if v.severity == "error" else "[yellow]△[/yellow]"
+        console.print(f"{tag} {v.file}:{v.loc} [dim]{v.rule_id}[/dim] — {v.message}")
+    if blocking:
+        console.print(f"\n[red]✗ {len(blocking)} net-new error violation(s) block this change.[/red]")
+        raise typer.Exit(1)
+    console.print("\n[green]✓ No net-new blocking violations.[/green]")
+
+
+@app.command()
+def steer(
+    path: Optional[str] = typer.Option(None),
+    files: Optional[List[str]] = typer.Option(None, "--files", "-f", help="Files in scope."),
+    task: Optional[str] = typer.Option(None, "--task", "-t", help="What the agent is about to do."),
+    targets: Optional[List[str]] = typer.Option(None, "--target", help="Agent files to write."),
+) -> None:
+    """Inject sharp, model-grounded guardrails into agent context files."""
+    ws = _ws(path)
+    _require_init(ws)
+    model = _load_model(ws)
+    intent = Intent.load(ws.intent)
+    engine = AgentSteeringEngine(ws.root)
+    payload = engine.synthesize(intent, model, files=files, task=task)
+    written = engine.write(payload, targets=targets)
+    console.print(f"[green]✓[/green] Steered: {', '.join(str(p.relative_to(ws.root)) for p in written) or '(no targets)'}")
+
+
+def _render_report(ws: Workspace, model: ArchitectureModel) -> None:
+    conf = _conformance(ws, model)
+    governed = ws.intent.exists()
+    prev = ArchitectureModel.load_if_exists(ws.model_prev)
+    pending = [d.title for d in DecisionEngine(ws.adr_dir).analyze_diff(prev, model)]
+    bl = Baseline.load_if_exists(ws.baseline)
+    fixed = bl.fixed(conf) if bl else 0
+    hist = History(ws.history_dir)
+    metas = hist.metas()
+    old_meta, new_meta = hist.latest_two()
+    old_model = hist.load_model(old_meta) if old_meta else None
+    feed = compute_feed(old_model, model, old_meta, new_meta)
+    ws.report_html.write_text(
+        render_report_html(
+            model, conf, pending, fixed_count=fixed,
+            feed=feed, history=metas, governed=governed,
+        ),
+        encoding="utf-8",
+    )
+
+
+@app.command()
+def report(path: Optional[str] = typer.Option(None)) -> None:
+    """Build the self-contained report.html (map + evolution + conformance + decisions)."""
+    ws = _ws(path)
+    _require_init(ws)
+    _render_report(ws, _load_model(ws))
+    console.print(f"[green]✓[/green] Wrote [bold]{ws.report_html}[/bold] — open it in a browser.")
+
+
+@app.command()
+def xray(path: Optional[str] = typer.Option(None, help="Repo root (default: cwd).")) -> None:
+    """Zero-config read-only X-ray: map + docs + evolution + report, no intent needed.
+
+    The universal wedge — point it at ANY repo and instantly see what the
+    architecture is and how it changed, without declaring any rules.
+    """
+    ws = _ws(path)
+    ws.dir.mkdir(parents=True, exist_ok=True)
+    if ws.model.exists():
+        shutil.copyfile(ws.model, ws.model_prev)
+    model = build_model(ws.root)
+    model.save(ws.model)
+    _record_snapshot(ws, model)
+    ws.architecture_md.write_text(render_architecture_md(model), encoding="utf-8")
+    # Draft ADRs for any structural change since last snapshot (architect-in-the-loop).
+    DecisionEngine(ws.adr_dir).write_drafts(
+        DecisionEngine(ws.adr_dir).analyze_diff(
+            ArchitectureModel.load_if_exists(ws.model_prev), model
+        )
+    )
+    _render_report(ws, model)
+    old_meta, new_meta = History(ws.history_dir).latest_two()
+    feed = compute_feed(
+        History(ws.history_dir).load_model(old_meta) if old_meta else None,
+        model, old_meta, new_meta,
+    )
+    console.print(
+        f"[green]✓[/green] X-ray of [bold]{ws.root.name}[/bold]: "
+        f"{len(model.components)} components, {len(model.get_layers())} layers."
+    )
+    console.print(f"  {feed.summary()}")
+    console.print(f"  → [bold]{ws.architecture_md.relative_to(ws.root)}[/bold] and "
+                  f"[bold]{ws.report_html.relative_to(ws.root)}[/bold] (open in a browser)")
+
+
+@app.command()
+def push(
+    path: Optional[str] = typer.Option(None),
+    url: Optional[str] = typer.Option(None, envvar="ARCHSTEER_URL", help="Ingest endpoint."),
+    token: Optional[str] = typer.Option(None, envvar="ARCHSTEER_TOKEN", help="Org API token."),
+    org: Optional[str] = typer.Option(None, envvar="ARCHSTEER_ORG", help="Organization slug."),
+) -> None:
+    """Push the latest snapshot + conformance to the cloud situation room."""
+    ws = _ws(path)
+    _require_init(ws)
+    model = _load_model(ws)
+    conf = _conformance(ws, model)
+    governed = ws.intent.exists()
+    prev = ArchitectureModel.load_if_exists(ws.model_prev)
+    pending = len(DecisionEngine(ws.adr_dir).analyze_diff(prev, model))
+    hist = History(ws.history_dir)
+    old_meta, new_meta = hist.latest_two()
+    feed = compute_feed(hist.load_model(old_meta) if old_meta else None, model, old_meta, new_meta)
+
+    payload = {
+        "repo": model.repo_name,
+        "org": org,
+        "commit": model.commit_sha,
+        "timestamp": model.timestamp,
+        "components": len(model.components),
+        "layers": sorted(model.get_layers()),
+        "external_dependencies": len(model.get_all_external_dependencies()),
+        "data_stores": len([s for s in model.get_all_data_stores() if s != "raw_sql"]),
+        "conformance_score": conf.conformance_score if governed else None,
+        "drift_score": conf.drift_score if governed else None,
+        "open_violations": len(conf.all_violations) if governed else None,
+        "pending_decisions": pending,
+        "changes": [c.model_dump() for c in feed.changes],
+    }
+    endpoint = url or "https://archsteer.dev/api/ingest"
+    req = urllib.request.Request(
+        endpoint, data=json.dumps(payload).encode("utf-8"),
+        headers={"Content-Type": "application/json",
+                 **({"Authorization": f"Bearer {token}"} if token else {})},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            body = json.loads(resp.read().decode("utf-8"))
+        console.print(
+            f"[green]✓[/green] Pushed [bold]{model.repo_name}[/bold] → situation room "
+            f"({endpoint}) · {body.get('snapshots', '?')} snapshot(s)."
+        )
+    except urllib.error.HTTPError as e:
+        console.print(f"[red]✗ Push failed ({e.code}): {e.reason}[/red]")
+        raise typer.Exit(1)
+    except urllib.error.URLError as e:
+        console.print(f"[red]✗ Could not reach {endpoint}: {e.reason}[/red]")
+        raise typer.Exit(1)
+
+
+@app.command()
+def evolution(
+    path: Optional[str] = typer.Option(None),
+    limit: int = typer.Option(15, help="Max changes to show."),
+) -> None:
+    """Show the Architecture Evolution Feed between the two latest snapshots."""
+    ws = _ws(path)
+    hist = History(ws.history_dir)
+    old_meta, new_meta = hist.latest_two()
+    if new_meta is None:
+        console.print("[yellow]No history yet — run [bold]archsteer map[/bold] or [bold]xray[/bold] first.[/yellow]")
+        raise typer.Exit(1)
+    old_model = hist.load_model(old_meta) if old_meta else None
+    new_model = hist.load_model(new_meta)
+    feed = compute_feed(old_model, new_model, old_meta, new_meta)
+    console.print(f"[bold]Architecture Evolution[/bold] — {feed.summary()}")
+    if feed.drift_delta is not None:
+        arrow = "↓ improved" if feed.drift_delta < 0 else ("↑ worsened" if feed.drift_delta > 0 else "unchanged")
+        console.print(f"Drift Index: {arrow} ({'+' if feed.drift_delta > 0 else ''}{feed.drift_delta} pts)")
+    for c in feed.changes[:limit]:
+        icon = {"positive": "[green]✓[/green]", "negative": "[red]✗[/red]"}.get(c.direction, "•")
+        console.print(f"  {icon} {c.text}")
+
+
+if __name__ == "__main__":
+    app()

archsteer/docs.py

@@ -0,0 +1,73 @@
+"""Living architecture docs generated from the model (deterministic / idempotent).
+
+Intentionally excludes wall-clock timestamps so regeneration is byte-identical when
+the model is unchanged (verification relies on this). Produces architecture.md with
+a Mermaid layer diagram and a component catalog.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Dict, List, Set, Tuple
+
+from archsteer.engine.model import ArchitectureModel
+
+
+def _layer_edges(model: ArchitectureModel) -> Set[Tuple[str, str]]:
+    edges: Set[Tuple[str, str]] = set()
+    for src, dst in model.internal_edges():
+        sl = model.components[src].layer or "unassigned"
+        dl = model.components[dst].layer or "unassigned"
+        if sl != dl:
+            edges.add((sl, dl))
+    return edges
+
+
+def _mermaid(model: ArchitectureModel) -> str:
+    edges = sorted(_layer_edges(model))
+    layers = sorted(model.get_layers() | {"unassigned"})
+    lines = ["```mermaid", "graph LR"]
+    if not edges:
+        for layer in layers:
+            lines.append(f"    {layer}[{layer}]")
+    for sl, dl in edges:
+        lines.append(f"    {sl}[{sl}] --> {dl}[{dl}]")
+    lines.append("```")
+    return "\n".join(lines)
+
+
+def render_architecture_md(model: ArchitectureModel) -> str:
+    layer_counts: Dict[str, int] = defaultdict(int)
+    for comp in model.components.values():
+        layer_counts[comp.layer or "unassigned"] += 1
+
+    ext_deps = sorted(model.get_all_external_dependencies())
+    stores = sorted(model.get_all_data_stores())
+
+    out: List[str] = [
+        f"# Architecture — {model.repo_name}",
+        "",
+        "> Auto-generated by ArchSteer from source. Do not edit by hand; run `archsteer docs`.",
+        "",
+        "## Overview",
+        f"- **Components:** {len(model.components)}",
+        f"- **Layers:** {', '.join(sorted(model.get_layers())) or '—'}",
+        f"- **Data stores:** {', '.join(stores) or '—'}",
+        f"- **External call sites:** {sum(len(c.external_calls) for c in model.components.values())}",
+        "",
+        "## Layer map",
+        _mermaid(model),
+        "",
+        "## Components by layer",
+    ]
+    for layer in sorted(layer_counts):
+        out.append(f"- **{layer}** — {layer_counts[layer]} component(s)")
+    out += ["", "## Component catalog", "", "| Component | Layer | Exports | Data access | External |", "|---|---|---|---|---|"]
+    for path in sorted(model.components):
+        c = model.components[path]
+        exports = ", ".join(c.exported_apis[:4]) or "—"
+        da = ", ".join(sorted({d.entity for d in c.data_access})) or "—"
+        ext = str(len(c.external_calls)) if c.external_calls else "—"
+        out.append(f"| `{path}` | {c.layer or '—'} | {exports} | {da} | {ext} |")
+    out.append("")
+    return "\n".join(out)

archsteer/engine/__init__.py

@@ -0,0 +1 @@
+"""ArchSteer engine: the single source of truth (model) and its projections."""

archsteer/engine/baseline.py

@@ -0,0 +1,53 @@
+"""The ratchet: accept existing debt, block only net-new violations.
+
+Teams mid-migration can't freeze features or fix all debt at once. ``baseline``
+snapshots the currently-accepted violation fingerprints; ``check`` then fails only
+on fingerprints not in that snapshot. Architecture can only improve from here.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import List
+
+from archsteer.engine.conformance import ConformanceReport, Violation
+
+
+class Baseline:
+    def __init__(self, fingerprints: set[str], created: str | None = None):
+        self.fingerprints = fingerprints
+        self.created = created or datetime.now(timezone.utc).isoformat()
+
+    @classmethod
+    def from_report(cls, report: ConformanceReport) -> "Baseline":
+        return cls({v.fingerprint for v in report.all_violations})
+
+    @classmethod
+    def load(cls, path: Path) -> "Baseline":
+        data = json.loads(Path(path).read_text(encoding="utf-8"))
+        return cls(set(data.get("fingerprints", [])), data.get("created"))
+
+    @classmethod
+    def load_if_exists(cls, path: Path) -> "Baseline | None":
+        p = Path(path)
+        return cls.load(p) if p.exists() else None
+
+    def save(self, path: Path) -> None:
+        Path(path).parent.mkdir(parents=True, exist_ok=True)
+        Path(path).write_text(
+            json.dumps(
+                {"created": self.created, "fingerprints": sorted(self.fingerprints)},
+                indent=2,
+            ),
+            encoding="utf-8",
+        )
+
+    def net_new(self, report: ConformanceReport) -> List[Violation]:
+        return [v for v in report.all_violations if v.fingerprint not in self.fingerprints]
+
+    def fixed(self, report: ConformanceReport) -> int:
+        """Count of baselined violations that are now resolved (progress!)."""
+        current = {v.fingerprint for v in report.all_violations}
+        return len(self.fingerprints - current)

archsteer/engine/conformance.py

@@ -0,0 +1,166 @@
+"""Evaluate declared intent against the model — fitness functions + drift score.
+
+Produces stable-fingerprinted violations (line-number independent, so cosmetic
+edits don't churn the ratchet baseline) and a per-rule migration/conformance %.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import hashlib
+import re
+from typing import Dict, List, Optional
+
+from pydantic import BaseModel
+
+from archsteer.engine.intent import Intent, Rule
+from archsteer.engine.model import ArchitectureComponent, ArchitectureModel
+
+
+class Violation(BaseModel):
+    rule_id: str
+    severity: str
+    file: str
+    message: str
+    loc: int = 0
+    fingerprint: str = ""
+
+    def with_fingerprint(self) -> "Violation":
+        # Line-independent identity: rule + file + message-shape.
+        key = f"{self.rule_id}|{self.file}|{self.message}".encode("utf-8")
+        self.fingerprint = hashlib.sha1(key).hexdigest()[:12]
+        return self
+
+
+class RuleResult(BaseModel):
+    rule_id: str
+    description: str
+    severity: str
+    scoped: int
+    compliant: int
+    violations: List[Violation] = []
+
+    @property
+    def progress(self) -> float:
+        if self.scoped == 0:
+            return 100.0
+        return round(100.0 * self.compliant / self.scoped, 1)
+
+
+class ConformanceReport(BaseModel):
+    target: Optional[str] = None
+    results: List[RuleResult] = []
+
+    @property
+    def all_violations(self) -> List[Violation]:
+        return [v for r in self.results for v in r.violations]
+
+    @property
+    def conformance_score(self) -> float:
+        """Overall % of (rule, component) checks that pass."""
+        scoped = sum(r.scoped for r in self.results)
+        compliant = sum(r.compliant for r in self.results)
+        if scoped == 0:
+            return 100.0
+        return round(100.0 * compliant / scoped, 1)
+
+    @property
+    def drift_score(self) -> float:
+        return round(100.0 - self.conformance_score, 1)
+
+
+def _in_scope(rule: Rule, comp: ArchitectureComponent) -> bool:
+    if rule.scope_layer is not None:
+        return comp.layer == rule.scope_layer
+    if rule.scope:
+        return fnmatch.fnmatch(comp.file_path, rule.scope)
+    return True  # whole repo
+
+
+def _eval_rule(rule: Rule, model: ArchitectureModel) -> RuleResult:
+    scoped = 0
+    compliant = 0
+    violations: List[Violation] = []
+
+    for comp in model.components.values():
+        if not _in_scope(rule, comp):
+            continue
+        scoped += 1
+        v = _violations_for(rule, comp, model)
+        if v:
+            violations.extend(v)
+        else:
+            compliant += 1
+
+    return RuleResult(
+        rule_id=rule.id,
+        description=rule.description,
+        severity=rule.severity,
+        scoped=scoped,
+        compliant=compliant,
+        violations=violations,
+    )
+
+
+def _violations_for(
+    rule: Rule, comp: ArchitectureComponent, model: ArchitectureModel
+) -> List[Violation]:
+    out: List[Violation] = []
+    ops = {o.upper() for o in rule.operations}
+
+    if rule.type == "required_layer_for_data_access":
+        if comp.layer in rule.allowed_layers:
+            return out
+        for da in comp.data_access:
+            if not ops or (da.operations & ops):
+                out.append(
+                    Violation(
+                        rule_id=rule.id, severity=rule.severity, file=comp.file_path,
+                        loc=da.loc,
+                        message=f"data access to '{da.entity}' ({'/'.join(sorted(da.operations))}) outside allowed layers {rule.allowed_layers}",
+                    ).with_fingerprint()
+                )
+
+    elif rule.type == "forbidden_data_access":
+        for da in comp.data_access:
+            if not ops or (da.operations & ops):
+                out.append(
+                    Violation(
+                        rule_id=rule.id, severity=rule.severity, file=comp.file_path,
+                        loc=da.loc,
+                        message=f"forbidden data access to '{da.entity}' ({'/'.join(sorted(da.operations))})",
+                    ).with_fingerprint()
+                )
+
+    elif rule.type == "forbidden_import" and rule.pattern:
+        rx = re.compile(rule.pattern)
+        for dep in comp.dependencies:
+            if rx.search(dep.target):
+                out.append(
+                    Violation(
+                        rule_id=rule.id, severity=rule.severity, file=comp.file_path,
+                        loc=dep.loc,
+                        message=f"forbidden import '{dep.target}' (matches /{rule.pattern}/)",
+                    ).with_fingerprint()
+                )
+
+    elif rule.type == "forbidden_layer_edge":
+        for dep in comp.dependencies:
+            tgt = model.components.get(dep.target)
+            if tgt and comp.layer == rule.from_layer and tgt.layer == rule.to_layer:
+                out.append(
+                    Violation(
+                        rule_id=rule.id, severity=rule.severity, file=comp.file_path,
+                        loc=dep.loc,
+                        message=f"{rule.from_layer} -> {rule.to_layer} dependency on '{dep.target}' is forbidden",
+                    ).with_fingerprint()
+                )
+
+    return out
+
+
+def evaluate(model: ArchitectureModel, intent: Intent) -> ConformanceReport:
+    return ConformanceReport(
+        target=intent.target,
+        results=[_eval_rule(rule, model) for rule in intent.rules],
+    )