tessera-learn 0.0.13 → 0.1.0

package/src/plugin/manifest.ts

@@ -1,6 +1,11 @@
 import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs';
 import { resolve, basename, extname } from 'node:path';
 import JSON5 from 'json5';
+import {
+  clearParseCache,
+  defaultExportObjectLiteral,
+  pageConfigLiteral,
+} from './ast.js';
 import type { CourseConfig, QuizConfig } from '../runtime/types.js';
 
 // ---------- Types ----------
@@ -85,29 +90,22 @@ export function deriveSlug(name: string, isFile = false): string {
   return stripPrefix(name);
 }
 
-/** Matches both Svelte 5 `<script module>` and legacy `<script context="module">`. */
-export const MODULE_SCRIPT_RE =
-  /<script\s+(?:context\s*=\s*["']module["']|module)[^>]*>([\s\S]*?)<\/script>/;
-
-/** Matches `export const pageConfig =` (RHS is read separately). */
-export const PAGE_CONFIG_EXPORT_RE = /export\s+const\s+pageConfig\s*=\s*/;
-
-/** Matches `export default ` (RHS is read separately). */
-const DEFAULT_EXPORT_RE = /export\s+default\s*/;
+export type DefaultExportLiteralResult =
+  | { kind: 'literal'; text: string }
+  | { kind: 'none' }
+  | { kind: 'invalid' }
+  | { kind: 'parse-error' };
 
 /**
- * Locate `export default { ... }` and return the object literal substring,
- * or null if no balanced object literal follows the `export default` keyword.
- * Used by both manifest extraction and project validation.
+ * Locate `export default { ... }` and return its object-literal text. Returns
+ * a discriminated result so callers can tell parse failure from a missing or
+ * non-literal default export. Used by both manifest extraction and project
+ * validation.
  */
 export function extractDefaultExportObjectLiteral(
   source: string,
-): string | null {
-  const match = source.match(DEFAULT_EXPORT_RE);
-  if (!match || match.index === undefined) return null;
-  const startIndex = source.indexOf('{', match.index);
-  if (startIndex < 0) return null;
-  return extractObjectLiteral(source, startIndex);
+): DefaultExportLiteralResult {
+  return defaultExportObjectLiteral(source);
 }
 
 export type CourseConfigRead =
@@ -128,12 +126,14 @@ export type CourseConfigRead =
 export function readCourseConfig(projectRoot: string): CourseConfigRead {
   const configPath = resolve(projectRoot, 'course.config.js');
   if (!existsSync(configPath)) return { ok: false, reason: 'missing' };
-  const objectStr = extractDefaultExportObjectLiteral(
+  const result = extractDefaultExportObjectLiteral(
     readSourceFileCached(configPath),
   );
-  if (!objectStr) return { ok: false, reason: 'no-export' };
+  if (result.kind === 'parse-error')
+    return { ok: false, reason: 'parse-error' };
+  if (result.kind !== 'literal') return { ok: false, reason: 'no-export' };
   try {
-    return { ok: true, config: JSON5.parse(objectStr) };
+    return { ok: true, config: JSON5.parse(result.text) };
   } catch (error) {
     return { ok: false, reason: 'parse-error', error };
   }
@@ -150,13 +150,13 @@ export function readMetaFile(metaPath: string): {
 } {
   if (!existsSync(metaPath)) return {};
 
-  const objectStr = extractDefaultExportObjectLiteral(
+  const result = extractDefaultExportObjectLiteral(
     readSourceFileCached(metaPath),
   );
-  if (!objectStr) return {};
+  if (result.kind !== 'literal') return {};
 
   try {
-    return JSON5.parse(objectStr);
+    return JSON5.parse(result.text);
   } catch {
     return {};
   }
@@ -178,30 +178,12 @@ export type PageConfigParseResult =
 export function parsePageConfigFromSource(
   content: string,
 ): PageConfigParseResult {
-  const moduleScriptMatch = content.match(MODULE_SCRIPT_RE);
-  if (!moduleScriptMatch) return { kind: 'none' };
-
-  const scriptContent = moduleScriptMatch[1];
-
-  const configMatch = scriptContent.match(PAGE_CONFIG_EXPORT_RE);
-  if (!configMatch || configMatch.index === undefined) return { kind: 'none' };
-
-  const afterExport = scriptContent
-    .slice(configMatch.index + configMatch[0].length)
-    .trimStart();
-  // pageConfig assigned to something other than an object literal — flag as invalid.
-  if (!afterExport.startsWith('{')) return { kind: 'invalid' };
-
-  const startIndex = scriptContent.indexOf(
-    '{',
-    configMatch.index + configMatch[0].length,
-  );
-  if (startIndex < 0) return { kind: 'invalid' };
-  const objectStr = extractObjectLiteral(scriptContent, startIndex);
-  if (!objectStr) return { kind: 'invalid' };
+  const literal = pageConfigLiteral(content);
+  if (literal.kind === 'none') return { kind: 'none' };
+  if (literal.kind === 'invalid') return { kind: 'invalid' };
 
   try {
-    return { kind: 'ok', value: JSON5.parse(objectStr) };
+    return { kind: 'ok', value: JSON5.parse(literal.text) };
   } catch {
     return { kind: 'invalid' };
   }
@@ -223,74 +205,6 @@ export function extractPageConfig(filePath: string): {
   return {};
 }
 
-/**
- * Extract a balanced `{...}` or `[...]` span starting at the opening bracket,
- * skipping strings and comments. Returns the substring (inclusive) or null if
- * the open char is wrong or no matching close is found. Shared by manifest
- * extraction, _meta/pageConfig parsing, and the validator's tag-prop parser.
- */
-export function extractObjectLiteral(
-  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;
-    }
-
-    // Skip single-line comments
-    if (char === '/' && i + 1 < source.length && source[i + 1] === '/') {
-      const newline = source.indexOf('\n', i);
-      i = newline === -1 ? source.length : newline;
-      continue;
-    }
-
-    // Skip multi-line comments
-    if (char === '/' && i + 1 < source.length && source[i + 1] === '*') {
-      const end = source.indexOf('*/', i + 2);
-      i = end === -1 ? source.length : end + 1;
-      continue;
-    }
-
-    if (char === '{' || char === '[') depth++;
-    if (char === '}' || char === ']') {
-      depth--;
-      if (depth === 0) {
-        return source.slice(startIndex, i + 1);
-      }
-    }
-  }
-
-  return null;
-}
-
 /**
  * Get sorted subdirectories of a given path.
  */
@@ -314,22 +228,73 @@ function getSvelteFiles(dirPath: string): string[] {
     .sort();
 }
 
+// ---------- Course structure walker ----------
+
+export interface WalkedLesson {
+  /** Lesson directory name, or null for a section's implicit flat lesson. */
+  name: string | null;
+  /** Directory holding the `.svelte` files (the section dir for a flat lesson). */
+  dir: string;
+  /** `_meta.js` path governing this lesson's title and page order. */
+  metaPath: string;
+  /** Sorted raw `.svelte` filenames in `dir` (pre-ordering). */
+  files: string[];
+}
+
+export interface WalkedSection {
+  name: string;
+  dir: string;
+  metaPath: string;
+  lessons: WalkedLesson[];
+}
+
+/**
+ * Enumerate the course's section → lesson → file structure. Section-level
+ * `.svelte` files become an implicit flat lesson (`name: null`) ordered before
+ * the section's explicit lesson directories. Shared by manifest generation and
+ * build-time validation so the two never disagree on which files are pages.
+ */
+export function walkPages(pagesDir: string): WalkedSection[] {
+  const sections: WalkedSection[] = [];
+  for (const sectionName of getSortedDirs(pagesDir)) {
+    const dir = resolve(pagesDir, sectionName);
+    const metaPath = resolve(dir, '_meta.js');
+    const lessons: WalkedLesson[] = [];
+
+    const flatFiles = getSvelteFiles(dir);
+    if (flatFiles.length > 0) {
+      lessons.push({ name: null, dir, metaPath, files: flatFiles });
+    }
+
+    for (const lessonName of getSortedDirs(dir)) {
+      const lessonDir = resolve(dir, lessonName);
+      lessons.push({
+        name: lessonName,
+        dir: lessonDir,
+        metaPath: resolve(lessonDir, '_meta.js'),
+        files: getSvelteFiles(lessonDir),
+      });
+    }
+
+    sections.push({ name: sectionName, dir, metaPath, lessons });
+  }
+  return sections;
+}
+
 // ---------- Main ----------
 
 /**
  * Generate a course manifest by scanning the pages/ directory.
  */
 export function generateManifest(pagesDir: string): Manifest {
+  clearParseCache();
   const sections: ManifestSection[] = [];
   const flatPages: ManifestPage[] = [];
   let pageIndex = 0;
 
-  const sectionDirs = getSortedDirs(pagesDir);
-
-  for (const sectionName of sectionDirs) {
-    const sectionPath = resolve(pagesDir, sectionName);
-    const sectionMeta = readMetaFile(resolve(sectionPath, '_meta.js'));
-    const sectionSlug = deriveSlug(sectionName);
+  for (const walkedSection of walkPages(pagesDir)) {
+    const sectionMeta = readMetaFile(walkedSection.metaPath);
+    const sectionSlug = deriveSlug(walkedSection.name);
 
     const section: ManifestSection = {
       title: sectionMeta.title || titleCase(sectionSlug),
@@ -337,25 +302,29 @@ export function generateManifest(pagesDir: string): Manifest {
       lessons: [],
     };
 
-    const lessonDirs = getSortedDirs(sectionPath);
-
-    for (const lessonName of lessonDirs) {
-      const lessonPath = resolve(sectionPath, lessonName);
-      const lessonMeta = readMetaFile(resolve(lessonPath, '_meta.js'));
-      const lessonSlug = deriveSlug(lessonName);
+    for (const walkedLesson of walkedSection.lessons) {
+      // The flat lesson uses the section _meta for ordering and has no title —
+      // the sidebar renders its pages without a lesson header.
+      const isFlat = walkedLesson.name === null;
+      const lessonMeta = isFlat
+        ? sectionMeta
+        : readMetaFile(walkedLesson.metaPath);
+      const lessonSlug = isFlat ? sectionSlug : deriveSlug(walkedLesson.name!);
+      const relDir = isFlat
+        ? `/pages/${walkedSection.name}`
+        : `/pages/${walkedSection.name}/${walkedLesson.name}`;
 
       const lesson: ManifestLesson = {
-        title: lessonMeta.title || titleCase(lessonSlug),
+        title: isFlat ? '' : lessonMeta.title || titleCase(lessonSlug),
         slug: lessonSlug,
         pages: [],
       };
 
-      // Determine page order
-      const allSvelteFiles = getSvelteFiles(lessonPath);
-      const orderedFiles = orderPageFiles(allSvelteFiles, lessonMeta.pages);
-
-      for (const fileName of orderedFiles) {
-        const filePath = resolve(lessonPath, fileName);
+      for (const fileName of orderPageFiles(
+        walkedLesson.files,
+        lessonMeta.pages,
+      )) {
+        const filePath = resolve(walkedLesson.dir, fileName);
         const pageSlug = deriveSlug(fileName, true);
 
         let pageConfig: {
@@ -371,13 +340,11 @@ export function generateManifest(pagesDir: string): Manifest {
           console.warn(`[tessera warning] ${(e as Error).message}`);
         }
 
-        const relativePath = `/pages/${sectionName}/${lessonName}/${fileName}`;
-
         const page: ManifestPage = {
           index: pageIndex,
           title: pageConfig.title || titleCase(pageSlug),
           slug: pageSlug,
-          importPath: relativePath,
+          importPath: `${relDir}/${fileName}`,
           quiz: pageConfig.quiz || null,
           ...(pageConfig.completesOn === 'view'
             ? { completesOn: 'view' as const }

package/src/plugin/package-root.ts

@@ -0,0 +1,24 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+// Walk up from this module to the tessera-learn package root (the dir holding
+// its package.json). Resolving by directory depth — resolve(dirname, '..', '..')
+// — is brittle: tsdown may emit plugin code at dist/plugin/ or hoist it into a
+// shared chunk at dist/, and those differ by one level. The package ships src/
+// and styles/, so its package.json is the stable anchor for both.
+export function resolvePackageRoot(): string {
+  const dir = import.meta.dirname;
+  for (let up = dir; up !== dirname(up); up = dirname(up)) {
+    const pkgPath = resolve(up, 'package.json');
+    if (existsSync(pkgPath)) {
+      try {
+        const { name } = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        if (name === 'tessera-learn') return up;
+      } catch {
+        // unreadable / non-JSON package.json — keep walking up
+      }
+    }
+  }
+  // Fallback to the historical depth assumption (dist/plugin → package root).
+  return resolve(dir, '..', '..');
+}

package/src/plugin/quiz.ts

@@ -1,16 +1,15 @@
 import type { Plugin } from 'vite';
-import { resolve, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
 import { createOverridePlugin } from './override-plugin.js';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
+import { resolvePackageRoot } from './package-root.js';
 
 export function tesseraQuizPlugin(): Plugin {
-  // The plugin lives in `dist/plugin/quiz.js` after build and `src/plugin/quiz.ts`
-  // in source — both put `Quiz.svelte` two levels up under `src/components/`.
-  const packageRoot = resolve(__dirname, '..', '..');
-  const builtinQuiz = resolve(packageRoot, 'src', 'components', 'Quiz.svelte');
+  const builtinQuiz = resolve(
+    resolvePackageRoot(),
+    'src',
+    'components',
+    'Quiz.svelte',
+  );
   return createOverridePlugin({
     name: 'tessera:quiz',
     virtualId: 'virtual:tessera-quiz',

package/src/plugin/validate-cli.ts

@@ -0,0 +1,30 @@
+import { validateProject, reportValidationIssues } from './validation.js';
+
+export function runValidate(projectRoot: string): number {
+  const { errors, warnings } = validateProject(projectRoot);
+
+  reportValidationIssues({ errors, warnings });
+
+  if (errors.length > 0) {
+    const summary =
+      `Validation failed with ${errors.length} error(s)` +
+      (warnings.length > 0 ? ` and ${warnings.length} warning(s)` : '') +
+      '.';
+    console.error(`\n\x1b[31m${summary}\x1b[0m`);
+    return 1;
+  }
+
+  if (warnings.length > 0) {
+    console.log(
+      `\n\x1b[33mValidation passed with ${warnings.length} warning(s).\x1b[0m`,
+    );
+  } else {
+    console.log(
+      '\x1b[32m[tessera]\x1b[0m Validation passed — no issues found.',
+    );
+  }
+  console.log(
+    '\x1b[2m[tessera] Static checks only. For a full runtime accessibility audit, run: tessera a11y\x1b[0m',
+  );
+  return 0;
+}