توطين المهن المحاسبية بـ TypeScript: محرّك نسبة الـ 50%

// tawteen/phases.ts
 
/** A size bracket within a phase. `max: null` means "and above". */
export type Bracket = {
  readonly min: number;
  readonly max: number | null;
  /** Whole percentage points. Never store this as a fraction. */
  readonly ratePercent: number;
};
 
export type Phase = {
  readonly ordinal: 1 | 2 | 3 | 4 | 5;
  /** ISO date the phase takes effect, inclusive. */
  readonly effectiveFrom: string;
  readonly brackets: readonly Bracket[];
};
 
export const ACCOUNTING_PHASES: readonly Phase[] = [
  { ordinal: 1, effectiveFrom: '2025-10-27', brackets: [{ min: 5, max: null, ratePercent: 40 }] },
  { ordinal: 2, effectiveFrom: '2026-10-27', brackets: [{ min: 5, max: null, ratePercent: 50 }] },
  { ordinal: 3, effectiveFrom: '2027-10-27', brackets: [{ min: 5, max: null, ratePercent: 60 }] },
  { ordinal: 4, effectiveFrom: '2028-10-27', brackets: [{ min: 5, max: null, ratePercent: 70 }] },
  {
    ordinal: 5,
    effectiveFrom: '2029-10-27',
    brackets: [
      // New in phase five: small establishments enter scope.
      { min: 3, max: 4, ratePercent: 30 },
      { min: 5, max: null, ratePercent: 70 },
    ],
  },
];

// tawteen/rate.ts
import { ACCOUNTING_PHASES, type Phase } from './phases';
 
export type ApplicableRate = {
  readonly phase: Phase['ordinal'];
  readonly ratePercent: number;
};
 
function phaseOn(onDate: string): Phase | null {
  let found: Phase | null = null;
  // ISO strings compare lexicographically; the table is in ascending order.
  for (const p of ACCOUNTING_PHASES) if (p.effectiveFrom <= onDate) found = p;
  return found;
}
 
/** `null` means the establishment is outside the decision's scope on that date. */
export function rateFor(totalAccountants: number, onDate: string): ApplicableRate | null {
  const phase = phaseOn(onDate);
  if (!phase) return null;
 
  for (const b of phase.brackets) {
    if (totalAccountants < b.min) continue;
    if (b.max !== null && totalAccountants > b.max) continue;
    return { phase: phase.ordinal, ratePercent: b.ratePercent };
  }
  return null;
}

// tawteen/job-codes.ts
 
/**
 * Job codes targeted by Ministerial Decision 103108, as transcribed from the
 * ministry's procedural guide. This table IS the denominator: a worker whose
 * GOSI job code is absent from it is outside the calculation entirely.
 */
export const TARGETED_JOB_CODES = {
  '121101': 'Financial manager',
  '121102': 'Accounts manager',
  '121103': 'Tariff accounts manager',
  '121104': 'Treasury manager',
  '121105': 'Budget manager',
  '121106': 'Audit manager',
  '121107': 'Internal audit manager',
  '121113': 'Collections manager',
  '121116': 'Treasury director',
  '241101': 'Accountant',
  '241102': 'Cost accountant',
  '241103': 'Internal auditor',
  '241105': 'Chartered accountant',
  '241106': 'Financial controller',
  '241107': 'Financial budgeting specialist',
  '241108': 'Tax accounts specialist',
  '241109': 'Inventory control specialist',
  '331301': 'Accounts assistant',
  '331302': 'Inventory controller',
  '335202': 'Tax officer',
  '431101': 'Accounts clerk',
  '431201': 'Finance clerk',
} as const;
 
export type TargetedJobCode = keyof typeof TARGETED_JOB_CODES;
 
export function isTargeted(code: string): code is TargetedJobCode {
  return code in TARGETED_JOB_CODES;
}

// tawteen/countable.ts
import { isTargeted } from './job-codes';
 
export type Qualification = 'BACHELOR' | 'DIPLOMA';
 
