@skmtc/core 0.0.983 → 0.16.1

package/script/gql/document/GqlDocument.d.ts

@@ -0,0 +1,93 @@
+import type { GqlRegistry } from '../registry/GqlRegistry.js';
+import type { GqlOperation } from '../operation/GqlOperation.js';
+import type { GqlRootTypes } from '../rootType/GqlRootTypes.js';
+import type { OasInfo } from '../../oas/info/Info.js';
+import type { StackTrail } from '../../context/StackTrail.js';
+/**
+ * Fields used to construct (or populate) a {@link GqlDocument}.
+ */
+export type GqlDocumentFields = {
+    /** Type registry containing all named GraphQL types as OAS schema objects. */
+    registry: GqlRegistry;
+    /** Root-level fields exposed as Query, Mutation, or Subscription. */
+    operations: GqlOperation[];
+    /** Names of the root operation types (Query, Mutation, Subscription). */
+    rootTypes: GqlRootTypes;
+    /** Schema-level metadata (title, version, description). Optional. */
+    info?: OasInfo;
+};
+/**
+ * Top-level container for a parsed GraphQL schema.
+ *
+ * `GqlDocument` is the GraphQL counterpart to {@link OasDocument}. It owns
+ * a {@link GqlRegistry} (the named-type registry, parallel to
+ * `OasComponents.schemas`), the list of root-level fields exposed as
+ * {@link GqlOperation} entries, and pointers to the schema's root operation
+ * types.
+ *
+ * Both documents are wrapped by {@link SkmtcParsedDocument} so the pipeline
+ * can carry either through the same generate phase.
+ *
+ * ## Empty-at-construction
+ *
+ * Like {@link OasDocument}, `GqlDocument` is intentionally constructable
+ * without fields — the parser creates an empty instance up front, hands
+ * out `OasRef`s that resolve through it, then populates
+ * `gqlDocument.fields = { ... }` at the end of parsing. See the
+ * "forward-declared refs" section on {@link OasDocument} for the full
+ * rationale; the short version is that refs need a stable resolution
+ * target *before* every target has been parsed, so the document and the
+ * refs that point at it must both be constructable up front and tied to
+ * the same instance.
+ */
+export declare class GqlDocument {
+    #private;
+    readonly oasType: "gqlDocument";
+    /**
+     * Creates a new GqlDocument instance.
+     *
+     * The document is typically created without fields and populated later
+     * during parsing. See the class-level docstring for why.
+     */
+    constructor(fields?: GqlDocumentFields);
+    /**
+     * Populates the document's fields after parsing.
+     */
+    set fields(fields: GqlDocumentFields);
+    /** Named-type registry. */
+    get registry(): GqlRegistry;
+    /** Root-field operations. */
+    get operations(): GqlOperation[];
+    /** Pointers to the schema's root operation types. */
+    get rootTypes(): GqlRootTypes;
+    /** Optional schema-level metadata. */
+    get info(): OasInfo | undefined;
+    /**
+     * Removes the consumer addressed by `stackTrail`. Parallel to
+     * {@link OasDocument.removeItem}; used by
+     * `ParseContext.removeErroredItems` to prune references whose target
+     * type failed to parse.
+     *
+     * Two consumer shapes are handled today:
+     *
+     * - `[<RootType>, <fieldName>, …]` where `<RootType>` matches one of
+     *   `rootTypes.{query,mutation,subscription}` → the matching
+     *   {@link GqlOperation} is removed from `operations`.
+     * - `[<ParentType>, <fieldName>, …]` where `<ParentType>` is a
+     *   registered object/input/interface → the named field is deleted
+     *   from the parent's properties (and from its `required` list if
+     *   present). The deeper segments of the stack trail are ignored,
+     *   matching `OasDocument.removeItem`'s coarse-grained behavior.
+     * - `[<UnionType>, members, <index>]` where `<UnionType>` is a
+     *   registered union or interface union → the indexed member is
+     *   removed.
+     *
+     * Returns the removed entity (`GqlOperation`, the removed property
+     * schema, or the removed union member) when removal happened, or
+     * `undefined` if no matching consumer was found. The return value
+     * acts as the truthy signal `removeErroredItems` uses to decide
+     * whether to emit an `INVALID_DEPENDENCY_REF` issue.
+     */
+    removeItem(stackTrail: StackTrail): unknown;
+}
+//# sourceMappingURL=GqlDocument.d.ts.map

