@ic-reactor/codegen 0.12.0 → 0.13.0

package/dist/index.d.cts

@@ -1,6 +1,3 @@
-export { generateCodecDeclarations } from './renderer.cjs';
-import '@ic-reactor/parser';
-
 /**
  * @ic-reactor/codegen — Core Types
  *
@@ -144,32 +141,126 @@ declare function getReactorName(canisterName: string): string;
 declare function getServiceTypeName(canisterName: string): string;
 
 /**
- * Candid Parser Utilities
+ * Config validation for the codegen pipeline.
+ *
+ * Every value validated here arrives from a project's `ic-reactor.json` or from
+ * `@ic-reactor/vite-plugin` options — that is, from a file in a repository the
+ * user may have merely cloned. The pipeline turns those values into filesystem
+ * paths it recursively deletes and into source text it writes into the user's
+ * bundle, so they are treated as untrusted input rather than as configuration.
  *
- * Parses Candid .did files to extract service method signatures.
- * Used by the CLI for listing methods and by advanced generators.
+ * Validation lives here, at the pipeline's own entry point, rather than in the
+ * CLI's interactive prompt: the prompt only covers one of the three entry paths
+ * (hand-edited config and plugin options bypass it entirely).
  */
-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;
+
+/**
+ * Thrown when a canister config would produce an unsafe path or unsafe
+ * generated source. Callers convert this into a `PipelineResult` error.
+ */
+declare class CodegenConfigError extends Error {
+    readonly name = "CodegenConfigError";
+    constructor(message: string);
 }
 /**
- * Extract method information from raw Candid source text.
+ * Characters allowed in a canister name.
+ *
+ * A canister name becomes a directory segment, so this excludes path
+ * separators, quotes, whitespace and control characters. It deliberately does
+ * NOT require a leading letter: `dfx` places no restriction on canister names,
+ * and real projects use `_private` and `my.canister`, both of which derive
+ * perfectly good identifiers. Identifier validity is enforced separately, on
+ * the *derived* names, by {@link assertSafeCanisterName}.
+ */
+declare const CANISTER_NAME_PATTERN: RegExp;
+/**
+ * Assert that a canister name is safe to use as a path segment and as the stem
+ * of a generated identifier.
+ *
+ * Rejecting a leading digit here is what stops `2048_game` from reaching the
+ * generator, where it would become `export const 2048GameReactor` — invalid
+ * TypeScript emitted with a success status.
+ */
+declare function assertSafeCanisterName(name: unknown): asserts name is string;
+/**
+ * Assert that a module specifier we interpolate into an `import` statement is a
+ * relative path or a bare package name — never a URL.
+ *
+ * A `https://…` specifier here would make the generated module pull code from a
+ * remote host at import time, inside the user's own bundle.
+ */
+declare function assertSafeModuleSpecifier(label: string, specifier: unknown): asserts specifier is string;
+/**
+ * Derive the declarations file stem from a `.did` path and assert it is usable
+ * both as a file name and as the tail of the import specifier we emit.
+ *
+ * `path.basename` is happy to hand back `"."` or `".."`: a `didFile` of
+ * `"canisters/.."` makes the generated reactor `import … from
+ * "./declarations/.."`, a *directory* reference — reported as a successful
+ * generation, rejected by the consumer's bundler. Validating the derived
+ * specifier here is the same treatment `clientManagerPath` gets, for the same
+ * reason: it is config-supplied text that ends up inside an `import`.
+ */
+declare function resolveDeclarationsBaseName(didFile: unknown): string;
+/** Reactor classes the generator knows how to emit an import for. */
+declare const REACTOR_CLASS_NAMES: readonly ReactorClassName[];
+/** Runtime targets the generator knows how to emit. */
+declare const CODEGEN_TARGETS: readonly CodegenTarget[];
+/**
+ * Assert a config value is one of a closed set.
+ *
+ * `mode` and `target` are interpolated into emitted source as bare identifiers
+ * and module specifiers, so an unrecognized value is not merely unsupported —
+ * it is injected.
+ */
+declare function assertOneOf<T extends string>(label: string, value: unknown, allowed: readonly T[]): asserts value is T;
+/**
+ * Assert that an already-resolved absolute path lies inside `projectRoot`.
+ *
+ * Containment is decided on the real on-disk locations: `path.resolve` does not
+ * follow symlinks, so a purely lexical comparison can be walked out of via a
+ * symlink placed inside the project root.
  *
- * Compiles the Candid to JS and inspects the IDL.Service definition.
+ * @param original - the path as the user wrote it, for the error message
  */
