@slugbugblue/trax 0.10.1 → 0.11.0

package/CHANGELOG.md

@@ -1,12 +1,22 @@
 # @slugbugblue/trax
 
-## 0.10.1 - 2022-06-12
+## 0.11.0 - 2022-09-22
+
+- Breaking change: Refactor `play()` and `playMove()` into a single function
+  `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
+
+## 0.10.1 - 0.10.2 - 2022-06-12
 
 - Added an entry point for the `Point` class at `@slugbugblue/trax/point`
 
 ## 0.10.0 - 2022-06-12
 
-- Added `point.in(topLoft, bottomRight)` to see if a point is inside a
+- Added `point.in(topLeft, bottomRight)` to see if a point is inside a
   rectangular bounded area
 - Minor coding style changes due to updated `xo` rules
 

package/README.md

@@ -117,9 +117,10 @@ puzzle.play('@2\\')
 
 For specifics, see the [engine.js documentation][engine-docs].
 
-## Related Projects
+## Roadmap
 
-- [TraxBot][traxbot]: Game position analysis and puzzlebot
+- Game position analysis
+- Puzzles and Puzzlebot
 
 ## Support
 
@@ -139,7 +140,7 @@ his generosity in allowing me to add the game to [GoldToken.com][goldtoken].
 Thanks to his widow Colleen Foley-Smith for extending that courtesy to allow me
 to include Trax on [slugbugblue.com][sbb] as well.
 
-I would also like to extend a huge heartfelt appreciation to the magnanimous
+I would also like to express my huge heartfelt appreciation to the magnanimous
 [Donald G. Bailey][dgb], who, through his excellent book [Trax Strategy for
 Beginners][traxbook], taught me the basics (and more!) of Trax. I found him
 always ready to share his insights on the mechanics of the game, as well as
@@ -179,7 +180,6 @@ David Smith and heirs, and are not to be used without permission.
 [repo]: https://gitlab.com/slugbugblue/trax
 [sbb]: https://slugbugblue.com/
 [traxbook]: http://traxgame.com/shop_book.php
-[traxbot]: https://gitlab.com/slugbugblue/traxbot
 [traxgame]: http://traxgame.com/
 [xdg]:
   https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html

package/docs/analyst.md

@@ -0,0 +1,160 @@
+# analyst.js API documentation
+
+This module provides additional analysis of Trax games, which can be used in the
+CLI and for bots.
+
+## Example usage
+
+```javascript
+import { Trax } from '@slugbugblue/trax'
+import { analyze } from '@slugbugblue/trax/analyst'
+
+const trax = new Trax('trax', '@0/ @1/ B0\\')
+
+const analysis = analyze(trax)
+
+console.log(JSON.stringify(analysis.edge, null, 2))
+console.log(JSON.stringify(analysis.threats, null, 2))
+console.log(JSON.stringify(analysis.scores, null, 2))
+```
+
+## API
+
+### Analysis class
+
+Available either as `Analysis` to be used with `new`, or it can also be returned
+using the `analyze` shortcut function.
+
+Provides important properties and functions to understand the current state of a
+Trax game.
+
+#### constructor
+
+##### `new Analysis(game)`
+
+##### `analyze(game)`
+
+Provide a Trax `game`, ideally with at least one move and not yet completed.
+
+#### computed properties
+
+##### `game`
+
+The Trax object that represents the position originally analyzed.
+
+##### `edge`
+
+An object with two properties, `b` and `w`, which are string representations of
+the traced edge, with one character per space, along with an array named `edge`
+which contains the full internal details of each edge space. This object is
+tightly tied to the internal representation of the edge tracing algorithm and as
+such is subject to change in future iterations.
+
+Edge tracing begins in the top left of the tiles (ie, space A0 or the nearest
+playable space to it) and walks clockwise around the perimeter of the played
+tiles, recording information about the lines that lead to each space. Note that
+the edge spaces are just outside the existing tiles, not on the tiles
+themselves. The following keys are present in each edge space representation:
+
+- `x` and `y`: The location of the edge space, which can be directly used to
+  create a `Point` for use in any function that takes a location.
+- `c`: The color of the line that leads into this space. This can be `b` or `w`
+  or `l` or `r`, the latter two representing both black and white lines ("left
+  turn") or neither ("right turn").
+- `t`: The type of space, which is `n` for a normal space, `c` for a space
+  inside a cave that has limits on which tiles can be legally played in it, or
+  `x` if there are no legal moves available for this space, which can happen
+  both in caves or in 8x8 Trax when the game size limits have been reached.
+- `w` and `b`: True if the next line of the same color is the other end of this
+  line.
+- `nw` and `nb`: The number of the white and/or black lines coming to this
+  space, which can then be used to find the other end of the line.
+- `pb` and `pw`: True if the next line of the same color is part of a
+  connectable pair of lines with this color.
+- `zb` and `zw`: The character used in the black or white string representation
+  of this space.
+
+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
+matching simpler, the black string is constructed by first swapping the colors,
+so that it appears as though all black tiles are white tiles.
+
+- `b`: a black line enters this space.
+- `w`: a white line enters this space.
+- `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
+  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.
+- `p`: both a black and a white line enter this space, and the next while line
+  in the edge forms a connectable pair with the white line.
+- `r`: no lines enter this space, but it represents a right-corner in the edge.
+
+##### `threats`
+
+Analyzes the existing threats for the current game position. Returns an object
+with both `b` and `w` keys, where each is an object with zero or more "depth"
+keys. Threats of depth 0 are corners or connectable-pairs. Threats of depth 1
+are immediate attacks. Threats of depth 2 are Ls. etc. Note that the threats are
+not checked for faultiness at this time. In other words, there may be a faulty L
+listed as a threat even if it is not currently possible to activate the L
+successfully.
+
+The "depth" keys are arrays of the threats at that level, which means that a
+simple count of the threats at each level can give a good first guess at the
+"score" of the current position. Each element of the array is an object with the
+following keys:
+
+- `pattern`: The threat pattern as it was fed into the threats database. This is
+  a simple edge string.
+- `match`: The portion of the actual edge string that matched the pattern, which
+  may or may not be exactly the same as the pattern.
+- `at`: The index of the edge string at which the pattern match began.
+
+##### `score`
+
+Computes a rough "score" of the current position using the list of threats. A
+positive score means that the player whose turn it is has a potential advantage,
+with the larger the number of higher the advantage. A negative score indicates a
+disadvantage.
+
+##### `scores`
+
+Returns the same score as above, but packaged into an object with both a `b` and
+`w` key, to more easily grab the score of a particular player without regard to
+whose turn it is. Note that `b` will not necessarily be equal to `w` times -1
+because the scores can change depending on who has the initiative.
+
+#### methods
+
+##### `inCave(loc)`
+
+For any given location, returns true if that location is found within a cave.
+
+##### `spaceType(loc)`
+
+For any given location, determine the type of playable space. Returns one of:
+
+- `n`: This location can be played in normally.
+- `x`: A move is not valid in this location.
+- `c`: This location is in a cave, but otherwise has no restrictions on its
+  play.
+- `C`: This location is in a cave, and certain plays at this position result in
+  illegal moves.
+
+## License
+
+Copyright 2019-2022 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/docs/engine.md

