dabke 0.83.0 → 0.84.0

package/src/cpsat/rules/max-consecutive-days.ts

@@ -1,5 +1,5 @@
 import * as z from "zod";
-import type { CompilationRule } from "../model-builder.js";
+import { defineRuleDescriptor } from "../rule-descriptor.js";
 import { priorityToPenalty } from "../utils.js";
 import {
   PrioritySchema,
@@ -8,8 +8,11 @@ import {
   resolveMembersFromScope,
   ruleGroup,
 } from "./scope.types.js";
+import { assignmentVarsForDay } from "./assignment-terms.js";
+import { hardConstraint, reportValidation, softConstraint } from "./artifacts.js";
+import { buildAssignedDayIndicator } from "./assigned-day.js";
 
-const MaxConsecutiveDaysSchema = z
+export const MaxConsecutiveDaysSchema = z
   .object({
     days: z.number().min(0),
     priority: PrioritySchema,
@@ -17,103 +20,83 @@ const MaxConsecutiveDaysSchema = z
   .and(entityScope(["members", "roles", "skills"]));
 
 /**
- * Configuration for {@link createMaxConsecutiveDaysRule}.
- *
- * - `days` (required): maximum consecutive days allowed
- * - `priority` (required): how strictly the solver enforces this rule
- *
- * Entity scoping (at most one): `memberIds`, `roleIds`, `skillIds`
+ * Configuration for {@link maxConsecutiveDaysRuleDescriptor}.
  */
 export type MaxConsecutiveDaysConfig = z.infer<typeof MaxConsecutiveDaysSchema>;
 
 /**
- * Limits how many consecutive days a person can be assigned.
+ * Low-level descriptor for the `max-consecutive-days` rule.
  *
- * @param config - See {@link MaxConsecutiveDaysConfig}
- * @example
- * ```ts
- * createMaxConsecutiveDaysRule({ days: 5, priority: "MANDATORY" });
- * ```
+ * @remarks
+ * This rule limits the length of each assignment streak by counting assigned
+ * days in every sliding window of `days + 1` days.
+ *
+ * @category Rules
  */
-export function createMaxConsecutiveDaysRule(config: MaxConsecutiveDaysConfig): CompilationRule {
-  const parsed = MaxConsecutiveDaysSchema.parse(config);
-  const scope = parseEntityScope(parsed);
-  const { days, priority } = parsed;
-  const windowSize = days + 1;
-  const group = ruleGroup(`max-consecutive-days:${days}`, `Max ${days} consecutive days`, scope);
-
-  return {
-    compile(b) {
-      const members = resolveMembersFromScope(scope, b.members);
+export const maxConsecutiveDaysRuleDescriptor = defineRuleDescriptor({
+  name: "max-consecutive-days",
+  schema: MaxConsecutiveDaysSchema,
+  compile(config, ctx) {
+    const scope = parseEntityScope(config);
+    const { days, priority } = config;
+    const windowSize = days + 1;
+    const group = ruleGroup(`max-consecutive-days:${days}`, `Max ${days} consecutive days`, scope);
+    const members = resolveMembersFromScope(scope, [...ctx.members]);
 
-      for (const emp of members) {
-        for (let i = 0; i <= b.days.length - windowSize; i++) {
-          const windowDays = b.days.slice(i, i + windowSize);
+    const artifacts = members.flatMap((member) => {
+      const supportArtifacts = ctx.days.flatMap(
+        (day) =>
+          buildAssignedDayIndicator({
+            memberId: member.id,
+            day,
+            assignmentVars: assignmentVarsForDay(member, day, ctx.shiftPatterns),
+            variableName: `assigned_${member.id}_${day.iso}`,
+          }).artifacts,
+      );
 
-          const worksDayVars: string[] = [];
-          for (const day of windowDays) {
-            const worksVar = b.boolVar(`works_${emp.id}_${day}`);
-            worksDayVars.push(worksVar);
-
-            const dayAssignments = b.shiftPatterns
-              .filter((p) => b.canAssign(emp, p) && b.patternAvailableOnDay(p, day))
-              .map((p) => b.assignment(emp.id, p.id, day));
+      const windowArtifacts = Array.from(
+        { length: Math.max(0, ctx.days.length - windowSize + 1) },
+        (_, index) => {
+          const windowDays = ctx.days.slice(index, index + windowSize);
+          const windowStart = windowDays[0]!;
+          const terms = windowDays.map((day) => ({
+            var: `assigned_${member.id}_${day.iso}`,
+            coeff: 1,
+          }));
+          const description = `${member.id} max ${days} consecutive days from ${windowStart.iso}`;
+          const context = { memberIds: [member.id], days: windowDays.map((day) => day.iso) };
+          const constraintId = `max-consecutive-days:${member.id}:${windowStart.iso}`;
 
-            if (dayAssignments.length === 0) {
-              b.addLinear([{ var: worksVar, coeff: 1 }], "==", 0);
-            } else {
-              for (const assignVar of dayAssignments) {
-                b.addLinear(
-                  [
-                    { var: worksVar, coeff: 1 },
-                    { var: assignVar, coeff: -1 },
-                  ],
-                  ">=",
-                  0,
-                );
-              }
-              b.addLinear(
-                [
-                  { var: worksVar, coeff: 1 },
-                  ...dayAssignments.map((v) => ({ var: v, coeff: -1 })),
-                ],
-                "<=",
-                0,
-              );
-            }
-          }
+          return priority === "MANDATORY"
+            ? hardConstraint({
+                group,
+                description,
+                context,
+                validation: reportValidation(constraintId),
+                terms,
+                comparator: "<=",
+                targetValue: days,
+              })
+            : softConstraint({
+                group,
+                description,
+                context,
+                validation: reportValidation(),
+                terms,
+                comparator: "<=",
+                targetValue: days,
+                penalty: priorityToPenalty(priority),
+                constraintId,
+              });
+        },
+      );
 
-          const windowStart = windowDays[0]!;
-          const constraintId = `max-consecutive-days:${emp.id}:${windowStart}`;
+      return supportArtifacts.concat(windowArtifacts);
+    });
 
-          if (priority === "MANDATORY") {
-            b.addLinear(
-              worksDayVars.map((v) => ({ var: v, coeff: 1 })),
-              "<=",
-              days,
-            );
-          } else {
-            b.addSoftLinear(
-              worksDayVars.map((v) => ({ var: v, coeff: 1 })),
-              "<=",
-              days,
-              priorityToPenalty(priority),
-              constraintId,
-            );
-            b.reporter.trackConstraint({
-              id: constraintId,
-              type: "rule",
-              rule: "max-consecutive-days",
-              description: `${emp.id} max ${days} consecutive days from ${windowStart}`,
-              targetValue: days,
-              comparator: "<=",
-              day: windowStart,
-              context: { memberIds: [emp.id], days: windowDays },
-              group,
-            });
-          }
-        }
-      }
-    },
-  };
-}
+    return {
+      rule: "max-consecutive-days",
+      artifacts,
+    };
+  },
+});

package/src/cpsat/rules/max-days-of-week-per-period.ts

@@ -0,0 +1,127 @@
+import * as z from "zod";
+import { DayOfWeekSchema } from "../../types.js";
+import { defineRuleDescriptor } from "../rule-descriptor.js";
+import { groupWeekChunks, priorityToPenalty, splitIntoMonths } from "../utils.js";
+import {
+  PrioritySchema,
+  entityScope,
+  parseEntityScope,
+  resolveMembersFromScope,
+  ruleGroup,
+} from "./scope.types.js";
+import { assignmentVarsForDay } from "./assignment-terms.js";
+import { assignedDayVariableName } from "./variables.js";
+import { hardConstraint, reportValidation, softConstraint } from "./artifacts.js";
+import { buildAssignedDayIndicator } from "./assigned-day.js";
+
+const PeriodSchema = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("weeks"), value: z.number().int().min(1) }),
+  z.object({ type: z.literal("months"), value: z.number().int().min(1) }),
+]);
+
+const MaxDaysOfWeekPerPeriodBase = z.object({
+  days: z.number().int().min(0),
+  dayOfWeek: z.array(DayOfWeekSchema).nonempty(),
+  period: PeriodSchema,
+  priority: PrioritySchema,
+});
+
+export const MaxDaysOfWeekPerPeriodSchema = MaxDaysOfWeekPerPeriodBase.and(
+  entityScope(["members", "roles", "skills"]),
+);
+
+/**
+ * Configuration for {@link maxDaysOfWeekPerPeriodRuleDescriptor}.
+ */
+export type MaxDaysOfWeekPerPeriodConfig = z.infer<typeof MaxDaysOfWeekPerPeriodSchema>;
+
+/**
+ * Low-level descriptor for the `max-days-of-week-per-period` rule.
+ *
+ * @remarks
+ * This rule counts assigned days matching the configured days of the week.
+ * Week-based periods align to `weekStartsOn`; month-based periods align to
+ * calendar month boundaries.
+ *
+ * @category Rules
+ */
+export const maxDaysOfWeekPerPeriodRuleDescriptor = defineRuleDescriptor({
+  name: "max-days-of-week-per-period",
+  schema: MaxDaysOfWeekPerPeriodSchema,
+  compile(config, ctx) {
+    const entityScopeValue = parseEntityScope(config);
+    const { days, dayOfWeek, period, priority } = config;
+    const dowLabel = dayOfWeek.toSorted().join(",");
+    const periodLabel = `${period.value}${period.type === "weeks" ? "w" : "m"}`;
+    const group = ruleGroup(
+      `max-days-of-week-per-period:${days}:${dowLabel}:${periodLabel}`,
+      `Max ${days} ${dowLabel} per ${period.value} ${period.type}`,
+      entityScopeValue,
+    );
+    const targetMembers = resolveMembersFromScope(entityScopeValue, [...ctx.members]);
+    const targetDows = new Set(dayOfWeek);
+    const chunks =
+      period.type === "weeks"
+        ? groupWeekChunks([...ctx.days], period.value, ctx.weekStartsOn)
+        : splitIntoMonths([...ctx.days], period.value);
+
+    const artifacts = targetMembers.flatMap((member) =>
+      chunks.flatMap((chunkDays) => {
+        const chunkStart = chunkDays[0];
+        if (!chunkStart) return [];
+
+        const matchingDays = chunkDays.filter((day) => targetDows.has(day.dayOfWeek));
+        if (matchingDays.length === 0) return [];
+
+        const supportArtifacts = matchingDays.flatMap(
+          (day) =>
+            buildAssignedDayIndicator({
+              memberId: member.id,
+              day,
+              assignmentVars: assignmentVarsForDay(member, day, ctx.shiftPatterns),
+            }).artifacts,
+        );
+
+        const assignedDayVars = matchingDays
+          .filter((day) => assignmentVarsForDay(member, day, ctx.shiftPatterns).length > 0)
+          .map((day) => assignedDayVariableName(member.id, day.iso));
+        if (assignedDayVars.length === 0) return supportArtifacts;
+
+        const description = `${member.id} max ${days} ${dowLabel} in period starting ${chunkStart.iso}`;
+        const context = { memberIds: [member.id], days: matchingDays.map((day) => day.iso) };
+        const constraintId = `max-days-of-week-per-period:${member.id}:${chunkStart.iso}`;
+        const terms = assignedDayVars.map((varName) => ({ var: varName, coeff: 1 }));
+
+        const finalArtifact =
+          priority === "MANDATORY"
+            ? hardConstraint({
+                group,
+                description,
+                context,
+                validation: reportValidation(constraintId),
+                terms,
+                comparator: "<=",
+                targetValue: days,
+              })
+            : softConstraint({
+                group,
+                description,
+                context,
+                validation: reportValidation(),
+                terms,
+                comparator: "<=",
+                targetValue: days,
+                penalty: priorityToPenalty(priority),
+                constraintId,
+              });
+
+        return supportArtifacts.concat(finalArtifact);
+      }),
+    );
+
+    return {
+      rule: "max-days-of-week-per-period",
+      artifacts,
+    };
+  },
+});

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

