@honestjs/rpc-plugin 1.5.0 → 1.6.0

package/dist/index.js

@@ -36,15 +36,18 @@ __export(index_exports, {
   GENERIC_TYPES: () => GENERIC_TYPES,
   LOG_PREFIX: () => LOG_PREFIX,
   RPCPlugin: () => RPCPlugin,
+  RPC_ARTIFACT_VERSION: () => RPC_ARTIFACT_VERSION,
   RouteAnalyzerService: () => RouteAnalyzerService,
   SchemaGeneratorService: () => SchemaGeneratorService,
   TypeScriptClientGenerator: () => TypeScriptClientGenerator,
+  assertRpcArtifact: () => assertRpcArtifact,
   buildFullApiPath: () => buildFullApiPath,
   buildFullPath: () => buildFullPath,
   camelCase: () => camelCase,
   computeHash: () => computeHash,
   extractNamedType: () => extractNamedType,
   generateTypeScriptInterface: () => generateTypeScriptInterface,
+  isRpcArtifact: () => isRpcArtifact,
   mapJsonSchemaTypeToTypeScript: () => mapJsonSchemaTypeToTypeScript,
   readChecksum: () => readChecksum,
   safeToString: () => safeToString,
@@ -63,6 +66,9 @@ var DEFAULT_OPTIONS = {
   tsConfigPath: "tsconfig.json",
   outputDir: "./generated/rpc",
   generateOnInit: true,
+  mode: "best-effort",
+  logLevel: "info",
+  artifactVersion: "1",
   context: {
     namespace: "rpc",
     keys: {
@@ -90,6 +96,16 @@ var GENERIC_TYPES = /* @__PURE__ */ new Set(["Array", "Promise", "Partial"]);
 var import_promises = __toESM(require("fs/promises"));
 var import_path = __toESM(require("path"));
 
+// src/utils/string-utils.ts
+function safeToString(value) {
+  if (typeof value === "string") return value;
+  if (typeof value === "symbol") return value.description || "Symbol";
+  return String(value);
+}
+function camelCase(str) {
+  return str.charAt(0).toLowerCase() + str.slice(1);
+}
+
 // src/utils/path-utils.ts
 function buildFullPath(basePath, parameters) {
   if (!basePath || typeof basePath !== "string") return "/";
@@ -128,14 +144,26 @@ function buildFullApiPath(route) {
   return fullPath || "/";
 }
 
-// src/utils/string-utils.ts
-function safeToString(value) {
-  if (typeof value === "string") return value;
-  if (typeof value === "symbol") return value.description || "Symbol";
-  return String(value);
+// src/generators/generator-utils.ts
+function groupRoutesByController(routes) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const route of routes) {
+    const controller = safeToString(route.controller);
+    if (!groups.has(controller)) {
+      groups.set(controller, []);
+    }
+    groups.get(controller).push(route);
+  }
+  return groups;
 }
-function camelCase(str) {
-  return str.charAt(0).toLowerCase() + str.slice(1);
+function buildNormalizedRequestPath(route) {
+  let requestPath = buildFullApiPath(route);
+  for (const parameter of route.parameters ?? []) {
+    if (parameter.decoratorType !== "param") continue;
+    const placeholder = `:${String(parameter.data ?? parameter.name)}`;
+    requestPath = requestPath.replace(placeholder, `:${parameter.name}`);
+  }
+  return requestPath;
 }
 
 // src/generators/typescript-client.generator.ts
@@ -176,7 +204,7 @@ var TypeScriptClientGenerator = class {
    * Generates the client TypeScript content with types included.
    */
   generateClientContent(routes, schemas) {
-    const controllerGroups = this.groupRoutesByController(routes);
+    const controllerGroups = groupRoutesByController(routes);
     return `// ============================================================================
 // TYPES SECTION
 // ============================================================================
@@ -337,13 +365,21 @@ export class ApiClient {
 				return undefined as T
 			}
 
-			const responseData = await response.json()
+			const contentType = response.headers.get('content-type') || ''
+			const isJson = contentType.includes('application/json') || contentType.includes('+json')
+			const responseData = isJson ? await response.json() : await response.text()
 
 			if (!response.ok) {
-				throw new ApiError(response.status, responseData.message || 'Request failed')
+				const message =
+					typeof responseData === 'object' && responseData && 'message' in (responseData as Record<string, unknown>)
+						? String((responseData as Record<string, unknown>).message)
+						: typeof responseData === 'string' && responseData.trim()
+							? responseData
+							: 'Request failed'
+				throw new ApiError(response.status, message)
 			}
 
-			return responseData
+			return responseData as T
 		} catch (error) {
 			if (error instanceof ApiError) {
 				throw error
@@ -412,14 +448,7 @@ ${this.generateControllerMethods(controllerGroups)}
         methods += "undefined";
         methods += `>) => {
 `;
-        let requestPath = buildFullApiPath(route);
-        if (pathParams.length > 0) {
-          for (const pathParam of pathParams) {
-            const paramName = pathParam.name;
-            const placeholder = `:${String(pathParam.data)}`;
-            requestPath = requestPath.replace(placeholder, `:${paramName}`);
-          }
-        }
+        const requestPath = buildNormalizedRequestPath(route);
         methods += `				return this.request<Result>('${httpMethod.toUpperCase()}', \`${requestPath}\`, options)
 `;
         methods += `			},
@@ -460,20 +489,6 @@ ${this.generateControllerMethods(controllerGroups)}
     }
     return content;
   }
-  /**
-   * Groups routes by controller for better organization.
-   */
-  groupRoutesByController(routes) {
-    const groups = /* @__PURE__ */ new Map();
-    for (const route of routes) {
-      const controller = safeToString(route.controller);
-      if (!groups.has(controller)) {
-        groups.set(controller, []);
-      }
-      groups.get(controller).push(route);
-    }
-    return groups;
-  }
   /**
    * Analyzes route parameters to determine their types and usage.
    */
@@ -523,13 +538,42 @@ async function writeChecksum(outputDir, data) {
   await (0, import_promises2.writeFile)(checksumPath, JSON.stringify(data, null, 2), "utf-8");
 }
 
+// src/utils/artifact-contract.ts
+var RPC_ARTIFACT_VERSION = "1";
+function isRpcArtifact(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const obj = value;
+  return typeof obj.artifactVersion === "string" && Array.isArray(obj.routes) && Array.isArray(obj.schemas);
+}
+function assertRpcArtifact(value) {
+  if (!isRpcArtifact(value)) {
+    throw new Error("Invalid RPC artifact: expected { artifactVersion, routes, schemas }");
+  }
+  if (value.artifactVersion !== RPC_ARTIFACT_VERSION) {
+    throw new Error(
+      `Unsupported RPC artifact version '${value.artifactVersion}'. Supported: ${RPC_ARTIFACT_VERSION}.`
+    );
+  }
+}
+
 // src/services/route-analyzer.service.ts
 var import_honestjs = require("honestjs");
 var RouteAnalyzerService = class {
+  customClassMatcher;
+  onWarn;
+  warnings = [];
+  constructor(options = {}) {
+    this.customClassMatcher = options.customClassMatcher;
+    this.onWarn = options.onWarn;
+  }
+  getWarnings() {
+    return this.warnings;
+  }
   /**
    * Analyzes controller methods to extract type information
    */
   async analyzeControllerMethods(project) {
+    this.warnings = [];
     const routes = import_honestjs.RouteRegistry.getRoutes();
     if (!routes?.length) {
       return [];
@@ -550,13 +594,20 @@ var RouteAnalyzerService = class {
       const classes = sourceFile.getClasses();
       for (const classDeclaration of classes) {
         const className = classDeclaration.getName();
-        if (className?.endsWith("Controller")) {
+        if (className && this.isControllerClass(classDeclaration, className)) {
           controllers.set(className, classDeclaration);
         }
       }
     }
     return controllers;
   }
+  isControllerClass(classDeclaration, _className) {
+    if (this.customClassMatcher) {
+      return this.customClassMatcher(classDeclaration);
+    }
+    const decoratorNames = classDeclaration.getDecorators().map((decorator) => decorator.getName());
+    return decoratorNames.includes("Controller") || decoratorNames.includes("View");
+  }
   /**
    * Processes all routes and extracts type information
    */
@@ -567,10 +618,9 @@ var RouteAnalyzerService = class {
         const extendedRoute = this.createExtendedRoute(route, controllers);
         analyzedRoutes.push(extendedRoute);
       } catch (routeError) {
-        console.warn(
-          `${LOG_PREFIX} Skipping route ${safeToString(route.controller)}.${safeToString(route.handler)}:`,
-          routeError
-        );
+        const warning = `Skipping route ${safeToString(route.controller)}.${safeToString(route.handler)}`;
+        this.warnings.push(warning);
+        this.onWarn?.(warning, routeError);
       }
     }
     return analyzedRoutes;
@@ -590,6 +640,10 @@ var RouteAnalyzerService = class {
         returns = this.getReturnType(handlerMethod);
         parameters = this.getParametersWithTypes(handlerMethod, route.parameters || []);
       }
+    } else {
+      const warning = `Controller class not found in source files: ${controllerName} (handler: ${handlerName})`;
+      this.warnings.push(warning);
+      this.onWarn?.(warning);
     }
     return {
       controller: controllerName,
@@ -728,14 +782,23 @@ function extractNamedType(type) {
 
 // src/services/schema-generator.service.ts
 var SchemaGeneratorService = class {
-  constructor(controllerPattern, tsConfigPath) {
+  constructor(controllerPattern, tsConfigPath, options = {}) {
     this.controllerPattern = controllerPattern;
     this.tsConfigPath = tsConfigPath;
+    this.failOnSchemaError = options.failOnSchemaError ?? false;
+    this.onWarn = options.onWarn;
+  }
+  failOnSchemaError;
+  onWarn;
+  warnings = [];
+  getWarnings() {
+    return this.warnings;
   }
   /**
    * Generates JSON schemas from types used in controllers
    */
   async generateSchemas(project) {
+    this.warnings = [];
     const sourceFiles = project.getSourceFiles(this.controllerPattern);
     const collectedTypes = this.collectTypesFromControllers(sourceFiles);
     return this.processTypes(collectedTypes);
@@ -782,7 +845,12 @@ var SchemaGeneratorService = class {
           typescriptType
         });
       } catch (err) {
-        console.error(`Failed to generate schema for ${typeName}:`, err);
+        if (this.failOnSchemaError) {
+          throw err;
+        }
+        const warning = `Failed to generate schema for ${typeName}`;
+        this.warnings.push(warning);
+        this.onWarn?.(warning, err);
       }
     }
     return schemas;
@@ -801,7 +869,12 @@ var SchemaGeneratorService = class {
       });
       return generator.createSchema(typeName);
     } catch (error) {
-      console.error(`Failed to generate schema for type ${typeName}:`, error);
+      if (this.failOnSchemaError) {
+        throw error;
+      }
+      const warning = `Failed to generate schema for type ${typeName}`;
+      this.warnings.push(warning);
+      this.onWarn?.(warning, error);
       return {
         type: "object",
         properties: {},
@@ -819,6 +892,11 @@ var RPCPlugin = class {
   generateOnInit;
   contextNamespace;
   contextArtifactKey;
+  mode;
+  logLevel;
+  failOnSchemaError;
+  failOnRouteAnalysisWarning;
+  customClassMatcher;
   // Services
   routeAnalyzer;
   schemaGenerator;
@@ -829,16 +907,28 @@ var RPCPlugin = class {
   analyzedRoutes = [];
   analyzedSchemas = [];
   generatedInfos = [];
+  diagnostics = null;
   app = null;
   constructor(options = {}) {
     this.controllerPattern = options.controllerPattern ?? DEFAULT_OPTIONS.controllerPattern;
     this.tsConfigPath = options.tsConfigPath ?? import_path3.default.resolve(process.cwd(), DEFAULT_OPTIONS.tsConfigPath);
     this.outputDir = options.outputDir ?? import_path3.default.resolve(process.cwd(), DEFAULT_OPTIONS.outputDir);
     this.generateOnInit = options.generateOnInit ?? DEFAULT_OPTIONS.generateOnInit;
+    this.mode = options.mode ?? DEFAULT_OPTIONS.mode;
+    this.logLevel = options.logLevel ?? DEFAULT_OPTIONS.logLevel;
     this.contextNamespace = options.context?.namespace ?? DEFAULT_OPTIONS.context.namespace;
     this.contextArtifactKey = options.context?.keys?.artifact ?? DEFAULT_OPTIONS.context.keys.artifact;
-    this.routeAnalyzer = new RouteAnalyzerService();
-    this.schemaGenerator = new SchemaGeneratorService(this.controllerPattern, this.tsConfigPath);
+    this.customClassMatcher = options.customClassMatcher;
+    this.failOnSchemaError = options.failOnSchemaError ?? this.mode === "strict";
+    this.failOnRouteAnalysisWarning = options.failOnRouteAnalysisWarning ?? this.mode === "strict";
+    this.routeAnalyzer = new RouteAnalyzerService({
+      customClassMatcher: this.customClassMatcher,
+      onWarn: (message, details) => this.logWarn(message, details)
+    });
+    this.schemaGenerator = new SchemaGeneratorService(this.controllerPattern, this.tsConfigPath, {
+      failOnSchemaError: this.failOnSchemaError,
+      onWarn: (message, details) => this.logWarn(message, details)
+    });
     this.generators = options.generators ?? [new TypeScriptClientGenerator(this.outputDir)];
     this.validateConfiguration();
   }
@@ -860,6 +950,12 @@ var RPCPlugin = class {
     if (!this.outputDir?.trim()) {
       errors.push("Output directory cannot be empty");
     }
+    if (!["strict", "best-effort"].includes(this.mode)) {
+      errors.push('Mode must be "strict" or "best-effort"');
+    }
+    if (!["silent", "error", "warn", "info", "debug"].includes(this.logLevel)) {
+      errors.push("logLevel must be one of: silent, error, warn, info, debug");
+    }
     if (!this.contextNamespace?.trim()) {
       errors.push("Context namespace cannot be empty");
     }
@@ -878,7 +974,7 @@ var RPCPlugin = class {
       throw new Error(`Configuration validation failed: ${errors.join(", ")}`);
     }
     this.log(
-      `Configuration validated: controllerPattern=${this.controllerPattern}, tsConfigPath=${this.tsConfigPath}, outputDir=${this.outputDir}`
+      `Configuration validated: controllerPattern=${this.controllerPattern}, tsConfigPath=${this.tsConfigPath}, outputDir=${this.outputDir}, mode=${this.mode}`
     );
   }
   /**
@@ -887,14 +983,17 @@ var RPCPlugin = class {
   afterModulesRegistered = async (app, hono) => {
     this.app = app;
     if (this.generateOnInit) {
-      await this.analyzeEverything();
+      await this.analyzeEverything({ force: false, dryRun: false });
       this.publishArtifact(app);
     }
   };
   /**
    * Main analysis method that coordinates all three components
    */
-  async analyzeEverything(force = false) {
+  async analyzeEverything(options) {
+    const { force, dryRun } = options;
+    const warnings = [];
+    let cacheState = force ? "bypass" : "miss";
     try {
       this.log("Starting comprehensive RPC analysis...");
       this.dispose();
@@ -906,21 +1005,50 @@ var RPCPlugin = class {
         const stored = readChecksum(this.outputDir);
         if (stored && stored.hash === currentHash && this.outputFilesExist()) {
           if (this.loadArtifactFromDisk()) {
-            this.log("Source files unchanged \u2014 skipping regeneration");
+            cacheState = "hit";
+            this.logDebug("Source files unchanged - skipping regeneration");
+            this.diagnostics = {
+              generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+              mode: this.mode,
+              dryRun,
+              cache: cacheState,
+              routesCount: this.analyzedRoutes.length,
+              schemasCount: this.analyzedSchemas.length,
+              warnings: []
+            };
             this.dispose();
             return;
           }
-          this.log("Source files unchanged but cached artifact missing/invalid \u2014 regenerating");
+          this.logDebug("Source files unchanged but cached artifact missing/invalid - regenerating");
         }
       }
       this.analyzedRoutes = [];
       this.analyzedSchemas = [];
       this.generatedInfos = [];
       this.analyzedRoutes = await this.routeAnalyzer.analyzeControllerMethods(this.project);
+      warnings.push(...this.routeAnalyzer.getWarnings());
       this.analyzedSchemas = await this.schemaGenerator.generateSchemas(this.project);
-      this.generatedInfos = await this.runGenerators();
-      await writeChecksum(this.outputDir, { hash: computeHash(filePaths), files: filePaths });
-      this.writeArtifactToDisk();
+      warnings.push(...this.schemaGenerator.getWarnings());
+      if (this.failOnRouteAnalysisWarning && this.routeAnalyzer.getWarnings().length > 0) {
+        throw new Error(`Route analysis warnings encountered in strict mode: ${this.routeAnalyzer.getWarnings().join("; ")}`);
+      }
+      if (!dryRun) {
+        this.generatedInfos = await this.runGenerators();
+      }
+      if (!dryRun) {
+        await writeChecksum(this.outputDir, { hash: computeHash(filePaths), files: filePaths });
+        this.writeArtifactToDisk();
+      }
+      this.diagnostics = {
+        generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        mode: this.mode,
+        dryRun,
+        cache: cacheState,
+        routesCount: this.analyzedRoutes.length,
+        schemasCount: this.analyzedSchemas.length,
+        warnings
+      };
+      this.writeDiagnosticsToDisk();
       this.log(
         `\u2705 RPC analysis complete: ${this.analyzedRoutes.length} routes, ${this.analyzedSchemas.length} schemas`
       );
@@ -930,13 +1058,10 @@ var RPCPlugin = class {
       throw error;
     }
   }
-  /**
-   * Manually trigger analysis (useful for testing or re-generation).
-   * Defaults to force=true to bypass cache; pass false to use caching.
-   */
-  async analyze(force = true) {
-    await this.analyzeEverything(force);
-    if (this.app) {
+  async analyze(forceOrOptions = true) {
+    const options = typeof forceOrOptions === "boolean" ? { force: forceOrOptions, dryRun: false } : { force: forceOrOptions.force ?? true, dryRun: forceOrOptions.dryRun ?? false };
+    await this.analyzeEverything(options);
+    if (this.app && !options.dryRun) {
       this.publishArtifact(this.app);
     }
   }
@@ -964,6 +1089,9 @@ var RPCPlugin = class {
   getGenerationInfos() {
     return this.generatedInfos;
   }
+  getDiagnostics() {
+    return this.diagnostics;
+  }
   /**
    * Checks whether expected output files exist on disk
    */
@@ -979,23 +1107,38 @@ var RPCPlugin = class {
   getArtifactPath() {
     return import_path3.default.join(this.outputDir, "rpc-artifact.json");
   }
+  getDiagnosticsPath() {
+    return import_path3.default.join(this.outputDir, "rpc-diagnostics.json");
+  }
   writeArtifactToDisk() {
     const artifact = {
+      artifactVersion: RPC_ARTIFACT_VERSION,
       routes: this.analyzedRoutes,
       schemas: this.analyzedSchemas
     };
     import_fs2.default.mkdirSync(this.outputDir, { recursive: true });
     import_fs2.default.writeFileSync(this.getArtifactPath(), JSON.stringify(artifact));
   }
+  writeDiagnosticsToDisk() {
+    if (!this.diagnostics) return;
+    import_fs2.default.mkdirSync(this.outputDir, { recursive: true });
+    import_fs2.default.writeFileSync(this.getDiagnosticsPath(), JSON.stringify(this.diagnostics, null, 2));
+  }
   loadArtifactFromDisk() {
     try {
       const raw = import_fs2.default.readFileSync(this.getArtifactPath(), "utf8");
       const parsed = JSON.parse(raw);
-      if (!Array.isArray(parsed.routes) || !Array.isArray(parsed.schemas)) {
-        return false;
+      if (parsed.artifactVersion === void 0) {
+        if (!Array.isArray(parsed.routes) || !Array.isArray(parsed.schemas)) {
+          return false;
+        }
+        this.analyzedRoutes = parsed.routes;
+        this.analyzedSchemas = parsed.schemas;
+      } else {
+        assertRpcArtifact(parsed);
+        this.analyzedRoutes = parsed.routes;
+        this.analyzedSchemas = parsed.schemas;
       }
-      this.analyzedRoutes = parsed.routes;
-      this.analyzedSchemas = parsed.schemas;
       this.generatedInfos = [];
       return true;
     } catch {
@@ -1020,6 +1163,7 @@ var RPCPlugin = class {
   }
   publishArtifact(app) {
     app.getContext().set(this.getArtifactContextKey(), {
+      artifactVersion: RPC_ARTIFACT_VERSION,
       routes: this.analyzedRoutes,
       schemas: this.analyzedSchemas
     });
@@ -1043,13 +1187,37 @@ var RPCPlugin = class {
    * Logs a message with the plugin prefix
    */
   log(message) {
-    console.log(`${LOG_PREFIX} ${message}`);
+    if (this.canLog("info")) {
+      console.log(`${LOG_PREFIX} ${message}`);
+    }
   }
   /**
    * Logs an error with the plugin prefix
    */
   logError(message, error) {
-    console.error(`${LOG_PREFIX} ${message}`, error || "");
+    if (this.canLog("error")) {
+      console.error(`${LOG_PREFIX} ${message}`, error || "");
+    }
+  }
+  logWarn(message, details) {
+    if (this.canLog("warn")) {
+      console.warn(`${LOG_PREFIX} ${message}`, details || "");
+    }
+  }
+  logDebug(message) {
+    if (this.canLog("debug")) {
+      console.log(`${LOG_PREFIX} ${message}`);
+    }
+  }
+  canLog(level) {
+    const order = {
+      silent: 0,
+      error: 1,
+      warn: 2,
+      info: 3,
+      debug: 4
+    };
+    return order[this.logLevel] >= order[level];
   }
 };
 // Annotate the CommonJS export names for ESM import in node:
@@ -1060,15 +1228,18 @@ var RPCPlugin = class {
   GENERIC_TYPES,
   LOG_PREFIX,
   RPCPlugin,
+  RPC_ARTIFACT_VERSION,
   RouteAnalyzerService,
   SchemaGeneratorService,
   TypeScriptClientGenerator,
+  assertRpcArtifact,
   buildFullApiPath,
   buildFullPath,
   camelCase,
   computeHash,
   extractNamedType,
   generateTypeScriptInterface,
+  isRpcArtifact,
   mapJsonSchemaTypeToTypeScript,
   readChecksum,
   safeToString,