genoc 0.4.3 → 0.5.1

package/dist/analyzer/analyze.js

@@ -1,6 +1,7 @@
 import { RefResolver } from '../parser/ref-resolver.js';
 import { buildSchemaRenameMap, buildTypeJsDoc, sanitizeJsDocText, sanitizeTypeName, toPascalCase, } from '../utils/generator-helpers.js';
 import { operationEmissions, RESERVED_TYPE_NAMES } from '../utils/operation-naming.js';
+import { escapeStringLiteral } from '../utils/string.js';
 import { buildDiscriminatorRegistry, renameAwareTypeName } from './discriminator-registry.js';
 import { analyzePathsDetailed } from './path-analyzer.js';
 import { SchemaMapper } from './schema-mapper.js';
@@ -151,75 +152,92 @@ function topologicalSort(entries, allNames) {
     }
     return sorted;
 }
-function securitySchemeToTsType(scheme) {
-    const parts = [`type: "${scheme.type}"`];
+/**
+ * Build the `key: "value"` fragments of a security scheme object — shared by
+ * the contracts TYPE renderer (`'; '` separator) and the client CONST value
+ * renderer (`', '` separator).
+ */
+function schemeParts(scheme, separator) {
+    const parts = [`type: '${escapeStringLiteral(scheme.type)}'`];
     if (scheme.description) {
-        parts.push(`description: "${scheme.description}"`);
+        parts.push(`description: '${escapeStringLiteral(scheme.description)}'`);
     }
     if (scheme.type === 'apiKey') {
         if (scheme.name)
-            parts.push(`name: "${scheme.name}"`);
+            parts.push(`name: '${escapeStringLiteral(scheme.name)}'`);
         if (scheme.in)
-            parts.push(`in: "${scheme.in}"`);
+            parts.push(`in: '${escapeStringLiteral(scheme.in)}'`);
     }
     if (scheme.type === 'http') {
         if (scheme.scheme)
-            parts.push(`scheme: "${scheme.scheme}"`);
-        if (scheme.bearerFormat)
-            parts.push(`bearerFormat: "${scheme.bearerFormat}"`);
+            parts.push(`scheme: '${escapeStringLiteral(scheme.scheme)}'`);
+        if (scheme.bearerFormat) {
+            parts.push(`bearerFormat: '${escapeStringLiteral(scheme.bearerFormat)}'`);
+        }
     }
     if (scheme.type === 'oauth2' && scheme.flows) {
         const flowParts = [];
         const flows = scheme.flows;
         if (flows.implicit) {
-            flowParts.push(`implicit: ${oAuth2FlowToTs(flows.implicit, true)}`);
+            flowParts.push(`implicit: ${oAuth2FlowToTs(flows.implicit, true, separator)}`);
         }
         if (flows.password) {
-            flowParts.push(`password: ${oAuth2FlowToTs(flows.password, false)}`);
+            flowParts.push(`password: ${oAuth2FlowToTs(flows.password, false, separator)}`);
         }
         if (flows.clientCredentials) {
-            flowParts.push(`clientCredentials: ${oAuth2FlowToTs(flows.clientCredentials, false)}`);
+            flowParts.push(`clientCredentials: ${oAuth2FlowToTs(flows.clientCredentials, false, separator)}`);
         }
         if (flows.authorizationCode) {
-            flowParts.push(`authorizationCode: ${oAuth2FlowToTs(flows.authorizationCode, true)}`);
+            flowParts.push(`authorizationCode: ${oAuth2FlowToTs(flows.authorizationCode, true, separator)}`);
         }
-        parts.push(`flows: { ${flowParts.join('; ')} }`);
+        parts.push(`flows: { ${flowParts.join(separator)} }`);
     }
     if (scheme.type === 'openIdConnect' && scheme.openIdConnectUrl) {
-        parts.push(`openIdConnectUrl: "${scheme.openIdConnectUrl}"`);
+        parts.push(`openIdConnectUrl: '${escapeStringLiteral(scheme.openIdConnectUrl)}'`);
     }
-    return `{ ${parts.join('; ')} }`;
+    return parts;
+}
+function securitySchemeToTsType(scheme) {
+    return `{ ${schemeParts(scheme, '; ').join('; ')} }`;
 }
-function oAuth2FlowToTs(flow, hasAuthUrl) {
+/** The scheme object as a value expression — client-file consts (`as const`). */
+function securitySchemeConstExpression(scheme) {
+    return `{ ${schemeParts(scheme, ', ').join(', ')} } as const`;
+}
+function oAuth2FlowToTs(flow, hasAuthUrl, separator) {
     const entries = [];
     if (hasAuthUrl && flow.authorizationUrl) {
-        entries.push(`authorizationUrl: "${flow.authorizationUrl}"`);
+        entries.push(`authorizationUrl: '${escapeStringLiteral(flow.authorizationUrl)}'`);
     }
     if (flow.tokenUrl) {
-        entries.push(`tokenUrl: "${flow.tokenUrl}"`);
+        entries.push(`tokenUrl: '${escapeStringLiteral(flow.tokenUrl)}'`);
     }
     if (flow.refreshUrl) {
-        entries.push(`refreshUrl: "${flow.refreshUrl}"`);
+        entries.push(`refreshUrl: '${escapeStringLiteral(flow.refreshUrl)}'`);
     }
     const scopeEntries = Object.entries(flow.scopes)
-        .map(([k, v]) => `"${k}": "${v}"`)
-        .join('; ');
+        .map(([k, v]) => `'${escapeStringLiteral(k)}': '${escapeStringLiteral(v)}'`)
+        .join(separator);
     entries.push(`scopes: { ${scopeEntries} }`);
-    return `{ ${entries.join('; ')} }`;
+    return `{ ${entries.join(separator)} }`;
 }
 /**
  * Translate `components.securitySchemes` into finished `{Name}Auth` type
  * declarations: sanitize + PascalCase the key, number collisions, render the
- * object type text and the description JSDoc. Spec key order preserved.
+ * object type text, the client-file const, and the description JSDoc. Spec
+ * key order preserved; `$ref` entries resolved through the resolver.
  */
-function analyzeSecuritySchemes(securitySchemes) {
+function analyzeSecuritySchemes(securitySchemes, resolver) {
     const entries = [];
     if (!securitySchemes || Object.keys(securitySchemes).length === 0) {
         return entries;
     }
     const usedSecurityTypeNames = new Set();
-    for (const [schemeName, scheme] of Object.entries(securitySchemes)) {
-        const baseTypeName = `${sanitizeTypeName(toPascalCase(schemeName))}Auth`;
+    const usedConstNames = new Set();
+    for (const [schemeName, rawScheme] of Object.entries(securitySchemes)) {
+        const scheme = resolver.resolve(rawScheme);
+        const pascal = sanitizeTypeName(toPascalCase(schemeName));
+        const baseTypeName = `${pascal}Auth`;
         let typeName = baseTypeName;
         let n = 2;
         while (usedSecurityTypeNames.has(typeName)) {
@@ -227,14 +245,36 @@ function analyzeSecuritySchemes(securitySchemes) {
             n += 1;
         }
         usedSecurityTypeNames.add(typeName);
+        const baseConstName = `${pascal.charAt(0).toLowerCase()}${pascal.slice(1)}Scheme`;
+        let constName = baseConstName;
+        n = 2;
+        while (usedConstNames.has(constName)) {
+            constName = `${baseConstName}${n}`;
+            n += 1;
+        }
+        usedConstNames.add(constName);
         entries.push({
+            schemeName,
             name: typeName,
             tsType: securitySchemeToTsType(scheme),
             jsDoc: buildDescriptionJsDoc(scheme.description),
+            constName,
+            constExpression: securitySchemeConstExpression(scheme),
         });
     }
     return entries;
 }
+/**
+ * Resolve effective `security` requirements into per-call facts: each spec
+ * requirement object becomes one AND-list of `{ schemeName, scopes }` calls,
+ * `{}` becoming the empty (anonymous-access) alternative. Scheme names are
+ * passed through unfiltered; the client generator degrades gracefully if a
+ * name has no scheme (unreachable in practice — validation rejects unknown
+ * names before analysis runs).
+ */
+function analyzeSecurityRequirements(requirements) {
+    return requirements.map((requirement) => Object.entries(requirement).map(([schemeName, scopes]) => ({ schemeName, scopes })));
+}
 /**
  * Translate `doc.servers` into finished server variable interface
  * declarations, one per server that declares variables. Names are index-aware
@@ -406,9 +446,11 @@ export function analyze(doc, opts = {}) {
         if (pathParamTypeNames.size > 0) {
             op.pathParamTypeNames = [...pathParamTypeNames];
         }
+        const effectiveSecurity = op.security ?? doc.security;
         operations.push({
             ...op,
             contractsLines: [],
+            securityRequirements: effectiveSecurity === undefined ? [] : analyzeSecurityRequirements(effectiveSecurity),
         });
     }
     const hasFileUpload = operations.some((op) => op.requestBody?.isMultipart);
@@ -548,7 +590,7 @@ export function analyze(doc, opts = {}) {
     // Branded types snapshot after every mapSchema call has run, mirroring the
     // pre-refactor read position at the end of generateContracts.
     const brandedTypes = Array.from(mapper.getBrandedTypes().values());
-    const securitySchemeTypes = analyzeSecuritySchemes(doc.components?.securitySchemes);
+    const securitySchemeTypes = analyzeSecuritySchemes(doc.components?.securitySchemes, resolver);
     const serverTypes = analyzeServers(doc.servers);
     return {
         specVersion: doc.openapi,

package/dist/analyzer/path-analyzer.d.ts

@@ -1,6 +1,6 @@
 import { RefResolver } from '../parser/ref-resolver.js';
 import type { MethodNameStrategy } from '../types/client.js';
-import type { OpenAPIDocument, ReferenceObject, SchemaObject } from '../types/openapi.js';
+import type { OpenAPIDocument, ReferenceObject, SchemaObject, SecurityRequirementObject } from '../types/openapi.js';
 export interface AnalyzedParameter {
     name: string;
     in: 'path' | 'query' | 'header' | 'cookie';
@@ -79,6 +79,8 @@ export interface AnalyzedOperation {
     pathParamTypeNames?: string[];
     requestBody: AnalyzedRequestBody | undefined;
     responses: AnalyzedResponse[];
+    /** Raw operation-level `security`; `undefined` = inherit the document default. */
+    security?: SecurityRequirementObject[];
 }
 /**
  * Analyzer-internal analysis result: the analyzed operations plus the raw

package/dist/analyzer/path-analyzer.js

@@ -1,8 +1,8 @@
 import { RefResolver } from '../parser/ref-resolver.js';
 import { isBinaryContentType } from '../utils/generator-helpers.js';
+import { HTTP_METHODS } from '../utils/http-methods.js';
 import { getOperationTypePrefix } from '../utils/operation-naming.js';
 import { getMethodName } from './naming.js';
-const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'options', 'head', 'trace'];
 /**
  * Resolve a possibly-$ref-ed schema and check for an exact top-level `format: binary`
  * match. Top-level only — intentionally no deep-walk into items/allOf/oneOf/anyOf.
@@ -183,6 +183,7 @@ export function analyzePathsDetailed(doc, resolver, strategy = 'path-based') {
                 ...categorized,
                 requestBody: requestBodyResult?.requestBody,
                 responses,
+                security: operation.security,
             });
             requestBodySchemas.push(requestBodyResult?.rawSchema);
         }

package/dist/analyzer/types.d.ts

@@ -20,12 +20,29 @@ export interface TypeDeclaration {
  * and the description-only JSDoc block ('' when absent).
  */
 export interface SecuritySchemeTypeDeclaration {
+    /** Spec key under `components.securitySchemes` — the requirement lookup name. */
+    schemeName: string;
     /** Emitted `{Name}Auth` type name (sanitized, numbered on collision). */
     name: string;
     /** Rendered object type text — the `securitySchemeToTsType` output. */
     tsType: string;
     /** Description JSDoc block; '' when the scheme carries no description. */
     jsDoc: string;
+    /**
+     * Client-file const identifier holding the full scheme literal. Inline
+     * `scheme:` values in method bodies reference it — one const per scheme
+     * caps oauth2-flows bloat at a single site.
+     */
+    constName: string;
+    /** `{ … } as const` — the scheme object as a value expression. */
+    constExpression: string;
+}
+/** One scheme invocation inside an effective security requirement. */
+export interface AnalyzedSecurityCall {
+    /** Scheme name as declared in `components.securitySchemes` (spec key). */
+    schemeName: string;
+    /** Requested scopes/roles; empty for non-oauth2/openIdConnect schemes. */
+    scopes: string[];
 }
 /**
  * Finished server variable type declaration (contracts Section 1c). Names
@@ -81,6 +98,14 @@ export interface FinishedOperation extends AnalyzedOperation {
      * emission). Sole fact source for the client generator's FormData appends.
      */
     fileUploadProperties?: FileUploadPropertyFact[];
+    /**
+     * Effective security requirements (operation override ?? document default
+     * ?? none): an OR-list of AND-lists. Each call names its scheme by spec
+     * key; the client generator resolves it to a `securitySchemeTypes` const.
+     * `[]` = public operation (explicitly or by absence). An empty AND-list is
+     * the spec's `{}` — "anonymous access acceptable" alternative.
+     */
+    securityRequirements: AnalyzedSecurityCall[][];
 }
 /**
  * Single-pass analysis model of an OpenAPI document — the ONLY input every

package/dist/cli/impl.js

@@ -138,12 +138,14 @@ async function runOneTarget(target, context) {
     }
     context.process.stdout.write(`Loading spec from ${target.input}...\n`);
     const doc = await load(target.input, { proxy: target.proxy });
-    context.process.stdout.write(`Loaded OpenAPI ${doc.openapi} spec\n`);
     const override = target.specVersion;
     if (override !== undefined && override !== '3.0' && override !== '3.1') {
         throw new Error(`No strategy registered for version: ${override}`);
     }
+    // Resolve the dialect before logging so a missing/malformed `openapi`
+    // field is reported (with its spec link) instead of logging "undefined".
     const profile = resolveVersion(doc, override);
+    context.process.stdout.write(`Loaded OpenAPI ${doc.openapi} spec\n`);
     if (override !== undefined &&
         target.strictVersion !== false &&
         profile.detected !== profile.effective) {

package/dist/generator/client-generator.js

@@ -1,5 +1,6 @@
 import { DEFAULT_RUNTIME_IMPORT_PATH, makeHeader } from '../utils/generator-helpers.js';
 import { clientImportedNames, clientValueImports, getErrorType, getSuccessType, operationEmissions, } from '../utils/operation-naming.js';
+import { escapeStringLiteral } from '../utils/string.js';
 import { renderContracts } from './contracts-generator.js';
 import { generateMethod } from './method-generator.js';
 function collectImportTypes(operations) {
@@ -12,7 +13,34 @@ function collectImportTypes(operations) {
     // oxlint-disable-next-line unicorn/no-array-sort
     return [...types].sort();
 }
-function buildClientMethodBody(op) {
+/**
+ * Render the `security` option value for a call: `[[call, …], …]` — an
+ * OR-list of AND-lists, each call naming its scheme and pointing at the
+ * file-level scheme const. Returns `undefined` for public operations (option
+ * omitted) and when any scheme name is missing from the declared schemes
+ * (unreachable post-validation; degrades to omission rather than emitting a
+ * dangling reference).
+ */
+function buildSecurityExpression(requirements, schemeConsts) {
+    if (requirements.length === 0) {
+        return undefined;
+    }
+    const alternatives = [];
+    for (const requirement of requirements) {
+        const calls = [];
+        for (const call of requirement) {
+            const scheme = schemeConsts.get(call.schemeName);
+            if (scheme === undefined) {
+                return undefined;
+            }
+            const scopes = call.scopes.map((scope) => `'${escapeStringLiteral(scope)}'`).join(', ');
+            calls.push(`{ schemeName: '${escapeStringLiteral(call.schemeName)}', scopes: [${scopes}], scheme: ${scheme.constName} }`);
+        }
+        alternatives.push(`[${calls.join(', ')}]`);
+    }
+    return `[${alternatives.join(', ')}]`;
+}
+function buildClientMethodBody(op, schemeConsts) {
     const successType = getSuccessType(op);
     const emissions = operationEmissions(op);
     let urlTemplate = op.path;
@@ -67,6 +95,10 @@ function buildClientMethodBody(op) {
     if (op.headerParams.length > 0) {
         opts.push('headers');
     }
+    const securityExpression = buildSecurityExpression(op.securityRequirements, schemeConsts);
+    if (securityExpression !== undefined) {
+        opts.push(`security: ${securityExpression}`);
+    }
     const lines = [];
     if (op.requestBody?.isMultipart && op.fileUploadProperties !== undefined) {
         const bodyRequired = op.requestBody.required;
@@ -123,7 +155,23 @@ function buildClientMethodBody(op) {
     }
     return tryCatchLines.join('\n');
 }
-function buildClientFile(operations, version, runtimeImportPath = DEFAULT_RUNTIME_IMPORT_PATH) {
+/**
+ * Collect the scheme consts actually referenced by some operation's effective
+ * security — spec declaration order preserved. Schemes no operation uses are
+ * not emitted (dead weight in the client file).
+ */
+function collectUsedSchemeConsts(operations, securitySchemeTypes) {
+    const used = new Set();
+    for (const op of operations) {
+        for (const requirement of op.securityRequirements) {
+            for (const call of requirement) {
+                used.add(call.schemeName);
+            }
+        }
+    }
+    return securitySchemeTypes.filter((scheme) => used.has(scheme.schemeName));
+}
+function buildClientFile(operations, securitySchemeTypes, version, runtimeImportPath = DEFAULT_RUNTIME_IMPORT_PATH) {
     const lines = [];
     lines.push(makeHeader(version));
     const importTypes = collectImportTypes(operations);
@@ -142,6 +190,18 @@ function buildClientFile(operations, version, runtimeImportPath = DEFAULT_RUNTIM
     lines.push('');
     lines.push(`export { isDefinedError } from '${runtimeImportPath}';`);
     lines.push(`export type { Requester } from '${runtimeImportPath}';`);
+    const schemeConsts = new Map(securitySchemeTypes.map((scheme) => [scheme.schemeName, scheme]));
+    const usedSchemes = collectUsedSchemeConsts(operations, securitySchemeTypes);
+    if (usedSchemes.length > 0) {
+        lines.push('');
+        lines.push('/**');
+        lines.push(' * Security schemes (from `components.securitySchemes`) referenced by operations below.');
+        lines.push(' * Passed to the requester via the `security` option — auth decisions stay in user land.');
+        lines.push(' */');
+        for (const scheme of usedSchemes) {
+            lines.push(`const ${scheme.constName} = ${scheme.constExpression};`);
+        }
+    }
     lines.push('');
     lines.push('export function createClient(requester: Requester) {');
     lines.push('  return {');
@@ -155,7 +215,7 @@ function buildClientFile(operations, version, runtimeImportPath = DEFAULT_RUNTIM
                 .join('\n');
             lines.push(indentedJsDoc);
         }
-        const body = buildClientMethodBody(op);
+        const body = buildClientMethodBody(op, schemeConsts);
         const sig = method.signature;
         const firstParen = sig.indexOf('(');
         const closeParenColon = sig.indexOf('): ');
@@ -202,7 +262,7 @@ function buildIndexFile(version) {
  */
 export function renderClient(analyzed, config) {
     const runtimeImportPath = config.runtimeImportPath ?? DEFAULT_RUNTIME_IMPORT_PATH;
-    const client = buildClientFile(analyzed.operations, analyzed.specVersion, runtimeImportPath);
+    const client = buildClientFile(analyzed.operations, analyzed.securitySchemeTypes, analyzed.specVersion, runtimeImportPath);
     const index = buildIndexFile(analyzed.specVersion);
     return { client, index };
 }

package/dist/generator/contracts-generator.js

@@ -1,5 +1,6 @@
 import { DEFAULT_RUNTIME_IMPORT_PATH, makeHeader } from '../utils/generator-helpers.js';
 import { RUNTIME_CLASS_NAMES } from '../utils/operation-naming.js';
+import { escapeStringLiteral } from '../utils/string.js';
 /**
  * Build the import + re-export block for the shared runtime classes.
  * Generated code re-uses the genoc runtime as the single source of truth
@@ -53,6 +54,12 @@ export function renderContracts(analyzed, runtimeImportPath = DEFAULT_RUNTIME_IM
             lines.push('');
             lines.push(`export type ${entry.name} = ${entry.tsType};`);
         }
+        const nameMembers = analyzed.securitySchemeTypes
+            .map((entry) => `'${escapeStringLiteral(entry.schemeName)}'`)
+            .join(' | ');
+        lines.push('');
+        lines.push('/** Names of the security schemes declared in `components.securitySchemes` (spec keys). */');
+        lines.push(`export type SecuritySchemeName = ${nameMembers};`);
         if (analyzed.securitySchemeTypes.length > 1) {
             const unionMembers = analyzed.securitySchemeTypes.map((entry) => entry.name).join(' | ');
             lines.push('');

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

@@ -1,9 +1,17 @@
 import type { AnalyzedOperation } from '../analyzer/path-analyzer.js';
+import type { FinishedOperation } from '../analyzer/types.js';
 import type { GeneratedMethod } from '../types/client.js';
+/**
+ * Method rendering input: an analyzed operation plus the finished security
+ * facts when available (`analyze()` output; bare `AnalyzedOperation`s from
+ * path analysis render without the `@security` tag).
+ */
+type MethodOperation = AnalyzedOperation & Partial<Pick<FinishedOperation, 'securityRequirements'>>;
 /**
  * Generate a client method from an analyzed OpenAPI operation.
  *
  * @param op - The analyzed operation
  * @returns Generated method with name, JSDoc, and signature
  */
-export declare function generateMethod(op: AnalyzedOperation): GeneratedMethod;
+export declare function generateMethod(op: MethodOperation): GeneratedMethod;
+export {};

package/dist/generator/method-generator.js

@@ -94,6 +94,13 @@ function buildJsDoc(op) {
         }
         lines.push(` * @param body — request body`);
     }
+    const securitySummary = renderSecuritySummary(op.securityRequirements);
+    if (securitySummary !== undefined) {
+        if (lines.length > 0) {
+            lines.push(' *');
+        }
+        lines.push(` * @security ${sanitizeJsDocText(securitySummary)}`);
+    }
     if (op.tags && op.tags.length > 0) {
         if (lines.length > 0) {
             lines.push(' *');
@@ -122,6 +129,25 @@ function buildJsDoc(op) {
     }
     return `/**\n${lines.join('\n')}\n */`;
 }
+/**
+ * Render the `@security` tag text: OR-joined alternatives, AND-joined schemes
+ * within one alternative (parenthesized), scopes as `name[scope, …]`. An
+ * empty alternative is the spec's `{}` — rendered as `anonymous`. Returns
+ * `undefined` for public operations (no tag emitted).
+ */
+function renderSecuritySummary(requirements) {
+    if (requirements === undefined || requirements.length === 0) {
+        return undefined;
+    }
+    const alternatives = requirements.map((requirement) => {
+        const calls = requirement.map((call) => call.scopes.length > 0 ? `${call.schemeName}[${call.scopes.join(', ')}]` : call.schemeName);
+        if (calls.length === 0) {
+            return 'anonymous';
+        }
+        return calls.length > 1 ? `(${calls.join(' AND ')})` : (calls[0] ?? '');
+    });
+    return alternatives.join(' OR ');
+}
 /**
  * Generate a client method from an analyzed OpenAPI operation.
  *

package/dist/parser/spec-reader.js

@@ -5,23 +5,6 @@ import { fetchSpec } from '../utils/proxy.js';
 import { isUrl } from '../utils/url.js';
 const VALID_EXTENSIONS = ['.json', '.yaml', '.yml'];
 const MAX_FILE_SIZE = 50 * 1024 * 1024; // 50MB
-function assertSupportedVersion(doc) {
-    if (typeof doc !== 'object' ||
-        doc === null ||
-        !('openapi' in doc) ||
-        typeof doc.openapi !== 'string') {
-        throw new Error("Invalid spec: missing or invalid 'openapi' field.");
-    }
-    const version = doc.openapi;
-    // Check for valid version format
-    if (!version.match(/^\d+\.\d+(\.\d+)?$/)) {
-        throw new Error(`Invalid OpenAPI version format: ${version}`);
-    }
-    // Check that major version is 3 (but don't restrict minor versions)
-    if (!version.startsWith('3.')) {
-        throw new Error(`Unsupported OpenAPI version: ${version}. Supported versions: 3.0, 3.1, 3.2`);
-    }
-}
 function parseContent(content, ext) {
     if (ext === '.json') {
         try {
@@ -69,10 +52,10 @@ export async function loadFromFile(filePath) {
         throw new Error(`Failed to load spec from file: ${err.message}`, { cause: err });
     }
     const doc = parseContent(content, ext);
-    if (typeof doc !== 'object' || doc === null) {
-        throw new Error('Failed to parse: spec is not an object.');
-    }
-    assertSupportedVersion(doc);
+    // Version/dialect rules — including whether the parsed root is even an
+    // OpenAPI document — belong to the version module, which resolves the
+    // dialect and links spec violations to the specification. The cast is safe
+    // for the same I/O reason as above: callers validate via resolveVersion.
     return doc;
 }
 export async function loadFromUrl(url, opts) {
@@ -103,10 +86,8 @@ export async function loadFromUrl(url, opts) {
             throw new Error(`Failed to parse spec from URL as JSON or YAML: ${yamlErr.message}`, { cause: yamlErr });
         }
     }
-    if (typeof doc !== 'object' || doc === null) {
-        throw new Error('Failed to parse: spec is not an object.');
-    }
-    assertSupportedVersion(doc);
+    // Version/dialect rules — including document-rootedness — belong to the
+    // version module (see loadFromFile).
     return doc;
 }
 export async function load(source, opts) {

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

@@ -0,0 +1,55 @@
+/**
+ * Single source of links from spec-violation errors to the section of the
+ * OpenAPI specification that states the rule being violated.
+ *
+ * Unsupported-feature errors (Swagger 2.0, OpenAPI 3.2, external `$ref`s)
+ * never use this module: the document is valid and the error cites a genoc
+ * limitation, not a specification rule.
+ */
+/** Latest patch release per dialect. */
+export declare const SPEC_PAGE: Record<'3.0' | '3.1', string>;
+/**
+ * One anchor per violated rule, shared by both dialect pages. A wrong anchor
+ * is a one-line fix here; no automated anchor checking exists.
+ */
+export declare const SPEC_ANCHORS: {
+    readonly 'document-root': "openapi-object";
+    readonly 'openapi-field': "oas-version";
+    readonly 'info-object': "info-object";
+    readonly 'info-title': "info-title";
+    readonly 'info-version': "info-version";
+    readonly 'paths-object': "paths-object";
+    readonly 'path-item-object': "path-item-object";
+    readonly 'components-security-schemes': "security-scheme-object";
+    readonly 'components-schemas': "components-schemas";
+    readonly 'schema-object': "schema-object";
+    readonly 'security-scheme-object': "security-scheme-object-0";
+    readonly 'security-scheme-type': "security-scheme-type";
+    readonly 'security-scheme-name': "security-scheme-name";
+    readonly 'security-scheme-in': "security-scheme-in";
+    readonly 'security-scheme-scheme': "security-scheme-scheme";
+    readonly 'security-scheme-flows': "security-scheme-flows";
+    readonly 'security-scheme-open-id-connect-url': "security-scheme-open-id-connect-url";
+    readonly 'oauth-flow-object': "oauth-flow-object";
+    readonly 'oauth-flow-scopes': "oauth-flow-scopes";
+    readonly 'reference-object': "reference-object";
+    readonly 'security-requirement-object': "security-requirement-object";
+};
+export type SpecLinkKey = keyof typeof SPEC_ANCHORS;
+export declare function specLinkUrl(version: '3.0' | '3.1', key: SpecLinkKey): string;
+/**
+ * Renders a spec-violation message with its link line appended on its own
+ * line, indented four spaces so it aligns under the `  - ` bullet that
+ * `validateSpec` puts each message in.
+ */
+export declare function specViolation(version: '3.0' | '3.1', key: SpecLinkKey, message: string): string;
+/**
+ * Detection error for a document that violates the specification itself
+ * (as opposed to an unsupported-but-valid dialect). Carries the anchor key
+ * so `resolveVersion` can render the link against the dialect being applied.
+ */
+export declare class SpecViolationError extends Error {
+    /** Which specification section states the violated rule. */
+    linkKey: SpecLinkKey;
+    constructor(message: string, linkKey: SpecLinkKey);
+}

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

@@ -0,0 +1,65 @@
+/**
+ * Single source of links from spec-violation errors to the section of the
+ * OpenAPI specification that states the rule being violated.
+ *
+ * Unsupported-feature errors (Swagger 2.0, OpenAPI 3.2, external `$ref`s)
+ * never use this module: the document is valid and the error cites a genoc
+ * limitation, not a specification rule.
+ */
+/** Latest patch release per dialect. */
+export const SPEC_PAGE = {
+    '3.0': 'https://spec.openapis.org/oas/v3.0.4.html',
+    '3.1': 'https://spec.openapis.org/oas/v3.1.1.html',
+};
+/**
+ * One anchor per violated rule, shared by both dialect pages. A wrong anchor
+ * is a one-line fix here; no automated anchor checking exists.
+ */
+export const SPEC_ANCHORS = {
+    'document-root': 'openapi-object',
+    'openapi-field': 'oas-version',
+    'info-object': 'info-object',
+    'info-title': 'info-title',
+    'info-version': 'info-version',
+    'paths-object': 'paths-object',
+    'path-item-object': 'path-item-object',
+    'components-security-schemes': 'security-scheme-object',
+    'components-schemas': 'components-schemas',
+    'schema-object': 'schema-object',
+    'security-scheme-object': 'security-scheme-object-0',
+    'security-scheme-type': 'security-scheme-type',
+    'security-scheme-name': 'security-scheme-name',
+    'security-scheme-in': 'security-scheme-in',
+    'security-scheme-scheme': 'security-scheme-scheme',
+    'security-scheme-flows': 'security-scheme-flows',
+    'security-scheme-open-id-connect-url': 'security-scheme-open-id-connect-url',
+    'oauth-flow-object': 'oauth-flow-object',
+    'oauth-flow-scopes': 'oauth-flow-scopes',
+    'reference-object': 'reference-object',
+    'security-requirement-object': 'security-requirement-object',
+};
+export function specLinkUrl(version, key) {
+    return `${SPEC_PAGE[version]}#${SPEC_ANCHORS[key]}`;
+}
+/**
+ * Renders a spec-violation message with its link line appended on its own
+ * line, indented four spaces so it aligns under the `  - ` bullet that
+ * `validateSpec` puts each message in.
+ */
+export function specViolation(version, key, message) {
+    return `${message}\n    ${specLinkUrl(version, key)}`;
+}
+/**
+ * Detection error for a document that violates the specification itself
+ * (as opposed to an unsupported-but-valid dialect). Carries the anchor key
+ * so `resolveVersion` can render the link against the dialect being applied.
+ */
+export class SpecViolationError extends Error {
+    /** Which specification section states the violated rule. */
+    linkKey;
+    constructor(message, linkKey) {
+        super(message);
+        this.name = 'SpecViolationError';
+        this.linkKey = linkKey;
+    }
+}