capt-hook 0.2.0__py3-none-any.whl

captain_hook/styleguide/__init__.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import ast
+import inspect
+import logging
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+from captain_hook.app import on
+from captain_hook.state import hook_name
+from captain_hook.styleguide.query import (
+    Assignment,
+    Call,
+    Class,
+    ControlFlow,
+    Definition,
+    Function,
+    Import,
+    Kind,
+    Module,
+    Query,
+    Slot,
+    TypeChecking,
+    annotated_slots,
+    annotations,
+    calls,
+    has_future_annotations,
+    has_keyword,
+    is_name,
+    name_of,
+    named,
+    parent_map,
+    string_literals,
+)
+from captain_hook.styleguide.scope import changed_lines, read_source, reconstruct_pre
+from captain_hook.styleguide.types import StyleDiffRule, StyleRule, Violation
+from captain_hook.types import Action, Event, FilePath, HookResult, TCondition, TestFile, Tool
+
+if TYPE_CHECKING:
+    from captain_hook.events import BaseHookEvent
+
+logger = logging.getLogger(__name__)
+
+GUARD_ONLY_IF: tuple[TCondition, ...] = (Tool("Edit|Write"), FilePath("*.py", project_only=False))
+GUARD_SKIP_IF: tuple[TCondition, ...] = (TestFile(),)
+
+__all__ = [
+    "Assignment",
+    "Call",
+    "Class",
+    "ControlFlow",
+    "Definition",
+    "Function",
+    "Import",
+    "Kind",
+    "Module",
+    "Query",
+    "Slot",
+    "StyleDiffRule",
+    "StyleRule",
+    "TypeChecking",
+    "Violation",
+    "annotated_slots",
+    "annotations",
+    "calls",
+    "has_future_annotations",
+    "has_keyword",
+    "is_name",
+    "name_of",
+    "named",
+    "parent_map",
+    "string_literals",
+    "styleguide",
+]
+
+
+def styleguide(
+    *rules: type[StyleRule],
+    block: bool = False,
+    only_if: Sequence[TCondition] = (),
+    skip_if: Sequence[TCondition] = (),
+    events: Event | None = None,
+    max_shown: int = 5,
+) -> None:
+    """Register one change-scoped hook applying the given style rules to Python edits and writes.
+
+    Each rule is a [`StyleRule`][captain_hook.styleguide.StyleRule] (or
+    [`StyleDiffRule`][captain_hook.styleguide.StyleDiffRule]) subclass whose docstring is its
+    message. The single registered hook parses the edited file once, runs every rule against the
+    post-edit tree, scopes each violation to the changed lines, and emits one aggregated warning
+    (or block, when ``block`` is set). Call again with different ``only_if`` / ``skip_if`` /
+    ``events`` / ``block`` to register a separately scoped hook.
+
+    Args:
+        rules: ``StyleRule`` / ``StyleDiffRule`` subclasses to apply.
+        block: Block the tool call instead of warning.
+        only_if: Extra conditions ANDed onto the built-in ``Edit|Write`` + ``*.py`` guards.
+        skip_if: Extra conditions ORed onto the built-in test-file skip.
+        events: Override the default ``PostToolUse`` targeting.
+        max_shown: Maximum violations shown per rule.
+
+    Example:
+        >>> styleguide(NoPrint, NoBareExcept)
+        >>> styleguide(NoSqlInjection, block=True, only_if=[FilePath("api/**/*.py")])
+    """
+    if not (instances := [validate(rule)() for rule in rules]):
+        return
+
+    def handler(evt: BaseHookEvent) -> HookResult | None:
+        try:
+            return run_rules(instances, evt, block=block, max_shown=max_shown)
+        except Exception:
+            logger.warning("styleguide hook failed", exc_info=True)
+            return None
+
+    handler.__name__ = handler.__qualname__ = hook_name("styleguide", None, "+".join(r.slug() for r in instances))
+
+    on(
+        events or Event.PostToolUse,
+        only_if=(*GUARD_ONLY_IF, *only_if),
+        skip_if=(*GUARD_SKIP_IF, *skip_if),
+        tests={key: expected for inst in instances for key, expected in type(inst).tests.items()},
+    )(handler)
+
+
+def validate(rule: type[StyleRule]) -> type[StyleRule]:
+    if not (isinstance(rule, type) and issubclass(rule, StyleRule)):
+        raise TypeError(f"styleguide() expects StyleRule subclasses, got {rule!r}")
+    if rule.__doc__ is None:
+        raise ValueError(f"{rule.__name__} must define a docstring — it is the rule's message")
+    return rule
+
+
+def run_rules(rules: list[StyleRule], evt: BaseHookEvent, *, block: bool, max_shown: int) -> HookResult | None:
+    if (source := read_source(evt)) is None:
+        return None
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return None
+    pre = reconstruct_pre(evt, source)
+    changed = changed_lines(pre, source)
+    pre_tree = parse_quietly(pre) if any(isinstance(r, StyleDiffRule) for r in rules) else None
+    if not (
+        sections := [
+            section
+            for rule in rules
+            if (section := run_one(rule, tree, pre_tree, source, changed, max_shown)) is not None
+        ]
+    ):
+        return None
+    return HookResult(action=Action.block if block else Action.warn, message="\n\n".join(sections))
+
+
+def run_one(
+    rule: StyleRule,
+    tree: ast.Module,
+    pre_tree: ast.Module | None,
+    source: str,
+    changed: set[int],
+    max_shown: int,
+) -> str | None:
+    if rule.trigger and rule.trigger not in source:
+        return None
+    match rule:
+        case StyleDiffRule() if pre_tree is not None:
+            violations = rule.check(pre_tree, tree)
+        case StyleDiffRule():
+            return None
+        case _:
+            violations = rule.check(tree)
+    if not (scoped := [v for v in violations if v.line in changed]):
+        return None
+    block = rule.sep.join(f"{v.label} (line {v.line})" for v in scoped[:max_shown])
+    doc = inspect.cleandoc(type(rule).__doc__ or "")
+    return doc.format(violations=block) if "{violations}" in doc else f"{doc}{rule.sep}{block}"
+
+
+def parse_quietly(source: str) -> ast.Module | None:
+    try:
+        return ast.parse(source)
+    except SyntaxError:
+        return None

