Merge pull request #11901 from github/redsun82/swift-ql-internal

Swift: introduce `@ql.internal` pragma for classes

Author: MathiasVP

swift/codegen/generators/qlgen.py

@@ -327,7 +327,8 @@ def generate(opts, renderer):
                 renderer.render(stub, stub_file)
 
         # for example path/to/elements -> path/to/elements.qll
-        renderer.render(ql.ImportList(list(imports.values())), include_file)
+        renderer.render(ql.ImportList([i for name, i in imports.items() if not classes[name].ql_internal]),
+                        include_file)
 
         renderer.render(ql.GetParentImplementation(list(classes.values())), out / 'ParentChild.qll')
 

swift/codegen/lib/ql.py

@@ -100,6 +100,7 @@ class Class:
     qltest_skip: bool = False
     qltest_collapse_hierarchy: bool = False
     qltest_uncollapse_hierarchy: bool = False
+    ql_internal: bool = False
     ipa: bool = False
     doc: List[str] = field(default_factory=list)
 
@@ -130,7 +131,7 @@ def last_base(self) -> str:
 
     @property
     def has_doc(self) -> bool:
-        return bool(self.doc)
+        return bool(self.doc) or self.ql_internal
 
 
 @dataclass

swift/codegen/lib/schema/defs.py

@@ -35,6 +35,19 @@ def include(source: str):
         "__includes", []).append(source)
 
 
+class _Namespace:
+    """ simple namespacing mechanism """
+
+    def __init__(self, **kwargs):
+        self.__dict__.update(kwargs)
+
+
+qltest = _Namespace()
+ql = _Namespace()
+cpp = _Namespace()
+synth = _Namespace()
+
+
 @_dataclass
 class _Pragma(_schema.PropertyModifier):
     """ A class or property pragma.
@@ -43,6 +56,10 @@ class _Pragma(_schema.PropertyModifier):
     """
     pragma: str
 
+    def __post_init__(self):
+        namespace, _, name = self.pragma.partition('_')
+        setattr(globals()[namespace], name, self)
+
     def modify(self, prop: _schema.Property):
         prop.pragmas.append(self.pragma)
 
@@ -86,13 +103,6 @@ def __getitem__(self, item):
         return item | self.modifier
 
 
-class _Namespace:
-    """ simple namespacing mechanism """
-
-    def __init__(self, **kwargs):
-        self.__dict__.update(kwargs)
-
-
 _ClassDecorator = _Callable[[type], type]
 
 
@@ -119,28 +129,21 @@ def f(cls: type) -> type:
 
 use_for_null = _annotate(null=True)
 
-qltest = _Namespace(
-    skip=_Pragma("qltest_skip"),
-    collapse_hierarchy=_Pragma("qltest_collapse_hierarchy"),
-    uncollapse_hierarchy=_Pragma("qltest_uncollapse_hierarchy"),
-)
+_Pragma("qltest_skip")
+_Pragma("qltest_collapse_hierarchy")
+_Pragma("qltest_uncollapse_hierarchy")
 
-ql = _Namespace(
-    default_doc_name=lambda doc: _annotate(doc_name=doc)
-)
+ql.default_doc_name = lambda doc: _annotate(doc_name=doc)
+_Pragma("ql_internal")
 
-cpp = _Namespace(
-    skip=_Pragma("cpp_skip"),
-)
+_Pragma("cpp_skip")
 
 
 def group(name: str = "") -> _ClassDecorator:
     return _annotate(group=name)
 
 
-synth = _Namespace(
-    from_class=lambda ref: _annotate(ipa=_schema.IpaInfo(
-        from_class=_schema.get_type_name(ref))),
-    on_arguments=lambda **kwargs: _annotate(
-        ipa=_schema.IpaInfo(on_arguments={k: _schema.get_type_name(t) for k, t in kwargs.items()}))
-)
+synth.from_class = lambda ref: _annotate(ipa=_schema.IpaInfo(
+    from_class=_schema.get_type_name(ref)))
+synth.on_arguments = lambda **kwargs: _annotate(
+    ipa=_schema.IpaInfo(on_arguments={k: _schema.get_type_name(t) for k, t in kwargs.items()}))

swift/codegen/templates/ql_class.mustache

@@ -11,6 +11,9 @@ module Generated {
   {{#doc}}
    * {{.}}
   {{/doc}}
+  {{#ql_internal}}
+   * INTERNAL: Do not use.
+  {{/ql_internal}}
    */
   {{/has_doc}}
   class {{name}} extends Synth::T{{name}}{{#bases}}, {{.}}{{/bases}} {

swift/codegen/templates/ql_stub.mustache

@@ -1,4 +1,9 @@
 // generated by {{generator}}, remove this comment if you wish to edit this file
 private import {{base_import}}
 
+{{#ql_internal}}
+/**
+ * INTERNAL: Do not use.
+ */
+{{/ql_internal}}
 class {{name}} extends Generated::{{name}} {}

swift/codegen/test/test_ql.py

@@ -127,14 +127,16 @@ def test_class_with_children():
     assert cls.has_children is True
 
 
-def test_class_with_doc():
-    cls = ql.Class("Class", doc=["foo", "bar"])
-    assert cls.has_doc is True
-
-
-def test_class_without_doc():
-    cls = ql.Class("Class", doc=[])
-    assert cls.has_doc is False
+@pytest.mark.parametrize("doc,ql_internal,expected",
+                         [
+                             (["foo", "bar"], False, True),
+                             (["foo", "bar"], True, True),
+                             ([], False, False),
+                             ([], True, True),
+                         ])
+def test_has_doc(doc, ql_internal, expected):
+    cls = ql.Class("Class", doc=doc, ql_internal=ql_internal)
+    assert cls.has_doc is expected
 
 
 def test_property_with_description():

swift/codegen/test/test_qlgen.py

@@ -170,6 +170,15 @@ def test_hierarchy_imports(generate_import_list):
     ]) == ql.ImportList([stub_import_prefix + cls for cls in "ABCD"])
 
 
+def test_internal_not_in_import_list(generate_import_list):
+    assert generate_import_list([
+        schema.Class("D", bases=["B", "C"]),
+        schema.Class("C", bases=["A"], derived={"D"}, pragmas=["ql_internal"]),
+        schema.Class("B", bases=["A"], derived={"D"}),
+        schema.Class("A", derived={"B", "C"}, pragmas=["ql_internal"]),
+    ]) == ql.ImportList([stub_import_prefix + cls for cls in "BD"])
+
+
 def test_hierarchy_children(generate_children_implementations):
     assert generate_children_implementations([
         schema.Class("A", derived={"B", "C"}),

swift/codegen/test/test_schema.py

@@ -265,6 +265,7 @@ class A:
             (defs.qltest.collapse_hierarchy, "qltest_collapse_hierarchy"),
             (defs.qltest.uncollapse_hierarchy, "qltest_uncollapse_hierarchy"),
             (defs.cpp.skip, "cpp_skip"),
+            (defs.ql.internal, "ql_internal"),
             ]