@lxpack/validators 0.2.0 → 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;
@@ -291,7 +327,7 @@ declare const assessmentRefSchema: z.ZodObject<{
     id: string;
     file: string;
 }>;
-declare const variableDefSchema: z.ZodObject<{
+declare const variableDefSchema: z.ZodEffects<z.ZodObject<{
     default: z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>;
     type: z.ZodOptional<z.ZodEnum<["string", "number", "boolean"]>>;
 }, "strict", z.ZodTypeAny, {
@@ -300,6 +336,12 @@ declare const variableDefSchema: z.ZodObject<{
 }, {
     default: string | number | boolean;
     type?: "string" | "number" | "boolean" | undefined;
+}>, {
+    default: string | number | boolean;
+    type?: "string" | "number" | "boolean" | undefined;
+}, {
+    default: string | number | boolean;
+    type?: "string" | "number" | "boolean" | undefined;
 }>;
 declare const trackingSchema: z.ZodOptional<z.ZodObject<{
     completion: z.ZodOptional<z.ZodObject<{
@@ -354,7 +396,7 @@ declare const courseManifestSchema: z.ZodObject<{
             threshold?: number | undefined;
         } | undefined;
     }>>;
-    variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+    variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodObject<{
         default: z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>;
         type: z.ZodOptional<z.ZodEnum<["string", "number", "boolean"]>>;
     }, "strict", z.ZodTypeAny, {
@@ -363,6 +405,12 @@ declare const courseManifestSchema: z.ZodObject<{
     }, {
         default: string | number | boolean;
         type?: "string" | "number" | "boolean" | undefined;
+    }>, {
+        default: string | number | boolean;
+        type?: "string" | "number" | "boolean" | undefined;
+    }, {
+        default: string | number | boolean;
+        type?: "string" | "number" | "boolean" | undefined;
     }>>>;
     flow: z.ZodOptional<z.ZodArray<z.ZodObject<{
         when: z.ZodType<Condition, z.ZodTypeDef, Condition>;
@@ -529,18 +577,6 @@ declare const BUILTIN_COMPONENT_IDS: readonly ["callout", "image-card", "checkli
 type BuiltinComponentId = (typeof BUILTIN_COMPONENT_IDS)[number];
 declare function isBuiltinComponentId(id: string): id is BuiltinComponentId;
 
-declare function formatErrorMessage(err: unknown): string;
-declare function formatIssuePath(path: PropertyKey[]): string;
-interface ValidationIssue {
-    path: string;
-    message: string;
-    severity: "error" | "warning";
-}
-interface ValidationResult {
-    valid: boolean;
-    manifest?: CourseManifest;
-    issues: ValidationIssue[];
-}
 declare function isPathContained(rootDir: string, candidatePath: string): boolean;
 declare function resolveCoursePath(courseDir: string, relativePath: string): {
     ok: true;
@@ -555,6 +591,21 @@ declare function assertResolvedPathContained(courseDir: string, resolvedPath: st
     ok: false;
     message: string;
 };
+
+declare function formatErrorMessage(err: unknown): string;
+declare function formatIssuePath(path: PropertyKey[]): string;
+interface ValidationIssue {
+    path: string;
+    message: string;
+    severity: "error" | "warning";
+}
+interface ValidationResult {
+    valid: boolean;
+    manifest?: CourseManifest;
+    issues: ValidationIssue[];
+    /** Populated when assessment files parse successfully. */
+    parsedAssessments?: Map<string, Assessment>;
+}
 declare function loadManifest(courseDir: string): Promise<{
     manifest: CourseManifest;
     raw: unknown;
@@ -562,9 +613,14 @@ declare function loadManifest(courseDir: string): Promise<{
 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;
@@ -601,6 +657,22 @@ declare function toLearnerAssessment(assessment: Assessment): {
     config: AssessmentRuntimeConfig;
     feedback: QuestionFeedback;
 };
+
+interface ParsedAssessmentsResult {
+    parsed: Map<string, Assessment>;
+    issues: ValidationIssue[];
+}
+declare function loadParsedAssessments(courseDir: string, manifest: CourseManifest): Promise<ParsedAssessmentsResult>;
+declare function buildRuntimeAssessmentBundleFromParsed(parsed: Map<string, Assessment>): RuntimeAssessmentBundle;
 declare function buildRuntimeAssessmentBundle(courseDir: string, manifest: CourseManifest): Promise<RuntimeAssessmentBundle>;
 
-export { type Assessment, type AssessmentRef, type AssessmentRuntimeConfig, BUILTIN_COMPONENT_IDS, type BuiltinComponentId, type ComponentLesson, type Condition, 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, collectActivityIds, componentLessonSchema, conditionSchema, courseManifestSchema, detectFlowCycles, flowRuleSchema, formatErrorMessage, formatIssuePath, htmlLessonSchema, isBuiltinComponentId, isPathContained, lessonSchema, loadManifest, markdownLessonSchema, resolveCoursePath, runtimeConfigSchema, showFeedbackSchema, toLearnerAssessment, trackingSchema, validateCourse, validateFlow, variableDefSchema };
+interface CourseActivity {
+    id: string;
+    title: string;
+    kind: "lesson" | "assessment";
+}
+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, 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,22 +98,58 @@ 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({
   default: z2.union([z2.string(), z2.number(), z2.boolean()]),
   type: z2.enum(["string", "number", "boolean"]).optional()
-}).strict();
+}).strict().superRefine((def, ctx) => {
+  const t = def.type;
+  if (t === "string" && typeof def.default !== "string") {
+    ctx.addIssue({
+      code: z2.ZodIssueCode.custom,
+      message: "Default must be a string when type is string",
+      path: ["default"]
+    });
+  }
+  if (t === "number" && typeof def.default !== "number") {
+    ctx.addIssue({
+      code: z2.ZodIssueCode.custom,
+      message: "Default must be a number when type is number",
+      path: ["default"]
+    });
+  }
+  if (t === "boolean" && typeof def.default !== "boolean") {
+    ctx.addIssue({
+      code: z2.ZodIssueCode.custom,
+      message: "Default must be a boolean when type is boolean",
+      path: ["default"]
+    });
+  }
+});
 var trackingSchema = z2.object({
   completion: z2.object({
     threshold: z2.number().min(0).max(1).default(0.9)
@@ -139,6 +191,61 @@ function collectActivityIds(manifest) {
   }
   return ids;
 }
+function collectAssessmentIds(manifest) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const ref of manifest.assessments ?? []) {
+    ids.add(ref.id);
+  }
+  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]);
@@ -161,9 +268,12 @@ function validateFlow(manifest) {
   const flow = manifest.flow;
   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`,
@@ -187,7 +297,7 @@ function validateFlow(manifest) {
       }
     }
     for (const a of refs.assessments) {
-      if (!activityIds.has(a)) {
+      if (!assessmentIds.has(a)) {
         issues.push({
           path: `${path}.when`,
           message: `Unknown assessment in condition: ${a}`,
@@ -196,57 +306,92 @@ 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}`,
-          severity: "warning"
+          message: `Unknown interaction id in condition (expected html lesson): ${i}`,
+          severity: "error"
         });
       }
     }
   });
   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;
 }
 
 // src/validate.ts
-import { existsSync, realpathSync, statSync } from "fs";
-import { isAbsolute, join, relative, resolve } from "path";
-import { parse as parseYaml } from "yaml";
+import { existsSync as existsSync5 } from "fs";
+import { readFile as readFile2 } from "fs/promises";
+import { join as join3, resolve as resolve2 } from "path";
+import { parse as parseYaml2 } from "yaml";
+
+// src/course-assessments.ts
+import { existsSync, statSync } from "fs";
 import { readFile } from "fs/promises";
-function formatErrorMessage(err) {
-  return err instanceof Error ? err.message : String(err);
-}
-function formatIssuePath(path) {
-  const joined = path.map(String).join(".");
-  return joined || "course.yaml";
-}
+import { parse as parseYaml } from "yaml";
+
+// src/course-paths.ts
+import { realpathSync } from "fs";
+import { isAbsolute, relative, resolve } from "path";
 function isPathContained(rootDir, candidatePath) {
   const root = resolve(rootDir);
   const candidate = resolve(candidatePath);
@@ -277,10 +422,360 @@ function assertResolvedPathContained(courseDir, resolvedPath) {
     return { ok: false, message: "Path could not be resolved" };
   }
 }
+
+// src/assessments.ts
+function toLearnerAssessment(assessment) {
+  const answerKey = {};
+  const feedback = {};
+  const questions = assessment.questions.map((q) => {
+    const correct = q.choices.find((c) => c.correct === true);
+    if (correct) {
+      answerKey[q.id] = correct.id;
+    }
+    if (q.explanation) {
+      feedback[q.id] = q.explanation;
+    }
+    return {
+      id: q.id,
+      prompt: q.prompt,
+      choices: q.choices.map((c) => ({ id: c.id, text: c.text }))
+    };
+  });
+  return {
+    learner: {
+      id: assessment.id,
+      title: assessment.title,
+      passingScore: assessment.passingScore,
+      questions
+    },
+    answerKey,
+    config: {
+      maxAttempts: assessment.maxAttempts ?? 1,
+      shuffleChoices: assessment.shuffleChoices ?? false,
+      showFeedback: assessment.showFeedback ?? "never"
+    },
+    feedback
+  };
+}
+
+// src/course-assessments.ts
+async function loadParsedAssessments(courseDir, manifest) {
+  const resolvedDir = courseDir;
+  const issues = [];
+  const parsed = /* @__PURE__ */ new Map();
+  const assessmentIds = /* @__PURE__ */ new Set();
+  for (const ref of manifest.assessments ?? []) {
+    if (assessmentIds.has(ref.id)) {
+      issues.push({
+        path: "assessments",
+        message: `Duplicate assessment ID: ${ref.id}`,
+        severity: "error"
+      });
+      continue;
+    }
+    assessmentIds.add(ref.id);
+    const resolved = resolveCoursePath(resolvedDir, ref.file);
+    if (!resolved.ok) {
+      issues.push({
+        path: `assessments.${ref.id}.file`,
+        message: resolved.message,
+        severity: "error"
+      });
+      continue;
+    }
+    if (!existsSync(resolved.path)) {
+      issues.push({
+        path: `assessments.${ref.id}.file`,
+        message: `Assessment file not found: ${ref.file}`,
+        severity: "error"
+      });
+      continue;
+    }
+    const contained = assertResolvedPathContained(resolvedDir, resolved.path);
+    if (!contained.ok) {
+      issues.push({
+        path: `assessments.${ref.id}.file`,
+        message: contained.message,
+        severity: "error"
+      });
+      continue;
+    }
+    const assessmentStat = statSync(resolved.path);
+    if (!assessmentStat.isFile()) {
+      issues.push({
+        path: `assessments.${ref.id}.file`,
+        message: `Assessment path is not a file: ${ref.file}`,
+        severity: "error"
+      });
+      continue;
+    }
+    try {
+      const content = await readFile(resolved.path, "utf-8");
+      const raw = parseYaml(content);
+      const result = assessmentSchema.safeParse(raw);
+      if (!result.success) {
+        for (const issue of result.error.issues) {
+          const subPath = issue.path.length ? issue.path.join(".") : "root";
+          issues.push({
+            path: `${ref.file}:${subPath}`,
+            message: issue.message,
+            severity: "error"
+          });
+        }
+        continue;
+      }
+      if (result.data.id !== ref.id) {
+        issues.push({
+          path: `assessments.${ref.id}`,
+          message: `Assessment file id "${result.data.id}" does not match manifest ref id "${ref.id}"`,
+          severity: "error"
+        });
+        continue;
+      }
+      parsed.set(ref.id, result.data);
+    } catch (err) {
+      issues.push({
+        path: ref.file,
+        message: `Failed to parse assessment: ${formatErrorMessage(err)}`,
+        severity: "error"
+      });
+    }
+  }
+  return { parsed, issues };
+}
+function buildRuntimeAssessmentBundleFromParsed(parsed) {
+  const assessments = {};
+  const answerKeys = {};
+  const configs = {};
+  const feedback = {};
+  for (const [id, assessment] of parsed) {
+    const built = toLearnerAssessment(assessment);
+    assessments[id] = built.learner;
+    answerKeys[id] = built.answerKey;
+    configs[id] = built.config;
+    feedback[id] = built.feedback;
+  }
+  return { assessments, answerKeys, configs, feedback };
+}
+async function buildRuntimeAssessmentBundle(courseDir, manifest) {
+  const { parsed, issues } = await loadParsedAssessments(courseDir, manifest);
+  const errors = issues.filter((i) => i.severity === "error");
+  if (errors.length > 0) {
+    throw new Error(
+      errors.map((i) => `${i.path}: ${i.message}`).join("; ")
+    );
+  }
+  return buildRuntimeAssessmentBundleFromParsed(parsed);
+}
+
+// src/validate/lesson-markdown.ts
+import { existsSync as existsSync2, statSync as statSync2 } from "fs";
+function validateMarkdownLesson(courseDir, lesson) {
+  const issues = [];
+  const resolved = resolveCoursePath(courseDir, lesson.file);
+  if (!resolved.ok) {
+    issues.push({
+      path: `lessons.${lesson.id}.file`,
+      message: resolved.message,
+      severity: "error"
+    });
+    return issues;
+  }
+  if (!existsSync2(resolved.path)) {
+    issues.push({
+      path: `lessons.${lesson.id}.file`,
+      message: `Lesson file not found: ${lesson.file}`,
+      severity: "error"
+    });
+    return issues;
+  }
+  const contained = assertResolvedPathContained(courseDir, resolved.path);
+  if (!contained.ok) {
+    issues.push({
+      path: `lessons.${lesson.id}.file`,
+      message: contained.message,
+      severity: "error"
+    });
+    return issues;
+  }
+  const stat = statSync2(resolved.path);
+  if (!stat.isFile()) {
+    issues.push({
+      path: `lessons.${lesson.id}.file`,
+      message: `Lesson path is not a file: ${lesson.file}`,
+      severity: "error"
+    });
+  }
+  return issues;
+}
+
+// src/validate/lesson-html.ts
+import { existsSync as existsSync3, statSync as statSync3 } from "fs";
+import { join } from "path";
+function validateHtmlLesson(courseDir, lesson) {
+  const issues = [];
+  const resolved = resolveCoursePath(courseDir, lesson.path);
+  if (!resolved.ok) {
+    issues.push({
+      path: `lessons.${lesson.id}.path`,
+      message: resolved.message,
+      severity: "error"
+    });
+    return issues;
+  }
+  if (!existsSync3(resolved.path)) {
+    issues.push({
+      path: `lessons.${lesson.id}.path`,
+      message: `HTML interaction directory not found: ${lesson.path}`,
+      severity: "error"
+    });
+    return issues;
+  }
+  const contained = assertResolvedPathContained(courseDir, resolved.path);
+  if (!contained.ok) {
+    issues.push({
+      path: `lessons.${lesson.id}.path`,
+      message: contained.message,
+      severity: "error"
+    });
+    return issues;
+  }
+  const stat = statSync3(resolved.path);
+  if (!stat.isDirectory()) {
+    issues.push({
+      path: `lessons.${lesson.id}.path`,
+      message: `HTML interaction path is not a directory: ${lesson.path}`,
+      severity: "error"
+    });
+    return issues;
+  }
+  const indexPath = join(resolved.path, "index.html");
+  if (!existsSync3(indexPath)) {
+    issues.push({
+      path: `lessons.${lesson.id}.path`,
+      message: `HTML interaction missing index.html: ${lesson.path}`,
+      severity: "error"
+    });
+    return issues;
+  }
+  const indexContained = assertResolvedPathContained(courseDir, indexPath);
+  if (!indexContained.ok) {
+    issues.push({
+      path: `lessons.${lesson.id}.path`,
+      message: indexContained.message,
+      severity: "error"
+    });
+    return issues;
+  }
+  if (!statSync3(indexPath).isFile()) {
+    issues.push({
+      path: `lessons.${lesson.id}.path`,
+      message: `index.html is not a file: ${lesson.path}/index.html`,
+      severity: "error"
+    });
+  }
+  return issues;
+}
+
+// src/validate/lesson-component.ts
+import { existsSync as existsSync4, statSync as statSync4 } from "fs";
+import { join as join2 } from "path";
+function validateComponentLesson(courseDir, lesson) {
+  const issues = [];
+  if (isBuiltinComponentId(lesson.component)) {
+    return issues;
+  }
+  const resolved = resolveCoursePath(
+    courseDir,
+    join2("components", lesson.component)
+  );
+  if (!resolved.ok) {
+    issues.push({
+      path: `lessons.${lesson.id}.component`,
+      message: resolved.message,
+      severity: "error"
+    });
+    return issues;
+  }
+  if (!existsSync4(resolved.path)) {
+    issues.push({
+      path: `lessons.${lesson.id}.component`,
+      message: `Unknown component "${lesson.component}" and no override at components/${lesson.component}`,
+      severity: "error"
+    });
+    return issues;
+  }
+  const contained = assertResolvedPathContained(courseDir, resolved.path);
+  if (!contained.ok) {
+    issues.push({
+      path: `lessons.${lesson.id}.component`,
+      message: contained.message,
+      severity: "error"
+    });
+    return issues;
+  }
+  const componentStat = statSync4(resolved.path);
+  if (!componentStat.isFile()) {
+    issues.push({
+      path: `lessons.${lesson.id}.component`,
+      message: `Component override path is not a file: components/${lesson.component}`,
+      severity: "error"
+    });
+  }
+  return issues;
+}
+
+// src/validate/registry.ts
+var lessonValidators = {
+  markdown: (courseDir, lesson) => validateMarkdownLesson(courseDir, lesson),
+  html: (courseDir, lesson) => validateHtmlLesson(courseDir, lesson),
+  component: (courseDir, lesson) => validateComponentLesson(courseDir, lesson)
+};
+
+// src/validate/ids.ts
+function validateActivityIds(manifest) {
+  const issues = [];
+  const lessonIdCounts = /* @__PURE__ */ new Map();
+  for (const lesson of manifest.lessons) {
+    lessonIdCounts.set(lesson.id, (lessonIdCounts.get(lesson.id) ?? 0) + 1);
+  }
+  for (const [id, count] of lessonIdCounts) {
+    if (count > 1) {
+      issues.push({
+        path: "lessons",
+        message: `Duplicate lesson ID: ${id}`,
+        severity: "error"
+      });
+    }
+  }
+  const assessmentIdSet = /* @__PURE__ */ new Set();
+  for (const ref of manifest.assessments ?? []) {
+    assessmentIdSet.add(ref.id);
+  }
+  for (const lesson of manifest.lessons) {
+    if (assessmentIdSet.has(lesson.id)) {
+      issues.push({
+        path: "lessons",
+        message: `Lesson ID "${lesson.id}" conflicts with an assessment ID`,
+        severity: "error"
+      });
+    }
+  }
+  return issues;
+}
+
+// src/validate.ts
+function formatErrorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+function formatIssuePath(path) {
+  const joined = path.map(String).join(".");
+  return joined || "course.yaml";
+}
 async function loadManifest(courseDir) {
-  const resolvedDir = resolve(courseDir);
-  const manifestPath = join(resolvedDir, "course.yaml");
-  if (!existsSync(manifestPath)) {
+  const resolvedDir = resolve2(courseDir);
+  const manifestPath = join3(resolvedDir, "course.yaml");
+  if (!existsSync5(manifestPath)) {
     return [
       {
         path: "course.yaml",
@@ -291,8 +786,8 @@ async function loadManifest(courseDir) {
   }
   let raw;
   try {
-    const content = await readFile(manifestPath, "utf-8");
-    raw = parseYaml(content);
+    const content = await readFile2(manifestPath, "utf-8");
+    raw = parseYaml2(content);
   } catch (err) {
     return [
       {
@@ -314,346 +809,76 @@ async function loadManifest(courseDir) {
 }
 async function validateCourse(courseDir) {
   const issues = [];
-  const resolvedDir = resolve(courseDir);
+  const resolvedDir = resolve2(courseDir);
   const loaded = await loadManifest(resolvedDir);
   if (Array.isArray(loaded)) {
     return { valid: false, issues: loaded };
   }
   const { manifest } = loaded;
   for (const lesson of manifest.lessons) {
-    if (lesson.type === "markdown") {
-      const resolved = resolveCoursePath(resolvedDir, lesson.file);
-      if (!resolved.ok) {
-        issues.push({
-          path: `lessons.${lesson.id}.file`,
-          message: resolved.message,
-          severity: "error"
-        });
-        continue;
-      }
-      if (!existsSync(resolved.path)) {
-        issues.push({
-          path: `lessons.${lesson.id}.file`,
-          message: `Lesson file not found: ${lesson.file}`,
-          severity: "error"
-        });
-        continue;
-      }
-      const contained = assertResolvedPathContained(resolvedDir, resolved.path);
-      if (!contained.ok) {
-        issues.push({
-          path: `lessons.${lesson.id}.file`,
-          message: contained.message,
-          severity: "error"
-        });
-        continue;
-      }
-      const stat = statSync(resolved.path);
-      if (!stat.isFile()) {
-        issues.push({
-          path: `lessons.${lesson.id}.file`,
-          message: `Lesson path is not a file: ${lesson.file}`,
-          severity: "error"
-        });
-      }
-    } else if (lesson.type === "component") {
-      if (!isBuiltinComponentId(lesson.component)) {
-        const resolved = resolveCoursePath(
-          resolvedDir,
-          join("components", lesson.component)
-        );
-        if (!resolved.ok) {
-          issues.push({
-            path: `lessons.${lesson.id}.component`,
-            message: resolved.message,
-            severity: "error"
-          });
-          continue;
-        }
-        if (!existsSync(resolved.path)) {
-          issues.push({
-            path: `lessons.${lesson.id}.component`,
-            message: `Unknown component "${lesson.component}" and no override at components/${lesson.component}`,
-            severity: "error"
-          });
-          continue;
-        }
-        const contained = assertResolvedPathContained(resolvedDir, resolved.path);
-        if (!contained.ok) {
-          issues.push({
-            path: `lessons.${lesson.id}.component`,
-            message: contained.message,
-            severity: "error"
-          });
-        }
-      }
-    } else if (lesson.type === "html") {
-      const resolved = resolveCoursePath(resolvedDir, lesson.path);
-      if (!resolved.ok) {
-        issues.push({
-          path: `lessons.${lesson.id}.path`,
-          message: resolved.message,
-          severity: "error"
-        });
-        continue;
-      }
-      if (!existsSync(resolved.path)) {
-        issues.push({
-          path: `lessons.${lesson.id}.path`,
-          message: `HTML interaction directory not found: ${lesson.path}`,
-          severity: "error"
-        });
-        continue;
-      }
-      const contained = assertResolvedPathContained(resolvedDir, resolved.path);
-      if (!contained.ok) {
-        issues.push({
-          path: `lessons.${lesson.id}.path`,
-          message: contained.message,
-          severity: "error"
-        });
-        continue;
-      }
-      const stat = statSync(resolved.path);
-      if (!stat.isDirectory()) {
-        issues.push({
-          path: `lessons.${lesson.id}.path`,
-          message: `HTML interaction path is not a directory: ${lesson.path}`,
-          severity: "error"
-        });
-        continue;
-      }
-      const indexPath = join(resolved.path, "index.html");
-      if (!existsSync(indexPath)) {
-        issues.push({
-          path: `lessons.${lesson.id}.path`,
-          message: `HTML interaction missing index.html: ${lesson.path}`,
-          severity: "error"
-        });
-      } else {
-        const indexContained = assertResolvedPathContained(
-          resolvedDir,
-          indexPath
-        );
-        if (!indexContained.ok) {
-          issues.push({
-            path: `lessons.${lesson.id}.path`,
-            message: indexContained.message,
-            severity: "error"
-          });
-        } else if (!statSync(indexPath).isFile()) {
-          issues.push({
-            path: `lessons.${lesson.id}.path`,
-            message: `index.html is not a file: ${lesson.path}/index.html`,
-            severity: "error"
-          });
-        }
-      }
-    }
-  }
-  if (manifest.assessments) {
-    const assessmentIds = /* @__PURE__ */ new Set();
-    for (const ref of manifest.assessments) {
-      if (assessmentIds.has(ref.id)) {
-        issues.push({
-          path: "assessments",
-          message: `Duplicate assessment ID: ${ref.id}`,
-          severity: "error"
-        });
-      }
-      assessmentIds.add(ref.id);
-      const resolved = resolveCoursePath(resolvedDir, ref.file);
-      if (!resolved.ok) {
-        issues.push({
-          path: `assessments.${ref.id}.file`,
-          message: resolved.message,
-          severity: "error"
-        });
-        continue;
-      }
-      if (!existsSync(resolved.path)) {
-        issues.push({
-          path: `assessments.${ref.id}.file`,
-          message: `Assessment file not found: ${ref.file}`,
-          severity: "error"
-        });
-        continue;
-      }
-      const contained = assertResolvedPathContained(resolvedDir, resolved.path);
-      if (!contained.ok) {
-        issues.push({
-          path: `assessments.${ref.id}.file`,
-          message: contained.message,
-          severity: "error"
-        });
-        continue;
-      }
-      const assessmentStat = statSync(resolved.path);
-      if (!assessmentStat.isFile()) {
-        issues.push({
-          path: `assessments.${ref.id}.file`,
-          message: `Assessment path is not a file: ${ref.file}`,
-          severity: "error"
-        });
-        continue;
-      }
-      try {
-        const content = await readFile(resolved.path, "utf-8");
-        const raw = parseYaml(content);
-        const parsed = assessmentSchema.safeParse(raw);
-        if (!parsed.success) {
-          for (const issue of parsed.error.issues) {
-            const subPath = issue.path.length ? issue.path.join(".") : "root";
-            issues.push({
-              path: `${ref.file}:${subPath}`,
-              message: issue.message,
-              severity: "error"
-            });
-          }
-          continue;
-        }
-        if (parsed.data.id !== ref.id) {
-          issues.push({
-            path: `assessments.${ref.id}`,
-            message: `Assessment file id "${parsed.data.id}" does not match manifest ref id "${ref.id}"`,
-            severity: "error"
-          });
-        }
-      } catch (err) {
-        issues.push({
-          path: ref.file,
-          message: `Failed to parse assessment: ${formatErrorMessage(err)}`,
-          severity: "error"
-        });
-      }
-    }
+    issues.push(...lessonValidators[lesson.type](resolvedDir, lesson));
   }
-  const lessonIdCounts = /* @__PURE__ */ new Map();
-  for (const lesson of manifest.lessons) {
-    lessonIdCounts.set(lesson.id, (lessonIdCounts.get(lesson.id) ?? 0) + 1);
-  }
-  for (const [id, count] of lessonIdCounts) {
-    if (count > 1) {
+  const assessmentLoad = await loadParsedAssessments(resolvedDir, manifest);
+  issues.push(...assessmentLoad.issues);
+  issues.push(...validateActivityIds(manifest));
+  issues.push(...validateFlow(manifest));
+  if (manifest.flow?.length) {
+    for (const message of detectFlowCycles(manifest)) {
       issues.push({
-        path: "lessons",
-        message: `Duplicate lesson ID: ${id}`,
+        path: "flow",
+        message,
         severity: "error"
       });
     }
   }
-  issues.push(...validateFlow(manifest));
-  if (manifest.variables) {
-    for (const [name, def] of Object.entries(manifest.variables)) {
-      const t = def.type;
-      if (t === "string" && typeof def.default !== "string") {
-        issues.push({
-          path: `variables.${name}.default`,
-          message: "Default must be a string when type is string",
-          severity: "error"
-        });
-      }
-      if (t === "number" && typeof def.default !== "number") {
-        issues.push({
-          path: `variables.${name}.default`,
-          message: "Default must be a number when type is number",
-          severity: "error"
-        });
-      }
-      if (t === "boolean" && typeof def.default !== "boolean") {
-        issues.push({
-          path: `variables.${name}.default`,
-          message: "Default must be a boolean when type is boolean",
-          severity: "error"
-        });
-      }
-    }
-  }
   return {
     valid: issues.filter((i) => i.severity === "error").length === 0,
     manifest,
-    issues
+    issues,
+    parsedAssessments: assessmentLoad.parsed
   };
 }
 
-// src/assessments.ts
-import { readFile as readFile2 } from "fs/promises";
-import { parse as parseYaml2 } from "yaml";
-function toLearnerAssessment(assessment) {
-  const answerKey = {};
-  const feedback = {};
-  const questions = assessment.questions.map((q) => {
-    const correct = q.choices.find((c) => c.correct === true);
-    if (correct) {
-      answerKey[q.id] = correct.id;
-    }
-    if (q.explanation) {
-      feedback[q.id] = q.explanation;
-    }
-    return {
-      id: q.id,
-      prompt: q.prompt,
-      choices: q.choices.map((c) => ({ id: c.id, text: c.text }))
-    };
-  });
-  return {
-    learner: {
-      id: assessment.id,
-      title: assessment.title,
-      passingScore: assessment.passingScore,
-      questions
-    },
-    answerKey,
-    config: {
-      maxAttempts: assessment.maxAttempts ?? 1,
-      shuffleChoices: assessment.shuffleChoices ?? false,
-      showFeedback: assessment.showFeedback ?? "never"
-    },
-    feedback
-  };
-}
-async function buildRuntimeAssessmentBundle(courseDir, manifest) {
-  const assessments = {};
-  const answerKeys = {};
-  const configs = {};
-  const feedback = {};
+// src/activities.ts
+function enumerateActivities(manifest) {
+  const activities = manifest.lessons.map((lesson) => ({
+    id: lesson.id,
+    title: lesson.title ?? lesson.id,
+    kind: "lesson"
+  }));
   for (const ref of manifest.assessments ?? []) {
-    const resolved = resolveCoursePath(courseDir, ref.file);
-    if (!resolved.ok) {
-      throw new Error(resolved.message);
-    }
-    const content = await readFile2(resolved.path, "utf-8");
-    const raw = parseYaml2(content);
-    const parsed = assessmentSchema.safeParse(raw);
-    if (!parsed.success) {
-      throw new Error(
-        `Invalid assessment ${ref.file}: ${parsed.error.issues.map((i) => i.message).join("; ")}`
-      );
-    }
-    if (parsed.data.id !== ref.id) {
-      throw new Error(
-        `Assessment file id "${parsed.data.id}" does not match manifest ref "${ref.id}"`
-      );
-    }
-    const built = toLearnerAssessment(parsed.data);
-    assessments[ref.id] = built.learner;
-    answerKeys[ref.id] = built.answerKey;
-    configs[ref.id] = built.config;
-    feedback[ref.id] = built.feedback;
+    activities.push({
+      id: ref.id,
+      title: ref.id.replace(/_/g, " "),
+      kind: "assessment"
+    });
   }
-  return { assessments, answerKeys, configs, feedback };
+  return activities;
+}
+
+// src/html.ts
+function escapeHtml(text) {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
 export {
   BUILTIN_COMPONENT_IDS,
+  activityIdSchema,
   assertResolvedPathContained,
   assessmentQuestionSchema,
   assessmentRefSchema,
   assessmentSchema,
+  buildActivityOrder,
   buildRuntimeAssessmentBundle,
+  buildRuntimeAssessmentBundleFromParsed,
   collectActivityIds,
+  collectAssessmentIds,
+  collectInteractionIds,
   componentLessonSchema,
   conditionSchema,
   courseManifestSchema,
   detectFlowCycles,
+  enumerateActivities,
+  escapeHtml,
   flowRuleSchema,
   formatErrorMessage,
   formatIssuePath,
@@ -662,6 +887,7 @@ export {
   isPathContained,
   lessonSchema,
   loadManifest,
+  loadParsedAssessments,
   markdownLessonSchema,
   resolveCoursePath,
   runtimeConfigSchema,

package/package.json

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