@angular-modernizer/core

The Kernel - Infrastructure and plugin lifecycle management

Overview

The @angular-modernizer/core package provides the foundational infrastructure for the Angular Modernization Platform. It contains the Kernel, file system abstractions, plugin management system, transformation pipeline, and advanced orchestration capabilities that power the entire platform.

Architecture

The core package follows the "Infrastructure Only" principle - it provides domain-agnostic building blocks without any Angular-specific logic.

Kernel (Domain Agnostic)
  - Plugin System (Contracts)
  - File System (Abstraction)
  - TypeScript Project (ts-morph)
  - Transformation Pipeline (Coordinator + Execution Engine)
  - Orchestration System (Parallel + Incremental + Workers)
  - Cache Manager (AST Caching + Invalidation)
Copy

Core Components

Kernel

The Kernel is the central orchestrator that manages the entire platform lifecycle:

interface KernelConfig {
  tsConfigPath?: string;
  fileSystem?: FileSystemAdapter;
  projectOptions?: Partial<ProjectOptions>;
  plugins?: Plugin[];
  transformationCoordinator?: TransformationCoordinator;
  api?: unknown; // defaults to createPublicApi(project) when plugins are set
  cacheConfig?: Partial<CacheConfig>;
  resourceLimits?: ResourceLimits;
  enableParallelExecution?: boolean; // default: true
}

class Kernel {
  constructor(config?: KernelConfig); // All parameters optional

  async initialize(): Promise<void>;
  getProject(): Project;
  getFileSystem(): FileSystemAdapter;
  getCacheManager(): CacheManager | undefined;
  getBuildValidator(): BuildValidator;
  getPlugin(name: string): Plugin | undefined;
  getAllPlugins(): Plugin[];
  hasPlugin(name: string): boolean;
  isInitialized(): boolean;
  getConfig(): Readonly<KernelConfig>;
  getProjectRoot(): string; // safe before initialize()

  // Transformation API
  transformFile(
    sourceFile: SourceFile,
    config?: TransformationConfig,
  ): Promise<TransformationResult>;

  // Orchestration API
  getParallelExecutor(): ParallelExecutor | undefined;
  getIncrementalAnalyzer(): IncrementalAnalyzer | undefined;
  getProgressReporter(): ProgressReporter | undefined;
  getResourceManager(): ResourceManager | undefined;
  getOrchestrationStats(): OrchestrationStats | undefined;

  analyzeParallel(options?: ParallelAnalysisOptions): Promise<unknown[]>;
  analyzeIncremental(options?: IncrementalAnalysisOptions): Promise<unknown>;
}
Copy

Key features:

• All constructor parameters are optional with sensible defaults
• Async lifecycle management with async plugin loading
• Full TypeScript support with strict typing
• Configuration is read-only after initialization

Usage examples:

// Minimal setup
const kernel1 = new Kernel();
await kernel1.initialize();

// Explicit empty config
const kernel2 = new Kernel({});
await kernel2.initialize();

// Full configuration
const kernel3 = new Kernel({
  tsConfigPath: './tsconfig.json',
  fileSystem: new RealFileSystemAdapter(),
  plugins: [new StandalonePlugin()],
});
await kernel3.initialize();
Copy

File System Abstraction

The platform uses a custom FileSystemAdapter interface to enable both production file system access and in-memory testing:

interface FileSystemAdapter {
  readFile(path: string): Promise<string>;
  writeFile(path: string, content: string): Promise<void>;
  exists(path: string): Promise<boolean>;
  readDirectory(path: string): Promise<string[]>;
  deleteFile(path: string): Promise<void>;
  createDirectory(path: string): Promise<void>;
  fileExists(path: string): Promise<boolean>;
  directoryExists(path: string): Promise<boolean>;
  getFileStats(path: string): Promise<{ /* size, mtime, ... */ }>;
}
Copy

RealFileSystemAdapter

Production file system access with full ts-morph compatibility:

import { RealFileSystemAdapter } from '@angular-modernizer/core';

