@jjlmoya/utils-civic 1.2.0 → 1.4.0

package/src/tool/referendum-threshold-calculator/logic.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest';
+import { evaluateReferendum, getExampleInput, type ReferendumInput } from './logic';
+
+const withChanges = (changes: Partial<ReferendumInput['counts']>): ReferendumInput => ({ ...getExampleInput(), counts: { ...getExampleInput().counts, ...changes } });
+
+describe('referendum threshold logic', () => {
+  it('passes the documented example with inclusive percentage thresholds', () => {
+    const result = evaluateReferendum(getExampleInput());
+    expect(result.status).toBe('passed');
+    expect(result.participation).toMatchObject({ numerator: 850, denominator: 1000, rate: 85, passed: true });
+    expect(result.approval).toMatchObject({ numerator: 520, denominator: 820, passed: true });
+  });
+
+  it('keeps blank and invalid ballots in all ballots but not valid votes', () => {
+    const result = evaluateReferendum(withChanges({ yes: 10, no: 10, blank: 30, invalid: 50 }));
+    expect(result.totals).toEqual({ allBallots: 100, validVotes: 20, participationCount: 100 });
+    expect(result.approval.denominator).toBe(20);
+  });
+
+  it('distinguishes participation failure from approval failure', () => {
+    const participation = evaluateReferendum(withChanges({ yes: 200, no: 100, blank: 10, invalid: 0 }));
+    expect(participation.status).toBe('participation-failed');
+    const approval = evaluateReferendum({ ...withChanges({ yes: 300, no: 500, blank: 20, invalid: 10 }), rules: { ...getExampleInput().rules, approval: { mode: 'percentage', value: 50, denominator: 'valid-votes' } } });
+    expect(approval.status).toBe('approval-failed');
+  });
+
+  it('supports absolute participation and approval thresholds', () => {
+    const input = getExampleInput();
+    input.rules = { participation: { mode: 'absolute', value: 800, denominator: 'all-ballots' }, approval: { mode: 'absolute', value: 500, denominator: 'valid-votes' } };
+    const result = evaluateReferendum(input);
+    expect(result.status).toBe('passed');
+  });
+
+  it('supports approval thresholds over the electorate and strict majorities', () => {
+    const input = getExampleInput();
+    input.rules.approval = { mode: 'percentage', value: 50, denominator: 'eligible-voters', comparison: 'more-than' };
+    const result = evaluateReferendum(input);
+    expect(result.approval).toMatchObject({ numerator: 520, denominator: 1000, rate: 52, passed: true });
+    input.counts.yes = 500;
+    input.counts.no = 300;
+    expect(evaluateReferendum(input).approval.passed).toBe(false);
+  });
+
+  it('fails safely when approval has no denominator', () => {
+    const result = evaluateReferendum(withChanges({ yes: 0, no: 0, blank: 20, invalid: 5 }));
+    expect(result.valid).toBe(true);
+    expect(result.approval.rate).toBe(0);
+    expect(result.approval.passed).toBe(false);
+    expect(result.warnings).toContain('no-valid-votes');
+  });
+
+  it('rejects impossible totals and invalid threshold values', () => {
+    const impossible = evaluateReferendum(withChanges({ eligibleVoters: 10, yes: 20 }));
+    expect(impossible.status).toBe('invalid');
+    expect(impossible.errors).toContain('ballots-exceed-eligible');
+    const invalidThreshold = evaluateReferendum({ ...getExampleInput(), rules: { ...getExampleInput().rules, approval: { mode: 'percentage', value: 101, denominator: 'valid-votes' } } });
+    expect(invalidThreshold.errors).toContain('invalid-percentage');
+  });
+
+  it('treats zero thresholds as valid only when the required denominator exists', () => {
+    const input = getExampleInput();
+    input.rules = { participation: { mode: 'percentage', value: 0, denominator: 'all-ballots' }, approval: { mode: 'percentage', value: 0, denominator: 'valid-votes' } };
+    const result = evaluateReferendum(input);
+    expect(result.participation.passed).toBe(true);
+    expect(result.approval.passed).toBe(true);
+    const empty = evaluateReferendum({ ...input, counts: { eligibleVoters: 100, yes: 0, no: 0, blank: 0, invalid: 0 } });
+    expect(empty.approval.passed).toBe(false);
+  });
+});

package/src/tool/referendum-threshold-calculator/logic.ts

