Package org.egothor.methodatlas

Class MethodAtlasApp

java.lang.Object
org.egothor.methodatlas.MethodAtlasApp
public final class MethodAtlasApp extends Object
Command-line application for scanning Java test sources, extracting JUnit test metadata, and optionally enriching the emitted results with AI-generated security tagging suggestions.

The application traverses one or more directory roots, parses matching source files using JavaParser, identifies supported JUnit Jupiter test methods, and emits one output record per discovered test method. File selection matches source files whose names end with the configured suffix (default: Test.java).

Source-Derived Metadata

For each discovered test method, the application reports:

  • fully qualified class name
  • method name
  • inclusive line count of the method declaration
  • JUnit @Tag values declared on the method

AI Enrichment

When AI support is enabled, the application submits each discovered test class to an AiSuggestionEngine and merges the returned method-level suggestions into the emitted output.

Manual AI Workflow

Operators who cannot access an AI API directly can use the two-phase manual workflow:

  1. Prepare phase (-manual-prepare): the application scans test sources and writes one work file per class to the specified directory. Each work file contains operator instructions and the full AI prompt (with class source embedded). No CSV output is produced in this phase.
  2. Consume phase (-manual-consume): the application reads operator-saved AI response files (<stem>.response.txt) from the response directory and produces the final enriched CSV. Classes whose response file is absent receive empty AI columns.

Supported Command-Line Options

  • -config <path> — loads default values from a YAML configuration file; command-line flags override YAML values
  • -plain — emits plain text output instead of CSV
  • -sarif — emits SARIF 2.1.0 JSON output
  • -ai — enables AI-based enrichment
  • -ai-provider <provider> — selects the AI provider
  • -ai-model <model> — selects the provider-specific model
  • -ai-base-url <url> — overrides the provider base URL
  • -ai-api-key <key> — supplies the AI API key directly
  • -ai-api-key-env <name> — resolves the AI API key from an environment variable
  • -ai-taxonomy <path> — loads taxonomy text from an external file
  • -ai-taxonomy-mode <mode> — selects the built-in taxonomy variant
  • -ai-max-class-chars <count> — limits class source size submitted to AI
  • -ai-timeout-sec <seconds> — sets the AI request timeout
  • -ai-max-retries <count> — sets the retry limit for AI operations
  • -ai-confidence — requests a confidence score for each AI security classification; adds an ai_confidence column to the output
  • -ai-cache <path> — loads a previous scan CSV produced with -content-hash -ai as an AI result cache; classes whose content_hash matches a cache entry are classified without an API call; changed and new classes are classified normally
  • -file-suffix <suffix> — matches source files by name suffix (default: Test.java); may be repeated to match multiple patterns, e.g. -file-suffix Test.java -file-suffix IT.java; the first occurrence replaces the default
  • -test-annotation <name> — recognises methods annotated with name as test methods; may be repeated; the first occurrence replaces the JVM provider's default set (JUnit 5 Test, ParameterizedTest, RepeatedTest, TestFactory, TestTemplate)
  • -emit-metadata — emits # key: value comment lines before the header row describing the tool version, scan timestamp, and taxonomy configuration
  • -apply-tags — instead of emitting a report, writes AI-generated @DisplayName and @Tag annotations back to the scanned source files; requires AI enrichment to be enabled
  • -content-hash — includes a SHA-256 fingerprint of each class source as a content_hash column in CSV/plain output and as a SARIF property; useful for detecting which classes changed between scans
  • -security-only — suppresses non-security methods from the output; only methods whose AI classification (or override) has securityRelevant=true are emitted; requires AI enrichment or a classification override file to have any effect
  • -manual-prepare <workdir> <responsedir> — runs the manual AI prepare phase, writing work files to workdir and empty response stubs to responsedir; the two paths may be identical
  • -manual-consume <workdir> <responsedir> — runs the manual AI consume phase, reading response files from responsedir and emitting the final enriched CSV
  • -diff <before.csv> <after.csv> — compares two MethodAtlas scan outputs and emits a delta report showing added, removed, and modified test methods; all other flags are ignored when -diff is present
  • -apply-tags-from-csv <path> — instead of emitting a report, applies the annotation decisions recorded in the reviewed CSV back to the source files; the CSV is treated as a complete desired-state specification: every test method's @Tag set and @DisplayName are driven entirely by the corresponding CSV row
  • -mismatch-limit <n> — when used with -apply-tags-from-csv, aborts without modifying any source file if the number of mismatches between the CSV and the current source tree reaches or exceeds n; -1 (the default) logs mismatches as warnings and proceeds
  • -emit-source-root — adds a source_root column to CSV output and a SRCROOT= token to plain-text output, identifying which scan root each record originated from; essential in multi-root or monorepo projects where the same fully qualified class name can appear under different source trees (e.g. module-a/src/test/java/ and module-b/src/test/java/); has no effect on SARIF or GitHub Annotations output

Any remaining non-option arguments are interpreted as root paths to scan. If no scan path is supplied, the current working directory is scanned.

Exit Codes

  • 0 — all files processed successfully
  • 1 — one or more files could not be parsed or processed
See Also:

  • Method Details

    • main

      public static void main(String[] args) throws IOException
      Program entry point.

      Delegates all work to run(String[], PrintWriter). Exits with a non-zero status code if any source file could not be processed.

      Parameters:
      args - command-line arguments
      Throws:
      IOException - if traversal of a configured file tree fails
      IllegalArgumentException - if an option is unknown, if a required option value is missing, or if an option value cannot be parsed
      IllegalStateException - if AI support is enabled but the AI engine cannot be created successfully