@lxpack/validators 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,127 @@
+# @lxpack/validators
+
+[![npm version](https://img.shields.io/npm/v/@lxpack/validators)](https://www.npmjs.com/package/@lxpack/validators)
+[![CI](https://github.com/eddiethedean/lxpack/actions/workflows/ci.yml/badge.svg)](https://github.com/eddiethedean/lxpack/actions/workflows/ci.yml)
+[![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.
+
+Part of [LXPack](https://github.com/eddiethedean/lxpack) — an AI-native learning experience compiler and runtime.
+
+| Related | Package |
+|---------|---------|
+| CLI | [`@lxpack/cli`](../cli/README.md) |
+| Packaging | [`@lxpack/scorm`](../scorm/README.md) |
+| Runtime | [`@lxpack/runtime`](../runtime/README.md) |
+
+## Install
+
+```bash
+npm install @lxpack/validators
+```
+
+Requires Node.js 20+.
+
+## Usage
+
+```ts
+import {
+  validateCourse,
+  loadManifest,
+  buildRuntimeAssessmentBundle,
+  courseManifestSchema,
+  type ValidationResult,
+} from "@lxpack/validators";
+
+const result: ValidationResult = await validateCourse("/path/to/my-course");
+
+if (!result.valid) {
+  for (const issue of result.issues) {
+    console.error(`${issue.path}: ${issue.message}`);
+  }
+} else {
+  const { manifest } = result;
+  const bundle = await buildRuntimeAssessmentBundle("/path/to/my-course", manifest);
+  // bundle.assessments — learner-facing questions (no correct flags)
+  // bundle.answerKeys — scoring keys for the runtime (embedded at build time)
+}
+```
+
+### Load and parse only
+
+```ts
+const loaded = await loadManifest("/path/to/my-course");
+if (Array.isArray(loaded)) {
+  // validation issues
+} else {
+  const { manifest } = loaded;
+}
+```
+
+### Schema-only validation
+
+```ts
+const parsed = courseManifestSchema.safeParse(manifestObject);
+```
+
+### Safe path resolution
+
+```ts
+import { resolveCoursePath, isPathContained } from "@lxpack/validators";
+
+const abs = resolveCoursePath(courseDir, "lessons/intro.md");
+isPathContained(courseDir, abs); // true if inside course root
+```
+
+## Exports
+
+| Export | Description |
+|--------|-------------|
+| `validateCourse(dir)` | Parse `course.yaml`, validate schema, check files, symlink containment |
+| `loadManifest(courseDir)` | Load and parse `course.yaml` |
+| `buildRuntimeAssessmentBundle(dir, manifest)` | Load assessments; split learner view vs answer keys |
+| `toLearnerAssessment(assessment)` | Strip `correct` / `explanation` from one assessment |
+| `resolveCoursePath(dir, relativePath)` | Resolve a path safely inside the course directory |
+| `isPathContained(root, target)` | Whether `target` stays under `root` |
+| `courseManifestSchema` | Zod schema for the full course manifest |
+| `lessonSchema`, `assessmentSchema`, … | Strict sub-schemas for manifest sections |
+| `CourseManifest`, `Lesson`, `Assessment`, `LearnerAssessment`, `RuntimeAssessmentBundle` | TypeScript types |
+
+## What gets validated
+
+- Manifest shape (lessons, assessments, tracking rules)
+- Lesson types: `markdown` (`file`) and `html` (`path`)
+- Assessment YAML: strict MCQ schemas (`correct` on exactly one choice per question)
+- Duplicate lesson IDs
+- Path containment — referenced files must stay inside the course directory (including via symlinks)
+- On-disk assets: files exist and assessments paths are regular files
+
+## Assessment packaging
+
+Author assessments live as YAML under `assessments/` in the course repo. At build/preview time:
+
+1. `buildRuntimeAssessmentBundle()` reads each assessment file.
+2. **Learner payload** — questions and choices without `correct` or `explanation`.
+3. **Answer keys** — `questionId → choiceId` map for scoring.
+
+The CLI and [`@lxpack/scorm`](../scorm/README.md) embed both in the HTML config JSON. Exported ZIPs **do not** include `assessments/` files, so answer keys are not fetchable as static assets.
+
+## Development
+
+From the monorepo root:
+
+```bash
+pnpm --filter @lxpack/validators build
+pnpm --filter @lxpack/validators test
+pnpm --filter @lxpack/validators typecheck
+```
+
+## Links
+
+- [LXPack repository](https://github.com/eddiethedean/lxpack)
+- [Changelog](https://github.com/eddiethedean/lxpack/blob/main/CHANGELOG.md)
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -7,7 +7,7 @@ declare const assessmentQuestionSchema: z.ZodEffects<z.ZodObject<{
         id: z.ZodString;
         text: z.ZodString;
         correct: z.ZodOptional<z.ZodBoolean>;
-    }, "strip", z.ZodTypeAny, {
+    }, "strict", z.ZodTypeAny, {
         id: string;
         text: string;
         correct?: boolean | undefined;
@@ -17,7 +17,7 @@ declare const assessmentQuestionSchema: z.ZodEffects<z.ZodObject<{
         correct?: boolean | undefined;
     }>, "many">;
     explanation: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
+}, "strict", z.ZodTypeAny, {
     id: string;
     prompt: string;
     choices: {
@@ -128,7 +128,7 @@ declare const assessmentSchema: z.ZodObject<{
             id: z.ZodString;
             text: z.ZodString;
             correct: z.ZodOptional<z.ZodBoolean>;
-        }, "strip", z.ZodTypeAny, {
+        }, "strict", z.ZodTypeAny, {
             id: string;
             text: string;
             correct?: boolean | undefined;
@@ -138,7 +138,7 @@ declare const assessmentSchema: z.ZodObject<{
             correct?: boolean | undefined;
         }>, "many">;
         explanation: z.ZodOptional<z.ZodString>;
-    }, "strip", z.ZodTypeAny, {
+    }, "strict", z.ZodTypeAny, {
         id: string;
         prompt: string;
         choices: {
@@ -379,6 +379,7 @@ interface ValidationResult {
     manifest?: CourseManifest;
     issues: ValidationIssue[];
 }
+declare function isPathContained(rootDir: string, candidatePath: string): boolean;
 declare function resolveCoursePath(courseDir: string, relativePath: string): {
     ok: true;
     path: string;
@@ -386,10 +387,41 @@ declare function resolveCoursePath(courseDir: string, relativePath: string): {
     ok: false;
     message: string;
 };
+declare function assertResolvedPathContained(courseDir: string, resolvedPath: string): {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
 declare function loadManifest(courseDir: string): Promise<{
     manifest: CourseManifest;
     raw: unknown;
 } | ValidationIssue[]>;
 declare function validateCourse(courseDir: string): Promise<ValidationResult>;
 
-export { type Assessment, type AssessmentRef, type CourseManifest, type Lesson, type ValidationIssue, type ValidationResult, assessmentQuestionSchema, assessmentRefSchema, assessmentSchema, courseManifestSchema, formatErrorMessage, formatIssuePath, htmlLessonSchema, lessonSchema, loadManifest, markdownLessonSchema, resolveCoursePath, runtimeConfigSchema, trackingSchema, validateCourse };
+interface LearnerChoice {
+    id: string;
+    text: string;
+}
+interface LearnerQuestion {
+    id: string;
+    prompt: string;
+    choices: LearnerChoice[];
+}
+interface LearnerAssessment {
+    id: string;
+    title?: string;
+    passingScore: number;
+    questions: LearnerQuestion[];
+}
+interface RuntimeAssessmentBundle {
+    assessments: Record<string, LearnerAssessment>;
+    answerKeys: Record<string, Record<string, string>>;
+}
+declare function toLearnerAssessment(assessment: Assessment): {
+    learner: LearnerAssessment;
+    answerKey: Record<string, string>;
+};
+declare function buildRuntimeAssessmentBundle(courseDir: string, manifest: CourseManifest): Promise<RuntimeAssessmentBundle>;
+
+export { type Assessment, type AssessmentRef, type CourseManifest, type LearnerAssessment, type LearnerChoice, type LearnerQuestion, type Lesson, type RuntimeAssessmentBundle, type ValidationIssue, type ValidationResult, assertResolvedPathContained, assessmentQuestionSchema, assessmentRefSchema, assessmentSchema, buildRuntimeAssessmentBundle, courseManifestSchema, formatErrorMessage, formatIssuePath, htmlLessonSchema, isPathContained, lessonSchema, loadManifest, markdownLessonSchema, resolveCoursePath, runtimeConfigSchema, toLearnerAssessment, trackingSchema, validateCourse };

package/dist/index.js

@@ -4,13 +4,13 @@ var choiceSchema = z.object({
   id: z.string().min(1),
   text: z.string().min(1),
   correct: z.boolean().optional()
-});
+}).strict();
 var assessmentQuestionSchema = z.object({
   id: z.string().min(1),
   prompt: z.string().min(1),
   choices: z.array(choiceSchema).min(1),
   explanation: z.string().optional()
-}).superRefine((question, ctx) => {
+}).strict().superRefine((question, ctx) => {
   const correctCount = question.choices.filter((c) => c.correct === true).length;
   if (correctCount !== 1) {
     ctx.addIssue({
@@ -65,8 +65,8 @@ var courseManifestSchema = z.object({
 }).strict();
 
 // src/validate.ts
-import { existsSync, statSync } from "fs";
-import { join, resolve, sep } from "path";
+import { existsSync, realpathSync, statSync } from "fs";
+import { isAbsolute, join, relative, resolve } from "path";
 import { parse as parseYaml } from "yaml";
 import { readFile } from "fs/promises";
 function formatErrorMessage(err) {
@@ -76,20 +76,39 @@ function formatIssuePath(path) {
   const joined = path.map(String).join(".");
   return joined || "course.yaml";
 }
+function isPathContained(rootDir, candidatePath) {
+  const root = resolve(rootDir);
+  const candidate = resolve(candidatePath);
+  const rel = relative(root, candidate);
+  if (rel === "") return true;
+  return !rel.startsWith("..") && !isAbsolute(rel);
+}
 function resolveCoursePath(courseDir, relativePath) {
   if (relativePath.startsWith("/") || /^[a-zA-Z]:\\/.test(relativePath)) {
     return { ok: false, message: "Absolute paths are not allowed" };
   }
   const resolvedDir = resolve(courseDir);
   const resolvedPath = resolve(resolvedDir, relativePath);
-  const prefix = `${resolvedDir}${sep}`;
-  if (!resolvedPath.startsWith(prefix)) {
+  if (!isPathContained(resolvedDir, resolvedPath)) {
     return { ok: false, message: "Path escapes course directory" };
   }
   return { ok: true, path: resolvedPath };
 }
+function assertResolvedPathContained(courseDir, resolvedPath) {
+  try {
+    const root = realpathSync(resolve(courseDir));
+    const target = realpathSync(resolvedPath);
+    if (!isPathContained(root, target)) {
+      return { ok: false, message: "Path escapes course directory" };
+    }
+    return { ok: true };
+  } catch {
+    return { ok: false, message: "Path could not be resolved" };
+  }
+}
 async function loadManifest(courseDir) {
-  const manifestPath = join(courseDir, "course.yaml");
+  const resolvedDir = resolve(courseDir);
+  const manifestPath = join(resolvedDir, "course.yaml");
   if (!existsSync(manifestPath)) {
     return [
       {
@@ -149,6 +168,15 @@ async function validateCourse(courseDir) {
         });
         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({
@@ -175,6 +203,15 @@ async function validateCourse(courseDir) {
         });
         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({
@@ -191,12 +228,24 @@ async function validateCourse(courseDir) {
           message: `HTML interaction missing index.html: ${lesson.path}`,
           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"
-        });
+      } 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"
+          });
+        }
       }
     }
   }
@@ -228,6 +277,24 @@ async function validateCourse(courseDir) {
         });
         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);
@@ -259,13 +326,18 @@ async function validateCourse(courseDir) {
       }
     }
   }
-  const lessonIds = new Set(manifest.lessons.map((l) => l.id));
-  if (lessonIds.size !== manifest.lessons.length) {
-    issues.push({
-      path: "lessons",
-      message: "Duplicate lesson IDs detected",
-      severity: "error"
-    });
+  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"
+      });
+    }
   }
   return {
     valid: issues.filter((i) => i.severity === "error").length === 0,
@@ -273,19 +345,77 @@ async function validateCourse(courseDir) {
     issues
   };
 }
+
+// src/assessments.ts
+import { readFile as readFile2 } from "fs/promises";
+import { parse as parseYaml2 } from "yaml";
+function toLearnerAssessment(assessment) {
+  const answerKey = {};
+  const questions = assessment.questions.map((q) => {
+    const correct = q.choices.find((c) => c.correct === true);
+    if (correct) {
+      answerKey[q.id] = correct.id;
+    }
+    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
+  };
+}
+async function buildRuntimeAssessmentBundle(courseDir, manifest) {
+  const assessments = {};
+  const answerKeys = {};
+  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 { learner, answerKey } = toLearnerAssessment(parsed.data);
+    assessments[ref.id] = learner;
+    answerKeys[ref.id] = answerKey;
+  }
+  return { assessments, answerKeys };
+}
 export {
+  assertResolvedPathContained,
   assessmentQuestionSchema,
   assessmentRefSchema,
   assessmentSchema,
+  buildRuntimeAssessmentBundle,
   courseManifestSchema,
   formatErrorMessage,
   formatIssuePath,
   htmlLessonSchema,
+  isPathContained,
   lessonSchema,
   loadManifest,
   markdownLessonSchema,
   resolveCoursePath,
   runtimeConfigSchema,
+  toLearnerAssessment,
   trackingSchema,
   validateCourse
 };

package/package.json

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