-declare function extractMethods(didContent: string): MethodInfo[];
+declare function assertContainedPath(label: string, resolved: string, projectRoot: string, original?: string): void;
 /**
- * Parse a .did file from disk and return its methods.
+ * Resolve `outDir` against `projectRoot` and assert the result stays inside it.
  *
- * @throws if the file does not exist or fails to parse
+ * The pipeline recursively deletes `<outDir>/declarations` before every
+ * generation, so an `outDir` that escapes the project root turns a config file
+ * into an arbitrary-directory delete.
  */
-declare function parseDIDFile(didFilePath: string): MethodInfo[];
+declare function resolveContainedOutDir(label: string, outDir: unknown, projectRoot: string): string;
+interface ValidatedCanisterPaths {
+    /** The validated canister name. */
+    name: string;
+    /** Absolute output directory, guaranteed to be inside `projectRoot`. */
+    outDir: string;
+    /** Validated module specifier for the client manager import. */
+    clientManagerPath: string;
+}
+interface ValidateCanisterConfigOptions {
+    name: unknown;
+    /** Per-canister `outDir`, if the config sets one. */
+    canisterOutDir?: unknown;
+    /** Global `outDir`; the canister name is appended to it when used. */
+    globalOutDir: unknown;
+    clientManagerPath: unknown;
+    projectRoot: string;
+    /** Resolved reactor class (`canisterConfig.mode`), if the config sets one. */
+    mode?: unknown;
+    /** Resolved runtime target (`canisterConfig.target` / global `target`). */
+    target?: unknown;
+}
+/**
+ * Validate one canister's config and return the resolved, contained paths the
+ * pipeline should use.
+ *
+ * Call this before any filesystem work: it is the single choke point that all
+ * three entry paths (CLI, vite plugin, direct API) share.
+ */
+declare function assertSafeCanisterConfig(options: ValidateCanisterConfigOptions): ValidatedCanisterPaths;
 
 /**
  * Declarations Generator
@@ -197,17 +288,17 @@ interface DeclarationsGeneratorResult {
     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.
- */
 declare function generateDeclarations(options: DeclarationsGeneratorOptions): Promise<DeclarationsGeneratorResult>;
 /**
  * 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.
  */
-declare function declarationsExist(outDir: string, canisterName: string): boolean;
+declare function declarationsExist(outDir: string, canisterName: string, didFile?: string): boolean;
 
 /**
  * Reactor File Generator
@@ -286,4 +377,4 @@ interface ClientGeneratorOptions {
  */
 declare function generateClientFile(options?: ClientGeneratorOptions): string;
 
-export { type CanisterConfig, type ClientGeneratorOptions, type CodegenConfig, type CodegenTarget, type DeclarationsGeneratorOptions, type DeclarationsGeneratorResult, type GeneratorResult, type MethodInfo, type MethodType, type PipelineOptions, type PipelineResult, type ReactorClassName, type ReactorGeneratorOptions, declarationsExist, extractMethods, generateClientFile, generateDeclarations, generateReactorEntryFile, generateReactorFile, getReactorName, getServiceTypeName, parseDIDFile, runCanisterPipeline, toPascalCase };
+export { CANISTER_NAME_PATTERN, CODEGEN_TARGETS, type CanisterConfig, type ClientGeneratorOptions, type CodegenConfig, CodegenConfigError, type CodegenTarget, type DeclarationsGeneratorOptions, type DeclarationsGeneratorResult, type GeneratorResult, type PipelineOptions, type PipelineResult, REACTOR_CLASS_NAMES, type ReactorClassName, type ReactorGeneratorOptions, type ValidateCanisterConfigOptions, type ValidatedCanisterPaths, assertContainedPath, assertOneOf, assertSafeCanisterConfig, assertSafeCanisterName, assertSafeModuleSpecifier, declarationsExist, generateClientFile, generateDeclarations, generateReactorEntryFile, generateReactorFile, getReactorName, getServiceTypeName, resolveContainedOutDir, resolveDeclarationsBaseName, runCanisterPipeline, toPascalCase };

