quizwitz-validator 0.1.1 → 0.3.0

package/dist/aggregate.d.ts

@@ -58,3 +58,10 @@ export declare function validGroupId(value: unknown): number | undefined;
  * questions becomes one new group above the highest id.
  */
 export declare function normalizedGroupIds(questions: QuestionAggregate[]): number[];
+/**
+ * A sound setting of an audio/video attachment as the game reads it
+ * (client SoundParameters.parse): `attributes.sound.{key}`, else a legacy
+ * `[key=value]` bracket in the name (key ignoring case). A volume above 1 is
+ * played at 1. Undefined when neither holds a number.
+ */
+export declare function attachmentSoundNumber(attachment: Record<string, any>, key: string): number | undefined;

package/dist/aggregate.js

@@ -145,3 +145,31 @@ export function normalizedGroupIds(questions) {
         return runId;
     });
 }
+/**
+ * A sound setting of an audio/video attachment as the game reads it
+ * (client SoundParameters.parse): `attributes.sound.{key}`, else a legacy
+ * `[key=value]` bracket in the name (key ignoring case). A volume above 1 is
+ * played at 1. Undefined when neither holds a number.
+ */
+export function attachmentSoundNumber(attachment, key) {
+    const read = (value) => {
+        const number = typeof value === 'number' ? value : parseFloat(String(value));
+        return isFinite(number) ? Math.min(1, number) : undefined;
+    };
+    const sound = attachment?.attributes?.sound;
+    if (sound && typeof sound === 'object' && sound[key] !== undefined && sound[key] !== null) {
+        const stored = read(sound[key]);
+        if (stored !== undefined) {
+            return stored;
+        }
+    }
+    let legacy;
+    const name = typeof attachment?.name === 'string' ? attachment.name : '';
+    for (const match of name.match(/\[(.*?)\]/g) ?? []) {
+        const parts = match.substring(1, match.length - 1).split('=');
+        if (parts.length === 2 && parts[0].toLowerCase() === key.toLowerCase()) {
+            legacy = read(parts[1]) ?? legacy;
+        }
+    }
+    return legacy;
+}

package/dist/evaluate.js

