subedit 0.1.0__py3-none-any.whl

subedit/domain/rules/structure.py

@@ -0,0 +1,141 @@
+import typing
+
+from ..models.comment import CommentForm, CommentGroup, CommentPlacement
+from ..models.diagnostic import Diagnostic, Fix, FixKind, RuleMetadata
+from ..ports.language_conventions import LanguageConventions
+from ..ports.rule import Rule, RuleContext
+
+
+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,
+)
+
+PLAIN_COMMENT_ON_PUBLIC = RuleMetadata(
+    rule_id='plain-comment-on-public',
+    summary='A public symbol must be documented in the doc comment form its language renders.',
+    fix_kind=FixKind.REWRITE,
+)
+
+SIGNATURE_RESTATING_TAG = RuleMetadata(
+    rule_id='signature-restating-tag',
+    summary='A doc comment must not restate what the type signature already carries.',
+    fix_kind=FixKind.REWRITE,
+)
+
+
+class FileHeaderCommentRule(Rule):
+    metadata = FILE_HEADER_COMMENT
+
+    def check(self, group: CommentGroup, context: RuleContext) -> typing.Iterable[Diagnostic]:
+        if group.placement is not CommentPlacement.FILE_HEADER:
+            return
+        yield Diagnostic(
+            rule_id=self.metadata.rule_id,
+            range=group.range,
+            message=(
+                'This comment opens the file before any declaration. '
+                'A reader has the file, not a banner about it, so delete it. '
+                'If it states a constraint, move that to the declaration the constraint applies to.'
+            ),
+            fix=Fix.rewrite(),
+        )
+
+
+class PlainCommentOnPublicRule(Rule):
+    metadata = PLAIN_COMMENT_ON_PUBLIC
+
+    def __init__(self, conventions: LanguageConventions) -> None:
+        self._conventions = conventions
+
+    def check(self, group: CommentGroup, context: RuleContext) -> typing.Iterable[Diagnostic]:
+        if not group.attaches_to_public_symbol or group.form is CommentForm.DOC:
+            return
+        if group.placement is not CommentPlacement.LEADING_DECLARATION:
+            return
+        delimiter = self._conventions.doc_delimiter
+        name = group.attachment.name if group.attachment else 'the symbol'
+        yield Diagnostic(
+            rule_id=self.metadata.rule_id,
+            range=group.range,
+            message=(
+                f'{name} is public but documented with a plain comment. '
+                f'Move the text into a {delimiter} doc comment so tooling renders it on hover.'
+            ),
+            fix=Fix.rewrite(),
+        )
+
+
+class SignatureRestatingTagRule(Rule):
+    metadata = SIGNATURE_RESTATING_TAG
+
+    def __init__(self, conventions: LanguageConventions) -> None:
+        self._conventions = conventions
+
+    def check(self, group: CommentGroup, context: RuleContext) -> typing.Iterable[Diagnostic]:
+        if group.form is not CommentForm.DOC:
+            return
+        for line in group.lines:
+            matched_tag = self._first_matching_tag(line.text)
+            if matched_tag is None:
+                continue
+            yield Diagnostic(
+                rule_id=self.metadata.rule_id,
+                range=group.range,
+                message=(
+                    f'The tag "{matched_tag}" restates the signature, which the annotations already carry. '
+                    'Delete the tag and its block. '
+                    'If a parameter needs explaining, say why it matters in prose instead.'
+                ),
+                fix=Fix.rewrite(),
+            )
+            return
+
+    def _first_matching_tag(self, text: str) -> str | None:
+        stripped_text = text.strip()
+        for matched_tag in self._conventions.signature_tags:
+            if stripped_text.startswith(matched_tag):
+                return matched_tag
+        return None
+
+
+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,
+)
+
+
+# Set from the p95 of a measured corpus, which subedit stats reports.
+# A comment past this length has usually started restating the code below it.
+DEFAULT_LIMITS = {
+    'line': 4,
+    'doc-internal': 13,
+    'doc-public': 20,
+}
+
+
+class BlockTooLongRule(Rule):
+    metadata = BLOCK_TOO_LONG
+
+    def check(self, group: CommentGroup, context: RuleContext) -> typing.Iterable[Diagnostic]:
+        category = self._category(group)
+        limit = context.settings(self.metadata.rule_id).integer(category, DEFAULT_LIMITS[category])
+        if group.line_count <= limit:
+            return
+        yield Diagnostic(
+            rule_id=self.metadata.rule_id,
+            range=group.range,
+            message=(
+                f'This comment runs to {group.line_count} lines against a limit of {limit} lines for {category} '
+                'comments. A comment earns its place by stating one constraint the code cannot show. '
+                'Cut it to that constraint, or move the explanation into a name.'
+            ),
+            fix=Fix.rewrite(),
+        )
+
+    def _category(self, group: CommentGroup) -> str:
+        if group.form is not CommentForm.DOC:
+            return 'line'
+        return 'doc-public' if group.attaches_to_public_symbol else 'doc-internal'

subedit/infrastructure/__init__.py

@@ -0,0 +1,47 @@
+from ..domain.rules import (
+    BlockTooLongRule,
+    FileHeaderCommentRule,
+    LineTooLongRule,
+    MidClauseBreakRule,
+    PlainCommentOnPublicRule,
+    SignatureRestatingTagRule,
+    StubFragmentRule,
+    UnbreakableSentenceRule,
+)
+from .config_sources import CONFIG_NAME, TomlConfigSource
+from .linters import AutoCorrectLinter, ValeLinter
+from .parsers import PYTHON, LanguageProfile, NodeRole, TreeSitterParser
+
+
+LAYOUT_RULES = (MidClauseBreakRule(), LineTooLongRule())
+REWRITE_RULES = (StubFragmentRule(), UnbreakableSentenceRule())
+STRUCTURAL_RULES = (
+    FileHeaderCommentRule(),
+    PlainCommentOnPublicRule(PYTHON),
+    SignatureRestatingTagRule(PYTHON),
+    BlockTooLongRule(),
+)
+ALL_RULES = LAYOUT_RULES + REWRITE_RULES + STRUCTURAL_RULES
+
+DEFAULT_PARSER = TreeSitterParser((PYTHON,))
+DEFAULT_CONFIG_SOURCE = TomlConfigSource(tuple(rule.metadata.rule_id for rule in ALL_RULES))
+
+EXTERNAL_LINTERS = (ValeLinter(), AutoCorrectLinter())
+
+__all__ = [
+    'ALL_RULES',
+    'CONFIG_NAME',
+    'DEFAULT_CONFIG_SOURCE',
+    'DEFAULT_PARSER',
+    'EXTERNAL_LINTERS',
+    'LAYOUT_RULES',
+    'PYTHON',
+    'REWRITE_RULES',
+    'STRUCTURAL_RULES',
+    'AutoCorrectLinter',
+    'LanguageProfile',
+    'NodeRole',
+    'TomlConfigSource',
+    'TreeSitterParser',
+    'ValeLinter',
+]

subedit/infrastructure/config_sources/__init__.py

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

subedit/infrastructure/config_sources/config_schema.py

@@ -0,0 +1,43 @@
+import typing
+
+import pydantic
+
+from ...domain.models.diagnostic import SEVERITY_BY_NAME, Severity
+
+
+class RuleTable(pydantic.BaseModel):
+    model_config = pydantic.ConfigDict(extra='allow', frozen=True)
+
+    severity: str | None = None
+
+    @property
+    def resolved_severity(self) -> Severity | None:
+        return SEVERITY_BY_NAME.get(self.severity) if self.severity else None
+
+    @property
+    def options(self) -> dict[str, object]:
+        return dict(self.__pydantic_extra__ or {})
+
+
+RuleEntry = typing.Annotated[bool | str | RuleTable, pydantic.Field(union_mode='left_to_right')]
+
+
+class SubeditSection(pydantic.BaseModel):
+    model_config = pydantic.ConfigDict(frozen=True, populate_by_name=True)
+
+    line_width: int = pydantic.Field(default=120, alias='line-width', gt=0)
+    exclude: tuple[str, ...] = ()
+
+
+class ConfigFile(pydantic.BaseModel):
+    model_config = pydantic.ConfigDict(frozen=True)
+
+    subedit: SubeditSection = pydantic.Field(default_factory=SubeditSection)
+    rules: dict[str, RuleEntry] = pydantic.Field(default_factory=dict)
+
+    @classmethod
+    def parse(cls, raw: typing.Mapping[str, object]) -> 'ConfigFile':
+        try:
+            return cls.model_validate(raw)
+        except pydantic.ValidationError:
+            return cls()

