refactor: fix documentation, drop additional env variables in source-only mode

Signed-off-by: Brandon Luo <br32710@ll.mit.edu>

Author: br32710

docs/config/target-project.md

@@ -58,8 +58,8 @@ uv run oss-crs run \
 
 Source-only runs omit `--fuzz-proj-path` entirely. The source path is
 directly bind-mounted to `OSS_CRS_TARGET_SOURCE`. There is no build step,
-no `OSS_CRS_FUZZ_PROJ` mount, and `SANITIZER`, `ARCHITECTURE`, and
-`FUZZING_LANGUAGE` are not injected into source-only containers.
+no `OSS_CRS_FUZZ_PROJ` mount, and `SANITIZER`, `ARCHITECTURE`,
+`FUZZING_LANGUAGE`, etc. not injected into source-only containers.
 
 ## Arguments
 
@@ -70,9 +70,8 @@ no `OSS_CRS_FUZZ_PROJ` mount, and `SANITIZER`, `ARCHITECTURE`, and
 | `--target-harness` | Yes (run) | Fuzz target harness binary name. |
 
 At least one of `--fuzz-proj-path` or `--target-source-path` is required.
-If `--fuzz-proj-path` is specified, `--target-harness` is required.
 
-Existing [OSS-Fuzz projects](https://github.com/google.com/oss-fuzz/tree/master/projects) can be used directly as `--fuzz-proj-path` without modification.
+Existing [OSS-Fuzz projects](https://github.com/google/oss-fuzz/tree/master/projects) can be used directly as `--fuzz-proj-path` without modification.
 
 ## Source Path Semantics
 
@@ -91,7 +90,8 @@ Instead, during image build:
 
 For source-only runs, `--target-source-path` is directly bind-mounted to
 `OSS_CRS_TARGET_SOURCE`. There is no image build, no `OSS_CRS_FUZZ_PROJ`
-mount, and no `SANITIZER`, `ARCHITECTURE`, or `FUZZING_LANGUAGE` injection.
+mount, and environment variables like `SANITIZER`, `ARCHITECTURE`, `FUZZING_LANGUAGE`,
+etc. are not injected.
 
 ### Common Semantics
 

docs/crs-development-guide.md

@@ -801,7 +801,7 @@ Your CRS should submit findings through libCRS:
 
 ### Source-Level Bug Finding Without A Harness
 
-Source-only runs are invoked without `--fuzz-proj-path` and instead use `--target-source-path` to point at the source tree. They skip OSS-Fuzz target image builds and require every run module to set `target_dependent: false`; run `oss-crs prepare` first to build those target-independent images. They do not mount `OSS_CRS_BUILD_OUT_DIR` or `OSS_CRS_FUZZ_PROJ`, but still receive `OSS_CRS_SUBMIT_DIR`, `OSS_CRS_FETCH_DIR`, `OSS_CRS_SHARED_DIR`, `OSS_CRS_LOG_DIR`, and `OSS_CRS_TARGET_SOURCE`. They do not receive `OSS_CRS_TARGET_HARNESS`, `SANITIZER`, `ARCHITECTURE`, or `FUZZING_LANGUAGE`.
+Source-only runs are invoked without `--fuzz-proj-path` and instead use `--target-source-path` to point at the source tree. They skip OSS-Fuzz target image builds and require every run module to set `target_dependent: false`; run `oss-crs prepare` first to build those target-independent images. They do not mount `OSS_CRS_BUILD_OUT_DIR` or `OSS_CRS_FUZZ_PROJ`, but still receive `OSS_CRS_SUBMIT_DIR`, `OSS_CRS_FETCH_DIR`, `OSS_CRS_SHARED_DIR`, `OSS_CRS_LOG_DIR`, and `OSS_CRS_TARGET_SOURCE`. They do not receive `OSS_CRS_TARGET_HARNESS`, `SANITIZER`, `ARCHITECTURE`, `FUZZING_LANGUAGE`, `FUZZING_ENGINE`, `HELPER`, or `RUN_FUZZER_MODE`, since none of these are consumed by source-level analysis.
 
 Source-only runs require all CRSs to be of type `auditing`. This ensures that only CRSs designed to analyze source code without a compiled target can run in source-only mode. An `auditing` CRS is a regular producer that reads `OSS_CRS_TARGET_SOURCE` and submits `bug-candidate` artifacts. The type is a capability label rather than a source-only restriction: auditors may run alone without `--target-harness` or alongside harness-based CRSs.
 

oss_crs/src/cli/crs_compose.py

@@ -626,6 +626,14 @@ def add_gen_compose_command(subparsers):
     )
 
 
+def _resolve_source_only(args, crs_compose) -> bool:
+    """Source-only iff no --target-harness, no --fuzz-proj-path, and the
+    composition contains no harness-generation CRSs."""
+    if args.target_harness is not None or args.target_proj_path is not None:
+        return False
+    return not any(crs.config.is_harness_gen for crs in crs_compose.crs_list)
+
+
 def init_target_from_args(
     args, *, source_only: bool = False, require_source_dir: bool = False
 ) -> Target:
@@ -951,12 +959,7 @@ def cli() -> bool | int:
         ):
             return False
     elif args.command == "run":
