Comment out IPython magics in Python virtual documents to avoid spurious diagnostics

[juliasilge]

Fixes #1011

IPython magic lines (%, %%) and shell escapes (!) inside Python code cells are not valid Python, so third-party language servers like Pyrefly and Ruff flag them with spurious diagnostics:

This does not happen in Jupyter notebooks, because tooling such as the ruff_notebook crate sanitizes notebook input first by commenting out these lines.

Change in this PR

When Quarto builds the Python virtual document that gets fed to embedded language servers, magic and shell-escape lines are now replaced in place with the comment character (#) instead of being copied verbatim. This mirrors the existing mechanism that already blanks out non-code lines:

Because the lines are substituted (not removed), line counts stay identical and all the existing position-mapping logic (adjustedLine / unadjustedLine) keeps working unchanged.

Details:

• Added a commentMagics language option, enabled for Python only since these are IPython/Jupyter specific.
• The pattern /^\s*(%{1,2}|!)/ (from the issue) matches line magics, cell magics, and shell escapes, including leading whitespace.
• Unlike the existing inject directives (# type: ignore, # flake8: noqa), this applies to the diagnostics action too, which is the path the false diagnostics come through.
• Added an example (vdoc/magics.qmd) exercising %, %%, !, an indented %time, and surrounding real Python, plus a snapshot test confirming the magic lines become # while real Python is preserved.
• The cell magics (%%bash, etc.) only comment out the magic line itself, not the rest of the cell body. This matches the issue's suggested regex and keeps the change simple; full cell-magic handling can be a follow-up if users report it.

[posit-snyk-bot]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[seeM]

Works well in my testing!

[seeM]

I'm not sure if this has any user-facing consequences: should these be commented out including the original code?

# %reload_ext pandas
# %%timeit
# !pip install pandas
#   %time x = 1

[juliasilge]

I don't believe so, no. You can see how typical vdocs look here (empty comment lines):
https://github.com/quarto-dev/quarto/tree/main/apps/vscode/src/test/examples/generated_snapshots/vdoc
The extension keeps track of the mapping between the vdoc and the real doc, and the real doc is still there as well to get the info when needed.