subedit 0.1.0__py3-none-any.whl

subedit/infrastructure/parsers/tree_sitter_parser.py

@@ -0,0 +1,219 @@
+from tree_sitter import Node, Query, QueryCursor
+from tree_sitter_language_pack import get_language, get_parser
+
+from ...domain.models.comment import CommentForm, CommentGroup, CommentLine, CommentPlacement, SymbolRef
+from ...domain.models.document import Document
+from ...domain.models.position import SourceRange
+from ...domain.ports.source_parser import SourceParser
+from .languages import LanguageProfile, NodeRole
+
+
+# Every profile must spell its captures this way, and the type system cannot check it.
+# A query that names them otherwise yields nothing, silently.
+COMMENT_CAPTURE = 'comment'
+DOC_CAPTURE = 'doc'
+
+
+class TreeSitterParser(SourceParser):
+    def __init__(self, profiles: tuple[LanguageProfile, ...]) -> None:
+        self._profiles = {profile.language_id: profile for profile in profiles}
+
+    def supports(self, language_id: str) -> bool:
+        return language_id in self._profiles
+
+    def parse(self, document: Document) -> tuple[CommentGroup, ...]:
+        """Turn source text into the comment groups the rules read.
+
+        1. Look up the profile. An unknown language yields nothing rather than raising.
+        2. Encode to bytes, because every offset this package stores is a byte offset.
+        3. Parse with tree-sitter and run the profile query over the tree.
+        4. Build one group per doc comment, since each already arrives as a single node.
+        5. Group adjacent line comments first,
+           because three consecutive hashes are three nodes sharing one sentence.
+        6. Sort by position, so a caller reading the result walks the file in order.
+        """
+        profile = self._profiles.get(document.language_id)
+        if profile is None:
+            return ()
+        source_bytes = document.text.encode('utf-8')
+        tree = get_parser(document.language_id).parse(source_bytes)  # pyright: ignore[reportArgumentType]
+        grouped_captures = self._run_query(profile, document.language_id, tree.root_node)
+        comment_groups = [self._build_doc_group(profile, document, node) for node in grouped_captures[DOC_CAPTURE]]
+        comment_groups.extend(
+            self._build_line_group(profile, document, group)
+            for group in self._group_adjacent_comments(profile, document, grouped_captures[COMMENT_CAPTURE])
+        )
+        return tuple(sorted(comment_groups, key=lambda group: group.range.start))
+
+    def _run_query(self, profile: LanguageProfile, language_id: str, root: Node) -> dict[str, list[Node]]:
+        query = Query(get_language(language_id), profile.query())  # pyright: ignore[reportArgumentType]
+        captures_by_name = QueryCursor(query).captures(root)
+        # A node can match several patterns at once, so the same byte offset arrives twice.
+        grouped_captures: dict[str, list[Node]] = {COMMENT_CAPTURE: [], DOC_CAPTURE: []}
+        for name, nodes in captures_by_name.items():
+            grouped_captures.setdefault(name, []).extend(nodes)
+        for name, nodes in grouped_captures.items():
+            seen_offsets: set[int] = set()
+            unique_nodes = [
+                node for node in nodes if not (node.start_byte in seen_offsets or seen_offsets.add(node.start_byte))
+            ]
+            grouped_captures[name] = sorted(unique_nodes, key=lambda node: node.start_byte)
+        return grouped_captures
+
+    def _group_adjacent_comments(
+        self, profile: LanguageProfile, document: Document, nodes: list[Node]
+    ) -> list[list[Node]]:
+        groups: list[list[Node]] = []
+        for node in nodes:
+            if groups and self._joins_previous_group(profile, document, groups[-1][-1], node):
+                groups[-1].append(node)
+            else:
+                groups.append([node])
+        return groups
+
+    # Same column, next line, and neither one trailing.
+    # A trailing comment describes the code to its left, so it never joins what sits below it.
+    def _joins_previous_group(self, profile: LanguageProfile, document: Document, previous: Node, node: Node) -> bool:
+        if previous.start_point[0] != node.start_point[0] - 1:
+            return False
+        if self._is_trailing_comment(document, previous) or self._is_trailing_comment(document, node):
+            return False
+        return previous.start_point[1] == node.start_point[1]
+
+    def _is_trailing_comment(self, document: Document, node: Node) -> bool:
+        line = document.positions.line_text(node.start_point[0])
+        return bool(line[: node.start_point[1]].strip())
+
+    def _build_line_group(self, profile: LanguageProfile, document: Document, nodes: list[Node]) -> CommentGroup:
+        lines = tuple(self._build_comment_line(profile, document, node, CommentForm.LINE) for node in nodes)
+        placement = self._classify_placement(profile, document, nodes[-1], is_doc=False)
+        return CommentGroup(
+            range=SourceRange(lines[0].range.start, lines[-1].range.end),
+            lines=lines,
+            form=CommentForm.LINE,
+            placement=placement,
+            attachment=self._resolve_attachment(profile, nodes[-1], is_doc=False)
+            if placement is CommentPlacement.LEADING_DECLARATION
+            else None,
+        )
+
+    def _build_doc_group(self, profile: LanguageProfile, document: Document, node: Node) -> CommentGroup:
+        lines: list[CommentLine] = []
+        for line_number in range(node.start_point[0], node.end_point[0] + 1):
+            marker_split = profile.split_delimiter(document.positions.line_text(line_number), CommentForm.DOC)
+            lines.append(
+                CommentLine(
+                    range=document.positions.line_range(line_number),
+                    indent=marker_split.indent,
+                    delimiter=marker_split.delimiter,
+                    text=marker_split.text,
+                    suffix=marker_split.suffix,
+                )
+            )
+        return CommentGroup(
+            range=SourceRange(lines[0].range.start, lines[-1].range.end),
+            lines=tuple(lines),
+            form=CommentForm.DOC,
+            placement=self._classify_placement(profile, document, node, is_doc=True),
+            attachment=self._resolve_attachment(profile, node, is_doc=True),
+        )
+
+    # Width is measured across indent, delimiter, and text together.
+    # Vale measures the extracted content alone, which is why a deeply indented comment passes there.
+    def _build_comment_line(
+        self, profile: LanguageProfile, document: Document, node: Node, form: CommentForm
+    ) -> CommentLine:
+        line_number, column = node.start_point
+        line_text = document.positions.line_text(line_number)
+        marker_split = profile.split_delimiter(line_text[column:], form)
+        return CommentLine(
+            range=document.positions.line_range(line_number),
+            indent=line_text[:column] + marker_split.indent,
+            delimiter=marker_split.delimiter,
+            text=marker_split.text,
+            suffix=marker_split.suffix,
+        )
+
+    def _classify_placement(
+        self,
+        profile: LanguageProfile,
+        document: Document,
+        node: Node,
+        *,
+        is_doc: bool,
+    ) -> CommentPlacement:
+        if is_doc:
+            owner = self._find_owning_definition(profile, node)
+            return CommentPlacement.FILE_HEADER if owner is None else CommentPlacement.LEADING_DECLARATION
+        if self._is_trailing_comment(document, node):
+            return CommentPlacement.TRAILING
+        if self._find_next_definition(profile, node) is not None:
+            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):
+            return CommentPlacement.FILE_HEADER
+        return CommentPlacement.INLINE_BODY
+
+    def _has_code_before(self, profile: LanguageProfile, node: Node) -> bool:
+        parent = node.parent
+        if parent is None:
+            return False
+        return any(
+            sibling.start_byte < node.start_byte and profile.role_of(sibling.type) is not NodeRole.COMMENT
+            for sibling in parent.named_children
+        )
+
+    def _find_next_definition(self, profile: LanguageProfile, node: Node) -> Node | None:
+        candidate = node.next_named_sibling
+        while candidate is not None:
+            role = profile.role_of(candidate.type)
+            if role is NodeRole.DEFINITION:
+                return candidate
+            if role is not NodeRole.COMMENT:
+                return None
+            candidate = candidate.next_named_sibling
+        return None
+
+    def _find_owning_definition(self, profile: LanguageProfile, node: Node) -> Node | None:
+        ancestor = node.parent
+        while ancestor is not None:
+            role = profile.role_of(ancestor.type)
+            if role is NodeRole.DEFINITION:
+                return ancestor
+            if role is NodeRole.ROOT:
+                return None
+            ancestor = ancestor.parent
+        return None
+
+    # Only a leading declaration documents a symbol, and CommentGroup rejects any other pairing.
+    def _resolve_attachment(self, profile: LanguageProfile, node: Node, *, is_doc: bool) -> SymbolRef | None:
+        definition_node = (
+            self._find_owning_definition(profile, node) if is_doc else self._find_next_definition(profile, node)
+        )
+        if definition_node is None:
+            return None
+        declaration = self._find_named_declaration(profile, definition_node)
+        if declaration is None:
+            return None
+        name_node = declaration.child_by_field_name('name')
+        if name_node is None or name_node.text is None:
+            return None
+        name = name_node.text.decode('utf-8')
+        return SymbolRef(
+            name=name,
+            kind=profile.symbol_kind(declaration.type),
+            visibility=profile.visibility_of(name),
+        )
+
+    # A decorated definition wraps the real one and carries no name field of its own,
+    # so the search descends until it reaches whichever node actually names something.
+    def _find_named_declaration(self, profile: LanguageProfile, node: Node) -> Node | None:
+        if node.child_by_field_name('name') is not None:
+            return node
+        for child_node in node.named_children:
+            if profile.role_of(child_node.type) is NodeRole.DEFINITION:
+                named_declaration = self._find_named_declaration(profile, child_node)
+                if named_declaration is not None:
+                    return named_declaration
+        return None

