@slugbugblue/trax-cli 0.12.1 → 0.14.0

package/src/cmds/analyze.js

@@ -1,24 +1,22 @@
-/* Copyright 2022-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.
- * 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 analyze command
+ * @copyright 2022-2026
+ * @author Chad Transtrum <chad@transtrum.net>
+ * @license Apache-2.0
  */
 
-// CLI analyze command
+/** @typedef {import('../cli.js').CLIContext} CLIContext */
 
 import { analyze } from '@slugbugblue/trax-analyst'
 import { Trax } from '@slugbugblue/trax'
 
-const notationRx = /^[@a-z]+\d+[bps/\\+]$/i
+const notationRx = /^[@a-z]+\d+[bps\/\\+]$/iv
+
+/** @type {Record<string, string>} */
+const threatNames = {
+  0: 'corners',
+  1: 'attacks',
+  2: 'Ls',
+}
 
 export const analyzeCmd = {
   name: 'analyze',
@@ -29,14 +27,64 @@ export const analyzeCmd = {
     'Analyze the current position of the currently selected game, or pass in a',
     'move to analyze the result of that move.',
   ],
-}
+  /** @param {CLIContext} CLI @param {string} [move] */
+  fn(CLI, move) {
+    if (!String(CLI.GAME?.id)) {
+      return CLI.error('No active game. Type "new" to start a game.')
+    }
 
-const threatNames = {
-  0: 'corners',
-  1: 'attacks',
-  2: 'Ls',
+    let trax = CLI.TRAX
+
+    const detailed =
+      typeof move === 'string' &&
+      ('detail'.startsWith(move) || 'debug'.startsWith(move))
+
+    if (move && notationRx.test(move)) {
+      move = CLI.fixNotation(move)
+      CLI.do('try', move)
+      trax = new Trax(trax.rules, trax.moves, 'cli')
+      const play = trax.dropTile(move)
+      if (!play.valid || trax.over) return
+    }
+
+    if (trax.over) {
+      return CLI.error('Game has ended.')
+    }
+
+    const { edge, threats, scores, faulty } = analyze(trax)
+
+    if (detailed) CLI.out(CLI.color.white(edge.w))
+    CLI.out(
+      CLI.bubble('w', scores.w) +
+        CLI.color.white(' ') +
+        listThreats(threats.w, detailed),
+    )
+
+    if (detailed) {
+      if (faulty.w.length > 0) {
+        CLI.out(CLI.color.white('') + listFaulty(faulty.w))
+      }
+
+      CLI.out(CLI.color.black(edge.b))
+    }
+
+    CLI.out(
+      CLI.bubble('b', scores.b) +
+        CLI.color.black(' ') +
+        listThreats(threats.b, detailed),
+    )
+
+    if (detailed && faulty.b.length > 0) {
+      CLI.out(CLI.color.black('') + listFaulty(faulty.b))
+    }
+  },
 }
 
