@eduardo-afonso/codebase-intelligence 0.1.0

package/README.md

@@ -0,0 +1,147 @@
+# Codebase Intelligence
+
+**Codebase Intelligence** is a professional-grade Node.js library designed to parse, index, and understand codebases programmatically. It scans files, builds dependency graphs, and indexes symbols (like classes, functions, and interfaces) directly from the AST.
+
+## The Problem It Solves
+
+Modern applications are complex. When developers (or AI agents) need to understand how pieces of code fit together, simple text search (like `grep`) falls short. Finding exactly where a class is used, understanding the impact of modifying a specific file, or tracing transitive dependencies usually requires manual work or a heavy IDE.
+
+Codebase Intelligence acts as a foundational "Knowledge Graph" for your code. It provides structured insights into your codebase, serving as the perfect backbone for AI-assisted development tools, code generation, RAG pipelines, and automated code review systems.
+
+## Features
+
+- **Project Discovery**: Automatically detects project languages, frameworks (React, Next.js, etc.), and package managers.
+- **AST Parsing**: Leverages `ts-morph` for robust, regex-free TypeScript/JavaScript parsing to extract classes, functions, methods, and variables.
+- **Symbol Indexing**: Instantly query your codebase for symbols by name, type, or file.
+- **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.
+- **CLI Included**: Run analyses and queries directly from your terminal.
+
+---
+
+## Installation
+
+```bash
+npm install codebase-intelligence
+```
+
+*(Note: Currently in MVP phase. Ensure your project has TypeScript setup to use properly).*
+
+## Quick Start
+
+You can use the library programmatically in your own scripts:
+
+```typescript
+import { Codebase } from 'codebase-intelligence';
+
+async function run() {
+  // 1. Load the codebase (scans files and detects project info)
+  const codebase = await Codebase.load('./src');
+
+  // 2. Analyze the AST and build the dependency graph
+  await codebase.analyze();
+
+  // 3. Query the data
+  console.log('Total files:', codebase.files().length);
+  
+  // Search for a specific class or function
+  const searchResults = codebase.search('AuthService');
+  console.log('Search Results:', searchResults);
+
+  // Check the impact of a file change
+  const impact = codebase.impact('src/auth/AuthService.ts');
+  console.log('Files directly depending on this:', impact.direct);
+  console.log('Files indirectly depending on this:', impact.indirect);
+}
+
+run();
+```
+
+---
+
+## Public API Reference
+
+### `Codebase.load(path: string, options?: CodebaseOptions): Promise<Codebase>`
+Initializes the instance, scanning the given directory path. `options.ignore` accepts an array of glob patterns to exclude.
+
+### `codebase.analyze(): Promise<void>`
+Parses the discovered files and populates the internal Symbol Index and Dependency Graph. Must be called before querying symbols or dependencies.
+
+### `codebase.files(): CodebaseFile[]`
+Returns all indexed files in the project.
+
+### `codebase.symbols(): CodeSymbol[]`
+Returns all extracted symbols (classes, functions, interfaces, etc.) from the project.
+
+### `codebase.search(query: string, options?: SearchOptions): SearchResult[]`
+Performs a lexical/structural search for files and symbols matching the query.
+
+### `codebase.dependencies(file: string): string[]`
+Returns files that the target file directly depends on (imports).
+
+### `codebase.dependents(file: string): string[]`
+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.
+
+---
+
+## CLI Reference
+
+Codebase Intelligence comes with a CLI for terminal use:
+
+```bash
+# Analyze the current directory and output a summary
+npx codebase-intelligence analyze .
+
+# Search for a specific symbol
+npx codebase-intelligence search "UserService" .
+
+# View what a file depends on
+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" .
+```
+
+---
+
+## Architecture Overview
+
+Codebase Intelligence is designed in modular layers to allow future extensibility (e.g., adding C# or Python parsers):
+
+1. **Discovery Layer**: Responsible for finding files (`FileScanner`) and detecting project properties (`ProjectDetector`).
+2. **Analysis Layer**: Houses parsers (`TypeScriptParser`) that turn raw code into structured `CodeSymbol` and `CodeDependency` objects.
+3. **Knowledge Layer**: Indexes the data for fast retrieval (`SymbolIndex`, `FileIndex`, `DependencyGraph`).
+
+For deeper architectural details, see [docs/architecture.md](docs/architecture.md).
+
+---
+
+## Roadmap
+
+The current version (MVP) establishes the deterministic structural analysis of a codebase. 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.
+- **Multi-language Support**: Expanding the `ParserRegistry` to handle Python, Go, and C#.
+
+---
+
+## Contributing
+
+Contributions are welcome. Please ensure that you:
+1. Discuss major architectural changes in an issue first.
+2. Ensure all tests pass (`npm run test:run`).
+3. Ensure no type errors (`npm run typecheck`).
+4. Avoid introducing unnecessary dependencies. The core library aims to remain lightweight.
+
+## License
+
+ISC License. See the `LICENSE` file for details.

package/README.pt-BR.md

@@ -0,0 +1,147 @@
+# Codebase Intelligence
+
+**Codebase Intelligence** é uma biblioteca Node.js de nível profissional, projetada para analisar, indexar e compreender bases de código (codebases) de forma programática. Ela escaneia arquivos, constrói grafos de dependência e indexa símbolos (como classes, funções e interfaces) diretamente a partir da AST.
+
+## O Problema que Resolve
+
+Aplicações modernas são complexas. Quando desenvolvedores (ou agentes de IA) precisam entender como as partes do código se encaixam, a busca textual simples (como `grep`) não é suficiente. Encontrar exatamente onde uma classe é usada, entender o impacto de modificar um arquivo específico, ou rastrear dependências transitivas geralmente exige trabalho manual ou uma IDE pesada.
+
+O Codebase Intelligence funciona como um "Grafo de Conhecimento" fundamental para o seu código. Ele fornece insights estruturados sobre sua base de código, servindo como a espinha dorsal perfeita para ferramentas de desenvolvimento assistido por IA, geração de código, pipelines de RAG e sistemas automatizados de revisão de código.
+
+## Funcionalidades
+
+- **Descoberta de Projeto**: Detecta automaticamente linguagens do projeto, frameworks (React, Next.js, etc.) e gerenciadores de pacotes.
+- **Análise via AST**: Utiliza o `ts-morph` para uma análise robusta e livre de regex de TypeScript/JavaScript, extraindo classes, funções, métodos e variáveis.
+- **Indexação de Símbolos**: Consulte instantaneamente sua base de código por símbolos, seja por nome, tipo ou arquivo.
+- **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.
+- **CLI Incluída**: Execute análises e consultas diretamente pelo terminal.
+
+---
+
+## Instalação
+
+```bash
+npm install codebase-intelligence
+```
+
+*(Nota: Atualmente em fase de MVP. Certifique-se de que seu projeto tenha o TypeScript configurado para uso adequado).*
+
+## Início Rápido
+
+Você pode usar a biblioteca de forma programática em seus próprios scripts:
+
+```typescript
+import { Codebase } from 'codebase-intelligence';
+
+async function run() {
+  // 1. Carrega a base de código (escaneia arquivos e detecta informações do projeto)
+  const codebase = await Codebase.load('./src');
+
+  // 2. Analisa a AST e constrói o grafo de dependências
+  await codebase.analyze();
+
+  // 3. Consulta os dados
+  console.log('Total de arquivos:', codebase.files().length);
+  
+  // Busca por uma classe ou função específica
+  const searchResults = codebase.search('AuthService');
+  console.log('Resultados da busca:', searchResults);
+
+  // Verifica o impacto de uma alteração em um arquivo
+  const impact = codebase.impact('src/auth/AuthService.ts');
+  console.log('Arquivos que dependem diretamente deste:', impact.direct);
+  console.log('Arquivos que dependem indiretamente deste:', impact.indirect);
+}
+
+run();
+```
+
+---
+
+## Referência da API Pública
+
+### `Codebase.load(path: string, options?: CodebaseOptions): Promise<Codebase>`
+Inicializa a instância, escaneando o diretório informado. `options.ignore` aceita um array de padrões glob para excluir arquivos.
+
+### `codebase.analyze(): Promise<void>`
+Analisa os arquivos descobertos e popula o Índice de Símbolos e o Grafo de Dependências internos. Deve ser chamado antes de consultar símbolos ou dependências.
+
+### `codebase.files(): CodebaseFile[]`
+Retorna todos os arquivos indexados do projeto.
+
+### `codebase.symbols(): CodeSymbol[]`
+Retorna todos os símbolos extraídos (classes, funções, interfaces, etc.) do projeto.
+
+### `codebase.search(query: string, options?: SearchOptions): SearchResult[]`
+Realiza uma busca léxica/estrutural por arquivos e símbolos que correspondam à consulta.
+
+### `codebase.dependencies(file: string): string[]`
+Retorna os arquivos dos quais o arquivo informado depende diretamente (imports).
+
+### `codebase.dependents(file: string): string[]`
+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.
+
+---
+
+## Referência da CLI
+
+O Codebase Intelligence vem com uma CLI para uso no terminal:
+
+```bash
+# Analisa o diretório atual e exibe um resumo
+npx codebase-intelligence analyze .
+
+# Busca por um símbolo específico
+npx codebase-intelligence search "UserService" .
+
+# Exibe as dependências de um arquivo
+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" .
+```
+
+---
+
+## Visão Geral da Arquitetura
+
+O Codebase Intelligence é projetado em camadas modulares para permitir extensibilidade futura (por exemplo, adicionar parsers de C# ou Python):
+
+1. **Camada de Descoberta**: Responsável por encontrar arquivos (`FileScanner`) e detectar propriedades do projeto (`ProjectDetector`).
+2. **Camada de Análise**: Contém os parsers (`TypeScriptParser`) que transformam código bruto em objetos estruturados `CodeSymbol` e `CodeDependency`.
+3. **Camada de Conhecimento**: Indexa os dados para recuperação rápida (`SymbolIndex`, `FileIndex`, `DependencyGraph`).
+
+Para detalhes arquiteturais mais profundos, veja [docs/architecture.md](docs/architecture.md).
+
+---
+
+## 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:
+
+- **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.
+- **Suporte Multi-linguagem**: Expansão do `ParserRegistry` para suportar Python, Go e C#.
+
+---
+
+## Contribuindo
+
+Contribuições são bem-vindas. Por favor, certifique-se de que você:
+1. Discuta mudanças arquiteturais importantes em uma issue primeiro.
+2. Garanta que todos os testes passem (`npm run test:run`).
+3. Garanta que não haja erros de tipo (`npm run typecheck`).
+4. Evite introduzir dependências desnecessárias. A biblioteca principal busca permanecer leve.
+
+## Licença
+
+Licença ISC. Veja o arquivo `LICENSE` para mais detalhes.

package/dist/analysis/DependencyAnalyzer.d.ts

@@ -0,0 +1,8 @@
+import type { DependencyGraph } from '../graph/DependencyGraph.js';
+export declare class DependencyAnalyzer {
+    private graph;
+    constructor(graph: DependencyGraph);
+    dependencies(file: string): string[];
+    dependents(file: string): string[];
+}
+//# sourceMappingURL=DependencyAnalyzer.d.ts.map

package/dist/analysis/DependencyAnalyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DependencyAnalyzer.d.ts","sourceRoot":"","sources":["../../src/analysis/DependencyAnalyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAEnE,qBAAa,kBAAkB;IACjB,OAAO,CAAC,KAAK;IAAzB,YAAoB,KAAK,EAAE,eAAe,EAAI;IAEvC,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAE1C;IAEM,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAExC;CACF"}

package/dist/analysis/DependencyAnalyzer.js

@@ -0,0 +1,13 @@
+export class DependencyAnalyzer {
+    graph;
+    constructor(graph) {
+        this.graph = graph;
+    }
+    dependencies(file) {
+        return this.graph.dependenciesOf(file);
+    }
+    dependents(file) {
+        return this.graph.dependentsOf(file);
+    }
+}
+//# sourceMappingURL=DependencyAnalyzer.js.map

package/dist/analysis/DependencyAnalyzer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DependencyAnalyzer.js","sourceRoot":"","sources":["../../src/analysis/DependencyAnalyzer.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,kBAAkB;IACT,KAAK;IAAzB,YAAoB,KAAsB;qBAAtB,KAAK;IAAoB,CAAC;IAEvC,YAAY,CAAC,IAAY;QAC9B,OAAO,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;IACzC,CAAC;IAEM,UAAU,CAAC,IAAY;QAC5B,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;IACvC,CAAC;CACF"}

package/dist/analysis/ImpactAnalyzer.d.ts

@@ -0,0 +1,25 @@
+import type { DependencyGraph } from '../graph/DependencyGraph.js';
+export interface ImpactResult {
+    direct: string[];
+    indirect: string[];
+    tests: string[];
+}
+/**
+ * Analyzes the impact of changing a file.
+ *
+ * - `direct`: files that directly import/depend on the given file
+ * - `indirect`: all transitive dependents minus the direct ones
+ * - `tests`: discovered by convention only — files whose basename matches
+ *   `<basename>.test.ts`, `<basename>.spec.ts`, `<basename>.test.js`, or
+ *   `<basename>.spec.js` among the nodes in the graph.
+ *   This uses NO relationship proof from the graph itself — it is purely
+ *   name-based convention. If the convention is insufficient for a project,
+ *   the list will be empty.
+ */
+export declare class ImpactAnalyzer {
+    private graph;
+    constructor(graph: DependencyGraph);
+    impact(file: string): ImpactResult;
+    private findRelatedTests;
+}
+//# sourceMappingURL=ImpactAnalyzer.d.ts.map

package/dist/analysis/ImpactAnalyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ImpactAnalyzer.d.ts","sourceRoot":"","sources":["../../src/analysis/ImpactAnalyzer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAEnE,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,cAAc;IACb,OAAO,CAAC,KAAK;IAAzB,YAAoB,KAAK,EAAE,eAAe,EAAI;IAEvC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAUxC;IAED,OAAO,CAAC,gBAAgB;CAezB"}

package/dist/analysis/ImpactAnalyzer.js

@@ -0,0 +1,41 @@
+import * as path from 'path';
+/**
+ * Analyzes the impact of changing a file.
+ *
+ * - `direct`: files that directly import/depend on the given file
+ * - `indirect`: all transitive dependents minus the direct ones
+ * - `tests`: discovered by convention only — files whose basename matches
+ *   `<basename>.test.ts`, `<basename>.spec.ts`, `<basename>.test.js`, or
+ *   `<basename>.spec.js` among the nodes in the graph.
+ *   This uses NO relationship proof from the graph itself — it is purely
+ *   name-based convention. If the convention is insufficient for a project,
+ *   the list will be empty.
+ */
+export class ImpactAnalyzer {
+    graph;
+    constructor(graph) {
+        this.graph = graph;
+    }
+    impact(file) {
+        const direct = this.graph.dependentsOf(file);
+        const directSet = new Set(direct);
+        const allTransitive = this.graph.allDependentsOf(file);
+        const indirect = allTransitive.filter(dep => !directSet.has(dep));
+        const tests = this.findRelatedTests(file);
+        return { direct, indirect, tests };
+    }
+    findRelatedTests(file) {
+        const basename = path.basename(file, path.extname(file));
+        const testSuffixes = ['.test.ts', '.spec.ts', '.test.js', '.spec.js'];
+        const candidateNames = testSuffixes.map(s => `${basename}${s}`);
+        const testFiles = [];
+        for (const node of this.graph.nodes()) {
+            const nodeName = path.basename(node);
+            if (candidateNames.includes(nodeName)) {
+                testFiles.push(node);
+            }
+        }
+        return testFiles;
+    }
+}
+//# sourceMappingURL=ImpactAnalyzer.js.map

package/dist/analysis/ImpactAnalyzer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ImpactAnalyzer.js","sourceRoot":"","sources":["../../src/analysis/ImpactAnalyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAS7B;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,cAAc;IACL,KAAK;IAAzB,YAAoB,KAAsB;qBAAtB,KAAK;IAAoB,CAAC;IAEvC,MAAM,CAAC,IAAY;QACxB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;QAC7C,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;QAElC,MAAM,aAAa,GAAG,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;QACvD,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;QAElE,MAAM,KAAK,GAAG,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;QAE1C,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IACrC,CAAC;IAEO,gBAAgB,CAAC,IAAY;QACnC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QACzD,MAAM,YAAY,GAAG,CAAC,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;QACtE,MAAM,cAAc,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,QAAQ,GAAG,CAAC,EAAE,CAAC,CAAC;QAEhE,MAAM,SAAS,GAAa,EAAE,CAAC;QAC/B,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;YACtC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YACrC,IAAI,cAAc,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACtC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACvB,CAAC;QACH,CAAC;QAED,OAAO,SAAS,CAAC;IACnB,CAAC;CACF"}

package/dist/cli/Watcher.d.ts

@@ -0,0 +1,40 @@
+export type WatchEventHandler = (changedFiles: ReadonlySet<string>) => Promise<void>;
+export interface WatcherOptions {
+    /** Debounce window in ms (default: 300) */
+    debounceMs?: number;
+    /** Called after debounce with the set of changed absolute paths */
+    onChanged: WatchEventHandler;
+    /**
+     * Injection point for tests — replaces the real `fs.watch` call.
+     * The factory receives the directory and a raw event callback, and must
+     * return a { close() } handle.
+     */
+    watchFactory?: (dir: string, signal: AbortSignal, rawHandler: (filename: string) => void) => void;
+}
+/**
+ * Lightweight file watcher built on Node's native `fs.watch` with:
+ * - `recursive: true` (Node ≥ 18.8)
+ * - Configurable debounce window
+ * - Graceful shutdown via AbortController
+ *
+ * `dependenciesOf`/`dependentsOf` are direct (not transitive).
+ * For transitive traversal use `allDependenciesOf` / `allDependentsOf`.
+ */
+export declare class Watcher {
+    private readonly debounceMs;
+    private readonly onChanged;
+    private readonly watchFactory;
+    private abortController;
+    private debounceTimer;
+    private pendingFiles;
+    constructor(opts: WatcherOptions);
+    start(dir: string): void;
+    stop(): void;
+    /**
+     * Exposed for testing: directly enqueue a file change.
+     */
+    _enqueue(absolutePath: string): void;
+    private handleRaw;
+    private scheduleFlush;
+}
+//# sourceMappingURL=Watcher.d.ts.map

package/dist/cli/Watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Watcher.d.ts","sourceRoot":"","sources":["../../src/cli/Watcher.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,iBAAiB,GAAG,CAAC,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAErF,MAAM,WAAW,cAAc;IAC7B,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,SAAS,EAAE,iBAAiB,CAAC;IAC7B;;;;OAIG;IACH,YAAY,CAAC,EAAE,CACb,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,WAAW,EACnB,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,KACnC,IAAI,CAAC;CACX;AAED;;;;;;;;GAQG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoB;IAC9C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAiC;IAE9D,OAAO,CAAC,eAAe,CAAgC;IACvD,OAAO,CAAC,aAAa,CAA8C;IACnE,OAAO,CAAC,YAAY,CAAqB;IAEzC,YAAY,IAAI,EAAE,cAAc,EAI/B;IAEM,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CA4B9B;IAEM,IAAI,IAAI,IAAI,CAQlB;IAID;;OAEG;IACI,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAE1C;IAED,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,aAAa;CAWtB"}

package/dist/cli/Watcher.js

@@ -0,0 +1,80 @@
+import * as fs from 'fs';
+/**
+ * Lightweight file watcher built on Node's native `fs.watch` with:
+ * - `recursive: true` (Node ≥ 18.8)
+ * - Configurable debounce window
+ * - Graceful shutdown via AbortController
+ *
+ * `dependenciesOf`/`dependentsOf` are direct (not transitive).
+ * For transitive traversal use `allDependenciesOf` / `allDependentsOf`.
+ */
+export class Watcher {
+    debounceMs;
+    onChanged;
+    watchFactory;
+    abortController = null;
+    debounceTimer = null;
+    pendingFiles = new Set();
+    constructor(opts) {
+        this.debounceMs = opts.debounceMs ?? 300;
+        this.onChanged = opts.onChanged;
+        this.watchFactory = opts.watchFactory;
+    }
+    start(dir) {
+        if (this.abortController) {
+            throw new Error('Watcher is already running. Call stop() first.');
+        }
+        this.abortController = new AbortController();
+        const signal = this.abortController.signal;
+        if (this.watchFactory) {
+            // Testable path — delegate to injected factory
+            this.watchFactory(dir, signal, (filename) => this.handleRaw(dir, filename));
+        }
+        else {
+            // Production path — native fs.watch
+            const watcher = fs.watch(dir, { recursive: true, signal }, (_event, filename) => {
+                if (filename)
+                    this.handleRaw(dir, filename);
+            });
+            watcher.on('error', (err) => {
+                // AbortError is expected on stop() — swallow it silently
+                if (err.name !== 'AbortError') {
+                    console.error('[watch] error:', err.message);
+                }
+            });
+        }
+    }
+    stop() {
+        if (this.debounceTimer !== null) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+        this.pendingFiles.clear();
+        this.abortController?.abort();
+        this.abortController = null;
+    }
+    // ---- Internal -------------------------------------------------------
+    /**
+     * Exposed for testing: directly enqueue a file change.
+     */
+    _enqueue(absolutePath) {
+        this.handleRaw('', absolutePath, true);
+    }
+    handleRaw(dir, filename, alreadyAbsolute = false) {
+        const fullPath = alreadyAbsolute ? filename : `${dir}/${filename}`.replace(/\\/g, '/');
+        this.pendingFiles.add(fullPath);
+        this.scheduleFlush();
+    }
+    scheduleFlush() {
+        if (this.debounceTimer !== null) {
+            clearTimeout(this.debounceTimer);
+        }
+        this.debounceTimer = setTimeout(async () => {
+            this.debounceTimer = null;
+            const snapshot = new Set(this.pendingFiles);
+            this.pendingFiles.clear();
+            await this.onChanged(snapshot);
+        }, this.debounceMs);
+    }
+}
+//# sourceMappingURL=Watcher.js.map

package/dist/cli/Watcher.js.map

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

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":""}