@slugbugblue/trax 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @slugbugblue/trax
 
+## 0.13.0 - 2022-11-25
+
+- Add move suggestions to `analyst.js` for CLI and bot use
+
+  - use `suggest(trax)` to get a suggestion for the current position
+  - added the `suggest` CLI command for quick access to a random suggestion
+
+- Use font glyphs for text bubbles in `tty.js` only if one of the following
+  environment variables are defined and non-empty:
+
+  - `NERDFONT`, `POWERLINE`, `P9K_TTY`, `P9K_SSH`
+
+- Begin work on documenting the javascript files using jsdoc, with the initial
+  focus on types so typescript-powered autocomplete can be more useful
+
 ## 0.12.0 - 2022-10-28
 
 - `point.in()` now accepts any two opposing corners to define the bounding box

package/README.md

@@ -5,8 +5,8 @@ Trax game-playing engine and etc.
 ## Description
 
 Trax is a two-player boardless board game invented by David Smith. For more
-information about Trax, including its rules and history, see the official
-website at [traxgame.com][traxgame].
+information about Trax, including its [rules][traxrules] and
+[history][traxhistory], see the official website at [traxgame.com][traxgame].
 
 This goal of this javascript project is to allow Trax to be played
 programmatically. It can be used as an engine in a web browser, for example at
@@ -95,7 +95,9 @@ Examples:
 
 ## API Usage
 
-The main Trax engine is provided as `engine.js`, which can be used as follows:
+### Trax engine
+
+The main Trax engine is provided in `engine.js`, which can be used as follows:
 
 ```javascript
 import { Trax } from '@slugbugblue/trax'
@@ -115,12 +117,45 @@ let puzzle = new Trax('trax', '@0/ a0\\ @2/')
 puzzle.play('@2\\')
 ```
 
-For specifics, see the [engine.js documentation][engine-docs].
+For specifics, see the [engine.js documentation][docs-engine].
+
+### Analysis
+
+The analysis engine is provided in `analyst.js`, and it can be used as follows:
+
+```javascript
+import { Trax } from '@slugbugblue/trax'
+import { analyze } from '@slugbugblue/trax/analyst'
+
+let trax = new Trax('trax', '@0/ @1\\')
+
+let analysis = analyze(trax)
+
+console.log('Edge analysis:', analysis.edge)
+console.log('Threat analysis:', analysis.threats)
+console.log('Score analysis:', analysis.scores)
+```
+
+For additional information, refer to the [analyst.js
+documentation][docs-analyst].
+
+### Threats database
+
+The threats database is currently hand-coded in `threats.js`, so refer to that
+file if you want to try to update the analysis engine's understanding of
+threats.
+
+### Puzzles database
+
+The puzzles database is provided in `puzzles.js`, and so far just contains
+puzzles that I've been using to test the analysis engine, along with the list of
+publicly available puzzles at [the traxgame.com puzzles page][traxpuzzles].
 
 ## Roadmap
 
-- Game position analysis
-- Puzzles and Puzzlebot
+- Improve the threats database / analysis engine.
+- Add a puzzle interface to the CLI.
+- Add more puzzles.
 
 ## Support
 
@@ -174,12 +209,16 @@ David Smith and heirs, and are not to be used without permission.
 
 [ctrans]: mailto:chad@transtrum.net
 [dgb]: mailto:donald@traxgame.com
-[engine-docs]: docs/engine.md
+[docs-engine]: docs/engine.md
+[docs-analyst]: docs/analyst.md
 [env-path]: https://www.npmjs.com/package/env-paths
 [goldtoken]: https://goldtoken.com/
 [repo]: https://gitlab.com/slugbugblue/trax
 [sbb]: https://slugbugblue.com/
 [traxbook]: http://traxgame.com/shop_book.php
 [traxgame]: http://traxgame.com/
+[traxhistory]: http://www.traxgame.com/about_history.php
+[traxpuzzles]: http://www.traxgame.com/games_puzzles.php
+[traxrules]: http://www.traxgame.com/about_rules.php
 [xdg]:
   https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html

package/docs/analyst.md