captain_hook/styleguide/query.py

@@ -0,0 +1,238 @@
+from __future__ import annotations
+
+import ast
+from collections.abc import Callable, Iterator, Mapping
+from dataclasses import dataclass, replace
+
+from captain_hook.styleguide.types import Violation
+
+
+@dataclass(frozen=True, slots=True)
+class Kind:
+    """A matchable category of AST node — a set of node types and/or a predicate.
+
+    Compose with ``|`` (matches either), narrow with the constructor, or build one with the
+    [`calls`][captain_hook.styleguide.calls] / [`named`][captain_hook.styleguide.named]
+    factories. Authoring a new rule is usually a matter of combining existing `Kind`s rather
+    than adding a framework helper.
+
+    Example:
+        >>> Definition = Function | Class
+        >>> Decorated = Kind(test=lambda n: bool(getattr(n, "decorator_list", None)))
+    """
+
+    types: tuple[type[ast.AST], ...] = ()
+    test: Callable[[ast.AST], bool] | None = None
+    label: str = "Kind"
+
+    def matches(self, node: ast.AST) -> bool:
+        return (not self.types or isinstance(node, self.types)) and (self.test is None or self.test(node))
+
+    def __or__(self, other: Kind) -> Kind:
+        return Kind(test=lambda n: self.matches(n) or other.matches(n), label=f"{self.label}|{other.label}")
+
+
+def is_type_checking_test(test: ast.expr) -> bool:
+    """Return whether ``test`` is the ``TYPE_CHECKING`` / ``typing.TYPE_CHECKING`` condition."""
+    match test:
+        case ast.Name(id="TYPE_CHECKING"):
+            return True
+        case ast.Attribute(value=ast.Name(id="typing"), attr="TYPE_CHECKING"):
+            return True
+        case _:
+            return False
+
+
+Module = Kind((ast.Module,), label="Module")
+Class = Kind((ast.ClassDef,), label="Class")
+Function = Kind((ast.FunctionDef, ast.AsyncFunctionDef), label="Function")
+Definition = Class | Function
+Import = Kind((ast.Import, ast.ImportFrom), label="Import")
+Call = Kind((ast.Call,), label="Call")
+Assignment = Kind((ast.Assign, ast.AnnAssign), label="Assignment")
+ControlFlow = Kind(
+    (ast.If, ast.For, ast.AsyncFor, ast.While, ast.With, ast.AsyncWith, ast.Try, ast.ExceptHandler),
+    label="ControlFlow",
+)
+TypeChecking = Kind((ast.If,), lambda n: is_type_checking_test(n.test), label="TypeChecking")
+
+
+def calls(name: str) -> Kind:
+    """A `Kind` matching a call to the named function, e.g. ``calls("zip")``."""
+    return Kind((ast.Call,), lambda n: isinstance(n.func, ast.Name) and n.func.id == name, label=f"calls({name})")
+
+
+def named(*names: str) -> Kind:
+    """A `Kind` matching a class/function/assignment/argument bound to one of ``names``."""
+    return Kind(test=lambda n: name_of(n) in names, label=f"named({', '.join(names)})")
+
+
+@dataclass(frozen=True, slots=True)
+class Query:
+    """A fluent, immutable filter over the nodes of an AST tree.
+
+    Start with ``Query.of(tree)``, chain refinements (each returns a new `Query`), and finish
+    with a terminal — iterate it, call ``exists()``, or ``violations(label)`` to turn the
+    survivors into [`Violation`][captain_hook.styleguide.Violation]s.
+
+    Example:
+        >>> Query.of(tree).matching(Import).directly_inside(ControlFlow).not_inside(TypeChecking)
+    """
+
+    tree: ast.Module
+    items: tuple[ast.AST, ...]
+    parents: Mapping[ast.AST, ast.AST]
+
+    @classmethod
+    def of(cls, tree: ast.Module) -> Query:
+        return cls(tree, tuple(ast.walk(tree)), parent_map(tree))
+
+    def matching(self, kind: Kind) -> Query:
+        """Keep only nodes matching ``kind``."""
+        return self.keeping(kind.matches)
+
+    def where(self, predicate: Callable[[ast.AST], bool]) -> Query:
+        """Keep only nodes satisfying ``predicate`` — the escape hatch for one-off conditions."""
+        return self.keeping(predicate)
+
+    def inside(self, kind: Kind) -> Query:
+        """Keep nodes with any ancestor matching ``kind``."""
+        return self.keeping(lambda n: any(kind.matches(a) for a in self.ancestors(n)))
+
+    def directly_inside(self, kind: Kind) -> Query:
+        """Keep nodes whose immediate parent matches ``kind``."""
+        return self.keeping(lambda n: (p := self.parents.get(n)) is not None and kind.matches(p))
+
+    def not_inside(self, kind: Kind) -> Query:
+        """Keep nodes with no ancestor matching ``kind`` (e.g. ``not_inside(TypeChecking)``)."""
+        return self.keeping(lambda n: not any(kind.matches(a) for a in self.ancestors(n)))
+
+    def after_first(self, boundary: Kind) -> Query:
+        """Keep body-statements that follow the first sibling matching ``boundary``.
+
+        The basis for "declarations must precede code" rules: pair with ``directly_inside`` to
+        scope it to a module or class body.
+        """
+        return self.keeping(self.is_late(boundary))
+
+    def violations(self, label: str | Callable[[ast.AST], str]) -> Iterator[Violation]:
+        """Turn the surviving nodes into `Violation`s located at each node's line."""
+        return (Violation(node.lineno, label(node) if callable(label) else label) for node in self.items)
+
+    def exists(self) -> bool:
+        return bool(self.items)
+
+    def keeping(self, predicate: Callable[[ast.AST], bool]) -> Query:
+        return replace(self, items=tuple(node for node in self.items if predicate(node)))
+
+    def ancestors(self, node: ast.AST) -> Iterator[ast.AST]:
+        cur = self.parents.get(node)
+        while cur is not None:
+            yield cur
+            cur = self.parents.get(cur)
+
+    def is_late(self, boundary: Kind) -> Callable[[ast.AST], bool]:
+        def late(node: ast.AST) -> bool:
+            body = getattr(self.parents.get(node), "body", None)
+            if not isinstance(body, list) or node not in body:
+                return False
+            cut = next((i for i, stmt in enumerate(body) if boundary.matches(stmt)), None)
+            return cut is not None and body.index(node) > cut
+
+        return late
+
+    def __iter__(self) -> Iterator[ast.AST]:
+        return iter(self.items)
+
+
+@dataclass(frozen=True, slots=True)
+class Slot:
+    """An annotated slot: a variable, function return, or parameter and its annotation expr."""
+
+    name: str
+    annotation: ast.expr
+    line: int
+    is_return: bool = False
+
+
+def parent_map(tree: ast.AST) -> dict[ast.AST, ast.AST]:
+    """Map every node in ``tree`` to its parent node."""
+    return {child: node for node in ast.walk(tree) for child in ast.iter_child_nodes(node)}
+
+
+def name_of(node: ast.AST) -> str | None:
+    """The name a node binds or defines: a class, function, simple assignment target, or argument."""
+    match node:
+        case ast.ClassDef(name=name) | ast.FunctionDef(name=name) | ast.AsyncFunctionDef(name=name):
+            return name
+        case ast.Assign(targets=[ast.Name(id=name), *_]) | ast.AnnAssign(target=ast.Name(id=name)):
+            return name
+        case ast.arg(arg=name):
+            return name
+        case _:
+            return None
+
+
+def is_name(expr: ast.expr, name: str) -> bool:
+    """Return whether ``expr`` is exactly the bare name ``name`` (e.g. ``is_name(ann, "Any")``)."""
+    return isinstance(expr, ast.Name) and expr.id == name
+
+
+def has_keyword(call: ast.Call, name: str) -> bool:
+    """Return whether ``call`` passes a keyword argument named ``name``."""
+    return any(kw.arg == name for kw in call.keywords)
+
+
+def has_future_annotations(tree: ast.Module) -> bool:
+    """Return whether the module begins with ``from __future__ import annotations``."""
+    return any(
+        isinstance(node, ast.ImportFrom)
+        and node.module == "__future__"
+        and any(alias.name == "annotations" for alias in node.names)
+        for node in tree.body
+    )
+
+
+def annotations(tree: ast.Module) -> Iterator[ast.expr]:
+    """Every annotation expression in ``tree`` — annotated assignments, returns, and arguments."""
+    for node in ast.walk(tree):
+        match node:
+            case ast.AnnAssign(annotation=ann):
+                yield ann
+            case ast.FunctionDef(returns=ann) | ast.AsyncFunctionDef(returns=ann) if ann is not None:
+                yield ann
+            case ast.arg(annotation=ann) if ann is not None:
+                yield ann
+
+
+def string_literals(expr: ast.expr) -> Iterator[ast.Constant]:
+    """String-literal type references within an annotation, skipping ``Literal``/``Annotated`` metadata."""
+    match expr:
+        case ast.Constant(value=str()):
+            yield expr
+        case ast.Subscript(value=ast.Name(id="Literal") | ast.Attribute(attr="Literal")):
+            return
+        case ast.Subscript(value=ast.Name(id="Annotated") | ast.Attribute(attr="Annotated"), slice=ast.Tuple(elts=[first, *_])):
+            yield from string_literals(first)
+        case _:
+            yield from (ref for child in ast.iter_child_nodes(expr) if isinstance(child, ast.expr) for ref in string_literals(child))
+
+
+def annotated_slots(tree: ast.Module) -> Iterator[Slot]:
+    """Every annotated slot in ``tree`` as a [`Slot`][captain_hook.styleguide.Slot].
+
+    Covers annotated variables, function return types, and positional/keyword parameters —
+    enough to drive any annotation-shape rule via a predicate on ``slot.annotation``.
+    """
+    for node in ast.walk(tree):
+        match node:
+            case ast.AnnAssign(target=ast.Name(id=name), annotation=ann):
+                yield Slot(name, ann, node.lineno)
+            case ast.FunctionDef() | ast.AsyncFunctionDef():
+                if node.returns is not None:
+                    yield Slot(node.name, node.returns, node.lineno, is_return=True)
+                yield from (
+                    Slot(arg.arg, arg.annotation, arg.lineno)
+                    for arg in (*node.args.posonlyargs, *node.args.args, *node.args.kwonlyargs)
+                    if arg.annotation is not None
+                )