package/script/gql/document/GqlDocument.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GqlDocument.d.ts","sourceRoot":"","sources":["../../../src/gql/document/GqlDocument.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAA;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAC/D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAA;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAA;AAI7D;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,8EAA8E;IAC9E,QAAQ,EAAE,WAAW,CAAA;IACrB,qEAAqE;IACrE,UAAU,EAAE,YAAY,EAAE,CAAA;IAC1B,yEAAyE;IACzE,SAAS,EAAE,YAAY,CAAA;IACvB,qEAAqE;IACrE,IAAI,CAAC,EAAE,OAAO,CAAA;CACf,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,WAAW;;IACtB,QAAQ,CAAC,OAAO,EAAG,aAAa,CAAS;IAKzC;;;;;OAKG;gBACS,MAAM,CAAC,EAAE,iBAAiB;IAItC;;OAEG;IACH,IAAI,MAAM,CAAC,MAAM,EAAE,iBAAiB,EAEnC;IAED,2BAA2B;IAC3B,IAAI,QAAQ,IAAI,WAAW,CAK1B;IAED,6BAA6B;IAC7B,IAAI,UAAU,IAAI,YAAY,EAAE,CAK/B;IAED,qDAAqD;IACrD,IAAI,SAAS,IAAI,YAAY,CAK5B;IAED,sCAAsC;IACtC,IAAI,IAAI,IAAI,OAAO,GAAG,SAAS,CAK9B;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,UAAU,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO;CAqD5C"}

package/script/gql/document/GqlDocument.js

