subedit 0.1.0__py3-none-any.whl

subedit/__init__.py

@@ -0,0 +1,3 @@
+__version__ = '0.1.0'
+
+__all__ = ['__version__']

subedit/application/__init__.py

@@ -0,0 +1,16 @@
+from .corpus_meter import CorpusMeter, CorpusStatistics, Distribution
+from .fixer import Fixer, FixResult
+from .linter import Linter, RuleEngine
+from .report_aggregator import ReportAggregator
+
+
+__all__ = [
+    'CorpusMeter',
+    'CorpusStatistics',
+    'Distribution',
+    'FixResult',
+    'Fixer',
+    'Linter',
+    'ReportAggregator',
+    'RuleEngine',
+]

subedit/application/corpus_meter.py

@@ -0,0 +1,87 @@
+import dataclasses
+import statistics
+
+from ..domain.models.comment import CommentForm, CommentGroup, CommentPlacement, Visibility
+from ..domain.models.document import Document
+from ..domain.ports import SourceParser
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Distribution:
+    label: str
+    measurements: tuple[int, ...]
+
+    @property
+    def count(self) -> int:
+        return len(self.measurements)
+
+    def percentile(self, fraction: float) -> int:
+        if not self.measurements:
+            return 0
+        sorted_values = sorted(self.measurements)
+        position = min(len(sorted_values) - 1, max(0, round(fraction * (len(sorted_values) - 1))))
+        return sorted_values[position]
+
+    @property
+    def maximum(self) -> int:
+        return max(self.measurements, default=0)
+
+    @property
+    def median(self) -> int:
+        return round(statistics.median(self.measurements)) if self.measurements else 0
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class CorpusStatistics:
+    document_count: int
+    group_count: int
+    line_counts: tuple[Distribution, ...]
+    physical_widths: Distribution
+    sentence_lengths: Distribution
+    unbreakable_counts_by_width: tuple[tuple[int, int], ...]
+
+
+class CorpusMeter:
+    def __init__(self, parser: SourceParser, candidate_widths: tuple[int, ...] = (72, 80, 88, 100, 120)) -> None:
+        self._parser = parser
+        self._candidate_widths = candidate_widths
+
+    def run(self, documents: tuple[Document, ...]) -> CorpusStatistics:
+        grouped_line_counts: dict[str, list[int]] = {}
+        physical_widths: list[int] = []
+        sentence_lengths: list[int] = []
+        unbreakable_counts = dict.fromkeys(self._candidate_widths, 0)
+        group_count = 0
+
+        for document in documents:
+            for group in self._parser.parse(document):
+                group_count += 1
+                grouped_line_counts.setdefault(self._label_for(group), []).append(group.line_count)
+                physical_widths.extend(line.physical_width for line in group.lines)
+                for sentence in group.prose().sentences():
+                    sentence_lengths.append(len(sentence.text))
+                    for width in self._candidate_widths:
+                        if self._is_unbreakable(sentence.text, width):
+                            unbreakable_counts[width] += 1
+
+        return CorpusStatistics(
+            document_count=len(documents),
+            group_count=group_count,
+            line_counts=tuple(
+                Distribution(label, tuple(measurements)) for label, measurements in sorted(grouped_line_counts.items())
+            ),
+            physical_widths=Distribution('physical-width', tuple(physical_widths)),
+            sentence_lengths=Distribution('sentence-length', tuple(sentence_lengths)),
+            unbreakable_counts_by_width=tuple(sorted(unbreakable_counts.items())),
+        )
+
+    def _label_for(self, group: CommentGroup) -> str:
+        if group.form is CommentForm.DOC:
+            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}'
+
+    def _is_unbreakable(self, sentence: str, width: int) -> bool:
+        return len(sentence) > width and ',' not in sentence

subedit/application/fixer.py