+/**
+ * @param {Record<string, any[]>} threats
+ * @param {boolean} detailed
+ * @returns {string}
+ */
 const listThreats = (threats, detailed) => {
   const summary = []
   for (const level of Object.keys(threats || {})) {
@@ -54,6 +102,10 @@ const listThreats = (threats, detailed) => {
   return summary.join('  ')
 }
 
+/**
+ * @param {any[]} faulty
+ * @returns {string}
+ */
 const listFaulty = (faulty) => {
   const summary = []
   for (const threat of faulty) {
@@ -64,49 +116,3 @@ const listFaulty = (faulty) => {
 
   return 'Faulty: ' + summary.join(' ')
 }
-
-analyzeCmd.fn = (CLI, move) => {
-  if (!String(CLI.GAME?.id)) {
-    return CLI.error('No active game. Type "new" to start a game.')
-  }
-
-  let trax = CLI.TRAX
-
-  const detailed = 'detail'.startsWith(move) || 'debug'.startsWith(move)
-
-  if (notationRx.test(move)) {
-    move = CLI.fixNotation(move)
-    CLI.do('try', move)
-    trax = new Trax(trax.rules, trax.moves, 'cli')
-    const play = trax.dropTile(move)
-    if (!play.valid || trax.over) return
-  }
-
-  if (trax.over) {
-    return CLI.error('Game has ended.')
-  }
-
-  const { edge, threats, scores, faulty } = analyze(trax)
-
-  if (detailed) CLI.out(CLI.color.white(edge.w))
-  CLI.out(
-    CLI.bubble('w', scores.w) +
-      CLI.color.white(' ') +
-      listThreats(threats.w, detailed),
-  )
-
-  if (detailed) {
-    if (faulty.w.length > 0) CLI.out(CLI.color.white('') + listFaulty(faulty.w))
-    CLI.out(CLI.color.black(edge.b))
-  }
-
-  CLI.out(
-    CLI.bubble('b', scores.b) +
-      CLI.color.black(' ') +
-      listThreats(threats.b, detailed),
-  )
-
-  if (detailed && faulty.b.length > 0) {
-    CLI.out(CLI.color.black('') + listFaulty(faulty.b))
-  }
-}

package/src/cmds/delete.js

@@ -1,19 +1,10 @@
-/* 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 delete command
+ * @copyright 2022-2026
+ * @author Chad Transtrum <chad@transtrum.net>
+ * @license Apache-2.0
  */
 
-// CLI delete command
+/** @typedef {import('../cli.js').CLIContext} CLIContext */
 
 export const deleteCmd = {
   name: 'delete',
@@ -25,11 +16,40 @@ export const deleteCmd = {
     'Delete the current game. Or specify a game number to delete that game.',
     'If the game is in progress, you must type "force" to delete it.',
   ],
+  /** @param {CLIContext} CLI @param {string} [id] @param {string} [force] */
+  fn(CLI, id, force = 'x') {
+    const current = String(CLI.GAME.id)
+    id ||= current
+    if ('force'.startsWith(id)) {
+      id = current
+      force = 'force'
+    }
+
+    if (id.startsWith('#')) id = id.slice(1)
+
+    const game = CLI.GAMES[id]
+
+    if (!game || !String(game.id)) {
+      return CLI.error('Invalid id. Type "list" to see available games.')
+    }
+
+    if (game.over || game.moves === '' || 'force'.startsWith(force)) {
+      CLI.delete(id)
+      CLI.out(CLI.color('Deleted game #' + id + '.'))
+
+      if (id === String(current)) {
+        selectAnyGame(CLI)
+      }
+    } else {
+      CLI.error('Game #' + id + ' is still active. Use "force" to delete it.')
+    }
+  },
 }
 
+/** @param {CLIContext} CLI */
 const selectAnyGame = (CLI) => {
   if (CLI.GAMES) {
-    const games = Object.values(CLI.GAMES).sort((a, b) => {
+    const games = Object.values(CLI.GAMES).toSorted((a, b) => {
       // Active games first
       if (a.over && !b.over) return 1
       if (b.over && !a.over) return -1
@@ -41,31 +61,3 @@ const selectAnyGame = (CLI) => {
     }
   }
 }
-
-deleteCmd.fn = (CLI, id, force = 'x') => {
-  const current = String(CLI.GAME.id)
-  id ||= current
-  if ('force'.startsWith(id)) {
-    id = current
-    force = 'force'
-  }
-
-  if (id.startsWith('#')) id = id.slice(1)
-
-  const game = CLI.GAMES[id]
-
-  if (!game || !String(game.id)) {
-    return CLI.error('Invalid id. Type "list" to see available games.')
-  }
-
-  if (game.over || game.moves === '' || 'force'.startsWith(force)) {
-    CLI.delete(id)
-    CLI.out(CLI.color('Deleted game #' + id + '.'))
-
-    if (id === String(current)) {
-      selectAnyGame(CLI)
-    }
-  } else {
-    CLI.error('Game #' + id + ' is still active. Use "force" to delete it.')
-  }
-}

package/src/cmds/help.js

@@ -1,19 +1,10 @@
-/* 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 help command
+ * @copyright 2022-2026
+ * @author Chad Transtrum <chad@transtrum.net>
+ * @license Apache-2.0
  */
 
-// CLI help command
+/** @typedef {import('../cli.js').CLIContext} CLIContext */
 
 export const helpCmd = {
   name: 'help',
@@ -26,56 +17,62 @@ export const helpCmd = {
     'Type "help <command>" or "<command> help" to see additional information',
     'for a specific command.',
   ],
-}
-
-// Find the length of the printable characters of the string
-const length = (text) => text.replaceAll(/[<">]/g, '').length
-
-helpCmd.fn = (CLI, word) => {
-  // If we are looking for help on a particular commands, get that command
-  word = CLI.resolveCommand(word) || (word ? String(word).toLowerCase() : '')
-  let cmds = CLI.commands.filter((c) => !word || c.startsWith(word))
-  if (cmds.length === 0) {
-    cmds = CLI.commands.filter((c) => c.includes(word))
-  }
-
-  // If we don't have a few commands, select all commands
-  if (cmds.length === 0) cmds = CLI.commands
+  /** @param {CLIContext} CLI @param {string} [word] */
+  fn(CLI, word) {
+    // If we are looking for help on a particular commands, get that command
+    const resolved = CLI.resolveCommand(word)
+    const resolvedWord =
+      typeof resolved === 'string'
+        ? resolved
+        : word
+          ? String(word).toLowerCase()
+          : ''
+    let cmds = CLI.commands.filter(
+      (c) => !resolvedWord || c.startsWith(resolvedWord),
+    )
+    if (cmds.length === 0) {
+      cmds = CLI.commands.filter((c) => c.includes(resolvedWord))
+    }
 
-  // Load all the commands we need to print into a local variable
-  // and also use the loop to get the length of the longest args
-  let max = 1
-  const commands = {}
-  for (const key of cmds) {
-    commands[key] = CLI.cmd(key)
-    max = Math.max(max, key.length + length(commands[key].args))
-  }
+    // If we don't have a few commands, select all commands
+    if (cmds.length === 0) cmds = CLI.commands
 
-  // Print a summary of all matching commands
-  for (const key of cmds.sort()) {
-    const topic = commands[key]
-    if (topic.hide && !CLI.repl) continue // Hidden commands only in repl
-    const space = ' '.repeat(5 + max - length(topic.args) - key.length)
-    CLI.out(
-      CLI.color.command(`  ${key} ${topic.args}`) +
-        CLI.color.short(space + topic.desc),
-    )
-  }
+    // Load all the commands we need to print into a local variable
+    // and also use the loop to get the length of the longest args
+    let max = 1
+    /** @type {Record<string, ReturnType<CLIContext['cmd']>>} */
+    const commands = {}
+    for (const key of cmds) {
+      commands[key] = CLI.cmd(key)
+      max = Math.max(max, key.length + printLength(commands[key].args))
+    }
 
-  // And if we have just one command, print details on that command
-  if (cmds.length === 1) {
-    const topic = commands[cmds[0]]
-    for (const alias of topic.alt) {
-      CLI.out(CLI.color.command(`  ${alias}`))
+    // Print a summary of all matching commands
+    for (const key of cmds.toSorted()) {
+      const topic = commands[key]
+      if (topic.hide && !CLI.repl) continue // Hidden commands only in repl
+      const space = ' '.repeat(5 + max - printLength(topic.args) - key.length)
+      CLI.out(
+        CLI.color.command(`  ${key} ${topic.args}`) +
+          CLI.color.short(space + topic.desc),
+      )
     }
 
-    CLI.out('')
-    if (CLI.is(topic.help, 'str')) {
-      CLI.out('    ' + CLI.color.help(topic.help))
-    } else {
+    // And if we have just one command, print details on that command
+    if (cmds.length === 1) {
+      const topic = commands[cmds[0]]
+      for (const alias of topic.alt) {
+        CLI.out(CLI.color.command(`  ${alias}`))
+      }
+
+      CLI.out('')
       for (const line of topic.help) {
         CLI.out('    ' + CLI.color.help(line))
       }
     }
-  }
+  },
 }
+
+// Find the length of the printable characters of the string
+/** @param {string} text @returns {number} */
+const printLength = (text) => text.replaceAll(/[<">]/gv, '').length