subedit/presentation/cli.py

@@ -0,0 +1,193 @@
+import difflib
+import pathlib
+import sys
+import typing
+
+import typer
+
+from .. import __version__
+from ..application import CorpusMeter, CorpusStatistics, Fixer, Linter, ReportAggregator, RuleEngine
+from ..domain.models.document import Document
+from ..infrastructure import ALL_RULES, DEFAULT_CONFIG_SOURCE, DEFAULT_PARSER, EXTERNAL_LINTERS, PYTHON
+from . import report as reporters
+from . import rule_reference
+
+
+app = typer.Typer(add_completion=False, help='A linter and formatter for the prose inside code comments.')
+
+FORMATTERS = {
+    'full': reporters.full,
+    'actionable': reporters.actionable,
+    'json': reporters.as_json,
+}
+PERCENTILES = (0.5, 0.75, 0.9, 0.95, 0.99)
+
+
+@app.command()
+def check(
+    paths: list[pathlib.Path] = typer.Argument(..., help='Files or directories to check.'),
+    output: str = typer.Option('full', '--output', help='full, actionable, or json.'),
+    delegate: bool = typer.Option(True, '--delegate/--no-delegate', help='Also run Vale and AutoCorrect.'),
+) -> None:
+    documents = _load(tuple(paths))
+    _require(documents)
+    formatter = FORMATTERS.get(output)
+    if formatter is None:
+        typer.echo(f'Unknown output format {output!r}. Choose full, actionable, or json.', err=True)
+        raise typer.Exit(2)
+
+    aggregator = _build_report_aggregator(delegate)
+    finding_count = 0
+    for document in documents:
+        report = aggregator.run(document, DEFAULT_CONFIG_SOURCE.resolve(_file_path(document)))
+        finding_count += len(report.diagnostics)
+        rendered_report = formatter(document, report)
+        if rendered_report:
+            typer.echo(rendered_report)
+    raise typer.Exit(1 if finding_count else 0)
+
+
+@app.command()
+def fix(
+    paths: list[pathlib.Path] = typer.Argument(..., help='Files or directories to fix.'),
+    write: bool = typer.Option(False, '--write', help='Write changes instead of printing a diff.'),
+) -> None:
+    documents = _load(tuple(paths))
+    _require(documents)
+
+    fixer = Fixer(_build_linter())
+    changed_file_count = 0
+    unresolved_finding_count = 0
+    for document in documents:
+        fix_result = fixer.run(document, DEFAULT_CONFIG_SOURCE.resolve(_file_path(document)))
+        unresolved_finding_count += len(fix_result.unresolved_findings)
+        if fix_result.has_changes:
+            changed_file_count += 1
+            if write:
+                pathlib.Path(_file_path(document)).write_text(fix_result.document.text, encoding='utf-8')
+            else:
+                typer.echo(_diff(document, fix_result.document))
+        if fix_result.unresolved_findings:
+            typer.echo(reporters.brief(fix_result.document, fix_result.report))
+
+    action_word = 'rewrote' if write else 'would rewrite'
+    typer.echo(
+        f'{action_word} {changed_file_count} of {len(documents)} files, {unresolved_finding_count} findings need an author.',
+        err=True,
+    )
+    raise typer.Exit(1 if unresolved_finding_count else 0)
+
+
+@app.command()
+def stats(paths: list[pathlib.Path] = typer.Argument(..., help='Files or directories to measure.')) -> None:
+    documents = _load(tuple(paths))
+    _require(documents)
+    typer.echo(_render(CorpusMeter(DEFAULT_PARSER).run(documents)))
+
+
+@app.command()
+def rules(
+    destination: pathlib.Path = typer.Option(None, '--write', help='Write the generated table to this path.'),
+) -> None:
+    rule_table = rule_reference.render(ALL_RULES)
+    if destination is None:
+        typer.echo(rule_table, nl=False)
+        return
+    destination.write_text(rule_table, encoding='utf-8')
+
+
+@app.command()
+def version() -> None:
+    typer.echo(f'subedit {__version__}')
+
+
+def main() -> int:
+    app()
+    return 0
+
+
+def _load(paths: tuple[pathlib.Path, ...]) -> tuple[Document, ...]:
+    source_paths: list[pathlib.Path] = []
+    for path in paths:
+        if path.is_dir():
+            source_paths.extend(
+                sorted(candidate for candidate in path.rglob('*') if candidate.suffix in PYTHON.extensions)
+            )
+        elif path.suffix in PYTHON.extensions:
+            source_paths.append(path)
+    documents: list[Document] = []
+    for source_path in source_paths:
+        root = DEFAULT_CONFIG_SOURCE.root_for(str(source_path))
+        if DEFAULT_CONFIG_SOURCE.is_excluded(
+            source_path, root, DEFAULT_CONFIG_SOURCE.exclude_patterns(str(source_path))
+        ):
+            continue
+        try:
+            text = source_path.read_text(encoding='utf-8')
+        except (OSError, UnicodeDecodeError):
+            continue
+        documents.append(Document(uri=source_path.resolve().as_uri(), text=text, language_id=PYTHON.language_id))
+    return tuple(documents)
+
+
+def _require(documents: tuple[Document, ...]) -> None:
+    if not documents:
+        typer.echo('No readable source files found.', err=True)
+        raise typer.Exit(1)
+
+
+def _build_linter() -> Linter:
+    return Linter(DEFAULT_PARSER, RuleEngine(ALL_RULES))
+
+
+def _build_report_aggregator(delegate: bool) -> ReportAggregator:
+    return ReportAggregator(_build_linter(), EXTERNAL_LINTERS if delegate else ())
+
+
+def _file_path(document: Document) -> str:
+    return document.uri.removeprefix('file://')
+
+
+def _diff(before: Document, after: Document) -> str:
+    path = _file_path(before)
+    return ''.join(
+        difflib.unified_diff(
+            before.text.splitlines(keepends=True),
+            after.text.splitlines(keepends=True),
+            fromfile=path,
+            tofile=path,
+        )
+    ).rstrip()
+
+
+def _render(statistics: CorpusStatistics) -> str:
+    heading = (
+        f'{"group":24s} {"n":>6s} {"med":>5s} '
+        + ' '.join(f'p{int(fraction * 100):<3d}' for fraction in PERCENTILES)
+        + '  max'
+    )
+    lines = [
+        f'{statistics.document_count} documents, {statistics.group_count} comment blocks',
+        '',
+        'block line counts',
+        heading,
+    ]
+    lines.extend(_row(distribution.label, distribution) for distribution in statistics.line_counts)
+    for distribution in (statistics.physical_widths, statistics.sentence_lengths):
+        lines.extend(['', distribution.label, _row('', distribution)])
+    lines.extend(['', 'sentences over width with no comma to break at'])
+    for width, sentence_count in statistics.unbreakable_counts_by_width:
+        percentage = (
+            sentence_count / statistics.sentence_lengths.count * 100 if statistics.sentence_lengths.count else 0.0
+        )
+        lines.append(f'  width {width:3d}  {sentence_count:5d} sentences  {percentage:5.2f}%')
+    return '\n'.join(lines)
+
+
+def _row(label: str, distribution: typing.Any) -> str:
+    cells = ' '.join(f'{distribution.percentile(fraction):<4d}' for fraction in PERCENTILES)
+    return f'{label:24s} {distribution.count:6d} {distribution.median:5d} {cells} {distribution.maximum:4d}'
+
+
+if __name__ == '__main__':
+    sys.exit(main())

