توطين مهن إدارة المشاريع 70%: فحص الامتثال بلغة TypeScript

// src/rules.ts
export type OccupationCode = string;
 
export interface QuotaRule {
  decision: string;
  guideIssued: string;   // ISO date
  effectiveFrom: string; // ISO date
  ratePercent: number;   // whole percent, e.g. 70
  minWorkers: number;    // the rule applies from this many workers in scope
  codes: Record<OccupationCode, string>;
  gosiWageFloor: number | null; // SAR per month, null = no floor in the guide
}
 
// Procedural guide issued with Ministerial Decision 41454 (13 Aug 2026)
export const PM_2026: QuotaRule = {
  decision: "41454",
  guideIssued: "2026-08-13",
  effectiveFrom: "2027-02-14",
  ratePercent: 70,
  minWorkers: 3,
  codes: {
    "121314": "Project management manager",
    "214909": "Project management engineer",
    "242108": "Project management specialist",
  },
  gosiWageFloor: null,
};
 
// The 2023 guide for Ministerial Decision 141749, second phase (40%),
// in force since 11/06/1446 AH (about 12 Dec 2024)
export const PM_2023: QuotaRule = {
  decision: "141749",
  guideIssued: "2023-04-02",
  effectiveFrom: "2024-12-12",
  ratePercent: 40,
  minWorkers: 3,
  codes: {
    "121314": "Project management manager",
    "242108": "Project management specialist",
    "2133241": "Project manager",
    "2133231": "Project management office specialist",
    "1216031": "Telecommunications project manager",
    "1217011": "Business services project manager",
    "1216011": "Transport project manager",
  },
  gosiWageFloor: 6000,
};

// src/quota.ts
// Saudis required for a headcount, rounded to the nearest whole number
// (3.5 becomes 4, as in the guide's worked example).
// Integer arithmetic only: 45 * 0.7 is 31.499999999999996 in floating point.
export function requiredSaudis(headcount: number, ratePercent: number): number {
  return Math.floor((headcount * ratePercent + 50) / 100);
}
 
// Replacement: swap non-Saudis for Saudis, headcount stays the same.
export function gapByReplacement(
  headcount: number,
  saudis: number,
  ratePercent: number,
): number {
  return Math.max(0, requiredSaudis(headcount, ratePercent) - saudis);
}
 
// Hiring only: each new Saudi raises both sides of the ratio.
export function gapByHiring(
  headcount: number,
  saudis: number,
  ratePercent: number,
): number {
  if (ratePercent >= 100) {
    return saudis >= headcount ? 0 : Number.POSITIVE_INFINITY;
  }
  let hires = 0;
  while (saudis + hires < requiredSaudis(headcount + hires, ratePercent)) {
    hires += 1;
  }
  return hires;
}

// src/assess.ts
import { QuotaRule } from "./rules";
import { requiredSaudis, gapByReplacement, gapByHiring } from "./quota";
 
export interface Worker {
  id: string;
  entityId: string;        // all branches with the same activity, one owner
  branchId: string;
  saudi: boolean;
  occupationCode: string;  // as registered in Qiwa / GOSI
  doesPmWork: boolean;     // what the person actually does, from the line manager
  gosiWage: number;        // contributory wage, SAR per month
}
 
export type Finding =
  | { kind: "title-mismatch"; workerId: string; saudi: boolean }
  | { kind: "below-wage-floor"; workerId: string; wage: number };
 
export interface EntityResult {
  entityId: string;
  inScope: number;
  saudisCounted: number;
  applies: boolean;
  required: number;
  rate: number;            // percent, one decimal
  byReplacement: number;
  byHiring: number;
  findings: Finding[];
}
 
export function assessEntity(
  entityId: string,
  workers: Worker[],
  rule: QuotaRule,
): EntityResult {
  const mine = workers.filter((w) => w.entityId === entityId);
  const findings: Finding[] = [];
 
  // Duties without the code. For a non-Saudi the guide calls this a breach;
  // a Saudi in the same position is simply not counted.
  for (const w of mine) {
    if (w.doesPmWork && !(w.occupationCode in rule.codes)) {
      findings.push({ kind: "title-mismatch", workerId: w.id, saudi: w.saudi });
    }
  }
 
  // Scope is the registered code AND the actual work.
  const scoped = mine.filter((w) => w.occupationCode in rule.codes && w.doesPmWork);
  const counted = scoped.filter((w) => {
    if (!w.saudi) return false;
    if (rule.gosiWageFloor !== null && w.gosiWage < rule.gosiWageFloor) {
      findings.push({ kind: "below-wage-floor", workerId: w.id, wage: w.gosiWage });
      return false;
    }
    return true;
  });
 
  const n = scoped.length;
  const s = counted.length;
  const applies = n >= rule.minWorkers;
  return {
    entityId,
    inScope: n,
    saudisCounted: s,
    applies,
    required: applies ? requiredSaudis(n, rule.ratePercent) : 0,
    rate: n === 0 ? 0 : Math.round((s / n) * 1000) / 10,
    byReplacement: applies ? gapByReplacement(n, s, rule.ratePercent) : 0,
    byHiring: applies ? gapByHiring(n, s, rule.ratePercent) : 0,
    findings,
  };
}

