@ic-reactor/codegen 0.4.0 → 0.5.0

package/src/generators/declarations.ts

@@ -0,0 +1,112 @@
+/**
+ * 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
+ */
+
+import { didToJs, didToTs } from "@ic-reactor/parser"
+import path from "node:path"
+import fs from "node:fs"
+import type { GeneratorResult } from "../types.js"
+
+export interface DeclarationsGeneratorOptions {
+  /** Absolute path to the .did file */
+  didFile: string
+  /** Absolute path to the output directory (declarations/ will be created inside) */
+  outDir: string
+  /** Canister name (used only for error messages) */
+  canisterName: string
+}
+
+export interface DeclarationsGeneratorResult {
+  success: boolean
+  declarationsDir: string
+  files: GeneratorResult[]
+  error?: string
+}
+
+/**
+ * Generate TypeScript declarations from a Candid file.
+ *
+ * Always cleans and regenerates the declarations directory to ensure
+ * it's in sync with the source .did file.
+ */
+export async function generateDeclarations(
+  options: DeclarationsGeneratorOptions
+): Promise<DeclarationsGeneratorResult> {
+  const { didFile, outDir, canisterName } = options
+
+  if (!fs.existsSync(didFile)) {
+    return {
+      success: false,
+      declarationsDir: "",
+      files: [],
+      error: `DID file not found: ${didFile}`,
+    }
+  }
+
+  const declarationsDir = path.join(outDir, "declarations")
+  const baseName = path.basename(didFile, ".did") // e.g. "backend" from "backend.did"
+
+  try {
+    // Read the DID content before any directory manipulation
+    const didContent = fs.readFileSync(didFile, "utf-8")
+
+    // Ensure output dir exists
+    if (!fs.existsSync(outDir)) {
+      fs.mkdirSync(outDir, { recursive: true })
+    }
+
+    // Clean and recreate declarations dir for a fresh generation
+    if (fs.existsSync(declarationsDir)) {
+      fs.rmSync(declarationsDir, { recursive: true, force: true })
+    }
+    fs.mkdirSync(declarationsDir, { recursive: true })
+
+    const jsContent = didToJs(didContent)
+    const tsContent = didToTs(didContent)
+
+    const jsPath = path.join(declarationsDir, `${baseName}.js`)
+    const dtsPath = path.join(declarationsDir, `${baseName}.d.ts`)
+    const didCopyPath = path.join(declarationsDir, `${baseName}.did`)
+
+    fs.writeFileSync(jsPath, jsContent)
+    fs.writeFileSync(dtsPath, tsContent)
+    fs.writeFileSync(didCopyPath, didContent)
+
+    return {
+      success: true,
+      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,
+      files: [],
+      error: `[${canisterName}] Failed to generate declarations: ${message}`,
+    }
+  }
+}
+
+/**
+ * Check if declarations already exist for a canister.
+ */
+export function declarationsExist(
+  outDir: string,
+  canisterName: string
+): boolean {
+  const dtsPath = path.join(outDir, "declarations", `${canisterName}.d.ts`)
+  return fs.existsSync(dtsPath)
+}

package/src/generators/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Generator exports
+ *
+ * All individual generators are exported here.
+ * The pipeline composes them; CLI and vite-plugin use them via the pipeline.
+ */
+
+export { generateDeclarations, declarationsExist } from "./declarations.js"
+export type {
+  DeclarationsGeneratorOptions,
+  DeclarationsGeneratorResult,
+} from "./declarations.js"
+
+export { generateReactorFile } from "./reactor.js"
+export type { ReactorGeneratorOptions } from "./reactor.js"
+
+export { generateClientFile } from "./client.js"
+export type { ClientGeneratorOptions } from "./client.js"

package/src/generators/reactor.ts

