scripts/enumerate_surface.pl

filter: Statementstmt 94.4% 153 / 162 Branchbran 75.0% 54 / 72 Conditioncond 94.1% 16 / 17 MC/DCmcdc 90.0% 9 / 10 Subroutinesub 100% 15 / 15 Podpod n/a totaltotal 89.4% 247 / 276 CC 47 SCAR 26.6
CC
47
Cov
89%
collect_surface
23.4
parse_file
17.2
git_sha
3.1
CRAP 14.3
« blib/lib/SignalWire/Contexts.pm ↑ Summary blib/lib/SignalWire/Agent/AgentBase.pm »
1 #!/usr/bin/env perl
2 # enumerate_surface.pl — emit a JSON snapshot of the Perl SDK's public API in
3 # the same shape as the porting-sdk's python_surface.json.
4 #
5 # Layer B symbol-level surface audit: walk lib/SignalWire/**/*.pm, extract
6 # every `package Foo::Bar;` block and the `sub name {` declarations within
7 # it, then translate Perl-native names to Python-reference names so
8 # diff_port_surface.py can line up the two surfaces without false positives.
9 #
10 # Translation rules (see the task spec):
11 # * package SignalWire::Agent::AgentBase -> module signalwire.core.agent_base,
12 # class AgentBase
13 # * sub foo -> method foo (already snake_case)
14 # * sub new -> method __init__
15 # * sub _foo -> skipped (Perl convention: private)
16 # * AgentBase in Perl is one big class, but Python splits it across mixins
17 # (prompt/tool/ai_config/auth/skill/web/state/serverless/mcp_server).
18 # The translation table below routes each Perl sub to the right Python
19 # home so the diff is meaningful instead of noise.
20 #
21 # Usage:
22 # perl scripts/enumerate_surface.pl # write port_surface.json
23 # perl scripts/enumerate_surface.pl --output surface.json
24 # perl scripts/enumerate_surface.pl --stdout # dump to stdout
25 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
26 1 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
27 1 ▶use JSON ();
Subroutine BEGIN: called CC=1 SCAR=0.0
28 1 ▶use File::Find ();
Subroutine BEGIN: called CC=1 SCAR=0.0
29 1 ▶use File::Spec ();
Subroutine BEGIN: called CC=1 SCAR=0.0
30 1 ▶use Getopt::Long ();
Subroutine BEGIN: called CC=1 SCAR=0.0
31 1 ▶use FindBin ();
Subroutine BEGIN: called CC=1 SCAR=0.0
32  
33 # -------------------------------------------------------------------------
34 # Configuration
35 # -------------------------------------------------------------------------
36  
37 1 my $REPO_ROOT = File::Spec->rel2abs(File::Spec->catdir($FindBin::Bin, '..'));
38 1 my $LIB_ROOT = File::Spec->catdir($REPO_ROOT, 'lib', 'SignalWire');
39  
40 1 my $output_path = File::Spec->catfile($REPO_ROOT, 'port_surface.json');
41 1 my $to_stdout = 0;
42 1 ▶Getopt::Long::GetOptions(
Branch: 1 branch
BranchTrueFalseTotal
&Getopt::Long::GetOptions("output=s", \$output_path, "stdout", \$to_stdout) or die "usage: $0 [--output PATH] [--stdout]\n" 1 0 1
43 'output=s' => \$output_path,
44 'stdout' => \$to_stdout,
45 ) or die "usage: $0 [--output PATH] [--stdout]\n";
46  
47 # -------------------------------------------------------------------------
48 # Package -> Python module/class translation
49 # -------------------------------------------------------------------------
50 #
51 # For packages whose Perl-native layout matches a single Python module, this
52 # is a straight map. For AgentBase (a fat Moo class that Python splits into
53 # mixins) the mapping is per-method and handled below.
54 #
55 1 my %PACKAGE_TO_PY = (
56 # Entry point (SignalWire.pm acts as the package-level loader)
57 'SignalWire' => { module => 'signalwire', class => undef },
58  
59 # Core orchestration
60 'SignalWire::Agent::AgentBase' => { module => 'signalwire.core.agent_base', class => 'AgentBase' },
61 'SignalWire::SWML::Service' => { module => 'signalwire.core.swml_service', class => 'SWMLService' },
62 'SignalWire::SWAIG::FunctionResult' => { module => 'signalwire.core.function_result', class => 'FunctionResult' },
63 'SignalWire::DataMap' => { module => 'signalwire.core.data_map', class => 'DataMap' },
64 'SignalWire::Security::SessionManager' => { module => 'signalwire.core.security.session_manager', class => 'SessionManager' },
65 'SignalWire::Security::WebhookValidator' => { module => 'signalwire.core.security.webhook_validator', class => undef },
66 'SignalWire::Security::WebhookMiddleware' => { module => 'signalwire.core.security.webhook_middleware', class => undef },
67 'SignalWire::Server::AgentServer' => { module => 'signalwire.agent_server', class => 'AgentServer' },
68 'SignalWire::Logging' => { module => 'signalwire.core.logging_config', class => undef },
69 'SignalWire::Core::LoggingConfig' => { module => 'signalwire.core.logging_config', class => undef },
70 'SignalWire::Utils' => { module => 'signalwire.utils', class => undef },
71 'SignalWire::Utils::UrlValidator' => { module => 'signalwire.utils.url_validator', class => undef },
72  
73 # Contexts (multiple classes in one .pm)
74 'SignalWire::Contexts' => { module => 'signalwire.core.contexts', class => undef },
75 'SignalWire::Contexts::Context' => { module => 'signalwire.core.contexts', class => 'Context' },
76 'SignalWire::Contexts::ContextBuilder' => { module => 'signalwire.core.contexts', class => 'ContextBuilder' },
77 'SignalWire::Contexts::GatherInfo' => { module => 'signalwire.core.contexts', class => 'GatherInfo' },
78 'SignalWire::Contexts::GatherQuestion' => { module => 'signalwire.core.contexts', class => 'GatherQuestion' },
79 'SignalWire::Contexts::Step' => { module => 'signalwire.core.contexts', class => 'Step' },
80  
81 # Skills
82 'SignalWire::Skills::SkillBase' => { module => 'signalwire.core.skill_base', class => 'SkillBase' },
83 'SignalWire::Skills::SkillManager' => { module => 'signalwire.core.skill_manager', class => 'SkillManager' },
84 'SignalWire::Skills::SkillRegistry' => { module => 'signalwire.skills.registry', class => 'SkillRegistry' },
85  
86 # Built-in skills: each Perl package maps to the equivalent
87 # signalwire.skills.<name>.skill module + Skill class.
88 'SignalWire::Skills::Builtin::Datetime' => { module => 'signalwire.skills.datetime.skill', class => 'DateTimeSkill' },
89 'SignalWire::Skills::Builtin::Math' => { module => 'signalwire.skills.math.skill', class => 'MathSkill' },
90 'SignalWire::Skills::Builtin::WebSearch' => { module => 'signalwire.skills.web_search.skill', class => 'WebSearchSkill' },
91 'SignalWire::Skills::Builtin::WikipediaSearch' => { module => 'signalwire.skills.wikipedia_search.skill', class => 'WikipediaSearchSkill' },
92 'SignalWire::Skills::Builtin::WeatherApi' => { module => 'signalwire.skills.weather_api.skill', class => 'WeatherApiSkill' },
93 'SignalWire::Skills::Builtin::Joke' => { module => 'signalwire.skills.joke.skill', class => 'JokeSkill' },
94 'SignalWire::Skills::Builtin::Spider' => { module => 'signalwire.skills.spider.skill', class => 'SpiderSkill' },
95 'SignalWire::Skills::Builtin::Datasphere' => { module => 'signalwire.skills.datasphere.skill', class => 'DataSphereSkill' },
96 'SignalWire::Skills::Builtin::DatasphereServerless' => { module => 'signalwire.skills.datasphere_serverless.skill', class => 'DataSphereServerlessSkill' },
97 'SignalWire::Skills::Builtin::NativeVectorSearch' => { module => 'signalwire.skills.native_vector_search.skill', class => 'NativeVectorSearchSkill' },
98 'SignalWire::Skills::Builtin::ApiNinjasTrivia' => { module => 'signalwire.skills.api_ninjas_trivia.skill', class => 'ApiNinjasTriviaSkill' },
99 'SignalWire::Skills::Builtin::SwmlTransfer' => { module => 'signalwire.skills.swml_transfer.skill', class => 'SWMLTransferSkill' },
100 'SignalWire::Skills::Builtin::GoogleMaps' => { module => 'signalwire.skills.google_maps.skill', class => 'GoogleMapsSkill' },
101 'SignalWire::Skills::Builtin::PlayBackgroundFile' => { module => 'signalwire.skills.play_background_file.skill', class => 'PlayBackgroundFileSkill' },
102 'SignalWire::Skills::Builtin::InfoGatherer' => { module => 'signalwire.skills.info_gatherer.skill', class => 'InfoGathererSkill' },
103 'SignalWire::Skills::Builtin::McpGateway' => { module => 'signalwire.skills.mcp_gateway.skill', class => 'MCPGatewaySkill' },
104 'SignalWire::Skills::Builtin::ClaudeSkills' => { module => 'signalwire.skills.claude_skills.skill', class => 'ClaudeSkillsSkill' },
105 # CustomSkills has no direct Python equivalent — it's a Perl-only harness
106 # for loading user-supplied skill packages. Report it under the registry
107 # namespace with a port-only class; it will surface in PORT_ADDITIONS.md.
108 'SignalWire::Skills::Builtin::CustomSkills' => { module => 'signalwire.skills.registry', class => 'CustomSkills' },
109  
110 # Prefabs
111 'SignalWire::Prefabs::Concierge' => { module => 'signalwire.prefabs.concierge', class => 'ConciergeAgent' },
112 'SignalWire::Prefabs::FAQBot' => { module => 'signalwire.prefabs.faq_bot', class => 'FAQBotAgent' },
113 'SignalWire::Prefabs::InfoGatherer' => { module => 'signalwire.prefabs.info_gatherer', class => 'InfoGathererAgent' },
114 'SignalWire::Prefabs::Receptionist' => { module => 'signalwire.prefabs.receptionist', class => 'ReceptionistAgent' },
115 'SignalWire::Prefabs::Survey' => { module => 'signalwire.prefabs.survey', class => 'SurveyAgent' },
116  
117 # RELAY client
118 'SignalWire::Relay::Client' => { module => 'signalwire.relay.client', class => 'RelayClient' },
119 'SignalWire::Relay::Call' => { module => 'signalwire.relay.call', class => 'Call' },
120 'SignalWire::Relay::Message' => { module => 'signalwire.relay.message', class => 'Message' },
121 'SignalWire::Relay::Action' => { module => 'signalwire.relay.call', class => 'Action' },
122 'SignalWire::Relay::Action::AI' => { module => 'signalwire.relay.call', class => 'AIAction' },
123 'SignalWire::Relay::Action::Collect' => { module => 'signalwire.relay.call', class => 'CollectAction' },
124 'SignalWire::Relay::Action::StandaloneCollect' => { module => 'signalwire.relay.call', class => 'StandaloneCollectAction' },
125 'SignalWire::Relay::Action::Detect' => { module => 'signalwire.relay.call', class => 'DetectAction' },
126 'SignalWire::Relay::Action::Fax' => { module => 'signalwire.relay.call', class => 'FaxAction' },
127 'SignalWire::Relay::Action::Pay' => { module => 'signalwire.relay.call', class => 'PayAction' },
128 'SignalWire::Relay::Action::Play' => { module => 'signalwire.relay.call', class => 'PlayAction' },
129 'SignalWire::Relay::Action::Record' => { module => 'signalwire.relay.call', class => 'RecordAction' },
130 'SignalWire::Relay::Action::Stream' => { module => 'signalwire.relay.call', class => 'StreamAction' },
131 'SignalWire::Relay::Action::Tap' => { module => 'signalwire.relay.call', class => 'TapAction' },
132 'SignalWire::Relay::Action::Transcribe' => { module => 'signalwire.relay.call', class => 'TranscribeAction' },
133 'SignalWire::Relay::Event' => { module => 'signalwire.relay.event', class => 'RelayEvent' },
134 'SignalWire::Relay::Event::CallState' => { module => 'signalwire.relay.event', class => 'CallStateEvent' },
135 'SignalWire::Relay::Event::CallReceive' => { module => 'signalwire.relay.event', class => 'CallReceiveEvent' },
136 'SignalWire::Relay::Event::CallDial' => { module => 'signalwire.relay.event', class => 'DialEvent' },
137 'SignalWire::Relay::Event::CallConnect' => { module => 'signalwire.relay.event', class => 'ConnectEvent' },
138 'SignalWire::Relay::Event::CallPlay' => { module => 'signalwire.relay.event', class => 'PlayEvent' },
139 'SignalWire::Relay::Event::CallRecord' => { module => 'signalwire.relay.event', class => 'RecordEvent' },
140 'SignalWire::Relay::Event::CallCollect' => { module => 'signalwire.relay.event', class => 'CollectEvent' },
141 'SignalWire::Relay::Event::CallDetect' => { module => 'signalwire.relay.event', class => 'DetectEvent' },
142 'SignalWire::Relay::Event::CallFax' => { module => 'signalwire.relay.event', class => 'FaxEvent' },
143 'SignalWire::Relay::Event::CallTap' => { module => 'signalwire.relay.event', class => 'TapEvent' },
144 'SignalWire::Relay::Event::CallStream' => { module => 'signalwire.relay.event', class => 'StreamEvent' },
145 'SignalWire::Relay::Event::CallTranscribe' => { module => 'signalwire.relay.event', class => 'TranscribeEvent' },
146 'SignalWire::Relay::Event::CallPay' => { module => 'signalwire.relay.event', class => 'PayEvent' },
147 'SignalWire::Relay::Event::CallSendDigits' => { module => 'signalwire.relay.event', class => 'SendDigitsEvent' },
148 'SignalWire::Relay::Event::CallRefer' => { module => 'signalwire.relay.event', class => 'ReferEvent' },
149 'SignalWire::Relay::Event::Conference' => { module => 'signalwire.relay.event', class => 'ConferenceEvent' },
150 'SignalWire::Relay::Event::CallAI' => { module => 'signalwire.relay.event', class => 'CallingErrorEvent' },
151 'SignalWire::Relay::Event::MessageReceive' => { module => 'signalwire.relay.event', class => 'MessageReceiveEvent' },
152 'SignalWire::Relay::Event::MessageState' => { module => 'signalwire.relay.event', class => 'MessageStateEvent' },
153 # Perl-only events: CallDisconnect, Conference subtypes, Authorization,
154 # plain Disconnect. Routed to relay.event so they surface in PORT_ADDITIONS.
155 'SignalWire::Relay::Event::CallDisconnect' => { module => 'signalwire.relay.event', class => 'CallDisconnectEvent' },
156 'SignalWire::Relay::Event::AuthorizationState' => { module => 'signalwire.relay.event', class => 'AuthorizationStateEvent' },
157 'SignalWire::Relay::Event::Disconnect' => { module => 'signalwire.relay.event', class => 'DisconnectEvent' },
158 'SignalWire::Relay::Constants' => { module => 'signalwire.relay.client', class => 'Constants' },
159  
160 # REST client
161 'SignalWire::REST::RestClient' => { module => 'signalwire.rest.client', class => 'RestClient' },
162 'SignalWire::REST::HttpClient' => { module => 'signalwire.rest._base', class => 'HttpClient' },
163 'SignalWire::REST::HttpClient::Error' => { module => 'signalwire.rest._base', class => 'SignalWireRestError' },
164 'SignalWire::REST::Namespaces::Base' => { module => 'signalwire.rest._base', class => 'BaseResource' },
165 'SignalWire::REST::Namespaces::CrudResource' => { module => 'signalwire.rest._base', class => 'CrudResource' },
166 'SignalWire::REST::PhoneCallHandler' => { module => 'signalwire.rest.call_handler', class => 'PhoneCallHandler' },
167 'SignalWire::REST::Pagination' => { module => 'signalwire.rest._pagination', class => undef },
168 'SignalWire::REST::Pagination::PaginatedIterator' => { module => 'signalwire.rest._pagination', class => 'PaginatedIterator' },
169  
170 # REST: simple namespaces
171 'SignalWire::REST::Namespaces::Calling' => { module => 'signalwire.rest.namespaces.calling', class => 'CallingNamespace' },
172 'SignalWire::REST::Namespaces::Chat' => { module => 'signalwire.rest.namespaces.chat', class => 'ChatResource' },
173 'SignalWire::REST::Namespaces::PubSub' => { module => 'signalwire.rest.namespaces.pubsub', class => 'PubSubResource' },
174 'SignalWire::REST::Namespaces::PhoneNumbers' => { module => 'signalwire.rest.namespaces.phone_numbers', class => 'PhoneNumbersResource' },
175 'SignalWire::REST::Namespaces::Datasphere' => { module => 'signalwire.rest.namespaces.datasphere', class => 'DatasphereNamespace' },
176 'SignalWire::REST::Namespaces::Datasphere::Documents' => { module => 'signalwire.rest.namespaces.datasphere', class => 'DatasphereDocuments' },
177 'SignalWire::REST::Namespaces::Project' => { module => 'signalwire.rest.namespaces.project', class => 'ProjectNamespace' },
178 'SignalWire::REST::Namespaces::Project::Tokens' => { module => 'signalwire.rest.namespaces.project', class => 'ProjectTokens' },
179  
180 # REST: multi-package Resources.pm splits into several namespaces
181 'SignalWire::REST::Namespaces::Resources' => { module => 'signalwire.rest._base', class => undef },
182 'SignalWire::REST::Namespaces::Addresses' => { module => 'signalwire.rest.namespaces.addresses', class => 'AddressesResource' },
183 'SignalWire::REST::Namespaces::Queues' => { module => 'signalwire.rest.namespaces.queues', class => 'QueuesResource' },
184 'SignalWire::REST::Namespaces::Recordings' => { module => 'signalwire.rest.namespaces.recordings', class => 'RecordingsResource' },
185 'SignalWire::REST::Namespaces::NumberGroups' => { module => 'signalwire.rest.namespaces.number_groups', class => 'NumberGroupsResource' },
186 'SignalWire::REST::Namespaces::VerifiedCallers' => { module => 'signalwire.rest.namespaces.verified_callers', class => 'VerifiedCallersResource' },
187 'SignalWire::REST::Namespaces::SipProfile' => { module => 'signalwire.rest.namespaces.sip_profile', class => 'SipProfileResource' },
188 'SignalWire::REST::Namespaces::Lookup' => { module => 'signalwire.rest.namespaces.lookup', class => 'LookupResource' },
189 'SignalWire::REST::Namespaces::ShortCodes' => { module => 'signalwire.rest.namespaces.short_codes', class => 'ShortCodesResource' },
190 'SignalWire::REST::Namespaces::ImportedNumbers' => { module => 'signalwire.rest.namespaces.imported_numbers', class => 'ImportedNumbersResource' },
191 'SignalWire::REST::Namespaces::MFA' => { module => 'signalwire.rest.namespaces.mfa', class => 'MfaResource' },
192  
193 # REST: Logs.pm — multi-package
194 'SignalWire::REST::Namespaces::Logs' => { module => 'signalwire.rest.namespaces.logs', class => 'LogsNamespace' },
195 'SignalWire::REST::Namespaces::Logs::Messages' => { module => 'signalwire.rest.namespaces.logs', class => 'MessageLogs' },
196 'SignalWire::REST::Namespaces::Logs::Voice' => { module => 'signalwire.rest.namespaces.logs', class => 'VoiceLogs' },
197 'SignalWire::REST::Namespaces::Logs::Fax' => { module => 'signalwire.rest.namespaces.logs', class => 'FaxLogs' },
198 'SignalWire::REST::Namespaces::Logs::Conferences' => { module => 'signalwire.rest.namespaces.logs', class => 'ConferenceLogs' },
199  
200 # REST: Registry.pm — multi-package
201 'SignalWire::REST::Namespaces::Registry' => { module => 'signalwire.rest.namespaces.registry', class => 'RegistryNamespace' },
202 'SignalWire::REST::Namespaces::Registry::Brands' => { module => 'signalwire.rest.namespaces.registry', class => 'RegistryBrands' },
203 'SignalWire::REST::Namespaces::Registry::Campaigns' => { module => 'signalwire.rest.namespaces.registry', class => 'RegistryCampaigns' },
204 'SignalWire::REST::Namespaces::Registry::Orders' => { module => 'signalwire.rest.namespaces.registry', class => 'RegistryOrders' },
205 'SignalWire::REST::Namespaces::Registry::Numbers' => { module => 'signalwire.rest.namespaces.registry', class => 'RegistryNumbers' },
206  
207 # REST: Compat.pm — multi-package
208 'SignalWire::REST::Namespaces::Compat' => { module => 'signalwire.rest.namespaces.compat', class => 'CompatNamespace' },
209 'SignalWire::REST::Namespaces::Compat::Accounts' => { module => 'signalwire.rest.namespaces.compat', class => 'CompatAccounts' },
210 'SignalWire::REST::Namespaces::Compat::Calls' => { module => 'signalwire.rest.namespaces.compat', class => 'CompatCalls' },
211 'SignalWire::REST::Namespaces::Compat::Messages' => { module => 'signalwire.rest.namespaces.compat', class => 'CompatMessages' },
212 'SignalWire::REST::Namespaces::Compat::Faxes' => { module => 'signalwire.rest.namespaces.compat', class => 'CompatFaxes' },
213 'SignalWire::REST::Namespaces::Compat::Conferences' => { module => 'signalwire.rest.namespaces.compat', class => 'CompatConferences' },
214 'SignalWire::REST::Namespaces::Compat::PhoneNumbers' => { module => 'signalwire.rest.namespaces.compat', class => 'CompatPhoneNumbers' },
215 'SignalWire::REST::Namespaces::Compat::Applications' => { module => 'signalwire.rest.namespaces.compat', class => 'CompatApplications' },
216 'SignalWire::REST::Namespaces::Compat::LamlBins' => { module => 'signalwire.rest.namespaces.compat', class => 'CompatLamlBins' },
217 'SignalWire::REST::Namespaces::Compat::Queues' => { module => 'signalwire.rest.namespaces.compat', class => 'CompatQueues' },
218 'SignalWire::REST::Namespaces::Compat::Recordings' => { module => 'signalwire.rest.namespaces.compat', class => 'CompatRecordings' },
219 'SignalWire::REST::Namespaces::Compat::Transcriptions' => { module => 'signalwire.rest.namespaces.compat', class => 'CompatTranscriptions' },
220 'SignalWire::REST::Namespaces::Compat::Tokens' => { module => 'signalwire.rest.namespaces.compat', class => 'CompatTokens' },
221  
222 # REST: Fabric.pm — multi-package (Python surface under rest.namespaces.fabric)
223 'SignalWire::REST::Namespaces::Fabric' => { module => 'signalwire.rest.namespaces.fabric', class => 'FabricNamespace' },
224 'SignalWire::REST::Namespaces::Fabric::Addresses' => { module => 'signalwire.rest.namespaces.fabric', class => 'FabricAddresses' },
225 'SignalWire::REST::Namespaces::Fabric::Subscribers' => { module => 'signalwire.rest.namespaces.fabric', class => 'SubscribersResource' },
226 'SignalWire::REST::Namespaces::Fabric::Tokens' => { module => 'signalwire.rest.namespaces.fabric', class => 'FabricTokens' },
227 'SignalWire::REST::Namespaces::Fabric::GenericResources' => { module => 'signalwire.rest.namespaces.fabric', class => 'GenericResources' },
228 'SignalWire::REST::Namespaces::Fabric::SwmlWebhooks' => { module => 'signalwire.rest.namespaces.fabric', class => 'SwmlWebhooksResource' },
229 # Other Fabric::* subpackages are helpers that have no 1:1 Python
230 # equivalent; they'll land in PORT_ADDITIONS.md under rest.namespaces.fabric.
231 'SignalWire::REST::Namespaces::Fabric::Resource' => { module => 'signalwire.rest.namespaces.fabric', class => 'FabricResource' },
232 'SignalWire::REST::Namespaces::Fabric::AutoMaterializedWebhook' => { module => 'signalwire.rest.namespaces.fabric', class => 'AutoMaterializedWebhook' },
233 'SignalWire::REST::Namespaces::Fabric::CxmlWebhooks' => { module => 'signalwire.rest.namespaces.fabric', class => 'CxmlWebhooksResource' },
234 'SignalWire::REST::Namespaces::Fabric::ResourcePUT' => { module => 'signalwire.rest.namespaces.fabric', class => 'FabricResourcePUT' },
235 'SignalWire::REST::Namespaces::Fabric::CallFlows' => { module => 'signalwire.rest.namespaces.fabric', class => 'CallFlowsResource' },
236 'SignalWire::REST::Namespaces::Fabric::ConferenceRooms' => { module => 'signalwire.rest.namespaces.fabric', class => 'ConferenceRoomsResource' },
237 'SignalWire::REST::Namespaces::Fabric::CxmlApplications' => { module => 'signalwire.rest.namespaces.fabric', class => 'CxmlApplicationsResource' },
238  
239 # REST: Video.pm — multi-package
240 'SignalWire::REST::Namespaces::Video' => { module => 'signalwire.rest.namespaces.video', class => 'VideoNamespace' },
241 'SignalWire::REST::Namespaces::Video::Rooms' => { module => 'signalwire.rest.namespaces.video', class => 'VideoRooms' },
242 'SignalWire::REST::Namespaces::Video::RoomTokens' => { module => 'signalwire.rest.namespaces.video', class => 'VideoRoomTokens' },
243 'SignalWire::REST::Namespaces::Video::RoomSessions' => { module => 'signalwire.rest.namespaces.video', class => 'VideoRoomSessions' },
244 'SignalWire::REST::Namespaces::Video::RoomRecordings' => { module => 'signalwire.rest.namespaces.video', class => 'VideoRoomRecordings' },
245 'SignalWire::REST::Namespaces::Video::Conferences' => { module => 'signalwire.rest.namespaces.video', class => 'VideoConferences' },
246 'SignalWire::REST::Namespaces::Video::ConferenceTokens' => { module => 'signalwire.rest.namespaces.video', class => 'VideoConferenceTokens' },
247 'SignalWire::REST::Namespaces::Video::Streams' => { module => 'signalwire.rest.namespaces.video', class => 'VideoStreams' },
248  
249 # SWML
250 'SignalWire::SWML::Document' => { module => 'signalwire.core.swml_builder', class => 'SWMLBuilder' },
251 'SignalWire::SWML::Schema' => { module => 'signalwire.utils.schema_utils', class => 'SchemaUtils' },
252  
253 # POM — typed Prompt Object Model. Python lives in ``signalwire.pom.pom``;
254 # Perl mirrors the same shape under ``SignalWire::POM::*`` and projects
255 # both classes back to the canonical Python paths.
256 'SignalWire::POM::PromptObjectModel' => { module => 'signalwire.pom.pom', class => 'PromptObjectModel' },
257 'SignalWire::POM::Section' => { module => 'signalwire.pom.pom', class => 'Section' },
258 );
259  
260 # -------------------------------------------------------------------------
261 # AgentBase method -> Python module/class router.
262 #
263 # In the Python SDK, AgentBase inherits from many mixins. Each mixin owns a
264 # slice of the public API. The Perl port flattens all of this into one
265 # SignalWire::Agent::AgentBase package, so at enumeration time we must
266 # re-project each method onto its Python home. This is the only way the
267 # diff tool can reason about surface parity.
268 # -------------------------------------------------------------------------
269 1 my %AGENTBASE_METHOD_TO_PY = (
270 # Stays on AgentBase itself
271 'new' => { module => 'signalwire.core.agent_base', class => 'AgentBase', method => '__init__' },
272 'get_name' => { module => 'signalwire.core.agent_base', class => 'AgentBase', method => 'get_name' },
273 'get_full_url' => { module => 'signalwire.core.agent_base', class => 'AgentBase', method => 'get_full_url' },
274 'set_web_hook_url' => { module => 'signalwire.core.agent_base', class => 'AgentBase', method => 'set_web_hook_url' },
275 'set_post_prompt_url' => { module => 'signalwire.core.agent_base', class => 'AgentBase', method => 'set_post_prompt_url' },
276 'add_pre_answer_verb' => { module => 'signalwire.core.agent_base', class => 'AgentBase', method => 'add_pre_answer_verb' },
277 'add_post_answer_verb' => { module => 'signalwire.core.agent_base', class => 'AgentBase', method => 'add_post_answer_verb' },
278 'add_post_ai_verb' => { module => 'signalwire.core.agent_base', class => 'AgentBase', method => 'add_post_ai_verb' },
279 'clear_pre_answer_verbs' => { module => 'signalwire.core.agent_base', class => 'AgentBase', method => 'clear_pre_answer_verbs' },
280 'clear_post_answer_verbs' => { module => 'signalwire.core.agent_base', class => 'AgentBase', method => 'clear_post_answer_verbs' },
281 'clear_post_ai_verbs' => { module => 'signalwire.core.agent_base', class => 'AgentBase', method => 'clear_post_ai_verbs' },
282 'add_swaig_query_params' => { module => 'signalwire.core.agent_base', class => 'AgentBase', method => 'add_swaig_query_params' },
283 'clear_swaig_query_params' => { module => 'signalwire.core.agent_base', class => 'AgentBase', method => 'clear_swaig_query_params' },
284 'on_summary' => { module => 'signalwire.core.agent_base', class => 'AgentBase', method => 'on_summary' },
285 'on_debug_event' => { module => 'signalwire.core.agent_base', class => 'AgentBase', method => 'on_debug_event' },
286 'enable_sip_routing' => { module => 'signalwire.core.agent_base', class => 'AgentBase', method => 'enable_sip_routing' },
287 'register_sip_username' => { module => 'signalwire.core.agent_base', class => 'AgentBase', method => 'register_sip_username' },
288 'auto_map_sip_usernames' => { module => 'signalwire.core.agent_base', class => 'AgentBase', method => 'auto_map_sip_usernames' },
289 'add_answer_verb' => { module => 'signalwire.core.agent_base', class => 'AgentBase', method => 'add_answer_verb' },
290  
291 # PromptMixin
292 'set_prompt_text' => { module => 'signalwire.core.mixins.prompt_mixin', class => 'PromptMixin', method => 'set_prompt_text' },
293 'set_post_prompt' => { module => 'signalwire.core.mixins.prompt_mixin', class => 'PromptMixin', method => 'set_post_prompt' },
294 'prompt_add_section' => { module => 'signalwire.core.mixins.prompt_mixin', class => 'PromptMixin', method => 'prompt_add_section' },
295 'prompt_add_subsection' => { module => 'signalwire.core.mixins.prompt_mixin', class => 'PromptMixin', method => 'prompt_add_subsection' },
296 'prompt_add_to_section'=> { module => 'signalwire.core.mixins.prompt_mixin', class => 'PromptMixin', method => 'prompt_add_to_section' },
297 'prompt_has_section' => { module => 'signalwire.core.mixins.prompt_mixin', class => 'PromptMixin', method => 'prompt_has_section' },
298 'get_prompt' => { module => 'signalwire.core.mixins.prompt_mixin', class => 'PromptMixin', method => 'get_prompt' },
299 'define_contexts' => { module => 'signalwire.core.mixins.prompt_mixin', class => 'PromptMixin', method => 'define_contexts' },
300 'reset_contexts' => { module => 'signalwire.core.mixins.prompt_mixin', class => 'PromptMixin', method => 'reset_contexts' },
301 'contexts' => { module => 'signalwire.core.mixins.prompt_mixin', class => 'PromptMixin', method => 'contexts' },
302  
303 # ToolMixin
304 'define_tool' => { module => 'signalwire.core.mixins.tool_mixin', class => 'ToolMixin', method => 'define_tool' },
305 'register_swaig_function' => { module => 'signalwire.core.mixins.tool_mixin', class => 'ToolMixin', method => 'register_swaig_function' },
306 'define_tools' => { module => 'signalwire.core.mixins.tool_mixin', class => 'ToolMixin', method => 'define_tools' },
307 'on_function_call' => { module => 'signalwire.core.mixins.tool_mixin', class => 'ToolMixin', method => 'on_function_call' },
308  
309 # AIConfigMixin
310 'add_hint' => { module => 'signalwire.core.mixins.ai_config_mixin', class => 'AIConfigMixin', method => 'add_hint' },
311 'add_hints' => { module => 'signalwire.core.mixins.ai_config_mixin', class => 'AIConfigMixin', method => 'add_hints' },
312 'add_pattern_hint' => { module => 'signalwire.core.mixins.ai_config_mixin', class => 'AIConfigMixin', method => 'add_pattern_hint' },
313 'add_language' => { module => 'signalwire.core.mixins.ai_config_mixin', class => 'AIConfigMixin', method => 'add_language' },
314 'set_languages' => { module => 'signalwire.core.mixins.ai_config_mixin', class => 'AIConfigMixin', method => 'set_languages' },
315 'get_language_params' => { module => 'signalwire.core.mixins.ai_config_mixin', class => 'AIConfigMixin', method => 'get_language_params' },
316 'set_language_params' => { module => 'signalwire.core.mixins.ai_config_mixin', class => 'AIConfigMixin', method => 'set_language_params' },
317 'add_pronunciation' => { module => 'signalwire.core.mixins.ai_config_mixin', class => 'AIConfigMixin', method => 'add_pronunciation' },
318 'set_pronunciations' => { module => 'signalwire.core.mixins.ai_config_mixin', class => 'AIConfigMixin', method => 'set_pronunciations' },
319 'set_param' => { module => 'signalwire.core.mixins.ai_config_mixin', class => 'AIConfigMixin', method => 'set_param' },
320 'set_params' => { module => 'signalwire.core.mixins.ai_config_mixin', class => 'AIConfigMixin', method => 'set_params' },
321 'set_global_data' => { module => 'signalwire.core.mixins.ai_config_mixin', class => 'AIConfigMixin', method => 'set_global_data' },
322 'update_global_data' => { module => 'signalwire.core.mixins.ai_config_mixin', class => 'AIConfigMixin', method => 'update_global_data' },
323 'set_native_functions' => { module => 'signalwire.core.mixins.ai_config_mixin', class => 'AIConfigMixin', method => 'set_native_functions' },
324 'set_internal_fillers' => { module => 'signalwire.core.mixins.ai_config_mixin', class => 'AIConfigMixin', method => 'set_internal_fillers' },
325 'add_internal_filler' => { module => 'signalwire.core.mixins.ai_config_mixin', class => 'AIConfigMixin', method => 'add_internal_filler' },
326 'enable_debug_events' => { module => 'signalwire.core.mixins.ai_config_mixin', class => 'AIConfigMixin', method => 'enable_debug_events' },
327 'add_function_include' => { module => 'signalwire.core.mixins.ai_config_mixin', class => 'AIConfigMixin', method => 'add_function_include' },
328 'set_function_includes' => { module => 'signalwire.core.mixins.ai_config_mixin', class => 'AIConfigMixin', method => 'set_function_includes' },
329 'set_prompt_llm_params' => { module => 'signalwire.core.mixins.ai_config_mixin', class => 'AIConfigMixin', method => 'set_prompt_llm_params' },
330 'set_post_prompt_llm_params' => { module => 'signalwire.core.mixins.ai_config_mixin', class => 'AIConfigMixin', method => 'set_post_prompt_llm_params' },
331 'add_mcp_server' => { module => 'signalwire.core.mixins.ai_config_mixin', class => 'AIConfigMixin', method => 'add_mcp_server' },
332 'enable_mcp_server' => { module => 'signalwire.core.mixins.ai_config_mixin', class => 'AIConfigMixin', method => 'enable_mcp_server' },
333  
334 # SkillMixin
335 'add_skill' => { module => 'signalwire.core.mixins.skill_mixin', class => 'SkillMixin', method => 'add_skill' },
336 'remove_skill' => { module => 'signalwire.core.mixins.skill_mixin', class => 'SkillMixin', method => 'remove_skill' },
337 'list_skills' => { module => 'signalwire.core.mixins.skill_mixin', class => 'SkillMixin', method => 'list_skills' },
338 'has_skill' => { module => 'signalwire.core.mixins.skill_mixin', class => 'SkillMixin', method => 'has_skill' },
339  
340 # WebMixin
341 'run' => { module => 'signalwire.core.mixins.web_mixin', class => 'WebMixin', method => 'run' },
342 'serve' => { module => 'signalwire.core.mixins.web_mixin', class => 'WebMixin', method => 'serve' },
343 'manual_set_proxy_url' => { module => 'signalwire.core.mixins.web_mixin', class => 'WebMixin', method => 'manual_set_proxy_url' },
344 'set_dynamic_config_callback' => { module => 'signalwire.core.mixins.web_mixin', class => 'WebMixin', method => 'set_dynamic_config_callback' },
345  
346 # SWMLService (extract_sip_username lives here in Python)
347 'extract_sip_username' => { module => 'signalwire.core.swml_service', class => 'SWMLService', method => 'extract_sip_username' },
348  
349 # Port-only on AgentBase — will land in PORT_ADDITIONS.md
350 'render_swml' => { module => 'signalwire.core.agent_base', class => 'AgentBase', method => 'render_swml' },
351 'psgi_app' => { module => 'signalwire.core.agent_base', class => 'AgentBase', method => 'psgi_app' },
352 'set_answer_config' => { module => 'signalwire.core.agent_base', class => 'AgentBase', method => 'set_answer_config' },
353 'list_tool_names' => { module => 'signalwire.core.agent_base', class => 'AgentBase', method => 'list_tool_names' },
354 );
355  
356 # Package-scoped overrides for specific (package, sub) → (module, class, method)
357 # mappings. Used when the default (which preserves the sub's name and class
358 # membership) needs to be rerouted, e.g. Perl helpers that live in a different
359 # Python home, or when Perl had to rename to avoid a builtin.
360 1 my %METHOD_OVERRIDES = (
361 # SWMLService auth methods come from AuthMixin in Python.
362 'SignalWire::SWML::Service' => {
363 'validate_basic_auth' => { module => 'signalwire.core.mixins.auth_mixin', class => 'AuthMixin', method => 'validate_basic_auth' },
364 'get_basic_auth_credentials' => { module => 'signalwire.core.mixins.auth_mixin', class => 'AuthMixin', method => 'get_basic_auth_credentials' },
365 },
366  
367 # Perl renamed `delete` to `delete_<resource>` because `delete` is a
368 # core builtin keyword. Translate back to the Python name `delete`.
369 'SignalWire::REST::Namespaces::Recordings' => {
370 'delete_recording' => { module => 'signalwire.rest.namespaces.recordings', class => 'RecordingsResource', method => 'delete' },
371 },
372 'SignalWire::REST::Namespaces::Fabric::GenericResources' => {
373 'delete_resource' => { module => 'signalwire.rest.namespaces.fabric', class => 'GenericResources', method => 'delete' },
374 },
375 'SignalWire::REST::Namespaces::Compat::PhoneNumbers' => {
376 'delete_number' => { module => 'signalwire.rest.namespaces.compat', class => 'CompatPhoneNumbers', method => 'delete' },
377 },
378 'SignalWire::REST::Namespaces::Compat::Recordings' => {
379 'delete_recording' => { module => 'signalwire.rest.namespaces.compat', class => 'CompatRecordings', method => 'delete' },
380 },
381 'SignalWire::REST::Namespaces::Compat::Tokens' => {
382 'delete_token' => { module => 'signalwire.rest.namespaces.compat', class => 'CompatTokens', method => 'delete' },
383 },
384 'SignalWire::REST::Namespaces::Compat::Transcriptions' => {
385 'delete_transcription' => { module => 'signalwire.rest.namespaces.compat', class => 'CompatTranscriptions', method => 'delete' },
386 },
387 'SignalWire::REST::Namespaces::Project::Tokens' => {
388 'delete_token' => { module => 'signalwire.rest.namespaces.project', class => 'ProjectTokens', method => 'delete' },
389 },
390 'SignalWire::REST::Namespaces::Registry::Numbers' => {
391 'delete_number' => { module => 'signalwire.rest.namespaces.registry', class => 'RegistryNumbers', method => 'delete' },
392 },
393 'SignalWire::REST::Namespaces::Video::RoomRecordings' => {
394 'delete_recording' => { module => 'signalwire.rest.namespaces.video', class => 'VideoRoomRecordings', method => 'delete' },
395 },
396 'SignalWire::REST::Namespaces::Video::Streams' => {
397 'delete_stream' => { module => 'signalwire.rest.namespaces.video', class => 'VideoStreams', method => 'delete' },
398 },
399 # CrudResource base class's delete_resource maps to the Python `delete`.
400 'SignalWire::REST::Namespaces::CrudResource' => {
401 'delete_resource' => { module => 'signalwire.rest._base', class => 'CrudResource', method => 'delete' },
402 },
403 'SignalWire::REST::HttpClient' => {
404 'delete_request' => { module => 'signalwire.rest._base', class => 'HttpClient', method => 'delete' },
405 },
406  
407 # Perl uses `to_hash` where Python uses `to_dict`. Python hash-like
408 # APIs are dicts; the Perl convention is hashref, hence the name. For
409 # surface parity, translate back to the Python name.
410 'SignalWire::Contexts::Context' => {
411 'to_hash' => { module => 'signalwire.core.contexts', class => 'Context', method => 'to_dict' },
412 },
413 'SignalWire::Contexts::ContextBuilder' => {
414 'to_hash' => { module => 'signalwire.core.contexts', class => 'ContextBuilder', method => 'to_dict' },
415 },
416 'SignalWire::Contexts::GatherInfo' => {
417 'to_hash' => { module => 'signalwire.core.contexts', class => 'GatherInfo', method => 'to_dict' },
418 },
419 'SignalWire::Contexts::GatherQuestion' => {
420 'to_hash' => { module => 'signalwire.core.contexts', class => 'GatherQuestion', method => 'to_dict' },
421 },
422 'SignalWire::Contexts::Step' => {
423 'to_hash' => { module => 'signalwire.core.contexts', class => 'Step', method => 'to_dict' },
424 },
425 'SignalWire::SWAIG::FunctionResult' => {
426 'to_hash' => { module => 'signalwire.core.function_result', class => 'FunctionResult', method => 'to_dict' },
427 },
428 # POM Section/PromptObjectModel: same to_hash -> to_dict rename as the
429 # Contexts/FunctionResult families above; the underlying serialised
430 # shape is identical between languages.
431 'SignalWire::POM::Section' => {
432 'to_hash' => { module => 'signalwire.pom.pom', class => 'Section', method => 'to_dict' },
433 },
434 'SignalWire::POM::PromptObjectModel' => {
435 'to_hash' => { module => 'signalwire.pom.pom', class => 'PromptObjectModel', method => 'to_dict' },
436 },
437  
438 # SWML::Service auth methods come from AuthMixin in Python (declared
439 # above); ContextBuilder validate is an AgentBase-internal helper not
440 # surfaced in Python.
441  
442 # Logging helpers: Perl exports debug/info/warn/error as package-level
443 # functions; in Python they come via get_logger() -> logger.debug etc.
444 # The Perl module also has get_logger, so keep debug/info/warn/error
445 # recorded under logging_config where they currently are (they'll
446 # surface as port additions, which is fine).
447 );
448  
449 # Force implicit __init__ for packages whose Python equivalent records
450 # __init__ on the class (Python AST sees an explicit `def __init__`), but
451 # whose Perl class extends another Moo class so our is_moo_root detector
452 # doesn't flag them. This list was derived from which Python classes
453 # expose __init__ in python_surface.json.
454 1 my %FORCE_IMPLICIT_INIT = map { $_ => 1 } (
455 # REST core
456 'SignalWire::REST::RestClient',
457 'SignalWire::REST::HttpClient',
458 'SignalWire::REST::HttpClient::Error',
459 'SignalWire::REST::Namespaces::Base',
460  
461 # REST namespaces whose top-level class or resource declares __init__
462 'SignalWire::REST::Namespaces::Calling',
463 'SignalWire::REST::Namespaces::Chat',
464 'SignalWire::REST::Namespaces::PubSub',
465 'SignalWire::REST::Namespaces::PhoneNumbers',
466 'SignalWire::REST::Namespaces::Addresses',
467 'SignalWire::REST::Namespaces::Queues',
468 'SignalWire::REST::Namespaces::Recordings',
469 'SignalWire::REST::Namespaces::NumberGroups',
470 'SignalWire::REST::Namespaces::VerifiedCallers',
471 'SignalWire::REST::Namespaces::SipProfile',
472 'SignalWire::REST::Namespaces::Lookup',
473 'SignalWire::REST::Namespaces::ShortCodes',
474 'SignalWire::REST::Namespaces::ImportedNumbers',
475 'SignalWire::REST::Namespaces::MFA',
476 'SignalWire::REST::Namespaces::Logs',
477 'SignalWire::REST::Namespaces::Registry',
478 'SignalWire::REST::Namespaces::Compat',
479 'SignalWire::REST::Namespaces::Compat::Accounts',
480 'SignalWire::REST::Namespaces::Compat::PhoneNumbers',
481 'SignalWire::REST::Namespaces::Fabric',
482 'SignalWire::REST::Namespaces::Fabric::Tokens',
483 'SignalWire::REST::Namespaces::Datasphere',
484 'SignalWire::REST::Namespaces::Datasphere::Documents',
485 'SignalWire::REST::Namespaces::Video',
486 'SignalWire::REST::Namespaces::Project',
487 'SignalWire::REST::Namespaces::Project::Tokens',
488 'SignalWire::REST::Pagination::PaginatedIterator',
489  
490 # Server / security / skills
491 'SignalWire::Server::AgentServer',
492 'SignalWire::Security::SessionManager',
493 'SignalWire::Security::WebhookValidator',
494 'SignalWire::Security::WebhookMiddleware',
495 'SignalWire::Skills::SkillBase',
496 'SignalWire::Skills::SkillManager',
497 'SignalWire::Skills::SkillRegistry',
498  
499 # SWML
500 'SignalWire::SWML::Document', # SWMLBuilder in Python
501 'SignalWire::SWML::Service',
502 'SignalWire::SWML::Schema', # SchemaUtils in Python
503  
504 # Prefabs (Python records __init__ on each prefab agent)
505 'SignalWire::Prefabs::Concierge',
506 'SignalWire::Prefabs::FAQBot',
507 'SignalWire::Prefabs::InfoGatherer',
508 'SignalWire::Prefabs::Receptionist',
509 'SignalWire::Prefabs::Survey',
510  
511 # Skills that Python declares __init__ on the top-level Skill class
512 # (GoogleMaps, WebSearch have __init__ on the INNER helper class, not
513 # the skill itself — don't list those here).
514 'SignalWire::Skills::Builtin::ApiNinjasTrivia',
515 'SignalWire::Skills::Builtin::PlayBackgroundFile',
516 'SignalWire::Skills::Builtin::Spider',
517 'SignalWire::Skills::Builtin::WeatherApi',
518 );
519  
520 # Suppress implicit __init__ emission. Relay::Event subclasses and the
521 # Constants holder are dataclasses in Python: they don't expose __init__
522 # as a public method. Matching that keeps the diff meaningful.
523 1 my %SKIP_IMPLICIT_INIT = map { $_ => 1 } (
524 'SignalWire::Relay::Constants',
525 # Relay::Event and every Relay::Event::Foo subclass
526 'SignalWire::Relay::Event',
527 'SignalWire::Relay::Event::CallState',
528 'SignalWire::Relay::Event::CallReceive',
529 'SignalWire::Relay::Event::CallDial',
530 'SignalWire::Relay::Event::CallConnect',
531 'SignalWire::Relay::Event::CallDisconnect',
532 'SignalWire::Relay::Event::CallPlay',
533 'SignalWire::Relay::Event::CallRecord',
534 'SignalWire::Relay::Event::CallCollect',
535 'SignalWire::Relay::Event::CallDetect',
536 'SignalWire::Relay::Event::CallFax',
537 'SignalWire::Relay::Event::CallTap',
538 'SignalWire::Relay::Event::CallStream',
539 'SignalWire::Relay::Event::CallTranscribe',
540 'SignalWire::Relay::Event::CallPay',
541 'SignalWire::Relay::Event::CallSendDigits',
542 'SignalWire::Relay::Event::CallRefer',
543 'SignalWire::Relay::Event::Conference',
544 'SignalWire::Relay::Event::CallAI',
545 'SignalWire::Relay::Event::MessageReceive',
546 'SignalWire::Relay::Event::MessageState',
547 'SignalWire::Relay::Event::AuthorizationState',
548 'SignalWire::Relay::Event::Disconnect',
549  
550 # CLI-only container packages with no instantiable class contract
551 # (we don't emit them here, but listed for future use).
552 );
553  
554 # Subs to always skip: private helpers, Moo plumbing, __PACKAGE__ accessors.
555 1 my %SKIP_SUB = map { $_ => 1 } qw(
556 BUILD
557 BUILDARGS
558 DEMOLISH
559 DESTROY
560 import
561 AUTOLOAD
562 );
563  
564 # Filenames to exclude from the walk.
565 1 my %SKIP_FILE = ();
566  
567 # -------------------------------------------------------------------------
568 # Parser — one pass per file, tracking current package.
569 # -------------------------------------------------------------------------
570 68 ▶sub parse_file {
Subroutine parse_file: called CC=17 SCAR=28.4
571 68 my ($path) = @_;
572 68 ▶ open my $fh, '<', $path or die "open $path: $!";
Branch: 1 branch
BranchTrueFalseTotal
open my $fh, "<", $path or die "open ${path}: $!" 68 0 68
573 68 my @packages; # list of { name => ..., subs => [...], _seen => {...} }
574 my $current;
575 68 ▶ while (my $line = <$fh>) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined(my $line = readline $fh)) 13646 68 13714
576 13646 ▶ if ($line =~ /^\s*package\s+([A-Za-z_][\w:]*)\s*;/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($line =~ /^\s*package\s+([A-Za-z_][\w:]*)\s*;/) 169 13477 13646
577 169 my $pkg = $1;
578 169 $current = {
579 name => $pkg,
580 subs => [],
581 _seen => {},
582 uses_moo => 0,
583 has_extends => 0,
584 };
585 169 push @packages, $current;
586 169 next;
587 }
588 # Detect `use Moo;` / `use Moo::Role;`
589 13477 ▶ if ($line =~ /^\s*use\s+Moo(?:::Role)?\b/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($line =~ /^\s*use\s+Moo(?:::Role)?\b/) 155 13322 13477
590 155 ▶ $current->{uses_moo} = 1 if $current;
Branch: 1 branch
BranchTrueFalseTotal
if $current 155 0 155
591 155 next;
592 }
593 # Detect `extends 'Foo';` (Moo inheritance)
594 13322 ▶ if ($line =~ /^\s*extends\s+['"\(]/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($line =~ /^\s*extends\s+['"\(]/) 113 13209 13322
595 113 ▶ $current->{has_extends} = 1 if $current;
Branch: 1 branch
BranchTrueFalseTotal
if $current 113 0 113
596 # fall through — no 'next' needed, but nothing else to match
597 }
598 # Only match sub definitions at column 0. Indented subs are almost
599 # always inside string heredocs/POD examples or nested coderefs, not
600 # package-level public API. This keeps false positives out.
601 13322 ▶ if ($line =~ /^sub\s+([A-Za-z_]\w*)\b/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($line =~ /^sub\s+([A-Za-z_]\w*)\b/) 882 12440 13322
602 882 my $sub_name = $1;
603 882 ▶ next unless $current; # sub before any package — ignore
Branch: 1 branch
BranchTrueFalseTotal
unless $current 0 882 882
604 # Perl convention: leading underscore = private. Dunder
605 # methods (e.g. __iter__, __next__, __init__) are public
606 # protocol hooks and should be emitted.
607 882 ▶ next if $sub_name =~ /^_/ && !($sub_name =~ /^__\w+__$/);
Branch: 1 branch
BranchTrueFalseTotal
if $sub_name =~ /^_/ and not $sub_name =~ /^__\w+__$/ 206 676 882
Condition100%3/3
$sub_name =~ /^_/ and not $sub_name =~ /^__\w+__$/
!ll&&!rl&&r
6742206
MC/DC100%2/2
$sub_name =~ /^_/ and not $sub_name =~ /^__\w+__$/
$sub_name =~ /^_/ not $sub_name =~ /^__\w+__$/
Truth table100%3/3
A and not(B)
A= $sub_name =~ /^_/B= not $sub_name =~ /^__\w+__$/
ABresult
0X0
100
111
608 676 ▶ next if $SKIP_SUB{$sub_name};
Branch: 1 branch
BranchTrueFalseTotal
if $SKIP_SUB{$sub_name} 12 664 676
609 664 ▶ next if $current->{_seen}{$sub_name}++; # de-dup overloaded defs
Branch: 1 branch
BranchTrueFalseTotal
if $current->{"_seen"}{$sub_name}++ 0 664 664
610 664 push @{ $current->{subs} }, $sub_name;
611 }
612 }
613 68 close $fh;
614  
615 # A Moo "root" class uses Moo directly with no `extends`. Those classes
616 # own their own __init__ and should emit it; subclasses/roles inherit it
617 # and shouldn't repeat it in the surface.
618 68 for my $p (@packages) {
619 169 ▶ $p->{is_moo_root} = ($p->{uses_moo} && !$p->{has_extends}) ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
$p->{'uses_moo'} && !$p->{'has_extends'} ? : 42 127 169
Condition100%3/3
$p->{"uses_moo"} and not $p->{"has_extends"}
!ll&&!rl&&r
1411342
MC/DC100%2/2
$p->{"uses_moo"} and not $p->{"has_extends"}
$p->{"uses_moo"} not $p->{"has_extends"}
Truth table100%3/3
A and not(B)
A= $p->{"uses_moo"}B= not $p->{"has_extends"}
ABresult
0X0
100
111
620 }
621 68 return \@packages;
622 }
623  
624 # -------------------------------------------------------------------------
625 # Projection — walk the files, project each (package, sub) into Python-shape
626 # surface buckets.
627 # -------------------------------------------------------------------------
628 1 ▶sub collect_surface {
Subroutine collect_surface: called CC=23 SCAR=31.5
629 1 my ($lib_root) = @_;
630 1 my %modules; # module => { classes => { CLS => [...] }, functions => [...] }
631  
632 890 ▶ my $ensure = sub {
Subroutine __ANON__: called CC=2 SCAR=6.9
633 890 my ($mod) = @_;
634 890 ▶ $modules{$mod} //= { classes => {}, functions => [] };
Condition100%2/2
$modules{$mod} //= {"classes", {}, "functions", []}
l!l
81575
MC/DC100%1/1
$modules{$mod} //= {"classes", {}, "functions", []}
$modules{$mod}
Truth table100%2/2
A
A= $modules{$mod}
Aresult
11
00
635 890 return $modules{$mod};
636 1 };
637 715 ▶ my $record_class_method = sub {
Subroutine __ANON__: called CC=3 SCAR=11.0
638 715 my ($mod, $class, $method) = @_;
639 715 my $bucket = $ensure->($mod);
640 715 ▶ $bucket->{classes}{$class} //= [];
Condition100%2/2
$bucket->{"classes"}{$class} //= []
l!l
7096
MC/DC100%1/1
$bucket->{"classes"}{$class} //= []
$bucket->{"classes"}{$class}
Truth table100%2/2
A
A= $bucket->{"classes"}{$class}
Aresult
11
00
641 715 my %seen = map { $_ => 1 } @{ $bucket->{classes}{$class} };
642 715 ▶ push @{ $bucket->{classes}{$class} }, $method unless $seen{$method};
Branch: 1 branch
BranchTrueFalseTotal
unless $seen{$method} 697 18 715
643 1 };
644 17 ▶ my $record_function = sub {
Subroutine __ANON__: called CC=2 SCAR=6.9
645 17 my ($mod, $fn) = @_;
646 17 my $bucket = $ensure->($mod);
647 17 my %seen = map { $_ => 1 } @{ $bucket->{functions} };
648 17 ▶ push @{ $bucket->{functions} }, $fn unless $seen{$fn};
Branch: 1 branch
BranchTrueFalseTotal
unless $seen{$fn} 16 1 17
649 1 };
650 158 ▶ my $record_class_only = sub {
Subroutine __ANON__: called CC=2 SCAR=6.9
651 158 my ($mod, $class) = @_;
652 158 my $bucket = $ensure->($mod);
653 158 ▶ $bucket->{classes}{$class} //= [];
Condition100%2/2
$bucket->{"classes"}{$class} //= []
l!l
10148
MC/DC100%1/1
$bucket->{"classes"}{$class} //= []
$bucket->{"classes"}{$class}
Truth table100%2/2
A
A= $bucket->{"classes"}{$class}
Aresult
11
00
654 1 };
655  
656 1 my @pm_files;
657 File::Find::find({
658 97 ▶ wanted => sub { push @pm_files, $File::Find::name if /\.pm$/ },
Subroutine __ANON__: called CC=2 SCAR=6.9
Branch: 1 branch
BranchTrueFalseTotal
if /\.pm$/ 67 30 97
659 1 no_chdir => 1,
660 }, $lib_root);
661 # SignalWire.pm at the lib root
662 1 my $top = File::Spec->catfile(File::Spec->catdir($lib_root, '..'), 'SignalWire.pm');
663 1 ▶ push @pm_files, $top if -f $top;
Branch: 1 branch
BranchTrueFalseTotal
if -f $top 1 0 1
664  
665 1 for my $file (sort @pm_files) {
666 68 ▶ next if $SKIP_FILE{$file};
Branch: 1 branch
BranchTrueFalseTotal
if $SKIP_FILE{$file} 0 68 68
667 68 my $packages = parse_file($file);
668 68 for my $pkg (@$packages) {
669 169 my $pkg_name = $pkg->{name};
670 169 my $info = $PACKAGE_TO_PY{$pkg_name};
671 169 ▶ if (!$info) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($info) 0 169 169
672 0 warn "enumerate_surface: package $pkg_name not in translation map (file: $file)\n";
673 0 next;
674 }
675 169 my $mod = $info->{module};
676 169 my $class = $info->{class};
677  
678 # Record the class even if there are no subs, to keep the shape
679 # consistent with Python's output for empty-class definitions.
680 169 ▶ $record_class_only->($mod, $class) if defined $class;
Branch: 1 branch
BranchTrueFalseTotal
if defined $class 158 11 169
681  
682 # Emit implicit `__init__` only when the Perl class is a Moo root
683 # (use Moo; with no extends) — that matches Python's AST-based
684 # enumerator which records `__init__` on the class that defines
685 # it, not on subclasses that inherit it. Packages opting in via
686 # %FORCE_IMPLICIT_INIT get one too.
687 169 ▶ if (defined $class && !$SKIP_IMPLICIT_INIT{$pkg_name}) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $class and not $SKIP_IMPLICIT_INIT{$pkg_name}) 133 36 169
Condition100%3/3
defined $class and not $SKIP_IMPLICIT_INIT{$pkg_name}
!ll&&!rl&&r
1125133
MC/DC100%2/2
defined $class and not $SKIP_IMPLICIT_INIT{$pkg_name}
defined $class not $SKIP_IMPLICIT_INIT{$pkg_name}
Truth table100%3/3
A and not(B)
A= defined $classB= not $SKIP_IMPLICIT_INIT{$pkg_name}
ABresult
0X0
100
111
688 133 my $has_explicit_new = grep { $_ eq 'new' } @{ $pkg->{subs} };
689 133 my $should_emit_init = 0;
690 133 ▶ if (!$has_explicit_new) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($has_explicit_new) 133 0 133
691 133 ▶ if ($FORCE_IMPLICIT_INIT{$pkg_name}) {
Branch: 2 branches
BranchTrueFalseTotal
if ($FORCE_IMPLICIT_INIT{$pkg_name}) { } 55 78 133
elsif ($pkg->{'is_moo_root'}) { } 13 65 78
692 55 $should_emit_init = 1;
693 } elsif ($pkg->{is_moo_root}) {
694 13 $should_emit_init = 1;
695 }
696 }
697 133 ▶ if ($should_emit_init) {
Branch: 1 branch
BranchTrueFalseTotal
if ($should_emit_init) 68 65 133
698 68 ▶ if ($pkg_name eq 'SignalWire::Agent::AgentBase') {
Branch: 1 branch
BranchTrueFalseTotal
if ($pkg_name eq 'SignalWire::Agent::AgentBase') { } 0 68 68
699 0 my $r = $AGENTBASE_METHOD_TO_PY{new};
700 0 ▶ $record_class_method->($r->{module}, $r->{class}, $r->{method}) if $r;
Branch: 1 branch
BranchTrueFalseTotal
if $r 0 0 0
701 } else {
702 68 $record_class_method->($mod, $class, '__init__');
703 }
704 }
705 }
706  
707 169 for my $sub (@{ $pkg->{subs} }) {
708 # Special-case routing for AgentBase flat class.
709 664 ▶ if ($pkg_name eq 'SignalWire::Agent::AgentBase') {
Branch: 1 branch
BranchTrueFalseTotal
if ($pkg_name eq "SignalWire::Agent::AgentBase") 66 598 664
710 66 my $route = $AGENTBASE_METHOD_TO_PY{$sub};
711 66 ▶ if ($route) {
Branch: 1 branch
BranchTrueFalseTotal
if ($route) { } 59 7 66
712 59 $record_class_method->($route->{module}, $route->{class}, $route->{method});
713 } else {
714 7 warn "enumerate_surface: AgentBase sub '$sub' has no routing entry; recording on AgentBase\n";
715 7 $record_class_method->('signalwire.core.agent_base', 'AgentBase', $sub);
716 }
717 66 next;
718 }
719  
720 # Per-package overrides
721 598 ▶ if (my $ov = $METHOD_OVERRIDES{$pkg_name}{$sub}) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $ov = $METHOD_OVERRIDES{$pkg_name}{$sub}) 22 576 598
722 22 $record_class_method->($ov->{module}, $ov->{class}, $ov->{method});
723 22 next;
724 }
725  
726 # Default: project onto declared (module, class)
727 576 ▶ my $method = ($sub eq 'new') ? '__init__' : $sub;
Branch: 1 branch
BranchTrueFalseTotal
$sub eq 'new' ? : 0 576 576
728 576 ▶ if (defined $class) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $class) { } 559 17 576
729 559 $record_class_method->($mod, $class, $method);
730 } else {
731 # Module-level (no class)
732 17 $record_function->($mod, $method);
733 }
734 }
735 }
736 }
737  
738 # Normalise: sort method arrays and function arrays.
739 1 for my $mod (keys %modules) {
740 75 my $bucket = $modules{$mod};
741 75 for my $c (keys %{ $bucket->{classes} }) {
742 154 my @m = sort @{ $bucket->{classes}{$c} };
743 154 $bucket->{classes}{$c} = \@m;
744 }
745 75 my @f = sort @{ $bucket->{functions} };
746 75 $bucket->{functions} = \@f;
747 }
748  
749 1 return \%modules;
750 }
751  
752 # -------------------------------------------------------------------------
753 # git sha for provenance (optional)
754 # -------------------------------------------------------------------------
755 1 ▶sub git_sha {
Subroutine git_sha: called CC=3 SCAR=11.3
756 1 my $out = eval { `git -C '$REPO_ROOT' rev-parse HEAD 2>/dev/null` };
757 1 ▶ return 'N/A' unless defined $out;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $out 0 1 1
758 1 chomp $out;
759 1 ▶ return $out || 'N/A';
Condition50%1/2
$out || 'N/A'
l!l
01
MC/DC0%0/1
$out || 'N/A'
$out
Truth table50%1/2
A
A= $out
Aresult
11
00
760 }
761  
762 # -------------------------------------------------------------------------
763 # Main
764 # -------------------------------------------------------------------------
765 1 my $modules = collect_surface($LIB_ROOT);
766  
767 1 my $snapshot = {
768 version => '1',
769 generated_from => 'signalwire-perl @ ' . git_sha(),
770 perl_version => sprintf('%vd', $^V),
771 modules => $modules,
772 };
773  
774 1 my $json = JSON->new->utf8->canonical->pretty->encode($snapshot);
775  
776 1 ▶if ($to_stdout) {
Branch: 1 branch
BranchTrueFalseTotal
if ($to_stdout) { } 1 0 1
777 1 print $json;
778 } else {
779 0 ▶ open my $fh, '>', $output_path or die "open $output_path: $!";
Branch: 1 branch
BranchTrueFalseTotal
open my $fh, ">", $output_path or die "open ${output_path}: $!" 0 0 0
780 0 print {$fh} $json;
781 0 close $fh;
782 0 print STDERR "wrote $output_path\n";
783 }
« blib/lib/SignalWire/Contexts.pm ↑ Summary blib/lib/SignalWire/Agent/AgentBase.pm »