@@ -0,0 +1,120 @@
+export type ThresholdMode = 'percentage' | 'absolute';
+export type DenominatorMode = 'all-ballots' | 'valid-votes' | 'eligible-voters';
+export type ThresholdComparison = 'at-least' | 'more-than';
+
+export interface BallotCounts {
+  eligibleVoters: number;
+  yes: number;
+  no: number;
+  blank: number;
+  invalid: number;
+}
+
+export interface ThresholdRule {
+  mode: ThresholdMode;
+  value: number;
+  denominator: DenominatorMode;
+  comparison?: ThresholdComparison;
+}
+
+export interface RuleSet {
+  participation: ThresholdRule;
+  approval: ThresholdRule;
+}
+
+export interface ReferendumInput {
+  counts: BallotCounts;
+  rules: RuleSet;
+}
+
+export interface Totals {
+  allBallots: number;
+  validVotes: number;
+  participationCount: number;
+}
+
+export interface RuleEvaluation {
+  numerator: number;
+  denominator: number;
+  rate: number;
+  mode: ThresholdMode;
+  comparison: ThresholdComparison;
+  threshold: number;
+  passed: boolean;
+  denominatorMode: DenominatorMode;
+}
+
+export type ReferendumStatus = 'passed' | 'participation-failed' | 'approval-failed' | 'both-failed' | 'invalid';
+
+export interface ReferendumEvaluation {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+  totals: Totals;
+  participation: RuleEvaluation;
+  approval: RuleEvaluation;
+  status: ReferendumStatus;
+}
+
+const emptyRule: RuleEvaluation = { numerator: 0, denominator: 0, rate: 0, mode: 'percentage', comparison: 'at-least', threshold: 0, passed: false, denominatorMode: 'valid-votes' };
+
+function isWholeNonnegative(value: number): boolean {
+  return Number.isFinite(value) && Number.isInteger(value) && value >= 0;
+}
+
+function validateCounts(counts: BallotCounts): string[] {
+  if (!Object.values(counts).every(isWholeNonnegative) || counts.eligibleVoters === 0) return ['invalid-counts'];
+  if (counts.yes + counts.no + counts.blank + counts.invalid > counts.eligibleVoters) return ['ballots-exceed-eligible'];
+  return [];
+}
+
+function validateRule(rule: ThresholdRule): string[] {
+  if (!Number.isFinite(rule.value) || rule.value < 0) return ['invalid-threshold'];
+  if (rule.mode === 'percentage' && rule.value > 100) return ['invalid-percentage'];
+  if (rule.mode === 'absolute' && !Number.isInteger(rule.value)) return ['invalid-absolute-threshold'];
+  return [];
+}
+
+function getDenominator(counts: BallotCounts, mode: DenominatorMode): number {
+  if (mode === 'all-ballots') return counts.yes + counts.no + counts.blank + counts.invalid;
+  if (mode === 'valid-votes') return counts.yes + counts.no;
+  return counts.eligibleVoters;
+}
+
+function meetsThreshold(observed: number, threshold: number, comparison: ThresholdComparison): boolean {
+  return comparison === 'more-than' ? observed > threshold : observed >= threshold;
+}
+
+function evaluateRule(rule: ThresholdRule, numerator: number, denominator: number): RuleEvaluation {
+  const comparison = rule.comparison ?? 'at-least';
+  const rate = denominator > 0 ? (numerator / denominator) * 100 : 0;
+  const passed = rule.mode === 'percentage' ? denominator > 0 && meetsThreshold(rate, rule.value, comparison) : meetsThreshold(numerator, rule.value, comparison);
+  return { numerator, denominator, rate, mode: rule.mode, comparison, threshold: rule.value, passed, denominatorMode: rule.denominator };
+}
+
+function getStatus(participation: RuleEvaluation, approval: RuleEvaluation): ReferendumStatus {
+  if (participation.passed && approval.passed) return 'passed';
+  if (!participation.passed && !approval.passed) return 'both-failed';
+  return participation.passed ? 'approval-failed' : 'participation-failed';
+}
+
+export function evaluateReferendum(input: ReferendumInput): ReferendumEvaluation {
+  const errors = [...new Set([...validateCounts(input.counts), ...validateRule(input.rules.participation), ...validateRule(input.rules.approval)])];
+  const allBallots = input.counts.yes + input.counts.no + input.counts.blank + input.counts.invalid;
+  const validVotes = input.counts.yes + input.counts.no;
+  const participationCount = getDenominator(input.counts, input.rules.participation.denominator);
+  const totals: Totals = { allBallots, validVotes, participationCount };
+  const participation = evaluateRule(input.rules.participation, participationCount, input.counts.eligibleVoters);
+  const approval = evaluateRule(input.rules.approval, input.counts.yes, getDenominator(input.counts, input.rules.approval.denominator));
+  const warnings: string[] = [];
+  if (allBallots === 0) warnings.push('no-ballots');
+  if (validVotes === 0) warnings.push('no-valid-votes');
+  if (errors.length > 0) return { valid: false, errors, warnings, totals, participation, approval, status: 'invalid' };
+  return { valid: true, errors: [], warnings, totals, participation, approval, status: getStatus(participation, approval) };
+}
+
+export function getExampleInput(): ReferendumInput {
+  return { counts: { eligibleVoters: 1000, yes: 520, no: 300, blank: 20, invalid: 10 }, rules: { participation: { mode: 'percentage', value: 50, denominator: 'all-ballots', comparison: 'at-least' }, approval: { mode: 'percentage', value: 50, denominator: 'valid-votes', comparison: 'at-least' } } };
+}
+
+export const EMPTY_RULE_EVALUATION = emptyRule;