Skip to content

Attribute exports to their true origin via Sub::Identify - #194

Draft
oalders wants to merge 1 commit into
mainfrom
spike/sub-identify-symbol-origins
Draft

oalders wants to merge 1 commit into
mainfrom
spike/sub-identify-symbol-origins

Conversation

@oalders

@oalders oalders commented Sep 11, 2026 •

Copy link
Copy Markdown
Member

Summary

Attribute each exportable sub to the package where it was defined, using Sub::Identify::stash_name. The idea comes from Devel::Wherefore.

@EXPORT and @EXPORT_OK say what a module exports, not where each sub lives. A module can re-export subs it imported from elsewhere: Test::Most re-exports most of its symbols from Test::More, Test::Deep, Test::Exception and others.

Changes

  • ExportInspector:
    • symbol_origins maps each sub in @EXPORT/@EXPORT_OK to its defining package. It skips variables and names with no sub behind them, strips & prefixes, and returns {} if the module can't be loaded.
    • reexported_symbols returns the sorted list of subs defined in another package.
    • stash_name stays correct for generated and __ANON__ subs.
  • dump-perl-exports:
    • Adds an Origin column to the symbol tables when the module re-exports something. Output for other modules is unchanged.
    • Loads the module up front and exits 1 with a single error if it can't be loaded, instead of one error per sandboxed eval plus a bogus fatal_error export.
  • Sub::Identify is a new runtime dependency. AutoPrereqs picks it up; cpanfile, META.json and Makefile.PL are regenerated by dzil at release.
  • New test fixtures Local::Origin* and t/ExportInspector/symbol-origins.t, plus Origin column tests in t/dump-perl-exports.t. Test::Script is now required at version 1.29 for script_fails.

Not yet done

  • No consumer in Include.pm/Document.pm yet. A possible next step is to use the origin to resolve re-export facades.
  • Some core subs report builtin as their origin on newer Perls (e.g. Scalar::Util::blessed). This is documented.

Testing

  • prove -lr -j4 t: PASS (100 files, 345 tests)
  • precious lint on changed files: PASS

Codex review (local)

Codex ran locally with its own sandbox bypassed (outer sandbox: nono).

Declined:

  • Declare Sub::Identify in distribution metadata (P2) and Declare Sub::Identify in dist.ini (P1): AutoPrereqs in @Author::OALDERS already picks it up from use Sub::Identify in ExportInspector.pm. dzil build regenerates cpanfile, META.json and Makefile.PL with Sub::Identify and no dist.ini entry, and those files aren't hand-edited between releases. [Prereqs / RuntimeRequires] only lists modules that need a minimum version.

🤖 Generated with Claude Code · Opus 5.5

@oalders
oalders force-pushed the spike/sub-identify-symbol-origins branch from d7c8360 to b9e3e92 Compare October 5, 2026 15:53
@oalders
oalders force-pushed the spike/sub-identify-symbol-origins branch 2 times, most recently from 235a1dc to 592dce4 Compare October 7, 2026 18:50
@codecov

codecov Bot commented Oct 7, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.91%. Comparing base (cb26458) to head (4218e7f).

Additional details and impacted files
@@            Coverage Diff             @@
##             main     #194      +/-   ##
==========================================
+ Coverage   88.64%   88.91%   +0.27%     
==========================================
  Files          10       10              
  Lines        1136     1155      +19     
  Branches      272      275       +3     
==========================================
+ Hits         1007     1027      +20     
  Misses         73       73              
+ Partials       56       55       -1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@oalders
oalders force-pushed the spike/sub-identify-symbol-origins branch 3 times, most recently from 605fdc8 to 2963cf4 Compare October 8, 2026 00:59

@oalders oalders left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Automated review. Ready to merge? With fixes.

The code is correct. 19 tests pass and lint passes. symbol_origins gives sensible results on real modules: Test::Most shows 26 subs from Test::More, POSIX shows 7 from Fcntl, and List::Util, Carp and Encode show none. The up-front load in dump-perl-exports gives a single clean error for a missing module, an invalid name and a syntax error.

Important: the committed cpanfile doesn't list Sub::Identify. The built dist gets it from AutoPrereqs, so CI is fine. But anyone installing from a checkout with cpm install --cpanfile cpanfile won't get it, and ExportInspector.pm will fail to compile. Run dzil build and commit the regenerated cpanfile; optionally declare it in dist.ini as well.

Minor:

  • On Perl 5.42, Scalar::Util's blessed, weaken and friends report builtin as their origin. That's fine for the dump script, but worth a POD note before reexported_symbols is used to suggest a different import.
  • dump-perl-exports now exits 1 for a module that can't be loaded. The script's POD doesn't mention this.
  • Test gaps: nothing covers &-prefixed names or a name listed in both @EXPORT and @EXPORT_OK, and the unit test never asserts that $origin_var is left out of symbol_origins.

🤖 Review by Claude Code · Opus 5.5

Comment thread lib/App/perlimports/ExportInspector.pm Outdated
A HashRef mapping each sub in C<@EXPORT> and C<@EXPORT_OK> to the package in
which it was defined, per L<Sub::Identify/stash_name>. Empty if the module
cannot be loaded or does not use C<@EXPORT> and C<@EXPORT_OK> (e.g.
L<Sub::Exporter>). Loads the module into the current process, outside the

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Outside the sandbox" is misleading. The Sandbox is an eval in a random package in the same process, so the module is already loaded in-process. The real difference is that this uses require with no import. Suggest: "Requires the module directly (not via a sandboxed use) if it isn't already loaded."

Comment thread lib/App/perlimports/ExportInspector.pm Outdated
unless $INC{ module_notional_filename($module) }
|| $self->_maybe_require_module($module);

# Only subs have an origin.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The filtering to subs happens in the loop below (the sigil skip and the exists & check), not where %names is built. Move this comment to the loop.

Comment thread lib/App/perlimports/ExportInspector.pm Outdated
$origins{$bare}
= Sub::Identify::stash_name( \&{ $module . q{::} . $bare } );
}
use strict;

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: putting no strict 'refs' inside a bare block around the loop is the usual idiom, and it removes the need for this use strict;.

Comment thread t/ExportInspector/symbol-origins.t Outdated
);

is_deeply(
[ sort $ei->reexported_symbols ],

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The sort here hides whether reexported_symbols actually returns a sorted list, which the POD documents. Drop it, and give a fixture two re-exported subs so the order is tested.

@oalders
oalders force-pushed the spike/sub-identify-symbol-origins branch from 8072cc9 to 85b9b26 Compare October 13, 2026 02:35
@oalders oalders changed the title Spike: attribute exports to their true origin via Sub::Identify Attribute exports to their true origin via Sub::Identify Oct 13, 2026
Add symbol_origins and reexported_symbols to ExportInspector, mapping
each sub in @EXPORT/@EXPORT_OK to the package where it was defined.

dump-perl-exports shows an Origin column when a module re-exports subs,
and exits 1 with a single error when the module can't be loaded.

Thanks to Matt S Trout for pointing me at Devel::Wherefore.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@oalders
oalders force-pushed the spike/sub-identify-symbol-origins branch from 9619426 to 4218e7f Compare October 16, 2026 13:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant