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:

1. 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.
2. 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.
3. 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.
4. 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:

1. escolha o representative como base da especificação determinística;
2. transforme variationPoints em parâmetros, Strategy objects ou métodos protegidos/sobrescritos;
3. execute os geradores de documentação, cápsulas e testes de caracterização do toolkit para cada membro;
4. 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