kata-cli 0.7.0__py3-none-any.whl

seer/lookup/recent_outline.py

@@ -0,0 +1,304 @@
+"""seer.lookup.recent_outline — git log + AST symbol diff per commit.
+
+Provides:
+  recent_with_outline  — run ``git log`` and pair every changed file with
+                         a structural symbol-diff (functions/classes added /
+                         removed / modified) at the AST level.
+  render_recent_markdown — format the result as a Markdown commit log.
+"""
+
+from __future__ import annotations
+
+import ast
+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 list_symbols
+
+__all__ = ["recent_with_outline", "render_recent_markdown"]
+
+
+def _run_git(  # type: ignore[type-arg]
+    args: list[str],
+    path: Path,
+    allow_nonzero: bool = False,
+) -> subprocess.CompletedProcess:
+    """Run a git command in *path* and return the CompletedProcess.
+
+    Raises:
+        SeerError(EXIT_ENV_ERROR): git not found on PATH.
+        SeerError(EXIT_ENV_ERROR): git exits non-zero (unless *allow_nonzero*).
+    """
+    try:
+        result = subprocess.run(  # noqa: S603,S607  # nosec B603 B607
+            ["git", "-C", str(path), *args],
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=30,
+        )
+    except FileNotFoundError:
+        raise SeerError(
+            code=EXIT_ENV_ERROR,
+            kind="env_error",
+            message="git not found on PATH",
+            remediation="install git and ensure it is on your PATH.",
+        )
+    except subprocess.SubprocessError as exc:
+        raise SeerError(
+            code=EXIT_ENV_ERROR,
+            kind="env_error",
+            message=f"git subprocess failed: {exc}",
+        )
+
+    if not allow_nonzero and result.returncode != 0:
+        raise SeerError(
+            code=EXIT_ENV_ERROR,
+            kind="env_error",
+            message=f"git exited with code {result.returncode}",
+            reason=result.stderr.strip()[:400],
+        )
+
+    return result
+
+
+def _symbols_from_source(source: str) -> dict[str, Any]:
+    """Parse *source* and return a mapping of symbol name → Scope.
+
+    On parse failure (SyntaxError, ValueError) returns an empty dict —
+    graceful degradation for files with syntax errors.
+    """
+    try:
+        tree = ast.parse(source)
+    except (SyntaxError, ValueError):
+        return {}
+    return {s.name: s for s in list_symbols(tree)}
+
+
+def _file_diff(sha: str, file_path: str, repo_path: Path, is_initial: bool) -> dict[str, Any]:
+    """Return the symbol diff for a single *file_path* in commit *sha*.
+
+    For non-Python files always returns empty added/removed/modified.
+
+    The "modified" heuristic compares (start_line, end_line) tuples between
+    before and after versions.  A pure line-shift (e.g. adding a blank line
+    above a function) can cause a false positive here; content hashing would
+    eliminate these false positives but is deferred as a future improvement.
+    """
+    # Get "before" content (parent version).  For the initial commit the
+    # parent reference <sha>^ does not exist, so we treat before as empty.
+    if is_initial:
+        before = ""
+    else:
+        before_result = _run_git(
+            ["show", f"{sha}^:{file_path}"],
+            repo_path,
+            allow_nonzero=True,
+        )
+        before = before_result.stdout if before_result.returncode == 0 else ""
+
+    # Get "after" content (this commit's version).
+    after_result = _run_git(
+        ["show", f"{sha}:{file_path}"],
+        repo_path,
+        allow_nonzero=True,
+    )
+    after = after_result.stdout if after_result.returncode == 0 else ""
+
+    entry: dict[str, Any] = {"file": file_path, "added": [], "removed": [], "modified": []}
+
+    if not file_path.endswith(".py"):
+        return entry
+
+    before_map = _symbols_from_source(before)
+    after_map = _symbols_from_source(after)
+
+    before_names = set(before_map)
+    after_names = set(after_map)
+
+    entry["added"] = sorted(after_names - before_names)
+    entry["removed"] = sorted(before_names - after_names)
+    entry["modified"] = sorted(
+        name
+        for name in before_names & after_names
+        if (before_map[name].start_line, before_map[name].end_line)
+        != (after_map[name].start_line, after_map[name].end_line)
+    )
+
+    return entry
+
+
+def _validate_recent_args(n: int, path: str | Path) -> Path:
+    """Validate *n* and *path*; return the resolved repo Path on success."""
+    repo = Path(path)
+    if n < 1:
+        raise SeerError(
+            code=EXIT_USER_ERROR,
+            kind="user_error",
+            message=f"n must be >= 1, got {n}",
+            remediation="pass a positive integer for the commit count.",
+        )
+    if not repo.exists() or not repo.is_dir():
+        raise SeerError(
+            code=EXIT_USER_ERROR,
+            kind="user_error",
+            message=f"path is not an existing directory: {path}",
+            remediation="pass an existing directory that contains a git repository.",
+        )
+    rev_parse = _run_git(["rev-parse", "--is-inside-work-tree"], repo, allow_nonzero=True)
+    if rev_parse.returncode != 0 or rev_parse.stdout.strip() != "true":
+        raise SeerError(
+            code=EXIT_USER_ERROR,
+            kind="user_error",
+            message=f"not a git repository: {path}",
+            reason=(rev_parse.stderr.strip()[:200] or "git rev-parse rejected the path."),
+            remediation="pass a path that is inside a git work tree.",
+        )
+    return repo
+
+
+def _fetch_commit_lines(repo: Path, n: int) -> list[str]:
+    """Run `git log -n N`; return the non-empty SHA/date/subject lines.
+
+    Returns ``[]`` for the empty-repo case (exit 128 with the sentinel
+    stderr). Raises ``SeerError(EXIT_ENV_ERROR)`` for any other fatal error.
+    """
+    log_result = _run_git(
+        ["log", f"-n{n}", "--pretty=format:%H%x09%cI%x09%s"], repo, allow_nonzero=True
+    )
+    if log_result.returncode == 128:
+        stderr_lc = log_result.stderr.lower()
+        if "does not have any commits yet" not in stderr_lc and "fatal" in stderr_lc:
+            raise SeerError(
+                code=EXIT_ENV_ERROR,
+                kind="env_error",
+                message="git log failed",
+                reason=log_result.stderr.strip()[:400],
+            )
+    elif log_result.returncode != 0:
+        raise SeerError(
+            code=EXIT_ENV_ERROR,
+            kind="env_error",
+            message=f"git log exited with code {log_result.returncode}",
+            reason=log_result.stderr.strip()[:400],
+        )
+    raw_log = log_result.stdout.strip()
+    return raw_log.splitlines() if raw_log else []
+
+
+def recent_with_outline(n: int = 20, path: str | Path = ".") -> dict[str, Any]:
+    """Return the last *n* commits in *path*, each paired with AST symbol diffs.
+
+    The returned dict has the shape::
+
+        {"commits": [
+          {"sha": "abc1234",  # 7-char prefix
+           "date": "2026-05-15",  # YYYY-MM-DD
+           "subject": "feat: ...",
+           "changes": [
+             {"file": "lib.py",
+              "added": ["bar"], "removed": [], "modified": ["foo"]},
+             {"file": "README.md",
+              "added": [], "removed": [], "modified": []},
+           ]},
+          ...
+        ]}
+
+    Commits are ordered newest-first (same as ``git log``).
+
+    Raises:
+        SeerError(EXIT_USER_ERROR): *n* < 1 or *path* is not an existing directory.
+        SeerError(EXIT_ENV_ERROR):  git not found, or git exits with a fatal error.
+    """
+    repo = _validate_recent_args(n, path)
+    commit_lines = _fetch_commit_lines(repo, n)
+    if not commit_lines:
+        return {"commits": []}
+
+    # Determine which commit is the initial commit (no parent).
+    # We do this by getting the root commit SHA.
+    root_result = _run_git(
+        ["rev-list", "--max-parents=0", "HEAD"],
+        repo,
+        allow_nonzero=True,
+    )
+    root_sha = root_result.stdout.strip() if root_result.returncode == 0 else None
+
+    commits: list[dict[str, Any]] = []
+
+    for line in commit_lines:
+        parts = line.split("\t", 2)
+        if len(parts) < 3:
+            continue
+        full_sha, iso_date, subject = parts
+        short_sha = full_sha[:7]
+        date = iso_date.split("T")[0]
+        is_initial = root_sha is not None and full_sha == root_sha
+
+        # Get the list of files changed in this commit.
+        if is_initial:
+            diff_args = ["diff-tree", "--no-commit-id", "--name-only", "-r", "--root", full_sha]
+        else:
+            diff_args = ["diff-tree", "--no-commit-id", "--name-only", "-r", full_sha]
+
+        files_result = _run_git(diff_args, repo, allow_nonzero=True)
+        changed_files = [f.strip() for f in files_result.stdout.splitlines() if f.strip()]
+
+        changes = [_file_diff(full_sha, f, repo, is_initial=is_initial) for f in changed_files]
+
+        commits.append(
+            {
+                "sha": short_sha,
+                "date": date,
+                "subject": subject,
+                "changes": changes,
+            }
+        )
+
+    return {"commits": commits}
+
+
+def _render_change_line(ch: dict[str, Any]) -> str:
+    """Format one changed-file entry as a Markdown bullet line."""
+    file_name = ch.get("file", "")
+    added = ch.get("added") or []
+    removed = ch.get("removed") or []
+    modified = ch.get("modified") or []
+    if not (added or removed or modified):
+        return f"- {file_name}"
+    parts: list[str] = []
+    if added:
+        parts.append(f"+{', '.join(added)}")
+    if removed:
+        parts.append(f"-{', '.join(removed)}")
+    if modified:
+        parts.append(f"~{', '.join(modified)}")
+    return f"- **{file_name}**: {', '.join(parts)}"
+
+
+def render_recent_markdown(data: dict[str, Any]) -> str:
+    """Render a :func:`recent_with_outline` result dict as Markdown.
+
+    Each commit gets a ``###`` heading followed by a bullet list of changed
+    files.  Python files with non-empty symbol diffs render with ``+added``,
+    ``-removed``, ``~modified`` inline annotations.
+    """
+    commits = data.get("commits") or []
+    if not commits:
+        return "_No commits found._\n"
+
+    lines: list[str] = []
+    for commit in commits:
+        sha = commit.get("sha", "")
+        date = commit.get("date", "")
+        subject = commit.get("subject", "")
+        changes = commit.get("changes") or []
+        lines.append(f"### {sha} ({date}) {subject}")
+        lines.append("")
+        for ch in changes:
+            lines.append(_render_change_line(ch))
+        lines.append("")
+
+    return "\n".join(lines)

