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

context_engineering/analysis/cross_cutting/co_change.py

@@ -0,0 +1,47 @@
+"""Git co-change signal — count file pairs touched in the same commit."""
+
+from __future__ import annotations
+
+from collections import Counter
+from collections.abc import Iterable
+from pathlib import Path
+
+from ...domain.commit import Commit
+from ...infra.git import git_log
+from .buckets import infer, module_for_path
+
+
+def pairs_between(commits: Iterable[Commit], module_roots: list[str]) -> Counter:
+    """Count how often each pair of `module_roots` co-changes."""
+    pairs: Counter = Counter()
+    for commit in commits:
+        touched = {
+            m for f in commit.files if (m := module_for_path(f, module_roots))
+        }
+        ordered = sorted(touched)
+        for i in range(len(ordered)):
+            for j in range(i + 1, len(ordered)):
+                pairs[(ordered[i], ordered[j])] += 1
+    return pairs
+
+
+def discover_partners(
+    repo_root: Path, target_module: str, lookback_days: int
+) -> tuple[Counter, int]:
+    """(partners, total_commits_touching_target) — `discover` mode counterpart."""
+    partners: Counter = Counter()
+    total = 0
+    for commit in git_log(repo_root, since_days=lookback_days):
+        if not commit.touches(target_module):
+            continue
+        total += 1
+        others: set[str] = set()
+        for f in commit.files:
+            if f == target_module or f.startswith(target_module + "/"):
+                continue
+            bucket = infer(f)
+            if bucket and bucket != target_module:
+                others.add(bucket)
+        for bucket in others:
+            partners[bucket] += 1
+    return partners, total

context_engineering/analysis/cross_cutting/discover.py

@@ -0,0 +1,75 @@
+"""Discover mode — auto-find partners of a single target module."""
+
+from __future__ import annotations
+
+from collections import Counter
+from pathlib import Path
+
+from ...domain.result import AnalysisResult
+from ...infra.git import git_root
+from . import authors, co_change, imports
+
+
+def _rank(counts: Counter, *, top_n: int, min_edge: int = 0) -> list[tuple[str, int]]:
+    """Stable ranking by (-count, name) so tie-breaking is deterministic."""
+    return sorted(
+        ((k, v) for k, v in counts.items() if v >= min_edge),
+        key=lambda x: (-x[1], x[0]),
+    )[:top_n]
+
+
+def discover(
+    target_path: Path,
+    *,
+    lookback_days: int = 90,
+    min_edge: int = 3,
+    top_n: int = 10,
+    signals: frozenset[str] = frozenset({"imports", "co-change", "authors"}),
+) -> AnalysisResult:
+    repo = git_root(target_path)
+    if repo is None:
+        return AnalysisResult(
+            target=str(target_path),
+            data={"error": "not in a git repo", "mode": "discover"},
+        )
+
+    try:
+        target_rel = str(target_path.resolve().relative_to(repo.resolve()))
+    except ValueError:
+        target_rel = str(target_path)
+
+    data: dict = {
+        "repo_root": str(repo),
+        "modules": [target_rel],
+        "lookback_days": lookback_days,
+        "mode": "discover",
+    }
+
+    if "imports" in signals:
+        import_counts = imports.discover_targets(target_path, repo)
+        data["discovered_imports"] = [
+            {"module": m, "count": c}
+            for m, c in _rank(import_counts, top_n=top_n, min_edge=min_edge)
+        ]
+
+    if "co-change" in signals:
+        partners, total = co_change.discover_partners(repo, target_rel, lookback_days)
+        data["discovered_co_change"] = [
+            {"module": m, "shared_commits": c}
+            for m, c in _rank(partners, top_n=top_n, min_edge=min_edge)
+        ]
+        data["co_change_total_commits_touching_target"] = total
+
+    if "authors" in signals:
+        author_partners = authors.discover_partner_modules(repo, target_rel, lookback_days)
+        module_to_authors: Counter = Counter()
+        for counts in author_partners.values():
+            for m in counts:
+                module_to_authors[m] += 1
+        data["discovered_by_authors"] = [
+            {"module": m, "shared_authors": c}
+            for m, c in _rank(module_to_authors, top_n=top_n, min_edge=min_edge)
+        ]
+        data["target_author_count"] = len(author_partners)
+
+    return AnalysisResult(target=target_rel, data=data)

