frob 0.0.0__py3-none-any.whl

frob/app/config.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+import argparse
+import enum
+from pathlib import Path
+
+from pydantic import BaseModel
+
+from frob._compat import Self, toml
+
+
+class Subcommand(str, enum.Enum):
+    init = "init"
+    cycle = "cycle"
+    stub = "stub"
+    outline = "outline"
+    map = "map"
+    xref = "xref"
+    tokens = "tokens"
+    bundle = "bundle"
+    parse = "parse"
+    dup = "dup"
+    arch = "arch"
+    inspect = "inspect"
+    docs = "docs"
+    bind = "bind"
+
+
+class AppConfig(BaseModel):
+    subcommand: Subcommand | None = None
+
+    # init
+    init_command: str | None = None  # "list" or "new"
+    init_type: str | None = None
+    init_name: str | None = None
+    init_output: Path | None = None
+    init_force: bool = False
+
+    # cycle
+    cycle_path: Path | None = None
+    cycle_lang: str | None = None
+    cycle_suggest: bool = False
+
+    # stub
+    stub_file: Path | None = None
+    stub_target: str | None = None
+    stub_output: Path | None = None
+
+    # outline
+    outline_file: Path | None = None
+    outline_json: bool = False
+
+    # map
+    map_path: Path | None = None
+    map_json: bool = False
+    map_depth: int | None = None
+
+    # xref
+    xref_symbol: str | None = None
+    xref_path: Path | None = None
+    xref_lang: str | None = None
+    xref_json: bool = False
+
+    # tokens
+    tokens_paths: list[Path] = []
+    tokens_detail: bool = False
+    tokens_json: bool = False
+
+    # bundle
+    bundle_file: Path | None = None
+    bundle_target: str | None = None
+    bundle_depth: int = 1
+    bundle_format: str = "markdown"
+
+    # dup
+    dup_path: Path | None = None
+    dup_min_lines: int = 6
+    dup_json: bool = False
+
+    # arch
+    arch_path: Path | None = None
+    arch_json: bool = False
+    arch_max_function_lines: int = 30
+    arch_max_class_methods: int = 12
+
+    # inspect
+    inspect_project: Path | None = None
+    inspect_pycharm: Path | None = None
+    inspect_profile: Path | None = None
+    inspect_output_dir: Path | None = None
+    inspect_scope: str | None = None
+    inspect_json: bool = False
+
+    # docs
+    docs_path: Path | None = None
+    docs_symbol: str | None = None
+    docs_overview: bool = False
+    docs_search: str | None = None
+    docs_json: bool = False
+
+    # parse
+    parse_tool: str | None = None
+    parse_input: Path | None = None
+    parse_exit_code: int = 0
+    parse_json: bool = False
+    parse_verbose: bool = False
+    parse_passthrough: bool = False
+
+    @classmethod
+    def from_external(cls, args: argparse.Namespace, file: Path) -> Self:
+        file_cfg: dict = {}
+        if file.exists():
+            with file.open("rb") as f:
+                data = toml.load(f)
+            file_cfg = data.get("tool", {}).get("frob", {})
+
+        d: dict = {**file_cfg}
+
+        sub = getattr(args, "subcommand", None)
+        if sub is not None:
+            d["subcommand"] = Subcommand(sub)
+
+        for field in (
+            "init_command",
+            "init_type",
+            "init_name",
+            "cycle_lang",
+            "stub_target",
+            "xref_symbol",
+            "xref_lang",
+            "bundle_target",
+            "bundle_format",
+            "parse_tool",
+            "inspect_scope",
+            "docs_symbol",
+            "docs_search",
+        ):
+            val = getattr(args, field, None)
+            if val is not None:
+                d[field] = val
+
+        for path_field in (
+            "init_output",
+            "cycle_path",
+            "stub_file",
+            "stub_output",
+            "outline_file",
+            "map_path",
+            "xref_path",
+            "bundle_file",
+            "parse_input",
+            "dup_path",
+            "arch_path",
+            "docs_path",
+            "inspect_project",
+            "inspect_pycharm",
+            "inspect_profile",
+            "inspect_output_dir",
+        ):
+            val = getattr(args, path_field, None)
+            if val is not None:
+                d[path_field] = Path(val)
+
+        # Multi-path field
+        token_paths = getattr(args, "tokens_paths", None)
+        if token_paths:
+            d["tokens_paths"] = [Path(p) for p in token_paths]
+
+        # Int fields
+        for int_field in (
+            "map_depth",
+            "bundle_depth",
+            "dup_min_lines",
+            "arch_max_function_lines",
+            "arch_max_class_methods",
+        ):
+            val = getattr(args, int_field, None)
+            if val is not None:
+                d[int_field] = val
+
+        # Int fields
+        parse_ec = getattr(args, "parse_exit_code", None)
+        if parse_ec is not None:
+            d["parse_exit_code"] = int(parse_ec)
+
+        # Bool flags: only override when explicitly True
+        for flag in (
+            "init_force",
+            "cycle_suggest",
+            "outline_json",
+            "map_json",
+            "xref_json",
+            "tokens_detail",
+            "tokens_json",
+            "parse_json",
+            "parse_verbose",
+            "parse_passthrough",
+            "dup_json",
+            "arch_json",
+            "inspect_json",
+            "docs_json",
+            "docs_overview",
+        ):
+            if getattr(args, flag, False):
+                d[flag] = True
+
+        return cls(**d)
+
+    @classmethod
+    def from_args(cls, args: argparse.Namespace) -> Self:
+        return cls.from_external(args, Path("pyproject.toml"))

