srcly 0.3.0__tar.gz → 1.0.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: srcly
-Version: 0.3.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.3.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.3.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.3.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.3.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")

{srcly-0.3.0 → srcly-1.0.0}/app/run.py

@@ -9,7 +9,7 @@ from pathlib import Path
 
 import uvicorn
 
-from app.services import reporting
+from app.services import activity, metric_catalog, quadrants, reporting
 from app.services.scan_workers import ScanCancelled
 
 # Seconds uvicorn waits for open connections after Ctrl+C before closing them.
@@ -165,6 +165,12 @@ def _run_headless(argv: list[str]) -> None:
     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(
+        "--activity-window",
+        choices=list(activity.WINDOWS),
+        default=activity.DEFAULT_WINDOW,
+        help="Git history window for commit_count / churn_lines (default 90d).",
+    )
     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.")
@@ -177,6 +183,12 @@ def _run_headless(argv: list[str]) -> None:
     )
 
     report_parser = subparsers.add_parser("report", help="Write agent-ready report artifacts.")
+    report_parser.add_argument(
+        "--activity-window",
+        choices=list(activity.WINDOWS),
+        default=activity.DEFAULT_WINDOW,
+        help="Git history window for commit_count / churn_lines (default 90d).",
+    )
     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(
@@ -217,7 +229,23 @@ def _run_headless(argv: list[str]) -> None:
         "--profile",
         choices=["general", "frontend", "backend", "typescript", "python", "docs"],
         default="general",
-        help="Scoring profile.",
+        help="Profile for the weighted findings queue.",
+    )
+    report_parser.add_argument(
+        "--quadrant",
+        choices=quadrants.PRESET_IDS,
+        help="Also list members per quadrant of a named 2x2 preset (report.md section + quadrants.json).",
+    )
+    report_parser.add_argument(
+        "--quadrant-cohort",
+        choices=("file", "function", "component"),
+        help="Point type for --quadrant. Defaults to the preset's first (files; components for component_weight).",
+    )
+    report_parser.add_argument(
+        "--metric",
+        choices=metric_catalog.RANKABLE_IDS,
+        default=None,
+        help="Metric for the Top Files / Top Functions tables and hotspots.json. Defaults to the profile's heaviest metric.",
     )
     report_parser.add_argument(
         "--format",
@@ -241,12 +269,35 @@ def _run_headless(argv: list[str]) -> None:
     )
 
     hotspots_parser = subparsers.add_parser("hotspots", help="Print ranked hotspots.")
+    hotspots_parser.add_argument(
+        "--activity-window",
+        choices=list(activity.WINDOWS),
+        default=activity.DEFAULT_WINDOW,
+        help="Git history window for commit_count / churn_lines (default 90d).",
+    )
     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(
+        "--metric",
+        choices=metric_catalog.RANKABLE_IDS,
+        default="complexity",
+        help="Metric to rank by, worst first (the explorer's Hot Spots list).",
+    )
     hotspots_parser.add_argument("--limit", type=int, default=25, help="Maximum hotspots to print.")
+    hotspots_parser.add_argument(
+        "--cohort",
+        choices=["file", "function"],
+        default="file",
+        help="Rank files against files, or functions against functions.",
+    )
     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(
+        "--activity-window",
+        choices=list(activity.WINDOWS),
+        default=activity.DEFAULT_WINDOW,
+        help="Git history window for commit_count / churn_lines (default 90d).",
+    )
     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.")
@@ -297,7 +348,7 @@ def _run_headless(argv: list[str]) -> None:
             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)
+        reporting.write_scan(target_path, out_path, refresh=args.refresh, activity_window=args.activity_window)
         if str(args.out) != "-":
             print(f"Wrote Srcly tree JSON to {out_path}")
         return
@@ -308,6 +359,7 @@ def _run_headless(argv: list[str]) -> None:
             payload = reporting.build_report_payload(
                 target_path,
                 profile=args.profile,
+                metric=args.metric,
                 limit=args.limit,
                 refresh=args.refresh,
                 tree_depth=args.tree_depth,
@@ -319,6 +371,9 @@ def _run_headless(argv: list[str]) -> None:
                 agent_compact=args.agent_compact,
                 verbose=args.verbose,
                 output_format=args.format,
+                activity_window=args.activity_window,
+                quadrant=args.quadrant,
+                quadrant_cohort=args.quadrant_cohort,
             )
             print(reporting._json_dumps(payload))
         else:
@@ -328,6 +383,7 @@ def _run_headless(argv: list[str]) -> None:
                 target_path,
                 out_dir,
                 profile=args.profile,
+                metric=args.metric,
                 limit=args.limit,
                 output_format=output_format,
                 refresh=args.refresh,
@@ -339,6 +395,9 @@ def _run_headless(argv: list[str]) -> None:
                 deprioritize_paths=_deprioritize_paths(args),
                 agent_compact=args.agent_compact,
                 verbose=args.verbose,
+                activity_window=args.activity_window,
+                quadrant=args.quadrant,
+                quadrant_cohort=args.quadrant_cohort,
             )
             if args.verbose:
                 print(f"Wrote Srcly report artifacts to {out_dir}")
@@ -355,22 +414,25 @@ def _run_headless(argv: list[str]) -> None:
 
     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]
+        tree = reporting.scan_tree(target_path, activity_window=args.activity_window)
+        result = reporting.rank_by_metric(tree, args.metric, cohort=args.cohort, root_path=target_path)
+        result["ranked"] = result["ranked"][: args.limit]
         if args.format == "json":
-            print(reporting._json_dumps({"rankings": ranked}))
+            print(reporting._json_dumps(result))
         else:
-            for item in ranked:
+            for item in result["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']}")
+                where = f" in {item['witness']['name']} (line {item['witness']['start_line']})" if item["witness"] else ""
+                print(f"{item['rank']}. {item['value']} {item['unit']} {location}{where}")
+            if result["na_count"]:
+                print(f"({result['na_count']} N/A for {args.metric}, not ranked)")
         return
 
     if args.command == "explain":
         target_path = _resolve_target_path(args.path)
-        tree = reporting.scan_tree(target_path)
+        tree = reporting.scan_tree(target_path, activity_window=args.activity_window)
         payload = _explain_file(tree, Path(args.file).resolve(), target_path)
         if args.format == "json":
             print(reporting._json_dumps(payload))
@@ -414,14 +476,6 @@ def _run_compare(args) -> None:
         print(render_markdown(payload, limit=args.limit), end="")
 
 
-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 _deprioritize_paths(args) -> tuple[str, ...]:
     if args.no_default_deprioritize:
         return tuple(args.deprioritize or ())
@@ -467,7 +521,8 @@ def _explain_file(tree, file_path: Path, root_path: Path) -> dict:
     if target is None:
         raise SystemExit(f"File not found in analysis tree: {file_path}")
 
-    ranked = reporting.rank_nodes(target)
+    # Inside one file, rank its functions against each other.
+    ranked = reporting.rank_nodes(target, cohort="function")
     return {
         "path": str(file_path),
         "summary": reporting.summarize_tree(target, ranked, root_path=root_path, max_depth=3, top_children=20),