srcly 0.2.0__tar.gz → 1.0.0__tar.gz

{srcly-0.2.0 → srcly-1.0.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.2.0 → srcly-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: srcly
-Version: 0.2.0
+Version: 1.0.0
 Summary: Interactive codebase treemap and metrics viewer.
 Requires-Python: >=3.13
 Requires-Dist: fastapi>=0.121.3
@@ -9,6 +9,7 @@ Requires-Dist: lizard>=1.21.7
 Requires-Dist: pathspec>=0.12.1
 Requires-Dist: pydantic>=2.12.4
 Requires-Dist: pytest>=9.0.1
+Requires-Dist: ruff>=0.17.1
 Requires-Dist: tree-sitter-css==0.25.0
 Requires-Dist: tree-sitter-markdown<0.6.0,>=0.5.1
 Requires-Dist: tree-sitter-python==0.25.0

{srcly-0.2.0 → srcly-1.0.0}/app/main.py

@@ -8,7 +8,7 @@ import os
 import signal
 import threading
 
-from app.routers import analysis, compare, files, scans
+from app.routers import analysis, compare, files, metrics, scans
 from app.services.scan_workers import cancel_all_scans
 
 _SHUTDOWN_SIGNALS = (signal.SIGINT, signal.SIGTERM)
@@ -77,6 +77,7 @@ app.include_router(analysis.router)
 app.include_router(files.router)
 app.include_router(scans.router)
 app.include_router(compare.router)
+app.include_router(metrics.router)
 
 
 @app.get("/api-status")

srcly-1.0.0/app/models.py

@@ -0,0 +1,207 @@
+from typing import List
+from pydantic import BaseModel, Field
+
+class Witness(BaseModel):
+    """The function responsible for a max-type metric, so the UI can open it."""
+
+    path: str  # node path of the function: "<file>::<scope>::<name>"
+    name: str
+    start_line: int = 0
+    end_line: int = 0
+
+
+class Metrics(BaseModel):
+    # Always measured: every file has lines, bytes and a mtime.
+    loc: int = 0
+    last_modified: float = 0.0
+    gitignored_count: int = 0
+    file_size: int = 0
+    file_count: int = 0
+
+    # Everything below is ``None`` (N/A) when the metric doesn't apply to the
+    # node's language, the file was skipped or failed, or (for means) there are
+    # no functions to average. A measured zero stays 0. ``na_reason`` says why
+    # this node's ``None`` values are missing. Folder rollups ignore N/A
+    # children; a folder value is ``None`` only when no child measured it.
+    #
+    # Max cyclomatic complexity (CCN) of any executable function in this node,
+    # so files and folders mean the same thing; ``complexity_witness`` names
+    # that function. A scope node holds its own CCN.
+    complexity: float | None = None
+    complexity_witness: Witness | None = None
+    # Mean CCN over executable functions (any depth), weighted by function
+    # count for folders.
+    complexity_avg: float | None = None
+    # Executable functions at any depth (methods, nested functions, arrows);
+    # classes, types, object literals and JSX containers don't count.
+    function_count: int | None = None
+
+    comment_lines: int | None = None
+    # Comment noise: flags for over-commenting on absolute thresholds (see
+    # ``services/comment_noise.py``). The total and its three parts.
+    comment_noise: int | None = None
+    comment_noise_ratio: int | None = None
+    comment_noise_docblock: int | None = None
+    comment_noise_commented_code: int | None = None
+    max_nesting_depth: int | None = None
+    average_function_length: float | None = None
+    parameter_count: int | None = None
+    # Neutral detail: shown, never ranked as risk.
+    todo_count: int | None = None
+    classes_count: int | None = None
+
+    # React/Solid components (TSX). A component scope holds its own values;
+    # files and folders hold the max over their components, and ``witnesses``
+    # names the component behind each max. N/A when there are no components.
+    component_loc: int | None = None
+    component_hook_count: int | None = None
+    component_effect_count: int | None = None
+    component_jsx_depth: int | None = None
+    component_prop_count: int | None = None
+    component_inline_handler_count: int | None = None
+    component_jsx_conditional_count: int | None = None
+    witnesses: dict[str, Witness] | None = None
+
+    # TS/TSX Specific Metrics
+    ts_any_usage_count: int | None = None
+    ts_ignore_count: int | None = None
+    # Neutral detail
+    ts_import_coupling_count: int | None = None
+    ts_type_interface_count: int | None = None
+    ts_export_count: int | None = None
+
+    # Python-specific metrics
+    python_import_count: int | None = None
+
+    # Markdown-specific metrics
+    md_data_url_count: int | None = None
+
+    # Git activity (``services/activity.py``), laid over the tree when it is
+    # served: commits touching the file in the selected window, and lines
+    # added + removed by them. Files and folders (sums) only; scopes are N/A.
+    commit_count: int | None = None
+    churn_lines: int | None = None
+
+    # Lint and type-check findings (``services/findings``), laid over the tree
+    # when it is served: everything the checkers reported for the file, and
+    # the errors among them. N/A when no checker covers the file or its
+    # checker failed or timed out. Files and folders (sums); scopes are N/A.
+    finding_count: int | None = None
+    error_count: int | None = None
+
+    na_reason: str = ""
+    # Per-metric reasons that override ``na_reason`` (activity has its own:
+    # "Not a Git repository", "Shallow clone", ...).
+    na_reasons: dict[str, str] | None = None
+
+    # 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
+
+
+# Metrics that can be N/A, in display order. Rollup rules live in
+# ``analysis.aggregate_metrics``.
+OPTIONAL_METRIC_FIELDS: tuple[str, ...] = tuple(
+    name for name, field in Metrics.model_fields.items()
+    if name not in ("complexity_witness", "witnesses", "na_reasons") and field.default is None
+)
+
+
+class ActivityInfo(BaseModel):
+    """Git activity status for a whole tree (root node only)."""
+
+    window: str
+    window_label: str
+    status: str  # "ok" | "na"
+    reason: str = ""
+    note: str = ""  # e.g. uncommitted changes; results are still valid
+    head: str = ""
+    files_touched: int = 0
+
+
+class FindingsTool(BaseModel):
+    """One checker run: which tool, from where, and how it went."""
+
+    id: str
+    tool: str  # "tsc" | "eslint" | "ruff" | "srcly-ts"
+    label: str  # "tsc (client/tsconfig.app.json)", "ruff (srcly defaults)"
+    source: str  # "project" | "srcly defaults"
+    status: str  # "ok" | "na"
+    reason: str = ""
+    seconds: float = 0.0
+    finding_count: int = 0
+    error_count: int = 0
+    files_checked: int | None = None
+
+
+class FindingsInfo(BaseModel):
+    """Lint and type-check status for a whole tree (root node only)."""
+
+    status: str  # "running" | "ok" | "na"
+    reason: str = ""
+    tools: List[FindingsTool] = Field(default_factory=list)
+    finding_count: int = 0
+
+
+class Node(BaseModel):
+    name: str
+    type: str  # "folder", "file", "function", "function_body"
+    # For "function" nodes: the scope kind ("function" is executable code;
+    # "class" | "type" | "object" | "jsx" | "imports" | "block" are display
+    # scopes). ``None`` for folders, files and bodies.
+    kind: str | None = None
+    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
+    # Root only: whether Git activity could be measured, and for which window.
+    activity: ActivityInfo | None = None
+    # Root only: whether the checks finished, and which tools ran.
+    findings: FindingsInfo | None = None
+
+    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.2.0 → srcly-1.0.0}/app/routers/analysis.py

