@dastbal/nestjs-ai-agent 1.0.0

package/dist/core/state/db.js

@@ -0,0 +1,118 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentDB = void 0;
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+/**
+ * Singleton Database Manager.
+ * Handles the connection to the local SQLite instance used for caching and state management.
+ */
+class AgentDB {
+    /**
+     * Private constructor to enforce Singleton pattern.
+     */
+    constructor() { }
+    /**
+     * Retrieves the active database connection.
+     * If it doesn't exist, it initializes the DB file and the schema.
+     * * @returns {Database.Database} The SQLite connection instance.
+     */
+    static getInstance() {
+        if (!this.instance) {
+            const rootDir = process.cwd();
+            const dbDir = path.join(rootDir, '.agent'); // Hidden folder in project root
+            const dbPath = path.join(dbDir, 'memory.db');
+            // Ensure directory exists
+            if (!fs.existsSync(dbDir)) {
+                fs.mkdirSync(dbDir, { recursive: true });
+            }
+            console.log(`💾 Connecting to Local State DB: ${dbPath}`);
+            this.instance = new better_sqlite3_1.default(dbPath);
+            // OPTIMIZATION: Write-Ahead Logging makes writing faster and safer
+            this.instance.pragma('journal_mode = WAL');
+            this.initSchema();
+        }
+        return this.instance;
+    }
+    /**
+     * Initializes the database tables based on our architectural plan.
+     * 1. file_registry: Tracks file hashes and cached skeletons.
+     */
+    static initSchema() {
+        const db = this.instance;
+        db.prepare(`
+      CREATE TABLE IF NOT EXISTS file_registry (
+        path TEXT PRIMARY KEY,           -- Absolute or relative path (Unique ID)
+        hash TEXT NOT NULL,              -- MD5 checksum of the full content
+        last_indexed INTEGER NOT NULL,   -- Timestamp (Date.now())
+        skeleton_signature TEXT          -- JSON String of the file structure (Class/Methods signatures)
+      )
+    `).run();
+        // 2. Dependency Graph (Knowledge Graph)
+        // Maps how files relate to each other (imports, inheritance).
+        db.prepare(`
+      CREATE TABLE IF NOT EXISTS dependency_graph (
+        source TEXT NOT NULL,
+        target TEXT NOT NULL,
+        relation TEXT NOT NULL,
+        PRIMARY KEY (source, target),
+        FOREIGN KEY(source) REFERENCES file_registry(path) ON DELETE CASCADE
+      )
+    `).run();
+        // 3. Code Chunks (Vector Store)
+        // Stores the actual code fragments and their vector embeddings.
+        // 'vector_json' stores the float array as a JSON string for simplicity in SQLite.
+        db.prepare(`
+      CREATE TABLE IF NOT EXISTS code_chunks (
+        id TEXT PRIMARY KEY,        -- UUID
+        file_path TEXT NOT NULL,    -- Parent File
+        chunk_type TEXT NOT NULL,   -- 'method' | 'file' | 'class'
+        content TEXT NOT NULL,      -- The actual code text
+        vector_json TEXT,           -- The Embedding [0.1, -0.5, ...]
+        metadata TEXT,              -- JSON extra info (decorators, lines)
+        FOREIGN KEY(file_path) REFERENCES file_registry(path) ON DELETE CASCADE
+      )
+    `).run();
+        // Create indexes for faster retrieval
+        db.prepare(`CREATE INDEX IF NOT EXISTS idx_graph_source ON dependency_graph(source)`).run();
+        db.prepare(`CREATE INDEX IF NOT EXISTS idx_chunks_file ON code_chunks(file_path)`).run();
+    }
+}
+exports.AgentDB = AgentDB;

