Fun facts

A small collection of trivia about the codebase. Nothing actionable — just things that surprised us while writing this wiki.

The longest source file is generated, and it's enormous

sdk/go/pulumi/types_builtins.go weighs in at roughly 480 KB (and types_builtins_test.go at ~435 KB). Both are generated by sdk/go/pulumi/generate/ and define Output types for every primitive shape (StringOutput, Int64MapOutput, ...). The repo's non-generated longest file is pkg/resource/deploy/step_generator.go at ~137 KB.

The PCL acronym is doing a lot of work

PCL stands for Pulumi Configuration Language. It is HCL-based (Terraform's syntax) but has its own type system, its own evaluator, and its own emitters for every supported language. It exists primarily as the intermediate representation for pulumi convert — it is not a user-facing language for writing infrastructure (despite being a "language"). It lives in two places: pkg/codegen/hcl2/ (the parser/checker) and sdk/pcl/ (the host, plus a small library).

"DIY" is a recent rename

The "do-it-yourself" backend was previously called filestate. The rename to diy happened in user-facing flags first, then in the package directory itself. There's still legacy terminology floating around — the helper for tagging stacks legacy-style is pkg/backend/diy/backend_legacy_test.go.

The biggest unique committers chart skews toward bots

If you git shortlog -sn the last 6 months, the top of the list looks ordinary, but pulumi-renovate[bot] (43 commits) and Pulumi Bot (30 commits) sit alongside human contributors. Most of these are dependency bumps and version freezes from the release pipeline.

The CLI knows how to generate its own spec

make generate-cli-spec runs the pulumi binary with a hidden subcommand to dump every command, flag, and argument into tools/automation/specification.json. The Automation API SDKs (Node, Python) use that spec as input to a code generator (sdk/{nodejs,python}/tools/automation/) so that the API surface always tracks the CLI.

Lifecycle tests run by fuzzing

pkg/engine/lifecycletest/ uses pgregory.net/rapid to generate random Pulumi programs and run them against a mock provider, checking that the engine never gets into an inconsistent state. The default is 10,000 random checks per invocation, configurable via the LIFECYCLE_TEST_FUZZ_CHECKS make variable.

The metaschema is also a JSON Schema

pkg/codegen/schema/pulumi.json is the schema for Pulumi schemas. It is itself a valid JSON Schema document. CI lints it with biome to keep it consistently formatted (make lint_pulumi_json).

You can talk to the engine without a CLI

pkg/cmd/pulumi/operations/ and the Automation API exist precisely so other tools can drive Pulumi without going through the user-visible CLI. Internally, the Automation API still spawns pulumi subprocesses — but the API surface looks like a library.

The proto package is named pulumirpc, not pulumi

option go_package = "github.com/pulumi/pulumi/sdk/v3/proto/go;pulumirpc" — this comes up when you grep for resource-monitor types in Go code; the package alias to look for is pulumirpc.

The image at the repo root is a YouTube preview

youtube_preview_image.png (75 KB) sits at the root because the README.md embeds it as a clickable thumbnail linking to a pulumi up demo on YouTube. Every time you cd into the repo, you have a tiny 75 KB billboard following you.