@@ -0,0 +1,68 @@
+import dataclasses
+
+from ..domain.models.diagnostic import Diagnostic, FixKind, Report
+from ..domain.models.document import Document
+from ..domain.models.rule_set import RuleSet
+from ..domain.models.text import TextEdit, apply_edits
+from .linter import Linter
+
+
+MAX_ROUNDS = 10
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class FixResult:
+    document: Document
+    report: Report
+    round_count: int
+    applied_edit_count: int
+
+    @property
+    def has_changes(self) -> bool:
+        return self.applied_edit_count > 0
+
+    @property
+    def unresolved_findings(self) -> tuple[Diagnostic, ...]:
+        return self.report.needing_author
+
+
+class Fixer:
+    def __init__(self, linter: Linter, max_rounds: int = MAX_ROUNDS) -> None:
+        self._linter = linter
+        self._max_rounds = max_rounds
+
+    def run(self, document: Document, rule_set: RuleSet) -> FixResult:
+        working_document = document
+        applied_edit_count = 0
+        round_count = 0
+        report = self._linter.run(working_document, rule_set)
+
+        while round_count < self._max_rounds:
+            edits = self._next_edits(report)
+            if not edits:
+                break
+            working_document = working_document.with_text(apply_edits(working_document.text, edits))
+            applied_edit_count += len(edits)
+            round_count += 1
+            report = self._linter.run(working_document, rule_set)
+
+        return FixResult(
+            document=working_document, report=report, round_count=round_count, applied_edit_count=applied_edit_count
+        )
+
+    def _next_edits(self, report: Report) -> tuple[TextEdit, ...]:
+        for mechanical_kind in (FixKind.TARGETED, FixKind.REFLOW):
+            edits = self._without_overlaps(report.by_fix_kind(mechanical_kind))
+            if edits:
+                return edits
+        return ()
+
+    def _without_overlaps(self, diagnostics: tuple[Diagnostic, ...]) -> tuple[TextEdit, ...]:
+        candidate_edits = [edit for diagnostic in diagnostics if diagnostic.fix for edit in diagnostic.fix.edits]
+        candidate_edits.sort(key=lambda edit: (edit.range.start, edit.range.end))
+        accepted_edits: list[TextEdit] = []
+        for edit in candidate_edits:
+            if accepted_edits and accepted_edits[-1].range.overlaps(edit.range):
+                continue
+            accepted_edits.append(edit)
+        return tuple(accepted_edits)

subedit/application/linter.py

@@ -0,0 +1,55 @@
+import dataclasses
+
+from ..domain.models.comment import CommentGroup
+from ..domain.models.diagnostic import Diagnostic, Report
+from ..domain.models.document import Document
+from ..domain.models.rule_set import RuleSet
+from ..domain.ports import SourceParser
+from ..domain.ports.rule import Rule, RuleContext
+
+
+class RuleEngine:
+    def __init__(self, rules: tuple[Rule, ...]) -> None:
+        duplicate_ids = self._find_duplicate_ids(rules)
+        if duplicate_ids:
+            raise ValueError(f'Duplicate rule ids registered: {sorted(duplicate_ids)}')
+        self._rules = rules
+
+    def run(self, document: Document, groups: tuple[CommentGroup, ...], rule_set: RuleSet) -> tuple[Diagnostic, ...]:
+        context = RuleContext(document=document, rule_set=rule_set)
+        enabled_rules = [rule for rule in self._rules if rule_set.is_enabled(rule.metadata.rule_id)]
+        diagnostics: list[Diagnostic] = []
+        for group in groups:
+            for rule in enabled_rules:
+                for diagnostic in rule.check(group, context):
+                    diagnostics.append(self._with_severity(diagnostic, rule, rule_set))
+        return tuple(diagnostics)
+
+    def _with_severity(self, diagnostic: Diagnostic, rule: Rule, rule_set: RuleSet) -> Diagnostic:
+        severity = rule_set.severity_for(rule.metadata)
+        if diagnostic.severity is severity:
+            return diagnostic
+        return dataclasses.replace(diagnostic, severity=severity)
+
+    def _find_duplicate_ids(self, rules: tuple[Rule, ...]) -> set[str]:
+        seen_ids: set[str] = set()
+        duplicate_ids: set[str] = set()
+        for rule in rules:
+            if rule.metadata.rule_id in seen_ids:
+                duplicate_ids.add(rule.metadata.rule_id)
+            seen_ids.add(rule.metadata.rule_id)
+        return duplicate_ids
+
+
+class Linter:
+    def __init__(self, parser: SourceParser, engine: RuleEngine) -> None:
+        self._parser = parser
+        self._engine = engine
+
+    def run(self, document: Document, rule_set: RuleSet) -> Report:
+        if not self._parser.supports(document.language_id):
+            return Report()
+        groups = self._parser.parse(document)
+        diagnostics = self._engine.run(document, groups, rule_set)
+        sorted_diagnostics = sorted(diagnostics, key=lambda item: (item.range.start, item.rule_id))
+        return Report(tuple(sorted_diagnostics))

subedit/application/report_aggregator.py