package/dist/core/state/file-registry.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Represents the database row structure for a file.
+ */
+export interface FileRecord {
+    path: string;
+    hash: string;
+    last_indexed: number;
+    skeleton_signature: string | null;
+}
+/**
+ * Manages the state of the codebase files.
+ * Responsible for detecting changes (hashing) and caching skeletons.
+ */
+export declare class FileRegistry {
+    private db;
+    /**
+     * Checks if a file has changed since the last index.
+     * * @param filePath - Relative path of the file (e.g., 'src/users.service.ts')
+     * @returns {boolean} True if the file is new or modified; False if cached.
+     */
+    isFileChanged(filePath: string): boolean;
+    /**
+     * Updates the registry with the new file state.
+     * This should be called AFTER the vector indexing and skeleton generation is done.
+     * * @param filePath - The path of the file
+     * @param skeleton - The JSON string representing the AST Skeleton (Class/Method signatures)
+     */
+    updateFile(filePath: string, skeleton: object | null): void;
+    /**
+     * Retrieves the cached skeleton for a file.
+     * Used by the LLM Provider to build context without reading the full disk.
+     */
+    getSkeleton(filePath: string): object | null;
+    /**
+     * Helper: Generates MD5 hash of string content.
+     */
+    private computeHash;
+}

package/dist/core/state/file-registry.js

@@ -0,0 +1,112 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileRegistry = void 0;
+const crypto = __importStar(require("crypto"));
+const fs = __importStar(require("fs"));
+const db_1 = require("./db");
+/**
+ * Manages the state of the codebase files.
+ * Responsible for detecting changes (hashing) and caching skeletons.
+ */
+class FileRegistry {
+    constructor() {
+        this.db = db_1.AgentDB.getInstance();
+    }
+    /**
+     * Checks if a file has changed since the last index.
+     * * @param filePath - Relative path of the file (e.g., 'src/users.service.ts')
+     * @returns {boolean} True if the file is new or modified; False if cached.
+     */
+    isFileChanged(filePath) {
+        // 1. If file was deleted or doesn't exist, strictly it "changed" (it's gone),
+        // but for indexing purposes, we skip it or handle cleanup.
+        if (!fs.existsSync(filePath))
+            return true;
+        // 2. Compute current Hash
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const newHash = this.computeHash(content);
+        // 3. Query DB
+        const stmt = this.db.prepare('SELECT hash FROM file_registry WHERE path = ?');
+        const row = stmt.get(filePath);
+        // 4. Decision Logic
+        if (!row) {
+            return true; // New file
+        }
+        if (row.hash !== newHash) {
+            return true; // Modified file
+        }
+        return false; // Pristine (Cached)
+    }
+    /**
+     * Updates the registry with the new file state.
+     * This should be called AFTER the vector indexing and skeleton generation is done.
+     * * @param filePath - The path of the file
+     * @param skeleton - The JSON string representing the AST Skeleton (Class/Method signatures)
+     */
+    updateFile(filePath, skeleton) {
+        if (!fs.existsSync(filePath))
+            return;
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const hash = this.computeHash(content);
+        const now = Date.now();
+        const skeletonStr = skeleton ? JSON.stringify(skeleton) : null;
+        // UPSERT: Insert or Update if exists
+        const stmt = this.db.prepare(`
+      INSERT OR REPLACE INTO file_registry (path, hash, last_indexed, skeleton_signature)
+      VALUES (?, ?, ?, ?)
+    `);
+        stmt.run(filePath, hash, now, skeletonStr);
+    }
+    /**
+     * Retrieves the cached skeleton for a file.
+     * Used by the LLM Provider to build context without reading the full disk.
+     */
+    getSkeleton(filePath) {
+        const stmt = this.db.prepare('SELECT skeleton_signature FROM file_registry WHERE path = ?');
+        const row = stmt.get(filePath);
+        if (row && row.skeleton_signature) {
+            return JSON.parse(row.skeleton_signature);
+        }
+        return null;
+    }
+    /**
+     * Helper: Generates MD5 hash of string content.
+     */
+    computeHash(content) {
+        return crypto.createHash('md5').update(content).digest('hex');
+    }
+}
+exports.FileRegistry = FileRegistry;

