@slugbugblue/trax 0.17.0 → 0.19.0

package/.husky/pre-commit

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+npm test

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @slugbugblue/trax
 
+## 0.19.0 - 2023-02-06
+
+- Added a simple LRU cache to increase the efficiency of the analysis engine
+
+## 0.18.0 - 2023-02-05
+
+- Analysis improvements:
+
+  - Add `count.b(level)` and `count.w(level)` methods to an analysis to quickly
+    count the number of threats at a given level
+  - Remove faulty threats from an analysis
+  - Add additional threats for more puzzle solving mojo
+
+- Development environment enhancements:
+
+  - Added an initial benchmarking framework with puzzle benchmarks so far
+  - Added husky pre-commit hook to ensure npm test is run before a commit
+
+- CLI improvements:
+
+  - Puzzle information is now stored as notes, to make it searchable
+
+- More puzzles:
+
+  - Martin M. S. Pedersen contributed eleven new puzzles
+
 ## 0.17.0 - 2022-12-29
 
 - The `import` CLI command now loads comments from a .trx file
@@ -26,9 +52,9 @@
   - Adjust puzzle category levels for harder puzzles
   - Add multiple hints when the puzzle can be solved multiple ways
 
-- Analysis engine improvements:
+- Analysis improvements:
 
-  - Analysis engine suggestions now "solve" all tough puzzles
+  - Analysis suggestions now "solve" all tough puzzles
   - Reworked threats to be more precise
   - Reworked scoring to add more nuance
 
@@ -39,9 +65,9 @@
   - `trax puzzles ls`: see all the puzzles
   - `trax puzzle new`: start a new puzzle
 
-- Analysis engine tests now include correctly suggesting the first move for
-  solving all tutorial and easy puzzles. As the threats database improves, we
-  will add more puzzles to the tests.
+- Analysis tests now include correctly suggesting the first move for solving all
+  tutorial and easy puzzles. As the threats database improves, we will add more
+  puzzles to the tests.
 
 ## 0.13.0 - 2022-11-25
 
@@ -134,7 +160,7 @@ variables from snake_case to camelCase.
   - `to`: the normalized position code of the board after the move
   - `via`: the move notation to go from `from` to `to`
 
-### 0.3.1 - 2022-01-07
+## 0.3.1 - 2022-01-07
 
 - Make a faster implementation of `trax.possible_locations()`
 - Display updates for tentative moves

package/Dockerfile

@@ -0,0 +1,9 @@
+# Use the latest nodejs long-term-support release,
+# on the latest Alpine Linux for its small footprint
+FROM node:lts-alpine
+# Install current source code globally
+COPY . /src
+WORKDIR /src
+RUN npm install -g @slugbugblue/trax
+# Use the trax CLI as the starting point
+ENTRYPOINT ["/usr/local/bin/trax"]

package/README.md

@@ -4,7 +4,7 @@ This project aims to provide tools for working with Trax games in Javascript.
 
 - Trax game-playing engine
 - Position analysis engine
-- Over 50 puzzles to help hone your Trax skills
+- Over 60 puzzles to help hone your Trax skills
 - Command-line interface for ease of use
 
 ## Description
@@ -153,9 +153,10 @@ threats.
 
 ### Puzzles database
 
-The puzzles database is provided in `puzzles.js`, and so far just contains
-puzzles that I've been using to test the analysis engine, along with the list of
-publicly available puzzles at [the traxgame.com puzzles page][traxpuzzles].
+The puzzles database is provided in `puzzles.js`, and contains puzzles that I've
+been using to test the analysis engine, publicly available puzzles from [the
+traxgame.com puzzles page][traxpuzzles], and [puzzles curated][puzzlebook] by
+[Martin M. S. Pedersen][traxplayer].
 
 ## Roadmap
 
@@ -187,9 +188,14 @@ always ready to share his insights on the mechanics of the game, as well as
 various approaches to encoding its complexities. His undeserved kindness and
 infinite patience in indulging my many questions can never be repaid.
 
+Thanks for [Martin M. S. Pedersen][traxplayer] for contributing ideas, code, and
+puzzles to this effort. He's been [curating Trax puzzles][puzzlebook] and
+[coding solutions for Trax][gnutrax] for over two decades, and brings a lot of
+expertise.
+
 ## License
 
