argusf 0.1.0.dev0__py3-none-any.whl

argusf/parser/treesitter/__init__.py

@@ -0,0 +1 @@
+"""Tree-sitter implementation of the parsing engine."""

argusf/parser/treesitter/backend.py

@@ -0,0 +1,157 @@
+"""Tree-sitter parsing engine producing SourceFile IR."""
+
+from typing import TYPE_CHECKING
+
+import tree_sitter_fortran as tsfortran
+from tree_sitter import Language, Node, Parser, Tree
+
+from argusf.ir.models import Comment, ProgramUnit, SourceFile, SourceFileMetadata, SourceSpan
+from argusf.parser.backend import ParseError, ParsingEngine
+
+from .walker import TreeSitterNodeParserRegistry, TreeSitterNodeType, get_node_span, walk
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from argusf.diagnostics import Diagnostics
+
+FORTRAN_LANGUAGE = Language(tsfortran.language())
+
+
+class TreesitterParsingEngine(ParsingEngine):
+    """Parses Fortran source into IR via tree-sitter."""
+
+    def __init__(self, diagnostics: Diagnostics) -> None:
+        """Build the engine with a diagnostics channel.
+
+        Args:
+            diagnostics: Channel for reporting skipped top-level
+                nodes encountered during the walk.
+        """
+        self._parser = Parser(FORTRAN_LANGUAGE)
+        self._diagnostics = diagnostics
+
+    def parse(self, file: SourceFileMetadata) -> SourceFile:
+        """Read `file` from disk and parse it into a `SourceFile`.
+
+        Args:
+            file: Identity metadata of the file to parse.
+
+        Returns:
+            The parsed source file.
+
+        Raises:
+            ParseError: If the file can no longer be read.
+        """
+        # This re-read is an accepted TOCTOU window against the
+        # discovery hash (metadata is deliberately lean, so the bytes
+        # don't travel with it): a file modified mid-run is parsed in
+        # its newer form. Harm is bounded — the fix stage re-verifies
+        # the content hash before editing, and a cache entry keyed to
+        # the stale identity fails validation next run, forcing
+        # re-analysis.
+        try:
+            source = file.file_path.read_bytes()
+        except OSError as error:
+            # Readable at discovery but not now (deleted, permissions
+            # flipped): surface through the normal parse-failure path.
+            raise ParseError(f"could not read {file.file_path}: {error}") from error
+        return self.parse_source(file.file_path, source)
+
+    def parse_source(self, path: Path, source: bytes) -> SourceFile:
+        """Parse in-memory `source` into a `SourceFile`.
+
+        Collects syntax-error spans, walks the tree into IR program
+        units and comments, then orders the errors by document
+        position.
+
+        Args:
+            path: Path recorded on the resulting SourceFile.
+            source: The exact bytes to parse.
+
+        Returns:
+            The parsed source file.
+        """
+        tree = self._parser.parse(source)
+        source_file = SourceFile(file_path=path, source=source)
+        source_file.syntax_errors = self._collect_error_spans(tree.root_node)
+        self._walk_tree(source_file, tree)
+        # Unit-level failures are appended during the walk, after the
+        # error-node spans, so restore document order.
+        source_file.syntax_errors.sort(key=lambda span: span.start_byte)
+        return source_file
+
+    def _collect_error_spans(self, root: Node) -> list[SourceSpan]:
+        """Collect one span per unparseable region of the tree.
+
+        Covers ERROR nodes (tree-sitter's error recovery wraps
+        unrecognised input in them) and missing nodes (zero-width
+        tokens inserted to complete a rule, e.g. a lost `end`). Descent
+        is pruned to error-carrying subtrees, so clean files pay a
+        single flag check and error regions are never descended into
+        (nested errors collapse into the enclosing region's span).
+        """
+        if not root.has_error:
+            return []
+        if root.is_error:
+            return [get_node_span(root)]
+
+        spans: list[SourceSpan] = []
+        stack = [root]
+        while stack:
+            node = stack.pop()
+            for child in reversed(node.children):
+                if child.is_error or child.is_missing:
+                    spans.append(get_node_span(child))
+                elif child.has_error:
+                    stack.append(child)
+        return spans
+
+    def _walk_tree(self, source_file: SourceFile, tree: Tree) -> None:
+        if tree.root_node.type != TreeSitterNodeType.TRANSLATION_UNIT:
+            # The grammar's root rule matches any input (including
+            # none), so this should be unreachable; the error walk has
+            # already recorded the whole file as a syntax error if it
+            # fires.
+            return
+
+        for child_node in tree.root_node.children:
+            # A failure inside one unit skips that unit only; the rest
+            # of the file still gets analysed (tree-sitter is
+            # error-tolerant, so one malformed region must not reject
+            # the whole file).
+            try:
+                result = walk(child_node)
+            except ParseError:
+                self._record_failed_unit(source_file, child_node)
+                continue
+            if isinstance(result, ProgramUnit):
+                source_file.add_program_unit(result)
+                continue
+            if isinstance(result, Comment):
+                source_file.add_comment(result)
+                continue
+            if not child_node.is_named:
+                continue
+            if result is None and TreeSitterNodeParserRegistry.get(child_node.type) is not None:
+                continue
+            if child_node.type == TreeSitterNodeType.ERROR:
+                continue  # already recorded as a syntax error by the error walk
+            # A named node with no handler or an unexpected bare
+            # statement: surface what was dropped instead of vanishing
+            # silently.
+            self._diagnostics.emit(
+                f"skipped top-level node '{child_node.type}': {source_file.file_path}:{child_node.start_point.row + 1}"
+            )
+
+    def _record_failed_unit(self, source_file: SourceFile, node: Node) -> None:
+        """Record a failed unit as one whole-unit syntax error.
+
+        Skipped when the error walk already recorded a region inside
+        the unit, in which case that span is the better (narrower)
+        report.
+        """
+        for span in source_file.syntax_errors:
+            if node.start_byte <= span.start_byte and span.end_byte <= node.end_byte:
+                return
+        source_file.syntax_errors.append(get_node_span(node))

