@lincyaw/addon-classroom 0.0.0-stage → 1.0.0-rc.2

package/src/domain/summary.ts

@@ -0,0 +1,96 @@
+import type { Participant, SessionStatus } from '@lincyaw/kernel'
+import type { SectionNumbers } from './config.ts'
+import { exerciseTally } from './exercise.ts'
+import type { ExerciseTally, Submission } from './exercise.ts'
+import { placeIndex, placeKey } from './place.ts'
+import type { Place } from './place.ts'
+import { predictionTally } from './predict.ts'
+import type { Prediction, PredictionTally } from './predict.ts'
+import { pulseTally } from './pulse.ts'
+import type { PulseVote } from './pulse.ts'
+import type { Question } from './questions.ts'
+import { countedAnswers, quizTally } from './quiz.ts'
+import type { Answer, QuizState, QuizTally } from './quiz.ts'
+import { latestPerParticipant } from './tally.ts'
+
+/** A component's place, numbered in this window's version, and its id (the place's key). */
+type Where = Place & { id: string }
+
+export interface ClassroomRecords {
+  quizzes: (QuizState & { id: string })[]
+  answers: Answer[]
+  predictions: Prediction[]
+  votes: PulseVote[]
+  submissions: Submission[]
+  numbers?: SectionNumbers
+}
+
+/** The tallies of each component of the classroom, in the order of their places. */
+export interface ClassroomRows {
+  quizzes: (Where & { open: boolean, options: string[], tally: QuizTally })[]
+  predictions: (Where & { question: string, choices?: string[], tally: PredictionTally })[]
+  pulse: (Where & { levels: string[], counts: number[] })[]
+  exercises: (Where & { tally: ExerciseTally })[]
+}
+
+export function classroomRows(records: ClassroomRecords): ClassroomRows {
+  const where = (place: Place): Where => ({ id: placeKey(place), section: place.section, block: place.block, title: place.title, index: placeIndex(place, records.numbers) })
+  const latestByPlace = <T extends Place>(items: T[], id: (item: T) => string): T[] =>
+    [...new Map(items.map(item => [id(item), item])).values()].sort((a, b) => placeIndex(a, records.numbers) - placeIndex(b, records.numbers))
+  return {
+    quizzes: latestByPlace(records.quizzes, q => q.id).map(quiz => ({
+      ...where(quiz),
+      open: quiz.open,
+      options: quiz.options,
+      tally: quizTally(quiz.options.length, quiz.correct, countedAnswers(quiz.id, quiz, records.answers)),
+    })),
+    predictions: latestByPlace(records.predictions, p => p.predictId).map(prediction => ({
+      ...where(prediction),
+      question: prediction.question,
+      ...prediction.choices ? { choices: prediction.choices } : {},
+      tally: predictionTally(prediction.predictId, prediction.choices?.length ?? 0, records.predictions),
+    })),
+    pulse: latestByPlace(records.votes, v => v.pulseId).map(vote => ({
+      ...where(vote),
+      levels: vote.levels,
+      counts: pulseTally(vote.pulseId, vote.levels.length, records.votes),
+    })),
+    exercises: latestByPlace(records.submissions, s => s.exerciseId).map(submission => ({
+      ...where(submission),
+      tally: exerciseTally(latestPerParticipant(records.submissions.filter(s => s.exerciseId === submission.exerciseId))),
+    })),
+  }
+}
+
+export function unansweredCount(questions: readonly Question[]): number {
+  return questions.filter(q => !q.answered).length
+}
+
+export interface ClassroomSummary {
+  status: SessionStatus
+  learners: number
+  questions: { asked: number, unanswered: number }
+  quizzes: (Where & { open: boolean, options: string[], counts: number[], respondents: number, correct: number })[]
+  predictions: (Where & { question: string, choices?: string[], counts?: number[], respondents: number })[]
+  pulse: (Where & { levels: string[], counts: number[] })[]
+  exercises: (Where & { submitted: number, passed: number })[]
+}
+
+export interface SummaryInput extends ClassroomRecords {
+  status: SessionStatus
+  participants: Participant[]
+  questions: Question[]
+}
+
+export function classroomSummary(input: SummaryInput): ClassroomSummary {
+  const rows = classroomRows(input)
+  return {
+    status: input.status,
+    learners: input.participants.filter(p => p.role === 'learner').length,
+    questions: { asked: input.questions.length, unanswered: unansweredCount(input.questions) },
+    quizzes: rows.quizzes.map(({ tally, ...quiz }) => ({ ...quiz, ...tally })),
+    predictions: rows.predictions.map(({ tally, choices, question, ...place }) => ({ ...place, question, ...choices ? { choices, counts: tally.counts } : {}, respondents: tally.respondents })),
+    pulse: rows.pulse,
+    exercises: rows.exercises.map(({ tally, ...place }) => ({ ...place, submitted: tally.submitted, passed: tally.passed })),
+  }
+}

