ReceiptBuilder.java

// SPDX-License-Identifier: Apache-2.0

// Copyright 2026 Egothor

// Copyright 2026 Accenture

package org.egothor.methodatlas.receipt;

import java.io.IOException;

import java.nio.charset.StandardCharsets;

import java.nio.file.Path;

import java.security.MessageDigest;

import java.security.NoSuchAlgorithmException;

import java.time.Instant;

import java.util.HexFormat;

import java.util.List;

import java.util.Map;

import java.util.TreeMap;

import org.egothor.methodatlas.CliConfig;

import org.egothor.methodatlas.ai.AiOptions;

import org.egothor.methodatlas.ai.PromptTemplateKind;

import org.egothor.methodatlas.ai.PromptTemplateSet;

import org.egothor.methodatlas.command.ContentHasher;

/**

 * Assembles a {@link ReproducibilityReceipt} from a parsed

 * {@link CliConfig} and the resolved tool version.

 *

 * <p>

 * Package-private because nothing outside the {@code receipt} package needs to

 * call this; {@code MethodAtlasApp} is the sole external caller, accessing it

 * through {@link #build(CliConfig, String, String)}.

 * </p>

 */

final class ReceiptBuilder {

    /**

     * Schema version of the JSON payload; bumped on any breaking change.

     *

     * <p>

     * v2 (4.1.0) replaced the single {@code inputs.promptTemplateHash} of v1 with

     * three per-template hashes ({@code classificationPromptHash},

     * {@code triageAppendixPromptHash}, {@code dedicatedTriagePromptHash}) and folds

     * all three into {@code configHash}. See {@code docs/usage-modes/reproducibility-receipts.md}.

     * </p>

     */

    private static final String SCHEMA_VERSION = "2";

    /** Algorithm string passed to {@link MessageDigest#getInstance(String)}. */

    private static final String SHA256_ALGO = "SHA-256";

    /** Sentinel for "no value" in the canonical key=value serialisation. */

    @SuppressWarnings("InlineTrivialConstant")

    private static final String EMPTY = "";

    // Canonical key=value separator characters: kept as constants so the

    // algorithm is unambiguous to an auditor re-deriving the hash from

    // standard tooling (e.g. sha256sum + printf).

    /** Separator between key and value in the canonical serialisation. */

    private static final String CONFIG_HASH_KV_SEP = "=";

    /** Separator between key=value pairs in the canonical serialisation. */

    private static final String CONFIG_HASH_SEPARATOR = "\n";

    // TreeMap keys: alphabetical insertion is enforced by TreeMap, not by the

    // declaration order here.

    /** TreeMap key for the AI cache file fingerprint. */

    private static final String KEY_AI_CACHE_FILE_SHA = "aiCacheFileSha256";

    /** TreeMap key for the configured AI model name. */

    private static final String KEY_AI_MODEL = "aiModel";

    /** TreeMap key for the configured AI provider. */

    private static final String KEY_AI_PROVIDER = "aiProvider";

    /** TreeMap key for the built-in taxonomy mode name. */

    private static final String KEY_BUILT_IN_TAXONOMY = "builtInTaxonomy";

    /** TreeMap key for the MethodAtlas tool version. */

    private static final String KEY_METHOD_ATLAS_VERSION = "methodAtlasVersion";

    /** TreeMap key for the override file fingerprint. */

    private static final String KEY_OVERRIDE_FILE_SHA = "overrideFileSha256";

    /** TreeMap key for the effective method-classification prompt template hash. */

    private static final String KEY_CLASSIFICATION_PROMPT = "classificationPromptHash";

    /** TreeMap key for the effective folded credential-triage appendix template hash. */

    private static final String KEY_TRIAGE_APPENDIX_PROMPT = "triageAppendixPromptHash";

    /** TreeMap key for the effective standalone credential-triage template hash. */

    private static final String KEY_DEDICATED_TRIAGE_PROMPT = "dedicatedTriagePromptHash";

    /** TreeMap key for the taxonomy file fingerprint. */

    private static final String KEY_TAXONOMY_FILE_SHA = "taxonomyFileSha256";

    /**

     * Rough capacity estimate for the canonical key=value buffer: ten keys

     * with combined length ≈ 200 characters plus up to ten 64-char SHA-256

     * values plus separators leaves the StringBuilder near its final size

     * without reallocations.

     */

    private static final int CANONICAL_BUFFER_CAPACITY = 1024;

        // Utility class.