@@ -1,18 +1,21 @@
 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 { assignmentVarsForDay } from "./assignment-terms.js";
+import { assignedDayVariableName } from "./variables.js";
+import { hardConstraint, reportValidation, softConstraint } from "./artifacts.js";
+import { buildAssignedDayIndicator } from "./assigned-day.js";
 
 const MaxDaysWeekBase = z.object({
   days: z.number().int().min(0),
@@ -20,124 +23,95 @@ const MaxDaysWeekBase = z.object({
   weekStartsOn: DayOfWeekSchema.optional(),
 });
 
-const MaxDaysWeekSchema = MaxDaysWeekBase.and(entityScope(["members", "roles", "skills"])).and(
-  timeScope(["dateRange", "specificDates", "dayOfWeek", "recurring"]),
-);
+export const MaxDaysWeekSchema = MaxDaysWeekBase.and(
+  entityScope(["members", "roles", "skills"]),
+).and(timeScope(["dateRange", "specificDates", "dayOfWeek", "recurring"]));
 
 /**
- * Configuration for {@link createMaxDaysWeekRule}.
- *
- * - `days` (required): maximum number of days 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 maxDaysWeekRuleDescriptor}.
  */
 export type MaxDaysWeekConfig = z.infer<typeof MaxDaysWeekSchema>;
 
 /**
- * Caps total number of days a person can work within each scheduling week.
+ * Low-level descriptor for the `max-days-week` rule.
  *
  * @remarks
- * Creates a binary "works on day" variable for each member and day, then
- * constrains the weekly sum. This counts distinct days, regardless of how
- * many shifts are assigned on a single day.
- *
- * @param config - See {@link MaxDaysWeekConfig}
- * @example Limit everyone to 5 days per week
- * ```ts
- * createMaxDaysWeekRule({ days: 5, priority: "MANDATORY" });
- * ```
+ * This rule counts assigned days, not assigned shifts. Multiple assignments on
+ * the same day still count as one assigned day.
  *
- * @example Part-time staff limited to 3 days
- * ```ts
- * createMaxDaysWeekRule({
- *   roleIds: ["part-time"],
- *   days: 3,
- *   priority: "HIGH",
- * });
- * ```
+ * @category Rules
  */
-export function createMaxDaysWeekRule(config: MaxDaysWeekConfig): CompilationRule {
-  const parsed = MaxDaysWeekSchema.parse(config);
-  const entityScopeValue = parseEntityScope(parsed);
-  const timeScopeValue = parseTimeScope(parsed);
-  const { days, priority, weekStartsOn } = parsed;
-  const group = ruleGroup(
-    `max-days-week:${days}`,
-    `Max ${days}d per week`,
-    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;
-
-      const weeks = splitIntoWeeks(activeDays, weekStartsOn ?? b.weekStartsOn);
-
-      for (const emp of targetMembers) {
-        for (const weekDays of weeks) {
-          const weekWorkVars: string[] = [];
-
-          for (const day of weekDays) {
-            const dayAssignments = b.shiftPatterns
-              .filter((p) => b.canAssign(emp, p) && b.patternAvailableOnDay(p, day))
-              .map((p) => b.assignment(emp.id, p.id, day));
-
-            if (dayAssignments.length === 0) continue;
-
-            const worksVar = b.boolVar(`works_day_${emp.id}_${day}`);
-            weekWorkVars.push(worksVar);
-
-            // worksVar >= each assignment (if any assignment is 1, worksVar must be 1)
-            for (const assignVar of dayAssignments) {
-              b.addLinear(
-                [
-                  { var: worksVar, coeff: 1 },
-                  { var: assignVar, coeff: -1 },
-                ],
-                ">=",
-                0,
-              );
-            }
-
-            // worksVar <= sum(assignments) (if no assignment is 1, worksVar must be 0)
-            b.addLinear(
-              [{ var: worksVar, coeff: 1 }, ...dayAssignments.map((v) => ({ var: v, coeff: -1 }))],
-              "<=",
-              0,
-            );
-          }
-
-          if (weekWorkVars.length === 0) continue;
-
-          const weekLabel = weekDays[0]!;
-          const constraintId = `max-days-week:${emp.id}:${weekLabel}`;
-          const terms: Term[] = weekWorkVars.map((v) => ({ var: v, coeff: 1 }));
-
-          if (priority === "MANDATORY") {
-            b.addLinear(terms, "<=", days);
-          } else {
-            b.addSoftLinear(terms, "<=", days, priorityToPenalty(priority), constraintId);
-            b.reporter.trackConstraint({
-              id: constraintId,
-              type: "rule",
-              rule: "max-days-week",
-              description: `${emp.id} max ${days}d in week starting ${weekLabel}`,
-              targetValue: days,
-              comparator: "<=",
-              day: weekLabel,
-              context: { memberIds: [emp.id], days: weekDays },
-              group,
-            });
-          }
-        }
-      }
-    },
-  };
-}
+export const maxDaysWeekRuleDescriptor = defineRuleDescriptor({
+  name: "max-days-week",
+  schema: MaxDaysWeekSchema,
+  compile(config, ctx) {
+    const entityScopeValue = parseEntityScope(config);
+    const timeScopeValue = parseTimeScope(config);
+    const { days, priority, weekStartsOn } = config;
+    const group = ruleGroup(
+      `max-days-week:${days}`,
+      `Max ${days}d per week`,
+      entityScopeValue,
+      timeScopeValue,
+    );
+    const targetMembers = resolveMembersFromScope(entityScopeValue, [...ctx.members]);
+    const activeDays = resolveActiveDaysFromScope(timeScopeValue, [...ctx.days]);
+    const weeks = splitIntoWeeks(activeDays, weekStartsOn ?? ctx.weekStartsOn);
+
+    const artifacts = targetMembers.flatMap((member) =>
+      weeks.flatMap((weekDays) => {
+        const weekStart = weekDays[0];
+        if (!weekStart) return [];
+
+        const supportArtifacts = weekDays.flatMap(
+          (day) =>
+            buildAssignedDayIndicator({
+              memberId: member.id,
+              day,
+              assignmentVars: assignmentVarsForDay(member, day, ctx.shiftPatterns),
+            }).artifacts,
+        );
+
+        const assignedDayVars = weekDays
+          .filter((day) => assignmentVarsForDay(member, day, ctx.shiftPatterns).length > 0)
+          .map((day) => assignedDayVariableName(member.id, day.iso));
+        if (assignedDayVars.length === 0) return supportArtifacts;
+
+        const description = `${member.id} max ${days}d in week starting ${weekStart.iso}`;
+        const context = { memberIds: [member.id], days: weekDays.map((day) => day.iso) };
+        const constraintId = `max-days-week:${member.id}:${weekStart.iso}`;
+        const terms = assignedDayVars.map((varName) => ({ var: varName, coeff: 1 }));
+
+        const finalArtifact =
+          priority === "MANDATORY"
+            ? hardConstraint({
+                group,
+                description,
+                context,
+                validation: reportValidation(constraintId),
+                terms,
+                comparator: "<=",
+                targetValue: days,
+              })
+            : softConstraint({
+                group,
+                description,
+                context,
+                validation: reportValidation(),
+                terms,
+                comparator: "<=",
+                targetValue: days,
+                penalty: priorityToPenalty(priority),
+                constraintId,
+              });
+
+        return supportArtifacts.concat(finalArtifact);
+      }),
+    );
+
+    return {
+      rule: "max-days-week",
+      artifacts,
+    };
+  },
+});