@@ -0,0 +1,174 @@
+"use strict";
+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 _GqlDocument_fields;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GqlDocument = void 0;
+const Object_js_1 = require("../../oas/object/Object.js");
+const Union_js_1 = require("../../oas/union/Union.js");
+/**
+ * Top-level container for a parsed GraphQL schema.
+ *
+ * `GqlDocument` is the GraphQL counterpart to {@link OasDocument}. It owns
+ * a {@link GqlRegistry} (the named-type registry, parallel to
+ * `OasComponents.schemas`), the list of root-level fields exposed as
+ * {@link GqlOperation} entries, and pointers to the schema's root operation
+ * types.
+ *
+ * Both documents are wrapped by {@link SkmtcParsedDocument} so the pipeline
+ * can carry either through the same generate phase.
+ *
+ * ## Empty-at-construction
+ *
+ * Like {@link OasDocument}, `GqlDocument` is intentionally constructable
+ * without fields — the parser creates an empty instance up front, hands
+ * out `OasRef`s that resolve through it, then populates
+ * `gqlDocument.fields = { ... }` at the end of parsing. See the
+ * "forward-declared refs" section on {@link OasDocument} for the full
+ * rationale; the short version is that refs need a stable resolution
+ * target *before* every target has been parsed, so the document and the
+ * refs that point at it must both be constructable up front and tied to
+ * the same instance.
+ */
+class GqlDocument {
+    /**
+     * Creates a new GqlDocument instance.
+     *
+     * The document is typically created without fields and populated later
+     * during parsing. See the class-level docstring for why.
+     */
+    constructor(fields) {
+        Object.defineProperty(this, "oasType", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 'gqlDocument'
+        });
+        /** @internal Private fields storage — set after parsing. */
+        _GqlDocument_fields.set(this, void 0);
+        __classPrivateFieldSet(this, _GqlDocument_fields, fields, "f");
+    }
+    /**
+     * Populates the document's fields after parsing.
+     */
+    set fields(fields) {
+        __classPrivateFieldSet(this, _GqlDocument_fields, fields, "f");
+    }
+    /** Named-type registry. */
+    get registry() {
+        if (!__classPrivateFieldGet(this, _GqlDocument_fields, "f")) {
+            throw new Error(`Accessing 'registry' before fields are set`);
+        }
+        return __classPrivateFieldGet(this, _GqlDocument_fields, "f").registry;
+    }
+    /** Root-field operations. */
+    get operations() {
+        if (!__classPrivateFieldGet(this, _GqlDocument_fields, "f")) {
+            throw new Error(`Accessing 'operations' before fields are set`);
+        }
+        return __classPrivateFieldGet(this, _GqlDocument_fields, "f").operations;
+    }
+    /** Pointers to the schema's root operation types. */
+    get rootTypes() {
+        if (!__classPrivateFieldGet(this, _GqlDocument_fields, "f")) {
+            throw new Error(`Accessing 'rootTypes' before fields are set`);
+        }
+        return __classPrivateFieldGet(this, _GqlDocument_fields, "f").rootTypes;
+    }
+    /** Optional schema-level metadata. */
+    get info() {
+        if (!__classPrivateFieldGet(this, _GqlDocument_fields, "f")) {
+            throw new Error(`Accessing 'info' before fields are set`);
+        }
+        return __classPrivateFieldGet(this, _GqlDocument_fields, "f").info;
+    }
+    /**
+     * Removes the consumer addressed by `stackTrail`. Parallel to
+     * {@link OasDocument.removeItem}; used by
+     * `ParseContext.removeErroredItems` to prune references whose target
+     * type failed to parse.
+     *
+     * Two consumer shapes are handled today:
+     *
+     * - `[<RootType>, <fieldName>, …]` where `<RootType>` matches one of
+     *   `rootTypes.{query,mutation,subscription}` → the matching
+     *   {@link GqlOperation} is removed from `operations`.
+     * - `[<ParentType>, <fieldName>, …]` where `<ParentType>` is a
+     *   registered object/input/interface → the named field is deleted
+     *   from the parent's properties (and from its `required` list if
+     *   present). The deeper segments of the stack trail are ignored,
+     *   matching `OasDocument.removeItem`'s coarse-grained behavior.
+     * - `[<UnionType>, members, <index>]` where `<UnionType>` is a
+     *   registered union or interface union → the indexed member is
+     *   removed.
+     *
+     * Returns the removed entity (`GqlOperation`, the removed property
+     * schema, or the removed union member) when removal happened, or
+     * `undefined` if no matching consumer was found. The return value
+     * acts as the truthy signal `removeErroredItems` uses to decide
+     * whether to emit an `INVALID_DEPENDENCY_REF` issue.
+     */
+    removeItem(stackTrail) {
+        if (!__classPrivateFieldGet(this, _GqlDocument_fields, "f")) {
+            // Mirrors OasDocument's behavior: prune calls before fields are
+            // set are a no-op, matching the "empty-at-construction" contract.
+            return undefined;
+        }
+        const path = stackTrail.stackTrail;
+        if (path.length < 2)
+            return undefined;
+        const [first, second, third] = path;
+        if (typeof first !== 'string' || typeof second !== 'string')
+            return undefined;
+        const { registry, operations, rootTypes } = __classPrivateFieldGet(this, _GqlDocument_fields, "f");
+        // Case 1: root-field operation removal.
+        const isRootType = first === rootTypes.query || first === rootTypes.mutation || first === rootTypes.subscription;
+        if (isRootType) {
+            const index = operations.findIndex(op => op.fieldName === second);
+            if (index === -1)
+                return undefined;
+            const [removed] = operations.splice(index, 1);
+            return removed;
+        }
+        // Case 2: union or interface-union member removal at `[Type, members, index]`.
+        if (second === 'members' && typeof third === 'string') {
+            const parent = registry.schemas[first];
+            if (parent instanceof Union_js_1.OasUnion) {
+                const idx = Number.parseInt(third, 10);
+                if (!Number.isFinite(idx) || idx < 0 || idx >= parent.members.length)
+                    return undefined;
+                const [removed] = parent.members.splice(idx, 1);
+                return removed;
+            }
+            return undefined;
+        }
+        // Case 3: field-of-object removal at `[ParentType, fieldName]` (deeper
+        // segments ignored).
+        const parent = registry.schemas[first];
+        if (parent instanceof Object_js_1.OasObject) {
+            const properties = parent.properties;
+            if (!properties || !(second in properties))
+                return undefined;
+            const removed = properties[second];
+            delete properties[second];
+            if (parent.required) {
+                const i = parent.required.indexOf(second);
+                if (i !== -1)
+                    parent.required.splice(i, 1);
+            }
+            return removed;
+        }
+        return undefined;
+    }
+}
+exports.GqlDocument = GqlDocument;
+_GqlDocument_fields = new WeakMap();

