context-engineering-cli 2.6.0__py3-none-any.whl

context_engineering/domain/result.py

@@ -0,0 +1,59 @@
+"""Result containers — LintResult (findings) and AnalysisResult (data + findings)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .finding import Finding, Severity
+
+
+@dataclass
+class LintResult:
+    target: str
+    findings: list[Finding] = field(default_factory=list)
+
+    @property
+    def error_count(self) -> int:
+        return sum(1 for f in self.findings if f.severity == Severity.ERROR)
+
+    @property
+    def warning_count(self) -> int:
+        return sum(1 for f in self.findings if f.severity == Severity.WARNING)
+
+    @property
+    def info_count(self) -> int:
+        return sum(1 for f in self.findings if f.severity == Severity.INFO)
+
+    @property
+    def has_errors(self) -> bool:
+        return self.error_count > 0
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "target": self.target,
+            "findings": [f.to_dict() for f in self.findings],
+            "summary": {
+                "error": self.error_count,
+                "warning": self.warning_count,
+                "info": self.info_count,
+            },
+        }
+
+
+@dataclass
+class AnalysisResult:
+    target: str
+    data: dict[str, Any] = field(default_factory=dict)
+    findings: list[Finding] = field(default_factory=list)
+
+    @property
+    def has_errors(self) -> bool:
+        return any(finding.severity == Severity.ERROR for finding in self.findings)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "target": self.target,
+            "data": self.data,
+            "findings": [f.to_dict() for f in self.findings],
+        }

context_engineering/infra/__init__.py

@@ -0,0 +1,13 @@
+"""Thin wrappers around the outside world — git, YAML, filesystem."""
+
+from .filesystem import EXCLUDED_DIRS, read_text_safe
+from .git import git_log, git_root
+from .yaml_frontmatter import parse_frontmatter
+
+__all__ = [
+    "EXCLUDED_DIRS",
+    "git_log",
+    "git_root",
+    "parse_frontmatter",
+    "read_text_safe",
+]

context_engineering/infra/filesystem.py

@@ -0,0 +1,22 @@
+"""Shared filesystem helpers — excluded-dir set + safe text read.
+
+Each checker/analyzer does its own specialized discovery walk (docs-only,
+AGENTS.md + docs pairs, git-tracked files), so we don't try to provide a
+one-size-fits-all walker. Consumers check `EXCLUDED_DIRS` directly.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+EXCLUDED_DIRS: frozenset[str] = frozenset(
+    {".git", ".venv", "_archive", "archive", "node_modules", "__pycache__"}
+)
+
+
+def read_text_safe(path: Path) -> str | None:
+    """Read text or return None on OSError/UnicodeDecodeError/missing."""
+    try:
+        return path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return None

context_engineering/infra/git.py

