Publish @minecraft/api-docs-generator and @minecraft/markup-generators-plugin

.github/workflows/pull-request.yml

@@ -16,4 +16,4 @@ jobs:
         with:
           node-version: 22
       - run: npm ci
-      - run: npm run test
+      - run: npm run test:ci

.github/workflows/release-changes.yml

@@ -20,7 +20,7 @@ jobs:
         with:
           node-version: 22
       - run: npm ci
-      - run: npm run test # Fully build the repo so we have artifacts available to create releases, include tests so we don't ship in a broken state
+      - run: npm run test:ci # Fully build the repo so we have artifacts available to create releases, include tests so we don't ship in a broken state
 
       - name: Set git credentials
         run: |

.gitignore

@@ -1,8 +1,44 @@
+# dependencies
+node_modules
+.pnp
+.pnp.js
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+.pnpm-debug.log*
+
+# local env files
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# turbo
 .turbo
+
+# git
+*.orig
+
+# build output
+build
+dist
 lib
 lib-cjs
-dist
 temp
-node_modules
+
+# test outputs
+**/*output/
+*.log
+
+# api-docs-generator output
+out/
+tsconfig*/
+
+# packages
 *.tgz
-*.zip
+*.zip

.prettierignore

@@ -0,0 +1,6 @@
+node_modules
+build
+dist
+lib
+lib-cjs
+out

.vscode/extensions.json

@@ -0,0 +1,9 @@
+{
+    "recommendations": [
+        "attilabuti.mustache-syntax-vscode",
+        "dbaeumer.vscode-eslint",
+        "esbenp.prettier-vscode",
+        "shd101wyy.markdown-preview-enhanced",
+        "spadin.memento-inputs"
+    ]
+}

.vscode/launch.json

@@ -0,0 +1,119 @@
+{
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "API Docs Generator - Launch",
+      "console": "integratedTerminal",
+      "preLaunchTask": "build: api-docs-generator",
+      "outputCapture": "std",
+      "skipFiles": [
+        "<node_internals>/**"
+      ],
+      "program": "${workspaceFolder}/core/api-docs-generator/lib/src/cli.js",
+      "args": [
+        "-i",
+        "${input:metadataInputDirectory}",
+        "-o",
+        "${workspaceFolder}/out"
+      ]
+    },
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "API Docs Generator - Launch Specific Generators",
+      "console": "integratedTerminal",
+      "preLaunchTask": "build: api-docs-generator",
+      "outputCapture": "std",
+      "skipFiles": [
+        "<node_internals>/**"
+      ],
+      "program": "${workspaceFolder}/core/api-docs-generator/lib/src/cli.js",
+      "args": [
+        "-i",
+        "${input:metadataInputDirectory}",
+        "-o",
+        "${workspaceFolder}/out",
+        "-g",
+        "${input:generators}"
+      ]
+    },
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "API Docs Generator - Run All Tests",
+      "console": "integratedTerminal",
+      "preLaunchTask": "build: api-docs-generator-test-snapshots",
+      "outputCapture": "std",
+      "skipFiles": [
+        "<node_internals>/**",
+      ],
+      "runtimeExecutable": "npm",
+      "runtimeArgs": [
+        "run",
+        "test",
+        "--",
+        "--only",
+        "--filter=api-docs-generator-test-snapshots..."
+      ],
+    },
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "API Docs Generator - Run Specific Tests",
+      "console": "integratedTerminal",
+      "preLaunchTask": "build: api-docs-generator-test-snapshots",
+      "outputCapture": "std",
+      "skipFiles": [
+        "<node_internals>/**",
+      ],
+      "runtimeExecutable": "npm",
+      "runtimeArgs": [
+        "run",
+        "test",
+        "--",
+        "--only",
+        "--filter=api-docs-generator-test-snapshots...",
+        "--",
+        "--test",
+        "${input:test}"
+      ],
+    },
+  ],
+  "inputs": [
+    {
+      "id": "metadataInputDirectory",
+      "type": "command",
+      "command": "memento.promptString",
+      "args": {
+        "id": "metadataInputDirectory",
+        "description": "Path to input metadata files",
+        "default": "${workspaceFolder}/../bedrock-samples/metadata"
+      }
+    },
+    {
+      "id": "generators",
+      "type": "command",
+      "command": "memento.promptString",
+      "args": {
+        "id": "generators",
+        "description": "List of generators to run",
+        "default": "ts msdocs"
+      }
+    },
+    {
+      "id": "test",
+      "type": "command",
+      "command": "memento.promptString",
+      "args": {
+        "id": "test",
+        "description": "Pattern for test files to run",
+        "default": "general"
+      }
+    }
+  ]
+}

