oxn 0.1.0__py3-none-any.whl

oxn/__init__.py

@@ -0,0 +1,10 @@
+"""OXN -- a local architecture and quality gatekeeper for LLM coding agents.
+
+This module is imported by every entry point, including the PostToolUse hook that runs
+after every agent edit. Keep it free of imports: see ADR-0002 for the latency budget
+(p95 <= 200 ms per file, of which a bare interpreter already costs ~15 ms).
+"""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

oxn/__main__.py

@@ -0,0 +1,16 @@
+"""Run OXN as a module: ``python -m oxn``.
+
+Equivalent to the ``oxn`` console script, and useful wherever that script is not on
+``PATH`` -- an unactivated virtualenv, a hook whose environment you do not control, ``uv
+run``, or a CI step that only knows an interpreter path.
+
+Kept deliberately thin. The PostToolUse hook may invoke OXN this way, so this module must
+respect the same rule as :mod:`oxn.cli`: **nothing heavy at import time.**
+``tests/test_import_guard.py`` enforces it for both entry points.
+"""
+
+from __future__ import annotations
+
+from oxn.cli import main
+
+main()

oxn/_app.py

@@ -0,0 +1,470 @@
+"""The human-facing typer application.
+
+Imported lazily by :func:`oxn.cli.main`, never by the hook fast path. Anything that is
+pleasant for a person and expensive for a machine belongs here.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import typer
+
+from oxn import __version__
+
+app = typer.Typer(
+    name="oxn",
+    help="Local architecture and quality gatekeeper for LLM coding agents.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+if TYPE_CHECKING:  # pragma: no cover
+    from rich.console import Console
+
+
+def _console() -> Console:
+    from rich.console import Console
+
+    return Console()
+
+
+@app.command()
+def version() -> None:
+    """Print the OXN version."""
+    _console().print(f"oxn {__version__}")
+
+
+@app.command()
+def check(
+    paths: list[str] = typer.Argument(None, help="Files or directories to check."),
+    json_output: bool = typer.Option(False, "--json", help="Machine-readable output."),
+    deep: bool = typer.Option(
+        False, "--deep", help="Also check repository-scoped contracts. Too slow for a hook."
+    ),
+    no_baseline: bool = typer.Option(
+        False, "--no-baseline", help="Ignore .oxn/baseline.json and report every violation."
+    ),
+) -> None:
+    """Check files against the project's architectural and quality invariants.
+
+    The ``--json`` form is dispatched by :mod:`oxn.cli` before typer is ever imported, so
+    this function is only reached on the human path.
+    """
+    from oxn.check import render, run_check
+    from oxn.config import ConfigError
+
+    console = _console()
+    try:
+        report = run_check(paths or ["."], deep=deep, use_baseline=not no_baseline)
+    except ConfigError as error:
+        console.print(f"[red]oxn.yaml[/red]: {error}")
+        raise typer.Exit(1) from error
+
+    if json_output:
+        import json
+
+        console.print_json(json.dumps(report.as_dict()))
+    else:
+        render(report, console)
+    raise typer.Exit(report.exit_code)
+
+
+@app.command()
+def baseline(
+    paths: list[str] = typer.Argument(None, help="Files or directories to record."),
+    deep: bool = typer.Option(False, "--deep", help="Include repository-scoped contracts."),
+) -> None:
+    """Record today's violations as accepted debt, so only *new* ones fail.
+
+    The ratchet, not an amnesty: a recorded violation stops failing the build, but the same
+    violation getting worse starts failing it again, and anything new fails immediately.
+    This is what makes `oxn check` adoptable on a repository that predates it.
+    """
+    from oxn.check import run_check, write_baseline
+    from oxn.config import Config, ConfigError
+
+    console = _console()
+    try:
+        settings = Config.load()
+        report = run_check(paths or ["."], config=settings, deep=deep, use_baseline=False)
+    except ConfigError as error:
+        console.print(f"[red]oxn.yaml[/red]: {error}")
+        raise typer.Exit(1) from error
+
+    if report.errors:
+        for path, problem in report.errors.items():
+            console.print(f"[red]error[/red] {path}: {problem}")
+        raise typer.Exit(1)
+
+    recorded = write_baseline(report, settings.baseline_path)
+    where = settings.baseline_path.relative_to(settings.root)
+    console.print(f"recorded [bold]{recorded}[/bold] violation(s) as accepted debt in {where}")
+    console.print("[dim]new violations, and these getting worse, will still fail[/dim]")
+
+
+@app.command()
+def init(
+    no_hook: bool = typer.Option(
+        False, "--no-hook", help="Write config and docs but do not install the hook."
+    ),
+    no_mcp: bool = typer.Option(
+        False, "--no-mcp", help="Do not wire the MCP server into .mcp.json."
+    ),
+    github: bool = typer.Option(
+        False, "--github", help="Also write the `@oxn` pull-request review workflow."
+    ),
+) -> None:
+    """Wire OXN into this repository. Additive and idempotent -- run it twice safely.
+
+    Nothing is overwritten. `oxn.yaml` is written only if absent, the `CLAUDE.md` section
+    lives between markers, and existing `.claude/settings.json` and `.mcp.json` files are
+    merged rather than replaced.
+    """
+    from oxn.init import run_init
+
+    console = _console()
+    report = run_init(with_hook=not no_hook, with_mcp=not no_mcp, with_github=github)
+    for label, paths in (
+        ("created", report.created),
+        ("updated", report.updated),
+        ("unchanged", report.unchanged),
+    ):
+        for path in paths:
+            colour = {"created": "green", "updated": "cyan"}.get(label, "dim")
+            console.print(f"[{colour}]{label:9}[/{colour}] {path}")
+    for note in report.notes:
+        console.print(f"[yellow]note[/yellow]      {note}")
+    console.print(
+        "\n[dim]next: `oxn check` to see where you stand, `oxn baseline` to accept it[/dim]"
+    )
+
+
+@app.command()
+def calibration(
+    json_output: bool = typer.Option(False, "--json", help="Machine-readable output."),
+) -> None:
+    """List every tunable threshold with the evidence behind it.
+
+    A number with no stated provenance is folklore, and folklore is what makes developers
+    distrust a gate. This is also the surface P10's calibration work optimises over.
+    """
+    from oxn.calibration import gate_status, summary
+    from oxn.calibration import parameters as _parameters
+    from oxn.config import Config
+
+    console = _console()
+    report = summary()
+    active = gate_status(Config.load(Path.cwd()))
+    report["disabled"] = sorted(name for name, on in active.items() if not on)
+    if json_output:
+        import json
+
+        console.print_json(json.dumps(report))
+        return
+
+    for parameter in _parameters():
+        marker = (
+            "[yellow]provisional[/yellow]" if parameter.is_provisional else "[green]fitted[/green]"
+        )
+        state = "" if active.get(parameter.name, True) else "  [red]off in this project[/red]"
+        console.print(
+            f"[bold]{parameter.name}[/bold] = {parameter.value:g}  "
+            f"{marker} {parameter.evidence.value} n={parameter.observations}{state}"
+        )
+        console.print(f"  [dim]{parameter.provenance}[/dim]")
+        if parameter.fit_when:
+            console.print(f"  [dim]fit when: {parameter.fit_when}[/dim]")
+    console.print(f"\n[dim]{report['provisional']}/{report['total']} provisional[/dim]")
+    console.print(f"[dim]{report['note']}[/dim]")
+
+
+@app.command()
+def parse(
+    paths: list[str] = typer.Argument(None, help="Files or directories to parse."),
+    json_output: bool = typer.Option(False, "--json", help="Machine-readable output."),
+    force: bool = typer.Option(False, "--force", help="Ignore the cache and re-parse."),
+    stats: bool = typer.Option(False, "--stats", help="Show cache totals instead of entities."),
+) -> None:
+    """Parse sources into the code graph and report what was built.
+
+    A debugging surface for the parse layer: it shows the containment skeleton the metric
+    engine will read, and whether a run hit the cache.
+    """
+    from oxn.render import Output
+    from oxn.report import run_parse
+
+    run_parse(
+        paths or ["."],
+        Output(console=None if json_output else _console()),
+        force=force,
+        stats_only=stats,
+    )
+
+
+@app.command()
+def metrics(
+    paths: list[str] = typer.Argument(None, help="Files or directories to measure."),
+    json_output: bool = typer.Option(False, "--json", help="Machine-readable output."),
+    sort_by: str = typer.Option("cognitive_complexity", "--sort-by", help="Metric to rank by."),
+    limit: int = typer.Option(20, "--limit", help="How many entities to show."),
+    explain: bool = typer.Option(
+        False, "--explain", help="Show the increment trail for the worst offender."
+    ),
+) -> None:
+    """Rank code by a Tier-1 metric.
+
+    Every point of a cognitive-complexity score can be traced to a line and a reason:
+    ``oxn metrics --explain`` prints that trail.
+    """
+    from oxn.render import Output
+    from oxn.report import run_metrics
+
+    run_metrics(
+        paths or ["."],
+        Output(console=None if json_output else _console()),
+        sort_by=sort_by,
+        limit=limit,
+        explain=explain,
+    )
+
+
+@app.command()
+def volume(
+    paths: list[str] = typer.Argument(None, help="Files or directories to analyse."),
+    json_output: bool = typer.Option(False, "--json", help="Machine-readable output."),
+    no_history: bool = typer.Option(False, "--no-history", help="Skip git history."),
+) -> None:
+    """Report duplication, verbosity, structural erosion and hotspots.
+
+    These are the signals agent-written code degrades: volume correlates with
+    architectural decay where prompt specificity does not.
+    """
+    from oxn.render import Output
+    from oxn.report import run_volume
+
+    run_volume(
+        paths or ["."],
+        Output(console=None if json_output else _console()),
+        include_history=not no_history,
+    )
+
+
+@app.command()
+def arch(
+    paths: list[str] = typer.Argument(None, help="Files or directories to analyse."),
+    json_output: bool = typer.Option(False, "--json", help="Machine-readable output."),
+    granularity: str = typer.Option(
+        "directory", "--by", help="Component granularity: directory | file | top."
+    ),
+    show_unresolved: bool = typer.Option(
+        False, "--unresolved", help="List imports that could not be resolved."
+    ),
+) -> None:
+    """Report the dependency graph: cycles, Martin metrics, Lakos levels, smells.
+
+    Report-path only. Building the graph compares every file against every other, so it
+    never runs on the hook's per-edit budget.
+    """
+    from oxn.render import Output
+    from oxn.report import run_arch
+
+    run_arch(
+        paths or ["."],
+        Output(console=None if json_output else _console()),
+        granularity=granularity,
+        show_unresolved=show_unresolved,
+    )
+
+
+@app.command()
+def index(
+    paths: list[str] = typer.Argument(None, help="Directory to index."),
+    language: str = typer.Option("python", "--language", help="Language to index."),
+    json_output: bool = typer.Option(False, "--json", help="Machine-readable output."),
+    reuse: str = typer.Option(
+        "", "--index-file", help="Ingest an existing .scip file instead of generating one."
+    ),
+) -> None:
+    """Build a SCIP index and merge compiler-grade symbols into the graph.
+
+    This is resolution rung L2 (ADR-0002): it makes coupling and call-graph metrics exact
+    rather than heuristic. It needs a per-language indexer, which OXN detects but never
+    installs -- run `oxn doctor` to see what is available.
+    """
+    from oxn.render import Output
+    from oxn.report import run_index
+
+    run_index(
+        paths or ["."],
+        Output(console=None if json_output else _console()),
+        language=language,
+        index_file=reuse or None,
+    )
+
+
+@app.command()
+def calls(
+    paths: list[str] = typer.Argument(None, help="Files or directories to analyse."),
+    json_output: bool = typer.Option(False, "--json", help="Machine-readable output."),
+    limit: int = typer.Option(20, "--limit", help="How many rows to show."),
+) -> None:
+    """Fan-in, fan-out, recursion and dead-code candidates over the call graph.
+
+    Needs L2. OXN recovers call edges from a SCIP index and never invents them from names,
+    so on a tree that has not been indexed this says it has no call graph rather than
+    reporting an empty one -- see `oxn index`.
+    """
+    from oxn.calls import run_calls
+    from oxn.render import Output
+
+    run_calls(
+        paths or ["."],
+        Output(console=None if json_output else _console()),
+        limit=limit,
+    )
+
+
+@app.command()
+def review(
+    base: str = typer.Option("origin/main", "--base", help="Ref the pull request targets."),
+    head: str = typer.Option("HEAD", "--head", help="Ref under review."),
+    json_output: bool = typer.Option(False, "--json", help="Machine-readable output."),
+    write: str = typer.Option(
+        "", "--write", help="Backend that turns the measurement into prose: `ollama`."
+    ),
+    model: str = typer.Option("", "--model", help="Model for `--write`."),
+) -> None:
+    """Measure what a pull request changed, and optionally write the comment.
+
+    Without `--write` this prints the measurement and nothing else, which is the half OXN is
+    sure about. With it, a model turns the measurement into review prose -- and any comment
+    stating a number the measurement does not contain is **refused rather than posted**.
+
+    This never gates. The CI job running `oxn check` already does, and two gates disagreeing
+    about one pull request is worse than one gate.
+    """
+    from oxn.render import Output
+    from oxn.report import run_review_report
+
+    run_review_report(
+        base,
+        head,
+        Output(console=None if json_output else _console()),
+        write=write,
+        model=model,
+    )
+
+
+@app.command()
+def classes(
+    paths: list[str] = typer.Argument(None, help="Files or directories to analyse."),
+    json_output: bool = typer.Option(False, "--json", help="Machine-readable output."),
+    sort_by: str = typer.Option(
+        "lcom_star", "--sort-by", help="lcom_star | lcom4 | wmc | cbo | rfc"
+    ),
+    limit: int = typer.Option(20, "--limit", help="How many classes to show."),
+) -> None:
+    """Report class cohesion (LCOM) and coupling (the CK suite).
+
+    These are the metrics that detect the "Modular Mirage" -- file-level modularity with no
+    semantic cohesion -- which is the documented signature of agent-written code.
+    """
+    from oxn.render import Output
+    from oxn.report import run_classes
+
+    run_classes(
+        paths or ["."],
+        Output(console=None if json_output else _console()),
+        sort_by=sort_by,
+        limit=limit,
+    )
+
+
+@app.command()
+def health(
+    paths: list[str] = typer.Argument(None, help="Files or directories to report on."),
+    json_output: bool = typer.Option(False, "--json", help="Machine-readable output."),
+    limit: int = typer.Option(10, "--limit", help="Entities to name per profile."),
+) -> None:
+    """Risk profiles: how much of the code is over budget, and which code.
+
+    The informational output of `docs/metrics.md` section 10.1 -- it never blocks, and it
+    reports no single score. Every share names the entities that carry it, because a number
+    on its own is not something an agent or a person can act on.
+    """
+    from oxn.health import run_health
+    from oxn.render import Output
+
+    run_health(
+        paths or ["."],
+        Output(console=None if json_output else _console()),
+        limit=limit,
+    )
+
+
+@app.command()
+def doctor() -> None:
+    """Report the environment OXN found: grammars, toolchains, and indexers."""
+    from oxn.doctor import run_doctor
+
+    run_doctor(_console())
+
+
+@app.command()
+def context(
+    task: str = typer.Argument(..., help="What you are about to do, in your own words."),
+    files: list[str] = typer.Option(
+        None, "--file", "-f", help="Files the task is about. Scope beats wording (ADR-0006)."
+    ),
+    limit: int = typer.Option(0, "--limit", help="Constraints to show; 0 uses the budget."),
+    json_output: bool = typer.Option(False, "--json", help="The bundle as typed JSON."),
+) -> None:
+    """Show the constraints that govern a task -- ranked, capped, and never a gate.
+
+    This is the human view of what P9's MCP `get_architectural_context` will serve. It
+    cannot pass or fail anything: ADR-0006 keeps retrieval out of the gate entirely.
+    """
+    from oxn import thresholds
+    from oxn.config import Config
+    from oxn.context.bundle import build_bundle
+    from oxn.context.project import load_project
+
+    bundle = build_bundle(
+        load_project(Config.load()),
+        task=task,
+        targets=files or (),
+        limit=limit or thresholds.MAX_BUNDLE_CONSTRAINTS,
+    )
+
+    console = _console()
+    if json_output:
+        console.print_json(bundle.model_dump_json())
+        return
+    for constraint in bundle.constraints:
+        mark = "gated" if constraint.enforced else "prose"
+        console.print(f"[bold]{constraint.statement}[/bold]")
+        console.print(f"  {mark} · {constraint.source} · governs {constraint.governs} file(s)")
+    console.print(f"\n{bundle.omitted} more not shown. {bundle.note}")
+
+
+@app.command()
+def serve(
+    root: str = typer.Option(
+        "", "--root", help="The repository to serve. Defaults to $OXN_ROOT, else discovery."
+    ),
+) -> None:
+    """Speak MCP over stdio, so an agent can ask before it edits.
+
+    The server is also OXN's warm process (ADR-0004): it is alive for the whole session, so
+    "current when the agent asks" costs no daemon. It informs and never enforces -- the gate
+    is the `PostToolUse` hook, and `check_code` here reaches the same verdict without being
+    able to stop anything.
+
+    Wire it with `claude mcp add oxn -- oxn serve`. Nothing is printed: stdout is the wire.
+    """
+    from oxn.server import serve as run_server
+
+    run_server(root=root or None)