Ban inferred types in public interfaces

[mshustov]

There are several places in our code base when public interfaces aren't declared explicitly but inferred. That works just fine for the TS compiler, but it's not a human-friendly format.
When working in IDE, it doesn't unfold an inferred type to the final form

The generated documentation suffers from the problem:

Thus, a developer cannot use public API without digging into the platform (or a plugin) internals.

Ideally, we'd like to declare a linting rule enforcing explicit type declaration for the public types.
That's a recommenced approach used by the api-extractor team. They employ '@typescript-eslint/typedef' rule to enforce type declarations for all memberVariableDeclaration, function params, variable declarations & property declarations
https://github.com/microsoft/rushstack/blob/c4385524b073ca157d29b666e61504d10df80f86/stack/eslint-config/index.js#L483-L492
We could benefit from this approach but it adds a huge overhead for development - only the platform code has 4500+ places to fix when this rule is on! Also the rule explicitly says If you are using stricter TypeScript compiler options, particularly --noImplicitAny and/or --strictPropertyInitialization, you likely don't need this rule. (we do use strict: true). Probably it's not worth the effort since we care about public interfaces only. But there is no easy way to tell whether an interface is public or internal in the context of the linter, since those @public & @internal tags are parsed in the context of TSDoc only.
So we'd have to run a linter against the generated type declarations emitted in the target folder.

The further investigation required, but in the meantime, we could invert the approach for the public interface declaration: declare a public interface explicitly and use it to infer an internal type.

[elasticmachine]

Pinging @elastic/kibana-platform (Team:Platform)

[pgayvallet]

Moving core to packages did two things:

• It forced us to get rid of almost all the inferred types in our public types and signatures, so the issue is mostly resolved.

• It made us learn (the hard way) that getting rid of the remaining 1% wasn't realistically doable and that therefore a hard ban ES rule wasn't an option.

I'm going to close this.