dabke 0.78.0

package/dist/validation.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Validation utilities for scheduling configuration.
+ *
+ * These functions help catch configuration errors early, before the ModelBuilder
+ * attempts to compile the scheduling problem. This is especially useful when
+ * configuration is generated by an LLM, which may hallucinate role or skill names.
+ */
+import type { CoverageRequirement, SchedulingEmployee } from "./cpsat/types.js";
+/**
+ * Result of coverage role validation.
+ */
+export interface CoverageValidationResult {
+    valid: boolean;
+    /** Role IDs used in coverage that don't match any team member */
+    unknownRoles: string[];
+    /** Role IDs used in coverage that match team members */
+    knownRoles: string[];
+}
+/**
+ * Validates that all roleIds used in coverage requirements match the team.
+ *
+ * This catches a common LLM error where the model generates coverage requirements
+ * using role names that don't match any team member's roleIds. Without this validation,
+ * such mismatches would result in valid but semantically wrong schedules (e.g.,
+ * coverage requirements that no one can satisfy).
+ *
+ * @example
+ * ```typescript
+ * const employees = [
+ *   { id: "alice", roleIds: ["cashier"] },
+ *   { id: "bob", roleIds: ["stocker"] },
+ * ];
+ *
+ * const coverage = [
+ *   { roleId: "cashier", targetCount: 1, ... },  // OK
+ *   { roleId: "worker", targetCount: 1, ... },   // Unknown role!
+ * ];
+ *
+ * const result = validateCoverageRoles(coverage, employees);
+ * // result.valid = false
+ * // result.unknownRoles = ["worker"]
+ * // result.knownRoles = ["cashier"]
+ * ```
+ */
+export declare function validateCoverageRoles(coverage: CoverageRequirement[], employees: SchedulingEmployee[]): CoverageValidationResult;
+/**
+ * Result of coverage skill validation.
+ */
+export interface SkillValidationResult {
+    valid: boolean;
+    /** Skill IDs used in coverage that don't match any team member */
+    unknownSkills: string[];
+    /** Skill IDs used in coverage that match team members */
+    knownSkills: string[];
+}
+/**
+ * Validates that all skillIds used in coverage requirements match the team.
+ *
+ * Similar to role validation, this catches LLM hallucinations where skill names
+ * in coverage don't match any team member's skillIds.
+ *
+ * @example
+ * ```typescript
+ * const employees = [
+ *   { id: "alice", roleIds: ["server"], skillIds: ["keyholder"] },
+ *   { id: "bob", roleIds: ["server"] },
+ * ];
+ *
+ * const coverage = [
+ *   { skillIds: ["keyholder"], targetCount: 1, ... },  // OK
+ *   { skillIds: ["manager"], targetCount: 1, ... },   // Unknown skill!
+ * ];
+ *
+ * const result = validateCoverageSkills(coverage, employees);
+ * // result.valid = false
+ * // result.unknownSkills = ["manager"]
+ * ```
+ */
+export declare function validateCoverageSkills(coverage: CoverageRequirement[], employees: SchedulingEmployee[]): SkillValidationResult;
+/**
+ * Combined validation result for coverage requirements.
+ */
+export interface CoverageConfigValidationResult {
+    valid: boolean;
+    roles: CoverageValidationResult;
+    skills: SkillValidationResult;
+    /** Human-readable error messages */
+    errors: string[];
+}
+/**
+ * Validates coverage requirements against team roles and skills.
+ *
+ * This is the primary validation function to call before building a scheduling model.
+ * It checks both roles and skills, returning a combined result with error messages.
+ *
+ * @example
+ * ```typescript
+ * const result = validateCoverageConfig(coverage, employees);
+ * if (!result.valid) {
+ *   throw new Error(result.errors.join("; "));
+ * }
+ * ```
+ */
+export declare function validateCoverageConfig(coverage: CoverageRequirement[], employees: SchedulingEmployee[]): CoverageConfigValidationResult;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAEhF;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,OAAO,CAAC;IACf,iEAAiE;IACjE,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,wDAAwD;IACxD,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,mBAAmB,EAAE,EAC/B,SAAS,EAAE,kBAAkB,EAAE,GAC9B,wBAAwB,CAoB1B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,OAAO,CAAC;IACf,kEAAkE;IAClE,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,yDAAyD;IACzD,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,mBAAmB,EAAE,EAC/B,SAAS,EAAE,kBAAkB,EAAE,GAC9B,qBAAqB,CAoBvB;AAED;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC7C,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,wBAAwB,CAAC;IAChC,MAAM,EAAE,qBAAqB,CAAC;IAC9B,oCAAoC;IACpC,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,mBAAmB,EAAE,EAC/B,SAAS,EAAE,kBAAkB,EAAE,GAC9B,8BAA8B,CA4BhC"}

package/dist/validation.js

