repocodex 0.0.1__py3-none-any.whl

repocodex/__init__.py

@@ -0,0 +1,6 @@
+"""RepoCodex engine: repository-native executable memory for coding agents."""
+
+from __future__ import annotations
+
+ENGINE_VERSION = "0.0.1"
+__version__ = ENGINE_VERSION

repocodex/__main__.py

@@ -0,0 +1,8 @@
+"""Run the RepoCodex CLI as `python -m repocodex`."""
+
+from __future__ import annotations
+
+from repocodex.cli import app
+
+if __name__ == "__main__":
+    app()

repocodex/cli.py

@@ -0,0 +1,189 @@
+"""Typer CLI for RepoCodex. Commands print JSON envelopes and exit non-zero on failure."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from repocodex.commands.advisory import advisory as run_advisory
+from repocodex.commands.audit import audit as run_audit
+from repocodex.commands.bootstrap import bootstrap as run_bootstrap
+from repocodex.commands.context import context_for
+from repocodex.commands.install import install as run_install
+from repocodex.commands.reconcile import apply_anchor_patch, reconcile_memory
+from repocodex.commands.relocate import relocate_memory
+from repocodex.commands.repair import repair as run_repair
+from repocodex.commands.validate import validate as run_validate
+from repocodex.commands.write import write_memory
+from repocodex.config import EngineVersionMismatch
+from repocodex.schema import envelope
+
+app = typer.Typer(no_args_is_help=True, add_completion=False, help="RepoCodex executable memory CLI")
+
+
+def _emit(payload: dict, exit_code: int = 0) -> None:
+    """Print ``payload`` as JSON and exit with ``exit_code``."""
+    typer.echo(json.dumps(payload, indent=2))
+    raise typer.Exit(exit_code)
+
+
+def _repo() -> Path:
+    """Return the process working directory as the target repository."""
+    return Path.cwd()
+
+
+def _guarded(fn):
+    """Run ``fn`` and emit an engine-version-mismatch envelope on pin failure."""
+    try:
+        return fn()
+    except EngineVersionMismatch as exc:
+        _emit(exc.to_json(), 1)
+        raise
+
+
+@app.command("validate")
+def validate_command(
+    diff: bool = typer.Option(False, "--diff", help="Attest anchors intersecting the diff"),
+    base: Optional[str] = typer.Option(None, "--base", help="Git diff base, e.g. origin/main...HEAD"),
+    staged: bool = typer.Option(False, "--staged"),
+    all_concepts: bool = typer.Option(False, "--all"),
+    check: bool = typer.Option(False, "--check", help="Exit 1 on deterministic blocking outcomes"),
+    hook: bool = typer.Option(False, "--hook"),
+    memory_exempt: bool = typer.Option(False, "--memory-exempt"),
+    review_ack: bool = typer.Option(False, "--review-ack", hidden=True),
+    ack_file: Optional[Path] = typer.Option(None, "--ack-file", help="Tracked review-agent acknowledgment record"),
+    apply_patches: bool = typer.Option(False, "--apply-patches"),
+) -> None:
+    """Attest anchors on the working tree or diff. JSON includes engine_version."""
+    payload = _guarded(
+        lambda: run_validate(
+            _repo(),
+            base=base,
+            staged=staged or hook,
+            all_concepts=all_concepts or not diff,
+            memory_exempt=memory_exempt,
+            review_ack=review_ack,
+            ack_file=str(ack_file) if ack_file else None,
+        )
+    )
+    if apply_patches:
+        for patch in payload.get("patches") or []:
+            apply_anchor_patch(_repo(), patch)
+            payload.setdefault("applied_patches", []).append(patch)
+    code = 1 if (check or hook) and payload.get("blocking") else 0
+    _emit(payload, code)
+
+
+@app.command("write")
+def write_command(
+    concept: Optional[Path] = typer.Argument(None),
+    identity: Optional[str] = typer.Option(None, "--identity"),
+    stdin: bool = typer.Option(False, "--stdin"),
+) -> None:
+    """Write-gate a concept into .context/."""
+    text = None
+    if stdin:
+        text = typer.get_text_stream("stdin").read()
+    if concept is None and text is None:
+        raise typer.BadParameter("provide a concept file or --stdin")
+    payload = _guarded(lambda: write_memory(_repo(), concept or Path("."), identity=identity, stdin_text=text))
+    _emit(payload, 0 if payload.get("accepted") else 1)
+
+
+@app.command("relocate")
+def relocate_command(
+    identity: Optional[str] = typer.Argument(None),
+    mismatched: bool = typer.Option(
+        False, "--mismatched", help="Move all authored-type concepts with wrong prefixes"
+    ),
+) -> None:
+    """Move authored concepts into the type-folder identity required by their type."""
+    if not mismatched and not identity:
+        raise typer.BadParameter("provide an identity or --mismatched")
+    payload = _guarded(lambda: relocate_memory(_repo(), identity, mismatched=mismatched))
+    _emit(payload)
+
+
+@app.command("reconcile")
+def reconcile_command(
+    concept: Optional[Path] = typer.Argument(None),
+    identity: Optional[str] = typer.Option(None, "--identity"),
+    apply_patch: Optional[str] = typer.Option(None, "--apply-patch", help="JSON patch object"),
+) -> None:
+    """Repair DRIFT with gate-enforced new anchors, or apply a REANCHOR patch."""
+    repo = _repo()
+    if apply_patch:
+        patch = json.loads(apply_patch)
+        path = apply_anchor_patch(repo, patch)
+        _emit(envelope({"applied": True, "path": str(path)}))
+    if concept is None:
+        raise typer.BadParameter("provide a concept file")
+    payload = _guarded(lambda: reconcile_memory(repo, concept, identity=identity))
+    _emit(payload, 0 if payload.get("accepted") else 1)
+
+
+@app.command("context")
+def context_command(
+    paths: list[Path] = typer.Argument(..., metavar="PATHS"),
+    drafts: bool = typer.Option(False, "--drafts"),
+) -> None:
+    """Staged retrieval: reverse index → catalogs → bodies + one link-hop of titles."""
+    payload = _guarded(lambda: context_for(_repo(), [str(p) for p in paths], include_drafts=drafts))
+    _emit(payload)
+
+
+@app.command("repair")
+def repair_command() -> None:
+    """Invoke a repair agent against the current RECONCILE state."""
+    payload = _guarded(lambda: run_repair(_repo()))
+    code = 1 if payload.get("error") else 0
+    _emit(payload, code)
+
+
+@app.command("install")
+def install_command(
+    mcp: bool = typer.Option(False, "--mcp", help="Register optional MCP wrapper"),
+) -> None:
+    """Install pre-commit hook, GitHub Action, skills, and optional MCP."""
+    payload = _guarded(lambda: run_install(_repo(), mcp=mcp))
+    _emit(payload, 0 if payload.get("ok", True) else 1)
+
+
+@app.command("bootstrap")
+def bootstrap_command() -> None:
+    """Mine history/comments/docs; keep only gate-passing drafts."""
+    _emit(_guarded(lambda: run_bootstrap(_repo())))
+
+
+@app.command("audit")
+def audit_command(
+    sample_size: int = typer.Option(10, "--sample-size"),
+    seed: int = typer.Option(0, "--seed"),
+    findings: Optional[Path] = typer.Option(None, "--findings", help="Out-of-band screening result JSON"),
+) -> None:
+    """Emit a screening payload for out-of-band review. No model is invoked."""
+    _emit(
+        _guarded(
+            lambda: run_audit(_repo(), sample_size=sample_size, seed=seed, findings_path=findings)
+        )
+    )
+
+
+@app.command("advisory")
+def advisory_command(
+    base: Optional[str] = typer.Option(None, "--base"),
+    staged: bool = typer.Option(False, "--staged"),
+) -> None:
+    """Agent-judged findings for the advisory CI check. Never affects the required verdict."""
+    _emit(_guarded(lambda: run_advisory(_repo(), base=base, staged=staged)))
+
+
+@app.command("mcp")
+def mcp_command() -> None:
+    """Run the optional MCP server wrapping the CLI."""
+    from repocodex.mcp_server import run_mcp
+
+    run_mcp()

repocodex/commands/__init__.py

@@ -0,0 +1,3 @@
+"""CLI command implementations invoked from `repocodex.cli`."""
+
+from __future__ import annotations

repocodex/commands/advisory.py

@@ -0,0 +1,95 @@
+"""Rank code-side impact and wrap optional agent judgments into a non-blocking advisory envelope."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from repocodex.commands.validate import changed_files
+from repocodex.config import load_config
+from repocodex.engine.code_impact import rank_code_hits
+from repocodex.schema import envelope
+
+NOT_EVALUATED = "not_evaluated"
+EVALUATED = "evaluated"
+
+
+def _category(status: str, findings: list[dict] | None = None) -> dict[str, Any]:
+    """Build a category payload, attaching findings only when evaluated."""
+    payload: dict[str, Any] = {"status": status}
+    if status == EVALUATED:
+        payload["findings"] = findings or []
+    return payload
+
+
+def advisory(
+    repo: Path,
+    *,
+    base: str | None = None,
+    staged: bool = False,
+    judgments: dict[str, list[dict]] | None = None,
+) -> dict:
+    """Return a non-blocking advisory envelope for the current diff.
+
+    Skips ``.context/`` paths and ``reverse-index.md``. Judgment categories
+    without a key in ``judgments`` stay ``not_evaluated``.
+
+    Returns:
+        Envelope with ``kind`` ``advisory``, ``code_side_impact`` (path/hits
+        rows), ``prose_versus_diff``, ``skipped_recipe_steps``, ``churn_flags``
+        (each ``status`` plus optional ``findings``), ``agent_judgment``, and
+        ``required_verdict_unaffected`` always ``True``.
+
+    """
+    config = load_config(repo)
+    files = changed_files(repo, base=base, staged=staged)
+    code_side: list[dict] = []
+    for path in files:
+        if path.startswith(".context/") or path.endswith("reverse-index.md"):
+            continue
+        symbols = Path(path).stem
+        hits = rank_code_hits(path, symbols, repo, cap=config.impact_read_cap, exclusions=config.all_exclusions)
+        if hits:
+            code_side.append({"path": path, "hits": hits})
+
+    judgments = judgments or {}
+
+    def category_for(name: str) -> dict[str, Any]:
+        if name in judgments:
+            return _category(EVALUATED, judgments[name])
+        return _category(NOT_EVALUATED)
+
+    prose = category_for("prose_versus_diff")
+    skipped = category_for("skipped_recipe_steps")
+    churn = category_for("churn_flags")
+    any_judgment = any(cat["status"] == EVALUATED for cat in (prose, skipped, churn))
+    return envelope(
+        {
+            "kind": "advisory",
+            "code_side_impact": code_side,
+            "prose_versus_diff": prose,
+            "skipped_recipe_steps": skipped,
+            "churn_flags": churn,
+            "agent_judgment": any_judgment,
+            "required_verdict_unaffected": True,
+        }
+    )
+
+
+def scenario_integrity_status(root: Path) -> dict:
+    """Report whether an OKF concept bundle exists for scenario integrity.
+
+    Never falls back to a test table.
+
+    Returns:
+        ``{"status": "unsatisfied", "reason": "no_okf_bundle"}`` when no
+        concepts are loaded, otherwise
+        ``{"status": "available", "reason": "agent_read_okf"}``.
+
+    """
+    from repocodex.store.bundle import load_concepts
+
+    concepts = load_concepts(root)
+    if not concepts:
+        return {"status": "unsatisfied", "reason": "no_okf_bundle"}
+    return {"status": "available", "reason": "agent_read_okf"}

