ng-di-graph 0.5.0 → 0.6.0

package/README.md

@@ -19,8 +19,8 @@ npm install -g ng-di-graph
 
 ## Quick start
 ```bash
-# Analyze the whole project and print JSON (auto-discover tsconfig)
-ng-di-graph --format json
+# Analyze the whole project and print text output (default)
+ng-di-graph
 
 # Generate a Mermaid diagram and save it
 ng-di-graph --format mermaid --out docs/di-graph.mmd
@@ -45,13 +45,15 @@ ng-di-graph --project ./tsconfig.json --format json
 - 🔍 **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:  
+- Full project, text output (default):  
+  `ng-di-graph`
+- JSON output to stdout:  
   `ng-di-graph --format json`
 - Mermaid diagram to file:  
   `ng-di-graph --format mermaid --out docs/di-graph.mmd`
@@ -73,7 +75,7 @@ Option | Default | Description
 `filePaths` | none | Positional alias for `--files`; combines with `--files` when both are set.
 `-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.
@@ -83,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": [
     {
@@ -119,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

@@ -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");
 	}
 }
@@ -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,79 @@ 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";
@@ -2168,7 +2279,7 @@ function enforceMinimumNodeVersion() {
 enforceMinimumNodeVersion();
 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 (auto-discovered if omitted)").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 mergedFiles = mergeFileTargets(filePaths, options.files);
@@ -2184,7 +2295,11 @@ program.action(async (filePaths = [], options) => {
 			"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 cliOptions = {
@@ -2229,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}`);