tree-sitter-cobol-enterprise

A Tree-sitter grammar for IBM Enterprise COBOL, the dialect used on z/OS mainframe systems, with first-class support for EXEC CICS and EXEC SQL embedded blocks.

If you have tried to parse real-world mainframe COBOL with an off-the-shelf tool, you have probably hit the same wall. Most COBOL parsers treat EXEC CICS and EXEC SQL blocks as opaque blobs of unstructured text. Any program that talks to a CICS transaction or a DB2 database — which is most of the interesting ones — produces parse errors or meaningless AST nodes.

This grammar fixes that. EXEC CICS and EXEC SQL blocks are parsed as typed AST nodes with named fields, so downstream tools can actually reason about what each transaction or query is doing. EXEC CICS READ is not a bag of words; it has a DATASET, an INTO, a RIDFLD, and an optional RESP. That distinction matters when you are trying to understand or migrate a program.

We built this as part of Spantree's AI-assisted mainframe modernization pipeline. We needed a parser that could handle the full IBM Enterprise COBOL dialect without choking on the parts that matter most for analysis.

Validated against the AWS CardDemo corpus: 65 of 66 files parse cleanly.

Mainframe systems running COBOL are the backbone of many large enterprises: banks, insurers, railroads, retailers. Migrating them is expensive and risky, partly because most tools cannot accurately read and understand the code.

This library is a building block for tools that can. It turns raw COBOL source files into structured data: a map of what each program does, what it calls, what database tables it reads and writes, and what transactions it handles. That structured representation is what makes automated analysis, documentation generation, and migration tooling possible.

Think of the difference between having a pile of documents in an unknown language versus having those documents accurately transcribed into something a computer can reason about. The transcription has to be right, and for IBM Enterprise COBOL, most open-source transcribers get it wrong on the parts that matter.

This is a Tree-sitter grammar, the same parsing framework used in Neovim, GitHub's code search, and dozens of other developer tools. Tree-sitter produces fast, incremental, error-tolerant concrete syntax trees from source code.

What is covered:

IBM Enterprise COBOL fixed-form source (columns 1 to 80). All four divisions: IDENTIFICATION, ENVIRONMENT, DATA, PROCEDURE. EXEC CICS commands as typed AST nodes with named fields (DATASET, INTO, FROM, RESP, and others). EXEC SQL statements as typed AST nodes. COPY/REPLACE directives, REDEFINES, level-number data definitions. PIC clause parsing including alphabetic, alphanumeric, numeric, COMP-3, and packed decimal. Nested programs and CALL statements.

Known gaps:

The NIST COBOL 85 test suite (6.3% clean) targets features rarely used in enterprise z/OS shops. WRITE AFTER ADVANCING has a GLR ambiguity in some edge cases. Intrinsic FUNCTION calls are partially supported. Free-form COBOL dialect is not supported.

Architecture:

grammar.js          Main grammar — all syntax rules
src/scanner.c       External scanner — column-position rules, comment lines, continuations
src/parser.c        AUTO-GENERATED by tree-sitter generate — do not edit
bindings/node/      Node.js native binding (nan-based, tree-sitter 0.20.x)
test/corpus/        Tree-sitter test cases (one .txt file per concern area)
scripts/validate.js Parses a corpus directory and reports ERROR node counts

Prerequisites: Node.js 18 or later, the tree-sitter CLI (npm install -g tree-sitter-cli), and node-gyp (npm install -g node-gyp).

git clone https://github.com/Spantree/tree-sitter-cobol-enterprise
cd tree-sitter-cobol-enterprise
npm install
npm run build

Run the test suite:

npm test

Parse a file:

npx tree-sitter parse path/to/program.cbl

Validate a corpus directory:

node scripts/validate.js /path/to/cobol/directory

Use in Node.js:

const Parser = require('tree-sitter');
const COBOL = require('./bindings/node');

const parser = new Parser();
parser.setLanguage(COBOL);

const tree = parser.parse(`
       IDENTIFICATION DIVISION.
       PROGRAM-ID. HELLO.
       PROCEDURE DIVISION.
           DISPLAY 'HELLO WORLD'.
           STOP RUN.
`);

console.log(tree.rootNode.toString());

CardDemo is the primary target corpus. NIST85 tests COBOL 85 features not commonly found in enterprise z/OS shops. The legacy and z Open Editor numbers reflect ongoing work.

tree-sitter-cobol by Yutaro Sakamoto is the most widely used open-source COBOL grammar for Tree-sitter, and this project derives from it. The upstream grammar does not handle EXEC CICS and EXEC SQL blocks as structured nodes; they fall through as ERROR sequences. This project addresses that gap specifically for the IBM Enterprise COBOL dialect. Per the terms of the upstream MIT license, attribution is preserved in LICENSE.

AWS Mainframe Modernization is AWS's managed migration service. Their transform pipeline generates Java but requires the proprietary BluAge runtime. This grammar is designed to feed open-source analysis tooling that produces portable output.

Issues and pull requests welcome. The highest-impact areas are expanding EXEC CICS command coverage (new commands follow the existing pattern in grammar.js), improving NIST85 compatibility for features that appear in real enterprise code, and adding test corpus files for edge cases you encounter in production programs.

MIT. See LICENSE.

This project is a derivative of tree-sitter-cobol by Yutaro Sakamoto, also MIT licensed. Original copyright and license text are preserved in LICENSE.

Built by Spantree Technology Group, a Trifork company.