codejury 0.1.0__py3-none-any.whl

codejury/providers/retry.py

@@ -0,0 +1,48 @@
+"""RetryProvider -- wrap any Provider, retrying complete() on transient failure.
+
+Real model calls fail intermittently (timeouts, rate limits). This decorator
+retries with linear backoff and re-raises the last error once attempts are
+exhausted. ``sleep`` is injectable so tests do not actually wait.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Callable
+
+from codejury.providers.base import CompletionResult, Message, Provider
+
+
+class RetryProvider(Provider):
+    def __init__(
+        self,
+        inner: Provider,
+        *,
+        max_attempts: int = 3,
+        base_delay: float = 1.0,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        self._inner = inner
+        self._max_attempts = max_attempts
+        self._base_delay = base_delay
+        self._sleep = sleep
+
+    def complete(
+        self,
+        *,
+        system: str,
+        messages: list[Message],
+        model: str,
+        max_tokens: int,
+        cache: bool = False,
+    ) -> CompletionResult:
+        for attempt in range(1, self._max_attempts + 1):
+            try:
+                return self._inner.complete(
+                    system=system, messages=messages, model=model, max_tokens=max_tokens, cache=cache
+                )
+            except Exception:
+                if attempt == self._max_attempts:
+                    raise
+                self._sleep(self._base_delay * attempt)
+        raise AssertionError("unreachable")  # pragma: no cover

codejury/reporting.py

@@ -0,0 +1,114 @@
+"""Render audit results into machine- and human-readable reports.
+
+Input is the per-file ``[(path, AnalysisResult)]`` the audit produces. JSON is
+for tooling; Markdown is for a human reviewer and leads with the issues, then
+shows what was checked and cleared (the "why it's fine" side) and what was
+dismissed.
+"""
+
+from __future__ import annotations
+
+import json
+
+from codejury.domain.observation import Observation
+from codejury.domain.result import AnalysisResult
+
+Results = list[tuple[str, AnalysisResult]]
+
+_SEVERITY_ORDER = {"CRITICAL": 0, "HIGH": 1, "MEDIUM": 2, "LOW": 3, "INFO": 4}
+_CLEARED = ("SECURE", "NOT_PRESENT")
+_PROBLEM_STATUSES = ("VULNERABLE", "PARTIAL")
+
+
+def to_json(results: Results) -> str:
+    payload = {
+        "files": [
+            {
+                "path": path,
+                "error": result.error,
+                "observations": [o.to_dict() for o in result.observations],
+            }
+            for path, result in results
+        ]
+    }
+    return json.dumps(payload, indent=2, ensure_ascii=False)
+
+
+def to_markdown(results: Results) -> str:
+    lines = ["# Security Audit Report", ""]
+    lines += _summary(results)
+    for path, result in results:
+        lines += ["", f"## {path}"]
+        if result.error:
+            lines.append(f"> error: {result.error}")
+
+        problems = sorted((o for o in result.observations if _is_problem(o)), key=_rank)
+        cleared = [o for o in result.observations if o.kind == "verdict" and o.status in _CLEARED]
+        dismissed = [o for o in result.observations if o.kind == "concession"]
+
+        if problems:
+            lines += ["", "### Issues"]
+            for o in problems:
+                lines += _render_problem(o)
+        if cleared:
+            lines += ["", "### Checked and clear"]
+            lines += [f"- {o.status} `{o.capability}`" for o in cleared]
+        if dismissed:
+            lines += ["", "### Dismissed"]
+            lines += [f"- ~~{o.target}~~ — {o.reason}" for o in dismissed]
+        if not result.observations and not result.error:
+            lines += ["", "_no observations_"]
+    return "\n".join(lines)
+
+
+def _summary(results: Results) -> list[str]:
+    vulnerable = cleared = findings = dismissed = 0
+    for _, result in results:
+        for o in result.observations:
+            if o.kind == "verdict":
+                vulnerable += o.status in _PROBLEM_STATUSES
+                cleared += o.status in _CLEARED
+            elif o.kind == "finding":
+                findings += 1
+            elif o.kind == "concession":
+                dismissed += 1
+    return [
+        f"- files audited: {len(results)}",
+        f"- issues: {vulnerable} vulnerable verdict(s), {findings} finding(s)",
+        f"- checked and clear: {cleared}",
+        f"- dismissed: {dismissed}",
+    ]
+
+
+def _is_problem(o: Observation) -> bool:
+    return o.kind == "finding" or (o.kind == "verdict" and o.status in _PROBLEM_STATUSES)
+
+
+def _rank(o: Observation) -> int:
+    if o.kind == "finding":
+        return _SEVERITY_ORDER.get(o.severity, 5)
+    return -1 if o.status == "VULNERABLE" else 4  # vulnerable verdicts float to the top
+
+
+def _render_problem(o: Observation) -> list[str]:
+    if o.kind == "finding":
+        cwe = f" ({o.cwe})" if o.cwe else ""
+        out = [f"- **{o.severity}**{cwe} {o.title}"]
+        if o.description:
+            out.append(f"  - {o.description}")
+    else:
+        matched = ", ".join(o.matched_anti)
+        tag = f" [{matched}]" if matched else ""
+        out = [f"- **{o.status}** `{o.capability}`{tag}"]
+        if o.reasoning:
+            out.append(f"  - {o.reasoning}")
+    return out + _evidence_lines(o.evidence)
+
+
+def _evidence_lines(evidence) -> list[str]:
+    lines = []
+    for e in evidence:
+        location = e.file + (f":{e.line}" if e.line else "")
+        code = f" `{e.code}`" if e.code else ""
+        lines.append(f"  - {location}{code}")
+    return lines

codejury/resources.py

@@ -0,0 +1,13 @@
+"""Locations of the knowledge base bundled inside the installed package.
+
+These are the CLI defaults, resolved relative to the package so they work from
+any working directory once installed. Override them with --capabilities etc.
+"""
+
+from pathlib import Path
+
+_DATA = Path(__file__).resolve().parent / "data"
+
+CAPABILITIES_DIR = _DATA / "capabilities"
+TASKS_DIR = _DATA / "tasks"
+GOLDEN_DIR = _DATA / "golden"

codejury/sources/__init__.py

@@ -0,0 +1,6 @@
+"""codejury.sources -- where code to audit comes from.
+
+Agents never read files directly; they receive CodeArtifacts from a Source. This
+keeps the "any input" axis (diff / file / repo / function) independent from the
+rest of the framework.
+"""

codejury/sources/base.py

@@ -0,0 +1,17 @@
+"""Source ABC.
+
+A Source turns some input (a PR diff, a file, a repo, a function) into a list of
+CodeArtifacts an agent can analyze. Returning a list rather than one artifact
+lets a single source fan out (e.g. one artifact per changed hunk).
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from codejury.domain.artifact import CodeArtifact
+
+
+class Source(ABC):
+    @abstractmethod
+    def list_artifacts(self) -> list[CodeArtifact]: ...

