ng-di-graph 0.1.0

package/dist/core/parser.d.ts

@@ -0,0 +1,252 @@
+import { Project } from 'ts-morph';
+import type { CliOptions, ParsedClass, StructuredWarnings } from '../types';
+import { type Logger } from './logger';
+export declare class AngularParser {
+    private _options;
+    private _logger?;
+    private _project?;
+    private _typeResolutionCache;
+    private _circularTypeRefs;
+    private _structuredWarnings;
+    constructor(_options: CliOptions, _logger?: Logger | undefined);
+    /**
+     * Reset global warning deduplication state (useful for testing)
+     */
+    static resetWarningState(): void;
+    /**
+     * Get structured warnings for analysis (Task 3.3)
+     * Returns a copy of the structured warnings collected during parsing
+     * @returns StructuredWarnings object with categorized warnings
+     */
+    getStructuredWarnings(): StructuredWarnings;
+    /**
+     * Add structured warning to collection (Task 3.3)
+     * Includes global deduplication for both structured warnings and console output
+     * @param category Warning category
+     * @param warning Warning object
+     */
+    private addStructuredWarning;
+    /**
+     * Load TypeScript project using ts-morph
+     * Implements FR-01 with error handling from PRD Section 13
+     */
+    loadProject(): void;
+    /**
+     * Get the loaded ts-morph Project instance
+     * @returns Project instance
+     * @throws Error if project not loaded
+     */
+    getProject(): Project;
+    /**
+     * Parse decorated classes from the loaded project
+     * Auto-loads project if not already loaded
+     * @returns Promise of parsed class information
+     */
+    parseClasses(): Promise<ParsedClass[]>;
+    /**
+     * Find all classes decorated with @Injectable, @Component, or @Directive
+     * Implements FR-02: Decorated Class Collection
+     * @returns Promise<ParsedClass[]> List of decorated classes
+     */
+    findDecoratedClasses(): Promise<ParsedClass[]>;
+    /**
+     * Parse a single class declaration for Angular decorators
+     * @param classDeclaration ts-morph ClassDeclaration
+     * @returns ParsedClass if decorated with Angular decorator, null otherwise
+     */
+    private parseClassDeclaration;
+    /**
+     * Find Angular decorator (@Injectable, @Component, @Directive) from list of decorators
+     * @param decorators Array of decorators from ts-morph
+     * @returns Angular decorator if found, null otherwise
+     */
+    private findAngularDecorator;
+    /**
+     * Extract decorator name from ts-morph Decorator
+     * Handles various import patterns and aliases
+     * @param decorator ts-morph Decorator
+     * @returns Decorator name string
+     */
+    private getDecoratorName;
+    /**
+     * Resolve decorator alias from import declarations with basic caching
+     * @param sourceFile Source file containing the decorator
+     * @param decoratorName Raw decorator name from AST
+     * @returns Original decorator name if alias found, null otherwise
+     */
+    private resolveDecoratorAlias;
+    /**
+     * Determine NodeKind from Angular decorator
+     * @param decorator Angular decorator
+     * @returns NodeKind mapping
+     */
+    private determineNodeKind;
+    /**
+     * Detect and warn about anonymous class expressions
+     * Handles patterns like: const X = Decorator()(class { ... })
+     * @param sourceFile Source file to analyze
+     */
+    private detectAnonymousClasses;
+    /**
+     * Extract constructor dependencies from a class declaration
+     * Implements FR-03: Constructor parameter analysis
+     * Implements TDD Cycle 2.1: inject() function detection
+     * @param classDeclaration ts-morph ClassDeclaration
+     * @returns Array of parsed dependencies
+     */
+    private extractConstructorDependencies;
+    /**
+     * Check if type reference is circular (Task 3.3)
+     * @param typeText Type text to check
+     * @param typeNode TypeNode for context
+     * @returns True if circular reference detected
+     */
+    private isCircularTypeReference;
+    /**
+     * Check if type is generic (Task 3.3)
+     * @param typeText Type text to check
+     * @returns True if generic type
+     */
+    private isGenericType;
+    /**
+     * Handle generic types (Task 3.3)
+     * @param typeText Generic type text
+     * @param filePath File path for context
+     * @param lineNumber Line number
+     * @param columnNumber Column number
+     * @returns Token string or null
+     */
+    private handleGenericType;
+    /**
+     * Check if type is union type (Task 3.3)
+     * @param typeText Type text to check
+     * @returns True if union type
+     */
+    private isUnionType;
+    /**
+     * Handle union types (Task 3.3)
+     * @param typeText Union type text
+     * @param filePath File path for context
+     * @param lineNumber Line number
+     * @param columnNumber Column number
+     * @returns Null (union types are skipped)
+     */
+    private handleUnionType;
+    /**
+     * Check if type can be resolved through imports (Task 3.3)
+     * Handles module-scoped types (e.g., MyModule.ScopedService)
+     * @param typeNode TypeNode to check
+     * @returns True if type can be resolved
+     */
+    private canResolveType;
+    /**
+     * Enhanced type token extraction with advanced analysis (Task 3.3)
+     * @param typeNode TypeNode to extract token from
+     * @param filePath File path for context
+     * @param lineNumber Line number
+     * @param columnNumber Column number
+     * @returns Token string or null
+     */
+    private extractTypeTokenEnhanced;
+    /**
+     * Resolve inferred types with enhanced validation (Task 3.3)
+     * @param type Type object from ts-morph
+     * @param typeText Type text representation
+     * @param param Parameter declaration for context
+     * @param filePath File path for warnings
+     * @param lineNumber Line number for warnings
+     * @param columnNumber Column number for warnings
+     * @returns Resolved token or null
+     */
+    private resolveInferredTypeEnhanced;
+    /**
+     * Parse a single constructor parameter to extract dependency token
+     * Implements FR-03 token resolution priority: @Inject > type annotation > inferred type
+     * Implements FR-04 parameter decorator handling
+     * @param param ts-morph ParameterDeclaration
+     * @returns ParsedDependency if valid dependency, null if should be skipped
+     */
+    private parseConstructorParameter;
+    /**
+     * Extract token from @Inject decorator
+     * @param decorator @Inject decorator
+     * @returns Token string or null
+     */
+    private extractInjectToken;
+    /**
+     * Check if type should be skipped (any/unknown types)
+     * Implements FR-09: Skip dependencies whose type resolves to any/unknown
+     * @param typeText Type text to check
+     * @returns True if should be skipped
+     */
+    private shouldSkipType;
+    /**
+     * Check if type is primitive and should be skipped
+     * @param typeText Type text to check
+     * @returns True if primitive type
+     */
+    private isPrimitiveType;
+    /**
+     * Extract parameter decorators from constructor parameter
+     * Implements FR-04: Parameter decorator handling (@Optional, @Self, @SkipSelf, @Host)
+     * Optimized for performance with early returns and minimal object allocation
+     * @param param ts-morph ParameterDeclaration
+     * @returns EdgeFlags object with detected decorators
+     */
+    private extractParameterDecorators;
+    /**
+     * Extract dependencies from inject() function calls in class properties
+     * Implements TDD Cycle 2.1: Modern Angular inject() pattern detection
+     * @param classDeclaration ts-morph ClassDeclaration
+     * @returns Array of parsed dependencies from inject() calls
+     */
+    private extractInjectFunctionDependencies;
+    /**
+     * Parse a property declaration for inject() function calls
+     * @param property ts-morph PropertyDeclaration
+     * @returns ParsedDependency if inject() call found, null otherwise
+     */
+    private parseInjectProperty;
+    /**
+     * Parse options object from inject() function call
+     * @param optionsArg Options argument from inject() call
+     * @returns EdgeFlags object with parsed options
+     */
+    private parseInjectOptions;
+    /**
+     * Analyze parameter decorators for TDD Cycle 1.1
+     * Legacy parameter decorator detection method for @Optional, @Self, @SkipSelf, @Host
+     * @param parameter ParameterDeclaration to analyze
+     * @param includeDecorators Whether to include decorators in analysis
+     * @returns EdgeFlags object with detected decorators
+     */
+    private analyzeParameterDecorators;
+    /**
+     * Check if inject() function is imported from @angular/core
+     * Prevents false positives from custom inject() functions
+     * @param sourceFile Source file to check imports
+     * @returns True if Angular inject is imported
+     */
+    private isAngularInjectImported;
+    /**
+     * Analyze inject() function call expression to extract token and options
+     * Implements TDD Cycle 2.1 - Modern Angular inject() pattern support
+     * @param expression Expression to analyze (should be a CallExpression)
+     * @returns ParameterAnalysisResult or null if not a valid inject() call
+     */
+    private analyzeInjectCall;
+    /**
+     * Collect verbose statistics for decorator analysis
+     * @param param Parameter declaration being analyzed
+     * @param dependency Parsed dependency result
+     * @param verboseStats Statistics object to update
+     */
+    private collectVerboseStats;
+    /**
+     * Output comprehensive verbose analysis summary
+     * @param dependencies All parsed dependencies
+     * @param verboseStats Collected statistics
+     * @param classDeclaration Class being analyzed
+     */
+    private outputVerboseAnalysis;
+}

