@ic-reactor/codegen 0.12.0 → 0.13.0

package/src/generators/declarations.ts

@@ -14,6 +14,7 @@ import { didToJs, didToTs } from "@ic-reactor/parser"
 import path from "node:path"
 import fs from "node:fs"
 import type { GeneratorResult } from "../types.js"
+import { CodegenConfigError, resolveDeclarationsBaseName } from "../validate.js"
 
 export interface DeclarationsGeneratorOptions {
   /** Absolute path to the .did file */
@@ -31,18 +32,95 @@ export interface DeclarationsGeneratorResult {
   error?: string
 }
 
+/**
+ * Move `from` onto `to`, replacing whatever is already there.
+ *
+ * `rename(2)` refuses to replace a non-empty directory, so the previous output
+ * is moved aside first and only removed once the new directory is in place. If
+ * the second rename fails the old directory is put back, so the observable
+ * states are "old output" and "new output" — never "no output".
+ */
+function replaceDirectory(from: string, to: string): void {
+  if (!fs.existsSync(to)) {
+    fs.renameSync(from, to)
+    return
+  }
+
+  // Same parent as `to`, so this is a rename within one filesystem. Dot-prefixed
+  // because a crash between the two renames below strands this directory next
+  // to the real one: `declarations.old-XYZ` sits inside the project's source
+  // tree and TypeScript would compile it, producing duplicate declarations on
+  // top of whatever the crash already caused.
+  const displaced = fs.mkdtempSync(
+    path.join(path.dirname(to), `.${path.basename(to)}.old-`)
+  )
+  // mkdtemp created the directory; rename needs the name to be free.
+  fs.rmdirSync(displaced)
+  fs.renameSync(to, displaced)
+
+  try {
+    fs.renameSync(from, to)
+  } catch (error) {
+    fs.renameSync(displaced, to)
+    throw error
+  }
+
+  fs.rmSync(displaced, { recursive: true, force: true })
+}
+
 /**
  * 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.
+ * Generation happens in a staging directory that is swapped over the existing
+ * `declarations/` only after every file has been written. The parser runs on
+ * user-authored Candid and throws on a syntax error — under the vite plugin
+ * that is a *normal* watch-mode event, one keystroke in a .did file — so
+ * deleting the previous output before parsing turned every typo into a broken
+ * build with no declarations at all. A failure now leaves the previous
+ * declarations byte-identical.
+ */
+/**
+ * The export the generated reactor imports. Its presence in `didToJs` output is
+ * the authoritative "this .did describes a service" test — see the note in
+ * generateDeclarations.
+ */
+const HAS_IDL_FACTORY = /\bexport\s+const\s+idlFactory\b/
+
+/**
+ * Marker naming the canister an output directory belongs to. Dot-prefixed so
+ * it stays out of the generated surface consumers import.
  */
+export const OWNER_FILE = ".ic-reactor-owner"
+
 export async function generateDeclarations(
   options: DeclarationsGeneratorOptions
 ): Promise<DeclarationsGeneratorResult> {
   const { didFile, outDir, canisterName } = options
 
-  if (!fs.existsSync(didFile)) {
+  const declarationsDir = path.join(outDir, "declarations")
+
+  // Checked before the file itself: an absolute `didFile` ending in ".." is not
+  // normalized by the caller and does exist, so without this the diagnostic
+  // would be about the file type rather than about the path being a directory.
+  let baseName: string
+  try {
+    baseName = resolveDeclarationsBaseName(didFile)
+  } catch (error) {
+    if (error instanceof CodegenConfigError) {
+      return {
+        success: false,
+        declarationsDir: "",
+        files: [],
+        error: `[${canisterName}] ${error.message}`,
+      }
+    }
+    throw error
+  }
+
+  let didStat: fs.Stats
+  try {
+    didStat = fs.statSync(didFile)
+  } catch {
     return {
       success: false,
       declarationsDir: "",
@@ -51,34 +129,72 @@ export async function generateDeclarations(
     }
   }
 
-  const declarationsDir = path.join(outDir, "declarations")
-  const baseName = path.basename(didFile, ".did") // e.g. "backend" from "backend.did"
+  // A fifo or character device reads forever. Refusing anything that is not a
+  // regular file turns an indefinite hang into a diagnosable error.
+  if (!didStat.isFile()) {
+    return {
+      success: false,
+      declarationsDir: "",
+      files: [],
+      error: `[${canisterName}] DID path is not a regular file: ${didFile}`,
+    }
+  }
+
+  let staging: string | undefined
 
   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 })
-    }
+    const jsContent = didToJs(didContent)
+    const tsContent = didToTs(didContent)
 
-    // Clean and recreate declarations dir for a fresh generation
-    if (fs.existsSync(declarationsDir)) {
-      fs.rmSync(declarationsDir, { recursive: true, force: true })
+    // A .did that parses but declares no service is a normal thing to have — a
+    // shared types file, say — but it compiles to a module with no `idlFactory`
+    // and no `_SERVICE`, which is exactly what the generated reactor imports.
+    // Caught here the caller gets the .did path; not caught, the consumer's
+    // build fails on a file we just reported as generated.
+    //
+    // The test is on the GENERATED OUTPUT, not on `parseDid(...).service`. That
+    // AST field is only populated for an inline body; it is null for every
+    // alias form — `service : S;`, `service : (args) -> S;`, `service name : S;`
+    // — which the parser nonetheless compiles to a complete idlFactory. Gating
+    // on the AST field rejected those valid files outright.
+    if (!HAS_IDL_FACTORY.test(jsContent)) {
+      return {
+        success: false,
+        declarationsDir,
+        files: [],
+        error:
+          `[${canisterName}] ${didFile} produces no idlFactory, so there is no service ` +
+          `to generate against. Point this canister at the .did file that declares its ` +
+          `service.`,
+      }
     }
-    fs.mkdirSync(declarationsDir, { recursive: true })
 
-    const jsContent = didToJs(didContent)
-    const tsContent = didToTs(didContent)
+    // Ensure output dir exists — it is also the staging directory's parent, so
+    // the swap below stays a same-filesystem rename.
+    fs.mkdirSync(outDir, { recursive: true })
+
+    // Record which canister owns this directory. The pipeline reads it to stop
+    // a second canister generating into the same outDir and wiping the first
+    // one's declarations. It lives here rather than in index.generated.ts
+    // because `--bindgen-only` never writes that file, and the declarations
+    // replacement it skips past is exactly the destructive step.
+    fs.writeFileSync(path.join(outDir, OWNER_FILE), `${canisterName}\n`)
+
+    staging = fs.mkdtempSync(path.join(outDir, ".declarations.tmp-"))
 
     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)
+    fs.writeFileSync(path.join(staging, `${baseName}.js`), jsContent)
+    fs.writeFileSync(path.join(staging, `${baseName}.d.ts`), tsContent)
+    fs.writeFileSync(path.join(staging, `${baseName}.did`), didContent)
+
+    replaceDirectory(staging, declarationsDir)
+    staging = undefined
 
     return {
       success: true,
@@ -97,16 +213,43 @@ export async function generateDeclarations(
       files: [],
       error: `[${canisterName}] Failed to generate declarations: ${message}`,
     }
+  } finally {
+    // Reached on the failure path and on an interrupted swap; a completed swap
+    // has already cleared `staging`.
+    if (staging) fs.rmSync(staging, { recursive: true, force: true })
   }
 }
 
 /**
  * Check if declarations already exist for a canister.
+ *
+ * Declarations are written under the *.did basename*, which need not equal the
+ * canister name — `{ name: "backend", didFile: "service.did" }` writes
+ * `declarations/service.d.ts`. Pass `didFile` for an exact answer; without it
+ * this falls back to any `.d.ts` in the directory, because a bare
+ * `<canisterName>.d.ts` check reports "missing" for perfectly good output.
  */
 export function declarationsExist(
   outDir: string,
-  canisterName: string
+  canisterName: string,
+  didFile?: string
 ): boolean {
-  const dtsPath = path.join(outDir, "declarations", `${canisterName}.d.ts`)
-  return fs.existsSync(dtsPath)
+  const declarationsDir = path.join(outDir, "declarations")
+
+  if (didFile !== undefined) {
+    const baseName = path.basename(didFile, ".did")
+    return fs.existsSync(path.join(declarationsDir, `${baseName}.d.ts`))
+  }
+
+  if (fs.existsSync(path.join(declarationsDir, `${canisterName}.d.ts`))) {
+    return true
+  }
+
+  try {
+    return fs
+      .readdirSync(declarationsDir)
+      .some((entry) => entry.endsWith(".d.ts"))
+  } catch {
+    return false
+  }
 }

