Plan analysis: mask comments and string literals before the text rules (#4524)

[erikdarlingdata]

Fixes #4524
Part of #4511

Why

Several plan-analysis rules search the statement text for a hint or a keyword — MAXDOP 1, RECOMPILE, OPTIMIZE FOR UNKNOWN, NOT IN, and the row-goal cause lookup (TOP/EXISTS/IN/FAST). They searched the raw text, so the same word inside a -- comment, a /* */ comment, or a string literal counted as real code. -- OPTION (RECOMPILE) in a comment stopped the local-variables rule from warning about unsniffable parameters. NOT IN inside a string literal could make the anti-join rule warn about a pattern that was never in the query.

What changes

Adds MaskCommentsAndLiterals, mirroring erikdarlingdata/PerformanceStudio@cc18844: it blanks the contents of string literals and whole comments with spaces (so positions and every other character stay put), handles N'...', doubled-quote escapes '', nested /* /* */ */ comments, and an unterminated comment or literal (masks to the end of the text). Delimited identifiers ([...], "...") are stepped over unchanged.

Wired at the five call sites PM has today:

• Rule 3, MAXDOP 1 (PlanAnalyzer.cs ~114)
• Rule 20, RECOMPILE (~255)
• Rule 26, the row-goal cause via IdentifyRowGoalCause (~1086)
• Rule 27, OPTIMIZE FOR UNKNOWN (~277)
• Rule 28, NOT IN via HasNotInPattern (~1138)

PerformanceStudio's follow-up commit (dcec793) also applies the helper to a rule 38 (Standard Edition), which PM doesn't have yet — that's #4530, and this PR doesn't touch it.

Test plan

New class Darling.Tests.PlanSync4524Tests:

• the helper's own scan behavior (through rule 27): a -- comment, a /* */ comment, nested /* /* */ */, a plain string literal, N'...' with a doubled '', and an unterminated /* that masks to the end of the text — none of these fire the warning;

• a real hint survives a dash pair inside a string, a quote inside a bracketed identifier, or a closed comment earlier in the text;

• rule 20: RECOMPILE mentioned only in a -- or /* */ comment still warns about local variables (it used to suppress the warning); a real OPTION (RECOMPILE) still suppresses it;

• rule 28: NOT IN inside a string literal does not warn; a real NOT IN still does;

• rule 3: MAXDOP 1 mentioned only in a comment is not treated as a query-level hint;

• rule 26: the row-goal cause ignores a keyword sitting inside a trailing comment.

• Runtime RED on dev: the new class compiles unchanged against dev (0ed0c4736), and 11 of its theory cases fail there, across rules 3, 20, 26, 27 and 28.

• Mutation: putting rule 20 back on the raw text turns both comment cases of Rule20_RecompileMentionedOnlyInAComment_StillWarnsAboutLocalVariables red.

• Run: the plan-analysis test classes (PlanSync4524Tests, ShowPlanParserCondAndMultiplePlanTests, DarlingActualPlanTests, DarlingAnalysisPipelineTests, DarlingMcpPlanToolsTests, McpPlanAnalysisEnvelopeTests, SerialLoopStoreSizeSourceTests, TsqlConventionGuardTests, DocCommentHygieneTests): Total: 151, Failed: 0, Skipped: 1. Lite.Tests builds; its plan-analysis classes run on Windows only.

CHANGELOG

SECTION: Fixed
ENTRY: - Plan analysis rules for MAXDOP 1, RECOMPILE, OPTIMIZE FOR UNKNOWN, NOT IN, and row-goal causes ignore hints and keywords written inside a comment or a string literal ([#4540]) - A hint or keyword sitting in a --//* */ comment or inside a quoted string no longer counts as code, so these rules no longer fire on text that isn't actually part of the query, and no longer miss a real hint hidden behind one.
REF: [#4540]: #4540