CliArgs.java

package org.egothor.methodatlas;

import java.io.IOException;

import java.nio.file.Files;

import java.nio.file.Path;

import java.nio.file.Paths;

import java.time.Duration;

import java.util.ArrayList;

import java.util.LinkedHashMap;

import java.util.LinkedHashSet;

import java.util.List;

import java.util.Locale;

import java.util.Map;

import java.util.Set;

import org.egothor.methodatlas.ai.AiOptions;

import org.egothor.methodatlas.emit.OutputMode;

import org.egothor.methodatlas.ai.AiProvider;

import org.egothor.methodatlas.ai.PromptTemplateException;

import org.egothor.methodatlas.ai.PromptTemplateKind;

import org.egothor.methodatlas.ai.PromptTemplateSet;

import org.egothor.methodatlas.ai.PromptTemplateValidator;

/**

 * Parses command-line arguments into a {@link CliConfig}.

 *

 * <p>

 * This class centralises all argument-parsing logic for the MethodAtlas

 * application. It is intentionally separated from {@link MethodAtlasApp} to

 * keep each class focused and below the project's cyclomatic-complexity

 * threshold.

 * </p>

 *

 * <p>

 * When a {@code -config <file>} argument is present it is processed first

 * (via a pre-scan) so that the YAML file provides default values before

 * individual command-line flags are evaluated. Command-line flags always take

 * precedence over values from the YAML configuration file.

 * </p>

 *

 * <p>

 * This class is a non-instantiable utility holder.

 * </p>

 *

 * @see CliConfig

 * @see MethodAtlasApp

 */

@SuppressWarnings({"PMD.CyclomaticComplexity", "PMD.LongVariable"})

final class CliArgs {

    private static final String DEFAULT_FILE_SUFFIX = "java:Test.java";

    private static final String FLAG_CONFIG = "-config";

    private static final String FLAG_AI_CACHE = "-ai-cache";

    private static final String FLAG_AI_CACHE_OUT = "-ai-cache-out";

    private static final String FLAG_DRIFT_DETECT = "-drift-detect";

    private static final String FLAG_EMIT_SOURCE_ROOT = "-emit-source-root";

    private static final String FLAG_INCLUDE_NON_SECURITY = "-include-non-security";

    private static final String FLAG_SARIF_OMIT_SCORES = "-sarif-omit-scores";

    private static final String FLAG_APPLY_TAGS_FROM_CSV = "-apply-tags-from-csv";

    private static final String FLAG_PROMOTE_AI = "-promote-ai";

    private static final String FLAG_MISMATCH_LIMIT = "-mismatch-limit";

    private static final String FLAG_MIN_CONFIDENCE = "-min-confidence";

    private static final String FLAG_EMIT_RECEIPT = "-emit-receipt";

    private static final String FLAG_RECEIPT_FILE = "-receipt-file";

    private static final String FLAG_EMIT_COVERAGE = "-emit-coverage";

    private static final String FLAG_COVERAGE_FILE = "-coverage-file";

    private static final String FLAG_COVERAGE_MAPPING = "-coverage-mapping";

    private static final String FLAG_EVIDENCE_PACK = "-evidence-pack";

    private static final String FLAG_EVIDENCE_PACK_DIR = "-evidence-pack-dir";

    private static final String FLAG_EVIDENCE_PACK_OVERWRITE = "-evidence-pack-overwrite";

    private static final String FLAG_EVIDENCE_PACK_KEYRING = "-evidence-pack-keyring";

    private static final String FLAG_EVIDENCE_PACK_KEYRING_ENV = "-evidence-pack-keyring-env";

    private static final String FLAG_EVIDENCE_PACK_KEY_ALIAS = "-evidence-pack-key-alias";

    private static final String FLAG_EVIDENCE_PACK_SIGN_ALGO = "-evidence-pack-sign-algo";

    private static final String FLAG_DETECT_SECRETS = "-detect-secrets";

    private static final String FLAG_SECRETS_INCLUDE = "-secrets-include";

    private static final String FLAG_SECRETS_RULES = "-secrets-rules";

    private static final String FLAG_SECRETS_OUT = "-secrets-out";

    private static final String FLAG_SECRETS_SEPARATE_LLM = "-secrets-separate-llm";

