subedit 0.4.0__tar.gz → 0.5.0__tar.gz

{subedit-0.4.0 → subedit-0.5.0}/.vale.ini

@@ -9,7 +9,6 @@ BasedOnStyles = subedit
 # These guard a comment against going stale. A Markdown note may tell a history,
 # cite an issue, date a release, or explain a tag on purpose.
 subedit.EditHistory = NO
-subedit.SignatureTag = NO
 subedit.DateRef = NO
 subedit.ExternalRef = NO
 

{subedit-0.4.0 → subedit-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: subedit
-Version: 0.4.0
+Version: 0.5.0
 Summary: A subeditor for AI agents, keeping every sentence they write to your house style.
 Project-URL: Homepage, https://github.com/mroops0111/subedit
 Project-URL: Repository, https://github.com/mroops0111/subedit
@@ -209,8 +209,8 @@ Judgment rules, such as a long block or a date in a comment, default to `warning
 Reflow works on sentences rather than lines, so the result reads the way the author would have broken it.
 
 - **One Line When It Fits**: a sentence that fits takes one line, and a wrapped one that would fit is joined.
-- **Clause Commas Only**: a longer sentence breaks only at a comma that ends a clause, never inside a list, brackets, or a code span.
-- **No Stubs**: no break leaves a line shorter than the `stub-fragment` floor, 24 characters by default.
+- **Clause Commas Only**: a longer sentence breaks only at a comma that ends a clause, never inside brackets or a code span, and preferably not inside a list.
+- **No Short Lines**: no break leaves a line shorter than the `line-too-short` floor, 24 characters by default.
 - **Verbatim Blocks**: code examples, docstring sections, and JSDoc tags are left as written.
 - **Markdown Paragraphs**: Markdown has no column limit, so a paragraph takes one source line, and a hand-wrapped one is joined.
 
@@ -284,12 +284,12 @@ Registering the hook with both agents is fine, since each payload identifies its
 
 ### Configuration
 
-Settings come from `subedit.toml`, or from `[tool.subedit]` in `pyproject.toml`, whichever sits closest above the file being checked. Without either, `check` and `fix` run with the defaults.
+Settings come from `subedit.toml`, or from `[tool.subedit]` in `pyproject.toml`, whichever sits closest above the file being checked. Without either, `check` and `fix` run with the defaults. A config with a misspelled key, level, or option stops subedit with an error that names the file and the key, so a typo never leaves a project on defaults it did not choose.
 
 A rule takes one of two forms, depending on whether it has options to set.
 
 - **Level Only**: a string, `"error"`, `"warning"`, or `"off"`. Every rule takes this form, including the delegated Vale and AutoCorrect rules.
-- **Level and Options**: a `[rules.<name>]` table, holding `severity` and the rule's options. Leave out `severity` to keep the default level. Only `block-too-long` and `stub-fragment` have options, listed in [Rules](#rules).
+- **Level and Options**: a `[rules.<name>]` table, holding `severity` and the rule's options. Leave out `severity` to keep the default level. The [rule reference](docs/rules.md) lists each rule's options with their defaults.
 
 ```toml
 [subedit]
@@ -301,18 +301,23 @@ mid-clause-break = "warning"
 file-header-comment = "off"
 "subedit.DateRef" = "off"
 
-[rules.block-too-long]
+[rules.comment-too-long]
 severity = "error"
-line = 3
+max-plain-lines = 3
 
-[rules.stub-fragment]
-minimum_characters = 30
+[rules.line-too-short]
+min-line-characters = 30
+
+[rules.heading-title-case]
+exceptions = ["npm"]
 ```
 
+A name Title Case must leave as written, such as `npm`, goes under `exceptions`, which headings, table headers, and list labels all follow.
+
 In `pyproject.toml`, the same keys sit under `[tool.subedit]`, `[tool.subedit.rules]`, and `[tool.subedit.rules.<name>]`.
 
 <details>
-<summary><b>Settings</b>: the width, excluded paths, and code blocks</summary>
+<summary><b>Settings</b>: the width, excluded paths, code blocks, and abbreviations</summary>
 
 <br>
 
@@ -321,6 +326,7 @@ In `pyproject.toml`, the same keys sit under `[tool.subedit]`, `[tool.subedit.ru
 | `line-width` | Integer | The formatter's width, else 120 | The column every comment line must fit, counting indent and delimiter |
 | `exclude` | List of globs | `[]` | Paths a directory walk skips, relative to the config file |
 | `code-blocks` | Boolean | `false` | Whether the comments in a Markdown code block are read, in a language subedit supports |
+| `abbreviations` | List of strings | `[]` | Abbreviations whose period ends no sentence, each written with its period and its case, such as `"Dept."` |
 
 Left unset, `line-width` follows the formatter that would format the file, read from its own config.
 
@@ -333,7 +339,7 @@ Left unset, `line-width` follows the formatter that would format the file, read
 
 ### Rules
 
-`subedit` ships 18 native rules, a bundled Vale style of 6 rules, and AutoCorrect. Every rule is set by name under `[rules]` to `"error"`, `"warning"`, or `"off"`, and its fix kind follows [Fix Kinds](#fix-kinds).
+`subedit` ships 21 native rules, a bundled Vale style of 5 rules, and AutoCorrect. Every rule is set by name under `[rules]` to `"error"`, `"warning"`, or `"off"`, and its fix kind follows [Fix Kinds](#fix-kinds).
 
 Comments and Markdown share one house style, and differ where their forms differ. A comment has a column limit and sits beside the code it explains, while Markdown has no limit and is built from paragraphs and headings.
 
@@ -361,7 +367,7 @@ A surface is a kind of file where prose lives. Every surface goes through the sa
 | Code comments and docstrings | Available | Layout, because a comment must fit a column limit |
 | Markdown | Available | One line per paragraph and the shape of headings, because Markdown has no column limit |
 
-Markdown is read from `.md` and `.markdown` files, leaving front matter, code, tables, and HTML blocks alone. With `code-blocks = true`, the comments in a fenced block are read too, when its info string names a language subedit supports, such as `python`, `ts`, or `yaml`. Each block is checked as a file of that language would be, by Vale and AutoCorrect as well, except for the rules on a whole file. A code block is often an example, so this stays off unless the project asks. Editor diagnostics over LSP are planned, so the same findings show as you type.
+Markdown is read from `.md` and `.markdown` files, leaving front matter, code, and HTML blocks alone, and reading only the header of a table. With `code-blocks = true`, the comments in a fenced block are read too, when its info string names a language subedit supports, such as `python`, `ts`, or `yaml`. Each block is checked as a file of that language would be, by Vale and AutoCorrect as well, except for the rules on a whole file. A code block is often an example, so this stays off unless the project asks. Editor diagnostics over LSP are planned, so the same findings show as you type.
 
 #### Languages
 
@@ -391,4 +397,4 @@ Each language is a profile that knows its comment forms, its doc comment, and wh
 
 ## License
 
-[MIT](LICENSE)
+[MIT](LICENSE). The English abbreviations that end no sentence come from the [Unicode CLDR](https://cldr.unicode.org/) under the Unicode License v3, whose notice ships with the [data file](src/subedit/domain/models/cldr_sentence_suppressions.txt).

{subedit-0.4.0 → subedit-0.5.0}/README.md

@@ -171,8 +171,8 @@ Judgment rules, such as a long block or a date in a comment, default to `warning
 Reflow works on sentences rather than lines, so the result reads the way the author would have broken it.
 
 - **One Line When It Fits**: a sentence that fits takes one line, and a wrapped one that would fit is joined.
-- **Clause Commas Only**: a longer sentence breaks only at a comma that ends a clause, never inside a list, brackets, or a code span.
-- **No Stubs**: no break leaves a line shorter than the `stub-fragment` floor, 24 characters by default.
+- **Clause Commas Only**: a longer sentence breaks only at a comma that ends a clause, never inside brackets or a code span, and preferably not inside a list.
+- **No Short Lines**: no break leaves a line shorter than the `line-too-short` floor, 24 characters by default.
 - **Verbatim Blocks**: code examples, docstring sections, and JSDoc tags are left as written.
 - **Markdown Paragraphs**: Markdown has no column limit, so a paragraph takes one source line, and a hand-wrapped one is joined.
 
@@ -246,12 +246,12 @@ Registering the hook with both agents is fine, since each payload identifies its
 
 ### Configuration
 
-Settings come from `subedit.toml`, or from `[tool.subedit]` in `pyproject.toml`, whichever sits closest above the file being checked. Without either, `check` and `fix` run with the defaults.
+Settings come from `subedit.toml`, or from `[tool.subedit]` in `pyproject.toml`, whichever sits closest above the file being checked. Without either, `check` and `fix` run with the defaults. A config with a misspelled key, level, or option stops subedit with an error that names the file and the key, so a typo never leaves a project on defaults it did not choose.
 
 A rule takes one of two forms, depending on whether it has options to set.
 
 - **Level Only**: a string, `"error"`, `"warning"`, or `"off"`. Every rule takes this form, including the delegated Vale and AutoCorrect rules.
-- **Level and Options**: a `[rules.<name>]` table, holding `severity` and the rule's options. Leave out `severity` to keep the default level. Only `block-too-long` and `stub-fragment` have options, listed in [Rules](#rules).
+- **Level and Options**: a `[rules.<name>]` table, holding `severity` and the rule's options. Leave out `severity` to keep the default level. The [rule reference](docs/rules.md) lists each rule's options with their defaults.
 
 ```toml
 [subedit]
@@ -263,18 +263,23 @@ mid-clause-break = "warning"
 file-header-comment = "off"
 "subedit.DateRef" = "off"
 
-[rules.block-too-long]
+[rules.comment-too-long]
 severity = "error"
-line = 3
+max-plain-lines = 3
 
-[rules.stub-fragment]
-minimum_characters = 30
+[rules.line-too-short]
+min-line-characters = 30
+
+[rules.heading-title-case]
+exceptions = ["npm"]
 ```
 
+A name Title Case must leave as written, such as `npm`, goes under `exceptions`, which headings, table headers, and list labels all follow.
+
 In `pyproject.toml`, the same keys sit under `[tool.subedit]`, `[tool.subedit.rules]`, and `[tool.subedit.rules.<name>]`.
 
 <details>
-<summary><b>Settings</b>: the width, excluded paths, and code blocks</summary>
+<summary><b>Settings</b>: the width, excluded paths, code blocks, and abbreviations</summary>
 
 <br>
 
@@ -283,6 +288,7 @@ In `pyproject.toml`, the same keys sit under `[tool.subedit]`, `[tool.subedit.ru
 | `line-width` | Integer | The formatter's width, else 120 | The column every comment line must fit, counting indent and delimiter |
 | `exclude` | List of globs | `[]` | Paths a directory walk skips, relative to the config file |
 | `code-blocks` | Boolean | `false` | Whether the comments in a Markdown code block are read, in a language subedit supports |
+| `abbreviations` | List of strings | `[]` | Abbreviations whose period ends no sentence, each written with its period and its case, such as `"Dept."` |
 
 Left unset, `line-width` follows the formatter that would format the file, read from its own config.
 
@@ -295,7 +301,7 @@ Left unset, `line-width` follows the formatter that would format the file, read
 
 ### Rules
 
-`subedit` ships 18 native rules, a bundled Vale style of 6 rules, and AutoCorrect. Every rule is set by name under `[rules]` to `"error"`, `"warning"`, or `"off"`, and its fix kind follows [Fix Kinds](#fix-kinds).
+`subedit` ships 21 native rules, a bundled Vale style of 5 rules, and AutoCorrect. Every rule is set by name under `[rules]` to `"error"`, `"warning"`, or `"off"`, and its fix kind follows [Fix Kinds](#fix-kinds).
 
 Comments and Markdown share one house style, and differ where their forms differ. A comment has a column limit and sits beside the code it explains, while Markdown has no limit and is built from paragraphs and headings.
 
@@ -323,7 +329,7 @@ A surface is a kind of file where prose lives. Every surface goes through the sa
 | Code comments and docstrings | Available | Layout, because a comment must fit a column limit |
 | Markdown | Available | One line per paragraph and the shape of headings, because Markdown has no column limit |
 
-Markdown is read from `.md` and `.markdown` files, leaving front matter, code, tables, and HTML blocks alone. With `code-blocks = true`, the comments in a fenced block are read too, when its info string names a language subedit supports, such as `python`, `ts`, or `yaml`. Each block is checked as a file of that language would be, by Vale and AutoCorrect as well, except for the rules on a whole file. A code block is often an example, so this stays off unless the project asks. Editor diagnostics over LSP are planned, so the same findings show as you type.
+Markdown is read from `.md` and `.markdown` files, leaving front matter, code, and HTML blocks alone, and reading only the header of a table. With `code-blocks = true`, the comments in a fenced block are read too, when its info string names a language subedit supports, such as `python`, `ts`, or `yaml`. Each block is checked as a file of that language would be, by Vale and AutoCorrect as well, except for the rules on a whole file. A code block is often an example, so this stays off unless the project asks. Editor diagnostics over LSP are planned, so the same findings show as you type.
 
 #### Languages
 
@@ -353,4 +359,4 @@ Each language is a profile that knows its comment forms, its doc comment, and wh
 
 ## License
 
-[MIT](LICENSE)
+[MIT](LICENSE). The English abbreviations that end no sentence come from the [Unicode CLDR](https://cldr.unicode.org/) under the Unicode License v3, whose notice ships with the [data file](src/subedit/domain/models/cldr_sentence_suppressions.txt).

subedit-0.5.0/docs/rules.md

@@ -0,0 +1,105 @@
+# Rules
+
+`subedit` ships 21 native rules, a bundled Vale style of 5 rules, and AutoCorrect. The [README](../README.md#rules) compares what comments and Markdown share and where they differ, and this page lists every rule by group.
+
+Every rule is set by name under `[rules]` to `"error"`, `"warning"`, or `"off"`, as in `"subedit.DateRef" = "off"`. An error fails `check` and stops an agent, while a warning is shown as advice. The fix kind states who resolves a finding, as [Fix Kinds](../README.md#fix-kinds) describes.
+
+## Style
+
+These rules read comments and Markdown alike, and hold the punctuation, labels, and wording of the house style.
+
+| Rule | Catches | Fix Kind | Default | Options |
+| --- | --- | --- | --- | --- |
+| `mid-sentence-colon` | A colon, half-width or full-width, joining clauses or leading into an inline list | Rewrite | `error` | `max-label-words` (5), `max-bold-label-words` (10), `max-full-width-label-characters` (12), `max-tag-words` (3) |
+| `parenthesis-style` | Parentheses around prose in the width `style` does not pick, or spaced wrong for their width | Targeted | `error` | `style` (`half-width`) |
+| `list-label-title-case` | A `label: description` item whose English label is not in Title Case | Targeted | `error` | None |
+| `list-label-not-bold` | A `label: description` item whose label is not bold where the text renders | Targeted | `error` | None |
+| `discouraged-word` | A word the project writes otherwise, replaced with the one it prefers | Targeted | `error` | `replacements` (1 pair) |
+| `contrast-framing` | A Chinese sentence framed as *not A, but B*, which states B against what it is not | Rewrite | `warning` | None |
+
+A colon may stand in a heading, after a short label, or at the end of a line that a list or block follows. A label opens a list item, or a paragraph as a capitalized tag such as `Note`, and carries no verb such as *is* or *can*. A label the author set in bold may run longer. Words opening a list item, or set in bold, that run past these limits may still be a label, so their colon is a warning unless the project sets the rule's severity. A colon anywhere else stays an error. Both list label rules read the same limits, so every rule agrees on what a label is. Parentheses around code, such as `foo(bar)`, are left alone. `half-width` parentheses take a space outside and none inside, the house style. `full-width` follows the CJK standard, where an aside in or beside CJK text takes full-width parentheses with no spaces, and one in English keeps half-width ones. By default `discouraged-word` replaces one Chinese verb for *include* with the one the house style prefers. A project lists its own pairs under `replacements`, as in `{ utilize = "use" }`, or sets it to `{}`. A word in Latin letters matches whole, and a CJK word wherever it stands. Bold goes only where a reader sees it rendered, in Markdown, docstrings, and JSDoc, not in a line comment. Quoted text, in a block quote or quotation marks, is left as written.
+
+## Wording
+
+These rules come from the bundled Vale style, and the author rewrites what they find. They run when Vale is installed, and only in a repository without its own `.vale.ini`. A repository with one runs its own styles instead, and their findings join the same report.
+
+| Rule | Catches | Fix Kind | Default | Options |
+| --- | --- | --- | --- | --- |
+| `subedit.EmDash` | An em dash, an en dash, or an arrow in prose | Rewrite | `error` | None |
+| `subedit.Semicolon` | A semicolon, half-width or full-width, joining two clauses | Rewrite | `error` | None |
+| `subedit.EditHistory` | A phrase such as "no longer" or "used to" that may narrate a change, in comments only | Rewrite | `warning` | None |
+| `subedit.ExternalRef` | An identifier shaped like a ticket number a reader may not be able to open, in comments only | Rewrite | `warning` | None |
+| `subedit.DateRef` | A date that records when something changed, in comments only | Rewrite | `warning` | None |
+
+Standards such as `UTF-8` and `SHA-256` are exempt from `subedit.ExternalRef`. The `subedit:judging-findings` skill gives an agent the criteria for these judgment calls.
+
+## Spacing
+
+AutoCorrect reads comments and Markdown alike, and autofixes the spacing between CJK and Latin text.
+
+| Rule | Catches | Fix Kind | Default | Options |
+| --- | --- | --- | --- | --- |
+| `autocorrect.Spacing` | Missing spaces and wrong punctuation width between CJK and Latin text | Targeted | `error` | `.autocorrectrc` |
+
+AutoCorrect ships as a Python dependency, so it runs wherever `subedit` does, and reads `.autocorrectrc` from the working directory.
+
+## Layout
+
+These rules read comments, and autofix how a comment breaks across lines.
+
+| Rule | Catches | Fix Kind | Default | Options |
+| --- | --- | --- | --- | --- |
+| `mid-clause-break` | A sentence broken where it need not be, or a wrapped sentence that would fit one line | Reflow | `error` | None |
+| `line-too-long` | A comment line past the width, counting indent and delimiter | Reflow, or Rewrite for a trailing comment | `error` | None |
+
+A trailing comment cannot break without leaving its code behind, so `line-too-long` asks the author to shorten it or move it above the code.
+
+## Sentence
+
+These rules read comments, and catch the sentences no layout can save, which the author rewrites.
+
+| Rule | Catches | Fix Kind | Default | Options |
+| --- | --- | --- | --- | --- |
+| `unbreakable-sentence` | A sentence over the width with no clause comma, or a summary that does not fit one line | Rewrite | `error` | None |
+| `line-too-short` | A forced break that leaves a line too short to read as a clause | Rewrite | `warning` | `min-line-characters` (24) |
+| `mid-list-break` | A break that seems to fall between the items of a list | Rewrite | `warning` | `max-item-words` (3) |
+
+Reflow reads the same `min-line-characters` floor, so a fix never lays out a line that `line-too-short` then rejects.
+
+Whether a comma parts list items, clauses, or an aside is a matter of syntax, which subedit can only guess, so `mid-list-break` is a warning. Reflow still prefers a break that splits no list when it lays a sentence out itself, but it keeps a legal break the author chose. A piece of up to `max-item-words` words between two commas may be a list item. Switching either rule off leaves its concern out of reflow too.
+
+A period ends a sentence unless it closes an abbreviation. The abbreviations are the English ones Unicode CLDR lists, such as *Mr.* and *Ph.D.*, matched with their case, the Latin ones in lowercase, such as *e.g.* and *etc.*, and a reference such as *Fig.* or *Sec.* before a number. Many CLDR entries, such as *Go.* and *OK.*, are also words, so one ends no sentence only before a lowercase word or a number, unless it holds a period inside, as *U.S.* does. A title such as *Dr.* ends none before a name. A project adds its own under `abbreviations` in its settings, which never end a sentence.
+
+## Structure
+
+These rules read comments, and check where documentation lives and how much of it there is.
+
+| Rule | Catches | Fix Kind | Default | Options |
+| --- | --- | --- | --- | --- |
+| `plain-comment-on-public` | A public symbol documented with a plain comment instead of a docstring or JSDoc block | Rewrite | `error` | None |
+| `signature-restating-tag` | A doc comment section that restates types the signature already carries, such as `Args:` or `@param` | Rewrite | `error` | None |
+| `file-header-comment` | A banner comment opening the file before its first declaration | Rewrite | `warning` | None |
+| `comment-too-long` | A comment long enough to restate the code below it | Rewrite | `warning` | `max-plain-lines` (4), `max-internal-doc-lines` (13), `max-public-doc-lines` (20) |
+
+The `comment-too-long` limits are line counts, for a plain comment and for a doc comment on an internal or a public symbol, set from the 95th percentile of a measured corpus. `subedit stats` reports the same percentiles for your codebase.
+
+A plain comment right under another declaration may head a group rather than document one symbol, so `plain-comment-on-public` reports that case as a warning.
+
+## Markdown
+
+These rules read Markdown files, and keep each paragraph on one source line and each heading in its house form.
+
+| Rule | Catches | Fix Kind | Default | Options |
+| --- | --- | --- | --- | --- |
+| `paragraph-line-break` | A paragraph or list item broken across source lines | Reflow | `error` | None |
+| `heading-wrapped-in-bold` | A heading whose whole text is bold, though a heading already renders bold | Targeted | `error` | None |
+| `heading-title-case` | An English heading not in Title Case | Targeted | `error` | `exceptions` (`[]`), `style` (`apa`), `levels` (`[1, 2, 3, 4, 5, 6]`) |
+| `table-header-title-case` | An English table header cell not in Title Case | Targeted | `error` | None |
+| `missing-lead-sentence` | A heading that opens straight into a list, with no sentence to frame it | Rewrite | `error` | None |
+| `heading-not-noun-phrase` | A heading that asks a question or gives an instruction | Rewrite | `error` | `levels` (`[1, 2, 3, 4, 5, 6]`) |
+
+GitHub issues, Notion, and Heptabase can show a source newline as a line break, so a hand-wrapped paragraph breaks once it is copied there. Joining puts no space between two CJK characters, and keeps a break the author marked with two trailing spaces or a backslash.
+
+Title Case follows a published standard, which `style` names. `apa` lowercases articles, conjunctions, and prepositions of three letters or fewer, so it writes *Working With a List*. `chicago` lowercases articles, *and*, *but*, *for*, *or*, *nor*, and every preposition, so it writes *Working with a List*. A word such as *up* or *in* that may stand as an adverb, as in *Set Up*, keeps the case the author wrote, and a capitalized one inside a heading is a warning. Title Case leaves code, file names, acronyms, and a lone lowercase word alone. A lowercase name such as `npm` goes under `exceptions`. List labels and table headers follow `style` and `exceptions` too. A table is otherwise left unread, since its cells are fragments rather than sentences.
+
+A heading that opens with a question word such as *How* or *What*, or ends with a question mark, is a question, so it is an error. A heading whose first word is followed straight by a word opening an object, such as *a*, *the*, or *your*, reads as an instruction, as in *Add a Rule*. That is a guess, so it is a warning unless the project sets the rule's severity. A single word such as *Install* passes, since it may name the subject. Both heading rules read only the heading levels listed under `levels`, so a project can leave out a document title or a FAQ.

{subedit-0.4.0 → subedit-0.5.0}/plugins/subedit/.claude-plugin/plugin.json

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

{subedit-0.4.0 → subedit-0.5.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.4.0'
+SPEC='subedit[vale]>=0.5.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.4.0 → subedit-0.5.0}/plugins/subedit/skills/judging-findings/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: judging-findings
-description: Decide what to do with a subedit finding that no tool can fix, such as subedit.ExternalRef, subedit.DateRef, mid-sentence-colon, block-too-long, or unbreakable-sentence. Use when a subedit hook, `subedit check`, or `subedit fix` reports a finding that needs rewriting or a warning that is a judgment call.
+description: Decide what to do with a subedit finding that no tool can fix, such as subedit.ExternalRef, subedit.DateRef, mid-sentence-colon, comment-too-long, or unbreakable-sentence. Use when a subedit hook, `subedit check`, or `subedit fix` reports a finding that needs rewriting or a warning that is a judgment call.
 ---
 
 # Judge subedit Findings
@@ -23,25 +23,26 @@ Rewrite in place, keep the meaning, and keep the comment to the constraint the c
 
 A warning passes when the text meets its criterion. Leave such text exactly as it is, and say so in one line if anyone asks.
 
-| Rule | Keep the text when | Rewrite it when |
+| Rule | Keep the Text When | Rewrite It When |
 | --- | --- | --- |
 | `subedit.ExternalRef` | The identifier is public and resolvable by anyone, such as an RFC, an MCP SEP, a PEP, a CVE, or an ISO standard. | It is a private ticket, such as a Jira key or an internal issue number. State the constraint the ticket recorded instead. |
 | `subedit.DateRef` | The date names a version or a spec revision, such as the dated revision an MCP specification is named by. | It records when something happened or changed. State the constraint that holds now. |
 | `subedit.EditHistory` | The phrase states a constraint that holds now, as in "a file no longer than 10 lines". | It tells how the code used to behave. State the behavior it has now. |
 | `contrast-framing` | Never in the house style, unless the contrast is the point, written as 是 B 而非 A. | It frames B against what it is not. State B directly. |
 | `heading-not-noun-phrase` | The heading is a noun phrase that happens to open with the flagged word. | It asks a question or gives an instruction. Name the section's subject instead. |
-| `block-too-long` | Every sentence states a constraint the code cannot show. | Some sentences narrate what the code does. Cut them, or move the explanation into a name. |
+| `comment-too-long` | Every sentence states a constraint the code cannot show. | Some sentences narrate what the code does. Cut them, or move the explanation into a name. |
 | `file-header-comment` | It states a constraint about the whole module that no single declaration owns. | It is a banner or a summary of the file. Delete it, or move the constraint to the declaration it applies to. |
-| `stub-fragment` | Never. A stub reads as a broken clause. | Always. Rewrite the sentence to fit one line, or split it into two complete sentences. |
+| `line-too-short` | Never. A line that short reads as a broken clause. | Always. Rewrite the sentence to fit one line, or split it into two complete sentences. |
+| `mid-list-break` | The comma at the break parts an aside or a clause, as in "stays a reference, rewritten to X, and the component is expanded". | It parts the items of a list. Move the list to the end of the sentence, or split the sentence in two. |
 
 ## Errors
 
 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. 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.
+- **`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 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.
+- **`signature-restating-tag`**: delete the tag, since the signature already says it.
 - **`mid-sentence-colon`**: a colon stands only in a heading, after a short label, or at the end of a line that a list or block follows. Split the sentence in two, or turn the inline list into a list.
 - **`missing-lead-sentence`**: add a sentence or two under the heading that frames what the list holds.
 - **`subedit.Semicolon`, `subedit.EmDash`**: split into two sentences, or use a comma or parentheses.

{subedit-0.4.0 → subedit-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "subedit"
-version = "0.4.0"
+version = "0.5.0"
 description = "A subeditor for AI agents, keeping every sentence they write to your house style."
 authors = [
     {name = "Yun-Tai Yang"},

{subedit-0.4.0 → subedit-0.5.0}/src/subedit/__init__.py

@@ -1,3 +1,3 @@
-__version__ = '0.4.0'
+__version__ = '0.5.0'
 
 __all__ = ['__version__']

{subedit-0.4.0 → subedit-0.5.0}/src/subedit/application/corpus_meter.py

@@ -86,8 +86,8 @@ class CorpusMeter:
             visibility = Visibility.PUBLIC if group.attaches_to_public_symbol else Visibility.INTERNAL
             return f'doc/{visibility.value}'
         if group.placement is CommentPlacement.FILE_HEADER:
-            return 'line/file-header'
-        return f'line/{group.placement.value}'
+            return 'plain/file-header'
+        return f'plain/{group.placement.value}'
 
     def _is_unbreakable(self, sentence: str, width: int) -> bool:
         return len(sentence) > width and ',' not in sentence

{subedit-0.4.0 → subedit-0.5.0}/src/subedit/domain/__init__.py

@@ -3,11 +3,13 @@ from .models import (
     PLAIN_MARKUP,
     QUOTED_DOC_LAYOUT,
     SEVERITY_BY_NAME,
+    ChoiceOption,
     CommentForm,
     CommentGroup,
     CommentLayout,
     CommentLine,
     CommentPlacement,
+    CountOption,
     Diagnostic,
     Document,
     EmbeddedDocument,
@@ -16,6 +18,7 @@ from .models import (
     Fix,
     FixKind,
     FramedDocLayout,
+    HeadingLevelsOption,
     LinePrefixLayout,
     MarkdownBlock,
     MarkdownBlockKind,
@@ -28,8 +31,10 @@ from .models import (
     ProseMarkup,
     ProseUnit,
     QuotedDocLayout,
+    ReplacementsOption,
     Report,
     RuleMetadata,
+    RuleOption,
     RuleSet,
     RuleSettings,
     Sentence,
@@ -39,6 +44,7 @@ from .models import (
     SymbolRef,
     TextEdit,
     Visibility,
+    WordsOption,
     apply_edits,
 )
 from .ports import (
@@ -57,11 +63,13 @@ __all__ = [
     'PLAIN_MARKUP',
     'QUOTED_DOC_LAYOUT',
     'SEVERITY_BY_NAME',
+    'ChoiceOption',
     'CommentForm',
     'CommentGroup',
     'CommentLayout',
     'CommentLine',
     'CommentPlacement',
+    'CountOption',
     'DelimiterSplit',
     'Diagnostic',
     'Document',
@@ -72,6 +80,7 @@ __all__ = [
     'Fix',
     'FixKind',
     'FramedDocLayout',
+    'HeadingLevelsOption',
     'LanguageConventions',
     'LinePrefixLayout',
     'MarkdownBlock',
@@ -86,10 +95,12 @@ __all__ = [
     'ProseMarkup',
     'ProseUnit',
     'QuotedDocLayout',
+    'ReplacementsOption',
     'Report',
     'Rule',
     'RuleContext',
     'RuleMetadata',
+    'RuleOption',
     'RuleSet',
     'RuleSettings',
     'Sentence',
@@ -100,5 +111,6 @@ __all__ = [
     'SymbolRef',
     'TextEdit',
     'Visibility',
+    'WordsOption',
     'apply_edits',
 ]

{subedit-0.4.0 → subedit-0.5.0}/src/subedit/domain/models/__init__.py

@@ -24,6 +24,7 @@ from .position import Encoding, Position, PositionMap, SourceRange
 from .prose import PLAIN_MARKUP, Prose, ProseMarkup, Sentence
 from .prose_map import ProseMap
 from .prose_unit import ProseLine, ProseUnit
+from .rule_option import ChoiceOption, CountOption, HeadingLevelsOption, ReplacementsOption, RuleOption, WordsOption
 from .rule_set import RuleSet, RuleSettings
 from .text import TextEdit, apply_edits
 
@@ -33,11 +34,13 @@ __all__ = [
     'PLAIN_MARKUP',
     'QUOTED_DOC_LAYOUT',
     'SEVERITY_BY_NAME',
+    'ChoiceOption',
     'CommentForm',
     'CommentGroup',
     'CommentLayout',
     'CommentLine',
     'CommentPlacement',
+    'CountOption',
     'Diagnostic',
     'Document',
     'EmbeddedDocument',
@@ -46,6 +49,7 @@ __all__ = [
     'Fix',
     'FixKind',
     'FramedDocLayout',
+    'HeadingLevelsOption',
     'LinePrefixLayout',
     'MarkdownBlock',
     'MarkdownBlockKind',
@@ -58,8 +62,10 @@ __all__ = [
     'ProseMarkup',
     'ProseUnit',
     'QuotedDocLayout',
+    'ReplacementsOption',
     'Report',
     'RuleMetadata',
+    'RuleOption',
     'RuleSet',
     'RuleSettings',
     'Sentence',
@@ -69,5 +75,6 @@ __all__ = [
     'SymbolRef',
     'TextEdit',
     'Visibility',
+    'WordsOption',
     'apply_edits',
 ]

subedit-0.5.0/src/subedit/domain/models/abbreviations.py

@@ -0,0 +1,64 @@
+import importlib.resources
+
+
+# The abbreviations Unicode CLDR lists for English, each with its final period and matched with its case.
+# A lone letter such as A. is an initial, which prose reading judges by whether it stands as a word of its own.
+CLDR_SUPPRESSIONS = frozenset(
+    line
+    for line in importlib.resources.files(__name__.rpartition('.')[0])
+    .joinpath('cldr_sentence_suppressions.txt')
+    .read_text(encoding='utf-8')
+    .splitlines()
+    if line and not line.startswith('#') and len(line) > 2
+)
+
+# Latin abbreviations, which CLDR lists only capitalized, such as E.g., while prose mostly writes them lowercase.
+_LATIN = frozenset({'al.', 'approx.', 'ca.', 'cf.', 'e.g.', 'etc.', 'i.e.', 'p.m.', 'resp.', 'viz.', 'vs.'})
+# Abbreviations that point into a document, such as Fig. 3, which end no sentence only before a number.
+_BEFORE_A_NUMBER = frozenset(
+    {'art.', 'ch.', 'eq.', 'eqs.', 'fig.', 'figs.', 'no.', 'nos.', 'p.', 'para.', 'ref.', 'sec.', 'vol.'}
+)
+
+
+# Courtesy titles and ranks, which stand before a name, so the capitalized word after one is that name.
+_TITLES = frozenset(
+    {
+        'capt.',
+        'col.',
+        'dr.',
+        'gen.',
+        'gov.',
+        'hon.',
+        'lt.',
+        'maj.',
+        'mr.',
+        'mrs.',
+        'ms.',
+        'mt.',
+        'mx.',
+        'prof.',
+        'pvt.',
+        'sen.',
+        'sgt.',
+        'st.',
+    }
+)
+
+
+def ends_no_sentence(word: str, following: str, added: frozenset[str] = frozenset()) -> bool:
+    """Whether a word written with its period, such as Dr., abbreviates rather than ends the sentence.
+
+    added holds the project's own abbreviations, each written with its period and matched with its case.
+    Many CLDR entries, such as Go. or OK., are also words that end a sentence,
+    so one ends no sentence only where its context shows an abbreviation, as Punkt reads the case of the next word.
+    """
+    lowered = word.lower()
+    next_character = following.lstrip()[:1]
+    if word in added or lowered in _LATIN or (lowered in _TITLES and word[:1].isupper()):
+        return True
+    if lowered in _BEFORE_A_NUMBER:
+        return next_character.isdigit()
+    if word in CLDR_SUPPRESSIONS:
+        # A period inside the word, as in U.S. or Ph.D., marks it an abbreviation whatever follows.
+        return '.' in word[:-1] or not next_character.isupper()
+    return False