@datamoc/mw_games 0.42.0 → 0.44.2

package/dist/mwl/package-document.js

@@ -0,0 +1,639 @@
+import JSON5 from 'json5';
+import { checkConditionSyntax } from './conditions.js';
+import { preprocess } from './grammar.js';
+import { checkPackagePath, PackageFormatError } from './package-container.js';
+/**
+ * The `kind` values an `asset` tag accepts.
+ *
+ * @example
+ * ```ts
+ * import { PACKAGE_ASSET_KINDS } from '@datamoc/mw_games/mwl';
+ *
+ * console.log(PACKAGE_ASSET_KINDS.includes('synth-patch')); // true
+ * ```
+ */
+export const PACKAGE_ASSET_KINDS = [
+    'image',
+    'audio',
+    'music',
+    'font',
+    'data',
+    'synth-patch',
+];
+/**
+ * Kinds that are somebody's creative work: `license` and `source` are mandatory for these.
+ *
+ * @example
+ * ```ts
+ * import { PACKAGE_MEDIA_KINDS } from '@datamoc/mw_games/mwl';
+ *
+ * console.log(PACKAGE_MEDIA_KINDS.includes('data')); // false
+ * ```
+ */
+export const PACKAGE_MEDIA_KINDS = ['image', 'audio', 'music', 'font'];
+/**
+ * The MWL tags a package document may hold, and the only ones. Standard game tags (`unit_type`,
+ * `event`, ...) are refused in a package: a character expands into them, and keeping the two
+ * apart means nothing in a shared file can reach the rules of the game it is dropped into.
+ *
+ * @example
+ * ```ts
+ * import { PACKAGE_TAGS } from '@datamoc/mw_games/mwl';
+ *
+ * console.log(PACKAGE_TAGS.includes('character')); // true
+ * ```
+ */
+export const PACKAGE_TAGS = [
+    'package',
+    'asset',
+    'character',
+    'animation',
+    'sound_effect',
+    'music',
+    'script',
+    'import',
+];
+/**
+ * The event vocabulary a package script may `do`. It is the data-only subset of the MWL event
+ * actions plus `play` and `give`; `hook` (game-author code), `endlevel`, `win`, `lose`,
+ * `spawn`, `kill` and anything else that decides the outcome of a scenario are not on it.
+ *
+ * @example
+ * ```ts
+ * import { PACKAGE_SCRIPT_ACTIONS } from '@datamoc/mw_games/mwl';
+ *
+ * console.log(PACKAGE_SCRIPT_ACTIONS.includes('hook')); // false
+ * ```
+ */
+export const PACKAGE_SCRIPT_ACTIONS = [
+    'message',
+    'say',
+    'play',
+    'give',
+    'set_variable',
+    'gold',
+    'heal_unit',
+    'fire_event',
+];
+/**
+ * The capabilities mwg itself knows how to grant; a package may name others, a policy decides.
+ *
+ * @example
+ * ```ts
+ * import { KNOWN_PACKAGE_CAPABILITIES } from '@datamoc/mw_games/mwl';
+ *
+ * console.log(KNOWN_PACKAGE_CAPABILITIES); // ['audio', 'script']
+ * ```
+ */
+export const KNOWN_PACKAGE_CAPABILITIES = ['audio', 'script'];
+const ID = /^[A-Za-z_][\w.-]*$/;
+const VERSION = /^\d+\.\d+\.\d+(?:[-+][\w.+-]*)?$/;
+const MAX_FRAMES = 4096;
+const MAX_CODE = 65536;
+const MAX_CONDITION = 512;
+const MAX_ACTIONS = 64;
+const MAX_JSON_DEPTH = 16;
+const MAX_IMPORT_DEPTH = 4;
+/** every import read counts, so a fan-out of repeated imports cannot multiply within the depth bound */
+const MAX_IMPORT_READS = 64;
+/**
+ * Reads a package document: the MWL tags `package`, `asset`, `character`, `animation`,
+ * `sound_effect`, `music`, `script` and `import`, into plain typed data. Macros and
+ * `#include`s are expanded first, as for any MWL file. Nothing is executed: a script's `when` is
+ * only checked for syntax and its `do` only for membership of the safe vocabulary.
+ *
+ * `character` is a macro, not a compiled type of its own: it stays one record here and expands
+ * into a `unit_type` (plus the animations, effects and scripts it names) when merged. A new
+ * compiled table would need its own schema, validator and loader beside the one `unit_type`
+ * already has; the macro reuses all of them, and the fields only a renderer or a player of
+ * sound reads (portrait, sprite, theme) have no consumer in the rules core anyway.
+ *
+ * @example
+ * ```ts
+ * import { parsePackageDocument } from '@datamoc/mw_games/mwl';
+ *
+ * const document = parsePackageDocument(
+ *   "[{ tag: 'package', id: 'marta', version: '1.0.0' }, { tag: 'character', id: 'marta', hitpoints: 28 }]",
+ * );
+ * console.log(document.characters[0]?.stats.hitpoints); // 28
+ * ```
+ */
+export function parsePackageDocument(source, options = {}) {
+    const sections = emptySections();
+    readInto(sections, source, options, 0, '', { reads: 0 });
+    if (!sections.meta)
+        throw new PackageFormatError(`${options.file ?? 'package'}: needs a [package] tag`);
+    return finish(sections, sections.meta);
+}
+function emptySections() {
+    return {
+        assets: [],
+        characters: [],
+        animations: [],
+        soundEffects: [],
+        music: [],
+        scripts: [],
+        imports: [],
+        messages: new Set(),
+    };
+}
+function finish(sections, meta) {
+    return {
+        meta,
+        assets: sections.assets,
+        characters: sections.characters,
+        animations: sections.animations,
+        soundEffects: sections.soundEffects,
+        music: sections.music,
+        scripts: sections.scripts,
+        imports: sections.imports,
+        messages: [...sections.messages].sort(),
+    };
+}
+/** parses one source into `sections`; a file `import` recurses with a prefix and a depth bound */
+function readInto(sections, source, options, depth, prefix, budget) {
+    const file = options.file ?? 'package.mwl';
+    const fail = (message) => {
+        throw new PackageFormatError(`${file}: ${message}`);
+    };
+    let value;
+    try {
+        value = JSON5.parse(preprocess(source, options));
+    }
+    catch (error) {
+        return fail(error instanceof Error ? error.message : String(error));
+    }
+    if (!Array.isArray(value))
+        return fail('a package document is a top-level array of nodes');
+    const text = (raw, where) => {
+        if (typeof raw === 'string')
+            return raw;
+        const gettext = raw?.$gettext;
+        if (typeof gettext === 'string' && Object.keys(raw).length === 1) {
+            sections.messages.add(gettext);
+            return gettext;
+        }
+        return fail(`${where} must be a string or _("...")`);
+    };
+    const plain = (raw, where) => {
+        if (typeof raw !== 'string')
+            return fail(`${where} must be a string`);
+        return raw;
+    };
+    const idOf = (raw, where) => {
+        if (typeof raw !== 'string' || !ID.test(raw))
+            return fail(`${where} must be an id (letters, digits, _ . -)`);
+        return raw;
+    };
+    const finite = (raw, where) => {
+        if (typeof raw !== 'number' || !Number.isFinite(raw))
+            return fail(`${where} must be a number`);
+        return raw;
+    };
+    const record = (raw, where) => {
+        if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+            return fail(`${where} must be an object`);
+        return raw;
+    };
+    const only = (body, allowed, where) => {
+        for (const key of Object.keys(body))
+            if (!allowed.includes(key))
+                fail(`${where}: unknown field "${key}"`);
+    };
+    const unique = (list, id, where) => {
+        if (list.some((item) => item.id === id))
+            fail(`${where}: duplicate id "${id}"`);
+    };
+    const local = (id) => (prefix ? `${prefix}.${id}` : id);
+    const json = (raw, where, level = 0) => {
+        if (level > MAX_JSON_DEPTH)
+            return fail(`${where} is nested too deep`);
+        if (raw === null || typeof raw === 'boolean' || typeof raw === 'string')
+            return raw;
+        if (typeof raw === 'number')
+            return Number.isFinite(raw) ? raw : fail(`${where} must be finite`);
+        if (Array.isArray(raw))
+            return raw.map((item) => json(item, where, level + 1));
+        if (typeof raw === 'object') {
+            const out = {};
+            for (const [key, item] of Object.entries(raw)) {
+                if (key === '__proto__')
+                    fail(`${where} has a forbidden key`);
+                out[key] =
+                    key === '$gettext' && typeof item === 'string'
+                        ? (sections.messages.add(item), item)
+                        : json(item, where, level + 1);
+            }
+            return out;
+        }
+        return fail(`${where} must be plain data`);
+    };
+    const animationOf = (id, body, where) => {
+        only(body, ['tag', 'id', 'frames', 'fps', 'loop', 'events'], where);
+        const frames = body.frames;
+        if (!Array.isArray(frames) || frames.length === 0 || frames.length > MAX_FRAMES)
+            fail(`${where}: frames must be a list of 1 to ${MAX_FRAMES} frame numbers`);
+        frames.forEach((frame) => {
+            if (!Number.isInteger(frame) || frame < 0)
+                fail(`${where}: a frame is a non-negative integer`);
+        });
+        const events = {};
+        for (const [frame, event] of Object.entries(record(body.events ?? {}, `${where}.events`))) {
+            if (!/^\d+$/.test(frame))
+                fail(`${where}: event keys are frame numbers`);
+            const entry = record(event, `${where}.events.${frame}`);
+            only(entry, ['sound'], `${where}.events.${frame}`);
+            events[frame] = { sound: idOrRef(entry.sound, `${where}.events.${frame}.sound`) };
+        }
+        const fps = body.fps === undefined ? undefined : finite(body.fps, `${where}.fps`);
+        if (fps !== undefined && (fps <= 0 || fps > 240))
+            fail(`${where}: fps must be between 0 and 240`);
+        if (body.loop !== undefined && typeof body.loop !== 'boolean')
+            fail(`${where}: loop must be true or false`);
+        return {
+            id,
+            frames: frames,
+            ...(fps === undefined ? {} : { fps }),
+            ...(body.loop === undefined ? {} : { loop: body.loop }),
+            events,
+        };
+    };
+    /** a reference is an id, optionally qualified `package:id` */
+    const idOrRef = (raw, where) => {
+        if (typeof raw !== 'string' || !/^[A-Za-z_][\w.-]*(?:@[\w.+-]+)?(?::[A-Za-z_][\w.-]*)?$/.test(raw))
+            return fail(`${where} must be an id or package:id`);
+        return raw;
+    };
+    const scriptOf = (id, body, where) => {
+        only(body, ['tag', 'id', 'on', 'when', 'do', 'code'], where);
+        const on = plain(body.on, `${where}.on`);
+        if (!ID.test(on))
+            fail(`${where}: on must be an event name`);
+        let when;
+        if (body.when !== undefined) {
+            when = plain(body.when, `${where}.when`);
+            if (when.length > MAX_CONDITION)
+                fail(`${where}: when is longer than ${MAX_CONDITION} characters`);
+            try {
+                checkConditionSyntax(when);
+            }
+            catch (error) {
+                fail(`${where}: when: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        const rawDo = body.do ?? [];
+        if (!Array.isArray(rawDo) || rawDo.length > MAX_ACTIONS)
+            fail(`${where}: do is a list of at most ${MAX_ACTIONS} actions`);
+        const actions = rawDo.map((item, index) => {
+            const action = record(item, `${where}.do[${index}]`);
+            let tag = action.tag;
+            let fields = action;
+            if (typeof tag !== 'string') {
+                // the named form `{ message: { text: ... } }`
+                const keys = Object.keys(action);
+                tag = keys.length === 1 ? keys[0] : undefined;
+                fields = tag ? record(action[tag], `${where}.do[${index}]`) : action;
+            }
+            if (typeof tag !== 'string' || !PACKAGE_SCRIPT_ACTIONS.includes(tag))
+                return fail(`${where}.do[${index}]: "${String(tag)}" is not an allowed action (${PACKAGE_SCRIPT_ACTIONS.join(', ')})`);
+            const attributes = {};
+            for (const [key, raw] of Object.entries(fields)) {
+                if (key === 'tag')
+                    continue;
+                attributes[key] =
+                    typeof raw === 'number' || typeof raw === 'boolean'
+                        ? raw
+                        : text(raw, `${where}.do[${index}].${key}`);
+            }
+            return { tag, attributes };
+        });
+        let code;
+        if (body.code !== undefined) {
+            code = plain(body.code, `${where}.code`);
+            if (code.length > MAX_CODE)
+                fail(`${where}: code is longer than ${MAX_CODE} characters`);
+        }
+        return {
+            id,
+            on,
+            ...(when === undefined ? {} : { when }),
+            do: actions,
+            ...(code === undefined ? {} : { code }),
+        };
+    };
+    const characterOf = (id, body) => {
+        const where = `[character] ${id}`;
+        unique(sections.characters, id, where);
+        const animations = {};
+        for (const [name, item] of Object.entries(record(body.animations ?? {}, `${where}.animations`))) {
+            if (typeof item === 'string')
+                animations[name] = idOrRef(item, `${where}.animations.${name}`);
+            else {
+                // inline: becomes an animation of its own, named after the character
+                const animationId = `${id}.${name}`;
+                unique(sections.animations, animationId, where);
+                sections.animations.push(animationOf(animationId, record(item, `${where}.animations.${name}`), `${where}.animations.${name}`));
+                animations[name] = animationId;
+            }
+        }
+        const sounds = {};
+        for (const [name, item] of Object.entries(record(body.sounds ?? {}, `${where}.sounds`))) {
+            if (typeof item === 'string')
+                sounds[name] = idOrRef(item, `${where}.sounds.${name}`);
+            else {
+                const soundId = `${id}.${name}`;
+                unique(sections.soundEffects, soundId, where);
+                const definition = record(item, `${where}.sounds.${name}`);
+                sections.soundEffects.push({
+                    id: soundId,
+                    definition: JSON.parse(JSON.stringify(definition)),
+                });
+                sounds[name] = soundId;
+            }
+        }
+        const scripts = [];
+        const rawScripts = body.scripts ?? [];
+        if (!Array.isArray(rawScripts))
+            fail(`${where}.scripts must be a list`);
+        rawScripts.forEach((item, index) => {
+            if (typeof item === 'string')
+                scripts.push(idOrRef(item, `${where}.scripts[${index}]`));
+            else {
+                const scriptId = `${id}.script${index}`;
+                unique(sections.scripts, scriptId, where);
+                sections.scripts.push(scriptOf(scriptId, record(item, `${where}.scripts[${index}]`), `${where}.scripts[${index}]`));
+                scripts.push(scriptId);
+            }
+        });
+        let sprite;
+        if (body.sprite !== undefined) {
+            const raw = record(body.sprite, `${where}.sprite`);
+            only(raw, ['image', 'frame'], `${where}.sprite`);
+            const frame = raw.frame;
+            if (frame !== undefined &&
+                (!Array.isArray(frame) || frame.length !== 2 || frame.some((n) => !Number.isInteger(n) || n <= 0)))
+                fail(`${where}.sprite.frame is [width, height]`);
+            sprite = {
+                image: idOrRef(raw.image, `${where}.sprite.image`),
+                ...(frame === undefined ? {} : { frame: frame }),
+            };
+        }
+        const stats = {};
+        for (const [key, raw] of Object.entries(body)) {
+            if (CHARACTER_FIELDS.includes(key))
+                continue;
+            if (!ID.test(key))
+                fail(`${where}: bad field name "${key}"`);
+            stats[key] = typeof raw === 'number' || typeof raw === 'boolean' ? raw : text(raw, `${where}.${key}`);
+        }
+        sections.characters.push({
+            id,
+            ...(body.name === undefined ? {} : { name: text(body.name, `${where}.name`) }),
+            ...(body.description === undefined ? {} : { description: text(body.description, `${where}.description`) }),
+            ...(body.portrait === undefined ? {} : { portrait: idOrRef(body.portrait, `${where}.portrait`) }),
+            ...(sprite === undefined ? {} : { sprite }),
+            ...(body.theme === undefined ? {} : { theme: idOrRef(body.theme, `${where}.theme`) }),
+            animations,
+            sounds,
+            scripts,
+            stats,
+        });
+    };
+    const entries = [];
+    for (const entry of value) {
+        const body = record(entry, 'a node');
+        if (typeof body.tag === 'string')
+            entries.push([body.tag, body]);
+        else {
+            const keys = Object.keys(body);
+            if (keys.length !== 1)
+                fail('a node needs a tag');
+            const items = Array.isArray(body[keys[0]]) ? body[keys[0]] : [body[keys[0]]];
+            for (const item of items)
+                entries.push([keys[0], record(item, keys[0])]);
+        }
+    }
+    for (const [tag, body] of entries) {
+        const where = `[${tag}]`;
+        if (!PACKAGE_TAGS.includes(tag))
+            fail(`${where} is not allowed in a package; use [character] and the other package tags`);
+        if (tag === 'package') {
+            if (depth > 0)
+                fail('an imported file cannot hold a [package] tag');
+            if (sections.meta)
+                fail('a second [package] tag');
+            only(body, ['tag', 'id', 'version', 'author', 'license', 'requires'], where);
+            const version = plain(body.version, `${where}.version`);
+            if (!VERSION.test(version))
+                fail(`${where}: version must look like 1.2.3`);
+            const requires = record(body.requires ?? {}, `${where}.requires`);
+            only(requires, ['mwg', 'retroAudio', 'capabilities'], `${where}.requires`);
+            const capabilities = requires.capabilities ?? [];
+            if (!Array.isArray(capabilities) || capabilities.some((item) => typeof item !== 'string' || !ID.test(item)))
+                fail(`${where}: requires.capabilities is a list of names`);
+            sections.meta = {
+                id: idOf(body.id, `${where}.id`),
+                version,
+                ...(body.author === undefined ? {} : { author: text(body.author, `${where}.author`) }),
+                ...(body.license === undefined ? {} : { license: plain(body.license, `${where}.license`) }),
+                requires: {
+                    ...(requires.mwg === undefined ? {} : { mwg: plain(requires.mwg, `${where}.requires.mwg`) }),
+                    ...(requires.retroAudio === undefined
+                        ? {}
+                        : { retroAudio: plain(requires.retroAudio, `${where}.requires.retroAudio`) }),
+                    capabilities: [...new Set(capabilities)].sort(),
+                },
+            };
+            continue;
+        }
+        if (tag === 'import') {
+            only(body, ['tag', 'src', 'package', 'version', 'as'], where);
+            if ((body.src === undefined) === (body.package === undefined))
+                fail(`${where}: needs exactly one of src and package`);
+            const imported = {
+                ...(body.src === undefined ? {} : { src: checkPackagePath(plain(body.src, `${where}.src`)) }),
+                ...(body.package === undefined ? {} : { package: idOf(body.package, `${where}.package`) }),
+                ...(body.version === undefined ? {} : { version: plain(body.version, `${where}.version`) }),
+                ...(body.as === undefined ? {} : { as: idOf(body.as, `${where}.as`) }),
+            };
+            sections.imports.push(imported);
+            if (imported.src !== undefined) {
+                if (depth + 1 > MAX_IMPORT_DEPTH)
+                    fail(`${where}: imports are nested more than ${MAX_IMPORT_DEPTH} deep`);
+                if (++budget.reads > MAX_IMPORT_READS)
+                    fail(`${where}: more than ${MAX_IMPORT_READS} imports in one package`);
+                const files = options.files;
+                const imported_source = files && Object.hasOwn(files, imported.src) ? files[imported.src] : undefined;
+                if (imported_source === undefined)
+                    fail(`${where}: "${imported.src}" is not in the package`);
+                readInto(sections, imported_source, { ...options, file: imported.src }, depth + 1, imported.as ? local(imported.as) : prefix, budget);
+            }
+            continue;
+        }
+        const id = local(idOf(body.id, `${where}.id`));
+        if (tag === 'asset') {
+            only(body, ['tag', 'id', 'kind', 'path', 'mime', 'sha256', 'license', 'source'], where);
+            const kind = plain(body.kind, `${where}.kind`);
+            if (!PACKAGE_ASSET_KINDS.includes(kind))
+                fail(`${where}: kind must be one of ${PACKAGE_ASSET_KINDS.join(', ')}`);
+            unique(sections.assets, id, where);
+            const sha256 = body.sha256 === undefined ? undefined : plain(body.sha256, `${where}.sha256`);
+            if (sha256 !== undefined && !/^[0-9a-f]{64}$/.test(sha256))
+                fail(`${where}: sha256 is 64 lower-case hex digits`);
+            sections.assets.push({
+                id,
+                kind,
+                path: checkPackagePath(plain(body.path, `${where}.path`)),
+                ...(body.mime === undefined ? {} : { mime: plain(body.mime, `${where}.mime`) }),
+                ...(sha256 === undefined ? {} : { sha256 }),
+                ...(body.license === undefined ? {} : { license: plain(body.license, `${where}.license`) }),
+                ...(body.source === undefined ? {} : { source: plain(body.source, `${where}.source`) }),
+            });
+        }
+        else if (tag === 'animation') {
+            unique(sections.animations, id, where);
+            sections.animations.push(animationOf(id, body, `${where} ${id}`));
+        }
+        else if (tag === 'sound_effect') {
+            unique(sections.soundEffects, id, where);
+            const { tag: _tag, id: _id, ...rest } = body;
+            void _tag;
+            void _id;
+            sections.soundEffects.push({
+                id,
+                definition: json(rest, `${where} ${id}`),
+            });
+        }
+        else if (tag === 'music') {
+            only(body, ['tag', 'id', 'src', 'loop', 'region', 'fallback'], where);
+            unique(sections.music, id, where);
+            const region = body.region;
+            if (region !== undefined &&
+                (!Array.isArray(region) || region.length !== 2 || region.some((n) => typeof n !== 'number' || n < 0)))
+                fail(`${where}: region is [start, end]`);
+            sections.music.push({
+                id,
+                src: idOrRef(body.src, `${where}.src`),
+                ...(body.loop === undefined ? {} : { loop: body.loop === true }),
+                ...(region === undefined ? {} : { region: region }),
+                ...(body.fallback === undefined ? {} : { fallback: idOrRef(body.fallback, `${where}.fallback`) }),
+            });
+        }
+        else if (tag === 'script') {
+            unique(sections.scripts, id, where);
+            sections.scripts.push(scriptOf(id, body, `${where} ${id}`));
+        }
+        else {
+            characterOf(id, body);
+        }
+    }
+}
+const CHARACTER_FIELDS = [
+    'tag',
+    'id',
+    'name',
+    'description',
+    'portrait',
+    'sprite',
+    'theme',
+    'animations',
+    'sounds',
+    'scripts',
+];
+function parseTriple(text, partial) {
+    const parts = text.split(/[-+]/)[0].split('.');
+    if (parts.length > 3 || (!partial && parts.length !== 3))
+        throw new PackageFormatError(`bad version "${text}"`);
+    return parts.map((part) => {
+        if (!/^\d{1,9}$/.test(part))
+            throw new PackageFormatError(`bad version "${text}"`);
+        return Number(part);
+    });
+}
+function compareTriples(a, b) {
+    for (let index = 0; index < 3; index++) {
+        const difference = (a[index] ?? 0) - (b[index] ?? 0);
+        if (difference)
+            return difference;
+    }
+    return 0;
+}
+/** the first version a partial one does not cover: `1.2` -> `1.3.0`, `1` -> `2.0.0` */
+function bump(parts) {
+    if (parts.length === 1)
+        return [parts[0] + 1, 0, 0];
+    if (parts.length === 2)
+        return [parts[0], parts[1] + 1, 0];
+    return [parts[0], parts[1], parts[2] + 1];
+}
+function comparator(text) {
+    const match = /^(>=|<=|>|<|\^|~|=)?\s*(.*)$/.exec(text.trim());
+    const operator = match?.[1] ?? '=';
+    const body = match?.[2] ?? '';
+    if (body === '' || body === '*' || /^[xX*]$/.test(body))
+        return undefined;
+    const parts = parseTriple(body.replace(/\.[xX*]/g, ''), true);
+    const low = [parts[0], parts[1] ?? 0, parts[2] ?? 0];
+    if (operator === '>=')
+        return { low, op: 'range' };
+    if (operator === '>')
+        return parts.length === 3 ? { low, op: 'gt' } : { low: bump(parts), op: 'range' };
+    if (operator === '<')
+        return { low: [0, 0, 0], high: low, op: 'range' };
+    if (operator === '<=')
+        return parts.length === 3 ? { low, op: 'lte' } : { low: [0, 0, 0], high: bump(parts), op: 'range' };
+    if (operator === '^') {
+        // a caret allows changes right of the first non-zero part
+        const significant = parts.findIndex((part) => part > 0);
+        return { low, high: bump(parts.slice(0, significant < 0 ? parts.length : significant + 1)), op: 'range' };
+    }
+    if (operator === '~')
+        return { low, high: bump(parts.slice(0, 2)), op: 'range' };
+    return { low, high: bump(parts), op: 'range' };
+}
+/**
+ * Checks a version against a small semver range: `>=`, `>`, `<=`, `<`, `^`, `~`, an exact
+ * version or a partial one (`0.42` is `0.42.x`), several separated by spaces (all must hold) and
+ * alternatives separated by `||`. A pre-release or build suffix on the version is ignored.
+ * A malformed range throws a `PackageFormatError`.
+ *
+ * @example
+ * ```ts
+ * import { satisfiesVersionRange } from '@datamoc/mw_games/mwl';
+ *
+ * console.log(satisfiesVersionRange('0.43.0', '>=0.42 <1')); // true
+ * console.log(satisfiesVersionRange('0.43.0', '^0.42.0')); // false
+ * ```
+ */
+export function satisfiesVersionRange(version, range) {
+    const actual = parseTriple(version, false);
+    return range.split('||').some((alternative) => alternative
+        .replace(/([<>=^~])\s+/g, '$1')
+        .trim()
+        .split(/\s+/)
+        .every((part) => {
+        const rule = comparator(part);
+        if (!rule)
+            return true;
+        if (rule.op === 'gt')
+            return compareTriples(actual, rule.low) > 0;
+        if (rule.op === 'lte')
+            return compareTriples(actual, rule.low) <= 0;
+        return compareTriples(actual, rule.low) >= 0 && (!rule.high || compareTriples(actual, rule.high) < 0);
+    }));
+}
+/**
+ * Orders two `x.y.z` versions: negative when `a` is older, positive when newer. It decides which
+ * of two coexisting versions of a package owns the plain `packageId:id` name.
+ *
+ * @example
+ * ```ts
+ * import { compareVersions } from '@datamoc/mw_games/mwl';
+ *
+ * console.log(compareVersions('1.2.0', '1.10.0') < 0); // true
+ * ```
+ */
+export function compareVersions(a, b) {
+    return compareTriples(parseTriple(a, false), parseTriple(b, false));
+}
+//# sourceMappingURL=package-document.js.map