@@ -0,0 +1,23 @@
+from ..domain.models.diagnostic import Report
+from ..domain.models.document import Document
+from ..domain.models.rule_set import RuleSet
+from ..domain.ports.external_linter import ExternalLinter
+from .linter import Linter
+
+
+class ReportAggregator:
+    def __init__(self, linter: Linter, linters: tuple[ExternalLinter, ...] = ()) -> None:
+        self._linter = linter
+        self._linters = linters
+
+    def run(self, document: Document, rule_set: RuleSet) -> Report:
+        report = self._linter.run(document, rule_set)
+        missing_sources: list[str] = []
+        for linter in self._linters:
+            if not linter.is_available():
+                missing_sources.append(linter.name)
+                continue
+            report = report.merged_with(Report(linter.run(document)))
+        if missing_sources:
+            report = report.merged_with(Report(unavailable_sources=tuple(missing_sources)))
+        return report

subedit/domain/__init__.py

@@ -0,0 +1,63 @@
+from .models import (
+    SEVERITY_BY_NAME,
+    CommentForm,
+    CommentGroup,
+    CommentLine,
+    CommentPlacement,
+    Diagnostic,
+    Document,
+    Encoding,
+    Fix,
+    FixKind,
+    Position,
+    PositionMap,
+    Prose,
+    Report,
+    RuleMetadata,
+    RuleSet,
+    RuleSettings,
+    Sentence,
+    Severity,
+    SourceRange,
+    SymbolKind,
+    SymbolRef,
+    TextEdit,
+    Visibility,
+    apply_edits,
+)
+from .ports import DelimiterSplit, ExternalLinter, LanguageConventions, Rule, RuleContext, SourceParser
+
+
+__all__ = [
+    'SEVERITY_BY_NAME',
+    'CommentForm',
+    'CommentGroup',
+    'CommentLine',
+    'CommentPlacement',
+    'DelimiterSplit',
+    'Diagnostic',
+    'Document',
+    'Encoding',
+    'ExternalLinter',
+    'Fix',
+    'FixKind',
+    'LanguageConventions',
+    'Position',
+    'PositionMap',
+    'Prose',
+    'Report',
+    'Rule',
+    'RuleContext',
+    'RuleMetadata',
+    'RuleSet',
+    'RuleSettings',
+    'Sentence',
+    'Severity',
+    'SourceParser',
+    'SourceRange',
+    'SymbolKind',
+    'SymbolRef',
+    'TextEdit',
+    'Visibility',
+    'apply_edits',
+]

subedit/domain/models/__init__.py

@@ -0,0 +1,36 @@
+from .comment import CommentForm, CommentGroup, CommentLine, CommentPlacement, SymbolKind, SymbolRef, Visibility
+from .diagnostic import SEVERITY_BY_NAME, Diagnostic, Fix, FixKind, Report, RuleMetadata, Severity
+from .document import Document
+from .position import Encoding, Position, PositionMap, SourceRange
+from .prose import Prose, Sentence
+from .rule_set import RuleSet, RuleSettings
+from .text import TextEdit, apply_edits
+
+
+__all__ = [
+    'SEVERITY_BY_NAME',
+    'CommentForm',
+    'CommentGroup',
+    'CommentLine',
+    'CommentPlacement',
+    'Diagnostic',
+    'Document',
+    'Encoding',
+    'Fix',
+    'FixKind',
+    'Position',
+    'PositionMap',
+    'Prose',
+    'Report',
+    'RuleMetadata',
+    'RuleSet',
+    'RuleSettings',
+    'Sentence',
+    'Severity',
+    'SourceRange',
+    'SymbolKind',
+    'SymbolRef',
+    'TextEdit',
+    'Visibility',
+    'apply_edits',
+]

subedit/domain/models/comment.py

