srcly/156,914 LOC · 1,136 files · 14,382 functions

See where the code gets hard.

Srcly maps a repository into folders, files, functions and nested scopes, then colors the map by the metric you pick. Start with the whole tree, then open the code behind a signal.

Get started

Runs on your machine. No account and no upload.

Version 1.12.0. Full analysis for TypeScript, JavaScript and Python; size and complexity for Go, Java, C, C++ and every other language Lizard reads.

Srcly's own source at e4485453. Area is lines of code; color is the most complex function in each file. Point at a tile to read it.

01050+ CCN N/A
start/server/app/run.py626 LOC · CCN 27

Install and first run

Srcly is a Python package that you run with uv. Nothing is installed globally. It needs Python 3.13 or newer, and uv gets that for you if it is missing.

  1. Run it in a repository

    uvx srcly
    uvx srcly .
    uvx srcly ~/code/app

    With no path, Srcly walks up to the enclosing Git root. Pass . to scan only the current folder, or give any path.

  2. Use the browser tab it opens

    Srcly starts a local server on 127.0.0.1 with a free port and opens your browser. --port and --host change that. Keep the terminal open. Ctrl+C stops it.

    The path bar at the top picks another folder. Recent folders stay in the menu.

  3. Wait for one scan

    The first scan shows live progress per file. Srcly saves the result in your user cache folder, never in the repository. When you open an unchanged repository again, it loads at once. Any file change starts a fresh scan.

    Srcly's own repository, 1,136 files, scans in about ten seconds on a laptop.

Optional: data flow needs Node.js 18 or newer on PATH. Lint and type checks use the project's own tsc and eslint when node_modules has them, and the bundled ruff for Python. Full setup guide

read/client/src/viz/treemap/1,835 LOC · CCN 54

How to read the treemap

Every rectangle is a piece of code, and every piece sits inside its parent. A folder holds files, a file holds functions, and a function holds its nested scopes.

client/src from the same scan. Each tile is a file; its color is its most complex function.
Area
Lines of code: nonblank lines that are not only a comment. Lines inside a function that are not in a nested scope become a (body) tile, so a line is never counted twice.
Color
The metric you pick in Color. Every metric uses one ramp, from blue (fine) through amber to red (look here). Each metric sets its own stops. For complexity they are 0, 10 and 50.
Hatching
N/A. The metric does not apply to that file, or its tool did not run. Srcly never shows N/A as 0, and the tooltip gives the reason.
Folders
Each metric has one rollup rule. LOC is a sum. Complexity is the maximum and names the function that sets it. A sum such as LOC colors a folder by its average per file.
Moving
Click a folder to zoom in, and use the breadcrumb or the browser's Back button to go up. Click a file or function to read its source. The All files menu filters by file type, and the explorer can hide or isolate a path.
views/client/src/viz/15,658 LOC · CCN 135

The views

One scan feeds every view. They share the metric model, the location in the URL, and the browser's Back button.

Srcly's treemap of its own repository, colored by maximum complexity, beside the explorer tree.

Treemap and explorer

The explorer on the left is the same tree as the map, with sortable columns for LOC, complexity and the other metrics. A folder row shows its file count, and the header names the most complex function below it.

The Activity 2×2 of Srcly's files, complexity against commits, with the Hot mess quadrant selected.

2×2

Plots two metrics against each other and names the four quadrants. Drag a cut-off line to move items between quadrants. The 5 presets:

  • Activity Complexity (max) × Commits: Hot mess, Sleeping giant, Busy, fine, Quiet
  • Blast radius Complexity (max) × Fan-in: Load-bearing tangle, Isolated mess, Hub, Leaf
  • Component weight Component LOC × Hooks: God component, Long markup, Hook soup, Lean
  • Comment noise Comment ratio × Complexity (max): Narrated complexity, Narrated trivia, Complex code, Clean
  • Findings Complexity (max) × Findings: Flagged tangle, Clean but complex, Quick cleanup, Clean
The code viewer showing buildViewModel, the most complex function in Srcly, with its metrics and marked lines.

Code viewer

Opens the source with syntax highlighting, the file's metrics, and each finding with its rule and the tool that reported it. Click a metric to mark its lines in the code, such as each branch that adds to complexity. Markdown renders as a preview.

The import graph centered on Srcly's treemap folder, with importers on the left and imports on the right.

Graph: imports

Shows TypeScript and Python imports as folders, files and symbols. The focus sits in the middle, what imports it on the left, and what it imports on the right. tsconfig path aliases resolve, and barrel files pass through to the real module.

Symbols mode centered on NotePage in the symbol-graph example, with its references and the inspector.

Graph: symbols

Centers one function, class or component and shows what refers to it and what it refers to, from a reference index for TypeScript and Python. Press / to find a symbol. It can draw the path between two symbols and mark dead code and hubs.

A data-flow trace from the NotePage route in the symbol-graph example, with where the trace stops in the inspector.

Graph: data flow

Traces how a value moves through calls in TypeScript, JavaScript and Python: from a route, a function or one expression, forward, backward or both. Each trace names its outcome and the places it stops. It needs Node.js 18 or newer.

Compare mode for Srcly pull request 354: 6 risk metrics worse, 1 better, with the changed files and SymbolInspector.tsx selected.

Compare

Shows what a change did to the codebase: which risk metrics got worse or better, and every changed file with its metric changes. The Treemap and Dependencies tabs show the before and after. Pick an open PR, a branch or a worktree, and step through a PR one commit at a time.

The symbols and data-flow shots use engine/examples/symbol-graph, a small app in the repository. A trace over the whole Srcly repository takes minutes.

workflows/server/app/services/reporting.py871 LOC · CCN 12

Common workflows

Each starts with a question. The answer is a place to read code, not a verdict on it.

Find the refactor that pays off first

  1. Set Color to Complexity (max) and look for red inside big tiles.
  2. Open Hot Spots and click the top row. The code viewer opens on the function that sets the value.
  3. Switch to 2×2 with the Activity preset. Files in Hot mess are complex and change often.

Review what a pull request did

  1. Click Compare and pick the PR, or run uvx srcly compare main pr:42.
  2. Read the risk metrics that got worse, then the changed files. The Dependencies tab shows the import graph before and after.
  3. A file measured on one side only counts as a coverage change, not as an improvement.

Stop big files from getting bigger

  1. report writes size_budget.json: each code file over 5,000 tokens (bytes ÷ 4).
  2. Add uvx srcly check . --ratchet to a pre-commit hook or CI.
  3. It exits 1 when a tracked file grows or a new file crosses the line. The baseline only goes down.

Clean up exports nobody uses

  1. Run uvx srcly fix . to print a diff of the safe fixes.
  2. Add --write to apply them.
  3. Deleting unreachable files needs --rule unreachable-file. Reachability follows imports from the entries Srcly finds, plus any you add in srcly.toml.
cli/server/app/run.py626 LOC · CCN 27

Command line

Headless commands run the same scan and share the app's cache. Machine-readable output is the only thing on stdout; progress goes to stderr.

CommandWhat it does
srcly [path]Scan and open the app. --host and --port pick the bind address.
srcly reportWrite report.md and JSON artifacts: findings, folders, hotspots, a tree summary, the metric schema and an agent guide. --quadrant adds a 2×2.
srcly explain --atDrill into the repo, a folder, a file, or file::symbol. Any printed "start at" value works.
srcly hotspotsRank files or functions by one metric. --format json for scripts.
srcly compare [base] [head]Metric and dependency changes between two refs. Defaults to the merge base against the working tree; pr:<n> names a PR.
srcly fixPrint a diff of safe fixes for srcly's own findings; --write applies them.
srcly check --ratchetExit 1 when a file over the size budget grows.
srcly scanWrite the raw analysis tree as JSON.
uvx srcly hotspots . --metric complexity --cohort function --limit 6
1. 135 CCN client/src/viz/deps/viewModel.ts::buildViewModel:130-510
2. 71 CCN engine/src/analysis/route-totality-field-transfer-verifier.ts::consumerPattern:458-545
3. 69 CCN client/src/compare/graphModel.ts::buildCompareGraph:109-293
4. 66 CCN client/src/viz/deps/layout.ts::placeAndRoute:637-1101
5. 66 CCN engine/src/analysis/route-totality-field-lineage-transition.ts::classifyRouteTotalityFieldTransition:116-269
6. 66 CCN server/app/services/typescript/typescript_analysis.py::(class) TreeSitterAnalyzer::_get_function_name:687-848
uvx srcly explain . --at client/src/viz/treemap

9 ranked files (code). Score: the profile's weighted mix of complexity, size, nesting and history, 1.0 = the repo's worst; 0.4+ is a finding. Pass any "start at" value to --at.

Folders, worst first

Folder Files LOC Findings Worst Its worst file: start at
client/src/viz/treemap/hooks/ 1 326 0 0.3259 client/src/viz/treemap/hooks/useTreemapTooltip.ts:255 buildTooltipContent
client/src/viz/treemap/components/ 3 720 0 0.2565 client/src/viz/treemap/components/TreemapCanvas.tsx:167 paint
client/src/viz/treemap/utils/ 5 276 0 0.1536 client/src/viz/treemap/utils/tree.ts:6 addScopeBodyDummyNodes

