test: add regression test for choice validation (#613)

CLAUDE.md

@@ -128,9 +128,9 @@ mvn install -DskipTests
 
 # Generate binding classes using bootstrap POM (choose the appropriate module)
 # Each bootstrap POM generates classes directly into src/main/java
-mvn -f metaschema-testing/pom-bootstrap.xml generate-sources
-mvn -f databind/pom-bootstrap-config.xml generate-sources
-mvn -f databind/pom-bootstrap-model.xml generate-sources
+mvn -f metaschema-testing/pom-bootstrap.xml process-sources
+mvn -f databind/pom-bootstrap-config.xml process-sources
+mvn -f databind/pom-bootstrap-model.xml process-sources
 ```
 
 See the README.md files in each module for detailed instructions.

cli-processor/src/main/java/gov/nist/secauto/metaschema/cli/processor/command/CommandExecutionException.java

@@ -15,6 +15,9 @@
  */
 public class CommandExecutionException
     extends Exception {
+  /**
+   * The exit code indicating the type of error that occurred.
+   */
   private final ExitCode exitCode;
 
   /**

cli-processor/src/main/java/module-info.java

@@ -0,0 +1,35 @@
+/*
+ * SPDX-FileCopyrightText: none
+ * SPDX-License-Identifier: CC0-1.0
+ */
+
+import gov.nist.secauto.metaschema.cli.processor.command.ICommand;
+
+/**
+ * Provides a command-line interface processing framework for Metaschema tools.
+ *
+ * @uses ICommand to discover CLI commands via service loader
+ */
+module gov.nist.secauto.metaschema.cli.processor {
+  // requirements
+  requires java.base;
+
+  requires transitive gov.nist.secauto.metaschema.core;
+
+  requires static org.eclipse.jdt.annotation;
+  requires static com.github.spotbugs.annotations;
+
+  requires org.apache.commons.cli;
+  requires org.jansi.core;
+  requires nl.talsmasoftware.lazy4j;
+  requires org.apache.logging.log4j;
+  requires org.apache.logging.log4j.core;
+  requires org.apache.logging.log4j.jul;
+
+  exports gov.nist.secauto.metaschema.cli.processor;
+  exports gov.nist.secauto.metaschema.cli.processor.command;
+  exports gov.nist.secauto.metaschema.cli.processor.command.impl;
+  exports gov.nist.secauto.metaschema.cli.processor.completion;
+
+  uses ICommand;
+}

core/src/main/java/module-info.java

@@ -18,6 +18,7 @@
  *       implementing
  *       {@link gov.nist.secauto.metaschema.core.metapath.function.IFunction}
  */
+@SuppressWarnings("requires-transitive-automatic")
 module gov.nist.secauto.metaschema.core {
   // requirements
   requires java.base;
@@ -42,8 +43,8 @@
   requires transitive org.json;
   requires org.jsoup;
 
-  // dependencies without a module descriptor
-  requires transitive everit.json.schema; // needed for validation details
+  // dependencies without a module descriptor (automatic modules)
+  requires transitive everit.json.schema;
   requires transitive flexmark;
   requires flexmark.ext.escaped.character;
   requires flexmark.ext.gfm.strikethrough;

databind-metaschema/src/main/java/gov/nist/secauto/metaschema/modules/sarif/SarifValidationHandler.java

@@ -107,12 +107,23 @@ public String getLabel() {
 
   @NonNull
   static final String SARIF_NS = "https://docs.oasis-open.org/sarif/sarif/v2.1.0";
+  /**
+   * The property key for specifying a URL that provides help information for a
+   * constraint.
+   */
   @NonNull
   public static final IAttributable.Key SARIF_HELP_URL_KEY
       = IAttributable.key("help-url", SARIF_NS);
+  /**
+   * The property key for specifying plain text help content for a constraint.
+   */
   @NonNull
   public static final IAttributable.Key SARIF_HELP_TEXT_KEY
       = IAttributable.key("help-text", SARIF_NS);
+  /**
+   * The property key for specifying markdown-formatted help content for a
+   * constraint.
+   */
   @NonNull
   public static final IAttributable.Key SARIF_HELP_MARKDOWN_KEY
       = IAttributable.key("help-markdown", SARIF_NS);

databind-metaschema/src/main/java/module-info.java

@@ -0,0 +1,27 @@
+/*
+ * SPDX-FileCopyrightText: none
+ * SPDX-License-Identifier: CC0-1.0
+ */
+
+/**
+ * Provides Metaschema module bindings and validation handlers including SARIF
+ * output support.
+ */
+module gov.nist.secauto.metaschema.databind.modules {
+  // requirements
+  requires java.base;
+
+  requires transitive gov.nist.secauto.metaschema.core;
+  requires transitive gov.nist.secauto.metaschema.databind;
+  requires transitive gov.nist.secauto.metaschema.schemagen;
+
+  requires static org.eclipse.jdt.annotation;
+  requires static com.github.spotbugs.annotations;
+
+  requires json.schema;
+
+  exports gov.nist.secauto.metaschema.modules.sarif;
+
+  // open generated binding classes for reflection
+  opens org.schemastore.json.sarif.x210;
+}

databind/pom-bootstrap-config.xml

@@ -3,7 +3,7 @@
   This POM is used to regenerate the metaschema-bindings binding classes.
   It is NOT part of the normal build due to circular dependencies.
 
-  Usage: mvn -f databind/pom-bootstrap-config.xml generate-sources
+  Usage: mvn -f databind/pom-bootstrap-config.xml process-sources
 
   This will:
   1. Delete existing generated classes in the config/binding package
@@ -93,7 +93,7 @@
 				<executions>
 					<execution>
 						<id>add-license-headers</id>
-						<phase>generate-sources</phase>
+						<phase>process-sources</phase>
 						<goals>
 							<goal>format</goal>
 						</goals>
@@ -116,7 +116,7 @@
 				<executions>
 					<execution>
 						<id>format-generated-sources</id>
-						<phase>generate-sources</phase>
+						<phase>process-sources</phase>
 						<goals>
 							<goal>format</goal>
 						</goals>

databind/pom-bootstrap-model.xml

@@ -3,7 +3,7 @@
   This POM is used to regenerate the Metaschema model binding classes.
   It is NOT part of the normal build due to circular dependencies.
 
-  Usage: mvn -f databind/pom-bootstrap-model.xml generate-sources
+  Usage: mvn -f databind/pom-bootstrap-model.xml process-sources
 
   This will:
   1. Delete existing generated classes in the model/metaschema/binding package
@@ -98,7 +98,7 @@
 				<executions>
 					<execution>
 						<id>add-license-headers</id>
-						<phase>generate-sources</phase>
+						<phase>process-sources</phase>
 						<goals>
 							<goal>format</goal>
 						</goals>
@@ -121,7 +121,7 @@
 				<executions>
 					<execution>
 						<id>format-generated-sources</id>
-						<phase>generate-sources</phase>
+						<phase>process-sources</phase>
 						<goals>
 							<goal>format</goal>
 						</goals>

databind/src/main/java/gov/nist/secauto/metaschema/databind/DefaultBindingContext.java

@@ -270,6 +270,7 @@ public <CLASS extends IBoundObject> CLASS deepCopy(@NonNull CLASS other, IBoundO
    */
   @Override
   @SuppressWarnings({
+      "deprecation",
       "PMD.EmptyFinalizer",
       "checkstyle:NoFinalizer" })
   protected final void finalize() {

databind/src/main/java/gov/nist/secauto/metaschema/databind/IBindingContext.java

@@ -519,7 +519,9 @@ default IConstraintValidator newValidator(
    *          the validation configuration
    * @return the validation result
    * @throws ConstraintValidationException
+   *           if a constraint violation prevents validation from completing
    * @throws IllegalArgumentException
+   *           if the node item is not valid for validation
    */
   default IValidationResult validate(
       @NonNull IDocumentNodeItem nodeItem,
@@ -541,7 +543,9 @@ default IValidationResult validate(
    *          the validation configuration
    * @return the validation result
    * @throws ConstraintValidationException
+   *           if a constraint violation prevents validation from completing
    * @throws IllegalArgumentException
+   *           if the node item is not valid for validation
    */
   default IValidationResult validate(
       @NonNull IDefinitionNodeItem<?, ?> nodeItem,
@@ -577,6 +581,7 @@ default IValidationResult validate(
    * @throws IOException
    *           if an error occurred while reading the target
    * @throws ConstraintValidationException
+   *           if a constraint violation prevents validation from completing
    */
   default IValidationResult validate(
       @NonNull URI target,
@@ -605,6 +610,7 @@ default IValidationResult validate(
    * @throws IOException
    *           if an error occurred while parsing the target
    * @throws ConstraintValidationException
+   *           if a constraint violation prevents validation from completing
    */
   default IValidationResult validateWithConstraints(
       @NonNull URI target,

databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/IGeneratedDefinitionClass.java

@@ -9,6 +9,9 @@
 
 import edu.umd.cs.findbugs.annotations.NonNull;
 
+/**
+ * Represents a generated Java class for a Metaschema definition.
+ */
 public interface IGeneratedDefinitionClass extends IGeneratedClass {
 
   /**

databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/config/DefaultBindingConfiguration.java

@@ -39,6 +39,14 @@
 import edu.umd.cs.findbugs.annotations.NonNull;
 import edu.umd.cs.findbugs.annotations.Nullable;
 
+/**
+ * Default implementation of {@link IBindingConfiguration} that provides binding
+ * configuration for Java class generation from Metaschema modules.
+ * <p>
+ * This implementation supports loading configuration from XML files and
+ * provides namespace-to-package mappings and definition-specific binding
+ * configurations.
+ */
 public class DefaultBindingConfiguration implements IBindingConfiguration {
   private static final Logger LOGGER = LogManager.getLogger(DefaultBindingConfiguration.class);
 
@@ -659,6 +667,12 @@ private static IMutableDefinitionBindingConfiguration processDefinitionBindingCo
     return config;
   }
 
+  /**
+   * Holds binding configurations for a specific Metaschema module.
+   * <p>
+   * This class maintains mappings from definition names to their binding
+   * configurations for both assembly and field definitions.
+   */
   public static final class MetaschemaBindingConfiguration {
     private final Map<String, IDefinitionBindingConfiguration> assemblyBindingConfigs = new ConcurrentHashMap<>();
     private final Map<String, IDefinitionBindingConfiguration> fieldBindingConfigs = new ConcurrentHashMap<>();

databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/config/DefaultDefinitionBindingConfiguration.java

@@ -15,6 +15,10 @@
 import edu.umd.cs.findbugs.annotations.NonNull;
 import edu.umd.cs.findbugs.annotations.Nullable;
 
+/**
+ * Default implementation of {@link IMutableDefinitionBindingConfiguration} that
+ * provides mutable binding configuration for a specific Metaschema definition.
+ */
 public class DefaultDefinitionBindingConfiguration implements IMutableDefinitionBindingConfiguration {
   @Nullable
   private String className;

databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/config/IBindingConfiguration.java

@@ -13,6 +13,14 @@
 import edu.umd.cs.findbugs.annotations.NonNull;
 import edu.umd.cs.findbugs.annotations.Nullable;
 
+/**
+ * Provides configuration for Java class binding generation from Metaschema
+ * modules.
+ * <p>
+ * This interface defines how Metaschema module elements are mapped to Java
+ * classes, including package names, class names, base classes, and
+ * superinterfaces.
+ */
 public interface IBindingConfiguration {
 
   /**

databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/config/IDefinitionBindingConfiguration.java

@@ -11,6 +11,13 @@
 import edu.umd.cs.findbugs.annotations.NonNull;
 import edu.umd.cs.findbugs.annotations.Nullable;
 
+/**
+ * Provides binding configuration for a specific Metaschema definition.
+ * <p>
+ * This interface defines how an individual field or assembly definition is
+ * mapped to a generated Java class, including the class name, base class, and
+ * interfaces to implement.
+ */
 public interface IDefinitionBindingConfiguration {
   /**
    * Get the class name to use for the generated class associated with this

databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/DefaultMetaschemaClassFactory.java

@@ -312,7 +312,7 @@ public IGeneratedClass generatePackageInfoClass(
         writer.format(" * version %s%n", module.getVersion());
         MarkupMultiline remarks = module.getRemarks();
         if (remarks != null) {
-          writer.format(" * <p>%n");
+          // Remarks already include proper HTML formatting
           writer.format(" * %s%n", remarks.toHtml());
         }
       }
@@ -691,9 +691,19 @@ protected Set<IModelDefinition> buildClass(
   protected Set<IModelDefinition> buildClass(
       @NonNull IModelDefinitionTypeInfo typeInfo,
       @NonNull TypeSpec.Builder builder) {
-    MarkupLine description = typeInfo.getDefinition().getDescription();
+    IModelDefinition definition = typeInfo.getDefinition();
+    MarkupLine description = definition.getDescription();
     if (description != null) {
       builder.addJavadoc(description.toHtml());
+    } else {
+      // Fallback to formal-name or definition name when description is missing
+      String formalName = definition.getEffectiveFormalName();
+      if (formalName != null) {
+        builder.addJavadoc("$L.", formalName);
+      } else {
+        // Last resort: use the definition name
+        builder.addJavadoc("A binding class for the {@code $L} definition.", definition.getName());
+      }
     }
 
     Set<IModelDefinition> additionalChildClasses = new LinkedHashSet<>();

databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/FieldValueTypeInfoImpl.java

@@ -8,6 +8,7 @@
 import com.squareup.javapoet.AnnotationSpec;
 import com.squareup.javapoet.ClassName;
 import com.squareup.javapoet.FieldSpec;
+import com.squareup.javapoet.MethodSpec;
 import com.squareup.javapoet.TypeName;
 import com.squareup.javapoet.TypeSpec;
 
@@ -72,4 +73,19 @@ protected Set<IModelDefinition> buildField(
     fieldBuilder.addAnnotation(fieldValue.build());
     return retval;
   }
+
+  @Override
+  public void buildFieldJavadoc(@NonNull FieldSpec.Builder builder) {
+    builder.addJavadoc("The field value.");
+  }
+
+  @Override
+  public void buildGetterJavadoc(@NonNull MethodSpec.Builder builder) {
+    builder.addJavadoc("Get the field value.\n\n@return the value");
+  }
+
+  @Override
+  public void buildSetterJavadoc(@NonNull MethodSpec.Builder builder, @NonNull String paramName) {
+    builder.addJavadoc("Set the field value.\n\n@param $L\n          the value to set", paramName);
+  }
 }

databind/src/main/java/gov/nist/secauto/metaschema/databind/config/binding/MetaschemaBindings.java

@@ -1481,6 +1481,9 @@ public static class ItemType implements IBoundObject {
               typeAdapter = BooleanAdapter.class)
           private Boolean _useWildcard;
 
+          /**
+           * The field value.
+           */
           @BoundFieldValue(
               valueKeyName = "STRVALUE",
               typeAdapter = TokenAdapter.class)
@@ -1540,11 +1543,22 @@ public void setUseWildcard(@Nullable Boolean value) {
             _useWildcard = value;
           }
 
+          /**
+           * Get the field value.
+           *
+           * @return the value
+           */
           @Nullable
           public String getValue() {
             return _value;
           }
 
+          /**
+           * Set the field value.
+           *
+           * @param value
+           *          the value to set
+           */
           public void setValue(@Nullable String value) {
             _value = value;
           }