GNU Linux-libre 4.19.211-gnu1
[releases.git] / scripts / documentation-file-ref-check
1 #!/usr/bin/env perl
2 # SPDX-License-Identifier: GPL-2.0
3 #
4 # Treewide grep for references to files under Documentation, and report
5 # non-existing files in stderr.
6
7 use warnings;
8 use strict;
9 use Getopt::Long qw(:config no_auto_abbrev);
10
11 my $scriptname = $0;
12 $scriptname =~ s,.*/([^/]+/),$1,;
13
14 # Parse arguments
15 my $help = 0;
16 my $fix = 0;
17
18 GetOptions(
19         'fix' => \$fix,
20         'h|help|usage' => \$help,
21 );
22
23 if ($help != 0) {
24     print "$scriptname [--help] [--fix]\n";
25     exit -1;
26 }
27
28 # Step 1: find broken references
29 print "Finding broken references. This may take a while...  " if ($fix);
30
31 my %broken_ref;
32
33 open IN, "git grep 'Documentation/'|"
34      or die "Failed to run git grep";
35 while (<IN>) {
36         next if (!m/^([^:]+):(.*)/);
37
38         my $f = $1;
39         my $ln = $2;
40
41         # Makefiles and scripts contain nasty expressions to parse docs
42         next if ($f =~ m/Makefile/ || $f =~ m/\.sh$/);
43
44         # Skip this script
45         next if ($f eq $scriptname);
46
47         if ($ln =~ m,\b(\S*)(Documentation/[A-Za-z0-9\_\.\,\~/\*\[\]\?+-]*)(.*),) {
48                 my $prefix = $1;
49                 my $ref = $2;
50                 my $base = $2;
51                 my $extra = $3;
52
53                 # some file references are like:
54                 # /usr/src/linux/Documentation/DMA-{API,mapping}.txt
55                 # For now, ignore them
56                 next if ($extra =~ m/^{/);
57
58                 # Remove footnotes at the end like:
59                 # Documentation/devicetree/dt-object-internal.txt[1]
60                 $ref =~ s/(txt|rst)\[\d+]$/$1/;
61
62                 # Remove ending ']' without any '['
63                 $ref =~ s/\].*// if (!($ref =~ m/\[/));
64
65                 # Remove puntuation marks at the end
66                 $ref =~ s/[\,\.]+$//;
67
68                 my $fulref = "$prefix$ref";
69
70                 $fulref =~ s/^(\<file|ref)://;
71                 $fulref =~ s/^[\'\`]+//;
72                 $fulref =~ s,^\$\(.*\)/,,;
73                 $base =~ s,.*/,,;
74
75                 # Remove URL false-positives
76                 next if ($fulref =~ m/^http/);
77
78                 # Remove sched-pelt false-positive
79                 next if ($fulref =~ m,^Documentation/scheduler/sched-pelt$,);
80
81                 # Discard some build examples from Documentation/target/tcm_mod_builder.txt
82                 next if ($fulref =~ m,mnt/sdb/lio-core-2.6.git/Documentation/target,);
83
84                 # Check if exists, evaluating wildcards
85                 next if (grep -e, glob("$ref $fulref"));
86
87                 # Accept relative Documentation patches for tools/
88                 if ($f =~ m/tools/) {
89                         my $path = $f;
90                         $path =~ s,(.*)/.*,$1,;
91                         next if (grep -e, glob("$path/$ref $path/$fulref"));
92                 }
93
94                 if ($fix) {
95                         if (!($ref =~ m/(scripts|Kconfig|Kbuild)/)) {
96                                 $broken_ref{$ref}++;
97                         }
98                 } else {
99                         print STDERR "$f: $fulref\n";
100                 }
101         }
102 }
103
104 exit 0 if (!$fix);
105
106 # Step 2: Seek for file name alternatives
107 print "Auto-fixing broken references. Please double-check the results\n";
108
109 foreach my $ref (keys %broken_ref) {
110         my $new =$ref;
111
112         # get just the basename
113         $new =~ s,.*/,,;
114
115         my $f="";
116
117         # usual reason for breakage: DT file moved around
118         if ($ref =~ /devicetree/) {
119                 my $search = $new;
120                 $search =~ s,^.*/,,;
121                 $f = qx(find Documentation/devicetree/ -iname "*$search*") if ($search);
122                 if (!$f) {
123                         # Manufacturer name may have changed
124                         $search =~ s/^.*,//;
125                         $f = qx(find Documentation/devicetree/ -iname "*$search*") if ($search);
126                 }
127         }
128
129         # usual reason for breakage: file renamed to .rst
130         if (!$f) {
131                 $new =~ s/\.txt$/.rst/;
132                 $f=qx(find . -iname $new) if ($new);
133         }
134
135         # usual reason for breakage: use dash or underline
136         if (!$f) {
137                 $new =~ s/[-_]/[-_]/g;
138                 $f=qx(find . -iname $new) if ($new);
139         }
140
141         # Wild guess: seek for the same name on another place
142         if (!$f) {
143                 $f = qx(find . -iname $new) if ($new);
144         }
145
146         my @find = split /\s+/, $f;
147
148         if (!$f) {
149                 print STDERR "ERROR: Didn't find a replacement for $ref\n";
150         } elsif (scalar(@find) > 1) {
151                 print STDERR "WARNING: Won't auto-replace, as found multiple files close to $ref:\n";
152                 foreach my $j (@find) {
153                         $j =~ s,^./,,;
154                         print STDERR "    $j\n";
155                 }
156         } else {
157                 $f = $find[0];
158                 $f =~ s,^./,,;
159                 print "INFO: Replacing $ref to $f\n";
160                 foreach my $j (qx(git grep -l $ref)) {
161                         qx(sed "s\@$ref\@$f\@g" -i $j);
162                 }
163         }
164 }