quizwitz-validator 0.0.0-stage → 0.2.0

package/dist/evaluate.js

@@ -0,0 +1,287 @@
+import { TypeCatalog } from './catalog.js';
+import { questionSetting, questionTypeToken, questionsOf, normalizedGroupIds, roundName, roundTypeToken, roundsOf } from './aggregate.js';
+import { ignoredBy } from './ignore.js';
+import { questionWarningId } from './ignore.js';
+import { COMPLETENESS_MESSAGES, evaluateConsistency, evaluateExplanationPair, evaluateGroupPosition, evaluateGroupSize, evaluateOddOneOut, evaluateOptionCountMajority, evaluateOutlier, evaluateRequire, matchesLegacyWarning, matchesOptionCountOver, matchesSettingEquals, matchesTypeSetting, passesCheck, render } from './rules.js';
+import { localizedText } from './text.js';
+import { COMPARATIVE_KINDS } from './types.js';
+export const ROUND_INCOMPLETE_MESSAGE = '{round}: scoring settings incomplete ({fields})';
+export const STRATEGY_NOT_OFFERED_MESSAGE = '{round}: this round type does not offer the {strategy} scoring';
+export const QUESTION_TYPE_NOT_OFFERED_MESSAGE = '{location}: this round type does not offer the question type {questionType}';
+export const SCORING_STRATEGY_LABEL = 'Scoring strategy';
+/**
+ * The findings of a quiz or a round: validation issues (errors), the
+ * surprising-settings warnings in effect, and the ones that fired but are
+ * ignored (docs/design.md, 4).
+ */
+export function evaluateFindings(input) {
+    const catalog = new TypeCatalog(input.manifests);
+    const scope = {
+        quiz: input.quiz ?? null,
+        rounds: input.quiz ? roundsOf(input.quiz) : (input.round ? [input.round] : []),
+        singleRound: !input.quiz,
+        language: input.language,
+        ignoredWarnings: input.ignoredWarnings ?? [],
+        ignoredRules: input.ignoredRules ?? []
+    };
+    const errors = [];
+    const warnings = [];
+    const ignored = [];
+    scope.rounds.forEach((round, roundIndex) => {
+        const result = evaluateRound(catalog, scope, round, roundIndex);
+        errors.push(...result.errors);
+        const questions = questionsOf(round);
+        for (const finding of result.warnings) {
+            const question = questions.find(q => q?.uuid === finding.questionId) ?? null;
+            const by = ignoredBy(finding, {
+                round, question, quiz: scope.quiz, ignoredWarnings: scope.ignoredWarnings, ignoredRules: scope.ignoredRules
+            });
+            if (by === null) {
+                warnings.push(finding);
+            }
+            else {
+                ignored.push({ ...finding, ignoredBy: by });
+            }
+        }
+    });
+    return { errors, warnings, ignored };
+}
+function locationLabel(scope, roundIndex, questionIndex) {
+    const question = 'Q' + (questionIndex + 1);
+    return scope.singleRound ? question : roundLabel(scope, roundIndex) + '.' + question;
+}
+function roundLabel(scope, roundIndex) {
+    return scope.singleRound ? 'Round' : 'R' + (roundIndex + 1);
+}
+function questionListsOf(rule) {
+    if (rule.questionList === undefined) {
+        return null;
+    }
+    return Array.isArray(rule.questionList) ? rule.questionList : [rule.questionList];
+}
+function evaluateRound(catalog, scope, round, roundIndex) {
+    const errors = [];
+    const warnings = [];
+    const language = scope.language;
+    const roundToken = catalog.canonical('roundTypes', roundTypeToken(round));
+    const roundEntry = catalog.get('roundTypes', roundToken);
+    const modeIssue = roundModeIssue(catalog, scope, round, roundIndex);
+    if (modeIssue) {
+        errors.push(modeIssue);
+    }
+    const questionList = catalog.questionList(roundToken);
+    if (questionList === 'none') {
+        return { errors, warnings };
+    }
+    const strategyEntry = catalog.get('scoringStrategies', round?.scoringStrategy?.token);
+    const questions = questionsOf(round);
+    const contexts = questions.map((question, index) => {
+        const token = catalog.canonical('questionTypes', questionTypeToken(question));
+        return {
+            question, index, token,
+            uuid: typeof question?.uuid === 'string' ? question.uuid : '',
+            settingsFields: catalog.get('questionTypes', token)?.type.settingsFields ?? []
+        };
+    });
+    // --- errors ---
+    for (const q of contexts) {
+        const entry = catalog.get('questionTypes', q.token);
+        const label = locationLabel(scope, roundIndex, q.index);
+        for (const check of entry?.type.completeness ?? []) {
+            if (!passesCheck(q.question, check)) {
+                const detail = COMPLETENESS_MESSAGES[check] ?? check;
+                errors.push({ type: 'question', label, roundId: round.uuid, questionId: q.uuid, ruleId: 'completeness:' + check, detail, messageKey: detail, messageParams: {} });
+            }
+        }
+        if (roundEntry && entry && !catalog.allowsQuestionType(roundToken, q.token)) {
+            const params = { location: label, questionType: localizedText(entry.type.name, language) || entry.token };
+            const text = render(QUESTION_TYPE_NOT_OFFERED_MESSAGE, params, language);
+            errors.push({ type: 'round', roundId: round.uuid, questionId: q.uuid, label: text.message, messageKey: text.messageKey, messageParams: params });
+        }
+    }
+    // Per-question rules, in scope order: round type, scoring strategy, question type, core.
+    const perQuestionRules = (q) => {
+        const applies = (rule) => {
+            const lists = questionListsOf(rule);
+            return !COMPARATIVE_KINDS.includes(rule.rule) && (lists === null || lists.includes(questionList));
+        };
+        return [
+            ...(roundEntry?.type.findings ?? []).filter(applies).map(rule => ({ rule, source: 'round' })),
+            ...(strategyEntry?.type.findings ?? []).filter(applies).map(rule => ({ rule, source: 'round' })),
+            ...(catalog.get('questionTypes', q.token)?.type.findings ?? []).filter(applies).map(rule => ({ rule, source: 'type' })),
+            ...(catalog.manifests.core?.findings ?? []).filter(applies).map(rule => ({ rule, source: 'core' }))
+        ];
+    };
+    for (const q of contexts) {
+        for (const { rule } of perQuestionRules(q)) {
+            if (rule.rule !== 'require' || (rule.severity ?? 'error') !== 'error') {
+                continue;
+            }
+            const params = evaluateRequire(rule, q);
+            if (params) {
+                const text = render(rule.message, params, language);
+                errors.push({ type: 'question', label: locationLabel(scope, roundIndex, q.index), roundId: round.uuid, questionId: q.uuid, ruleId: rule.id, detail: text.message, messageKey: text.messageKey, messageParams: params });
+            }
+        }
+    }
+    // --- warnings ---
+    // A uuid-less question means the editor refused the entity; its warnings could not be ignored one by one, so the round has none.
+    if (typeof round?.uuid !== 'string' || round.uuid === '' || contexts.some(q => q.uuid === '')) {
+        return { errors, warnings };
+    }
+    const ctx = { roundId: round.uuid, questions: contexts, groupIds: normalizedGroupIds(questions), language };
+    const seen = new Set();
+    const add = (finding) => {
+        if (!seen.has(finding.id)) {
+            seen.add(finding.id);
+            warnings.push(finding);
+        }
+    };
+    const perQuestion = (q, ruleId, text, params) => {
+        add({ id: questionWarningId(q.uuid, ruleId), ruleId, roundId: round.uuid, questionId: q.uuid, ...render(text, params, language) });
+    };
+    for (const q of contexts) {
+        // Legacy setting warnings: the round type's, then the strategy's (a setting the round type already warns about is dropped), then the question type's.
+        const roundRules = roundEntry?.type.questionSettingWarnings ?? [];
+        const roundSettings = new Set(roundRules.map(r => r.setting));
+        const declared = [
+            ...roundRules.map(rule => ({ source: 'round', rule })),
+            ...(strategyEntry?.type.questionSettingWarnings ?? []).filter(r => !roundSettings.has(r.setting)).map(rule => ({ source: 'round', rule })),
+            ...(catalog.get('questionTypes', q.token)?.type.settingWarnings ?? []).map(rule => ({ source: 'type', rule }))
+        ];
+        for (const { source, rule } of declared) {
+            if (questionSetting(q.question, rule.setting) === rule.equals) {
+                perQuestion(q, 'setting:' + source + ':' + rule.setting, rule.message, {});
+            }
+        }
+        // Legacy answer warnings of the question type.
+        (catalog.get('questionTypes', q.token)?.type.warnings ?? []).forEach((warning, i) => {
+            if (matchesLegacyWarning(warning, q)) {
+                perQuestion(q, 'type-warning:' + i, warning.message, {});
+            }
+        });
+        // New per-question kinds.
+        for (const { rule } of perQuestionRules(q)) {
+            switch (rule.rule) {
+                case 'require': {
+                    if ((rule.severity ?? 'error') !== 'warning') {
+                        break;
+                    }
+                    const params = evaluateRequire(rule, q);
+                    if (params) {
+                        perQuestion(q, rule.id, rule.message, params);
+                    }
+                    break;
+                }
+                case 'settingEquals':
+                    if (matchesSettingEquals(rule, q)) {
+                        perQuestion(q, rule.id, rule.message, {});
+                    }
+                    break;
+                case 'optionCountOver':
+                    if (matchesOptionCountOver(rule, q)) {
+                        perQuestion(q, rule.id, rule.message, {});
+                    }
+                    break;
+                case 'typeSetting':
+                    if (matchesTypeSetting(rule, q)) {
+                        perQuestion(q, rule.id, rule.message, {});
+                    }
+                    break;
+            }
+        }
+    }
+    // Comparative rules: round type, scoring strategy, core. The explanation pair goes first: its swaps quiet the consistency gaps they explain.
+    const comparative = [
+        ...(roundEntry?.type.findings ?? []),
+        ...(strategyEntry?.type.findings ?? []),
+        ...(catalog.manifests.core?.findings ?? [])
+    ].filter(rule => {
+        const lists = questionListsOf(rule);
+        return COMPARATIVE_KINDS.includes(rule.rule) && (lists === null || lists.includes(questionList));
+    });
+    const quiet = new Set();
+    for (const rule of comparative) {
+        if (rule.rule === 'explanationPair') {
+            evaluateExplanationPair(rule, ctx, quiet).forEach(add);
+        }
+    }
+    for (const rule of comparative) {
+        switch (rule.rule) {
+            case 'outlier':
+                evaluateOutlier(rule, ctx).forEach(add);
+                break;
+            case 'oddOneOut':
+                evaluateOddOneOut(rule, ctx).forEach(add);
+                break;
+            case 'optionCountMajority':
+                evaluateOptionCountMajority(rule, ctx).forEach(add);
+                break;
+            case 'groupSize':
+                evaluateGroupSize(rule, ctx).forEach(add);
+                break;
+            case 'groupPosition':
+                evaluateGroupPosition(rule, ctx).forEach(add);
+                break;
+            case 'consistency':
+                evaluateConsistency(rule, ctx, quiet).forEach(add);
+                break;
+        }
+    }
+    return { errors, warnings };
+}
+// --- round settings (the editor's round-mode-defaults.ts) ---
+function isMeaningfulDefault(value) {
+    return value !== undefined && value !== null && value !== '';
+}
+function isMissing(value, defaultValue) {
+    if (value === undefined) {
+        return true;
+    }
+    return (value === null || value === '') && isMeaningfulDefault(defaultValue);
+}
+function isVisible(field, bag) {
+    return !field.showWhen || bag[field.showWhen.key] === field.showWhen.equals;
+}
+function missingFields(fields, bag) {
+    return fields.filter(field => isMeaningfulDefault(field.default) && isVisible(field, bag) && isMissing(bag[field.key], field.default));
+}
+/**
+ * A round short of its mode's scoring settings: no (allowed) scoring
+ * strategy, or a manifest field with a default left empty. A strategy the
+ * round type does not allow gets its own sentence. Known round types only.
+ */
+function roundModeIssue(catalog, scope, round, roundIndex) {
+    const roundToken = catalog.canonical('roundTypes', roundTypeToken(round));
+    const roundEntry = catalog.get('roundTypes', roundToken);
+    if (!roundEntry) {
+        return null;
+    }
+    const language = scope.language;
+    const current = round?.scoringStrategy && typeof round.scoringStrategy === 'object' ? round.scoringStrategy : null;
+    const currentToken = typeof current?.token === 'string' && current.token !== '' ? current.token : null;
+    const allowed = catalog.offeredScoringStrategies(roundToken);
+    const invalidStrategy = allowed.length > 0 && (currentToken === null || !catalog.allowsScoringStrategy(roundToken, currentToken));
+    const strategyToken = invalidStrategy ? catalog.pickedScoringStrategy(roundToken) : currentToken;
+    const strategyBag = invalidStrategy ? {} : (current ?? {});
+    const missing = [
+        ...missingFields(catalog.get('scoringStrategies', strategyToken)?.type.settingsFields ?? [], strategyBag),
+        ...missingFields(roundEntry.type.settingsFields ?? [], round?.modeSettings && typeof round.modeSettings === 'object' ? round.modeSettings : {})
+    ];
+    if (!invalidStrategy && missing.length === 0) {
+        return null;
+    }
+    const name = roundName(round) || roundLabel(scope, roundIndex);
+    if (invalidStrategy && currentToken !== null) {
+        const strategy = catalog.get('scoringStrategies', currentToken);
+        const params = { round: name, strategy: localizedText(strategy?.type.name, language) || currentToken };
+        const text = render(STRATEGY_NOT_OFFERED_MESSAGE, params, language);
+        return { type: 'round', roundId: round.uuid, label: text.message, canUseDefaults: true, messageKey: text.messageKey, messageParams: params };
+    }
+    const fields = missing.length > 0
+        ? missing.map(field => localizedText(field.label, language) || field.key)
+        : [SCORING_STRATEGY_LABEL];
+    const params = { round: name, fields: fields.join(', ') };
+    const text = render(ROUND_INCOMPLETE_MESSAGE, params, language);
+    return { type: 'round', roundId: round.uuid, label: text.message, canUseDefaults: true, messageKey: text.messageKey, messageParams: params };
+}