@@ -2,7 +2,7 @@ from fastapi import APIRouter, HTTPException, Response
 from pathlib import Path
 
 from app.models import Node
-from app.services import analysis, scan_jobs
+from app.services import analysis, quadrants, scan_jobs
 from app.models import DepGraph
 from app.services.deps.graph import build_dependency_graph
 
@@ -12,7 +12,15 @@ router = APIRouter(prefix="/api/analysis", tags=["analysis"])
 ROOT_PATH = Path.cwd()
 
 
-def _scan_response(target_path: Path, force: bool = False) -> Response:
+def result_bytes(job: scan_jobs.ScanJob, activity_window: str | None = None) -> bytes:
+    """The finished tree with Git activity for ``activity_window`` (default 90d) and findings."""
+    try:
+        return job.result_json_overlaid(activity_window)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+
+def _scan_response(target_path: Path, force: bool = False, activity_window: str | None = None) -> Response:
     """
     Scan ``target_path`` through the shared job manager and return the tree.
 
@@ -31,7 +39,7 @@ def _scan_response(target_path: Path, force: bool = False) -> Response:
         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")
+    return Response(content=result_bytes(job, activity_window), media_type="application/json")
 
 
 # Scan endpoints are plain `def` on purpose: FastAPI runs them in a worker
@@ -39,7 +47,7 @@ def _scan_response(target_path: Path, force: bool = False) -> Response:
 # 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):
+def get_analysis(path: str = None, activity_window: str | None = None):
     """
     Get the static analysis of the codebase.
     Returns the cached result if no files changed since it was taken,