    private static final String FLAG_SECRETS_SHOW_VALUES = "-secrets-show-values";

    private static final String FLAG_SECRETS_ERROR_THRESHOLD = "-secrets-error-threshold";

    private static final String FLAG_SECRETS_WARNING_THRESHOLD = "-secrets-warning-threshold";

    private static final String FLAG_SECRETS_MIN_SCORE = "-secrets-min-score";

    private static final String FLAG_CLASSIFICATION_PROMPT = "-classification-prompt";

    private static final String FLAG_TRIAGE_PROMPT = "-triage-prompt";

    private static final String FLAG_DEDICATED_TRIAGE_PROMPT = "-dedicated-triage-prompt";

    /**

     * Prevents instantiation of this utility class.

     */

    /**

     * Parses command-line arguments into a structured configuration object.

     *

     * <p>

     * If a {@code -config <file>} argument is present it is loaded first and

     * its values seed the initial configuration. Subsequent command-line flags

     * override those defaults.

     * </p>

     *

     * <p>

     * <b>SARIF mode and security filtering:</b> when {@code -sarif} is selected

     * (or {@code outputMode: sarif} is set in YAML), the security-only filter is

     * applied automatically — only security-relevant methods are emitted. This

     * default exists because SARIF is consumed by GitHub Code Scanning and

     * equivalent security tooling that expects actionable security findings, not

     * an exhaustive inventory of all test methods. Use {@code -include-non-security}

     * to override this behaviour and include all methods in the SARIF document.

     * </p>

     *

     * <p>

     * The {@code -security-only} flag continues to work independently and applies

     * the same filter to CSV and plain-text output modes.

     * </p>

     *

     * @param args raw command-line arguments

     * @return parsed command-line configuration, or {@code null} when a

     *         validation error (for example {@code -emit-coverage} without

     *         {@code -coverage-mapping}) has already been reported to

     *         {@code stderr} and the caller should exit with a bad-arguments code

     * @throws IllegalArgumentException if an option value is missing, malformed,

     *                                  or unsupported, or if the config file

     *                                  cannot be read

     */

    @SuppressWarnings({"PMD.AvoidReassigningLoopVariables", "PMD.CyclomaticComplexity",

            "PMD.NPathComplexity", "PMD.NcssCount", "PMD.CognitiveComplexity"})