package/dist/formatters/json-formatter.d.ts

@@ -0,0 +1,24 @@
+import { type Logger } from '../core/logger';
+import type { Graph } from '../types';
+/**
+ * JSON formatter for dependency graph output
+ * Produces pretty-printed JSON with 2-space indentation
+ */
+export declare class JsonFormatter {
+    /**
+     * Logger instance for verbose output (optional)
+     * @private
+     */
+    private readonly _logger?;
+    /**
+     * Create a new JSON formatter
+     * @param logger Optional Logger instance for verbose mode
+     */
+    constructor(logger?: Logger);
+    /**
+     * Format a dependency graph as JSON
+     * @param graph The dependency graph to format
+     * @returns Pretty-printed JSON string
+     */
+    format(graph: Graph): string;
+}

package/dist/formatters/mermaid-formatter.d.ts

@@ -0,0 +1,31 @@
+import { type Logger } from '../core/logger';
+import type { Graph } from '../types';
+/**
+ * Mermaid formatter for dependency graph output
+ * Produces flowchart LR syntax compatible with Mermaid Live Editor
+ */
+export declare class MermaidFormatter {
+    /**
+     * Logger instance for verbose output (optional)
+     * @private
+     */
+    private readonly _logger?;
+    /**
+     * Create a new Mermaid formatter
+     * @param logger Optional Logger instance for verbose mode
+     */
+    constructor(logger?: Logger);
+    /**
+     * Format a dependency graph as Mermaid flowchart
+     * @param graph The dependency graph to format
+     * @returns Mermaid flowchart string
+     */
+    format(graph: Graph): string;
+    /**
+     * Sanitize node names for Mermaid compatibility
+     * Replaces special characters that break Mermaid syntax
+     * @param nodeName The original node name
+     * @returns Sanitized node name
+     */
+    private sanitizeNodeName;
+}

