@cobbled-creators/cobblemon-schemas 1.7.0

package/schemas/species_additions/schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://cobblemon-schema.local/species_additions/schema.json",
+  "title": "Cobblemon Species Addition",
+  "type": "object",
+  "properties": {
+    "target": {
+      "$ref": "../_shared/defs/identifiers.schema.json#/$defs/identifier"
+    }
+  },
+  "required": [
+    "target"
+  ],
+  "additionalProperties": true,
+  "allOf": [
+    {
+      "not": {
+        "maxProperties": 1
+      }
+    }
+  ]
+}

package/schemas/species_feature_assignments/schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://cobblemon-schema.local/species_feature_assignments/schema.json",
+  "title": "Cobblemon Species Feature Assignment",
+  "type": "object",
+  "properties": {
+    "pokemon": {
+      "type": "array",
+      "items": {
+        "$ref": "../_shared/defs/pokemon.schema.json#/$defs/pokemonProperties"
+      }
+    },
+    "features": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "required": [
+    "pokemon",
+    "features"
+  ],
+  "additionalProperties": false
+}

package/schemas/species_features/schema.json

@@ -0,0 +1,139 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://cobblemon-schema.local/species_features/schema.json",
+  "title": "Cobblemon Species Feature Provider",
+  "type": "object",
+  "properties": {
+    "type": {
+      "type": "string",
+      "enum": [
+        "choice",
+        "flag",
+        "integer"
+      ]
+    },
+    "keys": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string"
+      }
+    },
+    "default": {
+      "oneOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "integer"
+        },
+        {
+          "type": "boolean"
+        }
+      ]
+    },
+    "visible": {
+      "type": "boolean"
+    },
+    "needsKey": {
+      "type": "boolean"
+    },
+    "choices": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "isAspect": {
+      "type": "boolean"
+    },
+    "aspectFormat": {
+      "type": "string"
+    },
+    "min": {
+      "type": "integer"
+    },
+    "max": {
+      "type": "integer"
+    },
+    "display": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "colour": {
+          "type": "array",
+          "minItems": 3,
+          "maxItems": 3,
+          "items": {
+            "type": "number"
+          }
+        },
+        "color": {
+          "type": "array",
+          "minItems": 3,
+          "maxItems": 3,
+          "items": {
+            "type": "number"
+          }
+        },
+        "underlay": {
+          "$ref": "../_shared/defs/identifiers.schema.json#/$defs/identifier"
+        },
+        "overlay": {
+          "$ref": "../_shared/defs/identifiers.schema.json#/$defs/identifier"
+        }
+      },
+      "additionalProperties": false
+    },
+    "itemPoints": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "integer"
+      }
+    }
+  },
+  "required": [
+    "type",
+    "keys"
+  ],
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "type": {
+            "const": "choice"
+          }
+        },
+        "required": [
+          "type"
+        ]
+      },
+      "then": {
+        "required": [
+          "choices"
+        ]
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "type": {
+            "const": "integer"
+          }
+        },
+        "required": [
+          "type"
+        ]
+      },
+      "then": {
+        "required": [
+          "min",
+          "max"
+        ]
+      }
+    }
+  ],
+  "additionalProperties": false
+}

package/schemas/starters/schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://cobblemon-schema.local/starters/schema.json",
+  "title": "Cobblemon Starter Category",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 1
+    },
+    "displayName": {
+      "type": "string",
+      "minLength": 1
+    },
+    "pokemon": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "../_shared/defs/pokemon.schema.json#/$defs/pokemonProperties"
+      }
+    }
+  },
+  "required": [
+    "name",
+    "pokemon"
+  ],
+  "additionalProperties": false
+}

package/schemas/unlockable_pc_box_wallpapers/schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://cobblemon-schema.local/unlockable_pc_box_wallpapers/schema.json",
+  "title": "Cobblemon Unlockable PC Box Wallpaper",
+  "type": "object",
+  "properties": {
+    "enabled": {
+      "type": "boolean"
+    },
+    "displayName": {
+      "oneOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "texture": {
+      "$ref": "../_shared/defs/identifiers.schema.json#/$defs/identifier"
+    }
+  },
+  "required": [
+    "enabled",
+    "texture"
+  ],
+  "additionalProperties": false
+}

package/src/errors/format.mjs