subedit/infrastructure/config_sources/toml_config_source.py

@@ -0,0 +1,102 @@
+import fnmatch
+import pathlib
+import tomllib
+
+from ...domain.models.rule_set import RuleSet, RuleSettings
+from .config_schema import ConfigFile, RuleTable
+
+
+CONFIG_NAME = 'subedit.toml'
+PYPROJECT_NAME = 'pyproject.toml'
+DEFAULT_WIDTH = 120
+
+
+class TomlConfigSource:
+    def __init__(self, available_rule_ids: tuple[str, ...]) -> None:
+        self._available_rule_ids = available_rule_ids
+
+    def resolve(self, path: str) -> RuleSet:
+        config_file = self._read(path)
+        if config_file is None:
+            return self.defaults()
+        return self._to_rule_set(config_file)
+
+    def defaults(self) -> RuleSet:
+        return RuleSet(enabled_rule_ids=frozenset(self._available_rule_ids), line_width=DEFAULT_WIDTH)
+
+    def exclude_patterns(self, path: str) -> tuple[str, ...]:
+        config_file = self._read(path)
+        return config_file.subedit.exclude if config_file else ()
+
+    def is_excluded(self, target: pathlib.Path, root: pathlib.Path, patterns: tuple[str, ...]) -> bool:
+        try:
+            relative = target.resolve().relative_to(root.resolve()).as_posix()
+        except ValueError:
+            relative = target.resolve().as_posix()
+        return any(fnmatch.fnmatch(relative, pattern) for pattern in patterns)
+
+    def root_for(self, path: str) -> pathlib.Path:
+        config_path = self._locate(pathlib.Path(path))
+        return config_path.parent if config_path else pathlib.Path.cwd()
+
+    def _read(self, path: str) -> ConfigFile | None:
+        config_path = self._locate(pathlib.Path(path))
+        if config_path is None:
+            return None
+        try:
+            raw_table = tomllib.loads(config_path.read_text(encoding='utf-8'))
+        except (OSError, tomllib.TOMLDecodeError):
+            return None
+        if config_path.name == PYPROJECT_NAME:
+            raw_table = self._reshape_pyproject(raw_table)
+            if raw_table is None:
+                return None
+        return ConfigFile.parse(raw_table)
+
+    def _reshape_pyproject(self, raw_table: dict[str, object]) -> dict[str, object] | None:
+        tools = raw_table.get('tool')
+        tool_section = tools.get('subedit') if isinstance(tools, dict) else None
+        if not isinstance(tool_section, dict):
+            return None
+        return {
+            'subedit': {name: setting for name, setting in tool_section.items() if name != 'rules'},
+            'rules': tool_section.get('rules', {}),
+        }
+
+    def _locate(self, start: pathlib.Path) -> pathlib.Path | None:
+        base = start if start.is_dir() else start.parent
+        for directory in (base.resolve(), *base.resolve().parents):
+            for name in (CONFIG_NAME, PYPROJECT_NAME):
+                config_path = directory / name
+                if config_path.is_file() and self._carries_settings(config_path):
+                    return config_path
+        return None
+
+    def _carries_settings(self, config_path: pathlib.Path) -> bool:
+        if config_path.name != PYPROJECT_NAME:
+            return True
+        try:
+            tools = tomllib.loads(config_path.read_text(encoding='utf-8')).get('tool')
+        except (OSError, tomllib.TOMLDecodeError):
+            return False
+        return isinstance(tools, dict) and 'subedit' in tools
+
+    def _to_rule_set(self, config_file: ConfigFile) -> RuleSet:
+        enabled_ids = set(self._available_rule_ids)
+        settings: dict[str, RuleSettings] = {}
+
+        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)
+            elif isinstance(rule_entry, RuleTable):
+                settings[rule_id] = RuleSettings(severity=rule_entry.resolved_severity, options=rule_entry.options)
+            elif isinstance(rule_entry, str):
+                settings[rule_id] = RuleSettings(severity=RuleTable(severity=rule_entry).resolved_severity)
+
+        return RuleSet(
+            enabled_rule_ids=frozenset(enabled_ids),
+            settings=settings,
+            line_width=config_file.subedit.line_width,
+        )

