feat(coverage): add configurable coverage thresholds (#35056)

Teams that gate CI on coverage had no way to make Deno fail when
coverage dropped below a target; `deno coverage` and `deno test --coverage`
always exited zero regardless of the numbers. This was the long-standing ask in
issues #9669 and #29076.

This adds a minimum-coverage threshold that exits non-zero when unmet.
`deno coverage --threshold=<percent>` and `deno test --coverage
--coverage-threshold=<percent>` apply one percentage to line, branch,
and function coverage. For finer control, a `coverage` section in deno.json
sets per-metric thresholds, modelled on Vitest's `coverage.thresholds`:

    {
      "coverage": {
        "thresholds": { "lines": 90, "branches": 80, "functions": 90 }
      }
    }

When the CLI flag is given it applies its single value to all three
metrics, overriding whatever the config sets for each. With no flag, the
per-metric config is honored by both `deno coverage` and `deno test --coverage`.
The check runs against the aggregate across all reported files, and reuses
the same accumulation the summary reporter prints so the checked numbers
match the displayed ones. A metric with no configured threshold is not checked
(e.g. a `branches` threshold passes vacuously for files that have no
branches), and a malformed or out-of-range `coverage` config is a hard
error rather than being silently ignored.

CLI flags take integer percentages in 0-100 (validated by the parser);
the deno.json config accepts fractional values in 0-100 for finer per-metric
targets. Per-file thresholds (Vitest's `perFile`) are not included here
and could be a follow-up.

Closes #9669
Closes #29076

Author: bartlomieju

cli/args/flags.rs

@@ -342,6 +342,9 @@ pub struct CoverageFlags {
   pub include: Vec<String>,
   pub exclude: Vec<String>,
   pub r#type: CoverageType,
+  /// Minimum coverage percentage (0-100) applied to line, branch, and function
+  /// coverage. Overrides per-metric thresholds from `deno.json`.
+  pub threshold: Option<u32>,
 }
 
 #[derive(Clone, Debug, Eq, PartialEq, Default)]
@@ -682,6 +685,9 @@ pub struct TestFlags {
   pub no_run: bool,
   pub coverage_dir: Option<String>,
   pub coverage_raw_data_only: bool,
+  /// Minimum coverage percentage (0-100) required when `--coverage` is set.
+  /// Overrides per-metric thresholds from `deno.json`.
+  pub coverage_threshold: Option<u32>,
   pub clean: bool,
   pub fail_fast: Option<NonZeroUsize>,
   pub files: FileFlags,
@@ -3588,6 +3594,15 @@ Generate html reports from lcov:
           .help("Output coverage report in detailed format in the terminal")
           .action(ArgAction::SetTrue),
       )
+      .arg(
+        Arg::new("threshold")
+          .long("threshold")
+          .value_name("PERCENT")
+          .value_parser(value_parser!(u32).range(0..=100))
+          .require_equals(true)
+          .help(cstr!("Fail if coverage is below this percentage (0-100), applied to line, branch, and function coverage.
+  <p(245)>Per-metric thresholds can be set in deno.json under \"coverage\": { \"thresholds\": { ... } }. The flag takes precedence.</>")),
+      )
       .arg(
         Arg::new("files")
           .num_args(0..)
@@ -5247,6 +5262,16 @@ or <c>**/__tests__/**</>:
           .action(ArgAction::SetTrue)
           .help_heading(TEST_HEADING),
       )
+      .arg(
+        Arg::new("coverage-threshold")
+          .long("coverage-threshold")
+          .value_name("PERCENT")
+          .value_parser(value_parser!(u32).range(0..=100))
+          .require_equals(true)
+          .requires("coverage")
+          .help("Fail if coverage is below this percentage (0-100). Requires --coverage")
+          .help_heading(TEST_HEADING),
+      )
       .arg(
         Arg::new("clean")
           .long("clean")
@@ -7741,6 +7766,7 @@ fn coverage_parse(
     CoverageType::Summary
   };
   let output = matches.remove_one::<String>("output");
+  let threshold = matches.remove_one::<u32>("threshold");
   flags.subcommand = DenoSubcommand::Coverage(CoverageFlags {
     files: FileFlags {
       include: files,
@@ -7750,6 +7776,7 @@ fn coverage_parse(
     include,
     exclude,
     r#type,
+    threshold,
   });
   Ok(())
 }
@@ -8795,6 +8822,7 @@ fn test_parse(
     doc,
     coverage_dir: matches.remove_one::<String>("coverage"),
     coverage_raw_data_only: matches.get_flag("coverage-raw-data-only"),
+    coverage_threshold: matches.remove_one::<u32>("coverage-threshold"),
     clean,
     fail_fast,
     files: FileFlags { include, ignore },
@@ -13229,6 +13257,7 @@ mod tests {
           sanitize_resources: false,
           coverage_dir: Some("cov".to_string()),
           coverage_raw_data_only: false,
+          coverage_threshold: None,
           clean: true,
           watch: Default::default(),
           reporter: Default::default(),
@@ -13341,6 +13370,7 @@ mod tests {
           sanitize_resources: false,
           coverage_dir: None,
           coverage_raw_data_only: false,
+          coverage_threshold: None,
           clean: false,
           watch: Default::default(),
           reporter: Default::default(),
@@ -13390,6 +13420,7 @@ mod tests {
           sanitize_resources: false,
           coverage_dir: None,
           coverage_raw_data_only: false,
+          coverage_threshold: None,
           clean: false,
           watch: Default::default(),
           reporter: Default::default(),
@@ -13533,6 +13564,7 @@ mod tests {
           sanitize_resources: false,
           coverage_dir: None,
           coverage_raw_data_only: false,
+          coverage_threshold: None,
           clean: false,
           watch: Default::default(),
           reporter: Default::default(),
@@ -13575,6 +13607,7 @@ mod tests {
           sanitize_resources: false,
           coverage_dir: None,
           coverage_raw_data_only: false,
+          coverage_threshold: None,
           clean: false,
           watch: Default::default(),
           reporter: Default::default(),
@@ -13636,6 +13669,7 @@ mod tests {
           sanitize_resources: false,
           coverage_dir: None,
           coverage_raw_data_only: false,
+          coverage_threshold: None,
           clean: false,
           watch: Some(Default::default()),
           reporter: Default::default(),
@@ -13677,6 +13711,7 @@ mod tests {
           sanitize_resources: false,
           coverage_dir: None,
           coverage_raw_data_only: false,
+          coverage_threshold: None,
           clean: false,
           watch: Some(Default::default()),
           reporter: Default::default(),
@@ -13720,6 +13755,7 @@ mod tests {
           sanitize_resources: false,
           coverage_dir: None,
           coverage_raw_data_only: false,
+          coverage_threshold: None,
           clean: false,
           watch: Some(WatchFlagsWithPaths {
             hmr: false,
@@ -14575,6 +14611,36 @@ mod tests {
     );
   }
 
+  #[test]
+  fn coverage_with_threshold() {
+    let r =
+      flags_from_vec(svec!["deno", "coverage", "--threshold=80", "foo.json"]);
+    assert_eq!(
+      r.unwrap(),
+      Flags {
+        subcommand: DenoSubcommand::Coverage(CoverageFlags {
+          files: FileFlags {
+            include: vec!["foo.json".to_string()],
+            ignore: vec![],
+          },
+          include: vec![r"^file:".to_string()],
+          exclude: vec![r"test\.(js|mjs|ts|jsx|tsx)$".to_string()],
+          threshold: Some(80),
+          ..CoverageFlags::default()
+        }),
+        ..Flags::default()
+      }
+    );
+  }
+
+  #[test]
+  fn coverage_threshold_out_of_range() {
+    // Percentages above 100 are rejected by the value parser.
+    let r =
+      flags_from_vec(svec!["deno", "coverage", "--threshold=150", "foo.json"]);
+    assert!(r.is_err());
+  }
+
   #[test]
   fn coverage_with_lcov_and_out_file() {
     let r = flags_from_vec(svec![
@@ -14595,6 +14661,7 @@ mod tests {
           include: vec![r"^file:".to_string()],
           exclude: vec![r"test\.(js|mjs|ts|jsx|tsx)$".to_string()],
           r#type: CoverageType::Lcov,
+          threshold: None,
           output: Some(String::from("foo.lcov")),
         }),
         ..Flags::default()

cli/args/mod.rs

@@ -18,6 +18,7 @@ use deno_cache_dir::file_fetcher::CacheSetting;
 pub use deno_config::deno_json::BenchConfig;
 pub use deno_config::deno_json::CompilerOptions;
 pub use deno_config::deno_json::ConfigFile;
+pub use deno_config::deno_json::CoverageThresholds;
 use deno_config::deno_json::FmtConfig;
 pub use deno_config::deno_json::FmtOptionsConfig;
 pub use deno_config::deno_json::LintRulesConfig;
@@ -1018,6 +1019,14 @@ impl CliOptions {
     Ok(result)
   }
 
+  /// Resolves the coverage thresholds configured in `deno.json`'s `coverage`
+  /// section. CLI flags are layered on top of this by the caller.
+  pub fn resolve_coverage_thresholds(
+    &self,
+  ) -> Result<CoverageThresholds, AnyError> {
+    Ok(self.start_dir.to_coverage_config()?.thresholds)
+  }
+
   pub fn resolve_workspace_test_options(
     &self,
     test_flags: &TestFlags,

cli/lib.rs

@@ -205,6 +205,7 @@ async fn run_subcommand(
         coverage_flags.include,
         coverage_flags.exclude,
         coverage_flags.output,
+        coverage_flags.threshold.map(|t| t as f64),
         &[&*reporter],
       )
     }),

cli/schemas/config-file.v1.json

@@ -1080,6 +1080,36 @@
         }
       }
     },
+    "coverage": {
+      "description": "Configuration for deno coverage and deno test --coverage",
+      "type": "object",
+      "properties": {
+        "thresholds": {
+          "description": "Minimum coverage percentages required for the command to succeed. Each metric is checked against the aggregate across all files.",
+          "type": "object",
+          "properties": {
+            "lines": {
+              "type": "number",
+              "description": "Minimum line coverage percentage (0-100).",
+              "minimum": 0,
+              "maximum": 100
+            },
+            "branches": {
+              "type": "number",
+              "description": "Minimum branch coverage percentage (0-100).",
+              "minimum": 0,
+              "maximum": 100
+            },
+            "functions": {
+              "type": "number",
+              "description": "Minimum function coverage percentage (0-100).",
+              "minimum": 0,
+              "maximum": 100
+            }
+          }
+        }
+      }
+    },
     "license": {
       "description": "The SPDX license identifier if this is a JSR package. Specify this or add a license file to the package.",
       "type": ["string"]

cli/tools/coverage/mod.rs

@@ -30,6 +30,7 @@ use self::ignore_directives::lex_comments;
 use self::ignore_directives::parse_next_ignore_directives;
 use self::ignore_directives::parse_range_ignore_directives;
 use crate::args::CliOptions;
+use crate::args::CoverageThresholds;
 use crate::args::FileFlags;
 use crate::args::Flags;
 use crate::cdp;
@@ -588,13 +589,15 @@ fn filter_coverages(
     .collect::<Vec<cdp::ScriptCoverage>>()
 }
 
+#[allow(clippy::too_many_arguments, reason = "coverage entry point")]
 pub fn cover_files(
   flags: Arc<Flags>,
   files_include: Vec<String>,
   files_ignore: Vec<String>,
   include: Vec<String>,
   exclude: Vec<String>,
   output: Option<String>,
+  cli_threshold: Option<f64>,
   reporters: &[&dyn CoverageReporter],
 ) -> Result<(), AnyError> {
   if files_include.is_empty() {
@@ -770,5 +773,95 @@ pub fn cover_files(
     reporter.done(&coverage_root, &file_reports);
   }
 
+  // Layer the `--threshold` CLI flag over per-metric thresholds from deno.json
+  // (the flag wins) and fail the command if any configured threshold is unmet.
+  let config_thresholds = cli_options.resolve_coverage_thresholds()?;
+  let thresholds = CoverageThresholds {
+    lines: cli_threshold.or(config_thresholds.lines),
+    branches: cli_threshold.or(config_thresholds.branches),
+    functions: cli_threshold.or(config_thresholds.functions),
+  };
+  check_coverage_thresholds(&file_reports, thresholds)?;
+
   Ok(())
 }
+
+/// Computes the aggregate line, branch, and function coverage percentages
+/// across all reported files. A metric with no measurable items counts as 100%
+/// (e.g. a `branches` threshold passes vacuously for files that have no
+/// branches). Reuses the same accumulation and percentage helpers as the
+/// summary reporter so the checked numbers match the printed ones.
+fn aggregate_coverage_percentages(
+  file_reports: &[(CoverageReport, String)],
+) -> (f64, f64, f64) {
+  let mut stats = reporter::CoverageStats::default();
+  for (report, _) in file_reports {
+    stats.add_report(report);
+  }
+  let percent = |hit: usize, miss: usize| -> f64 {
+    util::calc_coverage_display_info(hit, miss).1 as f64
+  };
+  (
+    percent(stats.line_hit, stats.line_miss),
+    percent(stats.branch_hit, stats.branch_miss),
+    percent(stats.fn_hit, stats.fn_miss),
+  )
+}
+
+fn check_coverage_thresholds(
+  file_reports: &[(CoverageReport, String)],
+  thresholds: CoverageThresholds,
+) -> Result<(), AnyError> {
+  if thresholds.lines.is_none()
+    && thresholds.branches.is_none()
+    && thresholds.functions.is_none()
+  {
+    return Ok(());
+  }
+
+  let (line_percent, branch_percent, fn_percent) =
+    aggregate_coverage_percentages(file_reports);
+
+  let mut failures = Vec::new();
+  let mut check = |name: &str, actual: f64, threshold: Option<f64>| {
+    if let Some(threshold) = threshold
+      && actual < threshold
+    {
+      // Floor the displayed value to two decimals so a near-miss like 89.999%
+      // doesn't render as "90.00% is below the threshold of 90.00%".
+      let actual = (actual * 100.0).floor() / 100.0;
+      failures.push(format!(
+        "  - {name} coverage {actual:.2}% is below the threshold of {threshold:.2}%"
+      ));
+    }
+  };
+  check("Line", line_percent, thresholds.lines);
+  check("Branch", branch_percent, thresholds.branches);
+  check("Function", fn_percent, thresholds.functions);
+
+  if failures.is_empty() {
+    Ok(())
+  } else {
+    Err(
+      CoverageThresholdError(format!(
+        "Coverage threshold not met:\n{}",
+        failures.join("\n")
+      ))
+      .into(),
+    )
+  }
+}
+
+/// Returned when a configured coverage threshold is not met. A distinct type so
+/// `deno test --coverage` can treat it as fatal while still tolerating benign
+/// report-generation errors.
+#[derive(Debug)]
+pub struct CoverageThresholdError(pub String);
+
+impl std::fmt::Display for CoverageThresholdError {
+  fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
+    write!(f, "{}", self.0)
+  }
+}
+
+impl std::error::Error for CoverageThresholdError {}