const fileSystem = new RealFileSystemAdapter();

const kernel = new Kernel({
  fileSystem,
  projectOptions: {
    fileSystem: fileSystem,
  },
});
Copy

Features:

• Full FileSystemHost implementation for ts-morph compatibility
• All sync methods implemented: readFileSync(), writeFileSync(), mkdirSync(), etc.
• Proper error handling and encoding support

InMemoryFileSystemAdapter

Testing and development with in-memory file system:

import { InMemoryFileSystemAdapter } from '@angular-modernizer/core';

const fileSystem = new InMemoryFileSystemAdapter();

const kernel = new Kernel({
  fileSystem,
  projectOptions: {
    useInMemoryFileSystem: true,
    compilerOptions: {
      target: 99,   // ES2022
      module: 199,  // NodeNext
    },
  },
});
Copy

Features:

• No file system side effects
• Fast and deterministic
• Full ts-morph compatibility

Plugin Management

The Kernel provides comprehensive plugin lifecycle management:

class Kernel {
  getPlugin(name: string): Plugin | undefined;
  getAllPlugins(): Plugin[];
  hasPlugin(name: string): boolean;
  async initialize(): Promise<void>;
}
Copy

Plugin interface:

interface Plugin {
  readonly name: string;
  readonly version: string;

  initialize(kernel: IKernel): Promise<void>;
  getAnalysisRules(): AnalysisRule[];
  getTransformRules(): TransformRule[];
  getValidationRules(): ValidationRule[];
}
Copy

Transformation Infrastructure

The core package provides a robust transformation pipeline for automated code modifications.

TransformationCoordinator

Orchestrates transformation operations across multiple plugins:

class TransformationCoordinator {
  constructor(plugins: Plugin[], api: unknown);

  async transformFile(
    sourceFile: SourceFile,
    project: Project,
    config?: TransformationConfig,
  ): Promise<TransformationResult>;
}
Copy

Key responsibilities:

