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

context_engineering/checks/references.py

@@ -0,0 +1,325 @@
+"""Verify that paths referenced in AGENTS.md / docs/*.md files resolve.
+
+`is_likely_path` is a series of small named predicates — each rules out a
+specific kind of non-path that happens to appear in backticks. Adding a new
+exclusion means adding a one-liner, not extending a 15-branch function.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterator
+from pathlib import Path
+
+from ..analysis.context_layout import RepositoryContextLayout, discover
+from ..domain.finding import Finding, Severity
+from ..domain.result import LintResult
+from ..infra.filesystem import EXCLUDED_DIRS, read_text_safe
+
+# ---------------------------------------------------------------------------
+# Path-likeness heuristic — factored into named predicates so adding
+# exclusions doesn't mean touching a 30-branch function.
+# ---------------------------------------------------------------------------
+
+_URL_RE = re.compile(r"^(https?|git\+https?|gs|gcr\.io|docker\.io)[:/]")
+_ENV_OR_FLAG_RE = re.compile(r"^(--|\$|[A-Z_]+=|@|#|\*|>)")
+_KEYBINDING_RE = re.compile(r"^(Alt|Ctrl|Shift|Meta|Cmd|Super)\+")
+_VIM_KEY_RE = re.compile(r"^<(leader|prefix|space|cr|esc|tab|bs|del|up|down|left|right)")
+_DOMAIN_RE = re.compile(r"^\w+\.\w+\.\w+/")
+_CONTAINER_TAG_RE = re.compile(r":\w[\w.-]*$")
+_DOTTED_PROP_RE = re.compile(r"\w+(\.\w+)+")
+# Deliberately narrow: only match bare org/repo when no file extension would
+# distinguish it. Two-segment repo paths like `services/payments` match the
+# filesystem-resolution fallback, so we accept them as path candidates and let
+# the resolver decide. Matching `foo/bar` as "github repo" caused broken
+# references to pass silently.
+_TOOL_OUTPUT_DIR_RE = re.compile(r"^\.[a-zA-Z][\w-]*(/|$)")
+_UPPERCASE_PROPERTY_RE = re.compile(r"\.[a-z]*[A-Z]\w*$")  # .sourceDir, .chezmoi
+_DOTTED_METHOD_NAMES = {".parent", ".name", ".stem", ".suffix", ".resolve"}
+
+
+def _looks_like_prose(text: str) -> bool:
+    """Strings that can't possibly be file paths."""
+    return (
+        not text
+        or len(text) < 3
+        or " " in text
+        or any(c in text for c in "()=;{}<>\"'")
+        or "{{" in text
+        or "*" in text
+        or "?" in text
+    )
+
+
+def _is_homebrew_tap(text: str) -> bool:
+    return text.startswith(("brew ", "tap ", "homebrew/"))
+
+
+def _is_home_or_absolute(text: str) -> bool:
+    return text.startswith(("/", "~/", "~"))
+
+
+def _is_protocol_uri(text: str) -> bool:
+    return bool(_URL_RE.match(text)) or text.startswith(
+        ("collection://", "discussion://", "notion://")
+    )
+
+
+def _is_flag_or_cli(text: str) -> bool:
+    return bool(_ENV_OR_FLAG_RE.match(text))
+
+
+def _is_shortcut(text: str) -> bool:
+    return bool(_KEYBINDING_RE.match(text) or _VIM_KEY_RE.match(text))
+
+
+def _is_domain_path(text: str) -> bool:
+    return bool(_DOMAIN_RE.match(text))
+
+
+def _is_tool_output_dir(text: str) -> bool:
+    return bool(_TOOL_OUTPUT_DIR_RE.match(text))
+
+
+def _is_bare_extension(text: str) -> bool:
+    return "/" not in text and text.startswith(".") and bool(re.fullmatch(r"\.\w+", text))
+
+
+def _is_dotted_config_key(text: str) -> bool:
+    return "/" not in text and bool(_DOTTED_PROP_RE.fullmatch(text))
+
+
+def _is_uppercase_property(text: str) -> bool:
+    return "/" not in text and bool(_UPPERCASE_PROPERTY_RE.search(text))
+
+
+def _is_dotted_method(text: str) -> bool:
+    return "/" not in text and any(text.endswith(m) for m in _DOTTED_METHOD_NAMES)
+
+
+def _is_container_image(text: str) -> bool:
+    return ":" in text and bool(_CONTAINER_TAG_RE.search(text))
+
+
+def _looks_pathish(text: str) -> bool:
+    has_slash = "/" in text
+    has_extension = bool(re.search(r"\.\w{1,10}$", text))
+    return has_slash or has_extension
+
+
+_NON_PATH_PREDICATES = (
+    _is_homebrew_tap,
+    _is_home_or_absolute,
+    _is_protocol_uri,
+    _is_flag_or_cli,
+    _is_shortcut,
+    _is_domain_path,
+    _is_tool_output_dir,
+    _is_bare_extension,
+    _is_dotted_config_key,
+    _is_uppercase_property,
+    _is_dotted_method,
+    _is_container_image,
+)
+
+
+def is_likely_path(text: str) -> bool:
+    """Conservative: exclude everything we know isn't a path, accept the rest."""
+    text = text.strip()
+    if _looks_like_prose(text):
+        return False
+    if any(pred(text) for pred in _NON_PATH_PREDICATES):
+        return False
+    return _looks_pathish(text)
+
+
+# ---------------------------------------------------------------------------
+# Extraction
+# ---------------------------------------------------------------------------
+
+
+def strip_code_fences(content: str) -> str:
+    return re.sub(r"```[\s\S]*?```", "", content)
+
+
+def extract_backtick_paths(content: str) -> list[str]:
+    stripped = strip_code_fences(content)
+    return [
+        m.group(1).strip().rstrip(",;:")
+        for m in re.finditer(r"`([^`\n]+)`", stripped)
+        if is_likely_path(m.group(1))
+    ]
+
+
+def _extract_markdown_links(content: str) -> list[str]:
+    out: list[str] = []
+    for match in re.finditer(r"\[([^\]]*)\]\(([^)]+)\)", content):
+        target = match.group(2).strip()
+        if target.startswith(("http://", "https://", "#", "mailto:")):
+            continue
+        out.append(target.split("#")[0])
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Lint
+# ---------------------------------------------------------------------------
+
+
+def _under_reference_dir(path: Path, root: Path) -> bool:
+    try:
+        rel = path.relative_to(root).parts
+    except ValueError:
+        return False
+    return any(part in ("references", "resources", "skills") for part in rel)
+
+
+def _resolve_ref(ref: str, file_dir: Path, root: Path, git_root_path: Path | None) -> bool:
+    clean = re.sub(r":\d+(-\d+)?$", "", ref)
+    for base in (file_dir, root, git_root_path):
+        if base and (base / clean).exists():
+            return True
+    return False
+
+
+def lint_file(path: Path, root: Path, *, git_root_path: Path | None = None) -> Iterator[Finding]:
+    content = read_text_safe(path)
+    if content is None:
+        return
+    # extract_backtick_paths already strips code fences — don't double-strip.
+    paths = dict.fromkeys(extract_backtick_paths(content))
+    in_ref_dir = _under_reference_dir(path, root)
+
+    for ref in paths:
+        if _resolve_ref(ref, path.parent, root, git_root_path):
+            continue
+        if "{{" in ref or "{%" in ref or "*" in ref:
+            continue
+        if in_ref_dir and ref.startswith("docs/"):
+            continue
+        yield Finding(
+            file=str(path),
+            line=0,
+            severity=Severity.ERROR,
+            code="broken-reference",
+            message=f"broken reference `{ref}`",
+        )
+
+
+def _lint_symlinks(root: Path, layout: RepositoryContextLayout) -> Iterator[Finding]:
+    for agents in layout.agents_files:
+        claude = agents.parent / "CLAUDE.md"
+        if claude.is_symlink():
+            if not claude.exists():
+                yield Finding(
+                    file=str(claude),
+                    line=0,
+                    severity=Severity.ERROR,
+                    code="claude-md-broken-symlink",
+                    message="broken symlink (target does not exist)",
+                )
+            elif claude.resolve() != agents.resolve():
+                yield Finding(
+                    file=str(claude),
+                    line=0,
+                    severity=Severity.ERROR,
+                    code="claude-md-wrong-target",
+                    message=f"symlink points to {claude.resolve()}, expected {agents}",
+                )
+        elif claude.exists():
+            yield Finding(
+                file=str(claude),
+                line=0,
+                severity=Severity.ERROR,
+                code="claude-md-not-symlink",
+                message="is a regular file, must be a symlink to AGENTS.md",
+            )
+
+
+def _lint_docs_indexes(root: Path, layout: RepositoryContextLayout) -> Iterator[Finding]:
+    docs_paths = {tree.path for tree in layout.docs_trees}
+    for agents in layout.agents_files:
+        if agents.parent not in docs_paths:
+            continue
+        content = read_text_safe(agents) or ""
+        referenced = {m.group(1).strip() for m in re.finditer(r"`([^`\n]+)`", content)}
+        for md in agents.parent.rglob("*.md"):
+            if md.name in ("README.md", "AGENTS.md"):
+                continue
+            relative_to_docs = md.relative_to(agents.parent)
+            if "docs" in relative_to_docs.parts[:-1]:
+                continue
+            if any(p in EXCLUDED_DIRS for p in md.relative_to(root).parts):
+                continue
+            rel_to_docs = str(relative_to_docs)
+            rel_to_root = str(md.relative_to(root))
+            if rel_to_docs in referenced or rel_to_root in referenced:
+                continue
+            yield Finding(
+                file=str(agents),
+                line=0,
+                severity=Severity.ERROR,
+                code="docs-index-incomplete",
+                message=f"docs index missing entry for `{rel_to_docs}`",
+            )
+
+
+def _lint_docs_readme_links(root: Path, layout: RepositoryContextLayout) -> Iterator[Finding]:
+    for tree in layout.docs_trees:
+        readme = tree.path / "README.md"
+        if not readme.is_file():
+            continue
+        content = read_text_safe(readme) or ""
+        for link in _extract_markdown_links(content):
+            if (readme.parent / link).exists() or (root / link).exists():
+                continue
+            yield Finding(
+                file=str(readme),
+                line=0,
+                severity=Severity.ERROR,
+                code="readme-broken-link",
+                message=f"broken link `{link}`",
+            )
+
+
+def _find_context_files(root: Path, layout: RepositoryContextLayout) -> Iterator[Path]:
+    yield from layout.agents_files
+    for tree in layout.docs_trees:
+        docs_dir = tree.path
+        for md in sorted(docs_dir.rglob("*.md")):
+            relative = md.relative_to(docs_dir)
+            if "docs" in relative.parts[:-1]:
+                continue
+            if any(part in EXCLUDED_DIRS for part in relative.parts):
+                continue
+            yield md
+
+
+def _context_root_for(path: Path, layout: RepositoryContextLayout) -> Path:
+    """Return the nearest contract root that owns a context file."""
+    matches = [
+        root
+        for root in layout.contract_roots
+        if path == root or root in path.parents
+    ]
+    return max(matches, key=lambda root: len(root.parts), default=layout.root)
+
+
+def lint(root: Path) -> LintResult:
+    from ..infra.git import git_root
+
+    root = root.resolve()
+    # Materialized commit trees intentionally have no .git directory. In that
+    # case the requested validation root is still the repository-scope fallback
+    # for references written from the checkout root.
+    git_root_path = git_root(root) or root
+
+    layout = discover(root)
+    findings: list[Finding] = []
+    for path in _find_context_files(root, layout):
+        context_root = _context_root_for(path, layout)
+        findings.extend(lint_file(path, context_root, git_root_path=git_root_path))
+    findings.extend(_lint_symlinks(root, layout))
+    findings.extend(_lint_docs_indexes(root, layout))
+    findings.extend(_lint_docs_readme_links(root, layout))
+    return LintResult(target=str(root), findings=findings)

