@slugbugblue/trax 0.19.0 → 0.21.0

package/.dockerignore

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

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @slugbugblue/trax
 
+## 0.21.0 -2023-03-12
+
+- Update the analysis engine to be more lazy
+
+  - Call `validateThreats()` to make it work harder
+  - This also increases LRU cache hits
+  - This makes the suggestions much faster because it skips validations for
+    low-scoring moves
+
+## 0.20.0 - 2023-02-11
+
+- Provide timing feedback on the puzzlebot's actions
+- Add license information for puzzle sources
+- Add gitlab CI configuration
+- Drop support for node 14; node v16.15 is our minimum supported version
+- More puzzles from Martin M. S. Pedersen -- bringing the total to 100+
+- Enhance the docker configuration and document it in the README
+- Refine faulty threat detection and add test for once case it was failing
+
 ## 0.19.0 - 2023-02-06
 
 - Added a simple LRU cache to increase the efficiency of the analysis engine

package/CONTRIBUTING.md

@@ -0,0 +1,113 @@
+# Contributing to slugbugblue/trax
+
+Hi, thanks for considering contributing to this project.
+
+If this is your first time working on an open source project, it is recommended
+that you start by reading [How to Contribute to Open Source][howto].
+
+## Ways to contribute
+
+### Improve documentation
+
+One of the simplest ways to get started contributing is to find areas of the
+documentation that are unclear, incorrect, or that have typos or other errors,
+and providing feedback and corrections. You don't have to know how to code or
+even how to use git.
+
+### Identify bugs
+
+If you are aware of something not working as you think it should, feel free to
+open a new issue to let us know. Browsing through the existing open issues and
+adding comments or making clarifications can also be a great way to get started.
+
+### Fixing bugs
+
+If you feel you have a solution to an existing bug, you are welcome to code up
+your solution and submit a merge request. It may take some time to get fully up
+to speed with our coding styles and with the structure of the code, so don't
+feel bad if your merge request receives comments rather than being immediately
+accepted. Simply make any necessary changes, and update the merge request, or
+let us know in a subsequent comment if you think we are misunderstanding the
+merge request.
+
+## Submitting an issue
+
+If you choose to submit an issue, please take the time to ensure that you
+provide as much detail as possible about the issue. A poorly worded or poorly
+researched issue report will unnecessarily delay the issue resolution.
+
+Even if you don't have the time or expertise to fully diagnose the problem, a
+good issue report can be very helpful to us as we seek to improve the code.
+
+## Submitting a merge request
+
+Good merge requests are a fantastic way to contribute to this project. Your
+merge request is going to be accepted more quickly if it is easy to understand.
+Ideally it should be focused on a single item and avoid unrelated commits.
+
+Please ask first before embarking on a major change, such as adding a new
+feature or refactoring the code, otherwise you risk spending a significant
+amount of time working on something that will not be merged into the project.
+
+If you have never submitted a merge request before, no fear. Here is a [quick
+tutorial][howto-mr] on how to create one.
+
+### Merge request steps
+
+- Fork the project and clone it to your own workspace.
+- Get the latest changes and update the project dependencies:
+
+```bash
+$ git checkout develop
+$ git pull upstream develop
+$ rm -rf node_modules
+$ npm install
+```
+
+- Create a new branch to contain your changes:
+
+```bash
+$ git checkout -b <new-branch-name>
+```
+
+- Make your changes.
+- Test your changes.
+
+```bash
+$ npm test
+```
+
+- Push your changes back to your fork.
+
+```bash
+$ git push -u origin <new-branch-name>
+```
+
+1. Open a merge request in the [slugbugblue/trax][trax-repo] repo.
+
+## Working with the code
+
+This repository uses [XO][xo] for linting and [Prettier][prettier] for
+formatting. Running `npm test` will produce an error if your changes do not
+conform. You should consider installing the [XO plugin][xo-plugin] for your
+editor to have the linting errors highlighted for you and automatically fixed on
+save. You can also run `npx xo --fix` from the command line to fix most linting
+errors.
+
+This repository uses [AVA][ava] for writing and running tests. While we want as
+much code coverage as possible for all code, we have a minimum requirement of
+95% of code coverage for the [analysis engine][analyst] and 100% for the [main
+trax engine][engine]. You should be able to get a quick grasp on the testing
+process by simply examining a few of the test files in the [test
+directory][test].
+
+[analyst]: src/analyst.js
+[ava]: https://github.com/avajs/ava
+[engine]: src/engine.js
+[howto]: https://opensource.guide/how-to-contribute/
+[howto-mr]: https://opensource.guide/how-to-contribute/#opening-a-pull-request
+[prettier]: https://prettier.io
+[test]: test/
+[trax-repo]: https://gitlab.com/slugbugblue/trax
+[xo]: https://github.com/sidresorhus/xo
+[xo-plugin]: https://github.com/sidresorhus/xo#editor-plugins

