quizwitz-validator 0.0.0-stage → 0.2.0

package/dist/rules.js

@@ -0,0 +1,333 @@
+/**
+ * The rule kinds (docs/design.md, 3.4): the comparative kinds look at a
+ * round, the per-question kinds at one question. Ported from the editor's
+ * question-anomaly.ts and question-type-descriptor.ts so behaviour and ids
+ * are identical.
+ */
+import { filledOptionCount, fillsSlot, imageMapOf, optionsOf, questionSetting, resourceText, typeSettingValue } from './aggregate.js';
+import { groupSizeWarningId, questionWarningId } from './ignore.js';
+import { interpolate, localizedText } from './text.js';
+export function render(text, params, language) {
+    const messageKey = localizedText(text, language);
+    return { message: interpolate(messageKey, params), messageKey, messageParams: params };
+}
+function finding(ctx, q, rule, text, params, id) {
+    return {
+        id: id ?? questionWarningId(q.uuid, rule.id),
+        ruleId: rule.id,
+        roundId: ctx.roundId,
+        questionId: q.uuid,
+        ...render(text, params, ctx.language)
+    };
+}
+function median(values) {
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 1 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+function byType(questions) {
+    const groups = new Map();
+    for (const q of questions) {
+        const list = groups.get(q.token) ?? [];
+        list.push(q);
+        groups.set(q.token, list);
+    }
+    return groups;
+}
+// --- comparative kinds ---
+export function evaluateOutlier(rule, ctx) {
+    const carriers = ctx.questions.filter(q => {
+        const value = questionSetting(q.question, rule.field);
+        return typeof value === 'number' && value > 0;
+    });
+    if (carriers.length < (rule.minPopulation ?? 3)) {
+        return [];
+    }
+    const m = median(carriers.map(q => questionSetting(q.question, rule.field)));
+    if (m <= 0) {
+        return [];
+    }
+    const out = [];
+    for (const q of carriers) {
+        const value = questionSetting(q.question, rule.field);
+        if (value >= m * rule.factor || value <= m / rule.factor) {
+            out.push(finding(ctx, q, rule, rule.message, { value, median: m }));
+        }
+    }
+    return out;
+}
+export function evaluateOddOneOut(rule, ctx) {
+    const on = rule.unsetIsOn ? (value) => value !== false : (value) => !!value;
+    const out = [];
+    byType(ctx.questions).forEach(siblings => {
+        if (siblings.length < (rule.minPopulation ?? 4)) {
+            return;
+        }
+        const enabled = siblings.filter(q => on(questionSetting(q.question, rule.setting)));
+        const disabled = siblings.filter(q => !on(questionSetting(q.question, rule.setting)));
+        const deviant = enabled.length === 1 && disabled.length === siblings.length - 1 ? enabled[0] :
+            disabled.length === 1 && enabled.length === siblings.length - 1 ? disabled[0] :
+                null;
+        if (!deviant) {
+            return;
+        }
+        const deviantOn = on(questionSetting(deviant.question, rule.setting));
+        out.push(finding(ctx, deviant, rule, deviantOn ? rule.message : rule.messageDisabled, { setting: rule.label ?? rule.setting }));
+    });
+    return out;
+}
+export function evaluateOptionCountMajority(rule, ctx) {
+    const types = new Set(rule.types.map(t => t.toLowerCase()));
+    const out = [];
+    byType(ctx.questions).forEach((siblings, token) => {
+        if (!types.has(token)) {
+            return;
+        }
+        const carriers = siblings.filter(q => filledOptionCount(q.question) > 0);
+        if (carriers.length < (rule.minPopulation ?? 4)) {
+            return;
+        }
+        const tally = new Map();
+        for (const q of carriers) {
+            const count = filledOptionCount(q.question);
+            tally.set(count, (tally.get(count) ?? 0) + 1);
+        }
+        let expected = 0;
+        let agreeing = 0;
+        tally.forEach((questions, count) => {
+            if (questions > agreeing) {
+                expected = count;
+                agreeing = questions;
+            }
+        });
+        if (agreeing === carriers.length || agreeing <= carriers.length * (rule.majority ?? 0.5)) {
+            return;
+        }
+        for (const q of carriers) {
+            const count = filledOptionCount(q.question);
+            if (count !== expected) {
+                out.push(finding(ctx, q, rule, rule.message, { count, expected }));
+            }
+        }
+    });
+    return out;
+}
+export function evaluateGroupSize(rule, ctx) {
+    const order = [];
+    const groups = new Map();
+    ctx.questions.forEach((q, i) => {
+        const id = ctx.groupIds[i];
+        if (!groups.has(id)) {
+            groups.set(id, []);
+            order.push(id);
+        }
+        groups.get(id).push(q);
+    });
+    if (order.length < (rule.minPopulation ?? 3)) {
+        return [];
+    }
+    const bySize = new Map();
+    for (const id of order) {
+        const size = groups.get(id).length;
+        bySize.set(size, [...(bySize.get(size) ?? []), id]);
+    }
+    if (bySize.size !== 2) {
+        return [];
+    }
+    const [[sizeA, idsA], [sizeB, idsB]] = [...bySize.entries()];
+    const odd = idsA.length === 1 ? { id: idsA[0], count: sizeA, expected: sizeB }
+        : idsB.length === 1 ? { id: idsB[0], count: sizeB, expected: sizeA }
+            : null;
+    if (!odd) {
+        return [];
+    }
+    const first = groups.get(odd.id)[0];
+    return [finding(ctx, first, rule, odd.count === 1 ? rule.messageSingle : rule.message, { count: odd.count, expected: odd.expected }, groupSizeWarningId(ctx.roundId, odd.id))];
+}
+/**
+ * The nth question of every group compared across the groups: where a strict
+ * majority (but not all) of the groups agree on the value, the nth questions
+ * that differ. Questions without a value (no positive setting, empty text)
+ * are left out of the count.
+ */
+export function evaluateGroupPosition(rule, ctx) {
+    const order = [];
+    const groups = new Map();
+    ctx.questions.forEach((q, i) => {
+        const id = ctx.groupIds[i];
+        if (!groups.has(id)) {
+            groups.set(id, []);
+            order.push(id);
+        }
+        groups.get(id).push(q);
+    });
+    const valueOf = (q) => {
+        if (rule.setting !== undefined) {
+            const value = questionSetting(q.question, rule.setting);
+            return typeof value === 'number' && value > 0 ? { key: String(value), value } : null;
+        }
+        const text = resourceText(q.question, rule.field);
+        return text !== '' ? { key: text.toLowerCase(), value: text } : null;
+    };
+    const longest = Math.max(0, ...order.map(id => groups.get(id).length));
+    const out = [];
+    for (let position = 0; position < longest; position++) {
+        const carriers = [];
+        for (const id of order) {
+            const q = groups.get(id)[position];
+            const value = q ? valueOf(q) : null;
+            if (q && value) {
+                carriers.push({ q, ...value });
+            }
+        }
+        if (carriers.length < (rule.minPopulation ?? 3)) {
+            continue;
+        }
+        const tally = new Map();
+        for (const c of carriers) {
+            tally.set(c.key, (tally.get(c.key) ?? 0) + 1);
+        }
+        let expected = '';
+        let agreeing = 0;
+        tally.forEach((count, key) => {
+            if (count > agreeing) {
+                expected = key;
+                agreeing = count;
+            }
+        });
+        if (agreeing === carriers.length || agreeing <= carriers.length * (rule.majority ?? 0.5)) {
+            continue;
+        }
+        const shown = carriers.find(c => c.key === expected).value;
+        for (const c of carriers) {
+            if (c.key !== expected) {
+                out.push(finding(ctx, c.q, rule, rule.message, { value: c.value, expected: shown, position: position + 1 }));
+            }
+        }
+    }
+    return out;
+}
+/** Explanation swaps; `quiet` names the `questionUuid:field` gaps the swap explains, for the consistency rules. */
+export function evaluateExplanationPair(rule, ctx, quiet) {
+    const fields = rule.fields;
+    const has = (q, field) => resourceText(q.question, field) !== '';
+    const carriers = ctx.questions.filter(q => fields.some(f => has(q, f)));
+    if (carriers.length < (rule.minPopulation ?? 4)) {
+        return [];
+    }
+    const label = (field) => rule.labels?.[field] ?? field;
+    const out = [];
+    for (const expected of fields) {
+        const actual = fields.find(f => f !== expected);
+        const users = carriers.filter(q => has(q, expected));
+        if (users.length === carriers.length || users.length < carriers.length * (rule.majority ?? 0.75)) {
+            continue;
+        }
+        for (const q of carriers) {
+            if (has(q, expected) || !has(q, actual)) {
+                continue;
+            }
+            out.push(finding(ctx, q, rule, rule.message, { expected: label(expected), actual: label(actual) }));
+            quiet.add(q.uuid + ':' + expected);
+        }
+    }
+    return out;
+}
+export function evaluateConsistency(rule, ctx, quiet) {
+    const questions = ctx.questions;
+    if (questions.length < (rule.minPopulation ?? 4)) {
+        return [];
+    }
+    const field = rule.field;
+    const fills = field !== undefined
+        ? (q) => resourceText(q.question, field) !== ''
+        : (q) => fillsSlot(q.question, rule.slot);
+    const carriers = questions.filter(fills);
+    if (carriers.length === questions.length || carriers.length < questions.length * (rule.majority ?? 0.75)) {
+        return [];
+    }
+    const label = rule.label ?? (field ?? rule.slot);
+    const params = field !== undefined ? { field: label } : { slot: label };
+    const out = [];
+    for (const q of questions) {
+        if (fills(q) || (field !== undefined && quiet.has(q.uuid + ':' + field))) {
+            continue;
+        }
+        out.push(finding(ctx, q, rule, rule.message, params));
+    }
+    return out;
+}
+// --- per-question kinds ---
+/** The completeness checks by name (the editor's QuestionTypeDescriptor.checkRule). */
+export function passesCheck(question, check) {
+    const options = optionsOf(question);
+    const filled = (text) => text.trim().length > 0;
+    switch (check) {
+        case 'requireText':
+            return resourceText(question, 'text') !== '';
+        case 'correctOption':
+        case 'requireCorrectOption':
+            return options.some(o => o.correct && filled(o.text));
+        case 'allOptionsFilled':
+        case 'requireAllOptionsFilled':
+            return options.length > 0 && options.every(o => filled(o.text));
+        case 'answer':
+        case 'requireAnswer':
+            return options.length > 0 && filled(options[0].text);
+        case 'imageMap':
+        case 'requireImageMap': {
+            // A neutral zone scores nothing: a map with only neutral zones can never be answered correctly.
+            const map = imageMapOf(question);
+            return map !== null && map.points.some(p => p && p.kind !== 'neutral');
+        }
+        default:
+            return true;
+    }
+}
+/** What a failed `require` reports, or null when it passes. */
+export function evaluateRequire(rule, q) {
+    if (rule.field !== undefined) {
+        return resourceText(q.question, rule.field) !== '' ? null : { field: rule.field };
+    }
+    if (rule.setting !== undefined) {
+        return questionSetting(q.question, rule.setting) === true ? null : { setting: rule.setting };
+    }
+    if (rule.check !== undefined) {
+        return passesCheck(q.question, rule.check) ? null : { check: rule.check };
+    }
+    return null;
+}
+export function matchesSettingEquals(rule, q) {
+    return questionSetting(q.question, rule.setting) === rule.equals;
+}
+/** A typeSettings value, or the field's default when unset (as the editor's form shows it). */
+function typeSettingOrDefault(q, key) {
+    const value = typeSettingValue(q.question, key);
+    if (value !== undefined && value !== null) {
+        return value;
+    }
+    return q.settingsFields.find(f => f.key === key)?.default ?? null;
+}
+export function matchesOptionCountOver(rule, q) {
+    const settingOff = !questionSetting(q.question, rule.settingFalse);
+    return optionsOf(q.question).length > rule.optionsOver && settingOff;
+}
+export function matchesTypeSetting(rule, q) {
+    if (typeSettingOrDefault(q, rule.typeSetting.key) !== rule.typeSetting.equals) {
+        return false;
+    }
+    const value = Number(typeSettingOrDefault(q, rule.typeSettingBelow.key));
+    return !Number.isFinite(value) || value < rule.typeSettingBelow.min;
+}
+/** A legacy `warnings` entry of a question type (optionsOver / typeSetting shapes). */
+export function matchesLegacyWarning(warning, q) {
+    return 'typeSetting' in warning ? matchesTypeSetting(warning, q) : matchesOptionCountOver(warning, q);
+}
+/** The English detail of a failed completeness rule. */
+export const COMPLETENESS_MESSAGES = {
+    requireText: 'The question has no text',
+    requireCorrectOption: 'No answer option is marked correct',
+    requireAllOptionsFilled: 'Every answer option needs a text',
+    requireAnswer: 'The answer is missing',
+    requireImageMap: 'The image map needs a picture with at least one zone that scores'
+};

package/dist/text.d.ts

@@ -0,0 +1,9 @@
+import type { LocalizedText } from './types.js';
+/**
+ * The text of a manifest text in `language`: that language (a regional one
+ * matches its base: nl-BE -> nl), else English, else the first text there
+ * is. Empty texts are skipped (the editor's localizedMessage).
+ */
+export declare function localizedText(text: LocalizedText | null | undefined, language?: string): string;
+/** Fills `{placeholder}`s; a placeholder without a value stays as it is. */
+export declare function interpolate(template: string, params: Record<string, string | number>): string;

package/dist/text.js

@@ -0,0 +1,29 @@
+/**
+ * The text of a manifest text in `language`: that language (a regional one
+ * matches its base: nl-BE -> nl), else English, else the first text there
+ * is. Empty texts are skipped (the editor's localizedMessage).
+ */
+export function localizedText(text, language) {
+    if (typeof text === 'string') {
+        return text;
+    }
+    if (!text || typeof text !== 'object') {
+        return '';
+    }
+    const texts = new Map();
+    for (const key of Object.keys(text)) {
+        const value = text[key];
+        if (typeof value === 'string' && value.trim().length > 0) {
+            texts.set(key.toLowerCase().replace('_', '-'), value);
+        }
+    }
+    const wanted = (language ?? '').toLowerCase().replace('_', '-');
+    return texts.get(wanted)
+        ?? texts.get(wanted.split('-')[0])
+        ?? texts.get('en')
+        ?? (texts.size > 0 ? texts.values().next().value : '');
+}
+/** Fills `{placeholder}`s; a placeholder without a value stays as it is. */
+export function interpolate(template, params) {
+    return template.replace(/\{(\w+)\}/g, (match, key) => (key in params ? String(params[key]) : match));
+}

package/dist/types.d.ts

@@ -0,0 +1,237 @@
+/**
+ * The served manifests (the part this package reads), the rule vocabulary
+ * and the evaluator's input and output (docs/design.md, 3 and 4).
+ */
+/** A text, or a text per language (`{ "en": "…", "nl": "…" }`). */
+export type LocalizedText = string | Record<string, string>;
+/** `"*"` or a list of tokens. */
+export type TokenList = '*' | string[];
+export type QuestionList = 'list' | 'grouped' | 'none';
+export interface SettingsField {
+    key: string;
+    type?: string;
+    target?: string;
+    label?: LocalizedText;
+    default?: unknown;
+    min?: number;
+    max?: number;
+    /** Shown (and so expected) only when another field of the same bag equals a value. */
+    showWhen?: {
+        key: string;
+        equals: unknown;
+    };
+    [key: string]: unknown;
+}
+export type RuleKind = 'outlier' | 'oddOneOut' | 'consistency' | 'explanationPair' | 'optionCountMajority' | 'groupSize' | 'groupPosition' | 'require' | 'settingEquals' | 'optionCountOver' | 'typeSetting';
+export declare const COMPARATIVE_KINDS: readonly RuleKind[];
+export declare const PER_QUESTION_KINDS: readonly RuleKind[];
+export type Severity = 'error' | 'warning';
+export interface RuleBase {
+    /** The rule id: what ignoredWarnings stores. */
+    id: string;
+    rule: RuleKind;
+    severity?: Severity;
+    message: LocalizedText;
+    description?: LocalizedText;
+    /** Only in rounds whose type has this questionList (absent: every round with questions). */
+    questionList?: Exclude<QuestionList, 'none'> | Exclude<QuestionList, 'none'>[];
+    minPopulation?: number;
+    majority?: number;
+}
+export interface OutlierRule extends RuleBase {
+    rule: 'outlier';
+    field: string;
+    factor: number;
+}
+export interface OddOneOutRule extends RuleBase {
+    rule: 'oddOneOut';
+    setting: string;
+    label?: string;
+    /** null/undefined count as on (playTimerMusic). */
+    unsetIsOn?: boolean;
+    messageDisabled: LocalizedText;
+}
+export interface ConsistencyRule extends RuleBase {
+    rule: 'consistency';
+    field?: string;
+    slot?: string;
+    label?: string;
+}
+export interface ExplanationPairRule extends RuleBase {
+    rule: 'explanationPair';
+    fields: [string, string] | string[];
+    labels?: Record<string, string>;
+}
+export interface OptionCountMajorityRule extends RuleBase {
+    rule: 'optionCountMajority';
+    types: string[];
+}
+export interface GroupSizeRule extends RuleBase {
+    rule: 'groupSize';
+    messageSingle: LocalizedText;
+}
+export interface GroupPositionRule extends RuleBase {
+    rule: 'groupPosition';
+    /** A question setting (`points`), or else */
+    setting?: string;
+    /** a text on the primary resource (`label`), compared trimmed and ignoring case. */
+    field?: string;
+}
+export type RequireCheck = 'correctOption' | 'allOptionsFilled' | 'answer' | 'imageMap';
+export interface RequireRule extends RuleBase {
+    rule: 'require';
+    field?: string;
+    setting?: string;
+    check?: RequireCheck;
+}
+export interface SettingEqualsRule extends RuleBase {
+    rule: 'settingEquals';
+    setting: string;
+    equals: unknown;
+}
+export interface OptionCountOverRule extends RuleBase {
+    rule: 'optionCountOver';
+    optionsOver: number;
+    settingFalse: string;
+}
+export interface TypeSettingRule extends RuleBase {
+    rule: 'typeSetting';
+    typeSetting: {
+        key: string;
+        equals: unknown;
+    };
+    typeSettingBelow: {
+        key: string;
+        min: number;
+    };
+}
+export type FindingRule = OutlierRule | OddOneOutRule | ConsistencyRule | ExplanationPairRule | OptionCountMajorityRule | GroupSizeRule | GroupPositionRule | RequireRule | SettingEqualsRule | OptionCountOverRule | TypeSettingRule;
+/** The existing editor-facing fields the evaluator reads as well (docs/design.md, 3.2). */
+export type CompletenessRule = 'requireText' | 'requireCorrectOption' | 'requireAllOptionsFilled' | 'requireAnswer' | 'requireImageMap';
+export interface OptionCountWarning {
+    optionsOver: number;
+    settingFalse: string;
+    message: LocalizedText;
+}
+export interface TypeSettingWarning {
+    typeSetting: {
+        key: string;
+        equals: unknown;
+    };
+    typeSettingBelow: {
+        key: string;
+        min: number;
+    };
+    message: LocalizedText;
+}
+export type LegacyWarning = OptionCountWarning | TypeSettingWarning;
+export interface SettingWarning {
+    setting: string;
+    equals: unknown;
+    message: LocalizedText;
+}
+export interface TypeEntryBase {
+    token: string;
+    name?: LocalizedText;
+    description?: LocalizedText;
+    aliases?: string[];
+    hidden?: boolean;
+    settingsFields?: SettingsField[];
+    findings?: FindingRule[];
+    guidance?: LocalizedText;
+    [key: string]: unknown;
+}
+export interface RoundTypeEntry extends TypeEntryBase {
+    questionList?: QuestionList;
+    allowedQuestionTypes?: TokenList;
+    allowedScoringStrategies?: TokenList;
+    defaultScoringStrategy?: string;
+    questionSettingWarnings?: SettingWarning[];
+}
+export interface QuestionTypeEntry extends TypeEntryBase {
+    addToRounds?: TokenList;
+    completeness?: CompletenessRule[];
+    warnings?: LegacyWarning[];
+    settingWarnings?: SettingWarning[];
+}
+export interface ScoringStrategyEntry extends TypeEntryBase {
+    supportedRoundTypes?: TokenList;
+    unsupportedRoundTypes?: string[];
+    questionSettingWarnings?: SettingWarning[];
+}
+export interface TypeManifest {
+    id: string;
+    name?: LocalizedText;
+    version?: string;
+    roundTypes?: RoundTypeEntry[];
+    questionTypes?: QuestionTypeEntry[];
+    scoringStrategies?: ScoringStrategyEntry[];
+    /** Core manifest only: the round-wide rules every round with questions gets. */
+    findings?: FindingRule[];
+    [key: string]: unknown;
+}
+export interface ServedManifests {
+    format: number;
+    core: TypeManifest;
+    mods: TypeManifest[];
+}
+export type TypeKind = 'roundTypes' | 'questionTypes' | 'scoringStrategies';
+/** The REST aggregates, as plain JSON (docs/design.md, 4). */
+export type QuizAggregate = Record<string, any>;
+export type RoundAggregate = Record<string, any>;
+export type QuestionAggregate = Record<string, any>;
+export interface EvaluateInput {
+    manifests: ServedManifests;
+    quiz?: QuizAggregate;
+    round?: RoundAggregate;
+    /** Extra finding ids to treat as ignored (e.g. the editor's legacy per-browser list). */
+    ignoredWarnings?: string[];
+    /** Extra rule ids muted for the whole subject. */
+    ignoredRules?: string[];
+    /** For manifest messages that come per language. */
+    language?: string;
+}
+export interface ValidationIssue {
+    type: 'question' | 'language' | 'round';
+    /** The location (`R2.Q3`, `Q3`), or for round issues the whole message. */
+    label: string;
+    /** What exactly is wrong (question issues). */
+    detail?: string;
+    roundId?: string;
+    questionId?: string;
+    language?: string;
+    /** Round issues: the round's mode defaults can fill what is missing. */
+    canUseDefaults?: boolean;
+    ruleId?: string;
+    /** The message template (in the asked language) and its values, for consumers with their own translations. */
+    messageKey?: string;
+    messageParams?: Record<string, string | number>;
+}
+export interface Finding {
+    /** `${questionUuid}:${ruleId}`, or `${roundUuid}:group:${groupId}:group-size`. */
+    id: string;
+    ruleId: string;
+    roundId: string;
+    questionId: string;
+    /** Rendered in the asked language. */
+    message: string;
+    /** The template `message` was rendered from. */
+    messageKey: string;
+    messageParams: Record<string, string | number>;
+}
+export type IgnoredBy = 'question' | 'round' | 'quiz' | 'caller';
+export interface IgnoredFinding extends Finding {
+    ignoredBy: IgnoredBy;
+}
+export interface EvaluateResult {
+    errors: ValidationIssue[];
+    /** Warnings in effect. */
+    warnings: Finding[];
+    /** Warnings that fired but are ignored, and by whom. */
+    ignored: IgnoredFinding[];
+}
+export interface RuleDescription {
+    message: string;
+    messageKey: string;
+    messageParams: Record<string, string | number>;
+}

package/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * The served manifests (the part this package reads), the rule vocabulary
+ * and the evaluator's input and output (docs/design.md, 3 and 4).
+ */
+export const COMPARATIVE_KINDS = ['outlier', 'oddOneOut', 'consistency', 'explanationPair', 'optionCountMajority', 'groupSize', 'groupPosition'];
+export const PER_QUESTION_KINDS = ['require', 'settingEquals', 'optionCountOver', 'typeSetting'];