توطين مهنة مشرف مسكن: أداة تحقق بلغة TypeScript

/** Ministerial Decision 62298 of 31 October 2025 and its procedural guide. */
export const HOUSING_SUPERVISOR = {
  decision: '62298',
  issued: '2025-10-31',
  enforcedFrom: '2026-02-01', // issue date plus a three-month grace period
  occupationCode: '515102', // "Housing supervisor" (مشرف مسكن)
  saudiRatePercent: 100,
  minGosiWageSar: 5000, // contributory wage registered with GOSI
  minBeneficiaries: 20, // collective housing for 20 or more people
} as const;
 
/** One collective housing site: a compound, a building, a set of caravans. */
export interface HousingSite {
  readonly id: string;
  readonly beneficiaries: number; // people housed there today
}
 
export interface Worker {
  readonly id: string;
  readonly saudi: boolean;
  readonly occupationCode: string; // as registered in Qiwa
  readonly gosiWageSar: number; // integer riyals, as registered with GOSI
  /** Sites this person supervises in practice, whatever the job title says. */
  readonly supervisesSiteIds: readonly string[];
}

/** Sites that bring the establishment under the decision. */
export function sitesInScope(sites: readonly HousingSite[]): HousingSite[] {
  return sites.filter((s) => s.beneficiaries >= HOUSING_SUPERVISOR.minBeneficiaries);
}
 
/** On or after the enforcement date? ISO dates compare correctly as strings. */
export function isEnforced(onDate: string): boolean {
  return onDate >= HOUSING_SUPERVISOR.enforcedFrom;
}

export type RoleSource = 'title' | 'actual-work' | 'both';
 
/** Is this person a housing supervisor for the decision, and on what evidence? */
export function supervisorRole(w: Worker): RoleSource | null {
  const byTitle = w.occupationCode === HOUSING_SUPERVISOR.occupationCode;
  const byWork = w.supervisesSiteIds.length > 0;
  if (byTitle && byWork) return 'both';
  if (byTitle) return 'title';
  if (byWork) return 'actual-work';
  return null;
}
 
export type Finding =
  | { kind: 'non-saudi'; workerId: string; role: RoleSource }
  | { kind: 'wage-below-floor'; workerId: string; shortfallSar: number }
  | { kind: 'title-mismatch'; workerId: string };
 
/** Everything wrong with one worker. An empty list means this person is fine. */
export function checkWorker(w: Worker): Finding[] {
  const role = supervisorRole(w);
  if (role === null) return [];
  if (!w.saudi) return [{ kind: 'non-saudi', workerId: w.id, role }];
  const out: Finding[] = [];
  const shortfall = HOUSING_SUPERVISOR.minGosiWageSar - w.gosiWageSar;
  if (shortfall > 0) out.push({ kind: 'wage-below-floor', workerId: w.id, shortfallSar: shortfall });
  if (role === 'actual-work') out.push({ kind: 'title-mismatch', workerId: w.id });
  return out;
}

export interface Assessment {
  readonly onDate: string;
  readonly inScope: boolean;
  readonly enforced: boolean;
  readonly sitesInScope: readonly string[];
  readonly findings: readonly Finding[];
  /** In-scope sites that no compliant Saudi supervises. Information, not a breach. */
  readonly sitesWithoutCompliantSupervisor: readonly string[];
  readonly compliant: boolean;
}
 
export function assess(
  onDate: string,
  sites: readonly HousingSite[],
  workers: readonly Worker[],
): Assessment {
  const scoped = sitesInScope(sites).map((s) => s.id);
  const inScope = scoped.length > 0;
  const findings = inScope ? workers.flatMap(checkWorker) : [];
 
  const breached = new Set(
    findings.filter((f) => f.kind !== 'title-mismatch').map((f) => f.workerId),
  );
  // A non-Saudi supervisor always has a finding, so "not breached" means a compliant Saudi.
  const covered = new Set(
    workers.filter((w) => !breached.has(w.id)).flatMap((w) => w.supervisesSiteIds),
  );
 
  return {
    onDate,
    inScope,
    enforced: isEnforced(onDate),
    sitesInScope: scoped,
    findings,
    sitesWithoutCompliantSupervisor: scoped.filter((id) => !covered.has(id)),
    compliant: findings.every((f) => f.kind === 'title-mismatch'),
  };
}

