Replaced Paths.get() with Paths.get(System.getProperty(user.dir)) to be more explict. Improved value creation methods in date and date/time item classes. Added many Javadocs.

Author: David Waltermire

cli-processor/src/main/java-templates/gov/nist/secauto/metaschema/cli/processor/ProcessorVersion.java

@@ -12,7 +12,7 @@
  */
 public class ProcessorVersion implements IVersionInfo {
 
-  private static final String NAME = "metaschema-java";
+  private static final String NAME = "${project.name}";
   private static final String VERSION = "${project.version}";
   private static final String BUILD_TIMESTAMP = "${timestamp}";
   private static final String COMMIT = "@git.commit.id.abbrev@";

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

@@ -15,6 +15,11 @@
 
 /**
  * Records information about the exit status of a CLI command.
+ * <p>
+ * This abstract class provides base functionality for handling CLI command exit
+ * statuses, including error logging and throwable management. Implementing
+ * classes must provide the {@link #getMessage()} implementation to define the
+ * status message content.
  */
 public abstract class AbstractExitStatus implements ExitStatus {
   private static final Logger LOGGER = LogManager.getLogger(AbstractExitStatus.class);
@@ -64,6 +69,14 @@ public ExitStatus withThrowable(@NonNull Throwable throwable) {
   @Nullable
   protected abstract String getMessage();
 
+  /**
+   * Determines the appropriate LogBuilder based on the exit code status. For
+   * non-positive exit codes (success/info), returns an INFO level builder. For
+   * positive exit codes (errors), returns an ERROR level builder.
+   *
+   * @return the appropriate LogBuilder based on exit status, or {@code null} if
+   *         logging is disabled at the determined level
+   */
   @Nullable
   private LogBuilder getLogBuilder() {
     LogBuilder logBuilder = null;
@@ -77,6 +90,15 @@ private LogBuilder getLogBuilder() {
     return logBuilder;
   }
 
+  /**
+   * Generates and logs a message based on the current exit status. The message is
+   * logged at either INFO level (for success/info status) or ERROR level (for
+   * error status).
+   *
+   * @param showStackTrace
+   *          if {@code true} and a throwable is present, includes the stack trace
+   *          in the log
+   */
   @Override
   public void generateMessage(boolean showStackTrace) {
     LogBuilder logBuilder = getLogBuilder();
@@ -99,7 +121,7 @@ public void generateMessage(boolean showStackTrace) {
     } else if (useStackTrace) {
       // log the throwable
       logBuilder.log();
-    }
+    } // else avoid an empty log line
   }
 
 }

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

@@ -51,6 +51,9 @@
 
 /**
  * Processes command line arguments and dispatches called commands.
+ * <p>
+ * This implementation make significant use of the command pattern to support a
+ * delegation chain of commands based on implementations of {@link ICommand}.
  */
 @SuppressWarnings("PMD.CouplingBetweenObjects")
 public class CLIProcessor {
@@ -114,7 +117,7 @@ public class CLIProcessor {
   @NonNull
   private final List<ICommand> commands = new LinkedList<>();
   @NonNull
-  private final String args;
+  private final String exec;
   @NonNull
   private final Map<String, IVersionInfo> versionInfos;
 
@@ -152,13 +155,13 @@ public CLIProcessor(@NonNull String args) {
    * <p>
    * This uses the provided version information.
    *
-   * @param args
-   *          the command line arguments
+   * @param exec
+   *          the command name
    * @param versionInfos
    *          the version info to display when the version option is provided
    */
-  public CLIProcessor(@NonNull String args, @NonNull Map<String, IVersionInfo> versionInfos) {
-    this.args = args;
+  public CLIProcessor(@NonNull String exec, @NonNull Map<String, IVersionInfo> versionInfos) {
+    this.exec = exec;
     this.versionInfos = versionInfos;
     AnsiConsole.systemInstall();
   }
@@ -169,8 +172,8 @@ public CLIProcessor(@NonNull String args, @NonNull Map<String, IVersionInfo> ver
    * @return the command name
    */
   @NonNull
-  public String getArguments() {
-    return args;
+  public String getExec() {
+    return exec;
   }
 
   /**
@@ -631,7 +634,7 @@ private String buildHelpFooter() {
         builder
             .append(System.lineSeparator())
             .append('\'')
-            .append(getArguments())
+            .append(getExec())
             .append(" <command> --help' will show help on that specific command.")
             .append(System.lineSeparator());
         retval = builder.toString();
@@ -648,7 +651,7 @@ private String buildHelpFooter() {
     private String buildHelpCliSyntax() {
 
       StringBuilder builder = new StringBuilder(64);
-      builder.append(getArguments());
+      builder.append(getExec());
 
       List<ICommand> calledCommands = getCalledCommands();
       if (!calledCommands.isEmpty()) {

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

@@ -15,6 +15,9 @@
 
 /**
  * An {@link ExitStatus} implementation with an associated message.
+ * <p>
+ * The message arguments are stored in an unmodifiable list to ensure
+ * thread-safety and immutability.
  */
 public class MessageExitStatus
     extends AbstractExitStatus {

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

@@ -8,21 +8,32 @@
 import edu.umd.cs.findbugs.annotations.NonNull;
 
 /**
- * An {@link ExitStatus} implementation without an associated message.
+ * An {@link ExitStatus} implementation that represents a status without an
+ * associated message.
+ * <p>
+ * This implementation is useful when only the exit code needs to be
+ * communicated, without additional context or explanation.
  */
 public class NonMessageExitStatus
     extends AbstractExitStatus {
 
   /**
-   * Construct a new message status.
+   * Construct a new exit status without an associated message.
+   *
+   * @param code
+   *          the non-null exit code representing the status
    */
   NonMessageExitStatus(@NonNull ExitCode code) {
     super(code);
   }
 
+  /**
+   * {@inheritDoc}
+   *
+   * @return {@code null} as this implementation does not support messages
+   */
   @Override
   protected String getMessage() {
-    // always null
     return null;
   }
 }

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

@@ -38,7 +38,8 @@ protected AbstractCommandExecutor(
   }
 
   /**
-   * Get the context of the command execution.
+   * Get the context of the command execution, which provides access to the
+   * execution environment needed for command processing.
    *
    * @return the context
    */
@@ -48,7 +49,8 @@ protected CallingContext getCallingContext() {
   }
 
   /**
-   * Get the parsed command line details.
+   * Get the parsed command line details containing the command options and
+   * arguments provided by the user during execution.
    *
    * @return the cli details
    */

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

@@ -21,7 +21,11 @@
 import edu.umd.cs.findbugs.annotations.NonNull;
 
 /**
- * A base class for a command that has child commands.
+ * A base class for a command that supports hierarchical command structure with
+ * child commands. This class provides the foundation for implementing complex
+ * CLI commands that can have multiple levels of sub-commands.
+ * <p>
+ * This class is thread-safe and supports concurrent access to command handlers.
  */
 public abstract class AbstractParentCommand implements ICommand {
   @NonNull

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

@@ -17,13 +17,17 @@
 import nl.talsmasoftware.lazy4j.Lazy;
 
 /**
- * A base class for commands that have no children.
+ * A base class for terminal commands in the command processing hierarchy.
+ * Terminal commands represent leaf nodes that perform actual operations and
+ * cannot have child commands.
  */
 public abstract class AbstractTerminalCommand implements ICommand {
-  private static Lazy<Path> currentWorkingDirectory = Lazy.lazy(() -> Paths.get("").toAbsolutePath());
+  private static Lazy<Path> currentWorkingDirectory = Lazy.lazy(() -> Paths.get(System.getProperty("user.dir")));
 
   /**
    * A utility method that can be used to get the current working directory.
+   * <p>
+   * This method is thread-safe due to lazy initialization.
    *
    * @return the current working directory
    */
@@ -35,6 +39,8 @@ protected static Path getCurrentWorkingDirectory() {
   /**
    * A utility method that can be used to resolve a path against the current
    * working directory.
+   * <p>
+   * If the path is already absolute, then the provided path is returned.
    *
    * @param path
    *          the path to resolve
@@ -43,12 +49,21 @@ protected static Path getCurrentWorkingDirectory() {
    */
   @NonNull
   protected static Path resolveAgainstCWD(@NonNull Path path) {
-    return ObjectUtils.notNull(getCurrentWorkingDirectory().resolve(path).normalize());
+
+    return path.isAbsolute()
+        ? path
+        : ObjectUtils.notNull(getCurrentWorkingDirectory().resolve(path).normalize());
   }
 
   /**
    * A utility method that can be used to resolve a URI against the URI for the
    * current working directory.
+   * <p>
+   * If the URI is already absolute, then the provided URI is returned.
+   * <p>
+   * The path is normalized after resolution to remove any redundant name elements
+   * (like "." or "..").
+   *
    *
    * @param uri
    *          the uri to resolve
@@ -57,7 +72,9 @@ protected static Path resolveAgainstCWD(@NonNull Path path) {
    */
   @NonNull
   protected static URI resolveAgainstCWD(@NonNull URI uri) {
-    return ObjectUtils.notNull(getCurrentWorkingDirectory().toUri().resolve(uri.normalize()));
+    return uri.isAbsolute()
+        ? uri
+        : ObjectUtils.notNull(getCurrentWorkingDirectory().toUri().resolve(uri.normalize()));
   }
 
   /**

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

@@ -17,6 +17,9 @@
 
 /**
  * A service that loads commands using SPI.
+ * <p>
+ * This class implements the singleton pattern to ensure a single instance of
+ * the command service is used throughout the application.
  *
  * @see ServiceLoader for more information
  */
@@ -36,8 +39,12 @@ public static CommandService getInstance() {
 
   /**
    * Construct a new service.
+   * <p>
+   * Initializes the ServiceLoader for ICommand implementations.
+   * <p>
+   * This constructor is private to enforce the singleton pattern.
    */
-  public CommandService() {
+  private CommandService() {
     ServiceLoader<ICommand> loader = ServiceLoader.load(ICommand.class);
     assert loader != null;
     this.loader = loader;

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

@@ -24,6 +24,9 @@ public interface ExtraArgument {
    */
   @NonNull
   static ExtraArgument newInstance(@NonNull String name, boolean required) {
+    if (name.isBlank()) {
+      throw new IllegalArgumentException("name cannot be empty or blank");
+    }
     return new DefaultExtraArgument(name, required);
   }