package/script/gql/document/parseGqlDocument.d.ts

@@ -0,0 +1,33 @@
+import type { GqlDocumentFields } from './GqlDocument.js';
+import type { ParseContext, GqlParseOptions } from '../../context/ParseContext.js';
+import type { StackTrail } from '../../context/StackTrail.js';
+export type ParseGqlDocumentArgs = {
+    options: GqlParseOptions;
+    context: ParseContext;
+    /**
+     * Root stack trail to descend from. Each named type and root field
+     * is parsed inside `stackTrail.trace(<name>, ...)` so consumer
+     * stack trails (recorded via `context.registerRef`) line up with
+     * the addresses `removeErroredItems` uses to prune.
+     */
+    stackTrail: StackTrail;
+};
+/**
+ * Internal implementation behind `ParseContext.parse()` (GQL branch)
+ * and the convenience free function `toGqlDocument`.
+ *
+ * Returns the `GqlDocumentFields` ready to be assigned via
+ * `gqlDocument.fields = ...` onto the empty `GqlDocument` that
+ * `ParseContext` issued at construction time. This indirection exists
+ * so refs constructed during the walk hold a reference to the same
+ * `GqlDocument` instance that will eventually carry the fields — see
+ * the forward-declared-refs notes on `OasDocument` / `GqlDocument`.
+ *
+ * Reads `context.schema` and `context.registry` directly — both are
+ * populated by the `ParseContext` constructor, so this function does
+ * no setup.
+ */
+export declare const parseGqlDocument: ({ options, context, stackTrail }: ParseGqlDocumentArgs) => {
+    fields: GqlDocumentFields;
+};
+//# sourceMappingURL=parseGqlDocument.d.ts.map

package/script/gql/document/parseGqlDocument.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseGqlDocument.d.ts","sourceRoot":"","sources":["../../../src/gql/document/parseGqlDocument.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAazD,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAA;AAClF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAA;AAU7D,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,EAAE,eAAe,CAAA;IACxB,OAAO,EAAE,YAAY,CAAA;IACrB;;;;;OAKG;IACH,UAAU,EAAE,UAAU,CAAA;CACvB,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,GAAI,kCAI9B,oBAAoB,KAAG;IAAE,MAAM,EAAE,iBAAiB,CAAA;CA2GpD,CAAA"}

package/script/gql/document/parseGqlDocument.js