subedit/presentation/harnesses/__init__.py

@@ -0,0 +1,40 @@
+import pathlib
+
+from ...infrastructure import PYTHON
+from .agent_harness import BLOCK_EXIT, AgentHarness, HarnessMetadata, Payload
+from .claude_code_harness import ClaudeCodeHarness
+from .codex_harness import CodexHarness
+
+
+EXTENSIONS = frozenset(PYTHON.extensions)
+
+# Each agent names its edit tools differently, so a payload identifies its own sender.
+# One project can run both agents at once, and neither needs to know the other exists.
+ALL_HARNESSES: tuple[AgentHarness, ...] = (
+    ClaudeCodeHarness(EXTENSIONS),
+    CodexHarness(EXTENSIONS),
+)
+
+
+def resolve(payload: Payload) -> tuple[AgentHarness, tuple[pathlib.Path, ...]] | None:
+    """Hand the payload to each harness until one recognises it.
+
+    A harness that declines returns None, so declining and finding nothing stay distinct.
+    """
+    for harness in ALL_HARNESSES:
+        edited_paths = harness.edited_files(payload)
+        if edited_paths is not None:
+            return harness, edited_paths
+    return None
+
+
+__all__ = [
+    'ALL_HARNESSES',
+    'BLOCK_EXIT',
+    'AgentHarness',
+    'ClaudeCodeHarness',
+    'CodexHarness',
+    'HarnessMetadata',
+    'Payload',
+    'resolve',
+]

