@skmtc/core 0.0.984 → 0.16.2

package/script/enrichments/toEnrichmentDescriptor.d.ts

@@ -0,0 +1,97 @@
+import * as v from 'valibot';
+/**
+ * Widget kind for one enrichment field — the rendered control in the
+ * enrichment-editor UI. Mirrors the `EnrichmentFieldKind` enum in the
+ * skmtc-hub TypeSpec contract.
+ */
+export type EnrichmentFieldKind = 'text' | 'textarea' | 'toggle' | 'select' | 'module' | 'accessorPath' | 'array' | 'object';
+/**
+ * One node of a serialised enrichment-schema descriptor — the
+ * form-renderable projection of a generator's enrichment schema.
+ */
+export type EnrichmentField = {
+    /** Key written into the enrichment values object. */
+    key: string;
+    /** Human label, derived from the key when no metadata is supplied. */
+    label: string;
+    description?: string;
+    /** Whether the schema marks this field optional. */
+    optional: boolean;
+    kind: EnrichmentFieldKind;
+    /** Choices for a `select` field. */
+    options?: string[];
+    /**
+     * For `kind: 'array'` — a one-element list describing the item shape.
+     * If the item is an object, the synthesised field carries the nested
+     * `fields`; if it is a primitive, the synthesised field carries the
+     * appropriate primitive kind. The single-element convention matches
+     * the contract's `EnrichmentField[]` shape.
+     */
+    item?: EnrichmentField[];
+    /** For `kind: 'object'` — the nested object's fields. */
+    fields?: EnrichmentField[];
+};
+/** What a generator targets — operations or models. */
+export type TargetKind = 'operation' | 'model';
+/**
+ * A generator's enrichment schema, projected for the CMS. The same
+ * descriptor is what an agent would drive — the form UI is one
+ * renderer of it.
+ */
+export type EnrichmentDescriptor = {
+    generator: string;
+    appliesTo: TargetKind;
+    fields: EnrichmentField[];
+};
+/**
+ * Structural view of the data the walker needs from a generator entry.
+ * Every entry returned by `toOasOperationEntry`, `toGqlOperationEntry`,
+ * and `toModelEntry` satisfies this shape — the walker stays decoupled
+ * from `GeneratorConfig` so callers can pass any entry-like object
+ * (e.g. tests or programmatically authored generators).
+ */
+export type EnrichmentSource = {
+    readonly id: string;
+    readonly type: 'oasOperation' | 'gqlOperation' | 'model' | 'webhook';
+    readonly toEnrichmentSchema?: () => v.GenericSchema;
+};
+/**
+ * Walk a Valibot object schema and return the projected list of
+ * `EnrichmentField`s. A `v.optional(v.object({...}))` outer wrapper is
+ * silently unwrapped; any non-object root yields an empty list; members that
+ * unwrap to `v.undefined()` are omitted (see {@link isOmittedMember}).
+ *
+ * For a generator entry the schema is the three-scope **umbrella** composite
+ * `v.object({ subject, generator, stack })` that `toEnrichmentSchema` returns,
+ * so the top-level fields are the three scopes — each an `object` field whose
+ * nested `fields` are that scope's own leaf. The walk discovers the scopes
+ * structurally; it never names `subject` / `generator` / `stack`. A scope
+ * declared `v.undefined()` (the no-enrichment marker) drops out, so a
+ * subject-only generator yields just the `subject` scope and a fully empty
+ * umbrella yields `[]`.
+ *
+ * Generally callers should prefer {@link toEnrichmentDescriptor}, which
+ * takes a generator entry and fills in `generator` / `appliesTo`
+ * automatically. This lower-level entry point is useful in tests and
+ * when only the field shape is needed.
+ */
+export declare const toEnrichmentFields: (schema: v.GenericSchema | undefined) => EnrichmentField[];
+/**
+ * Project a generator entry's enrichment schema into a serialisable
+ * `EnrichmentDescriptor` the CMS can render as a form. The entry's
+ * `id` becomes `descriptor.generator`; its `type` discriminator maps
+ * to `appliesTo` (`'oasOperation' | 'gqlOperation'` → `'operation'`;
+ * `'model'` → `'model'`). If the entry has no `toEnrichmentSchema`, or
+ * declares the empty umbrella, the descriptor has an empty `fields`
+ * array — the UI hides the section, matching the engine's "no
+ * enrichments" behaviour.
+ *
+ * `toEnrichmentSchema` returns the three-scope umbrella composite
+ * `v.object({ subject, generator, stack })`, so the descriptor's
+ * top-level `fields` are the three scopes — each an `object` field whose
+ * nested `fields` are that scope's own leaf (absent scopes drop out). The
+ * `subject` scope describes one *variant*'s leaf shape; variant selection
+ * sits above it in the editor UI, since the variant axis is core-owned.
+ */
+export declare const toEnrichmentDescriptor: (entry: EnrichmentSource) => EnrichmentDescriptor;
+//# sourceMappingURL=toEnrichmentDescriptor.d.ts.map