captain_hook/styleguide/scope.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import difflib
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from captain_hook.events import BaseHookEvent
+
+
+def read_source(evt: BaseHookEvent) -> str | None:
+    if evt.file and evt.file.path.exists():
+        try:
+            return evt.file.read_text()
+        except (OSError, UnicodeDecodeError):
+            pass
+    return evt.content
+
+
+def reconstruct_pre(evt: BaseHookEvent, source: str) -> str:
+    """Best-effort pre-edit source: an Edit's ``new_string`` swapped back to ``old_string``.
+
+    Returns ``""`` when there is nothing to diff against (a Write, or an Edit whose fragment
+    can't be located) — the conservative choice that treats the whole file as changed.
+    """
+    match (evt.old, evt.content):
+        case (str() as old, str() as new) if new and new in source:
+            return source.replace(new, old, 1)
+        case _:
+            return ""
+
+
+def changed_lines(pre: str, source: str) -> set[int]:
+    """1-based line numbers in ``source`` that differ from ``pre``.
+
+    An empty ``pre`` means "everything changed" (a Write or an unlocatable Edit), so every line
+    of ``source`` is returned.
+    """
+    new_lines = source.splitlines()
+    if not pre:
+        return set(range(1, len(new_lines) + 1))
+    return {
+        i
+        for tag, _, _, lo, hi in difflib.SequenceMatcher(a=pre.splitlines(), b=new_lines, autojunk=False).get_opcodes()
+        if tag in {"replace", "insert"}
+        for i in range(lo + 1, hi + 1)
+    }

