Class ParserOrchestrator

Parser Orchestrator

Coordinates parser selection and fallback mechanisms for resilient parsing across different project types. Automatically selects the best parser based on project characteristics and falls back gracefully on failures.

Architecture:

ProjectContext → ParserOrchestrator → selectParser() → ParserStrategy
                        ↓
                 [StandardParser, EnhancedParser]
                        ↓
                  Cache (>80% hit rate)

Selection Algorithm:

Check cache for previous selection
Filter parsers that can handle project (canHandle() == true)
Select parser with highest reliability score
Cache selection for future use
Log decision for feedback system

Fallback Algorithm:

Try primary parser (from selectParser())
On failure, try each alternative parser in order
Log fallback attempts and results
Throw if all parsers fail

Example: Basic usage

import { ParserOrchestrator } from '@angular-modernizer/core';
import { Project } from 'ts-morph';

const project = new Project({ tsConfigFilePath: './tsconfig.json' });
const orchestrator = new ParserOrchestrator(project);

// Define project context
const context: ProjectContext = {
  projectRoot: '/path/to/project',
  hasCustomDecorators: true,
  hasPathAliases: true,
  hasComplexConstructors: false,
  angularVersion: '17.0.0'
};

// Auto-select best parser
const parser = await orchestrator.selectParser(context);
console.info(`Selected: ${parser.name}`); // 'enhanced'

// Parse with automatic fallback
const result = await orchestrator.parseWithFallback(
  'src/app/component.ts',
  fileContent,
  context
);
console.info(`Parsed by: ${result.parserUsed}`);

Example: With fallback

// If primary parser fails, orchestrator tries alternatives
try {
  const result = await orchestrator.parseWithFallback(file, content, context);
  if (result.fallbackUsed) {
    console.warn(`Primary parser failed, used ${result.parserUsed}`);
    result.failedParsers?.forEach(({ parserName, error }) => {
      console.error(`${parserName}: ${error}`);
    });
  }
} catch (error) {
  console.error('All parsers failed:', error);
}

Index

Constructors

constructor

Methods

clearCache getCacheStats getSelectedStrategy getSelectionHistory getStrategies parseWithFallback selectParser transform

Constructors

constructor

new ParserOrchestrator(
project: Project,
options?: { verboseLogging?: boolean },
): ParserOrchestrator
Initialize the Parser Orchestrator.

Registers available parser strategies:
- StandardParserStrategy (0.95 reliability for standard projects)
- EnhancedParserStrategy (0.6-0.8 reliability for complex projects)
Strategies are ordered by preference (StandardParser first for performance).
Parameters
- project: Project
  ts-morph Project instance for parsing
- Optionaloptions: { verboseLogging?: boolean }
  Configuration options
Returns ParserOrchestrator
Example
```
const project = new Project({ tsConfigFilePath: './tsconfig.json' });
const orchestrator = new ParserOrchestrator(project, {
  verboseLogging: true
});
```

Methods

clearCache

clearCache(): void
Clear the parser selection cache.

Useful for testing or forcing re-evaluation of parser selection.

Returns void
Example
```
orchestrator.clearCache();
// Next selectParser() call will re-evaluate
```

getCacheStats

getCacheStats(): {
    cacheHits: number;
    hitRate: number;
    size: number;
    totalSelections: number;
}
Get cache statistics for monitoring.

Returns { cacheHits: number; hitRate: number; size: number; totalSelections: number }
Cache statistics object
- cacheHits: number
  Selections answered from the cache.
- hitRate: number
  cacheHits / totalSelections (0 to 1; 0 without selections).
- size: number
  Number of cached parser selections.
- totalSelections: number
  Number of recorded parser selections.
Example
```
const stats = orchestrator.getCacheStats();
console.info(`Cache size: ${stats.size}`);
console.info(`Hit rate: ${(stats.hitRate * 100).toFixed(1)}%`);
```

getSelectedStrategy

getSelectedStrategy(): string
Get the name of the currently selected parser strategy.

Returns 'none' if no parser has been selected yet.

Returns string
Parser strategy name or 'none'
Example
```
await orchestrator.selectParser(context);
console.info(orchestrator.getSelectedStrategy()); // 'enhanced'
```

getSelectionHistory

getSelectionHistory(): ParserSelectionDecision[]

Get parser selection history for feedback analysis.

Limited to last 100 selections to prevent memory leaks.

Returns ParserSelectionDecision[]

Array of parser selection decisions

Example

const history = orchestrator.getSelectionHistory();
console.info(`Total selections: ${history.length}`);
console.info(`Cache hit rate: ${history.filter(h => h.fromCache).length / history.length}`);
history.forEach(decision => {
  console.info(`${decision.timestamp}: ${decision.selectedParser} (${decision.reliability})`);
});

getStrategies

