# To read this file, run:
#    perldoc TODO.pod

=encoding utf8

=head1 NAME

TODO - Roadmap, ecosystem, and help-wanted items for GDPR::IAB::TCFv2

=head1 STATUS

C<GDPR-IAB-TCFv2> entered B<maintenance mode> on 2026-05-09 with the
v0.400 release. The core parser, validator, and CMP-validator surfaces
are considered feature-complete for IAB TCF v2.3.

In maintenance mode the maintainer commits to:

=over 4

=item *

bug fixes,

=item *

security fixes,

=item *

CPAN-tester regression triage,

=item *

tracking IAB-spec updates (TCF v2.4 / v3 if and when they ship).

=back

Larger feature work -- the three remaining roadmap phases below, the
distribution items, and the sister-distribution ideas -- is now tracked
as B<help-wanted> issues on GitHub. Patches and PRs from the community
are still welcome and will continue to be reviewed.

=head1 COMPLETED PHASES

The phases below shipped between v0.270 and v0.400. They are listed
here for historical context only; details live in F<CHANGELOG.md> and
the linked PRs.

=over 4

=item Phase 0 -- Core legal-basis predicates

C<is_vendor_consent_allowed>, C<is_vendor_legitimate_interest_allowed>,
C<is_vendor_allowed_for_flexible_purpose>, plus C<strict> mode.

=item Phase 1 -- TCF v2.3 segments and parser robustness

Disclosed Vendors / Allowed Vendors segments, multi-segment safety,
C<has_vendor_disclosure>, C<has_publisher_restrictions>, the
C<vendor_id> filter on C<TO_JSON>, and the automated release workflow.

=item Phase 2 -- Declarative validator interface

C<GDPR::IAB::TCFv2::Validator> with C<validate> / C<validate_all> and
C<Validator::Result>.

=item Phase 3 -- Alignment and cleanup

Purpose names normalized to TCF v2.3 wording; POD streamlined.

=item Phase 4 -- Performance pass

Bitfield decode optimizations and golden-corpus benchmarks.

=item Phase 5 -- CMP validator

C<GDPR::IAB::TCFv2::CMPValidator> with file / JSON / URL loading,
staleness warning, and integration into the main validator as a rule.

=item Phase 6 -- Structured failure reporting

Five sub-phases (6.1 -- 6.5) delivering C<Validator::Reason> codes,
C<Validator::Failure> objects, the TCF LI carve-out, distinct
publisher-restriction reasons, and per-call list overrides.

=back

=head1 HELP WANTED -- ROADMAP PHASES

Three roadmap phases were originally planned for inclusion in this
distribution but are now open for community contribution. Each is
self-contained and can ship as an independent PR; pick one and open
(or claim) the corresponding C<help-wanted> + C<roadmap> issue on
GitHub.

=head2 Phase 7 -- GVL-Aware Validator

Bridge the IAB Global Vendor List schema to the Phase 2 validator so
callers do not have to translate vendor entries by hand.

Scope:

=over 4

=item *

C<from_gvl_vendor_entry($vendor_entry)> -- accept a single GVL vendor
entry (C<{ id, purposes, legIntPurposes, flexiblePurposes }>) and
return the keyword-argument list expected by C<< Validator->new >>.

=item *

C<from_gvl($gvl_doc, $vendor_id)> -- look up the vendor in a parsed
GVL document and return a fully configured C<Validator>; fail fast
if the vendor ID is missing.

=item *

Flexible GVL input: file path, raw JSON string, or pre-parsed hashref.

=item *

CLI integration: C<iabtcfv2 validate --gvl path/to/gvl.json -v 32 ...>
should derive C<-C> / C<-L> / C<-F> from the GVL entry.

=item *

Tests: golden GVL fixture covering vendors with and without flexible
purposes; round-trip C<from_gvl_vendor_entry> against a hand-crafted
entry.

=back

=head2 Phase 8 -- Features, Special Features, Special Purposes

Extend the validator beyond standard purposes to cover the rest of the
TCF taxonomy. Should consume the C<REASON_*> codes introduced in
Phase 6.

Scope:

=over 4

=item *

Validator support for B<Special Features> (opt-in, e.g. precise
geolocation): require the bit in the TC string when listed.

=item *

Validator support for B<Features> (vendor-declared): no consent
required, but cross-check the vendor's GVL declaration once Phase 7
lands.

=item *

Validator support for B<Special Purposes>: legitimate-interest-only by
spec; check vendor declaration without requiring a consent bit.

=item *

Surface on the CLI as C<--special-features> / C<--features> /
C<--special-purposes> (comma-separated, same shape as C<-C> / C<-L>).

=item *

Tests: extend F<t/06-validator.t> with subtests per category; extend
F<t/10-cli-iabtcfv2.t> with CLI subtests.

=back

=head2 Phase 9 -- CLI Configuration Loading

