Merge branch 'kvm-5.16-fixes' into kvm-master
[platform/kernel/linux-rpi.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 # NOTE: only add things here when the file was gone, but the text wants
12 # to mention a past documentation file, for example, to give credits for
13 # the original work.
14 my %false_positives = (
15         "Documentation/scsi/scsi_mid_low_api.rst" => "Documentation/Configure.help",
16         "drivers/vhost/vhost.c" => "Documentation/virtual/lguest/lguest.c",
17 );
18
19 my $scriptname = $0;
20 $scriptname =~ s,.*/([^/]+/),$1,;
21
22 # Parse arguments
23 my $help = 0;
24 my $fix = 0;
25 my $warn = 0;
26
27 if (! -e ".git") {
28         printf "Warning: can't check if file exists, as this is not a git tree\n";
29         exit 0;
30 }
31
32 GetOptions(
33         'fix' => \$fix,
34         'warn' => \$warn,
35         'h|help|usage' => \$help,
36 );
37
38 if ($help != 0) {
39     print "$scriptname [--help] [--fix]\n";
40     exit -1;
41 }
42
43 # Step 1: find broken references
44 print "Finding broken references. This may take a while...  " if ($fix);
45
46 my %broken_ref;
47
48 my $doc_fix = 0;
49
50 open IN, "git grep ':doc:\`' Documentation/|"
51      or die "Failed to run git grep";
52 while (<IN>) {
53         next if (!m,^([^:]+):.*\:doc\:\`([^\`]+)\`,);
54         next if (m,sphinx/,);
55
56         my $file = $1;
57         my $d = $1;
58         my $doc_ref = $2;
59
60         my $f = $doc_ref;
61
62         $d =~ s,(.*/).*,$1,;
63         $f =~ s,.*\<([^\>]+)\>,$1,;
64
65         if ($f =~ m,^/,) {
66                 $f = "$f.rst";
67                 $f =~ s,^/,Documentation/,;
68         } else {
69                 $f = "$d$f.rst";
70         }
71
72         next if (grep -e, glob("$f"));
73
74         if ($fix && !$doc_fix) {
75                 print STDERR "\nWARNING: Currently, can't fix broken :doc:`` fields\n";
76         }
77         $doc_fix++;
78
79         print STDERR "$file: :doc:`$doc_ref`\n";
80 }
81 close IN;
82
83 open IN, "git grep 'Documentation/'|"
84      or die "Failed to run git grep";
85 while (<IN>) {
86         next if (!m/^([^:]+):(.*)/);
87
88         my $f = $1;
89         my $ln = $2;
90
91         # On linux-next, discard the Next/ directory
92         next if ($f =~ m,^Next/,);
93
94         # Makefiles and scripts contain nasty expressions to parse docs
95         next if ($f =~ m/Makefile/ || $f =~ m/\.sh$/);
96
97         # It doesn't make sense to parse hidden files
98         next if ($f =~ m#/\.#);
99
100         # Skip this script
101         next if ($f eq $scriptname);
102
103         # Ignore the dir where documentation will be built
104         next if ($ln =~ m,\b(\S*)Documentation/output,);
105
106         if ($ln =~ m,\b(\S*)(Documentation/[A-Za-z0-9\_\.\,\~/\*\[\]\?+-]*)(.*),) {
107                 my $prefix = $1;
108                 my $ref = $2;
109                 my $base = $2;
110                 my $extra = $3;
111
112                 # some file references are like:
113                 # /usr/src/linux/Documentation/DMA-{API,mapping}.txt
114                 # For now, ignore them
115                 next if ($extra =~ m/^{/);
116
117                 # Remove footnotes at the end like:
118                 # Documentation/devicetree/dt-object-internal.txt[1]
119                 $ref =~ s/(txt|rst)\[\d+]$/$1/;
120
121                 # Remove ending ']' without any '['
122                 $ref =~ s/\].*// if (!($ref =~ m/\[/));
123
124                 # Remove puntuation marks at the end
125                 $ref =~ s/[\,\.]+$//;
126
127                 my $fulref = "$prefix$ref";
128
129                 $fulref =~ s/^(\<file|ref)://;
130                 $fulref =~ s/^[\'\`]+//;
131                 $fulref =~ s,^\$\(.*\)/,,;
132                 $base =~ s,.*/,,;
133
134                 # Remove URL false-positives
135                 next if ($fulref =~ m/^http/);
136
137                 # Remove sched-pelt false-positive
138                 next if ($fulref =~ m,^Documentation/scheduler/sched-pelt$,);
139
140                 # Discard some build examples from Documentation/target/tcm_mod_builder.rst
141                 next if ($fulref =~ m,mnt/sdb/lio-core-2.6.git/Documentation/target,);
142
143                 # Check if exists, evaluating wildcards
144                 next if (grep -e, glob("$ref $fulref"));
145
146                 # Accept relative Documentation patches for tools/
147                 if ($f =~ m/tools/) {
148                         my $path = $f;
149                         $path =~ s,(.*)/.*,$1,;
150                         $path =~ s,testing/selftests/bpf,bpf/bpftool,;
151                         next if (grep -e, glob("$path/$ref $path/../$ref $path/$fulref"));
152                 }
153
154                 # Discard known false-positives
155                 if (defined($false_positives{$f})) {
156                         next if ($false_positives{$f} eq $fulref);
157                 }
158
159                 if ($fix) {
160                         if (!($ref =~ m/(scripts|Kconfig|Kbuild)/)) {
161                                 $broken_ref{$ref}++;
162                         }
163                 } elsif ($warn) {
164                         print STDERR "Warning: $f references a file that doesn't exist: $fulref\n";
165                 } else {
166                         print STDERR "$f: $fulref\n";
167                 }
168         }
169 }
170 close IN;
171
172 exit 0 if (!$fix);
173
174 # Step 2: Seek for file name alternatives
175 print "Auto-fixing broken references. Please double-check the results\n";
176
177 foreach my $ref (keys %broken_ref) {
178         my $new =$ref;
179
180         my $basedir = ".";
181         # On translations, only seek inside the translations directory
182         $basedir  = $1 if ($ref =~ m,(Documentation/translations/[^/]+),);
183
184         # get just the basename
185         $new =~ s,.*/,,;
186
187         my $f="";
188
189         # usual reason for breakage: DT file moved around
190         if ($ref =~ /devicetree/) {
191                 # usual reason for breakage: DT file renamed to .yaml
192                 if (!$f) {
193                         my $new_ref = $ref;
194                         $new_ref =~ s/\.txt$/.yaml/;
195                         $f=$new_ref if (-f $new_ref);
196                 }
197
198                 if (!$f) {
199                         my $search = $new;
200                         $search =~ s,^.*/,,;
201                         $f = qx(find Documentation/devicetree/ -iname "*$search*") if ($search);
202                         if (!$f) {
203                                 # Manufacturer name may have changed
204                                 $search =~ s/^.*,//;
205                                 $f = qx(find Documentation/devicetree/ -iname "*$search*") if ($search);
206                         }
207                 }
208         }
209
210         # usual reason for breakage: file renamed to .rst
211         if (!$f) {
212                 $new =~ s/\.txt$/.rst/;
213                 $f=qx(find $basedir -iname $new) if ($new);
214         }
215
216         # usual reason for breakage: use dash or underline
217         if (!$f) {
218                 $new =~ s/[-_]/[-_]/g;
219                 $f=qx(find $basedir -iname $new) if ($new);
220         }
221
222         # Wild guess: seek for the same name on another place
223         if (!$f) {
224                 $f = qx(find $basedir -iname $new) if ($new);
225         }
226
227         my @find = split /\s+/, $f;
228
229         if (!$f) {
230                 print STDERR "ERROR: Didn't find a replacement for $ref\n";
231         } elsif (scalar(@find) > 1) {
232                 print STDERR "WARNING: Won't auto-replace, as found multiple files close to $ref:\n";
233                 foreach my $j (@find) {
234                         $j =~ s,^./,,;
235                         print STDERR "    $j\n";
236                 }
237         } else {
238                 $f = $find[0];
239                 $f =~ s,^./,,;
240                 print "INFO: Replacing $ref to $f\n";
241                 foreach my $j (qx(git grep -l $ref)) {
242                         qx(sed "s\@$ref\@$f\@g" -i $j);
243                 }
244         }
245 }