documentation-file-ref-check 2.73 KB
Newer Older
1
2
3
#!/usr/bin/env perl
# SPDX-License-Identifier: GPL-2.0
#
4
5
6
# Treewide grep for references to files under Documentation, and report
# non-existing files in stderr.

7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
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) {
24
    print "$scriptname [--help] [--fix]\n";
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
    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 contain nasty expressions to parse docs
	next if ($f =~ m/Makefile/);
	# Skip this script
	next if ($f eq $scriptname);

46
	if ($ln =~ m,\b(\S*)(Documentation/[A-Za-z0-9\_\.\,\~/\*\[\]\?+-]*),) {
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
		my $prefix = $1;
		my $ref = $2;
		my $base = $2;

		$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/);

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

		if ($fix) {
67
			if (!($ref =~ m/(scripts|Kconfig|Kbuild)/)) {
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
				$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="";

89
90
91
92
93
94
95
96
97
98
99
	# 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);
		}
	}
100
101
102
103
104
105
106

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

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

112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
	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);
		}
	}
}