@compilr-dev/agents-coding-ts 0.1.2 → 0.1.4

package/dist/index.d.ts

@@ -4,10 +4,10 @@
  * TypeScript/JavaScript analysis tools for AI coding agents.
  * Provides AST-based code analysis, complexity metrics, and type hierarchy tools.
  */
-export { parseTypeScript, detectLanguage, isLanguageSupported, } from './parser/index.js';
-export { getFileStructureTool, createGetFileStructureTool, findSymbolTool, createFindSymbolTool, findReferencesTool, createFindReferencesTool, getImportsTool, createGetImportsTool, getExportsTool, createGetExportsTool, getCallGraphTool, createGetCallGraphTool, getDependencyGraphTool, createGetDependencyGraphTool, findImplementationsTool, createFindImplementationsTool, getTypeHierarchyTool, createGetTypeHierarchyTool, getComplexityTool, createGetComplexityTool, findDeadCodeTool, createFindDeadCodeTool, findDuplicatesTool, createFindDuplicatesTool, findPatternsTool, createFindPatternsTool, getSignatureTool, createGetSignatureTool, getDocumentationTool, createGetDocumentationTool, } from './tools/index.js';
-export type { SupportedLanguage, ParameterInfo, GetFileStructureInput, FileStructure, ImportInfo, ExportInfo, ClassInfo, FunctionInfo, MethodInfo, PropertyInfo, VariableInfo, TypeDefinitionInfo, FileStats, SymbolKind, SymbolKindFilter, FindSymbolInput, FindSymbolResult, SymbolDefinition, SearchStats, ReferenceType, FindReferencesInput, FindReferencesResult, Reference, FileReferences, GetImportsInput, GetImportsResult, DetailedImport, ImportedSymbol, TransitiveImport, ImportStats, GetExportsInput, GetExportsResult, ExportedSymbol, ExportKind, ReExport, ExportStats, CallGraphDirection, CallType, GetCallGraphInput, GetCallGraphResult, FunctionNode, CallInfo, CallGraphNode, CallGraphStats, GetDependencyGraphInput, GetDependencyGraphResult, ModuleNode, DependencyEdge, CircularDependency, DependencyGraphStats, FindImplementationsInput, FindImplementationsResult, ImplementationInfo, HierarchyDirection, GetTypeHierarchyInput, GetTypeHierarchyResult, TypeHierarchyNode, GetComplexityInput, GetComplexityResult, FileComplexity, FunctionComplexity, ComplexityContributor, ComplexityContributorType, FindDeadCodeInput, FindDeadCodeResult, DeadCodeItem, FindDuplicatesInput, FindDuplicatesResult, DuplicateGroup, CodeLocation, FindPatternsInput, FindPatternsResult, PatternMatch, CodePattern, GetSignatureInput, GetSignatureResult, ParameterDetail, TypeDetail, GenericDetail, Documentation, MemberSignature, SignatureSymbolKind, GetDocumentationInput, GetDocumentationResult, FileDocumentation, DocumentedSymbol, DocumentationSymbolKind, ExtractorOptions, } from './tools/index.js';
-export { codeStructureSkill, dependencyAuditSkill, refactorImpactSkill, typeAnalysisSkill, codeHealthSkill, tsSkills, defineSkill, type Skill, } from './skills/index.js';
+export { parseTypeScript, detectLanguage, isLanguageSupported, } from "./parser/index.js";
+export { getFileStructureTool, createGetFileStructureTool, findSymbolTool, createFindSymbolTool, findReferencesTool, createFindReferencesTool, getImportsTool, createGetImportsTool, getExportsTool, createGetExportsTool, getCallGraphTool, createGetCallGraphTool, getDependencyGraphTool, createGetDependencyGraphTool, findImplementationsTool, createFindImplementationsTool, getTypeHierarchyTool, createGetTypeHierarchyTool, getComplexityTool, createGetComplexityTool, findDeadCodeTool, createFindDeadCodeTool, findDuplicatesTool, createFindDuplicatesTool, findPatternsTool, createFindPatternsTool, getSignatureTool, createGetSignatureTool, getDocumentationTool, createGetDocumentationTool, readFunctionTool, readClassTool, readTypeTool, createReadFunctionTool, createReadClassTool, createReadTypeTool, } from "./tools/index.js";
+export type { SupportedLanguage, ParameterInfo, GetFileStructureInput, FileStructure, ImportInfo, ExportInfo, ClassInfo, FunctionInfo, MethodInfo, PropertyInfo, VariableInfo, TypeDefinitionInfo, FileStats, SymbolKind, SymbolKindFilter, FindSymbolInput, FindSymbolResult, SymbolDefinition, SearchStats, ReferenceType, FindReferencesInput, FindReferencesResult, Reference, FileReferences, GetImportsInput, GetImportsResult, DetailedImport, ImportedSymbol, TransitiveImport, ImportStats, GetExportsInput, GetExportsResult, ExportedSymbol, ExportKind, ReExport, ExportStats, CallGraphDirection, CallType, GetCallGraphInput, GetCallGraphResult, FunctionNode, CallInfo, CallGraphNode, CallGraphStats, GetDependencyGraphInput, GetDependencyGraphResult, ModuleNode, DependencyEdge, CircularDependency, DependencyGraphStats, FindImplementationsInput, FindImplementationsResult, ImplementationInfo, HierarchyDirection, GetTypeHierarchyInput, GetTypeHierarchyResult, TypeHierarchyNode, GetComplexityInput, GetComplexityResult, FileComplexity, FunctionComplexity, ComplexityContributor, ComplexityContributorType, FindDeadCodeInput, FindDeadCodeResult, DeadCodeItem, FindDuplicatesInput, FindDuplicatesResult, DuplicateGroup, CodeLocation, FindPatternsInput, FindPatternsResult, PatternMatch, CodePattern, GetSignatureInput, GetSignatureResult, ParameterDetail, TypeDetail, GenericDetail, Documentation, MemberSignature, SignatureSymbolKind, GetDocumentationInput, GetDocumentationResult, FileDocumentation, DocumentedSymbol, DocumentationSymbolKind, ExtractorOptions, ReadFunctionInput, ReadClassInput, ReadTypeInput, ReadSymbolResult, } from "./tools/index.js";
+export { codeStructureSkill, dependencyAuditSkill, refactorImpactSkill, typeAnalysisSkill, codeHealthSkill, tsSkills, defineSkill, type Skill, } from "./skills/index.js";
 /**
  * All TypeScript/JavaScript analysis tools for easy registration
  */
