genoc 0.1.0

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

@@ -0,0 +1,513 @@
+import { parseJsonPointer } from '../../../utils/url.js';
+const MAX_REF_DEPTH = 10;
+/**
+ * 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 class V3_1_VersionStrategy {
+    version() {
+        return '3.1';
+    }
+    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.1');
+        }
+        return false;
+    }
+    /**
+     * 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) {
+        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] = this.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] = this.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] = this.normalizePathItem(pathItem);
+                }
+            }
+        }
+        return {
+            openapi: typeof raw.openapi === 'string' ? raw.openapi : '3.1.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,
+        };
+    }
+    validateSpec(spec) {
+        const errors = [];
+        if (!spec.openapi || typeof spec.openapi !== 'string') {
+            errors.push("OpenAPI specification must have an 'openapi' field with string value");
+        }
+        else if (!spec.openapi.startsWith('3.1')) {
+            errors.push(`OpenAPI version must start with '3.1', got: ${spec.openapi}`);
+        }
+        if (!spec.info) {
+            errors.push("OpenAPI specification must have an 'info' field with object value");
+        }
+        else {
+            if (!spec.info.title) {
+                errors.push("Info object must have a 'title' field with string value");
+            }
+            if (!spec.info.version) {
+                errors.push("Info object must have a 'version' field with string value");
+            }
+        }
+        if (!spec.paths && !spec.components && !spec.webhooks) {
+            errors.push("OpenAPI specification must have at least one of 'paths', 'components', or 'webhooks'");
+        }
+        if (spec.paths) {
+            if (typeof spec.paths !== 'object' || Array.isArray(spec.paths)) {
+                errors.push("'paths' field must be an object");
+            }
+        }
+        if (spec.components?.schemas) {
+            if (typeof spec.components.schemas !== 'object' || Array.isArray(spec.components.schemas)) {
+                errors.push("'components.schemas' must be an object");
+            }
+            else {
+                for (const [key, schema] of Object.entries(spec.components.schemas)) {
+                    if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
+                        errors.push(`Schema '${key}' must be an object`);
+                    }
+                }
+            }
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+        };
+    }
+    /**
+     * Resolve a $ref within the document. For OpenAPI 3.1, sibling properties
+     * alongside `$ref` are preserved via shallow merge (siblings override target).
+     */
+    resolveRef(ref, doc, context) {
+        const resolving = new Set();
+        const resolved = this.resolveRefInternal(ref, doc, resolving, 0);
+        if (context && typeof context === 'object' && !Array.isArray(context)) {
+            const ctx = context;
+            const siblings = {};
+            let hasSiblings = false;
+            for (const [key, value] of Object.entries(ctx)) {
+                if (key !== '$ref') {
+                    siblings[key] = value;
+                    hasSiblings = true;
+                }
+            }
+            if (hasSiblings &&
+                resolved !== null &&
+                resolved !== undefined &&
+                typeof resolved === 'object' &&
+                !Array.isArray(resolved)) {
+                return {
+                    ...resolved,
+                    ...siblings,
+                };
+            }
+        }
+        return resolved;
+    }
+    getSupportedFeatures() {
+        return ['typeArrays', 'webhooks', 'nullable', 'jsonSchema202012'];
+    }
+    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;
+    }
+    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: [],
+                description: typeof s.description === 'string' ? s.description : undefined,
+            };
+        }
+        let types = [];
+        let nullable = false;
+        if (Array.isArray(s.type)) {
+            const typeArr = s.type;
+            if (typeArr.includes('null')) {
+                nullable = true;
+                types = typeArr.filter((t) => t !== 'null');
+            }
+            else {
+                types = [...typeArr];
+            }
+        }
+        else if (typeof s.type === 'string') {
+            types = [s.type];
+        }
+        if (s.nullable === true) {
+            nullable = true;
+        }
+        let examples = [];
+        if (Array.isArray(s.examples)) {
+            examples = [...s.examples];
+        }
+        else if (s.example !== undefined) {
+            examples = [s.example];
+        }
+        const exclusiveMinimum = typeof s.exclusiveMinimum === 'number' ? s.exclusiveMinimum : undefined;
+        const exclusiveMaximum = typeof s.exclusiveMaximum === 'number' ? s.exclusiveMaximum : undefined;
+        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 = this.normalizePropertyMap(s.properties);
+        const items = s.items ? this.normalizeSchema(s.items) : undefined;
+        const allOf = Array.isArray(s.allOf)
+            ? s.allOf.map((item) => this.normalizeSchema(item))
+            : undefined;
+        const oneOf = Array.isArray(s.oneOf)
+            ? s.oneOf.map((item) => this.normalizeSchema(item))
+            : undefined;
+        const anyOf = Array.isArray(s.anyOf)
+            ? s.anyOf.map((item) => this.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 = this.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,
+        };
+    }
+    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] = this.normalizeSchema(val);
+        }
+        return result;
+    }
+    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) => this.normalizeParameter(p));
+        }
+        for (const method of httpMethods) {
+            const op = pi[method];
+            if (op && typeof op === 'object' && !Array.isArray(op)) {
+                result[method] = this.normalizeOperation(op);
+            }
+        }
+        return result;
+    }
+    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) => this.normalizeParameter(p));
+        }
+        if (o.requestBody && typeof o.requestBody === 'object' && !Array.isArray(o.requestBody)) {
+            const rb = o.requestBody;
+            result.requestBody = {
+                content: this.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 = this.normalizeContentMap(r.content);
+                    if (r.links && typeof r.links === 'object')
+                        responses[code].links = r.links;
+                }
+            }
+            result.responses = responses;
+        }
+        return result;
+    }
+    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 = this.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;
+    }
+    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 = this.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.2/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Export for OpenAPI 3.2 version strategy
+ */
+export { V3_2_VersionStrategy } from './strategy.js';

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

