Debian Codegraph @

llvm-project/clang-tools-extra/clang-tidy/add_new_check.py

raw
1 #!/usr/bin/env python3
2 #
3 #===- add_new_check.py - clang-tidy check generator ---------*- python -*--===#
4 #
5 # Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
6 # See https://llvm.org/LICENSE.txt for license information.
7 # SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
8 #
9 #===-----------------------------------------------------------------------===#
10
11 from __future__ import print_function
12 from __future__ import unicode_literals
13
14 import argparse
15 import io
16 import os
17 import re
18 import sys
19
20 # Adapts the module's CMakelist file. Returns 'True' if it could add a new
21 # entry and 'False' if the entry already existed.
22 def adapt_cmake(module_path, check_name_camel):
23 filename = os.path.join(module_path, 'CMakeLists.txt')
24
25 # The documentation files are encoded using UTF-8, however on Windows the
26 # default encoding might be different (e.g. CP-1252). To make sure UTF-8 is
27 # always used, use `io.open(filename, mode, encoding='utf8')` for reading and
28 # writing files here and elsewhere.
29 with io.open(filename, 'r', encoding='utf8') as f:
30 lines = f.readlines()
31
32 cpp_file = check_name_camel + '.cpp'
33
34 # Figure out whether this check already exists.
35 for line in lines:
36 if line.strip() == cpp_file:
37 return False
38
39 print('Updating %s...' % filename)
40 with io.open(filename, 'w', encoding='utf8', newline='\n') as f:
41 cpp_found = False
42 file_added = False
43 for line in lines:
44 cpp_line = line.strip().endswith('.cpp')
45 if (not file_added) and (cpp_line or cpp_found):
46 cpp_found = True
47 if (line.strip() > cpp_file) or (not cpp_line):
48 f.write(' ' + cpp_file + '\n')
49 file_added = True
50 f.write(line)
51
52 return True
53
54
55 # Adds a header for the new check.
56 def write_header(module_path, module, namespace, check_name, check_name_camel):
57 filename = os.path.join(module_path, check_name_camel) + '.h'
58 print('Creating %s...' % filename)
59 with io.open(filename, 'w', encoding='utf8', newline='\n') as f:
60 header_guard = ('LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_' + module.upper() + '_'
61 + check_name_camel.upper() + '_H')
62 f.write('//===--- ')
63 f.write(os.path.basename(filename))
64 f.write(' - clang-tidy ')
65 f.write('-' * max(0, 42 - len(os.path.basename(filename))))
66 f.write('*- C++ -*-===//')
67 f.write("""
68 //
69 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
70 // See https://llvm.org/LICENSE.txt for license information.
71 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
72 //
73 //===----------------------------------------------------------------------===//
74
75 #ifndef %(header_guard)s
76 #define %(header_guard)s
77
78 #include "../ClangTidyCheck.h"
79
80 namespace clang::tidy::%(namespace)s {
81
82 /// FIXME: Write a short description.
83 ///
84 /// For the user-facing documentation see:
85 /// http://clang.llvm.org/extra/clang-tidy/checks/%(module)s/%(check_name)s.html
86 class %(check_name_camel)s : public ClangTidyCheck {
87 public:
88 %(check_name_camel)s(StringRef Name, ClangTidyContext *Context)
89 : ClangTidyCheck(Name, Context) {}
90 void registerMatchers(ast_matchers::MatchFinder *Finder) override;
91 void check(const ast_matchers::MatchFinder::MatchResult &Result) override;
92 };
93
94 } // namespace clang::tidy::%(namespace)s
95
96 #endif // %(header_guard)s
97 """ % {'header_guard': header_guard,
98 'check_name_camel': check_name_camel,
99 'check_name': check_name,
100 'module': module,
101 'namespace': namespace})
102
103
104 # Adds the implementation of the new check.
105 def write_implementation(module_path, module, namespace, check_name_camel):
106 filename = os.path.join(module_path, check_name_camel) + '.cpp'
107 print('Creating %s...' % filename)
108 with io.open(filename, 'w', encoding='utf8', newline='\n') as f:
109 f.write('//===--- ')
110 f.write(os.path.basename(filename))
111 f.write(' - clang-tidy ')
112 f.write('-' * max(0, 51 - len(os.path.basename(filename))))
113 f.write('-===//')
114 f.write("""
115 //
116 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
117 // See https://llvm.org/LICENSE.txt for license information.
118 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
119 //
120 //===----------------------------------------------------------------------===//
121
122 #include "%(check_name)s.h"
123 #include "clang/AST/ASTContext.h"
124 #include "clang/ASTMatchers/ASTMatchFinder.h"
125
126 using namespace clang::ast_matchers;
127
128 namespace clang::tidy::%(namespace)s {
129
130 void %(check_name)s::registerMatchers(MatchFinder *Finder) {
131 // FIXME: Add matchers.
132 Finder->addMatcher(functionDecl().bind("x"), this);
133 }
134
135 void %(check_name)s::check(const MatchFinder::MatchResult &Result) {
136 // FIXME: Add callback implementation.
137 const auto *MatchedDecl = Result.Nodes.getNodeAs<FunctionDecl>("x");
138 if (!MatchedDecl->getIdentifier() || MatchedDecl->getName().startswith("awesome_"))
139 return;
140 diag(MatchedDecl->getLocation(), "function %%0 is insufficiently awesome")
141 << MatchedDecl;
142 diag(MatchedDecl->getLocation(), "insert 'awesome'", DiagnosticIDs::Note)
143 << FixItHint::CreateInsertion(MatchedDecl->getLocation(), "awesome_");
144 }
145
146 } // namespace clang::tidy::%(namespace)s
147 """ % {'check_name': check_name_camel,
148 'module': module,
149 'namespace': namespace})
150
151
152 # Returns the source filename that implements the module.
153 def get_module_filename(module_path, module):
154 modulecpp = list(filter(
155 lambda p: p.lower() == module.lower() + 'tidymodule.cpp',
156 os.listdir(module_path)))[0]
157 return os.path.join(module_path, modulecpp)
158
159
160 # Modifies the module to include the new check.
161 def adapt_module(module_path, module, check_name, check_name_camel):
162 filename = get_module_filename(module_path, module)
163 with io.open(filename, 'r', encoding='utf8') as f:
164 lines = f.readlines()
165
166 print('Updating %s...' % filename)
167 with io.open(filename, 'w', encoding='utf8', newline='\n') as f:
168 header_added = False
169 header_found = False
170 check_added = False
171 check_fq_name = module + '-' + check_name
172 check_decl = (' CheckFactories.registerCheck<' + check_name_camel +
173 '>(\n "' + check_fq_name + '");\n')
174
175 lines = iter(lines)
176 try:
177 while True:
178 line = next(lines)
179 if not header_added:
180 match = re.search('#include "(.*)"', line)
181 if match:
182 header_found = True
183 if match.group(1) > check_name_camel:
184 header_added = True
185 f.write('#include "' + check_name_camel + '.h"\n')
186 elif header_found:
187 header_added = True
188 f.write('#include "' + check_name_camel + '.h"\n')
189
190 if not check_added:
191 if line.strip() == '}':
192 check_added = True
193 f.write(check_decl)
194 else:
195 match = re.search('registerCheck<(.*)> *\( *(?:"([^"]*)")?', line)
196 prev_line = None
197 if match:
198 current_check_name = match.group(2)
199 if current_check_name is None:
200 # If we didn't find the check name on this line, look on the
201 # next one.
202 prev_line = line
203 line = next(lines)
204 match = re.search(' *"([^"]*)"', line)
205 if match:
206 current_check_name = match.group(1)
207 if current_check_name > check_fq_name:
208 check_added = True
209 f.write(check_decl)
210 if prev_line:
211 f.write(prev_line)
212 f.write(line)
213 except StopIteration:
214 pass
215
216
217 # Adds a release notes entry.
218 def add_release_notes(module_path, module, check_name):
219 check_name_dashes = module + '-' + check_name
220 filename = os.path.normpath(os.path.join(module_path,
221 '../../docs/ReleaseNotes.rst'))
222 with io.open(filename, 'r', encoding='utf8') as f:
223 lines = f.readlines()
224
225 lineMatcher = re.compile('New checks')
226 nextSectionMatcher = re.compile('New check aliases')
227 checkMatcher = re.compile('- New :doc:`(.*)')
228
229 print('Updating %s...' % filename)
230 with io.open(filename, 'w', encoding='utf8', newline='\n') as f:
231 note_added = False
232 header_found = False
233 add_note_here = False
234
235 for line in lines:
236 if not note_added:
237 match = lineMatcher.match(line)
238 match_next = nextSectionMatcher.match(line)
239 match_check = checkMatcher.match(line)
240 if match_check:
241 last_check = match_check.group(1)
242 if last_check > check_name_dashes:
243 add_note_here = True
244
245 if match_next:
246 add_note_here = True
247
248 if match:
249 header_found = True
250 f.write(line)
251 continue
252
253 if line.startswith('^^^^'):
254 f.write(line)
255 continue
256
257 if header_found and add_note_here:
258 if not line.startswith('^^^^'):
259 f.write("""- New :doc:`%s
260 <clang-tidy/checks/%s/%s>` check.
261
262 FIXME: add release notes.
263
264 """ % (check_name_dashes, module, check_name))
265 note_added = True
266
267 f.write(line)
268
269
270 # Adds a test for the check.
271 def write_test(module_path, module, check_name, test_extension):
272 check_name_dashes = module + '-' + check_name
273 filename = os.path.normpath(os.path.join(
274 module_path, '..', '..', 'test', 'clang-tidy', 'checkers',
275 module, check_name + '.' + test_extension))
276 print('Creating %s...' % filename)
277 with io.open(filename, 'w', encoding='utf8', newline='\n') as f:
278 f.write("""// RUN: %%check_clang_tidy %%s %(check_name_dashes)s %%t
279
280 // FIXME: Add something that triggers the check here.
281 void f();
282 // CHECK-MESSAGES: :[[@LINE-1]]:6: warning: function 'f' is insufficiently awesome [%(check_name_dashes)s]
283
284 // FIXME: Verify the applied fix.
285 // * Make the CHECK patterns specific enough and try to make verified lines
286 // unique to avoid incorrect matches.
287 // * Use {{}} for regular expressions.
288 // CHECK-FIXES: {{^}}void awesome_f();{{$}}
289
290 // FIXME: Add something that doesn't trigger the check here.
291 void awesome_f2();
292 """ % {'check_name_dashes': check_name_dashes})
293
294
295 def get_actual_filename(dirname, filename):
296 if not os.path.isdir(dirname):
297 return ''
298 name = os.path.join(dirname, filename)
299 if (os.path.isfile(name)):
300 return name
301 caselessname = filename.lower()
302 for file in os.listdir(dirname):
303 if (file.lower() == caselessname):
304 return os.path.join(dirname, file)
305 return ''
306
307
308 # Recreates the list of checks in the docs/clang-tidy/checks directory.
309 def update_checks_list(clang_tidy_path):
310 docs_dir = os.path.join(clang_tidy_path, '../docs/clang-tidy/checks')
311 filename = os.path.normpath(os.path.join(docs_dir, 'list.rst'))
312 # Read the content of the current list.rst file
313 with io.open(filename, 'r', encoding='utf8') as f:
314 lines = f.readlines()
315 # Get all existing docs
316 doc_files = []
317 for subdir in filter(lambda s: os.path.isdir(os.path.join(docs_dir, s)), os.listdir(docs_dir)):
318 for file in filter(lambda s: s.endswith('.rst'), os.listdir(os.path.join(docs_dir, subdir))):
319 doc_files.append([subdir, file])
320 doc_files.sort()
321
322 # We couldn't find the source file from the check name, so try to find the
323 # class name that corresponds to the check in the module file.
324 def filename_from_module(module_name, check_name):
325 module_path = os.path.join(clang_tidy_path, module_name)
326 if not os.path.isdir(module_path):
327 return ''
328 module_file = get_module_filename(module_path, module_name)
329 if not os.path.isfile(module_file):
330 return ''
331 with io.open(module_file, 'r') as f:
332 code = f.read()
333 full_check_name = module_name + '-' + check_name
334 name_pos = code.find('"' + full_check_name + '"')
335 if name_pos == -1:
336 return ''
337 stmt_end_pos = code.find(';', name_pos)
338 if stmt_end_pos == -1:
339 return ''
340 stmt_start_pos = code.rfind(';', 0, name_pos)
341 if stmt_start_pos == -1:
342 stmt_start_pos = code.rfind('{', 0, name_pos)
343 if stmt_start_pos == -1:
344 return ''
345 stmt = code[stmt_start_pos+1:stmt_end_pos]
346 matches = re.search('registerCheck<([^>:]*)>\(\s*"([^"]*)"\s*\)', stmt)
347 if matches and matches[2] == full_check_name:
348 class_name = matches[1]
349 if '::' in class_name:
350 parts = class_name.split('::')
351 class_name = parts[-1]
352 class_path = os.path.join(clang_tidy_path, module_name, '..', *parts[0:-1])
353 else:
354 class_path = os.path.join(clang_tidy_path, module_name)
355 return get_actual_filename(class_path, class_name + '.cpp')
356
357 return ''
358
359 # Examine code looking for a c'tor definition to get the base class name.
360 def get_base_class(code, check_file):
361 check_class_name = os.path.splitext(os.path.basename(check_file))[0]
362 ctor_pattern = check_class_name + '\([^:]*\)\s*:\s*([A-Z][A-Za-z0-9]*Check)\('
363 matches = re.search('\s+' + check_class_name + '::' + ctor_pattern, code)
364
365 # The constructor might be inline in the header.
366 if not matches:
367 header_file = os.path.splitext(check_file)[0] + '.h'
368 if not os.path.isfile(header_file):
369 return ''
370 with io.open(header_file, encoding='utf8') as f:
371 code = f.read()
372 matches = re.search(' ' + ctor_pattern, code)
373
374 if matches and matches[1] != 'ClangTidyCheck':
375 return matches[1]
376 return ''
377
378 # Some simple heuristics to figure out if a check has an autofix or not.
379 def has_fixits(code):
380 for needle in ['FixItHint', 'ReplacementText', 'fixit',
381 'TransformerClangTidyCheck']:
382 if needle in code:
383 return True
384 return False
385
386 # Try to figure out of the check supports fixits.
387 def has_auto_fix(check_name):
388 dirname, _, check_name = check_name.partition('-')
389
390 check_file = get_actual_filename(os.path.join(clang_tidy_path, dirname),
391 get_camel_check_name(check_name) + '.cpp')
392 if not os.path.isfile(check_file):
393 # Some older checks don't end with 'Check.cpp'
394 check_file = get_actual_filename(os.path.join(clang_tidy_path, dirname),
395 get_camel_name(check_name) + '.cpp')
396 if not os.path.isfile(check_file):
397 # Some checks aren't in a file based on the check name.
398 check_file = filename_from_module(dirname, check_name)
399 if not check_file or not os.path.isfile(check_file):
400 return ''
401
402 with io.open(check_file, encoding='utf8') as f:
403 code = f.read()
404 if has_fixits(code):
405 return ' "Yes"'
406
407 base_class = get_base_class(code, check_file)
408 if base_class:
409 base_file = os.path.join(clang_tidy_path, dirname, base_class + '.cpp')
410 if os.path.isfile(base_file):
411 with io.open(base_file, encoding='utf8') as f:
412 code = f.read()
413 if has_fixits(code):
414 return ' "Yes"'
415
416 return ''
417
418 def process_doc(doc_file):
419 check_name = doc_file[0] + '-' + doc_file[1].replace('.rst', '')
420
421 with io.open(os.path.join(docs_dir, *doc_file), 'r', encoding='utf8') as doc:
422 content = doc.read()
423 match = re.search('.*:orphan:.*', content)
424
425 if match:
426 # Orphan page, don't list it.
427 return '', ''
428
429 match = re.search('.*:http-equiv=refresh: \d+;URL=(.*).html(.*)',
430 content)
431 # Is it a redirect?
432 return check_name, match
433
434 def format_link(doc_file):
435 check_name, match = process_doc(doc_file)
436 if not match and check_name:
437 return ' `%(check_name)s <%(module)s/%(check)s.html>`_,%(autofix)s\n' % {
438 'check_name': check_name,
439 'module': doc_file[0],
440 'check': doc_file[1].replace('.rst', ''),
441 'autofix': has_auto_fix(check_name)
442 }
443 else:
444 return ''
445
446 def format_link_alias(doc_file):
447 check_name, match = process_doc(doc_file)
448 if match and check_name:
449 module = doc_file[0]
450 check_file = doc_file[1].replace('.rst', '')
451 if match.group(1) == 'https://clang.llvm.org/docs/analyzer/checkers':
452 title = 'Clang Static Analyzer ' + check_file
453 # Preserve the anchor in checkers.html from group 2.
454 target = match.group(1) + '.html' + match.group(2)
455 autofix = ''
456 else:
457 redirect_parts = re.search('^\.\./([^/]*)/([^/]*)$', match.group(1))
458 title = redirect_parts[1] + '-' + redirect_parts[2]
459 target = redirect_parts[1] + '/' + redirect_parts[2] + '.html'
460 autofix = has_auto_fix(title)
461
462 # The checker is just a redirect.
463 return ' `%(check_name)s <%(module)s/%(check_file)s.html>`_, `%(title)s <%(target)s>`_,%(autofix)s\n' % {
464 'check_name': check_name,
465 'module': module,
466 'check_file': check_file,
467 'target': target,
468 'title': title,
469 'autofix': autofix
470 }
471 return ''
472
473 checks = map(format_link, doc_files)
474 checks_alias = map(format_link_alias, doc_files)
475
476 print('Updating %s...' % filename)
477 with io.open(filename, 'w', encoding='utf8', newline='\n') as f:
478 for line in lines:
479 f.write(line)
480 if line.strip() == '.. csv-table::':
481 # We dump the checkers
482 f.write(' :header: "Name", "Offers fixes"\n\n')
483 f.writelines(checks)
484 # and the aliases
485 f.write('\n\n')
486 f.write('.. csv-table:: Aliases..\n')
487 f.write(' :header: "Name", "Redirect", "Offers fixes"\n\n')
488 f.writelines(checks_alias)
489 break
490
491
492 # Adds a documentation for the check.
493 def write_docs(module_path, module, check_name):
494 check_name_dashes = module + '-' + check_name
495 filename = os.path.normpath(os.path.join(
496 module_path, '../../docs/clang-tidy/checks/', module, check_name + '.rst'))
497 print('Creating %s...' % filename)
498 with io.open(filename, 'w', encoding='utf8', newline='\n') as f:
499 f.write(""".. title:: clang-tidy - %(check_name_dashes)s
500
501 %(check_name_dashes)s
502 %(underline)s
503
504 FIXME: Describe what patterns does the check detect and why. Give examples.
505 """ % {'check_name_dashes': check_name_dashes,
506 'underline': '=' * len(check_name_dashes)})
507
508
509 def get_camel_name(check_name):
510 return ''.join(map(lambda elem: elem.capitalize(),
511 check_name.split('-')))
512
513
514 def get_camel_check_name(check_name):
515 return get_camel_name(check_name) + 'Check'
516
517
518 def main():
519 language_to_extension = {
520 'c': 'c',
521 'c++': 'cpp',
522 'objc': 'm',
523 'objc++': 'mm',
524 }
525 parser = argparse.ArgumentParser()
526 parser.add_argument(
527 '--update-docs',
528 action='store_true',
529 help='just update the list of documentation files, then exit')
530 parser.add_argument(
531 '--language',
532 help='language to use for new check (defaults to c++)',
533 choices=language_to_extension.keys(),
534 default='c++',
535 metavar='LANG')
536 parser.add_argument(
537 'module',
538 nargs='?',
539 help='module directory under which to place the new tidy check (e.g., misc)')
540 parser.add_argument(
541 'check',
542 nargs='?',
543 help='name of new tidy check to add (e.g. foo-do-the-stuff)')
544 args = parser.parse_args()
545
546 if args.update_docs:
547 update_checks_list(os.path.dirname(sys.argv[0]))
548 return
549
550 if not args.module or not args.check:
551 print('Module and check must be specified.')
552 parser.print_usage()
553 return
554
555 module = args.module
556 check_name = args.check
557 check_name_camel = get_camel_check_name(check_name)
558 if check_name.startswith(module):
559 print('Check name "%s" must not start with the module "%s". Exiting.' % (
560 check_name, module))
561 return
562 clang_tidy_path = os.path.dirname(sys.argv[0])
563 module_path = os.path.join(clang_tidy_path, module)
564
565 if not adapt_cmake(module_path, check_name_camel):
566 return
567
568 # Map module names to namespace names that don't conflict with widely used top-level namespaces.
569 if module == 'llvm':
570 namespace = module + '_check'
571 else:
572 namespace = module
573
574 write_header(module_path, module, namespace, check_name, check_name_camel)
575 write_implementation(module_path, module, namespace, check_name_camel)
576 adapt_module(module_path, module, check_name, check_name_camel)
577 add_release_notes(module_path, module, check_name)
578 test_extension = language_to_extension.get(args.language)
579 write_test(module_path, module, check_name, test_extension)
580 write_docs(module_path, module, check_name)
581 update_checks_list(clang_tidy_path)
582 print('Done. Now it\'s your turn!')
583
584
585 if __name__ == '__main__':
586 main()