@slugbugblue/trax 0.21.0 → 0.23.0

package/src/engine.js

@@ -1,37 +1,17 @@
-/* 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.
-
-// Tile type names are determined by listing the line color at each edge,
-// starting from the top and going clockwise, and then sorted alphabetically
-// and given a single letter name, so 'bbww' becomes 'a', which gives us six
-// different tile names: a-f
+import { Point } from '@slugbugblue/point'
 
-import { Point } from '@slugbugblue/trax/point'
-
-// Type definitions
 // Fun trax helper constants
 
 const zero = new Point(0, 0)
 const moveNumberRegex = /^(\d+)[.):]?$/
 const notationRegex = /^([@a-z]+)(\d+)([/\\+])$/i
 
-/** @type ValidTiles[] */
-const tileTypes = ['a', 'b', 'c', 'd', 'e', 'f']
-
 /** Tiles are represented by the letters a-f.
  *     a         b        c        d        e        f
  *  +--#--+   +--#--+  +--#--+  +--o--+  +--o--+  +--o--+
@@ -40,7 +20,14 @@ const tileTypes = ['a', 'b', 'c', 'd', 'e', 'f']
  *  | o   |   |  #  |  |   o |  |   # |  |  o  |  | #   |
  *  +--o--+   +--#--+  +--o--+  +--#--+  +--o--+  +--#--+
  *
- * Slashes are represented by / \ or +.
+ * @readonly
+ * @type ValidTiles[]
+ * */
+const tileTypes = ['a', 'b', 'c', 'd', 'e', 'f']
+
+/** 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>}
  */
@@ -201,10 +188,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
@@ -252,7 +239,6 @@ export class Trax {
   /** Restore a previously saved position.
    * @arg {SaveState} saved - the previously saved state
    * @see save for saving the state
-   * @returns {void}
    */
   restore(saved) {
     // So we need to be able to restore it when we are done
@@ -316,6 +302,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
@@ -339,7 +326,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) {
@@ -382,6 +369,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
@@ -403,26 +394,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()) {
@@ -435,9 +431,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) {
@@ -460,16 +461,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
@@ -482,6 +493,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)
@@ -509,7 +528,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'))
@@ -519,6 +544,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
@@ -526,6 +556,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
@@ -534,13 +567,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)]
         }
       }
     }
@@ -581,6 +614,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
@@ -608,6 +646,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
@@ -628,7 +669,7 @@ export class Trax {
   }
 
   /** 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
@@ -678,6 +719,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)
@@ -700,15 +746,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)
@@ -731,15 +786,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
@@ -804,9 +875,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) {
@@ -821,6 +894,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,131 +7,21 @@
 /** Color is a single character to represent white or black. */
 type Color = 'w' | 'b'
 
