genoc 0.1.0

package/dist/parser/version/normalized-spec.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Normalized schema with consistent types across OpenAPI versions
+ */
+export interface NormalizedSchema {
+    /** Normalized types - always an array, even for single types */
+    types: string[];
+    /** Format information */
+    format?: string;
+    /** Properties object */
+    properties?: Record<string, NormalizedSchema>;
+    /** Required properties array */
+    required?: string[];
+    /** Array items schema */
+    items?: NormalizedSchema;
+    /** Additional properties flag or schema */
+    additionalProperties?: boolean | NormalizedSchema;
+    /** Reference pointer */
+    $ref?: string;
+    /** AllOf composition */
+    allOf?: NormalizedSchema[];
+    /** OneOf composition */
+    oneOf?: NormalizedSchema[];
+    /** AnyOf composition */
+    anyOf?: NormalizedSchema[];
+    /** Enum values */
+    enum?: unknown[];
+    /** Const value */
+    const?: unknown;
+    /** Default value */
+    default?: unknown;
+    /** Description */
+    description?: string;
+    /** Whether nullable */
+    nullable: boolean;
+    /** Examples - always normalized to array */
+    examples: unknown[];
+    /** File upload information */
+    fileUpload?: {
+        binary: boolean;
+        base64: boolean;
+    };
+    /** Exclusive minimum (always number) */
+    exclusiveMinimum?: number;
+    /** Exclusive maximum (always number) */
+    exclusiveMaximum?: number;
+    /** Minimum value */
+    minimum?: number;
+    /** Maximum value */
+    maximum?: number;
+    /** Read only */
+    readOnly?: boolean;
+    /** Write only */
+    writeOnly?: boolean;
+    /** Deprecated */
+    deprecated?: boolean;
+    /** Discriminator information */
+    discriminator?: {
+        propertyName: string;
+        mapping?: Record<string, string>;
+    };
+}
+/**
+ * Normalized OpenAPI specification with consistent structure
+ */
+export interface NormalizedSpec {
+    /** Original OpenAPI version string */
+    openapi: string;
+    /** Info object */
+    info: {
+        title: string;
+        version: string;
+        description?: string;
+        termsOfService?: string;
+        contact?: {
+            name?: string;
+            url?: string;
+            email?: string;
+        };
+        license?: {
+            name: string;
+            url?: string;
+            identifier?: string;
+        };
+    };
+    /** Servers array */
+    servers?: Array<{
+        url: string;
+        description?: string;
+        variables?: Record<string, {
+            default: string;
+            description?: string;
+            enum?: string[];
+        }>;
+    }>;
+    /** Paths object - simplified version */
+    paths?: Record<string, {
+        $ref?: string;
+        summary?: string;
+        description?: string;
+        get?: NormalizedOperation;
+        put?: NormalizedOperation;
+        post?: NormalizedOperation;
+        delete?: NormalizedOperation;
+        options?: NormalizedOperation;
+        head?: NormalizedOperation;
+        patch?: NormalizedOperation;
+        trace?: NormalizedOperation;
+        parameters?: Array<NormalizedParameter>;
+        servers?: unknown[];
+    }>;
+    /** Components object */
+    components?: {
+        schemas?: Record<string, NormalizedSchema>;
+        responses?: Record<string, unknown>;
+        parameters?: Record<string, unknown>;
+        requestBodies?: Record<string, unknown>;
+        headers?: Record<string, unknown>;
+        securitySchemes?: Record<string, unknown>;
+        links?: Record<string, unknown>;
+        callbacks?: Record<string, unknown>;
+        examples?: Record<string, unknown>;
+    };
+    /** Security requirements */
+    security?: unknown[];
+    /** Tags */
+    tags?: unknown[];
+    /** External documentation */
+    externalDocs?: {
+        description?: string;
+        url: string;
+    };
+    /** Webhooks */
+    webhooks?: Record<string, {
+        $ref?: string;
+        summary?: string;
+        description?: string;
+        get?: NormalizedOperation;
+        put?: NormalizedOperation;
+        post?: NormalizedOperation;
+        delete?: NormalizedOperation;
+        options?: NormalizedOperation;
+        head?: NormalizedOperation;
+        patch?: NormalizedOperation;
+        trace?: NormalizedOperation;
+        parameters?: Array<NormalizedParameter>;
+        servers?: unknown[];
+    }>;
+}
+/**
+ * Normalized operation object
+ */
+interface NormalizedOperation {
+    tags?: string[];
+    summary?: string;
+    description?: string;
+    operationId?: string;
+    parameters?: Array<NormalizedParameter>;
+    requestBody?: {
+        description?: string;
+        content: Record<string, {
+            schema?: NormalizedSchema;
+            examples?: Record<string, unknown>;
+            example?: unknown;
+            encoding?: Record<string, unknown>;
+        }>;
+        required?: boolean;
+    };
+    responses: Record<string, {
+        description: string;
+        headers?: Record<string, unknown>;
+        content?: Record<string, {
+            schema?: NormalizedSchema;
+            examples?: Record<string, unknown>;
+            example?: unknown;
+            encoding?: Record<string, unknown>;
+        }>;
+        links?: Record<string, unknown>;
+    }>;
+    deprecated?: boolean;
+    security?: unknown[];
+    servers?: unknown[];
+}
+/**
+ * Normalized parameter object
+ */
+interface NormalizedParameter {
+    name: string;
+    in: 'query' | 'path' | 'header' | 'cookie';
+    description?: string;
+    required?: boolean;
+    deprecated?: boolean;
+    schema?: NormalizedSchema;
+    style?: string;
+    explode?: boolean;
+    allowEmptyValue?: boolean;
+    example?: unknown;
+    examples?: Record<string, unknown>;
+}
+export {};

