Remove usages of GraphQL user.email field

Created by: dadlerj

Currently, there are two ways to access user emails through our GraphQL API:

export interface IUser {
    __typename: 'User'
    id: ID

    ...

    /**
     * @deprecated "use emails instead"
     */
    email: string
    emails: IUserEmail[]

    ...
}

In the process of removing usages of email for #490 , I discovered that it's impossible to determine a user's primary email address through the emails array, which is of type IUserEmail:

export interface IUserEmail {
    __typename: 'UserEmail'
    email: string
    verified: boolean
    verificationPending: boolean
    user: IUser
    viewerCanManuallyVerify: boolean
}

email, however, returns a user's primary email address, which is actually helpful/necessary in some situations (e.g. sending notification emails, password reset emails, etc.). email currently uses a strange definition of "primary" though, returning the (1) oldest email address that (2) has a verified_at field, whether the verification was successful or not: https://sourcegraph.sgdev.org/github.com/sourcegraph/enterprise/-/blob/cmd/frontend/db/user_emails.go#L60:26.

My proposal:

• Fully remove all usages of the email field

But to do this, we must...

• Add a primary: boolean field to the IUserEmail interface
• Update the definition of "primary" to mean: (1) the oldest successfully verified email, or, if no verified emails exist, (2) the oldest email.

cc @ijsnow