fix: reject out-of-range profiler tunables instead of self-contradicting

min_share / intersection_floor / missing_flag / reference_flag were
accepted as any float, and imbalance_flag / min_group_size as any number,
with no range check anywhere in the CLI -> _build_opts -> _resolve_opts
chain. min_share=1.5 (a percentage/fraction typo) was silently accepted:
every group got flagged "under-represented" in flags while
overall_score/grade stayed 100/"A" - the two halves of the same report
contradicting each other with no error.

_resolve_opts (and its JS mirror resolveOpts) now validate:
  - min_share, intersection_floor, missing_flag, reference_flag in [0, 1]
  - imbalance_flag >= 1
  - min_group_size >= 1
raising ValueError, which the CLI already renders as "error: ..." (exit 2)
and the MCP server wraps as a ToolError. Covers profile_dataset,
compare_datasets, `faircode profile`, and `faircode compare`.

Closes #511

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: propcgamer20-png

assets/profiler-engine.js

@@ -36,6 +36,28 @@
     reference: null   // {column: {group: expected_share}} baseline (SPEC 8)
   };
 
+  // SPEC section 7 tunables that must fall in [0, 1]. Mirrors
+  // faircode.profiler._UNIT_INTERVAL_OPTS.
+  var UNIT_INTERVAL_OPTS = ['min_share', 'intersection_floor', 'missing_flag', 'reference_flag'];
+
+  function validateOpts(o) {
+    // Reject out-of-range tunables instead of silently producing a
+    // self-contradictory report (#511). Mirrors _validate_opts in the
+    // Python engine.
+    UNIT_INTERVAL_OPTS.forEach(function (k) {
+      var v = o[k];
+      if (v !== null && v !== undefined && !(v >= 0 && v <= 1)) {
+        throw new Error(k + ' must be between 0 and 1, got ' + v);
+      }
+    });
+    if (o.imbalance_flag !== null && o.imbalance_flag !== undefined && o.imbalance_flag < 1) {
+      throw new Error('imbalance_flag must be >= 1, got ' + o.imbalance_flag);
+    }
+    if (o.min_group_size !== null && o.min_group_size !== undefined && o.min_group_size < 1) {
+      throw new Error('min_group_size must be >= 1, got ' + o.min_group_size);
+    }
+  }
+
   function resolveOpts(opts) {
     var o = {};
     Object.keys(DEFAULT_OPTS).forEach(function (k) { o[k] = DEFAULT_OPTS[k]; });
@@ -44,6 +66,7 @@
         if (opts[k] !== null && opts[k] !== undefined) o[k] = opts[k];
       });
     }
+    validateOpts(o);
     return o;
   }
   // Comparison / drift (SPEC section 8)

faircode/profiler.py

@@ -65,10 +65,31 @@ def _wilson(count: int, n: int) -> tuple:
 }
 
 
+_UNIT_INTERVAL_OPTS = ("min_share", "intersection_floor", "missing_flag", "reference_flag")
+
+
+def _validate_opts(o: dict) -> None:
+    """Reject out-of-range tunables (SPEC section 7) instead of silently
+    producing a self-contradictory report - e.g. min_share=1.5 flags every
+    group as under-represented while overall_score/grade stay 100/"A" (#511).
+    """
+    for key in _UNIT_INTERVAL_OPTS:
+        v = o.get(key)
+        if v is not None and not 0.0 <= v <= 1.0:
+            raise ValueError(f"{key} must be between 0 and 1, got {v!r}")
+    imbalance = o.get("imbalance_flag")
+    if imbalance is not None and imbalance < 1.0:
+        raise ValueError(f"imbalance_flag must be >= 1, got {imbalance!r}")
+    min_group_size = o.get("min_group_size")
+    if min_group_size is not None and min_group_size < 1:
+        raise ValueError(f"min_group_size must be >= 1, got {min_group_size!r}")
+
+
 def _resolve_opts(opts) -> dict:
     o = dict(_DEFAULT_OPTS)
     if opts:
         o.update({k: v for k, v in opts.items() if v is not None})
