srcly 0.1.34__tar.gz → 0.3.0__tar.gz

{srcly-0.1.34 → srcly-0.3.0}/.gitignore

@@ -68,3 +68,6 @@ venv.bak/
 # uv.lock is intentionally not ignored as this is an application
 
 .tmp
+
+# Local dependency-graph captures (may come from private repos)
+client/src/viz/deps/__fixtures__/local/

{srcly-0.1.34 → srcly-0.3.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.5
 Name: srcly
-Version: 0.1.34
+Version: 0.3.0
 Summary: Interactive codebase treemap and metrics viewer.
 Requires-Python: >=3.13
 Requires-Dist: fastapi>=0.121.3
 Requires-Dist: httpx>=0.28.1
-Requires-Dist: lizard>=1.19.0
+Requires-Dist: lizard>=1.21.7
 Requires-Dist: pathspec>=0.12.1
 Requires-Dist: pydantic>=2.12.4
 Requires-Dist: pytest>=9.0.1
@@ -14,7 +14,7 @@ Requires-Dist: tree-sitter-markdown<0.6.0,>=0.5.1
 Requires-Dist: tree-sitter-python==0.25.0
 Requires-Dist: tree-sitter-scss==1.0.0
 Requires-Dist: tree-sitter-typescript>=0.23.2
-Requires-Dist: tree-sitter>=0.25.2
+Requires-Dist: tree-sitter<0.26,>=0.25.2
 Requires-Dist: uvicorn>=0.38.0
 Description-Content-Type: text/markdown
 
@@ -25,7 +25,7 @@ A FastAPI server for static code analysis using [lizard](https://github.com/terr
 ## Features
 
 - **Static Analysis**: Scans the codebase for cyclomatic complexity and LOC (Lines of Code).
-- **Caching**: Caches analysis results to `codebase_mri.json` to avoid redundant scans.
+- **Caching**: Caches analysis results in the user cache directory (see the main README) and reuses them until files change.
 - **File Serving**: Provides an API to read raw file contents (absolute paths).
 - **API Documentation**: Auto-generated Swagger UI at `/docs`.
 
@@ -53,8 +53,8 @@ The API will be available at `http://localhost:8000`.
 
 ### Analysis
 
-- `GET /api/analysis`: Get the analysis tree. Scans if no cache exists.
-- `POST /api/analysis/refresh`: Force a new scan.
+- `GET /api/analysis`: Get the analysis tree. Scans unless an unchanged cached analysis exists.
+- `POST /api/analysis/refresh`: Force a new scan and replace the cached analysis.
 
 ### Files
 

{srcly-0.1.34 → srcly-0.3.0}/README.md

@@ -5,7 +5,7 @@ A FastAPI server for static code analysis using [lizard](https://github.com/terr
 ## Features
 
 - **Static Analysis**: Scans the codebase for cyclomatic complexity and LOC (Lines of Code).
-- **Caching**: Caches analysis results to `codebase_mri.json` to avoid redundant scans.
+- **Caching**: Caches analysis results in the user cache directory (see the main README) and reuses them until files change.
 - **File Serving**: Provides an API to read raw file contents (absolute paths).
 - **API Documentation**: Auto-generated Swagger UI at `/docs`.
 
@@ -33,8 +33,8 @@ The API will be available at `http://localhost:8000`.
 
 ### Analysis
 
-- `GET /api/analysis`: Get the analysis tree. Scans if no cache exists.
-- `POST /api/analysis/refresh`: Force a new scan.
+- `GET /api/analysis`: Get the analysis tree. Scans unless an unchanged cached analysis exists.
+- `POST /api/analysis/refresh`: Force a new scan and replace the cached analysis.
 
 ### Files
 

srcly-0.3.0/app/config.py

@@ -0,0 +1,139 @@
+from typing import Set
+
+IGNORE_DIRS: Set[str] = {
+    ".git",
+    "node_modules",
+    "venv",
+    ".venv",
+    "__pycache__",
+    "dist",
+    "build",
+    ".next",
+    "coverage",
+    ".idea",
+    ".vscode",
+    "target",
+    "out",
+    "android",
+    "ios",
+}
+
+IGNORE_FILES: Set[str] = {
+    # In git worktrees and submodules `.git` is a pointer file, not a directory.
+    ".git",
+    ".DS_Store",
+    "package-lock.json",
+    "yarn.lock",
+    "pnpm-lock.yaml",
+    "cargo.lock",
+    "poetry.lock",
+    "Gemfile.lock",
+    "composer.lock",
+    "mix.lock",
+}
+
+IGNORE_EXTENSIONS: Set[str] = {
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".svg",
+    ".ico",
+    ".pdf",
+    ".zip",
+    ".tar",
+    ".gz",
+    ".map",
+    ".min.js",
+    ".min.css",
+    ".json",
+    ".xml",
+    ".txt",
+    ".ttf",
+    ".woff",
+    ".woff2",
+    ".eot",
+    ".otf",
+    ".mp4",
+    ".mp3",
+    ".wav",
+    ".webm",
+    ".ogg",
+    ".exe",
+    ".dll",
+    ".so",
+    ".dylib",
+    ".bin",
+    ".iso",
+    ".dmg",
+    ".pkg",
+    ".deb",
+    ".rpm",
+    ".csv",
+    ".lock",
+}
+
+# Binary formats that are never worth analyzing. Files without a listed
+# extension are still caught by a null-byte sniff (see BINARY_SNIFF_BYTES).
+BINARY_EXTENSIONS: Set[str] = {
+    ".wasm",
+    ".o",
+    ".a",
+    ".lib",
+    ".obj",
+    ".pdb",
+    ".class",
+    ".jar",
+    ".war",
+    ".pyc",
+    ".pyo",
+    ".node",
+    ".webp",
+    ".avif",
+    ".bmp",
+    ".tif",
+    ".tiff",
+    ".psd",
+    ".heic",
+    ".icns",
+    ".mov",
+    ".avi",
+    ".mkv",
+    ".flac",
+    ".m4a",
+    ".aac",
+    ".7z",
+    ".bz2",
+    ".xz",
+    ".zst",
+    ".rar",
+    ".tgz",
+    ".sqlite",
+    ".sqlite3",
+    ".db",
+    ".npy",
+    ".npz",
+    ".pkl",
+    ".parquet",
+    ".onnx",
+    ".pt",
+    ".safetensors",
+}
+
+# How much of each candidate file to read when sniffing for binary content.
+BINARY_SNIFF_BYTES = 8 * 1024
+
+# Minified/bundled JS and CSS: checked by content, since built bundles rarely
+# carry a ``.min`` suffix (e.g. Vite's ``assets/index-<hash>.js``).
+MINIFIED_CHECK_EXTENSIONS: Set[str] = {".js", ".mjs", ".cjs", ".css"}
+MINIFIED_SNIFF_BYTES = 64 * 1024
+# Hand-written code averages well under 80 characters per line.
+MINIFIED_MIN_AVG_LINE_LENGTH = 200
+
+# Files larger than this skip their analyzer and stay in the tree with a line
+# count and size only (analysis_status "too_large"). The scan checks this before
+# dispatch, so no worker is spent on them. Peak worker memory grows about 80 MB
+# per MB of input on the heaviest paths (tree-sitter on generated TSX, CSS,
+# lizard on HTML with data URLs), so 2 MiB keeps a worker near 220 MB. The
+# largest real source files in the repos measured are under 1 MB.
+MAX_ANALYZED_FILE_BYTES = 2 * 1024 * 1024

{srcly-0.1.34 → srcly-0.3.0}/app/main.py

@@ -8,7 +8,7 @@ import os
 import signal
 import threading
 
-from app.routers import analysis, files, scans
+from app.routers import analysis, compare, files, scans
 from app.services.scan_workers import cancel_all_scans
 
 _SHUTDOWN_SIGNALS = (signal.SIGINT, signal.SIGTERM)
@@ -76,6 +76,14 @@ app.add_middleware(
 app.include_router(analysis.router)
 app.include_router(files.router)
 app.include_router(scans.router)
+app.include_router(compare.router)
+
+
+@app.get("/api-status")
+async def root():
+    return {
+        "message": "Srcly server is running. Visit /docs for API documentation."
+    }
 
 
 def _find_static_dir() -> str | None:
@@ -111,14 +119,9 @@ def _find_static_dir() -> str | None:
     return None
 
 
-# Serve SPA if we can find built assets
+# Serve SPA if we can find built assets. Mounted last: a mount at "/" matches
+# every path, so routes declared after it would be unreachable.
 static_dir = _find_static_dir()
 if static_dir:
     app.mount("/", StaticFiles(directory=static_dir, html=True), name="static")
 
-
-@app.get("/api-status")
-async def root():
-    return {
-        "message": "Srcly server is running. Visit /docs for API documentation."
-    }

srcly-0.3.0/app/models.py

@@ -0,0 +1,105 @@
+from typing import List
+from pydantic import BaseModel, Field
+
+class Metrics(BaseModel):
+    loc: int = 0
+    # Max cyclomatic complexity (CCN) of any function or nested scope in this
+    # node, so files and folders mean the same thing (a folder is the max of
+    # its children). A function node holds its own CCN.
+    complexity: float = 0.0
+    # Mean CCN per function: the analyzer's per-file average for files, and
+    # the function-count-weighted mean of children for folders.
+    complexity_avg: float = 0.0
+    function_count: int = 0
+    last_modified: float = 0.0
+    gitignored_count: int = 0
+    file_size: int = 0
+    file_count: int = 0
+    
+    # New metrics
+    comment_lines: int = 0
+    comment_density: float = 0.0
+    max_nesting_depth: int = 0
+    average_function_length: float = 0.0
+    parameter_count: int = 0
+    todo_count: int = 0
+    classes_count: int = 0
+    
+    # TS/TSX Specific Metrics
+    tsx_nesting_depth: int = 0
+    tsx_render_branching_count: int = 0
+    tsx_react_use_effect_count: int = 0
+    tsx_anonymous_handler_count: int = 0
+    tsx_prop_count: int = 0
+    ts_any_usage_count: int = 0
+    ts_ignore_count: int = 0
+    ts_import_coupling_count: int = 0
+    tsx_hardcoded_string_volume: int = 0
+    tsx_duplicated_string_count: int = 0
+    ts_type_interface_count: int = 0
+    ts_export_count: int = 0
+    
+    # Python-specific metrics
+    python_import_count: int = 0
+
+    # Markdown-specific metrics
+    md_data_url_count: int = 0
+
+    # Analysis outcome. Files whose analyzer timed out, crashed, or raised stay
+    # in the tree with fallback LOC/size; ``analysis_status`` says why
+    # ("ok" | "timeout" | "error" | "crash" | "too_large"). "too_large" files are
+    # over ``MAX_ANALYZED_FILE_BYTES`` and were skipped on purpose, so they do
+    # not count in ``analysis_failed_count``. Folders sum failed files below.
+    analysis_status: str = "ok"
+    analysis_error: str = ""
+    analysis_failed_count: int = 0
+
+class Node(BaseModel):
+    name: str
+    type: str  # "folder", "file", "function", "code_fragment"
+    path: str
+    metrics: Metrics
+    # Use default_factory to avoid sharing the same list across instances
+    children: List["Node"] = Field(default_factory=list)
+    start_line: int = 0
+    end_line: int = 0
+
+    model_config = {
+        "populate_by_name": True
+    }
+
+# --- Hierarchical dependency graph contract (client/src/viz/deps/contract.ts) ---
+
+class DepGraphNode(BaseModel):
+    """folder | file | symbol | external node in the dependency hierarchy."""
+
+    model_config = {"populate_by_name": True}
+
+    id: str
+    kind: str
+    name: str
+    parent: str | None = None
+    path: str | None = None
+    abs_path: str | None = Field(default=None, alias="absPath")
+    language: str | None = None
+    is_test: bool | None = Field(default=None, alias="isTest")
+    symbol_kind: str | None = Field(default=None, alias="symbolKind")
+    line: int | None = None
+
+
+class DepGraphEdge(BaseModel):
+    """importer → imported; endpoints are file, symbol or external ids."""
+
+    model_config = {"populate_by_name": True}
+
+    source: str
+    target: str
+    type_only: bool | None = Field(default=None, alias="typeOnly")
+    via_barrel: bool | None = Field(default=None, alias="viaBarrel")
+    symbols: List[str] | None = None
+
+
+class DepGraph(BaseModel):
+    root: str
+    nodes: List[DepGraphNode]
+    edges: List[DepGraphEdge]

srcly-0.3.0/app/routers/analysis.py

@@ -0,0 +1,131 @@
+from fastapi import APIRouter, HTTPException, Response
+from pathlib import Path
+
+from app.models import Node
+from app.services import analysis, scan_jobs
+from app.models import DepGraph
+from app.services.deps.graph import build_dependency_graph
+
+router = APIRouter(prefix="/api/analysis", tags=["analysis"])
+
+# TODO: Make this configurable via env var or request
+ROOT_PATH = Path.cwd()
+
+
+def _scan_response(target_path: Path, force: bool = False) -> Response:
+    """
+    Scan ``target_path`` through the shared job manager and return the tree.
+
+    An unchanged cached analysis is returned without scanning unless
+    ``force`` is set.
+
+    Joining the manager means concurrent requests for the same path (two tabs,
+    a reload mid-scan, or a ``/api/scans`` job started by the UI) share one
+    scan instead of each starting their own. The tree is returned as
+    pre-encoded JSON so the encoding happens here, in a worker thread, rather
+    than on the event loop.
+    """
+    job = scan_jobs.manager.start(target_path, force=force)
+    job.wait()
+    if job.phase == "cancelled":
+        raise HTTPException(status_code=503, detail="Scan cancelled")
+    if job.phase != "complete":
+        raise HTTPException(status_code=500, detail=job.error or f"Scan {job.phase}")
+    return Response(content=job.result_json(), media_type="application/json")
+
+
+# Scan endpoints are plain `def` on purpose: FastAPI runs them in a worker
+# thread, so a long scan never blocks the event loop (which would also stop
+# uvicorn from reacting to Ctrl+C). They return a `Response` directly, so
+# `response_model` only documents the shape.
+@router.get("", response_model=Node)
+def get_analysis(path: str = None):
+    """
+    Get the static analysis of the codebase.
+    Returns the cached result if no files changed since it was taken,
+    otherwise scans.
+    """
+    target_path = Path(path) if path else ROOT_PATH
+
+    if not target_path.exists():
+         # Fallback or error? Let's error if explicit path is invalid
+         if path:
+             raise HTTPException(status_code=404, detail="Path not found")
+         target_path = ROOT_PATH
+
+    return _scan_response(target_path)
+
+@router.get("/dependency-graph", response_model=DepGraph, response_model_exclude_none=True)
+def get_dependency_graph(path: str = None):
+    """
+    Hierarchical, language-neutral dependency graph (folders → files, importer → imported
+    edges, barrels passed through). The client aggregates and lays it out.
+    """
+    target_path = Path(path) if path else ROOT_PATH
+    if not target_path.exists():
+        raise HTTPException(status_code=404, detail="Path not found")
+    if target_path.is_file():
+        target_path = target_path.parent
+    return build_dependency_graph(target_path)
+
+
+@router.post("/refresh", response_model=Node)
+def refresh_analysis(path: str = None):
+    """
+    Force a re-scan of the codebase, ignoring (and replacing) the cache.
+    """
+    target_path = Path(path) if path else ROOT_PATH
+    if not target_path.exists():
+        raise HTTPException(status_code=404, detail="Path not found")
+    return _scan_response(target_path, force=True)
+
+
+def _estimate_counts(root: Path) -> tuple[int, int]:
+    """
+    Return the (file_count, folder_count) a scan of ``root`` will analyze.
+
+    Uses the scan's own discovery (git ls-files or the .gitignore walk, plus
+    the built-in, binary, and minified filters) so the landing page matches
+    the scan.
+    """
+    try:
+        discovery = analysis.discover_files(root)
+    except Exception:
+        # If anything goes wrong, fall back to zeros but still report the path.
+        return 0, 0
+    return len(discovery.files), discovery.folder_count
+
+
+@router.get("/context")
+def get_analysis_context():
+    """
+    Return basic information about the current analysis root directory.
+
+    This is used by the client to offer one-click analysis options on first
+    load, for both the current working directory and the repository root.
+    """
+    current_root = ROOT_PATH
+    # Use the same repository root detection logic as the analysis layer so that
+    # the client sees a consistent "repo root" regardless of how the server was
+    # started (uvx, direct CLI, dev mode, etc.).
+    #
+    # This mirrors the behaviour of the CLI helper that walks upwards from the
+    # current directory to the enclosing `.git` root, falling back to the
+    # starting directory when no repository is found.
+    repo_root = analysis.find_repo_root(current_root)
+
+    current_file_count, current_folder_count = _estimate_counts(current_root)
+
+    repo_file_count = 0
+    repo_folder_count = 0
+    if repo_root.exists():
+        repo_file_count, repo_folder_count = _estimate_counts(repo_root)
+
+    return {
+        "root_path": str(current_root),
+        "file_count": current_file_count,
+        "folder_count": current_folder_count,
+        "repo_root_path": str(repo_root),
+        "repo_file_count": repo_file_count,
+        "repo_folder_count": repo_folder_count,
+    }

srcly-0.3.0/app/routers/compare.py

@@ -0,0 +1,171 @@
+"""
+Compare two git refs (PR compare mode).
+
+    GET    /api/compare/refs          branches + recent commits for the picker
+    GET    /api/compare/sources       one picker section: prs | worktrees | branches
+    GET    /api/compare/commits       first-parent commits in base..head (commit stepper)
+    POST   /api/compare/prewarm       scan one commit side in the background
+    POST   /api/compare               start (or join) a compare   -> snapshot
+    GET    /api/compare/{id}          current snapshot (poll)
+    GET    /api/compare/{id}/result   compare payload once complete
+    DELETE /api/compare/{id}          cancel                      -> snapshot
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import Response
+from pydantic import BaseModel
+
+from app.routers import analysis as analysis_router
+from app.services.compare import jobs, sources
+from app.services.compare.git_refs import (
+    AUTO,
+    GitError,
+    default_branch,
+    list_commits,
+    repo_root,
+    resolve_auto_base,
+    resolve_ref,
+    run_git,
+)
+from app.services.compare.service import DEFAULT_BASE, DEFAULT_HEAD
+
+router = APIRouter(prefix="/api/compare", tags=["compare"])
+
+RECENT_COMMITS = 30
+RECENT_BRANCHES = 20
+
+
+class StartCompareRequest(BaseModel):
+    path: Optional[str] = None
+    base: str = DEFAULT_BASE
+    head: str = DEFAULT_HEAD
+    force: bool = False
+
+
+def _target(path: Optional[str]) -> Path:
+    target = Path(path) if path else analysis_router.ROOT_PATH
+    if not target.exists():
+        raise HTTPException(status_code=404, detail=f"Path not found: {target}")
+    return target.resolve()
+
+
+def _job_or_404(job_id: str) -> jobs.CompareJob:
+    job = jobs.manager.get(job_id)
+    if job is None:
+        raise HTTPException(status_code=404, detail="Compare not found")
+    return job
+
+
+@router.get("/refs")
+def list_refs(path: Optional[str] = None) -> dict:
+    try:
+        repo = repo_root(_target(path))
+        current = run_git(repo, "rev-parse", "--abbrev-ref", "HEAD").strip()
+        branches = [
+            dict(zip(("name", "sha", "date"), line.split("\0")))
+            for line in run_git(
+                repo,
+                "for-each-ref",
+                "--sort=-committerdate",
+                f"--count={RECENT_BRANCHES}",
+                "--format=%(refname:short)%00%(objectname:short)%00%(committerdate:relative)",
+                "refs/heads",
+            ).splitlines()
+        ]
+        commits = [
+            dict(zip(("sha", "subject", "date"), line.split("\0")))
+            for line in run_git(
+                repo, "log", f"-{RECENT_COMMITS}", "--format=%h%x00%s%x00%cr"
+            ).splitlines()
+        ]
+        try:
+            default = default_branch(repo)
+        except GitError:
+            default = None
+    except GitError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    return {
+        "repo": str(repo),
+        "current": current,
+        "defaultBranch": default,
+        "branches": branches,
+        "commits": commits,
+    }
+
+
+@router.get("/sources")
+def list_sources(kind: str, path: Optional[str] = None, all: bool = False, refresh: bool = False) -> dict:
+    """
+    One picker section. Each kind is its own request so worktrees and branches
+    render while ``gh`` is still answering. A source that can't load (no gh,
+    not signed in, offline) comes back with ``available: false`` and a reason.
+    """
+    if kind not in ("prs", "worktrees", "branches"):
+        raise HTTPException(status_code=400, detail=f"Unknown source kind: {kind}")
+    try:
+        repo = repo_root(_target(path))
+    except GitError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    return {"repo": str(repo), **sources.load_source(repo, kind, mine=not all, refresh=refresh)}
+
+
+@router.get("/commits")
+def get_commits(base: str, head: str, path: Optional[str] = None) -> dict:
+    """The commits a stepper walks: ``base`` resolves as a base (``pr:<n>`` → its merge-base, ``auto``)."""
+    try:
+        repo = repo_root(_target(path))
+        head_ref = resolve_ref(repo, head, side="head")
+        base_ref = resolve_auto_base(repo, head, head_ref) if base == AUTO else resolve_ref(repo, base, side="base")
+        listing = list_commits(repo, base_ref, head_ref)
+    except GitError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    return {
+        "base": {"sha": base_ref.sha, "label": base_ref.label, "subject": base_ref.subject},
+        "head": {"sha": head_ref.sha, "label": head_ref.label},
+        **listing,
+    }
+
+
+class PrewarmRequest(BaseModel):
+    path: Optional[str] = None
+    ref: str
+
+
+@router.post("/prewarm", status_code=202)
+def prewarm(req: PrewarmRequest) -> dict:
+    try:
+        state = jobs.manager.prewarm(_target(req.path), req.ref.strip())
+    except GitError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    return {"ref": req.ref, "state": state}
+
+
+@router.post("", status_code=202)
+def start_compare(req: StartCompareRequest) -> dict:
+    target = _target(req.path)
+    return jobs.manager.start(target, req.base.strip(), req.head.strip(), force=req.force).snapshot()
+
+
+@router.get("/{job_id}")
+def get_compare(job_id: str) -> dict:
+    return _job_or_404(job_id).snapshot()
+
+
+@router.delete("/{job_id}")
+def cancel_compare(job_id: str) -> dict:
+    job = _job_or_404(job_id)
+    job.cancel_token.cancel()
+    return job.snapshot()
+
+
+@router.get("/{job_id}/result")
+def get_compare_result(job_id: str):
+    job = _job_or_404(job_id)
+    if job.phase != "complete" or job.result_json is None:
+        raise HTTPException(status_code=409, detail=f"Compare is {job.phase}, not complete")
+    return Response(content=job.result_json, media_type="application/json")