subedit/infrastructure/linters/__init__.py

@@ -0,0 +1,5 @@
+from .autocorrect_linter import AutoCorrectLinter
+from .vale_linter import ValeLinter
+
+
+__all__ = ['AutoCorrectLinter', 'ValeLinter']

subedit/infrastructure/linters/autocorrect_linter.py

@@ -0,0 +1,71 @@
+import pathlib
+import re
+import shutil
+import subprocess
+
+from ...domain.models.diagnostic import Diagnostic, Fix, Severity
+from ...domain.models.document import Document
+from ...domain.models.position import Position, SourceRange
+from ...domain.models.text import TextEdit
+from ...domain.ports.external_linter import ExternalLinter
+
+
+LOCATION = re.compile(r'^(?P<source_path>.+?):(?P<line>\d+):(?P<column>\d+)$')
+TIMEOUT_SECONDS = 30
+RULE_ID = 'autocorrect/spacing'
+
+
+class AutoCorrectLinter(ExternalLinter):
+    name = 'autocorrect'
+
+    def __init__(self, executable: str = 'autocorrect') -> None:
+        self._executable = executable
+
+    def is_available(self) -> bool:
+        return shutil.which(self._executable) is not None
+
+    def run(self, document: Document) -> tuple[Diagnostic, ...]:
+        source_path = pathlib.Path(document.uri.removeprefix('file://'))
+        if not self.is_available() or not source_path.is_file():
+            return ()
+        corrected_text = self._run_autocorrect(source_path)
+        if corrected_text is None or corrected_text == document.text:
+            return ()
+        return self._diff_lines(document, corrected_text)
+
+    def _run_autocorrect(self, source_path: pathlib.Path) -> str | None:
+        try:
+            process = subprocess.run(  # noqa: S603
+                [self._executable, '--stdin', str(source_path)],
+                capture_output=True,
+                text=True,
+                check=False,
+                timeout=TIMEOUT_SECONDS,
+                input=source_path.read_text(encoding='utf-8'),
+            )
+        except (OSError, UnicodeDecodeError, subprocess.TimeoutExpired):
+            return None
+        return process.stdout if process.stdout else None
+
+    def _diff_lines(self, document: Document, corrected_text: str) -> tuple[Diagnostic, ...]:
+        original_lines = document.text.splitlines(keepends=True)
+        corrected_lines = corrected_text.splitlines(keepends=True)
+        if len(original_lines) != len(corrected_lines):
+            return ()
+        diagnostics: list[Diagnostic] = []
+        for index, (original, fixed) in enumerate(zip(original_lines, corrected_lines, strict=True)):
+            if original == fixed:
+                continue
+            start_offset = document.positions.to_offset(Position(index, 0))
+            end_offset = start_offset + len(original.rstrip('\n').encode('utf-8'))
+            diagnostics.append(
+                Diagnostic(
+                    rule_id=RULE_ID,
+                    range=SourceRange(start_offset, end_offset),
+                    message='Spacing or punctuation between CJK and Latin text needs correcting.',
+                    severity=Severity.ERROR,
+                    fix=Fix.targeted(TextEdit(SourceRange(start_offset, end_offset), fixed.rstrip('\n'))),
+                    source=self.name,
+                )
+            )
+        return tuple(diagnostics)

subedit/infrastructure/linters/vale_linter.py

