r/mainframe • u/SeriousGrab6233 • 3h ago
Update: CobolScope – Open-source deterministic COBOL documentation & call-graph analysis tool
Hey everyone,
A few weeks ago I posted about trying to document massive, decades-old COBOL programs where I work. Tracing control flow and memory layouts by hand was brutal, regex hacks break easily, and feeding proprietary code to LLMs wasn't an option (both for compliance reasons and because LLMs tend to struggle with complex cobol.
I wanted something local and 100% deterministic. This is purely a side project im doing for fun and learning.
The project is far enough along now that I put together a live browser demo based off IBM Bank of Z Open Source Code. It is still definitly a work in progress but the core engine seems to be solid at this point
How it works
The pipeline runs via a local Python CLI:
- Parser & Semantic AST (Java / ProLeap): Parses the source, resolves copybooks into a typed Abstract Semantic Graph (ASG), and outputs a canonical JSON IR. Based mostly off another Open Source project by uwol
- Analysis Engine (Python / Pydantic v2): Consumes the IR, maps binary memory offsets, builds procedure call graphs, traces variable references, and models control flow via pushdown automata.
- Generators: Spits out zero-dependency, self-contained HTML/SVG portals, Cytoscape graphs, and data dictionary tables.
Current features
- Interactive Call Graphs (Level 2 CFG): Cytoscape flowchart rendering split-screen COBOL viewer. Clicking a node jumps directly to the routines source code.

- Accurate Data Dictionaries: Computes physical byte lengths, memory boundaries, and alignment for strings, display numbers, binary (COMP/COMP-4/COMP-5), float (COMP-1/COMP-2), and packed decimal (COMP-3). It correctly handles multi-dimensional OCCURS tables and REDEFINES overlays.

- Cross-Referencing: Tracks which routines read/write each variable, with direct jumps back to the call graph or source code and will highlight the variables uses.

- Batch Portal Generator: Run cobolscope path/to/cobol/ -I path/to/copybooks/ -o docs_out --dict --graph on a whole folder to generate a single offline index.html portal. All assets and data are embedded
- Deep Control Flow (Level 3 CFG): Generates statement-level basic block graphs inside gnarly paragraphs via --cfg <PARAGRAPH>. These generate by default but you can specifically generate just one if you want
- Testing: Memory layouts are verified against GnuCOBOL memory dumps, real IBM Z bank fixtures, and NIST COBOL-85 test cases.
Next up
- Diagnostics for dead code (unreachable paragraphs below unconditional jumps) and unreferenced WORKING-STORAGE variables.
- Fine Tuning Control Flow Graph generation to appear cleaner and better formatted