sql-utilities/src/Strata.SqlTools.Markdown/Expressions/SimpleExpressionGenerator.cs

using System.Text;
using Strata.SqlTools.SqlBreakdown.Expressions;
using Strata.SqlTools.Visitors.SqlServer;

namespace Strata.SqlTools.Markdown.Expressions;

/// <summary>
/// Generates simplified markdown documentation for Expression trees focused on readability.
/// </summary>
public class SimpleExpressionGenerator
{
    private readonly CommandVisitor _sqlVisitor = new();

    /// <summary>
    /// Generates a simple markdown document from an Expression.
    /// </summary>
    /// <param name="expression">The expression to document.</param>
    /// <param name="title">Optional title for the documentation.</param>
    /// <returns>A markdown formatted string documenting the expression.</returns>
    public string GenerateMarkdown(Expression expression, string? title = null)
    {
        var sb = new StringBuilder();

        if (!string.IsNullOrWhiteSpace(title))
        {
            sb.AppendLine($"# {title}");
            sb.AppendLine();
        }

        sb.AppendLine("## Expression");
        sb.AppendLine();
        sb.AppendLine("```sql");
        sb.AppendLine(expression.Accept(_sqlVisitor));
        sb.AppendLine("```");
        sb.AppendLine();

        sb.AppendLine("## Type Information");
        sb.AppendLine();
        sb.AppendLine($"- **Expression Type:** `{expression.GetType().Name}`");
        sb.AppendLine($"- **Namespace:** `{expression.GetType().Namespace}`");
        sb.AppendLine();

        sb.AppendLine("## Description");
        sb.AppendLine();
        sb.AppendLine(GetExpressionDescription(expression));
        sb.AppendLine();

        return sb.ToString();
    }

    /// <summary>
    /// Generates a comparison table for multiple expressions.
    /// </summary>
    /// <param name="expressions">Dictionary of expression names to expressions.</param>
    /// <param name="title">Optional title for the table.</param>
    /// <returns>A markdown formatted comparison table.</returns>
    public string GenerateComparisonTable(Dictionary<string, Expression> expressions, string? title = null)
    {
        var sb = new StringBuilder();

        if (!string.IsNullOrWhiteSpace(title))
        {
            sb.AppendLine($"# {title}");
            sb.AppendLine();
        }

        sb.AppendLine("| Name | Expression | Type |");
        sb.AppendLine("|------|------------|------|");

        foreach (var (name, expr) in expressions)
        {
            var sql = expr.Accept(_sqlVisitor).Replace("|", "\\|").Replace("\n", " ");
            var type = expr.GetType().Name;
            sb.AppendLine($"| {name} | `{sql}` | `{type}` |");
        }

        sb.AppendLine();

        return sb.ToString();
    }

    /// <summary>
    /// Generates a bulleted list of expressions.
    /// </summary>
    /// <param name="expressions">List of expressions to document.</param>
    /// <param name="title">Optional title for the list.</param>
    /// <returns>A markdown formatted bulleted list.</returns>
    public string GenerateBulletList(IEnumerable<Expression> expressions, string? title = null)
    {
        var sb = new StringBuilder();

        if (!string.IsNullOrWhiteSpace(title))
        {
            sb.AppendLine($"## {title}");
            sb.AppendLine();
        }

        foreach (var expr in expressions)
        {
            var sql = expr.Accept(_sqlVisitor).Replace("\n", " ");
            sb.AppendLine($"- `{sql}` - *{expr.GetType().Name}*");
        }

        sb.AppendLine();

        return sb.ToString();
    }

    private static string GetExpressionDescription(Expression expression)
    {
        var typeName = expression.GetType().Name;

        return typeName switch
        {
            "AndExpression" => "A logical AND expression that combines two boolean expressions. Both expressions must evaluate to true for the result to be true.",
            "OrExpression" => "A logical OR expression that combines two boolean expressions. Either expression can evaluate to true for the result to be true.",
            "NotExpression" => "A logical NOT expression that negates a boolean expression.",
            "ComparisonOperatorExpression" => "A comparison expression that compares two values using an operator (=, <>, <, >, <=, >=).",
            "ArithmeticExpression" => "An arithmetic expression that performs mathematical operations (+, -, *, /) on numeric values.",
            "FunctionExpression" => "A SQL function call expression that invokes a database function with arguments.",
            "AggregateFunctionExpression" => "An aggregate function expression (SUM, COUNT, AVG, MIN, MAX) that operates on sets of values.",
            "CaseExpression" => "A CASE expression that provides conditional logic similar to if-then-else statements.",
            "InExpression" => "An IN expression that checks if a value exists in a set of values.",
            "BetweenExpression" => "A BETWEEN expression that checks if a value falls within a range.",
            "LikeExpression" => "A LIKE expression that performs pattern matching on strings using wildcards.",
            "NumberLiteralExpression" => "A numeric literal value.",
            "StringLiteralExpression" => "A string literal value enclosed in quotes.",
            "DateTimeLiteralExpression" => "A date/time literal value.",
            "BooleanLiteralExpression" => "A boolean literal value (true/false).",
            "NullLiteralExpression" => "A NULL literal value representing absence of data.",
            "ParameterExpression" => "A parameterized value placeholder that will be substituted at runtime.",
            "ColumnExpression" => "A reference to a database column from a table or view.",
            _ => $"A {typeName} expression."
        };
    }
}