@intellectif/lk-core 1.6.0 → 1.8.0

package/dist/index.cjs

@@ -1,11 +1,11 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_registry = require("./registry-Ih5n4PVZ.cjs");
-const require_ai_writing = require("./ai-writing-C4YRVrFi.cjs");
-const require_scoring = require("./scoring-CaPS6q8b.cjs");
-const require_item_group = require("./item-group-CQRbb8Rx.cjs");
-const require_schemas = require("./schemas-Q2dyOgc2.cjs");
-const require_xapi = require("./xapi-BX0hvRRB.cjs");
-//#region src/delivery.ts
+const require_registry = require("./registry-Cymq7Ah0.cjs");
+const require_ai_writing = require("./ai-writing-Bh2Y53cY.cjs");
+const require_scoring = require("./scoring-D9tFvPEG.cjs");
+const require_item_group = require("./item-group-KV4hYu3a.cjs");
+const require_schemas = require("./schemas-wDzbKdKa.cjs");
+const require_xapi = require("./xapi-Dyqcl3JK.cjs");
+// src/delivery.ts
 /**
 * The policy that restricts nothing: every setting `true`. It is what an absent
 * policy resolves to, and it is exactly the behaviour the SDK had before
@@ -159,8 +159,7 @@ function validateDeliveryPolicy(policy) {
 		data: given
 	};
 }
-//#endregion
-//#region src/item-group.ts
+// src/item-group.ts
 /** Narrows a sequence entry to an item group. */
 function isItemGroup(entry) {
 	return entry.type === "item-group";
@@ -284,8 +283,7 @@ function flattenSequence(entries, options = {}) {
 	}
 	return slots;
 }
-//#endregion
-//#region src/media-budget.ts
+// src/media-budget.ts
 /**
 * The authored-entry prefix of a slot id: `"3"` for both `"3"` and `"3.1"`.
 *
@@ -399,8 +397,7 @@ function restoreMediaPlayLedger(plan, stored) {
 	if (stored.planHash !== plan.planHash) throw new Error(`restoreMediaPlayLedger: this ledger belongs to a different paper (ledger ${stored.planHash}, plan ${plan.planHash}). Restoring it would hold the learner to a play budget from an exam they never sat.`);
 	return serializeMediaPlayLedger(plan, stored.entries, { ...stored.savedAt !== void 0 ? { savedAt: stored.savedAt } : {} });
 }
-//#endregion
-//#region src/attempt-plan.ts
+// src/attempt-plan.ts
 /**
 * The activity as CONTENT, with its slot key removed.
 *
@@ -651,8 +648,7 @@ function scoredItemsFromPlan(plan, outcomes, options = {}) {
 		outcome: Object.hasOwn(outcomes, slot.slotId) ? outcomes[slot.slotId] : missingOutcome(slot, policy)
 	}));
 }
-//#endregion
-//#region src/attempt-state.ts
+// src/attempt-state.ts
 /**
 * A DEEP copy of the responses.
 *
@@ -776,8 +772,7 @@ function diffResponses(before, after) {
 	}
 	return entries;
 }
-//#endregion
-//#region src/redact.ts
+// src/redact.ts
 /** Merges per-call overrides over a registered policy, one level deep. */
 function mergePolicy(base, overrides) {
 	if (overrides === void 0) return base;
@@ -1044,8 +1039,7 @@ function withoutAuthorOnly(entry) {
 		...Array.isArray(items) ? { items: items.map((item) => withoutAuthorOnlyValue(item, policyOf(item?.type))) } : items !== void 0 ? { items } : {}
 	};
 }