@@ -0,0 +1,168 @@
+import dataclasses
+import enum
+
+from .position import SourceRange
+from .prose import Prose, reflow_sentence
+from .text import TextEdit
+
+
+class CommentForm(enum.Enum):
+    LINE = 'line'
+    BLOCK = 'block'
+    DOC = 'doc'
+
+
+class CommentPlacement(enum.Enum):
+    FILE_HEADER = 'file-header'
+    LEADING_DECLARATION = 'leading-declaration'
+    INLINE_BODY = 'inline-body'
+    TRAILING = 'trailing'
+
+
+class Visibility(enum.Enum):
+    PUBLIC = 'public'
+    INTERNAL = 'internal'
+
+
+class SymbolKind(enum.Enum):
+    MODULE = 'module'
+    CLASS = 'class'
+    FUNCTION = 'function'
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class SymbolRef:
+    name: str
+    kind: SymbolKind
+    visibility: Visibility
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class CommentLine:
+    range: SourceRange
+    indent: str
+    delimiter: str
+    text: str
+    suffix: str = ''
+
+    @property
+    def physical_width(self) -> int:
+        return len(self.indent) + len(self.delimiter) + len(self.text) + len(self.suffix)
+
+    @property
+    def prefix_width(self) -> int:
+        return len(self.indent) + len(self.delimiter)
+
+    def render(self) -> str:
+        if not self.text and not self.suffix:
+            return (self.indent + self.delimiter).rstrip()
+        return self.indent + self.delimiter + self.text + self.suffix
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class CommentGroup:
+    range: SourceRange
+    lines: tuple[CommentLine, ...]
+    form: CommentForm
+    placement: CommentPlacement
+    attachment: SymbolRef | None = None
+
+    def __post_init__(self) -> None:
+        if not self.lines:
+            raise ValueError('A comment group needs at least one line')
+        if self.attachment is not None and self.placement is not CommentPlacement.LEADING_DECLARATION:
+            raise ValueError(
+                f'Only a leading declaration comment documents a symbol, '
+                f'but a {self.placement.value} comment carries {self.attachment.name!r}'
+            )
+
+    @property
+    def line_count(self) -> int:
+        return len(self.lines)
+
+    @property
+    def longest_line(self) -> int:
+        return max(line.physical_width for line in self.lines)
+
+    @property
+    def attaches_to_public_symbol(self) -> bool:
+        return self.attachment is not None and self.attachment.visibility is Visibility.PUBLIC
+
+    def prose(self) -> Prose:
+        filled_lines = [line for line in self.lines if line.text.strip()]
+        base = min((len(line.indent) for line in filled_lines), default=0)
+        rendered_lines = [
+            ' ' * max(0, len(line.indent) - base) + line.text.rstrip() if line.text.strip() else ''
+            for line in self.lines
+        ]
+        return Prose('\n'.join(rendered_lines))
+
+    def reflow(self, width: int) -> 'CommentGroup':
+        texts = self._reflow_into_texts(width)
+        if not texts:
+            return self
+        return self._rebuild_lines(texts)
+
+    def _reflow_into_texts(self, width: int) -> tuple[str, ...]:
+        budget = max(20, width - self.lines[0].prefix_width)
+        out: list[str] = []
+        for paragraph, is_literal in 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))
+        return tuple(out)
+
+    def _split_into_paragraphs(self) -> tuple[tuple[tuple[str, ...], bool], ...]:
+        paragraphs: list[tuple[tuple[str, ...], bool]] = []
+        for segment in self.prose().segments():
+            current_lines: list[str] = []
+            for line in segment.lines:
+                if line.strip():
+                    current_lines.append(line)
+                elif current_lines:
+                    paragraphs.append((tuple(current_lines), segment.is_literal))
+                    current_lines = []
+            if current_lines:
+                paragraphs.append((tuple(current_lines), segment.is_literal))
+        return tuple(paragraphs)
+
+    def _rebuild_lines(self, texts: tuple[str, ...]) -> 'CommentGroup':
+        if self.form is not CommentForm.DOC:
+            return self.with_texts(texts)
+        opening, closing = self.lines[0], self.lines[-1]
+        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:
+            body.append(
+                dataclasses.replace(closing, delimiter=closing.delimiter or opening.delimiter, text='', suffix='')
+            )
+            if not closes_alone:
+                body[-1] = dataclasses.replace(body[-1], delimiter=opening.delimiter.strip())
+        else:
+            body[0] = dataclasses.replace(body[0], suffix=closing.suffix or opening.delimiter.strip())
+        return dataclasses.replace(self, lines=tuple(body))
+
+    def with_texts(self, texts: tuple[str, ...]) -> 'CommentGroup':
+        if not texts:
+            raise ValueError('A comment block needs at least one line')
+        template = self.lines[0]
+        rebuilt = tuple(
+            dataclasses.replace(
+                self.lines[index] if index < len(self.lines) else template,
+                text=text,
+            )
+            for index, text in enumerate(texts)
+        )
+        return dataclasses.replace(self, lines=rebuilt)
+
+    def render(self) -> str:
+        return '\n'.join(line.render() for line in self.lines)
+
+    def as_edit(self) -> TextEdit:
+        return TextEdit(self.range, self.render())

subedit/domain/models/diagnostic.py

