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

// nitaqat/types.ts
export const BAND_ORDER = ['lowGreen', 'midGreen', 'highGreen', 'platinum'] as const;
export type BandKey = (typeof BAND_ORDER)[number];
 
/** Red is not a threshold — it is where you are when you clear none of them. */
export type BandStatus = BandKey | 'red';
 
export const NITAQAT_YEARS = [2026, 2027, 2028] as const;
export type NitaqatYear = (typeof NITAQAT_YEARS)[number];
 
/**
 * Annex 1 gives, per activity and band, one curve constant and one levelling
 * constant per commitment year.
 */
export type BandConstants = {
  m: number;
  c: readonly [number, number, number];
};
 
export type Activity = {
  id: string;
  label: string;
  bands: Record<BandKey, BandConstants>;
};

// nitaqat/annex1.ts
import type { Activity } from './types';
 
export const ACTIVITIES: Record<string, Activity> = {
  manufacturing: {
    id: 'manufacturing',
    label: 'الصناعات',
    bands: {
      lowGreen: { m: 1.68, c: [15.08, 18.08, 21.08] },
      midGreen: { m: 1.87, c: [21.87, 24.87, 27.87] },
      highGreen: { m: 2.08, c: [23.97, 26.97, 29.97] },
      platinum: { m: 2.08, c: [29.87, 32.87, 35.87] },
    },
  },
  construction: {
    id: 'construction',
    label: 'مقاولات التشييد والبناء',
    bands: {
      lowGreen: { m: -0.37, c: [14.17, 16.17, 18.17] },
      midGreen: { m: -0.37, c: [16.17, 18.17, 20.17] },
      highGreen: { m: 0, c: [17.5, 19.5, 21.5] },
      platinum: { m: 0, c: [22.5, 24.5, 26.5] },
    },
  },
  itInfrastructure: {
    id: 'itInfrastructure',
    label: 'البنية التحتية لتقنية المعلومات',
    bands: {
      lowGreen: { m: 3.61, c: [17.77, 19.77, 21.77] },
      midGreen: { m: 3.61, c: [24.64, 26.64, 28.64] },
      highGreen: { m: 3.61, c: [40, 42, 44] },
      platinum: { m: 3.61, c: [50, 52, 54] },
    },
  },
};

// nitaqat/thresholds.ts
import { BAND_ORDER, NITAQAT_YEARS } from './types';
import type { Activity, BandKey, BandStatus, NitaqatYear } from './types';
 
/** The curve applies from six workers up; below that a flat rule governs. */
export const CURVE_MIN_HEADCOUNT = 6;
 
export function bandThresholds(
  activity: Activity,
  totalWorkforce: number,
  year: NitaqatYear = 2026,
): Record<BandKey, number> {
  const yearIndex = Math.max(0, NITAQAT_YEARS.indexOf(year));
  // ln(0) is -Infinity and ln of a fraction is negative, so floor the size.
  const ln = Math.log(Math.max(totalWorkforce, 1));
 
  const out = {} as Record<BandKey, number>;
  for (const band of BAND_ORDER) {
    const { m, c } = activity.bands[band];
    // Clamped: the curve is an empirical fit, not an identity. A negative
    // constant at a small headcount can produce a faithful negative percentage.
    out[band] = Math.min(100, Math.max(0, m * ln + c[yearIndex]));
  }
  return out;
}
 
/** The highest band a rate actually clears. */
export function classifyBand(
  rate: number,
  thresholds: Record<BandKey, number>,
): BandStatus {
  let status: BandStatus = 'red';
  for (const band of BAND_ORDER) {
    if (rate >= thresholds[band]) status = band;
  }
  return status;
}

// nitaqat/small-entity.ts
import { CURVE_MIN_HEADCOUNT } from './thresholds';
 
export const SMALL_ENTITY_SAUDI_REQUIREMENT = 1;
 
export type SmallEntityCheck = {
  applies: true;
  met: boolean;
  required: number;
} | null;
 
/** Null once the curve takes over — the caller should read the band instead. */
export function smallEntityCheck(total: number, saudis: number): SmallEntityCheck {
  if (total === 0 || total >= CURVE_MIN_HEADCOUNT) return null;
  return {
    applies: true,
    met: saudis >= SMALL_ENTITY_SAUDI_REQUIREMENT,
    required: SMALL_ENTITY_SAUDI_REQUIREMENT,
  };
}

// nitaqat/gap.ts
export type Gap = {
  hiresNeeded: number;
  nonSaudiReduction: number;
};
 
