purecontext-mcp 1.1.7 → 1.2.0

package/REFACTORING-SAFELY.md

@@ -0,0 +1,279 @@
+# Refactoring Safely
+
+Refactoring is risky not because the changes are hard, but because the side effects are invisible. You rename a function and forget about the string-literal reference in a config file. You delete a helper and miss the one call site that imported it from a different path. You move a file and half the codebase's import paths silently break.
+
+PureContext's refactoring safety tools give you a complete impact analysis before you make any change — so you know exactly what you're dealing with before you start.
+
+---
+
+## Before renaming a symbol
+
+Renaming a function, class, or constant affects every file that references it. The question is always: *exactly how many places, which ones, and are there any that a text-replace can't fix automatically?*
+
+**Scenario:** You're renaming `validateToken` to `verifyAuthToken` to align with the new naming convention. Before you do it in your editor, get the full picture.
+
+> "I want to rename validateToken to verifyAuthToken. Is that safe? Show me everywhere it's used."
+
+```
+check_rename_safe(repoId, symbolId: "validateToken-id", newName: "verifyAuthToken") →
+
+  safe: true
+  verdict: "Rename is safe. All references are in import statements and call sites
+            that can be updated automatically. No string-literal references detected."
+
+  Affected files (12):
+    src/auth/index.ts:3        import  — import { validateToken } from './validator'
+    src/auth/index.ts:47       call    — const result = validateToken(req.headers.auth)
+    src/api/middleware/auth.ts:12  import  — import { validateToken } ...
+    src/api/middleware/auth.ts:67  call    — validateToken(bearer)
+    src/api/routes/login.ts:23     call    — if (!validateToken(session)) ...
+    test/auth/validator.test.ts:15  call   — expect(validateToken('expired')).toBe(false)
+    test/auth/validator.test.ts:31  call   — validateToken(validToken)
+    ... (5 more)
+
+  No conflicts: "verifyAuthToken" does not exist in any of these files.
+  No string-literal references that require manual updates.
+```
+
+Safe to proceed. All 12 references are structured code — imports and call sites — that any rename tool can update mechanically. No surprises.
+
+**When it's not safe:**
+
+```
+check_rename_safe(repoId, symbolId: "processPayment-id", newName: "handlePayment") →
+
+  safe: false
+  blockers:
+    1. String-literal reference found:
+       src/config/routes.json:34  "handler": "processPayment"
+       ← This is a string, not a code reference. A rename tool won't catch it.
+
+    2. Name conflict:
+       src/billing/processor.ts already contains a symbol named "handlePayment"
+       ← Two functions with the same name in the same import scope will conflict.
+```
+
+Two blockers. The string-literal reference in `routes.json` needs a manual update — it's used as a string key to look up the handler dynamically. The name conflict needs to be resolved before the rename can proceed.
+
+---
+
+## Before deleting a symbol
+
+Deleting code that's still called causes runtime errors. `check_delete_safe` finds every live reference before you delete anything.
+
+**Scenario:** You think `formatDateLegacy` is dead code. You want to confirm before deleting it.
+
+> "Is formatDateLegacy safe to delete?"
+
+```
+check_delete_safe(repoId, symbolId: "formatDateLegacy-id") →
+
+  safe: true
+  verdict: "No live references found. Symbol is unexported. Safe to delete."
+
+  Risks found:
+    test-subject  test/utils/date.test.ts:45  — test file references this symbol
+                  (informational — deleting will require updating the test)
+```
+
+No production code references it. The only reference is in a test file — which is expected and will need to be cleaned up alongside the deletion. Safe to proceed.
+
+**When there are live references:**
+
+```
+check_delete_safe(repoId, symbolId: "getUserById-id") →
+
+  safe: false
+  verdict: "3 live references found. Deletion would cause runtime errors."
+
+  Risks:
+    live-reference  src/api/routes/users.ts:67
+      const user = getUserById(req.params.id);
+
+    live-reference  src/workers/sync.ts:34
+      const admin = getUserById(config.adminId);
+
+    exported-symbol  (symbol is exported — may be consumed by external packages)
+```
+
+Not safe. Two active call sites would break immediately. The exported flag also indicates external consumers may exist outside the indexed codebase.
+
+**Checking an entire file for deletion:**
+
+> "I want to delete src/legacy/auth-v1.ts entirely. What would break?"
+
+```
+check_delete_safe(repoId, filePath: "src/legacy/auth-v1.ts") →
+
+  safe: false  (aggregate verdict across 8 symbols in this file)
+
+  Breakdown:
+    generateLegacyToken()   → safe: true   (0 references)
+    validateBasicAuth()     → safe: true   (0 references)
+    LegacySession           → safe: false  (2 live references)
+      live-reference  src/api/middleware/legacy-compat.ts:23
+      live-reference  src/workers/migrate-sessions.ts:67
+    ... (5 more symbols, all safe)
+
+  Summary: 2 of 8 symbols have live references. Remove references first.
+```
+
+You can delete most of the file immediately. Two symbols — `LegacySession` — need their callers updated first. The tool tells you exactly which two files.
+
+---
+
+## Before moving a file
+
+Moving a file changes all the import paths that reference it. `check_move_safe` shows you every import that will need updating, and flags any that require manual intervention.
+
+**Scenario:** You're reorganizing the project structure and want to move `src/utils/auth-helpers.ts` into `src/auth/helpers.ts`.
+
+> "If I move auth-helpers.ts to src/auth/helpers.ts, what import paths will break?"
+
+```
+check_move_safe(repoId,
+  filePath: "src/utils/auth-helpers.ts",
+  newFilePath: "src/auth/helpers.ts") →
+
+  safe: true
+  verdict: "All 9 import references use relative paths and can be updated automatically."
+
+  Import updates needed (9 files):
+    src/api/middleware/auth.ts:2
+      current:  import { hashToken } from '../../utils/auth-helpers'
+      updated:  import { hashToken } from '../auth/helpers'
+
+    src/auth/validator.ts:1
+      current:  import { compareHash } from '../utils/auth-helpers'
+      updated:  import { compareHash } from './helpers'
+
+    src/core/session.ts:3
+      current:  import { generateSecret } from '../utils/auth-helpers'
+      updated:  import { generateSecret } from '../auth/helpers'
+
+    ... (6 more, all relative paths)
+
+  manualUpdatesRequired: false
+```
+
+All relative paths — a find-and-replace-style operation can handle this automatically.
+
+**When manual updates are required:**
+
+```
+check_move_safe(repoId,
+  filePath: "src/core/database.ts",
+  newFilePath: "src/db/database.ts") →
+
+  safe: false
+  manualUpdatesRequired: true
+
+  Problems:
+    src/config/jest.config.ts:14
+      moduleNameMapper: { '@core/database': './src/core/database' }
+      ← Path alias in Jest config — not a TypeScript import. Requires manual update.
+
+    src/build/webpack.config.js:56
+      resolve: { alias: { 'core/database': path.resolve('./src/core/database') } }
+      ← Webpack alias. Requires manual update.
+```
+
+The TypeScript imports can be updated automatically. The Jest and Webpack configs use the old path as a string — those need manual updates before the move.
+
+---
+
+## Getting a complete refactoring plan
+
+When the scope is larger — breaking a circular dependency, extracting a module, reducing coupling — `plan_refactoring` synthesizes all the individual safety checks into a sequenced, risk-annotated action plan.
+
+**Scenario:** You want to rename a widely-used symbol, and you want a step-by-step plan rather than a raw impact list.
+
+> "Give me a complete refactoring plan for renaming validateToken to verifyAuthToken."
+
+```
+plan_refactoring(repoId, goal: "rename-symbol",
+  symbolId: "validateToken-id", newName: "verifyAuthToken") →
+
+  Goal: rename-symbol
+  Estimated files: 12
+  Estimated risk: low
+
+  Steps (execute in order):
+
+  1. [LOW RISK] Update test references (2 files)
+     test/auth/validator.test.ts — update 2 call sites
+     test/integration/auth.test.ts — update 1 import + 3 calls
+     Reason: Start with tests — they validate the rename worked correctly.
+
+  2. [LOW RISK] Update leaf callers (4 files)
+     src/api/routes/login.ts — update 1 call site
+     src/api/routes/refresh.ts — update 1 call site
+     src/workers/session-cleanup.ts — update 1 call site
+     src/api/middleware/auth.ts — update 1 import + 2 calls
+     Reason: These files import validateToken but nothing else imports them in this context.
+
+  3. [MEDIUM RISK] Update hub callers (2 files)
+     src/auth/index.ts — update export re-export
+     src/core/auth.ts — update 1 import + 4 calls
+     Reason: These are imported by 8+ other files. Change here last.
+
+  4. [FINAL] Rename the declaration
+     src/auth/validator.ts — rename the function
+     Reason: Always rename the declaration last, after all references are updated.
+
+  Warnings:
+    - After step 4, run index_folder to update the symbol index.
+    - Run tests after each step to catch regressions early.
+```
+
+The plan is sequenced bottom-up: leaf files first, hub files last, the declaration itself final. This minimizes the window between "declaration renamed" and "all references updated," reducing the chance of a broken build.
+
+**Other refactoring goals:**
+
+```
+plan_refactoring(repoId, goal: "delete-symbol", symbolId: "...")
+  → sequenced steps for removing all references then deleting
+
+plan_refactoring(repoId, goal: "break-cycle", filePath: "src/core/auth.ts")
+  → identifies the specific import causing the cycle and how to break it
+
+plan_refactoring(repoId, goal: "extract-module",
+  filePath: "src/utils/helpers.ts", newFilePath: "src/format/currency.ts")
+  → step-by-step extraction with all affected import updates
+
+plan_refactoring(repoId, goal: "reduce-coupling", filePath: "src/core/auth.ts")
+  → identifies the highest-coupling imports and suggests what to decouple
+
+plan_refactoring(repoId, goal: "general", filePath: "src/utils/helpers.ts")
+  → open-ended: surfaces the top structural issues in this file
+```
+
+---
+
+## The pre-change pattern
+
+For any significant structural change, this is the workflow:
+
+```
+1. Run the relevant safety check
+   check_rename_safe / check_delete_safe / check_move_safe
+   → get the verdict and full impact list
+
+2. If safe: get the sequenced plan
+   plan_refactoring(goal: "...")
+   → step-by-step with risk annotations
+
+3. Execute from leaf to hub, test after each step
+
+4. Re-index after all changes
+   index_folder(path, force: false)
+   → incremental, picks up only what changed
+
+5. Verify no dead code was created
+   find_dead_code(repoId)
+   → check nothing is now unreferenced
+```
+
+---
+
+→ Reference: [MCP Tools Reference](docs/06-tools-reference.md) — `check_rename_safe`, `check_delete_safe`, `check_move_safe`, `plan_refactoring`

