توطين المهن الفنية الهندسية بنسبة 35%: محرك امتثال بلغة TypeScript

/** A dated rate step: from this date (inclusive), this percentage applies. */
export interface RateStep {
  readonly from: string; // ISO date, YYYY-MM-DD
  readonly ratePercent: number; // integer, e.g. 35
}
 
export interface OccupationDecision {
  readonly id: string;
  /** Unified Saudi Classification of Occupations codes covered by the decision. */
  readonly codes: ReadonlySet<string>;
  /** Steps in date order. */
  readonly steps: readonly RateStep[];
  /** The decision applies only at or above this many workers in the covered codes. */
  readonly minWorkers: number;
  /** Minimum GOSI contributory wage, in SAR, for a Saudi to be counted. */
  readonly minWageSar: number;
}
 
export const ENGINEERING_TECHNICIANS: OccupationDecision = {
  id: 'engineering-technicians',
  // Seven of the codes printed in the 2025 procedural guide. Load the full list
  // from the current guide; do not ship this sample as your production table.
  codes: new Set([
    '311201', // civil engineering technician
    '311211', // surveying technician
    '311301', // electrical engineering technician
    '311409', // electronics engineering technician
    '311501', // mechanical engineering technician
    '311511', // mechanical maintenance technician
    '311805', // architectural draughtsman
  ]),
  steps: [
    { from: '2025-07-23', ratePercent: 30 },
    { from: '2027-05-09', ratePercent: 35 },
  ],
  minWorkers: 5,
  minWageSar: 5000,
};
 
/** The rate in force on a date, or null before the first step. */
export function rateOn(decision: OccupationDecision, isoDate: string): number | null {
  let rate: number | null = null;
  for (const step of decision.steps) {
    if (step.from <= isoDate) rate = step.ratePercent;
  }
  return rate;
}

/**
 * Where one code is covered by several decisions, the guide applies the higher rate.
 * Returns the decision that governs this code on this date, or null if none does.
 */
export function governingDecision(
  code: string,
  isoDate: string,
  decisions: readonly OccupationDecision[],
): OccupationDecision | null {
  let best: OccupationDecision | null = null;
  let bestRate = -1;
  for (const d of decisions) {
    if (!d.codes.has(code)) continue;
    const rate = rateOn(d, isoDate);
    if (rate !== null && rate > bestRate) {
      best = d;
      bestRate = rate;
    }
  }
  return best;
}

export interface Worker {
  readonly id: string;
  readonly occupationCode: string;
  readonly saudi: boolean;
  /** Contributory wage registered with GOSI, in SAR. Not gross pay. */
  readonly gosiWageSar: number;
  /** Active professional accreditation with the Saudi Council of Engineers. */
  readonly sceAccredited: boolean;
  /**
   * True when a line manager confirms the person does targeted technical work
   * under a title outside the list. The decision follows the actual work.
   */
  readonly doesTargetedWork?: boolean;
}
 
export type Exclusion = 'NOT_SAUDI' | 'WAGE_BELOW_FLOOR' | 'NOT_SCE_ACCREDITED';
 
/** Every reason this worker does not count toward the numerator. Empty means countable. */
export function exclusions(w: Worker, decision: OccupationDecision): Exclusion[] {
  const reasons: Exclusion[] = [];
  if (!w.saudi) reasons.push('NOT_SAUDI');
  if (w.gosiWageSar < decision.minWageSar) reasons.push('WAGE_BELOW_FLOOR');
  if (!w.sceAccredited) reasons.push('NOT_SCE_ACCREDITED');
  return reasons;
}

/**
 * Required Saudis = workers x rate, rounded to the nearest whole number.
 * Integer arithmetic only; a half rounds up (the guide does not say, this is our reading).
 */
export function requiredSaudis(workers: number, ratePercent: number): number {
  return Math.floor((workers * ratePercent + 50) / 100);
}