@@ -0,0 +1,123 @@
+import dataclasses
+import enum
+
+from .position import SourceRange
+from .text import TextEdit
+
+
+class Severity(enum.IntEnum):
+    SUGGESTION = 1
+    WARNING = 2
+    ERROR = 3
+
+
+SEVERITY_BY_NAME = {severity.name.lower(): severity for severity in Severity}
+
+
+class FixKind(enum.Enum):
+    TARGETED = 'targeted'
+    REFLOW = 'reflow'
+    REWRITE = 'rewrite'
+
+    @property
+    def is_mechanical(self) -> bool:
+        return self is not FixKind.REWRITE
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Fix:
+    kind: FixKind
+    edits: tuple[TextEdit, ...] = ()
+
+    def __post_init__(self) -> None:
+        if self.kind is FixKind.REWRITE and self.edits:
+            raise ValueError('A REWRITE fix carries no edits, only the author can resolve it')
+        if self.kind.is_mechanical and not self.edits:
+            raise ValueError(f'A {self.kind.name} fix must carry at least one edit')
+
+    @classmethod
+    def targeted(cls, *edits: TextEdit) -> 'Fix':
+        return cls(FixKind.TARGETED, edits)
+
+    @classmethod
+    def reflow(cls, *edits: TextEdit) -> 'Fix':
+        return cls(FixKind.REFLOW, edits)
+
+    @classmethod
+    def rewrite(cls) -> 'Fix':
+        return cls(FixKind.REWRITE)
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class RuleMetadata:
+    rule_id: str
+    summary: str
+    fix_kind: FixKind
+    default_severity: Severity = Severity.ERROR
+    source: str = 'subedit'
+
+    def __post_init__(self) -> None:
+        if not self.rule_id:
+            raise ValueError('A rule needs an id')
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Diagnostic:
+    rule_id: str
+    range: SourceRange
+    message: str
+    severity: Severity = Severity.ERROR
+    fix: Fix | None = None
+    source: str = 'subedit'
+
+    def __post_init__(self) -> None:
+        if not self.message:
+            raise ValueError(f'Rule {self.rule_id} produced an empty message')
+
+    @property
+    def is_mechanical(self) -> bool:
+        return self.fix is not None and self.fix.kind.is_mechanical
+
+    @property
+    def needs_author(self) -> bool:
+        return not self.is_mechanical
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Report:
+    diagnostics: tuple[Diagnostic, ...] = ()
+    unavailable_sources: tuple[str, ...] = ()
+
+    @property
+    def mechanical(self) -> tuple[Diagnostic, ...]:
+        return tuple(diagnostic for diagnostic in self.diagnostics if diagnostic.is_mechanical)
+
+    @property
+    def needing_author(self) -> tuple[Diagnostic, ...]:
+        return tuple(diagnostic for diagnostic in self.diagnostics if diagnostic.needs_author)
+
+    @property
+    def is_clean(self) -> bool:
+        return not self.diagnostics
+
+    def by_fix_kind(self, wanted: FixKind) -> tuple[Diagnostic, ...]:
+        return tuple(
+            diagnostic
+            for diagnostic in self.diagnostics
+            if diagnostic.fix is not None and diagnostic.fix.kind is wanted
+        )
+
+    def merged_with(self, other: 'Report') -> 'Report':
+        seen_keys: set[tuple[str, int, int]] = set()
+        merged_diagnostics: list[Diagnostic] = []
+        for diagnostic in (*self.diagnostics, *other.diagnostics):
+            key = (diagnostic.rule_id, diagnostic.range.start, diagnostic.range.end)
+            if key in seen_keys:
+                continue
+            seen_keys.add(key)
+            merged_diagnostics.append(diagnostic)
+        merged_diagnostics.sort(key=lambda diagnostic: (diagnostic.range.start, diagnostic.rule_id))
+        return Report(
+            tuple(merged_diagnostics),
+            tuple(dict.fromkeys((*self.unavailable_sources, *other.unavailable_sources))),
+        )

subedit/domain/models/document.py

@@ -0,0 +1,23 @@
+import dataclasses
+import functools
+
+from .position import PositionMap
+
+
+@dataclasses.dataclass(frozen=True)
+class Document:
+    uri: str
+    text: str
+    language_id: str
+    version: int = 0
+
+    @functools.cached_property
+    def positions(self) -> PositionMap:
+        return PositionMap(self.text)
+
+    def with_text(self, text: str, version: int | None = None) -> 'Document':
+        return dataclasses.replace(
+            self,
+            text=text,
+            version=self.version + 1 if version is None else version,
+        )