bin/ctgetreports

   1 #!/usr/bin/perl -- -*- mode: cperl -*-
   2
   3 =head1 NAME
   4
   5 ctgetreports - Quickly fetch cpantesters results with all reports
   6
   7 =head1 SYNOPSIS
   8
   9   ctgetreports [options] distroname
  10   ctgetreports [options] --report number ...
  11   ctgetreports -h
  12
  13 =head1 OPTIONS
  14
  15 A distroname is either unversioned as in C<IPC-Run> or versioned as in
  16 C<IPC-Run-0.80>.
  17
  18 =over 2
  19
  20 =cut
  21
  22 my $optpod = <<'=back';
  23
  24 =item B<--cachedir=s>
  25
  26 Directory to keep mirrored data in. Defaults to C<$HOME/var/cpantesters>.
  27
  28 =item B<--ctformat=s>
  29
  30 Format of the cpan-testers file that should be downloaded. Available
  31 options were originally C<html> and C<yaml>. With major construction
  32 works going on the HTML on cpantesters is now unsupported for the time
  33 being.
  34
  35 =item B<--cturl=s>
  36
  37 Base URL of the cpantesters website. Defaults to
  38 C<http://www.cpantesters.org/show> but sometimes it is interesting to set
  39 it to the old URL, C<http://cpantesters.perl.org/show> to diagnose bugs
  40 or whatever.
  41
  42 =item B<--dumpfile=s>
  43
  44 If dumpvars are specified, dump them into this file. Defaults to "ctgetreports.out".
  45
  46 =item B<--dumpvars=s>
  47
  48 Dump all queryable variables matching the regular expression given as
  49 argument at the end of the loop for a distro.
  50
  51 =item B<--help|h>
  52
  53 Prints a brief message and exists.
  54
  55 =item B<--interactive|i>
  56
  57 After every parsed report asks if you want to see it in a pager.
  58
  59 =item B<--local>
  60
  61 Do not mirror, use a local *.html file. Dies if the HTML or YAML file
  62 is missing, skips missing report files.
  63
  64 =item B<--pager=s>
  65
  66 Pager (needed when -i is given). Defaults to C<less>.
  67
  68 =item B<--q=s@>
  69
  70 Query, may be repeated.
  71
  72 Example: C<--q mod:Clone --q meta:writer>
  73
  74 =item B<--quiet!>
  75
  76 Do not output the usual query lines per parsed report. Quiet
  77 overrules verbose.
  78
  79 =item B<--raw!>
  80
  81 Boolean which, if set, causes the full (HTML) report to be
  82 concatenated to STDOUT after every status line.
  83
  84 =item B<--report=s@>
  85
  86 Avert going through a cpan testers index, go straight to the report
  87 with this number.
  88
  89 Example: C<--report 1238673>
  90
  91 =item B<--solve!>
  92
  93 Calls the solve function which tries to identify the best contenders
  94 for a blame using Statistics::Regression. Currently only limited to
  95 single variables and with simple heuristics. Implies C<--dumpvars=.>
  96 unless the caller sets dumpvars himself.
  97
  98 The function prints at the moment to STDOUT the top 3 (set with
  99 C<--solvetop>) candidates according to R^2 with their regression
 100 analysis.
 101
 102 A few words of advise: do not take the results as a prove ever. Take
 103 them just as a hint where you can most probablt prove a causal
 104 relationship. And keep in mind that causal relationships can be the
 105 other direction as well.
 106
 107 If you want to extend on that approach, I recommend you study the
 108 ctgetreports.out file where you find all the data you'd need and feed
 109 your assumptions to Statistics::Regression.
 110
 111 =item B<--solvetop=i>
 112
 113 The number of top candidates from the C<--solve> regression analysis
 114 to display.
 115
 116 =item B<--transport=s>
 117
 118 Specifies transport to get the reports. C<nntp> uses Net::NNTP,
 119 C<http> uses LWP::UserAgent. Defaults to nntp.
 120
 121 =item B<--vdistro=s>
 122
 123 Versioned distro, e.g.
 124
 125   IPC-Run-0.80
 126
 127 Usually not needed because a versioned distro name can be specified as
 128 normal commandline argument.
 129
 130 =item B<--verbose|v+>
 131
 132 Feedback during download.
 133
 134 =item B<--ycb=s>
 135
 136 Only used during --solve. Provides perl code to be used as a callback
 137 from the regression to determine the B<Y> of the regression equation.
 138 The callback function gets a record (hashref) as the only argument and
 139 must return a value or undefined. If it returns undefined, the record
 140 is skipped, otherwise this record is processed with the returned
 141 value. The callback is pure perl code without any surrounding sub
 142 declaration.
 143
 144 The following example analyses diagnostic output from Acme-Study-Perl:
 145
 146   ctgetreports --q qr:"#(.*native big math float/int.*)" --solve \
 147     --ycb 'my $rec = shift;
 148            my $nbfi = $rec->{"qr:#(.*native big math float/int.*)"};
 149           return undef unless defined $nbfi;
 150           my $VAR1 = eval($nbfi);
 151           return $VAR1->{">"}' Acme-Study-Perl
 152
 153 =back
 154
 155 =head1 DESCRIPTION
 156
 157 !!!!Alert: alpha quality software, subject to change without warning!!!!
 158
 159 The intent is to get at both the summary at cpantesters and the
 160 individual reports and parse the reports and collect the data for
 161 further inspection.
 162
 163 We always only fetch the reports for the most recent (optionally
 164 picked) release. Target root directory is C<$HOME/var/cpantesters>
 165 (can be overridden with the --cachedir option).
 166
 167 The C<--q> paramater can be repeated. It takes one argument which
 168 stands for a query. This query must consist of two parts, a qualifier
 169 and the query itself. Qualifiers are one of the following
 170
 171   conf       parameters from the output of 'perl -V'
 172              e.g.: conf:usethreads, conf:cc
 173   mod        for installed modules, either from prerequisites or from the toolchain
 174              e.g.: mod:Test::Simple, mod:Imager
 175   env        environment variables
 176              e.g.: env:TERM
 177   meta       all other parameters
 178              e.g.: meta:perl, meta:from, meta:date, meta:writer
 179   qr         boolean set if the appended regexp matches the report
 180              e.g.: qr:'division by zero'
 181
 182 The conf parameters specify a word used by the C<Config> module.
 183
 184 The mod parameters consist of a package name.
 185
 186 The meta parameters are the following: C<perl> for the perl version,
 187 C<from> for the sender of the report, C<date> for the date in the mail
 188 header, C<writer> for the module that produced the report,
 189 C<output_from> for the line that is reported to have produced the output.
 190
 191
 192 =head2 Examples
 193
 194 This gets all recent reports for Object-Relation and outputs the
 195 version number of the prerequisite Clone:
 196
 197   $0 --q mod:Clone Object-Relation
 198
 199 Collects reports about Clone and reports the default set of metadata:
 200
 201   $0 Clone
 202
 203 Collect reports for Devel-Events and report the version number of
 204 Moose in thses reports and sort by success/failure. If Moose broke
 205 Devel-Events is becomes pretty obvious:
 206
 207   $0 --q mod:Moose Devel-Events |sort
 208
 209 Which tool was used to write how many reports, sorted by frequency:
 210
 211   $0 --q meta:writer Template-Timer | sed -e 's/.*meta:writer//' | sort | uniq -c | sort -n
 212
 213 Who was in the From field of the mails whose report writer was not determined:
 214
 215   $0 --q meta:writer --q meta:from Template-Timer | grep 'UNDEF'
 216
 217 At the time of this writing this collected the results of
 218 IPC-Run-0.80_91 which was not really the latest release. In this case
 219 manual investigations were necessary to find out that 0.80 was the
 220 most recent:
 221
 222   $0 IPC-Run
 223
 224 Pick the specific release IPC-Run-0.80:
 225
 226   $0 IPC-Run-0.80
 227
 228 The following displays in its own column if the report contains the
 229 regexp C<division by zero>:
 230
 231   $0 --q qr:"division by zero" CPAN-Testers-ParseReport-0.0.7
 232
 233 The following is a simple job to refresh all HTML pages we already
 234 have and fetch new reports referenced there too:
 235
 236   perl -le '
 237   for my $dirent (glob "$ENV{HOME}/var/cpantesters/cpantesters-show/*.html"){
 238     my($distro) = $dirent =~ m|/([^/]+)\.html$| or next;
 239     print $distro;
 240     my $system = "ctgetreports --verbose --verbose $distro";
 241     0 == system $system or die;
 242   }'
 243
 244 =cut
 245
 246 use strict;
 247 use warnings;
 248
 249 use CPAN::Testers::ParseReport;
 250 use Getopt::Long;
 251 use Pod::Usage qw(pod2usage);
 252
 253 our %Opt;
 254 my @opt = $optpod =~ /B<--(\S+)>/g;
 255 for (@opt) {
 256     $_ .= "!" unless /[+!=]/;
 257 }
 258
 259 GetOptions(\%Opt,
 260            @opt,
 261           ) or pod2usage(2);
 262
 263 if ($Opt{help}) {
 264     pod2usage(0);
 265 }
 266
 267 if ($Opt{report}) {
 268     if (@ARGV) {
 269         pod2usage(2);
 270     }
 271 } else {
 272     if (1 != @ARGV) {
 273         pod2usage(2);
 274     }
 275 }
 276
 277 if ($Opt{solve}) {
 278     eval { require Statistics::Regression };
 279     if ($@) {
 280         die "Statistics::Regression required for solved option: $@";
 281     }
 282 }
 283
 284 if ($Opt{dumpvars}) {
 285     eval { require YAML::Syck };
 286     if ($@) {
 287         die "YAML::Syck required for dumpvars option: $@";
 288     }
 289 }
 290
 291 $|=1;
 292 if (my $reports = delete $Opt{report}) {
 293     my $dumpvars = {};
 294  REPORT: for my $report (@$reports) {
 295         CPAN::Testers::ParseReport::parse_single_report({id => $report},$dumpvars,%Opt);
 296         last REPORT if $CPAN::Testers::ParseReport::Signal;
 297     }
 298     my $dumpfile = $Opt{dumpfile} || "ctgetreports.out";
 299     YAML::Syck::DumpFile($dumpfile,$dumpvars);
 300 } else {
 301     $ARGV[0] =~ s|.+/||;
 302     CPAN::Testers::ParseReport::parse_distro($ARGV[0],%Opt);
 303 }
 304
 305 __END__