subedit 0.1.0__py3-none-any.whl

subedit/domain/models/position.py

@@ -0,0 +1,108 @@
+import bisect
+import dataclasses
+import enum
+
+
+class Encoding(enum.Enum):
+    UTF8 = 'utf-8'
+    UTF16 = 'utf-16'
+    UTF32 = 'utf-32'
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Position:
+    line: int
+    character: int
+
+    def __post_init__(self) -> None:
+        if self.line < 0 or self.character < 0:
+            raise ValueError(f'Position must be non negative, got line {self.line} character {self.character}')
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class SourceRange:
+    start: int
+    end: int
+
+    def __post_init__(self) -> None:
+        if self.start < 0:
+            raise ValueError(f'Range start must be non negative, got {self.start}')
+        if self.end < self.start:
+            raise ValueError(f'Range end {self.end} precedes start {self.start}')
+
+    @property
+    def length(self) -> int:
+        return self.end - self.start
+
+    @property
+    def is_empty(self) -> bool:
+        return self.start == self.end
+
+    def overlaps(self, other: 'SourceRange') -> bool:
+        return self.start < other.end and other.start < self.end
+
+    def contains(self, other: 'SourceRange') -> bool:
+        return self.start <= other.start and other.end <= self.end
+
+
+class PositionMap:
+    def __init__(self, text: str) -> None:
+        self._text = text
+        self._encoded_text = text.encode('utf-8')
+        starts = [0]
+        for index, byte in enumerate(self._encoded_text):
+            if byte == 0x0A:
+                starts.append(index + 1)
+        self._line_starts = starts
+
+    @property
+    def line_count(self) -> int:
+        return len(self._line_starts)
+
+    def line_range(self, line: int) -> SourceRange:
+        self._require_line(line)
+        start = self._line_starts[line]
+        if line + 1 < len(self._line_starts):
+            end = self._line_starts[line + 1] - 1
+            if end > start and self._encoded_text[end - 1] == 0x0D:
+                end -= 1
+        else:
+            end = len(self._encoded_text)
+        return SourceRange(start, end)
+
+    def line_text(self, line: int) -> str:
+        span = self.line_range(line)
+        return self._encoded_text[span.start : span.end].decode('utf-8')
+
+    def to_position(self, offset: int, encoding: Encoding = Encoding.UTF16) -> Position:
+        self._require_offset(offset)
+        line = bisect.bisect_right(self._line_starts, offset) - 1
+        span = self.line_range(line)
+        prefix = self._encoded_text[span.start : min(offset, span.end)].decode('utf-8')
+        return Position(line, self._measure(prefix, encoding))
+
+    def to_offset(self, position: Position, encoding: Encoding = Encoding.UTF16) -> int:
+        self._require_line(position.line)
+        span = self.line_range(position.line)
+        text = self._encoded_text[span.start : span.end].decode('utf-8')
+        consumed = 0
+        for index, character in enumerate(text):
+            if consumed >= position.character:
+                return span.start + len(text[:index].encode('utf-8'))
+            consumed += self._measure(character, encoding)
+        return span.end
+
+    def _measure(self, text: str, encoding: Encoding) -> int:
+        if encoding is Encoding.UTF8:
+            return len(text.encode('utf-8'))
+        if encoding is Encoding.UTF32:
+            return len(text)
+        return sum(2 if character > '￿' else 1 for character in text)
+
+    def _require_line(self, line: int) -> None:
+        if not 0 <= line < len(self._line_starts):
+            raise ValueError(f'Line {line} out of range, document has {len(self._line_starts)} lines')
+
+    def _require_offset(self, offset: int) -> None:
+        if not 0 <= offset <= len(self._encoded_text):
+            raise ValueError(f'Offset {offset} out of range, document has {len(self._encoded_text)} bytes')

subedit/domain/models/prose.py

