GeezerVison

Five of the six enums populated from API responses coerced strictly, so any value the backend added would raise ValueError inside from_dict and empty an entire response rather than degrade one field. That is the mechanism behind issue #78 and the unknown generic purl type. Each was fixed on the single enum that happened to fire, leaving the other five holding the same landmine.

This fixes the class rather than the next instance, and adds a check that finds the next one before a customer does.

Forward-compatible enums

SocketIssueSeverity, SocketCategory, DiffType, ScanType and SecurityAction now fall back to a documented member and log the unrecognized value. SocketPURL_Type already did; its inline implementation now routes through one shared helper in socketdev/core/enums.py so all six behave and log identically. The dead try/except in SocketAlert.from_dict is removed, since _missing_ covers every coercion path rather than that one call site.

The fallbacks are chosen, not convenient:

Enforced as an invariant

tests/unit/test_enum_forward_compat.py walks the package, discovers every enum including ones added later, and fails if any raises on an unrecognized value. It also asserts the fallback is a real member of its own enum, that the warning names the enum, and that known values still round-trip.

Two details that matter: a test_enums_are_discovered guard prevents a broken walk from making every other assertion vacuously pass, and a documented REQUEST_ONLY_ENUMS opt-out (currently empty) gives a future request-building enum a legitimate escape hatch — strictness is correct where the value comes from the caller, not the API.

Drift detection with no setup

scripts/check_api_enum_drift.py compares the SDK's enums against https://api.socket.dev/v0/openapi. That spec is public and unauthenticated, so this needs no token, no org and no fixture data.

It immediately found ten purl types the API defines and this SDK did not know about, all of which were being flattened to unknown: alpm, chrome, clawhub, edge-extension, firefox-extension, qpkg, socket, swid, vscode, vscode-extension. Those are added here.

Missing values fail. SDK-only values warn rather than fail, since dropping a member would be breaking and the spec omitting one is usually a spec gap. The two enums the spec exposes no named schema for (ScanType, SecurityAction) are reported as uncovered rather than silently skipped.

.github/workflows/api-drift-check.yml runs it. It is workflow_dispatch-only for now, with the weekly schedule commented and a TODO to enable once it has run green by hand a few times. Deliberately not a pull_request trigger: it tests the API, not the diff, and a backend change must never block an unrelated SDK pull request.

Also in here

• Linear IDs removed from two pre-existing test docstrings. Ticket identifiers belong in the pull request description, not in code that outlives the ticket. The GitHub issue reference stays, since that resolves for anyone reading the repo.
• .gitattributes plus a one-time line-ending normalization. Eleven Python files were committed with CRLF, socketdev/__init__.py among them, so any tooling that rewrites one converts it to LF and turns a two-line edit into a whole-file diff. That happened while writing this branch. Isolated in its own commit and reviewable with git diff -w, which shows only .gitattributes — no file content changed.

Verification

• 149 passed, 1 skipped, 84 subtests, including both pre-existing regression tests unmodified
• Drift check exits 0; negative-tested by deleting two purl members, which correctly produced exit 1 naming them
• ruff check clean on all touched files
• Version bumped to 3.6.0: additive members plus a behavior change, no breakage