@@ -0,0 +1,189 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseGqlDocument = void 0;
+const graphql_1 = require("graphql");
+const toObjectType_js_1 = require("../object/toObjectType.js");
+const toInputType_js_1 = require("../input/toInputType.js");
+const toEnumType_js_1 = require("../enum/toEnumType.js");
+const toUnionType_js_1 = require("../union/toUnionType.js");
+const toInterfaceUnion_js_1 = require("../interface/toInterfaceUnion.js");
+const toScalarType_js_1 = require("../scalar/toScalarType.js");
+const toRootField_js_1 = require("../operation/toRootField.js");
+const tryParseAt_js_1 = require("../../context/tryParseAt.js");
+/**
+ * Built-in GraphQL directives that are part of every schema and not
+ * worth reporting as "skipped" — they always exist whether the user
+ * authored them or not.
+ */
+const BUILTIN_DIRECTIVES = new Set(['skip', 'include', 'deprecated', 'specifiedBy', 'oneOf']);
+/**
+ * Internal implementation behind `ParseContext.parse()` (GQL branch)
+ * and the convenience free function `toGqlDocument`.
+ *
+ * Returns the `GqlDocumentFields` ready to be assigned via
+ * `gqlDocument.fields = ...` onto the empty `GqlDocument` that
+ * `ParseContext` issued at construction time. This indirection exists
+ * so refs constructed during the walk hold a reference to the same
+ * `GqlDocument` instance that will eventually carry the fields — see
+ * the forward-declared-refs notes on `OasDocument` / `GqlDocument`.
+ *
+ * Reads `context.schema` and `context.registry` directly — both are
+ * populated by the `ParseContext` constructor, so this function does
+ * no setup.
+ */
+const parseGqlDocument = ({ options, context, stackTrail }) => {
+    const { interfaceUnionSuffix = 'Union', synthesizeInterfaceUnions = true } = options;
+    const { schema, registry } = context;
+    // Schema-level: warn about user-defined directive *definitions*.
+    // Applied directives on individual nodes are recorded by the
+    // per-type/per-field walks via `recordAppliedDirectives`. Schema-level
+    // directive definitions sit in a flat namespace with no tree
+    // position, so `log` (pre-computed location) is the clean shape
+    // here rather than threading a synthetic stack trail.
+    for (const directive of schema.getDirectives()) {
+        if (BUILTIN_DIRECTIVES.has(directive.name))
+            continue;
+        context.log({
+            level: 'warning',
+            location: `@${directive.name}`,
+            parent: directive,
+            message: `Custom directive '@${directive.name}' is not represented in generated output`,
+            type: 'DROPPED_DIRECTIVE'
+        });
+    }
+    // Pass 1: walk all named types and register them.
+    const typeMap = schema.getTypeMap();
+    for (const [name, type] of Object.entries(typeMap)) {
+        if ((0, graphql_1.isIntrospectionType)(type))
+            continue;
+        // Skip the root operation types if they're encountered here; we treat
+        // their fields as operations, not as object schema entries that need
+        // their own registry slot. Generators that want a "Query" type can
+        // look at the rootTypes pointers.
+        if (type === schema.getQueryType() ||
+            type === schema.getMutationType() ||
+            type === schema.getSubscriptionType()) {
+            continue;
+        }
+        addNamedType({
+            name,
+            type,
+            stackTrail,
+            context,
+            synthesizeInterfaceUnions,
+            interfaceUnionSuffix
+        });
+    }
+    // Pass 2: build operations from each root type's fields.
+    const operations = [];
+    const rootTypes = {};
+    const collectRootOps = (rootType, rootKind, assignRootType) => {
+        if (!rootType)
+            return;
+        assignRootType(rootType.name);
+        stackTrail.trace(rootType.name, rootStack => {
+            for (const field of Object.values(rootType.getFields())) {
+                const typedField = field;
+                // Qualified name (`Query.getUser`) so any cross-references to
+                // this operation can be pruned by `removeErroredItems` if its
+                // parse throws.
+                const operationName = `${rootType.name}.${typedField.name}`;
+                const operation = (0, tryParseAt_js_1.tryParseAt)({
+                    stackTrail: rootStack,
+                    key: typedField.name,
+                    context,
+                    type: 'INVALID_TYPE_DEFINITION',
+                    parent: typedField,
+                    refKey: operationName,
+                    fn: fieldStack => (0, toRootField_js_1.toRootField)({
+                        rootKind,
+                        // deno-lint-ignore no-explicit-any
+                        field: typedField,
+                        context,
+                        stackTrail: fieldStack
+                    })
+                });
+                if (operation !== undefined) {
+                    operations.push(operation);
+                }
+            }
+        });
+    };
+    collectRootOps(schema.getQueryType(), 'query', n => {
+        rootTypes.query = n;
+    });
+    collectRootOps(schema.getMutationType(), 'mutation', n => {
+        rootTypes.mutation = n;
+    });
+    collectRootOps(schema.getSubscriptionType(), 'subscription', n => {
+        rootTypes.subscription = n;
+    });
+    return {
+        fields: {
+            registry,
+            operations,
+            rootTypes
+        }
+    };
+};
+exports.parseGqlDocument = parseGqlDocument;
+/**
+ * Dispatch each named type to its protocol-specific parser, wrapping
+ * the call in `tryParseAt` so a single bad type doesn't abort the
+ * whole run. The helper handles the `stackTrail.trace(name, ...)`
+ * descent, the try/catch, and the error-issue logging in one shot —
+ * shared with the OAS-side `to<Kind>sV3` callers.
+ */
+const addNamedType = ({ name, type, stackTrail, context, synthesizeInterfaceUnions, interfaceUnionSuffix }) => {
+    const { registry } = context;
+    const tryAdd = (refName, builder) => {
+        // `refKey: name` (the type's own name, not `refName`) preserves the
+        // prior behavior where an interface-union failure marks the base
+        // type as errored so dependents of either form get pruned together.
+        const value = (0, tryParseAt_js_1.tryParseAt)({
+            stackTrail,
+            key: name,
+            context,
+            type: 'INVALID_TYPE_DEFINITION',
+            parent: type,
+            refKey: name,
+            fn: typeStack => builder(typeStack)
+        });
+        if (value !== undefined) {
+            registry.add(refName, value);
+        }
+    };
+    if ((0, graphql_1.isObjectType)(type)) {
+        tryAdd(name, typeStack => (0, toObjectType_js_1.toObjectType)({ objectType: type, context, stackTrail: typeStack }));
+    }
+    else if ((0, graphql_1.isInputObjectType)(type)) {
+        tryAdd(name, typeStack => (0, toInputType_js_1.toInputType)({ inputType: type, context, stackTrail: typeStack }));
+    }
+    else if ((0, graphql_1.isInterfaceType)(type)) {
+        // Base interface as an object (so generators can emit a TS interface).
+        tryAdd(name, typeStack => (0, toObjectType_js_1.toObjectType)({ objectType: type, context, stackTrail: typeStack }));
+        if (synthesizeInterfaceUnions) {
+            const unionName = `${name}${interfaceUnionSuffix}`;
+            tryAdd(unionName, typeStack => (0, toInterfaceUnion_js_1.toInterfaceUnion)({ interfaceType: type, context, stackTrail: typeStack }));
+        }
+    }
+    else if ((0, graphql_1.isUnionType)(type)) {
+        tryAdd(name, typeStack => (0, toUnionType_js_1.toUnionType)({ unionType: type, context, stackTrail: typeStack }));
+    }
+    else if ((0, graphql_1.isEnumType)(type)) {
+        tryAdd(name, typeStack => (0, toEnumType_js_1.toEnumType)({ enumType: type, context, stackTrail: typeStack }));
+    }
+    else if ((0, graphql_1.isScalarType)(type)) {
+        // Built-in scalars (Int, String, …) are inlined at usage sites and
+        // don't need registry entries; only register custom scalars so
+        // downstream generators can iterate them if needed.
+        const isBuiltin = type.name === 'Int' ||
+            type.name === 'Float' ||
+            type.name === 'String' ||
+            type.name === 'Boolean' ||
+            type.name === 'ID';
+        if (!isBuiltin) {
+            tryAdd(name, typeStack => (0, toScalarType_js_1.toScalarType)({ scalar: type, nullable: false, context, stackTrail: typeStack }));
+        }
+    }
+};

