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

context_engineering/checks/antipatterns/context.py

@@ -0,0 +1,23 @@
+"""Context passed to each checker — depth, modified flag, shared git metadata."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class CheckContext:
+    root: Path
+    git_root: Path | None
+    modified_only: bool
+
+    def depth(self, path: Path) -> int:
+        """Depth of `path.parent` relative to git root. Falls back to 2 (leaf default)."""
+        if self.git_root is None:
+            return 2
+        try:
+            rel = path.parent.resolve().relative_to(self.git_root.resolve())
+            return len([p for p in rel.parts if p != "."])
+        except ValueError:
+            return 2

context_engineering/checks/antipatterns/density.py

@@ -0,0 +1,72 @@
+"""P2: section density — long prose with no file refs or DO/NOT/BECAUSE bullets.
+
+Heuristic: an H2 section with 5+ prose lines and no file:line references and no
+DO/NOT/BECAUSE markers is drifting architecture prose that belongs in docs/.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterator
+from pathlib import Path
+
+from ...domain.finding import Finding, Severity
+from ...infra.filesystem import read_text_safe
+from .context import CheckContext
+
+_FILE_REF_RE = re.compile(r"`[^`]+:\d+`|`[^`]+\.[a-z]+`")
+_MARKER_RE = re.compile(r"\*\*DO\*\*|\*\*NOT\*\*|\*\*BECAUSE\*\*")
+_MIN_PROSE = 5
+
+
+def _is_prose(line: str) -> bool:
+    s = line.strip()
+    return bool(s) and not s.startswith(("#", "-", "*", "|", ">", "```"))
+
+
+def _evaluate_section(
+    path: Path, section: str, start_line: int, body: list[str]
+) -> Iterator[Finding]:
+    prose = [ln for ln in body if _is_prose(ln)]
+    if len(prose) <= _MIN_PROSE:
+        return
+    if any(_FILE_REF_RE.search(ln) for ln in body):
+        return
+    if any(_MARKER_RE.search(ln) for ln in body):
+        return
+    yield Finding(
+        file=str(path),
+        line=start_line,
+        severity=Severity.INFO,
+        code="P2-low-density",
+        message=(
+            f"Section '{section}' has {len(prose)} prose lines with no "
+            "file:line references or DO/NOT/BECAUSE bullets"
+        ),
+        hint="Consider cutting, adding specific references, or moving to docs/",
+    )
+
+
+def check(path: Path, _ctx: CheckContext) -> Iterator[Finding]:
+    if path.name not in ("AGENTS.md", "CLAUDE.md"):
+        return
+    content = read_text_safe(path)
+    if content is None:
+        return
+
+    current: str | None = None
+    start = 0
+    body: list[str] = []
+
+    for i, line in enumerate(content.splitlines(), 1):
+        if line.startswith("## "):
+            if current is not None:
+                yield from _evaluate_section(path, current, start, body)
+            current = line.lstrip("# ").strip()
+            start = i
+            body = []
+        elif current is not None:
+            body.append(line)
+
+    if current is not None:
+        yield from _evaluate_section(path, current, start, body)

context_engineering/checks/antipatterns/line_limits.py

