dabke 0.81.1 → 0.83.0

package/dist/cpsat/validation.types.d.ts

@@ -1,23 +1,4 @@
 import type { TimeOfDay } from "../types.js";
-declare const GroupKeyBrand: unique symbol;
-/**
- * Branded type for validation group keys.
- * Groups related validation items that originated from the same instruction.
- */
-export type GroupKey = string & {
-    readonly [GroupKeyBrand]: never;
-};
-/**
- * Creates a GroupKey from a description string.
- * Use this to create keys that group related validation items together.
- *
- * @example
- * ```typescript
- * const key = groupKey("2x waiter during lunch");
- * coverage.groupKey = key;
- * ```
- */
-export declare function groupKey(description: string): GroupKey;
 /**
  * Context shared across validation results for grouping/display.
  */
@@ -26,30 +7,53 @@ export interface ValidationContext {
     timeSlots?: string[];
     memberIds?: string[];
 }
+/**
+ * Groups related validation items under a deterministic, structural key.
+ *
+ * The `key` is derived from the rule/coverage structure (e.g.,
+ * `"rule:max-hours-week:40:roles:nurse"`), ensuring that identical
+ * configurations always produce the same key. The `title` is the
+ * human-readable label shown in summaries.
+ *
+ * Rule authors create groups via {@link ruleGroup} in `scope.types.ts`;
+ * coverage groups are produced by the semantic-time resolver.
+ */
+export interface ValidationGroup {
+    /** Deterministic key derived from rule/coverage structure. */
+    readonly key: string;
+    /** Human-readable label for summaries (e.g., "Max 40h per week"). */
+    readonly title: string;
+}
+/**
+ * Throws if a value contains characters used as key delimiters.
+ * Call before interpolating user-provided IDs into group keys.
+ */
+export declare function assertSafeKeySegment(value: string, label: string): void;
+export declare function assertSafeKeySegments(values: readonly string[], label: string): void;
 export interface CoverageError {
     readonly id: string;
     readonly type: "coverage";
     readonly day: string;
     readonly timeSlots: readonly string[];
-    readonly roles?: string[];
-    readonly skills?: readonly string[];
-    readonly reason: string;
+    readonly roleIds?: string[];
+    readonly skillIds?: readonly string[];
+    readonly message: string;
     readonly suggestions?: readonly string[];
-    readonly groupKey?: GroupKey;
+    readonly group?: ValidationGroup;
 }
 export interface RuleError {
     readonly id: string;
     readonly type: "rule";
     readonly rule: string;
-    readonly reason: string;
+    readonly message: string;
     readonly context: ValidationContext;
     readonly suggestions?: readonly string[];
-    readonly groupKey?: GroupKey;
+    readonly group?: ValidationGroup;
 }
 export interface SolverError {
     readonly id: string;
     readonly type: "solver";
-    readonly reason: string;
+    readonly message: string;
 }
 export type ScheduleError = CoverageError | RuleError | SolverError;
 export interface CoverageViolation {
@@ -57,22 +61,23 @@ export interface CoverageViolation {
     readonly type: "coverage";
     readonly day: string;
     readonly timeSlots: readonly string[];
-    readonly roles?: string[];
-    readonly skills?: readonly string[];
+    readonly roleIds?: string[];
+    readonly skillIds?: readonly string[];
     readonly targetCount: number;
     readonly actualCount: number;
     readonly shortfall: number;
-    readonly groupKey?: GroupKey;
+    readonly message: string;
+    readonly group?: ValidationGroup;
 }
 export interface RuleViolation {
     readonly id: string;
     readonly type: "rule";
     readonly rule: string;
-    readonly reason: string;
+    readonly message: string;
     readonly context: ValidationContext;
     readonly shortfall?: number;
     readonly overflow?: number;
-    readonly groupKey?: GroupKey;
+    readonly group?: ValidationGroup;
 }
 export type ScheduleViolation = CoverageViolation | RuleViolation;
 export interface CoveragePassed {
@@ -80,20 +85,21 @@ export interface CoveragePassed {
     readonly type: "coverage";
     readonly day: string;
     readonly timeSlots: readonly string[];
-    readonly roles?: string[];
-    readonly skills?: readonly string[];
-    readonly description: string;
-    readonly groupKey?: GroupKey;
+    readonly roleIds?: string[];
+    readonly skillIds?: readonly string[];
+    readonly message: string;
+    readonly group?: ValidationGroup;
 }
 export interface RulePassed {
     readonly id: string;
     readonly type: "rule";
     readonly rule: string;
-    readonly description: string;
+    readonly message: string;
     readonly context: ValidationContext;
-    readonly groupKey?: GroupKey;
+    readonly group?: ValidationGroup;
 }
 export type SchedulePassed = CoveragePassed | RulePassed;
+/** @category Validation */
 export interface ScheduleValidation {
     readonly errors: readonly ScheduleError[];
     readonly violations: readonly ScheduleViolation[];
@@ -101,12 +107,16 @@ export interface ScheduleValidation {
 }
 /**
  * Summary of validation items grouped by their source instruction.
- * Use `summarizeValidation()` to create these from a ScheduleValidation.
+ * Use `summarizeValidation()` to create these from a `ScheduleValidation`.
+ *
+ * @category Validation
  */
 export interface ValidationSummary {
-    readonly groupKey: GroupKey;
+    /** Deterministic group key derived from rule/coverage structure. */
+    readonly groupKey: string;
     readonly type: "coverage" | "rule";
-    readonly description: string;
+    /** Human-readable title for this group (e.g., "3x nurse during day_ward"). */
+    readonly title: string;
     readonly days: readonly string[];
     readonly status: "passed" | "partial" | "failed";
     readonly passedCount: number;
@@ -117,15 +127,16 @@ export interface TrackedConstraint {
     readonly id: string;
     readonly type: "coverage" | "rule";
     readonly rule?: string;
+    /** Per-constraint description used to generate violation messages. */
     readonly description: string;
     readonly targetValue: number;
     readonly comparator: "<=" | ">=";
     readonly day?: string;
     readonly timeSlot?: string;
-    readonly roles?: string[];
-    readonly skills?: readonly string[];
+    readonly roleIds?: string[];
+    readonly skillIds?: readonly string[];
     readonly context: ValidationContext;
-    readonly groupKey?: GroupKey;
+    readonly group?: ValidationGroup;
 }
 /**
  * Coverage exclusion - indicates a team member is unavailable for coverage during a time period.
@@ -137,5 +148,4 @@ export interface CoverageExclusion {
     startTime?: TimeOfDay;
     endTime?: TimeOfDay;
 }
-export {};
 //# sourceMappingURL=validation.types.d.ts.map

package/dist/cpsat/validation.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.types.d.ts","sourceRoot":"","sources":["../../src/cpsat/validation.types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"validation.types.d.ts","sourceRoot":"","sources":["../../src/cpsat/validation.types.ts"],"names":[],"mappings":"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"}

package/dist/cpsat/validation.types.js

@@ -1,14 +1,19 @@
+// =============================================================================
+// Key safety helpers
+// =============================================================================
+const KEY_DELIMITERS = /[,:/+]/;
 /**
- * Creates a GroupKey from a description string.
- * Use this to create keys that group related validation items together.
- *
- * @example
- * ```typescript
- * const key = groupKey("2x waiter during lunch");
- * coverage.groupKey = key;
- * ```
+ * Throws if a value contains characters used as key delimiters.
+ * Call before interpolating user-provided IDs into group keys.
  */
-export function groupKey(description) {
-    return description;
+export function assertSafeKeySegment(value, label) {
+    if (KEY_DELIMITERS.test(value)) {
+        throw new Error(`${label} "${value}" contains reserved delimiter characters (: , / +)`);
+    }
+}
+export function assertSafeKeySegments(values, label) {
+    for (const v of values) {
+        assertSafeKeySegment(v, label);
+    }
 }
 //# sourceMappingURL=validation.types.js.map

package/dist/cpsat/validation.types.js.map

@@ -1 +1 @@
-{"version":3,"file":"validation.types.js","sourceRoot":"","sources":["../../src/cpsat/validation.types.ts"],"names":[],"mappings":"AAcA;;;;;;;;;GASG;AACH,MAAM,UAAU,QAAQ,CAAC,WAAmB;IAC1C,OAAO,WAAuB,CAAC;AACjC,CAAC"}
+{"version":3,"file":"validation.types.js","sourceRoot":"","sources":["../../src/cpsat/validation.types.ts"],"names":[],"mappings":"AAiCA,gFAAgF;AAChF,qBAAqB;AACrB,gFAAgF;AAEhF,MAAM,cAAc,GAAG,QAAQ,CAAC;AAEhC;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAa,EAAE,KAAa;IAC/D,IAAI,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,KAAK,KAAK,oDAAoD,CAAC,CAAC;IAC1F,CAAC;AACH,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,MAAyB,EAAE,KAAa;IAC5E,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,oBAAoB,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IACjC,CAAC;AACH,CAAC"}

package/dist/datetime.utils.d.ts

@@ -1,210 +1,10 @@
-import { CalendarDate, DateTime, DateTimeRange, DayOfWeek, SchedulingPeriod } from "./types.js";
+import type { DayOfWeek, SchedulingPeriod } from "./types.js";
+export declare const DAY_OF_WEEK_MAP: Record<DayOfWeek, number>;
 /**
- * Converts a JavaScript Date to a CalendarDate
- */
-export declare function dateToCalendarDate(date: Date): CalendarDate;
-/**
- * Converts a DateTime to a JavaScript Date
- * Internal helper function
- */
-export declare function dateTimeToDate(dateTime: DateTime): Date;
-/**
- * Compares two DateTimes
- * Returns:
- *  -1 if dateTime1 < dateTime2
- *   0 if dateTime1 = dateTime2
- *   1 if dateTime1 > dateTime2
- */
-export declare function compareDateTimes(dateTime1: DateTime, dateTime2: DateTime): number;
-export declare const DAY_OF_WEEK_MAP: {
-    sunday: number;
-    monday: number;
-    tuesday: number;
-    wednesday: number;
-    thursday: number;
-    friday: number;
-    saturday: number;
-};
-/**
- * Helper to get the day of week name from a Date (local time)
- */
-export declare function toDayOfWeek(date: Date): DayOfWeek;
-/**
- * Helper to get the day of week name from a Date (UTC)
+ * Helper to get the day of week name from a Date (UTC).
  * Use this when working with date strings like "2026-01-10" that are timezone-agnostic.
  */
 export declare function toDayOfWeekUTC(date: Date): DayOfWeek;
-/**
- * Formats a date as YYYY-MM-DD string
- */
-export declare function formatDateString(date: Date): string;
-/**
- * Generates an array of day strings (YYYY-MM-DD) from a time horizon.
- *
- * @param horizon - The time horizon with start (inclusive) and end (inclusive) dates
- * @returns Array of day strings in YYYY-MM-DD format
- *
- * @example
- * ```typescript
- * const days = generateDays({
- *   start: new Date('2025-01-01'),
- *   end: new Date('2025-01-04')
- * });
- * // Returns: ["2025-01-01", "2025-01-02", "2025-01-03", "2025-01-04"]
- * ```
- */
-export declare function generateDays(horizon: {
-    start: Date;
-    end: Date;
-}): string[];
-/**
- * Splits a time period into consecutive day ranges.
- *
- * Each range represents a single calendar day within the period from start to end.
- * This is useful for rules that need to apply constraints on a per-day basis,
- * such as maximum or minimum hours per day.
- *
- * @param start - The start date of the period (inclusive)
- * @param end - The end date of the period (exclusive)
- * @returns An array of [startDate, endDate] tuples, where each tuple represents
- * a single day. The last range's end date will be the provided end date.
- *
- * @example
- * ```typescript
- * const ranges = splitPeriodIntoDays({
- *   start: new Date('2025-01-01'),
- *   end: new Date('2025-01-03')
- * });
- * // Returns:
- * // [
- * //   [Date('2025-01-01'), Date('2025-01-02')],
- * //   [Date('2025-01-02'), Date('2025-01-03')]
- * // ]
- * ```
- */
-export declare function splitPeriodIntoDays({ start, end }: {
-    start: Date;
-    end: Date;
-}): [Date, Date][];
-/**
- * Splits a time period into consecutive week ranges.
- *
- * Each range represents a week period starting on the specified day of the week.
- * This is useful for rules that need to apply constraints on a per-week basis,
- * such as maximum or minimum hours per week.
- *
- * The first range starts at the provided start date (not necessarily on weekStartsOn).
- * Subsequent ranges align to the weekStartsOn day. The last range's end date will be
- * the provided end date.
- *
- * @param start - The start date of the period (inclusive)
- * @param end - The end date of the period (exclusive)
- * @param weekStartsOn - The day of the week that weeks start on (e.g., "monday", "sunday")
- * @returns An array of [startDate, endDate] tuples, where each tuple represents
- * a week period aligned to the specified week start day.
- *
- * @example
- * ```typescript
- * const ranges = splitPeriodIntoWeeks({
- *   start: new Date('2025-01-01'), // Wednesday
- *   end: new Date('2025-01-15'),
- *   weekStartsOn: 'monday'
- * });
- * // Returns ranges starting from Jan 1 (Wed), then aligning to Mondays:
- * // [
- * //   [Date('2025-01-01 Wed'), Date('2025-01-06 Mon')],
- * //   [Date('2025-01-06 Mon'), Date('2025-01-13 Mon')],
- * //   [Date('2025-01-13 Mon'), Date('2025-01-15 Wed')]
- * // ]
- * ```
- */
-export declare function splitPeriodIntoWeeks({ start, end, weekStartsOn, }: {
-    start: Date;
-    end: Date;
-    weekStartsOn: DayOfWeek;
-}): [Date, Date][];
-/**
- * Checks if two DateTime ranges overlap in both date and time.
- * Ranges overlap if they share any moment in time.
- *
- * Two ranges overlap if: range1.start < range2.end AND range2.start < range1.end
- *
- * @param range1 First time range with start (inclusive) and end (exclusive)
- * @param range2 Second time range with start (inclusive) and end (exclusive)
- * @returns true if ranges overlap, false otherwise
- *
- * @example
- * ```typescript
- * // Same day, overlapping times (9-17 overlaps with 12-20)
- * dateTimeRangesOverlap(
- *   {
- *     start: { year: 2025, month: 6, day: 1, hours: 9, minutes: 0 },
- *     end: { year: 2025, month: 6, day: 1, hours: 17, minutes: 0 }
- *   },
- *   {
- *     start: { year: 2025, month: 6, day: 1, hours: 12, minutes: 0 },
- *     end: { year: 2025, month: 6, day: 1, hours: 20, minutes: 0 }
- *   }
- * ); // true
- *
- * // Different days - no overlap
- * dateTimeRangesOverlap(
- *   {
- *     start: { year: 2025, month: 6, day: 1, hours: 9, minutes: 0 },
- *     end: { year: 2025, month: 6, day: 1, hours: 17, minutes: 0 }
- *   },
- *   {
- *     start: { year: 2025, month: 6, day: 2, hours: 9, minutes: 0 },
- *     end: { year: 2025, month: 6, day: 2, hours: 17, minutes: 0 }
- *   }
- * ); // false
- *
- * // Works naturally with Shift objects
- * dateTimeRangesOverlap(
- *   { start: shift1.startDateTime, end: shift1.endDateTime },
- *   { start: shift2.startDateTime, end: shift2.endDateTime }
- * );
- * ```
- */
-export declare function dateTimeRangesOverlap(range1: DateTimeRange, range2: DateTimeRange): boolean;
-/**
- * Calculates the number of complete days between two dates
- * @param start The start date
- * @param end The end date
- * @returns Number of complete days from start to end (can be negative if end < start)
- *
- * @example
- * ```typescript
- * daysBetween(new Date('2025-01-01'), new Date('2025-01-05')); // 4
- * ```
- */
-export declare function daysBetween(start: Date, end: Date): number;
-/**
- * Adds a number of minutes to a base date and returns a DateTime.
- * Treats the base date as a reference point (typically midnight of horizon start),
- * and the minutes parameter as absolute minutes from that point.
- *
- * @param baseDate The starting date (used as reference point)
- * @param minutes Absolute minutes from the base date
- * @returns DateTime representing the result
- *
- * @example
- * ```typescript
- * // Add 90 minutes from midnight
- * addMinutesToDate(new Date('2025-01-01'), 90);
- * // Returns: { year: 2025, month: 1, day: 1, hours: 1, minutes: 30 }
- *
- * // Add 1500 minutes (spans to next day)
- * addMinutesToDate(new Date('2025-01-01'), 1500);
- * // Returns: { year: 2025, month: 1, day: 2, hours: 1, minutes: 0 }
- * ```
- */
-export declare function addMinutesToDate(baseDate: Date, minutes: number): DateTime;
-/**
- * Returns the points where a range should be split, filtered to within [start, end).
- * Always includes range start. Sorted ascending.
- */
-export declare function splitPoints([start, end]: [number, number], splitAt: number[]): number[];
 /**
  * Computes the list of day strings (YYYY-MM-DD) from a SchedulingPeriod.
  *

package/dist/datetime.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"datetime.utils.d.ts","sourceRoot":"","sources":["../src/datetime.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEhG;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,YAAY,CAM3D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CASvD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,GAAG,MAAM,CAOjF;AAED,eAAO,MAAM,eAAe;;;;;;;;CAQ3B,CAAC;AAYF;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,CAGjD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,CAGpD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAKnD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,IAAI,CAAA;CAAE,GAAG,MAAM,EAAE,CAU1E;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,IAAI,CAAA;CAAE,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAsB9F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,oBAAoB,CAAC,EACnC,KAAK,EACL,GAAG,EACH,YAAY,GACb,EAAE;IACD,KAAK,EAAE,IAAI,CAAC;IACZ,GAAG,EAAE,IAAI,CAAC;IACV,YAAY,EAAE,SAAS,CAAC;CACzB,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAoCjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAM3F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,GAAG,MAAM,CAG1D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,QAAQ,CAc1E;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAQvF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,EAAE,CAyBxE"}
+{"version":3,"file":"datetime.utils.d.ts","sourceRoot":"","sources":["../src/datetime.utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9D,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAQrD,CAAC;AAYF;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,CAGpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,EAAE,CAyBxE"}