@slugbugblue/trax 0.20.0 → 0.22.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @slugbugblue/trax
 
+## 0.22.0 - 2023-03-25
+
+- Pull point.js into its own package: `@slugbugblue/point`
+- Pull lru.js into its own package: `@slugbugblue/lru`
+- Pull puzzles.js into its own package: `@slugbugblue/trax-puzzles`
+- Pull tty.js into its own package: `@slugbugblue/trax-tty`
+- Pull analyst.js into its own package: `@slugbugblue/trax-analyst`
+- Pull cli.js into its own package: `@slugbugblue/trax-cli`
+
+## 0.21.0 - 2023-03-12
+
+- Update the analysis engine to be more lazy
+
+  - The LRU cache is more likely to have a hit because it no longer separates
+    validated from unvalidated analyses
+  - Suggestions are much faster because it now skips validations for low-scoring
+    moves
+  - You will now need to call `validateThreats()` to remove faulty threats
+    manually
+
 ## 0.20.0 - 2023-02-11
 
 - Provide timing feedback on the puzzlebot's actions

package/README.md

@@ -1,11 +1,6 @@
 # Trax
 
-This project aims to provide tools for working with Trax games in Javascript.
-
-- Trax game-playing engine
-- Position analysis engine
-- Over 100 puzzles to help hone your Trax skills
-- Command-line interface for ease of use
+This project provides the ability to work with Trax games in Javascript.
 
 ## Description
 
@@ -15,111 +10,15 @@ information about Trax, including its [rules][traxrules] and
 
 The 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
-[slugbugblue.com][sbb]; or in nodejs, for example by using the `trax` CLI
-provided as part of this project.
+[slugbugblue.com][sbb]; or in nodejs, for example by using the [trax
+CLI][trax-cli] provided as a child of this project.
 
 The Trax engine now enjoys automated testing with 100% code coverage. Any future