subedit/presentation/harnesses/agent_harness.py

@@ -0,0 +1,43 @@
+import abc
+import dataclasses
+import pathlib
+import typing
+
+
+# Both Claude Code and Codex block by exiting two and writing the reason to stderr,
+# so the exit contract is shared and only the payload shape differs.
+BLOCK_EXIT = 2
+
+Payload = typing.Mapping[str, object]
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class HarnessMetadata:
+    name: str
+    summary: str
+    example: Payload
+
+    def __post_init__(self) -> None:
+        if not self.name or not self.summary:
+            raise ValueError('A harness names itself and says what it recognises')
+
+
+class AgentHarness(abc.ABC):
+    metadata: HarnessMetadata
+
+    @abc.abstractmethod
+    def edited_files(self, payload: Payload) -> tuple[pathlib.Path, ...] | None:
+        """Return the files this payload edited, or None when it came from another agent.
+
+        An empty tuple and None mean different things.
+        Empty says the payload was ours and touched nothing we check.
+        None says it was never ours to read.
+        """
+        ...
+
+
+def existing_source_files(
+    candidates: typing.Iterable[str | pathlib.Path], extensions: frozenset[str]
+) -> tuple[pathlib.Path, ...]:
+    paths = [pathlib.Path(candidate) for candidate in candidates]
+    return tuple(dict.fromkeys(path for path in paths if path.suffix in extensions and path.is_file()))