@@ -7,7 +7,7 @@ CLI and for bots.
 
 ```javascript
 import { Trax } from '@slugbugblue/trax'
-import { analyze } from '@slugbugblue/trax/analyst'
+import { analyze, suggest } from '@slugbugblue/trax/analyst'
 
 const trax = new Trax('trax', '@0/ @1/ B0\\')
 
@@ -16,6 +16,12 @@ 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))
+
+const suggestion = suggest(trax)
+
+console.log(JSON.stringify(suggestion.options, null, 2))
+
+trax.play(suggestion.pick.move)
 ```
 
 ## API
@@ -107,7 +113,7 @@ 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
+- `threat`: 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.
@@ -144,6 +150,42 @@ For any given location, determine the type of playable space. Returns one of:
 - `C`: This location is in a cave, and certain plays at this position result in
   illegal moves.
 
+### Suggestion class
+
+Accessible from `suggest(game)`, this class is returned with several useful
+pieces of information.
+
+#### properties
+
+##### `all`
+
+A list of all the moves analyzed, ordered by highest scoring move first.
+
+Each move is an object with the following properties:
+
+- `move`: the notation of the move
+- `score`: the score of the move
+- `analysis`: the analysis object of the position for this move
+
+##### `options`
+
+A smaller subset of the `all` list, with only the moves that are worth
+considering.
+
+##### `pick`
+
+A random selection of one of the `options`.
+
+##### `ms`
+
+The number of milliseconds spent performing the analyses required to create the
+suggestion.
+
+#### computed properties
+
+- `best`: quick access to the top-scoring move
+- `analyzed`: quick access to a count of the number of moves analyzed
+
 ## License
 
 Copyright 2019-2022 Chad Transtrum

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slugbugblue/trax",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Trax game engine and friends",
   "keywords": [
     "trax",
@@ -11,16 +11,15 @@
   "bugs": "https://gitlab.com/slugbugblue/trax/issues",
   "license": "Apache-2.0",
   "author": "Chad Transtrum <chad@transtrum.net>",
+  "types": "./src/types.d.ts",
   "exports": {
     ".": "./src/engine.js",
-    "./analyst": "./src/analyst.js",
-    "./analyst.js": "./src/analyst.js",
     "./point": "./src/point.js",
-    "./point.js": "./src/point.js",
+    "./analyst": "./src/analyst.js",
+    "./puzzles": "./src/puzzles.js",
     "./threats": "./src/threats.js",
-    "./threats.js": "./src/threats.js",
     "./tty": "./src/tty.js",
-    "./tty.js": "./src/tty.js"
+    "./version": "./src/version.js"
   },
   "repository": "gitlab:slugbugblue/trax",
   "bin": {
@@ -38,7 +37,7 @@
     "yaml": "^2.0.0-11"
   },
   "devDependencies": {
-    "ava": "^4.1.0",
+    "ava": "^5.1.0",
     "c8": "^7.11.0",
     "genversion": "^3.0.2",
     "prettier": "^2.6.1",

package/src/analyst.js

@@ -15,10 +15,10 @@
 
 // Analyst module: provides analysis functions for Trax games
 
-import { Point } from '@slugbugblue/trax/point.js'
+import { Point } from '@slugbugblue/trax/point'
 import { Trax } from '@slugbugblue/trax'
 
-import { threats } from '@slugbugblue/trax/threats.js'
+import { threats } from '@slugbugblue/trax/threats'
 
 // Helpers
 const id = () => {
@@ -31,7 +31,17 @@ const id = () => {
   return 'analysis-' + code
 }
 
-// Make parseInt Array.map()-friendly
+// A sort function for hashes with a numeric score property
+const byScoreDesc = (a, b) => b.score - a.score
+
+// A filter function factory to remove scores not within x points of the highest score
+const withinX = (highest, tolerance) => (s) =>
+  s.score === highest || highest - s.score <= tolerance
+
+// Return a random element of an array
+const randomDraw = (array) => array[Math.floor(Math.random() * array.length)]
+
+// Make parseInt a little shorter
 const int = (s) => Number.parseInt(s, 10)
 
 const leftTurn = { d: 'r', l: 'd', r: 'u', u: 'l' }
@@ -160,18 +170,41 @@ 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
+}
+
 const attackScore = (from, level) => {
-  const count = from[level]?.length ?? 0
+  const count = threatValues(from[level] || [])
   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
+// Shortcut to get the number of attacks
+const attackCount = (from) => threatValues(from['1'] || [])
+
+// Shortcut to get the number of passive threats
+const threatCount = (from) => {
+  let count = 0
+  for (const [depth, array] of Object.entries(from)) {
+    count += int(depth) > 1 ? threatValues(array) : 0
+  }
+
+  return count
+}
+
+const passiveAttack = (from) =>
+  attackCount(from) > 1 || (attackCount(from) === 1 && threatCount(from) > 0)
+
+const underAttack = (from) => attackCount(from) + threatCount(from) > 0
 
 // Analysis class
 export const Analysis = class {
+  /** @type TraxVariant */
   #rules = 'trax'
   #id = 'analysis'
   #moves = []
@@ -255,17 +288,14 @@ export const Analysis = class {
       const inactive = this.threats[Trax.other(game.color)]
       let advantage = Number.POSITIVE_INFINITY
 
-      // First examine the player who has the initiative
+      // 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 ||
-        threatCount(this.threats[color]) > 1 ||
-        threatCount(this.threats[Trax.other(color)]) > 0
+      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))) {
@@ -406,6 +436,7 @@ export const Analysis = class {
             threat: threat.pattern,
             match: match[0],
             at: match.index,
+            value: threat.value,
           })
         }
       }
