@hexaijs/plugin-contracts-generator 0.1.1 → 0.2.0

package/dist/index.d.ts

@@ -1,43 +1,536 @@
+import { D as DecoratorNames, M as MessageType, R as ResponseNamingConvention, S as SourceFile, a as DomainEvent, C as Command, Q as Query, T as TypeDefinition, b as ContractsPluginConfig } from './cli-CPg-O4OY.js';
+export { A as ArrayType, c as ClassDefinition, d as ClassImport, e as Config, f as Dependency, g as DependencyKind, E as EnumDefinition, h as EnumMember, i as ExtractionError, j as ExtractionResult, k as ExtractionWarning, F as Field, l as FunctionParameter, m as FunctionType, I as ImportSource, n as IntersectionType, L as LiteralType, o as Message, p as MessageBase, O as ObjectType, P as PrimitiveType, q as ReferenceType, r as TupleType, s as TypeDefinitionKind, t as TypeRef, U as UnionType, u as isArrayType, v as isCommand, w as isDomainEvent, x as isFunctionType, y as isIntersectionType, z as isLiteralType, B as isObjectType, G as isPrimitiveType, H as isReferenceType, J as isTupleType, K as isUnionType } from './cli-CPg-O4OY.js';
+export { PublicCommand, PublicCommandOptions, PublicEvent, PublicEventOptions, PublicQuery, PublicQueryOptions } from './decorators/index.js';
+import { HexaiCliPlugin } from '@hexaijs/cli';
+
+interface FileStats {
+    isDirectory(): boolean;
+    isFile(): boolean;
+}
+interface FileSystem {
+    readFile(path: string): Promise<string>;
+    readdir(path: string): Promise<string[]>;
+    writeFile(path: string, content: string): Promise<void>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<FileStats>;
+}
+declare class NodeFileSystem implements FileSystem {
+    readFile(path: string): Promise<string>;
+    readdir(path: string): Promise<string[]>;
+    writeFile(path: string, content: string): Promise<void>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<FileStats>;
+}
+declare const nodeFileSystem: NodeFileSystem;
+
+interface ScannerOptions {
+    exclude?: string[];
+    fileSystem?: FileSystem;
+    decoratorNames?: DecoratorNames;
+    /**
+     * Filter which message types to scan for.
+     * Defaults to all types: ['event', 'command', 'query']
+     */
+    messageTypes?: MessageType[];
+}
+declare class Scanner {
+    private readonly exclude;
+    private readonly fs;
+    private readonly decoratorPatterns;
+    constructor(options?: ScannerOptions);
+    scan(sourceDir: string): Promise<string[]>;
+    private containsPublicDecorator;
+}
+
+interface ParseResult {
+    readonly events: readonly DomainEvent[];
+    readonly commands: readonly Command[];
+    readonly queries: readonly Query[];
+    readonly typeDefinitions: readonly TypeDefinition[];
+}
+interface ParserOptions {
+    decoratorNames?: DecoratorNames;
+    responseNamingConventions?: readonly ResponseNamingConvention[];
+    messageTypes?: readonly MessageType[];
+}
+declare class Parser {
+    private readonly decoratorMappings;
+    private readonly responseNamingConventions;
+    private readonly messageTypes;
+    constructor(options?: ParserOptions);
+    parse(sourceCode: string, sourceFileInfo: SourceFile): ParseResult;
+    private collectMessagesFromClass;
+    private applyNamingConventionMatching;
+    private findMatchingResponseType;
+    private buildMessage;
+    private extractMessageDetails;
+    private extractPayload;
+    private parsePayloadTypeArgument;
+    private flattenIntersectionToFields;
+    private extractTypeDefinition;
+    private extractInterfaceDefinition;
+    private buildTypeDefinition;
+}
+
+interface InputContextConfig {
+    readonly name: string;
+    readonly path: string;
+    readonly sourceDir?: string;
+    readonly tsconfigPath?: string;
+    readonly responseNamingConventions?: readonly ResponseNamingConvention[];
+}
 /**
- * Contracts Generator
+ * Encapsulates context configuration with path resolution capabilities.
+ * Created via factory method to ensure proper initialization.
+ */
+declare class ContextConfig {
+    private readonly fs;
+    private readonly tsconfig;
+    readonly name: string;
+    readonly sourceDir: string;
+    readonly responseNamingConventions?: readonly ResponseNamingConvention[];
+    private constructor();
+    /**
+     * Factory method to create ContextConfig with properly loaded tsconfig.
+     */
+    static create(input: InputContextConfig, configDir: string, fs?: FileSystem): Promise<ContextConfig>;
+    private static loadTsconfig;
+    /**
+     * Creates a ContextConfig without async loading (for cases where tsconfig is not needed
+     * or already handled externally).
+     */
+    static createSync(name: string, sourceDir: string, fs?: FileSystem, responseNamingConventions?: readonly ResponseNamingConvention[]): ContextConfig;
+    /**
+     * Resolves a module specifier (path alias) to actual file path.
+     * Only handles non-relative imports (path aliases).
+     *
+     * @param moduleSpecifier - The import path to resolve (e.g., "@/utils/helper")
+     * @returns Object with resolvedPath (null if external) and isExternal flag
+     */
+    resolvePath(moduleSpecifier: string): Promise<{
+        resolvedPath: string | null;
+        isExternal: boolean;
+    }>;
+    private tryResolveWithExtensions;
+}
+
+interface ImportInfo {
+    moduleSpecifier: string;
+    resolvedPath: string | null;
+    isExternal: boolean;
+    importedNames: string[];
+}
+interface FileNode {
+    absolutePath: string;
+    relativePath: string;
+    imports: ImportInfo[];
+    isEntryPoint: boolean;
+}
+interface FileGraph {
+    nodes: Map<string, FileNode>;
+    entryPoints: Set<string>;
+    excludedPaths: Set<string>;
+}
+interface FileGraphResolverOptions {
+    contextConfig: ContextConfig;
+    fileSystem?: FileSystem;
+    excludeDependencies?: string[];
+}
+declare class FileGraphResolver {
+    private readonly contextConfig;
+    private readonly fs;
+    private readonly excludeDependencies;
+    private constructor();
+    static create(options: FileGraphResolverOptions): FileGraphResolver;
+    buildGraph(entryPoints: string[], sourceRoot: string): Promise<FileGraph>;
+    private extractImports;
+    private readSourceFile;
+    private extractModuleSpecifier;
+    private extractImportedNamesFromNode;
+    private resolveModule;
+    private queueUnvisitedLocalDependencies;
+    private shouldExclude;
+    private resolveRelativeModule;
+    private tryResolveWithExtensions;
+}
+
+interface CopyOptions {
+    sourceRoot: string;
+    outputDir: string;
+    fileGraph: FileGraph;
+    pathAliasRewrites?: Map<string, string>;
+    removeDecorators?: boolean;
+    responseTypesToExport?: Map<string, string[]>;
+    messageTypes?: readonly MessageType[];
+    decoratorNames?: DecoratorNames;
+}
+interface CopyResult {
+    copiedFiles: string[];
+    rewrittenImports: Map<string, string[]>;
+}
+interface FileCopierOptions {
+    fileSystem?: FileSystem;
+}
+declare class FileCopier {
+    private readonly fs;
+    constructor(options?: FileCopierOptions);
+    copyFiles(options: CopyOptions): Promise<CopyResult>;
+    private preprocessEntryFiles;
+    private expandTransitiveDependencies;
+    private resolveNodeContent;
+    private applyTransformations;
+    generateBarrelExport(copiedFiles: string[], outputDir: string): string;
+    private readFileContent;
+    private writeOutputFile;
+    private processExcludedImports;
+    private processDecoratorRemoval;
+    private processTypeExports;
+    private processInternalPathAliases;
+    private processExternalPathAliases;
+    private createExportStatement;
+    private rewriteInternalPathAliases;
+    private isExternalOrRelativeImport;
+    private resolveInternalImport;
+    private rewriteModuleSpecifier;
+    private computeRelativePath;
+    private applyPathAliasRewrites;
+    private escapeRegex;
+    private removeExcludedImports;
+    private findExcludedModuleSpecifiers;
+    private createExcludedImportsVisitor;
+    private isImportFromExcludedModule;
+    private isExportFromExcludedModule;
+    private removeContractDecorators;
+    private createDecoratorRemovalVisitor;
+    private processContractGeneratorImport;
+    private createImportWithFilteredBindings;
+    private removeContractDecoratorsFromClass;
+    private extractDecoratorName;
+    private isDecoratorCallExpression;
+    private hasExportModifier;
+    private prependExportModifier;
+    private addExportToTypes;
+    private createExportAdditionVisitor;
+    private addExportToTypeAlias;
+    private addExportToInterface;
+    private transformSourceFile;
+    private extractSymbolsFromEntry;
+    private buildDecoratorToMessageTypeMap;
+    private findTargetClasses;
+    private computeRelatedTypeNames;
+    private collectUsedIdentifiers;
+    private collectDecoratorIdentifier;
+    private collectLocalTypeDeclarations;
+    private addToDeclarationMap;
+    private resolveIncludedLocalTypes;
+    private collectTypeIdentifiersFromNodes;
+    private collectComputedPropertyIdentifier;
+    private generateExtractedOutput;
+    private buildImportMap;
+    private filterImports;
+    private appendImportStatements;
+    private appendLocalTypeDeclarations;
+    private appendTargetClasses;
+    private appendNodeWithExport;
+    private nodeHasExportKeyword;
+}
+
+/**
+ * Base error class for all contracts-generator errors.
+ * Allows catching all library errors with `instanceof MessageParserError`.
+ */
+declare class MessageParserError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Base class for configuration-related errors.
+ */
+declare class ConfigurationError extends MessageParserError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Error thrown when loading application.config.ts fails.
+ */
+declare class ConfigLoadError extends ConfigurationError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Base class for file system operation errors.
+ */
+declare class FileSystemError extends MessageParserError {
+    readonly path: string;
+    constructor(message: string, path: string, options?: ErrorOptions);
+}
+/**
+ * Error thrown when a required file is not found.
+ */
+declare class FileNotFoundError extends FileSystemError {
+    constructor(path: string, options?: ErrorOptions);
+}
+/**
+ * Error thrown when reading a file fails.
+ */
+declare class FileReadError extends FileSystemError {
+    constructor(path: string, options?: ErrorOptions);
+}
+/**
+ * Error thrown when writing a file fails.
+ */
+declare class FileWriteError extends FileSystemError {
+    constructor(path: string, options?: ErrorOptions);
+}
+/**
+ * Base class for parsing errors.
+ */
+declare class ParseError extends MessageParserError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Error thrown when JSON parsing fails.
+ */
+declare class JsonParseError extends ParseError {
+    readonly filePath?: string;
+    constructor(message: string, filePath?: string, options?: ErrorOptions);
+}
+/**
+ * Base class for module/path resolution errors.
+ */
+declare class ResolutionError extends MessageParserError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Error thrown when module resolution fails.
+ */
+declare class ModuleResolutionError extends ResolutionError {
+    readonly moduleSpecifier: string;
+    readonly fromFile: string;
+    constructor(moduleSpecifier: string, fromFile: string, options?: ErrorOptions);
+}
+
+interface ContractsConfig {
+    readonly contexts: readonly ContextConfig[];
+    readonly pathAliasRewrites?: Readonly<Record<string, string>>;
+    readonly externalDependencies?: Readonly<Record<string, string>>;
+    readonly decoratorNames: Required<DecoratorNames>;
+    readonly responseNamingConventions?: readonly ResponseNamingConvention[];
+    readonly removeDecorators?: boolean;
+}
+interface ConfigLoaderOptions {
+    fileSystem?: FileSystem;
+}
+declare class ConfigLoader {
+    private readonly fs;
+    constructor(options?: ConfigLoaderOptions);
+    load(configPath: string): Promise<ContractsConfig>;
+    private loadTypeScriptConfig;
+    private extractContractsConfig;
+    private resolveContexts;
+    private resolveStringContext;
+    private expandGlobPattern;
+    private createObjectContext;
+    private matchGlobPattern;
+}
+
+interface RegistryGeneratorOptions {
+    readonly messageRegistryImport: string;
+    readonly useNamespace?: boolean;
+}
+interface ContextMessages {
+    readonly contextName: string;
+    readonly events: readonly DomainEvent[];
+    readonly commands: readonly Command[];
+    readonly queries?: readonly Query[];
+    readonly importPath?: string;
+}
+declare class RegistryGenerator {
+    private readonly options;
+    constructor(options?: Partial<RegistryGeneratorOptions>);
+    generate(contexts: readonly ContextMessages[]): string;
+    private generateEmptyRegistry;
+    private generateWithNamespace;
+    private getNamespaceInfos;
+    private generateNamespaceImports;
+    private generateNamespaceExports;
+    private generateNamespaceRegistrations;
+    private toNamespace;
+    private generateImports;
+    private generateRegistrations;
+}
+
+/**
+ * Represents an import that was rewritten via pathAliasRewrites
+ */
+interface RewrittenImport {
+    /** The rewritten module specifier (e.g., "@libera/contracts/common/request") */
+    readonly rewrittenPath: string;
+    /** The original module specifier before rewrite (e.g., "@libera/common/request") */
+    readonly originalPath: string;
+    /** The imported symbol names */
+    readonly symbols: readonly string[];
+    /** Whether this is a type-only import */
+    readonly isTypeOnly: boolean;
+}
+/**
+ * Represents a re-export file to be generated
+ */
+interface ReexportFile {
+    /** Relative path within contracts output dir (e.g., "common/request.ts") */
+    readonly relativePath: string;
+    /** The original module to re-export from */
+    readonly originalModule: string;
+    /** Symbols to re-export */
+    readonly symbols: readonly string[];
+    /** Whether all symbols are type-only */
+    readonly isTypeOnly: boolean;
+}
+interface ReexportGeneratorOptions {
+    fileSystem?: FileSystem;
+}
+interface AnalyzeOptions {
+    /** The files to analyze (absolute paths) */
+    readonly files: readonly string[];
+    /** Map of original path prefix -> rewritten path prefix */
+    readonly pathAliasRewrites: ReadonlyMap<string, string>;
+}
+interface GenerateOptions {
+    /** The output directory for re-export files */
+    readonly outputDir: string;
+    /** The re-export files to generate */
+    readonly reexportFiles: readonly ReexportFile[];
+}
+/**
+ * Generates re-export files for pathAliasRewrites
+ */
+declare class ReexportGenerator {
+    private readonly fs;
+    constructor(options?: ReexportGeneratorOptions);
+    /**
+     * Analyzes files to find imports that match pathAliasRewrites
+     * and groups them by rewritten path
+     */
+    analyze(options: AnalyzeOptions): Promise<ReexportFile[]>;
+    /**
+     * Generates re-export files
+     */
+    generate(options: GenerateOptions): Promise<string[]>;
+    /**
+     * Extracts imports from source content that match rewritten prefixes
+     */
+    private extractRewrittenImports;
+    /**
+     * Extracts symbol names from import clause
+     */
+    private extractSymbolNames;
+    /**
+     * Groups imports by rewritten path and merges symbols
+     */
+    private groupImportsByPath;
+    /**
+     * Converts a rewritten package path to a relative file path
+     * e.g., "@libera/contracts/common/request" with prefix "@libera/contracts"
+     *       -> "common/request.ts"
+     */
+    private rewrittenPathToRelativePath;
+    /**
+     * Generates the content for a re-export file
+     */
+    private generateReexportContent;
+}
+
+type LogLevel = "debug" | "info" | "warn" | "error";
+interface Logger {
+    debug(message: string): void;
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+}
+interface ConsoleLoggerOptions {
+    level?: LogLevel;
+}
+declare class ConsoleLogger implements Logger {
+    private readonly level;
+    constructor(options?: ConsoleLoggerOptions);
+    debug(message: string): void;
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+    private shouldLog;
+}
+declare const noopLogger: Logger;
+
+interface PipelineDependencies {
+    readonly scanner: Scanner;
+    readonly parser: Parser;
+    readonly fileGraphResolver: FileGraphResolver;
+    readonly fileCopier: FileCopier;
+    readonly fileSystem: FileSystem;
+    readonly logger: Logger;
+}
+interface PipelineOptions {
+    readonly contextName: string;
+    readonly sourceDir: string;
+    readonly outputDir: string;
+    readonly pathAliasRewrites?: Map<string, string>;
+    readonly removeDecorators?: boolean;
+}
+interface PipelineResult {
+    readonly events: readonly DomainEvent[];
+    readonly commands: readonly Command[];
+    readonly queries: readonly Query[];
+    readonly copiedFiles: string[];
+}
+interface ParsedMessages {
+    readonly events: readonly DomainEvent[];
+    readonly commands: readonly Command[];
+    readonly queries: readonly Query[];
+    readonly typeDefinitions: readonly TypeDefinition[];
+}
+declare class ContractsPipeline {
+    private readonly deps;
+    private readonly messageTypes?;
+    private constructor();
+    static create(options: {
+        contextConfig: ContextConfig;
+        responseNamingConventions?: readonly ResponseNamingConvention[];
+        fileSystem?: FileSystem;
+        logger?: Logger;
+        excludeDependencies?: string[];
+        messageTypes?: MessageType[];
+    }): ContractsPipeline;
+    static fromDependencies(deps: PipelineDependencies): ContractsPipeline;
+    execute(options: PipelineOptions): Promise<PipelineResult>;
+    private collectResponseTypesToExport;
+    scan(sourceDir: string): Promise<string[]>;
+    parse(files: string[], sourceRoot: string): Promise<ParsedMessages>;
+    resolve(entryPoints: string[], sourceRoot: string): Promise<FileGraph>;
+    copy(fileGraph: FileGraph, sourceRoot: string, outputDir: string, pathAliasRewrites?: Map<string, string>, responseTypesToExport?: Map<string, string[]>, removeDecorators?: boolean, messageTypes?: readonly MessageType[]): Promise<string[]>;
+    exportBarrel(copiedFiles: string[], outputDir: string): Promise<void>;
+}
+
+/**
+ * CLI plugin definition for hexai integration.
  *
- * Extract Domain Events and Commands from TypeScript source code using decorators.
+ * This allows the contracts generator to be invoked via `pnpm hexai generate-contracts`.
+ * Configuration is provided via hexai.config.ts.
  *
  * @example
- * ```typescript
- * import { extract } from '@hexaijs/plugin-contracts-generator';
- *
- * const result = await extract({
- *   sourceDir: 'packages',
- *   outputDir: 'packages/contracts',
- * });
- *
- * console.log(`Extracted ${result.events.length} events and ${result.commands.length} commands`);
+ * ```bash
+ * pnpm hexai generate-contracts -o packages/contracts/src
+ * pnpm hexai generate-contracts -o packages/contracts/src -m event,command
  * ```
  */
