@slugbugblue/trax 0.22.0 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @slugbugblue/trax
 
+## 1.0.0 - 2025-11-04
+
+v1 release:
+
+- Update dev dependencies to latest versions
+- Fix xo complaints
+- No other code changes
+
+## 0.23.0 - 2023-03-28
+
+Release candidate
+
+Finalize work with jsdoc/typescript
+
 ## 0.22.0 - 2023-03-25
 
 - Pull point.js into its own package: `@slugbugblue/point`
@@ -12,7 +26,6 @@
 ## 0.21.0 - 2023-03-12
 
 - Update the analysis engine to be more lazy
-
   - The LRU cache is more likely to have a hit because it no longer separates
     validated from unvalidated analyses
   - Suggestions are much faster because it now skips validations for low-scoring
@@ -28,7 +41,7 @@
 - Drop support for node 14; node v16.15 is our minimum supported version
 - More puzzles from Martin M. S. Pedersen -- bringing the total to 100+
 - Enhance the docker configuration and document it in the README
-- Refine faulty threat detection and add test for once case it was failing
+- Refine faulty threat detection and add test for one case it was failing
 
 ## 0.19.0 - 2023-02-06
 
@@ -37,23 +50,19 @@
 ## 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
@@ -63,7 +72,6 @@
 ## 0.16.0 - 2022-12-27
 
 - Added a `notes` command to the CLI to add comments to a game
-
   - all comments are included in the output generated by the `export` command
   - the latest comment can be used as a text filter by the `list` command
   - the latest comment is displayed by the `view` and `list` commands
@@ -73,17 +81,14 @@
 ## 0.15.0 - 2022-12-14
 
 - Added shared `puzzles` commands to the CLI:
-
   - `trax ls puzzles`: see all the puzzles
   - `trax new puzzle`: start a new puzzle
 
 - Puzzle improvements:
-
   - Adjust puzzle category levels for harder puzzles
   - Add multiple hints when the puzzle can be solved multiple ways
 
 - Analysis improvements:
-
   - Analysis suggestions now "solve" all tough puzzles
   - Reworked threats to be more precise
   - Reworked scoring to add more nuance
@@ -91,7 +96,6 @@
 ## 0.14.0 - 2022-12-05
 
 - Added `puzzles` to the CLI:
-
   - `trax puzzles ls`: see all the puzzles
   - `trax puzzle new`: start a new puzzle
 
@@ -102,13 +106,11 @@
 ## 0.13.0 - 2022-11-25
 
 - Add move suggestions to `analyst.js` for CLI and bot use
-
   - use `suggest(trax)` to get a suggestion for the current position
   - added the `suggest` CLI command for quick access to a random suggestion
 
 - Use font glyphs for text bubbles in `tty.js` only if one of the following
   environment variables are defined and non-empty:
-
   - `NERDFONT`, `POWERLINE`, `P9K_TTY`, `P9K_SSH`
 
 - Begin work on documenting the javascript files using jsdoc, with the initial
@@ -125,7 +127,6 @@
   `play()`. `playMove()` is no longer available.
 - Add a new function `playMoves()` to submit multiple moves at once
 - Initial work on `analyst.js`, with documentation and a start on tests
-
   - use `analyze(trax)` to perform an analysis
   - added the `analyze` CLI command to see an analysis
 
@@ -185,7 +186,6 @@ variables from snake_case to camelCase.
 - The name and signature for provisional move handling, which was broken, has
   been changed. It is now called `provisional_moves()` and takes three
   arguments:
-
   - `from`: the normalized position code of the board before the move
   - `to`: the normalized position code of the board after the move
   - `via`: the move notation to go from `from` to `to`
@@ -221,7 +221,6 @@ More convenience:
 Initial release:
 
 - engine.js
-
   - create a new Trax game with `trax = new Trax()`
   - play one move at a time with `trax.play('@0/')`
   - ... etc

package/README.md

@@ -71,7 +71,7 @@ Trax][gnutrax] for over two decades, and has a lot of expertise in this area.
 
 ## License
 
