quizwitz-validator 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,58 @@
-# Temporary Holding Version
+# quizwitz-validator
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Evaluates the **findings** of a QuizWitz quiz or round: validation issues
+(errors) and surprising-settings warnings, as the game client's type
+manifests declare them. One evaluator for the quiz editor
+(`quizwitz-social`) and the MCP server (`quizwitz-mcp`), so both agree and
+every rule is data in `client.quizwitz.com` (`types/manifests.json`), where
+mods declare their own.
+
+Design, schema and rule vocabulary: [docs/design.md](docs/design.md).
+
+## Install
+
+```
+npm install quizwitz-validator
+```
+
+`dist/` is committed: no build step on install. ESM, TypeScript types
+included, no runtime dependencies, no DOM, Node 20+.
+
+## Use
+
+```ts
+import { evaluateFindings, describeRule, guidanceFor } from 'quizwitz-validator';
+
+const manifests = await (await fetch(gameClient + '/types/manifests.json')).json();
+const { errors, warnings, ignored } = evaluateFindings({
+    manifests,
+    quiz,                     // or round: the REST aggregate, as plain JSON
+    ignoredWarnings: [...],   // optional: extra finding ids to treat as ignored
+    ignoredRules: [...],      // optional: extra rule ids muted for the whole subject
+    language: 'nl'            // optional: for manifest messages per language
+});
+
+describeRule(manifests, 'odd:hideQuestion');          // the rule in one line, for an "ignored checks" list
+guidanceFor(manifests, 'roundTypes', 'mod-betting');  // prose on what makes a good round of this type
+```
+
+- `errors`: `ValidationIssue[]` (`type`, `label`, `detail`, `roundId`, `questionId`, `canUseDefaults`, `ruleId`, `messageKey`, `messageParams`).
+- `warnings`: `Finding[]` in effect (`id`, `ruleId`, `roundId`, `questionId`, `message`, `messageKey`, `messageParams`).
+- `ignored`: the findings that fired but are ignored, with `ignoredBy` (`question`, `round`, `quiz`, `caller`).
+
+Ids and ignore keys are the editor's: `${questionUuid}:${ruleId}` and
+`${roundUuid}:group:${groupId}:group-size` (`questionWarningId`,
+`groupSizeWarningId`, `findingIgnoreTarget`).
+
+## Develop
+
+```
+npm install
+npm test          # unit tests + every fixture (committed copy, and the game client checkout when it is next to this repo)
+npm run verify    # typecheck, build dist/, test
+```
+
+The fixtures (`fixtures/findings-fixtures.json`) are a copy of the game
+client's served `types/findings-fixtures.json`; refresh the copy when the
+game client's rules change. Build `dist/` (`npm run build`) and commit it
+before tagging a release.