@@ -53,7 +61,7 @@ def get_analysis(path: str = None):
              raise HTTPException(status_code=404, detail="Path not found")
          target_path = ROOT_PATH
 
-    return _scan_response(target_path)
+    return _scan_response(target_path, activity_window=activity_window)
 
 @router.get("/dependency-graph", response_model=DepGraph, response_model_exclude_none=True)
 def get_dependency_graph(path: str = None):
@@ -69,15 +77,27 @@ def get_dependency_graph(path: str = None):
     return build_dependency_graph(target_path)
 
 
+@router.get("/fan-in")
+def get_fan_in(path: str = None) -> dict:
+    """Absolute file path → distinct files importing it, for the Blast radius 2x2."""
+    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
+    counts = quadrants.fan_in_by_path(target_path)
+    return {"counts": counts, "available": bool(counts)}
+
+
 @router.post("/refresh", response_model=Node)
-def refresh_analysis(path: str = None):
+def refresh_analysis(path: str = None, activity_window: str | None = 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)
+    return _scan_response(target_path, force=True, activity_window=activity_window)
 
 
 def _estimate_counts(root: Path) -> tuple[int, int]:

{srcly-0.2.0 → srcly-1.0.0}/app/routers/compare.py

@@ -2,6 +2,9 @@
 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
@@ -18,8 +21,17 @@ from fastapi.responses import Response
 from pydantic import BaseModel
 
 from app.routers import analysis as analysis_router
-from app.services.compare import jobs
-from app.services.compare.git_refs import GitError, default_branch, repo_root, run_git
+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"])
@@ -86,6 +98,53 @@ def list_refs(path: Optional[str] = None) -> dict:
     }
 
 
+@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)

{srcly-0.2.0 → srcly-1.0.0}/app/routers/files.py

@@ -74,6 +74,74 @@ def _content_at_ref(file_path: Path, ref: str) -> str:
         raise HTTPException(status_code=404, detail=f"File not found at {ref}: {exc}") from exc
 
 
