Automattic / Automattic/harper

Python comments/docstrings don't respect Markdown syntax (backticks, code fences/snippets) after v0.67.0

Open
#2,417 3 comments 1 reaction 0 assignees View on GitHub
enhancement harper-comments harper-core markdown
Dominant language
Rust
Stars
15.4k
Forks
627
Avg merge
1d 15h
Merged PRs (30d)
102

Description

## Describe the bug

After upgrading from v0.66.0 to v0.67.0, inline code wrapped in backticks (`` `row_idx` ``) and content inside code fences (` ``` `) within Python comments and docstrings triggers spell-check errors. Previously, these Markdown-style constructs were correctly skipped.

For example, this Python file:

```python
def test() -> int:
"""Docstring with `row_idx` inline code."""
# Test comment with `row_idx`.
# ```
# row_idx
# ```
return -1
```

- **v0.66.0**: No errors (backtick content skipped from spell-check)
- **v0.67.0+**: `"Did you mean to spell 'idx' this way?"` error on all `row_idx` occurrences

## To Reproduce

1. Create a Python file with inline code in backticks inside a comment or docstring (e.g., `` `row_idx` ``)
2. Open the file in VS Code with Harper extension v0.67.0 or later
3. Observe spell-check errors on text inside backticks

## What I found

I traced this to #2038 ("Add support for Python docstrings"). Before this change, Python comments were parsed via `CommentParser` which fell through to the default case using `Unit::new_markdown(markdown_options)`: a Markdown-aware parser.

After #2038, a dedicated `PythonParser` was introduced that uses `PlainEnglish` as the inner parser instead:

```rust
// harper-python/src/lib.rs
inner: parsers::Mask::new(
TreeSitterMasker::new(tree_sitter_python::LANGUAGE.into(), Self::node_condition),
PlainEnglish, // <-- This doesn't understand Markdown syntax
),
```

## Screenshots

**v1.3.0 (current) — Multiple false positives on backtick content:**

Image

**v0.66.0 (previous) — Only real error flagged, backtick content correctly ignored:**

Image

## Question

Was this change intentional? If restoring Markdown syntax support for Python comments/docstrings is desired, I'd be happy to submit a PR. The fix would involve replacing `PlainEnglish` with a Markdown-aware parser similar to how other languages handle this.

## Platform

Visual Studio Code (Harper extension)

Contributor guide

Open the contributing guide

Research direction

Start in harper-python/src/lib.rs at PythonParser and compare its PlainEnglish inner parser with the earlier Markdown-aware CommentParser path described in the issue. Reproduce the supplied Python comment and docstring examples, then verify that inline backticks and fenced content no longer produce spell-check errors while ordinary prose is still checked.

Written by the indexing model from the issue text.

Assessment

Tech stack
python, rust, vscode
Domain
tooling
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.