package/dist/ignore.d.ts

@@ -0,0 +1,25 @@
+import type { Finding, IgnoredBy, QuestionAggregate, RoundAggregate } from './types.js';
+/** The ignore key of a per-question finding: `${questionUuid}:${ruleId}`. */
+export declare function questionWarningId(questionUuid: string, ruleId: string): string;
+/** The ignore key of the group-size finding: `${roundUuid}:group:${groupId}:group-size`. */
+export declare function groupSizeWarningId(roundUuid: string, groupId: number | string): string;
+/**
+ * Where ignoring a finding is stored (the entity's `ignoredWarnings`): the
+ * group-size warning on its round, as `group:{groupId}:group-size`; every
+ * other warning on its question, as the rule id.
+ */
+export declare function findingIgnoreTarget(finding: Finding): {
+    entity: 'round' | 'question';
+    key: string;
+};
+/** Whether the finding is ignored on its own entity (the question, or the round for a group). */
+export declare function isIgnoredOnEntity(finding: Finding, round: RoundAggregate | null | undefined, question: QuestionAggregate | null | undefined): boolean;
+export interface IgnoreContext {
+    round?: RoundAggregate | null;
+    question?: QuestionAggregate | null;
+    quiz?: Record<string, any> | null;
+    ignoredWarnings?: string[];
+    ignoredRules?: string[];
+}
+/** Who ignores the finding, or null when it is in effect. */
+export declare function ignoredBy(finding: Finding, context: IgnoreContext): IgnoredBy | null;

package/dist/ignore.js

@@ -0,0 +1,43 @@
+/** The ignore key of a per-question finding: `${questionUuid}:${ruleId}`. */
+export function questionWarningId(questionUuid, ruleId) {
+    return questionUuid + ':' + ruleId;
+}
+/** The ignore key of the group-size finding: `${roundUuid}:group:${groupId}:group-size`. */
+export function groupSizeWarningId(roundUuid, groupId) {
+    return roundUuid + ':group:' + groupId + ':group-size';
+}
+/**
+ * Where ignoring a finding is stored (the entity's `ignoredWarnings`): the
+ * group-size warning on its round, as `group:{groupId}:group-size`; every
+ * other warning on its question, as the rule id.
+ */
+export function findingIgnoreTarget(finding) {
+    if (finding.id.startsWith(finding.roundId + ':')) {
+        return { entity: 'round', key: finding.id.substring(finding.roundId.length + 1) };
+    }
+    return { entity: 'question', key: finding.id.substring(finding.questionId.length + 1) };
+}
+function ignoredWarningsOf(entity) {
+    const list = entity?.ignoredWarnings;
+    return Array.isArray(list) ? list.filter((key) => typeof key === 'string') : [];
+}
+/** Whether the finding is ignored on its own entity (the question, or the round for a group). */
+export function isIgnoredOnEntity(finding, round, question) {
+    const target = findingIgnoreTarget(finding);
+    return target.entity === 'round'
+        ? ignoredWarningsOf(round).includes(target.key)
+        : ignoredWarningsOf(question).includes(target.key);
+}
+/** Who ignores the finding, or null when it is in effect. */
+export function ignoredBy(finding, context) {
+    if (isIgnoredOnEntity(finding, context.round, context.question)) {
+        return findingIgnoreTarget(finding).entity;
+    }
+    if (ignoredWarningsOf(context.quiz).includes(finding.ruleId)) {
+        return 'quiz';
+    }
+    if ((context.ignoredWarnings ?? []).includes(finding.id) || (context.ignoredRules ?? []).includes(finding.ruleId)) {
+        return 'caller';
+    }
+    return null;
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './types.js';
+export { evaluateFindings, ROUND_INCOMPLETE_MESSAGE, STRATEGY_NOT_OFFERED_MESSAGE, QUESTION_TYPE_NOT_OFFERED_MESSAGE, SCORING_STRATEGY_LABEL } from './evaluate.js';
+export { describeRule, guidanceFor, listRules, type DeclaredRule } from './describe.js';
+export { localizedText, interpolate } from './text.js';
+export { questionWarningId, groupSizeWarningId, findingIgnoreTarget, isIgnoredOnEntity, ignoredBy, type IgnoreContext } from './ignore.js';
+export { TypeCatalog, TYPE_KINDS, type CatalogEntry } from './catalog.js';
+export { COMPLETENESS_MESSAGES, passesCheck } from './rules.js';
+export { DEFAULT_QUESTION_SETTINGS, DEFAULT_QUESTION_TYPE, DEFAULT_ROUND_TYPE, questionSetting, typeSettingValue, optionsOf, filledOptionCount, attachmentsOf, imageMapOf, fillsSlot, primaryResource, resourceText, validGroupId, normalizedGroupIds, questionsOf, roundsOf } from './aggregate.js';

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from './types.js';
+export { evaluateFindings, ROUND_INCOMPLETE_MESSAGE, STRATEGY_NOT_OFFERED_MESSAGE, QUESTION_TYPE_NOT_OFFERED_MESSAGE, SCORING_STRATEGY_LABEL } from './evaluate.js';
+export { describeRule, guidanceFor, listRules } from './describe.js';
+export { localizedText, interpolate } from './text.js';
+export { questionWarningId, groupSizeWarningId, findingIgnoreTarget, isIgnoredOnEntity, ignoredBy } from './ignore.js';
+export { TypeCatalog, TYPE_KINDS } from './catalog.js';
+export { COMPLETENESS_MESSAGES, passesCheck } from './rules.js';
+export { DEFAULT_QUESTION_SETTINGS, DEFAULT_QUESTION_TYPE, DEFAULT_ROUND_TYPE, questionSetting, typeSettingValue, optionsOf, filledOptionCount, attachmentsOf, imageMapOf, fillsSlot, primaryResource, resourceText, validGroupId, normalizedGroupIds, questionsOf, roundsOf } from './aggregate.js';

package/dist/rules.d.ts

@@ -0,0 +1,63 @@
+import type { CompletenessRule, ConsistencyRule, ExplanationPairRule, Finding, GroupPositionRule, GroupSizeRule, LegacyWarning, LocalizedText, OddOneOutRule, OptionCountMajorityRule, OptionCountOverRule, OutlierRule, QuestionAggregate, RequireCheck, RequireRule, SettingEqualsRule, SettingsField, TypeSettingRule } from './types.js';
+export interface QuestionContext {
+    question: QuestionAggregate;
+    uuid: string;
+    /** Canonical question type token. */
+    token: string;
+    index: number;
+    /** The type's settings fields, for type-setting defaults. */
+    settingsFields: SettingsField[];
+}
+export interface RoundContext {
+    roundId: string;
+    questions: QuestionContext[];
+    /** Normalised group id per question (index-aligned). */
+    groupIds: number[];
+    language?: string;
+}
+export interface RenderedMessage {
+    message: string;
+    messageKey: string;
+    messageParams: Record<string, string | number>;
+}
+export declare function render(text: LocalizedText, params: Record<string, string | number>, language?: string): RenderedMessage;
+export declare function evaluateOutlier(rule: OutlierRule, ctx: RoundContext): Finding[];
+export declare function evaluateOddOneOut(rule: OddOneOutRule, ctx: RoundContext): Finding[];
+export declare function evaluateOptionCountMajority(rule: OptionCountMajorityRule, ctx: RoundContext): Finding[];
+export declare function evaluateGroupSize(rule: GroupSizeRule, ctx: RoundContext): Finding[];
+/**
+ * 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 declare function evaluateGroupPosition(rule: GroupPositionRule, ctx: RoundContext): Finding[];
+/** Explanation swaps; `quiet` names the `questionUuid:field` gaps the swap explains, for the consistency rules. */
+export declare function evaluateExplanationPair(rule: ExplanationPairRule, ctx: RoundContext, quiet: Set<string>): Finding[];
+export declare function evaluateConsistency(rule: ConsistencyRule, ctx: RoundContext, quiet: Set<string>): Finding[];
+/** The completeness checks by name (the editor's QuestionTypeDescriptor.checkRule). */
+export declare function passesCheck(question: QuestionAggregate, check: RequireCheck | CompletenessRule): boolean;
+/** What a failed `require` reports, or null when it passes. */
+export declare function evaluateRequire(rule: RequireRule, q: QuestionContext): Record<string, string | number> | null;
+export declare function matchesSettingEquals(rule: SettingEqualsRule | {
+    setting: string;
+    equals: unknown;
+}, q: QuestionContext): boolean;
+export declare function matchesOptionCountOver(rule: OptionCountOverRule | {
+    optionsOver: number;
+    settingFalse: string;
+}, q: QuestionContext): boolean;
+export declare function matchesTypeSetting(rule: TypeSettingRule | {
+    typeSetting: {
+        key: string;
+        equals: unknown;
+    };
+    typeSettingBelow: {
+        key: string;
+        min: number;
+    };
+}, q: QuestionContext): boolean;
+/** A legacy `warnings` entry of a question type (optionsOver / typeSetting shapes). */
+export declare function matchesLegacyWarning(warning: LegacyWarning, q: QuestionContext): boolean;
+/** The English detail of a failed completeness rule. */
+export declare const COMPLETENESS_MESSAGES: Record<CompletenessRule, string>;