@@ -0,0 +1,215 @@
+import dataclasses
+import re
+
+
+# Abbreviations whose period does not end a sentence, written without that period.
+ABBREVIATIONS = frozenset(
+    {
+        'e.g',
+        'i.e',
+        'etc',
+        'vs',
+        'cf',
+        'al',
+        'approx',
+        'fig',
+        'ca',
+        'resp',
+    }
+)
+
+_SENTENCE_END = re.compile(r'[.!?]')
+_TRAILING_WORD = re.compile(r'([A-Za-z][A-Za-z.]*)$')
+_URL = re.compile(r'\b(?:https?://|www\.)\S+')
+_CODE_SPAN = re.compile(r'`[^`]*`')
+_FENCE = re.compile(r'^\s*(```|~~~)')
+_LIST_DELIMITER = re.compile(r'^\s*(?:[0-9]+[.)]|[-*+]|[a-zA-Z][.)])\s')
+_LITERAL_DELIMITER = '\\b'
+_CLOSING_MARKS = '"\')]}'
+
+# Only before a number, since "No. 5" abbreviates while a trailing no ends its sentence.
+NUMBER_ABBREVIATION = 'no'
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Sentence:
+    text: str
+    offset: int
+
+    @property
+    def end(self) -> int:
+        return self.offset + len(self.text)
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Segment:
+    lines: tuple[str, ...]
+    is_literal: bool
+
+    @property
+    def text(self) -> str:
+        return '\n'.join(self.lines)
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Prose:
+    text: str
+
+    @property
+    def physical_lines(self) -> tuple[str, ...]:
+        return tuple(self.text.split('\n'))
+
+    def segments(self) -> tuple[Segment, ...]:
+        segments: list[Segment] = []
+        current_lines: list[str] = []
+        segment_is_literal = False
+        inside_fence = False
+        inside_literal_marker = False
+        inside_list = False
+
+        def flush(next_is_literal: bool) -> None:
+            nonlocal current_lines, segment_is_literal
+            if current_lines and next_is_literal != segment_is_literal:
+                segments.append(Segment(tuple(current_lines), segment_is_literal))
+                current_lines = []
+            segment_is_literal = next_is_literal
+
+        for line in self.physical_lines:
+            stripped_line = line.strip()
+            if _FENCE.match(line):
+                inside_fence = not inside_fence
+                flush(next_is_literal=True)
+                current_lines.append(line)
+                continue
+            if stripped_line.startswith(_LITERAL_DELIMITER):
+                inside_literal_marker = stripped_line == _LITERAL_DELIMITER
+                flush(next_is_literal=True)
+                current_lines.append(line)
+                continue
+            if not stripped_line:
+                inside_literal_marker = False
+                inside_list = False
+                flush(next_is_literal=inside_fence)
+                current_lines.append(line)
+                continue
+            if self._is_list_item(line):
+                inside_list = True
+            elif not self._continues_list_item(line, inside_list):
+                inside_list = False
+            flush(next_is_literal=inside_fence or inside_literal_marker or inside_list or self._is_indented(line))
+            current_lines.append(line)
+
+        if current_lines:
+            segments.append(Segment(tuple(current_lines), segment_is_literal))
+        return tuple(segments)
+
+    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,
+    # 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 _is_list_item(self, line: str) -> bool:
+        return bool(_LIST_DELIMITER.match(line))
+
+    @property
+    def flattened(self) -> str:
+        return ' '.join(
+            line.strip()
+            for segment in self.segments()
+            if not segment.is_literal
+            for line in segment.lines
+            if line.strip()
+        )
+
+    def sentences(self) -> tuple[Sentence, ...]:
+        text = self.flattened
+        if not text:
+            return ()
+        protected = self._find_protected_spans(text)
+        found_sentences: list[Sentence] = []
+        start = 0
+        for sentence_end in _SENTENCE_END.finditer(text):
+            end = sentence_end.end()
+            if end < len(text) and text[end] in _CLOSING_MARKS:
+                end += 1
+            if self._is_protected(sentence_end.start(), protected):
+                continue
+            if not self._terminates_a_sentence(text, sentence_end.start()):
+                continue
+            found_sentences.append(Sentence(text[start:end].strip(), start))
+            start = end
+            while start < len(text) and text[start] == ' ':
+                start += 1
+        if start < len(text):
+            found_sentences.append(Sentence(text[start:].strip(), start))
+        return tuple(sentence for sentence in found_sentences if sentence.text)
+
+    def _find_protected_spans(self, text: str) -> tuple[tuple[int, int], ...]:
+        spans = [(url.start(), url.end()) for url in _URL.finditer(text)]
+        spans.extend((code_span.start(), code_span.end()) for code_span in _CODE_SPAN.finditer(text))
+        return tuple(spans)
+
+    def _is_protected(self, offset: int, spans: tuple[tuple[int, int], ...]) -> bool:
+        return any(start <= offset < end for start, end in spans)
+
+    def _terminates_a_sentence(self, text: str, offset: int) -> bool:
+        if text[offset] != '.':
+            return self._followed_by_break(text, offset)
+        if offset + 1 < len(text) and text[offset + 1].isdigit():
+            return False
+        trailing_word = _TRAILING_WORD.search(text[:offset])
+        word = trailing_word.group(1).lower().rstrip('.') if trailing_word else ''
+        if word in ABBREVIATIONS:
+            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:
+            return False
+        return self._followed_by_break(text, offset)
+
+    def _followed_by_break(self, text: str, offset: int) -> bool:
+        rest = text[offset + 1 :]
+        if not rest:
+            return True
+        if rest[0] in _CLOSING_MARKS:
+            rest = rest[1:]
+        return not rest or rest[0] == ' '
+
+
+def reflow_sentence(sentence: str, width: int) -> tuple[str, ...]:
+    if len(sentence) <= width:
+        return (sentence,)
+    pieces = _comma_pieces(sentence)
+    if len(pieces) == 1:
+        return (sentence,)
+    return _pack(pieces, width)
+
+
+def _comma_pieces(sentence: str) -> tuple[str, ...]:
+    pieces: list[str] = []
+    start = 0
+    for comma in re.finditer(r',\s+', sentence):
+        pieces.append(sentence[start : comma.end()].rstrip())
+        start = comma.end()
+    tail = sentence[start:].strip()
+    if tail:
+        pieces.append(tail)
+    return tuple(pieces) if pieces else (sentence,)
+
+
+def _pack(pieces: tuple[str, ...], width: int) -> tuple[str, ...]:
+    lines: list[str] = []
+    current_line = ''
+    for piece in pieces:
+        candidate = f'{current_line} {piece}'.strip() if current_line else piece
+        if current_line and len(candidate) > width:
+            lines.append(current_line)
+            current_line = piece
+        else:
+            current_line = candidate
+    if current_line:
+        lines.append(current_line)
+    return tuple(lines)

