genoc 0.2.0 → 0.4.0

package/dist/analyzer/path-analyzer.js

@@ -1,63 +1,16 @@
 import { RefResolver } from '../parser/ref-resolver.js';
-import { sanitizeTypeName } from '../utils/generator-helpers.js';
+import { isBinaryContentType } from '../utils/generator-helpers.js';
+import { getOperationTypePrefix } from '../utils/operation-naming.js';
 import { getMethodName } from './naming.js';
 const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'options', 'head', 'trace'];
-function isRef(obj) {
-    return obj !== null && typeof obj === 'object' && '$ref' in obj;
-}
-function isBinaryContentType(ct) {
-    if (ct === 'application/octet-stream')
-        return true;
-    if (ct.startsWith('image/'))
-        return true;
-    if (ct.startsWith('video/'))
-        return true;
-    if (ct.startsWith('audio/'))
-        return true;
-    return false;
-}
-function schemaToTsType(schema, resolver) {
+/**
+ * Resolve a possibly-$ref-ed schema and check for an exact top-level `format: binary`
+ * match. Top-level only — intentionally no deep-walk into items/allOf/oneOf/anyOf.
+ */
+function isBinarySchema(schema, resolver) {
     if (!schema)
-        return 'unknown';
-    if (isRef(schema)) {
-        const resolved = resolver.resolve(schema);
-        const refStr = schema.$ref;
-        const lastSegment = sanitizeTypeName(refStr.split('/').pop());
-        if (lastSegment && resolved.type) {
-            return lastSegment;
-        }
-        return lastSegment ?? 'unknown';
-    }
-    const s = schema;
-    if (s.type === undefined)
-        return 'unknown';
-    if (Array.isArray(s.type)) {
-        const nonNull = s.type.filter((t) => t !== 'null');
-        if (nonNull.length === 0)
-            return 'null';
-        return schemaToTsType({ ...s, type: nonNull[0] }, resolver);
-    }
-    switch (s.type) {
-        case 'string':
-            return 'string';
-        case 'integer':
-        case 'number':
-            return 'number';
-        case 'boolean':
-            return 'boolean';
-        case 'array':
-            if (s.items) {
-                const itemType = schemaToTsType(s.items, resolver);
-                return `${itemType}[]`;
-            }
-            return 'unknown[]';
-        case 'object':
-            return 'object';
-        case 'null':
-            return 'null';
-        default:
-            return 'unknown';
-    }
+        return false;
+    return resolver.resolveSchema(schema).format === 'binary';
 }
 function resolveParameter(param, resolver) {
     return resolver.resolve(param);
@@ -75,7 +28,6 @@ function analyzeParameter(param, resolver) {
         in: param.in,
         required: param.required ?? param.in === 'path',
         schema,
-        tsType: schemaToTsType(param.schema, resolver),
         description: param.description,
         deprecated: param.deprecated,
         example: param.example,
@@ -100,28 +52,40 @@ function mergeParameters(pathItemParams, operationParams, resolver) {
     }
     return merged;
 }
+/**
+ * Analyze one request body. Returns the structural facts plus the RAW
+ * (possibly `$ref`) first-content schema as a separate value — the schema is
+ * analyzer-internal translation input for `analyze()` and does not travel on
+ * the `AnalyzedRequestBody` seam.
+ */
 function analyzeRequestBody(body, resolver) {
     if (!body)
         return undefined;
     const resolved = resolveRequestBody(body, resolver);
     const contentTypes = Object.keys(resolved.content);
     let schema;
-    let tsType = 'unknown';
     if (contentTypes.length > 0) {
         const firstContent = resolved.content[contentTypes[0]];
         if (firstContent?.schema) {
             schema = firstContent.schema;
-            tsType = schemaToTsType(schema, resolver);
         }
     }
     const isMultipart = contentTypes.length > 0 && contentTypes[0] === 'multipart/form-data';
+    // Contract with the generators: multipart bodies keep the FileInput shape
+    // and must never be Blob-ified, so the binary signals are bypassed.
+    const isBinary = isMultipart
+        ? false
+        : contentTypes.some(isBinaryContentType) || isBinarySchema(schema, resolver);
     return {
-        required: resolved.required ?? false,
-        contentTypes,
-        schema,
-        tsType,
-        isMultipart,
-        description: resolved.description,
+        requestBody: {
+            required: resolved.required ?? false,
+            contentTypes,
+            hasSchema: schema !== undefined,
+            isMultipart,
+            isBinary,
+            description: resolved.description,
+        },
+        rawSchema: schema,
     };
 }
 function analyzeResponses(responses, resolver) {
@@ -129,7 +93,6 @@ function analyzeResponses(responses, resolver) {
     for (const [statusCode, response] of Object.entries(responses)) {
         const resolved = resolveResponse(response, resolver);
         let schema;
-        let tsType = 'unknown';
         let contentTypes = [];
         if (resolved.content) {
             contentTypes = Object.keys(resolved.content);
@@ -137,24 +100,22 @@ function analyzeResponses(responses, resolver) {
                 const firstContent = resolved.content[contentTypes[0]];
                 if (firstContent?.schema) {
                     schema = firstContent.schema;
-                    tsType = schemaToTsType(schema, resolver);
                 }
             }
         }
         // Empty-body success responses → void
-        if (tsType === 'unknown' &&
+        const isVoid = schema === undefined &&
             statusCode.startsWith('2') &&
-            (!resolved.content || contentTypes.length === 0)) {
-            tsType = 'void';
-        }
-        const isBinary = contentTypes.length > 0 && isBinaryContentType(contentTypes[0]);
+            (!resolved.content || contentTypes.length === 0);
+        const isBinary = contentTypes.length > 0 &&
+            (isBinaryContentType(contentTypes[0]) || isBinarySchema(schema, resolver));
         result.push({
             statusCode,
             description: resolved.description,
             schema,
-            tsType,
             isSuccess: statusCode.startsWith('2'),
             isBinary,
+            isVoid,
         });
     }
     return result;
@@ -183,18 +144,21 @@ function categorizeParameters(params) {
     return { pathParams, queryParams, headerParams, cookieParams };
 }
 /**
- * Analyze all paths and operations from an OpenAPI document into structured data
- * for code generation.
+ * Analyze all paths and operations from an OpenAPI document into structured
+ * data for code generation, carrying the raw request body schemas alongside.
  *
  * @param doc - The parsed and validated OpenAPI document
  * @param resolver - A RefResolver for resolving $ref pointers
  * @param strategy - Method naming strategy (defaults to 'path-based')
- * @returns Array of AnalyzedOperation objects
+ * @returns Operations with parallel raw request body schemas
  */
-export function analyzePaths(doc, resolver, strategy = 'path-based') {
+export function analyzePathsDetailed(doc, resolver, strategy = 'path-based') {
     const operations = [];
+    const requestBodySchemas = [];
     if (!doc.paths)
-        return operations;
+        return { operations, requestBodySchemas };
+    const usedTypePrefixes = new Set();
+    const usedMethodNames = new Set();
     for (const [urlPath, pathItem] of Object.entries(doc.paths)) {
         for (const method of HTTP_METHODS) {
             const operation = pathItem[method];
@@ -203,7 +167,7 @@ export function analyzePaths(doc, resolver, strategy = 'path-based') {
             const mergedParams = mergeParameters(pathItem.parameters, operation.parameters, resolver);
             const analyzedParams = mergedParams.map((p) => analyzeParameter(p, resolver));
             const categorized = categorizeParameters(analyzedParams);
-            const requestBody = analyzeRequestBody(operation.requestBody, resolver);
+            const requestBodyResult = analyzeRequestBody(operation.requestBody, resolver);
             const responses = analyzeResponses(operation.responses, resolver);
             const methodName = getMethodName(method, urlPath, operation.operationId, strategy);
             operations.push({
@@ -216,10 +180,47 @@ export function analyzePaths(doc, resolver, strategy = 'path-based') {
                 deprecated: operation.deprecated ?? false,
                 tags: operation.tags ?? [],
                 ...categorized,
-                requestBody,
+                requestBody: requestBodyResult?.requestBody,
                 responses,
             });
+            requestBodySchemas.push(requestBodyResult?.rawSchema);
         }
     }
-    return operations;
+    // Dedupe type prefixes and method names so that distinct routes folding to
+    // the same identifier (e.g. "/weird" and "/weird-", or "/Weird" and
+    // "/weird") cannot produce duplicate exported types or client methods.
+    // Assignment relies on insertion order and the fixed HTTP_METHODS loop.
+    for (const op of operations) {
+        const baseTypePrefix = getOperationTypePrefix(op);
+        let typePrefix = baseTypePrefix;
+        let n = 2;
+        while (usedTypePrefixes.has(typePrefix)) {
+            typePrefix = `${baseTypePrefix}${n}`;
+            n += 1;
+        }
+        usedTypePrefixes.add(typePrefix);
+        op.typePrefix = typePrefix;
+        const baseMethodName = op.methodName;
+        let methodName = baseMethodName;
+        n = 2;
+        while (usedMethodNames.has(methodName)) {
+            methodName = `${baseMethodName}${n}`;
+            n += 1;
+        }
+        usedMethodNames.add(methodName);
+        op.methodName = methodName;
+    }
+    return { operations, requestBodySchemas };
+}
+/**
+ * Analyze all paths and operations from an OpenAPI document into structured
+ * data for code generation.
+ *
+ * @param doc - The parsed and validated OpenAPI document
+ * @param resolver - A RefResolver for resolving $ref pointers
+ * @param strategy - Method naming strategy (defaults to 'path-based')
+ * @returns Array of AnalyzedOperation objects
+ */
+export function analyzePaths(doc, resolver, strategy = 'path-based') {
+    return analyzePathsDetailed(doc, resolver, strategy).operations;
 }

package/dist/analyzer/schema-mapper.d.ts

@@ -17,11 +17,12 @@ export declare class SchemaMapper {
     private readonly discriminatorTargets;
     private readonly reservedNames;
     private readonly brandedTypes;
-    private static nullableWarned;
+    private nullableWarned;
+    private readonly warnSink;
     constructor(resolver: RefResolver, typeNameGenerator?: TypeNameGenerator, discriminatorTargets?: Map<string, {
         propertyName: string;
         literalValue: string;
-    }>, reservedNames?: Set<string>);
+    }>, reservedNames?: Set<string>, warnSink?: (message: string) => void);
     getBrandedTypes(): Map<string, {
         name: string;
         format: string;

package/dist/analyzer/schema-mapper.js

@@ -40,12 +40,22 @@ export class SchemaMapper {
     discriminatorTargets;
     reservedNames;
     brandedTypes = new Map();
-    static nullableWarned = false;
-    constructor(resolver, typeNameGenerator, discriminatorTargets, reservedNames) {
+    nullableWarned = false;
+    warnSink;
+    constructor(resolver, typeNameGenerator, discriminatorTargets, reservedNames, warnSink) {
+        // NOTE: discriminatorTargets must be keyed by names produced by the SAME
+        // (rename-aware) typeNameGenerator that resolves $refs. Passing targets
+        // keyed by raw schema names means renamed subtypes silently lose their
+        // `& { prop: 'literal' }` intersection in the generated output.
         this.resolver = resolver;
         this.typeNameGenerator = typeNameGenerator ?? defaultTypeNameGenerator;
         this.discriminatorTargets = discriminatorTargets ?? new Map();
         this.reservedNames = reservedNames ?? new Set();
+        this.warnSink =
+            warnSink ??
+                ((message) => {
+                    process.stderr.write(message);
+                });
     }
     getBrandedTypes() {
         return this.brandedTypes;
@@ -112,11 +122,9 @@ export class SchemaMapper {
         // TODO: Remove deprecated nullable warning and handling when OpenAPI 3.1 support is complete
         // The 'nullable' property is deprecated in OpenAPI 3.1 in favor of type arrays like ["string", "null"]
         // This warning should be removed once full type array support is implemented
-        if (s.nullable === true && !SchemaMapper.nullableWarned) {
-            // TODO: Replace with structured logging solution
-            // oxlint-disable-next-line no-console
-            console.warn('Warning: \'nullable\' is deprecated in OpenAPI 3.1. Use \'type: ["string", "null"]\' instead.');
-            SchemaMapper.nullableWarned = true;
+        if (s.nullable === true && !this.nullableWarned) {
+            this.warnSink('Warning: \'nullable\' is deprecated in OpenAPI 3.1. Use \'type: ["string", "null"]\' instead.');
+            this.nullableWarned = true;
         }
         if (s.enum !== undefined && s.enum.length > 0) {
             let tsType = this.mapEnumValues(s.enum);
@@ -237,7 +245,7 @@ export class SchemaMapper {
         }
     }
     resolveDiscriminatorInfo(schema, refStr) {
-        const schemaName = sanitizeTypeName(refStr.split('/').pop());
+        const schemaName = this.typeNameGenerator(refStr);
         const target = this.discriminatorTargets.get(schemaName);
         if (target)
             return target;

package/dist/analyzer/types.d.ts

@@ -0,0 +1,119 @@
+import type { RefResolver } from '../parser/ref-resolver.js';
+import type { MethodNameStrategy } from '../types/client.js';
+import type { AnalyzedOperation } from './path-analyzer.js';
+/**
+ * Finished (render-ready) type declaration for the contracts file: the emitted
+ * type name, its complete definition statement, and an optional type-level
+ * JSDoc block rendered above it.
+ */
+export interface TypeDeclaration {
+    /** Emitted type name (rename-aware). */
+    name: string;
+    /** Complete definition statement, e.g. `export type User = { … };`. */
+    definition: string;
+    /** Type-level JSDoc block, when the source carries renderable metadata. */
+    jsDoc?: string;
+}
+/**
+ * Finished security scheme type declaration (contracts Section 1b): the
+ * collision-deduped `{Name}Auth` type name, the rendered object type text,
+ * and the description-only JSDoc block ('' when absent).
+ */
+export interface SecuritySchemeTypeDeclaration {
+    /** Emitted `{Name}Auth` type name (sanitized, numbered on collision). */
+    name: string;
+    /** Rendered object type text — the `securitySchemeToTsType` output. */
+    tsType: string;
+    /** Description JSDoc block; '' when the scheme carries no description. */
+    jsDoc: string;
+}
+/**
+ * Finished server variable type declaration (contracts Section 1c). Names
+ * are index-aware over ALL `doc.servers` — `ServerParams` when the document
+ * declares a single server, `Server{i}Params` otherwise — so servers without
+ * variables still occupy an index.
+ */
+export interface ServerTypeDeclaration {
+    name: string;
+    /** Server URL, emitted as the `/** Server: url *\/` comment when present. */
+    url?: string;
+    /** Finished interface body lines — variable JSDoc comments and property lines, indentation included. */
+    propertyLines: string[];
+}
+/** Branded format type discovered by the schema mapper during translation. */
+export interface BrandedTypeDeclaration {
+    name: string;
+    format: string;
+    baseType: string;
+}
+/**
+ * One multipart `FileInput` property fact from the ref-resolving walk of a
+ * multipart request body ($refs followed; a resolved `format: binary`
+ * property is a `file`/`file-array`, not a `field`).
+ */
+export interface FileUploadPropertyFact {
+    /** Property name in the multipart schema. */
+    name: string;
+    /** Whether the property is listed in the schema's `required` array. */
+    required: boolean;
+    /** `file` → `FileInput`, `file-array` → `FileInput[]`, `field` → `string`. */
+    kind: 'file' | 'file-array' | 'field';
+}
+/**
+ * Analyzed operation plus its finished translation results.
+ *
+ * The structural fields are the plain `AnalyzedOperation`; the added fields
+ * carry the real-mapper output the contracts renderer emits verbatim.
+ */
+export interface FinishedOperation extends AnalyzedOperation {
+    /**
+     * Finished contracts-file emission lines for this operation (Sections 2–4:
+     * query/header/body/response/error types, with JSDoc attached), in emission
+     * order. Assembled by `analyze()`; `renderContracts` spills them unchanged.
+     */
+    contractsLines: string[];
+    /**
+     * Multipart `FileInput` property facts from the ref-resolving walk of the
+     * request body schema (`$ref`s followed; a resolved `format: binary`
+     * property is a `file`/`file-array`, not a `field`). Present exactly when
+     * the operation has a multipart body WITH a schema — an empty array means a
+     * zero-property body; `undefined` means no multipart schema (no FormData
+     * emission). Sole fact source for the client generator's FormData appends.
+     */
+    fileUploadProperties?: FileUploadPropertyFact[];
+}
+/**
+ * Single-pass analysis model of an OpenAPI document — the ONLY input every
+ * generator renderer consumes. Renderers get the model plus config; they never
+ * touch the raw spec or a `RefResolver`.
+ */
+export interface AnalyzedSpec {
+    /** `doc.openapi` verbatim (e.g. `"3.1.0"`) — feeds generated file headers. */
+    specVersion: string;
+    /** Operations with structural facts and finished contracts emission lines. */
+    operations: FinishedOperation[];
+    /**
+     * Section-1 component schema declarations as finished entries, in the
+     * pre-refactor emission order: topologically sorted schemas first, then
+     * discriminator `{Base}Variant` unions in discovery order.
+     */
+    schemaTypes: TypeDeclaration[];
+    /** Branded format types discovered during mapping, in discovery order. */
+    brandedTypes: BrandedTypeDeclaration[];
+    /** Any operation has a multipart request body → contracts emits `FileInput`. */
+    hasFileUpload: boolean;
+    /**
+     * Finished security scheme type declarations (`{Name}Auth`), in spec key
+     * order. The `SecuritySchemes` union is emitted when more than one exists.
+     */
+    securitySchemeTypes: SecuritySchemeTypeDeclaration[];
+    /** Finished server variable interface declarations, in spec order. */
+    serverTypes: ServerTypeDeclaration[];
+}
+/** Options for `analyze()`. */
+export interface AnalyzeOptions {
+    /** Resolver for `$ref` pointers; defaults to a fresh `RefResolver(doc)`. */
+    resolver?: RefResolver;
+    /** Method naming strategy; defaults to `'path-based'`. */
+    strategy?: MethodNameStrategy;
+}

package/dist/cli/app.d.ts

@@ -1,9 +1,12 @@
 interface Flags {
-    outputDir: string;
+    outputDir?: string;
     methodNameStrategy: 'path-based' | 'operationId' | 'operationId-with-fallback';
     specVersion?: string;
-    strictVersion: boolean;
+    strictVersion?: boolean;
     runtimeImportPath?: string;
+    proxy?: string;
+    config?: string;
+    project?: string;
 }
 export type AppFlags = Flags;
 export declare const app: import("@stricli/core").Application<import("@stricli/core").CommandContext>;

package/dist/cli/app.js

@@ -8,8 +8,9 @@ const command = buildCommand({
             outputDir: {
                 kind: 'parsed',
                 parse: String,
-                brief: 'Directory to write generated files',
+                brief: 'Directory to write generated files (or set outputDir in the config file)',
                 placeholder: 'dir',
+                optional: true,
             },
             methodNameStrategy: {
                 kind: 'enum',
@@ -26,8 +27,8 @@ const command = buildCommand({
             },
             strictVersion: {
                 kind: 'boolean',
-                default: true,
-                brief: 'Enable strict version checking',
+                brief: 'Warn when --spec-version mismatches the detected version (default: true)',
+                optional: true,
             },
             runtimeImportPath: {
                 kind: 'parsed',
@@ -36,14 +37,39 @@ const command = buildCommand({
                 optional: true,
                 placeholder: 'module',
             },
+            proxy: {
+                kind: 'parsed',
+                parse: String,
+                brief: 'HTTP(S) proxy URL for fetching specs (overrides HTTP_PROXY/HTTPS_PROXY env vars)',
+                optional: true,
+                placeholder: 'url',
+            },
+            config: {
+                kind: 'parsed',
+                parse: String,
+                brief: 'Path to a genoc config file (.genocrc.yml / .genocrc.json); skips discovery',
+                optional: true,
+                placeholder: 'path',
+            },
+            project: {
+                kind: 'parsed',
+                parse: String,
+                brief: 'Run only the named client from a multi-client config',
+                optional: true,
+                placeholder: 'name',
+            },
+        },
+        aliases: {
+            o: 'outputDir',
         },
         positional: {
             kind: 'tuple',
             parameters: [
                 {
-                    brief: 'Path or URL to OpenAPI 3.0 or 3.1 spec (JSON/YAML)',
+                    brief: 'Path or URL to OpenAPI 3.0 or 3.1 spec (JSON/YAML); omit to use a config file',
                     parse: String,
                     placeholder: 'spec',
+                    optional: true,
                 },
             ],
         },

package/dist/cli/config-loader.d.ts

@@ -0,0 +1,20 @@
+import type { ParsedConfig } from './config-schema.js';
+export interface LoadConfigFileOptions {
+    /** Explicit config file path (`--config`); skips discovery when set. */
+    explicitPath?: string;
+    /** Directory to start discovery from; defaults to `process.cwd()`. */
+    searchDir?: string;
+}
+export interface LoadedConfigFile {
+    config: ParsedConfig;
+    filepath: string;
+}
+/**
+ * Load the genoc config file. With `explicitPath`, loads exactly that file
+ * (skipping discovery). Otherwise discovers `.genocrc.yml` / `.genocrc.json`
+ * walking up from `searchDir` (default `process.cwd()`), stopping at the git
+ * boundary (fs root fallback). Returns `null` when no config file is found;
+ * throws `UserError` for parse errors, schema violations, empty documents,
+ * and duplicate resolved output dirs.
+ */
+export declare function loadConfigFile(options?: LoadConfigFileOptions): Promise<LoadedConfigFile | null>;