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

.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