@@ -449,3 +480,56 @@ export const Analysis = class {
 }
 
 export const analyze = (game) => new Analysis(game)
+
+export const Suggestion = class {
+  all = []
+  options = []
+  pick = {}
+  ms = 0
+
+  constructor(analyzed, ms) {
+    this.all = analyzed.sort(byScoreDesc)
+    const best = analyzed[0] || { move: '', score: 0 }
+    this.options = analyzed.filter(withinX(best.score, 5))
+    this.pick = randomDraw(this.options) || best
+    this.ms = ms
+  }
+
+  get best() {
+    return this.all[0]
+  }
+
+  get analyzed() {
+    return this.all.length
+  }
+
+  // Make a nice representation for the nodejs REPL
+  [Symbol.for('nodejs.util.inspect.custom')](_, options) {
+    const style = options.stylize
+    let out = style(this.pick.move, 'string')
+    out += ' ' + style(this.pick.score, 'number') + ' ['
+    out += this.options
+      .slice(0, 5)
+      .map((s) => style(s.move, 'string') + ' ' + style(s.score, 'number'))
+      .join(', ')
+    out += '] ' + this.analyzed + ' in ' + this.ms + 'ms'
+    return out
+  }
+}
+
+export const suggest = (game) => {
+  const start = Date.now()
+  const analyzed = {}
+  const { color, moves, rules } = game
+  for (const move of game.possibleMoves()) {
+    const trax = new Trax(rules, moves)
+    trax.play(move)
+    const unique = trax.normalized
+    if (!analyzed[unique]) {
+      const analysis = analyze(trax)
+      analyzed[unique] = { move, score: analysis.scores[color], analysis }
+    }
+  }
+
+  return new Suggestion(Object.values(analyzed), Date.now() - start)
+}

package/src/cli.js

@@ -21,9 +21,9 @@ import repl from 'node:repl'
 
 import YAML from 'yaml'
 
-import { Trax } from './engine.js'
-import { version } from './version.js'
-import * as tty from './tty.js'
+import { Trax } from '@slugbugblue/trax'
+import { version } from '@slugbugblue/trax/version'
+import * as tty from '@slugbugblue/trax/tty'
 
 // Load all the commands as individual plugins
 import { analyzeCmd } from './cmds/analyze.js'
@@ -40,6 +40,7 @@ import { listCmd } from './cmds/list.js'
 import { newCmd } from './cmds/new.js'
 import { playCmd, tryCmd } from './cmds/play-try.js'
 import { selectCmd } from './cmds/select.js'
+import { suggestCmd } from './cmds/suggest.js'
 import { undoCmd } from './cmds/undo.js'
 import { viewCmd } from './cmds/view.js'
 