getStrategies(): ParserStrategy[]

Get all registered parser strategies.

Returns ParserStrategy[]

Array of registered parser strategies

Example

const strategies = orchestrator.getStrategies();
strategies.forEach(s => {
  console.info(`${s.name}: can handle = ${s.canHandle(context)}`);
});

parseWithFallback

parseWithFallback(
    file: string,
    content: string,
    projectContext: ParserProjectContext,
): Promise<ParseWithFallbackResult>
Parse a file with automatic fallback on failure.

Fallback algorithm:
1. Try primary parser (from selectParser())
2. On failure, log error and try each alternative parser
3. Return first successful parse result with metadata
4. Throw if all parsers fail
Resilience: Gracefully degrades to alternative parsers on failure Performance: No overhead unless primary parser fails
Parameters
- file: string
  File path to parse
- content: string
  File content to parse
- projectContext: ParserProjectContext
  Project characteristics
Returns Promise<ParseWithFallbackResult>
Promise resolving to parse result with fallback metadata
Throws
Error if all parsers fail
Example: Successful primary parse
```
const result = await orchestrator.parseWithFallback(file, content, context);
console.info(`Parsed by: ${result.parserUsed}`); // 'enhanced'
console.info(`Fallback used: ${result.fallbackUsed}`); // false
console.info(`Errors: ${result.ast.errors.length}`); // 0
```
Example: With fallback
```
// If EnhancedParser fails, StandardParser used as fallback
const result = await orchestrator.parseWithFallback(file, content, context);
if (result.fallbackUsed) {
  console.warn(`Primary parser failed, using ${result.parserUsed}`);
  result.failedParsers?.forEach(({ parserName, error }) => {
    console.error(`${parserName} failed: ${error}`);
  });
}
```

selectParser

selectParser(projectContext: ParserProjectContext): Promise<ParserStrategy>
Select the best parser for the given project context.

Selection algorithm:
1. Check cache for previous selection
2. Filter parsers that can handle the project (canHandle() == true)
3. Select parser with highest reliability score
4. Cache selection for future use
5. Log decision for feedback system
Performance:
- Cached selection: <1ms
- New selection: <5ms
- Cache hit rate: >80% in typical usage
Parameters
- projectContext: ParserProjectContext
  Project characteristics
Returns Promise<ParserStrategy>
Promise resolving to selected ParserStrategy
Throws
Error if no parser can handle the project
Example: Standard project (uses StandardParser)
```
const context: ProjectContext = {
  projectRoot: '/app',
  hasCustomDecorators: false,
  hasPathAliases: false,
  hasComplexConstructors: false,
  angularVersion: '17.0.0'
};
const parser = await orchestrator.selectParser(context);
console.info(parser.name); // 'standard'
console.info(parser.getReliability(context)); // 0.95
```
Example: Complex project (uses EnhancedParser)
```
const context: ProjectContext = {
  projectRoot: '/app',
  hasCustomDecorators: true,
  hasPathAliases: true,
  hasComplexConstructors: false,
  angularVersion: '16.0.0'
};
const parser = await orchestrator.selectParser(context);
console.info(parser.name); // 'enhanced'
console.info(parser.getReliability(context)); // 0.65
```

transform

transform(
ast: ParserAST,
rules: TransformRule[],
): Promise<ParserTransformResult>
Transform an AST with the selected parser.

Delegates to the currently selected parser's transform method.
Parameters
- ast: ParserAST
  Abstract Syntax Tree to transform
- rules: TransformRule[]
  Transformation rules to apply
Returns Promise<ParserTransformResult>
Promise resolving to transformation result
Example
```
const parseResult = await orchestrator.parseWithFallback(file, content, context);
const transformResult = await orchestrator.transform(parseResult.ast, rules);
console.info(`Modified: ${transformResult.modified}`);
console.info(`Parser: ${transformResult.metadata?.parserStrategy}`);
```

Class ParserOrchestrator

Example: Basic usage

Example: With fallback

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns ParserOrchestrator

Example

Methods

clearCache

Returns void

Example

getCacheStats

Returns { cacheHits: number; hitRate: number; size: number; totalSelections: number }

cacheHits: number

hitRate: number

size: number

totalSelections: number

Example

getSelectedStrategy

Returns string

Example

getSelectionHistory

Returns ParserSelectionDecision[]

Example

getStrategies

Returns ParserStrategy[]

Example

parseWithFallback

Parameters

Returns Promise<ParseWithFallbackResult>

Throws

Example: Successful primary parse

Example: With fallback

selectParser

Parameters

Returns Promise<ParserStrategy>

Throws

Example: Standard project (uses StandardParser)

Example: Complex project (uses EnhancedParser)

transform

Parameters

Returns Promise<ParserTransformResult>

Example

Settings

On This Page