/*
    * SPDX-FileCopyrightText: none
    * SPDX-License-Identifier: CC0-1.0
    */
   
   package dev.metaschema.databind.io;
   
   import java.io.IOException;
   import java.util.ArrayList;
  import java.util.Collection;
  import java.util.HashMap;
  import java.util.HashSet;
  import java.util.List;
  import java.util.Map;
  import java.util.Set;
  import java.util.stream.Collectors;
  
  import dev.metaschema.core.model.IAssemblyInstance;
  import dev.metaschema.core.model.IBoundObject;
  import dev.metaschema.core.model.IChoiceInstance;
  import dev.metaschema.core.model.IFieldInstance;
  import dev.metaschema.core.model.IFlagInstance;
  import dev.metaschema.core.model.IModelInstance;
  import dev.metaschema.core.model.INamedModelInstanceAbsolute;
  import dev.metaschema.core.util.ObjectUtils;
  import dev.metaschema.databind.model.IBoundDefinitionModelAssembly;
  import dev.metaschema.databind.model.IBoundDefinitionModelComplex;
  import dev.metaschema.databind.model.IBoundProperty;
  import edu.umd.cs.findbugs.annotations.NonNull;
  import edu.umd.cs.findbugs.annotations.Nullable;
  
  /**
   * Abstract base class for problem handlers that can validate required fields
   * during deserialization.
   */
  public abstract class AbstractProblemHandler implements IProblemHandler {
    private final boolean validateRequiredFields;
  
    /**
     * Construct a new problem handler with default settings.
     * <p>
     * Required field validation is enabled by default.
     */
    protected AbstractProblemHandler() {
      this(true);
    }
  
    /**
     * Construct a new problem handler with the specified validation setting.
     *
     * @param validateRequiredFields
     *          {@code true} to validate that required fields are present,
     *          {@code false} to skip validation
     */
    protected AbstractProblemHandler(boolean validateRequiredFields) {
      this.validateRequiredFields = validateRequiredFields;
    }
  
    /**
     * Determine if required field validation is enabled.
     *
     * @return {@code true} if required fields should be validated, {@code false}
     *         otherwise
     */
    protected boolean isValidateRequiredFields() {
      return validateRequiredFields;
    }
  
    @Override
    public void handleMissingInstances(
        IBoundDefinitionModelComplex parentDefinition,
        IBoundObject targetObject,
        Collection<? extends IBoundProperty<?>> unhandledInstances) throws IOException {
      // Delegate to the context-aware version with null context
      handleMissingInstances(parentDefinition, targetObject, unhandledInstances, null);
    }
  
    @Override
    public void handleMissingInstances(
        IBoundDefinitionModelComplex parentDefinition,
        IBoundObject targetObject,
        Collection<? extends IBoundProperty<?>> unhandledInstances,
        @Nullable ValidationContext context) throws IOException {
      if (isValidateRequiredFields()) {
        validateRequiredFields(parentDefinition, unhandledInstances, context);
      }
      applyDefaults(targetObject, unhandledInstances);
    }
  
    /**
     * Validate that all required fields have values or defaults.
     * <p>
     * This method handles choice groups correctly: if an instance belongs to a
     * choice and at least one sibling in that choice was provided, the instance is
     * not considered missing.
     *
     * @param parentDefinition
     *          the definition containing the unhandled instances
     * @param unhandledInstances
    *          the collection of unhandled instances to validate
    * @param context
    *          the validation context with location and path information, may be
    *          null
    * @throws IOException
    *           if a required field is missing and has no default value
    */
   protected void validateRequiredFields(
       @NonNull IBoundDefinitionModelComplex parentDefinition,
       @NonNull Collection<? extends IBoundProperty<?>> unhandledInstances,
       @Nullable ValidationContext context) throws IOException {
 
     // Build a set of unhandled instance names for quick lookup
     Set<String> unhandledNames = new HashSet<>();
     for (IBoundProperty<?> instance : unhandledInstances) {
       assert instance != null;
       unhandledNames.add(getInstanceName(instance, context));
     }
 
     // Build a map from instance name to its choice group (if any)
     Map<String, IChoiceInstance> instanceToChoice = buildInstanceToChoiceMap(parentDefinition, context);
 
     // Collect missing required properties grouped by type
     List<IBoundProperty<?>> missingFlags = new ArrayList<>();
     List<IBoundProperty<?>> missingFields = new ArrayList<>();
     List<IBoundProperty<?>> missingAssemblies = new ArrayList<>();
 
     for (IBoundProperty<?> instance : unhandledInstances) {
       assert instance != null;
       if (isRequiredAndMissingDefault(instance)) {
         String instanceName = getInstanceName(instance, context);
         IChoiceInstance choice = instanceToChoice.get(instanceName);
 
         if (choice != null) {
           // Instance belongs to a choice group - check if any sibling was provided
           if (!isChoiceSatisfied(choice, unhandledNames, context)) {
             // All siblings in the choice are missing - report this as an error
             addToTypeList(instance, missingFlags, missingFields, missingAssemblies);
           }
           // else: at least one sibling was provided, choice is satisfied
         } else {
           // Not in a choice group - normal required field check
           addToTypeList(instance, missingFlags, missingFields, missingAssemblies);
         }
       }
     }
 
     if (!missingFlags.isEmpty() || !missingFields.isEmpty() || !missingAssemblies.isEmpty()) {
       throw new IOException(formatMissingPropertiesMessage(
           parentDefinition, missingFlags, missingFields, missingAssemblies, context));
     }
   }
 
   /**
    * Add an instance to the appropriate type-specific list.
    *
    * @param instance
    *          the instance to categorize
    * @param missingFlags
    *          list for flag instances
    * @param missingFields
    *          list for field instances
    * @param missingAssemblies
    *          list for assembly instances
    */
   private static void addToTypeList(
       @NonNull IBoundProperty<?> instance,
       @NonNull List<IBoundProperty<?>> missingFlags,
       @NonNull List<IBoundProperty<?>> missingFields,
       @NonNull List<IBoundProperty<?>> missingAssemblies) {
     if (instance instanceof IFlagInstance) {
       missingFlags.add(instance);
     } else if (instance instanceof IFieldInstance) {
       missingFields.add(instance);
     } else if (instance instanceof IAssemblyInstance) {
       missingAssemblies.add(instance);
     } else {
       // Default to fields for unknown types
       missingFields.add(instance);
     }
   }
 
   /**
    * Format a comprehensive error message for missing required properties.
    *
    * @param parentDefinition
    *          the parent definition containing the properties
    * @param missingFlags
    *          missing flag instances
    * @param missingFields
    *          missing field instances
    * @param missingAssemblies
    *          missing assembly instances
    * @param context
    *          the validation context, may be null
    * @return a formatted error message
    */
   @NonNull
   private static String formatMissingPropertiesMessage(
       @NonNull IBoundDefinitionModelComplex parentDefinition,
       @NonNull List<IBoundProperty<?>> missingFlags,
       @NonNull List<IBoundProperty<?>> missingFields,
       @NonNull List<IBoundProperty<?>> missingAssemblies,
       @Nullable ValidationContext context) {
 
     StringBuilder message = new StringBuilder();
     String parentName = getParentName(parentDefinition, context);
     Format format = context != null ? context.getFormat() : Format.JSON;
 
     int totalMissing = missingFlags.size() + missingFields.size() + missingAssemblies.size();
 
     if (totalMissing == 1) {
       // Single missing property - use specific format
       IBoundProperty<?> missing = ObjectUtils.notNull(!missingFlags.isEmpty() ? missingFlags.get(0)
           : !missingFields.isEmpty() ? missingFields.get(0)
               : missingAssemblies.get(0));
       String type = getPropertyTypeName(missing, format, false);
       String name = getInstanceName(missing, context);
       message.append(String.format("Missing required %s '%s' in '%s'", type, name, parentName));
     } else if (hasSingleType(missingFlags, missingFields, missingAssemblies)) {
       // Multiple properties of single type
       List<IBoundProperty<?>> list = !missingFlags.isEmpty() ? missingFlags
           : !missingFields.isEmpty() ? missingFields
               : missingAssemblies;
       String type = getPropertyTypeName(ObjectUtils.notNull(list.get(0)), format, true);
       String names = formatNameList(list, context);
       message.append(String.format("Missing required %s in '%s': %s", type, parentName, names));
     } else {
       // Multiple properties of different types
       message.append(String.format("Missing required properties in '%s':", parentName));
       if (!missingFlags.isEmpty()) {
         message.append("\n  ").append(getFormatPropertyGroupLabel(true, format))
             .append(": ").append(formatNameList(missingFlags, context));
       }
       if (!missingFields.isEmpty()) {
         message.append("\n  ").append(getFormatPropertyGroupLabel(false, format))
             .append(": ").append(formatNameList(missingFields, context));
       }
       if (!missingAssemblies.isEmpty()) {
         message.append("\n  ").append(getFormatPropertyGroupLabel(false, format))
             .append(": ").append(formatNameList(missingAssemblies, context));
       }
     }
 
     // Add location and path context
     if (context != null) {
       String location = context.formatLocation();
       if (!location.isEmpty()) {
         message.append("\n  Location: ").append(location);
       }
       String path = context.getPath();
       if (!"/".equals(path) && !path.isEmpty()) {
         message.append("\n  Path: ").append(path);
       }
     }
 
     return ObjectUtils.notNull(message.toString());
   }
 
   /**
    * Get the user-friendly name for a property type in the given format.
    * <p>
    * This method maps Metaschema concepts to format-appropriate terminology:
    * <ul>
    * <li>XML: flags are "attribute", fields/assemblies are "element"</li>
    * <li>JSON: all properties are "property"</li>
    * <li>YAML: all properties are "property"</li>
    * </ul>
    *
    * @param isFlag
    *          {@code true} if the property is a flag instance
    * @param format
    *          the format being parsed
    * @param plural
    *          {@code true} for plural form, {@code false} for singular
    * @return the user-friendly type name
    */
   @NonNull
   private static String getFormatPropertyTypeName(boolean isFlag, @NonNull Format format, boolean plural) {
     switch (format) {
     case XML:
       if (isFlag) {
         return plural ? "attributes" : "attribute";
       }
       return plural ? "elements" : "element";
     case JSON:
     case YAML:
       return plural ? "properties" : "property";
     default:
       // Fallback for any future formats - use generic "property"
       return plural ? "properties" : "property";
     }
   }
 
   /**
    * Get the user-friendly label for a group of properties in the given format.
    * <p>
    * Used when listing multiple properties of the same type in error messages.
    * Delegates to {@link #getFormatPropertyTypeName(boolean, Format, boolean)} and
    * capitalizes the result.
    *
    * @param isFlags
    *          {@code true} if listing flag instances
    * @param format
    *          the format being parsed
    * @return the plural label (e.g., "Attributes", "Elements", "Properties")
    */
   @NonNull
   private static String getFormatPropertyGroupLabel(boolean isFlags, @NonNull Format format) {
     String typeName = getFormatPropertyTypeName(isFlags, format, true);
     return Character.toUpperCase(typeName.charAt(0)) + typeName.substring(1);
   }
 
   /**
    * Check if only one type list has entries.
    */
   private static boolean hasSingleType(
       List<IBoundProperty<?>> flags,
       List<IBoundProperty<?>> fields,
       List<IBoundProperty<?>> assemblies) {
     int nonEmpty = 0;
     if (!flags.isEmpty()) {
       nonEmpty++;
     }
     if (!fields.isEmpty()) {
       nonEmpty++;
     }
     if (!assemblies.isEmpty()) {
       nonEmpty++;
     }
     return nonEmpty == 1;
   }
 
   /**
    * Get the property type name for error messages in format-appropriate terms.
    * <p>
    * Delegates to {@link #getFormatPropertyTypeName(boolean, Format, boolean)}
    * based on whether the instance is a flag.
    *
    * @param instance
    *          the property instance
    * @param format
    *          the format being parsed
    * @param plural
    *          {@code true} for plural form, {@code false} for singular
    * @return the user-friendly type name appropriate for the format
    */
   @NonNull
   private static String getPropertyTypeName(
       @NonNull IBoundProperty<?> instance,
       @NonNull Format format,
       boolean plural) {
     boolean isFlag = instance instanceof IFlagInstance;
     return getFormatPropertyTypeName(isFlag, format, plural);
   }
 
   /**
    * Format a list of property names as a comma-separated string.
    */
   @NonNull
   private static String formatNameList(
       @NonNull List<IBoundProperty<?>> instances,
       @Nullable ValidationContext context) {
     return ObjectUtils.notNull(instances.stream()
         .map(i -> getInstanceName(ObjectUtils.notNull(i), context))
         .collect(Collectors.joining(", ")));
   }
 
   /**
    * Get the parent definition name for error messages.
    *
    * @param parentDefinition
    *          the parent definition
    * @param context
    *          the validation context, may be null
    * @return the effective name of the parent
    */
   @NonNull
   private static String getParentName(
       @NonNull IBoundDefinitionModelComplex parentDefinition,
       @Nullable ValidationContext context) {
     // Use effective name which is format-appropriate
     return parentDefinition.getEffectiveName();
   }
 
   /**
    * Build a map from instance name to its containing choice instance.
    *
    * @param parentDefinition
    *          the parent definition to examine
    * @param context
    *          the validation context, may be null
    * @return a map of instance names to their choice groups, empty if no choices
    */
   @NonNull
   private static Map<String, IChoiceInstance> buildInstanceToChoiceMap(
       @NonNull IBoundDefinitionModelComplex parentDefinition,
       @Nullable ValidationContext context) {
     Map<String, IChoiceInstance> result = new HashMap<>();
 
     if (parentDefinition instanceof IBoundDefinitionModelAssembly) {
       IBoundDefinitionModelAssembly assembly = (IBoundDefinitionModelAssembly) parentDefinition;
       for (IChoiceInstance choice : assembly.getChoiceInstances()) {
         for (INamedModelInstanceAbsolute modelInstance : choice.getNamedModelInstances()) {
           // Use effective name for format-appropriate matching
           result.put(modelInstance.getEffectiveName(), choice);
         }
       }
     }
 
     return result;
   }
 
   /**
    * Check if a choice is satisfied.
    * <p>
    * A choice is satisfied if:
    * <ul>
    * <li>At least one alternative was provided, OR</li>
    * <li>The choice is optional (minOccurs = 0) and no alternative is required
    * </li>
    * </ul>
    *
    * @param choice
    *          the choice to check
    * @param unhandledNames
    *          the set of instance names that were NOT provided
    * @param context
    *          the validation context, may be null
    * @return {@code true} if the choice requirements are satisfied, {@code false}
    *         if a required alternative is missing
    */
   private static boolean isChoiceSatisfied(
       @NonNull IChoiceInstance choice,
       @NonNull Set<String> unhandledNames,
       @Nullable ValidationContext context) {
     // Check if any alternative was provided
     for (INamedModelInstanceAbsolute modelInstance : choice.getNamedModelInstances()) {
       // Use effective name for format-appropriate matching
       String name = modelInstance.getEffectiveName();
       if (!unhandledNames.contains(name)) {
         // This sibling was provided (not in unhandled list)
         return true;
       }
     }
 
     // All siblings are in the unhandled list - check if choice is optional
     // If choice.getMinOccurs() == 0, having no selection is valid
     return choice.getMinOccurs() == 0;
   }
 
   /**
    * Determine if the given instance is required and has no default value.
    *
    * @param instance
    *          the instance to check
    * @return {@code true} if the instance is required and has no default value
    */
   private static boolean isRequiredAndMissingDefault(@NonNull IBoundProperty<?> instance) {
     // Check if the instance has a default value
     Object defaultValue = instance.getResolvedDefaultValue();
     if (defaultValue != null) {
       // Has a default value, so it's not "missing"
       return false;
     }
 
     // Check if the instance is required
     if (instance instanceof IFlagInstance) {
       return ((IFlagInstance) instance).isRequired();
     } else if (instance instanceof IModelInstance) {
       return ((IModelInstance) instance).getMinOccurs() > 0;
     }
 
     // Unknown instance type, don't require it
     return false;
   }
 
   /**
    * Get a human-readable name for the instance.
    * <p>
    * Uses {@code getEffectiveName()} when available to return the
    * format-appropriate name (XML element/attribute name for XML, JSON property
    * name for JSON). Falls back to {@code getJsonName()} if effective name is not
    * available.
    *
    * @param instance
    *          the instance to get the name for
    * @param context
    *          the validation context, may be null
    * @return the instance name
    */
   @NonNull
   private static String getInstanceName(
       @NonNull IBoundProperty<?> instance,
       @Nullable ValidationContext context) {
     // Check for specific instance types that have getEffectiveName()
     if (instance instanceof IFlagInstance) {
       return ((IFlagInstance) instance).getEffectiveName();
     } else if (instance instanceof IFieldInstance) {
       return ((IFieldInstance) instance).getEffectiveName();
     } else if (instance instanceof IAssemblyInstance) {
       return ((IAssemblyInstance) instance).getEffectiveName();
     }
     // Fall back to JSON name for other types
     return instance.getJsonName();
   }
 
   /**
    * A utility method for applying default values for the provided
    * {@code unhandledInstances}.
    *
    * @param targetObject
    *          the Java object to apply default values to
    * @param unhandledInstances
    *          the collection of unhandled instances to assign default values for
    * @throws IOException
    *           if an error occurred while determining the default value for an
    *           instance
    */
   protected static void applyDefaults(
       @NonNull Object targetObject,
       @NonNull Collection<? extends IBoundProperty<?>> unhandledInstances) throws IOException {
     for (IBoundProperty<?> instance : unhandledInstances) {
       assert instance != null;
       Object value = instance.getResolvedDefaultValue();
       if (value != null) {
         instance.setValue(targetObject, value);
       }
     }
   }
 }