package/script/gql/enum/toEnumType.d.ts

@@ -0,0 +1,29 @@
+import type { GraphQLEnumType } from 'graphql';
+import { OasString } from '../../oas/string/String.js';
+import type { ParseContextType } from '../../context/parseTypes.js';
+import type { StackTrail } from '../../context/StackTrail.js';
+export type ToEnumTypeArgs = {
+    enumType: GraphQLEnumType;
+    /**
+     * Whether the enum appears in a nullable position. Defaults to
+     * `false` for top-level registry entries; usage sites set this based
+     * on how the enum was referenced.
+     */
+    nullable?: boolean;
+    context: ParseContextType;
+    stackTrail: StackTrail;
+};
+/**
+ * Maps a GraphQL enum to an `OasString` with the enum's values listed
+ * under `enums`.
+ *
+ * GraphQL enum values are always strings at the wire level, so this
+ * representation is precise. Downstream generators that prefer a TS
+ * literal union (`'ADMIN' | 'USER'`) or an `as const` object read this
+ * the same way they handle OAS string enums.
+ *
+ * `context` and `stackTrail` follow the OAS parser convention and are
+ * threaded for future diagnostic reporting; today the function is pure.
+ */
+export declare const toEnumType: ({ enumType, nullable, context, stackTrail }: ToEnumTypeArgs) => OasString;
+//# sourceMappingURL=toEnumType.d.ts.map

