Compiler Architecture, AST & Custom Transformers

+---------------------------------------------------------------------------------------+
|                               The TypeScript Compiler Pipeline                        |
|                                                                                       |
|   1. SOURCE CODE (e.g., app.ts)                                                       |
|         |                                                                             |
|         v                                                                             |
|   2. SCANNER (scanner.ts)                                                             |
|         | Converts character stream into a flat sequence of lexical tokens.           |
|         | Tokens: [Keyword_const, Identifier_x, Colon, Keyword_number, Equals, ...]    |
|         v                                                                             |
|   3. PARSER (parser.ts)                                                               |
|         | Transforms token sequence into an Abstract Syntax Tree (SourceFile AST).    |
|         | Nodes: VariableStatement -> VariableDeclaration -> BinaryExpression         |
|         v                                                                             |
|   4. BINDER (binder.ts)                                                               |
|         | Scans AST to generate Symbols, Symbol Tables, and Lexical Scopes.           |
|         | Binds declarations to identifiers across modules and namespaces.            |
|         v                                                                             |
|   5. TYPE CHECKER (checker.ts)                                                        |
|         | The heart of tsc (~45,000 lines). Performs structural type checking,       |
|         | subtyping resolution, flow-sensitive CFA, and diagnostic error reporting.   |
|         v                                                                             |
|   6. EMITTER (emitter.ts) & TRANSFORMERS                                              |
|         | Runs custom AST transformers, strips type annotations, downlevels syntax,   |
|         | and emits .js, .js.map, and .d.ts files.                                    |
+---------------------------------------------------------------------------------------+

interface Node {
  kind: SyntaxKind;
  pos: number;          // Starting character offset in source text
  end: number;          // Ending character offset
  flags: NodeFlags;     // Bitwise flags (e.g., Let, Const, Yield, Await)
  parent?: Node;        // Pointer to enclosing parent node
}

+---------------------------------------------------------------------------------------+
|                               AST Node Hierarchy Decomposition                        |
|                                                                                       |
|   Statement:    const message: string = "Hello World";                                |
|                                                                                       |
|   AST Hierarchy:                                                                      |
|   ts.VariableStatement (kind: 240)                                                    |
|     +-- ts.VariableDeclarationList (kind: 258, flags: NodeFlags.Const)                |
|           +-- ts.VariableDeclaration (kind: 257)                                      |
|                 +-- ts.Identifier (kind: 79, text: "message")                         |
|                 +-- ts.TypeReferenceNode (kind: 180)                                  |
|                 |     +-- ts.Identifier (kind: 79, text: "string")                    |
|                 +-- ts.StringLiteral (kind: 10, text: "Hello World")                  |
+---------------------------------------------------------------------------------------+

import * as ts from "typescript";

function printNodeRecursive(node: ts.Node, depth: number = 0) {
  const indent = "  ".repeat(depth);
  const syntaxName = ts.SyntaxKind[node.kind];
  console.log(`{indent}{syntaxName} [{node.pos} - {node.end}]`);

  // Recursively visit all child nodes
  ts.forEachChild(node, (child) => printNodeRecursive(child, depth + 1));
}

+---------------------------------------------------------------------------------------+
|                             Custom AST Transformer Pipeline                           |
|                                                                                       |
|   [ Source AST ]                                                                      |
|         |                                                                             |
|         v                                                                             |
|   +-------------------------------------------------------------------------------+   |
|   | Custom Transformer Factory: (context) => (sourceFile) => transformedSource    |   |
|   |                                                                               |   |
|   |   Visitor Function: ts.visitEachChild(node, visitor, context)                 |   |
|   |   - Inspects node.kind (e.g., MethodDeclaration)                              |   |
|   |   - Modifies or wraps node using ts.factory API                               |   |
|   +-------------------------------------------------------------------------------+   |
|         |                                                                             |
|         v                                                                             |
|   [ Transformed AST ] ---> [ Emitter: Writes Instrumented JavaScript to Disk ]        |
+---------------------------------------------------------------------------------------+

import * as ts from "typescript";

export function createCustomTransformer(
  context: ts.TransformationContext
): ts.Transformer<ts.SourceFile> {
  const factory = context.factory;

  return (sourceFile: ts.SourceFile): ts.SourceFile => {
    function visitor(node: ts.Node): ts.Node {
      // 1. Inspect Node Kind
      if (ts.isCallExpression(node)) {
        // Intercept calls to logger.debug() and strip them in production builds
        if (isLoggerDebugCall(node)) {
          return factory.createVoidZero(); // Replace with 'void 0;'
        }
      }

      // 2. Recursively visit child nodes
      return ts.visitEachChild(node, visitor, context);
    }

    return ts.visitNode(sourceFile, visitor) as ts.SourceFile;
  };
}

function isLoggerDebugCall(node: ts.CallExpression): boolean {
  if (ts.isPropertyAccessExpression(node.expression)) {
    return (
      node.expression.name.text === "debug" &&
      ts.isIdentifier(node.expression.expression) &&
      node.expression.expression.text === "logger"
    );
  }
  return false;
}

// Synthesizing: console.log("Execution Time: ", elapsed);
const logStatement = context.factory.createExpressionStatement(
  context.factory.createCallExpression(
    context.factory.createPropertyAccessExpression(
      context.factory.createIdentifier("console"),
      context.factory.createIdentifier("log")
    ),
    /* typeArguments */ undefined,
    /* argumentsArray */ [
      context.factory.createStringLiteral("Execution Time: "),
      context.factory.createIdentifier("elapsed")
    ]
  )
);

// 1. Create a TypeScript Program
const program = ts.createProgram(["src/index.ts"], { target: ts.ScriptTarget.ES2022 });
const checker = program.getTypeChecker();
const sourceFile = program.getSourceFile("src/index.ts")!;

