Skip to content

fix: allow theme-check-disable-next-line to suppress checks inside doc tags#1189

Open
SinhSinhAn wants to merge 1 commit intoShopify:mainfrom
SinhSinhAn:fix/disable-next-line-doc-tag
Open

fix: allow theme-check-disable-next-line to suppress checks inside doc tags#1189
SinhSinhAn wants to merge 1 commit intoShopify:mainfrom
SinhSinhAn:fix/disable-next-line-doc-tag

Conversation

@SinhSinhAn
Copy link
Copy Markdown
Contributor

What is this PR?

This fixes a bug where {% # theme-check-disable-next-line %} placed before a {% doc %} tag doesn't actually suppress any of the checks that run against the doc tag's contents.

What was the issue?

Issue #945 reported that you can't use theme-check-disable-next-line to silence checks inside {% doc %} tags. For example, if you have a snippet with duplicate param names that you want to temporarily ignore:

{% # theme-check-disable-next-line UniqueDocParamNames %}
{% doc %}
  @param prods - products
  @param prods - intentional duplicate for some reason
{% enddoc %}

The UniqueDocParamNames offense would still fire despite the disable comment. The workaround was wrapping the entire doc tag in a disable/enable pair, which is verbose.

Why it was happening

The disable-next-line logic in findNextLinePosition has a guard for block tags: when the next node has a blockStartPosition (like {% if %}, {% for %}, or {% doc %}), it intentionally returns only the blockStartPosition span (just the opening marker, e.g., the literal {% doc %} characters) rather than the full tag body. This prevents disable-next-line from accidentally suppressing checks on all children of control flow tags.

The problem is that {% doc %} tags are different from {% if %} tags. Doc tag checks (like UniqueDocParamNames, ValidDocParamTypes, ReservedDocParamNames) report their offenses at positions inside the doc body (where the @param declarations live). Since blockStartPosition only covers the opening {% doc %} marker, those offense positions fall outside the disabled range and are never suppressed.

How this PR fixes it

When disable-next-line resolves the next node and that node is a LiquidRawTag with name === 'doc', it now returns the full position span (covering the entire tag from {% doc %} to {% enddoc %}) instead of just blockStartPosition.

This is safe because doc tags don't contain nested Liquid control flow. Their body is parsed by a separate grammar (LiquidDocGrammar) that only produces doc-specific nodes (@param, @description, @example). There's no risk of accidentally silencing unrelated checks on deeply nested children.

The change is a 4-line addition to findNextLinePosition in disabled-checks/index.ts.

Tests

Added 3 test cases to disabled-checks/index.spec.ts:

  • Disable-next-line with a specific check name suppresses that check inside doc tags
  • Disable-next-line without a check name suppresses all checks inside doc tags
  • Without the disable comment, offenses inside doc tags are still reported (regression guard)

All 18 tests pass (15 existing + 3 new).

Closes #945

…c tags

When `{% # theme-check-disable-next-line %}` was placed before a
`{% doc %}` tag, it only covered the opening `{% doc %}` marker itself
(via `blockStartPosition`), not the body. Checks like
UniqueDocParamNames, ValidDocParamTypes, and ReservedDocParamNames
report offenses at positions inside the doc body, so they were never
suppressed.

The fix: when the next node is a `{% doc %}` LiquidRawTag, use the
full `position` span (covering the entire tag including its body)
instead of just `blockStartPosition`. This is safe because doc tags
contain a flat list of doc-specific nodes (params, descriptions),
not nested Liquid control flow that should remain independently
checkable.

Closes Shopify#945
@SinhSinhAn SinhSinhAn requested a review from a team as a code owner April 21, 2026 15:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Theme check disable next line does not work for doc tag

1 participant