Add rule to detect redundant // @internal comments

[ajafff]

// @internal
namespace foo {
  export var v: any;
  // v-- this one is redundant because a parent is already marked as internal
  // @internal
  export var v2: any;
  // v-- this one is redundant as well, just other comment kind
  /* @internal */ export var v3: any;
}

This should probably not be enabled in a preset.

TBD: how should this work if --stripInternal is not enabled?

[ajafff]

For posterity: TypeScript simply omits any Node that has the substring @internal somewhere in its leasing comments.

I'll do some further investigation to see if there is the need for a rule to disallow @internal comments at invalid/dangerous positions.

[ajafff]

It should also be an error to have @internal comment in trailing comments

[ajafff]

Also explore adding errors for internal declarations that are used by other non-internal declarations.

[ajafff]

The complexity of this topic actually warrants more than one rule: #345 and #346

Regarding // @internal at "dangerous" positions: It turns out you can omit certain certain declarations, but there will be no syntax error:

// emits nothing
export var
  // @internal
  a: any;

// emits 'var b: any'
export var
  b: any,
  // @internal
  c: any;

// doesn't emit the heritage clause, also works for 'implements'
export class Foo
  extends
  // @internal
  Object {}

[ajafff]

This rule should also detect // @internal comments on local declarations:

// @internal
const foo = 1;

// @internal
export const bar = 1;

expected: error on foo as it's not exported

[ajafff]

That last thing is actually quite hard to achieve now that declarations are implicitly added to the declaration file. So this needs the same logic as #346