@slugbugblue/trax 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @slugbugblue/trax
 
+## 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 engine improvements:
+
+  - Analysis engine suggestions now "solve" all tough puzzles
+  - Reworked threats to be more precise
+  - Reworked scoring to add more nuance
+
+## 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
+
+- 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.
+
 ## 0.13.0 - 2022-11-25
 
 - Add move suggestions to `analyst.js` for CLI and bot use

package/README.md

@@ -1,6 +1,11 @@
 # Trax
 
-Trax game-playing engine and etc.
+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
+- Command-line interface for ease of use
 
 ## Description
 
@@ -32,10 +37,10 @@ The command-line interface is provided as `trax`, available in your path if
 installed globally, or in the `node_modules/.bin` directory and runnable using
 `npx trax` if installed locally.
 
-The CLI can be used interactively by passing the `--interactive` or `-i` flag.
-When run interactively, you can avoid worries about the need to escape certain
-characters from the shell, and it can be easier to run multiple commands back to
-back.
+The CLI can be used interactively by running the command with no parameters or
+by passing the `--interactive` or `-i` flag. When run interactively, you can
+avoid worries about the need to escape certain characters from the shell, and it
+can be easier to run multiple commands back to back.
 
 Help is available for the CLI through the use of the `help` command. Type
 `trax help` to see a list of the available commands, and `trax help play` to see
@@ -154,7 +159,6 @@ publicly available puzzles at [the traxgame.com puzzles page][traxpuzzles].
 ## Roadmap
 
 - Improve the threats database / analysis engine.
