bsdata40k-to-json 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Antone
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,205 @@
+# bsdata40k-to-json
+
+Convert [BSData](https://github.com/BSData) BattleScribe XML for **Warhammer 40,000** into JSON. Turn army list data (factions, units, weapons, abilities, points) from the community-maintained BSData repos into two output formats:
+
+- **Raw** — Faithful 1:1 XML-to-JSON conversion preserving all BattleScribe elements, attributes, and list-builder logic
+- **Curated** — Clean, game-ready JSON: datasheet stats (M, T, SV, W, LD, OC), ranged/melee weapon profiles, abilities, keywords, transport capacity, leader attachments, enhancements, and points per faction
+
+Built for **Warhammer 40,000** (40k) 10th edition data. Use the output for list-building apps, points calculators, roster viewers, or any tool that needs structured 40k game data.
+
+## Install
+
+```bash
+npm install bsdata40k-to-json
+```
+
+Or install globally for CLI access:
+
+```bash
+npm install -g bsdata40k-to-json
+```
+
+## CLI Usage
+
+Pass the input directory (BSData repo) and output directory as two arguments:
+
+```bash
+bsdata40k-to-json ./wh40k-10e ./output
+```
+
+### Options
+
+| Argument / Flag | Description |
+|---|---|
+| `<input-dir>` | Directory containing `.cat` and `.gst` files (required) |
+| `<output-dir>` | Directory to write JSON output (required) |
+| `--raw-only` | Only produce raw (1:1 XML-to-JSON) output |
+| `--curated-only` | Only produce curated game-data output |
+| `--help`, `-h` | Show help message |
+
+### Development scripts
+
+| Command | Description |
+|---|---|
+| `npm run convert -- <input-dir> <output-dir>` | Run both pipelines via `tsx` |
+| `npm run convert:raw -- <input-dir> <output-dir>` | Raw XML-to-JSON only |
+| `npm run convert:curated -- <input-dir> <output-dir>` | Curated extraction only |
+| `npm run build` | Compile TypeScript to `dist/` |
+
+## Library Usage
+
+```typescript
+import { convert } from "bsdata40k-to-json";
+
+const result = await convert({
+  inputDir: "./wh40k-10e",
+  outputDir: "./output",
+  curatedOnly: true,
+});
+
+console.log(`Converted ${result.factionCount} factions`);
+```
+
+Individual extractors are also available:
+
+```typescript
+import {
+  convertFileToRawJson,
+  extractGameSystem,
+  extractCatalogue,
+  discoverFiles,
+} from "bsdata40k-to-json";
+
+const { gstFiles, catFiles } = await discoverFiles("./wh40k-10e");
+const rawJson = await convertFileToRawJson(gstFiles[0]);
+const gameSystem = extractGameSystem(rawJson);
+```
+
+All TypeScript types are exported:
+
+```typescript
+import type {
+  CuratedFaction,
+  CuratedUnit,
+  WeaponProfile,
+  Enhancement,
+  CuratedGameSystem,
+  ConvertOptions,
+  ConvertResult,
+} from "bsdata40k-to-json";
+```
+
+## Output Structure
+
+```
+<output-dir>/
+  raw/                          # 1:1 XML-to-JSON
+    game-system.json            # Warhammer 40,000.gst (core rules, profile types)
+    necrons.json                # One file per faction catalogue (.cat)
+    imperium-space-marines.json
+    ...
+
+  curated/                      # Clean game data
+    game-system.json            # Shared rules (e.g. Blast, Devastating Wounds), profile types, categories
+    factions/
+      necrons.json
+      imperium-space-marines.json
+      ...
+    index.json                  # Faction manifest with unit counts
+```
+
+### What’s in the curated output (40k terms)
+
+- **Factions** — One JSON file per 40k faction (e.g. Necrons, Space Marines, Tyranids), with `name`, `catalogueName`, and all units/enhancements for that army.
+- **Units** — Full datasheet-style data: Movement (M), Toughness (T), Save (SV), Wounds (W), Leadership (LD), Objective Control (OC), plus keywords (Infantry, Character, etc.) and faction keywords.
+- **Weapons** — Ranged and melee weapon profiles with Range, Attacks (A), Ballistic Skill (BS) or Weapon Skill (WS), Strength (S), Armour Penetration (AP), Damage (D), and weapon keywords (e.g. Devastating Wounds, Blast).
+- **Abilities** — Named abilities and their rules text (e.g. *Master Chronomancer*, *Oath of Moment*).
+- **Enhancements** — Detachment enhancements with name, points cost, and description; optional `detachment` when applicable.
+- **Leader attachments** — Which units a character can lead (e.g. Orikan the Diviner → Immortals, Necron Warriors).
+
+## Curated JSON Format (example: Necrons)
+
+Each faction file contains units with full 40k-style datasheets:
+
+```json
+{
+  "id": "b654-a18a-ea1-3bf2",
+  "name": "Necrons",
+  "catalogueName": "Xenos - Necrons",
+  "units": [
+    {
+      "id": "ba86-eaad-5396-fc07",
+      "name": "Orikan the Diviner",
+      "points": 80,
+      "keywords": ["Infantry", "Character", "Epic Hero", "Cryptek"],
+      "factionKeywords": ["Necrons"],
+      "stats": { "M": "5\"", "T": "4", "SV": "4+", "W": "4", "LD": "6+", "OC": "1" },
+      "rangedWeapons": [],
+      "meleeWeapons": [
+        {
+          "name": "Staff of Tomorrow",
+          "range": "Melee",
+          "A": "2",
+          "WS": "3+",
+          "S": "4",
+          "AP": "-3",
+          "D": "D3",
+          "keywords": ["Devastating Wounds"]
+        }
+      ],
+      "abilities": [
+        { "name": "Master Chronomancer", "description": "While this model is leading a unit, models in that unit have a 4+ invulnerable save." }
+      ],
+      "leader": ["Immortals", "Necron Warriors"]
+    }
+  ],
+  "enhancements": [
+    {
+      "name": "Veil of Darkness",
+      "points": 20,
+      "description": "NECRONS model only. Once per battle...",
+      "detachment": "Awakened Dynasty"
+    }
+  ]
+}
+```
+
+## Project Structure
+
+```
+src/
+  cli.ts                         # CLI entry point (arg parsing)
+  index.ts                       # Library entry point (programmatic API + re-exports)
+  raw-converter.ts               # Faithful XML-to-JSON using fast-xml-parser
+  utils.ts                       # File discovery, slugification, helpers
+  curated/
+    types.ts                     # TypeScript interfaces for output shapes
+    extract-game-system.ts       # .gst extractor (rules, profile types, categories)
+    extract-catalogue.ts         # .cat extractor (units, weapons, abilities, enhancements)
+```
+
+## How It Works
+
+1. **Discovery** — Scans the input directory for the 40k game system (`.gst`) and faction catalogues (`.cat`).
+2. **Raw conversion** — Parses each XML file with `fast-xml-parser`, preserving attributes (prefixed with `@_`) and forcing arrays for repeatable elements.
+3. **Curated extraction** — Walks the parsed XML tree to extract 40k game data:
+   - Resolves `entryLink` cross-references (shared units, wargear, weapons) by building an ID lookup map
+   - Recursively collects profiles from nested `selectionEntry`, `selectionEntryGroup`, and `entryLink` elements
+   - Deduplicates weapons by name
+   - Parses leader attachment targets from ability descriptions (e.g. “This model can be attached to…”)
+   - Separates faction keywords (e.g. `Faction: Necrons`) from unit keywords (Infantry, Character, etc.)
+
+## Data Source (Warhammer 40,000)
+
+Input files come from the [BSData](https://github.com/BSData) community-maintained **Warhammer 40,000** data. For 10th edition use the [BSData/wh40k-10e](https://github.com/BSData/wh40k-10e) repository:
+
+```bash
+git clone https://github.com/BSData/wh40k-10e.git
+bsdata40k-to-json ./wh40k-10e ./output
+```
+
+The repo contains the core game system (`Warhammer 40,000.gst`) and one catalogue (`.cat`) per faction (Space Marines, Necrons, Tyranids, etc.). Download or clone the repo and pass its path as the first argument.
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+import { convert } from "./index.js";
+function printUsage() {
+    console.log(`
+bsdata40k-to-json — Convert BSData XML files (.cat/.gst) to JSON
+
+Usage:
+  bsdata40k-to-json <input-dir> <output-dir> [options]
+
+  input-dir   Directory containing .cat and .gst files
+  output-dir  Directory to write JSON output
+
+Options:
+  --raw-only      Only produce raw (1:1 XML-to-JSON) output
+  --curated-only  Only produce curated game-data output
+  --help, -h      Show this help message
+`.trim());
+}
+function parseArgs(argv) {
+    const result = {
+        input: undefined,
+        output: undefined,
+        rawOnly: false,
+        curatedOnly: false,
+        help: false,
+    };
+    const positionals = [];
+    for (let i = 2; i < argv.length; i++) {
+        const arg = argv[i];
+        switch (arg) {
+            case "--raw-only":
+                result.rawOnly = true;
+                break;
+            case "--curated-only":
+                result.curatedOnly = true;
+                break;
+            case "--help":
+            case "-h":
+                result.help = true;
+                break;
+            default:
+                if (arg.startsWith("-")) {
+                    console.error(`Unknown option: ${arg}`);
+                    printUsage();
+                    process.exit(1);
+                }
+                positionals.push(arg);
+        }
+    }
+    if (positionals.length >= 1)
+        result.input = positionals[0];
+    if (positionals.length >= 2)
+        result.output = positionals[1];
+    return result;
+}
+const args = parseArgs(process.argv);
+if (args.help) {
+    printUsage();
+    process.exit(0);
+}
+if (!args.input || !args.output) {
+    console.error("Error: input and output directories are required.\n");
+    printUsage();
+    process.exit(1);
+}
+convert({
+    inputDir: args.input,
+    outputDir: args.output,
+    rawOnly: args.rawOnly,
+    curatedOnly: args.curatedOnly,
+}).catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/curated/extract-catalogue.d.ts

@@ -0,0 +1,2 @@
+import type { CuratedFaction } from "./types.js";
+export declare function extractCatalogue(rawJson: any): CuratedFaction;

package/dist/curated/extract-catalogue.js

@@ -0,0 +1,320 @@
+import { ensureArray, cleanFactionName } from "../utils.js";
+export function extractCatalogue(rawJson) {
+    const cat = rawJson.catalogue;
+    const catalogueName = cat["@_name"];
+    // Build a lookup map of all shared entries by ID so we can resolve entryLinks
+    const entryMap = buildEntryMap(cat);
+    const units = [];
+    const enhancements = [];
+    // Units live in sharedSelectionEntries
+    const sharedEntries = ensureArray(cat?.sharedSelectionEntries?.selectionEntry);
+    for (const entry of sharedEntries) {
+        const type = entry["@_type"];
+        if (type === "unit" || type === "model") {
+            const unit = extractUnit(entry, entryMap);
+            if (unit)
+                units.push(unit);
+        }
+    }
+    // Also check top-level selectionEntries (some catalogues use these)
+    const topEntries = ensureArray(cat?.selectionEntries?.selectionEntry);
+    for (const entry of topEntries) {
+        const type = entry["@_type"];
+        if (type === "unit" || type === "model") {
+            const unit = extractUnit(entry, entryMap);
+            if (unit)
+                units.push(unit);
+        }
+    }
+    // Extract enhancements from sharedSelectionEntryGroups
+    const sharedGroups = ensureArray(cat?.sharedSelectionEntryGroups?.selectionEntryGroup);
+    for (const group of sharedGroups) {
+        if (group["@_name"] === "Enhancements") {
+            enhancements.push(...extractEnhancementsFromGroup(group));
+        }
+    }
+    return {
+        id: cat["@_id"],
+        name: cleanFactionName(catalogueName),
+        catalogueName,
+        units,
+        enhancements,
+    };
+}
+function buildEntryMap(cat) {
+    const map = new Map();
+    function indexEntry(entry) {
+        if (entry["@_id"]) {
+            map.set(entry["@_id"], entry);
+        }
+        for (const sub of ensureArray(entry?.selectionEntries?.selectionEntry)) {
+            indexEntry(sub);
+        }
+        for (const group of ensureArray(entry?.selectionEntryGroups?.selectionEntryGroup)) {
+            if (group["@_id"])
+                map.set(group["@_id"], group);
+            for (const ge of ensureArray(group?.selectionEntries?.selectionEntry)) {
+                indexEntry(ge);
+            }
+        }
+    }
+    for (const entry of ensureArray(cat?.sharedSelectionEntries?.selectionEntry)) {
+        indexEntry(entry);
+    }
+    for (const entry of ensureArray(cat?.selectionEntries?.selectionEntry)) {
+        indexEntry(entry);
+    }
+    for (const group of ensureArray(cat?.sharedSelectionEntryGroups?.selectionEntryGroup)) {
+        if (group["@_id"])
+            map.set(group["@_id"], group);
+        for (const ge of ensureArray(group?.selectionEntries?.selectionEntry)) {
+            indexEntry(ge);
+        }
+    }
+    return map;
+}
+function extractUnit(entry, entryMap) {
+    const name = entry["@_name"];
+    const id = entry["@_id"];
+    const profiles = collectAllProfiles(entry, entryMap);
+    const stats = extractUnitStats(profiles);
+    if (!stats)
+        return null;
+    const rangedWeapons = extractWeapons(entry, "Ranged Weapons", entryMap);
+    const meleeWeapons = extractWeapons(entry, "Melee Weapons", entryMap);
+    const abilities = extractAbilities(profiles);
+    const points = extractPoints(entry);
+    const { keywords, factionKeywords } = extractKeywords(entry);
+    const leader = extractLeaderTargets(profiles);
+    const transportCapacity = extractTransportCapacity(profiles);
+    const unit = {
+        id,
+        name,
+        points,
+        keywords,
+        factionKeywords,
+        stats,
+        rangedWeapons,
+        meleeWeapons,
+        abilities,
+    };
+    if (transportCapacity)
+        unit.transportCapacity = transportCapacity;
+    if (leader.length > 0)
+        unit.leader = leader;
+    return unit;
+}
+/**
+ * Recursively collects all <profile> elements from an entry and its nested children,
+ * including those reachable via entryLink references.
+ */
+function collectAllProfiles(entry, entryMap, visited = new Set()) {
+    const entryId = entry["@_id"];
+    if (entryId && visited.has(entryId))
+        return [];
+    if (entryId)
+        visited.add(entryId);
+    const profiles = [];
+    // Direct profiles on this entry
+    profiles.push(...ensureArray(entry?.profiles?.profile));
+    // Profiles inside nested selectionEntries
+    for (const sub of ensureArray(entry?.selectionEntries?.selectionEntry)) {
+        profiles.push(...collectAllProfiles(sub, entryMap, visited));
+    }
+    // Profiles inside selectionEntryGroups
+    for (const group of ensureArray(entry?.selectionEntryGroups?.selectionEntryGroup)) {
+        for (const ge of ensureArray(group?.selectionEntries?.selectionEntry)) {
+            profiles.push(...collectAllProfiles(ge, entryMap, visited));
+        }
+        // entryLinks inside groups
+        for (const link of ensureArray(group?.entryLinks?.entryLink)) {
+            const target = entryMap.get(link["@_targetId"]);
+            if (target) {
+                profiles.push(...collectAllProfiles(target, entryMap, visited));
+            }
+        }
+    }
+    // Resolve entryLink references
+    for (const link of ensureArray(entry?.entryLinks?.entryLink)) {
+        const target = entryMap.get(link["@_targetId"]);
+        if (target) {
+            profiles.push(...collectAllProfiles(target, entryMap, visited));
+        }
+    }
+    return profiles;
+}
+/**
+ * Recursively collect weapon profiles from nested selectionEntries,
+ * including those reachable via entryLink references.
+ */
+function collectWeaponProfiles(entry, typeName, entryMap, visited = new Set()) {
+    const entryId = entry["@_id"];
+    if (entryId && visited.has(entryId))
+        return [];
+    if (entryId)
+        visited.add(entryId);
+    const weapons = [];
+    // Direct profiles on this entry
+    for (const profile of ensureArray(entry?.profiles?.profile)) {
+        if (profile["@_typeName"] === typeName) {
+            const wp = parseWeaponProfile(profile, typeName);
+            if (wp)
+                weapons.push(wp);
+        }
+    }
+    // Nested selectionEntries
+    for (const sub of ensureArray(entry?.selectionEntries?.selectionEntry)) {
+        weapons.push(...collectWeaponProfiles(sub, typeName, entryMap, visited));
+    }
+    // Nested selectionEntryGroups -> selectionEntries + entryLinks
+    for (const group of ensureArray(entry?.selectionEntryGroups?.selectionEntryGroup)) {
+        for (const ge of ensureArray(group?.selectionEntries?.selectionEntry)) {
+            weapons.push(...collectWeaponProfiles(ge, typeName, entryMap, visited));
+        }
+        for (const link of ensureArray(group?.entryLinks?.entryLink)) {
+            const target = entryMap.get(link["@_targetId"]);
+            if (target) {
+                weapons.push(...collectWeaponProfiles(target, typeName, entryMap, visited));
+            }
+        }
+    }
+    // Resolve entryLink references
+    for (const link of ensureArray(entry?.entryLinks?.entryLink)) {
+        const target = entryMap.get(link["@_targetId"]);
+        if (target) {
+            weapons.push(...collectWeaponProfiles(target, typeName, entryMap, visited));
+        }
+    }
+    return weapons;
+}
+function extractWeapons(entry, typeName, entryMap) {
+    const all = collectWeaponProfiles(entry, typeName, entryMap);
+    // Deduplicate by name
+    const seen = new Set();
+    const unique = [];
+    for (const w of all) {
+        if (!seen.has(w.name)) {
+            seen.add(w.name);
+            unique.push(w);
+        }
+    }
+    return unique;
+}
+function parseWeaponProfile(profile, typeName) {
+    const chars = characteristicsToMap(profile);
+    const isRanged = typeName === "Ranged Weapons";
+    const keywordsRaw = chars["Keywords"] || "-";
+    const keywords = keywordsRaw === "-"
+        ? []
+        : keywordsRaw
+            .split(",")
+            .map((k) => k.trim())
+            .filter(Boolean);
+    return {
+        name: profile["@_name"],
+        range: chars["Range"] || "",
+        A: chars["A"] || "",
+        ...(isRanged ? { BS: chars["BS"] || "" } : { WS: chars["WS"] || "" }),
+        S: chars["S"] || "",
+        AP: chars["AP"] || "",
+        D: chars["D"] || "",
+        keywords,
+    };
+}
+function extractUnitStats(profiles) {
+    const unitProfile = profiles.find((p) => p["@_typeName"] === "Unit");
+    if (!unitProfile)
+        return null;
+    const chars = characteristicsToMap(unitProfile);
+    return {
+        M: chars["M"] || "",
+        T: chars["T"] || "",
+        SV: chars["SV"] || "",
+        W: chars["W"] || "",
+        LD: chars["LD"] || "",
+        OC: chars["OC"] || "",
+    };
+}
+function extractAbilities(profiles) {
+    return profiles
+        .filter((p) => p["@_typeName"] === "Abilities")
+        .map((p) => {
+        const chars = characteristicsToMap(p);
+        return {
+            name: p["@_name"],
+            description: chars["Description"] || "",
+        };
+    });
+}
+function extractTransportCapacity(profiles) {
+    const transport = profiles.find((p) => p["@_typeName"] === "Transport");
+    if (!transport)
+        return undefined;
+    const chars = characteristicsToMap(transport);
+    return chars["Capacity"] || undefined;
+}
+function extractPoints(entry) {
+    const costs = ensureArray(entry?.costs?.cost);
+    const ptsCost = costs.find((c) => c["@_name"] === "pts" || c["@_typeId"] === "51b2-306e-1021-d207");
+    return ptsCost ? parseInt(ptsCost["@_value"], 10) || 0 : 0;
+}
+function extractKeywords(entry) {
+    const links = ensureArray(entry?.categoryLinks?.categoryLink);
+    const keywords = [];
+    const factionKeywords = [];
+    for (const link of links) {
+        const name = link["@_name"] || "";
+        if (name.startsWith("Faction: ")) {
+            factionKeywords.push(name.replace("Faction: ", ""));
+        }
+        else if (name !== "Configuration" &&
+            name !== "Unit" &&
+            name !== entry["@_name"]) {
+            keywords.push(name);
+        }
+    }
+    return { keywords, factionKeywords };
+}
+function extractLeaderTargets(profiles) {
+    const leaderProfile = profiles.find((p) => p["@_typeName"] === "Abilities" && p["@_name"] === "Leader");
+    if (!leaderProfile)
+        return [];
+    const chars = characteristicsToMap(leaderProfile);
+    const desc = chars["Description"] || "";
+    // Parse lines like "■ IMMORTALS" or "■ NECRON WARRIORS"
+    const matches = desc.match(/■[ \t]*([A-Z][A-Z ''-]+)/g);
+    if (!matches)
+        return [];
+    return matches.map((m) => m
+        .replace(/^■[ \t]*/, "")
+        .trim()
+        .split(/\s+/)
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())
+        .join(" "));
+}
+function characteristicsToMap(profile) {
+    const chars = ensureArray(profile?.characteristics?.characteristic);
+    const map = {};
+    for (const c of chars) {
+        const name = c["@_name"];
+        const value = typeof c === "object" ? c["#text"] ?? "" : String(c);
+        map[name] = String(value);
+    }
+    return map;
+}
+function extractEnhancementsFromGroup(group) {
+    const entries = ensureArray(group?.selectionEntries?.selectionEntry);
+    return entries.map((entry) => {
+        const profiles = ensureArray(entry?.profiles?.profile);
+        const abilityProfile = profiles.find((p) => p["@_typeName"] === "Abilities");
+        const chars = abilityProfile
+            ? characteristicsToMap(abilityProfile)
+            : {};
+        return {
+            name: entry["@_name"],
+            points: extractPoints(entry),
+            description: chars["Description"] || "",
+            ...(entry.comment ? { detachment: String(entry.comment) } : {}),
+        };
+    });
+}

package/dist/curated/extract-game-system.d.ts

@@ -0,0 +1,2 @@
+import type { CuratedGameSystem } from "./types.js";
+export declare function extractGameSystem(rawJson: any): CuratedGameSystem;

package/dist/curated/extract-game-system.js

@@ -0,0 +1,45 @@
+import { ensureArray } from "../utils.js";
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export function extractGameSystem(rawJson) {
+    const gs = rawJson.gameSystem;
+    return {
+        id: gs["@_id"],
+        name: gs["@_name"],
+        revision: gs["@_revision"],
+        profileTypes: extractProfileTypes(gs),
+        categories: extractCategories(gs),
+        sharedRules: extractSharedRules(gs),
+    };
+}
+function extractProfileTypes(gs) {
+    const profileTypes = ensureArray(gs?.profileTypes?.profileType);
+    return profileTypes.map((pt) => ({
+        id: pt["@_id"],
+        name: pt["@_name"],
+        characteristics: ensureArray(pt?.characteristicTypes?.characteristicType).map((ct) => ({
+            id: ct["@_id"],
+            name: ct["@_name"],
+        })),
+    }));
+}
+function extractCategories(gs) {
+    const categories = ensureArray(gs?.categoryEntries?.categoryEntry);
+    return categories.map((cat) => ({
+        id: cat["@_id"],
+        name: cat["@_name"],
+    }));
+}
+function extractSharedRules(gs) {
+    const rules = ensureArray(gs?.sharedRules?.rule);
+    return rules.map((rule) => {
+        const result = {
+            id: rule["@_id"],
+            name: rule["@_name"],
+            description: rule.description || "",
+        };
+        if (rule.alias) {
+            result.alias = rule.alias;
+        }
+        return result;
+    });
+}

package/dist/curated/types.d.ts

@@ -0,0 +1,89 @@
+export interface WeaponProfile {
+    name: string;
+    range: string;
+    A: string;
+    BS?: string;
+    WS?: string;
+    S: string;
+    AP: string;
+    D: string;
+    keywords: string[];
+}
+export interface UnitStats {
+    M: string;
+    T: string;
+    SV: string;
+    W: string;
+    LD: string;
+    OC: string;
+}
+export interface Ability {
+    name: string;
+    description: string;
+}
+export interface TransportCapacity {
+    capacity: string;
+}
+export interface CuratedUnit {
+    id: string;
+    name: string;
+    points: number;
+    keywords: string[];
+    factionKeywords: string[];
+    stats: UnitStats;
+    rangedWeapons: WeaponProfile[];
+    meleeWeapons: WeaponProfile[];
+    abilities: Ability[];
+    transportCapacity?: string;
+    leader?: string[];
+}
+export interface Enhancement {
+    name: string;
+    points: number;
+    description: string;
+    detachment?: string;
+}
+export interface SharedRule {
+    id: string;
+    name: string;
+    description: string;
+    alias?: string;
+}
+export interface ProfileTypeDefinition {
+    id: string;
+    name: string;
+    characteristics: {
+        id: string;
+        name: string;
+    }[];
+}
+export interface CategoryDefinition {
+    id: string;
+    name: string;
+}
+export interface CuratedGameSystem {
+    id: string;
+    name: string;
+    revision: string;
+    profileTypes: ProfileTypeDefinition[];
+    categories: CategoryDefinition[];
+    sharedRules: SharedRule[];
+}
+export interface CuratedFaction {
+    id: string;
+    name: string;
+    catalogueName: string;
+    units: CuratedUnit[];
+    enhancements: Enhancement[];
+}
+export interface FactionManifestEntry {
+    id: string;
+    name: string;
+    catalogueName: string;
+    filename: string;
+    unitCount: number;
+}
+export interface FactionManifest {
+    gameSystem: string;
+    factions: FactionManifestEntry[];
+}

package/dist/curated/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export { convertFileToRawJson } from "./raw-converter.js";
+export { extractGameSystem } from "./curated/extract-game-system.js";
+export { extractCatalogue } from "./curated/extract-catalogue.js";
+export * from "./curated/types.js";
+export { slugify, discoverFiles, ensureArray, cleanFactionName } from "./utils.js";
+export interface ConvertOptions {
+    inputDir: string;
+    outputDir: string;
+    rawOnly?: boolean;
+    curatedOnly?: boolean;
+}
+export interface ConvertResult {
+    rawFiles: string[];
+    curatedFiles: string[];
+    factionCount: number;
+}
+export declare function convert(options: ConvertOptions): Promise<ConvertResult>;

package/dist/index.js

@@ -0,0 +1,95 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { discoverFiles, slugify } from "./utils.js";
+import { convertFileToRawJson } from "./raw-converter.js";
+import { extractGameSystem } from "./curated/extract-game-system.js";
+import { extractCatalogue } from "./curated/extract-catalogue.js";
+// --- Re-exports for programmatic consumers ---
+export { convertFileToRawJson } from "./raw-converter.js";
+export { extractGameSystem } from "./curated/extract-game-system.js";
+export { extractCatalogue } from "./curated/extract-catalogue.js";
+export * from "./curated/types.js";
+export { slugify, discoverFiles, ensureArray, cleanFactionName } from "./utils.js";
+async function writeJson(filePath, data) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, JSON.stringify(data, null, 2), "utf-8");
+}
+export async function convert(options) {
+    const { inputDir, outputDir, rawOnly = false, curatedOnly = false } = options;
+    const rawDir = path.join(outputDir, "raw");
+    const curatedDir = path.join(outputDir, "curated");
+    const factionsDir = path.join(curatedDir, "factions");
+    const doRaw = !curatedOnly;
+    const doCurated = !rawOnly;
+    const rawFiles = [];
+    const curatedFiles = [];
+    console.log(`Input:  ${inputDir}`);
+    console.log(`Output: ${outputDir}`);
+    console.log();
+    const { gstFiles, catFiles } = await discoverFiles(inputDir);
+    console.log(`Found ${gstFiles.length} game system file(s)`);
+    console.log(`Found ${catFiles.length} catalogue file(s)`);
+    console.log();
+    if (gstFiles.length === 0) {
+        throw new Error("No .gst file found in input directory.");
+    }
+    const gstPath = gstFiles[0];
+    const gstRaw = await convertFileToRawJson(gstPath);
+    if (doRaw) {
+        const rawPath = path.join(rawDir, "game-system.json");
+        await writeJson(rawPath, gstRaw);
+        rawFiles.push(rawPath);
+        console.log(`[raw] game-system.json`);
+    }
+    if (doCurated) {
+        const gameSystem = extractGameSystem(gstRaw);
+        const curatedPath = path.join(curatedDir, "game-system.json");
+        await writeJson(curatedPath, gameSystem);
+        curatedFiles.push(curatedPath);
+        console.log(`[curated] game-system.json (${gameSystem.sharedRules.length} shared rules, ${gameSystem.categories.length} categories)`);
+    }
+    const manifest = [];
+    for (const catPath of catFiles) {
+        const baseName = path.basename(catPath, ".cat");
+        const slug = slugify(baseName);
+        const catRaw = await convertFileToRawJson(catPath);
+        if (doRaw) {
+            const rawPath = path.join(rawDir, `${slug}.json`);
+            await writeJson(rawPath, catRaw);
+            rawFiles.push(rawPath);
+            console.log(`[raw] ${slug}.json`);
+        }
+        if (doCurated) {
+            const faction = extractCatalogue(catRaw);
+            const factionPath = path.join(factionsDir, `${slug}.json`);
+            await writeJson(factionPath, faction);
+            curatedFiles.push(factionPath);
+            console.log(`[curated] ${slug}.json — ${faction.name} (${faction.units.length} units, ${faction.enhancements.length} enhancements)`);
+            manifest.push({
+                id: faction.id,
+                name: faction.name,
+                catalogueName: faction.catalogueName,
+                filename: `${slug}.json`,
+                unitCount: faction.units.length,
+            });
+        }
+    }
+    if (doCurated) {
+        const index = {
+            gameSystem: "Warhammer 40,000 10th Edition",
+            factions: manifest.sort((a, b) => a.name.localeCompare(b.name)),
+        };
+        const indexPath = path.join(curatedDir, "index.json");
+        await writeJson(indexPath, index);
+        curatedFiles.push(indexPath);
+        console.log();
+        console.log(`[curated] index.json (${manifest.length} factions)`);
+    }
+    console.log();
+    console.log("Done.");
+    return {
+        rawFiles,
+        curatedFiles,
+        factionCount: manifest.length,
+    };
+}

