ng-di-graph 0.4.6 → 0.5.0

package/README.md

@@ -8,95 +8,78 @@ A command-line tool that analyzes Angular TypeScript codebases to extract depend
 
 **Target Angular Versions:** 17-20
 
-## Requirements
-
-- Node.js 20.x LTS (see `.node-version`; e.g., `mise use node@$(cat .node-version)`)
-- npm 10+ (ships with Node 20). Use your preferred version manager (mise recommended) to match the pinned runtime before installing dependencies.
-
-## Features
-
-✨ **Complete Feature Set** - Production-ready dependency graph analysis for Angular applications
-
-- 🔍 **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)
-- 🎨 **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
+## Prerequisites
+- Node.js 20.x (npm 10+)
+- Angular project targeting v17-20 with a `tsconfig.json` to discover or reference
 
 ## Installation
-
 ```bash
 npm install -g ng-di-graph
 ```
 
-## Usage
-
+## Quick start
 ```bash
-# Target specific files without the --files flag (positional shortcut)
-ng-di-graph src/app/app.component.ts --project ./tsconfig.json --format json
+# Analyze the whole project and print JSON (auto-discover tsconfig)
+ng-di-graph --format json
 
-# Analyze an Angular project and output JSON
-ng-di-graph --project ./my-angular-app/tsconfig.json --format json
+# Generate a Mermaid diagram and save it
+ng-di-graph --format mermaid --out docs/di-graph.mmd
 
-# Generate a Mermaid flowchart
-ng-di-graph --project ./tsconfig.json --format mermaid --out graph.mmd
+# Target specific files via positional filePaths
+ng-di-graph src/app/app.component.ts src/app/auth.service.ts --format json
 
-# Analyze dependencies of a specific component
-ng-di-graph --project ./tsconfig.json --entry AppComponent --format mermaid
+# Auto-discover the nearest tsconfig.json (no --project needed)
+ng-di-graph src/app --format mermaid --out docs/di-graph.mmd
 
-# Focus on a specific file (similar to eslint targets)
-ng-di-graph --project ./tsconfig.json --files src/app/app.component.ts
+# Focus on a symbol and see who depends on it
+ng-di-graph --entry UserService --direction upstream
 
-# Show verbose logging with detailed type resolution
-ng-di-graph --project ./tsconfig.json --verbose
+# Override auto-discovery with an explicit tsconfig
+ng-di-graph --project ./tsconfig.json --format json
+```
 
-# Include parameter decorator flags
-ng-di-graph --project ./tsconfig.json --include-decorators
+## Features
 
-# Analyze upstream dependencies (who depends on this?)
-ng-di-graph --project ./tsconfig.json --entry UserService --direction upstream
-```
+✨ **Complete Feature Set** - Production-ready dependency graph analysis for Angular applications
+
+- 🔍 **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)
+- 🎨 **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
 
-## CLI Reference
+## Common commands
+- Full project, JSON output:  
+  `ng-di-graph --format json`
+- Mermaid diagram to file:  
+  `ng-di-graph --format mermaid --out docs/di-graph.mmd`
+- Filter to specific symbols:  
+  `ng-di-graph --entry AppComponent`
+- Upstream consumers of a service:  
+  `ng-di-graph --entry UserService --direction upstream`
+- Include decorator flags with verbose logging:  
+  `ng-di-graph --include-decorators --verbose`
+
+## CLI options at a glance
 
 ```
 ng-di-graph [filePaths...] [options]
-
-Arguments:
-  filePaths                 Optional list of files/directories to analyze (alias for --files)
-
-Options:
-  -p, --project <path>       Path to tsconfig.json (default: ./tsconfig.json)
-  --files <paths...>         Specific file paths to analyze (similar to eslint targets)
-  -f, --format <format>      Output format: json | mermaid (default: json)
-  -e, --entry <symbol...>    Starting nodes for sub-graph filtering
-  -d, --direction <dir>      Filter direction: upstream | downstream | both (default: downstream)
-  --include-decorators       Include @Optional, @Self, @SkipSelf, @Host flags in output
-  --out <file>               Output file path (prints to stdout if omitted)
-  -v, --verbose              Show detailed parsing and resolution information
-  -h, --help                 Display help information
 ```
 
-### Option Details
-
-- **`filePaths` (positional)**: Optional positional arguments that act as a shortcut for `--files`,
-  allowing you to target specific files or directories without the flag; omit to scan the full project
-- **`--project`**: Specifies the TypeScript configuration file to use for project analysis (required
-  when your tsconfig lives outside `./tsconfig.json`)
-- **`--files`**: Restrict analysis to one or more specific TypeScript files (relative paths supported)
-  and merges with positional `filePaths` when both are provided; useful when targeting a subset of your
-  project similar to ESLint CLI usage
-- **`--format`**: Choose between JSON (structured data) or Mermaid (visual diagram)
-- **`--entry`**: Filter the graph to show only dependencies related to specified symbols (supports multiple entries)
-- **`--direction`**:
-  - `downstream` (default): Show what the entry depends on
-  - `upstream`: Show what depends on the entry
-  - `both`: Show both upstream and downstream dependencies
-- **`--include-decorators`**: Add parameter decorator information to edge flags
-- **`--out`**: Save output to a file instead of stdout
-- **`--verbose`**: Enable detailed logging including timing metrics, memory usage, and type resolution details
+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`.
+`-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.
+`--out <file>` | stdout | Write output to a file.
+`-v, --verbose` | `false` | Show detailed parsing and resolution logs.
+`-h, --help` | `false` | Display CLI help.
 
 ## Output Formats
 
@@ -107,21 +90,26 @@ Options:
   "nodes": [
     { "id": "AppComponent", "kind": "component" },
     { "id": "UserService", "kind": "service" },
-    { "id": "AuthService", "kind": "service" }
+    { "id": "AuthService", "kind": "service" },
+    { "id": "Logger", "kind": "service" }
   ],
   "edges": [
     {
       "from": "AppComponent",
-      "to": "UserService",
-      "flags": { "optional": false }
+      "to": "UserService"
     },
     {
       "from": "UserService",
       "to": "AuthService",
-      "flags": { "optional": true, "self": false }
+      "flags": { "optional": true, "self": false, "skipSelf": false, "host": false }
+    },
+    {
+      "from": "AuthService",
+      "to": "Logger",
+      "flags": { "optional": false, "self": false, "skipSelf": false, "host": false }
     }
   ],
-  "circularDependencies": []
+  "circularDependencies": [["UserService", "AuthService", "UserService"]]
 }
 ```
 