captain_hook/styleguide/types.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import ast
+from abc import ABC, abstractmethod
+from collections.abc import Iterator
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, ClassVar
+
+from captain_hook.utils import kebab
+
+if TYPE_CHECKING:
+    from captain_hook.testing import InlineTests
+
+
+@dataclass(frozen=True, slots=True)
+class Violation:
+    """A single style violation, located by line so the runner can scope it to the edit.
+
+    Attributes:
+        line: 1-based line number of the offending construct in the post-edit file.
+        label: Short human-readable description, rendered as ``"{label} (line {line})"``.
+    """
+
+    line: int
+    label: str
+
+
+class StyleRule(ABC):
+    """Base class for a single-tree AST style rule applied to Python edits and writes.
+
+    Subclass it, write the rule's message as the class **docstring** (``{violations}`` is
+    substituted at fire time), and implement ``check``. The class name is the rule's identity —
+    ``NoNestedImports`` becomes ``"no-nested-imports"``.
+
+    Example:
+        ```python
+        class NoPrint(StyleRule):
+            \"\"\"
+            print() calls don't belong in committed code:
+              - {violations}
+            \"\"\"
+            def check(self, tree):
+                for node in ast.walk(tree):
+                    match node:
+                        case ast.Call(func=ast.Name(id="print")):
+                            yield Violation(node.lineno, "print() call")
+        ```
+    """
+
+    trigger: ClassVar[str | None] = None
+    sep: ClassVar[str] = "\n  - "
+    tests: ClassVar[InlineTests] = {}
+
+    @classmethod
+    def slug(cls) -> str:
+        return kebab(cls.__name__)
+
+    @abstractmethod
+    def check(self, tree: ast.Module) -> Iterator[Violation]: ...
+
+
+class StyleDiffRule(StyleRule):
+    """Base class for a diff rule: flags constructs newly introduced by the change.
+
+    Like [`StyleRule`][captain_hook.styleguide.StyleRule], but ``check`` receives both the
+    pre-edit and post-edit module trees, so it can report only what the edit *added*.
+    """
+
+    @abstractmethod
+    def check(self, pre: ast.Module, post: ast.Module) -> Iterator[Violation]: ...  # type: ignore[override]