@@ -88,6 +89,7 @@ const plugins = [
   playCmd,
   quitCmd,
   selectCmd,
+  suggestCmd,
   tryCmd,
   undoCmd,
   versionCmd,
@@ -111,7 +113,10 @@ const newId = (DATA) => {
   return String(min - 1)
 }
 
-// Colorize text according to simplistic and not very complete patterns
+/** Colorize text according to simplistic and not very complete patterns.
+ * @type Colorer
+ */
+// @ts-ignore
 const color = (text, def) => {
   let out = ''
   let quote = false
@@ -121,7 +126,7 @@ const color = (text, def) => {
   const short = (t) => tty.color(t, CLI.COLORS.short) + c()
   for (const char of text) {
     switch (char) {
-      case '"':
+      case '"': {
         if (quote) {
           colors.pop()
         } else {
@@ -131,31 +136,45 @@ const color = (text, def) => {
         out += c('')
         quote = !quote
         break
-      case '#':
+      }
+
+      case '#': {
         id = true
         colors.push(CLI.COLORS.id)
         out += c('#')
         break
-      case '|':
+      }
+
+      case '|': {
         out += short('|')
         break
-      case '[':
+      }
+
+      case '[': {
         colors.push(CLI.COLORS.optional)
         out += short('[')
         break
-      case ']':
+      }
+
+      case ']': {
         colors.pop()
         out += short(']')
         break
-      case '<':
+      }
+
+      case '<': {
         colors.push(CLI.COLORS.variable)
         out += c('')
         break
-      case '>':
+      }
+
+      case '>': {
         colors.pop()
         out += c('')
         break
-      default:
+      }
+
+      default: {
         if (id && !/[\da-z]/.test(char)) {
           id = false
           colors.pop()
@@ -163,6 +182,7 @@ const color = (text, def) => {
         } else {
           out += char
         }
+      }
     }
   }
 
@@ -170,7 +190,7 @@ const color = (text, def) => {
 }
 
 // Internal representations of files
-const CONFIG = { id: 0 }
+const CONFIG = { id: '' }
 const DATA = { games: {} }
 
 // CLI context object for plugins
@@ -550,11 +570,34 @@ const completer = (line) => {
   return [completions, match]
 }
 
+const ambiguousSuggestions = (cmd) => {
+  const maybe = new Set()
+  for (const alias of cmd) {
+    if (alias.startsWith(CLI.CMD)) maybe.add(alias)
+
+    let alts = commands[alias].alt
+    alts = is(alts, 'arr') ? alts : [alts || '']
+
+    for (const alt of alts) {
+      if (alt.startsWith(CLI.CMD)) maybe.add(alt)
+    }
+  }
+
+  return maybe
+}
+
 const evaluate = async (command) => {
   const [CMD, ...words] = command.split(/\s+/).filter(Boolean)
-  const cmdLower = CMD.toLowerCase()
+  const cmdLower = CMD?.toLowerCase() || ''
   CLI.CMD = cmdLower
-  const cmd = abbreviations[cmdLower]
+  let cmd = abbreviations[cmdLower]
+
+  // If we are not in a REPL, let's remove hidden commands
+  if (!CLI.repl && is(cmd, 'arr')) {
+    cmd = cmd.filter((c) => !commands[c].hide)
+    if (cmd.length === 1) cmd = cmd[0]
+  }
+
   if (is(cmd, 'str')) {
     if (words.length > 0 && abbreviations[words[0].toLowerCase()] === 'help') {
       commands.help.fn(CLI, cmd)
@@ -563,18 +606,7 @@ const evaluate = async (command) => {
     }
   } else if (is(cmd, 'arr')) {
     CLI.error('Ambiguous command. Perhaps you meant one of the following:')
-    const maybe = new Set()
-
-    for (const alias of cmd) {
-      if (alias.startsWith(cmdLower)) maybe.add(alias)
-
-      let alts = commands[alias].alt
-      alts = is(alts, 'arr') ? alts : [alts || '']
-
-      for (const alt of alts) {
-        if (alt.startsWith(cmdLower)) maybe.add(alt)
-      }
-    }
+    const maybe = ambiguousSuggestions(cmd)
 
     if (maybe.size > 0) {
       for (const alias of [...maybe].sort()) {
@@ -593,8 +625,6 @@ const evaluate = async (command) => {
       CLI.error('Unknown command. Type "help" for a list of valid commands.')
     }
   }
-
-  return undefined
 }
 
 const main = async () => {
@@ -630,4 +660,4 @@ const main = async () => {
   }
 }
 
-main()
+await main()

package/src/cmds/analyze.js

@@ -15,8 +15,8 @@
 
 // CLI analyze command
 
-import { analyze } from '../analyst.js'
-import { Trax } from '../engine.js'
+import { analyze } from '@slugbugblue/trax/analyst'
+import { Trax } from '@slugbugblue/trax'
 
 const notationRx = /^[@a-z]+\d+[bps/\\+]$/i
 

package/src/cmds/import-export.js

@@ -21,7 +21,7 @@ import process from 'node:process'
 import envPaths from 'env-paths'
 import makeDir from 'make-dir'
 
-import { Trax } from '../engine.js'
+import { Trax } from '@slugbugblue/trax'
 
 const paths = envPaths('trax', { suffix: '' })
 const PATHS = {}

package/src/cmds/list.js

@@ -15,7 +15,7 @@
 
 // CLI list command
 
-import { Trax } from '../engine.js'
+import { Trax } from '@slugbugblue/trax'
 
 export const listCmd = {
   name: 'list',
@@ -41,7 +41,7 @@ export const listCmd = {
 }
 
 const plural = (n, noun, nouns) =>
-  n + ' ' + (Math.abs(n) === 1 ? noun : nouns ? nouns : noun + 's')
+  n + ' ' + (Math.abs(n) === 1 ? noun : nouns || noun + 's')
 
 const alphaSort = (a, b) => {
   a = String(a).toLowerCase()

package/src/cmds/new.js

@@ -58,13 +58,13 @@ const pairs = [
   ['Mario', 'Luigi'],
   ['Marlin', 'Dory'],
   ['Mary-Kate', 'Ashley'],
-  ['Micky', 'Minnie'],
+  ['Mickey', 'Minnie'],
   ['Miss Piggy', 'Kermit'],
   ['Mork', 'Mindy'],
   ['Obi-Wan', 'Anakin'],
   ['Pan', 'Hook'],
   ['Phineas', 'Ferb'],
-  ['Player 1', 'Player 2'],
+  ['player 1', 'player 2'],
   ['p1', 'p2'],
   ['R2-D2', 'C-3PO'],
   ['Ren', 'Stimpy'],
@@ -89,7 +89,9 @@ const pairs = [
 ]
 
 const pairUp = () => {
-  return pairs[Math.floor(Math.random() * pairs.length)]
+  const duo = pairs[Math.floor(Math.random() * pairs.length)]
+  if (duo[0].toLowerCase() !== duo[0] && Math.random() < 0.5) duo.reverse()
+  return duo
 }
 
 newCmd.fn = (CLI, variant, ...names) => {

package/src/cmds/suggest.js

@@ -0,0 +1,52 @@
+/* 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 suggest command
+
+import { suggest } from '@slugbugblue/trax/analyst'
+
+export const suggestCmd = {
+  name: 'suggest',
+  alt: ['bot'],
+  desc: 'suggest a move',
+  help: ['Suggest a move in the current game.'],
+}
+
+suggestCmd.fn = (CLI, debug) => {
+  if (!String(CLI.GAME?.id)) {
+    return CLI.error('No active game. Type "new" to start a game.')
+  }
+
+  const game = CLI.TRAX
+  const suggestion = suggest(game)
+
+  if (!suggestion.best) return
+
+  CLI.out(
+    CLI.bubble(
+      game.turn === '1' ? 'wh' : 'bh',
+      String(game.move + 1) + '. ' + suggestion.pick.move,
+    ),
+  )
+
+  if ('debug'.startsWith(debug)) {
+    const m = []
+    for (const move of suggestion.options) {
+      m.push(move.move + ' ' + move.score)
+    }
+
+    CLI.out('[' + m.join(', ') + '] ' + suggestion.ms + 'ms')
+  }
+}