package/dist/raw-converter.d.ts

@@ -0,0 +1 @@
+export declare function convertFileToRawJson(filePath: string): Promise<Record<string, unknown>>;

package/dist/raw-converter.js

@@ -0,0 +1,43 @@
+import { readFile } from "node:fs/promises";
+import { XMLParser } from "fast-xml-parser";
+const ARRAY_TAGS = new Set([
+    "publication",
+    "costType",
+    "profileType",
+    "characteristicType",
+    "categoryEntry",
+    "forceEntry",
+    "selectionEntry",
+    "selectionEntryGroup",
+    "entryLink",
+    "categoryLink",
+    "infoLink",
+    "infoGroup",
+    "profile",
+    "characteristic",
+    "rule",
+    "constraint",
+    "modifier",
+    "modifierGroup",
+    "condition",
+    "conditionGroup",
+    "repeat",
+    "cost",
+    "association",
+    "comment",
+]);
+function createRawParser() {
+    return new XMLParser({
+        ignoreAttributes: false,
+        attributeNamePrefix: "@_",
+        allowBooleanAttributes: true,
+        parseAttributeValue: false,
+        trimValues: true,
+        isArray: (name) => ARRAY_TAGS.has(name),
+    });
+}
+export async function convertFileToRawJson(filePath) {
+    const xml = await readFile(filePath, "utf-8");
+    const parser = createRawParser();
+    return parser.parse(xml);
+}

