@skmtc/core 0.0.984 → 0.16.1

package/esm/context/ParseContext.js

@@ -1,184 +1,467 @@
-var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
-    if (kind === "m") throw new TypeError("Private method is not writable");
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
-    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
-};
 var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
     if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _ParseContext_refStackTrails, _ParseContext_refErrors;
-import { toDocumentFieldsV3 } from '../oas/document/toDocumentFieldsV3.js';
+var _ParseContext_refConsumers, _ParseContext_refErrors;
+/**
+ * Unified parse context for both OAS and GraphQL inputs.
+ *
+ * One class, two protocol-specific states behind a discriminated union.
+ * Universal capabilities (issue collection, logger mirroring,
+ * dependency-ref tracking) live at the top of the class and apply to
+ * both protocols. Protocol-specific state (`oasDocument` vs
+ * `schema`/`registry`) sits on `this.protocol`, narrowed by
+ * `this.protocol.type`. The OAS-flavored logging surface
+ * (`logIssue`/`logIssueNoKey`/`logSkippedFields`) accepts a
+ * {@link StackTrail} for location; the GQL-flavored surface (`log`,
+ * `logSkippedFields` with a pre-computed `location` string) accepts a
+ * raw string. Both funnel into the shared {@link ParseContext.logIssueAt}.
+ *
+ * `removeErroredItems` is universal but its body dispatches on
+ * `protocol.type` — the cleanup step is document-shaped. The GQL branch
+ * is a no-op stub today; the infrastructure (the `#refConsumers` /
+ * `#refErrors` maps, `registerRef` / `registerRefError`) is in place
+ * for GQL parsers to populate when type-reference invalidation is
+ * needed.
+ */
+import "../_dnt.polyfills.js";
+import { buildSchema } from 'graphql';
+import { toDocumentFieldsV3 } from '../parse/v3-0/document/toDocumentFieldsV3.js';
+import { toDocumentFieldsV3 as toDocumentFieldsV31 } from '../parse/v3-1/document/toDocumentFieldsV3.js';
+import { toOasDialect } from '../parse/toOasDialect.js';
 import { OasDocument } from '../oas/document/Document.js';
