@eduardo-afonso/codebase-intelligence 0.1.0 → 2.0.0

package/README.md

@@ -16,6 +16,8 @@ Codebase Intelligence acts as a foundational "Knowledge Graph" for your code. It
 - **Dependency Graph**: Builds a directed graph of imports, `extends`, and `implements`.
 - **Code Search**: Lexical and structural search across files and symbols.
 - **Impact Analysis**: Understand the direct and indirect consequences of modifying any given file, including related test files.
+- **Diff Impact Analysis**: Given Git changes (a branch, staged files, uncommitted edits), answer *"what does this set of changes affect?"* — conservatively, at file granularity, without inventing relationships.
+- **Context Engine**: Build token-budgeted, LLM-ready context payloads using three strategies (shallow, signature, deep).
 - **CLI Included**: Run analyses and queries directly from your terminal.
 
 ---
@@ -23,7 +25,7 @@ Codebase Intelligence acts as a foundational "Knowledge Graph" for your code. It
 ## Installation
 
 ```bash
-npm install codebase-intelligence
+npm i @eduardo-afonso/codebase-intelligence
 ```
 
 *(Note: Currently in MVP phase. Ensure your project has TypeScript setup to use properly).*
@@ -86,6 +88,51 @@ Returns files that directly depend on the target file.
 ### `codebase.impact(file: string): ImpactResult`
 Returns `{ direct: string[], indirect: string[], tests: string[] }`, revealing the full blast radius of a change to the given file.
 
+### `codebase.impactOfFiles(paths: string[]): ChangeSetImpact`
+Pure, synchronous impact analysis without querying Git. Treats all given relative paths as `modified` and resolves their dependents from the graph.
+
+```typescript
+const impact = codebase.impactOfFiles(['src/auth/AuthService.ts']);
+console.log(impact.direct);          // direct importers
+console.log(impact.indirect);        // transitive dependents
+console.log(impact.tests);           // test files (by naming convention)
+console.log(impact.globalChanges);   // config files that affect everything
+console.log(impact.unanalyzable);    // files that couldn't be traced + why
+```
+
+### `codebase.impactOfChanges(options?, provider?): Promise<ChangeSetImpact>`
+Queries a `ChangeSetProvider` (Git by default) to determine which files changed, then maps that to a `ChangeSetImpact`.
+
+```typescript
+// Changes introduced by the current branch vs main:
+const impact = await codebase.impactOfChanges({ since: 'main' });
+
+// Only staged changes:
+const staged = await codebase.impactOfChanges({ staged: true });
+
+// All uncommitted changes (including untracked files):
+const uncommitted = await codebase.impactOfChanges();
+
+// Custom provider (e.g. GitHub PR API, test stub):
+const impact = await codebase.impactOfChanges({}, myCustomProvider);
+```
+
+**`ChangeSetImpact` shape:**
+```typescript
+{
+  changed: FileChange[];               // raw list from the provider
+  direct: string[];                    // files that directly import a changed file
+  indirect: string[];                  // transitive dependents (minus direct)
+  tests: string[];                     // test files by naming convention
+  globalChanges: string[];             // e.g. package.json, tsconfig.json
+  unanalyzable: { path, reason }[];    // files that couldn't be traced
+  unresolvedDependencies: string[];    // unresolvable import specifiers
+  metadata: { granularity: 'file'; base?: string; head?: string };
+}
+```
+
+> ⚠️ **Granularity note**: the analysis operates at **file granularity**. A one-line change marks *all* dependents of that file as potentially affected. The result is a conservative upper bound.
+
 ---
 
 ## CLI Reference
@@ -105,8 +152,36 @@ npx codebase-intelligence dependencies "src/auth/AuthService.ts" .
 # View what depends on a file
 npx codebase-intelligence dependents "src/auth/AuthService.ts" .
 
