@slugbugblue/trax 0.18.0 → 0.20.0

package/src/analyst.js

@@ -6,9 +6,12 @@
 
 import { Point } from '@slugbugblue/trax/point'
 import { Trax } from '@slugbugblue/trax'
+import { LRU } from '@slugbugblue/trax/lru'
 
 import { threats } from '@slugbugblue/trax/threats'
 
+const cache = new LRU(2750)
+
 /** Helper function to generate a unique id for the analysis. */
 const id = () => {
   const chars = 'abcdefghijklmnopqrstuvwxyz0123456789'
@@ -201,7 +204,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
@@ -214,16 +217,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
@@ -233,26 +243,32 @@ 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 {ColorThreats} from - the threats found for a player
+//  * @returns {boolean}
+//  */
+// const underAttack = (from) => attackCount(from) > 0
 
-/** Shortcut to determine if we are under attack.
- * @arg {FoundThreats} from - the threats found for a player
+/** 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
-export const Analysis = class {
+export class Analysis {
   /** @type {TraxVariant} */
   #rules = 'trax'
   #id = 'analysis'
@@ -279,6 +295,10 @@ export const Analysis = class {
       b: (level) => this.threats.b[level]?.length || 0,
     }
     this.#partial = Boolean(partial)
+    if (this.#moves.length === 0 || game.over) {
+      this.#edge = { b: '', w: '', rawEdge: [] }
+      this.#threats = { b: {}, w: {} }
+    }
   }
 
   get game() {
@@ -380,7 +400,7 @@ export const Analysis = class {
     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)
@@ -554,17 +574,19 @@ export const Analysis = class {
   /**
    * @arg {FoundThreat} threat - a threat
    * @arg {string} color - the player color
-   * @returns {InstanceType<typeof Point>[]} - locations relevant to the threat
+   * @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
@@ -580,16 +602,15 @@ export const Analysis = class {
       }
     }
 
-    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)
@@ -613,7 +634,7 @@ export const Analysis = class {
   /** Clean up the list of matches, removing any false positives. */
   #validateThreats() {
     for (const bw of ['w', 'b']) {
-      /** @type FoundThreats */
+      /** @type ColorThreats */
       const matches = this.#threats[bw]
       for (const key of Object.keys(matches)) {
         const level = Number(key)
@@ -645,10 +666,12 @@ export const Analysis = class {
    * @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)
@@ -656,20 +679,23 @@ export const Analysis = class {
 
         // 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
 
-        const { threats } = new Analysis(game, true)
+        // Otherwise, we cannot evaluate an ended game
+        if (game.over) continue
+
+        const { threats } = analyze(game, true)
 
         // 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
         }
       }
@@ -712,11 +738,19 @@ export const Analysis = class {
 
 /** 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) => new Analysis(game)
+export const analyze = (game, partial = false) => {
+  const id = (partial ? 'y' : 'n') + game.rules + game.normalized
+  const cached = cache.get(id)
+  if (cached) return cached
+  const analysis = new Analysis(game, partial)
+  cache.set(id, analysis)
+  return analysis
+}
 
-export const Suggestion = class {
+export class Suggestion {
   /** @type {PositionScore[]} */
   all = []
   /** @type {PositionScore[]} */
@@ -755,7 +789,7 @@ export const Suggestion = class {
   }
 }
 
-export const suggest = (game) => {
+export const suggest = (game, partial = false) => {
   const start = Date.now()
   const analyzed = {}
   const { color, moves, rules } = game
@@ -764,7 +798,7 @@ export const suggest = (game) => {
     trax.play(move)
     const unique = trax.normalized
     if (!analyzed[unique]) {
-      const analysis = analyze(trax)
+      const analysis = analyze(trax, partial)
       analyzed[unique] = { move, score: analysis.scores[color], analysis }
     }
   }

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
  */
@@ -34,8 +34,14 @@ const an = (word = '') => {
 }
 
 const showPuzzle = (CLI, id) => {
-  const puzzle = puzzles.find((p) => p.id === id)
+  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,14 +51,19 @@ 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)
@@ -144,14 +155,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 ('list'.startsWith(x) || 'ls'.startsWith(x)) {
+      return listPuzzles(CLI)
+    }
+
+    return showPuzzle(CLI, x)
   }
 
   listPuzzles(CLI)

package/src/cmds/suggest.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 suggest command
 
 import { suggest } from '@slugbugblue/trax/analyst'
+import { timeString } from '@slugbugblue/trax/utils'
 
 export const suggestCmd = {
   name: 'suggest',
@@ -47,6 +48,8 @@ suggestCmd.fn = (CLI, debug) => {
       m.push(move.move + ' ' + move.score)
     }
 
-    CLI.out('[' + m.join(', ') + '] ' + suggestion.ms + 'ms')
+    CLI.out(
+      '[' + m.join(', ') + '] ' + CLI.color.black(timeString(suggestion.ms)),
+    )
   }
 }

package/src/engine.js

@@ -127,7 +127,7 @@ const codeRowLength = (row) =>
 
 // This is where the magic happens
 /** A digital representation of a Trax game. */
-export const Trax = class {
+export class Trax {
   // Static class properties
 
   /** @readonly @type {Record<TraxVariant, string>} */

package/src/lru.js

@@ -0,0 +1,153 @@
+/** Least Recently Used cache
+ * @copyright 2023
+ * @author Chad Transtrum <chad@transtrum.net>
+ * @license Apache-2.0
+ */
+
+/** LRU cache: a class for remembering things. It uses a Map internally and
+ * exposes most of the same interface.
+ */
+export class LRU {
+  /** @type Map */
+  #cache
+  #capacity = 0
+  #hits = 0
+  #misses = 0
+  #expired = 0
+
+  /** Instantiate this class with the max number of cached items
+   * @arg {number} capacity - the maximum number of items to cache
+   */
+  constructor(capacity = 1000) {
+    this.#cache = new Map()
+    if (typeof capacity === 'number' && capacity >= 1) {
+      this.#capacity = Math.floor(capacity)
+    } else {
+      throw new SyntaxError('capacity must be a positive integer')
+    }
+  }
+
+  /** The maximum capacity. */
+  get capacity() {
+    return this.#capacity
+  }
+
+  /** The current size. */
+  get size() {
+    return this.#cache.size
+  }
+
+  /** Number of times we have had a cache hit. */
+  get hits() {
+    return this.#hits
+  }
+
+  /** Number of times we have had a cache miss. */
+  get misses() {
+    return this.#misses
+  }
+
+  /** Number of times we have expired a cache entry. */
+  get expired() {
+    return this.#expired
+  }
+
+  /** Retrieve an item from the cache.
+   * @arg {any} key - the key of the cached item
+   * @returns {any} - the cached item or undefined
+   */
+  get(key) {
+    if (this.#cache.has(key)) {
+      // Update the least recently used order
+      const value = this.#cache.get(key)
+      this.#cache.delete(key)
+      this.#cache.set(key, value)
+      this.#hits++
+    } else {
+      this.#misses++
+    }
+
+    return this.#cache.get(key)
+  }
+
+  /** Retrieve an item from the cache without triggering any LRU handling.
+   * @arg {any} key - the key of the cached item to retrieve
+   * @returns {any} - the cached item or undefined
+   */
+  peek(key) {
+    return this.#cache.get(key)
+  }
+
+  /** Store an item in the cache.
+   * @arg {any} key - the key of the cached item
+   * @arg {any} value - the value to store
+   */
+  set(key, value) {
+    // To update an item, remove and re-add it to track LRU status
+    this.#cache.delete(key)
+
+    // If there are too many items, expire one before adding more
+    if (this.#cache.size >= this.#capacity) {
+      this.#expired++
+      const [expire] = this.#cache[Symbol.iterator]().next().value
+      this.#cache.delete(expire)
+    }
+
+    this.#cache.set(key, value)
+  }
+
+  /** Delete an item from the cache.
+   * @arg {any} key - the key of the cached item
+   * @returns {boolean} true if the item was in the cache
+   */
+  delete(key) {
+    return this.#cache.delete(key)
+  }
+
+  /** Clear the cache and all its statistics. */
+  clear() {
+    this.#cache.clear()
+    this.#hits = 0
+    this.#misses = 0
+    this.#expired = 0
+  }
+
+  /** Get an iterator to return [key, value] pairs from the cache. Does not
+   * update any LRU information. */
+  entries() {
+    return this.#cache.entries()
+  }
+
+  /** Determine if a key is already in the cache. Does not trigger hit/miss.
+   * @arg {any} key - the key to check
+   * @returns {boolean} true if the key is in the cache
+   */
+  has(key) {
+    return this.#cache.has(key)
+  }
+
+  /** Get an iterator for the keys stored in cache, in order from least to most
+   * recent. Does not update any LRU information. */
+  keys() {
+    return this.#cache.keys()
+  }
+
+  /** Get an iterator for the values stored in cache, in order from least to
+   * most recent. Does not update any LRU information. */
+  values() {
+    return this.#cache.values()
+  }
+
+  // Play nicely with the rest of the world
+  toString() {
+    return `LRU(${this.#cache.size} of ${this.#capacity})`
+  }
+
+  [Symbol.for('nodejs.util.inspect.custom')](_, options) {
+    const [y, s, n] = [options.stylize, 'special', 'number']
+    return `${y('LRU', s)}(${y(this.#cache.size, n)} of ${y(
+      this.#capacity,
+      n,
+    )})`
+  }
+}

package/src/point.js

@@ -32,7 +32,7 @@ const between = (end1, mid, end2) => {
  * Point: an immutable two-dimensional location (x,y) with
  * functions for moving around quickly to neighboring points.
  */
-export const Point = class {
+export class Point {
   #x = 0
   #y = 0