blib/lib/App/perlvars.pm

filter: Statementstmt 99.3% 161 / 162 Branchbran 88.1% 37 / 42 Conditioncond 60.0% 6 / 10 MC/DCmcdc 33.3% 2 / 6 Subroutinesub 100% 18 / 18 Podpod 50.0% 1 / 2 totaltotal 93.7% 225 / 240 CC 32 SCAR 18.0
CC
32
Cov
95%
_build_ignore_for_package
11.3
validate_file
9.0
_code_before_data
6.1
CRAP 6.1
↑ Summary test-data/lib/Local/Unused.pm »
1 package App::perlvars;
2  
3 52 ▶use Moo;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 52 ▶use autodie;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 52 our $VERSION = '0.000009';
7  
8 52 ▶use Encode ();
Subroutine BEGIN: called CC=1 SCAR=0.0
9 52 ▶use File::Spec ();
Subroutine BEGIN: called CC=1 SCAR=0.0
10 52 ▶use Path::Tiny qw( path );
Subroutine BEGIN: called CC=1 SCAR=0.0
11 52 ▶use PPI::Document ();
Subroutine BEGIN: called CC=1 SCAR=0.0
12 52 ▶use Test::Builder ();
Subroutine BEGIN: called CC=1 SCAR=0.0
13 52 ▶use Test::Vars import => [qw( test_vars )];
Subroutine BEGIN: called CC=1 SCAR=0.0
14  
15 52 my $SYNTHETIC_PACKAGE = 'PerlvarsSyntheticPackage';
16 52 my $WRAPPER_SUB = '__perlvars_wrapper__';
17  
18 # Number of lines we prepend when wrapping a package-less file (the synthetic
19 # "package ...;" line and the "sub ... {" line). Reported line numbers are
20 # shifted back by this amount. See _validate_package_less.
21 52 my $WRAP_OFFSET = 2;
22  
23 52 has ignore_file => (
24 is => 'ro',
25 predicate => '_has_ignore_file',
26 );
27  
28 52 has lint_scripts => (
29 is => 'ro',
30 default => 0,
31 );
32  
33 52 has _ignore_for_package => (
34 is => 'ro',
35 init_arg => undef,
36 lazy => 1,
37 builder => '_build_ignore_for_package',
38 );
39  
40 139 ▶sub BUILD {
Subroutine BUILD: called CC=1 SCAR=0.0
Pod undocumented
41 139 my $self = shift;
42  
43 # We need to read the file before we start checking anything so we can die
44 # if it contains bad lines and not have it look like a failure in a
45 # particular file we're tidying.
46 139 $self->_ignore_for_package;
47  
48 139 return;
49 }
50  
51 147 ▶sub validate_file {
Subroutine validate_file: called CC=9 SCAR=22.0
Pod documented
52 147 my $self = shift;
53 147 my $file = path(shift);
54 147 ▶ unless ( $file->exists ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($file->exists) 13 134 147
55 13 return ( 1, "$file could not be found" );
56 }
57 134 ▶ if ( $file->is_dir ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($file->is_dir) 1 133 134
58 1 return ( 1, "$file is a dir" );
59 }
60  
61 133 my $doc = _ppi_document($file);
62 133 ▶ unless ($doc) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($doc) 4 129 133
63  
64 # A file we cannot parse is one we cannot analyze. Under lint_scripts
65 # that is a silent skip, consistent with the other unanalyzable files
66 # below, so a single bad file does not abort a batch run. Without the
67 # opt-in the old contract stands: report it as an error.
68 4 ▶ return ( 0, undef ) if $self->lint_scripts;
Branch: 1 branch
BranchTrueFalseTotal
if $self->lint_scripts 2 2 4
69 2 return ( 1, "$file could not be parsed as Perl" );
70 }
71  
72 129 my $package_stmt = $doc->find_first('PPI::Statement::Package');
73 129 ▶ if ($package_stmt) {
Branch: 1 branch
BranchTrueFalseTotal
if ($package_stmt) 43 86 129
74 my ( $analyzed, $exit_code, @msgs ) = _run_test_vars(
75 "$file",
76 %{
77 43 ▶ $self->_ignore_for_package->{ $package_stmt->namespace } || {}
Condition100%2/2
$self->_ignore_for_package->{$package_stmt->namespace} || {}
l!l
538
MC/DC100%1/1
$self->_ignore_for_package->{$package_stmt->namespace} || {}
$self->_ignore_for_package->{$package_stmt->namespace}
Truth table100%2/2
A
A= $self->_ignore_for_package->{$package_stmt->namespace}
Aresult
11
00
78 },
79 );
80  
81 # A file that exits or dies at compile time (e.g. "use Test::More
82 # skip_all") leaves Test::Vars nothing to inspect and makes its parent
83 # die thawing an empty pipe. Treat it like the other unanalyzable files:
84 # skip silently so one such file does not abort a batch run.
85 32 ▶ return 0, undef unless $analyzed;
Branch: 1 branch
BranchTrueFalseTotal
unless $analyzed 3 29 32
86  
87 29 return $exit_code, undef, @msgs;
88 }
89  
90 # Test::Vars only inspects lexicals in subs in packages, so a package-less
91 # file (most .t/.pl scripts) is otherwise skipped. Analyzing it is opt-in:
92 # wrapping runs the file's compile-time code and can surface never-seen
93 # findings, so the caller must ask via lint_scripts.
94 86 ▶ return ( 0, "$file contains no package" ) unless $self->lint_scripts;
Branch: 1 branch
BranchTrueFalseTotal
unless $self->lint_scripts 11 75 86
95  
96 75 return $self->_validate_package_less( $file, $doc );
97 }
98  
99 133 ▶sub _ppi_document {
Subroutine _ppi_document: called CC=3 SCAR=11.0
100 133 my $file = shift; # Path::Tiny
101  
102 # PPI reads the file as raw bytes. That is fine for ASCII and for high
103 # bytes that only appear in comments or strings, but a file with UTF-8
104 # characters in code (e.g. a Unicode identifier) trips the lexer. When the
105 # raw parse fails, retry against UTF-8-decoded source (leading BOM
106 # stripped). We only need the tree to spot a package statement and the
107 # __END__/__DATA__ cut line, both of which are unaffected by decoding; the
108 # body is still copied as raw bytes when wrapping (see _code_before_data).
109 133 my $doc = PPI::Document->new("$file");
110 133 ▶ return $doc if $doc;
Branch: 1 branch
BranchTrueFalseTotal
if $doc 126 7 133
111  
112 7 my $bytes = $file->slurp_raw;
113 7 $bytes =~ s/\A\x{EF}\x{BB}\x{BF}//;
114 7 my $text = eval { Encode::decode( 'UTF-8', $bytes, Encode::FB_CROAK() ) };
115 7 ▶ return undef unless defined $text; # not UTF-8 (e.g. Latin-1)
Branch: 1 branch
BranchTrueFalseTotal
unless defined $text 0 7 7
116  
117 7 return PPI::Document->new( \$text );
118 }
119  
120 75 ▶sub _validate_package_less {
Subroutine _validate_package_less: called CC=5 SCAR=16.1
121 75 my $self = shift;
122 75 my $file = shift; # Path::Tiny
123 75 my $doc = shift; # PPI::Document
124  
125 # Hand Test::Vars a synthetic "package X; sub Y { ...body... }":
126 # * Wrapping in a sub means require only *compiles* the file, not runs it,
127 # yet its named and anonymous subs become nested subs Test::Vars still
128 # inspects. (The wrapper's own pad -- the file's top-level lexicals -- is
129 # dropped below; see the grep.)
130 # * No #line directive: it would rewrite GvFILE so Test::Vars no longer
131 # matches subs to inspect. We shift line numbers back in
132 # _rewrite_message instead.
133  
134 75 my $code = _code_before_data( $file, $doc );
135  
136 75 my $tmpdir = Path::Tiny->tempdir;
137 75 my $wrapped = $tmpdir->child( 'lib', "$SYNTHETIC_PACKAGE.pm" );
138 75 $wrapped->parent->mkpath;
139  
140 # Copy the body as raw bytes: perl compiles this temp file verbatim, so
141 # re-encoding would be wrong and would die on non-UTF-8 source.
142 75 $wrapped->spew(
143 "package $SYNTHETIC_PACKAGE;\n",
144 "sub $WRAPPER_SUB {\n",
145 $code,
146 "\n}\n1;\n",
147 );
148  
149 # Ignore rules are keyed on "main": that is where a script's findings are
150 # reported (see _rewrite_message) and the namespace a user keys on.
151 my ( $analyzed, $exit_code, @msgs ) = _run_test_vars(
152 "$wrapped",
153 75 ▶ %{ $self->_ignore_for_package->{main} || {} },
Condition100%2/2
$self->_ignore_for_package->{'main'} || {}
l!l
966
MC/DC100%1/1
$self->_ignore_for_package->{'main'} || {}
$self->_ignore_for_package->{'main'}
Truth table100%2/2
A
A= $self->_ignore_for_package->{'main'}
Aresult
11
00
154 );
155  
156 # Compiling the wrapper runs the file's compile-time code, which can exit or
157 # die (e.g. skip_all). That leaves nothing to inspect and is not an
158 # unused-variable finding, so skip the file silently (see _run_test_vars).
159 56 ▶ return 0, undef unless $analyzed;
Branch: 1 branch
BranchTrueFalseTotal
unless $analyzed 1 55 56
160  
161 # A wrapper that won't compile in isolation (a FindBin/"use lib" sibling, or
162 # an uninstalled dep) makes Test::Vars inspect nothing and emit an "ignores
163 # ... because: $@" note. Skip silently rather than report against code we
164 # never inspected (and avoid leaking the wrapper path). The exit code is not
165 # checked: a file can register an END block that runs as the analyzer child
166 # exits and sets a non-zero status, even though nothing was inspected.
167 55 ▶ if ( grep { /^Test::Vars ignores / } @msgs ) {
Branch: 1 branch
BranchTrueFalseTotal
if (grep {/^Test::Vars ignores /;} @msgs) 9 46 55
168 9 return 0, undef;
169 }
170  
171 # Drop findings on the wrapper sub itself: the file's top-level lexicals are
172 # its pad, and one read only from a nested named sub looks "used once" here.
173 # This mirrors how Test::Vars ignores file-scope lexicals in a real package;
174 # the trade-off is a genuinely unused top-level lexical is not reported.
175 46 @msgs = grep { !/ in &\Q$SYNTHETIC_PACKAGE\E::$WRAPPER_SUB / } @msgs;
176  
177 46 @msgs = map { _rewrite_message( $_, "$file", "$wrapped" ) } @msgs;
178  
179 46 ▶ return ( @msgs ? $exit_code : 0 ), undef, @msgs;
Branch: 1 branch
BranchTrueFalseTotal
@msgs ? : 27 19 46
180 }
181  
182 # Run Test::Vars against $target with all of the analyzed file's own output
183 # suppressed, returning ( $analyzed_ok, $exit_code, @msgs ). Both the packaged
184 # and the package-less paths funnel through here so suppression stays identical.
185 #
186 # Analyzing $target requires it, which runs its compile-time code (use/BEGIN).
187 # That code can print or exit/die -- none of which is an unused-variable
188 # finding -- so we contain all three:
189 # * STDOUT and STDERR are redirected to the null device, so the file's own
190 # output (warnings, stray TAP, messages naming a synthetic wrapper path)
191 # never leaks. Test::Vars forks a child that inherits these handles, so its
192 # output is captured too.
193 # * Test::Builder (loaded via Test::Vars) dup'd the real STDOUT/STDERR when it
194 # was first loaded -- before this redirect -- and writes TAP (the plan line,
195 # "not ok", diagnostics) to those private copies, bypassing the fd redirect.
196 # Point its handles at the null device too; the fork inherits the muted
197 # singleton. Test::Builder is a global singleton shared with whatever is
198 # running perlvars (its own test suite included), so its handles are saved
199 # and restored around the run rather than left muted.
200 # * skip_all and friends call exit(), so Test::Vars' child dies before writing
201 # to its pipe and the parent dies thawing an empty string; the eval traps
202 # that, reported as $analyzed_ok being false, so a single file that opts out
203 # at compile time does not abort a batch run.
204 # The real findings come back through test_vars's return value, not any of these
205 # handles.
206 118 ▶sub _run_test_vars {
Subroutine _run_test_vars: called CC=1 SCAR=0.0
207 118 my $target = shift; # file to hand Test::Vars (string)
208 118 my %ignore = @_;
209  
210 118 my ( $exit_code, @msgs );
211  
212 118 open my $stdout_copy, '>&', \*STDOUT;
213 118 open my $stderr_copy, '>&', \*STDERR;
214 118 open STDOUT, '>', File::Spec->devnull;
215 118 open STDERR, '>', File::Spec->devnull;
216  
217 118 my $builder = Test::Builder->new;
218 118 my $tb_out = $builder->output;
219 118 my $tb_failure = $builder->failure_output;
220 118 my $tb_todo = $builder->todo_output;
221 118 $builder->output( File::Spec->devnull );
222 118 $builder->failure_output( File::Spec->devnull );
223 118 $builder->todo_output( File::Spec->devnull );
224  
225 118 my $analyzed = eval {
226 118 ( $exit_code, @msgs )
227 = test_vars( $target, \&_result_handler, %ignore );
228 84 1;
229 };
230  
231 88 $builder->output($tb_out);
232 88 $builder->failure_output($tb_failure);
233 88 $builder->todo_output($tb_todo);
234 88 open STDOUT, '>&', $stdout_copy;
235 88 open STDERR, '>&', $stderr_copy;
236  
237 88 return ( $analyzed, $exit_code, @msgs );
238 }
239  
240 75 ▶sub _code_before_data {
Subroutine _code_before_data: called CC=6 SCAR=18.2
241 75 my $file = shift; # Path::Tiny
242 75 my $doc = shift; # PPI::Document
243  
244 # Drop everything from __END__/__DATA__ on (it would close our synthetic sub
245 # early). Locate the marker via PPI, but slice the *raw* text: PPI drops
246 # heredoc bodies when stringified, which would corrupt the code.
247 75 my $cut_line;
248 75 for my $class (qw( PPI::Statement::End PPI::Statement::Data )) {
249 150 ▶ my $stmt = $doc->find_first($class) or next;
Branch: 1 branch
BranchTrueFalseTotal
my $stmt = $doc->find_first($class) or next 6 144 150
250 6 my $line = $stmt->line_number;
251 6 ▶ $cut_line = $line if !defined $cut_line || $line < $cut_line;
Branch: 1 branch
BranchTrueFalseTotal
if not defined $cut_line or $line < $cut_line 6 0 6
Condition33%1/3
not defined $cut_line or $line < $cut_line
l!l&&r!l&&!r
600
MC/DC0%0/2
not defined $cut_line or $line < $cut_line
not defined $cut_line $line < $cut_line
Truth table33%1/3
not(A) or B
A= not defined $cut_lineB= $line < $cut_line
ABresult
1X1
011
000
252 }
253  
254 # Raw bytes, not decoded text (see spew in _validate_package_less); also
255 # avoids dying on non-UTF-8 source. Slicing keeps line numbers intact.
256 75 my @lines = $file->lines( { binmode => ':raw' } );
257 75 ▶ @lines = @lines[ 0 .. $cut_line - 2 ] if defined $cut_line;
Branch: 1 branch
BranchTrueFalseTotal
if defined $cut_line 6 69 75
258  
259 75 return join q{}, @lines;
260 }
261  
262 38 ▶sub _rewrite_message {
Subroutine _rewrite_message: called CC=1 SCAR=0.0
263 38 my $msg = shift;
264 38 my $file = shift; # original file (string)
265 38 my $wrapped = shift; # synthetic wrapper file (string)
266  
267 # Map the diagnostic back to the real source: shift off the prepended lines
268 # (only for our wrapper path, so other files' line numbers are untouched),
269 # restore the original path, and hide the synthetic anon tag and package.
270 # The line shift runs first, while the wrapper path still anchors it.
271 38 $msg =~ s{(\Q$wrapped\E line )(\d+)}{ $1 . ( $2 - $WRAP_OFFSET ) }ge;
272 38 $msg =~ s{\Q$wrapped\E}{$file}g;
273 38 $msg =~ s{__ANON__\[[^\]]*\]}{__ANON__}g;
274 38 $msg =~ s{\Q$SYNTHETIC_PACKAGE\E::}{main::}g;
275  
276 38 return $msg;
277 }
278  
279 139 ▶sub _build_ignore_for_package {
Subroutine _build_ignore_for_package: called CC=11 SCAR=24.2
280 139 my $self = shift;
281  
282 139 ▶ return {} unless $self->_has_ignore_file;
Branch: 1 branch
BranchTrueFalseTotal
unless $self->_has_ignore_file 125 14 139
283  
284 14 my %vars;
285 my %regexes;
286  
287 14 my $file = path( $self->ignore_file );
288 14 my @lines = $file->lines( { chomp => 1 } );
289 14 for my $line (@lines) {
290 38 ▶ next unless $line =~ /\S/;
Branch: 1 branch
BranchTrueFalseTotal
unless $line =~ /\S/ 0 38 38
291  
292 38 my ( $package, $ignore ) = split( /\s*=\s*/, $line );
293 38 ▶ unless ( defined $package && defined $ignore ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $package and defined $ignore) 0 38 38
Condition33%1/3
defined $package and defined $ignore
!ll&&!rl&&r
0038
MC/DC0%0/2
defined $package and defined $ignore
defined $package defined $ignore
Truth table33%1/3
A and B
A= defined $packageB= defined $ignore
ABresult
0X0
100
111
294 0 die 'Invalid line in ' . $self->ignore_file . ": $line\n";
295 }
296  
297 38 ▶ if ( $ignore =~ m{^qr} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($ignore =~ /^qr/) { } 14 24 38
298 14 local $@ = undef;
299 ## no critic (BuiltinFunctions::ProhibitStringyEval)
300 14 $ignore = eval $ignore;
301 ## use critic
302 14 ▶ die $@ if $@;
Branch: 1 branch
BranchTrueFalseTotal
if $@ 0 14 14
303  
304 14 push @{ $regexes{$package} }, $ignore;
305 }
306 else {
307 24 push @{ $vars{$package} }, $ignore;
308 }
309 }
310  
311 14 my %ignore;
312 14 for my $package ( keys %regexes ) {
313 14 my @re = @{ $regexes{$package} };
314 4 ▶ $ignore{$package}{ignore_if} = sub {
Subroutine __ANON__: called CC=3 SCAR=11.0
315 4 my $check = shift;
316 4 for my $re (@re) {
317 4 ▶ return 1 if $check =~ /$re/;
Branch: 1 branch
BranchTrueFalseTotal
if $check =~ /$re/ 3 1 4
318 }
319 1 return 0;
320 14 };
321 }
322  
323 14 for my $package ( keys %vars ) {
324 14 $ignore{$package}{ignore_vars}{$_} = 1 for @{ $vars{$package} };
325 }
326  
327 14 return \%ignore;
328 }
329  
330 84 ▶sub _result_handler {
Subroutine _result_handler: called CC=1 SCAR=0.0
331 84 shift;
332 84 my $exit_code = shift;
333 84 my $results = shift;
334  
335 84 my @errors = map { $_->[1] } grep { $_->[0] eq 'diag' } @{$results};
336 84 return $exit_code, @errors;
337 }
338  
339 52 1;
340  
341 =pod
342  
343 =encoding UTF-8
344  
345 =head1 NAME
346  
347 App::perlvars - CLI tool to detect unused variables in Perl modules
348  
349 =head1 VERSION
350  
351 version 0.000009
352  
353 =head1 DESCRIPTION
354  
355 You probably don't want to use this class directly. See L<perlvars> for
356 documentation on how to use the command line interface.
357  
358 =head2 ignore_file
359  
360 The path to a file containing a list of variables to ignore on a per-package
361 basis. The pattern is C<Module::Name = $variable> or C<Module::Name = qr/some
362 regex/>. For example:
363  
364 Local::Unused = $unused
365 Local::Unused = $one
366 Local::Unused = $two
367 Local::Unused = qr/^\$.*hree$/
368  
369 =head2 lint_scripts
370  
371 A boolean, false by default. When false, a file without a C<package>
372 declaration is not analyzed (C<validate_file> returns a success exit code and a
373 "contains no package" message). Set it to a true value to also lint
374 package-less files (most C<.t> and C<.pl> scripts) as described under
375 L</validate_file>. It is opt-in because wrapping a file executes its
376 compile-time code and can surface findings on scripts that were never linted
377 before.
378  
379 =head2 validate_file
380  
381 Path to a file which will be validated. Returns an exit code, an error message
382 and a list of unused variables.
383  
384 When L</lint_scripts> is true, files without a C<package> declaration are
385 wrapped in a synthetic package and subroutine so the lexicals inside their
386 named and anonymous subroutines can still be analyzed; reported line numbers
387 are mapped back to the original file. File-scope (top-level) lexicals are not
388 reported, matching how L<Test::Vars> treats file-scope lexicals in a file that
389 declares a package. Findings in these files are reported against the C<main>
390 package, so an C<ignore_file> uses C<main> as the package name to suppress a
391 variable in a package-less file.
392  
393 Wrapping a file for analysis C<require>s it, which executes its compile-time
394 code (C<use> statements and C<BEGIN> blocks) even though its runtime statements
395 do not run. The analyzed file's own output on C<STDOUT> and C<STDERR> is
396 suppressed during analysis so it does not leak through C<perlvars>; the real
397 findings are returned, not printed. A package-less file that cannot be analyzed
398 -- because it finds a sibling library at runtime (e.g. L<FindBin>), depends on
399 a module that is not installed, contains a C<#line> directive that hides its
400 subroutines from L<Test::Vars>, or cannot be parsed as Perl at all -- is
401 skipped silently and returns a success exit code with no notes.
402  
403 Files whose source is UTF-8 (for example a file with a Unicode identifier under
404 C<use utf8>) are handled: the file body is always copied verbatim as raw bytes,
405 and when the tree cannot be built from those raw bytes it is rebuilt from the
406 UTF-8-decoded source.
407  
408 A file that B<does> declare a package is analyzed directly rather than wrapped,
409 but it is C<require>d in the same way, so the same protections apply: its
410 compile-time output is suppressed, and if it exits or dies at compile time (for
411 example C<use Test::More skip_all>) it is skipped silently with a success exit
412 code rather than aborting the run.
413  
414 =head1 AUTHOR
415  
416 Olaf Alders <olaf@wundercounter.com>
417  
418 =head1 COPYRIGHT AND LICENSE
419  
420 This software is copyright (c) 2022 by MaxMind, Inc.
421  
422 This is free software; you can redistribute it and/or modify it under
423 the same terms as the Perl 5 programming language system itself.
424  
425 =cut
426  
427 __END__
↑ Summary test-data/lib/Local/Unused.pm »