frob/app/cycle_runner.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from frob.app.config import AppConfig
+from frob.ast.common import ModuleTag
+from frob.cycle.graph import DependencyGraph, find_cycles
+from frob.logging import get_logger
+
+_log = get_logger(__name__)
+
+
+def run(cfg: AppConfig) -> None:
+    if cfg.cycle_path is None:
+        _log.error("frob cycle requires <path>")
+        sys.exit(1)
+
+    graph, errors = _build_graph(cfg.cycle_path, cfg.cycle_lang)
+
+    for err in errors:
+        _log.warning(err)
+
+    cycles = find_cycles(graph)
+    if not cycles:
+        _log.info("no cycles found")
+        return
+
+    for cycle in cycles:
+        nodes = " -> ".join(cycle + [cycle[0]])
+        _log.info("cycle (%d nodes): %s", len(cycle), nodes)
+        if cfg.cycle_suggest:
+            _log.info("  suggestion: extract shared symbols into a new module")
+
+
+def _build_graph(root: Path, lang: str | None) -> tuple[DependencyGraph, list[str]]:
+    from frob.ast import cpp as _cpp
+    from frob.ast import python as _py
+
+    graph = DependencyGraph()
+    errors: list[str] = []
+
+    files = [root] if root.is_file() else list(root.rglob("*"))
+    scan_root = root.parent if root.is_file() else root
+
+    for path in files:
+        if not path.is_file():
+            continue
+        ext = path.suffix.lower()
+        try:
+            rel = str(path.relative_to(scan_root))
+        except ValueError:
+            continue
+
+        graph.add_node(rel)
+
+        try:
+            if ext == ".py" and lang in (None, "python"):
+                for imp in _py.get_imports(ModuleTag(rel), scan_root):
+                    graph.add_edge(rel, imp)
+            elif ext in _cpp.ALL_EXTS and lang in (None, "cpp", "c"):
+                for imp in _cpp.get_imports(ModuleTag(rel), scan_root):
+                    graph.add_edge(rel, imp)
+        except Exception as exc:
+            errors.append(f"parse error in {rel}: {exc}")
+
+    return graph, errors