+import { GqlRegistry } from '../gql/registry/GqlRegistry.js';
+import { GqlDocument } from '../gql/document/GqlDocument.js';
+import { parseGqlDocument } from '../gql/document/parseGqlDocument.js';
+import { StackTrail } from './StackTrail.js';
 export class ParseContext {
-    /**
-     * Creates a new ParseContext instance for the parsing phase.
-     *
-     * @param args - Constructor arguments including document object, logger, and options
-     */
-    constructor({ documentObject, logger, silent = true }) {
-        /** The original OpenAPI v3 document being parsed */
-        Object.defineProperty(this, "documentObject", {
+    constructor({ input, logger, silent = true, options }) {
+        Object.defineProperty(this, "issues", {
             enumerable: true,
             configurable: true,
             writable: true,
-            value: void 0
+            value: []
         });
-        /** Logger instance for tracking parse progress and issues */
         Object.defineProperty(this, "logger", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
-        /** The parsed OAS document result */
-        Object.defineProperty(this, "oasDocument", {
+        Object.defineProperty(this, "silent", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
-        /** Collection of parsing issues encountered during processing */
-        Object.defineProperty(this, "issues", {
+        Object.defineProperty(this, "protocol", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
-        /** Whether to suppress console output during parsing */
-        Object.defineProperty(this, "silent", {
+        /**
+         * The StackTrail of the currently-traversed position. Set by
+         * factories via {@link ParseContext.withStackTrail} just before
+         * constructing the node so the `OasBase` base can snapshot it.
+         * `undefined` outside an active `withStackTrail` scope.
+         */
+        Object.defineProperty(this, "currentStackTrail", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
-        _ParseContext_refStackTrails.set(this, void 0);
-        _ParseContext_refErrors.set(this, void 0);
-        this.documentObject = documentObject;
+        // Universal dependency-ref tracking. Populated by parsers as they
+        // encounter references. OAS uses `$ref` strings as keys; GQL would
+        // use type names. The maps don't care about the encoding.
+        _ParseContext_refConsumers.set(this, new Map());
+        _ParseContext_refErrors.set(this, new Map());
         this.logger = logger;
-        this.oasDocument = new OasDocument();
         this.silent = silent;
-        this.issues = [];
-        __classPrivateFieldSet(this, _ParseContext_refStackTrails, {}, "f");
-        __classPrivateFieldSet(this, _ParseContext_refErrors, {}, "f");
+        switch (input.type) {
+            case 'oas': {
+                this.protocol = {
+                    type: 'oas',
+                    documentObject: input.value,
+                    oasDocument: new OasDocument()
+                };
+                break;
+            }
+            case 'gql': {
+                const schema = typeof input.value === 'string' ? buildSchema(input.value) : input.value;
+                this.protocol = {
+                    type: 'gql',
+                    schema,
+                    registry: new GqlRegistry({ schemas: {} }),
+                    // Empty `GqlDocument` issued up front so any `OasRef`
+                    // constructed during the walk has a stable resolution target.
+                    // `parse()` populates `gqlDocument.fields` once the walk
+                    // produces operations / rootTypes.
+                    gqlDocument: new GqlDocument(),
+                    options: options?.gql ?? {}
+                };
+                break;
+            }
+            default: {
+                const _exhaustive = input;
+                throw new Error(`Unhandled document input type: ${JSON.stringify(_exhaustive)}`);
+            }
+        }
     }
     /**
-     * Parses the OpenAPI v3 document and returns the internal OAS document representation.
-     *
-     * @returns Parsed OAS document with all components and operations
+     * OAS-only accessor. Throws when called on a GQL-protocol context —
+     * deliberate, because OAS parser code uses this and a misroute is a
+     * real bug, not a recoverable situation.
      */
-    parse(stackTrail) {
-        this.oasDocument.fields = toDocumentFieldsV3({
-            documentObject: this.documentObject,
-            stackTrail: stackTrail,
-            context: this
-        });
-        this.removeErroredItems();
-        return this.oasDocument;
+    get oasDocument() {
+        if (this.protocol.type !== 'oas') {
+            throw new Error('oasDocument accessed on non-OAS ParseContext');
+        }
+        return this.protocol.oasDocument;
+    }
+    /** OAS-only accessor; symmetric reason to {@link oasDocument}. */
+    get documentObject() {
+        if (this.protocol.type !== 'oas') {
+            throw new Error('documentObject accessed on non-OAS ParseContext');
+        }
+        return this.protocol.documentObject;
+    }
+    /** GQL-only accessor; throws if called on an OAS context. */
+    get schema() {
+        if (this.protocol.type !== 'gql') {
+            throw new Error('schema accessed on non-GQL ParseContext');
+        }
+        return this.protocol.schema;
+    }
+    /** GQL-only accessor; throws if called on an OAS context. */
+    get registry() {
+        if (this.protocol.type !== 'gql') {
+            throw new Error('registry accessed on non-GQL ParseContext');
+        }
+        return this.protocol.registry;
     }
     /**
-     * Removes items from the parsed document that encountered errors during parsing.
+     * GQL-only accessor returning the in-flight `GqlDocument` (empty
+     * during parse, populated at the end). Parsers use this when
+     * constructing `OasRef`s via `registry.createRef(refName, context)`
+     * so the resulting refs point at the right document instance.
      */
-    removeErroredItems() {
-        Object.entries(__classPrivateFieldGet(this, _ParseContext_refErrors, "f")).forEach(([$ref, errors]) => {
-            errors.forEach(error => {
-                __classPrivateFieldGet(this, _ParseContext_refStackTrails, "f")[$ref]?.forEach(stackTrail => {
-                    const removed = this.oasDocument.removeItem(stackTrail);
-                    if (removed) {
-                        this.issues.push({
-                            level: 'error',
-                            error,
-                            location: stackTrail.toString(),
-                            parent: removed,
-                            type: 'INVALID_DEPENDENCY_REF'
+    get gqlDocument() {
+        if (this.protocol.type !== 'gql') {
+            throw new Error('gqlDocument accessed on non-GQL ParseContext');
+        }
+        return this.protocol.gqlDocument;
+    }
+    /**
+     * Convenience: returns the discriminated `SkmtcParsedDocument` for
+     * the active protocol. Useful for parser code that needs to hand a
+     * document to `OasRef` (or `registry.createRef`) without manually
+     * constructing the wrapper.
+     */
+    get parsedDocument() {
+        switch (this.protocol.type) {
+            case 'oas':
+                return { type: 'oas', value: this.protocol.oasDocument };
+            case 'gql':
+                return { type: 'gql', value: this.protocol.gqlDocument };
+            default: {
+                const _exhaustive = this.protocol;
+                throw new Error(`Unhandled protocol type: ${JSON.stringify(_exhaustive)}`);
+            }
+        }
+    }
+    /**
+     * Runs the protocol-appropriate parse step and returns the result
+     * wrapped in {@link SkmtcParsedDocument}. `stackTrail` is required
+     * for OAS (used by `toDocumentFieldsV3` for issue location tracking)
+     * and ignored by GQL (which uses pre-computed schema addresses).
+     */
+    parse(stackTrail) {
+        switch (this.protocol.type) {
+            case 'oas': {
+                const oasState = this.protocol;
+                // The ONE place the OpenAPI version is examined: pick the dialect's
+                // parser tree. Everything downstream is version-specific code living
+                // in its own tree (v3-0 / v3-1) and never re-checks the version.
+                const dialect = toOasDialect(oasState.documentObject.openapi);
+                switch (dialect) {
+                    case '3.0':
+                        oasState.oasDocument.fields = toDocumentFieldsV3({
+                            documentObject: oasState.documentObject,
+                            stackTrail,
+                            context: this
                         });
+                        break;
+                    case '3.1':
+                        oasState.oasDocument.fields = toDocumentFieldsV31({
+                            documentObject: oasState.documentObject,
+                            stackTrail,
+                            context: this
+                        });
+                        break;
+                    default: {
+                        const _exhaustive = dialect;
+                        throw new Error(`Unhandled OAS dialect: ${JSON.stringify(_exhaustive)}`);
                     }
+                }
+                this.removeErroredItems();
+                return { type: 'oas', value: oasState.oasDocument };
+            }
+            case 'gql': {
+                const gqlState = this.protocol;
+                const { fields } = parseGqlDocument({
+                    options: gqlState.options,
+                    context: this,
+                    stackTrail
                 });
-            });
-        });
+                // Populate the empty `GqlDocument` issued at construction time.
+                // Refs constructed during the walk hold a reference to this same
+                // instance and now resolve through its filled registry.
+                gqlState.gqlDocument.fields = fields;
+                this.removeErroredItems();
+                return { type: 'gql', value: gqlState.gqlDocument };
+            }
+            default: {
+                const _exhaustive = this.protocol;
+                throw new Error(`Unhandled protocol type: ${JSON.stringify(_exhaustive)}`);
+            }
+        }
     }
     /**
-     * Registers a reference ($ref) with its associated stack trail for error tracking.
-     *
-     * @param stackTrail - Current processing context stack trail
-     * @param $ref - OpenAPI reference string to register
+     * Walks any registered ref errors and prunes their consumers from
+     * the parsed document. Symmetric across protocols: OAS prunes via
+     * `OasDocument.removeItem`, GQL via `GqlDocument.removeItem`. Each
+     * pruned consumer yields an `INVALID_DEPENDENCY_REF` issue.
      */
-    registerRef(stackTrail, $ref) {
-        const refStackTrails = __classPrivateFieldGet(this, _ParseContext_refStackTrails, "f")[$ref];
-        refStackTrails ? refStackTrails.push(stackTrail) : (__classPrivateFieldGet(this, _ParseContext_refStackTrails, "f")[$ref] = [stackTrail]);
+    removeErroredItems() {
+        switch (this.protocol.type) {
+            case 'oas': {
+                const oasState = this.protocol;
+                for (const [refKey, errors] of __classPrivateFieldGet(this, _ParseContext_refErrors, "f")) {
+                    for (const error of errors) {
+                        const consumers = __classPrivateFieldGet(this, _ParseContext_refConsumers, "f").get(refKey) ?? [];
+                        for (const stackTrail of consumers) {
+                            const removed = oasState.oasDocument.removeItem(stackTrail);
+                            if (removed) {
+                                this.issues.push({
+                                    protocol: 'oas',
+                                    level: 'error',
+                                    type: 'INVALID_DEPENDENCY_REF',
+                                    location: stackTrail.toString(),
+                                    message: error instanceof Error ? error.message : String(error),
+                                    cause: error
+                                });
+                            }
+                        }
+                    }
+                }
+                break;
+            }
+            case 'gql': {
+                const gqlState = this.protocol;
+                for (const [refKey, errors] of __classPrivateFieldGet(this, _ParseContext_refErrors, "f")) {
+                    for (const error of errors) {
+                        const consumers = __classPrivateFieldGet(this, _ParseContext_refConsumers, "f").get(refKey) ?? [];
+                        for (const stackTrail of consumers) {
+                            const removed = gqlState.gqlDocument.removeItem(stackTrail);
+                            if (removed) {
+                                this.issues.push({
+                                    protocol: 'gql',
+                                    level: 'error',
+                                    type: 'INVALID_DEPENDENCY_REF',
+                                    location: stackTrail.toString(),
+                                    message: error instanceof Error ? error.message : String(error),
+                                    cause: error
+                                });
+                            }
+                        }
+                    }
+                }
+                break;
+            }
+            default: {
+                const _exhaustive = this.protocol;
+                throw new Error(`Unhandled protocol type: ${JSON.stringify(_exhaustive)}`);
+            }
+        }
     }
     /**
-     * Registers an error that occurred while processing a reference.
+     * Run `fn` with `currentStackTrail` set to the given trail; restore
+     * the previous value afterwards (try/finally semantics). Factories
+     * wrap schema-construction in this so `OasBase` can snapshot the
+     * trail off the context without each factory threading it
+     * explicitly into the constructor.
      *
-     * @param error - Error that occurred during reference processing
-     * @param $ref - Reference string that caused the error (if available)
+     * @example
+     * ```ts
+     * return context.withStackTrail(stackTrail, () =>
+     *   new OasBoolean({ title, ... }, context)
+     * )
+     * ```
      */
-    registerRefError(error, $ref) {
-        if ($ref) {
-            const refErrors = __classPrivateFieldGet(this, _ParseContext_refErrors, "f")[$ref];
-            refErrors ? refErrors.push(error) : (__classPrivateFieldGet(this, _ParseContext_refErrors, "f")[$ref] = [error]);
+    withStackTrail(stackTrail, fn) {
+        const prev = this.currentStackTrail;
+        this.currentStackTrail = stackTrail;
+        try {
+            return fn();
+        }
+        finally {
+            this.currentStackTrail = prev;
         }
     }
     /**
-     * Logs warnings for fields that were skipped during parsing.
-     *
-     * @param args - Arguments containing skipped fields and parent context
+     * Register a `$ref`-style consumer site. The key encoding is up to
+     * the caller — OAS uses `#/components/schemas/User` strings, GQL
+     * would use type names or qualified field paths.
      */
-    logSkippedFields({ skipped, stackTrail, parent, parentType }) {
-        Object.keys(skipped).forEach(key => {
-            this.logIssue({
-                key,
-                stackTrail,
-                parent,
-                level: 'warning',
-                message: `Unexpected property '${key}' in '${parentType}'`,
-                type: 'UNEXPECTED_PROPERTY'
-            });
-        });
+    registerRef(consumer, refKey) {
+        const existing = __classPrivateFieldGet(this, _ParseContext_refConsumers, "f").get(refKey);
+        if (existing) {
+            existing.push(consumer);
+        }
+        else {
+            __classPrivateFieldGet(this, _ParseContext_refConsumers, "f").set(refKey, [consumer]);
+        }
     }
-    // /**
-    //  * Executes a function within a traced context for debugging and monitoring.
-    //  *
-    //  * @param token - Trace identifier or path segments
-    //  * @param fn - Function to execute within the trace context
-    //  * @returns The result of the traced function execution
-    //  */
-    // trace<T>(token: string, fn: () => T): T {
-    //   return tracer(this.stackTrail, token, fn, this.logger)
-    // }
     /**
-     * Logs a parsing issue with associated key context.
+     * Register an error against a ref key — typically called when the
+     * target of a `$ref` (or type reference) fails to parse. `undefined`
+     * `refKey` is a deliberate no-op: callers may pass the result of
+     * `StackTrail.toStackRef()` directly, which is `undefined` for
+     * non-component stack trails.
+     */
+    registerRefError(error, refKey) {
+        if (!refKey)
+            return;
+        const existing = __classPrivateFieldGet(this, _ParseContext_refErrors, "f").get(refKey);
+        if (existing) {
+            existing.push(error);
+        }
+        else {
+            __classPrivateFieldGet(this, _ParseContext_refErrors, "f").set(refKey, [error]);
+        }
+    }
+    /**
+     * Universal issue recorder. Pushes to `issues` and (when not silent)
+     * mirrors to the logger. Both protocols' surface methods funnel
+     * here.
      *
-     * @param args - Issue arguments including key, parent object, and issue details
+     * `parent` is an optional log-time-only field — surface methods
+     * forward the surrounding object so log readers see its shape, not
+     * just the leaf address. Stringified here so the logger payload
+     * stays JSON-clonable. It is intentionally **not** stored on the
+     * persisted `ParseIssue` (which would require clone-safe
+     * serialization across the worker boundary and would bloat the
+     * manifest).
      */
+    logIssueAt(issue, parent) {
+        this.issues.push(issue);
+        if (!this.silent) {
+            this.logger.warn({
+                protocol: issue.protocol,
+                level: issue.level,
+                location: issue.location,
+                message: issue.message,
+                type: issue.type,
+                ...(parent === undefined ? {} : { parent: JSON.stringify(parent) })
+            });
+        }
+    }
+    // -- OAS-flavored surface (StackTrail-based) ---------------------
     logIssue({ key, parent, type, stackTrail, ...issue }) {
         stackTrail.trace(key, st => this.logIssueNoKey({ parent, type, stackTrail: st, ...issue }));
     }
+    logIssueNoKey({ parent, type, stackTrail, ...issue }) {
+        const location = stackTrail.toString();
+        // Protocol is set from the active context; callers don't have to
+        // pass it. `LogIssueAtArgs` discriminates `type` by protocol, so
+        // the type-system narrowing happens at the LogIssueAtArgs boundary —
+        // we widen here because LogIssueNoKey accepts either protocol's
+        // type enum.
+        const protocol = this.protocol.type;
+        // The casts below bridge LogIssueNoKeyArgs (widened type field,
+        // covers both protocols) to LogIssueAtArgs (narrowed per
+        // protocol). Callers are responsible for passing a `type` from
+        // the matching protocol's enum; the stored ParseIssue then
+        // carries the correct combination.
+        switch (issue.level) {
+            case 'error': {
+                // Auto-register against the component-shaped ref the trail
+                // points at. No-op for non-component trails (and for GQL
+                // trails) because `toStackRef` returns `undefined` and
+                // `registerRefError` ignores undefined refs.
+                this.registerRefError(issue.cause ?? issue.message, stackTrail.toStackRef());
+                this.logIssueAt({
+                    protocol,
+                    level: 'error',
+                    type,
+                    location,
+                    message: issue.message,
+                    cause: issue.cause
+                }, parent);
+                break;
+            }
+            case 'warning': {
+                this.logIssueAt({
+                    protocol,
+                    level: 'warning',
+                    type,
+                    location,
+                    message: issue.message
+                }, parent);
+                break;
+            }
+            default: {
+                const _exhaustive = issue;
+                throw new Error(`Unhandled parse-issue level: ${JSON.stringify(_exhaustive)}`);
+            }
+        }
+    }
     /**
-     * Logs a parsing issue without specific key context.
+     * Thin convenience for recording an issue at a pre-computed string
+     * `location` rather than threading a {@link StackTrail}. Use this
+     * for issues whose natural address isn't a tree position:
+     *
+     *   - Schema-level directive definitions (`@auth`) — flat namespace,
+     *     no parent type.
+     *   - Catch-all error paths where the parsed entity doesn't exist
+     *     yet (the parse threw before producing one).
      *
-     * @param args - Issue arguments including parent object and issue details
+     * For tree-position issues, prefer {@link logIssueNoKey} so the
+     * stack trail composes with the surrounding traces.
+     *
+     * Internally constructs a `StackTrail` from `location.split(':')`
+     * and delegates to {@link logIssueNoKey} — the underlying issue
+     * recording logic (protocol tagging, optional ref-error
+     * auto-registration, logger mirror with parent context) is shared.
      */
-    logIssueNoKey({ parent, type, stackTrail, ...issue }) {
-        if (issue.level === 'error') {
-            this.registerRefError(issue.error, stackTrail.toStackRef());
-        }
-        this.issues.push({
-            ...issue,
-            location: stackTrail.toString(),
-            parent,
-            type
-        });
-        if (!this.silent) {
-            this.logger.warn({
-                ...issue,
-                location: stackTrail.toString(),
-                parent: JSON.stringify(parent),
+    log({ location, parent, type, ...issue }) {
+        const stackTrail = new StackTrail(location.split(':'));
+        this.logIssueNoKey({ stackTrail, parent, type, ...issue });
+    }
+    /**
+     * Records one warning per unrecognized key under `parent`.
+     *
+     * Each skipped key is traced as a child of `stackTrail` so the
+     * resulting issue locations point at the offending property, not
+     * the parent. `parentType` is used in the message text
+     * (`Unexpected property 'foo' in 'SchemaObject'`); `type` defaults
+     * to `UNEXPECTED_PROPERTY` (the OAS convention) but GQL callers can
+     * pass a more specific category like `SKIPPED_FIELD_ARGUMENTS`.
+     */
+    logSkippedFields({ skipped, stackTrail, parent, parentType, type = 'UNEXPECTED_PROPERTY' }) {
+        Object.keys(skipped).forEach(key => {
+            this.logIssue({
+                key,
+                stackTrail,
+                parent,
+                level: 'warning',
+                message: `Unexpected property '${key}' in '${parentType}'`,
                 type
             });
-        }
+        });
     }
 }
-_ParseContext_refStackTrails = new WeakMap(), _ParseContext_refErrors = new WeakMap();
+_ParseContext_refConsumers = new WeakMap(), _ParseContext_refErrors = new WeakMap();

package/esm/context/ParseIssue.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Unified discriminated union for parse-time issues across both OAS and
+ * GraphQL parsing. Each variant stands on its own — no shared base —
+ * so TypeScript narrows cleanly on `protocol` and `level`.
+ *
+ * `cause?: unknown` is only present on the error variants. Warnings are
+ * synthesized by the parser with all the information needed for the
+ * `message`; errors usually wrap a thrown `Error`, which we keep in
+ * `cause` for debugging without forcing renderers to know about it.
+ *
+ * `location` is the schema-level address of the issue: for OAS it's the
+ * stringified stack trail (e.g. `components.schemas.User.properties.email`);
+ * for GraphQL it's the schema-level address used by the GQL parser
+ * (e.g. `Query.getUser.return`).
+ */
+import * as v from 'valibot';
+import type { OasIssueType } from './generateTypes.js';
+/**
+ * Categories of issues recorded during GraphQL → OAS mapping.
+ *
+ * Kept narrow on purpose. Extend only when a new lossy/diagnostic
+ * code path is added — open-ended categories rot fast.
+ *
+ * - `NESTED_LIST_LOSSY` — `[[T]]` collapsed to `OasUnknown`.
+ * - `UNKNOWN_TYPE_KIND` — defensive fallback for an unrecognized
+ *   GraphQL type kind. Should never fire in practice.
+ * - `DROPPED_DIRECTIVE` — applied directive ignored during mapping
+ *   (other than `@deprecated`, whose `reason` we capture).
+ * - `SKIPPED_FIELD_ARGUMENTS` — non-root object/interface field
+ *   carries arguments we don't model. Surfaces as a list of arg
+ *   names so the user can see what's lost.
+ * - `SKIPPED_FEATURE` — catch-all for other GraphQL features that
+ *   don't translate (schema-level directive definitions, type
+ *   extensions, etc.).
+ * - `INVALID_TYPE_DEFINITION` — a top-level named type (object,
+ *   input, interface, union, scalar, enum) threw during parse. The
+ *   type is dropped from the registry and the wrapped error rides
+ *   along as `cause`. Mirrors the role of OAS's `INVALID_SCHEMA` at
+ *   the component layer.
+ * - `INVALID_DEPENDENCY_REF` — a field, union member, or interface
+ *   implementer references a type that failed to parse, and the
+ *   consumer was pruned by `removeErroredItems`. Mirrors OAS's
+ *   identically-named issue.
+ */
+export type GqlIssueType = 'NESTED_LIST_LOSSY' | 'UNKNOWN_TYPE_KIND' | 'DROPPED_DIRECTIVE' | 'SKIPPED_FIELD_ARGUMENTS' | 'SKIPPED_FEATURE' | 'INVALID_TYPE_DEFINITION' | 'INVALID_DEPENDENCY_REF';
+/**
+ * Valibot schema for {@link GqlIssueType}. Annotation deliberately
+ * omitted so the precise literal-union output type flows through to
+ * consumers; drift between this list and {@link GqlIssueType} is
+ * caught by the compile-time assertion below.
+ */
+export declare const gqlIssueType: v.UnionSchema<[v.LiteralSchema<"NESTED_LIST_LOSSY", undefined>, v.LiteralSchema<"UNKNOWN_TYPE_KIND", undefined>, v.LiteralSchema<"DROPPED_DIRECTIVE", undefined>, v.LiteralSchema<"SKIPPED_FIELD_ARGUMENTS", undefined>, v.LiteralSchema<"SKIPPED_FEATURE", undefined>, v.LiteralSchema<"INVALID_TYPE_DEFINITION", undefined>, v.LiteralSchema<"INVALID_DEPENDENCY_REF", undefined>], undefined>;
+export type ParseIssue = {
+    protocol: 'oas';
+    level: 'error';
+    type: OasIssueType;
+    location: string;
+    message: string;
+    cause?: unknown;
+} | {
+    protocol: 'oas';
+    level: 'warning';
+    type: OasIssueType;
+    location: string;
+    message: string;
+} | {
+    protocol: 'gql';
+    level: 'error';
+    type: GqlIssueType;
+    location: string;
+    message: string;
+    cause?: unknown;
+} | {
+    protocol: 'gql';
+    level: 'warning';
+    type: GqlIssueType;
+    location: string;
+    message: string;
+};
+//# sourceMappingURL=ParseIssue.d.ts.map