package/src/domain/tally.ts

@@ -0,0 +1,8 @@
+export function latestPerParticipant<T extends { participant: string, at: number }>(items: Iterable<T>): T[] {
+  const latest = new Map<string, T>()
+  for (const item of items) {
+    const before = latest.get(item.participant)
+    if (!before || item.at >= before.at) latest.set(item.participant, item)
+  }
+  return [...latest.values()]
+}

package/src/node/classroom-pass.ts

@@ -0,0 +1,84 @@
+import { deckLocale, isRecord } from '@lincyaw/kernel'
+import type { ComponentNode, IRBlock, IRDocument, IRPass, IRSection, PassContext } from '@lincyaw/kernel'
+import { CLASSROOM_ID, isAuthorLabel, isForStudents, MESSAGES } from '../domain/index.ts'
+import type { ClassroomMessages, Place } from '../domain/index.ts'
+import { isClassroomComponent, isPredict } from './components.ts'
+import { fallbackOf } from './fallbacks.ts'
+
+/** The blocks of a section, with what a {predict} reveals in front of it. */
+function sectionBlocks(section: IRSection): IRBlock[] {
+  return section.blocks.flatMap((block) => {
+    const { node } = block
+    return isPredict(node) ? [...(node.children ?? []).filter(child => child.id !== 'prompt'), block] : [block]
+  })
+}
+
+/** Writes the number of every section students have into the plugin's configuration (`presmium.classroom.sections`). */
+function writeSectionNumbers(doc: IRDocument): void {
+  const own = doc.config.presmium[CLASSROOM_ID]
+  doc.config.presmium[CLASSROOM_ID] = {
+    ...isRecord(own) ? own : {},
+    sections: Object.fromEntries(doc.sections.filter(isForStudents).map(section => [section.id, section.index])),
+  }
+}
+
+function isLabelled(lines: readonly string[], from: number, at: number, id: string): boolean {
+  let end = at
+  while (end < lines.length && lines[end]!.trim().startsWith(':')) end++
+  return lines.slice(from - 1, end).some(line => line.trim() === `(${id})=` || line.trim() === `:label: ${id}`)
+}
+
+/** Warns of a label the author wrote that looks like a generated block id. */
+async function checkLabel(block: IRBlock, section: IRSection, linesOf: (file: string) => Promise<string[]>, ctx: PassContext): Promise<void> {
+  const { source } = block
+  if (isAuthorLabel(block.id)) return
+  const from = source.file === section.source.file ? section.source.line : 1
+  if (!isLabelled(await linesOf(source.file), from, source.line, block.id)) return
+  ctx.report({
+    checkId: CLASSROOM_ID,
+    severity: 'warning',
+    message: `label (${block.id})= ends in -<number> like a generated block id: it takes no notes and the presenter's lists do not name it; choose another label`,
+    source: { file: source.file, line: source.line },
+  })
+}
+
+/** Gives a classroom component its place, its default props and its fallback, and checks its target. */
+function placeComponent(node: ComponentNode, block: IRBlock, section: IRSection, blocks: readonly IRBlock[], t: ClassroomMessages, ctx: PassContext): void {
+  node.props.place = { section: section.id, block: block.id, title: section.title, index: section.index } satisfies Place
+  if (node.name === 'PmPulse') {
+    node.props.question ??= t.pulse.question
+    node.props.levels ??= t.pulse.levels
+  }
+  node.fallback = fallbackOf(node, t)
+  const { target } = node.props
+  if (typeof target === 'string' && !blocks.some(b => b.id === target)) {
+    ctx.report({
+      checkId: CLASSROOM_ID,
+      severity: 'warning',
+      message: `{question-box}: no block (${target})= in section ${section.id}; questions are attached to the section`,
+      source: { file: block.source.file, line: block.source.line },
+    })
+    delete node.props.target
+  }
+}
+
+export const classroomPass: IRPass = {
+  name: 'presmium.classroom.places',
+  async run(doc, ctx) {
+    const t = MESSAGES[deckLocale(ctx.lang)]
+    writeSectionNumbers(doc)
+    const sources = new Map<string, Promise<string[]>>()
+    const linesOf = (file: string) => {
+      let lines = sources.get(file)
+      if (!lines) sources.set(file, lines = ctx.src.read(file).then(text => text?.split('\n') ?? []))
+      return lines
+    }
+    for (const section of doc.sections) {
+      const blocks = sectionBlocks(section)
+      for (const block of blocks) {
+        await checkLabel(block, section, linesOf, ctx)
+        if (isClassroomComponent(block.node)) placeComponent(block.node, block, section, blocks, t, ctx)
+      }
+    }
+  },
+}