context_engineering/analysis/cross_cutting/imports.py

@@ -0,0 +1,61 @@
+"""Static-import signal — collect Python imports, count cross-module edges."""
+
+from __future__ import annotations
+
+import re
+from collections import Counter
+from pathlib import Path
+
+from .buckets import infer, module_for_path
+
+_IMPORT_RE = re.compile(
+    r"^\s*(?:from\s+([a-zA-Z0-9_.]+)\s+import\b|import\s+([a-zA-Z0-9_.]+))",
+    re.MULTILINE,
+)
+
+
+def collect(module_path: Path) -> set[str]:
+    """Every dotted import path referenced from Python files under `module_path`."""
+    imports: set[str] = set()
+    for py in module_path.rglob("*.py"):
+        try:
+            content = py.read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            continue
+        for match in _IMPORT_RE.finditer(content):
+            name = match.group(1) or match.group(2)
+            if name:
+                imports.add(name)
+    return imports
+
+
+def edges_between(
+    module_paths: list[Path], module_roots: list[str]
+) -> dict[str, Counter]:
+    """For each source module, count imports that resolve into a *different* input module."""
+    result: dict[str, Counter] = {root: Counter() for root in module_roots}
+    for src_path, src_root in zip(module_paths, module_roots, strict=True):
+        for imp in collect(src_path):
+            imp_path = imp.replace(".", "/")
+            target = module_for_path(imp_path, module_roots)
+            if target and target != src_root:
+                result[src_root][target] += 1
+    return result
+
+
+def discover_targets(module_path: Path, repo_root: Path) -> Counter:
+    """Count buckets the input imports from (for discover mode)."""
+    try:
+        src_bucket = infer(str(module_path.relative_to(repo_root)))
+    except ValueError:
+        src_bucket = None
+
+    counts: Counter = Counter()
+    for imp in collect(module_path):
+        bucket = infer(imp.replace(".", "/"))
+        if bucket is None or bucket == src_bucket:
+            continue
+        if not (repo_root / bucket).exists():
+            continue
+        counts[bucket] += 1
+    return counts

context_engineering/analysis/cross_cutting/pair.py

