genoc 0.2.0 → 0.4.0

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

@@ -1,389 +0,0 @@
-/**
- * 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;
-}

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

@@ -1,27 +0,0 @@
-import type { ValidationResult } from '../../validators.js';
-import type { NormalizedSpec } from '../normalized-spec.js';
-import type { VersionStrategy } from '../version-strategy.js';
-/**
- * Version strategy for OpenAPI 3.0.x specifications.
- *
- * OpenAPI 3.0 is the original version of the OpenAPI specification and differs
- * from 3.1 in several key ways:
- * - `nullable` keyword (not type arrays with "null")
- * - `exclusiveMinimum`/`exclusiveMaximum` as booleans modifying `minimum`/`maximum`
- * - `$ref` siblings are ignored (not merged)
- * - `example` keyword (not `examples`)
- * - `paths` is required
- */
-export declare class V3_0_VersionStrategy implements VersionStrategy {
-    version(): string;
-    matches(spec: unknown): boolean;
-    normalizeSpec(rawSpec: unknown): NormalizedSpec;
-    validateSpec(spec: NormalizedSpec): ValidationResult;
-    /**
-     * Resolve a $ref within the document. For OpenAPI 3.0, sibling properties
-     * alongside `$ref` are ignored — only the $ref target is returned.
-     */
-    resolveRef(ref: string, doc: unknown, _context?: unknown): unknown;
-    getSupportedFeatures(): string[];
-    private resolveRefInternal;
-}

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

@@ -1,96 +0,0 @@
-import { parseJsonPointer } from '../../../utils/url.js';
-import { normalizeSpec30 } from './normalizer.js';
-import { validateSpec30 } from './validator.js';
-const MAX_REF_DEPTH = 10;
-/**
- * Version strategy for OpenAPI 3.0.x specifications.
- *
- * OpenAPI 3.0 is the original version of the OpenAPI specification and differs
- * from 3.1 in several key ways:
- * - `nullable` keyword (not type arrays with "null")
- * - `exclusiveMinimum`/`exclusiveMaximum` as booleans modifying `minimum`/`maximum`
- * - `$ref` siblings are ignored (not merged)
- * - `example` keyword (not `examples`)
- * - `paths` is required
- */
-export class V3_0_VersionStrategy {
-    version() {
-        return '3.0';
-    }
-    matches(spec) {
-        if (!spec || typeof spec !== 'object' || Array.isArray(spec)) {
-            return false;
-        }
-        const specObj = spec;
-        const openapiVersion = specObj.openapi;
-        if (typeof openapiVersion === 'string') {
-            return openapiVersion.startsWith('3.0');
-        }
-        return false;
-    }
-    normalizeSpec(rawSpec) {
-        return normalizeSpec30(rawSpec);
-    }
-    validateSpec(spec) {
-        return validateSpec30(spec);
-    }
-    /**
-     * Resolve a $ref within the document. For OpenAPI 3.0, sibling properties
-     * alongside `$ref` are ignored — only the $ref target is returned.
-     */
-    resolveRef(ref, doc, _context) {
-        const resolving = new Set();
-        return this.resolveRefInternal(ref, doc, resolving, 0);
-    }
-    getSupportedFeatures() {
-        return ['nullable', 'example'];
-    }
-    resolveRefInternal(ref, doc, resolving, depth) {
-        if (ref.startsWith('http://') || ref.startsWith('https://')) {
-            throw new Error(`External $ref resolution is not supported: ${ref}`);
-        }
-        if (!ref.startsWith('#')) {
-            throw new Error(`External $ref resolution is not supported: ${ref}`);
-        }
-        if (depth >= MAX_REF_DEPTH) {
-            throw new Error(`Maximum $ref depth (${MAX_REF_DEPTH}) exceeded: ${ref}`);
-        }
-        if (resolving.has(ref)) {
-            const cyclePath = [...resolving, ref].join(' -> ');
-            throw new Error(`Circular $ref detected: ${cyclePath}`);
-        }
-        resolving.add(ref);
-        const pointer = ref.slice(1);
-        const segments = parseJsonPointer(pointer);
-        let current = doc;
-        for (const segment of segments) {
-            if (current === null || current === undefined) {
-                throw new Error(`$ref "${ref}" could not be resolved: segment "${segment}" not found`);
-            }
-            if (typeof current !== 'object') {
-                throw new Error(`$ref "${ref}" could not be resolved: segment "${segment}" is not an object`);
-            }
-            if (Array.isArray(current)) {
-                const index = Number(segment);
-                if (Number.isNaN(index)) {
-                    throw new Error(`$ref "${ref}" could not be resolved: "${segment}" is not a valid array index`);
-                }
-                current = current[index];
-            }
-            else {
-                current = current[segment];
-            }
-        }
-        if (current === undefined) {
-            throw new Error(`$ref "${ref}" could not be resolved`);
-        }
-        if (current !== null &&
-            typeof current === 'object' &&
-            !Array.isArray(current) &&
-            '$ref' in current) {
-            const chainedRef = current.$ref;
-            return this.resolveRefInternal(chainedRef, doc, new Set(resolving), depth + 1);
-        }
-        return current;
-    }
-}

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

@@ -1 +0,0 @@
-export { V3_1_VersionStrategy } from './strategy.js';

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

@@ -1 +0,0 @@
-export { V3_1_VersionStrategy } from './strategy.js';

package/dist/parser/version/v3.1/strategy.d.ts

@@ -1,42 +0,0 @@
-import type { ValidationResult } from '../../validators.js';
-import type { NormalizedSpec } from '../normalized-spec.js';
-import type { VersionStrategy } from '../version-strategy.js';
-/**
- * Version strategy for OpenAPI 3.1.x specifications.
- *
- * OpenAPI 3.1 is aligned with JSON Schema 2020-12 and supports:
- * - Type arrays (e.g., `type: ["string", "null"]`)
- * - Sibling properties alongside `$ref`
- * - `exclusiveMinimum`/`exclusiveMaximum` as numbers
- * - `webhooks` at the top level
- */
-export declare class V3_1_VersionStrategy implements VersionStrategy {
-    version(): string;
-    matches(spec: unknown): boolean;
-    /**
-     * Normalize a raw OpenAPI 3.1 specification to a consistent format.
-     *
-     * Schema normalization:
-     * - `type: "string"` → `types: ["string"]`
-     * - `type: ["string", "null"]` → `types: ["string"]`, `nullable: true`
-     * - `example: value` → `examples: [value]` (defensive)
-     * - `exclusiveMinimum`/`exclusiveMaximum` extracted as numbers
-     * - `format: "binary"` → `fileUpload: { binary: true, base64: false }`
-     * - `format: "byte"` → `fileUpload: { binary: false, base64: true }`
-     */
-    normalizeSpec(rawSpec: unknown): NormalizedSpec;
-    validateSpec(spec: NormalizedSpec): ValidationResult;
-    /**
-     * Resolve a $ref within the document. For OpenAPI 3.1, sibling properties
-     * alongside `$ref` are preserved via shallow merge (siblings override target).
-     */
-    resolveRef(ref: string, doc: unknown, context?: unknown): unknown;
-    getSupportedFeatures(): string[];
-    private resolveRefInternal;
-    private normalizeSchema;
-    private normalizePropertyMap;
-    private normalizePathItem;
-    private normalizeOperation;
-    private normalizeContentMap;
-    private normalizeParameter;
-}