// src/overlap.ts
import { QuotaRule } from "./rules";
 
// When two decisions cover the same code, the higher rate applies.
// Only decisions already in force on the date are considered.
export function ruleFor(
  code: string,
  onDate: string,
  rules: QuotaRule[],
): QuotaRule | undefined {
  return rules
    .filter((r) => code in r.codes && r.effectiveFrom <= onDate)
    .sort((a, b) => b.ratePercent - a.ratePercent)[0];
}

// src/diff.ts
import { QuotaRule } from "./rules";
import { Worker } from "./assess";
 
export interface RuleDiff {
  codesAdded: string[];
  codesRemoved: string[];
  workersJoining: string[];  // in scope under the new rule only
  workersLeaving: string[];  // in scope under the old rule only
  wageFloorChange: [number | null, number | null];
}
 
export function diffRules(
  oldRule: QuotaRule,
  newRule: QuotaRule,
  workers: Worker[],
): RuleDiff {
  const oldCodes = Object.keys(oldRule.codes);
  const newCodes = Object.keys(newRule.codes);
  const inOld = (w: Worker) => w.occupationCode in oldRule.codes;
  const inNew = (w: Worker) => w.occupationCode in newRule.codes;
  return {
    codesAdded: newCodes.filter((c) => !oldCodes.includes(c)),
    codesRemoved: oldCodes.filter((c) => !newCodes.includes(c)),
    workersJoining: workers.filter((w) => inNew(w) && !inOld(w)).map((w) => w.id),
    workersLeaving: workers.filter((w) => inOld(w) && !inNew(w)).map((w) => w.id),
    wageFloorChange: [oldRule.gosiWageFloor, newRule.gosiWageFloor],
  };
}

// src/plan.ts
import { EntityResult } from "./assess";
 
export function phaseOn(today: string, effectiveFrom: string): "grace" | "enforced" {
  return today < effectiveFrom ? "grace" : "enforced";
}
 
export function daysLeft(today: string, effectiveFrom: string): number {
  const ms = Date.parse(effectiveFrom) - Date.parse(today);
  return Math.max(0, Math.ceil(ms / 86_400_000));
}
 
export function actionPlan(r: EntityResult, today: string, effectiveFrom: string): string[] {
  const lines: string[] = [];
  if (!r.applies) {
    lines.push(`Entity ${r.entityId}: ${r.inScope} in scope, below the threshold. Re-run on every hire.`);
    return lines;
  }
  lines.push(
    `Entity ${r.entityId}: ${r.saudisCounted}/${r.inScope} Saudi (${r.rate}%), ` +
      `${r.required} required.`,
  );
  if (r.byReplacement > 0) {
    lines.push(`Replace ${r.byReplacement}, or hire ${r.byHiring} additional Saudis.`);
    const phase = phaseOn(today, effectiveFrom);
    lines.push(
      phase === "grace"
        ? `${daysLeft(today, effectiveFrom)} days of grace left.`
        : "Grace period over: the entity is in breach now.",
    );
  }
  for (const f of r.findings) {
    if (f.kind === "title-mismatch" && f.saudi) {
      lines.push(`Worker ${f.workerId} is Saudi and not counted: register the right code in Qiwa.`);
    } else if (f.kind === "title-mismatch") {
      lines.push(`Worker ${f.workerId} does project management under another code: fix the role or the code.`);
    } else {
      lines.push(`Worker ${f.workerId} is below the wage floor (SAR ${f.wage}).`);
    }
  }
  return lines;
}

// src/assess.test.ts
import { test } from "node:test";
import assert from "node:assert/strict";
import { PM_2023, PM_2026 } from "./rules";
import { requiredSaudis, gapByReplacement, gapByHiring } from "./quota";
import { assessEntity, Worker } from "./assess";
import { ruleFor } from "./overlap";
import { diffRules } from "./diff";
import { actionPlan, daysLeft } from "./plan";
 