.vscode/settings.json

@@ -1,11 +1,22 @@
 {
-    "eslint.experimental.useFlatConfig": true,
-    "eslint.workingDirectories": [
-        {
-            "pattern": "./libraries/*/"
-        },
-        {
-            "pattern": "./tools/*/"
-        }
-    ]
-}
+    "eslint.useFlatConfig": true,
+    "eslint.workingDirectories":  [{"mode": "auto"}],
+    "debug.javascript.terminalOptions": {
+        "skipFiles": ["<node_internals>/**"]
+    },
+    "[javascript]": {
+        "editor.formatOnSave": true,
+        "editor.defaultFormatter": "esbenp.prettier-vscode"
+    },
+    "[typescript]": {
+        "editor.formatOnSave": true,
+        "editor.defaultFormatter": "esbenp.prettier-vscode"
+    },
+    "files.exclude": {
+        ".turbo": true,
+        "dist": true,
+        "lib": true,
+        "lib-cjs": true,
+        "node_modules": true
+    },
+}

.vscode/tasks.json

@@ -0,0 +1,49 @@
+{
+    // See https://go.microsoft.com/fwlink/?LinkId=733558
+    // for the documentation about the tasks.json format
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "build: all",
+            "type": "npm",
+            "script": "build",
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            }
+        },
+        {
+            "label": "build: api-docs-generator",
+            "type": "npm",
+            "script": "build -- -- --filter=@minecraft/api-docs-generator... --filter=@minecraft/markup-generators-plugin...",
+            "group": {
+                "kind": "build"
+            }
+        },
+        {
+            "label": "build: api-docs-generator-test-snapshots",
+            "type": "npm",
+            "script": "build -- -- --filter=api-docs-generator-test-snapshots...",
+            "group": {
+                "kind": "build"
+            }
+        },
+        {
+            "label": "test: all",
+            "type": "npm",
+            "script": "test",
+            "group": {
+                "kind": "test",
+                "isDefault": true
+            }
+        },
+        {
+            "label": "test: api-docs-generator",
+            "type": "npm",
+            "script": "test -- -- --filter=api-docs-generator-test-snapshots...",
+            "group": {
+                "kind": "test"
+            }
+        }
+    ]
+}

CONTRIBUTING.md

@@ -15,8 +15,19 @@ or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any addi
 
 ## Specific Guidelines
 
-Contributions to these libraries are welcome! These libraries are maintained by Mojang but we are open to contributions and bug fixes. In general, we consider the backwards compatibility and versioning to be the absolute top priority when making changes to the libraries. Because of this, we strictly adhere to semver for changes, and libraries depend on minecraft modules at specific major versions as well. Any PR submitted to any library **must** contain a change file using the beachball tool to indicate the severity of the change. When a change is submitted, it will automatically update versions and publish to NPM via our pipelines.
+Contributions to these libraries are welcome! These libraries are maintained by Mojang but we are open to contributions and bug fixes. In general, we consider the backwards compatibility and versioning to be the absolute top priority when making changes to the libraries. Because of this, we strictly adhere to SemVer for changes, and libraries depend on Minecraft modules at specific major versions as well.
 
-### Naming
+### Use Beachball Versioning
 
