[compiler]internal symbols

[witemple-msft]

This PR enables libraries to define internal symbols that cannot be referenced from outside the same project scope.

internal can apply to any declaration except namespace. Internality is a property of symbols, not of types. A Type that is declared internal can be used from a different package, but can't be referred to by name. This allows you to use an alias to publicly expose an internal declaration:

internal model X {}

// Totally fine -- the model itself isn't internal, only the _symbol_ `X` is.
alias Public = X;

Resolution logic for symbols declared with internal is:

• Resolution is allowed if the source location is in the compiler stdlib or is synthetic (programmatic through checker.resolveTypeReference or otherwise synthetic).
• Resolution is allowed if the source location is a library, and the target symbol was declared within that same library.
• Resolution is allowed if the source location is the user project, and the target symbol was declared within the user project.
• Resolution is otherwise disallowed.

Notes:

• To preserve backwards compatibility, internal is allowed as the name of a model property, since it is allowed as one now. The logic for this also allows extern to be a model property name, which isn't currently allowed.

Implementation:

• Refactors parser a bit to handle modifiers on all declarations.
• Adds SymbolFlags.Internal, which binds to a symbol if the corresponding declaration has ModifierFlags.Internal.
• Access control is enforced in resolveTypeReferenceSymInternal when resolving a type reference. Access control must pass for any referenced symbol.

[github-actions]

All changed packages have been documented.

• ✅ @typespec/compiler
• ✅ @typespec/tspd

Show changes

@typespec/compiler - feature ✏️

Added experimental support for internal modifiers on type declarations. Any type except namespace can be declared internal. An internal symbol can only be accessed from within the same package where it was declared.

@typespec/tspd - internal ✏️

Updated documentation generation to ignore items tagged internal.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@typespec/compiler@9762

npm i https://pkg.pr.new/@typespec/tspd@9762

commit: df16015

[azure-sdk]

You can try these changes here

🛝 Playground	🌐 Website	🛝 VSCode Extension

[timotheeguerin]

Looks good, just if we can easily also mark compiler internal decorators internal via the checker it would be good