Perl Support in Maguyva: Package and Subroutine Graphs

Why Perl estates are hard to change safely

Perl code is dense, flexible, and often written by people who left years ago. Sigils change a name’s meaning, packages double as classes, and the same module is loaded by scripts in many directories. A text search finds the strings; it does not tell an agent which subroutine a script actually calls.

Maguyva gives the agent packages, subroutines, imports, and constructors as structure, so it can scope a change before touching the code.

What Maguyva extracts in Perl

Maguyva covers .pl, .pm, .t, .pod, and .perl. Subroutines are extracted as functions and package declarations as classes, and definition names have their sigils ($, @, %, &, *) stripped so variables and subroutines are searchable by their bare names.

Imports come from use, require, and package statements. Method calls of the form Class->new count as instantiation, and bless and tie are kept in the call graph on purpose. The graph also records inheritance, overrides, type references, reads and writes, and exception raises.

About 189 built-in functions (print, open, die, warn, and similar) are filtered from call relationships so repository code stands out.

Example agent prompts

• “Which scripts use Billing::Invoice, and which of its subroutines do they call?” (dependency_search incoming)
• “Where is Report::Monthly constructed, and what happens after ->new?” (find_symbol, then get_task_context)
• “Find every test file that exercises Auth::Session.” (text_pattern_search, then find_symbol)

Known limits

• Classic Perl methods are ordinary sub declarations inside a package, so only the newer dedicated method syntax is classified as a method in structural search. Use the functions preset for older object-oriented Perl.
• Calls to filtered built-ins do not appear as graph edges. Use text_pattern_search when you need every open or print call.

Next steps

Connect a repository with the quickstart, then check the support matrix on the compatibility page. If the estate is moving to another scripting language, compare the Python guide.