subedit 0.1.1__tar.gz → 0.1.2__tar.gz

{subedit-0.1.1 → subedit-0.1.2}/.claude-plugin/plugin.json

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

subedit-0.1.2/.vale.ini

@@ -0,0 +1,13 @@
+StylesPath = src/subedit/vale/styles
+MinAlertLevel = warning
+
+[*.{py,ts,tsx,js,go,rs}]
+BasedOnStyles = subedit
+subedit.MidSentenceColonMarkup = NO
+
+[*.md]
+BasedOnStyles = subedit
+subedit.MidSentenceColon = NO
+
+[tests/fixtures/vale/*]
+BasedOnStyles =

{subedit-0.1.1 → subedit-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: subedit
-Version: 0.1.1
+Version: 0.1.2
 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
@@ -163,11 +163,19 @@ block-too-long = { severity = "warning", line = 3, doc-public = 20 }
 
 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.
+
+```toml
+[rules]
+"subedit.MidSentenceColon" = "error"
+"subedit.DateRef" = "off"
+```
+
 ## Delegated Tools
 
 `check`, `fix`, and the agent hook also run two tools, and fold their findings into the same report.
 
-- **Vale**: punctuation, banned phrasing, and anything a markup aware prose linter already handles. Vale has no autofix, so its findings come back as rewrites. It runs where it is installed, or where the `vale` extra fetched it. A repository without its own `.vale.ini` gets the `mroops` style that ships with subedit.
+- **Vale**: punctuation, banned phrasing, and anything a markup aware prose linter already handles. Vale has no autofix, so its findings come back as rewrites. It runs where it is installed, or where the `vale` extra fetched it. A repository without its own `.vale.ini` gets the style that ships with subedit, whose rules are named `subedit.*`.
 - **AutoCorrect**: spacing and punctuation width between CJK and Latin text. Its corrections are applied silently, like any other mechanical fix. It arrives as a Python dependency, and reads `.autocorrectrc` from the working directory.
 
 `--no-delegate` skips both for `check` and `fix`.

{subedit-0.1.1 → subedit-0.1.2}/README.md

@@ -129,11 +129,19 @@ block-too-long = { severity = "warning", line = 3, doc-public = 20 }
 
 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.
+
+```toml
+[rules]
+"subedit.MidSentenceColon" = "error"
+"subedit.DateRef" = "off"
+```
+
 ## Delegated Tools
 
 `check`, `fix`, and the agent hook also run two tools, and fold their findings into the same report.
 
-- **Vale**: punctuation, banned phrasing, and anything a markup aware prose linter already handles. Vale has no autofix, so its findings come back as rewrites. It runs where it is installed, or where the `vale` extra fetched it. A repository without its own `.vale.ini` gets the `mroops` style that ships with subedit.
+- **Vale**: punctuation, banned phrasing, and anything a markup aware prose linter already handles. Vale has no autofix, so its findings come back as rewrites. It runs where it is installed, or where the `vale` extra fetched it. A repository without its own `.vale.ini` gets the style that ships with subedit, whose rules are named `subedit.*`.
 - **AutoCorrect**: spacing and punctuation width between CJK and Latin text. Its corrections are applied silently, like any other mechanical fix. It arrives as a Python dependency, and reads `.autocorrectrc` from the working directory.
 
 `--no-delegate` skips both for `check` and `fix`.

subedit-0.1.2/docs/rules.md

@@ -0,0 +1,18 @@
+# Rules
+
+Generated from `RuleMetadata`. Edit the rule, not this file.
+
+The fix kind states who resolves a finding. A mechanical kind is repaired without telling the author, so only a rewrite reaches an agent.
+
+The level says whether a rewrite blocks. An error fails check and stops an agent, while a warning is shown as advice. Set either per rule under `[rules]`, and the Vale rules the same way by name, as in `"subedit.DateRef" = "off"`.
+
+| Rule | Fix kind | Level | Summary |
+| --- | --- | --- | --- |
+| `line-too-long` | reflow | error | A physical comment line must fit the configured width, counting indent and delimiter. |
+| `mid-clause-break` | reflow | error | A comment block must be laid out one sentence per line, splitting only at commas. |
+| `block-too-long` | rewrite | warning | A comment block long enough to restate the code has stopped earning its place. |
+| `file-header-comment` | rewrite | warning | A file must not open with a banner comment before its first declaration. |
+| `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 comma so it has somewhere legal to break. |

{subedit-0.1.1 → subedit-0.1.2}/hooks/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.1'
+SPEC='subedit[vale]>=0.1.2'
 # 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.1 → subedit-0.1.2}/pyproject.toml

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

{subedit-0.1.1 → subedit-0.1.2}/src/subedit/__init__.py

@@ -1,3 +1,3 @@
-__version__ = '0.1.1'
+__version__ = '0.1.2'
 
 __all__ = ['__version__']

{subedit-0.1.1 → subedit-0.1.2}/src/subedit/application/fixer.py

@@ -25,7 +25,7 @@ class FixResult:
 
     @property
     def unresolved_findings(self) -> tuple[Diagnostic, ...]:
-        return self.report.needing_author
+        return self.report.blocking
 
 
 class Fixer:

{subedit-0.1.1 → subedit-0.1.2}/src/subedit/application/report_aggregator.py

@@ -1,4 +1,6 @@
-from ..domain.models.diagnostic import Report
+import dataclasses
+
+from ..domain.models.diagnostic import Diagnostic, Report
 from ..domain.models.document import Document
 from ..domain.models.rule_set import RuleSet
 from ..domain.ports.external_linter import ExternalLinter
@@ -17,7 +19,17 @@ class ReportAggregator:
             if not external_linter.is_available():
                 missing_sources.append(external_linter.name)
                 continue
-            report = report.merged_with(Report(external_linter.run(document)))
+            report = report.merged_with(Report(self._configured(external_linter.run(document), rule_set)))
         if missing_sources:
             report = report.merged_with(Report(unavailable_sources=tuple(missing_sources)))
         return report
+
+    # The project's config has the last word on a delegated rule, as it does on a native one.
+    def _configured(self, diagnostics: tuple[Diagnostic, ...], rule_set: RuleSet) -> tuple[Diagnostic, ...]:
+        configured: list[Diagnostic] = []
+        for diagnostic in diagnostics:
+            if not rule_set.allows_external(diagnostic.rule_id):
+                continue
+            severity = rule_set.settings_for(diagnostic.rule_id).severity
+            configured.append(dataclasses.replace(diagnostic, severity=severity) if severity else diagnostic)
+        return tuple(configured)

{subedit-0.1.1 → subedit-0.1.2}/src/subedit/domain/models/comment.py

@@ -97,24 +97,34 @@ class CommentGroup:
         ]
         return Prose('\n'.join(rendered_lines))
 
-    def reflow(self, width: int) -> 'CommentGroup':
-        texts = self._reflow_into_texts(width)
+    def reflow(self, width: int, stub_floor: int = 0) -> 'CommentGroup':
+        # 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)
         if not texts:
             return self
         return self._rebuild_lines(texts)
 
-    def _reflow_into_texts(self, width: int) -> tuple[str, ...]:
+    # A sentence whose split strands a stub needs its author,
+    # so the block keeps the layout they gave it rather than one its own check rejects.
+    def _reflow_into_texts(self, width: int, stub_floor: int) -> tuple[str, ...]:
         budget = max(20, width - self.lines[0].prefix_width)
         out: list[str] = []
-        for paragraph, is_literal in self._split_into_paragraphs():
+        for paragraph_index, (paragraph, is_literal) in enumerate(self._split_into_paragraphs()):
             if out:
                 out.append('')
             if is_literal:
                 out.extend(paragraph)
                 continue
             joined_text = ' '.join(line.strip() for line in paragraph if line.strip())
-            for sentence in Prose(joined_text).sentences():
-                out.extend(reflow_sentence(sentence.text, budget))
+            for sentence_index, sentence in enumerate(Prose(joined_text).sentences()):
+                if sentence_index == 1 and paragraph_index == 0 and self.form is CommentForm.DOC:
+                    out.append('')
+                sentence_lines = reflow_sentence(sentence.text, budget)
+                if len(sentence_lines) > 1 and min(map(len, sentence_lines)) < stub_floor:
+                    return ()
+                out.extend(sentence_lines)
         return tuple(out)
 
     def _split_into_paragraphs(self) -> tuple[tuple[tuple[str, ...], bool], ...]:
@@ -138,7 +148,8 @@ class CommentGroup:
         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)
-        if closes_alone or len(texts) > 1:
+        # 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='')
             )

{subedit-0.1.1 → subedit-0.1.2}/src/subedit/domain/models/diagnostic.py

@@ -96,6 +96,19 @@ class Report:
     def needing_author(self) -> tuple[Diagnostic, ...]:
         return tuple(diagnostic for diagnostic in self.diagnostics if diagnostic.needs_author)
 
+    @property
+    def blocking(self) -> tuple[Diagnostic, ...]:
+        """The findings an author must resolve, since a warning reaches them as advice and blocks nothing."""
+        return tuple(diagnostic for diagnostic in self.needing_author if diagnostic.severity is Severity.ERROR)
+
+    @property
+    def advisory(self) -> tuple[Diagnostic, ...]:
+        return tuple(diagnostic for diagnostic in self.needing_author if diagnostic.severity is not Severity.ERROR)
+
+    @property
+    def has_errors(self) -> bool:
+        return any(diagnostic.severity is Severity.ERROR for diagnostic in self.diagnostics)
+
     @property
     def is_clean(self) -> bool:
         return not self.diagnostics

{subedit-0.1.1 → subedit-0.1.2}/src/subedit/domain/models/prose.py

@@ -26,6 +26,7 @@ _FENCE = re.compile(r'^\s*(```|~~~)')
 _LIST_DELIMITER = re.compile(r'^\s*(?:[0-9]+[.)]|[-*+]|[a-zA-Z][.)])\s')
 _LITERAL_DELIMITER = '\\b'
 _CLOSING_MARKS = '"\')]}'
+_APOSTROPHES = ("'", '\u2019')
 
 # Only before a number, since "No. 5" abbreviates while a trailing no ends its sentence.
 NUMBER_ABBREVIATION = 'no'
@@ -161,6 +162,9 @@ class Prose:
         if offset + 1 < len(text) and text[offset + 1].isdigit():
             return False
         trailing_word = _TRAILING_WORD.search(text[:offset])
+        # The s of a possessive is no initial, so a sentence closing on a word like API's still ends there.
+        if trailing_word and text[: trailing_word.start()].endswith(_APOSTROPHES):
+            return self._followed_by_break(text, offset)
         word = trailing_word.group(1).lower().rstrip('.') if trailing_word else ''
         if word in ABBREVIATIONS:
             return False

{subedit-0.1.1 → subedit-0.1.2}/src/subedit/domain/models/rule_set.py

@@ -19,6 +19,8 @@ class RuleSet:
     enabled_rule_ids: frozenset[str]
     settings: typing.Mapping[str, RuleSettings] = dataclasses.field(default_factory=dict)
     line_width: int = 120
+    # A delegated tool's rules are not known up front, so they are listed when switched off instead.
+    disabled_external_ids: frozenset[str] = frozenset()
 
     def is_enabled(self, rule_id: str) -> bool:
         return rule_id in self.enabled_rule_ids
@@ -28,3 +30,6 @@ class RuleSet:
 
     def severity_for(self, metadata: RuleMetadata) -> Severity:
         return self.settings_for(metadata.rule_id).severity or metadata.default_severity
+
+    def allows_external(self, rule_id: str) -> bool:
+        return rule_id not in self.disabled_external_ids

{subedit-0.1.1 → subedit-0.1.2}/src/subedit/domain/ports/external_linter.py

@@ -12,3 +12,6 @@ class ExternalLinter(abc.ABC):
 
     @abc.abstractmethod
     def run(self, document: Document) -> tuple[Diagnostic, ...]: ...
+
+    def prepare(self) -> None:  # noqa: B027, an optional hook rather than a required one
+        """Fetch what the tool needs, for a caller that can afford to wait. Most tools need nothing."""

{subedit-0.1.1 → subedit-0.1.2}/src/subedit/domain/rules/layout.py

@@ -3,6 +3,7 @@ import typing
 from ..models.comment import CommentGroup
 from ..models.diagnostic import Diagnostic, Fix, FixKind, RuleMetadata
 from ..ports.rule import Rule, RuleContext
+from .rewrite import stub_floor
 
 
 MID_CLAUSE_BREAK = RuleMetadata(
@@ -22,7 +23,7 @@ class MidClauseBreakRule(Rule):
     metadata = MID_CLAUSE_BREAK
 
     def check(self, group: CommentGroup, context: RuleContext) -> typing.Iterable[Diagnostic]:
-        reflowed = group.reflow(context.line_width)
+        reflowed = group.reflow(context.line_width, stub_floor(context))
         if reflowed.render() == group.render():
             return
         yield Diagnostic(
@@ -43,7 +44,7 @@ class LineTooLongRule(Rule):
         width = context.line_width
         if group.longest_line <= width:
             return
-        reflowed = group.reflow(width)
+        reflowed = group.reflow(width, stub_floor(context))
         if reflowed.longest_line > width:
             return
         yield Diagnostic(

{subedit-0.1.1 → subedit-0.1.2}/src/subedit/domain/rules/rewrite.py

@@ -1,7 +1,7 @@
 import typing
 
 from ..models.comment import CommentGroup
-from ..models.diagnostic import Diagnostic, Fix, FixKind, RuleMetadata
+from ..models.diagnostic import Diagnostic, Fix, FixKind, RuleMetadata, Severity
 from ..models.prose import Prose, reflow_sentence
 from ..ports.rule import Rule, RuleContext
 
@@ -10,6 +10,7 @@ STUB_FRAGMENT = RuleMetadata(
     rule_id='stub-fragment',
     summary='A sentence forced to break must not leave a stub of a line behind.',
     fix_kind=FixKind.REWRITE,
+    default_severity=Severity.WARNING,
 )
 
 UNBREAKABLE_SENTENCE = RuleMetadata(
@@ -35,14 +36,19 @@ def sentence_budget(group: CommentGroup, context: RuleContext) -> int:
     return max(20, context.line_width - group.lines[0].prefix_width)
 
 
+def stub_floor(context: RuleContext) -> int:
+    """Reflow reads the same floor, so a fix never lays out a stub that this rule then rejects."""
+    if not context.rule_set.is_enabled(STUB_FRAGMENT.rule_id):
+        return 0
+    return context.settings(STUB_FRAGMENT.rule_id).integer('minimum_characters', DEFAULT_MINIMUM_CHARACTERS)
+
+
 class StubFragmentRule(Rule):
     metadata = STUB_FRAGMENT
 
     def check(self, group: CommentGroup, context: RuleContext) -> typing.Iterable[Diagnostic]:
         budget = sentence_budget(group, context)
-        minimum_length = context.settings(self.metadata.rule_id).integer(
-            'minimum_characters', DEFAULT_MINIMUM_CHARACTERS
-        )
+        minimum_length = stub_floor(context)
         for sentence in prose_sentences(group):
             split_pieces = reflow_sentence(sentence, budget)
             if len(split_pieces) < 2:

{subedit-0.1.1 → subedit-0.1.2}/src/subedit/domain/rules/structure.py

@@ -1,7 +1,7 @@
 import typing
 
 from ..models.comment import CommentForm, CommentGroup, CommentPlacement
-from ..models.diagnostic import Diagnostic, Fix, FixKind, RuleMetadata
+from ..models.diagnostic import Diagnostic, Fix, FixKind, RuleMetadata, Severity
 from ..ports.language_conventions import LanguageConventions
 from ..ports.rule import Rule, RuleContext
 
@@ -10,6 +10,7 @@ FILE_HEADER_COMMENT = RuleMetadata(
     rule_id='file-header-comment',
     summary='A file must not open with a banner comment before its first declaration.',
     fix_kind=FixKind.REWRITE,
+    default_severity=Severity.WARNING,
 )
 
 PLAIN_COMMENT_ON_PUBLIC = RuleMetadata(
@@ -104,6 +105,7 @@ BLOCK_TOO_LONG = RuleMetadata(
     rule_id='block-too-long',
     summary='A comment block long enough to restate the code has stopped earning its place.',
     fix_kind=FixKind.REWRITE,
+    default_severity=Severity.WARNING,
 )
 
 

{subedit-0.1.1 → subedit-0.1.2}/src/subedit/infrastructure/config_sources/toml_config_source.py

@@ -83,13 +83,16 @@ class TomlConfigSource:
 
     def _to_rule_set(self, config_file: ConfigFile) -> RuleSet:
         enabled_ids = set(self._available_rule_ids)
+        disabled_external_ids: set[str] = set()
         settings: dict[str, RuleSettings] = {}
 
+        # A name subedit does not define belongs to a delegated tool, such as subedit.Semicolon from Vale.
         for rule_id, rule_entry in config_file.rules.items():
-            if rule_id not in self._available_rule_ids:
-                continue
             if rule_entry is False or rule_entry == 'off':
-                enabled_ids.discard(rule_id)
+                if rule_id in self._available_rule_ids:
+                    enabled_ids.discard(rule_id)
+                else:
+                    disabled_external_ids.add(rule_id)
             elif isinstance(rule_entry, RuleTable):
                 settings[rule_id] = RuleSettings(severity=rule_entry.resolved_severity, options=rule_entry.options)
             elif isinstance(rule_entry, str):
@@ -99,4 +102,5 @@ class TomlConfigSource:
             enabled_rule_ids=frozenset(enabled_ids),
             settings=settings,
             line_width=config_file.subedit.line_width,
+            disabled_external_ids=frozenset(disabled_external_ids),
         )

{subedit-0.1.1 → subedit-0.1.2}/src/subedit/infrastructure/linters/vale_linter.py

@@ -13,6 +13,8 @@ from ...domain.ports.external_linter import ExternalLinter
 
 
 TIMEOUT_SECONDS = 30
+# The first run of the vale extra downloads the binary, which a slow link can take minutes over.
+PREPARE_TIMEOUT_SECONDS = 900
 BUNDLED_CONFIG = pathlib.Path(__file__).resolve().parents[2] / 'vale' / 'vale.ini'
 # Vale exits with this code when its own search finds no config.
 NO_CONFIG_CODE = 'E100'
@@ -55,6 +57,20 @@ class ValeLinter(ExternalLinter):
     def is_available(self) -> bool:
         return shutil.which(self._executable) is not None and _launcher_is_ready()
 
+    def prepare(self) -> None:
+        """Let the vale extra finish its download, with progress left on stderr so a waiting command shows why."""
+        if _launcher_is_ready() or shutil.which(self._executable) is None:
+            return
+        try:
+            subprocess.run(  # noqa: S603
+                [self._executable, '--version'],
+                stdout=subprocess.DEVNULL,
+                check=False,
+                timeout=PREPARE_TIMEOUT_SECONDS,
+            )
+        except (OSError, subprocess.TimeoutExpired):
+            return
+
     def run(self, document: Document) -> tuple[Diagnostic, ...]:
         if not self.is_available():
             return ()

{subedit-0.1.1 → subedit-0.1.2}/src/subedit/infrastructure/parsers/languages/language_profile.py

@@ -10,6 +10,7 @@ from ....domain.ports.language_conventions import LanguageConventions
 class NodeRole(enum.Enum):
     ROOT = 'root'
     DEFINITION = 'definition'
+    IMPORT = 'import'
     COMMENT = 'comment'
     OTHER = 'other'
 

{subedit-0.1.1 → subedit-0.1.2}/src/subedit/infrastructure/parsers/languages/python_profile.py

@@ -32,6 +32,9 @@ class PythonProfile(LanguageProfile):
         'function_definition': NodeRole.DEFINITION,
         'class_definition': NodeRole.DEFINITION,
         'decorated_definition': NodeRole.DEFINITION,
+        'import_statement': NodeRole.IMPORT,
+        'import_from_statement': NodeRole.IMPORT,
+        'future_import_statement': NodeRole.IMPORT,
     }
 
     def language(self) -> Language:

{subedit-0.1.1 → subedit-0.1.2}/src/subedit/infrastructure/parsers/tree_sitter_parser.py

@@ -150,10 +150,24 @@ class TreeSitterParser(SourceParser):
             return CommentPlacement.LEADING_DECLARATION
         parent = node.parent
         is_root = parent is not None and profile.role_of(parent.type) is NodeRole.ROOT
-        if is_root and not self._has_code_before(profile, node):
+        if is_root and not self._has_code_before(profile, node) and not self._touches_next_code(profile, node):
             return CommentPlacement.FILE_HEADER
         return CommentPlacement.INLINE_BODY
 
+    # 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.
+    def _touches_next_code(self, profile: LanguageProfile, node: Node) -> bool:
+        candidate = node.next_named_sibling
+        return (
+            candidate is not None
+            and profile.role_of(candidate.type) not in (NodeRole.COMMENT, NodeRole.IMPORT)
+            and self._is_adjacent(node, 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:
+        return lower.start_point[0] == upper.end_point[0] + 1
+
     def _has_code_before(self, profile: LanguageProfile, node: Node) -> bool:
         parent = node.parent
         if parent is None:
@@ -164,13 +178,15 @@ class TreeSitterParser(SourceParser):
         )
 
     def _find_next_definition(self, profile: LanguageProfile, node: Node) -> Node | None:
+        previous = node
         candidate = node.next_named_sibling
-        while candidate is not None:
+        while candidate is not None and self._is_adjacent(previous, candidate):
             role = profile.role_of(candidate.type)
             if role is NodeRole.DEFINITION:
                 return candidate
             if role is not NodeRole.COMMENT:
                 return None
+            previous = candidate
             candidate = candidate.next_named_sibling
         return None
 

{subedit-0.1.1 → subedit-0.1.2}/src/subedit/presentation/cli.py

@@ -38,14 +38,14 @@ def check(
         raise typer.Exit(2)
 
     aggregator = _build_report_aggregator(delegate)
-    finding_count = 0
+    has_errors = False
     for document in documents:
         report = aggregator.run(document, DEFAULT_CONFIG_SOURCE.resolve(_file_path(document)))
-        finding_count += len(report.diagnostics)
+        has_errors = has_errors or report.has_errors
         rendered_report = formatter(document, report)
         if rendered_report:
             typer.echo(rendered_report)
-    raise typer.Exit(1 if finding_count else 0)
+    raise typer.Exit(1 if has_errors else 0)
 
 
 @app.command()
@@ -71,6 +71,8 @@ def fix(
                 typer.echo(_diff(document, fix_result.document))
         if fix_result.unresolved_findings:
             typer.echo(reporters.brief(fix_result.document, fix_result.report))
+        if fix_result.report.advisory:
+            typer.echo(reporters.advice(fix_result.document, fix_result.report))
 
     action_word = 'rewrote' if write else 'would rewrite'
     typer.echo(
@@ -146,8 +148,19 @@ def _build_report_aggregator(delegate: bool) -> ReportAggregator:
     return ReportAggregator(_build_linter(), _external_linters(delegate))
 
 
+# A command can wait for a download, unlike the hook, and a skipped tool must not read as a clean run.
 def _external_linters(delegate: bool) -> tuple[ExternalLinter, ...]:
-    return EXTERNAL_LINTERS if delegate else ()
+    if not delegate:
+        return ()
+    for external_linter in EXTERNAL_LINTERS:
+        external_linter.prepare()
+        if not external_linter.is_available():
+            typer.echo(
+                f'{external_linter.name} is not installed, so its checks were skipped. '
+                'Install subedit[vale] for Vale, or pass --no-delegate to skip it on purpose.',
+                err=True,
+            )
+    return EXTERNAL_LINTERS
 
 
 def _file_path(document: Document) -> str:

{subedit-0.1.1 → subedit-0.1.2}/src/subedit/presentation/report.py

@@ -16,14 +16,26 @@ def full(document: Document, report: Report) -> str:
 
 
 def brief(document: Document, report: Report) -> str:
-    if not report.needing_author:
+    if not report.blocking:
         return ''
     return _rewrite_brief(document, report)
 
 
+def advice(document: Document, report: Report) -> str:
+    if not report.advisory:
+        return ''
+    lines = [
+        f'{len(report.advisory)} comment {"warning" if len(report.advisory) == 1 else "warnings"} in {_path(document)}, worth a look but not required.'
+    ]
+    lines.extend(_finding_lines(document, report.advisory))
+    return '\n'.join(lines)
+
+
 def actionable(document: Document, report: Report) -> str:
-    if report.needing_author:
+    if report.blocking:
         return _rewrite_brief(document, report)
+    if report.advisory:
+        return advice(document, report)
     if report.mechanical:
         mechanical_count = len(report.mechanical)
         return (
@@ -46,17 +58,23 @@ def as_json(document: Document, report: Report) -> str:
 
 
 def _rewrite_brief(document: Document, report: Report) -> str:
-    finding_count = len(report.needing_author)
+    finding_count = len(report.blocking)
     lines = [
         f'{finding_count} comment {"finding needs" if finding_count == 1 else "findings need"} rewriting in {_path(document)}.',
         'Each states the fix. Apply it in place, do not add a suppression comment.',
         '',
     ]
-    for diagnostic in report.needing_author:
+    lines.extend(_finding_lines(document, report.blocking))
+    return '\n'.join(lines)
+
+
+def _finding_lines(document: Document, diagnostics: tuple[Diagnostic, ...]) -> list[str]:
+    lines: list[str] = []
+    for diagnostic in diagnostics:
         position = document.positions.to_position(diagnostic.range.start)
         lines.append(f'line {position.line + 1}  [{diagnostic.rule_id}]')
         lines.append(f'  {diagnostic.message}')
-    return '\n'.join(lines)
+    return lines
 
 
 def _encode(document: Document, diagnostic: Diagnostic) -> dict[str, object]:

{subedit-0.1.1 → subedit-0.1.2}/src/subedit/presentation/rule_reference.py

@@ -6,16 +6,19 @@ HEADING = '# Rules'
 PREAMBLE = (
     'Generated from `RuleMetadata`. Edit the rule, not this file.\n\n'
     'The fix kind states who resolves a finding. A mechanical kind is repaired without telling the author, '
-    'so only a rewrite reaches an agent.'
+    'so only a rewrite reaches an agent.\n\n'
+    'The level says whether a rewrite blocks. An error fails check and stops an agent, '
+    'while a warning is shown as advice. Set either per rule under `[rules]`, '
+    'and the Vale rules the same way by name, as in `"subedit.DateRef" = "off"`.'
 )
 
 
 def render(rules: tuple[Rule, ...]) -> str:
     sorted_rules = sorted(rules, key=lambda rule: (rule.metadata.fix_kind.value, rule.metadata.rule_id))
-    lines = [HEADING, '', PREAMBLE, '', '| Rule | Fix kind | Summary |', '| --- | --- | --- |']
+    lines = [HEADING, '', PREAMBLE, '', '| Rule | Fix kind | Level | Summary |', '| --- | --- | --- | --- |']
     lines.extend(_row(rule.metadata) for rule in sorted_rules)
     return '\n'.join(lines) + '\n'
 
 
 def _row(metadata: RuleMetadata) -> str:
-    return f'| `{metadata.rule_id}` | {metadata.fix_kind.value} | {metadata.summary} |'
+    return f'| `{metadata.rule_id}` | {metadata.fix_kind.value} | {metadata.default_severity.name.lower()} | {metadata.summary} |'

subedit-0.1.2/src/subedit/vale/styles/subedit/DateRef.yml

@@ -0,0 +1,13 @@
+extends: existence
+message: "Date '%s' in a comment. Keep it if it names a version. If it records when something changed, state the current constraint instead."
+level: warning
+nonword: true
+tokens:
+  - '\b\d{4}-\d{2}-\d{2}\b'
+  - '\b\d{4}/\d{1,2}/\d{1,2}\b'
+  - '\b\d{1,2}/\d{1,2}/\d{4}\b'
+  - '\b(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Sept|Oct|Nov|Dec)[a-z]*\.? \d{1,2},? \d{4}\b'
+  - '\b\d{1,2} (?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Sept|Oct|Nov|Dec)[a-z]* \d{4}\b'
+  - '\b(?:January|February|March|April|May|June|July|August|September|October|November|December) \d{4}\b'
+  - '\b(?:[Aa]s of|[Ss]ince|[Uu]ntil) (?:Q[1-4] )?\d{4}\b'
+  - '\b[Ii]n Q[1-4] \d{4}\b'

subedit-0.1.2/src/subedit/vale/styles/subedit/ExternalRef.yml

@@ -0,0 +1,15 @@
+extends: existence
+message: "External reference '%s' a reader cannot open. Restate the constraint."
+level: error
+nonword: true
+tokens:
+  - '[A-Z]{2,}-\d+'
+# Standards and encodings are names a reader can look up, not tickets.
+exceptions:
+  - 'ISO-\d+'
+  - 'UTF-\d+'
+  - 'SHA-\d+'
+  - 'AES-\d+'
+  - 'CRC-\d+'
+  - 'IEEE-\d+'
+  - 'ECMA-\d+'