argusf/parser/treesitter/walker/__init__.py

@@ -0,0 +1,5 @@
+# Import handlers to trigger registration with the registry.
+from . import handlers
+from .walker import TreeSitterNodeParserRegistry, TreeSitterNodeType, get_node_span, walk
+
+__all__ = ["TreeSitterNodeParserRegistry", "TreeSitterNodeType", "get_node_span", "walk"]

argusf/parser/treesitter/walker/handlers.py

@@ -0,0 +1,209 @@
+from typing import TYPE_CHECKING
+
+from argusf.ir.models import (
+    ArithmeticIfStatement,
+    BlockData,
+    Comment,
+    CommonStatement,
+    EntryStatement,
+    EquivalenceStatement,
+    Function,
+    GotoStatement,
+    ImplicitStatement,
+    Module,
+    PauseStatement,
+    Program,
+    ProgramUnit,
+    Statement,
+    Submodule,
+    Subroutine,
+    UseStatement,
+)
+from argusf.parser.backend import ParseError
+
+from .walker import TreeSitterNodeParserRegistry, TreeSitterNodeType, get_node_span, walk
+
+if TYPE_CHECKING:
+    from tree_sitter import Node
+
+
+def _collect_body(node: Node, unit: ProgramUnit) -> None:
+    """Walk `node`'s children into `unit`'s statements and subunits.
+
+    Statements can sit arbitrarily deep inside a program unit (e.g. a
+    GOTO nested in an IF block), so for nodes with no registered handler
+    we keep recursing down their children looking for ones that do. Only
+    named children are walked: anonymous keyword tokens such as the
+    `program` in "END PROGRAM" share a node type with their container
+    and would otherwise be dispatched to the wrong handler. Contained
+    procedures (a `contains` section) walk to ProgramUnits and become
+    subunits of the enclosing unit. Interface blocks are never descended
+    into: their bodies are procedure *signatures* represented as full
+    subroutine/function nodes, which would otherwise become phantom
+    empty subunits.
+    """
+    for child in node.named_children:
+        if child.type == TreeSitterNodeType.INTERFACE:
+            continue
+        result = walk(child)
+        if isinstance(result, ProgramUnit):
+            unit.add_subunit(result)
+        elif isinstance(result, Statement):
+            unit.add_statement(result)
+        else:
+            _collect_body(child, unit)
+
+
+def _extract_unit_name(node: Node, name_statement_type: TreeSitterNodeType) -> str | None:
+    """Extract a unit's declared name, or None if anonymous.
+
+    The unit's *_statement child holds its name as a direct child of
+    node type `name`. Position is not reliable: function_statement puts
+    prefix tokens (purity, result type) before the name, and
+    submodule_statement wraps the parent module's name in a
+    `module_name` node before the submodule's own. The statement is
+    metadata for the enclosing unit rather than an IR node, so it is
+    extracted here instead of through a registered handler. Returns None
+    for anonymous units (a main program without a PROGRAM statement has
+    no program_statement child at all).
+    """
+    for child in node.named_children:
+        if child.type != name_statement_type:
+            continue
+        for statement_child in child.named_children:
+            if statement_child.type == TreeSitterNodeType.NAME and statement_child.text is not None:
+                return statement_child.text.decode()
+        return None
+    return None
+
+
+def _parse_program_unit[UnitT: ProgramUnit](
+    node: Node, name_statement_type: TreeSitterNodeType, unit_cls: type[UnitT]
+) -> UnitT:
+    if not node.children:
+        raise ParseError(f"{unit_cls.__name__} node at {node.start_point} has no children")
+
+    name = _extract_unit_name(node, name_statement_type)
+    unit = unit_cls(name=name, span=get_node_span(node))
+    _collect_body(node, unit)
+    return unit
+
+
+@TreeSitterNodeParserRegistry.register(TreeSitterNodeType.PROGRAM)
+def parse_program(node: Node) -> Program:
+    return _parse_program_unit(node, TreeSitterNodeType.PROGRAM_STATEMENT, Program)
+
+
+@TreeSitterNodeParserRegistry.register(TreeSitterNodeType.MODULE)
+def parse_module(node: Node) -> Module:
+    return _parse_program_unit(node, TreeSitterNodeType.MODULE_STATEMENT, Module)
+
+
+@TreeSitterNodeParserRegistry.register(TreeSitterNodeType.SUBROUTINE)
+def parse_subroutine(node: Node) -> Subroutine:
+    return _parse_program_unit(node, TreeSitterNodeType.SUBROUTINE_STATEMENT, Subroutine)
+
+
+@TreeSitterNodeParserRegistry.register(TreeSitterNodeType.FUNCTION)
+def parse_function(node: Node) -> Function:
+    return _parse_program_unit(node, TreeSitterNodeType.FUNCTION_STATEMENT, Function)
+
+
+@TreeSitterNodeParserRegistry.register(TreeSitterNodeType.SUBMODULE)
+def parse_submodule(node: Node) -> Submodule:
+    return _parse_program_unit(node, TreeSitterNodeType.SUBMODULE_STATEMENT, Submodule)
+
+
+@TreeSitterNodeParserRegistry.register(TreeSitterNodeType.BLOCK_DATA)
+def parse_block_data(node: Node) -> BlockData:
+    return _parse_program_unit(node, TreeSitterNodeType.BLOCK_DATA_STATEMENT, BlockData)
+
+
+def _leading_keyword(node: Node) -> str:
+    """Return the type of a node's leading keyword child.
+
+    Several grammar node types bundle multiple Fortran statements under
+    one node, discriminated by the leading keyword child (GOTO under
+    keyword_statement, PAUSE under file_position_statement). Raises if
+    the node is unexpectedly childless.
+    """
+    keyword_node = node.child(0)
+    if keyword_node is None:
+        raise ParseError(f"Statement at {node.start_point} has no keyword node")
+
+    return keyword_node.type
+
+
+# GOTO has no dedicated node type; the grammar groups it with other
+# simple statements (CONTINUE, RETURN, STOP, ...) under
+# keyword_statement, and the leading keyword child tells them apart.
+# "GOTO 10" yields a single `goto` child while "GO TO 10" yields a `go`
+# child followed by a `to` child.
+@TreeSitterNodeParserRegistry.register(TreeSitterNodeType.KEYWORD_STATEMENT)
+def parse_keyword_statement(node: Node) -> GotoStatement | None:
+    if _leading_keyword(node) in (TreeSitterNodeType.GOTO, TreeSitterNodeType.GO):
+        return GotoStatement(span=get_node_span(node))
+    return None
+
+
+@TreeSitterNodeParserRegistry.register(TreeSitterNodeType.COMMON_STATEMENT)
+def parse_common_statement(node: Node) -> CommonStatement:
+    return CommonStatement(span=get_node_span(node))
+
+
+@TreeSitterNodeParserRegistry.register(TreeSitterNodeType.EQUIVALENCE_STATEMENT)
+def parse_equivalence_statement(node: Node) -> EquivalenceStatement:
+    return EquivalenceStatement(span=get_node_span(node))
+
+
+@TreeSitterNodeParserRegistry.register(TreeSitterNodeType.ARITHMETIC_IF_STATEMENT)
+def parse_arithmetic_if_statement(node: Node) -> ArithmeticIfStatement:
+    return ArithmeticIfStatement(span=get_node_span(node))
+
+
+@TreeSitterNodeParserRegistry.register(TreeSitterNodeType.ENTRY_STATEMENT)
+def parse_entry_statement(node: Node) -> EntryStatement:
+    return EntryStatement(span=get_node_span(node))
+
+
+# IMPLICIT NONE and implicit typing rules (IMPLICIT REAL(A-H)) share the
+# implicit_statement node type; a named `none` child tells them apart. A
+# parenthesised spec list after NONE narrows what it disables: bare NONE
+# and NONE (TYPE, ...) disable implicit typing, NONE (EXTERNAL) alone
+# does not (it only forbids implicit procedure interfaces). The spec
+# keywords are anonymous tokens, so all children are scanned, not just
+# named ones.
+@TreeSitterNodeParserRegistry.register(TreeSitterNodeType.IMPLICIT_STATEMENT)
+def parse_implicit_statement(node: Node) -> ImplicitStatement:
+    has_none = any(child.type == TreeSitterNodeType.NONE for child in node.named_children)
+    has_spec_list = any(child.type == "(" for child in node.children)
+    has_type_spec = any(child.type == TreeSitterNodeType.TYPE for child in node.children)
+    is_none = has_none and (not has_spec_list or has_type_spec)
+    return ImplicitStatement(span=get_node_span(node), is_none=is_none)
+
+
+# The module name is a dedicated module_name child; submodule extensions
+# (`use, non_intrinsic :: m`) and ONLY clauses are sibling nodes the
+# span already covers, so only the name needs extracting.
+@TreeSitterNodeParserRegistry.register(TreeSitterNodeType.USE_STATEMENT)
+def parse_use_statement(node: Node) -> UseStatement:
+    for child in node.named_children:
+        if child.type == TreeSitterNodeType.MODULE_NAME and child.text is not None:
+            return UseStatement(span=get_node_span(node), module_name=child.text.decode())
+    raise ParseError(f"Use statement at {node.start_point} has no module name")
+
+
+# PAUSE has no dedicated node type; the grammar groups it with REWIND,
+# BACKSPACE and ENDFILE under file_position_statement, and the leading
+# keyword child tells them apart (same trick as GOTO above).
+@TreeSitterNodeParserRegistry.register(TreeSitterNodeType.FILE_POSITION_STATEMENT)
+def parse_file_position_statement(node: Node) -> PauseStatement | None:
+    if _leading_keyword(node) == TreeSitterNodeType.PAUSE:
+        return PauseStatement(span=get_node_span(node))
+    return None
+
+
+@TreeSitterNodeParserRegistry.register(TreeSitterNodeType.COMMENT)
+def parse_comment(node: Node) -> Comment:
+    text = node.text.decode(errors="replace") if node.text is not None else ""
+    return Comment(span=get_node_span(node), text=text)

