dabke 0.81.1 → 0.83.0

package/src/validation.ts

@@ -1,188 +0,0 @@
-/**
- * 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, SchedulingMember } 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 roles 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 roles. 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 members = [
- *   { id: "alice", roles: ["cashier"] },
- *   { id: "bob", roles: ["stocker"] },
- * ];
- *
- * const coverage = [
- *   { roles: ["cashier"], targetCount: 1, ... },  // OK
- *   { roles: ["worker"], targetCount: 1, ... },   // Unknown role!
- * ];
- *
- * const result = validateCoverageRoles(coverage, members);
- * // result.valid = false
- * // result.unknownRoles = ["worker"]
- * // result.knownRoles = ["cashier"]
- * ```
- */
-export function validateCoverageRoles(
-  coverage: CoverageRequirement[],
-  members: SchedulingMember[],
-): CoverageValidationResult {
-  const memberRoles = new Set(members.flatMap((e) => e.roles));
-  const coverageRoles = new Set(coverage.flatMap((c) => c.roles ?? []));
-
-  const unknownRoles: string[] = [];
-  const knownRoles: string[] = [];
-
-  for (const role of coverageRoles) {
-    if (memberRoles.has(role)) {
-      knownRoles.push(role);
-    } else {
-      unknownRoles.push(role);
-    }
-  }
-
-  return {
-    valid: unknownRoles.length === 0,
-    unknownRoles: unknownRoles.toSorted(),
-    knownRoles: knownRoles.toSorted(),
-  };
-}
-
-/**
- * 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 skills 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 skills.
- *
- * @example
- * ```typescript
- * const members = [
- *   { id: "alice", roles: ["server"], skills: ["keyholder"] },
- *   { id: "bob", roles: ["server"] },
- * ];
- *
- * const coverage = [
- *   { skills: ["keyholder"], targetCount: 1, ... },  // OK
- *   { skills: ["manager"], targetCount: 1, ... },   // Unknown skill!
- * ];
- *
- * const result = validateCoverageSkills(coverage, members);
- * // result.valid = false
- * // result.unknownSkills = ["manager"]
- * ```
- */
-export function validateCoverageSkills(
-  coverage: CoverageRequirement[],
-  members: SchedulingMember[],
-): SkillValidationResult {
-  const memberSkills = new Set(members.flatMap((e) => e.skills ?? []));
-  const coverageSkills = new Set(coverage.flatMap((c) => c.skills ?? []));
-
-  const unknownSkills: string[] = [];
-  const knownSkills: string[] = [];
-
-  for (const skill of coverageSkills) {
-    if (memberSkills.has(skill)) {
-      knownSkills.push(skill);
-    } else {
-      unknownSkills.push(skill);
-    }
-  }
-
-  return {
-    valid: unknownSkills.length === 0,
-    unknownSkills: unknownSkills.toSorted(),
-    knownSkills: knownSkills.toSorted(),
-  };
-}
-
-/**
- * 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, members);
- * if (!result.valid) {
- *   throw new Error(result.errors.join("; "));
- * }
- * ```
- */
-export function validateCoverageConfig(
-  coverage: CoverageRequirement[],
-  members: SchedulingMember[],
-): CoverageConfigValidationResult {
-  const roles = validateCoverageRoles(coverage, members);
-  const skills = validateCoverageSkills(coverage, members);
-
-  const errors: string[] = [];
-
-  if (!roles.valid) {
-    const availableRoles = [...new Set(members.flatMap((e) => e.roles))].toSorted();
-    errors.push(
-      `Coverage uses unknown roles: ${roles.unknownRoles.join(", ")}. ` +
-        `Available roles: ${availableRoles.join(", ")}`,
-    );
-  }
-
-  if (!skills.valid) {
-    const availableSkills = [...new Set(members.flatMap((e) => e.skills ?? []))].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,
-  };
-}