-export type { SourceFile, TypeRef, PrimitiveType, ArrayType, ObjectType, UnionType, IntersectionType, ReferenceType, LiteralType, TupleType, FunctionType, FunctionParameter, Field, TypeDefinition, TypeDefinitionKind, EnumMember, EnumDefinition, ClassDefinition, ClassImport, Message, MessageBase, DomainEvent, Command, Dependency, DependencyKind, ImportSource, ExtractionResult, ExtractionError, ExtractionWarning, Config, } from "./domain/types";
-export { isPrimitiveType, isArrayType, isObjectType, isUnionType, isIntersectionType, isReferenceType, isLiteralType, isTupleType, isFunctionType, isDomainEvent, isCommand, } from "./domain/types";
-export { PublicEvent, PublicCommand, PublicQuery, type PublicEventOptions, type PublicCommandOptions, type PublicQueryOptions, } from "./decorators";
-export { Scanner, type ScannerOptions } from "./scanner";
-export { Parser, type ParseResult } from "./parser";
-export { FileGraphResolver } from "./file-graph-resolver";
-export { FileCopier } from "./file-copier";
-export { TsconfigLoader } from "./tsconfig-loader";
-export { ConfigLoader, type ContractsConfig, type ContextConfig, } from "./config-loader";
-export { MessageParserError, ConfigurationError, ConfigLoadError, TsconfigLoadError, FileSystemError, FileNotFoundError, FileReadError, FileWriteError, ParseError, JsonParseError, ResolutionError, ModuleResolutionError, } from "./errors";
-export { RegistryGenerator, type RegistryGeneratorOptions, type ContextMessages, } from "./registry-generator";
-export { ReexportGenerator, type ReexportGeneratorOptions, type AnalyzeOptions, type GenerateOptions, type RewrittenImport, type ReexportFile, } from "./reexport-generator";
-import { type FileSystem } from "./file-system";
-import { type Logger } from "./logger";
-export type { FileSystem, FileStats } from "./file-system";
-export { nodeFileSystem } from "./file-system";
-export type { Logger, LogLevel, ConsoleLoggerOptions } from "./logger";
-export { ConsoleLogger, noopLogger } from "./logger";
-export { ContractsPipeline, type PipelineDependencies, type PipelineOptions, type PipelineResult, type ParsedMessages, } from "./pipeline";
-import type { ResponseNamingConvention, MessageType } from "./domain/types";
-export interface ProcessContextOptions {
+declare const cliPlugin: HexaiCliPlugin<ContractsPluginConfig>;
+
+interface ProcessContextOptions {
     contextName: string;
-    sourceDir: string;
+    path: string;
+    sourceDir?: string;
     outputDir: string;
     pathAliasRewrites?: Map<string, string>;
     tsconfigPath?: string;
@@ -47,12 +540,12 @@ export interface ProcessContextOptions {
     fileSystem?: FileSystem;
     logger?: Logger;
 }
-export interface ProcessContextResult {
-    events: readonly import("./domain/types").DomainEvent[];
-    commands: readonly import("./domain/types").Command[];
-    queries: readonly import("./domain/types").Query[];
+interface ProcessContextResult {
+    events: readonly DomainEvent[];
+    commands: readonly Command[];
+    queries: readonly Query[];
     copiedFiles: string[];
 }
-export declare function processContext(options: ProcessContextOptions): Promise<ProcessContextResult>;
-export { cliPlugin } from "./hexai-plugin";
-//# sourceMappingURL=index.d.ts.map
+declare function processContext(options: ProcessContextOptions): Promise<ProcessContextResult>;
+
+export { type AnalyzeOptions, Command, ConfigLoadError, ConfigLoader, ConfigurationError, ConsoleLogger, type ConsoleLoggerOptions, ContextConfig, type ContextMessages, type ContractsConfig, ContractsPipeline, DomainEvent, FileCopier, FileGraphResolver, FileNotFoundError, FileReadError, type FileStats, type FileSystem, FileSystemError, FileWriteError, type GenerateOptions, type InputContextConfig, JsonParseError, type LogLevel, type Logger, MessageParserError, ModuleResolutionError, ParseError, type ParseResult, type ParsedMessages, Parser, type PipelineDependencies, type PipelineOptions, type PipelineResult, type ProcessContextOptions, type ProcessContextResult, type ReexportFile, ReexportGenerator, type ReexportGeneratorOptions, RegistryGenerator, type RegistryGeneratorOptions, ResolutionError, type RewrittenImport, Scanner, type ScannerOptions, SourceFile, TypeDefinition, cliPlugin, nodeFileSystem, noopLogger, processContext };