kata-cli 0.7.0__py3-none-any.whl

seer/repo/connections.py

@@ -0,0 +1,298 @@
+"""BFS walker from a seed repo.
+
+Edge types emitted:
+
+  * ``import``  — from manifest deps_runtime
+  * ``cite``    — from CITATION.md
+  * ``vendor``  — from vendored_skills' ``source`` provenance
+
+Each edge target name is resolved against repos discovered under
+``roots`` via :func:`seer.repo.detect.find_repos`. Unresolvable target names
+become "external" nodes (no path, no profile).
+
+Per-node errors during the walk are collected in the result's
+``walk_errors`` field; the walk continues unless ``strict=True``.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from seer.cli._errors import SeerError
+from seer.repo.detect import find_repos, resolve_name
+from seer.repo.errors import invalid_depth, path_not_a_directory
+from seer.repo.profile import profile_deep, profile_shallow
+
+
+def _coerce_depth(depth: int | str | None) -> int | str:
+    """Normalise *depth* to a non-negative ``int`` or the sentinel ``"all"``.
+
+    Raises :func:`seer.repo.errors.invalid_depth` for any value that is
+    neither a non-negative integer nor the string ``"all"``.
+    """
+    if depth is None:
+        return 1
+    if isinstance(depth, str):
+        if depth == "all":
+            return "all"
+        try:
+            n = int(depth)
+        except ValueError as exc:
+            raise invalid_depth(depth) from exc
+    else:
+        n = depth
+    if n < 0:
+        raise invalid_depth(str(n))
+    return n
+
+
+def _build_index(  # pylint: disable=duplicate-code
+    roots: list[Path],
+    additional_markers: list[str] | None,
+    skip_dirs: list[str] | None,
+) -> dict[str, Path]:
+    """Map every known repo name to its path (first-write wins on collisions)."""
+    index: dict[str, Path] = {}
+    for root in roots:
+        if not root.is_dir():
+            continue
+        for repo in find_repos(
+            root,
+            additional_markers=additional_markers,
+            skip_dirs=skip_dirs,
+        ):
+            name = resolve_name(repo)
+            index.setdefault(name, repo)
+    return index
+
+
+def _strip_version(spec: str) -> str:
+    """Return the bare package name from a PEP 508 dependency specifier.
+
+    Examples::
+
+        "pkg[extra]>=1.0"  -> "pkg"
+        "requests>=2,<3"   -> "requests"
+        "mylib"            -> "mylib"
+    """
+    for sep in ("[", "(", ">=", "<=", ">", "<", "==", "!=", "~="):
+        if sep in spec:
+            spec = spec.split(sep, 1)[0]
+    return spec.strip()
+
+
+def _edges_from_profile(name: str, profile: dict[str, Any]) -> list[dict[str, str]]:
+    """Build the outgoing edge list for *name* from its shallow profile dict."""
+    edges: list[dict[str, str]] = []
+    _collect_import_edges(edges, name, profile.get("deps_runtime") or [])
+    _collect_cite_edges(edges, name, profile.get("citations") or [])
+    _collect_vendor_edges(edges, name, profile.get("vendored_skills") or [])
+    return edges
+
+
+def _collect_import_edges(edges: list[dict[str, str]], name: str, deps: list[Any]) -> None:
+    """Append ``import`` edges to *edges* for each runtime dependency."""
+    for dep in deps:
+        target = _strip_version(dep)
+        if target:
+            edges.append({"from": name, "to": target, "type": "import", "spec": dep})
+
+
+def _collect_cite_edges(edges: list[dict[str, str]], name: str, citations: list[Any]) -> None:
+    """Append ``cite`` edges to *edges* for each CITATION.md row."""
+    for cit in citations:
+        repo = cit.get("source_repo")
+        if repo:
+            edges.append(
+                {
+                    "from": name,
+                    "to": str(repo),
+                    "type": "cite",
+                    "spec": str(cit.get("sha", "")),
+                }
+            )
+
+
+def _collect_vendor_edges(edges: list[dict[str, str]], name: str, skills: list[Any]) -> None:
+    """Append ``vendor`` edges to *edges* for each vendored skill with a source."""
+    for skill in skills:
+        source = skill.get("source")
+        if source:
+            edges.append(
+                {
+                    "from": name,
+                    "to": str(source),
+                    "type": "vendor",
+                    "spec": str(skill.get("name", "")),
+                }
+            )
+
+
+@dataclass
+class _ProfileOpts:
+    """Options that control how nodes are profiled during the BFS walk."""
+
+    with_profile: bool = False
+    depth_profile: str = "shallow"
+    strict: bool = False
+
+
+@dataclass
+class _BfsState:
+    """Mutable BFS accumulator: repo index, depth budget, queue, and results."""
+
+    index: dict[str, Path]
+    depth_n: int | str
+    nodes: list[dict[str, Any]] = field(default_factory=list)
+    edges: list[dict[str, str]] = field(default_factory=list)
+    walk_errors: list[dict[str, str]] = field(default_factory=list)
+    visited: set[str] = field(default_factory=set)
+    queue: deque = field(default_factory=deque)
+
+
+def _profile_node(path: Path, opts: _ProfileOpts) -> tuple[dict[str, Any], dict[str, Any]]:
+    """Return ``(node_extra, shallow_profile)`` for an internal node."""
+    p = profile_shallow(path)
+    node_extra: dict[str, Any] = {"version": p.get("version", "")}
+    if opts.with_profile:
+        node_extra["profile"] = profile_deep(path) if opts.depth_profile == "deep" else p
+    return node_extra, p
+
+
+def _enqueue_targets(
+    outgoing: list[dict[str, str]],
+    state: _BfsState,
+    current_hop: int,
+) -> None:
+    """Push unvisited edge targets onto *state.queue* when the depth budget allows."""
+    within_budget = state.depth_n == "all" or current_hop < int(
+        state.depth_n
+    )  # type: ignore[arg-type]
+    if not within_budget:
+        return
+    for edge in outgoing:
+        target = edge["to"]
+        if target not in state.visited:
+            state.visited.add(target)
+            state.queue.append((target, current_hop + 1))
+
+
+def _expand_node(
+    current_name: str,
+    path: Path,
+    current_hop: int,
+    state: _BfsState,
+    opts: _ProfileOpts,
+) -> dict[str, Any]:
+    """Profile *path*, collect edges, enqueue targets; return the node dict."""
+    node: dict[str, Any] = {"id": current_name, "path": str(path), "external": False}
+    try:
+        node_extra, shallow = _profile_node(path, opts)
+        node.update(node_extra)
+        outgoing = _edges_from_profile(current_name, shallow)
+        state.edges.extend(outgoing)
+        _enqueue_targets(outgoing, state, current_hop)
+    except SeerError as err:
+        if opts.strict:
+            raise
+        state.walk_errors.append(
+            {
+                "node": f"{current_name} ({path})",
+                "reason": err.reason or err.message,
+                "remediation": err.remediation,
+            }
+        )
+    return node
+
+
+def _run_bfs(
+    seed_name: str,
+    index: dict[str, Path],
+    depth_n: int | str,
+    opts: _ProfileOpts,
+) -> _BfsState:
+    """Execute the BFS from *seed_name* and return the populated state."""
+    state = _BfsState(index=index, depth_n=depth_n)
+    state.visited.add(seed_name)
+    state.queue.append((seed_name, 0))
+
+    while state.queue:
+        current_name, current_hop = state.queue.popleft()
+        path = state.index.get(current_name)
+        if path is not None:
+            node = _expand_node(current_name, path, current_hop, state, opts)
+        else:
+            node = {"id": current_name, "path": None, "external": True}
+        state.nodes.append(node)
+
+    return state
+
+
+def walk(  # pylint: disable=too-many-arguments
+    *,
+    seed: Path,
+    roots: list[Path],
+    depth: int | str = 1,
+    with_profile: bool = False,
+    depth_profile: str = "shallow",
+    additional_markers: list[str] | None = None,
+    skip_dirs: list[str] | None = None,
+    strict: bool = False,
+) -> dict[str, Any]:
+    """BFS-walk from *seed* outward, emitting nodes + typed edges.
+
+    Parameters
+    ----------
+    seed:
+        The root repo to start from (must be an existing directory).
+    roots:
+        Workspace roots scanned by :func:`seer.repo.detect.find_repos` to
+        resolve edge targets to local paths.
+    depth:
+        How many hops to follow.  ``1`` visits direct neighbours only;
+        ``"all"`` walks the full connected component.
+    with_profile:
+        When *True*, attach a ``"profile"`` key to each internal node.
+    depth_profile:
+        ``"shallow"`` (default) or ``"deep"``; controls which profiler is
+        used when *with_profile* is *True*.
+    additional_markers:
+        Extra filenames treated as repo markers during discovery.
+    skip_dirs:
+        Directory names skipped during discovery.
+    strict:
+        When *True*, a per-node :class:`SeerError` re-raises immediately
+        instead of being collected in ``walk_errors``.
+
+    Returns
+    -------
+    dict with keys:
+        ``seed``, ``seed_name``, ``depth``, ``nodes``, ``edges``,
+        ``walk_errors``.
+    """
+    if not seed.is_dir():
+        raise path_not_a_directory(seed)
+    depth_n = _coerce_depth(depth)
+
+    index = _build_index(roots, additional_markers, skip_dirs)
+    seed_name = resolve_name(seed)
+    index.setdefault(seed_name, seed)
+
+    opts = _ProfileOpts(
+        with_profile=with_profile,
+        depth_profile=depth_profile,
+        strict=strict,
+    )
+    accum = _run_bfs(seed_name, index, depth_n, opts)
+
+    return {
+        "seed": str(seed),
+        "seed_name": seed_name,
+        "depth": depth_n,
+        "nodes": accum.nodes,
+        "edges": accum.edges,
+        "walk_errors": accum.walk_errors,
+    }

seer/repo/detect.py

@@ -0,0 +1,86 @@
+"""Generic repo detection + name resolution.
+
+A directory is a "repo of interest" when ANY of the following is true:
+
+  1. it contains ``pyproject.toml``
+  2. it contains ``.claude/skills/``
+  3. it contains any file listed in ``additional_markers``
+
+Name resolution prefers, in order:
+
+  1. ``[project].name`` from ``pyproject.toml``
+  2. ``agents[0].suffix`` (or ``.nick``) from ``culture.yaml``
+  3. the directory basename
+"""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+import yaml
+
+
+def is_repo(path: Path, additional_markers: list[str] | None = None) -> bool:
+    """Return True if ``path`` qualifies as a repo of interest."""
+    if not path.is_dir():
+        return False
+    if (path / "pyproject.toml").exists():
+        return True
+    if (path / ".claude" / "skills").is_dir():
+        return True
+    for marker in additional_markers or []:
+        if (path / marker).exists():
+            return True
+    return False
+
+
+def find_repos(
+    root: Path,
+    *,
+    additional_markers: list[str] | None = None,
+    skip_dirs: list[str] | None = None,
+) -> list[Path]:
+    """Return the sorted list of child directories under ``root`` that qualify as repos."""
+    skip = set(skip_dirs or [])
+    repos: list[Path] = []
+    for child in root.iterdir():
+        if not child.is_dir() or child.name in skip:
+            continue
+        if is_repo(child, additional_markers):
+            repos.append(child)
+    return sorted(repos, key=lambda p: p.name)
+
+
+def _name_from_pyproject(path: Path) -> str | None:
+    """Return ``[project].name`` from *path*'s ``pyproject.toml`` if present and parseable."""
+    pyproject = path / "pyproject.toml"
+    if not pyproject.exists():
+        return None
+    try:
+        data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+    except (tomllib.TOMLDecodeError, OSError):
+        return None
+    name = (data.get("project") or {}).get("name")
+    return str(name) if name else None
+
+
+def _name_from_culture_yaml(path: Path) -> str | None:
+    """Return the first agent's nick (``suffix`` or ``nick``) from ``culture.yaml`` if any."""
+    culture_yaml = path / "culture.yaml"
+    if not culture_yaml.exists():
+        return None
+    try:
+        data = yaml.safe_load(culture_yaml.read_text(encoding="utf-8")) or {}
+    except (yaml.YAMLError, OSError):
+        return None
+    agents = data.get("agents", [])
+    if not agents or not isinstance(agents[0], dict):
+        return None
+    nick = agents[0].get("suffix") or agents[0].get("nick")
+    return str(nick) if nick else None
+
+
+def resolve_name(path: Path) -> str:
+    """Return the repo's preferred name (pyproject → culture.yaml → basename)."""
+    return _name_from_pyproject(path) or _name_from_culture_yaml(path) or path.name

