chore: add TypeScript definition file for most API

This is following advice found in this comment: microsoft/TypeScript#8305 (comment)

Author: eventualbuddha

lib/coffee-script/coffee-script.d.ts

@@ -0,0 +1,59 @@
+import SourceMap, { V3SourceMap } from './sourcemap';
+import { Token, LexerOptions } from './lexer';
+import { Block } from './nodes';
+
+export const VERSION: string;
+export const FILE_EXTENSIONS: Array<string>;
+
+interface CompileOptions {
+  header?: boolean;
+  shiftLine?: boolean;
+
+  // Source map options.
+  sourceMap?: boolean;
+  generatedFile?: string;
+  sourceRoot?: string;
+  sourceFiles?: Array<string>;
+  inline?: boolean;
+}
+
+type CompileResult = string | {
+  js: string,
+  sourceMap: SourceMap,
+  v3SourceMap: V3SourceMap,
+};
+
+interface RunOptions extends CompileOptions {
+  filename?: string;
+}
+
+/**
+ * Compile CoffeeScript code to JavaScript, using the Coffee/Jison compiler.
+ *
+ * If `options.sourceMap` is specified, then `options.filename` must also be specified.  All
+ * options that can be passed to `SourceMap#generate` may also be passed here.
+ *
+ * This returns a javascript string, unless `options.sourceMap` is passed,
+ * in which case this returns a `{js, v3SourceMap, sourceMap}`
+ * object, where sourceMap is a sourcemap.coffee#SourceMap object, handy for doing programatic
+ * lookups.
+ */
+export function compile(code: string, options?: CompileOptions): CompileResult;
+
+/**
+ * Tokenize a string of CoffeeScript code, and return the array of tokens.
+ */
+export function tokens(code: string, options?: LexerOptions): Array<Token>;
+
+/**
+ * Parse a string of CoffeeScript code or an array of lexed tokens, and
+ * return the AST. You can then compile it by calling `.compile()` on the root,
+ * or traverse it by using `.traverseChildren()` with a callback.
+ */
+export function nodes(source: string | Array<Token>, options?: LexerOptions): Block;
+
+/**
+ * Compile and execute a string of CoffeeScript (on the server), correctly
+ * setting `__filename`, `__dirname`, and relative `require()`.
+ */
+export function run(code: string, options?: RunOptions);

lib/coffee-script/lexer.d.ts

@@ -0,0 +1,83 @@
+import { LocationData } from './nodes';
+
+export type TokenType =
+  'BIN?' |
+  'BOOL' |
+  'CALL_END' |
+  'CALL_START' |
+  'COMPARE' |
+  'COMPOUND_ASSIGN' |
+  'COMPOUND_ASSIGN' |
+  'FOR' |
+  'FORINSTANCEOF' |
+  'FUNC_EXIST' |
+  'HERESTRING' |
+  'IDENTIFIER' |
+  'IF' |
+  'INDENT' |
+  'INDEX_END' |
+  'INDEX_SOAK' |
+  'INDEX_START' |
+  'INSTANCEOF' |
+  'LEADING_WHEN' |
+  'MATH' |
+  'NEOSTRING' |
+  'OUTDENT' |
+  'OUTDENT' |
+  'OWN' |
+  'PARAM_END' |
+  'PARAM_START' |
+  'REGEX' |
+  'REGEX_END' |
+  'REGEX_START' |
+  'RELATION' |
+  'SHIFT' |
+  'STATEMENT' |
+  'STRING' |
+  'STRING_END' |
+  'STRING_START' |
+  'TERMINATOR' |
+  'TOKENS' |
+  'UNARY' |
+  'UNARY_MATH' |
+  'UNLESS' |
+  'WHEN' |
+  'YIELD';
+
+export type Token = [
+  TokenType,
+  // code
+  string,
+  LocationData
+];
+
+export interface LexerOptions {
+  literate?: boolean;
+  line?: number;
+  column?: number;
+  untilBalanced?: boolean;
+  rewrite?: boolean;
+}
+
+export class Lexer {
+  /**
+   * **tokenize** is the Lexer's main method. Scan by attempting to match tokens
+   * one at a time, using a regular expression anchored at the start of the
+   * remaining code, or a custom recursive token-matching method
+   * (for interpolations). When the next token has been recorded, we move forward
+   * within the code past the token, and begin again.
+   *
+   * Each tokenizing method is responsible for returning the number of characters
+   * it has consumed.
+   *
+   * Before returning the token stream, run it through the [Rewriter](rewriter.html).
+   */
+  tokenize(code: string, opts?: LexerOptions): Array<Token>;
+
+  /**
+   * Preprocess the code to remove leading and trailing whitespace, carriage
+   * returns, etc. If we're lexing literate CoffeeScript, strip external Markdown
+   * by removing all lines that aren't indented by at least four spaces or a tab.
+   */
+  clean(code: string): string;
+}