@@ -167,8 +167,16 @@ each move that can be played will be legal.
 
 ##### `play(notation)`
 
-Attempts to play the given `notation`. Updates the game instance if the notation
-is valid for the current position.
+##### `play(moveNumber, notation)`
+
+Attempts to play the given `notation`. If `moveNumber` is provided, add a
+safeguard around the move to ensure that the move is being submitted against the
+expected position, which can be useful in the context of asynchronous
+communication and retries, such as when this engine is being used as the back
+end of a web interface. For example, if no moves have been made yet in a game,
+this can be called either as `play(1, '@0/')` or `play(1, '@0+')`.
+
+Updates the game instance if the notation is valid for the current position.
 
 Returns an object with at minimum the following key/value pair:
 
@@ -179,16 +187,24 @@ If the move is valid, the following will also be part of the returned object:
 - `dropped`: a list of the tiles that were played by this move
 - `notation`: the resulting notation of the move
 
-##### `playMove(moveNumber, notation)`
+##### `playMoves(moves)`
 
-Used to play a move, but with an extra safeguard around the status of the game
-so that if this is called multiple times with the same values, it will ignore
-subsequent calls, which can be useful in the context of asynchronous
-communication and retries, such as when this engine is being used as the back
-end of a web interface. For example, if no moves have been made yet in a game,
-this can be called either as `playMove(1, '@0/')` or `playMove(1, '@0+')`.
+Can be used to enter multiple `moves` at once. Pass in either a string of
+space-separated notations or an array of notations. In both cases move numbers
+can be optionally included, in which case the moves are not made if the move
+numbers do not match the board position. This function tries to be as forgiving
+as possible of format.
+
+For example, if a new trax object with zero moves were just created, each of the
+following statements would put the game in the same position:
 
