Overlay annotations script: Add --check mode

Author: kaspersv

config/add-overlay-annotations.py

@@ -6,8 +6,10 @@
 # some specific cases (e.g., empty files, files that configure dataflow for queries).
 
 # The script takes a list of languages and processes the corresponding directories.
+# If the optional --check argument is provided, the script checks for missing annotations,
+# but does not modify any files.
 
-# Usage: python3 add-overlay-annotations.py <language1> <language2> ...
+# Usage: python3 add-overlay-annotations.py [--check] <language1> <language2> ...
 
 # The script will modify the files in place and print the changes made.
 # The script is designed to be run from the root of the repository.
@@ -128,15 +130,20 @@ def annotate_as_appropriate(filename, lines):
     return insert_toplevel_maybe_local_annotation(filename, lines)
 
 
-def process_single_file(filename):
+def process_single_file(write, filename):
     '''
-    Process a single file, annotating it as appropriate and writing the changes back to the file.
+    Process a single file, annotating it as appropriate.
+    If write is set, the changes are written back to the file.
+    Returns True if the file requires changes.
     '''
     old = [line for line in open(filename)]
 
     annotate_result = annotate_as_appropriate(filename, old)
     if annotate_result is None:
-        return
+        return False
+
+    if not write:
+        return True
 
     new = annotate_result[1]
 
@@ -150,9 +157,18 @@ def process_single_file(filename):
             for line in new:
                 out_file.write(line)
 
+    return True
+
+
+if len(sys.argv) > 1 and sys.argv[1] == "--check":
+  check = True
+  langs = sys.argv[2:]
+else:
+  check = False
+  langs = sys.argv[1:]
 
 dirs = []
-for lang in sys.argv[1:]:
+for lang in langs:
     if lang in ["cpp", "go", "csharp", "java", "javascript", "python", "ruby", "rust", "swift"]:
         dirs.append(f"{lang}/ql/lib")
     else:
@@ -161,8 +177,24 @@ def process_single_file(filename):
 if dirs:
     dirs.append("shared")
 
+missingAnnotations = []
+
 for roots in dirs:
     for dirpath, dirnames, filenames in os.walk(roots):
         for filename in filenames:
             if filename.endswith(".qll") and not dirpath.endswith("tutorial"):
-                process_single_file(os.path.join(dirpath, filename))
+                path = os.path.join(dirpath, filename)
+                res = process_single_file(not check, path)
+                if check and res:
+                    missingAnnotations.append(path)
+
+
+if len(missingAnnotations) > 0:
+    print("The following files have no overlay annotations:")
+    for path in missingAnnotations[:10]:
+      print("- " + path)
+    if len(missingAnnotations) > 10:
+      print("and " + str(len(missingAnnotations) - 10) + " additional files.")
+    print()
+    print("Please manually add overlay annotations or use the config/add-overlay-annotations.py script to automatically add sensible default overlay annotations.")
+    exit(-1)