minovative-mind-cli 1.0.0

package/dist/utils/dependencyTracer.js

@@ -0,0 +1,647 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { EXCLUDED_EXTENSIONS } from './excludedExtensions.js';
+// ─── Language Profile Registry ───────────────────────────────────────
+//
+// Each profile defines regex patterns that extract import specifiers for
+// a family of languages. Patterns use named capture groups for uniform
+// extraction. The registry is intentionally exhaustive — covering edge
+// cases like dynamic imports, re-exports, CSS @use, Go multi-import
+// blocks, and Rust `mod` declarations.
+const LANGUAGE_PROFILES = [
+    // ── JavaScript / TypeScript ────────────────────────────────────────
+    {
+        extensions: ['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs', '.mts', '.cts'],
+        patterns: [
+            // Static imports: import X from 'specifier'  /  import 'specifier'
+            // Covers: import Foo from '...', import { a, b } from '...', import * as X from '...'
+            // Also covers: import '...' (side-effect only)
+            /import\s+(?:[\s\S]*?\s+from\s+)?['"](?<specifier>[^'"]+)['"]/gm,
+            // Dynamic imports: import('specifier')  /  await import('specifier')
+            /import\s*\(\s*['"](?<specifier>[^'"]+)['"]\s*\)/gm,
+            // CommonJS require: require('specifier')
+            /require\s*\(\s*['"](?<specifier>[^'"]+)['"]\s*\)/gm,
+            // Re-exports: export { X } from 'specifier'  /  export * from 'specifier'
+            /export\s+(?:[\s\S]*?\s+from\s+)['"](?<specifier>[^'"]+)['"]/gm,
+        ],
+    },
+    // ── Python ─────────────────────────────────────────────────────────
+    {
+        extensions: ['.py'],
+        patterns: [
+            // from package.module import X  →  captures 'package.module'
+            /^from\s+(?<specifier>[^\s]+)\s+import\s/gm,
+            // import package.module  →  captures 'package.module'
+            // Negative lookahead prevents matching 'from X import Y' (handled above)
+            /^import\s+(?!.*\sfrom\s)(?<specifier>[^\s,]+)/gm,
+        ],
+        normalizeSpecifier: (spec) => {
+            // Convert dotted module path to filesystem path: foo.bar.baz → foo/bar/baz.py
+            if (spec.startsWith('.')) {
+                // Relative import: .foo → ./foo.py, ..foo → ../foo.py
+                const dots = spec.match(/^\.+/)[0];
+                const rest = spec.slice(dots.length);
+                const prefix = dots.length === 1 ? './' : '../'.repeat(dots.length - 1);
+                return rest ? `${prefix}${rest.replace(/\./g, '/')}.py` : prefix.slice(0, -1);
+            }
+            return spec.replace(/\./g, '/') + '.py';
+        },
+    },
+    // ── Rust ────────────────────────────────────────────────────────────
+    {
+        extensions: ['.rs'],
+        patterns: [
+            // use crate::module::item  →  captures 'crate::module::item'
+            /use\s+(?<specifier>(?:crate|self|super)(?:::[a-zA-Z_][a-zA-Z0-9_]*)+)/gm,
+            // mod module_name;  →  captures 'module_name' (file-level module declaration)
+            /mod\s+(?<specifier>[a-zA-Z_][a-zA-Z0-9_]*)\s*;/gm,
+        ],
+        normalizeSpecifier: (spec, sourceFile) => {
+            if (!spec.includes('::')) {
+                // It's a `mod foo;` — resolves to either foo.rs or foo/mod.rs
+                return spec + '.rs';
+            }
+            // crate::foo::bar → src/foo/bar.rs (strip 'crate::' prefix)
+            const parts = spec.replace(/^crate::/, '').replace(/^(self|super)::/, '').split('::');
+            return parts.join('/') + '.rs';
+        },
+    },
+    // ── Go ─────────────────────────────────────────────────────────────
+    {
+        extensions: ['.go'],
+        patterns: [
+            // Single import: import "fmt"  or  import alias "pkg/path"
+            /import\s+(?:[a-zA-Z_][a-zA-Z0-9_]*\s+)?["'](?<specifier>[^"']+)["']/gm,
+            // Multi-line import block:  import ( "fmt" \n "os" )
+            // This captures individual lines inside the block
+            /^\s*(?:[a-zA-Z_][a-zA-Z0-9_]*\s+)?["'](?<specifier>[^"']+)["']\s*$/gm,
+        ],
+    },
+    // ── C / C++ ────────────────────────────────────────────────────────
+    {
+        extensions: ['.c', '.h', '.cpp', '.hpp', '.cc', '.cxx', '.hh', '.hxx'],
+        patterns: [
+            // #include "local_header.h"  →  captures local includes (quoted)
+            /^\s*#\s*include\s+"(?<specifier>[^"]+)"/gm,
+            // #include <system_header>  →  captures system includes (angled)
+            // We still track these — the resolver will skip if not found locally
+            /^\s*#\s*include\s+<(?<specifier>[^>]+)>/gm,
+        ],
+    },
+    // ── Java / Kotlin ──────────────────────────────────────────────────
+    {
+        extensions: ['.java', '.kt', '.kts'],
+        patterns: [
+            // import com.example.package.ClassName
+            /^import\s+(?:static\s+)?(?<specifier>[a-zA-Z_][a-zA-Z0-9_.]*\.[a-zA-Z_][a-zA-Z0-9_]*)/gm,
+        ],
+        normalizeSpecifier: (spec) => {
+            // com.example.Foo → com/example/Foo.java (best-effort)
+            return spec.replace(/\./g, '/') + '.java';
+        },
+    },
+    // ── CSS / SCSS / SASS / LESS ───────────────────────────────────────
+    {
+        extensions: ['.css', '.scss', '.sass', '.less', '.styl'],
+        patterns: [
+            // @import 'file'  or  @import url('file')
+            /@import\s+(?:url\s*\(\s*)?['"](?<specifier>[^'"]+)['"]/gm,
+            // @use 'file'  (SCSS)
+            /@use\s+['"](?<specifier>[^'"]+)['"]/gm,
+            // @forward 'file'  (SCSS)
+            /@forward\s+['"](?<specifier>[^'"]+)['"]/gm,
+        ],
+    },
+    // ── Ruby ───────────────────────────────────────────────────────────
+    {
+        extensions: ['.rb'],
+        patterns: [
+            // require 'file'  or  require "file"
+            /require\s+['"](?<specifier>[^'"]+)['"]/gm,
+            // require_relative 'file'
+            /require_relative\s+['"](?<specifier>[^'"]+)['"]/gm,
+            // load 'file'
+            /load\s+['"](?<specifier>[^'"]+)['"]/gm,
+        ],
+    },
+    // ── PHP ────────────────────────────────────────────────────────────
+    {
+        extensions: ['.php'],
+        patterns: [
+            // use Namespace\ClassName
+            /use\s+(?<specifier>[A-Z][a-zA-Z0-9_\\]+)/gm,
+            // include/require 'file.php'  or  include_once/require_once 'file.php'
+            /(?:include|require)(?:_once)?\s+['"](?<specifier>[^'"]+)['"]/gm,
+            // include/require with parentheses
+            /(?:include|require)(?:_once)?\s*\(\s*['"](?<specifier>[^'"]+)['"]\s*\)/gm,
+        ],
+        normalizeSpecifier: (spec) => {
+            // Convert PHP namespace to path: App\Models\User → App/Models/User.php
+            if (spec.includes('\\')) {
+                return spec.replace(/\\/g, '/') + '.php';
+            }
+            return spec;
+        },
+    },
+    // ── Swift ──────────────────────────────────────────────────────────
+    {
+        extensions: ['.swift'],
+        patterns: [
+            // import ModuleName  or  import class Module.Type
+            /^import\s+(?:class\s+|struct\s+|enum\s+|protocol\s+|typealias\s+|func\s+|var\s+|let\s+)?(?<specifier>[a-zA-Z_][a-zA-Z0-9_.]*)/gm,
+        ],
+    },
+    // ── Dart ───────────────────────────────────────────────────────────
+    {
+        extensions: ['.dart'],
+        patterns: [
+            // import 'package:...'  or  import 'relative/path.dart'
+            /import\s+['"](?<specifier>[^'"]+)['"]/gm,
+            // export 'file.dart'
+            /export\s+['"](?<specifier>[^'"]+)['"]/gm,
+            // part 'file.dart'
+            /part\s+['"](?<specifier>[^'"]+)['"]/gm,
+            // part of 'file.dart'
+            /part\s+of\s+['"](?<specifier>[^'"]+)['"]/gm,
+        ],
+    },
+];
+// ─── Extension → Profile Lookup ──────────────────────────────────────
+//
+// Pre-computed for O(1) lookups during the workspace walk.
+const PROFILE_BY_EXT = new Map();
+for (const profile of LANGUAGE_PROFILES) {
+    for (const ext of profile.extensions) {
+        const existing = PROFILE_BY_EXT.get(ext) || [];
+        existing.push(profile);
+        PROFILE_BY_EXT.set(ext, existing);
+    }
+}
+// ─── Ignored Directories ─────────────────────────────────────────────
+//
+// Mirrors the ignore lists from agent-tools.ts to stay consistent.
+const WALK_IGNORED_DIRS = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    '.next',
+    '.nuxt',
+    '__pycache__',
+    '.venv',
+    'venv',
+    '.cache',
+    'coverage',
+    '.turbo',
+    'build',
+    'out',
+    'target', // Rust/Java build output
+    '.gradle',
+    '.idea',
+]);
+const WALK_IGNORED_FILES = new Set([
+    'package-lock.json',
+    'yarn.lock',
+    'pnpm-lock.yaml',
+    '.DS_Store',
+]);
+// Build a set of bare extensions from EXCLUDED_EXTENSIONS for fast lookup
+const EXCLUDED_EXT_SET = new Set(EXCLUDED_EXTENSIONS.map((glob) => glob.replace('*', '')));
+let cachedAliases = null;
+let cachedAliasRoot = null;
+/**
+ * Reads and caches `tsconfig.json` or `jsconfig.json` path aliases.
+ * Returns an array of alias mappings, or an empty array if none found.
+ */
+async function loadPathAliases(workspaceRoot) {
+    if (cachedAliasRoot === workspaceRoot && cachedAliases !== null) {
+        return cachedAliases;
+    }
+    const aliases = [];
+    for (const configName of ['tsconfig.json', 'jsconfig.json']) {
+        try {
+            const configPath = path.join(workspaceRoot, configName);
+            const raw = await fs.readFile(configPath, 'utf-8');
+            // Strip single-line comments (// ...) and trailing commas for lenient JSON parsing
+            const cleaned = raw
+                .replace(/\/\/.*$/gm, '')
+                .replace(/,\s*([\]}])/g, '$1');
+            const config = JSON.parse(cleaned);
+            const paths = config?.compilerOptions?.paths;
+            const baseUrl = config?.compilerOptions?.baseUrl || '.';
+            if (paths && typeof paths === 'object') {
+                for (const [pattern, targets] of Object.entries(paths)) {
+                    if (!Array.isArray(targets))
+                        continue;
+                    // Convert tsconfig paths pattern to prefix matching
+                    // e.g., "@/*" → prefix "@/", targets ["./src/*"] → ["./src/"]
+                    const prefix = pattern.replace(/\*$/, '');
+                    const resolvedTargets = targets.map((t) => {
+                        const targetBase = t.replace(/\*$/, '');
+                        return path.join(baseUrl, targetBase);
+                    });
+                    aliases.push({ prefix, targets: resolvedTargets });
+                }
+            }
+            break; // Found a config, stop looking
+        }
+        catch {
+            // Config doesn't exist or is invalid — try the next one
+        }
+    }
+    cachedAliases = aliases;
+    cachedAliasRoot = workspaceRoot;
+    return aliases;
+}
+// ─── Import Extraction ───────────────────────────────────────────────
+/**
+ * Extracts all import specifiers from a file's content based on its extension.
+ * Returns an array of raw specifier strings (not yet resolved to paths).
+ */
+function extractImports(content, ext) {
+    const profiles = PROFILE_BY_EXT.get(ext);
+    if (!profiles || profiles.length === 0)
+        return [];
+    const specifiers = new Set();
+    for (const profile of profiles) {
+        for (const pattern of profile.patterns) {
+            // Reset lastIndex for safety (patterns are reused across files)
+            pattern.lastIndex = 0;
+            for (const match of content.matchAll(pattern)) {
+                const raw = match.groups?.specifier;
+                if (raw && raw.trim().length > 0) {
+                    const normalized = profile.normalizeSpecifier
+                        ? profile.normalizeSpecifier(raw.trim(), '')
+                        : raw.trim();
+                    specifiers.add(normalized);
+                }
+            }
+        }
+    }
+    return Array.from(specifiers);
+}
+// ─── Path Resolution ─────────────────────────────────────────────────
+/** Extensions to probe when the import specifier has no extension */
+const PROBE_EXTENSIONS = [
+    '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mts', '.cts',
+    '.py', '.rs', '.go', '.rb', '.php', '.swift', '.dart',
+    '.css', '.scss', '.sass', '.less',
+    '.json',
+];
+/** Index file basenames to probe for directory imports */
+const INDEX_FILES = [
+    'index.ts', 'index.tsx', 'index.js', 'index.jsx', 'index.mjs',
+    'mod.rs', // Rust convention
+    '__init__.py', // Python convention
+];
+/**
+ * Resolves a raw import specifier to a workspace-relative file path.
+ * Returns `null` if the specifier is external (node_modules, system import)
+ * or if the target file doesn't exist.
+ *
+ * Resolution cascade:
+ * 1. Path alias expansion (tsconfig/jsconfig `compilerOptions.paths`)
+ * 2. Relative path resolution
+ * 3. Extension probing (try appending .ts, .js, etc.)
+ * 4. Index/barrel file probing (try /index.ts, /index.js, etc.)
+ * 5. Existence verification
+ */
+async function resolveImportPath(workspaceRoot, sourceFile, specifier) {
+    // ── Skip clearly external / unresolvable specifiers ──
+    // Node built-ins (fs, path, etc.), npm packages, protocol imports
+    if (specifier.startsWith('node:') ||
+        specifier.startsWith('bun:') ||
+        specifier.startsWith('deno:') ||
+        specifier.startsWith('package:') || // Dart packages
+        specifier.startsWith('dart:') || // Dart SDK
+        specifier.startsWith('http://') ||
+        specifier.startsWith('https://')) {
+        return null;
+    }
+    const isRelative = specifier.startsWith('.') || specifier.startsWith('/');
+    // ── Try alias expansion first ──
+    if (!isRelative) {
+        const aliases = await loadPathAliases(workspaceRoot);
+        let expanded = null;
+        for (const alias of aliases) {
+            if (specifier.startsWith(alias.prefix)) {
+                const remainder = specifier.slice(alias.prefix.length);
+                // Try each target mapping (usually just one)
+                for (const target of alias.targets) {
+                    const candidate = path.join(workspaceRoot, target, remainder);
+                    const resolved = await probeFilePath(candidate);
+                    if (resolved) {
+                        expanded = path.relative(workspaceRoot, resolved);
+                        break;
+                    }
+                }
+                if (expanded)
+                    break;
+            }
+        }
+        if (expanded)
+            return normalizeSlashes(expanded);
+        // If it's not relative and no alias matched, it's likely an external package
+        // But still try to resolve it from workspace root as a last resort
+        // (handles cases like monorepo internal packages)
+        const fromRoot = path.join(workspaceRoot, specifier);
+        const rootResolved = await probeFilePath(fromRoot);
+        if (rootResolved) {
+            return normalizeSlashes(path.relative(workspaceRoot, rootResolved));
+        }
+        return null; // External package
+    }
+    // ── Resolve relative path ──
+    const sourceDir = path.dirname(path.join(workspaceRoot, sourceFile));
+    const absoluteCandidate = path.resolve(sourceDir, specifier);
+    // Security: ensure it's still within workspace
+    if (!absoluteCandidate.startsWith(workspaceRoot)) {
+        return null;
+    }
+    const resolved = await probeFilePath(absoluteCandidate);
+    if (resolved) {
+        return normalizeSlashes(path.relative(workspaceRoot, resolved));
+    }
+    return null;
+}
+/**
+ * Given an absolute path (possibly without extension), probes for
+ * the actual file by trying the path as-is, then with common extensions,
+ * then as a directory with index files.
+ */
+async function probeFilePath(candidate) {
+    // 1. Try exact path
+    if (await fileExists(candidate)) {
+        const stat = await fs.stat(candidate);
+        if (stat.isFile())
+            return candidate;
+        // It's a directory — fall through to index probing
+    }
+    // 2. Try appending extensions
+    for (const ext of PROBE_EXTENSIONS) {
+        const withExt = candidate + ext;
+        if (await fileExists(withExt)) {
+            return withExt;
+        }
+    }
+    // 3. Try as directory with index files
+    for (const indexFile of INDEX_FILES) {
+        const withIndex = path.join(candidate, indexFile);
+        if (await fileExists(withIndex)) {
+            return withIndex;
+        }
+    }
+    // 4. For CSS imports, try prepending underscore (SCSS partials: _file.scss)
+    const basename = path.basename(candidate);
+    if (!basename.startsWith('_')) {
+        const dir = path.dirname(candidate);
+        for (const ext of ['.scss', '.sass', '.less', '.css']) {
+            const partial = path.join(dir, `_${basename}${ext}`);
+            if (await fileExists(partial)) {
+                return partial;
+            }
+            // Also try if basename already has extension
+            if (basename.endsWith(ext)) {
+                const partialWithExt = path.join(dir, `_${basename}`);
+                if (await fileExists(partialWithExt)) {
+                    return partialWithExt;
+                }
+            }
+        }
+    }
+    return null;
+}
+async function fileExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function normalizeSlashes(p) {
+    return p.replace(/\\/g, '/');
+}
+// ─── Workspace Walking ───────────────────────────────────────────────
+/**
+ * Walks the workspace recursively, collecting all source files.
+ * Respects the same ignore rules as agent-tools.ts.
+ */
+async function walkWorkspace(workspaceRoot) {
+    const files = [];
+    // Parse .gitignore for supplemental ignore rules
+    const extraIgnored = new Set();
+    try {
+        const gitignoreContent = await fs.readFile(path.join(workspaceRoot, '.gitignore'), 'utf-8');
+        const lines = gitignoreContent
+            .split('\n')
+            .map((l) => l.trim())
+            .filter((l) => l && !l.startsWith('#'));
+        for (const line of lines) {
+            const clean = line.replace(/^\//, '').replace(/\/$/, '');
+            if (!clean.includes('*')) {
+                extraIgnored.add(clean);
+            }
+        }
+    }
+    catch {
+        // No .gitignore
+    }
+    async function walk(dir) {
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return; // Permission denied or other error — skip silently
+        }
+        for (const entry of entries) {
+            const name = entry.name;
+            // Skip hidden entries
+            if (name.startsWith('.'))
+                continue;
+            if (entry.isDirectory()) {
+                if (WALK_IGNORED_DIRS.has(name) || extraIgnored.has(name))
+                    continue;
+                await walk(path.join(dir, name));
+            }
+            else if (entry.isFile()) {
+                if (WALK_IGNORED_FILES.has(name) || extraIgnored.has(name))
+                    continue;
+                // Skip binary/generated extensions
+                const ext = path.extname(name).toLowerCase();
+                if (EXCLUDED_EXT_SET.has(ext))
+                    continue;
+                // Only process files we have profiles for (source code)
+                if (!PROFILE_BY_EXT.has(ext))
+                    continue;
+                const relPath = normalizeSlashes(path.relative(workspaceRoot, path.join(dir, name)));
+                files.push(relPath);
+            }
+        }
+    }
+    await walk(workspaceRoot);
+    return files;
+}
+// ─── Graph Builder ───────────────────────────────────────────────────
+/**
+ * Builds a complete bidirectional dependency graph of the workspace.
+ *
+ * Performance: This is pure regex + filesystem walking — no AST parsing.
+ * For a typical project (<5,000 source files), this completes in <1s.
+ * The graph is ephemeral: built once per `gatherContext` call and discarded.
+ */
+export async function buildDependencyGraph(workspaceRoot) {
+    const nodes = new Map();
+    function getOrCreate(filePath) {
+        let node = nodes.get(filePath);
+        if (!node) {
+            node = { imports: new Set(), importedBy: new Set() };
+            nodes.set(filePath, node);
+        }
+        return node;
+    }
+    // 1. Walk workspace to find all source files
+    const sourceFiles = await walkWorkspace(workspaceRoot);
+    // 2. Process each file: extract imports → resolve paths → populate graph
+    await Promise.all(sourceFiles.map(async (relPath) => {
+        const absPath = path.join(workspaceRoot, relPath);
+        const ext = path.extname(relPath).toLowerCase();
+        let content;
+        try {
+            content = await fs.readFile(absPath, 'utf-8');
+        }
+        catch {
+            return; // Unreadable file — skip
+        }
+        const rawImports = extractImports(content, ext);
+        const sourceNode = getOrCreate(relPath);
+        for (const specifier of rawImports) {
+            const resolved = await resolveImportPath(workspaceRoot, relPath, specifier);
+            if (resolved) {
+                sourceNode.imports.add(resolved);
+                const targetNode = getOrCreate(resolved);
+                targetNode.importedBy.add(relPath);
+            }
+        }
+    }));
+    // 3. Return the graph with query methods
+    return {
+        nodes,
+        getImports(filePath) {
+            return Array.from(nodes.get(filePath)?.imports || []);
+        },
+        getImportedBy(filePath) {
+            return Array.from(nodes.get(filePath)?.importedBy || []);
+        },
+        getReverseDependencyTree(filePath, maxDepth = 3) {
+            return bfsTraverse(nodes, filePath, 'importedBy', maxDepth);
+        },
+        getForwardDependencyTree(filePath, maxDepth = 3) {
+            return bfsTraverse(nodes, filePath, 'imports', maxDepth);
+        },
+    };
+}
+/**
+ * BFS traversal of the dependency graph in a given direction.
+ * Returns all unique files reachable from `startFile` within `maxDepth` hops.
+ * The start file itself is NOT included in the result.
+ */
+function bfsTraverse(nodes, startFile, direction, maxDepth) {
+    const visited = new Set();
+    visited.add(startFile); // Exclude the starting file from results
+    const queue = [{ file: startFile, depth: 0 }];
+    const result = [];
+    while (queue.length > 0) {
+        const { file, depth } = queue.shift();
+        if (depth >= maxDepth)
+            continue;
+        const node = nodes.get(file);
+        if (!node)
+            continue;
+        const neighbors = node[direction];
+        for (const neighbor of neighbors) {
+            if (!visited.has(neighbor)) {
+                visited.add(neighbor);
+                result.push(neighbor);
+                queue.push({ file: neighbor, depth: depth + 1 });
+            }
+        }
+    }
+    return result;
+}
+/**
+ * High-level function exposed as a tool to the agents.
+ * Builds the dependency graph (or reuses if already built in this invocation),
+ * then queries it for the specified file.
+ */
+export async function findDependencies(workspaceRoot, filePath, direction = 'both', maxDepth = 3) {
+    const graph = await buildDependencyGraph(workspaceRoot);
+    const forwardDeps = direction !== 'reverse' ? graph.getImports(filePath) : [];
+    const reverseDeps = direction !== 'forward' ? graph.getImportedBy(filePath) : [];
+    const forwardTree = direction !== 'reverse' ? graph.getForwardDependencyTree(filePath, maxDepth) : [];
+    const reverseTree = direction !== 'forward' ? graph.getReverseDependencyTree(filePath, maxDepth) : [];
+    return { filePath, forwardDeps, reverseDeps, forwardTree, reverseTree };
+}
+/**
+ * Formats a FindDependenciesResult into a human-readable string
+ * suitable for feeding back to the LLM.
+ */
+export function formatDependencyResult(result) {
+    const lines = [];
+    lines.push(`Dependency analysis for: ${result.filePath}`);
+    lines.push('');
+    if (result.forwardDeps.length > 0 || result.forwardTree.length > 0) {
+        lines.push('─── Direct Imports (what this file imports) ───');
+        if (result.forwardDeps.length > 0) {
+            for (const dep of result.forwardDeps) {
+                lines.push(`  → ${dep}`);
+            }
+        }
+        else {
+            lines.push('  (none)');
+        }
+        lines.push('');
+        if (result.forwardTree.length > result.forwardDeps.length) {
+            lines.push('─── Transitive Import Tree ───');
+            for (const dep of result.forwardTree) {
+                const isDirect = result.forwardDeps.includes(dep);
+                lines.push(`  ${isDirect ? '→' : '↳'} ${dep}${isDirect ? '' : ' (transitive)'}`);
+            }
+            lines.push('');
+        }
+    }
+    if (result.reverseDeps.length > 0 || result.reverseTree.length > 0) {
+        lines.push('─── Direct Dependents (files that import this file) ───');
+        if (result.reverseDeps.length > 0) {
+            for (const dep of result.reverseDeps) {
+                lines.push(`  ← ${dep}`);
+            }
+        }
+        else {
+            lines.push('  (none)');
+        }
+        lines.push('');
+        if (result.reverseTree.length > result.reverseDeps.length) {
+            lines.push('─── Transitive Dependent Tree ───');
+            for (const dep of result.reverseTree) {
+                const isDirect = result.reverseDeps.includes(dep);
+                lines.push(`  ${isDirect ? '←' : '↰'} ${dep}${isDirect ? '' : ' (transitive)'}`);
+            }
+            lines.push('');
+        }
+    }
+    if (result.forwardDeps.length === 0 && result.reverseDeps.length === 0) {
+        lines.push('No dependencies found. This file appears to be standalone (no imports and nothing imports it).');
+    }
+    const totalImpact = new Set([...result.forwardTree, ...result.reverseTree]).size;
+    lines.push(`Total impact radius: ${totalImpact} file(s)`);
+    return lines.join('\n');
+}
+/**
+ * Resets the tsconfig alias cache (useful between workspace changes).
+ */
+export function resetAliasCache() {
+    cachedAliases = null;
+    cachedAliasRoot = null;
+}

package/dist/utils/excludedExtensions.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Comprehensive list of binary/generated file extensions that grep should skip.
+ * Covers images, video, audio, fonts, archives, documents, compiled artifacts,
+ * IDE files, and tool-specific generated files across all major languages.
+ * These are used to prevent commands like `grep` from searching through
+ * non-textual or compiled files, which can lead to incorrect results or errors.
+ */
+export declare const EXCLUDED_EXTENSIONS: string[];