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

context_engineering/analysis/context_check.py

@@ -0,0 +1,253 @@
+"""Compose deterministic contract checks with advisory diff review."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..checks import contracts, frontmatter, references, skill_structure
+from ..domain.finding import Finding, Severity
+from ..domain.result import AnalysisResult
+from ..infra.git import git_root
+from ..infra.git_tree import materialize_tree
+from . import context_review
+from .context_layout import RepositoryContextLayout, discover, is_ignored_contract_path
+
+
+def _relative_owners(layout: RepositoryContextLayout) -> tuple[Path, ...]:
+    roots = {
+        *(path.parent for path in layout.specs),
+        *(tree.path.parent for tree in layout.adr_trees),
+        *(tree.path for tree in layout.docs_trees),
+        *(path.parent for path in layout.agents_files),
+        *(tree for tree in layout.skill_roots),
+    }
+    relative = (path.relative_to(layout.root) for path in roots)
+    return tuple(sorted(relative, key=lambda path: path.as_posix()))
+
+
+def _affected_roots(
+    owners: tuple[Path, ...], changed: list[dict[str, str]], *, all_context: bool
+) -> tuple[Path, ...]:
+    if all_context:
+        return owners
+    affected: set[Path] = set()
+    for entry in changed:
+        for raw_path in (entry.get("path"), entry.get("old_path")):
+            if raw_path is None:
+                continue
+            path = Path(raw_path)
+            matches = [root for root in owners if path == root or root in path.parents]
+            if matches:
+                affected.add(max(matches, key=lambda root: len(root.parts)))
+    return tuple(sorted(affected, key=lambda path: path.as_posix()))
+
+
+def _deleted_contract_path(entry: dict[str, str]) -> bool:
+    """Return whether a changed path removes a non-template SPEC contract."""
+    path = Path(entry["path"])
+    if entry.get("status") == "deleted":
+        return path.name == "SPEC.md" and not is_ignored_contract_path(path)
+    if entry.get("status") == "renamed":
+        old_path = Path(entry.get("old_path", ""))
+        return (
+            old_path.name == "SPEC.md"
+            and not is_ignored_contract_path(old_path)
+            and path.name != "SPEC.md"
+        )
+    return False
+
+
+def _finding_in_roots(finding: Finding, tree: Path, roots: tuple[Path, ...]) -> bool:
+    if not roots:
+        return False
+    path = Path(finding.file)
+    if path.is_absolute():
+        try:
+            relative = path.resolve().relative_to(tree.resolve())
+        except ValueError:
+            return False
+    else:
+        relative = path
+    return any(relative == root or root in relative.parents for root in roots)
+
+
+def _normalized_finding(finding: Finding, module: Path) -> Finding:
+    path = Path(finding.file)
+    if path.is_absolute():
+        try:
+            file = path.resolve().relative_to(module.resolve()).as_posix()
+        except ValueError:
+            file = finding.file
+    else:
+        file = finding.file
+    return Finding(
+        file=file,
+        line=finding.line,
+        severity=finding.severity,
+        code=finding.code,
+        message=finding.message.replace(str(module), "."),
+        hint=finding.hint,
+    )
+
+
+def _validate(module: Path) -> list[Finding]:
+    findings = [
+        *contracts.analyze(module).findings,
+        *frontmatter.lint(module).findings,
+        *references.lint(module).findings,
+    ]
+    for skill_root in discover(module).skill_roots:
+        findings.extend(skill_structure.lint(skill_root, recurse=True).findings)
+    return findings
+
+
+def analyze(
+    module: Path,
+    *,
+    base: str,
+    head: str = "HEAD",
+    all_context: bool = False,
+) -> AnalysisResult:
+    """Run one read-only PR-time journey with deterministic and advisory outputs."""
+    module = module.resolve()
+    review = context_review.analyze(module, base=base, head=head)
+    repo = git_root(module)
+    if repo is None or review.has_errors:
+        return AnalysisResult(
+            target=str(module),
+            data={**review.data, "affected_context_roots": [], "deterministic_findings": []},
+            findings=review.findings,
+        )
+    relative_module = module.relative_to(repo)
+    exact_base = str(review.data["range"]["merge_base"])
+    exact_head = str(review.data["range"]["head"])
+    findings: list[Finding] = [
+        Finding(
+            entry["path"],
+            0,
+            Severity.ERROR,
+            "context-check-contract-deleted",
+            "A SPEC.md contract was deleted in this range",
+        )
+        for entry in review.data["changed_paths"]
+        if _deleted_contract_path(entry)
+    ]
+    affected: tuple[Path, ...] = ()
+    with materialize_tree(repo, exact_base) as (base_tree, base_error):
+        if base_error is not None or base_tree is None:
+            findings.append(
+                Finding(
+                    str(module),
+                    0,
+                    Severity.ERROR,
+                    "context-check-tree-unavailable",
+                    base_error or "base tree is unavailable",
+                )
+            )
+        with materialize_tree(repo, exact_head) as (head_tree, head_error):
+            if head_error is not None or head_tree is None:
+                findings.append(
+                    Finding(
+                        str(module),
+                        0,
+                        Severity.ERROR,
+                        "context-check-tree-unavailable",
+                        head_error or "head tree is unavailable",
+                    )
+                )
+            else:
+                head_module = (head_tree / relative_module).resolve()
+                base_module = (
+                    (base_tree / relative_module).resolve() if base_tree is not None else None
+                )
+                if not head_module.is_dir():
+                    findings.append(
+                        Finding(
+                            str(relative_module),
+                            0,
+                            Severity.ERROR,
+                            "context-check-target-deleted",
+                            "The target module does not exist in the head tree",
+                        )
+                    )
+                head_layout = discover(head_module) if head_module.is_dir() else None
+                base_layout = (
+                    discover(base_module)
+                    if base_module is not None and base_module.is_dir()
+                    else None
+                )
+                head_owners = _relative_owners(head_layout) if head_layout is not None else ()
+                base_owners = _relative_owners(base_layout) if base_layout is not None else ()
+                owners = tuple(
+                    sorted(set((*head_owners, *base_owners)), key=lambda path: path.as_posix())
+                )
+                affected = _affected_roots(
+                    owners,
+                    list(review.data["changed_paths"]),
+                    all_context=all_context,
+                )
+                changed_endpoints = {
+                    path
+                    for entry in review.data["changed_paths"]
+                    for path in (entry.get("path"), entry.get("old_path"))
+                    if path is not None
+                }
+                if base_layout is not None:
+                    base_specs = {
+                        path.relative_to(base_layout.root).as_posix() for path in base_layout.specs
+                    }
+                    head_specs = (
+                        {
+                            path.relative_to(head_layout.root).as_posix()
+                            for path in head_layout.specs
+                        }
+                        if head_layout is not None
+                        else set()
+                    )
+                    findings.extend(
+                        Finding(
+                            path,
+                            0,
+                            Severity.ERROR,
+                            "context-check-contract-deleted",
+                            "A SPEC.md contract was removed from this context owner",
+                        )
+                        for path in sorted(base_specs - head_specs)
+                        if path in changed_endpoints
+                    )
+                if head_module.is_dir():
+                    head_candidates = [
+                        _normalized_finding(item, head_module) for item in _validate(head_module)
+                    ]
+                    if all_context:
+                        findings.extend(head_candidates)
+                    else:
+                        head_candidates = [
+                            item
+                            for item in head_candidates
+                            if _finding_in_roots(item, head_module, affected)
+                        ]
+                        base_candidates: set[Finding] = set()
+                        if base_module is not None and base_module.is_dir():
+                            base_candidates = {
+                                _normalized_finding(item, base_module)
+                                for item in _validate(base_module)
+                                if _finding_in_roots(item, base_module, affected)
+                            }
+                        findings.extend(
+                            item for item in head_candidates if item not in base_candidates
+                        )
+    findings = sorted(set(findings))
+    return AnalysisResult(
+        target=str(module),
+        data={
+            "range": review.data["range"],
+            "changed_paths": review.data["changed_paths"],
+            "evidence": review.data["evidence"],
+            "affected_context_roots": [path.as_posix() or "." for path in affected],
+            "deterministic_findings": [finding.to_dict() for finding in findings],
+            "advisory_routes": review.data["advisory_routes"],
+            "write_performed": False,
+        },
+        findings=findings,
+    )

context_engineering/analysis/context_layout.py

@@ -0,0 +1,111 @@
+"""Discover portable repository context owners from current filesystem truth."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from ..infra.filesystem import EXCLUDED_DIRS
+
+_ADR_NAMES = {"adr", "adrs", "decisions"}
+_ADR_PARENTS = {"architecture", "docs"}
+_AGENT_TEMPLATE_ROOTS = ((".ai", "plans", "_templates"),)
+
+
+def is_ignored_contract_path(path: Path) -> bool:
+    """Return whether a repository-relative path is an agent template artifact."""
+    return any(path.parts[: len(root)] == root for root in _AGENT_TEMPLATE_ROOTS)
+
+
+@dataclass(frozen=True)
+class ContextTree:
+    path: Path
+    framework: str | None = None
+
+
+@dataclass(frozen=True)
+class RepositoryContextLayout:
+    root: Path
+    contract_roots: tuple[Path, ...]
+    specs: tuple[Path, ...]
+    adr_trees: tuple[ContextTree, ...]
+    docs_trees: tuple[ContextTree, ...]
+    agents_files: tuple[Path, ...]
+    skill_roots: tuple[Path, ...]
+
+
+def _sort_paths(paths: set[Path]) -> tuple[Path, ...]:
+    return tuple(sorted(paths, key=lambda path: path.as_posix()))
+
+
+def _docs_framework(path: Path) -> str | None:
+    """Return the framework that owns a docs tree, when one is evidenced."""
+    parent = path.parent
+    markers = (
+        (parent / "mkdocs.yml", "mkdocs"),
+        (parent / "mkdocs.yaml", "mkdocs"),
+        (parent / "docusaurus.config.js", "docusaurus"),
+        (parent / "docusaurus.config.ts", "docusaurus"),
+        (path / "conf.py", "sphinx"),
+        (parent / "book.toml", "mdbook"),
+    )
+    return next((framework for marker, framework in markers if marker.is_file()), None)
+
+
+def discover(root: Path) -> RepositoryContextLayout:
+    """Return one conservative layout consumed by context checks and review."""
+    root = root.resolve()
+    directories: set[Path] = set()
+    specs: set[Path] = set()
+    agents_files: set[Path] = set()
+    docs_trees: set[Path] = set()
+    skill_roots: set[Path] = set()
+    for current_text, names, files in os.walk(root):
+        current = Path(current_text)
+        names[:] = sorted(
+            name
+            for name in names
+            if name not in EXCLUDED_DIRS and (not name.startswith(".") or name == ".agents")
+        )
+        directories.add(current)
+        if current.name == "docs" and "docs" not in current.relative_to(root).parts[:-1]:
+            docs_trees.add(current)
+        if current.name == "skills":
+            skill_roots.add(current)
+        if "SPEC.md" in files:
+            spec = current / "SPEC.md"
+            if not is_ignored_contract_path(spec.relative_to(root)):
+                specs.add(spec)
+        if "AGENTS.md" in files:
+            agents_files.add(current / "AGENTS.md")
+
+    spec_roots = {spec.parent for spec in specs}
+    adr_trees = {
+        directory
+        for directory in directories
+        if directory != root
+        and directory.name.casefold() in _ADR_NAMES
+        and (
+            directory.parent == root
+            or directory.parent.name.casefold() in _ADR_PARENTS
+            or directory.parent in spec_roots
+        )
+    }
+    contract_roots = {root, *spec_roots}
+    for tree in adr_trees:
+        if tree.parent.name.casefold() in _ADR_PARENTS:
+            contract_roots.add(tree.parent.parent)
+        else:
+            contract_roots.add(tree.parent)
+    return RepositoryContextLayout(
+        root=root,
+        contract_roots=_sort_paths(contract_roots),
+        specs=_sort_paths(specs),
+        adr_trees=tuple(ContextTree(path) for path in _sort_paths(adr_trees)),
+        docs_trees=tuple(
+            ContextTree(path, framework=_docs_framework(path)) for path in _sort_paths(docs_trees)
+        ),
+        agents_files=_sort_paths(agents_files),
+        skill_roots=_sort_paths(skill_roots),
+    )

