tessera-learn 0.0.13 → 0.1.0

package/src/plugin/validation.ts

@@ -3,17 +3,26 @@ import { resolve, relative } from 'node:path';
 import JSON5 from 'json5';
 import {
   extractDefaultExportObjectLiteral,
-  extractObjectLiteral,
   parsePageConfigFromSource,
   readSourceFileCached,
   ensureSvelteSuffix,
   readCourseConfig,
+  orderPageFiles,
+  walkPages,
+  type WalkedLesson,
 } from './manifest.js';
+import {
+  clearParseCache,
+  findComponents,
+  getParseError,
+  type PropValue,
+} from './ast.js';
 import {
   validateAgent,
   validateAuthCredential,
   joinFieldError,
 } from '../runtime/xapi/agent-rules.js';
+import { httpOrigin } from '../runtime/xapi/derive-actor.js';
 import { shortIdentifier } from '../runtime/interaction-format.js';
 import { FEEDBACK_MODES, RETRY_MODES } from '../runtime/types.js';
 import { contrastRatio } from './a11y/contrast.js';
@@ -174,6 +183,7 @@ const VALID_RETRY_MODES: readonly string[] = RETRY_MODES;
  * Returns errors (block build) and warnings (informational).
  */
 export function validateProject(projectRoot: string): ValidationResult {
+  clearParseCache();
   const errors: string[] = [];
   const warnings: string[] = [];
 
@@ -246,12 +256,10 @@ function parseConfig(
   if (!read.ok) {
     // 'missing' can't occur — validateProject checks existsSync first.
     if (read.reason === 'no-export') {
-      errors.push(
-        'course.config.js: could not parse — must use `export default { ... }` syntax',
-      );
+      errors.push('course.config.js: must use `export default { ... }` syntax');
     } else if (read.reason === 'parse-error') {
       errors.push(
-        'course.config.js: syntax error — must export a static object literal',
+        'course.config.js: could not parse — JavaScript syntax error',
       );
     }
     return null;
@@ -426,10 +434,14 @@ function isPlausibleColor(value: string): boolean {
  * on primaryColor. Runtime failures are mild: an unresolved logo ships a broken
  * <img src>, an unparseable color falls back to theme defaults.
  */
+function describeType(raw: unknown): string {
+  return raw === null ? 'null' : Array.isArray(raw) ? 'array' : typeof raw;
+}
+
 function validateBranding(raw: unknown, warnings: string[]): void {
   if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
     warnings.push(
-      `course.config.js: "branding" must be an object, got ${raw === null ? 'null' : Array.isArray(raw) ? 'array' : typeof raw} — will be ignored`,
+      `course.config.js: "branding" must be an object, got ${describeType(raw)} — will be ignored`,
     );
     return;
   }
@@ -488,7 +500,7 @@ function validateBranding(raw: unknown, warnings: string[]): void {
 function validateA11yConfig(raw: unknown, errors: string[]): void {
   if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
     errors.push(
-      `course.config.js: "a11y" must be an object, got ${raw === null ? 'null' : Array.isArray(raw) ? 'array' : typeof raw}`,
+      `course.config.js: "a11y" must be an object, got ${describeType(raw)}`,
     );
     return;
   }
@@ -764,21 +776,14 @@ function validateSingleXAPIEntry(
   if (
     actor === undefined &&
     (standard === 'scorm12' || standard === 'scorm2004') &&
-    typeof activityId === 'string'
+    typeof activityId === 'string' &&
+    httpOrigin(activityId) === null &&
+    aahp === undefined
   ) {
-    let isHttp: boolean;
-    try {
-      const u = new URL(activityId);
-      isHttp = u.protocol === 'http:' || u.protocol === 'https:';
-    } catch {
-      isHttp = false;
-    }
-    if (!isHttp && aahp === undefined) {
-      errors.push(
-        `course.config.js: ${label}.activityId is not an http(s) URL, so its origin can't be used as the SCORM actor's account.homePage. ` +
-          `Provide ${label}.actorAccountHomePage explicitly.`,
-      );
-    }
+    errors.push(
+      `course.config.js: ${label}.activityId is not an http(s) URL, so its origin can't be used as the SCORM actor's account.homePage. ` +
+        `Provide ${label}.actorAccountHomePage explicitly.`,
+    );
   }
 
   // registration — optional UUID v4.
@@ -811,6 +816,7 @@ interface PagesValidationResult extends ValidationResult {
   totalPages: number;
   totalQuizzes: number;
   hasGradedQuiz: boolean;
+  hasParseErrors: boolean;
   pages: PageInfo[];
 }
 
@@ -828,10 +834,32 @@ function validatePageFile(
   warnings: string[],
   assetExistsCache: Map<string, boolean>,
   exportStandard?: string,
-): { page: PageInfo; isQuiz: boolean; isGradedQuiz: boolean } {
+): {
+  page: PageInfo;
+  isQuiz: boolean;
+  isGradedQuiz: boolean;
+  parseError: boolean;
+} {
   const fileRel = relative(projectRoot, filePath);
   const content = readSourceFileCached(filePath);
 
+  const parseError = getParseError(content);
+  if (parseError) {
+    errors.push(`${fileRel}: could not parse — ${parseError}`);
+    return {
+      page: {
+        fileRel,
+        navIndex,
+        hasGradedQuiz: false,
+        hasQuiz: false,
+        completesOnView: false,
+      },
+      isQuiz: false,
+      isGradedQuiz: false,
+      parseError: true,
+    };
+  }
+
   const pageConfig = validatePageConfig(content, fileRel, errors);
 
   const isQuiz = !!pageConfig?.quiz;
@@ -878,6 +906,7 @@ function validatePageFile(
     },
     isQuiz,
     isGradedQuiz,
+    parseError: false,
   };
 }
 
@@ -893,98 +922,69 @@ function validatePages(
   let totalPages = 0;
   let totalQuizzes = 0;
   let hasGradedQuiz = false;
+  let hasParseErrors = false;
   // One existsSync per unique asset for the whole pass.
   const assetExistsCache = new Map<string, boolean>();
 
-  if (!existsSync(pagesDir)) {
+  const noPages = (): PagesValidationResult => {
     errors.push(
       'No pages found. Create at least one section with a lesson and page in pages/',
     );
     return {
       errors,
       warnings,
-      totalPages: 0,
-      totalQuizzes: 0,
-      hasGradedQuiz: false,
+      totalPages,
+      totalQuizzes,
+      hasGradedQuiz,
+      hasParseErrors,
       pages,
     };
-  }
+  };
 
-  const topLevelEntries = readdirSync(pagesDir);
+  if (!existsSync(pagesDir)) return noPages();
 
-  // Check for stray .svelte files at pages/ root
-  for (const entry of topLevelEntries) {
+  // walkPages only descends into section dirs, so scan pages/ root separately.
+  for (const entry of readdirSync(pagesDir)) {
     const fullPath = resolve(pagesDir, entry);
     if (entry.endsWith('.svelte') && statSync(fullPath).isFile()) {
-      const relPath = relative(projectRoot, fullPath);
       warnings.push(
-        `${relPath}: this file is outside the section/lesson structure and will be ignored`,
+        `${relative(projectRoot, fullPath)}: this file is outside the section/lesson structure and will be ignored`,
       );
     }
   }
 
-  // Get section directories
-  const sectionDirs = topLevelEntries
-    .filter((name) => {
-      const full = resolve(pagesDir, name);
-      return statSync(full).isDirectory() && !name.startsWith('.');
-    })
-    .sort();
-
-  if (sectionDirs.length === 0) {
-    errors.push(
-      'No pages found. Create at least one section with a lesson and page in pages/',
-    );
-    return {
-      errors,
-      warnings,
-      totalPages: 0,
-      totalQuizzes: 0,
-      hasGradedQuiz: false,
-      pages,
-    };
-  }
-
-  for (const sectionName of sectionDirs) {
-    const sectionPath = resolve(pagesDir, sectionName);
-    const sectionRel = relative(projectRoot, sectionPath);
-    const pagesBeforeSection = totalPages;
-
-    // Validate section _meta.js
-    const sectionMeta = validateMetaFile(
-      resolve(sectionPath, '_meta.js'),
-      sectionRel,
-      errors,
-    );
+  const sections = walkPages(pagesDir);
+  if (sections.length === 0) return noPages();
 
-    // Flat mode: .svelte files directly at section level are pages of an
-    // implicit single lesson. Validate them just like lesson-level pages.
-    const sectionEntries = readdirSync(sectionPath);
-    const sectionSvelteFiles = sectionEntries
-      .filter((name) => {
-        const full = resolve(sectionPath, name);
-        return name.endsWith('.svelte') && statSync(full).isFile();
-      })
-      .sort();
-
-    if (sectionMeta?.pages) {
-      for (const pageName of sectionMeta.pages) {
+  // For a flat lesson `meta` is the section's _meta. Same ordering as generateManifest.
+  const validateLesson = (
+    lesson: WalkedLesson,
+    meta: { pages?: string[] } | null,
+  ): void => {
+    if (meta?.pages) {
+      for (const pageName of meta.pages) {
         const fileName = ensureSvelteSuffix(pageName);
-        if (!sectionSvelteFiles.includes(fileName)) {
-          const metaRel = relative(
-            projectRoot,
-            resolve(sectionPath, '_meta.js'),
-          );
+        if (!lesson.files.includes(fileName)) {
           errors.push(
-            `${metaRel}: pages array lists "${pageName}" but ${fileName} not found in this directory`,
+            `${relative(projectRoot, lesson.metaPath)}: pages array lists "${pageName}" but ${fileName} not found in this directory`,
+          );
+        }
+      }
+    }
+    if (meta?.pages && meta.pages.length > 0) {
+      const listedSet = new Set(meta.pages.map(ensureSvelteSuffix));
+      for (const file of lesson.files) {
+        if (!listedSet.has(file)) {
+          warnings.push(
+            `${relative(projectRoot, resolve(lesson.dir, file))}: not listed in _meta.js pages array — will be appended at end`,
           );
         }
       }
     }
 
-    for (const fileName of sectionSvelteFiles) {
+    for (const fileName of orderPageFiles(lesson.files, meta?.pages)) {
       const result = validatePageFile(
-        resolve(sectionPath, fileName),
+        resolve(lesson.dir, fileName),
         projectRoot,
         assetsDir,
         totalPages,
@@ -996,78 +996,28 @@ function validatePages(
       totalPages++;
       if (result.isQuiz) totalQuizzes++;
       if (result.isGradedQuiz) hasGradedQuiz = true;
+      if (result.parseError) hasParseErrors = true;
       pages.push(result.page);
     }
+  };
 
-    // Get lesson directories
-    const lessonDirs = sectionEntries
-      .filter((name) => {
-        const full = resolve(sectionPath, name);
-        return statSync(full).isDirectory() && !name.startsWith('.');
-      })
-      .sort();
-
-    for (const lessonName of lessonDirs) {
-      const lessonPath = resolve(sectionPath, lessonName);
-      const lessonRel = relative(projectRoot, lessonPath);
-
-      // Validate lesson _meta.js
-      const meta = validateMetaFile(
-        resolve(lessonPath, '_meta.js'),
-        lessonRel,
-        errors,
-      );
-
-      // Get .svelte files
-      const svelteFiles = readdirSync(lessonPath)
-        .filter((name) => name.endsWith('.svelte'))
-        .sort();
-
-      // Check pages array references
-      if (meta?.pages) {
-        for (const pageName of meta.pages) {
-          const fileName = ensureSvelteSuffix(pageName);
-          if (!svelteFiles.includes(fileName)) {
-            const metaRel = relative(
-              projectRoot,
-              resolve(lessonPath, '_meta.js'),
-            );
-            errors.push(
-              `${metaRel}: pages array lists "${pageName}" but ${fileName} not found in this directory`,
-            );
-          }
-        }
-      }
+  for (const section of sections) {
+    const sectionRel = relative(projectRoot, section.dir);
+    const pagesBeforeSection = totalPages;
 
-      // Check for unlisted .svelte files
-      if (meta?.pages && meta.pages.length > 0) {
-        const listedSet = new Set(meta.pages.map(ensureSvelteSuffix));
-        for (const file of svelteFiles) {
-          if (!listedSet.has(file)) {
-            const relPath = relative(projectRoot, resolve(lessonPath, file));
-            warnings.push(
-              `${relPath}: not listed in _meta.js pages array — will be appended at end`,
-            );
-          }
-        }
-      }
+    const sectionMeta = validateMetaFile(section.metaPath, sectionRel, errors);
 
-      // Validate each .svelte file
-      for (const fileName of svelteFiles) {
-        const result = validatePageFile(
-          resolve(lessonPath, fileName),
-          projectRoot,
-          assetsDir,
-          totalPages,
+    for (const lesson of section.lessons) {
+      if (lesson.name === null) {
+        // Flat lesson uses the section _meta, already validated above.
+        validateLesson(lesson, sectionMeta);
+      } else {
+        const meta = validateMetaFile(
+          lesson.metaPath,
+          relative(projectRoot, lesson.dir),
           errors,
-          warnings,
-          assetExistsCache,
-          exportStandard,
         );
-        totalPages++;
-        if (result.isQuiz) totalQuizzes++;
-        if (result.isGradedQuiz) hasGradedQuiz = true;
-        pages.push(result.page);
+        validateLesson(lesson, meta);
       }
     }
 
@@ -1079,13 +1029,17 @@ function validatePages(
     }
   }
 
-  if (totalPages === 0) {
-    errors.push(
-      'No pages found. Create at least one section with a lesson and page in pages/',
-    );
-  }
+  if (totalPages === 0) return noPages();
 
-  return { errors, warnings, totalPages, totalQuizzes, hasGradedQuiz, pages };
+  return {
+    errors,
+    warnings,
+    totalPages,
+    totalQuizzes,
+    hasGradedQuiz,
+    hasParseErrors,
+    pages,
+  };
 }
 
 // ---------- _meta.js Validation ----------
@@ -1098,11 +1052,15 @@ function validateMetaFile(
   if (!existsSync(metaPath)) return null;
 
   const metaRel = `${parentRel}/_meta.js`;
-  const objectStr = extractDefaultExportObjectLiteral(
+  const result = extractDefaultExportObjectLiteral(
     readSourceFileCached(metaPath),
   );
 
-  if (!objectStr) {
+  if (result.kind === 'parse-error') {
+    errors.push(`${metaRel}: could not parse — JavaScript syntax error`);
+    return null;
+  }
+  if (result.kind !== 'literal') {
     errors.push(
       `${metaRel}: syntax error — must export default { title: "..." }`,
     );
@@ -1111,7 +1069,7 @@ function validateMetaFile(
 
   let meta: { title?: string; pages?: string[] };
   try {
-    meta = JSON5.parse(objectStr);
+    meta = JSON5.parse(result.text);
   } catch {
     errors.push(
       `${metaRel}: syntax error — must export default { title: "..." }`,
@@ -1213,68 +1171,6 @@ const QUESTION_COMPONENT_REQUIRED: Record<string, string[]> = {
   Sorting: ['question', 'items', 'targets', 'correct'],
 };
 
-type PropValue =
-  | { kind: 'string'; value: string }
-  | { kind: 'expr'; raw: string }
-  | { kind: 'bool' };
-
-/**
- * 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,
-): { props: Map<string, PropValue>; hasSpread: boolean } | null {
-  const props = new Map<string, PropValue>();
-  let hasSpread = false;
-  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, hasSpread };
-    if (c === '/' && content[i + 1] === '>') return { props, hasSpread };
-    // Spread / shorthand expression — skip the whole {...} block, but record
-    // that unseen props may be supplied here so callers can suppress
-    // false-positive "missing required prop / alt / title" diagnostics.
-    if (c === '{') {
-      const block = extractObjectLiteral(content, i);
-      if (!block) return null;
-      hasSpread = true;
-      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 = extractObjectLiteral(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 {
@@ -1302,17 +1198,14 @@ function validateQuestionComponents(
   warnings: string[],
   exportStandard?: string,
 ): void {
-  const names = Object.keys(QUESTION_COMPONENT_REQUIRED).join('|');
-  const tagStartRe = new RegExp(`<(${names})(?=[\\s/>])`, 'g');
+  const components = findComponents(
+    content,
+    new Set(Object.keys(QUESTION_COMPONENT_REQUIRED)),
+  );
+  if (!components) return;
   const seenIds = new Set<string>();
   const seenSanitized = new Set<string>();
-  let m: RegExpExecArray | null;
-  while ((m = tagStartRe.exec(content)) !== null) {
-    const name = m[1];
-    const parsed = parseTagProps(content, m.index + m[0].length);
-    if (!parsed) continue;
-    const { props, hasSpread } = parsed;
-
+  for (const { name, props, hasSpread } of components) {
     for (const req of QUESTION_COMPONENT_REQUIRED[name]) {
       if (!hasSpread && !props.has(req)) {
         errors.push(`${fileRel}: <${name}> is missing required prop "${req}"`);
@@ -1458,6 +1351,21 @@ function validateQuestionComponents(
 /** Remove HTML/Svelte comments so commented-out markup isn't scanned as live. */
 const HTML_COMMENT_RE = /<!--[\s\S]*?-->/g;
 
+const SCRIPT_STYLE_RE = /<(script|style)\b[\s\S]*?<\/\1>/gi;
+
+// Loop until stable: one pass can leave a reconstructed tag behind (e.g. `<scr<script></script>ipt>`).
+function stripRepeated(input: string, patterns: RegExp[]): string {
+  let out = input;
+  for (const pattern of patterns) {
+    let prev: string;
+    do {
+      prev = out;
+      out = out.replace(pattern, '');
+    } while (out !== prev);
+  }
+  return out;
+}
+
 /**
  * Sibling to validateQuestionComponents kept out of QUESTION_COMPONENT_REQUIRED
  * so media isn't treated as gradable questions. Declares `warnings` directly.
@@ -1469,15 +1377,12 @@ function validateMediaComponents(
   errors: string[],
   warnings: string[],
 ): void {
-  const scan = content.replace(HTML_COMMENT_RE, '');
-  const tagStartRe = /<(Image|Video|Audio)(?=[\s/>])/g;
-  let m: RegExpExecArray | null;
-  while ((m = tagStartRe.exec(scan)) !== null) {
-    const name = m[1];
-    const parsed = parseTagProps(scan, m.index + m[0].length);
-    if (!parsed) continue;
-    const { props, hasSpread } = parsed;
-
+  const components = findComponents(
+    content,
+    new Set(['Image', 'Video', 'Audio']),
+  );
+  if (!components) return;
+  for (const { name, props, hasSpread } of components) {
     if (name === 'Image') {
       const alt = props.get('alt');
       const decorative = props.get('decorative');
@@ -1585,9 +1490,7 @@ function validateHeadingOrder(
   fileRel: string,
   warnings: string[],
 ): void {
-  const html = content
-    .replace(/<(script|style)\b[\s\S]*?<\/\1>/gi, '')
-    .replace(HTML_COMMENT_RE, '');
+  const html = stripRepeated(content, [SCRIPT_STYLE_RE, HTML_COMMENT_RE]);
   const levels = [...html.matchAll(/<h([1-6])\b/gi)].map((h) => Number(h[1]));
   let prevSeen: number | null = null;
   for (const level of levels) {
@@ -1687,7 +1590,11 @@ function crossValidate(
   warnings: string[],
 ): void {
   // completion.mode "quiz" but no graded quizzes
-  if (config.completion?.mode === 'quiz' && !pageResults.hasGradedQuiz) {
+  if (
+    config.completion?.mode === 'quiz' &&
+    !pageResults.hasGradedQuiz &&
+    !pageResults.hasParseErrors
+  ) {
     errors.push(
       'completion.mode is "quiz" but no pages have quiz config with graded: true',
     );
@@ -1710,7 +1617,8 @@ function crossValidate(
   if (
     isManual &&
     config.completion?.trigger === 'page' &&
-    completesOnPages.length === 0
+    completesOnPages.length === 0 &&
+    !pageResults.hasParseErrors
   ) {
     errors.push(
       'completion.mode is "manual" with trigger: "page", but no page declares pageConfig.completesOn: "view". ' +