update nvim configuration

Author: rachitnigam

tools/.claude/settings.local.json

@@ -0,0 +1,15 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(mkdir:*)",
+      "Bash(cp:*)",
+      "Bash(npx tree-sitter parse:*)",
+      "Bash(npx tree-sitter:*)",
+      "Bash(tree:*)",
+      "Bash(lua:*)",
+      "Bash(npm run build-parser:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

tools/treesitter/README.md

@@ -59,7 +59,7 @@ The most significant design decision was resolving parse ambiguity between three
 **Problem:**
 ```filament
 x := new Component[32];     // Instance creation
-y := Component<'G>(ports);  // Invocation  
+y := Component<'G>(ports);  // Invocation
 z := expr;                  // Existential binding
 ```
 
@@ -84,7 +84,7 @@ assignment: $ => seq(
 ```
 
 This approach:
-- ✅ Leverages unique tokens (`new`, `<`) for disambiguation  
+- ✅ Leverages unique tokens (`new`, `<`) for disambiguation
 - ✅ Maintains identical AST structure for downstream tools
 - ✅ Eliminates all parse conflicts
 - ✅ Handles 100% of test cases correctly
@@ -94,7 +94,7 @@ This approach:
 The grammar is specifically designed for LSP functionality with careful attention to:
 
 **Definition Providers:**
-- Component names: `comp MyComponent` 
+- Component names: `comp MyComponent`
 - Parameter names: `[WIDTH, HEIGHT]`, `with { some PARAM; }`
 - Instance names: `adder := new Add[32]`
 - Port names: `input: ['G, 'G+1] 32`
@@ -117,7 +117,7 @@ tools/tree-sitter/
 ├── package.json            # NPM package configuration
 ├── queries/                # LSP query files
 │   ├── highlights.scm      # Syntax highlighting rules
-│   ├── locals.scm          # Local scope definitions  
+│   ├── locals.scm          # Local scope definitions
 │   └── tags.scm            # Symbol extraction for navigation
 ├── src/                    # Generated parser (auto-generated)
 ├── bindings/               # Language bindings (auto-generated)
@@ -128,17 +128,126 @@ tools/tree-sitter/
 
 ### Building the Parser
 
+The parser build process involves several steps that transform the grammar definition into a usable shared library:
+
+#### Automated Build (Recommended)
+```bash
+# Install dependencies and build parser in one step
+npm install  # Runs postinstall hook automatically
+
+# Or build explicitly
+npm run build-parser
+```
+
+#### Manual Build Steps
 ```bash
-# Install dependencies
+# 1. Install tree-sitter CLI and dependencies
 npm install
 
-# Generate the parser
+# 2. Generate C code from grammar.js
 npx tree-sitter generate
 
-# Test the grammar
+# 3. Compile shared library for Neovim
+gcc -o src/parser.so -shared -fPIC -I src src/parser.c
+
+# 4. Test the grammar
 npx tree-sitter test
 ```
 
+#### What Each Step Does
+
+1. **`npm install`**:
+   - Installs `tree-sitter-cli` and Node.js dependencies
+   - Runs `postinstall` hook → automatically builds parser
+   - Creates `node_modules/` directory
+
+2. **`tree-sitter generate`**:
+   - Reads `grammar.js` (source grammar definition)
+   - Generates `src/parser.c` (C implementation)
+   - Generates `src/grammar.json` (grammar metadata)
+   - Generates `src/node-types.json` (AST node types)
+   - Creates `src/tree_sitter/parser.h` (header file)
+
+3. **`gcc` compilation**:
+   - Compiles `src/parser.c` to `src/parser.so`
+   - Creates position-independent code (`-fPIC`)
+   - Links as shared library (`-shared`)
+   - Includes headers from `src/` directory (`-I src`)
+
+4. **Result**: `src/parser.so` - ready for Neovim integration
+
+#### Build Artifacts
+
+**Generated files (git-ignored):**
+```
+src/
+├── parser.c          # Generated C parser implementation
+├── parser.so         # Compiled shared library (for Neovim)
+├── grammar.json      # Grammar metadata
+├── node-types.json   # AST node type definitions
+└── tree_sitter/
+    └── parser.h      # C header file
+```
+
+**Source files (version controlled):**
+```
+grammar.js            # Grammar definition (source of truth)
+package.json          # Build configuration with npm scripts
+queries/              # Syntax highlighting and query rules
+├── highlights.scm
+├── locals.scm
+└── tags.scm
+```
+
+The `package.json` defines several build scripts for different purposes:
+
+```json
+{
+  "scripts": {
+    "build": "tree-sitter generate && node-gyp build",
+    "build-parser": "tree-sitter generate && gcc -o src/parser.so -shared -fPIC -I src src/parser.c",
+    "postinstall": "npm run build-parser",
+    "test": "tree-sitter test"
+  }
+}
+```
+
+#### Script Breakdown
+
+- **`npm run build`**: Full Node.js binding build
+  - Generates parser C code
+  - Builds Node.js native module using `node-gyp`
+  - Creates `build/Release/tree_sitter_filament_binding.node`
+  - Used for Node.js applications and tree-sitter CLI tools
+
+- **`npm run build-parser`**: Neovim-specific build
+  - Generates parser C code
+  - Compiles directly to shared library (`parser.so`)
+  - Optimized for Neovim tree-sitter integration
+  - **This is what editor plugins use**
+
+- **`postinstall`**: Automatic build hook
+  - Runs after `npm install`
+  - Calls `build-parser` to create `src/parser.so`
+  - Enables zero-config installation for users
+
+- **`npm test`**: Grammar validation
+  - Runs tree-sitter test suite
+  - Validates grammar against test files
+  - Checks parsing correctness
+
+#### Build Requirements
+
+**System Dependencies:**
+- **Node.js & npm**: For running build scripts
+- **GCC**: For compiling C code to shared library
+- **tree-sitter CLI**: Installed via npm dependencies
+
+**Platform Notes:**
+- **Linux/macOS**: Uses GCC directly
+- **Windows**: May require MinGW or MSYS2 for GCC
+- **Cross-platform**: Node.js parts work everywhere
+
 ### Testing with Filament Files
 
 ```bash
@@ -170,7 +279,7 @@ Defines syntax highlighting rules:
 - Types: component names, parameter names
 - Functions: builtin functions like `pow2`, `log2`
 
-### locals.scm  
+### locals.scm
 Defines local scope rules for variable resolution:
 - Component scopes for parameter visibility
 - With-block scopes for existential parameters
@@ -188,14 +297,99 @@ Defines symbol extraction for "jump to definition":
 
 The grammar includes comprehensive tests covering:
 - ✅ Simple component definitions
-- ✅ Complex signatures with with-blocks  
+- ✅ Complex signatures with with-blocks
 - ✅ External declarations
 - ✅ All three assignment types (instance, invocation, existential)
 - ✅ Nested expressions and time arithmetic
 - ✅ Error recovery and partial parsing
 
 Test files demonstrate parsing of real Filament programs from the repository.
 
+## Build Troubleshooting
+
+### Common Build Issues
+
+#### Missing GCC Compiler
+```
+Error: gcc: command not found
+```
+**Solutions:**
+- **macOS**: Install Xcode command line tools: `xcode-select --install`
+- **Linux**: Install build-essential: `sudo apt install build-essential` (Ubuntu/Debian) or `sudo yum groupinstall "Development Tools"` (RHEL/CentOS)
+- **Windows**: Install MinGW-w64 or use WSL with Linux tools
+
+#### Node.js/NPM Missing
+```
+Error: npm: command not found
+```
+**Solutions:**
+- Install Node.js from https://nodejs.org/
+- Use package manager: `brew install node` (macOS), `sudo apt install nodejs npm` (Linux)
+- Use version manager: `nvm install node`
+
+#### Parser Generation Fails
+```
+Error during tree-sitter generate
+```
+**Solutions:**
+- Check `grammar.js` syntax for JavaScript errors
+- Verify tree-sitter CLI installation: `npx tree-sitter --version`
+- Clean and rebuild: `rm -rf src/ && npm run build-parser`
+
+#### Compilation Errors
+```
+Error: src/parser.c: No such file or directory
+```
+**Solutions:**
+- Ensure `tree-sitter generate` ran successfully first
+- Check that `src/parser.c` exists after generation
+- Run full build: `npm install && npm run build-parser`
+
+#### Permission Issues
+```
+Error: EACCES: permission denied
+```
+**Solutions:**
+- Don't use `sudo` with npm (security risk)
+- Fix npm permissions: https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally
+- Use node version manager (nvm) instead of system Node.js
+
+#### Windows-Specific Issues
+```
+Error: 'gcc' is not recognized as an internal or external command
+```
+**Solutions:**
+- Install MinGW-w64: https://www.mingw-w64.org/
+- Add GCC to PATH environment variable
+- Use WSL (Windows Subsystem for Linux) with Ubuntu
+- Consider using Visual Studio Build Tools with node-gyp
+
+### Verification Steps
+
+After successful build, verify:
+```bash
+# Check generated files exist
+ls -la src/
+# Should show: parser.c, parser.so, grammar.json, node-types.json
+
+# Test the parser works
+npx tree-sitter parse test_simple.fil
+
+# Verify shared library
+file src/parser.so
+# Should show: shared library, dynamically linked
+```
+
+### Clean Rebuild
+
+If experiencing persistent issues:
+```bash
+# Full clean and rebuild
+rm -rf src/ node_modules/ build/
+npm install
+npm run build-parser
+```
+
 ## Implementation Notes
 
 ### Grammar Conflicts Resolved
@@ -228,7 +422,7 @@ Test files demonstrate parsing of real Filament programs from the repository.
 The grammar foundation supports adding:
 - **Error diagnostics** with precise source locations
 - **Semantic highlighting** based on symbol types
-- **Auto-completion** using partial parse trees  
+- **Auto-completion** using partial parse trees
 - **Refactoring tools** via AST transformations
 - **Documentation generation** from parsed structures
 
@@ -242,4 +436,4 @@ When modifying the grammar:
 4. **Document design decisions** for complex changes
 5. **Preserve LSP compatibility** by maintaining field names
 
-The grammar is designed to evolve with the Filament language while maintaining backward compatibility for existing LSP tooling.
+The grammar is designed to evolve with the Filament language while maintaining backward compatibility for existing LSP tooling.

tools/vim/README.md

@@ -40,7 +40,7 @@ Plug 'filament-hdl/filament', {'rtp': 'treesitter/tools/vim/filament', 'do': 'cd
 }
 ```
 
-**That's it!** The parser builds automatically and syntax highlighting works immediately.
+**That's it!** The `do`/`build` hook builds the parser during plugin installation, then syntax highlighting works immediately.
 
 ### Requirements
 - **Neovim 0.8+** (for tree-sitter support)
@@ -73,7 +73,7 @@ Add to your lazy configuration:
   dependencies = { 'nvim-treesitter/nvim-treesitter' },
   config = function()
     require('filament').setup({
-      auto_install = false, -- Parser is built automatically
+      -- Parser is built by 'build' hook above
     })
   end,
 }
@@ -89,7 +89,7 @@ use {
   run = 'cd treesitter/tools/treesitter && npm install && npm run build-parser',
   config = function()
     require('filament').setup({
-      auto_install = false, -- Parser is built automatically
+      -- Parser is built by 'run' hook above
     })
   end
 }
@@ -366,9 +366,9 @@ The tree-sitter grammar provides comprehensive highlighting for:
 Error: no parser for 'filament' language
 ```
 **Solutions**:
-1. Run `:TSInstall filament` in Neovim
-2. Use `require('filament').setup({ auto_install = true })`
-3. Build parser manually from `treesitter/tools/treesitter/`
+1. **Most likely**: Plugin manager didn't run the build hook. Reinstall with `:PlugClean` then `:PlugInstall`
+2. **Manual build**: Run `:FilamentBuildParser` in Neovim
+3. **Command line**: `cd treesitter/tools/treesitter && npm run build-parser`
 
 ### Plugin Not Loading
 1. Check runtimepath: `:set rtp?` should include filament plugin path

tools/vim/examples/lazy.lua

@@ -43,9 +43,8 @@ return {
     dependencies = { 'nvim-treesitter/nvim-treesitter' },
     config = function()
       require('filament').setup({
-        auto_install = true,
+        -- Parser built by 'build' hook above, no auto_install needed
         treesitter = {
-          -- Additional tree-sitter configuration specific to filament
           highlight = { enable = true },
           indent = { enable = true },
           fold = { enable = true },

tools/vim/examples/packer.lua

@@ -36,7 +36,7 @@ return require('packer').startup(function(use)
     run = 'cd treesitter/tools/treesitter && npm install && npm run build-parser',
     config = function()
       require('filament').setup({
-        auto_install = true,
+        -- Parser built by 'run' hook above, no auto_install needed
         treesitter = {
           highlight = { enable = true },
           indent = { enable = true },

tools/vim/examples/vim-plug.vim

@@ -29,10 +29,11 @@ require('nvim-treesitter.configs').setup {
   },
 }
 
--- Setup filament with auto-install
+-- Setup filament (parser built by 'do' hook above)
 require('filament').setup({
-  auto_install = true,
   treesitter = {
+    highlight = { enable = true },
+    indent = { enable = true },
     fold = { enable = true },
     incremental_selection = { enable = true },
   }

tools/vim/filament/lua/filament/init.lua

@@ -19,11 +19,12 @@ function M.setup(opts)
     }, opts.treesitter or {}))
   end
 
-  -- Auto-install parser if requested
+  -- Auto-install parser if explicitly requested (not recommended)
   if opts.auto_install then
     vim.schedule(function()
       local status = treesitter.status()
       if status.available and not status.parser_installed then
+        vim.notify('Auto-installing Filament parser...', vim.log.levels.INFO)
         treesitter.install_parser()
       end
     end)