argusf/parser/treesitter/walker/walker.py

@@ -0,0 +1,82 @@
+"""Tree-sitter node walking: registry, node types, and span helper."""
+
+from enum import StrEnum
+from typing import TYPE_CHECKING
+
+from argusf.ir.models import ProgramUnit, SourceSpan, Statement
+from argusf.registry import Registry
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from tree_sitter import Node
+
+TreeSitterNodeParserRegistry: Registry[str, Callable[[Node], ProgramUnit | Statement | None]] = Registry()
+
+
+def get_node_span(node: Node) -> SourceSpan:
+    """Return the source span of a tree-sitter `node`."""
+    start_row, start_col = node.start_point
+    end_row, end_col = node.end_point
+
+    return SourceSpan(
+        start_row=start_row,
+        start_col=start_col,
+        end_row=end_row,
+        end_col=end_col,
+        start_byte=node.start_byte,
+        end_byte=node.end_byte,
+    )
+
+
+class TreeSitterNodeType(StrEnum):
+    """Tree-sitter node type names used by the parser handlers."""
+
+    ARITHMETIC_IF_STATEMENT = "arithmetic_if_statement"
+    BLOCK_DATA = "block_data"
+    BLOCK_DATA_STATEMENT = "block_data_statement"
+    COMMENT = "comment"
+    COMMON_STATEMENT = "common_statement"
+    ENTRY_STATEMENT = "entry_statement"
+    EQUIVALENCE_STATEMENT = "equivalence_statement"
+    ERROR = "ERROR"
+    FILE_POSITION_STATEMENT = "file_position_statement"
+    FUNCTION = "function"
+    FUNCTION_STATEMENT = "function_statement"
+    GO = "go"
+    GOTO = "goto"
+    IMPLICIT_STATEMENT = "implicit_statement"
+    INTERFACE = "interface"
+    KEYWORD_STATEMENT = "keyword_statement"
+    MODULE = "module"
+    MODULE_NAME = "module_name"
+    MODULE_STATEMENT = "module_statement"
+    NAME = "name"
+    NONE = "none"
+    PAUSE = "pause"
+    PROGRAM = "program"
+    PROGRAM_STATEMENT = "program_statement"
+    SUBMODULE = "submodule"
+    SUBMODULE_STATEMENT = "submodule_statement"
+    SUBROUTINE = "subroutine"
+    SUBROUTINE_STATEMENT = "subroutine_statement"
+    TRANSLATION_UNIT = "translation_unit"
+    TYPE = "type"
+    USE_STATEMENT = "use_statement"
+
+
+def walk(node: Node) -> ProgramUnit | Statement | None:
+    """Dispatch `node` to its registered handler, if any.
+
+    Args:
+        node: Tree-sitter node to parse.
+
+    Returns:
+        The handler's IR result, or None when no handler is
+        registered for the node type.
+    """
+    handler = TreeSitterNodeParserRegistry.get(node.type)
+    if handler is None:
+        return None
+
+    return handler(node)