repocodex/commands/audit.py

@@ -0,0 +1,153 @@
+"""Sample stable concepts for out-of-band screening and retire orphan or expired drafts."""
+
+from __future__ import annotations
+
+import json
+import random
+from datetime import date, datetime, timezone
+from pathlib import Path
+
+from repocodex.config import load_config
+from repocodex.engine.contradiction import contradiction_flags
+from repocodex.engine.gate import _term_count
+from repocodex.engine.match import evaluate_file, read_pinned
+from repocodex.schema import ConceptStatus, envelope, utc_now
+from repocodex.store.bundle import deprecate_concept, load_concepts
+from repocodex.store.reverse_index import merged_index
+
+
+def _expired(stale_after: str | None) -> bool:
+    """Return True when ``stale_after`` parses as a UTC date already past."""
+    if not stale_after:
+        return False
+    try:
+        return date.fromisoformat(stale_after[:10]) < datetime.now(timezone.utc).date()
+    except ValueError:
+        return False
+
+
+def gc(repo: Path) -> list[str]:
+    """Deprecate orphan concepts and expired drafts.
+
+    A concept is retired when nothing inbound-links it and no anchor still
+    matches, or when it is a draft past ``stale_after``. Deprecation uses
+    reason ``gc``.
+
+    Returns:
+        Identities that were deprecated.
+
+    """
+    retired: list[str] = []
+    concepts = load_concepts(repo)
+    inbound: set[str] = set()
+    from repocodex.engine.impact import linked_identities
+
+    for doc in concepts:
+        inbound.update(linked_identities(doc))
+    for doc in concepts:
+        live_anchor = False
+        for anchor in doc.anchors:
+            matched = evaluate_file(anchor, repo)
+            if matched.hits_for_best() > 0:
+                live_anchor = True
+                break
+        orphan = doc.identity not in inbound and not live_anchor
+        expired_draft = doc.status == ConceptStatus.draft and _expired(doc.frontmatter.stale_after)
+        if orphan or expired_draft:
+            deprecate_concept(repo, doc.identity, reason="gc")
+            retired.append(doc.identity)
+    return retired
+
+
+def audit(
+    repo: Path,
+    *,
+    sample_size: int | None = None,
+    seed: int = 0,
+    findings_path: Path | None = None,
+) -> dict:
+    """Emit a screening payload for out-of-band review; never invoke a model.
+
+    Samples stable concepts (all of them when the set is at most ``n``),
+    scores term distinctiveness, flags contradictions, and runs :func:`gc`.
+    Optional ``findings_path`` JSON (a list, or ``findings`` / ``results``)
+    becomes ``CONTRADICTION`` proposals for the attested-write path.
+
+    Returns:
+        Envelope with ``sampled``, ``distinctiveness``, ``weak_anchors``,
+        ``contradictions``, ``contradiction_proposals``, ``gc_deprecated``,
+        ``screening``, ``model_invoked`` always ``False``, ``note``, and
+        ``at``.
+
+    """
+    config = load_config(repo)
+    concepts = [doc for doc in load_concepts(repo) if doc.status == ConceptStatus.stable]
+    n = sample_size or config.audit_sample_size
+    rng = random.Random(seed)
+    sample = concepts if len(concepts) <= n else rng.sample(concepts, n)
+    scored = []
+    weak = []
+    screening = []
+    for doc in sample:
+        term_counts: dict[str, int] = {}
+        for anchor in doc.anchors:
+            for term in anchor.all_of:
+                term_counts[term] = _term_count(term, config)
+            distinctive = any(
+                count < config.distinctiveness_ceiling for count in term_counts.values()
+            )
+            if not distinctive:
+                weak.append(doc.identity)
+            region = ""
+            text = read_pinned(repo, anchor.path)
+            if text:
+                matched = evaluate_file(anchor, repo, default_scope=config.scope_lines)
+                if matched.best:
+                    region = matched.best.source(text.splitlines())
+            screening.append(
+                {
+                    "identity": doc.identity,
+                    "title": doc.frontmatter.title,
+                    "body": doc.body,
+                    "pinned_region": region,
+                    "term_counts": term_counts,
+                }
+            )
+        scored.append({"identity": doc.identity, "term_counts": term_counts})
+    contradictions = contradiction_flags(load_concepts(repo), repo)
+    retired = gc(repo)
+    proposals: list[dict] = []
+    if findings_path:
+        data = json.loads(Path(findings_path).read_text(encoding="utf-8"))
+        items = data if isinstance(data, list) else data.get("findings") or data.get("results") or []
+        for item in items:
+            identity = item.get("identity") or item.get("concept")
+            if not identity:
+                continue
+            proposals.append(
+                {
+                    "kind": "CONTRADICTION",
+                    "reason": "audit_screening",
+                    "concept": identity,
+                    "proposal": True,
+                    "detail": item,
+                }
+            )
+    return envelope(
+        {
+            "sampled": [doc.identity for doc in sample],
+            "distinctiveness": scored,
+            "weak_anchors": weak,
+            "contradictions": contradictions,
+            "contradiction_proposals": proposals,
+            "gc_deprecated": retired,
+            "screening": screening,
+            "model_invoked": False,
+            "note": (
+                "repocodex audit emits a screening payload for out-of-band model review; "
+                "no model is invoked inside the engine. Returned findings become CONTRADICTION "
+                "proposals resolved through the attested-write path, never automatic edits."
+            ),
+            "at": utc_now(),
+        }
+    )

