Metadata-Version: 2.4
Name: mainframe-modernization-toolkit
Version: 0.1.19
Summary: Deterministic COBOL/JCL analysis and mainframe modernization tooling
Author: Mainframe Migration Toolkit Contributors
License-Expression: Apache-2.0
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<3,>=2
Provides-Extra: release
Requires-Dist: build>=1.2; extra == "release"
Requires-Dist: twine>=6; extra == "release"
Provides-Extra: aws
Requires-Dist: boto3<2,>=1.34; extra == "aws"
Provides-Extra: postgres
Requires-Dist: psycopg[binary]<4,>=3.1; extra == "postgres"
Provides-Extra: pyspark
Requires-Dist: pyspark<5,>=3.5; extra == "pyspark"
Provides-Extra: runtime
Requires-Dist: boto3<2,>=1.34; extra == "runtime"
Requires-Dist: psycopg[binary]<4,>=3.1; extra == "runtime"
Requires-Dist: pyspark<5,>=3.5; extra == "runtime"
Dynamic: license-file

# Mainframe Modernization Toolkit

Deterministic tools and agent instructions for migrating a JCL-bounded COBOL workload to Python or PySpark.

The toolkit discovers source relationships, validates configuration and record layouts, extracts SQL and business rules, generates typed boundaries, compiles validated relational IR to PySpark, and compares final outputs with an authoritative Golden Dataset. It does not invent missing source semantics.

## Install

Python 3.10 or newer is required.

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

Optional runtime dependencies:

```bash
python -m pip install "mainframe-modernization-toolkit[pyspark]"
python -m pip install "mainframe-modernization-toolkit[aws]"
```

## Initialize A Workspace

```bash
mainframe-toolkit workspace init . --target vscode
mainframe-toolkit workspace init . --target claude
mainframe-toolkit workspace init . --target all
```

The initializer adds `mainframe-migration.json`, JSON schemas, and the selected agent integration without overwriting existing files. Configure source directories, encoding, extensions, known external dependencies, transport profiles, environment facts, and `targetCapabilities` in `mainframe-migration.json`.

For Claude Code, verify the project MCP server with `claude mcp list` or `/mcp`.

## Migration Workflow

A migration starts from one JCL. A compact campaign inventories the job, then processes one program at a time so large jobs do not produce one huge preflight response.

```bash
mainframe-toolkit run migration_campaign -- init . --jcl MYJOB --format json
mainframe-toolkit run migration_campaign -- next . --jcl MYJOB --worker local --format json
```

For each selected program:

1. Resolve dependencies, callers, copybooks, impact, and blockers.
2. Generate canonical record contracts and readers.
3. Extract SQL and business rules.
4. Generate one program capsule containing machine-readable I/O and partial IR.
5. Implement cohesive business logic and focused tests.
6. Validate relational IR and compile PySpark when appropriate.
7. Mark the program complete and claim the next one.

After all programs are implemented, compose the JCL pipeline and compare its final output with an authoritative Golden Dataset.

```bash
mainframe-toolkit validate-golden . --manifest validation/job-output.json --format json
```

Intermediate program outputs do not require Golden files when the migrated job passes DataFrames in process. Validate those boundaries with explicit contracts and focused tests.

## Core Commands

| Command | Purpose |
|---|---|
| `migration_preflight` | Validate sources, references, environment, scope, and target capabilities. |
| `migration_campaign` | Track compact program-at-a-time progress for one JCL. |
| `dependency_graph` | Build CALL, COPY, and EXEC relationships. |
| `impact_analysis` | Calculate transitive impact. |
| `dead_code_finder` | Find unreferenced migration candidates. |
| `jcl_flow_extractor` | Extract JCL flow and generate a local runner. |
| `migration_complexity_report` | Order programs by deterministic risk. |
| `copybook_to_contract` | Generate canonical record contracts. |
| `copybook_to_dataclass` | Generate Python boundary models. |
| `generate_copybook_fixtures` | Generate ingestion-only test records. |
| `generate_file_readers` | Generate contract-based readers. |
| `sql_extractor` | Extract SQL and host variables. |
| `business_rule_extractor` | Extract conditional rules with source locations. |
| `characterization_test_scaffolder` | Generate a starting characterization test. |
| `generate_program_capsule` | Generate a program manifest, contracts, and partial IR. |
| `validate_relational_ir` | Validate typed relational IR. |
| `ir_to_pyspark` | Compile executable IR to PySpark. |
| `golden_validate` | Compare authoritative expected and actual CSV files. |

Run any command through the stable entry point:

```bash
mainframe-toolkit run <command> -- <arguments>
```

## AWS Glue And Local PySpark

Use the `aws-glue-pyspark` starter profile when creating a new configuration:

```bash
mainframe-toolkit run migration_preflight -- . --write-template --profile aws-glue-pyspark
```

Keep transformations in `transform_frames()`. Production wrappers can use Glue Catalog, S3, and Iceberg descriptors; local runners can load semicolon-delimited CSV files with explicit schemas and invoke the same transformations.

The toolkit does not provision AWS resources. IAM, Lake Formation, buckets, Glue jobs, Catalog tables, bookmarks, connectors, and Iceberg configuration belong in deployment infrastructure.

## Safety Boundaries

- Missing copybooks, PROCs, conflicting sources, parse failures, and unsafe layouts block the affected migration.
- Unknown external programs remain explicit adapter TODOs.
- Synthetic fixtures validate ingestion, not business equivalence.
- Only mainframe output or a verified equivalent implementation is an authoritative Golden Dataset.
- Generated relational IR with TODOs is non-executable.

See [docs/JCL-MIGRATION-GUIDE.md](docs/JCL-MIGRATION-GUIDE.md) for the concise end-to-end procedure.
