# Project Overview: skillls

`skillls` is a Language Server Protocol (LSP) implementation for the **Skill** language (specifically targeting `.il` and `.ocn` files). It provides essential IDE features to enhance the development experience, such as error detection, structural navigation, and intelligent code hints.

## Core Capabilities

The server implements several key LSP features:

- **Diagnostics**: Automatically detects syntax errors, specifically focusing on parenthesis mismatches (too many opening or closing parentheses), and reports them with precise line/column information to the editor.
- **Document Symbols**: Parses the file structure to generate a hierarchy of scopes (nodes). This enables editors to provide an "Outline" or "Symbol Tree" view for navigating functions, variables, and namespaces.
- **Inlay Hints**: Provides inline metadata at specific code locations, allowing the editor to display additional context directly within the source text.
- **Workspace Initialization**: Upon connecting, the server scans the workspace root for relevant `.il` and `.ocn` files, building an initial representation of the project's scopes.

## Architecture & Implementation

### Parsing Logic
The project uses a multi-layered approach to understand the Skill language:
1.  **Content Cleaning**: A pre-processing step identifies and handles comments (`;`) and strings (`"..."`) to ensure parsing is not misled by ignored text.
2.  **Structural Analysis**: The server identifies "scope starters" using regular expressions and manual parenthesis tracking to determine the boundaries of functions or namespaces.
3.  **Hierarchy Building**: Once individual nodes are identified, the server builds a parent-child tree structure based on the nesting level of parentheses.
4.  **Symbol Extraction**: Within each scope, the parser identifies local variables and symbols to populate the `DocumentSymbol` list.

### Key Components

- **`skillls/main.py`**: The entry point of the LSP server. It implements the `LanguageServer` class and contains the handlers for LSP lifecycle events (`initialize`, `didOpen`, `didChange`, etc.) and feature requests (`inlayHint`, `documentSymbol`).
- **`skillls/checker.py`**: Contains the logic for syntactic validation, specifically the algorithm for detecting unbalanced parentheses.
- **`skillls/helpers.py`**: Provides the heavy lifting for text processing, including the content cleaning state machine and the recursive logic for building the node hierarchy.
- **`skillls/types.py`**: Defines the internal data models (e.g., `Node`, `URI`) used across the project.

## Technical Stack

- **Language**: Python 3.11+
- **LSP Framework**: `pygls` (Python Language Server)
- **Parsing Utilities**: `parsimonious` (PEG parser), `tree-sitter` (for structural tree analysis).
- **Formatting & Tooling**: `rich` (terminal output), `black`, `ruff`, `mypy`.