seer/lookup/render.py

@@ -0,0 +1,41 @@
+"""Markdown emitter for seer.lookup.classify."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def _section_break(lines: list[str]) -> None:
+    """Emit a blank line + horizontal rule before a top-level section heading."""
+    lines.append("")
+    lines.append("---")
+
+
+def render_classify_markdown(data: dict[str, Any]) -> str:
+    """Render a classify() dict as a markdown report."""
+    lines: list[str] = []
+    lines.append(f"# {data.get('path', '(unknown)')}")
+
+    manifest = data.get("manifest")
+    language = data.get("language") or "unknown"
+    if manifest:
+        lines.append(f"- **Manifest:** {manifest} ({language})")
+    else:
+        lines.append(f"- **Manifest:** none ({language})")
+
+    tags = data.get("tags") or []
+    if tags:
+        names = ", ".join(t["name"] for t in tags)
+        lines.append(f"- **Tags:** {names}")
+    else:
+        lines.append("- **Tags:** _(none)_")
+
+    if tags:
+        _section_break(lines)
+        lines.append("## Tags")
+        lines.append("| Tag | Evidence |")
+        lines.append("|---|---|")
+        for t in tags:
+            lines.append(f"| `{t['name']}` | {t['evidence']} |")
+
+    return "\n".join(lines) + "\n"

seer/repo/__init__.py

@@ -0,0 +1,9 @@
+"""seer.repo — repo profiling, connection walks, and workspace graphs.
+
+Forward-compatible with seer-cli's eventual `whoami` / `explain` / `learn`
+verbs; today the entry point is `python -m seer.repo <verb>`.
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []

seer/repo/__main__.py

@@ -0,0 +1,228 @@
+"""argparse dispatch for ``python -m seer.repo``.
+
+Verbs:
+
+  profile <path> [--depth shallow|deep] [--json]
+  connections <path> [--depth N|all] [--profile] [--depth-profile shallow|deep]
+              [--root PATH ...] [--marker FILE ...] [--strict] [--json]
+  graph [<root>...] [--marker FILE ...] [--strict] [--json]
+
+Output: markdown by default; JSON when ``--json`` is passed.
+Errors: routed through :func:`_dispatch`, which loads config and invokes the
+verb handler inside a single try/except so neither config-load nor verb
+execution can leak a Python traceback. Partial-failure inlining for walks
+lives inside :func:`seer.repo.connections.walk` /
+:func:`seer.repo.graph.build_graph`.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from seer.cli._errors import (
+    EXIT_ENV_ERROR,
+    EXIT_INTERNAL,
+    EXIT_USER_ERROR,
+    SeerError,
+)
+from seer.cli._output import emit_error, emit_result
+from seer.repo.config import RepoMapConfig, load_config
+from seer.repo.connections import walk
+from seer.repo.errors import path_not_a_directory
+from seer.repo.graph import build_graph
+from seer.repo.profile import profile_deep, profile_shallow
+from seer.repo.render import (
+    render_connections_markdown,
+    render_graph_markdown,
+    render_profile_markdown,
+)
+
+
+def _profile(args: argparse.Namespace, _cfg: RepoMapConfig) -> int:
+    """Handle the ``profile`` verb."""
+    path = Path(args.path)
+    if not path.is_dir():
+        raise path_not_a_directory(path)
+    basic = bool(getattr(args, "basic", False))
+    if args.depth == "deep":
+        data = profile_deep(path, basic=basic)
+    else:
+        data = profile_shallow(path, basic=basic)
+    if args.json:
+        emit_result({"ok": True, "data": data}, json_mode=True)
+    else:
+        emit_result(render_profile_markdown(data), json_mode=False)
+    return 0
+
+
+def _connections(args: argparse.Namespace, cfg: RepoMapConfig) -> int:
+    """Handle the ``connections`` verb."""
+    seed = Path(args.path)
+    if not seed.is_dir():
+        raise path_not_a_directory(seed)
+    roots = [Path(r) for r in (args.root or [str(p) for p in cfg.roots])]
+    # `--depth` defaults to None at the parser level so the configured
+    # `default_connections_depth` is reachable when the user doesn't pass
+    # an explicit flag.
+    depth = args.depth if args.depth is not None else cfg.default_connections_depth
+    result = walk(
+        seed=seed,
+        roots=roots,
+        depth=depth,
+        with_profile=args.profile,
+        depth_profile=args.depth_profile,
+        additional_markers=(args.marker or cfg.additional_markers),
+        skip_dirs=cfg.skip_dirs,
+        strict=args.strict,
+    )
+    if args.json:
+        emit_result({"ok": True, "data": result}, json_mode=True)
+    else:
+        emit_result(render_connections_markdown(result), json_mode=False)
+    return 0
+
+
+def _graph(args: argparse.Namespace, cfg: RepoMapConfig) -> int:
+    """Handle the ``graph`` verb."""
+    roots = [Path(r) for r in (args.roots or [str(p) for p in cfg.roots])]
+    result = build_graph(
+        roots,
+        additional_markers=(args.marker or cfg.additional_markers),
+        skip_dirs=cfg.skip_dirs,
+        strict=args.strict,
+    )
+    if args.json:
+        emit_result({"ok": True, "data": result}, json_mode=True)
+    else:
+        emit_result(render_graph_markdown(result), json_mode=False)
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Build and return the argparse parser for ``python -m seer.repo``."""
+    parser = argparse.ArgumentParser(
+        prog="seer.repo",
+        description="repo-map engine: profile / connections / graph.",
+    )
+    sub = parser.add_subparsers(dest="verb")
+
+    pp = sub.add_parser("profile", help="Profile one repo.")
+    pp.add_argument("path")
+    pp.add_argument("--depth", choices=["shallow", "deep"], default="shallow")
+    pp.add_argument(
+        "--basic",
+        action="store_true",
+        help=(
+            "Skip Tier-2 online fields (github_state, pypi_state) — "
+            "Tier-1 mechanical fields only."
+        ),
+    )
+    pp.add_argument("--json", action="store_true")
+    pp.set_defaults(func=_profile)
+
+    pc = sub.add_parser("connections", help="Walk outward from a seed repo.")
+    pc.add_argument("path")
+    pc.add_argument(
+        "--depth",
+        default=None,
+        help=(
+            "non-negative int or 'all'. When omitted, falls back to "
+            "config `default_connections_depth` (default: 1)."
+        ),
+    )
+    pc.add_argument(
+        "--profile",
+        action="store_true",
+        help="include each internal node's profile",
+    )
+    pc.add_argument(
+        "--depth-profile",
+        choices=["shallow", "deep"],
+        default="shallow",
+        dest="depth_profile",
+    )
+    pc.add_argument(
+        "--root",
+        action="append",
+        default=None,
+        help="root to search for connected repos (repeatable)",
+    )
+    pc.add_argument(
+        "--marker",
+        action="append",
+        default=None,
+        help="additional marker filename (repeatable)",
+    )
+    pc.add_argument(
+        "--strict",
+        action="store_true",
+        help="fail on any per-node error",
+    )
+    pc.add_argument("--json", action="store_true")
+    pc.set_defaults(func=_connections)
+
+    pg = sub.add_parser("graph", help="Multi-root workspace view.")
+    pg.add_argument("roots", nargs="*")
+    pg.add_argument("--marker", action="append", default=None)
+    pg.add_argument("--strict", action="store_true", help="fail on any per-node error")
+    pg.add_argument("--json", action="store_true")
+    pg.set_defaults(func=_graph)
+
+    return parser
+
+
+def _dispatch(args: argparse.Namespace) -> int:
+    """Load config and invoke the verb handler with structured error wrapping.
+
+    Centralises the policy: every failure — whether it originates in
+    :func:`seer.repo.config.load_config` or inside a verb handler — is
+    routed through :func:`seer.cli._output.emit_error` and translated to an
+    exit code. No Python traceback leaks.
+    """
+    json_mode = bool(getattr(args, "json", False))
+    try:
+        cfg = load_config()
+        return args.func(args, cfg)
+    except SeerError as err:
+        emit_error(err, json_mode=json_mode)
+        return err.code
+    except json.JSONDecodeError as err:
+        wrapped = SeerError(
+            code=EXIT_ENV_ERROR,
+            kind="env_error",
+            message="Malformed .claude/skills/repo-map/config.json",
+            reason=f"JSON parse error: {err}",
+            remediation=("Fix the JSON syntax or delete the file to fall back to defaults."),
+        )
+        emit_error(wrapped, json_mode=json_mode)
+        return wrapped.code
+    except Exception as err:  # noqa: BLE001  # pylint: disable=broad-exception-caught
+        wrapped = SeerError(
+            code=EXIT_INTERNAL,
+            kind="bug",
+            message=f"unexpected: {err.__class__.__name__}: {err}",
+            reason="An unhandled exception escaped a seer.repo verb.",
+            remediation="file a bug at https://github.com/agentculture/seer-cli/issues",
+        )
+        emit_error(wrapped, json_mode=json_mode)
+        return wrapped.code
+
+
+def main(argv: list[str] | None = None) -> int:
+    """argparse entry point for ``python -m seer.repo``."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    if args.verb is None:
+        parser.print_help()
+        return 0
+    if not hasattr(args, "func"):
+        parser.print_help()
+        return EXIT_USER_ERROR
+    return _dispatch(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

seer/repo/config.py

@@ -0,0 +1,57 @@
+"""Per-workspace defaults for repo-map.
+
+Loaded from `.claude/skills/repo-map/config.json` (or any path the caller
+passes). Missing file => defaults; missing keys => per-key defaults.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+DEFAULT_SKIP_DIRS: tuple[str, ...] = (
+    ".git",
+    ".venv",
+    "node_modules",
+    "__pycache__",
+)
+
+
+def _default_roots() -> list[Path]:
+    """Return the default root search path list."""
+    return [Path.home() / "git"]
+
+
+def _default_skip_dirs() -> list[str]:
+    """Return the default list of directory names to skip during traversal."""
+    return list(DEFAULT_SKIP_DIRS)
+
+
+@dataclass
+class RepoMapConfig:
+    """Per-workspace defaults consumed by every repo-map verb."""
+
+    roots: list[Path] = field(default_factory=_default_roots)
+    additional_markers: list[str] = field(default_factory=list)
+    skip_dirs: list[str] = field(default_factory=_default_skip_dirs)
+    default_connections_depth: int = 1
+
+
+def load_config(path: Path | None = None) -> RepoMapConfig:
+    """Load config from `path` (default `.claude/skills/repo-map/config.json`).
+
+    Returns :class:`RepoMapConfig` with defaults filled in for missing keys.
+    Raises :exc:`json.JSONDecodeError` if the file exists but is not valid JSON.
+    """
+    if path is None:
+        path = Path(".claude/skills/repo-map/config.json")
+    if not path.exists():
+        return RepoMapConfig()
+    raw = json.loads(path.read_text(encoding="utf-8"))
+    return RepoMapConfig(
+        roots=([Path(r) for r in raw["roots"]] if "roots" in raw else _default_roots()),
+        additional_markers=list(raw.get("additional_markers", [])),
+        skip_dirs=list(raw.get("skip_dirs", DEFAULT_SKIP_DIRS)),
+        default_connections_depth=int(raw.get("default_connections_depth", 1)),
+    )