captain_hook/tasks.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, ClassVar, overload
+
+from loguru import logger
+
+
+@dataclass(frozen=True, kw_only=True)
+class Task:
+    """A task read from Claude Code's native task store (``~/.claude/tasks/<list-id>/<id>.json``)."""
+
+    OPEN_STATUSES: ClassVar[tuple[str, ...]] = ("pending", "in_progress")
+
+    id: str
+    subject: str
+    status: str
+    description: str = ""
+    owner: str | None = None
+    blocked_by: tuple[str, ...] = ()
+    blocks: tuple[str, ...] = ()
+
+    @property
+    def is_open(self) -> bool:
+        return self.status in self.OPEN_STATUSES
+
+    @classmethod
+    def from_raw(cls, raw: dict[str, Any]) -> Task:
+        return cls(
+            id=str(raw.get("id", "")),
+            subject=raw.get("subject") or "",
+            status=raw.get("status") or "pending",
+            description=raw.get("description") or "",
+            owner=raw.get("owner") or None,
+            blocked_by=tuple(raw.get("blockedBy") or ()),
+            blocks=tuple(raw.get("blocks") or ()),
+        )
+
+
+@dataclass(frozen=True)
+class Tasks(Sequence[Task]):
+    """The live task list for one session, read from the native store rather than the transcript.
+
+    Always keyed by the exact list id (session id) — a session with no store has no
+    tasks, never another session's. This is the source of truth for completion gates;
+    transcript-derived ``task_ops()`` misses updates made by subagents, teammates, or
+    resumed sessions.
+    """
+
+    tasks: tuple[Task, ...] = ()
+
+    @classmethod
+    def resolve_root(cls) -> Path:
+        """Resolve the root of Claude Code's native task store (``<config-dir>/tasks``)."""
+        if explicit := os.environ.get("CAPTAIN_HOOK_TASKS_DIR"):
+            return Path(explicit)
+        config_dir = Path(os.environ.get("CLAUDE_CONFIG_DIR") or Path.home() / ".claude")
+        return config_dir / "tasks"
+
+    @classmethod
+    def for_session(cls, session_id: str, *, root: Path | None = None) -> Tasks:
+        """Load the task list stored under ``session_id``, empty when absent."""
+        list_dir = (root or cls.resolve_root()) / session_id
+        if not session_id or not list_dir.is_dir():
+            return cls()
+        tasks: list[Task] = []
+        for path in list_dir.glob("*.json"):
+            try:
+                tasks.append(Task.from_raw(json.loads(path.read_text())))
+            except (OSError, ValueError):
+                logger.bind(path=str(path)).opt(exception=True).warning("failed to read task file")
+        return cls(tuple(sorted(tasks, key=lambda t: (not t.id.isdigit(), int(t.id) if t.id.isdigit() else 0, t.id))))
+
+    @overload
+    def __getitem__(self, index: int) -> Task: ...
+    @overload
+    def __getitem__(self, index: slice) -> tuple[Task, ...]: ...
+    def __getitem__(self, index: int | slice) -> Task | tuple[Task, ...]:
+        return self.tasks[index]
+
+    def __len__(self) -> int:
+        return len(self.tasks)
+
+    def get(self, task_id: str) -> Task | None:
+        return next((t for t in self.tasks if t.id == task_id), None)
+
+    def with_status(self, *statuses: str) -> tuple[Task, ...]:
+        return tuple(t for t in self.tasks if t.status in statuses)
+
+    @property
+    def pending(self) -> tuple[Task, ...]:
+        return self.with_status("pending")
+
+    @property
+    def in_progress(self) -> tuple[Task, ...]:
+        return self.with_status("in_progress")
+
+    @property
+    def completed(self) -> tuple[Task, ...]:
+        return self.with_status("completed")
+
+    @property
+    def open(self) -> tuple[Task, ...]:
+        return self.with_status(*Task.OPEN_STATUSES)
+
+    @property
+    def all_completed(self) -> bool:
+        return not self.open