-changes to the engine should meet the same standard.
-
-## Installation
-
-```bash
-# Install into a javascript project
-npm install @slugbugblue/trax
-
-# Or install globally to use the trax CLI more easily
-npm install -g @slugbugblue/trax
-
-# Or create a docker image
-docker build -t trax .
-```
-
-## CLI Usage
-
-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.
-
-> If you installed by creating a Docker image, use the following command to
-> launch the CLI:
->
-> - `docker run --name trax -itv $HOME/trax:/mnt/data --rm trax`
->
-> Since that's a bit much to type, it's recommended to create an alias in one of
-> your startup scripts:
->
-> - `alias trax="docker run --name trax -itv $HOME/trax:/mnt/data --rm trax"`
->
-> Then you can launch the docker container simply by typing in `trax`, the same
-> as if it were installed globally.
-
-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` (or `npx trax help` with a local installation, or simply `help` if
-run interactively) to see a list of the available commands, and `trax help play`
-to see information about the `play` command. Aliases and abbreviations are
-provided to minimize typing and to try to avoid the requirement of memorizing
-the commands. For example, the `list` command has an alias of `ls`, and the
-`select` command can be activated using `#`.
-
-When you first launch the CLI, you can create a new game using the `new`
-command, and then enter moves for that game using `play`. Since `play` is likely
-to be the most common command used, you can simply omit the command name. For
-example, at the interactive prompt, entering `@0/` is the same as if you had
-entered `play 1. @0/`.
-
-Multiple games can be started at once, and the CLI will remember the currently
-active game and apply future actions to that game. Each game will retain its
-`#id` number until it is deleted, and you can use that number to switch between
-games. For example, to make game #1 active, enter `select 1` or `select #1` or
-simply `#1` at the interactive prompt.
-
-For ease of working at the command line, the symbols used as the last character
-of the Trax notation can optionally be replaced with letters. Use `s` for slash
-symbol (`/`), `b` for backslash (`\`), and `p` for plus (`+`). While there is no
-need to escape at the interactive prompt, these substitutions will be avilable
-there as well.
-
-The CLI uses standard Windows and Linux [XDG][xdg] file locations as provided by
-the [env-paths library][env-path], with current uses being the `config` and
-`data` folders.
-
-Examples:
-
-```text
-# Start a new Trax game with Chad playing as white
-> trax new Chad vs
-
-# Start a new Loop Trax game with Chad playing as black
-> trax new loop vs Chad
-
-# Start a new 8x8 Trax game with Chad as white and Another Player as black
-> trax new 8x8 Chad vs Another Player
-
-# Switch back to the first game. Note the quoting required at the command line.
-# This would not be necessary when running at the interactive prompt.
-> trax '#1'
-
-# Play two moves, using full notation
-> trax play 1. @0/ 2. A0/
-
-# Two more moves, using short notation and symbol substitution
-# B2/ => b2s and A0\ => a0b
-> trax b2s a0b
-
-# See the status of all games
-> trax ls
-```
+changes should meet the same standard.
 
 ## API Usage
 
-### Trax engine
-
-The main Trax engine is provided in `engine.js`, which can be used as follows:
+The Trax engine can be used as follows:
 
 ```javascript
 import { Trax } from '@slugbugblue/trax'
@@ -139,47 +38,7 @@ let puzzle = new Trax('trax', '@0/ a0\\ @2/')
 puzzle.play('@2\\')
 ```
 
-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 contains puzzles that I've
-been using to test the analysis engine, publicly available puzzles from [the
-traxgame.com puzzles page][traxpuzzles], and [puzzles curated][puzzlebook] by
-[Martin M. S. Pedersen][traxplayer].
-
-## Roadmap
-
-- Improve the threats database / analysis engine.
-  - Bot should be able to win all puzzles.
-  - Analysis should recognize line threats.
-- Add more puzzles.
+For specifics, see the [engine.js documentation][docs].
 
 ## Support
 
@@ -208,7 +67,7 @@ infinite patience in indulging my many questions can never be repaid.
 
 Thanks to [Martin M. S. Pedersen][traxplayer] for contributing ideas, code, and
 puzzles. He's been [curating Trax puzzles][puzzlebook] and [coding solutions for
-Trax][gnutrax] for over two decades, and brings a lot of expertise.
+Trax][gnutrax] for over two decades, and has a lot of expertise in this area.
 
 ## License
 
@@ -238,19 +97,15 @@ David Smith and heirs, and are not to be used without permission.
 [contributing]: CONTRIBUTING.md
 [ctrans]: mailto:chad@transtrum.net
 [dgb]: mailto:donald@traxgame.com
-[docs-engine]: docs/engine.md
-[docs-analyst]: docs/analyst.md
-[env-path]: https://www.npmjs.com/package/env-paths
+[docs]: docs/engine.md
 [gnutrax]: https://gnutrax.com
 [goldtoken]: https://goldtoken.com/
 [puzzlebook]: https://gnutrax.com/book
 [repo]: https://gitlab.com/slugbugblue/trax
 [sbb]: https://slugbugblue.com/
+[trax-cli]: https://gitlab.com/slugbugblue/trax-cli
 [traxbook]: http://traxgame.com/shop_book.php
 [traxgame]: http://traxgame.com/
 [traxhistory]: http://www.traxgame.com/about_history.php
 [traxplayer]: mailto:traxplayer@gmail.com
-[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/engine.md

@@ -427,4 +427,4 @@ 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.
 
-[point-docs]: point.md
+[point-docs]: https://gitlab.com/slugbugblue/point

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@slugbugblue/trax",
-  "version": "0.20.0",
-  "description": "Trax game engine and friends",
+  "version": "0.22.0",
+  "description": "Trax game engine",
   "keywords": [
     "trax",
     "traxgame",
@@ -14,33 +14,22 @@
   "types": "./src/types.d.ts",
   "exports": {
     ".": "./src/engine.js",
-    "./analyst": "./src/analyst.js",
-    "./lru": "./src/lru.js",
-    "./point": "./src/point.js",
-    "./puzzles": "./src/puzzles.js",
-    "./threats": "./src/threats.js",
-    "./tty": "./src/tty.js",
-    "./utils": "./src/utils.js",
-    "./version": "./src/version.js"
+    "./version": "./src/version.js",
+    "./version.js": "./src/version.js"
   },
   "repository": "gitlab:slugbugblue/trax",
-  "bin": {
-    "trax": "./src/cli.js"
-  },
   "scripts": {
-    "benchmark": "node benchmark/puzzles.bench.js",
     "genversion": "genversion --es6 src/version.js",
-    "git-add": "git add src/version.js benchmark/benchmarks.json",
+    "git-add": "git add src/version.js",
     "test": "xo && c8 ava",
     "prepare": "husky install",
     "preversion": "npm test",
-    "version": "npm run genversion ; npm run benchmark ; npm run git-add",
+    "version": "npm run genversion ; npm run git-add",
     "postversion": "git push && git push --tags && npm publish"
   },
   "dependencies": {
-    "env-paths": "^3.0.0",
-    "make-dir": "^3.1.0",
-    "yaml": "^2.0.0-11"
+    "@slugbugblue/lru": "^1.0.0",
+    "@slugbugblue/point": "^1.0.0"
   },
   "devDependencies": {
     "ava": "^5.1.0",
@@ -55,11 +44,11 @@
     "node": ">=16.15.0"
   },
   "c8": {
-    "branches": 95,
+    "branches": 100,
     "check-coverage": true,
-    "functions": 95,
-    "lines": 95,
-    "statements": 95
+    "functions": 100,
+    "lines": 100,
+    "statements": 100
   },
   "prettier": {
     "bracketSpacing": true,

package/src/engine.js

@@ -15,23 +15,14 @@
 
 // Trax internals. Woot.
 
-// Tile type names are determined by listing the line color at each edge,
-// starting from the top and going clockwise, and then sorted alphabetically
-// and given a single letter name, so 'bbww' becomes 'a', which gives us six
-// different tile names: a-f
+import { Point } from '@slugbugblue/point'
 
-import { Point } from '@slugbugblue/trax/point'
-
-// Type definitions
 // Fun trax helper constants
 
 const zero = new Point(0, 0)
 const moveNumberRegex = /^(\d+)[.):]?$/
 const notationRegex = /^([@a-z]+)(\d+)([/\\+])$/i
 
-/** @type ValidTiles[] */
-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--+
@@ -40,7 +31,12 @@ const tileTypes = ['a', 'b', 'c', 'd', 'e', 'f']
  *  | o   |   |  #  |  |   o |  |   # |  |  o  |  | #   |
  *  +--o--+   +--#--+  +--o--+  +--#--+  +--o--+  +--#--+
  *
- * Slashes are represented by / \ or +.
+ * @readonly
+ * @type ValidTiles[]
+ * */
+const tileTypes = ['a', 'b', 'c', 'd', 'e', 'f']
+
+/** Slashes are represented by / \ or +.
  * @readonly
  * @type {Record<ValidTiles, Slash>}
  */
@@ -252,7 +248,6 @@ export class Trax {
   /** Restore a previously saved position.
    * @arg {SaveState} saved - the previously saved state
    * @see save for saving the state
-   * @returns {void}
    */
   restore(saved) {
     // So we need to be able to restore it when we are done

package/src/types.d.ts

@@ -7,125 +7,6 @@
 /** Color is a single character to represent white or black. */
 type Color = 'w' | 'b'
 
-/** Colorize is a fancy function for colorizing text. */
-type Colorize = (text: string, def?: string | number) => string
-
-/** Colorer is a little too fancy. Hence the gnarly typescript. */
-type Colorer = {
-  (text: string, def?: string | number): string
-  black: Colorize
-  command: Colorize
-  default: Colorize
-  error: Colorize
-  fatal: Colorize
-  help: Colorize
-  id: Colorize
-  variable: Colorize
-  optional: Colorize
-  short: Colorize
-  white: Colorize
-}
-
-/** An object representing a space on the perimeter of a Trax position.
- * x,y: the coordinates of the space
- * c: the color present beside the space (w, b, l: both w and b, r: none)
- * t: the type of possible moves: n-normal, x-none, c-cave, C-restricted cave
- * b,w: if present, the number of the line to match with its other end
- * pb, pw: if present, can pair with the next line in one turn
- * xb, xw: the label of this space for each color
- */
-type EdgeLocation = {
-  x: number
-  y: number
-  c: string
-  t: string
-  b?: number
-  w?: number
-  pb?: boolean
-  pw?: boolean
-  zb?: string
-  zw?: string
-  idx?: number
-}
-
-type EdgeObject = {
-  b: string
-  w: string
-  edge: RawEdge
-}
-
-/** Object representing a concrete threat found in a position. */
-type FoundThreat = {
-  threat: string
-  match: string
-  at: number
-  value: number
-  level: number
-}
-
-/** Threats found for each color that cannot actually be activated. */
-type FaultyThreats = {
-  b: FoundThreat[]
-  w: FoundThreat[]
-}
-
-/** An object with keys representing each level, with arrays for each threat of
- * that level. */
-type ColorThreats = Record<string, FoundThreat[]>
-
-/** All the threats found for both the white and black player. */
-type FoundThreatsCollection = { b: ColorThreats; w: ColorThreats }
-
-/** A note with a move number */
-type GameNote = {
-  move: number
-  note: string
-}
-
-/** Notes saved in the game object in the CLI. */
-type GameNotes = GameNote[]
-
-/** A point-like object has numerical x and y properties. */
-type PointLike = {
-  x: number
-  y: number
-}
-
-/** An object used to track an analysis on a position. */
-type PositionScore = {
-  move: string
-  score: number
-  analysis?: Analysis
-}
-
-/** A puzzle. */
-type Puzzle = {
-  id: string
-  src: string
-  game: TraxVariant
-  notation: string
-  icon: string
-  level: number
-  max: number
-  player: number
-  title?: string
-  desc?: string
-  hint?: string
-  hints?: string[]
-}
-
-type PuzzleSource = {
-  name: string
-  url?: string
-  copyright?: string
-  license?: string
-  licenseUrl?: string
-}
-
-/** Array of objects representing the spaces surrounding the perimeter of a
- * Trax position. */
-type RawEdge = EdgeLocation[]
-
 /** Treat the save state as an opaque object,
  * produced by save() and fed into restore().
  */
@@ -149,14 +30,6 @@ type SaveState = {
  */
 type Slash = '/' | '\\' | '+'
 
-/** Threat definition. */
-type Threat = {
-  depth: number
-  pattern: string
-  rx: RegExp
-  value: number
-}
-
 /** A single tile on the board. */
 type Tile = {
   id: TileId
@@ -182,5 +55,15 @@ type TileType = ValidTiles | 'x'
 /** All of the variants supported by the engine. */
 type TraxVariant = 'trax' | 'traxloop' | 'trax8'
 
-/** Tile types are represented by one of the following single characters. */
+/** Tile type names are determined by listing the line color at each edge,
+ * starting from the top and going clockwise, and then sorted alphabetically
+ * and given a single letter name, so 'bbww' becomes 'a', which gives us six
+ * different tile names: a-f, as follows:
+ *     a         b        c        d        e        f
+ *  +--#--+   +--#--+  +--#--+  +--o--+  +--o--+  +--o--+
+ *  |   # |   |  #  |  | #   |  | o   |  |  o  |  |   o |
+ *  oo   ##   ooo#ooo  ##   oo  oo   ##  #######  ##   oo
+ *  | o   |   |  #  |  |   o |  |   # |  |  o  |  | #   |
+ *  +--o--+   +--#--+  +--o--+  +--#--+  +--o--+  +--#--+
+ */
 type ValidTiles = 'a' | 'b' | 'c' | 'd' | 'e' | 'f'

package/src/version.js

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '0.20.0'
+export const version = '0.22.0'

package/.dockerignore

@@ -1,11 +0,0 @@
-.dockerignore
-.git*
-.husky
-.npmignore
-benchmark
-coverage
-Dockerfile
-docs
-jsconfig.json
-node_modules
-test

package/.gitlab-ci.yml

@@ -1,90 +0,0 @@
-include:
-  - template: Security/SAST.gitlab-ci.yml
-  - template: Security/Secret-Detection.gitlab-ci.yml
-
-stages:
-  - test
-  - sast
-  - benchmark
-  - release
-
-sast:
-  stage: sast
-
-nodejs-scan-sast:
-  allow_failure: false
-  rules:
-  - if: "$SAST_DISABLED"
-    when: never
-  - if: "$SAST_EXCLUDED_ANALYZERS =~ /nodejs-scan/"
-    when: never
-  - if: "$CI_COMMIT_BRANCH == 'main'"
-    exists:
-    - "**/package.json"
-
-semgrep-sast:
-  allow_failure: false
-  rules:
-  - if: "$SAST_DISABLED"
-    when: never
-  - if: "$SAST_EXCLUDED_ANALYZERS =~ /semgrep/"
-    when: never
-  - if: "$CI_COMMIT_BRANCH == 'main'"
-    exists:
-    - "**/*.js"
-
-secret_detection:
-  allow_failure: false
-
-code-coverage:
-  stage: test
-  image: node:lts-alpine
-  cache:
-    key: lts
-    paths:
-      - node_modules/
-  script:
-    - node --version
-    - npm install
-    - npm test
-  coverage: /^All files\s*\|\s*([\d.]+)/
-
-node16:
-  stage: test
-  image: node:16.15.0-alpine
-  cache:
-    key: node16
-    paths:
-      - node_modules/
-  script:
-    - node --version
-    - npm install
-    - npm test
-
-benchmark:
-  stage: benchmark
-  image: node:lts-alpine
-  cache:
-    key: lts
-    paths:
-      - node_modules/
-  rules:
-    - if: $CI_COMMIT_TAG =~ /^v\d\+\.\d+\.\d+$/
-  script:
-    - npm run benchmark
-    - awk '/^## /{p++}p==1;p==2{exit}' CHANGELOG.md > RELEASE.$CI_COMMIT_TAG.md
-  artifacts:
-    paths:
-      - RELEASE.$CI_COMMIT_TAG.md
-    expire_in: 1 day
-
-release:
-  stage: release
-  image: registry.gitlab.com/gitlab-org/release-cli:latest
-  rules:
-    - if: $CI_COMMIT_TAG =~ /^v\d\+\.\d+\.\d+$/
-  script:
-    - echo "Releasing $CI_COMMIT_TAG"
-  release:
-    tag_name: $CI_COMMIT_TAG
-    description: ./RELEASE.$CI_COMMIT_TAG.md

package/.husky/pre-commit

@@ -1,5 +0,0 @@
-#!/usr/bin/env sh
-. "$(dirname -- "$0")/_/husky.sh"
-
-npm outdated
-npm test

package/Dockerfile

@@ -1,14 +0,0 @@
-# Use the latest nodejs long-term-support release,
-# on the latest Alpine Linux for its small footprint
-FROM node:lts-alpine
-# Install current source code
-WORKDIR /trax
-COPY . .
-RUN npm install
-# Ensure the data files can be persisted
-WORKDIR /mnt/data
-ENV XDG_CONFIG_HOME=/mnt/data
-ENV XDG_DATA_HOME=/mnt/data
-VOLUME /mnt/data
-# Use the trax CLI as the starting point
-ENTRYPOINT ["/trax/src/cli.js"]