Files below, worst first

Score Start at Why
0.3259 client/src/viz/treemap/hooks/useTreemapTooltip.ts:255 buildTooltipContent High complexity 41, 326 LOC, nesting depth 2
0.2565 client/src/viz/treemap/components/TreemapCanvas.tsx:167 paint High complexity 54, 435 LOC, nesting depth 3
0.1536 client/src/viz/treemap/utils/tree.ts:6 addScopeBodyDummyNodes High complexity 25, 59 LOC, nesting depth 3
0.1452 client/src/viz/treemap/utils/hitTest.ts:28 buildTileHitIndex High complexity 7, 70 LOC, nesting depth 4
0.1037 client/src/viz/treemap/utils/colors.ts:62 scaleValue High complexity 5, 103 LOC, nesting depth 1
0.097 client/src/viz/treemap/utils/path.ts:10 dfs High complexity 5, 20 LOC, nesting depth 2
0.0687 client/src/viz/treemap/components/TreemapTooltip.tsx:7 tailPath High complexity 5, 164 LOC, nesting depth 1
0.0605 client/src/viz/treemap/components/TreemapHeader.tsx:47 TreemapHeader High complexity 2, 121 LOC
0.0491 client/src/viz/treemap/utils/zoom.ts:4 zoomTransforms High complexity 11, 24 LOC, nesting depth 1

Not ranked as code: test 6 (mostly test file name; top client/src/viz/treemap/hooks/useTreemapTooltip.test.ts). Add --include-class <class> to rank one.

Analysis: reused the scan from 2026-11-20 22:53 UTC (no file has changed since); Git history at e448545; lint/type checks: ruff (180 files), srcly TS rules (745 files), srcly reachability (758 files), srcly Solid rules (158 files), srcly await-in-loop (632 files); 11 of 571 code files have none (finding_count N/A).

Next: srcly explain /tmp/srcly --at client/src/viz/treemap/hooks

Both outputs are real, from Srcly scanning itself at e4485453. Every command and flag · What each report file holds

agents/skills/srcly-code-quality/81 LOC

For coding agents

Srcly runs headless, so an agent can scan a repository, read a ranked report, and drill into one scope at a time without loading the whole tree.

  1. Write the report

    uvx srcly report . --out .srcly

    Writes report.md, findings.json, hotspots.json, tree.summary.json, metrics.schema.json and agent-skill.md. The terminal prints the top findings and the next command to run.

  2. Drill in, one scope at a time

    uvx srcly explain . --at server/app
    uvx srcly explain . --at "server/app/run.py::_main"

    Each answer reuses the cached scan, takes about a second, and ends with a Next: command. Any printed "start at" value works as --at.

  3. Check a change

    uvx srcly compare --json
    uvx srcly check . --ratchet

    compare diffs the merge base against the working tree. A metric that is unavailable stays null, never 0.

reference/server/app/services/metric_catalog.py328 LOC · CCN 4

Reference

These tables come from Srcly's metric catalog, the same list the app's Color menu reads.

Metrics

Rollup is how a folder or file combines its children. Max, named also names the function or component that sets it. How to read a metric

MetricRollupLanguagesWhat it measures
General Size, complexity and comment noise for any code file.
Complexity (max)max, namedTS/JS, TSX/JSX, Python, other codeCyclomatic complexity: exact for a function; for a file or folder, its most complex function, which it names.
Cognitive complexity (max)max, namedTS/JS, TSX/JSX, PythonHow hard a function is to follow (Sonar's cognitive complexity): each if, loop, catch or ternary costs 1 plus its nesting, and each run of && or || costs 1, so a flat chain of checks stays low. A file or folder holds its worst function, which it names.
Complexity (avg)averageTS/JS, TSX/JSX, Python, other codeMean cyclomatic complexity per function; folders weight by function count.
LOCsumany fileLines of code, excluding comments and blanks where the analyzer can tell.
Sizesumany fileFile size in bytes.
Comment NoisesumTS/JS, TSX/JSX, PythonOver-commenting flags: functions with more comment lines than code lines (10+ code lines), docblocks over 1.5x their body (8+ lines), and 3+ line runs of commented-out code.
NestingmaxTS/JS, TSX/JSX, PythonDeepest control-flow nesting.
ParamssumTS/JS, TSX/JSX, Python, other codeFunction parameters; a file sums its functions, so rank the Functions cohort for arity.
Components React/Solid components in TSX: a file holds the max over its components and names it.
Component LOCmax, namedTSX/JSXLines in one React/Solid component. A file or folder holds the max over its components and names it.
Hooksmax, namedTSX/JSXHooks (use*) and Solid primitives (create*) in one component. A file or folder holds the max over its components and names it.
Effectsmax, namedTSX/JSXuseEffect/useLayoutEffect/createEffect calls in one component. A file or folder holds the max over its components and names it.
JSX Depthmax, namedTSX/JSXDeepest JSX nesting inside one component. A file or folder holds the max over its components and names it.
Propsmax, namedTSX/JSXDeclared props of one component (props type members or destructured names). A file or folder holds the max over its components and names it.
Inline Handlersmax, namedTSX/JSXInline on*={() => ...} handlers in one component. A file or folder holds the max over its components and names it.
JSX Conditionalsmax, namedTSX/JSXJSX conditionals (?:, &&, <Show>, <Match>) in one component. A file or folder holds the max over its components and names it.
TypeScript Type-safety escapes in .ts and .tsx files.
any UsagesumTS, TSXExplicit any types.
TS IgnoressumTS, TSX@ts-ignore / @ts-expect-error / @ts-nocheck directives.
Markdown Markdown documents.
Markdown Data URLssumMarkdownInline data: URLs (embedded images) in Markdown.
Activity Git history per file in the selected window (90 days by default). On whenever the folder is a Git repo.
Commitssumany fileNon-merge commits that touched the file in the activity window, following renames. Frequent change in complex code is where refactoring pays off.
Churnsumany fileLines added plus removed by those commits. Kept apart from commit count: one bulk rewrite churns a lot in a single commit.
Findings Lint and type-check results: the project's own tsc and eslint when it has them, otherwise srcly's bundled ruff and TS rules. No setup.
FindingssumTS/JS, TSX/JSX, PythonEverything the checkers reported for the file: the project's tsc and eslint, or srcly's ruff and TS rules. The code viewer lists each one with its rule and tool.
ErrorssumTS/JS, TSX/JSX, PythonFindings the checker calls errors: type errors, eslint errors, syntax errors and undefined names. Warnings aren't counted.
Data flow Render-path evidence from the TypeScript checker, after `srcly report --dataflow`: dead `??` guards, repeated forks and the worst value path in each TS/TSX file.
Impossible DefensessumTS, TSX?? and ?. whose guarded value the TypeScript types say is never null or undefined, so the fallback never runs. Only a type checker can prove this.
Repeated ForkssumTS, TSXComponents that test the same discriminant at several sibling branch sites (ternaries, &&, Solid <Show> and <Match>): each wants one sub-component per branch.
Prop RelaymaxTS, TSXThe most component boundaries a value crosses on its way to one of the file's render sinks.
Shape ChangesmaxTS, TSXThe most representation-only steps (alias, object pack, spread) on one of the file's render paths.
Path DepthmaxTS, TSXThe most steps from a source (prop, signal, local) to one of the file's JSX sinks.
Value Fan-OutmaxTS, TSXThe most render sinks that one of the file's sink sources also feeds. Wide reach is a fact, not a fault.
Detail Counts that describe code without saying it needs work: shown and colorable, never ranked.
Function Length (avg)averageTS/JS, TSX/JSX, Python, other codeMean function length in LOC; folders weight by function count. Detail: the M7 pilot's queues were tests, markup and one-function files.
TODOssumTS/JS, TSX/JSX, PythonTODO/FIXME-style comments.
Narrated CodesumTS/JS, TSX/JSX, PythonComment noise part: functions (or a whole file) with more comment lines than code lines and 10+ code lines.
Oversized DocblockssumTS/JS, TSX/JSX, PythonComment noise part: docblocks or docstrings of 8+ lines that are over 1.5x their function's code lines.
Commented-out CodesumTS/JS, TSX/JSX, PythonComment noise part: runs of 3+ line comments that parse as code.
Comment LinessumTS/JS, TSX/JSX, PythonComment lines.
FunctionssumTS/JS, TSX/JSX, Python, other codeExecutable functions at any depth (methods, nested functions, arrows).
ClassessumTS/JS, TSX/JSX, PythonClass declarations.
TS ImportssumTS, TSXDistinct import sources.
Types/InterfacessumTS, TSXType and interface declarations.
ExportssumTS, TSXExport declarations.
Python ImportssumPythonImport statements.
Filessumany fileFiles a node represents.

Languages and analyzers

Srcly picks an analyzer by file extension. Each file runs in a worker process with a hard timeout, so one bad file can't stop the scan. Git-ignored files and folders such as node_modules and dist are skipped.

FilesAnalyzerWhat it adds
TypeScript, TSX, JavaScript, JSXtree-sitter (JS parses with the TSX grammar)Functions and nested scopes, complexity, cognitive complexity, nesting, comment noise, React and Solid components, TS escapes
Pythontree-sitterFunctions, classes and nested scopes, complexity, cognitive complexity, nesting, comment noise
CSS, SCSStree-sitterEach rule and at-rule block as a scope
Markdowntree-sitterHeading sections, code blocks and block quotes as scopes, data URL count
Jupyter notebooksSrcly's notebook readerEach cell as a scope; LOC counts cell source, never outputs
Go, Java, C, C++, C#, PHP and the rest Lizard readsLizardFunctions, complexity, parameters
YAML, shell, HTML and other textline count onlyLOC and size; other metrics are N/A

Findings checkers

Checkers run in the background beside the scan, with no setup. A checker that is missing, fails or times out leaves its files N/A with the reason. Findings guide

tscThe project's own tsc --noEmit for each tsconfig, when node_modules/.bin has it
eslintThe project's eslint and its config, when it has both
ruffBundled with Srcly. Uses the project's ruff config, or bug-finding rules (E9, E722, F, B, PLE) labelled "srcly defaults"
srcly TS rulesTS files no project tool covers: explicit any, @ts-ignore without a reason, @ts-nocheck, chains of non-null assertions
srcly reachabilityUnreachable files and unused exports, walking imports from detected entries
srcly Solid rules, await-in-loopSolid cleanups returned from onMount or createEffect, and await inside a loop
ast-grepYour own YAML rules in .srcly/rules/

Configuration

Most projects need none. Two files at the Git root change what Srcly checks. Configuration guide

# srcly.toml: extra entry points for reachability
[reachability]
entries = ["app/scripts/**/*.ts"]

# .srcly/rules/*.yml: ast-grep rules reported beside tsc, eslint and ruff
SRCLY_CACHE_DIRWhere scans are saved. Default: ~/Library/Caches/srcly on macOS, ~/.cache/srcly on Linux, %LOCALAPPDATA%\srcly\Cache on Windows
SRCLY_NODEThe Node.js 18+ binary for data flow. Default: node on PATH
SRCLY_FINDINGS_TIMEOUTSeconds each checker may run (default 120 for tsc and eslint, 60 for the rest)
SRCLY_DATAFLOW_TIMEOUTOverrides every data-flow request timeout
SRCLY_AST_GREPThe ast-grep binary, ahead of the project's and PATH
built/

How I built it

I started Srcly in 2025 because I wanted to look at a codebase as a whole: where the code is, how complex it is, how often it changes, and how the pieces connect. A file list can't show that. A map can.

It is a FastAPI server and a SolidJS client. The scan runs Lizard for broad language coverage, and tree-sitter analyzers where I want more than a function count. Everything lands in one tree of folders, files, functions and scopes, and the metrics roll up that tree so any level can be sorted, colored and ranked. The data-flow engine is TypeScript, so it runs as a Node process that starts only when you open that view.

A few things I learned on the way:

  • A measured 0 and "not measured" are different answers. If a missing value shows as 0, code where nothing ran looks clean. So N/A is its own state everywhere: hatched on the map, named in reports, and counted as lost coverage in compare.
  • Show the lines behind a number. The overlay that marks them exposed a nesting bug that had inflated hotspot scores for long else if chains.
  • The dependency graph took six rounds of before-and-after screenshots to read well. I tried ELK for layout and dropped it, because I couldn't steer its packing and edge bundling. Srcly now uses its own grid and router, and boxes never move after layout.

The longer story is on the Srcly project page , with posts on the dependency graph, the metric overlay and compare.

How Srcly fits togetherThe uvx srcly command starts a FastAPI server. A scan runs Lizard and tree-sitter analyzers in worker processes, builds one tree with rolled-up metrics, and saves it in the user cache. Checkers run beside the scan. The SolidJS app and the headless commands read the same scan. A Node data-flow engine starts only when the data-flow view needs it.uvx srclyopens the appin your browsersrcly report …explain, hotspots,compare, fix,check, scanFastAPI serverScanwalk files, skip ignoredLizard + tree-sitter,one worker per fileTree + rollupsfolders › files › scopesCheckerstsc, eslint, ruff, own rulesSolidJS apptreemap, graph,2×2, compareUser cacheone scan per repo,until a file changesData-flow engineTypeScript on Node 18+,started on first use
One scan, cached per repository, feeds the browser app and the headless commands. The Node engine starts only for data flow.
Screenshot
100%