@@ -0,0 +1,4 @@
+/**
+ * Export for OpenAPI 3.2 version strategy
+ */
+export { V3_2_VersionStrategy } from './strategy.js';

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

@@ -0,0 +1,39 @@
+import type { ValidationResult } from '../../validators.js';
+import type { NormalizedSpec } from '../normalized-spec.js';
+import type { VersionStrategy } from '../version-strategy.js';
+/**
+ * Stub strategy for OpenAPI 3.2.x specifications
+ *
+ * This strategy matches OpenAPI 3.2.x specifications but throws
+ * "not yet supported" errors until full implementation is available.
+ */
+export declare class V3_2_VersionStrategy implements VersionStrategy {
+    /**
+     * Get the supported OpenAPI version
+     */
+    version(): string;
+    /**
+     * Check if this strategy matches the given OpenAPI specification
+     */
+    matches(spec: unknown): boolean;
+    /**
+     * Normalize a raw OpenAPI specification to a consistent format
+     * Throws "not yet supported" error
+     */
+    normalizeSpec(_rawSpec: unknown): NormalizedSpec;
+    /**
+     * Validate the normalized specification
+     * Throws "not yet supported" error
+     */
+    validateSpec(_spec: NormalizedSpec): ValidationResult;
+    /**
+     * Resolve a reference within the document context
+     * Throws "not yet supported" error
+     */
+    resolveRef(_ref: string, _doc: unknown, _context?: unknown): unknown;
+    /**
+     * Get supported features for this version
+     * Returns empty array since version is not yet supported
+     */
+    getSupportedFeatures(): string[];
+}

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

@@ -0,0 +1,57 @@
+/**
+ * Stub strategy for OpenAPI 3.2.x specifications
+ *
+ * This strategy matches OpenAPI 3.2.x specifications but throws
+ * "not yet supported" errors until full implementation is available.
+ */
+export class V3_2_VersionStrategy {
+    /**
+     * Get the supported OpenAPI version
+     */
+    version() {
+        return '3.2';
+    }
+    /**
+     * Check if this strategy matches the given OpenAPI specification
+     */
+    matches(spec) {
+        if (!spec || typeof spec !== 'object' || Array.isArray(spec)) {
+            return false;
+        }
+        const specObj = spec;
+        const openapiVersion = specObj.openapi;
+        if (typeof openapiVersion === 'string') {
+            // Match 3.2.x versions (e.g., "3.2.0", "3.2.1", etc.)
+            return openapiVersion.startsWith('3.2');
+        }
+        return false;
+    }
+    /**
+     * Normalize a raw OpenAPI specification to a consistent format
+     * Throws "not yet supported" error
+     */
+    normalizeSpec(_rawSpec) {
+        throw new Error('OpenAPI 3.2 is not yet supported. Supported versions: 3.0, 3.1');
+    }
+    /**
+     * Validate the normalized specification
+     * Throws "not yet supported" error
+     */
+    validateSpec(_spec) {
+        throw new Error('OpenAPI 3.2 is not yet supported. Supported versions: 3.0, 3.1');
+    }
+    /**
+     * Resolve a reference within the document context
+     * Throws "not yet supported" error
+     */
+    resolveRef(_ref, _doc, _context) {
+        throw new Error('OpenAPI 3.2 is not yet supported. Supported versions: 3.0, 3.1');
+    }
+    /**
+     * Get supported features for this version
+     * Returns empty array since version is not yet supported
+     */
+    getSupportedFeatures() {
+        return [];
+    }
+}

package/dist/parser/version/version-detector.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Version detector for multi-version OpenAPI support
+ */
+export declare function detectSpecVersion(rawSpec: unknown): string;

package/dist/parser/version/version-detector.js

@@ -0,0 +1,34 @@
+/**
+ * Version detector for multi-version OpenAPI support
+ */
+export function detectSpecVersion(rawSpec) {
+    if (typeof rawSpec !== 'object' || rawSpec === null || Array.isArray(rawSpec)) {
+        throw new Error('Invalid spec: must be a non-null object');
+    }
+    const spec = rawSpec;
+    // Check for Swagger 2.0
+    if ('swagger' in spec && typeof spec.swagger === 'string') {
+        if (spec.swagger === '2.0') {
+            throw new Error('Swagger 2.0 is not supported. Convert to OpenAPI using swagger2openapi first.');
+        }
+        throw new Error(`Unsupported Swagger version: ${spec.swagger}`);
+    }
+    // Check for OpenAPI 3.0+
+    if (!('openapi' in spec) || typeof spec.openapi !== 'string') {
+        throw new Error("Invalid spec: missing or invalid 'openapi' field");
+    }
+    const openapiVersion = spec.openapi;
+    // Extract major.minor version
+    const versionMatch = openapiVersion.match(/^(\d+\.\d+)/);
+    if (!versionMatch) {
+        throw new Error(`Invalid OpenAPI version format: ${openapiVersion}`);
+    }
+    const majorMinorVersion = versionMatch[1];
+    // Validate supported versions
+    const supportedVersions = ['3.0', '3.1', '3.2'];
+    if (!supportedVersions.includes(majorMinorVersion)) {
+        throw new Error(`Unsupported OpenAPI version: ${openapiVersion}. ` +
+            `Supported versions: ${supportedVersions.join(', ')}`);
+    }
+    return majorMinorVersion;
+}