@@ -0,0 +1,82 @@
+/**
+ * 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"):
+ *
+ *   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)
+ */
+
+import path from "node:path"
+import { toPascalCase, getReactorName, getServiceTypeName } from "../naming.js"
+
+export 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 content of a canister's `index.ts` reactor file.
+ */
+export function generateReactorFile(options: ReactorGeneratorOptions): string {
+  const { canisterName, didFile, clientManagerPath = "../../clients" } = options
+
+  const pascalName = toPascalCase(canisterName)
+  const reactorName = getReactorName(canisterName)
+  const serviceName = getServiceTypeName(canisterName)
+
+  // Derive the declarations import path from the .did filename
+  const baseName = path.basename(didFile, ".did")
+  const declarationsPath = `./declarations/${baseName}`
+
+  return `import { DisplayReactor, createActorHooks } from "@ic-reactor/react"
+import { clientManager } from "${clientManagerPath}"
+import { idlFactory, type _SERVICE } from "${declarationsPath}"
+
+export type ${serviceName} = _SERVICE
+
+/**
+ * ${pascalName} Reactor
+ *
+ * Auto-generated by @ic-reactor/codegen — do not edit.
+ * Re-run \`ic-reactor generate\` (or the Vite plugin) to regenerate.
+ */
+export const ${reactorName} = new DisplayReactor<${serviceName}>({
+  clientManager,
+  idlFactory,
+  name: "${canisterName}",
+})
+
+export const {
+  useActorQuery: use${pascalName}Query,
+  useActorSuspenseQuery: use${pascalName}SuspenseQuery,
+  useActorInfiniteQuery: use${pascalName}InfiniteQuery,
+  useActorSuspenseInfiniteQuery: use${pascalName}SuspenseInfiniteQuery,
+  useActorMutation: use${pascalName}Mutation,
+  useActorMethod: use${pascalName}Method,
+} = createActorHooks(${reactorName})
+`
+}

package/src/index.ts

@@ -2,19 +2,21 @@
  * @ic-reactor/codegen
  *
  * Shared code generation utilities for IC Reactor.
- * Used by both @ic-reactor/vite-plugin and @ic-reactor/cli.
+ * Used by @ic-reactor/cli and @ic-reactor/vite-plugin.
  */
 
-// Naming utilities
-export { toPascalCase, getReactorName, getServiceTypeName } from "./naming.js"
+// Core Types
+export type { CanisterConfig, CodegenConfig, GeneratorResult } from "./types.js"
+
+// Pipeline (Primary Entry Point)
+export { runCanisterPipeline } from "./pipeline.js"
+export type { PipelineOptions, PipelineResult } from "./pipeline.js"
 
-// Bindgen utilities
-export { generateDeclarations, declarationsExist } from "./bindgen.js"
-export type { BindgenOptions, BindgenResult } from "./bindgen.js"
+// Utilities
+export { toPascalCase, getReactorName, getServiceTypeName } from "./naming.js"
 
-// Template generators
-export { generateReactorFile } from "./templates/reactor.js"
-export type { ReactorGeneratorOptions } from "./templates/reactor.js"
+export { parseDIDFile, extractMethods } from "./parser.js"
+export type { MethodInfo, MethodType } from "./parser.js"
 
-export { generateClientFile } from "./templates/client.js"
-export type { ClientGeneratorOptions } from "./templates/client.js"
+// Individual Generators (Advanced Usage)
+export * from "./generators/index.js"

package/src/naming.test.ts

@@ -2,9 +2,6 @@ import { describe, it, expect } from "vitest"
 import {
   toPascalCase,
   toCamelCase,
-  getHookFileName,
-  getHookExportName,
-  getReactHookName,
   getReactorName,
   getServiceTypeName,
 } from "./naming"
