srcly 0.1.27__tar.gz → 0.1.30__tar.gz

{srcly-0.1.27 → srcly-0.1.30}/.gitignore

@@ -5,6 +5,7 @@ node_modules/
 
 # Data files
 codebase_mri.json
+.srcly*/
 
 # Python
 __pycache__/
@@ -66,4 +67,4 @@ venv.bak/
 .python-version
 # uv.lock is intentionally not ignored as this is an application
 
-.tmp
+.tmp

{srcly-0.1.27 → srcly-0.1.30}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: srcly
-Version: 0.1.27
+Version: 0.1.30
 Summary: Interactive codebase treemap and metrics viewer.
 Requires-Python: >=3.13
 Requires-Dist: fastapi>=0.121.3

{srcly-0.1.27 → srcly-0.1.30}/app/models.py

@@ -99,3 +99,34 @@ class OverlayToken(BaseModel):
 
 class FocusOverlayResponse(BaseModel):
     tokens: List[OverlayToken] = Field(default_factory=list)
+
+
+# --- Scope Graph Models ---
+
+class ScopeGraphRequest(BaseModel):
+    path: str
+    focusStartLine: int
+    focusEndLine: int
+
+class SymbolNode(BaseModel):
+    id: str  # e.g. "var:expanded:L12:C5" or just a unique ID
+    name: str
+    kind: str  # "var", "func", "param", "class", "jsx_comp", etc.
+    declLine: int
+    isCaptured: bool = False
+    isDeclaredHere: bool = False
+
+class ScopeNode(BaseModel):
+    id: str
+    kind: str  # "function", "jsx", "block", "root"
+    name: str | None = None
+    startLine: int
+    endLine: int
+    children: List["ScopeNode"] = Field(default_factory=list)
+    declared: List[SymbolNode] = Field(default_factory=list)
+    captured: List[SymbolNode] = Field(default_factory=list)
+
+class ScopeGraph(BaseModel):
+    root: ScopeNode
+    # We might want edges later, but for MVP, nested scopes + lists are enough.
+

{srcly-0.1.27 → srcly-0.1.30}/app/routers/analysis.py

@@ -8,7 +8,7 @@ from app.models import Node, DependencyGraph, DependencyNode, DependencyEdge
 from app.services import analysis, cache
 from app.services.typescript import typescript_analysis
 from app.config import IGNORE_DIRS
-from app.models import FocusOverlayRequest, FocusOverlayResponse
+from app.models import FocusOverlayRequest, FocusOverlayResponse, ScopeGraphRequest, ScopeGraph
 
 router = APIRouter(prefix="/api/analysis", tags=["analysis"])
 
@@ -648,3 +648,27 @@ async def get_focus_overlay(req: FocusOverlayRequest):
     except Exception as e:
         print(f"Error computing focus overlay for {req.path}: {e}")
         raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/focus/scope-graph", response_model=ScopeGraph)
