Coverage for src/renaissance/syntax_tree/ast_node.py: 94%

155 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: Abstract base class for AST node implementations, with the shared traversal and rewrite protocol.""" 

8 

9from __future__ import annotations 

10 

11import re 

12import sys 

13from abc import ABC, abstractmethod 

14from collections.abc import Callable, Sequence 

15from enum import Enum 

16from pathlib import Path 

17from typing import Any, Self 

18 

19from renaissance.syntax_tree.node_protocol import NodeProtocol 

20from renaissance.syntax_tree.semantic_kind import SemanticKind 

21from renaissance.utils.ast_utils import format_node, next_sibling, preceding_sibling, process_node 

22from renaissance.utils.text_utils import TextUtils 

23 

24 

25# enum with ABORT, CONTINUE and SKIP 

26class VisitorResult(Enum): 

27 """AI: Signal how an AST traversal should continue after visiting a node.""" 

28 

29 ABORT = 0 

30 CONTINUE = 1 

31 SKIP = 2 

32 

33 

34class ASTReference[NodeProtocolT: NodeProtocol]: 

35 """Reference between two AST nodes, with its kind and additional properties.""" 

36 

37 def __init__(self, ast_node: NodeProtocolT, ref_kind: str, properties: dict[str, Any]) -> None: 

38 """Initialise the reference. 

39 

40 Args: 

41 ast_node: Node at the other end of the reference. 

42 ref_kind: Kind of the reference. 

43 properties: Additional properties of the reference. 

44 

45 """ 

46 self._node = ast_node 

47 self._ref_kind = ref_kind 

48 self._properties = properties 

49 

50 @property 

51 def node(self) -> NodeProtocolT: 

52 """Return the node at the other end of the reference.""" 

53 return self._node 

54 

55 @property 

56 def ref_kind(self) -> str: 

57 """AI: Return the kind of this reference.""" 

58 return self._ref_kind 

59 

60 @property 

61 def properties(self) -> dict[str, Any]: 

62 """AI: Return this reference's additional properties.""" 

63 return self._properties 

64 

65 

66# To make usage of the concrete class methods easier, ASTNode MUST NOT have ABSTRACT public classes!! 

67class ASTNode[NodeT, TranslationUnitT](ABC): 

68 """The base class to represent an AST node. 

69 

70 It is an abstract class that should be inherited by concrete classes that represent specific AST nodes. 

71 """ 

72 

73 cache: dict[str, bytes] = {} 

74 parser_kind: str 

75 semantic_kind: SemanticKind 

76 

77 def __init__(self, root: Self) -> None: 

78 """AI: Initialize a new AST node rooted at the given translation-unit-level node.""" 

79 super().__init__() 

80 self._parent = None 

81 self._children: list[Self] = [] 

82 self.show_props: bool = False 

83 self.translation_unit: TranslationUnitT | None = None 

84 self._kind: str = "" 

85 self._length: int = 0 

86 self._offset: int = 0 

87 self._filename: str = "" 

88 self.root: Self = root 

89 self._properties = {} 

90 self._name = "" 

91 self.node: NodeT | None = None 

92 self.indent = "" 

93 

94 def __repr__(self) -> str: 

95 """AI: Return the formatted node representation.""" 

96 return format_node(self) 

97 

98 def is_part_of_translation_unit(self) -> bool: 

99 """AI: Return whether this node's filename matches its root node's filename.""" 

100 return self.filename == self.root.filename 

101 

102 @property 

103 def signature(self) -> str: 

104 """AI: Return this node's source code text, or an empty string if it has no filename or span.""" 

105 start = self.offset 

106 end = self.extended_end_offset 

107 if start == end: 

108 return "" 

109 file = self.filename 

110 if not file: 

111 return "" 

112 return self.content(start, end) 

113 

114 @property 

115 def text(self) -> str: 

116 """AI: Return this node's signature text shifted left to remove its leading indent.""" 

117 return TextUtils.shift_left(self.signature, len(self.indent), start_line=1) 

118 

119 def content(self, start: int, end: int) -> str: 

120 """AI: Return the decoded source text between start and end offsets in the root's file content.""" 

121 content = self.root.binary_file_content() 

122 # TODO: see docs/developer/architecture/position-consistency.md - decodes with the host encoding, not the adapter's. 

123 return str(content[start:end], sys.getfilesystemencoding()) 

124 

125 def binary_file_content(self, file_path: str | None = None) -> bytes: 

126 """AI: Return the raw bytes of file_path (or the root's filename), reading and caching it on first access.""" 

127 if not file_path: 

128 file_path = self.root.filename 

129 try: 

130 return ASTNode.cache[file_path] 

131 except KeyError: 

132 with Path(file_path).open("rb") as f: 

133 content = f.read() 

134 ASTNode.cache[file_path] = content 

135 return content 

136 

137 @property 

138 def preceding_sibling(self) -> Self | None: 

139 """AI: Return the sibling node immediately preceding this one, or None.""" 