-Returns the same object structure as the `play()` method.
+```javascript
+trax.playMoves('@0/ A0+ B1/')
+trax.playMoves(['@0/', 'a0+', 'B1/'])
+trax.playMoves('1 @0/ 2. a0+ 3 b1/')
+trax.playMoves([1, '@0/', '2', 'A0+', '3.', 'B1/')
+trax.playMoves(['1. @0/', 'a0+', 3, 'b1/')
+```
 
 ##### `provisionalMove(from, to, via)`
 

package/docs/point.md

@@ -9,7 +9,7 @@ functionality here.
 ## Example usage
 
 ```javascript
-import { Point } from '@slugbugblue/trax/point'
+import { Point } from '@slugbugblue/trax/point.js'
 
 const zero = new Point(0, 0)
 
@@ -49,6 +49,8 @@ an `x` and a `y` key with numeric values), or from individual `x` and `y`
 numbers. Once a point is created, it cannot be changed; however, you can use its
 functions to return other points relative to it.
 
+#### properties
+
 ##### `x` and `y` immutable properties
 
 You can return the individual `x` or `y` property of a point by accessing it
@@ -64,6 +66,8 @@ points.
 
 Or, get an array of all four cardinal points around the existing point.
 
+#### methods
+
 ##### `dir(direction)`
 
 Pass in a string named direction (ie, one of `up`, `down`, `left`, or `right`)
@@ -111,11 +115,13 @@ default. For example:
 
 ```javascript
 const zero = new Point(0, 0)
-const json = JSON.stringify(zero)
-const jsonzero = JSON.parse(json)
+const json = JSON.stringify(zero) // '{"x":0,"y":0}'
+const jsonzero = JSON.parse(json) // { x: 0, y: 0 }
 
 console.log(zero.eq(jsonzero)) // true
 jsonzero.eq(zero) // TypeError: jsonzero.eq is not a function