-# View the full impact of a file
-npx codebase-intelligence impact "src/auth/AuthService.ts" .
+# ── Impact Analysis ─────────────────────────────────────────────────────
+
+# Classic file-mode: impact of a single file
+npx codebase-intelligence impact src/auth/AuthService.ts .
+
+# Diff mode: what does changing since main affect? (merge-base comparison)
+npx codebase-intelligence impact . --since main
+
+# Diff mode: only staged changes
+npx codebase-intelligence impact . --staged
+
+# Diff mode: all uncommitted changes + untracked files
+npx codebase-intelligence impact . --uncommitted
+
+# Output as JSON (clean on stdout, suitable for piping)
+npx codebase-intelligence impact . --since main --format json
+
+# Print only related test paths — useful in CI scripts
+npx codebase-intelligence impact . --since main --tests-only
+
+# ── Context & Chunking ───────────────────────────────────────────────────
+
+# Generate an LLM-ready context payload for a file (including dependencies)
+npx codebase-intelligence context "src/auth/AuthService.ts" --strategy signature .
+
+# Generate semantic chunks for the codebase
+npx codebase-intelligence chunks . --max-tokens 512
+
+# Estimate token usage for the entire codebase
+npx codebase-intelligence tokens .
 ```
 
 ---
@@ -125,12 +200,12 @@ For deeper architectural details, see [docs/architecture.md](docs/architecture.m
 
 ## Roadmap
 
-The current version (MVP) establishes the deterministic structural analysis of a codebase. Future versions will introduce:
+The current version establishes the deterministic structural analysis of a codebase, includes the **Context Engine** for semantic chunking and RAG pipelines, and now features **Diff Impact Analysis** for Git change sets. Future versions will introduce:
 
-- **AI Adapters**: Interfaces to connect external LLMs (OpenAI, Anthropic, Gemini, Ollama).
-- **RAG & Embeddings Pipeline**: Automatic chunking and vector storage integrations for semantic code search.
-- **Context Engine**: Tools to dynamically generate context payloads for LLMs based on the dependency graph.
+- **AI Adapters**: Concrete implementations to connect external LLMs (OpenAI, Anthropic, Gemini, Ollama) and Vector Stores (Qdrant, Chroma).
 - **Multi-language Support**: Expanding the `ParserRegistry` to handle Python, Go, and C#.
+- **Symbol-level Granularity**: Narrowing impact analysis from file-level to the specific changed symbols.
+- **Incremental Indexing**: Avoid full re-analysis on every run by detecting changed files from the index cache.
 
 ---
 

package/README.pt-BR.md

@@ -16,6 +16,8 @@ O Codebase Intelligence funciona como um "Grafo de Conhecimento" fundamental par
 - **Grafo de Dependências**: Constrói um grafo direcionado de imports, `extends` e `implements`.
 - **Busca de Código**: Busca léxica e estrutural em arquivos e símbolos.
 - **Análise de Impacto**: Entenda as consequências diretas e indiretas de modificar qualquer arquivo, incluindo arquivos de teste relacionados.
+- **Análise de Impacto de Diferenças (Diff Impact)**: Dado um conjunto de alterações no Git (um branch, arquivos em stage, edições não commitadas), descubra *"o que este conjunto de mudanças afeta?"* — de forma conservadora, na granularidade do arquivo, sem inventar relações.
+- **Context Engine**: Crie payloads de contexto prontos para LLMs, com controle de tokens, usando três estratégias (shallow, signature, deep).
 - **CLI Incluída**: Execute análises e consultas diretamente pelo terminal.
 
 ---
@@ -23,7 +25,7 @@ O Codebase Intelligence funciona como um "Grafo de Conhecimento" fundamental par
 ## Instalação
 
 ```bash
