ai-code-quality-auditor 0.1.0__py3-none-any.whl

ai_code_quality_auditor-0.1.0.dist-info/METADATA

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: ai-code-quality-auditor
+Version: 0.1.0
+Summary: Empirical Safety Harness for agentic AI coding systems. Scores AI-generated code on 5 metrics across 5 vendor conditions against one fixed spec.
+Author-email: Dominic Rume <dominicrume@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Dominic Rume
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/dominicrume/NEW-enterprise-ai-code-quality-auditor
+Project-URL: Repository, https://github.com/dominicrume/NEW-enterprise-ai-code-quality-auditor
+Project-URL: Issues, https://github.com/dominicrume/NEW-enterprise-ai-code-quality-auditor/issues
+Project-URL: Documentation, https://github.com/dominicrume/NEW-enterprise-ai-code-quality-auditor/tree/main/docs
+Keywords: ai,code-quality,llm,agents,evaluation,claude-code,cursor,sonarcloud,dissertation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: click>=8.1
+Requires-Dist: rich>=13.0
+Requires-Dist: radon>=6.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: bandit>=1.8
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Provides-Extra: notebook
+Requires-Dist: pandas>=2.0; extra == "notebook"
+Requires-Dist: scipy>=1.10; extra == "notebook"
+Requires-Dist: matplotlib>=3.7; extra == "notebook"
+Requires-Dist: jupyter>=1.0; extra == "notebook"
+Provides-Extra: dashboard
+Requires-Dist: flask>=3.0; extra == "dashboard"
+Provides-Extra: recorder
+Requires-Dist: pynput>=1.7; extra == "recorder"
+Provides-Extra: all
+Requires-Dist: pytest>=8.0; extra == "all"
+Requires-Dist: pandas>=2.0; extra == "all"
+Requires-Dist: scipy>=1.10; extra == "all"
+Requires-Dist: matplotlib>=3.7; extra == "all"
+Requires-Dist: jupyter>=1.0; extra == "all"
+Requires-Dist: flask>=3.0; extra == "all"
+Requires-Dist: pynput>=1.7; extra == "all"
+Dynamic: license-file
+
+# AI Code Quality Auditor — the Referee Tool
+
+[![CI](https://github.com/dominicrume/NEW-enterprise-ai-code-quality-auditor/actions/workflows/ci.yml/badge.svg)](https://github.com/dominicrume/NEW-enterprise-ai-code-quality-auditor/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/ai-code-quality-auditor.svg)](https://pypi.org/project/ai-code-quality-auditor/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Live dashboard](https://img.shields.io/badge/live-dashboard-purple)](https://auditor-dashboard.fly.dev)
+
+> An empirical Safety Harness for agentic AI coding systems.
+> Quantifies where AI-assisted development fails at governance, security,
+> and ethical alignment — *before* the code reaches production.
+
+**🟢 Try it in 30 seconds:**
+```bash
+pipx install ai-code-quality-auditor
+auditor --help
+```
+
+**🚀 Or wire it into your CI in 6 lines** (`.github/workflows/auditor.yml`):
+```yaml
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dominicrume/NEW-enterprise-ai-code-quality-auditor@main
+        with:
+          run-id: ${{ github.run_id }}
+          conditions: claude_code,cursor_agent
+```
+
+**📊 Live dashboard:** https://auditor-dashboard.fly.dev *(pending deploy — see below)*
+
+This is the experimental instrument for the MSc dissertation
+**"AI-Assisted Coding Assessment Tool: Evaluating LLM Performance, Governance,
+and Security in an Agent Education System"** (Aston University, MSc AI &
+Business Strategy). The same instrument is the working prototype for the
+PhD extension at the Aston-Capgemini Centre of Excellence for Enterprise AI.
+
+---
+
+## What it does
+Given a fixed specification (the "spec box"), the Auditor:
+1. Runs five experimental conditions against the same task (human control,
+   visualisation→Claude→Replit, Cursor IDE, autonomous agent).
+2. Captures every output and every interaction event.
+3. Scores each result on five empirical metrics: security vulnerability
+   density, cyclomatic complexity, code duplication, hallucination frequency
+   (features outside spec), and keystroke dynamics (correction frequency).
+4. Emits CSV/JSON reports for statistical comparison.
+
+## Quick start
+```bash
+cp .env.example .env
+pip install -e .
+auditor run --spec specs/agent_education_system.yaml --workflow human_control
+auditor report --out data/reports/
+```
+
+## Read in this order
+1. `docs/ARCHITECTURE.md` — how the pieces fit
+2. `docs/METHODOLOGY.md` — how an experiment is run
+3. `docs/METRICS.md` — what each metric means and how it's computed
+4. `docs/ETHICS.md` — GDPR, synthetic data, academic integrity
+5. `docs/DISSERTATION_LINKAGE.md` — which folder serves which proposal section
+6. `docs/ROADMAP.md` — the PhD extension (API security + enterprise risk)
+
+## Principles
+- One analyzer per metric. One adapter per AI workflow. Single responsibility.
+- The spec is data, not code — externalised in `specs/` for reproducibility.
+- Synthetic data only. No PII, no proprietary corporate records, ever.
+- Every analyzer has a test. Green tests = trustable experiment.

ai_code_quality_auditor-0.1.0.dist-info/RECORD

@@ -0,0 +1,39 @@
+ai_code_quality_auditor-0.1.0.dist-info/licenses/LICENSE,sha256=D9Qe54txI-WgF2yA83uPVryQLnTT2fB05ySsIkg3-4Q,1069
+auditor/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+auditor/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+auditor/adapters/antigravity_adapter.py,sha256=yYiUQZM6lh8rd49QlKwvvQ3LFpRwr8D9K1gpd95VGhU,5504
+auditor/adapters/base_adapter.py,sha256=oG3oHBb2CHW1o7Gu2_H7i-4Su8BAqsiXbD4tvGGRyRU,423
+auditor/adapters/claude_code_adapter.py,sha256=YqbTW0HpkhUiYNXEJc4mfyaccmIiaJbLhsRHKyWaEUQ,5916
+auditor/adapters/cursor_agent_adapter.py,sha256=h9-6k_z1fmaBBx_ffyDynYMq112YHM2bZE7WidAoEHs,4777
+auditor/adapters/human_control_adapter.py,sha256=ry4GUSaZxbtUtzfIr_PnFS6FQn7JeZg5M-bD5_yTOS0,4051
+auditor/adapters/human_control_recorder.py,sha256=I8UM2RyvQz_v2E_HugF6IJOYtfRhI0Iq7elq-gN8Ktw,3166
+auditor/adapters/replit_agent_adapter.py,sha256=n951L0o5s6mZrGK9BvedufBHJ6Ew8evhN6z7zbF9Xdw,5579
+auditor/analyzers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+auditor/analyzers/complexity_analyzer.py,sha256=NyEeezTbPG8G3YQuyJSXAcA7ffG4imYrf6XxzMIW7hY,1168
+auditor/analyzers/duplication_analyzer.py,sha256=Kk9JRa9oIXMI6lU8tFBCVERduLwqF2eN2AP6sFstbeY,2098
+auditor/analyzers/hallucination_analyzer.py,sha256=0fd0JZjBNFWzFeFychsCj9RZQO5Ipbo-sVLuk6FdoG0,977
+auditor/analyzers/keystroke_analyzer.py,sha256=G-yq3XAxe-5AwlJdzfYkDpAPAbPyhSlGmQHnp1rp9Nk,516
+auditor/analyzers/manifest_deriver.py,sha256=0H_gKZpLIWBTZj6bTyrMREwsqQ95_PXb9u4PYZomRPE,2398
+auditor/analyzers/security_analyzer.py,sha256=t7oQY2GdqHALCcMuacKy_fR_I9h0zX8HA1ljUH-Gjkk,2397
+auditor/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+auditor/core/cli.py,sha256=0y2VXeAVeEwyc-Z7Lh50B0vlLX793Jnl-_pNKyjAQyw,2408
+auditor/core/config.py,sha256=6julYSA9kD2jw_b5P50aDkHdiDAcPL5qRqvOheQHdK8,581
+auditor/core/experiment.py,sha256=rl0QVSAdg7Ksvz8rEcosxOZ-T1bh-_LFW2mpiH4OQDI,5500
+auditor/core/logger.py,sha256=zL4aflL6h35I0FRJNVKAcnhc89oGDUzU2tVvP643F5E,446
+auditor/core/runner.py,sha256=7YblOlIrxggv018h7_u6_VEDQIP6ca8VOuMDDVLfI_o,1488
+auditor/dashboard/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+auditor/dashboard/app.py,sha256=yz_aYrCxqtER3v67YEPSIzWZ1uRiHAS2Hdv_NCleHJg,6239
+auditor/dashboard/templates/index.html,sha256=OvVnd4CpZ2kCYfmTfZspGjsrmr2cHiSZB0WktbWtORQ,6292
+auditor/dashboard/templates/report.html,sha256=0TydCVQIeHkopZOg_z7tvQrvxu5JB41bshX9vbJnA78,21357
+auditor/governance/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+auditor/governance/compliance_checker.py,sha256=fomnTEicVo2fbIec6yno8t0c4LbntbwyZVb0eSA3Y4w,5969
+auditor/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+auditor/models/audit_result.py,sha256=EB3RRSAsY1c1p-DXRV4zq0aMJ9rFbz5MrQbOek-Png4,645
+auditor/reporting/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+auditor/reporting/csv_reporter.py,sha256=e6ztPRC8zmrVppDHt_bVTxvzNgEDbwfkAAvyqJo6SbM,727
+auditor/reporting/json_reporter.py,sha256=35FS2meVK4g0wErKqfBYe75P3AMNvQMWcgWX0E4-pTw,278
+ai_code_quality_auditor-0.1.0.dist-info/METADATA,sha256=gaxc6z6F8u4kGHaTNpLU0lyeqgmQpKS4umgx3fCIBS8,6899
+ai_code_quality_auditor-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+ai_code_quality_auditor-0.1.0.dist-info/entry_points.txt,sha256=Gxvra13kW5Mg0ra2d7b6_NdEySSjSCNs-hcOS7_NoZM,50
+ai_code_quality_auditor-0.1.0.dist-info/top_level.txt,sha256=8Z_-H3ebzZbnAMChd_M4BQ8AZ7MiD2LX-gwa6p58Xls,8
+ai_code_quality_auditor-0.1.0.dist-info/RECORD,,

ai_code_quality_auditor-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ai_code_quality_auditor-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+auditor = auditor.core.cli:main

ai_code_quality_auditor-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Rume
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ai_code_quality_auditor-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+auditor

auditor/adapters/antigravity_adapter.py

@@ -0,0 +1,139 @@
+"""antigravity adapter — vendor: Google Gemini Antigravity.
+
+Drives the Antigravity agent CLI against the spec, captures its streamed
+agent events, and reads the produced codebase from the work_dir.
+
+Capture contract: see docs/METHODOLOGY.md. Antigravity is agentic, so every
+captured event maps to ``agent_action``.
+"""
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Callable, Iterable
+
+from auditor.adapters.base_adapter import BaseAdapter
+from auditor.core.config import settings
+
+
+_CODE_SUFFIXES = {".py", ".js", ".ts", ".tsx", ".jsx", ".go", ".rs", ".java",
+                  ".rb", ".sql", ".yaml", ".yml", ".toml", ".md"}
+
+Runner = Callable[[str, Path], Iterable[dict]]
+
+
+def _default_runner(prompt: str, work_dir: Path, cli: str = "antigravity",
+                    timeout: int = 600) -> list[dict]:
+    proc = subprocess.run(
+        [cli, "run", "--prompt", prompt, "--format", "jsonl"],
+        cwd=str(work_dir), capture_output=True, text=True,
+        timeout=timeout, check=False,
+    )
+    events: list[dict] = []
+    for line in proc.stdout.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            events.append(json.loads(line))
+        except json.JSONDecodeError:
+            continue
+    return events
+
+
+def _build_prompt(spec: dict) -> str:
+    return (
+        "Build the following specification in the current working directory. "
+        "Implement only the listed features.\n\n"
+        f"SPEC:\n{json.dumps(spec, indent=2)}\n"
+    )
+
+
+def _to_contract_events(raw_events: Iterable[dict]) -> list[dict]:
+    out: list[dict] = []
+    for ev in raw_events:
+        out.append({
+            "type": "agent_action",
+            "subtype": ev.get("kind") or ev.get("type"),
+            "detail": ev.get("phase") or ev.get("status"),
+            "tool": ev.get("tool") or ev.get("action"),
+        })
+    return out
+
+
+def _load_codebase(work_dir: Path) -> dict:
+    work_dir = Path(work_dir)
+    if not work_dir.is_dir():
+        raise FileNotFoundError(f"work_dir not found: {work_dir}")
+    _EXCLUDE_DIRS = {".venv", "venv", "env", "__pycache__", "node_modules",
+                     ".pytest_cache", ".git", "site-packages", "dist", "build",
+                     ".mypy_cache", ".ruff_cache", "egg-info"}
+    files: dict[str, str] = {}
+    for path in sorted(work_dir.rglob("*")):
+        if not path.is_file() or path.name == "manifest.json":
+            continue
+        if path.suffix not in _CODE_SUFFIXES:
+            continue
+        if any(part in _EXCLUDE_DIRS or part.endswith(".egg-info")
+               for part in path.relative_to(work_dir).parts):
+            continue
+        files[path.relative_to(work_dir).as_posix()] = path.read_text(encoding="utf-8")
+    manifest_path = work_dir / "manifest.json"
+    manifest = json.loads(manifest_path.read_text()) if manifest_path.exists() else []
+    return {"files": files, "manifest": manifest}
+
+
+class AntigravityAdapter(BaseAdapter):
+    name = "antigravity"
+
+    def __init__(self, work_dir: str | Path, cli: str = "antigravity",
+                 run_id: str | None = None, raw_root: str | Path = "data/raw",
+                 runner: Runner | None = None, timeout: int = 600,
+                 replay_dir: str | Path | None = None):
+        """
+        replay_dir: if given, skip the CLI and load codebase from this folder
+        plus an interaction log from ``<replay_dir>/log.json``. Use this to
+        score sessions captured manually in the Antigravity web IDE.
+        """
+        self.work_dir = Path(work_dir)
+        self.cli = cli
+        self.run_id = run_id or settings.run_id
+        self.raw_root = Path(raw_root)
+        self.timeout = timeout
+        self.replay_dir = Path(replay_dir) if replay_dir else None
+        self._runner: Runner = runner or (
+            lambda prompt, wd: _default_runner(prompt, wd, cli=self.cli, timeout=self.timeout)
+        )
+
+    def _persist(self, codebase, interaction_log, raw_events) -> Path:
+        dest = self.raw_root / self.run_id / self.name
+        dest.mkdir(parents=True, exist_ok=True)
+        (dest / "codebase.json").write_text(json.dumps(codebase, indent=2))
+        (dest / "interaction_log.json").write_text(json.dumps(interaction_log, indent=2))
+        (dest / "raw_stream.json").write_text(json.dumps(raw_events, indent=2))
+        code_copy = dest / "code"
+        if code_copy.exists():
+            shutil.rmtree(code_copy)
+        source = self.replay_dir if self.replay_dir is not None else self.work_dir
+        if source.exists():
+            shutil.copytree(source, code_copy)
+        return dest
+
+    def generate(self, spec: dict) -> tuple[dict, list[dict]]:
+        if self.replay_dir is not None:
+            codebase = _load_codebase(self.replay_dir)
+            log_path = self.replay_dir / "log.json"
+            interaction_log = (
+                json.loads(log_path.read_text()) if log_path.exists() else []
+            )
+            self._persist(codebase, interaction_log, raw_events=[])
+            return codebase, interaction_log
+        self.work_dir.mkdir(parents=True, exist_ok=True)
+        prompt = _build_prompt(spec)
+        raw_events = list(self._runner(prompt, self.work_dir))
+        interaction_log = _to_contract_events(raw_events)
+        codebase = _load_codebase(self.work_dir)
+        self._persist(codebase, interaction_log, raw_events)
+        return codebase, interaction_log

auditor/adapters/base_adapter.py

@@ -0,0 +1,14 @@
+"""Base contract every AI workflow adapter implements."""
+from abc import ABC, abstractmethod
+
+
+class BaseAdapter(ABC):
+    name: str
+
+    @abstractmethod
+    def generate(self, spec: dict) -> tuple[dict, list[dict]]:
+        """Return (codebase, interaction_log).
+
+        codebase: {"files": {path: content}, "manifest": [feature_ids...]}
+        interaction_log: list of events with at minimum a "type" key.
+        """

auditor/adapters/claude_code_adapter.py

@@ -0,0 +1,151 @@
+"""claude_code adapter — vendor: Anthropic Claude Code (see docs/METHODOLOGY.md).
+
+Drives the Claude Code CLI in non-interactive ("-p") mode against the spec,
+captures the streamed agent events, and reads back the final codebase from
+the working directory the CLI wrote into.
+
+All vendor-specific glue lives in this file; the engine remains neutral.
+
+Capture contract (docs/METHODOLOGY.md):
+  codebase        : {"files": {path: content}, "manifest": [feature_ids]}
+  interaction_log : list of events, each with at minimum {"type": str}
+                    where type ∈ {keystroke, backspace, delete, agent_action}.
+
+Since Claude Code is an agentic system (no human keystrokes), every captured
+event maps to ``agent_action`` with vendor-specific detail preserved in
+sibling keys (``subtype``, ``tool``, etc.) for downstream forensics.
+"""
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Callable, Iterable
+
+from auditor.adapters.base_adapter import BaseAdapter
+from auditor.core.config import settings
+
+
+_CODE_SUFFIXES = {".py", ".js", ".ts", ".tsx", ".jsx", ".go", ".rs", ".java",
+                  ".rb", ".sql", ".yaml", ".yml", ".toml", ".md"}
+
+
+Runner = Callable[[str, Path], Iterable[dict]]
+"""Signature: runner(prompt, work_dir) -> iterable of raw Claude Code events."""
+
+
+def _default_runner(prompt: str, work_dir: Path, cli: str = "claude",
+                    timeout: int = 600) -> list[dict]:
+    """Invoke the real Claude Code CLI and parse its streaming JSON output."""
+    proc = subprocess.run(
+        [cli, "-p", prompt, "--output-format", "stream-json", "--verbose",
+         "--dangerously-skip-permissions"],
+        cwd=str(work_dir),
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+        check=False,
+    )
+    events: list[dict] = []
+    for line in proc.stdout.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            events.append(json.loads(line))
+        except json.JSONDecodeError:
+            continue
+    return events
+
+
+def _build_prompt(spec: dict) -> str:
+    """Render the spec dict into a single prompt string for the agent."""
+    return (
+        "You are implementing the following specification. Build the code in "
+        "the current working directory. Stay strictly within the listed "
+        "features — do not invent extras.\n\n"
+        f"SPEC:\n{json.dumps(spec, indent=2)}\n"
+    )
+
+
+def _to_contract_events(raw_events: Iterable[dict]) -> list[dict]:
+    """Map every raw Claude Code event to a capture-contract event.
+
+    All Claude Code events are agent actions; we preserve the original
+    payload's identifying fields (``type``, ``subtype``, ``tool_name``) under
+    new keys so analyzers can interrogate detail without leaking the vendor
+    schema into the contract.
+    """
+    out: list[dict] = []
+    for ev in raw_events:
+        out.append({
+            "type": "agent_action",
+            "subtype": ev.get("type"),
+            "detail": ev.get("subtype"),
+            "tool": ev.get("tool_name") or ev.get("name"),
+        })
+    return out
+
+
+def _load_codebase(work_dir: Path) -> dict:
+    work_dir = Path(work_dir)
+    if not work_dir.is_dir():
+        raise FileNotFoundError(f"work_dir not found: {work_dir}")
+    _EXCLUDE_DIRS = {".venv", "venv", "env", "__pycache__", "node_modules",
+                     ".pytest_cache", ".git", "site-packages", "dist", "build",
+                     ".mypy_cache", ".ruff_cache", "egg-info"}
+    files: dict[str, str] = {}
+    for path in sorted(work_dir.rglob("*")):
+        if not path.is_file():
+            continue
+        if path.name == "manifest.json":
+            continue
+        if path.suffix not in _CODE_SUFFIXES:
+            continue
+        rel = path.relative_to(work_dir).as_posix()
+        if any(part in _EXCLUDE_DIRS or part.endswith(".egg-info")
+               for part in Path(rel).parts):
+            continue
+        files[rel] = path.read_text(encoding="utf-8")
+    manifest_path = work_dir / "manifest.json"
+    manifest = json.loads(manifest_path.read_text()) if manifest_path.exists() else []
+    return {"files": files, "manifest": manifest}
+
+
+class ClaudeCodeAdapter(BaseAdapter):
+    name = "claude_code"
+
+    def __init__(self, work_dir: str | Path, cli: str = "claude",
+                 run_id: str | None = None, raw_root: str | Path = "data/raw",
+                 runner: Runner | None = None, timeout: int = 600):
+        self.work_dir = Path(work_dir)
+        self.cli = cli
+        self.run_id = run_id or settings.run_id
+        self.raw_root = Path(raw_root)
+        self.timeout = timeout
+        self._runner: Runner = runner or (
+            lambda prompt, wd: _default_runner(prompt, wd, cli=self.cli, timeout=self.timeout)
+        )
+
+    def _persist(self, codebase: dict, interaction_log: list[dict],
+                 raw_events: list[dict]) -> Path:
+        dest = self.raw_root / self.run_id / self.name
+        dest.mkdir(parents=True, exist_ok=True)
+        (dest / "codebase.json").write_text(json.dumps(codebase, indent=2))
+        (dest / "interaction_log.json").write_text(json.dumps(interaction_log, indent=2))
+        (dest / "raw_stream.json").write_text(json.dumps(raw_events, indent=2))
+        code_copy = dest / "code"
+        if code_copy.exists():
+            shutil.rmtree(code_copy)
+        shutil.copytree(self.work_dir, code_copy)
+        return dest
+
+    def generate(self, spec: dict) -> tuple[dict, list[dict]]:
+        self.work_dir.mkdir(parents=True, exist_ok=True)
+        prompt = _build_prompt(spec)
+        raw_events = list(self._runner(prompt, self.work_dir))
+        interaction_log = _to_contract_events(raw_events)
+        codebase = _load_codebase(self.work_dir)
+        self._persist(codebase, interaction_log, raw_events)
+        return codebase, interaction_log

auditor/adapters/cursor_agent_adapter.py

@@ -0,0 +1,124 @@
+"""cursor_agent adapter — vendor: Cursor (agent mode CLI).
+
+Drives ``cursor-agent`` non-interactively against the spec, captures the
+streamed agent events, and reads the produced codebase from the work_dir.
+
+Capture contract: see docs/METHODOLOGY.md. Cursor is agentic, so every
+captured event maps to ``agent_action`` with vendor detail preserved as
+sibling keys (``subtype``, ``tool``).
+"""
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Callable, Iterable
+
+from auditor.adapters.base_adapter import BaseAdapter
+from auditor.core.config import settings
+
+
+_CODE_SUFFIXES = {".py", ".js", ".ts", ".tsx", ".jsx", ".go", ".rs", ".java",
+                  ".rb", ".sql", ".yaml", ".yml", ".toml", ".md"}
+
+Runner = Callable[[str, Path], Iterable[dict]]
+
+
+def _default_runner(prompt: str, work_dir: Path, cli: str = "cursor-agent",
+                    timeout: int = 600) -> list[dict]:
+    proc = subprocess.run(
+        [cli, "-p", "--output-format", "stream-json", "--force",
+         "--model", "auto", prompt],
+        cwd=str(work_dir), capture_output=True, text=True,
+        timeout=timeout, check=False,
+    )
+    events: list[dict] = []
+    for line in proc.stdout.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            events.append(json.loads(line))
+        except json.JSONDecodeError:
+            continue
+    return events
+
+
+def _build_prompt(spec: dict) -> str:
+    return (
+        "Implement the specification below in the current working directory. "
+        "Do not introduce features outside the listed set.\n\n"
+        f"SPEC:\n{json.dumps(spec, indent=2)}\n"
+    )
+
+
+def _to_contract_events(raw_events: Iterable[dict]) -> list[dict]:
+    out: list[dict] = []
+    for ev in raw_events:
+        out.append({
+            "type": "agent_action",
+            "subtype": ev.get("type") or ev.get("event"),
+            "detail": ev.get("subtype") or ev.get("status"),
+            "tool": ev.get("tool") or ev.get("tool_name"),
+        })
+    return out
+
+
+def _load_codebase(work_dir: Path) -> dict:
+    work_dir = Path(work_dir)
+    if not work_dir.is_dir():
+        raise FileNotFoundError(f"work_dir not found: {work_dir}")
+    _EXCLUDE_DIRS = {".venv", "venv", "env", "__pycache__", "node_modules",
+                     ".pytest_cache", ".git", "site-packages", "dist", "build",
+                     ".mypy_cache", ".ruff_cache", "egg-info"}
+    files: dict[str, str] = {}
+    for path in sorted(work_dir.rglob("*")):
+        if not path.is_file() or path.name == "manifest.json":
+            continue
+        if path.suffix not in _CODE_SUFFIXES:
+            continue
+        if any(part in _EXCLUDE_DIRS or part.endswith(".egg-info")
+               for part in path.relative_to(work_dir).parts):
+            continue
+        files[path.relative_to(work_dir).as_posix()] = path.read_text(encoding="utf-8")
+    manifest_path = work_dir / "manifest.json"
+    manifest = json.loads(manifest_path.read_text()) if manifest_path.exists() else []
+    return {"files": files, "manifest": manifest}
+
+
+class CursorAgentAdapter(BaseAdapter):
+    name = "cursor_agent"
+
+    def __init__(self, work_dir: str | Path, cli: str = "cursor-agent",
+                 run_id: str | None = None, raw_root: str | Path = "data/raw",
+                 runner: Runner | None = None, timeout: int = 600):
+        self.work_dir = Path(work_dir)
+        self.cli = cli
+        self.run_id = run_id or settings.run_id
+        self.raw_root = Path(raw_root)
+        self.timeout = timeout
+        self._runner: Runner = runner or (
+            lambda prompt, wd: _default_runner(prompt, wd, cli=self.cli, timeout=self.timeout)
+        )
+
+    def _persist(self, codebase, interaction_log, raw_events) -> Path:
+        dest = self.raw_root / self.run_id / self.name
+        dest.mkdir(parents=True, exist_ok=True)
+        (dest / "codebase.json").write_text(json.dumps(codebase, indent=2))
+        (dest / "interaction_log.json").write_text(json.dumps(interaction_log, indent=2))
+        (dest / "raw_stream.json").write_text(json.dumps(raw_events, indent=2))
+        code_copy = dest / "code"
+        if code_copy.exists():
+            shutil.rmtree(code_copy)
+        shutil.copytree(self.work_dir, code_copy)
+        return dest
+
+    def generate(self, spec: dict) -> tuple[dict, list[dict]]:
+        self.work_dir.mkdir(parents=True, exist_ok=True)
+        prompt = _build_prompt(spec)
+        raw_events = list(self._runner(prompt, self.work_dir))
+        interaction_log = _to_contract_events(raw_events)
+        codebase = _load_codebase(self.work_dir)
+        self._persist(codebase, interaction_log, raw_events)
+        return codebase, interaction_log