@@ -0,0 +1,87 @@
+import pathlib
+import shutil
+import subprocess
+
+import pydantic
+
+from ...domain.models.diagnostic import SEVERITY_BY_NAME, Diagnostic, Fix, Severity
+from ...domain.models.document import Document
+from ...domain.models.position import Position, SourceRange
+from ...domain.ports.external_linter import ExternalLinter
+
+
+TIMEOUT_SECONDS = 30
+
+
+class ValeAlert(pydantic.BaseModel):
+    model_config = pydantic.ConfigDict(frozen=True, extra='ignore')
+
+    check: str = pydantic.Field(alias='Check')
+    message: str = pydantic.Field(alias='Message')
+    line: int = pydantic.Field(alias='Line', ge=1)
+    span: tuple[int, int] = pydantic.Field(default=(1, 1), alias='Span')
+    severity: str = pydantic.Field(default='error', alias='Severity')
+
+    @property
+    def resolved_severity(self) -> Severity:
+        return SEVERITY_BY_NAME.get(self.severity, Severity.ERROR)
+
+
+class ValeReport(pydantic.RootModel[dict[str, list[ValeAlert]]]):
+    @classmethod
+    def parse(cls, payload: str) -> tuple[ValeAlert, ...]:
+        try:
+            report = cls.model_validate_json(payload or '{}')
+        except pydantic.ValidationError:
+            return ()
+        return tuple(alert for alerts in report.root.values() for alert in alerts)
+
+
+class ValeLinter(ExternalLinter):
+    name = 'vale'
+
+    def __init__(self, executable: str = 'vale') -> None:
+        self._executable = executable
+
+    def is_available(self) -> bool:
+        return shutil.which(self._executable) is not None
+
+    def run(self, document: Document) -> tuple[Diagnostic, ...]:
+        source_path = pathlib.Path(document.uri.removeprefix('file://'))
+        if not self.is_available() or not source_path.is_file():
+            return ()
+        try:
+            process = subprocess.run(  # noqa: S603
+                [self._executable, '--no-exit', '--output=JSON', str(source_path)],
+                capture_output=True,
+                text=True,
+                check=False,
+                timeout=TIMEOUT_SECONDS,
+            )
+        except (OSError, subprocess.TimeoutExpired):
+            return ()
+        return self._decode(document, process.stdout)
+
+    def _decode(self, document: Document, payload: str) -> tuple[Diagnostic, ...]:
+        diagnostics: list[Diagnostic] = []
+        for alert in ValeReport.parse(payload):
+            diagnostic = self._to_diagnostic(document, alert)
+            if diagnostic is not None:
+                diagnostics.append(diagnostic)
+        return tuple(diagnostics)
+
+    def _to_diagnostic(self, document: Document, alert: ValeAlert) -> Diagnostic | None:
+        start_column, end_column = alert.span
+        try:
+            start_offset = document.positions.to_offset(Position(alert.line - 1, start_column - 1))
+            end_offset = document.positions.to_offset(Position(alert.line - 1, end_column))
+        except ValueError:
+            return None
+        return Diagnostic(
+            rule_id=alert.check,
+            range=SourceRange(start_offset, max(start_offset, end_offset)),
+            message=alert.message,
+            severity=alert.resolved_severity,
+            fix=Fix.rewrite(),
+            source=self.name,
+        )

subedit/infrastructure/parsers/__init__.py

@@ -0,0 +1,12 @@
+from .languages import PYTHON, GrammarAdapter, LanguageProfile, NodeRole, PythonProfile
+from .tree_sitter_parser import TreeSitterParser
+
+
+__all__ = [
+    'PYTHON',
+    'GrammarAdapter',
+    'LanguageProfile',
+    'NodeRole',
+    'PythonProfile',
+    'TreeSitterParser',
+]

subedit/infrastructure/parsers/languages/__init__.py

@@ -0,0 +1,11 @@
+from .language_profile import GrammarAdapter, LanguageProfile, NodeRole
+from .python_profile import PYTHON, PythonProfile
+
+
+__all__ = [
+    'PYTHON',
+    'GrammarAdapter',
+    'LanguageProfile',
+    'NodeRole',
+    'PythonProfile',
+]

