Package org.egothor.methodatlas

Class ClassificationOverride

java.lang.Object
org.egothor.methodatlas.ClassificationOverride
public final class ClassificationOverride extends Object
Applies human-authored classification overrides to AI-generated (or absent) security classification results.

Purpose

AI classification is a best-effort semantic analysis. In practice, a provider may under-classify a method that is clearly security-relevant, over-classify a utility method, assign incorrect tags, or produce a rationale that does not meet audit requirements. ClassificationOverride allows a team or individual to record corrections in a persistent YAML file so that re-running MethodAtlas does not lose those decisions.

Overrides are also the only mechanism for adding AI-style enrichment columns to methods that are not going through live AI or the manual workflow — for example, when running in static inventory mode with a trusted set of hand-reviewed classifications.

Override File Format

The override file is a YAML document with a top-level overrides list. Each entry targets either a single method (when method is present) or every method in a class (when method is absent). Only the fields you specify are overridden; unspecified fields retain their AI-derived or default values. 

 overrides:

   # Correct a false positive: AI classified this as security-relevant but it is not.
   - fqcn: com.acme.util.DateFormatterTest
     method: format_returnsIso8601
     securityRelevant: false
     reason: "Date formatting only — no security property tested"
     note: "Reviewed 2026-04-24 by alice"

   # Correct a false negative: AI missed this security-critical test.
   - fqcn: com.acme.crypto.AesGcmTest
     method: roundTrip_encryptDecrypt
     securityRelevant: true
     tags: [security, crypto]
     displayName: "SECURITY: crypto — AES-GCM round-trip"
     reason: "Verifies ciphertext integrity under AES-GCM — critical crypto test"
     note: "Confirmed by security team 2026-04-20"

   # Classify all methods in a class (no 'method' field = class-level override).
   - fqcn: com.acme.auth.Oauth2FlowTest
     securityRelevant: true
     tags: [security, auth]
     note: "Entire class covers OAuth 2.0 flow — AI taxonomy too narrow"

Field Reference

  • fqcn — fully qualified class name; required; must match the fqcn column in MethodAtlas output
  • method — method name; optional; when absent the override applies to all methods in the class; method-level overrides take precedence over class-level overrides for the same class
  • securityRelevant — true or false; optional; when absent the AI decision (or default false) is kept
  • tags — YAML list of security taxonomy tags; optional; when absent the AI tags (or an empty list) are kept
  • displayName — suggested @DisplayName value; optional; when absent the AI-suggested name (or null) is kept
  • reason — human-readable rationale for the classification; optional; when absent the AI rationale (or null) is kept
  • note — free-text annotation for human use only; never appears in any MethodAtlas output; useful for recording reviewer identity, date, and decision context

Confidence Behaviour

When any override field is applied to a method, the output confidence value is set to 1.0 if the method is classified as security-relevant, or 0.0 otherwise. This reflects the fact that a human review provides higher certainty than any AI score and ensures that confidence-based filters (such as --min-confidence) do not suppress human-verified results.

Integration Points

ClassificationOverride works in all MethodAtlas operating modes:

  • Live AI mode (-ai) — AI result is obtained first; overrides are applied on top.
  • Manual AI workflow (-manual-consume) — operator-filled responses are loaded first; overrides are applied on top.
  • Static mode (no -ai) — no AI result exists; any override that marks a method as security-relevant synthesizes a full AiMethodSuggestion from the override fields alone.

Unknown Methods

Override entries that reference a method name not found in the parsed source are silently ignored. This means old entries remain harmless after methods are renamed or deleted, and the file does not need to be pruned after refactoring.

See Also:

  • Method Details

    • empty

      public static ClassificationOverride empty()
      Returns an empty override set that leaves all classifications unchanged.

      Use this when no override file is configured.

      Returns:
      shared empty instance

    • load

      public static ClassificationOverride load(Path path) throws IOException
      Loads an override file from the given path.

      The file must be a YAML document with a top-level overrides list. See the class Javadoc for the expected structure. Unknown YAML fields are silently ignored, so the file can carry additional human-readable metadata beyond the recognized fields without causing parse errors.

      Parameters:
      path - path to the YAML override file
      Returns:
      loaded override set; never null
      Throws:
      IOException - if the file cannot be read or contains invalid YAML

    • hasOverridesFor

      public boolean hasOverridesFor(String fqcn)
      Returns true if at least one override entry targets the given class.

      This can be used to decide whether apply(java.lang.String, org.egothor.methodatlas.ai.AiClassSuggestion, java.util.List<java.lang.String>) should be called even when no AI suggestion was produced (e.g. in static mode), avoiding unnecessary processing for classes that have no overrides.

      Parameters:
      fqcn - fully qualified class name to check
      Returns:
      true if overrides exist for fqcn

    • apply

      public AiClassSuggestion apply(String fqcn, AiClassSuggestion suggestion, List<String> methodNames)
      Applies override entries to an existing AI classification result.

      The methodNames list must contain the canonical method names as discovered by the MethodAtlas parser. It drives the set of methods for which output records are produced; override entries targeting method names absent from this list are silently skipped.

      When suggestion is null and no overrides target fqcn, this method returns null unchanged so that the absence of AI data is preserved correctly in the output.

      When suggestion is null but at least one override targets fqcn, a synthetic AiClassSuggestion is constructed from the override fields. Methods not targeted by any override will have securityRelevant=false and empty tag/reason fields in the synthesized result.

      Parameters:
      fqcn - fully qualified class name of the class being processed
      suggestion - AI classification result to modify; may be null
      methodNames - names of all test methods found by the parser in this class, in discovery order
      Returns:
      modified or synthesized classification; null only when both suggestion is null and no overrides target fqcn