What the Hex is a Dex? Introducing Deterministic Transformation Artifacts

Large code refactors usually happen through fragile scripts, regex sorcery, and the occasional ritual chicken.

What if transformations themselves were portable, inspectable artifacts you could sign, verify, and undo?

Meet DEX — deterministic transformation artifacts, forged with a tool called Dennis.

The Problem: Code Transformations Are Usually Chaos

Software engineers constantly need to transform codebases.
Not just small edits. We're talking about massive structural changes:

• API migrations
• framework upgrades
• localization rewrites
• security patches across hundreds of repositories
• refactors touching thousands of files

Most of the time these transformations are done with a mix of:

• fragile scripts
• regex sorcery
• one-off codemods
• questionable search-and-replace rituals involving chickens

And once the script runs… Well.
Good luck.

You often get:

• no clear audit trail
• no reproducibility
• no safe rollback
• no way to inspect the transformation beforehand

In other words: You just ran a very large mutation across your codebase and now you're praying to the CI gods that the chicken satisfied their thirst for bugs.

But... What If Code Transformations Were Artifacts?
Imagine this: Instead of executing transformations blindly, what if we treated them like first-class artifacts? Something you could:

• inspect
• verify
• share
• sign
• reproduce
• and even undo (without needing any chickens)

This is the idea behind DEX.
DEX: Deterministic Transformation Artifacts

A DEX artifact is a portable package that describes a code transformation in a deterministic way.

Think of it as something like:

Git commit
+
migration script
+
cryptographic signature
+
replayable transformation plan

But instead of being tied to a specific repository state, a DEX artifact describes the transformation itself.

Inside a DEX artifact you typically find:

DEX
├── manifest.json
├── payload/
│ └── plan.json
└── signatures/

The important piece is the transformation plan. That plan describes:

• which files change
• which lines are modified
• what the original code was
• what the replacement becomes
• which helpers were injected
• the exact hash of the source file

Everything needed to reproduce the change deterministically.
Given the same inputs, the artifact will always produce the same transformation output. No hidden state, no runtime surprises.

The Dennis Forge

DEX artifacts are produced by a tool called Dennis.
Dennis is a deterministic codemod engine designed around a simple philosophy:

"Transformations should be planned, inspectable, and reversible."

The workflow looks like this:

Scan → Plan → Package → Sign → Verify → Apply

Instead of modifying your project directly, Dennis first generates a plan.
It is safe enough to try at home. No chickens required.

So... enough theory.
Let’s forge an artifact.
To begin with, clone the small example repository:

git clone https://github.com/crevilla2050/hello-dennis
cd hello-dennis

Inside you will find a minimal Python program:

!/usr/bin/env python3

def main():

print("Hello world.")
print("Thank you for using Dennis. Love, the Dennis Team.")

if name == "main":
main()

Nothing fancy.
Just two hardcoded strings — exactly the kind of thing that quietly spreads across a codebase until someone eventually says:

“We should probably internationalize this.”

Generating the Transformation Plan

To build a new artifact, once the repository is on your local machine, run the following inside the project folder:

dennis plan run . --dict messages_en.json --add-helper helper.py --target-file hello.py --line 12

This command analyzes the project and produces a deterministic transformation plan describing exactly what changes will occur.

However, nothing is modified yet.

Dennis always starts with a plan.

The plan is simply a JSON document describing the transformation.
You can open it and inspect it directly.

Packaging the Artifact

Once the plan exists, you can package it into a DEX artifact:

dennis pack plan.json hello-dennis.dex

At this point the transformation becomes a portable artifact. It can be shared, inspected, versioned, and stored like any other build artifact.

Signing the Artifact

DEX artifacts can also be cryptographically signed.
First generate a signing key:

dennis keygen

Then sign the artifact:

dennis dex sign hello-dennis.dex --key dennis.key

Now the artifact contains a verifiable signature proving its origin. If someone modifies the artifact payload and signs it again, older signatures remain inside the artifact as part of its historical record. This creates a chain of custody for transformations.

Inspecting the Artifact

Before executing anything, you can inspect the artifact:

dennis inspect hello-dennis.dex

Dennis will display:

• artifact metadata
• payload type
• payload hash
• signatures
• transformation information

This allows engineers to verify what the artifact contains before trusting it.

Applying the Transformation

To execute the transformation:

dennis rehydrate hello-dennis.dex
dennis apply rehydrated-plan.json

Your Python script will be transformed into a localization-ready structure. Instead of hardcoded strings, the program will now load messages from a dictionary.

Testing the Result

You can now try running the program with different language settings.
For example:

LANG=es python hello.py

or

LANG=de python hello.py

The program will automatically load the corresponding translation dictionary.
No chicken magic. Just deterministic, reversible transformations.

Undoing the Transformation

Dennis transformations are reversible by design. If something goes wrong, you can generate the inverse plan:

dennis invert rehydrated-plan.json
dennis apply rehydrated-plan.undo.json

Your project returns to its original state.

• No Git resets.
• No archaeology.
• Just a deterministic undo.

Encrypted Artifacts: XDEX

In some situations you may want to distribute a transformation artifact without exposing the internal transformation logic.

For that purpose Dennis supports XDEX artifacts.
An XDEX artifact is simply an encrypted version of a DEX file.

DEX → XDEX

The payload is encrypted while the outer metadata remains visible.

This allows organizations to distribute verifiable transformation artifacts while keeping the transformation plan confidential.

You can encrypt an artifact like this:

dennis encrypt hello-dennis.dex

Why This Matters?

Modern software pipelines treat many things as artifacts:

• container images
• compiled binaries
• dependency locks
• signed releases

But strangely, code transformations themselves are often invisible. DEX artifacts change that. They turn transformations into portable, inspectable, verifiable objects. Which means software evolution itself becomes something we can track, audit, and reproduce.

Final Thoughts

Software history is written through transformations.

• Refactors.
• Migrations.
• Patches.
• Upgrades.

Most of the time those transformations vanish after they run.

DEX artifacts make them visible.

And Dennis is the forge where they are made.

The forge lives under: https://github.com/crevilla2050/string-audit

Install with pip or pipx, and start DEX-ing your code.
DEX artifacts turn transformations into something you can pass around, inspect, and trust.

And may chickens live forever!

Comments

[crevilla2050]

if anyone tries the hello-dennis example repo, I’d love to hear how it works for you.
I’m especially curious what kinds of migrations people would package as DEX artifacts.