kata-cli 0.7.0__py3-none-any.whl

seer/lookup/__init__.py

@@ -0,0 +1,25 @@
+"""seer.lookup — codebase classification + lookup verbs.
+
+This package is the sibling of `seer.repo`: it answers "what kind of project
+is this?" / "where is X?" rather than "tell me about this repo."
+"""
+
+from __future__ import annotations
+
+from seer.lookup.ast_scope import Scope, find_enclosing, list_symbols
+from seer.lookup.classify import classify
+from seer.lookup.grep_context import grep_with_context, render_grep_markdown
+from seer.lookup.recent_outline import recent_with_outline, render_recent_markdown
+from seer.lookup.render import render_classify_markdown
+
+__all__ = [
+    "classify",
+    "find_enclosing",
+    "grep_with_context",
+    "list_symbols",
+    "recent_with_outline",
+    "render_classify_markdown",
+    "render_grep_markdown",
+    "render_recent_markdown",
+    "Scope",
+]

seer/lookup/ast_scope.py

@@ -0,0 +1,74 @@
+"""seer.lookup.ast_scope — AST-based scope resolver (stdlib ast only).
+
+Provides:
+  Scope          — frozen dataclass describing a named code scope.
+  list_symbols   — collect all module-level + class-method scopes.
+  find_enclosing — smallest scope whose line range contains a given line.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+
+__all__ = ["Scope", "list_symbols", "find_enclosing"]
+
+
+@dataclass(frozen=True)
+class Scope:
+    kind: str  # "function" | "async_function" | "class"
+    name: str  # qualified, e.g. "Foo.method_a"
+    start_line: int
+    end_line: int
+
+
+def _scope_kind(node: ast.AST) -> str | None:
+    """Return the scope kind string for *node*, or ``None`` if not a named scope."""
+    if isinstance(node, ast.AsyncFunctionDef):
+        return "async_function"
+    if isinstance(node, ast.ClassDef):
+        return "class"
+    if isinstance(node, ast.FunctionDef):
+        return "function"
+    return None
+
+
+def list_symbols(tree: ast.AST) -> list[Scope]:
+    """Walk *tree* and return one :class:`Scope` per named scope.
+
+    Covers:
+    - Module-level functions, async functions, and classes.
+    - Methods defined directly inside a class (one level of nesting per
+      class, but classes inside classes recurse so ``Outer.Inner.method``
+      is emitted correctly).
+
+    Does **not** recurse into function bodies.
+    """
+    out: list[Scope] = []
+
+    def visit(node: ast.AST, prefix: str = "") -> None:
+        for child in ast.iter_child_nodes(node):
+            kind = _scope_kind(child)
+            if kind is None:
+                continue
+            name = f"{prefix}{child.name}"  # type: ignore[attr-defined]
+            end = child.end_lineno or child.lineno  # type: ignore[attr-defined]
+            start = child.lineno  # type: ignore[attr-defined]
+            out.append(Scope(kind=kind, name=name, start_line=start, end_line=end))
+            if isinstance(child, ast.ClassDef):
+                visit(child, prefix=f"{name}.")
+
+    visit(tree)
+    return out
+
+
+def find_enclosing(tree: ast.AST, line: int) -> Scope | None:
+    """Return the smallest :class:`Scope` whose ``[start_line, end_line]``
+    contains *line*, or ``None`` for module-level lines.
+    """
+    best: Scope | None = None
+    for s in list_symbols(tree):
+        if s.start_line <= line <= s.end_line:
+            if best is None or (s.end_line - s.start_line) < (best.end_line - best.start_line):
+                best = s
+    return best

seer/lookup/classify.py

@@ -0,0 +1,301 @@
+"""Project-type classifier.
+
+`classify(path)` returns a dict with `path`, `manifest`, `language`, and
+`tags` (a list of `{name, evidence}` dicts). Per-tag rules are pure
+functions of a `_Context` snapshot — one filesystem walk per call.
+"""
+
+from __future__ import annotations
+
+import json
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from seer.cli._errors import EXIT_ENV_ERROR, EXIT_USER_ERROR, SeerError
+from seer.repo.errors import malformed_pyproject
+
+
+@dataclass
+class _Context:
+    """Filesystem snapshot consumed by per-tag rules. One walk per classify() call."""
+
+    path: Path
+    pyproject: dict | None = None
+    package_json: dict | None = None
+    bash_scripts: list[Path] = field(default_factory=list)
+    has_dockerfile: bool = False
+    has_compose: bool = False
+    compose_filename: str | None = None
+    has_tests_dir: bool = False
+    workflow_files: list[Path] = field(default_factory=list)
+    has_culture_yaml: bool = False
+
+
+_COMPOSE_FILENAMES = ("docker-compose.yml", "docker-compose.yaml", "compose.yml", "compose.yaml")
+
+
+def _load_pyproject(path: Path) -> dict | None:
+    """Parse `path/pyproject.toml` or return None if absent.
+
+    Raises `SeerError(EXIT_ENV_ERROR)` if the file exists but is unreadable
+    (OS error, non-UTF8) or malformed (invalid TOML).
+    """
+    pyproject = path / "pyproject.toml"
+    if not pyproject.exists():
+        return None
+    try:
+        text = pyproject.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as e:
+        raise _pyproject_unreadable_error(pyproject, str(e)) from e
+    try:
+        return tomllib.loads(text)
+    except tomllib.TOMLDecodeError as e:
+        raise malformed_pyproject(pyproject, str(e)) from e
+
+
+def _load_package_json(path: Path) -> dict | None:
+    """Parse `path/package.json` or return None if absent / unreadable / malformed.
+
+    Soft-fails on any read/decode/parse error — Node tools handle missing or
+    bad manifests gracefully and we follow the same "fail-soft for optional
+    sources" pattern here.
+    """
+    package_json = path / "package.json"
+    if not package_json.exists():
+        return None
+    try:
+        return json.loads(package_json.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError):
+        return None
+
+
+def _detect_compose(path: Path) -> str | None:
+    """Return the first matching compose filename present at *path*, or None."""
+    for compose in _COMPOSE_FILENAMES:
+        if (path / compose).exists():
+            return compose
+    return None
+
+
+def _build_context(path: Path) -> _Context:
+    """Walk *path* once and capture every signal the rule set needs."""
+    ctx = _Context(path=path)
+    ctx.pyproject = _load_pyproject(path)
+    ctx.package_json = _load_package_json(path)
+
+    scripts_dir = path / "scripts"
+    if scripts_dir.is_dir():
+        ctx.bash_scripts = sorted(p for p in scripts_dir.iterdir() if p.suffix == ".sh")
+
+    ctx.has_dockerfile = (path / "Dockerfile").exists()
+    compose = _detect_compose(path)
+    if compose is not None:
+        ctx.has_compose = True
+        ctx.compose_filename = compose
+
+    ctx.has_culture_yaml = (path / "culture.yaml").exists()
+    ctx.has_tests_dir = (path / "tests").is_dir()
+
+    workflows_dir = path / ".github" / "workflows"
+    if workflows_dir.is_dir():
+        ctx.workflow_files = sorted(
+            p for p in workflows_dir.iterdir() if p.suffix in (".yml", ".yaml")
+        )
+
+    return ctx
+
+
+def _rule_python(ctx: _Context) -> dict[str, str] | None:
+    if ctx.pyproject is None:
+        return None
+    return {"name": "python", "evidence": "pyproject.toml present"}
+
+
+def _rule_node(ctx: _Context) -> dict[str, str] | None:
+    if ctx.package_json is None:
+        return None
+    return {"name": "node", "evidence": "package.json present"}
+
+
+def _rule_bash(ctx: _Context) -> dict[str, str] | None:
+    if ctx.pyproject is not None or ctx.package_json is not None:
+        return None
+    if not ctx.bash_scripts:
+        return None
+    n = len(ctx.bash_scripts)
+    file_word = "file" if n == 1 else "files"
+    return {
+        "name": "bash",
+        "evidence": f"scripts/ contains {n} .sh {file_word}; no Python/Node manifest",
+    }
+
+
+def _rule_cli(ctx: _Context) -> dict[str, str] | None:
+    # Python: [project.scripts] non-empty.
+    if ctx.pyproject is not None:
+        scripts = (ctx.pyproject.get("project", {}) or {}).get("scripts", {}) or {}
+        if scripts:
+            entries = ", ".join(f'{k} = "{v}"' for k, v in scripts.items())
+            return {"name": "cli", "evidence": f"[project.scripts] defines {entries}"}
+    # Node: package.json `bin` non-empty (object or string).
+    if ctx.package_json is not None:
+        bin_field = ctx.package_json.get("bin")
+        if bin_field:
+            if isinstance(bin_field, dict):
+                names = ", ".join(bin_field.keys())
+            else:
+                names = ctx.package_json.get("name", "<unnamed>")
+            return {"name": "cli", "evidence": f"package.json bin defines {names}"}
+    return None
+
+
+def _rule_library(ctx: _Context) -> dict[str, str] | None:
+    """Importable Python package: `<name>/__init__.py` or `src/<name>/__init__.py`."""
+    if ctx.pyproject is None:
+        return None
+    name = (ctx.pyproject.get("project", {}) or {}).get("name")
+    if not name:
+        return None
+    # PyPI normalises hyphen vs underscore; check both possible package dir names.
+    candidates = [name, name.replace("-", "_")]
+    for candidate in candidates:
+        flat = ctx.path / candidate / "__init__.py"
+        if flat.exists():
+            return {"name": "library", "evidence": f"`{candidate}/__init__.py` present"}
+        nested = ctx.path / "src" / candidate / "__init__.py"
+        if nested.exists():
+            return {"name": "library", "evidence": f"`src/{candidate}/__init__.py` present"}
+    return None
+
+
+def _rule_dockerized(ctx: _Context) -> dict[str, str] | None:
+    if ctx.has_dockerfile:
+        return {"name": "dockerized", "evidence": "Dockerfile present"}
+    if ctx.has_compose and ctx.compose_filename:
+        return {"name": "dockerized", "evidence": f"{ctx.compose_filename} present"}
+    return None
+
+
+def _rule_tested(ctx: _Context) -> dict[str, str] | None:
+    if not ctx.has_tests_dir:
+        return None
+    # Python path: pytest in [dependency-groups] dev
+    if ctx.pyproject is not None:
+        dev_deps = (ctx.pyproject.get("dependency-groups", {}) or {}).get("dev", []) or []
+        # Strip version spec: pytest>=8.0 -> pytest; pytest==8.1 -> pytest; etc.
+        dep_names = {d.split(">=")[0].split("==")[0].split("~=")[0].strip() for d in dev_deps}
+        if "pytest" in dep_names:
+            return {
+                "name": "tested",
+                "evidence": "tests/ exists; pytest in dependency-groups.dev",
+            }
+    # Node path: scripts.test defined
+    if ctx.package_json is not None:
+        scripts = ctx.package_json.get("scripts", {}) or {}
+        if scripts.get("test"):
+            return {
+                "name": "tested",
+                "evidence": f"tests/ exists; package.json scripts.test = {scripts['test']!r}",
+            }
+    return None
+
+
+def _rule_packaged_pypi(ctx: _Context) -> dict[str, str] | None:
+    needles = ("pypi.org", "pypa/gh-action-pypi-publish")
+    for wf in ctx.workflow_files:
+        try:
+            text = wf.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            # Best-effort: skip unreadable / undecodable workflow files
+            # rather than aborting classification.
+            continue
+        if any(needle in text for needle in needles):
+            return {
+                "name": "packaged-pypi",
+                "evidence": f".github/workflows/{wf.name} uploads to pypi.org",
+            }
+    return None
+
+
+def _rule_agentculture_sibling(ctx: _Context) -> dict[str, str] | None:
+    if ctx.has_culture_yaml:
+        return {"name": "agentculture-sibling", "evidence": "culture.yaml present"}
+    return None
+
+
+_RULES = [
+    _rule_python,
+    _rule_node,
+    _rule_bash,
+    _rule_cli,
+    _rule_library,
+    _rule_dockerized,
+    _rule_tested,
+    _rule_packaged_pypi,
+    _rule_agentculture_sibling,
+]
+
+
+def _path_not_found_error(p: Path) -> SeerError:
+    return SeerError(
+        code=EXIT_USER_ERROR,
+        kind="user_error",
+        message=f"path not found: {p}",
+        reason="classify expected a directory path that exists on disk.",
+        remediation="check the path argument and retry.",
+    )
+
+
+def _path_not_a_directory_error(p: Path) -> SeerError:
+    return SeerError(
+        code=EXIT_USER_ERROR,
+        kind="user_error",
+        message=f"classify expects a directory, got file: {p}",
+        reason="classify operates on a repository root, not a single file.",
+        remediation="pass the parent directory.",
+    )
+
+
+def _pyproject_unreadable_error(p: Path, detail: str) -> SeerError:
+    return SeerError(
+        code=EXIT_ENV_ERROR,
+        kind="env_error",
+        message=f"cannot read pyproject.toml at {p}",
+        reason=f"OS or decode error while reading the manifest: {detail}",
+        remediation=("check file permissions and confirm the file is valid UTF-8."),
+    )
+
+
+def classify(path: Path) -> dict[str, object]:
+    """Return `{path, manifest, language, tags}` for the repo at *path*."""
+    if not path.exists():
+        raise _path_not_found_error(path)
+    if not path.is_dir():
+        raise _path_not_a_directory_error(path)
+
+    ctx = _build_context(path)
+    tags: list[dict[str, str]] = []
+    for rule in _RULES:
+        result = rule(ctx)
+        if result is not None:
+            tags.append(result)
+
+    # Manifest + language derivation. Python wins over Node when both present
+    # (see spec — polyglot caller should read the tag list, not the scalar).
+    if ctx.pyproject is not None:
+        manifest: str | None = "pyproject.toml"
+        language = "python"
+    elif ctx.package_json is not None:
+        manifest = "package.json"
+        language = "node"
+    else:
+        manifest = None
+        language = "unknown"
+
+    return {
+        "path": str(path),
+        "manifest": manifest,
+        "language": language,
+        "tags": tags,
+    }

seer/lookup/grep_context.py

@@ -0,0 +1,160 @@
+"""seer.lookup.grep_context — ripgrep-backed search with AST scope annotation.
+
+Provides:
+  grep_with_context  — run ``rg --json`` and pair every match with the
+                       enclosing Python scope from the AST resolver.
+  render_grep_markdown — format grep results as a Markdown table.
+"""
+
+from __future__ import annotations
+
+import ast
+import json
+import subprocess  # noqa: S404  # nosec B404
+from pathlib import Path
+from typing import Any
+
+from seer.cli._errors import EXIT_ENV_ERROR, EXIT_USER_ERROR, SeerError
+from seer.lookup.ast_scope import find_enclosing
+
+__all__ = ["grep_with_context", "render_grep_markdown"]
+
+
+def _run_rg(pattern: str, path: Path) -> "subprocess.CompletedProcess[str]":
+    """Run ``rg --json``; raise :class:`SeerError` on missing binary or exit code 2+."""
+    try:
+        result = subprocess.run(  # noqa: S603,S607  # nosec B603 B607
+            ["rg", "--json", pattern, str(path)],
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=30,
+        )
+    except FileNotFoundError:
+        raise SeerError(
+            code=EXIT_ENV_ERROR,
+            kind="env_error",
+            message="`rg` not found on PATH",
+            reason="seer grep requires ripgrep (rg) for match-finding.",
+            remediation=("install ripgrep (e.g. `apt install ripgrep` or `brew install ripgrep`)."),
+        )
+    except subprocess.SubprocessError as exc:
+        raise SeerError(
+            code=EXIT_ENV_ERROR,
+            kind="env_error",
+            message=f"rg subprocess failed: {exc}",
+        )
+
+    # rg exits 1 when there are no matches — that is not an error.
+    if result.returncode >= 2:
+        stderr_snippet = result.stderr.strip()[:200]
+        raise SeerError(
+            code=EXIT_ENV_ERROR,
+            kind="env_error",
+            message=f"rg exited with code {result.returncode}",
+            reason=stderr_snippet or "rg reported an error.",
+            remediation="check that the pattern is a valid regex and the path is readable.",
+        )
+
+    return result
+
+
+def _parse_rg_matches(stdout: str) -> "dict[str, list[dict[str, Any]]]":
+    """Group ``rg --json`` match events by file, preserving emission order."""
+    matches_by_file: dict[str, list[dict[str, Any]]] = {}
+    for raw_line in stdout.splitlines():
+        raw_line = raw_line.strip()
+        if not raw_line:
+            continue
+        try:
+            event = json.loads(raw_line)
+        except json.JSONDecodeError:
+            continue
+        if event.get("type") != "match":
+            continue
+        data = event.get("data", {})
+        file_str = (data.get("path") or {}).get("text", "")
+        line_num = data.get("line_number", 0)
+        line_text = ((data.get("lines") or {}).get("text") or "").rstrip("\n")
+        entry: dict[str, Any] = {
+            "file": file_str,
+            "line": line_num,
+            "scope": None,  # filled in by _annotate_scopes
+            "text": line_text,
+        }
+        matches_by_file.setdefault(file_str, []).append(entry)
+    return matches_by_file
+
+
+def _annotate_scopes(file_str: str, entries: "list[dict[str, Any]]") -> None:
+    """Resolve the enclosing Python scope for each entry in *entries* (in-place)."""
+    if not file_str.endswith(".py"):
+        return
+    try:
+        source = Path(file_str).read_text(encoding="utf-8")
+        tree = ast.parse(source)
+    except (SyntaxError, OSError, UnicodeDecodeError):
+        # Best-effort: leave scope=None for all matches in this file.
+        return
+    for entry in entries:
+        scope_obj = find_enclosing(tree, entry["line"])
+        entry["scope"] = scope_obj.name if scope_obj else None
+
+
+def grep_with_context(pattern: str, path: str | Path) -> dict[str, Any]:
+    """Search *path* for *pattern* via ``rg --json`` and annotate each match.
+
+    Each match in the returned dict has the shape::
+
+        {"file": str, "line": int, "scope": str | None, "text": str}
+
+    ``scope`` is the qualified name of the enclosing function / method / class
+    for Python files (``None`` for module-level lines and all non-Python files).
+
+    Raises:
+        SeerError(EXIT_USER_ERROR): *path* does not exist.
+        SeerError(EXIT_ENV_ERROR):  ``rg`` is not on PATH, or rg exits with
+                                    code 2+ (real error, not "no matches").
+    """
+    p = Path(path)
+    if not p.exists():
+        raise SeerError(
+            code=EXIT_USER_ERROR,
+            kind="user_error",
+            message=f"path not found: {path}",
+            remediation="pass an existing file or directory.",
+        )
+
+    result = _run_rg(pattern, p)
+    matches_by_file = _parse_rg_matches(result.stdout)
+
+    for file_str, entries in matches_by_file.items():
+        _annotate_scopes(file_str, entries)
+
+    all_matches = [entry for entries in matches_by_file.values() for entry in entries]
+    return {"pattern": pattern, "matches": all_matches}
+
+
+def render_grep_markdown(data: dict[str, Any]) -> str:
+    """Render a :func:`grep_with_context` result dict as a Markdown table."""
+    lines: list[str] = []
+    pattern = data.get("pattern", "")
+    matches = data.get("matches") or []
+
+    lines.append(f"# grep: `{pattern}`")
+    lines.append("")
+
+    if not matches:
+        lines.append("_No matches found._")
+        return "\n".join(lines) + "\n"
+
+    lines.append("| File | Line | Scope | Text |")
+    lines.append("|---|---|---|---|")
+    for m in matches:
+        file_cell = m.get("file", "")
+        line_cell = str(m.get("line", ""))
+        scope_cell = m.get("scope") or "_module_"
+        text_cell = (m.get("text") or "").replace("|", "\\|")
+        lines.append(f"| {file_cell} | {line_cell} | {scope_cell} | {text_cell} |")
+
+    return "\n".join(lines) + "\n"