purecontext-mcp 1.1.8 → 1.2.0

package/AST-SEARCH.md

@@ -0,0 +1,274 @@
+# AST-Level Search
+
+The three standard search modes — by name, by meaning, by text — cover most navigation tasks. But some questions can only be answered by looking at the *structure* of the code, not its surface.
+
+- How many arrow functions are in this codebase?
+- Find every function that returns `Promise<void>`.
+- Which classes use the `@Injectable` decorator?
+- Show me every function with more than 6 parameters.
+
+These are structural questions. PureContext's AST-level search tools answer them by searching the indexed symbol data and — where needed — re-parsing stored file content through tree-sitter grammars.
+
+---
+
+## Searching by AST node type
+
+`search_ast` finds every occurrence of a specific tree-sitter node type across all indexed files. If you've ever wanted to run a structural grep across a codebase, this is it.
+
+**Scenario:** Your team is trying to eliminate all `try/catch` blocks in favor of `Result` types. Before you start, you want to know how many there are and where.
+
+> "Find every try/catch block in the TypeScript source files."
+
+```
+search_ast(repoId, nodeType: "try_statement", language: "typescript") →
+
+  47 matches across 23 files:
+
+  src/api/routes/auth.ts:34         try { await validateToken(req) } catch (e) { ... }
+  src/api/routes/payments.ts:67     try { await chargeCard(amount) } catch (err) { ... }
+  src/core/database.ts:123          try { return await db.query(sql) } catch (e) { ... }
+  src/workers/sync.ts:45            try { await syncUser(id) } catch (e) {
+  ...
+  (43 more)
+```
+
+47 places. The migration scope is now concrete.
+
+**Finding all await expressions (checking for missing error handling):**
+
+> "Find every await expression so I can check which ones lack try/catch."
+
+```
+search_ast(repoId, nodeType: "await_expression", filePath: "src/api/") →
+  [all awaited calls in the API directory]
+```
+
+**Common node types by language:**
+
+| Language | Node types to try |
+|----------|------------------|
+| TypeScript / JS | `arrow_function`, `function_declaration`, `class_declaration`, `interface_declaration`, `try_statement`, `await_expression`, `call_expression`, `import_statement`, `jsx_element`, `template_string`, `throw_statement`, `type_alias_declaration` |
+| Python | `function_definition`, `class_definition`, `for_statement`, `with_statement`, `decorated_definition`, `lambda` |
+| Go | `function_declaration`, `method_declaration`, `go_statement`, `defer_statement`, `type_declaration`, `interface_type` |
+| Rust | `function_item`, `struct_item`, `impl_item`, `match_expression`, `closure_expression`, `trait_item` |
+| Java / Kotlin | `method_declaration`, `class_declaration`, `try_statement`, `lambda_expression`, `annotation` |
+
+Node type names are tree-sitter's internal names and are exact, case-sensitive matches.
+
+---
+
+## Searching by type signature
+
+`search_by_signature` finds symbols by the pattern of their type signature. It operates on the one-line signature stored for every indexed symbol — no re-parsing needed.
+
+**Scenario:** You're auditing all functions that accept a `Request` object to make sure they all validate the request before using it.
+
+> "Find all functions that accept a Request parameter."
+
+```
+search_by_signature(repoId, pattern: "(req: Request", kind: "function") →
+
+  handleLogin()           src/api/routes/auth.ts          function
+  handleLogout()          src/api/routes/auth.ts          function
+  validateRequestBody()   src/api/middleware/validate.ts  function
+  processWebhook()        src/api/routes/webhooks.ts      function
+  ... (14 more)
+```
+
+All 17 functions that accept a `Request`. Spot-check each one for input validation.
+
+**Finding all async functions in a specific directory:**
+
+```
+search_by_signature(repoId, pattern: "async", mode: "startsWith", filePath: "src/core/") →
+  [all symbols in src/core/ whose signature starts with "async"]
+```
+
+**Finding all exported symbols (to audit the public API surface):**
+
+```
+search_by_signature(repoId, pattern: "export", mode: "startsWith") →
+  [every symbol with a signature beginning with "export"]
+```
+
+**Finding functions that return a specific type:**
+
+```
+search_by_signature(repoId, pattern: "Promise<void>") →
+  [all functions returning Promise<void>]
+
+search_by_signature(repoId, pattern: ": string[]") →
+  [all functions returning string[]]
+
+search_by_signature(repoId, pattern: "AuthResult") →
+  [any signature mentioning AuthResult — return types, parameters, or type aliases]
+```
+
+**Using regex mode for complex patterns:**
+
+```
+search_by_signature(repoId, pattern: "\\(.*password.*\\)", mode: "regex") →
+  [all functions that have "password" somewhere in their parameter list]
+```
+
+---
+
+## Searching by decorator
+
+`search_by_decorator` finds all symbols annotated with a specific decorator. It re-parses file content to locate decorator nodes — catching decorators that may not appear in the stored signature.
+
+**Scenario:** You're auditing all NestJS route handlers decorated with `@Get` to verify they all have proper authentication guards.
+
+> "Find all @Get route handlers."
+
+```
+search_by_decorator(repoId, decoratorName: "Get") →
+
+  getUsers()           src/users/users.controller.ts:14    method
+  getUserById()        src/users/users.controller.ts:28    method
+  getOrderHistory()    src/orders/orders.controller.ts:8   method
+  getPaymentMethods()  src/billing/billing.controller.ts:19 method
+  ... (11 more)
+```
+
+15 GET handlers. Now cross-reference with those that have an `@UseGuards` decorator:
+
+```
+search_by_decorator(repoId, decoratorName: "UseGuards") →
+  [12 matches]
+```
+
+Three handlers don't have a guard. Those are your security gaps.
+
+**Prefix match for families of decorators:**
+
+```
+search_by_decorator(repoId, decoratorName: "Get", matchMode: "prefix") →
+  → finds @Get, @GetMapping, etc.
+
+search_by_decorator(repoId, decoratorName: "Column", matchMode: "prefix") →
+  → finds @Column, @ColumnType, @ColumnDefault, etc.
+```
+
+**Finding all ORM entities:**
+
+```
+search_by_decorator(repoId, decoratorName: "Entity") →
+  [all classes marked as TypeORM entities]
+
+search_by_decorator(repoId, decoratorName: "injectable", matchMode: "contains") →
+  [all injection-related decorators across frameworks — @Injectable, @Inject, etc.]
+```
+
+---
+
+## Searching by complexity thresholds
+
+`search_by_complexity` finds symbols that match specific numeric criteria across six complexity dimensions. This is different from `get_complexity_hotspots` (which ranks files) — here you set specific thresholds and get back the matching symbols.
+
+**Scenario:** A code review checklist says any function with cyclomatic complexity above 8 requires two reviewers. Before the release, find all such functions.
+
+> "Find all functions with cyclomatic complexity above 8."
+
+```
+search_by_complexity(repoId, minCyclomaticComplexity: 8, kind: "function") →
+
+  processAuthRequest()    src/auth/processor.ts      complexity: 18  lines: 120
+  generateReport()        src/reporting/engine.ts    complexity: 14  lines: 89
+  validatePaymentForm()   src/billing/validator.ts   complexity: 11  lines: 67
+  migrateUserData()       src/workers/migration.ts   complexity: 9   lines: 43
+  ... (7 more)
+```
+
+11 functions require dual review.
+
+**Finding functions with too many parameters:**
+
+> "Find all functions with 5 or more parameters — we're moving to options objects."
+
+```
+search_by_complexity(repoId, minParamCount: 5) →
+
+  createUser(name, email, role, tenantId, options, ...rest)  — 6 params
+  sendEmail(to, from, subject, body, attachments, headers)    — 6 params
+  processOrder(items, userId, discount, tax, shipping, note) — 6 params
+  ... (9 more)
+```
+
+**Finding long functions to split:**
+
+```
+search_by_complexity(repoId, minLineCount: 100, kind: "function") →
+  [all functions longer than 100 lines]
+```
+
+**Combining multiple criteria:**
+
+> "Find the most dangerous code — high complexity AND deeply nested AND long."
+
+```
+search_by_complexity(repoId,
+  minCyclomaticComplexity: 8,
+  minNestingDepth: 4,
+  minLineCount: 50) →
+  [intersection of all three filters]
+```
+
+**Finding simple utility functions (to understand what's safe to inline):**
+
+```
+search_by_complexity(repoId,
+  maxCyclomaticComplexity: 2,
+  maxLineCount: 10,
+  maxParamCount: 2,
+  kind: "function") →
+  [simple, pure helper functions — candidates for inlining]
+```
+
+The six complexity dimensions available:
+
+| Dimension | What it measures |
+|-----------|-----------------|
+| `cyclomaticComplexity` | Number of independent code paths (branching) |
+| `cognitiveComplexity` | Mental effort to understand (nested structures) |
+| `lineCount` | Function body size |
+| `nestingDepth` | Maximum level of nested blocks |
+| `paramCount` | Number of parameters |
+| `returnCount` | Number of return statements (exit points) |
+
+---
+
+## Combining AST search with other tools
+
+AST search tools work best as the starting point for further navigation:
+
+```
+1. search_ast(nodeType: "try_statement")
+   → get all try/catch blocks in the codebase
+
+2. [review the list, pick the ones you care about]
+
+3. get_symbol_source(symbolId)
+   → read the source for specific matches
+
+4. find_references(symbolId)
+   → see who calls functions that contain the pattern
+
+5. get_context_bundle(symbolId)
+   → understand the full context around a complex function
+```
+
+```
+1. search_by_complexity(minCyclomaticComplexity: 10)
+   → find the most complex functions
+
+2. get_symbol_history(symbolId)
+   → check how long they've been this complex and who wrote them
+
+3. plan_refactoring(goal: "general", filePath)
+   → get a structured plan for the worst files
+```
+
+---
+
+→ Reference: [MCP Tools Reference](docs/06-tools-reference.md) — `search_ast`, `search_by_signature`, `search_by_decorator`, `search_by_complexity`

package/CHANGELOG.md

@@ -7,6 +7,68 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.2.0] - 2026-05-13
+
+### Added
+
+**Advanced relationship analysis (Phase 28)**
+- `find_implementations` — find all concrete implementations of a TypeScript interface or abstract class; returns implementing classes with `implementedMethods` and `missingMethods` arrays compared against the interface contract
+- `get_call_hierarchy` — callers and callees of a function N levels deep as a hierarchical tree; supports `callers`, `callees`, and `both` directions; recursive calls marked `cyclic: true`
+- `get_class_hierarchy` — full inheritance tree rooted at a class, showing both ancestors and descendants; use before refactoring a base class to understand the full polymorphism surface
+- `find_cycles` — detect circular import dependencies across the repo or a subtree; returns strongly-connected components with severity rating
+- `get_coupling_map` — afferent/efferent coupling metrics and instability scores (`I = efferent / (afferent + efferent)`) for every file; highlights highest-risk refactoring candidates
+
+**Architectural visualization (Phase 29)**
+- `render_diagram` — general-purpose Mermaid or DOT dependency diagram (module, call graph, class hierarchy); output renders natively in GitHub, VS Code, and Claude
+- `render_call_graph` — specialized call graph diagram rooted at a symbol with call-graph-specific layout options
+- `render_import_graph` — file-level import graph for a directory or whole repo; nodes clustered by directory
+- `render_class_hierarchy` — class inheritance diagram in Mermaid `classDiagram` format; shows fields, methods, and inheritance/implementation relationships
+- `render_dep_matrix` — dependency matrix diagram showing coupling between modules as a grid; surfaces structural hotspots at a glance
+- `get_architecture_snapshot` — captures architectural state (file count, symbol count, module breakdown, coupling summary, health scores); take two snapshots to prove structural improvement objectively
+
+**Refactoring safety checks (Phase 30)**
+- `check_rename_safe` — pre-flight check before renaming a symbol; returns `safe` verdict and all `affectedSites` (call, import, type-reference, string-literal, comment) with file, line, column, and context snippet
+- `check_delete_safe` — pre-flight check before deleting a symbol; returns `safe: false` if anything in the repo still imports or references the symbol
+- `check_move_safe` — pre-flight check before moving a symbol to a different file; validates no import conflicts and lists all import statements that need updating
+- `plan_refactoring` — generate a sequenced, dependency-ordered plan for a structural change from a natural-language description; steps ordered so lower-risk changes happen first
+
+**Health dashboards & debt reporting (Phase 31)**
+- `health_radar` — five-axis health score (complexity, coupling, maintainability, documentation, stability), each 0–100; returns `overallHealth` score and letter grade (A–F); designed for CI health gates
+- `diff_health_radar` — compare two health radar snapshots (before/after a refactoring) with axis-by-axis deltas and regression/improvement verdicts
+- `get_debt_report` — detailed technical debt report with per-file rankings, priority tiers, worst files by each metric, specific symbols to address, and estimated effort indicators
+
+**AST-level search (Phase 32)**
+- `search_ast` — find every occurrence of a specific tree-sitter node type across all indexed files (e.g. `try_statement`, `arrow_function`, `await_expression`); returns file, line, column, and snippet
+- `search_by_signature` — search symbols by type signature pattern (regex or substring); find all functions returning `Promise<void>` or methods accepting a `Request` parameter
+- `search_by_decorator` — find all symbols annotated with a specific decorator; works for TypeScript (`@Injectable`, `@Controller`) and Python (`@app.route`, `@property`) decorators
+- `search_by_complexity` — find symbols above or below a complexity threshold; returns symbols ranked by complexity score; use before refactoring sprints or to enforce complexity budgets
+
+**Code intelligence helpers (Phase 33)**
+- `get_entry_points` — identify all runnable entry points: main functions, CLI handlers, HTTP server startups, Lambda handlers, test suites, and scripts; each result includes `kind`, `confidence`, and reason
+- `get_public_api` — all exported symbols grouped by file; use to document a library, audit what is exposed, or check for accidental exports
+- `get_todos` — find all TODO, FIXME, HACK, NOTE, and XXX comments across the repo with file, line, tag type, and comment text
+- `get_complexity_hotspots` — symbols ranked by complexity score, highest first; use to identify the worst functions before a refactoring sprint
+- `get_type_graph` — type dependency graph showing which types reference which other types, rooted at a specific type or across the whole repo; supports `uses`, `usedBy`, and `both` directions
+- `find_untested_symbols` — exported symbols with no corresponding test coverage, ranked by complexity (highest priority first); uses import-based heuristics
+- `get_test_coverage_map` — per-file coverage map showing which symbols are referenced by test files and which are not; produces `coverageRatio` per file and aggregated totals
+
+**Documentation guides**
+- `AST-SEARCH.md` — guide to AST-level search tools and tree-sitter node types
+- `CODE-INTELLIGENCE.md` — guide to code intelligence helper tools
+- `HEALTH-DASHBOARDS.md` — guide to health radar, debt reporting, and architecture snapshots
+- `REFACTORING-SAFELY.md` — guide to refactoring safety check tools and pre-flight workflows
+- `UNDERSTANDING-RELATIONSHIPS.md` — guide to relationship analysis tools (call hierarchy, class hierarchy, coupling)
+- `VISUALIZING-CODE.md` — guide to diagram rendering tools and Mermaid output
+- `WORKFLOW-TECH-DEBT.md` — end-to-end tech debt sprint workflow
+
+### Fixed
+
+- Token savings tracker: corrected cumulative savings calculation and fixed display in web UI
+- Web UI: dependency graph and repo detail pages now render correctly after token tracker refactor
+- Docker: UI workspace panel and repo list routing fixes
+
+---
+
 ## [1.1.0] - 2026-05-07
 
 ### Added