{"_id":"@doikayt/nx-graph-to-mermaid","_rev":"6-1c28668452192e76a3f0fc9fbe00f8b7","name":"@doikayt/nx-graph-to-mermaid","dist-tags":{"latest":"1.4.20"},"versions":{"1.4.16":{"name":"@doikayt/nx-graph-to-mermaid","version":"1.4.16","keywords":["nx","javascript","node","typescript","mermaid","graph","task-graph","build","automation","documentation","ci"],"_id":"@doikayt/nx-graph-to-mermaid@1.4.16","maintainers":[{"name":"datalackey","email":"chris@buildlackey.com"}],"homepage":"https://github.com/doikayt/build-tools/tree/main/javascript/nx-graph-to-mermaid","bugs":{"url":"https://github.com/doikayt/build-tools/issues"},"bin":{"nx-graph-to-mermaid":"bin/nx-graph-to-mermaid.js"},"dist":{"shasum":"697d7660fa478ce0ff23e81f21adc00a7c111fb7","tarball":"https://registry.npmjs.org/@doikayt/nx-graph-to-mermaid/-/nx-graph-to-mermaid-1.4.16.tgz","fileCount":14,"integrity":"sha512-Z2aE2I1mD3xrH/VTbf3sPUHdMoA8WIsPJhERUgOZen57pI9E8ojfkwLEj0GLyQgB4B+9h9kR6LlkeBxmjXcigQ==","signatures":[{"sig":"MEQCIHjXPNP3e4NZV3oUjFR2VkC2Pfxb3XxaEIceB1L8jcqRAiB5in9oELz1ddDeLqG3yLQRKpT7xOITV5fjbFRSsc4qeA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":35476},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=22"},"gitHead":"d1cdb9d8727e1aecffdc4916e6766d9b50765e64","private":false,"scripts":{"test":"vitest run","prepack":"npx nx build @doikayt/nx-graph-to-mermaid 1>&2"},"_npmUser":{"name":"datalackey","email":"chris@buildlackey.com"},"executors":"./executors.json","repository":{"url":"git+https://github.com/doikayt/build-tools.git","type":"git","directory":"javascript/nx-graph-to-mermaid"},"_npmVersion":"10.9.8","description":"Auto-generates a Mermaid task flow diagram from an NX `project.json` file — with optional CI drift detection and Markdown injection support.","directories":{},"_nodeVersion":"22.23.1","dependencies":{"@doikayt/tooling-core":"^1.4.16"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^1.0.0","typescript":"^5.4.0","@types/node":"^18.16.0"},"_npmOperationalInternal":{"tmp":"tmp/nx-graph-to-mermaid_1.4.16_1783993667512_0.2125909795429255","host":"s3://npm-registry-packages-npm-production"}},"1.4.17":{"name":"@doikayt/nx-graph-to-mermaid","version":"1.4.17","keywords":["nx","javascript","node","typescript","mermaid","graph","task-graph","build","automation","documentation","ci"],"_id":"@doikayt/nx-graph-to-mermaid@1.4.17","maintainers":[{"name":"datalackey","email":"chris@buildlackey.com"}],"homepage":"https://github.com/doikayt/build-tools/tree/main/javascript/nx-graph-to-mermaid","bugs":{"url":"https://github.com/doikayt/build-tools/issues"},"bin":{"nx-graph-to-mermaid":"bin/nx-graph-to-mermaid.js"},"dist":{"shasum":"fcda144ac92f86dac086502d3c28bb20bcb0774d","tarball":"https://registry.npmjs.org/@doikayt/nx-graph-to-mermaid/-/nx-graph-to-mermaid-1.4.17.tgz","fileCount":14,"integrity":"sha512-P7b9qdSc/Bnh5zyBUNYh+wdepnhff/1NTjzP8SHA+WtRx+YEETRmIn0PV+rYR3kzyQzMajHqAdS/3liGVgXhlg==","signatures":[{"sig":"MEYCIQCYZCDbRRxhQzGJ+uGTX5zyG9AIUkjRlWygHUYw/pcpIwIhANrX2AvAi/h/NS4YczSruHJUTUUH03lwF6mg0NA2T/jp","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":35476},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=22"},"gitHead":"776931f4dfd9bbbc5a3e59c185ad157c2bba7b24","private":false,"scripts":{"test":"vitest run","prepack":"npx nx build @doikayt/nx-graph-to-mermaid 1>&2"},"_npmUser":{"name":"datalackey","email":"chris@buildlackey.com"},"executors":"./executors.json","repository":{"url":"git+https://github.com/doikayt/build-tools.git","type":"git","directory":"javascript/nx-graph-to-mermaid"},"_npmVersion":"10.9.8","description":"Auto-generates a Mermaid task flow diagram from an NX `project.json` file — with optional CI drift detection and Markdown injection support.","directories":{},"_nodeVersion":"22.23.1","dependencies":{"@doikayt/tooling-core":"^1.4.17"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^1.0.0","typescript":"^5.4.0","@types/node":"^18.16.0"},"_npmOperationalInternal":{"tmp":"tmp/nx-graph-to-mermaid_1.4.17_1783994513550_0.6175711292184738","host":"s3://npm-registry-packages-npm-production"}},"1.4.18":{"name":"@doikayt/nx-graph-to-mermaid","version":"1.4.18","keywords":["nx","javascript","node","typescript","mermaid","graph","task-graph","build","automation","documentation","ci"],"_id":"@doikayt/nx-graph-to-mermaid@1.4.18","maintainers":[{"name":"datalackey","email":"chris@buildlackey.com"},{"name":"lastliet","email":"pranjalk.dev@outlook.com"}],"homepage":"https://github.com/doikayt/build-tools/tree/main/javascript/nx-graph-to-mermaid","bugs":{"url":"https://github.com/doikayt/build-tools/issues"},"bin":{"nx-graph-to-mermaid":"bin/nx-graph-to-mermaid.js"},"dist":{"shasum":"c3990a80b6a84a932d3aa1ffd8f4410a925441e1","tarball":"https://registry.npmjs.org/@doikayt/nx-graph-to-mermaid/-/nx-graph-to-mermaid-1.4.18.tgz","fileCount":14,"integrity":"sha512-58T6MmmY3WezjKliJ4gNVM+QXnd4O2BvWupgBhkKbBCJv2m6hiz+Rx6vHFFMx2k6oC3Ebei26iiidQpr0vz9oA==","signatures":[{"sig":"MEUCIQDprHGk3U4JORjM5236Y5aJ1A1if8f3Pl4Eh+jL0mrIJgIgG4AMf5vzBu3I0JYpCra6W6z+BpOzosLMHc45Ugl6b38=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEYCIQCTm7byssQRBTHhSsX1iiVda49DzlqNPcL516ol+zrwqwIhAO63HiO/0MsNcG+TAuboOP2mAPxC6vc2a+AhWUdIk5X0","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":35599},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=22"},"gitHead":"2974899886f97c0ea44079338ff50f59a7c28718","private":false,"scripts":{"test":"vitest run","prepack":"npx nx build @doikayt/nx-graph-to-mermaid 1>&2"},"_npmUser":{"name":"datalackey","email":"chris@buildlackey.com"},"executors":"./executors.json","repository":{"url":"git+https://github.com/doikayt/build-tools.git","type":"git","directory":"javascript/nx-graph-to-mermaid"},"_npmVersion":"10.9.8","description":"Auto-generates a Mermaid task flow diagram from an NX `project.json` file — with optional CI drift detection and Markdown injection support.","directories":{},"_nodeVersion":"22.23.2","dependencies":{"@doikayt/tooling-core":"^1.4.18"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^1.0.0","typescript":"^5.4.0","@types/node":"^18.16.0"},"_npmOperationalInternal":{"tmp":"tmp/nx-graph-to-mermaid_1.4.18_1790823379780_0.4564163064200031","host":"s3://npm-registry-packages-npm-production"}},"1.4.19":{"name":"@doikayt/nx-graph-to-mermaid","version":"1.4.19","keywords":["nx","javascript","node","typescript","mermaid","graph","task-graph","build","automation","documentation","ci"],"_id":"@doikayt/nx-graph-to-mermaid@1.4.19","maintainers":[{"name":"datalackey","email":"chris@buildlackey.com"},{"name":"lastliet","email":"pranjalk.dev@outlook.com"}],"homepage":"https://github.com/doikayt/build-tools/tree/main/javascript/nx-graph-to-mermaid","bugs":{"url":"https://github.com/doikayt/build-tools/issues"},"bin":{"nx-graph-to-mermaid":"bin/nx-graph-to-mermaid.js"},"dist":{"shasum":"078d08a3b2026c8c1dc8cb0ae0f29e59f25ca8b5","tarball":"https://registry.npmjs.org/@doikayt/nx-graph-to-mermaid/-/nx-graph-to-mermaid-1.4.19.tgz","fileCount":14,"integrity":"sha512-u3cloJSZxdayus41g4Pt4qvjOEQ9s4iHlNiYra/oP+5YQBVsm3BqyDSGekNWXnCIWV8pDBTdXZ8144iRa71n5w==","signatures":[{"sig":"MEQCIFWJiPK5bcpLxy73AOtOVeILyizgbSHssa0SNBQ+VojEAiBP/2s4xIST6mz8SnJ5IQxvDw6AFKTYAeijE+jiKN0A4A==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIQC+/fgc4jYoGVTb8ll7luO3WzTvgg/CIeW/3Kc0a2ANUQIgX4bCgWXlwEfaunVLdXVLALiFGg307tdRjPBp53AdkU8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":35599},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=22"},"gitHead":"cbd192dc2455809281db2b19a5527a6260f33594","private":false,"scripts":{"test":"vitest run","prepack":"npx nx build @doikayt/nx-graph-to-mermaid 1>&2"},"_npmUser":{"name":"datalackey","email":"chris@buildlackey.com"},"executors":"./executors.json","repository":{"url":"git+https://github.com/doikayt/build-tools.git","type":"git","directory":"javascript/nx-graph-to-mermaid"},"_npmVersion":"10.9.9","description":"Auto-generates a Mermaid task flow diagram from an NX `project.json` file — with optional CI drift detection and Markdown injection support.","directories":{},"_nodeVersion":"22.23.3","dependencies":{"@doikayt/tooling-core":"^1.4.19"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^1.0.0","typescript":"^5.4.0","@types/node":"^18.16.0"},"_npmOperationalInternal":{"tmp":"tmp/nx-graph-to-mermaid_1.4.19_1790823998612_0.020838956977386802","host":"s3://npm-registry-packages-npm-production"}},"1.4.20":{"_id":"@doikayt/nx-graph-to-mermaid@1.4.20","bin":{"nx-graph-to-mermaid":"bin/nx-graph-to-mermaid.js"},"bugs":{"url":"https://github.com/doikayt/build-tools/issues"},"dist":{"shasum":"fa21ce8d5c34c53f7f442f2de813da72ac037a09","tarball":"https://registry.npmjs.org/@doikayt/nx-graph-to-mermaid/-/nx-graph-to-mermaid-1.4.20.tgz","fileCount":14,"integrity":"sha512-oVF1ksWZ0ZwOtHLm4qlh2L/kU1nMqKE5xbkJPbhNfvUh+/juP/ZLRqL6SL7q4lqUtR9fyMPyon0BEV65savIqQ==","signatures":[{"sig":"MEYCIQCWsxjALctRTi4qY4mtIuNHR/DctLRGgwziCjF24CxeDgIhAKoC0d/mfb4Gdn8mSu43XAfq6EtsJh9ymmdzlj1VZ0A0","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDzFR2v5oJREfzbMQ/3ZaQ3YexLKJFbxe13FY8EE5fk4wIgZWfFjdzET8Knun1/bxcQX4scIDejNEv/oVyRBtLKXBs="}],"unpackedSize":35599},"main":"dist/index.js","name":"@doikayt/nx-graph-to-mermaid","type":"module","types":"./dist/index.d.ts","engines":{"node":">=22"},"gitHead":"711d730053d3e887dc94a1850139fffba699d816","private":false,"scripts":{"test":"vitest run","prepack":"npx nx build @doikayt/nx-graph-to-mermaid 1>&2"},"version":"1.4.20","_npmUser":{"name":"datalackey","email":"chris@buildlackey.com"},"homepage":"https://github.com/doikayt/build-tools/tree/main/javascript/nx-graph-to-mermaid","keywords":["nx","javascript","node","typescript","mermaid","graph","task-graph","build","automation","documentation","ci"],"executors":"./executors.json","repository":{"url":"git+https://github.com/doikayt/build-tools.git","type":"git","directory":"javascript/nx-graph-to-mermaid"},"_npmVersion":"10.9.9","description":"Auto-generates a Mermaid task flow diagram from an NX `project.json` file — with optional CI drift detection and Markdown injection support.","directories":{},"maintainers":[{"name":"datalackey","email":"chris@buildlackey.com"},{"name":"lastliet","email":"pranjalk.dev@outlook.com"}],"_nodeVersion":"22.23.3","dependencies":{"@doikayt/tooling-core":"^1.4.20"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^1.0.0","typescript":"^5.4.0","@types/node":"^18.16.0"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/nx-graph-to-mermaid_1.4.20_1790824825842_0.8019890919997432"}}},"time":{"created":"2026-07-14T01:47:47.423Z","modified":"2026-10-01T03:20:26.119Z","1.4.16":"2026-07-14T01:47:47.667Z","1.4.17":"2026-07-14T02:01:53.694Z","1.4.18":"2026-10-01T02:56:19.876Z","1.4.19":"2026-10-01T03:06:38.698Z","1.4.20":"2026-10-01T03:20:25.925Z"},"bugs":{"url":"https://github.com/doikayt/build-tools/issues"},"homepage":"https://github.com/doikayt/build-tools/tree/main/javascript/nx-graph-to-mermaid","keywords":["nx","javascript","node","typescript","mermaid","graph","task-graph","build","automation","documentation","ci"],"repository":{"url":"git+https://github.com/doikayt/build-tools.git","type":"git","directory":"javascript/nx-graph-to-mermaid"},"description":"Auto-generates a Mermaid task flow diagram from an NX `project.json` file — with optional CI drift detection and Markdown injection support.","maintainers":[{"name":"datalackey","email":"chris@buildlackey.com"},{"name":"lastliet","email":"pranjalk.dev@outlook.com"}],"readme":"\n\n\n<!-- TOC:START -->\n- [@doikayt/NX-graph-to-mermaid](#doikaytnx-graph-to-mermaid)\n  - [Overview](#overview)\n  - [Adding Documentation To NX Configuration](#adding-documentation-to-nx-configuration)\n  - [Installation](#installation)\n  - [Extending `project.json`](#extending-projectjson)\n  - [Dependency Rendering](#dependency-rendering)\n- [Usage](#usage)\n  - [Diagram Injection Targets Special Start/End Markers](#diagram-injection-targets-special-startend-markers)\n  - [Generate Mode](#generate-mode)\n  - [Inject Mode](#inject-mode)\n  - [Update Mode (Generate + Inject)](#update-mode-generate--inject)\n  - [Check Mode (CI Drift Detection)](#check-mode-ci-drift-detection)\n  - [Debug Mode](#debug-mode)\n- [Single-File Operation Only](#single-file-operation-only)\n- [Determinism](#determinism)\n- [Full Example](#full-example)\n- [Built With](#built-with)\n- [Packaging, Publishing, and Inter-relationship with Other Plugins](#packaging-publishing-and-inter-relationship-with-other-plugins)\n  - [Contributing and Releasing](#contributing-and-releasing)\n- [License](#license)\n<!-- TOC:END -->\n\n\n# @doikayt/NX-graph-to-mermaid\n\n> Deterministically generates Mermaid task flow diagrams from NX `project.json` config files.\n\n`NX-graph-to-mermaid` is an **NX** (See: https://NX.dev/) plugin that generates deterministic [Mermaid](https://www.mermaid.ai/) task flow diagrams from an NX `project.json` file — with optional Markdown injection and CI drift detection support.\n\nIt operates purely on the specified `project.json`. Cross-project dependencies are named in the diagram but not expanded — their internal target graphs are not followed.\n\nSo, basically: no monorepo recursion (but contributions are always welcome!)\n\n\n\n<p align=\"center\">\n  <img\n    src=\"docs/demo.gif\"\n    width=\"720\"\n    alt=\"nx-graph-to-mermaid demo\">\n</p>\n\n\nIn the above quick demo, we use the `nx-graph-to-mermaid` plugin to update this README file:\n\n```aiignore\n  # Sample Project\n\n  ## Task Graph\n\n  <!-- NX_GRAPH:START -->\n  <!-- NX_GRAPH:END -->\n  EOF\n\n```\n\nBetween the START and END markers we inject a Mermaid diagram generated from a `project.json` file\nwith contents like this:\n\n```aiignore\n{\n  \"name\": \"sample\",\n  \"targets\": {\n    \"test\": {\n      \"executor\": \"nx:run-commands\",\n      \"description\": \"Run unit tests\",\n      \"options\": {\n        \"command\": \"echo Running tests\"\n      }\n    },\n    \"build\": {\n      \"executor\": \"nx:run-commands\",\n      \"description\": \"Build the project\",\n      \"dependsOn\": [\"test\"],\n      \"options\": {\n        \"command\": \"echo Building project\"\n      }\n    },\n    \"task-graph:inject\": {\n      \"executor\": \"@doikayt/nx-graph-to-mermaid:run\",\n      \"options\": {\n        \"mode\": \"update\",\n        \"projectJsonPath\": \"apps/sample/project.json\",\n        \"markdownPath\": \"apps/sample/README.md\"\n      }\n    }\n  }\n}\n```\n\nThis image will be generated as a result\n\n```mermaid\ngraph TD\n\n  build[\"build<br/>Build the project\"]\n  task_graph_inject\n  test[\"test<br/>Run unit tests\"]\n\n  build --> test\n```\n\n\nSee [Full Example](#full-example) for a more extensive\nexample of how project.json relates to the corresponding generated Mermaid diagram.\n\n---\n\n\n## Overview\n\nPlugin behavior is controlled entirely by `options.mode`.\n\nSupported modes:\n\n- `generate` — Generate a deterministic Mermaid diagram from a specified `project.json`.\n- `inject` — Inject a previously generated Mermaid document into a Markdown file between NX_GRAPH markers.\n- `check` — Validate that an existing Mermaid diagram matches what would be generated from `project.json`.\n- `update` — Regenerate the Mermaid diagram and inject it into a Markdown file.\n\n\n## Adding Documentation To NX Configuration\n\nYour [`project.json`](https://NX.dev/docs/reference/project-configuration) already defines the execution graph of your build.\n\nBy extending targets with a `description` field:\n\n```json\n{\n  \"release\": {\n    \"dependsOn\": [\"package\"],\n    \"description\": \"Full release pipeline\"\n  }\n}\n```\nyour documentation will co-reside with configuration metadata.\n\n`nx-graph-to-mermaid` compiles that metadata into a deterministic Mermaid diagram suitable for Markdown rendering.\n\n---\n\n## Installation\n\n```bash\nnpm install --save-dev @doikayt/nx-graph-to-mermaid\n```\n\n---\n\n## Extending `project.json`\n\nAdd a `description` field to any target:\n\n```json\n{\n  \"targets\": {\n    \"build\": {\n      \"dependsOn\": [\"lint\", \"test\"],\n      \"description\": \"Runs lint and test\"\n    }\n  }\n}\n```\n\nNX ignores unknown fields, so this is safe.\n\n---\n\n## Dependency Rendering\n\nEach string in a `dependsOn` array is classified and rendered as follows:\n\n| Entry form | Example | Rendered as |\n|---|---|---|\n| Plain local target name | `\"lint\"` | Arrow to that target node |\n| Same-project qualified ref | `\"my-project:check-all\"` | Arrow to the local target (prefix stripped) |\n| `^` upstream fan-out | `\"^build\"` | Arrow to a synthetic `^build` stadium node |\n| Cross-project ref | `\"@scope/pkg:build\"` | Arrow to a synthetic `pkg:build` hexagon node (scope stripped from label) |\n\n**`^` fan-out deps** deserve special mention. NX's `^target` shorthand means \"before running this target, \nrun `target` across every project in the upstream dependency closure.\" For example, `^build` on a `ci` task \ntriggers a `build` run on all packages listed in `implicitDependencies` — and transitively \non their dependencies — before `ci` is allowed to start. It is a graph-wide fan-out, \nnot a reference to any single local target.\n\nThe diagram renders `^target` entries as synthetic pill-shaped (stadium) nodes — e.g. `([^build])` — so \nthe dependency is visible without implying a local target exists. Multiple targets that share the same `^dep` \nall point to the same synthetic node.\n\n**Cross-project refs** (e.g. `@scope/pkg:build`) are rendered as **hexagon** nodes. The org \nscope (`@scope/`) is stripped from the display label for readability — so \n`@doikayt/tooling-core:lint` appears as `tooling-core:lint` inside the hex. \nThe full dep string is still encoded in the node ID in the Mermaid source. The \nref is named but not expanded — the internal dependency graph of the referenced project is not followed.\n\nFor an example of how all this appears together in a diagram, refer to the \n[Build Targets](../README.md#build-targets) section  of the README\nfor  the orchestrating workspace.\n\n---\n\n# Usage\n\nAll modes use the same executor:\n\n```json\n\"executor\": \"@doikayt/nx-graph-to-mermaid:run\"\n```\n\nBehavior is controlled exclusively by `options.mode`.\n\n\n## Diagram Injection Targets Special Start/End Markers\n\nNX-graph-to-mermaid uses fixed markers to inject the generated Mermaid diagram into a Markdown file:\n\n```\n<!-- NX_GRAPH:START -->\n<!-- NX_GRAPH:END -->\n```\n\n\n---\n\n## Generate Mode\n\nAdd a target:\n\n```json\n{\n  \"task-graph:generate\": {\n    \"executor\": \"@doikayt/nx-graph-to-mermaid:run\",\n    \"options\": {\n      \"mode\": \"generate\",\n      \"projectJsonPath\": \"project.json\",\n      \"generatedMermaidPath\": \"docs/task-graph.md\"\n    }\n  }\n}\n```\n\n**This mode:**  \nReads the specified `project.json`, extracts all target definitions, resolves `dependsOn` relationships, and \nincorporates optional `description` metadata. It then renders a fully deterministic Mermaid diagram and writes it to disk.\n\nWhat it does:\n\n- Reads target definitions\n- Reads `dependsOn` relationships\n- Reads optional `description` metadata\n- Sorts targets deterministically\n- Sorts dependencies deterministically\n- Outputs normalized Mermaid markup\n\nRun:\n\n```bash\nnpx nx run my-project:task-graph:generate\n```\n\n---\n\n## Inject Mode\n\nAdd a target:\n\n```json\n{\n  \"task-graph:inject\": {\n    \"executor\": \"@doikayt/nx-graph-to-mermaid:run\",\n    \"options\": {\n      \"mode\": \"inject\",\n      \"projectJsonPath\": \"project.json\",\n      \"generatedMermaidPath\": \"docs/task-graph.md\",\n      \"markdownPath\": \"README.md\"\n    }\n  }\n}\n```\n\n**This mode:**  \nPerforms deterministic Markdown injection only. It does not generate a graph. It reads a previously generated Mermaid artifact and replaces the content between fixed markers inside the specified Markdown file.\n\nIt requires:\n\n- A path to the generated Mermaid document\n- A path to the target Markdown file\n\n\nRun:\n\n```bash\nnpx nx run my-project:task-graph:inject\n```\n\n---\n\n## Update Mode (Generate + Inject)\n\nAdd a target:\n\n```json\n{\n  \"task-graph:update\": {\n    \"executor\": \"@doikayt/nx-graph-to-mermaid:run\",\n    \"options\": {\n      \"mode\": \"update\",\n      \"projectJsonPath\": \"project.json\",\n      \"markdownPath\": \"README.md\",\n      \"generatedMermaidPath\": \"docs/task-graph.md\"\n    }\n  }\n}\n```\n\n**This mode:**  \nCombines generation and injection in a single deterministic operation. It regenerates the Mermaid diagram from `project.json`, injects it into the specified Markdown file between NX_GRAPH markers, and optionally writes the generated artifact to disk.\n\n> **`generatedMermaidPath` is optional in update mode.** Omit it to regenerate and inject in one step without writing a separate Mermaid file to disk.\n\nRun:\n\n```bash\nnpx nx run my-project:task-graph:update\n```\n\n---\n\n## Check Mode (CI Drift Detection)\n\nAdd a target:\n\n```json\n{\n  \"task-graph:check\": {\n    \"executor\": \"@doikayt/nx-graph-to-mermaid:run\",\n    \"options\": {\n      \"mode\": \"check\",\n      \"projectJsonPath\": \"project.json\",\n      \"markdownPath\": \"README.md\"\n    }\n  }\n}\n```\n\n**This mode:**  \nRegenerates the diagram in memory and compares it against the content currently between the `NX_GRAPH` markers in the specified Markdown file. If any difference is detected, it returns `{ success: false }`, making it suitable for CI enforcement.\n\nRun:\n\n```bash\nnpx nx run my-project:task-graph:check\n```\n\nIf drift is detected:\n\n- A failure message is printed\n- The executor returns `{ success: false }`\n- CI exits with a non-zero status\n\nThis prevents stale diagrams from being merged.\n\n> **Setup requirement:** check mode compares the current marker content byte-for-byte against the freshly generated diagram. A file with empty markers (no injected content yet) will always fail. Run `update` mode once first to populate the markers, then commit the result before enabling check mode in CI.\n\n---\n\n## Debug Mode\n\nAdd `\"debug\": true` to any executor target's options to emit diagnostic messages\nto `stderr`. Each message is prefixed with `[debug]`, keeping it separate from\nnormal stdout output and safe to ignore in CI logs.\n\n```json\n{\n  \"task-graph:update\": {\n    \"executor\": \"@doikayt/nx-graph-to-mermaid:run\",\n    \"options\": {\n      \"mode\": \"update\",\n      \"projectJsonPath\": \"project.json\",\n      \"markdownPath\": \"README.md\",\n      \"debug\": true\n    }\n  }\n}\n```\n\nEach run logs:\n\n- Raw and normalized options (mode, resolved file paths)\n- Number of targets loaded from `project.json`\n- Length of the generated Mermaid output\n- Final `{ success }` result\n\n---\n\n# Single-File Operation Only\n\nThis tool operates on an explicit (`projectJsonPath`, `markdownPath`) pair and does not \nsupport recursive folder traversal. Each `NX_GRAPH` marker block is tied to a \nspecific `project.json`, so the association must be declared explicitly \nvia the aforementioned executor options pair. \n\n---\n\n# Determinism\n\nOutput is fully deterministic:\n\n- Targets sorted alphabetically\n- Dependencies sorted\n- Whitespace normalized\n- No timestamps\n- No randomness\n\nThe tool operates purely on `project.json`.\nIdentical input → identical output.\n\n\n---\n\n# Full Example\n\nA six-stage pipeline: `lint` and `docs` are independent roots; `test` depends on `lint`; `build` depends on both `lint` and `test`; `package` depends on `build`; `release` converges both `package` and `docs`.\n\n- Input: [`tests/fixtures/realistic-pipeline/project.json`](tests/fixtures/realistic-pipeline/project.json)\n- Golden output: [`tests/fixtures/realistic-pipeline/expected-readme.md`](tests/fixtures/realistic-pipeline/expected-readme.md)\n\nThe golden file is the CI assertion — `check` mode regenerates the diagram and diffs against it, so the output can never silently drift.\n\n---\n# Built With\n\n- [`@doikayt/tooling-core`](../tooling-core/README.md) — shared internal utilities\n\nFor the full workspace tech stack see: [TECH-STACK.md](../TECH-STACK.md)\n\n---\n# Packaging, Publishing, and Inter-relationship with Other Plugins\n\nThis package is one component of a small ecosystem of JavaScript tooling plugins maintained as individual npm packages in this repository.  The versioning and release of these packages is governed by a coordinated release policy, and the packages adhere to common design and architectural principles policies that are more completely described [here](../README.md).\n\n\n---\n\n\n\n## Contributing and Releasing\n\nFor code overview, development setup, build workflow, and release procedures (including how to\ntrigger a publish via Changesets), see\n[CONTRIBUTING.md](./docs/CONTRIBUTING.md).\n\n---\n\n\n\n\n\n\n# License\n\nMIT\n\n[![Remember the USS Liberty!](https://badge.techforpalestine.org/ceasefire-now)](https://techforpalestine.org/learn-more)\n","readmeFilename":"README.md"}