@hexaijs/plugin-contracts-generator 0.2.0 → 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,20 +127,30 @@ 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",
-        },
     },
 };
 ```
@@ -208,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
@@ -255,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

package/dist/{cli-CPg-O4OY.d.ts → cli-DajurpEQ.d.ts}

@@ -176,6 +176,74 @@ 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.
  */
@@ -189,12 +257,7 @@ interface RunWithConfigOptions {
  * This is the config passed from hexai.config.ts.
  */
 interface ContractsPluginConfig {
-    contexts: Array<{
-        name: string;
-        path: string;
-        sourceDir?: string;
-        tsconfigPath?: string;
-    }>;
+    contexts: Array<string | InputContextConfig>;
     pathAliasRewrites?: Record<string, string>;
     externalDependencies?: Record<string, string>;
     decoratorNames?: DecoratorNames;
@@ -211,4 +274,4 @@ declare function run(args: string[]): Promise<void>;
  */
 declare function runWithConfig(options: RunWithConfigOptions, pluginConfig: ContractsPluginConfig): Promise<void>;
 
-export { type ArrayType as A, isObjectType as B, type Command as C, type DecoratorNames as D, type EnumDefinition as E, type Field as F, isPrimitiveType as G, isReferenceType as H, type ImportSource as I, isTupleType as J, isUnionType as K, type LiteralType as L, type MessageType as M, type RunWithConfigOptions 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, run as V, runWithConfig as W, type DomainEvent as a, type ContractsPluginConfig as b, type ClassDefinition as c, type ClassImport as d, type Config as e, type Dependency as f, type DependencyKind as g, type EnumMember as h, type ExtractionError as i, type ExtractionResult as j, type ExtractionWarning as k, type FunctionParameter as l, type FunctionType as m, type IntersectionType as n, type Message as o, type MessageBase as p, type ReferenceType as q, type TupleType as r, type TypeDefinitionKind as s, type TypeRef as t, isArrayType as u, isCommand as v, isDomainEvent as w, isFunctionType as x, isIntersectionType as y, isLiteralType as z };
+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,2 +1,2 @@
 #!/usr/bin/env node
-export { b as ContractsPluginConfig, N as RunWithConfigOptions, V as run, W as runWithConfig } from './cli-CPg-O4OY.js';
+export { c as ContractsPluginConfig, Z as RunWithConfigOptions, _ as run, $ as runWithConfig } from './cli-DajurpEQ.js';

package/dist/cli.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 import { fileURLToPath } from 'url';
 import * as path from 'path';
-import path__default, { resolve, dirname, basename, relative, join } from 'path';
+import path__default, { resolve, dirname, join, relative, basename } from 'path';
 import * as ts8 from 'typescript';
 import ts8__default from 'typescript';
 import { readFile, readdir, writeFile, mkdir, access, stat } from 'fs/promises';
 import { constants } from 'fs';
-import 'reflect-metadata';
+import '@hexaijs/contracts/decorators';
 import { glob } from 'glob';
 import { minimatch } from 'minimatch';
 
@@ -233,6 +233,90 @@ var ContextConfig = class _ContextConfig {
 
 // src/config-loader.ts
 var SUPPORTED_GLOB_PARTS_COUNT = 2;
+async function resolveContextEntries(entries, configDir, fs = nodeFileSystem) {
+  const contexts = [];
+  for (let i = 0; i < entries.length; i++) {
+    const item = entries[i];
+    if (typeof item === "string") {
+      const resolved = await resolveStringEntry(item, configDir, fs);
+      contexts.push(...resolved);
+    } else {
+      const contextConfig = await createObjectContext(item, i, configDir, fs);
+      contexts.push(contextConfig);
+    }
+  }
+  return contexts;
+}
+async function resolveStringEntry(contextPath, configDir, fs) {
+  if (contextPath.includes("*")) {
+    return expandGlobPattern(contextPath, configDir, fs);
+  }
+  const basePath = resolve(configDir, contextPath);
+  const name = basename(basePath);
+  return [await ContextConfig.create(
+    { name, path: contextPath },
+    configDir,
+    fs
+  )];
+}
+async function expandGlobPattern(pattern, configDir, fs) {
+  const packageDirs = await matchGlobPattern(pattern, configDir, fs);
+  return Promise.all(
+    packageDirs.map((dir) => {
+      const name = basename(dir);
+      const relativePath = relative(configDir, dir);
+      return ContextConfig.create(
+        { name, path: relativePath },
+        configDir,
+        fs
+      );
+    })
+  );
+}
+async function createObjectContext(ctx, index, configDir, fs) {
+  if (!ctx.name || typeof ctx.name !== "string") {
+    throw new ConfigLoadError(
+      `Invalid context at index ${index}: missing 'name'`
+    );
+  }
+  if (!ctx.path || typeof ctx.path !== "string") {
+    throw new ConfigLoadError(
+      `Invalid context at index ${index}: missing 'path'`
+    );
+  }
+  return ContextConfig.create(ctx, configDir, fs);
+}
+async function matchGlobPattern(pattern, configDir, fs) {
+  const globParts = pattern.split("*");
+  if (globParts.length !== SUPPORTED_GLOB_PARTS_COUNT) {
+    throw new ConfigLoadError(
+      `Invalid glob pattern: "${pattern}". Only single wildcard patterns like "packages/*" are supported.`
+    );
+  }
+  const [prefix, suffix] = globParts;
+  const baseDir = resolve(configDir, prefix);
+  if (!await fs.exists(baseDir)) {
+    return [];
+  }
+  const entries = await fs.readdir(baseDir);
+  const matchedDirs = [];
+  for (const entry of entries) {
+    const fullPath = resolve(baseDir, entry);
+    const stats = await fs.stat(fullPath);
+    if (!stats.isDirectory()) {
+      continue;
+    }
+    if (suffix) {
+      const suffixPath = resolve(fullPath, suffix.replace(/^\//, ""));
+      if (await fs.exists(suffixPath)) {
+        matchedDirs.push(fullPath);
+      }
+    } else {
+      matchedDirs.push(fullPath);
+    }
+  }
+  return matchedDirs.sort();
+}
 var ConfigLoader = class {
   fs;
   constructor(options = {}) {
@@ -265,7 +349,7 @@ var ConfigLoader = class {
     if (!contracts.contexts || !Array.isArray(contracts.contexts)) {
       throw new ConfigLoadError("Missing 'contracts.contexts' in config");
     }
-    const contexts = await this.resolveContexts(contracts.contexts, configDir);
+    const contexts = await resolveContextEntries(contracts.contexts, configDir, this.fs);
     if (contexts.length === 0) {
       throw new ConfigLoadError("No contexts found from 'contexts'");
     }
@@ -279,90 +363,6 @@ var ConfigLoader = class {
       removeDecorators: contracts.removeDecorators ?? true
     };
   }
-  async resolveContexts(contextsConfig, configDir) {
-    const contexts = [];
-    for (let i = 0; i < contextsConfig.length; i++) {
-      const item = contextsConfig[i];
-      if (typeof item === "string") {
-        const resolvedContexts = await this.resolveStringContext(item, configDir);
-        contexts.push(...resolvedContexts);
-      } else {
-        const contextConfig = await this.createObjectContext(item, i, configDir);
-        contexts.push(contextConfig);
-      }
-    }
-    return contexts;
-  }
-  async resolveStringContext(contextPath, configDir) {
-    if (contextPath.includes("*")) {
-      return this.expandGlobPattern(contextPath, configDir);
-    }
-    const basePath = resolve(configDir, contextPath);
-    const name = basename(basePath);
-    return [await ContextConfig.create(
-      { name, path: contextPath },
-      configDir,
-      this.fs
-    )];
-  }
-  async expandGlobPattern(pattern, configDir) {
-    const packageDirs = await this.matchGlobPattern(pattern, configDir);
-    return Promise.all(
-      packageDirs.map((dir) => {
-        const name = basename(dir);
-        const relativePath = relative(configDir, dir);
-        return ContextConfig.create(
-          { name, path: relativePath },
-          configDir,
-          this.fs
-        );
-      })
-    );
-  }
-  async createObjectContext(ctx, index, configDir) {
-    if (!ctx.name || typeof ctx.name !== "string") {
-      throw new ConfigLoadError(
-        `Invalid context at index ${index}: missing 'name'`
-      );
-    }
-    if (!ctx.path || typeof ctx.path !== "string") {
-      throw new ConfigLoadError(
-        `Invalid context at index ${index}: missing 'path'`
-      );
-    }
-    return ContextConfig.create(ctx, configDir, this.fs);
-  }
-  async matchGlobPattern(pattern, configDir) {
-    const globParts = pattern.split("*");
-    if (globParts.length !== SUPPORTED_GLOB_PARTS_COUNT) {
-      throw new ConfigLoadError(
-        `Invalid glob pattern: "${pattern}". Only single wildcard patterns like "packages/*" are supported.`
-      );
-    }
-    const [prefix, suffix] = globParts;
-    const baseDir = resolve(configDir, prefix);
-    if (!await this.fs.exists(baseDir)) {
-      return [];
-    }
-    const entries = await this.fs.readdir(baseDir);
-    const matchedDirs = [];
-    for (const entry of entries) {
-      const fullPath = resolve(baseDir, entry);
-      const stats = await this.fs.stat(fullPath);
-      if (!stats.isDirectory()) {
-        continue;
-      }
-      if (suffix) {
-        const suffixPath = resolve(fullPath, suffix.replace(/^\//, ""));
-        if (await this.fs.exists(suffixPath)) {
-          matchedDirs.push(fullPath);
-        }
-      } else {
-        matchedDirs.push(fullPath);
-      }
-    }
-    return matchedDirs.sort();
-  }
 };
 var DEFAULT_EXCLUDE_PATTERNS = [
   "**/node_modules/**",
@@ -2360,9 +2360,12 @@ Config file format:
   export default {
     contracts: {
       contexts: [
+        "packages/*",                    // glob: auto-discover all contexts
+        "packages/auth",                 // string: name inferred from directory
         {
           name: "lecture",
-          sourceDir: "packages/lecture/src",
+          path: "packages/lecture",       // required: base directory
+          sourceDir: "src",              // optional, default: "src"
         },
       ],
       pathAliasRewrites: {
@@ -2448,19 +2451,10 @@ async function run(args) {
   }
 }
 async function toContractsConfig(pluginConfig) {
-  const contexts = await Promise.all(
-    pluginConfig.contexts.map(
-      (ctx) => ContextConfig.create(
-        {
-          name: ctx.name,
-          path: ctx.path,
-          sourceDir: ctx.sourceDir,
-          tsconfigPath: ctx.tsconfigPath
-        },
-        process.cwd(),
-        nodeFileSystem
-      )
-    )
+  const contexts = await resolveContextEntries(
+    pluginConfig.contexts,
+    process.cwd(),
+    nodeFileSystem
   );
   return {
     contexts,