genoc 0.1.0

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

@@ -0,0 +1,48 @@
+import { RefResolver } from '../parser/ref-resolver.js';
+import type { TypeMappingResult } from '../types/contracts.js';
+import type { SchemaObject, ReferenceObject } from '../types/openapi.js';
+/**
+ * Callback to customize how $ref strings are converted to TypeScript type names.
+ */
+export type TypeNameGenerator = (refString: string) => string;
+/**
+ * SchemaMapper converts OpenAPI 3.1 Schema Objects to TypeScript type strings.
+ *
+ * Handles primitives, objects, arrays, enums, combinators (allOf/oneOf/anyOf),
+ * references, nullable types, and readOnly/writeOnly context filtering.
+ */
+export declare class SchemaMapper {
+    private readonly resolver;
+    private readonly typeNameGenerator;
+    private readonly discriminatorTargets;
+    private readonly reservedNames;
+    private readonly brandedTypes;
+    private static nullableWarned;
+    constructor(resolver: RefResolver, typeNameGenerator?: TypeNameGenerator, discriminatorTargets?: Map<string, {
+        propertyName: string;
+        literalValue: string;
+    }>, reservedNames?: Set<string>);
+    getBrandedTypes(): Map<string, {
+        name: string;
+        format: string;
+        baseType: string;
+    }>;
+    /**
+     * Convert an OpenAPI Schema Object to a TypeScript type string.
+     *
+     * @param schema - The schema to convert
+     * @param name - Optional name for the schema (produces object literal type for objects)
+     * @param context - Optional context for readOnly/writeOnly filtering
+     * @returns TypeMappingResult with tsType string and imports array
+     */
+    mapSchema(schema: SchemaObject | ReferenceObject, name?: string, context?: 'request' | 'response'): TypeMappingResult;
+    private getBrandTypeName;
+    private mapInternal;
+    private resolveDiscriminatorInfo;
+    private mapEnumValues;
+    private mapCombinator;
+    private mapDiscriminatedUnion;
+    private resolveDiscriminantValue;
+    private mapArray;
+    private mapObject;
+}

package/dist/analyzer/schema-mapper.js

