forgot format()
[xonotic/xonotic.wiki.git] / assets / check-and-fix.py
1 #!/usr/bin/env python3
2
3 # Run in wiki root
4
5 # Well, this wasn't supposed to be so long and complicated.
6 # Anyway, it makes sure the wiki works on both Gitlab and Github by moving
7 # stuff around and fixing links. Then it reports all remaining broken links
8 # and unused files. Since the wiki is in git, you can use `git status`
9 # and `git diff` to see the changes. You can also use the `--dry-run` flag
10 # to print all changes the script would make without actually making them.
11
12 # See Editing.md for more information.
13
14 # Some stuff that could have been done better:
15 #  - Not parsing Markdown with regex. Currently, we for example report
16 #    broken links even though they're inside code blocks (e.g. Irclog.md)
17 #  - Using the type system (and mypy) to distinguish different link types
18 #    to make sure the right functions are called with the right link types
19 #    (e.g. page links, file links, links with headers, urls, ...)
20 #  - Checking outbound links for 404s.
21
22 import sys
23 import os
24 import glob
25 import regex  # sudo pip3 install regex
26 import functools
27 from typing import *
28 from os.path import normpath, join, dirname, basename
29
30
31 # yeah, well, this is ugly but sure beats putting the regex on one line
32 def compile_regex(rgx: str):
33     # regex (unlike re) supports non-constant length look-behinds
34     return regex.compile(
35         "".join(
36             [line.strip() for line in rgx]))
37
38
39 # examples:
40 # [Page link](Some_Page)
41 # [Url link](http://example.com)
42 # ![Image](image_1.png)
43 # [![Image link to image](image_inner.png)](image_outer.png)
44 # [![Image link to page](image_inner.png)](Archive/Some_Page)
45
46 # regex.sub doesnt support overlapping - we have to use lookbehinds.
47 # Practically, the inner link will never be a page so we don't need to
48 # sub it, but later we can reuse the regex to go through all the links
49 # and check that they're valid.
50 LINK_REGEX = compile_regex("""
51 (?<=
52     \[
53         (?:
54             [^\[\]]*
55         |
56             \!\[
57                 [^\[\]]*
58             \]
59             \(
60                 [^()]*
61             \)
62         )
63     \]
64 )
65 \(
66     ([^()]*)
67 \)
68 """)
69
70
71 fix = False
72
73
74 def strip_header_link(link: str) -> str:
75     "remove links to headers inside the file"
76
77     header_index = link.rfind('#')
78     if header_index != -1:
79         link = link[:header_index]
80     return link
81
82
83 def convert_page_name(path: str) -> str:
84     "path can be with or without .md"
85
86     if path.startswith("_"):
87         # ignore header, footer etc
88         return path
89
90     if "-" in path:
91         # don't wanna break stuff like mapping-entity-func_door
92         return path
93
94     headerless = strip_header_link(path)
95     # don't reformat these links because they're often linked to from outside
96     for exc in ["Repository_Access", "Halogenes_Newbie_Corner"]:
97         if headerless == exc or headerless == exc + ".md":
98             return path
99
100     return basename(path).replace("_", "-")
101
102
103 def convert_page_link(link: str) -> str:
104     header_index = link.rfind('#')
105     if header_index != -1:
106         header = link[header_index + 1:]
107         if "_" in header:
108             print("warning: underscore in header: {}".format(link))
109     return convert_page_name(link)
110
111
112 def find_paths() -> Tuple[List[str], List[str]]:
113     all_paths = sorted(filter(
114         os.path.isfile,
115         [name for name in glob.iglob('**', recursive=True)]))
116     md_paths = sorted(filter(lambda s: s.endswith(".md"), all_paths))
117     return all_paths, md_paths
118
119
120 def fix_dir_structure():
121     _, md_paths = find_paths()
122     for path in md_paths:
123         fixed = convert_page_name(path)
124         if fixed == path:
125             continue
126
127         if os.path.exists(fixed):
128             print("warning: collision: {}".format(path))
129         elif fix:
130             os.rename(path, fixed)
131         else:
132             print("would rename {} to {}".format(path, fixed))
133
134
135 def is_between_files(link: str) -> bool:
136     if "://" in link or link.startswith("#"):
137         # http(s) link or link to header on the same page
138         return False
139     else:
140         return True
141
142
143 def is_page_link(link: str) -> bool:
144     # this is a best guess, i don't think there is a foolproof way to tell
145
146     if link.startswith("assets") or link.startswith("img"):
147         # hopefully nobody adds more directories
148         return False
149     if "." in basename(link):
150         # hopefully it's an extension
151         return False
152     # files in root without extension will fail
153
154     return True
155
156
157 def replace_link(changes: List[str], match) -> str:
158     text = match.group()
159     link_start = match.start(1) - match.start()
160     link_end = match.end(1) - match.start()
161
162     link = text[link_start:link_end]
163
164     if is_between_files(link) and is_page_link(link):
165         new_link = convert_page_link(link)
166         new_text = text[:link_start] + new_link + text[link_end:]
167         if text != new_text:
168             changes.append("\t{} -> {}".format(text, new_text))
169         return new_text
170     else:
171         return text
172
173
174 def fix_links():
175     _, md_paths = find_paths()
176     for path in md_paths:
177         with open(path, 'r+') as f:
178             contents = f.read()
179
180             changes = []
181             replacer = functools.partial(replace_link, changes)
182             contents_new = LINK_REGEX.sub(replacer, contents)
183             if fix and contents != contents_new:
184                 f.seek(0)
185                 f.write(contents_new)
186                 f.truncate()
187             elif not fix and any(changes):
188                 print("would convert these links in {}:".format(path))
189                 for change in changes:
190                     print(change)
191
192
193 def link_to_path(current_file: str, link: str) -> str:
194     #           nothing     .           ..          /
195     # gitlab    root        current     current     root
196     # gollum    current     current     current     root
197     # github    ok          ok          broken      broken
198
199     # when not using subdirs, nothing or "." works for all 3
200
201     if link.startswith("..") or link.startswith("/"):
202         print("file: {} bad link: {}".format(current_file, link))
203
204     # path relative to wiki root, not curent file
205     current_dir = dirname(current_file)
206     link = normpath(join(current_dir, link))
207
208     link = strip_header_link(link)
209
210     # page links don't have an extension - add it
211     extension_index = link.rfind('.')
212     if extension_index == -1:
213         link = link + '.md'
214
215     return link
216
217
218 def get_file_links(path: str) -> Generator[str, None, None]:
219     with open(path, 'r') as f:
220         contents = f.read()
221         for match in LINK_REGEX.finditer(contents):
222             link = match.group(1)
223
224             if is_between_files(link):
225                 yield link
226
227
228 def canonicalize(path: str) -> str:
229     # spaces and capitalization don't seem to matter for pages
230     if path.endswith(".md"):
231         return path.replace(" ", "-").casefold()
232     else:
233         return path
234
235
236 def find_broken(all_paths: List[str], md_paths: List[str]):
237     canonical_paths = [canonicalize(path) for path in all_paths]
238
239     for path in md_paths:
240         if path == "Irclog.md":
241             continue  # TODO need to parse MD properly to avoid false posiives
242         for link in get_file_links(path):
243             link_target = canonicalize(link_to_path(path, link))
244             if not link_target in canonical_paths:
245                 #print("broken link in {}: {} -> {}".format(path, link, link_target))
246                 print("broken link in {}: {}".format(path, link))
247
248
249 def walk_links(canonical_to_real: Dict[str, str], is_linked: Dict[str, bool], current_path: str):
250     canonical = canonicalize(current_path)
251     if canonical not in canonical_to_real:
252         # broken link - nothing to do here, we check broken links elsewhere
253         # because here we're not guaranteed to walk through all files
254         #print("not in known paths: {}".format(current_path))
255         return
256
257     current_path = canonical_to_real[canonical]
258
259     if is_linked[current_path]:
260         return
261
262     is_linked[current_path] = True
263     if current_path.endswith(".md"):
264         for link in get_file_links(current_path):
265             link_target = link_to_path(current_path, link)
266             walk_links(canonical_to_real, is_linked, link_target)
267
268
269 def find_unlinked(all_paths: List[str]):
270     canonical_to_real = {canonicalize(path): path for path in all_paths}
271     is_linked = {path: False for path in all_paths}
272
273     # ignore these 2 - currently they don't show on GitLab but do on GitHub
274     is_linked["_Footer.md"] = True
275     is_linked["_Sidebar.md"] = True
276
277     walk_links(canonical_to_real, is_linked, "Home.md")
278
279     for path, linked in sorted(is_linked.items()):
280         if not linked:
281             print("not reachable from Home: {}".format(path))
282
283
284 def check_links():
285     all_paths, md_paths = find_paths()
286     find_broken(all_paths, md_paths)
287     find_unlinked(all_paths)
288
289
290 def main():
291     global fix
292     if len(sys.argv) > 1 and sys.argv[1] == "--fix":
293         fix = True
294
295     # convert file paths - put everything into root
296     fix_dir_structure()
297
298     # convert links on all pages
299     fix_links()
300
301     # look for broken links and unlinked files
302     check_links()
303
304
305 if __name__ == '__main__':
306     main()