package/script/enrichments/toEnrichmentDescriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toEnrichmentDescriptor.d.ts","sourceRoot":"","sources":["../../src/enrichments/toEnrichmentDescriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAI5B;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAC3B,MAAM,GACN,UAAU,GACV,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,cAAc,GACd,OAAO,GACP,QAAQ,CAAA;AAEZ;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAA;IACX,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,oDAAoD;IACpD,QAAQ,EAAE,OAAO,CAAA;IACjB,IAAI,EAAE,mBAAmB,CAAA;IACzB,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,eAAe,EAAE,CAAA;IACxB,yDAAyD;IACzD,MAAM,CAAC,EAAE,eAAe,EAAE,CAAA;CAC3B,CAAA;AAED,uDAAuD;AACvD,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,OAAO,CAAA;AAE9C;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,UAAU,CAAA;IACrB,MAAM,EAAE,eAAe,EAAE,CAAA;CAC1B,CAAA;AAED;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,cAAc,GAAG,OAAO,GAAG,SAAS,CAAA;IACpE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC,CAAC,aAAa,CAAA;CACpD,CAAA;AAwHD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,CAAC,CAAC,aAAa,GAAG,SAAS,KAAG,eAAe,EAKvF,CAAA;AAwBD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,sBAAsB,GAAI,OAAO,gBAAgB,KAAG,oBAI/D,CAAA"}

package/script/enrichments/toEnrichmentDescriptor.js

