dabke 0.83.0 → 0.84.0

package/src/cpsat/rules/max-hours-day.ts

@@ -1,19 +1,21 @@
 import * as z from "zod";
-import type { CompilationRule } from "../model-builder.js";
-import type { Term } from "../types.js";
+import { defineRuleDescriptor } from "../rule-descriptor.js";
 import { priorityToPenalty } from "../utils.js";
 import {
   PrioritySchema,
   entityScope,
-  timeScope,
   parseEntityScope,
   parseTimeScope,
-  resolveMembersFromScope,
   resolveActiveDaysFromScope,
+  resolveMembersFromScope,
   ruleGroup,
+  timeScope,
 } from "./scope.types.js";
+import { assignmentTermsForDay } from "./assignment-terms.js";
+import { patternDurationMinutes } from "./pattern-time.js";
+import { hardConstraint, reportValidation, softConstraint } from "./artifacts.js";
 
-const MaxHoursDaySchema = z
+export const MaxHoursDaySchema = z
   .object({
     hours: z.number().min(0),
     priority: PrioritySchema,
@@ -22,92 +24,70 @@ const MaxHoursDaySchema = z
   .and(timeScope(["dateRange", "specificDates", "dayOfWeek", "recurring"]));
 
 /**
- * Configuration for {@link createMaxHoursDayRule}.
- *
- * - `hours` (required): maximum hours allowed per day
- * - `priority` (required): how strictly the solver enforces this rule
- *
- * Entity scoping (at most one): `memberIds`, `roleIds`, `skillIds`
- * Time scoping (at most one, optional): `dateRange`, `specificDates`, `dayOfWeek`, `recurringPeriods`
+ * Configuration for {@link maxHoursDayRuleDescriptor}.
  */
 export type MaxHoursDayConfig = z.infer<typeof MaxHoursDaySchema>;
 
 /**
- * Limits how many hours a person can work in a single day.
- *
- * @param config - See {@link MaxHoursDayConfig}
- * @example Limit everyone to 8 hours per day
- * ```ts
- * createMaxHoursDayRule({
- *   hours: 8,
- *   priority: "MANDATORY",
- * });
- * ```
+ * Low-level descriptor for the `max-hours-day` rule.
  *
- * @example Students limited to 4 hours on weekdays during term
- * ```ts
- * createMaxHoursDayRule({
- *   roleIds: ["student"],
- *   hours: 4,
- *   dayOfWeek: ["monday", "tuesday", "wednesday", "thursday", "friday"],
- *   priority: "MANDATORY",
- * });
- * ```
+ * @category Rules
  */
-export function createMaxHoursDayRule(config: MaxHoursDayConfig): CompilationRule {
-  const parsed = MaxHoursDaySchema.parse(config);
-  const entityScopeValue = parseEntityScope(parsed);
-  const timeScopeValue = parseTimeScope(parsed);
-  const { hours, priority } = parsed;
-  const maxMinutes = hours * 60;
-  const group = ruleGroup(
-    `max-hours-day:${hours}`,
-    `Max ${hours}h per day`,
-    entityScopeValue,
-    timeScopeValue,
-  );
-
-  return {
-    compile(b) {
-      const targetMembers = resolveMembersFromScope(entityScopeValue, b.members);
-      const activeDays = resolveActiveDaysFromScope(timeScopeValue, b.days);
-
-      if (targetMembers.length === 0 || activeDays.length === 0) return;
+export const maxHoursDayRuleDescriptor = defineRuleDescriptor({
+  name: "max-hours-day",
+  schema: MaxHoursDaySchema,
+  compile(config, ctx) {
+    const entityScopeValue = parseEntityScope(config);
+    const timeScopeValue = parseTimeScope(config);
+    const { hours, priority } = config;
+    const maxMinutes = hours * 60;
+    const group = ruleGroup(
+      `max-hours-day:${hours}`,
+      `Max ${hours}h per day`,
+      entityScopeValue,
+      timeScopeValue,
+    );
+    const targetMembers = resolveMembersFromScope(entityScopeValue, [...ctx.members]);
+    const activeDays = resolveActiveDaysFromScope(timeScopeValue, [...ctx.days]);
 
-      for (const emp of targetMembers) {
-        for (const day of activeDays) {
-          const terms: Term[] = [];
-          for (const pattern of b.shiftPatterns) {
-            if (!b.canAssign(emp, pattern)) continue;
-            if (!b.patternAvailableOnDay(pattern, day)) continue;
-            terms.push({
-              var: b.assignment(emp.id, pattern.id, day),
-              coeff: b.patternDuration(pattern.id),
-            });
-          }
+    const artifacts = targetMembers.flatMap((member) =>
+      activeDays.flatMap((day) => {
+        const terms = assignmentTermsForDay(member, day, ctx.shiftPatterns, patternDurationMinutes);
+        if (terms.length === 0) return [];
 
-          if (terms.length === 0) continue;
+        const description = `${member.id} max ${hours}h on ${day.iso}`;
+        const context = { memberIds: [member.id], days: [day.iso] };
+        const constraintId = `max-hours-day:${member.id}:${day.iso}`;
 
-          const constraintId = `max-hours-day:${emp.id}:${day}`;
+        return [
+          priority === "MANDATORY"
+            ? hardConstraint({
+                group,
+                description,
+                context,
+                validation: reportValidation(constraintId),
+                terms,
+                comparator: "<=",
+                targetValue: maxMinutes,
+              })
+            : softConstraint({
+                group,
+                description,
+                context,
+                validation: reportValidation(),
+                terms,
+                comparator: "<=",
+                targetValue: maxMinutes,
+                penalty: priorityToPenalty(priority),
+                constraintId,
+              }),
+        ];
+      }),
+    );
 
-          if (priority === "MANDATORY") {
-            b.addLinear(terms, "<=", maxMinutes);
-          } else {
-            b.addSoftLinear(terms, "<=", maxMinutes, priorityToPenalty(priority), constraintId);
-            b.reporter.trackConstraint({
-              id: constraintId,
-              type: "rule",
-              rule: "max-hours-day",
-              description: `${emp.id} max ${hours}h on ${day}`,
-              targetValue: maxMinutes,
-              comparator: "<=",
-              day,
-              context: { memberIds: [emp.id], days: [day] },
-              group,
-            });
-          }
-        }
-      }
-    },
-  };
-}
+    return {
+      rule: "max-hours-day",
+      artifacts,
+    };
+  },
+});

package/src/cpsat/rules/max-hours-week.ts

@@ -1,18 +1,20 @@
 import * as z from "zod";
 import { DayOfWeekSchema } from "../../types.js";
-import type { CompilationRule } from "../model-builder.js";
-import type { Term } from "../types.js";
+import { defineRuleDescriptor } from "../rule-descriptor.js";
 import { priorityToPenalty, splitIntoWeeks } from "../utils.js";
 import {
   PrioritySchema,
   entityScope,
-  timeScope,
   parseEntityScope,
   parseTimeScope,
-  resolveMembersFromScope,
   resolveActiveDaysFromScope,
+  resolveMembersFromScope,
   ruleGroup,
+  timeScope,
 } from "./scope.types.js";
+import { assignmentTermsForDays } from "./assignment-terms.js";
+import { patternDurationMinutes } from "./pattern-time.js";
+import { hardConstraint, reportValidation, softConstraint } from "./artifacts.js";
 
 const MaxHoursWeekBase = z.object({
   hours: z.number().min(0),
@@ -20,102 +22,84 @@ const MaxHoursWeekBase = z.object({
   weekStartsOn: DayOfWeekSchema.optional(),
 });
 
-const MaxHoursWeekSchema = MaxHoursWeekBase.and(entityScope(["members", "roles", "skills"])).and(
-  timeScope(["dateRange", "specificDates", "dayOfWeek", "recurring"]),
-);
+export const MaxHoursWeekSchema = MaxHoursWeekBase.and(
+  entityScope(["members", "roles", "skills"]),
+).and(timeScope(["dateRange", "specificDates", "dayOfWeek", "recurring"]));
 
 /**
- * Configuration for {@link createMaxHoursWeekRule}.
- *
- * - `hours` (required): maximum hours allowed per scheduling week
- * - `priority` (required): how strictly the solver enforces this rule
- * - `weekStartsOn` (optional): which day starts the week; defaults to {@link ModelBuilder.weekStartsOn}
- *
- * Entity scoping (at most one): `memberIds`, `roleIds`, `skillIds`
- * Time scoping (at most one, optional): `dateRange`, `specificDates`, `dayOfWeek`, `recurringPeriods`
+ * Configuration for {@link maxHoursWeekRuleDescriptor}.
  */
 export type MaxHoursWeekConfig = z.infer<typeof MaxHoursWeekSchema>;
 
 /**
- * Caps total hours a person can work within each scheduling week.
- *
- * @param config - See {@link MaxHoursWeekConfig}
- * @example Limit everyone to 40 hours per week
- * ```ts
- * createMaxHoursWeekRule({ hours: 40, priority: "HIGH" });
- * ```
+ * Low-level descriptor for the `max-hours-week` rule.
  *
- * @example Students limited to 20 hours during term time
- * ```ts
- * createMaxHoursWeekRule({
- *   roleIds: ["student"],
- *   hours: 20,
- *   recurringPeriods: [
- *     { name: "fall-term", startMonth: 9, startDay: 1, endMonth: 12, endDay: 15 },
- *   ],
- *   priority: "MANDATORY",
- * });
- * ```
+ * @category Rules
  */
-export function createMaxHoursWeekRule(config: MaxHoursWeekConfig): CompilationRule {
-  const parsed = MaxHoursWeekSchema.parse(config);
-  const entityScopeValue = parseEntityScope(parsed);
-  const timeScopeValue = parseTimeScope(parsed);
-  const { hours, priority, weekStartsOn } = parsed;
-  const maxMinutes = hours * 60;
-  const group = ruleGroup(
-    `max-hours-week:${hours}`,
-    `Max ${hours}h per week`,
-    entityScopeValue,
-    timeScopeValue,
-  );
-
-  return {
-    compile(b) {
-      const targetMembers = resolveMembersFromScope(entityScopeValue, b.members);
-      const activeDays = resolveActiveDaysFromScope(timeScopeValue, b.days);
+export const maxHoursWeekRuleDescriptor = defineRuleDescriptor({
+  name: "max-hours-week",
+  schema: MaxHoursWeekSchema,
+  compile(config, ctx) {
+    const entityScopeValue = parseEntityScope(config);
+    const timeScopeValue = parseTimeScope(config);
+    const { hours, priority, weekStartsOn } = config;
+    const maxMinutes = hours * 60;
+    const group = ruleGroup(
+      `max-hours-week:${hours}`,
+      `Max ${hours}h per week`,
+      entityScopeValue,
+      timeScopeValue,
+    );
+    const targetMembers = resolveMembersFromScope(entityScopeValue, [...ctx.members]);
+    const activeDays = resolveActiveDaysFromScope(timeScopeValue, [...ctx.days]);
+    const weeks = splitIntoWeeks(activeDays, weekStartsOn ?? ctx.weekStartsOn);
 
-      if (targetMembers.length === 0 || activeDays.length === 0) return;
+    const artifacts = targetMembers.flatMap((member) =>
+      weeks.flatMap((weekDays) => {
+        const weekStart = weekDays[0];
+        if (!weekStart) return [];
 
-      const weeks = splitIntoWeeks(activeDays, weekStartsOn ?? b.weekStartsOn);
+        const terms = assignmentTermsForDays(
+          member,
+          weekDays,
+          ctx.shiftPatterns,
+          patternDurationMinutes,
+        );
+        if (terms.length === 0) return [];
 
-      for (const emp of targetMembers) {
-        for (const weekDays of weeks) {
-          const terms: Term[] = [];
-          for (const day of weekDays) {
-            for (const pattern of b.shiftPatterns) {
-              if (!b.canAssign(emp, pattern)) continue;
-              if (!b.patternAvailableOnDay(pattern, day)) continue;
-              terms.push({
-                var: b.assignment(emp.id, pattern.id, day),
-                coeff: b.patternDuration(pattern.id),
-              });
-            }
-          }
+        const description = `${member.id} max ${hours}h in week starting ${weekStart.iso}`;
+        const context = { memberIds: [member.id], days: weekDays.map((day) => day.iso) };
+        const constraintId = `max-hours-week:${member.id}:${weekStart.iso}`;
 
-          if (terms.length === 0) continue;
+        return [
+          priority === "MANDATORY"
+            ? hardConstraint({
+                group,
+                description,
+                context,
+                validation: reportValidation(constraintId),
+                terms,
+                comparator: "<=",
+                targetValue: maxMinutes,
+              })
+            : softConstraint({
+                group,
+                description,
+                context,
+                validation: reportValidation(),
+                terms,
+                comparator: "<=",
+                targetValue: maxMinutes,
+                penalty: priorityToPenalty(priority),
+                constraintId,
+              }),
+        ];
+      }),
+    );
 
-          const weekLabel = weekDays[0]!;
-          const constraintId = `max-hours-week:${emp.id}:${weekLabel}`;
-
-          if (priority === "MANDATORY") {
-            b.addLinear(terms, "<=", maxMinutes);
-          } else {
-            b.addSoftLinear(terms, "<=", maxMinutes, priorityToPenalty(priority), constraintId);
-            b.reporter.trackConstraint({
-              id: constraintId,
-              type: "rule",
-              rule: "max-hours-week",
-              description: `${emp.id} max ${hours}h in week starting ${weekLabel}`,
-              targetValue: maxMinutes,
-              comparator: "<=",
-              day: weekLabel,
-              context: { memberIds: [emp.id], days: weekDays },
-              group,
-            });
-          }
-        }
-      }
-    },
-  };
-}
+    return {
+      rule: "max-hours-week",
+      artifacts,
+    };
+  },
+});

package/src/cpsat/rules/max-shifts-day.ts

@@ -1,19 +1,20 @@
 import * as z from "zod";
-import type { CompilationRule } from "../model-builder.js";
-import type { Term } from "../types.js";
+import { defineRuleDescriptor } from "../rule-descriptor.js";
 import { priorityToPenalty } from "../utils.js";
 import {
   PrioritySchema,
   entityScope,
-  timeScope,
   parseEntityScope,
   parseTimeScope,
-  resolveMembersFromScope,
   resolveActiveDaysFromScope,
+  resolveMembersFromScope,
   ruleGroup,
+  timeScope,
 } from "./scope.types.js";
+import { assignmentTermsForDay } from "./assignment-terms.js";
+import { hardConstraint, reportValidation, softConstraint } from "./artifacts.js";
 
-const MaxShiftsDaySchema = z
+export const MaxShiftsDaySchema = z
   .object({
     shifts: z.number().int().min(1),
     priority: PrioritySchema,
@@ -22,94 +23,73 @@ const MaxShiftsDaySchema = z
   .and(timeScope(["dateRange", "specificDates", "dayOfWeek", "recurring"]));
 
 /**
- * Configuration for {@link createMaxShiftsDayRule}.
- *
- * - `shifts` (required): maximum number of shifts per day (at least 1)
- * - `priority` (required): how strictly the solver enforces this rule
- *
- * Entity scoping (at most one): `memberIds`, `roleIds`, `skillIds`
- * Time scoping (at most one, optional): `dateRange`, `specificDates`, `dayOfWeek`, `recurringPeriods`
+ * Configuration for {@link maxShiftsDayRuleDescriptor}.
  */
 export type MaxShiftsDayConfig = z.infer<typeof MaxShiftsDaySchema>;
 
 /**
- * Limits how many shifts a person can work in a single day.
- *
- * Controls the maximum number of distinct shift assignments per day,
- * regardless of shift duration. For limiting total hours worked, use `max-hours-day`.
+ * Low-level descriptor for the `max-shifts-day` rule.
  *
- * @param config - See {@link MaxShiftsDayConfig}
- * @example Limit to one shift per day
- * ```ts
- * createMaxShiftsDayRule({
- *   shifts: 1,
- *   priority: "MANDATORY",
- * });
- * ```
+ * @remarks
+ * This rule limits distinct assignments per day, regardless of their duration.
+ * Use {@link maxHoursDayRuleDescriptor} to limit assigned time instead.
  *
- * @example Students can work 2 shifts on weekends only
- * ```ts
- * createMaxShiftsDayRule({
- *   roleIds: ["student"],
- *   shifts: 2,
- *   dayOfWeek: ["saturday", "sunday"],
- *   priority: "MANDATORY",
- * });
- * ```
+ * @category Rules
  */
-export function createMaxShiftsDayRule(config: MaxShiftsDayConfig): CompilationRule {
-  const parsed = MaxShiftsDaySchema.parse(config);
-  const entityScopeValue = parseEntityScope(parsed);
-  const timeScopeValue = parseTimeScope(parsed);
-  const { shifts, priority } = parsed;
-  const group = ruleGroup(
-    `max-shifts-day:${shifts}`,
-    `Max ${shifts} shift${shifts === 1 ? "" : "s"} per day`,
-    entityScopeValue,
-    timeScopeValue,
-  );
-
-  return {
-    compile(b) {
-      const targetMembers = resolveMembersFromScope(entityScopeValue, b.members);
-      const activeDays = resolveActiveDaysFromScope(timeScopeValue, b.days);
-
-      if (targetMembers.length === 0 || activeDays.length === 0) return;
+export const maxShiftsDayRuleDescriptor = defineRuleDescriptor({
+  name: "max-shifts-day",
+  schema: MaxShiftsDaySchema,
+  compile(config, ctx) {
+    const entityScopeValue = parseEntityScope(config);
+    const timeScopeValue = parseTimeScope(config);
+    const { shifts, priority } = config;
+    const group = ruleGroup(
+      `max-shifts-day:${shifts}`,
+      `Max ${shifts} shift${shifts === 1 ? "" : "s"} per day`,
+      entityScopeValue,
+      timeScopeValue,
+    );
+    const targetMembers = resolveMembersFromScope(entityScopeValue, [...ctx.members]);
+    const activeDays = resolveActiveDaysFromScope(timeScopeValue, [...ctx.days]);
 
-      for (const emp of targetMembers) {
-        for (const day of activeDays) {
-          const terms: Term[] = [];
-          for (const pattern of b.shiftPatterns) {
-            if (!b.canAssign(emp, pattern)) continue;
-            if (!b.patternAvailableOnDay(pattern, day)) continue;
-            terms.push({
-              var: b.assignment(emp.id, pattern.id, day),
-              coeff: 1,
-            });
-          }
+    const artifacts = targetMembers.flatMap((member) =>
+      activeDays.flatMap((day) => {
+        const terms = assignmentTermsForDay(member, day, ctx.shiftPatterns, () => 1);
+        if (terms.length === 0) return [];
 
-          if (terms.length === 0) continue;
+        const description = `${member.id} max ${shifts} shift${shifts === 1 ? "" : "s"} on ${day.iso}`;
+        const context = { memberIds: [member.id], days: [day.iso] };
+        const constraintId = `max-shifts-day:${member.id}:${day.iso}`;
 
-          const constraintId = `max-shifts-day:${emp.id}:${day}`;
+        return [
+          priority === "MANDATORY"
+            ? hardConstraint({
+                group,
+                description,
+                context,
+                validation: reportValidation(constraintId),
+                terms,
+                comparator: "<=",
+                targetValue: shifts,
+              })
+            : softConstraint({
+                group,
+                description,
+                context,
+                validation: reportValidation(),
+                terms,
+                comparator: "<=",
+                targetValue: shifts,
+                penalty: priorityToPenalty(priority),
+                constraintId,
+              }),
+        ];
+      }),
+    );
 
-          if (priority === "MANDATORY") {
-            b.addLinear(terms, "<=", shifts);
-          } else {
-            b.addSoftLinear(terms, "<=", shifts, priorityToPenalty(priority), constraintId);
-            b.reporter.trackConstraint({
-              id: constraintId,
-              type: "rule",
-              rule: "max-shifts-day",
-              description: `${emp.id} max ${shifts} shift${shifts === 1 ? "" : "s"} on ${day}`,
-              targetValue: shifts,
-              comparator: "<=",
-              day,
-              context: { memberIds: [emp.id], days: [day] },
-              group,
-            });
-          }
-        }
-      }
-    },
-  };
-}
+    return {
+      rule: "max-shifts-day",
+      artifacts,
+    };
+  },
+});