-npm install codebase-intelligence
+npm i @eduardo-afonso/codebase-intelligence
 ```
 
 *(Nota: Atualmente em fase de MVP. Certifique-se de que seu projeto tenha o TypeScript configurado para uso adequado).*
@@ -86,6 +88,52 @@ Retorna os arquivos que dependem diretamente do arquivo informado.
 ### `codebase.impact(file: string): ImpactResult`
 Retorna `{ direct: string[], indirect: string[], tests: string[] }`, revelando o raio de impacto completo de uma alteração no arquivo informado.
 
+### `codebase.impactOfFiles(paths: string[]): ChangeSetImpact`
+Análise de impacto pura e síncrona sem consultar o Git. Trata todos os caminhos relativos fornecidos como `modificados` e resolve as suas dependências através do grafo.
+
+```typescript
+// O que é afetado se alterar utils.ts?
+const impact = codebase.impactOfFiles(['src/utils.ts']);
+console.log(impact.direct);          // importadores diretos
+console.log(impact.indirect);        // dependentes transitivos
+console.log(impact.tests);           // arquivos de teste (por convenção)
+console.log(impact.globalChanges);   // arquivos globais (afetam tudo)
+console.log(impact.unanalyzable);    // arquivos não indexados e porquê
+```
+
+### `codebase.impactOfChanges(options?, provider?): Promise<ChangeSetImpact>`
+Consulta um `ChangeSetProvider` (Git por defeito) para determinar quais os arquivos alterados, mapeando-os para um `ChangeSetImpact`.
+
+```typescript
+// Alterações introduzidas pela branch atual vs main:
+const impact = await codebase.impactOfChanges({ since: 'main' });
+
+// Apenas arquivos em stage:
+const staged = await codebase.impactOfChanges({ staged: true });
+
+// Todas as alterações não commitadas (incluindo arquivos untracked):
+const uncommitted = await codebase.impactOfChanges();
+
+// Provider personalizado (ex: API de PR do GitHub, mock de teste):
+const impact = await codebase.impactOfChanges({}, meuProvider);
+```
+
+**Formato de `ChangeSetImpact`:**
+```typescript
+{
+  changed: FileChange[];               // lista bruta do provider
+  direct: string[];                    // arquivos que importam um arquivo alterado
+  indirect: string[];                  // dependentes transitivos (excluindo direct)
+  tests: string[];                     // arquivos de teste por convenção de nomes
+  globalChanges: string[];             // ex: package.json, tsconfig.json
+  unanalyzable: { path, reason }[];    // arquivos não rastreáveis
+  unresolvedDependencies: string[];    // imports impossíveis de resolver
+  metadata: { granularity: 'file'; base?: string; head?: string };
+}
+```
+
+> ⚠️ **Nota sobre granularidade**: a análise opera na **granularidade de arquivo**. Uma alteração de uma linha marca *todos* os dependentes desse arquivo como potencialmente afetados. O resultado é um limite superior conservador.
+
 ---
 
 ## Referência da CLI
@@ -105,8 +153,36 @@ npx codebase-intelligence dependencies "src/auth/AuthService.ts" .
 # Exibe o que depende de um arquivo
 npx codebase-intelligence dependents "src/auth/AuthService.ts" .
 
-# Exibe o impacto completo de um arquivo
-npx codebase-intelligence impact "src/auth/AuthService.ts" .
+# ── Análise de Impacto ──────────────────────────────────────────────────
+
+# Modo de arquivo clássico: impacto de um único arquivo
+npx codebase-intelligence impact src/auth/AuthService.ts .
+
+# Modo Diff: o que afetam as mudanças desde a branch main? (comparação merge-base)
+npx codebase-intelligence impact . --since main
+
+# Modo Diff: apenas arquivos em stage
+npx codebase-intelligence impact . --staged
+
+# Modo Diff: todas as alterações não commitadas + arquivos untracked
+npx codebase-intelligence impact . --uncommitted
+
+# Saída em JSON (limpo em stdout, ideal para scripts)
+npx codebase-intelligence impact . --since main --format json
+
+# Imprime apenas caminhos de testes relacionados — útil em CI
+npx codebase-intelligence impact . --since main --tests-only
+
+# ── Context Engine & Chunking ────────────────────────────────────────────
+
+# Gera um payload de contexto pronto para LLMs para um arquivo (incluindo dependências)
+npx codebase-intelligence context "src/auth/AuthService.ts" --strategy signature .
+
+# Gera chunks semânticos para a base de código
+npx codebase-intelligence chunks . --max-tokens 512
+
+# Estima o uso de tokens de toda a base de código
+npx codebase-intelligence tokens .
 ```
 
 ---
