subedit 0.2.0__tar.gz → 0.3.1__tar.gz

{subedit-0.2.0 → subedit-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: subedit
-Version: 0.2.0
+Version: 0.3.1
 Summary: A linter and formatter for the prose inside code comments, across languages.
 Project-URL: Homepage, https://github.com/mroops0111/subedit
 Project-URL: Repository, https://github.com/mroops0111/subedit
@@ -38,7 +38,7 @@ Your house style, enforced in the places prose hides inside a codebase.
 
 A subeditor is the person at a publication who makes every piece of copy match its house style. `subedit` does that job for the prose in your code.
 
-Linters check your code. Almost nothing checks the sentences you write around it. `subedit` reads the comments and docstrings in your source, lays them out one sentence per line, and only tells you about the sentences a tool cannot fix for you.
+Linters check your code. Almost nothing checks the sentences you write around it. `subedit` reads the comments and docstrings in your source, lays them out so no sentence breaks mid clause, and only tells you about the sentences a tool cannot fix for you.
 
 ## Example
 
@@ -56,6 +56,8 @@ An editor wraps a comment at whatever column it reaches, so sentences break mid
     # Retry once, then give up.
 ```
 
+Short sentences may share a line while it fits, as in `# Retry once. Then give up.` A line of them that overflows is split, one sentence a line.
+
 A sentence that runs past the width with no comma has nowhere legal to break, and only its author knows where the meaning divides. That one comes back to you, or to the agent that wrote it.
 
 ```text
@@ -151,13 +153,15 @@ Registering the hook with both agents is the normal case. Each agent names its e
 
 ## Languages
 
-| Language | Files | Doc comment | Default width |
+| Language | Files | Doc comment | Width read from |
 | --- | --- | --- | --- |
-| Python | `.py`, `.pyi` | `"""` docstring | 120 |
-| TypeScript | `.ts`, `.mts`, `.cts`, `.tsx` | `/** */` JSDoc | 80, as Prettier sets it |
+| Python | `.py`, `.pyi` | `"""` docstring | `line-length` for ruff or black |
+| TypeScript | `.ts`, `.mts`, `.cts`, `.tsx` | `/** */` JSDoc | `printWidth` for Prettier, `lineWidth` for Biome |
 
 A TypeScript symbol is public when it is exported, and a class member stays public unless it is `private`, `protected`, or `#named`.
-A JSDoc block keeps its frame when reflowed. Its tag section, from the first tag such as `@throws` onward, is left as written.
+A plain comment opening a paragraph over several declarations heads them as a group, so it documents none of them. One right under another declaration may be either, so `plain-comment-on-public` reports it as a warning.
+A JSDoc block keeps its frame when reflowed. Its tag section, from the first tag such as `@throws` onward, is left as written, as a docstring's sections from `Args:`, `Parameters`, or `:param` onward are.
+A comment line that the language's own grammar reads as code, such as `// return result` or `# client.send(`, is left as written in either language.
 A plain `/* */` block and a directive such as `// eslint-disable-next-line` carry no prose for subedit to lay out, so only Vale reads the block, and nothing reads the directive.
 A directory walk skips dotted directories such as `.venv`, and the package directories each language installs into, such as `node_modules` or `venv`.
 
@@ -175,7 +179,7 @@ mid-clause-break = "error"
 block-too-long = { severity = "warning", line = 3, doc-public = 20 }
 ```
 
-Left unset, `line-width` takes the default of each file's language.
+Left unset, `line-width` follows the project's formatter, from the config the formatter would read for that file, and is 120 where no formatter sets one.
 
 Rule names describe the problem they report. `docs/rules.md` lists every rule, generated from the rules themselves.
 

{subedit-0.2.0 → subedit-0.3.1}/README.md

@@ -4,7 +4,7 @@ Your house style, enforced in the places prose hides inside a codebase.
 
 A subeditor is the person at a publication who makes every piece of copy match its house style. `subedit` does that job for the prose in your code.
 
-Linters check your code. Almost nothing checks the sentences you write around it. `subedit` reads the comments and docstrings in your source, lays them out one sentence per line, and only tells you about the sentences a tool cannot fix for you.
+Linters check your code. Almost nothing checks the sentences you write around it. `subedit` reads the comments and docstrings in your source, lays them out so no sentence breaks mid clause, and only tells you about the sentences a tool cannot fix for you.
 
 ## Example
 
@@ -22,6 +22,8 @@ An editor wraps a comment at whatever column it reaches, so sentences break mid
     # Retry once, then give up.
 ```
 
+Short sentences may share a line while it fits, as in `# Retry once. Then give up.` A line of them that overflows is split, one sentence a line.
+
 A sentence that runs past the width with no comma has nowhere legal to break, and only its author knows where the meaning divides. That one comes back to you, or to the agent that wrote it.
 
 ```text
@@ -117,13 +119,15 @@ Registering the hook with both agents is the normal case. Each agent names its e
 
 ## Languages
 
-| Language | Files | Doc comment | Default width |
+| Language | Files | Doc comment | Width read from |
 | --- | --- | --- | --- |
-| Python | `.py`, `.pyi` | `"""` docstring | 120 |
-| TypeScript | `.ts`, `.mts`, `.cts`, `.tsx` | `/** */` JSDoc | 80, as Prettier sets it |
+| Python | `.py`, `.pyi` | `"""` docstring | `line-length` for ruff or black |
+| TypeScript | `.ts`, `.mts`, `.cts`, `.tsx` | `/** */` JSDoc | `printWidth` for Prettier, `lineWidth` for Biome |
 
 A TypeScript symbol is public when it is exported, and a class member stays public unless it is `private`, `protected`, or `#named`.
-A JSDoc block keeps its frame when reflowed. Its tag section, from the first tag such as `@throws` onward, is left as written.
+A plain comment opening a paragraph over several declarations heads them as a group, so it documents none of them. One right under another declaration may be either, so `plain-comment-on-public` reports it as a warning.
+A JSDoc block keeps its frame when reflowed. Its tag section, from the first tag such as `@throws` onward, is left as written, as a docstring's sections from `Args:`, `Parameters`, or `:param` onward are.
+A comment line that the language's own grammar reads as code, such as `// return result` or `# client.send(`, is left as written in either language.
 A plain `/* */` block and a directive such as `// eslint-disable-next-line` carry no prose for subedit to lay out, so only Vale reads the block, and nothing reads the directive.
 A directory walk skips dotted directories such as `.venv`, and the package directories each language installs into, such as `node_modules` or `venv`.
 
@@ -141,7 +145,7 @@ mid-clause-break = "error"
 block-too-long = { severity = "warning", line = 3, doc-public = 20 }
 ```
 
-Left unset, `line-width` takes the default of each file's language.
+Left unset, `line-width` follows the project's formatter, from the config the formatter would read for that file, and is 120 where no formatter sets one.
 
 Rule names describe the problem they report. `docs/rules.md` lists every rule, generated from the rules themselves.
 

{subedit-0.2.0 → subedit-0.3.1}/plugins/subedit/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "subedit",
   "displayName": "subedit",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Repairs comment layout silently on write, and returns only what needs rewriting.",
   "author": {
     "name": "mroops0111"

{subedit-0.2.0 → subedit-0.3.1}/plugins/subedit/scripts/run-subedit-hook.sh

@@ -4,7 +4,7 @@
 # because the first run installs subedit and downloads Vale, which no edit should wait on.
 set -uo pipefail
 
-SPEC='subedit[vale]>=0.2.0'
+SPEC='subedit[vale]>=0.3.1'
 # A bare uvx takes the first Python it finds, which on a stock Mac is too old for subedit.
 PYTHON='>=3.11'
 

{subedit-0.2.0 → subedit-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "subedit"
-version = "0.2.0"
+version = "0.3.1"
 description = "A linter and formatter for the prose inside code comments, across languages."
 authors = [
     {name = "Yun-Tai Yang"},

{subedit-0.2.0 → subedit-0.3.1}/src/subedit/__init__.py

@@ -1,3 +1,3 @@
-__version__ = '0.2.0'
+__version__ = '0.3.1'
 
 __all__ = ['__version__']

{subedit-0.2.0 → subedit-0.3.1}/src/subedit/application/linter.py

@@ -1,7 +1,7 @@
 import dataclasses
 
 from ..domain.models.comment import CommentGroup
-from ..domain.models.diagnostic import Diagnostic, Report
+from ..domain.models.diagnostic import Diagnostic, Report, Severity
 from ..domain.models.document import Document
 from ..domain.models.prose_map import ProseMap
 from ..domain.models.rule_set import RuleSet
@@ -27,7 +27,13 @@ class RuleEngine:
         return tuple(diagnostics)
 
     def _with_severity(self, diagnostic: Diagnostic, rule: Rule, rule_set: RuleSet) -> Diagnostic:
-        severity = rule_set.severity_for(rule.metadata)
+        configured = rule_set.settings_for(rule.metadata.rule_id).severity
+        if configured is not None:
+            severity = configured
+        elif diagnostic.tentative:
+            severity = Severity.WARNING
+        else:
+            severity = rule.metadata.default_severity
         if diagnostic.severity is severity:
             return diagnostic
         return dataclasses.replace(diagnostic, severity=severity)
@@ -64,4 +70,5 @@ class Linter:
         groups = self._parser.parse(document)
         diagnostics = self._engine.run(document, groups, rule_set)
         sorted_diagnostics = sorted(diagnostics, key=lambda item: (item.range.start, item.rule_id))
-        return Inspection(Report(tuple(sorted_diagnostics)), ProseMap.of_comments(groups))
+        prose_map = ProseMap.of_comments(groups, self._parser.directive_ranges(document))
+        return Inspection(Report(tuple(sorted_diagnostics)), prose_map)

{subedit-0.2.0 → subedit-0.3.1}/src/subedit/domain/models/comment.py

@@ -37,6 +37,8 @@ class SymbolRef:
     name: str
     kind: SymbolKind
     visibility: Visibility
+    # A comment over several declarations, right under code, may head them as a group rather than document this one.
+    may_head_a_group: bool = False
 
 
 @dataclasses.dataclass(frozen=True, slots=True)
@@ -102,7 +104,12 @@ class CommentGroup:
             texts = self._reflow_into_texts(width, stub_floor, closing_width)
         if not texts:
             return self
-        return dataclasses.replace(self, lines=self.layout.rebuild(self.lines, texts, width))
+        rebuilt = dataclasses.replace(self, lines=self.layout.rebuild(self.lines, texts, width))
+        # A sentence with no legal break may come out longer than the author wrapped it,
+        # and a fix that pushes a line past the width trades one finding for another.
+        if rebuilt.longest_line > max(width, self.longest_line):
+            return self
+        return rebuilt
 
     def sentences_held_by_a_list(self, width: int, stub_floor: int = 0) -> tuple[str, ...]:
         """The sentences reflow leaves as the author broke them, since every legal break would split a list."""
@@ -130,11 +137,21 @@ class CommentGroup:
                 out.extend(paragraph)
                 continue
             lines = tuple(line.strip() for line in paragraph if line.strip())
-            for sentence_index, sentence in enumerate(Prose(' '.join(lines)).sentences()):
+            sentences = Prose(' '.join(lines)).sentences()
+            shared_until = 0
+            for sentence_index, sentence in enumerate(sentences):
+                if sentence.offset < shared_until:
+                    continue
                 if sentence_index == 1 and paragraph_index == 0 and self.has_summary_line:
                     out.append('')
                 first_budget = self.text_budget(width, first_line=not out) - (reserve if not out else 0)
-                if self.has_summary_line and paragraph_index == 0 and sentence_index == 0:
+                is_summary = self.has_summary_line and paragraph_index == 0 and sentence_index == 0
+                shared_line = None if is_summary else _shared_line(lines, sentences[sentence_index:])
+                if shared_line is not None and len(shared_line) <= first_budget:
+                    out.append(shared_line)
+                    shared_until = sentence.offset + len(shared_line)
+                    continue
+                if is_summary:
                     best_lines: tuple[str, ...] = (sentence.text,)
                 else:
                     best_lines = reflow_sentence(sentence.text, body_budget, stub_floor, first_width=first_budget)
@@ -185,6 +202,19 @@ class CommentGroup:
         return TextEdit(self.range, self.render())
 
 
+# A line the author filled with several short sentences, each whole, reads as well as one sentence a line,
+# so it stays while it fits.
+def _shared_line(lines: tuple[str, ...], sentences: tuple[Sentence, ...]) -> str | None:
+    start = 0
+    for line in lines:
+        if start == sentences[0].offset:
+            end = start + len(line)
+            ending_here = [sentence for sentence in sentences[1:] if sentence.end == end]
+            return line if ending_here and sentences[0].end < end else None
+        start += len(line) + 1
+    return None
+
+
 # The lines a sentence already occupies, when it has them to itself.
 def _given_lines(lines: tuple[str, ...], sentence: Sentence) -> tuple[str, ...] | None:
     covering: list[str] = []

{subedit-0.2.0 → subedit-0.3.1}/src/subedit/domain/models/diagnostic.py

@@ -69,6 +69,8 @@ class Diagnostic:
     severity: Severity = Severity.ERROR
     fix: Fix | None = None
     source: str = 'subedit'
+    # A finding the rule may have read wrong reaches the author as advice, unless the project sets its severity.
+    tentative: bool = False
 
     def __post_init__(self) -> None:
         if not self.message:
@@ -121,10 +123,11 @@ class Report:
         )
 
     def merged_with(self, other: 'Report') -> 'Report':
-        seen_keys: set[tuple[str, int, int]] = set()
+        seen_keys: set[tuple[str, int, int, str]] = set()
         merged_diagnostics: list[Diagnostic] = []
         for diagnostic in (*self.diagnostics, *other.diagnostics):
-            key = (diagnostic.rule_id, diagnostic.range.start, diagnostic.range.end)
+            # One rule can find several sentences in one block, and each finding carries its own message.
+            key = (diagnostic.rule_id, diagnostic.range.start, diagnostic.range.end, diagnostic.message)
             if key in seen_keys:
                 continue
             seen_keys.add(key)

{subedit-0.2.0 → subedit-0.3.1}/src/subedit/domain/models/prose.py

@@ -1,6 +1,7 @@
 import dataclasses
 import itertools
 import re
+import typing
 
 
 # Abbreviations whose period does not end a sentence, written without that period.
@@ -20,6 +21,8 @@ ABBREVIATIONS = frozenset(
 )
 
 _SENTENCE_END = re.compile(r'[.!?]')
+# A colon ends a lead-in as a period ends a sentence, so the line after either opens something new.
+_ENDS_A_SENTENCE = re.compile(r'[.!?:]["\')\]]*\s*$')
 _TRAILING_WORD = re.compile(r'([A-Za-z][A-Za-z.]*)$')
 _URL = re.compile(r'\b(?:https?://|www\.)\S+')
 # A span opened by two backticks, as reStructuredText writes code, closes on two.
@@ -29,6 +32,7 @@ _FENCE = re.compile(r'^\s*(```|~~~)')
 _LIST_DELIMITER = re.compile(r'^\s*(?:[0-9]+[.)]|[-*+]|[a-zA-Z][.)])\s')
 _LITERAL_DELIMITER = '\\b'
 _CLOSING_MARKS = '"\')]}'
