jsii-diff 1.117.0 → 1.119.0

package/BREAKING_CHANGES.md

@@ -49,7 +49,9 @@ const d = new Dog({ name: 'Fido' });
 console.log(d.name.toLowerCase());
 
 // Not valid anymore after the type of `d.name` has changed into `string | undefined`.
-// 'd.name' can be undefined, and we have to account for that with an `if`!
+// 'd.name' can be undefined, and calling `undefined.toLowerCase()` would throw an error.
+// The user will have to account for that with an `if`, which means changing their code,
+// which means a breaking change.
 ```
 
 ### Optional properties: how to solve
@@ -83,6 +85,30 @@ This doesn't break any existing users: all their Dogs will have names, so they w
 
 For new users that fail to give their Dog a name, presumably they will be aware that their Dog doesn't have a name, so they can avoid trying to read it. If you want to give them a way to avoid the exception, add a `public get hasName(): boolean` field so they can test for the existence of the name before accessing it.
 
+### Optional properties: what about structs?
+
+In the above example, we said that `DogOptions#name` was an *input* and `Dog#name` was an *output*. Does that mean it's
+always okay to change struct (data interface) fields to optional? 
+
+Not necessarily! It depends on how the struct is used. If the struct is used as the return value of a method or the 
+type of a class proeprty somewhere, it is in *output position* and all of its fields are as well. So if you have the following
+class:
+
+```ts
+class Dog {
+  public readonly options: DogOptions; // DogOptions is an OUTPUT
+
+  constructor(options: DogOptions) {  // DogOptions is an INPUT
+    this.options = options;
+  }
+}
+```
+
+Then `DogOptions` is now both in input as well as output position, and you're not allowed to make anything optional anymore!
+
+(That's why using the same struct name to represent both input and output data is best avoided, because it limits
+evolvability).
+
 ## Changing types to superclass/subclass
 
 When changing types involved in an operation, you run into a similar issue as with changing the optionality of a property:

package/README.md

@@ -126,6 +126,45 @@ abstract members yet.
 for subclassing, but treating them as such would limit the evolvability of
 libraries too much.
 
+## Accepting breaking changes
+
+Sometimes you want to move forward with a change, even if it would technically
+be a breaking change to your API. In order to do that, run `jsii-diff`
+with the flag `--keys`. It will then print an identifier for every violation
+between square brackets, for example:
+
+```
+$ jsii-diff <old> --keys
+IFACE pkg.MyStruct: formerly required property 'prop' is optional: returned from pkg.IConsumer.someMethod [weakened:pkg.MyStruct]
+```
+
+To accept a breaking finding, put the key (in this example `weakened:pkg.MyStruct`)
+into a text file, for example `allowed-breaking-changes.txt`, and pass it to
+`jsii-diff` as an ignore file:
+
+```
+$ jsii-diff <old> --keys --ignore-file allowed-breaking-changes.txt
+(no error)
+```
+
+### Moving/renaming API elements
+
+If you've moved API elements around between versions of your library, you can
+put a special ignore marker starting with `move:` into your `--ignore-file`.  To
+separate the old and new class names, you can use `:`, `,` or whitespace.
+
+For example:
+
+```
+move:package.OldClassName    package.NewClassName
+move:package.OldClassName:package.NewClassName
+move:package.OldClassName, package.NewClassName
+```
+
+Moving API elements is always breaking, but using this feature you can confirm
+that you at least didn't break anything in the API surface of the moved classes
+themselves.
+
 ## Help! jsii-diff is marking my changes as breaking
 
 See [BREAKING_CHANGES.md](./BREAKING_CHANGES.md) for more information.

package/bin/jsii-diff.js