    /**

     * Builds a reproducibility receipt for the supplied configuration.

     *

     * <p>

     * The {@code configHash} field is computed as follows:

     * </p>

     * <ol>

     *   <li>A {@link TreeMap} is populated with the ten canonical keys

     *       documented at class scope. Absent inputs map to the empty

     *       string.</li>

     *   <li>The map is serialised as {@code key1=value1\n…keyN=valueN\n}

     *       using {@link StandardCharsets#UTF_8}; {@link TreeMap} guarantees

     *       alphabetical key order.</li>

     *   <li>SHA-256 is applied to those bytes and the result is emitted as

     *       lowercase hex via {@link HexFormat#of()}.</li>

     * </ol>

     *

     * @param config         parsed CLI configuration; must not be {@code null}

     * @param toolVersion    resolved tool version string (use {@code "dev"} when

     *                       no implementation version is available)

     * @param outputModeName textual name of the chosen output mode (e.g.

     *                       {@code "SARIF"}); included in the receipt's

     *                       {@code outputMode} field

     * @return a populated receipt with a stable {@code configHash} that an

     *         auditor can recompute from the other fields

     * @throws IOException if any input file referenced by {@code config}

     *                     (override file, taxonomy file, AI cache) cannot be

     *                     read for hashing

     */

    /* default */ static ReproducibilityReceipt build(CliConfig config, String toolVersion,

            String outputModeName) throws IOException {

        } else {

        }

                overrideArtifact, aiCacheArtifact, aiProvider, aiModel,

                classificationPromptHash, triageAppendixPromptHash, dedicatedTriagePromptHash);

                taxonomyArtifact, builtInTaxonomy,

                classificationPromptHash, triageAppendixPromptHash, dedicatedTriagePromptHash);

                SCHEMA_VERSION,

                toolVersion,

                outputModeName,

                inputs,

                configHash);

    }

    /**

     * Returns a {@link FileArtifact} for {@code file} or {@code null} when

     * {@code file} is itself {@code null}.

     *

     * @param file path to fingerprint; may be {@code null}

     * @return populated artefact or {@code null}

     * @throws IOException if the file cannot be read

     */

    private static FileArtifact hashIfPresent(Path file) throws IOException {

        }

    }

    /**

     * Resolves the JVM's reported Java version to a non-null string.

     *

     * @return Java version, or the literal {@code "unknown"} when the

     *         {@code java.version} property is unset

     */

    private static String javaVersion() {

    }

    /**

     * Maps scan roots to absolute path strings. An empty input list means

     * "scan the current directory"; the absolute resolution captures the

     * actual directory that was scanned.

     *

     * @param config parsed CLI configuration

     * @return absolute path strings for every scan root, in the order

     *         supplied on the command line

     */

    private static List<String> resolveScanRoots(CliConfig config) {

        }

    }

    /**

     * Computes the {@code deterministicReplay} flag.

     *

     * @param config parsed CLI configuration

     * @return {@code true} when AI is disabled or an AI cache is configured

     */

    private static boolean computeDeterministicReplay(CliConfig config) {

    }

    /**

     * Produces the SHA-256 hex of the canonical {@code key=value} buffer.

     *

     * @param toolVersion        MethodAtlas tool version string

     * @param ai                 parsed AI options

     * @param overrideArtifact   override file artefact, or {@code null}

     * @param aiCacheArtifact    AI cache file artefact, or {@code null}

     * @param taxonomyArtifact   taxonomy file artefact, or {@code null}

     * @param builtInTaxonomy    built-in taxonomy mode name, or {@code null}

     * @param classificationPromptHash effective classification template hash, or {@code null}

     * @param triageAppendixPromptHash effective folded triage-appendix template hash, or {@code null}

     * @param dedicatedTriagePromptHash effective standalone triage template hash, or {@code null}

     * @return 64-character lowercase hex SHA-256

     */

    private static String computeConfigHash(String toolVersion, AiOptions ai,

            FileArtifact overrideArtifact, FileArtifact aiCacheArtifact,

            FileArtifact taxonomyArtifact, String builtInTaxonomy,

            String classificationPromptHash, String triageAppendixPromptHash,

            String dedicatedTriagePromptHash) {

        try {

        }

    }

    /**

     * Extracts the SHA-256 string from a {@link FileArtifact}, or returns the

     * empty-string sentinel when the artefact is absent.

     *

     * @param artifact artefact to inspect; may be {@code null}

     * @return SHA-256 hex or {@code ""}

     */

    private static String shaOrEmpty(FileArtifact artifact) {

    }

}

Mutations

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

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

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

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

3.3
Location : javaVersion
Killed by : none replaced return value with "" for org/egothor/methodatlas/receipt/ReceiptBuilder::javaVersion → SURVIVED Covering tests

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

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

1.1
Location : resolveScanRoots
Killed by : none replaced return value with Collections.emptyList for org/egothor/methodatlas/receipt/ReceiptBuilder::resolveScanRoots → SURVIVED Covering tests

1.1
Location : resolveScanRoots
Killed by : none replaced return value with Collections.emptyList for org/egothor/methodatlas/receipt/ReceiptBuilder::resolveScanRoots → SURVIVED Covering tests

2.2
Location : lambda$resolveScanRoots$0
Killed by : none replaced return value with "" for org/egothor/methodatlas/receipt/ReceiptBuilder::lambda$resolveScanRoots$0 → SURVIVED Covering tests

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

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

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

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

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

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

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