@angular-modernizer/api 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christian Weiss<CWOIDA>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,507 @@
+# @angular-modernizer/api
+
+Analysis and transformation utilities used by plugins. Plugins must use this API and never manipulate the AST directly.
+
+## Overview
+
+The `@angular-modernizer/api` package provides high-level, reusable tools that plugins use to analyze and transform Angular codebases. This package contains the core business logic that powers the entire platform.
+
+## Architecture
+
+The API follows the "API-Driven Plugin" pattern:
+
+```typescript
+// Incorrect: plugin implements low-level AST logic
+class BadPlugin {
+  analyze(sourceFile: SourceFile) {
+    // 100 lines of AST manipulation code
+  }
+}
+
+// Correct: plugin uses API tools
+class GoodPlugin {
+  analyze(context: AnalysisContext) {
+    const usages = context.api.analysis.templateAnalyzer.analyze(template);
+    const deps = context.api.analysis.dependencyAnalyzer.analyzeDependencies(sourceFile);
+    // Focus on business logic, not implementation details
+  }
+}
+```
+
+## Core Components
+
+### PublicApi
+
+The `PublicApi` is the single entry point for all analysis and transformation tools:
+
+```typescript
+import { createPublicApi } from '@angular-modernizer/api';
+
+const api = createPublicApi();
+
+const templateUsages = api.analysis.templateAnalyzer.analyze(template);
+const dependencies = api.analysis.dependencyAnalyzer.analyzeDependencies(sourceFile);
+const imports = api.transformation.importManager.addImport(
+  sourceFile,
+  'Inject',
+  '@angular/core',
+);
+```
+
+### Analysis Tools
+
+#### TemplateAnalyzer
+
+Purpose: extract all template usages.
+
+```typescript
+interface TemplateAnalyzer {
+  analyze(template: string): TemplateUsage[];
+}
+
+interface TemplateUsage {
+  element: string;
+  selector: string;
+  attributes: string[];
+  inputs: string[];
+  outputs: string[];
+  content: string;
+}
+```
+
+Design: extracts all usages from templates without filtering or heuristics. Provides raw data for downstream decision-making.
+
+Example:
+
+```typescript
+const api = createPublicApi();
+const usages = api.analysis.templateAnalyzer.analyze(`
+  <app-user [user]="currentUser" (save)="onSave()">
+    <div *ngIf="loading">Loading...</div>
+    <input [(ngModel)]="name">
+  </app-user>
+`);
+
+// Result:
+// - app-user component with [user] input and (save) output
+// - *ngIf directive usage
+// - ngModel directive usage
+```
+
+#### DependencyAnalyzer
+
+Purpose: build comprehensive symbol maps.
+
+```typescript
+interface DependencyAnalyzer {
+  analyzeDependencies(sourceFile: SourceFile): DependencyMap;
+  findNgModules(project: Project): NgModuleInfo[];
+  resolveSelector(selector: string, project: Project): SymbolInfo | null;
+}
+
+interface DependencyMap {
+  components: Map<string, ComponentInfo>;
+  directives: Map<string, DirectiveInfo>;
+  pipes: Map<string, PipeInfo>;
+  modules: Map<string, NgModuleInfo>;
+}
+
+interface ComponentInfo {
+  className: string;
+  selector: string;
+  inputs: PropertyInfo[];
+  outputs: PropertyInfo[];
+  module?: string;
+}
+
+interface PropertyInfo {
+  name: string;
+  alias?: string;
+  type?: string;
+}
+```
+
+Key features:
+- Maps selectors to class names
+- Handles aliased @Input/@Output bindings
+- Resolves module declarations
+- Builds complete dependency graphs
+
+Example:
+
+```typescript
+const api = createPublicApi();
+const sourceFile = project.addSourceFileAtPath('user.module.ts');
+const dependencies = api.analysis.dependencyAnalyzer.analyzeDependencies(sourceFile);
+
+// Result: complete symbol map
+// - UserComponent: selector 'app-user', inputs: ['user'], outputs: ['save']
+// - UserModule: declarations: [UserComponent], exports: [UserComponent]
+```
+
+Also supports advanced analysis:
+
+```typescript
+const analyzer = new DependencyAnalyzer();
+
+// Build comprehensive symbol map
+const symbolMap = analyzer.buildSymbolMap(moduleFile, project);
+console.log(symbolMap.available); // All available symbols in scope
+
+// Detect circular dependencies
+const cycles = analyzer.detectCircularDependencies(project);
+
+// Get transitive dependencies
+const transitiveDeps = analyzer.getTransitiveDependencies(sourceFile, project);
+
+// Extract symbol information
+const symbolInfo = analyzer.extractSymbolInfo(sourceFile, 'MyComponent');
+console.log(symbolInfo?.inputs);  // ['input1', 'customAlias']
+console.log(symbolInfo?.outputs); // ['output1']
+```
+
+#### ComplexityMetricsCalculator
+
+Purpose: calculate code complexity and maintainability metrics.
+
+```typescript
+interface ComplexityMetricsCalculator {
+  calculateForFile(sourceFile: SourceFile): FileMetrics;
+  calculateForProject(project: Project): ProjectMetrics;
+}
+
+interface FileMetrics {
+  linesOfCode: number;
+  cyclomaticComplexity: number;
+  maintainabilityIndex: number;
+  halsteadMetrics: HalsteadMetrics;
+  cognitiveComplexity: number;
+}
+
+interface ProjectMetrics {
+  totalFiles: number;
+  averageComplexity: number;
+  complexityDistribution: ComplexityDistribution;
+  maintainabilityScore: number;
+}
+```
+
+Example:
+
+```typescript
+const calculator = new ComplexityMetricsCalculator();
+
+const score = calculator.calculateOverallComplexity(componentClass);
+const cyclomatic = calculator.calculateCyclomaticComplexity(method);
+const loc = calculator.calculateLOC(sourceFile);
+const angularMetrics = calculator.calculateAngularSpecificMetrics(classDecl);
+console.log(angularMetrics.lifecycleHooks);
+console.log(angularMetrics.inputs);
+console.log(angularMetrics.outputs);
+```
+
+### Transformation Tools
+
+#### ImportManager
+
+Purpose: safely manage TypeScript import statements.
+
+```typescript
+interface ImportManager {
+  addImport(sourceFile: SourceFile, symbol: string, module: string): boolean;
+  removeImport(sourceFile: SourceFile, symbol: string): boolean;
+  organizeImports(sourceFile: SourceFile): void;
+  hasImport(sourceFile: SourceFile, symbol: string, module?: string): boolean;
+}
+```
+
+Key features:
+- Prevents duplicate imports
+- Handles default vs named imports
+- Organizes import statements
+- Resolves import conflicts
+
+Example:
+
+```typescript
+const importManager = new ImportManager();
+
+importManager.addNamedImport(sourceFile, 'OnInit', '@angular/core');
+importManager.addNamedImport(sourceFile, 'Directive', '@angular/core', 'NgDirective');
+
+importManager.removeNamedImport(sourceFile, 'OnInit', '@angular/core');
+
+const hasImport = importManager.hasImport(sourceFile, 'Component', '@angular/core');
+const alias = importManager.getImportAlias(sourceFile, 'Component', '@angular/core');
+
+importManager.mergeImports(sourceFile);
+importManager.cleanupEmptyImports(sourceFile);
+```
+
+## Performance Characteristics
+
+- ComplexityMetricsCalculator: <100ms for large components
+- ImportManager: <50ms for 20+ import operations
+- DependencyAnalyzer: <200ms for comprehensive analysis
+- Memory usage: <50MB increase during repeated operations
+
+## Usage Examples
+
+### Standalone Migration Workflow
+
+```typescript
+import { createPublicApi } from '@angular-modernizer/api';
+import { ContextFactory } from '@angular-modernizer/plugin-system';
+
+const api = createPublicApi();
+
+// 1. Analyze template dependencies
+const template = `<div *ngIf="loading" [user]="user" (save)="onSave()"></div>`;
+const templateUsages = api.analysis.templateAnalyzer.analyze(template);
+
+// 2. Get component dependencies
+const sourceFile = project.addSourceFileAtPath('user.component.ts');
+const dependencies = api.analysis.dependencyAnalyzer.analyzeDependencies(sourceFile);
+
+// 3. Transform component to standalone
+const context = ContextFactory.createTransformContext({
+  sourceFile,
+  project,
+  api,
+  config: {},
+});
+
+// The plugin uses the API to:
+// - Add standalone: true to @Component decorator
+// - Build imports array from templateUsages + dependencies
+// - Add necessary import statements
+```
+
+### SOLID Principle Analysis
+
+```typescript
+const api = createPublicApi();
+
+function findDirectInstantiations(sourceFile: SourceFile): Violation[] {
+  const violations: Violation[] = [];
+
+  sourceFile.forEachDescendant((node) => {
+    if (ts.isNewExpression(node)) {
+      const className = node.expression.getText();
+
+      if (className.endsWith('Service')) {
+        violations.push({
+          type: 'direct-instantiation',
+          location: getLocation(node),
+          message: `Direct instantiation of ${className} violates Dependency Inversion Principle`,
+          suggestion: 'Use dependency injection instead',
+        });
+      }
+    }
+  });
+
+  return violations;
+}
+```
+
+### Complexity Analysis
+
+```typescript
+const api = createPublicApi();
+
+const projectMetrics = api.analysis.complexityMetricsCalculator.calculateForProject(project);
+
+const complexFiles = projectMetrics.fileMetrics.filter(
+  (metrics) =>
+    metrics.cyclomaticComplexity > 10 || metrics.maintainabilityIndex < 50,
+);
+
+complexFiles.forEach((file) => {
+  console.log(`${file.filePath}:`);
+  console.log(`  - Complexity: ${file.cyclomaticComplexity}`);
+  console.log(`  - Maintainability: ${file.maintainabilityIndex}`);
+  console.log('  -> Consider breaking down into smaller functions');
+});
+```
+
+## API Design Principles
+
+### Stateless and Pure
+
+All API methods are stateless and side-effect free:
+
+```typescript
+const result1 = api.analysis.templateAnalyzer.analyze(template);
+const result2 = api.analysis.templateAnalyzer.analyze(template);
+assert.deepEqual(result1, result2); // Always true
+```
+
+### Composable
+
+Tools work together seamlessly:
+
+```typescript
+const templateUsages = api.analysis.templateAnalyzer.analyze(template);
+const dependencies = api.analysis.dependencyAnalyzer.analyzeDependencies(sourceFile);
+const complexity = api.analysis.complexityMetricsCalculator.calculateForFile(sourceFile);
+
+const transformationPlan = createTransformationPlan({
+  templateUsages,
+  dependencies,
+  complexity,
+});
+```
+
+### Error-Resilient
+
+APIs handle edge cases gracefully:
+
+```typescript
+// Handles malformed templates
+const usages = api.analysis.templateAnalyzer.analyze('<invalid html>>>');
+// Returns empty array or best-effort parsing
+
+// Handles missing files
+const dependencies = api.analysis.dependencyAnalyzer.analyzeDependencies(missingFile);
+// Returns empty map, no crash
+```
+
+### Performance-Conscious
+
+Efficient algorithms for large codebases:
+- Lazy evaluation where possible
+- Caching of expensive operations
+- Streaming processing for large files
+- Incremental analysis support
+
+## Testing
+
+```bash
+pnpm test --filter @angular-modernizer/api
+pnpm test --filter @angular-modernizer/api --coverage
+```
+
+Test categories:
+- Unit tests: individual tool functionality
+- Integration tests: tool composition and workflows
+- Performance tests: large codebase handling
+- Edge case tests: error conditions and malformed input
+
+Testing patterns:
+
+```typescript
+import { createPublicApi } from '@angular-modernizer/api';
+import { Project } from 'ts-morph';
+
+describe('TemplateAnalyzer', () => {
+  let api: PublicApi;
+  let project: Project;
+
+  beforeEach(() => {
+    api = createPublicApi();
+    project = new Project();
+  });
+
+  it('should extract component usages', () => {
+    const template = '<app-user [user]="user"></app-user>';
+    const usages = api.analysis.templateAnalyzer.analyze(template);
+
+    expect(usages).toContainEqual({
+      element: 'app-user',
+      selector: 'app-user',
+      inputs: ['user'],
+      attributes: [],
+      outputs: [],
+      content: '',
+    });
+  });
+});
+```
+
+## Package Structure
+
+```
+packages/api/
+├── src/
+│   ├── analysis/
+│   │   ├── template-analyzer.ts
+│   │   ├── dependency-analyzer.ts
+│   │   └── complexity-metrics-calculator.ts
+│   ├── transformation/
+│   │   └── import-manager.ts
+│   ├── index.ts
+│   └── types.ts
+├── __tests__/
+│   ├── analysis/
+│   │   ├── template-analyzer.test.ts
+│   │   ├── dependency-analyzer.test.ts
+│   │   └── complexity-metrics-calculator.test.ts
+│   ├── transformation/
+│   │   └── import-manager.test.ts
+│   └── integration.test.ts
+├── package.json
+├── tsconfig.json
+├── jest.config.js
+└── README.md
+```
+
+## Dependencies
+
+- **ts-morph:** TypeScript AST manipulation
+- **typescript:** TypeScript compiler API
+- **@angular-modernizer/core:** Kernel and infrastructure (peer dependency)
+
+## Contributing
+
+When adding new API tools:
+
+1. Follow the PublicApi pattern - add to the unified interface
+2. Write comprehensive tests (unit, integration, and edge cases)
+3. Document with examples and update this README
+4. Maintain backward compatibility
+5. Optimize for large codebases
+
+### Adding a New Analysis Tool
+
+```typescript
+// 1. Create the tool interface
+export interface NewAnalyzer {
+  analyze(input: InputType): OutputType;
+}
+
+// 2. Implement the tool
+export class NewAnalyzerImpl implements NewAnalyzer {
+  analyze(input: InputType): OutputType {
+    // Implementation
+  }
+}
+
+// 3. Add to PublicApi interface
+interface PublicApi {
+  analysis: {
+    templateAnalyzer: TemplateAnalyzer;
+    dependencyAnalyzer: DependencyAnalyzer;
+    newAnalyzer: NewAnalyzer;
+  };
+}
+
+// 4. Update factory function
+export function createPublicApi(): PublicApi {
+  return {
+    analysis: {
+      templateAnalyzer: new TemplateAnalyzerImpl(),
+      dependencyAnalyzer: new DependencyAnalyzerImpl(),
+      newAnalyzer: new NewAnalyzerImpl(),
+    },
+  };
+}
+```
+
+## See Also
+
+- [packages/core/README.md](../core/README.md) - Kernel infrastructure
+- [packages/plugin-system/README.md](../plugin-system/README.md) - Plugin contracts
+
+## License
+
+MIT License - See LICENSE file for details