-- Add a puzzle interface to the CLI.
 - Add more puzzles.
 
 ## Support

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slugbugblue/trax",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Trax game engine and friends",
   "keywords": [
     "trax",

package/src/analyst.js

@@ -1,26 +1,15 @@
-/* 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.
+ * @copyright 2022
+ * @author Chad Transtrum <chad@transtrum.net>
+ * @license Apache-2.0
  */
 
-// Analyst module: provides analysis functions for Trax games
-
 import { Point } from '@slugbugblue/trax/point'
 import { Trax } from '@slugbugblue/trax'
 
 import { threats } from '@slugbugblue/trax/threats'
 
-// Helpers
+/** Helper function to generate a unique id for the analysis. */
 const id = () => {
   const chars = 'abcdefghijklmnopqrstuvwxyz0123456789'
   let code = ''
@@ -31,14 +20,27 @@ const id = () => {
   return 'analysis-' + code
 }
 
-// A sort function for hashes with a numeric score property
+/** A sort function for hashes with a numeric score property.
+ * @arg {PositionScore} a - The first Position Score to be compared
+ * @arg {PositionScore} b - The second Position Score to be compared
+ * @returns {number} a.score <=> b.score
+ */
 const byScoreDesc = (a, b) => b.score - a.score
 
-// A filter function factory to remove scores not within x points of the highest score
+/** A filter function factory to remove scores not within x points of the
+ * highest score.
+ * @arg highest {number} - The highest score
+ * @arg tolerance {number} - How close another score must be to be included
+ * @returns {(s:PositionScore)=>boolean} a filter function
+ */
 const withinX = (highest, tolerance) => (s) =>
   s.score === highest || highest - s.score <= tolerance
 
-// Return a random element of an array
+/** Return a random element of an array.
+ * @template T
+ * @arg {T[]} array - an array of elements
+ * @returns {T} one of the elements at random
+ */
 const randomDraw = (array) => array[Math.floor(Math.random() * array.length)]
 
 // Make parseInt a little shorter
@@ -56,12 +58,16 @@ const edgeColor = (tile, dir) => {
 
 const encodeNumber = (n) => String.fromCodePoint(48 + n)
 
-// Explore a raw edge and update cave information
+/** Explore a raw edge and update cave information.
+ * @arg {RawEdge} rawEdge - the raw edge information
+ * @returns {RawEdge}
+ */
 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] || {}
+      const blank = () => ({ x: 0, y: 0, c: '', t: '' })
+      const previous = rawEdge[index - 1] || blank()
+      const next = rawEdge[index + 1] || blank()
       if (next.t === 'c') next.t = 'C'
       if (previous.t === 'c') {
         previous.t = 'C'
@@ -78,7 +84,10 @@ const spelunk = (rawEdge) => {
   return rawEdge
 }
 
-// Combine hollows into a single item in the raw edge array
+/** Combine hollows into a single item in the raw edge array.
+ * @arg {RawEdge} rawEdge
+ * @returns {RawEdge}
+ */
 const hollowOut = (rawEdge) => {
   for (let index = 1; index < rawEdge.length - 1; index++) {
     const space = rawEdge[index]
@@ -93,8 +102,13 @@ const hollowOut = (rawEdge) => {
   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 ...
+/** Supposedly deep nesting is bad, so we broke this out of "pairUp" for
+ * "better" code, even though this is useless on its own ...
+ * @arg {RawEdge} rawEdge
+ * @arg {number} index
+ * @arg {string} color
+ * @pairs {Record<string, number>}
+ */
 const findPair = (rawEdge, index, color, pairs) => {
   const colors = new Set([color, 'l'])
   const space = rawEdge[index]
@@ -131,8 +145,12 @@ const findPair = (rawEdge, index, color, pairs) => {
   }
 }
 
-// Find connectable pairs in the raw edge
+/** Find connectable pairs in the raw edge.
+ * @arg {RawEdge} rawEdge
+ * @returns {RawEdge}
+ */
 const pairUp = (rawEdge) => {
+  /** @type Record<string, number> */
   const pairs = {}
   for (const [index, space] of rawEdge.entries()) {
     for (const bw of ['w', 'b']) {
@@ -146,7 +164,10 @@ const pairUp = (rawEdge) => {
   return rawEdge
 }
 
-// Label and finalize the raw edge
+/** Label and finalize the raw edge.
+ * @arg {RawEdge} rawEdge
+ * @returns {EdgeObject}
+ */
 const label = (rawEdge) => {
   const final = { w: '', b: '', edge: rawEdge }
   for (const space of rawEdge) {
@@ -170,47 +191,73 @@ const label = (rawEdge) => {
   return final
 }
 
-const threatValues = (threatsArray) => {
-  return threatsArray.length
-  // Hm. Maybe we don't need this ...
-  // let count = 0
-  // for (const threat of threatsArray) count += threat.value
-  // return count
-}
+/** Quick way to get the number of items in an array.
+ * @returns {number} - length of the array
+ */
+const length = (array) => array?.length || 0
 
-const attackScore = (from, level) => {
-  const count = threatValues(from[level] || [])
-  if (level < 1) return count
-  return count * 10 ** (threats.maxDepth - level + 1)
+/** Calculate the points for the number of threats at a particular level.
+ * @arg {FoundThreats} from - the threats found for a certain player
+ * @arg {number} level - the level to calculate the points for
+ * @arg {number} [as] - if included, the level the points should be calculated as
+ * @return {number} the number of points for the level
+ */
+const attackScore = (from, level, as) => {
+  const count = length(from[level])
+  const calculateAs = Math.min(as === undefined ? level : as, threats.maxDepth)
+  if (calculateAs < 1) return count
+  return count * 10 ** (threats.maxDepth - calculateAs + 1)
 }
 
-// Shortcut to get the number of attacks
-const attackCount = (from) => threatValues(from['1'] || [])
+/** Shortcut to get the number of attacks.
+ * @arg {FoundThreats} from - the threats found for a certain player
+ * @returns {number} the number of attacks (win on next move) present
+ */
+const attackCount = (from) => length(from['1'])
 
-// Shortcut to get the number of passive threats
+/** Shortcut to get the number of passive threats
+ * @arg {FoundThreats} from - the threats found for a player
+ * @returns {number} the number of passive threats (win in 2 or more moves)
+ */
 const threatCount = (from) => {
   let count = 0
   for (const [depth, array] of Object.entries(from)) {
-    count += int(depth) > 1 ? threatValues(array) : 0
+    count += int(depth) > 1 ? length(array) : 0
   }
 
   return count
 }
 
-const passiveAttack = (from) =>
+/** Shortcut to determine if we have an active attack.
+ * @arg {FoundThreats} from - the threats found for a player
+ * @returns {boolean}
+ */
+const activeAttack = (from) =>
   attackCount(from) > 1 || (attackCount(from) === 1 && threatCount(from) > 0)
 
+/** Shortcut to determine if we have a passive attack.
+ * @arg {FoundThreats} from - the threats found for a player
+ * @returns {boolean}
+ */
+const passiveAttack = (from) => threatCount(from) > 1
+
+/** Shortcut to determine if we are under attack.
+ * @arg {FoundThreats} from - the threats found for a player
+ * @returns {boolean}
+ */
 const underAttack = (from) => attackCount(from) + threatCount(from) > 0
 
 // Analysis class
 export const Analysis = class {
-  /** @type TraxVariant */
+  /** @type {TraxVariant} */
   #rules = 'trax'
   #id = 'analysis'
+  /** @type {string[]} - List of moves to arrive at this position */
   #moves = []
   #notation = ''
   #edge = undefined
-  #game = {}
+  /** @type {Trax} */
+  #game
   #scores = {}
   #threats = undefined
 
@@ -241,6 +288,9 @@ export const Analysis = class {
     return this.#edge
   }
 
+  /** All threats present in this position.
+   * @returns {FoundThreatsCollection}
+   */
   get threats() {
     if (!this.#threats) {
       this.#threats = { b: this.#applyThreats('b'), w: this.#applyThreats('w') }
@@ -273,6 +323,69 @@ export const Analysis = class {
     return count > 2
   }
 
+  /** Determine the points of the currently active player.
+   * @returns {[number, number]} - the points for this player, and the level
+   * of the most dangerous threat
+   */
+  #activeScore() {
+    let score = 0
+    let threatLevel = Number.POSITIVE_INFINITY
+    const { game } = this
+    const active = this.threats[game.color]
+
+    // First examine the active player
+    for (const level of Object.keys(active).map((i) => int(i))) {
+      if (level > 0) threatLevel = Math.min(threatLevel, level)
+      score += attackScore(active, level)
+    }
+
+    return [score, threatLevel]
+  }
+
+  /** Determine the points of the waiting player.
+   * @arg {Color} color - the color for which we are generating the score
+   * @arg {number} threatLevel - the lowest level for which the active player
+   * has an active threat
+   * @returns {[number, number]} - the points for this player and the multiplier
+   * to be applied to the other player's points
+   */
+  #inactiveScore(color, threatLevel) {
+    const { game } = this
+    const active = this.threats[game.color]
+    const inactive = this.threats[Trax.other(game.color)]
+
+    // Is the color we are looking at the passive player?
+    const passive = game.color !== color
+
+    // Is the inactive player activating known threats?
+    const attacking = activeAttack(inactive)
+
+    // Was the inactive player unable to clear all threats?
+    const defending = !attacking && underAttack(active)
+
+    // Does the inactive player have multiple threats
+    const threatening = !attacking && passiveAttack(inactive)
+
+    // If calc is false, attacks and threats are treated as corners
+    const calc = !passive || attacking || defending || threatening
+
+    // If the current player does not hold the initiative, reduce the score
+    const multiplier = passive && attacking && threatLevel > 1 ? 0.1 : 1
+
+    let score = 0
+
+    // Now calculate the effects of the passive player
+    for (const level of Object.keys(inactive).map((i) => int(i))) {
+      const calcLevel = level > 0 && defending ? level + threatLevel - 1 : level
+      let points = attackScore(inactive, level, calc ? calcLevel : 0)
+      if (level === threatLevel) points = passive ? Math.floor(points / 2) : 0
+      if (threatening) points = Math.floor(points / 2)
+      score += points
+    }
+
+    return [score, multiplier]
+  }
+
   #score(color) {
     if (this.#scores[color] === undefined) {
       const { game } = this
@@ -282,30 +395,11 @@ export const Analysis = class {
         return this.#scores[color]
       }
 
-      let score = 0
+      const [currentPlayer, threatLevel] = this.#activeScore()
+      const [nextPlayer, multiplier] = this.#inactiveScore(color, threatLevel)
 
-      const active = this.threats[game.color]
-      const inactive = this.threats[Trax.other(game.color)]
-      let advantage = Number.POSITIVE_INFINITY
-
-      // First examine the active player
-      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 || passiveAttack(inactive) || underAttack(active)
-
-      // 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
+      let score = Math.floor(currentPlayer * multiplier) - nextPlayer
+      if (score && game.color !== color) score *= -1
 
       this.#scores[color] = score
     }
@@ -368,6 +462,7 @@ export const Analysis = class {
   // Trace the edge of the playing area
   #traceEdge() {
     const { game } = this
+    /** @type {RawEdge} */
     const rawEdge = []
     const lines = {}
     const count = { w: 0, b: 0 }
@@ -422,8 +517,26 @@ export const Analysis = class {
     return label(pairUp(hollowOut(spelunk(rawEdge))))
   }
 
-  // Apply the threats to a color's regex-ready edge
+  /** Compose the threat into a FoundThreat object.
+   * @arg {Threat} threat - the threat that has been found
+   * @arg {RegExpMatchArray} match - the matching item
+   * @returns {FoundThreat}
+   */
+  #foundThreat(threat, match) {
+    return {
+      threat: threat.pattern,
+      match: match[1], // The match is in the capturing group
+      at: match.index,
+      value: threat.value,
+    }
+  }
+
+  /** Apply the threats to a color's regex-ready edge.
+   * @arg {Color} color - the color to find threats for
+   * @returns {FoundThreats}
+   */
   #applyThreats(color) {
+    /** @type {FoundThreats} */
     const matches = {}
     const { length } = this.edge[color]
     const edge = this.edge[color].repeat(2)
@@ -431,13 +544,11 @@ export const Analysis = class {
       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,
-            value: threat.value,
-          })
+        if (find.every((f) => f.at !== match.index || f.match !== match[1])) {
+          find.push(this.#foundThreat(threat, match))
+        } else {
+          const duplicate = matches[99] || []
+          duplicate.push(this.#foundThreat(threat, match))
         }
       }
 
@@ -479,12 +590,19 @@ export const Analysis = class {
   }
 }
 
+/** Analyze a game position.
+ * @arg {Trax} game - the position to analyze
+ * @returns {Analysis}
+ */
 export const analyze = (game) => new Analysis(game)
 
 export const Suggestion = class {
+  /** @type {PositionScore[]} */
   all = []
+  /** @type {PositionScore[]} */
   options = []
-  pick = {}
+  /** @type {PositionScore} */
+  pick
   ms = 0
 
   constructor(analyzed, ms) {

package/src/cli.js

@@ -39,6 +39,7 @@ import {
 import { listCmd } from './cmds/list.js'
 import { newCmd } from './cmds/new.js'
 import { playCmd, tryCmd } from './cmds/play-try.js'
+import { puzzlesCmd } from './cmds/puzzles.js'
 import { selectCmd } from './cmds/select.js'
 import { suggestCmd } from './cmds/suggest.js'
 import { undoCmd } from './cmds/undo.js'
@@ -87,6 +88,7 @@ const plugins = [
   listCmd,
   newCmd,
   playCmd,
+  puzzlesCmd,
   quitCmd,
   selectCmd,
   suggestCmd,
@@ -190,8 +192,8 @@ const color = (text, def) => {
 }
 
 // Internal representations of files
-const CONFIG = { id: '' }
-const DATA = { games: {} }
+const CONFIG = { id: '', puzzleLevel: 0 }
+const DATA = { games: {}, puzzles: {} }
 
 // CLI context object for plugins
 const CLI = {
@@ -215,6 +217,10 @@ const CLI = {
   get ID() {
     return CONFIG.id
   },
+  // The current puzzle level
+  get puzzleLevel() {
+    return CONFIG.puzzleLevel
+  },
 
   // Provide access to the current Trax object
   TRAX: new Trax(),
@@ -231,6 +237,7 @@ const CLI = {
     variable: 123,
     optional: 110,
     short: 153,
+    success: 35,
     white: 250,
   },
 
@@ -298,11 +305,57 @@ const CLI = {
     return id
   },
 
+  newPuzzle(puzzle) {
+    // Starts a new puzzle
+    const id = newId(DATA)
+    const trax = new Trax(puzzle.game, puzzle.notation, 'cli')
+    const players = ['challenger', 'puzzlebot']
+    DATA.games[id] = {
+      id,
+      puzzle: puzzle.id,
+      rules: trax.rules,
+      name: trax.name,
+      turn: trax.turn,
+      max: puzzle.max,
+      players: trax.turn === 1 ? players : players.reverse(),
+      moves: trax.moves.join(' '),
+    }
+
+    if (DATA.puzzles[puzzle.id]) {
+      DATA.puzzles[puzzle.id].attempts += 1
+    } else {
+      DATA.puzzles[puzzle.id] = { attempts: 1, solved: 0 }
+    }
+
+    CONFIG.id = id
+    CONFIG.puzzleLevel = puzzle.level
+    CLI.TRAX = trax
+
+    saveConfig()
+    saveData()
+
+    return id
+  },
+
   out(text) {
     // Prints to stdout
     console.info(text + tty.color(''))
   },
 
+  plural(n, noun, nouns) {
+    return String(n) + ' ' + (Math.abs(n) === 1 ? noun : nouns || noun + 's')
+  },
+
+  puzzle(id) {
+    return DATA.puzzles?.[id] || { attempts: 0, solved: 0 }
+  },
+
+  puzzleSolved(id) {
+    DATA.puzzles = DATA.puzzles || {}
+    DATA.puzzles[id] = DATA.puzzles[id] || { attempts: 1, solved: 0 }
+    DATA.puzzles[id].solved += 1
+  },
+
   resolveCommand(word) {
     // Determine if an entered word is a valid command.
     // Returns the command if a single match is found, an array if multiple

package/src/cmds/analyze.js

@@ -22,7 +22,7 @@ const notationRx = /^[@a-z]+\d+[bps/\\+]$/i
 
 export const analyzeCmd = {
   name: 'analyze',
-  args: '[<move>]',
+  args: '[move]',
   comp: '<play>',
   desc: 'analyze a position',
   help: [
@@ -44,7 +44,7 @@ const listThreats = (threats, detailed) => {
     const items = []
     if (detailed) {
       for (const item of threats[level]) {
-        items.push('[' + item.at + ':' + item.match + ']')
+        items.push('[' + item.at + ':' + item.threat + ':' + item.match + ']')
       }
     }
 

package/src/cmds/import-export.js

@@ -22,6 +22,7 @@ import envPaths from 'env-paths'
 import makeDir from 'make-dir'
 
 import { Trax } from '@slugbugblue/trax'
+import { puzzles, sources } from '@slugbugblue/trax/puzzles'
 
 const paths = envPaths('trax', { suffix: '' })
 const PATHS = {}
@@ -30,7 +31,12 @@ const PATHS = {}
 let cli = {}
 
 const fsOuch = (fsError) => {
-  cli.out(fsError, cli.COLORS.fatal)
+  if (cli.out) {
+    cli.out(fsError, cli.COLORS.fatal)
+  } else {
+    console.log(fsError)
+  }
+
   throw fsError
 }
 
@@ -72,7 +78,12 @@ export const getFile = async (filetype, filename, variable, decode) => {
       }
     } catch (fsError) {
       if (fsError instanceof TypeError || fsError instanceof SyntaxError) {
-        cli.error(`Unable to read ${filetype} file ${path}/${filename}`)
+        const error = `Unable to read ${filetype} file ${path}/${filename}`
+        if (cli.error) {
+          cli.error(error)
+        } else {
+          console.log(error)
+        }
       } else if (fsError.code !== 'ENOENT') {
         fsOuch(fsError)
       }
@@ -200,6 +211,25 @@ exportCmd.fn = (CLI, id, filename) => {
   content += ' vs '
   content += game.players?.[1] || 'black'
   content += '\n; @slugbugblue/trax cli.js v' + CLI.version + '\n'
+  if (game.puzzle) {
+    const puzzle = puzzles.find((p) => p.id === game.puzzle)
+    if (puzzle) {
+      const source = sources[puzzle.src]
+      content += '; Puzzle ' + game.puzzle
+      if (source) {
+        content += ' provided courtesy of ' + source.name
+        if (source.url) content += ' (' + source.url + ')'
+      }
+
+      if (puzzle.title) content += '\n; ' + puzzle.title
+      if (puzzle.desc) content += '\n; ' + puzzle.desc
+      content += '\n; Starting position ' + puzzle.notation + '\n; '
+      const players = [0, 'white', 'black']
+      content += players[puzzle.player] + ' to win by move '
+      content += String(puzzle.max) + '\n'
+    }
+  }
+
   content += trax.notation + '\n'
   if (filename) filename = filename.replace(/[^ a-z\d.~/]/g, '')
   if (filename) {