-/** Colorize is a fancy function for colorizing text. */
-type Colorize = (text: string, def?: string | number) => string
-
-/** Colorer is a little too fancy. Hence the gnarly typescript. */
-type Colorer = {
-  (text: string, def?: string | number): string
-  black: Colorize
-  command: Colorize
-  default: Colorize
-  error: Colorize
-  fatal: Colorize
-  help: Colorize
-  id: Colorize
-  variable: Colorize
-  optional: Colorize
-  short: Colorize
-  white: Colorize
-}
-
-/** An object representing a space on the perimeter of a Trax position.
- * x,y: the coordinates of the space
- * c: the color present beside the space (w, b, l: both w and b, r: none)
- * t: the type of possible moves: n-normal, x-none, c-cave, C-restricted cave
- * b,w: if present, the number of the line to match with its other end
- * pb, pw: if present, can pair with the next line in one turn
- * xb, xw: the label of this space for each color
- */
-type EdgeLocation = {
-  x: number
-  y: number
-  c: string
-  t: string
-  b?: number
-  w?: number
-  pb?: boolean
-  pw?: boolean
-  zb?: string
-  zw?: string
-  idx?: number
-}
-
-type EdgeObject = {
-  b: string
-  w: string
-  edge: RawEdge
-}
-
-/** Object representing a concrete threat found in a position. */
-type FoundThreat = {
-  threat: string
-  match: string
-  at: number
-  value: number
-  level: number
-}
-
-/** Threats found for each color that cannot actually be activated. */
-type FaultyThreats = {
-  b: FoundThreat[]
-  w: FoundThreat[]
-}
-
-/** An object with keys representing each level, with arrays for each threat of
- * that level. */
-type ColorThreats = Record<string, FoundThreat[]>
-
-/** All the threats found for both the white and black player. */
-type FoundThreatsCollection = { b: ColorThreats; w: ColorThreats }
-
-/** Scores for each player. */
-type Scores = {
-  b: number
-  w: number
-}
-
-/** A note with a move number */
-type GameNote = {
-  move: number
-  note: string
-}
-
-/** Notes saved in the game object in the CLI. */
-type GameNotes = GameNote[]
-
-/** A point-like object has numerical x and y properties. */
-type PointLike = {
-  x: number
-  y: number
+/** One end of a line and the tiles taken to get there. */
+type LineEnd = {
+  loc: Point
+  path: TileId[]
 }
 
-/** An object used to track an analysis on a position. */
-type PositionScore = {
-  move: string
-  score: number
-  analysis?: Analysis
-}
+/** A notation of a move. */
+type Notation = string
 
-/** A puzzle. */
-type Puzzle = {
-  id: string
-  src: string
-  game: TraxVariant
-  notation: string
-  icon: string
-  level: number
-  max: number
-  player: number
-  title?: string
-  desc?: string
-  hint?: string
-  hints?: string[]
-}
-
-type PuzzleSource = {
-  name: string
-  url?: string
-  copyright?: string
-  license?: string
-  licenseUrl?: string
+/** A tile type and a location determine a raw move. */
+type RawMove = {
+  type: TileType
+  loc: Point
 }
 
-/** Array of objects representing the spaces surrounding the perimeter of a
- * Trax position. */
-type RawEdge = EdgeLocation[]
-
 /** Treat the save state as an opaque object,
  * produced by save() and fed into restore().
  */
@@ -144,7 +34,7 @@ type SaveState = {
   right: number
   top: number
   bottom: number
-  notation: string
+  notation: Notation
   tiles: string
   path: string
   invalid: boolean
@@ -155,14 +45,6 @@ type SaveState = {
  */
 type Slash = '/' | '\\' | '+'
 
-/** Threat definition. */
-type Threat = {
-  depth: number
-  pattern: string
-  rx: RegExp
-  value: number
-}
-
 /** A single tile on the board. */
 type Tile = {
   id: TileId
@@ -175,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
 }
 
@@ -188,5 +70,15 @@ type TileType = ValidTiles | 'x'
 /** All of the variants supported by the engine. */
 type TraxVariant = 'trax' | 'traxloop' | 'trax8'
 
-/** Tile types are represented by one of the following single characters. */
+/** Tile type names are determined by listing the line color at each edge,
+ * starting from the top and going clockwise, and then sorted alphabetically
+ * and given a single letter name, so 'bbww' becomes 'a', which gives us six
+ * different tile names: a-f, as follows:
+ *     a         b        c        d        e        f
+ *  +--#--+   +--#--+  +--#--+  +--o--+  +--o--+  +--o--+
+ *  |   # |   |  #  |  | #   |  | o   |  |  o  |  |   o |
+ *  oo   ##   ooo#ooo  ##   oo  oo   ##  #######  ##   oo
+ *  | o   |   |  #  |  |   o |  |   # |  |  o  |  | #   |
+ *  +--o--+   +--#--+  +--o--+  +--#--+  +--o--+  +--#--+
+ */
 type ValidTiles = 'a' | 'b' | 'c' | 'd' | 'e' | 'f'

package/src/version.js

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

package/.dockerignore

@@ -1,11 +0,0 @@
-.dockerignore
-.git*
-.husky
-.npmignore
-benchmark
-coverage
-Dockerfile
-docs
-jsconfig.json
-node_modules
-test

package/Dockerfile

@@ -1,14 +0,0 @@
-# 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
-WORKDIR /trax
-COPY . .
-RUN npm install
-# Ensure the data files can be persisted
-WORKDIR /mnt/data
-ENV XDG_CONFIG_HOME=/mnt/data
-ENV XDG_DATA_HOME=/mnt/data
-VOLUME /mnt/data
-# Use the trax CLI as the starting point
-ENTRYPOINT ["/trax/src/cli.js"]