-We generally follow the naming conventiosn specified by the [google style guide](https://google.github.io/styleguide/jsguide.html#naming). There is other general good practice within the style guide as well, though generally the vast majority of our style is enforced via a combination of ESLint and prettier enforcement at PR time.
+All PRs submitted for any package **must** contain a change file using the Beachball tool to indicate the severity of the change. When a change is submitted, it will automatically update versions and publish to NPM via our pipelines. Use `npm run change` to generate changefiles with Beachball.
+
+### Use a Consistent Coding Style
+
+- Use ESLint to lint (`npm run lint`)
+- Use Prettier to style
+  - VS Code is set up to format on save
+  - The lint command also runs Prettier and can fix issues: `npm run lint:fix`
+
+#### Naming
+
+We generally follow the naming conventions specified by the [Google Style Guide](https://google.github.io/styleguide/jsguide.html#naming). There are other general good practices within the style guide as well, though generally the vast majority of our style is enforced via a combination of ESLint and Prettier enforcement at PR time.

README.md

@@ -1,14 +1,14 @@
 # minecraft-scripting-libraries
 
-This repository contains a set of scripting libraries for use with the minecraft scripting modules in creating content for the game. The repository is structured as a javascript "monorepo" that contains multiple packages. These packages are fully javascript and are typically intended to server as helper libraries that can be commonly used when creating content. The libraries are provided both through NPM, but also in pre-bundled forms in cases where user workflows do not leverage techniques such as bundling for their own content creation.
+This repository contains a set of scripting libraries for use with the Minecraft Scripting modules in creating content for the game. The repository is structured as a javascript "monorepo" that contains multiple packages. These packages are fully javascript and are typically intended to server as helper libraries that can be commonly used when creating content. The libraries are provided both through NPM, but also in pre-bundled forms in cases where user workflows do not leverage techniques such as bundling for their own content creation.
 
 More details on each individual library are in the README files for individual packages. The packages are located generally within the libraries subfolder.
 
 # Working in the repository
 
 ## Prerequisites
 
-1. Install the latest LTS of [Node](https://nodejs.org/en/download) (20 or higher) and confirm after installation that you have NPM 10 or higher also installed.
+1. Install the latest LTS of [Node](https://nodejs.org/en/download) (22.x or higher) and confirm after installation that you have NPM 10 or higher also installed.
     1. It is recommended to use [nvm](https://github.com/nvm-sh/nvm) or [nvm-windows](https://github.com/coreybutler/nvm-windows) for ease of management of node version installation.
 1. Globally install the [turbo tool](https://turbo.build/repo/docs/installing) using the command `npm install --global turbo`. The turbo tool is used under the covers for all of the build scripts, and having it accessible globally is convenient for running builds from subdirectories as well.
 
@@ -34,7 +34,7 @@ This will build all packages in this repository in the right order using `turbo`
 
 ## Linting
 
-All packages are validated via ESLint with a consistent set of rules as well as enforces styling through prettier. To explicitly run linting, use `npm run lint`, and some changes can be fixed automatically with `npm run lint -- --fix`
+All packages are validated via ESLint with a consistent set of rules as well as enforces styling through prettier. To explicitly run linting, use `npm run lint`, and some changes can be fixed automatically with `npm run lint:fix`
 
 ## Testing
 
@@ -46,4 +46,4 @@ See [Contributing.md](./CONTRIBUTING.md) for details on contributions
 
 ## Trademark Notice
 
-Trademarks This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft’s Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party’s policies.
+Trademarks This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft’s Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party’s policies.

change/@minecraft-api-docs-generator-4e3a7c3a-5ef5-4878-9242-1220c2d4833a.json

@@ -0,0 +1,7 @@
+{
+  "type": "major",
+  "comment": "Add api-docs-generator and markup-generators-plugin",
+  "packageName": "@minecraft/api-docs-generator",
+  "email": "zachary.campbell@skyboxlabs.com",
+  "dependentChangeType": "none"
+}

change/@minecraft-core-build-tasks-6ee12b91-8f5b-49b9-970f-5469ec88a6a8.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Update core-build-tasks publishRelease to support uploading NPM tarballs",
+  "packageName": "@minecraft/core-build-tasks",
+  "email": "zachary.campbell@skyboxlabs.com",
+  "dependentChangeType": "none"
+}

change/@minecraft-markup-generators-plugin-fffee401-e694-444c-bdc5-fa766de60f8b.json

@@ -0,0 +1,7 @@
+{
+  "type": "major",
+  "comment": "Add api-docs-generator and markup-generators-plugin",
+  "packageName": "@minecraft/markup-generators-plugin",
+  "email": "zachary.campbell@skyboxlabs.com",
+  "dependentChangeType": "none"
+}

change/eslint-plugin-minecraft-linting-6adf84ca-0db6-4fe2-9a70-133c859bd0c2.json

@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "Increase test timeouts",
+  "packageName": "eslint-plugin-minecraft-linting",
+  "email": "zachary.campbell@skyboxlabs.com",
+  "dependentChangeType": "none"
+}