package/dist/tests/helpers/test-utils.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Common Test Utilities
+ * Provides reusable helper functions for test setup and mocking
+ */
+import type { LogCategory, LogContext, Logger, LoggingStats } from '../../core/logger';
+import { AngularParser } from '../../core/parser';
+import type { CliOptions, Edge, Graph, Node } from '../../types';
+/**
+ * Default test fixtures directory path
+ */
+export declare const TEST_FIXTURES_DIR = "./src/tests/fixtures";
+export declare const TEST_TSCONFIG = "./src/tests/fixtures/tsconfig.json";
+/**
+ * Create default CliOptions for testing
+ * @param overrides - Partial options to override defaults
+ * @returns Complete CliOptions object
+ */
+export declare function createTestCliOptions(overrides?: Partial<CliOptions>): CliOptions;
+/**
+ * Create and initialize an AngularParser for testing
+ * @param optionsOverrides - Optional CliOptions overrides
+ * @param loadProject - Whether to automatically load the project (default: true)
+ * @returns Initialized AngularParser instance
+ */
+export declare function createTestParser(optionsOverrides?: Partial<CliOptions>, loadProject?: boolean): AngularParser;
+/**
+ * Create a Logger instance for testing
+ * @param verbose - Whether to enable verbose mode (default: false)
+ * @returns Logger instance or undefined if verbose is false
+ */
+export declare function createTestLogger(verbose?: boolean): Logger | undefined;
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Lightweight stub logger that captures log events without touching the console.
+ * Enables deterministic assertions in tests that need to observe instrumentation.
+ */
+export declare class StubLogger implements Logger {
+    readonly logs: Array<{
+        level: LogLevel;
+        category: LogCategory;
+        message: string;
+        context?: LogContext;
+    }>;
+    private readonly _timers;
+    private readonly _completedTimers;
+    private readonly _stats;
+    debug(category: LogCategory, message: string, context?: LogContext): void;
+    info(category: LogCategory, message: string, context?: LogContext): void;
+    warn(category: LogCategory, message: string, context?: LogContext): void;
+    error(category: LogCategory, message: string, context?: LogContext): void;
+    time(label: string): void;
+    timeEnd(label: string): number;
+    getStats(): LoggingStats;
+    getCompletedTimerLabels(): string[];
+    getTimerDuration(label: string): number | undefined;
+    private _record;
+}
+/**
+ * Factory for stub logger instances so tests can avoid importing the class directly.
+ */
+export declare function createStubLogger(): StubLogger;
+/**
+ * Create a simple mock graph for testing
+ * @param options - Optional graph customization
+ * @returns Graph object
+ */
+export declare function createMockGraph(options?: {
+    nodes?: Node[];
+    edges?: Edge[];
+    circularDependencies?: string[][];
+}): Graph;
+/**
+ * Create a minimal empty graph
+ * @returns Empty graph object
+ */
+export declare function createEmptyGraph(): Graph;
+/**
+ * Mock console methods for testing CLI output
+ * @returns Object with mocked console methods and restore function
+ */
+export declare function mockConsole(): {
+    log: {
+        calls: () => string[];
+        mock: typeof console.log;
+    };
+    error: {
+        calls: () => string[];
+        mock: typeof console.error;
+    };
+    warn: {
+        calls: () => string[];
+        mock: typeof console.warn;
+    };
+    restore: () => void;
+};
+/**
+ * Wait for async operations to complete
+ * @param ms - Milliseconds to wait (default: 0)
+ * @returns Promise that resolves after specified time
+ */
+export declare function wait(ms?: number): Promise<void>;
+/**
+ * Reset warning state for parser tests
+ * Ensures clean test isolation
+ */
+export declare function resetParserState(): void;
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Core TypeScript interfaces for ng-di-graph CLI tool
+ * Based on PRD requirements in @docs/prd/mvp-requirements.md
+ */
+export type NodeKind = 'service' | 'component' | 'directive' | 'unknown';
+export interface Node {
+    id: string;
+    kind: NodeKind;
+}
+export interface EdgeFlags {
+    optional?: boolean;
+    self?: boolean;
+    skipSelf?: boolean;
+    host?: boolean;
+}
+export interface Edge {
+    from: string;
+    to: string;
+    flags?: EdgeFlags;
+    isCircular?: boolean;
+}
+export interface Graph {
+    nodes: Node[];
+    edges: Edge[];
+    circularDependencies: string[][];
+}
+export interface CliOptions {
+    project: string;
+    format: 'json' | 'mermaid';
+    entry?: string[];
+    direction: 'upstream' | 'downstream' | 'both';
+    includeDecorators: boolean;
+    out?: string;
+    verbose: boolean;
+}
+export interface ParsedClass {
+    name: string;
+    kind: NodeKind;
+    filePath: string;
+    dependencies: ParsedDependency[];
+}
+export interface ParsedDependency {
+    token: string;
+    flags?: EdgeFlags;
+    parameterName: string;
+}
+export interface ParameterAnalysisResult {
+    token: string;
+    flags: EdgeFlags;
+    source: 'decorator' | 'inject' | 'type';
+}
+export interface ParserError extends Error {
+    code: 'TSCONFIG_NOT_FOUND' | 'TSCONFIG_INVALID' | 'PROJECT_LOAD_FAILED' | 'COMPILATION_ERROR';
+    filePath?: string;
+}
+export type { CliError, ErrorCode, ExitCodes } from '../core/error-handler';
+export interface VerboseStats {
+    decoratorCounts: {
+        optional: number;
+        self: number;
+        skipSelf: number;
+        host: number;
+    };
+    skippedDecorators: Array<{
+        name: string;
+        reason: string;
+    }>;
+    parametersWithDecorators: number;
+    parametersWithoutDecorators: number;
+    legacyDecoratorsUsed: number;
+    injectPatternsUsed: number;
+    totalProcessingTime: number;
+    totalParameters: number;
+}
+/**
+ * Enhanced Type Validation - Task 3.3
+ * Structured warning system for comprehensive type analysis
+ */
+export interface Warning {
+    type: string;
+    message: string;
+    file: string;
+    line?: number;
+    column?: number;
+    suggestion?: string;
+    severity: 'warning' | 'error' | 'info';
+}
+export interface StructuredWarnings {
+    categories: {
+        typeResolution: Warning[];
+        skippedTypes: Warning[];
+        unresolvedImports: Warning[];
+        circularReferences: Warning[];
+        performance: Warning[];
+    };
+    totalCount: number;
+}
+export interface TypeValidationResult {
+    isValid: boolean;
+    token: string | null;
+    warnings: Warning[];
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "ng-di-graph",
+  "version": "0.1.0",
+  "description": "Angular DI dependency graph CLI tool",
+  "main": "dist/cli/index.cjs",
+  "bin": {
+    "ng-di-graph": "dist/cli/index.cjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "tsx src/cli/index.ts",
+    "dev:node": "tsx src/cli/index.ts",
+    "build:bundle": "tsdown --config tsdown.config.ts",
+    "build:types": "tsc --emitDeclarationOnly --outDir dist",
+    "build": "npm run build:bundle && npm run build:types",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:coverage": "vitest run --coverage",
+    "lint": "biome check src",
+    "lint:fix": "biome check --write src",
+    "format": "biome format src --write",
+    "format:check": "biome format src",
+    "check": "npm run lint && npm run typecheck",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "angular",
+    "dependency-injection",
+    "typescript",
+    "cli",
+    "graph"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.7",
+    "@types/node": "^24.10.1",
+    "@vitest/coverage-v8": "^4.0.13",
+    "rimraf": "^6.1.2",
+    "tsdown": "^0.16.6",
+    "tsx": "^4.8.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.10"
+  },
+  "dependencies": {
+    "commander": "^14.0.0",
+    "ts-morph": "^27.0.2"
+  },
+  "engines": {
+    "node": ">=20.19.0 <21.0.0 || >=22.12.0"
+  }
+}