puml-for-markdown 1.2.0 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## 2.0.0
+
+### Migration from version 1
+
+- Requires Node.js 22 or newer. Upgrade Node.js before installing version 2.
+- CLI failures now exit with a nonzero status so scripts and CI can detect errors.
+- The CLI creates `.puml-cache.json` by default. Add it to `.gitignore`, or use
+  `--no-cache` to disable caching. Refresh with `--no-cache` when remote includes
+  or the rendering server change.
+
+### Features and fixes
+
+- Add local image links, offline check and dry-run modes, persistent caching,
+  and private Polr URL shortening.
+- Support `.plantuml` files, Windows paths, nested ignore rules, and recursive
+  includes with cycle detection.
+- Preserve Markdown formatting and code examples while replacing diagram links.
+- Validate references before editing Markdown and preserve unrelated exported
+  files. Export images atomically with readable permissions.
+- Handle HTTP errors and timeouts, and serialize watch updates.
+- Update dependencies and examples, with automated checks on Linux, macOS,
+  and Windows using Node.js 22 and 24.

package/README.md

@@ -2,9 +2,10 @@
 
 ## Simple CLI Usage
 Just run `puml-for-markdown` in any directory where you have markdown files and it will render links to PlantUML files
-in markdown comments. [PlantUML](https://plantuml.com) files allow you to create diagrams that are defined using a
-simple and intuitive language. By default the entire directory is recursively searched, automatically ignoring anything
-in the gitignore file.
+in markdown comments. The best part about this is that it requires no build files, you don't even need to store 
+puml images in your repo. Also the embedded diagrams can link to other diagrams. [PlantUML](https://plantuml.com) files 
+allow you to create diagrams that are defined using a simple and intuitive language. By default the entire directory 
+is recursively searched, respecting root and nested `.gitignore` rules, including negation. `.git`, `node_modules`, the output directory, and symbolic links are always skipped. Both `.puml` and `.plantuml` diagram files are supported.
 
 ## Examples
 The following examples are of a project I worked on, **yellow components will link you to another diagram**. Obviously the
@@ -19,7 +20,7 @@ You can easily add an embedded diagram to your markdown. Simply add a link to th
 
 Here's the result. **Try clicking on the yellow blocks.**
 
-[![Diagram Image Link](https://tinyurl.com/y847en68)](https://tinyurl.com/y847en68)<!--![Diagram Image Link](./puml/level_1_system_view.puml)-->
+[![Diagram Image Link](https://tinyurl.com/2d47useb)](https://tinyurl.com/2d47useb)<!--![Diagram Image Link](./puml/level_1_system_view.puml)-->
 
 ### Link Only
 To render a link to a puml diagram, do the same thing but exclude the `!`
@@ -29,7 +30,7 @@ To render a link to a puml diagram, do the same thing but exclude the `!`
 
 which renders into
 
-[Click to Open Interactive Diagram](https://tinyurl.com/y847en68)<!--[Click to Open Interactive Diagram](./puml/level_1_system_view.puml)-->
+[Click to Open Interactive Diagram](https://tinyurl.com/2d47useb)<!--[Click to Open Interactive Diagram](./puml/level_1_system_view.puml)-->
 
 ## Goal
 The goal is to make PlantUML diagrams easily accessible from markdown, specifically GitHub flavored.
@@ -75,43 +76,79 @@ If you want to update the link text or switch it between image and link, just up
 don't need to delete the rendered image or link.
 
 ### Installation
+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
+[release notes](./CHANGELOG.md) for the changes.
+
 `npm i -g puml-for-markdown`
 
 ### 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`
+- 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).
 - You can specify the PUML server used to render the diagrams see `--puml-server-url`
 
 ### All CLI Options
-```
+```text
 Usage: puml-for-markdown [options]
 
 An application to add interactive PUML diagrams to your github markdown files. If running with default arguments, run in project root directory.
 
 Options:
-  -s, --puml-server-url <url>      This is the base URL used to render diagrams. Defaults to the public plantuml server. (default: "https://www.plantuml.com/plantuml")
+  -s, --puml-server-url <url>      This is the base URL used to render
+                                   diagrams. Defaults to the public plantuml
+                                   server. (default:
+                                   "https://www.plantuml.com/plantuml")
   -x, --root-directory <path>      The path to your project (default: CWD)
-  -r, --hot-reload                 Rerun markdown generator every `interval` seconds, determined by interval option
-  -v, --interval-seconds <number>  If --hot-reload is set, how often should it reload (default: 2)
-  -p, --puml-directory <path>      Path to directory containing puml files which are referenced in markdown files (default: rootDirectory)
-  -m, --markdown-directory <path>  Path to directory containing markdown files referencing puml files (default: rootDirectory)
-  -g, --ignore-gitignore           Don't use .gitignore to skip PUML and MD
-  -i, --gitignore-path <path>      Use this as path to .gitignore file. (default: rootDirectory/.gitignore)
-  -d, --output-images              If set, will output images of diagrams to the dist directory
-  -b, --dist-directory <path>      If --output-images is set, path to output diagram images (default: rootDirectory/dist_puml)
-  -f, --image-formats <format>     If --output-images is set, sets the output image format (choices: "png", "svg", "both", default: "png")
-  -t, --turn-off-link-shortening   Use the full puml server link instead of the tiny url, if your diagrams are too big this won't work
+  -r, --hot-reload                 Rerun markdown generator every `interval`
+                                   seconds, determined by interval option
+  -v, --interval-seconds <number>  If --hot-reload is set, how often should it
+                                   reload (default: 2)
+  -p, --puml-directory <path>      Path to directory containing puml files
+                                   which are referenced in markdown files
+                                   (default: rootDirectory)
+  -m, --markdown-directory <path>  Path to directory containing markdown files
+                                   referencing puml files (default:
+                                   rootDirectory)
+  -g, --ignore-gitignore           Don't use .gitignore rules to skip PUML and
+                                   MD
+  -i, --gitignore-path <path>      Use this as path to .gitignore file.
+                                   (default: rootDirectory/.gitignore)
+  -d, --output-images              If set, will output images of diagrams to
+                                   the dist directory
+  -b, --dist-directory <path>      If --output-images is set, path to output
+                                   diagram images (default:
+                                   rootDirectory/dist_puml)
+  -f, --image-formats <format>     If --output-images is set, sets the output
+                                   image format (choices: "png", "svg", "both",
+                                   default: "png")
+  -t, --turn-off-link-shortening   Use the full puml server link instead of the
+                                   tiny url, if your diagrams are too big this
+                                   won't work
+  --local-images                   Link Markdown to exported local images
+                                   (implies --output-images)
+  --interactive-links              Wrap local image previews in an interactive
+                                   renderer link
+  --check                          Check for stale Markdown and images without
+                                   writing or using the network
+  --dry-run                        List planned changes without writing or
+                                   using the network
+  --no-cache                       Disable the persistent diagram and image
+                                   cache
+  -l, --polr-url <url>             Use a private Polr shortener; reads
+                                   POLR_APIKEY from the environment
   -h, --help                       display help for command
 ```
 
 ### Notes
 - Comments within inline or multiline code styling will be ignored
-- Currently doesn't support cyclic graph references, i.e. a diagram can't reference any diagrams which reference back
-to it
+- Cyclic diagram links and recursive local includes fail with an error showing the reference chain.
 - See the [pre-commit hook](./.husky/pre-commit) to see how to add a git hook
-- If you are saving diagram images and have puml files which only define constants or settings
-(i.e. [example](./puml/constants.puml)) you'll see a warning in the console saying it failed to save the image to file
-because these aren't renderable on their own (since there is nothing to render)
+- Image export skips files without an `@start...` directive and files used only as local includes. A Markdown reference or diagram hyperlink makes an included file exportable. Other files must render successfully.
 - Anything inside `inline code` or `code blocks` will be excluded from rendering
 
 ### How It Works
@@ -145,25 +182,140 @@ though.
 ### 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.
+
 ### More Examples
-[![ERD](https://tinyurl.com/ya6qvr7r)](https://tinyurl.com/ya6qvr7r)<!--![ERD](./puml/level_4_erd.puml)-->
+[![ERD](https://tinyurl.com/2amb263t)](https://tinyurl.com/2amb263t)<!--![ERD](./puml/level_4_erd.puml)-->
+
+
+
+[![Container View](https://tinyurl.com/284kg5h5)](https://tinyurl.com/284kg5h5)<!--![Container View](./puml/level_2_container_view.puml)-->
+
+
+
+[![Component View - Label Retrieval Job](https://tinyurl.com/262ys7bk)](https://tinyurl.com/262ys7bk)<!--![Component View - Label Retrieval Job](./puml/level_3_component_view_label_retrieval_job.puml)-->
+
 
 
+[![Component View - Pipeline Component](https://tinyurl.com/2xlmr44t)](https://tinyurl.com/2xlmr44t)<!--![Component View - Pipeline Component](./puml/level_3_component_view_pipeline.puml)-->
 
-[![Container View](https://tinyurl.com/yblre3m4)](https://tinyurl.com/yblre3m4)<!--![Container View](./puml/level_2_container_view.puml)-->
 
 
+[![Activity Diagram - Sampler A](https://tinyurl.com/26j5s2fw)](https://tinyurl.com/26j5s2fw)<!--![Activity Diagram - Sampler A](./puml/level_4_activity_diagram_sampler_a.puml)-->
 
-[![Component View - Label Retrieval Job](https://tinyurl.com/y8egw3wt)](https://tinyurl.com/y8egw3wt)<!--![Component View - Label Retrieval Job](./puml/level_3_component_view_label_retrieval_job.puml)-->
 
 
+[![Activity Diagram - Sampler B](https://tinyurl.com/2cqvdekn)](https://tinyurl.com/2cqvdekn)<!--![Activity Diagram - Sampler B](./puml/level_4_activity_diagram_sampler_b.puml)-->
 
-[![Component View - Pipeline Component](https://tinyurl.com/y9j7twkz)](https://tinyurl.com/y9j7twkz)<!--![Component View - Pipeline Component](./puml/level_3_component_view_pipeline.puml)-->
 
+### Reliability and operational notes
 
+- Fatal errors return a nonzero exit status, suitable for CI. Watch mode logs errors
+  and retries on the next interval; it runs immediately on startup.
+- Local `!include` files are expanded recursively relative to the file containing
+  the directive. Remote, standard-library, and macro-based includes remain for the
+  renderer to evaluate. This is not a complete PlantUML preprocessor: conditional
+  includes and `!include_once` / `!include_many` are not expanded locally.
+- Unrelated Markdown links, fenced/indented code, inline code, and line endings
+  are preserved. Unchanged Markdown files are not rewritten.
+- All Markdown references are checked before documents are written. Image exports
+  complete before Markdown is updated, but an export failure can leave earlier
+  successfully exported images updated; the operation is not a multi-file transaction.
+- Export overwrites the matching generated image files but never clears the output
+  directory. Stale images are retained. Ambiguous output names and symlinks inside
+  the output path are rejected.
+- Renderer and shortener requests time out after 30 seconds. If TinyURL fails,
+  a warning is printed and the direct PlantUML URL is used. Large URLs can still
+  exceed renderer/proxy limits; shortening does not remove the renderer's limit.
+- **Diagram privacy:** encoded diagram URLs contain recoverable source text.
+  The default shortener receives that URL, and the renderer receives the diagram
+  when someone opens it or when images are exported. For private diagrams, use
+  your own renderer with `--puml-server-url` and disable shortening with `-t`.
 
-[![Activity Diagram - Sampler A](https://tinyurl.com/ybp8ju9x)](https://tinyurl.com/ybp8ju9x)<!--![Activity Diagram - Sampler A](./puml/level_4_activity_diagram_sampler_a.puml)-->
 
+### Local images and offline viewing
+
+```sh
+puml-for-markdown --local-images --image-formats svg
+```
+
+This implies `--output-images` and produces relative Markdown links to files in
+`dist_puml`. For example, `<!--![Diagram](puml/a.puml)-->` becomes
+`![Diagram](dist_puml/puml/a.svg)<!--![Diagram](puml/a.puml)-->`.
+Paths are relative to each Markdown file and URL-encoded, including spaces.
+Both `.puml` and `.plantuml` sources work.
+
+SVG diagrams link to other exported SVG diagrams using relative paths. Open the
+SVG directly in a browser or serve the export folder to navigate between them.
+Markdown hosts may disable links inside embedded SVG images. PNG previews cannot
+contain clickable elements. With `--image-formats both`, Markdown uses SVG.
+
+Add `--interactive-links` to wrap a local preview in a link to the online renderer.
+That renderer link uses separate source with online diagram hyperlinks, while
+exported SVGs retain their local hyperlinks. Local-only mode skips URL shortening.
+Rendering still contacts the configured PlantUML server; use `--puml-server-url`
+with your own renderer when the source must remain private.
+
+### Check or preview changes without modifying files
+
+```sh
+puml-for-markdown --dry-run -t
+puml-for-markdown --check -t
+puml-for-markdown --local-images --image-formats svg --check
+```
+
+Both commands are offline and never write Markdown, images, or cache files.
+`--dry-run` lists planned changes and exits successfully; `--check` exits with 1
+if documentation is stale, otherwise 0. Invalid inputs still exit with 1.
+Neither can be combined with `--hot-reload`.
+
+A check that uses shortened URLs or exported images needs the cache from a prior
+successful generation with the same settings. If it is missing, the check reports
+that generation is needed rather than contacting a shortener or claiming the files
+are current. Direct-URL Markdown checks (`--check -t` without image export) do not
+require a cache. For CI, use that deterministic mode or restore the generation
+cache with the exported images.
+
+### Persistent cache and incremental watch mode
+
+Successful runs save `.puml-cache.json` at the project root. Add it to your
+`.gitignore`: encoded URLs contain recoverable source text, even for private diagrams.
+The cache contains no Polr API key. Renderer/provider settings and a hash of the key
+separate cache entries when configuration changes.
+
+The CLI reuses encodings, shortened URLs, and verified image files. Watch mode
+checks inputs each interval and only rebuilds affected content. Local include
+changes invalidate their parent diagrams; remote diagram links invalidate parents
+when their target URL changes. Local links stay stable when only a child changes.
+Missing or externally modified images are rendered again.
+
+```sh
+puml-for-markdown --hot-reload
+puml-for-markdown --no-cache
+```
+
+`--no-cache` forces regeneration without reading or writing the cache. Use it to
+refresh remote includes, renderer upgrades at the same URL, or expired short links:
+those external changes cannot be detected from local file content. Failed shortening
+attempts are not cached, allowing the next run to retry. Stale generated images are
+retained; the CLI never clears the destination directory.
+
+### Private Polr URL shortening
+
+```sh
+# Set POLR_APIKEY in your shell or CI secret environment first.
+puml-for-markdown --puml-server-url https://uml.example.com/plantuml \
+  --polr-url https://short.example.com
+```
 
+This adapts the provider idea from [PR #8](https://github.com/danielyaa5/puml-for-markdown/pull/8)
+by @mzagar. The implementation uses the [Polr v2 API](https://docs.polrproject.org/en/latest/developer-guide/api/):
+POST `/api/v2/action/shorten`, with URL-encoded `url`, `key`, and `response_type`
+fields. JSON and plain-text responses are accepted and validated. Credentials are
+never written into generated links or the cache. A failed Polr request falls back
+to the direct renderer URL, never TinyURL. `--polr-url` cannot be combined with `-t`.
 
-[![Activity Diagram - Sampler B](https://tinyurl.com/ya3cqxkv)](https://tinyurl.com/ya3cqxkv)<!--![Activity Diagram - Sampler B](./puml/level_4_activity_diagram_sampler_b.puml)-->
+To avoid a shortener entirely, use your own renderer with `-t`. This is also the
+simplest setup for private diagrams when URLs are short enough for your renderer.

package/bin/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 const path = require('path')
+const fs = require('fs')
 
 const {Command, Option} = require('commander')
 
@@ -12,75 +13,91 @@ const run = require(path.resolve(__dirname, '../index.js'))
 // =============
 
 new Command()
-    .description('An application to add interactive PUML diagrams to your github markdown files. If running with default arguments, run in project root directory.')
-    .option(
-        '-s, --puml-server-url <url>',
-        'This is the base URL used to render diagrams. Defaults to the public plantuml server.',
-        'https://www.plantuml.com/plantuml',
-    )
-    .addOption(new Option(
-            '-x, --root-directory <path>',
-            'The path to your project'
-        ).default(process.cwd(), 'CWD')
-    )
-    .option(
-        '-r, --hot-reload',
-        'Rerun markdown generator every `interval` seconds, determined by interval option',
-    )
-    .option(
-        '-v, --interval-seconds <number>',
-        'If --hot-reload is set, how often should it reload',
-        2,
-    )
-    .addOption(new Option(
-            '-p, --puml-directory <path>',
-            'Path to directory containing puml files which are referenced in markdown files',
-        ).default(false, 'rootDirectory')
-    )
-    .addOption(new Option(
-            '-m, --markdown-directory <path>',
-            'Path to directory containing markdown files referencing puml files',
-        ).default(false, 'rootDirectory')
-    )
-    .option(
-        '-g, --ignore-gitignore',
-        "Don't use .gitignore to skip PUML and MD",
-    )
-    .addOption(new Option(
-            '-i, --gitignore-path <path>',
-            'Use this as path to .gitignore file.'
-        ).default(false, 'rootDirectory/.gitignore')
-    )
-    .option(
-        '-d, --output-images',
-        'If set, will output images of diagrams to the dist directory',
-    )
-    .addOption(new Option(
-            '-b, --dist-directory <path>',
-            'If --output-images is set, path to output diagram images'
-        ).default(false, 'rootDirectory/dist_puml')
-    )
-    .addOption(new Option(
-            '-f, --image-formats <format>',
-            'If --output-images is set, sets the output image format',
-        ).choices(['png', 'svg', 'both']).default('png')
-    )
-    .option(
-        '-t, --turn-off-link-shortening',
-        "Use the full puml server link instead of the tiny url, if your diagrams are too big this won't work",
-    )
-    .action(opts => {
-        opts.distDirectory = opts.distDirectory || path.resolve(opts.rootDirectory, 'dist_puml')
-        opts.gitignorePath = opts.gitignorePath || path.resolve(opts.rootDirectory, '.gitignore')
-        opts.markdownDirectory = opts.markdownDirectory || opts.rootDirectory
-        opts.pumlDirectory = opts.pumlDirectory || opts.rootDirectory
-        opts.shouldShortenLinks = !opts.turnOffLinkShortening
-        opts.respectGitignore = !opts.ignoreGitignore
-        opts.imageFormats = opts.imageFormats === 'both' ? ['png', 'svg'] : [opts.imageFormats]
+  .name('puml-for-markdown')
+  .description('An application to add interactive PUML diagrams to your github markdown files. If running with default arguments, run in project root directory.')
+  .option(
+    '-s, --puml-server-url <url>',
+    'This is the base URL used to render diagrams. Defaults to the public plantuml server.',
+    'https://www.plantuml.com/plantuml',
+  )
+  .addOption(new Option(
+      '-x, --root-directory <path>',
+      'The path to your project'
+    ).default(process.cwd(), 'CWD')
+  )
+  .option(
+    '-r, --hot-reload',
+    'Rerun markdown generator every `interval` seconds, determined by interval option',
+  )
+  .option(
+    '-v, --interval-seconds <number>',
+    'If --hot-reload is set, how often should it reload',
+    2,
+  )
+  .addOption(new Option(
+      '-p, --puml-directory <path>',
+      'Path to directory containing puml files which are referenced in markdown files',
+    ).default(false, 'rootDirectory')
+  )
+  .addOption(new Option(
+      '-m, --markdown-directory <path>',
+      'Path to directory containing markdown files referencing puml files',
+    ).default(false, 'rootDirectory')
+  )
+  .option(
+    '-g, --ignore-gitignore',
+    "Don't use .gitignore rules to skip PUML and MD",
+  )
+  .addOption(new Option(
+      '-i, --gitignore-path <path>',
+      'Use this as path to .gitignore file.'
+    ).default(false, 'rootDirectory/.gitignore')
+  )
+  .option(
+    '-d, --output-images',
+    'If set, will output images of diagrams to the dist directory',
+  )
+  .addOption(new Option(
+      '-b, --dist-directory <path>',
+      'If --output-images is set, path to output diagram images'
+    ).default(false, 'rootDirectory/dist_puml')
+  )
+  .addOption(new Option(
+      '-f, --image-formats <format>',
+      'If --output-images is set, sets the output image format',
+    ).choices(['png', 'svg', 'both']).default('png')
+  )
+  .option(
+    '-t, --turn-off-link-shortening',
+    "Use the full puml server link instead of the tiny url, if your diagrams are too big this won't work",
+  )
+  .option('--local-images', 'Link Markdown to exported local images (implies --output-images)')
+  .option('--interactive-links', 'Wrap local image previews in an interactive renderer link')
+  .option('--check', 'Check for stale Markdown and images without writing or using the network')
+  .option('--dry-run', 'List planned changes without writing or using the network')
+  .option('--no-cache', 'Disable the persistent diagram and image cache')
+  .option('-l, --polr-url <url>', 'Use a private Polr shortener; reads POLR_APIKEY from the environment')
+  .action(opts => {
+      const useDefaultGitignorePath = !opts.gitignorePath
 
-        return run(opts).catch((e) => {
-            console.error('FATAL EXCEPTION')
-            console.error(e)
-        })
-    })
-    .parse(process.argv)
+      opts.distDirectory = opts.distDirectory || path.resolve(opts.rootDirectory, 'dist_puml')
+      opts.gitignorePath = opts.gitignorePath || path.resolve(opts.rootDirectory, '.gitignore')
+      opts.markdownDirectory = opts.markdownDirectory || opts.rootDirectory
+      opts.pumlDirectory = opts.pumlDirectory || opts.rootDirectory
+      opts.shouldShortenLinks = !opts.turnOffLinkShortening
+      opts.respectGitignore = !opts.ignoreGitignore
+      opts.imageFormats = opts.imageFormats === 'both' ? ['png', 'svg'] : [opts.imageFormats]
+
+      // A missing root ignore file must not disable nested .gitignore files.
+      if (useDefaultGitignorePath && !fs.existsSync(opts.gitignorePath)) {
+          opts.gitignorePath = undefined
+      }
+
+      return run(opts).then(result => {
+          if (opts.check && result.stale) process.exitCode = 1
+      }).catch((e) => {
+          console.error(`ERROR: ${e.message}`)
+          process.exitCode = 1
+      })
+  })
+  .parse(process.argv)