context_engineering/analysis/context_review.py

@@ -0,0 +1,224 @@
+"""Inspect a Git diff without turning semantic routing hints into authority."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..domain.finding import Finding, Severity
+from ..domain.result import AnalysisResult
+from ..infra.git import git_root, resolve_commit, resolve_merge_base
+from ..infra.git_evidence import read_diff
+
+_STATUS = {
+    "A": "added",
+    "C": "copied",
+    "D": "deleted",
+    "M": "modified",
+    "R": "renamed",
+    "T": "type-changed",
+}
+
+
+def _diff(
+    repo: Path,
+    module: Path,
+    base: str,
+    head: str,
+) -> tuple[list[dict[str, str]], str | None]:
+    relative = module.relative_to(repo).as_posix()
+    changes, error = read_diff(repo, base=base, head=head)
+    if error:
+        return [], error
+    changed: list[dict[str, str]] = []
+    for change in changes:
+        raw_status = change.status
+        code = raw_status[:1]
+        entry = {"status": _STATUS.get(code, raw_status.casefold()), "path": change.path}
+        if change.old_path is not None:
+            entry["old_path"] = change.old_path
+        paths = [entry["path"], *([entry["old_path"]] if "old_path" in entry else [])]
+        in_scope = relative == "." or any(
+            path == relative or path.startswith(f"{relative}/") for path in paths
+        )
+        if not in_scope:
+            continue
+        if relative != ".":
+            for key in ("path", "old_path"):
+                if key in entry and entry[key].startswith(f"{relative}/"):
+                    entry[key] = entry[key][len(relative) + 1 :]
+        changed.append(entry)
+    return sorted(changed, key=lambda item: (item["path"], item["status"])), None
+
+
+def _route(path: str) -> list[tuple[str, str]]:
+    lowered = path.casefold()
+    routes: list[tuple[str, str]] = []
+    if Path(lowered).name == "spec.md":
+        routes.append(("SPEC.md", "the diff directly changes the current contract"))
+    has_adr_path = any(part in lowered for part in ("/adr/", "/adrs/", "/decisions/"))
+    if has_adr_path or lowered.startswith(("adr/", "adrs/")):
+        routes.append(("ADR", "the diff directly changes a decision record"))
+    if lowered.endswith("agents.md"):
+        routes.append(("AGENTS.md", "the diff changes agent routing or repository gotchas"))
+    if lowered.endswith("skill.md") or "/skills/" in lowered or lowered.startswith("skills/"):
+        routes.append(("skill", "the diff changes a repeatable agent workflow"))
+    has_doc_path = "/reference/" in lowered or "/explanation/" in lowered
+    if has_doc_path or lowered.startswith(("docs/reference/", "docs/explanation/")):
+        routes.append(
+            (
+                "architecture/reference docs",
+                "the diff changes durable explanatory or lookup context",
+            )
+        )
+    source_suffixes = {
+        ".bash",
+        ".c",
+        ".cc",
+        ".cjs",
+        ".cpp",
+        ".cs",
+        ".cxx",
+        ".dart",
+        ".ex",
+        ".exs",
+        ".fish",
+        ".go",
+        ".h",
+        ".hcl",
+        ".hpp",
+        ".java",
+        ".js",
+        ".json",
+        ".jsx",
+        ".kt",
+        ".kts",
+        ".lua",
+        ".mjs",
+        ".php",
+        ".py",
+        ".rb",
+        ".rs",
+        ".scala",
+        ".sh",
+        ".sql",
+        ".svelte",
+        ".swift",
+        ".tf",
+        ".toml",
+        ".ts",
+        ".tsx",
+        ".vue",
+        ".xml",
+        ".yaml",
+        ".yml",
+        ".zsh",
+    }
+    if not routes and Path(lowered).suffix in source_suffixes:
+        routes.extend(
+            (
+                (
+                    "SPEC.md",
+                    "implementation or configuration changed; inspect whether current "
+                    "behavior or invariants moved",
+                ),
+                (
+                    "ADR",
+                    "implementation or configuration changed; inspect whether a lasting "
+                    "decision was introduced",
+                ),
+            )
+        )
+    if not routes:
+        routes.append(("no update", "no deterministic context owner follows from the path alone"))
+    return routes
+
+
+def analyze(module: Path, *, base: str, head: str = "HEAD") -> AnalysisResult:
+    module = module.resolve()
+    repo = git_root(module)
+    if repo is None:
+        finding = Finding(
+            str(module),
+            0,
+            Severity.ERROR,
+            "context-review-not-git",
+            "Target is not in a Git repository",
+        )
+        return AnalysisResult(
+            target=str(module),
+            data={
+                "range": {"base": base, "head": head},
+                "changed_paths": [],
+                "evidence": [],
+                "advisory_routes": [],
+                "deterministic_errors": [
+                    {"code": "not-a-git-repository", "message": finding.message}
+                ],
+                "write_performed": False,
+            },
+            findings=[finding],
+        )
+    resolved_base, base_error = resolve_commit(repo, base)
+    resolved_head, head_error = resolve_commit(repo, head)
+    findings: list[Finding] = []
+    deterministic_errors: list[dict[str, str]] = []
+    merge_base: str | None = None
+    error = base_error or head_error
+    if error is None:
+        assert resolved_base is not None and resolved_head is not None
+        merge_base, error = resolve_merge_base(repo, resolved_base, resolved_head)
+    changed: list[dict[str, str]] = []
+    if error is None:
+        assert resolved_base is not None and resolved_head is not None
+        changed, error = _diff(repo, module, resolved_base, resolved_head)
+    if error:
+        deterministic_errors.append({"code": "invalid-git-range", "message": error})
+        findings.append(
+            Finding(str(module), 0, Severity.ERROR, "context-review-invalid-range", error)
+        )
+    exact_base = resolved_base or base
+    exact_head = resolved_head or head
+    evidence = [
+        {**entry, "source": "git-diff", "range": f"{exact_base}...{exact_head}"}
+        for entry in changed
+    ]
+    advisory_routes: list[dict[str, object]] = []
+    for index, entry in enumerate(changed):
+        route_reasons: dict[str, str] = {}
+        route_paths: dict[str, list[str]] = {}
+        paths = [entry["path"]]
+        if "old_path" in entry:
+            paths.append(entry["old_path"])
+        for path in paths:
+            for route, reason in _route(path):
+                route_reasons.setdefault(route, reason)
+                route_paths.setdefault(route, []).append(path)
+        for route, reason in route_reasons.items():
+            advisory_routes.append(
+                {
+                    "path": entry["path"],
+                    "paths": route_paths[route],
+                    "route": route,
+                    "reason": reason,
+                    "authority": "advisory",
+                    "evidence_index": index,
+                }
+            )
+    return AnalysisResult(
+        target=str(module),
+        data={
+            "range": {
+                "base": exact_base,
+                "head": exact_head,
+                "merge_base": merge_base,
+                "requested_base": base,
+                "requested_head": head,
+            },
+            "changed_paths": changed,
+            "evidence": evidence,
+            "advisory_routes": advisory_routes,
+            "deterministic_errors": deterministic_errors,
+            "write_performed": False,
+        },
+        findings=findings,
+    )

context_engineering/analysis/cross_cutting/__init__.py

@@ -0,0 +1,6 @@
+"""Cross-cutting analysis — pair mode + discover mode over 3 signals."""
+
+from .discover import discover
+from .pair import pair
+
+__all__ = ["discover", "pair"]

context_engineering/analysis/cross_cutting/authors.py

@@ -0,0 +1,57 @@
+"""Author-overlap signal — who ships across multiple modules?"""
+
+from __future__ import annotations
+
+from collections import Counter, defaultdict
+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 activity_by_author(
+    commits: Iterable[Commit], module_roots: list[str]
+) -> dict[str, Counter]:
+    """author → Counter{module_root: commits_touching_it}"""
+    out: dict[str, Counter] = defaultdict(Counter)
+    for commit in commits:
+        touched = {m for f in commit.files if (m := module_for_path(f, module_roots))}
+        for m in touched:
+            out[commit.author][m] += 1
+    return dict(out)
+
+
+def cross_cutting_authors(
+    activity: dict[str, Counter], *, min_modules: int = 2
+) -> list[tuple[str, dict[str, int]]]:
+    out = [
+        (author, dict(counts))
+        for author, counts in activity.items()
+        if len(counts) >= min_modules
+    ]
+    out.sort(key=lambda x: sum(x[1].values()), reverse=True)
+    return out
+
+
+def discover_partner_modules(
+    repo_root: Path, target_module: str, lookback_days: int
+) -> dict[str, Counter]:
+    """For authors of `target_module`, which *other* buckets do they ship to?"""
+    target_authors: set[str] = set()
+    author_commits: dict[str, list[list[str]]] = defaultdict(list)
+
+    for commit in git_log(repo_root, since_days=lookback_days):
+        author_commits[commit.author].append(list(commit.files))
+        if commit.touches(target_module):
+            target_authors.add(commit.author)
+
+    partners: dict[str, Counter] = defaultdict(Counter)
+    for author in target_authors:
+        for files in author_commits[author]:
+            for f in files:
+                bucket = infer(f)
+                if bucket and bucket != target_module:
+                    partners[author][bucket] += 1
+    return dict(partners)

context_engineering/analysis/cross_cutting/buckets.py

@@ -0,0 +1,40 @@
+"""Infer a module bucket from a repo-relative file path.
+
+Used by discover mode to answer "what bucket does this file belong to?" The
+patterns below cover common monorepo layouts. Anything else falls back to the
+top-level directory.
+"""
+
+from __future__ import annotations
+
+# Common generic monorepo containers. For paths under these directories, use the
+# next segment as the module name: `services/billing/api.py` -> `services/billing`.
+_PATTERNS: tuple[tuple[str, ...], ...] = (
+    ("apps",),
+    ("packages",),
+    ("services",),
+    ("libs",),
+    ("plugins",),
+    ("tools",),
+)
+
+
+def infer(path: str) -> str | None:
+    """Return the enclosing module bucket for `path`, or None for top-level files."""
+    parts = path.split("/")
+    if len(parts) < 2:
+        return None
+    for pattern in _PATTERNS:
+        if len(parts) > len(pattern) and tuple(parts[: len(pattern)]) == pattern:
+            return "/".join(parts[: len(pattern) + 1])
+    return parts[0]
+
+
+def module_for_path(rel_path: str, module_roots: list[str]) -> str | None:
+    """Match `rel_path` to the longest prefix in `module_roots`, or None."""
+    best: str | None = None
+    for root in module_roots:
+        if rel_path == root or rel_path.startswith(root.rstrip("/") + "/"):
+            if best is None or len(root) > len(best):
+                best = root
+    return best