@@ -0,0 +1,162 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toEnrichmentDescriptor = exports.toEnrichmentFields = void 0;
+const ModuleExport_js_1 = require("../types/ModuleExport.js");
+const AccessorPath_js_1 = require("../types/AccessorPath.js");
+const isValibotSchema = (input) => typeof input === 'object' &&
+    input !== null &&
+    'type' in input &&
+    typeof input.type === 'string';
+const isEntriesRecord = (input) => typeof input === 'object' && input !== null;
+const isOptionsArray = (input) => Array.isArray(input);
+const WRAPPER_TYPES = new Set(['optional', 'nullable', 'nullish']);
+const unwrap = (schema) => {
+    if (WRAPPER_TYPES.has(schema.type) && isValibotSchema(schema.wrapped)) {
+        return { inner: schema.wrapped, optional: true };
+    }
+    return { inner: schema, optional: false };
+};
+/**
+ * Whether an object member should be omitted from the descriptor. A member
+ * that unwraps to `v.undefined()` carries no payload — it is the canonical
+ * "this scope is absent" marker (e.g. the `v.undefined()` members of
+ * `emptyEnrichmentSchema`). Omitting it keeps a no-enrichment generator's
+ * descriptor empty (the editor hides the section) and lets a partially
+ * populated umbrella surface only the scopes that actually carry fields. The
+ * rule is structural — it names no scope, so it composes with the generic
+ * object walk rather than special-casing `subject` / `generator` / `stack`.
+ */
+const isOmittedMember = (rawSchema) => isValibotSchema(rawSchema) && unwrap(rawSchema).inner.type === 'undefined';
+const toLabel = (key) => {
+    if (key === '')
+        return '';
+    const spaced = key.replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/[_-]+/g, ' ');
+    return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+};
+const kindFor = (schema) => {
+    if (isValibotSchema(ModuleExport_js_1.moduleExport) && schema === ModuleExport_js_1.moduleExport) {
+        return { kind: 'module' };
+    }
+    if (isValibotSchema(AccessorPath_js_1.accessorPath) && schema === AccessorPath_js_1.accessorPath) {
+        return { kind: 'accessorPath' };
+    }
+    switch (schema.type) {
+        case 'string':
+            return { kind: 'text' };
+        case 'boolean':
+            return { kind: 'toggle' };
+        case 'number':
+            return { kind: 'text' };
+        case 'picklist': {
+            const opts = isOptionsArray(schema.options) ? schema.options.map(o => String(o)) : [];
+            return { kind: 'select', options: opts };
+        }
+        case 'object': {
+            const entries = isEntriesRecord(schema.entries) ? schema.entries : {};
+            return {
+                kind: 'object',
+                fields: walkEntries(entries)
+            };
+        }
+        case 'array': {
+            if (isValibotSchema(schema.item)) {
+                return { kind: 'array', item: [walkFromShape('', schema.item)] };
+            }
+            return { kind: 'array', item: [] };
+        }
+        default:
+            return { kind: 'text' };
+    }
+};
+const walkFromShape = (key, rawSchema) => {
+    const { inner, optional } = unwrap(rawSchema);
+    return { key, label: toLabel(key), optional, ...kindFor(inner) };
+};
+const walkField = (key, rawSchema) => {
+    if (!isValibotSchema(rawSchema)) {
+        return { key, label: toLabel(key), optional: false, kind: 'text' };
+    }
+    return walkFromShape(key, rawSchema);
+};
+/**
+ * Walk an object schema's `entries` into descriptor fields, omitting members
+ * that carry no payload (see {@link isOmittedMember}). The single iteration
+ * point shared by the top-level walk ({@link toEnrichmentFields}) and the
+ * nested-object case in {@link kindFor}.
+ */
+const walkEntries = (entries) => Object.keys(entries)
+    .filter(key => !isOmittedMember(entries[key]))
+    .map(key => walkField(key, entries[key]));
+/**
+ * Walk a Valibot object schema and return the projected list of
+ * `EnrichmentField`s. A `v.optional(v.object({...}))` outer wrapper is
+ * silently unwrapped; any non-object root yields an empty list; members that
+ * unwrap to `v.undefined()` are omitted (see {@link isOmittedMember}).
+ *
+ * For a generator entry the schema is the three-scope **umbrella** composite
+ * `v.object({ subject, generator, stack })` that `toEnrichmentSchema` returns,
+ * so the top-level fields are the three scopes — each an `object` field whose
+ * nested `fields` are that scope's own leaf. The walk discovers the scopes
+ * structurally; it never names `subject` / `generator` / `stack`. A scope
+ * declared `v.undefined()` (the no-enrichment marker) drops out, so a
+ * subject-only generator yields just the `subject` scope and a fully empty
+ * umbrella yields `[]`.
+ *
+ * Generally callers should prefer {@link toEnrichmentDescriptor}, which
+ * takes a generator entry and fills in `generator` / `appliesTo`
+ * automatically. This lower-level entry point is useful in tests and
+ * when only the field shape is needed.
+ */
+const toEnrichmentFields = (schema) => {
+    if (!isValibotSchema(schema))
+        return [];
+    const { inner } = unwrap(schema);
+    if (inner.type !== 'object' || !isEntriesRecord(inner.entries))
+        return [];
+    return walkEntries(inner.entries);
+};
+exports.toEnrichmentFields = toEnrichmentFields;
+const toAppliesTo = (entryType) => {
+    switch (entryType) {
+        case 'model':
+            return 'model';
+        case 'oasOperation':
+        case 'gqlOperation':
+            return 'operation';
+        // STOPGAP: a webhook is operation-shaped (method + responses), so its
+        // enrichment editor reuses the 'operation' context for now. A dedicated
+        // 'webhook' TargetKind would be more truthful but ripples into the
+        // skmtc-hub TypeSpec contract that TargetKind/appliesTo mirror — deferred
+        // to a coordinated change. (Was an uncovered gap: WebhookConfig joined the
+        // GeneratorConfig union without a toAppliesTo arm.)
+        case 'webhook':
+            return 'operation';
+        default: {
+            const _exhaustive = entryType;
+            throw new Error(`Unhandled generator entry type: ${String(_exhaustive)}`);
+        }
+    }
+};
+/**
+ * Project a generator entry's enrichment schema into a serialisable
+ * `EnrichmentDescriptor` the CMS can render as a form. The entry's
+ * `id` becomes `descriptor.generator`; its `type` discriminator maps
+ * to `appliesTo` (`'oasOperation' | 'gqlOperation'` → `'operation'`;
+ * `'model'` → `'model'`). If the entry has no `toEnrichmentSchema`, or
+ * declares the empty umbrella, the descriptor has an empty `fields`
+ * array — the UI hides the section, matching the engine's "no
+ * enrichments" behaviour.
+ *
+ * `toEnrichmentSchema` returns the three-scope umbrella composite
+ * `v.object({ subject, generator, stack })`, so the descriptor's
+ * top-level `fields` are the three scopes — each an `object` field whose
+ * nested `fields` are that scope's own leaf (absent scopes drop out). The
+ * `subject` scope describes one *variant*'s leaf shape; variant selection
+ * sits above it in the editor UI, since the variant axis is core-owned.
+ */
+const toEnrichmentDescriptor = (entry) => ({
+    generator: entry.id,
+    appliesTo: toAppliesTo(entry.type),
+    fields: (0, exports.toEnrichmentFields)(entry.toEnrichmentSchema?.())
+});
+exports.toEnrichmentDescriptor = toEnrichmentDescriptor;