export interface ActionPlan {
  /** Saudi supervisors to recruit, one per non-Saudi doing the job today. */
  readonly saudiHires: number;
  /** Non-Saudis whose supervision duties must stop, whatever their title. */
  readonly dutiesToReassign: readonly string[];
  /** Monthly increase in registered GOSI wages, in riyals. */
  readonly wageTopUpSarPerMonth: number;
  /** Saudis to re-register in Qiwa under code 515102. */
  readonly qiwaTitleChanges: readonly string[];
}
 
export function actionPlan(a: Assessment): ActionPlan {
  const nonSaudi = a.findings.filter((f) => f.kind === 'non-saudi');
  let topUp = 0;
  for (const f of a.findings) if (f.kind === 'wage-below-floor') topUp += f.shortfallSar;
  return {
    saudiHires: nonSaudi.length,
    dutiesToReassign: nonSaudi.map((f) => f.workerId),
    wageTopUpSarPerMonth: topUp,
    qiwaTitleChanges: a.findings
      .filter((f) => f.kind === 'title-mismatch')
      .map((f) => f.workerId),
  };
}

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { actionPlan, assess, checkWorker, type HousingSite, type Worker } from './engine.ts';
 
const sites: HousingSite[] = [
  { id: 'jubail-a', beneficiaries: 240 },
  { id: 'jubail-b', beneficiaries: 20 },
  { id: 'dammam-villa', beneficiaries: 19 },
];
 
function w(id: string, over: Partial<Worker> = {}): Worker {
  return { id, saudi: true, occupationCode: '515102', gosiWageSar: 5000,
    supervisesSiteIds: [], ...over };
}
 
test('scope starts at 20 beneficiaries, not 21', () => {
  const a = assess('2026-11-11', sites, []);
  assert.deepEqual(a.sitesInScope, ['jubail-a', 'jubail-b']);
  assert.equal(a.inScope, true);
});
 
test('an establishment with only small sites is out of scope', () => {
  const a = assess('2026-11-11', [{ id: 'v', beneficiaries: 19 }],
    [w('x', { saudi: false })]);
  assert.equal(a.inScope, false);
  assert.equal(a.findings.length, 0);
  assert.equal(a.compliant, true);
});
 
test('SAR 5,000 exactly counts; SAR 4,999 does not', () => {
  assert.deepEqual(checkWorker(w('ok')), []);
  assert.deepEqual(checkWorker(w('low', { gosiWageSar: 4999 })),
    [{ kind: 'wage-below-floor', workerId: 'low', shortfallSar: 1 }]);
});
 
test('a non-Saudi doing the work under another title is a breach', () => {
  const f = checkWorker(w('n', { saudi: false, occupationCode: '962101',
    supervisesSiteIds: ['jubail-a'] }));
  assert.deepEqual(f, [{ kind: 'non-saudi', workerId: 'n', role: 'actual-work' }]);
});
 
test('a Saudi doing the work under another title is a title fix, not a breach', () => {
  const a = assess('2026-11-11', sites,
    [w('s', { occupationCode: '432101', supervisesSiteIds: ['jubail-a', 'jubail-b'] })]);
  assert.equal(a.compliant, true);
  assert.deepEqual(actionPlan(a).qiwaTitleChanges, ['s']);
  assert.deepEqual(a.sitesWithoutCompliantSupervisor, []);
});
 
test('the plan adds up hires, duties and wage top-ups', () => {
  const a = assess('2026-11-11', sites, [
    w('a', { gosiWageSar: 4000, supervisesSiteIds: ['jubail-a'] }),
    w('b', { saudi: false, supervisesSiteIds: ['jubail-b'] }),
    w('c', { gosiWageSar: 4500 }),
  ]);
  assert.equal(a.compliant, false);
  assert.deepEqual(a.sitesWithoutCompliantSupervisor, ['jubail-a', 'jubail-b']);
  assert.deepEqual(actionPlan(a), { saudiHires: 1, dutiesToReassign: ['b'],
    wageTopUpSarPerMonth: 1500, qiwaTitleChanges: [] });
});
 
test('enforcement starts on 1 February 2026', () => {
  assert.equal(assess('2026-01-31', sites, []).enforced, false);
  assert.equal(assess('2026-02-01', sites, []).enforced, true);
});

npx tsx --test engine.test.ts