package/dist/parser/version/normalized-spec.js

@@ -0,0 +1 @@
+export {};

package/dist/parser/version/registry.d.ts

@@ -0,0 +1,28 @@
+import type { VersionStrategy } from './version-strategy.js';
+/**
+ * Registry for managing version strategies
+ */
+export declare class VersionStrategyRegistry {
+    private strategies;
+    /**
+     * Register a version strategy for a specific OpenAPI version
+     */
+    register(strategy: VersionStrategy): void;
+    /**
+     * Get a version strategy by version string
+     * @throws Error if strategy is not registered
+     */
+    get(version: string): VersionStrategy;
+    /**
+     * Detect the version from a raw OpenAPI specification and return the corresponding strategy
+     */
+    detectAndResolve(rawSpec: unknown): VersionStrategy;
+    /**
+     * Get list of supported version strings
+     */
+    listSupported(): string[];
+    /**
+     * Check if a version is supported
+     */
+    isSupported(version: string): boolean;
+}

package/dist/parser/version/registry.js

@@ -0,0 +1,44 @@
+import { detectSpecVersion } from './version-detector.js';
+/**
+ * Registry for managing version strategies
+ */
+export class VersionStrategyRegistry {
+    strategies = new Map();
+    /**
+     * Register a version strategy for a specific OpenAPI version
+     */
+    register(strategy) {
+        const version = strategy.version();
+        this.strategies.set(version, strategy);
+    }
+    /**
+     * Get a version strategy by version string
+     * @throws Error if strategy is not registered
+     */
+    get(version) {
+        const strategy = this.strategies.get(version);
+        if (!strategy) {
+            throw new Error(`No strategy registered for version: ${version}`);
+        }
+        return strategy;
+    }
+    /**
+     * Detect the version from a raw OpenAPI specification and return the corresponding strategy
+     */
+    detectAndResolve(rawSpec) {
+        const version = detectSpecVersion(rawSpec);
+        return this.get(version);
+    }
+    /**
+     * Get list of supported version strings
+     */
+    listSupported() {
+        return Array.from(this.strategies.keys());
+    }
+    /**
+     * Check if a version is supported
+     */
+    isSupported(version) {
+        return this.strategies.has(version);
+    }
+}

