subedit 0.3.0__tar.gz → 0.3.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: subedit
-Version: 0.3.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

{subedit-0.3.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

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

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

{subedit-0.3.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.3.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.3.0 → subedit-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "subedit"
-version = "0.3.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.3.0 → subedit-0.3.1}/src/subedit/__init__.py

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

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

@@ -137,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)
@@ -192,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.3.0 → subedit-0.3.1}/src/subedit/domain/models/prose.py

@@ -21,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.
@@ -30,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.
@@ -107,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:
@@ -133,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())
@@ -173,10 +177,10 @@ class Prose:
     def _is_indented(self, line: str) -> bool:
         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))
@@ -237,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.3.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.3.0 → subedit-0.3.1}/src/subedit/infrastructure/parsers/languages/language_profile.py

@@ -1,5 +1,6 @@
 import abc
 import enum
+import re
 
 from tree_sitter import Language, Node
 
@@ -47,6 +48,11 @@ class LanguageProfile(LanguageConventions, GrammarAdapter):
     width_settings: tuple[WidthSetting, ...] = ()
     # Directories a package manager fills with code nobody in the project wrote.
     vendor_directories: frozenset[str] = frozenset()
+    # A comment a tool reads, such as eslint-disable or noqa, which the query sets apart from prose.
+    directive: re.Pattern[str] | None = None
+
+    def is_directive(self, node: Node) -> bool:
+        return self.directive is not None and bool(self.directive.match((node.text or b'').decode('utf-8')))
 
     def imports_for_effect(self, node: Node) -> bool:
         """Whether an import binds no name and runs only for its side effect, which a comment over it explains."""

{subedit-0.3.0 → subedit-0.3.1}/src/subedit/infrastructure/parsers/languages/python_profile.py

@@ -76,6 +76,7 @@ class PythonProfile(LanguageProfile):
     signature_tags = ('Args:', 'Returns:', 'Raises:', 'Yields:', ':param', ':return', ':returns', ':rtype')
     canonical_extension = '.py'
     doc_layout = QUOTED_DOC_LAYOUT
+    directive = re.compile(_DIRECTIVE)
     doc_markup = ProseMarkup(tag_section=_SECTION, example_tag='Example', code_line=_CODE_LINE)
     line_markup = ProseMarkup(code_line=_CODE_LINE)
     vendor_directories = frozenset({'venv', 'site-packages', '__pypackages__'})

{subedit-0.3.0 → subedit-0.3.1}/src/subedit/infrastructure/parsers/languages/typescript_profile.py

@@ -20,7 +20,10 @@ _DOC_CLOSING = '*/'
 # A plain /* */ block is usually a license header or a lint directive, so only // and /** */ are prose.
 # A directive such as eslint-disable-next-line, or a triple-slash reference, is read by a tool rather than a person.
 # Three stars open a banner rather than a doc comment.