package/dist/core/tools/ast/chunker.d.ts

@@ -0,0 +1,58 @@
+import { FileAnalysisResult } from '../../types';
+/**
+ * The Brain Surgeon 🩺
+ * Analyzes TypeScript files using AST to extract intelligent code chunks and dependency graphs.
+ * Optimized for NestJS architecture patterns.
+ */
+export declare class NestChunker {
+    private project;
+    constructor();
+    /**
+     * Analyzes a file content and breaks it down based on its type (Service, DTO, Module).
+     * * @param filePath - The relative path of the file.
+     * @param content - The raw string content of the file.
+     * @param fileHash - The MD5 hash for registry tracking.
+     */
+    analyze(filePath: string, content: string, fileHash: string): FileAnalysisResult;
+    /**
+     * Checks if the file should be treated as a single atomic unit.
+     * Rules: DTOs, Entities, Interfaces, Enums.
+     */
+    private isAtomicFile;
+    /**
+     * Strategy A: Atomic Processing
+     * Stores the whole file as one chunk. Essential for DTOs/Entities context.
+     */
+    private processAtomicFile;
+    /**
+     * Strategy B: Logic Processing (Parent-Child)
+     * Splits Services/Controllers into Class Context (Parent) and Methods (Children).
+     */
+    private processLogicFile;
+    /**
+     * Extracts the "Context" of a class without the heavy method implementation.
+     * Keeps imports (from file), class decorators, properties, and constructor.
+     */
+    private extractClassContext;
+    /**
+     * Extracts static import relationships to build the Dependency Graph.
+     * It parses the AST to find all relative imports and resolves them to physical files.
+     * * @param sourceFile - The AST SourceFile object from ts-morph.
+     * @param sourcePath - The relative path of the file currently being analyzed (e.g., 'src/auth/auth.service.ts').
+     * @returns An array of graph edges representing 'import' relationships.
+     */
+    private extractDependencies;
+    private getClassName;
+    private generateSkeleton;
+    /**
+     * Resolves the physical filesystem path for a given import string.
+     * Handles TypeScript resolution strategies including file extensions and directory indexes.
+     * * @param sourceDir - The absolute directory path of the file containing the import.
+     * @param importPath - The raw import string (e.g., './users.service' or './dto').
+     * @returns The absolute path to the resolved .ts file, or `null` if not found/external.
+     * * @example
+     * resolveModulePath('/src/users', './dto');
+     * // Returns: '/src/users/dto/index.ts'
+     */
+    private resolveModulePath;
+}

package/dist/core/tools/ast/chunker.js