package/src/node/components.ts

@@ -0,0 +1,10 @@
+import type { ComponentNode, IRNode } from '@lincyaw/kernel'
+import { CLASSROOM_ID } from '../domain/index.ts'
+
+export function isClassroomComponent(node: IRNode): node is ComponentNode {
+  return node.type === 'component' && node.plugin === CLASSROOM_ID
+}
+
+export function isPredict(node: IRNode): node is ComponentNode {
+  return isClassroomComponent(node) && node.name === 'PmPredict'
+}

package/src/node/directives.ts

@@ -0,0 +1,77 @@
+import type { ComponentNode, DirectiveContext, DirectiveSpec, IRBlock, MdastNode } from '@lincyaw/kernel'
+import { CLASSROOM_ID, exerciseSource, optionList, quizSource } from '../domain/index.ts'
+
+function component(name: string, props: Record<string, unknown>, prompt: MdastNode[], ctx: DirectiveContext): ComponentNode {
+  const children: IRBlock[] = prompt.length ? [{ id: 'prompt', role: 'visual', at: 0, source: ctx.source, node: { type: 'markdown', mdast: { type: 'root', children: prompt } } }] : []
+  return { type: 'component', plugin: CLASSROOM_ID, name, props, ...children.length ? { children } : {} }
+}
+
+const body = (text: string, ctx: DirectiveContext): MdastNode => (text.trim() ? ctx.parse(text) : { type: 'root', children: [] })
+
+export const quizDirective: DirectiveSpec = {
+  name: 'quiz',
+  body: true,
+  toIR(input, ctx) {
+    const { prompt, options, correct } = quizSource(body(input.body, ctx))
+    if (options.length < 2) ctx.report({ checkId: CLASSROOM_ID, severity: 'error', message: '{quiz} needs at least two options, written as a task list: `- [ ] wrong`, `- [x] right`' })
+    else if (correct.length === 0) ctx.report({ checkId: CLASSROOM_ID, severity: 'error', message: '{quiz}: mark the right options with `[x]`' })
+    return { node: component('PmQuiz', { options, correct }, prompt, ctx) }
+  },
+}
+
+export const exerciseDirective: DirectiveSpec = {
+  name: 'exercise',
+  arg: true,
+  body: true,
+  options: { timeout: 'number' },
+  toIR(input, ctx) {
+    const lang = input.arg?.trim() || 'python'
+    const { prompt, code } = exerciseSource(body(input.body, ctx))
+    const [starter, checks] = code
+    if (!checks) ctx.report({ checkId: CLASSROOM_ID, severity: 'error', message: '{exercise} needs two code blocks: the starter code, then the checks' })
+    if (code.length > 2) ctx.report({ checkId: CLASSROOM_ID, severity: 'warning', message: '{exercise}: code blocks after the second (the checks) are ignored' })
+    if (lang !== 'python') ctx.report({ checkId: CLASSROOM_ID, severity: 'warning', message: `{exercise}: checks run Python; ${lang} exercises cannot be checked` })
+    const props: Record<string, unknown> = { lang, starter: starter?.value ?? '', checks: checks?.value ?? '' }
+    const timeout = Number(input.options.timeout)
+    if (Number.isFinite(timeout) && timeout > 0) props.timeout = timeout
+    return { node: component('PmExercise', props, prompt, ctx) }
+  },
+}
+
+export const questionBoxDirective: DirectiveSpec = {
+  name: 'question-box',
+  body: true,
+  options: { target: 'string' },
+  toIR(input, ctx) {
+    const target = typeof input.options.target === 'string' ? input.options.target.trim() : ''
+    return { node: component('PmQuestionBox', target ? { target } : {}, body(input.body, ctx).children ?? [], ctx) }
+  },
+}
+
+export const pulseDirective: DirectiveSpec = {
+  name: 'pulse',
+  arg: true,
+  body: true,
+  options: { levels: 'string' },
+  toIR(input, ctx) {
+    const question = input.arg?.trim()
+    const levels = optionList(input.options.levels)
+    return { node: component('PmPulse', { ...question ? { question } : {}, ...levels ? { levels } : {} }, body(input.body, ctx).children ?? [], ctx) }
+  },
+}
+
+export const predictDirective: DirectiveSpec = {
+  name: 'predict',
+  arg: true,
+  body: true,
+  options: { choices: 'string' },
+  toIR(input, ctx) {
+    const question = input.arg?.trim() ?? ''
+    const choices = optionList(input.options.choices)
+    if (!question) ctx.report({ checkId: CLASSROOM_ID, severity: 'error', message: '{predict} needs the question as its argument: ```{predict} How many …?' })
+    if (input.options.choices !== undefined && !choices) ctx.report({ checkId: CLASSROOM_ID, severity: 'warning', message: '{predict}: :choices: needs at least two, separated by commas; readers write their prediction instead' })
+    const node = component('PmPredict', { question, ...choices ? { choices } : {} }, body(input.body, ctx).children ?? [], ctx)
+    node.ownsCode = false
+    return { node }
+  },
+}