package/UNDERSTANDING-RELATIONSHIPS.md

@@ -0,0 +1,240 @@
+# Understanding Code Relationships
+
+The dependency graph gives you the broad picture — what imports what. But most real questions about a codebase go deeper: *who implements this interface?*, *what does this function call at runtime?*, *why is this module so hard to change?*, *where are the circular imports that are blocking our refactoring?*
+
+PureContext has a dedicated set of tools for answering these structural questions without reading source files.
+
+---
+
+## Finding all implementations of an interface
+
+When you're working with a codebase that uses interfaces heavily — whether for dependency injection, plugin systems, or polymorphism — you regularly need to know: *what concrete classes actually implement this?*
+
+**Scenario:** You're changing the `UserRepository` interface to add a new method. Before you change the interface, you need to know which classes implement it so you can update them all.
+
+> "Which classes implement the UserRepository interface?"
+
+```
+find_implementations(symbolId: "UserRepository-id") →
+
+  Interface: UserRepository  (src/core/repositories/user.ts)
+
+  Implementations:
+    PostgresUserRepository   src/db/postgres/user-repo.ts    implements all 7 methods ✓
+    InMemoryUserRepository   src/test/mocks/user-repo.ts     implements all 7 methods ✓
+    CachedUserRepository     src/cache/user-repo.ts          missing: batchGet, streamAll ✗
+
+  Total: 3 implementations
+```
+
+You can see immediately that `CachedUserRepository` is incomplete — it's missing two methods. Adding a third method to the interface will require updating all three classes. You know the scope before you change a single line.
+
+**Including abstract subclasses:**
+
+```
+find_implementations(symbolId: "UserRepository-id", includeAbstract: true)
+```
+
+This surfaces abstract classes that extend the interface — useful in Java or Kotlin codebases where abstract base classes form an intermediate layer.
+
+---
+
+## Understanding the call hierarchy
+
+`get_blast_radius` tells you which *files* import a symbol. `get_call_hierarchy` tells you how a function is actually *called at runtime* — the actual call stack, structured as a tree.
+
+**Scenario:** You're investigating a performance issue. The `generateReport` function is slow, but you're not sure if the problem is in the function itself or in something it calls deep down.
+
+> "Show me what generateReport calls, three levels deep."
+
+```
+get_call_hierarchy(symbolId: "generateReport-id", direction: "callees", maxDepth: 3) →
+
+  generateReport()                  [root]
+    ├── fetchReportData()            depth 1 — called 1×
+    │     ├── queryUserEvents()      depth 2 — called 1×
+    │     │     └── buildSQLQuery()  depth 3 — called 3×
+    │     └── queryMetrics()         depth 2 — called 1×
+    │           └── buildSQLQuery()  depth 3 — called 1×  [cyclic: seen above]
+    ├── formatReportRows()           depth 1 — called 1×
+    │     └── formatCurrency()       depth 2 — called N×
+    └── generatePDF()               depth 1 — called 1×
+          └── compressOutput()       depth 2 — called 1×
+
+  Total nodes: 10
+```
+
+`buildSQLQuery` is called four times from two different paths. `formatCurrency` is called in a loop. The tree structure lets you see exactly where the CPU time is going without running a profiler.
+
+**Checking who calls a function:**
+
+> "Who calls sendEmail? I need to know all the places it's triggered."
+
+```
+get_call_hierarchy(symbolId: "sendEmail-id", direction: "callers", maxDepth: 2) →
+
+  sendEmail()                  [root]
+    ├── triggerWelcomeEmail()   depth 1 — src/onboarding/welcome.ts
+    ├── sendPasswordReset()     depth 1 — src/auth/password.ts
+    │     └── resetPassword()   depth 2 — src/api/routes/auth.ts
+    ├── notifyPaymentFailed()   depth 1 — src/billing/notify.ts
+    └── weeklyDigest()          depth 1 — src/workers/digest.ts
+```
+
+Four callers, one with a caller of its own. This is the full list of places that trigger email sending — a complete picture for changing the email system.
+
+---
+
+## Tracing inheritance chains
+
+When working with class hierarchies — especially in enterprise codebases with deep inheritance — you need to understand both directions: what does a class inherit from, and what inherits from it?
+
+**Scenario:** You're refactoring `BaseController`. Before you change it, you want to know the full inheritance chain.
+
+> "Show me the full class hierarchy for BaseController."
+
+```
+get_class_hierarchy(symbolId: "BaseController-id", direction: "both") →
+
+  Ancestors (BaseController extends):
+    BaseController → Object  (external, not indexed)
+
+  Descendants (classes that extend BaseController):
+    BaseController
+      ├── AuthenticatedController
+      │     ├── UserController
+      │     ├── AdminController
+      │     └── ApiController
+      │           ├── RestApiController
+      │           └── GraphQLController
+      └── PublicController
+            └── LandingController
+
+  Total: 9 nodes
+```
+
+Seven classes will be affected by changes to `BaseController`. The deepest chains (`RestApiController`, `GraphQLController`) are four levels of inheritance — a sign that these might benefit from composition instead.
+
+**Checking ancestors only:**
+
+```
+get_class_hierarchy(symbolId: "UserController-id", direction: "ancestors")
+→ UserController → AuthenticatedController → BaseController → Object
+```
+
+---
+
+## Finding circular dependencies
+
+Circular imports are one of the most common causes of "this module is impossible to change independently." They also cause subtle initialization bugs and make testing harder.
+
+**Scenario:** You've noticed that changes to `src/core/` always seem to require changes in `src/utils/`, and vice versa. You suspect a circular dependency.
+
+> "Find all circular imports in the codebase. Start with cycles involving the core directory."
+
+```
+find_cycles(filePath: "src/core/") →
+
+  Cycle 1 (severity: error — tight 2-node cycle):
+    src/core/billing.ts → src/utils/currency.ts → src/core/billing.ts
+
+  Cycle 2 (severity: error — tight 3-node cycle):
+    src/core/auth.ts → src/models/user.ts → src/core/session.ts → src/core/auth.ts
+
+  Cycle 3 (severity: warning — longer chain):
+    src/core/events.ts → src/handlers/payment.ts → src/core/billing.ts
+    → src/core/events.ts
+
+  Total: 3 cycles found
+```
+
+The first cycle is the one you suspected — `billing.ts` and `currency.ts` are mutually dependent. Breaking this cycle (typically by extracting the shared types into a third module that both can import) is the fix.
+
+**Checking cycles in the whole repo:**
+
+```
+find_cycles(maxCycles: 50) → finds all cycles up to the limit
+find_cycles(minLength: 3)  → skips direct mutual imports, shows only longer chains
+```
+
+---
+
+## Measuring coupling
+
+Coupling tells you which files are the most dangerous to change — not because they're complex, but because everything else depends on them.
+
+**Scenario:** You're planning a major refactoring sprint. Before you start, you want to know which files have the highest coupling — both in terms of what they import and what imports them.
+
+> "Which files in src/ have the highest coupling? I want to know where the structural risk is."
+
+```
+get_coupling_map(repoId, topN: 10) →
+
+  src/utils/helpers.ts
+    efferentCoupling (imports): 3      ← imports only 3 files
+    afferentCoupling (imported by): 41 ← but 41 files depend on it
+    instability: 0.07                  ← near 0 = maximally stable = risky to change
+
+  src/core/auth.ts
+    efferentCoupling: 12
+    afferentCoupling: 28
+    instability: 0.30                  ← stable hub
+
+  src/api/middleware/logging.ts
+    efferentCoupling: 18
+    afferentCoupling: 2
+    instability: 0.90                  ← near 1 = leaf node = safe to change
+
+  ...
+```
+
+`helpers.ts` is the hidden risk: 41 files depend on it, but it only imports 3 things. Its instability score of 0.07 means it's a stable hub — every change to it ripples out to 41 files. That's the file to touch last, if at all.
+
+**Inspecting a single file's dependency list:**
+
+> "Who depends on src/core/auth.ts, and what does auth.ts itself depend on?"
+
+```
+get_coupling_map(repoId, filePath: "src/core/auth.ts", direction: "both") →
+
+  Imports (efferent — what auth.ts depends on):
+    src/models/user.ts
+    src/db/queries/auth.ts
+    src/utils/crypto.ts
+    ... (9 more)
+
+  Imported by (afferent — what depends on auth.ts):
+    src/api/middleware/auth-guard.ts
+    src/api/routes/login.ts
+    src/workers/session-cleanup.ts
+    ... (25 more)
+```
+
+---
+
+## Putting it together: pre-refactoring analysis
+
+Before a significant structural refactoring, combine these tools:
+
+```
+1. find_cycles(repoId)
+   → identify which circular deps are blocking modularization
+
+2. get_coupling_map(repoId, topN: 20)
+   → rank files by coupling to find the stable hubs
+
+3. get_class_hierarchy(symbolId)
+   → understand inheritance depth in affected areas
+
+4. find_implementations(symbolId)
+   → know how many classes implement interfaces you plan to change
+
+5. get_call_hierarchy(symbolId, direction: "callers")
+   → verify you've found all callers before changing a function signature
+```
+
+This analysis takes minutes and replaces hours of manual code reading.
+
+---
+
+→ Reference: [MCP Tools Reference](docs/06-tools-reference.md) — `find_implementations`, `get_call_hierarchy`, `get_class_hierarchy`, `find_cycles`, `get_coupling_map`

