bsdata-parser 0.1.2 → 0.1.3

package/README.md

@@ -1,55 +1,167 @@
 # bsdata-parser
 
-A faithful parser for [BSData](https://github.com/BSData) XML into an intermediate representation
-(IR), plus a golden-diff harness for validating a downstream projection of that IR against a
-reference output.
+A faithful, typed parser for [BSData](https://github.com/BSData) `.gst`/`.cat` XML game-data files into a typed Intermediate Representation (IR), plus a golden-diff harness for validating a downstream projection against a reference output.
 
-The parser exists to replace a **lossy** flatten: a naive parser drops conditions in the source it
-cannot statically resolve, which is the root cause of recurring "missing option" bugs in the
-downstream consumer. The rebuild keeps those conditions in the IR and resolves them in the projection.
+[![CI](https://github.com/aodhan-dev/bsdata-parser/actions/workflows/ci.yml/badge.svg)](https://github.com/aodhan-dev/bsdata-parser/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/bsdata-parser)](https://www.npmjs.com/package/bsdata-parser)
 
-## Design
+## Why
+
+Naive BSData parsers flatten the XML as they go, silently dropping modifiers and conditions they cannot statically resolve. The result is recurring "missing option" bugs whenever BSData's conditional logic kicks in. This library solves that by keeping the full modifier/condition tree in the IR and leaving resolution to the projection layer.
+
+## Architecture
 
 ```
-BSData (.gst/.cat)  ──parse──▶  IR (faithful tree)  ──project──▶  output
-                                                                     │
-                                       reference output  ◀──diff─────┘  (oracle)
+BSData (.gst/.cat)  ──parse──▶  IR (faithful tree)  ──project──▶  your output
+                                                                        │
+                                       reference output  ◀───diff───────┘
 ```
 
-- **`src/parse`** — XML → IR. Mechanical transcription, domain-agnostic, no interpretation. *(stub)*
-- **`src/project`** — IR → output. All domain interpretation lives here. Supplied locally. *(stub)*
-- **`src/index.ts`** — `buildCatalogue(files)`, signature-compatible with the downstream consumer
-  for incremental integration.
-- **`harness/`** — the golden diff. `loadOracle()`/`loadBsdata()` read from a local data directory;
-  `diffCatalogues()` asserts the candidate reproduces the reference as a superset.
+- **`src/parse`** - XML to IR. Mechanical transcription only: no interpretation, no flattening, no domain knowledge. Every modifier, condition, constraint, and repeat node is preserved verbatim.
+- **`src/project`** - IR to output. All domain interpretation lives here. This layer is intentionally not included in the package - you supply it, shaped to your own output schema.
+- **`harness/`** - golden-diff utilities. Load a reference output (oracle) and diff a candidate against it to find gaps. Auto-skips when no local data is present, so the test suite runs cleanly everywhere.
 
-## Data (local only, never committed)
+## Installation
 
-No data is bundled with this repo. The BSData source files and the reference output are third-party
-content you assemble yourself. Point the `BSDATA_DIR` environment variable at a local directory
-containing:
+```bash
+npm install bsdata-parser
+```
 
-- `bsdata/` — the `.cat`/`.gst` source set (input to the parser)
-- `catalogue.json` — a reference output (the oracle to diff against)
+## Usage
 
-Everything under that directory stays outside the repo. The concrete domain projector you plug into
-`src/project` is likewise kept local (gitignored), so nothing data- or domain-specific is published.
+```typescript
+import { parseToIr } from 'bsdata-parser'
+import type { Ir } from 'bsdata-parser'
 
-## Commands
+// 1. Load your .gst/.cat files however you like (fs, fetch, etc.)
+const files: Record<string, string> = {
+  'my-game.gst': '<gameSystem ...>...</gameSystem>',
+  'faction-a.cat': '<catalogue ...>...</catalogue>',
+}
+
+// 2. Parse to IR - faithful, lossless, typed
+const ir: Ir = parseToIr(files)
+
+// 3. Project to your output schema
+const output = myProjector(ir)
+```
+
+`parseToIr` accepts a `filename -> XML string` map and returns an `Ir` object containing the fully parsed game system and all catalogues as typed trees.
+
+## IR shape
+
+```typescript
+interface Ir {
+  gameSystem: IrCatalogueFile   // the .gst file
+  catalogues: IrCatalogueFile[] // all .cat files
+}
+
+interface IrCatalogueFile {
+  filename: string
+  kind: 'gameSystem' | 'catalogue'
+  id: string
+  name: string
+  gameSystemId?: string
+  catalogueLinks: IrCatalogueLink[]
+  root: IrCatalogueRoot
+}
+
+interface IrCatalogueRoot {
+  costTypes: IrCostType[]
+  profileTypes: IrProfileType[]
+  categoryEntries: IrCategoryEntry[]
+  rules: IrRule[]
+  sharedRules: IrRule[]
+  sharedProfiles: IrProfile[]
+  selectionEntries: IrSelectionEntry[]
+  sharedSelectionEntries: IrSelectionEntry[]
+  sharedSelectionEntryGroups: IrSelectionEntryGroup[]
+  entryLinks: IrEntryLink[]
+  forceEntries: IrForceEntry[]
+}
+```
+
+All node types (`IrSelectionEntry`, `IrConstraint`, `IrModifier`, `IrCondition`, etc.) are exported from the package. See `src/ir/types.ts` for the complete set.
+
+## Writing a projector
+
+A projector is a function `(ir: Ir) => YourOutputType`. It lives in your own codebase and is never part of this package:
 
-- `npm test` — unit suite plus the golden-parity test (auto-skips unless `BSDATA_DIR` is set,
-  so it runs cleanly anywhere, including CI with no data).
-- `npm run golden` — run the golden diff against the local reference and print the gap.
-- `npm run build` — build a local output from the local source with the parser.
-- `npm run typecheck` — `tsc --noEmit`.
+```typescript
+import { parseToIr } from 'bsdata-parser'
+import type { Ir } from 'bsdata-parser'
 
-## Status
+function projectMyGame(ir: Ir): MyOutput {
+  const categories: Record<string, string> = {}
+  for (const entry of ir.gameSystem.root.categoryEntries) {
+    categories[entry.id] = entry.name
+  }
+
+  const units = ir.catalogues.flatMap(cat =>
+    cat.root.sharedSelectionEntries
+      .filter(e => e.type === 'unit' && !e.hidden)
+      .map(e => ({ id: e.id, name: e.name, faction: cat.name }))
+  )
+
+  return { categories, units }
+}
+
+export function buildOutput(files: Record<string, string>): MyOutput {
+  return projectMyGame(parseToIr(files))
+}
+```
+
+## Golden-diff harness
+
+The `harness/` directory contains utilities for validating that your projector reproduces a known-good reference output as a superset. Copy or adapt these into your own project:
+
+- `harness/oracle.ts` - `loadBsdata()`, `loadOracle()`, `hasData()` (reads from `BSDATA_DIR`)
+- `harness/diff.ts` - `diffCatalogues(oracle, candidate)` - counts-based diff, domain-agnostic
+
+Set `BSDATA_DIR` to a local directory containing:
+- `bsdata/` - the `.cat`/`.gst` source files
+- `catalogue.json` - a reference output to diff against
+
+```typescript
+// your-project/harness/golden-parity.test.ts
+import { describe, it, expect } from 'vitest'
+import { readFile, readdir } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { buildOutput } from './my-projector'
+
+const dir = process.env.BSDATA_DIR ?? ''
+const hasData = () => existsSync(join(dir, 'catalogue.json'))
+
+describe.skipIf(!hasData())('golden parity', () => {
+  it('reproduces every oracle collection', async () => {
+    const oracle = JSON.parse(await readFile(join(dir, 'catalogue.json'), 'utf-8'))
+    const names = (await readdir(join(dir, 'bsdata'))).filter(f => f.endsWith('.cat') || f.endsWith('.gst'))
+    const files: Record<string, string> = {}
+    await Promise.all(names.map(async n => { files[n] = await readFile(join(dir, 'bsdata', n), 'utf-8') }))
+    const candidate = buildOutput(files)
+    // diff: for every key in oracle, compare collection size
+    const diffs = Object.keys(oracle).filter(k => {
+      const size = (v: unknown) => Array.isArray(v) ? v.length : v && typeof v === 'object' ? Object.keys(v as object).length : 0
+      return size(oracle[k]) !== size((candidate as Record<string, unknown>)[k])
+    })
+    expect(diffs).toEqual([])
+  })
+})
+```
+
+## Data and domain code (never committed)
+
+No game data is bundled here. BSData source files are third-party content you assemble yourself. Your projector is likewise kept local - nothing data- or domain-specific should be published.
+
+## Commands
 
-Scaffold. `parseToIr`/`projectCatalogue` are stubs, so the golden-parity test is **red by design** —
-that is the baseline the rebuild is built green against, test-first.
+| Command | Description |
+|---------|-------------|
+| `npm test` | Unit suite + golden-parity test (auto-skips without `BSDATA_DIR`) |
+| `npm run build` | Compile to `dist/` via tsup |
+| `npm run typecheck` | `tsc --noEmit` |
 
-## Method
+## License
 
-TDD against the BSData XML as the source of truth: establish the expected value from the `.cat`/`.gst`
-before writing the assertion. The golden diff is the integration oracle; per-entity unit tests are
-the inner loop.
+MIT

package/dist/index.d.ts

@@ -1,9 +1,257 @@
+/**
+ * BSData intermediate representation (IR).
+ *
+ * A FAITHFUL, lossless-by-intent tree mirror of the BSData .gst / .cat model.
+ * Nothing is resolved, flattened, or interpreted here. Scope strings are raw BSData
+ * values. Modifier/condition trees are opaque. All interpretation belongs in the
+ * projection (src/project).
+ */
+interface IrConstraint {
+    id: string;
+    type: 'min' | 'max';
+    value: number;
+    scope: string;
+    field: string;
+    shared?: boolean;
+    includeChildSelections?: boolean;
+}
+interface IrCharacteristic {
+    name: string;
+    typeId: string;
+    value: string;
+}
+interface IrProfile {
+    id: string;
+    name: string;
+    hidden: boolean;
+    typeId: string;
+    typeName: string;
+    characteristics: IrCharacteristic[];
+}
+interface IrCost {
+    name: string;
+    typeId: string;
+    value: number;
+}
+interface IrRule {
+    id: string;
+    name: string;
+    hidden: boolean;
+    description: string;
+}
+interface IrInfoLink {
+    id: string;
+    name: string;
+    hidden: boolean;
+    targetId: string;
+    type: string;
+}
+interface IrCategoryLink {
+    id: string;
+    targetId: string;
+    primary: boolean;
+}
+/** Verbatim condition node - not evaluated, retained for the modifier tree. */
+interface IrCondition {
+    type: string;
+    value: number;
+    field: string;
+    scope: string;
+    childId?: string;
+    shared?: boolean;
+    includeChildSelections?: boolean;
+    percentValue?: boolean;
+}
+interface IrConditionGroup {
+    type: string;
+    conditions: IrCondition[];
+    conditionGroups: IrConditionGroup[];
+}
+/** Verbatim modifier node - not evaluated. */
+interface IrModifier {
+    type: string;
+    field: string;
+    value: string | number;
+    conditions: IrCondition[];
+    conditionGroups: IrConditionGroup[];
+    repeats: IrRepeat[];
+}
+/**
+ * A BSData modifierGroup node: a block of modifiers that share a common set of conditions.
+ * Equivalent to a conditional modifier block - the conditions guard when ALL the inner modifiers apply.
+ */
+interface IrModifierGroup {
+    type: string;
+    modifiers: IrModifier[];
+    conditions: IrCondition[];
+    conditionGroups: IrConditionGroup[];
+    modifierGroups: IrModifierGroup[];
+}
+interface IrRepeat {
+    value: number;
+    repeats: number;
+    field: string;
+    scope: string;
+    childId?: string;
+    shared?: boolean;
+    includeChildSelections?: boolean;
+    roundUp?: boolean;
+}
+type IrEntryType = 'unit' | 'model' | 'upgrade' | 'mount';
+interface IrSelectionEntry {
+    id: string;
+    name: string;
+    hidden: boolean;
+    collective: boolean;
+    import: boolean;
+    type: IrEntryType;
+    defaultAmount?: number;
+    constraints: IrConstraint[];
+    profiles: IrProfile[];
+    rules: IrRule[];
+    infoLinks: IrInfoLink[];
+    categoryLinks: IrCategoryLink[];
+    costs: IrCost[];
+    modifiers: IrModifier[];
+    modifierGroups?: IrModifierGroup[];
+    selectionEntries: IrSelectionEntry[];
+    selectionEntryGroups: IrSelectionEntryGroup[];
+    entryLinks: IrEntryLink[];
+}
+interface IrSelectionEntryGroup {
+    id: string;
+    name: string;
+    hidden: boolean;
+    collective: boolean;
+    import: boolean;
+    defaultSelectionEntryId?: string;
+    constraints: IrConstraint[];
+    modifiers: IrModifier[];
+    modifierGroups?: IrModifierGroup[];
+    selectionEntries: IrSelectionEntry[];
+    selectionEntryGroups: IrSelectionEntryGroup[];
+    entryLinks: IrEntryLink[];
+}
+interface IrEntryLink {
+    id: string;
+    name: string;
+    hidden: boolean;
+    collective: boolean;
+    import: boolean;
+    flatten: boolean;
+    targetId: string;
+    type: string;
+    defaultAmount?: number;
+    comment?: string;
+    constraints: IrConstraint[];
+    costs: IrCost[];
+    modifiers: IrModifier[];
+    modifierGroups?: IrModifierGroup[];
+    profiles: IrProfile[];
+    infoLinks: IrInfoLink[];
+    categoryLinks: IrCategoryLink[];
+    selectionEntries: IrSelectionEntry[];
+    selectionEntryGroups: IrSelectionEntryGroup[];
+    entryLinks: IrEntryLink[];
+}
+interface IrCategoryEntry {
+    id: string;
+    name: string;
+    hidden: boolean;
+}
+interface IrForceCategoryLink {
+    id: string;
+    targetId: string;
+    primary: boolean;
+    hidden: boolean;
+    constraints: IrConstraint[];
+}
+interface IrForceEntry {
+    id: string;
+    name: string;
+    hidden: boolean;
+    constraints: IrConstraint[];
+    categoryLinks: IrForceCategoryLink[];
+    rules: IrRule[];
+    modifiers: IrModifier[];
+    forceEntries: IrForceEntry[];
+}
+interface IrCostType {
+    id: string;
+    name: string;
+    defaultCostLimit: number;
+}
+/** A BSData catalogueLink node: references another catalogue this one imports from. */
+interface IrCatalogueLink {
+    id: string;
+    name: string;
+    targetId: string;
+    type: string;
+    importRootEntries: boolean;
+}
+interface IrProfileType {
+    id: string;
+    name: string;
+    characteristicTypes: Array<{
+        id: string;
+        name: string;
+    }>;
+}
+interface IrCatalogueRoot {
+    costTypes: IrCostType[];
+    profileTypes: IrProfileType[];
+    categoryEntries: IrCategoryEntry[];
+    rules: IrRule[];
+    /** Rules from the BSData &lt;sharedRules&gt; element: the canonical rule-definition pool. */
+    sharedRules: IrRule[];
+    /** Profiles from the BSData &lt;sharedProfiles&gt; element: abilities with Summary/Description characteristics. */
+    sharedProfiles: IrProfile[];
+    selectionEntries: IrSelectionEntry[];
+    sharedSelectionEntries: IrSelectionEntry[];
+    sharedSelectionEntryGroups: IrSelectionEntryGroup[];
+    entryLinks: IrEntryLink[];
+    forceEntries: IrForceEntry[];
+}
+/** A single parsed BSData file (game system or catalogue). */
+interface IrCatalogueFile {
+    filename: string;
+    kind: 'gameSystem' | 'catalogue';
+    id: string;
+    name: string;
+    gameSystemId?: string;
+    catalogueLinks: IrCatalogueLink[];
+    root: IrCatalogueRoot;
+}
+/** The whole parsed source set: the game system plus every catalogue. */
+interface Ir {
+    gameSystem: IrCatalogueFile;
+    catalogues: IrCatalogueFile[];
+}
+
+declare function parseToIr(files: Record<string, string>): Ir;
+
+/**
+ * IR -> downstream projection.
+ *
+ * Projects the faithful IR into the flattened, ready-to-consume shape the downstream application
+ * needs. ALL domain interpretation lives here; the IR and parser stay domain-agnostic. The concrete
+ * projector and its reference data are supplied locally and are never committed to this repo (see
+ * README) -- this repo ships the framework, not any specific data model.
+ *
+ * "Superset" is the contract: the projection MUST reproduce every field the reference output carries
+ * (so the existing consumer keeps working unchanged), and MAY add fields the current consumer lacks.
+ * The golden-diff harness asserts the reproduction half; new fields are additive and ignored.
+ *
+ * STUB. Supply a local implementation that imports your projector modules. The local file is
+ * gitignored so it never reaches this public repo. See CLAUDE.md for the hygiene rule.
+ */
+declare function projectCatalogue(_ir: Ir): Record<string, unknown>;
+
 /**
  * Public entry point. `filename -> XML` map in, projected output object out. The signature matches
  * the downstream consumer's existing build step so this can be wired in incrementally (swap the
  * import, keep the golden diff green) without touching the consumer.
  */
-export declare function buildCatalogue(files: Record<string, string>): Record<string, unknown>;
-export { parseToIr } from './parse/index';
-export { projectCatalogue } from './project/catalogue';
-export type { Ir, IrCatalogueFile, IrModifierGroup } from './ir/types';
+declare function buildCatalogue(files: Record<string, string>): Record<string, unknown>;
+
+export { type Ir, type IrCatalogueFile, type IrModifierGroup, buildCatalogue, parseToIr, projectCatalogue };