@hexaijs/plugin-contracts-generator 0.1.1 → 0.2.1

package/README.md

@@ -30,14 +30,14 @@ npm install @hexaijs/plugin-contracts-generator
 The package provides three decorators that mark messages for extraction. These decorators have **no runtime overhead** - they simply tag classes for discovery during the build process.
 
 ```typescript
-import { PublicEvent, PublicCommand, PublicQuery } from "@hexaijs/plugin-contracts-generator/decorators";
+import { PublicEvent, PublicCommand, PublicQuery } from "@hexaijs/contracts/decorators";
 ```
 
 **@PublicEvent()** - Marks a domain event as part of the public contract:
 
 ```typescript
 import { DomainEvent } from "@hexaijs/core";
-import { PublicEvent } from "@hexaijs/plugin-contracts-generator/decorators";
+import { PublicEvent } from "@hexaijs/contracts/decorators";
 
 @PublicEvent()
 export class OrderPlaced extends DomainEvent<{
@@ -52,7 +52,7 @@ export class OrderPlaced extends DomainEvent<{
 **@PublicCommand()** - Marks a command as part of the public contract:
 
 ```typescript
-import { PublicCommand } from "@hexaijs/plugin-contracts-generator/decorators";
+import { PublicCommand } from "@hexaijs/contracts/decorators";
 
 @PublicCommand()
 export class CreateOrderRequest extends BaseRequest<{
@@ -70,7 +70,7 @@ export type CreateOrderResponse = {
 **@PublicQuery()** - Marks a query as part of the public contract:
 
 ```typescript
-import { PublicQuery } from "@hexaijs/plugin-contracts-generator/decorators";
+import { PublicQuery } from "@hexaijs/contracts/decorators";
 
 @PublicQuery({ response: "OrderDetails" })
 export class GetOrderQuery extends BaseRequest<{
@@ -101,21 +101,16 @@ export default {
         contexts: [
             {
                 name: "order",
-                sourceDir: "packages/order/src",
-                tsconfigPath: "packages/order/tsconfig.json", // optional
+                path: "packages/order",
+                tsconfigPath: "tsconfig.json", // optional, relative to path
             },
             {
                 name: "inventory",
-                sourceDir: "packages/inventory/src",
+                path: "packages/inventory",
+                sourceDir: "lib", // optional, defaults to "src"
             },
         ],
 
-        // Output package configuration (required)
-        outputPackage: {
-            name: "@myorg/contracts",
-            dir: "packages/contracts",
-        },
-
         // Path alias rewrite rules (optional)
         pathAliasRewrites: {
             "@myorg/": "@/",
@@ -132,25 +127,38 @@ export default {
             { messageSuffix: "Query", responseSuffix: "QueryResult" },
             { messageSuffix: "Request", responseSuffix: "Response" },
         ],
+
+        // Custom decorator names (optional, defaults shown)
+        decoratorNames: {
+            event: "PublicEvent",
+            command: "PublicCommand",
+            query: "PublicQuery",
+        },
+
+        // Strip decorators from generated output (optional, default: true)
+        removeDecorators: true,
     },
 };
 ```
 
+Each context requires `name` and `path`. The `path` is the base directory of the context (relative to the config file). Within that directory:
+- `sourceDir` defaults to `"src"` (resolved relative to `path`)
+- `tsconfigPath` defaults to `"tsconfig.json"` (resolved relative to `path`)
+
 For monorepos with many packages, use glob patterns to auto-discover contexts:
 
 ```typescript
 export default {
     contracts: {
         contexts: ["packages/*"],  // Matches all directories under packages/
-        outputPackage: {
-            name: "@myorg/contracts",
-            dir: "packages/contracts",
-        },
     },
 };
 ```
 
-Each matched package must have its own `application.config.ts` with `contextName` and `sourceDir`.
+Each matched directory is treated as a context with sensible defaults:
+- Context name = directory name (e.g., `packages/auth` → `auth`)
+- Source directory = `src/` (default)
+- TypeScript config = `tsconfig.json` (auto-detected if exists)
 
 ### Response Types
 
@@ -205,17 +213,19 @@ The generator handles two types of files differently:
 Run the generator from your monorepo root:
 
 ```bash
-# Uses application.config.ts by default
-npx contracts-generator
+# Required: --output-dir (-o) specifies where contracts are generated
+npx contracts-generator --output-dir packages/contracts/src
 
-# Specify config file path
-npx contracts-generator --config ./application.config.ts
+# Specify config file path (default: application.config.ts)
+npx contracts-generator -o packages/contracts/src --config ./app.config.ts
 
 # Filter by message types
-npx contracts-generator -m event           # Extract only events
-npx contracts-generator -m command         # Extract only commands
-npx contracts-generator -m query           # Extract only queries
-npx contracts-generator -m event,command   # Extract events and commands
+npx contracts-generator -o packages/contracts/src -m event           # Extract only events
+npx contracts-generator -o packages/contracts/src -m command         # Extract only commands
+npx contracts-generator -o packages/contracts/src -m event,command   # Extract events and commands
+
+# Generate with message registry (index.ts)
+npx contracts-generator -o packages/contracts/src --generate-message-registry
 ```
 
 ### Programmatic API
@@ -252,6 +262,7 @@ contracts/
 │   ├── {context}/
 │   │   ├── events.ts
 │   │   ├── commands.ts
+│   │   ├── queries.ts
 │   │   ├── types.ts       # Dependent types + Response types
 │   │   └── index.ts       # Barrel exports
 │   └── index.ts           # Namespace exports + MessageRegistry
@@ -313,7 +324,7 @@ try {
 **Error hierarchy:**
 
 - `MessageParserError` (base)
-  - `ConfigurationError` → `ConfigLoadError`, `TsconfigLoadError`
+  - `ConfigurationError` → `ConfigLoadError`
   - `FileSystemError` → `FileNotFoundError`, `FileReadError`, `FileWriteError`
   - `ParseError` → `JsonParseError`
   - `ResolutionError` → `ModuleResolutionError`

package/dist/cli-DajurpEQ.d.ts

@@ -0,0 +1,277 @@
+interface SourceFile {
+    readonly absolutePath: string;
+    readonly relativePath: string;
+    readonly packageName?: string;
+}
+type TypeRef = PrimitiveType | ArrayType | ObjectType | UnionType | IntersectionType | ReferenceType | LiteralType | TupleType | FunctionType;
+interface PrimitiveType {
+    readonly kind: 'primitive';
+    readonly name: 'string' | 'number' | 'boolean' | 'null' | 'undefined' | 'void' | 'any' | 'unknown' | 'never' | 'bigint' | 'symbol';
+}
+interface ArrayType {
+    readonly kind: 'array';
+    readonly elementType: TypeRef;
+}
+interface ObjectType {
+    readonly kind: 'object';
+    readonly fields: readonly Field[];
+}
+interface UnionType {
+    readonly kind: 'union';
+    readonly types: readonly TypeRef[];
+}
+interface IntersectionType {
+    readonly kind: 'intersection';
+    readonly types: readonly TypeRef[];
+}
+interface ReferenceType {
+    readonly kind: 'reference';
+    readonly name: string;
+    readonly typeArguments?: readonly TypeRef[];
+}
+interface LiteralType {
+    readonly kind: 'literal';
+    readonly value: string | number | boolean;
+}
+interface TupleType {
+    readonly kind: 'tuple';
+    readonly elements: readonly TypeRef[];
+}
+interface FunctionType {
+    readonly kind: 'function';
+    readonly parameters: readonly FunctionParameter[];
+    readonly returnType: TypeRef;
+}
+interface FunctionParameter {
+    readonly name: string;
+    readonly type: TypeRef;
+    readonly optional: boolean;
+}
+interface Field {
+    readonly name: string;
+    readonly type: TypeRef;
+    readonly optional: boolean;
+    readonly readonly: boolean;
+}
+type TypeDefinitionKind = 'interface' | 'type' | 'enum' | 'class';
+interface TypeDefinition {
+    readonly name: string;
+    readonly kind: TypeDefinitionKind;
+    readonly sourceFile: SourceFile;
+    readonly body: TypeRef;
+    readonly typeParameters?: readonly string[];
+    readonly exported: boolean;
+}
+interface EnumMember {
+    readonly name: string;
+    readonly value?: string | number;
+}
+interface EnumDefinition extends Omit<TypeDefinition, 'kind' | 'body'> {
+    readonly kind: 'enum';
+    readonly members: readonly EnumMember[];
+}
+interface ClassImport {
+    readonly names: readonly string[];
+    readonly source: string;
+    readonly isTypeOnly: boolean;
+    readonly isExternal: boolean;
+}
+interface ClassDefinition {
+    readonly name: string;
+    readonly kind: 'class';
+    readonly sourceFile: SourceFile;
+    readonly sourceText: string;
+    readonly imports: readonly ClassImport[];
+    readonly dependencies: readonly string[];
+    readonly baseClass?: string;
+    readonly exported: boolean;
+}
+interface MessageBase {
+    readonly name: string;
+    readonly sourceFile: SourceFile;
+    readonly fields: readonly Field[];
+    readonly baseClass?: string;
+    readonly sourceText: string;
+    readonly imports: readonly ClassImport[];
+}
+interface DomainEvent extends MessageBase {
+    readonly messageType: 'event';
+    readonly version?: number;
+    readonly context?: string;
+    readonly payloadType?: TypeRef;
+}
+interface Command extends MessageBase {
+    readonly messageType: 'command';
+    readonly resultType?: TypeRef;
+    readonly context?: string;
+    readonly payloadType?: TypeRef;
+}
+interface Query extends MessageBase {
+    readonly messageType: 'query';
+    readonly resultType?: TypeRef;
+    readonly context?: string;
+    readonly payloadType?: TypeRef;
+}
+type Message = DomainEvent | Command | Query;
+/** Used to filter which decorators the scanner should look for. */
+type MessageType = Message['messageType'];
+type ImportSource = {
+    readonly type: 'local';
+    readonly path: string;
+} | {
+    readonly type: 'external';
+    readonly package: string;
+};
+type DependencyKind = 'type' | 'value' | 'class';
+interface Dependency {
+    readonly name: string;
+    readonly source: ImportSource;
+    readonly kind: DependencyKind;
+    readonly definition?: TypeDefinition;
+}
+interface SourceLocation {
+    readonly file: string;
+    readonly message: string;
+    readonly line?: number;
+    readonly column?: number;
+}
+type ExtractionError = SourceLocation;
+type ExtractionWarning = SourceLocation;
+interface ExtractionResult {
+    readonly events: readonly DomainEvent[];
+    readonly commands: readonly Command[];
+    readonly types: readonly TypeDefinition[];
+    readonly dependencies: readonly Dependency[];
+    readonly errors: readonly ExtractionError[];
+    readonly warnings: readonly ExtractionWarning[];
+}
+/** Customizes decorator names used to identify public messages. Unspecified names use defaults. */
+interface DecoratorNames {
+    event?: string;
+    command?: string;
+    query?: string;
+}
+interface ResponseNamingConvention {
+    readonly messageSuffix: string;
+    readonly responseSuffix: string;
+}
+interface Config {
+    readonly sourceDir: string;
+    readonly outputDir: string;
+    readonly include?: readonly string[];
+    readonly exclude?: readonly string[];
+    readonly externalPackages?: Readonly<Record<string, string>>;
+    readonly decoratorNames?: DecoratorNames;
+    readonly responseNamingConventions?: readonly ResponseNamingConvention[];
+}
+declare function isPrimitiveType(type: TypeRef): type is PrimitiveType;
+declare function isArrayType(type: TypeRef): type is ArrayType;
+declare function isObjectType(type: TypeRef): type is ObjectType;
+declare function isUnionType(type: TypeRef): type is UnionType;
+declare function isIntersectionType(type: TypeRef): type is IntersectionType;
+declare function isReferenceType(type: TypeRef): type is ReferenceType;
+declare function isLiteralType(type: TypeRef): type is LiteralType;
+declare function isTupleType(type: TypeRef): type is TupleType;
+declare function isFunctionType(type: TypeRef): type is FunctionType;
+declare function isDomainEvent(message: Message): message is DomainEvent;
+declare function isCommand(message: Message): message is Command;
+
+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 InputContextConfig {
+    readonly name: string;
+    readonly path: string;
+    readonly sourceDir?: string;
+    readonly tsconfigPath?: string;
+    readonly responseNamingConventions?: readonly ResponseNamingConvention[];
+}
+/**
+ * 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;
+}
+
+/**
+ * Options for runWithConfig when config is provided directly.
+ */
+interface RunWithConfigOptions {
+    outputDir: string;
+    messageTypes?: MessageType[];
+    generateMessageRegistry?: boolean;
+}
+/**
+ * Plugin configuration structure for contracts generator.
+ * This is the config passed from hexai.config.ts.
+ */
+interface ContractsPluginConfig {
+    contexts: Array<string | InputContextConfig>;
+    pathAliasRewrites?: Record<string, string>;
+    externalDependencies?: Record<string, string>;
+    decoratorNames?: DecoratorNames;
+    responseNamingConventions?: ResponseNamingConvention[];
+    removeDecorators?: boolean;
+}
+declare function run(args: string[]): Promise<void>;
+/**
+ * Run contracts generator with config provided directly.
+ * This is used by the hexai CLI integration where config comes from hexai.config.ts.
+ *
+ * @param options - CLI options (outputDir, messageTypes, generateMessageRegistry)
+ * @param pluginConfig - Plugin configuration from hexai.config.ts
+ */
+declare function runWithConfig(options: RunWithConfigOptions, pluginConfig: ContractsPluginConfig): Promise<void>;
+
+export { runWithConfig as $, type ArrayType as A, isDomainEvent as B, type Command as C, type DecoratorNames as D, type EnumDefinition as E, type FileSystem as F, isFunctionType as G, isIntersectionType as H, type InputContextConfig as I, isLiteralType as J, isObjectType as K, type LiteralType as L, type MessageType as M, isPrimitiveType as N, type ObjectType as O, type PrimitiveType as P, type Query as Q, type ResponseNamingConvention as R, type SourceFile as S, type TypeDefinition as T, type UnionType as U, isReferenceType as V, isTupleType as W, isUnionType as X, nodeFileSystem as Y, type RunWithConfigOptions as Z, run as _, type DomainEvent as a, ContextConfig as b, type ContractsPluginConfig as c, type ClassDefinition as d, type ClassImport as e, type Config as f, type Dependency as g, type DependencyKind as h, type EnumMember as i, type ExtractionError as j, type ExtractionResult as k, type ExtractionWarning as l, type Field as m, type FileStats as n, type FunctionParameter as o, type FunctionType as p, type ImportSource as q, type IntersectionType as r, type Message as s, type MessageBase as t, type ReferenceType as u, type TupleType as v, type TypeDefinitionKind as w, type TypeRef as x, isArrayType as y, isCommand as z };

package/dist/cli.d.ts

@@ -1,36 +1,2 @@
 #!/usr/bin/env node
-import type { MessageType, DecoratorNames, ResponseNamingConvention } from "./domain/types";
-/**
- * Options for runWithConfig when config is provided directly.
- */
-export interface RunWithConfigOptions {
-    outputDir: string;
-    messageTypes?: MessageType[];
-    generateMessageRegistry?: boolean;
-}
-/**
- * Plugin configuration structure for contracts generator.
- * This is the config passed from hexai.config.ts.
- */
-export interface ContractsPluginConfig {
-    contexts: Array<{
-        name: string;
-        sourceDir: string;
-        tsconfigPath?: string;
-    }>;
-    pathAliasRewrites?: Record<string, string>;
-    externalDependencies?: Record<string, string>;
-    decoratorNames?: DecoratorNames;
-    responseNamingConventions?: ResponseNamingConvention[];
-    removeDecorators?: boolean;
-}
-export declare function run(args: string[]): Promise<void>;
-/**
- * Run contracts generator with config provided directly.
- * This is used by the hexai CLI integration where config comes from hexai.config.ts.
- *
- * @param options - CLI options (outputDir, messageTypes, generateMessageRegistry)
- * @param pluginConfig - Plugin configuration from hexai.config.ts
- */
-export declare function runWithConfig(options: RunWithConfigOptions, pluginConfig: ContractsPluginConfig): Promise<void>;
-//# sourceMappingURL=cli.d.ts.map
+export { c as ContractsPluginConfig, Z as RunWithConfigOptions, _ as run, $ as runWithConfig } from './cli-DajurpEQ.js';