-        harness_gen = any(crs.config.is_harness_gen for crs in crs_compose.crs_list)
-        source_only = (
-            args.target_harness is None
-            and args.target_proj_path is None
-            and not harness_gen
-        )
+        source_only = _resolve_source_only(args, crs_compose)
         try:
             target = init_target_from_args(
                 args, source_only=source_only, require_source_dir=source_only
@@ -1010,14 +1013,7 @@ def cli() -> bool | int:
         if run_rc != 0:
             return run_rc
     elif args.command == "artifacts":
-        harness_gen = args.target_harness is None and any(
-            crs.config.is_harness_gen for crs in crs_compose.crs_list
-        )
-        source_only = (
-            args.target_harness is None
-            and args.target_proj_path is None
-            and not harness_gen
-        )
+        source_only = _resolve_source_only(args, crs_compose)
         try:
             target = init_target_from_args(args, source_only=source_only)
         except ValueError as exc:
@@ -1031,14 +1027,7 @@ def cli() -> bool | int:
             unharnessed=args.target_harness is None,
         )
     elif args.command == "archive":
-        harness_gen = args.target_harness is None and any(
-            crs.config.is_harness_gen for crs in crs_compose.crs_list
-        )
-        source_only = (
-            args.target_harness is None
-            and args.target_proj_path is None
-            and not harness_gen
-        )
+        source_only = _resolve_source_only(args, crs_compose)
         try:
             target = init_target_from_args(args, source_only=source_only)
         except ValueError as exc:

oss_crs/src/env_policy.py

@@ -177,18 +177,19 @@ def build_run_service_env(
     llm_api_url: str | None = None,
     llm_api_key: str | None = None,
 ) -> EnvPlan:
-    base_env = {
-        "HELPER": "True",
-        "RUN_FUZZER_MODE": "interactive",
-        **{
-            k: target_env[v]
-            for k, v in OSS_FUZZ_TARGET_ENV.items()
-            if k != "SANITIZER"
-            and not (source_only and k == "FUZZING_LANGUAGE")
-            and not (source_only and k == "ARCHITECTURE")
-        },
-    }
+    base_env = {}
     if not source_only:
+        base_env["HELPER"] = "True"
+        base_env["RUN_FUZZER_MODE"] = "interactive"
+        # SANITIZER is excluded: its value always comes from the resolved
+        # sanitizer argument below, never from target_env.
+        base_env.update(
+            {
+                k: target_env[v]
+                for k, v in OSS_FUZZ_TARGET_ENV.items()
+                if k != "SANITIZER"
+            }
+        )
         base_env["SANITIZER"] = sanitizer
     base_env["PROJECT_NAME"] = target_env["name"]
     # Preserve existing behavior: module env first, CRS env last.

oss_crs/tests/unit/test_env_policy.py

