[engineering] Use type system to indicate when an index starts at one

[mjbvz]

Problem

The VS Code codebase has some indexes that start at one (IRange) and some that start at zero. I am very stupid and will not remember this

Proposal

Use types to annotate which types are one indexed:

export interface IRange {
	/**
	 * Line number on which the range starts (starts at 1).
	 */
	readonly startLineNumber: oneIndexedNumber;

      ...
}

Based on microsoft/TypeScript#364, the type could be something like:

declare const __oneIndexedMarker: unique symbol;
type oneIndexedNumber = number & { [__oneIndexedMarker]: '1' };

The benefit of this approach is that it introduces no runtime overhead. It is not perfect however, as it requires casts and can lose the type annotations:

const a = 1 as oneIndexedNumber;
const b = 1 as oneIndexedNumber;

const c = a + b; // type is number

@mhegazy @andy-ms Is a better way to do this with TS? It would be super useful for large codebases like ours