jspurefix 5.11.2 → 5.11.4

package/src/generator/corpus-store.ts

@@ -0,0 +1,166 @@
+import * as fs from 'fs'
+import * as path from 'path'
+import { IScatterPlan } from './scatter'
+import { CaseOutcome } from './outcome'
+import { IGeneratedCase } from './case-builder'
+
+/**
+ * The corpus: edge cases kept as bytes, not as recipes.
+ *
+ * The generator is how a case is *found*; it is not what a case *is*.  A seed reproduces
+ * a message only while the generator is unchanged - adjust one probability in the value
+ * conventions and the random stream reshuffles, so every seed produces a different
+ * message and every recorded expectation quietly stops describing what it was written
+ * for.  A corpus that has to be regenerated to be read is not a corpus.
+ *
+ * So an entry is the two encodings, frozen, plus the expectation someone looked at and
+ * agreed with.  Adding one is: generate until the tool proposes something interesting,
+ * read it, commit it.  From then on it tests the same bytes forever, and it keeps
+ * testing them if the generator is deleted.
+ *
+ * Layout, one directory per case:
+ *
+ *     data/corpus/<name>/case.json        metadata, plan and expected outcome
+ *     data/corpus/<name>/canonical.txt    the contiguous encoding - the oracle
+ *     data/corpus/<name>/scattered.txt    the legal re-ordering under test
+ */
+
+export interface ICorpusEntry {
+  readonly name: string
+  /** what this case is here to demonstrate, in a sentence */
+  readonly note: string
+  /** dictionary the case was built against, e.g. `repo44` */
+  readonly dictionary: string
+  /** session description used to encode and parse, relative to `data/` */
+  readonly session: string
+  readonly delimiter: string
+  /** what the engine does with it today, agreed by whoever added the case */
+  readonly expected: CaseOutcome
+  /**
+   * when `expected` is not `round-trips`, the leaf paths involved.  Recorded so a change
+   * in *how* a case fails is a test failure too, not just a change in whether it does.
+   */
+  readonly missing?: string[]
+  readonly added?: string[]
+  readonly changed?: string[]
+  /** how the case was originally found - provenance, not a way to rebuild it */
+  readonly origin?: {
+    readonly scenario?: string
+    readonly seed?: number
+    readonly depth?: number
+    readonly fragments?: number
+    readonly asOf?: string
+  }
+  readonly plan: IScatterPlan
+}
+
+export interface ILoadedCase {
+  readonly entry: ICorpusEntry
+  readonly canonical: string
+  readonly scattered: string
+  readonly directory: string
+}
+
+const CASE_FILE = 'case.json'
+const CANONICAL_FILE = 'canonical.txt'
+const SCATTERED_FILE = 'scattered.txt'
+
+export class CorpusStore {
+  constructor (public readonly root: string) {
+  }
+
+  public names (): string[] {
+    if (!fs.existsSync(this.root)) return []
+    return fs.readdirSync(this.root)
+      .filter(name => fs.existsSync(path.join(this.root, name, CASE_FILE)))
+      .sort()
+  }
+
+  public load (name: string): ILoadedCase {
+    const directory = path.join(this.root, name)
+    const entry = JSON.parse(fs.readFileSync(path.join(directory, CASE_FILE), 'utf8')) as ICorpusEntry
+    return {
+      entry,
+      canonical: CorpusStore.readWire(path.join(directory, CANONICAL_FILE)),
+      scattered: CorpusStore.readWire(path.join(directory, SCATTERED_FILE)),
+      directory
+    }
+  }
+
+  public loadAll (): ILoadedCase[] {
+    return this.names().map(name => this.load(name))
+  }
+
+  /**
+   * A case file is a fixture a person is expected to read, so it is written with the
+   * commentary a person needs: what the case demonstrates and what the engine does with
+   * it, above the wire.  Everything from the first `8=` is the message.
+   */
+  public save (entry: ICorpusEntry, canonical: string, scattered: string): string {
+    const directory = path.join(this.root, entry.name)
+    fs.mkdirSync(directory, { recursive: true })
+    fs.writeFileSync(path.join(directory, CASE_FILE), `${JSON.stringify(entry, null, 2)}\n`, 'utf8')
+    fs.writeFileSync(
+      path.join(directory, CANONICAL_FILE),
+      CorpusStore.wireFile(entry, 'canonical - dictionary order, contiguous, the oracle', canonical),
+      'utf8')
+    fs.writeFileSync(
+      path.join(directory, SCATTERED_FILE),
+      CorpusStore.wireFile(entry, 'scattered - the same bytes, legally re-ordered', scattered),
+      'utf8')
+    return directory
+  }
+
+  public static fromCase (
+    name: string,
+    note: string,
+    dictionary: string,
+    session: string,
+    delimiter: string,
+    generated: IGeneratedCase,
+    expected: CaseOutcome,
+    detail: { missing: string[], added: string[], changed: string[] },
+    asOf?: Date): ICorpusEntry {
+    return {
+      name,
+      note,
+      dictionary,
+      session,
+      delimiter,
+      expected,
+      missing: detail.missing.length > 0 ? detail.missing : undefined,
+      added: detail.added.length > 0 ? detail.added : undefined,
+      changed: detail.changed.length > 0 ? detail.changed : undefined,
+      origin: {
+        scenario: generated.name,
+        seed: generated.seed,
+        depth: generated.requestedDepth,
+        asOf: asOf ? asOf.toISOString() : undefined
+      },
+      plan: generated.plan
+    }
+  }
+
+  private static wireFile (entry: ICorpusEntry, what: string, wire: string): string {
+    const lines: string[] = []
+    lines.push(`# ${entry.name} - ${what}`)
+    lines.push(`# ${entry.note}`)
+    lines.push(`# dictionary ${entry.dictionary}, expected ${entry.expected}`)
+    for (const site of entry.plan.sites) {
+      lines.push(`# scattered: ${site.component} at structure depth ${site.structureDepth}, ${site.fragments} runs`)
+    }
+    lines.push(wire)
+    return `${lines.join('\n')}\n`
+  }
+
+  /**
+   * the message, ignoring the commentary above it
+   */
+  private static readWire (file: string): string {
+    const text = fs.readFileSync(file, 'utf8')
+    for (const line of text.split(/\r?\n/)) {
+      if (line.startsWith('8=')) return line
+    }
+    throw new Error(`${file} contains no message - expected a line beginning 8=`)
+  }
+}

