css-variable-lsp 1.0.7 → 1.0.8

package/.git-blame-ignore-revs

@@ -0,0 +1,3 @@
+d56bdde56644b9ea096d97daa49cd8c180d288ed
+# Set the blame.ignoreRevsFile configuration in your local git config
+# git config blame.ignoreRevsFile .git-blame-ignore-revs

package/.github/workflows/test.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test

package/AGENTS.md

@@ -12,23 +12,27 @@
 ### Quick Start
 
 **Check for ready work:**
+
 ```bash
 bd ready --json
 ```
 
 **Create new issues:**
+
 ```bash
 bd create "Issue title" -t bug|feature|task -p 0-4 --json
 bd create "Issue title" -p 1 --deps discovered-from:bd-123 --json
 ```
 
 **Claim and update:**
+
 ```bash
 bd update bd-42 --status in_progress --json
 bd update bd-42 --priority 1 --json
 ```
 
 **Complete work:**
+
 ```bash
 bd close bd-42 --reason "Completed" --json
 ```
@@ -62,6 +66,7 @@ bd close bd-42 --reason "Completed" --json
 ### Auto-Sync
 
 bd automatically syncs with git:
+
 - Exports to `.beads/issues.jsonl` after changes (5s debounce)
 - Imports from JSONL when newer (e.g., after `git pull`)
 - No manual export/import needed!
