@lessonkit/lxpack 1.3.0 → 1.3.1

package/dist/index.cjs

@@ -57,6 +57,7 @@ __export(index_exports, {
   validateLessonkitProject: () => validateLessonkitProject,
   validatePackageInputs: () => validatePackageInputs,
   validateProjectPaths: () => validateProjectPaths,
+  validateReactManifestParity: () => validateReactManifestParity,
   writeLxpackProject: () => writeLxpackProject
 });
 module.exports = __toCommonJS(index_exports);
@@ -718,8 +719,114 @@ function validateDescriptorForTarget(input, target) {
   return result;
 }
 
-// src/validateProjectPaths.ts
+// src/validateReactParity.ts
+var import_node_fs2 = require("fs");
 var import_node_path2 = require("path");
+var SCANNABLE_EXTENSIONS = [".tsx", ".ts", ".jsx", ".js"];
+function collectSourceUnderSrc(projectRoot) {
+  const srcDir = (0, import_node_path2.join)(projectRoot, "src");
+  if (!(0, import_node_fs2.existsSync)(srcDir)) return [];
+  const results = [];
+  const walk = (dir) => {
+    for (const entry of (0, import_node_fs2.readdirSync)(dir)) {
+      const abs = (0, import_node_path2.join)(dir, entry);
+      if ((0, import_node_fs2.statSync)(abs).isDirectory()) {
+        walk(abs);
+      } else if (SCANNABLE_EXTENSIONS.some((ext) => entry.endsWith(ext))) {
+        results.push((0, import_node_path2.relative)(projectRoot, abs));
+      }
+    }
+  };
+  walk(srcDir);
+  return results;
+}
+function readAppSources(projectRoot, appSources) {
+  return appSources.map((rel) => (0, import_node_path2.join)(projectRoot, rel)).filter((abs) => (0, import_node_fs2.existsSync)(abs)).map((abs) => (0, import_node_fs2.readFileSync)(abs, "utf8")).join("\n");
+}
+function stripComments(source) {
+  return source.replace(/\/\*[\s\S]*?\*\//g, " ").replace(/\/\/[^\n]*/g, " ");
+}
+function idPropPatterns(prop, id) {
+  return [
+    `${prop}="${id}"`,
+    `${prop}='${id}'`,
+    `${prop}={'${id}'}`,
+    `${prop}={"${id}"}`,
+    `${prop}={\`${id}\`}`
+  ];
+}
+function extractStringConstants(source) {
+  const stripped = stripComments(source);
+  const map = /* @__PURE__ */ new Map();
+  const re = /(?:export\s+)?(?:const|let|var)\s+(\w+)\s*=\s*(["'`])((?:\\.|(?!\2).)*)\2/g;
+  for (const match of stripped.matchAll(re)) {
+    map.set(match[1], match[3]);
+  }
+  return map;
+}
+function idUsedViaConstant(stripped, prop, id, constants) {
+  for (const [name, value] of constants) {
+    if (value !== id) continue;
+    const jsxPatterns = [
+      `${prop}={${name}}`,
+      `${prop}={ ${name} }`,
+      `${prop}={${name} }`,
+      `${prop}={ ${name}}`
+    ];
+    if (jsxPatterns.some((p) => stripped.includes(p))) return true;
+    const objPatterns = [`${prop}: ${name}`, `${prop}:${name}`];
+    if (objPatterns.some((p) => stripped.includes(p))) return true;
+  }
+  return false;
+}
+function courseIdPresent(source, courseId) {
+  const stripped = stripComments(source);
+  if (idPropPatterns("courseId", courseId).some((p) => stripped.includes(p))) return true;
+  return idUsedViaConstant(stripped, "courseId", courseId, extractStringConstants(source));
+}
+function checkIdPresent(source, checkId) {
+  const stripped = stripComments(source);
+  if (idPropPatterns("checkId", checkId).some((p) => stripped.includes(p))) return true;
+  return idUsedViaConstant(stripped, "checkId", checkId, extractStringConstants(source));
+}
+function validateReactManifestParity(opts) {
+  const appSources = opts.appSources ?? collectSourceUnderSrc(opts.projectRoot);
+  const source = readAppSources(opts.projectRoot, appSources);
+  const hasDescriptorIds = Boolean(opts.descriptor.courseId) || (opts.descriptor.assessments?.length ?? 0) > 0;
+  if (!source.trim()) {
+    return [
+      {
+        path: appSources.length > 0 ? appSources.join(", ") : "src/",
+        message: hasDescriptorIds ? "React app source not found for ID parity check" : "React app source not found for ID parity check",
+        severity: hasDescriptorIds ? "error" : "warning"
+      }
+    ];
+  }
+  const issues = [];
+  const courseId = opts.descriptor.courseId;
+  if (!courseIdPresent(source, courseId)) {
+    issues.push({
+      path: "course.courseId",
+      message: `React app source does not reference courseId="${courseId}" from lessonkit.json`,
+      severity: "error"
+    });
+  }
+  for (const assessment of opts.descriptor.assessments ?? []) {
+    const checkId = assessment.checkId;
+    if (!checkId) continue;
+    if (!checkIdPresent(source, checkId)) {
+      issues.push({
+        path: `assessments.checkId:${checkId}`,
+        message: `React app source missing checkId="${checkId}" declared in lessonkit.json`,
+        severity: "error"
+      });
+    }
+  }
+  return issues;
+}
+
+// src/validateProjectPaths.ts
+var import_node_path3 = require("path");
 function validatePathField(value, fieldPath, projectRoot, issues) {
   if (!isSafeRelativeSpaPath(value)) {
     issues.push({
@@ -729,7 +836,7 @@ function validatePathField(value, fieldPath, projectRoot, issues) {
     return;
   }
   try {
-    assertRealPathUnderRoot(projectRoot, (0, import_node_path2.resolve)(projectRoot, value));
+    assertRealPathUnderRoot(projectRoot, (0, import_node_path3.resolve)(projectRoot, value));
   } catch {
     issues.push({
       path: fieldPath,
@@ -739,7 +846,7 @@ function validatePathField(value, fieldPath, projectRoot, issues) {
 }
 function validateProjectPaths(projectRoot, paths) {
   const issues = [];
-  const root = (0, import_node_path2.resolve)(projectRoot);
+  const root = (0, import_node_path3.resolve)(projectRoot);
   if (paths.spaDistDir?.trim()) {
     validatePathField(paths.spaDistDir.trim(), "paths.spaDistDir", root, issues);
   }
@@ -752,20 +859,20 @@ function validateProjectPaths(projectRoot, paths) {
   return issues;
 }
 function resolveSafePackageOutputOverride(projectRoot, override) {
-  const root = (0, import_node_path2.resolve)(projectRoot);
+  const root = (0, import_node_path3.resolve)(projectRoot);
   const trimmed = override.trim();
   if (!trimmed) {
     throw new Error("output override must be a non-empty path");
   }
-  if ((0, import_node_path2.isAbsolute)(trimmed)) {
-    const resolved2 = (0, import_node_path2.resolve)(trimmed);
+  if ((0, import_node_path3.isAbsolute)(trimmed)) {
+    const resolved2 = (0, import_node_path3.resolve)(trimmed);
     assertRealPathUnderRoot(root, resolved2);
     return resolved2;
   }
   if (!isSafeRelativeSpaPath(trimmed)) {
     throw new Error(`unsafe output path: ${override}`);
   }
-  const resolved = (0, import_node_path2.resolve)(root, trimmed);
+  const resolved = (0, import_node_path3.resolve)(root, trimmed);
   assertRealPathUnderRoot(root, resolved);
   return resolved;
 }
@@ -841,21 +948,21 @@ function descriptorToInterchange(descriptor) {
 }
 
 // src/writeProject.ts
-var import_node_path4 = require("path");
+var import_node_path5 = require("path");
 var import_validators = require("@lxpack/validators");
 
 // src/spaDirs.ts
 var import_promises = require("fs/promises");
-var import_node_path3 = require("path");
+var import_node_path4 = require("path");
 async function resolveSpaDirs(options) {
   const { descriptor, spaDistDir, lessonSpaDirs, projectRoot } = options;
   const spaLessons = resolveSpaLessons(descriptor);
   if (descriptor.layout === "single-spa") {
     const spaDistRelative = spaDistDir ?? descriptor.spaDistDir ?? /* v8 ignore next */
     "dist";
-    const srcDist = projectRoot ? (0, import_node_path3.resolve)(projectRoot, spaDistRelative) : (0, import_node_path3.resolve)(spaDistRelative);
+    const srcDist = projectRoot ? (0, import_node_path4.resolve)(projectRoot, spaDistRelative) : (0, import_node_path4.resolve)(spaDistRelative);
     if (projectRoot) {
-      assertRealPathUnderRoot((0, import_node_path3.resolve)(projectRoot), srcDist);
+      assertRealPathUnderRoot((0, import_node_path4.resolve)(projectRoot), srcDist);
     }
     try {
       await (0, import_promises.access)(srcDist);
@@ -863,9 +970,9 @@ async function resolveSpaDirs(options) {
       throw new Error(`spaDistDir not found: ${srcDist}`);
     }
     try {
-      await (0, import_promises.access)((0, import_node_path3.join)(srcDist, "index.html"));
+      await (0, import_promises.access)((0, import_node_path4.join)(srcDist, "index.html"));
     } catch {
-      throw new Error(`spaDistDir must contain index.html: ${(0, import_node_path3.join)(srcDist, "index.html")}`);
+      throw new Error(`spaDistDir must contain index.html: ${(0, import_node_path4.join)(srcDist, "index.html")}`);
     }
     const lessonId = spaLessons[0]?.id ?? /* v8 ignore next */
     "main";
@@ -878,9 +985,9 @@ async function resolveSpaDirs(options) {
     if (!src) {
       throw new Error(`lessonSpaDirs missing build output for lesson "${lesson.id}"`);
     }
-    const resolved = projectRoot ? (0, import_node_path3.resolve)(projectRoot, src) : (0, import_node_path3.resolve)(src);
+    const resolved = projectRoot ? (0, import_node_path4.resolve)(projectRoot, src) : (0, import_node_path4.resolve)(src);
     if (projectRoot) {
-      assertRealPathUnderRoot((0, import_node_path3.resolve)(projectRoot), resolved);
+      assertRealPathUnderRoot((0, import_node_path4.resolve)(projectRoot), resolved);
     }
     try {
       await (0, import_promises.access)(resolved);
@@ -888,10 +995,10 @@ async function resolveSpaDirs(options) {
       throw new Error(`lessonSpaDirs path not found for lesson "${lesson.id}": ${resolved}`);
     }
     try {
-      await (0, import_promises.access)((0, import_node_path3.join)(resolved, "index.html"));
+      await (0, import_promises.access)((0, import_node_path4.join)(resolved, "index.html"));
     } catch {
       throw new Error(
-        `lessonSpaDirs must contain index.html for lesson "${lesson.id}": ${(0, import_node_path3.join)(resolved, "index.html")}`
+        `lessonSpaDirs must contain index.html for lesson "${lesson.id}": ${(0, import_node_path4.join)(resolved, "index.html")}`
       );
     }
     dirs[lesson.id] = resolved;
@@ -908,9 +1015,9 @@ async function writeLxpackProject(options) {
     );
   }
   const descriptor = validation.descriptor;
-  const outDir = (0, import_node_path4.resolve)(options.outDir);
+  const outDir = (0, import_node_path5.resolve)(options.outDir);
   if (options.projectRoot) {
-    assertRealPathUnderRoot((0, import_node_path4.resolve)(options.projectRoot), outDir);
+    assertRealPathUnderRoot((0, import_node_path5.resolve)(options.projectRoot), outDir);
   }
   const spaDirs = await resolveSpaDirs({ ...options, descriptor });
   const interchange = descriptorToInterchange(descriptor);
@@ -928,21 +1035,21 @@ async function writeLxpackProject(options) {
   const courseDir = materialized.courseDir;
   return {
     outDir: courseDir,
-    courseYamlPath: (0, import_node_path4.join)(courseDir, "course.yaml"),
-    lessonkitJsonPath: (0, import_node_path4.join)(courseDir, "lessonkit.json")
+    courseYamlPath: (0, import_node_path5.join)(courseDir, "course.yaml"),
+    lessonkitJsonPath: (0, import_node_path5.join)(courseDir, "lessonkit.json")
   };
 }
 
 // src/packageCourse.ts
-var import_node_path8 = require("path");
+var import_node_path9 = require("path");
 var fsp3 = __toESM(require("fs/promises"), 1);
 var import_api2 = require("@lxpack/api");
 
 // src/packaging/validateInputs.ts
-var import_node_path5 = require("path");
+var import_node_path6 = require("path");
 function validatePackageInputs(options) {
   const { target, output, outputBaseDir } = options;
-  const outDir = (0, import_node_path5.resolve)(options.outDir);
+  const outDir = (0, import_node_path6.resolve)(options.outDir);
   if (!options.projectRoot) {
     return {
       ok: false,
@@ -951,7 +1058,7 @@ function validatePackageInputs(options) {
       issues: [{ path: "projectRoot", message: "projectRoot is required for packageLessonkitCourse" }]
     };
   }
-  const projectRoot = (0, import_node_path5.resolve)(options.projectRoot);
+  const projectRoot = (0, import_node_path6.resolve)(options.projectRoot);
   try {
     assertRealPathUnderRoot(projectRoot, outDir);
   } catch (err) {
@@ -979,9 +1086,9 @@ function validatePackageInputs(options) {
     };
   }
   if (output && !isSafeRelativeSpaPath(output)) {
-    if ((0, import_node_path5.isAbsolute)(output)) {
+    if ((0, import_node_path6.isAbsolute)(output)) {
       try {
-        assertRealPathUnderRoot(projectRoot, (0, import_node_path5.resolve)(output));
+        assertRealPathUnderRoot(projectRoot, (0, import_node_path6.resolve)(output));
       } catch (err) {
         return {
           ok: false,
@@ -1008,7 +1115,7 @@ function validatePackageInputs(options) {
     }
   }
   if (outputBaseDir) {
-    const resolvedOutputBase = (0, import_node_path5.resolve)(projectRoot, outputBaseDir);
+    const resolvedOutputBase = (0, import_node_path6.resolve)(projectRoot, outputBaseDir);
     try {
       assertRealPathUnderRoot(projectRoot, resolvedOutputBase);
     } catch (err) {
@@ -1029,7 +1136,7 @@ function validatePackageInputs(options) {
     }
   }
   if (output) {
-    const resolvedOutput = (0, import_node_path5.isAbsolute)(output) ? (0, import_node_path5.resolve)(output) : (0, import_node_path5.resolve)(projectRoot, output);
+    const resolvedOutput = (0, import_node_path6.isAbsolute)(output) ? (0, import_node_path6.resolve)(output) : (0, import_node_path6.resolve)(projectRoot, output);
     try {
       assertRealPathUnderRoot(projectRoot, resolvedOutput);
     } catch (err) {
@@ -1069,20 +1176,20 @@ function remapArtifactPaths(stagingRoot, outDir, artifactPath) {
     throw new Error(`${artifactPath} is outside the staging directory`);
   }
   const rel = relativePathUnderRoot(stagingRoot, resolved);
-  if (rel.startsWith("..") || (0, import_node_path5.isAbsolute)(rel)) {
+  if (rel.startsWith("..") || (0, import_node_path6.isAbsolute)(rel)) {
     throw new Error(`${artifactPath} is outside the staging directory`);
   }
   if (!rel) return outDir;
   if (/^[a-zA-Z]:[/\\]/.test(outDir)) {
-    return import_node_path5.win32.join(outDir, rel.replace(/\//g, import_node_path5.win32.sep));
+    return import_node_path6.win32.join(outDir, rel.replace(/\//g, import_node_path6.win32.sep));
   }
-  return (0, import_node_path5.join)(outDir, rel);
+  return (0, import_node_path6.join)(outDir, rel);
 }
 
 // src/packaging/promote.ts
 var fsp = __toESM(require("fs/promises"), 1);
 var import_node_crypto = require("crypto");
-var import_node_path6 = require("path");
+var import_node_path7 = require("path");
 async function pathExists(path) {
   try {
     await fsp.access(path);
@@ -1102,31 +1209,32 @@ async function renameOrCopy(from, to) {
   }
 }
 function promoteLockPath(outDir) {
-  const parent = (0, import_node_path6.dirname)(outDir);
-  const hash = (0, import_node_crypto.createHash)("sha256").update((0, import_node_path6.resolve)(outDir)).digest("hex").slice(0, 16);
-  return (0, import_node_path6.join)(parent, `.lk-promote-lock-${hash}`);
+  const parent = (0, import_node_path7.dirname)(outDir);
+  const hash = (0, import_node_crypto.createHash)("sha256").update((0, import_node_path7.resolve)(outDir)).digest("hex").slice(0, 16);
+  return (0, import_node_path7.join)(parent, `.lk-promote-lock-${hash}`);
 }
 var STALE_LOCK_TTL_MS = 5 * 60 * 1e3;
 async function isStalePromoteLock(lockPath) {
   try {
-    const stat2 = await fsp.stat(lockPath);
-    if (Date.now() - stat2.mtimeMs > STALE_LOCK_TTL_MS) return true;
     const content = await fsp.readFile(lockPath, "utf8");
     const pid = Number.parseInt(content.trim(), 10);
-    if (!Number.isFinite(pid) || pid <= 0) return true;
-    try {
-      process.kill(pid, 0);
-      return false;
-    } catch {
-      return true;
+    if (Number.isFinite(pid) && pid > 0) {
+      try {
+        process.kill(pid, 0);
+        return false;
+      } catch {
+        return true;
+      }
     }
+    const stat2 = await fsp.stat(lockPath);
+    return Date.now() - stat2.mtimeMs > STALE_LOCK_TTL_MS;
   } catch {
     return true;
   }
 }
 async function withPromoteLock(outDir, fn) {
   const lockPath = promoteLockPath(outDir);
-  await fsp.mkdir((0, import_node_path6.dirname)(outDir), { recursive: true });
+  await fsp.mkdir((0, import_node_path7.dirname)(outDir), { recursive: true });
   let lockHandle;
   for (let attempt = 0; attempt < 200; attempt++) {
     try {
@@ -1178,11 +1286,11 @@ async function assertNoLegacyPromoteArtifacts(outDir) {
 async function promoteStagingToOutDir(stagingDir, outDir) {
   return withPromoteLock(outDir, async () => {
     await assertNoLegacyPromoteArtifacts(outDir);
-    const parent = (0, import_node_path6.dirname)(outDir);
-    const tmpPromote = await fsp.mkdtemp((0, import_node_path6.join)(parent, ".lk-promote-"));
+    const parent = (0, import_node_path7.dirname)(outDir);
+    const tmpPromote = await fsp.mkdtemp((0, import_node_path7.join)(parent, ".lk-promote-"));
     await renameOrCopy(stagingDir, tmpPromote);
     const hadOutDir = await pathExists(outDir);
-    const backup = hadOutDir ? await fsp.mkdtemp((0, import_node_path6.join)(parent, ".lk-backup-")) : void 0;
+    const backup = hadOutDir ? await fsp.mkdtemp((0, import_node_path7.join)(parent, ".lk-backup-")) : void 0;
     if (hadOutDir && backup) {
       await renameOrCopy(outDir, backup);
     }
@@ -1193,7 +1301,7 @@ async function promoteStagingToOutDir(stagingDir, outDir) {
         try {
           await renameOrCopy(backup, outDir);
         } catch (restoreError) {
-          const failedPromote2 = (0, import_node_path6.join)(parent, `.lk-failed-promote-${(0, import_node_crypto.randomUUID)()}`);
+          const failedPromote2 = (0, import_node_path7.join)(parent, `.lk-failed-promote-${(0, import_node_crypto.randomUUID)()}`);
           try {
             await renameOrCopy(tmpPromote, failedPromote2);
           } catch {
@@ -1223,7 +1331,7 @@ async function promoteStagingToOutDir(stagingDir, outDir) {
         }
         throw promoteError;
       }
-      const failedPromote = (0, import_node_path6.join)(parent, `.lk-failed-promote-${(0, import_node_crypto.randomUUID)()}`);
+      const failedPromote = (0, import_node_path7.join)(parent, `.lk-failed-promote-${(0, import_node_crypto.randomUUID)()}`);
       try {
         await renameOrCopy(tmpPromote, failedPromote);
       } catch {
@@ -1245,12 +1353,12 @@ async function promoteStagingToOutDir(stagingDir, outDir) {
 
 // src/packaging/staging.ts
 var fsp2 = __toESM(require("fs/promises"), 1);
-var import_node_path7 = require("path");
+var import_node_path8 = require("path");
 var import_node_os = require("os");
 var import_api = require("@lxpack/api");
 async function buildStagingPackage(options) {
   const { target, output, dir, outputBaseDir, descriptor, ...writeOpts } = options;
-  const stagingDir = await fsp2.mkdtemp((0, import_node_path7.join)((0, import_node_os.tmpdir)(), "lessonkit-lxpack-"));
+  const stagingDir = await fsp2.mkdtemp((0, import_node_path8.join)((0, import_node_os.tmpdir)(), "lessonkit-lxpack-"));
   try {
     let spaDirs;
     try {
@@ -1269,8 +1377,8 @@ async function buildStagingPackage(options) {
     }
     const interchange = descriptorToInterchange(descriptor);
     const outputBase = outputBaseDir ?? ".lxpack/out";
-    await fsp2.mkdir((0, import_node_path7.join)(stagingDir, outputBase), { recursive: true });
-    const defaultOutput = output ?? (dir ? (0, import_node_path7.join)(outputBase, target) : (0, import_node_path7.join)(outputBase, `course-${target}.zip`));
+    await fsp2.mkdir((0, import_node_path8.join)(stagingDir, outputBase), { recursive: true });
+    const defaultOutput = output ?? (dir ? (0, import_node_path8.join)(outputBase, target) : (0, import_node_path8.join)(outputBase, `course-${target}.zip`));
     const build = await (0, import_api.packageLessonkit)({
       interchange,
       spaDirs,
@@ -1310,7 +1418,7 @@ async function buildStagingPackage(options) {
   }
 }
 async function ensureOutDirParent(outDir) {
-  await fsp2.mkdir((0, import_node_path7.dirname)(outDir), { recursive: true });
+  await fsp2.mkdir((0, import_node_path8.dirname)(outDir), { recursive: true });
 }
 
 // src/packaging/issueSeverity.ts
@@ -1325,13 +1433,13 @@ function findPackagingErrorIssues(issues) {
 // src/packageCourse.ts
 async function validateLessonkitProject(options) {
   return (0, import_api2.validateCourse)({
-    courseDir: (0, import_node_path8.resolve)(options.courseDir),
+    courseDir: (0, import_node_path9.resolve)(options.courseDir),
     target: options.target
   });
 }
 async function buildLessonkitProject(options) {
   const buildOptions = {
-    courseDir: (0, import_node_path8.resolve)(options.courseDir),
+    courseDir: (0, import_node_path9.resolve)(options.courseDir),
     target: options.target,
     output: options.output,
     dir: options.dir,
@@ -1362,7 +1470,7 @@ async function packageLessonkitCourse(options) {
   if (!descriptorValidation.ok) {
     return {
       ok: false,
-      courseDir: (0, import_node_path8.resolve)(writeOpts.outDir),
+      courseDir: (0, import_node_path9.resolve)(writeOpts.outDir),
       target,
       issues: descriptorValidation.issues.map((i) => ({
         path: i.path,
@@ -1371,6 +1479,25 @@ async function packageLessonkitCourse(options) {
     };
   }
   const descriptor = descriptorValidation.descriptor;
+  if (writeOpts.projectRoot) {
+    const parityIssues = validateReactManifestParity({
+      projectRoot: writeOpts.projectRoot,
+      descriptor
+    });
+    const parityErrors = parityIssues.filter((i) => i.severity === "error");
+    if (parityErrors.length > 0) {
+      return {
+        ok: false,
+        courseDir: outDir,
+        target,
+        issues: parityErrors.map((i) => ({
+          path: i.path,
+          message: i.message,
+          severity: i.severity
+        }))
+      };
+    }
+  }
   const nonInjectableAssessments = (descriptor.assessments ?? []).map((assessment, index) => ({ assessment, index })).filter(({ assessment }) => assessmentDescriptorToLxpack(assessment) === null);
   if (nonInjectableAssessments.length > 0) {
     return {
@@ -1675,5 +1802,6 @@ var import_validators2 = require("@lxpack/validators");
   validateLessonkitProject,
   validatePackageInputs,
   validateProjectPaths,
+  validateReactManifestParity,
   writeLxpackProject
 });

package/dist/index.d.cts

@@ -110,6 +110,23 @@ type DescriptorValidationResult = {
 declare function validateDescriptor(input: unknown): DescriptorValidationResult;
 declare function validateDescriptorForTarget(input: unknown, target?: ExportTarget): DescriptorValidationResult;
 
+type ReactParityIssue = {
+    path: string;
+    message: string;
+    severity: "error" | "warning";
+};
+type ValidateReactManifestParityOptions = {
+    projectRoot: string;
+    descriptor: LessonkitCourseDescriptor;
+    /** Relative source files to scan (default: all `.tsx` under `src/`). */
+    appSources?: string[];
+};
+/**
+ * Validates that React app source references the same courseId and assessment checkIds
+ * as the lessonkit.json descriptor (prevents LMS/runtime ID drift at package time).
+ */
+declare function validateReactManifestParity(opts: ValidateReactManifestParityOptions): ReactParityIssue[];
+
 type ProjectPathsInput = {
     spaDistDir?: string;
     lxpackOutDir?: string;
@@ -308,4 +325,4 @@ type ParseManifestResult = {
 declare function parseLessonkitManifest(raw: unknown, label?: string, projectRoot?: string): ParseManifestResult;
 declare function loadLessonkitManifestFromFile(readJson: () => Promise<unknown>, label?: string, projectRoot?: string): Promise<ParseManifestResult>;
 
-export { type AssessmentDescriptor, type BuildLessonkitProjectOptions, type BuildStagingPackageOptions, type BuildStagingPackageResult, type DescriptorValidationIssue, type DescriptorValidationResult, type FillInBlanksAssessmentDescriptor, type LessonDescriptor, type LessonkitCourseDescriptor, type LessonkitManifest, type LessonkitManifestPaths, type LxpackInjectedAssessment, type LxpackRuntimeTheme, type ManifestParseIssue, type MappedLessonkitIds, type McqAssessmentDescriptor, type PackageLessonkitCourseOptions, type PackageLessonkitCourseResult, type PackageValidationIssue, type ParseManifestResult, type ProjectPathsInput, type SpaLayout, type SpaLessonEntry, type TrueFalseAssessmentDescriptor, type ValidateLessonkitProjectOptions, type ValidatePackageInputsResult, type ValidationIssue, type WriteLxpackProjectOptions, type WriteLxpackProjectResult, assessmentDescriptorToLxpack, buildLessonkitProject, buildStagingPackage, descriptorToInterchange, ensureOutDirParent, extractAssessments, loadLessonkitManifestFromFile, mapLessonkitIds, packageLessonkitCourse, parseLessonkitManifest, promoteStagingToOutDir, remapArtifactPaths, resolveSafePackageOutputOverride, resolveSpaLessons, themeToLxpackRuntime, validateDescriptor, validateDescriptorForTarget, validateLessonkitProject, validatePackageInputs, validateProjectPaths, writeLxpackProject };
+export { type AssessmentDescriptor, type BuildLessonkitProjectOptions, type BuildStagingPackageOptions, type BuildStagingPackageResult, type DescriptorValidationIssue, type DescriptorValidationResult, type FillInBlanksAssessmentDescriptor, type LessonDescriptor, type LessonkitCourseDescriptor, type LessonkitManifest, type LessonkitManifestPaths, type LxpackInjectedAssessment, type LxpackRuntimeTheme, type ManifestParseIssue, type MappedLessonkitIds, type McqAssessmentDescriptor, type PackageLessonkitCourseOptions, type PackageLessonkitCourseResult, type PackageValidationIssue, type ParseManifestResult, type ProjectPathsInput, type ReactParityIssue, type SpaLayout, type SpaLessonEntry, type TrueFalseAssessmentDescriptor, type ValidateLessonkitProjectOptions, type ValidatePackageInputsResult, type ValidationIssue, type WriteLxpackProjectOptions, type WriteLxpackProjectResult, assessmentDescriptorToLxpack, buildLessonkitProject, buildStagingPackage, descriptorToInterchange, ensureOutDirParent, extractAssessments, loadLessonkitManifestFromFile, mapLessonkitIds, packageLessonkitCourse, parseLessonkitManifest, promoteStagingToOutDir, remapArtifactPaths, resolveSafePackageOutputOverride, resolveSpaLessons, themeToLxpackRuntime, validateDescriptor, validateDescriptorForTarget, validateLessonkitProject, validatePackageInputs, validateProjectPaths, validateReactManifestParity, writeLxpackProject };

package/dist/index.d.ts

@@ -110,6 +110,23 @@ type DescriptorValidationResult = {
 declare function validateDescriptor(input: unknown): DescriptorValidationResult;
 declare function validateDescriptorForTarget(input: unknown, target?: ExportTarget): DescriptorValidationResult;
 
+type ReactParityIssue = {
+    path: string;
+    message: string;
+    severity: "error" | "warning";
+};
+type ValidateReactManifestParityOptions = {
+    projectRoot: string;
+    descriptor: LessonkitCourseDescriptor;
+    /** Relative source files to scan (default: all `.tsx` under `src/`). */
+    appSources?: string[];
+};
+/**
+ * Validates that React app source references the same courseId and assessment checkIds
+ * as the lessonkit.json descriptor (prevents LMS/runtime ID drift at package time).
+ */
+declare function validateReactManifestParity(opts: ValidateReactManifestParityOptions): ReactParityIssue[];
+
 type ProjectPathsInput = {
     spaDistDir?: string;
     lxpackOutDir?: string;
@@ -308,4 +325,4 @@ type ParseManifestResult = {
 declare function parseLessonkitManifest(raw: unknown, label?: string, projectRoot?: string): ParseManifestResult;
 declare function loadLessonkitManifestFromFile(readJson: () => Promise<unknown>, label?: string, projectRoot?: string): Promise<ParseManifestResult>;
 
-export { type AssessmentDescriptor, type BuildLessonkitProjectOptions, type BuildStagingPackageOptions, type BuildStagingPackageResult, type DescriptorValidationIssue, type DescriptorValidationResult, type FillInBlanksAssessmentDescriptor, type LessonDescriptor, type LessonkitCourseDescriptor, type LessonkitManifest, type LessonkitManifestPaths, type LxpackInjectedAssessment, type LxpackRuntimeTheme, type ManifestParseIssue, type MappedLessonkitIds, type McqAssessmentDescriptor, type PackageLessonkitCourseOptions, type PackageLessonkitCourseResult, type PackageValidationIssue, type ParseManifestResult, type ProjectPathsInput, type SpaLayout, type SpaLessonEntry, type TrueFalseAssessmentDescriptor, type ValidateLessonkitProjectOptions, type ValidatePackageInputsResult, type ValidationIssue, type WriteLxpackProjectOptions, type WriteLxpackProjectResult, assessmentDescriptorToLxpack, buildLessonkitProject, buildStagingPackage, descriptorToInterchange, ensureOutDirParent, extractAssessments, loadLessonkitManifestFromFile, mapLessonkitIds, packageLessonkitCourse, parseLessonkitManifest, promoteStagingToOutDir, remapArtifactPaths, resolveSafePackageOutputOverride, resolveSpaLessons, themeToLxpackRuntime, validateDescriptor, validateDescriptorForTarget, validateLessonkitProject, validatePackageInputs, validateProjectPaths, writeLxpackProject };
+export { type AssessmentDescriptor, type BuildLessonkitProjectOptions, type BuildStagingPackageOptions, type BuildStagingPackageResult, type DescriptorValidationIssue, type DescriptorValidationResult, type FillInBlanksAssessmentDescriptor, type LessonDescriptor, type LessonkitCourseDescriptor, type LessonkitManifest, type LessonkitManifestPaths, type LxpackInjectedAssessment, type LxpackRuntimeTheme, type ManifestParseIssue, type MappedLessonkitIds, type McqAssessmentDescriptor, type PackageLessonkitCourseOptions, type PackageLessonkitCourseResult, type PackageValidationIssue, type ParseManifestResult, type ProjectPathsInput, type ReactParityIssue, type SpaLayout, type SpaLessonEntry, type TrueFalseAssessmentDescriptor, type ValidateLessonkitProjectOptions, type ValidatePackageInputsResult, type ValidationIssue, type WriteLxpackProjectOptions, type WriteLxpackProjectResult, assessmentDescriptorToLxpack, buildLessonkitProject, buildStagingPackage, descriptorToInterchange, ensureOutDirParent, extractAssessments, loadLessonkitManifestFromFile, mapLessonkitIds, packageLessonkitCourse, parseLessonkitManifest, promoteStagingToOutDir, remapArtifactPaths, resolveSafePackageOutputOverride, resolveSpaLessons, themeToLxpackRuntime, validateDescriptor, validateDescriptorForTarget, validateLessonkitProject, validatePackageInputs, validateProjectPaths, validateReactManifestParity, writeLxpackProject };

package/dist/index.js

@@ -659,6 +659,112 @@ function validateDescriptorForTarget(input, target) {
   return result;
 }
 
+// src/validateReactParity.ts
+import { readFileSync, existsSync as existsSync2, readdirSync, statSync } from "fs";
+import { join as join2, relative as relative2 } from "path";
+var SCANNABLE_EXTENSIONS = [".tsx", ".ts", ".jsx", ".js"];
+function collectSourceUnderSrc(projectRoot) {
+  const srcDir = join2(projectRoot, "src");
+  if (!existsSync2(srcDir)) return [];
+  const results = [];
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir)) {
+      const abs = join2(dir, entry);
+      if (statSync(abs).isDirectory()) {
+        walk(abs);
+      } else if (SCANNABLE_EXTENSIONS.some((ext) => entry.endsWith(ext))) {
+        results.push(relative2(projectRoot, abs));
+      }
+    }
+  };
+  walk(srcDir);
+  return results;
+}
+function readAppSources(projectRoot, appSources) {
+  return appSources.map((rel) => join2(projectRoot, rel)).filter((abs) => existsSync2(abs)).map((abs) => readFileSync(abs, "utf8")).join("\n");
+}
+function stripComments(source) {
+  return source.replace(/\/\*[\s\S]*?\*\//g, " ").replace(/\/\/[^\n]*/g, " ");
+}
+function idPropPatterns(prop, id) {
+  return [
+    `${prop}="${id}"`,
+    `${prop}='${id}'`,
+    `${prop}={'${id}'}`,
+    `${prop}={"${id}"}`,
+    `${prop}={\`${id}\`}`
+  ];
+}
+function extractStringConstants(source) {
+  const stripped = stripComments(source);
+  const map = /* @__PURE__ */ new Map();
+  const re = /(?:export\s+)?(?:const|let|var)\s+(\w+)\s*=\s*(["'`])((?:\\.|(?!\2).)*)\2/g;
+  for (const match of stripped.matchAll(re)) {
+    map.set(match[1], match[3]);
+  }
+  return map;
+}
+function idUsedViaConstant(stripped, prop, id, constants) {
+  for (const [name, value] of constants) {
+    if (value !== id) continue;
+    const jsxPatterns = [
+      `${prop}={${name}}`,
+      `${prop}={ ${name} }`,
+      `${prop}={${name} }`,
+      `${prop}={ ${name}}`
+    ];
+    if (jsxPatterns.some((p) => stripped.includes(p))) return true;
+    const objPatterns = [`${prop}: ${name}`, `${prop}:${name}`];
+    if (objPatterns.some((p) => stripped.includes(p))) return true;
+  }
+  return false;
+}
+function courseIdPresent(source, courseId) {
+  const stripped = stripComments(source);
+  if (idPropPatterns("courseId", courseId).some((p) => stripped.includes(p))) return true;
+  return idUsedViaConstant(stripped, "courseId", courseId, extractStringConstants(source));
+}
+function checkIdPresent(source, checkId) {
+  const stripped = stripComments(source);
+  if (idPropPatterns("checkId", checkId).some((p) => stripped.includes(p))) return true;
+  return idUsedViaConstant(stripped, "checkId", checkId, extractStringConstants(source));
+}
+function validateReactManifestParity(opts) {
+  const appSources = opts.appSources ?? collectSourceUnderSrc(opts.projectRoot);
+  const source = readAppSources(opts.projectRoot, appSources);
+  const hasDescriptorIds = Boolean(opts.descriptor.courseId) || (opts.descriptor.assessments?.length ?? 0) > 0;
+  if (!source.trim()) {
+    return [
+      {
+        path: appSources.length > 0 ? appSources.join(", ") : "src/",
+        message: hasDescriptorIds ? "React app source not found for ID parity check" : "React app source not found for ID parity check",
+        severity: hasDescriptorIds ? "error" : "warning"
+      }
+    ];
+  }
+  const issues = [];
+  const courseId = opts.descriptor.courseId;
+  if (!courseIdPresent(source, courseId)) {
+    issues.push({
+      path: "course.courseId",
+      message: `React app source does not reference courseId="${courseId}" from lessonkit.json`,
+      severity: "error"
+    });
+  }
+  for (const assessment of opts.descriptor.assessments ?? []) {
+    const checkId = assessment.checkId;
+    if (!checkId) continue;
+    if (!checkIdPresent(source, checkId)) {
+      issues.push({
+        path: `assessments.checkId:${checkId}`,
+        message: `React app source missing checkId="${checkId}" declared in lessonkit.json`,
+        severity: "error"
+      });
+    }
+  }
+  return issues;
+}
+
 // src/validateProjectPaths.ts
 import { isAbsolute as isAbsolute2, resolve as resolve2 } from "path";
 function validatePathField(value, fieldPath, projectRoot, issues) {
@@ -782,12 +888,12 @@ function descriptorToInterchange(descriptor) {
 }
 
 // src/writeProject.ts
-import { join as join3, resolve as resolve4 } from "path";
+import { join as join4, resolve as resolve4 } from "path";
 import { materializeLessonkitProject } from "@lxpack/validators";
 
 // src/spaDirs.ts
 import { access } from "fs/promises";
-import { join as join2, resolve as resolve3 } from "path";
+import { join as join3, resolve as resolve3 } from "path";
 async function resolveSpaDirs(options) {
   const { descriptor, spaDistDir, lessonSpaDirs, projectRoot } = options;
   const spaLessons = resolveSpaLessons(descriptor);
@@ -804,9 +910,9 @@ async function resolveSpaDirs(options) {
       throw new Error(`spaDistDir not found: ${srcDist}`);
     }
     try {
-      await access(join2(srcDist, "index.html"));
+      await access(join3(srcDist, "index.html"));
     } catch {
-      throw new Error(`spaDistDir must contain index.html: ${join2(srcDist, "index.html")}`);
+      throw new Error(`spaDistDir must contain index.html: ${join3(srcDist, "index.html")}`);
     }
     const lessonId = spaLessons[0]?.id ?? /* v8 ignore next */
     "main";
@@ -829,10 +935,10 @@ async function resolveSpaDirs(options) {
       throw new Error(`lessonSpaDirs path not found for lesson "${lesson.id}": ${resolved}`);
     }
     try {
-      await access(join2(resolved, "index.html"));
+      await access(join3(resolved, "index.html"));
     } catch {
       throw new Error(
-        `lessonSpaDirs must contain index.html for lesson "${lesson.id}": ${join2(resolved, "index.html")}`
+        `lessonSpaDirs must contain index.html for lesson "${lesson.id}": ${join3(resolved, "index.html")}`
       );
     }
     dirs[lesson.id] = resolved;
@@ -869,8 +975,8 @@ async function writeLxpackProject(options) {
   const courseDir = materialized.courseDir;
   return {
     outDir: courseDir,
-    courseYamlPath: join3(courseDir, "course.yaml"),
-    lessonkitJsonPath: join3(courseDir, "lessonkit.json")
+    courseYamlPath: join4(courseDir, "course.yaml"),
+    lessonkitJsonPath: join4(courseDir, "lessonkit.json")
   };
 }
 
@@ -883,7 +989,7 @@ import {
 } from "@lxpack/api";
 
 // src/packaging/validateInputs.ts
-import { isAbsolute as isAbsolute3, join as join4, resolve as resolve5, win32 as win322 } from "path";
+import { isAbsolute as isAbsolute3, join as join5, resolve as resolve5, win32 as win322 } from "path";
 function validatePackageInputs(options) {
   const { target, output, outputBaseDir } = options;
   const outDir = resolve5(options.outDir);
@@ -1020,13 +1126,13 @@ function remapArtifactPaths(stagingRoot, outDir, artifactPath) {
   if (/^[a-zA-Z]:[/\\]/.test(outDir)) {
     return win322.join(outDir, rel.replace(/\//g, win322.sep));
   }
-  return join4(outDir, rel);
+  return join5(outDir, rel);
 }
 
 // src/packaging/promote.ts
 import * as fsp from "fs/promises";
 import { createHash, randomUUID } from "crypto";
-import { dirname, join as join5, resolve as resolve6 } from "path";
+import { dirname, join as join6, resolve as resolve6 } from "path";
 async function pathExists(path) {
   try {
     await fsp.access(path);
@@ -1048,22 +1154,23 @@ async function renameOrCopy(from, to) {
 function promoteLockPath(outDir) {
   const parent = dirname(outDir);
   const hash = createHash("sha256").update(resolve6(outDir)).digest("hex").slice(0, 16);
-  return join5(parent, `.lk-promote-lock-${hash}`);
+  return join6(parent, `.lk-promote-lock-${hash}`);
 }
 var STALE_LOCK_TTL_MS = 5 * 60 * 1e3;
 async function isStalePromoteLock(lockPath) {
   try {
-    const stat2 = await fsp.stat(lockPath);
-    if (Date.now() - stat2.mtimeMs > STALE_LOCK_TTL_MS) return true;
     const content = await fsp.readFile(lockPath, "utf8");
     const pid = Number.parseInt(content.trim(), 10);
-    if (!Number.isFinite(pid) || pid <= 0) return true;
-    try {
-      process.kill(pid, 0);
-      return false;
-    } catch {
-      return true;
+    if (Number.isFinite(pid) && pid > 0) {
+      try {
+        process.kill(pid, 0);
+        return false;
+      } catch {
+        return true;
+      }
     }
+    const stat2 = await fsp.stat(lockPath);
+    return Date.now() - stat2.mtimeMs > STALE_LOCK_TTL_MS;
   } catch {
     return true;
   }
@@ -1123,10 +1230,10 @@ async function promoteStagingToOutDir(stagingDir, outDir) {
   return withPromoteLock(outDir, async () => {
     await assertNoLegacyPromoteArtifacts(outDir);
     const parent = dirname(outDir);
-    const tmpPromote = await fsp.mkdtemp(join5(parent, ".lk-promote-"));
+    const tmpPromote = await fsp.mkdtemp(join6(parent, ".lk-promote-"));
     await renameOrCopy(stagingDir, tmpPromote);
     const hadOutDir = await pathExists(outDir);
-    const backup = hadOutDir ? await fsp.mkdtemp(join5(parent, ".lk-backup-")) : void 0;
+    const backup = hadOutDir ? await fsp.mkdtemp(join6(parent, ".lk-backup-")) : void 0;
     if (hadOutDir && backup) {
       await renameOrCopy(outDir, backup);
     }
@@ -1137,7 +1244,7 @@ async function promoteStagingToOutDir(stagingDir, outDir) {
         try {
           await renameOrCopy(backup, outDir);
         } catch (restoreError) {
-          const failedPromote2 = join5(parent, `.lk-failed-promote-${randomUUID()}`);
+          const failedPromote2 = join6(parent, `.lk-failed-promote-${randomUUID()}`);
           try {
             await renameOrCopy(tmpPromote, failedPromote2);
           } catch {
@@ -1167,7 +1274,7 @@ async function promoteStagingToOutDir(stagingDir, outDir) {
         }
         throw promoteError;
       }
-      const failedPromote = join5(parent, `.lk-failed-promote-${randomUUID()}`);
+      const failedPromote = join6(parent, `.lk-failed-promote-${randomUUID()}`);
       try {
         await renameOrCopy(tmpPromote, failedPromote);
       } catch {
@@ -1189,12 +1296,12 @@ async function promoteStagingToOutDir(stagingDir, outDir) {
 
 // src/packaging/staging.ts
 import * as fsp2 from "fs/promises";
-import { dirname as dirname2, join as join6 } from "path";
+import { dirname as dirname2, join as join7 } from "path";
 import { tmpdir } from "os";
 import { packageLessonkit } from "@lxpack/api";
 async function buildStagingPackage(options) {
   const { target, output, dir, outputBaseDir, descriptor, ...writeOpts } = options;
-  const stagingDir = await fsp2.mkdtemp(join6(tmpdir(), "lessonkit-lxpack-"));
+  const stagingDir = await fsp2.mkdtemp(join7(tmpdir(), "lessonkit-lxpack-"));
   try {
     let spaDirs;
     try {
@@ -1213,8 +1320,8 @@ async function buildStagingPackage(options) {
     }
     const interchange = descriptorToInterchange(descriptor);
     const outputBase = outputBaseDir ?? ".lxpack/out";
-    await fsp2.mkdir(join6(stagingDir, outputBase), { recursive: true });
-    const defaultOutput = output ?? (dir ? join6(outputBase, target) : join6(outputBase, `course-${target}.zip`));
+    await fsp2.mkdir(join7(stagingDir, outputBase), { recursive: true });
+    const defaultOutput = output ?? (dir ? join7(outputBase, target) : join7(outputBase, `course-${target}.zip`));
     const build = await packageLessonkit({
       interchange,
       spaDirs,
@@ -1315,6 +1422,25 @@ async function packageLessonkitCourse(options) {
     };
   }
   const descriptor = descriptorValidation.descriptor;
+  if (writeOpts.projectRoot) {
+    const parityIssues = validateReactManifestParity({
+      projectRoot: writeOpts.projectRoot,
+      descriptor
+    });
+    const parityErrors = parityIssues.filter((i) => i.severity === "error");
+    if (parityErrors.length > 0) {
+      return {
+        ok: false,
+        courseDir: outDir,
+        target,
+        issues: parityErrors.map((i) => ({
+          path: i.path,
+          message: i.message,
+          severity: i.severity
+        }))
+      };
+    }
+  }
   const nonInjectableAssessments = (descriptor.assessments ?? []).map((assessment, index) => ({ assessment, index })).filter(({ assessment }) => assessmentDescriptorToLxpack(assessment) === null);
   if (nonInjectableAssessments.length > 0) {
     return {
@@ -1586,5 +1712,6 @@ export {
   validateLessonkitProject,
   validatePackageInputs,
   validateProjectPaths,
+  validateReactManifestParity,
   writeLxpackProject
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/lxpack",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "private": false,
   "description": "LXPack export adapter for LessonKit courses (SCORM, standalone, xAPI, cmi5).",
   "license": "Apache-2.0",
@@ -55,8 +55,8 @@
     "lint": "echo \"(no lint configured yet)\""
   },
   "dependencies": {
-    "@lessonkit/core": "1.3.0",
-    "@lessonkit/themes": "1.3.0",
+    "@lessonkit/core": "1.3.1",
+    "@lessonkit/themes": "1.3.1",
     "@lxpack/api": "^0.6.2",
     "@lxpack/spa-bridge": "^0.6.2",
     "@lxpack/tracking-schema": "^0.6.2",