@@ -0,0 +1,52 @@
+"""P11: depth-tiered line limits for AGENTS.md and docs/ files."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from pathlib import Path
+
+from ...domain.finding import Finding, Severity
+from ...infra.filesystem import read_text_safe
+from .context import CheckContext
+
+LIMITS: dict[str, tuple[int, int]] = {
+    "depth_0_agents": (80, 120),
+    "depth_1_agents": (150, 200),
+    "depth_2plus_agents": (250, 300),
+    "docs": (300, 500),
+}
+
+
+def _limits_for(path: Path, depth: int) -> tuple[tuple[int, int], str]:
+    is_docs = "docs" in path.parts and path.name not in ("AGENTS.md", "README.md")
+    if is_docs:
+        return LIMITS["docs"], "docs/ file"
+    if depth == 0:
+        return LIMITS["depth_0_agents"], "root AGENTS.md (depth 0)"
+    if depth == 1:
+        return LIMITS["depth_1_agents"], f"module AGENTS.md (depth {depth})"
+    return LIMITS["depth_2plus_agents"], f"leaf AGENTS.md (depth {depth})"
+
+
+def check(path: Path, ctx: CheckContext) -> Iterator[Finding]:
+    content = read_text_safe(path)
+    if content is None:
+        return
+    line_count = len(content.splitlines())
+    depth = ctx.depth(path)
+    (target, hard_stop), label = _limits_for(path, depth)
+
+    if line_count > hard_stop:
+        yield Finding(
+            file=str(path), line=line_count, severity=Severity.WARNING,
+            code="P11-size-hard-stop",
+            message=f"{label} exceeds hard stop: {line_count}L > {hard_stop}L",
+            hint=f"target: {target}, hard stop: {hard_stop}",
+        )
+    elif line_count > target:
+        yield Finding(
+            file=str(path), line=line_count, severity=Severity.INFO,
+            code="P11-size-warning",
+            message=f"{label} exceeds target: {line_count}L > {target}L (hard stop: {hard_stop})",
+            hint=f"target: {target}, hard stop: {hard_stop}",
+        )

context_engineering/checks/antipatterns/runner.py

@@ -0,0 +1,137 @@
+"""Compose the 5 antipattern checkers over a discovered file set."""
+
+from __future__ import annotations
+
+import subprocess
+from collections.abc import Callable, Iterable, Iterator
+from pathlib import Path
+
+from ...domain.finding import Finding
+from ...domain.result import LintResult
+from ...infra.filesystem import EXCLUDED_DIRS
+from ...infra.git import git_root
+from . import density, line_limits, splitting, volatile, watermark
+from .context import CheckContext
+
+# Checker signature: (path, ctx) -> Iterator[Finding]
+Checker = Callable[[Path, CheckContext], Iterator[Finding]]
+
+# Universal checkers — run on every candidate file.
+UNIVERSAL: tuple[Checker, ...] = (
+    volatile.check,
+    watermark.check_presence,
+    watermark.check_staleness,
+    density.check,
+)
+
+# Checkers that apply only to AGENTS.md / CLAUDE.md
+AGENTS_ONLY: tuple[Checker, ...] = (
+    line_limits.check,
+    splitting.check,
+)
+
+# Checkers that apply only to docs/*.md (non-AGENTS, non-README)
+DOCS_ONLY: tuple[Checker, ...] = (
+    line_limits.check,
+)
+
+
+def _is_candidate(path: Path) -> bool:
+    if any(p in EXCLUDED_DIRS for p in path.parts):
+        return False
+    return (
+        path.name == "AGENTS.md"
+        or path.name == "CLAUDE.md"
+        or "docs" in path.parts
+    )
+
+
+def _git_tracked_md(root: Path) -> list[Path]:
+    try:
+        result = subprocess.run(
+            ["git", "ls-files", "--cached", "--others", "--exclude-standard", "*.md"],
+            capture_output=True, text=True, cwd=root,
+        )
+    except FileNotFoundError:
+        return []
+    if result.returncode != 0:
+        return []
+    return [root / p for p in result.stdout.strip().splitlines() if p]
+
+
+def _git_modified_md(root: Path, gr: Path) -> list[Path]:
+    try:
+        result = subprocess.run(
+            ["git", "status", "--porcelain", "-u"],
+            capture_output=True, text=True, cwd=root,
+        )
+    except FileNotFoundError:
+        return []
+    if result.returncode != 0:
+        return []
+    files: list[Path] = []
+    for line in result.stdout.strip().splitlines():
+        if len(line) < 4:
+            continue
+        path_str = line[3:].strip()
+        if " -> " in path_str:
+            path_str = path_str.split(" -> ")[-1]
+        if not path_str.endswith(".md"):
+            continue
+        full = (gr / path_str).resolve()
+        try:
+            full.relative_to(root.resolve())
+            files.append(full)
+        except ValueError:
+            continue
+    return files
+
+
+def _filesystem_fallback(root: Path) -> Iterable[Path]:
+    """Used outside git — targeted walk, not full rglob."""
+    if (root / "AGENTS.md").exists():
+        yield root / "AGENTS.md"
+    docs = root / "docs"
+    if docs.is_dir():
+        yield from sorted(docs.rglob("*.md"))
+    for child in sorted(root.iterdir()):
+        if child.is_dir() and not child.name.startswith("."):
+            nested = child / "AGENTS.md"
+            if nested.exists():
+                yield nested
+
+
+def _discover(root: Path, gr: Path | None, modified_only: bool) -> list[Path]:
+    if modified_only and gr is not None:
+        return _git_modified_md(root, gr)
+    candidates = _git_tracked_md(root) if gr is not None else []
+    if not candidates and not modified_only:
+        candidates = list(_filesystem_fallback(root))
+    return candidates
+
+
+def _checkers_for(path: Path) -> Iterable[Checker]:
+    yield from UNIVERSAL
+    if path.name in ("AGENTS.md", "CLAUDE.md"):
+        yield from AGENTS_ONLY
+    elif "docs" in path.parts and path.name != "README.md":
+        yield from DOCS_ONLY
+
+
+def lint(root: Path, *, modified_only: bool = False) -> LintResult:
+    gr = git_root(root)
+    ctx = CheckContext(root=root, git_root=gr, modified_only=modified_only)
+
+    seen: set[Path] = set()
+    findings: list[Finding] = []
+    for path in _discover(root, gr, modified_only):
+        if not path.is_file():
+            continue
+        resolved = path.resolve()
+        if resolved in seen or not _is_candidate(path):
+            continue
+        seen.add(resolved)
+        for checker in _checkers_for(path):
+            findings.extend(checker(path, ctx))
+
+    return LintResult(target=str(root), findings=findings)

context_engineering/checks/antipatterns/splitting.py

@@ -0,0 +1,97 @@
+"""P3: splitting-candidate — 3+ gotcha bullets clustering under a common path.
+
+Signal that the AGENTS.md wants to be split — promote a nested
+<subdir>/AGENTS.md rather than pack more into the current one.
+"""
+
+from __future__ import annotations
+
+import re
+from collections import Counter
+from collections.abc import Iterator
+from pathlib import Path
+
+from ...domain.finding import Finding, Severity
+from ...infra.filesystem import read_text_safe
+from .context import CheckContext
+
+_FILEREF_RE = re.compile(r"`([a-zA-Z0-9_./\-]+\.[a-zA-Z0-9_]+)(?::\d+(?:-\d+)?)?`")
+_MIN_BULLETS = 3
+
+
+def _parse_bullets(content: str) -> list[list[str]]:
+    """Return one list of referenced paths per DO bullet."""
+    bullets: list[list[str]] = []
+    current: list[str] = []
+    in_bullet = False
+
+    for line in content.splitlines():
+        stripped = line.lstrip()
+        if stripped.startswith("- **DO**"):
+            if in_bullet and current:
+                bullets.append(current)
+            current = []
+            in_bullet = True
+        elif not stripped and in_bullet:
+            if current:
+                bullets.append(current)
+            current = []
+            in_bullet = False
+
+        if in_bullet:
+            for m in _FILEREF_RE.finditer(line):
+                ref = m.group(1)
+                if "/" in ref:
+                    current.append(ref)
+
+    if in_bullet and current:
+        bullets.append(current)
+    return bullets
+
+
+def _count_prefixes(bullets: list[list[str]]) -> tuple[Counter, dict[str, list[str]]]:
+    prefix_bullets: Counter = Counter()
+    samples: dict[str, list[str]] = {}
+    for paths in bullets:
+        prefixes: set[str] = set()
+        for p in paths:
+            parts = p.split("/")
+            for n in (1, 2, 3):
+                if len(parts) > n:
+                    prefixes.add("/".join(parts[:n]))
+        for prefix in prefixes:
+            prefix_bullets[prefix] += 1
+            samples.setdefault(prefix, []).extend(paths)
+    return prefix_bullets, samples
+
+
+def check(path: Path, _ctx: CheckContext) -> Iterator[Finding]:
+    if path.name not in ("AGENTS.md", "CLAUDE.md"):
+        return
+    content = read_text_safe(path)
+    if content is None:
+        return
+
+    bullets = _parse_bullets(content)
+    prefix_bullets, samples = _count_prefixes(bullets)
+
+    for prefix, count in prefix_bullets.most_common():
+        if count < _MIN_BULLETS:
+            break
+        # Exact-segment match: `chat_bot` as file parent should NOT suppress
+        # a warning about prefix `bot` — compare leaf exactly, not endswith.
+        prefix_leaf = prefix.rsplit("/", 1)[-1]
+        if path.parent.name and prefix_leaf == path.parent.name:
+            continue
+        sample_refs = list(dict.fromkeys(samples[prefix]))[:3]
+        yield Finding(
+            file=str(path),
+            line=0,
+            severity=Severity.INFO,
+            code="splitting-candidate",
+            message=(
+                f"{count} gotcha bullets reference paths under `{prefix}/` — "
+                f"consider promoting to `{prefix}/AGENTS.md`"
+            ),
+            hint=f"sample refs: {', '.join(sample_refs)}",
+        )

context_engineering/checks/antipatterns/volatile.py

@@ -0,0 +1,38 @@
+"""P4: flag content that goes stale quickly (counts, timestamps, versions)."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterator
+from pathlib import Path
+
+from ...domain.finding import Finding, Severity
+from ...infra.filesystem import read_text_safe
+from .context import CheckContext
+
+_PATTERNS: tuple[tuple[re.Pattern, str], ...] = (
+    (re.compile(
+        r"~?\d{2,}\s+(files?|dirs?|directories|modules?|models?|services?|"
+        r"tables?|tests?|endpoints?|routes?|components?|packages?)"
+    ), "volatile count"),
+    (re.compile(r"[Aa]ll\s+\d+\s+\w+"), "volatile count with 'all'"),
+    (re.compile(r"Updated:\s*\d{4}-\d{2}-\d{2}"), "diagram timestamp (stale quickly)"),
+    (re.compile(r"v\d+\.\d+\.\d+"), "version number (may go stale)"),
+)
+
+
+def check(path: Path, _ctx: CheckContext) -> Iterator[Finding]:
+    content = read_text_safe(path)
+    if content is None:
+        return
+    for i, line in enumerate(content.splitlines(), 1):
+        for pattern, message in _PATTERNS:
+            if pattern.search(line):
+                yield Finding(
+                    file=str(path),
+                    line=i,
+                    severity=Severity.WARNING,
+                    code="P4-volatile",
+                    message=message,
+                    hint=line.strip()[:100],
+                )

