feat(vex): respect setup state + manual declaration (property 7)

Close the last RED contract pin: VEX now attests a patch only for an ecosystem
that is actually set up — or explicitly declared `manual` — instead of trusting
the whole manifest.

- schema: `SetupConfig` gains a `manual: Vec<String>` array (ecosystem cli_names
  the user applies by hand), serde-default + skip-empty alongside `exclude`.
- setup.rs: new `configured_ecosystems(common)` runs the same on-disk hook-
  presence probes as `setup --check` and returns the set of set-up ecosystems
  (feature-gated per ecosystem). `persist_setup_excludes` now preserves any
  existing `manual` when rewriting.
- vex.rs: `generate_vex` filters `outcome.applied` to
  `configured_ecosystems ∪ setup.manual` (mapping manual names via
  `ecosystem_from_manual_name`), in BOTH verify and `--no-verify` modes, on top
  of the existing --ecosystems + on-disk-verification filters.
- The `vex_omits_patches_for_unconfigured_ecosystem` pin is un-ignored and green
  (an un-set-up pypi patch, not manual, yields no statements / exit 1).
- VEX-suite migration (single point each): `e2e_vex` / `e2e_embedded_vex`
  `write_manifest` helpers now stamp a blanket `setup.manual` so those fixtures
  (which test document GENERATION, not setup state) still attest — all 18 of
  their tests stay green, including verify-mode omission. CLI_CONTRACT property 7
  updated to implemented.

All 5 setup contract-gap pins are now active (0 ignored). Verified: clippy
--features all-eco -D warnings clean; e2e_vex (13) + e2e_embedded_vex (5) +
core lib (933 / 969 with composer) all green.

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

Author: mikolalysenko

crates/socket-patch-cli/CLI_CONTRACT.md

@@ -138,13 +138,15 @@ in particular, are behavior changes that gate a version bump when implemented).
 
 7. **Reflected in VEX.** A patch contributes a `not_affected` statement to the repo's OpenVEX document
    only for ecosystems that are **actually set up** — or explicitly declared **manual** (below). Patches