@@ -0,0 +1,153 @@
+"""One git wrapper. Replaces three separate git-log parsers across modules."""
+
+from __future__ import annotations
+
+import datetime
+import subprocess
+from collections.abc import Iterator
+from pathlib import Path
+
+from ..domain.commit import Commit
+
+_COMMIT_SENTINEL = "\x1fCOMMIT\x1f"
+_FIELD_SEP = "\x1f"
+
+
+def resolve_commit(repo: Path, ref: str) -> tuple[str | None, str | None]:
+    """Resolve ``ref`` to a full commit SHA without allowing Git options."""
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--verify", "--end-of-options", f"{ref}^{{commit}}"],
+            capture_output=True,
+            text=True,
+            cwd=repo,
+        )
+    except FileNotFoundError:
+        return None, "Git is not installed or is not on PATH"
+    if result.returncode != 0:
+        diagnostic = result.stderr.strip() or f"git rev-parse exited {result.returncode}"
+        return None, diagnostic
+    return result.stdout.strip(), None
+
+
+def resolve_merge_base(repo: Path, base: str, head: str) -> tuple[str | None, str | None]:
+    """Resolve the unique merge base used by a three-dot diff."""
+    try:
+        result = subprocess.run(
+            ["git", "merge-base", "--", base, head],
+            capture_output=True,
+            text=True,
+            cwd=repo,
+        )
+    except FileNotFoundError:
+        return None, "Git is not installed or is not on PATH"
+    if result.returncode != 0:
+        diagnostic = result.stderr.strip() or f"git merge-base exited {result.returncode}"
+        return None, diagnostic
+    candidates = result.stdout.splitlines()
+    if len(candidates) != 1:
+        return None, "Git did not return one merge base"
+    return candidates[0], None
+
+
+def git_root(path: Path) -> Path | None:
+    """Return repo root for `path`, or None if not inside a git repo."""
+    search = path if path.is_dir() else path.parent
+    while not search.exists() and search != search.parent:
+        search = search.parent
+    if not search.exists():
+        return None
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"],
+            capture_output=True,
+            text=True,
+            cwd=search,
+        )
+    except FileNotFoundError:
+        return None
+    if result.returncode != 0:
+        return None
+    reported = Path(result.stdout.strip())
+    candidate = search
+    while True:
+        try:
+            if candidate.samefile(reported):
+                return candidate
+        except OSError:
+            pass
+        if candidate == candidate.parent:
+            break
+        candidate = candidate.parent
+    return reported
+
+
+def git_log(
+    repo: Path,
+    *,
+    since_days: int | None = None,
+    since_ref: str | None = None,
+    paths: list[str] | None = None,
+    max_count: int | None = None,
+) -> Iterator[Commit]:
+    """Stream commits from `repo`, newest first.
+
+    - `since_days`: restrict to commits within the last N days.
+    - `since_ref`: restrict to `<ref>..HEAD` (commits since a specific SHA/ref).
+    - `paths`: restrict to commits touching any of these paths.
+    - `max_count`: cap the number of commits (for lookups like "most recent one").
+    """
+    root = git_root(repo)
+    if root is None:
+        return
+
+    pretty = f"--pretty=format:{_COMMIT_SENTINEL}%H{_FIELD_SEP}%an{_FIELD_SEP}%aI"
+    cmd = ["git", "log", "--name-only", pretty]
+    if max_count is not None:
+        cmd.append(f"-{max_count}")
+    if since_days is not None:
+        cmd.append(f"--since={since_days}.days.ago")
+    if since_ref:
+        cmd.append(f"{since_ref}..HEAD")
+    if paths:
+        cmd.append("--")
+        cmd.extend(paths)
+
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, cwd=root)
+    except FileNotFoundError:
+        return
+    if result.returncode != 0:
+        return
+
+    yield from _parse(result.stdout)
+
+
+def _parse(stdout: str) -> Iterator[Commit]:
+    sha = ""
+    author = ""
+    date = datetime.datetime.min.replace(tzinfo=datetime.UTC)
+    files: list[str] = []
+    have_header = False
+
+    for raw in stdout.splitlines():
+        if raw.startswith(_COMMIT_SENTINEL):
+            if have_header:
+                yield Commit(sha=sha, author=author, date=date, files=tuple(files))
+            header = raw[len(_COMMIT_SENTINEL) :]
+            parts = header.split(_FIELD_SEP)
+            if len(parts) < 3:
+                have_header = False
+                continue
+            sha, author, date_str = parts[0], parts[1], parts[2]
+            try:
+                date = datetime.datetime.fromisoformat(date_str)
+            except ValueError:
+                date = datetime.datetime.min.replace(tzinfo=datetime.UTC)
+            files = []
+            have_header = True
+        elif raw.strip() and have_header:
+            files.append(raw.strip())
+
+    if have_header:
+        yield Commit(sha=sha, author=author, date=date, files=tuple(files))

context_engineering/infra/git_evidence.py

