puml-for-markdown 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 2.1.0
+
+- Add a GitHub Action, `danielyaa5/puml-for-markdown@v2`. `update` mode regenerates
+  diagrams and commits only the files it changed; `check` mode fails pull requests
+  whose diagrams are out of date. Works on Linux, macOS, and Windows runners.
+  See [GitHub Action](./README.md#github-action). No CLI changes.
+
+## 2.0.1
+
+- Correct outdated README statements about Windows support, automated testing,
+  the pre-commit hook, and diagram privacy. No runtime behavior changes.
+
 ## 2.0.0
 
 ### Migration from version 1

package/README.md

@@ -80,16 +80,69 @@ Requires **Node.js 22 or newer** (Node.js 24 recommended for development).
 
 Version 2 raises the minimum Node.js version to 22. Upgrade Node.js before upgrading
 from version 1. Existing dependencies pinned to `1.x` or `^1.2.1` stay on version 1;
-installing `latest` will select version 2 once it is published. See the
+installing `latest` selects version 2. See the
 [release notes](./CHANGELOG.md) for the changes.
 
 `npm i -g puml-for-markdown`
 
+### GitHub Action
+Keep diagrams current without running the CLI yourself. To regenerate and commit them on every push to `main`:
+
+```yaml
+# .github/workflows/diagrams.yml
+name: Diagrams
+on:
+  push:
+    branches: [main]
+permissions:
+  contents: write
+jobs:
+  diagrams:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: danielyaa5/puml-for-markdown@v2
+```
+
+To fail pull requests whose diagrams are out of date instead:
+
+```yaml
+name: Diagrams
+on: pull_request
+jobs:
+  diagrams:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: danielyaa5/puml-for-markdown@v2
+        with:
+          mode: check
+```
+
+| Input | Default | Description |
+|---|---|---|
+| `mode` | `update` | `update` regenerates links and images, then commits and pushes them. `check` regenerates and fails if anything differs from what is committed. |
+| `args` | | Extra CLI options, such as `--local-images -f svg` or `-s https://uml.example.com/plantuml`. Use the options you run locally, or `check` will report differences. |
+| `root-directory` | `.` | Project directory to scan. |
+| `commit` | `true` | In `update` mode, commit and push the changed files. Needs `permissions: contents: write`. |
+| `commit-message` | `Update PlantUML diagrams` | Commit message for `update` mode. |
+| `cache` | `true` | Restore `.puml-cache.json` from earlier runs, and save it in `update` mode, so unchanged diagrams are not rendered or shortened again. |
+
+Outputs: `changed` (`true` or `false`), `files` (changed paths, one per line), and `commit` (the pushed SHA).
+
+- The action commits only the files the CLI changed, never other changes made earlier in the job, and never `.puml-cache.json`.
+- Commits pushed with the default `GITHUB_TOKEN` do not start new workflow runs, so updates cannot loop.
+- `update` needs a branch checkout. On `pull_request` events use `check`, which also works for forks, or check out `${{ github.head_ref }}` for pull requests from the same repository.
+- `check` contacts the same renderer and shortener as a normal run. TinyURL returns the same link for the same diagram, so a pull request regenerated locally passes. With `-t` and no image export, `check` needs no network.
+- For Polr, pass the key from a secret: `env: POLR_APIKEY: ${{ secrets.POLR_APIKEY }}`.
+- The action uses the runner's Node.js when it is version 22 or newer, and otherwise installs Node.js 22. Linux, macOS, and Windows runners are supported.
+- `@v2` follows the latest 2.x release. Pin a release such as `@2.1.0`, or a commit SHA, to control updates.
+
 ### Advanced Usage
 Here are some other features supported
 - You can specify the CLI to output the diagram images as png and/or svg see `--output-images` and `--image-formats`.
-For an example of outputted images, checkout [dist_puml/puml](./dist_puml/puml). These images were created by the
-[pre-commit hook](./.husky/pre-commit).
+For historical examples of exported images, see [dist_puml/puml](./dist_puml/puml).
+The current pre-commit hook runs the automated tests.
 - You can specify the PUML server used to render the diagrams see `--puml-server-url`
 
 ### All CLI Options
@@ -173,18 +226,26 @@ In order to support `!include` we parse puml files and replace any `!include` wi
 #### Parsing Markdown
 The markdown files are then parsed for markdown comments. If the comments reference a PlantUML file, a link to the web
 service url will be added next to the comment. Because these links contain the full PlantUML diagram encoding in it,
-there are no issues using them in private repositories.
+the source can be recovered from the URL. A private repository does not make the
+renderer or shortener private; see [diagram privacy](#reliability-and-operational-notes).
 
 ### Testing
-Currently there is no TDD, for now I've just been using the example diagrams to test. The examples are pretty extensive
-though.
+Run `npm test` to execute the automated CLI regression tests. CI runs on Linux,
+macOS, and Windows with Node.js 22 and 24. The suite covers Markdown updates,
+path handling, ignore rules, includes, image exports, caching, and shortening.
+See [CONTRIBUTING.md](https://github.com/danielyaa5/puml-for-markdown/blob/main/CONTRIBUTING.md)
+for development instructions.
 
 ### Other Helpful Links
 * [C4-Puml](https://github.com/plantuml-stdlib/C4-PlantUML): A collection of PlantUML diagrams for use in C4, you'll see me using this in my examples
 
-### Known Issues
-* Seems to be breaking on Windows, see [here](https://github.com/danielyaa5/puml-for-markdown/issues/6). I don't have a
-Windows machine to test on so help here would be appreciated.
+### Windows support
+Version 2 fixes the reported Windows path lookup issue
+([#6](https://github.com/danielyaa5/puml-for-markdown/issues/6)). Windows path and
+ignore-rule regressions are covered by automated tests. The version 2 changes
+were also tested on Windows 11 ARM64 with Node.js 24.
+
+For remaining limitations, see [reliability and operational notes](#reliability-and-operational-notes).
 
 ### More Examples
 [![ERD](https://tinyurl.com/2amb263t)](https://tinyurl.com/2amb263t)<!--![ERD](./puml/level_4_erd.puml)-->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "puml-for-markdown",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "An application to add interactive PUML diagrams to your github markdown files. If running with default arguments, run in project root directory.",
   "main": "index.js",
   "scripts": {