-_DIRECTIVE = '^(///|//[ \t]*(eslint|@ts-|prettier-ignore|biome-ignore|istanbul |c8 |#region|#endregion))'
+_DIRECTIVE = (
+    '^(///|//[ \t]*(eslint|@ts-|prettier-ignore|biome-ignore|istanbul |c8 |#region|#endregion)'
+    '|/[*][ \t]*(eslint|prettier-ignore|biome-ignore|istanbul |c8 ))'
+)
 QUERY = f"""
 ((comment) @comment (#match? @comment "^//") (#not-match? @comment "{_DIRECTIVE}"))
 ((comment) @directive (#match? @directive "{_DIRECTIVE}"))
@@ -63,6 +66,7 @@ class TypeScriptProfile(LanguageProfile):
     doc_delimiter = '/**'
     doc_layout = FramedDocLayout(opening='/**', prefix=' * ', closing_line=' */')
     doc_leads_declaration = True
+    directive = re.compile(_DIRECTIVE)
     width_settings = (
         *(
             WidthSetting(name, ('printWidth',))

{subedit-0.3.0 → subedit-0.3.1}/src/subedit/infrastructure/parsers/tree_sitter_parser.py

@@ -181,12 +181,15 @@ class TreeSitterParser(SourceParser):
     # A comment on the line right above a statement describes that statement, even at the top of a file.
     # Imports are the exception, since a comment over them is a banner rather than a note on one import,
     # unless the import runs only for its effect, such as patching a library, which only a comment explains.
+    # A directive such as eslint-disable governs what follows it, so the comment over it explains the directive.
     def _touches_next_code(self, profile: LanguageProfile, node: Node) -> bool:
         candidate = node.next_named_sibling
         if candidate is None or not self._is_adjacent(node, candidate):
             return False
         role = profile.role_of(candidate.type)
-        return role is not NodeRole.COMMENT and (role is not NodeRole.IMPORT or profile.imports_for_effect(candidate))
+        if role is NodeRole.COMMENT:
+            return profile.is_directive(candidate)
+        return role is not NodeRole.IMPORT or profile.imports_for_effect(candidate)
 
     # A blank line between a comment and what follows sets the comment apart, as a section divider does.
     def _is_adjacent(self, upper: Node, lower: Node) -> bool:

{subedit-0.3.0 → subedit-0.3.1}/tests/test_fixer.py

@@ -116,13 +116,13 @@ def test_targeted_edits_run_before_reflow() -> None:
                     fix=Fix.reflow(reflowed.as_edit()),
                 )
 
-    source = 'def f():\n    # one. two.\n    pass\n'
+    source = 'def f():\n    # one\n    # two.\n    pass\n'
     document = Document(uri='file:///a.py', text=source, language_id='python')
     outcome = Fixer(Linter(DEFAULT_PARSER, RuleEngine((ReflowRule(), TargetedRule())))).run(
         document, RuleSet(enabled_rule_ids=frozenset({'targeted', 'reflowing'}), line_width=60)
     )
     assert '!' in outcome.document.text
-    assert outcome.document.text.count('    # ') == 2
+    assert outcome.document.text.count('    # ') == 1
 
 
 def test_overlapping_edits_are_deferred_rather_than_dropped() -> None:

{subedit-0.3.0 → subedit-0.3.1}/tests/test_language_parity.py

@@ -124,3 +124,66 @@ def test_one_line_of_code_is_code_in_both_languages(line: str) -> None:
 )
 def test_a_block_set_two_spaces_in_is_left_as_laid_out(source: str, language_id: str) -> None:
     assert fixed(source, language_id) == source
+
+
+@pytest.mark.parametrize(
+    ('source', 'language_id'),
+    [
+        (
+            '// Fixture strings hold literal placeholders the gateway expands.\n'
+            '/* eslint-disable no-template-curly-in-string */\nimport { describe } from "vitest";\n',
+            'typescript',
+        ),
+        (
+            '# Fixture strings hold literal placeholders the gateway expands.\n'
+            '# pylint: disable=consider-using-f-string\nimport os\n',
+            'python',
+        ),
+    ],
+)
+def test_a_comment_explaining_a_file_wide_directive_is_no_file_header(source: str, language_id: str) -> None:
+    suffix = '.py' if language_id == 'python' else '.ts'
+    document = Document(uri=f'file:///a{suffix}', text=source, language_id=language_id)
+    report = Linter(DEFAULT_PARSER, RuleEngine(ALL_RULES)).run(document, RuleSet(enabled_rule_ids=ENABLED))
+    assert 'file-header-comment' not in [item.rule_id for item in report.diagnostics]
+
+
+@pytest.mark.parametrize(
+    ('source', 'language_id'),
+    [
+        (
+            '/**\n * End-to-end flow.\n *\n * 1. Workspace scaffold, writes PRODUCT.md, registers workspace,\n'
+            " * binds the active plugin's validators.\n * 2. Proposal submission, which the reviewer approves.\n */\n"
+            'export function flow(): void {}\n',
+            'typescript',
+        ),
+        (
+            'def flow():\n    """End-to-end flow.\n\n    - **Graph**: reuses the workspace `GraphCanvas`,\n'
+            '    so the layout matches the main view.\n    - **List**: shows every proposal.\n    """\n',
+            'python',
+        ),
+    ],
+)
+def test_a_list_item_whose_sentence_runs_on_at_the_margin_stays_one_item(source: str, language_id: str) -> None:
+    assert fixed(source, language_id) == source
+
+
+@pytest.mark.parametrize(
+    ('source', 'language_id', 'marker'),
+    [
+        (
+            'def f():\n    """Do it."""\n    # Surface errors without stack traces. Reserve stacks for bugs.\n    return 1\n',
+            'python',
+            '#',
+        ),
+        (
+            '/** Do it. */\nexport function f() {\n'
+            '  // Surface errors without stack traces. Reserve stacks for bugs.\n  return 1;\n}\n',
+            'typescript',
+            '//',
+        ),
+    ],
+)
+def test_short_sentences_may_share_a_line_that_fits(source: str, language_id: str, marker: str) -> None:
+    assert fixed(source, language_id) == source
+    assert f'{marker} Surface errors without stack traces.\n' in fixed(source, language_id, width=60)

