Node.js Tools

/**
 * Engine host that resolves collections from npm packages
 */
class NodeModulesEngineHost extends FileSystemEngineHostBase {
  constructor(paths?: string[]);
  
  /** Get schematic metadata from package.json */
  protected _resolveCollectionPath(name: string, requester?: string): string;
  
  /** Transform relative paths to absolute for npm packages */
  protected _resolveReferenceString(refString: string, parentPath: string, collectionDescription?: CollectionDescription<{}>): { ref: RuleFactory<{}>, path: string } | null;
  
  /** Load package.json and extract schematics metadata */
  protected _transformCollectionDescription(name: string, desc: Partial<FileSystemCollectionDesc>): FileSystemCollectionDesc;
}

/**
 * Exception thrown when a package doesn't support schematics
 */
class NodePackageDoesNotSupportSchematics extends BaseException {
  constructor(name: string);
}

/**
 * Testing version of NodeModulesEngineHost with additional capabilities
 */
class NodeModulesTestEngineHost extends NodeModulesEngineHost {
  constructor(paths?: string[]);
  
  readonly tasks: TaskConfiguration[];
  
  /** Register a collection for testing */
  registerCollection(collectionName: string, collectionPath: string): void;
  
  /** Register option transformation for testing */
  registerOptionsTransform<T, R>(transform: OptionTransform<T, R>): void;
  
  /** Register custom task executor */
  registerTaskExecutor<T>(factory: TaskExecutorFactory<T>): void;
  
  /** Clear all registered tasks */
  clearTasks(): void;
}

/**
 * Creates an option transformer that validates options against JSON schema
 */
function validateOptionsWithSchema(
  registry: schema.SchemaRegistry
): OptionTransform<object, object>;

/**
 * Option transformation function type
 */
type OptionTransform<T, R> = (
  schematic: FileSystemSchematicDescription,
  options: T,
  context?: FileSystemSchematicContext,
) => Observable<R> | PromiseLike<R> | R;

/**
 * Reference to an exported value from a module
 */
class ExportStringRef<T> {
  constructor(ref: string, parentPath?: string, inner?: boolean);
  
  readonly ref: T | undefined;
  readonly module: string;
  readonly path: string;
}

import { 
  NodeModulesEngineHost, 
  NodeModulesTestEngineHost,
  validateOptionsWithSchema 
} from "@angular-devkit/schematics/tools";
import { schema } from "@angular-devkit/core";

// Use NodeModulesEngineHost to resolve npm package schematics
const engineHost = new NodeModulesEngineHost();
const engine = new SchematicEngine(engineHost);

// Resolve collection from npm package
const collection = engine.createCollection('@schematics/angular');
const schematic = collection.createSchematic('component');

// Testing with NodeModulesTestEngineHost
const testEngineHost = new NodeModulesTestEngineHost();

// Register a collection for testing
testEngineHost.registerCollection('test-collection', './test-schematics');

// Register schema validation
const registry = new schema.CoreSchemaRegistry();
testEngineHost.registerOptionsTransform(
  validateOptionsWithSchema(registry)
);

// Execute schematic and check tasks
const context = engine.createContext(schematic);
const result = await schematic.call(options, context).toPromise();
console.log('Registered tasks:', testEngineHost.tasks);

/**
 * Abstract base class for file system-based engine hosts
 */
abstract class FileSystemEngineHostBase implements FileSystemEngineHost {
  /** Load collection description from file system */
  protected abstract _resolveCollectionPath(name: string, requester?: string): string;
  
  /** Resolve reference strings to factory functions */
  protected abstract _resolveReferenceString(
    refString: string, 
    parentPath: string, 
    collectionDescription?: CollectionDescription<{}>
  ): { ref: RuleFactory<{}>, path: string } | null;
  
  /** Transform loaded collection metadata */
  protected abstract _transformCollectionDescription(
    name: string, 
    desc: Partial<FileSystemCollectionDesc>
  ): FileSystemCollectionDesc;
  
  /** Transform loaded schematic metadata */
  protected abstract _transformSchematicDescription(
    name: string,
    collection: Readonly<FileSystemCollectionDesc>,
    desc: Partial<FileSystemSchematicDesc>
  ): FileSystemSchematicDesc;
}

/**
 * Collection description for file system-based collections
 */
interface FileSystemCollectionDescription {
  readonly name: string;
  readonly path: string;
  readonly version?: string;
  readonly schematics: { [name: string]: FileSystemSchematicDesc };
  readonly encapsulation?: boolean;
}

/**
 * Schematic description with file system information
 */
interface FileSystemSchematicDescription extends FileSystemSchematicJsonDescription {
  readonly path: string;
  readonly schemaJson?: JsonObject;
  readonly factoryFn: RuleFactory<{}>;
}

/**
 * Context for file system schematic execution
 */
interface FileSystemSchematicContext extends TypedSchematicContext<FileSystemCollectionDescription, FileSystemSchematicDescription> {}

/**
 * Factory for creating task executors
 */
type TaskExecutorFactory<T> = (options: T) => TaskExecutor<T>;

/**
 * Task executor function
 */
interface TaskExecutor<T = {}> {
  (options: T | undefined, context: SchematicContext): Promise<void> | Observable<void>;
}

class CollectionCannotBeResolvedException extends BaseException {
  constructor(name: string);
}

class InvalidCollectionJsonException extends BaseException {
  constructor(name: string, path: string, jsonException?: Error);
}

class SchematicMissingFactoryException extends BaseException {
  constructor(name: string);
}

class FactoryCannotBeResolvedException extends BaseException {
  constructor(name: string);
}

class CollectionMissingSchematicsMapException extends BaseException {
  constructor(name: string);
}

class CollectionMissingFieldsException extends BaseException {
  constructor(name: string);
}

class SchematicMissingFieldsException extends BaseException {
  constructor(name: string);
}

class SchematicMissingDescriptionException extends BaseException {
  constructor(name: string);
}

class SchematicNameCollisionException extends BaseException {
  constructor(name: string);
}

class InvalidSchematicsNameException extends BaseException {
  constructor(name: string);
}