DOCSEARCHbyAlgolia
Submit Docs

pi-lens

repository·master·Indexed 42 days ago

https://github.com/apmantza/pi-lens

A high-performance intelligence layer for AI coding agents providing real-time LSP diagnostics, structural code analysis via ast-grep and tree-sitter, and impact cascade detection. Version 4.2.1 supports a wide range of managed tools including typescript-language-server, pyright, ruff, and rust-analyzer to ensure AI edits are safe and context-aware.

Tokens
164.7K
Snippets
291
Records
513
Agent score
59%

What's inside pi-lens

  1. Overview of the ast-grep rules catalog

    master

    pi-lens includes a collection of 481 enabled ast-grep rules designed for code analysis and linting. The ruleset is composed of:

    • 297 pi-lens-authored rules located in rules/ast-grep-rules/rules/.
    • 184 vendored rules from CodeRabbit located in rules/ast-grep-rules/coderabbit/rules/.

    The catalog currently supports 17 languages (including C, C++, C#, CSS, Go, HTML, and Java) and includes 16 disabled rules.

    To add your own custom rules, refer to docs/custom-rules.md.

  2. Understand pi-lens language support and capabilities

    master

    pi-lens supports over 36 languages using a combination of Language Server Protocol (LSP) integration and specialized dispatch runners.

    Core Capabilities

    • LSP Integration: Provides real-time diagnostics, hover information, definitions, and completions where supported.
    • Dispatch Runners: Executes diagnostics-oriented tasks like linting, type-checking, and structural analysis.
    • Formatting: Uses a single selected formatter per file. The hierarchy of selection is:
      1. Explicit project configuration (highest priority).
      2. Smart defaults provided by pi-lens.
      3. Config-first ecosystems (these will not autoformat unless explicitly configured).

    Important Execution Model

    Dispatch is designed to be diagnostics-oriented. Automatic formatting and safe autofixes are handled in the post-write pipeline rather than through the dispatch format-check runners.

  3. Understand the tree-sitter rules catalog

    master

    pi-lens includes a collection of tree-sitter query rules used for code analysis. The current version bundles 158 enabled rules across 14 languages.

    Rules are categorized by language (e.g., Python, Go, Java) and can be either enabled or disabled. If you are looking for the source of these rules, they are located in the rules/tree-sitter-queries/<language>/ directory of the repository.

  4. Research Overview: Graph and Code-Understanding Inspiration for pi-lens

    master

    This document is a research review comparing pi-lens against four external projects: Code-Graph-RAG, SylphAI codegraph, Compass, and Graphify. The goal is to identify architectural patterns for code-understanding, graph construction, and agent ergonomics that can be applied to pi-lens.

    Key Architectural Lessons

    • Separation of Concerns: Separate authoritative structure (the code graph) from interpretation (semantic meaning) and presentation (UI/reports).
    • Visibility of Uncertainty: Make the freshness and certainty of data visible (e.g., using provenance labels like EXTRACTED, INFERRED, or AMBIGUOUS).
    • Agent Ergonomics: Provide compact digests, progressive disclosure of information, and guided reading tours for AI agents.
    • Immutable Snapshots: Use immutable graph snapshots and atomic publication to ensure consistency.

  5. Use structural-intent parameters for cross-context queries

    master

    Instead of writing complex YAML, you can use structural-intent parameters to constrain where a pattern matches. These map directly to YAML constraints.

    ParameterDescription
    insideKindOnly match inside an ancestor of this node kind (searches ALL ancestors, stopBy: end).
    hasKindOnly match nodes whose immediate child has this kind (stopBy: neighbor).
    hasDescendantKindOnly match nodes containing this kind anywhere in their descendants (stopBy: end).
    followsOnly match nodes preceded by a sibling matching this pattern
    precedesOnly match nodes followed by a sibling matching this pattern

    Warning: hasKind and hasDescendantKind are mutually exclusive. Also, insideKind can escalate past the intended enclosing function if not scoped with paths or a specific stopBy boundary.

    # console.log only inside functions
ast_grep_search pattern="console.log($MSG)" lang="typescript" insideKind="function_declaration"

# replace var with let, scoped to functions only
ast_grep_replace pattern="var $X" rewrite="let $X" lang="javascript" insideKind="function_declaration"

  6. Understand the pi-lens MCP tool layers

    master

    pi-lens exposes functionality through Model Context Protocol (MCP) tools categorized into five operational layers. This allows developers to choose the right tool based on whether they need per-edit feedback, per-turn analysis, or project-wide observability.

    Tool Layers

    LayerMCP toolsPurpose
    Per-editpilens_analyze, pilens_lsp_navigation, pilens_ast_grep_search, pilens_ast_grep_replace, pilens_module_report, pilens_read_symbol, pilens_read_enclosingFast pipeline (format → autofix → LSP diagnostics → parallel runners). pilens_analyze supports mode: warm (reuses in-process LSP) or mode: fresh (forks a worker for latest disk state).
    Per-turnpilens_turn_endDrives handleTurnEnd (knip, dep-circular, cascade, tests, and quality warnings). Requires caller-supplied edited files via addModifiedRange.
    Per-sessionpilens_session_startDrives handleSessionStart (jscpd, knip, madge, govulncheck, gitleaks, trivy scans, complexity baselines, and LSP warm).
    Project / observabilitypilens_project_scan, pilens_project_report, pilens_diagnostics, pilens_health, pilens_latency, pilens_symbol_search, pilens_effective_configProject-wide scans, diagnostic state, latency telemetry, BM25-based identifier search, and configuration provenance. pilens_health reports a degradation ledger (e.g., LSP breaker trips, formatter skips).
    Lifecycle / looppilens_rebuildRuns npm run build:dist to ensure pilens_analyze mode=fresh reflects the latest commit.

  7. Understand LSP server capability terminology

    master

    When reviewing the LSP server capability inventory, the following abbreviations and terms are used to describe the supported operations and modes:

    Diagnostic Modes

    • mode: Refers to how diagnostics are handled.
      • pull: The server supports textDocument/diagnostic (the client can request diagnostics).
      • push-only: The server only pushes diagnostics to the client.
    • ws-pull: Indicates if the server advertises workspace/diagnostic (allowing for a single project-wide diagnostic pull).

    Navigation and Edit Operations

    • def: definition
    • tDef: typeDefinition
    • decl: declaration
    • ref: references
    • hov: hover
    • sig: signatureHelp
    • dSym: documentSymbol
    • wSym: workspaceSymbol
    • cAct: codeAction
    • rnm: rename
    • impl: implementation
    • cHir: callHierarchy
    • cmds: The size of the executeCommand allowlist.

  8. Understand LSP latency measurement types

    master

    The benchmark distinguishes between two types of latency:

    • cold: The latency of the first touch, which includes spawning the server, the initialize handshake, and the first scan.
    • warm: The per-edit latency experienced after an initial touch. This is measured by averaging the time taken over 3 consecutive content edits.

    Measurements are performed using source fixtures located in tests/fixtures/tool-smoke/* via the LSPService.touchFile method.

  9. Configure session behavior and LSP attachment

    master

    Control how multiple sessions interact and how LSPs are reused.

    PI_LENS_CONCURRENT_SESSION_GUARD

    Set to 0 to disable the concurrent-session guard. By default, the guard prevents a new session in the same workspace from resetting the warm LSP of a live incumbent session.

    PI_LENS_WARM_ATTACH

    Set to 1 to opt into same-workspace warm-attach. A second session will reuse a live incumbent session's LSP diagnostics over local IPC.

    • Fallback: If any transport, schema, or liveness failure occurs, the session falls back to a local LSP fleet.

  10. Understand the CLI flag '--no-*' one-way rule

    master

    In pi-lens, configuration keys are positive (e.g., "enabled": true means the feature is active).

    CLI flags starting with --no-* act as one-way switches. They can disable a feature, but they cannot re-enable it if the underlying configuration is set to false.

    Example:

    • Running pi --no-lsp will override lsp.enabled: true to disable LSP diagnostics.
    • However, running pi --no-lsp will not override a configuration where lsp.enabled is already set to false to make it true again.

    To re-enable a feature disabled by a config file, you must change the config key back to true in the JSON file.

  11. Understand the Compass provenance and honesty model

    master

    Compass uses a local-first knowledge graph model that emphasizes a 'honesty contract' regarding the data it provides. When consuming graph-backed reports, users should look for the following provenance markers to understand the reliability of the information:

    • EXTRACTED: Data directly pulled from source.
    • INFERRED: Data derived through analysis (not necessarily runtime truth).
    • AMBIGUOUS: Data where the source or relationship is uncertain.

    Key Design Principles:

    • Completeness & Bounds: Reports should explicitly expose their completeness, current-vs-historical state, and the bounds of the data covered.
    • Atomic Updates: Graph updates should be atomic, advancing the graph and the manifest together to prevent partial or corrupt states.
    • Immutable Snapshots: Representing Git history as immutable realizations (with commit/profile/extraction fingerprints) rather than mutable 'current' data.

  12. Understand the API ports inventory and host state projections

    master

    The API ports inventory tracks how host state (from clients/ and tools/) is projected into the engine via the DispatchContext.

    Key Concepts:

    • Host Ports: These are members of DispatchContext that are projections of the host tool context. Examples include cwd, pi.getFlag, hasTool, and log.
    • Engine Fields (Not Host Ports): Fields such as filePath, facts, project configuration, and runtime state are owned by the engine and are not considered host ports.
    • Mapping: The inventory maps current direct access mechanisms (e.g., ctx.cwd) to proposed, more structured port names (e.g., workspace.cwd).