package/dist/parser/version/v3.0/index.d.ts

@@ -0,0 +1,3 @@
+export { V3_0_VersionStrategy } from './strategy.js';
+export { normalizeSpec30 } from './normalizer.js';
+export { validateSpec30 } from './validator.js';

package/dist/parser/version/v3.0/index.js

@@ -0,0 +1,3 @@
+export { V3_0_VersionStrategy } from './strategy.js';
+export { normalizeSpec30 } from './normalizer.js';
+export { validateSpec30 } from './validator.js';

package/dist/parser/version/v3.0/normalizer.d.ts

@@ -0,0 +1,15 @@
+import type { NormalizedSpec } from '../normalized-spec.js';
+/**
+ * Normalize a raw OpenAPI 3.0.x specification to a consistent format.
+ *
+ * 3.0-specific transformations applied during normalization:
+ * - `nullable: true` → `nullable: true` on the NormalizedSchema
+ * - `exclusiveMinimum: true` + `minimum: 5` → `exclusiveMinimum: 5`
+ * - `exclusiveMinimum: false` → removed (not included in output)
+ * - `example: value` → `examples: [value]`
+ * - `format: "binary"` → `fileUpload: { binary: true, base64: false }`
+ * - `format: "byte"` → `fileUpload: { binary: false, base64: true }`
+ * - `$ref` siblings are stripped (3.0 compliant behavior)
+ * - Error if `items` is an array (3.1-only tuple syntax)
+ */
+export declare function normalizeSpec30(rawSpec: unknown): NormalizedSpec;

package/dist/parser/version/v3.0/normalizer.js