package/dist/index.d.ts

@@ -1,6 +1,3 @@
-export { generateCodecDeclarations } from './renderer.js';
-import '@ic-reactor/parser';
-
 /**
  * @ic-reactor/codegen — Core Types
  *
@@ -144,32 +141,126 @@ declare function getReactorName(canisterName: string): string;
 declare function getServiceTypeName(canisterName: string): string;
 
 /**
- * Candid Parser Utilities
+ * Config validation for the codegen pipeline.
+ *
+ * Every value validated here arrives from a project's `ic-reactor.json` or from
+ * `@ic-reactor/vite-plugin` options — that is, from a file in a repository the
+ * user may have merely cloned. The pipeline turns those values into filesystem
+ * paths it recursively deletes and into source text it writes into the user's
+ * bundle, so they are treated as untrusted input rather than as configuration.
  *
- * Parses Candid .did files to extract service method signatures.
- * Used by the CLI for listing methods and by advanced generators.
+ * Validation lives here, at the pipeline's own entry point, rather than in the
+ * CLI's interactive prompt: the prompt only covers one of the three entry paths
+ * (hand-edited config and plugin options bypass it entirely).
  */
-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;
+
+/**
+ * Thrown when a canister config would produce an unsafe path or unsafe
+ * generated source. Callers convert this into a `PipelineResult` error.
+ */
+declare class CodegenConfigError extends Error {
+    readonly name = "CodegenConfigError";
+    constructor(message: string);
 }
 /**
- * Extract method information from raw Candid source text.
+ * Characters allowed in a canister name.
+ *
+ * A canister name becomes a directory segment, so this excludes path
+ * separators, quotes, whitespace and control characters. It deliberately does
+ * NOT require a leading letter: `dfx` places no restriction on canister names,
+ * and real projects use `_private` and `my.canister`, both of which derive
+ * perfectly good identifiers. Identifier validity is enforced separately, on
+ * the *derived* names, by {@link assertSafeCanisterName}.
+ */
+declare const CANISTER_NAME_PATTERN: RegExp;
+/**
+ * Assert that a canister name is safe to use as a path segment and as the stem
+ * of a generated identifier.
+ *
+ * Rejecting a leading digit here is what stops `2048_game` from reaching the
+ * generator, where it would become `export const 2048GameReactor` — invalid
+ * TypeScript emitted with a success status.
+ */
+declare function assertSafeCanisterName(name: unknown): asserts name is string;
+/**
+ * Assert that a module specifier we interpolate into an `import` statement is a
+ * relative path or a bare package name — never a URL.
+ *
+ * A `https://…` specifier here would make the generated module pull code from a
+ * remote host at import time, inside the user's own bundle.
+ */
+declare function assertSafeModuleSpecifier(label: string, specifier: unknown): asserts specifier is string;
+/**
+ * Derive the declarations file stem from a `.did` path and assert it is usable
+ * both as a file name and as the tail of the import specifier we emit.
+ *
+ * `path.basename` is happy to hand back `"."` or `".."`: a `didFile` of
+ * `"canisters/.."` makes the generated reactor `import … from
+ * "./declarations/.."`, a *directory* reference — reported as a successful
+ * generation, rejected by the consumer's bundler. Validating the derived
+ * specifier here is the same treatment `clientManagerPath` gets, for the same
+ * reason: it is config-supplied text that ends up inside an `import`.
+ */
+declare function resolveDeclarationsBaseName(didFile: unknown): string;
+/** Reactor classes the generator knows how to emit an import for. */
+declare const REACTOR_CLASS_NAMES: readonly ReactorClassName[];
+/** Runtime targets the generator knows how to emit. */
+declare const CODEGEN_TARGETS: readonly CodegenTarget[];
+/**
+ * Assert a config value is one of a closed set.
+ *
+ * `mode` and `target` are interpolated into emitted source as bare identifiers
+ * and module specifiers, so an unrecognized value is not merely unsupported —
+ * it is injected.
+ */
+declare function assertOneOf<T extends string>(label: string, value: unknown, allowed: readonly T[]): asserts value is T;
+/**
+ * Assert that an already-resolved absolute path lies inside `projectRoot`.
+ *
+ * Containment is decided on the real on-disk locations: `path.resolve` does not
+ * follow symlinks, so a purely lexical comparison can be walked out of via a
+ * symlink placed inside the project root.
  *
- * Compiles the Candid to JS and inspects the IDL.Service definition.
+ * @param original - the path as the user wrote it, for the error message
  */