subedit/presentation/harnesses/claude_code_harness.py

@@ -0,0 +1,37 @@
+import pathlib
+import typing
+
+from .agent_harness import AgentHarness, HarnessMetadata, Payload, existing_source_files
+
+
+EDIT_TOOLS = frozenset({'Edit', 'Write', 'MultiEdit', 'NotebookEdit'})
+PATH_FIELDS = ('file_path', 'notebook_path')
+
+CLAUDE_CODE = HarnessMetadata(
+    name='claude-code',
+    summary='Claude Code names the edited file in tool_input.',
+    example={'tool_name': 'Edit', 'tool_input': {'file_path': 'src/module.py'}},
+)
+
+
+class ClaudeCodeHarness(AgentHarness):
+    metadata = CLAUDE_CODE
+
+    def __init__(self, extensions: frozenset[str]) -> None:
+        self._extensions = extensions
+
+    def edited_files(self, payload: Payload) -> tuple[pathlib.Path, ...] | None:
+        tool_name = payload.get('tool_name')
+        if not isinstance(tool_name, str) or tool_name not in EDIT_TOOLS:
+            return None
+        tool_input = self._tool_input(payload)
+        path_values = [tool_input.get(field) for field in PATH_FIELDS]
+        if not any(path_value is not None for path_value in path_values):
+            return None
+        return existing_source_files(
+            [path_value for path_value in path_values if isinstance(path_value, str) and path_value], self._extensions
+        )
+
+    def _tool_input(self, payload: Payload) -> typing.Mapping[str, object]:
+        tool_input = payload.get('tool_input')
+        return tool_input if isinstance(tool_input, dict) else {}