codejury/sources/chunker.py

@@ -0,0 +1,33 @@
+"""Chunker -- split oversized file content so each artifact fits a context budget.
+
+Splits on line boundaries into pieces of at most ``max_chars``. Small content is
+returned unchanged as a single chunk keeping its path; split content gets a
+``path#N`` suffix per chunk. A single line longer than the budget becomes its own
+(over-budget) chunk rather than being cut mid-line.
+"""
+
+from __future__ import annotations
+
+
+class Chunker:
+    def __init__(self, max_chars: int = 8000) -> None:
+        self._max_chars = max_chars
+
+    def split(self, path: str, content: str) -> list[tuple[str, str]]:
+        if len(content) <= self._max_chars:
+            return [(path, content)]
+
+        chunks: list[tuple[str, str]] = []
+        buffer: list[str] = []
+        size = 0
+        index = 1
+        for line in content.splitlines(keepends=True):
+            if buffer and size + len(line) > self._max_chars:
+                chunks.append((f"{path}#{index}", "".join(buffer)))
+                index += 1
+                buffer, size = [], 0
+            buffer.append(line)
+            size += len(line)
+        if buffer:
+            chunks.append((f"{path}#{index}", "".join(buffer)))
+        return chunks

codejury/sources/diff.py

@@ -0,0 +1,69 @@
+"""DiffSource -- turn a unified diff into one CodeArtifact per changed file.
+
+Splits on ``diff --git`` headers (falling back to a single section for a plain
+diff with no git header). The path is taken from the +++ line, then the ---
+line, then the header -- skipping /dev/null so adds and deletes still resolve to
+the real file.
+"""
+
+from __future__ import annotations
+
+from codejury.domain.artifact import CodeArtifact
+from codejury.sources.base import Source
+
+
+class DiffSource(Source):
+    def __init__(self, diff_text: str) -> None:
+        self._diff_text = diff_text
+
+    def list_artifacts(self) -> list[CodeArtifact]:
+        return [
+            CodeArtifact(kind="diff", path=path, content=body)
+            for path, body in _split_by_file(self._diff_text)
+        ]
+
+
+def _split_by_file(diff_text: str) -> list[tuple[str, str]]:
+    if not diff_text.strip():
+        return []
+
+    sections: list[list[str]] = []
+    current: list[str] = []
+    for line in diff_text.splitlines(keepends=True):
+        if line.startswith("diff --git ") and current:
+            sections.append(current)
+            current = []
+        current.append(line)
+    if current:
+        sections.append(current)
+
+    out: list[tuple[str, str]] = []
+    for section in sections:
+        path = _path_for(section)
+        if path:
+            out.append((path, "".join(section)))
+    return out
+
+
+def _path_for(lines: list[str]) -> str:
+    plus = minus = header = None
+    for line in lines:
+        if line.startswith("+++ "):
+            plus = _clean(line[4:])
+        elif line.startswith("--- "):
+            minus = _clean(line[4:])
+        elif line.startswith("diff --git "):
+            parts = line.split()
+            if len(parts) >= 4:
+                header = _clean(parts[3])
+    for candidate in (plus, minus, header):
+        if candidate and candidate != "/dev/null":
+            return candidate
+    return ""
+
+
+def _clean(path: str) -> str:
+    path = path.split("\t")[0].strip()  # drop trailing timestamp from plain `diff -u`
+    if path.startswith(("a/", "b/")):
+        path = path[2:]
+    return path