@@ -25,25 +22,14 @@ describe("Naming Utilities", () => {
   })
 
   describe("Domain-Specific Naming", () => {
-    it("generates hook file names", () => {
-      expect(getHookFileName("get_user", "query")).toBe("getUserQuery.ts")
-      expect(getHookFileName("update_item", "mutation")).toBe(
-        "updateItemMutation.ts"
-      )
-    })
-
-    it("generates hook export names", () => {
-      expect(getHookExportName("get_user", "query")).toBe("getUserQuery")
-      expect(getHookExportName("update_item", "mutation")).toBe(
-        "updateItemMutation"
-      )
+    it("generates reactor names", () => {
+      expect(getReactorName("backend")).toBe("backendReactor")
+      expect(getReactorName("my-canister")).toBe("myCanisterReactor")
     })
 
-    it("generates React hook names", () => {
-      expect(getReactHookName("get_user", "query")).toBe("useGetUserQuery")
-      expect(getReactHookName("update_item", "mutation")).toBe(
-        "useUpdateItemMutation"
-      )
+    it("generates service type names", () => {
+      expect(getServiceTypeName("backend")).toBe("BackendService")
+      expect(getServiceTypeName("update_item")).toBe("UpdateItemService")
     })
 
     it("generates reactor names", () => {

package/src/naming.ts

@@ -1,18 +1,18 @@
 /**
  * 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.
  */
 
 import { camelCase, pascalCase } from "change-case"
 
-// ═══════════════════════════════════════════════════════════════════════════
+// ─────────────────────────────────────────────────────────────────────────────
 // BASE CASE CONVERSIONS
-// ═══════════════════════════════════════════════════════════════════════════
+// ─────────────────────────────────────────────────────────────────────────────
 
 /**
- * Convert string to PascalCase
+ * Convert string to PascalCase.
  * @example toPascalCase("get_message") → "GetMessage"
  * @example toPascalCase("my-canister") → "MyCanister"
  */
@@ -21,7 +21,7 @@ export function toPascalCase(str: string): string {
 }
 
 /**
- * Convert string to camelCase
+ * Convert string to camelCase.
  * @example toCamelCase("get_message") → "getMessage"
  * @example toCamelCase("my-canister") → "myCanister"
  */
@@ -29,55 +29,33 @@ export function toCamelCase(str: string): string {
   return camelCase(str)
 }
 
-// ═══════════════════════════════════════════════════════════════════════════
+// ─────────────────────────────────────────────────────────────────────────────
 // DOMAIN-SPECIFIC NAMING
-// ═══════════════════════════════════════════════════════════════════════════
+// ─────────────────────────────────────────────────────────────────────────────
 
 /**
- * Generate hook file name
- * @example getHookFileName("get_message", "query") → "getMessageQuery.ts"
- */
-export function getHookFileName(methodName: string, hookType: string): string {
-  const camelMethod = toCamelCase(methodName)
-  const pascalType = toPascalCase(hookType)
-  return `${camelMethod}${pascalType}.ts`
-}
-
-/**
- * Generate hook export name
- * @example getHookExportName("get_message", "query") → "getMessageQuery"
- */
-export function getHookExportName(
-  methodName: string,
-  hookType: string
-): string {
-  const camelMethod = toCamelCase(methodName)
-  const pascalType = toPascalCase(hookType)
-  return `${camelMethod}${pascalType}`
-}
-
-/**
- * Generate React hook name (with use prefix)
- * @example getReactHookName("get_message", "query") → "useGetMessageQuery"
- */
-export function getReactHookName(methodName: string, hookType: string): string {
-  const pascalMethod = toPascalCase(methodName)
-  const pascalType = toPascalCase(hookType)
-  return `use${pascalMethod}${pascalType}`
-}
-
-/**
- * Generate reactor variable name
+ * Generate the reactor variable name for a canister.
  * @example getReactorName("backend") → "backendReactor"
+ * @example getReactorName("my_canister") → "myCanisterReactor"
  */
 export function getReactorName(canisterName: string): string {
   return `${toCamelCase(canisterName)}Reactor`
 }
 
 /**
- * Generate service type name
+ * Generate the service type name for a canister.
  * @example getServiceTypeName("backend") → "BackendService"
+ * @example getServiceTypeName("my_canister") → "MyCanisterService"
  */
 export function getServiceTypeName(canisterName: string): string {
   return `${toPascalCase(canisterName)}Service`
 }
+
+/**
+ * Generate the hook name prefix (PascalCase canister name).
+ * Used when naming the destructured hooks: `use<Prefix>Query`, etc.
+ * @example getHookPrefix("my_canister") → "MyCanister"
+ */
+export function getHookPrefix(canisterName: string): string {
+  return toPascalCase(canisterName)
+}

package/src/parser.ts

@@ -0,0 +1,79 @@
+/**
+ * Candid Parser Utilities
+ *
+ * Parses Candid .did files to extract service method signatures.
+ * Used by the CLI for listing methods and by advanced generators.
+ */
+
+import { didToJs } from "@ic-reactor/parser"
+import fs from "node:fs"
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TYPES
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type MethodType = "query" | "mutation"
+
+export 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
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// PARSERS
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Extract method information from raw Candid source text.
+ *
+ * Compiles the Candid to JS and inspects the IDL.Service definition.
+ */
+export function extractMethods(didContent: string): MethodInfo[] {
+  try {
+    const jsContent = didToJs(didContent)
+
+    const methods: MethodInfo[] = []
+
+    // Find the IDL.Service({...}) body
+    const serviceMatch = /IDL\.Service\(\{([\s\S]*?)\}\)/.exec(jsContent)
+    if (!serviceMatch) return methods
+
+    const serviceBody = serviceMatch[1]
+
+    // Match each method: 'methodName': IDL.Func([args], [rets], [annotations])
+    const methodRegex =
+      /['"]([\w]+)['"]\s*:\s*IDL\.Func\(\s*\[(.*?)\],\s*\[.*?\],\s*\[(.*?)\]\)/g
+
+    let match: RegExpExecArray | null
+    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}`)
+  }
+}
+
+/**
+ * Parse a .did file from disk and return its methods.
+ *
+ * @throws if the file does not exist or fails to parse
+ */
+export function parseDIDFile(didFilePath: string): MethodInfo[] {
+  if (!fs.existsSync(didFilePath)) {
+    throw new Error(`DID file not found: ${didFilePath}`)
+  }
+  const content = fs.readFileSync(didFilePath, "utf-8")
+  return extractMethods(content)
+}

package/src/pipeline.ts

@@ -0,0 +1,144 @@
+/**
+ * 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)
+ */
+
+import fs from "node:fs"
+import path from "node:path"
+import type { CanisterConfig, CodegenConfig, GeneratorResult } from "./types.js"
+import { generateDeclarations } from "./generators/declarations.js"
+import { generateReactorFile } from "./generators/reactor.js"
+
+export 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">
+}
+
+export 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
+ */
+export async function runCanisterPipeline(
+  options: PipelineOptions
+): Promise<PipelineResult> {
+  const { canisterConfig, projectRoot, globalConfig } = options
+  const { name, didFile, clientManagerPath } = canisterConfig
+
+  const files: GeneratorResult[] = []
+
+  // ── Resolve paths ──────────────────────────────────────────────────────────
+
+  const resolvedDidFile = path.isAbsolute(didFile)
+    ? didFile
+    : path.resolve(projectRoot, didFile)
+
+  if (!fs.existsSync(resolvedDidFile)) {
+    return {
+      canisterName: name,
+      success: false,
+      files: [],
+      error: `DID file not found: ${resolvedDidFile}`,
+    }
+  }
+
+  // Per-canister outDir overrides global outDir
+  const canisterOutDir =
+    canisterConfig.outDir != null
+      ? path.isAbsolute(canisterConfig.outDir)
+        ? canisterConfig.outDir
+        : path.resolve(projectRoot, canisterConfig.outDir)
+      : path.resolve(projectRoot, globalConfig.outDir, name)
+
+  // clientManagerPath falls back to global, then a safe default
+  const resolvedClientManagerPath =
+    clientManagerPath ?? globalConfig.clientManagerPath ?? "../../clients"
+
+  // ── Step 1: Declarations ───────────────────────────────────────────────────
+
+  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)}`,
+    }
+  }
+
+  // ── Step 2: Reactor file ───────────────────────────────────────────────────
+
+  const reactorPath = path.join(canisterOutDir, "index.ts")
+
+  try {
+    const reactorContent = generateReactorFile({
+      canisterName: name,
+      didFile: resolvedDidFile,
+      clientManagerPath: resolvedClientManagerPath,
+    })
+
+    fs.mkdirSync(canisterOutDir, { recursive: true })
+    fs.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,
+  }
+}

package/src/types.ts

@@ -0,0 +1,65 @@
+/**
+ * @ic-reactor/codegen — Core Types
+ *
+ * All shared types used across generators, pipeline, CLI, and vite-plugin.
+ */
+
+// ═══════════════════════════════════════════════════════════════════════════
+// CONFIGURATION TYPES
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Per-canister configuration.
+ * `name` is always required — it drives all naming in generators.
+ */
+export 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`).
+ */
+export 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>
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// GENERATOR TYPES
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Result of a single file-writing generator step.
+ */
+export 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
+}