subedit/infrastructure/parsers/languages/language_profile.py

@@ -0,0 +1,26 @@
+import abc
+import enum
+
+from ....domain.models.comment import SymbolKind
+from ....domain.ports.language_conventions import LanguageConventions
+
+
+class NodeRole(enum.Enum):
+    ROOT = 'root'
+    DEFINITION = 'definition'
+    COMMENT = 'comment'
+    OTHER = 'other'
+
+
+class GrammarAdapter(abc.ABC):
+    @abc.abstractmethod
+    def query(self) -> str: ...
+
+    @abc.abstractmethod
+    def role_of(self, node_type: str) -> NodeRole: ...
+
+    @abc.abstractmethod
+    def symbol_kind(self, node_type: str) -> SymbolKind: ...
+
+
+class LanguageProfile(LanguageConventions, GrammarAdapter): ...

subedit/infrastructure/parsers/languages/python_profile.py

@@ -0,0 +1,71 @@
+import re
+
+from ....domain.models.comment import CommentForm, SymbolKind, Visibility
+from ....domain.ports.language_conventions import DelimiterSplit
+from .language_profile import LanguageProfile, NodeRole
+
+
+_DOC_DELIMITER = re.compile(r'^([rRbBuUfF]{0,2})("""|\'\'\')')
+_HASH_DELIMITER = re.compile(r'^(#+\s?)')
+
+QUERY = """
+(comment) @comment
+(module . (string) @doc)
+(function_definition body: (block . (string) @doc))
+(class_definition body: (block . (string) @doc))
+"""
+
+
+class PythonProfile(LanguageProfile):
+    language_id = 'python'
+    extensions = frozenset({'.py', '.pyi'})
+    doc_delimiter = '"""'
+    signature_tags = ('Args:', 'Returns:', 'Raises:', 'Yields:', ':param', ':return', ':rtype')
+    _ROLES = {
+        'module': NodeRole.ROOT,
+        'comment': NodeRole.COMMENT,
+        'function_definition': NodeRole.DEFINITION,
+        'class_definition': NodeRole.DEFINITION,
+        'decorated_definition': NodeRole.DEFINITION,
+    }
+
+    def query(self) -> str:
+        return QUERY
+
+    def role_of(self, node_type: str) -> NodeRole:
+        return self._ROLES.get(node_type, NodeRole.OTHER)
+
+    def symbol_kind(self, node_type: str) -> SymbolKind:
+        return SymbolKind.CLASS if node_type == 'class_definition' else SymbolKind.FUNCTION
+
+    def visibility_of(self, name: str) -> Visibility:
+        return Visibility.INTERNAL if name.startswith('_') else Visibility.PUBLIC
+
+    def split_delimiter(self, line: str, form: CommentForm) -> DelimiterSplit:
+        indent = line[: len(line) - len(line.lstrip())]
+        rest = line[len(indent) :]
+        if form is CommentForm.DOC:
+            delimiter, text, suffix = self._split_doc(rest)
+            return DelimiterSplit(indent=indent, delimiter=delimiter, text=text, suffix=suffix)
+        hash_delimiter = _HASH_DELIMITER.match(rest)
+        if hash_delimiter is None:
+            return DelimiterSplit(indent=indent, delimiter='', text=rest.rstrip())
+        return DelimiterSplit(
+            indent=indent, delimiter=hash_delimiter.group(1), text=rest[hash_delimiter.end() :].rstrip()
+        )
+
+    def _split_doc(self, rest: str) -> tuple[str, str, str]:
+        opening = _DOC_DELIMITER.match(rest)
+        delimiter = opening.group(0) if opening else ''
+        body = rest[len(delimiter) :]
+        delimiter = opening.group(2) if opening else ''
+        suffix = ''
+        for candidate in (delimiter, '"""', "'''"):
+            if candidate and body.endswith(candidate):
+                suffix = candidate
+                body = body[: -len(candidate)]
+                break
+        return delimiter, body.rstrip(), suffix
+
+
+PYTHON = PythonProfile()