codejury/sources/function.py

@@ -0,0 +1,35 @@
+"""FunctionSource -- split Python source into one CodeArtifact per function.
+
+Parses the AST and emits an artifact for every function and method (including
+async and nested ones), in source order. Good for deeply auditing one handler at
+a time. The content must be valid Python; a parse failure raises SyntaxError.
+"""
+
+from __future__ import annotations
+
+import ast
+
+from codejury.domain.artifact import CodeArtifact
+from codejury.sources.base import Source
+
+
+class FunctionSource(Source):
+    def __init__(self, code: str, *, path: str = "<source>") -> None:
+        self._code = code
+        self._path = path
+
+    def list_artifacts(self) -> list[CodeArtifact]:
+        tree = ast.parse(self._code)
+        functions = [
+            node for node in ast.walk(tree) if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
+        ]
+        functions.sort(key=lambda n: n.lineno)
+
+        artifacts = []
+        for node in functions:
+            segment = ast.get_source_segment(self._code, node)
+            if segment:
+                artifacts.append(
+                    CodeArtifact(kind="function", path=f"{self._path}::{node.name}", content=segment)
+                )
+        return artifacts

codejury/sources/mock.py

@@ -0,0 +1,25 @@
+"""MockSource -- a Source that yields canned CodeArtifacts.
+
+Used by the dry-run and tests so the pipeline has input without touching git or
+the filesystem. Pass your own artifacts, or rely on the default illustrative diff.
+"""
+
+from __future__ import annotations
+
+from codejury.domain.artifact import CodeArtifact
+from codejury.sources.base import Source
+
+_DEFAULT_DIFF = """\
++def store_password(pwd: str) -> str:
++    return hashlib.sha256(pwd.encode()).hexdigest()
+"""
+
+
+class MockSource(Source):
+    def __init__(self, artifacts: list[CodeArtifact] | None = None) -> None:
+        self._artifacts = artifacts if artifacts is not None else [
+            CodeArtifact(kind="diff", path="auth.py", content=_DEFAULT_DIFF),
+        ]
+
+    def list_artifacts(self) -> list[CodeArtifact]:
+        return list(self._artifacts)

