ApplyTagsFromCsvEngine.java

package org.egothor.methodatlas;

import java.io.IOException;

import java.io.PrintWriter;

import java.nio.file.Files;

import java.nio.file.Path;

import java.nio.file.Paths;

import java.util.ArrayList;

import java.util.HashMap;

import java.util.LinkedHashMap;

import java.util.LinkedHashSet;

import java.util.List;

import java.util.Map;

import java.util.Set;

import java.util.logging.Level;

import java.util.logging.Logger;

import java.util.stream.Stream;

import org.egothor.methodatlas.api.ScanRecord;

import org.egothor.methodatlas.emit.DeltaReport;

import org.egothor.methodatlas.api.SourcePatcher;

/**

 * Engine that applies annotation changes to source files driven by a

 * reviewed MethodAtlas CSV export.

 *

 * <p>

 * The {@code -apply-tags-from-csv} workflow allows a security or development

 * team to review MethodAtlas output in a CSV file, adjust the {@code tags} and

 * {@code display_name} columns to reflect the desired annotation state, and

 * then replay those decisions back into the source code. The CSV acts as a

 * <em>desired-state specification</em>: after a successful run, re-running

 * MethodAtlas on the same source tree would reproduce an equivalent CSV.

 * </p>

 *

 * <h2>Invariant</h2>

 * <p>

 * The CSV must be complete — it must contain one row for every test method

 * currently present in the scanned source tree (matching the configured file

 * suffixes and test annotations). A method that appears in the source but not

 * in the CSV, or in the CSV but not in the source, constitutes a

 * <em>mismatch</em> and is reported as a warning. When a mismatch limit is

 * configured, the engine aborts without making any source changes if the

 * number of mismatches reaches or exceeds that limit.

 * </p>

 *

 * <h2>What is applied</h2>

 * <ul>

 *   <li>{@code tags} column — the exact set of {@code @Tag} annotations desired

 *       on the method; existing tags not in the list are removed, missing tags

 *       are added</li>

 *   <li>{@code display_name} column — the desired {@code @DisplayName} text;

 *       empty means "remove any existing {@code @DisplayName}"</li>

 * </ul>

 *

 * <h2>AI-column promotion (risky, opt-in)</h2>

 * <p>

 * <strong>Not recommended.</strong> When the caller passes {@code promoteAi},

 * the engine falls back to the AI-suggested {@code ai_tags} /

 * {@code ai_display_name} columns for any method whose curated {@code tags} /

 * {@code display_name} column is blank, and writes that raw AI suggestion into

 * source. Promotion is per-field and independent, and only fires when the

 * curated value is blank <em>and</em> a non-blank AI value is present.

 * </p>

 * <p>

 * This mode deliberately bypasses the human review step that the

 * apply-from-csv workflow exists to enforce — AI output reaches source without

 * validation. It should not be used unless the promotion has been rethought and

 * approved for the target environment. Every promoted value is counted and

 * reported on the completion summary line (and itemised under {@code -verbose})

 * so the run log records exactly which source writes originated from AI rather

 * than from a reviewed column.

 * </p>

 *

 * <h2>Mismatch handling</h2>

 * <p>

 * If {@code mismatchLimit} is {@code -1} (no limit), mismatches are logged as

 * warnings and the engine proceeds. If {@code mismatchLimit} is {@code >= 0},

 * the engine first counts mismatches and aborts with exit code {@code 1} when

 * the count is {@code >= mismatchLimit}. Setting the limit to {@code 1}

 * therefore causes any mismatch to abort the run without touching source files.

 * </p>

 *

 * <h2>Languages supported for write-back</h2>

 * <p>

 * Source write-back is only available for languages whose discovery plugin

 * ships a {@link SourcePatcher} implementation — currently

 * <strong>Java</strong> (JUnit&nbsp;5 / 4 / TestNG) and <strong>C#</strong>

 * (xUnit / NUnit / MSTest). Files whose language has no patcher are skipped

 * during the apply phase; a per-file notice is written to {@code log} and

 * the aggregate skip count is appended to the completion summary line.

 * These files do not appear in the source-method index built by

 * {@link SourcePatcher#discoverMethodsByClass(Path)} either, so rows in the

 * CSV that describe tests in unsupported languages will be reported as

 * mismatches.

 * </p>

 *

 * <p>

 * This class is a non-instantiable utility holder.

 * </p>

 *

 * @see SourcePatcher

 * @see MethodAtlasApp

 */

