Coverage for sources/agentsmgr/exceptions.py: 47%

125 statements  

« prev     ^ index     » next       coverage.py v7.17.2, created at 2026-11-07 23:07 +0000

1# vim: set filetype=python fileencoding=utf-8: 

2# -*- coding: utf-8 -*- 

3 

4#============================================================================# 

5# # 

6# Licensed under the Apache License, Version 2.0 (the "License"); # 

7# you may not use this file except in compliance with the License. # 

8# You may obtain a copy of the License at # 

9# # 

10# http://www.apache.org/licenses/LICENSE-2.0 # 

11# # 

12# Unless required by applicable law or agreed to in writing, software # 

13# distributed under the License is distributed on an "AS IS" BASIS, # 

14# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 

15# See the License for the specific language governing permissions and # 

16# limitations under the License. # 

17# # 

18#============================================================================# 

19 

20 

21''' Family of exceptions for package API. ''' 

22 

23 

24from . import __ 

25 

26 

27class Omniexception( __.immut.exceptions.Omniexception ): 

28 ''' Base for all exceptions raised by package API. ''' 

29 

30 

31class Omnierror( Omniexception, Exception ): 

32 ''' Base for error exceptions raised by package API. ''' 

33 

34 def render_as_markdown( self ) -> tuple[ str, ... ]: 

35 ''' Renders exception as Markdown lines for display. ''' 

36 return ( f"❌ {self}", ) 

37 

38 

39class UnexpectedError( Omnierror ): 

40 ''' Unexpected failure escaping command handling. 

41 

42 Wraps non-Omnierror exceptions reaching the CLI entrypoint so 

43 they render through the standard error presentation path 

44 instead of exiting silently. Carries the original exception 

45 for traceback rendering; the ``SystemExit`` raised after 

46 rendering keeps it as ``__context__``. 

47 ''' 

48 

49 def __init__( self, exception: BaseException ): 

50 self.exception = exception 

51 super( ).__init__( 

52 f"Unexpected {type( exception ).__name__}: {exception}" ) 

53 

54 def render_as_markdown( self ) -> tuple[ str, ... ]: 

55 ''' Renders wrapped exception with traceback for diagnosis. ''' 

56 lines = [ f"❌ {self}", "" ] 

57 frames = __.traceback.format_exception( 

58 type( self.exception ), 

59 self.exception, 

60 self.exception.__traceback__ ) 

61 lines.extend( 

62 line for chunk in frames for line in chunk.splitlines( ) ) 

63 return tuple( lines ) 

64 

65 

66class CoderAbsence( Omnierror, ValueError ): 

67 ''' Coder absence in registry. ''' 

68 

69 def __init__( self, coder: str ): 

70 message = f"Coder not found in registry: {coder}" 

71 super( ).__init__( message ) 

72 

73 

74class ConfigurationAbsence( Omnierror, FileNotFoundError ): 

75 

76 def __init__( 

77 self, location: __.Absential[ __.Path ] = __.absent 

78 ) -> None: 

79 message = "Could not locate agents configuration" 

80 if not __.is_absent( location ): 

81 message = f"{message} at '{location}'" 

82 super( ).__init__( f"{message}." ) 

83 

84 def render_as_markdown( self ) -> tuple[ str, ... ]: 

85 return ( 

86 f"❌ {self}", 

87 "", 

88 "Run 'copier copy gh:emcd/agents-common' to configure agents." 

89 ) 

90 

91 

92class ConfigurationInvalidity( Omnierror, ValueError ): 

93 ''' Base configuration data invalidity. ''' 

94 

95 def __init__( self, reason: __.Absential[ str | Exception ] = __.absent ): 

96 if __.is_absent( reason ): message = "Invalid configuration." 96 ↛ 98line 96 didn't jump to line 98 because

97 else: message = f"Invalid configuration: {reason}" 

98 super( ).__init__( message ) 

99 

100 

101class ContentAbsence( Omnierror, FileNotFoundError ): 

102 ''' Content file absence. ''' 

103 

104 def __init__( self, content_type: str, content_name: str, coder: str ): 

105 message = ( 

106 f"No {content_type} content found for {coder}: {content_name}" ) 

107 super( ).__init__( message ) 

108 

109 

110class FileOperationFailure( Omnierror, OSError ): 

111 ''' File or directory operation failure. ''' 

112 

113 def __init__( self, path: __.Path, operation: str = "access file" ): 

114 message = f"Failed to {operation}: {path}" 

115 super( ).__init__( message ) 

116 

117 

118class InstructionSourceInvalidity( Omnierror, ValueError ): 

119 ''' Instruction source configuration invalidity. ''' 

120 

121 

122class InstructionSourceFieldAbsence( InstructionSourceInvalidity ): 

123 ''' Instruction source 'source' field absence. ''' 

124 

125 def __init__( self ): 

126 message = "Instruction source missing required 'source' field." 

127 super( ).__init__( message ) 

128 

129 

130class InstructionFilesConfigurationInvalidity( 

131 InstructionSourceInvalidity 

132): 

133 ''' Instruction files configuration format invalidity. ''' 

134 

135 def __init__( self ): 

136 message = "Instruction 'files' configuration must be a mapping." 

137 super( ).__init__( message ) 

138 

139 

140class ContextInvalidity( Omnierror, TypeError ): 

141 ''' Invalid execution context. ''' 

142 

143 def __init__( self ): 

144 message = "Invalid execution context: expected agentsmgr.cli.Globals" 

145 super( ).__init__( message ) 

146 

147 