seer/repo/errors.py

@@ -0,0 +1,81 @@
+"""Domain-specific :class:`SeerError` factories for seer.repo.
+
+Centralising error construction here keeps message / reason / remediation
+copy uniform across every raise site.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from seer.cli._errors import EXIT_ENV_ERROR, EXIT_USER_ERROR, SeerError
+
+
+def manifest_not_found(path: Path) -> SeerError:
+    """Return a SeerError for a missing pyproject.toml manifest."""
+    return SeerError(
+        code=EXIT_USER_ERROR,
+        kind="user_error",
+        message=f"Cannot find pyproject.toml in {path}",
+        reason=(
+            "No recognized manifest at the given path. Looked for "
+            "pyproject.toml, .claude/skills/, and any configured "
+            "additional_markers."
+        ),
+        remediation=(
+            "Confirm the path points to a repo root, not a subdirectory. "
+            "To treat this directory as a repo regardless, add a marker "
+            "via .claude/skills/repo-map/config.json → additional_markers."
+        ),
+    )
+
+
+def malformed_pyproject(path: Path, detail: str) -> SeerError:
+    """Return a SeerError for a pyproject.toml that exists but won't parse."""
+    return SeerError(
+        code=EXIT_ENV_ERROR,
+        kind="env_error",
+        message=f"Cannot parse {path}",
+        reason=f"TOML syntax error: {detail}",
+        remediation=(
+            f'Validate with `python3 -c "import tomllib; '
+            f"tomllib.load(open('{path}', 'rb'))\"` or fix the file."
+        ),
+    )
+
+
+def invalid_depth(value: str) -> SeerError:
+    """Return a SeerError for a `--depth` value that is neither a non-negative int nor 'all'."""
+    return SeerError(
+        code=EXIT_USER_ERROR,
+        kind="user_error",
+        message=f"Invalid --depth value: '{value}'",
+        reason="--depth must be a non-negative integer or 'all'.",
+        remediation="Try `--depth 1` (default), `--depth 3`, or `--depth all`.",
+    )
+
+
+def path_not_a_directory(path: Path) -> SeerError:
+    """Return a SeerError for a path that doesn't exist or isn't a directory."""
+    return SeerError(
+        code=EXIT_USER_ERROR,
+        kind="user_error",
+        message=f"Path does not exist or is not a directory: {path}",
+        reason="The given path was not a directory on disk.",
+        remediation="Pass an absolute path to an existing directory.",
+    )
+
+
+def seed_not_under_root(seed: Path, roots: list[Path]) -> SeerError:
+    """Return a SeerError for a seed repo that doesn't live under any configured root."""
+    root_list = ", ".join(str(r) for r in roots)
+    return SeerError(
+        code=EXIT_USER_ERROR,
+        kind="user_error",
+        message=f"Seed repo {seed} is not under any configured root",
+        reason=f"Edge resolution requires the seed to live in a configured root: {root_list}.",
+        remediation=(
+            "Pass --root, or add the seed's parent to "
+            ".claude/skills/repo-map/config.json `roots`."
+        ),
+    )

seer/repo/graph.py

@@ -0,0 +1,182 @@
+"""Multi-root workspace view: every repo found + every edge between them.
+
+This is the "show me what's in this workspace" verb, distinct from
+:func:`seer.repo.connections.walk` which traverses outward from a single seed.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from pathlib import Path
+from typing import Any
+
+from seer.cli._errors import SeerError
+from seer.repo.connections import _edges_from_profile
+from seer.repo.detect import find_repos, resolve_name
+from seer.repo.profile import profile_shallow
+
+# ASCII flag is essential: without it, ``\W`` in Python 3 excludes Unicode
+# letters/digits from the "unsafe" set, which would leave non-ASCII chars
+# in Mermaid node ids. ``re.ASCII`` collapses ``\W`` to ``[^A-Za-z0-9_]``.
+_SAFE_RE = re.compile(r"\W", re.ASCII)
+
+
+def _discover_repos(
+    roots: list[Path],
+    additional_markers: list[str] | None,
+    skip_dirs: list[str] | None,
+) -> dict[str, Path]:
+    """Union-discover every repo under *roots*, mapped by resolved name."""
+    name_to_path: dict[str, Path] = {}
+    for root in roots:
+        if not root.is_dir():
+            continue
+        for repo in find_repos(
+            root,
+            additional_markers=additional_markers,
+            skip_dirs=skip_dirs,
+        ):
+            name_to_path.setdefault(resolve_name(repo), repo)
+    return name_to_path
+
+
+def _profile_or_walk_error(
+    name: str,
+    path: Path,
+    *,
+    strict: bool,
+    walk_errors: list[dict[str, str]],
+) -> dict[str, Any]:
+    """Return ``profile_shallow(path)`` or inline the error and return ``{}``.
+
+    Re-raises when ``strict`` is True.
+    """
+    try:
+        return profile_shallow(path)
+    except SeerError as err:
+        if strict:
+            raise
+        walk_errors.append(
+            {
+                "node": f"{name} ({path})",
+                "reason": err.reason or err.message,
+                "remediation": err.remediation,
+            }
+        )
+        return {}
+
+
+def _collect_nodes_and_edges(
+    name_to_path: dict[str, Path],
+    strict: bool,
+) -> tuple[list[dict[str, Any]], list[dict[str, str]], set[str], list[dict[str, str]]]:
+    """Build the (nodes, edges, externals, walk_errors) tuple for the workspace."""
+    nodes: list[dict[str, Any]] = []
+    edges: list[dict[str, str]] = []
+    external_seen: set[str] = set()
+    walk_errors: list[dict[str, str]] = []
+
+    for name, path in sorted(name_to_path.items()):
+        profile = _profile_or_walk_error(name, path, strict=strict, walk_errors=walk_errors)
+        nodes.append(
+            {
+                "id": name,
+                "path": str(path),
+                "external": False,
+                "version": profile.get("version", ""),
+            }
+        )
+        for edge in _edges_from_profile(name, profile):
+            edges.append(edge)
+            target = edge["to"]
+            if target not in name_to_path and target not in external_seen:
+                external_seen.add(target)
+    return nodes, edges, external_seen, walk_errors
+
+
+def build_graph(
+    roots: list[Path],
+    *,
+    additional_markers: list[str] | None = None,
+    skip_dirs: list[str] | None = None,
+    strict: bool = False,
+) -> dict[str, Any]:
+    """Build a workspace graph over the given roots.
+
+    Per-node profiling errors are collected in ``walk_errors``; the build
+    continues unless ``strict=True``.
+
+    Parameters
+    ----------
+    roots:
+        One or more workspace root directories.  Each is scanned with
+        :func:`seer.repo.detect.find_repos`; results are unioned.
+    additional_markers:
+        Extra filenames treated as repo markers during discovery.
+    skip_dirs:
+        Directory names skipped during discovery.
+    strict:
+        When ``True``, re-raise the first per-node :class:`SeerError`
+        instead of inlining it into ``walk_errors``.
+
+    Returns
+    -------
+    dict with keys:
+        ``roots``, ``nodes``, ``edges``, ``walk_errors``, ``mermaid``.
+    """
+    name_to_path = _discover_repos(roots, additional_markers, skip_dirs)
+    nodes, edges, external_seen, walk_errors = _collect_nodes_and_edges(name_to_path, strict)
+    for ext in sorted(external_seen):
+        nodes.append({"id": ext, "path": None, "external": True})
+
+    return {
+        "roots": [str(r) for r in roots],
+        "nodes": nodes,
+        "edges": edges,
+        "walk_errors": walk_errors,
+        "mermaid": _render_mermaid(nodes, edges),
+    }
+
+
+def _render_mermaid(
+    _nodes: list[dict[str, Any]],
+    edges: list[dict[str, str]],
+) -> str:
+    """Return a Mermaid ``graph TD`` source for the workspace."""
+    lines = ["graph TD"]
+    for edge in edges:
+        spec = edge.get("spec") or ""
+        edge_type = edge.get("type") or ""
+        if edge_type:
+            label = f"|{edge_type}{(' ' + spec) if spec else ''}|"
+        else:
+            label = ""
+        lines.append(f"  {_safe(edge['from'])} -->{label} {_safe(edge['to'])}")
+    return "\n".join(lines) + "\n"
+
+
+def _safe(name: str) -> str:
+    """Return a Mermaid-safe node id for ``name``.
+
+    Mermaid identifiers must match ``[A-Za-z_][A-Za-z0-9_]*``. This
+    helper:
+
+    * Replaces every character outside ``[A-Za-z0-9_]`` with ``_``.
+    * Prepends ``n_`` when the sanitised value is empty or starts with
+      a digit (Mermaid forbids digit-leading identifiers).
+    * Appends a short stable hash of the original string whenever
+      sanitisation actually changed the value, so two distinct inputs
+      that would otherwise collapse to the same id (e.g. ``a-b`` and
+      ``a_b``, or ``foo bar`` and ``foo/bar``) stay distinct in the
+      generated diagram.
+    """
+    if not name:
+        return "n_"
+    sanitised = _SAFE_RE.sub("_", name)
+    if sanitised != name:
+        digest = hashlib.sha256(name.encode("utf-8")).hexdigest()[:6]
+        sanitised = f"{sanitised}_{digest}"
+    if sanitised[0].isdigit():
+        sanitised = "n_" + sanitised
+    return sanitised

seer/repo/manifest.py

@@ -0,0 +1,36 @@
+"""pyproject.toml reader with structured-error mapping."""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+from seer.repo.errors import malformed_pyproject, manifest_not_found
+
+
+def read_pyproject(repo: Path) -> dict[str, object]:
+    """Parse ``repo/pyproject.toml`` into a stable dict.
+
+    Returns a dict with keys ``name``, ``version``, ``entry_points``,
+    ``deps_runtime``, ``deps_dev``. Raises :class:`SeerError` (user_error)
+    when the file is missing, or (env_error) when it cannot be parsed.
+    """
+    pyproject = repo / "pyproject.toml"
+    if not pyproject.exists():
+        raise manifest_not_found(repo)
+    try:
+        data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+    except tomllib.TOMLDecodeError as e:
+        raise malformed_pyproject(pyproject, str(e)) from e
+
+    project = data.get("project", {}) or {}
+    scripts = project.get("scripts", {}) or {}
+    dep_groups = data.get("dependency-groups", {}) or {}
+
+    return {
+        "name": project.get("name") or repo.name,
+        "version": project.get("version", ""),
+        "entry_points": dict(scripts),
+        "deps_runtime": list(project.get("dependencies", []) or []),
+        "deps_dev": list(dep_groups.get("dev", []) or []),
+    }