@matfsw/docusaurus-plantuml-plugin 1.5.0 → 1.5.2

package/CHANGELOG.md

@@ -7,6 +7,64 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.5.2] - 2026-08-20
+
+### Changed
+
+- **Development dependencies:** `jsdom` `26` → `29`, `@testing-library/jest-dom` `7.0.0` → `7.0.1`,
+  `@testing-library/user-event` `14.6.3` → `14.6.5`, `@types/node` `26.1.2` → `26.2.0`, `globals`
+  `17.9.0` → `17.11.0`, `typescript-eslint` `8.66.0` → `8.67.0`. No product code changed; all 651
+  tests pass unchanged.
+
+  jsdom 27 added `@exodus/bytes`, which needs `@noble/hashes` `^1.8.0 || ^2.0.0`, while
+  `@docusaurus/core`'s dev server reaches `pkijs`, which pins that package to **exactly** `1.4.0`.
+  npm 11 hoists `1.4.0` and leaves the tree invalid without saying so; npm 10 — what Node 20 and
+  22 ship, and what CI therefore runs — correctly refuses the resulting lockfile with
+  `Missing: @noble/hashes@2.3.0`. An `overrides` entry pins `@noble/hashes` to `^1.8.0`, which
+  both consumers accept. Overrides apply only to this repository's own installs, never to a
+  consumer's.
+
+  `.github/dependabot.yml` now ignores **jsdom 30 and above**. jsdom 30 requires Node
+  `^22.22.2 || ^24.15.0 || >=26.0.0`, dropping Node 20 outright, and the honest consequence of
+  taking it would be raising this package's `engines.node`. That is not ours to raise:
+  `@docusaurus/core` still declares `node: >=20.0` as of 3.10.2, and a plugin whose floor sits
+  above its host's cannot be installed into a site Docusaurus itself supports. jsdom 29 still
+  supports `^20.19.0`, which is what `.nvmrc` pins.
+
+### Fixed
+
+- **The Dependabot branch refresh no longer races GitHub.** It selected pull requests by
+  `mergeStateStatus == "BEHIND"`, but GitHub recomputes that field asynchronously after a push to
+  the base branch — on its first live run it reported nothing behind while two pull requests were
+  ten commits behind. It now asks `compare` for `behind_by`, which is computed on demand.
+
+- `actions/create-github-app-token` and `dependabot/fetch-metadata` were pinned at `v2`; both are
+  at `v3`.
+
+## [1.5.1] - 2026-08-20
+
+### Changed
+
+- **Dependency updates merge themselves, and releases are cut by CI rather than from a laptop.**
+  Dependabot now opens **one** pull request a week for npm — covering the plugin and the example
+  site together — and one for GitHub Actions. Minor and patch updates auto-merge once the new
+  `CI complete` check is green; majors ride in the same pull request and are held for review with
+  a comment naming what holds them.
+
+  Every green `main` then runs `.github/workflows/release.yml`, which reads `## [Unreleased]` to
+  decide the version (`### Removed` or `BREAKING` → major, `### Added` → minor, anything else →
+  patch, empty → no release), bumps `package.json` and `package-lock.json`, closes the section
+  into a dated one, and pushes the commit and the tag **atomically**. The old
+  `npm version && git push --follow-tags` recipe could leave a tag pointing at a pre-rebase commit
+  whenever a dependency pull request landed in between — and `verify:tag` could not see it,
+  because the tag and `package.json` agreed. `publish.yml` now also creates the GitHub Release,
+  after npm has accepted the publish. Recorded in
+  [ADR 0006](docs/adr/0006-automated-release-from-changelog.md).
+
+- `npm run sync:check` now also asserts that `package-lock.json`'s `version` fields match
+  `package.json`, and `npm run sync:meta` fixes them. That drift had to be repaired by hand once
+  already.
+
 ## [1.5.0] - 2026-08-14
 
 ### Added
@@ -482,7 +540,9 @@ Initial release.
   opt-out.
 - Plugin option validation that rejects unknown keys and out-of-range values at build time.
 
-[Unreleased]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.5.0...HEAD
+[Unreleased]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.5.2...HEAD
+[1.5.2]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.5.1...v1.5.2
+[1.5.1]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.5.0...v1.5.1
 [1.5.0]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.4.0...v1.5.0
 [1.4.0]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.3.1...v1.4.0
 [1.3.1]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.3.0...v1.3.1

package/README.md

@@ -1245,11 +1245,35 @@ DOT-only page that proves the PlantUML engine is never fetched for it.
 
 ## Release process
 
-Releases are triggered by pushing a version tag:
+Releases are automatic. Nothing is run from a local checkout, and nothing is tagged by hand.
+
+Every merge into `main` runs CI; when CI goes green, `.github/workflows/release.yml` reads
+`CHANGELOG.md` and decides whether the merge warrants a release and at what level:
+
+| `## [Unreleased]` contains                         | Release |
+| -------------------------------------------------- | ------- |
+| `### Removed`, or the word `BREAKING`              | major   |
+| `### Added`                                        | minor   |
+| any other section (`Fixed`, `Changed`, `Security`) | patch   |
+| nothing, but only dependency bumps since the tag   | patch   |
+| nothing else                                       | none    |
+
+That is why `CONTRIBUTING.md` insists on a `## [Unreleased]` entry in every pull request: the
+entry is what sets the version. Dependency-only merges need no entry — the workflow writes one
+from the commit subjects.
+
+Having decided, the workflow runs `scripts/next-release.mjs`, which bumps `package.json` and
+`package-lock.json`, closes `## [Unreleased]` into a dated section, opens a fresh empty one and
+adds the compare link at the foot of the changelog. It then pushes the `Release <version>`
+commit and the `v<version>` tag **atomically** — both land or neither does, so a tag can never
+describe a tree that is not on `main`. If `main` moved underneath, it rebuilds the release from
+the new `main` rather than forcing anything.
+
+To release a specific version, or to see what would happen without touching anything:
 
 ```bash
-npm version 1.2.3          # updates package.json and creates the v1.2.3 tag
-git push --follow-tags
+gh workflow run release.yml -f dry_run=true      # decide and print, push nothing
+gh workflow run release.yml -f version=2.0.0     # release a version explicitly
 ```
 
 Pushing `v<version>` runs `.github/workflows/publish.yml`, which:
@@ -1262,6 +1286,9 @@ Pushing `v<version>` runs `.github/workflows/publish.yml`, which:
    match the `version` in `package.json` (tag `v1.2.3` ⇒ version `1.2.3`).
 4. Publishes with `npm publish --access public` — the package is scoped, so `--access public`
    is required for the first and every subsequent publish.
+5. Creates the GitHub Release, with that version's changelog section as its notes. This runs
+   only after npm has accepted the publish, so a GitHub Release never exists without the npm
+   release behind it.
 
 Prereleases follow the same path: a version like `1.2.3-beta.1` is published under a
 non-`latest` dist-tag, so `npm install @matfsw/docusaurus-plantuml-plugin` keeps resolving to
@@ -1270,7 +1297,13 @@ the last stable release.
 Authentication is npm **trusted publishing** over GitHub Actions OIDC. There is no long-lived
 npm token anywhere in this repository, in its workflows, or in its secrets. The workflow runs
 in a GitHub environment named `npm`, so maintainers can require manual approval before a
-release proceeds. Provenance is attested automatically by trusted publishing.
+release proceeds — that environment is the one place to put a brake on the automation.
+Provenance is attested automatically by trusted publishing.
+
+The release commit and the tag are pushed with a GitHub App installation token rather than
+`GITHUB_TOKEN`, because a push made with `GITHUB_TOKEN` triggers no further workflow runs — the
+tag would sit there and `publish.yml` would never fire. See
+`docs/adr/0006-automated-release-from-changelog.md`.
 
 ## npm trusted publisher: one-time setup
 
@@ -1304,6 +1337,30 @@ _installing_ private dependencies. This repository has no private dependencies,
 add a read token to CI. Add one only if the repository genuinely starts consuming a private
 package.
 
+## Release GitHub App: one-time setup
+
+`release.yml` and `dependabot-auto-merge.yml` push and merge with a GitHub App installation
+token rather than `GITHUB_TOKEN`. This is not a preference: GitHub deliberately does not trigger
+workflow runs from events created with `GITHUB_TOKEN`, so under that token an auto-merge would
+not run CI on `main` and a pushed tag would not run `publish.yml`. Nothing would ever reach npm.
+
+Done once, by a repository admin:
+
+1. **Create a GitHub App** owned by the repository owner, with the webhook **inactive**.
+2. **Repository permissions, and nothing else**: Contents **Read and write** (push the release
+   commit and tag), Pull requests **Read and write** (enable auto-merge, comment, update a
+   branch), Metadata Read-only (mandatory).
+3. **Install it on this repository only**, and generate a private key.
+4. **Store the credentials** under _Settings → Secrets and variables → Actions_:
+   `RELEASE_APP_ID` and `RELEASE_APP_PRIVATE_KEY` (the whole `.pem`, BEGIN/END lines included).
+5. **Add the App as a bypass actor** on the `main` ruleset. A ruleset's required-status-checks
+   rule blocks direct pushes as well as merges, and the release commit is a direct push. The
+   safety net is `publish.yml`, which re-runs the entire suite on the tagged tree before
+   `npm publish`, so a bad release commit cannot reach npm even though it can reach `main`.
+
+Installation tokens are repo-scoped and expire in an hour. A personal access token would work
+too and was rejected: it carries one person's account reach and expires on a calendar.
+
 ## Limitations
 
 - **A theme providing `MDXComponents/Code` must already be installed.** The plugin wraps that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matfsw/docusaurus-plantuml-plugin",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "description": "Render PlantUML diagrams in Docusaurus 3 entirely in the browser - no Java, no PlantUML server, no CDN.",
   "keywords": [
     "docusaurus",
@@ -90,10 +90,10 @@
     "@eslint/js": "^9.39.5",
     "@playwright/test": "^1.57.0",
     "@testing-library/dom": "^10.4.1",
-    "@testing-library/jest-dom": "^7.0.0",
+    "@testing-library/jest-dom": "^7.0.1",
     "@testing-library/react": "^16.3.0",
-    "@testing-library/user-event": "^14.6.1",
-    "@types/node": "^26.1.2",
+    "@testing-library/user-event": "^14.6.5",
+    "@types/node": "^26.2.0",
     "@types/react": "^19.2.18",
     "@types/react-dom": "^19.2.4",
     "@vitest/coverage-v8": "^4.1.10",
@@ -101,19 +101,20 @@
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^5.2.0",
-    "globals": "^17.9.0",
-    "jsdom": "^26.1.0",
+    "globals": "^17.11.0",
+    "jsdom": "^29.1.1",
     "prettier": "^3.6.2",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "tsup": "^8.5.0",
     "typescript": "~5.9.3",
-    "typescript-eslint": "^8.46.4",
+    "typescript-eslint": "^8.67.0",
     "vitest": "^4.1.10"
   },
   "overrides": {
     "serialize-javascript": "^7.0.7",
     "uuid": "^11.1.1",
-    "esbuild": "^0.28.1"
+    "esbuild": "^0.28.1",
+    "@noble/hashes": "^1.8.0"
   }
 }