@alpaca-software/40kdc-data 0.1.0 → 0.1.1

package/dist/bundle-schemas.js

@@ -23,6 +23,15 @@ import { findSchemaFiles, SCHEMAS_ROOT } from "./schema-loader.js";
  * targets the `$id` `.../schemas/defs/...`, while the file lives in `$defs/`).
  */
 const COMMON_ID = "https://40kdc.dev/schemas/defs/common.schema.json";
+/**
+ * Schemas excluded from the codegen bundle (still loaded for AJV validation).
+ * The roster schema describes importer *output* — a tool-side artifact, not a
+ * dataset entity the Rust crate serves — so it is intentionally kept out of the
+ * generated types. Its TS types are hand-authored in `src/import/types.ts`.
+ */
+const CODEGEN_EXCLUDED_IDS = new Set([
+    "https://40kdc.dev/schemas/core/roster.schema.json",
+]);
 const OUTPUT_PATH = resolve(SCHEMAS_ROOT, "../crates/wh40kdc/schemas/bundled.schema.json");
 const BUNDLE_ID = "https://40kdc.dev/schemas/bundled.schema.json";
 function stemOfId(id) {
@@ -106,6 +115,8 @@ export function bundle() {
         const id = raw.$id;
         if (!id)
             throw new Error(`schema missing $id: ${file}`);
+        if (CODEGEN_EXCLUDED_IDS.has(id))
+            continue;
         const { $id: _id, $schema: _schema, $defs: localDefs, ...body } = raw;
         // Hoist this file's local $defs flat to the top level (names are globally
         // unique across the schema set; collisions throw above).

package/dist/cli.js

@@ -3,6 +3,7 @@ import { validateCoreCommand } from "./commands/validate-core.js";
 import { validateEnrichmentCommand } from "./commands/validate-enrichment.js";
 import { validateAllCommand } from "./commands/validate-all.js";
 import { translateCommand } from "./commands/translate.js";
+import { importCommand } from "./commands/import.js";
 const program = new Command();
 program
     .name("40kdc-validate")
@@ -28,4 +29,11 @@ program
     .description("Translate ability DSL to plain English")
     .argument("[path]", "Path to abilities.json file")
     .action(translateCommand);
+program
+    .command("import")
+    .description("Import a ListForge army-list export into a 40kdc roster")
+    .argument("[input]", "ListForge URL, base64 segment, JSON, or file path (omit/'-' for stdin)")
+    .option("--reporter <mode>", "Output format: json or pretty", "json")
+    .option("--out <file>", "Write roster JSON to a file instead of stdout")
+    .action(importCommand);
 program.parse();

package/dist/commands/import.d.ts

@@ -0,0 +1,6 @@
+interface ImportOpts {
+    reporter: string;
+    out?: string;
+}
+export declare function importCommand(input: string | undefined, opts: ImportOpts): Promise<void>;
+export {};

package/dist/commands/import.js

@@ -0,0 +1,102 @@
+/**
+ * `import` command: turn a ListForge army-list export into a 40kdc roster.
+ *
+ * Input may be a ListForge URL, a bare base64 segment, an already-decoded JSON
+ * string, or a path to a file containing any of those (or `-`/omitted for stdin).
+ * The resolved roster is validated against `roster.schema.json` before output —
+ * a guard that the importer only ever emits schema-valid rosters.
+ *
+ * The import is lenient: unresolved entries do not fail the command (exit 0).
+ * Only a decode failure or schema-invalid output is fatal (exit 1).
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { importListForge } from "../import/index.js";
+import { createValidator } from "../schema-loader.js";
+const ROSTER_SCHEMA_ID = "https://40kdc.dev/schemas/core/roster.schema.json";
+function readStdin() {
+    try {
+        return readFileSync(0, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+/** Resolve the command's input source to a raw payload string. */
+function resolveInput(input) {
+    if (!input || input === "-")
+        return readStdin().trim();
+    if (existsSync(input))
+        return readFileSync(input, "utf8").trim();
+    return input;
+}
+function formatPretty(roster) {
+    const d = roster.diagnostics;
+    const lines = [];
+    lines.push(`Roster: ${roster.name}`);
+    lines.push(`  Faction:    ${roster.faction_id ?? "(unresolved)"}`);
+    lines.push(`  Detachment: ${roster.detachment_id ?? "(none/unresolved)"}`);
+    lines.push(`  Battle size: ${roster.battle_size ?? "(unmapped)"}`);
+    lines.push(`  Points: computed ${roster.points.total_computed}` +
+        (roster.points.total_reported !== null ? `, reported ${roster.points.total_reported}` : "") +
+        (roster.points.declared_limit !== null ? `, limit ${roster.points.declared_limit}` : ""));
+    lines.push(`  Units (${roster.units.length}):`);
+    for (const u of roster.units) {
+        const mark = u.ref.resolved ? "✓" : "✗";
+        const id = u.ref.resolved ? u.ref.id : `${u.ref.raw_name} → unresolved`;
+        const extras = [];
+        if (u.is_warlord)
+            extras.push("warlord");
+        if (u.enhancement)
+            extras.push(`enh:${u.enhancement.resolved ? u.enhancement.id : "?"}`);
+        if (u.leader_attachment)
+            extras.push(`leads:${u.leader_attachment.bodyguard_ref.id}?`);
+        const suffix = extras.length ? ` [${extras.join(", ")}]` : "";
+        lines.push(`    ${mark} ${id} ×${u.model_count}${u.points !== null ? ` (${u.points}pts)` : ""}${suffix}`);
+    }
+    lines.push(`  Resolved: ${d.resolved_units} units / ${d.resolved_weapons} weapons; ` +
+        `unresolved: ${d.unresolved_units} units / ${d.unresolved_weapons} weapons`);
+    if (d.warnings.length) {
+        lines.push(`  Warnings (${d.warnings.length}):`);
+        for (const w of d.warnings) {
+            lines.push(`    - [${w.code}]${w.raw_name ? ` "${w.raw_name}":` : ""} ${w.message}`);
+        }
+    }
+    return lines.join("\n");
+}
+export async function importCommand(input, opts) {
+    const payload = resolveInput(input);
+    if (!payload) {
+        console.error("import: no input (provide a URL/base64/JSON argument, a file path, or pipe via stdin)");
+        process.exit(1);
+    }
+    let roster;
+    try {
+        roster = importListForge(payload);
+    }
+    catch (err) {
+        console.error(`import: failed to decode/parse payload: ${err.message}`);
+        process.exit(1);
+    }
+    // Guard: our own output must be schema-valid.
+    const validate = createValidator().getSchema(ROSTER_SCHEMA_ID);
+    if (!validate) {
+        console.error(`import: roster schema not found (${ROSTER_SCHEMA_ID})`);
+        process.exit(1);
+    }
+    if (!validate(roster)) {
+        console.error("import: produced roster failed schema validation:");
+        console.error(JSON.stringify(validate.errors, null, 2));
+        process.exit(1);
+    }
+    const json = JSON.stringify(roster, null, 2);
+    if (opts.out) {
+        writeFileSync(opts.out, json + "\n", "utf8");
+        console.error(`Wrote roster → ${opts.out}`);
+    }
+    if (opts.reporter === "pretty") {
+        console.log(formatPretty(roster));
+    }
+    else if (!opts.out) {
+        console.log(json);
+    }
+}

package/dist/gen-conformance.d.ts

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

package/dist/gen-conformance.js

@@ -0,0 +1,70 @@
+/**
+ * Generate the cross-implementation conformance corpus under repo-root
+ * `conformance/`. The TypeScript package is the reference implementation, so the
+ * goldens it emits are what the Rust crate must reproduce byte-for-byte
+ * (structurally). Run via `npm run gen:conformance`; CI regenerates and asserts
+ * `git diff --exit-code conformance/` is clean.
+ *
+ * Outputs:
+ * - `conformance/normalize.json` — `[{ input, expected }]` for normalizeName.
+ * - `conformance/roster/<case>/expected.roster.json` — the resolved Roster for
+ *   the sibling `input.json` (the ListForge payload).
+ */
+import { readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Dataset } from "./data/dataset.js";
+import { normalizeName } from "./data/normalize.js";
+import { importRoster } from "./import/import-listforge.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = join(__dirname, "../..");
+const CONFORMANCE = join(REPO_ROOT, "conformance");
+/** Inputs for the normalize table — every rule, plus real accented/quoted names. */
+const NORMALIZE_INPUTS = [
+    // NFD diacritic strip
+    "Khârn the Betrayer",
+    "Brôkhyr",
+    "Ûthar",
+    "Magnús",
+    // apostrophe / quote variants
+    "T'au",
+    "Be’lakor",
+    "Kor’sarro Khan",
+    "Aetaos'rau'keres",
+    "‘quoted’",
+    // whitespace / hyphen collapse + trim
+    "Brôkhyr Iron-master",
+    "  the   betrayer  ",
+    "space--marines",
+    // casefold
+    "KHÂRN THE BETRAYER",
+    // already-normalized (idempotence)
+    "kharn the betrayer",
+    // distinctness anchors (must NOT collapse together)
+    "Khorne",
+    "Khârn",
+];
+/** Pretty JSON with a trailing newline (matches the repo's 2-space convention). */
+function writeJson(path, value) {
+    writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+function genNormalize() {
+    const table = NORMALIZE_INPUTS.map((input) => ({ input, expected: normalizeName(input) }));
+    writeJson(join(CONFORMANCE, "normalize.json"), table);
+    console.log(`normalize.json: ${table.length} cases`);
+}
+function genRosters() {
+    const ds = Dataset.embedded();
+    const rosterDir = join(CONFORMANCE, "roster");
+    for (const entry of readdirSync(rosterDir, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const caseDir = join(rosterDir, entry.name);
+        const input = JSON.parse(readFileSync(join(caseDir, "input.json"), "utf8"));
+        const roster = importRoster(input, { dataset: ds });
+        writeJson(join(caseDir, "expected.roster.json"), roster);
+        console.log(`roster/${entry.name}: ${roster.units.length} units, ${roster.diagnostics.warnings.length} warnings`);
+    }
+}
+genNormalize();
+genRosters();

package/dist/import/adapter.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The format-adapter seam.
+ *
+ * Each supported source format implements {@link FormatAdapter}: it recognises a
+ * decoded payload ({@link FormatAdapter.matches}) and lowers it to the
+ * format-agnostic {@link ParsedRoster} ({@link FormatAdapter.parse}). Resolution
+ * onto 40kdc entity ids happens once, downstream, against any `ParsedRoster` —
+ * so adding a new source format (New Recruit, WTC, …) means writing one adapter,
+ * not touching the resolver.
+ *
+ * v1 registers only {@link listForgeAdapter}.
+ *
+ * @packageDocumentation
+ */
+import type { ParsedRoster } from "./types.js";
+/** Recognises and parses one source list-export format. */
+export interface FormatAdapter {
+    /** Stable identifier for the format (e.g. "listforge"). */
+    id: string;
+    /** True when this adapter can parse the given decoded payload. */
+    matches(decoded: unknown): boolean;
+    /** Lower a recognised payload to the format-agnostic intermediate. */
+    parse(decoded: unknown): ParsedRoster;
+}
+/** Pick the first adapter that recognises the payload. */
+export declare function selectAdapter(decoded: unknown, adapters: FormatAdapter[]): FormatAdapter;

package/dist/import/adapter.js

@@ -0,0 +1,9 @@
+/** Pick the first adapter that recognises the payload. */
+export function selectAdapter(decoded, adapters) {
+    const adapter = adapters.find((a) => a.matches(decoded));
+    if (!adapter) {
+        throw new Error("no registered import adapter recognises this payload " +
+            `(tried: ${adapters.map((a) => a.id).join(", ") || "none"})`);
+    }
+    return adapter;
+}

package/dist/import/decode.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Decode a ListForge payload (URL, bare base64, or raw JSON) into a JSON value.
+ *
+ * @throws if the input is neither valid JSON nor a decodable gzip payload.
+ */
+export declare function decodeListForge(input: string): unknown;

package/dist/import/decode.js

@@ -0,0 +1,72 @@
+/**
+ * Decode a ListForge share payload into a JSON object.
+ *
+ * ListForge packs a roster as `base64( gzip( utf8(json) ) )` and embeds it in a
+ * URL hash fragment: `https://app/#/listforge/<BASE64>`. The fragment is used
+ * deliberately so browsers never send it to a server, preserving the payload
+ * verbatim. A valid gzipped payload always base64-encodes to a string starting
+ * with `H4sIAAAAAAAAA`.
+ *
+ * {@link decodeListForge} accepts any of three forms and returns the parsed JSON:
+ * - a full URL (the segment after the last `/` is taken),
+ * - a bare base64 segment,
+ * - an already-decoded JSON string (passed straight to `JSON.parse`).
+ *
+ * Only `node:zlib` is used — no third-party dependency.
+ *
+ * @packageDocumentation
+ */
+import { gunzipSync } from "node:zlib";
+/** The base64 prefix every ListForge gzip payload begins with. */
+const GZIP_BASE64_PREFIX = "H4sIA";
+/** The path marker ListForge uses ahead of the payload. */
+const LISTFORGE_MARKER = "/listforge/";
+/**
+ * Extract the payload segment from an input that may be a URL.
+ *
+ * The base64 alphabet includes `/`, so a bare base64 segment cannot be split on
+ * `/`. We only treat the input as a URL when it carries the `/listforge/` marker
+ * or an `http(s)://` scheme; otherwise it is returned unchanged.
+ */
+function extractSegment(input) {
+    const markerIndex = input.indexOf(LISTFORGE_MARKER);
+    if (markerIndex !== -1) {
+        return input.slice(markerIndex + LISTFORGE_MARKER.length);
+    }
+    if (/^https?:\/\//i.test(input)) {
+        const lastSlash = input.lastIndexOf("/");
+        return lastSlash === -1 ? input : input.slice(lastSlash + 1);
+    }
+    return input;
+}
+/**
+ * Decode a ListForge payload (URL, bare base64, or raw JSON) into a JSON value.
+ *
+ * @throws if the input is neither valid JSON nor a decodable gzip payload.
+ */
+export function decodeListForge(input) {
+    const trimmed = input.trim();
+    if (trimmed === "") {
+        throw new Error("decodeListForge: empty input");
+    }
+    // Raw JSON object passed directly.
+    if (trimmed.startsWith("{")) {
+        return JSON.parse(trimmed);
+    }
+    const segment = extractSegment(trimmed);
+    if (!segment.startsWith(GZIP_BASE64_PREFIX)) {
+        throw new Error("decodeListForge: input is not a ListForge payload (expected raw JSON, " +
+            `or a gzip+base64 segment beginning with "${GZIP_BASE64_PREFIX}…")`);
+    }
+    let json;
+    try {
+        const bytes = Buffer.from(segment, "base64");
+        json = gunzipSync(bytes).toString("utf8");
+    }
+    catch (cause) {
+        throw new Error("decodeListForge: failed to gunzip base64 payload", {
+            cause,
+        });
+    }
+    return JSON.parse(json);
+}

package/dist/import/import-listforge.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Orchestrates a ListForge import: decode → parse → resolve.
+ *
+ * @packageDocumentation
+ */
+import { Dataset } from "../data/dataset.js";
+import type { Roster } from "./types.js";
+export interface ImportOptions {
+    /** Dataset to resolve against. Defaults to the package's embedded dataset. */
+    dataset?: Dataset;
+}
+/**
+ * Import a ListForge army-list export into a resolved 40kdc {@link Roster}.
+ *
+ * `input` may be a full ListForge URL, a bare base64 segment, or an
+ * already-decoded JSON string — all are handled transparently.
+ */
+export declare function importListForge(input: string, opts?: ImportOptions): Roster;
+/**
+ * Import an already-decoded payload. Selects the matching format adapter and
+ * resolves the result against the dataset.
+ */
+export declare function importRoster(decoded: unknown, opts?: ImportOptions): Roster;

package/dist/import/import-listforge.js

@@ -0,0 +1,32 @@
+/**
+ * Orchestrates a ListForge import: decode → parse → resolve.
+ *
+ * @packageDocumentation
+ */
+import { Dataset } from "../data/dataset.js";
+import { selectAdapter } from "./adapter.js";
+import { decodeListForge } from "./decode.js";
+import { listForgeAdapter } from "./listforge.js";
+import { resolve } from "./resolve.js";
+/** Adapters available to {@link importRoster}, in match-priority order. */
+const ADAPTERS = [listForgeAdapter];
+/**
+ * Import a ListForge army-list export into a resolved 40kdc {@link Roster}.
+ *
+ * `input` may be a full ListForge URL, a bare base64 segment, or an
+ * already-decoded JSON string — all are handled transparently.
+ */
+export function importListForge(input, opts = {}) {
+    const decoded = decodeListForge(input);
+    return importRoster(decoded, opts);
+}
+/**
+ * Import an already-decoded payload. Selects the matching format adapter and
+ * resolves the result against the dataset.
+ */
+export function importRoster(decoded, opts = {}) {
+    const ds = opts.dataset ?? Dataset.embedded();
+    const adapter = selectAdapter(decoded, ADAPTERS);
+    const parsed = adapter.parse(decoded);
+    return resolve(parsed, ds);
+}

package/dist/import/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Army-list importer: turn an external list-builder export into a resolved
+ * 40kdc roster.
+ *
+ * v1 supports ListForge's "share JSON" payload. The output is a {@link Roster}
+ * keyed on 40kdc entity ids and validatable against
+ * `schemas/core/roster.schema.json`. Resolution is lenient — unmatched names are
+ * retained with candidate suggestions and summarised in diagnostics.
+ *
+ * @packageDocumentation
+ */
+export { importListForge, importRoster } from "./import-listforge.js";
+export type { ImportOptions } from "./import-listforge.js";
+export { decodeListForge } from "./decode.js";
+export { resolve } from "./resolve.js";
+export { listForgeAdapter } from "./listforge.js";
+export type { FormatAdapter } from "./adapter.js";
+export type { Roster, RosterUnit, RosterWargear, RosterSource, RosterPoints, ResolvedRef, Candidate, RosterLeaderAttachment, Diagnostics, Warning, WarningCode, BattleSize, GameVersionRef, ParsedRoster, ParsedUnit, ParsedWargear, } from "./types.js";

package/dist/import/index.js

@@ -0,0 +1,15 @@
+/**
+ * Army-list importer: turn an external list-builder export into a resolved
+ * 40kdc roster.
+ *
+ * v1 supports ListForge's "share JSON" payload. The output is a {@link Roster}
+ * keyed on 40kdc entity ids and validatable against
+ * `schemas/core/roster.schema.json`. Resolution is lenient — unmatched names are
+ * retained with candidate suggestions and summarised in diagnostics.
+ *
+ * @packageDocumentation
+ */
+export { importListForge, importRoster } from "./import-listforge.js";
+export { decodeListForge } from "./decode.js";
+export { resolve } from "./resolve.js";
+export { listForgeAdapter } from "./listforge.js";

package/dist/import/listforge.d.ts

@@ -0,0 +1,23 @@
+/**
+ * ListForge adapter: lower a decoded ListForge "share JSON" payload (a
+ * BattleScribe-derived roster tree) to a {@link ParsedRoster}.
+ *
+ * The walk reads an ALLOWLIST of fields only — `name`, `number`, `type`,
+ * `categories[].name`, `group`, and `costs` point values — and never touches
+ * `rules[].description` or ability `profiles[].characteristics[].$text`, which
+ * carry reproduced rules text. This keeps the importer's output free of
+ * copyrighted prose by construction.
+ *
+ * Selection-tree shape (recursive `selections`):
+ * - Configuration nodes (`type: "upgrade"`) named "Detachment" / "Battle Size"
+ *   carry the chosen value as their first child selection.
+ * - Unit nodes (`type: "model" | "unit"`) carry role categories, a points cost,
+ *   and — nested anywhere beneath them — their wargear (weapon-category
+ *   selections), enhancement (a selection whose `group` starts "Enhancements"),
+ *   the "Warlord" marker, and model sub-selections.
+ * - Every unit carries a `"Faction: <Name>"` category.
+ *
+ * @packageDocumentation
+ */
+import type { FormatAdapter } from "./adapter.js";
+export declare const listForgeAdapter: FormatAdapter;

package/dist/import/listforge.js

@@ -0,0 +1,195 @@
+const PTS_COST_NAME = "pts";
+const FACTION_CATEGORY = /^Faction:\s*(.+)$/;
+const POINTS_LIMIT = /(\d[\d,]*)\s*Point/i;
+const ENHANCEMENT_GROUP_PREFIX = "Enhancements";
+const CHARACTER_CATEGORIES = new Set(["Character", "Epic Hero"]);
+const WEAPON_CATEGORY_SUFFIX = " Weapon"; // "Ranged Weapon", "Melee Weapon", "Psychic Weapon"
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function asString(value) {
+    return typeof value === "string" ? value : null;
+}
+function selectionName(sel) {
+    return asString(sel.name) ?? "";
+}
+function selectionType(sel) {
+    return asString(sel.type) ?? "";
+}
+/** A selection's multiplicity (`number`), defaulting to 1. */
+function selectionCount(sel) {
+    return typeof sel.number === "number" && sel.number > 0 ? sel.number : 1;
+}
+/** Point value from a selection's cost block, or null when absent. */
+function pointsOf(sel) {
+    for (const raw of asArray(sel.costs)) {
+        const cost = raw;
+        if (asString(cost.name) === PTS_COST_NAME && typeof cost.value === "number") {
+            return cost.value;
+        }
+    }
+    return null;
+}
+function categoryNames(sel) {
+    return asArray(sel.categories)
+        .map((c) => asString(c.name))
+        .filter((n) => n !== null);
+}
+function childSelections(sel) {
+    return asArray(sel.selections);
+}
+/** Depth-first visit of a selection and everything beneath it. */
+function walk(sel, visit) {
+    visit(sel);
+    for (const child of childSelections(sel))
+        walk(child, visit);
+}
+function isUnitSelection(sel) {
+    const type = selectionType(sel);
+    return type === "model" || type === "unit";
+}
+function isCharacter(sel) {
+    return categoryNames(sel).some((n) => CHARACTER_CATEGORIES.has(n));
+}
+function isWeaponSelection(sel) {
+    return categoryNames(sel).some((n) => n.endsWith(WEAPON_CATEGORY_SUFFIX));
+}
+function isEnhancementSelection(sel) {
+    const group = asString(sel.group);
+    return group !== null && group.startsWith(ENHANCEMENT_GROUP_PREFIX);
+}
+/** Sum the model count of a unit from its nested model selections. */
+function modelCount(unit) {
+    let total = 0;
+    walk(unit, (s) => {
+        if (selectionType(s) === "model")
+            total += selectionCount(s);
+    });
+    return total > 0 ? total : selectionCount(unit);
+}
+/** Build a parsed unit from a top-level unit selection. */
+function parseUnit(unit) {
+    const wargear = [];
+    let enhancement_raw_name = null;
+    let is_warlord = false;
+    for (const node of childSelections(unit)) {
+        walk(node, (s) => {
+            if (isEnhancementSelection(s)) {
+                enhancement_raw_name ??= selectionName(s);
+                return;
+            }
+            if (selectionName(s) === "Warlord") {
+                is_warlord = true;
+                return;
+            }
+            if (isWeaponSelection(s)) {
+                wargear.push({ raw_name: selectionName(s), count: selectionCount(s) });
+            }
+        });
+    }
+    return {
+        raw_name: selectionName(unit),
+        is_character: isCharacter(unit),
+        model_count: modelCount(unit),
+        points: pointsOf(unit),
+        is_warlord,
+        enhancement_raw_name,
+        wargear,
+    };
+}
+/** Value carried as the first child of a named configuration selection. */
+function configValue(selections, configName) {
+    const node = selections.find((s) => selectionName(s) === configName);
+    if (!node)
+        return null;
+    const child = childSelections(node)[0];
+    return child ? selectionName(child) : null;
+}
+function parseLimit(label) {
+    if (!label)
+        return null;
+    const match = POINTS_LIMIT.exec(label);
+    if (!match)
+        return null;
+    return Number.parseInt(match[1].replace(/,/g, ""), 10);
+}
+/** First `"Faction: X"` category found anywhere; reports all distinct names. */
+function collectFactions(forces) {
+    const seen = new Set();
+    for (const force of forces) {
+        for (const sel of childSelections(force)) {
+            walk(sel, (s) => {
+                for (const name of categoryNames(s)) {
+                    const match = FACTION_CATEGORY.exec(name);
+                    if (match)
+                        seen.add(match[1].trim());
+                }
+            });
+        }
+    }
+    return [...seen];
+}
+function rosterOf(decoded) {
+    if (!decoded || typeof decoded !== "object")
+        return null;
+    const roster = decoded.roster;
+    if (!roster || typeof roster !== "object")
+        return null;
+    if (!Array.isArray(roster.forces))
+        return null;
+    return roster;
+}
+export const listForgeAdapter = {
+    id: "listforge",
+    matches(decoded) {
+        return rosterOf(decoded) !== null;
+    },
+    parse(decoded) {
+        const payload = decoded;
+        const roster = rosterOf(decoded);
+        if (!roster) {
+            throw new Error("listforge: payload has no roster.forces array");
+        }
+        const forces = asArray(roster.forces);
+        // Configuration lives among each force's top-level selections.
+        let detachment_raw_name = null;
+        let battle_size_raw = null;
+        const units = [];
+        for (const force of forces) {
+            const top = childSelections(force);
+            detachment_raw_name ??= configValue(top, "Detachment");
+            battle_size_raw ??= configValue(top, "Battle Size");
+            for (const sel of top) {
+                if (isUnitSelection(sel))
+                    units.push(parseUnit(sel));
+            }
+        }
+        const factions = collectFactions(forces);
+        const total_reported = pointsOf(roster);
+        // Honest computed total: sum every cost line in the tree. A unit's own cost
+        // and its nested enhancement's cost are distinct lines that together make up
+        // the unit's army contribution, so a full walk reproduces the army total.
+        let total_computed = 0;
+        for (const force of forces) {
+            for (const sel of childSelections(force)) {
+                walk(sel, (s) => {
+                    const pts = pointsOf(s);
+                    if (pts)
+                        total_computed += pts;
+                });
+            }
+        }
+        return {
+            name: asString(payload.name) ?? asString(roster.name) ?? "Imported roster",
+            generated_by: asString(payload.generatedBy),
+            faction_raw_name: factions[0] ?? null,
+            detachment_raw_name,
+            battle_size_raw,
+            declared_limit: parseLimit(battle_size_raw),
+            total_reported,
+            total_computed,
+            units,
+            multi_force: factions.length > 1,
+        };
+    },
+};

package/dist/import/resolve.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Resolve a {@link ParsedRoster} onto 40kdc entity ids, producing a {@link Roster}.
+ *
+ * Resolution is lenient: a name that doesn't match a 40kdc entity yields a
+ * {@link ResolvedRef} with `id: null`, `resolved: false`, and up to five
+ * candidate suggestions — the roster is never dropped or rejected. Everything
+ * that didn't resolve cleanly is summarised in the {@link Diagnostics} block.
+ *
+ * Matching reuses the dataset's own lookups ({@link Collection.find},
+ * {@link Collection.findAll}, {@link Collection.byFaction}) and
+ * {@link normalizeName}; there is no bespoke fuzzy matcher. Faction is resolved
+ * first so unit/detachment/enhancement lookups can be scoped to it — the same
+ * unit id can appear under several factions, so scoping disambiguates.
+ *
+ * @packageDocumentation
+ */
+import type { Dataset } from "../data/dataset.js";
+import type { ParsedRoster, Roster } from "./types.js";
+export declare function resolve(parsed: ParsedRoster, ds: Dataset): Roster;

package/dist/import/resolve.js

@@ -0,0 +1,187 @@
+import { normalizeName } from "../data/normalize.js";
+/** The dataset edition/dataslate stamped onto an imported roster. */
+const ROSTER_GAME_VERSION = { edition: "11th", dataslate: "pre-launch-provisional" };
+const MAX_CANDIDATES = 5;
+/** Accumulates warnings and resolved/unresolved tallies during an import. */
+class DiagnosticsBuilder {
+    resolved_units = 0;
+    unresolved_units = 0;
+    resolved_weapons = 0;
+    unresolved_weapons = 0;
+    warnings = [];
+    warn(code, message, raw_name = null) {
+        this.warnings.push({ code, message, raw_name });
+    }
+    build() {
+        return {
+            resolved_units: this.resolved_units,
+            unresolved_units: this.unresolved_units,
+            resolved_weapons: this.resolved_weapons,
+            unresolved_weapons: this.unresolved_weapons,
+            warnings: this.warnings,
+        };
+    }
+}
+function unresolved(raw_name, candidates = []) {
+    return { id: null, raw_name, resolved: false, candidates };
+}
+function resolved(id, raw_name) {
+    return { id, raw_name, resolved: true, candidates: [] };
+}
+function toCandidates(records) {
+    return records.slice(0, MAX_CANDIDATES).map((r) => ({ id: r.id, name: r.name }));
+}
+/** Map a source battle-size label to the 40kdc enum, if recognisable. */
+function mapBattleSize(raw) {
+    if (!raw)
+        return null;
+    const key = normalizeName(raw);
+    if (key.includes("strike force"))
+        return "strike-force";
+    if (key.includes("incursion"))
+        return "incursion";
+    return null;
+}
+export function resolve(parsed, ds) {
+    const diag = new DiagnosticsBuilder();
+    if (parsed.multi_force) {
+        diag.warn("multi-force", "Source list contains more than one faction; the primary faction was used for scoping.");
+    }
+    // --- Faction (resolved first so other lookups can scope to it). -----------
+    let faction_id = null;
+    if (parsed.faction_raw_name) {
+        const hit = ds.factions.find(parsed.faction_raw_name);
+        if (hit) {
+            faction_id = hit.id;
+        }
+        else {
+            diag.warn("faction-unresolved", "Faction name did not match any 40kdc faction.", parsed.faction_raw_name);
+        }
+    }
+    // --- Detachment (scoped to faction, then global fallback). ----------------
+    let detachment_id = null;
+    if (parsed.detachment_raw_name) {
+        const key = normalizeName(parsed.detachment_raw_name);
+        const scoped = faction_id
+            ? ds.detachments.byFaction(faction_id).find((d) => normalizeName(d.name ?? "") === key)
+            : undefined;
+        const hit = scoped ?? ds.detachments.find(parsed.detachment_raw_name);
+        if (hit) {
+            detachment_id = hit.id;
+        }
+        else {
+            diag.warn("detachment-unresolved", "Detachment name did not match any 40kdc detachment.", parsed.detachment_raw_name);
+        }
+    }
+    // --- Battle size. ---------------------------------------------------------
+    const battle_size = mapBattleSize(parsed.battle_size_raw);
+    if (parsed.battle_size_raw && battle_size === null) {
+        diag.warn("battle-size-unmapped", "Battle size label could not be mapped.", parsed.battle_size_raw);
+    }
+    // --- Units (and their enhancements / wargear). ----------------------------
+    const units = parsed.units.map((u) => resolveUnit(u, faction_id, detachment_id, ds, diag));
+    // --- Leader attachments (second pass: needs all resolved unit ids). -------
+    inferLeaderAttachments(parsed.units, units, ds, diag);
+    // --- Points reconciliation (reported vs computed kept distinct). ----------
+    if (parsed.total_reported !== null && parsed.total_reported !== parsed.total_computed) {
+        diag.warn("points-mismatch", `Source-reported total (${parsed.total_reported}) differs from the sum of cost lines (${parsed.total_computed}).`);
+    }
+    return {
+        name: parsed.name,
+        source: { format: "listforge", generated_by: parsed.generated_by },
+        faction_id,
+        detachment_id,
+        battle_size,
+        points: {
+            declared_limit: parsed.declared_limit,
+            total_reported: parsed.total_reported,
+            total_computed: parsed.total_computed,
+        },
+        units,
+        game_version: { ...ROSTER_GAME_VERSION },
+        diagnostics: diag.build(),
+    };
+}
+function resolveUnit(parsed, faction_id, detachment_id, ds, diag) {
+    // Prefer a faction-scoped match (the same unit id recurs across factions),
+    // then fall back to a global name lookup.
+    const key = normalizeName(parsed.raw_name);
+    const scoped = faction_id
+        ? ds.units.byFaction(faction_id).find((u) => normalizeName(u.name) === key)
+        : undefined;
+    const all = ds.units.findAll(parsed.raw_name);
+    const hit = scoped ?? all[0];
+    let ref;
+    if (hit) {
+        ref = resolved(hit.id, parsed.raw_name);
+        diag.resolved_units += 1;
+    }
+    else {
+        ref = unresolved(parsed.raw_name, toCandidates(all));
+        diag.unresolved_units += 1;
+        diag.warn("unit-unresolved", "Unit name did not match any 40kdc unit.", parsed.raw_name);
+    }
+    const enhancement = parsed.enhancement_raw_name
+        ? resolveEnhancement(parsed.enhancement_raw_name, detachment_id, ds, diag)
+        : null;
+    const wargear = parsed.wargear.map((w) => {
+        const hits = ds.weapons.findAll(w.raw_name);
+        if (hits[0]) {
+            diag.resolved_weapons += 1;
+            return { ref: resolved(hits[0].id, w.raw_name), count: w.count };
+        }
+        diag.unresolved_weapons += 1;
+        diag.warn("weapon-unresolved", "Weapon name did not match any 40kdc weapon.", w.raw_name);
+        return { ref: unresolved(w.raw_name, toCandidates(hits)), count: w.count };
+    });
+    return {
+        ref,
+        model_count: parsed.model_count,
+        points: parsed.points,
+        is_warlord: parsed.is_warlord,
+        enhancement,
+        wargear,
+        leader_attachment: null,
+    };
+}
+function resolveEnhancement(raw_name, detachment_id, ds, diag) {
+    const key = normalizeName(raw_name);
+    // Enhancements belong to a detachment, not a faction — scope by detachment_id.
+    const scoped = detachment_id
+        ? ds.enhancements.all.find((e) => e.detachment_id === detachment_id && normalizeName(e.name ?? "") === key)
+        : undefined;
+    const hit = scoped ?? ds.enhancements.find(raw_name);
+    if (hit) {
+        return resolved(hit.id, raw_name);
+    }
+    diag.warn("enhancement-unresolved", "Enhancement name did not match any 40kdc enhancement.", raw_name);
+    return unresolved(raw_name, toCandidates(ds.enhancements.findAll(raw_name)));
+}
+/**
+ * Infer leader→bodyguard attachments. The source format does not encode an
+ * unambiguous attachment, so each inferred link is marked provisional: we match
+ * a resolved character unit against a resolved non-character unit in the same
+ * roster using the dataset's leader-attachment data.
+ */
+function inferLeaderAttachments(parsedUnits, units, ds, diag) {
+    const bodyguardIds = new Set(units.filter((u, i) => u.ref.id && !parsedUnits[i].is_character).map((u) => u.ref.id));
+    units.forEach((unit, i) => {
+        if (!unit.ref.id || !parsedUnits[i].is_character)
+            return;
+        const leaderId = unit.ref.id;
+        const attachment = ds.leaderAttachments.find((la) => la.leader_id === leaderId);
+        if (!attachment)
+            return;
+        const bodyguardId = attachment.eligible_bodyguard_ids.find((id) => bodyguardIds.has(id));
+        if (!bodyguardId)
+            return;
+        const bodyguard = units.find((u) => u.ref.id === bodyguardId);
+        if (!bodyguard)
+            return;
+        unit.leader_attachment = {
+            bodyguard_ref: resolved(bodyguardId, bodyguard.ref.raw_name),
+            provisional: true,
+        };
+        diag.warn("leader-attachment-inferred", "Leader attachment was inferred from leader-attachment data and is provisional.", unit.ref.raw_name);
+    });
+}

package/dist/import/types.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Types for the army-list importer.
+ *
+ * Two layers live here:
+ * - The **output** types ({@link Roster} and friends) mirror
+ *   `schemas/core/roster.schema.json` field-for-field. They are hand-authored
+ *   rather than generated so importer work isn't gated on the Rust→typify codegen
+ *   round-trip; the AJV validator (against the real schema) is the source of truth
+ *   for conformance.
+ * - The **intermediate** type ({@link ParsedRoster}) is format-agnostic: a parser
+ *   adapter lowers a source payload to this shape (raw names + counts only, no
+ *   resolved ids), and {@link resolve} turns it into a {@link Roster}.
+ *
+ * Nothing here ever carries reproduced rules or ability text — only permitted
+ * facts (names, counts, points, keywords, entity ids).
+ *
+ * @packageDocumentation
+ */
+/** A 40kdc battle size (mirrors the shared `battle-size` def). */
+export type BattleSize = "incursion" | "strike-force";
+/** Diagnostic warning codes emitted during an import. */
+export type WarningCode = "faction-unresolved" | "unit-unresolved" | "weapon-unresolved" | "enhancement-unresolved" | "detachment-unresolved" | "battle-size-unmapped" | "points-mismatch" | "leader-attachment-inferred" | "multi-force" | "unknown-field";
+/** A near-match suggestion offered when resolution fails. */
+export interface Candidate {
+    id: string;
+    name: string;
+}
+/**
+ * A reference to a 40kdc entity that may or may not have resolved. Retains the
+ * source's raw name so the import is lossless even on a miss.
+ */
+export interface ResolvedRef {
+    /** Resolved entity id, or null when no match was found. */
+    id: string | null;
+    /** The display name exactly as it appeared in the source payload. */
+    raw_name: string;
+    /** True iff {@link id} is non-null. */
+    resolved: boolean;
+    /** Up to 5 best-guess alternatives when resolution failed. */
+    candidates: Candidate[];
+}
+/** A weapon/wargear selection on a unit. */
+export interface RosterWargear {
+    ref: ResolvedRef;
+    count: number;
+}
+/** An inferred, always-provisional leader→bodyguard attachment. */
+export interface RosterLeaderAttachment {
+    bodyguard_ref: ResolvedRef;
+    provisional: boolean;
+}
+/** One unit entry in a roster. */
+export interface RosterUnit {
+    ref: ResolvedRef;
+    model_count: number;
+    points: number | null;
+    is_warlord: boolean;
+    enhancement: ResolvedRef | null;
+    wargear: RosterWargear[];
+    leader_attachment: RosterLeaderAttachment | null;
+}
+/** Provenance of the imported list. */
+export interface RosterSource {
+    format: "listforge";
+    generated_by: string | null;
+}
+/** Point totals; reported and computed are kept distinct, never reconciled. */
+export interface RosterPoints {
+    declared_limit: number | null;
+    total_reported: number | null;
+    total_computed: number;
+}
+/** A single diagnostic warning. */
+export interface Warning {
+    code: WarningCode;
+    message: string;
+    raw_name: string | null;
+}
+/** A summary of what resolved and what did not during the import. */
+export interface Diagnostics {
+    resolved_units: number;
+    unresolved_units: number;
+    resolved_weapons: number;
+    unresolved_weapons: number;
+    warnings: Warning[];
+}
+/** Reference to the game edition + dataslate (mirrors game-version-ref). */
+export interface GameVersionRef {
+    edition: string;
+    dataslate: string;
+}
+/** A fully-resolved army list. Validates against `roster.schema.json`. */
+export interface Roster {
+    name: string;
+    source: RosterSource;
+    faction_id: string | null;
+    detachment_id: string | null;
+    battle_size: BattleSize | null;
+    points: RosterPoints;
+    units: RosterUnit[];
+    game_version: GameVersionRef;
+    diagnostics: Diagnostics;
+}
+/** A weapon/wargear selection before id resolution. */
+export interface ParsedWargear {
+    raw_name: string;
+    count: number;
+}
+/** A unit selection before id resolution. */
+export interface ParsedUnit {
+    raw_name: string;
+    /** True when the source classifies this as a character/leader-capable model. */
+    is_character: boolean;
+    model_count: number;
+    points: number | null;
+    is_warlord: boolean;
+    enhancement_raw_name: string | null;
+    wargear: ParsedWargear[];
+}
+/**
+ * The format-agnostic intermediate. A {@link FormatAdapter} produces this from a
+ * decoded source payload; {@link resolve} consumes it. Contains only raw display
+ * names and counts — never reproduced rules text.
+ */
+export interface ParsedRoster {
+    name: string;
+    generated_by: string | null;
+    /** Raw faction name from the source (e.g. "Grey Knights"). */
+    faction_raw_name: string | null;
+    /** Raw detachment name (e.g. "Banishers"). */
+    detachment_raw_name: string | null;
+    /** Raw battle-size label (e.g. "2. Strike Force (2000 Point limit)"). */
+    battle_size_raw: string | null;
+    /** Points limit parsed from the battle-size label, if any. */
+    declared_limit: number | null;
+    /** Total points reported by the source cost block. */
+    total_reported: number | null;
+    /** Points summed from every cost line in the source tree. */
+    total_computed: number;
+    units: ParsedUnit[];
+    /** True when the source contained more than one distinct faction. */
+    multi_force: boolean;
+}

package/dist/import/types.js

@@ -0,0 +1,19 @@
+/**
+ * Types for the army-list importer.
+ *
+ * Two layers live here:
+ * - The **output** types ({@link Roster} and friends) mirror
+ *   `schemas/core/roster.schema.json` field-for-field. They are hand-authored
+ *   rather than generated so importer work isn't gated on the Rust→typify codegen
+ *   round-trip; the AJV validator (against the real schema) is the source of truth
+ *   for conformance.
+ * - The **intermediate** type ({@link ParsedRoster}) is format-agnostic: a parser
+ *   adapter lowers a source payload to this shape (raw names + counts only, no
+ *   resolved ids), and {@link resolve} turns it into a {@link Roster}.
+ *
+ * Nothing here ever carries reproduced rules or ability text — only permitted
+ * facts (names, counts, points, keywords, entity ids).
+ *
+ * @packageDocumentation
+ */
+export {};

package/dist/index.d.ts

@@ -1,3 +1,6 @@
 export * from "./data/index.js";
 export * from "./generated.js";
 export { createValidator, findSchemaFiles, listSchemaIds, SCHEMAS_ROOT, } from "./schema-loader.js";
+export { importListForge, importRoster, decodeListForge } from "./import/index.js";
+export type { FormatAdapter } from "./import/index.js";
+export type { ImportOptions, Roster, RosterUnit, RosterWargear, RosterSource, RosterPoints, RosterLeaderAttachment, ResolvedRef, Candidate, Diagnostics, Warning, WarningCode, ParsedRoster, ParsedUnit, ParsedWargear, } from "./import/index.js";

package/dist/index.js

@@ -5,3 +5,7 @@ export * from "./generated.js";
 // Schema access + AJV validation (secondary: this package also validates data
 // against the canonical JSON Schemas).
 export { createValidator, findSchemaFiles, listSchemaIds, SCHEMAS_ROOT, } from "./schema-loader.js";
+// Army-list importer (ListForge → resolved 40kdc roster). Types are curated
+// rather than re-exported wholesale to avoid name clashes with generated types
+// (e.g. BattleSize, LeaderAttachment).
+export { importListForge, importRoster, decodeListForge } from "./import/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alpaca-software/40kdc-data",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "The 40kdc Warhammer 40K dataset behind a linked, typed API — find units, follow them to their weapons, abilities, phases, and factions. Also validates data against the canonical JSON Schemas.",
   "keywords": [
@@ -46,6 +46,7 @@
   "scripts": {
     "build": "npm run codegen:data && tsc",
     "codegen:data": "tsx src/codegen-data.ts",
+    "gen:conformance": "tsx src/gen-conformance.ts",
     "docs:api": "typedoc",
     "validate": "tsx src/cli.ts validate-all",
     "validate:core": "tsx src/cli.ts validate-core",