    /* default */ static CliConfig parse(String... args) {

        // Pre-scan for -config to load YAML defaults before processing other flags.

        // Seed initial values from YAML (command-line flags will override these).

        }

        }

        // -promote-ai lets the apply-from-csv engine write unvalidated AI output

        // into source where curated columns are blank — risky and off by default.

        // Seeded from YAML (promoteAi:) and overridable by the CLI flag.

        // Credential-detection flags — all off/null/default until -detect-secrets is given.

        // Optional prompt-template override files (CLI overrides YAML). Resolved into

        // an effective PromptTemplateSet after parsing, validated fail-fast.

        // Tracks whether the first CLI -file-suffix has been seen; when it is,

        // subsequent -file-suffix values are appended rather than replacing defaults.

            }

            }

            }

                case "-file-suffix" -> {

                        // First CLI -file-suffix replaces YAML defaults

                    }

                case "-property" -> {

                                "Invalid -property value: '" + kv + "'; expected key=value format");

                    }

                case FLAG_RECEIPT_FILE -> {

                                "-receipt-file path must not be blank");

                    }

                case FLAG_COVERAGE_FILE -> {

                                "-coverage-file path must not be blank");

                    }

                case FLAG_COVERAGE_MAPPING -> {

                                "-coverage-mapping path must not be blank");

                    }

                case FLAG_EVIDENCE_PACK_KEYRING ->

                case FLAG_SECRETS_ERROR_THRESHOLD ->

                case FLAG_SECRETS_WARNING_THRESHOLD ->

                case FLAG_SECRETS_MIN_SCORE ->

                case FLAG_DEDICATED_TRIAGE_PROMPT ->

                case "-manual-prepare" -> {

                case "-manual-consume" -> {

                default -> {

                    }

                }

            }

        }

        }

        // SARIF is consumed by security tooling that expects findings, not a full

        // test inventory. Apply the security-only filter implicitly unless the

        // caller has explicitly opted in to the full-inventory form.

        }

        // Coverage mode requires a user-authored mapping file; the tool ships no

        // built-in mapping. Reject the request with a structured stderr message

        // pointing at the reference template; the caller (MethodAtlasApp) maps

        // the null return value to exit code 2.

        }

        // Resolve and validate any prompt-template overrides, then hand the effective

        // set to the AI options so both prompt rendering and receipt hashing use it.

                securityOnly, aiCacheFile, driftDetect, applyTagsFromCsvFile, mismatchLimit, emitSourceRoot,

                sarifOmitScores, minConfidence, emitReceipt, receiptFile,

                emitCoverage, coverageFile, coverageMappingFile,

                evidencePackFramework, evidencePackDir,

                evidencePackOverwrite, evidencePackKeyringFile, evidencePackKeyringEnv,

                evidencePackKeyAlias, evidencePackSignAlgo, verbose, promoteAi,

                detectSecrets, secretsInclude, secretsRules,

                secretsOut, secretsSeparateLlm, secretsShowValues,

                secretsErrorThreshold, secretsWarningThreshold, secretsMinScore,

                aiCacheOut);

    }

    // -------------------------------------------------------------------------

    // YAML config helpers

    // -------------------------------------------------------------------------

    /**

     * Pre-scans {@code args} for a {@code -config <file>} argument and loads the

     * YAML file if found.

     *

     * @param args raw command-line arguments

     * @return parsed YAML config, or {@code null} when no {@code -config} flag is

     *         present

     * @throws IllegalArgumentException if the config file cannot be read

     */

    private static YamlConfig.YamlConfigFile loadYamlConfigFromArgs(String... args) {

                try {

                }

            }

        }

    }

    /**

     * Derives the initial {@link OutputMode} from a loaded YAML config.

     *

     * @param yamlConfig YAML config, or {@code null}

     * @return resolved output mode; defaults to {@link OutputMode#CSV}

     */

    private static OutputMode resolveOutputModeFromYaml(YamlConfig.YamlConfigFile yamlConfig) {

        }

        };

    }

    /**

     * Seeds the AI options builder from YAML configuration values.

     *

     * @param builder   AI options builder to update

     * @param aiConfig  AI section of the YAML config; never {@code null}

     */

    @SuppressWarnings("PMD.NPathComplexity")

    private static void applyYamlAiConfig(AiOptions.Builder builder, YamlConfig.YamlAiConfig aiConfig) {

        }

        }

        }

        }

        }

        }

        }

        }

        }

        }

        }

        }

        }

    /**

     * Reads an AI prompt-template override path from the YAML config, if present.

     *

     * @param yamlConfig loaded YAML config, or {@code null}

     * @param which      one of {@code "classification"}, {@code "triage"},

     *                   {@code "dedicatedTriage"}

     * @return the configured path, or {@code null} when unset

     */

    private static Path yamlAiPromptPath(YamlConfig.YamlConfigFile yamlConfig, String which) {

        }

        };

    }

    /**

     * Builds the effective {@link PromptTemplateSet} from the built-in defaults plus

     * any operator overrides, validating each override fail-fast.

     *

     * @param classification  classification template file, or {@code null}

     * @param triageAppendix   folded triage-appendix template file, or {@code null}

     * @param dedicatedTriage standalone triage template file, or {@code null}

     * @return the resolved template set; never {@code null}

     * @throws IllegalArgumentException if an override file cannot be read or fails

     *                                  structural validation

     */

    private static PromptTemplateSet resolvePromptTemplates(Path classification, Path triageAppendix,

            Path dedicatedTriage) {

    }

    /**

     * Loads, validates, and applies a single prompt-template override.

     *

     * @param set  the set to extend; must not be {@code null}

     * @param kind the kind the file overrides; must not be {@code null}

     * @param file the override file, or {@code null} to leave the kind unchanged

     * @return the (possibly extended) set; never {@code null}

     * @throws IllegalArgumentException if the file cannot be read or is invalid

     */

    private static PromptTemplateSet applyPromptOverride(PromptTemplateSet set, PromptTemplateKind kind, Path file) {

        }

        String body;

        try {

        try {

    }

    // -------------------------------------------------------------------------

    // AI argument helper

    // -------------------------------------------------------------------------

    /**

     * Applies a single AI-related command-line argument to the builder.

     *

     * <p>

     * Handles all {@code -ai*} flags. Returns the updated argument index so

     * the caller's loop counter stays consistent when the flag consumes an

     * additional value token.

     * </p>

     *

     * @param arg     the flag token being processed

     * @param args    full argument array

     * @param i       current position in {@code args}

     * @param builder AI options builder to update

     * @return updated value of {@code i} after consuming any argument value

     * @throws IllegalArgumentException if a required value token is missing or

     *                                  the flag is unrecognised

     */

    private static int applyAiArg(String arg, String[] args, int i, AiOptions.Builder builder) {

            case "-ai-provider" ->

            case "-ai-taxonomy-mode" ->

            case "-ai-timeout-sec" ->

        }

    }

    /**

     * Validates and parses the {@code -min-confidence} argument value.

     *

     * @param value raw string value from the command line

     * @return parsed confidence threshold in the range {@code [0.0, 1.0]}

     * @throws IllegalArgumentException if the value is outside {@code [0.0, 1.0]}

     */

    private static double parseConfidenceThreshold(String value) {

                    "-min-confidence value must be between 0.0 and 1.0, got: " + parsed);

        }

    }

    /**

     * Returns the argument value following an option token.

     *

     * @param args   full command-line argument array

     * @param index  index of the expected option value

     * @param option option whose value is being retrieved

     * @return argument value at {@code index}

     * @throws IllegalArgumentException if {@code index} is outside the bounds of

     *                                  {@code args}

     */

    private static String nextArg(String[] args, int index, String option) {

        }

    }

}

