@powerhousedao/builder-tools 5.1.0-dev.4 → 5.1.0-dev.40

package/dist/document-model-editor/utils/helpers.js

@@ -1,6 +1,7 @@
 import { getPHCustomScalarByTypeName } from "@powerhousedao/document-engineering/graphql";
 import { pascalCase } from "change-case";
-import { Kind, print, visit } from "graphql";
+import { getVariableValues, GraphQLError, GraphQLInputObjectType, GraphQLList, GraphQLNonNull, isEnumType, isListType, isNonNullType, isObjectType, isScalarType, Kind, parse, print, visit, } from "graphql";
+import { buildASTSchema, getOperationAST } from "graphql/utilities";
 import { z } from "zod";
 import { BOOLEAN_GQL_PRIMITIVE_NAME, FLOAT_GQL_PRIMITIVE_NAME, gqlPrimitiveNodeNamesList, ID_GQL_PRIMITIVE_NAME, INT_GQL_PRIMITIVE_NAME, STRING_GQL_PRIMITIVE_NAME, } from "../constants/graphql-kinds.js";
 import { safeParseSdl } from "../context/schema-context.js";
@@ -27,6 +28,17 @@ export function makeOperationInitialDoc(name) {
 }`;
     return inputSdl;
 }
+export function makeEmptyOperationSchema(operationName) {
+    const pascalName = pascalCase(operationName);
+    return `input ${pascalName}Input {\n  _empty: Boolean\n}`;
+}
+export function isEmptyOperationSchema(schema) {
+    if (!schema)
+        return false;
+    // Check if schema only contains _empty: Boolean field
+    return (/_empty:\s*Boolean/.test(schema) &&
+        !schema.replace(/_empty:\s*Boolean/, "").match(/\w+:\s*\w+/));
+}
 export function safeParseJsonRecord(json) {
     try {
         return JSON.parse(json);
@@ -45,15 +57,18 @@ export function makeMinimalObjectForStateType(args) {
     if (!stateTypeDefinitionFields?.length) {
         return existingValue;
     }
+    // Initialize visitedTypes with the root type to detect self-recursive types
+    const visitedTypes = new Set([stateTypeDefinitionNode.name.value]);
     const minimalObject = makeMinimalValuesForObjectFields({
         schemaDocumentNode: sharedSchemaDocumentNode,
         fieldDefinitionNodes: stateTypeDefinitionFields,
         existingValueObject,
+        visitedTypes,
     });
     return JSON.stringify(minimalObject, null, 2);
 }
 export function makeMinimalValuesForObjectFields(args) {
-    const { schemaDocumentNode, existingValueObject, fieldDefinitionNodes } = args;
+    const { schemaDocumentNode, existingValueObject, fieldDefinitionNodes, visitedTypes, } = args;
     const newJson = {};
     for (const astNode of fieldDefinitionNodes) {
         const fieldName = getASTNodeName(astNode);
@@ -65,13 +80,14 @@ export function makeMinimalValuesForObjectFields(args) {
             astNode,
             schemaDocumentNode,
             existingValueObject,
+            visitedTypes,
         });
         newJson[astNode.name.value] = minimalValue;
     }
     return newJson;
 }
 function makeMinimalValueForASTNode(args) {
-    const { fieldName, astNode, schemaDocumentNode, existingValueObject } = args;
+    const { fieldName, astNode, schemaDocumentNode, existingValueObject, visitedTypes, } = args;
     const existingFieldValue = existingValueObject?.[fieldName];
     let node = astNode;
     if (isFieldDefinitionNode(astNode)) {
@@ -82,7 +98,7 @@ function makeMinimalValueForASTNode(args) {
         node = getASTNodeTypeNode(node);
     }
     if (isListTypeNode(node)) {
-        return makeMinimalValueForGqlListNode(node, existingFieldValue, isNonNull);
+        return makeMinimalValueForGqlListNode(node, existingFieldValue, isNonNull, schemaDocumentNode, visitedTypes);
     }
     if (isGqlPrimitiveNode(node)) {
         return makeMinimalValueForGQLPrimitiveNode(node, existingFieldValue, isNonNull);
@@ -95,10 +111,10 @@ function makeMinimalValueForASTNode(args) {
         return makeMinimalValueForGqlScalar(namedTypeDefinitionNode, existingFieldValue, isNonNull);
     }
     if (isUnionTypeDefinitionNode(namedTypeDefinitionNode)) {
-        return makeMinimalValueForGqlUnion(namedTypeDefinitionNode, existingFieldValue, schemaDocumentNode, existingValueObject, isNonNull);
+        return makeMinimalValueForGqlUnion(namedTypeDefinitionNode, existingFieldValue, schemaDocumentNode, existingValueObject, isNonNull, visitedTypes);
     }
     if (isObjectTypeDefinitionNode(namedTypeDefinitionNode)) {
-        return makeMinimalValueForGqlObject(namedTypeDefinitionNode, schemaDocumentNode, existingValueObject, existingFieldValue, isNonNull);
+        return makeMinimalValueForGqlObject(namedTypeDefinitionNode, schemaDocumentNode, existingValueObject, existingFieldValue, isNonNull, visitedTypes);
     }
     return existingFieldValue;
 }
@@ -243,7 +259,7 @@ function makeMinimalValueForGqlScalar(scalarTypeDefinitionNode, existingFieldVal
     }
     return existingFieldValue;
 }
-function makeMinimalValueForGqlUnion(namedTypeDefinitionNode, existingFieldValue, schemaDocumentNode, existingValueObject, isNonNull) {
+function makeMinimalValueForGqlUnion(namedTypeDefinitionNode, existingFieldValue, schemaDocumentNode, existingValueObject, isNonNull, visitedTypes) {
     if (!isNonNull && !existingFieldValue) {
         return null;
     }
@@ -259,18 +275,31 @@ function makeMinimalValueForGqlUnion(namedTypeDefinitionNode, existingFieldValue
     if (!isObjectTypeDefinitionNode(firstNamedTypeObjectDefinitionNode)) {
         return null;
     }
-    return makeMinimalValueForGqlObject(firstNamedTypeObjectDefinitionNode, schemaDocumentNode, existingValueObject, existingFieldValue, isNonNull);
+    return makeMinimalValueForGqlObject(firstNamedTypeObjectDefinitionNode, schemaDocumentNode, existingValueObject, existingFieldValue, isNonNull, visitedTypes);
 }
-function makeMinimalValueForGqlListNode(listTypeNode, existingFieldValue, isNonNull) {
+function makeMinimalValueForGqlListNode(listTypeNode, existingFieldValue, isNonNull, schemaDocumentNode, visitedTypes) {
     if (!isNonNull && !Array.isArray(existingFieldValue)) {
         return null;
     }
     if (isNonNull && !Array.isArray(existingFieldValue)) {
         return [];
     }
-    return existingFieldValue;
+    // Process each array item recursively
+    const arrayValue = existingFieldValue;
+    return arrayValue.map((item, index) => makeMinimalValueForASTNode({
+        fieldName: String(index),
+        astNode: listTypeNode.type,
+        schemaDocumentNode,
+        existingValueObject: { [index]: item },
+        visitedTypes,
+    }));
 }
-function makeMinimalValueForGqlObject(objectTypeDefinitionNode, schemaDocumentNode, existingValueObject, existingFieldValue, isNonNull) {
+function makeMinimalValueForGqlObject(objectTypeDefinitionNode, schemaDocumentNode, _existingValueObject, existingFieldValue, isNonNull, visitedTypes) {
+    const typeName = objectTypeDefinitionNode.name.value;
+    // Check for recursive types to prevent infinite recursion
+    if (visitedTypes?.has(typeName)) {
+        return null;
+    }
     if (!isNonNull && !existingFieldValue) {
         return null;
     }
@@ -278,10 +307,20 @@ function makeMinimalValueForGqlObject(objectTypeDefinitionNode, schemaDocumentNo
     if (!fields?.length) {
         return {};
     }
+    // Track this type to detect cycles
+    const newVisitedTypes = new Set(visitedTypes);
+    newVisitedTypes.add(typeName);
+    // Use existingFieldValue (the actual nested object) instead of existingValueObject (parent)
+    const nestedExistingValue = existingFieldValue &&
+        typeof existingFieldValue === "object" &&
+        !Array.isArray(existingFieldValue)
+        ? existingFieldValue
+        : null;
     return makeMinimalValuesForObjectFields({
         schemaDocumentNode,
-        existingValueObject,
+        existingValueObject: nestedExistingValue,
         fieldDefinitionNodes: fields,
+        visitedTypes: newVisitedTypes,
     });
 }
 function getNamedTypeDefinitionNode(astNodeTypeNode, schemaDocumentNode) {
@@ -354,4 +393,528 @@ export function handleModelNameChange(params) {
     }
     updateModelSchemaNames(params);
 }
+/**
+ * Converts an output object type into an equivalent input object type.
+ * Intended for structural validation of state objects.
+ */
+export function objectTypeToInputType(schema, objectType, options) {
+    const suffix = options?.nameSuffix ?? "Input";
+    const cache = options?.cache ?? new Map();
+    const inputTypeName = `${objectType.name}${suffix}`;
+    if (cache.has(inputTypeName)) {
+        return cache.get(inputTypeName);
+    }
+    const inputType = new GraphQLInputObjectType({
+        name: inputTypeName,
+        fields: () => {
+            const fields = objectType.getFields();
+            const inputFields = {};
+            for (const fieldName in fields) {
+                const field = fields[fieldName];
+                if (field.args.length > 0) {
+                    throw new Error(`Cannot convert field "${objectType.name}.${fieldName}" with arguments into input type`);
+                }
+                inputFields[fieldName] = {
+                    type: outputTypeToInputType(schema, field.type, suffix, cache),
+                };
+            }
+            return inputFields;
+        },
+    });
+    cache.set(inputTypeName, inputType);
+    return inputType;
+}
+function outputTypeToInputType(schema, type, suffix, cache) {
+    if (isNonNullType(type)) {
+        return new GraphQLNonNull(outputTypeToInputType(schema, type.ofType, suffix, cache));
+    }
+    if (isListType(type)) {
+        return new GraphQLList(outputTypeToInputType(schema, type.ofType, suffix, cache));
+    }
+    if (isScalarType(type) || isEnumType(type)) {
+        return type;
+    }
+    if (isObjectType(type)) {
+        return objectTypeToInputType(schema, type, {
+            nameSuffix: suffix,
+            cache,
+        });
+    }
+    throw new Error(`Unsupported output type: ${type.toString()}`);
+}
+export function validateStateObject(sharedSchemaDocumentNode, stateTypeDefinitionNode, stateValue) {
+    let stateObjectJson;
+    try {
+        stateObjectJson = JSON.parse(stateValue);
+    }
+    catch (error) {
+        return [new Error("Invalid JSON object", { cause: error })];
+    }
+    // 2) Build a quick index of type definitions from the shared schema
+    const typeDefByName = indexTypeDefinitions(sharedSchemaDocumentNode);
+    // Ensure the passed node exists in the shared schema (optional but helpful)
+    const stateTypeName = stateTypeDefinitionNode.name.value;
+    if (!typeDefByName.has(stateTypeName)) {
+        return [
+            new Error(`State type "${stateTypeName}" was not found in sharedSchemaDocumentNode`),
+        ];
+    }
+    // 3) Generate input types needed to validate this state object
+    const inputSuffix = "Input";
+    const generatedInputDefs = generateInputTypesForObjectTree(stateTypeName, typeDefByName, inputSuffix);
+    // 4) Build a schema that includes the generated input types
+    const augmentedDoc = {
+        ...sharedSchemaDocumentNode,
+        definitions: [
+            ...sharedSchemaDocumentNode.definitions,
+            ...generatedInputDefs,
+        ],
+    };
+    let schema;
+    try {
+        schema = buildASTSchema(augmentedDoc, { assumeValidSDL: false });
+    }
+    catch (e) {
+        return [new Error("Failed to build schema from SDL", { cause: e })];
+    }
+    // 5) Validate by coercing variables against the generated input type
+    const inputTypeName = `${stateTypeName}${inputSuffix}`;
+    const opDoc = parse(`query($v: ${inputTypeName}!) { __typename }`);
+    const op = getOperationAST(opDoc);
+    if (!op) {
+        return [new Error("Failed to create validation operation AST")];
+    }
+    const { errors } = getVariableValues(schema, op.variableDefinitions ?? [], {
+        v: stateObjectJson,
+    });
+    // Detect recursive types first - these take priority over NON_NULL errors
+    const recursiveTypeErrors = detectRecursiveTypes(stateTypeDefinitionNode, typeDefByName);
+    // Get the field names that have recursive types
+    const recursiveFieldNames = new Set(recursiveTypeErrors.map((e) => e.field));
+    const validationErrors = errors
+        ? graphQLErrorsToStateValidationErrors(errors).filter((e) => {
+            // Filter out NON_NULL errors caused by recursive types
+            if (e instanceof StateValidationError && e.kind === "NON_NULL") {
+                // Check if this error is in a path that starts with a recursive field
+                const rootField = e.path[0];
+                if (typeof rootField === "string" &&
+                    recursiveFieldNames.has(rootField)) {
+                    return false;
+                }
+            }
+            return true;
+        })
+        : [];
+    // Add recursive type errors first (they have priority)
+    validationErrors.unshift(...recursiveTypeErrors);
+    const missingOptionalErrors = detectMissingOptionalFields(sharedSchemaDocumentNode, stateTypeDefinitionNode, stateObjectJson);
+    validationErrors.push(...missingOptionalErrors);
+    return validationErrors;
+}
+/**
+ * Indexes object/input/enum/scalar/interface/union type definition nodes by name.
+ * Note: only AST definitions that have a "name" field are indexed.
+ */
+function indexTypeDefinitions(doc) {
+    const map = new Map();
+    for (const def of doc.definitions) {
+        if (def.kind === Kind.OBJECT_TYPE_DEFINITION ||
+            def.kind === Kind.INPUT_OBJECT_TYPE_DEFINITION ||
+            def.kind === Kind.ENUM_TYPE_DEFINITION ||
+            def.kind === Kind.SCALAR_TYPE_DEFINITION ||
+            def.kind === Kind.INTERFACE_TYPE_DEFINITION ||
+            def.kind === Kind.UNION_TYPE_DEFINITION ||
+            def.kind === Kind.OBJECT_TYPE_EXTENSION ||
+            def.kind === Kind.INPUT_OBJECT_TYPE_EXTENSION ||
+            def.kind === Kind.ENUM_TYPE_EXTENSION ||
+            def.kind === Kind.INTERFACE_TYPE_EXTENSION ||
+            def.kind === Kind.UNION_TYPE_EXTENSION) {
+            // Extensions also have names; we index them too (but see note below).
+            // In production, you may want to merge extensions into base definitions.
+            // For state validation, prefer definitions (not extensions) if both exist.
+            const name = def.name.value;
+            if (!map.has(name)) {
+                map.set(name, def);
+            }
+        }
+    }
+    return map;
+}
+/**
+ * Generates InputObjectTypeDefinitionNode(s) for a root object type and any nested
+ * object types reachable via fields, converting object references to their *Input equivalents*.
+ */
+function generateInputTypesForObjectTree(rootObjectTypeName, typeDefByName, inputSuffix) {
+    const generated = new Map();
+    const visiting = new Set();
+    const ensureInputForObject = (objectTypeName) => {
+        const inputName = `${objectTypeName}${inputSuffix}`;
+        if (generated.has(inputName))
+            return;
+        if (visiting.has(objectTypeName)) {
+            // Recursive reference; we rely on GraphQLInputObjectType lazy field resolution via AST schema build.
+            // Still, we must avoid infinite loops while generating AST nodes.
+            return;
+        }
+        visiting.add(objectTypeName);
+        const def = typeDefByName.get(objectTypeName);
+        if (!def) {
+            throw new GraphQLError(`Unknown referenced type "${objectTypeName}"`);
+        }
+        if (def.kind !== Kind.OBJECT_TYPE_DEFINITION &&
+            def.kind !== Kind.OBJECT_TYPE_EXTENSION) {
+            throw new GraphQLError(`Type "${objectTypeName}" is not an object type; cannot generate input from kind "${def.kind}"`);
+        }
+        const objDef = def;
+        // Convert each field type to an input-acceptable TypeNode.
+        const inputFields = objDef.fields?.map((f) => {
+            return {
+                kind: Kind.INPUT_VALUE_DEFINITION,
+                name: f.name,
+                description: f.description,
+                directives: [], // output-field directives don't automatically translate to input fields
+                type: convertOutputTypeNodeToInputTypeNode(f.type, typeDefByName, inputSuffix, ensureInputForObject),
+                defaultValue: undefined,
+            };
+        }) ?? [];
+        const inputDef = {
+            kind: Kind.INPUT_OBJECT_TYPE_DEFINITION,
+            name: { kind: Kind.NAME, value: inputName },
+            description: objDef.description,
+            directives: [],
+            fields: inputFields,
+        };
+        generated.set(inputName, inputDef);
+        visiting.delete(objectTypeName);
+    };
+    // Kick off generation for root
+    ensureInputForObject(rootObjectTypeName);
+    return Array.from(generated.values());
+}
+function convertOutputTypeNodeToInputTypeNode(typeNode, typeDefByName, inputSuffix, ensureInputForObject) {
+    switch (typeNode.kind) {
+        case Kind.NON_NULL_TYPE:
+            return {
+                kind: Kind.NON_NULL_TYPE,
+                type: convertOutputTypeNodeToInputTypeNode(typeNode.type, typeDefByName, inputSuffix, ensureInputForObject),
+            };
+        case Kind.LIST_TYPE:
+            return {
+                kind: Kind.LIST_TYPE,
+                type: convertOutputTypeNodeToInputTypeNode(typeNode.type, typeDefByName, inputSuffix, ensureInputForObject),
+            };
+        case Kind.NAMED_TYPE: {
+            const named = typeNode;
+            const name = named.name.value;
+            const def = typeDefByName.get(name);
+            // If it's an object type, we must reference its generated input twin.
+            if (def?.kind === Kind.OBJECT_TYPE_DEFINITION ||
+                def?.kind === Kind.OBJECT_TYPE_EXTENSION) {
+                ensureInputForObject(name);
+                return {
+                    kind: Kind.NAMED_TYPE,
+                    name: { kind: Kind.NAME, value: `${name}${inputSuffix}` },
+                };
+            }
+            // Scalars/enums/input objects are valid as-is in input positions.
+            if (!def ||
+                def.kind === Kind.SCALAR_TYPE_DEFINITION ||
+                def.kind === Kind.ENUM_TYPE_DEFINITION ||
+                def.kind === Kind.INPUT_OBJECT_TYPE_DEFINITION ||
+                def.kind === Kind.INPUT_OBJECT_TYPE_EXTENSION) {
+                return named;
+            }
+            // Interfaces/unions are not valid input types.
+            if (def.kind === Kind.INTERFACE_TYPE_DEFINITION ||
+                def.kind === Kind.UNION_TYPE_DEFINITION) {
+                throw new GraphQLError(`Type "${name}" (${def.kind}) cannot be used in an input type`);
+            }
+            // Anything else is unexpected.
+            throw new GraphQLError(`Unsupported named type "${name}" of kind "${def.kind}"`);
+        }
+        default:
+            // Exhaustiveness guard
+            throw new GraphQLError(`Unsupported TypeNode kind: ${JSON.stringify(typeNode)}`);
+    }
+}
+export class StateValidationError extends Error {
+    payload;
+    originalMessage;
+    constructor(payload, originalMessage) {
+        // Keep Error.message stable but not user-facing; UI should render from payload.
+        super(payload.kind);
+        this.name = "StateValidationError";
+        this.payload = payload;
+        this.originalMessage = originalMessage;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+    get kind() {
+        return this.payload.kind;
+    }
+    get path() {
+        return this.payload.path;
+    }
+    get field() {
+        return this.payload.field;
+    }
+}
+function extractInputPath(message) {
+    const match = message.match(/at\s+"([^"]+)"/);
+    if (!match)
+        return [];
+    const parts = match[1].split(".").filter(Boolean);
+    const withoutVar = parts[0] === "v" ? parts.slice(1) : parts;
+    return withoutVar.map((p) => (/^\d+$/.test(p) ? Number(p) : p));
+}
+const RE_MISSING_REQUIRED_FIELD = /Field "([^"]+)" of required type "([^"]+)" was not provided\./;
+const RE_UNKNOWN_FIELD = /Field "([^"]+)" is not defined by type "([^"]+)"\.(?: Did you mean "([^"]+)"\?)?/;
+function extractMissingRequiredField(message) {
+    const m = message.match(RE_MISSING_REQUIRED_FIELD);
+    if (!m)
+        return null;
+    return { field: m[1], expectedType: m[2] };
+}
+function extractUnknownField(message) {
+    const m = message.match(RE_UNKNOWN_FIELD);
+    if (!m)
+        return null;
+    return { field: m[1], typeName: m[2], didYouMean: m[3] };
+}
+function lastFieldFromPath(path) {
+    for (let i = path.length - 1; i >= 0; i--) {
+        if (typeof path[i] === "string")
+            return path[i];
+    }
+    return undefined;
+}
+function extractExpectedType(message) {
+    // NON_NULL: Expected non-nullable type "Int!" not to be null.
+    let m = message.match(/Expected non-nullable type "([^"]+)"/);
+    if (m?.[1])
+        return m[1];
+    // Sometimes: Expected type "X" ...
+    m = message.match(/Expected type "([^"]+)"/);
+    if (m?.[1])
+        return m[1];
+    // Scalar coercion: "; String cannot represent ..."
+    m = message.match(/;\s*([_A-Za-z][_0-9A-Za-z]*)\s+cannot represent/i);
+    if (m?.[1])
+        return m[1];
+    return undefined;
+}
+export function graphQLErrorsToStateValidationErrors(errors) {
+    const out = [];
+    for (const e of errors) {
+        const originalMessage = e.message;
+        // 1) Missing required field (no `at "v.x"` path usually)
+        const missing = extractMissingRequiredField(originalMessage);
+        if (missing) {
+            out.push(new StateValidationError({
+                kind: "MISSING",
+                path: [missing.field],
+                field: missing.field,
+                expectedType: missing.expectedType, // if your payload supports it
+            }, originalMessage));
+            continue;
+        }
+        // 2) Unknown field (extra key)
+        const unknown = extractUnknownField(originalMessage);
+        if (unknown) {
+            out.push(new StateValidationError({
+                kind: "UNKNOWN_FIELD",
+                path: [unknown.field],
+                field: unknown.field,
+                didYouMean: unknown.didYouMean, // optional
+            }, originalMessage));
+            continue;
+        }
+        // 3) Usual `at "v.path"` extraction (NON_NULL / TYPE)
+        const path = extractInputPath(originalMessage);
+        const field = lastFieldFromPath(path) ?? "value";
+        const expectedType = extractExpectedType(originalMessage);
+        if (originalMessage.includes("Expected non-nullable type") &&
+            originalMessage.includes("not to be null")) {
+            out.push(new StateValidationError({ kind: "NON_NULL", path, field, expectedType }, originalMessage));
+            continue;
+        }
+        if (originalMessage.includes("cannot represent") ||
+            originalMessage.includes("Expected type")) {
+            out.push(new StateValidationError({
+                kind: "TYPE",
+                path,
+                field,
+                expectedType,
+                details: originalMessage,
+            }, originalMessage));
+            continue;
+        }
+        out.push(new StateValidationError({ kind: "TYPE", path, field, details: originalMessage }, originalMessage));
+    }
+    return out;
+}
+/**
+ * Finds all fields defined in the schema that are missing from the state object.
+ * Returns information about each missing field including whether it's required.
+ */
+export function findMissingFields(sharedSchemaDocumentNode, rootTypeNode, value, basePath = []) {
+    let stateObjectJson;
+    try {
+        stateObjectJson =
+            typeof value === "string"
+                ? JSON.parse(value)
+                : value;
+    }
+    catch {
+        return [];
+    }
+    const typeByName = indexObjectTypes(sharedSchemaDocumentNode);
+    const missingFields = [];
+    for (const field of rootTypeNode.fields ?? []) {
+        const fieldName = field.name.value;
+        const fieldPath = [...basePath, fieldName];
+        const isRequired = field.type.kind === Kind.NON_NULL_TYPE;
+        // Unwrap NonNull to get the underlying type
+        const underlyingType = isRequired
+            ? field.type.type
+            : field.type;
+        // Check if field is missing from the state object
+        if (!(fieldName in stateObjectJson)) {
+            missingFields.push({
+                fieldName,
+                path: fieldPath,
+                isRequired,
+                type: underlyingType,
+            });
+            continue;
+        }
+        // If present and object-typed → recurse to check nested missing fields
+        const namedType = unwrapNamedType(field.type);
+        const childType = namedType ? typeByName.get(namedType) : undefined;
+        if (childType &&
+            typeof stateObjectJson[fieldName] === "object" &&
+            stateObjectJson[fieldName] !== null &&
+            !Array.isArray(stateObjectJson[fieldName])) {
+            const nestedMissing = findMissingFields(sharedSchemaDocumentNode, childType, stateObjectJson[fieldName], fieldPath);
+            missingFields.push(...nestedMissing);
+        }
+    }
+    return missingFields;
+}
+/**
+ * Detects optional fields defined in the schema that are missing from the state object.
+ * Returns StateValidationError[] for each missing optional field.
+ */
+export function detectMissingOptionalFields(sharedSchemaDocumentNode, rootTypeNode, value) {
+    const missingFields = findMissingFields(sharedSchemaDocumentNode, rootTypeNode, value);
+    // Only report optional (not required) fields as MISSING_OPTIONAL errors
+    // Required fields are already caught by GraphQL validation
+    return missingFields
+        .filter((field) => !field.isRequired)
+        .map((field) => new StateValidationError({
+        kind: "MISSING_OPTIONAL",
+        path: field.path,
+        field: field.fieldName,
+        expectedType: typeNodeToString(field.type),
+    }));
+}
+/**
+ * Detects fields that have recursive types (types that reference themselves directly or indirectly).
+ * Returns a RECURSIVE_TYPE error for each field that contains a recursive type.
+ */
+function detectRecursiveTypes(stateTypeDefinitionNode, typeDefByName) {
+    const errors = [];
+    for (const field of stateTypeDefinitionNode.fields ?? []) {
+        const fieldName = field.name.value;
+        const namedTypeName = getNamedTypeName(field.type);
+        if (!namedTypeName)
+            continue;
+        // Check if this field's type is recursive
+        if (isRecursiveType(namedTypeName, typeDefByName, new Set())) {
+            errors.push(new StateValidationError({
+                kind: "RECURSIVE_TYPE",
+                path: [fieldName],
+                field: fieldName,
+                typeName: namedTypeName,
+            }));
+        }
+    }
+    return errors;
+}
+/**
+ * Gets the named type name from a TypeNode, unwrapping NonNull and List types.
+ */
+function getNamedTypeName(typeNode) {
+    if (typeNode.kind === Kind.NAMED_TYPE) {
+        return typeNode.name.value;
+    }
+    if (typeNode.kind === Kind.NON_NULL_TYPE ||
+        typeNode.kind === Kind.LIST_TYPE) {
+        return getNamedTypeName(typeNode.type);
+    }
+    return null;
+}
+/**
+ * Checks if a type is recursive (references itself directly or indirectly through required fields).
+ */
+function isRecursiveType(typeName, typeDefByName, visitedTypes) {
+    if (visitedTypes.has(typeName)) {
+        return true;
+    }
+    const typeDef = typeDefByName.get(typeName);
+    if (!typeDef || typeDef.kind !== Kind.OBJECT_TYPE_DEFINITION) {
+        return false;
+    }
+    visitedTypes.add(typeName);
+    for (const field of typeDef.fields ?? []) {
+        // Only check required fields for recursion (NonNull types)
+        if (field.type.kind !== Kind.NON_NULL_TYPE)
+            continue;
+        const innerType = field.type.type;
+        let fieldTypeName = null;
+        if (innerType.kind === Kind.NAMED_TYPE) {
+            fieldTypeName = innerType.name.value;
+        }
+        else if (innerType.kind === Kind.LIST_TYPE) {
+            // For list types like [Item!]!, get the inner type
+            fieldTypeName = getNamedTypeName(innerType);
+        }
+        if (fieldTypeName &&
+            isRecursiveType(fieldTypeName, typeDefByName, visitedTypes)) {
+            return true;
+        }
+    }
+    visitedTypes.delete(typeName);
+    return false;
+}
+/**
+ * Converts a TypeNode to its string representation (e.g., "String", "Int!", "[String]!")
+ */
+function typeNodeToString(typeNode) {
+    switch (typeNode.kind) {
+        case Kind.NAMED_TYPE:
+            return typeNode.name.value;
+        case Kind.NON_NULL_TYPE:
+            return `${typeNodeToString(typeNode.type)}!`;
+        case Kind.LIST_TYPE:
+            return `[${typeNodeToString(typeNode.type)}]`;
+    }
+}
+function indexObjectTypes(doc) {
+    const map = new Map();
+    for (const def of doc.definitions) {
+        if (def.kind === Kind.OBJECT_TYPE_DEFINITION) {
+            map.set(def.name.value, def);
+        }
+    }
+    return map;
+}
+function unwrapNamedType(typeNode) {
+    if (typeNode.kind === Kind.NAMED_TYPE)
+        return typeNode.name.value;
+    if (typeNode.kind === Kind.NON_NULL_TYPE)
+        return unwrapNamedType(typeNode.type);
+    if (typeNode.kind === Kind.LIST_TYPE)
+        return unwrapNamedType(typeNode.type);
+    return undefined;
+}
 //# sourceMappingURL=helpers.js.map