Coverage for src/renaissance/utils/ast_utils.py: 95%
73 statements
« prev ^ index » next coverage.py v7.17.0, created at 2026-11-16 16:04 +0000
« prev ^ index » next coverage.py v7.17.0, created at 2026-11-16 16:04 +0000
1# Copyright (C) 2024-2026 TNO
2#
3# Licensed under the terms specified in the LICENSE file in the root directory
4# of this repository, also available at:
5# https://github.com/TNO/Renaissance.Py/blob/main/LICENSE
7"""AI: Low-level AST utility helpers: sibling and ancestor lookup, placeholder handling, and node matching."""
9from collections import deque
10from contextlib import contextmanager
11from contextvars import ContextVar
12from typing import TYPE_CHECKING
14from renaissance.integrations import MATCH_ALL, MATCH_ONE
16# TODO(FrancescoPezzella): Replace with a lazy import in Python 3.15.
17# https://github.com/TNO/Renaissance.Py/issues/275
18if TYPE_CHECKING:
19 # syntax_tree imports this module, so a runtime import would be circular.
20 from renaissance.syntax_tree.ast_rewriter import Rewritable
21 from renaissance.syntax_tree.node_protocol import NodeProtocol
23DISPLAY_PARSER_KIND: ContextVar[bool] = ContextVar("display_parser_kind", default=False)
26@contextmanager
27def display_context(display_parser_kind: bool):
28 """AI: Temporarily set whether node display uses parser kind instead of semantic kind."""
29 token = DISPLAY_PARSER_KIND.set(display_parser_kind)
30 try:
31 yield
32 finally:
33 DISPLAY_PARSER_KIND.reset(token)
36def replace_dollar(text: str) -> str:
37 """Replace dollar-sign placeholders in the given text with their corresponding match symbols.
39 Two literal dollar-sign characters (`$$`) are replaced with MATCH_ALL; a single literal dollar-sign
40 character (`$`) is replaced with MATCH_ONE.
41 """
42 return text.replace("$$", MATCH_ALL).replace("$", MATCH_ONE)
45def use_dollar(text: str) -> str:
46 """Replace match symbols in the given text with their corresponding dollar-sign placeholders.
48 MATCH_ALL is replaced with two literal dollar-sign characters (`$$`); MATCH_ONE is replaced with a
49 single literal dollar-sign character (`$`).
50 """
51 return text.replace(MATCH_ALL, "$$").replace(MATCH_ONE, "$")
54def detect_placeholder(signature: str, original_node_type: str) -> tuple[bool, str, str]:
55 """Detect if the given signature represents a placeholder symbol.
57 Returns:
58 (is_placeholder, coerced_node_type, placeholder_name_or_signature)
60 """
61 if not signature:
62 return False, original_node_type, ""
63 if signature.startswith((MATCH_ALL, "$$")) and " " not in signature and "(" not in signature:
64 # legacy compatibility
65 return True, MATCH_ALL, signature
66 if signature.startswith((MATCH_ONE, "$")) and " " not in signature and "(" not in signature:
67 return True, MATCH_ONE, signature
68 return False, original_node_type, "-"
71# duplicate of ast node process
72def traverse(node):
73 """AI: Yield node and all its descendants in breadth-first order."""
74 todo = deque([node])
75 while todo:
76 node = todo.popleft()
77 if hasattr(node, "children"):
78 todo.extend(node.children)
79 yield node
82def process_node(node, action) -> None:
83 """AI: Recursively apply action to node and all its descendants."""
84 action(node)
85 if node.children:
86 for child in node.children:
87 process_node(child, action)
90def _sibling_at[NodeT: NodeProtocol](node: NodeT, offset: int) -> NodeT | None:
91 """Return the sibling offset positions away from node in its parent's children, or None.
93 The node is located by identity, since node equality is structural.
94 """
95 parent = node.parent
96 if parent is None:
97 return None
98 siblings = parent.children
99 for index, sibling in enumerate(siblings):
100 if sibling is node:
101 target = index + offset
102 return siblings[target] if 0 <= target < len(siblings) else None
103 msg = "node is not among the children of its parent"
104 raise ValueError(msg)
107def preceding_sibling[NodeT: NodeProtocol](node: NodeT) -> NodeT | None:
108 """AI: Return the sibling immediately before node in its parent's children, or None."""
109 return _sibling_at(node, -1)
112def next_sibling[NodeT: NodeProtocol](node: NodeT) -> NodeT | None:
113 """AI: Return the sibling immediately after node in its parent's children, or None."""
114 return _sibling_at(node, 1)
117def is_ancestor_of(ancestor: Rewritable, node: Rewritable) -> bool:
118 """Return True if ancestor is a proper ancestor of node.
120 Parent links are compared by identity, since node equality is structural.
121 """
122 current = node.parent
123 while current is not None:
124 if current is ancestor:
125 return True
126 current = current.parent
127 return False
130def match_props(mine, other, irrelevant_props) -> bool:
131 """AI: Return True if mine and other agree on all properties except the irrelevant ones."""
132 all_keys = (mine.keys() | other.keys()) - irrelevant_props
133 return all(mine.get(n) == other.get(n) for n in all_keys)
136def match_children(mine, other, irrelevant_kinds) -> bool:
137 """AI: Return True if every child in other matches the corresponding child in mine (or has an irrelevant kind)."""
138 if mine is None or other is None:
139 return mine == other
140 return all((i < len(mine) and mine[i] == child) or child.parser_kind in irrelevant_kinds for i, child in enumerate(other))
143def format_node(node) -> str:
144 """AI: Return a human-readable, indented display string for a single AST node."""
145 raw_lines = node.signature.splitlines()
146 properties_text = "" if not node.show_props else node.properties
147 prefix = " " if len(raw_lines) < 2 else f"\n {node.indent}"
148 formatted_lines = [f"{prefix}|{line}|" for line in raw_lines]
149 semantic_name = node.semantic_kind.value
150 kind = node.parser_kind if DISPLAY_PARSER_KIND.get() or semantic_name == "node" else semantic_name
151 return (
152 f"{node.indent}({kind}, {node.name}, "
153 f"{node.filename}[{node.offset}:{node.offset + node.length}])"
154 f"{properties_text}:{''.join(formatted_lines)}\n"
155 )