+
+// However, the object can easily be turned back into a Point:
 const reconstituted = new Point(jsonzero)
 console.log(reconstituted.eq(zero)) // true
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slugbugblue/trax",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "Trax game engine and friends",
   "keywords": [
     "trax",
@@ -13,7 +13,14 @@
   "author": "Chad Transtrum <chad@transtrum.net>",
   "exports": {
     ".": "./src/engine.js",
-    "./point": "./src/point.js"
+    "./analyst": "./src/analyst.js",
+    "./analyst.js": "./src/analyst.js",
+    "./point": "./src/point.js",
+    "./point.js": "./src/point.js",
+    "./threats": "./src/threats.js",
+    "./threats.js": "./src/threats.js",
+    "./tty": "./src/tty.js",
+    "./tty.js": "./src/tty.js"
   },
   "repository": "gitlab:slugbugblue/trax",
   "bin": {
@@ -22,7 +29,8 @@
   "scripts": {
     "test": "xo && c8 ava",
     "preversion": "npm test",
-    "postversion": "hooks/postversion.sh src/version.js"
+    "version": "genversion --es6 src/version.js && git add src/version.js",
+    "postversion": "git push && git push --tags && npm publish"
   },
   "dependencies": {
     "env-paths": "^3.0.0",

package/src/analyst.js

@@ -0,0 +1,395 @@
+/* Copyright 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.
+ */
+
+// Analyst module: provides analysis functions for Trax games
+
+import { Point } from '@slugbugblue/trax/point.js'
+import { Trax } from '@slugbugblue/trax'
+
+import { threats } from '@slugbugblue/trax/threats.js'
+
+// Helpers
+
+// Make parseInt Array.map()-friendly
+const int = (s) => Number.parseInt(s, 10)
+
+const leftTurn = { d: 'r', l: 'd', r: 'u', u: 'l' }
+const rightTurn = { d: 'l', l: 'u', r: 'd', u: 'r' }
+const follow = { d: 'right', l: 'bottom', r: 'top', u: 'left' }
+
+const edgeColor = (tile, dir) => {
+  return { d: 'ace', l: 'abd', r: 'bcf', u: 'def' }[dir].includes(tile)
+    ? 'w'
+    : 'b'
+}
+
+const encodeNumber = (n) => String.fromCodePoint(48 + n)
+
+// Explore a raw edge and update cave information
+const spelunk = (rawEdge) => {
+  for (let index = 1; index < rawEdge.length - 1; index++) {
+    if (rawEdge[index].t === 'C') {
+      const previous = rawEdge[index - 1] || {}
+      const next = rawEdge[index + 1] || {}
+      if (next.t === 'c') next.t = 'C'
+      if (previous.t === 'c') {
+        previous.t = 'C'
+        if (index > 1) index -= 2
+      }
+    }
+  }
+
+  for (const space of rawEdge) {
+    if (space.t === 'c') space.t = 'n'
+    if (space.t === 'C') space.t = 'c'
+  }
+
+  return rawEdge
+}
+
+// Combine hollows into a single item in the raw edge array
+const hollowOut = (rawEdge) => {
+  for (let index = 1; index < rawEdge.length - 1; index++) {
+    const space = rawEdge[index]
+    if (space.c === 'l') {
+      Object.assign(space, rawEdge[index - 1], rawEdge[index + 1])
+      space.c = 'l'
+      rawEdge.splice(index + 1, 1)
+      rawEdge.splice(index - 1, 1)
+    }
+  }
+
+  return rawEdge
+}
+
+// Supposedly deep nesting is bad, so we broke this out of "pairUp" for
+// "better" code, even though this is useless on its own ...
+const findPair = (rawEdge, index, color, pairs) => {
+  const colors = new Set([color, 'l'])
+  const space = rawEdge[index]
+  const nColor = 'n' + color
+  for (const x of [1, 2]) {
+    let j = x + index
+    if (j >= rawEdge.length) j -= rawEdge.length
+    const next = rawEdge[j]
+    if (colors.has(next.c) && space[nColor] !== next[nColor]) {
+      const one = color + space[nColor]
+      const two = color + next[nColor]
+      pairs[one + '-' + two] = index
+      if (two + '-' + one in pairs) {
+        for (const y of [index, pairs[two + '-' + one]]) {
+          rawEdge[y]['p' + color] = true
+        }
+      }
+
+      // Only process one connection
+      break
+    } else if (next.c === 'r') {
+      // Cannot connect past an r space
+      break
+    }
+  }
+
+  for (let x = 1; x < rawEdge.length; x++) {
+    let j = index + x
+    if (j >= rawEdge.length) j -= rawEdge.length
+    if (colors.has(rawEdge[j].c)) {
+      space[color] = rawEdge[j][nColor] === space[nColor]
+      break
+    }
+  }
+}
+
+// Find connectable pairs in the raw edge
+const pairUp = (rawEdge) => {
+  const pairs = {}
+  for (const [index, space] of rawEdge.entries()) {
+    for (const bw of ['w', 'b']) {
+      const colors = [bw, 'l']
+      if (colors.includes(space.c)) {
+        findPair(rawEdge, index, bw, pairs)
+      }
+    }
+  }
+
+  return rawEdge
+}
+
+// Label and finalize the raw edge
+const label = (rawEdge) => {
+  const final = { w: '', b: '', edge: rawEdge }
+  for (const space of rawEdge) {
+    for (const bw of ['b', 'w']) {
+      const colors = new Set([bw, 'l'])
+      let z = 'w'
+      if (colors.has(space.c)) {
+        if (space['p' + bw]) z = 'c'
+        if (space[bw]) z = 'a'
+        if (space.c === 'l') z = { w: 'l', a: 'm', c: 'p' }[z]
+      } else {
+        z = space.c === 'r' ? 'r' : 'b'
+      }
+
+      if (space.t === 'x') z = 'x'
+      space['z' + bw] = z
+      final[bw] += z
+    }
+  }
+
+  return final
+}
+
+const attackScore = (from, level) => {
+  const count = from[level]?.length ?? 0
+  if (level < 1) return count
+  return count * 10 ** (threats.maxDepth - level + 1)
+}
+
+// Shortcut to get the number of active threats
+const threatCount = (from) =>
+  Object.entries(from).filter(([d, l]) => d > 0 && l.length > 0).length
+
+// Analysis class
+export const Analysis = class {
+  #edge = undefined
+  #game = {}
+  #move = 0
+  #save = {}
+  #scores = {}
+  #threats = undefined
+
+  constructor(game) {
+    // Make a copy of the game
+    this.#game = game
+    this.#save = game.save()
+    this.#move = game.move
+  }
+
+  get game() {
+    // Return a fresh copy of the game as presented on init
+    if (this.#game.move !== this.#move) {
+      this.#game = new Trax().restore(this.#save)
+    }
+
+    return this.#game
+  }
+
+  get edge() {
+    if (!this.#edge) {
+      // Cache the edge
+      this.#edge = this.#traceEdge()
+    }
+
+    return this.#edge
+  }
+
+  get threats() {
+    if (!this.#threats) {
+      this.#threats = { b: this.#applyThreats('b'), w: this.#applyThreats('w') }
+    }
+
+    return this.#threats
+  }
+
+  // Is a given location in a cave?
+  inCave(loc) {
+    const { game } = this
+
+    if (game.tileAt(loc)) {
+      return false
+    }
+
+    const topLeft = new Point(game.left, game.top)
+    const bottomRight = new Point(game.right, game.bottom)
+    let count = 0
+
+    for (const dir of Point.dirs) {
+      let look = loc.dir(dir)
+      while (look.in(topLeft, bottomRight) && !game.tileAt(loc)) {
+        look = look.dir(dir)
+      }
+
+      if (game.tileAt(look)) count++
+    }
+
+    return count > 2
+  }
+
+  #score(color) {
+    if (this.#scores[color] === undefined) {
+      const { game } = this
+      if (game.over) {
+        this.#scores[game.color] = Number.POSITIVE_INFINITY
+        this.#scores[Trax.other(game.color)] = Number.NEGATIVE_INFINITY
+        return this.#scores[color]
+      }
+
+      let score = 0
+
+      const active = this.threats[game.color]
+      const inactive = this.threats[Trax.other(game.color)]
+      let advantage = Number.POSITIVE_INFINITY
+
+      // First examine the player who has the initiative
+      for (const level of Object.keys(active).map((i) => int(i))) {
+        if (level > 0 && level < advantage) advantage = level
+        score += attackScore(active, level)
+      }
+
+      const passive = game.color !== color
+      const calc =
+        !passive ||
+        threatCount(this.threats[color]) > 1 ||
+        threatCount(this.threats[Trax.other(color)]) > 0
+
+      // Calculate the effects of the passive player first
+      for (const level of Object.keys(inactive).map((i) => int(i))) {
+        if (level > advantage) continue
+        let points = calc || level === 0 ? attackScore(inactive, level) : 1
+        if (level === advantage) points = passive ? Math.floor(points / 2) : 0
+        score -= points
+      }
+
+      if (passive) score *= -1
+
+      this.#scores[color] = score
+    }
+
+    return this.#scores[color]
+  }
+
+  get scores() {
+    return {
+      w: this.#score('w'),
+      b: this.#score('b'),
+    }
+  }
+
+  get score() {
+    return this.scores[this.game.color]
+  }
+
+  // Space type
+  //
+  // determine which type of space we have:
+  // c = in a cave but has no restrictions (converted to n in edge)
+  // C = a cave where some moves are not allowed (converted to c in edge)
+  // n = normal space
+  // x = we cannot play here
+  spaceType(loc) {
+    const { game } = this
+
+    if (!game.validLocation(loc)) {
+      return 'x'
+    }
+
+    if (!this.inCave(loc)) {
+      return 'n'
+    }
+
+    // Check to see if we have an invalid move
+    for (const tile of game.possibleTiles(loc)) {
+      const drop = game.dropTile(tile, loc, 'tentative')
+      if (!drop.valid) {
+        return 'C'
+      }
+    }
+
+    return 'c'
+  }
+
+  // Trace the edge of the playing area
+  #traceEdge() {
+    const { game } = this
+    const rawEdge = []
+    const lines = {}
+    const count = { w: 0, b: 0 }
+    let start = new Point(game.left, game.top)
+    let dir = 'r'
+
+    while (!game.tileAt(start)) {
+      start = start.right
+    }
+
+    let loc = start
+
+    while (game.move > 0 && !game.over) {
+      let space = loc.dir(leftTurn[dir])
+      if (rawEdge.length > 0 && space.eq(rawEdge[0])) break
+
+      const color = edgeColor(game.tileAt(loc), leftTurn[dir])
+      const end = game.follow(color, loc, follow[dir]).loc
+      const type = this.spaceType(space)
+      const tile = { x: space.x, y: space.y, c: color, t: type }
+      const id = color + end.x + ':' + end.y
+      const nColor = 'n' + color
+
+      if (id in lines) {
+        tile[nColor] = lines[id][nColor]
+      } else {
+        tile[nColor] = encodeNumber(count[color])
+        count[color]++
+      }
+
+      lines[color + space.x + ':' + space.y] = tile
+      rawEdge.push(tile)
+
+      const next = loc.dir(dir)
+
+      if (game.tileAt(next)) {
+        loc = next.dir(leftTurn[dir])
+        if (game.tileAt(loc)) {
+          rawEdge.push({ x: space.x, y: space.y, c: 'l', t: type })
+          dir = leftTurn[dir]
+        } else {
+          loc = next
+        }
+      } else {
+        space = next.dir(leftTurn[dir])
+        const t = this.inCave(space) ? 'c' : 'n'
+        rawEdge.push({ x: space.x, y: space.y, c: 'r', t })
+        dir = rightTurn[dir]
+      }
+    }
+
+    return label(pairUp(hollowOut(spelunk(rawEdge))))
+  }
+
+  // Apply the threats to a color's regex-ready edge
+  #applyThreats(color) {
+    const matches = {}
+    const { length } = this.edge[color]
+    const edge = this.edge[color].repeat(2)
+    for (const threat of threats.list) {
+      const find = matches[threat.depth] || []
+      for (const match of edge.matchAll(threat.rx)) {
+        if (match.index >= length) break
+        if (find.every((f) => f.at !== match.index || f.match !== match[0])) {
+          find.push({
+            threat: threat.pattern,
+            match: match[0],
+            at: match.index,
+          })
+        }
+      }
+
+      if (find.length > 0) matches[threat.depth] = find
+    }
+
+    return matches
+  }
+}
+
+export const analyze = (game) => new Analysis(game)

