fix(comments): keep CSS at-rules like @keyframes inline instead of treating them as JSDoc tags - #672
Merged
Merged
Conversation
…eating them as JSDoc tags A wrapped prose line inside a JSDoc block that happened to start with a CSS at-rule (e.g. "... registered through the" / "@Keyframes rule and referenced by name") was classified as a tag line. The reflow then severed the sentence, injected a spurious period on the previous line, and kept the at-rule on its own line, mangling comments in style-heavy packages. isTagLine() now recognizes a small allowlist of CSS at-rules whose names never double as JSDoc/TSDoc tags (@Keyframes, @media, @layer, @supports, @container, @font-face, ...) and treats such lines as sentence continuation. At-rules that are also real JSDoc tags (@function, @import, @mixin, @namespace, @Property, @return) are deliberately left out so they keep working as tags. This mirrors the existing scoped-package exclusion (@auth0/auth0-react). Adds regression tests for both directions and documents the heuristic in the README. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MNMqVHj6CjPFuwpB1qXS5P
There was a problem hiding this comment.
Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Investigates and fixes the reported bug: "The comments script reflowed pre-existing comments and mangled the ui-styles JSDoc by misreading
@keyframesas a tag."The report is valid. A wrapped prose line inside a JSDoc block that starts with a CSS at-rule was classified as a JSDoc tag line by
isTagLine(). The reflow then flushed the paragraph early, injected a spurious period on the previous line, and left the at-rule on its own line:became
(The "reflowed pre-existing comments" part of the report is the tool's intended behavior: it reflows every JSDoc block it finds. Only the
@keyframesmangling was a defect.)Fix
isTagLine()now recognizes a small allowlist of CSS at-rules whose names never double as JSDoc/TSDoc tags (@keyframes,@media,@layer,@supports,@container,@font-face,@tailwind,@apply, ...) and treats such lines as sentence continuation. This mirrors the existing scoped-package exclusion (@auth0/auth0-react).@function,@import,@mixin,@namespace,@property,@return) are deliberately left out so they keep working as tags.isTagLine(), so it benefits automatically.Tests
@keyframes,@media, and@layeropening a wrapped prose line (no injected period, sentence joined).@property,@function,@namespace,@returnare still treated as tags.vitest: 52 passed.biome check: clean. Running the tool in dry-run mode against its ownsrc/lib.tsproduces the same diff as before this change (the new comments are stable under its own reflow).Docs
README heuristics list now mentions the scoped-package and CSS at-rule exclusions.
🤖 Generated with Claude Code
https://claude.ai/code/session_01MNMqVHj6CjPFuwpB1qXS5P
Generated by Claude Code