@@ -75,6 +80,7 @@ pip install beads-mcp
 ```
 
 Add to MCP config (e.g., `~/.config/claude/config.json`):
+
 ```json
 {
   "beads": {
@@ -89,6 +95,7 @@ Then use `mcp__beads__*` functions instead of CLI commands.
 ### Managing AI-Generated Planning Documents
 
 AI assistants often create planning and design documents during development:
+
 - PLAN.md, IMPLEMENTATION.md, ARCHITECTURE.md
 - DESIGN.md, CODEBASE_SUMMARY.md, INTEGRATION_PLAN.md
 - TESTING_GUIDE.md, TECHNICAL_DESIGN.md, and similar files
@@ -96,18 +103,21 @@ AI assistants often create planning and design documents during development:
 **Best Practice: Use a dedicated directory for these ephemeral files**
 
 **Recommended approach:**
+
 - Create a `history/` directory in the project root
 - Store ALL AI-generated planning/design docs in `history/`
 - Keep the repository root clean and focused on permanent project files
 - Only access `history/` when explicitly asked to review past planning
 
 **Example .gitignore entry (optional):**
+
 ```
 # AI planning documents (ephemeral)
 history/
 ```
 
 **Benefits:**
+
 - ✅ Clean repository root
 - ✅ Clear separation between ephemeral and permanent documentation
 - ✅ Easy to exclude from version control if desired

package/LIMITATIONS.md

@@ -5,12 +5,14 @@ This document outlines the current limitations of the CSS Variable Language Serv
 ## ✅ What We DO Handle
 
 ### Core CSS Cascade Features
+
 - **Selector tracking**: Each variable definition tracks its CSS selector (`:root`, `div`, `.class`, etc.)
 - **CSS Specificity**: Full specificity calculation for IDs, classes, pseudo-classes, elements
 - **Usage context detection**: Tracks which selector a `var(--name)` usage appears in
 - **Context-aware hover**: Shows all definitions sorted by specificity with indicator of which applies
 
 ### Advanced CSS Features ✨
+
 - **Source order tracking**: When two selectors have equal specificity, later definitions win
 - **!important support**: `--color: red !important` is tracked and prioritized correctly in cascade
 - **Inline style parsing**: `style="--color: red"` attributes are parsed for variable definitions
@@ -24,29 +26,38 @@ This document outlines the current limitations of the CSS Variable Language Serv
 **This is the key limitation you're asking about!**
 
 - **No DOM structure awareness**: We don't know the actual HTML element hierarchy
+
   - Example: Can't tell if a `div` is inside another `div` or a `section`
   - Can't resolve parent-child relationships
 
 - **No CSS nesting support** (CSS Nesting Module):
+
   ```css
   .parent {
     --color: red;
     .child {
-      --color: blue;  /* We parse this but don't know it's nested */
+      --color: blue; /* We parse this but don't know it's nested */
     }
   }
   ```
 
 - **No descendant/combinator resolution**:
   ```css
-  div .class { --color: blue; }      /* We see "div .class" but can't match it to usage context */
-  div > .class { --color: green; }   /* Same issue */
-  .parent .child { --color: red; }   /* We don't know .child is inside .parent */
+  div .class {
+    --color: blue;
+  } /* We see "div .class" but can't match it to usage context */
+  div > .class {
+    --color: green;
+  } /* Same issue */
+  .parent .child {
+    --color: red;
+  } /* We don't know .child is inside .parent */
   ```
 
 ### What This Means
 
 Our current implementation:
+
 1. ✅ Extracts the selector (e.g., `div`, `.class`)
 2. ✅ Calculates specificity (e.g., `.class` > `div`)
 3. ✅ Shows which would apply based on **exact selector match**
@@ -58,10 +69,16 @@ Our current implementation:
 ### Example of Current Limitation
 
 ```css
-div { --color: red; }
-div .inner { --color: blue; }
-
-.inner { color: var(--color); }  /* Which color applies? */
+div {
+  --color: red;
+}
+div .inner {
+  --color: blue;
+}
+
+.inner {
+  color: var(--color);
+} /* Which color applies? */
 ```
 
 **What we show**: Both `red` and `blue` with specificity scores
@@ -70,6 +87,7 @@ div .inner { --color: blue; }
 ### Other Limitations
 
 - **Complex selectors**:
+
   - Attribute selectors: `[data-attr="value"]` ✅ Parsed, ❌ Not matched
   - Pseudo-classes: `:hover`, `:nth-child()` ✅ Parsed, ❌ Context not resolved
   - Pseudo-elements: `::before`, `::after` ✅ Counted in specificity
@@ -119,10 +137,12 @@ div .inner { --color: blue; }
 **You asked: "Should we also care about nesting?"**
 
 **Answer**: YES! Nesting/hierarchy is currently our biggest limitation. We handle:
+
 - ✅ Basic selector matching and specificity
 - ❌ NOT actual DOM structure or nested selectors
 
 To fully resolve which value applies, we'd need:
+
 1. HTML DOM structure analysis
 2. Selector combinator matching
 3. CSS cascade simulation

package/README.md

@@ -1,111 +1,116 @@
 # CSS Variable Language Server
 
-A Language Server Protocol (LSP) implementation for CSS variables (custom properties). This server can be used by any LSP-compatible editor.
+A Language Server Protocol (LSP) implementation focused on CSS custom properties (variables). It indexes variables across your workspace and provides completions, hover resolution, and diagnostics.
 
 ## Features
 
-- **Context-Aware Completion**: Intelligently suggests CSS variables only in relevant contexts (property values, inside `var()`, style attributes). No more suggestions in selectors or property names!
-- **Cross-file Completion**: Suggests CSS variables defined in other `.css`, `.scss`, `.sass`, `.less` files or HTML `<style>` blocks.
-- **Hover Information**: Shows the value of the CSS variable on hover with full cascade resolution.
-- **Go to Definition**: Jumps to the line where the variable is defined.
-- **Find References**: Shows all usages of a CSS variable across files.
-- **Rename Support**: Rename CSS variables across the entire workspace.
-- **Color Decorations**: Shows color boxes next to CSS variables with color values (can be disabled with `--no-color-preview`).
-- **HTML Support**: Parses `<style>` blocks and inline styles in HTML files.
+- **Context-aware completion** in CSS property values, inside `var(...)`, and in HTML `style=""` attributes, with relevance scoring.
+- **Workspace-wide indexing** across `.css`, `.scss`, `.sass`, `.less`, plus HTML `<style>` blocks and inline styles.
+- **Cascade-aware hover** that orders definitions by `!important`, specificity, and source order.
+- **Go to definition**, **find references**, and **rename** support.
+- **Diagnostics** for undefined variables used via `var(--name)`.
+- **Color decorations** and a color picker with hex/rgb/hsl presentations.
 
 ## Getting Started
 
 ### Prerequisites
 
-- [Node.js](https://nodejs.org/) (v16 or higher)
-- [Visual Studio Code](https://code.visualstudio.com/)
+- Node.js (ES2020-compatible; v16+ recommended)
+- npm
 
-### Installation
+### Install / Build
 
-1.  Clone the repository.
-2.  Install dependencies:
-    ```bash
-    npm install
-    ```
+```bash
+npm install
+npm run compile
+```
 
-### Using the Language Server
+### Run
 
-This is a standalone LSP server. To use it, you'll need to integrate it with an LSP client (e.g., a VSCode extension). See the `../css-variable-vscode` project for a VSCode extension that uses this server.
+```bash
+# via local build
+node out/server.js --stdio
 
-#### Command-Line Options
+# or, if installed from npm
+css-variable-lsp --stdio
+```
 
-- `--no-color-preview`: Disable color decorations (color boxes) entirely.
-- `--color-only-variables`: Show color boxes only next to CSS variable usages (like `var(--my-color)`), not on raw color value definitions (like `#f0f0f0`). This keeps color boxes only on the CSS variables, making them stand out more clearly.
+### Editor Integration
 
-**Environment Variables:**
-- `CSS_LSP_COLOR_ONLY_VARIABLES=1`: Same as `--color-only-variables` flag.
+This is a standalone LSP server. Configure it in any LSP client.
 
-**Behavior comparison:**
+[VS Code extension](https://marketplace.visualstudio.com/items?itemName=miclmn451.css-variables-vscode)
 
-Without flag (default):
-- `--secondary-color: #f0f0f0` ← Shows color box on `#f0f0f0`
-- `var(--secondary-color)` ← Shows resolved color box
+[Zed extension](https://zed.dev/extensions/css-variables)
 
-With `--color-only-variables`:
-- `--secondary-color: #f0f0f0` ← No color box (native editor already shows this)
-- `var(--secondary-color)` ← Shows resolved color box (unique to this extension)
+## Configuration
 
-Examples:
-```bash
-# Disable all color boxes
-css-variable-lsp --no-color-preview
+Command-line flags:
 
-# Show colors only on CSS variable usages (recommended to avoid duplication)
-css-variable-lsp --color-only-variables
+- `--no-color-preview`
+- `--color-only-variables` (show colors only on `var(--...)` usages)
+- `--lookup-files "<glob>,<glob>"` (comma-separated list of glob patterns)
+- `--lookup-file "<glob>"` (repeatable)
+- `--path-display=relative|absolute|abbreviated`
+- `--path-display-length=N` (only used for `abbreviated`; `0` disables shortening)
 
-# Or using environment variable
-CSS_LSP_COLOR_ONLY_VARIABLES=1 css-variable-lsp
-```
+Environment variables:
 
-### Running Tests
+- `CSS_LSP_COLOR_ONLY_VARIABLES=1` (same as `--color-only-variables`)
+- `CSS_LSP_LOOKUP_FILES` (comma-separated glob patterns; ignored if CLI lookup flags are provided)
+- `CSS_LSP_DEBUG=1` (enable debug logging)
+- `CSS_LSP_PATH_DISPLAY=relative|absolute|abbreviated`
+- `CSS_LSP_PATH_DISPLAY_LENGTH=1` (same as `--path-display-length`)
 
-To run all tests in the repository:
+Defaults:
 
-```bash
-# From the root directory
-npm test
+- `--path-display`: `relative`
+- `--path-display-length`: `1`
+- Lookup globs:
+  - `**/*.css`
+  - `**/*.scss`
+  - `**/*.sass`
+  - `**/*.less`
+  - `**/*.html`
+  - `**/*.vue`
+  - `**/*.svelte`
+  - `**/*.astro`
+  - `**/*.ripple`
+- Ignore globs:
+  - `**/node_modules/**`
+  - `**/dist/**`
+  - `**/out/**`
+  - `**/.git/**`
 
-# Or from the server directory
-cd server
-npm run test:all
-```
+`abbreviated` mode shortens each directory segment (except the final one) to the configured length, matching fish-style prompt shortening. Lookup globs accept standard glob patterns (including brace expansions like `**/*.{css,scss}`) and the default ignore list remains in effect even when lookup globs are provided.
 
-Individual test suites:
-```bash
-cd server
-npm test              # Core functionality tests
-npx ts-node src/easyWins.test.ts  # Easy wins features
-```
+### Completion Path Examples
 
-## New Features
+Assume a variable is defined in `/Users/you/project/src/styles/theme.css` and your workspace root is `/Users/you/project`.
 
-### ✨ **Context-Specific Resolution**
-The LSP now understands CSS specificity and shows which variable value would actually apply:
-- Tracks CSS selectors for each definition
-- Calculates full CSS specificity
-- Considers `!important` declarations
-- Respects source order for equal specificity
-- Parses inline `style=""` attributes
+- `--path-display=relative` (default):
+  - `Defined in src/styles/theme.css`
+- `--path-display=absolute`:
+  - `Defined in /Users/you/project/src/styles/theme.css`
+- `--path-display=abbreviated --path-display-length=1`:
+  - `Defined in s/s/theme.css`
+- `--path-display=abbreviated --path-display-length=2`:
+  - `Defined in sr/st/theme.css`
+- `--path-display=abbreviated --path-display-length=0` (no shortening):
+  - `Defined in src/styles/theme.css`
 
-### Hover Example
-When you hover over a CSS variable, you'll see:
-```
-### CSS Variable: `--primary-color`
+## Cascade Awareness (Best-Effort)
 
-**Definitions** (CSS cascade order):
+Hover and color resolution use CSS cascade rules (specificity, `!important`, source order) but do not model DOM nesting or selector combinators. See `LIMITATIONS.md` for details.
 
-1. `green` from `.special` (0,1,0) !important ✓ Wins (!important)
-2. `blue` from `div` (0,0,1) _(overridden by !important)_
-3. `red` from `:root` (0,1,0) _(lower specificity)_
+## Project Structure
 
-_Context: `div`_
-```
+- `src/` TypeScript source
+- `out/` compiled server (npm bin entry)
+- `LIMITATIONS.md` known limitations
 
-## Project Structure
+## Testing
 
-- `server/`: Node.js Language Server implementation (CSS variable analysis logic).
+```bash
+npm test
+```

package/check_node_html_parser.ts

@@ -0,0 +1,10 @@
+import { parse } from "node-html-parser";
+
+const root = parse('<div class="foo bar"></div>');
+const el = root.querySelector("div")!;
+console.log("classList.length:", el.classList.length);
+console.log("classList.value:", el.classList.value);
+console.log("classList.values():", [...el.classList.values()]);
+for (let i = 0; i < el.classList.length; i++) {
+  console.log(`classList.value[${i}]:`, el.classList.value[i]);
+}