package/Dockerfile

@@ -1,9 +1,14 @@
 # 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 globally
-COPY . /src
-WORKDIR /src
-RUN npm install -g @slugbugblue/trax
+# 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 ["/usr/local/bin/trax"]
+ENTRYPOINT ["/trax/src/cli.js"]

package/LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2021 Chad Transtrum
+   Copyright © 2021-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.

package/README.md

@@ -4,7 +4,7 @@ This project aims to provide tools for working with Trax games in Javascript.
 
 - Trax game-playing engine
 - Position analysis engine
-- Over 60 puzzles to help hone your Trax skills
+- Over 100 puzzles to help hone your Trax skills
 - Command-line interface for ease of use
 
 ## Description
@@ -23,20 +23,47 @@ changes to the engine should meet the same standard.
 
 ## Installation
 
+Installation can be done in one of three ways, each for a slightly different
+purpose.
+
+If you want to use this code in your own javascript project:
+
 ```bash
-# Install into a javascript project
 npm install @slugbugblue/trax
+```
+
+If you want to use the trax CLI on your computer:
 
-# Or install globally to use the trax CLI more easily
+```bash
 npm install -g @slugbugblue/trax
 ```
 
+If you don't have node installed and want to use the CLI as a docker container:
+
+```bash
+git clone https://gitlab.com/slugbugblue/trax.git ~/trax
+docker build -t trax ~/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
@@ -59,7 +86,7 @@ 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
+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
@@ -68,11 +95,7 @@ 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:
+### Examples
 
 ```text
 # Start a new Trax game with Chad playing as white