const w = (id: string, saudi: boolean, code = "121314", extra: Partial<Worker> = {}): Worker => ({
  id, entityId: "E1", branchId: "B1", saudi, occupationCode: code,
  doesPmWork: true, gosiWage: 9000, ...extra,
});
 
test("guide example: 5 workers at 70% need 4 Saudis", () => {
  assert.equal(requiredSaudis(5, 70), 4);
  assert.equal(gapByReplacement(5, 2, 70), 2);
  assert.equal(gapByReplacement(5, 5, 70), 0);
});
 
test("rounding is to the nearest whole number", () => {
  assert.equal(requiredSaudis(3, 70), 2);  // 2.1
  assert.equal(requiredSaudis(4, 70), 3);  // 2.8
  assert.equal(requiredSaudis(15, 70), 11); // 10.5
  assert.equal(requiredSaudis(20, 70), 14);
  assert.equal(requiredSaudis(45, 70), 32); // 45 * 0.7 is 31.499999999999996
});
 
test("hiring only needs more people than replacement", () => {
  assert.equal(gapByHiring(5, 2, 70), 4);
  assert.equal(gapByHiring(10, 3, 70), 12);
  assert.equal(gapByHiring(10, 7, 70), 0);
  assert.equal(gapByHiring(3, 1, 100), Number.POSITIVE_INFINITY);
});
 
test("below three workers in scope the decision does not apply", () => {
  const r = assessEntity("E1", [w("a", false), w("b", false)], PM_2026);
  assert.equal(r.applies, false);
  assert.equal(r.byReplacement, 0);
});
 
test("branches of one entity are counted together", () => {
  const ws = [w("a", true), w("b", false, "214909", { branchId: "B2" }), w("c", false, "242108", { branchId: "B3" })];
  const r = assessEntity("E1", ws, PM_2026);
  assert.equal(r.inScope, 3);
  assert.equal(r.required, 2);
  assert.equal(r.byReplacement, 1);
});
 
test("a code without the work is out of scope; work without the code is flagged", () => {
  const ws = [
    w("a", true), w("b", true), w("c", false),
    w("d", false, "121314", { doesPmWork: false }),
    w("e", false, "263101"),
    w("f", true, "263101"),
  ];
  const r = assessEntity("E1", ws, PM_2026);
  assert.equal(r.inScope, 3);
  assert.equal(r.saudisCounted, 2);
  assert.deepEqual(r.findings, [
    { kind: "title-mismatch", workerId: "e", saudi: false },
    { kind: "title-mismatch", workerId: "f", saudi: true },
  ]);
});
 
test("the 2026 guide sets no wage floor; the 2023 one did", () => {
  const ws = [w("a", true, "121314", { gosiWage: 5000 }), w("b", true), w("c", false)];
  assert.equal(assessEntity("E1", ws, PM_2026).saudisCounted, 2);
  const old = assessEntity("E1", ws, PM_2023);
  assert.equal(old.saudisCounted, 1);
  assert.equal(old.findings[0].kind, "below-wage-floor");
});
 
test("diff between the 2023 and 2026 lists", () => {
  const ws = [w("a", true, "214909"), w("b", false, "2133241"), w("c", false, "121314")];
  const d = diffRules(PM_2023, PM_2026, ws);
  assert.deepEqual(d.codesAdded, ["214909"]);
  assert.equal(d.codesRemoved.length, 5);
  assert.deepEqual(d.workersJoining, ["a"]);
  assert.deepEqual(d.workersLeaving, ["b"]);
  assert.deepEqual(d.wageFloorChange, [6000, null]);
});
 
test("higher rate wins only once in force", () => {
  assert.equal(ruleFor("121314", "2026-12-01", [PM_2023, PM_2026])?.decision, "141749");
  assert.equal(ruleFor("121314", "2027-02-14", [PM_2023, PM_2026])?.decision, "41454");
  assert.equal(ruleFor("999999", "2027-02-14", [PM_2026]), undefined);
});
 
test("action plan counts grace days", () => {
  assert.equal(daysLeft("2026-11-16", "2027-02-14"), 90);
  const r = assessEntity("E1", [w("a", true), w("b", false), w("c", false)], PM_2026);
  const plan = actionPlan(r, "2026-11-16", PM_2026.effectiveFrom);
  assert.match(plan[1], /Replace 1, or hire 3/);
  assert.match(plan[2], /90 days/);
  const late = actionPlan(r, "2027-02-14", PM_2026.effectiveFrom);
  assert.match(late[2], /in breach now/);
});