context_engineering/checks/skill_structure.py

@@ -0,0 +1,124 @@
+"""Validate skill directory layout."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from pathlib import Path
+
+from ..domain.finding import Finding, Severity
+from ..domain.result import LintResult
+from ..infra.filesystem import read_text_safe
+from ..infra.yaml_frontmatter import parse_frontmatter
+
+_EXPECTED_SUBDIRS = frozenset({"scripts", "references", "resources", "assets"})
+_ALLOWED_TOP_LEVEL = frozenset({"SKILL.md", "SYNC.md", "README.md"})
+_SOFT_LINE_LIMIT = 500
+
+
+def _finding(path: Path, code: str, message: str, severity: Severity = Severity.ERROR) -> Finding:
+    return Finding(file=str(path), line=0, severity=severity, code=code, message=message)
+
+
+def lint_skill(skill_dir: Path) -> Iterator[Finding]:
+    if not skill_dir.is_dir():
+        yield _finding(skill_dir, "skill-not-a-directory", f"{skill_dir} is not a directory")
+        return
+
+    skill_md = skill_dir / "SKILL.md"
+    if not skill_md.exists():
+        yield _finding(skill_dir, "skill-missing-skill-md", "SKILL.md not found")
+        return
+
+    content = read_text_safe(skill_md) or ""
+    fm, _ = parse_frontmatter(content)
+
+    if fm is None:
+        yield _finding(skill_md, "skill-no-frontmatter", "SKILL.md has no YAML frontmatter")
+    else:
+        if "name" not in fm:
+            yield _finding(skill_md, "skill-missing-name", "frontmatter missing 'name'")
+        if "description" not in fm:
+            yield _finding(
+                skill_md,
+                "skill-missing-description",
+                "frontmatter missing 'description'",
+            )
+        if "name" in fm and fm["name"] != skill_dir.name:
+            yield _finding(
+                skill_md,
+                "skill-name-mismatch",
+                f"frontmatter name '{fm['name']}' differs from directory '{skill_dir.name}'",
+                Severity.WARNING,
+            )
+
+    line_count = len(content.splitlines())
+    if line_count > _SOFT_LINE_LIMIT:
+        yield _finding(
+            skill_md,
+            "skill-oversized",
+            f"SKILL.md is {line_count} lines (target <{_SOFT_LINE_LIMIT})",
+            Severity.WARNING,
+        )
+
+    yield from _lint_layout(skill_dir)
+    yield from _lint_scripts(skill_dir)
+    yield from _lint_references(skill_dir)
+
+
+def _lint_layout(skill_dir: Path) -> Iterator[Finding]:
+    for item in sorted(skill_dir.iterdir()):
+        if item.name.startswith("."):
+            continue
+        if item.is_dir() and item.name not in _EXPECTED_SUBDIRS:
+            yield _finding(
+                item,
+                "skill-unexpected-subdir",
+                f"unexpected subdirectory: {item.name}/",
+                Severity.WARNING,
+            )
+        elif item.is_file() and item.name not in _ALLOWED_TOP_LEVEL:
+            yield _finding(
+                item,
+                "skill-unexpected-top-level-file",
+                f"unexpected top-level file: {item.name}",
+                Severity.WARNING,
+            )
+
+
+def _lint_scripts(skill_dir: Path) -> Iterator[Finding]:
+    scripts = skill_dir / "scripts"
+    if not scripts.is_dir():
+        return
+    for py in sorted(scripts.glob("*.py")):
+        source = read_text_safe(py)
+        if source is None:
+            yield _finding(py, "skill-unreadable-script", "could not read script")
+            continue
+        # `compile()` does a pure syntax/parse check — no __pycache__ side
+        # effects like py_compile. A lint should be read-only.
+        try:
+            compile(source, str(py), "exec")
+        except SyntaxError as e:
+            yield _finding(py, "skill-script-compile-error", f"compile error: {e}")
+
+
+def _lint_references(skill_dir: Path) -> Iterator[Finding]:
+    for sub in ("references", "resources"):
+        subdir = skill_dir / sub
+        if not subdir.is_dir():
+            continue
+        for md in sorted(subdir.glob("*.md")):
+            if read_text_safe(md) is None:
+                yield _finding(md, "skill-unreadable-file", f"unreadable {sub} file")
+
+
+def lint(target: Path, *, recurse: bool = False) -> LintResult:
+    """If `recurse`, treat `target` as a parent of skills; otherwise target is one skill."""
+    if not recurse:
+        return LintResult(target=str(target), findings=list(lint_skill(target)))
+
+    findings: list[Finding] = []
+    for skill in sorted(target.iterdir()):
+        if skill.is_dir() and (skill / "SKILL.md").exists():
+            findings.extend(lint_skill(skill))
+    return LintResult(target=str(target), findings=findings)

context_engineering/cli/__init__.py

@@ -0,0 +1,3 @@
+from .dispatch import main
+
+__all__ = ["main"]

context_engineering/cli/dispatch.py

@@ -0,0 +1,90 @@
+"""One dispatcher. Build the parser from the registry, run, render, exit."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from ..domain.result import AnalysisResult, LintResult
+from .registry import Subcommand
+from .render import emit_json, render_analysis, render_lint
+from .subcommands import ALL
+
+
+def _error(message: str, *, exit_code: int = 1) -> int:
+    print(f"error: {message}", file=sys.stderr)
+    return exit_code
+
+
+def build_parser(subcommands: tuple[Subcommand, ...] = ALL) -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="context-engineering",
+        description=(
+            "Read-only analyzer CLI for context-engineering. "
+            "Inspect repository paths, contracts, history, and diffs."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "Examples:\n"
+            "  context-engineering tier services/payments\n"
+            "  context-engineering antipatterns modules/help-desk --json\n"
+            "  context-engineering cross-cutting services/payments --discover\n"
+            "  context-engineering skills ./skills --all\n"
+            "  context-engineering contracts packages/api --json\n"
+            "  context-engineering review . --base origin/main\n"
+            "  context-engineering check . --base origin/main\n"
+            "  context-engineering check . --all\n"
+            "  context-engineering backfill . --cutoff HEAD --json\n"
+        ),
+    )
+    sub = parser.add_subparsers(dest="subcommand", metavar="<subcommand>")
+
+    for cmd in subcommands:
+        sp = sub.add_parser(
+            cmd.name,
+            help=cmd.help,
+            description=cmd.description,
+            formatter_class=argparse.RawDescriptionHelpFormatter,
+            epilog=cmd.epilog(),
+        )
+        cmd.configure(sp)
+        sp.add_argument("--json", action="store_true", help="emit JSON to stdout")
+        sp.set_defaults(_handler=cmd)
+
+    return parser
+
+
+def _render(result, *, json_mode: bool) -> int:
+    if json_mode:
+        emit_json(result)
+        if isinstance(result, (LintResult, AnalysisResult)):
+            return 1 if result.has_errors else 0
+        return 0
+    if isinstance(result, LintResult):
+        return render_lint(result)
+    render_analysis(result)
+    return 1 if result.has_errors else 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if not getattr(args, "subcommand", None):
+        parser.print_help()
+        return 0
+
+    cmd: Subcommand = args._handler
+    result = cmd.run(args)
+
+    if result is None:
+        hint = cmd.examples[0] if cmd.examples else f"context-engineering {cmd.name} <path>"
+        return _error(
+            f"{cmd.name}: invalid target path. Try: {hint}",
+            exit_code=2,
+        )
+
+    if not isinstance(result, (LintResult, AnalysisResult)):
+        return _error(f"internal: {cmd.name} returned {type(result).__name__}")
+
+    return _render(result, json_mode=args.json)

