subedit 0.1.4__tar.gz → 0.2.0__tar.gz

{subedit-0.1.4 → subedit-0.2.0}/.vale.ini

@@ -1,7 +1,7 @@
 StylesPath = src/subedit/vale/styles
 MinAlertLevel = warning
 
-[*.{py,ts,tsx,js,go,rs}]
+[*.{py,pyi,ts,mts,cts,tsx,js,go,rs}]
 BasedOnStyles = subedit
 subedit.MidSentenceColonMarkup = NO
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: subedit
-Version: 0.1.4
+Version: 0.2.0
 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
@@ -8,7 +8,7 @@ Project-URL: Issues, https://github.com/mroops0111/subedit/issues
 Author: Yun-Tai Yang
 License: MIT
 License-File: LICENSE
-Keywords: comments,formatter,linter,lsp,prose,tree-sitter
+Keywords: comments,formatter,linter,lsp,prose,python,tree-sitter,typescript
 Classifier: Development Status :: 1 - Planning
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -21,13 +21,13 @@ Requires-Python: >=3.11
 Requires-Dist: autocorrect-py>=2.14.0
 Requires-Dist: pydantic>=2.13.5
 Requires-Dist: tree-sitter-python>=0.25.0
+Requires-Dist: tree-sitter-typescript>=0.23.2
 Requires-Dist: tree-sitter>=0.26.0
 Requires-Dist: typer>=0.27.2
 Provides-Extra: dev
 Requires-Dist: basedpyright>=1.40.1; extra == 'dev'
 Requires-Dist: pytest>=9.0.0; extra == 'dev'
 Requires-Dist: ruff>=0.16.7; extra == 'dev'
-Requires-Dist: tree-sitter-typescript>=0.23.2; extra == 'dev'
 Provides-Extra: vale
 Requires-Dist: vale>=3.22.0.0; extra == 'vale'
 Description-Content-Type: text/markdown
@@ -149,13 +149,25 @@ Add this to `~/.codex/hooks.json`.
 
 Registering the hook with both agents is the normal case. Each agent names its edit tools differently, so every payload identifies its sender, and a payload from anything else exits 0 untouched. `subedit-hook --help` prints the payload shapes it accepts.
 
+## Languages
+
+| Language | Files | Doc comment | Default width |
+| --- | --- | --- | --- |
+| Python | `.py`, `.pyi` | `"""` docstring | 120 |
+| TypeScript | `.ts`, `.mts`, `.cts`, `.tsx` | `/** */` JSDoc | 80, as Prettier sets it |
+
+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 `/* */` 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`.
+
 ## Configuration
 
 Settings come from `subedit.toml`, or from `[tool.subedit]` in `pyproject.toml`, whichever sits closest above the file being checked.
 
 ```toml
 [subedit]
-line-width = 120
+line-width = 100
 exclude = ["tests/fixtures/**"]
 
 [rules]
@@ -163,6 +175,8 @@ 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.
+
 Rule names describe the problem they report. `docs/rules.md` lists every rule, generated from the rules themselves.
 
 A rule at `error` fails `check` and stops an agent, while one at `warning` is shown as advice and blocks nothing. The same table sets the delegated Vale rules by name.
@@ -194,12 +208,12 @@ Code comments are the first surface, and Markdown comes next.
 
 ## Related Tools
 
-`subedit` covers the one thing the usual Python tools leave alone.
+`subedit` covers the one thing the usual linters and type checkers leave alone.
 
 | Tool | Checks |
 | --- | --- |
-| ruff | code structure |
-| basedpyright | types |
+| ruff, ESLint | code structure |
+| basedpyright, tsc | types |
 | **subedit** | **the natural language inside source** |
 
 ## License

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

@@ -115,13 +115,25 @@ Add this to `~/.codex/hooks.json`.
 
 Registering the hook with both agents is the normal case. Each agent names its edit tools differently, so every payload identifies its sender, and a payload from anything else exits 0 untouched. `subedit-hook --help` prints the payload shapes it accepts.
 