export function gapTo(targetPercent: number, saudis: number, total: number): Gap {
  const t = targetPercent / 100;
  if (t >= 1) throw new RangeError('a 100% target has no finite hiring solution');
 
  const rate = total === 0 ? 0 : (saudis / total) * 100;
  if (rate >= targetPercent) return { hiresNeeded: 0, nonSaudiReduction: 0 };
 
  // Hiring lifts both terms: (saudis + x) / (total + x) >= t
  const hiresNeeded = Math.max(0, Math.ceil((t * total - saudis) / (1 - t)));
 
  // The other lever — shrink the denominator: saudis / (saudis + y) >= t
  const nonSaudis = total - saudis;
  const allowedNonSaudis = t === 0 ? Infinity : Math.floor(saudis / t) - saudis;
  const nonSaudiReduction = Number.isFinite(allowedNonSaudis)
    ? Math.max(0, nonSaudis - Math.max(0, allowedNonSaudis))
    : 0;
 
  return { hiresNeeded, nonSaudiReduction };
}

// nitaqat/countable.ts
export type EmployeeRecord = {
  id: string;
  nationality: 'SA' | 'NON_SA';
  /** Qiwa contract authentication state, mirrored from the platform. */
  contractAuthenticated: boolean;
  /** Whether GOSI shows an open contribution record for the period. */
  gosiActive: boolean;
  /** For the cases the programme weights differently than one head. */
  weight?: number;
};
 
export type CountableWorkforce = {
  /** Saudis that actually count toward the ratio. */
  saudis: number;
  /** Everyone on an open GOSI record, counted toward Saudization or not. */
  total: number;
  /** Saudis sitting in the denominator but contributing nothing to the numerator. */
  uncountedSaudis: string[];
};
 
export function countableWorkforce(roster: EmployeeRecord[]): CountableWorkforce {
  let saudis = 0;
  let total = 0;
  const uncountedSaudis: string[] = [];
 
  for (const e of roster) {
    // No open GOSI contribution record, no place in either term.
    if (!e.gosiActive) continue;
 
    const weight = e.weight ?? 1;
    total += weight;
 
    if (e.nationality !== 'SA') continue;
 
    // Since 15 April 2026 a Saudi whose Qiwa contract is not authenticated
    // still occupies the denominator but adds nothing to the numerator.
    if (!e.contractAuthenticated) {
      uncountedSaudis.push(e.id);
      continue;
    }
    saudis += weight;
  }
 
  return { saudis, total, uncountedSaudis };
}

// nitaqat/forecast.ts
import { bandThresholds, classifyBand } from './thresholds';
import { NITAQAT_YEARS } from './types';
import type { Activity, BandStatus, NitaqatYear } from './types';
 
export type YearOutlook = {
  year: NitaqatYear;
  rate: number;
  band: BandStatus;
  lowGreenThreshold: number;
};
 
/** One unchanging workforce, read against each published year's constants. */
export function ratchetOutlook(
  activity: Activity,
  saudis: number,
  total: number,
): YearOutlook[] {
  const rate = total === 0 ? 0 : (saudis / total) * 100;
 
  return NITAQAT_YEARS.map((year) => {
    const thresholds = bandThresholds(activity, total, year);
    return {
      year,
      rate: Number(rate.toFixed(2)),
      band: classifyBand(rate, thresholds),
      lowGreenThreshold: Number(thresholds.lowGreen.toFixed(2)),
    };
  });
}

// nitaqat/alerts.ts
import { bandThresholds, classifyBand } from './thresholds';
import { ratchetOutlook } from './forecast';
import { BAND_ORDER } from './types';
import type { Activity, BandKey, NitaqatYear } from './types';
 
export type Alert = {
  level: 'info' | 'warn' | 'critical';
  code: string;
  message: string;
};
 
/** Percentage points between the current rate and the floor it sits on. */
export function bandBuffer(
  rate: number,
  thresholds: Record<BandKey, number>,
): number {
  const current = classifyBand(rate, thresholds);
  if (current === 'red') return 0;
  return Number((rate - thresholds[current]).toFixed(2));
}
 