• Plugin discovery (finds all TransformRules across loaded plugins)
• Context creation (builds TransformContext with dependency injection)
• Rule execution (coordinates execution through TransformExecutionEngine)
• Result aggregation (combines results from multiple rules)
• Error isolation (failed rules don't stop the entire transformation)

TransformExecutionEngine

Safely executes individual transformation rules:

class TransformExecutionEngine {
  async executeRule(
    rule: TransformRule,
    context: TransformContext,
  ): Promise<TransformResult>;
}
Copy

Key features:

• Pre-execution validation of rules and contexts
• 30-second execution timeout prevents hanging
• Structured error results instead of exceptions
• Consistent result format across all rules

TransformContext and TransformResult

interface TransformContext {
  sourceFile: SourceFile;
  project: Project;
  api?: unknown;
  config?: Record<string, unknown>;
  filePath?: string;
  type?: string;
  options?: {
    dryRun?: boolean;
    autoSave?: boolean;
    format?: boolean;
  };
}

interface TransformResult {
  ruleId: string;
  modified: boolean;
  message: string;
  filePath?: string;
  changeCount?: number;
  metadata?: Record<string, unknown>;
}
Copy

Cache Manager

Intelligent caching system for AST and analysis results with automatic invalidation.

The CacheManager provides significant performance improvements by caching expensive operations. It automatically invalidates cache entries when files change, using SHA-256 content hashing for accuracy.

interface CacheConfig {
  enabled: boolean;
  cacheDir: string;
  maxSize: number;
  maxAge: number;
  version: string;
  compression: boolean;
}

class CacheManager {
  constructor(fileSystem: FileSystemAdapter, config?: Partial<CacheConfig>);

  async initialize(): Promise<void>;

  async getAst(filePath: string): Promise<CachedAst | null>;
  async setAst(filePath: string, ast: string): Promise<void>;

  async getAnalysisResult(filePath: string): Promise<CachedAnalysisResult | null>;
  async setAnalysisResult(
    filePath: string,
    results: unknown[],
    dependencies?: string[],
  ): Promise<void>;

  async invalidate(filePath: string, type?: 'ast' | 'analysis'): Promise<void>;
  async clear(): Promise<void>;
  getStats(): CacheStats;
}
Copy

Key features:

• Content-based invalidation using SHA-256 hashes
• LRU eviction when cache size limits are reached; eviction, clear() and size statistics touch only the manager's own entries, never other caches or files in the same directory
• Entries at <cacheDir>/(ast|analysis)/<name>.<hash>.(ast|analysis).json, independent of the date, so maxAge (24 hours) applies across midnight
• Dependency tracking (invalidates analysis results when dependencies change)
• Optional gzip compression to reduce disk usage
• Real-time hit rate and performance metrics

Performance characteristics:

Usage example:

const kernel = new Kernel({
  tsConfigPath: './tsconfig.json',
  fileSystem: new RealFileSystemAdapter(),
  cacheConfig: {
    enabled: true,
    cacheDir: '.angular-modernizer-cache',
    maxSize: 100 * 1024 * 1024, // 100MB
    maxAge: 24 * 60 * 60 * 1000, // 24 hours
    compression: true,
    version: '1.0.0',
  },
});

await kernel.initialize();

const cache = kernel.getCacheManager();
if (cache) {
  const stats = cache.getStats();
  console.log(`Hit rate: ${stats.hitRate.toFixed(1)}%`);
  console.log(`Total entries: ${stats.totalEntries}`);
}
Copy

For detailed caching documentation, see CACHE.md.

Orchestration System

Advanced parallel processing, incremental analysis, and resource management for large-scale Angular projects.

interface KernelConfig {
  resourceLimits?: {
    maxMemory?: number;     // bytes, default: 80% of available
    maxWorkers?: number;    // default: CPU cores - 1
    maxQueueSize?: number;  // default: 1000
    autoThrottle?: boolean; // default: true
  };
  enableParallelExecution?: boolean; // default: true
}
Copy

Key components:

ParallelExecutor - File-level parallelism with configurable worker pools. Supports both Promise-based execution and worker threads for true multi-threaded execution.

IncrementalAnalyzer - Git-based change detection for efficient re-analysis. Uses content hashing for file modification tracking and dependency graph analysis for transitive invalidation.

ProgressReporter - Real-time progress tracking with ETA calculation. Event-driven architecture for flexible integration.

ResourceManager - Memory monitoring with configurable heap limits and CPU usage tracking. Automatic resource management for large codebases.

WorkerPool - Node.js worker threads for true parallelism. Isolated V8 instances preventing memory interference. Health monitoring with automatic recycling.

Performance characteristics:

Usage examples:

// Parallel analysis over all project files and the rules of all plugins
const kernel = new Kernel({
  tsConfigPath: './tsconfig.json',
  plugins: [new SolidPlugin()],
  resourceLimits: { maxWorkers: 4 },
});
await kernel.initialize();

const results = await kernel.analyzeParallel({
  plugins: ['@angular-modernizer/plugin-solid'],
  onProgress: (progress) => {
    console.log(`${progress.percentage}% complete, ETA: ${progress.eta}ms`);
  },
});

// Incremental analysis against a git base
const incrementalResult = await kernel.analyzeIncremental({
  baseBranch: 'main',
  includeDependents: true,
});

// Worker thread execution
const workerResults = await kernel.analyzeParallel({
  useWorkerThreads: true,
  tsConfigPath: './tsconfig.json',
  workerScriptPath: getWorkerScriptPath(), // from @angular-modernizer/worker
  maxWorkers: 4,
});
Copy

For detailed orchestration documentation, see the orchestration source files in src/orchestration/.

Feedback Collection

Privacy-first AI transformation feedback system for continuous learning and improvement.

The feedback collection system captures transformation outcomes, AI decision-making, and validation results in a privacy-preserving format that enables pattern learning without exposing sensitive code or business logic.

Key features:

• No code snippets stored, hashed file paths, bucketed metrics
• Dual storage (project .claude-feedback/ and platform root)
• Automated validation with 6 checks ensuring feedback quality
• Outlier detection (4 detection types) for anomaly handling
• Pattern detection with confidence scoring

FeedbackCollector

import { FeedbackCollector } from '@angular-modernizer/core';

const collector = new FeedbackCollector({
  projectRoot: '/path/to/project',
  platformRoot: '/path/to/tsanalyzer',
  storageLocation: 'both', // 'project', 'platform', or 'both' (default)
  salt: 'unique-installation-salt',
});

const project = new Project({ tsConfigFilePath: 'tsconfig.json' });
const sessionId = await collector.startSession({ projectRoot: '/path/to/project', project });

const feedback: TransformationFeedback = {
  transformationId: 'transform-1',
  timestamp: new Date().toISOString(),
  rule: {
    ruleId: 'standalone-migration-v1',
    ruleName: 'Migrate to Standalone Components',
    ruleType: 'transform',
    category: 'standalone-migration',
  },
  target: {
    filePathHash: 'src/app/user.component.ts', // Will be hashed
    fileType: 'component',
    linesOfCode: 147,
    complexity: 8.5,
  },
  decision: {
    approach: 'Convert to standalone component',
    alternatives: ['Keep NgModule', 'Partial migration'],
    reasoning: 'File is isolated, no complex dependencies',
    confidence: 0.95,
    contextUsed: ['file-structure', 'dependencies'],
    timeToDecision: 250,
  },
  execution: {
    succeeded: true,
    duration: 1200,
  },
  validation: {
    build: { success: true, duration: 8500, errors: [], warnings: [] },
    tests: { success: true, duration: 4200, coverage: 92.5 },
  },
  outcome: {
    status: 'success',
    quality: 'improved',
    metrics: {
      codeComplexity: { before: 10, after: 8, delta: -2 },
    },
  },
  metadata: {
    source: 'automatic',
    collectorVersion: '1.0.0',
    reliability: 1.0,
    completenessScore: 95,
  },
};

try {
  await collector.recordTransformation(sessionId, feedback);
} catch (error) {
  console.error('Validation failed:', error.message);
}

const outcome = await collector.endSession(sessionId);
console.log(`Success: ${outcome.successful}/${outcome.totalTransformations}`);
Copy

API reference:

class FeedbackCollector {
  constructor(
    config: FeedbackCollectorConfig,
    privacyFilter?: PrivacyFilter,
    feedbackStorage?: FeedbackStorage,
    feedbackValidator?: FeedbackValidator,
  );

  async startSession(context: TransformContext): Promise<string>;
  async recordTransformation(sessionId: string, feedback: TransformationFeedback): Promise<void>;
  async endSession(sessionId: string): Promise<SessionOutcome>;
  extractLearnings(feedback: TransformationFeedback): Learning[];
}
Copy

PrivacyFilter

Anonymizes sensitive data before storage:

import { PrivacyFilter } from '@angular-modernizer/core';

const filter = new PrivacyFilter({
  salt: 'unique-installation-salt',
  strictMode: true,
});

const anonymized = filter.anonymize(feedback);

// File path hashing (preserves structure)
const hashedPath = filter.anonymizeFilePath('src/app/user/user.component.ts', 'salt');
// Result: "abc123/def456/ghi789/jkl012.component.ts"

// Bucket numeric values (hide exact numbers)
const complexityBucket = filter.bucketValue(8.5, [0, 5, 10, 20, 50]);
// Result: "small" (labels: tiny, small, medium, large, huge)

// Audit privacy before storage (returns a PrivacyAudit, does not throw)
const audit = filter.auditPrivacy(anonymized);
if (!audit.passed) {
  console.error('Privacy audit failed:', {
    hasCodeSnippets: audit.hasCodeSnippets,
    hasRealFilePaths: audit.hasRealFilePaths,
    hasProjectNames: audit.hasProjectNames,
    hasBusinessLogic: audit.hasBusinessLogic,
  });
}
Copy

FeedbackValidator

Validates feedback quality with 6 checks:

import { FeedbackValidator } from '@angular-modernizer/core';

const validator = new FeedbackValidator({
  minCompletenessScore: 70,
  strictMode: false,
  maxDuration: 600000,
});

const result = validator.validate(feedback);

if (!result.valid) {
  console.error(`Validation failed (score: ${result.score}/100):`);
  result.issues.forEach((issue) => {
    console.error(`  [${issue.severity}] ${issue.field}: ${issue.message}`);
  });
}
Copy

Validation checks:

1. Schema completeness (required fields present)
2. Consistency checks (outcome matches execution)
3. Confidence sanity (high confidence failures flagged)
4. Quality metrics validity (reasonable deltas)
5. Duration sanity (positive, reasonable durations)
6. Learning quality (patterns, evidence present)

OutlierDetector

Detects anomalous feedback for quarantine:

import { OutlierDetector } from '@angular-modernizer/core';

const detector = new OutlierDetector();
const report = detector.detectOutliers(feedbackArray);

console.log(`Outlier rate: ${report.outlierRate * 100}%`);

report.outliers.forEach((outlier) => {
  console.log(`${outlier.feedbackId}: ${outlier.reasons.join(', ')}`);
  console.log(`Action: ${outlier.action}`); // 'quarantine' | 'flag' | 'purge'
});
Copy

Four outlier detection types:

1. Duration outliers: >10x median duration (unusually slow)
2. Overconfident failures: AI confidence >0.95 but transformation failed
3. Quality degradation: code complexity increased >50%
4. Impossibly fast: transformations <10ms (likely corrupted)

Target: <3% outlier rate

FeedbackStorage

Dual-location JSON Lines storage:

import { FeedbackStorage } from '@angular-modernizer/core';

const storage = new FeedbackStorage({
  projectRoot: '/path/to/project',
  platformRoot: '/path/to/tsanalyzer',
  storageLocation: 'both',
});

await storage.initSession(sessionId, session);
await storage.appendTransformation(sessionId, feedback);
const loadedSession = await storage.loadSession(sessionId);
Copy

Storage paths:

• Project: {projectRoot}/.claude-feedback/sessions/{sessionId}.jsonl
• Platform: {platformRoot}/.claude-feedback/sessions/{sessionId}.jsonl

The MCP feedback tools (collect-feedback, review-feedback, suggest-improvements, analyze-parser-performance) always use the project and add a platform root only when ANGULAR_MODERNIZER_PLATFORM_ROOT is set.

Format: JSON Lines (one JSON object per line, append-only)

Usage Patterns

Basic Kernel Setup

import { Kernel, RealFileSystemAdapter } from '@angular-modernizer/core';
import { StandalonePlugin } from '@angular-modernizer/plugin-standalone';

const kernel = new Kernel({
  tsConfigPath: './tsconfig.json',
  fileSystem: new RealFileSystemAdapter(),
  plugins: [new StandalonePlugin()],
});

await kernel.initialize();

const project = kernel.getProject();
const plugin = kernel.getPlugin('@angular-modernizer/plugin-standalone');
Copy

Testing with In-Memory File System

import { Kernel, InMemoryFileSystemAdapter } from '@angular-modernizer/core';

describe('MyPlugin', () => {
  let kernel: Kernel;

  beforeEach(async () => {
    kernel = new Kernel({
      fileSystem: new InMemoryFileSystemAdapter(),
      projectOptions: {
        useInMemoryFileSystem: true,
        compilerOptions: {
          target: 99,   // ES2022
          module: 199,  // NodeNext
        },
      },
      plugins: [new MyPlugin()],
    });

    await kernel.initialize();
  });

  it('should work with in-memory files', () => {
    const project = kernel.getProject();

    const sourceFile = project.createSourceFile(
      'test.component.ts',
      '@Component({}) export class TestComponent {}',
    );

    expect(sourceFile).toBeDefined();
  });
});
Copy

Plugin Development

import { Plugin, Kernel } from '@angular-modernizer/core';

class MyCustomPlugin implements Plugin {
  readonly name = '@my-org/plugin-custom';
  readonly version = '1.0.0';
  readonly description = 'Custom analysis and transformation rules';

  async initialize(kernel: Kernel): Promise<void> {
    console.log('Custom plugin initialized');
  }

  getAnalysisRules(): AnalysisRule[] {
    return [new MyAnalysisRule()];
  }

  getTransformRules(): TransformRule[] {
    return [new MyTransformRule()];
  }

  getValidationRules(): ValidationRule[] {
    return [];
  }
}

const kernel = new Kernel({
  plugins: [new MyCustomPlugin()],
});
Copy

Intelligent Mode Selection

The orchestration system automatically chooses between Promise-based and worker thread parallelism based on project complexity:

import { ParallelExecutor } from '@angular-modernizer/core';

const executor = new ParallelExecutor({ maxWorkers: 4 });

const results = await executor.executeParallel(sourceFiles, rules, {
  autoSelectMode: true,
});

// Mode selection analyzes:
// - File count (30% weight)
// - Total LOC/size (35% weight)
// - Large file outliers (20% weight)
// - Current memory pressure (15% weight)
//
// Decision thresholds:
// - Score < 35:  Promise mode (safe, fast startup)
// - Score 35-50: Promise mode with monitoring and fallback to workers
// - Score 50-75: Worker threads preferred
// - Score >= 75: Worker threads required
Copy

Promise mode monitoring and fallback:

const results = await executor.executeParallel(sourceFiles, rules, {
  autoSelectMode: true,
  enableMonitoring: true,
  fallbackToWorkers: true,
  workerScriptPath: getWorkerScriptPath(),
  tsConfigPath: './tsconfig.json',
});

// If Promise mode hits 85% heap limit:
// -> Aborts execution
// -> Automatically switches to worker threads
// -> Completes analysis safely
Copy

Force override (always respected):

const results = await executor.executeParallel(sourceFiles, rules, {
  useWorkerThreads: false, // Force Promise mode
});
Copy

The thresholds option exists in ParallelOptions but the mode selector currently always uses its default thresholds.

Advanced Orchestration

import { Kernel, RealFileSystemAdapter } from '@angular-modernizer/core';
import { SolidPlugin } from '@angular-modernizer/plugin-solid';
import { getWorkerScriptPath } from '@angular-modernizer/worker';

const kernel = new Kernel({
  tsConfigPath: './tsconfig.json',
  fileSystem: new RealFileSystemAdapter(),
  plugins: [new SolidPlugin()],
  resourceLimits: { maxWorkers: 4, maxMemory: 512 * 1024 * 1024 },
});

await kernel.initialize();

// Promise mode with progress
const results = await kernel.analyzeParallel({
  useWorkerThreads: false,
  onProgress: (progress) => {
    console.log(`Progress: ${progress.percentage}% (${progress.message})`);
  },
});

// Worker threads
const workerResults = await kernel.analyzeParallel({
  useWorkerThreads: true,
  tsConfigPath: './tsconfig.json',
  workerScriptPath: getWorkerScriptPath(),
});

// Incremental
const incrementalResult = await kernel.analyzeIncremental({
  baseBranch: 'main',
  includeDependents: true,
});
Copy

Code Transformations

import { Kernel, RealFileSystemAdapter } from '@angular-modernizer/core';
import { StandalonePlugin } from '@angular-modernizer/plugin-standalone';

const kernel = new Kernel({
  tsConfigPath: './tsconfig.json',
  fileSystem: new RealFileSystemAdapter(),
  plugins: [new StandalonePlugin()],
});

await kernel.initialize();

const sourceFile = kernel.getProject().getSourceFile('component.ts');
const result = await kernel.transformFile(sourceFile, {
  dryRun: false,
  autoSave: true,
  pluginConfig: {
    '@angular-modernizer/plugin-standalone': {
      migrationType: 'to-standalone',
    },
  },
});

console.log(`Success: ${result.success}`);
console.log(`Rules executed: ${result.ruleResults.length}`);
console.log(`Errors: ${result.errors.length}`);
Copy

Design Principles

Domain Agnostic

The core package contains no Angular-specific logic:

// Correct: generic infrastructure
class Kernel {
  // Manages any TypeScript project
  // Works with any plugins
  // Uses any file system
}
Copy

Optional Configuration

All configuration is optional with sensible defaults:

new Kernel();
new Kernel({});
new Kernel({ tsConfigPath: './tsconfig.json' });
new Kernel({ plugins: [plugin] });
Copy

Async by Default

All I/O operations are async for scalability:

await fileSystem.readFile('file.ts');
await fileSystem.writeFile('file.ts', content);
await kernel.initialize();
await plugin.initialize(kernel);
Copy

Testability First

In-memory file system enables fast, isolated testing:

const kernel = new Kernel({
  fileSystem: new InMemoryFileSystemAdapter(),
});
Copy

Package Structure

packages/core/
├── src/
│   ├── kernel.ts
│   ├── kernel-factory.ts        # createKernel, findTsConfigPath
│   ├── file-system.ts           # FileSystemAdapter, Real/InMemory adapters
│   ├── index.ts
│   ├── analysis/                # dependency graph, path aliases, false positives
│   ├── cache/                   # CacheManager, MultiCacheFallbackManager
│   ├── config/                  # ConfigLoader, config types
│   ├── feedback/                # FeedbackCollector, PrivacyFilter, storage
│   ├── fluent/                  # FluentKernel pipeline
│   ├── orchestration/
│   │   ├── parallel-executor.ts
│   │   ├── mode-selector.ts
│   │   ├── incremental-analyzer.ts
│   │   ├── progress-reporter.ts
│   │   ├── promise-monitor.ts
│   │   ├── resource-manager.ts
│   │   ├── worker-pool.ts
│   │   ├── types.ts
│   │   └── index.ts
│   ├── parsers/                 # parser strategies, external decorators
│   ├── pattern-analysis/
│   ├── rollback/                # BackupManager, GitIntegration, RollbackManager
│   ├── streaming/               # StreamingKernelWrapper, diffs
│   ├── testing/                 # RealFsTestHelper
│   ├── transformation/
│   │   ├── transformation-coordinator.ts
│   │   ├── transform-execution-engine.ts
│   │   ├── transform-rule-executor.ts
│   │   ├── transformation-result-validator.ts
│   │   └── index.ts
│   ├── utils/
│   └── validation/              # build, TypeScript and pre/post-transform validation
├── __tests__/
├── schemas/                     # angular-modernizer.schema.json
├── CACHE.md
├── package.json
├── tsconfig.json
├── jest.config.js
└── README.md
Copy

Dependencies

• ts-morph: TypeScript AST manipulation and project management
• @angular-modernizer/api, @angular-modernizer/plugin-system: public API and plugin contracts
• ajv: JSON Schema validation of .angular-modernizer.json
• diff: unified diffs for streaming results
• rxjs: optional peer dependency for the RxJS integration of the fluent API

Testing

pnpm --filter @angular-modernizer/core test
pnpm --filter @angular-modernizer/core test --coverage
pnpm --filter @angular-modernizer/core bench
Copy

Test categories:

• Kernel: initialization, configuration, plugin management
• File System: both real and in-memory implementations
• Cache: invalidation, LRU eviction, file change detection
• Transformation: coordinator, execution engine, context management
• Orchestration: parallel execution, incremental analysis, progress reporting, resource management, worker threads
• Performance benchmarks: cache performance, orchestration scaling, memory usage
• Integration: end-to-end kernel usage scenarios with real plugins
• Error handling: edge cases and failure scenarios

Worker thread tests run only with ENABLE_WORKER_TESTS=true.

Testing patterns:

describe('Kernel', () => {
  describe('initialization', () => {
    it('should initialize with minimal config', async () => {
      const kernel = new Kernel();
      await expect(kernel.initialize()).resolves.not.toThrow();
      expect(kernel.isInitialized()).toBe(true);
    });

    it('should initialize with full config', async () => {
      const kernel = new Kernel({
        tsConfigPath: './tsconfig.json',
        fileSystem: new RealFileSystemAdapter(),
        plugins: [new TestPlugin()],
      });

      await kernel.initialize();
      expect(kernel.getAllPlugins()).toHaveLength(1);
    });
  });
});
Copy

Performance Considerations

Memory Management

• ts-morph projects can be memory-intensive for large codebases
• Use InMemoryFileSystemAdapter for testing to reduce memory footprint
• Consider incremental analysis for very large projects

File System Operations

• RealFileSystemAdapter uses async operations for scalability
• Batch file operations when possible

Plugin Initialization

• Plugins are initialized sequentially to avoid race conditions
• Plugin initialization is async to support I/O operations
• A failing plugin initialize() aborts kernel.initialize() with Failed to initialize plugin "<name>"; plugin names must be unique

Troubleshooting

Common Issues

Kernel initialization fails:

const kernel = new Kernel({
  tsConfigPath: './tsconfig.json', // Ensure this file exists
});
Copy

Plugin not found:

const kernel = new Kernel({
  plugins: [new MyPlugin()],
});

await kernel.initialize();

console.log(kernel.getAllPlugins());
console.log(kernel.hasPlugin('my-plugin-name'));
Copy

File system errors:

const fileSystem = new RealFileSystemAdapter();
try {
  await fileSystem.exists('./src');
} catch (error) {
  console.error('File system error:', error);
}
Copy

ESLint / TypeScript IDE Errors

If VSCode shows @typescript-eslint/no-unsafe-assignment errors but the build passes:

1. Verify the code compiles: pnpm --filter @angular-modernizer/core build
2. Verify ESLint passes: npx eslint packages/core/src/orchestration/promise-monitor.ts
3. If both pass, reload the TypeScript server in VSCode (Cmd+Shift+P > "TypeScript: Restart TS Server")

This is a known issue with TypeScript language server type inference in certain contexts involving complex type narrowing. The satisfies operator can help:

private collectMetrics(): RuntimeMetrics {
  return {
    // ... properties
  } satisfies RuntimeMetrics;
}
Copy

Memory Issues with Promise-Based Parallelism

If you see FATAL ERROR: Reached heap limit Allocation failed with 500+ files:

const results = await kernel.analyzeParallel({
  useWorkerThreads: true,
  tsConfigPath: './tsconfig.json',
  workerScriptPath: getWorkerScriptPath(),
  maxWorkers: 4,
  minFilesForWorkers: 200,
});
Copy

Worker threads use isolated heaps and avoid the V8 heap fragmentation that causes crashes in Promise-based parallelism.

Worker Thread Build Errors

If worker threads fail with "Cannot find module" errors, build all packages:

pnpm run build
# Or build worker specifically
pnpm --filter @angular-modernizer/worker build
Copy

Promise-based parallelism does not require building and works immediately.

Streaming and Structured Diffs

The streaming path (deprecated on the MCP side, where tools use native progress and cancellation) is exported from the package root:

import {
  StreamingKernelWrapper,
  generateUnifiedDiff,
  generateDiffSummary,
  detectSyntaxErrors,
  type FileDiff,
  type DiffHunk,
  type LineChange,
  type SemanticAnnotation,
  type AngularContext,
  type SyntaxType,
  type StreamingOptions,
  type StreamingProgressEvent,
  type StreamingTransformResult,
} from '@angular-modernizer/core';
Copy

See Also

• packages/api/README.md - Public API tools and utilities
• packages/plugin-system/README.md - Plugin contracts and interfaces
• Orchestration source (src/orchestration/) - Orchestration and parallel processing
• CACHE.md - Comprehensive cache documentation

License

MIT License - See LICENSE file for details