package/dist/aggregate.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Readers for the REST aggregates (quiz, round, question) as plain JSON:
+ * per-language content in `resources[]`, flat play settings on the question,
+ * options under the resource, attachments as `{timing: {items}}`, the image
+ * map as an image attachment in option 1's `during` slot. Defaults are the
+ * editor's (DEFAULT_QUESTION_SETTINGS), applied the way it applies them on
+ * load.
+ */
+import type { QuestionAggregate, QuizAggregate, RoundAggregate } from './types.js';
+export declare const DEFAULT_QUESTION_SETTINGS: Record<string, unknown>;
+export declare const DEFAULT_QUESTION_TYPE = "multiplechoice";
+export declare const DEFAULT_ROUND_TYPE = "trivia";
+/** The type settings the API also keeps in question columns. */
+export declare const COLUMN_TYPE_SETTINGS: readonly string[];
+export declare function roundsOf(quiz: QuizAggregate | null | undefined): RoundAggregate[];
+export declare function questionsOf(round: RoundAggregate | null | undefined): QuestionAggregate[];
+/** The original-language resource: the one whose language is `original_language`, else the first. */
+export declare function primaryResource(entity: Record<string, any> | null | undefined): Record<string, any> | null;
+/** Trimmed text of a resource field (`text` is the question text, stored as `name`). */
+export declare function resourceText(entity: Record<string, any>, field: string): string;
+export declare function roundName(round: RoundAggregate): string;
+export declare function questionTypeToken(question: QuestionAggregate): string;
+export declare function roundTypeToken(round: RoundAggregate): string;
+/** A play setting as the editor reads it: the flat field, else `settings.{key}`, else the default. */
+export declare function questionSetting(question: QuestionAggregate, key: string): unknown;
+/** A type setting: `typeSettings`, else the question's own column for the ones the API keeps flat. */
+export declare function typeSettingValue(question: QuestionAggregate, key: string): unknown;
+export interface Option {
+    text: string;
+    correct: boolean;
+    raw: Record<string, any>;
+}
+export declare function optionsOf(question: QuestionAggregate): Option[];
+export declare function filledOptionCount(question: QuestionAggregate): number;
+/** The attachments map `{timing: {items}}`; attachments are language-agnostic, the primary resource holds them. */
+export declare function attachmentsOf(entity: Record<string, any>): Record<string, {
+    items: any[];
+}>;
+export interface ImageMap {
+    points: {
+        kind?: string;
+        [key: string]: unknown;
+    }[];
+}
+/**
+ * The image map: an image attachment in the `during` slot of the first
+ * option (the editor's storage), or a flat `imageMap` snapshot. Null when
+ * there is none.
+ */
+export declare function imageMapOf(question: QuestionAggregate): ImageMap | null;
+/** Whether the question shows or plays anything in a slot; an image map counts as `during`. */
+export declare function fillsSlot(question: QuestionAggregate, slot: string): boolean;
+/** A question's `group` as a usable id: a positive integer, also as the numeric string the API returns. */
+export declare function validGroupId(value: unknown): number | undefined;
+/**
+ * The group id of every question, normalised as the editor does on load
+ * (TranslatedRound.normalizeQuestionGroups): a run of consecutive ungrouped
+ * questions becomes one new group above the highest id.
+ */
+export declare function normalizedGroupIds(questions: QuestionAggregate[]): number[];

package/dist/aggregate.js