+    _validate_opts(o)
     return o
 
 

tests/test_cli.py

@@ -36,6 +36,19 @@ def test_profile_fail_under_returns_nonzero_and_explains_score(tmp_path, capsys)
     assert "representation score 72/100 is below --fail-under 90" in captured.err
 
 
+def test_profile_rejects_out_of_range_min_share(tmp_path, capsys):
+    # A percentage/fraction typo (15 instead of 0.15, or 1.5) used to be
+    # accepted silently and produce a self-contradictory report (#511).
+    path = tmp_path / "a.csv"
+    path.write_text("sex\n" + "M\n" * 50 + "F\n" * 50, encoding="utf-8")
+
+    exit_code = main(["profile", str(path), "--min-share", "1.5"])
+
+    captured = capsys.readouterr()
+    assert exit_code != 0
+    assert "min_share must be between 0 and 1" in captured.err
+
+
 def test_profile_fail_under_keeps_json_output_machine_readable(tmp_path, capsys):
     path = tmp_path / "balanced.csv"
     path.write_text("sex\nM\nF\nM\nF\n", encoding="utf-8")

tests/test_js_parity.py

@@ -234,6 +234,25 @@ def test_python_js_profiler_parity_with_overrides_cross_and_thresholds(tmp_path)
     assert any("reference" in d for d in python_result["dimensions"])
 
 
+def test_python_js_reject_out_of_range_min_share_parity(tmp_path):
+    """Both engines reject an out-of-range tunable (min_share=1.5) rather
+    than silently producing a self-contradictory report (#511)."""
+    csv = CSV_PATHS["small.csv"]
+
+    with pytest.raises(ValueError, match="min_share must be between 0 and 1"):
+        profile(pd.read_csv(csv), opts={"min_share": 1.5})
+
+    opts_path = tmp_path / "opts.json"
+    opts_path.write_text(json.dumps({"opts": {"min_share": 1.5}}), encoding="utf-8")
+
+    completed = subprocess.run(
+        ["node", "scripts/engine-js.js", "profile", str(csv), str(opts_path)],
+        capture_output=True, text=True, encoding="utf-8", check=False,
+    )
+    assert completed.returncode != 0
+    assert "min_share must be between 0 and 1" in completed.stderr
+
+
 def test_python_js_cross_parity_on_unmatched_column(tmp_path):
     """An unmatched `cross` column raises the same error on both engines
     instead of the JS engine silently falling back to the first two detected

tests/test_profiler.py

@@ -308,6 +308,22 @@ def test_imbalance_flag_tunable():
                    for f in profile(df, opts={"imbalance_flag": 5.0})["flags"])
 
 
+@pytest.mark.parametrize("opts, message", [
+    ({"min_share": 1.5}, "min_share must be between 0 and 1"),
+    ({"min_share": -0.1}, "min_share must be between 0 and 1"),
+    ({"intersection_floor": 2.0}, "intersection_floor must be between 0 and 1"),
+    ({"missing_flag": 5.0}, "missing_flag must be between 0 and 1"),
+    ({"imbalance_flag": 0.5}, "imbalance_flag must be >= 1"),
+    ({"min_group_size": 0}, "min_group_size must be >= 1"),
+])
+def test_out_of_range_tunables_raise_instead_of_contradicting_themselves(opts, message):
+    # min_share=1.5 used to be accepted silently: every group flagged
+    # "under-represented" while overall_score/grade stayed 100/"A" (#511).
+    df = pd.DataFrame({"sex": ["M"] * 50 + ["F"] * 50})
+    with pytest.raises(ValueError, match=message):
+        profile(df, opts=opts)
+
+
 # ── Choosable intersection pair (issue #58) ──────────────────────────────────
 def test_cross_selects_intersection_pair():
     df = pd.DataFrame({