@@ -0,0 +1,297 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NestChunker = void 0;
+const ts_morph_1 = require("ts-morph");
+const uuid_1 = require("uuid");
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs")); // Necesario para verificar si existe el archivo .ts o index.ts
+/**
+ * The Brain Surgeon 🩺
+ * Analyzes TypeScript files using AST to extract intelligent code chunks and dependency graphs.
+ * Optimized for NestJS architecture patterns.
+ */
+class NestChunker {
+    constructor() {
+        // Initialize ts-morph project.
+        // We skip loading the whole tsconfig for speed, processing files individually.
+        this.project = new ts_morph_1.Project({
+            skipAddingFilesFromTsConfig: true,
+            useInMemoryFileSystem: true,
+        });
+    }
+    /**
+     * Analyzes a file content and breaks it down based on its type (Service, DTO, Module).
+     * * @param filePath - The relative path of the file.
+     * @param content - The raw string content of the file.
+     * @param fileHash - The MD5 hash for registry tracking.
+     */
+    analyze(filePath, content, fileHash) {
+        // 1. Create AST from content
+        const sourceFile = this.project.createSourceFile(filePath, content, {
+            overwrite: true,
+        });
+        // 2. Determine Strategy based on file extension/name
+        const isAtomic = this.isAtomicFile(filePath);
+        // 3. Extract Dependencies (Imports) -> For the Knowledge Graph
+        const dependencies = this.extractDependencies(sourceFile, filePath);
+        // 4. Generate Chunks
+        let chunks = [];
+        if (isAtomic) {
+            chunks = this.processAtomicFile(sourceFile);
+        }
+        else {
+            chunks = this.processLogicFile(sourceFile);
+        }
+        // 5. Generate Skeleton (Simplified view for caching)
+        // We reuse the logic: if it's atomic, skeleton is full file. If logic, it's signatures.
+        const skeleton = isAtomic
+            ? { type: 'full', content: '...' }
+            : this.generateSkeleton(sourceFile);
+        return {
+            filePath,
+            fileHash,
+            chunks,
+            dependencies,
+            skeleton,
+        };
+    }
+    // ==========================================
+    // 🕵️ STRATEGIES
+    // ==========================================
+    /**
+     * Checks if the file should be treated as a single atomic unit.
+     * Rules: DTOs, Entities, Interfaces, Enums.
+     */
+    isAtomicFile(filePath) {
+        return (filePath.endsWith('.dto.ts') ||
+            filePath.endsWith('.entity.ts') ||
+            filePath.endsWith('.interface.ts') ||
+            filePath.endsWith('.enum.ts') ||
+            filePath.endsWith('.type.ts'));
+    }
+    /**
+     * Strategy A: Atomic Processing
+     * Stores the whole file as one chunk. Essential for DTOs/Entities context.
+     */
+    processAtomicFile(sourceFile) {
+        return [
+            {
+                id: (0, uuid_1.v4)(),
+                type: 'file',
+                content: sourceFile.getFullText(),
+                metadata: {
+                    startLine: 1,
+                    endLine: sourceFile.getEndLineNumber(),
+                    className: this.getClassName(sourceFile),
+                },
+            },
+        ];
+    }
+    /**
+     * Strategy B: Logic Processing (Parent-Child)
+     * Splits Services/Controllers into Class Context (Parent) and Methods (Children).
+     */
+    processLogicFile(sourceFile) {
+        const chunks = [];
+        const classes = sourceFile.getClasses();
+        for (const cls of classes) {
+            // 1. Create Parent Chunk (The Class Context)
+            // Includes: Decorators, Properties, Constructor. Excludes: Method Bodies.
+            const parentId = (0, uuid_1.v4)();
+            const classContext = this.extractClassContext(cls);
+            chunks.push({
+                id: parentId,
+                type: 'class_signature',
+                content: classContext,
+                metadata: {
+                    startLine: cls.getStartLineNumber(),
+                    endLine: cls.getEndLineNumber(),
+                    className: cls.getName(),
+                    decorators: cls.getDecorators().map((d) => d.getName()),
+                },
+            });
+            // 2. Create Child Chunks (The Methods)
+            const methods = cls.getMethods();
+            for (const method of methods) {
+                chunks.push({
+                    id: (0, uuid_1.v4)(),
+                    parentId: parentId, // Link to Parent!
+                    type: 'method',
+                    content: method.getFullText(), // Method logic
+                    metadata: {
+                        startLine: method.getStartLineNumber(),
+                        endLine: method.getEndLineNumber(),
+                        className: cls.getName(),
+                        methodName: method.getName(),
+                        decorators: method.getDecorators().map((d) => d.getName()),
+                    },
+                });
+            }
+        }
+        return chunks;
+    }
+    // ==========================================
+    // 🛠️ HELPERS
+    // ==========================================
+    /**
+     * Extracts the "Context" of a class without the heavy method implementation.
+     * Keeps imports (from file), class decorators, properties, and constructor.
+     */
+    extractClassContext(cls) {
+        // We clone the structure to manipulate text without breaking the original AST
+        // Ideally, we construct a string string representation:
+        let text = cls
+            .getDecorators()
+            .map((d) => d.getText())
+            .join('\n');
+        text += `\nexport class ${cls.getName()} {\n`;
+        // Add properties (e.g., private readonly userService: UserService;)
+        cls.getProperties().forEach((prop) => {
+            text += `  ${prop.getText()}\n`;
+        });
+        // Add constructor
+        const ctor = cls.getConstructors()[0];
+        if (ctor) {
+            text += `  ${ctor.getText()}\n`;
+        }
+        text += `  // Methods are indexed separately as child chunks...\n`;
+        text += `}`;
+        // Prepend Imports from the source file for full context
+        const imports = cls
+            .getSourceFile()
+            .getImportDeclarations()
+            .map((i) => i.getText())
+            .join('\n');
+        return `${imports}\n\n${text}`;
+    }
+    /**
+     * Extracts static import relationships to build the Dependency Graph.
+     * It parses the AST to find all relative imports and resolves them to physical files.
+     * * @param sourceFile - The AST SourceFile object from ts-morph.
+     * @param sourcePath - The relative path of the file currently being analyzed (e.g., 'src/auth/auth.service.ts').
+     * @returns An array of graph edges representing 'import' relationships.
+     */
+    extractDependencies(sourceFile, sourcePath) {
+        const edges = [];
+        const imports = sourceFile.getImportDeclarations();
+        // Necesitamos el directorio absoluto para resolver, así que combinamos CWD + sourcePath
+        // Nota: Asumimos que sourcePath entra como relativa, ej: 'src/users/users.service.ts'
+        const absoluteSourcePath = path.resolve(process.cwd(), sourcePath);
+        const sourceDir = path.dirname(absoluteSourcePath);
+        for (const imp of imports) {
+            const moduleSpecifier = imp.getModuleSpecifierValue();
+            // 1. Filter: We only care about internal relative imports (starting with '.')
+            if (moduleSpecifier.startsWith('.')) {
+                // 2. Resolution: Find the physical .ts file on disk
+                const resolvedPath = this.resolveModulePath(sourceDir, moduleSpecifier);
+                // 3. Validation: Only link if the file actually exists
+                if (resolvedPath) {
+                    // 4. Normalization: Convert back to relative path for the Database
+                    // We use split/join to force forward slashes (/) even on Windows for DB consistency.
+                    const relativeTarget = path
+                        .relative(process.cwd(), resolvedPath)
+                        .split(path.sep)
+                        .join('/');
+                    edges.push({
+                        sourcePath: sourcePath, // Already relative
+                        targetPath: relativeTarget,
+                        relation: 'import',
+                    });
+                }
+            }
+        }
+        return edges;
+    }
+    getClassName(sourceFile) {
+        return sourceFile.getClasses()[0]?.getName();
+    }
+    generateSkeleton(sourceFile) {
+        return {
+            // 1. Guardamos imports visuales para que el LLM sepa de dónde vienen los tipos
+            imports: sourceFile.getImportDeclarations().map((i) => i.getText()),
+            classes: sourceFile.getClasses().map((c) => ({
+                name: c.getName(),
+                // 2. MEJORA: No guardes solo el nombre "create".
+                // Guarda la firma: "create(dto: CreateUserDto): Promise<User>"
+                // Cortamos justo antes de la llave '{' para quitar el cuerpo.
+                methods: c.getMethods().map((m) => {
+                    // Obtiene solo la estructura (nombre, args, retorno)
+                    //   const structure = m.getStructure();
+                    // O reconstrúyelo simple:
+                    return `${m.getName()}(${m
+                        .getParameters()
+                        .map((p) => p.getText())
+                        .join(', ')}): ${m.getReturnType().getText()};`;
+                }),
+            })),
+        };
+    }
+    /**
+     * Resolves the physical filesystem path for a given import string.
+     * Handles TypeScript resolution strategies including file extensions and directory indexes.
+     * * @param sourceDir - The absolute directory path of the file containing the import.
+     * @param importPath - The raw import string (e.g., './users.service' or './dto').
+     * @returns The absolute path to the resolved .ts file, or `null` if not found/external.
+     * * @example
+     * resolveModulePath('/src/users', './dto');
+     * // Returns: '/src/users/dto/index.ts'
+     */
+    resolveModulePath(sourceDir, importPath) {
+        // 1. Construct the potential absolute path
+        const absoluteBase = path.join(sourceDir, importPath);
+        // Case A: Explicit file extension (rare in imports, but valid)
+        // import ... from './file.ts'
+        if (fs.existsSync(absoluteBase) && fs.statSync(absoluteBase).isFile()) {
+            return absoluteBase;
+        }
+        // Case B: Implicit .ts extension (Most common)
+        // import ... from './users.service' -> checks users.service.ts
+        const tsPath = `${absoluteBase}.ts`;
+        if (fs.existsSync(tsPath)) {
+            return tsPath;
+        }
+        // Case C: Directory Index (Barrel Files)
+        // import ... from './dto' -> checks dto/index.ts
+        const indexPath = path.join(absoluteBase, 'index.ts');
+        if (fs.existsSync(indexPath)) {
+            return indexPath;
+        }
+        // Case D: Resolution failed
+        // Could be a node_module, a path alias (@src/...), or a non-existent file.
+        return null;
+    }
+}
+exports.NestChunker = NestChunker;