public final class ApplyTagsFromCsvEngine {

    /**

     * Applies annotation changes from a reviewed CSV to source files.

     *

     * <p>

     * Source-method inventory (for mismatch detection) and source file write-back

     * are both delegated to the supplied {@link SourcePatcher} implementations via

     * {@link SourcePatcher#discoverMethodsByClass(java.nio.file.Path)} and

     * {@link SourcePatcher#patch(java.nio.file.Path, java.util.Map, java.util.Map,

     * java.io.PrintWriter)} respectively.

     * </p>

     *

     * @param csvFile         path to a MethodAtlas CSV produced with a previous

     *                        scan and reviewed by the team; must contain

     *                        {@code fqcn}, {@code method}, {@code tags}, and

     *                        {@code display_name} columns

     * @param roots           source root directories to scan for test files

     * @param mismatchLimit   maximum number of mismatches before aborting;

     *                        {@code -1} means no limit (warn and proceed)

     * @param patchers        list of configured {@link SourcePatcher} implementations

     * @param log             writer for progress and summary output

     * @param verbose         when {@code true}, print the CSV desired-state keys,

     *                        the keys discovered in the source tree, and the

     *                        key-by-key match result to {@code log}, so a run that

     *                        reports zero updates can be diagnosed (for example a

     *                        fully qualified class name or working-directory

     *                        mismatch between the CSV and the scanned source)

     * @param promoteAi       <strong>risky, not recommended</strong>: when

     *                        {@code true}, the engine falls back to the

     *                        {@code ai_tags} / {@code ai_display_name} columns for

     *                        any method whose curated {@code tags} /

     *                        {@code display_name} column is blank, writing the raw

     *                        AI suggestion into source without human review;

     *                        every promoted value is counted on the summary line

     *                        and itemised under {@code verbose}

     * @return {@code 0} on success, {@code 1} when the mismatch limit is

     *         exceeded or a fatal error occurs

     * @throws IOException if the CSV file or source files cannot be read or

     *                     written

     */

    public static int apply(Path csvFile, List<Path> roots,

            int mismatchLimit, List<SourcePatcher> patchers, PrintWriter log, boolean verbose,

            boolean promoteAi)

            throws IOException {

        // ── Step 1: load the desired-state CSV ────────────────────────────────

        }