@@ -0,0 +1,118 @@
+"""Pair mode — coupling between N specified modules."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ...domain.finding import Finding, Severity
+from ...domain.result import AnalysisResult
+from ...infra.git import git_log, git_root
+from . import authors, co_change, imports
+
+
+def _resolve_modules(
+    module_paths: list[Path], repo: Path
+) -> tuple[list[Path], list[str], list[Finding]]:
+    """Drop paths outside `repo`, returning a warning Finding for each drop.
+
+    Both sides are resolved (symlinks followed) so a repo root reported by
+    `git rev-parse` with a symlink component matches the same physical path
+    the user supplied — matching what discover mode does.
+    """
+    repo_resolved = repo.resolve()
+    inside_paths: list[Path] = []
+    inside_roots: list[str] = []
+    warnings: list[Finding] = []
+    for mp in module_paths:
+        try:
+            inside_roots.append(str(mp.resolve().relative_to(repo_resolved)))
+            inside_paths.append(mp)
+        except ValueError:
+            warnings.append(
+                Finding(
+                    file=str(mp),
+                    line=0,
+                    severity=Severity.WARNING,
+                    code="cross-cutting-path-outside-repo",
+                    message=f"skipping {mp}: not under repo root {repo}",
+                )
+            )
+    return inside_paths, inside_roots, warnings
+
+
+def _repo_for_any_path(module_paths: list[Path]) -> Path | None:
+    """Return the git root for the first path that is inside a repository."""
+    for module_path in module_paths:
+        repo = git_root(module_path)
+        if repo is not None:
+            return repo
+    return None
+
+
+def pair(
+    module_paths: list[Path],
+    *,
+    lookback_days: int = 90,
+    min_edge: int = 3,
+    signals: frozenset[str] = frozenset({"imports", "co-change", "authors"}),
+) -> AnalysisResult:
+    if not module_paths:
+        return AnalysisResult(
+            target="<not-a-repo>", data={"error": "no module paths provided", "mode": "pair"}
+        )
+
+    repo = _repo_for_any_path(module_paths)
+    if repo is None:
+        return AnalysisResult(
+            target="<not-a-repo>", data={"error": "not in a git repo", "mode": "pair"}
+        )
+
+    resolved_paths, module_roots, findings = _resolve_modules(module_paths, repo)
+
+    data: dict = {
+        "repo_root": str(repo),
+        "modules": module_roots,
+        "lookback_days": lookback_days,
+        "mode": "pair",
+    }
+
+    if "imports" in signals:
+        edges = imports.edges_between(resolved_paths, module_roots)
+        data["import_edges"] = {
+            src: [
+                {"target": t, "count": c}
+                # -count primary, name secondary → stable ordering.
+                # Apply min_edge consistently — discover mode filters all
+                # three signals, and pair's co-change does too.
+                for t, c in sorted(cs.items(), key=lambda x: (-x[1], x[0]))
+                if c >= min_edge
+            ]
+            for src, cs in edges.items()
+        }
+
+    # Share the history walk: co-change wants commits that touch a module
+    # root; authors wants the full stream. Pull once, slice twice.
+    if {"co-change", "authors"} & signals:
+        all_commits = list(git_log(repo, since_days=lookback_days))
+
+        if "co-change" in signals:
+            touching = [
+                c for c in all_commits
+                if any(c.touches(r) for r in module_roots)
+            ]
+            pairs = co_change.pairs_between(touching, module_roots)
+            data["co_change_pairs"] = [
+                {"modules": list(p), "commits": c}
+                for p, c in sorted(pairs.items(), key=lambda x: (-x[1], x[0]))
+                if c >= min_edge
+            ]
+            data["co_change_total_commits"] = len(touching)
+
+        if "authors" in signals:
+            activity = authors.activity_by_author(all_commits, module_roots)
+            data["cross_cutting_authors"] = [
+                {"author": a, "modules": m}
+                for a, m in authors.cross_cutting_authors(activity, min_modules=2)
+            ]
+
+    return AnalysisResult(target=str(module_paths[0]), data=data, findings=findings)

context_engineering/analysis/impact.py

@@ -0,0 +1,77 @@
+"""Classify changed files by impact (HIGH / MEDIUM / LOW).
+
+The patterns live here — staleness.py just calls classify() so there's one
+place to add a new high-impact filename.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class Impact(StrEnum):
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+
+
+@dataclass(frozen=True)
+class ImpactClassification:
+    impact: Impact
+    reason: str
+
+
+def _rule(pattern: str, reason: str) -> tuple[re.Pattern[str], str]:
+    return re.compile(pattern), reason
+
+
+_HIGH = (
+    _rule(r"(^|/)package\.json$", "dependency manifest"),
+    _rule(r"(^|/)pyproject\.toml$", "Python project manifest"),
+    _rule(r"(^|/)Cargo\.toml$", "Rust project manifest"),
+    _rule(r"(^|/)go\.(mod|sum)$", "Go dependency manifest"),
+    _rule(r"(^|/)pom\.xml$", "Maven project manifest"),
+    _rule(r"(^|/)build\.gradle", "Gradle build configuration"),
+    _rule(r"(^|/)Makefile$", "Make build entrypoint"),
+    _rule(r"(^|/)Taskfile", "Task runner configuration"),
+    _rule(r"(^|/)justfile$", "Just task runner configuration"),
+    _rule(r"(^|/)\.mise\.toml$", "mise task and tool configuration"),
+    _rule(r"(^|/)\.github/workflows/", "GitHub Actions workflow"),
+    _rule(r"(^|/)\.gitlab-ci", "GitLab CI configuration"),
+    _rule(r"(^|/)Jenkinsfile", "Jenkins pipeline"),
+    _rule(r"(^|/)Dockerfile", "container build definition"),
+    _rule(r"(^|/)docker-compose", "container composition configuration"),
+    _rule(r"(^|/)\.pre-commit-config\.yaml$", "pre-commit configuration"),
+)
+
+_MEDIUM = (
+    _rule(r"(^|/)README", "README documentation"),
+    _rule(r"(^|/)CHANGELOG", "changelog"),
+    _rule(r"(^|/)setup\.(py|cfg)$", "Python package configuration"),
+    _rule(r"(^|/)requirements.*\.txt$", "Python dependency list"),
+)
+
+
+def classify_with_reason(filepath: str) -> ImpactClassification:
+    for pattern, reason in _HIGH:
+        if pattern.search(filepath):
+            return ImpactClassification(Impact.HIGH, f"matched high-impact rule: {reason}")
+    for pattern, reason in _MEDIUM:
+        if pattern.search(filepath):
+            return ImpactClassification(Impact.MEDIUM, f"matched medium-impact rule: {reason}")
+    # Shallow paths (top-level changes) default to MEDIUM; deep paths are LOW
+    if len(filepath.split("/")) <= 2:
+        return ImpactClassification(
+            Impact.MEDIUM,
+            "no named rule matched; paths at depth 2 or less default to medium impact",
+        )
+    return ImpactClassification(
+        Impact.LOW,
+        "no named rule matched; paths deeper than 2 components default to low impact",
+    )
+
+
+def classify(filepath: str) -> Impact:
+    return classify_with_reason(filepath).impact