+async def get_scope_graph(req: ScopeGraphRequest):
+    """
+    Return the nested scope graph for a focused region.
+    """
+    target_path = Path(req.path)
+    if not target_path.exists() or not target_path.is_file():
+        raise HTTPException(status_code=404, detail="File not found")
+
+    from app.services.focus_overlay import compute_scope_graph
+
+    try:
+        return compute_scope_graph(
+            file_path=str(target_path),
+            focus_start_line=req.focusStartLine,
+            focus_end_line=req.focusEndLine,
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        print(f"Error computing scope graph for {req.path}: {e}")
+        raise HTTPException(status_code=500, detail=str(e))

srcly-0.1.30/app/run.py

@@ -0,0 +1,361 @@
+import argparse
+import os
+import socket
+import sys
+import threading
+import time
+import webbrowser
+from pathlib import Path
+
+import uvicorn
+
+from app.services import reporting
+
+
+def _open_browser_later(url: str, delay: float = 1.0) -> None:
+    """
+    Open the default web browser after a short delay.
+
+    This lets the server start first so the page is reachable.
+    """
+
+    def _worker() -> None:
+        time.sleep(delay)
+        try:
+            webbrowser.open(url)
+        except Exception:
+            # Don't crash the CLI if opening the browser fails (e.g. headless env)
+            pass
+
+    thread = threading.Thread(target=_worker, daemon=True)
+    thread.start()
+
+
+def _find_repo_root(start_path: str) -> str:
+    """
+    Walk upwards from ``start_path`` to find a Git repository root.
+
+    Returns the first directory that contains a `.git` directory or file.
+    If none is found, the original ``start_path`` is returned.
+    """
+    current = os.path.abspath(start_path)
+
+    while True:
+        git_path = os.path.join(current, ".git")
+        if os.path.exists(git_path):
+            return current
+
+        parent = os.path.dirname(current)
+        if parent == current:
+            # Reached filesystem root; fall back to the original start path.
+            return os.path.abspath(start_path)
+
+        current = parent
+
+
+def main(argv: list[str] | None = None) -> None:
+    """
+    Entry point for the CLI.
+
+    - With no path argument, uses the enclosing Git repo root as the codebase root.
+    - If a path is provided (including "."), uses that as the codebase root.
+    - Starts the FastAPI server.
+    - Opens the default browser to the app URL.
+    """
+    argv = list(argv) if argv is not None else sys.argv[1:]
+    if argv and argv[0] in {"scan", "report", "hotspots", "explain"}:
+        _run_headless(argv)
+        return
+
+    parser = argparse.ArgumentParser(
+        prog="srcly",
+        description=(
+            "Interactive codebase treemap and metrics viewer. "
+            "By default, analyzes the enclosing Git repository root."
+        ),
+    )
+    parser.add_argument(
+        "path",
+        nargs="?",
+        help=(
+            "Path to the codebase to analyze. "
+            "If omitted, the enclosing Git repo root is used. "
+            'Use "." explicitly to analyze the current directory.'
+        ),
+    )
+    parser.add_argument(
+        "--host",
+        default="127.0.0.1",
+        help="Host interface to bind the server to (default: 127.0.0.1).",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=None,
+        help="Port to run the server on (default: random free port).",
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.path is None:
+        target_path = _find_repo_root(os.getcwd())
+    else:
+        target_path = os.path.abspath(args.path)
+
+    if not os.path.exists(target_path):
+        raise SystemExit(f"Path does not exist: {target_path}")
+
+    # Change working directory so the API defaults to this path.
+    os.chdir(target_path)
+    print(f"📂 Analyzing codebase at: {target_path}")
+
+    port = args.port
+    if port is None:
+        # Find a random free port
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.bind(("", 0))
+            port = s.getsockname()[1]
+
+    url = f"http://{args.host}:{port}"
+    print(f"🚀 Starting server at {url}")
+    print("   Press Ctrl+C to stop.")
+
+    _open_browser_later(url)
+
+    uvicorn.run(
+        "app.main:app",
+        host=args.host,
+        port=port,
+        reload=False,
+    )
+
+
+def _resolve_target_path(path: str | None) -> Path:
+    if path is None:
+        target_path = Path(_find_repo_root(os.getcwd()))
+    else:
+        target_path = Path(path).resolve()
+
+    if not target_path.exists():
+        raise SystemExit(f"Path does not exist: {target_path}")
+    return target_path
+
+
+def _run_headless(argv: list[str]) -> None:
+    parser = argparse.ArgumentParser(
+        prog="srcly",
+        description="Headless Srcly analysis commands for agents and CI.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    scan_parser = subparsers.add_parser("scan", help="Write the raw analysis tree as JSON.")
+    scan_parser.add_argument("path", nargs="?", help="Path to analyze. Defaults to the enclosing Git repo root.")
+    scan_parser.add_argument("--out", default="codebase_mri.json", help="Output JSON file.")
+    scan_parser.add_argument("--refresh", action="store_true", help="Ignore cache when cache support is available.")
+    scan_parser.add_argument("--format", choices=["json", "jsonl"], default="json", help="Output format. JSONL is reserved.")
+    scan_parser.add_argument(
+        "--include-source",
+        choices=["false", "snippets", "none"],
+        default="none",
+        help="Reserved source inclusion mode. Full source is not emitted.",
+    )
+
+    report_parser = subparsers.add_parser("report", help="Write agent-ready report artifacts.")
+    report_parser.add_argument("path", nargs="?", help="Path to analyze. Defaults to the enclosing Git repo root.")
+    report_parser.add_argument("--out", default=".srcly", help="Output artifact directory.")
+    report_parser.add_argument(
+        "--stdout",
+        action="store_true",
+        help="Emit one compact bundled JSON report to stdout instead of writing artifact files.",
+    )
+    report_parser.add_argument("--refresh", action="store_true", help="Ignore cache when cache support is available.")
+    report_parser.add_argument("--limit", type=int, default=50, help="Maximum ranked findings to emit.")
+    report_parser.add_argument(
+        "--profile",
+        choices=["general", "frontend", "backend", "typescript", "python", "docs"],
+        default="general",
+        help="Scoring profile.",
+    )
+    report_parser.add_argument(
+        "--format",
+        choices=["markdown", "json", "both"],
+        default="both",
+        help="Artifact formats to write.",
+    )
+    report_parser.add_argument(
+        "--fail-on",
+        choices=["high", "medium", "none"],
+        default="none",
+        help="Exit non-zero if findings at this priority or higher are present.",
+    )
+    report_parser.add_argument("--tree-depth", type=int, default=3, help="Maximum depth in tree.summary.json.")
+    report_parser.add_argument("--tree-top", type=int, default=6, help="Maximum children per tree level.")
+    report_parser.add_argument("--include-tree", action="store_true", help="Also write/include the full raw tree.json artifact.")
+    report_parser.add_argument(
+        "--include-dependencies",
+        action="store_true",
+        help="Also write/include the TS/TSX dependency graph artifact.",
+    )
+
+    hotspots_parser = subparsers.add_parser("hotspots", help="Print ranked hotspots.")
+    hotspots_parser.add_argument("path", nargs="?", help="Path to analyze. Defaults to the enclosing Git repo root.")
+    hotspots_parser.add_argument("--metric", action="append", default=None, help="Metric to score. May be repeated.")
+    hotspots_parser.add_argument("--limit", type=int, default=25, help="Maximum hotspots to print.")
+    hotspots_parser.add_argument("--format", choices=["markdown", "json"], default="markdown", help="Output format.")
+
+    explain_parser = subparsers.add_parser("explain", help="Print a focused report for one file or subtree.")
+    explain_parser.add_argument("path", nargs="?", help="Path to analyze. Defaults to the enclosing Git repo root.")
+    explain_parser.add_argument("--file", required=True, help="File path to explain.")
+    explain_parser.add_argument("--format", choices=["markdown", "json"], default="markdown", help="Output format.")
+
+    args = parser.parse_args(argv)
+
+    if args.command == "scan":
+        if args.format != "json":
+            raise SystemExit("--format jsonl is reserved and not implemented yet.")
+        if args.include_source not in {"none", "false"}:
+            raise SystemExit("--include-source snippets is reserved and not implemented yet.")
+        target_path = _resolve_target_path(args.path)
+        out_path = Path("-") if args.out == "-" else Path(args.out).resolve()
+        reporting.write_scan(target_path, out_path, refresh=args.refresh)
+        if str(args.out) != "-":
+            print(f"Wrote Srcly tree JSON to {out_path}")
+        return
+
+    if args.command == "report":
+        target_path = _resolve_target_path(args.path)
+        if args.stdout:
+            payload = reporting.build_report_payload(
+                target_path,
+                profile=args.profile,
+                limit=args.limit,
+                refresh=args.refresh,
+                tree_depth=args.tree_depth,
+                tree_top=args.tree_top,
+                include_tree=args.include_tree,
+                include_dependencies=args.include_dependencies,
+            )
+            print(reporting._json_dumps(payload))
+        else:
+            out_dir = Path(args.out).resolve()
+            output_format = "both" if args.fail_on != "none" and args.format == "markdown" else args.format
+            written = reporting.write_report(
+                target_path,
+                out_dir,
+                profile=args.profile,
+                limit=args.limit,
+                output_format=output_format,
+                refresh=args.refresh,
+                tree_depth=args.tree_depth,
+                tree_top=args.tree_top,
+                include_tree=args.include_tree,
+                include_dependencies=args.include_dependencies,
+            )
+            print(f"Wrote Srcly report artifacts to {out_dir}")
+            for path in written.values():
+                print(f"- {path}")
+        if args.fail_on != "none":
+            if args.stdout:
+                _enforce_fail_on_payload(payload["findings"], args.fail_on)
+            else:
+                _enforce_fail_on(out_dir / "findings.json", args.fail_on)
+        return
+
+    if args.command == "hotspots":
+        target_path = _resolve_target_path(args.path)
+        tree = reporting.scan_tree(target_path)
+        profile = _profile_from_metrics(args.metric)
+        ranked = reporting.rank_nodes(tree, profile=profile)[: args.limit]
+        if args.format == "json":
+            print(reporting._json_dumps({"rankings": ranked}))
+        else:
+            for item in ranked:
+                location = item["path"]
+                if item.get("start_line") and item.get("end_line"):
+                    location = f"{location}:{item['start_line']}-{item['end_line']}"
+                print(f"{item['rank']}. score={item['score']} {location} - {item['reason']}")
+        return
+
+    if args.command == "explain":
+        target_path = _resolve_target_path(args.path)
+        tree = reporting.scan_tree(target_path)
+        payload = _explain_file(tree, Path(args.file).resolve(), target_path)
+        if args.format == "json":
+            print(reporting._json_dumps(payload))
+        else:
+            print(_render_explain_markdown(payload))
+        return
+
+
+def _profile_from_metrics(metrics: list[str] | None) -> str:
+    if not metrics:
+        return "general"
+    weights = {metric: 1.0 for metric in metrics}
+    reporting.PROFILE_WEIGHTS["_custom"] = weights
+    return "_custom"
+
+
+def _enforce_fail_on(findings_path: Path, fail_on: str) -> None:
+    import json
+
+    data = json.loads(findings_path.read_text(encoding="utf-8"))
+    _enforce_fail_on_payload(data, fail_on)
+
+
+def _enforce_fail_on_payload(data: dict, fail_on: str) -> None:
+    priorities = {"high": 2, "medium": 1, "low": 0}
+    threshold = priorities[fail_on]
+    offenders = [
+        finding
+        for finding in data.get("findings", [])
+        if priorities.get(finding.get("priority", "low"), 0) >= threshold
+    ]
+    if offenders:
+        raise SystemExit(f"Srcly found {len(offenders)} findings at priority {fail_on} or higher.")
+
+
+def _explain_file(tree, file_path: Path, root_path: Path) -> dict:
+    target = None
+    for node in reporting.iter_nodes(tree):
+        try:
+            node_path = Path(node.path).resolve()
+        except Exception:
+            continue
+        if node_path == file_path:
+            target = node
+            break
+
+    if target is None:
+        raise SystemExit(f"File not found in analysis tree: {file_path}")
+
+    ranked = reporting.rank_nodes(target)
+    return {
+        "path": str(file_path),
+        "summary": reporting.summarize_tree(target, ranked, root_path=root_path, max_depth=3, top_children=20),
+        "hotspots": ranked[:10],
+    }
+
+
+def _render_explain_markdown(payload: dict) -> str:
+    lines = [
+        f"# Srcly Explain: {payload['path']}",
+        "",
+        "## Tree",
+        "",
+        "```text",
+        *reporting.render_tree_lines(payload["summary"]),
+        "```",
+        "",
+        "## Hotspots",
+        "",
+    ]
+    for item in payload["hotspots"]:
+        location = item["path"]
+        if item.get("start_line") and item.get("end_line"):
+            location = f"{location}:{item['start_line']}-{item['end_line']}"
+        lines.append(f"- score={item['score']} `{location}`: {item['reason']}")
+    return "\n".join(lines) + "\n"
+
+
+if __name__ == "__main__":
+    main()

{srcly-0.1.27 → srcly-0.1.30}/app/services/analysis.py

@@ -1,6 +1,7 @@
 import os
 import lizard
 import multiprocessing
+import sys
 import time
 from pathlib import Path
 
@@ -369,6 +370,7 @@ def aggregate_metrics(node: Node) -> Metrics:
     total_type_interface_count = 0
     total_export_count = 0
     total_md_data_url_count = 0
+    total_python_import_count = 0
     
     # For average function length, we need total function loc and total functions (already have total_funcs)
     # But we need to sum function locs from children.
@@ -390,11 +392,7 @@ def aggregate_metrics(node: Node) -> Metrics:
         total_type_interface_count += child_metrics.ts_type_interface_count
         total_export_count += child_metrics.ts_export_count
         total_md_data_url_count += child_metrics.md_data_url_count
-        if hasattr(child_metrics, 'python_import_count'):
-             # Metric model has it, but child_metrics is a Metrics object so it should have it
-             total_python_import_count = getattr(child_metrics, 'python_import_count', 0)
-             # Should we add a local var for this? Yes
-             pass
+        total_python_import_count += child_metrics.python_import_count
         
         
         # Reconstruct total function loc from average * count
@@ -510,7 +508,7 @@ def _run_file_analyses_with_hard_timeouts(
 
             # Log every file *before* it is processed so we can identify the
             # last-started file if analysis hangs or crashes.
-            print(f"➡️ [{next_index}/{total_count}] Starting analysis: {file_path}", flush=True)
+            print(f"➡️ [{next_index}/{total_count}] Starting analysis: {file_path}", file=sys.stderr, flush=True)
 
             recv_conn, send_conn = ctx.Pipe(duplex=False)
             proc = ctx.Process(
@@ -544,6 +542,7 @@ def _run_file_analyses_with_hard_timeouts(
                 completed_count += 1
                 print(
                     f"❌ [{completed_count}/{total_count}] Timeout analyzing {file_path} after {elapsed:.2f}s (terminated)",
+                    file=sys.stderr,
                     flush=True,
                 )
                 try:
@@ -582,11 +581,12 @@ def _run_file_analyses_with_hard_timeouts(
             if isinstance(result, dict) and "error" in result:
                 print(
                     f"❌ [{completed_count}/{total_count}] Error analyzing {file_path}: {result.get('error')}",
+                    file=sys.stderr,
                     flush=True,
                 )
             else:
                 if _should_log_file_progress(completed_count, total_count):
-                    print(f"✅ [{completed_count}/{total_count}] Analyzed {file_path}", flush=True)
+                    print(f"✅ [{completed_count}/{total_count}] Analyzed {file_path}", file=sys.stderr, flush=True)
                 results.append(result)
 
         active = still_active
@@ -599,7 +599,7 @@ def _run_file_analyses_with_hard_timeouts(
 
 
 def scan_codebase(root_path: Path) -> Node:
-    print(f"🔍 Scanning: {root_path}", flush=True)
+    print(f"🔍 Scanning: {root_path}", file=sys.stderr, flush=True)
 
     # Load .gitignore spec (repo-wide, with nested .gitignore support)
     ignore_root, gitignore_spec = _load_gitignore_spec(root_path)
@@ -614,7 +614,7 @@ def scan_codebase(root_path: Path) -> Node:
         # We must modify dirs in-place to prune traversal
         pruned_dirs: list[str] = []
         for d in dirs:
-            if d in IGNORE_DIRS:
+            if d in IGNORE_DIRS or d.startswith(".srcly"):
                 continue
             dir_path = root_dir_path / d
             if _is_gitignored(dir_path, ignore_root, gitignore_spec):
@@ -643,6 +643,7 @@ def scan_codebase(root_path: Path) -> Node:
 
     print(
         f"📂 Analyzing {len(files_to_scan)} source files... (workers={MAX_ANALYSIS_WORKERS}, timeout={PER_FILE_ANALYSIS_TIMEOUT_SECONDS}s)",
+        file=sys.stderr,
         flush=True,
     )
 
@@ -661,7 +662,7 @@ def scan_codebase(root_path: Path) -> Node:
         # ``filename`` attribute), skip it instead of crashing the whole scan.
         filename = getattr(file_info, "filename", None)
         if not filename:
-            print(f"⚠️ Skipping unexpected analysis result without filename: {file_info!r}", flush=True)
+            print(f"⚠️ Skipping unexpected analysis result without filename: {file_info!r}", file=sys.stderr, flush=True)
             continue
 
         path_obj = Path(filename)