-Copyright 2019-2022 Chad Transtrum
+Copyright 2019-2023 Chad Transtrum
 
 Licensed under the Apache License, Version 2.0 (the "License"); you may not use
 the files in this project except in compliance with the License. You may obtain
@@ -217,12 +223,15 @@ David Smith and heirs, and are not to be used without permission.
 [docs-engine]: docs/engine.md
 [docs-analyst]: docs/analyst.md
 [env-path]: https://www.npmjs.com/package/env-paths
+[gnutrax]: https://gnutrax.com
 [goldtoken]: https://goldtoken.com/
+[puzzlebook]: https://gnutrax.com/book
 [repo]: https://gitlab.com/slugbugblue/trax
 [sbb]: https://slugbugblue.com/
 [traxbook]: http://traxgame.com/shop_book.php
 [traxgame]: http://traxgame.com/
 [traxhistory]: http://www.traxgame.com/about_history.php
+[traxplayer]: mailto:traxplayer@gmail.com
 [traxpuzzles]: http://www.traxgame.com/games_puzzles.php
 [traxrules]: http://www.traxgame.com/about_rules.php
 [xdg]:

package/benchmark/benchmarks.json

@@ -0,0 +1,60 @@
+{
+  "0.17.0": {
+    "puzzles.firstmove.tutorial": {
+      "count": 16,
+      "ms": 2007
+    },
+    "puzzles.firstmove.beginner": {
+      "count": 16,
+      "ms": 2664
+    },
+    "puzzles.firstmove.tough": {
+      "count": 1,
+      "ms": 76
+    },
+    "puzzles.firstmove.total": {
+      "count": 33,
+      "ms": 4838
+    }
+  },
+  "0.18.0": {
+    "puzzles.firstmove.tutorial": {
+      "count": 16,
+      "ms": 10164
+    },
+    "puzzles.firstmove.beginner": {
+      "count": 15,
+      "ms": 17864
+    },
+    "puzzles.firstmove.tough": {
+      "count": 26,
+      "ms": 30349
+    },
+    "puzzles.firstmove.advanced": {
+      "count": 1,
+      "ms": 427
+    },
+    "puzzles.firstmove.total": {
+      "count": 58,
+      "ms": 59031
+    }
+  },
+  "0.19.0": {
+    "puzzles.firstmove.tutorial": {
+      "count": 16,
+      "ms": 9753
+    },
+    "puzzles.firstmove.beginner": {
+      "count": 15,
+      "ms": 17376
+    },
+    "puzzles.firstmove.tough": {
+      "count": 25,
+      "ms": 26380
+    },
+    "puzzles.firstmove.total": {
+      "count": 56,
+      "ms": 55167
+    }
+  }
+}