@@ -172,9 +172,41 @@ def test_source_only_run_env_omits_build_and_fuzz_env() -> None:
     assert "OSS_CRS_PROJ_PATH" not in plan.effective_env
     assert "SANITIZER" not in plan.effective_env
     assert "ARCHITECTURE" not in plan.effective_env
+    assert "FUZZING_ENGINE" not in plan.effective_env
+    assert "HELPER" not in plan.effective_env
+    assert "RUN_FUZZER_MODE" not in plan.effective_env
     assert plan.effective_env["OSS_CRS_REPO_PATH"] == "/OSS_CRS_TARGET_SOURCE"
 
 
+def test_harnessed_run_env_includes_oss_fuzz_runtime_vars() -> None:
+    """Harnessed runs keep HELPER, RUN_FUZZER_MODE, and all target env vars."""
+    plan = build_run_service_env(
+        target_env={
+            "engine": "libfuzzer",
+            "architecture": "x86_64",
+            "name": "proj",
+            "language": "c",
+            "repo_path": "/repo",
+        },
+        sanitizer="address",
+        run_env_type="local",
+        crs_name="crs-a",
+        module_name="patcher",
+        run_id="r1",
+        cpuset="0-1",
+        memory_limit="2G",
+        module_additional_env=None,
+        crs_additional_env=None,
+        scope="test:harnessed-run",
+    )
+    assert plan.effective_env["HELPER"] == "True"
+    assert plan.effective_env["RUN_FUZZER_MODE"] == "interactive"
+    assert plan.effective_env["FUZZING_ENGINE"] == "libfuzzer"
+    assert plan.effective_env["SANITIZER"] == "address"
+    assert plan.effective_env["ARCHITECTURE"] == "x86_64"
+    assert plan.effective_env["FUZZING_LANGUAGE"] == "c"
+
+
 def test_user_cannot_override_reserved_source_env_vars() -> None:
     """User-provided OSS_CRS_FUZZ_PROJ and OSS_CRS_TARGET_SOURCE are superseded by system values."""
     plan = build_target_builder_env(

oss_crs/tests/unit/test_source_only_run.py

@@ -3,7 +3,7 @@
 
 import yaml
 
-from oss_crs.src.cli.crs_compose import init_target_from_args
+from oss_crs.src.cli.crs_compose import _resolve_source_only, init_target_from_args
 from oss_crs.src.crs_compose import CRSCompose
 from oss_crs.src.config.crs import CRSType
 from oss_crs.src.templates.renderer import render_run_crs_compose_docker_compose
@@ -254,11 +254,32 @@ def test_source_only_rejects_non_auditing_crs() -> None:
     assert "auditing" in result.error
 
 
-def test_harness_gen_without_harness_is_not_source_only() -> None:
-    target = SimpleNamespace(target_harness=None, source_only=False)
-    compose = CRSCompose.__new__(CRSCompose)
-    compose.crs_list = [
-        SimpleNamespace(config=SimpleNamespace(is_harness_gen=True)),
-    ]
+def _source_mode_args(**overrides) -> SimpleNamespace:
+    defaults: dict = {"target_harness": None, "target_proj_path": None}
+    defaults.update(overrides)
+    return SimpleNamespace(**defaults)
+
+
+def _compose_with(crs_types: list[str]) -> SimpleNamespace:
+    return SimpleNamespace(
+        crs_list=[
+            SimpleNamespace(config=SimpleNamespace(is_harness_gen=t == "harness-gen"))
+            for t in crs_types
+        ]
+    )
 
-    assert compose.is_source_only_run(target) is False
+
+def test_resolve_source_only_classification_matrix() -> None:
+    auditing = _compose_with(["auditing"])
+    harness_gen = _compose_with(["harness-gen"])
+
+    assert _resolve_source_only(_source_mode_args(), auditing) is True
+    assert _resolve_source_only(_source_mode_args(), harness_gen) is False
+    assert (
+        _resolve_source_only(_source_mode_args(target_harness="fuzz_target"), auditing)
+        is False
+    )
+    assert (
+        _resolve_source_only(_source_mode_args(target_proj_path="proj"), auditing)
+        is False
+    )