subedit/domain/models/rule_set.py

@@ -0,0 +1,30 @@
+import dataclasses
+import typing
+
+from .diagnostic import RuleMetadata, Severity
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class RuleSettings:
+    severity: Severity | None = None
+    options: typing.Mapping[str, object] = dataclasses.field(default_factory=dict)
+
+    def integer(self, name: str, fallback: int) -> int:
+        option = self.options.get(name, fallback)
+        return option if isinstance(option, int) and not isinstance(option, bool) else fallback
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class RuleSet:
+    enabled_rule_ids: frozenset[str]
+    settings: typing.Mapping[str, RuleSettings] = dataclasses.field(default_factory=dict)
+    line_width: int = 120
+
+    def is_enabled(self, rule_id: str) -> bool:
+        return rule_id in self.enabled_rule_ids
+
+    def settings_for(self, rule_id: str) -> RuleSettings:
+        return self.settings.get(rule_id, RuleSettings())
+
+    def severity_for(self, metadata: RuleMetadata) -> Severity:
+        return self.settings_for(metadata.rule_id).severity or metadata.default_severity

subedit/domain/models/text.py

@@ -0,0 +1,23 @@
+import dataclasses
+import itertools
+
+from .position import SourceRange
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class TextEdit:
+    range: SourceRange
+    new_text: str
+
+
+def apply_edits(text: str, edits: tuple[TextEdit, ...]) -> str:
+    if not edits:
+        return text
+    sorted_edits = sorted(edits, key=lambda edit: (edit.range.start, edit.range.end))
+    for earlier_edit, later_edit in itertools.pairwise(sorted_edits):
+        if earlier_edit.range.overlaps(later_edit.range):
+            raise ValueError(f'Overlapping edits at bytes {earlier_edit.range.start} and {later_edit.range.start}')
+    buffer = bytearray(text.encode('utf-8'))
+    for edit in reversed(sorted_edits):
+        buffer[edit.range.start : edit.range.end] = edit.new_text.encode('utf-8')
+    return buffer.decode('utf-8')

