@lxpack/validators 0.2.1 → 0.2.2

package/README.md

@@ -5,7 +5,7 @@
 [![License](https://img.shields.io/github/license/eddiethedean/lxpack)](https://github.com/eddiethedean/lxpack/blob/main/LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org/)
 
-Zod schemas and filesystem validation for LXPack course manifests — including flow, variables, and component lessons (v0.2.0).
+Zod schemas and filesystem validation for LXPack course manifests — including flow, variables, and component lessons (v0.2.2).
 
 Part of [LXPack](https://github.com/eddiethedean/lxpack) — an AI-native learning experience compiler and runtime.
 
@@ -94,7 +94,7 @@ isPathContained(courseDir, abs); // true if inside course root
 | `buildRuntimeAssessmentBundle(dir, manifest)` | Load assessments; split learner view, keys, configs, feedback |
 | `toLearnerAssessment(assessment)` | Strip `correct` from choices; extract config and feedback maps |
 | `validateFlow(manifest)` | Flow rule and target validation |
-| `detectFlowCycles(flow)` | Cycle detection for branching graphs |
+| `detectFlowCycles(manifest)` | Flow-jump cycle detection for branching graphs |
 | `collectActivityIds(manifest)` | Lesson and assessment IDs for flow targets |
 | `conditionSchema`, `flowRuleSchema` | Zod schemas for flow conditions and rules |
 | `BUILTIN_COMPONENT_IDS`, `isBuiltinComponentId` | Allowed built-in component lesson IDs |

package/dist/index.d.ts

@@ -30,6 +30,8 @@ declare const flowRuleSchema: z.ZodObject<{
 }>;
 type FlowRule = z.infer<typeof flowRuleSchema>;
 
+/** Safe for SCORM paths and manifest identifiers. */
+declare const activityIdSchema: z.ZodString;
 declare const assessmentQuestionSchema: z.ZodEffects<z.ZodObject<{
     id: z.ZodString;
     prompt: z.ZodString;
@@ -185,7 +187,7 @@ declare const lessonSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     props?: Record<string, unknown> | undefined;
 }>]>;
 declare const showFeedbackSchema: z.ZodDefault<z.ZodEnum<["immediate", "end", "never"]>>;
-declare const assessmentSchema: z.ZodObject<{
+declare const assessmentSchema: z.ZodEffects<z.ZodObject<{
     id: z.ZodString;
     title: z.ZodOptional<z.ZodString>;
     passingScore: z.ZodDefault<z.ZodNumber>;
@@ -280,6 +282,40 @@ declare const assessmentSchema: z.ZodObject<{
     maxAttempts?: number | undefined;
     shuffleChoices?: boolean | undefined;
     showFeedback?: "never" | "immediate" | "end" | undefined;
+}>, {
+    id: string;
+    passingScore: number;
+    questions: {
+        id: string;
+        prompt: string;
+        choices: {
+            id: string;
+            text: string;
+            correct?: boolean | undefined;
+        }[];
+        explanation?: string | undefined;
+    }[];
+    title?: string | undefined;
+    maxAttempts?: number | undefined;
+    shuffleChoices?: boolean | undefined;
+    showFeedback?: "never" | "immediate" | "end" | undefined;
+}, {
+    id: string;
+    questions: {
+        id: string;
+        prompt: string;
+        choices: {
+            id: string;
+            text: string;
+            correct?: boolean | undefined;
+        }[];
+        explanation?: string | undefined;
+    }[];
+    title?: string | undefined;
+    passingScore?: number | undefined;
+    maxAttempts?: number | undefined;
+    shuffleChoices?: boolean | undefined;
+    showFeedback?: "never" | "immediate" | "end" | undefined;
 }>;
 declare const assessmentRefSchema: z.ZodObject<{
     id: z.ZodString;
@@ -578,9 +614,13 @@ declare function validateCourse(courseDir: string): Promise<ValidationResult>;
 
 declare function collectActivityIds(manifest: CourseManifest): Set<string>;
 declare function collectAssessmentIds(manifest: CourseManifest): Set<string>;
+declare function collectInteractionIds(manifest: CourseManifest): Set<string>;
+declare function buildActivityOrder(manifest: CourseManifest): string[];
 declare function validateFlow(manifest: CourseManifest): ValidationIssue[];
-/** Detect simple goto cycles (same-target chains). */
-declare function detectFlowCycles(flow: FlowRule[]): string[];
+/**
+ * Detect cycles reachable via flow jumps (first matching applicable rule).
+ */
+declare function detectFlowCycles(manifest: CourseManifest): string[];
 
 interface LearnerChoice {
     id: string;
@@ -635,4 +675,4 @@ declare function enumerateActivities(manifest: CourseManifest): CourseActivity[]
 
 declare function escapeHtml(text: string): string;
 
-export { type Assessment, type AssessmentRef, type AssessmentRuntimeConfig, BUILTIN_COMPONENT_IDS, type BuiltinComponentId, type ComponentLesson, type Condition, type CourseActivity, type CourseManifest, type FlowRule, type LearnerAssessment, type LearnerChoice, type LearnerQuestion, type Lesson, type QuestionFeedback, type RuntimeAssessmentBundle, type ShowFeedback, type ValidationIssue, type ValidationResult, type VariableDef, assertResolvedPathContained, assessmentQuestionSchema, assessmentRefSchema, assessmentSchema, buildRuntimeAssessmentBundle, buildRuntimeAssessmentBundleFromParsed, collectActivityIds, collectAssessmentIds, componentLessonSchema, conditionSchema, courseManifestSchema, detectFlowCycles, enumerateActivities, escapeHtml, flowRuleSchema, formatErrorMessage, formatIssuePath, htmlLessonSchema, isBuiltinComponentId, isPathContained, lessonSchema, loadManifest, loadParsedAssessments, markdownLessonSchema, resolveCoursePath, runtimeConfigSchema, showFeedbackSchema, toLearnerAssessment, trackingSchema, validateCourse, validateFlow, variableDefSchema };
+export { type Assessment, type AssessmentRef, type AssessmentRuntimeConfig, BUILTIN_COMPONENT_IDS, type BuiltinComponentId, type ComponentLesson, type Condition, type CourseActivity, type CourseManifest, type FlowRule, type LearnerAssessment, type LearnerChoice, type LearnerQuestion, type Lesson, type QuestionFeedback, type RuntimeAssessmentBundle, type ShowFeedback, type ValidationIssue, type ValidationResult, type VariableDef, activityIdSchema, assertResolvedPathContained, assessmentQuestionSchema, assessmentRefSchema, assessmentSchema, buildActivityOrder, buildRuntimeAssessmentBundle, buildRuntimeAssessmentBundleFromParsed, collectActivityIds, collectAssessmentIds, collectInteractionIds, componentLessonSchema, conditionSchema, courseManifestSchema, detectFlowCycles, enumerateActivities, escapeHtml, flowRuleSchema, formatErrorMessage, formatIssuePath, htmlLessonSchema, isBuiltinComponentId, isPathContained, lessonSchema, loadManifest, loadParsedAssessments, markdownLessonSchema, resolveCoursePath, runtimeConfigSchema, showFeedbackSchema, toLearnerAssessment, trackingSchema, validateCourse, validateFlow, variableDefSchema };

package/dist/index.js

@@ -36,6 +36,10 @@ var flowRuleSchema = z.object({
 }).strict();
 
 // src/schemas.ts
+var activityIdSchema = z2.string().min(1).regex(
+  /^[a-zA-Z][a-zA-Z0-9_-]*$/,
+  "ID must start with a letter and contain only letters, numbers, underscores, and hyphens"
+);
 var choiceSchema = z2.object({
   id: z2.string().min(1),
   text: z2.string().min(1),
@@ -55,21 +59,33 @@ var assessmentQuestionSchema = z2.object({
       path: ["choices"]
     });
   }
+  const choiceIds = /* @__PURE__ */ new Set();
+  for (let i = 0; i < question.choices.length; i++) {
+    const choice = question.choices[i];
+    if (choiceIds.has(choice.id)) {
+      ctx.addIssue({
+        code: z2.ZodIssueCode.custom,
+        message: `Duplicate choice id: ${choice.id}`,
+        path: ["choices", i, "id"]
+      });
+    }
+    choiceIds.add(choice.id);
+  }
 });
 var markdownLessonSchema = z2.object({
-  id: z2.string().min(1),
+  id: activityIdSchema,
   type: z2.literal("markdown"),
   file: z2.string().min(1),
   title: z2.string().optional()
 }).strict();
 var htmlLessonSchema = z2.object({
-  id: z2.string().min(1),
+  id: activityIdSchema,
   type: z2.literal("html"),
   path: z2.string().min(1),
   title: z2.string().optional()
 }).strict();
 var componentLessonSchema = z2.object({
-  id: z2.string().min(1),
+  id: activityIdSchema,
   type: z2.literal("component"),
   component: z2.string().min(1),
   props: z2.record(z2.unknown()).optional(),
@@ -82,16 +98,29 @@ var lessonSchema = z2.discriminatedUnion("type", [
 ]);
 var showFeedbackSchema = z2.enum(["immediate", "end", "never"]).default("never");
 var assessmentSchema = z2.object({
-  id: z2.string().min(1),
+  id: activityIdSchema,
   title: z2.string().optional(),
   passingScore: z2.number().min(0).max(1).default(0.7),
   maxAttempts: z2.number().int().min(1).optional(),
   shuffleChoices: z2.boolean().optional(),
   showFeedback: showFeedbackSchema.optional(),
   questions: z2.array(assessmentQuestionSchema).min(1)
-}).strict();
+}).strict().superRefine((assessment, ctx) => {
+  const questionIds = /* @__PURE__ */ new Set();
+  for (let i = 0; i < assessment.questions.length; i++) {
+    const q = assessment.questions[i];
+    if (questionIds.has(q.id)) {
+      ctx.addIssue({
+        code: z2.ZodIssueCode.custom,
+        message: `Duplicate question id: ${q.id}`,
+        path: ["questions", i, "id"]
+      });
+    }
+    questionIds.add(q.id);
+  }
+});
 var assessmentRefSchema = z2.object({
-  id: z2.string().min(1),
+  id: activityIdSchema,
   file: z2.string().min(1)
 }).strict();
 var variableDefSchema = z2.object({
@@ -169,6 +198,54 @@ function collectAssessmentIds(manifest) {
   }
   return ids;
 }
+function collectInteractionIds(manifest) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const lesson of manifest.lessons) {
+    if (lesson.type === "html") {
+      ids.add(lesson.id);
+    }
+  }
+  return ids;
+}
+function buildActivityOrder(manifest) {
+  const ids = manifest.lessons.map((l) => l.id);
+  for (const ref of manifest.assessments ?? []) {
+    ids.push(ref.id);
+  }
+  return ids;
+}
+function validateConditionShape(condition, path) {
+  const issues = [];
+  if ("all" in condition && condition.all) {
+    if (condition.all.length === 0) {
+      issues.push({
+        path,
+        message: "Condition all: [] is always true at runtime; use a non-empty list",
+        severity: "error"
+      });
+    }
+    for (let i = 0; i < condition.all.length; i++) {
+      issues.push(
+        ...validateConditionShape(condition.all[i], `${path}.all[${i}]`)
+      );
+    }
+  }
+  if ("any" in condition && condition.any) {
+    if (condition.any.length === 0) {
+      issues.push({
+        path,
+        message: "Condition any: [] is always false at runtime; use a non-empty list",
+        severity: "error"
+      });
+    }
+    for (let i = 0; i < condition.any.length; i++) {
+      issues.push(
+        ...validateConditionShape(condition.any[i], `${path}.any[${i}]`)
+      );
+    }
+  }
+  return issues;
+}
 function collectConditionRefs(condition, refs) {
   if ("variable" in condition && condition.variable?.eq) {
     refs.variables.add(condition.variable.eq[0]);
@@ -192,9 +269,11 @@ function validateFlow(manifest) {
   if (!flow?.length) return issues;
   const activityIds = collectActivityIds(manifest);
   const assessmentIds = collectAssessmentIds(manifest);
+  const interactionIds = collectInteractionIds(manifest);
   const manifestVars = new Set(Object.keys(manifest.variables ?? {}));
   flow.forEach((rule, index) => {
     const path = `flow[${index}]`;
+    issues.push(...validateConditionShape(rule.when, `${path}.when`));
     if (!activityIds.has(rule.goto)) {
       issues.push({
         path: `${path}.goto`,
@@ -227,10 +306,10 @@ function validateFlow(manifest) {
       }
     }
     for (const i of refs.interactions) {
-      if (!activityIds.has(i)) {
+      if (!interactionIds.has(i)) {
         issues.push({
           path: `${path}.when`,
-          message: `Unknown interaction/lesson id in condition: ${i}`,
+          message: `Unknown interaction id in condition (expected html lesson): ${i}`,
           severity: "error"
         });
       }
@@ -238,30 +317,63 @@ function validateFlow(manifest) {
   });
   return issues;
 }
-function detectFlowCycles(flow) {
-  const gotoOf = /* @__PURE__ */ new Map();
-  flow.forEach((rule, i) => gotoOf.set(i, rule.goto));
+function conditionCouldApplyAt(condition, currentActivityId, interactionIds) {
+  if ("variable" in condition) return true;
+  if ("assessment" in condition && condition.assessment?.passed) {
+    return currentActivityId === condition.assessment.passed;
+  }
+  if ("interaction" in condition && condition.interaction?.done) {
+    return interactionIds.has(currentActivityId);
+  }
+  if ("all" in condition && condition.all) {
+    return condition.all.length > 0 && condition.all.every(
+      (c) => conditionCouldApplyAt(c, currentActivityId, interactionIds)
+    );
+  }
+  if ("any" in condition && condition.any) {
+    return condition.any.length > 0 && condition.any.some(
+      (c) => conditionCouldApplyAt(c, currentActivityId, interactionIds)
+    );
+  }
+  return false;
+}
+function detectFlowCycles(manifest) {
+  const flow = manifest.flow;
+  if (!flow?.length) return [];
+  const activityIds = collectActivityIds(manifest);
+  const interactionIds = collectInteractionIds(manifest);
+  const flowJumpFrom = (current) => {
+    for (const rule of flow) {
+      if (rule.goto !== current && activityIds.has(rule.goto) && conditionCouldApplyAt(rule.when, current, interactionIds)) {
+        return rule.goto;
+      }
+    }
+    return null;
+  };
   const errors = [];
-  const visited = /* @__PURE__ */ new Set();
-  for (let start = 0; start < flow.length; start++) {
-    if (visited.has(start)) continue;
-    const chain = /* @__PURE__ */ new Set();
-    let i = start;
-    while (i !== void 0 && i < flow.length) {
-      const ruleIndex = i;
-      if (chain.has(ruleIndex)) {
-        errors.push(`Flow rule cycle detected involving flow[${ruleIndex}]`);
-        break;
+  const reported = /* @__PURE__ */ new Set();
+  const dfs = (node, stack, onStack) => {
+    const jump = flowJumpFrom(node);
+    if (!jump) return;
+    if (onStack.has(jump)) {
+      const cycleStart = stack.indexOf(jump);
+      const cycle = [...stack.slice(cycleStart), jump];
+      const key = cycle.join("->");
+      if (!reported.has(key)) {
+        reported.add(key);
+        errors.push(`Flow cycle: ${cycle.join(" -> ")}`);
       }
-      if (visited.has(ruleIndex)) break;
-      chain.add(ruleIndex);
-      visited.add(ruleIndex);
-      const target = gotoOf.get(ruleIndex);
-      const nextIdx = flow.findIndex(
-        (_, idx) => idx > ruleIndex && flow[idx].goto === target
-      );
-      i = nextIdx >= 0 ? nextIdx : void 0;
+      return;
     }
+    if (stack.length >= activityIds.size) return;
+    onStack.add(jump);
+    stack.push(jump);
+    dfs(jump, stack, onStack);
+    stack.pop();
+    onStack.delete(jump);
+  };
+  for (const id of activityIds) {
+    dfs(id, [id], /* @__PURE__ */ new Set([id]));
   }
   return errors;
 }
@@ -359,6 +471,7 @@ async function loadParsedAssessments(courseDir, manifest) {
         message: `Duplicate assessment ID: ${ref.id}`,
         severity: "error"
       });
+      continue;
     }
     assessmentIds.add(ref.id);
     const resolved = resolveCoursePath(resolvedDir, ref.file);
@@ -710,7 +823,7 @@ async function validateCourse(courseDir) {
   issues.push(...validateActivityIds(manifest));
   issues.push(...validateFlow(manifest));
   if (manifest.flow?.length) {
-    for (const message of detectFlowCycles(manifest.flow)) {
+    for (const message of detectFlowCycles(manifest)) {
       issues.push({
         path: "flow",
         message,
@@ -749,14 +862,17 @@ function escapeHtml(text) {
 }
 export {
   BUILTIN_COMPONENT_IDS,
+  activityIdSchema,
   assertResolvedPathContained,
   assessmentQuestionSchema,
   assessmentRefSchema,
   assessmentSchema,
+  buildActivityOrder,
   buildRuntimeAssessmentBundle,
   buildRuntimeAssessmentBundleFromParsed,
   collectActivityIds,
   collectAssessmentIds,
+  collectInteractionIds,
   componentLessonSchema,
   conditionSchema,
   courseManifestSchema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lxpack/validators",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Course manifest validation for LXPack",
   "license": "Apache-2.0",
   "repository": {