Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion docs/autopilot.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down
6 changes: 4 additions & 2 deletions docs/exams.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<course>/<quiz-slug>/q<n>` (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/<course>/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
Expand Down
92 changes: 92 additions & 0 deletions src/content/computer-networks/generators.ts
Original file line number Diff line number Diff line change
@@ -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,
};
},
},
];
25 changes: 18 additions & 7 deletions src/content/questionBanks.ts
Original file line number Diff line number Diff line change
@@ -1,16 +1,27 @@
/* Loads a course's question bank (src/content/<course>/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/<course>/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<Question[]> {
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<QuestionGenerator[]> {
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<Question[]> {
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))];
}
58 changes: 58 additions & 0 deletions src/lib/questions.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<Question, "prompt" | "options" | "correctOptionId" | "explanation" | "difficulty">;

/**
* 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/<course>/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<Question, "options" | "correctOptionId"> {
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] };
}
15 changes: 11 additions & 4 deletions src/pages/ExamPage.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -31,6 +31,7 @@ export default function ExamPage() {
const { courseSlug } = useParams<{ courseSlug: string }>();
const course = courseSlug ? getCourse(courseSlug) : undefined;
const [bank, setBank] = useState<Question[] | null>(null);
const [generators, setGenerators] = useState<QuestionGenerator[]>([]);
const [phase, setPhase] = useState<Phase>({ name: "intro" });
const [conditions, setConditions] = useState(false);
const [attempts, setAttempts] = useState<ExamAttempt[]>(() => (courseSlug ? readAttempts(courseSlug) : []));
Expand All @@ -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;
};
Expand Down Expand Up @@ -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 (
Expand Down
18 changes: 18 additions & 0 deletions src/test/exam-page.test.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand All @@ -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;
};
Expand Down
Loading
Loading