148class DataSourceInvalidity( Omnierror, ValueError ): 

149 ''' Data source structure invalidity. ''' 

150 

151 def __init__( 

152 self, location: __.Path, missing_directories: tuple[ str, ... ] 

153 ) -> None: 

154 self.location = location 

155 self.missing_directories = missing_directories 

156 directories_list = ", ".join( missing_directories ) 

157 message = ( 

158 f"Invalid data source structure at {location}: " 

159 f"missing required directories: {directories_list}" ) 

160 super( ).__init__( message ) 

161 

162 def render_as_markdown( self ) -> tuple[ str, ... ]: 

163 ''' Renders data source invalidity with helpful guidance. ''' 

164 lines = [ "## Error: Invalid Data Source Structure" ] 

165 lines.append( "" ) 

166 lines.append( 

167 "The data source location does not contain the expected " 

168 "directory structure:" ) 

169 lines.append( "" ) 

170 lines.append( f" {self.location}" ) 

171 lines.append( "" ) 

172 lines.append( "**Missing required directories:**" ) 

173 lines.extend( 

174 f"- `{directory}`" for directory in self.missing_directories ) 

175 lines.append( "" ) 

176 lines.append( 

177 "Data sources should contain structured directories for " 

178 "configurations, contents, and templates." ) 

179 return tuple( lines ) 

180 

181 

182class DataSourceNoSupport( Omnierror, ValueError ): 

183 ''' Unsupported data source format error. ''' 

184 

185 def __init__( self, source_spec: str ): 

186 message = f"Unsupported source format: {source_spec}" 

187 super( ).__init__( message ) 

188 

189 

190class GlobalsPopulationFailure( Omnierror, OSError ): 

191 ''' Global settings population failure. ''' 

192 

193 def __init__( self, source: __.Path, target: __.Path ): 

194 message = f"Failed to populate global file from {source} to {target}" 

195 super( ).__init__( message ) 

196 

197 

198class MemoryFileAbsence( Omnierror, FileNotFoundError ): 

199 ''' Memory file absence. 

200 

201 Raised when project memory file (AGENTS.md) does not exist 

202 but memory symlinks need to be created. 

203 ''' 

204 

205 def __init__( self, location: __.Path ) -> None: 

206 self.location = location 

207 super( ).__init__( f"Memory file not found: {location}" ) 

208 

209 def render_as_markdown( self ) -> tuple[ str, ... ]: 

210 ''' Renders memory file absence with helpful guidance. ''' 

211 lines = [ "## Error: Memory File Not Found" ] 

212 lines.append( "" ) 

213 lines.append( 

214 "The project memory file does not exist at the expected " 

215 "location:" ) 

216 lines.append( "" ) 

217 lines.append( f" {self.location}" ) 

218 lines.append( "" ) 

219 lines.append( 

220 "Memory files provide project-specific conventions and " 

221 "context to AI coding assistants. Create this file before " 

222 "running `agentsmgr populate`." ) 

223 lines.append( "" ) 

224 lines.append( 

225 "**Suggested action**: Create " 

226 "`.auxiliary/agents/agents.md` with " 

227 "project-specific conventions, or copy from a template " 

228 "project." ) 

229 return tuple( lines ) 

230 

231 

232class TargetModeNoSupport( Omnierror, ValueError ): 

233 ''' Targeting mode lack of support. ''' 

234 

235 def __init__( self, coder: str, mode: str, reason: str = '' ): 

236 self.coder = coder 

237 self.mode = mode 

238 self.reason = reason 

239 message = ( 

240 f"The {coder} coder does not support {mode} targeting mode." ) 

241 if reason: message = f"{message} {reason}" 

242 super( ).__init__( message ) 

243 

244 def render_as_markdown( self ) -> tuple[ str, ... ]: 

245 ''' Renders targeting mode error with helpful guidance. ''' 

246 lines = [ 

247 "## Error: Unsupported Targeting Mode", 

248 "", 

249 f"The **{self.coder}** coder does not support " 

250 f"**{self.mode}** targeting mode.", 

251 ] 

252 if self.reason: 

253 lines.extend( [ "", self.reason ] ) 

254 return tuple( lines ) 

255 

256 

257class TemplateError( Omnierror, ValueError ): 

258 ''' Template processing error. ''' 

259 

260 def __init__( self, template_name: str ): 

261 super( ).__init__( f"Template error: {template_name}" ) 

262 

263 @classmethod 

264 def for_missing_template( 

265 cls, coder: str, item_type: str 

266 ) -> __.typx.Self: 

267 ''' Creates error for missing template. ''' 

268 return cls( f"no {item_type} template found for {coder}" ) 

269 

270 @classmethod 

271 def for_extension_parse( cls, template_name: str ) -> __.typx.Self: 

272 ''' Creates error for extension parsing failure. ''' 

273 return cls( f"cannot determine output extension for {template_name}" ) 

274 

275 

276class ToolSpecificationInvalidity( ConfigurationInvalidity ): 

277 ''' Tool specification invalidity. ''' 

278 

279 def __init__( self, specification: __.typx.Any ): 

280 message = f"Unrecognized tool specification: {specification}" 

281 super( ).__init__( message ) 

282 

283 

284class ToolSpecificationTypeInvalidity( ConfigurationInvalidity ): 

285 ''' Tool specification type invalidity. ''' 

286 

287 def __init__( self, specification: __.typx.Any ): 

288 specification_type = type( specification ).__name__ 

289 message = ( 

290 f"Tool specification must be string or dict, got: " 

291 f"{specification_type}" ) 

292 super( ).__init__( message )