Ast

Right, so you want to build a code generator. Not just any code generator, but one that understands the structure of the code it’s manipulating. You’re not just concatenating strings like a barbarian; you’re a sculptor, and the TypeScript Compiler API is your chisel. It’s the difference between sending a mass email and writing a personal letter. The former might get the job done, but the latter is correct, robust, and doesn’t accidentally call the recipient by the wrong name.

Alright, let’s get our hands dirty. You’ve met the raw TypeScript Compiler API. It’s powerful, but let’s be honest, it feels like you’re trying to perform open-heart surgery with a rusty spoon while wearing oven mitts. The API is low-level, verbose, and requires you to constantly check the node.flags bitmask to figure out what you’re even looking at. It’s a masterpiece of engineering, but a nightmare of ergonomics. This is where ts-morph swoops in like a superhero in a nicely tailored suit. It’s a library that wraps the raw Compiler API, giving you all its power but with a sane, object-oriented, and downright pleasant interface. Instead of dealing with ts.SyntaxKind.SomeObscureEnum and ts.isCallExpression(node), you work with clear classes like CallExpression. It’s the difference between assembling a car from a pile of parts and simply turning the key.

Right, so you want to mess with the very fabric of your code as it’s being compiled. Not content with just writing TypeScript, you want to reach into the compiler’s guts and twist the knobs. I respect that. It’s how you build the next generation of linters, code formatters, and those fancy tools that feel like magic (until you have to debug them). We call this a “Custom Transformer,” and it’s your VIP pass to the Abstract Syntax Tree (AST) party. The AST is the compiler’s internal, object-oriented representation of your code. A transformer’s job is to walk through this tree, find the nodes it cares about, and then optionally replace, update, or delete them to produce a new, transformed tree. It’s like performing surgery on your code while it’s still just a thought in the compiler’s brain.

Alright, let’s get our hands dirty. You’ve got a ts.Program and its trusty sidekick, the Type Checker (ts.createTypeChecker()). This isn’t some glorified linter; this is the engine room of the entire language service. It’s the thing that actually knows what string is, why your generic is failing, and that the property you’re trying to access on that object definitely, probably, doesn’t exist. Its job is to take all those abstract syntax trees and turn them into a coherent web of types.

Alright, let’s get our hands dirty. You’ve got a TypeScript program in memory, parsed into an Abstract Syntax Tree (AST). It’s a beautiful, terrifying, and deeply nested structure of objects. Your job is to traverse it, find the bits you care about, and do something useful. This isn’t about reading the file as text; it’s about understanding its meaning programmatically. To do that, you need to know two things intimately: ts.Node and ts.SyntaxKind.

Right, let’s get our hands dirty. You’ve parsed a file, you’ve looked at its AST, and you feel like a wizard. But a single file is a lonely island. In the real world, TypeScript understands your code by seeing the whole archipelago—every file, every dependency, every declaration. That holistic view is encapsulated in a ts.Program. This isn’t just a fancy concept; it’s the beating heart of the compiler API. It’s the in-memory representation of your entire project, and without it, you’re just playing with syntax trees in a vacuum.

Look, you don’t reach for the TypeScript Compiler API because you had a nice, normal day and thought, “You know what sounds relaxing?” You reach for it when you have a problem that can’t be solved by just writing more TypeScript. It’s the power tool for when you need to not just use the language, but understand it, manipulate it, and generate it programmatically. Think of it as the difference between driving a car and being a mechanic with a full diagnostic computer. Most of us just need to drive. But when you need to tune the engine or, heaven forbid, build a new car from scratch, you need the mechanic’s tools.

Right, so you’ve learned the dark incantations: eval, exec, introspection. Powerful, but like giving a toddler a power tool. The real art isn’t in knowing how to summon these powers, but in knowing when and where to build the summoning circle. That’s what practical metaprogramming is about: building systems that are elegantly extensible or beautifully expressive without turning into a maintenance nightmare. Let’s talk about two places where this magic pays rent: plugin systems and Domain-Specific Languages (DSLs).

Right, so you’ve met exec and eval, the two party animals of dynamic execution. They’re flashy, they get all the attention, and they’re a bit messy. But behind them, there’s a quieter, more methodical function doing the real work: compile(). This is the function that takes your raw string of code and turns it into a proper, runnable code object. Think of it as the stage manager who sets everything up before the actors (exec/eval) even step on stage.

Right, so you’ve made it to the part where we stop just looking at the code and start rewriting it from the inside. This is where we graduate from clever tricks to something that feels a bit like wizardry—powerful, dangerous, and liable to blow your own foot off if you’re not careful. We’re going to talk about taking the Abstract Syntax Tree (AST) we just learned to introspect and using it to generate or transform code.

Now, let’s get our hands dirty with the ast module. If you’ve ever wondered how linters, auto-formatters, or sophisticated refactoring tools work their magic, this is the secret sauce. They don’t use regular expressions on source code—that way lies madness. Instead, they parse the code into an Abstract Syntax Tree (AST), a structured, tree-like representation of your program’s syntax. Think of it like this: your code is a string of words. The AST is the diagram that a linguist would draw to show the subject, verb, object, and all the clauses. The ast module is our linguist.

Right, let’s talk about exec() and eval(). These are the two functions that make Python programmers either feel like omnipotent wizards or get them instantly fired. They allow you to take a string of code and run it on the fly, dynamically. It’s the programming equivalent of handing a loaded script to your interpreter and saying, “Here, run this, I dare you.” The core difference between them is often muddled but is actually quite simple:

Right, so you want to build something dynamic. Maybe you’re crafting an API client that maps to a RESTful service, or building a data model that needs to reflect a database schema you won’t see until runtime. Hard-coding every attribute would be a tedious nightmare. This is where Python stops being a polite language and starts showing you its power tools: getattr(), setattr(), and the whole gang. We’re going to use them, not to write obfuscated code, but to write less code. More importantly, we’re going to use them correctly.

Right, let’s get our hands dirty. You’re about to learn how Python lets Python look at Python. It’s a bit meta, like a snake eating its own tail, but far more useful and less… messy. This isn’t just academic navel-gazing; introspection is how you write flexible, powerful code that can adapt to its environment, inspect libraries you didn’t write, and build frameworks that feel like magic. We’ll start with the blunt instruments and work our way up to the surgical tools.