+_OPENING_MARKS = '"\'([{'
 _APOSTROPHES = ("'", '\u2019')
 
 # Only before a number, since "No. 5" abbreviates while a trailing no ends its sentence.
@@ -60,12 +64,12 @@ class ProseMarkup:
     """What a language writes in its comments besides prose, which reflow leaves as written.
 
     A tag section, such as JSDoc's from its first @throws on, runs to the end of the comment.
-    An example tag's body is code, and so is a line commented out of a language whose statements look like one.
+    An example tag's body is code, and so is a line that the language's grammar reads as code commented out.
     """
 
     tag_section: re.Pattern[str] | None = None
     example_tag: str | None = None
-    code_line: re.Pattern[str] | None = None
+    code_line: typing.Callable[[str], bool] | None = None
 
     def opens_tag_section(self, line: str) -> bool:
         return self.tag_section is not None and bool(self.tag_section.match(line))
@@ -74,7 +78,7 @@ class ProseMarkup:
         return self.example_tag is not None and line.strip().startswith(self.example_tag)
 
     def is_code(self, line: str) -> bool:
-        return self.code_line is not None and bool(self.code_line.search(line))
+        return self.code_line is not None and self.code_line(line)
 
 
 PLAIN_MARKUP = ProseMarkup()
@@ -106,7 +110,8 @@ class Prose:
                 current_lines = []
             segment_is_literal = next_is_literal
 