@@ -145,66 +133,18 @@ flowchart LR
   UserService --> AuthService
 ```
 
-Mermaid diagrams can be:
-- Rendered in GitHub/GitLab markdown
-- Viewed in the [Mermaid Live Editor](https://mermaid.live/)
-- Embedded in documentation sites
-- Converted to images using CLI tools
-
-## Use Cases
-
-### 1. Test Planning
-Quickly identify all dependencies of a component to plan test mocks:
-```bash
-ng-di-graph --project ./tsconfig.json --entry MyComponent --format json
-```
-
-### 2. Impact Analysis
-Find all consumers of a service before making breaking changes:
-```bash
-ng-di-graph --project ./tsconfig.json --entry UserService --direction upstream
-```
-
-### 3. Documentation
-Generate visual dependency diagrams for README or design docs:
-```bash
-ng-di-graph --project ./tsconfig.json --format mermaid --out docs/architecture.mmd
-```
-
-### 4. Circular Dependency Detection
-Identify circular dependencies in your DI graph:
-```bash
-ng-di-graph --project ./tsconfig.json --verbose
-# Check the "circularDependencies" array in output
-```
+Mermaid diagrams can be rendered in GitHub/GitLab markdown, viewed in the [Mermaid Live Editor](https://mermaid.live/), or converted to images with CLI tools.
 
-### 5. Debugging Type Issues
-Investigate type resolution problems with verbose logging:
-```bash
-ng-di-graph --project ./tsconfig.json --verbose
-# Shows detailed type resolution and warnings
-```
+## Use cases
+- Test planning: surface dependencies to decide what to mock.
+- Impact analysis: list consumers before changing a service.
+- Documentation: add Mermaid diagrams to READMEs or architecture docs.
 
 ## Release workflow
+Releases are automated via Release Please; tag pushes run lint → typecheck → test → build → pack → publish. Maintainer runbook: see `docs/release/ci-publish.md`.
 
-- PR-driven releases via Release Please; release PR merges tag `vX.Y.Z`.
-- Tag pushes trigger publish workflow: lint → typecheck → test → build → pack → publish with provenance.
-- Maintainer runbook: see docs/release/ci-publish.md.
-
-## Error Handling
-
-The tool provides graceful error handling:
-
-- **File Parsing Failures** - Skips unparseable files and continues processing
-- **Type Resolution Issues** - Logs warnings for `any`/`unknown` types
-- **Missing tsconfig.json** - Clear error message with suggestion
-- **Invalid CLI Arguments** - Help message with usage examples
-- **Circular Dependencies** - Detected and reported without blocking analysis
-- **Memory Constraints** - Suggestions for chunking large codebases
-
-Exit codes:
-- `0` - Success
-- `1` - Fatal error (invalid config, parsing failure, etc.)
+## Error handling
+The CLI reports clear failures and continues past unparseable files; rerun with `--verbose` for detailed logs.
 
 ## Contributing
 
@@ -213,9 +153,3 @@ Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md)
 ## License
 
 MIT License - See [LICENSE](LICENSE) file for details
-
-## Version
-
-Current version: **0.1.0**
-
-All core features are complete and production-ready.

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);
@@ -402,11 +402,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 +415,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);
@@ -1974,6 +1974,176 @@ var MermaidFormatter = class {
 	}
 };
 
+//#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,22 +2166,19 @@ 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: 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.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",
@@ -2020,7 +2187,6 @@ program.action(async (filePaths = [], options) => {
 		if (options.format && !["json", "mermaid"].includes(options.format)) throw ErrorHandler.createError(`Invalid format: ${options.format}. Must be '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 +2197,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", {