argusf/registry/__init__.py

@@ -0,0 +1,3 @@
+"""The generic registry underpinning the plugin registries."""
+
+from .registry import Registry as Registry

argusf/registry/registry.py

@@ -0,0 +1,69 @@
+"""A generic registry mapping keys to registered values."""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, KeysView, ValuesView
+
+
+class Registry[Key, Value]:
+    """Maps keys to values via a `@register`-style decorator.
+
+    The base of the plugin registries (rules, reporters, config
+    readers, parser handlers): subclasses instantiate it with their
+    own key/value types and share this registration and lookup
+    surface.
+    """
+
+    def __init__(self) -> None:
+        """Create an empty registry."""
+        self._store: dict[Key, Value] = {}
+
+    def register(self, key: Key) -> Callable[[Value], Value]:
+        """Return a decorator that registers a value under `key`.
+
+        Args:
+            key: Key to register the decorated value under.
+
+        Returns:
+            A decorator that stores the value and returns it
+            unchanged.
+
+        Raises:
+            ValueError: If `key` is already registered.
+        """
+
+        def decorator(func: Value) -> Value:
+            if key in self._store:
+                raise ValueError(f"Key {key} is already registered.")
+
+            self._store[key] = func
+            return func
+
+        return decorator
+
+    def get(self, key: Key) -> Value | None:
+        """Return the value registered under `key`, or None.
+
+        Args:
+            key: Key to look up.
+
+        Returns:
+            The registered value, or None when `key` is unknown.
+        """
+        if key in self._store:
+            return self._store[key]
+
+        return None
+
+    def keys(self) -> KeysView[Key]:
+        """Return a view of the registered keys."""
+        return self._store.keys()
+
+    def values(self) -> ValuesView[Value]:
+        """Return a view of the registered values."""
+        return self._store.values()
+
+    def __contains__(self, key: Key) -> bool:
+        """Return whether `key` is registered."""
+        return key in self._store

argusf/reporting/__init__.py

@@ -0,0 +1,22 @@
+"""Reporters that render a run's findings."""
+
+from .registry import Reporter, ReporterRegistry
+from .reporters import (
+    ConciseReporter,
+    DiffReporter,
+    JsonReporter,
+    NullReporter,
+    StandardReporter,
+    StatisticsReporter,
+)
+
+__all__ = [
+    "ConciseReporter",
+    "DiffReporter",
+    "JsonReporter",
+    "NullReporter",
+    "Reporter",
+    "ReporterRegistry",
+    "StandardReporter",
+    "StatisticsReporter",
+]