subedit/domain/ports/__init__.py

@@ -0,0 +1,14 @@
+from .external_linter import ExternalLinter
+from .language_conventions import DelimiterSplit, LanguageConventions
+from .rule import Rule, RuleContext
+from .source_parser import SourceParser
+
+
+__all__ = [
+    'DelimiterSplit',
+    'ExternalLinter',
+    'LanguageConventions',
+    'Rule',
+    'RuleContext',
+    'SourceParser',
+]

subedit/domain/ports/external_linter.py

@@ -0,0 +1,14 @@
+import abc
+
+from ..models.diagnostic import Diagnostic
+from ..models.document import Document
+
+
+class ExternalLinter(abc.ABC):
+    name: str
+
+    @abc.abstractmethod
+    def is_available(self) -> bool: ...
+
+    @abc.abstractmethod
+    def run(self, document: Document) -> tuple[Diagnostic, ...]: ...

subedit/domain/ports/language_conventions.py

@@ -0,0 +1,25 @@
+import abc
+import dataclasses
+
+from ..models.comment import CommentForm, Visibility
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class DelimiterSplit:
+    indent: str
+    delimiter: str
+    text: str
+    suffix: str = ''
+
+
+class LanguageConventions(abc.ABC):
+    language_id: str
+    extensions: frozenset[str]
+    doc_delimiter: str
+    signature_tags: tuple[str, ...]
+
+    @abc.abstractmethod
+    def visibility_of(self, name: str) -> Visibility: ...
+
+    @abc.abstractmethod
+    def split_delimiter(self, line: str, form: CommentForm) -> DelimiterSplit: ...

subedit/domain/ports/rule.py

@@ -0,0 +1,28 @@
+import abc
+import dataclasses
+import typing
+
+from ..models.comment import CommentGroup
+from ..models.diagnostic import Diagnostic, RuleMetadata
+from ..models.document import Document
+from ..models.rule_set import RuleSet, RuleSettings
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class RuleContext:
+    document: Document
+    rule_set: RuleSet
+
+    @property
+    def line_width(self) -> int:
+        return self.rule_set.line_width
+
+    def settings(self, rule_id: str) -> RuleSettings:
+        return self.rule_set.settings_for(rule_id)
+
+
+class Rule(abc.ABC):
+    metadata: RuleMetadata
+
+    @abc.abstractmethod
+    def check(self, group: CommentGroup, context: RuleContext) -> typing.Iterable[Diagnostic]: ...

subedit/domain/ports/source_parser.py

@@ -0,0 +1,12 @@
+import abc
+
+from ..models.comment import CommentGroup
+from ..models.document import Document
+
+
+class SourceParser(abc.ABC):
+    @abc.abstractmethod
+    def supports(self, language_id: str) -> bool: ...
+
+    @abc.abstractmethod
+    def parse(self, document: Document) -> tuple[CommentGroup, ...]: ...

subedit/domain/rules/__init__.py

@@ -0,0 +1,15 @@
+from .layout import LineTooLongRule, MidClauseBreakRule
+from .rewrite import StubFragmentRule, UnbreakableSentenceRule
+from .structure import BlockTooLongRule, FileHeaderCommentRule, PlainCommentOnPublicRule, SignatureRestatingTagRule
+
+
+__all__ = [
+    'BlockTooLongRule',
+    'FileHeaderCommentRule',
+    'LineTooLongRule',
+    'MidClauseBreakRule',
+    'PlainCommentOnPublicRule',
+    'SignatureRestatingTagRule',
+    'StubFragmentRule',
+    'UnbreakableSentenceRule',
+]

subedit/domain/rules/layout.py

