Legacy Similarity Analyzer
Ferramenta independente para encontrar JCLs e programas COBOL que podem ser migrados como uma única implementação parametrizável, com estratégias ou métodos sobrescritos apenas nos pontos que variam.
Ela não altera os fontes analisados e não importa o pacote
mainframe_modernization_toolkit. Os extratores deste projeto são próprios,
menores e sem dependências externas. O toolkit existente foi usado apenas como
referência para os fatos determinísticos importantes (steps/DDs/condições em
JCL e parágrafos/CALL/COPY/SQL/I-O em COBOL).
Estratégia
Uma comparação textual simples gera muitos falsos negativos: nomes de campos, datasets, programas e literais mudam mesmo quando o algoritmo é o mesmo. Fazer uma comparação estrutural cara de todos contra todos, por outro lado, não escala bem.
O analisador usa um pipeline em duas etapas:
- Perfil estrutural determinístico
- COBOL: remove comentários e áreas de sequência, canonicaliza identificadores locais, extrai n-grams, sequência de verbos, parágrafos, CALLs, COPYs, operações SQL/I-O e formatos PIC.
- JCL: combina continuações e extrai fluxo de EXEC/DD/IF, tipo de target, forma dos DDs, DISP, programas, procedures, datasets e condições.
- Recuperação MinHash/LSH
- cria 64 assinaturas por artefato e 16 bandas;
- somente itens que colidem em alguma banda viram candidatos;
- duplicatas estruturais exatas sempre são candidatas.
- Pontuação explicável
- combina estrutura, ordem, interface e tamanho;
- JCL nunca é comparado com COBOL;
- o relatório mostra as parcelas da pontuação e as diferenças concretas.
- Agrupamento conservador (complete-link incremental)
- um arquivo só entra no grupo se atingir o limiar contra todos os membros existentes;
- isso evita o perigoso efeito corrente: A é parecido com B, B com C, mas A não é parecido com C.
Para aproximadamente 700 JCLs e 500 COBOLs, Python é suficiente. Há cerca de 370 mil pares possíveis separados por tipo; o LSH normalmente elimina a maior parte antes da comparação detalhada. Spark só passa a ser interessante para milhões de artefatos ou quando os perfis já vivem em um data lake distribuído.
Uso
Requer Python 3.10 ou superior e não possui dependências de runtime.
cd legacy_similarity_analyzer
python -m pip install -e .
legacy-similarity /caminho/do/codebase \
--config similarity-config.json \
--output similarity-report.json \
--threshold 0.80 \
--cluster-threshold 0.82
A execução gera dois relatórios:
similarity-report.json: relatório completo, incluindo artefatos e grupos;similarity-report.csv: relação enriquecida entre arquivo e cluster, pronta para banco relacional, Excel, Google Sheets ou ingestão em Spark.
O CSV inclui todos os arquivos analisados e o contexto necessário para gerar relatórios relacionais:
programa,cluster_id,tipo,nome_logico,representante,score_representante,tamanho_cluster,status
cobol/BILL001.cbl,COBOL-0001,cobol,BILL001,true,1.000000,2,AGRUPADO
cobol/BILL999.cbl,COBOL-0001,cobol,BILL999,false,0.934821,2,AGRUPADO
cobol/UNIQUE.cbl,,cobol,UNIQUE,false,,0,ISOLADO
jcl/DAILY.jcl,JCL-0001,jcl,DAILY,true,1.000000,2,AGRUPADO
jcl/MONTHLY.jcl,JCL-0001,jcl,MONTHLY,false,0.882450,2,AGRUPADO
Um cluster_id vazio significa que o arquivo não foi agrupado com nenhum
outro artefato. score_representante é a similaridade do membro contra o
arquivo-base do cluster; o representante sempre recebe 1.000000.
O caminho do CSV é derivado automaticamente do JSON. Para escolher outro:
legacy-similarity /caminho/do/codebase \
--output reports/full-report.json \
--csv-output reports/similar-pairs.csv
O arquivo de configuração determina exclusivamente quais extensões representam JCL e COBOL. Não há inferência pelo conteúdo:
{
"jclExtensions": [".jcl", ".proc", ".prc", ".job"],
"cobolExtensions": [".cbl", ".cob", ".cobol", ".pgm"]
}
O ponto inicial é opcional ("jcl" e ".jcl" são equivalentes), e a
comparação não diferencia maiúsculas de minúsculas. Veja também
similarity-config.example.json.
Também pode ser usado como classe:
from legacy_similarity import LegacySimilarityAnalyzer, SimilarityConfig
analyzer = LegacySimilarityAnalyzer(
SimilarityConfig(
jcl_suffixes=(".job", ".proc"),
cobol_suffixes=(".pgm", ".cbl"),
similarity_threshold=0.80,
cluster_threshold=0.82,
)
)
report = analyzer.analyze_directory("/caminho/do/codebase")
report.write_json("similarity-report.json")
report.write_csv("similarity-report.csv")
# Comparação direta, útil durante uma revisão:
pair = analyzer.compare_files("jobs/DAILY.jcl", "jobs/MONTHLY.jcl")
print(pair.score, pair.differences)
O JSON contém:
groups: candidatos seguros para uma implementação comum;matches: pares semelhantes, suas pontuações e diferenças;artifacts: fatos extraídos para auditoria;stats: redução de candidatos e tempo de cada etapa.
Como usar o resultado na migração
O grupo é uma hipótese de consolidação, não uma autorização automática para apagar regras legadas. Para cada grupo:
- escolha o
representativecomo base da especificação determinística; - transforme
variationPointsem parâmetros, Strategy objects ou métodos protegidos/sobrescritos; - execute os geradores de documentação, cápsulas e testes de caracterização do toolkit para cada membro;
- somente consolide quando todos os testes do legado passarem contra a mesma implementação moderna.
Comece com limiar 0.85 para alta precisão. Depois revise falsos negativos e
reduza gradualmente até 0.78–0.80. Não é recomendável usar abaixo de 0.70
para decidir consolidação sem uma revisão humana forte.
Testes
python -m unittest discover -s tests -v
Metadata
Release files for legacy-similarity-analyzer 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| legacy_similarity_analyzer-0.1.2.tar.gz | 27.2 kB | Without provenance | Details for legacy_similarity_analyzer-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| legacy_similarity_analyzer-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for legacy_similarity_analyzer-0.1.2-py3-none-any.whl |
Total release size: 49.4 kB
Release files / legacy_similarity_analyzer-0.1.2.tar.gz
| Download URL | legacy_similarity_analyzer-0.1.2.tar.gz |
|---|---|
| Size | 27.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ada637da27775ed56928fdb417b4b23018effc76d1322432027ee19ad4ac7831
|
|
BLAKE2b-256 checksum How to use checksums |
c1a567f5230a97f2b3531df3dfcdc73a86afc7b25086af7dceffd2112ab08fd4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.13
|
Release files / legacy_similarity_analyzer-0.1.2-py3-none-any.whl
| Download URL | legacy_similarity_analyzer-0.1.2-py3-none-any.whl |
|---|---|
| Size | 22.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
19f170adb00f298cb04261ba12ce92505512a38d42419c7410f2756f477621a7
|
|
BLAKE2b-256 checksum How to use checksums |
b18495af87d26321e0f69a7c309c8a849c5b5d1044fe2ecd32c7c620853e2614
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.13
|
Security for legacy-similarity-analyzer 0.1.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.