dabke 0.78.0

package/src/cpsat/rules/scoping.ts

@@ -0,0 +1,340 @@
+import * as z from "zod";
+import type { DayOfWeek } from "../../types.js";
+import type { SchedulingEmployee } from "../types.js";
+
+export type EntityScope =
+  | { type: "global" }
+  | { type: "employees"; employeeIds: string[] }
+  | { type: "roles"; roleIds: string[] }
+  | { type: "skills"; skillIds: string[] };
+
+export type TimeScope =
+  | { type: "always" }
+  | { type: "dateRange"; start: string; end: string }
+  | { type: "specificDates"; dates: string[] }
+  | { type: "dayOfWeek"; days: DayOfWeek[] }
+  | {
+      type: "recurring";
+      periods: {
+        name: string;
+        startMonth: number;
+        startDay: number;
+        endMonth: number;
+        endDay: number;
+      }[];
+    };
+
+export interface RuleScope {
+  entity: EntityScope;
+  time?: TimeScope;
+}
+
+export interface ScopeConfig {
+  employeeIds?: string[];
+  roleIds?: string[];
+  skillIds?: string[];
+  dateRange?: { start: string; end: string };
+  specificDates?: string[];
+  dayOfWeek?: DayOfWeek[];
+  recurringPeriods?: {
+    name: string;
+    startMonth: number;
+    startDay: number;
+    endMonth: number;
+    endDay: number;
+  }[];
+}
+
+type SupportedEntities = ReadonlyArray<EntityKey>;
+type SupportedTimes = ReadonlyArray<TimeKey>;
+
+const dayOfWeekSchema = z.union([
+  z.literal("monday"),
+  z.literal("tuesday"),
+  z.literal("wednesday"),
+  z.literal("thursday"),
+  z.literal("friday"),
+  z.literal("saturday"),
+  z.literal("sunday"),
+]);
+
+type EntityKey = "employees" | "roles" | "skills";
+type TimeKey = "dateRange" | "specificDates" | "dayOfWeek" | "recurring";
+
+type EntityScopeShape<T extends readonly EntityKey[]> = ("employees" extends T[number]
+  ? { employeeIds: z.ZodOptional<z.ZodArray<z.ZodString>> }
+  : {}) &
+  ("roles" extends T[number] ? { roleIds: z.ZodOptional<z.ZodArray<z.ZodString>> } : {}) &
+  ("skills" extends T[number] ? { skillIds: z.ZodOptional<z.ZodArray<z.ZodString>> } : {});
+
+type TimeScopeShape<T extends readonly TimeKey[]> = ("dateRange" extends T[number]
+  ? {
+      dateRange: z.ZodOptional<
+        z.ZodObject<{
+          start: z.ZodString;
+          end: z.ZodString;
+        }>
+      >;
+    }
+  : {}) &
+  ("specificDates" extends T[number]
+    ? { specificDates: z.ZodOptional<z.ZodArray<z.ZodString>> }
+    : {}) &
+  ("dayOfWeek" extends T[number]
+    ? { dayOfWeek: z.ZodOptional<z.ZodArray<typeof dayOfWeekSchema>> }
+    : {}) &
+  ("recurring" extends T[number]
+    ? {
+        recurringPeriods: z.ZodOptional<
+          z.ZodArray<
+            z.ZodObject<{
+              name: z.ZodString;
+              startMonth: z.ZodNumber;
+              startDay: z.ZodNumber;
+              endMonth: z.ZodNumber;
+              endDay: z.ZodNumber;
+            }>
+          >
+        >;
+      }
+    : {});
+
+const timeScopeSchema = <T extends readonly TimeKey[]>(supported: T) =>
+  ({
+    ...(supported.includes("dateRange")
+      ? {
+          dateRange: z
+            .object({
+              start: z.iso.date(),
+              end: z.iso.date(),
+            })
+            .optional(),
+        }
+      : {}),
+    ...(supported.includes("specificDates")
+      ? { specificDates: z.array(z.iso.date()).optional() }
+      : {}),
+    ...(supported.includes("dayOfWeek") ? { dayOfWeek: z.array(dayOfWeekSchema).optional() } : {}),
+    ...(supported.includes("recurring")
+      ? {
+          recurringPeriods: z
+            .array(
+              z.object({
+                name: z.string(),
+                startMonth: z.number(),
+                startDay: z.number(),
+                endMonth: z.number(),
+                endDay: z.number(),
+              }),
+            )
+            .optional(),
+        }
+      : {}),
+  }) as TimeScopeShape<T>;
+
+const entityScopeSchema = <T extends readonly EntityKey[]>(supported: T) =>
+  ({
+    ...(supported.includes("employees") ? { employeeIds: z.array(z.string()).optional() } : {}),
+    ...(supported.includes("roles") ? { roleIds: z.array(z.string()).optional() } : {}),
+    ...(supported.includes("skills") ? { skillIds: z.array(z.string()).optional() } : {}),
+  }) as EntityScopeShape<T>;
+
+type ScopedShape<
+  T extends z.ZodRawShape,
+  TEntities extends readonly EntityKey[],
+  TTimes extends readonly TimeKey[],
+> = T & EntityScopeShape<TEntities> & TimeScopeShape<TTimes>;
+type ScopedSchema<
+  T extends z.ZodRawShape,
+  TEntities extends readonly EntityKey[],
+  TTimes extends readonly TimeKey[],
+> = z.ZodObject<ScopedShape<T, TEntities, TTimes>>;
+type ScopedSchemaWithRefinement<
+  T extends z.ZodRawShape,
+  TEntities extends readonly EntityKey[],
+  TTimes extends readonly TimeKey[],
+> = ReturnType<ScopedSchema<T, TEntities, TTimes>["superRefine"]>;
+
+export const withScopes = <
+  T extends z.ZodRawShape,
+  TEntities extends SupportedEntities,
+  TTimes extends SupportedTimes,
+>(
+  base: z.ZodObject<T>,
+  opts: { entities: TEntities; times: TTimes },
+): ScopedSchemaWithRefinement<T, TEntities, TTimes> => {
+  const entityFields = entityScopeSchema(opts.entities);
+  const timeFields = timeScopeSchema(opts.times);
+
+  const extended = base.extend({
+    ...entityFields,
+    ...timeFields,
+  }) as ScopedSchema<T, TEntities, TTimes>;
+
+  type ExtendedOutput = z.output<typeof extended>;
+
+  const refined = extended.superRefine((val: ExtendedOutput, ctx) => {
+    const entityKeys = ["employeeIds", "roleIds", "skillIds"] as const;
+    const activeEntities = entityKeys.filter((key) => {
+      const value = (val as Record<(typeof entityKeys)[number], unknown>)[key];
+      return Array.isArray(value) && value.length > 0;
+    });
+    if (activeEntities.length > 1) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "Only one of employeeIds/roleIds/skillIds is allowed",
+      });
+    }
+
+    const timeKeys = ["dateRange", "specificDates", "dayOfWeek", "recurringPeriods"] as const;
+    const activeTimes = timeKeys.filter((key) => {
+      const value = (val as Record<(typeof timeKeys)[number], unknown>)[key];
+      if (!value) return false;
+      if (key === "dateRange") return true;
+      return Array.isArray(value) && value.length > 0;
+    });
+    if (activeTimes.length > 1) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "Only one of dateRange/specificDates/dayOfWeek/recurringPeriods is allowed",
+      });
+    }
+  });
+
+  return refined;
+};
+
+export const normalizeScope = (
+  raw: {
+    employeeIds?: string[];
+    roleIds?: string[];
+    skillIds?: string[];
+    dateRange?: { start: string; end: string };
+    specificDates?: string[];
+    dayOfWeek?: DayOfWeek[];
+    recurringPeriods?: {
+      name: string;
+      startMonth: number;
+      startDay: number;
+      endMonth: number;
+      endDay: number;
+    }[];
+  },
+  employees: SchedulingEmployee[],
+): RuleScope => {
+  const employeeSet = new Set(employees.map((e) => e.id));
+
+  // Check if scopes were explicitly provided (even if empty arrays)
+  const hasExplicitEmployeeIds = raw.employeeIds !== undefined && raw.employeeIds.length > 0;
+  const hasExplicitRoleIds = raw.roleIds !== undefined && raw.roleIds.length > 0;
+  const hasExplicitSkillIds = raw.skillIds !== undefined && raw.skillIds.length > 0;
+
+  const roleIds = raw.roleIds ?? [];
+  const skillIds = raw.skillIds ?? [];
+
+  // Filter employee IDs to only those that exist
+  const filteredEmployees = hasExplicitEmployeeIds
+    ? raw.employeeIds!.filter((id) => employeeSet.has(id))
+    : [];
+
+  let entity: EntityScope;
+  if (hasExplicitEmployeeIds) {
+    // If employeeIds was explicitly provided, preserve that scope type
+    // even if all IDs were filtered out (matched no employees).
+    // This prevents a rule intended for specific employees from
+    // accidentally becoming a global rule affecting everyone.
+    entity = { type: "employees", employeeIds: filteredEmployees };
+  } else if (hasExplicitRoleIds) {
+    entity = { type: "roles", roleIds };
+  } else if (hasExplicitSkillIds) {
+    entity = { type: "skills", skillIds };
+  } else {
+    entity = { type: "global" };
+  }
+
+  let time: TimeScope | undefined;
+  if (raw.dateRange) {
+    time = {
+      type: "dateRange",
+      start: raw.dateRange.start,
+      end: raw.dateRange.end,
+    };
+  } else if (raw.specificDates && raw.specificDates.length > 0) {
+    time = { type: "specificDates", dates: raw.specificDates };
+  } else if (raw.dayOfWeek && raw.dayOfWeek.length > 0) {
+    time = { type: "dayOfWeek", days: raw.dayOfWeek };
+  } else if (raw.recurringPeriods && raw.recurringPeriods.length > 0) {
+    time = { type: "recurring", periods: raw.recurringPeriods };
+  }
+
+  return { entity, ...(time ? { time } : {}) };
+};
+
+export const specificity = (scope: EntityScope): number => {
+  switch (scope.type) {
+    case "employees":
+      return 4;
+    case "roles":
+      return 3;
+    case "skills":
+      return 2;
+    case "global":
+    default:
+      return 1;
+  }
+};
+
+export const effectiveEmployeeIds = (
+  scope: EntityScope,
+  employees: SchedulingEmployee[],
+): string[] => {
+  const ids = employees.map((e) => e.id);
+  const idSet = new Set(ids);
+
+  switch (scope.type) {
+    case "employees":
+      return scope.employeeIds.filter((id) => idSet.has(id));
+    default:
+      return ids;
+  }
+};
+
+export const subtractIds = (ids: string[], assigned: Set<string>): string[] =>
+  ids.filter((id) => !assigned.has(id));
+
+/**
+ * Creates a stable key for a time scope to use in grouping.
+ * Rules with different time scope keys don't compete for deduplication.
+ */
+export const timeScopeKey = (time: TimeScope | undefined): string => {
+  if (!time) return "always";
+  switch (time.type) {
+    case "always":
+      return "always";
+    case "dateRange":
+      return `dateRange:${time.start}:${time.end}`;
+    case "specificDates":
+      return `specificDates:${[...time.dates].toSorted().join(",")}`;
+    case "dayOfWeek":
+      return `dayOfWeek:${[...time.days].toSorted().join(",")}`;
+    case "recurring":
+      return `recurring:${time.periods.map((p) => `${p.startMonth}-${p.startDay}:${p.endMonth}-${p.endDay}`).join(";")}`;
+  }
+};
+
+/**
+ * Creates a stable key for an entity scope type.
+ * Used to prevent merging different scope types during resolution.
+ */
+export const entityScopeTypeKey = (entity: EntityScope): string => {
+  switch (entity.type) {
+    case "employees":
+      return "employees";
+    case "roles":
+      return `roles:${entity.roleIds.toSorted().join(",")}`;
+    case "skills":
+      return `skills:${entity.skillIds.toSorted().join(",")}`;
+    case "global":
+      return "global";
+  }
+};

