Summary
The Perl client currently ships duplicate modules that differ only by filename case, such as lib/Hlquery/Client.pm and lib/Hlquery/client.pm. This is a release-blocking portability issue: case-insensitive filesystems cannot reliably store or install both files, which can break packaging, CPAN distribution, and downstream installs on macOS/Windows.
Context
The problem appears to have been introduced in ff15f2c, which added lowercase compatibility wrappers for all major classes:
lib/Hlquery/Client.pm and lib/Hlquery/client.pmlib/Hlquery/Collections.pm and lib/Hlquery/collections.pmlib/Hlquery/Documents.pm and lib/Hlquery/documents.pmlib/Hlquery/Request.pm and lib/Hlquery/request.pmlib/Hlquery/Response.pm and lib/Hlquery/response.pmlib/Hlquery/Search.pm and lib/Hlquery/search.pm
On Linux this may appear to work, but on case-insensitive filesystems these paths collide. For a client library intended to front a high-performance search engine, installability and operational predictability are foundational: if users cannot reliably install the wrapper across environments, none of the runtime performance benefits matter.
This risk is amplified by the current simplified codebase, which no longer has strong validation/exception layers to absorb packaging or load-path ambiguity. The uncommitted README cleanup also suggests the public surface is still settling, which makes it a good time to normalize module naming before external adoption increases.
Proposed Implementation
- Choose one canonical public namespace convention and enforce it across the package. The safest option is standard Perl casing:
Hlquery::Client, Hlquery::Collections, Hlquery::Documents, Hlquery::Request, Hlquery::Response, and Hlquery::Search.
- Remove case-duplicate
.pm files from lib/Hlquery/ so the tarball contains only one filesystem representation per module.
- If backward compatibility for lowercase imports is required, implement it without duplicate files. Options include:
- documenting canonical imports only and treating lowercase usage as unsupported, or
- adding a controlled alias/loading strategy from a single canonical module path.
- Add a packaging/install test that fails if two library paths differ only by case.
- Validate the built distribution on at least one case-insensitive environment or with a tarball-level collision check in CI.
Impact
Fixing this prevents cross-platform install failures, reduces release risk, and makes the Perl client viable for broader distribution. It also simplifies long-term maintenance by removing namespace ambiguity and ensures the hlquery client can be adopted reliably in production environments where packaging hygiene matters as much as raw search performance.
Summary
The Perl client currently ships duplicate modules that differ only by filename case, such as
lib/Hlquery/Client.pmandlib/Hlquery/client.pm. This is a release-blocking portability issue: case-insensitive filesystems cannot reliably store or install both files, which can break packaging, CPAN distribution, and downstream installs on macOS/Windows.Context
The problem appears to have been introduced in
ff15f2c, which added lowercase compatibility wrappers for all major classes:lib/Hlquery/Client.pmandlib/Hlquery/client.pmlib/Hlquery/Collections.pmandlib/Hlquery/collections.pmlib/Hlquery/Documents.pmandlib/Hlquery/documents.pmlib/Hlquery/Request.pmandlib/Hlquery/request.pmlib/Hlquery/Response.pmandlib/Hlquery/response.pmlib/Hlquery/Search.pmandlib/Hlquery/search.pmOn Linux this may appear to work, but on case-insensitive filesystems these paths collide. For a client library intended to front a high-performance search engine, installability and operational predictability are foundational: if users cannot reliably install the wrapper across environments, none of the runtime performance benefits matter.
This risk is amplified by the current simplified codebase, which no longer has strong validation/exception layers to absorb packaging or load-path ambiguity. The uncommitted README cleanup also suggests the public surface is still settling, which makes it a good time to normalize module naming before external adoption increases.
Proposed Implementation
Hlquery::Client,Hlquery::Collections,Hlquery::Documents,Hlquery::Request,Hlquery::Response, andHlquery::Search..pmfiles fromlib/Hlquery/so the tarball contains only one filesystem representation per module.Impact
Fixing this prevents cross-platform install failures, reduces release risk, and makes the Perl client viable for broader distribution. It also simplifies long-term maintenance by removing namespace ambiguity and ensures the hlquery client can be adopted reliably in production environments where packaging hygiene matters as much as raw search performance.