Extend and simplify overlay annotations script

Author: kaspersv

config/add-overlay-annotations.py

@@ -27,65 +27,142 @@ def has_overlay_annotations(lines):
     return any(ann in line for ann in annotations for line in lines)
 
 
-def insert_toplevel_maybe_local_annotation(filename, lines):
+def is_line_comment(line):
+    return line.startswith("//") or (line.startswith("/*") and line.endswith("*/"))
+
+
+def find_file_level_module_declaration(lines):
     '''
-    Find a suitable place to insert an overlay[local?] annotation at the top of the file.
-    Return a pair: (string describing action taken, modified content as list of lines).
+    Returns the index of the existing file-level module declaration if one
+    exists. Returns None otherwise.
+    '''
+    comment = False
+    i = -1
+    for line in lines:
+        i = i + 1
+        trimmed = line.strip()
+
+        if is_line_comment(trimmed):
+            continue
+        elif trimmed.startswith("/*"):
+            comment = True
+        elif comment and trimmed.endswith("*/"):
+            comment = False
+        elif not comment and trimmed.endswith("module;"):
+            return i
+
+    return None
+
+
+def is_file_module_qldoc(i, lines):
+    '''
+    Assuming a qldoc ended on line i, determine if it belongs to the implicit
+    file-level module. If it is followed by another qldoc or imports, then it
+    does and if it is followed by any other non-empty, non-comment lines, then
+    we assume that is a declaration of some kind and the qldoc is attached to
+    that declaration.
+    '''
+    comment = False
+
+    for line in lines[i+1:]:
+        trimmed = line.strip()
+
+        if trimmed.startswith("import ") or trimmed.startswith("private import ") or trimmed.startswith("/**"):
+             return True
+        elif is_line_comment(trimmed) or not trimmed:
+             continue
+        elif trimmed.startswith("/*"):
+             comment = True
+        elif comment and trimmed.endswith("*/"):
+             comment = False
+        elif not comment and trimmed:
+             return False
+
+    return True
+
+
+def find_file_module_qldoc_declaration(lines):
+    '''
+    Returns the index of last line of the implicit file module qldoc if one
+    exists. Returns None otherwise.
     '''
-    out_lines = []
-    status = 0
 
+    i = -1
+    qldoc = False
+    comment = False
     for line in lines:
-        if status == 0 and line.rstrip().endswith("module;"):
-            out_lines.append("overlay[local?]\n")
-            status = 1
-        out_lines.append(line)
+        i = i + 1
+        trimmed = line.strip()
 
-    if status == 1:
-        return (f"Annotating \"{filename}\" via existing file-level module statement", out_lines)
+        if trimmed.startswith("//"):
+            continue
+        elif (qldoc or trimmed.startswith("/**")) and trimmed.endswith("*/"):
+            # a qldoc just ended; determine if it belongs to the implicit file module
+            if is_file_module_qldoc(i, lines):
+                return i
+            else:
+                return None
+        elif trimmed.startswith("/**"):
+            qldoc = True
+        elif trimmed.startswith("/*"):
+            comment = True
+        elif comment and trimmed.endswith("*/"):
+            comment = False
+        elif (not qldoc and not comment) and trimmed:
+            return None
+
+    return None
+
+
+def only_comments(lines):
+    '''
+    Returns true if the lines contain only comments and empty lines.
+    '''
+    comment = False
 
-    out_lines = []
-    empty_line_buffer = []
-    status = 0
     for line in lines:
         trimmed = line.strip()
-        if not trimmed:
-            empty_line_buffer.append(line)
+
+        if not trimmed or is_line_comment(trimmed):
             continue
-        if status <= 1 and trimmed.endswith("*/"):
-            status = 2
-        elif status == 0 and trimmed.startswith("/**"):
-            status = 1
-        elif status == 0 and not trimmed.startswith("/*"):
-            out_lines.append("overlay[local?]\n")
-            out_lines.append("module;\n")
-            out_lines.append("\n")
-            status = 3
-        elif status == 2 and (trimmed.startswith("import ") or trimmed.startswith("private import ")):
-            out_lines.append("overlay[local?]\n")
-            out_lines.append("module;\n")
-            status = 3
-        elif status == 2 and (trimmed.startswith("class ") or trimmed.startswith("predicate ")
-                              or trimmed.startswith("module ") or trimmed.startswith("signature ")):
-            out_lines = ["overlay[local?]\n", "module;\n", "\n"] + out_lines
-            status = 3
-        elif status == 2 and trimmed.startswith("/*"):
-            out_lines.append("overlay[local?]\n")
-            out_lines.append("module;\n")
-            status = 3
-        elif status == 2:
-            status = 4
-        if empty_line_buffer:
-            out_lines += empty_line_buffer
-            empty_line_buffer = []
-        out_lines.append(line)
-    if status == 3:
-        out_lines += empty_line_buffer
+        elif trimmed.startswith("/*"):
+            comment = True
+        elif comment and trimmed.endswith("*/"):
+            comment = False
+        elif comment:
+            continue
+        elif trimmed:
+            return False
+
+    return True
+
+
+def insert_toplevel_maybe_local_annotation(filename, lines):
+    '''
+    Find a suitable place to insert an overlay[local?] annotation at the top of the file.
+    Returns a pair consisting of description and the modified lines or None if no overlay
+    annotation is necessary (e.g., for files that only contain comments).
+    '''
+    if only_comments(lines):
+        return None
+
+    i = find_file_level_module_declaration(lines)
+    if not i == None:
+        out_lines = lines[:i]
+        out_lines.append("overlay[local?]\n")
+        out_lines.extend(lines[i:])
+        return (f"Annotating \"{filename}\" via existing file-level module statement", out_lines)
 
-    if status == 3:
-        return (f"Annotating \"{filename}\" after file-level module qldoc", out_lines)
+    i = find_file_module_qldoc_declaration(lines)
+    if not i == None:
+        out_lines = lines[:i+1]
+        out_lines.append("overlay[local?]\n")
+        out_lines.append("module;\n")
+        out_lines.extend(lines[i+1:])
+        return (f"Annotating \"{filename}\" which has a file-level module qldoc", out_lines)
 
-    raise Exception(f"Failed to annotate \"{filename}\" as overlay[local?].")
+    out_lines = ["overlay[local?]\n", "module;\n", "\n"] + lines
+    return (f"Annotating \"{filename}\" without file-level module qldoc", out_lines)
 
 
 def insert_overlay_caller_annotations(lines):