MeterVault/src/App/Analysis/AnalysisCsvWriter.cs

using System.Globalization;
using System.Text;

namespace MeterVault.App.Analysis;

/// <summary>
/// One row of the analysis CSV (D-55): one series in one bucket.
/// </summary>
/// <param name="SeriesId">The stable series identity (<c>m12</c>, <c>t3:use:kWh</c>, <c>portfolio</c>, <c>c4</c>).</param>
/// <param name="SeriesName">The series' name: a meter's, a type's or a category's (user data), or a worded measure.</param>
/// <param name="Kind">What the value measures, as its invariant identifier (<c>Consumption</c>, <c>Cost</c>).</param>
/// <param name="Unit">The value's unit (normalized, D-20), or the currency code for a cost series.</param>
/// <param name="BucketStart">The bucket's first instant, in the instance zone's local time with its offset.</param>
/// <param name="BucketEnd">The bucket's end (exclusive): the next local midnight, or now for a bucket cut at now.</param>
/// <param name="TimeZone">The instance zone id the bounds are local to.</param>
/// <param name="Value">The value; null when it is unavailable (missing, unresolved, invalid, being prepared).</param>
/// <param name="Status">The value's availability (<c>Available</c>, <c>Partial</c>, …).</param>
/// <param name="Provenance">Where the value comes from, as flag identifiers joined by <c>|</c> (<c>Measured|Estimated</c>); empty when none.</param>
/// <param name="Cost">The cost in the bucket; null when not priced or not costed.</param>
/// <param name="CostStatus">The cost's price coverage (<c>Priced</c>, <c>NotPriced</c>, …); null when the series has no cost.</param>
/// <param name="Currency">The currency of <paramref name="Cost"/>; null when the series has no cost.</param>
/// <param name="ComparisonValue">The value in the paired comparison bucket (D-06); null without a comparison or when unavailable.</param>
public sealed record AnalysisCsvRow(
    string SeriesId,
    string SeriesName,
    string Kind,
    string Unit,
    DateTimeOffset BucketStart,
    DateTimeOffset BucketEnd,
    string TimeZone,
    double? Value,
    string Status,
    string Provenance,
    double? Cost,
    string? CostStatus,
    string? Currency,
    double? ComparisonValue);

/// <summary>
/// Writes the analysis table as CSV (D-55): RFC 4180 quoting, a header of invariant column names, invariant numbers at
/// full precision, ISO-8601 local bucket bounds with their offset, and empty cells for unavailable values — a spreadsheet
/// or a script reads the same figures the page shows, never a fabricated zero.
/// </summary>
/// <remarks>
/// Names and units are user data. A cell that starts with <c>=</c>, <c>+</c>, <c>-</c>, <c>@</c> or a control character
/// is prefixed with an apostrophe, so a spreadsheet shows it as text instead of running it as a formula; numbers are
/// written by this class and never need it.
/// </remarks>
public static class AnalysisCsvWriter
{
    /// <summary>The header, in column order.</summary>
    public static IReadOnlyList<string> Columns { get; } =
    [
        "series_id", "series_name", "kind", "unit", "bucket_start", "bucket_end", "timezone",
        "value", "status", "provenance", "cost", "cost_status", "currency", "comparison_value",
    ];

    private const string InstantFormat = "yyyy-MM-dd'T'HH:mm:sszzz";

    /// <summary>Writes the header and one line per row.</summary>
    public static async Task WriteAsync(TextWriter writer, IEnumerable<AnalysisCsvRow> rows, CancellationToken cancellationToken = default)
    {
        ArgumentNullException.ThrowIfNull(writer);
        ArgumentNullException.ThrowIfNull(rows);

        await writer.WriteAsync(Line(Columns).AsMemory(), cancellationToken).ConfigureAwait(false);
        foreach (var row in rows)
        {
            cancellationToken.ThrowIfCancellationRequested();
            await writer.WriteAsync(Line(Fields(row)).AsMemory(), cancellationToken).ConfigureAwait(false);
        }

        await writer.FlushAsync(cancellationToken).ConfigureAwait(false);
    }

    /// <summary>The whole CSV as a string (tests, small exports).</summary>
    public static string Write(IEnumerable<AnalysisCsvRow> rows)
    {
        ArgumentNullException.ThrowIfNull(rows);

        var builder = new StringBuilder();
        builder.Append(Line(Columns));
        foreach (var row in rows)
        {
            builder.Append(Line(Fields(row)));
        }

        return builder.ToString();
    }

    /// <summary>One CSV field: quoted when it holds a comma, a quote or a line break, with quotes doubled.</summary>
    public static string Escape(string? field)
    {
        if (string.IsNullOrEmpty(field))
        {
            return string.Empty;
        }

        var needsQuotes = field.AsSpan().IndexOfAny(",\"\r\n") >= 0;
        return needsQuotes ? "\"" + field.Replace("\"", "\"\"", StringComparison.Ordinal) + "\"" : field;
    }

    /// <summary>A number at full precision in invariant form; empty when unknown or not finite.</summary>
    public static string Number(double? value) =>
        value is { } number && double.IsFinite(number) ? number.ToString("R", CultureInfo.InvariantCulture) : string.Empty;

    /// <summary>An instant as local ISO-8601 with its offset (<c>2026-09-01T00:00:00+02:00</c>).</summary>
    public static string Instant(DateTimeOffset value) => value.ToString(InstantFormat, CultureInfo.InvariantCulture);

    /// <summary>User text made safe to open in a spreadsheet: a leading formula character becomes literal text.</summary>
    public static string Text(string? value)
    {
        if (string.IsNullOrEmpty(value))
        {
            return string.Empty;
        }

        return value[0] is '=' or '+' or '-' or '@' or '\t' or '\r' or '\n' ? "'" + value : value;
    }

    private static IEnumerable<string> Fields(AnalysisCsvRow row) =>
    [
        row.SeriesId,
        Text(row.SeriesName),
        row.Kind,
        Text(row.Unit),
        Instant(row.BucketStart),
        Instant(row.BucketEnd),
        row.TimeZone,
        Number(row.Value),
        row.Status,
        row.Provenance,
        Number(row.Cost),
        row.CostStatus ?? string.Empty,
        row.Currency ?? string.Empty,
        Number(row.ComparisonValue),
    ];

    private static string Line(IEnumerable<string> fields) => string.Join(',', fields.Select(Escape)) + "\r\n";
}