@@ -2,7 +2,7 @@ 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, evaluateGroupSize, evaluateOddOneOut, evaluateOptionCountMajority, evaluateOutlier, evaluateRequire, matchesLegacyWarning, matchesOptionCountOver, matchesSettingEquals, matchesTypeSetting, passesCheck, render } from './rules.js';
+import { COMPLETENESS_MESSAGES, evaluateAttachmentVolume, 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})';
@@ -220,6 +220,12 @@ function evaluateRound(catalog, scope, round, roundIndex) {
             case 'groupSize':
                 evaluateGroupSize(rule, ctx).forEach(add);
                 break;
+            case 'groupPosition':
+                evaluateGroupPosition(rule, ctx).forEach(add);
+                break;
+            case 'attachmentVolume':
+                evaluateAttachmentVolume(rule, ctx).forEach(add);
+                break;
             case 'consistency':
                 evaluateConsistency(rule, ctx, quiet).forEach(add);
                 break;

package/dist/rules.d.ts

@@ -1,4 +1,4 @@
-import type { CompletenessRule, ConsistencyRule, ExplanationPairRule, Finding, GroupSizeRule, LegacyWarning, LocalizedText, OddOneOutRule, OptionCountMajorityRule, OptionCountOverRule, OutlierRule, QuestionAggregate, RequireCheck, RequireRule, SettingEqualsRule, SettingsField, TypeSettingRule } from './types.js';
+import type { AttachmentVolumeRule, 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;
@@ -25,6 +25,28 @@ export declare function evaluateOutlier(rule: OutlierRule, ctx: RoundContext): F
 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[];
+/**
+ * A volume gain as the editor's slider shows it: `√gain` as a whole percent
+ * (the sliders are perceptual, docs/design.md 3.4). Also the comparison key,
+ * so gains the author cannot tell apart on the slider count as the same.
+ */
+export declare function volumePercent(gain: number): number;
+/**
+ * One sound setting (`mutedBackgroundVolume`) on the audio/video attachments
+ * of a round's questions: where at least `majority` of the questions with
+ * such attachments (but not all) play every one of them at the same value,
+ * and that value is not the default, the questions with an attachment that
+ * differs or leaves it unset. A round whose majority leaves the setting at
+ * the default is left alone: the few that set it did so on purpose.
+ */
+export declare function evaluateAttachmentVolume(rule: AttachmentVolumeRule, 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[];

package/dist/rules.js

@@ -4,7 +4,7 @@
  * 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 { attachmentSoundNumber, attachmentsOf, 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) {
@@ -144,6 +144,141 @@ export function evaluateGroupSize(rule, ctx) {
     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;
+}
+/**
+ * A volume gain as the editor's slider shows it: `√gain` as a whole percent
+ * (the sliders are perceptual, docs/design.md 3.4). Also the comparison key,
+ * so gains the author cannot tell apart on the slider count as the same.
+ */
+export function volumePercent(gain) {
+    return gain > 0 ? Math.round(Math.sqrt(Math.min(1, gain)) * 100) : 0;
+}
+/**
+ * One sound setting (`mutedBackgroundVolume`) on the audio/video attachments
+ * of a round's questions: where at least `majority` of the questions with
+ * such attachments (but not all) play every one of them at the same value,
+ * and that value is not the default, the questions with an attachment that
+ * differs or leaves it unset. A round whose majority leaves the setting at
+ * the default is left alone: the few that set it did so on purpose.
+ */
+export function evaluateAttachmentVolume(rule, ctx) {
+    const types = rule.types ?? ['audio', 'video'];
+    const excluded = rule.excludeSlots ?? [];
+    const defaultPercent = volumePercent(rule.default);
+    const carriers = [];
+    for (const q of ctx.questions) {
+        const percents = [];
+        const slots = attachmentsOf(q.question);
+        for (const slot of Object.keys(slots)) {
+            const items = slots[slot]?.items;
+            if (excluded.includes(slot) || !Array.isArray(items)) {
+                continue;
+            }
+            for (const attachment of items) {
+                if (attachment && types.includes(attachment.type)) {
+                    const gain = attachmentSoundNumber(attachment, rule.setting);
+                    percents.push(volumePercent(gain ?? rule.default));
+                }
+            }
+        }
+        if (percents.length > 0) {
+            carriers.push({ q, percents });
+        }
+    }
+    if (carriers.length < (rule.minPopulation ?? 4)) {
+        return [];
+    }
+    const tally = new Map();
+    for (const c of carriers) {
+        if (c.percents.every(p => p === c.percents[0])) {
+            tally.set(c.percents[0], (tally.get(c.percents[0]) ?? 0) + 1);
+        }
+    }
+    let expected = defaultPercent;
+    let agreeing = 0;
+    tally.forEach((count, percent) => {
+        if (count > agreeing) {
+            expected = percent;
+            agreeing = count;
+        }
+    });
+    if (expected === defaultPercent || agreeing === carriers.length || agreeing < carriers.length * (rule.majority ?? 0.75)) {
+        return [];
+    }
+    const out = [];
+    for (const c of carriers) {
+        const odd = c.percents.find(p => p !== expected);
+        if (odd === undefined) {
+            continue;
+        }
+        out.push(odd === defaultPercent
+            ? finding(ctx, c.q, rule, rule.messageUnset, { expected: expected + '%' })
+            : finding(ctx, c.q, rule, rule.message, { value: odd + '%', expected: expected + '%' }));
+    }
+    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;

package/dist/types.d.ts

@@ -22,7 +22,7 @@ export interface SettingsField {
     };
     [key: string]: unknown;
 }
-export type RuleKind = 'outlier' | 'oddOneOut' | 'consistency' | 'explanationPair' | 'optionCountMajority' | 'groupSize' | 'require' | 'settingEquals' | 'optionCountOver' | 'typeSetting';
+export type RuleKind = 'outlier' | 'oddOneOut' | 'consistency' | 'explanationPair' | 'optionCountMajority' | 'groupSize' | 'groupPosition' | 'attachmentVolume' | 'require' | 'settingEquals' | 'optionCountOver' | 'typeSetting';
 export declare const COMPARATIVE_KINDS: readonly RuleKind[];
 export declare const PER_QUESTION_KINDS: readonly RuleKind[];
 export type Severity = 'error' | 'warning';
@@ -70,6 +70,26 @@ 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 interface AttachmentVolumeRule extends RuleBase {
+    rule: 'attachmentVolume';
+    /** The sound setting compared: a linear gain under `attributes.sound` (`mutedBackgroundVolume`, `volume`). */
+    setting: string;
+    /** The gain an attachment that does not set it plays at (`mutedBackgroundVolume` 0, `volume` 1). */
+    default: number;
+    /** Attachment types that carry the setting (default `["audio", "video"]`). */
+    types?: string[];
+    /** Question attachment slots left out (`background`). */
+    excludeSlots?: string[];
+    /** For an attachment that leaves the setting at its default. */
+    messageUnset: LocalizedText;
+}
 export type RequireCheck = 'correctOption' | 'allOptionsFilled' | 'answer' | 'imageMap';
 export interface RequireRule extends RuleBase {
     rule: 'require';
@@ -98,7 +118,7 @@ export interface TypeSettingRule extends RuleBase {
         min: number;
     };
 }
-export type FindingRule = OutlierRule | OddOneOutRule | ConsistencyRule | ExplanationPairRule | OptionCountMajorityRule | GroupSizeRule | RequireRule | SettingEqualsRule | OptionCountOverRule | TypeSettingRule;
+export type FindingRule = OutlierRule | OddOneOutRule | ConsistencyRule | ExplanationPairRule | OptionCountMajorityRule | GroupSizeRule | GroupPositionRule | AttachmentVolumeRule | 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 {

package/dist/types.js

@@ -2,5 +2,5 @@
  * 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'];
+export const COMPARATIVE_KINDS = ['outlier', 'oddOneOut', 'consistency', 'explanationPair', 'optionCountMajority', 'groupSize', 'groupPosition', 'attachmentVolume'];
 export const PER_QUESTION_KINDS = ['require', 'settingEquals', 'optionCountOver', 'typeSetting'];

package/docs/design.md

@@ -79,6 +79,8 @@ Messages are **English keys**: the editor translates them with its own catalogue
 | `consistency` | `field` (narration field on the primary resource: `long`, `tips`, `explanation`, `longExplanation`) **or** `slot` (question attachment slot: `before`, `during`, ...), `label`, `minPopulation` (4), `majority` (0.75) | Questions missing what at least `majority` of the round (but not all) has. Param `{field}` or `{slot}` = label. `during` counts as filled by an image map. A gap `explanationPair` already explains is skipped. |
 | `explanationPair` | `fields` (`["longExplanation", "explanation"]`), `labels` (`{field: label}`), `minPopulation` (4), `majority` (0.75) | Among questions that fill either field, the ones using the other half than the majority. Params `{expected, actual}` = labels. |
 | `optionCountMajority` | `types` (question type tokens), `minPopulation` (4), `majority` (0.5) | Same-type siblings (types listed) with a different number of filled options than the strict majority. Params `{count, expected}`. |
+| `groupPosition` | exactly one of `setting` (a numeric question setting: `points`) or `field` (a text on the primary resource: `label`, compared trimmed and ignoring case), `minPopulation` (3, groups), `majority` (0.5) | In a grouped round, the nth question of every group is compared with the nth question of the other groups: where a strict majority of the groups (but not all) agree, the nth questions that differ. Questions without a value (setting not > 0, empty text) are left out. Params `{value, expected, position}` (position from 1). |
+| `attachmentVolume` | `setting` (a sound setting under `attributes.sound`, a linear gain: `mutedBackgroundVolume`), `default` (the gain when unset: 0), `types` (`["audio", "video"]`), `excludeSlots` (`["background"]`), `messageUnset`, `minPopulation` (4, questions), `majority` (0.75) | The audio/video attachments of every question's slots (legacy `[key=value]` name brackets read too). Gains are compared as the editor's perceptual slider shows them (√gain as a whole percent). Where at least `majority` of the questions with such attachments (but not all) play all of them at one value that is not the default, the questions with an attachment that differs: `message` with `{value, expected}`, or `messageUnset` with `{expected}` when it leaves the setting at the default. A round whose majority leaves it at the default gets nothing. |
 | `groupSize` | `minPopulation` (3, groups), `message` (several), `messageSingle` (one question) | In a grouped round, the one group whose size differs when every other group agrees. Id `<roundUuid>:group:<groupId>:group-size`, anchored on the group's first question. Params `{count, expected}`. |
 
 **Per-question kinds** — checked on every question in scope: