# Srcly documentation All guides and the metric reference, from https://byronwall.github.io/srcly/. Version 1.12.0. --- Source: https://byronwall.github.io/srcly/docs/overview/ # Understand a codebase with Srcly Srcly helps you move from a broad view of a repository to the exact code behind a signal. It runs on your machine, maps folders, files, functions, and nested scopes, then links metrics and selected checker results to source. You can explore in the browser or create scoped reports for a terminal, an agent, or CI. - **Discover Srcly:** [Product tour](https://byronwall.github.io/srcly/docs/tour/) and [Design decisions](https://byronwall.github.io/srcly/docs/design/). - **Use Srcly:** [Get started](https://byronwall.github.io/srcly/docs/get-started/) and [Reports](https://byronwall.github.io/srcly/docs/reports/). ![Srcly showing a codebase in its treemap view](https://byronwall.github.io/srcly/screenshots/treemap.jpg) ## Choose your path ### If you want to try Srcly Start with [Get started](https://byronwall.github.io/srcly/docs/get-started/). Launch the app, analyze a repository, and complete one short review: choose a metric, inspect a high or unexpected value, and check the source behind it. Then follow [Explore the views](https://byronwall.github.io/srcly/docs/explore/) to compare the treemap, explorer, Hot Spots, 2×2, and graph views. ### If you want to understand the product Read the [Product tour](https://byronwall.github.io/srcly/docs/tour/) for the main workflow and the [Design decisions](https://byronwall.github.io/srcly/docs/design/) for the choices that shape it. Srcly combines a visual map for human navigation with CLI reports for repeatable review. It treats unavailable evidence as unavailable, and keeps import relationships distinct from modeled value flow. ### If you are reviewing code Use [Metrics](https://byronwall.github.io/srcly/docs/metrics/) to learn what a value measures and how a folder value is aggregated. Use [Findings](https://byronwall.github.io/srcly/docs/findings/) to check which tools ran and what they reported. Use [Data-flow analysis](https://byronwall.github.io/srcly/docs/data-flow/) when you need to trace a modeled value through supported code. Rankings and traces help direct review; they do not establish that code is defective or safe. ### If you are automating a review Start with [Reports for agents and CI](https://byronwall.github.io/srcly/docs/reports/), then use the [Command-line reference](https://byronwall.github.io/srcly/docs/cli/) for flags. A report includes Markdown and machine-readable artifacts. `explain` lets you investigate a repository, folder, file, or symbol without loading the full tree into your prompt. Read the analysis and coverage information before acting on results. ## What Srcly does Run `uvx srcly` from a repository to open the local app. The treemap gives a spatial overview: area represents lines of code, while color represents the selected metric. The explorer, Hot Spots, and 2×2 views offer other ways to sort or compare the same scan. Select a file or scope to open source and supporting evidence. The scan uses Lizard for broad source coverage and language-aware analyzers for richer signals where supported. Metrics vary by language and node. A metric can be zero, or it can be unavailable because it does not apply or could not be measured. Srcly keeps these states separate and reports reasons where available. For a repeatable terminal workflow, run: ```bash uvx srcly report . --out .srcly uvx srcly explain . --at src ``` The report gives you an overview and artifacts. `explain` narrows the next question to a folder, file, or symbol. Both commands share the analysis cache. See [Reports](https://byronwall.github.io/srcly/docs/reports/) for artifact meanings and [CLI](https://byronwall.github.io/srcly/docs/cli/) for supported scopes and options. ## What Srcly does not claim A large file is not automatically a problem. Complexity is not a quality score. A checker finding is not a confirmed defect. An empty or partial data-flow result does not prove that a value cannot reach a destination. Use each signal to decide where to inspect, then verify the claim against source and the tools your project trusts. Data-flow analysis is optional and requires Node.js 18 or newer. Without it, the rest of Srcly remains usable and the unavailable result has a reason. Import graphs and data-flow graphs answer different questions; see [Design decisions](https://byronwall.github.io/srcly/docs/design/) for why they stay distinct. ## Continue - [Get started](https://byronwall.github.io/srcly/docs/get-started/) — launch Srcly and complete your first review. - [Product tour](https://byronwall.github.io/srcly/docs/tour/) — follow one workflow from map to source evidence. - [Explore](https://byronwall.github.io/srcly/docs/explore/) — choose a view for a review question. - [Reports](https://byronwall.github.io/srcly/docs/reports/) — produce artifacts for agents and CI. - [Configuration](https://byronwall.github.io/srcly/docs/configuration/) — set roots, entries, optional checks, and environment variables. --- Source: https://byronwall.github.io/srcly/docs/tour/ # Product tour Srcly is designed for one practical loop: orient yourself in a codebase, choose a useful signal, inspect the code behind it, and decide what to do next. The browser keeps those steps connected. The CLI makes a similar investigation repeatable for scripts and coding agents. ![Srcly's treemap with a repository selection](https://byronwall.github.io/srcly/screenshots/treemap.jpg) ## 1. Start with the shape of the repository Run Srcly from a repository: ```bash uvx srcly ``` The app opens in your browser and serves the local repository through a local web server. Keep the terminal open while you work. Use the path bar to choose a repository, then select **Analyze**. The first scan reads files and reports progress. Unchanged analysis can be reused from the local cache on a later visit. The treemap provides the broad view. Folders contain files, and files can contain functions and nested scopes. Tile area represents lines of code; color represents the selected metric. Start by asking a specific question, such as “Which files have the highest complexity?” or “Where does this component concentrate its logic?” ## 2. Choose a signal that matches the question Choose a metric in the view controls. Complexity can help locate branching-heavy functions. LOC can show where code is concentrated. Component metrics can help inspect React or Solid component shape. Git activity can add historical context when repository history is available. Open Hot Spots when you want a ranked list, or use the 2×2 view to compare two supported metrics. A ranking is relative to its cohort and selected metric. A high value identifies a place to inspect; it does not diagnose a defect. For definitions and aggregation rules, see [Understand metrics](https://byronwall.github.io/srcly/docs/metrics/). ## 3. Inspect the source and its witness Select a file or function tile, or select its row in the explorer. Srcly opens the source with available metrics, findings, and line evidence. For an aggregated value, check which rule produced it. For maximum complexity, Srcly carries the function that sets the maximum as a witness. For a checker result, read the tool, rule, location, and message. ![Srcly's code inspector showing source and analysis evidence](https://byronwall.github.io/srcly/screenshots/code-inspector.jpg) Ask what the evidence supports. A complexity value describes branching structure. A checker finding reports what that checker detected under its configuration. Neither says whether a change is needed. Read the relevant code, then confirm a suspected issue with the project's tests or checker. ## 4. Follow a relationship when the question needs it Use the dependency graph to inspect TypeScript and TSX import relationships. It answers which modules import or use other modules. It is not a call graph and does not show where a particular runtime value goes. The graph also has **Symbols** mode for symbol-level references. It centers one symbol, shows referrers on the left and referenced symbols on the right, and frames the focus by file and class. Press `/` to find a symbol. Select a box to inspect references and source lines. Shift-click a box or press `E` to open that symbol's hop in place. Kind filters and the Tests control help narrow the view. These are static references; check the displayed resolution and source locations before treating a link as exact. ![Symbols graph for NotePage in the included symbol-graph example](https://byronwall.github.io/srcly/screenshots/symbols.jpg) Use Data flow when you have a supported route or symbol and want to follow modeled values, function effects, or route handling. Select a file or function, open Data flow, and choose an anchor available for that code. Inspect graph items and their source locations. For a route or value path, read the outcome and any assumptions or stops before drawing a conclusion. The bundled engine requires Node.js 18 or newer. See [Data-flow analysis](https://byronwall.github.io/srcly/docs/data-flow/) for language limits and outcome meanings. ![Partial route trace for /notes/[id] in Srcly's included symbol-graph example](https://byronwall.github.io/srcly/screenshots/data-flow.jpg) ## 5. Review what a session changed After a coding session, select **Changes** and pick **This branch**, **24 hours** or **7 days**. The map shows only the functions, sections and line ranges that the window edited, grouped by folder and file. Tile area is changed lines, so one edited handler in a 2,000-line file gets the footprint of that handler. The panel lists what to review first by plain rules: chunks that were already complex and changed, and chunks that crossed the complexity line. Select a chunk to see its before → after values and the commits that touched it, then open its diff. ![The Changes view of Srcly's own repository, with parseLocation selected](https://byronwall.github.io/srcly/screenshots/changes.jpg) Switch **Touched** to **Net** to drop work that was tried and put back. See [Review changes](https://byronwall.github.io/srcly/docs/changes/) for the window and chunk rules. ## 6. Repeat the investigation in a terminal If you need a saved review or want to pass evidence to an agent, run: ```bash uvx srcly report . --out .srcly uvx srcly explain . --at path/to/file.ts ``` Read `report.md` first, then follow its suggested scope into `explain`. The generated `Analysis:` line records whether the scan was reused or fresh, the Git revision and working-tree state, checker coverage, and analysis failures. It helps distinguish a measured result from a gap in coverage. See [Reports](https://byronwall.github.io/srcly/docs/reports/) for artifact-to-question mapping. ## Make the next decision The first review should end with a decision, not just a list of high values. You might verify a finding, add a missing checker, adjust a TypeScript entry glob, or defer a refactor because the evidence is weak. Keep the signal and its coverage with that decision. If a result is unavailable, use its reason to decide whether to configure a tool or accept the gap. Start with [Get started](https://byronwall.github.io/srcly/docs/get-started/) for installation details. Use [Explore](https://byronwall.github.io/srcly/docs/explore/) to compare the views, or [Findings](https://byronwall.github.io/srcly/docs/findings/) to understand checker coverage. --- Source: https://byronwall.github.io/srcly/docs/design/ # Design decisions Srcly combines a visual code map with source-level evidence and repeatable terminal output. Its design follows a simple review path: orient, select a question, inspect the evidence, and decide what to verify. This page explains the choices behind that path and where they set limits. ## Two evidence trails At revision `653037aa`, Srcly scanned its own public `client/src` tree: 236 files and 33,823 LOC. Hot Spots ranks 235 measured files; `viewModel.ts::buildViewModel` leads at CCN 135. The inspector opens `App.tsx::openAt` with source and metrics. Together, these screens support a product choice: move from map to ranked candidate to source witness. They show how the review works, not a measured improvement. The [capture record](https://byronwall.github.io/srcly/screenshots/README.md) names the source and revision. ![Complexity-ranked Srcly files, led by viewModel.ts at CCN 135](https://byronwall.github.io/srcly/screenshots/hotspots.jpg) ![Srcly's code inspector showing viewModel.ts and the buildViewModel function](https://byronwall.github.io/srcly/screenshots/code-inspector.jpg) A separate report on the included `engine/examples/solid-route` fixture at the same revision, `653037aa`, returns five findings with `--limit 5` across 10 code files. The first row points to `src/data/records.ts::isRecordItem` (complexity 8, 24 LOC). Inspect its branches and nearby tests; change it only if a test-backed, behavior-preserving simplification is clear. The [fixture source](https://github.com/byronwall/srcly/blob/main/engine/examples/solid-route/src/data/records.ts) is a different corpus from the client screenshots. Reproduce the report with [Reports](https://byronwall.github.io/srcly/docs/reports/). This case gives the CLI a matching role: create a bounded queue, name its evidence, and leave the final decision with the reviewer. The [agent-reporting plan](https://github.com/byronwall/srcly/blob/main/docs/intent/agent-reporting/implementation-plan.md) describes the emphasis on freshness, provenance, and coverage. ## Start with a local view of the codebase Srcly runs as a local command and opens a browser app served from the local process. It reads the repository you choose, follows Git ignore rules, skips common generated and dependency directories, and caches analysis in the user's cache directory. The map provides orientation; the code viewer connects a selected node to its source. The CLI saves a report for terminal or agent review. Both workflows expose evidence and its coverage. ## Keep the tree granular enough to inspect The analysis tree mirrors folders and files, then adds detected functions and nested scopes. Leftover lines inside parent scopes become body fragments, so nested scopes do not double-count area. Folder and file values roll up according to each metric's rule. The [code map](https://github.com/byronwall/srcly/blob/main/docs/CODE_MAP.md) points to the tree builder and aggregation code. Granularity creates a navigation trade-off. A repository-wide tile is useful for orientation; a function tile is useful for inspection. Linked views let you move between those scales. See [Explore](https://byronwall.github.io/srcly/docs/explore/) and [Metrics](https://byronwall.github.io/srcly/docs/metrics/). ## Preserve unavailable evidence as unavailable An unavailable metric is not zero. A missing, failed, or timed-out checker did not report a clean result. A TypeScript-only metric does not apply to another language. Srcly keeps these cases separate and gives a reason where it has one. Comparisons separate coverage changes from measured deltas. This prevents missing analysis from looking like improvement. Rankings can use different evidence for different files, so check coverage before comparing them. Configure a missing checker or accept the gap. See [Metrics](https://byronwall.github.io/srcly/docs/metrics/), [Findings](https://byronwall.github.io/srcly/docs/findings/), and the [agent-reporting plan](https://github.com/byronwall/srcly/blob/main/docs/intent/agent-reporting/implementation-plan.md) for freshness and provenance decisions. ## Use the right relationship for the question The TypeScript and TSX dependency graph shows imports. Data flow traces modeled values, function effects, or supported routes. An import edge does not prove value movement; a data-flow edge is not a general runtime trace. The [engine design](https://github.com/byronwall/srcly/blob/main/docs/dataflow-engine.md) and [logic visibility brief](https://github.com/byronwall/srcly/blob/0bfb05ba/docs/intent/dataflow-logic-visibility/intent-brief.md) explain the boundary. Symbols mode shows which functions, classes, fields, or types reference a symbol. Edges carry a resolution label: exact, typed, or name-based. This gives more detail than imports without claiming value flow. See the [symbol graph brief](https://github.com/byronwall/srcly/blob/0bfb05ba/docs/intent/symbol-graph/intent-brief.md). Data flow is optional. It runs through a bundled engine that requires Node.js 18 or newer. The engine's results carry outcomes and provenance, including partial, assumed, stale, and unavailable states. The rest of the scan does not depend on that engine. This keeps the base map usable when the optional analysis cannot run. Read [Data-flow analysis](https://byronwall.github.io/srcly/docs/data-flow/) before relying on a trace. ## Keep review signals separate from decisions Metrics describe code structure; findings report checker output; Git activity describes history when available. A profile or Hot Spots ranking helps choose where to look, but it does not prove quality, safety, or maintainability. Review the source and confirm what matters for the project. The same rule shapes the agent workflow. Reports include structured artifacts, metric definitions, checker coverage, and an analysis provenance line. Scoped `explain` output keeps the next question bounded. The artifacts are evidence for review, not instructions to refactor blindly. ## What these choices cost Local analysis means the user runs the command and keeps the server process open while using the app. Language-specific measurements have different coverage. Data-flow analysis needs Node and may stop at unsupported constructs. The visual map is a navigation aid, not a substitute for tests, type checks, or runtime behavior. Reports can be reused from cache, so the `Analysis:` line matters when deciding whether to refresh. Start with [Get started](https://byronwall.github.io/srcly/docs/get-started/), then use [Reports](https://byronwall.github.io/srcly/docs/reports/) to check provenance or [Configuration](https://byronwall.github.io/srcly/docs/configuration/) to address supported setup gaps. --- Source: https://byronwall.github.io/srcly/docs/get-started/ # Get started Run Srcly on a repository, choose one review question, and follow its evidence into the source. This guide takes you from installation to a first browser review and a saved terminal report. ## 1. Launch Srcly Install [uv](https://docs.astral.sh/uv/) if you do not have it. Then run Srcly without a global install: ```bash uvx srcly ``` The command uses the enclosing Git repository as its initial root. Outside a repository, it uses the current directory. Pass a path to select another root: ```bash uvx srcly /path/to/repository ``` The packaged release requires Python 3.13 or newer. The code you analyze can use another Python version. Srcly starts a local web server and opens the app in your browser. The default bind address is `127.0.0.1`, and Srcly selects an available port. Keep the terminal open while you use the app. Press `Ctrl+C` in that terminal to stop it. ![The Srcly app showing a repository treemap](https://byronwall.github.io/srcly/screenshots/treemap.jpg) ## 2. Scan a repository When the app opens, review the suggested path or enter another directory in the path bar. Select **Analyze**. Srcly shows scan progress while it reads files. In a Git repository, file discovery includes tracked files and nonignored untracked files. Git-ignored and common generated or dependency paths are excluded. If you want a narrower scan, enter a subdirectory as the root. The first scan can take longer than a later visit because the local cache can reuse unchanged analysis. The cache is stored in your user cache directory, not in the analyzed repository. A file change invalidates the cached analysis for that root. In a terminal workflow, use `--refresh` on commands that support it when you need to rerun analysis and checks; see [Reports](https://byronwall.github.io/srcly/docs/reports/). ## 3. Complete a first review Start with a question. For example: “Which function has the highest complexity in this folder?” 1. Start in the treemap. Area represents lines of code; color represents the selected metric. 2. Choose Complexity in the metric controls. A darker or stronger color indicates more of the selected metric under its legend. 3. Open Hot Spots or sort the explorer by complexity to find a high-ranked function or file. 4. Select the row or tile. Read the value, metric witness, and source lines in the code viewer. 5. Check whether the measurement applies and whether a checker finding or dependency adds useful context. 6. Confirm a suspected problem against the source and your project's own tools. ![Srcly's source inspector with metrics and findings](https://byronwall.github.io/srcly/screenshots/code-inspector.jpg) The measurement helps you choose where to look. It does not say that code is defective or must be changed. A folder complexity value is the maximum among its functions, not the sum. A checker result depends on that tool's rules and coverage. Read [Explore](https://byronwall.github.io/srcly/docs/explore/) and [Metrics](https://byronwall.github.io/srcly/docs/metrics/) for more. ## 4. Save a report For a terminal workflow, create a report: ```bash uvx srcly report . --out .srcly ``` This writes `report.md` and structured JSON files under `.srcly/`. Read `report.md` first. It includes a scan summary, ranked findings, metric hotspots, and coverage information. The `Analysis:` line records whether the scan was reused or fresh, the Git revision and uncommitted state, checker coverage, and analysis failures. Use that information to decide whether the result is current enough for your review. To inspect a narrower scope, run: ```bash uvx srcly explain . --at src uvx srcly explain . --at "src/app.tsx::App" ``` The first command explains a folder; the second explains a symbol. Use a path relative to the analyzed root. The printed `Start at` location can be copied into `--at` when you need to investigate a particular row. See [Reports](https://byronwall.github.io/srcly/docs/reports/) for output details and [CLI](https://byronwall.github.io/srcly/docs/cli/) for the full command list. ## 5. Decide what to do next If a result is unavailable, read its reason. You may need a project checker, a TypeScript reachability entry, Git history, or Node.js for optional data flow. If a result is measured, inspect the code and decide whether it merits a change, a test, or no action. Srcly is a review aid, not an automatic quality verdict. Metrics that do not apply or could not be measured appear as N/A, never as zero. Data-flow analysis requires Node.js 18 or newer and supports TypeScript, JavaScript, and Python roots. Without Node, the base scan remains available. See [Findings](https://byronwall.github.io/srcly/docs/findings/) for checker coverage and [Data flow](https://byronwall.github.io/srcly/docs/data-flow/) for trace outcomes. --- Source: https://byronwall.github.io/srcly/docs/explore/ # Explore a codebase Use Srcly's linked views to move from a broad signal to the source behind it. This guide helps you choose a view, inspect its evidence, and decide whether the result needs follow-up. ![Srcly's treemap view of a scanned repository](https://byronwall.github.io/srcly/screenshots/treemap.jpg) ## Choose the view for your question | Question | View | What to inspect next | | --- | --- | --- | | Where is code concentrated? | Treemap | Open the largest folder or file, then inspect its children. | | Which files or functions rank highest for one signal? | Hot Spots | Check the metric, cohort, value, and witness. | | Which items have two signals at once? | 2×2 | Read the axis names and cut-offs; select points to inspect members. | | What imports this TypeScript or TSX module? | Dependency graph | Follow direct import relationships and their source locations. | | How does a modeled value move through supported code? | Data flow | Read the outcome, assumptions, and stop points. | These views are not interchangeable. The dependency graph describes imports; it does not establish runtime calls or value movement. Data flow traces selected modeled relations and has different language coverage. See [Data-flow analysis](https://byronwall.github.io/srcly/docs/data-flow/) before interpreting a trace. ### Symbols mode Switch the graph from Imports to **Symbols** to inspect references around one symbol. The focus appears in the middle; referrers appear on the left and referenced symbols on the right, grouped by their source files and classes. Press `/` to search symbols. Select a box to read its reference lines in the inspector. Shift-click a box or press `E` to open its own hop in place. Use the kind chips and Tests control to narrow the graph. The edge's resolution label matters: exact, typed, and name-based matches are different levels of evidence. Follow an edge into source before relying on it. ![Symbols graph for NotePage in the included symbol-graph example](https://byronwall.github.io/srcly/screenshots/symbols.jpg) ## Read the treemap Each rectangle represents a folder, file, function, or code fragment. Area represents lines of code (LOC). Choose a metric to color tiles and read its legend. Open a folder or file to focus the map. Use the path and file-type controls to narrow the visible scope. Hiding a path changes the view; it does not alter source files or the scan. A large tile is not automatically a problem. It may reflect a legitimate module or generated content that should be excluded. Use the tile to choose where to inspect, then confirm its classification and contents in the explorer or code viewer. ## Rank candidates with Hot Spots Hot Spots ranks files or functions for one selected metric and cohort. Select a metric, then choose whether to rank files or functions where the control is available. The list orders measured values worst first and presents a witness when the value is an aggregate. N/A results are grouped separately because they cannot be ranked as measured values. Open a row to focus the corresponding source. Check the metric definition and cohort before comparing two entries. A file rank compares files; a function rank compares functions. A high value means “inspect this,” not “change this.” The [Metrics guide](https://byronwall.github.io/srcly/docs/metrics/) explains aggregation and availability. ## Compare two signals in the 2×2 view The 2×2 view places files, functions, or supported components on two metric axes. Presets include activity, blast radius, component weight, comment noise, and findings. Choose the preset and cohort, then read the axis labels. Drag the cut-offs to explore how different thresholds change quadrant membership. Select a group or point to inspect its members. ![Activity 2×2 for Srcly's own repository, with the Hot mess quadrant selected](https://byronwall.github.io/srcly/screenshots/quadrant.jpg) The cut-offs help you ask a question; they are not universal risk boundaries. A preset can omit unavailable points or show that it has no usable data. Read the selected metrics, cohort, and cut-offs before comparing groups. A point's position is not an overall quality grade. ## Inspect source and relationships Select a file or function from a tile or row to open the code viewer. Review the source, metric values, checker findings, and line evidence together. For a folder maximum, follow its witness function. For a checker finding, note the rule and tool that produced it. Some file classes, such as tests, docs, fixtures, generated, or vendored files, may be counted but left out of a default findings rank; see [Findings](https://byronwall.github.io/srcly/docs/findings/). Use the dependency graph to understand direct TypeScript and TSX imports, including nearby path aliases and external packages when available. Use Data flow for modeled routes, values, or function effects. A missing edge is not proof that no relationship exists. The dependency graph may not cover other languages; data flow can stop at unsupported constructs. See [Configuration](https://byronwall.github.io/srcly/docs/configuration/) for setup limits. ## A practical review sequence 1. State the question before choosing a metric. 2. Choose the matching view and check its legend, cohort, or axes. 3. Select a high or unexpected item and open its source. 4. Read the metric definition, witness, checker identity, and coverage status. 5. Confirm a suspected issue with source, tests, or the project's checker. 6. Record the decision and any evidence gap. This sequence avoids treating size, complexity, or a static-analysis message as proof of a bug. If you need a saved investigation, use `uvx srcly report . --out .srcly`, then narrow it with `uvx srcly explain . --at path/to/file`. The [Reports guide](https://byronwall.github.io/srcly/docs/reports/) maps artifacts to questions. --- Source: https://byronwall.github.io/srcly/docs/changes/ # Review changes The **Changes** view shows the code a window of Git history edited. Use it after a coding session to answer three questions: where did the work happen, what changed in the shape of the code, and what should you review first. A window changes which code is visible. It does not recolor a map of the whole repository. ![The Changes view of Srcly's own repository, with parseLocation selected](https://byronwall.github.io/srcly/screenshots/changes.jpg) ## Open the view 1. Analyze a folder inside a Git repository. 2. Select **Changes** beside Treemap, Graph and 2×2. 3. Pick a window: **This branch**, **24 hours**, **7 days**, or **Custom**. 4. Select a chunk on the map or in the review lists, then select **Open diff**. The status line under the toolbar shows the resolved base and head, the number of commits, the time limits with the time zone, and any notes. Read it first: it tells you exactly which history you are looking at. The view reads the checked-out branch. Staged and unstaged edits are included as one **Working tree** entry after the last commit. To read other revisions, use **Custom** and enter a base and a head (a branch, tag or sha), or a time range. ## Windows - **This branch** compares the branch with the commit where it left the default branch (the merge base). On the default branch itself, the base is the upstream tip. When the two are equal, the window is empty and a note says so. - **24 hours** and **7 days** read the commits whose committer date falls in that time, counted back from now. The base is the first parent of the oldest commit in the window. ### Off the default branch When the checkout is on another branch, or on the default branch but behind its upstream, the status row names the branch and how far it is behind and ahead of the default branch (`origin/main` when it exists and is not behind local `main`). A time window then gets a **History** toggle: **Branch** reads the checked-out branch, and **origin/main** reads the default branch's commits. Srcly reads Git objects only. It never checks out a branch or touches the working tree, so main history leaves out uncommitted edits. When the branch has no commits in a time window, the window reads the default branch and a note says so. Pick **Branch** to go back. When a window on the branch is empty and the default branch has commits in the same time (the last 7 days for **This branch**), the empty view offers a button that shows them. **This branch** always compares the branch with its merge base. - **Custom** takes two revisions, a time range, or both. Srcly reads one history: the first-parent log of the branch. A merge commit counts once, as its diff against its first parent, so merged work is never counted twice and other branches never mix in. A merge of the default branch into your branch is listed but not read, because those are upstream changes. A note names it. When the base is older than such a merge, "before" is the base with that merge's changes applied, so upstream work never reads as yours. If the merge overlaps your own earlier edits, the base stays as it is and a note says so. On the default branch itself, no merge is an upstream merge. A window keeps its newest 200 commits. A time window reads at most the newest 5,000 commits to find its start, and a note says when that cuts it short. In a shallow clone, Srcly never reads past the oldest commit the clone holds, and a note says so. Binary files and files that Srcly's ignore rules skip (lockfiles, `.json`, images) are left out, and a note gives their count. ## Touched and Net **Touched** is the default. It shows every chunk that any commit in the window changed. **Net** compares the base snapshot with the head snapshot. The two differ when work was tried and put back. A function that a commit changed and a later commit restored is **reverted** in Touched: it is drawn with dots and a ↺ mark. In Net it is gone, because the base and the head are equal. Use Touched to see where the session went. Use Net to review what will land. ## What a chunk is A chunk is the unit the map draws. Srcly parses each changed file on both sides with the same analyzer the scan uses, then groups hunks this way: - A hunk belongs to the innermost named function, method or class that holds its lines. A callback or object literal with no name belongs to the named scope around it. Nested names are qualified, such as `Class.method`. - Comment and decorator lines right above a function or method belong to it, not to the class around it. - Hunks outside every named scope form one file-level chunk for that file. - In Markdown, a hunk belongs to its nearest heading section. - In a file no analyzer reads (YAML, CSS, shell), nearby hunks form one line-range chunk. - A generated or vendored file is one chunk and is not analyzed. So is an empty file that was added or deleted. - A file that does not parse at the base or the head gets no symbols. Its chunks say **Syntax error**, and a note names the file. Srcly never invents a symbol. A chunk with no analyzer says **not measured**, never 0. So do heading and file-level chunks: no code metric applies to them. Head and base chunks pair by path and name. When Git reports a renamed file, they pair by name across the two paths. Two scopes with the same name in one file pair by body: identical first, then closest. A symbol that left one file and appeared in another with a near-identical body is **moved**. A weaker guess is labeled **uncertain**, and so is a Markdown heading that was reworded above the same text. A file added in the window has no base, even when a renamed file held that path before. A line-number overlap alone is never a match. A pure rename with an unchanged body has equal before and after values: it is not an improvement or a regression. ## Read the map **Only edits** packs the edited chunks together, grouped by folder and then file. Tile area is changed lines, with a floor so a one-line edit can still be selected. A folder label reads like `5 edited / 43 files · mostly tests`. Select a folder or file name to zoom; use the breadcrumbs to go back up. The chevron folds a group into one tile without moving its neighbours. In a long window, each file keeps its largest chunks open and pools the smaller ones into one **N more** tile. Select a pool to open it. A chunk you select from a list leaves its pool. **In repo** returns to the familiar file map, sized by file LOC. Untouched files are muted, and each edited chunk is a band at its lines in its file. The selection stays when you switch. The **Color** menu picks a metric and **Now** (the value at head) or **Δ** (the change in the window). Delta uses a diverging scale: blue fell, orange rose. Added, deleted, moved, reverted and not-measured chunks each have their own fill and mark. A color change keeps the layout and the selection. ## Review first The panel lists two review buckets. They are plain rules, not a score: - **Already complex and changed**: the chunk had cyclomatic complexity of 10 or more at base, and its body changed. - **New hotspot**: the chunk crossed the line in the window. Its complexity is 10 or more at head, and at base it was below 10 or the chunk did not exist. A chunk that was already at 10 or more is only in the first bucket. Test, docs, generated and vendored files get no bucket. **All edits** lists every chunk, most lines churned first, with status and file-class filters. ## Inspect a chunk The inspector shows the chunk's status, where it is, and each metric as base → head. Metrics that did not change fold into one line. **Touches** places one mark per commit that changed the chunk on the window's timeline, with churned lines against net lines. Six edits to one handler and one edit each to six handlers are different stories, and this is where you see which one you have. **Open diff** shows only the chunk's own lines. Changed lines of a nested named scope are in that scope's diff, not in its parent's. A symbol's diff compares its body on the two sides, so a moved symbol shows only what changed in it. Select a touch mark to see that one commit's diff. ## Step through commits The commit rail under the map shows the window's commits on a compressed time axis, sized by lines changed. Commits that touched the selected chunk are highlighted. Select a commit to dim every chunk it did not change. With a commit selected, **Open diff** shows that commit's hunk. Select **All** or the commit again to clear it. The left and right arrow keys step through commits. ## From the command line `srcly changes` prints the same result as Markdown: the resolved selection, the review buckets, then the chunks grouped by folder with before → after complexity. ```bash uvx srcly changes uvx srcly changes . --window 7d --mode net uvx srcly changes . --window custom --base main --head my-branch --json ``` See [Command line](https://byronwall.github.io/srcly/docs/cli/) for every flag. ## What it does not claim The view shows commits and local edits. It does not show who read a file or which tool made an edit, and it never credits an agent with a read or an edit. A complexity change is a structural signal to inspect, not a verdict on the change. --- Source: https://byronwall.github.io/srcly/docs/metrics/ # Understand metrics Use metrics to decide where to inspect, then check the code that produced the value. This guide explains common measurements, how folder values work, and what to do when a metric is unavailable. ## Read a metric in context A metric has a scope and an aggregation rule. A function may have an exact measurement. A file or folder may sum values from children, take the maximum, or report an average. The UI and generated `metrics.schema.json` identify definitions and interpretation hints. Check those details before you compare two values. Common measurements include: | Metric | What it describes | How to use it | | --- | --- | --- | | LOC | Nonblank, noncomment lines of code | Find where code is concentrated; size alone is not a risk verdict. | | Complexity (CCN) | Branching paths in a function | Inspect the function that sets a file or folder maximum. | | Cognitive complexity | Branching and nesting effort under Sonar's rules | Compare functions with different nesting shapes. Available for TS, JS, and Python. | | Function length, nesting, parameters | Code shape | Use as context for a review question, not as quality scores. | | Component metrics | Detected React or Solid component structure | Inspect component LOC, hooks, effects, JSX depth, props, inline handlers, and conditionals. | | Comment noise | Selected comment patterns | Check the flagged lines; this heuristic is not a style verdict. | | Git activity | Commit count and churn in a selected history window | Add history to code structure when repository history is available. | Other metrics include file size, imports, exports, TODOs, type signals, and language-specific measures. The [reference table](https://byronwall.github.io/srcly/#reference) lists every metric with its rollup, languages, and definition, straight from Srcly's metric catalog. Detail metrics can provide context without being ranked as risk. See [Findings](https://byronwall.github.io/srcly/docs/findings/) for checker results, which are separate evidence. ## Example: a maximum with a witness Suppose three functions in a folder have CCN values 2, 4, and 8. The folder's complexity is 8 because the rule is maximum, not sum. Srcly names the function with CCN 8 as the witness. The value means “this is the most complex measured function in the folder”; it does not mean the folder has total complexity 8 or that the function is defective. This example is illustrative. Use the displayed witness and metric definition for your actual scan. The witness gives you a source location to inspect. If the file or folder has no measured function for a metric, the result may be N/A instead of a numeric value. ## Distinguish zero from N/A A measured zero is evidence that the metric applies and its measured value is zero. N/A means the metric does not apply, its analyzer did not measure it, or required data was unavailable. For example, component metrics do not apply to a file with no detected component. Git activity can be unavailable without suitable Git history. A checker metric can be unavailable when a required tool is missing or fails. Srcly preserves this difference in the UI, reports, and comparisons. If a value is N/A, look for its reason. Do not turn it into zero when ranking or comparing. If the metric is important to your review, use [Configuration](https://byronwall.github.io/srcly/docs/configuration/) to address supported setup gaps or accept that the scan cannot answer that question. ## Interpret comparisons carefully Folder values aggregate children by the metric's rule. Complexity is a maximum and names its witness; LOC is a sum; other metrics may use maximum, average, or count. A single file's metric can change because its code changed, because measurement coverage changed, or because the measured population differs. `compare` keeps a metric unavailable on one side as `null` and reports measurement coverage changes separately from numeric deltas. This prevents missing coverage from appearing as improvement. It also means two rows with similar values may have different evidence behind them. Read metric definitions, coverage, and witness before you draw a conclusion. ## Turn a signal into a review 1. State the question you want to answer. 2. Choose a metric whose definition matches that question. 3. Check the node type and aggregation rule. 4. Open the source or witness that contributed the value. 5. Confirm suspected problems with the source, tests, or the project's tools. Metrics help you compare and focus attention. They do not measure correctness, security, or maintainability as one objective score. For per-metric rankings, use [Explore](https://byronwall.github.io/srcly/docs/explore/); for the report schema and generated evidence, see [Reports](https://byronwall.github.io/srcly/docs/reports/). --- Source: https://byronwall.github.io/srcly/docs/findings/ # Findings and check coverage Findings bring selected checker results into Srcly's explorer, code viewer, and reports. Use them to find code worth reviewing, then confirm the issue with its source and tool. A finding is a triage signal, not a confirmed bug. ## Check coverage before reading the queue Srcly selects checks based on the files and tools it finds. Checks run independently and have time limits. Missing tools, failures, and timeouts leave measurements unavailable with a reason. They do not count as zero findings. Read the coverage summary in the report or the checker status in the app before treating the queue as complete. | Check | When Srcly runs it | What an unavailable result means | | --- | --- | --- | | TypeScript compiler (`tsc --noEmit`) | TypeScript project configuration and compiler are available | The project configuration or compiler was not available, or the run failed or timed out. | | ESLint | The project has ESLint and its configuration | ESLint was not detected, or its run failed or timed out. | | Ruff | Python files are present; Srcly ships Ruff | The run failed or timed out. Srcly uses project Ruff settings when present, otherwise labeled Srcly defaults. | | Srcly TypeScript rules | TS files are outside project checker coverage | A selected built-in pattern matched, or that rule set did not cover the file. | | Reachability and Solid rules | Supported TypeScript graph and patterns are available | Entry-point detection or language coverage may not match the project. Configure entries when needed. | | ast-grep rules | `.srcly/rules/` files exist and ast-grep is available | The optional binary or rule run is unavailable. | | Data-flow rules (`impossible-defense`, `repeated-fork`, `context-relay`, `broad-prop-bundle`) | You pass `--dataflow` to `report` or `compare`, and Node 18+ is available | The engine is missing, the root is not TypeScript, or the run failed. The reason is in `report.md`. | The exact checks vary by project. Srcly runs `tsc` per detected TypeScript project, expands solution configurations, runs ESLint when configured, and runs Ruff for Python. Its built-in TS checks include selected patterns such as explicit `any`, suppression directives without a reason, and non-null assertion chains when project tools do not cover those files. It also reports selected reachability, Solid, and await-in-loop signals. Optional ast-grep YAML rules can add project-specific checks. See [Configuration](https://byronwall.github.io/srcly/docs/configuration/) for setup. ## Read a finding When you open a finding, check these fields: | Field | Review question | | --- | --- | | Tool and rule | Which checker produced this result, and what pattern does the rule detect? | | Location | Where should you inspect the source? | | Message and evidence | What specific code caused the result? | | Coverage | Which files did this checker analyze, and which did it leave unavailable? | | Profile or rank | Why did this file appear in the queue, and which metric drove its position? | The report's findings queue uses a profile such as `general`, `frontend`, `backend`, `typescript`, `python`, or `docs`. A profile weights available risk-related metrics to suggest a review order. It does not replace the checker's diagnostic. Hot Spots ranks one selected metric. A queue score and a checker message are different kinds of evidence. ## Files outside the default queue The report classifies files as code, tests, docs, styles, fixtures, generated, vendored, config, or data based on their paths. It explains which classes were left out and why. This keeps a README, fixture, or generated file from becoming a refactor target by accident, while preserving the count and reason. Use `--include-class` when you intentionally want to rank one class. Example: in the included `solid-route` project at revision `653037aa`, the `frontend` profile reported five ranked findings. Its first row pointed to `src/data/records.ts::isRecordItem` with complexity 8 and 24 LOC. That is an example of a review starting point, not a claim that the function contains a defect. Inspect the named source and tests before deciding what to do. ## Improve coverage when the answer matters If a result is unavailable, use the stated reason to decide whether to install or configure the relevant checker. For TypeScript reachability, Srcly detects common entries from routes, package metadata, scripts, and configuration. If the app has an entry pattern Srcly does not detect, add it to `srcly.toml`: ```toml [reachability] entries = ["app/scripts/**/*.ts"] ``` Then rescan so the result reflects the new setup: ```bash uvx srcly report . --refresh --out .srcly ``` For a particular report run, check `Analysis:`. It names the scan state, Git HEAD, uncommitted files, checkers and their coverage, code files no checker covers, and files that failed analysis. If you need source-level review, use [Reports](https://byronwall.github.io/srcly/docs/reports/) to find the relevant artifact, then [Metrics](https://byronwall.github.io/srcly/docs/metrics/) for N/A and aggregation rules. --- Source: https://byronwall.github.io/srcly/docs/data-flow/ # Data-flow analysis Data flow traces how values move through supported source code. Use it to investigate where a request is handled, what a function does with an input, or where a value is written or returned. It is separate from the TypeScript and TSX import dependency graph. ![Partial route trace for /notes/[id] in Srcly's included symbol-graph example](https://byronwall.github.io/srcly/screenshots/data-flow.jpg) ## Open a trace 1. Analyze a supported repository in the app. 2. Select a file or function and switch to **Data flow**. 3. Choose an available anchor, such as a route, exported function, or file. 4. Select a graph item to inspect its source location and modeled relations. 5. Read the outcome and any assumptions, stops, or unavailable reason. Depending on the anchor and language, Srcly can show a route, value-flow trace, or function effects. A route graph may show where a route's values move; an anchor graph starts from a selected symbol. The exact view depends on available code facts and supported language constructs. ## Data-flow reports and findings For a repository summary or an agent workflow, add `--dataflow` to a report: ```bash uvx srcly report . --out .srcly --dataflow ``` The engine traces every render path in the TypeScript and TSX program, from a prop, signal, or local to the JSX that renders it. This takes minutes on a large app, so it runs only when you ask. It adds: - `dataflow.md`: ranked work packets with candidate edits, the risk queue and a stop recommendation, then the defensive ledger, repeated forks, prop relay, context relay, and fan-out. - Four finding rules in the Data flow section of `report.md`. `impossible-defense` is a `??` or `?.` whose guarded value the types say is never null or undefined. `repeated-fork` is a component that tests the same discriminant at several sibling branch sites, including Solid `` and ``. `context-relay` and `broad-prop-bundle` are a parent that reads a context hook and passes context-like props, or three or more plain props, to a child in the same feature. - Six metrics per TS/TSX file in the Data flow group: impossible defenses, repeated forks, prop relay, shape changes, path depth, and value fan-out. After the run, the app colors the treemap and marks the code viewer with them while the files stay unchanged. `uvx srcly compare --dataflow` runs the engine on both sides and diffs these metrics. ## Requirements and language support The bundled engine requires Node.js 18 or newer on `PATH`. Set `SRCLY_NODE` to choose another executable. The engine analyzes TypeScript, JavaScript, and Python roots. TypeScript and JavaScript projects are detected from project configuration or source files; loose files can also be analyzed. Python projects are detected from Python project files or `.py` files. Python analysis has a different feature set from TypeScript. Python routes can open their handler in anchor mode; the TypeScript route graph does not apply to Python. Without project type configuration, some guarantees about null values are unavailable. Unsupported constructs and incomplete evidence can stop a trace early. If Node or the engine is unavailable, Srcly names the reason and leaves the rest of the scan available. An unavailable trace is not an empty proof. See [Configuration](https://byronwall.github.io/srcly/docs/configuration/) for selecting Node and [Get started](https://byronwall.github.io/srcly/docs/get-started/) for the base scan. ## Read outcomes honestly Trace outcomes distinguish different evidence states. The app may show no status text for a landed, fully proven (`ok`) result. Other outcomes have visible labels or reasons: | Outcome | How to use it | | --- | --- | | Proven (`ok`) | No status banner appears. The result landed without an assumed library step or a frontier; it remains limited to modeled language and library facts. | | Assumed | The app says “Landed · assumes library code.” Read “Assumed library steps” in the inspector. A trace that also has a stop is labeled partial. | | Partial | The app says “Partial: some paths stop at frontiers.” Inspect the frontier rows and locations before drawing a conclusion. | | Stale | The app says “Source changed. Refresh.” Rebuild the graph from the current sources before using it. | | Unsupported | The analysis names why it could not trace the selected anchor, such as “Nothing to trace.” Treat this as an analysis limit. | | Stopped at budget | The app names the budget limit. The trace stopped before covering the full requested slice. | | Not analyzed | The app says “Data flow N/A” and gives a reason such as Node.js not found or a timeout. Do not treat it as zero edges. | The engine's graph is not a whole-program proof. It models selected language constructs and libraries. An empty graph, a missing edge, or a partial path does not prove that a value cannot flow. Check assumptions and source locations, then verify important conclusions in code and tests. See [Design decisions](https://byronwall.github.io/srcly/docs/design/) for how Srcly keeps modeled data flow separate from imports. ## A review sequence 1. State the path or symbol you want to investigate. 2. Pick a route or anchor that corresponds to that question. 3. Follow the graph and inspect the source behind each key edge. 4. Read the outcome, assumptions, and terminal or stop locations. 5. Confirm important behavior against source and tests. 6. If the trace is unavailable, decide whether the reason can be fixed through setup or reflects an unsupported case. This keeps a plausible graph from becoming a stronger claim than its evidence supports. For other views, see [Explore](https://byronwall.github.io/srcly/docs/explore/). For checker coverage and findings, see [Findings](https://byronwall.github.io/srcly/docs/findings/). --- Source: https://byronwall.github.io/srcly/docs/reports/ # Reports for agents and CI Use `report` to scan a repository and write a Markdown summary plus JSON artifacts. The output gives a developer or coding agent a starting point for review. It does not change the analyzed source tree, except for files you choose in the report output directory. ## Create a report for a review From a checkout that has Srcly installed, this command reports on the included `solid-route` example: ```bash uvx srcly report engine/examples/solid-route --out tmp/solid-route-report --profile frontend --limit 5 ``` With the published command, use `uvx srcly report /path/to/repository --out /path/to/report`. Review `report.md` first. It names the selected profile and ranking metric, gives scan and checker coverage, lists ranked findings, and shows a compact folder breakdown. Then use the printed `Start at` location or a folder path with `explain`: ```bash uvx srcly explain /path/to/repository --at src/data uvx srcly explain /path/to/repository --at "src/data/records.ts::isRecordItem" ``` In the included example at revision `653037aa`, the frontend report ranked `src/data/records.ts` with a high complexity signal. It named `isRecordItem` at line 18 as the witness (complexity 8, 24 LOC). The folder explanation for `src/` covers 10 code files. These facts show how to follow a report; they do not establish a defect in that function. Re-run against your checkout to get current evidence. ## Match each artifact to a question The default report writes these artifacts: | Artifact | Use it to answer | | --- | --- | | `report.md` | What did the scan find, what ranked highest, and what should I inspect first? | | `manifest.json` | Which revision, scan state, checkers, and coverage details produced this report? | | `findings.top.json` | What evidence should an agent load first from the findings queue? | | `action-plan.md` | What review tasks did Srcly derive from the ranked evidence? Inspect the cited source before acting. | | `tree.summary.json` | Which folders and files make up the compact repository summary? | | `findings.json` | What are the machine-readable ranked findings up to `--limit`, with their evidence? | | `hotspots.json` | Which files or functions rank highest for the selected single metric? | | `metrics.schema.json` | What do metrics mean, and how should an agent interpret them? | | `agent-skill.md` | What guidance should an agent follow when it consumes the report? | | `dataflow.md` | With `--dataflow`: which render paths in TypeScript and TSX are worth cleaning up, and where does cleanup stop paying off? | | `size_budget.json` | Which code files exceed the token-size threshold, and what baseline does the ratchet use? | The manifest identifies artifact paths and scan provenance. `report.md` is a practical first read; the JSON files support targeted tools and agent workflows. Use `--include-tree` to include the full raw tree or `--include-dependencies` to include the TypeScript and TSX import graph. Use `--dataflow` to add `dataflow.md` and a Data flow section in `report.md`; it needs Node 18 or newer and takes minutes on a large app. If you add `--quadrant `, Srcly also writes `quadrants.json` with the full member lists for the selected 2×2. The report's Markdown section gives a compact readable summary. ## Choose a profile and ranking metric The findings queue uses one profile: `general`, `frontend`, `backend`, `typescript`, `python`, or `docs`. Profiles weight available risk-related metrics to suggest a review order. The top files and functions tables rank by one metric. If you omit `--metric`, Srcly chooses the profile's lead metric. Specify one when you need consistent rankings across runs: ```bash uvx srcly report . --profile frontend --metric complexity --limit 20 --out .srcly ``` The findings profile score and a Hot Spots metric rank answer different questions. Do not compare their scores as if they were the same scale. N/A remains unavailable and is not a zero. A file measured on one side of a comparison only is a coverage change without a metric delta. Add a named 2×2 preset when you want to inspect two metric axes: ```bash uvx srcly report . --quadrant blast_radius --quadrant-cohort file --out .srcly ``` Presets include `activity`, `blast_radius`, `component_weight`, `comment_noise`, and `findings`. Some presets or cohorts do not apply to every project. ## Check freshness and coverage Srcly reuses cached analysis when the files and checker signatures are unchanged. Use `--refresh` to rescan and rerun checks; use `--verbose` for per-file progress on stderr: ```bash uvx srcly report . --refresh --out .srcly --verbose ``` Read the `Analysis:` line and manifest before taking action. They report whether the scan was reused or fresh, the Git HEAD, uncommitted files, checker status and file counts, code files no checker covers, and analysis failures. If a checker is missing or fails, its coverage is unavailable with a reason. Do not read that as a clean run. ## Use stdout for a one-shot agent call `report --stdout` emits a bundled JSON payload to standard output: ```bash uvx srcly report . --stdout ``` Machine-readable output is kept on stdout; progress and cache warnings go to stderr. The static metric schema and agent guide are written only by `report --out`. Use `--format markdown`, `json`, or `both` when you want a chosen file format in an output directory. Reports help you choose what to inspect. Confirm each claim with its source, checker evidence, and project tests. See [Findings](https://byronwall.github.io/srcly/docs/findings/) for coverage and [CLI](https://byronwall.github.io/srcly/docs/cli/) for commands such as `explain`, `hotspots`, and `compare`. --- Source: https://byronwall.github.io/srcly/docs/cli/ # Command-line reference Srcly has an interactive command and headless commands for scripts, agents, and CI. Run `uvx srcly --help` or `uvx srcly --help` to see options in the version you installed. ## Open the interactive app ```bash uvx srcly uvx srcly /path/to/repository ``` The server binds to `127.0.0.1` by default, selects an available port, and opens the browser. Use `--port` to select a port or `--host` to select another interface. Keep the server on a trusted local interface because the app reads repository files through it. Keep the terminal open while using the app; stop it with `Ctrl+C`. ## Scan and summarize `scan` writes the raw analysis tree as JSON. Its default filename is `codebase_mri.json`: ```bash uvx srcly scan . --out tree.json ``` `report` writes a Markdown summary and JSON artifacts. Choose an output directory and profile: ```bash uvx srcly report . --out .srcly --profile frontend ``` Use `--stdout` for a bundled JSON payload, `--refresh` to rescan and rerun checks, and `--verbose` to print per-file progress to stderr. To include the full raw tree, use `--include-tree`; to include TypeScript and TSX imports, use `--include-dependencies`. Select the output format with `--format markdown`, `--format json`, or `--format both`. Add `--dataflow` to run the TypeScript data-flow engine too: it writes `dataflow.md` and adds data-flow metrics and findings (see [Data-flow analysis](https://byronwall.github.io/srcly/docs/data-flow/)). The findings profile and the top-table metric are different settings. Use `--profile` for the weighted findings queue; use `--metric` for top files and functions. For example: ```bash uvx srcly report . --profile frontend --metric complexity --limit 30 --out .srcly ``` Add `--quadrant activity`, `blast_radius`, `component_weight`, `comment_noise`, or `findings` to add a 2×2 breakdown. Use `--quadrant-cohort file`, `function`, or `component` when the preset supports it. ## Rank or explain `hotspots` ranks files or functions by one metric. The default metric is complexity and the default cohort is files: ```bash uvx srcly hotspots . --metric complexity --cohort function --limit 20 --format json ``` `explain` summarizes a repository, folder, file, or symbol. Use a path relative to the analyzed root, `file::symbol`, or a `file::name@line` value when names repeat: ```bash uvx srcly explain . --at src uvx srcly explain . --at src/app.tsx uvx srcly explain . --at "src/app.tsx::App" ``` You can also pass a `path:line name` Start at location printed by the report. `explain` reports scan provenance and checker coverage so you can see whether it reused a scan and what remains unmeasured. ## Compare refs `compare` compares Git refs. By default it compares the merge base with the current working tree, including uncommitted edits. Give two refs to compare explicit revisions, or request JSON: ```bash uvx srcly compare uvx srcly compare main HEAD --json uvx srcly compare main pr:42 --json uvx srcly compare --dataflow ``` Unavailable measurements stay null. If a file is measured on one side only, Srcly records a coverage change and does not count the missing value as a zero delta. A file absent from one dependency graph has unknown fan-in and fan-out. ## Review recent changes `changes` prints the code chunks a window of Git history edited, as Markdown: the resolved base and head, the review buckets, then the chunks grouped by folder with before → after complexity. It is the text form of the app's **Changes** view. ```bash uvx srcly changes uvx srcly changes . --window 7d uvx srcly changes . --window branch --mode net --json uvx srcly changes . --window custom --base main --head my-branch uvx srcly changes . --window custom --since 2026-11-01T00:00:00 --until 2026-11-08T00:00:00 ``` `--window` is `branch` (the default: this branch against its merge base), `24h`, `7d`, or `custom` with `--base`/`--head` or `--since`/`--until`. `--mode touched` (the default) lists every chunk a commit changed, with reverted work; `--mode net` compares the base and head snapshots only. `--ref` picks the branch whose first-parent history is read. Uncommitted edits are included when the head is the checked-out commit; `--no-worktree` leaves them out. `--json` prints the same payload the app reads. See [Review changes](https://byronwall.github.io/srcly/docs/changes/) for the window, chunk and bucket rules. ## Fix and check `fix` prints a diff of supported mechanical fixes. It applies changes only with `--write`: ```bash uvx srcly fix . uvx srcly fix . --write ``` The `unreachable-file` rule can delete a file. Name that rule to run it, and inspect the diff before applying it: ```bash uvx srcly fix . --rule unreachable-file uvx srcly fix . --rule unreachable-file --write ``` `check` requires `--ratchet` and an existing size budget. Create that budget with `report`; the default report writes `.srcly/size_budget.json`: ```bash uvx srcly report . --out .srcly uvx srcly check . --ratchet ``` The budget tracks code files over 5,000 estimated tokens, based on file bytes divided by four. The baseline only goes down. The check exits nonzero when a tracked file grows above its baseline or a new file crosses the threshold. Use `--budget` to pass a budget from another report directory. For supported settings see [Configuration](https://byronwall.github.io/srcly/docs/configuration/). For the report artifacts and review order, see [Reports](https://byronwall.github.io/srcly/docs/reports/). --- Source: https://byronwall.github.io/srcly/docs/configuration/ # Configuration Most users can start Srcly without a configuration file. Use this page when you need to choose a scan root, add TypeScript entry points, enable optional rules, or understand why a check is unavailable. ## Choose the scan root Pass a directory to the interactive command or a headless command: ```bash uvx srcly /path/to/repository uvx srcly report /path/to/repository --out .srcly ``` Without a path, Srcly uses the enclosing Git repository or the current directory when no repository contains it. In a Git repository, discovery includes tracked files and nonignored untracked files. Srcly follows Git ignore rules and skips common generated, hidden, dependency, and build paths. Start at a subdirectory when you want a narrower review. The interactive server binds to `127.0.0.1` by default and chooses an available port. Use `--host` or `--port` when you need to change those settings. The local app reads repository files through this server; keep the default local interface unless you have a specific reason to bind elsewhere. ## Configure TypeScript reachability entries Srcly detects common TypeScript entry points from routes, package metadata, scripts, and configuration. If your application uses another entry pattern, add globs to `srcly.toml` at the Git root. Patterns are relative to that file: ```toml [reachability] entries = ["app/scripts/**/*.ts"] ``` Reachability follows the TypeScript and JavaScript import graph from entries. An unreachable-file signal is a prompt to inspect runtime entry points, dynamic loading, and project structure. It is not proof that a file is unused. After changing entries, refresh the report so the new analysis is used: ```bash uvx srcly report . --refresh --out .srcly ``` ## Add ast-grep rules Put ast-grep YAML rules under `.srcly/rules/` in the project. Srcly discovers `.yml` and `.yaml` files there. Install ast-grep in the project or on `PATH`, or select it with `SRCLY_AST_GREP`. If the binary is unavailable, Srcly reports the check as unavailable rather than reporting zero matches. See the [rule-pack examples](https://github.com/byronwall/srcly/tree/main/docs/rule-packs) for syntax and sample rules. Rerun the scan after adding rules or changing the checker environment. ## Set environment variables | Variable | Purpose | | --- | --- | | `SRCLY_NODE` | Select the Node executable for data-flow analysis. Defaults to `node` on `PATH`; Node.js 18 or newer is required. | | `SRCLY_CACHE_DIR` | Select the local analysis cache directory. | | `SRCLY_FINDINGS_TIMEOUT` | Set the timeout for checker jobs. | | `SRCLY_DATAFLOW_TIMEOUT` | Override data-flow request timeouts. | | `SRCLY_AST_GREP` | Select the ast-grep executable and override project and `PATH` discovery. | Cache data is stored in your user cache directory, not in the analyzed repository. A changed file or checker signature can trigger fresh analysis. Use `--refresh` when a command supports it and you need to rerun the checks without relying on cached results. ## Troubleshoot a missing result | Symptom | Check | Next step | | --- | --- | --- | | Data flow says not analyzed | Node version and `SRCLY_NODE`; project type detection and supported language | Install or select Node 18+, then rerun. If the code pattern is unsupported, treat it as an evidence limit. | | Checker coverage is N/A | Report's `Analysis:` line and checker reason | Install/configure the project tool or accept the gap; use `--refresh` after setup changes. | | Reachability marks an entry file unused | Detected entries and dynamic imports | Add an entry glob in `srcly.toml`, then refresh. Confirm any finding against the runtime. | | ast-grep has no results or is unavailable | Rule file location, YAML extension, binary discovery | Put files in `.srcly/rules/` and install or select ast-grep. | | Metrics appear as N/A | Node type, language support, analyzer status, or missing history | Read the reason; N/A means unavailable or not applicable, not zero. | For the full command list, use the [CLI reference](https://byronwall.github.io/srcly/docs/cli/). For N/A interpretation, see [Metrics](https://byronwall.github.io/srcly/docs/metrics/); for checker behavior, see [Findings](https://byronwall.github.io/srcly/docs/findings/). --- Source: https://byronwall.github.io/srcly/metrics.md # Srcly metrics Every metric Srcly measures, from its metric catalog (version 1.12.0). Rollup is how a folder or file combines its children; "max, named" also names the function that sets it. N/A means the metric does not apply or its tool did not run. It is never 0. ## General Size, complexity and comment noise for any code file. | Metric | ID | Rollup | Languages | What it measures | | --- | --- | --- | --- | --- | | Complexity (max) | `complexity` | max, named | ts, tsx, js, jsx, python, code | Cyclomatic complexity: exact for a function; for a file or folder, its most complex function, which it names. | | Cognitive complexity (max) | `cognitive_complexity` | max, named | ts, tsx, js, jsx, python | How 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) | `complexity_avg` | mean | ts, tsx, js, jsx, python, code | Mean cyclomatic complexity per function; folders weight by function count. | | LOC | `loc` | sum | any file | Lines of code, excluding comments and blanks where the analyzer can tell. | | Size | `file_size` | sum | any file | File size in bytes. | | Comment Noise | `comment_noise` | sum | ts, tsx, js, jsx, python | Over-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. | | Nesting | `max_nesting_depth` | max | ts, tsx, js, jsx, python | Deepest control-flow nesting. | | Params | `parameter_count` | sum | ts, tsx, js, jsx, python, code | Function 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. | Metric | ID | Rollup | Languages | What it measures | | --- | --- | --- | --- | --- | | Component LOC | `component_loc` | max, named | tsx, jsx | Lines in one React/Solid component. A file or folder holds the max over its components and names it. | | Hooks | `component_hook_count` | max, named | tsx, jsx | Hooks (`use*`) and Solid primitives (`create*`) in one component. A file or folder holds the max over its components and names it. | | Effects | `component_effect_count` | max, named | tsx, jsx | `useEffect`/`useLayoutEffect`/`createEffect` calls in one component. A file or folder holds the max over its components and names it. | | JSX Depth | `component_jsx_depth` | max, named | tsx, jsx | Deepest JSX nesting inside one component. A file or folder holds the max over its components and names it. | | Props | `component_prop_count` | max, named | tsx, jsx | Declared props of one component (props type members or destructured names). A file or folder holds the max over its components and names it. | | Inline Handlers | `component_inline_handler_count` | max, named | tsx, jsx | Inline `on*={() => ...}` handlers in one component. A file or folder holds the max over its components and names it. | | JSX Conditionals | `component_jsx_conditional_count` | max, named | tsx, jsx | JSX conditionals (`?:`, `&&`, ``, ``) 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. | Metric | ID | Rollup | Languages | What it measures | | --- | --- | --- | --- | --- | | any Usage | `ts_any_usage_count` | sum | ts, tsx | Explicit `any` types. | | TS Ignores | `ts_ignore_count` | sum | ts, tsx | `@ts-ignore` / `@ts-expect-error` / `@ts-nocheck` directives. | ## Markdown Markdown documents. | Metric | ID | Rollup | Languages | What it measures | | --- | --- | --- | --- | --- | | Markdown Data URLs | `md_data_url_count` | sum | markdown | Inline `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. | Metric | ID | Rollup | Languages | What it measures | | --- | --- | --- | --- | --- | | Commits | `commit_count` | sum | any file | Non-merge commits that touched the file in the activity window, following renames. Frequent change in complex code is where refactoring pays off. | | Churn | `churn_lines` | sum | any file | Lines 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. | Metric | ID | Rollup | Languages | What it measures | | --- | --- | --- | --- | --- | | Findings | `finding_count` | sum | ts, tsx, js, jsx, python | Everything 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. | | Errors | `error_count` | sum | ts, tsx, js, jsx, python | Findings 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. | Metric | ID | Rollup | Languages | What it measures | | --- | --- | --- | --- | --- | | Impossible Defenses | `dataflow_impossible_defenses` | sum | ts, 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 Forks | `dataflow_repeated_forks` | sum | ts, tsx | Components that test the same discriminant at several sibling branch sites (ternaries, `&&`, Solid `` and ``): each wants one sub-component per branch. | | Prop Relay | `dataflow_relay_hops` | max | ts, tsx | The most component boundaries a value crosses on its way to one of the file's render sinks. | | Shape Changes | `dataflow_representation_changes` | max | ts, tsx | The most representation-only steps (alias, object pack, spread) on one of the file's render paths. | | Path Depth | `dataflow_path_depth` | max | ts, tsx | The most steps from a source (prop, signal, local) to one of the file's JSX sinks. | | Value Fan-Out | `dataflow_fan_out` | max | ts, tsx | The 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. | Metric | ID | Rollup | Languages | What it measures | | --- | --- | --- | --- | --- | | Function Length (avg) | `average_function_length` | mean | ts, tsx, js, jsx, python, code | Mean function length in LOC; folders weight by function count. Detail: the M7 pilot's queues were tests, markup and one-function files. | | TODOs | `todo_count` | sum | ts, tsx, js, jsx, python | TODO/FIXME-style comments. | | Narrated Code | `comment_noise_ratio` | sum | ts, tsx, js, jsx, python | Comment noise part: functions (or a whole file) with more comment lines than code lines and 10+ code lines. | | Oversized Docblocks | `comment_noise_docblock` | sum | ts, tsx, js, jsx, python | Comment noise part: docblocks or docstrings of 8+ lines that are over 1.5x their function's code lines. | | Commented-out Code | `comment_noise_commented_code` | sum | ts, tsx, js, jsx, python | Comment noise part: runs of 3+ line comments that parse as code. | | Comment Lines | `comment_lines` | sum | ts, tsx, js, jsx, python | Comment lines. | | Functions | `function_count` | sum | ts, tsx, js, jsx, python, code | Executable functions at any depth (methods, nested functions, arrows). | | Classes | `classes_count` | sum | ts, tsx, js, jsx, python | Class declarations. | | TS Imports | `ts_import_coupling_count` | sum | ts, tsx | Distinct import sources. | | Types/Interfaces | `ts_type_interface_count` | sum | ts, tsx | Type and interface declarations. | | Exports | `ts_export_count` | sum | ts, tsx | Export declarations. | | Python Imports | `python_import_count` | sum | python | Import statements. | | Files | `file_count` | sum | any file | Files a node represents. |