gn-language-server/ARCHITECTURE.md

# GN Language Server Architecture

This document outlines the architecture and key design decisions of the GN Language Server.

## 1. Overview

The primary goal of this language server is to provide a fast and useful IDE experience for the GN build system. It is written in **Rust** and built on top of several key libraries:
-   **`tower-lsp`**: For the core Language Server Protocol framework.
-   **`pest`**: For parsing the GN language based on a formal grammar.
-   **`tokio`**: For asynchronous I/O and concurrency.

## 2. Key Design Decisions

Several core design decisions shape the server's behavior and performance.

### Configuration-Agnostic Analysis (Ignoring `args.gn`)

The most fundamental design choice is that **the server does not read `args.gn` files**. It analyzes the build files in a configuration-agnostic way, without knowing the final values of build arguments for any specific output directory (e.g., `out/Debug`).

This is a deliberate trade-off that prioritizes simplicity and a holistic editing experience over configuration-specific precision.

**Pros:**
-   **Simplicity & Decoupling**: The server does not need to track which of the potentially many build directories is "active," simplifying state management and user configuration. It works out of the box.
-   **Holistic Code View**: By not evaluating conditionals, the server analyzes all possible code paths. This is ideal for developers who need to understand and refactor code that spans multiple configurations (e.g., `if (is_win)` and `if (is_linux)`).
-   **Performance & Stability**: The analysis is stable and depends only on the contents of the `.gn` and `.gni` source files. It avoids the high cost of a full build config evaluation. This means the analysis can be done quickly without costly evaluations like `exec_script()`.

**Cons:**
-   **Inaccurate Semantic Analysis**: The server's understanding is incomplete. It cannot know which code paths are "active" or "dead" for a specific build, nor can it compute the final value of any variable that depends on a build argument.
-   **Ambiguous Results**: LSP features may provide ambiguous results. For example, "Go to Definition" on a variable may navigate to multiple assignments across different conditional blocks.
-   **Diagnostic Mismatches**: The server's error checking may differ from `gn check`. It might produce false positives for code in an inactive block or miss errors in code that is currently disabled.

### Single-Pass Caching & On-Demand Scope Resolution

The analyzer employs a unified caching strategy combined with on-demand scope construction.

-   **Per-File Analysis (`AnalyzedFile`)**: Each file (`.gn` or `.gni`) is parsed and analyzed independently to extract local information:
    -   **Abstract Syntax Tree (AST)**: The structural representation of the code.
    -   **Exports**: Variables, templates, and targets defined at the top level.
    -   **Links**: File paths and target labels referenced in the file.
    -   **Symbols**: A simple index of symbols for document outline.
    This result is wrapped in an `AnalyzedFile` and cached. If a file hasn't changed, this cached result is reused instantly.

-   **On-Demand Scope Building (`analyze_at`)**: When a feature requires a full semantic understanding of a specific location (e.g., "Go to Definition" or "Completion" at a cursor position), the analyzer dynamically constructs an `Environment`.
    -   It starts from the target file and recursively gathers exports from all imported files (transitive imports).
    -   It combines these exports with the local definitions available at that specific position in the code.
    -   This process is fast because it relies on the pre-computed, cached `AnalyzedFile` structures, avoiding the need to re-parse or re-analyze the dependencies.

### Caching and Performance

The server uses a freshness-checking mechanism to avoid re-analyzing unchanged files and their dependencies. The `CacheConfig` struct allows the server to differentiate between interactive requests (which might trigger a shallow update) and background requests.

### Concurrency

The server is built on `tokio` to handle multiple LSP requests concurrently without blocking. Shared state is managed safely across threads. `DocumentStorage` uses `Arc<Mutex<T>>`, while the `Analyzer` uses `RwLock` and fine-grained internal locking to allow concurrent analysis of multiple files.

### Background Indexing

For workspace-wide features like "Find All References," a complete view of the project is necessary. When a `.gn` file is first opened, a background task is spawned to walk the entire workspace directory, analyzing every `.gn` and `.gni` file. This populates the analyzer's cache. The indexer skips build output directories by checking for the presence of an `args.gn` file. Subsequent requests that need this global view can then wait for the indexing task to complete.

