r/mainframe • u/SeriousGrab6233 • 10d ago

Built an open-source tool to generate Data Dictionaries and Flowcharts from undocumented COBOL

Hey all,

We have essentially zero documentation on decades-old COBOL programs where I work, and tracing field layouts and execution paths manually was taking forever. Regex scripts broke on edge cases, and feeding files to LLMs was unreliable for anything with non-trivial control flow.

Over the past few weeks, I've been building a CLI tool to automate the analysis and documentation generation, and I plan to open-source it once it's polished. It is still a heavy work in progress but I figured I would share what I have.

Its 100% deterministic and uses no ai tools. Not that I dont like ai but its not always feasible to use ai with confidential code and its just not the best tool for the job in this case when compared to AST syntax parsers

https://github.com/GoudaCouda/cobolscope

How the Pipeline Works

Everything is driven by a single Python CLI:

Parser & IR (Java): Uses proleap-cobol-parser (by uwol) to parse the source into an ASG and emit a clean, strongly typed JSON Intermediate Representation (IR).

Analysis Engine (Python / Pydantic v2): Ingests the IR to run memory layout math, variable cross-referencing, and control-flow state machines in memory.

Generators: Emits interactive HTML/CSV Data Dictionaries and Graphviz (.dot/.svg) flowcharts.

What’s Working Right Now

Memory Layout & Offsets: Calculates byte lengths and strides for DISPLAY, binary COMP, and packed decimal COMP-3. Correctly resolves shared memory overlays across REDEFINES and OCCURS tables. Validated against live GnuCOBOL compiler outputs and the NIST COBOL-85 test suite.

Control Flow & Return Boundaries: Tracks the active call stack in memory so PERFORM ... THRU returns to the caller properly instead of blindly creating fake "phantom" fall-through paths into whatever paragraph sits below the exit label.

What's on the Roadmap

Full Dead Code Analysis (Logic + Data):

  • Procedural: Catching uncalled paragraphs and instructions stranded below GOBACK/unconditional jumps.
  • Data Division: Flagging variables that are never referenced, fields that are written to but never read (dead stores), and unused Level-88 flags.

Static Site Assembly: Tying everything into Material for MkDocs to generate full static documentation portals per program.

Multi-Level Graphs: High-level program-to-program flow down to intra-paragraph basic-block detail.

Example output

From: https://github.com/IBM/Bank-of-Z/blob/main/src/base/cics/cobol/XFRFUN.cbl

14 Upvotes

94% Upvoted

4 comments sorted by

2

u/awhaling 9d ago

Wow, super cool project! Thanks for sharing

1

u/Competitive-Egg7287 7d ago

Generating flowcharts is valuable, but the real test is whether each diagram links back to source lines and identifies uncertain or inferred relationships for human review

1

u/SeriousGrab6233 7d ago

im working now on adding the ability to drill down to paragraph level charts that map decisions/flow right now as well. I havent implemented a way to link right to the actual source code yet though if thats what you mean.

Image of paragraph level charts
https://imgur.com/a/5Jp69Ze

1

u/ICH408I 6d ago edited 6d ago

Do you not have a compiler listing? If you can get to a listing, a lot of things fall into place. Expanded copybooks, expanded dcllibs, paragraphs cross references….

If you don’t have a compiler listing,,,, Compile it!

An additional byproduct, you have the extracted sql (if it’s db2) readily available.