@slugbugblue/trax 1.1.1 → 1.2.0

package/RELEASE.v1.2.0.md

@@ -0,0 +1,10 @@
+## 1.2.0 - 2026-06-25
+
+- Implement an initial benchmarking record
+- Swap the notation / moves storage (store moves, calculate notation)
+- Maintain the tile count and possible locations candidate set incrementally
+- Combined speedup of about 30% on new games and per-move play
+- Around 35% for `possibleMoves` on large boards vs 1.1.1
+- Update docs to reflect changes
+- Update dependencies
+

package/benchmark/benchmarks.json

@@ -0,0 +1,25 @@
+{
+  "1.1.1": {
+    "tutorial.01": {
+      "construction": { "count": 5000, "ms": 0.0843 },
+      "save+restore": { "count": 1000, "ms": 0.0058 },
+      "possibleMoves": { "count": 1000, "ms": 0.7045 },
+      "play": { "count": 1000, "ms": 0.1158 },
+      "normalized": { "count": 5000, "ms": 0.0092 }
+    },
+    "book.20": {
+      "construction": { "count": 5000, "ms": 0.2955 },
+      "save+restore": { "count": 1000, "ms": 0.0131 },
+      "possibleMoves": { "count": 1000, "ms": 2.3677 },
+      "play": { "count": 1000, "ms": 0.2953 },
+      "normalized": { "count": 5000, "ms": 0.0433 }
+    },
+    "book.30": {
+      "construction": { "count": 5000, "ms": 1.3156 },
+      "save+restore": { "count": 1000, "ms": 0.0486 },
+      "possibleMoves": { "count": 1000, "ms": 6.785 },
+      "play": { "count": 1000, "ms": 1.3788 },
+      "normalized": { "count": 5000, "ms": 0.1611 }
+    }
+  }
+}

package/benchmark/engine.bench.js

