Versioned parsers/serializers/translators + central registry + upgrades through generic queries (IR)

[geritwagner]

Summary

This PR introduces a versioned architecture for parsers, serializers, and translators (e.g., pubmed/v1, wos/v1, ebsco/v1) alongside a central registry that resolves the latest implementation per platform at runtime. It also lays the groundwork for IR-based upgrades (generic intermediate representation) and adds linter guidance for deprecated syntax.

Context

Addresses reviewer concerns (search-query-paper #54) about backward compatibility when database syntaxes evolve. Rather than saving queries redundantly in a structured format, we pin and store the syntax version with each saved query and provide a maintainable path to upgrade queries between versions.

Design

• Versioned modules: Parsers, serializers, and translators are versioned independently.

• Central registry & latest resolution (parser, serializer, translator): SERIALIZERS: dict[str, dict[str, type[StringSerializer]]] keyed by semantic version. LATEST_SERIALIZERS selects the newest per platform using packaging.version.Version.

• Generic query objects serve as Intermediate Representations (IR) for upgrades and cross-platform translations.

• Linters: Added platform-specific “deprecated-syntax” messages, so users receive actionable hints when their query uses outdated constructs.

Repository layout

Adopts a layout that scales with multiple versions and keeps code readable:

search_query/
  pubmed/
    v1/
      parser.py
      serializer.py
      translator.py
    v2/
      ...
  ebsco/
    ...
  wos/
    ...

Version policy

• MAJOR: grammar changes that alter the parser.

Backward compatibility & migration

• Saved queries should include:

  {
    "platform": "Web of Science",
    "search_string": "TS=(quantum AND dot AND spin)",
    "version": "1"
  }

• On load, the dispatcher resolves the requested (or latest) version; IR-based upgrade paths convert older versions forward.

Testing

• Golden files per version to verify stability. (currently TODO)
• Linter tests for “deprecated-syntax” diagnostics.

Optional user workflow

• Users may add a generic/structured form to their search history if they want redundancy, but the default path is version pinning + IR upgrades (no duplicate storage required).