diff --git a/docs/autopilot.md b/docs/autopilot.md index 5f97a65..4e0460e 100644 --- a/docs/autopilot.md +++ b/docs/autopilot.md @@ -63,7 +63,10 @@ The owner's priority since 2026-11-03: proper exam practice. The design, decisio - [x] Computer Organization 10, Microprocessors 10, Computer Architecture 6, Computer Networks 27, Data Structures 28: 81 tagged. (PR #104, stacked on #102) - [x] Discrete Mathematics 42, Logic Design 40, Algorithm Design 16: 98 tagged (5 with `lesson` only, where no single heading teaches the idea). (PR #105, stacked on #104) - [x] Computational Mathematics 83 tagged (1 with `lesson` only). (PR #108, stacked on #105) Every migrated question now names its lesson. Questions added to a quiz later still need a `lesson` by hand; no test enforces it, so authors' quiz rounds aren't blocked. -- [ ] 5. Generated questions (subnets, scheduling, Big-O first). +- [ ] 5. Generated questions (subnets, scheduling, Big-O first). Split into runs: + - [x] 5a. The `QuestionGenerator` plumbing (`instantiate`, `buildOptions`, `generators.ts` per course, `loadBank` adding instances, a fresh seed per exam attempt) and three Computer Networks generators: usable hosts, network address and broadcast address of a random subnet. (PR #109, stacked on #108) + - [ ] 5b. Operating Systems: CPU scheduling (waiting and turnaround times from `src/lib` scheduling logic). + - [ ] 5c. Algorithm Design: Big-O and step counts. The owner's course, so ask before adding. - [ ] 6. Account sync for review cards and exam attempts. ## Parked @@ -97,6 +100,7 @@ Nothing. The exam-stack block (since 2026-11-06, over #68's inline practice ques Newest first. One line per run: date and run, what was done, PR link, merged or open. +- 2026-11-20 10:40 (run B): exam phase 5a: generated questions. `QuestionGenerator` plumbing plus three subnet generators for Computer Networks (usable hosts, network address, broadcast address), answers from the lesson's own `parseCidr` and checked over 500 seeds against an independent bit-mask calculation. They appear in the course exam (fresh numbers every attempt) and in review (fresh numbers every session). PR #109, open, stacked on #108. - 2026-11-20 06:10 (run A): exam phase 4d finished: Computational Mathematics' 83 quiz questions tagged with lesson and section, so all 262 migrated questions now link back to their lesson. Next exam phase: 5, generated questions (subnets, scheduling, Big-O first). PR #108, open, stacked on #105. - 2026-11-19 10:40 (run B): exam phase 4d, second batch: tagged 98 quiz questions in Discrete Mathematics, Logic Design and Algorithm Design with the lesson and section that teach each (lesson only for 5 where no one heading does). Algorithm Design is the owner's course: only tags were added, no wording changed. Left: Computational Mathematics' 83. PR #105, open, stacked on #104. - 2026-11-19 06:10 (run A): exam phase 4d started. Tagged 81 migrated quiz questions in five courses with the lesson (and, where one heading teaches it, the section) that teaches each, checked against the lesson text. The bank test confirms every lesson and heading exists. PR #104, open, stacked on #102. diff --git a/docs/exams.md b/docs/exams.md index c1c5fdd..216c341 100644 --- a/docs/exams.md +++ b/docs/exams.md @@ -46,12 +46,14 @@ A module quiz shows the questions whose `quiz` is its slug (`questionsForQuiz(qu The 259 questions that existed before the bank keep their wording and have ids `//q` (for example `computer-networks/foundations-quiz/q1`). For them only the quiz is known, not the lesson that teaches each one, so their `lesson` is empty until it's filled in by hand (phase 4). New questions should always set `lesson`, and `section` where one heading teaches the idea. Tests check that ids are unique site-wide, that every `lesson` and `section` exists, and that every course with lessons has questions. -Generated questions implement the same shape from a function and a seed: +Generated questions implement the same shape from a function and a seed. Each course keeps them in `src/content//generators.ts`: ```ts -export type QuestionGenerator = { id: string; lesson: string; section?: string; generate: (seed: number) => Question }; +export type QuestionGenerator = { id: string; lesson: string; section?: string; generate: (random: () => number) => GeneratedBody }; ``` +`instantiate(generator, seed)` (in `src/lib/questions.ts`) seeds the random function, mixing in the generator's id so two generators with the same seed draw different numbers, and fills in the id, lesson and section. The id is the same for every seed, so the review queue tracks the skill rather than one set of numbers. `loadBank(course, seed)` adds one instance of each generator to the fixed bank, and the exam page uses a fresh seed for every attempt. `buildOptions(right, wrong, random)` drops duplicate distractors and puts the right answer at a random position. + The generator calls the course's `src/lib` logic for the right answer and builds the wrong options from typical mistakes (an off-by-one, the inverse formula), not random numbers. Its tests check, over many seeds, that options are distinct and exactly one is correct. ### Exams diff --git a/src/content/computer-networks/generators.ts b/src/content/computer-networks/generators.ts new file mode 100644 index 0000000..8f21db3 --- /dev/null +++ b/src/content/computer-networks/generators.ts @@ -0,0 +1,92 @@ +/* Generated questions for Computer Networks: fresh numbers every time, answers computed by + the same functions the lessons' visualizers use. Format: docs/exams.md. */ + +import { buildOptions, randomInt, type QuestionGenerator } from "@/lib/questions"; +import { intToIp, ipToInt, parseCidr } from "@/lib/networks"; + +const LESSON = "ip-addresses-and-subnets"; + +/** 2 to a power, written the way the lessons write it: 2⁵. */ +const pow2 = (n: number) => "2" + [...String(n)].map((d) => "⁰¹²³⁴⁵⁶⁷⁸⁹"[Number(d)]).join(""); +const SECTION = "network-part-and-host-part"; + +/** A private-range address whose host part is neither all zeros nor all ones for the given prefix. */ +function randomAddress(random: () => number, prefix: number): string { + const first = [10, 172, 192][randomInt(random, 0, 2)]; + const second = first === 10 ? randomInt(random, 0, 255) : first === 172 ? randomInt(random, 16, 31) : 168; + const base = ipToInt(`${first}.${second}.${randomInt(random, 0, 255)}.0`); + const size = 2 ** (32 - prefix); + const network = Math.floor((base + randomInt(random, 0, 255)) / size) * size; + const host = randomInt(random, 2, Math.min(size - 3, 2 ** 24)); + return intToIp(network + host); +} + +/** A prefix that doesn't fall on an octet boundary, so the work happens inside one octet. */ +const randomPrefix = (random: () => number) => [18, 19, 20, 21, 22, 23, 25, 26, 27, 28, 29][randomInt(random, 0, 10)]; + +/** The octet where the network/host boundary falls, and how many addresses one block spans in it. */ +function boundary(prefix: number) { + const octet = Math.floor(prefix / 8); // 0-based + const block = 2 ** (8 - (prefix % 8)); + return { octet, block, name: ["first", "second", "third", "fourth"][octet] }; +} + +export const generators: QuestionGenerator[] = [ + { + id: "computer-networks/ip-addresses-and-subnets/gen-usable-hosts", + lesson: LESSON, + section: SECTION, + generate(random) { + const prefix = randomInt(random, 20, 30); + const h = 32 - prefix; + const right = 2 ** h - 2; + return { + prompt: `How many usable host addresses does a /${prefix} subnet have?`, + ...buildOptions(String(right), [String(2 ** h), String(2 ** h - 1), String(2 ** (h + 1) - 2)], random), + explanation: `A /${prefix} leaves 32 − ${prefix} = ${h} host bits, so the block has ${pow2(h)} = ${2 ** h} addresses. Two are set aside: all host bits 0 is the network address and all host bits 1 is the broadcast address. That leaves ${2 ** h} − 2 = ${right}. ${2 ** h} forgets those two; ${2 ** (h + 1) - 2} is the answer for a /${prefix - 1}.`, + difficulty: 1, + }; + }, + }, + { + id: "computer-networks/ip-addresses-and-subnets/gen-network-address", + lesson: LESSON, + section: SECTION, + generate(random) { + const prefix = randomPrefix(random); + const ip = randomAddress(random, prefix); + const s = parseCidr(`${ip}/${prefix}`); + const { octet, block, name } = boundary(prefix); + const value = Number(ip.split(".")[octet]); + const right = intToIp(s.network); + const lastOctetZeroed = intToIp(Math.floor(ipToInt(ip) / 256) * 256); + return { + prompt: `What is the network address of ${ip}/${prefix}?`, + ...buildOptions(right, [intToIp(s.network + 1), intToIp(s.broadcast), lastOctetZeroed, ip], random), + explanation: `A /${prefix} splits inside the ${name} octet, where blocks are ${block} wide (${pow2(8 - (prefix % 8))}). ${value} falls in the block starting at ${Math.floor(value / block) * block} (${value} ÷ ${block}, rounded down, × ${block}), and every octet after it becomes 0: ${right}. ${intToIp(s.network + 1)} is the first usable host, one past the network address, and ${intToIp(s.broadcast)} is the broadcast address at the other end of the block.`, + difficulty: 2, + }; + }, + }, + { + id: "computer-networks/ip-addresses-and-subnets/gen-broadcast-address", + lesson: LESSON, + section: SECTION, + generate(random) { + const prefix = randomPrefix(random); + const ip = randomAddress(random, prefix); + const s = parseCidr(`${ip}/${prefix}`); + const { octet, block, name } = boundary(prefix); + const value = Number(ip.split(".")[octet]); + const start = Math.floor(value / block) * block; + const right = intToIp(s.broadcast); + const lastOctet255 = intToIp(Math.floor(ipToInt(ip) / 256) * 256 + 255); + return { + prompt: `What is the broadcast address of ${ip}/${prefix}?`, + ...buildOptions(right, [intToIp(s.broadcast - 1), intToIp(s.network), lastOctet255, intToIp(s.broadcast + 1)], random), + explanation: `A /${prefix} splits inside the ${name} octet, where blocks are ${block} wide. ${value} is in the block ${start} to ${start + block - 1}, so the ${name} octet of the broadcast address is ${start + block - 1} and every octet after it is 255: ${right}. ${intToIp(s.broadcast - 1)} is the last usable host, one before it, and ${intToIp(s.network)} is the network address.`, + difficulty: 2, + }; + }, + }, +]; diff --git a/src/content/questionBanks.ts b/src/content/questionBanks.ts index a7a0182..000368b 100644 --- a/src/content/questionBanks.ts +++ b/src/content/questionBanks.ts @@ -1,16 +1,27 @@ /* Loads a course's question bank (src/content//questions.ts) on demand, so a - page only downloads the bank it needs. */ + page only downloads the bank it needs. A course can also have generated questions + (src/content//generators.ts), which get fresh numbers from each seed. */ -import type { Question } from "@/lib/questions"; +import { instantiate, type Question, type QuestionGenerator } from "@/lib/questions"; const banks = import.meta.glob<{ questions: Question[] }>("./*/questions.ts"); +const generatorFiles = import.meta.glob<{ generators: QuestionGenerator[] }>("./*/generators.ts"); const slugOf = (path: string) => path.split("/")[1]; -/** Courses that have a question bank. */ -export const coursesWithBanks = new Set(Object.keys(banks).map(slugOf)); +/** Courses that have a question bank or generated questions. */ +export const coursesWithBanks = new Set([...Object.keys(banks), ...Object.keys(generatorFiles)].map(slugOf)); -export async function loadBank(courseSlug: string): Promise { - const load = banks[`./${courseSlug}/questions.ts`]; - return load ? (await load()).questions : []; +/** A course's generated questions, still as generators: call instantiate() with a seed for numbers. */ +export async function loadGenerators(courseSlug: string): Promise { + const load = generatorFiles[`./${courseSlug}/generators.ts`]; + return load ? (await load()).generators : []; +} + +/** A course's questions: its fixed bank plus one copy of each generated question, numbered from `seed`. */ +export async function loadBank(courseSlug: string, seed = Math.floor(Math.random() * 2 ** 31)): Promise { + const loadFixed = banks[`./${courseSlug}/questions.ts`]; + const loadGen = generatorFiles[`./${courseSlug}/generators.ts`]; + const [fixed, gens] = await Promise.all([loadFixed ? loadFixed().then((m) => m.questions) : [], loadGen ? loadGen().then((m) => m.generators) : []]); + return [...fixed, ...gens.map((g) => instantiate(g, seed))]; } diff --git a/src/lib/questions.ts b/src/lib/questions.ts index 0dda7d8..41d9bc2 100644 --- a/src/lib/questions.ts +++ b/src/lib/questions.ts @@ -25,3 +25,61 @@ export type Question = { export function questionsForQuiz(bank: Question[], quizSlug: string): Question[] { return bank.filter((q) => q.quiz === quizSlug); } + +/* ------------------------------ generated questions ------------------------------ */ + +/** What a generator produces for one seed: a question without its id, lesson and section, which come from the generator. */ +export type GeneratedBody = Pick; + +/** + * A question with fresh numbers every time. The id stays the same across seeds, so the + * review queue tracks the skill, not one set of numbers. Each course keeps its generators + * in src/content//generators.ts. Design: docs/exams.md. + */ +export type QuestionGenerator = { + id: string; + lesson: string; + section?: string; + generate: (random: () => number) => GeneratedBody; +}; + +/** A small seeded random number generator (mulberry32). */ +function mulberry32(seed: number): () => number { + let a = seed >>> 0; + return () => { + a = (a + 0x6d2b79f5) >>> 0; + let t = a; + t = Math.imul(t ^ (t >>> 15), t | 1); + t ^= t + Math.imul(t ^ (t >>> 7), t | 61); + return ((t ^ (t >>> 14)) >>> 0) / 4294967296; + }; +} + +/** FNV-1a, so generators given the same seed still draw different numbers. */ +function hashId(id: string): number { + let h = 0x811c9dc5; + for (let i = 0; i < id.length; i++) h = Math.imul(h ^ id.charCodeAt(i), 0x01000193); + return h >>> 0; +} + +/** Turn a generator into an ordinary question for one seed. */ +export function instantiate(gen: QuestionGenerator, seed: number): Question { + const body = gen.generate(mulberry32((seed ^ hashId(gen.id)) >>> 0)); + return { id: gen.id, lesson: gen.lesson, ...(gen.section ? { section: gen.section } : {}), ...body }; +} + +/** A whole number from lo to hi, both included. */ +export const randomInt = (random: () => number, lo: number, hi: number) => lo + Math.floor(random() * (hi - lo + 1)); + +/** + * Options a to d from the right answer and candidate wrong ones: drops repeats and any wrong + * option equal to the right one, keeps the first three left, and puts the right answer at a + * random position. + */ +export function buildOptions(right: string, wrong: string[], random: () => number): Pick { + const picked = [...new Set(wrong.filter((w) => w !== right))].slice(0, 3); + const at = Math.floor(random() * (picked.length + 1)); + const texts = [...picked.slice(0, at), right, ...picked.slice(at)]; + const ids = ["a", "b", "c", "d"]; + return { options: texts.map((text, i) => ({ id: ids[i], text })), correctOptionId: ids[at] }; +} diff --git a/src/pages/ExamPage.tsx b/src/pages/ExamPage.tsx index db97c43..a2da26d 100644 --- a/src/pages/ExamPage.tsx +++ b/src/pages/ExamPage.tsx @@ -2,8 +2,8 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react"; import { Link, Navigate, useParams } from "react-router-dom"; import { SiteHeader, SiteFooter } from "@/components/layout/SiteChrome"; import { getCourse } from "@/content/registry"; -import { loadBank } from "@/content/questionBanks"; -import type { Question } from "@/lib/questions"; +import { loadBank, loadGenerators } from "@/content/questionBanks"; +import { instantiate, type Question, type QuestionGenerator } from "@/lib/questions"; import { recordAnswers } from "@/lib/review"; import { buildExam, @@ -31,6 +31,7 @@ export default function ExamPage() { const { courseSlug } = useParams<{ courseSlug: string }>(); const course = courseSlug ? getCourse(courseSlug) : undefined; const [bank, setBank] = useState(null); + const [generators, setGenerators] = useState([]); const [phase, setPhase] = useState({ name: "intro" }); const [conditions, setConditions] = useState(false); const [attempts, setAttempts] = useState(() => (courseSlug ? readAttempts(courseSlug) : [])); @@ -41,7 +42,10 @@ export default function ExamPage() { useEffect(() => { let live = true; - if (courseSlug) loadBank(courseSlug).then((b) => live && setBank(b)); + if (courseSlug) { + loadBank(courseSlug).then((b) => live && setBank(b)); + loadGenerators(courseSlug).then((g) => live && setGenerators(g)); + } return () => { live = false; }; @@ -69,7 +73,10 @@ export default function ExamPage() { const start = () => { if (!bank) return; const seed = Math.floor(Math.random() * 2 ** 31); - setPhase({ name: "running", exam: buildExam(course, bank, seed), started: Date.now() }); + // Generated questions get fresh numbers from this attempt's seed. + const ids = new Set(generators.map((g) => g.id)); + const fresh = [...bank.filter((q) => !ids.has(q.id)), ...generators.map((g) => instantiate(g, seed))]; + setPhase({ name: "running", exam: buildExam(course, fresh, seed), started: Date.now() }); }; return ( diff --git a/src/test/exam-page.test.tsx b/src/test/exam-page.test.tsx index 22ba30a..cb705e8 100644 --- a/src/test/exam-page.test.tsx +++ b/src/test/exam-page.test.tsx @@ -3,6 +3,7 @@ import { act, fireEvent, render, screen } from "@testing-library/react"; import { MemoryRouter, Route, Routes } from "react-router-dom"; import ExamPage from "@/pages/ExamPage"; import { questions as networkQuestions } from "@/content/computer-networks/questions"; +import { intToIp, parseCidr } from "@/lib/networks"; function renderExam(slug = "computer-networks") { return render( @@ -15,11 +16,28 @@ function renderExam(slug = "computer-networks") { ); } +// Generated questions (subnets) get fresh numbers each attempt, so work their answers out from the prompt. +function generated(prompt: string): { right: string; wrong: string } | null { + const hosts = /a \/(\d+) subnet/.exec(prompt); + if (hosts) { + const h = 32 - Number(hosts[1]); + return { right: String(2 ** h - 2), wrong: String(2 ** h) }; + } + const addr = /(network|broadcast) address of ([\d.]+\/\d+)\?/.exec(prompt); + if (!addr) return null; + const s = parseCidr(addr[2]); + const [right, wrong] = addr[1] === "network" ? [s.network, s.broadcast] : [s.broadcast, s.network]; + return { right: intToIp(right), wrong: intToIp(wrong) }; +} const correctText = (prompt: string) => { + const g = generated(prompt); + if (g) return g.right; const q = networkQuestions.find((x) => x.prompt === prompt)!; return q.options.find((o) => o.id === q.correctOptionId)!.text; }; const wrongText = (prompt: string) => { + const g = generated(prompt); + if (g) return g.wrong; const q = networkQuestions.find((x) => x.prompt === prompt)!; return q.options.find((o) => o.id !== q.correctOptionId)!.text; }; diff --git a/src/test/generated-questions.test.ts b/src/test/generated-questions.test.ts new file mode 100644 index 0000000..aa6ac46 --- /dev/null +++ b/src/test/generated-questions.test.ts @@ -0,0 +1,101 @@ +import { describe, expect, it } from "vitest"; +import { readFileSync } from "fs"; +import { courses } from "@/content/registry"; +import { instantiate, type Question, type QuestionGenerator } from "@/lib/questions"; +import { parseSections } from "@/lib/lessonPreview"; +import { loadBank } from "@/content/questionBanks"; + +const files = import.meta.glob<{ generators: QuestionGenerator[] }>("@/content/*/generators.ts", { eager: true }); +const byCourse = Object.fromEntries(Object.entries(files).map(([f, m]) => [f.split("/").at(-2)!, m.generators])); +const all = Object.values(byCourse).flat(); +const banks = import.meta.glob<{ questions: Question[] }>("@/content/*/questions.ts", { eager: true }); +const bankIds = new Set(Object.values(banks).flatMap((m) => m.questions.map((q) => q.id))); + +const registry = readFileSync("src/content/registry.ts", "utf8"); +const importOf = Object.fromEntries([...registry.matchAll(/const (\w+) = lesson\(\(\) => import\("@\/content\/([^"]+)"\)\)/g)].map((m) => [m[1], m[2]])); +const fileOf: Record = {}; +for (const m of registry.matchAll(/slug: "([^"]+)"[^}]*?Component: (\w+)/g)) if (importOf[m[2]]) fileOf[`${importOf[m[2]].split("/")[0]}/${m[1]}`] = importOf[m[2]]; + +const SEEDS = Array.from({ length: 500 }, (_, i) => i * 7919 + 1); + +// An independent check of the subnet answers, with 32-bit integer masks instead of the lesson's arithmetic. +const toInt = (ip: string) => ip.split(".").reduce((a, o) => ((a << 8) | Number(o)) >>> 0, 0); +const toIp = (n: number) => [24, 16, 8, 0].map((s) => (n >>> s) & 255).join("."); +const maskOf = (p: number) => (p === 0 ? 0 : (0xffffffff << (32 - p)) >>> 0); + +describe("generated questions", () => { + it("have well-formed, unique ids that don't clash with the fixed banks", () => { + const seen = new Set(); + for (const [course, gens] of Object.entries(byCourse)) { + for (const g of gens) { + expect(g.id).toMatch(new RegExp(`^${course}/[a-z0-9-]+/gen-[a-z0-9-]+$`)); + expect(seen.has(g.id), g.id).toBe(false); + expect(bankIds.has(g.id), g.id).toBe(false); + seen.add(g.id); + } + } + expect(all.length).toBeGreaterThan(0); + }); + + it("point at a real lesson and heading", () => { + for (const [course, gens] of Object.entries(byCourse)) { + const c = courses.find((x) => x.slug === course)!; + for (const g of gens) { + expect(c.modules.some((m) => m.lessons.some((l) => l.slug === g.lesson)), g.id).toBe(true); + if (g.section) { + const file = fileOf[`${course}/${g.lesson}`]; + const ids = parseSections(readFileSync(`src/content/${file}`, "utf8")).map((s) => s.id); + expect(ids, g.id).toContain(g.section); + } + } + } + }); + + it("always give four distinct options with exactly one right answer", () => { + for (const g of all) { + for (const seed of SEEDS) { + const q = instantiate(g, seed); + const texts = q.options.map((o) => o.text); + expect(new Set(texts).size, `${g.id} seed ${seed}: ${texts}`).toBe(4); + expect(q.options.filter((o) => o.id === q.correctOptionId)).toHaveLength(1); + expect(q.prompt.trim() && q.explanation.trim()).toBeTruthy(); + } + } + }); + + it("are the same for the same seed and change between seeds", () => { + for (const g of all) { + expect(instantiate(g, 42)).toEqual(instantiate(g, 42)); + expect(new Set(SEEDS.slice(0, 50).map((s) => instantiate(g, s).prompt)).size, g.id).toBeGreaterThan(10); + } + }); + + it("place the right answer in every position, not always the same one", () => { + for (const g of all) expect(new Set(SEEDS.map((s) => instantiate(g, s).correctOptionId)).size, g.id).toBe(4); + }); + + it("compute subnet answers that match an independent bit-mask calculation", () => { + const gen = (name: string) => byCourse["computer-networks"].find((g) => g.id.endsWith(name))!; + for (const seed of SEEDS) { + const answer = (q: Question) => q.options.find((o) => o.id === q.correctOptionId)!.text; + const hosts = instantiate(gen("gen-usable-hosts"), seed); + const p = Number(/\/(\d+)/.exec(hosts.prompt)![1]); + expect(Number(answer(hosts))).toBe(2 ** (32 - p) - 2); + + for (const [name, pick] of [["gen-network-address", (ip: number, m: number) => ip & m], ["gen-broadcast-address", (ip: number, m: number) => ip | ~m]] as const) { + const q = instantiate(gen(name), seed); + const [, ip, prefix] = /of ([\d.]+)\/(\d+)\?/.exec(q.prompt)!; + expect(answer(q), `${name} ${ip}/${prefix}`).toBe(toIp(pick(toInt(ip), maskOf(Number(prefix))) >>> 0)); + expect(ip, "the address itself isn't the answer").not.toBe(answer(q)); + } + } + }); + + it("are added to a course's bank by loadBank, with numbers from the seed", async () => { + const a = await loadBank("computer-networks", 1); + const b = await loadBank("computer-networks", 2); + const id = byCourse["computer-networks"][1].id; + expect(a.filter((q) => q.id === id)).toHaveLength(1); + expect(a.find((q) => q.id === id)!.prompt).not.toBe(b.find((q) => q.id === id)!.prompt); + }); +});