Merge branch 'main' into feat/expand-consoles

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -3,8 +3,6 @@
 name: 🐞 Bug Report
 description: Create a report to help us improve.
 labels: ["potential-bug"]
-assignees:
-  - emmercm
 body:
   - type: markdown
     attributes:
@@ -43,7 +41,11 @@ body:
     attributes:
       label: Debug logs
       description: |
-        The debug logs of the command run with the `-vvv` option.
+        The debug logs of your command run with the `-vvv` option. This is _not_ just a copy of the standard progress bar CLI output.
+
+        You can redirect the CLI output of `igir` to a file with the syntax: `igir [commands..] [options] -vvv > igir.log`. You can then attach this file in the GitHub text editor.
+
+        This field is _not_ optional as it is one of the most important ways to gain insight into your unique scenario. Without this information it is difficult to reproduce your problem.
     validations:
       required: true
 
@@ -66,7 +68,7 @@ body:
       description: |
         What version of Node.js are you running? This can be seen with the `node --version` command.
 
-        You can specify "N/A" when using a standalone version of `igir`.
+        You can specify "N/A" when using a standalone version of `igir` (one downloaded from GitHub).
     validations:
       required: true
 

.github/ISSUE_TEMPLATE/feature-request.yml

@@ -3,8 +3,6 @@
 name: 🚀 Feature Request
 description: Suggest an idea for this project.
 labels: ["enhancement"]
-assignees:
-  - emmercm
 body:
   - type: markdown
     attributes:

.github/labels.yml

@@ -2,7 +2,7 @@
 
 # GitHub defaults
 - name: bug
-  description: Something isn't working
+  description: A confirmed issues that needs fixing
   color: 'd73a4a'
 #- name: dependencies
 #  description: Pull requests that update a dependency file
@@ -25,9 +25,9 @@
 #- name: invalid
 #  description: This doesn't seem right
 #  color: 'e4e669'
-#- name: question
-#  description: Further information is requested
-#  color: 'd876e3'
+- name: question
+  description: Further information is requested
+  color: 'd876e3'
 #- name: wontfix
 #  description: This will not be worked on
 #  color: 'ffffff'
@@ -37,6 +37,14 @@
 #  color: '4c2e9c'
 #  alias: ['enhancement']
 - name: potential-bug
-  color: '66b9cc'
+  description: A potential issue that needs confirmation and/or triage
+  color: '9f06e2'
 - name: security
   color: 'f72e32'
+- name: up-for-grabs
+  description: Issues to consider for external contribution
+  color: '66cc8d'
+
+- name: stale
+  description: Issue has had no recent activity and will be automatically closed
+  color: 'ffffff'

.github/workflows/gh-stale-issues.yml

@@ -0,0 +1,20 @@
+name: GitHub Stale Issues
+
+on:
+  schedule:
+    - cron: '30 1 * * *'
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/stale@v8
+        with:
+          days-before-issue-stale: 14
+          days-before-pr-stale: -1
+          days-before-close: 14
+          stale-issue-message: 'This issue is stale because it has been open 14 days with no activity. Comment or this will be automatically closed in 14 days.'
+          close-issue-message: 'This issue was closed because it has been stalled for 14 days with no activity. Only repository collaborators will be able to re-open this issue.'
+          stale-issue-label: 'stale'
+          only-labels: 'question'
+          exempt-assignees: 'emmercm'

.github/workflows/node-publish.yml

@@ -12,8 +12,12 @@ jobs:
   node-publish:
     runs-on: ubuntu-latest
     permissions:
+      # actions/checkout@v3
       contents: read
+      # `npm publish --provenance`
       id-token: write
+      # thollander/actions-comment-pull-request@v2
+      pull-requests: write
     steps:
       - uses: actions/checkout@v3
       - uses: actions/setup-node@v3

README.md

@@ -56,7 +56,7 @@ $ igir --help
   | $$  | $$|    \  | $$  | $$    $$   ROM collection manager
   | $$  | $$|    \  | $$  | $$    $$   https://igir.io/
   | $$  | $$ \$$$$  | $$  | $$$$$$$\