@@ -0,0 +1,57 @@
+import typing
+
+from ..models.comment import CommentGroup
+from ..models.diagnostic import Diagnostic, Fix, FixKind, RuleMetadata
+from ..ports.rule import Rule, RuleContext
+
+
+MID_CLAUSE_BREAK = RuleMetadata(
+    rule_id='mid-clause-break',
+    summary='A comment block must be laid out one sentence per line, splitting only at commas.',
+    fix_kind=FixKind.REFLOW,
+)
+
+LINE_TOO_LONG = RuleMetadata(
+    rule_id='line-too-long',
+    summary='A physical comment line must fit the configured width, counting indent and delimiter.',
+    fix_kind=FixKind.REFLOW,
+)
+
+
+class MidClauseBreakRule(Rule):
+    metadata = MID_CLAUSE_BREAK
+
+    def check(self, group: CommentGroup, context: RuleContext) -> typing.Iterable[Diagnostic]:
+        reflowed = group.reflow(context.line_width)
+        if reflowed.render() == group.render():
+            return
+        yield Diagnostic(
+            rule_id=self.metadata.rule_id,
+            range=group.range,
+            message=(
+                'Comment layout differs from one sentence per line. '
+                'Break only at a period or a comma, never mid clause.'
+            ),
+            fix=Fix.reflow(reflowed.as_edit()),
+        )
+
+
+class LineTooLongRule(Rule):
+    metadata = LINE_TOO_LONG
+
+    def check(self, group: CommentGroup, context: RuleContext) -> typing.Iterable[Diagnostic]:
+        width = context.line_width
+        if group.longest_line <= width:
+            return
+        reflowed = group.reflow(width)
+        if reflowed.longest_line > width:
+            return
+        yield Diagnostic(
+            rule_id=self.metadata.rule_id,
+            range=group.range,
+            message=(
+                f'A comment line runs to {group.longest_line} characters against a limit of {width}, '
+                'counting indent and delimiter.'
+            ),
+            fix=Fix.reflow(reflowed.as_edit()),
+        )

subedit/domain/rules/rewrite.py

@@ -0,0 +1,83 @@
+import typing
+
+from ..models.comment import CommentGroup
+from ..models.diagnostic import Diagnostic, Fix, FixKind, RuleMetadata
+from ..models.prose import Prose, reflow_sentence
+from ..ports.rule import Rule, RuleContext
+
+
+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,
+)
+
+UNBREAKABLE_SENTENCE = RuleMetadata(
+    rule_id='unbreakable-sentence',
+    summary='A sentence over the width must carry a comma so it has somewhere legal to break.',
+    fix_kind=FixKind.REWRITE,
+)
+
+
+DEFAULT_MINIMUM_CHARACTERS = 24
+
+
+def prose_sentences(group: CommentGroup) -> tuple[str, ...]:
+    return tuple(
+        sentence.text
+        for segment in group.prose().segments()
+        if not segment.is_literal
+        for sentence in Prose(segment.text).sentences()
+    )
+
+
+def sentence_budget(group: CommentGroup, context: RuleContext) -> int:
+    return max(20, context.line_width - group.lines[0].prefix_width)
+
+
+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
+        )
+        for sentence in prose_sentences(group):
+            split_pieces = reflow_sentence(sentence, budget)
+            if len(split_pieces) < 2:
+                continue
+            shortest_piece = min(split_pieces, key=len)
+            if len(shortest_piece) >= minimum_length:
+                continue
+            yield Diagnostic(
+                rule_id=self.metadata.rule_id,
+                range=group.range,
+                message=(
+                    f'Breaking this sentence leaves a line of {len(shortest_piece)} characters, below the minimum of '
+                    f'{minimum_length}, so the layout reads as a stub rather than a clause. '
+                    f'Rewrite it to fit one line, or split it into two complete sentences. '
+                    f'The fragment is "{shortest_piece.strip()}".'
+                ),
+                fix=Fix.rewrite(),
+            )
+
+
+class UnbreakableSentenceRule(Rule):
+    metadata = UNBREAKABLE_SENTENCE
+
+    def check(self, group: CommentGroup, context: RuleContext) -> typing.Iterable[Diagnostic]:
+        budget = max(20, context.line_width - group.lines[0].prefix_width)
+        for sentence in prose_sentences(group):
+            if len(sentence) <= budget or ',' in sentence:
+                continue
+            yield Diagnostic(
+                rule_id=self.metadata.rule_id,
+                range=group.range,
+                message=(
+                    f'This sentence runs to {len(sentence)} characters against a budget of {budget} characters '
+                    'and contains no comma, so there is no legal place to break it. '
+                    'Add a comma at a clause boundary, or split it into two sentences.'
+                ),
+                fix=Fix.rewrite(),
+            )