starting on the TypeScript compiler

Author: basarat

GLOSSARY.md

@@ -1,2 +1,5 @@
 # Duck Typing
-If it walks like a duck and quacks like a duck, its a duck. For TypeScript if it has all the members structurally then it okay for other things (irrespecitive of name) that accept that structure.
+If it walks like a duck and quacks like a duck, its a duck. For TypeScript if it has all the members structurally then it okay for other things (irrespecitive of name) that accept that structure.
+
+# OE
+Operating Environment. I'd like to use the term Operating System, but that is not necessarily what I mean here. Think Browser,Node.js,WScriptHost etc.

SUMMARY.md

@@ -16,7 +16,8 @@
   * [Async Await](docs/async-await.md)
   * [Generators](docs/generators.md)
 * [Project](docs/project/project.md)
-  * [tsconfig.json](docs/project/tsconfig.md)
+  * [Compilation Context](docs/project/compilation-context.md)
+    * [tsconfig.json](docs/project/tsconfig.md)
   * [Declaration Spaces](docs/project/declarationspaces.md)
   * [Modules](docs/project/modules.md)
     * [File Module Details](docs/project/external-modules.md)
@@ -29,3 +30,6 @@
   * [Type Assertion](docs/types/type-assertion.md)
   * [Type Compatability](docs/types/type-compatability.md)
 * [JSX](docs/jsx/tsx.md)
+* [TypeScript Compiler](docs/compiler/overview.md)
+  * [Program](docs/compiler/program.md)
+  * [AST](docs/compiler/ast.md)

docs/compiler/ast.md

@@ -0,0 +1,12 @@
+## Node
+The basic building block of the Abstract Syntax Tree (AST). In general node represent non-terminals in the language grammar; some terminals are kept in the tree such as identifiers and literals.
+
+## Note on AST description
+Two key things make up an AST node definition. Its `SyntaxKind` which identifies it within the AST and its `interface`, the API the node provides  when instantiated for the AST.
+
+## SourceFile
+
+* `SyntaxKind.SourceFile`
+* `interface SourceFile`.
+
+Each `SourceFile` is a top-level AST node that is contained in the `Program`.

docs/compiler/overview.md

@@ -0,0 +1,31 @@
+# Compiler
+The typescript compiler source is located under the [`src/compiler`] folder : https://github.com/Microsoft/TypeScript/tree/master/src/compiler
+
+It is split into the follow key parts:
+* Scanner (`scanner.ts`)
+* Parser (`parser.ts`)
+* Binder (`bindder.ts`)
+* Checker (`checker.ts`)
+* Emitter (`emitter.ts`)
+
+Each of these get their own unique files in the source. These parts will be explained later on in this chapter.
+
+There are a few additional files in the TypeScript compiler that provide utilities to many of these key portions:
+
+## File: Utilities
+core.ts : core utilities used by the TypeScript compiler
+
+## File: Key Data Structures
+`types.ts` contains key data structures and interfaces uses throughout the compiler. Here is a sampling of a few key ones:
+* `SyntaxKind`
+The AST node type is identified by the `SyntaxKind` enum.
+* `TypeChecker`
+This is the interface provided by the TypeChecker.
+* `CompilerHost`
+This is used by the `Program` to interact with the `System`
+
+## File: System
+All interaction of the TypeScript compiler with the operating system goes through a `System` interface. Both the interface and its implementations (`WScript` and `Node`) are defined in `system.ts`. You can think of it as the *Operating Environment* (OE).
+
+## File: Program
+The compilation context ([a concept we covered previously](docs/project/compilation-context.md)) is represented within the TypeScript compiler as a `Program`.

docs/compiler/program.md

@@ -0,0 +1,17 @@
+## Program
+
+### Usage of `CompilerHost`
+Its interaction mechanism with the OE:
+
+`Program` *-uses->* `CompilerHost` *-uses->* `System`
+
+The reason for having a `CompilerHost` as a point of indirection is that it allows it's interface to be more finely tuned for `Program` needs and not bother with OE needs (e.g. the `Program` doesn't care about `fileExists` a function provided by `System`).
+
+There are other users of `System` as well (e.g. tests).
+
+### SourceFile
+
+* `SyntaxKind.SourceFile`
+* `interface SourceFile`.
+
+The `program` consists of a bunch of source files. A `sourceFile` is actually a top-level AST node as well (`SyntaxKind.SourceFile`). Instances implement `interface SourceFile`.

docs/compiler/scanner.md

@@ -0,0 +1,2 @@
+## Compilation Context
+The compilation context is basically just a fancy term for grouping of the files that TypeScript will parse and analyze to determine what is valid and what isn't. Along with the information about which files, the compilation context contains information about *which compiler options*. A great way to define this logical grouping (we also like to use the term *project*) is using a `tsconfig.json` file.

docs/project/compilation-context.md

@@ -1,7 +1,3 @@
-## Compilation Context
-The compilation context is basically just a fancy term for grouping of the files that TypeScript will parse and analyze to determine what is valid and what isn't. A great way to define this logical grouping (we also like to use the term *project*) is using a `tsconfig.json` file.
-
-
 ### Basic
 It is extremely easy to get started with tsconfig.json as the basic file you need is:
 ```json
@@ -32,6 +28,4 @@ Good IDEs come with built in support for on the fly `ts` to `js` compilation. If
 * Just run `tsc` and it will look for `tsconfig.json` in the current as well as all parent folders till it finds it.
 * Run `tsc -p ./path-to-project-directory`. Of course the path can be a complete or relative to the current directory.
 
-You can even start the TypeScript compiler in *watch* mode using `tsc -w` and it will watch your TypeScript files for changes.
-
-{% include "footer.md" %}
+You can even start the TypeScript compiler in *watch* mode using `tsc -w` and it will watch your TypeScript project files for changes.