package/src/node/fallbacks.ts

@@ -0,0 +1,86 @@
+import { deckLocale, docBlocks } from '@lincyaw/kernel'
+import type { ComponentNode, IRBlock, IRPass, MdastNode, RunResult } from '@lincyaw/kernel'
+import { MESSAGES, optionLetter } from '../domain/index.ts'
+import type { ClassroomMessages } from '../domain/index.ts'
+import { isPredict } from './components.ts'
+
+const text = (value: string): MdastNode => ({ type: 'text', value })
+const paragraph = (...children: MdastNode[]): MdastNode => ({ type: 'paragraph', children })
+const strong = (value: string): MdastNode => ({ type: 'strong', children: [text(value)] })
+const strings = (value: unknown): string[] => (Array.isArray(value) ? value.map(String) : [])
+const html = (value: string): MdastNode => ({ type: 'html', value })
+const numbered = (items: string[]): MdastNode => ({ type: 'list', ordered: true, spread: false, children: items.map(item => ({ type: 'listItem', children: [paragraph(text(item))] })) })
+const lettered = (items: string[]): MdastNode[] => items.map((item, i) => paragraph(text(`${optionLetter(i)}. ${item}`)))
+
+const joined = (value: unknown): string => (Array.isArray(value) ? value.join('') : typeof value === 'string' ? value : '')
+
+function outputText(run: RunResult): string {
+  if (!run.outputs) return [run.stdout, run.stderr].join('')
+  return run.outputs.map((output) => {
+    if (output.output_type === 'stream') return joined(output.text)
+    if (output.output_type === 'error') return `${output.ename}: ${output.evalue}\n`
+    const text = joined(output.data['text/plain'])
+    return text && !text.endsWith('\n') ? `${text}\n` : text
+  }).join('')
+}
+
+function blockContent({ node }: IRBlock): MdastNode[] {
+  if (node.type === 'markdown') return node.mdast.type === 'root' ? node.mdast.children ?? [] : [node.mdast]
+  if (node.type === 'code') {
+    const output = (node.outputs ?? []).map(outputText).join('').trimEnd()
+    return [
+      ...node.echo === false ? [] : [{ type: 'code', lang: node.lang, value: node.value }],
+      ...output ? [{ type: 'code', lang: 'text', value: output }] : [],
+    ]
+  }
+  return node.fallback?.children ?? []
+}
+
+function foldedReveal(node: ComponentNode, t: ClassroomMessages): MdastNode[] {
+  const ids = new Set([...strings(node.props.reveal), ...strings(node.props.notes)])
+  const content = (node.children ?? []).filter(block => ids.has(block.id)).flatMap(blockContent)
+  return content.length ? [html(`<details data-static="open"><summary>${t.fallback.reveal}</summary>`), ...content, html('</details>')] : []
+}
+
+function componentBody(node: ComponentNode, t: ClassroomMessages): MdastNode[] {
+  const { props } = node
+  switch (node.name) {
+    case 'PmQuiz':
+      return [
+        ...lettered(strings(props.options)),
+        html(`<details><summary>${t.fallback.answer}</summary>${(props.correct as number[] ?? []).map(optionLetter).join(t.quiz.letters)}</details>`),
+      ]
+    case 'PmExercise':
+      return [
+        { type: 'code', lang: String(props.lang), value: String(props.starter ?? '') },
+        paragraph(strong(t.fallback.checks)),
+        { type: 'code', lang: String(props.lang), value: String(props.checks ?? '') },
+      ]
+    case 'PmQuestionBox':
+      return [paragraph(strong(t.fallback.questions.label), text(t.fallback.questions.text))]
+    case 'PmPulse':
+      return [paragraph(strong(t.fallback.pulse.label), text(t.fallback.pulse.text(String(props.question), strings(props.levels))))]
+    case 'PmPredict':
+      return [props.choices ? numbered(strings(props.choices)) : paragraph(text(t.fallback.write)), ...foldedReveal(node, t)]
+    default:
+      return []
+  }
+}
+
+export function fallbackOf(node: ComponentNode, t: ClassroomMessages): MdastNode {
+  const prompt = node.children?.find(block => block.id === 'prompt')?.node
+  const question = node.name === 'PmPredict' ? [paragraph(strong(t.fallback.predict), text(`${t.colon}${String(node.props.question)}`))] : []
+  return { type: 'root', children: [...question, ...prompt?.type === 'markdown' ? prompt.mdast.children ?? [] : [], ...componentBody(node, t)] }
+}
+
+export const predictFallbacksPass: IRPass = {
+  name: 'presmium.classroom.predict-fallbacks',
+  after: 'execute',
+  order: 1,
+  run(doc, ctx) {
+    const t = MESSAGES[deckLocale(ctx.lang)]
+    for (const { block: { node } } of docBlocks(doc)) {
+      if (isPredict(node)) node.fallback = fallbackOf(node, t)
+    }
+  },
+}