-Copyright 2019-2023 Chad Transtrum
+Copyright 2019-2025 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slugbugblue/trax",
-  "version": "0.22.0",
+  "version": "1.0.0",
   "description": "Trax game engine",
   "keywords": [
     "trax",
@@ -19,10 +19,10 @@
   },
   "repository": "gitlab:slugbugblue/trax",
   "scripts": {
-    "genversion": "genversion --es6 src/version.js",
+    "genversion": "genversion --esm src/version.js",
     "git-add": "git add src/version.js",
     "test": "xo && c8 ava",
-    "prepare": "husky install",
+    "prepare": "husky",
     "preversion": "npm test",
     "version": "npm run genversion ; npm run git-add",
     "postversion": "git push && git push --tags && npm publish"
@@ -32,12 +32,12 @@
     "@slugbugblue/point": "^1.0.0"
   },
   "devDependencies": {
-    "ava": "^5.1.0",
-    "c8": "^7.11.0",
+    "ava": "^6.4.1",
+    "c8": "^10.1.3",
     "genversion": "^3.0.2",
-    "husky": "^8.0.3",
-    "prettier": "^2.6.1",
-    "xo": "0.*"
+    "husky": "^9.1.7",
+    "prettier": "^3.6.2",
+    "xo": "^1.2.3"
   },
   "type": "module",
   "engines": {
@@ -60,6 +60,7 @@
   },
   "xo": {
     "prettier": true,
+    "space": true,
     "rules": {
       "curly": [
         "error",

package/src/engine.js

@@ -1,20 +1,9 @@
-/* Copyright 2019-2022 Chad Transtrum
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file 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.
+/** Trax engine.
+ * @copyright 2019-2022
+ * @author Chad Transtrum <chad@transtrum.net>
+ * @license Apache-2.0
  */
 
-// Trax internals. Woot.
-
 import { Point } from '@slugbugblue/point'
 
 // Fun trax helper constants
@@ -36,7 +25,9 @@ const notationRegex = /^([@a-z]+)(\d+)([/\\+])$/i
  * */
 const tileTypes = ['a', 'b', 'c', 'd', 'e', 'f']
 
-/** Slashes are represented by / \ or +.
+/** Slashes indicate the direction the tile is placed. A forward slash or a
+ * backslash indicate the tile is a "curve" and the plus sign indicates the
+ * tile is a "straight".
  * @readonly
  * @type {Record<ValidTiles, Slash>}
  */
@@ -119,50 +110,42 @@ const addBlank = (code) => {
  * @returns {number} - the actual length of the row
  */
 const codeRowLength = (row) =>
-  row.replace(/\d/g, (n) => '.'.repeat(Number(n) + 1)).length
+  row.replaceAll(/\d/g, (n) => '.'.repeat(Number(n) + 1)).length
 
 // This is where the magic happens
 /** A digital representation of a Trax game. */
 export class Trax {
   // Static class properties
-
   /** @readonly @type {Record<TraxVariant, string>} */
   static names = {
     trax: 'Trax',
     traxloop: 'Loop Trax',
     trax8: '8x8 Trax',
   }
-
   /** @readonly */
   static variants = new Set(Object.keys(this.names)) // Known variants
-
   // Static class methods
-
   /** Create an x,y Point object with special functions.
    * @arg {number|PointLike} x - either the x value, or an object with x,y keys
    * @arg {number} [y] - if x is a number, y must be provided as well
    * @returns {Point} a new Point object
    */
   static point = (x, y) => new Point(x, y)
-
   /** Given a player number, get the color.
    * @arg {number} playerNumber - the player number, 1 or 2
    * @returns {Color} the color of that player, w or b
    */
-  static colorOf = (playerNumber) => ({ 1: 'w', 2: 'b' }[playerNumber])
-
+  static colorOf = (playerNumber) => ({ 1: 'w', 2: 'b' })[playerNumber]
   /** Given a color, get the player number.
    * @arg {string} color - the color, w or b
    * @returns {number} the player number, 1 or 2
    */
-  static playerNumber = (color) => ({ b: 2, w: 1 }[color])
-
+  static playerNumber = (color) => ({ b: 2, w: 1 })[color]
   /** Given a color, get the other color.
    * @arg {string} color - the color, w or b
    * @returns {Color} the other color, b or w
    */
-  static other = (color) => ({ b: 'w', w: 'b' }[color])
-
+  static other = (color) => ({ b: 'w', w: 'b' })[color]
   /** Encode a numeric column number into the Trax notation column letter.
    * @arg {number} col - the colum number, with 0 just to the left of the tiles
    * @returns {string} the encoded column letter
@@ -177,7 +160,6 @@ export class Trax {
 
     return n || '@'
   }
-
   /** Decode a Trax notation column letter back to a number.
    * @arg {string} col - the Trax column letter
    * @returns {number} the column number
@@ -197,10 +179,10 @@ export class Trax {
   // Trax class constructor
   /** Create a new Trax game
    * @arg {TraxVariant} [rules='trax'] - the variant to play
-   * @arg {string|string[]} [moves=[]] - the initial moves to pre-play
+   * @arg {string|string[]} [moves=''] - the initial moves to pre-play
    * @arg {string} [id='trax'] - an id used to differentiate tiles from multiple games
    */
-  constructor(rules = 'trax', moves = [], id = 'trax') {
+  constructor(rules = 'trax', moves = '', id = 'trax') {
     if (!Trax.variants.has(rules)) rules = 'trax'
     this.id = String(id)
     this.rules = rules
@@ -311,6 +293,7 @@ export class Trax {
    */
   addTile(type, loc) {
     const id = this.tileId(loc)
+    /** @type {Tile} */
     const tile = { type, loc, id, move: this.move, seq: this.count }
     if (type === 'x') {
       this.invalid = true // Invalid tile is being played
@@ -334,7 +317,7 @@ export class Trax {
   }
 
   /** Is this tile valid?
-   * @type {(type: string, loc: Point) => type is TileType}
+   * @type {(type: string, loc: Point) => type is ValidTiles}
    */
   validTile(type, loc) {
     if (this.count === 0 && loc.x === 0 && loc.y === 0) {
@@ -377,6 +360,10 @@ export class Trax {
     return this.right - this.left + 1
   }
 
+  /** Determine if a location is valid to play in.
+   * @arg {Point} loc - the location to check
+   * @returns {boolean}
+   */
   validLocation(loc) {
     if (this.over) return false
     if (this.tileAt(loc)) return false
@@ -398,26 +385,31 @@ export class Trax {
     return false
   }
 
+  /** Find all possible locations to play in. Note that these are not
+   * necessarily valid locations, just empty ones that border existing tiles.
+   */
   possibleLocations() {
     if (this.count === 0) return [zero]
     /** @type Record<TileId, Point> */
     const possibles = {}
 
     for (const tile of Object.values(this.tiles)) {
-      tile.loc.around.map((loc) => {
+      for (const loc of tile.loc.around) {
         const id = this.tileId(loc)
         if (!(id in this.tiles)) possibles[id] = loc
-        return loc
-      })
+      }
     }
 
-    // Get rid of all the real tiles and return all the maybes
     return Object.values(possibles)
   }
 
+  /** Find all possible moves as a list of notations,
+   * ie: ['@1+', '@1/', '@1\\', ...]
+   *
+   * Note that moves are not guaranteed to be valid.
+   */
   possibleMoves() {
-    // Returns a list of every currently possible move
-    // as notations, ie ['@1+', '@1/', '@1\\', ...]
+    /** @type {string[]} */
     const possibles = []
     if (this.over) return possibles // Shortcut if the game is over
     for (const loc of this.possibleLocations()) {
@@ -430,9 +422,14 @@ export class Trax {
     return possibles
   }
 
+  /** Called after a move was just played, to determine the forced moves.
+   * @arg {Point} loc - the location just played at
+   * @returns {Tile[]} a list of tiles that should be added as part of the move
+   */
   forcedMoves(loc) {
-    // We just played at loc, so return all forced moves
+    /** @type {Tile[]} */
     const forced = []
+    /** @type {Record<string, boolean>} */
     const invalids = {}
     let check = loc.around
     while (check.length > 0) {
@@ -455,16 +452,26 @@ export class Trax {
     return forced
   }
 
+  /** Determine the notation for a move. Note that this must be determined
+   * BEFORE the move is placed on the board.
+   * @arg {ValidTiles} type - the tile placed on the board
+   * @arg {Point} loc - the location the tile is placed
+   * @returns {string} the notation of the move
+   */
   notate(type, loc) {
-    // Notation depends on the position of the board BEFORE the move
     let notation = Trax.encodeCol(loc.x - this.left + 1)
     notation += String(loc.y - this.top + 1)
     notation += slash[type]
     return notation
   }
 
+  /** Turn a move notation into a tile type and location.
+   * @arg {string} notation - a notation for a single move to be played at
+   * the current board position
+   * @returns {RawMove} the tile type and location of the move
+   */
   decodeNotation(notation) {
-    // Return {type, loc} from a notation
+    /** @type {RawMove} */
     const bad = { type: 'x', loc: zero }
     const match = notation.match(notationRegex)
     if (match === null) return bad
@@ -477,6 +484,14 @@ export class Trax {
     return bad
   }
 
+  /** Follow a color from one location through one or more tiles to the other
+   * end of the color line.
+   * @arg {Color} color - the color to follow
+   * @arg {Point} loc - the location to start
+   * @arg {string} from - the edge of the tile to start from
+   * @returns {LineEnd} the ending location and a list of the tile ids the path
+   * takes to get there.
+   */
   follow(color, loc, from) {
     const path = []
     let id = this.tileId(loc)
@@ -504,7 +519,13 @@ export class Trax {
     return { loc, path }
   }
 
+  /** Given a tile and a color, follow the line for that color to each end.
+   * @arg {Color} color - the color of ends of interest
+   * @arg { Point} loc - the location of the tile of interest
+   * @returns {LineEnd[]} a list of two items, each one end of the line
+   */
   findEnds(color, loc) {
+    /** @type {LineEnd[]} */
     const ends = []
     const tile = this.tileAt(loc)
     if (upColor(tile) === color) ends.push(this.follow(color, loc, 'top'))
@@ -514,6 +535,11 @@ export class Trax {
     return ends
   }
 
+  /** Determine if a given line ends the game.
+   * @arg {Point} locA - one end of the line
+   * @arg {Point} locB - the other end of the line
+   * @returns {boolean} - true if this line wins the game
+   */
   lineWin(locA, locB) {
     if (this.rules === 'traxloop') return false
     if (this.width > 7 && locA.distX(locB) > this.width) return true
@@ -521,6 +547,9 @@ export class Trax {
     return false
   }
 
+  /** Determine if the game has ended.
+   * @arg {Tile[]} tiles - a list of the tiles placed during the last move.
+   */
   checkWin(tiles) {
     /** @type {Color|false} */
     let winner = false
@@ -529,13 +558,13 @@ export class Trax {
       if (winner) continue // Skip the second player if the first has won
       for (const tile of tiles) {
         if (winner) continue // Skip the remaining tiles once we find a win
-        const ends = this.findEnds(color, tile.loc)
-        if (ends[0].loc.eq(ends[1].loc)) {
+        const [end1, end2] = this.findEnds(color, tile.loc)
+        if (end1.loc.eq(end2.loc)) {
           winner = color // Loop win
-          this.path = ends[0].path // Both paths are essentially the same
-        } else if (this.lineWin(ends[0].loc, ends[1].loc)) {
+          this.path = end1.path // Both paths are essentially the same
+        } else if (this.lineWin(end1.loc, end2.loc)) {
           winner = color // Line win, paths need to be combined
-          this.path = [...ends[0].path.reverse(), ...ends[1].path.slice(1)]
+          this.path = [...end1.path.reverse(), ...end2.path.slice(1)]
         }
       }
     }
@@ -576,6 +605,11 @@ export class Trax {
     return this.dropTile(notation)
   }
 
+  /** Play one or more moves.
+   * @arg {string|string[]} moves - the list of moves, provided either as a
+   * space-separated string of notations, or as a list of notations. Move
+   * numbers are optional, but if provided will be checked for accuracy.
+   */
   playMoves(moves) {
     // Play one or more moves, from a string or a list of moves
     // If move numbers are included, ensure they are accurate
@@ -583,12 +617,12 @@ export class Trax {
       moves = moves.join(' ')
     }
 
-    moves = moves.replace(/\n/g, ' ').split(/\s+/)
+    moves = moves.replaceAll('\n', ' ').split(/\s+/)
 
     let moveNumber = 0
     for (const move of moves) {
       if (moveNumberRegex.test(move)) {
-        moveNumber = Number(move.replace(/\D/g, ''))
+        moveNumber = Number(move.replaceAll(/\D/g, ''))
       }
 
       if (notationRegex.test(move)) {
@@ -603,6 +637,9 @@ export class Trax {
     }
   }
 
+  /** Add the current move notation to the notation string
+   * @arg {string} notation - the notation of the current move
+   */
   updateNotation(notation) {
     this.move++
     let note = this.move + '. ' + notation
@@ -617,13 +654,13 @@ export class Trax {
   /** An array of the moves made in the game. */
   get moves() {
     return this.notation
-      .replace(/\n/g, ' ')
+      .replaceAll('\n', ' ')
       .split(' ')
       .filter((n) => Boolean(n) && !n.endsWith('.'))
   }
 
   /** Drop a tile onto the board. This is a lower level call. Use play() if possible instead.
-   * @arg {string|TileType} type - a special move, a tile type, or a notation
+   * @arg {string|ValidTiles} type - a special move, a tile type, or a notation
    * @arg {Point} [loc] - a location if type is a tile type
    * @arg {string|boolean} [tentative] - if truthy, the move will not be saved
    * @returns {TileDrop} an object representing the results of the drop
@@ -673,6 +710,11 @@ export class Trax {
     return { dropped, notation, valid }
   }
 
+  /** Symmetry helper. Rotates a move around the board in case we are trying to
+   * play a symmetrical rather than an exact move.
+   * @arg {string} move - the notation of the move to be rotated
+   * @returns {string[]} the four rotations of this move
+   */
   moveRotations(move) {
     // Symmetry helper, rotate a move around the board
     const match = move.match(notationRegex)
@@ -695,15 +737,24 @@ export class Trax {
     return [...moves]
   }
 
+  /** Play a provisional move if it is valid.
+   * @arg {string} from - the normalized encoding of the starting position
+   * @arg {string} to - the normalized encoding of the ending position
+   * @arg {string} via - the move to be used to transition
+   * @returns {false|string} if the provisional move is invalid: false; if the
+   * provisional move will never be valid for any future moves:
+   * 'delete-provisional'; if the provisional move is valid, the correct
+   * notation, which may be symmetrically adjusted as needed
+   */
   provisionalMove(from, to, via) {
     // Test a provisional move against the current state
-    let rows = from.slice(1).split(':')
+    const lines = from.slice(1).split(':')
     let cols = 0
-    for (const row of rows) {
-      cols = Math.max(cols, codeRowLength(row))
+    for (const line of lines) {
+      cols = Math.max(cols, codeRowLength(line))
     }
 
-    rows = rows.length
+    const rows = lines.length
     if (
       (this.width > rows && this.height > cols) ||
       (this.width > cols && this.height > rows)
@@ -726,15 +777,31 @@ export class Trax {
     return false
   }
 
+  /** Get an encoded representation of the current position, useful for drawing
+   * the board without having to do much analysis.
+   * @returns {string} the current position code
+   */
   get icon() {
     return this.positionCode()
   }
 
+  /** Get an encoded representation of the current position, with a set of
+   * tiles highlighted differently, useful for showing the effects of a move.
+   * @arg {TileDrop} drops - the drops of the most recent play
+   * @returns {string} the current position code, with drops highlighted
+   */
   dropsIcon(drops) {
     return this.positionCode(undefined, undefined, undefined, drops)
   }
 
-  // Symmetry helper, draw the board from different angles
+  /** Symmetry helper, draw the board from different angles.
+   * @arg {boolean} [rightToLeft] - reverse order horizontally
+   * @arg {boolean} [bottomToTop] - reverse order vertically
+   * @arg {boolean} [rotate] - rotate the tiles by 90 degrees
+   * @arg {TileDrop} [drops] - the drops of the most recent play, if you want
+   * them highlighted
+   * @returns {string} an encoding of the position
+   */
   positionCode(rightToLeft, bottomToTop, rotate, drops) {
     const startX = rightToLeft ? this.right : this.left
     const startY = bottomToTop ? this.bottom : this.top
@@ -799,9 +866,11 @@ export class Trax {
     return code.join(':')
   }
 
+  /** Trax has the potential for symmetry, so this gives us the ability to
+   * examine horizontal, vertical, and rotational symmetry for a color.
+   * @returns {string} a position code that matches all symmetrical positions
+   */
   normalize() {
-    // Trax has the potential for symmetry, so this gives us the ability to
-    // examine horizontal, vertical, and rotational symmetry for a color
     let norm = 'z'
     const bools = [true, false]
     for (const rightToLeft of bools) {
@@ -816,6 +885,9 @@ export class Trax {
     return (this.color || 't').toUpperCase() + norm
   }
 
+  /** Get the normalized code for this position. All symmetrical positions will
+   * result in the same normalized code.
+   */
   get normalized() {
     return this.normalize()
   }

package/src/types.d.ts

@@ -7,6 +7,21 @@
 /** Color is a single character to represent white or black. */
 type Color = 'w' | 'b'
 
+/** One end of a line and the tiles taken to get there. */
+type LineEnd = {
+  loc: Point
+  path: TileId[]
+}
+
+/** A notation of a move. */
+type Notation = string
+
+/** A tile type and a location determine a raw move. */
+type RawMove = {
+  type: TileType
+  loc: Point
+}
+
 /** Treat the save state as an opaque object,
  * produced by save() and fed into restore().
  */
@@ -19,7 +34,7 @@ type SaveState = {
   right: number
   top: number
   bottom: number
-  notation: string
+  notation: Notation
   tiles: string
   path: string
   invalid: boolean
@@ -42,7 +57,7 @@ type Tile = {
 /** When a tile is dropped, this object represents the results. */
 type TileDrop = {
   dropped: Tile[]
-  notation: string
+  notation: Notation
   valid: boolean
 }
 

package/src/version.js

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '0.22.0'
+export const version = '1.0.0'