@@ -0,0 +1,147 @@
+export const DEFAULT_QUESTION_SETTINGS = {
+    points: 1000,
+    duration: 30,
+    randomizeOptions: true,
+    multipleCorrect: false,
+    skipOnAllAnswered: true,
+    showResults: true,
+    timeBasedScoring: true,
+    forceImmediateResults: false,
+    hideQuestion: false,
+    playTimerMusic: null,
+    autoJudge: null
+};
+export const DEFAULT_QUESTION_TYPE = 'multiplechoice';
+export const DEFAULT_ROUND_TYPE = 'trivia';
+/** The type settings the API also keeps in question columns. */
+export const COLUMN_TYPE_SETTINGS = ['minAnswers', 'maxAnswers', 'scoreStrategy'];
+export function roundsOf(quiz) {
+    const items = quiz?.rounds?.items;
+    return Array.isArray(items) ? items : [];
+}
+export function questionsOf(round) {
+    const items = round?.questions?.items;
+    return Array.isArray(items) ? items : [];
+}
+/** The original-language resource: the one whose language is `original_language`, else the first. */
+export function primaryResource(entity) {
+    const resources = entity?.resources;
+    if (!Array.isArray(resources) || resources.length === 0) {
+        return null;
+    }
+    const original = entity?.original_language;
+    return resources.find(r => r && r.language === original) ?? resources[0] ?? null;
+}
+/** Trimmed text of a resource field (`text` is the question text, stored as `name`). */
+export function resourceText(entity, field) {
+    const key = field === 'text' ? 'name' : field;
+    const value = primaryResource(entity)?.[key];
+    return typeof value === 'string' ? value.trim() : '';
+}
+export function roundName(round) {
+    return resourceText(round, 'name');
+}
+export function questionTypeToken(question) {
+    const token = question?.mode?.token;
+    return typeof token === 'string' && token !== '' ? token : DEFAULT_QUESTION_TYPE;
+}
+export function roundTypeToken(round) {
+    const token = round?.mode?.token;
+    return typeof token === 'string' && token !== '' ? token : DEFAULT_ROUND_TYPE;
+}
+/** A play setting as the editor reads it: the flat field, else `settings.{key}`, else the default. */
+export function questionSetting(question, key) {
+    const flat = question?.[key];
+    if (flat !== undefined && flat !== null) {
+        return flat;
+    }
+    const nested = question?.settings?.[key];
+    if (nested !== undefined && nested !== null) {
+        return nested;
+    }
+    return key in DEFAULT_QUESTION_SETTINGS ? DEFAULT_QUESTION_SETTINGS[key] : undefined;
+}
+/** A type setting: `typeSettings`, else the question's own column for the ones the API keeps flat. */
+export function typeSettingValue(question, key) {
+    const stored = question?.typeSettings && !Array.isArray(question.typeSettings) ? question.typeSettings[key] : undefined;
+    if (stored !== undefined && stored !== null) {
+        return stored;
+    }
+    const flat = COLUMN_TYPE_SETTINGS.includes(key) ? question?.[key] : undefined;
+    return flat !== undefined && flat !== null ? flat : undefined;
+}
+export function optionsOf(question) {
+    const items = primaryResource(question)?.options?.items;
+    if (!Array.isArray(items)) {
+        return [];
+    }
+    return items.filter(item => item && typeof item === 'object').map(item => ({
+        text: typeof item.text === 'string' ? item.text : '',
+        correct: item.correct === true,
+        raw: item
+    }));
+}
+export function filledOptionCount(question) {
+    return optionsOf(question).filter(o => o.text.trim().length > 0).length;
+}
+/** The attachments map `{timing: {items}}`; attachments are language-agnostic, the primary resource holds them. */
+export function attachmentsOf(entity) {
+    const map = primaryResource(entity)?.attachments ?? entity?.attachments;
+    return map && typeof map === 'object' && !Array.isArray(map) ? map : {};
+}
+/**
+ * The image map: an image attachment in the `during` slot of the first
+ * option (the editor's storage), or a flat `imageMap` snapshot. Null when
+ * there is none.
+ */
+export function imageMapOf(question) {
+    const flat = question?.imageMap;
+    if (flat && typeof flat === 'object' && Array.isArray(flat.points)) {
+        return { points: flat.points };
+    }
+    const during = optionsOf(question)[0]?.raw?.attachments?.during?.items;
+    if (!Array.isArray(during)) {
+        return null;
+    }
+    const image = during.find(a => a && a.type === 'image');
+    if (!image) {
+        return null;
+    }
+    const points = image.attributes?.points;
+    return { points: Array.isArray(points) ? points : [] };
+}
+/** Whether the question shows or plays anything in a slot; an image map counts as `during`. */
+export function fillsSlot(question, slot) {
+    const items = attachmentsOf(question)[slot]?.items;
+    return (Array.isArray(items) && items.length > 0) || (slot === 'during' && imageMapOf(question) !== null);
+}
+/** A question's `group` as a usable id: a positive integer, also as the numeric string the API returns. */
+export function validGroupId(value) {
+    if (value === undefined || value === null || value === '') {
+        return undefined;
+    }
+    const parsed = typeof value === 'number' ? value : parseInt(String(value), 10);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+/**
+ * The group id of every question, normalised as the editor does on load
+ * (TranslatedRound.normalizeQuestionGroups): a run of consecutive ungrouped
+ * questions becomes one new group above the highest id.
+ */
+export function normalizedGroupIds(questions) {
+    const ids = questions.map(q => validGroupId(q?.group));
+    let max = ids.reduce((m, id) => (id !== undefined && id > m ? id : m), 0);
+    let runId = null;
+    let prevUngrouped = false;
+    return ids.map(id => {
+        if (id !== undefined) {
+            prevUngrouped = false;
+            return id;
+        }
+        if (!(prevUngrouped && runId !== null)) {
+            runId = ++max;
+        }
+        prevUngrouped = true;
+        return runId;
+    });
+}

package/dist/catalog.d.ts

@@ -0,0 +1,38 @@
+import type { QuestionTypeEntry, RoundTypeEntry, ScoringStrategyEntry, ServedManifests, TypeKind, TypeManifest } from './types.js';
+export interface EntryByKind {
+    roundTypes: RoundTypeEntry;
+    questionTypes: QuestionTypeEntry;
+    scoringStrategies: ScoringStrategyEntry;
+}
+export interface CatalogEntry<K extends TypeKind = TypeKind> {
+    token: string;
+    type: EntryByKind[K];
+    /** The mod's manifest, or null for a core type. */
+    mod: TypeManifest | null;
+}
+export declare const TYPE_KINDS: readonly TypeKind[];
+/**
+ * The types of one served manifests file, by kind: a port of the game's
+ * TypeCatalog lookups the rules need (tokens ignore case, aliases resolve,
+ * core first, a token already taken is not learned twice).
+ */
+export declare class TypeCatalog {
+    readonly manifests: ServedManifests;
+    private readonly names;
+    private readonly entries;
+    constructor(manifests: ServedManifests);
+    private learn;
+    canonical(kind: TypeKind, token: unknown): string | null;
+    get<K extends TypeKind>(kind: K, token: unknown): CatalogEntry<K> | null;
+    all<K extends TypeKind>(kind: K): CatalogEntry<K>[];
+    private listAllows;
+    /** D12: the round type allows the question type (absent: all) and the question type accepts the round type (absent: none). */
+    allowsQuestionType(roundToken: unknown, questionToken: unknown): boolean;
+    /** Allowed by the round type, supported by the strategy, not listed as unsupported. Hidden is not checked. */
+    allowsScoringStrategy(roundToken: unknown, strategyToken: unknown): boolean;
+    /** The strategies offered for a round type: allowed, supported and not hidden. */
+    offeredScoringStrategies(roundToken: unknown): string[];
+    /** What a new round of this type scores with: its default, else the first allowed, else `default`; a hidden default reads as `default`. */
+    pickedScoringStrategy(roundToken: unknown): string;
+    questionList(roundToken: unknown): 'list' | 'grouped' | 'none';
+}

package/dist/catalog.js

@@ -0,0 +1,110 @@
+export const TYPE_KINDS = ['roundTypes', 'questionTypes', 'scoringStrategies'];
+/**
+ * The types of one served manifests file, by kind: a port of the game's
+ * TypeCatalog lookups the rules need (tokens ignore case, aliases resolve,
+ * core first, a token already taken is not learned twice).
+ */
+export class TypeCatalog {
+    manifests;
+    names = { roundTypes: new Map(), questionTypes: new Map(), scoringStrategies: new Map() };
+    entries = { roundTypes: new Map(), questionTypes: new Map(), scoringStrategies: new Map() };
+    constructor(manifests) {
+        this.manifests = manifests;
+        for (const kind of TYPE_KINDS) {
+            for (const type of manifests.core?.[kind] ?? []) {
+                this.learn(kind, type, null);
+            }
+        }
+        for (const mod of manifests.mods ?? []) {
+            for (const kind of TYPE_KINDS) {
+                for (const type of mod?.[kind] ?? []) {
+                    this.learn(kind, type, mod);
+                }
+            }
+        }
+    }
+    learn(kind, type, mod) {
+        if (!type || typeof type.token !== 'string' || type.token === '') {
+            return;
+        }
+        const token = type.token.toLowerCase();
+        if (this.names[kind].has(token)) {
+            return;
+        }
+        this.names[kind].set(token, token);
+        this.entries[kind].set(token, { token, type, mod });
+        for (const alias of type.aliases ?? []) {
+            const key = String(alias).toLowerCase();
+            if (!this.names[kind].has(key)) {
+                this.names[kind].set(key, token);
+            }
+        }
+    }
+    canonical(kind, token) {
+        if (token === null || token === undefined) {
+            return null;
+        }
+        const key = String(token).trim().toLowerCase();
+        return key === '' ? null : (this.names[kind].get(key) ?? key);
+    }
+    get(kind, token) {
+        const key = this.canonical(kind, token);
+        return key === null ? null : this.entries[kind].get(key) ?? null;
+    }
+    all(kind) {
+        return [...this.entries[kind].values()];
+    }
+    listAllows(list, kind, token) {
+        if (list === undefined || list === '*') {
+            return true;
+        }
+        return Array.isArray(list) && list.some(item => this.canonical(kind, item) === token);
+    }
+    /** D12: the round type allows the question type (absent: all) and the question type accepts the round type (absent: none). */
+    allowsQuestionType(roundToken, questionToken) {
+        const round = this.get('roundTypes', roundToken);
+        const question = this.get('questionTypes', questionToken);
+        if (!round || !question) {
+            return false;
+        }
+        return this.listAllows(round.type.allowedQuestionTypes, 'questionTypes', question.token)
+            && question.type.addToRounds !== undefined
+            && this.listAllows(question.type.addToRounds, 'roundTypes', round.token);
+    }
+    /** Allowed by the round type, supported by the strategy, not listed as unsupported. Hidden is not checked. */
+    allowsScoringStrategy(roundToken, strategyToken) {
+        const round = this.get('roundTypes', roundToken);
+        const strategy = this.get('scoringStrategies', strategyToken);
+        if (!round || !strategy) {
+            return false;
+        }
+        const unsupported = strategy.type.unsupportedRoundTypes;
+        return this.listAllows(round.type.allowedScoringStrategies, 'scoringStrategies', strategy.token)
+            && this.listAllows(strategy.type.supportedRoundTypes, 'roundTypes', round.token)
+            && !(Array.isArray(unsupported) && unsupported.some(t => this.canonical('roundTypes', t) === round.token));
+    }
+    /** The strategies offered for a round type: allowed, supported and not hidden. */
+    offeredScoringStrategies(roundToken) {
+        return this.all('scoringStrategies')
+            .filter(s => s.type.hidden !== true && this.allowsScoringStrategy(roundToken, s.token))
+            .map(s => s.token);
+    }
+    /** What a new round of this type scores with: its default, else the first allowed, else `default`; a hidden default reads as `default`. */
+    pickedScoringStrategy(roundToken) {
+        const round = this.get('roundTypes', roundToken);
+        let token = 'default';
+        if (round) {
+            if (typeof round.type.defaultScoringStrategy === 'string') {
+                token = this.canonical('scoringStrategies', round.type.defaultScoringStrategy);
+            }
+            else if (Array.isArray(round.type.allowedScoringStrategies) && round.type.allowedScoringStrategies.length > 0) {
+                token = this.canonical('scoringStrategies', round.type.allowedScoringStrategies[0]);
+            }
+        }
+        return this.get('scoringStrategies', token)?.type.hidden === true ? 'default' : token;
+    }
+    questionList(roundToken) {
+        const list = this.get('roundTypes', roundToken)?.type.questionList;
+        return list === 'grouped' || list === 'none' ? list : 'list';
+    }
+}

package/dist/describe.d.ts

@@ -0,0 +1,19 @@
+import type { FindingRule, RuleDescription, ServedManifests, TypeKind } from './types.js';
+export interface DeclaredRule {
+    rule: FindingRule;
+    /** Where it is declared: the core manifest's root, or a type. */
+    scope: {
+        kind: TypeKind;
+        token: string;
+    } | 'core';
+}
+/** Every rule the manifests declare, root first, then per type in manifest order. */
+export declare function listRules(manifests: ServedManifests): DeclaredRule[];
+/**
+ * A rule id in one line, for the "ignored checks" list: the rule's
+ * `description` (its message without values), with fallbacks for the ids
+ * the legacy fields produce.
+ */
+export declare function describeRule(manifests: ServedManifests, ruleId: string, language?: string): RuleDescription;
+/** The guidance text of a type, in `language`; empty when it has none or is unknown. */
+export declare function guidanceFor(manifests: ServedManifests, kind: TypeKind, token: string, language?: string): string;

package/dist/describe.js

@@ -0,0 +1,71 @@
+import { TypeCatalog, TYPE_KINDS } from './catalog.js';
+import { COMPLETENESS_MESSAGES, render } from './rules.js';
+import { localizedText } from './text.js';
+/** Every rule the manifests declare, root first, then per type in manifest order. */
+export function listRules(manifests) {
+    const out = [];
+    for (const rule of manifests.core?.findings ?? []) {
+        out.push({ rule, scope: 'core' });
+    }
+    for (const manifest of [manifests.core, ...(manifests.mods ?? [])]) {
+        for (const kind of TYPE_KINDS) {
+            for (const type of manifest?.[kind] ?? []) {
+                for (const rule of type.findings ?? []) {
+                    out.push({ rule, scope: { kind, token: type.token } });
+                }
+            }
+        }
+    }
+    return out;
+}
+function paramsOf(rule) {
+    switch (rule.rule) {
+        case 'oddOneOut':
+            return { setting: rule.label ?? rule.setting };
+        case 'consistency':
+            return rule.field !== undefined ? { field: rule.label ?? rule.field } : { slot: rule.label ?? rule.slot };
+        case 'require':
+            return rule.field !== undefined ? { field: rule.field } : rule.setting !== undefined ? { setting: rule.setting } : { check: rule.check };
+        default:
+            return {};
+    }
+}
+/** The label of a setting as an oddOneOut rule names it, else the key. */
+function settingLabel(manifests, key) {
+    const rule = listRules(manifests).find(d => d.rule.rule === 'oddOneOut' && d.rule.setting === key)?.rule;
+    return rule && rule.rule === 'oddOneOut' ? (rule.label ?? key) : key;
+}
+/**
+ * A rule id in one line, for the "ignored checks" list: the rule's
+ * `description` (its message without values), with fallbacks for the ids
+ * the legacy fields produce.
+ */
+export function describeRule(manifests, ruleId, language) {
+    const declared = listRules(manifests).find(d => d.rule.id === ruleId)?.rule;
+    if (declared) {
+        return render(declared.description ?? declared.message, paramsOf(declared), language);
+    }
+    if (ruleId.startsWith('setting:')) {
+        const key = ruleId.substring(ruleId.indexOf(':', 'setting:'.length) + 1);
+        const params = { setting: settingLabel(manifests, key) };
+        return render(ruleId.startsWith('setting:round:')
+            ? 'Question with {setting} in a round type that advises against it'
+            : 'Question type that advises against {setting}', params, language);
+    }
+    if (ruleId.startsWith('completeness:')) {
+        const check = ruleId.substring('completeness:'.length);
+        return render(COMPLETENESS_MESSAGES[check] ?? check, {}, language);
+    }
+    if (ruleId.startsWith('type-warning:')) {
+        return render('Warning the question type gives on its answer options', {}, language);
+    }
+    if (ruleId.startsWith('odd:')) {
+        return render('Only question with {setting} switched on or off', { setting: settingLabel(manifests, ruleId.substring('odd:'.length)) }, language);
+    }
+    return render(ruleId, {}, language);
+}
+/** The guidance text of a type, in `language`; empty when it has none or is unknown. */
+export function guidanceFor(manifests, kind, token, language) {
+    const entry = new TypeCatalog(manifests).get(kind, token);
+    return localizedText(entry?.type.guidance, language);
+}

package/dist/evaluate.d.ts

@@ -0,0 +1,11 @@
+import type { EvaluateInput, EvaluateResult } from './types.js';
+export declare const ROUND_INCOMPLETE_MESSAGE = "{round}: scoring settings incomplete ({fields})";
+export declare const STRATEGY_NOT_OFFERED_MESSAGE = "{round}: this round type does not offer the {strategy} scoring";
+export declare const QUESTION_TYPE_NOT_OFFERED_MESSAGE = "{location}: this round type does not offer the question type {questionType}";
+export declare 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 declare function evaluateFindings(input: EvaluateInput): EvaluateResult;