package/dist/analysis/complexity-metrics-calculator.d.ts

@@ -0,0 +1,99 @@
+/**
+ * @angular-modernizer/api - Complexity Metrics Calculator
+ *
+ * Calculates code complexity and maintainability metrics for Angular applications.
+ * Provides quantitative measures to prioritize refactoring efforts.
+ */
+import type { SourceFile, ClassDeclaration } from 'ts-morph';
+/**
+ * Angular-specific metrics for components and directives.
+ */
+export interface AngularMetrics {
+    /**
+     * Number of lifecycle hooks (ngOnInit, ngOnDestroy, etc.).
+     */
+    lifecycleHooks: number;
+    /**
+     * Number of @Input properties.
+     */
+    inputs: number;
+    /**
+     * Number of @Output properties.
+     */
+    outputs: number;
+    /**
+     * Number of Angular decorators (@Component, @Directive, etc.).
+     */
+    decorators: number;
+}
+/**
+ * Complexity Metrics Calculator - analyzes code complexity and maintainability.
+ */
+export declare class ComplexityMetricsCalculator {
+    /**
+     * Calculate overall complexity score for a class (0-100 scale).
+     * Custom weighted heuristic combining established metrics (McCabe's Cyclomatic Complexity,
+     * LOC, method count from CK metrics) with Angular-specific indicators.
+     *
+     * Combines multiple metrics:
+     * - Cyclomatic complexity
+     * - Lines of code
+     * - Method count
+     * - Angular-specific complexity
+     *
+     * @param classDecl - The class declaration to analyze
+     * @returns Complexity score (0-100)
+     */
+    calculateOverallComplexity(classDecl: ClassDeclaration): number;
+    /**
+     * Calculate cyclomatic complexity for a class.
+     *
+     * Measures the number of linearly independent paths through the code.
+     * Higher values indicate more complex control flow.
+     *
+     * @param classDecl - The class declaration
+     * @returns Cyclomatic complexity score
+     */
+    calculateCyclomaticComplexity(classDecl: ClassDeclaration): number;
+    /**
+     * Calculate cyclomatic complexity for a single method.
+     * Implements McCabe's algorithm by counting decision points:
+     * if/else if, loops, switch cases, ternary operators, logical operators.
+     */
+    private calculateMethodComplexity;
+    /**
+     * Calculate lines of code for a source file.
+     *
+     * Excludes comments and whitespace for meaningful LOC count.
+     *
+     * @param sourceFile - The source file
+     * @returns Number of lines of code
+     */
+    calculateLOC(sourceFile: SourceFile): number;
+    /**
+     * Calculate the number of methods in a class.
+     *
+     * @param classDecl - The class declaration
+     * @returns Number of methods
+     */
+    calculateMethodCount(classDecl: ClassDeclaration): number;
+    /**
+     * Calculate dependency count for a source file.
+     *
+     * Counts unique external dependencies (imports from node_modules).
+     *
+     * @param sourceFile - The source file
+     * @returns Number of unique dependencies
+     */
+    calculateDependencyCount(sourceFile: SourceFile): number;
+    /**
+     * Calculate Angular-specific metrics for a class.
+     *
+     * Analyzes Angular decorators and patterns.
+     *
+     * @param classDecl - The class declaration
+     * @returns Angular-specific metrics
+     */
+    calculateAngularSpecificMetrics(classDecl: ClassDeclaration): AngularMetrics;
+}
+//# sourceMappingURL=complexity-metrics-calculator.d.ts.map

package/dist/analysis/complexity-metrics-calculator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"complexity-metrics-calculator.d.ts","sourceRoot":"","sources":["../../src/analysis/complexity-metrics-calculator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAqB,MAAM,UAAU,CAAC;AAEhF;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,cAAc,EAAE,MAAM,CAAC;IAEvB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,qBAAa,2BAA2B;IACtC;;;;;;;;;;;;;OAaG;IACH,0BAA0B,CAAC,SAAS,EAAE,gBAAgB,GAAG,MAAM;IAyB/D;;;;;;;;OAQG;IACH,6BAA6B,CAAC,SAAS,EAAE,gBAAgB,GAAG,MAAM;IAWlE;;;;OAIG;IACH,OAAO,CAAC,yBAAyB;IAuBjC;;;;;;;OAOG;IACH,YAAY,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM;IAqB5C;;;;;OAKG;IACH,oBAAoB,CAAC,SAAS,EAAE,gBAAgB,GAAG,MAAM;IAIzD;;;;;;;OAOG;IACH,wBAAwB,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM;IAkBxD;;;;;;;OAOG;IACH,+BAA+B,CAAC,SAAS,EAAE,gBAAgB,GAAG,cAAc;CAsD7E"}