SS-9501 Dynamic table generation

.github/workflows/static.yml

@@ -33,17 +33,21 @@ jobs:
       MDBOOK_EXTERNAL_LINKS_VERSION: 0.1.2
     steps:
       - uses: actions/checkout@v4
+      - name: Setup mise tools
+        uses: jdx/mise-action@c37c93293d6b742fc901e1406b8f764f6fb19dac # v2.4.4
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
       - name: Install mdBook
         run: |
-          curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf -y | sh
-          rustup update
           cargo install --version ${MDBOOK_VERSION} mdbook
           cargo install --version ${MDBOOK_EXTERNAL_LINKS_VERSION} mdbook-external-links
+      - name: Create docs tables
+        run: npm run docs:create-tables
+      - name: Build with mdBook
+        run: mdbook build
       - name: Setup Pages
         id: pages
         uses: actions/configure-pages@v5
-      - name: Build with mdBook
-        run: mdbook build
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
@@ -59,4 +63,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1 +1,8 @@
 book
+
+# TypeScript
+node_modules
+dist
+.npmrc
+.nx
+*.tsbuildinfo

.husky/pre-commit

@@ -0,0 +1,2 @@
+#!/bin/sh
+npm run docs:validate

.prettierignore

@@ -0,0 +1,2 @@
+# Ignore markdown files
+/src

.prettierrc

@@ -0,0 +1,7 @@
+{
+    "printWidth": 99,
+    "tabWidth": 4,
+    "semi": true,
+    "singleQuote": true,
+    "trailingComma": "es5"
+}

.vscode/settings.json

@@ -0,0 +1,11 @@
+{
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "search.exclude": {
+        "**/.git": true,
+    },
+    "terminal.integrated.defaultProfile.osx": "zsh - work",
+    "js/ts.preferences.includePackageJsonAutoImports": "on",
+    "cSpell.words": [
+        "mdbook"
+    ]
+}

AGENTS.md

@@ -0,0 +1,76 @@
+# AGENTS.md
+
+## Repository purpose
+
+This repository contains example Grasshopper models and their documentation for ShapeDiver. Documentation is built with mdBook from the `src/` directory.
+
+## Important paths
+
+- `src/**/examples.json` — source of truth for example metadata
+- `src/**/definitions.md` — chapter documentation with human-written prose and generated tables
+- `tools/docs-cli/src/utils.ts` — defines `SCHEMA_EXAMPLES`
+- `tools/docs-cli/src/validate.ts` — validation logic
+- `tools/docs-cli/src/createTables.ts` — markdown table generation
+- `book.toml` — mdBook configuration
+
+## Source of truth
+
+Treat these as the canonical sources:
+
+- `src/**/examples.json`
+- human-written prose in `src/**/definitions.md`
+- existing model files provided by humans
+
+Treat generated markdown tables in `src/**/definitions.md` as derived output.
+
+## Hard rules
+
+- Never manually edit generated markdown tables in `src/**/definitions.md`.
+- If table content must change, update `src/**/examples.json` instead.
+- Never create, modify, or rewrite `.ghx`, `.gh`, or `.3dm` files.
+- Do not rename, move, or delete large groups of examples or docs unless the user explicitly asks.
+- Avoid broad structural reorganizations of chapter folders or documentation layout unless explicitly asked.
+
+## Editing guidance
+
+- You may add or edit explanatory prose in `src/**/definitions.md`.
+- Preserve mdBook structure and existing chapter organization unless the user asks for restructuring.
+- AI may help develop repository code, including the docs CLI and related automation.
+
+## Adding or updating examples
+
+Preferred workflow:
+
+1. Use the existing human-provided model artifact in the appropriate chapter folder.
+2. Add or update the matching entry in that chapter's `src/**/examples.json`.
+3. Add explanatory prose to `definitions.md` only when needed.
+4. Do not manually regenerate or rewrite markdown tables unless the user explicitly asks for that local workflow.
+
+## Naming convention
+
+Example files follow this pattern:
+
+`{chapter number}{alphabetical identifier starting from A}-{description}.{extension}`
+
+Example:
+
+`11A-AppBuilder_Tutorial1.ghx`
+
+## Validation
+
+After changing any `src/**/examples.json`, run:
+
+```bash
+npm run docs:validate
+```
+
+This validation is required, but it does not check everything. If your change affects behavior or content not fully covered by the validation script, explicitly warn the user about the remaining unchecked risk.
+
+## Useful commands
+
+```bash
+npm run docs:validate
+mdbook serve .
+```
+
+Use `npm run docs:validate` for metadata validation and `mdbook serve .` for local documentation preview.