codejury/sources/repo.py

@@ -0,0 +1,44 @@
+"""RepoSource -- walk a repository into CodeArtifacts, one per file (chunked).
+
+Selects files by extension, skips noise directories (.git, virtualenvs, caches),
+and runs each file through a Chunker so large files fit the model's context
+window. Artifact paths are relative to the repo root.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from codejury.domain.artifact import CodeArtifact
+from codejury.sources.base import Source
+from codejury.sources.chunker import Chunker
+
+_SKIP_DIRS = frozenset({".git", ".venv", "venv", "node_modules", "__pycache__", ".mypy_cache", ".pytest_cache"})
+
+
+class RepoSource(Source):
+    def __init__(
+        self,
+        root: str | Path,
+        *,
+        extensions: tuple[str, ...] = (".py",),
+        chunker: Chunker | None = None,
+        skip_dirs: frozenset[str] = _SKIP_DIRS,
+    ) -> None:
+        self._root = Path(root)
+        self._extensions = extensions
+        self._chunker = chunker or Chunker()
+        self._skip_dirs = skip_dirs
+
+    def list_artifacts(self) -> list[CodeArtifact]:
+        artifacts: list[CodeArtifact] = []
+        for path in sorted(self._root.rglob("*")):
+            if not path.is_file() or path.suffix not in self._extensions:
+                continue
+            if any(part in self._skip_dirs for part in path.relative_to(self._root).parts):
+                continue
+            rel = path.relative_to(self._root).as_posix()
+            content = path.read_text(encoding="utf-8", errors="replace")
+            for chunk_path, chunk_content in self._chunker.split(rel, content):
+                artifacts.append(CodeArtifact(kind="repo", path=chunk_path, content=chunk_content))
+        return artifacts

codejury/tasks/__init__.py

@@ -0,0 +1,6 @@
+"""codejury.tasks -- Layer 5 task presets.
+
+A task is a named binding of capabilities + orchestrator + provider + model, so a
+new audit is a new config file rather than new code. The input source is supplied
+at run time because it carries the actual code under review.
+"""

codejury/tasks/base.py

@@ -0,0 +1,55 @@
+"""Task model and runner.
+
+A Task selects which capabilities to check and under which orchestration and
+model. ``run_task`` binds it to a runtime source and executes it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from codejury.assembly import DEFAULT_MODEL, build_orchestration, make_provider, run_over_source
+from codejury.domain.capability import Capability
+from codejury.domain.result import AnalysisResult
+from codejury.sources.base import Source
+
+
+@dataclass(frozen=True, kw_only=True)
+class Task:
+    name: str
+    orchestrator: str = "single"
+    provider: str = "anthropic"
+    model: str = DEFAULT_MODEL
+    capabilities: tuple[str, ...] | None = None  # capability ids to check; None = all
+    max_tokens: int = 2048
+    retries: int = 0  # provider retry attempts on transient failure
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Task:
+        caps = data.get("capabilities")
+        return cls(
+            name=data["name"],
+            orchestrator=data.get("orchestrator", "single"),
+            provider=data.get("provider", "anthropic"),
+            model=data.get("model", DEFAULT_MODEL),
+            capabilities=tuple(caps) if caps is not None else None,
+            max_tokens=int(data.get("max_tokens", 2048)),
+            retries=int(data.get("retries", 0)),
+        )
+
+    def select(self, capabilities: list[Capability]) -> list[Capability]:
+        if self.capabilities is None:
+            return list(capabilities)
+        wanted = set(self.capabilities)
+        return [c for c in capabilities if c.id in wanted]
+
+
+def run_task(
+    task: Task, source: Source, capabilities: list[Capability]
+) -> list[tuple[str, AnalysisResult]]:
+    provider = make_provider(task.provider, retries=task.retries)
+    agents, orchestrator = build_orchestration(
+        task.orchestrator, provider=provider, model=task.model, max_tokens=task.max_tokens
+    )
+    return run_over_source(source, task.select(capabilities), agents, orchestrator)

codejury/tasks/registry.py