@@ -27,8 +27,11 @@ export declare const tsTools: {
     readonly findPatterns: import("@compilr-dev/agents").Tool<import("./tools/types.js").FindPatternsInput>;
     readonly getSignature: import("@compilr-dev/agents").Tool<import("./tools/types.js").GetSignatureInput>;
     readonly getDocumentation: import("@compilr-dev/agents").Tool<import("./tools/types.js").GetDocumentationInput>;
+    readonly readFunction: import("@compilr-dev/agents").Tool<import("./tools/read-symbol.js").ReadFunctionInput>;
+    readonly readClass: import("@compilr-dev/agents").Tool<import("./tools/read-symbol.js").ReadClassInput>;
+    readonly readType: import("@compilr-dev/agents").Tool<import("./tools/read-symbol.js").ReadTypeInput>;
 };
 /**
  * Array of all TypeScript/JavaScript analysis tools
  */
-export declare const allTsTools: readonly [import("@compilr-dev/agents").Tool<import("./tools/types.js").GetFileStructureInput>, import("@compilr-dev/agents").Tool<import("./tools/types.js").FindSymbolInput>, import("@compilr-dev/agents").Tool<import("./tools/types.js").FindReferencesInput>, import("@compilr-dev/agents").Tool<import("./tools/types.js").GetImportsInput>, import("@compilr-dev/agents").Tool<import("./tools/types.js").GetExportsInput>, import("@compilr-dev/agents").Tool<import("./tools/types.js").GetCallGraphInput>, import("@compilr-dev/agents").Tool<import("./tools/types.js").GetDependencyGraphInput>, import("@compilr-dev/agents").Tool<import("./tools/types.js").FindImplementationsInput>, import("@compilr-dev/agents").Tool<import("./tools/types.js").GetTypeHierarchyInput>, import("@compilr-dev/agents").Tool<import("./tools/types.js").GetComplexityInput>, import("@compilr-dev/agents").Tool<import("./tools/types.js").FindDeadCodeInput>, import("@compilr-dev/agents").Tool<import("./tools/types.js").FindDuplicatesInput>, import("@compilr-dev/agents").Tool<import("./tools/types.js").FindPatternsInput>, import("@compilr-dev/agents").Tool<import("./tools/types.js").GetSignatureInput>, import("@compilr-dev/agents").Tool<import("./tools/types.js").GetDocumentationInput>];
+export declare const allTsTools: readonly [import("@compilr-dev/agents").Tool<import("./tools/types.js").GetFileStructureInput>, import("@compilr-dev/agents").Tool<import("./tools/types.js").FindSymbolInput>, import("@compilr-dev/agents").Tool<import("./tools/types.js").FindReferencesInput>, import("@compilr-dev/agents").Tool<import("./tools/types.js").GetImportsInput>, import("@compilr-dev/agents").Tool<import("./tools/types.js").GetExportsInput>, import("@compilr-dev/agents").Tool<import("./tools/types.js").GetCallGraphInput>, import("@compilr-dev/agents").Tool<import("./tools/types.js").GetDependencyGraphInput>, import("@compilr-dev/agents").Tool<import("./tools/types.js").FindImplementationsInput>, import("@compilr-dev/agents").Tool<import("./tools/types.js").GetTypeHierarchyInput>, import("@compilr-dev/agents").Tool<import("./tools/types.js").GetComplexityInput>, import("@compilr-dev/agents").Tool<import("./tools/types.js").FindDeadCodeInput>, import("@compilr-dev/agents").Tool<import("./tools/types.js").FindDuplicatesInput>, import("@compilr-dev/agents").Tool<import("./tools/types.js").FindPatternsInput>, import("@compilr-dev/agents").Tool<import("./tools/types.js").GetSignatureInput>, import("@compilr-dev/agents").Tool<import("./tools/types.js").GetDocumentationInput>, import("@compilr-dev/agents").Tool<import("./tools/read-symbol.js").ReadFunctionInput>, import("@compilr-dev/agents").Tool<import("./tools/read-symbol.js").ReadClassInput>, import("@compilr-dev/agents").Tool<import("./tools/read-symbol.js").ReadTypeInput>];