-//#endregion
-//#region src/timeline.ts
+// src/timeline.ts
 /**
 * Reads a stored {@link MediaProgress}. Never throws: anything that is not one
 * — a string, a stale shape, an object whose getters throw — answers `null`,
@@ -1099,7 +1093,268 @@ function composeTimelineScore(entryKey, items, policy) {
 		items: own
 	}], policy);
 }
-//#endregion
+// src/versions.ts
+/**
+* Every code `critiqueVersions` reports, and its severity: a contract, as the
+* critic's codes are. `versions_shared_media` is `advice` for a picture both
+* forms may show, and a `warning` otherwise.
+*/
+const VERSION_FINDING_SEVERITY = {
+	versions_section_mismatch: "invalid",
+	versions_entry_count: "invalid",
+	versions_type_mismatch: "invalid",
+	versions_structure_mismatch: "invalid",
+	versions_objectives_mismatch: "warning",
+	versions_length_out_of_band: "warning",
+	versions_near_copy: "warning",
+	versions_same_key: "warning",
+	versions_shared_media: "warning"
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const listOf = (value) => Array.isArray(value) ? value : [];
+const stringOf = (value) => typeof value === "string" ? value : "";
+const key = (path) => path.join(".");
+function report(code, message, a, b, severity = VERSION_FINDING_SEVERITY[code]) {
+	return {
+		path: [...b ?? a ?? []],
+		message,
+		code,
+		severity,
+		...a !== void 0 ? { a: [...a] } : {},
+		...b !== void 0 ? { b: [...b] } : {}
+	};
+}
+function entriesOf(paper) {
+	return listOf(paper?.sections).flatMap((section, s) => listOf(isRecord(section) ? section.entries : void 0).flatMap((value, index) => isRecord(value) ? [{
+		path: [
+			"sections",
+			String(s),
+			"entries",
+			String(index)
+		],
+		section: s,
+		index,
+		value
+	}] : []));
+}
+/** A group's items, or the entry itself: the slots a learner answers. */
+const itemsOf = (entry) => entry.value.type === "item-group" ? listOf(entry.value.items).flatMap((item, at) => isRecord(item) ? [{
+	path: [
+		...entry.path,
+		"items",
+		String(at)
+	],
+	value: item
+}] : []) : [{
+	path: entry.path,
+	value: entry.value
+}];
+const typeName = (value) => stringOf(value.type) || "no type";
+function pairEntries(aEntries, bEntries, given) {
+	const pairs = [];
+	const takenA = /* @__PURE__ */ new Set();
+	const takenB = /* @__PURE__ */ new Set();
+	const add = (a, b, by) => {
+		pairs.push({
+			a,
+			b,
+			by
+		});
+		takenA.add(key(a.path));
+		takenB.add(key(b.path));
+	};
+	const aByPath = new Map(aEntries.map((one) => [key(one.path), one]));
+	const bByPath = new Map(bEntries.map((one) => [key(one.path), one]));
+	for (const pair of given ?? []) {
+		const a = aByPath.get(key(pair.a.map(String)));
+		const b = bByPath.get(key(pair.b.map(String)));
+		if (a !== void 0 && b !== void 0 && !takenA.has(key(a.path)) && !takenB.has(key(b.path))) add(a, b, "pairs");
+	}
+	for (const a of aEntries) {
+		const slotKey = a.value.slotKey;
+		if (takenA.has(key(a.path)) || typeof slotKey !== "string") continue;
+		const b = bEntries.find((one) => one.value.slotKey === slotKey && !takenB.has(key(one.path)));
+		if (b !== void 0) add(a, b, "slotKey");
+	}
+	for (const a of aEntries) {
+		if (takenA.has(key(a.path))) continue;
+		const b = bEntries.find((one) => one.section === a.section && one.index === a.index && !takenB.has(key(one.path)));
+		if (b !== void 0) add(a, b, "position");
+	}
+	return pairs;
+}
+/** A paired group's items, by their own `slotKey` when both have one, else by position. */
+function pairItems(pair) {
+	const aItems = itemsOf(pair.a);
+	const bItems = itemsOf(pair.b);
+	if (pair.a.value.type !== "item-group" || pair.b.value.type !== "item-group") {
+		const one = aItems[0];
+		const two = bItems[0];
+		return one !== void 0 && two !== void 0 ? [{
+			a: one,
+			b: two,
+			by: pair.by
+		}] : [];
+	}
+	const taken = /* @__PURE__ */ new Set();
+	const pairs = [];
+	aItems.forEach((a) => {
+		const slotKey = a.value.slotKey;
+		const found = typeof slotKey === "string" ? bItems.findIndex((b, index) => b.value.slotKey === slotKey && !taken.has(index)) : -1;
+		if (found !== -1) {
+			taken.add(found);
+			pairs.push({
+				a,
+				b: bItems[found],
+				by: "slotKey"
+			});
+		}
+	});
+	aItems.forEach((a, at) => {
+		if (pairs.some((one) => one.a === a) || at >= bItems.length || taken.has(at)) return;
+		taken.add(at);
+		pairs.push({
+			a,
+			b: bItems[at],
+			by: "position"
+		});
+	});
+	return pairs.sort((x, y) => aItems.indexOf(x.a) - aItems.indexOf(y.a));
+}
+const objectives = (value) => [...listOf(value.learningObjectives).filter((one) => typeof one === "string")].sort().join("\n");
+/**
+* Compares two forms of an exam slot by slot, and the whole of one with the
+* whole of the other: whether they are parallel — the same blueprint, types,
+* structure and scoring (`invalid` when not) — and whether a learner who sat
+* one would meet the other again: a near copy anywhere in the other form, a
+* shared right answer in a paired slot, the same recording (`warning`), or
+* the same picture (`advice` while `allowSharedImages`, its default).
+* Objectives and lengths that differ are warnings.
+*
+* Slots are paired by `pairs` (paths from each paper's root, as
+* `generateVariants`' pairs give them once a host places them), then by
+* `slotKey`, then by position: the same entry of the same section. A paired
+* group's items pair by their own `slotKey`, then by position.
+*
+* It reads content as stored, finished or not, and never throws.
+*/
+function critiqueVersions(a, b, options = {}) {
+	const findings = [];
+	const aSections = listOf(a?.sections);
+	const bSections = listOf(b?.sections);
+	if (aSections.length !== bSections.length) findings.push(report("versions_section_mismatch", `The second form has ${bSections.length} sections; the first has ${aSections.length}.`, void 0, void 0));
+	for (let s = 0; s < Math.min(aSections.length, bSections.length); s += 1) {
+		const one = isRecord(aSections[s]) ? aSections[s] : {};
+		const two = isRecord(bSections[s]) ? bSections[s] : {};
+		const at = ["sections", String(s)];
+		if (one.key !== two.key || one.title !== two.title) findings.push(report("versions_section_mismatch", `Section ${s + 1} is "${stringOf(two.title) || stringOf(two.key)}" in the second form and "${stringOf(one.title) || stringOf(one.key)}" in the first.`, at, at));
+		const aCount = listOf(one.entries).length;
+		const bCount = listOf(two.entries).length;
+		if (aCount !== bCount) findings.push(report("versions_entry_count", `Section ${s + 1} has ${bCount} entries in the second form and ${aCount} in the first.`, [...at, "entries"], [...at, "entries"]));
+	}
+	const aEntries = entriesOf(a);
+	const bEntries = entriesOf(b);
+	const pairs = pairEntries(aEntries, bEntries, options.pairs);
+	let structureMismatches = 0;
+	let paired = 0;
+	const slots = [];
+	for (const pair of pairs) {
+		slots.push({
+			a: pair.a.path,
+			b: pair.b.path,
+			by: pair.by
+		});
+		if (pair.a.value.type !== pair.b.value.type) {
+			structureMismatches += 1;
+			findings.push(report("versions_type_mismatch", `The second form has ${typeName(pair.b.value)} here; the first has ${typeName(pair.a.value)}.`, pair.a.path, pair.b.path));
+			continue;
+		}
+		const misses = require_ai_writing.structureMisses(pair.a.value, pair.b.value);
+		if (misses.length > 0) structureMismatches += 1;
+		for (const miss of misses) {
+			const code = miss.path[miss.path.length - 1] === "type" ? "versions_type_mismatch" : miss.path.length === 1 && miss.path[0] === "items" ? "versions_entry_count" : "versions_structure_mismatch";
+			findings.push(report(code, miss.message, [...pair.a.path, ...miss.path], [...pair.b.path, ...miss.path]));
+		}
+		for (const miss of require_ai_writing.lengthMisses(pair.a.value, pair.b.value, options.lengthTolerance)) findings.push(report("versions_length_out_of_band", `${miss.words} words; the first form's has ${miss.exemplarWords}, so ${miss.bounds[0]} to ${miss.bounds[1]}.`, [...pair.a.path, ...miss.path], [...pair.b.path, ...miss.path]));
+		const items = pairItems(pair);
+		if (pair.a.value.type === "item-group") for (const item of items) slots.push({
+			a: item.a.path,
+			b: item.b.path,
+			by: item.by
+		});
+		for (const item of items) {
+			if (item.a.value.type !== item.b.value.type) continue;
+			paired += 1;
+			if ((item.a.value.learningObjectives !== void 0 || item.b.value.learningObjectives !== void 0) && objectives(item.a.value) !== objectives(item.b.value)) findings.push(report("versions_objectives_mismatch", "The two forms test different learning objectives here.", item.a.path, item.b.path));
+			const aKeys = require_ai_writing.keysOf(item.a.value);
+			for (const slot of require_ai_writing.keysOf(item.b.value)) {
+				const match = aKeys.find((one) => one.slot === slot.slot);
+				const shared = match !== void 0 ? require_ai_writing.sharedAnswers(slot, match) : [];
+				if (shared.length > 0) findings.push(report("versions_same_key", `The right answer "${shared[0]}" is the same in both forms: a learner who sat the first scores again by memory.`, [...item.a.path, ...match.path], [...item.b.path, ...slot.path]));
+			}
+		}
+	}
+	const pairedA = new Set(slots.flatMap((slot) => slot.a !== null ? [key(slot.a)] : []));
+	const pairedB = new Set(slots.flatMap((slot) => slot.b !== null ? [key(slot.b)] : []));
+	for (const entry of aEntries) for (const one of entry.value.type === "item-group" ? [{ path: entry.path }, ...itemsOf(entry)] : [entry]) if (!pairedA.has(key(one.path))) slots.push({
+		a: one.path,
+		b: null,
+		by: "position"
+	});
+	for (const entry of bEntries) for (const one of entry.value.type === "item-group" ? [{ path: entry.path }, ...itemsOf(entry)] : [entry]) if (!pairedB.has(key(one.path))) slots.push({
+		a: null,
+		b: one.path,
+		by: "position"
+	});
+	const aTexts = aEntries.flatMap((entry) => require_ai_writing.textsOf(entry.value).map((text) => ({
+		...text,
+		path: [...entry.path, ...text.path]
+	})));
+	for (const entry of bEntries) for (const text of require_ai_writing.textsOf(entry.value)) {
+		let best;
+		for (const other of aTexts) {
+			if (other.kind !== text.kind) continue;
+			const score = require_ai_writing.textSimilarity(other.text, text.text);
+			if (score >= .5 && (best === void 0 || score > best.score)) best = {
+				score,
+				path: other.path
+			};
+		}
+		if (best !== void 0) findings.push(report("versions_near_copy", `This reads like the first form's text here (similarity ${require_ai_writing.shownScore(best.score)}).`, best.path, [...entry.path, ...text.path]));
+	}
+	const aOptions = aEntries.flatMap((entry) => itemsOf(entry).flatMap((item) => {
+		const set = require_ai_writing.optionSet(item.value);
+		return set !== null ? [{
+			path: item.path,
+			set: set.join("\n")
+		}] : [];
+	}));
+	for (const entry of bEntries) for (const item of itemsOf(entry)) {
+		const set = require_ai_writing.optionSet(item.value);
+		const match = set !== null ? aOptions.find((other) => other.set === set.join("\n")) : void 0;
+		if (match !== void 0) findings.push(report("versions_near_copy", "These options are the first form's, in another order.", [...match.path, "options"], [...item.path, "options"]));
+	}
+	const allowImages = options.allowSharedImages !== false;
+	const aFiles = /* @__PURE__ */ new Map();
+	for (const entry of aEntries) for (const ref of require_ai_writing.listMediaRefs(entry.value)) if (ref.url !== null && ref.url !== "" && !aFiles.has(ref.url)) aFiles.set(ref.url, [...entry.path, ...ref.path.map(String)]);
+	for (const entry of bEntries) for (const ref of require_ai_writing.listMediaRefs(entry.value)) {
+		const first = ref.url !== null ? aFiles.get(ref.url) : void 0;
+		if (first === void 0) continue;
+		const picture = ref.kind === "image";
+		findings.push(report("versions_shared_media", picture ? "Both forms show this picture." : "Both forms use this file: a learner who sat the first hears or sees it again.", first, [...entry.path, ...ref.path.map(String)], picture && allowImages ? "advice" : "warning"));
+	}
+	const count = (entries) => entries.reduce((sum, entry) => sum + itemsOf(entry).length, 0);
+	return {
+		findings,
+		slots,
+		summary: {
+			aItems: count(aEntries),
+			bItems: count(bEntries),
+			paired,
+			structureMismatches
+		}
+	};
+}
 exports.AI_COACHING_MAX_TIP_LENGTH = require_ai_writing.AI_COACHING_MAX_TIP_LENGTH;
 exports.AI_COACHING_MAX_WORDS = require_ai_writing.AI_COACHING_MAX_WORDS;
 exports.AI_CRITIQUE_MAX_FIELD_LENGTH = require_ai_writing.AI_CRITIQUE_MAX_FIELD_LENGTH;
@@ -1111,6 +1366,12 @@ exports.AI_GRADING_PROBABILITY_TOLERANCE = require_ai_writing.AI_GRADING_PROBABI
 exports.AI_HINT_TYPES = require_ai_writing.AI_HINT_TYPES;
 exports.AI_MATERIAL_MAX_LENGTH = require_ai_writing.AI_MATERIAL_MAX_LENGTH;
 exports.AI_TEXT_MAX_LENGTH = require_ai_writing.AI_TEXT_MAX_LENGTH;
+exports.AI_VARIANTS_MAX_EXEMPLARS = require_ai_writing.AI_VARIANTS_MAX_EXEMPLARS;
+exports.AI_VARIANTS_MAX_MATERIAL_LENGTH = require_ai_writing.AI_VARIANTS_MAX_MATERIAL_LENGTH;
+exports.AI_VARIANTS_MAX_REPAIRS = require_ai_writing.AI_VARIANTS_MAX_REPAIRS;
+exports.AI_VARIANT_CODE_SEVERITY = require_ai_writing.AI_VARIANT_CODE_SEVERITY;
+exports.AI_VARIANT_LENGTH_BANDS = require_ai_writing.AI_VARIANT_LENGTH_BANDS;
+exports.AI_VARIANT_NEAR_COPY_THRESHOLD = require_ai_writing.AI_VARIANT_NEAR_COPY_THRESHOLD;
 exports.AI_WRITING_MAX_CORRECTIONS = require_ai_writing.AI_WRITING_MAX_CORRECTIONS;
 exports.AI_WRITING_MAX_FIELD_LENGTH = require_ai_writing.AI_WRITING_MAX_FIELD_LENGTH;
 exports.ActivitySchemaError = require_registry.ActivitySchemaError;
@@ -1138,6 +1399,7 @@ exports.TIMELINE_MAX_ITEMS = require_item_group.TIMELINE_MAX_ITEMS;
 exports.TIMELINE_MAX_QUIZZES = require_item_group.TIMELINE_MAX_QUIZZES;
 exports.TIMELINE_MAX_TITLE_LENGTH = require_item_group.TIMELINE_MAX_TITLE_LENGTH;
 exports.UnknownActivityTypeError = require_registry.UnknownActivityTypeError;
+exports.VERSION_FINDING_SEVERITY = VERSION_FINDING_SEVERITY;
 exports.XAPIVerb = require_xapi.XAPIVerb;
 exports.XAPI_VERB_DISPLAY = require_xapi.XAPI_VERB_DISPLAY;
 exports.aiAllowedByContent = require_ai_writing.aiAllowedByContent;
@@ -1150,6 +1412,8 @@ exports.aiGradeOf = require_ai_writing.aiGradeOf;
 exports.aiGradingRequest = require_ai_writing.aiGradingRequest;
 exports.aiHintRequest = require_ai_writing.aiHintRequest;
 exports.aiSupports = require_ai_writing.aiSupports;
+exports.aiVariantsRepairRequest = require_ai_writing.aiVariantsRepairRequest;
+exports.aiVariantsRequest = require_ai_writing.aiVariantsRequest;
 exports.aiWritingFeedbackRequest = require_ai_writing.aiWritingFeedbackRequest;
 exports.alignDictation = require_registry.alignDictation;
 exports.alignReadAloud = require_scoring.alignReadAloud;
@@ -1164,6 +1428,7 @@ exports.checkAiDrafts = require_ai_writing.checkAiDrafts;
 exports.checkAiExplanation = require_ai_writing.checkAiExplanation;
 exports.checkAiGrading = require_ai_writing.checkAiGrading;
 exports.checkAiHint = require_ai_writing.checkAiHint;
+exports.checkAiVariants = require_ai_writing.checkAiVariants;
 exports.checkAiWritingFeedback = require_ai_writing.checkAiWritingFeedback;
 exports.classifyBand = require_scoring.classifyBand;
 exports.combineDeliveryPolicies = combineDeliveryPolicies;
@@ -1179,6 +1444,7 @@ exports.createItemGroupDraft = require_ai_writing.createItemGroupDraft;
 exports.critiqueDraft = require_ai_writing.critiqueDraft;
 exports.critiqueDrafts = require_ai_writing.critiqueDrafts;
 exports.critiqueItemGroupDraft = require_ai_writing.critiqueItemGroupDraft;
+exports.critiqueVersions = critiqueVersions;
 exports.defineActivityType = require_registry.defineActivityType;
 exports.dictationJsonSchema = require_schemas.dictationJsonSchema;
 exports.dictationReferenceWords = require_registry.dictationReferenceWords;
@@ -1195,6 +1461,7 @@ exports.flattenSequence = flattenSequence;
 exports.gapSelectJsonSchema = require_schemas.gapSelectJsonSchema;
 exports.gapSelectType = require_registry.gapSelectType;
 exports.generateDrafts = require_ai_writing.generateDrafts;
+exports.generateVariants = require_ai_writing.generateVariants;
 exports.getActivityTypeDescriptor = require_registry.getActivityTypeDescriptor;
 exports.gradeFromJudgement = require_scoring.gradeFromJudgement;
 exports.gradeFromRubric = require_scoring.gradeFromRubric;