Make every API-sourced enum forward-compatible, and detect drift proactively (#107)

* feat(enums): make every API-sourced enum forward-compatible

Five of the six enums populated from API responses coerced strictly, so a
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 fired, leaving the rest holding the same landmine.

All five now fall back to a documented member and log the unrecognized value.
The fallbacks are chosen rather than convenient: SocketIssueSeverity and
DiffType gain an explicit UNKNOWN, since guessing an existing level would
either hide a real finding or invent one, and SecurityAction defers.

A generalized test discovers every enum in the package, including ones added
later, and fails if any raises. A drift check compares the enums against the
public OpenAPI spec; it found 10 purl types the SDK was missing, which are
added here.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* docs: drop Linear IDs from test docstrings and comments

Ticket identifiers belong in the pull request description, not in code that
outlives the ticket. The GitHub issue reference in the purl test docstring
stays, since that resolves for anyone reading the repository.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* chore: add .gitattributes and normalize line endings to LF

Eleven Python files were committed with CRLF, socketdev/__init__.py among them.
Any tooling that reads and rewrites one of those files converts it to LF on the
way out, so a two-line edit arrives as a whole-file diff with the real change
buried in it. That happened while writing the enum change in this same branch.

This normalizes all of them once and pins the setting so it cannot recur.
Reviewable with `git diff -w`, which shows only .gitattributes: no file content
changed, and the unit suite is unaffected.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* fix(enums): keep ScanType strict, it only ever builds requests

ScanType never parses an API response. FullScanParams.to_dict() is urlencoded
onto the create-scan query string, so giving it a _missing_ fallback meant a
caller typo silently shipped scan_type=unknown to the API instead of failing at
construction. The same from_dict already passes integration_type through
uncoerced for that reason.

It is now recorded in REQUEST_ONLY_ENUMS, the opt-out the invariant test always
had and this branch had left empty, and a new test asserts request-only enums
keep raising so the exemption cannot quietly become a skip.

Also bumps actions/setup-python in the new workflow to v7.0.0, matching the pin
already used by .github/actions/setup-sfw.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: lelia

.gitattributes

@@ -0,0 +1,29 @@
+# Normalize line endings to LF in the repository.
+#
+# Eleven Python files were committed with CRLF, socketdev/__init__.py among
+# them. Any tooling that reads and rewrites one of those files converts it to
+# LF on the way out, which turns a two-line change into a whole-file diff and
+# buries the actual edit. Normalizing once and pinning the setting here stops
+# that from recurring.
+* text=auto
+
+*.py text eol=lf
+*.pyi text eol=lf
+*.md text eol=lf
+*.rst text eol=lf
+*.toml text eol=lf
+*.cfg text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+*.json text eol=lf
+*.sh text eol=lf
+*.lock text eol=lf
+
+# Byte-exact, never line-ending-normalized.
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.whl binary
+*.gz binary

.github/workflows/api-drift-check.yml

@@ -0,0 +1,37 @@
+name: API Drift Check
+
+# Compares this SDK's hand-maintained enums against the live Socket OpenAPI
+# spec. The spec is public and unauthenticated, so this job needs no secrets,
+# no org and no fixture data.
+#
+# 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.
+#
+# TODO: once this has run green manually a few times, uncomment the schedule
+# below to turn it into an early-warning signal instead of a manual check.
+on:
+  workflow_dispatch:
+  # schedule:
+  #   - cron: '0 14 * * 1'  # Mondays, 14:00 UTC
+
+permissions:
+  contents: read
+
+jobs:
+  enum-drift:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 1
+          persist-credentials: false
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+
+      - name: Install the SDK
+        run: python -m pip install .
+
+      - name: Compare SDK enums against the live OpenAPI spec
+        run: python scripts/check_api_enum_drift.py

CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 3.6.0
+
+### Changed: every API-sourced enum now tolerates unknown values
+
+- `SocketIssueSeverity`, `SocketCategory`, `DiffType` and `SecurityAction`
+  now fall back to a documented member instead of raising
+  `ValueError` when the API sends a value this release does not know about.
+  `SocketPURL_Type` already behaved this way; the others did not, so each was
+  one backend addition away from emptying a response the same way issue #78 and
+  the unknown `generic` purl type did. `ScanType` is deliberately left strict:
+  it is only ever urlencoded onto the create-scan request, so an unrecognized
+  value is a caller typo rather than API drift.
+- Fallbacks are deliberate rather than convenient. `SocketIssueSeverity` and
+  `DiffType` gained an explicit `UNKNOWN` member because guessing an existing
+  level would either hide a real finding or invent one, and `SecurityAction`
+  falls back to `DEFER` because that already means "use the configured
+  default". Every fallback logs a warning naming the unrecognized value.
+- Added the 10 purl types the API defines that this SDK was missing: `alpm`,
+  `chrome`, `clawhub`, `edge-extension`, `firefox-extension`, `qpkg`, `socket`,
+  `swid`, `vscode` and `vscode-extension`. Artifacts with those types were
+  being flattened to `unknown`.
+
+### Added: enum forward-compatibility is now an enforced invariant
+
+- `tests/unit/test_enum_forward_compat.py` discovers every enum in the package,
+  including ones added later, and fails if any raises on an unrecognized value.
+  The two prior incidents were each fixed with a bespoke test on the single
+  enum that happened to fire; this replaces that pattern.
+
+### Added: scheduled check for enum drift against the live API
+
+- `scripts/check_api_enum_drift.py` compares the SDK's enums against
+  `https://api.socket.dev/v0/openapi`. The spec is public, so the check needs no
+  token, org or fixture data. Run by `.github/workflows/api-drift-check.yml`,
+  which is manual-dispatch only for now and is not a pull request check --- it
+  tests the API rather than the diff.
+
 ## 3.5.0
 
 ### Changed: bound runtime dependency ranges and pin build backend