Three Tools for COBOL Modernization, and Why They Are Separate

Most COBOL modernization proposals begin with a rewrite plan. That is the wrong end.

A mainframe estate that has been running since before the current staff arrived has one defining property: nobody can tell you with confidence what is in it. Not the vendors, not the team, often not the documentation. Programs call programs that were deleted. Copybooks are included from paths that no longer resolve. Business rules live in code nobody has read this decade.

Estimating a rewrite of a system in that condition is not estimating. It is guessing with a spreadsheet.

So we built three Apache-2.0 tools that form a method rather than a product, and the order matters more than any of them individually.

1. Analyze — cobol-migration-toolkit

Discovery first. The toolkit scans COBOL and copybook files and emits a first-pass inventory: a versioned inventory.json, a Markdown report, a self-contained HTML report, and Graphviz call and copybook graphs with the unresolved dependencies coloured red.

pip install -e .
cobol-migrate scan src --copybook-path copybooks --output build
dot -Tsvg build/dependencies.dot -o build/dependencies.svg

The red edges are the point. An unresolved dependency is either a program that no longer exists, a copybook path nobody preserved, or a call into something outside the scanned tree — and each of those is a real finding about the estate, discovered in minutes rather than in month four of a migration.

It is built to run in CI, because an estate that is being modernized is also still changing:

cobol-migrate scan src --strict                          # exit 1 on anything unresolved
cobol-migrate scan src --fail-on max_fan_in:20           # gate on any metric
cobol-migrate schema --output inventory.schema.json      # the downstream contract

The parser is deliberately conservative and regex-based, and we say so in the README. That is not an apology. A grammar-based parser is the right long-term answer and it is on the roadmap, but a conservative scanner that produces a trustworthy partial inventory today beats an ambitious parser that produces a confident wrong one. The tool's job at this stage is to be honest about what it could not resolve.

Two constraints shaped the whole thing. It runs entirely locally with no telemetry — your COBOL never leaves your network. And it is open-core: this repository is the free discovery core, while deep grammar-based parsing, embedded SQL and CICS handling, AI documentation, SARIF export, and the assessment dashboard belong to Cartograph, which deploys inside your environment rather than ingesting your source.

2. Transpile — cobol-to-rust

An experimental transpiler scaffold: COBOL source, to an intermediate representation, to a generated Cargo project.

It supports a deliberately small subset — PROGRAM-ID, working-storage with simple PIC clauses, MOVE, ADD, SUBTRACT, MULTIPLY, DISPLAY, STOP RUN — chosen so that every construct it generates is understandable and testable by a human reading the output.

cobol2rust examples/hello.cbl --output build/hello-rust
cd build/hello-rust && cargo run

The verification approach matters more than the coverage. Generated code is checked by differential testing: run the original and the translation against the same inputs and compare the outputs. For a translated business rule, "it compiles" and "a human reviewed it" are both much weaker guarantees than "it produces identical results on the cases we ran."

This is beta, it is a scaffold rather than a full converter, and the README says that in the first paragraph. A transpiler that overstates its subset is worse than useless on a mainframe estate — it produces plausible code containing errors in exactly the places nobody is checking.

3. Integrate — cobol-rest-bridge

The tool that exists because most modernization does not finish, and the ones that succeed usually did not need to.

The bridge exposes compiled COBOL business logic through a FastAPI service:

HTTP client -> FastAPI -> subprocess -> compiled COBOL program -> JSON

docker compose up --build
curl -X POST http://localhost:8000/calculate-interest \
  -H 'Content-Type: application/json' \
  -d '{"principal":10000,"annual_rate_percent":5.25,"days":30}'

The process boundary is deliberate. It is easy to understand, easy to test, easy to containerize, and straightforward to replace later with a shared library, a message queue, or a proper mainframe connector when the volume justifies it.

The strategic point is bigger than the implementation. Business logic that has been correct for thirty years is an asset, not debt. Wrapping it in an interface the rest of your architecture can use buys you working software this quarter and removes the all-or-nothing framing that kills these projects. Rewrite the parts that genuinely need rewriting; keep the parts that are simply old and correct.

Why they are three repositories

Because they are three decisions, and a single tool would quietly make all three for you.

Analysis is valuable on its own — plenty of estates should be analysed and then left alone, and that is a legitimate outcome. Translation is valuable only where a component genuinely needs to become something else. Integration is valuable when the right answer is to keep the logic and change how it is reached.

A monolithic "modernization platform" has a commercial incentive for the answer always to be migrate. Three separate tools let the evidence decide, and let you stop after step one without having bought anything.

What we would tell you before you start

Assume the documentation is wrong. Not maliciously — just older than the code.

Unresolved dependencies are the schedule. They are where the surprises live, and counting them early is the closest thing to an honest estimate you will get.

"Nobody knows what this does" is a finding, not a blocker. Write it down, put a number next to it, and make it visible to whoever is deciding the budget.

Do not rewrite what you have not read. The most expensive mainframe projects we have seen began with a confident timeline and no inventory.

The toolchain is public: cobol-migration-toolkit, cobol-to-rust, and cobol-rest-bridge. All Apache-2.0, all beta, all actively looking for feedback from people with real estates.

If you have an inherited system — mainframe or otherwise — that nobody can safely change, an assessment is the version of this where we do the reading for you and tell you plainly what is at risk.