Codegen: patch customized stubs with QLdoc

Author: redsun82

misc/codegen/generators/qlgen.py

@@ -312,7 +312,43 @@ def _get_stub(cls: schema.Class, base_import: str, generated_import_prefix: str)
     else:
         accessors = []
     return ql.Stub(name=cls.name, base_import=base_import, import_prefix=generated_import_prefix,
-                   synth_accessors=accessors, ql_internal="ql_internal" in cls.pragmas)
+                   doc=cls.doc, synth_accessors=accessors,
+                   ql_internal="ql_internal" in cls.pragmas)
+
+
+def _patch_class_qldocs(cls: str, qldoc: str, stub_file: pathlib.Path):
+    if not qldoc or not stub_file.exists():
+        return
+    qldoc = "\n".join(l.rstrip() for l in qldoc.splitlines())
+    tmp = stub_file.with_suffix(f'{stub_file.suffix}.bkp')
+    header = "// the following QLdoc is generated: if you need to edit it, do it in the schema file\n"
+    with open(stub_file) as input:
+        qldoc_start = None
+        qldoc_end = None
+        class_start = None
+        for lineno, line in enumerate(input, 1):
+            if line == header:
+                qldoc_start = lineno
+            if line.startswith("/**") and lineno - 1 != qldoc_start:
+                qldoc_start = lineno
+            if line.endswith(" */\n"):
+                qldoc_end = lineno + 1
+            elif line.startswith(f"class {cls}"):
+                class_start = lineno
+                break
+        assert class_start, stub_file
+        assert bool(qldoc_start) == bool(qldoc_end), stub_file
+        if not qldoc_start or qldoc_end != class_start:
+            qldoc_start = class_start
+        input.seek(0)
+        with open(tmp, 'w') as output:
+            for lineno, line in enumerate(input, 1):
+                if lineno == qldoc_start:
+                    print(header, end='', file=output)
+                    print(qldoc, file=output)
+                if lineno < qldoc_start or lineno >= class_start:
+                    print(line, end='', file=output)
+    tmp.rename(stub_file)
 
 
 def generate(opts, renderer):
@@ -362,9 +398,13 @@ def generate(opts, renderer):
         for c in data.classes.values():
             path = _get_path(c)
             stub_file = stub_out / path
+            base_import = get_import(out / path, opts.root_dir)
+            stub = _get_stub(c, base_import, generated_import_prefix)
             if not renderer.is_customized_stub(stub_file):
-                base_import = get_import(out / path, opts.root_dir)
-                renderer.render(_get_stub(c, base_import, generated_import_prefix), stub_file)
+                renderer.render(stub, stub_file)
+            else:
+                qldoc = renderer.render_str(stub, template='ql_stub_class_qldoc')
+                _patch_class_qldocs(c.name, qldoc, stub_file)
 
         # for example path/to/elements -> path/to/elements.qll
         renderer.render(ql.ImportList([i for name, i in imports.items() if not classes[name].ql_internal]),

misc/codegen/lib/ql.py

@@ -167,11 +167,16 @@ class Stub:
     import_prefix: str
     synth_accessors: List[SynthUnderlyingAccessor] = field(default_factory=list)
     ql_internal: bool = False
+    doc: List[str] = field(default_factory=list)
 
     @property
     def has_synth_accessors(self) -> bool:
         return bool(self.synth_accessors)
 
+    @property
+    def has_doc(self) -> bool:
+        return bool(self.doc) or self.ql_internal
+
 
 @dataclass
 class DbClasses:

misc/codegen/test/test_qlgen.py

@@ -414,7 +414,7 @@ def test_class_with_doc(generate_classes):
     assert generate_classes([
         schema.Class("A", doc=doc),
     ]) == {
-        "A.qll": (a_ql_stub(name="A"), a_ql_class(name="A", final=True, doc=doc)),
+        "A.qll": (a_ql_stub(name="A", doc=doc), a_ql_class(name="A", final=True, doc=doc)),
     }
 
 

swift/ql/.generated.list

@@ -1,5 +1,21 @@
 private import codeql.swift.generated.AvailabilityInfo
 
+// the following QLdoc is generated: if you need to edit it, do it in the schema file
+/**
+ * An availability condition of an `if`, `while`, or `guard` statements.
+ *
+ * Examples:
+ * ```
+ * if #available(iOS 12, *) {
+ *   // Runs on iOS 12 and above
+ * } else {
+ *   // Runs only anything below iOS 12
+ * }
+ * if #unavailable(macOS 10.14, *) {
+ *   // Runs only on macOS 10 and below
+ * }
+ * ```
+ */
 class AvailabilityInfo extends Generated::AvailabilityInfo {
   override string toString() {
     result = "#available" and not this.isUnavailable()

swift/ql/lib/codeql/swift/elements/AvailabilityInfo.qll

@@ -1,6 +1,10 @@
 private import codeql.swift.generated.KeyPathComponent
 private import swift
 
+// the following QLdoc is generated: if you need to edit it, do it in the schema file
+/**
+ * A component of a `KeyPathExpr`.
+ */
 class KeyPathComponent extends Generated::KeyPathComponent {
   /**
    * Property access like `.bar` in `\Foo.bar`.

swift/ql/lib/codeql/swift/elements/AvailabilitySpec.qll

@@ -1,5 +1,9 @@
 private import codeql.swift.generated.OtherAvailabilitySpec
 
+// the following QLdoc is generated: if you need to edit it, do it in the schema file
+/**
+ * A wildcard availability spec `*`
+ */
 class OtherAvailabilitySpec extends Generated::OtherAvailabilitySpec {
   override string toString() { result = "*" }
 }

swift/ql/lib/codeql/swift/elements/ErrorElement.qll

@@ -1,5 +1,9 @@
 private import codeql.swift.generated.PlatformVersionAvailabilitySpec
 
+// the following QLdoc is generated: if you need to edit it, do it in the schema file
+/**
+ * An availability spec based on platform and version, for example `macOS 12` or `watchOS 14`
+ */
 class PlatformVersionAvailabilitySpec extends Generated::PlatformVersionAvailabilitySpec {
   override string toString() { result = this.getPlatform() + " " + this.getVersion() }
 }