@@ -0,0 +1,228 @@
+import { readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { version } from '../src/version.js'
+import { Trax } from '../src/engine.js'
+
+/** @import { TraxVariant } from '../src/engine.js' */
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const RESULTS_PATH = path.join(__dirname, 'benchmarks.json')
+
+/** @type {{ id: string, game: TraxVariant, notation: string, gatesRegressions: boolean }[]} */
+const POSITIONS = [
+  {
+    id: 'tutorial.01',
+    game: 'trax',
+    notation: '@0/ @1\\',
+    gatesRegressions: false,
+  },
+  {
+    id: 'book.20',
+    game: 'traxloop',
+    notation: '@0/ @1/ B0+ B0/ C3+ D3+ E3\\',
+    gatesRegressions: false,
+  },
+  {
+    id: 'book.30',
+    game: 'traxloop',
+    notation:
+      '@0/ @1/ @1/ D1+ A2+ E1+ E2+ E0+ F1\\ G1+ G2\\ F3+ E4\\ G3+ H2\\ C5\\ D5+ D6\\ D7\\',
+    gatesRegressions: true,
+  },
+]
+
+const ESC = String.fromCodePoint(27)
+const GREEN = `${ESC}[38;5;35m`
+const BLUE = `${ESC}[38;5;39m`
+const ORANGE = `${ESC}[38;5;208m`
+const RED = `${ESC}[38;5;196m`
+const GRAY = `${ESC}[38;5;240m`
+const RESET = `${ESC}[0m`
+
+/**
+Wrap a string with an ANSI color escape sequence.
+@param {string} string_ - the string to colorize
+@param {string} ansi - the ANSI escape code to apply
+@returns {string} the colorized string
+*/
+const colorize = (string_, ansi) => `${ansi}${string_}${RESET}`
+
+/**
+Pick an ANSI color for a benchmark regression percentage.
+@param {number} pct - the percentage change, positive means slower
+@returns {string} an ANSI escape code for the appropriate color
+*/
+function diffColor(pct) {
+  if (pct > 20) return RED
+  if (pct > 5) return ORANGE
+  if (pct < -20) return GREEN
+  if (pct < -5) return BLUE
+  return GRAY
+}
+
+/**
+Run a function repeatedly and return timing results.
+@param {() => unknown} fn - the function to benchmark
+@param {number} iterations - how many times to run fn
+@returns {{ count: number, ms: number }} average time per iteration
+*/
+function bench(fn, iterations) {
+  const start = performance.now()
+  for (let i = 0; i < iterations; i++) fn()
+  const ms = (performance.now() - start) / iterations
+  return { count: iterations, ms }
+}
+
+/** @typedef {{ name: string, current: string, prior: string, diff: string, percent: string, color: string, isRegression: boolean }} MetricRow */
+
+/**
+Benchmark a single game position across all metrics.
+@param {TraxVariant} game - the game variant to use
+@param {string} notation - the move sequence to set up the position
+@param {Record<string, { count: number, ms: number }> | undefined} baseline - prior results to compare against
+@returns {{ results: Record<string, { count: number, ms: number }>, rows: MetricRow[] }} timing results and formatted comparison rows
+*/
+function benchPosition(game, notation, baseline) {
+  const instance = new Trax(game, notation)
+  const { moves } = instance
+  const lastMove = moves.at(-1)
+
+  const construction = bench(() => new Trax(game, notation), 5000)
+  const saveRestore = bench(() => {
+    const saved = instance.save()
+    instance.restore(saved)
+  }, 1000)
+  const possibleMovesResult = bench(() => instance.possibleMoves(), 1000)
+  const play = bench(() => {
+    const g = new Trax(game, notation)
+    g.play(/** @type {string} */ (lastMove))
+  }, 1000)
+  const normalized = bench(() => instance.normalized, 5000)
+
+  /** @type {Record<string, { count: number, ms: number }>} */
+  const results = {
+    construction,
+    'save+restore': saveRestore,
+    possibleMoves: possibleMovesResult,
+    play,
+    normalized,
+  }
+
+  /** @type {MetricRow[]} */
+  const rows = []
+  for (const [name, { ms }] of Object.entries(results)) {
+    const prior = baseline?.[name]
+    const current = `${ms.toFixed(4)} ms`
+    if (prior) {
+      const delta = ms - prior.ms
+      const pct = (delta / prior.ms) * 100
+      const sign = delta >= 0 ? '+' : ''
+      rows.push({
+        name,
+        current,
+        prior: `${prior.ms.toFixed(4)} ms`,
+        diff: `${sign}${delta.toFixed(4)} ms`,
+        percent: `${sign}${pct.toFixed(1)}%`,
+        color: diffColor(pct),
+        isRegression: pct > 20,
+      })
+    } else {
+      rows.push({
+        name,
+        current,
+        prior: '',
+        diff: '',
+        percent: '',
+        color: GRAY,
+        isRegression: false,
+      })
+    }
+  }
+
+  return { results, rows }
+}
+
+/**
+Load prior benchmark results from disk.
+@returns {Record<string, Record<string, Record<string, { count: number, ms: number }>>>} all saved results keyed by version
+*/
+function loadResults() {
+  try {
+    return JSON.parse(readFileSync(RESULTS_PATH, 'utf8'))
+  } catch {
+    return {}
+  }
+}
+
+/**
+Print benchmark results to the console.
+@param {MetricRow[][]} allRows - one array of rows per position
+*/
+function printResults(allRows) {
+  const flat = allRows.flat()
+  const hasComparison = flat.some((r) => r.prior !== '')
+  const nameWidth = Math.max(...flat.map((r) => r.name.length))
+  const currentWidth = Math.max(...flat.map((r) => r.current.length))
+  const priorWidth = Math.max(...flat.map((r) => r.prior.length))
+  const diffWidth = Math.max(...flat.map((r) => r.diff.length))
+  const pctWidth = Math.max(...flat.map((r) => r.percent.length))
+
+  for (const [index, position] of POSITIONS.entries()) {
+    console.log(`\n  ${position.id}`)
+    for (const row of allRows[index]) {
+      const name = row.name.padEnd(nameWidth)
+      const current = row.current.padStart(currentWidth)
+      if (hasComparison && row.prior) {
+        const prior = `was ${row.prior.padStart(priorWidth)}`
+        const diff = colorize(row.diff.padStart(diffWidth), row.color)
+        const pct = colorize(row.percent.padStart(pctWidth), row.color)
+        console.log(`    ${name}  ${current}  (${prior},  ${diff},  ${pct})`)
+      } else {
+        console.log(`    ${name}  ${current}`)
+      }
+    }
+  }
+}
+
+console.log(`\n@slugbugblue/trax benchmark v${version}`)
+console.log('='.repeat(50))
+
+const allResults = loadResults()
+const baseline = allResults[version]
+/** @type {Record<string, Record<string, { count: number, ms: number }>>} */
+const versionResults = {}
+/** @type {MetricRow[][]} */
+const allRows = []
+const allRegressions = []
+
+for (const { id, game, notation, gatesRegressions } of POSITIONS) {
+  const { results, rows } = benchPosition(game, notation, baseline?.[id])
+  versionResults[id] = results
+  allRows.push(rows)
+  if (gatesRegressions) {
+    allRegressions.push(
+      ...rows
+        .filter((r) => r.isRegression)
+        .map(
+          (r) =>
+            `    ${id}/${r.name}: ${r.prior} → ${r.current} (${r.percent})`,
+        ),
+    )
+  }
+}
+
+printResults(allRows)
+console.log('')
+
+if (!baseline) {
+  allResults[version] = versionResults
+  writeFileSync(RESULTS_PATH, JSON.stringify(allResults, null, 2) + '\n')
+  console.log('Results written to benchmark/benchmarks.json')
+}
+
+if (allRegressions.length > 0) {
+  console.log('\nRegressions detected:')
+  for (const message of allRegressions) console.log(message)
+  throw new Error('Benchmark regressions detected')
+}

package/gl-sast-report.json

@@ -1 +1 @@
-{"version":"15.2.2","vulnerabilities":[],"scan":{"analyzer":{"id":"semgrep","name":"Semgrep","url":"https://gitlab.com/gitlab-org/security-products/analyzers/semgrep","vendor":{"name":"GitLab"},"version":"6.15.1"},"scanner":{"id":"semgrep","name":"Semgrep","url":"https://github.com/returntocorp/semgrep","vendor":{"name":"GitLab"},"version":"1.145.0"},"type":"sast","start_time":"2026-02-28T20:29:59","end_time":"2026-02-28T20:30:11","status":"success","observability":{"events":[{"event":"collect_sast_scan_metrics_from_pipeline","property":"54b1ad92-5d39-416b-9075-916f3da22681","label":"semgrep","value":0,"version":"6.15.1","exit_code":0,"override_count":0,"passthrough_count":0,"custom_exclude_path_count":0,"time_s":12,"file_count":7}]}}}
+{"version":"15.2.2","vulnerabilities":[],"scan":{"analyzer":{"id":"semgrep","name":"Semgrep","url":"https://gitlab.com/gitlab-org/security-products/analyzers/semgrep","vendor":{"name":"GitLab"},"version":"6.18.1"},"scanner":{"id":"semgrep","name":"Semgrep","url":"https://github.com/returntocorp/semgrep","vendor":{"name":"GitLab"},"version":"1.145.0"},"type":"sast","start_time":"2026-06-26T00:29:40","end_time":"2026-06-26T00:29:52","status":"success","observability":{"events":[{"event":"collect_sast_scan_metrics_from_pipeline","property":"c0b9149f-1c82-4346-9e3c-34727b5f04e6","label":"semgrep","value":0,"version":"6.18.1","exit_code":0,"override_count":0,"passthrough_count":0,"custom_exclude_path_count":0,"time_s":12,"file_count":8}]}}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slugbugblue/trax",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Trax game engine",
   "keywords": [
     "trax",
@@ -26,8 +26,9 @@
     "url": "git+https://gitlab.com/slugbugblue/trax.git"
   },
   "scripts": {
+    "benchmark": "node benchmark/engine.bench.js",
     "genversion": "genversion --esm src/version.js",
-    "git-add": "git add src/version.js src/engine.d.ts",
+    "git-add": "git add src/version.js src/engine.d.ts benchmark/benchmarks.json",
     "ts-build": "tsc -p tsconfig.build.json && rm -f src/version.d.ts",
     "test": "xo && c8 ava",
     "prepare": "[ -n \"$CI\" ] || husky",
@@ -40,12 +41,12 @@
     "@slugbugblue/point": "^1.0.0"
   },
   "devDependencies": {
-    "ava": "^7.0.0",
+    "ava": "^8.0.1",
     "c8": "^11.0.0",
     "genversion": "^3.0.2",
     "husky": "^9.1.7",
     "prettier": "^3.6.2",
-    "xo": "^1.2.3"
+    "xo": "^3.0.2"
   },
   "type": "module",
   "engines": {