genoc 0.3.0 → 0.4.0

package/dist/cli/impl.js

@@ -1,49 +1,199 @@
-import { generateFullOutput } from '../generator/client-generator.js';
 import { load } from '../parser/spec-reader.js';
-import { validateSpec } from '../parser/validators.js';
-import { defaultRegistry } from '../parser/version/index.js';
+import { resolveVersion, validateSpec } from '../parser/version/index.js';
+import { generateFullOutput } from '../pipeline.js';
 import { assertValidProxyUrl } from '../utils/proxy.js';
+import { loadConfigFile } from './config-loader.js';
 import { UserError } from './errors.js';
+/**
+ * Compare-to-default table for flags that declare a default in app.ts.
+ *
+ * A defaulted flag counts as "explicitly passed" only when its value differs
+ * from the declared default. KNOWN LIMITATION: an explicitly-passed flag whose
+ * value equals the declared default (e.g. `--method-name-strategy path-based`)
+ * is indistinguishable from an omitted flag, so a config-file value wins in
+ * that case. This is pinned by a characterization test.
+ *
+ * `strictVersion` avoids this limitation entirely: it is declared WITHOUT a
+ * default (`strictVersion?: boolean`), so `undefined` reliably means "not
+ * passed" and any explicit value — including `true` — beats the file value.
+ */
+const FLAG_DEFAULTS = {
+    methodNameStrategy: 'path-based',
+    strictVersion: true,
+};
+function mergeExplicitFlags(flags) {
+    return {
+        outputDir: flags.outputDir,
+        methodNameStrategy: flags.methodNameStrategy === FLAG_DEFAULTS.methodNameStrategy
+            ? undefined
+            : flags.methodNameStrategy,
+        specVersion: flags.specVersion,
+        strictVersion: flags.strictVersion,
+        runtimeImportPath: flags.runtimeImportPath,
+        proxy: flags.proxy,
+    };
+}
+function buildTarget(name, input, cli, file) {
+    const outputDir = cli.outputDir ?? file?.outputDir;
+    if (outputDir === undefined) {
+        throw new UserError('No output directory provided. Pass --output-dir, or set "outputDir" in a config file ' +
+            '(.genocrc.yml / .genocrc.json).');
+    }
+    return {
+        name,
+        input,
+        outputDir,
+        methodNameStrategy: cli.methodNameStrategy ?? file?.methodNameStrategy ?? FLAG_DEFAULTS.methodNameStrategy,
+        specVersion: cli.specVersion ?? file?.specVersion,
+        strictVersion: cli.strictVersion ?? file?.strictVersion ?? FLAG_DEFAULTS.strictVersion,
+        runtimeImportPath: cli.runtimeImportPath ?? file?.runtimeImportPath,
+        proxy: cli.proxy ?? file?.proxy,
+    };
+}
+/**
+ * Display name for a target that does not come from a `clients` map entry:
+ * the spec filename base (`petstore.yaml` -> `petstore`, URL last segment for
+ * remote specs). Chosen over the outputDir basename because several targets
+ * can share an input spec, but the input is what identifies the client being
+ * generated in the failure/aggregation output.
+ */
+export function targetNameFromInput(input) {
+    const withoutQuery = input.split('?')[0] ?? input;
+    const base = withoutQuery.split(/[\\/]/).pop() ?? withoutQuery;
+    const dot = base.lastIndexOf('.');
+    return dot > 0 ? base.slice(0, dot) : base;
+}
+function processCwd(proc) {
+    const cwd = proc.cwd;
+    return cwd === undefined ? process.cwd() : cwd.call(proc);
+}
+async function resolveTargets(flags, spec, context) {
+    const loaded = await loadConfigFile({
+        explicitPath: flags.config,
+        searchDir: processCwd(context.process),
+    });
+    const cli = mergeExplicitFlags(flags);
+    if (loaded !== null) {
+        const { config, filepath } = loaded;
+        if ('clients' in config) {
+            if (spec !== undefined) {
+                throw new UserError(`Config file ${filepath} defines named clients; a spec argument cannot be combined ` +
+                    'with it. Use --project <name> to select one client, or omit the spec argument to run all clients.');
+            }
+            const names = Object.keys(config.clients);
+            if (flags.project !== undefined) {
+                const entry = config.clients[flags.project];
+                if (entry === undefined) {
+                    throw new UserError(`Unknown client name "${flags.project}" for --project. Available clients: ${names.join(', ')}`);
+                }
+                return {
+                    targets: [buildTarget(flags.project, entry.input, cli, entry)],
+                    configDriven: true,
+                };
+            }
+            if (cli.outputDir !== undefined) {
+                throw new UserError(`--output-dir cannot be combined with running all clients from config file ${filepath}: ` +
+                    'every client would be written to the same directory. Use --project <name> to select a ' +
+                    'single client, or remove --output-dir.');
+            }
+            const targets = names.map((name) => buildTarget(name, config.clients[name].input, cli, config.clients[name]));
+            return { targets, configDriven: true };
+        }
+        if (flags.project !== undefined) {
+            throw new UserError(`Config file ${filepath} defines no clients; --project requires a multi-client config ` +
+                '(a "clients" map).');
+        }
+        return resolveFlatOrSingleTarget(spec, cli, config, true);
+    }
+    if (flags.project !== undefined) {
+        throw new UserError('No config file found; --project requires a config file (.genocrc.yml / .genocrc.json) ' +
+            'that defines clients.');
+    }
+    return resolveFlatOrSingleTarget(spec, cli, undefined, false);
+}
+function resolveFlatOrSingleTarget(spec, cli, flat, configDriven) {
+    const input = spec ?? flat?.input;
+    if (input === undefined) {
+        if (cli.outputDir === undefined && flat?.outputDir === undefined) {
+            throw new UserError('No spec input and no output directory were provided. Pass a spec path as the positional ' +
+                'argument and --output-dir, or use a config file (.genocrc.yml / .genocrc.json) that ' +
+                'provides "input" and "outputDir".');
+        }
+        throw new UserError('No spec input provided. Pass a spec path as the positional argument, or set "input" in a ' +
+            'config file (.genocrc.yml / .genocrc.json).');
+    }
+    return {
+        targets: [buildTarget(targetNameFromInput(input), input, cli, flat)],
+        configDriven,
+    };
+}
+async function runOneTarget(target, context) {
+    if (target.proxy) {
+        try {
+            assertValidProxyUrl(target.proxy);
+        }
+        catch (err) {
+            throw new UserError(err.message);
+        }
+    }
+    context.process.stdout.write(`Loading spec from ${target.input}...\n`);
+    const doc = await load(target.input, { proxy: target.proxy });
+    context.process.stdout.write(`Loaded OpenAPI ${doc.openapi} spec\n`);
+    const override = target.specVersion;
+    if (override !== undefined && override !== '3.0' && override !== '3.1') {
+        throw new Error(`No strategy registered for version: ${override}`);
+    }
+    const profile = resolveVersion(doc, override);
+    if (override !== undefined &&
+        target.strictVersion !== false &&
+        profile.detected !== profile.effective) {
+        context.process.stderr.write(`Warning: Specified version ${override} does not match detected version ${profile.detected}\n`);
+    }
+    try {
+        validateSpec(doc, profile.effective);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new UserError(message);
+    }
+    const config = {
+        input: target.input,
+        outputDir: target.outputDir,
+        methodNameStrategy: target.methodNameStrategy,
+        strictVersion: target.strictVersion,
+        runtimeImportPath: target.runtimeImportPath,
+    };
+    const { preserveRefSiblings } = profile;
+    context.process.stdout.write('Generating client...\n');
+    await generateFullOutput(doc, config, { preserveRefSiblings });
+    context.process.stdout.write(`✅ Success! Generated client files:\n`);
+    context.process.stdout.write(`  - ${target.outputDir}/contracts.ts\n`);
+    context.process.stdout.write(`  - ${target.outputDir}/client.ts\n`);
+    context.process.stdout.write(`  - ${target.outputDir}/index.ts\n`);
+}
 export default async function (flags, spec) {
     try {
-        if (flags.proxy) {
+        const { targets, configDriven } = await resolveTargets(flags, spec, this);
+        const failures = [];
+        for (const target of targets) {
             try {
-                assertValidProxyUrl(flags.proxy);
+                await runOneTarget(target, this);
             }
-            catch (err) {
-                throw new UserError(err.message);
+            catch (error) {
+                if (!configDriven) {
+                    throw error;
+                }
+                const message = error instanceof Error ? error.message : String(error);
+                failures.push({ name: target.name, message });
             }
         }
-        this.process.stdout.write(`Loading spec from ${spec}...\n`);
-        const doc = await load(spec, { proxy: flags.proxy });
-        this.process.stdout.write(`Loaded OpenAPI ${doc.openapi} spec\n`);
-        const strategy = flags.specVersion
-            ? defaultRegistry.get(flags.specVersion)
-            : defaultRegistry.detectAndResolve(doc);
-        if (flags.specVersion && flags.strictVersion !== false) {
-            const detected = defaultRegistry.detectAndResolve(doc);
-            if (detected.version() !== flags.specVersion) {
-                this.process.stderr.write(`Warning: Specified version ${flags.specVersion} does not match detected version ${detected.version()}\n`);
-            }
+        if (failures.length > 0) {
+            const lines = failures.map((failure) => `× client "${failure.name}": ${failure.message}`);
+            throw new UserError(`${lines.join('\n')}\n${failures.length}/${targets.length} targets failed`);
+        }
+        if (configDriven) {
+            this.process.stdout.write(`Generated ${targets.length}/${targets.length} clients\n`);
         }
-        const validation = validateSpec(doc, strategy);
-        if (!validation.valid) {
-            throw new UserError(`Invalid OpenAPI specification:\n${validation.errors.map((e) => `  - ${e}`).join('\n')}`);
-        }
-        const config = {
-            input: spec,
-            outputDir: flags.outputDir,
-            methodNameStrategy: flags.methodNameStrategy || 'path-based',
-            specVersion: flags.specVersion,
-            strictVersion: flags.strictVersion,
-            runtimeImportPath: flags.runtimeImportPath,
-        };
-        const preserveRefSiblings = strategy.version() === '3.1';
-        this.process.stdout.write('Generating client...\n');
-        await generateFullOutput(doc, config, { preserveRefSiblings });
-        this.process.stdout.write(`✅ Success! Generated client files:\n`);
-        this.process.stdout.write(`  - ${flags.outputDir}/contracts.ts\n`);
-        this.process.stdout.write(`  - ${flags.outputDir}/client.ts\n`);
     }
     catch (error) {
         if (error instanceof UserError) {

package/dist/generator/client-generator.d.ts

@@ -1,21 +1,20 @@
+import type { AnalyzedSpec } from '../analyzer/types.js';
 import type { GeneratorConfig } from '../types/client.js';
-import type { OpenAPIDocument } from '../types/openapi.js';
-export type ApiClient = {
-    [key: string]: (...args: any[]) => Promise<any>;
-};
-/** Options for controlling generation behavior. */
-export interface GenerationOptions {
-    /** When true, sibling properties alongside $ref are preserved (OpenAPI 3.1 behavior). */
-    preserveRefSiblings?: boolean;
-}
 /**
- * Generate both the contracts and client file content from an OpenAPI document.
+ * Render the client and index barrel files from the analyzed model.
+ * Pure string assembly — reads ONLY the AnalyzedSpec plus config, never the
+ * raw spec or a resolver.
  */
-export declare function generateClient(doc: OpenAPIDocument, config: GeneratorConfig, options?: GenerationOptions): {
-    contracts: string;
+export declare function renderClient(analyzed: AnalyzedSpec, config: GeneratorConfig): {
     client: string;
+    index: string;
 };
 /**
- * Generate and write both output files to disk.
+ * Generate the contracts, client, and index barrel file content from the
+ * analyzed model. Thin orchestration over the two renderers.
  */
-export declare function generateFullOutput(doc: OpenAPIDocument, config: GeneratorConfig, options?: GenerationOptions): Promise<void>;
+export declare function generateOutput(analyzed: AnalyzedSpec, config: GeneratorConfig): {
+    contracts: string;
+    client: string;
+    index: string;
+};

package/dist/generator/client-generator.js

@@ -1,37 +1,12 @@
-import { mkdir, writeFile } from 'fs/promises';
-import { join } from 'path';
-import { analyzePaths } from '../analyzer/path-analyzer.js';
-import { RefResolver } from '../parser/ref-resolver.js';
-import { DEFAULT_RUNTIME_IMPORT_PATH, getOperationTypePrefix, getSuccessType, getErrorType, makeHeader, } from '../utils/generator-helpers.js';
-import { generateContracts } from './contracts-generator.js';
+import { DEFAULT_RUNTIME_IMPORT_PATH, makeHeader } from '../utils/generator-helpers.js';
+import { clientImportedNames, clientValueImports, getErrorType, getSuccessType, operationEmissions, } from '../utils/operation-naming.js';
+import { renderContracts } from './contracts-generator.js';
 import { generateMethod } from './method-generator.js';
 function collectImportTypes(operations) {
     const types = new Set();
     for (const op of operations) {
-        const prefix = getOperationTypePrefix(op);
-        if (op.queryParams.length > 0) {
-            types.add(`${prefix}Query`);
-        }
-        if (op.headerParams.length > 0) {
-            types.add(`${prefix}Headers`);
-        }
-        if (op.requestBody?.schema) {
-            types.add(`${prefix}Body`);
-        }
-        const successType = getSuccessType(op);
-        if (successType !== 'void' && successType !== 'unknown' && /^[A-Z]/.test(successType)) {
-            types.add(successType);
-        }
-        const errorResponses = op.responses.filter((r) => !r.isSuccess && r.statusCode !== 'default');
-        for (const errResp of errorResponses) {
-            types.add(`${prefix}Error${errResp.statusCode}`);
-        }
-        const errorType = getErrorType(op);
-        if (errorType !== 'never') {
-            types.add(errorType);
-        }
-        if (op.responses.some((r) => !r.isSuccess && r.statusCode === 'default')) {
-            types.add(`${prefix}DefaultError`);
+        for (const name of clientImportedNames(op)) {
+            types.add(name);
         }
     }
     // oxlint-disable-next-line unicorn/no-array-sort
@@ -39,21 +14,18 @@ function collectImportTypes(operations) {
 }
 function buildClientMethodBody(op) {
     const successType = getSuccessType(op);
+    const emissions = operationEmissions(op);
     let urlTemplate = op.path;
     for (const param of op.pathParams) {
         urlTemplate = urlTemplate.replace(`{${param.name}}`, `\${encodeURIComponent(${param.name})}`);
     }
     const urlExpr = `\`${urlTemplate}\``;
-    const prefix = getOperationTypePrefix(op);
-    const hasDefaultResponse = op.responses.some((r) => !r.isSuccess && r.statusCode === 'default');
-    const errorResponses = op.responses.filter((r) => !r.isSuccess && r.statusCode !== 'default');
     const errorCheckLines = [];
-    for (const errResp of errorResponses) {
-        const status = errResp.statusCode;
-        errorCheckLines.push(`if (result.status === ${status}) throw new ApiError(${status}, result.data as ${prefix}Error${status}, result.message ?? \`Request failed with status ${status}\`);`);
+    for (const statusError of emissions.statusErrors) {
+        errorCheckLines.push(`if (result.status === ${statusError.status}) throw new ApiError(${statusError.status}, result.data as ${statusError.name}, result.message ?? \`Request failed with status ${statusError.status}\`);`);
     }
-    if (hasDefaultResponse) {
-        errorCheckLines.push(`throw new DefaultApiError(result.status, result.data as ${prefix}DefaultError, result.message ?? \`Request failed with status \${result.status}\`);`);
+    if (emissions.defaultError !== undefined) {
+        errorCheckLines.push(`throw new DefaultApiError(result.status, result.data as ${emissions.defaultError}, result.message ?? \`Request failed with status \${result.status}\`);`);
     }
     else {
         errorCheckLines.push('throw new UnspecifiedApiError(result.status, result.data, result.message ?? `Request failed with status ${result.status}`);');
@@ -96,26 +68,21 @@ function buildClientMethodBody(op) {
         opts.push('headers');
     }
     const lines = [];
-    if (op.requestBody?.isMultipart && op.requestBody.schema) {
-        const schema = op.requestBody.schema;
-        const requiredSet = new Set((schema?.required ?? []));
-        const properties = schema.properties ?? {};
-        const propNames = Object.keys(properties);
+    if (op.requestBody?.isMultipart && op.fileUploadProperties !== undefined) {
         const bodyRequired = op.requestBody.required;
         const formDataLines = [];
         formDataLines.push('const formData = new FormData();');
-        for (const propName of propNames) {
-            const propSchema = properties[propName];
-            const isArrayBinary = propSchema?.type === 'array' && propSchema?.items?.format === 'binary';
-            if (propSchema?.format === 'binary') {
-                if (requiredSet.has(propName)) {
+        for (const prop of op.fileUploadProperties) {
+            const propName = prop.name;
+            if (prop.kind === 'file') {
+                if (prop.required) {
                     formDataLines.push(`formData.append("${propName}", body.${propName}.data, body.${propName}.filename);`);
                 }
                 else {
                     formDataLines.push(`if (body.${propName} !== undefined) formData.append("${propName}", body.${propName}.data, body.${propName}.filename);`);
                 }
             }
-            else if (isArrayBinary) {
+            else if (prop.kind === 'file-array') {
                 formDataLines.push(`if (body.${propName} !== undefined) { for (const file of body.${propName}) { formData.append("${propName}", file.data, file.filename); } }`);
             }
             else {
@@ -160,17 +127,7 @@ function buildClientFile(operations, version, runtimeImportPath = DEFAULT_RUNTIM
     const lines = [];
     lines.push(makeHeader(version));
     const importTypes = collectImportTypes(operations);
-    const needsDefaultApiError = operations.some((op) => op.responses.some((r) => !r.isSuccess && r.statusCode === 'default'));
-    const valueImports = [
-        'ApiError',
-        'UnspecifiedApiError',
-        'ErrorResponse',
-        'StreamResponse',
-        'RequesterFailError',
-    ];
-    if (needsDefaultApiError) {
-        valueImports.push('DefaultApiError');
-    }
+    const valueImports = clientValueImports(operations);
     const typeImports = importTypes.filter((t) => !valueImports.includes(t));
     lines.push(`import { ${valueImports.join(', ')} } from './contracts.js';`);
     if (typeImports.length > 0) {
@@ -206,8 +163,8 @@ function buildClientFile(operations, version, runtimeImportPath = DEFAULT_RUNTIM
         const returnType = sig.substring(closeParenColon + 3);
         const methodName = method.name;
         const errorType = getErrorType(op);
-        const errorResponses = op.responses.filter((r) => !r.isSuccess && r.statusCode !== 'default');
-        const errorCodes = errorResponses.map((r) => r.statusCode);
+        const emissions = operationEmissions(op);
+        const errorCodes = emissions.statusErrors.map((statusError) => statusError.status);
         const errorCodeArray = errorCodes.length > 0 ? `[${errorCodes.join(', ')}] as const` : '[] as const';
         const indentedBody = body
             .split('\n')
@@ -227,24 +184,35 @@ function buildClientFile(operations, version, runtimeImportPath = DEFAULT_RUNTIM
     return lines.join('\n');
 }
 /**
- * Generate both the contracts and client file content from an OpenAPI document.
+ * Generate the `index.ts` barrel file content: re-exports everything from the
+ * generated contracts and client files.
  */
-export function generateClient(doc, config, options) {
-    const resolver = new RefResolver(doc, undefined, {
-        preserveRefSiblings: options?.preserveRefSiblings,
-    });
+function buildIndexFile(version) {
+    const lines = [];
+    lines.push(makeHeader(version));
+    lines.push('');
+    lines.push(`export * from './contracts.js';`);
+    lines.push(`export * from './client.js';`);
+    return lines.join('\n') + '\n';
+}
+/**
+ * Render the client and index barrel files from the analyzed model.
+ * Pure string assembly — reads ONLY the AnalyzedSpec plus config, never the
+ * raw spec or a resolver.
+ */
+export function renderClient(analyzed, config) {
     const runtimeImportPath = config.runtimeImportPath ?? DEFAULT_RUNTIME_IMPORT_PATH;
-    const contracts = generateContracts(doc, resolver, runtimeImportPath);
-    const operations = analyzePaths(doc, resolver, config.methodNameStrategy ?? 'path-based');
-    const client = buildClientFile(operations, doc.openapi, runtimeImportPath);
-    return { contracts, client };
+    const client = buildClientFile(analyzed.operations, analyzed.specVersion, runtimeImportPath);
+    const index = buildIndexFile(analyzed.specVersion);
+    return { client, index };
 }
 /**
- * Generate and write both output files to disk.
+ * Generate the contracts, client, and index barrel file content from the
+ * analyzed model. Thin orchestration over the two renderers.
  */
-export async function generateFullOutput(doc, config, options) {
-    const { contracts, client } = generateClient(doc, config, options);
-    await mkdir(config.outputDir, { recursive: true });
-    await writeFile(join(config.outputDir, 'contracts.ts'), contracts, 'utf-8');
-    await writeFile(join(config.outputDir, 'client.ts'), client, 'utf-8');
+export function generateOutput(analyzed, config) {
+    const runtimeImportPath = config.runtimeImportPath ?? DEFAULT_RUNTIME_IMPORT_PATH;
+    const contracts = renderContracts(analyzed, runtimeImportPath);
+    const { client, index } = renderClient(analyzed, config);
+    return { contracts, client, index };
 }

package/dist/generator/contracts-generator.d.ts

@@ -1,15 +1,17 @@
-import { RefResolver } from '../parser/ref-resolver.js';
-import type { OpenAPIDocument } from '../types/openapi.js';
+import type { AnalyzedSpec } from '../analyzer/types.js';
 /**
- * Generate the complete `*.contracts.ts` file content as a string.
+ * Render the complete `*.contracts.ts` file content from the analyzed model.
+ * Pure string assembly — reads ONLY the AnalyzedSpec, never the raw spec or
+ * a resolver.
  *
  * Sections produced:
  * 1. Header comment
- * 2. Schema types from `components/schemas`
- * 3. Query parameter types per operation
- * 4. Header parameter types per operation
- * 5. Request body types per operation
- * 6. Response / error types per operation
+ * 2. Schema types from `components/schemas` (finished model entries)
+ * 3. Security scheme types (finished model entries; `SecuritySchemes` union
+ *    when more than one)
+ * 4. Server variable types (finished model entries)
+ * 5. `FileInput` when any operation uploads files
+ * 6. Operation-derived types (finished emission lines from the model)
  * 7. Runtime re-export block (shared classes from the genoc runtime package)
  */
-export declare function generateContracts(doc: OpenAPIDocument, resolver: RefResolver, runtimeImportPath?: string): string;
+export declare function renderContracts(analyzed: AnalyzedSpec, runtimeImportPath?: string): string;