package/src/cpsat/rules/time-off.ts

@@ -0,0 +1,336 @@
+import * as z from "zod";
+import type { TimeOfDay } from "../../types.js";
+import type { CompilationRule, RuleValidationContext } from "../model-builder.js";
+import type { ResolvedShiftAssignment } from "../response.js";
+import type { SchedulingEmployee } from "../types.js";
+import {
+  normalizeEndMinutes,
+  parseDayString,
+  priorityToPenalty,
+  timeOfDayToMinutes,
+} from "../utils.js";
+import type { ValidationReporter } from "../validation-reporter.js";
+import { normalizeScope, withScopes, type RuleScope } from "./scoping.js";
+
+const timeOfDaySchema = z.object({
+  hours: z.number().int().min(0).max(23),
+  minutes: z.number().int().min(0).max(59),
+});
+
+const TimeOffSchema = withScopes(
+  z.object({
+    priority: z.union([
+      z.literal("LOW"),
+      z.literal("MEDIUM"),
+      z.literal("HIGH"),
+      z.literal("MANDATORY"),
+    ]),
+    startTime: timeOfDaySchema.optional(),
+    endTime: timeOfDaySchema.optional(),
+  }),
+  {
+    entities: ["employees", "roles", "skills"],
+    times: ["dateRange", "specificDates", "dayOfWeek", "recurring"],
+  },
+)
+  .refine(
+    (config) => {
+      const hasStartTime = config.startTime !== undefined;
+      const hasEndTime = config.endTime !== undefined;
+      return hasStartTime === hasEndTime;
+    },
+    {
+      message: "Both startTime and endTime must be provided together for partial day time-off",
+    },
+  )
+  .refine(
+    (config) => {
+      return !!(
+        config.dateRange ||
+        (config.specificDates && config.specificDates.length > 0) ||
+        (config.dayOfWeek && config.dayOfWeek.length > 0) ||
+        (config.recurringPeriods && config.recurringPeriods.length > 0)
+      );
+    },
+    {
+      message:
+        "Must provide time scoping (dateRange, specificDates, dayOfWeek, or recurringPeriods)",
+    },
+  );
+
+export type TimeOffConfig = z.infer<typeof TimeOffSchema>;
+
+/**
+ * Blocks or penalizes assignments during specified time periods.
+ *
+ * Supports entity scoping (people, roles, skills) and time scoping
+ * (date ranges, specific dates, days of week, recurring periods).
+ * Optionally supports partial-day time-off with startTime/endTime.
+ *
+ * @example Full day vacation
+ * ```ts
+ * createTimeOffRule({
+ *   employeeIds: ["alice"],
+ *   dateRange: { start: "2024-02-01", end: "2024-02-05" },
+ *   priority: "MANDATORY",
+ * });
+ * ```
+ *
+ * @example Every Wednesday afternoon off for students
+ * ```ts
+ * createTimeOffRule({
+ *   roleIds: ["student"],
+ *   dayOfWeek: ["wednesday"],
+ *   startTime: { hours: 14, minutes: 0 },
+ *   endTime: { hours: 23, minutes: 59 },
+ *   priority: "MANDATORY",
+ * });
+ * ```
+ *
+ * @example Specific date, partial day
+ * ```ts
+ * createTimeOffRule({
+ *   employeeIds: ["bob"],
+ *   specificDates: ["2024-03-15"],
+ *   startTime: { hours: 16, minutes: 0 },
+ *   endTime: { hours: 23, minutes: 59 },
+ *   priority: "MANDATORY",
+ * });
+ * ```
+ */
+export function createTimeOffRule(config: TimeOffConfig): CompilationRule {
+  const parsed = TimeOffSchema.parse(config);
+  const { priority, startTime, endTime } = parsed;
+
+  const fullDayStart: TimeOfDay = { hours: 0, minutes: 0 };
+  const fullDayEnd: TimeOfDay = { hours: 23, minutes: 59 };
+  const timeWindowStart = startTime ?? fullDayStart;
+  const timeWindowEnd = endTime ?? fullDayEnd;
+
+  return {
+    compile(builder) {
+      const scope = normalizeScope(parsed, builder.employees);
+      const targetEmployees = resolveEmployees(scope, builder.employees);
+      if (targetEmployees.length === 0) return;
+
+      const activeDays = resolveActiveDays(scope, builder.days);
+      if (activeDays.length === 0) return;
+
+      for (const emp of targetEmployees) {
+        for (const day of activeDays) {
+          // Report exclusion for coverage analysis (MANDATORY only)
+          if (priority === "MANDATORY") {
+            builder.reporter.excludeFromCoverage({
+              employeeId: emp.id,
+              day,
+              startTime: timeWindowStart,
+              endTime: timeWindowEnd,
+            });
+          }
+
+          for (const pattern of builder.shiftPatterns) {
+            if (!builder.canAssign(emp, pattern)) continue;
+            if (!builder.patternAvailableOnDay(pattern, day)) continue;
+
+            if (startTime && endTime) {
+              if (!shiftOverlapsTimeWindow(pattern, startTime, endTime)) {
+                continue;
+              }
+            }
+
+            const assignVar = builder.assignment(emp.id, pattern.id, day);
+
+            if (priority === "MANDATORY") {
+              builder.addLinear([{ var: assignVar, coeff: 1 }], "==", 0);
+            } else {
+              builder.addSoftLinear(
+                [{ var: assignVar, coeff: 1 }],
+                "<=",
+                0,
+                priorityToPenalty(priority),
+              );
+            }
+          }
+        }
+      }
+    },
+
+    validate(
+      assignments: ResolvedShiftAssignment[],
+      reporter: ValidationReporter,
+      context: RuleValidationContext,
+    ) {
+      // MANDATORY time-off is a hard constraint - can't be violated
+      if (priority === "MANDATORY") return;
+
+      // Re-resolve scoping using context
+      const scope = normalizeScope(parsed, context.employees);
+      const targetEmployees = resolveEmployees(scope, context.employees);
+      if (targetEmployees.length === 0) return;
+
+      const activeDays = resolveActiveDays(scope, context.days);
+      if (activeDays.length === 0) return;
+
+      // Check each employee/day combination
+      for (const emp of targetEmployees) {
+        for (const day of activeDays) {
+          const violated = assignments.some(
+            (a) =>
+              a.employeeId === emp.id &&
+              a.day === day &&
+              assignmentOverlapsTimeWindow(a, timeWindowStart, timeWindowEnd),
+          );
+
+          if (violated) {
+            reporter.reportRuleViolation({
+              rule: "time-off",
+              reason: `Time-off request for ${emp.id} on ${day} could not be honored`,
+              context: {
+                employeeIds: [emp.id],
+                days: [day],
+              },
+            });
+          } else {
+            reporter.reportRulePassed({
+              rule: "time-off",
+              description: `Time-off honored for ${emp.id} on ${day}`,
+              context: {
+                employeeIds: [emp.id],
+                days: [day],
+              },
+            });
+          }
+        }
+      }
+    },
+  };
+}
+
+function resolveEmployees(scope: RuleScope, employees: SchedulingEmployee[]): SchedulingEmployee[] {
+  const entity = scope.entity;
+  switch (entity.type) {
+    case "employees":
+      return employees.filter((e) => entity.employeeIds.includes(e.id));
+    case "roles":
+      return employees.filter((e) => e.roleIds.some((r) => entity.roleIds.includes(r)));
+    case "skills":
+      return employees.filter((e) => e.skillIds?.some((s) => entity.skillIds.includes(s)));
+    case "global":
+    default:
+      return employees;
+  }
+}
+
+function resolveActiveDays(scope: RuleScope, allDays: string[]): string[] {
+  const timeScope = scope.time;
+
+  if (!timeScope) {
+    return allDays;
+  }
+
+  switch (timeScope.type) {
+    case "always":
+      return allDays;
+
+    case "dateRange": {
+      const start = timeScope.start;
+      const end = timeScope.end;
+      return allDays.filter((day) => day >= start && day <= end);
+    }
+
+    case "specificDates":
+      return allDays.filter((day) => timeScope.dates.includes(day));
+
+    case "dayOfWeek": {
+      const targetDays = new Set(timeScope.days);
+      return allDays.filter((day) => {
+        const date = parseDayString(day);
+        const dayName = getDayOfWeekName(date.getUTCDay());
+        return targetDays.has(dayName);
+      });
+    }
+
+    case "recurring": {
+      return allDays.filter((day) => {
+        const date = parseDayString(day);
+        const month = date.getUTCMonth() + 1;
+        const dayOfMonth = date.getUTCDate();
+
+        return timeScope.periods.some((period) =>
+          isDateInRecurringPeriod(month, dayOfMonth, period),
+        );
+      });
+    }
+
+    default:
+      return allDays;
+  }
+}
+
+type DayName = "sunday" | "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday";
+
+function getDayOfWeekName(dayIndex: number): DayName {
+  const names: Record<number, DayName> = {
+    0: "sunday",
+    1: "monday",
+    2: "tuesday",
+    3: "wednesday",
+    4: "thursday",
+    5: "friday",
+    6: "saturday",
+  };
+  return names[dayIndex % 7] ?? "sunday";
+}
+
+function isDateInRecurringPeriod(
+  month: number,
+  dayOfMonth: number,
+  period: {
+    startMonth: number;
+    startDay: number;
+    endMonth: number;
+    endDay: number;
+  },
+): boolean {
+  const { startMonth, startDay, endMonth, endDay } = period;
+
+  if (startMonth <= endMonth) {
+    if (month < startMonth || month > endMonth) return false;
+    if (month === startMonth && dayOfMonth < startDay) return false;
+    if (month === endMonth && dayOfMonth > endDay) return false;
+    return true;
+  } else {
+    if (month > endMonth && month < startMonth) return false;
+    if (month === startMonth && dayOfMonth < startDay) return false;
+    if (month === endMonth && dayOfMonth > endDay) return false;
+    return true;
+  }
+}
+
+function shiftOverlapsTimeWindow(
+  pattern: { startTime: TimeOfDay; endTime: TimeOfDay },
+  windowStart: TimeOfDay,
+  windowEnd: TimeOfDay,
+): boolean {
+  const shiftStart = timeOfDayToMinutes(pattern.startTime);
+  const shiftEnd = normalizeEndMinutes(shiftStart, timeOfDayToMinutes(pattern.endTime));
+
+  const winStart = timeOfDayToMinutes(windowStart);
+  const winEnd = normalizeEndMinutes(winStart, timeOfDayToMinutes(windowEnd));
+
+  return Math.max(shiftStart, winStart) < Math.min(shiftEnd, winEnd);
+}
+
+function assignmentOverlapsTimeWindow(
+  assignment: ResolvedShiftAssignment,
+  windowStart: TimeOfDay,
+  windowEnd: TimeOfDay,
+): boolean {
+  const assignStart = timeOfDayToMinutes(assignment.startTime);
+  const assignEnd = normalizeEndMinutes(assignStart, timeOfDayToMinutes(assignment.endTime));
+
+  const winStart = timeOfDayToMinutes(windowStart);
+  const winEnd = normalizeEndMinutes(winStart, timeOfDayToMinutes(windowEnd));
+
+  return Math.max(assignStart, winStart) < Math.min(assignEnd, winEnd);
+}

package/src/cpsat/rules.ts

@@ -0,0 +1,27 @@
+export {
+  createAssignTogetherRule,
+  createEmployeeAssignmentPriorityRule,
+  createLocationPreferenceRule,
+  createMaxConsecutiveDaysRule,
+  createMaxHoursDayRule,
+  createMaxHoursWeekRule,
+  createMinConsecutiveDaysRule,
+  createMinHoursDayRule,
+  createMinHoursWeekRule,
+  createMinRestBetweenShiftsRule,
+  createTimeOffRule,
+} from "./rules/index.js";
+
+export { builtInCpsatRuleFactories, createCpsatRuleFactory } from "./rules/registry.js";
+
+export type {
+  CpsatRuleName,
+  CpsatRuleRegistry,
+  CpsatRuleFactories,
+  BuiltInCpsatRuleFactories,
+  CpsatRuleRegistryFromFactories,
+  CreateCpsatRuleFunction,
+  CpsatRuleConfigEntry,
+} from "./rules/rules.types.js";
+
+export { buildCpsatRules, getEmployeeIdsForScope, resolveRuleScopes } from "./rules/resolver.js";