@@ -0,0 +1,435 @@
+import { RefResolver } from '../parser/ref-resolver.js';
+import { formatToBrandTypeName } from '../utils/case.js';
+import { quoteKey } from '../utils/string.js';
+/**
+ * Default: extracts the last segment of the JSON pointer.
+ * "#/components/schemas/User" -> "User"
+ */
+function defaultTypeNameGenerator(refString) {
+    const segments = refString.split('/');
+    return segments[segments.length - 1] || 'unknown';
+}
+function isRefObject(obj) {
+    return (obj !== null &&
+        typeof obj === 'object' &&
+        !Array.isArray(obj) &&
+        '$ref' in obj);
+}
+function isComplexType(tsType) {
+    return (tsType.includes(' ') || tsType.includes('{') || tsType.includes('|') || tsType.includes('&'));
+}
+function needsParens(tsType) {
+    return tsType.includes(' | ') || tsType.includes(' & ');
+}
+/**
+ * SchemaMapper converts OpenAPI 3.1 Schema Objects to TypeScript type strings.
+ *
+ * Handles primitives, objects, arrays, enums, combinators (allOf/oneOf/anyOf),
+ * references, nullable types, and readOnly/writeOnly context filtering.
+ */
+export class SchemaMapper {
+    resolver;
+    typeNameGenerator;
+    discriminatorTargets;
+    reservedNames;
+    brandedTypes = new Map();
+    static nullableWarned = false;
+    constructor(resolver, typeNameGenerator, discriminatorTargets, reservedNames) {
+        this.resolver = resolver;
+        this.typeNameGenerator = typeNameGenerator ?? defaultTypeNameGenerator;
+        this.discriminatorTargets = discriminatorTargets ?? new Map();
+        this.reservedNames = reservedNames ?? new Set();
+    }
+    getBrandedTypes() {
+        return this.brandedTypes;
+    }
+    /**
+     * Convert an OpenAPI Schema Object to a TypeScript type string.
+     *
+     * @param schema - The schema to convert
+     * @param name - Optional name for the schema (produces object literal type for objects)
+     * @param context - Optional context for readOnly/writeOnly filtering
+     * @returns TypeMappingResult with tsType string and imports array
+     */
+    mapSchema(schema, name, context) {
+        if (typeof schema === 'boolean') {
+            return { tsType: schema ? 'unknown' : 'never', imports: [] };
+        }
+        const visited = new Set();
+        const result = this.mapInternal(schema, name, context, visited);
+        if (name && this.discriminatorTargets.has(name)) {
+            const target = this.discriminatorTargets.get(name);
+            result.tsType += ` & { ${quoteKey(target.propertyName)}: '${target.literalValue}' }`;
+        }
+        return result;
+    }
+    getBrandTypeName(format, openApiType) {
+        if (!format || format.trim() === '')
+            return null;
+        if (format === 'binary' || format === 'byte')
+            return null;
+        const brandName = formatToBrandTypeName(format, openApiType);
+        if (this.reservedNames.has(brandName))
+            return null;
+        return brandName;
+    }
+    mapInternal(schema, name, context, visited) {
+        if (isRefObject(schema)) {
+            const refStr = schema.$ref;
+            const refName = this.typeNameGenerator(refStr);
+            let resolved;
+            try {
+                resolved = this.resolver.resolveSchema(schema);
+            }
+            catch {
+                // unresolvable — skip discriminator detection
+            }
+            if (resolved) {
+                const discInfo = this.resolveDiscriminatorInfo(resolved, refStr);
+                if (discInfo) {
+                    const expanded = this.mapInternal(resolved, undefined, context, visited);
+                    expanded.tsType += ` & { ${quoteKey(discInfo.propertyName)}: '${discInfo.literalValue}' }`;
+                    return expanded;
+                }
+            }
+            return { tsType: refName, imports: [refName] };
+        }
+        const s = schema;
+        if (visited.has(s)) {
+            if (name) {
+                return { tsType: name, imports: [] };
+            }
+            return { tsType: 'unknown', imports: [] };
+        }
+        visited.add(s);
+        // 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.enum !== undefined && s.enum.length > 0) {
+            let tsType = this.mapEnumValues(s.enum);
+            if (s.nullable === true) {
+                tsType = `${tsType} | null`;
+            }
+            return { tsType, imports: [] };
+        }
+        if (s.allOf !== undefined && s.allOf.length > 0) {
+            const result = this.mapCombinator(s.allOf, '&', context, visited);
+            if (s.nullable === true) {
+                return {
+                    tsType: needsParens(result.tsType)
+                        ? `(${result.tsType}) | null`
+                        : `${result.tsType} | null`,
+                    imports: result.imports,
+                };
+            }
+            return result;
+        }
+        if (s.oneOf !== undefined && s.oneOf.length > 0) {
+            const result = s.discriminator
+                ? this.mapDiscriminatedUnion(s.oneOf, s.discriminator, context, visited)
+                : this.mapCombinator(s.oneOf, '|', context, visited);
+            if (s.nullable === true) {
+                return {
+                    tsType: needsParens(result.tsType)
+                        ? `(${result.tsType}) | null`
+                        : `${result.tsType} | null`,
+                    imports: result.imports,
+                };
+            }
+            return result;
+        }
+        if (s.anyOf !== undefined && s.anyOf.length > 0) {
+            const result = s.discriminator
+                ? this.mapDiscriminatedUnion(s.anyOf, s.discriminator, context, visited)
+                : this.mapCombinator(s.anyOf, '|', context, visited);
+            if (s.nullable === true) {
+                return {
+                    tsType: needsParens(result.tsType)
+                        ? `(${result.tsType}) | null`
+                        : `${result.tsType} | null`,
+                    imports: result.imports,
+                };
+            }
+            return result;
+        }
+        if (s.type === undefined) {
+            return { tsType: 'unknown', imports: [] };
+        }
+        if (Array.isArray(s.type)) {
+            const nonNull = s.type.filter((t) => t !== 'null');
+            const hasNull = s.type.includes('null');
+            if (nonNull.length === 0) {
+                return { tsType: 'null', imports: [] };
+            }
+            const baseResult = this.mapInternal({ ...s, type: nonNull[0] }, name, context, new Set(visited));
+            if (hasNull) {
+                return {
+                    tsType: `${baseResult.tsType} | null`,
+                    imports: baseResult.imports,
+                };
+            }
+            return baseResult;
+        }
+        switch (s.type) {
+            case 'string': {
+                const brandName = this.getBrandTypeName(s.format, 'string');
+                if (brandName) {
+                    this.brandedTypes.set(`${s.format}:string`, {
+                        name: brandName,
+                        format: s.format,
+                        baseType: 'string',
+                    });
+                    return {
+                        tsType: s.nullable === true ? `${brandName} | null` : brandName,
+                        imports: [brandName],
+                    };
+                }
+                return {
+                    tsType: s.nullable === true ? 'string | null' : 'string',
+                    imports: [],
+                };
+            }
+            case 'number':
+            case 'integer': {
+                const brandName = this.getBrandTypeName(s.format, s.type);
+                if (brandName) {
+                    this.brandedTypes.set(`${s.format}:number`, {
+                        name: brandName,
+                        format: s.format,
+                        baseType: 'number',
+                    });
+                    return {
+                        tsType: s.nullable === true ? `${brandName} | null` : brandName,
+                        imports: [brandName],
+                    };
+                }
+                return {
+                    tsType: s.nullable === true ? 'number | null' : 'number',
+                    imports: [],
+                };
+            }
+            case 'boolean':
+                return {
+                    tsType: s.nullable === true ? 'boolean | null' : 'boolean',
+                    imports: [],
+                };
+            case 'null':
+                return { tsType: 'null', imports: [] };
+            case 'array':
+                return this.mapArray(s, context, visited);
+            case 'object':
+                return this.mapObject(s, name, context, visited);
+            default:
+                return { tsType: 'unknown', imports: [] };
+        }
+    }
+    resolveDiscriminatorInfo(schema, refStr) {
+        const schemaName = refStr.split('/').pop();
+        const target = this.discriminatorTargets.get(schemaName);
+        if (target)
+            return target;
+        if (!schema.allOf || schema.allOf.length === 0)
+            return undefined;
+        for (const item of schema.allOf) {
+            if (isRefObject(item)) {
+                const resolved = this.resolver.resolveSchema(item);
+                if (resolved.discriminator) {
+                    const disc = resolved.discriminator;
+                    if (disc.mapping) {
+                        for (const [value, ref] of Object.entries(disc.mapping)) {
+                            if (ref === refStr) {
+                                return { propertyName: disc.propertyName, literalValue: value };
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        return undefined;
+    }
+    mapEnumValues(values) {
+        return values
+            .map((v) => {
+            if (typeof v === 'string')
+                return `'${v}'`;
+            if (typeof v === 'number')
+                return String(v);
+            if (typeof v === 'boolean')
+                return String(v);
+            if (v === null)
+                return 'null';
+            return 'unknown';
+        })
+            .join(' | ');
+    }
+    mapCombinator(schemas, kind, context, visited) {
+        const results = schemas.map((s) => this.mapInternal(s, undefined, context, visited));
+        const allImports = [];
+        for (const r of results) {
+            allImports.push(...r.imports);
+        }
+        const separator = kind === '&' ? ' & ' : ' | ';
+        const parts = results.map((r) => {
+            if (kind === '&' && r.tsType.includes(' | ')) {
+                return `(${r.tsType})`;
+            }
+            return r.tsType;
+        });
+        return { tsType: parts.join(separator), imports: allImports };
+    }
+    mapDiscriminatedUnion(schemas, discriminator, context, visited) {
+        const propertyName = discriminator.propertyName;
+        const mapping = discriminator.mapping;
+        const allImports = [];
+        const parts = [];
+        for (const schema of schemas) {
+            const discriminantValue = this.resolveDiscriminantValue(schema, propertyName, mapping);
+            const variantResult = this.mapInternal(schema, undefined, context, visited);
+            allImports.push(...variantResult.imports);
+            const quotedProp = quoteKey(propertyName);
+            parts.push(`({ ${quotedProp}: '${discriminantValue}' } & ${variantResult.tsType})`);
+        }
+        return { tsType: parts.join(' | '), imports: allImports };
+    }
+    resolveDiscriminantValue(schema, propertyName, mapping) {
+        // Try explicit mapping first
+        if (mapping && isRefObject(schema)) {
+            const refStr = schema.$ref;
+            for (const [value, ref] of Object.entries(mapping)) {
+                if (ref === refStr)
+                    return value;
+            }
+        }
+        // Infer from const on the discriminator property
+        const resolved = isRefObject(schema)
+            ? this.resolver.resolve(schema)
+            : schema;
+        const propSchema = resolved.properties?.[propertyName];
+        if (propSchema && propSchema.const !== undefined) {
+            return String(propSchema.const);
+        }
+        // Fallback: use the type name from $ref
+        if (isRefObject(schema)) {
+            const refStr = schema.$ref;
+            return this.typeNameGenerator(refStr);
+        }
+        return 'unknown';
+    }
+    mapArray(schema, context, visited) {
+        if (!schema.items) {
+            return {
+                tsType: schema.nullable === true ? 'unknown[] | null' : 'unknown[]',
+                imports: [],
+            };
+        }
+        const itemResult = this.mapInternal(schema.items, undefined, context, visited);
+        const tsType = isComplexType(itemResult.tsType)
+            ? `Array<${itemResult.tsType}>`
+            : `${itemResult.tsType}[]`;
+        return {
+            tsType: schema.nullable === true ? `${tsType} | null` : tsType,
+            imports: itemResult.imports,
+        };
+    }
+    mapObject(schema, name, context, visited) {
+        const properties = schema.properties ?? {};
+        const requiredSet = new Set(schema.required ?? []);
+        const propNames = Object.keys(properties);
+        const filteredPropNames = propNames.filter((propName) => {
+            const propSchema = properties[propName];
+            const resolved = isRefObject(propSchema)
+                ? this.resolver.resolve(propSchema)
+                : propSchema;
+            if (context === 'response' && resolved.writeOnly === true)
+                return false;
+            if (context === 'request' && resolved.readOnly === true)
+                return false;
+            return true;
+        });
+        const propEntries = [];
+        const allImports = [];
+        if (schema.discriminator) {
+            const discPropName = schema.discriminator.propertyName;
+            const discIndex = filteredPropNames.indexOf(discPropName);
+            if (discIndex !== -1) {
+                filteredPropNames.splice(discIndex, 1);
+            }
+            propEntries.push(`"${discPropName}": string`);
+        }
+        for (const propName of filteredPropNames) {
+            const propSchema = properties[propName];
+            const propResult = this.mapInternal(propSchema, undefined, context, visited);
+            allImports.push(...propResult.imports);
+            const optional = requiredSet.has(propName) ? '' : '?';
+            const quotedName = quoteKey(propName);
+            propEntries.push(`${quotedName}${optional}: ${propResult.tsType}`);
+        }
+        const additionalProps = schema.additionalProperties;
+        let indexSignature = null;
+        if (additionalProps === false) {
+            void 0;
+        }
+        else if (additionalProps === true) {
+            indexSignature = '[key: string]: unknown';
+        }
+        else if (additionalProps !== undefined && typeof additionalProps === 'object') {
+            const addPropResult = this.mapInternal(additionalProps, undefined, context, visited);
+            allImports.push(...addPropResult.imports);
+            indexSignature = `[key: string]: ${addPropResult.tsType}`;
+        }
+        const hasProps = propEntries.length > 0;
+        const hasIndex = indexSignature !== null;
+        let result;
+        if (!hasProps && !hasIndex) {
+            if (name) {
+                result = { tsType: `{}`, imports: allImports };
+            }
+            else {
+                result = { tsType: 'Record<string, unknown>', imports: allImports };
+            }
+        }
+        else if (!hasProps && hasIndex) {
+            const valueType = indexSignature.replace('[key: string]: ', '');
+            if (name) {
+                result = {
+                    tsType: `{ ${indexSignature}; }`,
+                    imports: allImports,
+                };
+            }
+            else {
+                result = {
+                    tsType: `Record<string, ${valueType}>`,
+                    imports: allImports,
+                };
+            }
+        }
+        else {
+            const propsBody = propEntries.join('; ') + ';';
+            if (hasIndex) {
+                result = {
+                    tsType: `{ ${propsBody} } & { ${indexSignature}; }`,
+                    imports: allImports,
+                };
+            }
+            else {
+                result = {
+                    tsType: `{ ${propsBody} }`,
+                    imports: allImports,
+                };
+            }
+        }
+        if (schema.nullable === true) {
+            return {
+                tsType: `${result.tsType} | null`,
+                imports: result.imports,
+            };
+        }
+        return result;
+    }
+}

package/dist/cli/app.d.ts

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

package/dist/cli/app.js

@@ -0,0 +1,60 @@
+import { readFileSync } from 'fs';
+import { buildCommand, buildApplication } from '@stricli/core';
+const VERSION = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url)).toString()).version;
+const command = buildCommand({
+    loader: async () => import('./impl.js'),
+    parameters: {
+        flags: {
+            outputDir: {
+                kind: 'parsed',
+                parse: String,
+                brief: 'Directory to write generated files',
+                placeholder: 'dir',
+            },
+            methodNameStrategy: {
+                kind: 'enum',
+                values: ['path-based', 'operationId', 'operationId-with-fallback'],
+                default: 'path-based',
+                brief: 'Method naming strategy',
+            },
+            specVersion: {
+                kind: 'parsed',
+                parse: String,
+                brief: 'Override auto-detected OpenAPI version (e.g. "3.0", "3.1")',
+                optional: true,
+                placeholder: 'version',
+            },
+            strictVersion: {
+                kind: 'boolean',
+                default: true,
+                brief: 'Enable strict version checking',
+            },
+        },
+        positional: {
+            kind: 'tuple',
+            parameters: [
+                {
+                    brief: 'Path or URL to OpenAPI 3.0 or 3.1 spec (JSON/YAML)',
+                    parse: String,
+                    placeholder: 'spec',
+                },
+            ],
+        },
+    },
+    docs: {
+        brief: 'Generate typed HTTP clients from OpenAPI specifications',
+        fullDescription: 'Generate typed TypeScript HTTP clients from OpenAPI 3.0 / 3.1 specs (JSON/YAML, file or URL).',
+    },
+});
+export const app = buildApplication(command, {
+    name: 'genoc',
+    versionInfo: {
+        currentVersion: VERSION,
+    },
+    scanner: {
+        caseStyle: 'allow-kebab-for-camel',
+    },
+    documentation: {
+        caseStyle: 'convert-camel-to-kebab',
+    },
+});

package/dist/cli/errors.d.ts

@@ -0,0 +1,3 @@
+export declare class UserError extends Error {
+    constructor(message: string);
+}

package/dist/cli/errors.js

@@ -0,0 +1,6 @@
+export class UserError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UserError';
+    }
+}