context_engineering/analysis/sessions.py

@@ -0,0 +1,27 @@
+"""Optional session-artifact discovery with no assumed agent or home-directory layout."""
+from __future__ import annotations
+from pathlib import Path
+from ..domain.result import AnalysisResult
+
+def analyze(project_path: str, max_results: int = 20, sessions_dir: str | None = None) -> AnalysisResult:
+    """Return explicit unavailable evidence unless the caller configures a directory.
+
+    This portable fallback deliberately never searches a personal agent-history path.
+    A caller may supply exported JSONL artifacts through a configured directory.
+    """
+    result=AnalysisResult(target=project_path)
+    root=Path(sessions_dir).expanduser() if sessions_dir else None
+    if root is None:
+        result.data={"state":"unavailable", "reason":"No session artifact directory was configured; continue without session evidence."}
+        return result
+    if not root.is_dir():
+        result.data={"state":"unavailable", "reason":"Configured session artifact directory does not exist."}
+        return result
+    target=str(Path(project_path).resolve())
+    hits=[]
+    for artifact in root.rglob("*.jsonl"):
+        try: count=artifact.read_text(encoding="utf-8").count(target)
+        except OSError: continue
+        if count: hits.append((count,artifact))
+    result.data={"state":"available", "sessions":[{"path":str(artifact),"mentions":count} for count, artifact in sorted(hits, reverse=True)[:max_results]]}
+    return result

context_engineering/analysis/staleness.py

