@liendev/lien 0.11.0 → 0.13.0

package/CURSOR_RULES_TEMPLATE.md

@@ -114,6 +114,182 @@ list_functions({
 
 ---
 
+## Enhanced Metadata (AST-Based) ⚡ NEW in v0.13.0
+
+Lien now uses **Abstract Syntax Tree (AST) parsing** for TypeScript/JavaScript files to provide rich code metadata:
+
+### Metadata Fields in Search Results
+
+All search results (`semantic_search`, `get_file_context`, `find_similar`, `list_functions`) now include enhanced metadata when available:
+
+```typescript
+{
+  content: "function validateEmail(email: string): boolean { ... }",
+  metadata: {
+    file: "src/validators.ts",
+    startLine: 45,
+    endLine: 60,
+    type: "function",  // 'function' | 'class' | 'block'
+    language: "typescript",
+    
+    // AST-derived metadata (NEW in v0.13.0):
+    symbolName: "validateEmail",              // Function/class name
+    symbolType: "function",                   // 'function' | 'method' | 'class' | 'interface'
+    parentClass: undefined,                   // For methods: parent class name
+    complexity: 3,                            // Cyclomatic complexity
+    parameters: ["email: string"],            // Function parameters
+    signature: "function validateEmail(email: string): boolean",  // Full signature
+    imports: ["@/utils/regex"]               // File imports (for context)
+  },
+  score: 0.85,
+  relevance: "highly_relevant"
+}
+```
+
+### AST Metadata Benefits
+
+1. **Never splits functions** - Chunks respect semantic boundaries (no mid-function splits)
+2. **Function context** - Know exactly which function you're looking at
+3. **Complexity metrics** - Identify complex functions that may need refactoring
+4. **Signature awareness** - See parameters and return types at a glance
+5. **Better AI context** - AI assistants get structured code information
+
+### Using AST Metadata
+
+**Find complex functions:**
+```typescript
+// Search for authentication logic
+const results = await semantic_search({ query: "authentication logic" });
+
+// Filter by complexity
+const complexFunctions = results.filter(r => (r.metadata.complexity || 0) > 5);
+```
+
+**Identify methods in a class:**
+```typescript
+// Get file context
+const context = await get_file_context({ filepath: "src/auth/AuthService.ts" });
+
+// Find all methods
+const methods = context.results.filter(r => r.metadata.symbolType === 'method');
+```
+
+**List functions with specific parameters:**
+```typescript
+const functions = await list_functions({ pattern: ".*validate.*", language: "typescript" });
+
+// Filter by parameter count
+const simpleValidators = functions.filter(r => (r.metadata.parameters?.length || 0) <= 2);
+```
+
+### AST Support
+
+**Currently supported:**
+- ✅ TypeScript (`.ts`, `.tsx`)
+- ✅ JavaScript (`.js`, `.jsx`, `.mjs`, `.cjs`)
+
+**Coming soon:**
+- 🔜 Python, Go, Rust, Java, PHP, and more
+
+**Fallback behavior:**
+- For unsupported languages, Lien automatically falls back to line-based chunking
+- No disruption to existing workflows
+
+### Known Limitations
+
+**Very large files (1000+ lines):**
+- Tree-sitter may fail with "Invalid argument" error on extremely large files
+- When this occurs, Lien automatically falls back to line-based chunking
+- This is a known Tree-sitter limitation with very large syntax trees
+- Fallback behavior is configurable via `astFallback` setting
+
+**Resilient parsing:**
+- Tree-sitter is designed to produce best-effort ASTs even for invalid syntax
+- Parse errors are rare; most malformed code still produces usable chunks
+- The `astFallback: 'error'` option mainly catches edge cases like large file errors
+
+### Configuration
+
+Control AST behavior in `.lien.config.json`:
+
+```json
+{
+  "chunking": {
+    "useAST": true,              // Enable AST-based chunking (default: true)
+    "astFallback": "line-based"  // Fallback strategy: 'line-based' | 'error'
+  }
+}
+```
+
+---
+
+## Input Validation & Error Handling
+
+Lien uses Zod schemas for runtime type-safe validation of all tool inputs. This provides:
+- **Automatic validation** of all parameters before tool execution
+- **Rich error messages** with field-level feedback
+- **Type safety** with full TypeScript inference
+- **Consistent error structure** across all tools
+
+### Understanding Validation Errors
+
+When you provide invalid parameters, you'll receive a structured error response:
+
+```json
+{
+  "error": "Invalid parameters",
+  "code": "INVALID_INPUT",
+  "details": [
+    {
+      "field": "query",
+      "message": "Query must be at least 3 characters"
+    },
+    {
+      "field": "limit",
+      "message": "Limit cannot exceed 50"
+    }
+  ]
+}
+```
+
+### Common Validation Rules
+
+**semantic_search:**
+- `query`: 3-500 characters (required)
+- `limit`: 1-50 (default: 5)
+
+**find_similar:**
+- `code`: minimum 10 characters (required)
+- `limit`: 1-20 (default: 5)
+
+**get_file_context:**
+- `filepath`: cannot be empty (required)
+- `includeRelated`: boolean (default: true)
+
+**list_functions:**
+- `pattern`: optional regex string
+- `language`: optional language filter
+
+### Error Codes
+
+Lien uses structured error codes for programmatic error handling:
+
+- `INVALID_INPUT` - Parameter validation failed
+- `FILE_NOT_FOUND` - Requested file doesn't exist in index
+- `INDEX_NOT_FOUND` - No index found (run `lien index`)
+- `INDEX_CORRUPTED` - Index is corrupted (run `lien reindex`)
+- `EMBEDDING_GENERATION_FAILED` - Embedding model failed (retryable)
+- `INTERNAL_ERROR` - Unexpected internal error
+
+### Best Practices
+
+1. **Always provide required fields**: Check tool schemas for required parameters
+2. **Respect validation limits**: Don't exceed max values for `limit` parameters
+3. **Use descriptive queries**: Avoid very short or vague queries
+4. **Handle validation errors gracefully**: Parse error details to understand what went wrong
+
+---
+
 ## Workflow Patterns (FOLLOW THESE)
 
 ### Pattern 1: User Asks "Where is X?"