Merge pull request #49 from TMHSDigital/review-fixes

Fixes from the repo review (#1 to #47)

Author: TMHSDigital

.github/ISSUE_TEMPLATE/new-source.yml

@@ -31,6 +31,7 @@ body:
         - characters
         - audio
         - animation
+        - video
         - environment
         - shaders-vfx
         - fonts

.github/PULL_REQUEST_TEMPLATE.md

@@ -2,12 +2,15 @@
 
 - [ ] New catalog entry
 - [ ] License / metadata correction
+- [ ] Starter stack
 - [ ] Docs or site
 
 ## Checklist
 
-- [ ] Copied `catalog/TEMPLATE.md` (new entries)
+- [ ] Started from `node site/new-entry.mjs <category> <id>` or copied `catalog/TEMPLATE.md` (new entries)
 - [ ] `id` is unique across the whole catalog
-- [ ] Live license checked today; `active` entries have dated `## Evidence`
-- [ ] Bumped `expectedEntryCount` in `site/config.json`
-- [ ] `node site/validate.mjs` passes
+- [ ] Live license checked today; `## Evidence` has a dated line quoting it
+- [ ] Row added to the category `README.md`, with the same licence as the frontmatter
+- [ ] Ran `node site/sync-counts.mjs` after adding or removing entries
+- [ ] Stacks: followed `stacks/README.md`; no licence named in a stack's own words
+- [ ] `npm run check` passes (tests, `node site/validate.mjs`, `node site/build.mjs`)

.github/dependabot.yml

@@ -0,0 +1,8 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+    commit-message:
+      prefix: ci

.github/workflows/ci.yml

@@ -1,27 +1,27 @@
 name: Validate catalog
 
+# No path filters: the build reads catalog/, stacks/, docs/, site/ and the
+# top-level Markdown files, and the whole run takes seconds.
 on:
   pull_request:
   push:
     branches: [main]
-    paths:
-      - "catalog/**"
-      - "docs/**"
-      - "site/**"
-      - "README.md"
-      - ".github/workflows/ci.yml"
+  workflow_call:
+
+permissions:
+  contents: read
 
 jobs:
   validate:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
       - name: Setup Node
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v7
         with:
-          node-version: "20"
+          node-version-file: .nvmrc
 
       - name: Test catalog checks
         run: node site/checks.test.mjs

.github/workflows/links.yml

@@ -0,0 +1,44 @@
+name: Check source links
+
+# Weekly: fetch every entry's url, and open or update one issue listing dead
+# links, sources that moved, and entries whose licence check is over a year
+# old. It never edits an entry: each one needs its licence re-read first.
+on:
+  schedule:
+    - cron: "41 7 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  links:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Setup Node
+        uses: actions/setup-node@v7
+        with:
+          node-version-file: .nvmrc
+
+      - name: Check links
+        id: check
+        run: node site/check-links.mjs --report link-report.md
+
+      - name: Open or update the report issue
+        if: steps.check.outputs.problems != '0'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PROBLEMS: ${{ steps.check.outputs.problems }}
+        run: |
+          title="Link check: ${PROBLEMS} sources need a look"
+          existing=$(gh issue list --state open --label correction --json number,title \
+            --jq '[.[] | select(.title | startswith("Link check:"))][0].number // empty')
+          if [ -n "$existing" ]; then
+            gh issue edit "$existing" --title "$title" --body-file link-report.md
+          else
+            gh issue create --title "$title" --label correction --body-file link-report.md
+          fi

.github/workflows/pages.yml

@@ -3,11 +3,6 @@ name: Deploy GitHub Pages
 on:
   push:
     branches: [main]
-    paths:
-      - "catalog/**"
-      - "docs/**"
-      - "site/**"
-      - ".github/workflows/pages.yml"
   workflow_dispatch:
   # Weekly rebuild so the freshness ages never lag the calendar by more than
   # about a week when nothing is pushed.
@@ -24,30 +19,27 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  # The same tests, validation and page checks as a pull request runs.
+  validate:
+    uses: ./.github/workflows/ci.yml
+
   build:
+    needs: validate
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
       - name: Setup Node
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v7
         with:
-          node-version: "20"
-
-      - name: Test catalog checks
-        run: node site/checks.test.mjs
-      - name: Test site build modules
-        run: node site/lib/lib.test.mjs
-
-      - name: Validate catalog
-        run: node site/validate.mjs
+          node-version-file: .nvmrc
 
       - name: Build site
         run: node site/build.mjs
 
       - name: Upload Pages artifact
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@v5
         with:
           path: site/dist
 
@@ -60,4 +52,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5

.gitignore

@@ -19,6 +19,9 @@ Desktop.ini
 .vscode/
 .idea/
 
+# Dependencies (the repo has none, but npx and editors may add them)
+node_modules/
+
 # Logs / caches
 *.log
 __pycache__/

.nvmrc

@@ -0,0 +1 @@
+24

CONTRIBUTING.md

@@ -21,20 +21,16 @@ Please follow the [Code of Conduct](CODE_OF_CONDUCT.md).
 
 ## Adding an entry
 
-One new markdown file is enough — the website rebuilds from frontmatter on deploy.
-
-1. Copy [`catalog/TEMPLATE.md`](catalog/TEMPLATE.md).
-2. Save it as `catalog/<category>/<id>.md` using a short kebab-case `id`.
-3. Fill every frontmatter field. Prefer primary URLs over mirror/aggregator pages.
-4. `id` must be unique across the **whole** catalog. A mixed kit already listed in another category is a duplicate, not a second entry.
-5. Verify the license on the live source page the day you submit.
-6. For `status: active`, include an `## Evidence` line with a short quote from that page.
-7. Bump `expectedEntryCount` in [`site/config.json`](site/config.json) by the number of files you added (or lowered if you removed some).
-8. Run `node site/validate.mjs` — it must exit 0.
-9. Run `node site/build.mjs`. It renders your entry's page and fails if the body uses markdown the site does not support (tables, code fences, blockquotes, images, raw HTML, `###` headings, numbered lists) or links to a file that does not exist.
-10. Optional 2D/UI fields: `grid_dimensions`, `camera_perspective`, `hardware_tags`, `attribution_string` (see [`TEMPLATE.md`](catalog/TEMPLATE.md)).
-11. Add a row to the matching category `README.md`. This is required: the validator fails an entry that is not listed there, and the row's licence cell must match your frontmatter.
-12. Optional: add the `id` to `site/config.json` → `featured` to pin it under Safe starting points.
+The website rebuilds from frontmatter on deploy. Node 22 or newer is all you need; there
+are no dependencies to install.
+
+1. Run `node site/new-entry.mjs <category> <id>` (or `npm run new-entry -- <category> <id>`). It copies [`catalog/TEMPLATE.md`](catalog/TEMPLATE.md) to `catalog/<category>/<id>.md` with the id, category and today's date filled in, and refuses an id already used anywhere in the catalog. Use a short kebab-case `id`; a mixed kit already listed in another category is a duplicate, not a second entry.
+2. Verify the license on the live source page the day you submit, and fill every frontmatter field from it (rules below). Prefer primary URLs over mirror/aggregator pages.
+3. Write the body: a one-paragraph summary, `## Notes`, and `## Evidence` with a dated line quoting the source, such as `- Live page (2026-09-25): "Free for commercial use"`. Every Evidence section needs at least one date, and `verified` may not be newer than the newest one. The scaffold starts at `status: needs-review`; set `active` once the licence, the commercial stance and the credit requirement are all settled.
+4. Add a row to the matching category `README.md`. This is required: the validator fails an entry that is not listed there, and the row's licence cell must match your frontmatter.
+5. Run `node site/sync-counts.mjs` (`npm run counts`). It updates every place the repo restates the entry count: both category count tables, the README badge and "Browse N sources" line, and `expectedEntryCount` in [`site/config.json`](site/config.json).
+6. Run `npm run check`: the check tests, `node site/validate.mjs` and `node site/build.mjs`, all of which must pass. The build renders your entry's page and fails if the body uses markdown the site does not support (tables, code fences, blockquotes, images, raw HTML, `###` headings, numbered lists) or links to a file that does not exist.
+7. Optional: add the `id` to `site/config.json` → `featured` to pin it under Safe starting points.
 
 To add a starter stack (one pick per need for a kind of game), follow [`stacks/README.md`](stacks/README.md).
 
@@ -44,13 +40,15 @@ To add a starter stack (one pick per need for a kind of game), follow [`stacks/R
 - `license_spdx`: the SPDX identifier the vocabulary maps your `license` to. The validator rejects a missing one when a mapping exists, and an invented one when it does not.
 - `commercial`: `true` / `false` / `unknown` / `varies`. Use `varies` for aggregators where some files are commercial-ok and others are not. The site still shows these under Commercial OK, labeled **per-file review**, so they are not silently excluded and not silently treated as a blanket grant.
 - `attribution_required`: `true` / `false` / `unknown`. If the licence normally requires credit (CC-BY) but the publisher waives it, set `false` and add a `- Attribution waived:` line in Notes saying so.
-- `attribution_string`: optional copy-paste credit.
+- `attribution_string`: the copy-paste credit line. Required when `attribution_required` is `true`; optional otherwise.
 - `publisher`: optional. Name the **rights-holding publisher**, never the host. Set it whenever that publisher has more than one catalog entry, so the entries group; setting it on a publisher that currently has only one entry is also fine and saves a backfill later. Do not set it to a generic host or distributor (GitHub, Hugging Face, itch.io, OpenGameArt, the Internet Archive, Google Fonts) or to a distributor that does not hold the rights. Distinguish sibling organisations that are genuinely different rights holders: `blender.md` (the application, Blender Foundation) carries no `publisher`, while the asset bundles under `studio.blender.org` carry `Blender Studio`. Kenney, Quaternius, KayKit, LuizMelo, 0x72, Blender Studio, Material Maker, Alif Type, GGBotNet and 3dmodelscc0 are the largest groups in use today; treat that as illustrative, not as the permitted set.
-- `subcategories`: lower-case kebab-case (`base-meshes`, `field-recordings`). Reuse a value already in the catalog before inventing one, and do not add a variant of an existing value that differs only in plural or spelling. Where both forms were in use, the more common one was kept (`characters`, `environment`, `interior`, `tileset`, `vectors`).
+- `subcategories`: lower-case kebab-case (`base-meshes`, `field-recordings`). Reuse a value already in the catalog before inventing one, and do not add a variant of an existing value that differs only in plural or spelling. Where both forms were in use, the more common one was kept (`characters`, `environment`, `interior`, `tileset`, `vectors`, `pixel`, `impulse-responses`, `base-meshes`). Retired spellings are listed in [`site/value-aliases.json`](site/value-aliases.json), which the validator enforces (V19); add a line there when you merge two values.
 - `formats`: what you actually get, in one of four kinds. **File formats**, as commonly written: usually upper case (`PNG`, `FBX`, `JSON`, `VOX`), tool-specific ones as the tool writes them (`gdshader`, `tmx`, `ktx2`). **Engine or language targets**, as the product writes them (`glTF`, `Godot`, `Unity`, `Python`, `React`). **Delivery types** for software with no file format of its own, lower-case kebab-case (`godot-addon`, `blender-extension`, `npm`, `cli`, `library`, `desktop-app`, `mobile-app`, `middleware`, `model`). And `various` for an aggregator whose files come in too many formats to list. Platforms (`windows`, `macos`, `ios`) and descriptions (`heightfield`, `examples`) are `tags`, not formats. Reuse the spelling already in the catalog.
+- Frontmatter is one `key: value` per line; lists are `[a, b]` or indented `- item` lines. A key given twice is an error. Entry files may not contain emoji.
 - `grid_dimensions` / `camera_perspective` / `hardware_tags`: optional metadata for 2D and UI entries. `3d` and `characters` entries leave `camera_perspective` out: it describes a 2D camera, and those entries have none.
-- `verified`: ISO date (`YYYY-MM-DD`) of your last license check.
-- `status`: `active` | `needs-review` | `deprecated`. `active` means the licence, the commercial stance and the credit requirement are all settled: an `unknown` in `license`, `commercial` or `attribution_required` keeps an entry at `needs-review`. The validator enforces this (V14), and rejects `formats`, `subcategories` or `tags` values that differ only by case, punctuation or a trailing "s" from one already in use (V13).
+- `url`: an `https://` address (`http://` only where the source has no https). Other schemes are rejected.
+- `verified`: ISO date (`YYYY-MM-DD`) of your last license check. It must be a real date, no later than tomorrow in UTC, and no newer than the newest date in `## Evidence` (V8): a new `verified` date needs a new dated Evidence line from the same check. Dates inside URLs do not count as Evidence dates.
+- `status`: `active` | `needs-review` | `deprecated`. A `deprecated` entry needs a `- Deprecated:` line in its body giving the reason (V9). `active` means the licence, the commercial stance and the credit requirement are all settled: an `unknown` in `license`, `commercial` or `attribution_required` keeps an entry at `needs-review`. The validator enforces this (V14), and rejects `formats`, `subcategories` or `tags` values that differ only by case, punctuation or a trailing "s" from one already in use (V13).
 
 ## License verification checklist
 

README.md

@@ -268,11 +268,14 @@ and follow the [Code of Conduct](CODE_OF_CONDUCT.md).
 <details>
 <summary>Run the checks and preview the site locally</summary>
 
+Node 22 or newer; there is nothing to install.
+
 ```bash
-node site/checks.test.mjs   # the checks, against known-bad fixtures
-node site/validate.mjs      # the catalog, against the checks
-node site/build.mjs         # builds the site into site/dist
-npx --yes serve site/dist   # preview at http://localhost:3000
+npm run check    # all of the below, in the order CI runs them
+npm test         # the checks against known-bad fixtures, and the site modules' tests
+npm run validate # the catalog, against the checks (node site/validate.mjs)
+npm run build    # builds the site into site/dist (node site/build.mjs)
+npm run serve    # preview at http://localhost:3000
 ```
 
 </details>
@@ -297,14 +300,19 @@ npx --yes serve site/dist   # preview at http://localhost:3000
 │   ├── godot-budget-stack.md research-index.md
 │   ├── review-ledger.md        every review pass and what it changed
 │   └── images/readme/          publisher stills used in this README
+├── stacks/                     starter stacks: one pick per need for a kind of game
 ├── site/
 │   ├── validate.mjs            catalog integrity checks
 │   ├── checks.mjs              the checks, as pure functions
 │   ├── checks.test.mjs         fixtures proving each check fails on bad input
+│   ├── new-entry.mjs           starts an entry from the template
+│   ├── sync-counts.mjs         rewrites every restated entry count
 │   ├── license-vocabulary.json the licence values the catalog accepts
 │   ├── spdx-allowed.json       SPDX identifiers in use
 │   ├── build.mjs config.json   static site generator and its settings
+│   ├── lib/                    page renderers and shared helpers, with lib.test.mjs
 │   └── public/                 page, styles and script
+├── package.json                npm scripts only; no dependencies
 └── RESEARCH/README.md          research archive index (drafts are gitignored)
 ```