diff --git a/packages/vortex-api/CHANGELOG.md b/packages/vortex-api/CHANGELOG.md index ad7e409f2c..8c3cbba673 100644 --- a/packages/vortex-api/CHANGELOG.md +++ b/packages/vortex-api/CHANGELOG.md @@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/). ### Added +- A JSON Schema for `info.json`, published as `@nexusmods/vortex-api/schemas/info.schema.json`, and an [`info.json` reference](./docs/INFO-JSON.md) covering every field, including `contributes`. Add `"$schema": "https://unpkg.com/@nexusmods/vortex-api/schemas/info.schema.json"` to your `info.json` for editor completion - `GameUid`, the id of a game in the Nexus Mods game catalogue, with its brander - `IMainPageOptions`: `menuIcon` property, a Material Symbol by name (such as `"settings"`) or an SVG path as `{ path }`, for the page's icon in the menu. A misspelled symbol name fails the typecheck - Game info entries from `registerGameInfoProvider` accept `type: "path"`, shown as a link that opens the file or folder. The built-in `game-path` entry uses it diff --git a/packages/vortex-api/README.md b/packages/vortex-api/README.md index 6d10063f06..e091f22bbc 100644 --- a/packages/vortex-api/README.md +++ b/packages/vortex-api/README.md @@ -10,6 +10,8 @@ For packaging and distributing extensions, see [How to package a game extension] For API changes between versions, see the [Changelog](CHANGELOG.md). +For the fields of an extension's `info.json`, including `contributes`, see the [`info.json` Reference](docs/INFO-JSON.md). + For a full list of events extensions can listen to or emit, see the [Events Reference](docs/EVENTS.md). For notable open-source extensions with advanced patterns, see the [Example Extensions](docs/EXAMPLES.md). @@ -30,10 +32,7 @@ A Vortex extension is a JavaScript module that exports an `init` function. The f `info.json` -- `name` - the display name of your extension. -- `author` - the extension author's name. -- `version` - the version of your extension. -- `description` - a short description of what your extension does. +- Describes your extension to Vortex: its name, version, and the games it contributes. See the [`info.json` reference](docs/INFO-JSON.md) for every field and the JSON Schema that gives your editor completion. `index.js` diff --git a/packages/vortex-api/docs/INFO-JSON.md b/packages/vortex-api/docs/INFO-JSON.md new file mode 100644 index 0000000000..65cae8317d --- /dev/null +++ b/packages/vortex-api/docs/INFO-JSON.md @@ -0,0 +1,162 @@ +# `info.json` Reference + +Every Vortex extension has an `info.json` at the top level of its folder. It tells Vortex what the extension is and, through `contributes`, which games it supports, without running any of the extension's code. + +Vortex never reads your `package.json`. That file belongs to npm and your build. If you build your extension with a tool that generates `info.json` from `package.json`, the generated file is the one Vortex reads, and it only contains what the tool wrote. + +## Editor completion + +The package ships a JSON Schema for `info.json`. Point your file at it to get completion and field documentation in editors that support JSON Schema, such as VS Code: + +```json +{ + "$schema": "https://unpkg.com/@nexusmods/vortex-api/schemas/info.schema.json", + "name": "My Game Support", + "version": "1.0.0" +} +``` + +If you have the package installed you can also reference the file from `node_modules/@nexusmods/vortex-api/schemas/info.schema.json`. Vortex ignores the `$schema` key. + +The schema describes the shape of the file: types, required keys and structure. It doesn't enforce every rule, so a file that passes the schema can still be invalid. The rules for values are listed below and in each field's description. Unknown keys are allowed everywhere, at the top level and inside `contributes`. + +## Fields + +| Field | Required | Meaning | +| ------------- | -------- | --------------------------------------------------------------------------------------------------------------- | +| `name` | yes | Display name of the extension. | +| `version` | yes | Version of the extension, as a semver string. | +| `author` | no | Display name of the author. Shown as `` when missing. | +| `description` | no | Short description of what the extension does. Shown as `` when missing. | +| `id` | no | Stable identifier, used by other extensions that call `requireExtension`. Pick one and keep it across versions. | +| `namespace` | no | i18next namespace for the extension's translations. | +| `contributes` | no | What the extension contributes. See below. | +| `gameId` | no | Deprecated. See [`gameId`](#gameid-deprecated). | + +Vortex also writes a `modId` key when it installs an extension. You don't write it, and it isn't part of the schema. + +## `contributes` + +`contributes` declares what your extension contributes in a form Vortex, Nexus Mods and other tools can read without loading it. Every field in it is optional. + +An extension without `contributes` keeps working exactly as it does today. Vortex treats it as a legacy extension and never rejects it. Older Vortex versions ignore the key, so you can add it now. + +If `contributes` is invalid, the extension loads as if it had none and Vortex logs a warning naming your extension and what failed. One invalid field makes all of `contributes` invalid, so fix the warning rather than relying on the fallback. + +### `contributes.games` + +The games your extension registers, keyed by the id you pass to `registerGame`. The typical extension supports one game that has its own page on Nexus Mods, and needs only this: + +```json +{ + "name": "Stardew Valley Support", + "version": "1.0.0", + "contributes": { + "games": { + "stardewvalley": { "nexusGameId": 1303, "name": "Stardew Valley" } + } + } +} +``` + +The key `stardewvalley` is the `id` the extension passes to `registerGame`. `nexusGameId` is the game's id on Nexus Mods, and `name` is how listings that can't run the extension show it. + +Rules for the keys: each is a non-empty string and none starts with `tier-0-`, which Vortex reserves. Registering an id that isn't listed is an error. A game may be an empty object, which declares the game and nothing else. + +Each game can set these fields: + +- `nexusGameId`: the Nexus Mods game this game's mods are published on, as a positive integer. Leave it out if the game has no page on Nexus Mods. It can't be `null`. Several games can declare the same one, as Skyrim Special Edition and Skyrim VR both do with 1704. +- `gameUid`: the game's id in the Nexus Mods game catalogue, a non-empty string. Vortex doesn't check its structure, because catalogue ids are opaque. Write it in any case, Vortex lowercases it. +- `name`: a non-empty listing name, for places that can't run your extension. Vortex itself shows the name you pass to `registerGame`. + +#### Supporting two games + +An extension that registers several games lists each under the id it passes to `registerGame`. Here, one extension supports a game and its sequel, and each has its own page on Nexus Mods, so neither needs a `gameUid`. The ids are made up: + +```json +{ + "name": "My Game Support", + "version": "1.0.0", + "contributes": { + "games": { + "mygame": { "nexusGameId": 1111, "name": "My Game" }, + "mygame2": { "nexusGameId": 2222, "name": "My Game 2" } + } + } +} +``` + +#### When `gameUid` is required + +A game resolves to the declared `gameUid` if there is one, otherwise to the game its `nexusGameId` belongs to, otherwise to nothing. So declare `gameUid` when your game is not the one its `nexusGameId` belongs to, or when it isn't on Nexus Mods at all. + +Skyrim VR is the first case: its mods are published on the Skyrim Special Edition page (1704), so `nexusGameId` alone would resolve to Skyrim Special Edition. Give it its own `gameUid`. Skyrim Special Edition is the game 1704 belongs to, so it doesn't need one: + +```json +{ + "name": "Skyrim Support", + "version": "1.0.0", + "contributes": { + "games": { + "skyrimse": { "nexusGameId": 1704, "name": "Skyrim Special Edition" }, + "skyrimvr": { + "nexusGameId": 1704, + "gameUid": "d88c5de7-353b-5d60-87be-bec5caa6244a", + "name": "Skyrim VR" + } + } + } +} +``` + +A game that isn't on Nexus Mods at all has no `nexusGameId` to fall back on, so `gameUid` is the only thing that identifies it: + +```json +{ + "name": "My Unlisted Game Support", + "version": "1.0.0", + "contributes": { + "games": { + "myunlistedgame": { + "gameUid": "00000000-0000-0000-0000-000000000000", + "name": "My Unlisted Game" + } + } + } +} +``` + +The `gameUid` above is a placeholder. Look up the real one as described next. + +#### Finding a game's ids + +Look the game up on [NexusDB](https://nexusdb.nexusmods.com), the catalogue's own site. It lists the `gameUid` of every game, including those whose mods are published on another game's page. A developer dialog on Nexus Mods game pages that shows `game_id` and `game_uid` is planned, and this page will link it once it exists. + +### `contributes.gameEnhancements` + +For games your extension is relevant to without registering them, such as a tool, a mod type or an installer that works with games other extensions provide. This is advisory. + +Each entry sets exactly one of `gameUid` and `nexusGameId`. Setting both, or neither, makes `contributes` invalid. + +- `gameUid` targets one game. +- `nexusGameId` targets every game whose mods are published on that Nexus Mods game. + +An extension that enhances every game published on Fallout New Vegas (130): + +```json +{ + "name": "Fallout New Vegas Sanity Checks", + "version": "1.0.0", + "contributes": { + "gameEnhancements": [{ "nexusGameId": 130 }] + } +} +``` + +## `gameId` (deprecated) + +`gameId` is superseded by `contributes.games`. Vortex doesn't read it, but the Nexus Mods data platform still does, so leave it in place if your extension already has it. + +- A number, or a string of digits, is the Nexus Mods game id: `2304` or `"2304"`. +- Any other string without whitespace is the game's domain on Nexus Mods: `"skyrimspecialedition"`. +- Anything else is ignored: an empty string, `0`, a negative number, a display name such as `"Game: My Game"`, a list or an object. diff --git a/packages/vortex-api/package.json b/packages/vortex-api/package.json index 21c8072b20..04ee1ab0b6 100644 --- a/packages/vortex-api/package.json +++ b/packages/vortex-api/package.json @@ -24,11 +24,13 @@ "exports": { ".": { "types": "./lib/api.d.ts" - } + }, + "./info.schema.json": "./schemas/info.schema.json" }, "files": [ "lib", "bin", + "schemas", "README.md", "docs" ], diff --git a/packages/vortex-api/schemas/info.schema.json b/packages/vortex-api/schemas/info.schema.json new file mode 100644 index 0000000000..8f5a3cfadf --- /dev/null +++ b/packages/vortex-api/schemas/info.schema.json @@ -0,0 +1,125 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://unpkg.com/@nexusmods/vortex-api/schemas/info.schema.json", + "title": "Vortex extension info.json", + "description": "The info.json file at the top level of a Vortex extension. The schema describes shape only: types, required keys and structure. Rules about values are written in each field's description. Vortex checks them and falls back to its legacy behaviour when `contributes` breaks one. Unknown keys are allowed everywhere.", + "type": "object", + "required": ["name", "version"], + "properties": { + "$schema": { + "type": "string", + "description": "Points editors at this schema for completion and field docs. Vortex ignores it." + }, + "name": { + "type": "string", + "description": "Display name of the extension." + }, + "version": { + "type": "string", + "description": "Version of the extension, as a semver string such as `1.2.0`." + }, + "author": { + "type": "string", + "description": "Display name of the extension's author. Shown as `` when missing." + }, + "description": { + "type": "string", + "description": "Short description of what the extension does. Shown as `` when missing." + }, + "id": { + "type": "string", + "description": "Stable identifier for the extension, used when other extensions require it with `requireExtension`. Pick one and keep it across versions." + }, + "namespace": { + "type": "string", + "description": "i18next namespace for the extension's translations." + }, + "contributes": { + "$ref": "#/$defs/contributes" + }, + "gameId": { + "type": ["integer", "string"], + "deprecated": true, + "description": "Deprecated: use `contributes.games` instead. Vortex doesn't read it, but the Nexus Mods data platform still does. A number or a string of digits is the Nexus Mods game id (`2304`). Any other string without whitespace is the game's domain on Nexus Mods (`skyrimspecialedition`). Anything else is ignored." + } + }, + "examples": [ + { + "name": "Skyrim Support", + "version": "1.0.0", + "contributes": { + "games": { + "skyrimse": { + "nexusGameId": 1704, + "name": "Skyrim Special Edition" + }, + "skyrimvr": { + "nexusGameId": 1704, + "gameUid": "d88c5de7-353b-5d60-87be-bec5caa6244a", + "name": "Skyrim VR" + } + } + } + }, + { + "name": "Fallout New Vegas Sanity Checks", + "version": "1.0.0", + "contributes": { + "gameEnhancements": [{ "nexusGameId": 130 }] + } + } + ], + "$defs": { + "contributes": { + "type": "object", + "description": "What the extension contributes, readable without running it. Every field is optional. Vortex reads it only when it is valid. One invalid field makes all of `contributes` invalid, and the extension then loads as if it had none, with a warning. Older Vortex versions ignore this key.", + "properties": { + "games": { + "type": "object", + "description": "The games the extension registers, keyed by the id it passes to `registerGame`. Keys must be non-empty and must not start with `tier-0-`, which is reserved. Registering an id that isn't listed is an error. An empty object for a game declares the game and nothing else.", + "additionalProperties": { + "$ref": "#/$defs/game" + } + }, + "gameEnhancements": { + "type": "array", + "description": "Games the extension is relevant to without registering them, for example a tool or a mod type that works with several games. Advisory.", + "items": { + "$ref": "#/$defs/gameEnhancement" + } + } + } + }, + "game": { + "type": "object", + "properties": { + "nexusGameId": { + "type": "integer", + "description": "The Nexus Mods game this game's mods are published on. Must be a positive integer, and `null` isn't allowed. Leave it out when the game has no page on Nexus Mods. Several games may declare the same one: Skyrim Special Edition and Skyrim VR both publish on 1704." + }, + "gameUid": { + "type": "string", + "description": "The game's id in the Nexus Mods game catalogue, found on NexusDB (https://nexusdb.nexusmods.com). Must be non-empty. Required when the game isn't the one its `nexusGameId` belongs to (Skyrim VR on 1704), or when it isn't on Nexus Mods. Any case is accepted, Vortex lowercases it." + }, + "name": { + "type": "string", + "description": "Name for listings that can't run the extension. Must be non-empty. Vortex itself shows the name passed to `registerGame`." + } + } + }, + "gameEnhancement": { + "type": "object", + "description": "Sets exactly one of `gameUid` and `nexusGameId`. Setting both, or neither, makes `contributes` invalid.", + "properties": { + "gameUid": { + "type": "string", + "description": "Enhances exactly this game. Same rules as `gameUid` on a game." + }, + "nexusGameId": { + "type": "integer", + "description": "Enhances every game whose mods are published on this Nexus Mods game. Same rules as `nexusGameId` on a game." + } + } + } + } +} diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index ab0027dca8..0caa3115ee 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -500,6 +500,9 @@ catalogs: '@welldone-software/why-did-you-render': specifier: 7.0.1 version: 7.0.1 + ajv: + specifier: 8.18.0 + version: 8.18.0 babel-loader: specifier: 10.1.1 version: 10.1.1 @@ -2434,7 +2437,7 @@ importers: version: 2.4.1 electron: specifier: 'catalog:' - version: 45.3.4 + version: 45.3.4(supports-color@10.2.2) modmeta-db: specifier: 'catalog:' version: https://codeload.github.com/Nexus-Mods/modmeta-db/tar.gz/daa8935b6e38e255ec192c908adfce35d47c0336(commander@14.0.3)(encoding-down@6.3.0)(express@4.22.1)(leveldown@5.6.0)(levelup@4.4.0) @@ -3105,7 +3108,7 @@ importers: version: 2.4.1 electron: specifier: 'catalog:' - version: 45.3.4 + version: 45.3.4(supports-color@10.2.2) turbowalk: specifier: 'catalog:' version: https://codeload.github.com/Nexus-Mods/node-turbowalk/tar.gz/c8d9be07cc658aecdca63af2508df929990cd583 @@ -3609,7 +3612,7 @@ importers: version: 2.4.1 electron: specifier: 'catalog:' - version: 45.3.4 + version: 45.3.4(supports-color@10.2.2) exe-version: specifier: workspace:* version: link:../../packages/exe-version @@ -3831,7 +3834,7 @@ importers: version: 24.12.2 electron: specifier: 'catalog:' - version: 45.3.4 + version: 45.3.4(supports-color@10.2.2) enquirer: specifier: 'catalog:' version: 2.4.1 @@ -4010,7 +4013,7 @@ importers: version: 3.6.0 electron: specifier: 'catalog:' - version: 45.3.4 + version: 45.3.4(supports-color@10.2.2) i18next: specifier: 'catalog:' version: 21.10.0 @@ -4545,7 +4548,7 @@ importers: version: 10.1.0 electron: specifier: 'catalog:' - version: 45.3.4 + version: 45.3.4(supports-color@10.2.2) electron-builder: specifier: 'catalog:' version: 24.13.3(electron-builder-squirrel-windows@24.13.3) @@ -4572,7 +4575,7 @@ importers: version: link:../shared electron: specifier: 'catalog:' - version: 45.3.4 + version: 45.3.4(supports-color@10.2.2) src/renderer: dependencies: @@ -4814,6 +4817,9 @@ importers: '@welldone-software/why-did-you-render': specifier: 'catalog:' version: 7.0.1(react@18.3.1) + ajv: + specifier: 'catalog:' + version: 8.18.0 babel-loader: specifier: 'catalog:' version: 10.1.1(@babel/core@7.29.7)(webpack@5.108.4) @@ -4876,7 +4882,7 @@ importers: version: https://codeload.github.com/TanninOne/drivelist/tar.gz/720d1890db11482ec05fc0f6aa176cfa6e6844dd electron: specifier: 'catalog:' - version: 45.3.4 + version: 45.3.4(supports-color@10.2.2) electron-context-menu: specifier: 'catalog:' version: 3.6.1 @@ -14204,14 +14210,14 @@ snapshots: glob: 7.2.3 minimatch: 3.1.5 - '@electron/get@5.0.0': + '@electron/get@5.0.0(supports-color@10.2.2)': dependencies: debug: 4.4.3(supports-color@10.2.2) env-paths: 3.0.0 graceful-fs: 4.2.11 progress: 2.0.3 semver: 7.8.5 - sumchecker: 3.0.1 + sumchecker: 3.0.1(supports-color@10.2.2) optionalDependencies: undici: 7.29.0 transitivePeerDependencies: @@ -14249,7 +14255,7 @@ snapshots: '@electron/remote@2.1.3(electron@45.3.4)': dependencies: - electron: 45.3.4 + electron: 45.3.4(supports-color@10.2.2) '@electron/universal@1.5.1': dependencies: @@ -17675,7 +17681,7 @@ snapshots: electron-extension-installer@2.0.1(electron@45.3.4): dependencies: - electron: 45.3.4 + electron: 45.3.4(supports-color@10.2.2) jszip: 3.10.1 electron-is-dev@2.0.0: {} @@ -17715,10 +17721,10 @@ snapshots: transitivePeerDependencies: - supports-color - electron@45.3.4: + electron@45.3.4(supports-color@10.2.2): dependencies: '@electron-internal/extract-zip': 1.0.4 - '@electron/get': 5.0.0 + '@electron/get': 5.0.0(supports-color@10.2.2) '@types/node': 24.12.2 transitivePeerDependencies: - supports-color @@ -20828,7 +20834,7 @@ snapshots: dependencies: inline-style-parser: 0.1.1 - sumchecker@3.0.1: + sumchecker@3.0.1(supports-color@10.2.2): dependencies: debug: 4.4.3(supports-color@10.2.2) transitivePeerDependencies: diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index fea5c6357a..8766b24782 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -116,6 +116,7 @@ catalog: "@vitest/coverage-v8": 4.1.9 "@vitest/ui": 4.1.9 "@welldone-software/why-did-you-render": 7.0.1 + ajv: 8.18.0 babel-loader: 10.1.1 bbcode-to-react: github:TanninOne/bbcode-to-react#c67356006470e5066ea447e04a3968dca367339d big.js: 5.2.2 diff --git a/src/renderer/package.json b/src/renderer/package.json index 3b17edeb41..4e0bdd9a95 100644 --- a/src/renderer/package.json +++ b/src/renderer/package.json @@ -133,6 +133,7 @@ "@vortex/nexus-api-v3": "workspace:*", "@vortex/shared": "workspace:*", "@welldone-software/why-did-you-render": "catalog:", + "ajv": "catalog:", "babel-loader": "catalog:", "bbcode-to-react": "catalog:", "big.js": "catalog:", diff --git a/src/renderer/src/extensions/extension_manager/infoSchema.test.ts b/src/renderer/src/extensions/extension_manager/infoSchema.test.ts new file mode 100644 index 0000000000..18ca1c7afc --- /dev/null +++ b/src/renderer/src/extensions/extension_manager/infoSchema.test.ts @@ -0,0 +1,185 @@ +import { readFileSync } from "node:fs"; +import { resolve } from "node:path"; + +import Ajv2020 from "ajv/dist/2020"; +import { describe, expect, it, vi } from "vitest"; + +import { ContributesSchema } from "./contributes"; +import { parseExtensionInfo } from "./extensionInfo"; + +vi.mock("../../logging", () => ({ log: vi.fn() })); + +// The JSON Schema in @nexusmods/vortex-api is written by hand, because the value rules of +// ContributesSchema can't be expressed in it. This test is what keeps the two in agreement. +const schemaPath = resolve( + __dirname, + "../../../../../packages/vortex-api/schemas/info.schema.json", +); +const infoSchema = JSON.parse(readFileSync(schemaPath, "utf8")) as { examples: unknown[] }; + +const ajv = new Ajv2020({ strict: true, allowUnionTypes: true }); +const validateSchema = ajv.compile(infoSchema); + +const schemaAccepts = (info: unknown) => validateSchema(info); + +/** What Vortex does with the file: loads it in manifest mode, or not at all, or in legacy mode. */ +function vortexAccepts(info: unknown): boolean { + try { + const parsed = parseExtensionInfo(info); + const raw = (info as { contributes?: unknown }).contributes; + // an invalid contributes doesn't reject the extension, but it isn't a valid manifest either + return raw === undefined || parsed.contributes !== undefined; + } catch { + return false; + } +} + +const base = { name: "Made-up Support", version: "1.0.0" }; +const game = (fields: unknown) => ({ ...base, contributes: { games: { madeup: fields } } }); +const enhancing = (...entries: unknown[]) => ({ + ...base, + contributes: { gameEnhancements: entries }, +}); + +describe("info.json schema and Vortex agree on shape", () => { + const wrongShape: [string, unknown][] = [ + ["missing name", { version: "1.0.0" }], + ["missing version", { name: "x" }], + ["null name", { ...base, name: null }], + ["numeric version", { ...base, version: 1 }], + ["numeric author", { ...base, author: 5 }], + ["numeric description", { ...base, description: 5 }], + ["numeric id", { ...base, id: 5 }], + ["numeric namespace", { ...base, namespace: 5 }], + ["null contributes", { ...base, contributes: null }], + ["string contributes", { ...base, contributes: "games" }], + ["array contributes", { ...base, contributes: [] }], + ["null games", { ...base, contributes: { games: null } }], + ["array games", { ...base, contributes: { games: [] } }], + ["string game", { ...base, contributes: { games: { madeup: "madeup" } } }], + ["null game", { ...base, contributes: { games: { madeup: null } } }], + ["string nexusGameId", game({ nexusGameId: "1" })], + ["null nexusGameId", game({ nexusGameId: null })], + ["fractional nexusGameId", game({ nexusGameId: 1.5 })], + ["numeric gameUid", game({ gameUid: 1 })], + ["null gameUid", game({ gameUid: null })], + ["numeric name", game({ name: 1 })], + ["object gameEnhancements", { ...base, contributes: { gameEnhancements: {} } }], + ["null gameEnhancements", { ...base, contributes: { gameEnhancements: null } }], + ["string enhancement", enhancing("abc")], + ["null enhancement", enhancing(null)], + ["string enhancement nexusGameId", enhancing({ nexusGameId: "130" })], + ["numeric enhancement gameUid", enhancing({ gameUid: 1 })], + ]; + + it.each(wrongShape)("both reject %s", (_label, info) => { + expect(vortexAccepts(info)).toBe(false); + expect(schemaAccepts(info)).toBe(false); + }); + + // The schema leaves these to the field descriptions, so it passes what Vortex rejects. + const wrongValue: [string, unknown][] = [ + ["a tier-0- game key", { ...base, contributes: { games: { "tier-0-made-up": {} } } }], + ["an empty game key", { ...base, contributes: { games: { "": {} } } }], + ["a zero nexusGameId", game({ nexusGameId: 0 })], + ["a negative nexusGameId", game({ nexusGameId: -1 })], + ["an empty gameUid", game({ gameUid: "" })], + ["an empty name", game({ name: "" })], + ["an enhancement with both targets", enhancing({ gameUid: "abc", nexusGameId: 130 })], + ["an enhancement with no target", enhancing({})], + ["a zero enhancement nexusGameId", enhancing({ nexusGameId: 0 })], + ["an empty enhancement gameUid", enhancing({ gameUid: "" })], + ]; + + it.each(wrongValue)("Vortex rejects but the schema passes %s", (_label, info) => { + expect(vortexAccepts(info)).toBe(false); + expect( + ContributesSchema.safeParse((info as { contributes: unknown }).contributes).success, + ).toBe(false); + expect(schemaAccepts(info)).toBe(true); + }); + + const accepted: [string, unknown][] = [ + ["only name and version", base], + ["every plain field", { ...base, author: "a", description: "d", id: "i", namespace: "n" }], + ["an empty contributes", { ...base, contributes: {} }], + ["an empty games object", { ...base, contributes: { games: {} } }], + ["an empty game", game({})], + ["a full game", game({ nexusGameId: 1704, gameUid: "abc", name: "Made-up" })], + ["an uppercase gameUid", game({ gameUid: "D88C5DE7-353B-5D60-87BE-BEC5CAA6244A" })], + ["a tier-1- game key", { ...base, contributes: { games: { "tier-1-made-up": {} } } }], + ["a gameUid that isn't a uuid", game({ gameUid: "not even a uuid!" })], + ["an enhancement of one game", enhancing({ gameUid: "abc" })], + ["an enhancement of a Nexus Mods game", enhancing({ nexusGameId: 130 })], + ["no enhancements", enhancing()], + ["unknown top-level keys", { ...base, somethingNew: { a: 1 } }], + ["unknown keys in contributes", { ...base, contributes: { somethingNew: true } }], + ["unknown keys in a game", game({ somethingNew: true })], + ["unknown keys in an enhancement", enhancing({ nexusGameId: 130, somethingNew: true })], + ["a $schema key", { ...base, $schema: "https://example.invalid/info.schema.json" }], + ["any modId, which is Vortex's own", { ...base, modId: 196 }], + ["an unusable modId, which Vortex ignores", { ...base, modId: "196" }], + ["a null modId", { ...base, modId: null }], + ]; + + it.each(accepted)("both accept %s", (_label, info) => { + expect(vortexAccepts(info)).toBe(true); + expect(schemaAccepts(info)).toBe(true); + }); +}); + +describe("info.json schema gameId", () => { + // Vortex has no parser for gameId. These follow the data platform's parse_game_id + // (ingestion/sources/gamedata/tests/test_vortex_parse.py in the data repository), by hand. + const passes: [string, unknown][] = [ + ["a number", 2304], + ["a digit string", "2304"], + ["a digit string with whitespace", " 2304 "], + ["a number written with a decimal point", 2304.0], + ["a domain", "gta5"], + ["a mixed case domain", "fableIII"], + ["a domain with punctuation", "steins;gateelite"], + // shape is right, the value is one the data platform ignores + ["zero", 0], + ["a negative number", -5], + ["an empty string", ""], + ["a display name", "Game: Lockdown Protocol"], + ["a number beyond the Nexus Mods id range", 2 ** 32], + ]; + + it.each(passes)("passes %s", (_label, gameId) => { + expect(schemaAccepts({ ...base, gameId })).toBe(true); + }); + + const fails: [string, unknown][] = [ + ["null", null], + ["true", true], + ["false", false], + ["a fraction", 2304.5], + ["a list", [2304]], + ["an object", { id: 2304 }], + ]; + + it.each(fails)("rejects %s", (_label, gameId) => { + expect(schemaAccepts({ ...base, gameId })).toBe(false); + }); + + it("is marked deprecated", () => { + const properties = (infoSchema as unknown as { properties: Record }).properties; + expect(properties.gameId).toMatchObject({ deprecated: true }); + }); +}); + +describe("info.json schema examples", () => { + it("has examples", () => { + expect(infoSchema.examples.length).toBeGreaterThan(0); + }); + + it.each(infoSchema.examples.map((example, index) => [index, example] as const))( + "example %i validates, and Vortex accepts it", + (_index, example) => { + expect(schemaAccepts(example)).toBe(true); + expect(vortexAccepts(example)).toBe(true); + }, + ); +});