                        + "will be filled from ai_tags/ai_display_name (unvalidated AI output)");

            }

        }

        // ── Step 2: scan source to build current method inventory ─────────────

        // Build a map from source file path → list of (fqcn, methodName) pairs

        // by asking each SourcePatcher to discover methods in supported files.

        }

        // ── Step 3: compute mismatches (symmetric difference) ─────────────────

        }

        // ── Step 4: enforce mismatch limit ────────────────────────────────────

        }

        // ── Step 5: warn about mismatches (no limit, or below limit) ──────────

        // ── Step 6: apply changes file by file ────────────────────────────────

    }

    private static int reportMismatchesAndAbort(Set<String> inCsvNotSource, Set<String> inSourceNotCsv,

            int mismatchCount, int mismatchLimit, PrintWriter log) {

                + " mismatch(es) >= limit " + mismatchLimit + ". No source files were modified.");

    }

    private static void warnMismatches(Set<String> inCsvNotSource, Set<String> inSourceNotCsv) {

        }

    private static int applyFilesLoop(Map<Path, List<MethodKey>> sourceIndex,

            Map<String, ScanRecord> desiredState, List<SourcePatcher> patchers,

            int mismatchCount, PrintWriter log, boolean verbose, boolean promoteAi) {

                    desiredState, patchers, log, verbose, promoteAi);

            }

            }

            }

        // Capacity 320 comfortably covers the worst-case message:

        //   "Apply-tags-from-csv complete: <int> change(s) in <int> file(s);

        //    <int> mismatch(es) skipped. <int> file(s) skipped (no source

        //    write-back support for the language). <int> value(s) promoted from

        //    AI columns (unvalidated — used with -promote-ai)."

        }

        }

                    + "the keys discovered in the source, and the key-by-key match result — the "

                    + "usual cause is a fully qualified class name or working-directory mismatch.");

        }

    }

    /**

     * Applies the desired state to a single source file and reports the outcome.

     *

     * @param path         source file to patch

     * @param methods      methods discovered in {@code path}

     * @param desiredState CSV desired state keyed by {@code <fqcn>::<method>}

     * @param patchers     configured source patchers

     * @param log          progress writer

     * @param verbose      whether to print per-file diagnostics

     * @param promoteAi    whether to fall back to the AI columns for blank

     *                     curated values (risky; see the class Javadoc)

     * @return the outcome (change count, promotion count, language-skip flag,

     *         error flag)

     */

    private static FileOutcome processFile(Path path, List<MethodKey> methods,

            Map<String, ScanRecord> desiredState, List<SourcePatcher> patchers,

            PrintWriter log, boolean verbose, boolean promoteAi) {

            }

        }

            }

                    + " — source write-back is not supported for this language "

                    + "(currently Java and C# only)");

        }

                tagsToApply, displayNames, log, verbose);

                    + " with a desired display-name"

        }

        try {

            }

            }

        }

    }

    /**

     * Fills the {@code tagsToApply} and {@code displayNames} maps from the CSV

     * desired state for every method discovered in {@code path}, applying

     * AI-column promotion when {@code promoteAi} is set.

     *

     * <p>

     * The {@code displayNames} value carries the established three-way contract:

     * {@code null} (column absent) leaves {@code @DisplayName} untouched and is

     * therefore not put into the map; {@code ""} removes it; non-empty text sets

     * it. Promotion only substitutes an AI value when the curated value is blank

     * and a non-blank AI value is present, so the contract is preserved for

     * every method the operator curated by hand.

     * </p>

     *

     * @param path         source file being processed (used for verbose notices)

     * @param methods      methods discovered in {@code path}

     * @param desiredState CSV desired state keyed by {@code <fqcn>::<method>}

     * @param promoteAi    whether to fall back to the AI columns for blank values

     * @param tagsToApply  output map from method name to desired tag list

     * @param displayNames output map from method name to desired display name

     * @param log          progress writer for verbose per-promotion notices

     * @param verbose      whether to itemise each promotion

     * @return the number of values promoted from the AI columns

     */

    private static int collectDesiredState(Path path, List<MethodKey> methods,

            Map<String, ScanRecord> desiredState, boolean promoteAi,

            Map<String, List<String>> tagsToApply, Map<String, String> displayNames,

            PrintWriter log, boolean verbose) {

            }

            }

            }

            }

            }

    }

    /**

     * Resolves the desired tag list for a record, optionally promoting the

     * {@code ai_tags} column when the curated {@code tags} column is blank.

     *

     * @param record    CSV record for the method

     * @param promoteAi whether AI promotion is enabled

     * @return the resolved tag list and whether it came from the AI column

     */

    private static Resolved<List<String>> resolveTags(ScanRecord record, boolean promoteAi) {

        }

    }

    /**

     * Resolves the desired display name for a record, optionally promoting the

     * {@code ai_display_name} column when the curated {@code display_name} column

     * is blank.

     *

     * @param record    CSV record for the method

     * @param promoteAi whether AI promotion is enabled

     * @return the resolved display name and whether it came from the AI column

     */

    private static Resolved<String> resolveDisplayName(ScanRecord record, boolean promoteAi) {

        }

    }

    /**

     * Writes a per-promotion audit notice under {@code -verbose}.

     *

     * @param log     progress writer

     * @param verbose whether verbose output is enabled

     * @param path    source file being processed

     * @param mk      method whose value was promoted

     * @param detail  short description of the promoted field

     */

    private static void logPromotion(PrintWriter log, boolean verbose, Path path,

            MethodKey mk, String detail) {

        }

    /**

     * A resolved desired-state value paired with whether it was promoted from an

     * AI column rather than taken from a curated column.

     *

     * @param <T>      the value type ({@code List<String>} for tags,

     *                 {@code String} for display name)

     * @param value    the resolved value; may be {@code null} for display name

     *                 when the column was absent

     * @param promoted {@code true} when the value came from an AI column

     */

    }

    /**

     * Outcome of patching one source file: the number of changes written, the

     * number of values promoted from AI columns, and whether the file was

     * skipped for lack of a {@link SourcePatcher} or failed with an I/O error.

     *

     * @param changes  number of annotation changes written (zero when none applied)

     * @param promoted number of desired-state values sourced from the AI columns

     * @param skipped  {@code true} when skipped because no patcher supports the language

     * @param error    {@code true} when patching threw an {@link IOException}

     */

        private static FileOutcome forSkip() {

        }

        private static FileOutcome forError() {

        }

        private static FileOutcome forChanges(int changes, int promoted) {

        }

    }

    private static boolean hasRelevantMethod(List<MethodKey> methods, Map<String, ScanRecord> desiredState) {

            }

    }

    /**

     * Scans source roots and builds an index mapping each source file to the

     * list of (FQCN, method) pairs for all test methods it contains.

     *

     * <p>

     * Each supported source file is passed to

     * {@link SourcePatcher#discoverMethodsByClass(Path)} to obtain the actual

     * test-method inventory. This gives the correct FQCN–method pairs

     * regardless of whether the source tree uses the standard

     * {@code package/to/ClassName.java} directory structure.

     * </p>

     *

     * @param roots    source root directories

     * @param patchers list of configured patchers used to identify supported files

     * @return map from source file path to list of {@link MethodKey} entries;

     *         never {@code null}

     * @throws IOException if a file tree cannot be traversed

     */

    @SuppressWarnings("PMD.AvoidInstantiatingObjectsInLoops")

    private static Map<Path, List<MethodKey>> buildSourceIndex(

            List<Path> roots,

            List<SourcePatcher> patchers) throws IOException {

            }

                    }

                    // Ask the patcher to discover test methods in this file

                    }

    }

    /**

     * Prints, under {@code -verbose}, the run context and the complete set of

     * desired-state keys loaded from the CSV.

     *

     * @param log          progress writer

     * @param csvFile      reviewed CSV path

     * @param roots        configured scan roots

     * @param desiredState CSV-derived desired state keyed by {@code <fqcn>::<method>}

     */

    private static void logVerboseHeader(PrintWriter log, Path csvFile, List<Path> roots,

            Map<String, ScanRecord> desiredState) {

                + "); lookup format is <fqcn>::<method>:");

    /**

     * Prints, under {@code -verbose}, the keys discovered in the scanned source

     * tree (the right-hand side of the lookup).

     *

     * @param log         progress writer

     * @param sourceIndex source file to discovered methods

     * @param sourceKeys  flattened {@code <fqcn>::<method>} keys discovered in source

     */

    private static void logVerboseSource(PrintWriter log, Map<Path, List<MethodKey>> sourceIndex,

            Set<String> sourceKeys) {

                    + "Confirm the command is run from the correct directory and that the files "

                    + "use a language with source write-back support (Java, C#).");

        }

    /**

     * Prints, under {@code -verbose}, the key-by-key match result so an operator

     * can see exactly which CSV rows failed to line up with a source method.

     *

     * @param log             progress writer

     * @param desiredCount    number of CSV desired-state keys

     * @param inCsvNotSource  keys present in the CSV but absent from source

     * @param inSourceNotCsv  keys present in source but absent from the CSV

     */

    private static void logVerboseMatch(PrintWriter log, int desiredCount,

            Set<String> inCsvNotSource, Set<String> inSourceNotCsv) {

    private static String key(String fqcn, String method) {

    }

    /** Lightweight tuple holding a fully qualified class name and a method name. */

    }

}

