@slugbugblue/trax 0.18.0 → 0.20.0

package/.dockerignore

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

package/.gitlab-ci.yml

@@ -0,0 +1,90 @@
+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,4 +1,5 @@
 #!/usr/bin/env sh
 . "$(dirname -- "$0")/_/husky.sh"
 
+npm outdated
 npm test

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @slugbugblue/trax
 
+## 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
+
 ## 0.18.0 - 2023-02-05
 
 - Analysis improvements:

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,5 +1,14 @@
-FROM node:19.5.0-slim
-COPY . /src
-WORKDIR /src
-RUN npm install -g @slugbugblue/trax
-ENTRYPOINT ["/usr/local/bin/trax"]
+# 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"]

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 50 puzzles to help hone your Trax skills
+- Over 100 puzzles to help hone your Trax skills
 - Command-line interface for ease of use
 
 ## Description
@@ -29,6 +29,9 @@ 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
@@ -37,6 +40,19 @@ 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
@@ -153,13 +169,16 @@ 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].
+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.
 
 ## Support
@@ -169,8 +188,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
 
@@ -187,10 +206,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
 
@@ -217,6 +235,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

package/docs/analyst.md

@@ -119,11 +119,22 @@ 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 fauly.
+
+Example data:
+
+```javascript
+{
+  w: [{ threat: 'Arw?!pW', match: 'arwpa', at: 1, level: 2, value: 1 }],
+  b: [],
+}
+```
 
 ##### `score`
 

package/docs/lru.md

@@ -0,0 +1,151 @@
+# lru.js API documentation
+
+This module provides a simple Least Recently Used cache.
+
+Internally, this uses a Map, which give us insertion-ordering for free. The
+first item in the list is the oldest. The last item is the most recently set or
+accessed. Most of the base functionality of the Map are replicated.
+
+Since I don't need it to be super fancy, there isn't a lot of extra
+functionality here.
+
+## Example usage
+
+```javascript
+import { LRU } from '@slugbugblue/trax/lru.js'
+
+const cache = new LRU(100)
+
+cache.set('a', 1)
+cache.set('b', 2)
+
+// Get an item from the cache
+console.log(cache.get('a')) // 1
+
+// Accessing a key makes it the most recent:
+console.log(cache.keys()) // [Map Iterator] { 'b', 'a' }
+console.log(cache.hits) // 1
+
+console.log(cache.get('z')) // undefined
+console.log(cache.misses) // 1
+
+console.log(cache.size) // 2
+console.log(cache.capacity) // 100
+```
+
+## API
+
+### LRU class
+
+An LRU cache is a way to remember a limited set of items, with the oldest
+expiring when the capacity is reached.
+
+#### constructor
+
+##### `new LRU(capacity)`
+
+Create the cache by specifying the maximum number of items it should hold.
+
+#### computed properties
+
+##### `capacity`
+
+The maximum number of items the cache can hold. This cannot be changed after the
+cache creation.
+
+##### `size`
+
+The number of items currently stored in the cache.
+
+##### `hits`
+
+The number of times a `get` call has found an item in the cache.
+
+##### `misses`
+
+The number of times a `get` call has not found an item in the cache.
+
+##### `expired`
+
+The number of times an item has been removed from the cache.
+
+#### methods
+
+##### `get(key)`
+
+Retrieve an item from the cache. If the item is found in the cache, `hits` will
+be updated, the item will be marked as the most-recently-used item, and the
+value will be returned. If the item is not present in the cache, `misses` will
+be updated, and `undefined` will be returned.
+
+Note that if you had stored `undefined` as the value in the cache, the return of
+`undefined` doesn't necessarily represent a cache miss.
+
+##### `peek(key)`
+
+Retrieve an item from the cache, if present, but without updating any of the
+LRU-specific information about the retrieval attempt. The item's age will not be
+updated. If the item is not present in the cache, `undefined` will be returned.
+
+##### `set(key, value)`
+
+Store an item in the cache. If the item is already present in the cache, it will
+be replaced and marked as the most-recently-used item.
+
+##### `delete(key)`
+
+Remove an item from the cache.
+
+##### `clear()`
+
+Clears all items and statistics from the cache. The maximum capacity will not
+change.
+
+##### `entries()`
+
+Returns an iterator that operates over all the \[key, value\] pairs stored in
+the cache. The entries will be in order from oldest to newest.
+
+##### `has(key)`
+
+Returns true if a key is found in the cache, false otherwise.
+
+##### `keys()`
+
+Returns an iterator that operates over all the keys stored in the cache. The
+keys will be returned oldest first, newest last.
+
+##### `values()`
+
+Returns an iterator that operates over all the values stored in the cache. The
+values will be returned oldest first, newest last.
+
+#### Plays well with others
+
+The LRU class also includes functionality to provide useful default results when
+used in other contexts.
+
+##### `toString()`
+
+Returns a string representation of the cache in the format `LRU(75 of 1000)`.
+This allows simple logging calls with `console.log(cache)`.
+
+##### `util.inspect.custom()`
+
+When running in the node command line interpreter, an LRU cache instance will be
+pretty-printed using the magic of `util.inspect`.
+
+## License
+
+Copyright 2023 Chad Transtrum
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+the files in this project 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slugbugblue/trax",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Trax game engine and friends",
   "keywords": [
     "trax",
@@ -14,11 +14,13 @@
   "types": "./src/types.d.ts",
   "exports": {
     ".": "./src/engine.js",
-    "./point": "./src/point.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"
   },
   "repository": "gitlab:slugbugblue/trax",
@@ -27,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": {
@@ -48,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,