tessera-learn 0.0.5 → 0.0.7

package/src/plugin/validation.ts

@@ -64,7 +64,15 @@ export function validateProject(projectRoot: string): ValidationResult {
   errors.push(...pageResults.errors);
   warnings.push(...pageResults.warnings);
 
-  // 4. Cross-cutting validations
+  // 4. Contract-bypass checks on project-root shell files
+  for (const shellFile of ['layout.svelte', 'quiz.svelte']) {
+    const shellPath = resolve(projectRoot, shellFile);
+    if (existsSync(shellPath)) {
+      validateContractBypass(readSourceFileCached(shellPath), shellFile, errors);
+    }
+  }
+
+  // 5. Cross-cutting validations
   if (config) {
     crossValidate(config, pageResults, errors, warnings);
   }
@@ -498,6 +506,57 @@ interface PagesValidationResult extends ValidationResult {
   pages: PageInfo[];
 }
 
+/**
+ * Validate a single page .svelte file. Used for both section-level (flat) and
+ * lesson-level pages — the validation is identical, only the containing
+ * directory differs.
+ */
+function validatePageFile(
+  filePath: string,
+  projectRoot: string,
+  assetsDir: string,
+  navIndex: number,
+  errors: string[],
+  warnings: string[],
+  assetExistsCache: Map<string, boolean>
+): { page: PageInfo; isQuiz: boolean; isGradedQuiz: boolean } {
+  const fileRel = relative(projectRoot, filePath);
+  const content = readSourceFileCached(filePath);
+
+  const pageConfig = validatePageConfig(content, fileRel, errors);
+
+  const isQuiz = !!pageConfig?.quiz;
+  let isGradedQuiz = false;
+  if (pageConfig?.quiz) {
+    validateQuizConfig(pageConfig.quiz, fileRel, errors);
+    if ((pageConfig.quiz as { graded?: unknown }).graded === true) {
+      isGradedQuiz = true;
+    }
+  }
+
+  const completesOnView = validateCompletesOn(pageConfig, fileRel, errors);
+
+  validateAssetRefs(content, fileRel, assetsDir, warnings, assetExistsCache);
+  validateQuestionComponents(content, fileRel, errors);
+  validateContractBypass(content, fileRel, errors);
+  if (
+    pageConfig?.quiz &&
+    !HAS_USE_QUESTION_RE.test(content) &&
+    !HAS_QUESTION_TAG_RE.test(content)
+  ) {
+    warnings.push(
+      `${fileRel}: quiz page has no question components or useQuestion() calls — ` +
+        `the quiz will have nothing to score`
+    );
+  }
+
+  return {
+    page: { fileRel, navIndex, hasGradedQuiz: isGradedQuiz, hasQuiz: isQuiz, completesOnView },
+    isQuiz,
+    isGradedQuiz,
+  };
+}
+
 function validatePages(
   pagesDir: string,
   assetsDir: string,
@@ -581,34 +640,19 @@ function validatePages(
     }
 
     for (const fileName of sectionSvelteFiles) {
-      const filePath = resolve(sectionPath, fileName);
-      const fileRel = relative(projectRoot, filePath);
-      const content = readSourceFileCached(filePath);
-
-      const pageConfig = validatePageConfig(content, fileRel, errors);
-      const navIndex = totalPages;
+      const result = validatePageFile(
+        resolve(sectionPath, fileName),
+        projectRoot,
+        assetsDir,
+        totalPages,
+        errors,
+        warnings,
+        assetExistsCache
+      );
       totalPages++;
-
-      let pageHasGradedQuiz = false;
-      if (pageConfig?.quiz) {
-        totalQuizzes++;
-        validateQuizConfig(pageConfig.quiz, fileRel, errors);
-        if ((pageConfig.quiz as { graded?: unknown }).graded === true) {
-          hasGradedQuiz = true;
-          pageHasGradedQuiz = true;
-        }
-      }
-
-      const completesOnView = validateCompletesOn(pageConfig, fileRel, errors);
-      pages.push({
-        fileRel,
-        navIndex,
-        hasGradedQuiz: pageHasGradedQuiz,
-        hasQuiz: !!pageConfig?.quiz,
-        completesOnView,
-      });
-
-      validateAssetRefs(content, fileRel, assetsDir, warnings, assetExistsCache);
+      if (result.isQuiz) totalQuizzes++;
+      if (result.isGradedQuiz) hasGradedQuiz = true;
+      pages.push(result.page);
     }
 
     // Get lesson directories
@@ -663,38 +707,19 @@ function validatePages(
 
       // Validate each .svelte file
       for (const fileName of svelteFiles) {
-        const filePath = resolve(lessonPath, fileName);
-        const fileRel = relative(projectRoot, filePath);
-        const content = readSourceFileCached(filePath);
-
-        const pageConfig = validatePageConfig(content, fileRel, errors);
-        const navIndex = totalPages;
+        const result = validatePageFile(
+          resolve(lessonPath, fileName),
+          projectRoot,
+          assetsDir,
+          totalPages,
+          errors,
+          warnings,
+          assetExistsCache
+        );
         totalPages++;
-
-        let pageHasGradedQuiz = false;
-        if (pageConfig?.quiz) {
-          totalQuizzes++;
-
-          // Validate quiz config
-          validateQuizConfig(pageConfig.quiz, fileRel, errors);
-
-          if ((pageConfig.quiz as { graded?: unknown }).graded === true) {
-            hasGradedQuiz = true;
-            pageHasGradedQuiz = true;
-          }
-        }
-
-        const completesOnView = validateCompletesOn(pageConfig, fileRel, errors);
-        pages.push({
-          fileRel,
-          navIndex,
-          hasGradedQuiz: pageHasGradedQuiz,
-          hasQuiz: !!pageConfig?.quiz,
-          completesOnView,
-        });
-
-        // Check $assets references
-        validateAssetRefs(content, fileRel, assetsDir, warnings, assetExistsCache);
+        if (result.isQuiz) totalQuizzes++;
+        if (result.isGradedQuiz) hasGradedQuiz = true;
+        pages.push(result.page);
       }
     }
   }
@@ -774,7 +799,7 @@ function validateCompletesOn(
 
 function validateQuizConfig(quiz: unknown, fileRel: string, errors: string[]): void {
   if (!quiz || typeof quiz !== 'object') return;
-  const cfg = quiz as { maxAttempts?: unknown; graded?: unknown };
+  const cfg = quiz as Record<string, unknown>;
 
   if (cfg.maxAttempts !== undefined) {
     const val = cfg.maxAttempts;
@@ -785,9 +810,258 @@ function validateQuizConfig(quiz: unknown, fileRel: string, errors: string[]): v
     }
   }
 
-  if (cfg.graded !== undefined && typeof cfg.graded !== 'boolean') {
+  for (const field of ['graded', 'gatesProgress', 'showFeedback']) {
+    if (cfg[field] !== undefined && typeof cfg[field] !== 'boolean') {
+      errors.push(
+        `${fileRel}: quiz.${field} must be a boolean, got ${typeof cfg[field]}`
+      );
+    }
+  }
+}
+
+// ---------- Question Component Validation ----------
+
+const QUESTION_COMPONENT_REQUIRED: Record<string, string[]> = {
+  MultipleChoice: ['question', 'options', 'correct'],
+  FillInTheBlank: ['question', 'answers'],
+  Matching: ['question', 'pairs'],
+  Sorting: ['question', 'items', 'targets', 'correct'],
+};
+
+type PropValue =
+  | { kind: 'string'; value: string }
+  | { kind: 'expr'; raw: string }
+  | { kind: 'bool' };
+
+/** Extract a balanced {...} or [...] span starting at startIndex, or null. */
+function extractBalanced(source: string, startIndex: number): string | null {
+  const open = source[startIndex];
+  if (open !== '{' && open !== '[') return null;
+  let depth = 0;
+  let inString: string | null = null;
+  let escaped = false;
+  for (let i = startIndex; i < source.length; i++) {
+    const char = source[i];
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (char === '\\' && inString) {
+      escaped = true;
+      continue;
+    }
+    if (inString) {
+      if (char === inString) inString = null;
+      continue;
+    }
+    if (char === '"' || char === "'" || char === '`') {
+      inString = char;
+      continue;
+    }
+    if (char === '{' || char === '[') depth++;
+    if (char === '}' || char === ']') {
+      depth--;
+      if (depth === 0) return source.slice(startIndex, i + 1);
+    }
+  }
+  return null;
+}
+
+/**
+ * Parse the props of an opening tag starting just after the component name.
+ * Returns null if the tag can't be parsed cleanly — callers then skip it
+ * rather than risk a false positive.
+ */
+function parseTagProps(content: string, start: number): Map<string, PropValue> | null {
+  const props = new Map<string, PropValue>();
+  let i = start;
+  while (i < content.length) {
+    while (i < content.length && /\s/.test(content[i])) i++;
+    if (i >= content.length) return null;
+    const c = content[i];
+    if (c === '>') return props;
+    if (c === '/' && content[i + 1] === '>') return props;
+    // Spread / shorthand expression — skip the whole {...} block.
+    if (c === '{') {
+      const block = extractBalanced(content, i);
+      if (!block) return null;
+      i += block.length;
+      continue;
+    }
+    const nameMatch = /^[A-Za-z_][\w-]*/.exec(content.slice(i));
+    if (!nameMatch) return null;
+    const propName = nameMatch[0];
+    i += propName.length;
+    while (i < content.length && /\s/.test(content[i])) i++;
+    if (content[i] !== '=') {
+      props.set(propName, { kind: 'bool' });
+      continue;
+    }
+    i++;
+    while (i < content.length && /\s/.test(content[i])) i++;
+    const v = content[i];
+    if (v === '"' || v === "'") {
+      const end = content.indexOf(v, i + 1);
+      if (end === -1) return null;
+      props.set(propName, { kind: 'string', value: content.slice(i + 1, end) });
+      i = end + 1;
+    } else if (v === '{') {
+      const block = extractBalanced(content, i);
+      if (!block) return null;
+      props.set(propName, { kind: 'expr', raw: block.slice(1, -1).trim() });
+      i += block.length;
+    } else {
+      return null;
+    }
+  }
+  return null;
+}
+
+function staticArray(prop: PropValue | undefined): unknown[] | null {
+  if (prop?.kind !== 'expr' || !prop.raw.startsWith('[')) return null;
+  try {
+    const parsed = JSON5.parse(prop.raw);
+    return Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function staticNumber(prop: PropValue | undefined): number | null {
+  if (prop?.kind !== 'expr') return null;
+  try {
+    const parsed = JSON5.parse(prop.raw);
+    return typeof parsed === 'number' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function validateQuestionComponents(
+  content: string,
+  fileRel: string,
+  errors: string[]
+): void {
+  const names = Object.keys(QUESTION_COMPONENT_REQUIRED).join('|');
+  const tagStartRe = new RegExp(`<(${names})(?=[\\s/>])`, 'g');
+  const seenIds = new Set<string>();
+  let m: RegExpExecArray | null;
+  while ((m = tagStartRe.exec(content)) !== null) {
+    const name = m[1];
+    const props = parseTagProps(content, m.index + m[0].length);
+    if (!props) continue;
+
+    for (const req of QUESTION_COMPONENT_REQUIRED[name]) {
+      if (!props.has(req)) {
+        errors.push(`${fileRel}: <${name}> is missing required prop "${req}"`);
+      }
+    }
+
+    const idProp = props.get('id');
+    if (idProp?.kind === 'string') {
+      if (seenIds.has(idProp.value)) {
+        errors.push(
+          `${fileRel}: duplicate question id "${idProp.value}" — each question on a page needs a unique id`
+        );
+      }
+      seenIds.add(idProp.value);
+    }
+
+    if (name === 'MultipleChoice') {
+      const options = staticArray(props.get('options'));
+      const correct = staticNumber(props.get('correct'));
+      if (options && correct !== null) {
+        if (!Number.isInteger(correct) || correct < 0 || correct >= options.length) {
+          errors.push(
+            `${fileRel}: <MultipleChoice> correct={${correct}} is out of range for ${options.length} options (valid: 0–${options.length - 1})`
+          );
+        }
+      }
+    } else if (name === 'Sorting') {
+      const items = staticArray(props.get('items'));
+      const targets = staticArray(props.get('targets'));
+      const correct = staticArray(props.get('correct'));
+      if (items && correct && correct.length !== items.length) {
+        errors.push(
+          `${fileRel}: <Sorting> correct has ${correct.length} entries but items has ${items.length} — they must be parallel arrays`
+        );
+      }
+      if (targets && correct) {
+        for (const idx of correct) {
+          if (
+            typeof idx !== 'number' ||
+            !Number.isInteger(idx) ||
+            idx < 0 ||
+            idx >= targets.length
+          ) {
+            errors.push(
+              `${fileRel}: <Sorting> correct contains ${JSON.stringify(idx)}, out of range for ${targets.length} targets (valid: 0–${targets.length - 1})`
+            );
+            break;
+          }
+        }
+      }
+    } else if (name === 'Matching') {
+      const pairs = staticArray(props.get('pairs'));
+      if (pairs) {
+        const bad = pairs.some(
+          (p) =>
+            typeof p !== 'object' ||
+            p === null ||
+            typeof (p as { left?: unknown }).left !== 'string' ||
+            typeof (p as { right?: unknown }).right !== 'string'
+        );
+        if (bad) {
+          errors.push(
+            `${fileRel}: <Matching> pairs must be an array of { left: string, right: string } objects`
+          );
+        }
+      }
+    } else if (name === 'FillInTheBlank') {
+      const answers = staticArray(props.get('answers'));
+      if (answers) {
+        if (answers.length === 0) {
+          errors.push(`${fileRel}: <FillInTheBlank> answers must not be empty`);
+        } else if (answers.some((a) => typeof a !== 'string')) {
+          errors.push(
+            `${fileRel}: <FillInTheBlank> answers must be an array of strings`
+          );
+        }
+      }
+    }
+  }
+}
+
+// ---------- Contract Bypass Detection ----------
+
+const QUIZ_COMPLETE_DISPATCH_RE =
+  /(?:new\s+CustomEvent\s*\(\s*['"]tessera-quiz-complete['"]|dispatchEvent\s*\([\s\S]{0,120}tessera-quiz-complete)/;
+const RUNTIME_INTERNAL_IMPORT_RE = /from\s+['"]tessera-learn\/runtime\//;
+const HAS_USE_QUESTION_RE = /\buseQuestion\s*\(/;
+const HAS_QUESTION_TAG_RE = new RegExp(
+  `<(${Object.keys(QUESTION_COMPONENT_REQUIRED).join('|')})(?=[\\s/>])`
+);
+
+/**
+ * Detect ways an author file can bypass the LMS data contract. These check
+ * source text for known escape hatches — they never inspect course content,
+ * so they constrain how you wire things up, not what you build.
+ */
+function validateContractBypass(
+  content: string,
+  fileRel: string,
+  errors: string[]
+): void {
+  if (QUIZ_COMPLETE_DISPATCH_RE.test(content)) {
+    errors.push(
+      `${fileRel}: dispatches "tessera-quiz-complete" directly — submit through ` +
+        `useQuiz().submit() so the result reaches the LMS`
+    );
+  }
+  if (RUNTIME_INTERNAL_IMPORT_RE.test(content)) {
     errors.push(
-      `${fileRel}: quiz.graded must be a boolean, got ${typeof cfg.graded}`
+      `${fileRel}: imports from tessera-learn/runtime/* — use the public hooks ` +
+        `(useQuiz, useQuestion, useNavigation, …) instead`
     );
   }
 }

package/src/runtime/adapters/index.ts

@@ -36,7 +36,7 @@ function missingApiError(
     standard,
     `Tessera: this course is configured for ${label} but ${detail} ` +
       `The course must be launched from an LMS that provides the ${label} runtime. ` +
-      `If you are testing locally, run \`npm run preview\` instead, or set export.standard to "web".`
+      `If you are testing locally, run \`npm run dev\` instead, or set export.standard to "web".`
   );
 }
 

package/src/runtime/adapters/retry.ts

@@ -1,13 +1,12 @@
 /**
- * Optional callback that surfaces the LMS's last-error code/message after
- * a failed call, so warning logs can name the actual cause instead of a
- * generic "LMS call failed".
+ * Surfaces LMSGetLastError / LMSGetErrorString / LMSGetDiagnostic so failure
+ * logs can name the cause instead of a generic "LMS call failed". SCORM
+ * Cloud uses the diagnostic to name the offending data-model element.
  */
 export interface LMSErrorReporter {
-  /** Last error from `LMSGetLastError` / `GetLastError`. */
   code(): string;
-  /** Human-readable message from `LMSGetErrorString` / `GetErrorString`. */
   message(code: string): string;
+  diagnostic?(code: string): string;
 }
 
 /** Default attempt count for LMS retry loops (one initial + two retries). */
@@ -33,19 +32,53 @@ function logRetryGiveUp(
   lastErrCode: string,
   context: string | undefined
 ): void {
-  let detail = '';
-  if (errorReporter && lastErrCode && lastErrCode !== '0') {
-    try {
-      const msg = errorReporter.message(lastErrCode);
-      detail = ` (LMS error ${lastErrCode}${msg ? `: ${msg}` : ''})`;
-    } catch {}
-  }
   const ctx = context ? ` [${context}]` : '';
   console.warn(
-    `Tessera: LMS call failed after retries${ctx}${detail}, continuing without persistence`
+    `Tessera: LMS call failed after retries${ctx}${formatLMSErrorDetail(errorReporter, lastErrCode)}, continuing without persistence`
   );
 }
 
+export function formatLMSErrorDetail(
+  errorReporter: LMSErrorReporter | undefined,
+  code: string
+): string {
+  if (!errorReporter || !code || code === '0') return '';
+  let msg = '';
+  let diag = '';
+  try { msg = errorReporter.message(code); } catch {}
+  try { diag = errorReporter.diagnostic?.(code) ?? ''; } catch {}
+  let detail = ` (LMS error ${code}`;
+  if (msg) detail += `: ${msg}`;
+  if (diag && diag !== msg) detail += ` — ${diag}`;
+  detail += ')';
+  return detail;
+}
+
+/** Sync call that warns with the LMS error code on failure (terminate-path). */
+export function callSyncOrWarn(
+  fn: () => any,
+  context: string,
+  errorReporter?: LMSErrorReporter
+): boolean {
+  let ok = false;
+  try {
+    ok = lmsCallSucceeded(fn());
+  } catch (err) {
+    console.warn(
+      `Tessera: LMS call threw [${context}] during terminate`,
+      err
+    );
+    return false;
+  }
+  if (!ok) {
+    const code = readLastErrorCode(errorReporter);
+    console.warn(
+      `Tessera: LMS call failed [${context}] during terminate${formatLMSErrorDetail(errorReporter, code)}`
+    );
+  }
+  return ok;
+}
+
 /**
  * Retry wrapper for LMS API calls.
  * Retries up to maxRetries times with exponential backoff.
@@ -68,17 +101,25 @@ export async function withRetry(
   context?: string
 ): Promise<boolean> {
   let lastErrCode = '';
+  let threw = false;
+  let lastError: unknown;
   for (let attempt = 0; attempt < maxRetries; attempt++) {
+    threw = false;
     try {
       if (lmsCallSucceeded(fn())) return true;
-    } catch {
-      // API call threw — treat as failure
+    } catch (err) {
+      threw = true;
+      lastError = err;
     }
     lastErrCode = readLastErrorCode(errorReporter);
     if (attempt < maxRetries - 1) {
       await new Promise((r) => setTimeout(r, backoffMs(attempt)));
     }
   }
+  if (threw) {
+    const ctx = context ? ` [${context}]` : '';
+    console.warn(`Tessera: LMS call threw${ctx} on final retry`, lastError);
+  }
   logRetryGiveUp(errorReporter, lastErrCode, context);
   return false;
 }
@@ -275,6 +316,36 @@ export function formatHHMMSS(totalSeconds: number): string {
   return `${hh}:${mm}:${ss}.00`;
 }
 
+/**
+ * SCORM 2004 4E §4.2/§4.3 define CMIDecimal-like elements as real(10,7) —
+ * `String(1/3)` exceeds that and trips SCORM Cloud with error 406. Rounds,
+ * then trims trailing zeros (no padded "0.8500000" forms).
+ */
+export function formatReal107(value: number): string {
+  if (!Number.isFinite(value)) return '0';
+  const rounded = Math.round(value * 1e7) / 1e7;
+  return rounded
+    .toFixed(7)
+    .replace(/(\.\d*?)0+$/, '$1')
+    .replace(/\.$/, '');
+}
+
+/**
+ * SCORM 2004 4E §3.3.10.1 references ISO 8601 §5.3.3 — local date+time, no
+ * zone designator. Strict validators reject `Z`, `±hh:mm`, and fractional
+ * seconds with error 406. UTC components are used so writes don't drift
+ * across local-TZ flips even though the format is zone-free.
+ */
+export function formatISO8601Timestamp(date: Date): string {
+  const yyyy = date.getUTCFullYear();
+  const mm = String(date.getUTCMonth() + 1).padStart(2, '0');
+  const dd = String(date.getUTCDate()).padStart(2, '0');
+  const hh = String(date.getUTCHours()).padStart(2, '0');
+  const mi = String(date.getUTCMinutes()).padStart(2, '0');
+  const ss = String(date.getUTCSeconds()).padStart(2, '0');
+  return `${yyyy}-${mm}-${dd}T${hh}:${mi}:${ss}`;
+}
+
 /**
  * Format seconds as ISO 8601 duration: PT1H30M45S
  */