DOCSEARCHbyAlgolia
Submit Docs

fallow

repository·main·Indexed 24 days ago

https://github.com/fallow-rs/fallow

A codebase intelligence tool for TypeScript and JavaScript that detects dead code, circular dependencies, duplication, complexity, and architecture violations. It features a deterministic static analysis engine that operates without a TypeScript compiler or Node.js runtime. Fallow provides a GitHub Action for SARIF/Code Scanning, a native Electron-based review application, a Node.js API via @fallow-cli/fallow-node, and editor integrations for Neovim and VS Code.

Tokens
86.9K
Snippets
155
Records
411
Agent score
88%

What's inside fallow

  1. Overview of fallow-type-aware sidecar

    main

    The fallow-type-aware sidecar provides optional TypeScript-Go semantic refinement for Fallow. It operates on a specific protocol (currently Protocol v6) that accepts a bounded set of queries to perform semantic analysis.

    Supported Query Types:

    • symbol-use
    • symbol-trace
    • api-surface
    • symbol-impact
    • type-coupling

    Key Characteristics:

    • Input/Output: Accepts one versioned JSON request on stdin and writes one JSON response to stdout.
    • Deterministic Results: Evidence and operation-specific arrays are deterministic and bounded. Results include explicit reporting for totals, omissions, reason codes, actions, and truncation.
    • Semantic Identity: Symbol identities include project-relative path, namespace, declaration kind, exported/local name, line number, byte column, and optional owner.
    • Safety Policy: The sidecar does not manufacture certainty from unsafe project states. It reports structural diagnostics, unknown identities, or capacity limits as advisory gaps rather than definitive findings. It does not emit TypeScript compiler diagnostics as Fallow findings.

  2. Overview of fallow analysis capabilities

    main

    Fallow performs several types of codebase intelligence analysis for TypeScript and JavaScript:

    • Dead Code: Finds unused files, exports, types, enum/class members, and circular dependencies.
    • Duplication: Detects code duplication using a suffix-array detector (supports JS/TS, CSS, and Vue/Svelte/Astro component regions).
    • Health & Complexity: Provides complexity hotspots and a 0-100 health score with a letter grade.
    • Architecture Boundaries: Detects violations using bulletproof, layered, hexagonal, or feature-sliced presets.
    • Styling Drift: Analyzes CSS and CSS-in-JS for design-system drift.
    • Security: Identifies security candidates ranked by reachability from entry points via fallow security.
    • Type-Aware Analysis: An optional, slower pass (--type-aware) that uses TypeScript evidence for exact symbol usage and private type leaks.

  3. Understand what Fallow detects

    main

    Fallow analyzes your codebase to identify several categories of technical debt and maintenance issues:

    • Unused files: Files that are not imported from any entry point.
    • Unused exports: Named exports that have zero references.
    • Unused types: Interfaces and type aliases that are never imported.
    • Unused dependencies: Packages listed in package.json that are never used.
    • Circular dependencies: Import cycles between modules.
    • Code duplication: Repeated code blocks across different files.

  4. Understand Fallow stability guarantees

    main

    Fallow provides stability guarantees for its public interfaces. However, the following elements are not covered by stability guarantees and may change in minor or patch versions:

    • Additive changes: New fields in config, JSON output, or plugin formats.
    • New content: New issue types or new built-in plugins.
    • Detection quality: Changes to false positive/negative rates.
    • Presentation: Human-readable terminal formatting, colors, and wording.
    • Performance: Timing, memory usage, and parallelism.
    • Protocol details: SARIF output details (beyond spec) and LSP protocol details (diagnostics, code actions, Code Lens behavior).
    • Internal APIs: Internal crates like fallow-core and fallow-config are not part of the public API and may change.

  5. Understand Fallow's PR interaction behavior

    main

    Fallow interacts with Pull Requests using several mechanisms:

    • Inline Review Comments: These target the current PR file state (side: RIGHT). Findings on deleted lines are not currently modeled.
    • Sticky PR Comments: Managed via fallow ci post-pr-comment. On 'clean' pull requests (where no issues are found), the action updates any existing sticky comment to reflect the clean result so that stale warnings are removed.
    • GitHub Check Runs: Posted against the PR head SHA (falling back to GITHUB_SHA).
    • Artifacts: The action writes fallow-pr-details.json as a CI artifact to allow for full finding drilldown.

  6. Access implementation references for Fallow subsystems

    main
    Fallow provides detailed implementation documentation for its various subsystems. Use these references to understand the internal workings of specific components. Note that the .claude/rules/ files contain scoped constraints and should be used to route to these durable implementation documents. When updating facts, modify the files in this directory rather than creating host-specific copies.

  7. Locate Fallow core components and crates

    main

    Fallow is organized into several specialized crates. Use this map to find the relevant logic for your integration or extension:

    Core Logic

    • crates/config/: Configuration, framework presets, and workspace metadata.
    • crates/types/: Shared types for discovery, extraction, reporting, and suppression.
    • crates/extract/: Oxc parsing, AST extraction, caches, and component file handling.
    • crates/graph/: Import resolution, module graph construction, reachability, and cycles.
    • crates/core/: Detector backend and analysis-specific cross-reference logic.
    • crates/engine/: Discovery, sessions, duplication, health, and security orchestration.
    • crates/api/: Public programmatic API and typed run entry points.
    • crates/output/: Typed output contracts, envelopes, and schemas.

    Interfaces and Tooling

    • crates/cli/: CLI commands, fixes, and terminal output.
    • crates/lsp/: Language Server Protocol (diagnostics, code actions, hover).
    • crates/mcp/: Model Context Protocol (MCP) tools for agents.
    • crates/napi/: Node.js bindings for the public API.
    • crates/multicall/: Unified binary for CLI, LSP, and MCP modes.
    • editors/vscode/: VS Code extension and LSP client.
    • action/: GitHub Action and related scripts.
    • ci/: GitLab CI templates and scripts.

  8. Understand Fallow CLI architecture and ownership

    main

    The Fallow CLI is structured into specific crates to separate orchestration from analysis logic. Use this mapping to locate relevant code for extensions or debugging:

    • Top-level Dispatch: crates/cli/src/lib.rs (Clap definitions and multicall surface).
    • Command Translation: crates/cli/src/check/, audit.rs, dupes.rs, health/, security.rs, and coverage/ translate CLI options into engine/API calls.
    • Rendering & Output: crates/cli/src/report/ handles terminal rendering and format dispatch.
    • Mutations: crates/cli/src/fix/ handles mutation planning and application.
    • Execution & Assembly: crates/api/ provides reusable typed execution and output assembly.
    • Core Analysis: crates/engine/ contains the analysis logic (duplication, health, discovery) and project state.
    • Serialization: crates/output/ defines serialized report types and stable envelopes.

  9. Understand the Fallow canonical knowledge model

    main

    Fallow organizes knowledge into layers to support multiple agent hosts (like Codex and Claude) through a single model.

    Knowledge Layers:

    • Codex Router: AGENTS.md (root or nested for subsystems).
    • Claude Router: CLAUDE.md (root) and .claude/rules/ (curated constraints/routes).
    • Durable Knowledge: docs/ (host-neutral) and docs/reference/ (extracted implementation details).
    • Authored Skills: .agents/skills/<name>/SKILL.md (the source of truth for maintainer workflows).
    • Generated Claude Adapters: .claude/skills/<name>/SKILL.md (automatically generated from the Codex source).

    Key Rule: Codex reads .agents/skills directly. Do not attempt to maintain equivalent prose for both Claude and Codex manually; use the generator.

  10. Understand Fallow Review Data Flow

    main

    The application follows a specific data pipeline to ensure grounded, deterministic reviews:

    1. Review Generation: fallow review --format json generates the initial data.
    2. Normalization: The toWalkthroughDocument adapter processes this data for the renderer (filtering out decisions without a Fallow signal_id to prevent hallucinations).
    3. Inspection: When a user clicks a component via the in-page picker, the app reads the data-fallow-source attribute, sends it to the bridge, and buildInspectorCard joins the selection to grounded facts from the latest review.
    4. Agent Feedback: All annotations and selections are routed to a local agent feed at .fallow-review/feed.jsonl.
    5. Verification: Judgments anchored to a signal_id are validated via fallow review --walkthrough-file using the Fallow graph as the verifier.

  11. Use Fallow for Codebase Intelligence

    main

    Fallow provides static and runtime analysis for TypeScript and JavaScript projects.

    Key Capabilities:

    • Cleanup: Find unused files, exports, types, members, and dependencies.
    • Quality & Risk: Detect code duplication, circular dependencies, complexity hotspots, and architecture boundary violations.
    • Styling: Check CSS dead surface and design-token drift.
    • Audit: Review changed code before commits, PRs, or releases.
    • Security: Surface local security candidates for verification using fallow security.
    • Runtime Coverage: Merge production execution data to identify hot-paths or stale feature flags using fallow health --coverage-gaps.
    • Type-Awareness: Use --type-aware to confirm exact TypeScript symbol usage and public-signature coupling when syntactic evidence is insufficient.

  12. Understand the Fallow System Architecture

    main

    Fallow is organized into three distinct layers to ensure separation of concerns between data analysis and user interfaces:

    1. Fact and Analysis Layer: Crates that build deterministic project knowledge.
    2. Contract Layer: Crates that shape knowledge into stable, public data formats.
    3. Protocol Adapter Layer: Crates that expose data through specific interfaces like CLI, LSP, MCP, NAPI, and editors.

    Core Crates Reference

    CrateRole
    fallow-typesShared typed contracts, issue metadata, suppressions, and envelope data.
    fallow-configConfig loading and typed configuration.
    fallow-processShared child-process lifecycle and process-tree termination.
    fallow-extractParser-facing facts from source files.
    fallow-graphModule graph, dependency traversal, cycles, and impact facts.
    fallow-securitySecurity matcher catalogue and candidate helpers.
    fallow-coreInternal detector backend used by fallow-engine for private detector phases.
    fallow-engineSession, discovery, parsing, graph construction, and typed analysis orchestration.
    fallow-outputShared output contracts, action builders, summaries, SARIF builders, and reusable formatter pieces.
    fallow-apiSupported Rust facade and programmatic workflow adapters.

    Protocol Adapters

    • fallow-cli
    • fallow-lsp
    • fallow-mcp
    • fallow-node (NAPI)