@@ -0,0 +1,130 @@
+/**
+ * Validation utilities for scheduling configuration.
+ *
+ * These functions help catch configuration errors early, before the ModelBuilder
+ * attempts to compile the scheduling problem. This is especially useful when
+ * configuration is generated by an LLM, which may hallucinate role or skill names.
+ */
+/**
+ * Validates that all roleIds used in coverage requirements match the team.
+ *
+ * This catches a common LLM error where the model generates coverage requirements
+ * using role names that don't match any team member's roleIds. Without this validation,
+ * such mismatches would result in valid but semantically wrong schedules (e.g.,
+ * coverage requirements that no one can satisfy).
+ *
+ * @example
+ * ```typescript
+ * const employees = [
+ *   { id: "alice", roleIds: ["cashier"] },
+ *   { id: "bob", roleIds: ["stocker"] },
+ * ];
+ *
+ * const coverage = [
+ *   { roleId: "cashier", targetCount: 1, ... },  // OK
+ *   { roleId: "worker", targetCount: 1, ... },   // Unknown role!
+ * ];
+ *
+ * const result = validateCoverageRoles(coverage, employees);
+ * // result.valid = false
+ * // result.unknownRoles = ["worker"]
+ * // result.knownRoles = ["cashier"]
+ * ```
+ */
+export function validateCoverageRoles(coverage, employees) {
+    const employeeRoles = new Set(employees.flatMap((e) => e.roleIds));
+    const coverageRoles = new Set(coverage.flatMap((c) => c.roleIds ?? []));
+    const unknownRoles = [];
+    const knownRoles = [];
+    for (const role of coverageRoles) {
+        if (employeeRoles.has(role)) {
+            knownRoles.push(role);
+        }
+        else {
+            unknownRoles.push(role);
+        }
+    }
+    return {
+        valid: unknownRoles.length === 0,
+        unknownRoles: unknownRoles.toSorted(),
+        knownRoles: knownRoles.toSorted(),
+    };
+}
+/**
+ * Validates that all skillIds used in coverage requirements match the team.
+ *
+ * Similar to role validation, this catches LLM hallucinations where skill names
+ * in coverage don't match any team member's skillIds.
+ *
+ * @example
+ * ```typescript
+ * const employees = [
+ *   { id: "alice", roleIds: ["server"], skillIds: ["keyholder"] },
+ *   { id: "bob", roleIds: ["server"] },
+ * ];
+ *
+ * const coverage = [
+ *   { skillIds: ["keyholder"], targetCount: 1, ... },  // OK
+ *   { skillIds: ["manager"], targetCount: 1, ... },   // Unknown skill!
+ * ];
+ *
+ * const result = validateCoverageSkills(coverage, employees);
+ * // result.valid = false
+ * // result.unknownSkills = ["manager"]
+ * ```
+ */
+export function validateCoverageSkills(coverage, employees) {
+    const employeeSkills = new Set(employees.flatMap((e) => e.skillIds ?? []));
+    const coverageSkills = new Set(coverage.flatMap((c) => c.skillIds ?? []));
+    const unknownSkills = [];
+    const knownSkills = [];
+    for (const skill of coverageSkills) {
+        if (employeeSkills.has(skill)) {
+            knownSkills.push(skill);
+        }
+        else {
+            unknownSkills.push(skill);
+        }
+    }
+    return {
+        valid: unknownSkills.length === 0,
+        unknownSkills: unknownSkills.toSorted(),
+        knownSkills: knownSkills.toSorted(),
+    };
+}
+/**
+ * Validates coverage requirements against team roles and skills.
+ *
+ * This is the primary validation function to call before building a scheduling model.
+ * It checks both roles and skills, returning a combined result with error messages.
+ *
+ * @example
+ * ```typescript
+ * const result = validateCoverageConfig(coverage, employees);
+ * if (!result.valid) {
+ *   throw new Error(result.errors.join("; "));
+ * }
+ * ```
+ */
+export function validateCoverageConfig(coverage, employees) {
+    const roles = validateCoverageRoles(coverage, employees);
+    const skills = validateCoverageSkills(coverage, employees);
+    const errors = [];
+    if (!roles.valid) {
+        const availableRoles = [...new Set(employees.flatMap((e) => e.roleIds))].toSorted();
+        errors.push(`Coverage uses unknown roles: ${roles.unknownRoles.join(", ")}. ` +
+            `Available roles: ${availableRoles.join(", ")}`);
+    }
+    if (!skills.valid) {
+        const availableSkills = [...new Set(employees.flatMap((e) => e.skillIds ?? []))].toSorted();
+        errors.push(`Coverage uses unknown skills: ${skills.unknownSkills.join(", ")}. ` +
+            `Available skills: ${availableSkills.length > 0 ? availableSkills.join(", ") : "(none)"}`);
+    }
+    return {
+        valid: roles.valid && skills.valid,
+        roles,
+        skills,
+        errors,
+    };
+}
+//# sourceMappingURL=validation.js.map

package/dist/validation.js.map

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