/** Minimum GOSI contributory wage in SAR for a Saudi accountant to be counted. */
export const WAGE_FLOOR_SAR: Record<Qualification, number> = {
  BACHELOR: 6000,
  DIPLOMA: 4500,
};
 
export type ExclusionReason =
  | 'JOB_CODE_NOT_TARGETED'
  | 'WAGE_BELOW_FLOOR'
  | 'SOCPA_ACCREDITATION_INACTIVE'
  | 'QUALIFICATION_UNMAPPED';
 
export type Employee = {
  readonly id: string;
  readonly nationality: 'SA' | 'NON_SA';
  /** The code as registered with GOSI — not the internal HR title. */
  readonly gosiJobCode: string;
  /** Undefined when HR holds no usable qualification record. */
  readonly qualification?: Qualification;
  /** The GOSI contributory wage, not gross pay and not basic salary. */
  readonly contributoryWageSar: number;
  readonly socpaAccreditationActive: boolean;
};
 
export type EmployeeAssessment = {
  readonly inDenominator: boolean;
  readonly inNumerator: boolean;
  readonly reasons: readonly ExclusionReason[];
};
 
export function assessEmployee(e: Employee): EmployeeAssessment {
  if (!isTargeted(e.gosiJobCode)) {
    // Outside the profession family: neither term. Not an exclusion, a filter.
    return { inDenominator: false, inNumerator: false, reasons: ['JOB_CODE_NOT_TARGETED'] };
  }
 
  // A non-Saudi accountant is denominator-only by definition.
  if (e.nationality !== 'SA') {
    return { inDenominator: true, inNumerator: false, reasons: [] };
  }
 
  const reasons: ExclusionReason[] = [];
 
  if (e.qualification === undefined) {
    // Never assume the lower floor to be generous. An unknown qualification is
    // a data incident to resolve, not a number to guess.
    reasons.push('QUALIFICATION_UNMAPPED');
  } else if (e.contributoryWageSar < WAGE_FLOOR_SAR[e.qualification]) {
    reasons.push('WAGE_BELOW_FLOOR');
  }
 
  if (!e.socpaAccreditationActive) {
    reasons.push('SOCPA_ACCREDITATION_INACTIVE');
  }
 
  return { inDenominator: true, inNumerator: reasons.length === 0, reasons };
}

// Wrong. Do not ship this.
const required = Math.round(total * (ratePercent / 100));

// tawteen/required.ts
 
/**
 * Required Saudi accountants, rounded to nearest with halves rounding up.
 * Integer-only: `total * ratePercent` is exact, so no float ever enters.
 */
export function requiredSaudis(totalAccountants: number, ratePercent: number): number {
  return Math.floor((totalAccountants * ratePercent + 50) / 100);
}

/** Achieved rate in basis points, truncated. 4000 = 40.00%. */
export function achievedBasisPoints(countableSaudis: number, totalAccountants: number): number {
  if (totalAccountants === 0) return 0;
  return Math.floor((countableSaudis * 10000) / totalAccountants);
}

// tawteen/assess.ts
import { assessEmployee, type Employee, type ExclusionReason } from './countable';
import { rateFor } from './rate';
import { achievedBasisPoints, requiredSaudis } from './required';
 
export type ExcludedSaudi = {
  readonly employeeId: string;
  readonly reasons: readonly ExclusionReason[];
};
 
export type Assessment =
  | { readonly inScope: false; readonly totalAccountants: number }
  | {
      readonly inScope: true;
      readonly phase: number;
      readonly ratePercent: number;
      readonly totalAccountants: number;
      readonly countableSaudis: number;
      readonly requiredSaudis: number;
      /** Heads short, by replacement. Zero when compliant. */
      readonly replacementGap: number;
      readonly achievedBasisPoints: number;
      readonly excludedSaudis: readonly ExcludedSaudi[];
    };
 