+@router.get("/markers")
+def get_file_markers(
+    path: str = Query(..., description="Absolute path to the file"),
+    ref: str | None = Query(None, description="Git commit to read the file from instead of the disk"),
+):
+    """
+    Where each metric fires in a file: ``{metric_id: [{line, end_line, note}]}``.
+    The code viewer overlays these lines when a metric is picked.
+    """
+    from app.services.markers import collect_markers, collect_markers_for_text
+
+    file_path = Path(path)
+    try:
+        if ref:
+            markers = collect_markers_for_text(_content_at_ref(file_path, ref), file_path.suffix)
+        elif not file_path.is_file():
+            raise HTTPException(status_code=404, detail="File not found")
+        else:
+            markers = collect_markers(str(file_path))
+            markers.update(_findings_markers(file_path))
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to locate metrics: {e}") from e
+    return {"markers": markers}
+
+
+def _findings_job_result(file_path: Path):
+    from app.services import findings
+
+    job = findings.manager.for_file(file_path)
+    return job.result if job is not None else None
+
+
+def _findings_markers(file_path: Path) -> dict:
+    """Lines behind ``finding_count`` / ``error_count``, from the last checks run on this file."""
+    from app.services import findings
+
+    return findings.markers_for(str(file_path), _findings_job_result(file_path))
+
+
+@router.get("/findings")
+def get_file_findings(path: str = Query(..., description="Absolute path to the file")):
+    """
+    Lint and type-check findings for one file from the latest scan's checks:
+    ``{"status": "ok"|"running"|"na", "reason", "tools": [...], "findings":
+    [{line, column, rule, message, severity, tool}]}``. ``tools`` are the
+    checkers that covered the file, so the viewer can say which one ran.
+    """
+    from app.services import findings
+
+    return findings.file_findings(str(Path(path)), _findings_job_result(Path(path)))
+
+
+@router.get("/commits")
+def get_file_commits(
+    path: str = Query(..., description="Absolute path to the file"),
+    limit: int = Query(5, ge=1, le=50),
+):
+    """
+    The last commits touching a file (following renames): the evidence behind
+    its activity metrics. ``{"status", "reason", "commits": [{sha, short, date, author, subject}]}``.
+    """
+    from app.services.activity import recent_commits
+
+    return recent_commits(Path(path), limit=limit)
+
+
 @router.get("/suggest")
 def suggest_files(path: str = Query(..., description="Path to list contents of")):
     """

srcly-1.0.0/app/routers/metrics.py

@@ -0,0 +1,11 @@
+from fastapi import APIRouter
+
+from app.services.metric_catalog import catalog_payload
+
+router = APIRouter(prefix="/api/metrics", tags=["metrics"])
+
+
+@router.get("/catalog")
+def get_metric_catalog() -> dict:
+    """Every metric's label, unit, group, direction, scope, languages and color stops."""
+    return catalog_payload()

{srcly-0.2.0 → srcly-1.0.0}/app/routers/scans.py

@@ -4,7 +4,8 @@ Scan jobs with live progress over Server-Sent Events.
     POST   /api/scans               start (or join) a scan    -> snapshot
     GET    /api/scans/{id}          current snapshot (polling fallback)
     GET    /api/scans/{id}/events   SSE stream of snapshots
-    GET    /api/scans/{id}/result   analysis tree once complete
+    GET    /api/scans/{id}/result   analysis tree once complete (``?activity_window=30d|90d|1y|all``)
+    GET    /api/scans/{id}/findings lint/type-check status; the result has counts once it isn't running
     DELETE /api/scans/{id}          cancel                    -> snapshot
 
 SSE rather than WebSockets: progress only flows server -> client, cancel is
@@ -82,13 +83,19 @@ def cancel_scan(job_id: str) -> dict:
 
 
 @router.get("/{job_id}/result", response_model=Node)
-def get_scan_result(job_id: str):
+def get_scan_result(job_id: str, activity_window: Optional[str] = None):
     job = _job_or_404(job_id)
     if job.phase != "complete":
         raise HTTPException(status_code=409, detail=f"Scan is {job.phase}, not complete")
     # Pre-encoded bytes: serializing a large tree on the event loop would
     # block every other request (see ScanJob.result_json).
-    return Response(content=job.result_json(), media_type="application/json")
+    return Response(content=analysis_router.result_bytes(job, activity_window), media_type="application/json")
+
+
+@router.get("/{job_id}/findings")
+def get_scan_findings(job_id: str) -> dict:
+    """The scan's lint/type-check status (``FindingsInfo``); poll until it isn't ``running``."""
+    return _job_or_404(job_id).findings_result().info()
 
 
 @router.get("/{job_id}/events")