@@ -0,0 +1,357 @@
+"""Byte-safe Git history and diff evidence parsing."""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+import threading
+from dataclasses import dataclass
+from pathlib import Path
+from typing import NotRequired, TypedDict
+
+_RECORD = b"\x1e"
+_FIELD = "\x1f"
+_DEFAULT_MAX_BYTES = 256 * 1024 * 1024
+
+
+@dataclass(frozen=True)
+class EvidenceBudget:
+    max_records: int = 100_000
+    max_paths: int = 1_000_000
+    max_bytes: int = _DEFAULT_MAX_BYTES
+    max_subprocesses: int = 10_000
+
+
+@dataclass(frozen=True)
+class EvidenceCounts:
+    records: int
+    paths: int
+    bytes: int
+    subprocesses: int = 1
+
+    def to_dict(self) -> dict[str, int]:
+        return {
+            "records": self.records,
+            "paths": self.paths,
+            "bytes": self.bytes,
+            "subprocesses": self.subprocesses,
+        }
+
+
+class CompletePathChange(TypedDict):
+    status: str
+    path: str
+    old_path: NotRequired[str]
+
+
+class CompleteHistoryRecord(TypedDict):
+    commit: str
+    date: str
+    subject: str
+    parents: list[str]
+    changes: list[CompletePathChange]
+
+
+@dataclass(frozen=True)
+class HistoryRecord:
+    commit: str
+    date: str
+    subject: str
+    paths: tuple[str, ...]
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "commit": self.commit,
+            "date": self.date,
+            "subject": self.subject,
+            "paths": list(self.paths),
+        }
+
+
+@dataclass(frozen=True)
+class PathChange:
+    status: str
+    path: str
+    old_path: str | None = None
+
+
+def communicate_bounded(
+    process: subprocess.Popen[bytes],
+    *,
+    max_bytes: int,
+    timeout: float = 120,
+) -> tuple[bytes, bytes, str | None]:
+    """Drain stdout and stderr concurrently under one combined byte ceiling."""
+    assert process.stdout is not None and process.stderr is not None
+    stdout = bytearray()
+    stderr = bytearray()
+    lock = threading.Lock()
+    exceeded = threading.Event()
+    observed = 0
+
+    def drain(stream, sink: bytearray) -> None:
+        nonlocal observed
+        while chunk := stream.read(64 * 1024):
+            with lock:
+                observed += len(chunk)
+                if len(stdout) + len(stderr) <= max_bytes:
+                    remaining = max_bytes + 1 - len(stdout) - len(stderr)
+                    sink.extend(chunk[:remaining])
+                if observed > max_bytes and not exceeded.is_set():
+                    exceeded.set()
+                    process.kill()
+
+    threads = [
+        threading.Thread(target=drain, args=(process.stdout, stdout), daemon=True),
+        threading.Thread(target=drain, args=(process.stderr, stderr), daemon=True),
+    ]
+    for thread in threads:
+        thread.start()
+    error: str | None = None
+    try:
+        process.wait(timeout=timeout)
+    except subprocess.TimeoutExpired:
+        process.kill()
+        error = "Git subprocess timed out"
+    for thread in threads:
+        thread.join(timeout=5)
+    if any(thread.is_alive() for thread in threads):
+        process.kill()
+        error = error or "Git subprocess streams did not close"
+    if exceeded.is_set():
+        error = "Git subprocess output exceeds the configured byte ceiling"
+    return bytes(stdout), bytes(stderr), error
+
+
+def parse_history_output(stdout: bytes) -> tuple[list[HistoryRecord], str | None]:
+    """Parse NUL-delimited history without decoding repository paths as UTF-8."""
+    records: list[HistoryRecord] = []
+    header: tuple[str, str, str] | None = None
+    paths: list[str] = []
+    first_path = False
+    for raw_token in stdout.split(b"\0"):
+        token = raw_token
+        structural = token[1:] if token.startswith(b"\n" + _RECORD) else token
+        if structural.startswith(_RECORD):
+            if header is not None and paths:
+                records.append(HistoryRecord(*header, tuple(sorted(paths))))
+            fields = os.fsdecode(structural[len(_RECORD) :]).split(_FIELD, 2)
+            if len(fields) != 3:
+                return [], "git log returned malformed commit metadata"
+            header = (fields[0], fields[1][:10], fields[2])
+            paths = []
+            first_path = True
+            continue
+        if not token:
+            continue
+        if header is None:
+            return [], "git log returned a path before commit metadata"
+        if first_path and token.startswith(b"\n"):
+            token = token[1:]
+        first_path = False
+        if token:
+            paths.append(os.fsdecode(token))
+    if header is not None and paths:
+        records.append(HistoryRecord(*header, tuple(sorted(paths))))
+    return records, None
+
+
+def read_history(
+    repo: Path,
+    *,
+    cutoff: str,
+    relative_path: str,
+    max_count: int,
+) -> tuple[list[HistoryRecord], str | None]:
+    command = [
+        "git",
+        "log",
+        f"--max-count={max_count}",
+        "--format=%x1e%H%x1f%aI%x1f%s",
+        "--name-only",
+        "-z",
+        "--end-of-options",
+        cutoff,
+        "--",
+    ]
+    if relative_path != ".":
+        command.append(relative_path)
+    try:
+        result = subprocess.run(command, cwd=repo, capture_output=True)
+    except FileNotFoundError:
+        return [], "Git is not installed or is not on PATH"
+    if result.returncode != 0:
+        diagnostic = os.fsdecode(result.stderr).strip()
+        return [], diagnostic or f"git log exited {result.returncode}"
+    return parse_history_output(result.stdout)
+
+
+def parse_diff_output(stdout: bytes) -> tuple[list[PathChange], str | None]:
+    """Parse `git diff --name-status -z` output into exact path changes."""
+    tokens = stdout.split(b"\0")
+    if tokens and tokens[-1] == b"":
+        tokens.pop()
+    changes: list[PathChange] = []
+    index = 0
+    while index < len(tokens):
+        raw_status = os.fsdecode(tokens[index])
+        index += 1
+        if not raw_status:
+            return [], "git diff returned an empty status field"
+        code = raw_status[:1]
+        path_count = 2 if code in {"R", "C"} else 1
+        if index + path_count > len(tokens):
+            return [], "git diff returned an incomplete NUL-delimited path record"
+        paths = [os.fsdecode(tokens[index + offset]) for offset in range(path_count)]
+        index += path_count
+        changes.append(
+            PathChange(
+                status=raw_status,
+                path=paths[-1],
+                old_path=paths[0] if path_count == 2 else None,
+            )
+        )
+    return changes, None
+
+
+def read_diff(
+    repo: Path,
+    *,
+    base: str,
+    head: str,
+) -> tuple[list[PathChange], str | None]:
+    command = ["git", "diff", "--name-status", "-z", "--find-renames", f"{base}...{head}", "--"]
+    try:
+        result = subprocess.run(command, cwd=repo, capture_output=True)
+    except FileNotFoundError:
+        return [], "Git is not installed or is not on PATH"
+    if result.returncode != 0:
+        diagnostic = os.fsdecode(result.stderr).strip()
+        return [], diagnostic or f"git diff exited {result.returncode}"
+    return parse_diff_output(result.stdout)
+
+
+def parse_complete_history_output(
+    stdout: bytes,
+    *,
+    budget: EvidenceBudget,
+) -> tuple[list[CompleteHistoryRecord], EvidenceCounts, str | None]:
+    """Parse complete name-status history with explicit resource accounting."""
+    records: list[CompleteHistoryRecord] = []
+    current: CompleteHistoryRecord | None = None
+    path_count = 0
+    tokens = stdout.split(b"\0")
+    index = 0
+    while index < len(tokens):
+        token = os.fsdecode(tokens[index])
+        structural = token.lstrip("\r\n")
+        if structural.startswith("\x1e"):
+            if current is not None:
+                records.append(current)
+                if len(records) > budget.max_records:
+                    counts = EvidenceCounts(len(records), path_count, len(stdout))
+                    return [], counts, "history exceeds the configured record ceiling"
+            fields = structural[1:].split(_FIELD, 3)
+            current = None
+            if len(fields) != 4:
+                return (
+                    [],
+                    EvidenceCounts(len(records), path_count, len(stdout)),
+                    ("git log returned malformed commit metadata"),
+                )
+            current = {
+                "commit": fields[0],
+                "date": fields[1][:10],
+                "subject": fields[2],
+                "parents": fields[3].split() if fields[3] else [],
+                "changes": [],
+            }
+            index += 1
+            continue
+        status = structural
+        rename_or_copy = re.fullmatch(r"[RC][0-9]+", status)
+        tuple_paths = 2 if rename_or_copy else 1
+        if current is None or not re.fullmatch(r"(?:[RC][0-9]+|[ACDMRTUXB]+)", status):
+            index += 1
+            continue
+        if index + tuple_paths >= len(tokens):
+            return (
+                [],
+                EvidenceCounts(len(records), path_count, len(stdout)),
+                ("git log returned an incomplete NUL-delimited path record"),
+            )
+        paths = [os.fsdecode(tokens[index + offset]) for offset in range(1, tuple_paths + 1)]
+        path_count += tuple_paths
+        if path_count > budget.max_paths:
+            counts = EvidenceCounts(len(records), path_count, len(stdout))
+            return [], counts, "history exceeds the configured path ceiling"
+        current["changes"].append(
+            {"status": status, "path": paths[0]}
+            if tuple_paths == 1
+            else {"status": status, "old_path": paths[0], "path": paths[1]}
+        )
+        index += tuple_paths + 1
+    if current is not None:
+        records.append(current)
+    counts = EvidenceCounts(len(records), path_count, len(stdout))
+    if counts.records > budget.max_records:
+        return [], counts, "history exceeds the configured record ceiling"
+    return records, counts, None
+
+
+def read_complete_history(
+    repo: Path,
+    *,
+    cutoff: str,
+    budget: EvidenceBudget | None = None,
+) -> tuple[list[CompleteHistoryRecord], EvidenceCounts, str | None]:
+    """Read complete history while stopping before unbounded stdout allocation."""
+    active_budget = budget or EvidenceBudget()
+    command = [
+        "git",
+        "log",
+        "--reverse",
+        "--topo-order",
+        "--full-history",
+        "--diff-merges=combined",
+        "--find-renames=50%",
+        f"--format=\x1e%H{_FIELD}%aI{_FIELD}%s{_FIELD}%P",
+        "--name-status",
+        "-z",
+        "--end-of-options",
+        cutoff,
+    ]
+    try:
+        process = subprocess.Popen(
+            command,
+            cwd=repo,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+        )
+    except OSError as exc:
+        return [], EvidenceCounts(0, 0, 0), f"could not run Git: {exc}"
+    stdout, stderr, transport_error = communicate_bounded(
+        process,
+        max_bytes=active_budget.max_bytes,
+    )
+    total_bytes = len(stdout) + len(stderr)
+    if transport_error is not None:
+        return (
+            [],
+            EvidenceCounts(0, 0, total_bytes),
+            (
+                "history exceeds the configured byte ceiling"
+                if "ceiling" in transport_error
+                else transport_error
+            ),
+        )
+    if process.returncode != 0:
+        diagnostic = os.fsdecode(stderr).strip()
+        return (
+            [],
+            EvidenceCounts(0, 0, total_bytes),
+            (diagnostic or f"git log exited {process.returncode}"),
+        )
+    records, counts, error = parse_complete_history_output(stdout, budget=active_budget)
+    return records, EvidenceCounts(counts.records, counts.paths, total_bytes), error