Skip to main content

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

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)

Source distribution for legacy-similarity-analyzer 0.1.2
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)

Table of built distributions (wheels) for legacy-similarity-analyzer 0.1.2
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page