140 return preceding_sibling(self) 

141 

142 @property 

143 def next_sibling(self) -> Self | None: 

144 """AI: Return the sibling node immediately following this one, or None.""" 

145 return next_sibling(self) 

146 

147 @property 

148 @abstractmethod 

149 def references(self) -> Sequence[ASTReference[ASTNode[NodeT, TranslationUnitT]]]: 

150 """AI: Return the references that this node points to.""" 

151 

152 @property 

153 @abstractmethod 

154 def referenced_by(self) -> Sequence[ASTReference[ASTNode[NodeT, TranslationUnitT]]]: 

155 """AI: Return the references that point to this node.""" 

156 

157 def get_ancestor(self, kind: str | re.Pattern[str]) -> Self | None: 

158 """AI: Return the nearest ancestor node whose kind matches the given kind pattern, or None.""" 

159 pattern = re.compile(kind, re.IGNORECASE) if isinstance(kind, str) else kind 

160 parent = self.parent 

161 if not parent: 

162 return None 

163 if pattern.match(parent.kind): 

164 return parent 

165 return parent.get_ancestor(pattern) 

166 

167 def is_descendant_of(self, node: Self) -> bool: 

168 """AI: Return whether this node is a descendant of node.""" 

169 return node.is_ancestor_of(self) 

170 

171 def is_ancestor_of(self, descendant: Self) -> bool: 

172 """AI: Return whether this node is an ancestor of descendant.""" 

173 parent: Self | None = descendant.parent 

174 if parent == self: 

175 return True 

176 if not parent: 

177 return False 

178 return self.is_ancestor_of(parent) 

179 

180 @staticmethod 

181 @abstractmethod 

182 def load(file_path: Path, extra_args: Sequence[str], working_dir: Path) -> ASTNode[NodeT, TranslationUnitT]: 

183 """AI: Parse the source file at file_path into an AST node.""" 

184 

185 @staticmethod 

186 @abstractmethod 

187 def load_from_text(text: str, file_name: str, extra_args: Sequence[str], working_dir: Path) -> ASTNode[NodeT, TranslationUnitT]: 

188 """AI: Parse source text (attributed to file_name) into an AST node.""" 

189 

190 @property 

191 def name(self) -> str: 

192 """AI: Return this node's name.""" 

193 return self._name 

194 

195 @property 

196 def filename(self) -> str: 

197 """AI: Return this node's source file name.""" 

198 return self._filename 

199 

200 # TODO: Is this the best name: offset, start_offset, begin_offset, ...? 

201 # TODO: Should offset return a slice object, https://docs.python.org/3/library/functions.html#slice, instead of an int? 

202 # That would make it easier to get the text segment. 

203 @property 

204 def offset(self) -> int: 

205 """AI: Return the character offset where this node begins in the source text.""" 

206 return self._offset 

207 

208 @property 

209 def end_offset(self) -> int: 

210 """AI: Return the character offset where this node ends in the source text.""" 

211 return self.offset + self.length 

212 

213 # TODO: Is this the really best solution to ensure that the modified code has the proper layout? 

214 @property 

215 @abstractmethod 

216 def extended_end_offset(self) -> int: 

217 """AI: Return the character offset where this node's extended span (including trailing layout) ends.""" 

218 

219 @property 

220 def length(self) -> int: 

221 """AI: Return the length in characters of this node's source text.""" 

222 return self._length 

223 

224 @property 

225 def kind(self) -> str: 

226 """AI: Return this node's parser kind.""" 

227 return self._kind 

228 

229 @abstractmethod 

230 def matches_kind(self, node: Self) -> bool: 

231 """AI: Return whether node has the same kind as this node.""" 

232 

233 # TODO: What is the best name: properties, attributes, syntax_attributes, ...? 

234 @property 

235 def properties(self) -> dict[str, int | str]: # TODO: Is int | str really sufficient? Shouldn't it be Any? 

236 """AI: Return this node's syntax properties.""" 

237 return self._properties 

238 

239 @property 

240 def parent(self) -> Self | None: 

241 """AI: Return this node's parent node, or None if it has none.""" 

242 return self._parent 

243 

244 @property 

245 @abstractmethod 

246 def is_statement(self) -> bool: 

247 """AI: Return whether this node represents a statement.""" 

248 

249 @property 

250 def children(self) -> list[Self]: 

251 """AI: Return this node's child nodes.""" 

252 return self._children 

253 

254 def process(self, function: Callable[[Self], None]) -> None: 

255 """AI: Apply function to this node and recursively to all of its descendants.""" 

256 process_node(self, function) 

257 

258 def accept(self, function: Callable[[Self], VisitorResult]) -> None: 

259 """Accept a visitor function and apply it to the current node and its children. 

260 

261 Args: 

262 function (Callable[[Self], VisitorResult]): A function that takes an ASTNode as an argument and returns a VisitorResult. 

263 

264 """ 

265 if function(self) == VisitorResult.CONTINUE: 

266 for child in self.children: 

267 child.accept(function)