export function assess(roster: readonly Employee[], onDate: string): Assessment {
  let total = 0;
  let countable = 0;
  const excludedSaudis: ExcludedSaudi[] = [];
 
  for (const e of roster) {
    const a = assessEmployee(e);
    if (!a.inDenominator) continue;
 
    total += 1;
    if (a.inNumerator) {
      countable += 1;
    } else if (e.nationality === 'SA') {
      // A Saudi in the denominator but not the numerator is the remediation list.
      excludedSaudis.push({ employeeId: e.id, reasons: a.reasons });
    }
  }
 
  const rate = rateFor(total, onDate);
  if (!rate) return { inScope: false, totalAccountants: total };
 
  const required = requiredSaudis(total, rate.ratePercent);
 
  return {
    inScope: true,
    phase: rate.phase,
    ratePercent: rate.ratePercent,
    totalAccountants: total,
    countableSaudis: countable,
    requiredSaudis: required,
    replacementGap: Math.max(0, required - countable),
    achievedBasisPoints: achievedBasisPoints(countable, total),
    excludedSaudis,
  };
}

// tawteen/gap.ts
import { requiredSaudis } from './required';
 
export type Remediation = {
  /** Non-Saudi accountants to replace with Saudis. Denominator unchanged. */
  readonly byReplacement: number;
  /** Net new countable Saudi hires, if you replace nobody. Denominator grows. */
  readonly byHiringOnly: number;
};
 
export function remediation(
  totalAccountants: number,
  countableSaudis: number,
  ratePercent: number,
): Remediation {
  const byReplacement = Math.max(0, requiredSaudis(totalAccountants, ratePercent) - countableSaudis);
 
  let hires = 0;
  // Each hire adds one to both terms; the target moves, so solve rather than divide.
  while (countableSaudis + hires < requiredSaudis(totalAccountants + hires, ratePercent)) {
    hires += 1;
    if (hires > 10_000) throw new Error('remediation did not converge');
  }
 
  return { byReplacement, byHiringOnly: hires };
}

// tawteen/forecast.ts
import { ACCOUNTING_PHASES } from './phases';
import { rateFor } from './rate';
import { requiredSaudis } from './required';
 
export type FutureBreach = {
  readonly effectiveFrom: string;
  readonly phase: number;
  readonly ratePercent: number;
  readonly requiredSaudis: number;
  readonly shortfall: number;
};
 
/** Phase dates on which the current roster would breach, if nothing changes. */
export function forecast(
  totalAccountants: number,
  countableSaudis: number,
  fromDate: string,
): FutureBreach[] {
  const out: FutureBreach[] = [];
 
  for (const phase of ACCOUNTING_PHASES) {
    if (phase.effectiveFrom <= fromDate) continue;
 
    const rate = rateFor(totalAccountants, phase.effectiveFrom);
    if (!rate) continue; // Still out of scope at that size.
 
    const required = requiredSaudis(totalAccountants, rate.ratePercent);
    if (countableSaudis >= required) continue;
 
    out.push({
      effectiveFrom: phase.effectiveFrom,
      phase: rate.phase,
      ratePercent: rate.ratePercent,
      requiredSaudis: required,
      shortfall: required - countableSaudis,
    });
  }
  return out;
}

import { strict as assert } from 'node:assert';
import { requiredSaudis } from './required';
import { remediation } from './gap';
 
// Ministry procedural guide, phase two: 23 x 50% = 11.5 -> 12.
assert.equal(requiredSaudis(23, 50), 12);
// Phase one from the same guide: 9.2 -> 9.
assert.equal(requiredSaudis(23, 40), 9);
 
// The float trap: Math.round(45 * 0.7) is 31 and wrong.
assert.equal(requiredSaudis(45, 70), 32);
assert.equal(requiredSaudis(85, 70), 60);
 
// Replacement and hiring are different numbers, and the gap is the smaller one.
assert.deepEqual(remediation(23, 9, 50), { byReplacement: 3, byHiringOnly: 5 });

import { TARGETED_JOB_CODES } from './job-codes';
import { ACCOUNTING_PHASES } from './phases';
 
const codes = Object.keys(TARGETED_JOB_CODES);
assert.equal(new Set(codes).size, codes.length, 'duplicate job code');
assert.ok(codes.every((c) => /^\d{6}$/.test(c)), 'job codes are six digits');
assert.equal(ACCOUNTING_PHASES.length, 5);