package/benchmark/puzzles.bench.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+
+/** Let's try to solve the puzzles
+ * @copyright 2023
+ * @author Chad Transtrum <chad@transtrum.net>
+ * @license Apache-2.0
+ */
+
+import fs from 'node:fs'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+
+import { Trax } from '@slugbugblue/trax'
+import { suggest } from '@slugbugblue/trax/analyst'
+import { puzzles } from '@slugbugblue/trax/puzzles'
+import { version } from '@slugbugblue/trax/version'
+
+import * as tty from '@slugbugblue/trax/tty'
+
+let STUMPED = false
+const FINAL = {}
+
+const record = (name, data) => {
+  FINAL['puzzles.firstmove.' + name] = data
+}
+
+const timeString = (ms) => {
+  if (ms < 1000) {
+    return (ms === Math.floor(ms) ? String(ms) : ms.toFixed(2)) + ' ms'
+  }
+
+  ms /= 1000
+  if (ms < 60) return ms.toFixed(3) + ' sec'
+
+  const min = Math.floor(ms / 60)
+  ms -= min * 60
+  return String(min) + ' min ' + ms.toFixed(3) + ' sec'
+}
+
+const time = (ms) => timeString(Date.now() - ms)
+
+const out = (messages) => {
+  tty.outty(messages.join(' '))
+}
+
+const section = (title) => {
+  out([tty.color('===', 250), tty.color(title, 39), tty.color('===', 250)])
+}
+
+const success = (puzzle, ms) => {
+  out([tty.color('✓', 35), tty.color(puzzle, 250), tty.color(ms, 240)])
+}
+
+const puzzled = (puzzle, move) => {
+  tty.display(new Trax(puzzle.game, puzzle.notation))
+  tty.outty('Puzzled by ' + puzzle.id, 205)
+  out([
+    tty.color('  played', 250),
+    tty.color(move, 127),
+    tty.color('instead of', 250),
+    tty.color(puzzle.hint || puzzle.hints.join(' '), 39),
+  ])
+  STUMPED = true
+}
+
+const finalize = (name, ms, count) => {
+  out([
+    tty.color('Finished', 195),
+    tty.color(String(count) + ' ' + name + ' puzzles', 123),
+    tty.color('in ' + time(ms), 195),
+  ])
+}
+
+const solvePuzzleLevel = (name, level) => {
+  if (STUMPED) return 0
+  section(name + ' puzzles')
+  name = name.toLowerCase()
+  let count = 0
+  const begin = Date.now()
+  for (const puzzle of puzzles) {
+    if (puzzle.level !== level) continue
+    const start = Date.now()
+    const game = new Trax(puzzle.game, puzzle.notation)
+    const { move } = suggest(game).pick
+    const solved = puzzle.hint
+      ? move === puzzle.hint
+      : puzzle.hints
+      ? puzzle.hints.includes(move)
+      : false
+    if (solved) {
+      success(puzzle.id, time(start))
+      count++
+      record(name, { count, ms: Date.now() - begin })
+    } else {
+      puzzled(puzzle, move)
+      process.exitCode = level + 1
+      return count
+    }
+  }
+
+  finalize(name, begin, count)
+  return count
+}
+
+// Gather the benchmark data
+let total = 0
+const timer = Date.now()
+total += solvePuzzleLevel('Tutorial', 0)
+total += solvePuzzleLevel('Beginner', 1)
+total += solvePuzzleLevel('Tough', 2)
+total += solvePuzzleLevel('Advanced', 3)
+total += solvePuzzleLevel('Genius', 4)
+
+record('total', { count: total, ms: Date.now() - timer })
+tty.outty(
+  'Benchmark: ' + total + ' puzzles in ' + time(timer),
+  STUMPED ? 205 : 35,
+)
+
+tty.outty()
+
+// Load the previous benchmarks
+const FILE = new URL('benchmarks.json', import.meta.url)
+let CONTENTS
+try {
+  CONTENTS = fs.readFileSync(FILE, 'utf8')
+} catch {
+  CONTENTS = '{}'
+}
+
+const BENCHMARK = JSON.parse(CONTENTS)
+
+const PREV = Object.values(BENCHMARK).pop() || {}
+
+// Report the benchmark data
+const size = [0, 0, 0, 0, 0]
+const REPORT = []
+for (const name of Object.keys(FINAL)) {
+  const report = [
+    name,
+    String(FINAL[name].count) + ' puzzles',
+    'in ' + timeString(FINAL[name].ms),
+    'avg ' + timeString(FINAL[name].ms / FINAL[name].count),
+  ]
+  if (PREV[name]) {
+    const diff =
+      FINAL[name].ms / FINAL[name].count - PREV[name].ms / PREV[name].count
+    if (diff <= 0) {
+      report.push('-' + timeString(Math.abs(diff)), '35')
+    } else {
+      report.push('+' + timeString(diff), '208')
+    }
+  } else {
+    report.push('new', '250')
+  }
+
+  size[0] = Math.max(size[0], report[0].length)
+  size[1] = Math.max(size[1], report[1].length)
+  size[2] = Math.max(size[2], report[2].length)
+  size[3] = Math.max(size[3], report[3].length)
+  size[4] = Math.max(size[4], report[4].length)
+  REPORT.push(report)
+}
+
+for (const line of REPORT) {
+  out([
+    tty.color(line[0].padEnd(size[0]), 39),
+    tty.color(line[1].padStart(size[1]), 123),
+    tty.color(line[2].padStart(size[2]), 195),
+    tty.color(line[3].padEnd(size[3]), 245),
+    tty.color(line[4].padStart(size[4]), Number(line[5])),
+  ])
+}
+
+tty.outty()
+
+// Save the benchmark data to a file
+if (BENCHMARK[version]) {
+  tty.outty('Not overwriting existing benchmark data')
+} else {
+  BENCHMARK[version] = FINAL
+  try {
+    fs.writeFileSync(FILE, JSON.stringify(BENCHMARK, null, 2), 'utf8')
+    const filename = fileURLToPath(FILE)
+    tty.outty('Saved benchmark data to ' + tty.color(filename, 74))
+  } catch (error) {
+    tty.outty('Error saving benchmark data', 205)
+    tty.outty(String(error.code) + ' ' + error.message, 127)
+  }
+}