subedit/presentation/harnesses/codex_harness.py

@@ -0,0 +1,43 @@
+import pathlib
+import re
+import typing
+
+from .agent_harness import AgentHarness, HarnessMetadata, Payload, existing_source_files
+
+
+EDIT_TOOLS = frozenset({'apply_patch'})
+
+CODEX = HarnessMetadata(
+    name='codex',
+    summary='Codex sends a patch, and the path is read from its header.',
+    example={'tool_name': 'apply_patch', 'tool_input': {'command': '*** Update File: src/module.py'}},
+)
+
+
+# Codex carries no path field.
+# The patch body names each file in its header, so the path is read back out of the diff.
+_PATCH_HEADER = re.compile(r'^(?:\*\*\*\s+(?:Update|Add|Delete) File:|---|\+\+\+)\s+(.+?)\s*$', re.MULTILINE)
+_STRIP_PREFIX = re.compile(r'^[ab]/')
+
+
+class CodexHarness(AgentHarness):
+    metadata = CODEX
+
+    def __init__(self, extensions: frozenset[str]) -> None:
+        self._extensions = extensions
+
+    def edited_files(self, payload: Payload) -> tuple[pathlib.Path, ...] | None:
+        tool_name = payload.get('tool_name')
+        if not isinstance(tool_name, str) or tool_name not in EDIT_TOOLS:
+            return None
+        command = self._tool_input(payload).get('command')
+        if not isinstance(command, str):
+            return None
+        patched_paths = [_STRIP_PREFIX.sub('', header.group(1)) for header in _PATCH_HEADER.finditer(command)]
+        return existing_source_files(
+            [patched_path for patched_path in patched_paths if patched_path != '/dev/null'], self._extensions
+        )
+
+    def _tool_input(self, payload: Payload) -> typing.Mapping[str, object]:
+        tool_input = payload.get('tool_input')
+        return tool_input if isinstance(tool_input, dict) else {}