-   for an ecosystem that is neither set up nor declared manual produce no VEX statement. *(Intended;
-   **not yet implemented** — VEX currently filters by `--ecosystems` and on-disk verification but has no
-   notion of setup state. RED-guarded.)*
-   - **Manual declaration.** Users who run `socket-patch apply` by hand (e.g. in a CI step) can declare
-     an ecosystem or individual hook as `manual`, so VEX still attests its patches even though the
-     auto-install hook is intentionally not wired. Intended home: a sub-property of
-     `.socket/manifest.json`. *(Follow-up work.)*
+   for an ecosystem that is neither set up nor declared manual produce no VEX statement. *(Implemented —
+   `generate_vex` filters `applied` to ecosystems returned by `commands/setup::configured_ecosystems`
+   (on-disk hook presence) ∪ the manifest's `setup.manual`, in addition to the existing `--ecosystems`
+   filter and on-disk verification. Applies in both verify and `--no-verify` modes.)*
+   - **Manual declaration.** Users who run `socket-patch apply` by hand (e.g. in a CI step) declare an
+     ecosystem as `manual` so VEX still attests its patches even though the auto-install hook is
+     intentionally not wired. Home: the `setup.manual` array (a list of ecosystem `cli_name`s — `pypi`,
+     `cargo`, …) in `.socket/manifest.json`. *(Implemented for the read/attest path; a `setup` flag to
+     populate it is a future nicety — today it's hand-authored in the manifest.)*
 
 8. **Graceful, exact remove.** `setup --remove` (optionally per-ecosystem via `--ecosystems`) restores
    the repo to its exact pre-setup state: manifests byte-for-byte, sibling scripts/dependencies

crates/socket-patch-cli/src/commands/setup.rs

@@ -278,14 +278,97 @@ async fn persist_setup_excludes(common: &GlobalArgs, excludes: &[String]) {
     {
         return; // already persisted exactly — don't rewrite
     }
+    // Preserve any existing `manual` declarations (property 7) when rewriting.
+    let manual = existing
+        .as_ref()
+        .and_then(|m| m.setup.as_ref())
+        .map(|s| s.manual.clone())
+        .unwrap_or_default();
     let mut manifest = existing.unwrap_or_else(PatchManifest::new);
-    manifest.setup = Some(SetupConfig { exclude: merged });
+    manifest.setup = Some(SetupConfig {
+        exclude: merged,
+        manual,
+    });
     if let Some(parent) = path.parent() {
         let _ = tokio::fs::create_dir_all(parent).await;
     }
     let _ = write_manifest(&path, &manifest).await;
 }
 
+/// Which ecosystems are **actually set up** at `cwd` — i.e. their auto-repatch
+/// hook is present on disk (the same presence checks `setup --check` runs). VEX
+/// uses this (∪ the manifest's `manual` declarations) to attest patches only for
+/// set-up-or-manual ecosystems (CLI_CONTRACT property 7). Read-only; ignores the
+/// `--ecosystems` filter (it reports real on-disk state).
+pub(crate) async fn configured_ecosystems(
+    common: &GlobalArgs,
+) -> std::collections::HashSet<socket_patch_core::crawlers::Ecosystem> {
+    use socket_patch_core::crawlers::Ecosystem;
+    let mut set = std::collections::HashSet::new();
+
+    // npm: any discovered package.json whose hook scripts are present.
+    let npm = find_package_json_files(&common.cwd).await;
+    for loc in &npm.files {
+        if let Ok(content) = tokio::fs::read_to_string(&loc.path).await {
+            if !is_setup_configured_str(&content).needs_update {
+                set.insert(Ecosystem::Npm);
+                break;
+            }
+        }
+    }
+
+    // pypi: a chosen python manifest carries the `socket-patch[hook]` dep.
+    if let Some(plan) = plan_python(common).await {
+        for (path, _) in &plan.manifests {
+            if let Ok(content) = tokio::fs::read_to_string(path).await {
+                if deps_contain_hook(&content) {
+                    set.insert(Ecosystem::Pypi);
+                    break;
+                }
+            }
+        }
+    }
+
+    // gem: the managed plugin directive is present in the Gemfile.
+    if let Some(project) = gem_setup::discover_bundler_project(&common.cwd).await {
+        if let Ok(content) = tokio::fs::read_to_string(&project.gemfile).await {
+            if gem_setup::is_plugin_directive_present(&content) {
+                set.insert(Ecosystem::Gem);
+            }
+        }
+    }
+
+    #[cfg(feature = "cargo")]
+    if let Some(project) = discover_cargo_project(&common.cwd).await {
+        for member in &project.members {
+            if let Ok(content) = tokio::fs::read_to_string(member).await {
+                if is_guard_dep_present(&content) {
+                    set.insert(Ecosystem::Cargo);
+                    break;
+                }
+            }
+        }
+    }
+
+    #[cfg(feature = "golang")]
+    if let Some(module) = go_setup::discover_go_module(&common.cwd).await {
+        if go_setup::guard_files_present(&module.root).await {
+            set.insert(Ecosystem::Golang);
+        }
+    }
+
+    #[cfg(feature = "composer")]
+    if let Some(project) = composer_setup::discover_composer_project(&common.cwd).await {
+        if let Ok(content) = tokio::fs::read_to_string(&project.composer_json).await {
+            if composer_setup::is_hook_present(&content) {
+                set.insert(Ecosystem::Composer);
+            }
+        }
+    }
+
+    set
+}
+
 // Canonical `--ecosystems` token sets per setup branch (see `eco_in_scope`).
 const ECO_NPM: &[&str] = &["npm"];
 const ECO_PYPI: &[&str] = &["pypi", "python"];

crates/socket-patch-cli/src/commands/vex.rs

@@ -17,7 +17,7 @@ use std::collections::HashMap;
 use std::path::{Path, PathBuf};
 
 use clap::Args;
-use socket_patch_core::crawlers::CrawlerOptions;
+use socket_patch_core::crawlers::{CrawlerOptions, Ecosystem};
 use socket_patch_core::manifest::operations::read_manifest;
 use socket_patch_core::manifest::schema::PatchManifest;
 use socket_patch_core::utils::telemetry::{track_vex_failed, track_vex_generated};
@@ -246,6 +246,26 @@ pub async fn run(args: VexArgs) -> i32 {
 /// telemetry. Returns a [`VexWriteSummary`] on success or a structured
 /// [`VexGenError`] (with a stable code) on failure. All `track_vex_*`
 /// telemetry is fired here so every caller reports consistently.
+/// Map a `setup.manual` entry to an `Ecosystem`. Accepts the canonical
+/// `cli_name` plus the friendly aliases `setup --exclude`/`--ecosystems` accept
+/// (`go`/`golang`, `python`/`pypi`, `ruby`/`gem`, `php`/`composer`). Names for
+/// ecosystems not compiled into this build (or unrecognized) yield `None` and
+/// are ignored.
+fn ecosystem_from_manual_name(name: &str) -> Option<Ecosystem> {
+    match name.to_ascii_lowercase().as_str() {
+        "npm" | "yarn" | "pnpm" | "bun" => Some(Ecosystem::Npm),
+        "pypi" | "python" => Some(Ecosystem::Pypi),
+        "gem" | "ruby" => Some(Ecosystem::Gem),
+        #[cfg(feature = "cargo")]
+        "cargo" | "rust" => Some(Ecosystem::Cargo),
+        #[cfg(feature = "golang")]
+        "golang" | "go" => Some(Ecosystem::Golang),
+        #[cfg(feature = "composer")]
+        "composer" | "php" => Some(Ecosystem::Composer),
+        _ => None,
+    }
+}
+
 pub(crate) async fn generate_vex(
     common: &GlobalArgs,
     params: &VexBuildParams,
@@ -258,7 +278,7 @@ pub(crate) async fn generate_vex(
     };
 
     // Partition manifest into applied / failed.
-    let outcome = if params.no_verify {
+    let mut outcome = if params.no_verify {
         VerifyOutcome {
             applied: manifest.patches.keys().cloned().collect(),
             failed: Vec::new(),
@@ -268,6 +288,31 @@ pub(crate) async fn generate_vex(
         socket_patch_core::vex::applied_patches(manifest, &package_paths).await
     };
 
+    // Property 7: attest a patch only for an ecosystem that is actually set up —
+    // or explicitly declared `manual` in the manifest. Patches for an ecosystem
+    // that is neither are dropped regardless of verification mode (so even
+    // `--no-verify` won't attest an un-set-up ecosystem's patches).
+    let mut allowed = crate::commands::setup::configured_ecosystems(common).await;
+    if let Some(s) = &manifest.setup {
+        for name in &s.manual {
+            if let Some(e) = ecosystem_from_manual_name(name) {
+                allowed.insert(e);
+            }
+        }
+    }
+    let before = outcome.applied.len();
+    outcome.applied.retain(|purl| {
+        Ecosystem::from_purl(purl)
+            .map(|e| allowed.contains(&e))
+            .unwrap_or(false)
+    });
+    if outcome.applied.len() != before && !common.silent && !common.json {
+        eprintln!(
+            "Note: omitting patches for ecosystems that are not set up (and not declared `manual` \
+             in .socket/manifest.json's `setup.manual`) from VEX."
+        );
+    }
+
     if !outcome.failed.is_empty() && !common.silent && !common.json {
         for f in &outcome.failed {
             eprintln!(

crates/socket-patch-cli/tests/e2e_embedded_vex.rs

@@ -17,9 +17,14 @@ use std::process::Command;
 use serde_json::Value;
 use socket_patch_core::hash::git_sha256::compute_git_sha256_from_bytes;
 use socket_patch_core::manifest::schema::{
-    PatchFileInfo, PatchManifest, PatchRecord, VulnerabilityInfo,
+    PatchFileInfo, PatchManifest, PatchRecord, SetupConfig, VulnerabilityInfo,
 };
 
+/// Declare every ecosystem `manual` in fixtures so the property-7 setup-state
+/// filter doesn't drop these patches — these tests exercise embedded-VEX
+/// generation, not setup state.
+const ALL_MANUAL: &[&str] = &["npm", "pypi", "cargo", "golang", "gem", "composer"];
+
 fn binary() -> &'static str {
     env!("CARGO_BIN_EXE_socket-patch")
 }
@@ -53,9 +58,14 @@ fn cli() -> Command {
 fn write_manifest(cwd: &Path, manifest: &PatchManifest) {
     let dir = cwd.join(".socket");
     std::fs::create_dir_all(&dir).unwrap();
+    let mut m = manifest.clone();
+    m.setup = Some(SetupConfig {
+        exclude: Vec::new(),
+        manual: ALL_MANUAL.iter().map(|s| s.to_string()).collect(),
+    });
     std::fs::write(
         dir.join("manifest.json"),
-        serde_json::to_string_pretty(manifest).unwrap(),
+        serde_json::to_string_pretty(&m).unwrap(),
     )
     .unwrap();
 }

crates/socket-patch-cli/tests/e2e_vex.rs

@@ -20,9 +20,15 @@ use std::process::Command;
 use serde_json::Value;
 use socket_patch_core::hash::git_sha256::compute_git_sha256_from_bytes;
 use socket_patch_core::manifest::schema::{
-    PatchFileInfo, PatchManifest, PatchRecord, VulnerabilityInfo,
+    PatchFileInfo, PatchManifest, PatchRecord, SetupConfig, VulnerabilityInfo,
 };
 
+/// Every setup-supported ecosystem, declared `manual` in test fixtures so the
+/// property-7 setup-state filter (`commands/setup::configured_ecosystems`) does
+/// not drop these patches — these tests exercise VEX document GENERATION, not
+/// setup state, so they opt every patch in via the `manual` escape hatch.
+const ALL_MANUAL: &[&str] = &["npm", "pypi", "cargo", "golang", "gem", "composer"];
+
 fn binary() -> &'static str {
     env!("CARGO_BIN_EXE_socket-patch")
 }
@@ -58,9 +64,14 @@ fn cli() -> Command {
 fn write_manifest(cwd: &Path, manifest: &PatchManifest) {
     let dir = cwd.join(".socket");
     std::fs::create_dir_all(&dir).unwrap();
+    let mut m = manifest.clone();
+    m.setup = Some(SetupConfig {
+        exclude: Vec::new(),
+        manual: ALL_MANUAL.iter().map(|s| s.to_string()).collect(),
+    });
     std::fs::write(
         dir.join("manifest.json"),
-        serde_json::to_string_pretty(manifest).unwrap(),
+        serde_json::to_string_pretty(&m).unwrap(),
     )
     .unwrap();
 }

crates/socket-patch-cli/tests/setup_contract_gaps.rs

@@ -188,17 +188,17 @@ fn setup_check_detects_unapplied_manifest_patch() {
 // has a pypi patch but pypi is NOT set up (no requirements.txt / pyproject hook),
 // so the document must contain zero statements (exit 1, no applicable patches).
 //
-// CURRENTLY RED: VEX has no notion of setup state. With `--no-verify` it trusts
-// the manifest wholesale and emits the statement regardless of whether pypi was
-// ever set up — so it writes a 1-statement document and exits 0.
+// SHIPPED: VEX now filters by setup state — `generate_vex` drops patches whose
+// ecosystem is neither set up (`commands/setup::configured_ecosystems`) nor
+// declared `manual` in the manifest's `setup.manual`. With pypi un-set-up and
+// not manual, the only patch is dropped → no applicable patches → exit 1. This
+// pin is now an active (non-ignored) regression guard.
 //
-// (The converse — declaring pypi `manual` to re-include it — is follow-up work;
-// see the `#[ignore]`d placeholder below.)
+// (The converse — declaring pypi `manual` to re-include it — is exercised by the
+// `manual` escape hatch the e2e_vex / e2e_embedded_vex fixtures rely on.)
 // ===========================================================================
 
 #[test]
-// Gap pin (non-blocking, runnable via --ignored). Un-ignore when property 7 ships.
-#[ignore = "gap: VEX has no notion of setup state; see CLI_CONTRACT 'Setup command contract' property 7"]
 fn vex_omits_patches_for_unconfigured_ecosystem() {
     let proj = tempfile::tempdir().unwrap();
     let home = tempfile::tempdir().unwrap();

crates/socket-patch-core/src/manifest/schema.rs

@@ -44,12 +44,17 @@ pub struct SetupConfig {
     /// needing configuration.
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub exclude: Vec<String>,
+    /// Ecosystems (by `Ecosystem::cli_name`, e.g. `"pypi"`) the user runs
+    /// `socket-patch apply` for by hand, so their patches are still attested in
+    /// VEX even though no auto-install hook is wired (CLI_CONTRACT property 7).
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub manual: Vec<String>,
 }
 
 impl SetupConfig {
     /// Whether this carries no setup state (so the manifest can omit the key).
     pub fn is_empty(&self) -> bool {
-        self.exclude.is_empty()
+        self.exclude.is_empty() && self.manual.is_empty()
     }
 }