@@ -0,0 +1,389 @@
+/**
+ * Normalize a raw OpenAPI 3.0.x specification to a consistent format.
+ *
+ * 3.0-specific transformations applied during normalization:
+ * - `nullable: true` → `nullable: true` on the NormalizedSchema
+ * - `exclusiveMinimum: true` + `minimum: 5` → `exclusiveMinimum: 5`
+ * - `exclusiveMinimum: false` → removed (not included in output)
+ * - `example: value` → `examples: [value]`
+ * - `format: "binary"` → `fileUpload: { binary: true, base64: false }`
+ * - `format: "byte"` → `fileUpload: { binary: false, base64: true }`
+ * - `$ref` siblings are stripped (3.0 compliant behavior)
+ * - Error if `items` is an array (3.1-only tuple syntax)
+ */
+export function normalizeSpec30(rawSpec) {
+    if (!rawSpec || typeof rawSpec !== 'object' || Array.isArray(rawSpec)) {
+        throw new Error('Invalid spec: must be a non-null object');
+    }
+    const raw = rawSpec;
+    const rawInfo = raw.info;
+    if (!rawInfo || typeof rawInfo !== 'object' || Array.isArray(rawInfo)) {
+        throw new Error("Invalid spec: missing or invalid 'info' field");
+    }
+    const ri = rawInfo;
+    const info = {
+        title: typeof ri.title === 'string' ? ri.title : '',
+        version: typeof ri.version === 'string' ? ri.version : '',
+        description: typeof ri.description === 'string' ? ri.description : undefined,
+        termsOfService: typeof ri.termsOfService === 'string' ? ri.termsOfService : undefined,
+        contact: ri.contact && typeof ri.contact === 'object' && !Array.isArray(ri.contact)
+            ? ri.contact
+            : undefined,
+        license: ri.license && typeof ri.license === 'object' && !Array.isArray(ri.license)
+            ? ri.license
+            : undefined,
+    };
+    const servers = Array.isArray(raw.servers)
+        ? raw.servers
+        : undefined;
+    let paths;
+    if (raw.paths && typeof raw.paths === 'object' && !Array.isArray(raw.paths)) {
+        paths = {};
+        for (const [pathKey, pathItem] of Object.entries(raw.paths)) {
+            if (pathItem && typeof pathItem === 'object' && !Array.isArray(pathItem)) {
+                paths[pathKey] = normalizePathItem(pathItem);
+            }
+        }
+    }
+    let components;
+    if (raw.components && typeof raw.components === 'object' && !Array.isArray(raw.components)) {
+        const rc = raw.components;
+        components = {};
+        if (rc.schemas && typeof rc.schemas === 'object' && !Array.isArray(rc.schemas)) {
+            components.schemas = {};
+            for (const [name, schema] of Object.entries(rc.schemas)) {
+                components.schemas[name] = normalizeSchema(schema);
+            }
+        }
+        if (rc.responses && typeof rc.responses === 'object')
+            components.responses = rc.responses;
+        if (rc.parameters && typeof rc.parameters === 'object')
+            components.parameters = rc.parameters;
+        if (rc.requestBodies && typeof rc.requestBodies === 'object')
+            components.requestBodies = rc.requestBodies;
+        if (rc.headers && typeof rc.headers === 'object')
+            components.headers = rc.headers;
+        if (rc.securitySchemes && typeof rc.securitySchemes === 'object')
+            components.securitySchemes = rc.securitySchemes;
+        if (rc.links && typeof rc.links === 'object')
+            components.links = rc.links;
+        if (rc.callbacks && typeof rc.callbacks === 'object')
+            components.callbacks = rc.callbacks;
+        if (rc.examples && typeof rc.examples === 'object')
+            components.examples = rc.examples;
+    }
+    let webhooks;
+    if (raw.webhooks && typeof raw.webhooks === 'object' && !Array.isArray(raw.webhooks)) {
+        webhooks = {};
+        for (const [name, pathItem] of Object.entries(raw.webhooks)) {
+            if (pathItem && typeof pathItem === 'object' && !Array.isArray(pathItem)) {
+                webhooks[name] = normalizePathItem(pathItem);
+            }
+        }
+    }
+    return {
+        openapi: typeof raw.openapi === 'string' ? raw.openapi : '3.0.0',
+        info,
+        servers,
+        paths,
+        components,
+        security: Array.isArray(raw.security) ? raw.security : undefined,
+        tags: Array.isArray(raw.tags) ? raw.tags : undefined,
+        externalDocs: raw.externalDocs && typeof raw.externalDocs === 'object' && !Array.isArray(raw.externalDocs)
+            ? raw.externalDocs
+            : undefined,
+        webhooks,
+    };
+}
+/**
+ * Normalize a schema object with 3.0-specific transformations.
+ *
+ * Key differences from 3.1 normalization:
+ * - `nullable` keyword is the primary null indicator (not type arrays with "null")
+ * - `exclusiveMinimum`/`exclusiveMaximum` are boolean modifiers of `minimum`/`maximum`
+ * - `$ref` siblings are stripped (3.0 compliant behavior)
+ * - `items` as array is an error (3.1-only tuple syntax)
+ */
+function normalizeSchema(schema) {
+    if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
+        return { types: [], nullable: false, examples: [] };
+    }
+    const s = schema;
+    if (typeof s.$ref === 'string') {
+        return {
+            $ref: s.$ref,
+            types: [],
+            nullable: false,
+            examples: [],
+        };
+    }
+    let types = [];
+    let nullable = false;
+    if (typeof s.type === 'string') {
+        types = [s.type];
+    }
+    else if (Array.isArray(s.type)) {
+        const typeArr = s.type;
+        if (typeArr.includes('null')) {
+            nullable = true;
+            types = typeArr.filter((t) => t !== 'null');
+        }
+        else {
+            types = [...typeArr];
+        }
+    }
+    if (s.nullable === true) {
+        nullable = true;
+    }
+    let examples = [];
+    if (Array.isArray(s.examples)) {
+        examples = [...s.examples];
+    }
+    else if (s.example !== undefined) {
+        examples = [s.example];
+    }
+    let exclusiveMinimum;
+    if (s.exclusiveMinimum === true && typeof s.minimum === 'number') {
+        exclusiveMinimum = s.minimum;
+    }
+    else if (typeof s.exclusiveMinimum === 'number') {
+        exclusiveMinimum = s.exclusiveMinimum;
+    }
+    let exclusiveMaximum;
+    if (s.exclusiveMaximum === true && typeof s.maximum === 'number') {
+        exclusiveMaximum = s.maximum;
+    }
+    else if (typeof s.exclusiveMaximum === 'number') {
+        exclusiveMaximum = s.exclusiveMaximum;
+    }
+    let fileUpload;
+    if (typeof s.format === 'string') {
+        if (s.format === 'binary') {
+            fileUpload = { binary: true, base64: false };
+        }
+        else if (s.format === 'byte') {
+            fileUpload = { binary: false, base64: true };
+        }
+    }
+    const properties = normalizePropertyMap(s.properties);
+    let items;
+    if (s.items !== undefined) {
+        if (Array.isArray(s.items)) {
+            throw new Error("Schema 'items' as an array is not supported in OpenAPI 3.0 (tuple syntax is 3.1-only). Use prefixItems in 3.1.");
+        }
+        items = normalizeSchema(s.items);
+    }
+    const allOf = Array.isArray(s.allOf)
+        ? s.allOf.map((item) => normalizeSchema(item))
+        : undefined;
+    const oneOf = Array.isArray(s.oneOf)
+        ? s.oneOf.map((item) => normalizeSchema(item))
+        : undefined;
+    const anyOf = Array.isArray(s.anyOf)
+        ? s.anyOf.map((item) => normalizeSchema(item))
+        : undefined;
+    let additionalProperties;
+    if (s.additionalProperties === true) {
+        additionalProperties = true;
+    }
+    else if (s.additionalProperties === false) {
+        additionalProperties = false;
+    }
+    else if (s.additionalProperties &&
+        typeof s.additionalProperties === 'object' &&
+        !Array.isArray(s.additionalProperties)) {
+        additionalProperties = normalizeSchema(s.additionalProperties);
+    }
+    return {
+        types,
+        nullable,
+        format: typeof s.format === 'string' ? s.format : undefined,
+        properties,
+        required: Array.isArray(s.required) ? s.required : undefined,
+        items,
+        additionalProperties,
+        allOf,
+        oneOf,
+        anyOf,
+        enum: Array.isArray(s.enum) ? [...s.enum] : undefined,
+        const: 'const' in s ? s.const : undefined,
+        default: 'default' in s ? s.default : undefined,
+        description: typeof s.description === 'string' ? s.description : undefined,
+        examples,
+        fileUpload,
+        exclusiveMinimum,
+        exclusiveMaximum,
+        minimum: typeof s.minimum === 'number' ? s.minimum : undefined,
+        maximum: typeof s.maximum === 'number' ? s.maximum : undefined,
+        readOnly: s.readOnly === true ? true : undefined,
+        writeOnly: s.writeOnly === true ? true : undefined,
+        deprecated: s.deprecated === true ? true : undefined,
+        discriminator: s.discriminator && typeof s.discriminator === 'object' && !Array.isArray(s.discriminator)
+            ? s.discriminator
+            : undefined,
+    };
+}
+function normalizePropertyMap(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return undefined;
+    }
+    const entries = Object.entries(raw);
+    if (entries.length === 0)
+        return undefined;
+    const result = {};
+    for (const [key, val] of entries) {
+        result[key] = normalizeSchema(val);
+    }
+    return result;
+}
+function normalizePathItem(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return {};
+    }
+    const pi = raw;
+    const httpMethods = [
+        'get',
+        'put',
+        'post',
+        'delete',
+        'options',
+        'head',
+        'patch',
+        'trace',
+    ];
+    const result = {};
+    if (typeof pi.$ref === 'string')
+        result.$ref = pi.$ref;
+    if (typeof pi.summary === 'string')
+        result.summary = pi.summary;
+    if (typeof pi.description === 'string')
+        result.description = pi.description;
+    if (Array.isArray(pi.servers))
+        result.servers = pi.servers;
+    if (Array.isArray(pi.parameters)) {
+        result.parameters = pi.parameters.map((p) => normalizeParameter(p));
+    }
+    for (const method of httpMethods) {
+        const op = pi[method];
+        if (op && typeof op === 'object' && !Array.isArray(op)) {
+            result[method] = normalizeOperation(op);
+        }
+    }
+    return result;
+}
+function normalizeOperation(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return { responses: {} };
+    }
+    const o = raw;
+    const result = {
+        responses: {},
+    };
+    if (Array.isArray(o.tags))
+        result.tags = o.tags;
+    if (typeof o.summary === 'string')
+        result.summary = o.summary;
+    if (typeof o.description === 'string')
+        result.description = o.description;
+    if (typeof o.operationId === 'string')
+        result.operationId = o.operationId;
+    if (o.deprecated === true)
+        result.deprecated = true;
+    if (Array.isArray(o.security))
+        result.security = o.security;
+    if (Array.isArray(o.servers))
+        result.servers = o.servers;
+    if (Array.isArray(o.parameters)) {
+        result.parameters = o.parameters.map((p) => normalizeParameter(p));
+    }
+    if (o.requestBody && typeof o.requestBody === 'object' && !Array.isArray(o.requestBody)) {
+        const rb = o.requestBody;
+        result.requestBody = {
+            content: normalizeContentMap(rb.content),
+        };
+        if (typeof rb.description === 'string')
+            result.requestBody.description = rb.description;
+        if (rb.required === true)
+            result.requestBody.required = true;
+    }
+    if (o.responses && typeof o.responses === 'object' && !Array.isArray(o.responses)) {
+        const responses = {};
+        for (const [code, resp] of Object.entries(o.responses)) {
+            if (resp && typeof resp === 'object' && !Array.isArray(resp)) {
+                const r = resp;
+                responses[code] = {
+                    description: typeof r.description === 'string' ? r.description : '',
+                };
+                if (r.headers && typeof r.headers === 'object')
+                    responses[code].headers = r.headers;
+                if (r.content && typeof r.content === 'object')
+                    responses[code].content = normalizeContentMap(r.content);
+                if (r.links && typeof r.links === 'object')
+                    responses[code].links = r.links;
+            }
+        }
+        result.responses = responses;
+    }
+    return result;
+}
+function normalizeContentMap(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return {};
+    }
+    const result = {};
+    for (const [mediaType, mediaObj] of Object.entries(raw)) {
+        if (mediaObj && typeof mediaObj === 'object' && !Array.isArray(mediaObj)) {
+            const m = mediaObj;
+            const entry = {};
+            if (m.schema) {
+                entry.schema = normalizeSchema(m.schema);
+            }
+            if (m.examples && typeof m.examples === 'object')
+                entry.examples = m.examples;
+            if ('example' in m)
+                entry.example = m.example;
+            if (m.encoding && typeof m.encoding === 'object')
+                entry.encoding = m.encoding;
+            result[mediaType] = entry;
+        }
+    }
+    return result;
+}
+function normalizeParameter(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return { name: '', in: 'query' };
+    }
+    const p = raw;
+    if (typeof p.$ref === 'string') {
+        return {
+            name: '',
+            in: 'query',
+            $ref: p.$ref,
+        };
+    }
+    const result = {
+        name: typeof p.name === 'string' ? p.name : '',
+        in: ['query', 'path', 'header', 'cookie'].includes(p.in)
+            ? p.in
+            : 'query',
+    };
+    if (typeof p.description === 'string')
+        result.description = p.description;
+    if (p.required === true)
+        result.required = true;
+    if (p.deprecated === true)
+        result.deprecated = true;
+    if (p.schema)
+        result.schema = normalizeSchema(p.schema);
+    if (typeof p.style === 'string')
+        result.style = p.style;
+    if (p.explode !== undefined)
+        result.explode = p.explode;
+    if (p.allowEmptyValue === true)
+        result.allowEmptyValue = true;
+    if ('example' in p)
+        result.example = p.example;
+    if (p.examples && typeof p.examples === 'object')
+        result.examples = p.examples;
+    return result;
+}