+## Languages
+
+| Language | Files | Doc comment | Default width |
+| --- | --- | --- | --- |
+| Python | `.py`, `.pyi` | `"""` docstring | 120 |
+| TypeScript | `.ts`, `.mts`, `.cts`, `.tsx` | `/** */` JSDoc | 80, as Prettier sets it |
+
+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 `/* */` 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`.
+
 ## Configuration
 
 Settings come from `subedit.toml`, or from `[tool.subedit]` in `pyproject.toml`, whichever sits closest above the file being checked.
 
 ```toml
 [subedit]
-line-width = 120
+line-width = 100
 exclude = ["tests/fixtures/**"]
 
 [rules]
@@ -129,6 +141,8 @@ 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.
+
 Rule names describe the problem they report. `docs/rules.md` lists every rule, generated from the rules themselves.
 
 A rule at `error` fails `check` and stops an agent, while one at `warning` is shown as advice and blocks nothing. The same table sets the delegated Vale rules by name.
@@ -160,12 +174,12 @@ Code comments are the first surface, and Markdown comes next.
 
 ## Related Tools
 
-`subedit` covers the one thing the usual Python tools leave alone.
+`subedit` covers the one thing the usual linters and type checkers leave alone.
 
 | Tool | Checks |
 | --- | --- |
-| ruff | code structure |
-| basedpyright | types |
+| ruff, ESLint | code structure |
+| basedpyright, tsc | types |
 | **subedit** | **the natural language inside source** |
 
 ## License

{subedit-0.1.4 → subedit-0.2.0}/docs/rules.md

@@ -15,4 +15,4 @@ The level says whether a rewrite blocks. An error fails check and stops an agent
 | `plain-comment-on-public` | rewrite | error | A public symbol must be documented in the doc comment form its language renders. |
 | `signature-restating-tag` | rewrite | error | A doc comment must not restate what the type signature already carries. |
 | `stub-fragment` | rewrite | warning | A sentence forced to break must not leave a stub of a line behind. |
-| `unbreakable-sentence` | rewrite | error | A sentence over the width must carry a clause comma wherever it has to break. |
+| `unbreakable-sentence` | rewrite | error | A sentence over the width must carry a clause comma, splitting no list, wherever it has to break, and a summary its style guide keeps to one line must fit it. |

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

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

{subedit-0.1.4 → subedit-0.2.0}/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.1.4'
+SPEC='subedit[vale]>=0.2.0'
 # A bare uvx takes the first Python it finds, which on a stock Mac is too old for subedit.
 PYTHON='>=3.11'
 

{subedit-0.1.4 → subedit-0.2.0}/plugins/subedit/skills/judging-findings/SKILL.md

@@ -36,8 +36,9 @@ A warning passes when the text meets its criterion. Leave such text exactly as i
 
 An error always needs a rewrite. The message states the fix, and these notes cover what it leaves out.
 
-- `unbreakable-sentence`: a line can break only at a comma that ends a clause, and a comma inside brackets or a code span does not count. Add a comma at a clause boundary, or split the sentence in two.
-- `plain-comment-on-public`: move the text into the docstring.
+- `unbreakable-sentence`: a line can break only at a comma that ends a clause, and a comma inside brackets or a code span does not count. Add a comma at a clause boundary, or split the sentence in two. When every such comma would split a list, move the list to the end of the sentence. When the message names a style guide that keeps a summary to one line, shorten the summary and move the detail into the body.
+- `line-too-long` (trailing comment): a comment beside code cannot break, so shorten it or move it to its own line above the code.
+- `plain-comment-on-public`: move the text into the doc comment, a docstring in Python or a `/** */` block in TypeScript.
 - `signature-restating-tag` and `subedit.SignatureTag`: delete the tag, since the signature already says it.
 - `subedit.EditHistory`: state the current behavior, not its history.
 - `subedit.Semicolon`, `subedit.EmDash`: split into two sentences, or use a comma or parentheses.

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

@@ -1,6 +1,6 @@
 [project]
 name = "subedit"
