@ic-reactor/codegen 0.4.0 → 0.5.0

package/README.md

@@ -0,0 +1,45 @@
+# @ic-reactor/codegen
+
+> shared code generation pipeline and utilities for IC Reactor.
+
+This package contains the core machinery for generating TypeScript declarations, reactor instances, and client managers from Candid files. It is primarily used by:
+
+- **`@ic-reactor/cli`**: For manual/CLI-based generation
+- **`@ic-reactor/vite-plugin`**: For automatic build-time generation
+
+## API
+
+The main entry point is the `runCanisterPipeline` function, which orchestrates the generation process.
+
+```typescript
+import { runCanisterPipeline } from "@ic-reactor/codegen"
+
+await runCanisterPipeline({
+  canisterConfig: {
+    name: "backend",
+    didFile: "./backend.did",
+  },
+  projectRoot: process.cwd(),
+  globalConfig: {
+    outDir: "src/declarations",
+    clientManagerPath: "../../clients",
+  },
+})
+```
+
+## Generators
+
+You can also use individual generators if you need more granular control:
+
+- **`generateDeclarations`**: Generates `.js` (factory), `.d.ts` (types), and `.did` copy.
+- **`generateReactorFile`**: Generates the `index.ts` file with `DisplayReactor` and hooks.
+- **`generateClientFile`**: Generates a `ClientManager` boilerplate file.
+
+## Utilities
+
+- **`parseDIDFile`**: Parses a `.did` file and extracts method signatures.
+- **`toPascalCase` / `toCamelCase`**: Naming helpers.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -31,45 +31,38 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   declarationsExist: () => declarationsExist,
+  extractMethods: () => extractMethods,
   generateClientFile: () => generateClientFile,
   generateDeclarations: () => generateDeclarations,
   generateReactorFile: () => generateReactorFile,
   getReactorName: () => getReactorName,
   getServiceTypeName: () => getServiceTypeName,
+  parseDIDFile: () => parseDIDFile,
+  runCanisterPipeline: () => runCanisterPipeline,
   toPascalCase: () => toPascalCase
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/naming.ts
-var import_change_case = require("change-case");
-function toPascalCase(str) {
-  return (0, import_change_case.pascalCase)(str);
-}
-function toCamelCase(str) {
-  return (0, import_change_case.camelCase)(str);
-}
-function getReactorName(canisterName) {
-  return `${toCamelCase(canisterName)}Reactor`;
-}
-function getServiceTypeName(canisterName) {
-  return `${toPascalCase(canisterName)}Service`;
-}
+// src/pipeline.ts
+var import_node_fs2 = __toESM(require("fs"), 1);
+var import_node_path3 = __toESM(require("path"), 1);
 
