feat(pubmed): envolver saída em ArticleSet/DOCTYPE e corrigir ordem dos elementos

[Rossi-Luciano]

O que esse PR faz?

Adiciona o envelope <!DOCTYPE ArticleSet ...> + <ArticleSet> exigido pela DTD do PubMed à saída de packtools/sps/formats/pubmed.py, que hoje gera um <Article> solto e inválido segundo a DTD oficial.

• Extrai a construção do <Article> (antes inline em pipeline_pubmed) para build_pubmed_article(xml_tree).
• Adiciona pipeline_pubmed_set(xml_trees, pretty_print=True), que agrupa N artigos num único <ArticleSet> — pré-requisito para o processamento em lote da CLI (Pubmed XML: CLI em lote (.zip) e registro como comando instalável #1241).
• Mantém pipeline_pubmed(xml_tree, pretty_print=True) com a assinatura original (delega para pipeline_pubmed_set([xml_tree], ...)), então nenhum código que já chama essa função quebra.

Ao validar a saída contra a DTD oficial real do PubMed (não o validador web citado na issue-mãe, que é para outro formato — ver seção de contexto), apareceram 2 bugs no pipeline existente, corrigidos neste PR:

• Abstract/OtherAbstract precisavam vir antes de CopyrightInformation/CoiStatement/ObjectList/ReferenceList no <Article> — a DTD exige essa ordem (Abstract?, OtherAbstract*, CopyrightInformation?, CoiStatement?, ObjectList?, ReferenceList*), e o pipeline gerava na ordem inversa.
• xml_pubmed_vernacular_title_pipe nunca era chamado dentro do pipeline, apesar de implementado e coberto por teste próprio (test_xml_pubmed_vernacular_title_pipe) — código morto por falta de wiring.

Onde a revisão poderia começar?

packtools/sps/formats/pubmed.py, a partir da constante PUBMED_DOCTYPE até o fim do arquivo: xml_pubmed_article_set_pipe, build_pubmed_article, pipeline_pubmed_set, pipeline_pubmed. Nenhuma função de pipe individual (xml_pubmed_X_pipe) foi alterada — só a orquestração e ordem em volta delas.

Como este poderia ser testado manualmente?

1. Rodar a suíte: source .venv/bin/activate && python -m pytest tests/sps/formats/test_pubmed.py -v (48 passed: 46 originais + 2 novos cobrindo o envelope).
2. Gerar um XML real via CLI:

   python -m packtools.sps.formats.pubmed_generator \
     -i tests/samples/0034-7094-rba-69-03-0227.xml \
     -o /tmp/saida.pubmed.xml
   

   Confirmar visualmente que a saída tem DOCTYPE + <ArticleSet><Article>...</Article></ArticleSet>, não um <Article> solto.
3. Validar contra a DTD oficial:

   curl -o /tmp/PubMed.dtd https://dtd.nlm.nih.gov/ncbi/pubmed/in/PubMed.dtd
   python3 - <<'PY'
   from lxml import etree as ET
   dtd = ET.DTD('/tmp/PubMed.dtd')
   doc = ET.parse('/tmp/saida.pubmed.xml')
   print('VALID:', dtd.validate(doc))
   for err in dtd.error_log:
       print(err)
   PY
   

   Resultado obtido: VALID: True, tanto para artigo único quanto para pipeline_pubmed_set com 2 artigos no mesmo ArticleSet.

Algum cenário de contexto que queira dar?

A #1226 pede um conversor completo SPS 1.10 → PubMed XML. O módulo já existia (pubmed.py/pubmed_generator.py, 46 testes) mas não do zero — o trabalho foi quebrado em 8 sub-issues (#1234–#1241), sendo esta a primeira (#1234), pré-requisito estrutural para o processamento em lote (#1241).

O link do validador referenciado na #1226 (ncbi.nlm.nih.gov/projects/linkout/doc/file-validator.html) é para XML de LinkOut (outro sistema NCBI, de outro formato) — colar a saída deste pipeline lá retorna "Unknown file content", que não é sinal de erro no XML gerado. A validação real precisa ser feita contra a DTD do PubMed ArticleSet (https://dtd.nlm.nih.gov/ncbi/pubmed/in/PubMed.dtd, a mesma referenciada no DOCTYPE que este PR adiciona), via lxml.etree.DTD ou xmllint --dtdvalid. Foi assim que os 2 bugs de ordenação/wiring corrigidos aqui foram encontrados.

Um terceiro achado da validação (Journal/PubDate obrigatório na DTD, mas ausente quando o artigo fonte não tem data reconhecida) ficou fora do escopo deste PR e virou a #1242.

Screenshots

Não se aplica — mudança em geração de XML, sem interface gráfica.

Quais são tickets relevantes?

Closes #1234. Relacionado a #1226 (issue-mãe), #1241 (depende deste PR), #1242 (achado durante a validação, escopo separado).

Referências

• DTD oficial do PubMed: https://dtd.nlm.nih.gov/ncbi/pubmed/in/PubMed.dtd
• NCBI — PubMed XML Tagged Format: https://www.ncbi.nlm.nih.gov/books/NBK3828/#publisherhelp.PubMed_XML_Tagged_Format

[Rossi-Luciano]

Adicionado mais um commit a este PR (0d4b37c). Encontrado ao validar as 26 amostras reais de tests/samples/*.xml contra a DTD real do PubMed (em vez de só 1-2 arquivos escolhidos a dedo, como vinha sendo feito até então):

1. get_date() só reconhecia article_date (epub), ignorando collection_date (pub-type="epub-ppub"/date-type="collection", o padrão mais comum em artigos SciELO mais antigos). Isso fazia 21 de 26 (81%) das amostras reais serem descartadas do lote inteiro por "falta de PubDate", quando na verdade tinham data — só não no formato que o código reconhecia. references.py e oai_dc.py já fazem esse fallback manualmente; só pubmed.py não fazia.

2. xml_pubmed_citations quebrava com AttributeError quando <ref-list> não tem <title> (opcional no JATS), pois presumia que xml_pubmed_title_reference_list já tinha criado <ReferenceList>. Agora cria o elemento se necessário — válido pela DTD (ReferenceList (Title?, Reference*, ReferenceList*)).

3. get_first_page só olhava elocation-id, nunca fpage; LastPage não existia. Artigos com paginação tradicional (fpage/lpage) perdiam essa informação por completo — confirmado com a amostra 0034-7094-rba-69-03-0227.xml (fpage=227, lpage=232, sem elocation-id): nenhum dos dois aparecia na saída. Agora FirstPage prefere fpage e cai para elocation-id só quando não há paginação (fluxo de Publicação Contínua); LastPage foi implementado.

Validado: 24/26 amostras reais passam na DTD real agora (as 2 restantes dependem do fix de Author FirstName/LastName de #1236/#1245 e do fallback or [] em get_affiliations, ainda não mesclados nesta branch — não são regressão destes fixes, confirmei revertendo e comparando).

Suíte: 57/57 passando.

[Rossi-Luciano]

Adicionado mais um commit (6414737): suíte de integração fim-a-fim (tests/sps/formats/test_pubmed_integration.py).

Até agora test_pubmed.py só testava cada pipe isoladamente com XML sintético mínimo — nada rodava o pipeline completo numa amostra real e validava contra a DTD de verdade. Essa lacuna foi exatamente o motivo dos 3 bugs do commit anterior (PubDate/collection_date, crash em citations, FirstPage/LastPage) terem passado despercebidos por 8 PRs já abertos.

A suíte nova:

• Roda build_pubmed_article + build_article_set_xml em cada uma das 26 amostras reais de tests/samples/*.xml.
• Valida o resultado contra a DTD real do PubMed, agora vendorizada em tests/fixtures/pubmed/PubMed.dtd (não depende de rede — testado offline explicitamente, já que CI não deveria depender do servidor da NLM estar no ar).
• Duas amostras (example.xml, 0034-8910-rsp-48-2-0249.xml) ainda dependem de fixes que vivem em Pubmed XML: adicionar Suffix e CollectiveName em AuthorList #1236/PR feat(pubmed): adicionar Suffix e CollectiveName em AuthorList #1245 (pareamento FirstName/LastName e fallback or [] em get_affiliations), ainda não mesclados nesta branch — marcadas em KNOWN_FAILURES com asserção invertida, então a suíte avisa (em vez de silenciosamente passar) quando alguém puder remover a entrada, ao invés de simplesmente ficar verde por acaso.

Testado: confirmei que a suíte realmente pega regressão (reverti o fix de collection_date momentaneamente em memória e vi 21 subtestes falharem, como esperado).