Mutations

1.1
Location : parse
Killed by : none removed conditional - replaced equality check with false → SURVIVED Covering tests

2.2
Location : parse
Killed by : org.egothor.methodatlas.MethodAtlasAppContentHashTest.[engine:junit-jupiter]/[class:org.egothor.methodatlas.MethodAtlasAppContentHashTest]/[method:yamlConfig_contentHashFalse_noHashColumn(java.nio.file.Path)] removed conditional - replaced equality check with true → KILLED

3.3
Location : parse
Killed by : org.egothor.methodatlas.CliArgsTest.[engine:junit-jupiter]/[class:org.egothor.methodatlas.CliArgsTest]/[method:parse_unknownAiFlag_throwsIllegalArgumentException()] removed conditional - replaced equality check with true → KILLED

4.4
Location : parse
Killed by : none removed conditional - replaced equality check with false → SURVIVED Covering tests

2.2
Location : parse
Killed by : none removed conditional - replaced equality check with false → SURVIVED Covering tests

3.3
Location : parse
Killed by : org.egothor.methodatlas.CliArgsTest.[engine:junit-jupiter]/[class:org.egothor.methodatlas.CliArgsTest]/[method:parse_unknownAiFlag_throwsIllegalArgumentException()] removed conditional - replaced equality check with true → KILLED

4.4
Location : parse
Killed by : none removed conditional - replaced equality check with false → SURVIVED Covering tests

2.2
Location : parse
Killed by : none removed conditional - replaced equality check with false → SURVIVED Covering tests

3.3
Location : parse
Killed by : org.egothor.methodatlas.CliArgsTest.[engine:junit-jupiter]/[class:org.egothor.methodatlas.CliArgsTest]/[method:parse_unknownAiFlag_throwsIllegalArgumentException()] removed conditional - replaced equality check with true → KILLED

4.4
Location : parse
Killed by : none removed conditional - replaced equality check with false → SURVIVED Covering tests

1.1
Location : parse
Killed by : none removed conditional - replaced equality check with true → SURVIVED Covering tests

2.2
Location : parse
Killed by : org.egothor.methodatlas.CliArgsTest.[engine:junit-jupiter]/[class:org.egothor.methodatlas.CliArgsTest]/[method:parse_unknownAiFlag_throwsIllegalArgumentException()] removed conditional - replaced equality check with true → KILLED

3.3
Location : parse
Killed by : none removed conditional - replaced equality check with false → SURVIVED Covering tests

4.4
Location : parse
Killed by : none removed conditional - replaced equality check with false → SURVIVED Covering tests

1.1
Location : parse
Killed by : none removed conditional - replaced equality check with false → SURVIVED Covering tests

2.2
Location : parse
Killed by : none removed conditional - replaced equality check with false → SURVIVED Covering tests