-// src/bindgen.ts
+// src/generators/declarations.ts
 var import_parser = require("@ic-reactor/parser");
 var import_node_path = __toESM(require("path"), 1);
 var import_node_fs = __toESM(require("fs"), 1);
 async function generateDeclarations(options) {
-  const { didFile, outDir } = options;
+  const { didFile, outDir, canisterName } = options;
   if (!import_node_fs.default.existsSync(didFile)) {
     return {
       success: false,
       declarationsDir: "",
+      files: [],
       error: `DID file not found: ${didFile}`
     };
   }
   const declarationsDir = import_node_path.default.join(outDir, "declarations");
-  const didFileName = import_node_path.default.basename(didFile);
+  const baseName = import_node_path.default.basename(didFile, ".did");
   try {
     const didContent = import_node_fs.default.readFileSync(didFile, "utf-8");
     if (!import_node_fs.default.existsSync(outDir)) {
@@ -81,73 +74,75 @@ async function generateDeclarations(options) {
     import_node_fs.default.mkdirSync(declarationsDir, { recursive: true });
     const jsContent = (0, import_parser.didToJs)(didContent);
     const tsContent = (0, import_parser.didToTs)(didContent);
-    const baseName = didFileName.replace(/\.did$/, "");
-    const jsPath = import_node_path.default.join(declarationsDir, baseName + ".js");
-    const dtsPath = import_node_path.default.join(declarationsDir, baseName + ".d.ts");
-    const didPath = import_node_path.default.join(declarationsDir, didFileName);
+    const jsPath = import_node_path.default.join(declarationsDir, `${baseName}.js`);
+    const dtsPath = import_node_path.default.join(declarationsDir, `${baseName}.d.ts`);
+    const didCopyPath = import_node_path.default.join(declarationsDir, `${baseName}.did`);
     import_node_fs.default.writeFileSync(jsPath, jsContent);
     import_node_fs.default.writeFileSync(dtsPath, tsContent);
-    import_node_fs.default.writeFileSync(didPath, didContent);
+    import_node_fs.default.writeFileSync(didCopyPath, didContent);
     return {
       success: true,
-      declarationsDir
+      declarationsDir,
+      files: [
+        { success: true, filePath: jsPath },
+        { success: true, filePath: dtsPath },
+        { success: true, filePath: didCopyPath }
+      ]
     };
   } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
     return {
       success: false,
       declarationsDir,
-      error: error instanceof Error ? error.message : String(error)
+      files: [],
+      error: `[${canisterName}] Failed to generate declarations: ${message}`
     };
   }
 }
 function declarationsExist(outDir, canisterName) {
-  const declarationsDir = import_node_path.default.join(outDir, "declarations");
-  const didTsPath = import_node_path.default.join(declarationsDir, `${canisterName}.d.ts`);
-  return import_node_fs.default.existsSync(didTsPath);
+  const dtsPath = import_node_path.default.join(outDir, "declarations", `${canisterName}.d.ts`);
+  return import_node_fs.default.existsSync(dtsPath);
 }
 
-// src/templates/reactor.ts
+// src/generators/reactor.ts
 var import_node_path2 = __toESM(require("path"), 1);
+
+// src/naming.ts
+var import_change_case = require("change-case");
+function toPascalCase(str) {
+  return (0, import_change_case.pascalCase)(str);
+}
+function toCamelCase(str) {
+  return (0, import_change_case.camelCase)(str);
+}
+function getReactorName(canisterName) {
+  return `${toCamelCase(canisterName)}Reactor`;
+}
+function getServiceTypeName(canisterName) {
+  return `${toPascalCase(canisterName)}Service`;
+}
+
+// src/generators/reactor.ts
 function generateReactorFile(options) {
-  const pascalName = toPascalCase(options.canisterName);
-  const reactorName = getReactorName(options.canisterName);
-  const serviceName = getServiceTypeName(options.canisterName);
-  const reactorType = "DisplayReactor";
-  const didFileName = import_node_path2.default.basename(options.didFile);
-  const baseName = didFileName.replace(/\.did$/, "");
+  const { canisterName, didFile, clientManagerPath = "../../clients" } = options;
+  const pascalName = toPascalCase(canisterName);
+  const reactorName = getReactorName(canisterName);
+  const serviceName = getServiceTypeName(canisterName);
+  const baseName = import_node_path2.default.basename(didFile, ".did");
   const declarationsPath = `./declarations/${baseName}`;
-  const clientManagerPath = options.clientManagerPath ?? "../../clients";
-  const vars = {
-    canisterName: options.canisterName,
-    pascalName,
-    reactorName,
-    serviceName,
-    reactorType,
-    clientManagerPath,
-    declarationsPath
-  };
-  return generateStandardReactorFile(vars);
-}
-function generateStandardReactorFile(vars) {
-  const {
-    pascalName,
-    reactorName,
-    serviceName,
-    reactorType,
-    clientManagerPath,
-    declarationsPath,
-    canisterName
-  } = vars;
-  return `import { ${reactorType}, createActorHooks } from "@ic-reactor/react"
+  return `import { DisplayReactor, createActorHooks } from "@ic-reactor/react"
 import { clientManager } from "${clientManagerPath}"
 import { idlFactory, type _SERVICE } from "${declarationsPath}"
 
 export type ${serviceName} = _SERVICE
 
 /**
- * ${pascalName} Display Reactor
+ * ${pascalName} Reactor
+ *
+ * Auto-generated by @ic-reactor/codegen \u2014 do not edit.
+ * Re-run \`ic-reactor generate\` (or the Vite plugin) to regenerate.
  */
-export const ${reactorName} = new ${reactorType}<${serviceName}>({
+export const ${reactorName} = new DisplayReactor<${serviceName}>({
   clientManager,
   idlFactory,
   name: "${canisterName}",
@@ -164,18 +159,123 @@ export const {
 `;
 }
 
-// src/templates/client.ts
+// src/pipeline.ts
+async function runCanisterPipeline(options) {
+  const { canisterConfig, projectRoot, globalConfig } = options;
+  const { name, didFile, clientManagerPath } = canisterConfig;
+  const files = [];
+  const resolvedDidFile = import_node_path3.default.isAbsolute(didFile) ? didFile : import_node_path3.default.resolve(projectRoot, didFile);
+  if (!import_node_fs2.default.existsSync(resolvedDidFile)) {
+    return {
+      canisterName: name,
+      success: false,
+      files: [],
+      error: `DID file not found: ${resolvedDidFile}`
+    };
+  }
+  const canisterOutDir = canisterConfig.outDir != null ? import_node_path3.default.isAbsolute(canisterConfig.outDir) ? canisterConfig.outDir : import_node_path3.default.resolve(projectRoot, canisterConfig.outDir) : import_node_path3.default.resolve(projectRoot, globalConfig.outDir, name);
+  const resolvedClientManagerPath = clientManagerPath ?? globalConfig.clientManagerPath ?? "../../clients";
+  try {
+    const declResult = await generateDeclarations({
+      didFile: resolvedDidFile,
+      outDir: canisterOutDir,
+      canisterName: name
+    });
+    if (!declResult.success) {
+      return {
+        canisterName: name,
+        success: false,
+        files,
+        error: declResult.error
+      };
+    }
+    files.push(...declResult.files);
+  } catch (err) {
+    return {
+      canisterName: name,
+      success: false,
+      files,
+      error: `Declarations step failed: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+  const reactorPath = import_node_path3.default.join(canisterOutDir, "index.ts");
+  try {
+    const reactorContent = generateReactorFile({
+      canisterName: name,
+      didFile: resolvedDidFile,
+      clientManagerPath: resolvedClientManagerPath
+    });
+    import_node_fs2.default.mkdirSync(canisterOutDir, { recursive: true });
+    import_node_fs2.default.writeFileSync(reactorPath, reactorContent);
+    files.push({ success: true, filePath: reactorPath });
+  } catch (err) {
+    files.push({
+      success: false,
+      filePath: reactorPath,
+      error: `Reactor generation failed: ${err instanceof Error ? err.message : String(err)}`
+    });
+    return {
+      canisterName: name,
+      success: false,
+      files,
+      error: `Reactor step failed: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+  return {
+    canisterName: name,
+    success: true,
+    files
+  };
+}
+
+// src/parser.ts
+var import_parser2 = require("@ic-reactor/parser");
+var import_node_fs3 = __toESM(require("fs"), 1);
+function extractMethods(didContent) {
+  try {
+    const jsContent = (0, import_parser2.didToJs)(didContent);
+    const methods = [];
+    const serviceMatch = /IDL\.Service\(\{([\s\S]*?)\}\)/.exec(jsContent);
+    if (!serviceMatch) return methods;
+    const serviceBody = serviceMatch[1];
+    const methodRegex = /['"]([\w]+)['"]\s*:\s*IDL\.Func\(\s*\[(.*?)\],\s*\[.*?\],\s*\[(.*?)\]\)/g;
+    let match;
+    while ((match = methodRegex.exec(serviceBody)) !== null) {
+      const [, name, args, annotations] = match;
+      methods.push({
+        name,
+        type: annotations.includes("'query'") ? "query" : "mutation",
+        hasArgs: args.trim().length > 0
+      });
+    }
+    return methods;
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to parse Candid: ${msg}`);
+  }
+}
+function parseDIDFile(didFilePath) {
+  if (!import_node_fs3.default.existsSync(didFilePath)) {
+    throw new Error(`DID file not found: ${didFilePath}`);
+  }
+  const content = import_node_fs3.default.readFileSync(didFilePath, "utf-8");
+  return extractMethods(content);
+}
+
+// src/generators/client.ts
 function generateClientFile(options = {}) {
   const { queryClientPath } = options;
-  return `import { ClientManager } from "@ic-reactor/react"
-${queryClientPath ? `import { queryClient } from "${queryClientPath}"` : `import { QueryClient } from "@tanstack/react-query"
+  const queryClientImport = queryClientPath ? `import { queryClient } from "${queryClientPath}"` : `import { QueryClient } from "@tanstack/react-query"
 
-export const queryClient = new QueryClient()`}
+export const queryClient = new QueryClient()`;
+  return `import { ClientManager } from "@ic-reactor/react"
+${queryClientImport}
 
 /**
  * IC Reactor Client Manager
- * 
- * Auto-generated by @ic-reactor/codegen
+ *
+ * Auto-generated by @ic-reactor/codegen \u2014 customize as needed.
+ * See: https://github.com/B3Pay/ic-reactor#client-manager
  */
 export const clientManager = new ClientManager({
   queryClient,
@@ -186,10 +286,13 @@ export const clientManager = new ClientManager({
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   declarationsExist,
+  extractMethods,
   generateClientFile,
   generateDeclarations,
   generateReactorFile,
   getReactorName,
   getServiceTypeName,
+  parseDIDFile,
+  runCanisterPipeline,
   toPascalCase
 });

package/dist/index.d.cts

@@ -1,83 +1,249 @@
+/**
+ * @ic-reactor/codegen — Core Types
+ *
+ * All shared types used across generators, pipeline, CLI, and vite-plugin.
+ */
+/**
+ * Per-canister configuration.
+ * `name` is always required — it drives all naming in generators.
+ */
+interface CanisterConfig {
+    /** Canister name (used for variable names, file names, etc.) */
+    name: string;
+    /** Path to the .did file (relative to project root, or absolute) */
+    didFile: string;
+    /** Override output dir for this specific canister */
+    outDir?: string;
+    /**
+     * Import path to the ClientManager (relative from the generated reactor file).
+     * Example: "../../clients" → `import { clientManager } from "../../clients"`
+     */
+    clientManagerPath?: string;
+    /** Optional fixed canister ID */
+    canisterId?: string;
+}
+/**
+ * Top-level codegen / CLI configuration (stored in `ic-reactor.json`).
+ */
+interface CodegenConfig {
+    /** JSON Schema reference */
+    $schema?: string;
+    /**
+     * Default output directory for all canisters (relative to project root).
+     * Individual canisters can override via `CanisterConfig.outDir`.
+     */
+    outDir: string;
+    /**
+     * Default import path for the ClientManager (relative from generated files).
+     * Individual canisters can override via `CanisterConfig.clientManagerPath`.
+     */
+    clientManagerPath?: string;
+    /** Canister configurations, keyed by canister name */
+    canisters: Record<string, CanisterConfig>;
+}
+/**
+ * Result of a single file-writing generator step.
+ */
+interface GeneratorResult {
+    success: boolean;
+    /** Absolute path of the file that was (or would have been) written */
+    filePath: string;
+    /** If true, skipped because the file already existed */
+    skipped?: boolean;
+    error?: string;
+}
+
+/**
+ * Codegen Pipeline
+ *
+ * Orchestrates all generators for a single canister.
+ * This is the primary entry point used by @ic-reactor/cli and @ic-reactor/vite-plugin.
+ *
+ * Pipeline steps (in order):
+ *  1. Resolve paths (didFile, outDir)
+ *  2. Generate declarations (JS + .d.ts + .did copy)
+ *  3. Generate reactor file (index.ts)
+ */
+
+interface PipelineOptions {
+    /** Canister name and config */
+    canisterConfig: CanisterConfig;
+    /**
+     * Absolute path to the project root.
+     * Relative paths in `CanisterConfig` are resolved from here.
+     */
+    projectRoot: string;
+    /**
+     * Global codegen config (for fallback outDir and clientManagerPath).
+     */
+    globalConfig: Pick<CodegenConfig, "outDir" | "clientManagerPath">;
+}
+interface PipelineResult {
+    canisterName: string;
+    success: boolean;
+    /** All files the pipeline attempted to write */
+    files: GeneratorResult[];
+    error?: string;
+}
+/**
+ * Run the full codegen pipeline for a single canister.
+ *
+ * @returns PipelineResult with per-file details
+ */
+declare function runCanisterPipeline(options: PipelineOptions): Promise<PipelineResult>;
+
 /**
  * Naming utilities for code generation
  *
- * Uses the `change-case` library for base transformations,
- * with domain-specific helpers for IC Reactor patterns.
+ * Pure functions that convert canister/method names to correctly cased
+ * identifiers used throughout generated code.
  */
 /**
- * Convert string to PascalCase
+ * Convert string to PascalCase.
  * @example toPascalCase("get_message") → "GetMessage"
  * @example toPascalCase("my-canister") → "MyCanister"
  */
 declare function toPascalCase(str: string): string;
 /**
- * Generate reactor variable name
+ * Generate the reactor variable name for a canister.
  * @example getReactorName("backend") → "backendReactor"
+ * @example getReactorName("my_canister") → "myCanisterReactor"
  */
 declare function getReactorName(canisterName: string): string;
 /**
- * Generate service type name
+ * Generate the service type name for a canister.
  * @example getServiceTypeName("backend") → "BackendService"
+ * @example getServiceTypeName("my_canister") → "MyCanisterService"
  */
 declare function getServiceTypeName(canisterName: string): string;
 
 /**
- * Bindgen utilities
+ * Candid Parser Utilities
+ *
+ * Parses Candid .did files to extract service method signatures.
+ * Used by the CLI for listing methods and by advanced generators.
+ */
+type MethodType = "query" | "mutation";
+interface MethodInfo {
+    /** Method name as it appears in the Candid service */
+    name: string;
+    /** "query" for read-only calls, "mutation" for update calls */
+    type: MethodType;
+    /** True if the method takes at least one argument */
+    hasArgs: boolean;
+}
+/**
+ * Extract method information from raw Candid source text.
  *
- * Generates TypeScript declarations from Candid files using @ic-reactor/parser.
+ * Compiles the Candid to JS and inspects the IDL.Service definition.
  */
-interface BindgenOptions {
-    /** Path to the .did file */
+declare function extractMethods(didContent: string): MethodInfo[];
+/**
+ * Parse a .did file from disk and return its methods.
+ *
+ * @throws if the file does not exist or fails to parse
+ */
+declare function parseDIDFile(didFilePath: string): MethodInfo[];
+
+/**
+ * Declarations Generator
+ *
+ * Generates TypeScript declaration files (.js IDL factory + .d.ts types)
+ * from a Candid .did file using @ic-reactor/parser.
+ *
+ * Output structure:
+ *   <outDir>/declarations/<name>.js       — IDL factory
+ *   <outDir>/declarations/<name>.d.ts     — TypeScript types
+ *   <outDir>/declarations/<name>.did      — Copy of the source .did file
+ */
+
+interface DeclarationsGeneratorOptions {
+    /** Absolute path to the .did file */
     didFile: string;
-    /** Output directory for generated declarations */
+    /** Absolute path to the output directory (declarations/ will be created inside) */
     outDir: string;
-    /** Canister name (used for naming) */
+    /** Canister name (used only for error messages) */
     canisterName: string;
 }
-interface BindgenResult {
+interface DeclarationsGeneratorResult {
     success: boolean;
     declarationsDir: string;
+    files: GeneratorResult[];
     error?: string;
 }
 /**
- * Generate TypeScript declarations from a Candid file
+ * Generate TypeScript declarations from a Candid file.
  *
- * This creates:
- * - declarations/<canisterName>.js - IDL factory
- * - declarations/<canisterName>.d.ts - Types
+ * Always cleans and regenerates the declarations directory to ensure
+ * it's in sync with the source .did file.
  */
-declare function generateDeclarations(options: BindgenOptions): Promise<BindgenResult>;
+declare function generateDeclarations(options: DeclarationsGeneratorOptions): Promise<DeclarationsGeneratorResult>;
 /**
- * Check if declarations already exist for a canister
+ * Check if declarations already exist for a canister.
  */
 declare function declarationsExist(outDir: string, canisterName: string): boolean;
 
 /**
- * Reactor file template generator
+ * Reactor File Generator
+ *
+ * Generates the main `index.ts` for a canister — a DisplayReactor instance
+ * plus the full set of typed hooks via `createActorHooks`.
+ *
+ * Generated output example (for canister "backend"):
  *
- * Generates the reactor instance file for a canister using DisplayReactor.
- * Standardizes the output to include typed hooks and clean imports.
+ *   import { DisplayReactor, createActorHooks } from "@ic-reactor/react"
+ *   import { clientManager } from "../../clients"
+ *   import { idlFactory, type _SERVICE } from "./declarations/backend"
+ *
+ *   export type BackendService = _SERVICE
+ *
+ *   export const backendReactor = new DisplayReactor<BackendService>({ ... })
+ *
+ *   export const {
+ *     useActorQuery: useBackendQuery,
+ *     ...
+ *   } = createActorHooks(backendReactor)
  */
-type ReactorGeneratorOptions = {
+interface ReactorGeneratorOptions {
+    /** Canister name (e.g. "backend") */
     canisterName: string;
+    /**
+     * Path to the .did file. Used to derive the declarations import path.
+     * Can be relative or absolute — only the basename is used.
+     */
     didFile: string;
+    /**
+     * Import path for the client manager, relative from the generated reactor file.
+     * Default: "../../clients"
+     */
     clientManagerPath?: string;
-};
+}
 /**
- * Generate the reactor file content
+ * Generate the content of a canister's `index.ts` reactor file.
  */
 declare function generateReactorFile(options: ReactorGeneratorOptions): string;
 
 /**
  * Client Manager Generator
+ *
+ * Generates a central `clients.ts` file that creates a `ClientManager` instance.
+ * This file is shared across all canisters in a project.
+ *
+ * Users typically customize this file once to configure:
+ * - Custom host (local vs. mainnet)
+ * - Identity provider
+ * - Query client options
  */
 interface ClientGeneratorOptions {
-    /** Optional path to an existing queryClient */
+    /**
+     * Import path to an existing `queryClient` instance.
+     * If omitted, a default `QueryClient` will be created.
+     */
     queryClientPath?: string;
 }
 /**
- * Generate a central client manager file
+ * Generate the content for a central client manager file (`clients.ts`).
  */
 declare function generateClientFile(options?: ClientGeneratorOptions): string;
 
-export { type BindgenOptions, type BindgenResult, type ClientGeneratorOptions, type ReactorGeneratorOptions, declarationsExist, generateClientFile, generateDeclarations, generateReactorFile, getReactorName, getServiceTypeName, toPascalCase };
+export { type CanisterConfig, type ClientGeneratorOptions, type CodegenConfig, type DeclarationsGeneratorOptions, type DeclarationsGeneratorResult, type GeneratorResult, type MethodInfo, type MethodType, type PipelineOptions, type PipelineResult, type ReactorGeneratorOptions, declarationsExist, extractMethods, generateClientFile, generateDeclarations, generateReactorFile, getReactorName, getServiceTypeName, parseDIDFile, runCanisterPipeline, toPascalCase };