package/dist/core/tools/ast/definitions.js

@@ -0,0 +1,29 @@
+"use strict";
+// import { integrityCheckTool, askCodebaseTool } from '../tools/tools';
+// Nueva Descripción (Concepto): "Semantic Code Analysis Tool. Use this to gain deep context about the project's logic. It retrieves not just code snippets, but also class skeletons and dependency relationships. Returns: Code chunks + File Paths. Strategy: If the result implies a complex file, use the native read_file on the returned path to see the full implementation."
+// Eres un Ingeniero de Software Principal especializado en NestJS (Node.js).
+// Estás operando directamente en el sistema de archivos local de un proyecto real.
+// 💎 ESTÁNDARES DE CALIDAD (INQUEBRANTABLES):
+// 1. **Arquitectura:** Sigue DDD (Domain Driven Development) y Mejores Prácticas de NestJS.
+//    - Usa DTOs estrictos con 'class-validator' y 'class-transformer'.
+//    - Siempre documenta con TSDocs (inglés o español según contexto, prefiere inglés técnico).
+// 2. **Testing (TDD):** NO escribas código sin su test.
+//    - Crea el archivo '.spec.ts' junto con la implementación.
+//    - Asegúrate de que los tests pasen.
+// 3. **Manejo de Errores:**
+//    - Usa excepciones HTTP estándar de NestJS (NotFoundException, BadRequestException).
+//    - Nunca tragues errores silenciosamente (no empty catch).
+// 4. **Tipado:** TypeScript Estricto. Prohibido usar 'any'.
+// ⚙️ PROTOCOLO DE EJECUCIÓN:
+// 1. **PLANIFICAR (write_todos):** Desglosa la tarea. Si es compleja, delega el diseño al 'senior_architect'.
+// 2. **INVESTIGAR (ask_codebase):** ANTES de tocar nada, busca cómo se hacen las cosas en este proyecto.
+//    - Ejemplo: "Busca UserEntity antes de crear un DTO relacionado".
+// 3. **IMPLEMENTAR (Safe Write):** Escribe los archivos. 
+//    - Recuerda: Tienes un sistema de backups activo, trabaja con confianza pero con cuidado.
+// 4. **VALIDAR (run_integrity_check):** OBLIGATORIO.
+//    - Después de escribir, corre el chequeo de integridad.
+//    - Si falla, AUTO-CORRÍGETE. No preguntes al usuario, arregla el error de compilación.
+// 5. **APRENDER:** Si el usuario te corrige una preferencia de estilo, guárdala en '/memories/style-guide.txt'.
+// 🚨 REGLAS DE SEGURIDAD:
+// - Nunca borres archivos masivamente.
+// - Si modificas un archivo core (como app.module.ts), verifica doblemente los imports.