@slugbugblue/trax 0.19.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,15 @@
 # @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

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
@@ -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
@@ -161,6 +177,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 +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
 
@@ -188,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
 
@@ -218,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slugbugblue/trax",
-  "version": "0.19.0",
+  "version": "0.20.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,

package/src/analyst.js

@@ -204,7 +204,7 @@ const label = (rawEdge) => {
 const length = (array) => array?.length || 0
 
 /** Calculate the points for the number of threats at a particular level.
- * @arg {FoundThreats} from - the threats found for a certain player
+ * @arg {ColorThreats} from - the threats found for a certain player
  * @arg {number} level - the level to calculate the points for
  * @arg {number} [as] - if included, the level the points should be calculated as
  * @return {number} the number of points for the level
@@ -217,16 +217,23 @@ const attackScore = (from, level, as) => {
 }
 
 /** Shortcut to get the number of attacks.
- * @arg {FoundThreats} from - the threats found for a certain player
+ * @arg {ColorThreats} from - the threats found for a certain player
  * @returns {number} the number of attacks (win on next move) present
  */
 const attackCount = (from) => length(from['1'])
 
+/** Shortcut to get the number of threats at a certain level.
+ * @arg {ColorThreats} from - the threats found for a player
+ * @arg {number} level - the level for the threats to look for
+ * @returns {number} the number of threats at the given level
+ */
+const threatCount = (from, level) => length(from[level])
+
 /** Shortcut to get the number of passive threats
- * @arg {FoundThreats} from - the threats found for a player
+ * @arg {ColorThreats} from - the threats found for a player
  * @returns {number} the number of passive threats (win in 2 or more moves)
  */
-const threatCount = (from) => {
+const passiveCount = (from) => {
   let count = 0
   for (const [depth, array] of Object.entries(from)) {
     count += int(depth) > 1 ? length(array) : 0
@@ -236,23 +243,29 @@ const threatCount = (from) => {
 }
 
 /** Shortcut to determine if we have an active attack.
- * @arg {FoundThreats} from - the threats found for a player
+ * @arg {ColorThreats} from - the threats found for a player
  * @returns {boolean}
  */
 const activeAttack = (from) =>
-  attackCount(from) > 1 || (attackCount(from) === 1 && threatCount(from) > 0)
+  attackCount(from) > 1 || (attackCount(from) === 1 && passiveCount(from) > 0)
 
 /** Shortcut to determine if we have a passive attack.
- * @arg {FoundThreats} from - the threats found for a player
+ * @arg {ColorThreats} from - the threats found for a player
  * @returns {boolean}
  */
-const passiveAttack = (from) => threatCount(from) > 1
+const passiveAttack = (from) => passiveCount(from) > 1
+
+// /** Shortcut to determine if we are under attack.
+//  * @arg {ColorThreats} from - the threats found for a player
+//  * @returns {boolean}
+//  */
+// const underAttack = (from) => attackCount(from) > 0
 
-/** Shortcut to determine if we are under attack.
- * @arg {FoundThreats} from - the threats found for a player
+/** Shortcut to determine if we are under threat.
+ * @arg {ColorThreats} from - the threats found for a player
  * @returns {boolean}
  */
-const underAttack = (from) => attackCount(from) + threatCount(from) > 0
+const underThreat = (from) => attackCount(from) + passiveCount(from) > 0
 
 // Analysis class
 export class Analysis {
@@ -282,6 +295,10 @@ export class Analysis {
       b: (level) => this.threats.b[level]?.length || 0,
     }
     this.#partial = Boolean(partial)
+    if (this.#moves.length === 0 || game.over) {
+      this.#edge = { b: '', w: '', rawEdge: [] }
+      this.#threats = { b: {}, w: {} }
+    }
   }
 
   get game() {
@@ -383,7 +400,7 @@ export class Analysis {
     const attacking = activeAttack(inactive)
 
     // Was the inactive player unable to clear all threats?
-    const defending = !attacking && underAttack(active)
+    const defending = !attacking && underThreat(active)
 
     // Does the inactive player have multiple threats
     const threatening = !attacking && passiveAttack(inactive)
@@ -559,15 +576,17 @@ export class Analysis {
    * @arg {string} color - the player color
    * @returns {Point[]} - locations relevant to the threat
    */
-  #threatLocs(threat, color) {
+  threatLocs(threat, color) {
     const { edge } = this.edge
     const max = edge.length
     let index = threat.at
+    let count = 0
     const locs = new Set([index])
-    while (threat.match.length > locs.size) {
+    while (count < threat.match.length) {
       index += 1
       if (index >= max) index -= max
       locs.add(index)
+      count += 1
       // Check to see if we have a connectable pair
       if (edge[index]['p' + color]) {
         const line = 'n' + color
@@ -583,16 +602,15 @@ export class Analysis {
       }
     }
 
-    const value = [...locs].map((i) => new Point(edge[i]))
-    return value
+    return [...locs].map((i) => new Point(edge[i] || { x: 0, y: 0 }))
   }
 
   /** Apply the threats to a color's regex-ready edge.
    * @arg {Color} color - the color to find threats for
-   * @returns {FoundThreats}
+   * @returns {ColorThreats}
    */
   #applyThreats(color) {
-    /** @type {FoundThreats} */
+    /** @type {ColorThreats} */
     const matches = {}
     const { length } = this.edge[color]
     const edge = this.edge[color].repeat(2)
@@ -616,7 +634,7 @@ export class Analysis {
   /** Clean up the list of matches, removing any false positives. */
   #validateThreats() {
     for (const bw of ['w', 'b']) {
-      /** @type FoundThreats */
+      /** @type ColorThreats */
       const matches = this.#threats[bw]
       for (const key of Object.keys(matches)) {
         const level = Number(key)
@@ -648,10 +666,12 @@ export class Analysis {
    * @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)) {
+    const attacks = attackCount(this.#threats[color])
+    const player = Trax.playerNumber(color)
+    const other = Trax.other(color)
+    const otherAttacks = attackCount(this.#threats[other])
+    const higher = threatCount(this.#threats[color], level - 1)
+    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)
@@ -659,20 +679,23 @@ export class Analysis {
 
         // 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
+        if (game.over && game.turn === player) return true
+
+        // Otherwise, we cannot evaluate an ended game
+        if (game.over) continue
 
         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
+        const faulty = attackCount(threats[other]) - otherAttacks
         if (faulty > 0) continue
 
         // Activating the threat means we get an attack and a threat
-        const newAttacks = (threats[color][1]?.length ?? 0) - attacks
+        const newAttacks = attackCount(threats[color]) - attacks
         if (level === 2) {
           if (newAttacks > 1) return true
         } else {
-          const newThreats = (threats[color][level - 1]?.length ?? 0) - higher
+          const newThreats = threatCount(threats[color], level - 1) - higher
           if (newAttacks > 0 && newThreats > 0) return true
         }
       }
@@ -766,7 +789,7 @@ export class Suggestion {
   }
 }
 
-export const suggest = (game) => {
+export const suggest = (game, partial = false) => {
   const start = Date.now()
   const analyzed = {}
   const { color, moves, rules } = game
@@ -775,7 +798,7 @@ export const suggest = (game) => {
     trax.play(move)
     const unique = trax.normalized
     if (!analyzed[unique]) {
-      const analysis = analyze(trax)
+      const analysis = analyze(trax, partial)
       analyzed[unique] = { move, score: analysis.scores[color], analysis }
     }
   }

package/src/cmds/import-export.js

@@ -248,7 +248,7 @@ const gameNotes = (move, notes) => {
   if (moveNotes.length === 0) return ''
   return (
     '; ' +
-    moveNotes.map((n) => n.note.replaceAll('\n', '\n; ')).join('\n; ') +
+    moveNotes.map((n) => n.note.replace(/\n/g, '\n; ')).join('\n; ') +
     '\n'
   )
 }
@@ -328,8 +328,15 @@ exportCmd.fn = (CLI, id, filename) => {
       const source = sources[puzzle.src]
       content += '; Puzzle ' + game.puzzle
       if (source) {
-        content += ' provided courtesy of ' + source.name
+        content += source.copyright
+          ? ' ©' + source.copyright + ' by '
+          : ' provided courtesy of '
+        content += source.name
         if (source.url) content += '\n; ' + source.url
+        if (source.license) {
+          content += '\n; Licensed under ' + source.license
+          content += source.licenseUrl ? ' ' + source.licenseUrl : ''
+        }
       }
 
       content += '\n'

package/src/cmds/notes.js

@@ -25,6 +25,9 @@ notesCmd.fn = (CLI, id, ...note) => {
   if (id.startsWith('#')) id = id.slice(1)
 
   const game = CLI.GAMES[id]
+
+  if (!game) return CLI.error('Game not found.')
+
   const notes = game.notes || []
   const move = game.moves.length > 0 ? game.moves.split(' ').length : 0