ng-di-graph 0.4.7 → 0.6.0

package/README.md

@@ -10,7 +10,7 @@ A command-line tool that analyzes Angular TypeScript codebases to extract depend
 
 ## Prerequisites
 - Node.js 20.x (npm 10+)
-- Angular project targeting v17-20 with a `tsconfig.json` you can point to
+- Angular project targeting v17-20 with a `tsconfig.json` to discover or reference
 
 ## Installation
 ```bash
@@ -19,20 +19,23 @@ npm install -g ng-di-graph
 
 ## Quick start
 ```bash
-# Analyze the whole project and print JSON
-ng-di-graph --project ./tsconfig.json --format json
+# Analyze the whole project and print text output (default)
+ng-di-graph
 
 # Generate a Mermaid diagram and save it
-ng-di-graph --project ./tsconfig.json --format mermaid --out docs/di-graph.mmd
+ng-di-graph --format mermaid --out docs/di-graph.mmd
 
 # Target specific files via positional filePaths
-ng-di-graph src/app/app.component.ts src/app/auth.service.ts --project ./tsconfig.json --format json
+ng-di-graph src/app/app.component.ts src/app/auth.service.ts --format json
 
-# Use the default tsconfig at ./tsconfig.json (no --project needed)
+# Auto-discover the nearest tsconfig.json (no --project needed)
 ng-di-graph src/app --format mermaid --out docs/di-graph.mmd
 
 # Focus on a symbol and see who depends on it
