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>

Author: lelia

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

@@ -26,7 +26,7 @@ jobs:
           fetch-depth: 1
           persist-credentials: false
 
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.12"
 

CHANGELOG.md

@@ -4,12 +4,14 @@
 
 ### Changed: every API-sourced enum now tolerates unknown values
 
-- `SocketIssueSeverity`, `SocketCategory`, `DiffType`, `ScanType` and
-  `SecurityAction` now fall back to a documented member instead of raising
+- `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 other five 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.
+  `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`

scripts/check_api_enum_drift.py

@@ -43,10 +43,14 @@
     SocketIssueSeverity: "SocketIssueSeverity",
     SocketCategory: "SocketCategory",
     DiffType: "SocketDiffArtifactType",
-    ScanType: None,
     SecurityAction: None,
 }
 
+# Enums the SDK only ever sends, never parses. Drift in the API's copy cannot
+# break parsing here, and these are intentionally strict so a caller typo fails
+# at construction, so they are out of scope for this check rather than a gap.
+REQUEST_ONLY = (ScanType,)
+
 # Members this SDK adds deliberately, which the API will never send. They are
 # the documented _missing_ fallbacks (see socketdev/core/enums.py), so their
 # absence from the spec is expected rather than drift.
@@ -122,6 +126,11 @@ def main():
             f"named schema for them: {', '.join(sorted(unmapped))}"
         )
 
+    print(
+        f"not applicable (request-only, intentionally strict): "
+        f"{', '.join(sorted(e.__name__ for e in REQUEST_ONLY))}"
+    )
+
     if drifted:
         print(
             "\nAdd the missing members to the SDK enum. Existing values are "

socketdev/fullscans/__init__.py

@@ -102,14 +102,14 @@ def _missing_(cls, value):
 
 
 class ScanType(str, Enum):
+    # Deliberately strict, unlike the response-parsed enums in this module.
+    # ScanType only ever travels outbound: FullScanParams.to_dict() is
+    # urlencoded onto the create-scan query string, so an unrecognized value is
+    # the caller's typo, not API drift. Coercing it to a fallback would send
+    # scan_type=unknown to the API instead of failing at construction.
     SOCKET = "socket"
     SOCKET_TIER1 = "socket_tier1"
     SOCKET_BASICS = "socket_basics"
-    UNKNOWN = "unknown"
-
-    @classmethod
-    def _missing_(cls, value):
-        return unknown_enum_value(cls.__name__, value, cls.UNKNOWN)
 
 
 @dataclass(kw_only=True)

tests/unit/test_enum_forward_compat.py

@@ -25,7 +25,15 @@
 # Strictness is correct there: a bad value is the caller's typo and should raise
 # rather than be silently coerced. Add an entry only with a comment justifying
 # that the enum never sees API-supplied values.
-REQUEST_ONLY_ENUMS = frozenset()
+REQUEST_ONLY_ENUMS = frozenset(
+    {
+        # Only ever travels outbound: FullScanParams.to_dict() is urlencoded
+        # onto the create-scan query string. It never parses an API response, so
+        # an unrecognized value is a caller typo that should surface at
+        # construction rather than reach the API as scan_type=unknown.
+        "ScanType",
+    }
+)
 
 # A value the API will never legitimately send.
 SENTINEL = "__value_the_api_would_never_send__"
@@ -98,6 +106,24 @@ def test_unknown_value_warns(self):
                     f"got: {captured.output}",
                 )
 
+    def test_request_only_enums_stay_strict(self):
+        # The opt-out is not a "skip this one" marker: these enums must actively
+        # keep raising. Coercing a caller's typo to a fallback would send the
+        # fallback to the API instead of failing at construction, which is how
+        # the forward-compat change first got ScanType wrong.
+        by_name = {cls.__name__: cls for cls in _all_enums().values()}
+        for name in sorted(REQUEST_ONLY_ENUMS):
+            with self.subTest(enum=name):
+                enum_cls = by_name.get(name)
+                self.assertIsNotNone(
+                    enum_cls, f"{name} is exempted but no longer exists"
+                )
+                with self.assertRaises(
+                    ValueError,
+                    msg=f"{name} is request-only and must reject unknown values",
+                ):
+                    enum_cls(SENTINEL)
+
     def test_known_values_still_round_trip(self):
         # Forward-compat must not swallow legitimate values.
         for qualname, enum_cls in sorted(_all_enums().items()):