package/script/gql/_helpers/recordAppliedDirectives.d.ts

@@ -0,0 +1,25 @@
+import type { ASTNode, DirectiveNode } from 'graphql';
+import type { ParseContextType } from '../../context/parseTypes.js';
+import type { StackTrail } from '../../context/StackTrail.js';
+export type RecordAppliedDirectivesArgs = {
+    astNode: {
+        directives?: ReadonlyArray<DirectiveNode>;
+    } | ASTNode | undefined | null;
+    stackTrail: StackTrail;
+    context: ParseContextType;
+};
+/**
+ * Reads the `directives` array off any `astNode` and records each
+ * non-suppressed directive as a `DROPPED_DIRECTIVE` warning on the
+ * given context.
+ *
+ * Use this on object/input/interface/union types and their fields so
+ * the user sees a precise location (e.g. `User.secret`) for any
+ * applied directive the schema-driven pipeline can't represent.
+ *
+ * Works defensively: nodes from a `GraphQLSchema` built via
+ * `buildSchema` always have ASTs, but the type allows `undefined` for
+ * pure-runtime constructions, so we guard.
+ */
+export declare const recordAppliedDirectives: ({ astNode, stackTrail, context }: RecordAppliedDirectivesArgs) => void;
+//# sourceMappingURL=recordAppliedDirectives.d.ts.map

