@novedu/cli 0.14.0 → 0.15.0

package/dist/main.js

@@ -1517,6 +1517,25 @@ async function loadAndCheckCoding(url, fetchImpl, opts = {}) {
 }
 //#endregion
 //#region ../lib/quiz-schema.ts
+/**
+* A live quiz include: alias + URL, mirroring `FragmentFileRefSchema` (same URL
+* contract). The alias prefixes every imported question id as `"<alias>/<id>"`, so
+* on top of the no-dot rule it may not contain a `/` either. Aliases live in their
+* OWN namespace (they never appear in `{{…}}` markers — only in question ids).
+*/
+const QuizFileRefSchema = z.strictObject({
+	id: z.string().regex(/^[^./]+$/, { message: "Alias must not contain a dot or a slash" }).meta({
+		pattern: "^[^./]+$",
+		description: "Local alias for this included quiz. Prefixes every imported question id as \"<alias>/<id>\", so it may not contain a dot or a slash."
+	}),
+	url: FragmentFileRefSchema.shape.url.meta({
+		pattern: "^(https?://|(?![A-Za-z][A-Za-z0-9+.-]*:).+)$",
+		description: "HTTP(S) URL or relative path to the included quiz file."
+	})
+}).meta({
+	id: "quizFileRef",
+	description: "A reference to another quiz file whose questions are included live."
+});
 /** An optional content image attached to a question (carries no secret). */
 const ImageRefSchema = z.strictObject({
 	hosted: z.boolean().optional().meta({
@@ -1559,6 +1578,8 @@ const QuizYamlSchema = z.strictObject({
 		default: true,
 		description: "Present questions in a random order per attempt. Set to false to keep the authored order."
 	}),
+	question_count: z.number().int().min(1).optional().meta({ description: "How many questions one attempt asks (default: every question exactly once). May exceed the pool size — then questions repeat (drill mode). With shuffle off, fewer than the pool means the first N in authored order." }),
+	quiz_files: z.array(QuizFileRefSchema).default([]).meta({ description: "Other quiz files whose questions are ALL included live into this quiz (a compound/final quiz). One level deep — an included quiz may not itself declare quiz_files." }),
 	llm: z.strictObject({
 		model: z.string().min(1).meta({ description: "The model that grades answers and drives the per-question discussion chat." }),
 		provider: providerSchema,
@@ -1577,7 +1598,7 @@ const QuizYamlSchema = z.strictObject({
 	fragment_files: z.array(FragmentFileRefSchema).default([]).meta({ description: "Optional fragment libraries this quiz pulls shared prompt fragments from." }),
 	text_files: z.array(TextFileRefSchema).default([]).meta({ description: "Optional plain-text files (markdown / source) embedded verbatim into instructions via {{file \"alias\"}} markers." }),
 	instructions: z.string().optional().meta({ description: "Optional quiz-level preamble prepended to BOTH the grader prompt and the discussion chat. When any fragment_files or text_files are declared, place fragments inline with {{fragment \"alias.id\" …}} and embed text files with {{file \"alias\"}} (optionally {{file \"alias\" from=10 to=40}} for a line range; escape a literal {{ as \\{{)." }),
-	questions: z.array(QuizQuestionSchema).min(1).meta({ description: "The quiz questions. Each is open-ended and graded by the LLM via its evaluation prompt." })
+	questions: z.array(QuizQuestionSchema).default([]).meta({ description: "The quiz questions. Each is open-ended and graded by the LLM via its evaluation prompt. May be omitted when quiz_files supplies the questions." })
 });
 //#endregion
 //#region ../lib/quiz-validate.ts
@@ -1597,12 +1618,39 @@ function findDuplicateQuestionIds(quiz) {
 	return errors;
 }
 /**
-* Check an already-schema-validated quiz: unique question ids → metadata. Split from
+* Own question ids containing `/` — reserved as the namespace delimiter for
+* questions imported via `quiz_files` (`"<alias>/<id>"`), so an own id can never
+* collide with (or masquerade as) an imported one.
+*/
+function findReservedSlashIds(quiz) {
+	return quiz.questions.filter((question) => question.id.includes("/")).map((question) => error("QUIZ_QUESTION_ID_RESERVED_SLASH", `Question id "${question.id}" contains "/" — reserved for questions imported via quiz_files`, { questionId: question.id }));
+}
+/** Include aliases declared on more than one `quiz_files` entry. */
+function findDuplicateIncludeAliases(quiz) {
+	const errors = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const ref of quiz.quiz_files) {
+		if (seen.has(ref.id)) {
+			errors.push(error("DUPLICATE_QUIZ_INCLUDE_ALIAS", `Included-quiz alias "${ref.id}" is declared more than once`, { fileAlias: ref.id }));
+			continue;
+		}
+		seen.add(ref.id);
+	}
+	return errors;
+}
+/**
+* Check an already-schema-validated quiz: unique question ids, no reserved `/` ids,
+* unique include aliases, and a non-empty (potential) pool → metadata. Split from
 * `checkQuizValue` so `loadAndCheckQuiz` can reuse the single `validate` it already ran
 * (no second parse of the same document against the same schema).
 */
 function checkQuizParsed(quiz) {
-	const errors = findDuplicateQuestionIds(quiz);
+	const errors = [
+		...findDuplicateQuestionIds(quiz),
+		...findReservedSlashIds(quiz),
+		...findDuplicateIncludeAliases(quiz)
+	];
+	if (quiz.questions.length === 0 && quiz.quiz_files.length === 0) errors.push(error("QUIZ_NO_QUESTIONS", "This quiz has no questions and no quiz_files includes"));
 	if (errors.length > 0) return {
 		ok: false,
 		errors,
@@ -1619,12 +1667,83 @@ function checkQuizParsed(quiz) {
 		warnings: []
 	};
 }
+/** Wrap an include's nested failures into ONE error carrying the alias + URL. */
+function includeUnreadable(alias, url, nested) {
+	return error("QUIZ_INCLUDE_UNREADABLE", `Included quiz "${alias}" is not usable: ${nested.map((e) => e.message).join("; ")}`, url === void 0 ? { fileAlias: alias } : {
+		fileAlias: alias,
+		url
+	});
+}
+/**
+* Deep-check ONE `quiz_files` include: resolve + fetch + parse + the FULL strict
+* quiz check (schema, consistency passes, its own fragment-block authoring gate),
+* plus the one-level rule (`QUIZ_INCLUDE_NESTED`). Every other failure is wrapped
+* as `QUIZ_INCLUDE_UNREADABLE` with the alias + resolved URL.
+*/
+async function checkInclude(ref, baseUrl, fetchImpl, opts) {
+	let includeUrl;
+	try {
+		includeUrl = resolveFragmentUrl(ref.url, baseUrl);
+	} catch {
+		return {
+			ok: false,
+			errors: [includeUnreadable(ref.id, void 0, [error("INVALID_URL", `Invalid include URL: ${ref.url}`)])],
+			warnings: []
+		};
+	}
+	const yaml = await loadYaml(includeUrl, fetchImpl, opts);
+	if (!yaml.ok) return {
+		ok: false,
+		errors: [includeUnreadable(ref.id, includeUrl, [yaml.error])],
+		warnings: []
+	};
+	const valid = validate(yaml.value, QuizYamlSchema, "QUIZ_SCHEMA_ERROR", includeUrl);
+	if (!valid.ok) return {
+		ok: false,
+		errors: [includeUnreadable(ref.id, includeUrl, [valid.error])],
+		warnings: []
+	};
+	if (valid.data.quiz_files.length > 0) return {
+		ok: false,
+		errors: [error("QUIZ_INCLUDE_NESTED", `Included quiz "${ref.id}" itself declares quiz_files — includes are one level deep`, {
+			fileAlias: ref.id,
+			url: includeUrl
+		})],
+		warnings: []
+	};
+	const checked = checkQuizParsed(valid.data);
+	if (!checked.ok) return {
+		ok: false,
+		errors: [includeUnreadable(ref.id, includeUrl, checked.errors)],
+		warnings: checked.warnings
+	};
+	const assembled = await assembleFragmentPrompt({
+		fragment_files: valid.data.fragment_files,
+		text_files: valid.data.text_files
+	}, includeUrl, fetchImpl, {
+		allowedSchemes: opts.allowedSchemes,
+		validateLibraries: opts.validateLibraries ?? true
+	}, valid.data.instructions ?? "");
+	if (!assembled.ok) return {
+		ok: false,
+		errors: [includeUnreadable(ref.id, includeUrl, assembled.errors)],
+		warnings: assembled.warnings
+	};
+	return {
+		ok: true,
+		questionCount: valid.data.questions.length,
+		warnings: assembled.warnings
+	};
+}
 /**
 * Validate a quiz FILE: scheme-gate + fetch + parse (shared `loadYaml`), the pure
-* `checkQuizValue`, then the document-level fragment block's authoring gate — fetch
+* `checkQuizValue`, the document-level fragment block's authoring gate — fetch
 * every referenced library, run the THOROUGH whole-library check, consistency, and an
-* assembly dry-run (the strict-Handlebars backstop). The web app passes the default
-* http(s)-only schemes; the CLI adds `file:` so a local quiz YAML on disk validates too.
+* assembly dry-run (the strict-Handlebars backstop) — and a DEEP check of every
+* `quiz_files` include. On success `questionCount` is the RESOLVED pool size
+* (own + imported), so the `/files` save UI and code-create metadata reflect the
+* real exam size. The web app passes the default http(s)-only schemes; the CLI adds
+* `file:` so a local quiz YAML on disk validates too.
 */
 async function loadAndCheckQuiz(url, fetchImpl, opts = {}) {
 	const yaml = await loadYaml(url, fetchImpl, opts);
@@ -1654,8 +1773,22 @@ async function loadAndCheckQuiz(url, fetchImpl, opts = {}) {
 		errors: assembled.errors,
 		warnings
 	};
+	const includes = await Promise.all(valid.data.quiz_files.map((ref) => checkInclude(ref, url, fetchImpl, opts)));
+	const includeErrors = [];
+	let importedCount = 0;
+	for (const include of includes) {
+		warnings.push(...include.warnings);
+		if (include.ok) importedCount += include.questionCount;
+		else includeErrors.push(...include.errors);
+	}
+	if (includeErrors.length > 0) return {
+		ok: false,
+		errors: includeErrors,
+		warnings
+	};
 	return {
 		...checked,
+		questionCount: checked.questionCount + importedCount,
 		warnings
 	};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@novedu/cli",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Command-line companion for the Novedu chat app. Validates tutor, fragment, quiz, writing and coding YAML definitions; signs in with Entra ID and manages codes and app-hosted files over the app's API.",
   "type": "module",
   "repository": {