koffing 1.0.0 → 2.0.0

package/README.md

@@ -1,13 +1,100 @@
 # Koffing
 
-![Build Status](https://github.com/itsjavi/koffing/actions/workflows/CI.yml/badge.svg?branch=develop)
+A dependency-free Pokémon Showdown parser and formatter for JavaScript and TypeScript. Supports ESM and CommonJS. The API uses plain data and pure functions; it deliberately replaces the previous classes and `name`/`nickname` schema.
 
-Koffing is a Pokemon Showdown importable-syntax parser for JavaScript and TypeScript.
+```sh
+pnpm add koffing
+```
 
-## Features
+```ts
+import { parse, parseJSON, exportTeam, exportTeams } from "koffing";
 
-- Compatible with Gen 9 Pokémon definitions
-- Online parser
-- JS/TS Library
+const result = parse("Smogon (Koffing) @ Eviolite\nAbility: Levitate\n- Sludge Bomb");
+console.log(result.diagnostics);
+const sets = result.teams[0]!.pokemon;
+// [{ species: "Koffing", name: "Smogon", item: "Eviolite", ... }]
+const json = JSON.stringify(sets, null, 2); // Showdown-shaped set array
+const imported = parseJSON(json);
+const showdown = exportTeam(sets); // No team metadata header
+const backup = exportTeams(imported.teams); // Preserves named team metadata
+```
 
-> The full version of this README file can be found at https://github.com/itsjavi/koffing
+## Parsing and diagnostics
+
+`parse(text, options?)` returns `{ teams, diagnostics }`. Each team contains `pokemon: PokemonSet[]` and optional `name`, `format`, and `folder`. Headerless input does not invent metadata. `parseJSON(value, options?)` accepts JSON text or plain data: a single set, an array of sets, a `{ pokemon, ...metadata }` team, or a `{ teams }` collection.
+
+Set fields follow Showdown: required `species` and `moves`, optional `name` for a nickname, plus `item`, `ability`, `gender`, `nature`, `evs`, `ivs`, `level`, `shiny`, `happiness`, `pokeball`, `hpType`, `dynamaxLevel`, `gigantamax`, and `teraType`. Stat tables can be sparse.
+
+Supported text includes nicknames, genders, item headers, team backups, `Trait`/`Friendship`/`Ball` aliases, `Item:`/`Nickname:`/`Species:`/`Move:`, bracketed abilities, bare `Shiny`/`Gigantamax`, and EV nature modifiers. Hidden Power moves use the internal `Hidden Power Ice` form with `hpType`, and export with brackets. Explicit happiness and Hidden Power fields take precedence over inferred values. Unknown species and move names are retained without database lookup.
+
+Permissive mode is the default. Diagnostics identify unknown or malformed lines, duplicate fields, and suspicious numeric values; text diagnostics include one-based line numbers. Supported values are preserved, including levels over 100 and moves beyond four. Strict mode rejects these diagnostics. This is semantic preservation, not a byte-for-byte document editor: whitespace is normalized, repeated fields use the last accepted value, and unsupported lines are omitted with diagnostics. Always inspect diagnostics before replacing the original input.
+
+```ts
+import { parse, KoffingError } from "koffing";
+
+try {
+  parse(input, { mode: "strict" });
+} catch (error) {
+  if (error instanceof KoffingError) console.error(error.diagnostics);
+}
+```
+
+Strict mode throws on parsing diagnostics. Unsafe JSON structures, resource-limit violations, and packed team strings fail in either parsing mode. Packed formats are not interpreted as Pokémon names. Use upstream Showdown for pack/unpack support.
+
+## Parser scope and safety
+
+Koffing retains generic sanity diagnostics for traditional numeric ranges, EV totals, and move counts. These parser checks do not use a game database. Species, moves, abilities, items, natures, balls, and types remain open strings when parsing. New text syntax or fields may still require parser support. The optional `koffing/validator` entry point adds snapshot-based identifier checks; learnsets and format legality remain outside its scope.
+
+### Optional identifier and basic legality validation
+
+```ts
+import { parse } from "koffing";
+import { validate } from "koffing/validator";
+
+const parsed = parse("Koffing @ Eviolite\nAbility: Levitate\n- Sludge Bomb");
+const result = validate({ teams: parsed.teams });
+console.log(result.valid, result.diagnostics);
+// Also accepts a set, set array, team wrapper, or JSON string, like parseJSON.
+```
+
+This separate entry point keeps lookup data out of the core parser bundle. `validate(input, options?)` accepts unknown data without coercion or mutation and returns `{ valid, diagnostics }`. It checks runtime field types, known fields, finite integers, level 1–100, happiness 0–255, Dynamax level 0–10, IVs 0–31, EVs 0–255 with a 510 total, one to six Pokémon per team, and one to four distinct moves. EVs retain the historical 255 cap because no generation is assumed. Missing optional fields and empty optional strings remain unspecified. Shape failures return the first error; other checks can return multiple errors. Strict mode throws on diagnostics; resource-limit violations always throw. Inspect parser diagnostics separately when validating parsed text.
+
+Species, moves, items, abilities, natures, balls, Hidden Power types, and Tera types are checked against committed JSON tables. Display names and lowercase alphanumeric IDs compare equivalently; aliases are not resolved. Balls must be ball items; Hidden Power excludes Normal, Fairy, and Stellar. Typed Hidden Power variants count as one move for duplicate checks. Snapshot identifiers include past and nonstandard Showdown entries. A passing result is only a basic sanity check: it does not prove obtainability, species/ability compatibility, learnsets, event restrictions, generation availability, battle-form eligibility, or format legality. Species/item clauses and generation-specific EV rules are intentionally not imposed.
+
+Run `pnpm --filter koffing lookups:generate` to dump sorted, deduplicated IDs from the lockfile-pinned development-only `pokemon-showdown` dependency into `src/lookups/*.json`; `source.json` records its version and scope. `pnpm --filter koffing lookups:check` detects stale tables without writing. Review and commit regenerated files when updating Showdown. Runtime validation has no Showdown dependency or network requests.
+
+### Validation and explicit sanitization
+
+```ts
+import { validateTeam, sanitizeTeam } from "koffing";
+
+const issues = validateTeam(sets);
+const { pokemon, diagnostics } = sanitizeTeam(sets, {
+  maxLevel: 100,
+  maxMovesPerPokemon: 4,
+});
+```
+
+`validateTeam` reports generic numeric ranges, move counts, and EV totals. `sanitizeTeam` clones input, clamps supported numeric fields and truncates moves only when explicitly called, and reports changes. EVs use a 510-point budget allocated in HP, Atk, Def, SpA, SpD, Spe order, capped at 255 per stat. It is not a competitive legality validator. Sanitizing does not establish legality or choose an optimal EV distribution.
+
+`exportTeam(pokemon)` and `exportTeams(teams)` follow Showdown's trusted-object approach: they read typed data directly without cloning, descriptor inspection, unknown-property checks, diagnostics, or resource budgets. They accept no parsing options. Extra properties are ignored and nonfinite numbers are omitted; finite values, explicit defaults, and extra moves are preserved. For untrusted input, call `parseJSON` or `validateTeam` explicitly before export. Export does not escape delimiters or control characters, so callers are responsible for supplying representable text fields; arbitrary strings need not round-trip. Exports are Showdown text, not HTML.
+
+## Resource limits
+
+Parsing and validation entry points accept `limits` overrides. Defaults are 2,000,000 UTF-16 input code units, 16,384 code units per line, 1,000 teams, 10,000 Pokémon in total, 256 moves per Pokémon, and 1,000 diagnostics. Limits are resource budgets, not battle rules. Exceeding a limit throws; it never returns a silently truncated collection. Overrides must be positive safe integers.
+
+For object inputs to parsing and validation, the input budget conservatively counts known string lengths plus 32 units per string and 512 per set. Small custom budgets may therefore reject objects whose compact JSON would fit. Export does not impose input or output budgets.
+
+```ts
+parse(input, { limits: { maxInputLength: 100_000, maxPokemon: 60 } });
+```
+
+JSON parsing and validation accept ordinary data objects and reject accessor properties and non-plain records. Export reads properties directly, including getters. JavaScript proxies are executable objects and should not be treated as untrusted JSON; accept JSON text at trust boundaries.
+
+## Compatibility and verification
+
+The compatibility target is Showdown's exported text and sparse `PokemonSet` shape. Koffing retains backup metadata separately. Formatting need not be byte-identical to Showdown: explicit defaults can remain visible and harmless whitespace differs. Species aliases, generation-specific defaults, Hidden Power IV inference, and legality checks require game data and are intentionally not inferred by the core. Call a game-data resolver or Showdown validator separately when needed.
+
+Differential tests compare supported semantic behavior with the official server implementation. The development-only reference version and source commit are recorded in `test/upstream.json`, and `pnpm-lock.yaml` fixes its installation. This dependency also supplies the optional validator's generated ID tables. Updating the reference requires reviewing its expectations and regenerating those tables. Additional tests cover client syntax, old fixtures, malformed inputs, limits, serialization boundaries, optional validation, and round trips. There are no web app tests.
+
+Run `pnpm test` for tests and `pnpm bench` for Vitest benchmarks. Benchmarks cover normal teams, large backups, and malformed long lines; they are observations rather than CI speed thresholds. Upstream and Koffing perform different validation and metadata work, so throughput is not a like-for-like measure of every feature.

package/dist/data-CP51LAc9.cjs

@@ -0,0 +1,404 @@
+//#region src/limits.ts
+const DEFAULT_LIMITS = Object.freeze({
+	maxInputLength: 2e6,
+	maxLineLength: 16384,
+	maxTeams: 1e3,
+	maxPokemon: 1e4,
+	maxMoves: 256,
+	maxDiagnostics: 1e3
+});
+var KoffingError = class extends Error {
+	diagnostics;
+	constructor(message, diagnostics) {
+		super(message);
+		this.name = "KoffingError";
+		this.diagnostics = diagnostics;
+	}
+};
+function resolveLimits(options = {}) {
+	if (options.mode !== void 0 && options.mode !== "strict" && options.mode !== "permissive") throw new TypeError("mode must be strict or permissive");
+	if (options.limits === void 0) return DEFAULT_LIMITS;
+	const limits = {
+		...DEFAULT_LIMITS,
+		...options.limits
+	};
+	for (const [key, value] of Object.entries(limits)) if (!Number.isSafeInteger(value) || value < 1) throw new TypeError(`${key} must be a positive safe integer`);
+	return limits;
+}
+function fail(code, message, line) {
+	throw new KoffingError(message, [{
+		code,
+		message,
+		severity: "error",
+		...line === void 0 ? {} : { line }
+	}]);
+}
+function checkInput(input, limits) {
+	if (typeof input !== "string") throw new TypeError("Input must be a string");
+	if (input.length > limits.maxInputLength) fail("input-limit", `Input exceeds ${limits.maxInputLength} code units`);
+}
+function finish(diagnostics, options) {
+	if (options.mode === "strict" && diagnostics.length) throw new KoffingError(diagnostics[0].message, diagnostics);
+}
+function report(diagnostics, diagnostic, limits) {
+	if (diagnostics.length >= limits.maxDiagnostics) fail("diagnostic-limit", "Too many parsing issues", diagnostic.line);
+	diagnostics.push(diagnostic);
+}
+//#endregion
+//#region src/data.ts
+const strings = [
+	"species",
+	"name",
+	"item",
+	"ability",
+	"nature",
+	"pokeball",
+	"hpType",
+	"teraType"
+];
+const numbers = [
+	"level",
+	"happiness",
+	"dynamaxLevel"
+];
+const flags = ["shiny", "gigantamax"];
+const stats = [
+	"hp",
+	"atk",
+	"def",
+	"spa",
+	"spd",
+	"spe"
+];
+const statKeys = new Set(stats);
+const teamKeys = /* @__PURE__ */ new Set([
+	"name",
+	"format",
+	"folder",
+	"pokemon"
+]);
+const collectionKeys = /* @__PURE__ */ new Set(["teams"]);
+const setKeys = /* @__PURE__ */ new Set([
+	...strings,
+	...numbers,
+	...flags,
+	"gender",
+	"evs",
+	"ivs",
+	"moves"
+]);
+function objectKeys(value, path, limits) {
+	if (typeof value !== "object" || value === null || Array.isArray(value) || Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) fail("invalid-json", `${path} must be a plain object`);
+	const keys = Reflect.ownKeys(value);
+	if (keys.length > limits.maxDiagnostics + 32) fail("property-limit", `${path} contains too many properties`);
+	return keys;
+}
+function property(value, key, path, limits) {
+	const descriptor = Object.getOwnPropertyDescriptor(value, key);
+	if (typeof key !== "string" || !("value" in descriptor)) fail("invalid-json", `${path} contains an accessor or symbol`);
+	if (key.length > Math.max(32, limits.maxLineLength)) fail("property-limit", `${path} contains an oversized property name`);
+	return descriptor.value;
+}
+function object(value, path, limits) {
+	const keys = objectKeys(value, path, limits);
+	const result = Object.create(null);
+	for (const key of keys) result[key] = property(value, key, path, limits);
+	return result;
+}
+function array(value, path, maximum) {
+	if (!Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype) fail("invalid-json", `${path} must be an array`);
+	if (value.length > maximum) fail("collection-limit", `${path} exceeds ${maximum} entries`);
+	if (Reflect.ownKeys(value).length !== value.length + 1) fail("invalid-json", `${path} contains non-index properties or holes`);
+	const result = [];
+	for (let i = 0; i < value.length; i++) {
+		const descriptor = Object.getOwnPropertyDescriptor(value, String(i));
+		if (!descriptor || !("value" in descriptor)) fail("invalid-json", `${path} must not contain holes or accessors`);
+		result.push(descriptor.value);
+	}
+	return result;
+}
+function text(value, path, limits, budget) {
+	if (typeof value !== "string" || /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/u.test(value) || value !== value.trim()) fail("invalid-text", `${path} must be trimmed text without control characters`);
+	if (value.length > limits.maxLineLength) fail("line-limit", `${path} exceeds ${limits.maxLineLength} code units`);
+	budget.used += value.length + 32;
+	if (budget.used > limits.maxInputLength) fail("input-limit", "Aggregate data exceeds configured input limit");
+	return value;
+}
+function finite(value, path) {
+	if (typeof value !== "number" || !Number.isFinite(value)) fail("invalid-number", `${path} must be finite`);
+	return value;
+}
+function unknownKeys(source, known, path, diagnostics, limits) {
+	for (const key of Object.keys(source)) if (!known.has(key)) report(diagnostics, {
+		code: "unknown-field",
+		severity: "warning",
+		path: `${path}.${key}`,
+		message: `Unknown field ${path}.${key}`
+	}, limits);
+}
+function readSet(value, path, diagnostics, limits, budget) {
+	const keys = objectKeys(value, path, limits);
+	budget.used += 512;
+	if (budget.used > limits.maxInputLength) fail("input-limit", "Aggregate data exceeds configured input limit");
+	const result = {
+		species: "",
+		moves: []
+	};
+	let hasMoves = false;
+	for (const rawKey of keys) {
+		const entry = property(value, rawKey, path, limits);
+		const key = rawKey;
+		if (!setKeys.has(key)) {
+			report(diagnostics, {
+				code: "unknown-field",
+				severity: "warning",
+				path: `${path}.${key}`,
+				message: `Unknown field ${path}.${key}`
+			}, limits);
+			continue;
+		}
+		if (entry === void 0 && key !== "species" && key !== "moves") continue;
+		switch (key) {
+			case "species":
+			case "name":
+			case "item":
+			case "ability":
+			case "nature":
+			case "pokeball":
+			case "hpType":
+			case "teraType":
+				result[key] = text(entry, `${path}.${key}`, limits, budget);
+				break;
+			case "level":
+			case "happiness":
+			case "dynamaxLevel":
+				result[key] = finite(entry, `${path}.${key}`);
+				break;
+			case "shiny":
+			case "gigantamax":
+				if (typeof entry !== "boolean") fail("invalid-boolean", `${path}.${key} must be boolean`);
+				result[key] = entry;
+				break;
+			case "gender":
+				if (entry !== "M" && entry !== "F" && entry !== "N" && entry !== "") fail("invalid-gender", `${path}.gender must be M, F, N or empty`);
+				result.gender = entry;
+				break;
+			case "evs":
+			case "ivs": {
+				const statPath = `${path}.${key}`;
+				const values = {};
+				for (const rawStat of objectKeys(entry, statPath, limits)) {
+					const number = property(entry, rawStat, statPath, limits);
+					const stat = rawStat;
+					if (!statKeys.has(stat)) report(diagnostics, {
+						code: "unknown-field",
+						severity: "warning",
+						path: `${statPath}.${stat}`,
+						message: `Unknown field ${statPath}.${stat}`
+					}, limits);
+					else if (number !== void 0) values[stat] = finite(number, `${statPath}.${stat}`);
+				}
+				result[key] = values;
+				break;
+			}
+			case "moves": {
+				hasMoves = true;
+				const moves = array(entry, `${path}.moves`, limits.maxMoves);
+				for (let index = 0; index < moves.length; index++) if (!text(moves[index], `${path}.moves[${index}]`, limits, budget)) fail("invalid-move", `${path}.moves[${index}] cannot be empty`);
+				result.moves = moves;
+				break;
+			}
+		}
+	}
+	if (!result.species) fail("invalid-species", `${path}.species is required`);
+	if (!hasMoves) fail("invalid-json", `${path}.moves must be an array`);
+	return result;
+}
+/** Decode and copy known data only. Shape errors are fatal; unknown fields are diagnosed. */
+function parseJSON(input, options = {}) {
+	const limits = resolveLimits(options);
+	let value = input;
+	if (typeof value === "string") {
+		checkInput(value, limits);
+		try {
+			value = JSON.parse(value);
+		} catch {
+			fail("invalid-json", "Invalid JSON syntax");
+		}
+	}
+	const diagnostics = [];
+	const budget = { used: 0 };
+	let rawTeams;
+	if (Array.isArray(value)) rawTeams = [{ pokemon: value }];
+	else {
+		const source = object(value, "input", limits);
+		if (Object.hasOwn(source, "teams")) {
+			unknownKeys(source, collectionKeys, "input", diagnostics, limits);
+			rawTeams = array(source.teams, "teams", limits.maxTeams);
+		} else if (Object.hasOwn(source, "pokemon")) rawTeams = [source];
+		else rawTeams = [{ pokemon: [source] }];
+	}
+	if (rawTeams.length > limits.maxTeams) fail("collection-limit", "Too many teams");
+	let total = 0;
+	const teams = rawTeams.map((raw, index) => {
+		const path = `teams[${index}]`;
+		const source = object(raw, path, limits);
+		unknownKeys(source, teamKeys, path, diagnostics, limits);
+		const members = array(source.pokemon, `${path}.pokemon`, limits.maxPokemon - total);
+		total += members.length;
+		const team = { pokemon: members.map((member, i) => readSet(member, `${path}.pokemon[${i}]`, diagnostics, limits, budget)) };
+		for (const key of [
+			"name",
+			"format",
+			"folder"
+		]) if (source[key] !== void 0) team[key] = text(source[key], `${path}.${key}`, limits, budget);
+		return team;
+	});
+	for (const [index, team] of teams.entries()) checkRanges(team.pokemon, `teams[${index}].pokemon`, diagnostics, limits);
+	finish(diagnostics, options);
+	return {
+		teams,
+		diagnostics
+	};
+}
+/** Generic traditional-format checks, not species or format legality validation. */
+function checkRanges(pokemon, path, diagnostics, limits) {
+	const add = (code, path, message) => report(diagnostics, {
+		code,
+		severity: "warning",
+		path,
+		message
+	}, limits);
+	for (const [i, set] of pokemon.entries()) {
+		const prefix = `${path}[${i}]`;
+		const range = (value, min, max, field, code = "number-range") => {
+			if (value !== void 0 && (!Number.isInteger(value) || value < min || value > max)) add(code, `${prefix}.${field}`, `Expected an integer from ${min} to ${max}; value preserved`);
+		};
+		range(set.level, 1, 100, "level");
+		range(set.happiness, 0, 255, "happiness");
+		range(set.dynamaxLevel, 0, 10, "dynamaxLevel");
+		let evTotal = 0;
+		for (const stat of stats) {
+			const ev = set.evs?.[stat];
+			const iv = set.ivs?.[stat];
+			if (ev !== void 0) {
+				evTotal += ev;
+				range(ev, 0, 255, `evs.${stat}`, "stat-range");
+			}
+			if (iv !== void 0) range(iv, 0, 31, `ivs.${stat}`, "stat-range");
+		}
+		if (evTotal > 510) add("ev-total", `${prefix}.evs`, "Traditional EV total exceeds 510");
+		if (set.moves.length > 4) add("move-count", `${prefix}.moves`, "Traditional sets contain at most four moves");
+	}
+}
+function validateTeam(pokemon, options = {}) {
+	return parseJSON(pokemon, options).diagnostics;
+}
+/** Explicit, deterministic traditional-range sanitization; never mutates its input. */
+function sanitizeTeam(pokemon, options = {}) {
+	const maxLevel = options.maxLevel ?? 100;
+	const maxMoves = options.maxMovesPerPokemon ?? 4;
+	if (!Number.isSafeInteger(maxLevel) || maxLevel < 1 || !Number.isSafeInteger(maxMoves) || maxMoves < 0) throw new TypeError("Sanitization limits must be valid nonnegative integers (maxLevel >= 1)");
+	const parsed = parseJSON(pokemon, {
+		...options,
+		mode: "permissive"
+	});
+	const result = parsed.teams[0].pokemon;
+	const diagnostics = parsed.diagnostics;
+	const limits = resolveLimits(options);
+	const changed = (path) => report(diagnostics, {
+		code: "sanitized",
+		severity: "warning",
+		path,
+		message: `Sanitized ${path}`
+	}, limits);
+	const clamp = (value, min, max, path) => {
+		const next = Math.max(min, Math.min(max, Math.trunc(value)));
+		if (next !== value) changed(path);
+		return next;
+	};
+	for (const [i, set] of result.entries()) {
+		const path = `pokemon[${i}]`;
+		if (set.level !== void 0) set.level = clamp(set.level, 1, maxLevel, `${path}.level`);
+		if (set.happiness !== void 0) set.happiness = clamp(set.happiness, 0, 255, `${path}.happiness`);
+		if (set.dynamaxLevel !== void 0) set.dynamaxLevel = clamp(set.dynamaxLevel, 0, 10, `${path}.dynamaxLevel`);
+		let evBudget = 510;
+		for (const stat of stats) {
+			if (set.evs?.[stat] !== void 0) {
+				set.evs[stat] = clamp(set.evs[stat], 0, Math.min(255, evBudget), `${path}.evs.${stat}`);
+				evBudget -= set.evs[stat];
+			}
+			if (set.ivs?.[stat] !== void 0) set.ivs[stat] = clamp(set.ivs[stat], 0, 31, `${path}.ivs.${stat}`);
+		}
+		if (set.moves.length > maxMoves) {
+			set.moves = set.moves.slice(0, maxMoves);
+			changed(`${path}.moves`);
+		}
+	}
+	finish(diagnostics, options);
+	return {
+		pokemon: result,
+		diagnostics
+	};
+}
+//#endregion
+Object.defineProperty(exports, "DEFAULT_LIMITS", {
+	enumerable: true,
+	get: function() {
+		return DEFAULT_LIMITS;
+	}
+});
+Object.defineProperty(exports, "KoffingError", {
+	enumerable: true,
+	get: function() {
+		return KoffingError;
+	}
+});
+Object.defineProperty(exports, "checkInput", {
+	enumerable: true,
+	get: function() {
+		return checkInput;
+	}
+});
+Object.defineProperty(exports, "fail", {
+	enumerable: true,
+	get: function() {
+		return fail;
+	}
+});
+Object.defineProperty(exports, "finish", {
+	enumerable: true,
+	get: function() {
+		return finish;
+	}
+});
+Object.defineProperty(exports, "parseJSON", {
+	enumerable: true,
+	get: function() {
+		return parseJSON;
+	}
+});
+Object.defineProperty(exports, "report", {
+	enumerable: true,
+	get: function() {
+		return report;
+	}
+});
+Object.defineProperty(exports, "resolveLimits", {
+	enumerable: true,
+	get: function() {
+		return resolveLimits;
+	}
+});
+Object.defineProperty(exports, "sanitizeTeam", {
+	enumerable: true,
+	get: function() {
+		return sanitizeTeam;
+	}
+});
+Object.defineProperty(exports, "validateTeam", {
+	enumerable: true,
+	get: function() {
+		return validateTeam;
+	}
+});