@@ -0,0 +1,46 @@
+import { asRecord, stringArray } from './values.mjs';
+
+const MAX_LISTED_VALUES = 8;
+
+export function formatAjvError(error) {
+  const params = error.params ?? {};
+  switch (error.keyword) {
+    case 'required':
+      return `Missing required property '${params.missingProperty}'.`;
+    case 'additionalProperties':
+      return `Unknown property '${params.additionalProperty}'.`;
+    case 'enum':
+      return `Value must be one of: ${listValues(params.allowedValues ?? [])}.`;
+    case 'const':
+      return `Value must be ${JSON.stringify(params.allowedValue)}.`;
+    case 'type':
+      return `Expected type '${params.type}'.`;
+    case 'minProperties':
+      return `Object must define at least ${countProperties(params.limit)}.`;
+    case 'not':
+      return formatNot(asRecord(asRecord(error.parentSchema)?.not));
+    case 'oneOf':
+      return 'Value must match exactly one supported schema shape.';
+    case 'anyOf':
+      return 'Value does not match any supported schema shape.';
+    default:
+      return error.message ?? 'Validation failed';
+  }
+}
+
+function formatNot(notSchema) {
+  if (typeof notSchema?.maxProperties === 'number') return `Object must define more than ${countProperties(notSchema.maxProperties)}.`;
+  const disallowed = stringArray(notSchema?.required);
+  if (disallowed.length === 1) return `Property '${disallowed[0]}' is not allowed in this context.`;
+  if (disallowed.length > 1) return `These properties are not allowed in this context: ${disallowed.join(', ')}.`;
+  return 'Value matches a disallowed schema shape.';
+}
+
+function listValues(values) {
+  const shown = values.slice(0, MAX_LISTED_VALUES).map((value) => JSON.stringify(value)).join(', ');
+  return values.length > MAX_LISTED_VALUES ? `${shown}, ...` : shown;
+}
+
+function countProperties(count) {
+  return `${count} ${count === 1 ? 'property' : 'properties'}`;
+}

package/src/errors/pointer.mjs

@@ -0,0 +1,30 @@
+export function decodePointer(pointer) {
+  if (!pointer || pointer === '/') return [];
+  return pointer
+    .split('/')
+    .slice(1)
+    .map(unescapeSegment)
+    .map((segment) => (/^[0-9]+$/.test(segment) ? Number.parseInt(segment, 10) : segment));
+}
+
+export function parentPointer(pointer) {
+  const lastSlash = pointer.lastIndexOf('/');
+  return lastSlash <= 0 ? '' : pointer.slice(0, lastSlash);
+}
+
+export function isBelow(pointer, ancestor) {
+  return pointer.startsWith(ancestor ? `${ancestor}/` : '/');
+}
+
+export function valueAt(root, pointer) {
+  let current = root;
+  for (const segment of decodePointer(pointer)) {
+    if (current === null || typeof current !== 'object') return undefined;
+    current = current[segment];
+  }
+  return current;
+}
+
+function unescapeSegment(segment) {
+  return segment.replace(/~1/g, '/').replace(/~0/g, '~');
+}

package/src/errors/simplify.mjs

