@datajaddah/course 0.0.2

package/lib/repo-contract.js

@@ -0,0 +1,1291 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { renderSlideMarkdown } from "./slide-markdown.js";
+
+const ORDERED_NAME_PATTERN = /^(?<order>\d+)-(?<slug>[a-z0-9][a-z0-9-]*)$/;
+const FRONTMATTER_KEY_PATTERN = /^(?<key>[A-Za-z_][A-Za-z0-9_]*):(?:[ \t]*(?<value>.*))?$/;
+const CHOICE_METADATA_PATTERN = /^(?<key>[a-z_][a-z0-9_]*):(?:[ \t]*(?<value>.*))?$/;
+const FRONTMATTER_LIST_ITEM_PATTERN = /^(?:[ \t]*)-\s+(?<value>.*)$/;
+const MARKDOWN_HEADING_PATTERN = /^(#{2,6})\s+(.+?)\s*$/;
+const PLACEHOLDER_VIDEO_URL_HOSTS = new Set([
+  "example.com",
+  "www.example.com",
+  "example.org",
+  "www.example.org",
+  "example.net",
+  "www.example.net",
+]);
+const PLACEHOLDER_VIDEO_URL_PATTERNS = [/replace[-_]?me/i, /placeholder/i];
+
+const CHOICE_START = "@choice";
+const CHOICE_END = "@endchoice";
+const SCRIPT_START = "@script";
+const SCRIPT_END = "@endscript";
+const SUPPORTED_SPREADSHEET_ENGINES = new Set(["univer"]);
+const SPREADSHEET_CHECK_TYPES = new Set([
+  "value_equals",
+  "text_equals",
+  "has_formula",
+  "formula_equals",
+  "one_of",
+  "value_with_tolerance",
+]);
+
+export class RepoContractError extends Error {
+  constructor(filePath, message, line = 1) {
+    super(`${filePath}:${line}: ${message}`);
+    this.name = "RepoContractError";
+    this.path = filePath;
+    this.line = line;
+    this.message = message;
+  }
+}
+
+function toPosixPath(filePath) {
+  return filePath.split(path.sep).join("/");
+}
+
+function relativePosix(rootPath, filePath) {
+  return toPosixPath(path.relative(rootPath, filePath));
+}
+
+function slugToTitle(slug) {
+  return slug
+    .split("-")
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(" ");
+}
+
+function normalizeInlineText(value) {
+  return String(value || "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function plainTextFromMarkdown(value) {
+  return normalizeInlineText(
+    String(value || "")
+      .replace(/`([^`]+)`/g, "$1")
+      .replace(/!\[([^\]]*)\]\([^)]+\)/g, "$1")
+      .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+      .replace(/\*\*([^*]+)\*\*/g, "$1")
+      .replace(/(^|[^*])\*([^*]+)\*(?!\*)/g, "$1$2")
+      .replace(/_{1,2}([^_]+)_{1,2}/g, "$1")
+      .replace(/<\/?[^>]+>/g, " ")
+  );
+}
+
+function orderedPathParts(filePath) {
+  const baseName = path.basename(filePath, path.extname(filePath));
+  const match = ORDERED_NAME_PATTERN.exec(baseName);
+  if (!match?.groups) {
+    throw new RepoContractError(
+      toPosixPath(filePath),
+      "Expected an ordered name like `01-intro` or `01-question.md`"
+    );
+  }
+  return {
+    order: Number(match.groups.order),
+    slug: match.groups.slug,
+  };
+}
+
+function ensureString(value, filePath, line, label, { required = false } = {}) {
+  if (value == null) {
+    if (required) {
+      throw new RepoContractError(toPosixPath(filePath), `${label} is required`, line);
+    }
+    return null;
+  }
+  if (typeof value !== "string") {
+    throw new RepoContractError(toPosixPath(filePath), `${label} must be a string`, line);
+  }
+  const normalized = value.trim();
+  if (required && !normalized) {
+    throw new RepoContractError(toPosixPath(filePath), `${label} is required`, line);
+  }
+  return normalized || null;
+}
+
+function ensureBoolean(value, filePath, line, label, { defaultValue = false } = {}) {
+  if (value == null) {
+    return defaultValue;
+  }
+  if (typeof value !== "boolean") {
+    throw new RepoContractError(toPosixPath(filePath), `${label} must be a boolean`, line);
+  }
+  return value;
+}
+
+function ensureInteger(value, filePath, line, label) {
+  if (value == null) {
+    return null;
+  }
+  if (!Number.isInteger(value)) {
+    throw new RepoContractError(toPosixPath(filePath), `${label} must be an integer`, line);
+  }
+  return value;
+}
+
+function ensureVideoUrl(value, filePath, line) {
+  const normalized = ensureString(value, filePath, line, "video_url", { required: true });
+  let parsedUrl;
+
+  try {
+    parsedUrl = new URL(normalized);
+  } catch {
+    throw new RepoContractError(
+      toPosixPath(filePath),
+      "video_url must be an absolute http(s) URL",
+      line
+    );
+  }
+
+  if (!["http:", "https:"].includes(parsedUrl.protocol)) {
+    throw new RepoContractError(
+      toPosixPath(filePath),
+      "video_url must use `http` or `https`",
+      line
+    );
+  }
+
+  if (
+    PLACEHOLDER_VIDEO_URL_HOSTS.has(parsedUrl.hostname.toLowerCase()) ||
+    PLACEHOLDER_VIDEO_URL_PATTERNS.some((pattern) => pattern.test(normalized))
+  ) {
+    throw new RepoContractError(
+      toPosixPath(filePath),
+      "video_url must be a real external video URL, not a placeholder",
+      line
+    );
+  }
+
+  return normalized;
+}
+
+function parseExplicitBoolean(value, filePath, line, label) {
+  if (typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "string") {
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "true") {
+      return true;
+    }
+    if (normalized === "false") {
+      return false;
+    }
+  }
+  throw new RepoContractError(toPosixPath(filePath), `${label} must be \`true\` or \`false\``, line);
+}
+
+function parseInlineArray(value) {
+  const inner = value.slice(1, -1).trim();
+  if (!inner) {
+    return [];
+  }
+
+  const items = [];
+  let current = "";
+  let quote = null;
+
+  for (let index = 0; index < inner.length; index += 1) {
+    const char = inner[index];
+    if (quote) {
+      current += char;
+      if (char === quote && inner[index - 1] !== "\\") {
+        quote = null;
+      }
+      continue;
+    }
+    if (char === "'" || char === '"') {
+      quote = char;
+      current += char;
+      continue;
+    }
+    if (char === ",") {
+      items.push(parseScalar(current.trim()));
+      current = "";
+      continue;
+    }
+    current += char;
+  }
+
+  if (current.trim()) {
+    items.push(parseScalar(current.trim()));
+  }
+
+  return items;
+}
+
+function parseScalar(rawValue) {
+  const value = rawValue.trim();
+  if (!value) {
+    return "";
+  }
+  if (value === "true") {
+    return true;
+  }
+  if (value === "false") {
+    return false;
+  }
+  if (/^-?\d+$/.test(value)) {
+    return Number(value);
+  }
+  if (value.startsWith("[") && value.endsWith("]")) {
+    return parseInlineArray(value);
+  }
+  if (value.startsWith('"') && value.endsWith('"')) {
+    try {
+      return JSON.parse(value);
+    } catch {
+      return value.slice(1, -1);
+    }
+  }
+  if (value.startsWith("'") && value.endsWith("'")) {
+    return value.slice(1, -1).replace(/''/g, "'");
+  }
+  return value;
+}
+
+function parseFrontmatter(frontmatterLines, filePath) {
+  const frontmatter = {};
+  let index = 0;
+
+  while (index < frontmatterLines.length) {
+    const rawLine = frontmatterLines[index];
+    const lineNumber = index + 2;
+
+    if (!rawLine.trim()) {
+      index += 1;
+      continue;
+    }
+
+    if (/^[ \t]/.test(rawLine)) {
+      throw new RepoContractError(
+        toPosixPath(filePath),
+        "Frontmatter entries must start at column 1",
+        lineNumber
+      );
+    }
+
+    const match = FRONTMATTER_KEY_PATTERN.exec(rawLine);
+    if (!match?.groups) {
+      throw new RepoContractError(
+        toPosixPath(filePath),
+        "Invalid frontmatter entry; expected `key: value`",
+        lineNumber
+      );
+    }
+
+    const key = match.groups.key;
+    if (Object.prototype.hasOwnProperty.call(frontmatter, key)) {
+      throw new RepoContractError(
+        toPosixPath(filePath),
+        `Duplicate frontmatter field \`${key}\``,
+        lineNumber
+      );
+    }
+
+    const rawValue = (match.groups.value ?? "").trimEnd();
+    if (rawValue === "|") {
+      const blockLines = [];
+      index += 1;
+      while (index < frontmatterLines.length) {
+        const continuation = frontmatterLines[index];
+        if (continuation.startsWith("  ")) {
+          blockLines.push(continuation.slice(2));
+          index += 1;
+          continue;
+        }
+        if (continuation.startsWith("\t")) {
+          blockLines.push(continuation.slice(1));
+          index += 1;
+          continue;
+        }
+        break;
+      }
+      frontmatter[key] = blockLines.join("\n").trim();
+      continue;
+    }
+
+    if (!rawValue) {
+      const listItems = [];
+      let nextIndex = index + 1;
+      while (nextIndex < frontmatterLines.length) {
+        const continuation = frontmatterLines[nextIndex];
+        const listMatch = FRONTMATTER_LIST_ITEM_PATTERN.exec(continuation);
+        if (listMatch?.groups) {
+          listItems.push(parseScalar(listMatch.groups.value));
+          nextIndex += 1;
+          continue;
+        }
+        break;
+      }
+      if (listItems.length > 0) {
+        frontmatter[key] = listItems;
+        index = nextIndex;
+        continue;
+      }
+      frontmatter[key] = null;
+      index += 1;
+      continue;
+    }
+
+    frontmatter[key] = parseScalar(rawValue);
+    index += 1;
+  }
+
+  return frontmatter;
+}
+
+function readMarkdownDocument(filePath) {
+  let content;
+  try {
+    content = readFileSync(filePath, "utf8");
+  } catch (error) {
+    if (error instanceof TypeError) {
+      throw new RepoContractError(toPosixPath(filePath), "File must be valid UTF-8", 1);
+    }
+    throw error;
+  }
+
+  const normalized = content.replace(/\r\n/g, "\n");
+  if (normalized.startsWith("---\n")) {
+    const lines = normalized.split("\n");
+    let endIndex = null;
+    for (let index = 1; index < lines.length; index += 1) {
+      if (lines[index].trim() === "---") {
+        endIndex = index;
+        break;
+      }
+    }
+
+    if (endIndex == null) {
+      throw new RepoContractError(toPosixPath(filePath), "Frontmatter is missing a closing `---`", 1);
+    }
+
+    const frontmatterLines = lines.slice(1, endIndex);
+    const frontmatter = parseFrontmatter(frontmatterLines, filePath);
+    return {
+      path: filePath,
+      frontmatter,
+      body: lines.slice(endIndex + 1).join("\n"),
+      bodyStartLine: endIndex + 2,
+    };
+  }
+
+  return {
+    path: filePath,
+    frontmatter: {},
+    body: normalized,
+    bodyStartLine: 1,
+  };
+}
+
+function readJsonDocument(filePath, label) {
+  let content;
+  try {
+    content = readFileSync(filePath, "utf8");
+  } catch (error) {
+    if (error instanceof TypeError) {
+      throw new RepoContractError(toPosixPath(filePath), "File must be valid UTF-8", 1);
+    }
+    throw error;
+  }
+
+  try {
+    return JSON.parse(content);
+  } catch (error) {
+    const positionMatch =
+      error instanceof SyntaxError ? /position\s+(?<position>\d+)/i.exec(error.message) : null;
+    const position = positionMatch?.groups?.position ? Number(positionMatch.groups.position) : null;
+    const line =
+      Number.isInteger(position) && position != null
+        ? content.slice(0, position).split(/\r?\n/).length
+        : 1;
+    throw new RepoContractError(
+      toPosixPath(filePath),
+      `Invalid ${label} JSON`,
+      line
+    );
+  }
+}
+
+function orderedDirectories(dirPath) {
+  const items = readdirSync(dirPath, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => path.join(dirPath, entry.name))
+    .sort((left, right) => orderedPathParts(left).order - orderedPathParts(right).order);
+
+  items.forEach((itemPath, index) => {
+    const { order } = orderedPathParts(itemPath);
+    if (order !== index + 1) {
+      throw new RepoContractError(
+        toPosixPath(itemPath),
+        `Ordering must be contiguous; expected \`${String(index + 1).padStart(2, "0")}-...\` here`
+      );
+    }
+  });
+
+  return items;
+}
+
+function orderedMarkdownFiles(dirPath) {
+  const items = readdirSync(dirPath, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && path.extname(entry.name) === ".md")
+    .map((entry) => path.join(dirPath, entry.name))
+    .sort((left, right) => orderedPathParts(left).order - orderedPathParts(right).order);
+
+  items.forEach((itemPath, index) => {
+    const { order } = orderedPathParts(itemPath);
+    if (order !== index + 1) {
+      throw new RepoContractError(
+        toPosixPath(itemPath),
+        `Ordering must be contiguous; expected \`${String(index + 1).padStart(2, "0")}-...\` here`
+      );
+    }
+  });
+
+  return items;
+}
+
+function validateRequiredDirectory(dirPath, label) {
+  if (!statExists(dirPath, "directory")) {
+    throw new RepoContractError(toPosixPath(dirPath), `Missing required ${label} directory`);
+  }
+  return dirPath;
+}
+
+function validateRequiredFile(filePath, label) {
+  if (!statExists(filePath, "file")) {
+    throw new RepoContractError(toPosixPath(filePath), `Missing required ${label} file`);
+  }
+  return filePath;
+}
+
+function statExists(targetPath, expectedType) {
+  try {
+    const stats = statSync(targetPath);
+    return expectedType === "directory" ? stats.isDirectory() : stats.isFile();
+  } catch {
+    return false;
+  }
+}
+
+function extractNamedBlock(document, startMarker, endMarker) {
+  const lines = document.body.split("\n");
+  const contentLines = [];
+  const blockLines = [];
+  let inBlock = false;
+  let seenBlock = false;
+
+  lines.forEach((line, index) => {
+    const stripped = line.trim();
+    if (stripped === startMarker) {
+      if (inBlock || seenBlock) {
+        throw new RepoContractError(
+          toPosixPath(document.path),
+          `Only one \`${startMarker}\` block is allowed`,
+          document.bodyStartLine + index
+        );
+      }
+      inBlock = true;
+      seenBlock = true;
+      return;
+    }
+
+    if (stripped === endMarker) {
+      if (!inBlock) {
+        throw new RepoContractError(
+          toPosixPath(document.path),
+          `Found \`${endMarker}\` without a matching \`${startMarker}\``,
+          document.bodyStartLine + index
+        );
+      }
+      inBlock = false;
+      return;
+    }
+
+    if (inBlock) {
+      blockLines.push(line);
+    } else {
+      contentLines.push(line);
+    }
+  });
+
+  if (inBlock) {
+    throw new RepoContractError(
+      toPosixPath(document.path),
+      `Missing closing \`${endMarker}\` for \`${startMarker}\` block`,
+      document.bodyStartLine + lines.length
+    );
+  }
+
+  return {
+    content: contentLines.join("\n").trim(),
+    block: blockLines.join("\n").trim(),
+  };
+}
+
+function parseChoiceMetadata(document, metadataLines, choiceStartLine) {
+  const metadata = {};
+  const allowedKeys = new Set(["title", "correct", "feedback"]);
+  let index = 0;
+
+  while (index < metadataLines.length) {
+    const rawLine = metadataLines[index];
+    const lineNumber = choiceStartLine + 1 + index;
+
+    if (/^[ \t]/.test(rawLine)) {
+      throw new RepoContractError(
+        toPosixPath(document.path),
+        "Choice metadata continuation lines must follow a `key: |` entry",
+        lineNumber
+      );
+    }
+
+    const match = CHOICE_METADATA_PATTERN.exec(rawLine);
+    if (!match?.groups) {
+      throw new RepoContractError(
+        toPosixPath(document.path),
+        "Choice metadata lines must use `key: value` syntax",
+        lineNumber
+      );
+    }
+
+    const key = match.groups.key;
+    if (!allowedKeys.has(key)) {
+      throw new RepoContractError(
+        toPosixPath(document.path),
+        `Unknown choice metadata field \`${key}\``,
+        lineNumber
+      );
+    }
+    if (Object.prototype.hasOwnProperty.call(metadata, key)) {
+      throw new RepoContractError(
+        toPosixPath(document.path),
+        `Duplicate choice metadata field \`${key}\``,
+        lineNumber
+      );
+    }
+
+    const value = (match.groups.value ?? "").trimEnd();
+    if (value === "|") {
+      const blockLines = [];
+      index += 1;
+      while (index < metadataLines.length) {
+        const continuation = metadataLines[index];
+        if (continuation.startsWith("  ")) {
+          blockLines.push(continuation.slice(2));
+          index += 1;
+          continue;
+        }
+        if (continuation.startsWith("\t")) {
+          blockLines.push(continuation.slice(1));
+          index += 1;
+          continue;
+        }
+        break;
+      }
+      metadata[key] = blockLines.join("\n").trim();
+      continue;
+    }
+
+    metadata[key] = value;
+    index += 1;
+  }
+
+  return metadata;
+}
+
+function parseChoiceBlocks(document) {
+  const lines = document.body.split("\n");
+  const promptLines = [];
+  const choices = [];
+  let index = 0;
+  let foundChoice = false;
+
+  while (index < lines.length) {
+    const stripped = lines[index].trim();
+    if (stripped !== CHOICE_START) {
+      if (foundChoice) {
+        if (!stripped) {
+          index += 1;
+          continue;
+        }
+        throw new RepoContractError(
+          toPosixPath(document.path),
+          "All content after the first `@choice` must stay inside choice blocks",
+          document.bodyStartLine + index
+        );
+      }
+      promptLines.push(lines[index]);
+      index += 1;
+      continue;
+    }
+
+    foundChoice = true;
+    const choiceStartLine = document.bodyStartLine + index;
+    index += 1;
+
+    const metadataLines = [];
+    while (index < lines.length && lines[index].trim()) {
+      if (lines[index].trim() === CHOICE_END) {
+        break;
+      }
+      metadataLines.push(lines[index]);
+      index += 1;
+    }
+
+    if (index < lines.length && lines[index].trim() === CHOICE_END) {
+      throw new RepoContractError(
+        toPosixPath(document.path),
+        "Choice metadata must be followed by a blank line before the choice body",
+        document.bodyStartLine + index
+      );
+    }
+
+    if (metadataLines.length === 0) {
+      throw new RepoContractError(
+        toPosixPath(document.path),
+        "Each `@choice` block must include metadata lines before the blank line",
+        choiceStartLine
+      );
+    }
+
+    const metadata = parseChoiceMetadata(document, metadataLines, choiceStartLine);
+
+    if (index < lines.length && !lines[index].trim()) {
+      index += 1;
+    }
+
+    const bodyLines = [];
+    while (index < lines.length) {
+      const marker = lines[index].trim();
+      if (marker === CHOICE_START) {
+        throw new RepoContractError(
+          toPosixPath(document.path),
+          "Nested `@choice` blocks are not allowed",
+          document.bodyStartLine + index
+        );
+      }
+      if (marker === CHOICE_END) {
+        break;
+      }
+      bodyLines.push(lines[index]);
+      index += 1;
+    }
+
+    if (index >= lines.length || lines[index].trim() !== CHOICE_END) {
+      throw new RepoContractError(
+        toPosixPath(document.path),
+        "Missing `@endchoice` for choice block",
+        choiceStartLine
+      );
+    }
+
+    const bodyMarkdown = bodyLines.join("\n").trim();
+    const title = ensureString(metadata.title, document.path, choiceStartLine, "choice.title");
+    if (!bodyMarkdown && !title) {
+      throw new RepoContractError(
+        toPosixPath(document.path),
+        "Choice body cannot be empty unless `title` is provided",
+        choiceStartLine
+      );
+    }
+
+    if (!Object.prototype.hasOwnProperty.call(metadata, "correct")) {
+      throw new RepoContractError(
+        toPosixPath(document.path),
+        "choice.correct is required",
+        choiceStartLine
+      );
+    }
+
+    choices.push({
+      title,
+      correct: parseExplicitBoolean(metadata.correct, document.path, choiceStartLine, "choice.correct"),
+      feedback:
+        typeof metadata.feedback === "string" && metadata.feedback.trim()
+          ? metadata.feedback.trim()
+          : null,
+      bodyMarkdown: bodyMarkdown || title || "",
+      line: choiceStartLine,
+    });
+
+    index += 1;
+  }
+
+  return {
+    promptMarkdown: promptLines.join("\n").trim(),
+    choices,
+  };
+}
+
+const SUPPORTED_EXERCISE_LANGUAGES = new Set(["python", "r"]);
+const LANGUAGE_EXTENSIONS = {
+  python: new Set(["py"]),
+  r: new Set(["r"]),
+};
+
+function parseSlideFile(rootPath, filePath) {
+  const document = readMarkdownDocument(filePath);
+  const { slug } = orderedPathParts(filePath);
+  const title = ensureString(document.frontmatter.title, filePath, 1, "title") || slugToTitle(slug);
+  const { content, block } = extractNamedBlock(document, SCRIPT_START, SCRIPT_END);
+  const { html } = renderSlideMarkdown(content, {
+    onError(message, line) {
+      throw new RepoContractError(toPosixPath(filePath), message, document.bodyStartLine + line - 1);
+    },
+  });
+  return {
+    repoKey: relativePosix(rootPath, filePath).replace(/\.md$/, ""),
+    repoPath: relativePosix(rootPath, filePath),
+    title,
+    contentMarkdown: content,
+    contentHtml: html,
+    script: block,
+  };
+}
+
+function parseVideoFile(rootPath, filePath, titleFallback) {
+  const document = readMarkdownDocument(filePath);
+  const title = ensureString(document.frontmatter.title, filePath, 1, "title") || titleFallback;
+  const videoUrl = ensureVideoUrl(document.frontmatter.video_url, filePath, 1);
+  return {
+    repoKey: relativePosix(rootPath, filePath).replace(/\.md$/, ""),
+    repoPath: relativePosix(rootPath, filePath),
+    title,
+    videoUrl,
+    notesMarkdown: document.body.trim(),
+  };
+}
+
+function parseQuizQuestion(rootPath, filePath, warnings) {
+  const document = readMarkdownDocument(filePath);
+  const { slug } = orderedPathParts(filePath);
+  const title = ensureString(document.frontmatter.title, filePath, 1, "title") || slugToTitle(slug);
+  const { promptMarkdown, choices } = parseChoiceBlocks(document);
+
+  if (choices.length === 0) {
+    throw new RepoContractError(
+      toPosixPath(filePath),
+      "Quiz question must include at least one `@choice` block"
+    );
+  }
+
+  const correctCount = choices.filter((choice) => choice.correct).length;
+  if (correctCount === 0) {
+    throw new RepoContractError(
+      toPosixPath(filePath),
+      "Quiz question must include at least one correct choice"
+    );
+  }
+
+  const correctFeedback = document.frontmatter.correct_feedback;
+  if (correctFeedback != null && typeof correctFeedback !== "string") {
+    throw new RepoContractError(toPosixPath(filePath), "correct_feedback must be a string", 1);
+  }
+
+  const repoPath = relativePosix(rootPath, filePath);
+  for (const choice of choices) {
+    if (!choice.title || !choice.bodyMarkdown) {
+      continue;
+    }
+
+    const normalizedTitle = normalizeInlineText(choice.title);
+    const normalizedBody = plainTextFromMarkdown(choice.bodyMarkdown);
+    if (normalizedTitle && normalizedBody && normalizedTitle !== normalizedBody) {
+      warnings.push(
+        `Choice title differs from body in \`${repoPath}:${choice.line}\`; platform import uses the choice body as the visible answer text, so put the learner-facing answer in the choice body and use feedback for explanations.`
+      );
+    }
+  }
+
+  return {
+    repoKey: repoPath.replace(/\.md$/, ""),
+    repoPath,
+    title,
+    questionMarkdown: promptMarkdown || title,
+    correctFeedback:
+      typeof correctFeedback === "string" && correctFeedback.trim()
+        ? correctFeedback.trim()
+        : null,
+    randomizeChoices: ensureBoolean(
+      document.frontmatter.randomize_choices,
+      filePath,
+      1,
+      "randomize_choices"
+    ),
+    isMultipleChoice: correctCount > 1,
+    choices,
+  };
+}
+
+function parseExerciseSections(document) {
+  const lines = document.body.split(/\r?\n/);
+  const sectionOrder = [];
+  const sectionContent = new Map();
+  let currentSection = null;
+  let currentLines = [];
+
+  const finalizeCurrent = () => {
+    if (currentSection == null) {
+      return;
+    }
+    const markdown = currentLines.join("\n").trim();
+    sectionContent.set(currentSection, markdown || null);
+    currentSection = null;
+    currentLines = [];
+  };
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const rawLine = lines[index];
+    const stripped = rawLine.trim();
+    const headingMatch = MARKDOWN_HEADING_PATTERN.exec(rawLine);
+    const headingName = headingMatch?.[2]?.trim().toLowerCase();
+
+    if (headingName === "context" || headingName === "instructions") {
+      if (sectionContent.has(headingName) || currentSection === headingName) {
+        throw new RepoContractError(
+          toPosixPath(document.path),
+          `Exercise body cannot repeat the \`## ${headingName.charAt(0).toUpperCase()}${headingName.slice(1)}\` section`,
+          document.bodyStartLine + index
+        );
+      }
+      finalizeCurrent();
+      currentSection = headingName;
+      sectionOrder.push(headingName);
+      continue;
+    }
+
+    if (currentSection == null) {
+      if (stripped) {
+        throw new RepoContractError(
+          toPosixPath(document.path),
+          "Exercise body must use `## Context` followed by `## Instructions` sections",
+          document.bodyStartLine + index
+        );
+      }
+      continue;
+    }
+
+    currentLines.push(rawLine);
+  }
+
+  finalizeCurrent();
+
+  if (sectionOrder.length !== 2 || sectionOrder[0] !== "context" || sectionOrder[1] !== "instructions") {
+    throw new RepoContractError(
+      toPosixPath(document.path),
+      "Exercise body must use `## Context` followed by `## Instructions` sections",
+      document.bodyStartLine
+    );
+  }
+
+  return {
+    contextMarkdown: sectionContent.get("context") ?? null,
+    instructionsMarkdown: sectionContent.get("instructions") ?? null,
+  };
+}
+
+function parseExerciseDirectory(rootPath, dirPath, titleFallback) {
+  const exercisePath = validateRequiredFile(path.join(dirPath, "exercise.md"), "exercise");
+  const document = readMarkdownDocument(exercisePath);
+  const title = ensureString(document.frontmatter.title, exercisePath, 1, "title") || titleFallback;
+  const language = ensureString(document.frontmatter.language, exercisePath, 1, "language", {
+    required: true,
+  });
+  const normalizedLanguage = language.toLowerCase();
+  if (!SUPPORTED_EXERCISE_LANGUAGES.has(normalizedLanguage)) {
+    throw new RepoContractError(
+      toPosixPath(exercisePath),
+      "language must be one of `python` or `r`",
+      1
+    );
+  }
+  const { contextMarkdown, instructionsMarkdown } = parseExerciseSections(document);
+
+  const starterCandidates = readdirSync(dirPath, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && path.parse(entry.name).name === "starter")
+    .map((entry) => path.join(dirPath, entry.name))
+    .sort();
+  const solutionCandidates = readdirSync(dirPath, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && path.parse(entry.name).name === "solution")
+    .map((entry) => path.join(dirPath, entry.name))
+    .sort();
+
+  if (starterCandidates.length !== 1) {
+    throw new RepoContractError(
+      toPosixPath(dirPath),
+      "Exercise directory must contain exactly one `starter.*` file"
+    );
+  }
+  if (solutionCandidates.length !== 1) {
+    throw new RepoContractError(
+      toPosixPath(dirPath),
+      "Exercise directory must contain exactly one `solution.*` file"
+    );
+  }
+
+  const starterPath = starterCandidates[0];
+  const solutionPath = solutionCandidates[0];
+  const starterExtension = path.extname(starterPath).slice(1).toLowerCase();
+  const solutionExtension = path.extname(solutionPath).slice(1).toLowerCase();
+  if (starterExtension !== solutionExtension) {
+    throw new RepoContractError(
+      toPosixPath(dirPath),
+      "starter and solution files must use the same extension"
+    );
+  }
+
+  const supportedExtensions = LANGUAGE_EXTENSIONS[normalizedLanguage];
+  if (!supportedExtensions.has(starterExtension)) {
+    throw new RepoContractError(
+      toPosixPath(starterPath),
+      `starter file extension \`.${starterExtension}\` does not match language \`${normalizedLanguage}\``
+    );
+  }
+
+  return {
+    repoKey: relativePosix(rootPath, exercisePath).replace(/\.md$/, ""),
+    repoPath: relativePosix(rootPath, dirPath),
+    title,
+    language: normalizedLanguage,
+    bodyMarkdown: document.body.trim(),
+    contextMarkdown,
+    instructionsMarkdown,
+    starterPath: relativePosix(rootPath, starterPath),
+    solutionPath: relativePosix(rootPath, solutionPath),
+  };
+}
+
+function parseSpreadsheetChecks(checksPath) {
+  const rawChecks = readJsonDocument(checksPath, "spreadsheet checks");
+  if (!Array.isArray(rawChecks)) {
+    throw new RepoContractError(
+      toPosixPath(checksPath),
+      "checks.json must contain a JSON array",
+      1
+    );
+  }
+
+  return rawChecks.map((rawCheck, index) => {
+    if (!rawCheck || typeof rawCheck !== "object" || Array.isArray(rawCheck)) {
+      throw new RepoContractError(
+        toPosixPath(checksPath),
+        `checks[${index}] must be a JSON object`,
+        1
+      );
+    }
+
+    const id = ensureString(rawCheck.id, checksPath, 1, `checks[${index}].id`, {
+      required: true,
+    });
+    const label = ensureString(rawCheck.label, checksPath, 1, `checks[${index}].label`, {
+      required: true,
+    });
+    const type = ensureString(rawCheck.type, checksPath, 1, `checks[${index}].type`, {
+      required: true,
+    });
+    if (!SPREADSHEET_CHECK_TYPES.has(type)) {
+      throw new RepoContractError(
+        toPosixPath(checksPath),
+        `checks[${index}].type must be one of ${Array.from(SPREADSHEET_CHECK_TYPES)
+          .map((value) => `\`${value}\``)
+          .join(", ")}`,
+        1
+      );
+    }
+
+    const cell = ensureString(rawCheck.cell, checksPath, 1, `checks[${index}].cell`, {
+      required: true,
+    });
+    const sheetName = ensureString(
+      rawCheck.sheet_name,
+      checksPath,
+      1,
+      `checks[${index}].sheet_name`
+    );
+    const formula = ensureString(rawCheck.formula, checksPath, 1, `checks[${index}].formula`);
+    const details = ensureString(rawCheck.details, checksPath, 1, `checks[${index}].details`);
+
+    if (rawCheck.values != null && !Array.isArray(rawCheck.values)) {
+      throw new RepoContractError(
+        toPosixPath(checksPath),
+        `checks[${index}].values must be an array`,
+        1
+      );
+    }
+
+    if (
+      rawCheck.tolerance != null &&
+      (typeof rawCheck.tolerance !== "number" || !Number.isFinite(rawCheck.tolerance))
+    ) {
+      throw new RepoContractError(
+        toPosixPath(checksPath),
+        `checks[${index}].tolerance must be a number`,
+        1
+      );
+    }
+
+    return {
+      id,
+      label,
+      type,
+      sheetName,
+      cell,
+      value: rawCheck.value ?? null,
+      values: rawCheck.values ?? [],
+      formula,
+      tolerance: rawCheck.tolerance ?? null,
+      details,
+    };
+  });
+}
+
+function parseSpreadsheetDirectory(rootPath, dirPath, titleFallback) {
+  const exercisePath = validateRequiredFile(path.join(dirPath, "exercise.md"), "spreadsheet exercise");
+  const workbookPath = validateRequiredFile(path.join(dirPath, "workbook.json"), "spreadsheet workbook");
+  const solutionPath = validateRequiredFile(path.join(dirPath, "solution.json"), "spreadsheet solution");
+  const checksPath = validateRequiredFile(path.join(dirPath, "checks.json"), "spreadsheet checks");
+
+  const document = readMarkdownDocument(exercisePath);
+  const title = ensureString(document.frontmatter.title, exercisePath, 1, "title") || titleFallback;
+  const engine =
+    ensureString(document.frontmatter.engine, exercisePath, 1, "engine") || "univer";
+  const normalizedEngine = engine.toLowerCase();
+  if (!SUPPORTED_SPREADSHEET_ENGINES.has(normalizedEngine)) {
+    throw new RepoContractError(
+      toPosixPath(exercisePath),
+      "engine must be `univer`",
+      1
+    );
+  }
+
+  const { contextMarkdown, instructionsMarkdown } = parseExerciseSections(document);
+  const starterWorkbook = readJsonDocument(workbookPath, "spreadsheet workbook");
+  if (!starterWorkbook || typeof starterWorkbook !== "object" || Array.isArray(starterWorkbook)) {
+    throw new RepoContractError(
+      toPosixPath(workbookPath),
+      "workbook.json must contain a JSON object",
+      1
+    );
+  }
+
+  const solutionWorkbook = readJsonDocument(solutionPath, "spreadsheet solution");
+  if (!solutionWorkbook || typeof solutionWorkbook !== "object" || Array.isArray(solutionWorkbook)) {
+    throw new RepoContractError(
+      toPosixPath(solutionPath),
+      "solution.json must contain a JSON object",
+      1
+    );
+  }
+
+  const checks = parseSpreadsheetChecks(checksPath);
+  const bodyMarkdown = document.body.trim();
+
+  return {
+    repoKey: relativePosix(rootPath, exercisePath).replace(/\.md$/, ""),
+    repoPath: relativePosix(rootPath, dirPath),
+    title,
+    engine: normalizedEngine,
+    bodyMarkdown,
+    contextMarkdown,
+    instructionsMarkdown,
+    starterWorkbook,
+    solutionWorkbook,
+    checks,
+    workbookPath: relativePosix(rootPath, workbookPath),
+    solutionPath: relativePosix(rootPath, solutionPath),
+    checksPath: relativePosix(rootPath, checksPath),
+  };
+}
+
+function parseLessonDirectory(rootPath, dirPath, warnings) {
+  const { slug } = orderedPathParts(dirPath);
+  const lessonPath = validateRequiredFile(path.join(dirPath, "lesson.md"), "lesson");
+  const document = readMarkdownDocument(lessonPath);
+
+  const title = ensureString(document.frontmatter.title, lessonPath, 1, "title") || slugToTitle(slug);
+  const kind = ensureString(document.frontmatter.kind, lessonPath, 1, "kind", { required: true });
+  if (!["slides", "video", "quiz", "coding_exercise", "spreadsheet_lab"].includes(kind)) {
+    throw new RepoContractError(
+      toPosixPath(lessonPath),
+      "kind must be one of `slides`, `video`, `quiz`, `coding_exercise`, or `spreadsheet_lab`",
+      1
+    );
+  }
+
+  let resource;
+  if (kind === "slides") {
+    const slidesDir = validateRequiredDirectory(path.join(dirPath, "slides"), "slides");
+    const slideFiles = orderedMarkdownFiles(slidesDir);
+    if (slideFiles.length === 0) {
+      throw new RepoContractError(
+        toPosixPath(slidesDir),
+        "Slides lessons must contain at least one slide file"
+      );
+    }
+    resource = {
+      type: "slides",
+      title,
+      slides: slideFiles.map((slidePath) => parseSlideFile(rootPath, slidePath)),
+    };
+  } else if (kind === "video") {
+    const videoPath = validateRequiredFile(path.join(dirPath, "video.md"), "video");
+    resource = {
+      type: "video",
+      ...parseVideoFile(rootPath, videoPath, title),
+    };
+  } else if (kind === "quiz") {
+    const quizDir = validateRequiredDirectory(path.join(dirPath, "quiz"), "quiz");
+    const quizPath = validateRequiredFile(path.join(quizDir, "quiz.md"), "quiz metadata");
+    const quizDocument = readMarkdownDocument(quizPath);
+    const quizTitle = ensureString(quizDocument.frontmatter.title, quizPath, 1, "title") || title;
+    const questionsDir = validateRequiredDirectory(path.join(quizDir, "questions"), "quiz questions");
+    const questionFiles = orderedMarkdownFiles(questionsDir);
+    if (questionFiles.length === 0) {
+      throw new RepoContractError(
+        toPosixPath(questionsDir),
+        "Quiz lessons must contain at least one question file"
+      );
+    }
+    resource = {
+      type: "quiz",
+      title: quizTitle,
+      description: quizDocument.body.trim() || null,
+      questions: questionFiles.map((questionPath) => parseQuizQuestion(rootPath, questionPath, warnings)),
+    };
+  } else if (kind === "coding_exercise") {
+    const exerciseDir = validateRequiredDirectory(path.join(dirPath, "exercise"), "exercise");
+    resource = {
+      type: "coding_exercise",
+      ...parseExerciseDirectory(rootPath, exerciseDir, title),
+    };
+  } else {
+    const spreadsheetDir = validateRequiredDirectory(path.join(dirPath, "spreadsheet"), "spreadsheet");
+    resource = {
+      type: "spreadsheet_lab",
+      ...parseSpreadsheetDirectory(rootPath, spreadsheetDir, title),
+    };
+  }
+
+  return {
+    repoKey: relativePosix(rootPath, dirPath),
+    repoPath: relativePosix(rootPath, dirPath),
+    title,
+    summaryMarkdown: document.body.trim(),
+    kind,
+    resource,
+  };
+}
+
+export function parseCourseRepository(rootPath) {
+  const resolvedRoot = path.resolve(rootPath);
+  const coursePath = validateRequiredFile(path.join(resolvedRoot, "course.md"), "course");
+  const courseDocument = readMarkdownDocument(coursePath);
+
+  const schemaVersion = ensureInteger(courseDocument.frontmatter.schema_version, coursePath, 1, "schema_version");
+  if (schemaVersion !== 1) {
+    throw new RepoContractError(toPosixPath(coursePath), "schema_version must be 1", 1);
+  }
+
+  const courseTitle = ensureString(courseDocument.frontmatter.title, coursePath, 1, "title", {
+    required: true,
+  });
+  const duration = ensureInteger(courseDocument.frontmatter.duration, coursePath, 1, "duration");
+  const thumbnail = ensureString(courseDocument.frontmatter.thumbnail, coursePath, 1, "thumbnail");
+  const rawTags = courseDocument.frontmatter.tags;
+  let tags = [];
+  if (rawTags == null) {
+    tags = [];
+  } else if (Array.isArray(rawTags) && rawTags.every((item) => typeof item === "string")) {
+    tags = rawTags.map((item) => item.trim()).filter(Boolean);
+  } else {
+    throw new RepoContractError(toPosixPath(coursePath), "tags must be a list of strings", 1);
+  }
+
+  const chaptersDir = validateRequiredDirectory(path.join(resolvedRoot, "chapters"), "chapters");
+  const chapterDirs = orderedDirectories(chaptersDir);
+
+  const warnings = [];
+  for (const requiredDoc of [".agents/rules/general.md"]) {
+    if (!statExists(path.join(resolvedRoot, requiredDoc), "file")) {
+      warnings.push(`Missing recommended rules file \`${requiredDoc}\``);
+    }
+  }
+
+  const chapters = chapterDirs.map((chapterDir) => {
+    const { slug } = orderedPathParts(chapterDir);
+    const chapterPath = validateRequiredFile(path.join(chapterDir, "chapter.md"), "chapter");
+    const chapterDocument = readMarkdownDocument(chapterPath);
+    const title = ensureString(chapterDocument.frontmatter.title, chapterPath, 1, "title") || slugToTitle(slug);
+
+    const lessonsDir = validateRequiredDirectory(path.join(chapterDir, "lessons"), "lessons");
+    const lessonDirs = orderedDirectories(lessonsDir);
+    if (lessonDirs.length === 0) {
+      throw new RepoContractError(
+        toPosixPath(lessonsDir),
+        "Chapter must contain at least one lesson"
+      );
+    }
+
+    return {
+      repoKey: relativePosix(resolvedRoot, chapterDir),
+      repoPath: relativePosix(resolvedRoot, chapterDir),
+      title,
+      description: chapterDocument.body.trim() || null,
+      lessons: lessonDirs.map((lessonDir) => parseLessonDirectory(resolvedRoot, lessonDir, warnings)),
+    };
+  });
+
+  return {
+    schemaVersion: 1,
+    contract: "repo_tree_v1",
+    warnings,
+    course: {
+      repoKey: "course",
+      repoPath: "course.md",
+      title: courseTitle,
+      description: courseDocument.body.trim(),
+      duration,
+      thumbnail,
+      tags,
+    },
+    chapters,
+  };
+}
+
+export function buildValidationSummary(rootPath, parsedRepo) {
+  const resourceCounts = {
+    slides: 0,
+    video: 0,
+    quiz: 0,
+    coding_exercise: 0,
+    spreadsheet_lab: 0,
+  };
+
+  let lessonCount = 0;
+  for (const chapter of parsedRepo.chapters) {
+    lessonCount += chapter.lessons.length;
+    for (const lesson of chapter.lessons) {
+      if (lesson.resource?.type && Object.hasOwn(resourceCounts, lesson.resource.type)) {
+        resourceCounts[lesson.resource.type] += 1;
+      }
+    }
+  }
+
+  return {
+    ok: true,
+    path: toPosixPath(path.resolve(rootPath)),
+    contract: parsedRepo.contract,
+    courseTitle: parsedRepo.course.title,
+    chapterCount: parsedRepo.chapters.length,
+    lessonCount,
+    resourceCounts,
+    warnings: parsedRepo.warnings,
+  };
+}