Mutations

1.1
Location : apply
Killed by : none Replaced integer multiplication with division → SURVIVED Covering tests

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

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

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

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

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

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

5.5
Location : apply
Killed by : none changed conditional boundary → SURVIVED Covering tests

6.6
Location : apply
Killed by : org.egothor.methodatlas.MethodAtlasAppApplyTagsFromCsvTest.[engine:junit-jupiter]/[class:org.egothor.methodatlas.MethodAtlasAppApplyTagsFromCsvTest]/[method:applyTagsFromCsv_methodInSourceNotInCsvCountedAsMismatch(java.nio.file.Path)] removed conditional - replaced comparison check with false → KILLED

1.1
Location : apply
Killed by : none removed call to org/egothor/methodatlas/ApplyTagsFromCsvEngine::warnMismatches → SURVIVED Covering tests

1.1
Location : apply
Killed by : none replaced int return with 0 for org/egothor/methodatlas/ApplyTagsFromCsvEngine::apply → SURVIVED Covering tests

1.1
Location : reportMismatchesAndAbort
Killed by : none removed call to java/io/PrintWriter::println → SURVIVED Covering tests

1.1
Location : applyFilesLoop
Killed by : none Replaced integer addition with subtraction → SURVIVED Covering tests

1.1
Location : applyFilesLoop
Killed by : none Replaced integer addition with subtraction → SURVIVED Covering tests

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

