chore(jsii): better errors around use of hidden types (#1861)

When a hidden (that is, `@internal` or not exported) type is used in a
visible (`public` or `protected` on an exported type) API, the error
produced would refer to the unusable type, but would not give any
indication of where it was being used from.

This makes several enhancements to this process:
- Qualify the kind of use for the type (return, parameter, ...)
- Attach the error to the resolving node (usage location)
- Provide a related message with the unusable type's declaration
- Specifically message around "this" (used or inferred as a return type)

This is going to particularly enhance the experience of folks extending
internal base types, where those internal base types declare members
that return hidden types (or "this").

Fixes #1860

packages/jsii/test/negatives.test.ts

@@ -6,6 +6,12 @@ import { ProjectInfo } from '../lib/project-info';
 
 const SOURCE_DIR = path.join(__dirname, 'negatives');
 
+const formatHost: ts.FormatDiagnosticsHost = {
+  getCanonicalFileName: ts.sys.realpath ?? ts.sys.resolvePath,
+  getCurrentDirectory: () => SOURCE_DIR,
+  getNewLine: () => '\n',
+};
+
 for (const source of fs.readdirSync(SOURCE_DIR)) {
   if (
     !source.startsWith('neg.') ||
@@ -18,30 +24,33 @@ for (const source of fs.readdirSync(SOURCE_DIR)) {
   test(
     source.replace(/neg\.(.+)\.ts/, '$1'),
     async () => {
-      const [expectations, strict] = await _getExpectedErrorMessage(filePath);
-      expect(
-        expectations.length,
-        `Expected error messages should be specified using ${MATCH_ERROR_MARKER}`,
-      ).toBeGreaterThan(0);
+      const { strict } = await _getPragmas(filePath);
       const compiler = new Compiler({
         projectInfo: _makeProjectInfo(source),
         failOnWarnings: strict,
       });
       const emitResult = await compiler.emit(path.join(SOURCE_DIR, source));
+
       expect(emitResult.emitSkipped).toBeTruthy();
-      const errors = emitResult.diagnostics.filter(
-        (diag) =>
-          diag.category === ts.DiagnosticCategory.Error ||
-          (strict && diag.category === ts.DiagnosticCategory.Warning),
-      );
-      for (const expectation of expectations) {
-        expect(
-          errors.find((e) => _messageText(e).includes(expectation)),
-          `No error contained: ${expectation}. Errors: \n${errors
-            .map((e, i) => `[${i}] ${e.messageText.toString()}`)
-            .join('\n')}`,
-        ).toBeDefined();
-      }
+
+      const diagnostics = emitResult.diagnostics
+        .filter(
+          // Remove suggestion diagnostics, we don't care much for those for now...
+          (diag) => diag.category !== ts.DiagnosticCategory.Suggestion,
+        )
+        .map((diag) =>
+          ts.formatDiagnosticsWithColorAndContext([diag], formatHost),
+        )
+        .sort();
+
+      expect(diagnostics.length).toBeGreaterThan(0);
+      expect(
+        diagnostics
+          // Remove ANSI color codes from the message so it's nicer in the snapshots file
+          // eslint-disable-next-line no-control-regex
+          .map((diag) => diag.replace(/\x1B\[[0-9;]*[a-z]/gi, ''))
+          .join(''),
+      ).toMatchSnapshot();
 
       // Cleaning up...
       return Promise.all(
@@ -65,32 +74,12 @@ for (const source of fs.readdirSync(SOURCE_DIR)) {
   );
 }
 
-const MATCH_ERROR_MARKER = '///!MATCH_ERROR:';
 const STRICT_MARKER = '///!STRICT!';
-async function _getExpectedErrorMessage(
-  file: string,
-): Promise<[string[], boolean]> {
+async function _getPragmas(file: string): Promise<{ strict: boolean }> {
   const data = await fs.readFile(file, { encoding: 'utf8' });
   const lines = data.split('\n');
-  const matches = lines
-    .filter((line) => line.startsWith(MATCH_ERROR_MARKER))
-    .map((line) => line.substr(MATCH_ERROR_MARKER.length).trim());
   const strict = lines.some((line) => line.startsWith(STRICT_MARKER));
-  return [matches, strict];
-}
-
-function _messageText(
-  diagnostic: ts.Diagnostic | ts.DiagnosticMessageChain,
-): string {
-  if (typeof diagnostic.messageText === 'string') {
-    return diagnostic.messageText;
-  }
-  if (diagnostic.messageText.next) {
-    return `${diagnostic.messageText.messageText}|${_messageText(
-      diagnostic.messageText.next[0],
-    )}`;
-  }
-  return diagnostic.messageText.messageText;
+  return { strict };
 }
 
 function _makeProjectInfo(types: string): ProjectInfo {

packages/jsii/test/negatives/neg.behavior-requires-iprefix.ts

@@ -1,5 +1,3 @@
-///!MATCH_ERROR: Interface contains behavior: name should be "ISomething"
-
 export interface Something {
   // The presence of this method requires an I prefix on the interface
   doSomething(): void;

packages/jsii/test/negatives/neg.class-name.1.ts

@@ -1,5 +1 @@
-///!MATCH_ERROR: Type names must use PascalCase: My_class
-
-export class My_class {
-
-}
+export class My_class {}

packages/jsii/test/negatives/neg.class-name.ts

@@ -1,5 +1 @@
-///!MATCH_ERROR: Type names must use PascalCase: myclass
-
-export class myclass {
-
-}
+export class myclass {}

packages/jsii/test/negatives/neg.compilation-error.ts

@@ -1,4 +1 @@
-///!MATCH_ERROR: Cannot find name 'boom'.
-///!MATCH_ERROR: Cannot find name 'CompilerErrorIsHere'.
-
-boom! >CompilerErrorIsHere
+boom! > CompilerErrorIsHere;

packages/jsii/test/negatives/neg.const-enum.ts

@@ -1,8 +1,6 @@
-///!MATCH_ERROR: Exported enum cannot be declared 'const'
-
 export const enum NotAllowed {
   ThisEnum,
   GetsInlined,
   AndSoItGetsLost,
-  ForJsii
-}
+  ForJsii,
+}

packages/jsii/test/negatives/neg.double-interface-members-deeper.ts

@@ -1,15 +1,11 @@
-///!MATCH_ERROR: Interface declares same member as inherited interface: foo
-
 export interface IA {
   foo(): void;
 }
 
 export interface IB extends IA {
-    bar(): void;
+  bar(): void;
 }
 
 export interface IC extends IB {
   foo(): void;
 }
-
-

packages/jsii/test/negatives/neg.double-interface-members-method.ts

@@ -1,9 +1,6 @@
-///!MATCH_ERROR: Interface declares same member as inherited interface: foo
-
 export interface IA {
   foo(): void;
 }
 export interface IB extends IA {
   foo(): void;
 }
-

packages/jsii/test/negatives/neg.double-interface-members.ts

@@ -1,5 +1,3 @@
-///!MATCH_ERROR: Interface declares same member as inherited interface: foo
-
 export interface A {
   foo: number;
 }

packages/jsii/test/negatives/neg.enum-members.1.ts

@@ -1,6 +1,4 @@
-///!MATCH_ERROR: Enum members must use ALL_CAPS: Goo
-
 export enum MyEnum {
-    FOO,
-    Goo
+  FOO,
+  Goo,
 }

packages/jsii/test/negatives/neg.enum-name.1.ts

@@ -1,6 +1,4 @@
-///!MATCH_ERROR: Type names must use PascalCase: myEnum
-
 export enum myEnum {
-    FOO,
-    GOO
+  FOO,
+  GOO,
 }

packages/jsii/test/negatives/neg.enum-name.2.ts

@@ -1,6 +1,4 @@
-///!MATCH_ERROR: Type names must use PascalCase: My_Enum
-
 export enum My_Enum {
-    FOO,
-    GOO
+  FOO,
+  GOO,
 }

packages/jsii/test/negatives/neg.expose-unexported-type-external.ts

@@ -1,10 +1,8 @@
-///!MATCH_ERROR: Exported APIs cannot use un-exported type jsii.UnexportedType
-
 // Attempt to expose an unexported type defined in another file should fial
 // because that type will not be available in the module spec.
 
 import { UnexportedType } from './mylib';
 
 export class ExportedType {
-    public p?: UnexportedType;
+  public p?: UnexportedType;
 }

packages/jsii/test/negatives/neg.expose-unexported-type-internal-in-namespace.ts

@@ -1,13 +1,10 @@
-///!MATCH_ERROR: Cannot use private type MyNamespace.UnexportedType in exported declarations
-
 // Attempt to expose an unexported type defined in this file should fail
 // because that type will not be available in the module spec.
 
 namespace MyNamespace {
-    export class UnexportedType {
-    }
+  export class UnexportedType {}
 }
 
 export class ExportedType {
-    public p?: MyNamespace.UnexportedType;
+  public p?: MyNamespace.UnexportedType;
 }

packages/jsii/test/negatives/neg.expose-unexported-type-internal.ts

@@ -1,12 +1,8 @@
-///!MATCH_ERROR: Cannot use private type UnexportedType in exported declarations
-
 // Attempt to expose an unexported type defined in this file should fail
 // because that type will not be available in the module spec.
 
-class UnexportedType {
-
-}
+class UnexportedType {}
 
 export class ExportedType {
-    public p?: UnexportedType;
+  public p?: UnexportedType;
 }

packages/jsii/test/negatives/neg.expose-unexported-type-this.ts

@@ -0,0 +1,13 @@
+// Attempt to return "this" from a hidden base class
+
+abstract class HiddenBaseClass {
+  public returnsThis() {
+    return this;
+  }
+}
+
+export class PublicClass extends HiddenBaseClass {
+  public constructor(public readonly boolean = true) {
+    super();
+  }
+}

packages/jsii/test/negatives/neg.extend-struct.ts

@@ -1,5 +1,3 @@
-///!MATCH_ERROR: Attempted to extend struct jsii.Struct from regular interface jsii.IIllegal
-
 // Attempt to extend a Struct (aka data type) from a regular interface will fail.
 export interface Struct {
   readonly field: string;

packages/jsii/test/negatives/neg.implement-struct.ts

@@ -1,5 +1,3 @@
-///!MATCH_ERROR: Attempted to implement struct jsii.Struct from class jsii.Illegal
-
 // Attempt to implement a Struct (aka data type) will fail.
 export interface Struct {
   readonly field: string;

packages/jsii/test/negatives/neg.implementation-changes-types.1.ts

@@ -1,14 +1,12 @@
-///!MATCH_ERROR: jsii.Something#returnSomething changes the return type when implementing jsii.ISomething (expected jsii.Superclass, found jsii.Subclass)
-
 export class Superclass {}
 export class Subclass extends Superclass {}
 
 export interface ISomething {
-    returnSomething(): Superclass;
+  returnSomething(): Superclass;
 }
 
 export class Something implements ISomething {
-    public returnSomething(): Subclass {
-        return 5;
-    }
+  public returnSomething(): Subclass {
+    return 5;
+  }
 }

packages/jsii/test/negatives/neg.implementation-changes-types.2.ts

@@ -1,14 +1,12 @@
-///!MATCH_ERROR: jsii.ISomethingElse#returnSomething changes the return type when implementing jsii.ISomething (expected jsii.Superclass, found jsii.Subclass)
-
 export class Superclass {}
 export class Subclass extends Superclass {}
 
 export interface ISomething {
-    returnSomething(): Superclass;
+  returnSomething(): Superclass;
 }
 
 export class ISomethingElse implements ISomething {
-    public returnSomething(): Subclass {
-        return new Subclass();
-    }
+  public returnSomething(): Subclass {
+    return new Subclass();
+  }
 }

packages/jsii/test/negatives/neg.implementation-changes-types.3.ts

@@ -1,14 +1,12 @@
-///!MATCH_ERROR: jsii.Something#takeSomething changes type of argument _argument when implementing jsii.ISomething (expected jsii.Superclass, found jsii.Subclass
-
 export class Superclass {}
 export class Subclass extends Superclass {}
 
 export interface ISomething {
-    takeSomething(argument: Superclass): void;
+  takeSomething(argument: Superclass): void;
 }
 
 export class Something implements ISomething {
-    public takeSomething(_argument: Subclass): void {
-        // Nothing
-    }
+  public takeSomething(_argument: Subclass): void {
+    // Nothing
+  }
 }

packages/jsii/test/negatives/neg.implementation-changes-types.4.ts

@@ -1,12 +1,10 @@
-///!MATCH_ERROR: jsii.Something#something changes the type of property when implementing jsii.ISomething (expected jsii.Superclass, found jsii.Subclass)
-
 export class Superclass {}
 export class Subclass extends Superclass {}
 
 export interface ISomething {
-    something: Superclass;
+  something: Superclass;
 }
 
 export class Something implements ISomething {
-    public something: Subclass = new Subclass();
+  public something: Subclass = new Subclass();
 }

packages/jsii/test/negatives/neg.implementation-changes-types.5.ts

@@ -1,18 +1,16 @@
-///!MATCH_ERROR: jsii.ISomethingElse#something changes the type of property when implementing jsii.ISomething (expected jsii.Superclass, found jsii.Subclass)
-
 export class Superclass {}
 export class Subclass extends Superclass {}
 
 export interface ISomething {
-    something: Superclass;
+  something: Superclass;
 }
 
 export interface ISomethingElse extends ISomething {
-    addUnrelatedMember: number;
+  addUnrelatedMember: number;
 }
 
 // Should still fail even though 2-level inheritance
 export class Something implements ISomethingElse {
-    public something: Subclass = new Subclass();
-    public addUnrelatedMember: number = 1;
+  public something: Subclass = new Subclass();
+  public addUnrelatedMember: number = 1;
 }

packages/jsii/test/negatives/neg.implementing-method-changes-optionality.1.ts

@@ -1,5 +1,3 @@
-///!MATCH_ERROR: jsii.Implementor#method changes the optionality of paramerter _optional when overriding jsii.AbstractClass (expected true, found false)
-
 // Attempt to change optionality of method parameter
 export abstract class AbstractClass {
   public abstract method(required: string, optional?: number): void;

packages/jsii/test/negatives/neg.implementing-method-changes-optionality.2.ts

@@ -1,5 +1,3 @@
-///!MATCH_ERROR: jsii.Implementor#method changes the optionality of paramerter _optional when overriding jsii.ParentClass (expected true, found false)
-
 // Attempt to change optionality of method parameter
 export class ParentClass {
   public method(_required: string, _optional?: number): void {

packages/jsii/test/negatives/neg.implementing-method-changes-optionality.ts

@@ -1,5 +1,3 @@
-///!MATCH_ERROR: jsii.Implementor#method changes the optionality of paramerter _optional when implementing jsii.IInterface (expected true, found false)
-
 // Attempt to change optionality of method parameter
 export interface IInterface {
   method(required: string, optional?: number): void;

packages/jsii/test/negatives/neg.implementing-property-changes-optionality.1.ts

@@ -1,5 +1,3 @@
-///!MATCH_ERROR: jsii.Implementor#property changes optionality of property when overriding jsii.AbstractClass
-
 // Attempt to change optionality of method parameter
 export abstract class AbstractClass {
   public abstract property?: string;

packages/jsii/test/negatives/neg.implementing-property-changes-optionality.2.ts

@@ -1,5 +1,3 @@
-///!MATCH_ERROR: jsii.Implementor#property changes optionality of property when overriding jsii.ParentClass
-
 // Attempt to change optionality of method parameter
 export class ParentClass {
   public property?: string = undefined;

packages/jsii/test/negatives/neg.implementing-property-changes-optionality.ts

@@ -1,5 +1,3 @@
-///!MATCH_ERROR: jsii.Implementor#property changes optionality of property when implementing jsii.IInterface
-
 // Attempt to change optionality of method parameter
 export interface IInterface {
   property?: string;