package/script/gql/_helpers/recordAppliedDirectives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recordAppliedDirectives.d.ts","sourceRoot":"","sources":["../../../src/gql/_helpers/recordAppliedDirectives.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAA;AACnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAA;AAU7D,MAAM,MAAM,2BAA2B,GAAG;IACxC,OAAO,EAAE;QAAE,UAAU,CAAC,EAAE,aAAa,CAAC,aAAa,CAAC,CAAA;KAAE,GAAG,OAAO,GAAG,SAAS,GAAG,IAAI,CAAA;IACnF,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,gBAAgB,CAAA;CAC1B,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,uBAAuB,GAAI,kCAIrC,2BAA2B,KAAG,IAehC,CAAA"}

package/script/gql/_helpers/recordAppliedDirectives.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordAppliedDirectives = void 0;
+/**
+ * Names of directives we don't bother reporting as dropped, either
+ * because they're built-ins handled at the schema level or because we
+ * already capture their semantics elsewhere (`@deprecated`'s reason
+ * lifts onto the entity's `deprecationReason` field).
+ */
+const SUPPRESSED_DIRECTIVES = new Set(['skip', 'include', 'deprecated', 'specifiedBy', 'oneOf']);
+/**
+ * Reads the `directives` array off any `astNode` and records each
+ * non-suppressed directive as a `DROPPED_DIRECTIVE` warning on the
+ * given context.
+ *
+ * Use this on object/input/interface/union types and their fields so
+ * the user sees a precise location (e.g. `User.secret`) for any
+ * applied directive the schema-driven pipeline can't represent.
+ *
+ * Works defensively: nodes from a `GraphQLSchema` built via
+ * `buildSchema` always have ASTs, but the type allows `undefined` for
+ * pure-runtime constructions, so we guard.
+ */
+const recordAppliedDirectives = ({ astNode, stackTrail, context }) => {
+    const directives = astNode && 'directives' in astNode ? astNode.directives : undefined;
+    if (!directives || directives.length === 0)
+        return;
+    for (const directive of directives) {
+        const name = directive.name.value;
+        if (SUPPRESSED_DIRECTIVES.has(name))
+            continue;
+        context.logIssueNoKey({
+            level: 'warning',
+            stackTrail,
+            parent: astNode,
+            message: `Applied directive '@${name}' is not represented in generated output`,
+            type: 'DROPPED_DIRECTIVE'
+        });
+    }
+};
+exports.recordAppliedDirectives = recordAppliedDirectives;

package/script/gql/_helpers/unwrapType.d.ts

@@ -0,0 +1,39 @@
+import { type GraphQLType, type GraphQLNamedType } from 'graphql';
+/**
+ * Result of unwrapping a possibly list/non-null wrapped GraphQL type.
+ *
+ * GraphQL field types are stacked from named-type inwards:
+ * - `T`     → outerNullable=true
+ * - `T!`    → outerNullable=false
+ * - `[T]`   → list=true, outerNullable=true,  itemNullable=true
+ * - `[T!]`  → list=true, outerNullable=true,  itemNullable=false
+ * - `[T]!`  → list=true, outerNullable=false, itemNullable=true
+ * - `[T!]!` → list=true, outerNullable=false, itemNullable=false
+ *
+ * The four-cell list-nullability matrix is captured precisely. Nested
+ * lists (`[[T!]!]!`) are not currently representable as a single
+ * `OasArray` of items — the unwrapper detects them and signals via
+ * `nestedList=true` so the caller can fall back to a more permissive
+ * representation.
+ */
+export type UnwrappedType = {
+    /** The innermost named GraphQL type (object, scalar, enum, etc.). */
+    named: GraphQLNamedType;
+    /** True if the type is wrapped in a list (one level). */
+    isList: boolean;
+    /** Whether the (single) list itself can be null. */
+    outerNullable: boolean;
+    /** Whether items inside the list can be null. Meaningless if `isList=false`. */
+    itemNullable: boolean;
+    /** Set if more than one list wrapper was encountered. */
+    nestedList: boolean;
+};
+/**
+ * Strips list and non-null wrappers from a GraphQL type, returning the
+ * innermost named type and a structural description of its modifiers.
+ *
+ * GraphQL wrapping types are always shaped `(NonNull? List? NonNull? Named)`,
+ * peeled outermost first. This walks the chain and records the bookkeeping.
+ */
+export declare const unwrapType: (type: GraphQLType) => UnwrappedType;
+//# sourceMappingURL=unwrapType.d.ts.map