package/src/cli.js

@@ -26,6 +26,7 @@ import { version } from './version.js'
 import * as tty from './tty.js'
 
 // Load all the commands as individual plugins
+import { analyzeCmd } from './cmds/analyze.js'
 import { deleteCmd } from './cmds/delete.js'
 import { helpCmd } from './cmds/help.js'
 import {
@@ -77,6 +78,7 @@ const quitCmd = {
 }
 
 const plugins = [
+  analyzeCmd,
   deleteCmd,
   exportCmd,
   helpCmd,
@@ -173,6 +175,14 @@ const DATA = { games: {} }
 
 // CLI context object for plugins
 const CLI = {
+  // Notation manipulation
+  fixNotation(move) {
+    if (move.endsWith('b')) return move.slice(0, -1) + '\\'
+    if (move.endsWith('s')) return move.slice(0, -1) + '/'
+    if (move.endsWith('p')) return move.slice(0, -1) + '+'
+    return move
+  },
+
   // Quick access to all stored games
   get GAMES() {
     return DATA.games || {}

package/src/cmds/analyze.js

@@ -0,0 +1,92 @@
+/* Copyright 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.
+ */
+
+// CLI analyze command
+
+import { analyze } from '../analyst.js'
+import { Trax } from '../engine.js'
+
+const notationRx = /^[@a-z]+\d+[bps/\\+]$/i
+
+export const analyzeCmd = {
+  name: 'analyze',
+  args: '[<move>]',
+  comp: '<play>',
+  desc: 'analyze a position',
+  help: [
+    'Analyze the current position of the currently selected game, or pass in a',
+    'move to analyze the result of that move.',
+  ],
+}
+
+const threatNames = {
+  0: 'corners',
+  1: 'attacks',
+  2: 'Ls',
+}
+
+const listThreats = (threats, detailed) => {
+  const summary = []
+  for (const level of Object.keys(threats || {})) {
+    const name = (threatNames[level] || `stage-${level} threats`) + ': '
+    const items = []
+    if (detailed) {
+      for (const item of threats[level]) {
+        items.push('[' + item.at + ':' + item.match + ']')
+      }
+    }
+
+    summary.push(name + threats[level].length + ' ' + items.join(' '))
+  }
+
+  return summary.join('  ')
+}
+
+analyzeCmd.fn = (CLI, move) => {
+  if (!String(CLI.GAME?.id)) {
+    return CLI.error('No active game. Type "new" to start a game.')
+  }
+
+  let trax = CLI.TRAX
+
+  const detailed = 'detail'.startsWith(move) || 'debug'.startsWith(move)
+
+  if (notationRx.test(move)) {
+    move = CLI.fixNotation(move)
+    CLI.do('try', move)
+    trax = new Trax(trax.rules, trax.moves, 'cli')
+    const play = trax.dropTile(move)
+    if (!play.valid || trax.over) return
+  }
+
+  if (trax.over) {
+    return CLI.error('Game has ended.')
+  }
+
+  const { edge, threats, scores } = analyze(trax)
+
+  if (detailed) CLI.out(edge.w)
+  CLI.out(
+    CLI.bubble('w', scores.w) +
+      CLI.color.white(' ') +
+      listThreats(threats.w, detailed),
+  )
+  if (detailed) CLI.out(edge.b)
+  CLI.out(
+    CLI.bubble('b', scores.b) +
+      CLI.color.black(' ') +
+      listThreats(threats.b, detailed),
+  )
+}

package/src/cmds/play-try.js

@@ -46,13 +46,6 @@ export const tryCmd = {
   ],
 }
 
-const fixNotation = (move) => {
-  if (move.endsWith('b')) return move.slice(0, -1) + '\\'
-  if (move.endsWith('s')) return move.slice(0, -1) + '/'
-  if (move.endsWith('p')) return move.slice(0, -1) + '+'
-  return move
-}
-
 playCmd.fn = (CLI, ...moves) => {
   if (moves.length === 0 || !moves[0]) {
     CLI.error('You must provide a move.')
@@ -73,9 +66,9 @@ playCmd.fn = (CLI, ...moves) => {
   for (let move of moves) {
     if (notationRx.test(move)) {
       const moveNumber = CLI.TRAX.move
-      move = fixNotation(move)
+      move = CLI.fixNotation(move)
       if (checkMove) {
-        CLI.TRAX.playMove(checkMove, move)
+        CLI.TRAX.play(checkMove, move)
       } else {
         CLI.TRAX.play(move)
       }
@@ -116,7 +109,7 @@ tryCmd.fn = (CLI, move) => {
   }
 
   if (notationRx.test(move)) {
-    move = fixNotation(move)
+    move = CLI.fixNotation(move)
     const play = CLI.TRAX.dropTile(move, undefined, 'tentative')
     if (play.valid || play.dropped.length > 0) {
       CLI.display(CLI.TRAX, CLI.GAME.players, move)

package/src/engine.js

@@ -15,15 +15,17 @@
 
 // Trax internals. Woot.
 
-// Tile type names are determined by listing the color of line at each edge, clockwise
-// and then sorted alphabetically and given a single letter name, so 'bbww' becomes 'a'
-// which gives us six different tile names: a-f
+// 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 './point.js'
 
 // Fun trax helper constants
 
 const zero = new Point(0, 0)
+const moveNumberRegex = /^(\d+)[.):]?$/
 const notationRegex = /^([@a-z]+)(\d+)([/\\+])$/i
 
 const slash = { a: '\\', b: '+', c: '/', d: '/', e: '+', f: '\\' }
@@ -127,12 +129,7 @@ export const Trax = class {
     this.invalid = false
     // Moves might be a notation string
     if (moves) {
-      if (typeof moves === 'string') moves = moves.split(/\s+/)
-      for (const move of moves) {
-        if (notationRegex.test(move)) {
-          this.dropTile(move)
-        }
-      }
+      this.playMoves(moves)
     }
   }
 
@@ -435,15 +432,43 @@ export const Trax = class {
     }
   }
 
-  play(notation) {
-    // Fast and easy way to play a move
+  play(moveNumber, notation) {
+    // Generic API call for playing a move with move number safety
+    // or, alternately, pass only a single value, notation, for a quick play
+    if (notation) {
+      if (moveNumber !== this.move + 1) return { valid: false }
+    } else {
+      notation = moveNumber
+    }
+
     return this.dropTile(notation)
   }
 
-  playMove(moveNumber, notation) {
-    // Generic API call for playing a move with move number safety
-    if (moveNumber === this.move + 1) return this.dropTile(notation)
-    return { valid: false }
+  playMoves(moves) {
+    // Play one or more moves, from a string or a list of moves
+    // If move numbers are included, ensure they are accurate
+    if (Array.isArray(moves)) {
+      moves = moves.join(' ')
+    }
+
+    moves = moves.replace(/\n/g, ' ').split(/\s+/)
+
+    let moveNumber = 0
+    for (const move of moves) {
+      if (moveNumberRegex.test(move)) {
+        moveNumber = Number(move.replace(/\D/g, ''))
+      }
+
+      if (notationRegex.test(move)) {
+        if (moveNumber) {
+          this.play(moveNumber, move)
+        } else {
+          this.play(move)
+        }
+
+        moveNumber = 0
+      }
+    }
   }
 
   updateNotation(notation) {

package/src/threats.js

@@ -0,0 +1,164 @@
+/* Copyright 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.
+ */
+
+// Threats database: hand-coded threats
+
+const REGEX = {
+  a: '[am]', // White that pairs with the next white
+  c: '[cp]', // White that forms a connectable pair with next white
+  l: '[lmp]', // White in a hollow
+  w: '[aclmpw]', // Any white
+  '!': '(?:b[acw])*?', // Ripple black/white
+  '¡': '(?:[acw]b)*?', // Ripple white/black
+  '*': 'b*?', // Zero or more black pieces
+  '?': 'b?', // Zero or one black piece
+}
+
+class CustomInspectableThreat {
+  #depth = 0
+  #pattern = ''
+  #rx = null
+
+  constructor(depth, pattern) {
+    this.#depth = depth
+    this.#pattern = pattern
+
+    let rx = ''
+    for (const char of pattern) {
+      rx += REGEX[char] || char
+    }
+
+    this.#rx = new RegExp(rx, 'g')
+  }
+
+  get depth() {
+    return this.#depth
+  }
+
+  get pattern() {
+    return this.#pattern
+  }
+
+  get rx() {
+    return this.#rx
+  }
+
+  // To make life at the REPL a little easier
+  [Symbol.for('nodejs.util.inspect.custom')](_, out) {
+    const style = out.stylize
+    return [
+      '[' + style('Threat', 'special') + ']',
+      '{',
+      style(this.#pattern, 'string') + ':',
+      style(this.#depth, 'number'),
+      '}',
+    ].join(' ')
+  }
+}
+
+class CustomInspectableThreatsDB {
+  #db = {}
+  #depth = 0
+
+  constructor(corners) {
+    for (const corner of corners) {
+      this.add(0, corner)
+    }
+  }
+
+  add(depth, pattern) {
+    this.#depth = Math.max(depth, this.#depth)
+    this.#db[pattern] = new CustomInspectableThreat(depth, pattern)
+    return this.#db[pattern]
+  }
+
+  level(depth) {
+    return Object.values(this.#db).filter((p) => p.depth === depth)
+  }
+
+  get list() {
+    return Object.values(this.#db)
+  }
+
+  get maxDepth() {
+    return this.#depth
+  }
+
+  // To make life at the REPL a little easier
+  [Symbol.for('nodejs.util.inspect.custom')](_, out) {
+    const style = out.stylize
+    const inspection = '[' + style('Threats', 'special') + '] { '
+    let total = 0
+    const keys = []
+
+    for (let x = 0; x <= this.#depth; x++) {
+      const count = this.level(x).length
+      keys.push(style(x, 'string') + ': ' + style(count, 'number'))
+      total += count
+    }
+
+    return inspection + keys.join(', ') + ' } total: ' + total
+  }
+}
+
+const pre = true
+const post = true
+const corners = {
+  arw: { pre, post }, // Simple corner
+  abrw: { post }, // Wide-first corner
+  arbw: { pre }, // Wide-second corner
+  abrbw: {}, // Wide corner
+  'ab?bw': { pre, post }, // Flat corner and wide flat corner
+  cw: { pre, post }, // Connectable pair
+  cbw: {}, // Wide connectable pair
+}
+
+export const threats = new CustomInspectableThreatsDB(Object.keys(corners))
+
+// Attacks
+const attacks = [
+  'a?w', // Simple attack and wide attack
+]
+attacks.map((a) => threats.add(1, a))
+
+// Re-forming attacks
+const reform = [
+  'rm?lr', // Cave/wide cave attack
+  'rp?lr',
+  'rbm?lbr', // Deep cave/deep wide cave attack (impossibly rare?)
+  'rbp?lbr',
+  'ralmrw', // Attack at top of cave
+  'arlmwr', // Reversed
+]
+reform.map((r) => threats.add(2, r))
+
+// Create multi-stage threats
+for (const one of Object.keys(corners)) {
+  for (const two of Object.keys(corners)) {
+    // L threats
+    const [before, after] = [corners[one].post, corners[two].pre]
+    if (before || after) {
+      const start = one.replace('w', 'l')
+      threats.add(2, start + (before ? '?¡' : '¡') + two)
+      const end = two.replace('a', 'm').replace('c', 'p')
+      threats.add(2, one + (after ? '?!' : '!') + end)
+    }
+
+    // Edge threats
+    threats.add(3, one + '!b*b¡' + two)
+  }
+}
+
+// Create edge threats

package/src/version.js

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