// 2. Query Type of an AST Node
function inspectIdentifierType(node: ts.Identifier) {
  // Retrieve Symbol
  const symbol = checker.getSymbolAtLocation(node);
  if (!symbol) return;

  // Retrieve Type
  const type = checker.getTypeOfSymbolAtLocation(symbol, node);
  const typeString = checker.typeToString(type);

  console.log(`Identifier '{node.text}' has static type: {typeString}`);
}

// Production Benchmark Instrumentation Transformer
import * as ts from "typescript";

export function benchmarkTransformer(
  context: ts.TransformationContext
): ts.Transformer<ts.SourceFile> {
  const { factory } = context;

  return (sourceFile: ts.SourceFile): ts.SourceFile => {
    function visitor(node: ts.Node): ts.Node {
      // Intercept Method Declarations with bodies
      if (ts.isMethodDeclaration(node) && node.body) {
        const methodName = node.name.getText(sourceFile);

        // Check if method is decorated or annotated with benchmark
        const hasBenchmarkComment = sourceFile.text
          .slice(node.pos, node.body.pos)
          .includes("@benchmark");

        if (hasBenchmarkComment) {
          const timerLabel = factory.createStringLiteral(`Benchmark: {methodName}`);

          // Synthesize: console.time("Benchmark: methodName");
          const startTime = factory.createExpressionStatement(
            factory.createCallExpression(
              factory.createPropertyAccessExpression(
                factory.createIdentifier("console"),
                factory.createIdentifier("time")
              ),
              undefined,
              [timerLabel]
            )
          );

          // Synthesize: console.timeEnd("Benchmark: methodName");
          const endTime = factory.createExpressionStatement(
            factory.createCallExpression(
              factory.createPropertyAccessExpression(
                factory.createIdentifier("console"),
                factory.createIdentifier("timeEnd")
              ),
              undefined,
              [timerLabel]
            )
          );

          // Wrap existing method statements inside try ... finally
          const tryFinallyBlock = factory.createTryStatement(
            node.body,
            /* catchClause */ undefined,
            factory.createBlock([endTime], true)
          );

          // Replace method body
          const instrumentedBody = factory.createBlock(
            [startTime, tryFinallyBlock],
            true
          );

          return factory.updateMethodDeclaration(
            node,
            node.modifiers,
            node.asteriskToken,
            node.name,
            node.questionToken,
            node.typeParameters,
            node.parameters,
            node.type,
            instrumentedBody
          );
        }
      }

      return ts.visitEachChild(node, visitor, context);
    }

    return ts.visitNode(sourceFile, visitor) as ts.SourceFile;
  };
}

const total: number = a + 10;

ts.SourceFile
  |
  +-- ts.VariableStatement (SyntaxKind.VariableStatement)
        |
        +-- ts.VariableDeclarationList (SyntaxKind.VariableDeclarationList)
              |  [flags: NodeFlags.Const]
              |
              +-- ts.VariableDeclaration (SyntaxKind.VariableDeclaration)
                    |
                    +-- name: ts.Identifier (SyntaxKind.Identifier) [text: "total"]
                    |
                    +-- type: ts.TypeReferenceNode / Keyword (SyntaxKind.NumberKeyword)
                    |
                    +-- initializer: ts.BinaryExpression (SyntaxKind.BinaryExpression)
                          |
                          +-- left: ts.Identifier (SyntaxKind.Identifier) [text: "a"]
                          |
                          +-- operatorToken: ts.Token (SyntaxKind.PlusToken)
                          |
                          +-- right: ts.NumericLiteral (SyntaxKind.NumericLiteral) [text: "10"]

function findNumericLiteral(node: ts.Node): ts.NumericLiteral | null {
  if (ts.isNumericLiteral(node) && node.text === "10") {
    return node;
  }
  return ts.forEachChild(node, findNumericLiteral) ?? null;
}

interface UserConfig {
  apiKey: string;
}

function UserConfig(key: string): UserConfig {
  return { apiKey: key };
}

namespace UserConfig {
  export const DEFAULT_TIMEOUT_MS = 5000;
}

class ProductResolver {
  // Target method to inspect
  public async getProductDetails(id: string): Promise<ProductRecord> {
    return fetchProduct(id);
  }
}

function isPromiseReturningMethod(node: ts.MethodDeclaration, checker: ts.TypeChecker): boolean {
  if (!node.type) return false;

  // Query Type from TypeChecker
  const returnType = checker.getTypeFromTypeNode(node.type);
  const symbol = returnType.getSymbol();

  return symbol?.name === "Promise";
}

function extractUnwrappedTypeName(node: ts.MethodDeclaration, checker: ts.TypeChecker): string | null {
  if (!ts.isTypeReferenceNode(node.type!)) return null;

  // Read first type argument: Promise<ProductRecord> -> ProductRecord
  const typeArgs = node.type.typeArguments;
  if (!typeArgs || typeArgs.length === 0) return null;

  const innerTypeNode = typeArgs[0];
  const innerType = checker.getTypeFromTypeNode(innerTypeNode);

  return checker.typeToString(innerType);
}

function createMetadataAssignment(
  factory: ts.NodeFactory,
  className: string,
  returnTypeName: string
): ts.ExpressionStatement {
  return factory.createExpressionStatement(
    factory.createBinaryExpression(
      factory.createPropertyAccessExpression(
        factory.createIdentifier(className),
        factory.createIdentifier("__graphQLMetadata")
      ),
      ts.SyntaxKind.EqualsToken,
      factory.createObjectLiteralExpression([
        factory.createPropertyAssignment(
          factory.createIdentifier("returnTypeName"),
          factory.createStringLiteral(returnTypeName)
        )
      ], true)
    )
  );
}