package/docs/analyst.md

@@ -79,6 +79,7 @@ themselves. The following keys are present in each edge space representation:
   connectable pair of lines with this color.
 - `zb` and `zw`: The character used in the black or white string representation
   of this space.
+- `idx`: The index of this edge space in the edge array.
 
 For the edge string, the following characters are used as a hopefully useful
 shorthand summary of the tiles surrounding the space. To make regex pattern
@@ -90,7 +91,7 @@ so that it appears as though all black tiles are white tiles.
 - `l`: both a black and a white line enter this space.
 - `a`: a white line enters this space, and the next white line in the edge is
   the other end of this line.
-- 'c': a white line enters this space, and the next white line in the edge forms
+- `c`: a white line enters this space, and the next white line in the edge forms
   a connectable pair with this line.
 - `m`: both a black and a white line enter this space, and the next white line
   in the edge is the other end of the white line.
@@ -119,6 +120,11 @@ following keys:
   may or may not be exactly the same as the pattern.
 - `at`: The index of the edge string at which the pattern match began.
 
+##### `faulty`
+
+Contains the same information as `threats` but for removed threats that were
+found to be faulty.
+
 ##### `score`
 
 Computes a rough "score" of the current position using the list of threats. A
@@ -135,6 +141,14 @@ because the scores can change depending on who has the initiative.
 
 #### methods
 
+##### `count.w(level)`
+
+Returns the number of threats for white at the given level.
+
+##### `count.b(level)`
+
+Returns the number of threats for black at the given level.
+
 ##### `inCave(loc)`
 
 For any given location, returns true if that location is found within a cave.
@@ -188,7 +202,7 @@ suggestion.
 
 ## License
 
-Copyright 2019-2022 Chad Transtrum
+Copyright 2022-2023 Chad Transtrum
 
 Licensed under the Apache License, Version 2.0 (the "License"); you may not use
 the files in this project except in compliance with the License. You may obtain

package/docs/engine.md

@@ -42,7 +42,7 @@ class properties and methods:
 - `Trax.point(x, y)`: quick access to the [Point class][point-docs], for
   two-dimensional locations used internally by the Trax engine and which are
   required for some of the lower-level engine functions. Operates as a
-  constructor (without `new`) and returns a Point instance.
+  constructor (without `new`) and returns a [Point instance][point-docs].
 
 - `Trax.colorOf(playerNumber)`: Player 1 is white and Player 2 is black. So this
   is a quick function to turn `1` into `'w'` and `2` into `'b'`. Quick and
@@ -414,7 +414,7 @@ tie.
 
 ## License
 
-Copyright 2019-2022 Chad Transtrum
+Copyright 2019-2023 Chad Transtrum
 
 Licensed under the Apache License, Version 2.0 (the "License"); you may not use
 the files in this project except in compliance with the License. You may obtain

package/docs/lru.md