-        for line in self.physical_lines:
+        lines = self.physical_lines
+        for previous_line, line in zip(('', *lines), lines, strict=False):
             stripped_line = line.strip()
             inside_tags = inside_tags or self.markup.opens_tag_section(line)
             if inside_tags:
@@ -132,7 +137,7 @@ class Prose:
                 continue
             if self._is_list_item(line):
                 inside_list = True
-            elif not self._continues_list_item(line, inside_list):
+            elif not self._continues_list_item(line, previous_line, inside_list):
                 inside_list = False
             # The indented body under a commented-out opening brace is code too.
             inside_code = self.markup.is_code(line) or (inside_code and line[:1].isspace())
@@ -167,13 +172,15 @@ class Prose:
                 indexes.add(index)
         return frozenset(indexes)
 
+    # A line set two spaces past the margin, such as a tree diagram or an aligned table, is laid out by hand.
+    # Markdown wants four for a code block, but a comment's prefix already takes the space a writer would count.
     def _is_indented(self, line: str) -> bool:
-        return line.startswith(('    ', '\t'))
+        return line.startswith(('  ', '\t'))
 
-    # A wrapped list item is indented under its marker rather than to a fixed width,
+    # A wrapped list item is indented under its marker, or left at the margin while its sentence runs on,
     # so the continuation belongs to the item instead of opening a paragraph.