package/dist/index.js

@@ -5,7 +5,7 @@
  * Provides AST-based code analysis, complexity metrics, and type hierarchy tools.
  */
 // Parser exports
-export { parseTypeScript, detectLanguage, isLanguageSupported, } from './parser/index.js';
+export { parseTypeScript, detectLanguage, isLanguageSupported, } from "./parser/index.js";
 // Tool exports
 export { 
 // Tier 1 & 2 Tools
@@ -13,11 +13,13 @@ getFileStructureTool, createGetFileStructureTool, findSymbolTool, createFindSymb
 // Tier 3 Tools
 getComplexityTool, createGetComplexityTool, findDeadCodeTool, createFindDeadCodeTool, findDuplicatesTool, createFindDuplicatesTool, findPatternsTool, createFindPatternsTool, 
 // Tier 4 Utility Tools
-getSignatureTool, createGetSignatureTool, getDocumentationTool, createGetDocumentationTool, } from './tools/index.js';
+getSignatureTool, createGetSignatureTool, getDocumentationTool, createGetDocumentationTool, 
+// Smart File Reading Tools
+readFunctionTool, readClassTool, readTypeTool, createReadFunctionTool, createReadClassTool, createReadTypeTool, } from "./tools/index.js";
 // Skill exports
-export { codeStructureSkill, dependencyAuditSkill, refactorImpactSkill, typeAnalysisSkill, codeHealthSkill, tsSkills, defineSkill, } from './skills/index.js';
+export { codeStructureSkill, dependencyAuditSkill, refactorImpactSkill, typeAnalysisSkill, codeHealthSkill, tsSkills, defineSkill, } from "./skills/index.js";
 // Tool imports for collections
-import { getFileStructureTool, findSymbolTool, findReferencesTool, getImportsTool, getExportsTool, getCallGraphTool, getDependencyGraphTool, findImplementationsTool, getTypeHierarchyTool, getComplexityTool, findDeadCodeTool, findDuplicatesTool, findPatternsTool, getSignatureTool, getDocumentationTool, } from './tools/index.js';
+import { getFileStructureTool, findSymbolTool, findReferencesTool, getImportsTool, getExportsTool, getCallGraphTool, getDependencyGraphTool, findImplementationsTool, getTypeHierarchyTool, getComplexityTool, findDeadCodeTool, findDuplicatesTool, findPatternsTool, getSignatureTool, getDocumentationTool, readFunctionTool, readClassTool, readTypeTool, } from "./tools/index.js";
 /**
  * All TypeScript/JavaScript analysis tools for easy registration
  */
@@ -40,6 +42,10 @@ export const tsTools = {
     // Tier 4
     getSignature: getSignatureTool,
     getDocumentation: getDocumentationTool,
+    // Smart File Reading
+    readFunction: readFunctionTool,
+    readClass: readClassTool,
+    readType: readTypeTool,
 };
 /**
  * Array of all TypeScript/JavaScript analysis tools
@@ -63,4 +69,8 @@ export const allTsTools = [
     // Tier 4
     getSignatureTool,
     getDocumentationTool,
+    // Smart File Reading
+    readFunctionTool,
+    readClassTool,
+    readTypeTool,
 ];

package/dist/parser/index.d.ts

@@ -3,5 +3,5 @@
  *
  * Provides AST parsing capabilities using the TypeScript Compiler API.
  */