package/USER-GUIDE.md

@@ -20,6 +20,10 @@ For parameter-level documentation — every tool input, output, and flag — see
 
 - [Making Changes Safely](safe-changes.md) — Blast radius analysis before touching anything, context bundles for understanding dependencies, the full pre-change workflow, and architectural violation detection
 
+- [Understanding Code Relationships](understanding-relationships.md) — Call hierarchies, class hierarchies, interface implementations, circular dependency detection, and coupling maps
+
+- [Refactoring Safely](refactoring-safely.md) — Pre-flight checks before renaming, deleting, or moving symbols. Sequenced, risk-annotated refactoring plans for structural changes.
+
 - [Understanding Code History](code-history.md) — Symbol-level git history (not file-level), churn analysis for identifying risk, ownership mapping, and PR analysis before you read a diff
 
 ---
@@ -32,6 +36,14 @@ For parameter-level documentation — every tool input, output, and flag — see
 
 - [Code Health & Architecture Analysis](code-health.md) — Quality metrics, anti-pattern detection, auto-generated architecture docs, CI enforcement, and finding refactoring opportunities before they become crises
 
+- [Health Dashboards & Debt Reporting](health-dashboards.md) — Five-axis health radar, before/after PR comparisons, and comprehensive debt reports with prioritized action items
+
+- [Visualizing Code Structure](visualizing-code.md) — Mermaid and DOT diagrams of import graphs, call graphs, class hierarchies, and dependency matrices. Architecture snapshots for tracking structural change over time.
+
+- [AST-Level Search](ast-search.md) — Find any tree-sitter node type, search by type signature pattern, find symbols by decorator, and filter by complexity thresholds
+
+- [Code Intelligence](code-intelligence.md) — Entry points, public API surface, TODO inventory, complexity hotspots, type graphs, untested symbols, and coverage mapping
+
 ---
 
 ## For teams and enterprise
@@ -50,6 +62,8 @@ Complete end-to-end examples showing how PureContext fits into real development
 
 - [Reviewing a Pull Request](workflow-pr-review.md) — A 40-file authentication migration PR: structured review in 45 minutes that found two real issues before reading most of the diff
 
+- [Running a Tech Debt Sprint](workflow-tech-debt.md) — Full lifecycle of a two-week debt reduction sprint: assessment, planning, safe execution, and proving the improvement with snapshots
+
 ---
 
 ## Reference Manual