package/src/node/notebook.ts

@@ -0,0 +1,32 @@
+import { deckLocale } from '@lincyaw/kernel'
+import type { ComponentNode, IRBlock, MdastNode, RenderContext, RendererContribution } from '@lincyaw/kernel'
+import { MESSAGES } from '../domain/index.ts'
+
+function code(source: string) {
+  return { cell_type: 'code' as const, source, outputs: [], execution_count: null }
+}
+
+function exerciseCells(node: ComponentNode, _block: IRBlock, ctx: RenderContext): unknown[] {
+  const t = MESSAGES[deckLocale(ctx.lang)]
+  const prompt = node.children?.find(block => block.node.type === 'markdown')?.node
+  const intro = prompt?.type === 'markdown' ? prompt.mdast.children ?? [] : []
+  const label: MdastNode = { type: 'paragraph', children: [{ type: 'strong', children: [{ type: 'text', value: t.fallback.exercise }] }] }
+  return [
+    ...intro.length ? [{ cell_type: 'markdown', mdast: { type: 'root', children: [label, ...intro] } }] : [],
+    code(String(node.props.starter ?? '')),
+    code(`${t.fallback.checkCell}\n${String(node.props.checks ?? '')}`),
+  ]
+}
+
+function predictCells(node: ComponentNode): unknown[] {
+  return node.fallback ? [{ cell_type: 'markdown', mdast: node.fallback }] : []
+}
+
+export const notebookContribution: RendererContribution = {
+  components: {
+    PmExercise: exerciseCells,
+    PmPredict: predictCells,
+    PmQuestionBox: () => [],
+    PmPulse: () => [],
+  },
+}

