@slugbugblue/trax 0.17.0 → 0.19.0

package/src/analyst.js

@@ -1,14 +1,17 @@
 /** Analyst module: provides analysis functions for Trax games.
- * @copyright 2022
+ * @copyright 2022-2023
  * @author Chad Transtrum <chad@transtrum.net>
  * @license Apache-2.0
  */
 
 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'
@@ -170,6 +173,7 @@ const pairUp = (rawEdge) => {
  */
 const label = (rawEdge) => {
   const final = { w: '', b: '', edge: rawEdge }
+  let index = 0
   for (const space of rawEdge) {
     for (const bw of ['b', 'w']) {
       const colors = new Set([bw, 'l'])
@@ -186,6 +190,9 @@ const label = (rawEdge) => {
       space['z' + bw] = z
       final[bw] += z
     }
+
+    space.idx = index
+    index += 1
   }
 
   return final
@@ -248,7 +255,7 @@ const passiveAttack = (from) => threatCount(from) > 1
 const underAttack = (from) => attackCount(from) + threatCount(from) > 0
 
 // Analysis class
-export const Analysis = class {
+export class Analysis {
   /** @type {TraxVariant} */
   #rules = 'trax'
   #id = 'analysis'
@@ -260,14 +267,21 @@ export const Analysis = class {
   #game
   #scores = {}
   #threats = undefined
+  #faulty = { b: [], w: [] }
+  #partial = false
 
-  constructor(game) {
+  constructor(game, partial = false) {
     // Make a copy of the game
     this.#rules = game.rules
     this.#moves = game.moves
     this.#id = id()
     this.#notation = game.notation
     this.#game = new Trax(this.#rules, this.#moves, this.#id)
+    this.count = {
+      w: (level) => this.threats.w[level]?.length || 0,
+      b: (level) => this.threats.b[level]?.length || 0,
+    }
+    this.#partial = Boolean(partial)
   }
 
   get game() {
@@ -288,12 +302,20 @@ export const Analysis = class {
     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
@@ -528,9 +550,43 @@ export const Analysis = class {
       match: match[1], // The match is in the capturing group
       at: match.index,
       value: threat.value,
+      level: threat.depth,
     }
   }
 
+  /**
+   * @arg {FoundThreat} threat - a threat
+   * @arg {string} color - the player color
+   * @returns {Point[]} - locations relevant to the threat
+   */
+  #threatLocs(threat, color) {
+    const { edge } = this.edge
+    const max = edge.length
+    let index = threat.at
+    const locs = new Set([index])
+    while (threat.match.length > locs.size) {
+      index += 1
+      if (index >= max) index -= max
+      locs.add(index)
+      // Check to see if we have a connectable pair
+      if (edge[index]['p' + color]) {
+        const line = 'n' + color
+        const end = edge.find(
+          (space) =>
+            space.idx !== edge[index].idx && space[line] === edge[index][line],
+        )
+        if (end) {
+          // Add the opposite end and the space right before it, just in case
+          locs.add(end.idx)
+          locs.add(end.idx - 1)
+        }
+      }
+    }
+
+    const value = [...locs].map((i) => new Point(edge[i]))
+    return value
+  }
+
   /** Apply the threats to a color's regex-ready edge.
    * @arg {Color} color - the color to find threats for
    * @returns {FoundThreats}
@@ -544,11 +600,10 @@ export const Analysis = class {
       const find = matches[threat.depth] || []
       for (const match of edge.matchAll(threat.rx)) {
         if (match.index >= length) break
+
+        // Avoid saving duplicates
         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))
         }
       }
 
@@ -558,6 +613,74 @@ export const Analysis = class {
     return matches
   }
 
+  /** Clean up the list of matches, removing any false positives. */
+  #validateThreats() {
+    for (const bw of ['w', 'b']) {
+      /** @type FoundThreats */
+      const matches = this.#threats[bw]
+      for (const key of Object.keys(matches)) {
+        const level = Number(key)
+        if (level < 2) continue
+        /** @type {FoundThreat[]} */
+        const verified = []
+        const threats = matches[key]
+        for (const threat of threats) {
+          if (this.#canActivateThreat(threat, bw, level)) {
+            verified.push(threat)
+          } else {
+            this.#faulty[bw].push(threat)
+          }
+        }
+
+        if (verified.length > 0) {
+          matches[key] = verified
+        } else {
+          delete matches[key]
+        }
+      }
+    }
+  }
+
+  /** Determine if the given threat can be activated for this color
+   * @param {FoundThreat} threat - The threat to try to activate
+   * @param {string} color - The color this match belongs to
+   * @param {number} level - The depth level of this threat
+   * @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)) {
+      for (const type of this.game.possibleTiles(loc)) {
+        const game = new Trax(this.game.rules, this.game.moves)
+        const result = game.dropTile(type, loc)
+        if (!result.valid) continue
+
+        // 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
+
+        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
+        if (faulty > 0) continue
+
+        // Activating the threat means we get an attack and a threat
+        const newAttacks = (threats[color][1]?.length ?? 0) - attacks
+        if (level === 2) {
+          if (newAttacks > 1) return true
+        } else {
+          const newThreats = (threats[color][level - 1]?.length ?? 0) - higher
+          if (newAttacks > 0 && newThreats > 0) return true
+        }
+      }
+    }
+
+    return false
+  }
+
   // Make a reasonable inspect representation of the analysis
   [Symbol.for('nodejs.util.inspect.custom')](depth, options, inspect) {
     const sub = (object) => inspect(object, options).replace(/\n/g, '\n  ')
@@ -592,11 +715,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[]} */

package/src/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-/* 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.
@@ -326,6 +326,14 @@ const CLI = {
     const id = newId(DATA)
     const trax = new Trax(puzzle.game, puzzle.notation, 'cli')
     const players = ['challenger', 'puzzlebot']
+    const notes = []
+    if (puzzle.title) notes.push({ move: 0, note: puzzle.title })
+    if (puzzle.desc) notes.push({ move: 0, note: puzzle.desc })
+    const player = [0, 'white', 'black'][puzzle.player]
+    notes.push(
+      { move: 0, note: 'Starting position ' + puzzle.notation },
+      { move: 0, note: `${puzzle.id}: ${player} to win by move ${puzzle.max}` },
+    )
     DATA.games[id] = {
       id,
       puzzle: puzzle.id,
@@ -335,6 +343,7 @@ const CLI = {
       max: puzzle.max,
       players: trax.turn === 1 ? players : players.reverse(),
       moves: trax.moves.join(' '),
+      notes,
     }
 
     if (DATA.puzzles[puzzle.id]) {

package/src/cmds/analyze.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.
@@ -54,6 +54,17 @@ const listThreats = (threats, detailed) => {
   return summary.join('  ')
 }
 
+const listFaulty = (faulty) => {
+  const summary = []
+  for (const threat of faulty) {
+    summary.push(
+      `[L${threat.level} ${threat.at}:${threat.threat}:${threat.match}]`,
+    )
+  }
+
+  return 'Faulty: ' + summary.join(' ')
+}
+
 analyzeCmd.fn = (CLI, move) => {
   if (!String(CLI.GAME?.id)) {
     return CLI.error('No active game. Type "new" to start a game.')
@@ -75,18 +86,27 @@ analyzeCmd.fn = (CLI, move) => {
     return CLI.error('Game has ended.')
   }
 
-  const { edge, threats, scores } = analyze(trax)
+  const { edge, threats, scores, faulty } = analyze(trax)
 
-  if (detailed) CLI.out(edge.w)
+  if (detailed) CLI.out(CLI.color.white(edge.w))
   CLI.out(
     CLI.bubble('w', scores.w) +
       CLI.color.white(' ') +
       listThreats(threats.w, detailed),
   )
-  if (detailed) CLI.out(edge.b)
+
+  if (detailed) {
+    if (faulty.w.length > 0) CLI.out(CLI.color.white('') + listFaulty(faulty.w))
+    CLI.out(CLI.color.black(edge.b))
+  }
+
   CLI.out(
     CLI.bubble('b', scores.b) +
       CLI.color.black(' ') +
       listThreats(threats.b, detailed),
   )
+
+  if (detailed && faulty.b.length > 0) {
+    CLI.out(CLI.color.black('') + listFaulty(faulty.b))
+  }
 }

package/src/cmds/import-export.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.
@@ -332,12 +332,7 @@ exportCmd.fn = (CLI, id, filename) => {
         if (source.url) content += '\n; ' + 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 += '\n'
     }
   }
 

package/src/cmds/view.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.
@@ -53,6 +53,9 @@ viewCmd.fn = (CLI, move) => {
       CLI.bubble('b' + (trax.turn === 2 ? 'h' : ''), players[1]),
   )
   CLI.display(trax, players, undefined, show)
-  if (puzzle) CLI.out(CLI.color('Puzzle ' + puzzle))
+  if (puzzle && (!note || !note.includes(puzzle))) {
+    CLI.out(CLI.color('Puzzle ' + puzzle))
+  }
+
   if (note) CLI.out(CLI.color.help(note))
 }

package/src/engine.js

@@ -33,6 +33,13 @@ const notationRegex = /^([@a-z]+)(\d+)([/\\+])$/i
 const tileTypes = ['a', 'b', 'c', 'd', 'e', 'f']
 
 /** Tiles are represented by the letters a-f.
+ *     a         b        c        d        e        f
+ *  +--#--+   +--#--+  +--#--+  +--o--+  +--o--+  +--o--+
+ *  |   # |   |  #  |  | #   |  | o   |  |  o  |  |   o |
+ *  oo   ##   ooo#ooo  ##   oo  oo   ##  #######  ##   oo
+ *  | o   |   |  #  |  |   o |  |   # |  |  o  |  | #   |
+ *  +--o--+   +--#--+  +--o--+  +--#--+  +--o--+  +--#--+
+ *
  * Slashes are represented by / \ or +.
  * @readonly
  * @type {Record<ValidTiles, Slash>}
@@ -120,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