repocodex/commands/bootstrap.py

@@ -0,0 +1,152 @@
+"""Mine why-comments and commit history into draft TechnicalDecision concepts."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+from repocodex.config import load_config
+from repocodex.engine.gate import evaluate_write
+from repocodex.schema import (
+    Anchor,
+    ConceptDocument,
+    ConceptFrontmatter,
+    ConceptStatus,
+    ConceptType,
+    Source,
+    Verification,
+    envelope,
+)
+from repocodex.store.bundle import write_concept
+from repocodex.store.reverse_index import regenerate_all
+from repocodex.tools.git import git_ls_files, run_git
+
+WHY_COMMENT = re.compile(r"(?://|#|/\*)\s*why:\s*(.+)")
+DOC_WHY = re.compile(r"(?i)^(?:why|decision|invariant)\s*[:\-]\s*(.+)$")
+
+
+def _stale_after(days: int = 30) -> str:
+    """Return a UTC ISO date ``days`` from now for draft expiry."""
+    when = datetime.now(timezone.utc) + timedelta(days=days)
+    return when.date().isoformat()
+
+
+def _stable_id(rel: str, note: str) -> str:
+    """Build a deterministic ``decisions/`` identity from path and note."""
+    digest = hashlib.sha256(f"{rel}\n{note}".encode("utf-8")).hexdigest()[:12]
+    return f"decisions/{Path(rel).stem}-{digest}"
+
+
+def _commit_for(repo: Path, rel: str) -> str | None:
+    """Return the latest commit SHA that touched ``rel``, if any."""
+    result = run_git(["log", "-n", "1", "--pretty=%H", "--", rel], cwd=repo)
+    sha = result.stdout.strip()
+    return sha or None
+
+
+def _candidates_from_comments(repo: Path, files: list[str]) -> list[tuple[str, str, list[str], str | None]]:
+    """Collect why-comments and markdown decision lines from tracked files."""
+    SKIP_SUFFIX = {".py", ".ts", ".js", ".go", ".rs", ".java", ".md"}
+    found: list[tuple[str, str, list[str], str | None]] = []
+    for rel in files:
+        if Path(rel).suffix not in SKIP_SUFFIX:
+            continue
+        path = repo / rel
+        if not path.is_file():
+            continue
+        try:
+            text = path.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        for match in WHY_COMMENT.finditer(text):
+            note = match.group(1).strip()
+            terms = [part for part in re.findall(r"[A-Za-z_][A-Za-z0-9_]{3,}", note)][:3]
+            if terms:
+                found.append((rel, note, terms, _commit_for(repo, rel)))
+        if rel.endswith(".md") and not rel.startswith(".context/"):
+            for match in DOC_WHY.finditer(text):
+                note = match.group(1).strip()
+                terms = [part for part in re.findall(r"[A-Za-z_][A-Za-z0-9_]{3,}", note)][:3]
+                if terms:
+                    found.append((rel, note, terms, _commit_for(repo, rel)))
+    return found
+
+
+def _candidates_from_history(repo: Path) -> list[tuple[str, str, list[str], str | None]]:
+    """Collect why-like subjects from the last 100 commits and their first path."""
+    log = run_git(["log", "--pretty=%H%x09%s", "-n", "100"], cwd=repo)
+    found: list[tuple[str, str, list[str], str | None]] = []
+    for line in log.stdout.splitlines():
+        if "\t" not in line:
+            continue
+        sha, subject = line.split("\t", 1)
+        lower = subject.lower()
+        if not any(token in lower for token in ("why:", "because", "decision:", "do not ")):
+            continue
+        files = run_git(["diff-tree", "--no-commit-id", "--name-only", "-r", sha], cwd=repo)
+        paths = [p for p in files.stdout.splitlines() if p.strip()]
+        if not paths:
+            continue
+        rel = paths[0]
+        terms = [part for part in re.findall(r"[A-Za-z_][A-Za-z0-9_]{3,}", subject)][:3]
+        if terms:
+            found.append((rel, subject.strip(), terms, sha))
+    return found
+
+
+def bootstrap(repo: Path) -> dict:
+    """Write gate-passing draft decisions mined from comments and history.
+
+    Candidates without an evidencing commit are rejected with
+    ``no_evidencing_source``. Gate failures keep the identity and
+    ``tighten`` list. Successful writes regenerate the reverse index.
+
+    Returns:
+        Envelope with ``kept`` identities, ``rejected`` rows, and
+        ``status`` ``draft``.
+
+    """
+    config = load_config(repo)
+    kept: list[str] = []
+    rejected: list[dict] = []
+    tracked = git_ls_files(repo)
+    candidates = [
+        *_candidates_from_comments(repo, tracked),
+        *_candidates_from_history(repo),
+    ]
+    seen: set[str] = set()
+    for rel, note, terms, source in candidates:
+        identity = _stable_id(rel, note)
+        if identity in seen:
+            continue
+        seen.add(identity)
+        if not source:
+            rejected.append({"identity": identity, "tighten": ["no_evidencing_source"]})
+            continue
+        doc = ConceptDocument(
+            identity=identity,
+            frontmatter=ConceptFrontmatter(
+                type=ConceptType.TechnicalDecision,
+                title=note[:80],
+                status=ConceptStatus.draft,
+                stale_after=_stale_after(),
+                sources=[Source(resource=f"git://commit/{source}", title="commit", id=source)],
+                verification=Verification(
+                    engine="ripgrep",
+                    anchors=[Anchor(path=rel, all_of=terms)],
+                ),
+            ),
+            body=f"Bootstrapped from `{rel}`.\n\n{note}\n",
+        )
+        gate = evaluate_write(doc, config)
+        if not gate.accepted:
+            rejected.append({"identity": identity, "tighten": gate.tighten})
+            continue
+        write_concept(repo, doc)
+        kept.append(identity)
+
+    if kept:
+        regenerate_all(repo)
+    return envelope({"kept": kept, "rejected": rejected, "status": "draft"})

repocodex/commands/context.py

@@ -0,0 +1,28 @@
+"""Retrieve ranked concepts for given paths and record a tokens-per-turn metric."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from repocodex import ENGINE_VERSION
+from repocodex.metrics import record_metric
+from repocodex.retrieval import retrieve
+from repocodex.schema import envelope
+
+
+def context_for(repo: Path, paths: list[str], *, include_drafts: bool = False) -> dict:
+    """Return retrieved concepts for ``paths`` plus a tokens-per-turn estimate.
+
+    Drafts are omitted unless ``include_drafts``. Records a ``context`` metric
+    with ``tokens_per_turn`` (body chars / 4) and the requested paths.
+
+    Returns:
+        Envelope merging retrieve keys ``paths``, ``concepts``, ``related``,
+        and ``catalog`` with ``tokens_per_turn`` and ``engine_version``.
+
+    """
+    payload = retrieve(repo, paths, include_drafts=include_drafts)
+    chars = sum(len(item.get("body") or "") for item in payload.get("concepts") or [])
+    tokens_per_turn = chars / 4.0
+    record_metric(repo, "context", {"tokens_per_turn": tokens_per_turn, "paths": list(paths)})
+    return envelope({**payload, "tokens_per_turn": tokens_per_turn}, engine_version=ENGINE_VERSION)