Program Listing for File RequirementsLogger.h

↰ Return to documentation for file (include/Karana/RequirementsTest/RequirementsLogger.h)

/*
 * Copyright (c) 2024-2026 Karana Dynamics Pty Ltd. All rights reserved.
 *
 * NOTICE TO USER:
 *
 * This source code and/or documentation (the "Licensed Materials") is
 * the confidential and proprietary information of Karana Dynamics Inc.
 * Use of these Licensed Materials is governed by the terms and conditions
 * of a separate software license agreement between Karana Dynamics and the
 * Licensee ("License Agreement"). Unless expressly permitted under that
 * agreement, any reproduction, modification, distribution, or disclosure
 * of the Licensed Materials, in whole or in part, to any third party
 * without the prior written consent of Karana Dynamics is strictly prohibited.
 *
 * THE LICENSED MATERIALS ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.
 * KARANA DYNAMICS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
 * BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, AND
 * FITNESS FOR A PARTICULAR PURPOSE.
 *
 * IN NO EVENT SHALL KARANA DYNAMICS BE LIABLE FOR ANY DAMAGES WHATSOEVER,
 * INCLUDING BUT NOT LIMITED TO LOSS OF PROFITS, DATA, OR USE, EVEN IF
 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, WHETHER IN CONTRACT, TORT,
 * OR OTHERWISE ARISING OUT OF OR IN CONNECTION WITH THE LICENSED MATERIALS.
 *
 * U.S. Government End Users: The Licensed Materials are a "commercial item"
 * as defined at 48 C.F.R. 2.101, and are provided to the U.S. Government
 * only as a commercial end item under the terms of this license.
 *
 * Any use of the Licensed Materials in individual or commercial software must
 * include, in the user documentation and internal source code comments,
 * this Notice, Disclaimer, and U.S. Government Use Provision.
 */

// Written by Codex for kelly on 2026-08-10.
/**
 * @file
 * @brief Declares the process-wide requirements result logger.
 */

#pragma once

#include "Karana/RequirementsTest/Defs.h"
#include <filesystem>
#include <memory>
#include <string>
#include <vector>

namespace RequirementsTest {

    /**
     * @brief Collects requirement outcomes and writes one process JSON artifact.
     *
     * Logging is disabled unless KARANA_LOG_REQUIREMENTS is present in the
     * process environment.
     *
     * The first call to singleton() registers automatic artifact emission with
     * the standard process-exit callback registry.
     */
    class RequirementsLogger {
      public:
        /**
         * @brief Return a process-wide requirements logger.
         * @return Shared pointer to the singleton process logger.
         */
        static std::shared_ptr<RequirementsLogger> singleton();

        /**
         * @brief Record one requirement verification.
         * @param requirement Authored requirement identifier.
         * @param status Verification outcome.
         * @throws std::logic_error If status is not a declared enumerator.
         */
        void logRequirement(const Requirement &requirement, Status status);

        /**
         * @brief Record a passed or failed requirement verification from a boolean check.
         * @param requirement Authored requirement identifier.
         * @param passed True maps to PASSED and false maps to FAILED; SKIPPED remains explicit.
         */
        void logRequirement(const Requirement &requirement, bool passed);

        /**
         * @brief Return the process status implied by recorded requirement outcomes.
         * @return One after any FAILED outcome, otherwise zero.
         */
        int getReturnCode();

        /**
         * @brief Override the directory used for automatic artifact emission.
         * @param directory Destination directory, created during process exit.
         */
        void setArtifactDirectory(std::filesystem::path directory);

        /**
         * @brief Set the implementation language represented by this process.
         * @param language Stable language identifier written to the artifact.
         * @throws std::invalid_argument If language is empty.
         */
        void setLanguage(std::string language);

        RequirementsLogger(const RequirementsLogger &) = delete;
        RequirementsLogger &operator=(const RequirementsLogger &) = delete;

      private:
        /** @brief Construct the process-owned requirements logger. */
        RequirementsLogger();

        /** @brief Write collected results during normal process exit. */
        void writeArtifact();

        /** @brief Invoke artifact writing without allowing exceptions across std::atexit. */
        static void writeArtifactAtExit() noexcept;

        /** @brief One unaggregated requirement verification call. */
        struct RequirementRecord {
            /// Authored requirement identifier.
            Requirement requirement;
            /// Verification outcome.
            Status status;
        };

        /// Requirement calls retained in their original order.
        std::vector<RequirementRecord> _records;
        /// Directory receiving the process artifact.
        std::filesystem::path _artifact_directory;
        /// Implementation language used to locate the adjacent test source.
        std::string _language = "cpp";
        /// Whether the process explicitly enabled requirement collection.
        bool _enabled = false;
        /// Nonzero after any requirement has been logged as failed.
        int _return_code = 0;
    };

    // Free functions that allow us to avoid having to interact with the singleton directly if we
    // don't need to.

    /**
     * @brief Record one generated requirement outcome on the process logger.
     * @param requirement Authored requirement identifier.
     * @param status Verification outcome.
     */
    void logRequirement(const Requirement &requirement, Status status);

    /**
     * @brief Record a generated requirement outcome from a boolean check.
     * @param requirement Authored requirement identifier.
     * @param passed True maps to PASSED and false maps to FAILED; SKIPPED remains explicit.
     */
    void logRequirement(const Requirement &requirement, bool passed);

    /**
     * @brief Return the process status implied by recorded requirement outcomes.
     * @return One after any FAILED outcome, otherwise zero.
     */
    int getReturnCode();

} // namespace RequirementsTest