subedit/presentation/hook.py

@@ -0,0 +1,108 @@
+import dataclasses
+import json
+import pathlib
+import sys
+
+from ..application import Fixer, Linter, RuleEngine
+from ..domain.models.document import Document
+from ..infrastructure import ALL_RULES, DEFAULT_CONFIG_SOURCE, DEFAULT_PARSER, PYTHON
+from . import report as reporters
+from .harnesses import ALL_HARNESSES, BLOCK_EXIT, Payload, resolve
+
+
+HELP_FLAGS = frozenset({'--help', '-h', '--harnesses'})
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class HookResult:
+    exit_code: int
+    stderr: str = ''
+    repaired_paths: tuple[str, ...] = ()
+    harness_name: str = ''
+
+    @property
+    def is_blocking(self) -> bool:
+        return self.exit_code == BLOCK_EXIT
+
+
+def run(payload: Payload, *, write: bool = True) -> HookResult:
+    recognition = resolve(payload)
+    if recognition is None:
+        return HookResult(exit_code=0)
+    harness, edited_paths = recognition
+    if not edited_paths:
+        return HookResult(exit_code=0, harness_name=harness.metadata.name)
+
+    fixer = Fixer(Linter(DEFAULT_PARSER, RuleEngine(ALL_RULES)))
+    author_messages: list[str] = []
+    repaired_paths: list[str] = []
+
+    for source_path in edited_paths:
+        try:
+            source_text = source_path.read_text(encoding='utf-8')
+        except (OSError, UnicodeDecodeError):
+            continue
+        document = Document(uri=source_path.resolve().as_uri(), text=source_text, language_id=PYTHON.language_id)
+        fix_result = fixer.run(document, DEFAULT_CONFIG_SOURCE.resolve(str(source_path)))
+        if fix_result.has_changes and write:
+            source_path.write_text(fix_result.document.text, encoding='utf-8')
+            repaired_paths.append(str(source_path))
+        brief_report = reporters.brief(fix_result.document, fix_result.report)
+        if brief_report:
+            author_messages.append(brief_report)
+
+    if not author_messages:
+        return HookResult(exit_code=0, repaired_paths=tuple(repaired_paths), harness_name=harness.metadata.name)
+    return HookResult(
+        exit_code=BLOCK_EXIT,
+        stderr='\n\n'.join(author_messages),
+        repaired_paths=tuple(repaired_paths),
+        harness_name=harness.metadata.name,
+    )
+
+
+def edited_files(payload: Payload) -> tuple[pathlib.Path, ...]:
+    recognition = resolve(payload)
+    if recognition is None:
+        return ()
+    _, edited_paths = recognition
+    return edited_paths
+
+
+def describe_harnesses() -> str:
+    """Say which payload shapes reach this hook, so a caller can check its own.
+
+    Unrecognised payloads exit quietly, since an agent sends many that are none of our business.
+    That silence is why the shapes have to be askable for.
+    """
+    help_lines = ['subedit-hook reads one agent payload on stdin.', '']
+    for harness in ALL_HARNESSES:
+        metadata = harness.metadata
+        help_lines.extend([metadata.name, f'  {metadata.summary}', f'  {json.dumps(metadata.example)}', ''])
+    help_lines.extend(
+        [
+            'A payload no harness recognises exits 0 and changes nothing.',
+            'Outside an agent, use subedit fix --write and subedit check instead.',
+        ]
+    )
+    return '\n'.join(help_lines)
+
+
+def main() -> int:
+    if HELP_FLAGS & set(sys.argv[1:]):
+        sys.stdout.write(describe_harnesses() + '\n')
+        return 0
+    try:
+        payload = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        return 0
+    if not isinstance(payload, dict):
+        return 0
+    hook_result = run(payload)
+    if hook_result.stderr:
+        sys.stderr.write(hook_result.stderr + '\n')
+    return hook_result.exit_code
+
+
+if __name__ == '__main__':
+    sys.exit(main())