package/src/generators/reactor.ts

@@ -20,9 +20,9 @@
  *   } = createActorHooks(backendReactor)
  */
 
-import path from "node:path"
 import { toPascalCase, getReactorName, getServiceTypeName } from "../naming.js"
 import type { CodegenTarget, ReactorClassName } from "../types.js"
+import { resolveDeclarationsBaseName } from "../validate.js"
 
 export interface ReactorGeneratorOptions {
   /** Canister name (e.g. "backend") */
@@ -60,6 +60,14 @@ function getReactorClassImportSource(
     case "CandidDisplayReactor":
     case "MetadataDisplayReactor":
       return "@ic-reactor/candid"
+    default:
+      // The pipeline validates `mode` against a closed set before we are
+      // reached. Failing closed here means a caller that skips validation gets
+      // an error rather than an unknown class name interpolated into source.
+      throw new Error(
+        `Unknown reactor class ${JSON.stringify(reactorClass)}. Expected one of: ` +
+          `Reactor, DisplayReactor, CandidReactor, CandidDisplayReactor, MetadataDisplayReactor.`
+      )
   }
 }
 
@@ -80,8 +88,10 @@ export function generateReactorFile(options: ReactorGeneratorOptions): string {
   const reactorName = getReactorName(canisterName)
   const serviceName = getServiceTypeName(canisterName)
 
-  // Derive the declarations import path from the .did filename
-  const baseName = path.basename(didFile, ".did")
+  // Derive the declarations import path from the .did filename. The helper
+  // rejects stems like "." and ".." rather than emitting an import of a
+  // directory — this runs even for callers that bypass the pipeline.
+  const baseName = resolveDeclarationsBaseName(didFile)
   const declarationsPath = `./declarations/${baseName}`
   const reactorImportSource = getReactorClassImportSource(
     reactorClass,
@@ -105,9 +115,12 @@ export const {
 `
       : ""
 
-  return `${runtimeTarget === "react" ? 'import { createActorHooks } from "@ic-reactor/react"\n' : ""}import { ${reactorClass} } from "${reactorImportSource}"
-import { clientManager } from "${clientManagerPath}"
-import { idlFactory, type _SERVICE } from "${declarationsPath}"
+  // Every interpolation into emitted source is JSON.stringify'd. The pipeline
+  // validates these values before we are called; quoting them here as well
+  // means a future caller that skips validation cannot inject source text.
+  return `${runtimeTarget === "react" ? 'import { createActorHooks } from "@ic-reactor/react"\n' : ""}import { ${reactorClass} } from ${JSON.stringify(reactorImportSource)}
+import { clientManager } from ${JSON.stringify(clientManagerPath)}
+import { idlFactory, type _SERVICE } from ${JSON.stringify(declarationsPath)}
 
 export type ${serviceName} = _SERVICE
 
@@ -123,7 +136,7 @@ export type ${serviceName} = _SERVICE
 export const ${reactorName} = new ${reactorClass}<${serviceName}>({
   clientManager,
   idlFactory,
-${canisterIdLine}  name: "${canisterName}",
+${canisterIdLine}  name: ${JSON.stringify(canisterName)},
 })${hookExports || "\n"}`
 }
 

package/src/index.ts

@@ -21,11 +21,25 @@ export type { PipelineOptions, PipelineResult } from "./pipeline.js"
 // Utilities
 export { toPascalCase, getReactorName, getServiceTypeName } from "./naming.js"
 
-export { parseDIDFile, extractMethods } from "./parser.js"
-export type { MethodInfo, MethodType } from "./parser.js"
+// Config validation (run by the pipeline; exported for callers that want to
+// validate a config before invoking generation)
+export {
+  assertSafeCanisterConfig,
+  assertSafeCanisterName,
+  assertSafeModuleSpecifier,
+  assertContainedPath,
+  assertOneOf,
+  resolveContainedOutDir,
+  resolveDeclarationsBaseName,
+  CodegenConfigError,
+  CANISTER_NAME_PATTERN,
+  REACTOR_CLASS_NAMES,
+  CODEGEN_TARGETS,
+} from "./validate.js"
+export type {
+  ValidatedCanisterPaths,
+  ValidateCanisterConfigOptions,
+} from "./validate.js"
 
 // Individual Generators (Advanced Usage)
 export * from "./generators/index.js"
-
-// Renderer (Candid Codec)
-export { generateCodecDeclarations } from "./renderer.js"

package/src/pipeline.ts

@@ -20,11 +20,17 @@ import type {
   GeneratorResult,
   ReactorClassName,
 } from "./types.js"
-import { generateDeclarations } from "./generators/declarations.js"
+import { generateDeclarations, OWNER_FILE } from "./generators/declarations.js"
 import {
   generateReactorEntryFile,
   generateReactorFile,
 } from "./generators/reactor.js"
+import {
+  assertSafeCanisterConfig,
+  CodegenConfigError,
+  resolveDeclarationsBaseName,
+} from "./validate.js"
+import { getReactorName, getServiceTypeName } from "./naming.js"
 
 export interface PipelineOptions {
   /** Canister name and config */
@@ -60,13 +66,114 @@ function normalizeFileContent(content: string): string {
   return content.replace(/\r\n/g, "\n").trim()
 }
 
-function isLegacyGeneratedIndexFile(content: string): boolean {
-  return (
-    content.includes("Auto-generated by @ic-reactor/codegen") &&
-    content.includes("createActorHooks(")
+/** Header line every version of this generator has written into its output. */
+const GENERATED_MARKER = "Auto-generated by @ic-reactor/codegen"
+
+/**
+ * The reactor's `name:` property as this generator emits it. Canister names are
+ * restricted to `CANISTER_NAME_PATTERN`, so the emitted line is exactly this.
+ */
+const GENERATED_CANISTER_NAME = /^ {2}name: "([A-Za-z0-9_.-]+)",$/m
+
+/** Every `export …` statement, one per line, as the generator writes them. */
+const EXPORT_STATEMENT = /^export\b.*$/gm
+
+/**
+ * Decide whether an existing `index.ts` is still the pre-split generated
+ * reactor file, which this pipeline migrates to the thin wrapper.
+ *
+ * The old test — the header marker plus the substring `createActorHooks(` —
+ * matched any file that had *ever* been generated, including one the user has
+ * since filled with their own factories and hooks. Migration would overwrite it
+ * with six lines of boilerplate and report the write as an ordinary success.
+ *
+ * So the shape is checked, not just the header: the file must still declare the
+ * reactor and hooks for *this* canister and must export nothing the old
+ * generator did not write. Anything the user added — another `export const`, an
+ * `export * from`, a re-export — takes the file out of scope and it is
+ * preserved. Edits that add no export are still possible, which is why the
+ * caller keeps a backup before writing.
+ */
+function isLegacyGeneratedIndexFile(
+  content: string,
+  canisterName: string
+): boolean {
+  if (!content.includes(GENERATED_MARKER)) return false
+
+  const reactorName = getReactorName(canisterName)
+  const serviceName = getServiceTypeName(canisterName)
+
+  // The two lines that make this the generated reactor for this canister.
+  if (!content.includes(`export const ${reactorName} = new `)) return false
+  if (!content.includes(`= createActorHooks(${reactorName})`)) return false
+
+  const allowed = [
+    `export type ${serviceName} = _SERVICE`,
+    `export const ${reactorName} = new `,
+    // Opens the destructured hook block; its members are not export statements.
+    "export const {",
+  ]
+
+  const statements = normalizeFileContent(content).match(EXPORT_STATEMENT) ?? []
+
+  return statements.every((statement) =>
+    allowed.some((prefix) => statement.startsWith(prefix))
   )
 }
 
+/**
+ * Copy `filePath` next to itself before it is overwritten, and return the
+ * backup path.
+ *
+ * Migration decides from the file's contents that it is safe to replace. That
+ * inference can be wrong for an edit that adds no export, and the file being
+ * replaced may be the only copy of work the user has not committed, so the
+ * original is kept rather than deleted. An existing backup is never clobbered.
+ */
+function backUpFile(filePath: string): string {
+  let backupPath = `${filePath}.bak`
+  for (let n = 2; fs.existsSync(backupPath); n += 1) {
+    backupPath = `${filePath}.bak.${n}`
+  }
+  fs.copyFileSync(filePath, backupPath)
+  return backupPath
+}
+
+/**
+ * Read the canister name out of an existing `index.generated.ts`, if the file
+ * exists and this package wrote it.
+ *
+ * Two canisters pointed at the same `outDir` overwrite each other's
+ * `index.generated.ts` and — since the declarations directory is replaced
+ * wholesale — each other's declarations too, with both runs reporting success.
+ * The generated file records which canister owns the directory, so the second
+ * canister can be stopped before it destroys the first one's output.
+ */
+function findOutDirOwner(outDir: string): string | undefined {
+  // Written by generateDeclarations, so it is present for `--bindgen-only`
+  // runs too — those skip index.generated.ts but still replace declarations/,
+  // which is the step that destroys the other canister's output.
+  try {
+    const owner = fs.readFileSync(path.join(outDir, OWNER_FILE), "utf-8").trim()
+    if (owner) return owner
+  } catch {
+    // fall through to the legacy marker
+  }
+
+  // Directories generated before the marker existed only carry the canister
+  // name inside index.generated.ts.
+  let content: string
+  try {
+    content = fs.readFileSync(path.join(outDir, "index.generated.ts"), "utf-8")
+  } catch {
+    return undefined
+  }
+
+  if (!content.includes(GENERATED_MARKER)) return undefined
+
+  return GENERATED_CANISTER_NAME.exec(content)?.[1]
+}
+
 function isManagedEntryWrapper(
   content: string,
   expectedEntryContent: string
@@ -102,6 +209,37 @@ export async function runCanisterPipeline(
 
   const files: GeneratorResult[] = []
 
+  // ── Validate config ────────────────────────────────────────────────────────
+  //
+  // Runs before any filesystem work. `name`, `outDir` and `clientManagerPath`
+  // come from a checked-in config file, and downstream they become a directory
+  // this pipeline recursively deletes and source text it writes into the user's
+  // bundle — so they are validated here, at the choke point every entry path
+  // (CLI, vite plugin, direct API) goes through.
+  let validated: ReturnType<typeof assertSafeCanisterConfig>
+  try {
+    validated = assertSafeCanisterConfig({
+      name,
+      canisterOutDir: canisterConfig.outDir,
+      globalOutDir: globalConfig.outDir,
+      clientManagerPath:
+        clientManagerPath ?? globalConfig.clientManagerPath ?? "../../clients",
+      projectRoot,
+      mode: canisterConfig.mode,
+      target: canisterConfig.target ?? globalConfig.target,
+    })
+  } catch (err) {
+    if (err instanceof CodegenConfigError) {
+      return {
+        canisterName: typeof name === "string" ? name : String(name),
+        success: false,
+        files,
+        error: err.message,
+      }
+    }
+    throw err
+  }
+
   // ── Resolve paths ──────────────────────────────────────────────────────────
 
   const resolvedDidFile = path.isAbsolute(didFile)
@@ -117,17 +255,47 @@ export async function runCanisterPipeline(
     }
   }
 
-  // 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)
+  // The .did basename names the generated declaration files and is the tail of
+  // the import specifier the reactor emits, so it is validated here, before any
+  // filesystem work, rather than surfacing as a broken import later.
+  try {
+    resolveDeclarationsBaseName(resolvedDidFile)
+  } catch (err) {
+    if (err instanceof CodegenConfigError) {
+      return {
+        canisterName: name,
+        success: false,
+        files,
+        error: `[${name}] ${err.message}`,
+      }
+    }
+    throw err
+  }
+
+  // Per-canister outDir overrides global outDir; both are resolved and
+  // containment-checked by assertSafeCanisterConfig above.
+  const canisterOutDir = validated.outDir
+
+  // Refuse to generate into a directory another canister already owns. This has
+  // to happen before the declarations step, which replaces `declarations/`
+  // wholesale and would otherwise take the other canister's output with it.
+  const owner = findOutDirOwner(canisterOutDir)
+  if (owner !== undefined && owner !== name) {
+    return {
+      canisterName: name,
+      success: false,
+      files,
+      error:
+        `[${name}] Output directory ${canisterOutDir} was generated for canister ` +
+        `"${owner}". Two canisters cannot share an outDir — each run replaces the ` +
+        `declarations directory and index.generated.ts, so they would overwrite each ` +
+        `other. Give each canister its own "outDir". If you renamed "${owner}" to ` +
+        `"${name}", delete that directory and regenerate.`,
+    }
+  }
 
   // clientManagerPath falls back to global, then a safe default
-  const resolvedClientManagerPath =
-    clientManagerPath ?? globalConfig.clientManagerPath ?? "../../clients"
+  const resolvedClientManagerPath = validated.clientManagerPath
 
   // ── Step 1: Declarations ───────────────────────────────────────────────────
 
@@ -193,11 +361,15 @@ export async function runCanisterPipeline(
     } else {
       const existingEntryContent = fs.readFileSync(entryPath, "utf-8")
 
-      if (
-        isLegacyGeneratedIndexFile(existingEntryContent) ||
-        isManagedEntryWrapper(existingEntryContent, entryContent)
-      ) {
+      if (isManagedEntryWrapper(existingEntryContent, entryContent)) {
+        fs.writeFileSync(entryPath, entryContent)
+        files.push({ success: true, filePath: entryPath })
+      } else if (isLegacyGeneratedIndexFile(existingEntryContent, name)) {
+        // Migration replaces a file the user owns, on the strength of a
+        // content match. Keep the original so a wrong match is recoverable.
+        const backupPath = backUpFile(entryPath)
         fs.writeFileSync(entryPath, entryContent)
+        files.push({ success: true, filePath: backupPath })
         files.push({ success: true, filePath: entryPath })
       } else {
         files.push({ success: true, filePath: entryPath, skipped: true })