Punchcard

Modernization support for legacy COBOL systems — built for teams that need clarity before they change critical code.

Punchcard is a COBOL analysis and review workbench designed to help organizations understand legacy programs, identify risky logic, and prepare safer modernization plans. It combines parser-backed source analysis with optional LLM-assisted explanations so teams can move from "we are afraid to touch this" to a clear, auditable review workflow.

If you found this project through Fiverr, Upwork, or my freelance portfolio, Punchcard represents the type of practical modernization tooling I can build, adapt, or extend for your business.

I work with clients who need dependable engineering support around legacy systems, automation, and modernization. Typical engagements include:

• COBOL code review and inventory — map programs, paragraphs, copybooks, file operations, external calls, and high-risk control flow.
• Modernization planning — turn undocumented legacy code into a phased migration roadmap with clear risks, dependencies, and delivery milestones.
• Static analysis tools — build custom analyzers, parsers, dashboards, and reports for proprietary source code.
• LLM-assisted review workflows — add guarded AI explanations, rewrite suggestions, and audit trails without blindly trusting model output.
• Internal developer tools — create CLIs, web apps, APIs, and automation scripts that reduce manual review time.
• Secure integration work — connect tools to internal systems while protecting sensitive source code and business data.

Legacy code often runs business-critical operations, but many teams lack the original authors, documentation, or safe test coverage. Modernization efforts fail when teams start rewriting before they understand the system.

Punchcard is built around a safer process:

1. Parse the source into a structured representation.
2. Preserve traceability back to the original lines of code.
3. Score risk and complexity so reviewers know where to focus first.
4. Review changes paragraph by paragraph instead of attempting a risky big-bang rewrite.
5. Export an audit trail so decisions are visible and repeatable.

The goal is not to replace experienced engineers. The goal is to give them better tools.

Punchcard targets COBOL-85 (ISO 1989) with common extensions. The support contract is versioned and machine-readable: run uv run punchcard --compatibility or call GET /compatibility on the API to see the current contract.

These constructs produce diagnostics and are never silently treated as successfully analyzed:

• REPORT WRITER (RW) control statements
• DEBUGGING MODE (WITH DEBUGGING) clauses
• SCREEN SECTION interactive ACCEPT/DISPLAY
• COMMUNICATION SECTION message processing
• SORT/MERGE with INPUT PROCEDURE / OUTPUT PROCEDURE (recognized but not modeled)
• Nested programs (program-id … END PROGRAM)
• Object-oriented COBOL extensions (INVOKE, class-id, etc.)
• COBOL 2002/2014/2023 features (free-format beyond basic support, XML, JSON, etc.)
• IBM Enterprise COBOL extensions (INLINE, XML PARSE, JSON PARSE, etc.)
• Micro Focus / GnuCOBOL dialect-specific directives
• DECLARATIVES (USE procedures)
• SEGMENTATION (section priority numbers)

Unknown or unsupported syntax produces explicit diagnostics — never silent success. Diagnostics are categorized by severity (error, warning, info) and category (parse_error, unsupported_construct, unresolved_copybook, etc.). They appear in CLI output, API responses, and exports. See punchcard/backend/compatibility.py for the full taxonomy.

AI-assisted translation is opt-in. No COBOL source leaves the process unless an ANTHROPIC_API_KEY is explicitly configured and the process is not in test mode. AI output is advisory only. Parser facts, dependency edges, and risk scores are never altered by AI.

Depending on your needs, I can turn this foundation into a client-ready deliverable such as:

• A COBOL inventory report for a specific application portfolio.
• A risk-ranked modernization assessment.
• A searchable web dashboard for legacy programs and copybooks.
• A secure internal review tool with role-based workflow.
• A custom parser or analyzer for your organization's coding standards.
• A migration planning document with MVP scope, milestones, and technical tradeoffs.
• A proof of concept that translates selected COBOL paragraphs into another language for human review.

I prefer small, useful milestones over vague large projects. A typical engagement looks like this:

1. Discovery — confirm goals, constraints, sample inputs, security requirements, and success criteria.
2. Prototype — build or adapt a narrow workflow against representative source files.
3. Review — validate output with your subject-matter experts and adjust assumptions.
4. Production hardening — add authentication, logging, deployment scripts, tests, and documentation as needed.
5. Handoff — deliver source code, setup instructions, usage documentation, and a clear next-step roadmap.

Legacy source code can contain sensitive business logic, credentials, data formats, and operational procedures. Punchcard is designed with a conservative default posture:

• No external LLM calls are made unless an API key is explicitly configured.
• Proprietary source should not be sent to third-party AI services without written approval.
• Client projects should define a redaction policy, retention policy, and audit process before using hosted AI models.
• Local/offline workflows are preferred when confidentiality requirements are strict.

Punchcard is built with pragmatic, maintainable tools:

• Python 3.12 for the backend and command-line tooling.
• FastAPI for the review API.
• ANTLR-based COBOL parsing for structured source analysis.
• Textual for the terminal interface.
• React + Vite for the web interface.
• Pytest and Ruff for testing and code quality.

Developers can run Punchcard locally with uv:

uv sync --dev
uv run pytest
uv run punchcard fixtures/hello.cbl

View the supported-dialect contract:

uv run punchcard --compatibility

To start the terminal UI:

uv run punchcard-tui --source program.cbl

To build and serve the web UI:

cd frontend
npm install
npm run build
cd ..
uv run punchcard-web

If you need help understanding, modernizing, or safely automating around legacy systems, I can help turn your source code and operational goals into a practical plan.

Useful starting points for a first message:

• What language or system do you need reviewed?
• How many programs, files, or lines of code are involved?
• Are there copybooks, JCL, database schemas, or external integrations?
• Do you need a report, a working tool, a migration plan, or implementation support?
• Are there confidentiality or offline-only requirements?

I can start with a focused assessment and then scale into tooling, automation, or modernization support once the highest-value path is clear.