export interface Assessment {
  readonly decisionId: string;
  readonly isoDate: string;
  readonly applies: boolean;
  readonly ratePercent: number;
  readonly workers: number;
  readonly countableSaudis: number;
  readonly required: number;
  /** Non-Saudis to replace with countable Saudis. Denominator unchanged. */
  readonly byReplacement: number;
  /** Net new countable Saudi hires if nobody leaves. Denominator grows. */
  readonly byHiringOnly: number;
  /** Saudis in scope who do not count, with every reason. */
  readonly excluded: ReadonlyArray<{ id: string; reasons: Exclusion[] }>;
  /** People counted in scope only because of the actual-work rule. */
  readonly actualWorkFlags: readonly string[];
}
 
export function hiresOnly(workers: number, countable: number, ratePercent: number): number {
  if (ratePercent >= 100) throw new Error('rate must be under 100%');
  let k = 0;
  while (countable + k < requiredSaudis(workers + k, ratePercent)) k++;
  return k;
}
 
export function assess(
  staff: readonly Worker[],
  decision: OccupationDecision,
  all: readonly OccupationDecision[],
  isoDate: string,
): Assessment {
  const rate = rateOn(decision, isoDate) ?? 0;
  const inScope: Worker[] = [];
  const actualWorkFlags: string[] = [];
  for (const w of staff) {
    if (governingDecision(w.occupationCode, isoDate, all) === decision) {
      inScope.push(w);
    } else if (w.doesTargetedWork && !w.saudi) {
      inScope.push(w);
      actualWorkFlags.push(w.id);
    }
  }
  const workers = inScope.length;
  const applies = rate > 0 && workers >= decision.minWorkers;
  const excluded: { id: string; reasons: Exclusion[] }[] = [];
  let countable = 0;
  for (const w of inScope) {
    const reasons = exclusions(w, decision);
    if (reasons.length === 0) countable++;
    else if (w.saudi) excluded.push({ id: w.id, reasons });
  }
  const required = applies ? requiredSaudis(workers, rate) : 0;
  return {
    decisionId: decision.id,
    isoDate,
    applies,
    ratePercent: rate,
    workers,
    countableSaudis: countable,
    required,
    byReplacement: Math.max(0, required - countable),
    byHiringOnly: applies ? hiresOnly(workers, countable, rate) : 0,
    excluded,
    actualWorkFlags,
  };
}

/** Saudi working week: Sunday to Thursday. Friday (5) and Saturday (6) are off. */
function isWorkingDay(d: Date): boolean {
  const day = d.getUTCDay();
  return day !== 5 && day !== 6;
}
 
/**
 * Latest date a hire, wage change or accreditation must be registered so that it
 * shows in the ministry's count by `isoDate`, given a sync lag in working days.
 * The guide says updates show within five working days at most.
 */
export function registerBy(isoDate: string, lagWorkingDays = 5): string {
  const d = new Date(`${isoDate}T00:00:00Z`);
  let left = lagWorkingDays;
  while (left > 0) {
    d.setUTCDate(d.getUTCDate() - 1);
    if (isWorkingDay(d)) left--;
  }
  return d.toISOString().slice(0, 10);
}

import { test } from 'node:test';
import assert from 'node:assert/strict';
import {
  ENGINEERING_TECHNICIANS as ET, assess, hiresOnly, rateOn,
  registerBy, requiredSaudis, type OccupationDecision, type Worker,
} from './engine.ts';
 
function crew(n: number, saudi: number, code = '311201'): Worker[] {
  return Array.from({ length: n }, (_, i) => ({
    id: `w${i}`, occupationCode: code, saudi: i < saudi,
    gosiWageSar: 6000, sceAccredited: true,
  }));
}
 
test('rate steps from 30% to 35% on 9 May 2027', () => {
  assert.equal(rateOn(ET, '2025-07-22'), null);
  assert.equal(rateOn(ET, '2027-05-08'), 30);
  assert.equal(rateOn(ET, '2027-05-09'), 35);
});
 
