Coverage for sources/agentsmgr/exceptions.py: 47%
125 statements
« prev ^ index » next coverage.py v7.17.3, created at 2026-11-14 18:55 +0000
« prev ^ index » next coverage.py v7.17.3, created at 2026-11-14 18:55 +0000
1# vim: set filetype=python fileencoding=utf-8:
2# -*- coding: utf-8 -*-
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#============================================================================#
21''' Family of exceptions for package API. '''
24from . import __
27class Omniexception( __.immut.exceptions.Omniexception ):
28 ''' Base for all exceptions raised by package API. '''
31class Omnierror( Omniexception, Exception ):
32 ''' Base for error exceptions raised by package API. '''
34 def render_as_markdown( self ) -> tuple[ str, ... ]:
35 ''' Renders exception as Markdown lines for display. '''
36 return ( f"❌ {self}", )
39class UnexpectedError( Omnierror ):
40 ''' Unexpected failure escaping command handling.
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 '''
49 def __init__( self, exception: BaseException ):
50 self.exception = exception
51 super( ).__init__(
52 f"Unexpected {type( exception ).__name__}: {exception}" )
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 )
66class CoderAbsence( Omnierror, ValueError ):
67 ''' Coder absence in registry. '''
69 def __init__( self, coder: str ):
70 message = f"Coder not found in registry: {coder}"
71 super( ).__init__( message )
74class ConfigurationAbsence( Omnierror, FileNotFoundError ):
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}." )
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 )
92class ConfigurationInvalidity( Omnierror, ValueError ):
93 ''' Base configuration data invalidity. '''
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 )
101class ContentAbsence( Omnierror, FileNotFoundError ):
102 ''' Content file absence. '''
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 )
110class FileOperationFailure( Omnierror, OSError ):
111 ''' File or directory operation failure. '''
113 def __init__( self, path: __.Path, operation: str = "access file" ):
114 message = f"Failed to {operation}: {path}"
115 super( ).__init__( message )
118class InstructionSourceInvalidity( Omnierror, ValueError ):
119 ''' Instruction source configuration invalidity. '''
122class InstructionSourceFieldAbsence( InstructionSourceInvalidity ):
123 ''' Instruction source 'source' field absence. '''
125 def __init__( self ):
126 message = "Instruction source missing required 'source' field."
127 super( ).__init__( message )
130class InstructionFilesConfigurationInvalidity(
131 InstructionSourceInvalidity
132):
133 ''' Instruction files configuration format invalidity. '''
135 def __init__( self ):
136 message = "Instruction 'files' configuration must be a mapping."
137 super( ).__init__( message )
140class ContextInvalidity( Omnierror, TypeError ):
141 ''' Invalid execution context. '''
143 def __init__( self ):
144 message = "Invalid execution context: expected agentsmgr.cli.Globals"
145 super( ).__init__( message )
148class DataSourceInvalidity( Omnierror, ValueError ):
149 ''' Data source structure invalidity. '''
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 )
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 )
182class DataSourceNoSupport( Omnierror, ValueError ):
183 ''' Unsupported data source format error. '''
185 def __init__( self, source_spec: str ):
186 message = f"Unsupported source format: {source_spec}"
187 super( ).__init__( message )
190class GlobalsPopulationFailure( Omnierror, OSError ):
191 ''' Global settings population failure. '''
193 def __init__( self, source: __.Path, target: __.Path ):
194 message = f"Failed to populate global file from {source} to {target}"
195 super( ).__init__( message )
198class MemoryFileAbsence( Omnierror, FileNotFoundError ):
199 ''' Memory file absence.
201 Raised when project memory file (AGENTS.md) does not exist
202 but memory symlinks need to be created.
203 '''
205 def __init__( self, location: __.Path ) -> None:
206 self.location = location
207 super( ).__init__( f"Memory file not found: {location}" )
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 )
232class TargetModeNoSupport( Omnierror, ValueError ):
233 ''' Targeting mode lack of support. '''
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 )
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 )
257class TemplateError( Omnierror, ValueError ):
258 ''' Template processing error. '''
260 def __init__( self, template_name: str ):
261 super( ).__init__( f"Template error: {template_name}" )
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}" )
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}" )
276class ToolSpecificationInvalidity( ConfigurationInvalidity ):
277 ''' Tool specification invalidity. '''
279 def __init__( self, specification: __.typx.Any ):
280 message = f"Unrecognized tool specification: {specification}"
281 super( ).__init__( message )
284class ToolSpecificationTypeInvalidity( ConfigurationInvalidity ):
285 ''' Tool specification type invalidity. '''
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 )