package/src/node/presmium.ts

@@ -0,0 +1,21 @@
+import { createRequire } from 'node:module'
+import type { PresmiumNodePlugin } from '@lincyaw/kernel'
+import { CLASSROOM_ID } from '../domain/index.ts'
+import { classroomPass } from './classroom-pass.ts'
+import { exerciseDirective, predictDirective, pulseDirective, questionBoxDirective, quizDirective } from './directives.ts'
+import { predictFallbacksPass } from './fallbacks.ts'
+import { notebookContribution } from './notebook.ts'
+import { revealsPass } from './reveals.ts'
+
+const { version } = createRequire(import.meta.url)('../../package.json') as { version: string }
+
+const plugin: PresmiumNodePlugin = {
+  id: CLASSROOM_ID,
+  version,
+  kernel: '^1.0.0',
+  directives: [quizDirective, exerciseDirective, questionBoxDirective, pulseDirective, predictDirective],
+  passes: [revealsPass, classroomPass, predictFallbacksPass],
+  rendererExtensions: { notebook: notebookContribution },
+}
+
+export default plugin

package/src/node/reveals.ts

@@ -0,0 +1,29 @@
+import { deckLocale, docBlocks } from '@lincyaw/kernel'
+import type { IRPass } from '@lincyaw/kernel'
+import { CLASSROOM_ID, MESSAGES } from '../domain/index.ts'
+import { isPredict } from './components.ts'
+
+/** Predictions consume authored child identities and their explicit step visibility. */
+export const revealsPass: IRPass = {
+  name: 'presmium.classroom.predict-reveals',
+  order: -1,
+  run(doc, ctx) {
+    const t = MESSAGES[deckLocale(ctx.lang)].predict
+    for (const { block } of docBlocks(doc)) {
+      const { node } = block
+      if (!isPredict(node)) continue
+      const children = new Set(node.children?.map(child => child.id) ?? [])
+      for (const property of ['reveal', 'notes'] as const) {
+        const targets = node.props[property]
+        if (targets === undefined) continue
+        if (!Array.isArray(targets) || targets.some(target => typeof target !== 'string') || new Set(targets).size !== targets.length) {
+          ctx.report({ checkId: CLASSROOM_ID, severity: 'error', message: t.invalidTargets(property), source: block.source })
+          continue
+        }
+        for (const target of targets) if (!children.has(target)) ctx.report({
+          checkId: CLASSROOM_ID, severity: 'error', message: t.missingTarget(property, target, block.id), source: block.source,
+        })
+      }
+    }
+  },
+}