-version = "0.1.4"
+version = "0.2.0"
 description = "A linter and formatter for the prose inside code comments, across languages."
 authors = [
     {name = "Yun-Tai Yang"},
@@ -8,7 +8,7 @@ authors = [
 readme = "README.md"
 license = {text = "MIT"}
 requires-python = ">=3.11"
-keywords = ["linter", "formatter", "comments", "prose", "lsp", "tree-sitter"]
+keywords = ["linter", "formatter", "comments", "prose", "lsp", "tree-sitter", "python", "typescript"]
 classifiers = [
     "Development Status :: 1 - Planning",
     "Intended Audience :: Developers",
@@ -25,6 +25,7 @@ dependencies = [
     "pydantic>=2.13.5",
     "tree-sitter>=0.26.0",
     "tree-sitter-python>=0.25.0",
+    "tree-sitter-typescript>=0.23.2",
     "typer>=0.27.2",
 ]
 
@@ -33,7 +34,6 @@ dev = [
     "pytest>=9.0.0",
     "basedpyright>=1.40.1",
     "ruff>=0.16.7",
-    "tree-sitter-typescript>=0.23.2",
 ]
 vale = [
     "vale>=3.22.0.0",

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

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

{subedit-0.1.4 → subedit-0.2.0}/src/subedit/application/__init__.py

@@ -1,6 +1,6 @@
 from .corpus_meter import CorpusMeter, CorpusStatistics, Distribution
 from .fixer import Fixer, FixResult
-from .linter import Linter, RuleEngine
+from .linter import Inspection, Linter, RuleEngine
 from .report_aggregator import ReportAggregator
 
 
@@ -10,6 +10,7 @@ __all__ = [
     'Distribution',
     'FixResult',
     'Fixer',
+    'Inspection',
     'Linter',
     'ReportAggregator',
     'RuleEngine',

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

@@ -3,6 +3,7 @@ import dataclasses
 from ..domain.models.comment import CommentGroup
 from ..domain.models.diagnostic import Diagnostic, Report
 from ..domain.models.document import Document
+from ..domain.models.prose_map import ProseMap
 from ..domain.models.rule_set import RuleSet
 from ..domain.ports import SourceParser
 from ..domain.ports.rule import Rule, RuleContext
@@ -41,15 +42,26 @@ class RuleEngine:
         return duplicate_ids
 
 
+@dataclasses.dataclass(frozen=True, slots=True)
+class Inspection:
+    """What one parse of a document yields, the findings and the map of where its prose lies."""
+
+    report: Report = dataclasses.field(default_factory=Report)
+    prose_map: ProseMap = dataclasses.field(default_factory=ProseMap)
+
+
 class Linter:
     def __init__(self, parser: SourceParser, engine: RuleEngine) -> None:
         self._parser = parser
         self._engine = engine
 
     def run(self, document: Document, rule_set: RuleSet) -> Report:
+        return self.inspect(document, rule_set).report
+
+    def inspect(self, document: Document, rule_set: RuleSet) -> Inspection:
         if not self._parser.supports(document.language_id):
-            return Report()
+            return Inspection()
         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 Report(tuple(sorted_diagnostics))
+        return Inspection(Report(tuple(sorted_diagnostics)), ProseMap.of_comments(groups))

{subedit-0.1.4 → subedit-0.2.0}/src/subedit/application/report_aggregator.py

@@ -13,13 +13,15 @@ class ReportAggregator:
         self._external_linters = external_linters
 
     def run(self, document: Document, rule_set: RuleSet) -> Report:
-        report = self._linter.run(document, rule_set)
+        inspection = self._linter.inspect(document, rule_set)
+        report = inspection.report
         missing_sources: list[str] = []
         for external_linter in self._external_linters:
             if not external_linter.is_available():
                 missing_sources.append(external_linter.name)
                 continue
-            report = report.merged_with(Report(self._configured(external_linter.run(document), rule_set)))
+            found = tuple(item for item in external_linter.run(document) if inspection.prose_map.admits(item))
+            report = report.merged_with(Report(self._configured(found, rule_set)))
         if missing_sources:
             report = report.merged_with(Report(unavailable_sources=tuple(missing_sources)))
         return report

{subedit-0.1.4 → subedit-0.2.0}/src/subedit/domain/__init__.py

@@ -1,7 +1,11 @@
 from .models import (
+    LINE_LAYOUT,
+    PLAIN_MARKUP,
+    QUOTED_DOC_LAYOUT,
     SEVERITY_BY_NAME,
     CommentForm,
     CommentGroup,
+    CommentLayout,
     CommentLine,
     CommentPlacement,
     Diagnostic,
@@ -9,9 +13,14 @@ from .models import (
     Encoding,
     Fix,
     FixKind,
+    FramedDocLayout,
+    LinePrefixLayout,
     Position,
     PositionMap,
     Prose,
+    ProseMap,
+    ProseMarkup,
+    QuotedDocLayout,
     Report,
     RuleMetadata,
     RuleSet,
@@ -29,9 +38,13 @@ from .ports import DelimiterSplit, ExternalLinter, LanguageConventions, Rule, Ru
 
 
 __all__ = [
+    'LINE_LAYOUT',
+    'PLAIN_MARKUP',
+    'QUOTED_DOC_LAYOUT',
     'SEVERITY_BY_NAME',
     'CommentForm',
     'CommentGroup',
+    'CommentLayout',
     'CommentLine',
     'CommentPlacement',
     'DelimiterSplit',
@@ -41,10 +54,15 @@ __all__ = [
     'ExternalLinter',
     'Fix',
     'FixKind',
+    'FramedDocLayout',
     'LanguageConventions',
+    'LinePrefixLayout',
     'Position',
     'PositionMap',
     'Prose',
+    'ProseMap',
+    'ProseMarkup',
+    'QuotedDocLayout',
     'Report',
     'Rule',
     'RuleContext',

{subedit-0.1.4 → subedit-0.2.0}/src/subedit/domain/models/__init__.py

@@ -1,16 +1,37 @@
-from .comment import CommentForm, CommentGroup, CommentLine, CommentPlacement, SymbolKind, SymbolRef, Visibility
+from .comment import (
+    CommentForm,
+    CommentGroup,
+    CommentLine,
+    CommentPlacement,
+    SymbolKind,
+    SymbolRef,
+    Visibility,
+)
+from .comment_layout import (
+    LINE_LAYOUT,
+    QUOTED_DOC_LAYOUT,
+    CommentLayout,
+    FramedDocLayout,
+    LinePrefixLayout,
+    QuotedDocLayout,
+)
 from .diagnostic import SEVERITY_BY_NAME, Diagnostic, Fix, FixKind, Report, RuleMetadata, Severity
 from .document import Document
 from .position import Encoding, Position, PositionMap, SourceRange
-from .prose import Prose, Sentence
+from .prose import PLAIN_MARKUP, Prose, ProseMarkup, Sentence
+from .prose_map import ProseMap
 from .rule_set import RuleSet, RuleSettings
 from .text import TextEdit, apply_edits
 
 
 __all__ = [
+    'LINE_LAYOUT',
+    'PLAIN_MARKUP',
+    'QUOTED_DOC_LAYOUT',
     'SEVERITY_BY_NAME',
     'CommentForm',
     'CommentGroup',
+    'CommentLayout',
     'CommentLine',
     'CommentPlacement',
     'Diagnostic',
@@ -18,9 +39,14 @@ __all__ = [
     'Encoding',
     'Fix',
     'FixKind',
+    'FramedDocLayout',
+    'LinePrefixLayout',
     'Position',
     'PositionMap',
     'Prose',
+    'ProseMap',
+    'ProseMarkup',
+    'QuotedDocLayout',
     'Report',
     'RuleMetadata',
     'RuleSet',

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

@@ -2,8 +2,9 @@ import dataclasses
 import enum
 import itertools
 
+from .comment_layout import LINE_LAYOUT, CommentLayout, CommentLine
 from .position import SourceRange
-from .prose import Prose, Sentence, break_cost, comma_breaks, reflow_sentence
+from .prose import PLAIN_MARKUP, Prose, ProseMarkup, Sentence, break_cost, comma_breaks, reflow_sentence
 from .text import TextEdit
 
 
@@ -38,28 +39,6 @@ class SymbolRef:
     visibility: Visibility
 
 
-@dataclasses.dataclass(frozen=True, slots=True)
-class CommentLine:
-    range: SourceRange
-    indent: str
-    delimiter: str
-    text: str
-    suffix: str = ''
-
-    @property
-    def physical_width(self) -> int:
-        return len(self.indent) + len(self.delimiter) + len(self.text) + len(self.suffix)
-
-    @property
-    def prefix_width(self) -> int:
-        return len(self.indent) + len(self.delimiter)
-
-    def render(self) -> str:
-        if not self.text and not self.suffix:
-            return (self.indent + self.delimiter).rstrip()
-        return self.indent + self.delimiter + self.text + self.suffix
-
-
 @dataclasses.dataclass(frozen=True, slots=True)
 class CommentGroup:
     range: SourceRange
@@ -67,6 +46,8 @@ class CommentGroup:
     form: CommentForm
     placement: CommentPlacement
     attachment: SymbolRef | None = None
+    layout: CommentLayout = LINE_LAYOUT
+    markup: ProseMarkup = PLAIN_MARKUP
 
     def __post_init__(self) -> None:
         if not self.lines:
@@ -85,6 +66,11 @@ class CommentGroup:
     def longest_line(self) -> int:
         return max(line.physical_width for line in self.lines)
 
+    @property
+    def has_summary_line(self) -> bool:
+        """Whether the first sentence is a one-line summary, as a style guide such as PEP 257 asks."""
+        return self.layout.summary_convention is not None
+
     @property
     def attaches_to_public_symbol(self) -> bool:
         return self.attachment is not None and self.attachment.visibility is Visibility.PUBLIC
@@ -96,51 +82,72 @@ class CommentGroup:
             ' ' * max(0, len(line.indent) - base) + line.text.rstrip() if line.text.strip() else ''
             for line in self.lines
         ]
-        return Prose('\n'.join(rendered_lines))
+        return Prose('\n'.join(rendered_lines), self.markup)
+
+    def code_ranges(self) -> tuple[SourceRange, ...]:
+        """Where the lines holding code sit, which a prose checker has no business reading."""
+        return tuple(self.lines[index].range for index in sorted(self.prose().code_line_indexes()))
 
     def reflow(self, width: int, stub_floor: int = 0) -> 'CommentGroup':
+        # A trailing comment shares its line with code, so a second line would have no code to sit beside.
+        if self.placement is CommentPlacement.TRAILING:
+            return self
         # A one line docstring that fits is the summary convention, not a block to lay out.
         if self.form is CommentForm.DOC and self.line_count == 1 and self.longest_line <= width:
             return self
         texts = self._reflow_into_texts(width, stub_floor)
         # Text that ends up on one line closes there too, so the closing quotes need room beside it.
-        closing_width = len(self._closing_quotes())
+        closing_width = len(self.closing())
         if len(texts) == 1 and len(texts[0]) > self.text_budget(width, first_line=True) - closing_width:
             texts = self._reflow_into_texts(width, stub_floor, closing_width)
         if not texts:
             return self
-        return self._rebuild_lines(texts)
+        return dataclasses.replace(self, lines=self.layout.rebuild(self.lines, texts, width))
+
+    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."""
+        held: list[str] = []
+        self._reflow_into_texts(width, stub_floor, held=held)
+        return tuple(held)
 
     def text_budget(self, width: int, *, first_line: bool) -> int:
         """The characters of text a line holds, which on a docstring's opening line also cede the quotes."""
-        opening = self.lines[0]
-        quoted = first_line or self.form is not CommentForm.DOC
-        return max(20, width - (opening.prefix_width if quoted else len(opening.indent)))
+        return self.layout.text_budget(self.lines, width, first_line=first_line)
 
     # A sentence takes as few lines as fit, and the author's layout stays when it breaks no worse than the best one.
-    # A sentence whose new layout would strand a stub or still overflow needs its author,
+    # A sentence whose new layout would strand a stub, split a list, or still overflow needs its author,
     # so it keeps the layout they gave it rather than one its own check rejects.
-    def _reflow_into_texts(self, width: int, stub_floor: int, reserve: int = 0) -> tuple[str, ...]:
+    # A summary never breaks where the comment's style guide keeps it to one line.
+    def _reflow_into_texts(
+        self, width: int, stub_floor: int, reserve: int = 0, held: list[str] | None = None
+    ) -> tuple[str, ...]:
         body_budget = self.text_budget(width, first_line=False)
         out: list[str] = []
-        for paragraph_index, (paragraph, is_literal) in enumerate(self._split_into_paragraphs()):
-            if out:
+        for paragraph_index, (paragraph, is_literal, follows_blank) in enumerate(self._split_into_paragraphs()):
+            if out and (follows_blank or self.layout.parts_every_paragraph):
                 out.append('')
             if is_literal:
                 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()):
-                if sentence_index == 1 and paragraph_index == 0 and self.form is CommentForm.DOC:
+                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)
-                best_lines = reflow_sentence(sentence.text, body_budget, stub_floor, first_width=first_budget)
+                if self.has_summary_line and paragraph_index == 0 and sentence_index == 0:
+                    best_lines: tuple[str, ...] = (sentence.text,)
+                else:
+                    best_lines = reflow_sentence(sentence.text, body_budget, stub_floor, first_width=first_budget)
                 given_lines = _given_lines(lines, sentence)
                 if given_lines and _keeps_given(given_lines, best_lines, (first_budget, body_budget), stub_floor):
                     out.extend(given_lines)
-                elif _is_legal(best_lines, (first_budget, body_budget), stub_floor):
+                elif _is_legal(best_lines, (first_budget, body_budget), stub_floor) and not (
+                    given_lines and break_cost(best_lines)
+                ):
                     out.extend(best_lines)
                 elif given_lines:
+                    if held is not None and _is_legal(best_lines, (first_budget, body_budget), stub_floor):
+                        held.append(sentence.text)
                     out.extend(given_lines)
                 elif _strands_stub(best_lines, stub_floor):
                     return ()
@@ -148,55 +155,28 @@ class CommentGroup:
                     out.extend(best_lines)
         return tuple(out)
 
-    def _split_into_paragraphs(self) -> tuple[tuple[tuple[str, ...], bool], ...]:
-        paragraphs: list[tuple[tuple[str, ...], bool]] = []
+    def _split_into_paragraphs(self) -> tuple[tuple[tuple[str, ...], bool, bool], ...]:
+        """Each paragraph's lines, whether they are literal, and whether a blank line comes before them."""
+        paragraphs: list[tuple[tuple[str, ...], bool, bool]] = []
+        follows_blank = False
         for segment in self.prose().segments():
             current_lines: list[str] = []
             for line in segment.lines:
                 if line.strip():
                     current_lines.append(line)
-                elif current_lines:
-                    paragraphs.append((tuple(current_lines), segment.is_literal))
+                    continue
+                if current_lines:
+                    paragraphs.append((tuple(current_lines), segment.is_literal, follows_blank))
                     current_lines = []
+                follows_blank = True
             if current_lines:
-                paragraphs.append((tuple(current_lines), segment.is_literal))
+                paragraphs.append((tuple(current_lines), segment.is_literal, follows_blank))
+                follows_blank = False
         return tuple(paragraphs)
 
-    def _rebuild_lines(self, texts: tuple[str, ...]) -> 'CommentGroup':
-        if self.form is not CommentForm.DOC:
-            return self.with_texts(texts)
-        opening, closing = self.lines[0], self.lines[-1]
-        closes_alone = len(self.lines) > 1 and not closing.text.strip()
-        body = [dataclasses.replace(opening, delimiter='', suffix='', text=text, range=opening.range) for text in texts]
-        body[0] = dataclasses.replace(body[0], delimiter=opening.delimiter)
-        # Text that fits one line closes on that line, as ruff and black format it.
-        if len(texts) > 1:
-            body.append(
-                dataclasses.replace(closing, delimiter=closing.delimiter or opening.delimiter, text='', suffix='')
-            )
-            if not closes_alone:
-                body[-1] = dataclasses.replace(body[-1], delimiter=opening.delimiter.strip())
-        else:
-            body[0] = dataclasses.replace(body[0], suffix=self._closing_quotes())
-        return dataclasses.replace(self, lines=tuple(body))
-
-    def _closing_quotes(self) -> str:
-        if self.form is not CommentForm.DOC:
-            return ''
-        return self.lines[-1].suffix or self.lines[0].delimiter.strip()
-
-    def with_texts(self, texts: tuple[str, ...]) -> 'CommentGroup':
-        if not texts:
-            raise ValueError('A comment block needs at least one line')
-        template = self.lines[0]
-        rebuilt = tuple(
-            dataclasses.replace(
-                self.lines[index] if index < len(self.lines) else template,
-                text=text,
-            )
-            for index, text in enumerate(texts)
-        )
-        return dataclasses.replace(self, lines=rebuilt)
+    def closing(self) -> str:
+        """What closes the comment on its last text line, such as a docstring's quotes."""
+        return self.layout.closing(self.lines)
 
     def render(self) -> str:
         return '\n'.join(line.render() for line in self.lines)