package/dist/cli/impl.d.ts

@@ -0,0 +1,3 @@
+import type { CommandContext } from '@stricli/core';
+import type { AppFlags as Flags } from './app.js';
+export default function (this: CommandContext, flags: Flags, spec: string): Promise<void | Error>;

package/dist/cli/impl.js

@@ -0,0 +1,45 @@
+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 { UserError } from './errors.js';
+export default async function (flags, spec) {
+    try {
+        this.process.stdout.write(`Loading spec from ${spec}...\n`);
+        const doc = await load(spec);
+        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`);
+            }
+        }
+        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,
+        };
+        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) {
+            return error;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        return new Error(message);
+    }
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { run } from '@stricli/core';
+import { app } from './app.js';
+await run(app, process.argv.slice(2), { process });
+process.exit(typeof process.exitCode === 'number' ? process.exitCode : 0);

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

@@ -0,0 +1,21 @@
+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.
+ */
+export declare function generateClient(doc: OpenAPIDocument, config: GeneratorConfig, options?: GenerationOptions): {
+    contracts: string;
+    client: string;
+};
+/**
+ * Generate and write both output files to disk.
+ */
+export declare function generateFullOutput(doc: OpenAPIDocument, config: GeneratorConfig, options?: GenerationOptions): Promise<void>;