@@ -0,0 +1,179 @@
+"""Recommend whether an AGENTS.md needs refreshing based on recent git activity."""
+
+from __future__ import annotations
+
+import datetime
+from pathlib import Path
+
+from ..domain.result import AnalysisResult
+from ..infra.git import git_log, git_root
+from .impact import Impact, classify_with_reason
+
+
+def _last_update(agents_path: Path) -> tuple[str, str]:
+    """(sha, iso_date) of the most recent commit that touched `agents_path`."""
+    repo = git_root(agents_path.parent)
+    if repo is None:
+        return "", ""
+    # `git log -- <path>` pathspecs are repo-relative, and git_log runs from
+    # the repo root. Pass the full repo-relative path so nested AGENTS.md
+    # files (e.g. services/payments/AGENTS.md) actually match their history.
+    try:
+        rel = str(agents_path.resolve().relative_to(repo.resolve()))
+    except ValueError:
+        return "", ""
+    commit = next(git_log(repo, paths=[rel], max_count=1), None)
+    if commit is None:
+        return "", ""
+    return commit.sha, commit.date.isoformat()
+
+
+def _days_since(iso_date: str) -> int:
+    if not iso_date:
+        return 0
+    try:
+        dt = datetime.datetime.fromisoformat(iso_date)
+    except ValueError:
+        return -1
+    return (datetime.datetime.now(datetime.UTC) - dt).days
+
+
+def recommend(*, commits_since: int, high: int, medium: int, days_since: int) -> str:
+    if commits_since == 0:
+        return "skip"
+    if days_since > 30 or commits_since > 50:
+        return "full-rebuild"
+    if high > 0:
+        return "full-update"
+    if medium > 0:
+        return "partial-update"
+    return "skip"
+
+
+def _recommendation_reasons(
+    *, commits_since: int, high: int, medium: int, days_since: int
+) -> list[str]:
+    if commits_since == 0:
+        return ["no commits touched the scoped module since the AGENTS.md update"]
+    if days_since > 30 or commits_since > 50:
+        reasons = []
+        if days_since > 30:
+            reasons.append(f"{days_since} days exceeds the 30-day rebuild threshold")
+        if commits_since > 50:
+            reasons.append(
+                f"{commits_since} commits exceeds the 50-commit rebuild threshold"
+            )
+        return reasons
+    if high > 0:
+        return [f"{high} changed paths matched high-impact rules"]
+    if medium > 0:
+        return [f"{medium} changed paths classified medium impact"]
+    return ["all changed paths defaulted to low impact"]
+
+
+def analyze(agents_path: Path) -> AnalysisResult:
+    agents_path = agents_path.resolve()
+
+    if not agents_path.exists():
+        return AnalysisResult(
+            target=str(agents_path),
+            data={
+                "recommendation": "full-rebuild",
+                "recommendation_advisory": True,
+                "recommendation_reasons": ["the target AGENTS.md does not exist"],
+                "changed_files": [],
+                "error": f"{agents_path} not found",
+            },
+        )
+
+    repo = git_root(agents_path)
+    if repo is None:
+        return AnalysisResult(
+            target=str(agents_path),
+            data={
+                "recommendation": "full-rebuild",
+                "recommendation_advisory": True,
+                "recommendation_reasons": ["the target is not in a git repository"],
+                "changed_files": [],
+                "error": "Not a git repository",
+            },
+        )
+
+    last_sha, last_date = _last_update(agents_path)
+
+    # Scope the scan to the module directory — for a nested AGENTS.md like
+    # `services/payments/AGENTS.md`, we only care about commits that touched
+    # `services/payments/`. Walking the entire repo inflates commit counts and
+    # counts unrelated Dockerfiles/CI configs as HIGH-impact, which made
+    # the recommendation default to "full-rebuild" for every non-root
+    # AGENTS.md in a busy monorepo.
+    try:
+        scope = str(agents_path.parent.resolve().relative_to(repo.resolve()))
+    except ValueError:
+        scope = "."
+    scope_paths = [scope] if scope and scope != "." else None
+
+    commits_iter = (
+        git_log(repo, since_ref=last_sha, paths=scope_paths)
+        if last_sha
+        else git_log(repo, paths=scope_paths)
+    )
+    commits = 0
+    files: set[str] = set()
+    for commit in commits_iter:
+        commits += 1
+        files.update(commit.files)
+
+    changed_files: list[dict[str, str]] = []
+    impact_counts = {impact: 0 for impact in Impact}
+    for f in sorted(files):
+        classification = classify_with_reason(f)
+        impact_counts[classification.impact] += 1
+        changed_files.append(
+            {
+                "path": f,
+                "impact": classification.impact.value,
+                "classification_reason": classification.reason,
+            }
+        )
+
+    days_since = _days_since(last_date)
+    # A never-committed AGENTS.md (`last_sha == ""`) is not "fresh" — it's
+    # untracked. Force full-rebuild instead of letting days_since=0 trick the
+    # heuristic into "skip".
+    if not last_sha:
+        rec = "full-rebuild"
+    else:
+        rec = recommend(
+            commits_since=commits,
+            high=impact_counts[Impact.HIGH],
+            medium=impact_counts[Impact.MEDIUM],
+            days_since=days_since,
+        )
+
+    if not last_sha:
+        recommendation_reasons = ["the AGENTS.md has no committed update"]
+    else:
+        recommendation_reasons = _recommendation_reasons(
+            commits_since=commits,
+            high=impact_counts[Impact.HIGH],
+            medium=impact_counts[Impact.MEDIUM],
+            days_since=days_since,
+        )
+
+    return AnalysisResult(
+        target=str(agents_path),
+        data={
+            "agents_file": str(agents_path),
+            "last_updated": {"commit": last_sha, "date": last_date},
+            "commits_since": commits,
+            "days_since": days_since,
+            "changed_files": changed_files,
+            "impact_summary": {
+                impact.value: impact_counts[impact] for impact in Impact
+            },
+            "recommendation": rec,
+            "recommendation_advisory": True,
+            "recommendation_reasons": recommendation_reasons,
+        },
+    )