test("the guide's worked example: 51 technicians, 4 Saudi, at 30%", () => {
  const a = assess(crew(51, 4), ET, [ET], '2026-11-09');
  assert.equal(a.required, 15);
  assert.equal(a.byReplacement, 11);
  assert.equal(a.byHiringOnly, 16);
});
 
test('the same establishment at 35%', () => {
  const a = assess(crew(51, 4), ET, [ET], '2027-05-09');
  assert.equal(a.required, 18);
  assert.equal(a.byReplacement, 14);
  assert.equal(a.byHiringOnly, 21);
});
 
test('all-Saudi FAQ: 20 Saudis still need 6 who meet both conditions', () => {
  const staff = crew(20, 20).map((w, i) =>
    i < 6 ? w : { ...w, sceAccredited: false });
  const a = assess(staff, ET, [ET], '2026-11-09');
  assert.equal(a.required, 6);
  assert.equal(a.byReplacement, 0);
  assert.equal(a.excluded.length, 14);
});
 
test('four workers in scope: the decision does not apply', () => {
  const a = assess(crew(4, 0), ET, [ET], '2027-05-09');
  assert.equal(a.applies, false);
  assert.equal(a.byHiringOnly, 0);
});
 
test('every failing reason is kept, not just the first', () => {
  const [w] = crew(1, 1);
  const a = assess(
    [{ ...w!, gosiWageSar: 4800, sceAccredited: false }, ...crew(5, 0).map((x) => ({ ...x, id: `n${x.id}` }))],
    ET, [ET], '2026-11-09');
  assert.deepEqual(a.excluded[0]?.reasons, ['WAGE_BELOW_FLOOR', 'NOT_SCE_ACCREDITED']);
});
 
test('wage floor is inclusive at SAR 5,000', () => {
  const staff = crew(10, 3).map((w, i) => (i === 0 ? { ...w, gosiWageSar: 5000 } : w));
  assert.equal(assess(staff, ET, [ET], '2026-11-09').countableSaudis, 3);
});
 
test('actual-work rule pulls an off-list non-Saudi into scope', () => {
  const staff: Worker[] = [
    ...crew(5, 2),
    { id: 'x', occupationCode: '999999', saudi: false, gosiWageSar: 3000,
      sceAccredited: false, doesTargetedWork: true },
  ];
  const a = assess(staff, ET, [ET], '2026-11-09');
  assert.equal(a.workers, 6);
  assert.deepEqual(a.actualWorkFlags, ['x']);
});
 
test('higher rate wins when two decisions cover one code', () => {
  const other: OccupationDecision = {
    id: 'other', codes: new Set(['311201']),
    steps: [{ from: '2025-01-01', ratePercent: 50 }], minWorkers: 1, minWageSar: 4000,
  };
  const all = [ET, other];
  assert.equal(assess(crew(10, 0), ET, all, '2026-11-09').workers, 0);
  assert.equal(assess(crew(10, 0), other, all, '2026-11-09').workers, 10);
});
 
test('rounding: half rounds up, .3 rounds down, no float drift', () => {
  assert.equal(requiredSaudis(10, 35), 4); // 3.5
  assert.equal(requiredSaudis(51, 30), 15); // 15.3
  assert.equal(requiredSaudis(51, 35), 18); // 17.85
  assert.equal(requiredSaudis(3, 30), 1); // 0.9
});
 
test('hiring-only never beats replacement, and replacement always complies', () => {
  for (let n = 5; n <= 300; n++) {
    for (let s = 0; s <= n; s++) {
      for (const r of [30, 35]) {
        const req = requiredSaudis(n, r);
        const rep = Math.max(0, req - s);
        assert.ok(hiresOnly(n, s, r) >= rep);
        assert.ok(s + rep >= requiredSaudis(n, r));
      }
    }
  }
});
 
test('register by: five Saudi working days before Sunday 9 May 2027', () => {
  assert.equal(registerBy('2027-05-09'), '2027-05-02');
  assert.equal(registerBy('2027-05-09', 0), '2027-05-09');
});