package/script/gql/_helpers/unwrapType.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unwrapType.d.ts","sourceRoot":"","sources":["../../../src/gql/_helpers/unwrapType.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,gBAAgB,EAGtB,MAAM,SAAS,CAAA;AAEhB;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,qEAAqE;IACrE,KAAK,EAAE,gBAAgB,CAAA;IACvB,yDAAyD;IACzD,MAAM,EAAE,OAAO,CAAA;IACf,oDAAoD;IACpD,aAAa,EAAE,OAAO,CAAA;IACtB,gFAAgF;IAChF,YAAY,EAAE,OAAO,CAAA;IACrB,yDAAyD;IACzD,UAAU,EAAE,OAAO,CAAA;CACpB,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,GAAI,MAAM,WAAW,KAAG,aA2C9C,CAAA"}

package/script/gql/_helpers/unwrapType.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unwrapType = void 0;
+const graphql_1 = require("graphql");
+/**
+ * Strips list and non-null wrappers from a GraphQL type, returning the
+ * innermost named type and a structural description of its modifiers.
+ *
+ * GraphQL wrapping types are always shaped `(NonNull? List? NonNull? Named)`,
+ * peeled outermost first. This walks the chain and records the bookkeeping.
+ */
+const unwrapType = (type) => {
+    let outerNullable = true;
+    let isList = false;
+    let itemNullable = true;
+    let nestedList = false;
+    let current = type;
+    // Outer non-null
+    if ((0, graphql_1.isNonNullType)(current)) {
+        outerNullable = false;
+        current = current.ofType;
+    }
+    // List
+    if ((0, graphql_1.isListType)(current)) {
+        isList = true;
+        current = current.ofType;
+        // Item non-null
+        if ((0, graphql_1.isNonNullType)(current)) {
+            itemNullable = false;
+            current = current.ofType;
+        }
+        // Detect nested lists
+        if ((0, graphql_1.isListType)(current) || ((0, graphql_1.isNonNullType)(current) && (0, graphql_1.isListType)(current.ofType))) {
+            nestedList = true;
+            // Walk to the eventual named type
+            let walker = current;
+            while ((0, graphql_1.isListType)(walker) || (0, graphql_1.isNonNullType)(walker)) {
+                walker = walker.ofType;
+            }
+            current = walker;
+        }
+    }
+    return {
+        named: current,
+        isList,
+        outerNullable,
+        itemNullable,
+        nestedList
+    };
+};
+exports.unwrapType = unwrapType;

package/script/gql/argument/GqlArgument.d.ts