context_engineering/analysis/tier.py

@@ -0,0 +1,91 @@
+"""Classify a module's opinion-density tier from its recent unique authors."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..domain.result import AnalysisResult
+from ..infra.git import git_log, git_root
+
+_TIERS: tuple[tuple[int, str], ...] = (
+    (0, "unknown"),
+    (1, "1"),
+    (5, "2-5"),
+    (20, "6-20"),
+)
+
+
+def classify(unique_authors: int) -> str:
+    for threshold, label in _TIERS:
+        if unique_authors <= threshold:
+            return label
+    return "21+"
+
+
+_GUIDANCE: dict[str, dict[str, str]] = {
+    "unknown": {
+        "multi_path_commands": (
+            "No history in lookback window — default to listing options neutrally; "
+            "be conservative"
+        ),
+        "how_to_work_here": (
+            "No tier signal — skip unless code structure makes a canonical flow obvious"
+        ),
+        "gotcha_budget_default": "5-7",
+    },
+    "1": {
+        "multi_path_commands": "Pick the canonical path; one contributor owns it",
+        "how_to_work_here": "Opinionated step-by-step is appropriate",
+        "gotcha_budget_default": "7",
+    },
+    "2-5": {
+        "multi_path_commands": "Pick a default with a one-line rationale",
+        "how_to_work_here": "Opinionated, validated by the small team",
+        "gotcha_budget_default": "7",
+    },
+    "6-20": {
+        "multi_path_commands": "List options with tradeoff notes; don't prescribe a default",
+        "how_to_work_here": "Brief pointer to canonical flow",
+        "gotcha_budget_default": "7",
+    },
+    "21+": {
+        "multi_path_commands": "List options neutrally or defer to --help / nested AGENTS.md",
+        "how_to_work_here": "Drop; candidates go to SKIPPED_FOR_REVIEW.md",
+        "gotcha_budget_default": "5-7",
+    },
+}
+
+
+def guidance(tier: str) -> dict[str, str]:
+    return dict(_GUIDANCE[tier])
+
+
+def analyze(module_path: Path, *, lookback_days: int = 90) -> AnalysisResult:
+    repo = git_root(module_path)
+    try:
+        target = (
+            str(module_path.resolve().relative_to(repo.resolve()))
+            if repo
+            else str(module_path)
+        )
+    except ValueError:
+        target = str(module_path)
+
+    authors: set[str] = set()
+    total = 0
+    for commit in git_log(module_path, since_days=lookback_days, paths=[target]):
+        authors.add(commit.author)
+        total += 1
+
+    tier = classify(len(authors))
+    return AnalysisResult(
+        target=target,
+        data={
+            "path": target,
+            "lookback_days": lookback_days,
+            "unique_authors": len(authors),
+            "total_commits": total,
+            "tier": tier,
+            "guidance": guidance(tier),
+        },
+    )

context_engineering/checks/__init__.py

@@ -0,0 +1 @@
+"""Linters — each produces Iterator[Finding]."""

context_engineering/checks/antipatterns/__init__.py

@@ -0,0 +1,5 @@
+"""Antipattern checkers — each a pure function yielding Findings."""
+
+from .runner import lint
+
+__all__ = ["lint"]