Jungfraujoch/rugnux/ResultReport.h

// SPDX-FileCopyrightText: 2026 Filip Leonarski, Paul Scherrer Institute <filip.leonarski@psi.ch>
// SPDX-License-Identifier: GPL-3.0-only

#pragma once

#include <string>

#include "../common/DiffractionExperiment.h"
#include "../common/Logger.h"
#include "ReportDocument.h"
#include "Rugnux.h"

// <prefix>_report.txt - what the run DETERMINED, written next to the .mtz/.cif/.hkl on every run
// that has an output prefix. Modelled on XDS's CORRECT.LP: prose and tables a crystallographer
// reads top to bottom, with `KEY= value` assignment lines and fixed-width tables a script greps
// without parsing prose. Rates and per-image progress are deliberately absent - those are stdout;
// the command line and the total wall time are here, because they say how this result was produced
// and a report that has to be read next to a lost shell history is worth less.
//
// The format is an interface: key names, table columns and the reason vocabulary are stable, and
// REPORT_VERSION is bumped if they ever change. See docs/RUGNUX_REPORT.md.

// How the run was produced: the invocation, what it cost, and what it ran on. The CLI is the only
// caller that knows these, so they are passed in rather than read here. Each is left out of the
// report when it is not given - a caller that cannot supply one must not have the report claim the
// run was invoked by nobody, took no time, or saw no GPU.
struct RunProvenance {
    std::string command_line;      // argv as one shell-ready line
    double wall_time_s = 0.0;      // the whole invocation; 0 = not measured
    int32_t gpu_count = -1;        // -1 = not reported; 0 is a statement, not an omission
    std::string gpu_description;   // "4x NVIDIA A100-SXM4-80GB"; empty when there is no GPU
    // --developer: render the pipeline internals and the long explanations as well. The document is
    // built the same either way; this only selects how much of it the text rendering prints.
    bool developer = false;
};

// Authorship, licence and terms of use, written at the head of every report. The facts are the
// repository's: the copyright headers name the author, LICENSE is GPLv3, and the sentence about
// academic and commercial use restates what that licence already grants - said here because a
// report travels to readers who will never open a licence file.
inline constexpr const char *RUGNUX_AUTHORSHIP =
        "rugnux is written by Filip Leonarski at the Paul Scherrer Institute.\n"
        "Copyright (C) 2019-2026 Paul Scherrer Institute. It is free software under the\n"
        "GNU General Public License v3 (see the LICENSE file): academic institutions and\n"
        "commercial companies alike are free to use it.\n"
        "Releases: https://gitea.psi.ch/mx/Jungfraujoch/releases";

// The acknowledgement, printed by the CLI at startup and at the head of every report, so a
// result carries it wherever it travels. The methods are the field's, not this program's, and the
// program stands on other people's open-source code; the files named here are installed beside the
// binary (share/doc/jfjoch_rugnux on Linux, next to rugnux.exe in the Windows archive).
inline constexpr const char *RUGNUX_ACKNOWLEDGEMENT =
        "The methods rugnux implements were developed and published by the X-ray research\n"
        "community, and the program is built on open-source software from many projects. Both\n"
        "are credited in ACKNOWLEDGEMENT.md, with the licence terms in LICENSE and\n"
        "THIRD_PARTY_NOTICES.md - all three ship with this package.";

// The emitter. Populates the result object every rendering reads from; it writes no text itself.
ReportDocument BuildReportDocument(const std::string &output_prefix,
                                   const std::string &input_file,
                                   const DiffractionExperiment &experiment,
                                   const ProcessResult &result,
                                   const RunProvenance &provenance = {});

// The text rendering of that document - XDS-style prose, tables and `KEY= value` lines. Reads only
// from the document, so a second rendering is a second function of the same input.
std::string RenderReportText(const ReportDocument &doc, bool developer);

// Renders the report. Exposed for testing; RunPipeline results are the only input.
std::string RenderResultReport(const std::string &output_prefix,
                               const std::string &input_file,
                               const DiffractionExperiment &experiment,
                               const ProcessResult &result,
                               const RunProvenance &provenance = {});

// Renders and writes <output_prefix>_report.txt. Does nothing when the prefix is empty (the
// "compute statistics, persist nothing" mode). Never throws: a run that produced good reflections
// must not be lost because a side file could not be written, so a failure is logged and swallowed.
void WriteResultReport(const std::string &output_prefix,
                       const std::string &input_file,
                       const DiffractionExperiment &experiment,
                       const ProcessResult &result,
                       Logger &logger,
                       const RunProvenance &provenance = {});