Merge main into the ruff/QoL branch and move the release to 2.8.1

main shipped 2.8.0 (#325 monorepo scan diagnostics and API exit codes, #331
Slack severity normalization and the socketdev 3.6.0 bump) while this branch
was open, so the 2.7.3 it targeted is now behind the published release.

Conflict resolution, in every case keeping main's shipped behaviour and this
branch's formatting and fixes:

- slack.py: kept the "middle" -> "medium" normalization from #331, restyled to
  double quotes. Losing it would have silently reintroduced the wrong Slack
  severity counts.
- socketcli.py: kept #325's _log_scan_mode_fallback diagnostics and the
  force_api_mode branch; this branch's side was the older logic reformatted.
- core/__init__.py: kept #325's _log_scan_configuration helper and its call
  sites, and the switch from sys.exit to raise so API failures reach the
  configured infrastructure exit code. Kept this branch's contextlib.suppress
  cleanup and modern annotations, and modernized the helper's own signature
  since this branch drops the typing.List/Optional imports.
- version-check.yml: already assembled from main plus the enforcement gating
  and this branch's both-quote version strip.
- CHANGELOG: this branch's section is now 2.8.1, above the shipped 2.8.0.

uv.lock regenerated from the merged pyproject with the pinned uv 0.12.8.
ruff check and ruff format are both clean; 584 passed, 2 skipped.

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

Author: lelia

CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## 2.7.3
+## 2.8.1
 
 ### Fixed: credentials could appear in debug log output
 
@@ -56,6 +56,40 @@
 - `config.py` logged through the root logger, so its warnings and errors ignored
   the configured log level and format. They now use the `socketcli` logger like
   the rest of the CLI.
+## 2.8.0
+
+### Changed: improve monorepo scan diagnostics and guidance
+
+- Added aggregate scan configuration, manifest-count, baseline-selection, and
+  fallback diagnostics without listing submitted manifest paths.
+- Clarified monorepo scan scoping, workspace flags, CI path filters, and timeout
+  behavior, with a changed-workspace GitHub Actions example.
+
+### Changed: bump socketdev to 3.6.0
+
+- Bumped the pinned SDK (`socketdev`) from `3.5.0` to `3.6.0`. Its package-type
+  enum gained ten members — `alpm`, `chrome`, `clawhub`, `edge-extension`,
+  `firefox-extension`, `qpkg`, `socket`, `swid`, `vscode` and
+  `vscode-extension` — so artifacts of those types are now reported under their
+  own type instead of falling back to `unknown`.
+
+### Fixed: apply configured exit codes to API failures
+
+- Full-scan and streamed-diff API failures now use the configured infrastructure
+  error exit code instead of the security-finding exit code.
+
+### Fixed: mid-severity findings were dropped from the Slack summary
+
+- The Slack reachability formatter keyed every severity lookup on `medium`,
+  but the API sends `middle`. A mid-severity finding therefore missed all of
+  them at once: it was not counted, so the summary always read `Medium: 0`; it
+  was excluded from `total_findings`, which can drive the "and N more" count
+  negative; and it sorted at the default order of 4, below `low`, so it was the
+  first thing truncated when the Slack block limit was reached.
+- Severity is now normalized to one spelling when an alert is read, matching
+  how the GitLab and PR-comment paths already handle both forms. The findings
+  themselves were always listed; only the counts, ordering and truncation were
+  wrong.
 
 ## 2.7.2
 

README.md

@@ -229,6 +229,10 @@ value — e.g. a Buildkite
 code, or `0` to swallow infra errors. Exit `3` is a Socket convention, not an
 industry standard.
 
+This mapping applies to errors the CLI receives and handles. An external process
+supervisor (for example GNU `timeout`) can terminate the CLI before it handles an
+error, so the supervisor's exit status (commonly 124 or 137) takes precedence.
+
 ### How these options interact
 
 The two flags that affect exit codes can cancel each other out, so the order of

docs/ci-cd.md

