jsii 5.8.22-dev.9 → 5.8.23-dev.0

package/lib/assembler.d.ts

@@ -15,6 +15,7 @@ export declare class Assembler implements Emitter {
     private readonly mainFile;
     private readonly tscRootDir?;
     private readonly compressAssembly?;
+    private readonly usedFeatures;
     private readonly _typeChecker;
     private _diagnostics;
     private _deferred;
@@ -56,7 +57,7 @@ export declare class Assembler implements Emitter {
      *
      * @param fqn FQN of the current type (the type that has a dependency on baseTypes)
      * @param baseTypes Array of type references to be looked up
-     * @param referencingNode Node to report a diagnostic on if we fail to look up a t ype
+     * @param referencingNode Node to report a diagnostic on if we fail to look up a type
      * @param cb Callback to be invoked with the Types corresponding to the TypeReferences in baseTypes
      */
     private _deferUntilTypesAvailable;
@@ -164,11 +165,26 @@ export declare class Assembler implements Emitter {
     private _toParameter;
     private _typeReference;
     private _optionalValue;
+    /**
+     * Validate the restrictions on an intersection type reference
+     *
+     * - Type only consists of (behavioral) interface types
+     * - For all types referenced in the intersection, the definitions of all shared
+     *   members must match exactly.
+     */
+    private validateIntersectionType;
+    private comparePropForIntersection;
+    private compareMethodForIntersection;
     private callDeferredsInOrder;
     /**
      * Return the set of all (inherited) properties of an interface
      */
     private allProperties;
+    /**
+     * Return the set of all (inherited) methods of an interface
+     */
+    private allMethods;
+    private allInterfacesRecursively;
     private _verifyConsecutiveOptionals;
     /**
      * Updates the runtime type info with the fully-qualified name for the current class definition.
@@ -181,6 +197,13 @@ export declare class Assembler implements Emitter {
      */
     private mySubmodules;
     private findPackageInfo;
+    /**
+     * Validate types against input/output positions in functions and APIs
+     *
+     * Currently used to validate that intersection types are only used in input position,
+     * not output position
+     */
+    private validateTypesAgainstPositions;
 }
 export interface AssemblerOptions {
     /**

package/lib/assembler.js

@@ -19,10 +19,13 @@ const jsii_diagnostic_1 = require("./jsii-diagnostic");
 const literate = require("./literate");
 const bindings = require("./node-bindings");
 const reserved_words_1 = require("./reserved-words");
+const sets_1 = require("./sets");
 const deprecated_remover_1 = require("./transforms/deprecated-remover");
 const deprecation_warnings_1 = require("./transforms/deprecation-warnings");
 const runtime_info_1 = require("./transforms/runtime-info");
 const utils_1 = require("./transforms/utils");
+const type_reference_1 = require("./type-reference");
+const type_visitor_1 = require("./type-visitor");
 const utils_2 = require("./utils");
 const validator_1 = require("./validator");
 const version_1 = require("./version");
@@ -44,6 +47,7 @@ class Assembler {
         this.system = system;
         this.program = program;
         this.stdlib = stdlib;
+        this.usedFeatures = new Set();
         this._diagnostics = new Array();
         this._deferred = new Array();
         this._types = new Map();
@@ -135,6 +139,7 @@ class Assembler {
             }
         }
         this.callDeferredsInOrder();
+        this.validateTypesAgainstPositions();
         // Skip emitting if any diagnostic message is an error
         if (this._diagnostics.find((diag) => diag.category === ts.DiagnosticCategory.Error) != null) {
             LOG.debug('Skipping emit due to errors.');
@@ -178,6 +183,7 @@ class Assembler {
             jsiiVersion,
             bin: this.projectInfo.bin,
             fingerprint: '<TBD>',
+            usedFeatures: _assemblyFeatures(this.usedFeatures), // might be appended later
         };
         if (this.deprecatedRemover) {
             this._diagnostics.push(...this.deprecatedRemover.removeFrom(assembly));
@@ -197,6 +203,13 @@ class Assembler {
         }
         const validator = new validator_1.Validator(this.projectInfo, assembly);
         const validationResult = validator.emit();
+        // Inject detected features
+        if (validationResult.usedFeatures) {
+            for (const item of validationResult.usedFeatures) {
+                this.usedFeatures.add(item);
+            }
+            assembly.usedFeatures = _assemblyFeatures(this.usedFeatures);
+        }
         if (!validationResult.emitSkipped) {
             const zipped = (0, spec_1.writeAssembly)(this.projectInfo.projectRoot, _fingerprint(assembly), {
                 compress: this.compressAssembly ?? false,
@@ -212,6 +225,9 @@ class Assembler {
         finally {
             this._afterEmit();
         }
+        function _assemblyFeatures(usedFeatures) {
+            return usedFeatures.size > 0 ? Array.from(usedFeatures).sort() : undefined;
+        }
         function _loadReadme() {
             // Search for `README.md` in a case-insensitive way
             const fileName = fs
@@ -251,7 +267,7 @@ class Assembler {
      *
      * @param fqn FQN of the current type (the type that has a dependency on baseTypes)
      * @param baseTypes Array of type references to be looked up
-     * @param referencingNode Node to report a diagnostic on if we fail to look up a t ype
+     * @param referencingNode Node to report a diagnostic on if we fail to look up a type
      * @param cb Callback to be invoked with the Types corresponding to the TypeReferences in baseTypes
      */
     _deferUntilTypesAvailable(fqn, baseTypes, referencingNode, cb) {
@@ -260,9 +276,19 @@ class Assembler {
             cb();
             return;
         }
-        const baseFqns = baseTypes.map((bt) => (typeof bt === 'string' ? bt : bt.fqn));
+        const baseFqns = baseTypes.flatMap((bt) => {
+            if (typeof bt === 'string') {
+                return [bt];
+            }
+            if (spec.isNamedTypeReference(bt)) {
+                return [bt.fqn];
+            }
+            return [];
+        });
         this._defer(fqn, baseFqns, () => {
-            const resolved = baseFqns.map((x) => this._dereference(x, referencingNode)).filter((x) => x !== undefined);
+            const resolved = baseFqns
+                .map((x) => this._dereference(x, referencingNode, 'used-in-syntax'))
+                .filter((x) => x !== undefined);
             if (resolved.length > 0) {
                 cb(...resolved);
             }
@@ -290,7 +316,7 @@ class Assembler {
      *
      * @returns the de-referenced type, if it was found, otherwise ``undefined``.
      */
-    _dereference(ref, referencingNode) {
+    _dereference(ref, referencingNode, usedInSyntax) {
         if (typeof ref !== 'string') {
             ref = ref.fqn;
         }
@@ -311,7 +337,7 @@ class Assembler {
                 }
             }
         }
-        if (!type) {
+        if (!type && usedInSyntax === 'used-in-syntax') {
             this._diagnostics.push(jsii_diagnostic_1.JsiiDiagnostic.JSII_9002_UNRESOLVEABLE_TYPE.create(referencingNode, // Cheating here for now, until the referencingNode can be made required
             ref));
         }
@@ -390,7 +416,7 @@ class Assembler {
             assembly: dep,
         });
         const fqn = (dep && symbolId ? symbolIdIndex(dep)[symbolId] : undefined) ?? fallbackFqn;
-        if (!fqn || !this._dereference({ fqn }, sym.valueDeclaration)) {
+        if (!fqn || !this._dereference({ fqn }, sym.valueDeclaration, 'used-in-syntax')) {
             if (!hasError) {
                 this._diagnostics.push(jsii_diagnostic_1.JsiiDiagnostic.JSII_3002_USE_OF_UNEXPORTED_FOREIGN_TYPE.create(typeAnnotationNode, fqn ?? tsName, typeUse, pkg).addRelatedInformationIf(typeDeclaration, 'The referenced type is declared here'));
                 hasError = true;
@@ -1003,9 +1029,12 @@ class Assembler {
                 if (signature) {
                     for (const param of signature.getParameters()) {
                         jsiiType.initializer.parameters = jsiiType.initializer.parameters ?? [];
-                        jsiiType.initializer.parameters.push(
-                        // eslint-disable-next-line no-await-in-loop
-                        this._toParameter(param, ctx.replaceStability(jsiiType.docs?.stability)));
+                        const jsiiParam = // eslint-disable-next-line no-await-in-loop
+                         this._toParameter(param, ctx.replaceStability(jsiiType.docs?.stability));
+                        if (containsIntersection(jsiiParam.type)) {
+                            this._diagnostics.push(jsii_diagnostic_1.JsiiDiagnostic.JSII_1010_INTERSECTION_NOT_IN_CTOR.create(param.declarations?.[0]));
+                        }
+                        jsiiType.initializer.parameters.push(jsiiParam);
                         jsiiType.initializer.variadic = jsiiType.initializer?.parameters?.some((p) => !!p.variadic) || undefined;
                         jsiiType.initializer.protected =
                             (ts.getCombinedModifierFlags(ctorDeclaration) & ts.ModifierFlags.Protected) !== 0 || undefined;
@@ -1067,7 +1096,7 @@ class Assembler {
             .filter((x) => !x.static)
             .map((x) => x.name));
         // Intersect
-        for (const member of intersect(statics, nonStatics)) {
+        for (const member of sets_1.Sets.intersect(statics, nonStatics)) {
             this._diagnostics.push(jsii_diagnostic_1.JsiiDiagnostic.JSII_5013_STATIC_INSTANCE_CONFLICT.create(decl, member, klass));
         }
         // Check against base classes. They will not contain duplicate member names so we can load
@@ -1433,7 +1462,7 @@ class Assembler {
                 // Liftable datatype, make sure no parameter names match any of the properties in the datatype
                 const propNames = this.allProperties(lastParamType);
                 const paramNames = new Set(parameters.slice(0, parameters.length - 1).map((x) => x.name));
-                const sharedNames = intersection(propNames, paramNames);
+                const sharedNames = sets_1.Sets.intersection(propNames, paramNames);
                 for (const badName of sharedNames) {
                     this._diagnostics.push(jsii_diagnostic_1.JsiiDiagnostic.JSII_5017_POSITIONAL_KEYWORD_CONFLICT.create(declaration, badName));
                 }
@@ -1568,7 +1597,18 @@ class Assembler {
             return { type: primitiveType };
         }
         if (type.isUnion() && !_isEnumLike(type)) {
-            return _unionType.call(this);
+            return _setType.call(this, 'union');
+        }
+        if (type.isIntersection()) {
+            this.usedFeatures.add('intersection-types');
+            const ret = _setType.call(this, 'intersection');
+            const intersectionType = ret.type;
+            this.validateIntersectionType(intersectionType, declaration);
+            return ret;
+        }
+        if ((type.getFlags() & ts.TypeFlags.Never) !== 0) {
+            this._diagnostics.push(jsii_diagnostic_1.JsiiDiagnostic.JSII_1007_NEVER_TYPE.create(declaration));
+            return { type: spec.CANONICAL_ANY };
         }
         if (!type.symbol) {
             this._diagnostics.push(jsii_diagnostic_1.JsiiDiagnostic.JSII_1001_TYPE_HAS_NO_SYMBOL.create(declaration));
@@ -1674,7 +1714,7 @@ class Assembler {
             // Not a primitive type!
             return undefined;
         }
-        function _unionType() {
+        function _setType(field) {
             const types = new Array();
             let optional;
             for (const subType of type.types) {
@@ -1689,16 +1729,112 @@ class Assembler {
                 }
                 types.push(resolvedType);
             }
-            return types.length === 1 ? { optional, type: types[0] } : { optional, type: { union: { types } } };
+            const returnedType = {
+                [field]: { types },
+            };
+            return types.length === 1 ? { optional, type: types[0] } : { optional, type: returnedType };
         }
     }
+    /**
+     * Validate the restrictions on an intersection type reference
+     *
+     * - Type only consists of (behavioral) interface types
+     * - For all types referenced in the intersection, the definitions of all shared
+     *   members must match exactly.
+     */
+    validateIntersectionType(intersectionType, declaration) {
+        // Validate that this intersection type only consists of interface types
+        this._deferUntilTypesAvailable('', intersectionType.intersection.types, declaration, (...elementTypes) => {
+            const requestedFqns = new Set(intersectionType.intersection.types.map(type_reference_1.typeReferenceToString));
+            const resolvedFqns = new Set(elementTypes.map((t) => t.fqn));
+            const unresolved = sets_1.Sets.diff(requestedFqns, resolvedFqns);
+            if (unresolved.size > 0) {
+                this._diagnostics.push(jsii_diagnostic_1.JsiiDiagnostic.JSII_1008_ONLY_INTERFACE_INTERSECTION.create(declaration, Array.from(unresolved).join(', ')));
+            }
+            const nonBehavioral = elementTypes.filter((t) => !(0, type_visitor_1.isBehavioralInterfaceType)(t));
+            if (nonBehavioral.length > 0) {
+                this._diagnostics.push(jsii_diagnostic_1.JsiiDiagnostic.JSII_1008_ONLY_INTERFACE_INTERSECTION.create(declaration, nonBehavioral.map((t) => t.fqn).join(', ')));
+            }
+            // Check that shared members are the same
+            const interfaces = elementTypes.filter(type_visitor_1.isBehavioralInterfaceType);
+            const allProps = sets_1.Sets.union(...interfaces.map((int) => this.allProperties(int)));
+            const allMethods = sets_1.Sets.union(...interfaces.map((int) => this.allMethods(int)));
+            for (let i = 1; i < interfaces.length; i++) {
+                let int0 = interfaces[0];
+                let int1 = interfaces[i];
+                for (const prop of allProps) {
+                    const p1 = int0.properties?.find((p) => p.name === prop);
+                    const p2 = int1.properties?.find((p) => p.name === prop);
+                    const diff = this.comparePropForIntersection(p1, p2);
+                    if (diff) {
+                        this._diagnostics.push(jsii_diagnostic_1.JsiiDiagnostic.JSII_1011_INTERSECTION_MEMBER_DIFFERENT.create(declaration, prop, int0.name, diff[0], int1.name, diff[1]));
+                    }
+                }
+                for (const meth of allMethods) {
+                    const m1 = int0.methods?.find((p) => p.name === meth);
+                    const m2 = int1.methods?.find((p) => p.name === meth);
+                    const diff = this.compareMethodForIntersection(m1, m2);
+                    if (diff) {
+                        this._diagnostics.push(jsii_diagnostic_1.JsiiDiagnostic.JSII_1011_INTERSECTION_MEMBER_DIFFERENT.create(declaration, meth, int0.name, diff[0], int1.name, diff[1]));
+                    }
+                }
+            }
+        });
+    }
+    comparePropForIntersection(a, b) {
+        if (!a || !b) {
+            return undefined;
+        }
+        if (!(0, type_reference_1.typeReferenceEqual)(a.type, b.type)) {
+            return [(0, type_reference_1.typeReferenceToString)(a.type), (0, type_reference_1.typeReferenceToString)(b.type)];
+        }
+        return (cmpDesc(a.static, b.static, (s) => (s ? 'static' : 'instance member')) ??
+            cmpDesc(a.optional, b.optional, (o) => (o ? 'optional' : 'required')) ??
+            cmpDesc(a.abstract, b.abstract, (s) => (s ? 'abstract' : 'concrete')));
+    }
+    compareMethodForIntersection(a, b) {
+        if (!a || !b) {
+            return undefined;
+        }
+        if (a.returns && b.returns) {
+            if (!(0, type_reference_1.typeReferenceEqual)(a.returns.type, b.returns.type)) {
+                return [(0, type_reference_1.typeReferenceToString)(a.returns.type), (0, type_reference_1.typeReferenceToString)(b.returns.type)];
+            }
+            const x = cmpDesc(a.returns.optional, b.returns.optional, (o) => o ? 'return type optional' : 'return type required');
+            if (x) {
+                return x;
+            }
+        }
+        const paramsA = a.parameters ?? [];
+        const paramsB = b.parameters ?? [];
+        if (paramsA.length !== paramsB.length) {
+            return [`${paramsA.length} parameters`, `${paramsB.length} parameters`];
+        }
+        for (let i = 0; i < paramsA.length; i++) {
+            const p1 = paramsA[i];
+            const p2 = paramsB[i];
+            if (!(0, type_reference_1.typeReferenceEqual)(p1.type, p2.type)) {
+                return [(0, type_reference_1.typeReferenceToString)(p1.type), (0, type_reference_1.typeReferenceToString)(p2.type)];
+            }
+            const x = cmpDesc(p1.optional, p2.optional, (o) => (o ? `parameter ${i + 1} optional` : `parameter ${i + 1} required`)) ??
+                cmpDesc(p1.variadic, p2.variadic, (v) => v ? `parameter ${i + 1} variadic` : `parameter ${i + 1} not variadic`);
+            if (x) {
+                return x;
+            }
+        }
+        return (cmpDesc(a.abstract, b.abstract, (s) => (s ? 'abstract' : 'concrete')) ??
+            cmpDesc(a.async, b.async, (s) => (s ? 'async' : 'async')) ??
+            cmpDesc(a.protected, b.protected, (p) => (p ? 'protected' : 'public')) ??
+            cmpDesc(a.variadic, b.variadic, (v) => (v ? 'variadic' : 'non-variadic')) ??
+            cmpDesc(a.static, b.static, (s) => (s ? 'static' : 'instance member')));
+    }
     callDeferredsInOrder() {
         // Do a topological call order of all deferreds.
         while (this._deferred.length > 0) {
             // All fqns in dependency lists that don't have any pending
             // deferreds themselves can be executed now, so are removed from
             // dependency lists.
-            const pendingFqns = new Set(this._deferred.map((x) => x.fqn));
+            const pendingFqns = new Set(this._deferred.map((x) => x.fqn).filter((x) => x));
             for (const deferred of this._deferred) {
                 restrictDependenciesTo(deferred, pendingFqns);
             }
@@ -1727,20 +1863,33 @@ class Assembler {
      * Return the set of all (inherited) properties of an interface
      */
     allProperties(root) {
+        return this.allInterfacesRecursively(root, (int) => {
+            return (int.properties ?? []).map((p) => p.name);
+        });
+    }
+    /**
+     * Return the set of all (inherited) methods of an interface
+     */
+    allMethods(root) {
+        return this.allInterfacesRecursively(root, (int) => {
+            return (int.methods ?? []).map((p) => p.name);
+        });
+    }
+    allInterfacesRecursively(root, cb) {
         const ret = new Set();
         recurse.call(this, root);
         return ret;
         function recurse(int) {
-            for (const property of int.properties ?? []) {
-                ret.add(property.name);
+            for (const x of cb(int)) {
+                ret.add(x);
             }
             for (const baseRef of int.interfaces ?? []) {
-                const base = this._dereference(baseRef, undefined);
+                const base = this._dereference(baseRef, undefined, 'used-in-syntax');
                 if (!base) {
-                    throw new Error('Impossible to have unresolvable base in allProperties()');
+                    throw new Error('Impossible to have unresolvable base in allInterfacesRecursively()');
                 }
                 if (!spec.isInterfaceType(base)) {
-                    throw new Error('Impossible to have non-interface base in allProperties()');
+                    throw new Error('Impossible to have non-interface base in allInterfacesRecursively()');
                 }
                 recurse.call(this, base);
             }
@@ -1796,6 +1945,89 @@ class Assembler {
             return this.findPackageInfo(parent);
         }
     }
+    /**
+     * Validate types against input/output positions in functions and APIs
+     *
+     * Currently used to validate that intersection types are only used in input position,
+     * not output position
+     */
+    validateTypesAgainstPositions() {
+        const self = this;
+        const validatedFqns = {
+            in: new Set(),
+            out: new Set(),
+        };
+        for (const type of this._types.values()) {
+            if (spec.isClassType(type)) {
+                for (const ctorParam of type.initializer?.parameters ?? []) {
+                    validateRefFor.call(this, 'in', ctorParam.type, `a constructor parameter of ${type.name}`);
+                }
+            }
+            if (spec.isClassType(type) || (0, type_visitor_1.isBehavioralInterfaceType)(type)) {
+                for (const property of type.properties ?? []) {
+                    validateRefFor.call(this, 'out', property.type, `type of property ${type.name}.${property.name}`);
+                }
+                for (const method of type.methods ?? []) {
+                    for (const param of method.parameters ?? []) {
+                        validateRefFor.call(this, 'in', param.type, `a parameter of method ${type.name}.${method.name}()`);
+                    }
+                    if (method.returns) {
+                        validateRefFor.call(this, 'out', method.returns.type, `return type of method ${type.name}.${method.name}()`);
+                    }
+                }
+            }
+        }
+        function validateRefFor(dir, typeRef, reason) {
+            (0, type_visitor_1.visitTypeReference)(typeRef, {
+                named: (ref) => {
+                    // Named types we'll only validate once for every direction
+                    if (validatedFqns[dir].has(ref.fqn)) {
+                        return;
+                    }
+                    validatedFqns[dir].add(ref.fqn);
+                    const type = self._dereference(ref, undefined, 'just-validating');
+                    if (!type) {
+                        // Maybe this is an unexported type.
+                        return;
+                    }
+                    validateTypeFor(dir, type, reason);
+                },
+                primitive: () => { },
+                collection: (ref) => {
+                    validateRefFor(dir, ref.collection.elementtype, reason);
+                },
+                union: (ref) => {
+                    for (const t of ref.union.types) {
+                        validateRefFor(dir, t, reason);
+                    }
+                },
+                intersection: (ref) => {
+                    if (dir === 'out') {
+                        self._diagnostics.push(jsii_diagnostic_1.JsiiDiagnostic.JSII_1009_INTERSECTION_ONLY_INPUT.createDetached(reason));
+                    }
+                    for (const t of ref.intersection.types) {
+                        validateRefFor(dir, t, reason);
+                    }
+                },
+            });
+        }
+        function validateTypeFor(dir, type, reason) {
+            (0, type_visitor_1.visitType)(type, {
+                dataType: (t) => {
+                    // We only need to validate data types, because classes and interfaces
+                    // are done as part of the main loop.
+                    //
+                    // Recurse.
+                    for (const prop of t.properties ?? []) {
+                        validateRefFor(dir, prop.type, `type of property ${t.name}.${prop.name}, ${reason}`);
+                    }
+                },
+                classType: () => { },
+                interfaceType: () => { },
+                enumType: () => { },
+            });
+        }
+    }
 }
 exports.Assembler = Assembler;
 function _fingerprint(assembly) {
@@ -1929,18 +2161,6 @@ function last(xs) {
 function apply(x, fn) {
     return x !== undefined ? fn(x) : undefined;
 }
-/**
- * Return the intersection of two sets
- */
-function intersection(xs, ys) {
-    const ret = new Set();
-    for (const x of xs) {
-        if (ys.has(x)) {
-            ret.add(x);
-        }
-    }
-    return ret;
-}
 /**
  * Return all members names of a JSII interface type
  *
@@ -1971,12 +2191,10 @@ function isInterfaceName(name) {
 function getConstructor(type) {
     return type.symbol.members?.get(ts.InternalSymbolName.Constructor);
 }
-function* intersect(xs, ys) {
-    for (const x of xs) {
-        if (ys.has(x)) {
-            yield x;
-        }
-    }
+function cmpDesc(a, b, desc) {
+    const desc1 = desc(a);
+    const desc2 = desc(b);
+    return desc1 !== desc2 ? [desc1, desc2] : undefined;
 }
 function noEmptyDict(xs) {
     if (xs == null || Object.keys(xs).length === 0) {
@@ -2160,6 +2378,18 @@ function _findHint(decl, hint) {
     const [node] = ts.getAllJSDocTags(decl, (tag) => tag.tagName.text === hint);
     return node;
 }
+function containsIntersection(type) {
+    if (spec.isIntersectionTypeReference(type)) {
+        return true;
+    }
+    if (spec.isUnionTypeReference(type)) {
+        return type.union.types.some(containsIntersection);
+    }
+    if (spec.isCollectionTypeReference(type)) {
+        return containsIntersection(type.collection.elementtype);
+    }
+    return false;
+}
 /**
  * Resolve a Type to Symbol, taking into account single-valued enums which have a bug
  *