- _| $$_ | $$__| $$ _| $$_ | $$  | $$   v1.9.3
+ _| $$_ | $$__| $$ _| $$_ | $$  | $$   v1.9.4
 |   $$ \ \$$    $$|   $$ \| $$  | $$
  \$$$$$$  \$$$$$$  \$$$$$$ \$$   \$$
 

docs/input/dats.md

@@ -12,23 +12,71 @@ DATs are catalogs of every known ROM that exists per game system, complete with
 
 These DATs help `igir` distinguish known ROM files in input directories from other files. Because DATs typically contain the complete catalog for a console, `igir` also uses them to generate reports for you on what ROMs were found and which are missing.
 
-`igir` will look for `.dat` files automatically in your working directory, but you can specify a specific location with the `--dat <path>` option:
+`igir` will look for `*.dat` files automatically in your working directory, but you can specify a specific location with the `--dat <path>` option:
 
 ```shell
-igir [commands..] --dat dats/*.dat --input <input>
+igir [commands..] --dat "dats/*.dat" --input <input>
 ```
 
 Or you can specify archives that can contain multiple DATs (such as No-Intro's [daily download](https://datomatic.no-intro.org/index.php?page=download&s=64&op=daily)) with:
 
 ```shell
-igir [commands..] --dat No-Intro*.zip --input <input>
+igir [commands..] --dat "No-Intro*.zip" --input <input>
 ```
 
-**`igir` can process DAT files in [XML](https://github.com/SabreTools/SabreTools/wiki/DatFile-Formats#logiqx-xml-format) and [CMPro](http://www.logiqx.com/DatFAQs/CMPro.php) formats, as well as [Hardware Target Game Database](https://github.com/frederic-mahe/Hardware-Target-Game-Database) SMDBs that contain file sizes.**
+## Just tell me what to do
+
+The rest of this page goes into different types of DATs and different groups of people that publish them. If all you want to do is organize your ROMs with `igir` in some sane way, follow these instructions:
+
+1. Go to the No-Intro DAT-o-MATIC [daily download page](https://datomatic.no-intro.org/index.php?page=download&s=64&op=daily)
+2. Select the "P/C XML" dropdown option (as opposed to "standard DAT") and download the `.zip` to wherever you store your ROMs
+3. Every time you run `igir`, specify the `.zip` file you downloaded with the `--dat <path>` option:
+
+  ```shell
+  igir [commands..] --dat "No-Intro*.zip" --input <input>
+  ```
+
+## Supported DAT formats
+
+There have been a few DAT-like formats developed over the years. `igir` supports the following:
+
+- [Logiqx XML](https://github.com/SabreTools/SabreTools/wiki/DatFile-Formats#logiqx-xml-format) (most common) (No-Intro, Redump, TOSEC, and more)
+- [MAME ListXML](https://easyemu.mameworld.info/mameguide/command_line/frontend_commands/listxml.html) (XML exported by the `mame -listxml` command)
+
+  !!! tip
+
+      Instead of exporting the ListXML to a file yourself, you can also specify a MAME executable for the DAT path and then `igir` is smart enough to parse it:
+
+      === ":simple-windowsxp: Windows"
+
+          Windows is fairly easy, MAME is officially compiled for Windows and downloads can be found on many mirror sites.
+
+          ```batch
+          igir [commands..] --dat "mame0257b_64bit.exe" --input <input>
+          ```
+
+      === ":simple-apple: macOS"
+
+          MAME isn't officially compiled for macOS, you will have to use a third-party release such as [SDL MAME](https://sdlmame.lngn.net/).
+
+          ```shell
+          igir [commands..] --dat "mame0257-x86/mame" --input <input>
+          ```
+
+      === ":simple-linux: Linux"
+
+          Most distros (Ubuntu, Debian, Fedora, etc.) have MAME in their package repositories, but some will require you to compile MAME yourself. If the `mame` executable is in your `$PATH`, you can specify its path like this:
+
+          ```shell
+          igir [commands..] --dat "$(which "mame")" --input <input>
+          ```
+
+- [CMPro](http://www.logiqx.com/DatFAQs/CMPro.php)
+- [Hardware Target Game Database](https://github.com/frederic-mahe/Hardware-Target-Game-Database) SMDBs that contain file sizes
 
 !!! tip
 
-    `igir` supports URLs to DAT files and archives! This is helpful to make sure you're always using the most up-to-date version of a DAT hosted on sites such as GitHub. For example:
+    `igir` supports URLs to DAT files and archives. This is helpful to make sure you're always using the most up-to-date version of a DAT hosted on sites such as GitHub. For example:
 
     ```shell
     igir [commands..] --dat "https://raw.githubusercontent.com/libretro/libretro-database/master/dat/DOOM.dat" --input <input>
@@ -38,24 +86,16 @@ igir [commands..] --dat No-Intro*.zip --input <input>
 
 !!! info
 
-    See the [file scanning docs](file-scanning.md) for more information on specify files with the `--dat` option.
-
-## Just tell me what to do
-
-1. Go to the No-Intro DAT-o-MATIC [daily download page](https://datomatic.no-intro.org/index.php?page=download&s=64&op=daily)
-2. Select the "P/C XML" dropdown option (as opposed to "standard DAT") and download the `.zip` to wherever you store your ROMs
-3. Every time you run `igir`, specify the `.zip` file you downloaded with the `--dat <path>` option:
-
-  ```shell
-  igir [commands..] --dat "No-Intro*.zip" --input <input>
-  ```
+    See the [file scanning docs](file-scanning.md) for more information on specifying file paths with the `--dat <path>` option.
 
 ## DAT groups
 
 A number of different release groups maintain sets of DATs, the most popular are:
 
 - [No-Intro](https://datomatic.no-intro.org/index.php?page=download&s=64&op=daily) (cartridge-based consoles)
 - [Redump](http://redump.org/downloads/) (optical media-based consoles)
+- [progetto-SNAPS](https://www.progettosnaps.net/dats/MAME/) (MAME)
+- [pleasuredome](https://pleasuredome.github.io/pleasuredome/mame/) (MAME)
 
 And some less popular release groups are:
 
@@ -66,8 +106,6 @@ And some less popular release groups are:
   - [Mirrored DATs](https://github.com/libretro/libretro-database/tree/master/metadat) (No-Intro and Redump/trurip/TOSEC DATs)
   - [FinalBurn NEO](https://github.com/libretro/FBNeo/tree/master/dats) (arcade, gen 1-4 consoles)
 - [ADVANsCEne](https://www.advanscene.com/html/dats.php) (GBA, DS, 3DS, PSP, PS Vita)
-- [progetto-SNAPS](https://www.progettosnaps.net/dats/MAME/) (MAME)
-- [pleasuredome](https://pleasuredome.github.io/pleasuredome/mame/) (MAME)
 
 ## Parent/clone (P/C) DATs
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "igir",
-  "version": "1.9.3",
+  "version": "1.9.4",
   "description": "🕹 A video game ROM collection manager to help filter, sort, patch, archive, and report on collections on any OS.",
   "keywords": [
     "1g1r",
@@ -105,6 +105,7 @@
     "@types/semver": "7.5.0",
     "@types/tar": "6.1.5",
     "@types/unzipper": "0.10.6",
+    "@types/which": "3.0.0",
     "@types/xml2js": "0.4.11",
     "@types/yargs": "17.0.24",
     "@typescript-eslint/eslint-plugin": "6.4.1",
@@ -123,7 +124,8 @@
     "strip-ansi": "7.1.0",
     "ts-jest": "29.1.1",
     "ts-node": "10.9.1",
-    "typescript": "5.2.2"
+    "typescript": "5.2.2",
+    "which": "4.0.0"
   },
   "//engines": [
     "Requires ^12.20.0 || ^14.13.1 || >=16.0.0 for ES6 modules, even though `tsc` can target ES5 or lower.",