{subedit-0.3.0 → subedit-0.3.1}/tests/test_prose.py

@@ -237,3 +237,19 @@ def test_an_appositive_is_no_list_item() -> None:
 def test_parallel_items_led_by_articles_still_form_a_list() -> None:
     lines = ('It feeds a cat, a dog,', 'and a bird every morning before the long walk.')
     assert break_cost(lines) == 1
+
+
+@pytest.mark.parametrize(
+    'text',
+    [
+        'Process-local pub/sub of `WorkspaceEvent`s. Subscribers register per workspace.',
+        'Stop both on Ctrl+C. Standalone, it runs the server alone.',
+        'Retry on HTTP 5xx-A. Then give up.',
+    ],
+)
+def test_a_letter_closing_a_longer_token_is_no_initial(text: str) -> None:
+    assert len(Prose(text).sentences()) == 2
+
+
+def test_an_initial_in_brackets_still_holds_its_sentence() -> None:
+    assert len(Prose('named after (J. Smith) originally').sentences()) == 1

{subedit-0.3.0 → subedit-0.3.1}/tests/test_rules_layout.py

@@ -32,10 +32,27 @@ def test_a_mid_clause_break_is_reported_and_reflowed() -> None:
     assert '# cap the size to the limit so the mmap does not blow past it,\n' in fixed(source, width=70)
 
 
-def test_reflow_splits_one_sentence_per_line() -> None:
-    source = 'def f():\n    # first one. second one. third one.\n    pass\n'
-    result = fixed(source)
-    assert result.count('    # ') == 3
+def test_short_sentences_sharing_a_line_that_fits_stay_together() -> None:
+    assert lint('def f():\n    # first one. second one. third one.\n    pass\n').is_clean
+
+
+def test_sentences_sharing_a_line_that_overflows_take_one_line_each() -> None:
+    source = 'def f():\n    # the first sentence runs on. the second one too. the third one ends here.\n    pass\n'
+    assert fixed(source, width=40).count('    # ') == 3
+
+
+def test_sentences_on_lines_of_their_own_are_not_joined() -> None:
+    assert lint('def f():\n    # first one.\n    # second one.\n    pass\n').is_clean
+
+
+def test_a_sentence_running_on_from_a_shared_line_takes_its_own_line() -> None:
+    source = 'def f():\n    # first one. second one\n    # runs on.\n    pass\n'
+    assert fixed(source) == 'def f():\n    # first one.\n    # second one runs on.\n    pass\n'
+
+
+def test_a_docstring_summary_keeps_its_line_to_itself() -> None:
+    source = 'def f():\n    """Do it. Then more.\n\n    Body.\n    """\n'
+    assert '"""Do it.\n\n    Then more.' in fixed(source)
 
 
 def test_a_long_sentence_splits_at_commas_only() -> None:

{subedit-0.3.0 → subedit-0.3.1}/uv.lock

@@ -349,7 +349,7 @@ wheels = [
 
 [[package]]
 name = "subedit"
-version = "0.3.0"
+version = "0.3.1"
 source = { editable = "." }
 dependencies = [
     { name = "autocorrect-py" },