CobolBreaker: Legacy Modernization Engine

"Deterministic Parsing, Probabilistic Explanation"

CobolBreaker is an open-source ETL pipeline designed to ingest legacy COBOL source code, analyze its structure, enrich it with semantic understanding via LLMs, and output modern documentation and migration scaffolding for Java/Python projects.

Mission

Modernize the world's critical business systems by making COBOL codebases understandable, maintainable, and migratable. We bridge the gap between decades-old enterprise systems and modern development practices through automated analysis and intelligent documentation generation.

What It Does

CobolBreaker transforms legacy COBOL into two distinct artifacts:

Modern Documentation

• Static HTML Site: Generated via MkDocs with Material theme
• Business Logic Explanations: Plain English summaries of complex procedures
• Interactive Flow Diagrams: MermaidJS visualizations of control flow
• Data Dictionary: Variable mappings and usage patterns

Migration Scaffolding

• Compilation-Ready Code: Java or Python project structures
• Class Definitions: Mapped from COBOL PROGRAM-ID and DATA DIVISION
• Method Stubs: Generated from PARAGRAPHS with LLM-generated documentation
• Type Mapping: Automatic conversion from COBOL PIC clauses to modern types

Architecture

Ingest → Parse → Graph → Enrich → Generate

Core Components

• Preprocessor: Copybook resolution, column scrubbing, file normalization
• Parser: ANTLR4-based COBOL85 parsing with AST generation
• Graph Engine: NetworkX Control Flow Graph (CFG) construction
• LLM Integration: OpenAI/Azure API with intelligent caching
• Generators: Documentation (MkDocs) + Scaffolding (Java/Python)

Tech Stack

• Language: Python 3.10+
• Parsing: ANTLR4 (antlr4-python3-runtime)
• Graphing: NetworkX
• Database: SQLite (caching, incremental builds)
• LLM: OpenAI API (configurable for Azure OpenAI)
• Templating: Jinja2
• Documentation: MkDocs (Material Theme)

Project Status

Current Phase: Foundation Setup

• Project specification and architecture design
• Implementation roadmap and success criteria
• Core project structure and dependencies
• ANTLR4 grammar integration
• Preprocessor and parser modules
• Graph engine and analysis tools
• LLM integration and caching
• Documentation and scaffolding generators
• CLI interface and configuration
• Test suite and sample COBOL codebase

How to Participate

We welcome contributions from developers, COBOL experts, and organizations dealing with legacy systems.

For Developers

Getting Started:

1. Fork the repository
2. Set up Python 3.10+ environment
3. Install dependencies: pip install -r requirements.txt
4. Run tests: python -m pytest
5. Check issues labeled good first issue

Areas Needing Help:

• Core parsing engine development
• LLM prompt engineering and optimization
• Graph algorithm implementation
• Template design for code generation
• Test case development with real COBOL samples

For COBOL Experts

Your Expertise Matters:

• Validate parsing accuracy across different COBOL dialects
• Provide real-world COBOL samples for testing
• Help with business logic interpretation
• Contribute dialect-specific grammar rules
• Review generated documentation for accuracy

For Organizations

Partner With Us:

• Provide anonymized COBOL codebases for testing
• Sponsor development of specific features
• Share migration success stories and use cases
• Contribute enterprise requirements and feedback
• Help define industry standards for COBOL modernization

Development Workflow

Branch Strategy

• main: Stable releases
• develop: Integration branch
• feature/*: New features
• hotfix/*: Critical fixes

Contribution Guidelines

1. Code Style: Follow PEP 8, use black for formatting
2. Testing: All PRs must include tests
3. Documentation: Update docs for new features
4. Commits: Use conventional commit messages
5. PRs: Provide clear descriptions and testing instructions

Issue Labels

• bug: Errors and unexpected behavior
• enhancement: New feature requests
• good first issue: Beginner-friendly contributions
• help wanted: Community collaboration needed
• documentation: Docs and README improvements

Long-Term Goals

Phase 1: Foundation (Current)

• Complete core pipeline implementation
• Support for IBM COBOL dialect
• Basic Java and Python scaffolding
• Community-driven testing and validation

Phase 2: Expansion

• Multi-Dialect Support: MicroFocus, GnuCOBOL, ACUCOBOL
• Advanced Analysis: Data flow analysis, dead code detection
• Enhanced Scaffolding: Spring Boot, Django, FastAPI templates
• Performance: Parallel processing, incremental analysis
• IDE Integration: VS Code extension, IntelliJ plugin

Phase 3: Intelligence

• ML Models: Train specialized models for COBOL understanding
• Automated Refactoring: Suggest code improvements and modernizations
• Testing Generation: Automated unit test creation
• Migration Planning: Risk assessment and migration roadmaps
• Cloud Integration: AWS, Azure, GCP deployment targets

Phase 4: Ecosystem

• Plugin Architecture: Extensible generator system
• Marketplace: Community-contributed templates and extensions
• Enterprise Features: Role-based access, audit trails, compliance
• Integration Platform: Connect with modern DevOps tools
• Knowledge Base: Community wiki with best practices

Success Metrics

Technical Metrics

• Parsing Accuracy: >95% successful parsing across test corpus
• Performance: Process 10K LOC within 30 seconds
• Cache Hit Rate: >80% for incremental builds
• Generated Code Quality: 100% compilation success rate

Community Metrics

• Contributors: 50+ active community contributors
• Adoption: 100+ organizations using in production
• Code Coverage: >90% test coverage
• Documentation: Complete API docs and tutorials

Impact Metrics

• COBOL Lines Analyzed: 1M+ lines of legacy code processed
• Migration Projects: 100+ successful modernization projects
• Cost Savings: $10M+ estimated migration cost reduction
• Developer Productivity: 10x faster understanding of legacy code

Community

Communication Channels

• GitHub Discussions: General questions and ideas
• Discord Server: Real-time chat and collaboration
• Monthly Community Calls: Roadmap updates and demos
• Newsletter: Project updates and COBOL modernization trends

Events

• Hackathons: Quarterly COBOL modernization challenges
• Workshops: Educational sessions on legacy system modernization
• Conferences: Presentations at enterprise architecture events
• Office Hours: Open sessions with core maintainers

License

This project is licensed under the MIT License - see the LICENSE file for details. We believe in open collaboration and making modernization tools accessible to all organizations.

Acknowledgments

• ANTLR Project: For the powerful parsing framework
• OpenAI: For LLM capabilities enabling semantic understanding
• COBOL Community: For decades of enterprise computing innovation
• Legacy System Maintainers: The unsung heroes keeping critical systems running

Vision

We envision a world where legacy COBOL systems are no longer barriers to innovation, but foundations for modern digital transformation. By automating the understanding and modernization process, we enable organizations to:

• Preserve Business Logic: Decades of refined business rules
• Reduce Technical Debt: Modern architectures with proven logic
• Accelerate Innovation: Faster development cycles on stable foundations
• Bridge Generations: Connect experienced mainframe developers with modern cloud engineers

---

Join us in building the future of legacy system modernization!

Get Started Now | Documentation