@@ -0,0 +1,22 @@
+"""Load Task presets from YAML files."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+from codejury.tasks.base import Task
+
+
+def load_task(path: str | Path) -> Task:
+    with open(path, encoding="utf-8") as f:
+        data = yaml.safe_load(f)
+    if not isinstance(data, dict):
+        raise ValueError(f"{path}: expected a YAML mapping at the top level, got {type(data).__name__}")
+    return Task.from_dict(data)
+
+
+def load_tasks(directory: str | Path) -> dict[str, Task]:
+    """Load every ``*.yaml`` task in a directory, keyed by task name."""
+    return {task.name: task for task in (load_task(p) for p in sorted(Path(directory).glob("*.yaml")))}

codejury-0.1.0.dist-info/METADATA

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: codejury
+Version: 0.1.0
+Summary: General-purpose Application Security AI audit framework -- five-layer architecture, capabilities as first-class data
+Author: 4234288
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/4234288/codejury
+Project-URL: Repository, https://github.com/4234288/codejury
+Keywords: security,appsec,static analysis,llm,owasp,asvs,code review
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40; extra == "anthropic"
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == "openai"
+Provides-Extra: litellm
+Requires-Dist: litellm>=1.0; extra == "litellm"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# codejury
+
+A general-purpose **Application Security AI audit framework**. Domain knowledge (11
+capabilities aligned with OWASP ASVS) lives in versioned YAML files as
+first-class data, keeping the framework core small.
+
+The name comes from the core orchestration metaphor: code goes before a "jury"
+of adversarial roles -- Finder / Challenger / Judge -- that converge on a verdict.
+
+## Five-layer architecture
+
+```
+Layer 5  Task            task configuration (source + capabilities + orchestrator + agents)
+Layer 4  Capability      YAML domain knowledge (authn / authz / input_validation ...)
+Layer 3  Orchestrator    strategy (single / debate / pipeline / reflexion)
+         Source          input (diff / function / repo)
+         Agent           audit role (finder / challenger / judge / verifier)
+Layer 2  Provider        model backend (anthropic / openai / litellm / mock)
+Layer 1  Infrastructure  cross-cutting utilities (json parsing, ...)
+```
+
+Layers talk only through typed data. Each layer is an abstract base class (ABC)
+plus implementations, so the four axes (task / orchestration / model / input)
+compose independently.
+
+## Design notes
+
+- **Domain knowledge is data, not prompts**: a capability YAML is readable by
+  the LLM, by a rule engine, and by a human, and is versioned alongside code.
+- **Explains both "why it's wrong" and "why it's fine"**: every capability
+  yields a `Verdict`, recording safe matches too -- a checkup dimension rather
+  than an anomaly filter.
+
+## Status
+
+Usable end to end across all five layers:
+
+- **Orchestrators**: single, pipeline, debate, reflexion
+- **Sources**: diff, function, repo (with chunking)
+- **Providers**: anthropic, openai, litellm, mock (plus an opt-in retry wrapper)
+- **Capabilities**: all 11 OWASP ASVS areas
+- **Tasks**: named presets in `tasks/` (e.g. `audit_diff_debate`)
+- **Reporting**: text, markdown, json
+- **Evaluation**: a golden-case precision/recall harness
+
+The golden set ships with seed cases; real precision/recall numbers need a model
+(`codejury eval` with a provider key).
+
+## Install
+
+```bash
+pip install codejury                 # core + CLI
+pip install 'codejury[anthropic]'    # add the provider you'll use (anthropic / openai / litellm)
+```
+
+## Usage
+
+```bash
+# Audit a unified diff against the capability library
+git diff | codejury audit --orchestrator debate --provider anthropic --format markdown -
+
+# Run a named task preset (tasks/*.yaml)
+git diff | codejury run audit_diff_debate -
+
+# Score detection quality against the golden cases (needs a provider key)
+codejury eval --provider anthropic
+
+# No API key needed: prove the pipeline composes with mock layers
+codejury dry-run
+```
+
+`audit` and `run` read a diff from a file argument or stdin (`-`). Real providers
+read their key from the environment (e.g. `ANTHROPIC_API_KEY`).
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```