Documentation

FEATURES

Features

• Holographic Slice — One file plus all its imports plus every consumer in a single context bundle.
• Handler Trace — Trace a Tauri / IPC handler end-to-end across the FE → BE boundary.
• Dead Export Detection — Find exports with zero importers — confidence-scored, suppressible.
• Circular Import Detection — Tarjan SCC over the import graph; identifies the weakest link in each cycle.
• Auto-Detect Stack — Marker-file detection for Rust, JS/TS, Python, Go, Dart, Svelte, Vue, CSS.
• HTML Reports — Server-rendered Leptos report with a navigable dependency graph.

QUICK START · LIBRARY

Quick start — library usage

Two examples mirroring the docs.rs intro — stack detection and import analysis.

Detect a project's stack

use loctree::{detect, snapshot, slicer};
use std::path::PathBuf;

let detected = detect::detect_stack(std::path::Path::new("."));
println!("Detected: {}", detected.description);

Run import analysis

use loctree::{analyzer, args};
use std::path::PathBuf;

let mut parsed = args::ParsedArgs::default();
parsed.dead_exports = true;
parsed.circular = true;

let roots = vec![PathBuf::from(".")];
analyzer::run_import_analyzer(&roots, &parsed).unwrap();

QUICK START · CLI

Quick start — CLI

The CLI binary is loct (loctree binary remains as a compatibility alias).

loctree
loctree slice src/App.tsx
loctree trace get_user
loctree -A --circular
loctree --for-ai

Full operational walkthrough — install, scan, integrate — lives on /how-it-works.

RE-EXPORTS

Re-exports

Public surface re-exported at the crate root. Each entry links to the canonical rustdoc page.

• Mode — Top-level analysis mode (Init, Slice, Search, AnalyzeImports, ForAi, Tree, Git).
• Options — Aggregate options consumed by run_import_analyzer.
• OutputMode — Human / JSON / SARIF emission selector.
• ColorMode — Auto / always / never color rendering.
• FileAnalysis — Per-file analysis record (imports, exports, edges, language).
• DetectedStack — Result of stack detection — language, marker file, description.
• detect_stack — Detect the project stack from marker files.
• HolographicSlice — File + dependencies + consumers context bundle.
• SliceConfig — Configuration for the slicer (depth, filters).
• Snapshot — Persistent snapshot — files, edges, indexes, bridges.
• run_import_analyzer — Top-level entry point for analysis pipelines.
• ReportSection — Report section identifier used by HTML rendering.
• RefactorPlan — Composite refactor plan with steps and risk.
• ParsedCommand — Parsed CLI command after subcommand resolution.

MODULES

Modules

Top-level modules of the loctree crate. Each link opens the rustdoc module page.

• analyzer — Import / export analyzer for TS, JS, Python, Rust, CSS, Go, Dart, Svelte, Vue.
• args — Legacy flag parser used as fallback after the subcommand parser.
• cli — Command enum, parser, and dispatch layer for the loct binary.
• colors — ANSI color rendering and color-mode handling.
• config — Project configuration loader (.loctree/config.toml).
• detect — Stack detection from marker files (Cargo.toml, package.json, …).
• diff — Snapshot diff utilities — compare two scans.
• focuser — Module focus — files, internal edges, external dependencies.
• fs_utils — Filesystem helpers — gather files, respect gitignore + loctignore.
• git — Git integration — HEAD detection, staleness checks.
• impact — Impact analysis — direct + transitive consumers (blast radius).
• jaq_query — jq-style queries over snapshot.json.
• layoutmap — CSS layout map analyzer.
• progress — Progress bars and status reporting (stderr).
• query — Snapshot query layer used by instant commands.
• refactor_plan — Composite refactor planner — steps, risk, sequencing.
• similarity — Similarity metrics for the twins / crowd analyzers.
• slicer — Holographic slice generator — file + deps + consumers.
• snapshot — Snapshot persistence — files, edges, export index, bridges.
• suppressions — False-positive management (.loctree/suppressions.toml).
• tree — Directory tree rendering with LOC counts.
• types — Core types — FileAnalysis, Mode, Options, ImportEntry, ExportSymbol.
• watch — File watcher — incremental scans on change.

GETTING STARTED

Getting started

Hands-on entry into Loctree — install, scan, query.

• docs/getting-started.md — first scan, essential commands, core concepts.
• docs/README.md — documentation index with quick links to every topic.
• README.md — project overview, install paths, and the headline feature list.

INSTALLATION

Installation

• docs/installation.md — install matrix: cargo, curl, source build.
• docs/dev/01_installation.md — developer setup for working on Loctree itself.
• docs/01_homebrew_release.md — Homebrew release process and tap structure.

CLI REFERENCE

CLI reference

Every subcommand of loct, every flag, every output mode.

• docs/cli/commands.md — command catalog: scan, slice, dead, cycles, twins, trace, hotspots, …
• docs/cli/options.md — global flags, output modes, CI flags (--fail, --sarif, --no-scan).
• docs/02_query_mode.md — jq-style query mode reference.
• docs/03_runtime_apis.md — runtime API surface and integration points.

EDITOR / IDE

Editor / IDE

• docs/ide/vscode.md — VS Code extension setup and command map.
• docs/ide/neovim.md — Neovim integration via lspconfig.
• docs/ide/lsp-protocol.md — raw LSP protocol contract — diagnostics, hover, code actions.

INTEGRATIONS

Integrations

• docs/integrations/mcp-server.md — MCP server tools, configuration, and agent workflow.
• docs/integrations/ci-cd.md — GitHub Actions, GitLab CI, pre-commit, SARIF upload.
• docs/ci/README.md — CI cookbook entries.

TUTORIALS

Tutorials

• 01_ai_agents_manual.md — manual workflow for AI agents using loctree as a perception layer.
• 02_crowd_detection.md — functional clustering with the crowd analyzer.
• 03_test_fixture_filtering.md — filtering test fixtures from analysis.

USE CASES

Use cases

Thirty-plus worked examples on real codebases — from Tauri command audits to FastAPI route maps.

docs/use-cases/ — browse the full catalogue.

Highlights:

• 01 — circular imports fix
• 02 — dead exports massacre
• 06 — Tauri commands
• 12 — FastAPI
• 30 — agent recon loop
• 33 — agent context bootstrap

PERCEPTION LAYER

Perception layer

The doctrine behind context-over-memory: why agents perceive the codebase before remembering it.

• PERCEPTION.md — manifesto / doctrine document.
• docs/perception/adr.md — architecture decision record.
• docs/perception/kpis.md — KPI definitions for agent context quality.
• docs/perception/research.md — underlying research synthesis.

ARCHITECTURE

Architecture

• Long-form architecture page — the canonical 4-layer doctrine, rendered in-page.
• docs/architecture.md — source Markdown.
• Semantic spec page — Cut 3A shell + make idiom catalog.
• docs/semantic-spec.md — source Markdown.
• docs/dev/02_architecture.md — developer-oriented architecture notes.

BENCHMARKS

Benchmarks

• 01 — v0.7.0 comparative analysis — head-to-head comparison against alternative tools.
• docs/search-tools-comparison.md — loctree vs grep / ripgrep / ast-grep — when each one wins.
• /evidence — live transcripts and artifacts from real repositories.

RESOURCES

Resources

• CHANGELOG.md — release history.
• CONTRIBUTING.md — how to contribute, dev setup, release process.
• github.com/Loctree/loctree-ast — source, issues, releases.
• docs.rs/loctree — live API documentation (canonical).
• crates.io/crates/loctree — published crate.