context_engineering/checks/antipatterns/watermark.py

@@ -0,0 +1,113 @@
+"""Watermark presence + staleness checks.
+
+Presence: AGENTS.md needs an HTML-comment watermark; docs/*.md need both
+`generated-by` and `last-updated` frontmatter keys together.
+
+Staleness: a modified file whose `last-updated` date matches HEAD was
+"edited without updating the watermark" — a common oversight.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from collections.abc import Iterator
+from pathlib import Path
+
+from ...domain.finding import Finding, Severity
+from ...infra.filesystem import read_text_safe
+from .context import CheckContext
+
+_DATE_RE = re.compile(r"last-updated:\s*(\d{4}-\d{2}-\d{2})")
+_HTML_WATERMARK_RE = re.compile(r"<!--\s*generated-by:")
+
+
+def _last_updated(content: str) -> str | None:
+    m = _DATE_RE.search(content)
+    return m.group(1) if m else None
+
+
+def _head_content(path: Path, git_root: Path | None) -> str | None:
+    if git_root is None:
+        return None
+    try:
+        rel = path.resolve().relative_to(git_root.resolve())
+    except ValueError:
+        return None
+    try:
+        result = subprocess.run(
+            ["git", "show", f"HEAD:{rel}"], capture_output=True, text=True, cwd=git_root,
+        )
+    except FileNotFoundError:
+        return None
+    return result.stdout if result.returncode == 0 else None
+
+
+def check_presence(path: Path, _ctx: CheckContext) -> Iterator[Finding]:
+    content = read_text_safe(path)
+    if content is None:
+        return
+    lines = content.splitlines()
+
+    if path.name == "AGENTS.md" and content.startswith("---\n"):
+        yield Finding(
+            file=str(path), line=1, severity=Severity.WARNING,
+            code="structural", message="AGENTS.md should not have YAML frontmatter",
+            hint="---",
+        )
+
+    has_generated_by = any("generated-by:" in ln for ln in lines)
+    has_last_updated = any("last-updated:" in ln for ln in lines)
+
+    if path.name == "AGENTS.md":
+        if not _HTML_WATERMARK_RE.search(content):
+            yield Finding(
+                file=str(path), line=max(1, len(lines)), severity=Severity.WARNING,
+                code="watermark-missing",
+                message="AGENTS.md missing generated-by HTML comment watermark",
+                hint="<!-- generated-by: plugin@version | last-updated: YYYY-MM-DD -->",
+            )
+        return
+
+    if path.name == "README.md" or path.suffix != ".md":
+        return
+
+    if has_generated_by and not has_last_updated:
+        yield Finding(
+            file=str(path), line=1, severity=Severity.WARNING,
+            code="watermark-incomplete",
+            message="has generated-by but missing last-updated",
+        )
+    elif has_last_updated and not has_generated_by:
+        yield Finding(
+            file=str(path), line=1, severity=Severity.WARNING,
+            code="watermark-incomplete",
+            message="has last-updated but missing generated-by",
+        )
+
+
+def check_staleness(path: Path, ctx: CheckContext) -> Iterator[Finding]:
+    if not ctx.modified_only:
+        return
+    content = read_text_safe(path)
+    if content is None:
+        return
+    current = _last_updated(content)
+    if current is None:
+        return
+    head = _head_content(path, ctx.git_root)
+    if head is None:
+        return
+    head_date = _last_updated(head)
+    if head_date is None or head_date != current:
+        return
+    line_num = next(
+        (i for i, ln in enumerate(content.splitlines(), 1) if "last-updated:" in ln),
+        1,
+    )
+    yield Finding(
+        file=str(path), line=line_num, severity=Severity.WARNING,
+        code="watermark-stale",
+        message=f"file was modified but last-updated date unchanged ({current})",
+        hint=f"Update last-updated to today's date (currently: {current})",
+    )