-declare function extractMethods(didContent: string): MethodInfo[];
+declare function assertContainedPath(label: string, resolved: string, projectRoot: string, original?: string): void;
 /**
- * Parse a .did file from disk and return its methods.
+ * Resolve `outDir` against `projectRoot` and assert the result stays inside it.
  *
- * @throws if the file does not exist or fails to parse
+ * The pipeline recursively deletes `<outDir>/declarations` before every
+ * generation, so an `outDir` that escapes the project root turns a config file
+ * into an arbitrary-directory delete.
  */
-declare function parseDIDFile(didFilePath: string): MethodInfo[];
+declare function resolveContainedOutDir(label: string, outDir: unknown, projectRoot: string): string;
+interface ValidatedCanisterPaths {
+    /** The validated canister name. */
+    name: string;
+    /** Absolute output directory, guaranteed to be inside `projectRoot`. */
+    outDir: string;
+    /** Validated module specifier for the client manager import. */
+    clientManagerPath: string;
+}
+interface ValidateCanisterConfigOptions {
+    name: unknown;
+    /** Per-canister `outDir`, if the config sets one. */
+    canisterOutDir?: unknown;
+    /** Global `outDir`; the canister name is appended to it when used. */
+    globalOutDir: unknown;
+    clientManagerPath: unknown;
+    projectRoot: string;
+    /** Resolved reactor class (`canisterConfig.mode`), if the config sets one. */
+    mode?: unknown;
+    /** Resolved runtime target (`canisterConfig.target` / global `target`). */
+    target?: unknown;
+}
+/**
+ * Validate one canister's config and return the resolved, contained paths the
+ * pipeline should use.
+ *
+ * Call this before any filesystem work: it is the single choke point that all
+ * three entry paths (CLI, vite plugin, direct API) share.
+ */
+declare function assertSafeCanisterConfig(options: ValidateCanisterConfigOptions): ValidatedCanisterPaths;
 
 /**
  * Declarations Generator
@@ -197,17 +288,17 @@ interface DeclarationsGeneratorResult {
     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.
- */
 declare function generateDeclarations(options: DeclarationsGeneratorOptions): Promise<DeclarationsGeneratorResult>;
 /**
  * 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.
  */
-declare function declarationsExist(outDir: string, canisterName: string): boolean;
+declare function declarationsExist(outDir: string, canisterName: string, didFile?: string): boolean;
 
 /**
  * Reactor File Generator
@@ -286,4 +377,4 @@ interface ClientGeneratorOptions {
  */
 declare function generateClientFile(options?: ClientGeneratorOptions): string;
 
-export { type CanisterConfig, type ClientGeneratorOptions, type CodegenConfig, type CodegenTarget, type DeclarationsGeneratorOptions, type DeclarationsGeneratorResult, type GeneratorResult, type MethodInfo, type MethodType, type PipelineOptions, type PipelineResult, type ReactorClassName, type ReactorGeneratorOptions, declarationsExist, extractMethods, generateClientFile, generateDeclarations, generateReactorEntryFile, generateReactorFile, getReactorName, getServiceTypeName, parseDIDFile, runCanisterPipeline, toPascalCase };
+export { CANISTER_NAME_PATTERN, CODEGEN_TARGETS, type CanisterConfig, type ClientGeneratorOptions, type CodegenConfig, CodegenConfigError, type CodegenTarget, type DeclarationsGeneratorOptions, type DeclarationsGeneratorResult, type GeneratorResult, type PipelineOptions, type PipelineResult, REACTOR_CLASS_NAMES, type ReactorClassName, type ReactorGeneratorOptions, type ValidateCanisterConfigOptions, type ValidatedCanisterPaths, assertContainedPath, assertOneOf, assertSafeCanisterConfig, assertSafeCanisterName, assertSafeModuleSpecifier, declarationsExist, generateClientFile, generateDeclarations, generateReactorEntryFile, generateReactorFile, getReactorName, getServiceTypeName, resolveContainedOutDir, resolveDeclarationsBaseName, runCanisterPipeline, toPascalCase };