sdac-validate-replacements

Purpose

Validates replacement records and ensures comments link to main roster positions.

Tool type

Deterministic (rule-based)

Tool ID

sdac-validate-replacements

Inputs

• report_id (string)
• record_ids (number[], optional)

Outputs

• success, passed
• error_count, warning_count
• errors, warnings, executed_rules
• replacement_summary (optional)

Example output

{
  "success": true,
  "category": "REPLACEMENT",
  "report_id": "SDAC-2024-Q2-001",
  "total_records_checked": 4,
  "passed": false,
  "error_count": 1,
  "warning_count": 1,
  "errors": [
    {
      "rule_id": "REPLACEMENT_INVALID_LINK",
      "record_id": 7201,
      "row_number": 72,
      "first_name": "Taylor",
      "last_name": "Jones",
      "job_title": "SLP Substitute",
      "message": "Replacement references a row that is not present in the main roster.",
      "current_value": "row 999",
      "severity": "ERROR"
    }
  ],
  "warnings": [
    {
      "rule_id": "REPLACEMENT_MISSING_COMMENT",
      "record_id": 7301,
      "row_number": 73,
      "first_name": "Morgan",
      "last_name": "Lee",
      "job_title": "Nurse Substitute",
      "message": "Replacement record should include a comment linking to the main roster.",
      "current_value": "",
      "severity": "WARNING"
    }
  ],
  "executed_rules": [
    "REPLACEMENT_INVALID_LINK",
    "REPLACEMENT_MISSING_COMMENT"
  ],
  "replacement_summary": {
    "total_replacements": 4,
    "properly_linked": 2,
    "missing_links": 2
  },
  "execution_time_ms": 188
}

Functional details

• Ensures each replacement row references a main roster record.
• Flags missing or invalid row references in comments.
• Summarizes properly linked vs. orphaned replacements.

Implementation details

• Filters to IsReplacement records and checks comments for row references.
• Extracts row references using row patterns (e.g., row 12).
• Emits REPLACEMENT_MISSING_COMMENT, REPLACEMENT_MISSING_LINK, REPLACEMENT_INVALID_LINK.
• Tracks properly_linked vs missing_links summary counts.
• Builds the main roster row set from non-replacement records.
• Treats invalid row references as errors; missing references are warnings.

Code Location: packages/domain-sdac/src/tools/validate-replacements.tool.ts