-    def _continues_list_item(self, line: str, inside_list: bool) -> bool:
-        return inside_list and line[:1].isspace()
+    def _continues_list_item(self, line: str, previous_line: str, inside_list: bool) -> bool:
+        return inside_list and (line[:1].isspace() or not _ENDS_A_SENTENCE.search(previous_line))
 
     def _is_list_item(self, line: str) -> bool:
         return bool(_LIST_DELIMITER.match(line))
@@ -234,10 +241,19 @@ class Prose:
             return False
         if word == NUMBER_ABBREVIATION and text[offset + 1 :].lstrip()[:1].isdigit():
             return False
-        if trailing_word and len(trailing_word.group(1).replace('.', '')) == 1:
+        if (
+            trailing_word
+            and len(trailing_word.group(1).replace('.', '')) == 1
+            and self._stands_alone(text, trailing_word)
+        ):
             return False
         return self._followed_by_break(text, offset)
 
+    # An initial stands as a word of its own, so a letter closing Ctrl+C or a plural such as `Event`s is none.
+    def _stands_alone(self, text: str, trailing_word: re.Match[str]) -> bool:
+        before = text[: trailing_word.start()]
+        return not before or before[-1].isspace() or before[-1] in _OPENING_MARKS
+
     def _followed_by_break(self, text: str, offset: int) -> bool:
         rest = text[offset + 1 :]
         if not rest:

{subedit-0.2.0 → subedit-0.3.1}/src/subedit/domain/models/prose_map.py

@@ -15,11 +15,14 @@ class ProseMap:
 
     editable: tuple[SourceRange, ...] = ()
     code: tuple[SourceRange, ...] = ()
+    # A directive's text, such as the reason after @ts-expect-error, is read by a tool, so nothing reads it as prose.
+    directives: tuple[SourceRange, ...] = ()
 
     @classmethod
-    def of_comments(cls, groups: tuple[CommentGroup, ...]) -> 'ProseMap':
+    def of_comments(cls, groups: tuple[CommentGroup, ...], directives: tuple[SourceRange, ...] = ()) -> 'ProseMap':
         """A trailing comment shares its line with code, so only a comment standing on its own lines is editable."""
         return cls(
+            directives=directives,
             editable=tuple(
                 line.range
                 for group in groups
@@ -31,7 +34,7 @@ class ProseMap:
 
     def admits(self, diagnostic: Diagnostic) -> bool:
         """Whether a finding reads prose rather than code, and any edit it offers stays on lines of prose."""
-        if any(code_range.start <= diagnostic.range.start < code_range.end for code_range in self.code):
+        if any(region.start <= diagnostic.range.start < region.end for region in (*self.code, *self.directives)):
             return False
         if diagnostic.fix is None:
             return True

{subedit-0.2.0 → subedit-0.3.1}/src/subedit/domain/models/text.py

@@ -10,6 +10,19 @@ class TextEdit:
     new_text: str
 
 
+def source_lines(text: str) -> list[str]:
+    """The lines a source file holds, each with its newline, split where a newline falls and nowhere else.
+
+    str.splitlines also splits at characters such as a form feed or a record separator,
+    which leave a line's number out of step with what an editor, patch, and PositionMap count.
+    """
+    pieces = text.split('\n')
+    lines = [piece + '\n' for piece in pieces[:-1]]
+    if pieces[-1]:
+        lines.append(pieces[-1])
+    return lines
+
+
 def apply_edits(text: str, edits: tuple[TextEdit, ...]) -> str:
     if not edits:
         return text

{subedit-0.2.0 → subedit-0.3.1}/src/subedit/domain/ports/source_parser.py

@@ -2,6 +2,7 @@ import abc
 
 from ..models.comment import CommentGroup
 from ..models.document import Document
+from ..models.position import SourceRange
 
 
 class SourceParser(abc.ABC):
@@ -10,3 +11,7 @@ class SourceParser(abc.ABC):
 
     @abc.abstractmethod
     def parse(self, document: Document) -> tuple[CommentGroup, ...]: ...
+
+    def directive_ranges(self, document: Document) -> tuple[SourceRange, ...]:
+        """Where a comment holds a directive such as eslint-disable or noqa, which a tool reads instead of a person."""
+        return ()

{subedit-0.2.0 → subedit-0.3.1}/src/subedit/domain/rules/layout.py

@@ -30,8 +30,9 @@ class MidClauseBreakRule(Rule):
             rule_id=self.metadata.rule_id,
             range=group.range,
             message=(
-                'Comment layout differs from one sentence per line. '
-                'A sentence that fits takes one line, and a longer one breaks only at a comma ending a clause.'
+                'Comment layout breaks a sentence where it need not. '
+                'A sentence that fits takes one line, and a longer one breaks only at a comma ending a clause. '
+                'Short sentences may share a line that fits.'
             ),
             fix=Fix.reflow(reflowed.as_edit()),
         )

{subedit-0.2.0 → subedit-0.3.1}/src/subedit/domain/rules/rewrite.py

@@ -1,6 +1,6 @@
 import typing
 
-from ..models.comment import CommentGroup
+from ..models.comment import CommentGroup, CommentPlacement
 from ..models.diagnostic import Diagnostic, Fix, FixKind, RuleMetadata, Severity
 from ..models.prose import Prose, reflow_sentence
 from ..ports.rule import Rule, RuleContext
@@ -60,6 +60,9 @@ class StubFragmentRule(Rule):
     metadata = STUB_FRAGMENT
 
     def check(self, group: CommentGroup, context: RuleContext) -> typing.Iterable[Diagnostic]:
+        # A trailing comment never breaks, so a rule judging where a sentence breaks leaves it to line-too-long.
+        if group.placement is CommentPlacement.TRAILING:
+            return
         minimum_length = stub_floor(context)
         for index, (sentence, budget) in enumerate(budgeted_sentences(group, context)):
             if is_summary(group, index):
@@ -87,6 +90,9 @@ class UnbreakableSentenceRule(Rule):
     metadata = UNBREAKABLE_SENTENCE
 
     def check(self, group: CommentGroup, context: RuleContext) -> typing.Iterable[Diagnostic]:
+        # A trailing comment never breaks, so its width is line-too-long's to judge.
+        if group.placement is CommentPlacement.TRAILING:
+            return
         sentences = budgeted_sentences(group, context)
         for index, (sentence, budget) in enumerate(sentences):
             if is_summary(group, index):

{subedit-0.2.0 → subedit-0.3.1}/src/subedit/domain/rules/structure.py

@@ -70,15 +70,24 @@ class PlainCommentOnPublicRule(Rule):
         if conventions is None:
             return
         delimiter = conventions.doc_delimiter
-        name = group.attachment.name if group.attachment else 'the symbol'
+        attachment = group.attachment
+        name = attachment.name if attachment else 'the symbol'
+        message = (
+            f'{name} is public but documented with a plain comment. '
+            f'Move the text into a {delimiter} doc comment so tooling renders it on hover.'
+        )
+        may_head_a_group = attachment is not None and attachment.may_head_a_group
+        if may_head_a_group:
+            message += (
+                f' If it heads the declarations below it as a group rather than describing {name}, leave it, '
+                'or set it apart with a blank line above it.'
+            )
         yield Diagnostic(
             rule_id=self.metadata.rule_id,
             range=group.range,
-            message=(
-                f'{name} is public but documented with a plain comment. '
-                f'Move the text into a {delimiter} doc comment so tooling renders it on hover.'
-            ),
+            message=message,
             fix=Fix.rewrite(),
+            tentative=may_head_a_group,
         )
 
 

{subedit-0.2.0 → subedit-0.3.1}/src/subedit/infrastructure/__init__.py

@@ -10,7 +10,7 @@ from ..domain.rules import (
     StubFragmentRule,
     UnbreakableSentenceRule,
 )
-from .config_sources import CONFIG_NAME, TomlConfigSource
+from .config_sources import CONFIG_NAME, FormatterWidths, TomlConfigSource
 from .linters import AutoCorrectLinter, ValeLinter
 from .parsers import PYTHON, TSX, TYPESCRIPT, LanguageProfile, NodeRole, TreeSitterParser
 
@@ -38,7 +38,9 @@ ALL_RULES = LAYOUT_RULES + REWRITE_RULES + STRUCTURAL_RULES
 DEFAULT_PARSER = TreeSitterParser(LANGUAGES)
 DEFAULT_CONFIG_SOURCE = TomlConfigSource(
     tuple(rule.metadata.rule_id for rule in ALL_RULES),
-    {extension: language.default_line_width for language in LANGUAGES for extension in language.extensions},
+    FormatterWidths(
+        {extension: language.width_settings for language in LANGUAGES for extension in language.extensions}
+    ),
 )
 
 

{subedit-0.2.0 → subedit-0.3.1}/src/subedit/infrastructure/config_sources/__init__.py

@@ -1,11 +1,14 @@
 from .config_schema import ConfigFile, RuleTable, SubeditSection
+from .formatter_width import FormatterWidths, WidthSetting
 from .toml_config_source import CONFIG_NAME, TomlConfigSource
 
 
 __all__ = [
     'CONFIG_NAME',
     'ConfigFile',
+    'FormatterWidths',
     'RuleTable',
     'SubeditSection',
     'TomlConfigSource',
+    'WidthSetting',
 ]

subedit-0.3.1/src/subedit/infrastructure/config_sources/formatter_width.py

@@ -0,0 +1,92 @@
+import dataclasses
+import json
+import pathlib
+import re
+import tomllib
+import typing
+
+
+# A string is matched first, so a URL inside one, as a $schema value holds, keeps its slashes.
+_JSON_COMMENT = re.compile(r'("(?:\\.|[^"\\])*")|//[^\n]*|/\*.*?\*/', re.DOTALL)
+_TRAILING_COMMA = re.compile(r',(\s*[}\]])')
+
+
+def _without_comments(text: str) -> str:
+    """JSON with the comments and trailing commas that JSONC allows taken out, as biome.jsonc writes it."""
+    return _TRAILING_COMMA.sub(r'\1', _JSON_COMMENT.sub(lambda found: found.group(1) or '', text))
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class WidthSetting:
+    """Where a formatter keeps its line width, such as line-length under [tool.ruff] in pyproject.toml."""
+
+    file_name: str
+    key_path: tuple[str, ...]
+
+    def read(self, directory: pathlib.Path) -> int | None:
+        config_path = directory / self.file_name
+        if not config_path.is_file():
+            return None
+        try:
+            text = config_path.read_text(encoding='utf-8')
+        except OSError:
+            return None
+        return self._width_in(self._parse(text, config_path.suffix))
+
+    def _parse(self, text: str, suffix: str) -> object:
+        if suffix == '.toml':
+            try:
+                return tomllib.loads(text)
+            except tomllib.TOMLDecodeError:
+                return None
+        for candidate in (text, _without_comments(text)):
+            try:
+                return json.loads(candidate)
+            except json.JSONDecodeError:
+                continue
+        return self._parse_flat(text)
+
+    # A YAML .prettierrc holds a top-level key on a line of its own.
+    def _parse_flat(self, text: str) -> object:
+        if len(self.key_path) != 1:
+            return None
+        (key,) = self.key_path
+        found = re.search(rf'^{re.escape(key)}\s*:\s*(\d+)\s*$', text, re.MULTILINE)
+        return {key: int(found.group(1))} if found else None
+
+    def _width_in(self, table: object) -> int | None:
+        for key in self.key_path:
+            if not isinstance(table, dict):
+                return None
+            table = typing.cast(dict[str, object], table).get(key)
+        return table if isinstance(table, int) and not isinstance(table, bool) and table > 0 else None
+
+
+class FormatterWidths:
+    """The line width a project's own formatter sets, found the way the formatter finds its config.
+
+    The search climbs from the file toward the root, and the nearest directory that sets a width wins.
+    A formatter left at its own default sets nothing here, so the width falls back to subedit's default.
+    """
+
+    def __init__(self, settings_by_suffix: typing.Mapping[str, tuple[WidthSetting, ...]]) -> None:
+        self._settings_by_suffix = dict(settings_by_suffix)
+        self._widths: dict[tuple[pathlib.Path, tuple[WidthSetting, ...]], int | None] = {}
+
+    def width_for(self, path: str) -> int | None:
+        settings = self._settings_by_suffix.get(pathlib.Path(path).suffix)
+        if not settings:
+            return None
+        start = pathlib.Path(path)
+        directory = (start if start.is_dir() else start.parent).resolve()
+        if (directory, settings) not in self._widths:
+            self._widths[directory, settings] = self._width_from(directory, settings)
+        return self._widths[directory, settings]
+
+    def _width_from(self, directory: pathlib.Path, settings: tuple[WidthSetting, ...]) -> int | None:
+        for candidate in (directory, *directory.parents):
+            for setting in settings:
+                width = setting.read(candidate)
+                if width is not None:
+                    return width
+        return None