-export { parseTypeScript, detectLanguage, isLanguageSupported, } from './typescript-parser.js';
-export type { SupportedLanguage } from '../tools/types.js';
+export { parseTypeScript, detectLanguage, isLanguageSupported, } from "./typescript-parser.js";
+export type { SupportedLanguage } from "../tools/types.js";

package/dist/parser/index.js

@@ -3,4 +3,4 @@
  *
  * Provides AST parsing capabilities using the TypeScript Compiler API.
  */
-export { parseTypeScript, detectLanguage, isLanguageSupported, } from './typescript-parser.js';
+export { parseTypeScript, detectLanguage, isLanguageSupported, } from "./typescript-parser.js";

package/dist/parser/typescript-parser.d.ts

@@ -4,11 +4,11 @@
  * Uses TypeScript's built-in parser for accurate AST analysis.
  * Works for both TypeScript and JavaScript files.
  */
-import type { FileStructure, ExtractorOptions, SupportedLanguage } from '../tools/types.js';
+import type { FileStructure, ExtractorOptions, SupportedLanguage } from "../tools/types.js";
 /**
  * Parse a TypeScript/JavaScript file and extract its structure
  */
-export declare function parseTypeScript(sourceCode: string, filePath: string, options?: ExtractorOptions): Omit<FileStructure, 'path' | 'language' | 'languageConfidence'>;
+export declare function parseTypeScript(sourceCode: string, filePath: string, options?: ExtractorOptions): Omit<FileStructure, "path" | "language" | "languageConfidence">;
 /**
  * Detect language from file path
  */

package/dist/parser/typescript-parser.js

@@ -4,7 +4,7 @@
  * Uses TypeScript's built-in parser for accurate AST analysis.
  * Works for both TypeScript and JavaScript files.
  */