README.md

@@ -9,15 +9,31 @@ You can clone this repository to download all models at once.
 
 ### Overview
 
-This repository uses [mdBook](https://rust-lang.github.io/mdBook/) to auto-generate documentation based on [Markdown](https://rust-lang.github.io/mdBook/format/markdown.html). A [GitHub action](.github/workflows/static.yml) is used to deploy to [GitHub pages](https://shapediver.github.io/GrasshopperExampleModels/). 
+This repository uses [mdBook](https://rust-lang.github.io/mdBook/) to auto-generate documentation based on [Markdown](https://rust-lang.github.io/mdBook/format/markdown.html). A [GitHub action](.github/workflows/static.yml) is used to deploy to [GitHub pages](https://shapediver.github.io/GrasshopperExampleModels/).
+
+The source of truth for example metadata is `src/**/examples.json`. Markdown tables in `src/**/definitions.md` are generated from these JSON files and should not be created or edited manually.
+
+### Repository structure
+
+- `src/` contains the mdBook content, example metadata, and model files.
+- `tools/` contains repository tooling. In particular, `tools/docs-cli/` provides the scripts used to validate `examples.json` files and generate markdown tables from them.
 
 ### Guidelines
 
   * Use the `ghx` XML file format of Grasshopper.
+  * Update `examples.json` when changing example metadata.
+  * Add only additional explanatory text manually to Markdown files.
+  * Do not manually create or edit generated markdown tables; they are generated via GitHub workflows.
+
+### Commands
+
+- `npm run docs:validate` validates all `src/**/examples.json` files and checks referenced files.
+- `npm run docs:create-tables` regenerates markdown tables from `src/**/examples.json`.
+- `mdbook serve .` starts a local preview server for the documentation.
 
 ### Local testing
 
-Take the following setup steps to locally test auto-generation of the documentation. 
+Take the following setup steps to locally test auto-generation of the documentation.
 
   * Install [rust](https://www.rust-lang.org/tools/install)
   * Install [mdBook](https://rust-lang.github.io/mdBook/guide/installation.html)
@@ -26,3 +42,5 @@ Take the following setup steps to locally test auto-generation of the documentat
     `cargo install mdbook-external-links`
   * From the root directory of this repository run `mdbook serve .`
 
+In normal workflows, markdown tables are generated through GitHub workflows and should not be created manually.
+

eslint.config.mjs

@@ -0,0 +1,5 @@
+import { defineConfig } from 'eslint/config';
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+
+export default defineConfig([eslint.configs.recommended, ...tseslint.configs.recommended]);

mise.toml

@@ -0,0 +1,4 @@
+[tools]
+node = "24"
+pnpm = "11"
+rust = "stable"

package.json

@@ -0,0 +1,17 @@
+{
+    "name": "root",
+    "private": true,
+    "scripts": {
+        "prepare": "husky",
+        "docs:create-tables": "pnpm --filter @shapediver/docs-cli run create-tables \"${PWD}/src/\"",
+        "docs:validate": "pnpm --filter @shapediver/docs-cli run validate \"${PWD}/src/\""
+    },
+    "devDependencies": {
+        "@eslint/js": "10.0.1",
+        "eslint": "10.2.0",
+        "husky": "9.1.7",
+        "npm-check-updates": "21.0.0",
+        "prettier": "3.8.3",
+        "typescript-eslint": "8.58.2"
+    }
+}