@@ -125,12 +201,12 @@ Para detalhes arquiteturais mais profundos, veja [docs/architecture.md](docs/arc
 
 ## Roadmap
 
-A versão atual (MVP) estabelece a análise estrutural determinística de uma base de código. Versões futuras irão introduzir:
+A versão atual estabelece a análise estrutural determinística de uma base de código, inclui o **Context Engine** para chunking semântico e pipelines de RAG, e agora inclui **Análise de Impacto de Diferenças (Diff Impact)** para as alterações no Git. Versões futuras irão introduzir:
 
-- **Adaptadores de IA**: Interfaces para conectar LLMs externos (OpenAI, Anthropic, Gemini, Ollama).
-- **Pipeline de RAG e Embeddings**: Chunking automático e integrações de armazenamento vetorial para busca semântica de código.
-- **Context Engine**: Ferramentas para gerar dinamicamente payloads de contexto para LLMs com base no grafo de dependências.
+- **Adaptadores de IA**: Implementações concretas para conectar LLMs externos (OpenAI, Anthropic, Gemini, Ollama) e Vector Stores (Qdrant, Chroma).
 - **Suporte Multi-linguagem**: Expansão do `ParserRegistry` para suportar Python, Go e C#.
+- **Granularidade a nível de Símbolo**: Reduzindo a análise de impacto ao nível do arquivo para os símbolos especificamente alterados.
+- **Indexação Incremental**: Evita a re-análise completa a cada execução detetando arquivos alterados da cache.
 
 ---
 
@@ -144,4 +220,4 @@ Contribuições são bem-vindas. Por favor, certifique-se de que você:
 
 ## Licença
 
-Licença ISC. Veja o arquivo `LICENSE` para mais detalhes.
+Licença ISC. Veja o arquivo `LICENSE` para mais detalhes.

package/dist/ai/CodebaseWithAI.d.ts

@@ -0,0 +1,91 @@
+import type { AIProvider } from '../context/interfaces.js';
+import type { ContextOptions, LLMContextPayload } from '../context/types.js';
+import type { Codebase } from '../core/Codebase.js';
+/** Options accepted by `CodebaseWithAI.explain()`. */
+export interface ExplainOptions extends ContextOptions {
+    /**
+     * Optional instruction appended to the system prompt.
+     * Use to tailor the explanation style, e.g. `'Focus on security implications'`.
+     */
+    instruction?: string;
+}
+/** Options accepted by `CodebaseWithAI.ask()`. */
+export interface AskOptions {
+    /**
+     * Maximum number of top search results to include as context.
+     * @default 3
+     */
+    topK?: number;
+    /**
+     * Context strategy applied when building each file's payload.
+     * @default 'signature'
+     */
+    strategy?: ContextOptions['strategy'];
+    /**
+     * Token budget for each individual context payload.
+     * @default 4000
+     */
+    maxTokens?: number;
+}
+/**
+ * Composes a `Codebase` with an `AIProvider` to expose high-level AI APIs.
+ *
+ * Consumers obtain an instance via `codebase.withAI(provider)`:
+ * ```ts
+ * const cbWithAI = codebase.withAI(new OpenAIProvider());
+ *
+ * const explanation = await cbWithAI.explain('src/auth/AuthService.ts');
+ * const answer = await cbWithAI.ask('Como funciona a autenticação?');
+ * ```
+ *
+ * This class is intentionally thin: it delegates context-building to the
+ * `ContextEngine` and text-completion to the injected `AIProvider`.
+ * No LLM SDK is imported here.
+ */
+export declare class CodebaseWithAI {
+    private readonly codebase;
+    private readonly provider;
+    constructor(codebase: Codebase, provider: AIProvider);
+    /**
+     * Generates a natural-language explanation of the given file.
+     *
+     * The implementation:
+     * 1. Builds an `LLMContextPayload` for the file using the specified strategy.
+     * 2. Serialises the nodes as a Markdown-fenced code block per node.
+     * 3. Constructs a system prompt that includes project metadata.
+     * 4. Calls `provider.complete(prompt, systemPrompt)` and returns the result.
+     *
+     * @param file    - Absolute or codebase-relative path to the file to explain.
+     * @param options - Context and explanation options.
+     * @returns The provider's plain-text response, or `''` for stub providers.
+     */
+    explain(file: string, options?: ExplainOptions): Promise<string>;
+    /**
+     * Answers a free-text question about the codebase.
+     *
+     * The implementation:
+     * 1. Uses `codebase.search()` to find the most relevant files.
+     * 2. Builds context payloads for the top-K results.
+     * 3. Concatenates the serialised nodes into a single prompt.
+     * 4. Calls `provider.complete(prompt, systemPrompt)` and returns the result.
+     *
+     * @param question - Natural-language question about the codebase.
+     * @param options  - Search and context options.
+     * @returns The provider's plain-text response, or `''` for stub providers.
+     */
+    ask(question: string, options?: AskOptions): Promise<string>;
+    /**
+     * Exposes the prompt that `explain()` would send to the provider.
+     * Useful for debugging, logging, or prompt tuning without incurring
+     * LLM cost.
+     */
+    buildExplainPayload(file: string, options?: ExplainOptions): Promise<{
+        prompt: string;
+        systemPrompt: string;
+        payload: LLMContextPayload;
+    }>;
+    private buildExplainPrompt;
+    private buildAskPrompt;
+    private buildSystemPrompt;
+}
+//# sourceMappingURL=CodebaseWithAI.d.ts.map

package/dist/ai/CodebaseWithAI.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CodebaseWithAI.d.ts","sourceRoot":"","sources":["../../src/ai/CodebaseWithAI.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAGpD,sDAAsD;AACtD,MAAM,WAAW,cAAe,SAAQ,cAAc;IACpD;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,kDAAkD;AAClD,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IACtC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,cAAc;IAEvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAF3B,YACmB,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,UAAU,EACnC;IAIJ;;;;;;;;;;;;OAYG;IACU,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAKhF;IAED;;;;;;;;;;;;OAYG;IACU,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CA6B5E;IAED;;;;OAIG;IACU,mBAAmB,CAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,iBAAiB,CAAA;KAAE,CAAC,CAO/E;IAID,OAAO,CAAC,kBAAkB;IA8B1B,OAAO,CAAC,cAAc;IAmBtB,OAAO,CAAC,iBAAiB;CAuB1B"}

package/dist/ai/CodebaseWithAI.js

@@ -0,0 +1,149 @@
+/**
+ * Composes a `Codebase` with an `AIProvider` to expose high-level AI APIs.
+ *
+ * Consumers obtain an instance via `codebase.withAI(provider)`:
+ * ```ts
+ * const cbWithAI = codebase.withAI(new OpenAIProvider());
+ *
+ * const explanation = await cbWithAI.explain('src/auth/AuthService.ts');
+ * const answer = await cbWithAI.ask('Como funciona a autenticação?');
+ * ```
+ *
+ * This class is intentionally thin: it delegates context-building to the
+ * `ContextEngine` and text-completion to the injected `AIProvider`.
+ * No LLM SDK is imported here.
+ */
+export class CodebaseWithAI {
+    codebase;
+    provider;
+    constructor(codebase, provider) {
+        this.codebase = codebase;
+        this.provider = provider;
+    }
+    // ---- Public API -------------------------------------------------------
+    /**
+     * Generates a natural-language explanation of the given file.
+     *
+     * The implementation:
+     * 1. Builds an `LLMContextPayload` for the file using the specified strategy.
+     * 2. Serialises the nodes as a Markdown-fenced code block per node.
+     * 3. Constructs a system prompt that includes project metadata.
+     * 4. Calls `provider.complete(prompt, systemPrompt)` and returns the result.
+     *
+     * @param file    - Absolute or codebase-relative path to the file to explain.
+     * @param options - Context and explanation options.
+     * @returns The provider's plain-text response, or `''` for stub providers.
+     */
+    async explain(file, options = {}) {
+        const payload = await this.codebase.context().forFile(file, options);
+        const prompt = this.buildExplainPrompt(payload);
+        const systemPrompt = this.buildSystemPrompt(options.instruction);
+        return this.provider.complete(prompt, systemPrompt);
+    }
+    /**
+     * Answers a free-text question about the codebase.
+     *
+     * The implementation:
+     * 1. Uses `codebase.search()` to find the most relevant files.
+     * 2. Builds context payloads for the top-K results.
+     * 3. Concatenates the serialised nodes into a single prompt.
+     * 4. Calls `provider.complete(prompt, systemPrompt)` and returns the result.
+     *
+     * @param question - Natural-language question about the codebase.
+     * @param options  - Search and context options.
+     * @returns The provider's plain-text response, or `''` for stub providers.
+     */
+    async ask(question, options = {}) {
+        const { topK = 3, strategy = 'signature', maxTokens = 4_000 } = options;
+        const searchOpts = { limit: topK };
+        const results = this.codebase.search(question, searchOpts);
+        if (results.length === 0) {
+            const systemPrompt = this.buildSystemPrompt();
+            return this.provider.complete(`Question: ${question}\n\nNo relevant files were found in the codebase.`, systemPrompt);
+        }
+        const contextEngine = this.codebase.context();
+        const payloads = [];
+        for (const result of results) {
+            try {
+                const payload = await contextEngine.forFile(result.file, { strategy, maxTokens });
+                payloads.push(payload);
+            }
+            catch {
+                // Skip files that fail context building (e.g. not in index)
+            }
+        }
+        const prompt = this.buildAskPrompt(question, payloads);
+        const systemPrompt = this.buildSystemPrompt();
+        return this.provider.complete(prompt, systemPrompt);
+    }
+    /**
+     * Exposes the prompt that `explain()` would send to the provider.
+     * Useful for debugging, logging, or prompt tuning without incurring
+     * LLM cost.
+     */
+    async buildExplainPayload(file, options = {}) {
+        const payload = await this.codebase.context().forFile(file, options);
+        return {
+            prompt: this.buildExplainPrompt(payload),
+            systemPrompt: this.buildSystemPrompt(options.instruction),
+            payload,
+        };
+    }
+    // ---- Prompt builders --------------------------------------------------
+    buildExplainPrompt(payload) {
+        const sections = [
+            `# Explain: \`${payload.target}\``,
+            '',
+            `**Strategy**: ${payload.strategy} | **~${payload.totalTokenEstimate} tokens**`,
+            '',
+        ];
+        if (payload.metadata.directDependencies.length > 0) {
+            sections.push(`**Direct dependencies**: ${payload.metadata.directDependencies.join(', ')}`, '');
+        }
+        sections.push('## Source code\n');
+        for (const node of payload.nodes) {
+            const label = node.kind === 'file'
+                ? `File: ${node.relativePath}`
+                : `${node.kind}: ${node.symbolName ?? node.relativePath}`;
+            sections.push(`### ${label}\n`);
+            sections.push(`\`\`\`typescript\n${node.content}\n\`\`\`\n`);
+        }
+        sections.push('\n---\nPlease explain the code above clearly and concisely.');
+        return sections.join('\n');
+    }
+    buildAskPrompt(question, payloads) {
+        const sections = ['# Codebase Context\n'];
+        for (const payload of payloads) {
+            sections.push(`## File: \`${payload.target}\`\n`);
+            for (const node of payload.nodes) {
+                const label = node.kind === 'file'
+                    ? node.relativePath
+                    : `${node.kind}: ${node.symbolName ?? node.relativePath}`;
+                sections.push(`### ${label}\n`);
+                sections.push(`\`\`\`typescript\n${node.content}\n\`\`\`\n`);
+            }
+        }
+        sections.push(`\n---\n# Question\n\n${question}`);
+        return sections.join('\n');
+    }
+    buildSystemPrompt(extraInstruction) {
+        const projectInfo = this.codebase.projectInfo();
+        const parts = [
+            'You are an expert software engineer analysing a codebase.',
+        ];
+        if (projectInfo) {
+            const langs = projectInfo.languages.join(', ');
+            const frameworks = projectInfo.frameworks.join(', ');
+            if (langs)
+                parts.push(`The project uses: ${langs}.`);
+            if (frameworks)
+                parts.push(`Frameworks detected: ${frameworks}.`);
+        }
+        parts.push('Answer precisely and concisely. Cite specific symbols, files, and line references when relevant.');
+        if (extraInstruction) {
+            parts.push(extraInstruction);
+        }
+        return parts.join(' ');
+    }
+}
+//# sourceMappingURL=CodebaseWithAI.js.map

package/dist/ai/CodebaseWithAI.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CodebaseWithAI.js","sourceRoot":"","sources":["../../src/ai/CodebaseWithAI.ts"],"names":[],"mappings":"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"}

package/dist/ai/RAGPipeline.d.ts

@@ -0,0 +1,66 @@
+import type { SemanticChunker, SemanticChunk } from '../context/SemanticChunker.js';
+import type { EmbeddingProvider, VectorStore } from '../context/interfaces.js';
+import type { Codebase } from '../core/Codebase.js';
+/**
+ * Options for instantiating the RAG pipeline.
+ */
+export interface RAGPipelineOptions {
+    /**
+     * Responsible for dividing codebase files into semantically meaningful
+     * text chunks before embedding.
+     */
+    chunker: SemanticChunker;
+    /**
+     * Converts text chunks into dense numeric vectors.
+     * This is provided by an external integration (e.g. Ollama, OpenAI).
+     */
+    embedder: EmbeddingProvider;
+    /**
+     * Storage layer for the embeddings and chunk metadata, used for
+     * fast similarity search. Provided by an external integration (e.g. Qdrant).
+     */
+    store: VectorStore;
+}
+/**
+ * Orchestrates the Retrieval-Augmented Generation (RAG) pipeline for a codebase.
+ *
+ * It coordinates the extraction of semantic chunks, their conversion to
+ * embeddings, and storage in a vector database for semantic search.
+ *
+ * @example
+ * ```ts
+ * const pipeline = new RAGPipeline({
+ *   chunker: new SemanticChunker(),
+ *   embedder: new OllamaEmbeddingProvider({ model: 'nomic-embed-text' }),
+ *   store: new QdrantVectorStore({ url: 'http://localhost:6333' }),
+ * });
+ *
+ * await pipeline.index(codebase);
+ * const results = await pipeline.search('authentication logic');
+ * ```
+ */
+export declare class RAGPipeline {
+    private chunker;
+    private embedder;
+    private store;
+    constructor(options: RAGPipelineOptions);
+    /**
+     * Processes the entire codebase: generates semantic chunks, embeds them,
+     * and upserts the vectors and metadata into the vector store.
+     *
+     * @param codebase The fully analyzed codebase.
+     */
+    index(codebase: Codebase): Promise<void>;
+    /**
+     * Performs a semantic search over the indexed codebase.
+     *
+     * Embeds the query text and retrieves the closest matching chunks
+     * from the vector store.
+     *
+     * @param query The natural language search query.
+     * @param topK  The maximum number of results to return. Default is 5.
+     * @returns     The top matching semantic chunks.
+     */
+    search(query: string, topK?: number): Promise<SemanticChunk[]>;
+}
+//# sourceMappingURL=RAGPipeline.d.ts.map

package/dist/ai/RAGPipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RAGPipeline.d.ts","sourceRoot":"","sources":["../../src/ai/RAGPipeline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACpF,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC/E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAGpD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,OAAO,EAAE,eAAe,CAAC;IACzB;;;OAGG;IACH,QAAQ,EAAE,iBAAiB,CAAC;IAC5B;;;OAGG;IACH,KAAK,EAAE,WAAW,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,QAAQ,CAAoB;IACpC,OAAO,CAAC,KAAK,CAAc;IAE3B,YAAY,OAAO,EAAE,kBAAkB,EAItC;IAED;;;;;OAKG;IACU,KAAK,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAuCpD;IAED;;;;;;;;;OASG;IACU,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,MAAU,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CA4B7E;CACF"}