aboutsummaryrefslogtreecommitdiffstats
path: root/scripts/documentation-file-ref-check
blob: ad9db6821824392d293716107b843573c85145d6 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
#!/usr/bin/env perl
# SPDX-License-Identifier: GPL-2.0
#
# Treewide grep for references to files under Documentation, and report
# non-existing files in stderr.

use warnings;
use strict;
use Getopt::Long qw(:config no_auto_abbrev);

my $scriptname = $0;
$scriptname =~ s,.*/([^/]+/),$1,;

# Parse arguments
my $help = 0;
my $fix = 0;

GetOptions(
	'fix' => \$fix,
	'h|help|usage' => \$help,
);

if ($help != 0) {
    print "$scriptname [--help] [--fix]\n";
    exit -1;
}

# Step 1: find broken references
print "Finding broken references. This may take a while...  " if ($fix);

my %broken_ref;

open IN, "git grep 'Documentation/'|"
     or die "Failed to run git grep";
while (<IN>) {
	next if (!m/^([^:]+):(.*)/);

	my $f = $1;
	my $ln = $2;

	# Makefiles and scripts contain nasty expressions to parse docs
	next if ($f =~ m/Makefile/ || $f =~ m/\.sh$/);

	# Skip this script
	next if ($f eq $scriptname);

	if ($ln =~ m,\b(\S*)(Documentation/[A-Za-z0-9\_\.\,\~/\*\[\]\?+-]*)(.*),) {
		my $prefix = $1;
		my $ref = $2;
		my $base = $2;
		my $extra = $3;

		# some file references are like:
		# /usr/src/linux/Documentation/DMA-{API,mapping}.txt
		# For now, ignore them
		next if ($extra =~ m/^{/);

		# Remove footnotes at the end like:
		# Documentation/devicetree/dt-object-internal.txt[1]
		$ref =~ s/(txt|rst)\[\d+]$/$1/;

		# Remove ending ']' without any '['
		$ref =~ s/\].*// if (!($ref =~ m/\[/));

		# Remove puntuation marks at the end
		$ref =~ s/[\,\.]+$//;

		my $fulref = "$prefix$ref";

		$fulref =~ s/^(\<file|ref)://;
		$fulref =~ s/^[\'\`]+//;
		$fulref =~ s,^\$\(.*\)/,,;
		$base =~ s,.*/,,;

		# Remove URL false-positives
		next if ($fulref =~ m/^http/);

		# Remove sched-pelt false-positive
		next if ($fulref =~ m,^Documentation/scheduler/sched-pelt$,);

		# Discard some build examples from Documentation/target/tcm_mod_builder.txt
		next if ($fulref =~ m,mnt/sdb/lio-core-2.6.git/Documentation/target,);

		# Check if exists, evaluating wildcards
		next if (grep -e, glob("$ref $fulref"));

		# Accept relative Documentation patches for tools/
		if ($f =~ m/tools/) {
			my $path = $f;
			$path =~ s,(.*)/.*,$1,;
			next if (grep -e, glob("$path/$ref $path/$fulref"));
		}

		if ($fix) {
			if (!($ref =~ m/(scripts|Kconfig|Kbuild)/)) {
				$broken_ref{$ref}++;
			}
		} else {
			print STDERR "$f: $fulref\n";
		}
	}
}

exit 0 if (!$fix);

# Step 2: Seek for file name alternatives
print "Auto-fixing broken references. Please double-check the results\n";

foreach my $ref (keys %broken_ref) {
	my $new =$ref;

	# get just the basename
	$new =~ s,.*/,,;

	my $f="";

	# usual reason for breakage: DT file moved around
	if ($ref =~ /devicetree/) {
		my $search = $new;
		$search =~ s,^.*/,,;
		$f = qx(find Documentation/devicetree/ -iname "*$search*") if ($search);
		if (!$f) {
			# Manufacturer name may have changed
			$search =~ s/^.*,//;
			$f = qx(find Documentation/devicetree/ -iname "*$search*") if ($search);
		}
	}

	# usual reason for breakage: file renamed to .rst
	if (!$f) {
		$new =~ s/\.txt$/.rst/;
		$f=qx(find . -iname $new) if ($new);
	}

	# usual reason for breakage: use dash or underline
	if (!$f) {
		$new =~ s/[-_]/[-_]/g;
		$f=qx(find . -iname $new) if ($new);
	}

	# Wild guess: seek for the same name on another place
	if (!$f) {
		$f = qx(find . -iname $new) if ($new);
	}

	my @find = split /\s+/, $f;

	if (!$f) {
		print STDERR "ERROR: Didn't find a replacement for $ref\n";
	} elsif (scalar(@find) > 1) {
		print STDERR "WARNING: Won't auto-replace, as found multiple files close to $ref:\n";
		foreach my $j (@find) {
			$j =~ s,^./,,;
			print STDERR "    $j\n";
		}
	} else {
		$f = $find[0];
		$f =~ s,^./,,;
		print "INFO: Replacing $ref to $f\n";
		foreach my $j (qx(git grep -l $ref)) {
			qx(sed "s\@$ref\@$f\@g" -i $j);
		}
	}
}