@@ -71,6 +71,239 @@ Equivalent JSON:
     SOCKET_SECURITY_API_TOKEN: ${{ secrets.SOCKET_SECURITY_API_TOKEN }}
 ```
 
+#### GitHub Actions: scan changed monorepo workspaces independently
+
+GitHub Actions `paths` filters only decide whether a workflow starts. They do not
+change `socketcli` discovery or upload scope. For a merge gate, it is usually safer
+to start a small selector job on every PR update, then create one scan job per
+affected logical workspace. This also avoids a required check remaining pending
+when GitHub skips the entire workflow because of a top-level path filter.
+
+This pattern produces one dashboard entry per logical workspace, which is what
+gives each component its own alerts, baseline, and policy. It is also the layout
+that grows the dashboard's repository list. See
+[Choosing a scan layout](cli-reference.md#choosing-a-scan-layout) for when that
+trade-off is worth making.
+
+Define a repository variable named `SOCKET_MONOREPO_WORKSPACES_JSON`. Its value is
+an array with one stable workspace name, one or more scan roots, and the path globs
+that should select that workspace. Fill these placeholders with the repository's
+real layout. A workspace definition selects directory roots; shared root manifests,
+lockfiles, and cross-directory path dependencies outside those roots are not included
+automatically.
+
+```json
+[
+  {
+    "name": "<stable-workspace-name>",
+    "sub_paths": ["<repo-relative-scan-root>"],
+    "watch_globs": ["<repo-relative-changed-file-glob>"]
+  }
+]
+```
+
+Each `sub_paths` value must be a directory, not an individual manifest or lockfile.
+Using `.` includes the entire target path. Do not use this changed-workspace pattern
+until the directory boundaries preserve every shared input needed to resolve each
+logical graph. If root workspace metadata governs most or all of the repository, a
+smaller coverage-preserving split may not be representable with `--sub-path` alone.
+
+Also define `SOCKETCLI_VERSION` as the exact package version validated for the
+workflow. The workflow below logs that version, uses full Git history for reliable
+base/head selection, creates one matrix job (and therefore one graph and baseline)
+per selected workspace, and fails closed on CLI/API/timeout failures. It uses API
+SCM mode plus `--enable-diff` because parallel `--scm github` jobs can race while
+updating the same PR comments; the matrix checks and report links are the gate.
+
+```yaml
+name: Socket Security
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  select-workspaces:
+    runs-on: ubuntu-latest
+    outputs:
+      count: ${{ steps.select.outputs.count }}
+      matrix: ${{ steps.select.outputs.matrix }}
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - id: select
+        name: Select changed workspaces
+        env:
+          WORKSPACES_JSON: ${{ vars.SOCKET_MONOREPO_WORKSPACES_JSON }}
+          BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+        shell: bash
+        run: |
+          python - <<'PY'
+          import fnmatch
+          import json
+          import os
+          import re
+          import subprocess
+
+          workspaces = json.loads(os.environ["WORKSPACES_JSON"])
+          if not isinstance(workspaces, list):
+              raise SystemExit("SOCKET_MONOREPO_WORKSPACES_JSON must be a JSON array")
+
+          base = os.environ["BASE_SHA"]
+          head = os.environ["HEAD_SHA"]
+          if not base or set(base) == {"0"}:
+              base = subprocess.check_output(
+                  ["git", "rev-parse", f"{head}^"], text=True
+              ).strip()
+          changed_output = subprocess.check_output(
+              ["git", "diff", "--name-only", "-z", base, head]
+          )
+          changed = [
+              item.decode("utf-8", "surrogateescape")
+              for item in changed_output.split(b"\0")
+              if item
+          ]
+
+          selected = []
+          for workspace in workspaces:
+              name = workspace.get("name", "")
+              sub_paths = workspace.get("sub_paths") or []
+              watch_globs = workspace.get("watch_globs") or []
+              if not re.fullmatch(r"[A-Za-z0-9._-]+", name):
+                  raise SystemExit(f"Invalid workspace name: {name!r}")
+              if not sub_paths or any(
+                  not isinstance(path, str)
+                  or path.startswith("/")
+                  or ".." in path.split("/")
+                  for path in sub_paths
+              ):
+                  raise SystemExit(f"Invalid sub_paths for workspace {name!r}")
+              if not watch_globs:
+                  watch_globs = [
+                      pattern
+                      for path in sub_paths
+                      for pattern in (
+                          ["*"]
+                          if path.strip("/") in ("", ".")
+                          else [path.rstrip("/"), f"{path.rstrip('/')}/*"]
+                      )
+                  ]
+              if any(
+                  fnmatch.fnmatchcase(path, pattern)
+                  for path in changed
+                  for pattern in watch_globs
+              ):
+                  selected.append({"name": name, "sub_paths": sub_paths})
+
+          matrix = json.dumps({"include": selected}, separators=(",", ":"))
+          with open(os.environ["GITHUB_OUTPUT"], "a", encoding="utf-8") as output:
+              output.write(f"count={len(selected)}\n")
+              output.write(f"matrix={matrix}\n")
+          PY
+
+  scan-workspace:
+    needs: select-workspaces
+    if: needs.select-workspaces.outputs.count != '0'
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJSON(needs.select-workspaces.outputs.matrix) }}
+    name: Socket scan (${{ matrix.name }})
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+
+      - name: Install pinned Socket CLI
+        env:
+          SOCKETCLI_VERSION: ${{ vars.SOCKETCLI_VERSION }}
+        run: |
+          python -m pip install "socketsecurity==$SOCKETCLI_VERSION"
+          socketcli --version
+
+      - name: Scan workspace
+        env:
+          SOCKET_SECURITY_API_KEY: ${{ secrets.SOCKET_SECURITY_API_KEY }}
+          PR_NUMBER: ${{ github.event.pull_request.number || 0 }}
+          WORKSPACE_NAME: ${{ matrix.name }}
+          SUB_PATHS_JSON: ${{ toJSON(matrix.sub_paths) }}
+        shell: bash
+        run: |
+          set +e
+          args=(
+            --target-path "$GITHUB_WORKSPACE"
+            --workspace-name "$WORKSPACE_NAME"
+            --enable-diff
+            --pr-number "$PR_NUMBER"
+            --exit-code-on-api-error 3
+            --report-link-file socket-report-link.txt
+            --summary-file socket-summary.txt
+          )
+          while IFS= read -r sub_path; do
+            args+=(--sub-path "$sub_path")
+          done < <(jq -r '.[]' <<<"$SUB_PATHS_JSON")
+
+          socketcli "${args[@]}" 2>&1 | tee socket-output.log
+          code=${PIPESTATUS[0]}
+
+          {
+            echo "## Socket scan: $WORKSPACE_NAME"
+            if [ -s socket-report-link.txt ]; then
+              echo "[View the report]($(cat socket-report-link.txt))"
+            fi
+            if [ -s socket-summary.txt ]; then
+              echo '```'
+              cat socket-summary.txt
+              echo '```'
+            fi
+          } >> "$GITHUB_STEP_SUMMARY"
+
+          exit "$code"
+
+  socket-security:
+    if: always()
+    needs: [select-workspaces, scan-workspace]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Enforce matrix result
+        env:
+          SELECT_RESULT: ${{ needs.select-workspaces.result }}
+          SCAN_RESULT: ${{ needs.scan-workspace.result }}
+        run: |
+          test "$SELECT_RESULT" = success
+          [[ "$SCAN_RESULT" = success || "$SCAN_RESULT" = skipped ]]
+```
+
+Each configuration object may intentionally contain several `sub_paths` when
+those directories are one logical dependency graph. To split backend resolution,
+use separate objects with different `name` values. Add `--workspace <name>` only
+when the Socket organization requires API workspace association; it is not a scan
+scope control. Use `--save-submitted-files-list` in a non-required canary to verify
+the exact manifests selected before adopting workspace-level scans as a merge gate.
+
+The job has an explicit 20-minute total budget. Tune that value from observed
+workspace-level latency after the split; a five-minute cap can still be too close
+to a slow request plus local startup. The CLI's `--timeout` is different: it
+defaults to 1,200 seconds **per API request**. If an operator adds GNU `timeout`,
+that process supervisor can terminate the CLI before it maps an error through
+`--exit-code-on-api-error`; without `--preserve-status`, GNU reports 124 after its
+initial timeout signal or 137 if `SIGKILL` is involved.
+
 ### Buildkite
 
 ```yaml