package/dist/utils.d.ts

@@ -0,0 +1,13 @@
+import { XMLParser } from "fast-xml-parser";
+export declare function createXmlParser(): XMLParser;
+export declare function slugify(name: string): string;
+export declare function cleanFactionName(catalogueName: string): string;
+export declare function discoverFiles(inputDir: string): Promise<{
+    gstFiles: string[];
+    catFiles: string[];
+}>;
+/**
+ * Normalizes a value that may be a single item or array into an array.
+ * BSData XML elements sometimes appear once (parsed as object) or multiple times (parsed as array).
+ */
+export declare function ensureArray<T>(value: T | T[] | undefined | null): T[];

package/dist/utils.js

@@ -0,0 +1,61 @@
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+import { XMLParser } from "fast-xml-parser";
+export function createXmlParser() {
+    return new XMLParser({
+        ignoreAttributes: false,
+        attributeNamePrefix: "@_",
+        allowBooleanAttributes: true,
+        parseAttributeValue: false,
+        trimValues: true,
+        isArray: (_name, _jpath, isLeafNode) => {
+            // Force arrays for elements that can repeat
+            if (!isLeafNode)
+                return false;
+            return false;
+        },
+    });
+}
+export function slugify(name) {
+    return name
+        .toLowerCase()
+        .replace(/['']/g, "")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+export function cleanFactionName(catalogueName) {
+    // "Xenos - Necrons" -> "Necrons"
+    // "Imperium - Space Marines" -> "Space Marines"
+    // "Chaos - Chaos Space Marines" -> "Chaos Space Marines"
+    const parts = catalogueName.split(" - ");
+    if (parts.length > 1) {
+        return parts.slice(1).join(" - ").trim();
+    }
+    return catalogueName.trim();
+}
+export async function discoverFiles(inputDir) {
+    const entries = await readdir(inputDir);
+    const gstFiles = [];
+    const catFiles = [];
+    for (const entry of entries) {
+        const ext = path.extname(entry).toLowerCase();
+        if (ext === ".gst") {
+            gstFiles.push(path.join(inputDir, entry));
+        }
+        else if (ext === ".cat") {
+            catFiles.push(path.join(inputDir, entry));
+        }
+    }
+    return { gstFiles, catFiles };
+}
+/**
+ * Normalizes a value that may be a single item or array into an array.
+ * BSData XML elements sometimes appear once (parsed as object) or multiple times (parsed as array).
+ */
+export function ensureArray(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (Array.isArray(value))
+        return value;
+    return [value];
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "bsdata40k-to-json",
+  "version": "1.0.0",
+  "description": "Convert BSData BattleScribe XML files (.cat/.gst) to JSON — raw or curated",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "bsdata40k-to-json": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "convert": "tsx src/cli.ts",
+    "convert:raw": "tsx src/cli.ts --raw-only",
+    "convert:curated": "tsx src/cli.ts --curated-only",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "bsdata",
+    "battlescribe",
+    "warhammer",
+    "40k",
+    "xml",
+    "json",
+    "converter"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "fast-xml-parser": "^4.5.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.4",
+    "tsx": "^4.19.3",
+    "typescript": "^5.7.3"
+  }
+}