Reduce CLI boilerplate by letting common flags come from the
environment or a config file.

Scope:

=over 4

=item *

Map a curated set of env vars to CLI flags: C<IABTCFV2_VENDOR_ID>,
C<IABTCFV2_CONSENT_PURPOSES>,
C<IABTCFV2_LEGITIMATE_INTEREST_PURPOSES>,
C<IABTCFV2_FLEXIBLE_PURPOSES>, C<IABTCFV2_MIN_POLICY_VERSION>.
Explicit CLI flags always win.

=item *

Optional config-file discovery: F<.iabtcfv2rc> in C<$PWD> or C<$HOME>
(plus C<.env>-style loading if present). Documented precedence:
CLI > env > file > built-in defaults.

=item *

C<iabtcfv2 config> (or C<validate --print-config>) to dump the resolved
configuration as JSON for debugging.

=item *

**Tests:** a CLI subtest that sets the env vars, runs C<validate> without
the matching flags, and asserts the same outcome as the explicit
invocation.

=back

=head2 Phase 10 -- Advanced Error Handling

Modernize exception handling across the library.

Scope:

=over 4

=item *

Implement C<GDPR::IAB::TCFv2::Error> exception objects.

=item *

Overload stringification to provide clean messages while retaining
metadata (code, file, line).

=item *

Refactor C<croak> / C<die> calls in the library to throw objects.

=item *

Update CLI to catch objects and simplify its sanitization logic.

=back

=head2 Phase 6 follow-up -- CMPValidator structured failures (non-blocking)

Round out Phase 6 by migrating C<GDPR::IAB::TCFv2::CMPValidator>
(Phase 5) onto the structured failure-reporting model the rest of the
validator already uses. Today CMP-level failures are stringly-typed
croaks; this item brings them onto C<Validator::Failure> with stable
machine-readable codes.

Scope:

=over 4

=item *

Add a C<REASON_CMP_*> family to C<Validator::Reason>:
C<REASON_INVALID_CMP> (CMP ID not in registry),
C<REASON_CMP_DELETED> (retired CMP, C<deletedDate> honored),
C<REASON_CMP_UNKNOWN> (registry loaded but ID unclassifiable).
Update C<reason_string()> to cover them.

=item *

Refactor C<CMPValidator> (or its consumer wrapper inside the main
C<Validator> rule) to emit C<Validator::Failure> objects with the
matching codes instead of plain croaks.

=item *

Backwards compat: the human-readable text emitted by
C<Validator::Result> stringification must stay the same so existing
CLI output is unchanged.

=item *

Tests: extend F<t/14-cmp-validator.t> (and/or
F<t/16-validator-failures.t>) with subtests asserting each new code,
reusing the fixed reference dates already in place for determinism.

=back

=head1 HELP WANTED -- DISTRIBUTION


These items are about packaging the existing code, not about adding
features.

=head2 Linux package artifacts (.deb and .rpm)

Wire up a GitHub Actions workflow that, on every C<v*> tag, builds a
C<.deb> and a C<.rpm> from the released tarball and uploads both as
assets on the corresponding GitHub Release. Both packages are pure
Perl (noarch / C<all>), so a single Linux runner per format is
enough; no build matrix, no cross-arch concerns.

Suggested toolchain:

=over 4

=item *

B<.deb>: C<dh-make-perl --build --cpan-mirror=file:./> against the
C<make dist> tarball. Produces C<libgdpr-iab-tcfv2-perl_VERSION_all.deb>.
Confirm the resulting C<debian/control> picks up
C<bin/iabtcfv2> as an executable and respects the META C<recommends>.

=item *

B<.rpm>: C<cpanspec> on the tarball to produce a C<.spec>, then
C<rpmbuild -ba> inside a C<fedora:latest> container. Produces
C<perl-GDPR-IAB-TCFv2-VERSION-1.noarch.rpm>.

=item *

Upload both via C<gh release upload "$GITHUB_REF_NAME" *.deb *.rpm>.

=back

Out of scope (separate, larger efforts -- not part of this item):
filing an ITP bug to ship the package via Debian proper, hosting a
signed apt repo, or maintaining a Fedora COPR. The deliverable here is
B<artifacts on the Release page>, downloadable with C<wget> + C<dpkg -i>
or C<dnf install ./perl-GDPR-IAB-TCFv2-VERSION-1.noarch.rpm>.

=head2 Homebrew tap (macOS + Linux)

Stand up a self-hosted Homebrew tap repository
(C<peczenyj/homebrew-tap>) with a C<Formula/iabtcfv2.rb> formula that
installs the CLI from the released CPAN tarball. Users opt in with:

    brew tap peczenyj/tap
    brew install iabtcfv2

Maintenance contract: a small CI step on this repository's release
event that opens a PR against the tap repo bumping the formula's
C<url> + C<sha256>. Self-hosted (not C<homebrew-core>), so no
external review queue and no
C<homebrew-core>'s "notable + stable + popular" gate.

Same formula works on Homebrew on Linux (Linuxbrew), so this single
channel covers macOS plus a slice of Linux developer machines for
free.

=head2 Snap package (Ubuntu / cross-distro Linux)

Author a C<snapcraft.yaml> that packages C<bin/iabtcfv2> and the Perl
runtime, and publish to C<snapcraft.io> on every C<v*> tag. Users
install with:

    sudo snap install iabtcfv2

Heads-up for the contributor: snaps run under confinement, so any
file paths the CLI reads (config files, GVL JSON dumps) need to be
inside the snap-allowed locations or a C<personal-files> /
C<system-files> plug must be declared and connected. Path the
release notes accordingly so first-time users do not hit a silent
"file not found" inside the sandbox.

=head2 AUR package (Arch Linux)

Publish a C<PKGBUILD> for Arch's user repository. The recipe is
short -- C<makepkg> drives a C<perl Makefile.PL && make && make
install> against the release tarball. Best handled by a community
co-maintainer rather than this repo's CI; volunteer contributions
welcome.

=head1 ECOSYSTEM -- SISTER DISTRIBUTIONS

The following ideas are intentionally B<separate CPAN distributions>
rather than features of this one. Each adds a runtime dependency on
its host framework, so packaging them separately keeps
C<GDPR::IAB::TCFv2>'s own deps lean.

=head2 Highest priority

=over 4

=item *

L<GDPR::IAB::TCFv2::Validator::LIVR>

LIVR rule-engine binding for JSON-shaped TC payloads.

=item *

L<GDPR::IAB::TCFv2::Validator::TypeTiny>

Reusable Type::Tiny constraints (parameterized by purpose / vendor
sets) for Moo, Moose, or pure-Perl callers that prefer type-level
enforcement.

=item *

L<Plack::Middleware::GDPR::TCFv2>

Plack middleware that decodes a TC string from a request header or
cookie, attaches the parsed C<GDPR::IAB::TCFv2> object to C<< $env >>,
and short-circuits the response when consent is missing or invalid.

=back

=head2 Nice to have

=over 4

=item *

L<GDPR::IAB::TCFv2::Validator::Moose>

Moose attribute traits and role-based validation for projects that
already use Moose end-to-end.

=item *

L<GDPR::IAB::TCFv2::Validator::FormValidator>

C<Data::FormValidator> profile glue for legacy applications that drive
business validation through DFV.

=item *

L<GDPR::IAB::TCFv1>

A standalone parser for the legacy IAB TCF v1 / v1.1 consent string
format (April 2018 -- August 2020, superseded by TCF v2.0). The wire
format is unrelated to v2 -- different bit layout, no segment
structure, smaller fixed core -- so it does not belong inside this
distribution.

Audience is intentionally narrow: log spelunkers, audit teams, and
the historically curious. A useful contribution would expose a
similar surface to L<GDPR::IAB::TCFv2> (C<Parse>, C<TO_JSON>, simple
purpose / vendor predicates) without dragging in v2's validator
machinery.

=back

=head1 HOW TO CLAIM AN ITEM

=over 4

=item 1.

Open a GitHub issue (or comment on the existing one) referencing the
phase or sister-distribution name above. Include a rough scoping
sketch: what API you are proposing, what tests you will add, and which
existing module the work will touch.

=item 2.

Wait for a maintainer to assign the issue. This avoids duplicate
effort and surfaces any spec questions early.

=item 3.

Follow the patching workflow in F<CONTRIBUTING.pod>: branch from
C<devel>, run the full test suite (C<prove -lr t> plus
C<AUTHOR_TESTING=1 prove -lr xt>), open a PR.

=back

=head1 OUT OF SCOPE

The following are intentionally B<not> on the roadmap:

=over 4

=item *

TCF v1 / v1.1 support inside this distribution. The two wire formats
share nothing but the IAB acronym, so v1 belongs in a sibling
distribution rather than as a code path here. See the
L<GDPR::IAB::TCFv1> entry under L</ECOSYSTEM -- SISTER DISTRIBUTIONS>
if you are interested in claiming it.

=item *

Network-side discovery of CMP or GVL endpoints. The library accepts
pre-loaded data; fetching is the caller's responsibility (or the
optional C<HTTP::Tiny> path inside C<CMPValidator>).

=item *

Persistent caching of parsed strings. TC strings are cheap to parse;
caching is a deployment concern, not a library concern.

=back

=head1 SEE ALSO

L<GDPR::IAB::TCFv2>, L<GDPR::IAB::TCFv2::Validator>,
L<GDPR::IAB::TCFv2::CMPValidator>, F<CONTRIBUTING.pod>,
F<CHANGELOG.md>.

=cut