package/src/generator/index.ts

@@ -0,0 +1,12 @@
+export * from './rng'
+export * from './instrument-universe'
+export * from './market-context'
+export * from './value-conventions'
+export * from './realistic-generator'
+export * from './applicability'
+export * from './scenarios'
+export * from './layout'
+export * from './scatter'
+export * from './outcome'
+export * from './case-builder'
+export * from './corpus-store'

package/src/generator/instrument-universe.ts

@@ -0,0 +1,347 @@
+import { Rng } from './rng'
+
+/**
+ * A small book of instruments that read like instruments.
+ *
+ * The point is not coverage - it is that a generated message can be scanned by eye and
+ * recognised.  `55=BRN` with `541=20251231` and `44=71.35` is a Brent future at a
+ * plausible price; `55=Lorem` with `44=-4534.7` is noise that happens to encode.
+ *
+ * Prices carry a tick and a lot size so quantities and prices agree with the contract
+ * they claim to be, and a spread carries its legs so a multileg message can be built
+ * with parent and legs that actually correspond.
+ */
+
+export enum AssetClass {
+  Equity = 'equity',
+  Future = 'future',
+  Option = 'option',
+  Spread = 'spread',
+  Fx = 'fx',
+  Bond = 'bond'
+}
+
+export interface ILegSpec {
+  readonly symbol: string
+  readonly securityId: string
+  readonly securityIdSource: string
+  readonly securityType: string
+  readonly maturityMonthYear?: string
+  readonly side: string
+  readonly ratio: number
+  readonly refPx: number
+}
+
+export interface IInstrumentSpec {
+  readonly name: string
+  readonly assetClass: AssetClass
+  readonly symbol: string
+  readonly securityId: string
+  /** 1 CUSIP, 2 SEDOL, 4 ISIN, 8 exchange symbol, 9 CTA */
+  readonly securityIdSource: string
+  readonly securityExchange: string
+  readonly securityType: string
+  readonly cfiCode: string
+  readonly currency: string
+  readonly refPx: number
+  readonly tick: number
+  readonly lotSize: number
+  readonly contractMultiplier?: number
+  readonly maturityMonthYear?: string
+  readonly maturityDate?: string
+  readonly strikePrice?: number
+  readonly putOrCall?: number
+  readonly product?: number
+  readonly legs?: readonly ILegSpec[]
+}
+
+const equities: readonly IInstrumentSpec[] = [
+  {
+    name: 'Apple Inc',
+    assetClass: AssetClass.Equity,
+    symbol: 'AAPL',
+    securityId: 'US0378331005',
+    securityIdSource: '4',
+    securityExchange: 'XNAS',
+    securityType: 'CS',
+    cfiCode: 'ESVUFR',
+    currency: 'USD',
+    refPx: 214.5,
+    tick: 0.01,
+    lotSize: 100,
+    product: 5
+  },
+  {
+    name: 'Vodafone Group',
+    assetClass: AssetClass.Equity,
+    symbol: 'VOD.L',
+    securityId: 'GB00BH4HKS39',
+    securityIdSource: '4',
+    securityExchange: 'XLON',
+    securityType: 'CS',
+    cfiCode: 'ESVUFR',
+    currency: 'GBP',
+    refPx: 0.762,
+    tick: 0.0001,
+    lotSize: 1000,
+    product: 5
+  },
+  {
+    name: 'SAP SE',
+    assetClass: AssetClass.Equity,
+    symbol: 'SAP',
+    securityId: 'DE0007164600',
+    securityIdSource: '4',
+    securityExchange: 'XETR',
+    securityType: 'CS',
+    cfiCode: 'ESVUFR',
+    currency: 'EUR',
+    refPx: 196.3,
+    tick: 0.01,
+    lotSize: 100,
+    product: 5
+  }
+]
+
+const futures: readonly IInstrumentSpec[] = [
+  {
+    name: 'ICE Brent Crude Jan26',
+    assetClass: AssetClass.Future,
+    symbol: 'BRN',
+    securityId: 'BRN FMF0026!',
+    securityIdSource: '8',
+    securityExchange: 'IFEU',
+    securityType: 'FUT',
+    cfiCode: 'FCEPSX',
+    currency: 'USD',
+    refPx: 71.35,
+    tick: 0.01,
+    lotSize: 1,
+    contractMultiplier: 1000,
+    maturityMonthYear: '202601',
+    maturityDate: '20251130',
+    product: 2
+  },
+  {
+    name: 'ICE Low Sulphur Gasoil Feb26',
+    assetClass: AssetClass.Future,
+    symbol: 'GAS',
+    securityId: 'GAS FMG0026!',
+    securityIdSource: '8',
+    securityExchange: 'IFEU',
+    securityType: 'FUT',
+    cfiCode: 'FCEPSX',
+    currency: 'USD',
+    refPx: 668.25,
+    tick: 0.25,
+    lotSize: 1,
+    contractMultiplier: 100,
+    maturityMonthYear: '202602',
+    maturityDate: '20260112',
+    product: 2
+  },
+  {
+    name: 'CME E-mini S and P 500 Dec25',
+    assetClass: AssetClass.Future,
+    symbol: 'ES',
+    securityId: 'ESZ5',
+    securityIdSource: '8',
+    securityExchange: 'XCME',
+    securityType: 'FUT',
+    cfiCode: 'FFICSX',
+    currency: 'USD',
+    refPx: 6042.25,
+    tick: 0.25,
+    lotSize: 1,
+    contractMultiplier: 50,
+    maturityMonthYear: '202512',
+    maturityDate: '20251219',
+    product: 5
+  }
+]
+
+const options: readonly IInstrumentSpec[] = [
+  {
+    name: 'CME E-mini Dec25 6000 Call',
+    assetClass: AssetClass.Option,
+    symbol: 'ES',
+    securityId: 'ESZ5 C6000',
+    securityIdSource: '8',
+    securityExchange: 'XCME',
+    securityType: 'OPT',
+    cfiCode: 'OCEFCS',
+    currency: 'USD',
+    refPx: 118.75,
+    tick: 0.25,
+    lotSize: 1,
+    contractMultiplier: 50,
+    maturityMonthYear: '202512',
+    maturityDate: '20251219',
+    strikePrice: 6000,
+    putOrCall: 1,
+    product: 5
+  }
+]
+
+const fx: readonly IInstrumentSpec[] = [
+  {
+    name: 'EUR/USD spot',
+    assetClass: AssetClass.Fx,
+    symbol: 'EUR/USD',
+    securityId: 'EURUSD',
+    securityIdSource: '8',
+    securityExchange: 'XOFF',
+    securityType: 'FXSPOT',
+    cfiCode: 'MRCXXX',
+    currency: 'EUR',
+    refPx: 1.0842,
+    tick: 0.00005,
+    lotSize: 1000000,
+    product: 4
+  }
+]
+
+const bonds: readonly IInstrumentSpec[] = [
+  {
+    name: 'US Treasury 4.25 Nov 2034',
+    assetClass: AssetClass.Bond,
+    symbol: 'T 4.25 11/34',
+    securityId: 'US91282CLW12',
+    securityIdSource: '4',
+    securityExchange: 'XOFF',
+    securityType: 'TBOND',
+    cfiCode: 'DBFUFR',
+    currency: 'USD',
+    refPx: 99.421875,
+    tick: 0.015625,
+    lotSize: 1000,
+    maturityDate: '20341115',
+    product: 6
+  }
+]
+
+/**
+ * The shape the whole scattered component exercise is really about.  ICE publishes
+ * calendar and crack spreads as single tradeable instruments whose fills report a parent
+ * and one leg per contract, and a trade capture for one of these is where deep nesting
+ * shows up in real life.
+ */
+const spreads: readonly IInstrumentSpec[] = [
+  {
+    name: 'ICE Brent Jan26/Feb26 calendar spread',
+    assetClass: AssetClass.Spread,
+    symbol: 'BRN',
+    securityId: 'BRN JAN26-FEB26',
+    securityIdSource: '8',
+    securityExchange: 'IFEU',
+    securityType: 'MLEG',
+    cfiCode: 'FMEPSX',
+    currency: 'USD',
+    refPx: 0.34,
+    tick: 0.01,
+    lotSize: 1,
+    contractMultiplier: 1000,
+    maturityMonthYear: '202601',
+    product: 2,
+    legs: [
+      {
+        symbol: 'BRN',
+        securityId: 'BRN FMF0026!',
+        securityIdSource: '8',
+        securityType: 'FUT',
+        maturityMonthYear: '202601',
+        side: '1',
+        ratio: 1,
+        refPx: 71.35
+      },
+      {
+        symbol: 'BRN',
+        securityId: 'BRN FMG0026!',
+        securityIdSource: '8',
+        securityType: 'FUT',
+        maturityMonthYear: '202602',
+        side: '2',
+        ratio: 1,
+        refPx: 71.01
+      }
+    ]
+  },
+  {
+    name: 'ICE Brent/Gasoil crack spread',
+    assetClass: AssetClass.Spread,
+    symbol: 'BRNGAS',
+    securityId: 'BRN-GAS CRACK',
+    securityIdSource: '8',
+    securityExchange: 'IFEU',
+    securityType: 'MLEG',
+    cfiCode: 'FMEPSX',
+    currency: 'USD',
+    refPx: 12.68,
+    tick: 0.01,
+    lotSize: 1,
+    contractMultiplier: 1000,
+    maturityMonthYear: '202602',
+    product: 2,
+    legs: [
+      {
+        symbol: 'GAS',
+        securityId: 'GAS FMG0026!',
+        securityIdSource: '8',
+        securityType: 'FUT',
+        maturityMonthYear: '202602',
+        side: '1',
+        ratio: 1,
+        refPx: 668.25
+      },
+      {
+        symbol: 'BRN',
+        securityId: 'BRN FMG0026!',
+        securityIdSource: '8',
+        securityType: 'FUT',
+        maturityMonthYear: '202602',
+        side: '2',
+        ratio: 1,
+        refPx: 71.2
+      }
+    ]
+  }
+]
+
+function byClass (assetClass: AssetClass): readonly IInstrumentSpec[] {
+  switch (assetClass) {
+    case AssetClass.Equity: return equities
+    case AssetClass.Future: return futures
+    case AssetClass.Option: return options
+    case AssetClass.Fx: return fx
+    case AssetClass.Bond: return bonds
+    case AssetClass.Spread: return spreads
+    default: return equities
+  }
+}
+
+const all: readonly IInstrumentSpec[] = [
+  ...equities, ...futures, ...options, ...fx, ...bonds, ...spreads
+]
+
+export const InstrumentUniverse = {
+  equities,
+  futures,
+  options,
+  fx,
+  bonds,
+  spreads,
+  all,
+  byClass,
+
+  byName (name: string): IInstrumentSpec | undefined {
+    const lower = name.toLowerCase()
+    return all.find(i =>
+      i.symbol.toLowerCase() === lower ||
+      i.securityId.toLowerCase() === lower ||
+      i.name.toLowerCase() === lower)
+  },
+
+  choose (rng: Rng, assetClass?: AssetClass): IInstrumentSpec {
+    return rng.pick(assetClass ? byClass(assetClass) : all)
+  }
+}