feat(compiler): allow explicit lift qualifications of preflight objec…

…ts (#5935)

Fixes: #76
Creates a `lift` builtin function that can be used in inflight code to explicitly add lift qualifications to a method:
```wing
bring cloud;

let bucket = new cloud.Bucket();
bucket.addObject("k", "value");

let some_ops = ["put", "list"]; // We can define a list of ops in preflight code to be used when explicitly qualifying a lift

class Foo {
  pub inflight mehtod() {
    lift(bucket, some_ops); // Explicitly add some permissions to `bucket` using a preflight expression
    lift(bucket, ["delete"]); // Add more permissions to bucket using a literal
    log(bucket.get("k")); // Good old implicit qualification adds `get` permissions
    let b = bucket; // We can now use an inflight variable `b` to reference a preflight object `bucket`
    b.put("k2", "value2"); // We don't get a compiler error here, because explicit lifts are being used in the method disabling compiler qualification errors
    for k in b.list() { // `list` works on `bucket` because of explicit qualification and `b` references `bucket`
      log(k);
    }
    b.delete("k2"); // `delete` also works because of explicit qualification
    assert(bucket.tryGet("k2") == nil); `yay!`
  }
}

let foo = new Foo();

test "a test" {
  foo.mehtod();
}
```

## Checklist

- [x] Title matches [Winglang's style guide](https://www.winglang.io/contributing/start-here/pull_requests#how-are-pull-request-titles-formatted)
- [x] Description explains motivation and solution
- [x] Tests added (always)
- [x] Docs updated (only required for features)
- [ ] Added `pr/e2e-full` label if this feature requires end-to-end testing

*By submitting this pull request, I confirm that my contribution is made under the terms of the [Wing Cloud Contribution License](https://github.com/winglang/wing/blob/main/CONTRIBUTION_LICENSE.md)*.

docs/docs/02-concepts/01-preflight-and-inflight.md

@@ -268,6 +268,65 @@ inflight () => {
 };
 ```
 
+### Lift qualification
+
+Preflight objects referenced inflight are called "lifted" objects:
+
+```js playground
+let preflight_str = "hello from preflight"; 
+inflight () => {
+  log(preflight_str); // `preflight_str` is "lifted" into inflight.
+};
+```
+
+During the lifting process the compiler tries to figure out in what way the lifted objects are being used. 
+This is how Winglang generats least privilage permissions. Consider the case of lifting a [`cloud.Bucket`](../04-standard-library/cloud/bucket.md) object:
+
+```js playground
+bring cloud;
+let bucket = new cloud.Bucket();
+new cloud.Function(inflight () => {
+  bucket.put("key", "value"); // `bucket` is lifted and `put` is being used on it
+});
+```
+
+In this example the compiler generates the correct _write_ access permissions for the [`cloud.Function`](../04-standard-library/cloud/function.md) on `bucket` based on the fact we're `put`ing into it. We say `bucket`'s lift is qualified with `put`. 
+
+#### Explicit lift qualification
+In some cases the compiler can't figure out (yet) the lift qualifications, and therefore will report an error:
+
+```js playground
+bring cloud;
+let main_bucket = new cloud.Bucket() as "main";
+let secondary_bucket = new cloud.Bucket() as "backup";
+let use_main = true;
+new cloud.Function(inflight () => {
+  let var b = main_bucket;
+  if !use_main {
+    b = secondary_bucket;
+  }
+  b.put("key", "value"); // Error: the compiler doesn't know the possible values for `b` and therefore can't qualify the lift.
+});
+```
+
+To explicitly qualify lifts in an inflight closure or inflight method and supress the above compiler error use the `lift()` utility function:
+
+```js playground
+bring cloud;
+let main_bucket = new cloud.Bucket() as "main";
+let secondary_bucket = new cloud.Bucket() as "backup";
+let use_main = true;
+new cloud.Function(inflight () => {
+  lift(main_bucket, ["put"]); // Explicitly sate the "put" may be used on `main_bucket`
+  lift(secondary_bucket, ["put"]); // Explicitly sate the "put" may be used on `secondary_bucket`
+  let var b = main_bucket;
+  if !use_main {
+    b = secondary_bucket;
+  }
+  b.put("key", "value"); // Error is supressed and all possible values of `b` were explicitly qualified with "put"
+});
+```
+
 ## Phase-independent code
 
 The global functions `log`, `assert`, and `throw` can all be used in both preflight and inflight code.

docs/docs/03-language-reference.md

@@ -553,6 +553,7 @@ log("UTC: {t1.utc.toIso())}");            // output: 2023-02-09T06:21:03.000Z
 | `assert`     | checks a condition and _throws_ if evaluated to false |
 | `unsafeCast` | cast a value into a different type                    |
 | `nodeof`     | obtain the [tree node](./02-concepts/02-application-tree.md) of a preflight object |
+| `lift`       | explicitly qualify a [lift](./02-concepts/01-preflight-and-inflight.md#explicit-lift-qualification) of a preflight object |
 
 > ```TS
 > log("Hello {name}");

examples/tests/invalid/explicit_lift_qualification.test.w

@@ -0,0 +1,40 @@
+bring cloud;
+
+let bucket = new cloud.Bucket();
+
+let prelight_string = "hi";
+
+class Foo {
+  pub inflight mehtod1() {
+    let b = bucket;
+    lift(b, ["put"]); // Explicit qualification with inflight object, lift call as non first statement
+      // ^ Expected a preflight object as first argument to `lift` builtin, found inflight expression instead
+    //^^^^^^^^^^^^^^^ lift() calls must be at the top of the method
+
+    lift(prelight_string, ["contains"]); // Explicit qualification on preflight non-class
+      // ^^^^^^^^^^^^^^^ Expected type to be "Resource", but got "str" instead
+    //^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ lift() calls must be at the top of the method
+
+    let inflight_qualifier = "delete";
+    lift(bucket, [inflight_qualifier]); // Explicit qualification with inflight qualifiers, lift call as non first statement
+              // ^^^^^^^^^^^^^^^^^^^^ Qualification list must not contain any inflight elements
+    //^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ lift() calls must be at the top of the method
+
+    let inner_closure = () => {
+      lift(bucket, ["get"]); // lift() call in inner closure
+      //^^^^^^^^^^^^^^^^^^^^ lift() calls are only allowed in inflight methods and closures defined in preflight
+    };
+    class Bar {
+      pub inflight method() {
+        lift(bucket, ["get"]); // lift() call in inner class
+        //^^^^^^^^^^^^^^^^^^^^ lift() calls are only allowed in inflight methods and closures defined in preflight
+    }
+    }
+  }
+
+  pub inflight method2() {
+    let b = bucket;
+    b.put("k", "v"); // With no explicit qualification this should be an error
+    //^ Expression of type "Bucket" references an unknown preflight object
+  }
+}

examples/tests/valid/explicit_lift_qualification.test.w

@@ -0,0 +1,43 @@
+bring cloud;
+
+let bucket = new cloud.Bucket();
+bucket.addObject("k", "value");
+
+let put_and_list = ["put", "list"];
+
+class Foo {
+  pub inflight mehtod() {
+    lift(bucket, put_and_list); // Qualify `bucket` with a preflight expression
+    lift(bucket, ["delete"]); // Qualify `bucket` with `delete` via literal
+    let b = bucket; // Assign `bucket` to an inflight variable
+
+    // `put` should work on `b` since we explicitly qualified `bucket` with `put`
+    // no error generated here because of use of `lift()` in this method
+    b.put("k2", "value2"); 
+
+    // validate `put` worked and that we can also `list`
+    assert(b.list() == ["k", "k2"]);
+
+    // Validate `delete` works
+    b.delete("k2");
+    assert(bucket.tryGet("k2") == nil);
+  }
+}
+
+let foo = new Foo();
+
+test "explicit method lift qualification" {
+  foo.mehtod();
+}
+
+// Similar to the above test, but using a closure
+let inflight_closure = inflight () => {
+  lift(bucket, ["put"]);
+  let b = bucket;
+  b.put("k3", "value3"); // Use inflight expression to access explicitly qualified `bucket`
+  assert(bucket.get("k3") == "value3");
+};
+
+test "explicit closure lift qualification" {
+  inflight_closure();
+}

libs/wingc/src/ast.rs

@@ -304,37 +304,6 @@ pub struct Stmt {
 	pub idx: usize,
 }
 
-#[derive(Debug)]
-pub enum UtilityFunctions {
-	Log,
-	Assert,
-	UnsafeCast,
-	Nodeof,
-}
-
-impl UtilityFunctions {
-	/// Returns all utility functions.
-	pub fn all() -> Vec<UtilityFunctions> {
-		vec![
-			UtilityFunctions::Log,
-			UtilityFunctions::Assert,
-			UtilityFunctions::UnsafeCast,
-			UtilityFunctions::Nodeof,
-		]
-	}
-}
-
-impl Display for UtilityFunctions {
-	fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-		match self {
-			UtilityFunctions::Log => write!(f, "log"),
-			UtilityFunctions::Assert => write!(f, "assert"),
-			UtilityFunctions::UnsafeCast => write!(f, "unsafeCast"),
-			UtilityFunctions::Nodeof => write!(f, "nodeof"),
-		}
-	}
-}
-
 #[derive(Debug)]
 pub struct ElifBlock {
 	pub condition: Expr,

libs/wingc/src/jsify.rs

@@ -1855,8 +1855,15 @@ impl<'a> JSifier<'a> {
 			for (method_name, method_qual) in lift_qualifications {
 				bind_method.open(format!("\"{method_name}\": [",));
 				for (code, method_lift_qual) in method_qual {
-					let ops_strings = method_lift_qual.ops.iter().map(|op| format!("\"{}\"", op)).join(", ");
-					bind_method.line(format!("[{code}, [{ops_strings}]],",));
+					let ops = method_lift_qual.ops.iter().join(", ");
+					// To keep the code concise treat no ops, single op and multiple ops differenly here, although the multiple ops is the generic case
+					if method_lift_qual.ops.len() == 0 {
+						bind_method.line(format!("[{code}, []],"));
+					} else if method_lift_qual.ops.len() == 1 {
+						bind_method.line(format!("[{code}, {ops}],"));
+					} else {
+						bind_method.line(format!("[{code}, [].concat({ops})],"));
+					}
 				}
 				bind_method.close("],");
 			}

libs/wingc/src/jsify/snapshots/base_class_lift_indirect.snap

@@ -106,7 +106,7 @@ class $Root extends $stdlib.std.Resource {
       get _liftMap() {
         return ({
           "put": [
-            [this.b, ["list", "put"]],
+            [this.b, [].concat(["put"], ["list"])],
           ],
           "$inflight_init": [
             [this.b, []],

libs/wingc/src/jsify/snapshots/calls_methods_on_preflight_object.snap

@@ -78,7 +78,7 @@ class $Root extends $stdlib.std.Resource {
       get _liftMap() {
         return ({
           "handle": [
-            [b, ["list", "put"]],
+            [b, [].concat(["put"], ["list"])],
           ],
           "$inflight_init": [
             [b, []],

libs/wingc/src/jsify/snapshots/fail_unqualified_lift.snap

@@ -2,4 +2,4 @@
 source: libs/wingc/src/jsify/tests.rs
 ---
 ## Errors
-Expression of type "Queue" references an unknown preflight object, can't qualify its capabilities (see https://github.com/winglang/wing/issues/76 for details) 7:6
+Expression of type "Queue" references an unknown preflight object, can't qualify its capabilities. Use `lift()` to explicitly qualify the preflight object to disable this error. 7:6

libs/wingc/src/jsify/snapshots/fail_unqualified_lift_as_arg.snap

@@ -2,4 +2,4 @@
 source: libs/wingc/src/jsify/tests.rs
 ---
 ## Errors
-Expression of type "Queue" references an unknown preflight object, can't qualify its capabilities (see https://github.com/winglang/wing/issues/76 for details) 6:6
+Expression of type "Queue" references an unknown preflight object, can't qualify its capabilities. Use `lift()` to explicitly qualify the preflight object to disable this error. 6:6

libs/wingc/src/jsify/snapshots/fail_unqualified_lift_element_from_collection_of_objects.snap

@@ -2,4 +2,4 @@
 source: libs/wingc/src/jsify/tests.rs
 ---
 ## Errors
-Expression of type "Bucket" references an unknown preflight object, can't qualify its capabilities (see https://github.com/winglang/wing/issues/76 for details) 6:6
+Expression of type "Bucket" references an unknown preflight object, can't qualify its capabilities. Use `lift()` to explicitly qualify the preflight object to disable this error. 6:6

libs/wingc/src/jsify/snapshots/fail_unqualified_lift_return.snap

@@ -2,4 +2,4 @@
 source: libs/wingc/src/jsify/tests.rs
 ---
 ## Errors
-Expression of type "Queue" references an unknown preflight object, can't qualify its capabilities (see https://github.com/winglang/wing/issues/76 for details) 11:6
+Expression of type "Queue" references an unknown preflight object, can't qualify its capabilities. Use `lift()` to explicitly qualify the preflight object to disable this error. 11:6

libs/wingc/src/jsify/snapshots/preflight_object.snap

@@ -130,7 +130,7 @@ class $Root extends $stdlib.std.Resource {
       get _liftMap() {
         return ({
           "handle": [
-            [pf_obj, ["goodbye", "hello"]],
+            [pf_obj, [].concat(["hello"], ["goodbye"])],
           ],
           "$inflight_init": [
             [pf_obj, []],

libs/wingc/src/jsify/snapshots/preflight_object_with_operations.snap

@@ -77,7 +77,7 @@ class $Root extends $stdlib.std.Resource {
       get _liftMap() {
         return ({
           "handle": [
-            [b, ["list", "put"]],
+            [b, [].concat(["list"], ["put"])],
           ],
           "$inflight_init": [
             [b, []],

libs/wingc/src/jsify/snapshots/reference_preflight_field_from_inflight_expr.snap

@@ -3,4 +3,4 @@ source: libs/wingc/src/jsify/tests.rs
 ---
 ## Errors
 Can't access preflight member "x" on inflight instance of type "A" 9:14
-Expression of type "A" references an unknown preflight object, can't qualify its capabilities (see https://github.com/winglang/wing/issues/76 for details) 9:12
+Expression of type "A" references an unknown preflight object, can't qualify its capabilities. Use `lift()` to explicitly qualify the preflight object to disable this error. 9:12

libs/wingc/src/jsify/snapshots/reference_preflight_fields.snap

@@ -100,7 +100,7 @@ class $Root extends $stdlib.std.Resource {
             [this.s, ["length"]],
           ],
           "bam": [
-            [this.b, ["get", "put"]],
+            [this.b, [].concat(["put"], ["get"])],
           ],
           "$inflight_init": [
             [this.b, []],