export function reviewCompliance(input: {
  activity: Activity;
  saudis: number;
  total: number;
  uncountedSaudis: string[];
  year?: NitaqatYear;
  bufferPoints?: number;
}): Alert[] {
  const {
    activity, saudis, total, uncountedSaudis,
    year = 2026, bufferPoints = 2,
  } = input;
 
  const alerts: Alert[] = [];
  const rate = total === 0 ? 0 : (saudis / total) * 100;
  const thresholds = bandThresholds(activity, total, year);
  const band = classifyBand(rate, thresholds);
  const buffer = bandBuffer(rate, thresholds);
 
  if (band === 'red') {
    alerts.push({
      level: 'critical',
      code: 'BAND_RED',
      message: `Red band: ${rate.toFixed(2)}% against a ${thresholds.lowGreen.toFixed(2)}% floor.`,
    });
  } else if (buffer < bufferPoints) {
    alerts.push({
      level: 'warn',
      code: 'BAND_MARGIN_THIN',
      message: `Only ${buffer} points above the ${band} floor — one departure may cost the band.`,
    });
  }
 
  if (uncountedSaudis.length > 0) {
    alerts.push({
      level: 'warn',
      code: 'CONTRACTS_UNAUTHENTICATED',
      message: `${uncountedSaudis.length} Saudi employees have no authenticated Qiwa contract and are not counting.`,
    });
  }
 
  const falls = ratchetOutlook(activity, saudis, total).find((o) => o.band === 'red');
  if (falls && band !== 'red') {
    alerts.push({
      level: 'critical',
      code: 'RATCHET_FALL',
      message: `Unchanged, this workforce falls to red in ${falls.year}.`,
    });
  }
 
  return alerts;
}

// nitaqat/engine.test.ts
import { describe, expect, it } from 'vitest';
import { ACTIVITIES } from './annex1';
import { bandThresholds, classifyBand } from './thresholds';
import { gapTo } from './gap';
import { ratchetOutlook } from './forecast';
import { countableWorkforce } from './countable';
 
describe('thresholds', () => {
  it('computes the 2026 manufacturing curve at 100 employees', () => {
    const t = bandThresholds(ACTIVITIES.manufacturing, 100, 2026);
    expect(t.lowGreen).toBeCloseTo(22.82, 2);
    expect(t.midGreen).toBeCloseTo(30.48, 2);
    expect(t.highGreen).toBeCloseTo(33.55, 2);
    expect(t.platinum).toBeCloseTo(39.45, 2);
  });
 
  it('eases with size where the curve constant is negative', () => {
    const small = bandThresholds(ACTIVITIES.construction, 10, 2026).lowGreen;
    const large = bandThresholds(ACTIVITIES.construction, 1000, 2026).lowGreen;
    expect(small).toBeCloseTo(13.32, 2);
    expect(large).toBeCloseTo(11.61, 2);
    expect(large).toBeLessThan(small);
  });
 
  it('separates two activities that share a headcount', () => {
    const it = bandThresholds(ACTIVITIES.itInfrastructure, 30, 2026).lowGreen;
    const con = bandThresholds(ACTIVITIES.construction, 30, 2026).lowGreen;
    expect(it).toBeCloseTo(30.05, 2);
    expect(con).toBeCloseTo(12.91, 2);
  });
 
  it('does not call an empty establishment platinum', () => {
    const t = bandThresholds(ACTIVITIES.manufacturing, 0, 2026);
    expect(Number.isFinite(t.lowGreen)).toBe(true);
    expect(classifyBand(0, t)).toBe('red');
  });
});
 
describe('the gap', () => {
  it('accounts for the denominator growing with each hire', () => {
    expect(gapTo(30.48, 25, 100).hiresNeeded).toBe(8);
  });
 
  it('offers the reduction path as well', () => {
    expect(gapTo(30.48, 25, 100).nonSaudiReduction).toBe(18);
  });
 
  it('returns zero once the target is already met', () => {
    expect(gapTo(20, 25, 100)).toEqual({ hiresNeeded: 0, nonSaudiReduction: 0 });
  });
});
 
describe('the ratchet', () => {
  it('drops a static workforce a band without anyone moving', () => {
    const outlook = ratchetOutlook(ACTIVITIES.manufacturing, 25, 100);
    expect(outlook[0].band).toBe('lowGreen');
    expect(outlook[1].band).toBe('red');
    expect(outlook[1].lowGreenThreshold).toBeCloseTo(25.82, 2);
  });
});
 
describe('countable workforce', () => {
  it('keeps an unauthenticated Saudi in the denominator only', () => {
    const w = countableWorkforce([
      { id: 'a', nationality: 'SA', contractAuthenticated: true, gosiActive: true },
      { id: 'b', nationality: 'SA', contractAuthenticated: false, gosiActive: true },
      { id: 'c', nationality: 'NON_SA', contractAuthenticated: true, gosiActive: true },
    ]);
    expect(w.saudis).toBe(1);
    expect(w.total).toBe(3);
    expect(w.uncountedSaudis).toEqual(['b']);
  });
});