scripts/loaders/miami/ell-bounds.ts

// FLDOE's suppressed race cells do not identify a school-level ELL total.
// Numeric zero stays zero; a suppressed cell contributes [0, 9], conservatively
// allowing zero because historical files have used the same token for zeros.
export type EllCell = { value: number | null; suppressed: boolean; token?: string | null };

export function ellBounds(cells: EllCell[], enrollment: number) {
  if (!Number.isFinite(enrollment) || enrollment <= 0) throw new Error("ELL bounds require positive October membership");
  let visible = 0, hidden = 0;
  for (const c of cells) {
    if (c.suppressed) { hidden++; continue; }
    if (c.value === null) {
      if (c.token) throw new Error(`Unrecognized ELL count token: ${c.token}`);
      continue; // blank race cell = no reported count
    }
    if (!Number.isInteger(c.value) || c.value < 0) throw new Error(`Invalid ELL count: ${c.value}`);
    visible += c.value;
  }
  if (visible > enrollment) throw new Error(`Visible ELL count ${visible} exceeds October membership ${enrollment}`);
  const lower = 100 * visible / enrollment;
  const upper = 100 * Math.min(enrollment, visible + 9 * hidden) / enrollment;
  return { lower, upper, exact: lower === upper ? lower : null, hidden };
}