genoc 0.1.0

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

@@ -0,0 +1,27 @@
+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

@@ -0,0 +1,96 @@
+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.0/validator.d.ts

@@ -0,0 +1,13 @@
+import type { ValidationResult } from '../../validators.js';
+/**
+ * Validate a raw OpenAPI 3.0.x specification.
+ *
+ * 3.0-specific validation rules:
+ * - `openapi` must start with "3.0"
+ * - `paths` is required (unlike 3.1 where paths/components/webhooks is flexible)
+ * - `info` with `title` and `version` required
+ * - Warns about 3.1-only features: `webhooks`, `$schema` in schemas, `type` as array
+ * - Accepts `nullable` and `example` (valid in 3.0, not in 3.1)
+ * - Errors on `items` as array (3.1-only tuple syntax)
+ */
+export declare function validateSpec30(spec: unknown): ValidationResult;

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

@@ -0,0 +1,117 @@
+/**
+ * Validate a raw OpenAPI 3.0.x specification.
+ *
+ * 3.0-specific validation rules:
+ * - `openapi` must start with "3.0"
+ * - `paths` is required (unlike 3.1 where paths/components/webhooks is flexible)
+ * - `info` with `title` and `version` required
+ * - Warns about 3.1-only features: `webhooks`, `$schema` in schemas, `type` as array
+ * - Accepts `nullable` and `example` (valid in 3.0, not in 3.1)
+ * - Errors on `items` as array (3.1-only tuple syntax)
+ */
+export function validateSpec30(spec) {
+    const errors = [];
+    if (!spec || typeof spec !== 'object' || Array.isArray(spec)) {
+        errors.push('Document must be an object');
+        return { valid: false, errors };
+    }
+    const s = spec;
+    if (!s.openapi || typeof s.openapi !== 'string') {
+        errors.push("OpenAPI specification must have an 'openapi' field with string value");
+    }
+    else if (!s.openapi.startsWith('3.0')) {
+        errors.push(`OpenAPI version must start with '3.0', got: ${s.openapi}`);
+    }
+    if (!s.info || typeof s.info !== 'object' || Array.isArray(s.info)) {
+        errors.push("OpenAPI specification must have an 'info' field with object value");
+    }
+    else {
+        const info = s.info;
+        if (!info.title || typeof info.title !== 'string') {
+            errors.push("Info object must have a 'title' field with string value");
+        }
+        if (!info.version || typeof info.version !== 'string') {
+            errors.push("Info object must have a 'version' field with string value");
+        }
+    }
+    if (!s.paths || typeof s.paths !== 'object' || Array.isArray(s.paths)) {
+        errors.push("OpenAPI 3.0 specification must have a 'paths' field with object value");
+    }
+    if (s.paths && typeof s.paths === 'object' && !Array.isArray(s.paths)) {
+        for (const [pathKey, pathItem] of Object.entries(s.paths)) {
+            if (!pathItem || typeof pathItem !== 'object' || Array.isArray(pathItem)) {
+                errors.push(`Path item '${pathKey}' must be an object`);
+            }
+        }
+    }
+    if (s.components && typeof s.components === 'object' && !Array.isArray(s.components)) {
+        const components = s.components;
+        if (components.schemas) {
+            if (Array.isArray(components.schemas) || typeof components.schemas !== 'object') {
+                errors.push("'components.schemas' must be an object");
+            }
+            else {
+                const schemas = components.schemas;
+                for (const [key, schema] of Object.entries(schemas)) {
+                    if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
+                        errors.push(`Schema '${key}' must be an object`);
+                    }
+                    else {
+                        validateSchema30(schema, `components.schemas.${key}`, errors);
+                    }
+                }
+            }
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}
+/**
+ * Recursively validate a schema object for 3.0-specific rules.
+ * Detects 3.1-only features and reports them as errors.
+ */
+function validateSchema30(schema, path, errors) {
+    if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
+        return;
+    }
+    const s = schema;
+    if (Array.isArray(s.type)) {
+        errors.push(`Schema '${path}' uses 'type' as an array which is a 3.1-only feature`);
+    }
+    if ('$schema' in s) {
+        errors.push(`Schema '${path}' uses '$schema' which is a 3.1-only feature`);
+    }
+    if (s.items !== undefined && Array.isArray(s.items)) {
+        errors.push(`Schema '${path}' uses 'items' as an array (tuple syntax) which is a 3.1-only feature`);
+    }
+    if (s.properties && typeof s.properties === 'object' && !Array.isArray(s.properties)) {
+        for (const [key, prop] of Object.entries(s.properties)) {
+            validateSchema30(prop, `${path}.properties.${key}`, errors);
+        }
+    }
+    if (s.items && typeof s.items === 'object' && !Array.isArray(s.items)) {
+        validateSchema30(s.items, `${path}.items`, errors);
+    }
+    if (s.additionalProperties &&
+        typeof s.additionalProperties === 'object' &&
+        !Array.isArray(s.additionalProperties)) {
+        validateSchema30(s.additionalProperties, `${path}.additionalProperties`, errors);
+    }
+    if (Array.isArray(s.allOf)) {
+        s.allOf.forEach((item, i) => {
+            validateSchema30(item, `${path}.allOf[${i}]`, errors);
+        });
+    }
+    if (Array.isArray(s.oneOf)) {
+        s.oneOf.forEach((item, i) => {
+            validateSchema30(item, `${path}.oneOf[${i}]`, errors);
+        });
+    }
+    if (Array.isArray(s.anyOf)) {
+        s.anyOf.forEach((item, i) => {
+            validateSchema30(item, `${path}.anyOf[${i}]`, errors);
+        });
+    }
+}

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

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

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

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

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

@@ -0,0 +1,42 @@
+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;
+}