tessera-learn 0.0.10 → 0.0.13

package/src/plugin/manifest.ts

@@ -1,7 +1,7 @@
 import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs';
 import { resolve, basename, extname } from 'node:path';
 import JSON5 from 'json5';
-import type { QuizConfig } from '../runtime/types.js';
+import type { CourseConfig, QuizConfig } from '../runtime/types.js';
 
 // ---------- Types ----------
 
@@ -48,7 +48,10 @@ export function ensureSvelteSuffix(name: string): string {
  * sharing the read avoids the second disk hit (and matters most on cold-cache
  * CI runs and large courses).
  */
-const fileContentCache = new Map<string, { mtimeMs: number; content: string }>();
+const fileContentCache = new Map<
+  string,
+  { mtimeMs: number; content: string }
+>();
 
 export function readSourceFileCached(filePath: string): string {
   const stat = statSync(filePath);
@@ -70,7 +73,7 @@ export function stripPrefix(name: string): string {
 export function titleCase(slug: string): string {
   return slug
     .split('-')
-    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
     .join(' ');
 }
 
@@ -97,7 +100,9 @@ const DEFAULT_EXPORT_RE = /export\s+default\s*/;
  * or null if no balanced object literal follows the `export default` keyword.
  * Used by both manifest extraction and project validation.
  */
-export function extractDefaultExportObjectLiteral(source: string): string | null {
+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);
@@ -105,15 +110,49 @@ export function extractDefaultExportObjectLiteral(source: string): string | null
   return extractObjectLiteral(source, startIndex);
 }
 
+export type CourseConfigRead =
+  | { ok: true; config: Partial<CourseConfig> }
+  | {
+      ok: false;
+      reason: 'missing' | 'no-export' | 'parse-error';
+      error?: unknown;
+    };
+
+/**
+ * Read and JSON5-parse the `export default { ... }` literal from a project's
+ * course.config.js. Shared by the build plugin and the validator so the read,
+ * cache, and parse rules live in one place. The discriminated `reason` lets
+ * callers that care (export, validation) emit precise errors while callers
+ * that just need a value can fall back on `!ok`.
+ */
+export function readCourseConfig(projectRoot: string): CourseConfigRead {
+  const configPath = resolve(projectRoot, 'course.config.js');
+  if (!existsSync(configPath)) return { ok: false, reason: 'missing' };
+  const objectStr = extractDefaultExportObjectLiteral(
+    readSourceFileCached(configPath),
+  );
+  if (!objectStr) return { ok: false, reason: 'no-export' };
+  try {
+    return { ok: true, config: JSON5.parse(objectStr) };
+  } catch (error) {
+    return { ok: false, reason: 'parse-error', error };
+  }
+}
+
 /**
  * Read a _meta.js file and extract its default export object.
  * Uses the same JSON5 approach as pageConfig extraction — find the object literal
  * after `export default` and parse it.
  */
-export function readMetaFile(metaPath: string): { title?: string; pages?: string[] } {
+export function readMetaFile(metaPath: string): {
+  title?: string;
+  pages?: string[];
+} {
   if (!existsSync(metaPath)) return {};
 
-  const objectStr = extractDefaultExportObjectLiteral(readSourceFileCached(metaPath));
+  const objectStr = extractDefaultExportObjectLiteral(
+    readSourceFileCached(metaPath),
+  );
   if (!objectStr) return {};
 
   try {
@@ -128,12 +167,17 @@ export type PageConfigParseResult =
   /** No module script, or no `pageConfig =` export. Treat as "no config". */
   | { kind: 'none' }
   /** Found and successfully parsed. */
-  | { kind: 'ok'; value: { title?: string; quiz?: QuizConfig; completesOn?: 'view' } }
+  | {
+      kind: 'ok';
+      value: { title?: string; quiz?: QuizConfig; completesOn?: 'view' };
+    }
   /** Found but couldn't parse as a static object literal — non-literal RHS or JSON5 failure. */
   | { kind: 'invalid' };
 
 /** Source-level pageConfig extraction shared by manifest generation and build-time validation. */
-export function parsePageConfigFromSource(content: string): PageConfigParseResult {
+export function parsePageConfigFromSource(
+  content: string,
+): PageConfigParseResult {
   const moduleScriptMatch = content.match(MODULE_SCRIPT_RE);
   if (!moduleScriptMatch) return { kind: 'none' };
 
@@ -148,7 +192,10 @@ export function parsePageConfigFromSource(content: string): PageConfigParseResul
   // 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);
+  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' };
@@ -161,23 +208,33 @@ export function parsePageConfigFromSource(content: string): PageConfigParseResul
 }
 
 /** Extract pageConfig from a .svelte file. Throws on parse failure. */
-export function extractPageConfig(filePath: string): { title?: string; quiz?: QuizConfig; completesOn?: 'view' } {
+export function extractPageConfig(filePath: string): {
+  title?: string;
+  quiz?: QuizConfig;
+  completesOn?: 'view';
+} {
   const result = parsePageConfigFromSource(readSourceFileCached(filePath));
   if (result.kind === 'ok') return result.value;
   if (result.kind === 'invalid') {
     throw new Error(
-      `${filePath}: pageConfig must be a static object literal (no variables, function calls, or computed values)`
+      `${filePath}: pageConfig must be a static object literal (no variables, function calls, or computed values)`,
     );
   }
   return {};
 }
 
 /**
- * Extract an object literal from source starting at the opening brace.
- * Tracks brace depth to find the matching closing brace.
+ * 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 {
-  if (source[startIndex] !== '{') return null;
+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;
@@ -222,8 +279,8 @@ export function extractObjectLiteral(source: string, startIndex: number): string
       continue;
     }
 
-    if (char === '{') depth++;
-    if (char === '}') {
+    if (char === '{' || char === '[') depth++;
+    if (char === '}' || char === ']') {
       depth--;
       if (depth === 0) {
         return source.slice(startIndex, i + 1);
@@ -240,7 +297,7 @@ export function extractObjectLiteral(source: string, startIndex: number): string
 function getSortedDirs(dirPath: string): string[] {
   if (!existsSync(dirPath)) return [];
   return readdirSync(dirPath)
-    .filter(name => {
+    .filter((name) => {
       const full = resolve(dirPath, name);
       return statSync(full).isDirectory() && !name.startsWith('.');
     })
@@ -253,7 +310,7 @@ function getSortedDirs(dirPath: string): string[] {
 function getSvelteFiles(dirPath: string): string[] {
   if (!existsSync(dirPath)) return [];
   return readdirSync(dirPath)
-    .filter(name => name.endsWith('.svelte'))
+    .filter((name) => name.endsWith('.svelte'))
     .sort();
 }
 
@@ -301,7 +358,11 @@ export function generateManifest(pagesDir: string): Manifest {
         const filePath = resolve(lessonPath, fileName);
         const pageSlug = deriveSlug(fileName, true);
 
-        let pageConfig: { title?: string; quiz?: QuizConfig; completesOn?: 'view' } = {};
+        let pageConfig: {
+          title?: string;
+          quiz?: QuizConfig;
+          completesOn?: 'view';
+        } = {};
         try {
           pageConfig = extractPageConfig(filePath);
         } catch (e) {
@@ -318,7 +379,9 @@ export function generateManifest(pagesDir: string): Manifest {
           slug: pageSlug,
           importPath: relativePath,
           quiz: pageConfig.quiz || null,
-          ...(pageConfig.completesOn === 'view' ? { completesOn: 'view' as const } : {}),
+          ...(pageConfig.completesOn === 'view'
+            ? { completesOn: 'view' as const }
+            : {}),
         };
 
         lesson.pages.push(page);
@@ -342,17 +405,20 @@ export function generateManifest(pagesDir: string): Manifest {
 /**
  * Order .svelte files: listed in `pages` array first (in order), then unlisted appended alphabetically.
  */
-export function orderPageFiles(allFiles: string[], pagesArray?: string[]): string[] {
+export function orderPageFiles(
+  allFiles: string[],
+  pagesArray?: string[],
+): string[] {
   if (!pagesArray || pagesArray.length === 0) {
     return allFiles;
   }
 
   const listed = pagesArray.map(ensureSvelteSuffix);
   const listedSet = new Set(listed);
-  const unlisted = allFiles.filter(f => !listedSet.has(f)).sort();
+  const unlisted = allFiles.filter((f) => !listedSet.has(f)).sort();
 
   // Only include listed files that actually exist
-  const validListed = listed.filter(f => allFiles.includes(f));
+  const validListed = listed.filter((f) => allFiles.includes(f));
 
   return [...validListed, ...unlisted];
 }

package/src/plugin/override-plugin.ts

@@ -0,0 +1,68 @@
+import type { Plugin, ResolvedConfig, ViteDevServer } from 'vite';
+import { normalizePath } from 'vite';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+export interface OverridePluginOptions {
+  name: string;
+  virtualId: string;
+  projectFile: string;
+  /** Built-in re-exported when the project file is absent; null export otherwise. */
+  builtinFile?: string;
+}
+
+/**
+ * A virtual module that resolves to a project-root override file when present,
+ * and to the built-in (or a null export) otherwise. Shared by the layout and
+ * quiz plugins — they differ only in the virtual id, file name, and built-in.
+ */
+export function createOverridePlugin({
+  name,
+  virtualId,
+  projectFile,
+  builtinFile,
+}: OverridePluginOptions): Plugin {
+  const resolvedId = '\0' + virtualId;
+  const fallback = builtinFile
+    ? `export { default } from '${normalizePath(builtinFile)}';`
+    : 'export default null;';
+  let filePath: string;
+
+  return {
+    name,
+    enforce: 'pre',
+
+    configResolved(config: ResolvedConfig) {
+      filePath = resolve(config.root, projectFile);
+    },
+
+    resolveId(id) {
+      if (id === virtualId) return resolvedId;
+      return null;
+    },
+
+    load(id) {
+      if (id !== resolvedId) return null;
+      if (existsSync(filePath)) {
+        // Only watch when it exists — addWatchFile on a missing path makes
+        // Vite's importAnalysis try to resolve it as a real import.
+        this.addWatchFile(filePath);
+        return `export { default } from '${normalizePath(filePath)}';`;
+      }
+      return fallback;
+    },
+
+    configureServer(server: ViteDevServer) {
+      // Only add/unlink flips load()'s output between the override and the
+      // fallback; a `change` leaves it identical and Svelte's own HMR handles
+      // the underlying file.
+      server.watcher.on('all', (event, changed) => {
+        if (changed !== filePath) return;
+        if (event !== 'add' && event !== 'unlink') return;
+        const mod = server.moduleGraph.getModuleById(resolvedId);
+        if (mod) server.moduleGraph.invalidateModule(mod);
+        server.ws.send({ type: 'full-reload' });
+      });
+    },
+  };
+}

package/src/plugin/quiz.ts

@@ -1,65 +1,20 @@
-import type { Plugin, ResolvedConfig, ViteDevServer } from 'vite';
-import { existsSync } from 'node:fs';
+import type { Plugin } from 'vite';
 import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-
-const VIRTUAL_QUIZ_ID = 'virtual:tessera-quiz';
-const RESOLVED_QUIZ_ID = '\0' + VIRTUAL_QUIZ_ID;
+import { createOverridePlugin } from './override-plugin.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-/**
- * Resolve the project's quiz shell.
- * `projectRoot/quiz.svelte` overrides the built-in `<Quiz>` if it exists,
- * otherwise the built-in is used. Mirrors `tesseraLayoutPlugin` (Phase 3A).
- */
 export function tesseraQuizPlugin(): Plugin {
-  let projectRoot: string;
-  // Resolve the built-in Quiz.svelte once. The plugin lives in
-  // `dist/plugin/quiz.js` after build and `src/plugin/quiz.ts` in source —
-  // both layouts put `Quiz.svelte` two levels up under `src/components/`.
+  // 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');
-
-  return {
+  return createOverridePlugin({
     name: 'tessera:quiz',
-    enforce: 'pre',
-
-    configResolved(config: ResolvedConfig) {
-      projectRoot = config.root;
-    },
-
-    resolveId(id) {
-      if (id === VIRTUAL_QUIZ_ID) return RESOLVED_QUIZ_ID;
-      return null;
-    },
-
-    load(id) {
-      if (id !== RESOLVED_QUIZ_ID) return null;
-      const userQuizPath = resolve(projectRoot, 'quiz.svelte');
-      if (existsSync(userQuizPath)) {
-        // Watch the user file so add/remove flips through HMR (see below).
-        this.addWatchFile(userQuizPath);
-        const normalized = userQuizPath.replace(/\\/g, '/');
-        return `export { default } from '${normalized}';`;
-      }
-      const normalized = builtinQuiz.replace(/\\/g, '/');
-      return `export { default } from '${normalized}';`;
-    },
-
-    configureServer(server: ViteDevServer) {
-      const userQuizPath = resolve(projectRoot, 'quiz.svelte');
-      // Only react to add/unlink — those flip the load() output between the
-      // user quiz and the built-in. A `change` event leaves the resolved
-      // module identical and is handled by Svelte's own HMR.
-      server.watcher.on('all', (event, filePath) => {
-        if (filePath !== userQuizPath) return;
-        if (event !== 'add' && event !== 'unlink') return;
-        const mod = server.moduleGraph.getModuleById(RESOLVED_QUIZ_ID);
-        if (mod) server.moduleGraph.invalidateModule(mod);
-        server.ws.send({ type: 'full-reload' });
-      });
-    },
-  };
+    virtualId: 'virtual:tessera-quiz',
+    projectFile: 'quiz.svelte',
+    builtinFile: builtinQuiz,
+  });
 }