package/script/gql/enum/toEnumType.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toEnumType.d.ts","sourceRoot":"","sources":["../../../src/gql/enum/toEnumType.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAA;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAA;AACnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAA;AAE7D,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,EAAE,eAAe,CAAA;IACzB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,OAAO,EAAE,gBAAgB,CAAA;IACzB,UAAU,EAAE,UAAU,CAAA;CACvB,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,UAAU,GAAI,6CAKxB,cAAc,KAAG,SAanB,CAAA"}

package/script/gql/enum/toEnumType.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toEnumType = void 0;
+const String_js_1 = require("../../oas/string/String.js");
+/**
+ * Maps a GraphQL enum to an `OasString` with the enum's values listed
+ * under `enums`.
+ *
+ * GraphQL enum values are always strings at the wire level, so this
+ * representation is precise. Downstream generators that prefer a TS
+ * literal union (`'ADMIN' | 'USER'`) or an `as const` object read this
+ * the same way they handle OAS string enums.
+ *
+ * `context` and `stackTrail` follow the OAS parser convention and are
+ * threaded for future diagnostic reporting; today the function is pure.
+ */
+const toEnumType = ({ enumType, nullable = false, context, stackTrail }) => {
+    const values = enumType.getValues().map(v => v.value);
+    return context.withStackTrail(stackTrail, () => new String_js_1.OasString({
+        title: enumType.name,
+        description: enumType.description ?? undefined,
+        enums: values,
+        nullable
+    }, context));
+};
+exports.toEnumType = toEnumType;

package/script/gql/field/toFieldSchema.d.ts

@@ -0,0 +1,38 @@
+import type { GraphQLType } from 'graphql';
+import type { OasSchema } from '../../oas/schema/Schema.js';
+import type { OasRef } from '../../oas/ref/Ref.js';
+import type { ParseContextType } from '../../context/parseTypes.js';
+import type { StackTrail } from '../../context/StackTrail.js';
+/**
+ * Args for {@link toFieldSchema}.
+ *
+ * Mirrors the OAS parser convention `{ value, context, stackTrail }` —
+ * the stack trail represents the field's schema-level address (e.g.
+ * `User.posts`, `Query.getUser.return`). Issues recorded inside use
+ * `stackTrail.toString()` for the location string; ref consumers
+ * register via `context.registerRef(stackTrail, typeName)` so the
+ * cross-type invalidation pipeline can prune fields whose target type
+ * fails to parse.
+ */
+export type ToFieldSchemaArgs = {
+    type: GraphQLType;
+    context: ParseContextType;
+    stackTrail: StackTrail;
+};
+/**
+ * Converts a GraphQL field type into an `OasSchema | OasRef<'schema'>`
+ * suitable for use inside an `OasObject.properties` slot or as the
+ * `returnType` / argument type of a {@link GqlOperation}.
+ *
+ * Named composite types (objects, inputs, interfaces, unions) become
+ * refs into the registry so cross-type references resolve through the
+ * registry's internal mirror. Scalars and enums are emitted inline
+ * because they don't need to be referenced from anywhere else (their
+ * type info is fully self-contained).
+ *
+ * The function also encodes the GraphQL list-nullability matrix:
+ * `[T]`, `[T!]`, `[T]!`, `[T!]!` each produce different combinations of
+ * `OasArray.nullable` and the inner schema's nullability.
+ */
+export declare const toFieldSchema: ({ type, context, stackTrail }: ToFieldSchemaArgs) => OasSchema | OasRef<"schema">;
+//# sourceMappingURL=toFieldSchema.d.ts.map

package/script/gql/field/toFieldSchema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toFieldSchema.d.ts","sourceRoot":"","sources":["../../../src/gql/field/toFieldSchema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAU1C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAA;AAC3D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAA;AAOlD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAA;AACnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAA;AAE7D;;;;;;;;;;GAUG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,WAAW,CAAA;IACjB,OAAO,EAAE,gBAAgB,CAAA;IACzB,UAAU,EAAE,UAAU,CAAA;CACvB,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,aAAa,GAAI,+BAI3B,iBAAiB,KAAG,SAAS,GAAG,MAAM,CAAC,QAAQ,CA+EjD,CAAA"}