Hacktoberfest 2026: die Issues, die Maintainer für den Oktober markiert haben – offen und einsteigerfreundlich. Hacktoberfest-Issues durchsuchen

PreserveComments: trailing single-line comments are re-anchored to a different node, and output is not idempotent

Offen
  • Stimmt etwas nicht?
#225 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Dieses Issue hat noch niemand übernommen.

Bewertung

Schwierigkeit
4/5
Geschätzter Aufwand
3-5 Tage
Anfängerfreundlichkeit
48/100
Issue-Typ
Bug
Klarheit
Größtenteils klar
Aktivitätsstatus
Ruhig
Tech-Stack
csharp, sql
Bereich
tooling

Rechercherichtung

Beginne damit, die bereitgestellte C#-Reproduktion in drei Durchläufen mit TSql170Parser, Sql170ScriptGenerator und aktiviertem PreserveComments auszuführen. Verfolge die Kommentarverarbeitung während GenerateScript für mehrere nachgestellte Kommentare an CASE WHEN-Zweigen; als erledigt gilt, wenn die Kommentare ihren Zweigen oder der Klausel der Anweisung zugeordnet bleiben und der zweite Formatierungsdurchlauf keine Änderungen erzeugt.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

Describe the bug

With PreserveComments = true, a trailing -- comment attached to a WHEN branch of a CASE expression is emitted against a different node than the one it annotated. Formatting the generated output a second time moves the comment again — this time into the middle of the FROM clause. Output only becomes stable on the third pass, by which point the comment sits in a clause unrelated to the expression it documented.

No exception is thrown and the parser reports no errors on any pass — the only symptom is wrong output, which is what makes it easy to ship unnoticed.

Two problems, one root cause:

  1. Semantic relocation — a comment that documented WHEN a = 1 ends up annotating the whole select element, and a comment that documented WHEN a = 2 ends up inside FROM. For code where comments carry the rationale for individual CASE branches, the regenerated script is actively misleading: the text is preserved but the association is lost.
  2. Non-idempotency — Format(Format(x)) != Format(x). This breaks the usual formatter contract and makes the generator unusable behind a format-then-verify-no-diff gate, which is how formatters are normally enforced in CI.
Input
SELECT CASE WHEN a = 1 THEN 1 -- one
            WHEN a = 2 THEN 2 -- two
            ELSE 3 END AS x
FROM t;
Actual output
--- pass 1 (changed: True) ---
SELECT CASE WHEN a = 1 THEN 1 WHEN a = 2 THEN 2 ELSE 3 END AS x -- one
 -- two
FROM   t;

--- pass 2 (changed: True) ---
SELECT CASE WHEN a = 1 THEN 1 WHEN a = 2 THEN 2 ELSE 3 END AS x -- one
FROM   -- two
       t;

--- pass 3 (changed: False) ---
SELECT CASE WHEN a = 1 THEN 1 WHEN a = 2 THEN 2 ELSE 3 END AS x -- one
FROM   -- two
       t;

Note also the stray leading space on the -- two line in pass 1.

A single WHEN branch with a trailing comment is stable — two or more branches are needed to reproduce.

Expected behaviour

Each trailing comment stays attached to the construct it followed in the source, and the second pass is a no-op. Something along these lines would be acceptable:

SELECT CASE WHEN a = 1 THEN 1 -- one
            WHEN a = 2 THEN 2 -- two
            ELSE 3 END AS x
FROM   t;

If per-branch anchoring inside a collapsed expression is not feasible, then keeping every comment within the statement clause it originated in — and guaranteeing idempotency — would still be a large improvement over the current behaviour.

Repro
using Microsoft.SqlServer.TransactSql.ScriptDom;

const string sql = """
    SELECT CASE WHEN a = 1 THEN 1 -- one
                WHEN a = 2 THEN 2 -- two
                ELSE 3 END AS x
    FROM t;
    """;

static string Format(string input)
{
    var parser = new TSql170Parser(true);
    var tree = parser.Parse(new StringReader(input), out var errors);
    if (errors.Count > 0) throw new Exception(errors[0].Message);

    var generator = new Sql170ScriptGenerator(new SqlScriptGeneratorOptions
    {
        PreserveComments = true
    });
    generator.GenerateScript(tree, out var output);
    return output;
}

var current = sql;
for (var pass = 1; pass <= 3; pass++)
{
    var next = Format(current);
    Console.WriteLine($"--- pass {pass} (changed: {next != current}) ---");
    Console.WriteLine(next);
    current = next;
}
Environment
  • Microsoft.SqlServer.TransactSql.ScriptDom 180.78.1 (assembly 18.0.0.0), net8.0
  • Reproduces identically with Sql160ScriptGenerator, Sql170ScriptGenerator, Sql180ScriptGenerator (and their matching parsers)
  • .NET 10, macOS
Impact / context

We evaluated the generator as a formatter for a T-SQL codebase in which comments routinely annotate individual CASE branches. In that setting the relocation is worse than comment loss would be: the text survives, so the output looks fine, but the comment now explains a different expression — plausible enough to pass review unnoticed. The non-idempotency is a separate blocker, since it rules out enforcing the formatter with a format-then-check-for-diff step. Happy to test a fix if that would help.

Related

Adjacent but distinct: #194 (leading newline ahead of multi-line comments) is fixed and covers block comments; #20 is the original PreserveComments request. I could not find an existing report covering trailing single-line comment re-anchoring or the resulting non-idempotency.

Vorherrschende Sprache
GAP
Sterne
278
Forks
46
Ø Merge
9 T. 23 Std.
Gemergte PRs (30 T.)
2

Entwicklungsumgebung

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus microsoft/SqlScriptDOM

Alle Issues in microsoft/SqlScriptDOM

Ähnliche Issues

Weitere Issues zu DevTools

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.