context_engineering/cli/registry.py

@@ -0,0 +1,33 @@
+"""Subcommand registry — one dataclass per subcommand, zero dispatcher boilerplate.
+
+Each subcommand declares:
+- its name, help text, and Examples block
+- a `configure(parser)` callback to add arguments
+- a `run(args) -> Result` callback — the actual handler
+
+`dispatch.main` walks the registry to build the parser, pick a handler, and
+render the result uniformly.
+"""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+Configure = Callable[[argparse.ArgumentParser], None]
+Run = Callable[[argparse.Namespace], Any]  # Returns LintResult | AnalysisResult
+
+
+@dataclass(frozen=True)
+class Subcommand:
+    name: str
+    help: str
+    description: str
+    examples: tuple[str, ...]
+    configure: Configure
+    run: Run
+
+    def epilog(self) -> str:
+        return "Examples:\n" + "\n".join(f"  {e}" for e in self.examples) + "\n"

context_engineering/cli/render.py

@@ -0,0 +1,92 @@
+"""Render LintResult / AnalysisResult as JSON or human-readable text."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+from ..domain.finding import Finding, Severity
+from ..domain.result import AnalysisResult, LintResult
+
+
+def emit_json(result: Any) -> None:
+    json.dump(result.to_dict(), sys.stdout, indent=2, default=str, sort_keys=False)
+    sys.stdout.write("\n")
+
+
+def render_lint(result: LintResult) -> int:
+    """Print a LintResult in human-readable form. Return suggested exit code."""
+    if not result.findings:
+        print(f"No findings in {result.target}")
+        return 0
+
+    by_severity: dict[Severity, list[Finding]] = {
+        Severity.ERROR: [],
+        Severity.WARNING: [],
+        Severity.INFO: [],
+    }
+    for finding in result.findings:
+        by_severity[finding.severity].append(finding)
+
+    summary = (
+        f"{result.error_count} error(s), "
+        f"{result.warning_count} warning(s), "
+        f"{result.info_count} info"
+    )
+    print(f"{summary} in {result.target}\n")
+
+    for severity in (Severity.ERROR, Severity.WARNING, Severity.INFO):
+        for f in by_severity[severity]:
+            where = f"{f.file}:{f.line}" if f.line > 0 else f.file
+            print(f"  [{f.severity.value}] {where} [{f.code}] {f.message}")
+            if f.hint:
+                print(f"    hint: {f.hint}")
+        if by_severity[severity]:
+            print()
+
+    return 1 if result.has_errors else 0
+
+
+def render_analysis(result: AnalysisResult) -> int:
+    """Print an AnalysisResult. Key-value or tabular depending on shape."""
+    data = result.data
+    print(f"Target: {result.target}")
+    for key, value in data.items():
+        if isinstance(value, (dict, list)):
+            print(f"{key}:")
+            _print_nested(value, indent=2)
+        else:
+            print(f"{key}: {value}")
+
+    # Surface any warnings/errors that came along with the analysis (e.g.,
+    # cross-cutting's "skipping outside-repo path" warnings). Previously these
+    # showed up in --json but not in the human-readable output.
+    if result.findings:
+        print()
+        print(f"Findings ({len(result.findings)}):")
+        for f in result.findings:
+            where = f"{f.file}:{f.line}" if f.line > 0 else f.file
+            print(f"  [{f.severity.value}] {where} [{f.code}] {f.message}")
+            if f.hint:
+                print(f"    hint: {f.hint}")
+    return 0
+
+
+def _print_nested(value, indent: int) -> None:
+    pad = " " * indent
+    if isinstance(value, list):
+        for item in value[:20]:
+            if isinstance(item, dict):
+                print(pad + "- " + ", ".join(f"{k}={v}" for k, v in item.items()))
+            else:
+                print(f"{pad}- {item}")
+        if len(value) > 20:
+            print(f"{pad}... {len(value) - 20} more items; rerun with --json for all")
+    elif isinstance(value, dict):
+        for k, v in value.items():
+            if isinstance(v, (dict, list)):
+                print(f"{pad}{k}:")
+                _print_nested(v, indent + 2)
+            else:
+                print(f"{pad}{k}: {v}")