@@ -91,13 +91,16 @@ async function main() {
     if (original.name !== updated.name) {
         process.stderr.write(`Look like different assemblies: '${original.name}' vs '${updated.name}'. Comparing is probably pointless...\n`);
     }
+    const allowedBreakingChanges = await loadFilter(argv['ignore-file']);
+    const fqnRemapping = extractFqnRemappings(allowedBreakingChanges);
     LOG.info('Starting analysis');
     const mismatches = (0, lib_1.compareAssemblies)(original, updated, {
         defaultExperimental: argv['default-stability'] === 'experimental',
+        fqnRemapping,
     });
     LOG.info(`Found ${mismatches.count} issues`);
     if (mismatches.count > 0) {
-        const diags = (0, diagnostics_1.classifyDiagnostics)(mismatches, (0, diagnostics_1.treatAsError)(argv['error-on'], argv['experimental-errors']), await loadFilter(argv['ignore-file']));
+        const diags = (0, diagnostics_1.classifyDiagnostics)(mismatches, (0, diagnostics_1.treatAsError)(argv['error-on'], argv['experimental-errors']), allowedBreakingChanges);
         process.stderr.write(`Original assembly: ${original.name}@${original.version}\n`);
         process.stderr.write(`Updated assembly: ${updated.name}@${updated.version}\n`);
         process.stderr.write('API elements with incompatible changes:\n');
@@ -108,6 +111,35 @@ async function main() {
     }
     return 0;
 }
+/**
+ * Extract all lines that start with `move:` from the given string set
+ *
+ * Interpret them as `move:OLDFQN <sep> NEWFQN`, mapping moved FQNs.
+ *
+ * Separator can be any of `:`, comma or whitespace.
+ *
+ * Modifies the input set in-place.
+ */
+function extractFqnRemappings(allowedBreakingChanges) {
+    const ret = {};
+    for (const line of Array.from(allowedBreakingChanges)) {
+        const prefix = 'move:';
+        if (!line.startsWith(prefix)) {
+            continue;
+        }
+        const parts = line
+            .slice(prefix.length)
+            .trim()
+            .split(/[:, \t]+/g);
+        if (parts.length !== 2) {
+            throw new Error(`Invalid moved FQN declaration: ${line}. Expected format is 'move:old:new'`);
+        }
+        const [oldFqn, newFqn] = parts;
+        ret[oldFqn] = newFqn;
+        allowedBreakingChanges.delete(line);
+    }
+    return ret;
+}
 // Allow both npm:<package> (legacy) and npm://<package> (looks better)
 const NPM_REGEX = /^npm:(\/\/)?/;
 /**
@@ -234,7 +266,7 @@ async function loadFilter(filterFilename) {
         return new Set((await fs.readFile(filterFilename, { encoding: 'utf-8' }))
             .split('\n')
             .map((x) => x.trim())
-            .filter((x) => !x.startsWith('#')));
+            .filter((x) => x && !x.startsWith('#')));
     }
     catch (e) {
         if (e.code !== 'ENOENT') {

package/lib/type-analysis.d.ts

@@ -1,34 +1,39 @@
 import * as reflect from 'jsii-reflect';
-/**
- * Check whether A is a supertype of B
- *
- * Put differently: whether any value of type B would be assignable to a
- * variable of type A.
- *
- * We always check the relationship in the NEW (latest, updated) typesystem.
- */
-export declare function isSuperType(a: reflect.TypeReference, b: reflect.TypeReference, updatedSystem: reflect.TypeSystem): Analysis;
-/**
- * Find types A and B in the updated type system, and check whether they have a supertype relationship in the type system
- */
-export declare function isNominalSuperType(a: reflect.TypeReference, b: reflect.TypeReference, updatedSystem: reflect.TypeSystem): Analysis;
-/**
- * Is struct A a structural supertype of struct B?
- *
- * Trying to answer the question, is this assignment legal for all values
- * of `expr in B`.
- *
- * ```ts
- * const var: A = expr as B;
- * ```
- *
- * A is a structural supertype of B if all required members of A are also
- * required in B, and of a compatible type.
- *
- * Nullable members of A must either not exist in B, or be of a compatible
- * type.
- */
-export declare function isStructuralSuperType(a: reflect.InterfaceType, b: reflect.InterfaceType, updatedSystem: reflect.TypeSystem): Analysis;
+export declare class TypeAnalysis {
+    private readonly updatedSystem;
+    private readonly fqnRemapping;
+    constructor(updatedSystem: reflect.TypeSystem, fqnRemapping?: Record<string, string>);
+    /**
+     * Check whether A is a supertype of B
+     *
+     * Put differently: whether any value of type B would be assignable to a
+     * variable of type A.
+     *
+     * We always check the relationship in the NEW (latest, updated) typesystem.
+     */
+    isSuperType(a: reflect.TypeReference, b: reflect.TypeReference): Analysis;
+    /**
+     * Find types A and B in the updated type system, and check whether they have a supertype relationship in the type system
+     */
+    isNominalSuperType(a: reflect.TypeReference, b: reflect.TypeReference): Analysis;
+    /**
+     * Is struct A a structural supertype of struct B?
+     *
+     * Trying to answer the question, is this assignment legal for all values
+     * of `expr in B`.
+     *
+     * ```ts
+     * const var: A = expr as B;
+     * ```
+     *
+     * A is a structural supertype of B if all required members of A are also
+     * required in B, and of a compatible type.
+     *
+     * Nullable members of A must either not exist in B, or be of a compatible
+     * type.
+     */
+    isStructuralSuperType(a: reflect.InterfaceType, b: reflect.InterfaceType): Analysis;
+}
 export type Analysis = {
     success: true;
 } | FailedAnalysis;

package/lib/type-analysis.js

@@ -1,180 +1,185 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isSuperType = isSuperType;
-exports.isNominalSuperType = isNominalSuperType;
-exports.isStructuralSuperType = isStructuralSuperType;
+exports.TypeAnalysis = void 0;
 exports.prependReason = prependReason;
 const util_1 = require("./util");
-/**
- * Check whether A is a supertype of B
- *
- * Put differently: whether any value of type B would be assignable to a
- * variable of type A.
- *
- * We always check the relationship in the NEW (latest, updated) typesystem.
- */
-function isSuperType(a, b, updatedSystem) {
-    if (a.void || b.void) {
-        throw new Error('isSuperType() does not handle voids');
-    }
-    if (a.isAny) {
-        return { success: true };
-    }
-    if (a.primitive !== undefined) {
-        if (a.primitive === b.primitive) {
+class TypeAnalysis {
+    constructor(updatedSystem, fqnRemapping = {}) {
+        this.updatedSystem = updatedSystem;
+        this.fqnRemapping = fqnRemapping;
+    }
+    /**
+     * Check whether A is a supertype of B
+     *
+     * Put differently: whether any value of type B would be assignable to a
+     * variable of type A.
+     *
+     * We always check the relationship in the NEW (latest, updated) typesystem.
+     */
+    isSuperType(a, b) {
+        if (a.void || b.void) {
+            throw new Error('isSuperType() does not handle voids');
+        }
+        if (a.isAny) {
             return { success: true };
         }
-        return failure(`${b.toString()} is not assignable to ${a.toString()}`);
-    }
-    if (a.arrayOfType !== undefined) {
-        // Arrays are covariant
-        if (b.arrayOfType === undefined) {
-            return failure(`${b.toString()} is not an array type`);
+        if (a.primitive !== undefined) {
+            if (a.primitive === b.primitive) {
+                return { success: true };
+            }
+            return failure(`${b.toString()} is not assignable to ${a.toString()}`);
         }
-        return prependReason(isSuperType(a.arrayOfType, b.arrayOfType, updatedSystem), `${b.toString()} is not assignable to ${a.toString()}`);
-    }
-    if (a.mapOfType !== undefined) {
-        // Maps are covariant (are they?)
-        if (b.mapOfType === undefined) {
-            return failure(`${b.toString()} is not a map type`);
+        if (a.arrayOfType !== undefined) {
+            // Arrays are covariant
+            if (b.arrayOfType === undefined) {
+                return failure(`${b.toString()} is not an array type`);
+            }
+            return prependReason(this.isSuperType(a.arrayOfType, b.arrayOfType), `${b.toString()} is not assignable to ${a.toString()}`);
         }
-        return prependReason(isSuperType(a.mapOfType, b.mapOfType, updatedSystem), `${b.toString()} is not assignable to ${a.toString()}`);
-    }
-    // Every element of B can be assigned to A
-    if (b.unionOfTypes !== undefined) {
-        const analyses = b.unionOfTypes.map((bbb) => isSuperType(a, bbb, updatedSystem));
-        if (analyses.every((x) => x.success)) {
-            return { success: true };
+        if (a.mapOfType !== undefined) {
+            // Maps are covariant (are they?)
+            if (b.mapOfType === undefined) {
+                return failure(`${b.toString()} is not a map type`);
+            }
+            return prependReason(this.isSuperType(a.mapOfType, b.mapOfType), `${b.toString()} is not assignable to ${a.toString()}`);
         }
-        return failure(`some of ${b.toString()} are not assignable to ${a.toString()}`, ...(0, util_1.flatMap)(analyses, (x) => (x.success ? [] : x.reasons)));
-    }
-    // There should be an element of A which can accept all of B
-    if (a.unionOfTypes !== undefined) {
-        const analyses = a.unionOfTypes.map((aaa) => isSuperType(aaa, b, updatedSystem));
-        if (analyses.some((x) => x.success)) {
+        // Every element of B can be assigned to A
+        if (b.unionOfTypes !== undefined) {
+            const analyses = b.unionOfTypes.map((bbb) => this.isSuperType(a, bbb));
+            if (analyses.every((x) => x.success)) {
+                return { success: true };
+            }
+            return failure(`some of ${b.toString()} are not assignable to ${a.toString()}`, ...(0, util_1.flatMap)(analyses, (x) => (x.success ? [] : x.reasons)));
+        }
+        // There should be an element of A which can accept all of B
+        if (a.unionOfTypes !== undefined) {
+            const analyses = a.unionOfTypes.map((aaa) => this.isSuperType(aaa, b));
+            if (analyses.some((x) => x.success)) {
+                return { success: true };
+            }
+            return failure(`none of ${b.toString()} are assignable to ${a.toString()}`, ...(0, util_1.flatMap)(analyses, (x) => (x.success ? [] : x.reasons)));
+        }
+        // intersection A ⊒ B <=> all of the elements of A ⊒ B
+        if (a.intersectionOfTypes !== undefined) {
+            const analyses = a.intersectionOfTypes.map((aaa) => this.isSuperType(aaa, b));
+            if (analyses.every((x) => x.success)) {
+                return { success: true };
+            }
+            return failure(`${b.toString()} is not assignable to all of ${a.toString()}`, ...(0, util_1.flatMap)(analyses, (x) => (x.success ? [] : x.reasons)));
+        }
+        // A ⊒ intersection B <=> A ⊒ any of the elements of B
+        if (b.intersectionOfTypes !== undefined) {
+            const analyses = b.intersectionOfTypes.map((bbb) => this.isSuperType(a, bbb));
+            if (analyses.some((x) => x.success)) {
+                return { success: true };
+            }
+            return failure(`some of ${b.toString()} are not assignable to ${a.toString()}`, ...(0, util_1.flatMap)(analyses, (x) => (x.success ? [] : x.reasons)));
+        }
+        // We have two named types, recursion might happen so protect against it.
+        try {
+            // For named types, we'll always do a nominal typing relationship.
+            // That is, if in the updated typesystem someone were to use the type name
+            // from the old assembly, do they have a typing relationship that's accepted
+            // by a nominal type system. (That check also rules out enums)
+            const nominalCheck = this.isNominalSuperType(a, b);
+            if (nominalCheck.success === false) {
+                return nominalCheck;
+            }
+            // At this point, the only thing left to do is recurse into the structs.
+            // We used to do that here, but we don't anymore; structs check themselves
+            // for structural weakening/strengthening.
             return { success: true };
         }
-        return failure(`none of ${b.toString()} are assignable to ${a.toString()}`, ...(0, util_1.flatMap)(analyses, (x) => (x.success ? [] : x.reasons)));
+        catch (e) {
+            return failure(e.message);
+        }
     }
-    // intersection A ⊒ B <=> all of the elements of A ⊒ B
-    if (a.intersectionOfTypes !== undefined) {
-        const analyses = a.intersectionOfTypes.map((aaa) => isSuperType(aaa, b, updatedSystem));
-        if (analyses.every((x) => x.success)) {
+    /**
+     * Find types A and B in the updated type system, and check whether they have a supertype relationship in the type system
+     */
+    isNominalSuperType(a, b) {
+        if (a.fqn === undefined) {
+            throw new Error(`I was expecting a named type, got '${a.toString()}'`);
+        }
+        // Named type vs a non-named type
+        if (b.fqn === undefined) {
+            return failure(`${b.toString()} is not assignable to ${a.toString()}`);
+        }
+        // Short-circuit of the types are the same name, saves us some lookup
+        if (a.fqn === b.fqn) {
             return { success: true };
         }
-        return failure(`${b.toString()} is not assignable to all of ${a.toString()}`, ...(0, util_1.flatMap)(analyses, (x) => (x.success ? [] : x.reasons)));
-    }
-    // A ⊒ intersection B <=> A ⊒ any of the elements of B
-    if (b.intersectionOfTypes !== undefined) {
-        const analyses = b.intersectionOfTypes.map((bbb) => isSuperType(a, bbb, updatedSystem));
-        if (analyses.some((x) => x.success)) {
+        // We now need to do subtype analysis on the
+        // Find A in B's typesystem, and see if B is a subtype of A'
+        const B = this.updatedSystem.tryFindFqn(this.fqnRemapping[b.fqn] ?? b.fqn);
+        const A = this.updatedSystem.tryFindFqn(this.fqnRemapping[a.fqn] ?? a.fqn);
+        if (!B) {
+            return failure(`could not find type ${b.toString()}`);
+        }
+        if (!A) {
+            return failure(`could not find type ${a.toString()}`);
+        }
+        // If they're enums, they should have been exactly the same (tested above)
+        // enums are never subtypes of any other type.
+        if (A.isEnumType()) {
+            return failure(`${a.toString()} is an enum different from ${b.toString()}`);
+        }
+        if (B.isEnumType()) {
+            return failure(`${b.toString()} is an enum different from ${a.toString()}`);
+        }
+        if (B.extends(A)) {
             return { success: true };
         }
-        return failure(`some of ${b.toString()} are not assignable to ${a.toString()}`, ...(0, util_1.flatMap)(analyses, (x) => (x.success ? [] : x.reasons)));
-    }
-    // We have two named types, recursion might happen so protect against it.
-    try {
-        // For named types, we'll always do a nominal typing relationship.
-        // That is, if in the updated typesystem someone were to use the type name
-        // from the old assembly, do they have a typing relationship that's accepted
-        // by a nominal type system. (That check also rules out enums)
-        const nominalCheck = isNominalSuperType(a, b, updatedSystem);
-        if (nominalCheck.success === false) {
-            return nominalCheck;
-        }
-        // At this point, the only thing left to do is recurse into the structs.
-        // We used to do that here, but we don't anymore; structs check themselves
-        // for structural weakening/strengthening.
-        return { success: true };
-    }
-    catch (e) {
-        return failure(e.message);
-    }
-}
-/**
- * Find types A and B in the updated type system, and check whether they have a supertype relationship in the type system
- */
-function isNominalSuperType(a, b, updatedSystem) {
-    if (a.fqn === undefined) {
-        throw new Error(`I was expecting a named type, got '${a.toString()}'`);
-    }
-    // Named type vs a non-named type
-    if (b.fqn === undefined) {
-        return failure(`${b.toString()} is not assignable to ${a.toString()}`);
-    }
-    // Short-circuit of the types are the same name, saves us some lookup
-    if (a.fqn === b.fqn) {
-        return { success: true };
-    }
-    // We now need to do subtype analysis on the
-    // Find A in B's typesystem, and see if B is a subtype of A'
-    const B = updatedSystem.tryFindFqn(b.fqn);
-    const A = updatedSystem.tryFindFqn(a.fqn);
-    if (!B) {
-        return failure(`could not find type ${b.toString()}`);
-    }
-    if (!A) {
-        return failure(`could not find type ${a.toString()}`);
-    }
-    // If they're enums, they should have been exactly the same (tested above)
-    // enums are never subtypes of any other type.
-    if (A.isEnumType()) {
-        return failure(`${a.toString()} is an enum different from ${b.toString()}`);
-    }
-    if (B.isEnumType()) {
-        return failure(`${b.toString()} is an enum different from ${a.toString()}`);
-    }
-    if (B.extends(A)) {
-        return { success: true };
-    }
-    return failure(`${b.toString()} does not extend ${a.toString()}`);
-}
-/**
- * Is struct A a structural supertype of struct B?
- *
- * Trying to answer the question, is this assignment legal for all values
- * of `expr in B`.
- *
- * ```ts
- * const var: A = expr as B;
- * ```
- *
- * A is a structural supertype of B if all required members of A are also
- * required in B, and of a compatible type.
- *
- * Nullable members of A must either not exist in B, or be of a compatible
- * type.
- */
-function isStructuralSuperType(a, b, updatedSystem) {
-    // We know all members can only be properties, so that makes it easier.
-    const bProps = b.getProperties(true);
-    // Use timing words in error message to make it more understandable
-    const formerly = b.system === updatedSystem ? 'formerly' : 'newly';
-    const is = b.system === updatedSystem ? 'is' : 'used to be';
-    const removed = b.system === updatedSystem ? 'removed' : 'added';
-    for (const [name, aProp] of Object.entries(a.getProperties(true))) {
-        const bProp = bProps[name];
-        if (aProp.optional) {
-            // Optional field, only requirement is that IF it exists, the type must match.
-            if (!bProp) {
-                continue;
+        return failure(`${b.toString()} does not extend ${a.toString()}`);
+    }
+    /**
+     * Is struct A a structural supertype of struct B?
+     *
+     * Trying to answer the question, is this assignment legal for all values
+     * of `expr in B`.
+     *
+     * ```ts
+     * const var: A = expr as B;
+     * ```
+     *
+     * A is a structural supertype of B if all required members of A are also
+     * required in B, and of a compatible type.
+     *
+     * Nullable members of A must either not exist in B, or be of a compatible
+     * type.
+     */
+    isStructuralSuperType(a, b) {
+        // We know all members can only be properties, so that makes it easier.
+        const bProps = b.getProperties(true);
+        // Use timing words in error message to make it more understandable
+        const formerly = b.system === this.updatedSystem ? 'formerly' : 'newly';
+        const is = b.system === this.updatedSystem ? 'is' : 'used to be';
+        const removed = b.system === this.updatedSystem ? 'removed' : 'added';
+        for (const [name, aProp] of Object.entries(a.getProperties(true))) {
+            const bProp = bProps[name];
+            if (aProp.optional) {
+                // Optional field, only requirement is that IF it exists, the type must match.
+                if (!bProp) {
+                    continue;
+                }
             }
-        }
-        else {
-            if (!bProp) {
-                return failure(`${formerly} required property '${name}' ${removed}`);
+            else {
+                if (!bProp) {
+                    return failure(`${formerly} required property '${name}' ${removed}`);
+                }
+                if (bProp.optional) {
+                    return failure(`${formerly} required property '${name}' ${is} optional`);
+                }
             }
-            if (bProp.optional) {
-                return failure(`${formerly} required property '${name}' ${is} optional`);
+            const ana = this.isSuperType(aProp.type, bProp.type);
+            if (!ana.success) {
+                return failure(`property ${name}`, ...ana.reasons);
             }
         }
-        const ana = isSuperType(aProp.type, bProp.type, updatedSystem);
-        if (!ana.success) {
-            return failure(`property ${name}`, ...ana.reasons);
-        }
+        return { success: true };
     }
-    return { success: true };
 }
+exports.TypeAnalysis = TypeAnalysis;
 function failure(...reasons) {
     return { success: false, reasons };
 }

package/lib/type-comparison.d.ts

@@ -24,6 +24,10 @@ export declare class AssemblyComparison {
      * Based on a JSII TypeReference, return all reachable ComparableType<> objects.
      */
     typesIn(ref: reflect.TypeReference): Array<ComparableType<any>>;
+    /**
+     * Return the type's FQN, running it through the translation table if present.
+     */
+    private resolveFqn;
     /**
      * All ComparableType<>s
      */
@@ -44,10 +48,12 @@ export declare abstract class ComparableType<T> {
     protected readonly assemblyComparison: AssemblyComparison;
     protected readonly oldType: T;
     protected readonly newType: T;
+    protected readonly displayFqn: string;
     private static readonly recursionBreaker;
     private readonly _inputTypeReasons;
     private readonly _outputTypeReasons;
-    constructor(assemblyComparison: AssemblyComparison, oldType: T, newType: T);
+    constructor(assemblyComparison: AssemblyComparison, oldType: T, newType: T, displayFqn: string);
+    get fqnRemapping(): Record<string, string>;
     /**
      * Does this type occur in an input role?
      */

package/lib/type-comparison.js

@@ -33,7 +33,8 @@ class AssemblyComparison {
     load(original, updated) {
         /* eslint-disable prettier/prettier */
         for (const [origClass, updatedClass] of this.typePairs(original.allClasses, updated)) {
-            this.types.set(origClass.fqn, new ComparableClassType(this, origClass, updatedClass));
+            const { fqn, displayFqn } = this.resolveFqn(origClass);
+            this.types.set(fqn, new ComparableClassType(this, origClass, updatedClass, displayFqn));
         }
         for (const [origIface, updatedIface] of this.typePairs(original.allInterfaces, updated)) {
             if (origIface.datatype !== updatedIface.datatype) {
@@ -44,12 +45,14 @@ class AssemblyComparison {
                 });
                 continue;
             }
-            this.types.set(origIface.fqn, origIface.datatype
-                ? new ComparableStructType(this, origIface, updatedIface)
-                : new ComparableInterfaceType(this, origIface, updatedIface));
+            const { fqn, displayFqn } = this.resolveFqn(origIface);
+            this.types.set(fqn, origIface.datatype
+                ? new ComparableStructType(this, origIface, updatedIface, displayFqn)
+                : new ComparableInterfaceType(this, origIface, updatedIface, displayFqn));
         }
         for (const [origEnum, updatedEnum] of this.typePairs(original.allEnums, updated)) {
-            this.types.set(origEnum.fqn, new ComparableEnumType(this, origEnum, updatedEnum));
+            const { fqn, displayFqn } = this.resolveFqn(origEnum);
+            this.types.set(fqn, new ComparableEnumType(this, origEnum, updatedEnum, displayFqn));
         }
         /* eslint-enable prettier/prettier */
     }
@@ -67,13 +70,24 @@ class AssemblyComparison {
     typesIn(ref) {
         const ret = new Array();
         for (const fqn of fqnsFrom(ref)) {
-            const t = this.types.get(fqn);
+            const t = this.types.get(this.resolveFqn(fqn).fqn);
             if (t) {
                 ret.push(t);
             }
         }
         return ret;
     }
+    /**
+     * Return the type's FQN, running it through the translation table if present.
+     */
+    resolveFqn(x) {
+        const fqn = typeof x === 'string' ? x : x.fqn;
+        const finalFqn = this.options.fqnRemapping?.[fqn] ?? fqn;
+        if (fqn !== finalFqn) {
+            return { fqn: finalFqn, displayFqn: `${fqn} -> ${finalFqn}` };
+        }
+        return { fqn, displayFqn: fqn };
+    }
     /**
      * All ComparableType<>s
      */
@@ -85,8 +99,9 @@ class AssemblyComparison {
      */
     *typePairs(xs, updatedAssembly) {
         for (const origType of xs) {
-            LOG.trace(origType.fqn);
-            const updatedType = updatedAssembly.tryFindType(origType.fqn);
+            const { fqn, displayFqn } = this.resolveFqn(origType);
+            LOG.trace(displayFqn);
+            const updatedType = updatedAssembly.tryFindType(fqn);
             if (!updatedType) {
                 this.mismatches.report({
                     ruleKey: 'removed',
@@ -116,13 +131,17 @@ exports.AssemblyComparison = AssemblyComparison;
  * object.
  */
 class ComparableType {
-    constructor(assemblyComparison, oldType, newType) {
+    constructor(assemblyComparison, oldType, newType, displayFqn) {
         this.assemblyComparison = assemblyComparison;
         this.oldType = oldType;
         this.newType = newType;
+        this.displayFqn = displayFqn;
         this._inputTypeReasons = new Array();
         this._outputTypeReasons = new Array();
     }
+    get fqnRemapping() {
+        return this.assemblyComparison.options.fqnRemapping ?? {};
+    }
     /**
      * Does this type occur in an input role?
      */
@@ -208,9 +227,9 @@ class ComparableReferenceType extends ComparableType {
      * Compare members of the reference types
      */
     compare() {
-        LOG.debug(`Reference type ${this.oldType.fqn}`);
+        LOG.debug(`Reference type ${this.displayFqn}`);
         (0, stability_1.validateStabilities)(this.oldType, this.newType, this.mismatches);
-        (0, validations_1.validateBaseTypeAssignability)(this.oldType, this.newType, this.mismatches);
+        (0, validations_1.validateBaseTypeAssignability)(this.oldType, this.newType, this.fqnRemapping, this.mismatches);
         (0, validations_1.validateSubclassableNotRemoved)(this.oldType, this.newType, this.mismatches);
         if (this.subclassableType) {
             (0, validations_1.validateNoNewAbstractMembers)(this.oldType, this.newType, this.mismatches);
@@ -249,7 +268,7 @@ class ComparableReferenceType extends ComparableType {
             (0, validations_1.validateReturnTypeSame)(original, updated, this.mismatches.withMotivation('type is @subclassable'));
         }
         else {
-            (0, validations_1.validateReturnTypeNotWeakened)(original, updated, this.mismatches);
+            (0, validations_1.validateReturnTypeNotWeakened)(original, updated, this.fqnRemapping, this.mismatches);
         }
         this.validateCallable(original, updated);
     }
@@ -265,7 +284,7 @@ class ComparableReferenceType extends ComparableType {
                 (0, validations_1.validateParameterTypeSame)(original, oldParam, newParam, this.mismatches.withMotivation('type is @subclassable'));
             }
             else {
-                (0, validations_1.validateParameterTypeWeakened)(original, oldParam, newParam, this.mismatches);
+                (0, validations_1.validateParameterTypeWeakened)(original, oldParam, newParam, this.fqnRemapping, this.mismatches);
             }
         });
         (0, validations_1.validateNoNewRequiredParams)(original, updated, this.mismatches);
@@ -298,7 +317,7 @@ class ComparableReferenceType extends ComparableType {
             (0, validations_1.validatePropertyTypeSame)(original, updated, this.mismatches.withMotivation('mutable property cannot change type'));
         }
         else {
-            (0, validations_1.validatePropertyTypeNotWeakened)(original, updated, this.mismatches);
+            (0, validations_1.validatePropertyTypeNotWeakened)(original, updated, this.fqnRemapping, this.mismatches);
         }
     }
     /**
@@ -318,7 +337,7 @@ class ComparableClassType extends ComparableReferenceType {
         (0, validations_1.validateNotMadeAbstract)(this.oldType, this.newType, this.mismatches);
         // JSII assembler has already taken care of inheritance here
         if (this.oldType.initializer && this.newType.initializer) {
-            (0, validations_1.validateMethodCompatible)(this.oldType.initializer, this.newType.initializer, this.mismatches);
+            (0, validations_1.validateMethodCompatible)(this.oldType.initializer, this.newType.initializer, this.fqnRemapping, this.mismatches);
         }
     }
     /**
@@ -348,9 +367,9 @@ exports.ComparableInterfaceType = ComparableInterfaceType;
  */
 class ComparableStructType extends ComparableType {
     compare() {
-        LOG.debug(`Struct type ${this.oldType.fqn}`);
+        LOG.debug(`Struct type ${this.displayFqn}`);
         (0, stability_1.validateStabilities)(this.oldType, this.newType, this.mismatches);
-        (0, validations_1.validateBaseTypeAssignability)(this.oldType, this.newType, this.mismatches);
+        (0, validations_1.validateBaseTypeAssignability)(this.oldType, this.newType, this.fqnRemapping, this.mismatches);
         this.validateNoPropertiesRemoved();
         if (this.inputType) {
             // If the struct is written, it can't be strengthened (ex: can't change an optional property to required)
@@ -409,7 +428,7 @@ class ComparableStructType extends ComparableType {
     }
     isStructuralSuperType(a, b) {
         try {
-            return (0, type_analysis_1.isStructuralSuperType)(a, b, this.newType.system);
+            return new type_analysis_1.TypeAnalysis(this.newType.system, this.fqnRemapping).isStructuralSuperType(a, b);
         }
         catch (e) {
             // We might get an exception if the type is supposed to come from a different
@@ -427,7 +446,7 @@ class ComparableEnumType extends ComparableType {
      * Perform comparisons on enum members
      */
     compare() {
-        LOG.debug(`Enum type ${this.oldType.fqn}`);
+        LOG.debug(`Enum type ${this.displayFqn}`);
         (0, stability_1.validateStabilities)(this.oldType, this.newType, this.mismatches);
         (0, validations_1.validateExistingMembers)(this.oldType, this.newType, this.mismatches, (oldMember, newMember) => {
             (0, stability_1.validateStabilities)(oldMember, newMember, this.mismatches);

package/lib/types.d.ts

@@ -7,6 +7,10 @@ export interface ComparisonOptions {
      * @default Treat as stable
      */
     defaultExperimental?: boolean;
+    /**
+     * Mapping old FQNs to new ones
+     */
+    fqnRemapping?: Record<string, string>;
 }
 export interface ComparisonContext extends ComparisonOptions {
     /**

package/lib/validations.d.ts

@@ -11,7 +11,7 @@ import { IReport } from './types';
  *
  * Where CLASS ≤: BASE.
  */
-export declare function validateBaseTypeAssignability<T extends reflect.ReferenceType>(original: T, updated: T, mismatches: IReport): void;
+export declare function validateBaseTypeAssignability<T extends reflect.ReferenceType>(original: T, updated: T, fqnRemapping: Record<string, string>, mismatches: IReport): void;
 /**
  * The updated type has not been newly made abstract
  *
@@ -58,7 +58,7 @@ export declare function validateNoNewAbstractMembers<T extends reflect.Reference
  *
  * Where RETURN_TYPE(method) ≤: T.
  */
-export declare function validateReturnTypeNotWeakened(original: reflect.Method, updated: reflect.Method, mismatches: IReport): void;
+export declare function validateReturnTypeNotWeakened(original: reflect.Method, updated: reflect.Method, fqnRemapping: Record<string, string>, mismatches: IReport): void;
 /**
  * Validate that a method return type is the exact same
  *
@@ -76,7 +76,7 @@ export declare function validateReturnTypeSame(original: reflect.Method, updated
  *
  * Where RETURN_TYPE(prop) ≤: T.
  */
-export declare function validatePropertyTypeNotWeakened(original: reflect.Property, updated: reflect.Property, mismatches: IReport): void;
+export declare function validatePropertyTypeNotWeakened(original: reflect.Property, updated: reflect.Property, fqnRemapping: Record<string, string>, mismatches: IReport): void;
 /**
  * Validate that a property type is the exact same
  *
@@ -96,7 +96,7 @@ export declare function validatePropertyTypeSame(original: reflect.Property, upd
  *
  * Where T ≤: U.
  */
-export declare function validateParameterTypeWeakened(method: reflect.Method | reflect.Initializer, original: reflect.Parameter, updated: reflect.Parameter, mismatches: IReport): void;
+export declare function validateParameterTypeWeakened(method: reflect.Method | reflect.Initializer, original: reflect.Parameter, updated: reflect.Parameter, fqnRemapping: Record<string, string>, mismatches: IReport): void;
 /**
  * Validate that a method parameter type is the exact same
  *
@@ -127,7 +127,7 @@ export declare function validateExistingParams<T extends reflect.Initializer | r
  * (Not too few arguments)
  */
 export declare function validateNoNewRequiredParams<T extends reflect.Initializer | reflect.Method>(original: T, updated: T, mismatches: IReport): void;
-export declare function validateMethodCompatible<T extends reflect.Method | reflect.Initializer>(original: T, updated: T, mismatches: IReport): void;
+export declare function validateMethodCompatible<T extends reflect.Method | reflect.Initializer>(original: T, updated: T, fqnRemapping: Record<string, string>, mismatches: IReport): void;
 /**
  * Check if a class/interface has been marked as @subclassable
  */

package/lib/validations.js

@@ -36,8 +36,8 @@ const LOG = log4js.getLogger('jsii-diff');
  *
  * Where CLASS ≤: BASE.
  */
-function validateBaseTypeAssignability(original, updated, mismatches) {
-    const ana = assignableToAllBaseTypes(original, updated);
+function validateBaseTypeAssignability(original, updated, fqnRemapping, mismatches) {
+    const ana = assignableToAllBaseTypes(original, updated, fqnRemapping);
     if (!ana.success) {
         mismatches.report({
             ruleKey: 'base-types',
@@ -146,8 +146,8 @@ function validateNoNewAbstractMembers(original, updated, mismatches) {
  *
  * Where RETURN_TYPE(method) ≤: T.
  */
-function validateReturnTypeNotWeakened(original, updated, mismatches) {
-    const retAna = isCompatibleReturnType(original.returns, updated.returns);
+function validateReturnTypeNotWeakened(original, updated, fqnRemapping, mismatches) {
+    const retAna = isCompatibleReturnType(original.returns, updated.returns, fqnRemapping);
     if (!retAna.success) {
         mismatches.report({
             ruleKey: 'change-return-type',
@@ -183,8 +183,8 @@ function validateReturnTypeSame(original, updated, mismatches) {
  *
  * Where RETURN_TYPE(prop) ≤: T.
  */
-function validatePropertyTypeNotWeakened(original, updated, mismatches) {
-    const ana = isCompatibleReturnType(original, updated);
+function validatePropertyTypeNotWeakened(original, updated, fqnRemapping, mismatches) {
+    const ana = isCompatibleReturnType(original, updated, fqnRemapping);
     if (!ana.success) {
         mismatches.report({
             ruleKey: 'changed-type',
@@ -222,8 +222,8 @@ function validatePropertyTypeSame(original, updated, mismatches) {
  *
  * Where T ≤: U.
  */
-function validateParameterTypeWeakened(method, original, updated, mismatches) {
-    const argAna = isCompatibleArgumentType(original.type, updated.type);
+function validateParameterTypeWeakened(method, original, updated, fqnRemapping, mismatches) {
+    const argAna = isCompatibleArgumentType(original.type, updated.type, fqnRemapping);
     if (!argAna.success) {
         mismatches.report({
             ruleKey: 'incompatible-argument',
@@ -306,18 +306,18 @@ function validateNoNewRequiredParams(original, updated, mismatches) {
         }
     });
 }
-function validateMethodCompatible(original, updated, mismatches) {
+function validateMethodCompatible(original, updated, fqnRemapping, mismatches) {
     (0, stability_1.validateStabilities)(original, updated, mismatches);
     // Type guards on original are duplicated on updated to help tsc... They are required to be the same type by the declaration.
     if (reflect.isMethod(original) && reflect.isMethod(updated)) {
         validateStaticSame(original, updated, mismatches);
         validateAsyncSame(original, updated, mismatches);
-        validateReturnTypeNotWeakened(original, updated, mismatches);
+        validateReturnTypeNotWeakened(original, updated, fqnRemapping, mismatches);
     }
     validateNotMadeNonVariadic(original, updated, mismatches);
     // Check that every original parameter can still be mapped to a parameter in the updated method
     validateExistingParams(original, updated, mismatches, (oldParam, newParam) => {
-        validateParameterTypeWeakened(original, oldParam, newParam, mismatches);
+        validateParameterTypeWeakened(original, oldParam, newParam, fqnRemapping, mismatches);
     });
     validateNoNewRequiredParams(original, updated, mismatches);
 }
@@ -394,7 +394,7 @@ function* memberPairs(origClass, xs, updatedClass, mismatches) {
  *
  * Strengthening output values is allowed!
  */
-function isCompatibleReturnType(original, updated) {
+function isCompatibleReturnType(original, updated, fqnRemapping) {
     if (original.type.void) {
         return { success: true };
     } // If we didn't use to return anything, returning something now is fine
@@ -404,16 +404,16 @@ function isCompatibleReturnType(original, updated) {
     if (!original.optional && updated.optional) {
         return { success: false, reasons: ['output type is now optional'] };
     }
-    return (0, type_analysis_1.isSuperType)(original.type, updated.type, updated.system);
+    return new type_analysis_1.TypeAnalysis(updated.system, fqnRemapping).isSuperType(original.type, updated.type);
 }
 /**
  * Whether we are weakening the pre (input type of a method)
  *
  * Weakening preconditions is allowed!
  */
-function isCompatibleArgumentType(original, updated) {
+function isCompatibleArgumentType(original, updated, fqnRemapping) {
     // Input can never be void, so no need to check
-    return (0, type_analysis_1.isSuperType)(updated, original, updated.system);
+    return new type_analysis_1.TypeAnalysis(updated.system, fqnRemapping).isSuperType(updated, original);
 }
 /**
  * Verify assignability to supertypes
@@ -428,9 +428,9 @@ function isCompatibleArgumentType(original, updated) {
  * B an updated type B' needs to exist in the new assembly which is
  * still a supertype of T'.
  */
-function assignableToAllBaseTypes(original, updated) {
+function assignableToAllBaseTypes(original, updated, fqnRemapping) {
     for (const B of baseTypes(original)) {
-        const result = (0, type_analysis_1.isNominalSuperType)(B.reference, updated.reference, updated.system);
+        const result = new type_analysis_1.TypeAnalysis(updated.system, fqnRemapping).isNominalSuperType(B.reference, updated.reference);
         if (!result.success) {
             return result;
         }

package/lib/version.d.ts

@@ -1,3 +1,3 @@
 /** The qualified version number for this JSII compiler. */
-export declare const VERSION = "1.117.0 (build b8499c7)";
+export declare const VERSION = "1.119.0 (build 1634eac)";
 //# sourceMappingURL=version.d.ts.map

package/lib/version.js

@@ -1,7 +1,7 @@
 "use strict";
-// Generated at 2025-10-22T16:34:07Z by generate.sh
+// Generated at 2025-11-10T14:26:38Z by generate.sh
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
 /** The qualified version number for this JSII compiler. */
-exports.VERSION = '1.117.0 (build b8499c7)';
+exports.VERSION = '1.119.0 (build 1634eac)';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsii-diff",
-  "version": "1.117.0",
+  "version": "1.119.0",
   "description": "Assembly comparison for jsii",
   "license": "Apache-2.0",
   "author": {
@@ -33,10 +33,10 @@
     "package": "package-js"
   },
   "dependencies": {
-    "@jsii/check-node": "1.117.0",
-    "@jsii/spec": "1.117.0",
+    "@jsii/check-node": "1.119.0",
+    "@jsii/spec": "1.119.0",
     "fs-extra": "^10.1.0",
-    "jsii-reflect": "^1.117.0",
+    "jsii-reflect": "^1.119.0",
     "log4js": "^6.9.1",
     "yargs": "^17.7.2"
   },
@@ -46,6 +46,6 @@
     "@types/yargs": "^17.0.33",
     "jest-expect-message": "^1.1.3",
     "jsii": "^5.9.10",
-    "jsii-build-tools": "^1.117.0"
+    "jsii-build-tools": "^1.119.0"
   }
 }

package/test/classes.test.js

@@ -547,4 +547,14 @@ test('will find mismatches in submodules', () => (0, util_1.expectError)(/number
     'index.ts': 'export * as submodule from "./subdir"',
     'subdir/index.ts': 'export class Foo { public static readonly PROP = 42; }',
 }));
+// ----------------------------------------------------------------------
+test('allow remapping of FQNs', () => {
+    const original = `export class Foo1 { }`;
+    const updated = `export class Foo2 { }`;
+    // This should give no error because we remapped Foo1 to Foo2
+    const mms = (0, util_1.compare)(original, updated, {
+        fqnRemapping: { 'testpkg.Foo1': 'testpkg.Foo2' },
+    });
+    expect(Array.from(mms.messages())).toEqual([]);
+});
 //# sourceMappingURL=classes.test.js.map

package/test/util.d.ts

@@ -1,6 +1,6 @@
 import { MultipleSourceFiles } from 'jsii';
-import { Mismatches } from '../lib/types';
+import { ComparisonOptions, Mismatches } from '../lib/types';
 export declare function expectNoError(original: string | MultipleSourceFiles, updated: string | MultipleSourceFiles): void;
 export declare function expectError(error: RegExp | undefined, original: string | MultipleSourceFiles, updated: string | MultipleSourceFiles): void;
-export declare function compare(original: string | MultipleSourceFiles, updated: string | MultipleSourceFiles): Mismatches;
+export declare function compare(original: string | MultipleSourceFiles, updated: string | MultipleSourceFiles, options?: ComparisonOptions): Mismatches;
 //# sourceMappingURL=util.d.ts.map

package/test/util.js

@@ -25,13 +25,13 @@ function expectError(error, original, updated) {
         expect(msgs.join(',')).toMatch(error);
     }
 }
-function compare(original, updated) {
+function compare(original, updated, options = {}) {
     const ass1 = (0, jsii_1.sourceToAssemblyHelper)(original);
     const ts1 = new reflect.TypeSystem();
     const originalAssembly = ts1.addAssembly(new reflect.Assembly(ts1, ass1));
     const ass2 = (0, jsii_1.sourceToAssemblyHelper)(updated);
     const ts2 = new reflect.TypeSystem();
     const updatedAssembly = ts2.addAssembly(new reflect.Assembly(ts2, ass2));
-    return (0, lib_1.compareAssemblies)(originalAssembly, updatedAssembly);
+    return (0, lib_1.compareAssemblies)(originalAssembly, updatedAssembly, options);
 }
 //# sourceMappingURL=util.js.map