frob/app/docs_runner.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+from frob.app.config import AppConfig
+from frob.docs import extract_docstrings, find_docs_dir, overview, search
+from frob.logging import get_logger
+
+_log = get_logger(__name__)
+
+
+def run(cfg: AppConfig) -> None:
+    path = cfg.docs_path
+    if path is None:
+        _log.error("frob docs requires <path>")
+        sys.exit(1)
+    if not path.exists():
+        _log.error(f"error: {path} does not exist")
+        sys.exit(1)
+
+    if cfg.docs_search:
+        docs_dir = find_docs_dir(path)
+        if not docs_dir:
+            _log.error("error: no docs/ directory found")
+            sys.exit(1)
+        matches = search(cfg.docs_search, docs_dir)
+        if cfg.docs_json:
+            import json
+
+            _log.info(json.dumps([m.model_dump() for m in matches], indent=2))
+        else:
+            if not matches:
+                _log.info("no matches found")
+            for m in matches:
+                _log.info(f"{m.file}:{m.line}  [{m.heading}]")
+                _log.info(f"  {m.excerpt}")
+        return
+
+    if cfg.docs_overview:
+        docs_dir = find_docs_dir(path)
+        if not docs_dir:
+            _log.info("no docs/ directory found")
+            return
+        entries = overview(path, cfg.docs_symbol)
+        if cfg.docs_json:
+            import json
+
+            _log.info(json.dumps([e.model_dump() for e in entries], indent=2))
+        else:
+            for e in entries:
+                _log.info(f"## {e.heading}  ({e.file}:{e.line})")
+                if e.summary:
+                    _log.info(f"   {e.summary}")
+        return
+
+    if path.is_dir():
+        results = []
+        for root, _, files in os.walk(path):
+            for f in files:
+                if f.endswith(".py"):
+                    results.extend(extract_docstrings(Path(root) / f, cfg.docs_symbol))
+    else:
+        results = extract_docstrings(path, cfg.docs_symbol)
+
+    if cfg.docs_json:
+        import json
+
+        _log.info(json.dumps([d.model_dump() for d in results], indent=2))
+    else:
+        if not results:
+            _log.info("no docstrings found")
+            return
+        for d in results:
+            _log.info(f"[L{d.line}] {d.symbol} ({d.kind})")
+            for line in d.text.splitlines():
+                _log.info(f"  {line}")
+            _log.info("")

frob/app/dup_runner.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from frob.app.config import AppConfig
+from frob.dup import find_duplicates
+from frob.logging import get_logger
+
+_log = get_logger(__name__)
+
+# AppConfig fields used by this runner (add to AppConfig when wiring CLI):
+#   dup_path: Path | None      -- directory to scan (required)
+#   dup_min_lines: int         -- minimum function body size (default 6)
+#   dup_json: bool             -- emit JSON instead of human-readable text
+
+
+def run(cfg: AppConfig) -> None:
+    dup_path: Path | None = getattr(cfg, "dup_path", None)
+    if dup_path is None:
+        _log.error("frob dup requires <path>")
+        sys.exit(1)
+
+    if not dup_path.exists():
+        _log.error("path does not exist: %s", dup_path)
+        sys.exit(1)
+
+    min_lines: int = getattr(cfg, "dup_min_lines", 6) or 6
+    dup_json: bool = getattr(cfg, "dup_json", False)
+
+    result = find_duplicates(dup_path, min_lines=min_lines)
+
+    if dup_json:
+        _log.info("%s", result.as_json())
+    else:
+        _log.info("%s", result.as_text())

frob/app/init_runner.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from frob.app.config import AppConfig
+from frob.init.project import list_project_types, render_project
+from frob.logging import get_logger
+
+_log = get_logger(__name__)
+
+
+def run(cfg: AppConfig) -> None:
+    if cfg.init_command == "list" or cfg.init_command is None:
+        for t in list_project_types():
+            _log.info(t)
+        return
+
+    if cfg.init_type is None or cfg.init_name is None:
+        _log.error("frob init new requires <type> and <name>")
+        sys.exit(1)
+
+    out_dir = cfg.init_output or Path(".")
+    result = render_project(cfg.init_type, cfg.init_name, out_dir, force=cfg.init_force)
+
+    if result.is_err:
+        _log.error(result.danger_err.value)
+        sys.exit(1)
+
+    for p in result.danger_ok:
+        _log.info("created %s", p)

frob/app/inspect_runner.py

