Make every API-sourced enum forward-compatible, and detect drift proactively

[lelia]

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:

Enum	Fallback	Why not something else
SocketIssueSeverity	new UNKNOWN	LOW hides a serious finding, CRITICAL manufactures one
DiffType	new UNKNOWN	UNCHANGED would silently drop a real diff entry
ScanType	new UNKNOWN	no safe existing default
SocketCategory	MISCELLANEOUS	matches the existing convention
SecurityAction	DEFER	already means "use the configured default"; IGNORE disables a rule, ERROR fails builds

Worth a second opinion: SecurityAction

DEFER is inferred from the action descriptions in the OpenAPI spec rather than from backend code. If defer does not mean "fall through to the org default" in every context this enum is parsed from, a new UNKNOWN sentinel would be the safer choice.

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

---

Note

Medium Risk
Changes how unknown severities, diff types, categories, and security actions are represented at parse time (fallbacks instead of errors), which affects downstream reporting and policy behavior until the SDK is updated.

Overview
3.6.0 hardens the SDK against API enum drift so a single unknown value no longer fails entire scan/diff parses (the failure mode behind issue #78 and unknown purl types).

Response-parsed enums (SocketIssueSeverity, SocketCategory, DiffType, SecurityAction, and SocketPURL_Type) now use shared _missing_ handling via socketdev/core/enums.py: log a warning and return a documented fallback (UNKNOWN for severity/diff, MISCELLANEOUS for category, DEFER for security actions, UNKNOWN for purl types). ScanType stays strict because it is only sent on create-scan requests. Ten missing SocketPURL_Type members from the live API are added so those artifacts are no longer coerced to unknown. SocketAlert.from_dict drops its bespoke category try/except in favor of enum _missing_.

Guardrails: tests/unit/test_enum_forward_compat.py discovers all package enums and enforces tolerant parsing (with an explicit request-only opt-out for ScanType). scripts/check_api_enum_drift.py compares enums to the public OpenAPI spec; .github/workflows/api-drift-check.yml runs it on manual dispatch only (not on PRs). .gitattributes pins LF line endings to stop CRLF-only noise in future diffs. Version bumped to 3.6.0 with changelog updates.

^{Reviewed by Cursor Bugbot for commit 2d72644. Configure here.}

[lelia]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 2d72644. Configure here.}