@@ -0,0 +1,55 @@
+import type { OasSchema } from '../../oas/schema/Schema.js';
+import type { OasRef } from '../../oas/ref/Ref.js';
+import { OasBase } from '../../types/OasBase.js';
+import type { ParseContextType } from '../../context/parseTypes.js';
+/**
+ * Fields used to construct a {@link GqlArgument}.
+ */
+export type GqlArgumentFields = {
+    name: string;
+    schema: OasSchema | OasRef<'schema'>;
+    required: boolean;
+    /**
+     * The original GraphQL type string for this argument (e.g. `'ID!'`,
+     * `'CreatePostInput!'`, `'[String!]'`). Captured at parse time so
+     * generators that need to reconstruct an SDL fragment — like
+     * `gen-graphql-typed-document-node` building a `gql\`...\`` template
+     * — don't have to reverse-engineer it from the OAS form.
+     *
+     * Optional at construction so test fixtures don't have to fabricate
+     * one; falls back to `''` when omitted.
+     */
+    gqlType?: string;
+    defaultValue?: unknown;
+    description?: string;
+    deprecated?: boolean;
+    deprecationReason?: string;
+};
+/**
+ * A single argument on a GraphQL field.
+ *
+ * Intentionally slimmer than `OasParameter`: GraphQL field arguments are
+ * just `(name, type, default, description)` plus a required flag. None of
+ * the OpenAPI HTTP encoding state (`location`, `style`, `explode`,
+ * `allowReserved`, content-by-mediaType) applies, so we keep this class
+ * focused.
+ *
+ * The `required` flag corresponds directly to the GraphQL non-null
+ * indicator on the argument's type. A `defaultValue` makes an otherwise
+ * required argument effectively optional from the caller's perspective —
+ * but we surface both fields as the schema declared them and let
+ * downstream generators decide what to do with the combination.
+ */
+export declare class GqlArgument extends OasBase {
+    readonly oasType: "gqlArgument";
+    readonly name: string;
+    readonly schema: OasSchema | OasRef<'schema'>;
+    readonly required: boolean;
+    readonly gqlType: string;
+    readonly defaultValue: unknown;
+    readonly description: string | undefined;
+    readonly deprecated: boolean;
+    readonly deprecationReason: string | undefined;
+    constructor(fields: GqlArgumentFields, context?: ParseContextType);
+}
+//# sourceMappingURL=GqlArgument.d.ts.map

package/script/gql/argument/GqlArgument.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GqlArgument.d.ts","sourceRoot":"","sources":["../../../src/gql/argument/GqlArgument.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAA;AAC3D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAA;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAA;AAChD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAA;AAEnE;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAA;IACpC,QAAQ,EAAE,OAAO,CAAA;IACjB;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC3B,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,WAAY,SAAQ,OAAO;IACtC,QAAQ,CAAC,OAAO,EAAG,aAAa,CAAS;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAA;IAC7C,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IACxC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,SAAS,CAAA;gBAElC,MAAM,EAAE,iBAAiB,EAAE,OAAO,CAAC,EAAE,gBAAgB;CAWlE"}

package/script/gql/argument/GqlArgument.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GqlArgument = void 0;
+const OasBase_js_1 = require("../../types/OasBase.js");
+/**
+ * A single argument on a GraphQL field.
+ *
+ * Intentionally slimmer than `OasParameter`: GraphQL field arguments are
+ * just `(name, type, default, description)` plus a required flag. None of
+ * the OpenAPI HTTP encoding state (`location`, `style`, `explode`,
+ * `allowReserved`, content-by-mediaType) applies, so we keep this class
+ * focused.
+ *
+ * The `required` flag corresponds directly to the GraphQL non-null
+ * indicator on the argument's type. A `defaultValue` makes an otherwise
+ * required argument effectively optional from the caller's perspective —
+ * but we surface both fields as the schema declared them and let
+ * downstream generators decide what to do with the combination.
+ */
+class GqlArgument extends OasBase_js_1.OasBase {
+    constructor(fields, context) {
+        super(context);
+        Object.defineProperty(this, "oasType", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 'gqlArgument'
+        });
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "schema", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "required", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "gqlType", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "defaultValue", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "description", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "deprecated", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "deprecationReason", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.name = fields.name;
+        this.schema = fields.schema;
+        this.required = fields.required;
+        this.gqlType = fields.gqlType ?? '';
+        this.defaultValue = fields.defaultValue;
+        this.description = fields.description;
+        this.deprecated = fields.deprecated ?? false;
+        this.deprecationReason = fields.deprecationReason;
+    }
+}
+exports.GqlArgument = GqlArgument;