@slugbugblue/trax 0.19.0 → 0.21.0

package/src/analyst.js

@@ -12,7 +12,9 @@ import { threats } from '@slugbugblue/trax/threats'
 
 const cache = new LRU(2750)
 
-/** Helper function to generate a unique id for the analysis. */
+/** Helper function to generate a unique id for the analysis.
+ * @returns {string} a 6 character random string
+ */
 const id = () => {
   const chars = 'abcdefghijklmnopqrstuvwxyz0123456789'
   let code = ''
@@ -46,19 +48,35 @@ const withinX = (highest, tolerance) => (s) =>
  */
 const randomDraw = (array) => array[Math.floor(Math.random() * array.length)]
 
-// Make parseInt a little shorter
+/** Make parseInt a little shorter with decent defaults.
+ * @arg s {string} - A string representation of a decimal number
+ * @returns {number} the parsed number
+ */
 const int = (s) => Number.parseInt(s, 10)
 
+/** The direction after a left turn. */
 const leftTurn = { d: 'r', l: 'd', r: 'u', u: 'l' }
+/** The direction after a right turn. */
 const rightTurn = { d: 'l', l: 'u', r: 'd', u: 'r' }
+/** Which way to follow. */
 const follow = { d: 'right', l: 'bottom', r: 'top', u: 'left' }
 
+/** Given a tile and a direction, return the color of the line going that
+ * direction.
+ * @arg tile {TileType} - the tile in question
+ * @arg dir {string} - direction u, d, l, or r
+ * @returns {Color}
+ */
 const edgeColor = (tile, dir) => {
   return { d: 'ace', l: 'abd', r: 'bcf', u: 'def' }[dir].includes(tile)
     ? 'w'
     : 'b'
 }
 
+/** Encode a number as a character.
+ * @arg n {number} - the number to encode
+ * @returns {string} the encoded number
+ */
 const encodeNumber = (n) => String.fromCodePoint(48 + n)
 
 /** Explore a raw edge and update cave information.
@@ -204,7 +222,7 @@ const label = (rawEdge) => {
 const length = (array) => array?.length || 0
 
 /** Calculate the points for the number of threats at a particular level.
- * @arg {FoundThreats} from - the threats found for a certain player
+ * @arg {ColorThreats} 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
@@ -217,16 +235,23 @@ const attackScore = (from, level, as) => {
 }
 
 /** Shortcut to get the number of attacks.
- * @arg {FoundThreats} from - the threats found for a certain player
+ * @arg {ColorThreats} 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 threats at a certain level.
+ * @arg {ColorThreats} from - the threats found for a player
+ * @arg {number} level - the level for the threats to look for
+ * @returns {number} the number of threats at the given level
+ */
+const threatCount = (from, level) => length(from[level])
+
 /** Shortcut to get the number of passive threats
- * @arg {FoundThreats} from - the threats found for a player
+ * @arg {ColorThreats} from - the threats found for a player
  * @returns {number} the number of passive threats (win in 2 or more moves)
  */
-const threatCount = (from) => {
+const passiveCount = (from) => {
   let count = 0
   for (const [depth, array] of Object.entries(from)) {
     count += int(depth) > 1 ? length(array) : 0
@@ -236,25 +261,31 @@ const threatCount = (from) => {
 }
 
 /** Shortcut to determine if we have an active attack.
- * @arg {FoundThreats} from - the threats found for a player
+ * @arg {ColorThreats} from - the threats found for a player
  * @returns {boolean}
  */
 const activeAttack = (from) =>
-  attackCount(from) > 1 || (attackCount(from) === 1 && threatCount(from) > 0)
+  attackCount(from) > 1 || (attackCount(from) === 1 && passiveCount(from) > 0)
 
 /** Shortcut to determine if we have a passive attack.
- * @arg {FoundThreats} from - the threats found for a player
+ * @arg {ColorThreats} from - the threats found for a player
  * @returns {boolean}
  */
-const passiveAttack = (from) => threatCount(from) > 1
+const passiveAttack = (from) => passiveCount(from) > 1
 
-/** Shortcut to determine if we are under attack.
- * @arg {FoundThreats} from - the threats found for a player
+// /** Shortcut to determine if we are under attack.
+//  * @arg {ColorThreats} from - the threats found for a player
+//  * @returns {boolean}
+//  */
+// const underAttack = (from) => attackCount(from) > 0
+
+/** Shortcut to determine if we are under threat.
+ * @arg {ColorThreats} from - the threats found for a player
  * @returns {boolean}
  */
-const underAttack = (from) => attackCount(from) + threatCount(from) > 0
+const underThreat = (from) => attackCount(from) + passiveCount(from) > 0
 
-// Analysis class
+/** Trax position analysis. */
 export class Analysis {
   /** @type {TraxVariant} */
   #rules = 'trax'
@@ -262,15 +293,18 @@ export class Analysis {
   /** @type {string[]} - List of moves to arrive at this position */
   #moves = []
   #notation = ''
+  /** @type EdgeObject */
   #edge = undefined
   /** @type {Trax} */
   #game
-  #scores = {}
+  /** @type Scores */
+  #scores = undefined
+  /** @type FoundThreatsCollection */
   #threats = undefined
-  #faulty = { b: [], w: [] }
-  #partial = false
+  #validated = false
 
-  constructor(game, partial = false) {
+  /** @arg game {Trax} - an in-progress trax game */
+  constructor(game) {
     // Make a copy of the game
     this.#rules = game.rules
     this.#moves = game.moves
@@ -281,11 +315,18 @@ export class Analysis {
       w: (level) => this.threats.w[level]?.length || 0,
       b: (level) => this.threats.b[level]?.length || 0,
     }
-    this.#partial = Boolean(partial)
+    /** @type FaultyThreats */
+    this.faulty = { b: [], w: [] }
+    this.#validated = false
+    if (this.#moves.length === 0 || game.over) {
+      /** @type EdgeObject */
+      this.#edge = { b: '', w: '', edge: [] }
+      this.#threats = { b: {}, w: {} }
+    }
   }
 
+  /** A fresh copy of the game as presented on init. */
   get game() {
-    // Return a fresh copy of the game as presented on init
     if (this.#game.notation !== this.#notation) {
       this.#game = new Trax(this.#rules, this.#moves, this.#id)
     }
@@ -293,6 +334,7 @@ export class Analysis {
     return this.#game
   }
 
+  /** The edge of the playing area. */
   get edge() {
     if (!this.#edge) {
       // Cache the edge
@@ -302,20 +344,12 @@ export class Analysis {
     return this.#edge
   }
 
-  /** Any faulty threats
-   * @returns {FaultyThreats}
-   */
-  get faulty() {
-    return this.#faulty
-  }
-
   /** All threats present in this position.
    * @returns {FoundThreatsCollection}
    */
   get threats() {
     if (!this.#threats) {
       this.#threats = { b: this.#applyThreats('b'), w: this.#applyThreats('w') }
-      if (!this.#partial) this.#validateThreats()
     }
 
     return this.#threats
@@ -383,7 +417,7 @@ export class Analysis {
     const attacking = activeAttack(inactive)
 
     // Was the inactive player unable to clear all threats?
-    const defending = !attacking && underAttack(active)
+    const defending = !attacking && underThreat(active)
 
     // Does the inactive player have multiple threats
     const threatening = !attacking && passiveAttack(inactive)
@@ -408,45 +442,56 @@ export class Analysis {
     return [score, multiplier]
   }
 
+  /** Calculate the score for a player.
+   * @arg {Color} color - Color of the player
+   * @returns number
+   */
   #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]
-      }
-
-      const [currentPlayer, threatLevel] = this.#activeScore()
-      const [nextPlayer, multiplier] = this.#inactiveScore(color, threatLevel)
+    const { game } = this
+    if (game.over) {
+      return game.color === color
+        ? Number.POSITIVE_INFINITY
+        : game.color === color
+        ? Number.NEGATIVE_INFINITY
+        : -100_000
+    }
 
-      let score = Math.floor(currentPlayer * multiplier) - nextPlayer
-      if (score && game.color !== color) score *= -1
+    const [currentPlayer, threatLevel] = this.#activeScore()
+    const [nextPlayer, multiplier] = this.#inactiveScore(color, threatLevel)
 
-      this.#scores[color] = score
-    }
+    let score = Math.floor(currentPlayer * multiplier) - nextPlayer
+    if (score && game.color !== color) score *= -1
 
-    return this.#scores[color]
+    return score
   }
 
+  /** Get the scores for each player. */
   get scores() {
-    return {
-      w: this.#score('w'),
-      b: this.#score('b'),
+    if (this.#scores === undefined) {
+      this.#scores = {
+        w: this.#score('w'),
+        b: this.#score('b'),
+      }
     }
+
+    return this.#scores
   }
 
+  /** Get the score for the active player. */
   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 = no tile can be played here
+  /** Determine which type of space we have:
+   *
+   * 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 = no tile can be played here
+   * @arg {Point} loc - The location of the space
+   * @returns string
+   */
   spaceType(loc) {
     const { game } = this
 
@@ -481,7 +526,7 @@ export class Analysis {
     return 'c'
   }
 
-  // Trace the edge of the playing area
+  /** Trace the edge of the playing area. */
   #traceEdge() {
     const { game } = this
     /** @type {RawEdge} */
@@ -559,15 +604,17 @@ export class Analysis {
    * @arg {string} color - the player color
    * @returns {Point[]} - locations relevant to the threat
    */
-  #threatLocs(threat, color) {
+  threatLocs(threat, color) {
     const { edge } = this.edge
     const max = edge.length
     let index = threat.at
+    let count = 0
     const locs = new Set([index])
-    while (threat.match.length > locs.size) {
+    while (count < threat.match.length) {
       index += 1
       if (index >= max) index -= max
       locs.add(index)
+      count += 1
       // Check to see if we have a connectable pair
       if (edge[index]['p' + color]) {
         const line = 'n' + color
@@ -583,16 +630,15 @@ export class Analysis {
       }
     }
 
-    const value = [...locs].map((i) => new Point(edge[i]))
-    return value
+    return [...locs].map((i) => new Point(edge[i] || { x: 0, y: 0 }))
   }
 
   /** Apply the threats to a color's regex-ready edge.
    * @arg {Color} color - the color to find threats for
-   * @returns {FoundThreats}
+   * @returns {ColorThreats}
    */
   #applyThreats(color) {
-    /** @type {FoundThreats} */
+    /** @type {ColorThreats} */
     const matches = {}
     const { length } = this.edge[color]
     const edge = this.edge[color].repeat(2)
@@ -614,10 +660,12 @@ export class Analysis {
   }
 
   /** Clean up the list of matches, removing any false positives. */
-  #validateThreats() {
+  validateThreats() {
+    if (this.#validated) return
+    let someFaulty = false
     for (const bw of ['w', 'b']) {
-      /** @type FoundThreats */
-      const matches = this.#threats[bw]
+      /** @type ColorThreats */
+      const matches = this.threats[bw]
       for (const key of Object.keys(matches)) {
         const level = Number(key)
         if (level < 2) continue
@@ -628,7 +676,8 @@ export class Analysis {
           if (this.#canActivateThreat(threat, bw, level)) {
             verified.push(threat)
           } else {
-            this.#faulty[bw].push(threat)
+            this.faulty[bw].push(threat)
+            someFaulty = true
           }
         }
 
@@ -639,6 +688,9 @@ export class Analysis {
         }
       }
     }
+
+    if (someFaulty) this.#scores = undefined
+    this.#validated = true
   }
 
   /** Determine if the given threat can be activated for this color
@@ -648,10 +700,12 @@ export class Analysis {
    * @returns {boolean}
    */
   #canActivateThreat(threat, color, level) {
-    const attacks = this.#threats[color][1]?.length ?? 0
-    const other = this.#threats[Trax.other(color)][1]?.length ?? 0
-    const higher = this.#threats[color][level - 1]?.length ?? 0
-    for (const loc of this.#threatLocs(threat, color)) {
+    const attacks = attackCount(this.threats[color])
+    const player = Trax.playerNumber(color)
+    const other = Trax.other(color)
+    const otherAttacks = attackCount(this.threats[other])
+    const higher = threatCount(this.threats[color], level - 1)
+    for (const loc of this.threatLocs(threat, color)) {
       for (const type of this.game.possibleTiles(loc)) {
         const game = new Trax(this.game.rules, this.game.moves)
         const result = game.dropTile(type, loc)
@@ -659,20 +713,23 @@ export class Analysis {
 
         // This might be a bad shortcut, but if we already have an attack here
         // we just assume that this threat is also valid ...
-        if (game.over && game.turn === Trax.playerNumber(color)) return true
+        if (game.over && game.turn === player) return true
+
+        // Otherwise, we cannot evaluate an ended game
+        if (game.over) continue
 
-        const { threats } = analyze(game, true)
+        const { threats } = analyze(game)
 
         // If we give our opponent an attack, this is a faulty move
-        const faulty = (threats[Trax.other(color)][1]?.length ?? 0) - other
+        const faulty = attackCount(threats[other]) - otherAttacks
         if (faulty > 0) continue
 
         // Activating the threat means we get an attack and a threat
-        const newAttacks = (threats[color][1]?.length ?? 0) - attacks
+        const newAttacks = attackCount(threats[color]) - attacks
         if (level === 2) {
           if (newAttacks > 1) return true
         } else {
-          const newThreats = (threats[color][level - 1]?.length ?? 0) - higher
+          const newThreats = threatCount(threats[color], level - 1) - higher
           if (newAttacks > 0 && newThreats > 0) return true
         }
       }
@@ -701,12 +758,12 @@ export class Analysis {
       custom += tbd
     }
 
+    const score = this.#scores ? this.score : null
     custom += ',\n  threats: '
     custom += this.#threats ? sub(this.#threats) : tbd
     custom += ',\n  scores: '
-    custom += 'w' in this.#scores ? sub(this.#scores) : tbd
+    custom += this.#scores ? sub(this.#scores) : tbd
     custom += ',\n  score: '
-    const score = 'w' in this.#scores ? this.score : null
     custom += score === null ? tbd : style(score, 'number')
 
     return custom + '\n}'
@@ -715,14 +772,13 @@ export class Analysis {
 
 /** Analyze a game position.
  * @arg {Trax} game - the position to analyze
- * @arg {boolean} partial - if the position should only be partially analyzed
  * @returns {Analysis}
  */
-export const analyze = (game, partial = false) => {
-  const id = (partial ? 'y' : 'n') + game.rules + game.normalized
+export const analyze = (game) => {
+  const id = game.rules + game.normalized
   const cached = cache.get(id)
   if (cached) return cached
-  const analysis = new Analysis(game, partial)
+  const analysis = new Analysis(game)
   cache.set(id, analysis)
   return analysis
 }
@@ -736,9 +792,23 @@ export class Suggestion {
   pick
   ms = 0
 
-  constructor(analyzed, ms) {
+  constructor(color, analyzed, ms) {
     this.all = analyzed.sort(byScoreDesc)
-    const best = analyzed[0] || { move: '', score: 0 }
+    let best = analyzed[0] || { move: '', score: 0 }
+    let score = Number.NEGATIVE_INFINITY
+
+    while (score !== best.score) {
+      score = best.score
+      const options = analyzed.filter(withinX(best.score, 5))
+      for (const option of options) {
+        option.analysis.validateThreats()
+        option.score = option.analysis.scores[color]
+      }
+
+      analyzed.sort(byScoreDesc)
+      best = analyzed[0] || { move: '', score: 0 }
+    }
+
     this.options = analyzed.filter(withinX(best.score, 5))
     this.pick = randomDraw(this.options) || best
     this.ms = ms
@@ -776,9 +846,13 @@ export const suggest = (game) => {
     const unique = trax.normalized
     if (!analyzed[unique]) {
       const analysis = analyze(trax)
-      analyzed[unique] = { move, score: analysis.scores[color], analysis }
+      analyzed[unique] = {
+        move,
+        analysis,
+        score: analysis.scores[color],
+      }
     }
   }
 
-  return new Suggestion(Object.values(analyzed), Date.now() - start)
+  return new Suggestion(color, Object.values(analyzed), Date.now() - start)
 }

package/src/cmds/import-export.js

@@ -248,7 +248,7 @@ const gameNotes = (move, notes) => {
   if (moveNotes.length === 0) return ''
   return (
     '; ' +
-    moveNotes.map((n) => n.note.replaceAll('\n', '\n; ')).join('\n; ') +
+    moveNotes.map((n) => n.note.replace(/\n/g, '\n; ')).join('\n; ') +
     '\n'
   )
 }
@@ -328,8 +328,15 @@ exportCmd.fn = (CLI, id, filename) => {
       const source = sources[puzzle.src]
       content += '; Puzzle ' + game.puzzle
       if (source) {
-        content += ' provided courtesy of ' + source.name
+        content += source.copyright
+          ? ' ©' + source.copyright + ' by '
+          : ' provided courtesy of '
+        content += source.name
         if (source.url) content += '\n; ' + source.url
+        if (source.license) {
+          content += '\n; Licensed under ' + source.license
+          content += source.licenseUrl ? ' ' + source.licenseUrl : ''
+        }
       }
 
       content += '\n'

package/src/cmds/notes.js

@@ -25,6 +25,9 @@ notesCmd.fn = (CLI, id, ...note) => {
   if (id.startsWith('#')) id = id.slice(1)
 
   const game = CLI.GAMES[id]
+
+  if (!game) return CLI.error('Game not found.')
+
   const notes = game.notes || []
   const move = game.moves.length > 0 ? game.moves.split(' ').length : 0
 

package/src/cmds/play-try.js

@@ -1,4 +1,4 @@
-/* Copyright 2022 Chad Transtrum
+/* Copyright 2022-2023 Chad Transtrum
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,6 +16,7 @@
 // CLI play/try commands
 
 import { suggest } from '@slugbugblue/trax/analyst'
+import { timeString } from '@slugbugblue/trax/utils'
 
 const moveRx = /^\d+\.?$/
 const notationRx = /^[@a-z]+\d+[bps/\\+]$/i
@@ -70,9 +71,14 @@ const bot = (CLI) => {
 
     CLI.do('view')
     CLI.out(CLI.bubble(trax.color + 'd', `${name} thinking...`))
+    const start = Date.now()
     const move = suggest(trax)?.pick?.move
+    const ms = Date.now() - start
     if (move) {
-      CLI.out(CLI.bubble(trax.color + 'd', `${name} chooses ${move}`))
+      CLI.out(
+        CLI.bubble(trax.color + 'd', `${name} chooses ${move}`) +
+          CLI.color.black(' in ' + timeString(ms)),
+      )
       trax.play(move)
     }
 

package/src/cmds/puzzles.js

@@ -1,5 +1,5 @@
 /** @file Puzzles CLI
- * @copyright 2022
+ * @copyright 2022-2023
  * @author Chad Transtrum <chad@transtrum.net>
  * @license Apache-2.0
  */
@@ -17,11 +17,14 @@ for (const puzzle of puzzles) {
 const validLevels = levels.slice(0, maxLevel + 1)
 const completions = [...validLevels, ...puzzleIds].join('|')
 
+const listAliases = ['display', 'list', 'ls', 'show', 'view']
+const startAliases = ['new', 'start']
+
 export const puzzlesCmd = {
   name: 'puzzles',
   args: '["list"|"start"] [level|puzzle]',
-  comp: 'list|ls|new|show|start|view ' + completions,
-  desc: 'play puzzles',
+  comp: 'display|list|ls|new|show|start|view ' + completions,
+  desc: 'view and play puzzles',
   help: [
     'Practice your skills with puzzles. Use "list" to see the puzzle',
     'categories, or "start" to play a puzzle.',
@@ -33,9 +36,15 @@ const an = (word = '') => {
   return a + ' ' + word
 }
 
-const showPuzzle = (CLI, id) => {
-  const puzzle = puzzles.find((p) => p.id === id)
+const showPuzzle = (CLI, id, started = false) => {
+  let puzzle = puzzles.find((p) => p.id === id)
+  if (!puzzle) {
+    const possibles = puzzles.filter((p) => p.id.includes(id))
+    if (possibles.length === 1) puzzle = possibles[0]
+  }
+
   if (!puzzle) return CLI.error(`Puzzle ${id} not found`)
+
   const trax = new Trax(puzzle.game, puzzle.notation, 'cli')
   const players = ['white', 'black']
   CLI.display(trax, players)
@@ -45,17 +54,30 @@ const showPuzzle = (CLI, id) => {
   if (puzzle.desc) out += CLI.color.help(puzzle.desc) + '\n'
   out += CLI.color(players[puzzle.player - 1] + ' to win by move ' + puzzle.max)
   const src = sources[puzzle.src]
+
   if (src) {
     let source = '\nPuzzle '
     source += src.copyright
       ? 'copyright ' + src.copyright + ' by'
       : 'courtesy of'
     source += ' ' + src.name
-    const url = src.url ? ' ' + CLI.color.white(src.url) : ''
-    out += CLI.color.black(source) + url
+    const url = src.url ? ' ' + CLI.color.help(src.url) : ''
+    out += CLI.color.white(source) + url
+    if (src.license) {
+      out += '\n' + CLI.color.optional('License: ' + src.license)
+      if (src.licenseUrl) out += CLI.color.black(' ' + src.licenseUrl)
+    }
   }
 
   CLI.out(out)
+
+  if (started) return
+
+  CLI.out(
+    CLI.color.short(
+      `Want to try this puzzle? Enter: "puzzles start ${puzzle.id}"`,
+    ),
+  )
 }
 
 const listPuzzles = (CLI) => {
@@ -115,7 +137,7 @@ const listLevel = (CLI, levelName) => {
 const startPuzzle = (CLI, puzzle) => {
   const id = CLI.newPuzzle(puzzle)
   CLI.out(CLI.color(`Started puzzle ${puzzle.id} as game #${id}`))
-  showPuzzle(CLI, puzzle.id)
+  showPuzzle(CLI, puzzle.id, true)
 }
 
 const startNextPuzzle = (CLI, level) => {
@@ -132,7 +154,7 @@ const startNextPuzzle = (CLI, level) => {
 
 puzzlesCmd.fn = (CLI, action, id) => {
   action = action?.toLowerCase() ?? 'list'
-  if ('start'.startsWith(action) || 'new'.startsWith(action)) {
+  if (startAliases.some((alias) => alias.startsWith(action))) {
     if (!id) return startNextPuzzle(CLI)
 
     const puzzle = puzzles.find((p) => p.id === id)
@@ -144,14 +166,22 @@ puzzlesCmd.fn = (CLI, action, id) => {
       return startNextPuzzle(CLI, levels.indexOf(id))
     }
 
-    return CLI.error('Could not start puzzle ' + id)
+    const possibles = puzzles.filter((p) => p.id.includes(id))
+    if (possibles.length === 1) {
+      return startPuzzle(CLI, possibles[0])
+    }
+
+    return CLI.error('Could not find puzzle ' + id)
   }
 
   if (action) {
     const x = id || action
     if (validLevels.includes(x)) return listLevel(CLI, x)
-    if (puzzleIds.includes(x)) return showPuzzle(CLI, x)
-    if (id) return CLI.error('Could not find puzzle ' + id)
+    if (listAliases.some((alias) => alias.startsWith(x))) {
+      return listPuzzles(CLI)
+    }
+
+    return showPuzzle(CLI, x)
   }
 
   listPuzzles(CLI)