[jsii] Confusing error message when using internal types in exported declarations

[RomainMuller]

🐛 Bug Report

Affected Languages

• TypeScript or Javascript
• Python
• Java
• .NET (C#, F#, ...)

General Information

• JSII Version: 1.9.0
• Platform: any

What is the problem?

It can be useful to have internal base types that are intentionally not exported out of the module. In many cases, developers want to organize their code in such a way that those types are internally exported within the module, but not from the module's entry point:

• Declaring these types in private files, unexpected from the index
• Declaring these types in public files, but only exporting specific symbols in the index (using export { ... } from "...";)

When such a type is extended/implemented, the jsii compiler does not automatically erase those (as it would for un-exported types, or those documented as @internal), and instead produces the following errors (see #1818 for more context of this particular one):

lib/shared/policy-statement/9-final.ts:6:1 - error TS9999: JSII: Unable to resolve referenced type 'iam-floyd.PolicyStatement'. Type may be @internal or unexported

  6 export class PolicyStatement extends PolicyStatementWithPrincipal {
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  7   protected cdkApplied = false; // internally used to check if resources, actions and conditions have already been applied to the policy
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
... 
 15   }
    ~~~
 16 }
    ~
lib/generated/awsdeeplens.ts:8:1 - error TS9999: JSII: Unable to resolve referenced type 'iam-floyd.PolicyStatement'. Type may be @internal or unexported

  8 export class Deeplens extends PolicyStatement {
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  9   public servicePrefix = 'deeplens';
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
... 
514   }
    ~~~
515 }
    ~

These are misleading:

• The declaration is not marked @internal, and it quite likely should have (the user expressly states this type is not part of the public API fo the module)
• The declaration is (locally) exported, however it is not exported from the module

This error needs to be enhanced in order to improve the actionability of it (clarify the problem and highlight possible solutions). Additionally, it would be useful if the locality of the error would be enhanced (so the specific usage site for the declaration is flagged, instead of the whole referenced or referencing type).

[github-actions]

This issue has not received any attention in 2 years. If you want to keep this issue open, please leave a comment below and auto-close will be canceled.