@liendev/lien 0.18.0 → 0.19.1

package/CURSOR_RULES_TEMPLATE.md

@@ -18,6 +18,7 @@ You have access to Lien semantic search tools. USE THEM INSTEAD OF grep/ripgrep/
 | Edit a file | `get_files_context` FIRST | direct edit |
 | Find similar code | `find_similar` | manual search |
 | "What depends on this file?" | `get_dependents` | manual grep |
+| "What's complex?" / "Tech debt?" | `get_complexity` | manual analysis |
 
 ## Before ANY Code Change
 
@@ -59,6 +60,18 @@ REQUIRED sequence:
   - Complexity metrics (how complex the dependent code is)
 - Highlights top 5 most complex dependents when complexity data available
 
+**`get_complexity({ top: 10 })`**
+- Find most complex functions in the codebase
+- Analyzes multiple complexity metrics:
+  - **Test paths**: Number of test cases needed for full coverage (cyclomatic)
+  - **Mental load**: How hard to follow - penalizes nesting (cognitive)
+  - **Time to understand**: Estimated reading time (Halstead effort)
+  - **Estimated bugs**: Predicted bug count (Halstead volume / 3000)
+- Use for tech debt analysis and refactoring prioritization
+- Returns `metricType` ('cyclomatic', 'cognitive', 'halstead_effort', or 'halstead_bugs')
+- Human-readable output: "23 (needs ~23 tests)", "🧠 45", "~2h 30m", "2.27 bugs"
+- Optional: `files` to filter specific files, `threshold` to set minimum complexity
+
 ## Test Associations
 
 `get_files_context` returns `testAssociations` showing which tests import/cover the file.
@@ -122,10 +135,12 @@ get_files_context({ filepaths: ["src/auth.ts", "src/user.ts"] })
 
 ## AST Metadata
 
-Results include rich metadata: `symbolName`, `symbolType`, `complexity`, `parameters`, `signature`.
+Results include rich metadata: `symbolName`, `symbolType`, `complexity`, `cognitiveComplexity`, `halsteadVolume`, `halsteadDifficulty`, `halsteadEffort`, `halsteadBugs`, `parameters`, `signature`.
 
 Use for filtering:
-- Complex functions: `results.filter(r => r.metadata.complexity > 5)`
+- Complex functions (cyclomatic): `results.filter(r => r.metadata.complexity > 10)`
+- Complex functions (cognitive): `results.filter(r => r.metadata.cognitiveComplexity > 15)`
+- Long to understand (>1 hour): `results.filter(r => r.metadata.halsteadEffort > 64800)`
 - Methods only: `results.filter(r => r.metadata.symbolType === 'method')`
 
 ## When to Use grep Instead

package/README.md

@@ -17,8 +17,10 @@ Lien connects AI coding assistants like Cursor to your codebase through the Mode
 - 🎯 **MCP Integration** - Works seamlessly with Cursor and other MCP-compatible tools
 - ⚡ **Fast** - Sub-500ms queries, minutes to index large codebases
 - 🆓 **Free Forever** - No API costs, no subscriptions, no usage limits
-- 📦 **Framework-Aware** - Auto-detects Node.js, Laravel; supports 15+ languages
+- 📦 **Framework-Aware** - Auto-detects Node.js, Laravel, Shopify; supports 15+ languages
 - 🏗️ **Monorepo Support** - Index multiple frameworks in one repository
+- 📊 **Complexity Analysis** - Human-friendly metrics: test paths, mental load, time to understand
+- 🔍 **Impact Analysis** - Find all dependents before refactoring with risk assessment
 
 ## Quick Start
 
@@ -46,13 +48,35 @@ lien index
 
 **👉 [Full installation guide](https://lien.dev/guide/installation)**
 
+## MCP Tools
+
+Lien exposes **6 powerful tools** via Model Context Protocol:
+
+| Tool | Description |
+|------|-------------|
+| `semantic_search` | Natural language code search |
+| `find_similar` | Find similar code patterns |
+| `get_files_context` | Get file context with test associations |
+| `list_functions` | List symbols by pattern |
+| `get_dependents` | Impact analysis (what depends on this?) |
+| `get_complexity` | Tech debt analysis with human-friendly metrics |
+
+### Complexity Metrics
+
+Lien tracks code complexity with intuitive outputs:
+
+- 🔀 **Test paths** - Cyclomatic complexity as "needs ~X tests for full coverage"
+- 🧠 **Mental load** - Cognitive complexity with nesting penalty
+- ⏱️ **Time to understand** - Halstead effort as readable duration (~2h 30m)
+- 🐛 **Estimated bugs** - Halstead prediction (Volume / 3000)
+
 ## Documentation
 
 - **[Installation](https://lien.dev/guide/installation)** - npm, npx, or local setup
 - **[Getting Started](https://lien.dev/guide/getting-started)** - Step-by-step configuration for Cursor
-- **[Configuration](https://lien.dev/guide/configuration)** - Customize indexing, performance tuning
+- **[Configuration](https://lien.dev/guide/configuration)** - Customize indexing, thresholds, performance
 - **[CLI Commands](https://lien.dev/guide/cli-commands)** - Full command reference
-- **[MCP Tools](https://lien.dev/guide/mcp-tools)** - API for semantic search tools
+- **[MCP Tools](https://lien.dev/guide/mcp-tools)** - Complete API reference for all 6 tools
 - **[How It Works](https://lien.dev/how-it-works)** - Architecture overview
 
 ## Supported Languages