@@ -0,0 +1,151 @@
+# lru.js API documentation
+
+This module provides a simple Least Recently Used cache.
+
+Internally, this uses a Map, which give us insertion-ordering for free. The
+first item in the list is the oldest. The last item is the most recently set or
+accessed. Most of the base functionality of the Map are replicated.
+
+Since I don't need it to be super fancy, there isn't a lot of extra
+functionality here.
+
+## Example usage
+
+```javascript
+import { LRU } from '@slugbugblue/trax/lru.js'
+
+const cache = new LRU(100)
+
+cache.set('a', 1)
+cache.set('b', 2)
+
+// Get an item from the cache
+console.log(cache.get('a')) // 1
+
+// Accessing a key makes it the most recent:
+console.log(cache.keys()) // [Map Iterator] { 'b', 'a' }
+console.log(cache.hits) // 1
+
+console.log(cache.get('z')) // undefined
+console.log(cache.misses) // 1
+
+console.log(cache.size) // 2
+console.log(cache.capacity) // 100
+```
+
+## API
+
+### LRU class
+
+An LRU cache is a way to remember a limited set of items, with the oldest
+expiring when the capacity is reached.
+
+#### constructor
+
+##### `new LRU(capacity)`
+
+Create the cache by specifying the maximum number of items it should hold.
+
+#### computed properties
+
+##### `capacity`
+
+The maximum number of items the cache can hold. This cannot be changed after the
+cache creation.
+
+##### `size`
+
+The number of items currently stored in the cache.
+
+##### `hits`
+
+The number of times a `get` call has found an item in the cache.
+
+##### `misses`
+
+The number of times a `get` call has not found an item in the cache.
+
+##### `expired`
+
+The number of times an item has been removed from the cache.
+
+#### methods
+
+##### `get(key)`
+
+Retrieve an item from the cache. If the item is found in the cache, `hits` will
+be updated, the item will be marked as the most-recently-used item, and the
+value will be returned. If the item is not present in the cache, `misses` will
+be updated, and `undefined` will be returned.
+
+Note that if you had stored `undefined` as the value in the cache, the return of
+`undefined` doesn't necessarily represent a cache miss.
+
+##### `peek(key)`
+
+Retrieve an item from the cache, if present, but without updating any of the
+LRU-specific information about the retrieval attempt. The item's age will not be
+updated. If the item is not present in the cache, `undefined` will be returned.
+
+##### `set(key, value)`
+
+Store an item in the cache. If the item is already present in the cache, it will
+be replaced and marked as the most-recently-used item.
+
+##### `delete(key)`
+
+Remove an item from the cache.
+
+##### `clear()`
+
+Clears all items and statistics from the cache. The maximum capacity will not
+change.
+
+##### `entries()`
+
+Returns an iterator that operates over all the \[key, value\] pairs stored in
+the cache. The entries will be in order from oldest to newest.
+
+##### `has(key)`
+
+Returns true if a key is found in the cache, false otherwise.
+
+##### `keys()`
+
+Returns an iterator that operates over all the keys stored in the cache. The
+keys will be returned oldest first, newest last.
+
+##### `values()`
+
+Returns an iterator that operates over all the values stored in the cache. The
+values will be returned oldest first, newest last.
+
+#### Plays well with others
+
+The LRU class also includes functionality to provide useful default results when
+used in other contexts.
+
+##### `toString()`
+
+Returns a string representation of the cache in the format `LRU(75 of 1000)`.
+This allows simple logging calls with `console.log(cache)`.
+
+##### `util.inspect.custom()`
+
+When running in the node command line interpreter, an LRU cache instance will be
+pretty-printed using the magic of `util.inspect`.
+
+## License
+
+Copyright 2023 Chad Transtrum
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+the files in this project except in compliance with the License. You may obtain
+a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slugbugblue/trax",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Trax game engine and friends",
   "keywords": [
     "trax",
@@ -14,8 +14,9 @@
   "types": "./src/types.d.ts",
   "exports": {
     ".": "./src/engine.js",
-    "./point": "./src/point.js",
     "./analyst": "./src/analyst.js",
+    "./lru": "./src/lru.js",
+    "./point": "./src/point.js",
     "./puzzles": "./src/puzzles.js",
     "./threats": "./src/threats.js",
     "./tty": "./src/tty.js",
@@ -26,9 +27,11 @@
     "trax": "./src/cli.js"
   },
   "scripts": {
+    "benchmark": "node benchmark/puzzles.bench.js",
     "test": "xo && c8 ava",
+    "prepare": "husky install",
     "preversion": "npm test",
-    "version": "genversion --es6 src/version.js && git add src/version.js",
+    "version": "genversion --es6 src/version.js && npm run benchmark || git add src/version.js benchmark/benchmarks.json",
     "postversion": "git push && git push --tags && npm publish"
   },
   "dependencies": {
@@ -40,6 +43,7 @@
     "ava": "^5.1.0",
     "c8": "^7.11.0",
     "genversion": "^3.0.2",
+    "husky": "^8.0.3",
     "prettier": "^2.6.1",
     "xo": "0.*"
   },