Mainframe Modernization Toolkit

Deterministic COBOL and JCL navigation, impact analysis, migration evidence, and code-generation tools for Python modernization projects.

The package includes:

• A Python CLI with 17 deterministic analysis and generation commands.
• A bundled VS Code extension and COBOL/JCL language server.
• GitHub Copilot Language Model Tools for dependency-aware agent workflows.
• A packaged migration skill and specialized VS Code agent.

The parsers and graph operations do not use an AI model. Given the same source and configuration, they produce the same result.

Quick start

1. Install the Python package

Python 3.10 or newer is required.

python -m pip install mainframe-modernization-toolkit
mainframe-toolkit --version

If the command is not on PATH, use:

python -m mainframe_modernization_toolkit --version

2. Export and install the VS Code extension

The wheel contains the matching VSIX. Installing the Python package does not modify VS Code automatically.

mainframe-toolkit vsix export --output mainframe-migration-toolkit.vsix
mainframe-toolkit vsix verify mainframe-migration-toolkit.vsix
code --install-extension mainframe-migration-toolkit.vsix

Reload VS Code after installation.

3. Initialize a mainframe workspace

Run this from the workspace containing COBOL, copybooks, and JCL:

mainframe-toolkit workspace init .

This adds, without overwriting existing files:

• mainframe-migration.json and its schema.
• The relational IR schema.
• .github/skills/mainframe-jcl-migration/.
• .github/agents/mainframe-jcl-migrator.agent.md.

Edit mainframe-migration.json so its source libraries, extensions, encoding, known external programs, and transport profiles match the workspace.

4. Verify the setup

mainframe-toolkit doctor --workspace .
mainframe-toolkit run migration_preflight -- . --jcl MYJOB --format text

Preflight exits 0 when generation is unblocked and 2 when required source or configuration is missing or ambiguous.

5. Use it in VS Code

The extension provides:

• F12 and hover for COBOL CALL, COPY, data items, and JCL EXEC PGM=.
• Context-aware copybook resolution.
• COBOL/JCL diagnostics, completion, and document symbols.
• Commands to reindex and inspect the dependency graph.
• Five deterministic Language Model Tools for Copilot agent mode.

Run Mainframe Migration: Reindex COBOL/JCL Workspace after changing source library configuration.

Invoke the packaged workflow with a workspace root and JCL boundary:

/mainframe-jcl-migration /path/to/workspace MYJOB migration/MYJOB

Alternatively, select the Mainframe JCL Migrator custom agent.

How it works

The toolkit separates deterministic evidence collection from AI reasoning:

1. The language server indexes COBOL programs, copybooks, JCL jobs, calls, includes, data declarations, and execution edges.
2. Language Model Tools expose those indexed facts to Copilot.
3. Python commands persist graphs, warnings, contracts, rules, SQL, readers, fixtures, scaffolds, and migration reports.
4. The agent reasons over tool output instead of reconstructing dependencies from model memory.

Unresolved or unsafe constructs are never silently guessed. Tools emit structured BLOCK, TODO, or informational findings for dynamic calls, missing copybooks, ambiguous libraries, edited PIC clauses, ODO, REDEFINES, transaction dialects, and unterminated SQL blocks.

Running packaged tools

Prefer the umbrella command:

mainframe-toolkit run dependency_graph -- . --format json
mainframe-toolkit run impact_analysis -- . --changed ACCTREC --format text
mainframe-toolkit run business_rule_extractor -- app/cbl/VALIDATE.cbl --format markdown
mainframe-toolkit run copybook_to_contract -- app/cpy/ACCTREC.cpy --config mainframe-migration.json --format json
mainframe-toolkit run generate_file_readers -- . --out-dir migration/data --format text

The separator -- ends arguments for mainframe-toolkit; everything after it is passed to the selected tool.

The module form works when the console entry point is not on PATH:

python -m mainframe_modernization_toolkit run dependency_graph -- . --format json

Consumer workspaces do not need a scripts/ directory. Do not locate or run Python files inside site-packages directly.

Tool catalog

Each tool is also installed as an individual console entry point, but the umbrella command is the stable form used by the VS Code extension and agent.

Language Model Tools

The VS Code extension registers:

• mainframe_getDependencyGraph
• mainframe_getCallers
• mainframe_resolveCopybook
• mainframe_impactAnalysis
• mainframe_runMigrationScript

mainframe_runMigrationScript invokes the pip-installed package. It does not expect repository scripts in the user's project.

Configuration

mainframe-migration.json controls:

• Ordered primary and fallback COBOL, copybook, and JCL libraries.
• Source extensions and encoding.
• Known external programs, utilities, and copybooks.
• Generated TODO syntax.
• Physical-to-transport record representations.

Configuration is authoritative. The tools do not widen searches to guessed directories when configured resolution fails.

The extension invokes mainframe-toolkit by default. If VS Code cannot find the entry point, set mainframeMigration.executablePath to its absolute path. Find it with the Python environment where the package was installed:

python -c "import shutil; print(shutil.which('mainframe-toolkit'))"

Safety boundaries

• Generated skeletons and capsules are evidence, not complete translations.
• Synthetic fixtures validate ingestion and field boundaries only. They are not authoritative expected program outputs.
• Semantic equivalence requires outputs captured from the mainframe or another verified implementation.
• Physical binary layouts and text transport layouts are separate contracts.
• PySpark generation requires reviewed, executable relational IR; the compiler does not invent business semantics.

Troubleshooting

mainframe-toolkit: command not found

Use:

python -m mainframe_modernization_toolkit doctor --workspace .

Then configure the extension with the absolute entry-point path if needed.

The agent tries to run scripts/<tool>.py

Upgrade the package, reinstall its bundled VSIX, and replace packaged workspace customizations only after reviewing local changes:

python -m pip install --upgrade mainframe-modernization-toolkit
mainframe-toolkit vsix export --output mainframe-migration-toolkit.vsix
code --install-extension mainframe-migration-toolkit.vsix --force
mainframe-toolkit workspace init . --force

The VSIX and Python package versions differ

mainframe-toolkit --version
mainframe-toolkit vsix verify

Export the VSIX from the same Python environment used by the extension tools.

License

Apache-2.0.