Partial type checking of a file (more granular opt-in)

[robatwilliams]

Proposal

Allow opting-in to type checking at a sub-file granularity, to enhance gradual-introduction ability.

Any function in an otherwise untyped file can be individually opted-in to type checking. Once the file opts in to this capability with // @flow partial, this is done by adding // @flow to individual functions.

Interactions between opted-in and non-opted-in code in the same file behave in the same way as those between opted-in and non-opted-in files.

1   // @flow partial
2
3   function a() {
4     // Not type checked
5   }
...

500 // @flow
501 function b() {
502   // Type checked
503 }

Use case

Gradually adding type safety to a codebase with long files.

We're doing that to a very large codebase in which many of the files are very long. That is due to existing usage of the re-ducks pattern of organising code into files.

This makes the smallest possible increment of adding type safety (opting-in one file with // @flow) a fairly large one. Many problems may arise, both in that file and in other already-typed files which use it.

Thus it doesn't encourage gradual and opportunistic opting-in as we would like to do by the boy-scout principle. Existing code is left untyped when modified, and new code is added without types.

Allowing more granular opting-in would enable that, and would further strengthen Flow's suitability for gradually introducing type safety to existing codebases.

[robatwilliams]

Same intent as #740