@@ -99,6 +122,18 @@ Examples:
 > trax ls
 ```
 
+### Environment variables
+
+The CLI uses standard Windows and Linux [XDG][xdg] file locations as provided by
+the [env-paths library][env-path], with current uses being user-specific
+`config` (`XDG_CONFIG_HOME`) and `data` (`XDG_DATA_HOME`) folders.
+
+In addition, the CLI recognizes several environment variables to determine the
+glyphs to use in the user interface. Setting either `NERDFONT` or `NERDFONTS` to
+any non-empty string will use characters from [Nerdfonts][nerfont]. Otherwise,
+any of `POWERLINE`, `P9K_TTY`, or `P9K_SSH` will use characters from [Powerline
+fonts][powerline].
+
 ## API Usage
 
 ### Trax engine
@@ -161,6 +196,8 @@ traxgame.com puzzles page][traxpuzzles], and [puzzles curated][puzzlebook] by
 ## Roadmap
 
 - Improve the threats database / analysis engine.
+  - Bot should be able to win all puzzles.
+  - Analysis should recognize line threats.
 - Add more puzzles.
 
 ## Support
@@ -170,8 +207,8 @@ Issues can be opened on the [gitlab project page][repo].
 
 ## Contributing
 
-Contributions are welcome. Ideally in the form of pull requests, but feel free
-to open an issue with a bug report or a suggestion as well.
+[Contributions are welcome][contributing]. Ideally in the form of pull requests,
+but feel free to open an issue with a bug report or a suggestion as well.
 
 ## Acknowledgments
 
@@ -188,10 +225,9 @@ always ready to share his insights on the mechanics of the game, as well as
 various approaches to encoding its complexities. His undeserved kindness and
 infinite patience in indulging my many questions can never be repaid.
 
-Thanks for [Martin M. S. Pedersen][traxplayer] for contributing ideas, code, and
-puzzles to this effort. He's been [curating Trax puzzles][puzzlebook] and
-[coding solutions for Trax][gnutrax] for over two decades, and brings a lot of
-expertise.
+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.
 
 ## License
 
@@ -218,6 +254,7 @@ The official rules for Trax are found at http://traxgame.com/about_rules.php.
 As Trax is a proprietary game, these rules are the intellectual property of
 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
@@ -225,6 +262,8 @@ David Smith and heirs, and are not to be used without permission.
 [env-path]: https://www.npmjs.com/package/env-paths
 [gnutrax]: https://gnutrax.com
 [goldtoken]: https://goldtoken.com/
+[nerdfont]: https://nerdfonts.com/
+[powerline]: https://github.com/powerline/fonts
 [puzzlebook]: https://gnutrax.com/book
 [repo]: https://gitlab.com/slugbugblue/trax
 [sbb]: https://slugbugblue.com/

package/docs/analyst.md

@@ -104,10 +104,12 @@ so that it appears as though all black tiles are white tiles.
 Analyzes the existing threats for the current game position. Returns an object
 with both `b` and `w` keys, where each is an object with zero or more "depth"
 keys. Threats of depth 0 are corners or connectable-pairs. Threats of depth 1
-are immediate attacks. Threats of depth 2 are Ls. etc. Note that the threats are
-not checked for faultiness at this time. In other words, there may be a faulty L
-listed as a threat even if it is not currently possible to activate the L
-successfully.
+are immediate attacks. Threats of depth 2 are Ls. etc.
+
+Note that the threats are not checked for faultiness at this time. In other
+words, there may be a faulty L listed as a threat even if it is not currently
+possible to activate the L successfully. To ensure that the listed threats are
+valid, use the `validateThreats()` method call.
 
 The "depth" keys are arrays of the threats at that level, which means that a
 simple count of the threats at each level can give a good first guess at the
@@ -119,11 +121,23 @@ following keys:
 - `match`: The portion of the actual edge string that matched the pattern, which
   may or may not be exactly the same as the pattern.
 - `at`: The index of the edge string at which the pattern match began.
+- `value`: The multiplier for this threat. Most often this is `1`, but some
+  threats can be re-formed, and this will be `2` in those cases.
 
 ##### `faulty`
 
-Contains the same information as `threats` but for removed threats that were
-found to be faulty.
+An object with two keys, `w` and `b`, each of which is a list of threats that
+were found to be faulty. This object will be empty if `validateThreats()` has
+not yet been called.
+
+Example data:
+
+```javascript
+{
+  w: [{ threat: 'Arw?!pW', match: 'arwpa', at: 1, level: 2, value: 1 }],
+  b: [],
+}
+```
 
 ##### `score`
 
@@ -164,6 +178,12 @@ 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.
 
+##### `validateThreats()`
+
+Ensure that all of the threats that are present for each color are actually
+valid. If it finds any faulty threats, it will update the `score` and populate
+the `faulty` property with each threat that was found to be invalid.
+
 ### Suggestion class
 
 Accessible from `suggest(game)`, this class is returned with several useful

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slugbugblue/trax",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "Trax game engine and friends",
   "keywords": [
     "trax",
@@ -20,6 +20,7 @@
     "./puzzles": "./src/puzzles.js",
     "./threats": "./src/threats.js",
     "./tty": "./src/tty.js",
+    "./utils": "./src/utils.js",
     "./version": "./src/version.js"
   },
   "repository": "gitlab:slugbugblue/trax",
@@ -28,10 +29,12 @@
   },
   "scripts": {
     "benchmark": "node benchmark/puzzles.bench.js",
+    "genversion": "genversion --es6 src/version.js",
+    "git-add": "git add src/version.js benchmark/benchmarks.json",
     "test": "xo && c8 ava",
     "prepare": "husky install",
     "preversion": "npm test",
-    "version": "genversion --es6 src/version.js && npm run benchmark || git add src/version.js benchmark/benchmarks.json",
+    "version": "npm run genversion ; npm run benchmark ; npm run git-add",
     "postversion": "git push && git push --tags && npm publish"
   },
   "dependencies": {
@@ -49,7 +52,14 @@
   },
   "type": "module",
   "engines": {
-    "node": "^14.14.0 || >=16.0.0"
+    "node": ">=16.15.0"
+  },
+  "c8": {
+    "branches": 95,
+    "check-coverage": true,
+    "functions": 95,
+    "lines": 95,
+    "statements": 95
   },
   "prettier": {
     "bracketSpacing": true,