### Interaction with `gn` CLI

The server is designed to be mostly standalone but relies on the `gn` command-line tool for specific features where re-implementing the logic would be impractical.
-   **Location**: It has a built-in strategy to find the `gn` binary, looking in common prebuilt directories within a Chromium or Fuchsia checkout, or falling back to the system `PATH`.
-   **Formatting**: Document formatting is implemented by shelling out to `gn format --stdin`, leveraging the canonical formatter directly.

## 3. Core Components

The server is designed with a modular architecture, separating concerns into distinct components.

### Server (`src/server/mod.rs`)

This is the main entry point of the application. It initializes the server, manages the LSP request/response lifecycle, and holds the shared state of the application, including the document storage and the analyzer.

### Document Storage (`src/common/storage.rs`)

This component acts as a cache for file contents. It distinguishes between:
1.  Files currently open and being edited in the client (in-memory).
2.  Files on disk that are part of the workspace but not open for editing.

It uses a combination of LSP document versions (for in-memory files) and file system modification timestamps (for on-disk files) to determine if a file is "fresh" or needs to be re-read.

### Parser (`src/parser/`)

The parser is responsible for turning raw text into a structured representation.
-   **Grammar (`src/parser/gn.pest`)**: A formal grammar defines the syntax of the GN language. This makes the parser predictable and easy to maintain.
-   **AST (`src/parser/mod.rs`, `src/parser/parse.rs`)**: The raw parse tree from `pest` is transformed into a more ergonomic Abstract Syntax Tree (AST). The AST nodes provide methods for easy traversal and inspection, forming the input for the semantic analyzer.

### Semantic Analyzer (`src/analyzer/`)

The analyzer is the brain of the language server. It consumes the AST and builds a rich semantic understanding of the code.

-   **Workspace Context**: The server establishes the workspace context by first finding the root directory, identified by a `.gn` file. This root path is essential for resolving source-absolute paths (e.g., `//path/to/file.cc`). The `WorkspaceAnalyzer` manages the state for a specific workspace, including the build configuration loaded from `build/config/BUILDCONFIG.gn`.

-   **Key Data Structures**:
    -   `AnalyzedFile`: The complete, cached semantic model for a single file, containing its AST, exports, and links.
    -   `Environment`: Represents the fully resolved scope at a specific point in execution, aggregating variables and templates from the current file and all its dependencies.
    -   `FileExports`: Summarizes the public interface of a file (variables, templates, targets) available to importers.
    -   `AnalyzedBlock`, `AnalyzedStatement`: Semantic wrappers around AST nodes, holding resolved scopes and other metadata.

-   **Analysis Flow**:
    -   `analyze_file(path)`: Returns the cached `AnalyzedFile`.
    -   `analyze_at(file, pos)`: Returns an `Environment` representing the state of the program at `pos`, aggregating definitions from the build config and imports.

### LSP Feature Providers (`src/server/providers/`)

Each LSP feature is implemented in its own module. These providers consume the data from the Semantic Analyzer to generate responses for the client. Examples include `completion`, `hover`, `goto_definition`, and `references`.

## 4. Data Flow Example: "Go to Definition"

A typical request flows through the system as follows:

1.  **Request**: The user triggers "Go to Definition" on a variable in the editor. The client sends a `textDocument/definition` request to the server.
2.  **Dispatch**: The `Backend` in `src/server/mod.rs` receives the request and dispatches it to the `goto_definition` provider.
3.  **Analysis (File)**: The provider calls `analyzer.analyze_file()` to get the `AnalyzedFile` for the current document. This returns the cached result of the local analysis (AST, links, exports).
4.  **Link Check**: The provider first checks if the cursor is on a "link" (e.g., a file path in an import or a target label in `deps`). If so, it resolves the destination immediately.
5.  **Analysis (Scope)**: If the cursor is on an identifier, the provider calls `analyzer.analyze_at()`. This triggers the on-demand scope construction, aggregating exports from imported files to build a complete `Environment` for that specific position.
6.  **Resolution**: The provider looks up the identifier in the `Environment` to find all matching variable assignments or template definitions.
7.  **Response**: The provider constructs a `LocationLink` response containing the URIs and ranges of the definitions and returns it to the client.