-import * as ts from 'typescript';
+import * as ts from "typescript";
 // Helper to check for a specific modifier kind
 function hasModifierKind(modifiers, kind) {
     return modifiers?.some((m) => m.kind === kind) ?? false;
@@ -27,7 +27,7 @@ export function parseTypeScript(sourceCode, filePath, options = {}) {
     const types = extractTypes(sourceFile);
     // Calculate stats
     const stats = {
-        lineCount: sourceCode.split('\n').length,
+        lineCount: sourceCode.split("\n").length,
         importCount: imports.length,
         exportCount: exports.length,
         classCount: classes.length,
@@ -48,21 +48,21 @@ export function parseTypeScript(sourceCode, filePath, options = {}) {
  * Get TypeScript script kind from file extension
  */
 function getScriptKind(filePath) {
-    const ext = filePath.toLowerCase().split('.').pop();
+    const ext = filePath.toLowerCase().split(".").pop();
     switch (ext) {
-        case 'ts':
+        case "ts":
             return ts.ScriptKind.TS;
-        case 'tsx':
+        case "tsx":
             return ts.ScriptKind.TSX;
-        case 'js':
+        case "js":
             return ts.ScriptKind.JS;
-        case 'jsx':
+        case "jsx":
             return ts.ScriptKind.JSX;
-        case 'mts':
-        case 'cts':
+        case "mts":
+        case "cts":
             return ts.ScriptKind.TS;
-        case 'mjs':
-        case 'cjs':
+        case "mjs":
+        case "cjs":
             return ts.ScriptKind.JS;
         default:
             return ts.ScriptKind.TS;
@@ -80,7 +80,9 @@ function extractImports(sourceFile) {
                 return;
             const source = moduleSpecifier.text;
             // Check for type-only import using modifiers
-            const modifiers = ts.canHaveModifiers(node) ? ts.getModifiers(node) : undefined;
+            const modifiers = ts.canHaveModifiers(node)
+                ? ts.getModifiers(node)
+                : undefined;
             const hasTypeKeyword = hasModifierKind(modifiers, ts.SyntaxKind.TypeKeyword);
             const importInfo = {
                 source,
@@ -120,7 +122,7 @@ function extractExports(sourceFile) {
         // export default ...
         if (ts.isExportAssignment(node)) {
             exports.push({
-                name: 'default',
+                name: "default",
                 isDefault: true,
                 isTypeOnly: false,
             });
@@ -129,7 +131,9 @@ function extractExports(sourceFile) {
         // export { ... }
         if (ts.isExportDeclaration(node)) {
             // Check for type-only export using modifiers
-            const exportMods = ts.canHaveModifiers(node) ? ts.getModifiers(node) : undefined;
+            const exportMods = ts.canHaveModifiers(node)
+                ? ts.getModifiers(node)
+                : undefined;
             const isTypeOnlyExport = hasModifierKind(exportMods, ts.SyntaxKind.TypeKeyword);
             if (node.exportClause && ts.isNamedExports(node.exportClause)) {
                 for (const element of node.exportClause.elements) {
@@ -143,11 +147,13 @@ function extractExports(sourceFile) {
             return;
         }
         // Check for export modifier on declarations
-        const modifiers = ts.canHaveModifiers(node) ? ts.getModifiers(node) : undefined;
+        const modifiers = ts.canHaveModifiers(node)
+            ? ts.getModifiers(node)
+            : undefined;
         const hasExport = hasModifierKind(modifiers, ts.SyntaxKind.ExportKeyword);
         const hasDefault = hasModifierKind(modifiers, ts.SyntaxKind.DefaultKeyword);
         if (hasExport) {
-            let name = 'unknown';
+            let name = "unknown";
             if (ts.isFunctionDeclaration(node) && node.name) {
                 name = node.name.text;
             }
@@ -175,9 +181,9 @@ function extractExports(sourceFile) {
             else if (ts.isEnumDeclaration(node)) {
                 name = node.name.text;
             }
-            if (name !== 'unknown' || hasDefault) {
+            if (name !== "unknown" || hasDefault) {
                 exports.push({
-                    name: hasDefault ? 'default' : name,
+                    name: hasDefault ? "default" : name,
                     isDefault: hasDefault,
                     isTypeOnly: ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node),
                 });
@@ -205,24 +211,28 @@ function extractClasses(sourceFile, includePrivate, maxDepth) {
  * Extract information from a class declaration
  */
 function extractClassInfo(node, includePrivate, _maxDepth) {
-    const name = node.name?.text ?? 'anonymous';
-    const modifiers = ts.canHaveModifiers(node) ? ts.getModifiers(node) : undefined;
+    const name = node.name?.text ?? "anonymous";
+    const modifiers = ts.canHaveModifiers(node)
+        ? ts.getModifiers(node)
+        : undefined;
     const isExported = hasModifierKind(modifiers, ts.SyntaxKind.ExportKeyword);
     const isAbstract = hasModifierKind(modifiers, ts.SyntaxKind.AbstractKeyword);
     const methods = [];
     const properties = [];
     for (const member of node.members) {
-        const memberModifiers = ts.canHaveModifiers(member) ? ts.getModifiers(member) : undefined;
+        const memberModifiers = ts.canHaveModifiers(member)
+            ? ts.getModifiers(member)
+            : undefined;
         const visibility = getVisibility(memberModifiers);
         // Skip private members if not included
-        if (!includePrivate && visibility === 'private') {
+        if (!includePrivate && visibility === "private") {
             continue;
         }
         if (ts.isConstructorDeclaration(member)) {
             const isAsync = hasModifierKind(memberModifiers, ts.SyntaxKind.AsyncKeyword);
             const isStatic = hasModifierKind(memberModifiers, ts.SyntaxKind.StaticKeyword);
             methods.push({
-                name: 'constructor',
+                name: "constructor",
                 visibility,
                 async: isAsync,
                 static: isStatic,
@@ -231,7 +241,9 @@ function extractClassInfo(node, includePrivate, _maxDepth) {
             });
         }
         else if (ts.isMethodDeclaration(member)) {
-            const methodName = ts.isIdentifier(member.name) ? member.name.text : 'computed';
+            const methodName = ts.isIdentifier(member.name)
+                ? member.name.text
+                : "computed";
             const isAsync = hasModifierKind(memberModifiers, ts.SyntaxKind.AsyncKeyword);
             const isStatic = hasModifierKind(memberModifiers, ts.SyntaxKind.StaticKeyword);
             methods.push({
@@ -244,8 +256,7 @@ function extractClassInfo(node, includePrivate, _maxDepth) {
             });
         }
         else if (ts.isPropertyDeclaration(member)) {
-            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- member.name can be undefined for computed properties
-            const propName = member.name && ts.isIdentifier(member.name) ? member.name.text : null;
+            const propName = ts.isIdentifier(member.name) ? member.name.text : null;
             if (propName) {
                 const isStatic = hasModifierKind(memberModifiers, ts.SyntaxKind.StaticKeyword);
                 const isReadonly = hasModifierKind(memberModifiers, ts.SyntaxKind.ReadonlyKeyword);
@@ -272,21 +283,21 @@ function extractClassInfo(node, includePrivate, _maxDepth) {
  */
 function getVisibility(modifiers) {
     if (!modifiers)
-        return 'public';
+        return "public";
     for (const mod of modifiers) {
         if (mod.kind === ts.SyntaxKind.PrivateKeyword)
-            return 'private';
+            return "private";
         if (mod.kind === ts.SyntaxKind.ProtectedKeyword)
-            return 'protected';
+            return "protected";
     }
-    return 'public';
+    return "public";
 }
 /**
  * Extract parameter information
  */
 function extractParameters(params) {
     return params.map((param) => ({
-        name: ts.isIdentifier(param.name) ? param.name.text : 'param',
+        name: ts.isIdentifier(param.name) ? param.name.text : "param",
         type: param.type ? param.type.getText() : undefined,
     }));
 }
@@ -298,7 +309,9 @@ function extractFunctions(sourceFile) {
     ts.forEachChild(sourceFile, (node) => {
         // Function declarations
         if (ts.isFunctionDeclaration(node) && node.name) {
-            const modifiers = ts.canHaveModifiers(node) ? ts.getModifiers(node) : undefined;
+            const modifiers = ts.canHaveModifiers(node)
+                ? ts.getModifiers(node)
+                : undefined;
             const isExported = hasModifierKind(modifiers, ts.SyntaxKind.ExportKeyword);
             const isAsync = hasModifierKind(modifiers, ts.SyntaxKind.AsyncKeyword);
             functions.push({
@@ -311,11 +324,14 @@ function extractFunctions(sourceFile) {
         }
         // Variable declarations that are arrow functions
         if (ts.isVariableStatement(node)) {
-            const modifiers = ts.canHaveModifiers(node) ? ts.getModifiers(node) : undefined;
+            const modifiers = ts.canHaveModifiers(node)
+                ? ts.getModifiers(node)
+                : undefined;
             const isExported = hasModifierKind(modifiers, ts.SyntaxKind.ExportKeyword);
             for (const decl of node.declarationList.declarations) {
                 if (ts.isIdentifier(decl.name) && decl.initializer) {
-                    if (ts.isArrowFunction(decl.initializer) || ts.isFunctionExpression(decl.initializer)) {
+                    if (ts.isArrowFunction(decl.initializer) ||
+                        ts.isFunctionExpression(decl.initializer)) {
                         const funcModifiers = decl.initializer.modifiers;
                         const isAsync = funcModifiers
                             ? funcModifiers.some((m) => m.kind === ts.SyntaxKind.AsyncKeyword)
@@ -325,7 +341,9 @@ function extractFunctions(sourceFile) {
                             exported: isExported,
                             async: isAsync,
                             parameters: extractParameters(decl.initializer.parameters),
-                            returnType: decl.initializer.type ? decl.initializer.type.getText() : undefined,
+                            returnType: decl.initializer.type
+                                ? decl.initializer.type.getText()
+                                : undefined,
                         });
                     }
                 }
@@ -341,14 +359,17 @@ function extractVariables(sourceFile) {
     const variables = [];
     ts.forEachChild(sourceFile, (node) => {
         if (ts.isVariableStatement(node)) {
-            const modifiers = ts.canHaveModifiers(node) ? ts.getModifiers(node) : undefined;
+            const modifiers = ts.canHaveModifiers(node)
+                ? ts.getModifiers(node)
+                : undefined;
             const isExported = hasModifierKind(modifiers, ts.SyntaxKind.ExportKeyword);
-            const kind = node.declarationList.flags & ts.NodeFlags.Const ? 'const' : 'let';
+            const kind = node.declarationList.flags & ts.NodeFlags.Const ? "const" : "let";
             for (const decl of node.declarationList.declarations) {
                 if (ts.isIdentifier(decl.name)) {
                     // Skip if this is a function (arrow function or function expression)
                     if (decl.initializer &&
-                        (ts.isArrowFunction(decl.initializer) || ts.isFunctionExpression(decl.initializer))) {
+                        (ts.isArrowFunction(decl.initializer) ||
+                            ts.isFunctionExpression(decl.initializer))) {
                         continue;
                     }
                     variables.push({
@@ -369,26 +390,28 @@ function extractVariables(sourceFile) {
 function extractTypes(sourceFile) {
     const types = [];
     ts.forEachChild(sourceFile, (node) => {
-        const modifiers = ts.canHaveModifiers(node) ? ts.getModifiers(node) : undefined;
+        const modifiers = ts.canHaveModifiers(node)
+            ? ts.getModifiers(node)
+            : undefined;
         const isExported = hasModifierKind(modifiers, ts.SyntaxKind.ExportKeyword);
         if (ts.isInterfaceDeclaration(node)) {
             types.push({
                 name: node.name.text,
-                kind: 'interface',
+                kind: "interface",
                 exported: isExported,
             });
         }
         else if (ts.isTypeAliasDeclaration(node)) {
             types.push({
                 name: node.name.text,
-                kind: 'type',
+                kind: "type",
                 exported: isExported,
             });
         }
         else if (ts.isEnumDeclaration(node)) {
             types.push({
                 name: node.name.text,
-                kind: 'enum',
+                kind: "enum",
                 exported: isExported,
             });
         }
@@ -399,18 +422,18 @@ function extractTypes(sourceFile) {
  * Detect language from file path
  */
 export function detectLanguage(filePath) {
-    const ext = filePath.toLowerCase().split('.').pop();
+    const ext = filePath.toLowerCase().split(".").pop();
     switch (ext) {
-        case 'ts':
-        case 'tsx':
-        case 'mts':
-        case 'cts':
-            return { language: 'typescript', confidence: 1.0 };
-        case 'js':
-        case 'jsx':
-        case 'mjs':
-        case 'cjs':
-            return { language: 'javascript', confidence: 1.0 };
+        case "ts":
+        case "tsx":
+        case "mts":
+        case "cts":
+            return { language: "typescript", confidence: 1.0 };
+        case "js":
+        case "jsx":
+        case "mjs":
+        case "cjs":
+            return { language: "javascript", confidence: 1.0 };
         default:
             return { language: null, confidence: 0 };
     }
@@ -419,5 +442,5 @@ export function detectLanguage(filePath) {
  * Check if a language is supported by this parser
  */
 export function isLanguageSupported(language) {
-    return language === 'typescript' || language === 'javascript';
+    return language === "typescript" || language === "javascript";
 }

package/dist/skills/code-health.js

@@ -3,15 +3,28 @@
  *
  * Analyze codebase health: complexity, dead code, duplicates, and anti-patterns.
  */
-import { defineSkill } from '@compilr-dev/agents';
+import { defineSkill } from "@compilr-dev/agents";
 /**
  * Code health skill - Analyze codebase health using Tier 3 tools
  */
 export const codeHealthSkill = defineSkill({
-    name: 'code-health',
-    description: 'Analyze codebase health: complexity, dead code, duplicates, and anti-patterns',
+    name: "code-health",
+    description: "Analyze codebase health: complexity, dead code, duplicates, and anti-patterns",
     prompt: `You are in CODE HEALTH ANALYSIS mode. Analyze the codebase for quality issues.
 
+## When to Use
+- Conducting a code quality audit
+- Finding complexity hotspots before refactoring
+- Identifying dead code that can be removed
+- Detecting code duplication and anti-patterns
+- Preparing for a code review or tech debt assessment
+
+## When NOT to Use
+- Need security-focused review → use security-review skill
+- Want to understand code structure → use code-structure skill
+- Planning specific refactoring → use refactor-impact skill first
+- Checking npm package vulnerabilities → use dependency-management skill (from core)
+
 ## TOOLS TO USE
 
 1. **get_complexity**: Analyze code complexity
@@ -162,6 +175,6 @@ find_patterns({
 - Consider project context (prototype vs production)
 - Dead code detection has false positives - verify before removing
 - Duplication is sometimes intentional - use judgment`,
-    tags: ['analysis', 'quality', 'complexity', 'health', 'audit'],
-    version: '1.0.0',
+    tags: ["analysis", "quality", "complexity", "health", "audit"],
+    version: "1.0.0",
 });

package/dist/skills/code-structure.js

@@ -3,15 +3,25 @@
  *
  * Analyze and understand codebase structure using analysis tools.
  */
-import { defineSkill } from '@compilr-dev/agents';
+import { defineSkill } from "@compilr-dev/agents";
 /**
  * Code structure skill - Understand codebase structure using analysis tools
  */
 export const codeStructureSkill = defineSkill({
-    name: 'code-structure',
-    description: 'Analyze and understand codebase structure quickly',
+    name: "code-structure",
+    description: "Analyze and understand codebase structure quickly",
     prompt: `You are in CODE STRUCTURE ANALYSIS mode. Analyze the specified path to understand its structure.
 
+## When to Use
+- Understanding a new file or module
+- Exploring codebase architecture
+- Finding entry points and exports
+
+## When NOT to Use
+- Need to find a specific symbol → use code-navigation skill
+- Need to refactor → use refactor-impact skill first
+- Need dependency analysis → use dependency-audit skill
+
 ## TOOLS TO USE
 
 1. **get_file_structure**: Analyze a file's internal structure
@@ -92,6 +102,6 @@ Any patterns, conventions, or notable design decisions.
 - Highlight patterns and conventions
 - Note any red flags (circular deps, mixed concerns) but don't dwell
 - Keep output concise - expand only when asked`,
-    tags: ['analysis', 'structure', 'understanding', 'navigation'],
-    version: '1.0.0',
+    tags: ["analysis", "structure", "understanding", "navigation"],
+    version: "1.0.0",
 });

package/dist/skills/dependency-audit.js

@@ -3,15 +3,26 @@
  *
  * Audit module dependencies and identify potential issues.
  */
-import { defineSkill } from '@compilr-dev/agents';
+import { defineSkill } from "@compilr-dev/agents";
 /**
  * Dependency audit skill - Analyze module dependencies for issues
  */
 export const dependencyAuditSkill = defineSkill({
-    name: 'dependency-audit',
-    description: 'Audit module dependencies and identify potential issues',
+    name: "dependency-audit",
+    description: "Audit module dependencies and identify potential issues",
     prompt: `You are in DEPENDENCY AUDIT mode. Analyze the project's module dependencies.
 
+## When to Use
+- Investigating circular dependency issues
+- Auditing module coupling before refactoring
+- Understanding dependency relationships in a codebase
+- Identifying heavy or duplicate external packages
+
+## When NOT to Use
+- Just need to understand one file's structure → use code-structure skill
+- Looking for a specific function or class → use code-navigation skill (find_symbol)
+- Checking npm package vulnerabilities → use dependency-management skill (from core)
+
 ## TOOLS TO USE
 
 1. **get_dependency_graph**: Build a complete module dependency graph
@@ -105,6 +116,6 @@ For suspicious files, use get_imports to see:
 - Don't flag normal patterns as issues
 - Provide actionable recommendations
 - Be concise - expand only on request`,
-    tags: ['analysis', 'dependencies', 'audit', 'architecture'],
-    version: '1.0.0',
+    tags: ["analysis", "dependencies", "audit", "architecture"],
+    version: "1.0.0",
 });

package/dist/skills/index.d.ts

@@ -3,13 +3,13 @@
  *
  * Specialized skills for code analysis workflows using AST-based tools.
  */
-import type { Skill } from '@compilr-dev/agents';
-export { defineSkill, type Skill } from '@compilr-dev/agents';
-export { codeStructureSkill } from './code-structure.js';
-export { dependencyAuditSkill } from './dependency-audit.js';
-export { refactorImpactSkill } from './refactor-impact.js';
-export { typeAnalysisSkill } from './type-analysis.js';
-export { codeHealthSkill } from './code-health.js';
+import type { Skill } from "@compilr-dev/agents";
+export { defineSkill, type Skill } from "@compilr-dev/agents";
+export { codeStructureSkill } from "./code-structure.js";
+export { dependencyAuditSkill } from "./dependency-audit.js";
+export { refactorImpactSkill } from "./refactor-impact.js";
+export { typeAnalysisSkill } from "./type-analysis.js";
+export { codeHealthSkill } from "./code-health.js";
 /**
  * All TypeScript/JavaScript analysis skills
  */

package/dist/skills/index.js

@@ -3,18 +3,18 @@
  *
  * Specialized skills for code analysis workflows using AST-based tools.
  */
-export { defineSkill } from '@compilr-dev/agents';
-export { codeStructureSkill } from './code-structure.js';
-export { dependencyAuditSkill } from './dependency-audit.js';
-export { refactorImpactSkill } from './refactor-impact.js';
-export { typeAnalysisSkill } from './type-analysis.js';
-export { codeHealthSkill } from './code-health.js';
+export { defineSkill } from "@compilr-dev/agents";
+export { codeStructureSkill } from "./code-structure.js";
+export { dependencyAuditSkill } from "./dependency-audit.js";
+export { refactorImpactSkill } from "./refactor-impact.js";
+export { typeAnalysisSkill } from "./type-analysis.js";
+export { codeHealthSkill } from "./code-health.js";
 // Import for collection
-import { codeStructureSkill } from './code-structure.js';
-import { dependencyAuditSkill } from './dependency-audit.js';
-import { refactorImpactSkill } from './refactor-impact.js';
-import { typeAnalysisSkill } from './type-analysis.js';
-import { codeHealthSkill } from './code-health.js';
+import { codeStructureSkill } from "./code-structure.js";
+import { dependencyAuditSkill } from "./dependency-audit.js";
+import { refactorImpactSkill } from "./refactor-impact.js";
+import { typeAnalysisSkill } from "./type-analysis.js";
+import { codeHealthSkill } from "./code-health.js";
 /**
  * All TypeScript/JavaScript analysis skills
  */