tessera-learn 0.0.13 → 0.2.0

package/src/plugin/a11y-cli.ts

@@ -1,5 +1,4 @@
-#!/usr/bin/env node
-import { runAudit, type ImpactLevel } from './a11y/audit.js';
+import { runAudit, type AuditOptions, type ImpactLevel } from './a11y/audit.js';
 
 const VALID_THRESHOLDS: ImpactLevel[] = [
   'minor',
@@ -8,28 +7,46 @@ const VALID_THRESHOLDS: ImpactLevel[] = [
   'critical',
 ];
 
-const args = process.argv.slice(2);
-let threshold: ImpactLevel | undefined;
-let rebuild = false;
+export type ParsedA11yArgs =
+  | { ok: true; args: AuditOptions }
+  | { ok: false; error: string };
 
-for (let i = 0; i < args.length; i++) {
-  const arg = args[i];
-  if (arg === '--threshold') {
-    const value = args[++i] as ImpactLevel;
-    if (!VALID_THRESHOLDS.includes(value)) {
-      console.error(
-        `[tessera a11y] --threshold must be one of: ${VALID_THRESHOLDS.join(', ')}`,
-      );
-      process.exit(1);
+export function parseA11yArgs(argv: string[]): ParsedA11yArgs {
+  let threshold: ImpactLevel | undefined;
+  let rebuild = false;
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--threshold') {
+      const value = argv[++i] as ImpactLevel;
+      if (!VALID_THRESHOLDS.includes(value)) {
+        return {
+          ok: false,
+          error: `--threshold must be one of: ${VALID_THRESHOLDS.join(', ')}`,
+        };
+      }
+      threshold = value;
+    } else if (arg === '--build') {
+      rebuild = true;
+    } else {
+      return { ok: false, error: `Unknown argument: ${arg}` };
     }
-    threshold = value;
-  } else if (arg === '--build') {
-    rebuild = true;
-  } else {
-    console.error(`[tessera a11y] Unknown argument: ${arg}`);
-    process.exit(1);
   }
+
+  const args: AuditOptions = { rebuild };
+  if (threshold !== undefined) args.threshold = threshold;
+  return { ok: true, args };
 }
 
-const code = await runAudit(process.cwd(), { threshold, rebuild });
-process.exit(code);
+export async function runA11y(
+  projectRoot: string,
+  workspaceRoot: string,
+  argv: string[],
+): Promise<number> {
+  const parsed = parseA11yArgs(argv);
+  if (!parsed.ok) {
+    console.error(`[tessera a11y] ${parsed.error}`);
+    return 1;
+  }
+  return runAudit(projectRoot, workspaceRoot, parsed.args);
+}

package/src/plugin/ast.ts

@@ -0,0 +1,276 @@
+import { Parser } from 'acorn';
+import { tsPlugin } from '@sveltejs/acorn-typescript';
+import { parse } from 'svelte/compiler';
+
+/**
+ * Shared parsing layer for the build-time validator and manifest generator.
+ *
+ * `.svelte` files go through `svelte/compiler`'s `parse`; plain JS files
+ * (`course.config.js`, `_meta.js`) and the module-script fallback go through
+ * acorn (with `acorn-typescript` for `as const` / `satisfies T`). Static
+ * *values* are still recovered with JSON5 by the callers — only structure
+ * parsing lives here.
+ */
+
+export type PropValue =
+  | { kind: 'string'; value: string }
+  | { kind: 'expr'; raw: string }
+  | { kind: 'bool' };
+
+export interface ComponentMatch {
+  name: string;
+  props: Map<string, PropValue>;
+  hasSpread: boolean;
+}
+
+export type NamedObjectLiteral =
+  | { kind: 'none' }
+  | { kind: 'invalid' }
+  | { kind: 'literal'; text: string };
+
+interface Node {
+  type: string;
+  start: number;
+  end: number;
+  [key: string]: unknown;
+}
+
+interface CacheEntry {
+  root: Node | null;
+  error: string | null;
+}
+
+const rootCache = new Map<string, CacheEntry>();
+
+/** Drop every cached root. Call at the start of a run to scope the cache. */
+export function clearParseCache(): void {
+  rootCache.clear();
+}
+
+function parseRoot(source: string): CacheEntry {
+  const cached = rootCache.get(source);
+  if (cached !== undefined) return cached;
+  let entry: CacheEntry;
+  try {
+    entry = {
+      root: parse(source, { modern: true }) as unknown as Node,
+      error: null,
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const firstLine = message.split('\n')[0].trim();
+    entry = { root: null, error: firstLine || 'parse error' };
+  }
+  rootCache.set(source, entry);
+  return entry;
+}
+
+function collectComponents(root: Node, names: ReadonlySet<string>): Node[] {
+  const found: Node[] = [];
+  const seen = new Set<object>();
+  const walk = (value: unknown): void => {
+    if (!value || typeof value !== 'object') return;
+    if (seen.has(value)) return;
+    seen.add(value);
+    if (Array.isArray(value)) {
+      for (const item of value) walk(item);
+      return;
+    }
+    const node = value as Node;
+    if (node.type === 'Component' && names.has(node.name as string)) {
+      found.push(node);
+    }
+    for (const key of Object.keys(node)) {
+      if (key === 'type') continue;
+      walk(node[key]);
+    }
+  };
+  walk(root);
+  return found.sort((a, b) => a.start - b.start);
+}
+
+function readProps(source: string, node: Node): ComponentMatch {
+  const props = new Map<string, PropValue>();
+  let hasSpread = false;
+  const attributes = (node.attributes as Node[]) ?? [];
+  for (const attr of attributes) {
+    if (attr.type === 'SpreadAttribute') {
+      hasSpread = true;
+      continue;
+    }
+    if (attr.type === 'BindDirective') {
+      const expr = (attr as { expression?: Node }).expression;
+      if (expr) {
+        props.set(attr.name as string, {
+          kind: 'expr',
+          raw: source.slice(expr.start, expr.end).trim(),
+        });
+      }
+      continue;
+    }
+    if (attr.type !== 'Attribute') continue;
+    const name = attr.name as string;
+    const value = attr.value;
+    if (value === true) {
+      props.set(name, { kind: 'bool' });
+    } else if (Array.isArray(value)) {
+      if (value.length === 0) {
+        props.set(name, { kind: 'string', value: '' });
+      } else {
+        const first = value[0] as Node;
+        const last = value[value.length - 1] as Node;
+        props.set(name, {
+          kind: 'string',
+          value: source.slice(first.start, last.end),
+        });
+      }
+    } else if (
+      value &&
+      typeof value === 'object' &&
+      (value as Node).type === 'ExpressionTag'
+    ) {
+      const expr = (value as { expression: Node }).expression;
+      props.set(name, {
+        kind: 'expr',
+        raw: source.slice(expr.start, expr.end).trim(),
+      });
+      if (source[attr.start] === '{') hasSpread = true;
+    }
+  }
+  return { name: node.name as string, props, hasSpread };
+}
+
+/**
+ * Return a one-line message if `source` is not valid Svelte, else null. Lets
+ * the validator surface a real syntax error itself rather than only failing
+ * later in the compiler (and the compile-less CLI would otherwise miss it).
+ */
+export function getParseError(source: string): string | null {
+  return parseRoot(source).error;
+}
+
+/**
+ * Find every question/media component in a `.svelte` source, anywhere in the
+ * markup, with its props. Returns null if the source can't be parsed — callers
+ * then skip component validation, matching the old "skip when unsure" stance.
+ */
+export function findComponents(
+  source: string,
+  names: ReadonlySet<string>,
+): ComponentMatch[] | null {
+  const { root } = parseRoot(source);
+  if (!root) return null;
+  return collectComponents(root, names).map((node) => readProps(source, node));
+}
+
+const TsParser = Parser.extend(
+  tsPlugin() as unknown as Parameters<typeof Parser.extend>[0],
+);
+
+function parseJsModule(source: string): Node | null {
+  try {
+    return TsParser.parse(source, {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+    }) as unknown as Node;
+  } catch {
+    return null;
+  }
+}
+
+function unwrapTsCast(node: Node | null): Node | null {
+  let current = node;
+  while (
+    current &&
+    (current.type === 'TSAsExpression' ||
+      current.type === 'TSSatisfiesExpression' ||
+      current.type === 'TSTypeAssertion' ||
+      current.type === 'TSNonNullExpression')
+  ) {
+    current = (current as { expression?: Node }).expression ?? null;
+  }
+  return current;
+}
+
+function findPageConfigInProgram(
+  program: Node,
+  source: string,
+): NamedObjectLiteral {
+  const body = (program.body as Node[]) ?? [];
+  for (const node of body) {
+    if (node.type !== 'ExportNamedDeclaration') continue;
+    const declaration = node.declaration as Node | null;
+    if (!declaration || declaration.type !== 'VariableDeclaration') continue;
+    for (const decl of declaration.declarations as Node[]) {
+      const id = decl.id as Node;
+      if (id.type !== 'Identifier' || id.name !== 'pageConfig') continue;
+      const init = unwrapTsCast(decl.init as Node | null);
+      if (init && init.type === 'ObjectExpression') {
+        return { kind: 'literal', text: source.slice(init.start, init.end) };
+      }
+      return { kind: 'invalid' };
+    }
+  }
+  return { kind: 'none' };
+}
+
+/**
+ * Locate the `export default { ... }` object literal in a plain JS source.
+ * Returns a discriminated result so callers can tell parse failure from a
+ * missing or non-literal default export.
+ */
+export function defaultExportObjectLiteral(
+  jsSource: string,
+): NamedObjectLiteral | { kind: 'parse-error' } {
+  const program = parseJsModule(jsSource);
+  if (!program) return { kind: 'parse-error' };
+  for (const node of (program.body as Node[]) ?? []) {
+    if (node.type !== 'ExportDefaultDeclaration') continue;
+    const decl = unwrapTsCast(
+      (node as { declaration?: Node }).declaration ?? null,
+    );
+    if (decl && decl.type === 'ObjectExpression') {
+      return { kind: 'literal', text: jsSource.slice(decl.start, decl.end) };
+    }
+    return { kind: 'invalid' };
+  }
+  return { kind: 'none' };
+}
+
+const MODULE_SCRIPT_OPEN_RE =
+  /<script\s+(?:context\s*=\s*["']module["']|module)[^>]*>/;
+const SCRIPT_CLOSE = '</script>';
+
+function pageConfigFromModuleScriptFallback(
+  svelteSource: string,
+): NamedObjectLiteral {
+  const open = svelteSource.match(MODULE_SCRIPT_OPEN_RE);
+  if (!open || open.index === undefined) return { kind: 'none' };
+  const bodyStart = open.index + open[0].length;
+  // Try every `</script>` candidate from earliest; the first one whose body
+  // parses as JS is the real close (an earlier hit is inside a string literal).
+  let from = bodyStart;
+  while (true) {
+    const closeIdx = svelteSource.indexOf(SCRIPT_CLOSE, from);
+    if (closeIdx < 0) return { kind: 'none' };
+    const body = svelteSource.slice(bodyStart, closeIdx);
+    const program = parseJsModule(body);
+    if (program) return findPageConfigInProgram(program, body);
+    from = closeIdx + SCRIPT_CLOSE.length;
+  }
+}
+
+/**
+ * Locate `export const pageConfig = { ... }` in a Svelte page's module script
+ * and return the object-literal text. Walks the page-level AST so TypeScript
+ * (`lang="ts"`) module scripts are handled by Svelte's own parser.
+ */
+export function pageConfigLiteral(svelteSource: string): NamedObjectLiteral {
+  const { root } = parseRoot(svelteSource);
+  if (root) {
+    const program = (root.module as { content?: Node } | null)?.content;
+    if (!program) return { kind: 'none' };
+    return findPageConfigInProgram(program, svelteSource);
+  }
+  return pageConfigFromModuleScriptFallback(svelteSource);
+}

package/src/plugin/build-commands.ts

@@ -0,0 +1,31 @@
+import { resolveTesseraConfig } from './inline-config.js';
+
+export async function runDev(
+  projectRoot: string,
+  workspaceRoot: string,
+): Promise<number> {
+  const vite = await import('vite');
+  const config = await resolveTesseraConfig(projectRoot, workspaceRoot, {
+    command: 'serve',
+    mode: 'development',
+  });
+  const server = await vite.createServer(config);
+  await server.listen();
+  server.printUrls();
+  server.bindCLIShortcuts({ print: true });
+  // Never resolve: the CLI wrapper would process.exit and kill the server.
+  return new Promise<number>(() => {});
+}
+
+export async function runBuild(
+  projectRoot: string,
+  workspaceRoot: string,
+): Promise<number> {
+  const vite = await import('vite');
+  const config = await resolveTesseraConfig(projectRoot, workspaceRoot, {
+    command: 'build',
+    mode: 'production',
+  });
+  await vite.build(config);
+  return 0;
+}

package/src/plugin/cli.ts

@@ -1,28 +1,103 @@
 #!/usr/bin/env node
-import { validateProject, reportValidationIssues } from './validation.js';
+import { runValidate } from './validate-cli.js';
+import { runA11y } from './a11y-cli.js';
+import { runNew } from './new-cli.js';
+import { runDuplicate } from './duplicate-cli.js';
+import { resolveCourse } from './course-root.js';
 
-const projectRoot = process.cwd();
-const { errors, warnings } = validateProject(projectRoot);
+const USAGE = `Usage: tessera <command> [course] [options]
 
-reportValidationIssues({ errors, warnings });
+Commands:
+  new <name>                  Scaffold a new course into courses/<name>
+  duplicate <source> <new>    Copy courses/<source> to courses/<new>
+  dev       [course]          Start the Vite dev server
+  export    [course]          Build and package the course for its LMS standard
+  validate  [course]          Fast static structure checks
+  a11y      [course]          Runtime accessibility audit (builds + drives Playwright)
+  check     [course]          Run validate, then a11y
 
-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`);
-  process.exit(1);
+Run a command from inside a course folder, or name the course explicitly.
+
+a11y/check options:
+  --threshold <minor|moderate|serious|critical>   Failing impact (default: serious)
+  --build                                          Force a fresh build first`;
+
+// The course is a leading positional: `tessera <cmd> [course] [flags]`. Only the
+// first token can be the course, and only when it isn't a flag — otherwise a flag
+// value (e.g. the `serious` in `--threshold serious`) would be misread as a name.
+export function splitCourseArg(rest: string[]): {
+  course?: string;
+  flags: string[];
+} {
+  if (rest.length > 0 && !rest[0].startsWith('-')) {
+    return { course: rest[0], flags: rest.slice(1) };
+  }
+  return { course: undefined, flags: rest };
+}
+
+export async function main(
+  argv: string[],
+  cwd: string = process.cwd(),
+): Promise<number> {
+  const [sub, ...rest] = argv;
+
+  if (sub === 'new') return runNew(rest[0], cwd);
+  if (sub === 'duplicate') return runDuplicate(rest[0], rest[1], cwd);
+
+  switch (sub) {
+    case 'dev':
+    case 'export':
+    case 'validate':
+    case 'a11y':
+    case 'check': {
+      if (rest.includes('--help') || rest.includes('-h')) {
+        console.log(USAGE);
+        return 0;
+      }
+      const { course, flags } = splitCourseArg(rest);
+      const resolved = resolveCourse(cwd, course);
+      if (!resolved.ok) {
+        console.error(`[tessera] ${resolved.error}`);
+        return 1;
+      }
+      const { courseRoot, workspaceRoot } = resolved;
+
+      switch (sub) {
+        case 'dev': {
+          const { runDev } = await import('./build-commands.js');
+          return runDev(courseRoot, workspaceRoot);
+        }
+        case 'export': {
+          const { runBuild } = await import('./build-commands.js');
+          return runBuild(courseRoot, workspaceRoot);
+        }
+        case 'validate':
+          return runValidate(courseRoot);
+        case 'check': {
+          const validateCode = runValidate(courseRoot);
+          if (validateCode !== 0) return validateCode;
+          return runA11y(courseRoot, workspaceRoot, flags);
+        }
+        case 'a11y':
+          return runA11y(courseRoot, workspaceRoot, flags);
+      }
+      return 0;
+    }
+    case '--help':
+    case '-h':
+      console.log(USAGE);
+      return 0;
+    case undefined:
+      console.error(`No command given.\n\n${USAGE}`);
+      return 1;
+    default:
+      console.error(`Unknown command: ${sub}\n\n${USAGE}`);
+      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.');
+// import.meta.main is true only when this module is the program entry point,
+// and resolves symlinks itself (pnpm/npm bin shims) — Node >= 24.
+if (import.meta.main) {
+  void main(process.argv.slice(2)).then((code) => process.exit(code));
 }
-console.log(
-  '\x1b[2m[tessera] Static checks only. For a full runtime accessibility audit, run: npm run accessibility-check\x1b[0m',
-);
-process.exit(0);

package/src/plugin/course-root.ts

@@ -0,0 +1,98 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { validateProjectName } from './project-name.js';
+
+export interface ResolvedCourse {
+  ok: true;
+  courseRoot: string;
+  workspaceRoot: string;
+}
+
+export type ResolveResult = ResolvedCourse | { ok: false; error: string };
+
+function isDir(path: string): boolean {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function isCourse(dir: string): boolean {
+  return existsSync(join(dir, 'course.config.js'));
+}
+
+// A workspace is the nearest ancestor holding a courses/ directory. The walk
+// includes the starting dir, so the workspace root resolves to itself.
+export function findWorkspaceRoot(cwd: string): string | null {
+  for (let dir = resolve(cwd); ; dir = dirname(dir)) {
+    if (isDir(join(dir, 'courses'))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+  }
+}
+
+export function listCourses(workspaceRoot: string): string[] {
+  const coursesDir = join(workspaceRoot, 'courses');
+  try {
+    return readdirSync(coursesDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && isCourse(join(coursesDir, e.name)))
+      .map((e) => e.name)
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+const NOT_A_WORKSPACE =
+  'Not inside a Tessera workspace — no `courses/` directory was found at or above the current directory.';
+
+function listHint(workspaceRoot: string): string {
+  const courses = listCourses(workspaceRoot);
+  if (courses.length === 0) {
+    return '\nNo courses found. Create one with `tessera new <name>`.';
+  }
+  return (
+    `\nAvailable courses:\n${courses.map((c) => `  ${c}`).join('\n')}` +
+    '\nName one (`tessera <command> <course>`) or cd into its folder.'
+  );
+}
+
+// A name argument always wins; otherwise the cwd must itself be a course. There
+// is deliberately no "single course → use it implicitly" rule, so a bare command
+// never changes meaning when a second course is added.
+export function resolveCourse(cwd: string, name?: string): ResolveResult {
+  const here = resolve(cwd);
+
+  if (name) {
+    const nameError = validateProjectName(name, 'the name');
+    if (nameError) {
+      return {
+        ok: false,
+        error: `Invalid course name "${name}" — ${nameError}.`,
+      };
+    }
+    const workspaceRoot = findWorkspaceRoot(here);
+    if (!workspaceRoot) return { ok: false, error: NOT_A_WORKSPACE };
+    const courseRoot = join(workspaceRoot, 'courses', name);
+    if (!isCourse(courseRoot)) {
+      return {
+        ok: false,
+        error: `Course "${name}" not found in courses/.${listHint(workspaceRoot)}`,
+      };
+    }
+    return { ok: true, courseRoot, workspaceRoot };
+  }
+
+  if (isCourse(here)) {
+    const workspaceRoot = findWorkspaceRoot(here) ?? dirname(dirname(here));
+    return { ok: true, courseRoot: here, workspaceRoot };
+  }
+
+  const workspaceRoot = findWorkspaceRoot(here);
+  if (!workspaceRoot) return { ok: false, error: NOT_A_WORKSPACE };
+  return {
+    ok: false,
+    error: `No course specified.${listHint(workspaceRoot)}`,
+  };
+}

package/src/plugin/duplicate-cli.ts

@@ -0,0 +1,74 @@
+import { cpSync, existsSync } from 'node:fs';
+import { basename, join, relative } from 'node:path';
+import { resolveCourse } from './course-root.js';
+import { validateProjectName } from './project-name.js';
+
+const HELP =
+  'Usage: tessera duplicate <source> <new>\n\n' +
+  'Copy courses/<source>/ to courses/<new>/ within the current workspace.';
+
+// Generated/build artifacts that should never travel with a verbatim copy. The
+// a11y throwaway build and Vite's cache live under node_modules, so they're
+// already pruned by the node_modules skip; the rest are belt-and-suspenders.
+const SKIP = new Set(['node_modules', 'dist', 'a11y-report.json', '.vite']);
+
+function skip(srcPath: string): boolean {
+  const name = basename(srcPath);
+  return SKIP.has(name) || name.startsWith('.tessera');
+}
+
+// `tessera duplicate <source> <new>` — copy an existing course verbatim within
+// the current workspace. Unlike `new`, there is no template stamping: the JS
+// config (including its title) is copied untouched.
+export function runDuplicate(
+  source: string | undefined,
+  target: string | undefined,
+  cwd: string,
+): number {
+  if (
+    source === '--help' ||
+    source === '-h' ||
+    target === '--help' ||
+    target === '-h'
+  ) {
+    console.log(HELP);
+    return 0;
+  }
+  if (!source || !target) {
+    console.error('Usage: tessera duplicate <source> <new>');
+    return 1;
+  }
+
+  const nameError = validateProjectName(target, 'Course name');
+  if (nameError) {
+    console.error(`[tessera duplicate] ${nameError}`);
+    return 1;
+  }
+
+  const resolved = resolveCourse(cwd, source);
+  if (!resolved.ok) {
+    console.error(`[tessera duplicate] ${resolved.error}`);
+    return 1;
+  }
+  const { courseRoot: srcDir, workspaceRoot } = resolved;
+
+  const destDir = join(workspaceRoot, 'courses', target);
+  if (existsSync(destDir)) {
+    console.error(`[tessera duplicate] Course "${target}" already exists.`);
+    return 1;
+  }
+
+  cpSync(srcDir, destDir, {
+    recursive: true,
+    filter: (src) => src === srcDir || !skip(src),
+  });
+
+  const rel = relative(workspaceRoot, destDir);
+  const srcRel = relative(workspaceRoot, srcDir);
+  console.log(
+    `\nCreated ${rel} (duplicated from ${srcRel}).\n\n` +
+      `Remember to update the title in ${rel}/course.config.js.\n\n` +
+      `Next steps:\n  pnpm tessera dev ${target}\n`,
+  );
+  return 0;
+}