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

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 

6 

7"""AI: Low-level AST utility helpers: sibling and ancestor lookup, placeholder handling, and node matching.""" 

8 

9from collections import deque 

10from contextlib import contextmanager 

11from contextvars import ContextVar 

12from typing import TYPE_CHECKING 

13 

14from renaissance.integrations import MATCH_ALL, MATCH_ONE 

15 

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 

22 

23DISPLAY_PARSER_KIND: ContextVar[bool] = ContextVar("display_parser_kind", default=False) 

24 

25 

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) 

34 

35 

36def replace_dollar(text: str) -> str: 

37 """Replace dollar-sign placeholders in the given text with their corresponding match symbols. 

38 

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) 

43 

44 

45def use_dollar(text: str) -> str: 

46 """Replace match symbols in the given text with their corresponding dollar-sign placeholders. 

47 

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, "$") 

52 

53 

54def detect_placeholder(signature: str, original_node_type: str) -> tuple[bool, str, str]: 

55 """Detect if the given signature represents a placeholder symbol. 

56 

57 Returns: 

58 (is_placeholder, coerced_node_type, placeholder_name_or_signature) 

59 

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, "-" 

69 

70 

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 

80 

81 

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) 

88 

89 

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. 

92 

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) 

105 

106 

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) 

110 

111 

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) 

115 

116 

117def is_ancestor_of(ancestor: Rewritable, node: Rewritable) -> bool: 

118 """Return True if ancestor is a proper ancestor of node. 

119 

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 

128 

129 

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) 

134 

135 

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)) 

141 

142 

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 )