-ng-di-graph --project ./tsconfig.json --entry UserService --direction upstream
+ng-di-graph --entry UserService --direction upstream
+
+# Override auto-discovery with an explicit tsconfig
+ng-di-graph --project ./tsconfig.json --format json
 ```
 
 ## Features
@@ -42,22 +45,24 @@ ng-di-graph --project ./tsconfig.json --entry UserService --direction upstream
 - 🔍 **Dependency Analysis** - Extract DI relationships from `@Injectable`, `@Component`, and `@Directive` classes
 - 🎯 **Constructor Injection** - Analyze constructor parameters with type annotations and `@Inject()` tokens
 - 🏷️ **Decorator Flags** - Capture `@Optional`, `@Self`, `@SkipSelf`, and `@Host` parameter decorators
-- 📊 **Multiple Output Formats** - JSON (machine-readable) and Mermaid (visual flowcharts)
+- 📊 **Multiple Output Formats** - Text (default), JSON (machine-readable), Mermaid (visual flowcharts)
 - 🎨 **Entry Point Filtering** - Generate sub-graphs from specific starting nodes
 - 🔄 **Bidirectional Analysis** - Explore upstream dependencies, downstream consumers, or both
 - 🔁 **Circular Detection** - Automatically detect and report circular dependencies
 
 ## Common commands
-- Full project, JSON output:  
-  `ng-di-graph --project ./tsconfig.json --format json`
+- Full project, text output (default):  
+  `ng-di-graph`
+- JSON output to stdout:  
+  `ng-di-graph --format json`
 - Mermaid diagram to file:  
-  `ng-di-graph --project ./tsconfig.json --format mermaid --out docs/di-graph.mmd`
+  `ng-di-graph --format mermaid --out docs/di-graph.mmd`
 - Filter to specific symbols:  
-  `ng-di-graph --project ./tsconfig.json --entry AppComponent`
+  `ng-di-graph --entry AppComponent`
 - Upstream consumers of a service:  
-  `ng-di-graph --project ./tsconfig.json --entry UserService --direction upstream`
+  `ng-di-graph --entry UserService --direction upstream`
 - Include decorator flags with verbose logging:  
-  `ng-di-graph --project ./tsconfig.json --include-decorators --verbose`
+  `ng-di-graph --include-decorators --verbose`
 
 ## CLI options at a glance
 
@@ -68,9 +73,9 @@ ng-di-graph [filePaths...] [options]
 Option | Default | Description
 -- | -- | --
 `filePaths` | none | Positional alias for `--files`; combines with `--files` when both are set.
-`-p, --project <path>` | `./tsconfig.json` | Path to the TypeScript config file to analyze.
+`-p, --project <path>` | auto-discovered | Path to the TypeScript config file to analyze (omit to auto-discover).
 `--files <paths...>` | none | Limit analysis to specific files or directories.
-`-f, --format <format>` | `json` | Output as `json` or `mermaid`.
+`-f, --format <format>` | `text` | Output as `text`, `json`, or `mermaid`.
 `-e, --entry <symbol...>` | none | Start the graph from one or more symbols.
 `-d, --direction <dir>` | `downstream` | `downstream`, `upstream`, or `both` relative to entries.
 `--include-decorators` | `false` | Add `@Optional`, `@Self`, `@SkipSelf`, `@Host` flags to edges.
@@ -80,15 +85,47 @@ Option | Default | Description
 
 ## Output Formats
 
+### Text Format (default)
+
+```text
+Project: ./tsconfig.json
+Scope: direction=downstream, entry=all
+Files: 12 (skipped: 0)
+
+Dependencies (A depends on B):
+AppComponent
+└─ UserService
+
+UserService
+├─ AuthService
+└─ Logger
+```
+
 ### JSON Format
 
 ```json
 {
   "nodes": [
-    { "id": "AppComponent", "kind": "component" },
-    { "id": "UserService", "kind": "service" },
-    { "id": "AuthService", "kind": "service" },
-    { "id": "Logger", "kind": "service" }
+    {
+      "id": "AppComponent",
+      "kind": "component",
+      "source": { "filePath": "/path/to/src/app.component.ts", "line": 12, "column": 14 }
+    },
+    {
+      "id": "UserService",
+      "kind": "service",
+      "source": { "filePath": "/path/to/src/user.service.ts", "line": 8, "column": 14 }
+    },
+    {
+      "id": "AuthService",
+      "kind": "service",
+      "source": { "filePath": "/path/to/src/auth.service.ts", "line": 20, "column": 14 }
+    },
+    {
+      "id": "Logger",
+      "kind": "service",
+      "source": { "filePath": "/path/to/src/logger.service.ts", "line": 5, "column": 14 }
+    }
   ],
   "edges": [
     {
@@ -116,6 +153,11 @@ Option | Default | Description
 - `directive` - Classes decorated with `@Directive()`
 - `unknown` - Could not determine decorator type
 
+**Node Source** (when available):
+- `source.filePath` - Absolute file path reported by the TypeScript project
+- `source.line` / `source.column` - 1-based position of the class name token
+- `source` is omitted for `unknown` nodes created from unresolved tokens
+
 **Edge Flags** (when `--include-decorators` is used):
 - `optional` - Parameter has `@Optional()` decorator
 - `self` - Parameter has `@Self()` decorator

package/dist/cli/index.cjs

@@ -26,10 +26,10 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 
 //#endregion
+let commander = require("commander");
 let node_fs = require("node:fs");
 let node_path = require("node:path");
 node_path = __toESM(node_path);
-let commander = require("commander");
 let ts_morph = require("ts-morph");
 let typescript = require("typescript");
 typescript = __toESM(typescript);
@@ -378,6 +378,9 @@ function validateInput(parsedClasses) {
 		if (typeof parsedClass.kind !== "string") throw new Error("ParsedClass must have a valid kind property");
 		if (parsedClass.dependencies == null) throw new Error("ParsedClass must have a dependencies array");
 		if (!Array.isArray(parsedClass.dependencies)) throw new Error("ParsedClass dependencies must be an array");
+		if (!parsedClass.source) throw new Error("ParsedClass must have a valid source property");
+		if (typeof parsedClass.source.filePath !== "string" || parsedClass.source.filePath === "") throw new Error("ParsedClass source must have a valid filePath");
+		if (!Number.isFinite(parsedClass.source.line) || !Number.isFinite(parsedClass.source.column) || parsedClass.source.line < 1 || parsedClass.source.column < 1) throw new Error("ParsedClass source must include valid line and column values");
 		for (const dependency of parsedClass.dependencies) if (typeof dependency.token !== "string") throw new Error("ParsedDependency must have a valid token property");
 	}
 }
@@ -402,11 +405,11 @@ function detectCircularDependencies(edges, nodes) {
 	/**
 	* DFS helper function to detect cycles
 	*/
-	function dfs(node, path$1) {
+	function dfs(node, path$2) {
 		if (processedNodes.has(node)) return;
 		if (recursionStack.has(node)) {
-			const cycleStartIndex = path$1.indexOf(node);
-			const cyclePath = [...path$1.slice(cycleStartIndex), node];
+			const cycleStartIndex = path$2.indexOf(node);
+			const cyclePath = [...path$2.slice(cycleStartIndex), node];
 			circularDependencies.push(cyclePath);
 			for (let i = 0; i < cyclePath.length - 1; i++) {
 				const edgeKey = `${cyclePath[i]}->${cyclePath[i + 1]}`;
@@ -415,7 +418,7 @@ function detectCircularDependencies(edges, nodes) {
 			return;
 		}
 		recursionStack.add(node);
-		const newPath = [...path$1, node];
+		const newPath = [...path$2, node];
 		const neighbors = adjacencyList.get(node) || [];
 		for (const neighbor of neighbors) dfs(neighbor, newPath);
 		recursionStack.delete(node);
@@ -441,7 +444,8 @@ function buildGraph(parsedClasses, logger) {
 	const edges = [];
 	for (const parsedClass of parsedClasses) if (!nodeMap.has(parsedClass.name)) nodeMap.set(parsedClass.name, {
 		id: parsedClass.name,
-		kind: parsedClass.kind
+		kind: parsedClass.kind,
+		source: parsedClass.source
 	});
 	logger?.info(LogCategory.GRAPH_CONSTRUCTION, `Created ${nodeMap.size} nodes`, { nodeCount: nodeMap.size });
 	let unknownNodeCount = 0;
@@ -660,6 +664,10 @@ var AngularParser = class {
 		this._logger = _logger;
 		this._typeResolutionCache = /* @__PURE__ */ new Map();
 		this._circularTypeRefs = /* @__PURE__ */ new Set();
+		this._processingStats = {
+			processedFileCount: 0,
+			skippedFileCount: 0
+		};
 		this._structuredWarnings = {
 			categories: {
 				typeResolution: [],
@@ -710,6 +718,12 @@ var AngularParser = class {
 		};
 	}
 	/**
+	* Get file processing stats from the most recent parse run.
+	*/
+	getProcessingStats() {
+		return { ...this._processingStats };
+	}
+	/**
 	* Add structured warning to collection (Task 3.3)
 	* Includes global deduplication for both structured warnings and console output
 	* @param category Warning category
@@ -898,6 +912,10 @@ var AngularParser = class {
 		const sourceFiles = this.getTargetSourceFiles();
 		let processedFiles = 0;
 		let skippedFiles = 0;
+		this._processingStats = {
+			processedFileCount: 0,
+			skippedFileCount: 0
+		};
 		this._circularTypeRefs.clear();
 		this._logger?.time("findDecoratedClasses");
 		this._logger?.info(LogCategory.FILE_PROCESSING, "Starting file processing", { fileCount: sourceFiles.length });
@@ -948,6 +966,10 @@ var AngularParser = class {
 			timing: elapsed
 		});
 		if (decoratedClasses.length === 0) ErrorHandler.warn("No decorated classes found in the project");
+		this._processingStats = {
+			processedFileCount: processedFiles,
+			skippedFileCount: skippedFiles
+		};
 		return decoratedClasses;
 	}
 	/**
@@ -963,6 +985,13 @@ var AngularParser = class {
 			else ErrorHandler.warn(message);
 			return null;
 		}
+		const nameNode = classDeclaration.getNameNode();
+		if (!nameNode) {
+			const message = "Skipping class without name node - classes must be named for dependency injection analysis";
+			if (this._logger) this._logger.warn(LogCategory.AST_ANALYSIS, message, { className });
+			else ErrorHandler.warn(message);
+			return null;
+		}
 		const decorators = classDeclaration.getDecorators();
 		if (this._options.verbose) {
 			const decoratorNames = decorators.map((d) => this.getDecoratorName(d)).join(", ");
@@ -980,10 +1009,19 @@ var AngularParser = class {
 			});
 			return null;
 		}
+		const nodeKind = this.determineNodeKind(angularDecorator);
+		const sourceFile = classDeclaration.getSourceFile();
+		const filePath = sourceFile.getFilePath();
+		const { line, column } = sourceFile.getLineAndColumnAtPos(nameNode.getStart());
 		return {
 			name: className,
-			kind: this.determineNodeKind(angularDecorator),
-			filePath: classDeclaration.getSourceFile().getFilePath(),
+			kind: nodeKind,
+			filePath,
+			source: {
+				filePath,
+				line,
+				column
+			},
 			dependencies: this.extractConstructorDependencies(classDeclaration)
 		};
 	}
@@ -1974,6 +2012,249 @@ var MermaidFormatter = class {
 	}
 };
 
+//#endregion
+//#region src/formatters/text-formatter.ts
+var TextFormatter = class {
+	constructor(context = {}, logger) {
+		this._context = context;
+		this._logger = logger;
+	}
+	format(graph) {
+		this._logger?.time("text-format");
+		this._logger?.info(LogCategory.PERFORMANCE, "Generating text output", {
+			nodeCount: graph.nodes.length,
+			edgeCount: graph.edges.length
+		});
+		const warningCount = this._context.warningCount ?? this._context.warnings?.length ?? 0;
+		const circularDependencyCount = graph.circularDependencies.length;
+		const lines = [];
+		if (this._context.projectPath) lines.push(`Project: ${this._context.projectPath}`);
+		if (this._context.direction) {
+			const entry = this._context.entry && this._context.entry.length > 0 ? this._context.entry.join(", ") : "all";
+			lines.push(`Scope: direction=${this._context.direction}, entry=${entry}`);
+		}
+		lines.push(`Files: ${this._context.processedFileCount ?? 0} (skipped: ${this._context.skippedFileCount ?? 0})`);
+		if (warningCount > 0) lines.push(`Warnings: ${warningCount}`);
+		if (circularDependencyCount > 0) lines.push(`Circular dependencies: ${circularDependencyCount}`);
+		const dependencyGroups = this.getDependencyGroups(graph, 10);
+		if (dependencyGroups.length > 0) {
+			lines.push("");
+			lines.push("Dependencies (A depends on B):");
+			lines.push(...dependencyGroups);
+		}
+		const result = `${lines.join("\n")}\n`;
+		const elapsed = this._logger?.timeEnd("text-format") ?? 0;
+		this._logger?.info(LogCategory.PERFORMANCE, "Text output complete", {
+			outputSize: result.length,
+			elapsed
+		});
+		return result;
+	}
+	getDependencyGroups(graph, limit) {
+		const uniqueEdges = /* @__PURE__ */ new Map();
+		for (const edge of graph.edges) {
+			const key = `${edge.from}->${edge.to}`;
+			if (!uniqueEdges.has(key)) uniqueEdges.set(key, {
+				from: edge.from,
+				to: edge.to
+			});
+		}
+		const sortedEdges = [...uniqueEdges.values()].sort((a, b) => {
+			const fromOrder = a.from.localeCompare(b.from);
+			return fromOrder !== 0 ? fromOrder : a.to.localeCompare(b.to);
+		}).slice(0, limit);
+		const grouped = /* @__PURE__ */ new Map();
+		for (const edge of sortedEdges) {
+			const deps = grouped.get(edge.from);
+			if (deps) deps.push(edge.to);
+			else grouped.set(edge.from, [edge.to]);
+		}
+		const lines = [];
+		const groups = [...grouped.entries()];
+		for (let i = 0; i < groups.length; i++) {
+			const [from, deps] = groups[i];
+			lines.push(from);
+			for (let depIndex = 0; depIndex < deps.length; depIndex++) {
+				const dep = deps[depIndex];
+				const prefix = depIndex === deps.length - 1 ? "└─" : "├─";
+				lines.push(`${prefix} ${dep}`);
+			}
+			if (i < groups.length - 1) lines.push("");
+		}
+		return lines;
+	}
+};
+
+//#endregion
+//#region src/cli/project-resolver.ts
+const TSCONFIG_NAME = "tsconfig.json";
+const WORKSPACE_FILES = ["angular.json", "workspace.json"];
+const WORKSPACE_TARGET_ORDER = [
+	"build",
+	"test",
+	"serve",
+	"lint",
+	"e2e"
+];
+function resolveProjectPath(options) {
+	const { projectOption, fileTargets, cwd, logger } = options;
+	if (projectOption) {
+		const resolved = normalizeExplicitProject(projectOption);
+		logDiscovery(logger, "Using explicit --project path", { project: resolved });
+		return resolved;
+	}
+	const resolvedFromTargets = resolveFromFileTargets(fileTargets, cwd, logger);
+	if (resolvedFromTargets) {
+		logDiscovery(logger, "Auto-discovered tsconfig.json from file targets", { project: resolvedFromTargets });
+		return resolvedFromTargets;
+	}
+	const startDir = fileTargets.length > 0 ? getCommonAncestor(fileTargets, cwd) : cwd;
+	const tsconfigPath = findNearestTsconfig(startDir);
+	if (tsconfigPath) {
+		logDiscovery(logger, "Auto-discovered tsconfig.json", {
+			startDir,
+			project: tsconfigPath
+		});
+		return tsconfigPath;
+	}
+	const workspaceResolution = resolveWorkspaceTsconfig(startDir);
+	if (workspaceResolution) {
+		logDiscovery(logger, "Resolved tsconfig via Angular workspace", {
+			workspace: workspaceResolution.workspacePath,
+			project: workspaceResolution.tsconfigPath
+		});
+		return workspaceResolution.tsconfigPath;
+	}
+	throw ErrorHandler.createError(`tsconfig.json not found starting from: ${startDir}`, "TSCONFIG_NOT_FOUND", startDir, { startDir });
+}
+function normalizeExplicitProject(projectOption) {
+	try {
+		if ((0, node_fs.statSync)(projectOption).isDirectory()) {
+			const tsconfigPath = node_path.default.join(projectOption, TSCONFIG_NAME);
+			if ((0, node_fs.existsSync)(tsconfigPath)) return tsconfigPath;
+		}
+	} catch {}
+	return projectOption;
+}
+function resolveFromFileTargets(fileTargets, cwd, logger) {
+	if (fileTargets.length === 0) return;
+	const targetDirectories = getTargetDirectories(fileTargets, cwd);
+	const resolvedConfigs = /* @__PURE__ */ new Map();
+	const missingTargets = [];
+	for (const directory of targetDirectories) {
+		const configPath = findNearestTsconfig(directory);
+		if (configPath) {
+			const targets = resolvedConfigs.get(configPath) ?? [];
+			targets.push(directory);
+			resolvedConfigs.set(configPath, targets);
+		} else missingTargets.push(directory);
+	}
+	if (resolvedConfigs.size > 1) {
+		const configPaths = Array.from(resolvedConfigs.keys());
+		throw ErrorHandler.createError("File targets resolve to multiple tsconfig.json files. Use --project to select one.", "INVALID_ARGUMENTS", void 0, { configs: configPaths });
+	}
+	if (resolvedConfigs.size === 1 && missingTargets.length > 0) {
+		const [configPath] = resolvedConfigs.keys();
+		throw ErrorHandler.createError("Some file targets do not resolve to a tsconfig.json. Use --project to select one.", "INVALID_ARGUMENTS", void 0, {
+			configPath,
+			missingTargets
+		});
+	}
+	const [singleConfig] = resolvedConfigs.keys();
+	if (singleConfig) {
+		logDiscovery(logger, "Resolved tsconfig.json for file targets", { project: singleConfig });
+		return singleConfig;
+	}
+}
+function getTargetDirectories(fileTargets, cwd) {
+	const directories = /* @__PURE__ */ new Set();
+	for (const target of fileTargets) {
+		const directory = resolveTargetDirectory(resolvePath(target, cwd));
+		directories.add(directory);
+	}
+	return [...directories];
+}
+function resolveTargetDirectory(targetPath) {
+	try {
+		if ((0, node_fs.statSync)(targetPath).isDirectory()) return targetPath;
+	} catch {}
+	return node_path.default.dirname(targetPath);
+}
+function findNearestTsconfig(startDir) {
+	return typescript.findConfigFile(startDir, typescript.sys.fileExists, TSCONFIG_NAME);
+}
+function resolveWorkspaceTsconfig(startDir) {
+	for (const workspaceFile of WORKSPACE_FILES) {
+		const workspacePath = typescript.findConfigFile(startDir, typescript.sys.fileExists, workspaceFile);
+		if (!workspacePath) continue;
+		const workspaceConfig = readJsonConfig(workspacePath);
+		if (!workspaceConfig) continue;
+		const tsconfigPath = selectWorkspaceTsconfig(workspaceConfig, workspacePath);
+		if (tsconfigPath) return {
+			workspacePath,
+			tsconfigPath
+		};
+	}
+}
+function readJsonConfig(configPath) {
+	const configFile = typescript.readConfigFile(configPath, typescript.sys.readFile);
+	if (configFile.error) return;
+	return configFile.config;
+}
+function selectWorkspaceTsconfig(workspaceConfig, workspacePath) {
+	if (!workspaceConfig || typeof workspaceConfig !== "object") return;
+	const config = workspaceConfig;
+	const projects = config.projects ?? {};
+	const projectNames = Object.keys(projects);
+	if (projectNames.length === 0) return;
+	const projectConfig = projects[(config.defaultProject && projects[config.defaultProject] ? config.defaultProject : projectNames.length === 1 ? projectNames[0] : void 0) ?? projectNames[0]];
+	const tsconfig = findWorkspaceTargetTsconfig(projectConfig?.architect ?? projectConfig?.targets ?? {});
+	if (!tsconfig) return;
+	const resolvedPath = node_path.default.resolve(node_path.default.dirname(workspacePath), tsconfig);
+	return (0, node_fs.existsSync)(resolvedPath) ? resolvedPath : void 0;
+}
+function findWorkspaceTargetTsconfig(targets) {
+	for (const targetName of WORKSPACE_TARGET_ORDER) {
+		const tsconfig = targets[targetName]?.options?.tsConfig;
+		if (tsconfig) return tsconfig;
+	}
+	for (const targetName of Object.keys(targets).sort()) {
+		const tsconfig = targets[targetName]?.options?.tsConfig;
+		if (tsconfig) return tsconfig;
+	}
+}
+function getCommonAncestor(fileTargets, cwd) {
+	const targetDirs = getTargetDirectories(fileTargets, cwd);
+	if (targetDirs.length === 0) return cwd;
+	const [first, ...rest] = targetDirs.map((dir) => node_path.default.resolve(dir));
+	const baseParts = splitPath(first);
+	let commonLength = baseParts.length;
+	for (const dir of rest) {
+		const parts = splitPath(dir);
+		commonLength = Math.min(commonLength, parts.length);
+		for (let i = 0; i < commonLength; i += 1) if (parts[i] !== baseParts[i]) {
+			commonLength = i;
+			break;
+		}
+	}
+	const commonParts = baseParts.slice(0, commonLength);
+	if (commonParts.length === 0) return node_path.default.parse(first).root;
+	const [root, ...segments] = commonParts;
+	return root ? node_path.default.join(root, ...segments) : node_path.default.join(...segments);
+}
+function splitPath(value) {
+	const resolved = node_path.default.resolve(value);
+	const { root } = node_path.default.parse(resolved);
+	const segments = resolved.slice(root.length).split(node_path.default.sep).filter(Boolean);
+	return root ? [root, ...segments] : segments;
+}
+function resolvePath(value, cwd) {
+	return node_path.default.isAbsolute(value) ? value : node_path.default.resolve(cwd, value);
+}
+function logDiscovery(logger, message, context) {
+	logger?.info(LogCategory.FILE_PROCESSING, message, context);
+}
+
 //#endregion
 //#region src/cli/index.ts
 /**
@@ -1996,31 +2277,31 @@ function enforceMinimumNodeVersion() {
 	process.exit(1);
 }
 enforceMinimumNodeVersion();
-function resolveProjectPath(projectOption) {
-	const candidatePath = projectOption;
-	try {
-		if ((0, node_fs.statSync)(candidatePath).isDirectory()) {
-			const tsconfigPath = (0, node_path.join)(candidatePath, "tsconfig.json");
-			if ((0, node_fs.existsSync)(tsconfigPath)) return tsconfigPath;
-		}
-	} catch {}
-	return candidatePath;
-}
 const program = new commander.Command();
 program.name("ng-di-graph").description("Angular DI dependency graph CLI tool").version("0.1.0");
-program.argument("[filePaths...]", "TypeScript files to analyze (alias for --files)").option("-p, --project <path>", "tsconfig.json path", "./tsconfig.json").option("--files <paths...>", "specific file paths to analyze (similar to eslint targets)").option("-f, --format <format>", "output format: json | mermaid", "json").option("-e, --entry <symbol...>", "starting nodes for sub-graph").option("-d, --direction <dir>", "filtering direction: upstream|downstream|both", "downstream").option("--include-decorators", "include Optional/Self/SkipSelf/Host flags", false).option("--out <file>", "output file (stdout if omitted)").option("-v, --verbose", "show detailed parsing information", false);
+program.argument("[filePaths...]", "TypeScript files to analyze (alias for --files)").option("-p, --project <path>", "tsconfig.json path (auto-discovered if omitted)").option("--files <paths...>", "specific file paths to analyze (similar to eslint targets)").option("-f, --format <format>", "output format: text | json | mermaid", "text").option("-e, --entry <symbol...>", "starting nodes for sub-graph").option("-d, --direction <dir>", "filtering direction: upstream|downstream|both", "downstream").option("--include-decorators", "include Optional/Self/SkipSelf/Host flags", false).option("--out <file>", "output file (stdout if omitted)").option("-v, --verbose", "show detailed parsing information", false);
 program.action(async (filePaths = [], options) => {
 	try {
-		const project = resolveProjectPath(options.project);
+		const mergedFiles = mergeFileTargets(filePaths, options.files);
+		const logger = createLogger(options.verbose);
+		const project = resolveProjectPath({
+			projectOption: options.project,
+			fileTargets: mergedFiles,
+			cwd: process.cwd(),
+			logger
+		});
 		if (options.direction && ![
 			"upstream",
 			"downstream",
 			"both"
 		].includes(options.direction)) throw ErrorHandler.createError(`Invalid direction: ${options.direction}. Must be 'upstream', 'downstream', or 'both'`, "INVALID_ARGUMENTS");
-		if (options.format && !["json", "mermaid"].includes(options.format)) throw ErrorHandler.createError(`Invalid format: ${options.format}. Must be 'json' or 'mermaid'`, "INVALID_ARGUMENTS");
+		if (options.format && ![
+			"json",
+			"mermaid",
+			"text"
+		].includes(options.format)) throw ErrorHandler.createError(`Invalid format: ${options.format}. Must be 'text', 'json', or 'mermaid'`, "INVALID_ARGUMENTS");
 		const tsconfigLikePositional = filePaths.find((filePath) => /(?:^|[\\/])tsconfig(?:\.[^/\\]+)?\.json$/.test(filePath));
 		if (tsconfigLikePositional) throw ErrorHandler.createError(`Positional argument "${tsconfigLikePositional}" looks like a tsconfig. Use --project "${tsconfigLikePositional}" instead.`, "INVALID_ARGUMENTS");
-		const mergedFiles = mergeFileTargets(filePaths, options.files);
 		const cliOptions = {
 			project,
 			files: mergedFiles.length > 0 ? mergedFiles : void 0,
@@ -2031,7 +2312,6 @@ program.action(async (filePaths = [], options) => {
 			out: options.out,
 			verbose: options.verbose
 		};
-		const logger = createLogger(cliOptions.verbose);
 		if (logger) {
 			logger.time("total-execution");
 			logger.info(LogCategory.FILE_PROCESSING, "CLI execution started", {
@@ -2064,7 +2344,18 @@ program.action(async (filePaths = [], options) => {
 		}
 		let formatter;
 		if (cliOptions.format === "mermaid") formatter = new MermaidFormatter(logger);
-		else formatter = new JsonFormatter(logger);
+		else if (cliOptions.format === "json") formatter = new JsonFormatter(logger);
+		else {
+			const processingStats = parser.getProcessingStats();
+			formatter = new TextFormatter({
+				projectPath: cliOptions.project,
+				direction: cliOptions.direction,
+				entry: cliOptions.entry,
+				processedFileCount: processingStats.processedFileCount,
+				skippedFileCount: processingStats.skippedFileCount,
+				warningCount: parser.getStructuredWarnings().totalCount
+			}, logger);
+		}
 		const formattedOutput = formatter.format(graph);
 		await new OutputHandler().writeOutput(formattedOutput, cliOptions.out);
 		if (cliOptions.verbose && cliOptions.out) console.log(`✅ Output written to: ${cliOptions.out}`);