@@ -0,0 +1,58 @@
+import { isBelow, parentPointer } from './pointer.mjs';
+import { findTypeBranches } from './type-branches.mjs';
+
+const COMBINATOR_KEYWORDS = new Set(['anyOf', 'oneOf', 'if']);
+
+export function simplifyAjvErrors(errors, rootData) {
+  const branches = findTypeBranches(errors, rootData);
+  const meaningful = errors.filter((error) =>
+    !isOtherBranchError(error, branches)
+    && !isParentTypeError(error, errors)
+    && !isRedundantCombinatorError(error, errors));
+  return withoutDuplicates(meaningful);
+}
+
+function isOtherBranchError(error, branches) {
+  if (error.keyword === 'required') return isRequiredByOtherBranch(error, branches.get(error.instancePath));
+  if (error.keyword === 'const' && error.instancePath.endsWith('/type')) {
+    return isOtherBranchTypeConst(error, branches.get(parentPointer(error.instancePath)));
+  }
+  return false;
+}
+
+function isRequiredByOtherBranch(error, branch) {
+  const missing = error.params?.missingProperty;
+  if (!missing || !branch?.actualType) return false;
+  if (branch.selectedRequired.size > 0) return !branch.selectedRequired.has(missing);
+  return branch.typeIsInvalid || branch.hasOtherErrorsInside;
+}
+
+function isOtherBranchTypeConst(error, branch) {
+  if (!branch?.actualType) return false;
+  if (branch.typeIsInvalid || branch.hasOtherErrorsInside) return true;
+  if (branch.selectedRequired.size === 0) return false;
+  return error.params?.allowedValue !== branch.actualType;
+}
+
+function isParentTypeError(error, errors) {
+  if (error.keyword !== 'type' || !error.params?.type) return false;
+  return errors.some((other) => other !== error && !COMBINATOR_KEYWORDS.has(other.keyword) && isBelow(other.instancePath, error.instancePath));
+}
+
+function isRedundantCombinatorError(error, errors) {
+  if (!COMBINATOR_KEYWORDS.has(error.keyword)) return false;
+  return errors.some((other) =>
+    other !== error
+    && !COMBINATOR_KEYWORDS.has(other.keyword)
+    && (other.instancePath === error.instancePath || isBelow(other.instancePath, error.instancePath)));
+}
+
+function withoutDuplicates(errors) {
+  const seen = new Set();
+  return errors.filter((error) => {
+    const key = `${error.keyword}|${error.instancePath}|${error.schemaPath}|${JSON.stringify(error.params)}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}

package/src/errors/type-branches.mjs

@@ -0,0 +1,65 @@
+import { isBelow, parentPointer, valueAt } from './pointer.mjs';
+import { asRecord, stringArray } from './values.mjs';
+
+const BRANCH_KEYWORDS = new Set(['anyOf', 'oneOf', 'if', 'const', 'required']);
+
+export function findTypeBranches(errors, rootData) {
+  const branches = new Map();
+  for (const [objectPointer, branch] of collectBranches(errors, rootData)) {
+    branches.set(objectPointer, summarizeBranch(objectPointer, branch, errors));
+  }
+  return branches;
+}
+
+function collectBranches(errors, rootData) {
+  const branches = new Map();
+  for (const error of errors) {
+    const parentSchema = asRecord(error.parentSchema);
+    const branchType = asRecord(asRecord(parentSchema?.properties)?.type)?.const;
+    if (typeof branchType !== 'string') continue;
+
+    const objectPointer = error.instancePath.endsWith('/type') ? parentPointer(error.instancePath) : error.instancePath;
+    if (!objectPointer) continue;
+
+    if (!branches.has(objectPointer)) {
+      branches.set(objectPointer, { actualType: typeAt(rootData, objectPointer), requiredByType: new Map() });
+    }
+    const { requiredByType } = branches.get(objectPointer);
+    const required = requiredByType.get(branchType) ?? new Set();
+    for (const field of requiredFields(parentSchema)) required.add(field);
+    requiredByType.set(branchType, required);
+  }
+  return branches;
+}
+
+function summarizeBranch(objectPointer, { actualType, requiredByType }, errors) {
+  const typePointer = `${objectPointer}/type`;
+  const typeIsInvalid = errors.some((error) => error.instancePath === typePointer && (error.keyword === 'enum' || error.keyword === 'type'));
+  const hasOtherErrorsInside = errors.some((error) =>
+    error.instancePath !== typePointer
+    && isBelow(error.instancePath, objectPointer)
+    && !BRANCH_KEYWORDS.has(error.keyword));
+
+  return {
+    actualType,
+    selectedRequired: (actualType && requiredByType.get(actualType)) || new Set(),
+    typeIsInvalid,
+    hasOtherErrorsInside,
+  };
+}
+
+function requiredFields(schema) {
+  const fields = new Set(stringArray(schema.required));
+  for (const combinator of [schema.anyOf, schema.oneOf]) {
+    if (!Array.isArray(combinator)) continue;
+    for (const option of combinator) {
+      for (const field of stringArray(asRecord(option)?.required)) fields.add(field);
+    }
+  }
+  return fields;
+}
+
+function typeAt(rootData, pointer) {
+  const type = asRecord(valueAt(rootData, pointer))?.type;
+  return typeof type === 'string' ? type : undefined;
+}

package/src/errors/values.mjs

@@ -0,0 +1,7 @@
+export function asRecord(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+
+export function stringArray(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
+}

package/src/index.d.ts

@@ -0,0 +1,74 @@
+export type Pointer = Array<string | number>;
+
+export interface CobblemonTarget {
+  version: string;
+  minecraft: string;
+  baseline: string;
+}
+
+export interface SchemaEntry {
+  path: string;
+  id?: string;
+  dataPath?: string;
+  validator?: string;
+}
+
+export interface Bundle {
+  package: string;
+  cobblemon: CobblemonTarget;
+  entries: SchemaEntry[];
+}
+
+export interface SchemaError {
+  pointer: Pointer;
+  keyword: string;
+  params: Record<string, unknown>;
+  message: string;
+}
+
+export type ValidateFunction = ((value: unknown) => boolean) & { errors?: unknown[] | null };
+
+export class SchemaEngine {
+  constructor(options: { entries: SchemaEntry[]; validators: Record<string, ValidateFunction>; cobblemon?: CobblemonTarget | null });
+  static fromBundle(bundle: Bundle, compiled: Record<string, ValidateFunction>): SchemaEngine;
+  readonly cobblemon: CobblemonTarget | null;
+  resolve(relPath: string): string | undefined;
+  validate(schemaPath: string, value: unknown): SchemaError[];
+  check(relPath: string, value: unknown): { schema: string | null; errors: SchemaError[] };
+}
+
+export function simplifyAjvErrors<T>(errors: T[], rootData: unknown): T[];
+export function formatAjvError(error: unknown): string;
+export function decodePointer(pointer: string): Pointer;
+
+export interface Position {
+  line: number;
+  column: number;
+}
+
+export interface ParsedJson {
+  value: unknown;
+  ok: boolean;
+  syntaxErrors: Array<Position & { message: string }>;
+  locate(pointer: Pointer): Position | Record<string, never>;
+}
+
+export function parseJson(bytes: Uint8Array | string): ParsedJson;
+
+export interface PackError {
+  kind: 'syntax' | 'schema';
+  pointer: Pointer;
+  message: string;
+  line?: number;
+  column?: number;
+  keyword?: string;
+  params?: Record<string, unknown>;
+}
+
+export interface PackResult {
+  file: string;
+  schema: string;
+  errors: PackError[];
+}
+
+export function validatePack(files: Map<string, Uint8Array | string>, engine: SchemaEngine): PackResult[];

package/src/index.mjs

@@ -0,0 +1,6 @@
+export { SchemaEngine } from './schema-engine.mjs';
+export { simplifyAjvErrors } from './errors/simplify.mjs';
+export { formatAjvError } from './errors/format.mjs';
+export { decodePointer } from './errors/pointer.mjs';
+export { parseJson } from './json/parse-json.mjs';
+export { validatePack } from './validate-pack.mjs';

package/src/json/line-index.mjs

@@ -0,0 +1,21 @@
+export function createLineIndex(text) {
+  const lineStarts = [0];
+  for (let offset = 0; offset < text.length; offset += 1) {
+    if (text.charCodeAt(offset) === 10) lineStarts.push(offset + 1);
+  }
+  return (offset) => {
+    const line = lineContaining(lineStarts, offset);
+    return { line: line + 1, column: offset - lineStarts[line] + 1 };
+  };
+}
+
+function lineContaining(lineStarts, offset) {
+  let low = 0;
+  let high = lineStarts.length - 1;
+  while (low < high) {
+    const middle = (low + high + 1) >> 1;
+    if (lineStarts[middle] <= offset) low = middle;
+    else high = middle - 1;
+  }
+  return low;
+}

package/src/json/parse-json.mjs

@@ -0,0 +1,28 @@
+import { findNodeAtLocation, parse, parseTree } from 'jsonc-parser';
+import { createLineIndex } from './line-index.mjs';
+import { describeSyntaxErrors } from './syntax-errors.mjs';
+
+const STRICT_COMMAS = { allowTrailingComma: false, disallowComments: false };
+const LENIENT_COMMAS = { allowTrailingComma: true, disallowComments: false };
+
+export function parseJson(content) {
+  const text = withoutBom(typeof content === 'string' ? content : new TextDecoder('utf-8', { ignoreBOM: true }).decode(content));
+  const positionOf = createLineIndex(text);
+  const parseErrors = [];
+  const value = parse(text, parseErrors, STRICT_COMMAS);
+  const tree = parseTree(text, [], LENIENT_COMMAS);
+
+  return {
+    value,
+    ok: parseErrors.length === 0,
+    syntaxErrors: describeSyntaxErrors(text, parseErrors, positionOf),
+    locate(pointer) {
+      const node = tree && findNodeAtLocation(tree, pointer);
+      return node ? positionOf(node.offset) : {};
+    },
+  };
+}
+
+function withoutBom(text) {
+  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}

package/src/json/syntax-errors.mjs

@@ -0,0 +1,56 @@
+import { createScanner, printParseErrorCode, SyntaxKind } from 'jsonc-parser';
+
+const MESSAGES = {
+  InvalidSymbol: 'Unexpected character.',
+  InvalidNumberFormat: 'Invalid number.',
+  PropertyNameExpected: 'Expected a property name.',
+  ValueExpected: 'Expected a value.',
+  ColonExpected: 'Expected ":".',
+  CommaExpected: 'Expected ",".',
+  CloseBraceExpected: 'Expected "}".',
+  CloseBracketExpected: 'Expected "]".',
+  EndOfFileExpected: 'Unexpected content after the end of the JSON.',
+  UnexpectedEndOfComment: 'Unclosed comment.',
+  UnexpectedEndOfString: 'Unclosed string.',
+  UnexpectedEndOfNumber: 'Incomplete number.',
+  InvalidUnicode: 'Invalid unicode escape.',
+  InvalidEscapeCharacter: 'Invalid escape character.',
+  InvalidCharacter: 'Invalid character in string.',
+};
+
+const CLOSING_BRACKETS = '}]';
+const ERRORS_AFTER_TRAILING_COMMA = new Set(['PropertyNameExpected', 'ValueExpected']);
+
+export function describeSyntaxErrors(text, parseErrors, positionOf) {
+  const described = [];
+  const reportedOffsets = new Set();
+  for (const parseError of parseErrors) {
+    const { message, offset } = describe(text, parseError);
+    if (reportedOffsets.has(offset)) continue;
+    reportedOffsets.add(offset);
+    described.push({ message, ...positionOf(offset) });
+  }
+  return described;
+}
+
+function describe(text, { error, offset }) {
+  const code = printParseErrorCode(error);
+  const trailingComma = findTrailingComma(text, code, offset);
+  if (trailingComma !== null) return { message: 'Trailing comma.', offset: trailingComma };
+  return { message: MESSAGES[code] ?? code, offset };
+}
+
+function findTrailingComma(text, code, offset) {
+  if (!CLOSING_BRACKETS.includes(text[offset]) || !ERRORS_AFTER_TRAILING_COMMA.has(code)) return null;
+  const previous = tokenBefore(text, offset);
+  return previous?.kind === SyntaxKind.CommaToken ? previous.offset : null;
+}
+
+function tokenBefore(text, offset) {
+  const scanner = createScanner(text, true);
+  let previous = null;
+  for (let kind = scanner.scan(); kind !== SyntaxKind.EOF && scanner.getTokenOffset() < offset; kind = scanner.scan()) {
+    previous = { kind, offset: scanner.getTokenOffset() };
+  }
+  return previous;
+}

package/src/node/load-engine.mjs

@@ -0,0 +1,30 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { SchemaEngine } from '../schema-engine.mjs';
+import { loadSchemas } from './load-schemas.mjs';
+import { cobblemon, distRoot } from './package-info.mjs';
+
+const BUNDLE_FILE = path.join(distRoot, 'bundle.json');
+const VALIDATORS_FILE = path.join(distRoot, 'validators.mjs');
+
+export async function loadEngine({ live = false } = {}) {
+  if (!live && fs.existsSync(BUNDLE_FILE)) return loadBundledEngine();
+  return compileEngine();
+}
+
+async function loadBundledEngine() {
+  const bundle = JSON.parse(fs.readFileSync(BUNDLE_FILE, 'utf8'));
+  const compiled = await import(pathToFileURL(VALIDATORS_FILE).href);
+  return SchemaEngine.fromBundle(bundle, compiled);
+}
+
+function compileEngine() {
+  const { ajv, entries } = loadSchemas();
+  const validators = {};
+  for (const entry of entries) {
+    const validator = entry.id && ajv.getSchema(entry.id);
+    if (validator) validators[entry.path] = validator;
+  }
+  return new SchemaEngine({ entries, validators, cobblemon });
+}