@@ -0,0 +1,85 @@
+"""
+frob inspect -- run PyCharm headless inspection and display results.
+
+Usage:
+    frob inspect [--pycharm PATH] [--profile PATH] [--output-dir DIR] [--scope DIR]
+                 <project_dir>
+"""
+
+from __future__ import annotations
+
+import sys
+import tempfile
+from pathlib import Path
+
+from frob.app.config import AppConfig
+from frob.logging import get_logger
+
+_log = get_logger(__name__)
+
+
+def run(cfg: AppConfig) -> None:
+    from frob.inspect import find_pycharm, run_inspection
+    from frob.process.parsers import parse_pycharm_dir
+
+    project = cfg.inspect_project
+    if project is None:
+        _log.error("frob inspect requires <project_dir>")
+        sys.exit(1)
+
+    if not project.exists():
+        _log.error("project directory does not exist: %s", project)
+        sys.exit(1)
+
+    # Resolve PyCharm binary
+    pycharm = cfg.inspect_pycharm
+    if pycharm is None:
+        pycharm = find_pycharm()
+    if pycharm is None:
+        _log.error(
+            "cannot find PyCharm inspect.bat -- use --pycharm PATH to specify it"
+        )
+        sys.exit(1)
+
+    # Resolve profile
+    profile = cfg.inspect_profile
+    if profile is None:
+        _log.error("--profile PATH is required (path to inspection profile XML)")
+        sys.exit(1)
+
+    if not profile.exists():
+        _log.error("profile file does not exist: %s", profile)
+        sys.exit(1)
+
+    # Resolve output directory
+    _tmp_dir = None
+    if cfg.inspect_output_dir is not None:
+        output_dir = cfg.inspect_output_dir
+    else:
+        _tmp_dir = tempfile.mkdtemp(prefix="frob_pycharm_")
+        output_dir = Path(_tmp_dir)
+
+    _log.info("output dir: %s", output_dir)
+
+    success, err = run_inspection(
+        pycharm,
+        project,
+        profile,
+        output_dir,
+        scope=cfg.inspect_scope,
+    )
+
+    if not success:
+        assert err is not None
+        _log.error("inspection failed: %s", err)
+        sys.exit(1)
+
+    result = parse_pycharm_dir(output_dir, project_root=project)
+
+    if cfg.inspect_json:
+        _log.info(result.as_json())
+    else:
+        _log.info(result.as_text())
+
+    if result.error_count:
+        sys.exit(1)

frob/app/map_runner.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from frob.app.config import AppConfig
+from frob.logging import get_logger
+from frob.map import map_project
+
+_log = get_logger(__name__)
+
+
+def run(cfg: AppConfig) -> None:
+    root = cfg.map_path or Path(".")
+    result = map_project(root, depth=cfg.map_depth)
+    if cfg.map_json:
+        _log.info(result.as_json())
+    else:
+        _log.info(result.as_text())

frob/app/outline_runner.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import sys
+
+from frob.app.config import AppConfig
+from frob.logging import get_logger
+from frob.outline import outline_file
+
+_log = get_logger(__name__)
+
+
+def run(cfg: AppConfig) -> None:
+    if cfg.outline_file is None:
+        _log.error("frob outline requires <file>")
+        sys.exit(1)
+
+    result = outline_file(cfg.outline_file)
+    if result.is_err:
+        _log.error(result.danger_err.value)
+        sys.exit(1)
+
+    ol = result.danger_ok
+    if cfg.outline_json:
+        _log.info(ol.as_json())
+    else:
+        _log.info(ol.as_text())

frob/app/parse_runner.py

@@ -0,0 +1,84 @@
+"""
+frob parse -- read tool output from stdin or a file and emit a compact summary.
+
+Usage:
+    pytest ... 2>&1 | frob parse pytest
+    frob parse ruff < ruff_output.txt
+    frob parse ty --json < ty_output.txt
+    frob parse clang --exit-code 1 < build.log
+    frob parse junit < test_results.xml
+"""
+
+from __future__ import annotations
+
+import sys
+
+from frob.app.config import AppConfig
+from frob.logging import get_logger
+from frob.process.parsers import (
+    parse_clang,
+    parse_junit_xml,
+    parse_pycharm_dir,
+    parse_pytest,
+    parse_ruff,
+    parse_ty,
+)
+
+_log = get_logger(__name__)
+
+_PARSERS = {
+    "pytest": lambda text, rc: parse_pytest(text, exit_code=rc),
+    "ruff": lambda text, rc: parse_ruff(text, exit_code=rc),
+    "ty": lambda text, rc: parse_ty(text, exit_code=rc),
+    "clang": lambda text, rc: parse_clang(text, exit_code=rc, tool="clang"),
+    "clang++": lambda text, rc: parse_clang(text, exit_code=rc, tool="clang++"),
+    "gcc": lambda text, rc: parse_clang(text, exit_code=rc, tool="gcc"),
+    "g++": lambda text, rc: parse_clang(text, exit_code=rc, tool="g++"),
+    "junit": lambda text, rc: parse_junit_xml(text, tool="junit"),
+    "gtest": lambda text, rc: parse_junit_xml(text, tool="gtest"),
+    "catch2": lambda text, rc: parse_junit_xml(text, tool="catch2"),
+}
+
+
+def run(cfg: AppConfig) -> None:
+    tool = cfg.parse_tool
+    if tool is None:
+        _log.error("frob parse requires <tool>")
+        sys.exit(1)
+
+    _ALL_TOOLS = set(_PARSERS) | {"pycharm"}
+    if tool not in _ALL_TOOLS:
+        known = ", ".join(sorted(_ALL_TOOLS))
+        _log.error("unknown tool %r -- known: %s", tool, known)
+        sys.exit(1)
+
+    # pycharm takes a directory, not stdin
+    if tool == "pycharm":
+        if cfg.parse_input is None:
+            _log.error("frob parse pycharm requires a directory argument")
+            sys.exit(1)
+        d = cfg.parse_input
+        if not d.is_dir():
+            _log.error("frob parse pycharm: %s is not a directory", d)
+            sys.exit(1)
+        result = parse_pycharm_dir(d)
+    else:
+        # Read from file or stdin
+        if cfg.parse_input is not None:
+            try:
+                text = cfg.parse_input.read_text()
+            except OSError as exc:
+                _log.error("cannot read %s: %s", cfg.parse_input, exc)
+                sys.exit(1)
+        else:
+            text = sys.stdin.read()
+        result = _PARSERS[tool](text, cfg.parse_exit_code)
+
+    if cfg.parse_json:
+        _log.info(result.as_json())
+    else:
+        _log.info(result.as_text(verbose=cfg.parse_verbose))
+
+    # Propagate the tool's exit code so pipelines work correctly
+    if cfg.parse_passthrough and not result.passed:
+        sys.exit(result.exit_code or 1)

frob/app/stub_runner.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import sys
+
+from frob.app.config import AppConfig
+from frob.logging import get_logger
+from frob.stub import stub_file
+
+_log = get_logger(__name__)
+
+
+def run(cfg: AppConfig) -> None:
+    if cfg.stub_file is None or cfg.stub_target is None:
+        _log.error("frob stub requires <file> and <target>")
+        sys.exit(1)
+
+    result = stub_file(cfg.stub_file, cfg.stub_target)
+
+    if result.is_err:
+        _log.error(result.danger_err.value)
+        sys.exit(1)
+
+    out = result.danger_ok
+    if cfg.stub_output:
+        cfg.stub_output.write_text(out)
+        _log.info("wrote %s", cfg.stub_output)
+    else:
+        _log.info(out)

frob/app/tokens_runner.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from frob.app.config import AppConfig
+from frob.logging import get_logger
+from frob.tokens import count_paths
+
+_log = get_logger(__name__)
+
+
+def run(cfg: AppConfig) -> None:
+    paths = cfg.tokens_paths or [Path(".")]
+    result = count_paths(paths, detail=cfg.tokens_detail)
+    if cfg.tokens_json:
+        _log.info(result.as_json())
+    else:
+        _log.info(result.as_text(detail=cfg.tokens_detail))