purecontext-mcp 1.1.1 → 1.1.2

package/docs/dev/feature-analysis.md

@@ -1,305 +0,0 @@
-# PureContext MCP — Advanced Feature Analysis
-
-## Purpose of This Document
-
-This document provides a detailed analysis of five advanced PureContext MCP features: AI Summarization, Git History Integration, Cross-Repo Intelligence, Architectural Analysis, and Ecosystem Tools. For each feature, we examine benefits from two perspectives: the **AI agent** consuming the MCP tools, and the **developer/user** who benefits from the agent's improved capabilities.
-
----
-
-## 1. AI Summarization
-
-### What It Does
-
-AI Summarization generates one-line descriptions for every symbol (function, class, method, type, etc.) in the indexed codebase. It follows a priority chain: extracted docstring first, then framework-derived descriptions, then AI-generated summaries (via Claude Haiku, GPT-4o-mini, Gemini Flash, or a local model), and finally a signature-based fallback. Summaries are cached in SQLite and never regenerated for unchanged symbols.
-
-### Benefits for the AI Agent
-
-| Benefit | Explanation |
-|---------|-------------|
-| **Navigate without reading source** | When `search_symbols` returns 20 results, the agent reads signatures + summaries to pick the right one. Without summaries, the agent would need to call `get_symbol_source` on every candidate — costing 10-50x more tokens. |
-| **Semantic search quality** | The HNSW vector index embeds summaries alongside signatures. Richer summaries produce better embeddings, which means `search_semantic` returns more relevant results for natural-language queries like "function that validates JWT tokens." |
-| **Faster decision-making** | A summary like "Validates JWT token and returns authenticated user" lets the agent immediately decide whether to fetch the source. Without it, the agent sees only `function authenticate(token: string): Promise<User>` — informative but ambiguous about implementation details. |
-| **Context bundle efficiency** | When `get_context_bundle` traverses dependencies, each node includes its summary. The agent can scan a 20-symbol dependency tree by reading summaries alone and only fetch source for the 2-3 symbols it actually needs to modify. |
-| **Reduced hallucination risk** | When the agent knows what a function does (from a summary), it is less likely to make incorrect assumptions about behavior during code modification tasks. |
-
-### Benefits for the Developer
-
-| Benefit | Explanation |
-|---------|-------------|
-| **Massive token cost savings** | Without summaries, agents read far more source code. On a 1,000-symbol project, summaries can save 50,000+ tokens per session — translating to $0.75+ per session on Claude Opus, or $15+ per developer per week. |
-| **Better agent accuracy** | When the agent understands what code does before modifying it, the developer gets fewer incorrect suggestions, fewer broken refactors, and less back-and-forth correction. |
-| **Documentation as a side effect** | Even if your codebase lacks JSDoc/docstrings, AI summarization means the index always has human-readable descriptions. Developers reviewing `get_repo_outline` output get useful descriptions for every symbol. |
-| **Cost-effective** | Summarizing a 1,000-symbol undocumented project costs $0.01-0.05. Well-documented codebases cost nearly nothing because docstrings are extracted for free. |
-| **Incentivizes good documentation** | The priority chain means docstrings are always preferred over AI. Developers who write JSDoc get deterministic, zero-cost summaries. This creates a virtuous cycle: better docs lead to better agent performance lead to more motivation to write docs. |
-
-### How an Agent Should Use It
-
-1. **Always check summaries before fetching source.** After `search_symbols`, read the `summary` field. Only call `get_symbol_source` for symbols where the summary confirms relevance.
-2. **Use hybrid search to leverage summaries.** `search_symbols({ mode: "hybrid" })` searches both names and summary content, finding symbols even when you don't know the exact name.
-3. **Trust but verify.** Summaries describe intent; source code is ground truth. For modification tasks, always read the source after using the summary to navigate.
-
----
-
-## 2. Git History Integration
-
-### What It Does
-
-During indexing, PureContext walks `git log`, parses diffs, and maps changed byte ranges to indexed symbols. This creates a symbol-level git history stored in SQLite. Three capabilities result: `get_symbol_history` (commits that touched a specific symbol), `get_churn_metrics` (file/symbol change frequency), and PR/diff analysis (symbol-level impact of a branch).
-
-### Benefits for the AI Agent
-
-| Benefit | Explanation |
-|---------|-------------|
-| **Understand code evolution without git commands** | Agents don't need to run `git log`, `git blame`, or `git diff` as shell commands — which are slow, token-expensive (raw git output is verbose), and require parsing. `get_symbol_history` returns structured JSON with exactly the relevant commits. |
-| **Risk assessment before modification** | Before changing a function, the agent can check churn metrics. A function with 47 commits in the last month is either under active development (risk of merge conflicts) or chronically buggy (risk of introducing new bugs). Either way, the agent should proceed with extra caution. |
-| **Authorship-aware suggestions** | `get_symbol_history` includes author information. If the agent is asked "who wrote this code?" or "who should review this change?", it can answer from the index without running git commands. |
-| **PR review preparation** | When asked to review a PR, the agent can call the diff analysis tool to understand the symbol-level impact — not just "which files changed" but "which functions were added/modified/deleted and what depends on them." This is far more useful context than raw file diffs. |
-| **Prioritize investigation** | When debugging, the agent can use `get_churn_metrics` to identify recently-changed symbols — because recent changes are the most likely source of new bugs. This narrows the search space dramatically. |
-
-### Benefits for the Developer
-
-| Benefit | Explanation |
-|---------|-------------|
-| **Smarter code reviews** | Instead of asking the agent to "review this PR," the developer gets symbol-level analysis: "This PR modifies `authenticateUser` (changed 47 times in the last 3 months, churn score 8.4 — a hotspot) and adds a new `validateMFA` function. `authenticateUser` has 14 reverse dependents that should be tested." |
-| **Evidence-based refactoring decisions** | Churn metrics reveal which files are genuinely problematic vs. merely old. A file with high churn AND low quality score is a strong refactoring candidate. A file with low churn and low quality might be legacy code that works fine and isn't worth touching. |
-| **No context-switching to git** | Developers don't need to leave the agent conversation to run git commands. The agent can answer "when was this last changed?" or "what changed in this function recently?" directly. |
-| **Onboarding acceleration** | New team members can ask the agent "what's the history of this module?" and get a structured answer with the key commits, authors, and changes — without reading through hundreds of git log entries. |
-| **Pre-change impact awareness** | Before asking the agent to modify a high-churn function, the developer sees the history context and can make an informed decision about whether this is the right time to change it (e.g., is someone else actively working on it?). |
-
-### How an Agent Should Use It
-
-1. **Check churn before modifying.** Before changing any symbol, call `get_churn_metrics` to understand its change frequency. If churnScore > 6, mention this to the user and suggest extra testing.
-2. **Use history for debugging.** When investigating a bug, check `get_symbol_history` for recently changed functions in the affected area. Recent changes are the most likely cause.
-3. **Use diff analysis for PR reviews.** When reviewing a PR, call the diff analysis tool first to get the symbol-level impact, then selectively fetch source for the modified symbols.
-
----
-
-## 3. Cross-Repo Intelligence
-
-### What It Does
-
-Cross-repo tools enable searching across multiple indexed repositories simultaneously. `search_cross_repo` finds symbols by name/meaning across all repos in a workspace. `find_similar` uses the HNSW vector index to discover semantically similar code across repo boundaries. Cross-repo dependency tracking follows import relationships between repos. MCP Resources provide push-based subscriptions so agents can monitor specific symbols for changes.
-
-### Benefits for the AI Agent
-
-| Benefit | Explanation |
-|---------|-------------|
-| **Unified view of microservices** | In a microservices architecture, the same concept (e.g., "authenticate") exists in multiple repos with different implementations. `search_cross_repo` lets the agent find all of them in one call, rather than indexing and searching each repo individually. |
-| **Duplication detection** | `find_similar` discovers copy-pasted or independently-reimplemented logic across repos. When the agent is asked to implement a `formatCurrency` function, it can first check if one already exists somewhere in the organization. This prevents duplicate implementations. |
-| **Cross-repo impact analysis** | With `crossRepoDeps` configured, `get_blast_radius` follows dependency chains across repo boundaries. When modifying a shared library function, the agent can identify all downstream repos that would be affected. |
-| **Proactive suggestions** | When creating a new function, the agent can search for similar code and say: "There's already a `formatMoney` function in the billing-service repo with 94% similarity. Consider using it or extracting a shared utility." |
-| **Live monitoring via MCP Resources** | Agents can subscribe to critical symbols and be notified when they change. This enables reactive workflows — e.g., "whenever `authenticateUser` changes, re-run the security audit." |
-
-### Benefits for the Developer
-
-| Benefit | Explanation |
-|---------|-------------|
-| **Eliminate organizational silos** | In large organizations, teams often don't know what code exists in other repos. Cross-repo search breaks down these walls. A developer working on the billing service can discover useful utilities in the payments repo they didn't know about. |
-| **Reduce code duplication** | Duplication across repos is one of the hardest problems in large codebases because no single developer sees all the code. `find_similar` makes invisible duplication visible, enabling extraction into shared libraries. |
-| **Safer cross-repo changes** | When modifying a shared package, the developer (via the agent) can see exactly which repos and functions would be affected. This prevents breaking downstream consumers. |
-| **Faster onboarding to multi-repo environments** | New developers working in a microservices ecosystem can ask "how is authentication implemented across our services?" and get a cross-cutting view instead of having to explore each repo individually. |
-| **Data-driven consolidation** | When leadership asks "should we merge these two services?", `find_similar` provides quantitative data on code overlap, and cross-repo dependency tracking shows the coupling between them. |
-
-### How an Agent Should Use It
-
-1. **Before implementing new functionality**, search across repos with `find_similar` to check if equivalent code already exists.
-2. **Before modifying shared library code**, use `get_blast_radius` with `crossRepo: true` to understand the full downstream impact across all repos.
-3. **Use `search_cross_repo` for architectural questions** like "which services handle email sending?" or "where is the `UserProfile` type defined?"
-
----
-
-## 4. AI-Powered Architecture Analysis
-
-### What It Does
-
-Architecture analysis tools use the symbol graph, dependency data, and optionally AI to compute quality metrics, detect anti-patterns, generate architecture documentation, identify refactoring candidates, and provide smart context bundling. Specifically: `get_quality_metrics` scores files on complexity/coupling/cohesion/documentation, `detect_antipatterns` finds god classes/circular deps/dead code/etc., `get_architecture_doc` generates markdown or Mermaid architecture diagrams, and the refactoring detector prioritizes improvement candidates.
-
-### Benefits for the AI Agent
-
-| Benefit | Explanation |
-|---------|-------------|
-| **Quantified code quality** | Instead of the agent making subjective assessments ("this file looks complex"), it gets metrics: complexity 6.2, fan-out 8, cohesion 0.71, composite score 72/100. This enables data-driven recommendations. |
-| **Structured anti-pattern detection** | The agent doesn't need to manually scan for god classes, circular dependencies, or dead code. `detect_antipatterns` returns structured results with severity levels, specific file/symbol locations, and actionable descriptions. |
-| **Automatic architecture documentation** | When asked "how is this project structured?", the agent can call `get_architecture_doc` to generate an accurate, current architecture summary — rather than inferring it from file names and imports (which is slow and error-prone). |
-| **Refactoring prioritization** | The refactoring detector identifies candidates and assigns priority (high/medium/low) based on multiple signals: size, complexity, coupling, and duplication. The agent can present these to the developer in priority order. |
-| **Smart context bundling** | When fetching context for a modification task, the agent can use quality-aware strategies. The "churn" strategy prioritizes recently-changed dependencies (most likely to be relevant). The "quality" strategy prioritizes well-documented dependencies (most likely to be understood correctly). |
-
-### Benefits for the Developer
-
-| Benefit | Explanation |
-|---------|-------------|
-| **Objective codebase health assessment** | Quality metrics provide an objective, reproducible measure of code health. Developers can track scores over time, set thresholds for CI gates, and justify refactoring efforts with data. |
-| **Automated code review insights** | During PR review, the agent can run `detect_antipatterns` and flag new anti-patterns introduced by the PR. This catches structural issues that unit tests don't cover. |
-| **Always-current architecture docs** | Architecture documentation becomes stale the moment it's written. `get_architecture_doc` generates documentation from the actual code structure, so it's always accurate. |
-| **Strategic refactoring** | Instead of refactoring whatever feels messy, developers get a prioritized list of candidates with clear reasons: "processAuthRequest is 120 lines with cyclomatic complexity 18 — extract validation and transformation logic." This makes refactoring sprints 2-3x more productive. |
-| **Onboarding** | New developers can request an architecture doc and get a Mermaid diagram + markdown summary of the project. This provides the big-picture understanding that usually takes weeks to develop. |
-| **Pre/post refactoring verification** | Run `detect_antipatterns` before and after a refactoring to verify that anti-patterns were actually resolved. This closes the feedback loop that typically only exists in code review. |
-
-### How an Agent Should Use It
-
-1. **Pre-refactoring workflow:**
-   - `get_quality_metrics` to find the worst files
-   - `detect_antipatterns` to find structural issues
-   - `get_blast_radius` to understand impact scope
-   - `get_architecture_doc` to generate a "before" snapshot
-   - Make the changes
-   - `detect_antipatterns` again to verify resolution
-2. **When asked about code quality**, always use `get_quality_metrics` rather than making subjective assessments from reading source code.
-3. **When onboarding to a new codebase**, call `get_architecture_doc` early to build a mental model before diving into specific symbols.
-
----
-
-## 5. Ecosystem & Data Tools
-
-### What It Does
-
-Ecosystem tools extend PureContext beyond application code into data infrastructure. The **context provider framework** is a plugin system for domain-specific enrichment. Three built-in providers exist: **dbt** (column lineage, upstream/downstream model dependencies, Jinja expansion), **OpenAPI/Swagger** (endpoint indexing with request/response schemas), and **SQL** (table/view/function/procedure indexing). Additionally, `search_columns` searches column definitions across dbt models and SQL tables.
-
-### Benefits for the AI Agent
-
-| Benefit | Explanation |
-|---------|-------------|
-| **Data pipeline navigation** | Without ecosystem tools, agents cannot navigate dbt projects meaningfully — `.sql` files with Jinja templating are opaque to standard code search. With the dbt provider, `{{ ref('orders') }}` is resolved and the agent can traverse model dependencies just like code imports. **Note:** Jinja preprocessing is scoped specifically to dbt's SQL dialect. Other templating systems (Helm/Go templates in Kubernetes YAML, Ansible Jinja2 in playbooks, ERB) are not currently preprocessed and those files would be indexed as plain YAML/text. |
-| **Column-level lineage** | `search_columns` returns not just where a column is defined but its full upstream/downstream lineage. When the agent is asked "where does the `revenue` column come from?", it can trace the chain from source tables through staging models to final fact tables. |
-| **API specification awareness** | The OpenAPI provider indexes endpoints as symbols. The agent can use `search_symbols(query: "users", kind: "route")` to find all user-related API endpoints. Each endpoint includes its parameters, request body schema, and response schema. |
-| **Unified code + data search** | A single `search_symbols` call can return both application code (the `calculateRevenue` function) and data pipeline code (the `fct_revenue` dbt model). This unified view is critical for understanding how data flows from database to API to frontend. |
-| **Custom provider extensibility** | The `ContextProvider` interface lets teams add domain-specific enrichment (e.g., a Terraform provider that enriches infrastructure symbols with cloud resource metadata). Agents benefit from richer metadata without any changes to the agent itself. |
-
-### Benefits for the Developer
-
-| Benefit | Explanation |
-|---------|-------------|
-| **Data team productivity** | Data engineers and analysts can ask the agent to navigate dbt projects with the same efficiency as application code. "Find the model that calculates monthly revenue" works via `search_symbols`, and "what feeds into fct_orders?" works via `get_context_bundle`. |
-| **Cross-domain traceability** | For full-stack applications with data pipelines, the developer can trace a data point from the database schema (SQL handler) through the ETL pipeline (dbt provider) to the API endpoint (OpenAPI provider) to the frontend component (application code). This end-to-end traceability is extremely difficult to achieve manually. |
-| **Schema change impact analysis** | Before changing a database column, the developer can use `search_columns` to find all dbt models that reference it, then use `get_blast_radius` to find all downstream models and API endpoints affected. This prevents silent data pipeline breakages. |
-| **API design review** | When OpenAPI specs are indexed, the agent can answer questions like "which endpoints accept a `userId` parameter?" or "show me all POST endpoints" — making API reviews and audits faster. |
-| **Reduced context switching** | Data engineers typically switch between dbt docs, SQL clients, and code editors. With PureContext indexing all of these, the agent conversation becomes a single point of access for navigating the entire data stack. |
-
-### How an Agent Should Use It
-
-1. **For dbt projects**, always run `index_folder` after `dbt compile` to ensure `manifest.json` is current.
-2. **Use `search_columns` for data lineage questions** — it returns upstream/downstream lineage that `search_symbols` doesn't.
-3. **Combine data tools with graph tools** — use `get_context_bundle` to traverse dbt model dependencies just like code dependencies.
-4. **Use `search_symbols` with `kind: "route"` for API navigation** — this leverages the OpenAPI provider to find endpoints.
-
----
-
-## Cross-Feature Synergies
-
-These five features are most powerful when combined. Here are the key synergies:
-
-### Summarization + Semantic Search + Cross-Repo
-AI summaries improve embedding quality, which improves `search_semantic` results, which powers `find_similar` in cross-repo search. Better summaries lead directly to better duplication detection across repos.
-
-### Git History + Architecture Analysis
-Churn metrics from git history feed into quality scores and refactoring prioritization. A file with high complexity AND high churn is a much stronger refactoring candidate than one with high complexity but zero churn (stable legacy code).
-
-### Cross-Repo + Ecosystem Tools
-In a microservices architecture, `search_cross_repo` can find both the API endpoint (OpenAPI provider) in the gateway service and the dbt model (dbt provider) in the analytics repo that consumes data from that endpoint. This cross-cutting view spans both code and data.
-
-### Architecture Analysis + Git History + Summarization
-`get_architecture_doc` uses AI to generate natural-language descriptions of the architecture. The quality of this output depends on symbol summaries (from AI Summarization) and can be enriched with churn data (from Git History) to highlight active vs. stable areas.
-
-### Smart Context Bundling (all features combined)
-Smart context bundling in `get_context_bundle` uses quality metrics (Architecture Analysis), churn data (Git History), and summaries (AI Summarization) to intelligently select which dependencies to include within a token budget. This is the ultimate expression of all features working together to minimize token usage while maximizing agent effectiveness.
-
----
-
-## 6. Known Gaps & Limitations
-
-This section documents what each feature area does **not** currently support. Gaps marked **[workaround]** have a partial mitigation; gaps marked **[future]** are on the roadmap but not yet implemented.
-
----
-
-### AI Summarization
-
-| Gap | Impact | Notes |
-|-----|--------|-------|
-| **No summary invalidation when AI model changes** | Summaries cached by an older model version persist after a model upgrade. | Force regeneration with `index_folder({ force: true })`, which re-summarizes all symbols. |
-| **English-only summaries** | AI-generated summaries are always in English regardless of the language of surrounding code comments. | No workaround; docstring extraction respects the original language, so well-documented codebases are unaffected. |
-| **Summaries are intent, not contract** | A summary describes what a function is meant to do, not what it actually does. Incorrect summaries in poorly-tested code can mislead the agent. | Always verify with `get_symbol_source` before modifying. |
-| **Local model quality variance** | Local Ollama models produce substantially lower-quality summaries than Claude Haiku or GPT-4o-mini, which degrades semantic search recall. | Use a hosted model for semantic-search-heavy workflows; use local only for cost-sensitive offline environments. |
-| **No summary staleness signal** | There is no indication that a summary was generated before recent code changes. A symbol refactored after its summary was cached will have a stale description until re-indexed. | The file watcher triggers incremental re-indexing on save — summaries for changed symbols are regenerated automatically if `ai.allowRemoteAI` is true. |
-
----
-
-### Git History Integration
-
-| Gap | Impact | Notes |
-|-----|--------|-------|
-| **Rename/move breaks history continuity** | When a file is renamed or moved, git rename detection is best-effort. Symbols in the renamed file start fresh history from the rename commit; prior history is lost. | **[future]** A rename-tracking pass using `git log --follow` would close this gap. |
-| **Rebase invalidates commit hashes** | After a rebase, all commit hashes change. A re-index is needed to rebuild accurate history. | Run `invalidate_cache` + `index_folder` after a significant rebase. |
-| **`maxCommits` caps deep history** | The default limit of 500 commits means long-lived projects lose early history. Raising this increases indexing time proportionally. | Increase `git.maxCommits` for history-sensitive workflows; leave it low for large active repos where only recent history matters. |
-| **Git-only** | No support for SVN, Mercurial, or Perforce. Projects not tracked by git get no history, churn, or diff analysis. | No workaround; git is a hard requirement for this feature set. |
-| **No external issue/PR linking** | `get_symbol_history` returns commit messages but cannot link them to GitHub/GitLab issues or Jira tickets. | **[future]** A GitHub API provider (Phase 20 scaffolding exists) could correlate commits to PR metadata. |
-| **Submodules not indexed** | Git submodules are skipped entirely — their history and symbols are invisible. | Index each submodule as a separate repo and use cross-repo tools to connect them. **[workaround]** |
-
----
-
-### Cross-Repo Intelligence
-
-| Gap | Impact | Notes |
-|-----|--------|-------|
-| **`crossRepoDeps` is manual** | Cross-repo dependency tracking requires explicitly listing package names in each repo's config. There is no auto-detection of workspace packages (Nx, Turborepo, Lerna, pnpm workspaces). | **[future]** Auto-detection by reading `package.json` workspaces or `pnpm-workspace.yaml` would eliminate the manual step. |
-| **`find_similar` requires semantic search** | Similarity search uses the HNSW vector index, which is only built when `semantic.enabled: true` and a provider is configured. Teams that cannot use an external embedding API cannot use `find_similar`. | Use a local Ollama embedding model as a zero-cost alternative. **[workaround]** |
-| **MCP Resources subscription client support** | The push-based symbol monitoring (`resources/subscribe`) works only with MCP clients that implement the `resources/subscribe` method. Most current clients do not. | Claude Code and Cursor do not yet implement this — the feature is effectively unavailable in practice today. |
-| **No cross-repo auth model** | All indexed repos are treated as equally accessible. There is no per-repo access control for `search_cross_repo` — if a repo is indexed, it is searchable by anyone with access to the workspace. | Manage access at the workspace level (separate workspaces for different trust boundaries). |
-| **Monorepo packages need separate indexing** | In an Nx or Turborepo monorepo, each package/app must be indexed individually with `index_folder`. The root-level `index_folder` does not auto-discover sub-packages as separate repos. | **[future]** Monorepo workspace detection would make this seamless. |
-
----
-
-### AI-Powered Architecture Analysis
-
-| Gap | Impact | Notes |
-|-----|--------|-------|
-| **`get_architecture_doc` requires remote AI** | Architecture doc generation calls the configured AI provider (`ai.allowRemoteAI: true`). Air-gapped or cost-constrained environments cannot use it. | `detect_antipatterns` and `get_quality_metrics` are fully static and work without AI. |
-| **Quality metrics are point-in-time** | There is no historical trend tracking for quality scores. You cannot ask "is this file's quality improving or degrading over time?" | **[future]** Combining with git history (churn + quality) gives a proxy — high churn + low score signals degradation. **[workaround]** |
-| **Cyclomatic complexity is estimated** | Complexity is computed from symbol count and nesting depth heuristics, not true AST branch-counting. Estimates are less accurate for languages with complex control flow (Haskell, Elixir, Scala). | Treat complexity scores as directional signals, not precise measurements. |
-| **Anti-pattern detection is static only** | `detect_antipatterns` cannot detect runtime coupling, dynamic dispatch patterns, or issues that only emerge at runtime (e.g., a god class that delegates through reflection). | Static analysis is complementary to, not a replacement for, profiling and runtime observability. |
-| **Layer violation detection requires manual config** | `get_layer_violations` needs layer boundaries defined explicitly in config. It has no default understanding of your architecture's intended layers. | Requires upfront investment to define the layer rules before the tool delivers value. |
-| **Refactoring detector cannot distinguish intentional complexity** | A highly complex function that is complex by design (e.g., a parser, a state machine) is flagged the same as an accidentally complex function. | The `reason` field in refactoring candidates is descriptive, not prescriptive — the developer decides whether to act on it. |
-
----
-
-### Ecosystem & Data Tools
-
-#### Templating Language Coverage
-
-This is the most significant gap in the ecosystem feature area. Jinja preprocessing is implemented only for dbt's SQL dialect. All other templating systems are unsupported:
-
-| Templating System | File Types | Current Behavior | Gap |
-|---|---|---|---|
-| **dbt Jinja (SQL)** | `*.sql` in dbt projects | Fully supported — `{{ ref() }}`, `{{ source() }}`, `{% if/for/set %}` expanded before parsing | None |
-| **Helm / Go templates** | `*.yaml` chart templates | Indexed as raw YAML — `{{ .Values.x }}` expressions are treated as literal text; most templates fail YAML parsing and are skipped | No Go template preprocessor |
-| **Ansible Jinja2** | `*.yaml` playbooks, roles | Same as above — Jinja2 expressions in YAML break the YAML parser | No Jinja2-in-YAML preprocessor |
-| **Kubernetes raw YAML** | `*.yaml` manifests | Only indexed if the file contains an `openapi:` or `swagger:` key (OpenAPI handler). Plain k8s manifests are skipped. | No Kubernetes manifest handler |
-| **ERB (Ruby)** | `*.erb` | Not indexed — no ERB handler | No ERB handler or preprocessor |
-| **Kustomize** | `kustomization.yaml` | Skipped — no Kustomize handler | No Kustomize handler |
-| **Nunjucks / Twig** | `*.njk`, `*.html.twig` | Not indexed | No handler |
-
-**Impact for agent and developer:** Infrastructure-heavy teams (Platform Engineering, DevOps, SRE) using Helm or Ansible cannot navigate their IaC templates with PureContext. Kubernetes manifest search, Helm chart dependency analysis, and Ansible role navigation all require falling back to raw file reads.
-
-**Workaround:** Terraform is fully supported via `src/handlers/terraform.ts`. For Kubernetes-adjacent infrastructure, structure resources as Terraform modules rather than Helm charts where possible.
-
-#### Other Ecosystem Gaps
-
-| Gap | Impact | Notes |
-|-----|--------|-------|
-| **dbt Jinja preprocessing is regex-based** | Complex nested Jinja (macros that call other macros, multi-level conditionals) may not strip cleanly, leaving malformed SQL that tree-sitter cannot parse. | Simple dbt models (the majority) work correctly. Complex macro-heavy models may produce incomplete symbol extraction. |
-| **`dbt compile` is a prerequisite** | `manifest.json` must be current before indexing. Stale manifests produce incorrect column lineage. This is not enforced automatically — the indexer does not know if `manifest.json` is stale. | **[future]** Auto-detection of manifest age vs. source file modification times would allow a warning or auto-recompile trigger. |
-| **SQL dialect coverage is incomplete** | The `tree-sitter-sql` grammar handles standard SQL reasonably well but vendor-specific syntax in BigQuery (STRUCT, ARRAY), Snowflake (QUALIFY, SAMPLE), and DuckDB (LIST, MAP) may produce parse errors or missed symbols. | dbt model-level symbols (the file itself) are always extracted even when the body fails to parse — so search still finds the model, just without CTEs or internal structure. |
-| **`search_columns` is dbt-only** | Despite the name, `search_columns` only searches the `provider_metadata` table populated by the dbt provider. Columns defined in raw SQL `CREATE TABLE` statements (indexed by the SQL handler) are not included. | Use `get_symbol_source` on a `CREATE TABLE` symbol to read its column definitions directly. **[workaround]** |
-| **No official third-party provider SDK** | The `ContextProvider` interface is extensible, but there is no documentation, scaffolding, or testing utilities for writing third-party providers. Teams wanting to build a Terraform cloud provider, a Datadog metrics provider, or similar must read the source to understand the contract. | **[future]** A provider development guide and a provider starter template would lower the barrier significantly. |
-| **OpenAPI handler conflicts with other YAML files** | The OpenAPI handler registers for `.yaml`, `.yml`, and `.json` extensions and uses content detection (`openapi:` key) to self-select. In projects with many large YAML config files, the content-scan adds a small indexing overhead for every YAML file. | Not a correctness issue, only a minor performance concern at scale. |
-
----
-
-## Summary Table
-
-| Feature | Primary Agent Benefit | Primary Developer Benefit | Token Impact |
-|---------|----------------------|--------------------------|-------------|
-| AI Summarization | Navigate by summary, not source | Lower API costs, better accuracy | 50-80% reduction in navigation tokens |
-| Git History | Risk assessment, debugging aid | Smarter reviews, evidence-based refactoring | Eliminates verbose git command output |
-| Cross-Repo Intelligence | Unified multi-repo search | Eliminate silos, reduce duplication | Single query replaces N per-repo queries |
-| Architecture Analysis | Quantified quality data | Objective health metrics, auto-docs | Smart bundling optimizes token budgets |
-| Ecosystem Tools | Data pipeline navigation | Cross-domain traceability | Indexes data artifacts like code symbols |

package/docs/dev/phase-1-notes.md

@@ -1,3 +0,0 @@
-The one thing worth noting after phase 1 is done: the handler bug fix (getChildText char vs byte offsets) is documented in memory, but if you ever revisit the buildSignature function, it
-has the same latent issue — it uses source.toString('utf8', node.startIndex, endByte) which would also misbehave for files with multi-byte chars before the symbol. Not a Phase 2
-blocker, just worth knowing.