2.2
Location : applyFilesLoop
Killed by : org.egothor.methodatlas.MethodAtlasAppApplyTagsFromCsvTest.[engine:junit-jupiter]/[class:org.egothor.methodatlas.MethodAtlasAppApplyTagsFromCsvTest]/[method:applyTagsFromCsv_zeroUpdates_printsVerboseHintWhenNotVerbose(java.nio.file.Path)] changed conditional boundary → KILLED

3.3
Location : applyFilesLoop
Killed by : org.egothor.methodatlas.MethodAtlasAppApplyTagsFromCsvTest.[engine:junit-jupiter]/[class:org.egothor.methodatlas.MethodAtlasAppApplyTagsFromCsvTest]/[method:applyTagsFromCsv_zeroUpdates_printsVerboseHintWhenNotVerbose(java.nio.file.Path)] removed conditional - replaced comparison check with true → KILLED

1.1
Location : applyFilesLoop
Killed by : none Changed increment from 1 to -1 → SURVIVED Covering tests

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

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

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

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

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

2.2
Location : applyFilesLoop
Killed by : none changed conditional boundary → SURVIVED Covering tests

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

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

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

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

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

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

4.4
Location : applyFilesLoop
Killed by : org.egothor.methodatlas.MethodAtlasAppApplyTagsFromCsvTest.[engine:junit-jupiter]/[class:org.egothor.methodatlas.MethodAtlasAppApplyTagsFromCsvTest]/[method:applyTagsFromCsv_zeroUpdates_printsVerboseHintWhenNotVerbose(java.nio.file.Path)] removed conditional - replaced equality check with false → KILLED

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

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

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

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

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

1.1
Location : processFile
Killed by : none removed call to java/io/PrintWriter::println → SURVIVED Covering tests

1.1
Location : lambda$processFile$0
Killed by : none replaced boolean return with true for org/egothor/methodatlas/ApplyTagsFromCsvEngine::lambda$processFile$0 → SURVIVED Covering tests

2.2
Location : lambda$processFile$0
Killed by : org.egothor.methodatlas.MethodAtlasAppApplyTagsFromCsvTest.[engine:junit-jupiter]/[class:org.egothor.methodatlas.MethodAtlasAppApplyTagsFromCsvTest]/[method:applyTagsFromCsv_setsDisplayNameFromCsv(java.nio.file.Path)] replaced boolean return with false for org/egothor/methodatlas/ApplyTagsFromCsvEngine::lambda$processFile$0 → KILLED

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

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

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

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