archy 0.4.1__py3-none-any.whl

archy/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.4.1"

archy/cli.py

@@ -0,0 +1,473 @@
+"""Click-based command-line interface for archy."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import click
+import networkx as nx
+
+from archy import __version__
+from archy.cycles import Cycle, find_cycles
+from archy.graph import build_graph
+from archy.history import append as append_history
+from archy.history import git_metadata, row_from_score
+from archy.history import read as read_history
+from archy.layers import (
+    LayerConfigError,
+    Violation,
+    discover_config,
+    find_violations,
+    load_config,
+)
+from archy.score import Score, compute_score
+from archy.trend import render_text as render_trend
+
+
+@click.group()
+@click.version_option(__version__)
+def main() -> None:
+    """archy - architectural sensor for Python codebases."""
+
+
+@main.command()
+@click.argument("path", type=click.Path(exists=True, file_okay=False, path_type=Path))
+@click.option(
+    "--format",
+    "fmt",
+    type=click.Choice(["json", "dot", "text"]),
+    default="text",
+    help="Output format.",
+)
+@click.option(
+    "--internal-only",
+    is_flag=True,
+    help="Hide edges to external (third-party / stdlib) modules.",
+)
+def graph(path: Path, fmt: str, internal_only: bool) -> None:
+    """Build the import graph for a Python project rooted at PATH."""
+    g = _load_graph(path, internal_only=internal_only)
+
+    if fmt == "json":
+        click.echo(json.dumps(_graph_to_dict(g), indent=2, sort_keys=True))
+    elif fmt == "dot":
+        click.echo(_graph_to_dot(g))
+    else:
+        click.echo(_graph_to_text(g))
+
+    if g.graph.get("parse_errors"):
+        click.echo(
+            f"\n[archy] {len(g.graph['parse_errors'])} file(s) had parse errors "
+            "(partial trees were used). Run with --format json to see which.",
+            err=True,
+        )
+
+
+@main.command()
+@click.argument("path", type=click.Path(exists=True, file_okay=False, path_type=Path))
+@click.option(
+    "--format",
+    "fmt",
+    type=click.Choice(["text", "json"]),
+    default="text",
+    help="Output format.",
+)
+@click.option(
+    "--internal-only/--all",
+    default=True,
+    help="Restrict cycle detection to internal modules (the default).",
+)
+@click.option(
+    "--min-size",
+    type=int,
+    default=2,
+    show_default=True,
+    help="Minimum SCC size to report.",
+)
+@click.option(
+    "--strict",
+    is_flag=True,
+    help="Exit non-zero if any cycles are found.",
+)
+def cycles(path: Path, fmt: str, internal_only: bool, min_size: int, strict: bool) -> None:
+    """Find import cycles in a Python project rooted at PATH."""
+    g = _load_graph(path, internal_only=internal_only)
+
+    found = find_cycles(g, min_size=min_size)
+
+    if fmt == "json":
+        click.echo(json.dumps(_cycles_to_json(found), indent=2, sort_keys=True))
+    else:
+        click.echo(_cycles_to_text(found, min_size))
+
+    if strict and found:
+        sys.exit(1)
+
+
+@main.command()
+@click.argument(
+    "path",
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+    default=".",
+)
+@click.option(
+    "--config",
+    "config_path",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=None,
+    help="Path to archy.yaml. Discovered from PATH upward if omitted.",
+)
+@click.option(
+    "--format",
+    "fmt",
+    type=click.Choice(["text", "json"]),
+    default="text",
+    help="Output format.",
+)
+def check(path: Path, config_path: Path | None, fmt: str) -> None:
+    """Check the project at PATH against layer rules in archy.yaml.
+
+    Exits 0 if there are no violations, 1 otherwise.
+    """
+    if config_path is None:
+        discovered = discover_config(path)
+        if discovered is None:
+            raise click.ClickException(
+                f"no archy.yaml found near {path}; pass --config or create one at the project root."
+            )
+        config_path = discovered
+
+    try:
+        config = load_config(config_path)
+    except LayerConfigError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    g = build_graph(path)
+    try:
+        violations = find_violations(g, config)
+    except LayerConfigError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    if fmt == "json":
+        click.echo(json.dumps(_violations_to_json(violations), indent=2, sort_keys=True))
+    else:
+        click.echo(_violations_to_text(violations, config_path))
+
+    if violations:
+        sys.exit(1)
+
+
+@main.command()
+@click.argument(
+    "path",
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+    default=".",
+)
+@click.option(
+    "--format",
+    "fmt",
+    type=click.Choice(["text", "json"]),
+    default="text",
+    help="Output format.",
+)
+@click.option(
+    "--internal-only/--all",
+    default=True,
+    help="Restrict scoring to internal modules (default).",
+)
+@click.option(
+    "--record",
+    is_flag=True,
+    help="Append this score to .archy/history.jsonl for archy trend.",
+)
+@click.option(
+    "--strict",
+    is_flag=True,
+    help=(
+        "Compare against the most recent recorded score; exit 1 if the overall "
+        "score drops by more than --strict-tolerance."
+    ),
+)
+@click.option(
+    "--strict-tolerance",
+    type=float,
+    default=0.02,
+    show_default=True,
+    help="Maximum allowed drop in overall score before --strict fails.",
+)
+def score(
+    path: Path,
+    fmt: str,
+    internal_only: bool,
+    record: bool,
+    strict: bool,
+    strict_tolerance: float,
+) -> None:
+    """Compute the composite architecture quality score for PATH."""
+    g = _load_graph(path, internal_only=internal_only)
+    s = compute_score(g)
+
+    history_path = path / ".archy" / "history.jsonl"
+    # Strict reads BEFORE recording so the comparison is against the truly
+    # previous run rather than the row we are about to append.
+    gate = _gate_against_history(s, history_path) if strict else None
+
+    if fmt == "json":
+        payload = _score_to_dict(s)
+        if gate is not None:
+            payload["gate"] = _gate_to_dict(gate, strict_tolerance)
+        click.echo(json.dumps(payload, indent=2, sort_keys=True))
+    else:
+        click.echo(_score_to_text(s))
+        if gate is not None:
+            click.echo("")
+            click.echo(_gate_to_text(gate, strict_tolerance))
+
+    if record:
+        commit, branch = git_metadata(path)
+        row = row_from_score(s, commit=commit, branch=branch)
+        append_history(history_path, row)
+
+    if gate is not None and gate["delta"] is not None and gate["delta"] < -strict_tolerance:
+        sys.exit(1)
+
+
+@main.command()
+@click.argument(
+    "path",
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+    default=".",
+)
+@click.option(
+    "--last",
+    "last_n",
+    type=int,
+    default=10,
+    show_default=True,
+    help="Number of most-recent records to display.",
+)
+@click.option(
+    "--format",
+    "fmt",
+    type=click.Choice(["text", "json"]),
+    default="text",
+    help="Output format.",
+)
+def trend(path: Path, last_n: int, fmt: str) -> None:
+    """Show the archy score trend for PATH (reads .archy/history.jsonl)."""
+    rows = read_history(path / ".archy" / "history.jsonl")
+    if fmt == "json":
+        window = rows[-last_n:] if last_n > 0 else rows
+        click.echo(
+            json.dumps(
+                [
+                    {
+                        "timestamp": r.timestamp,
+                        "commit": r.commit,
+                        "branch": r.branch,
+                        "score": {
+                            "overall": r.overall,
+                            "modularity": r.modularity,
+                            "acyclicity": r.acyclicity,
+                            "depth": r.depth,
+                            "equality": r.equality,
+                        },
+                    }
+                    for r in window
+                ],
+                indent=2,
+                sort_keys=True,
+            )
+        )
+    else:
+        click.echo(render_trend(rows, last_n=last_n))
+
+
+@main.command()
+def mcp() -> None:
+    """Run archy as an MCP server on stdio for AI agent integration."""
+    from archy.mcp import create_server
+
+    create_server().run()
+
+
+def _load_graph(path: Path, *, internal_only: bool) -> nx.DiGraph:
+    g = build_graph(path)
+    if internal_only:
+        external = {n for n, d in g.nodes(data=True) if d.get("external")}
+        g.remove_nodes_from(external)
+    return g
+
+
+def _format_lines(lines: tuple[int, ...]) -> str:
+    label = "lines" if len(lines) > 1 else "line"
+    text = ", ".join(str(n) for n in lines) or "?"
+    return f"({label}: {text})"
+
+
+def _gate_against_history(current: Score, history_path: Path) -> dict:
+    rows = read_history(history_path)
+    if not rows:
+        return {"previous": None, "current": current.overall, "delta": None}
+    previous = rows[-1]
+    return {
+        "previous": previous.overall,
+        "previous_commit": previous.commit,
+        "previous_timestamp": previous.timestamp,
+        "current": current.overall,
+        "delta": current.overall - previous.overall,
+    }
+
+
+def _gate_to_dict(gate: dict, tolerance: float) -> dict:
+    delta = gate["delta"]
+    return {
+        "previous": gate["previous"],
+        "current": gate["current"],
+        "delta": delta,
+        "tolerance": tolerance,
+        "passed": delta is None or delta >= -tolerance,
+    }
+
+
+def _gate_to_text(gate: dict, tolerance: float) -> str:
+    if gate["delta"] is None:
+        return (
+            "# strict: no prior score recorded; nothing to compare. "
+            "Pass `--record` to seed the baseline."
+        )
+    delta = gate["delta"]
+    direction = "improved" if delta >= 0 else "dropped"
+    verdict = "PASS" if delta >= -tolerance else "FAIL"
+    prev_label = (gate.get("previous_commit") or "?")[:7]
+    return (
+        f"# strict: {verdict}  "
+        f"{gate['previous']:.3f} ({prev_label}) -> {gate['current']:.3f}  "
+        f"({direction} {delta:+.3f}, tolerance {tolerance:.3f})"
+    )
+
+
+def _score_to_dict(s: Score) -> dict:
+    return {
+        "overall": s.overall,
+        "components": {
+            "modularity": s.modularity,
+            "acyclicity": s.acyclicity,
+            "depth": s.depth,
+            "equality": s.equality,
+        },
+        "inputs": {
+            "module_count": s.inputs.module_count,
+            "edge_count": s.inputs.edge_count,
+            "cycle_count": s.inputs.cycle_count,
+            "max_depth": s.inputs.max_depth,
+            "community_count": s.inputs.community_count,
+            "raw_modularity": s.inputs.raw_modularity,
+            "raw_gini": s.inputs.raw_gini,
+        },
+    }
+
+
+def _score_to_text(s: Score) -> str:
+    lines = [
+        f"# archy score: {s.overall:.3f}",
+        f"modularity:  {s.modularity:.3f}  "
+        f"({s.inputs.community_count} communities, raw Q={s.inputs.raw_modularity:.3f})",
+        f"acyclicity:  {s.acyclicity:.3f}  ({s.inputs.cycle_count} cycles)",
+        f"depth:       {s.depth:.3f}  (max depth {s.inputs.max_depth})",
+        f"equality:    {s.equality:.3f}  (Gini={s.inputs.raw_gini:.3f})",
+        f"# graph: {s.inputs.module_count} modules, {s.inputs.edge_count} edges",
+    ]
+    return "\n".join(lines)
+
+
+def _violations_to_json(violations: list[Violation]) -> list[dict]:
+    return [
+        {
+            "rule": {"from": v.rule.from_layer, "to": v.rule.to_layer},
+            "source": v.source,
+            "target": v.target,
+            "lines": list(v.lines),
+        }
+        for v in violations
+    ]
+
+
+def _violations_to_text(violations: list[Violation], config_path: Path) -> str:
+    if not violations:
+        return f"# No layer violations (config: {config_path})."
+    lines = [f"# {len(violations)} layer violation(s) (config: {config_path})"]
+    current_rule: tuple[str, str] | None = None
+    for v in violations:
+        rule_pair = (v.rule.from_layer, v.rule.to_layer)
+        if rule_pair != current_rule:
+            lines.append(f"\n{v.rule.from_layer} -> {v.rule.to_layer} (forbidden):")
+            current_rule = rule_pair
+        lines.append(f"  {v.source} -> {v.target}  {_format_lines(v.lines)}")
+    return "\n".join(lines)
+
+
+def _cycles_to_json(cycles: list[Cycle]) -> list[dict]:
+    return [
+        {
+            "modules": list(c.modules),
+            "edges": [
+                {"source": e.source, "target": e.target, "lines": list(e.lines)} for e in c.edges
+            ],
+        }
+        for c in cycles
+    ]
+
+
+def _cycles_to_text(cycles: list[Cycle], min_size: int) -> str:
+    if not cycles:
+        return f"# No cycles found (min_size={min_size})."
+    lines = [f"# {len(cycles)} cycle(s) found"]
+    for c in cycles:
+        lines.append(f"\nCycle of {len(c.modules)} module(s):")
+        for m in c.modules:
+            lines.append(f"  - {m}")
+        lines.append("Edges:")
+        for e in c.edges:
+            lines.append(f"  {e.source} -> {e.target}  {_format_lines(e.lines)}")
+    return "\n".join(lines)
+
+
+def _graph_to_dict(g: nx.DiGraph) -> dict:
+    return {
+        "root": g.graph.get("root"),
+        "parse_errors": list(g.graph.get("parse_errors", ())),
+        "nodes": [{"id": n, **d} for n, d in sorted(g.nodes(data=True))],
+        "edges": [
+            {"source": u, "target": v, **d}
+            for u, v, d in sorted(g.edges(data=True), key=lambda e: (e[0], e[1]))
+        ],
+    }
+
+
+def _graph_to_dot(g: nx.DiGraph) -> str:
+    lines = ["digraph imports {", '  rankdir="LR";']
+    for n, d in sorted(g.nodes(data=True)):
+        style = ' style="dashed" color="gray"' if d.get("external") else ""
+        lines.append(f'  "{n}"[{style.strip()}];')
+    for u, v in sorted(g.edges()):
+        lines.append(f'  "{u}" -> "{v}";')
+    lines.append("}")
+    return "\n".join(lines)
+
+
+def _graph_to_text(g: nx.DiGraph) -> str:
+    internal = sorted(n for n, d in g.nodes(data=True) if not d.get("external"))
+    lines = [f"# {len(internal)} internal module(s), {g.number_of_edges()} import edge(s)"]
+    for n in internal:
+        lines.append(f"{n}")
+        for t in sorted(g.successors(n)):
+            marker = "ext" if g.nodes[t].get("external") else "int"
+            lines.append(f"  -> [{marker}] {t}")
+    return "\n".join(lines)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

archy/cycles.py

@@ -0,0 +1,59 @@
+"""Strongly-connected-component cycle detection over an import graph."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import networkx as nx
+
+
+@dataclass(frozen=True)
+class CycleEdge:
+    source: str
+    target: str
+    lines: tuple[int, ...]
+
+
+@dataclass(frozen=True)
+class Cycle:
+    modules: tuple[str, ...]
+    edges: tuple[CycleEdge, ...]
+
+
+def find_cycles(graph: nx.DiGraph, *, min_size: int = 2) -> list[Cycle]:
+    """Return cycles in the graph, sorted largest-first then by qualname.
+
+    A cycle is either a strongly-connected component of size >= min_size or
+    a singleton SCC whose only node has a self-edge. Self-loops are always
+    real cycles (a module importing itself), so we report them regardless
+    of min_size; the gate only suppresses incidental singletons (DAG nodes
+    that happen to be their own SCC because they have no inbound mutual
+    relationship).
+    """
+    cycles: list[Cycle] = []
+    for component in nx.strongly_connected_components(graph):
+        size = len(component)
+        if size == 1:
+            node = next(iter(component))
+            if not graph.has_edge(node, node):
+                continue
+        elif size < min_size:
+            continue
+        modules = tuple(sorted(component))
+        component_set = set(component)
+        edges: list[CycleEdge] = []
+        for u in modules:
+            for v in graph.successors(u):
+                if v in component_set:
+                    data = graph[u][v]
+                    edges.append(
+                        CycleEdge(
+                            source=u,
+                            target=v,
+                            lines=tuple(data.get("lines", ())),
+                        )
+                    )
+        edges.sort(key=lambda e: (e.source, e.target))
+        cycles.append(Cycle(modules=modules, edges=tuple(edges)))
+    cycles.sort(key=lambda c: (-len(c.modules), c.modules[0]))
+    return cycles