valn8n 0.1.0__tar.gz

valn8n-0.1.0/.gitignore

@@ -0,0 +1,71 @@
+# From https://github.com/ArjanCodes/examples/blob/main/2024/vscode_python/.gitignore
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environment directories
+env/
+venv/
+ENV/
+env.bak/
+venv.bak
+.venv/
+
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis
+.pytest_cache
+cover
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# python version
+.python-version
+
+# Various tool caches (BaCh)
+.ruff_cache
+.mypy_cache
+
+# Various backup files (BaCh)
+*~
+*.bak
+
+# This project
+n8n-src/

valn8n-0.1.0/.mypy.ini

@@ -0,0 +1,15 @@
+[mypy]
+exclude = .venv/
+#plugins = pydantic.mypy
+disallow_untyped_defs = True
+disallow_any_unimported = True
+no_implicit_optional = True
+check_untyped_defs = True
+warn_return_any = True
+show_error_codes = True
+warn_unused_ignores = True
+
+[pydantic-mypy]
+init_forbid_extra = True
+init_typed = True
+#warn_required_dynamic_aliases = True

valn8n-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,10 @@
+repos:
+  - repo: local
+    hooks:
+      - id: validate-commit-message
+        name: Validate Commit Message
+        language: python
+        entry: python devsupport/check_commitmsg.py
+        always_run: false
+        pass_filenames: true
+        stages: [commit-msg]

valn8n-0.1.0/.pylintrc

@@ -0,0 +1,14 @@
+[FORMAT]
+max-line-length=100
+
+[MESSAGES CONTROL]
+# Quieten pylint messages that are duplicate of other tools (ruff, pyright)
+# or where the rules get in each others way.
+disable=
+    R0912, # Duplicate of ruff PLR...
+    R0913, # Duplicate of ruff PLR...
+    R0915, # Duplicate of ruff PLR...
+    R1711, # Duplicate of ruff PLR...
+    unnecessary-ellipsis, #  makes pyright complain e.g. for protocol classes with return type
+    too-few-public-methods, # not useful for protocol/dataclass-heavy code
+    wrong-import-position # wrong-import-position - duplicate of Ruff E402. And pylint has different oppinion

valn8n-0.1.0/.vscode/extensions.json

@@ -0,0 +1,11 @@
+{
+    "recommendations": [
+        "ms-python.python",
+        "ms-python.vscode-pylance",
+        "charliermarsh.ruff",
+        "tamasfe.even-better-toml",
+        "aaron-bond.better-comments",
+        "github.vscode-github-actions",
+        "bierner.markdown-mermaid",
+    ]
+}

valn8n-0.1.0/.vscode/settings.json

@@ -0,0 +1,45 @@
+{
+    //    // Python settings
+    //    "python.analysis.autoSearchPaths": true,
+    // These are driving me nuts when using PyTorch, and as pyright has no way to switch 
+    // them off on a file by file basis ... screw it, and trust mypy
+    "python.analysis.diagnosticSeverityOverrides": {
+        "reportMissingTypeArgument": "none",
+        "reportUnknownArgumentType": "none",
+        "reportUnknownMemberType": "none",
+        "reportUnknownParameterType": "none",
+        "reportUnknownVariableType": "none",
+    },
+    //    "python.analysis.extraPaths": [
+    //        "${workspaceFolder}/src"
+    //    ],
+    //    "python.envFile": "${workspaceFolder}/.env",
+    //    "python.terminal.activateEnvironment": true,
+    //    // Test settings
+    //    "python.testing.pytestEnabled": true,
+    //    "python.testing.unittestEnabled": false,
+    //    "python.testing.cwd": "${workspaceFolder}/tests",
+    //    "python.testing.pytestPath": "${workspaceFolder}/.venv/bin/pytest",
+    //    "python.testing.autoTestDiscoverOnSaveEnabled": true,
+    //
+    //
+    // we're going to use UVs virtual envs anyway, and VSCode doesn't seem to pick them up automatically
+    "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
+    // ruff formatter
+    "ruff.importStrategy": "useBundled",
+    // Editor settings, Python specific
+    "[python]": {
+        "editor.defaultFormatter": "charliermarsh.ruff",
+        "editor.formatOnPaste": true,
+        "editor.formatOnSave": true,
+        "editor.formatOnSaveMode": "file",
+    },
+    "spellright.language": [
+        "en_GB"
+    ],
+    "spellright.documentTypes": [
+        "latex",
+        "plaintext",
+        "markdown"
+    ],
+}

valn8n-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bastien Chevreux
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

valn8n-0.1.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: valn8n
+Version: 0.1.0
+Summary: A validator for n8n workflow JSON files
+Project-URL: Homepage, https://github.com/DrMicrobit/valn8n
+Project-URL: GitHub, https://github.com/DrMicrobit/valn8n
+Project-URL: Issues, https://github.com/DrMicrobit/valn8n/issues
+Author-email: Bastien Chevreux <bach@chevreux.org>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.13
+Requires-Dist: json-source-map>=1.0.5
+Requires-Dist: rich>=14.0.0
+Description-Content-Type: text/markdown
+
+# valn8n
+
+A validator for [n8n](https://n8n.io/) workflow JSON files. Like `ruff` for Python, but for your n8n workflows.
+
+Checks for errors, warning, and hints regarding syntax and semantics of workflows. Output in different formats (rich in terminal, text, JSON, CSV), most LLMs seem to work with 'text' quite well (tightly followed by JSON, but more tokens).
+
+Also, `valn8n` allows me to asses the quality or hidden traps of workflows downloaded from the web, saving a lot of time not bothering with sometimes totally broken workflows.
+
+## Background
+
+I have been testing n8n on and off with LLM assisted workflow generation and couldn't find a n8n workflow validator that would find whatever silly mistake an LLM (even flagship ones) could sometimes generate.
+
+With `valn8n` however I can have the LLMs autocorrect those errors and am getting most n8n workflows as one-shot.
+
+## Requirements
+
+- Python >= 3.13
+- [uv](https://docs.astral.sh/uv/getting-started/installation/) package and project manager
+
+## Installation
+
+```bash
+uv tool install valn8n
+```
+
+## Quick Start
+
+```bash
+valn8n check my_workflow.json
+valn8n check --strict-only my_workflow.json
+```
+
+See also README in supplied demo workflows in `demo_valn8n/broken_vs_notbroken`.
+
+## Usage
+
+### Check a single file
+
+```bash
+valn8n check workflow.json
+```
+
+### Check a directory
+
+```bash
+valn8n check workflows/
+```
+
+### Select specific rules
+
+Only check rules ND01xx and ND05xx.
+
+```bash
+valn8n check --select ND01,ND05 workflow.json
+```
+
+### Ignore specific rules
+
+Ignore ND05xx and ND0802.
+
+```bash
+valn8n check --ignore ND05,ND0802 workflow.json
+```
+
+### Switching back on ignored rules
+
+Ignore ND05xx but not ND0502.
+
+```bash
+valn8n check --ignore ND05 --extend-select ND0502 workflow.json
+```
+
+### Strict-only mode
+
+Run only strict rules, skipping advisory and hint rules:
+
+```bash
+valn8n check --strict-only workflow.json
+```
+
+### JSON output (for CI)
+
+```bash
+valn8n check --fmt json workflow.json
+```
+
+### Quiet mode (summary only)
+
+```bash
+valn8n check -q workflow.json
+```
+
+### Tolerate unknown node keys
+
+```bash
+valn8n check --tolerate-node-keys '*' workflow.json
+```
+
+### List all rules
+
+```bash
+valn8n rule
+```
+
+## Output Formats
+
+| Format | Flag | Description |
+|--------|------|-------------|
+| Rich | `--fmt rich` | Colored terminal output (default) |
+| Text | `--fmt text` | Plain text |
+| JSON | `--fmt json` | Machine-readable JSON |
+| CSV | `--fmt csv` | Comma-separated values |
+| List | `--fmt lst` | One diagnostic per line |
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | No violations found |
+| 1 | Violations found |
+| 2 | Error (e.g. file not found, invalid arguments) |
+
+## Rules
+
+| Group | Range | Description |
+|-------|-------|-------------|
+| IO | IO00xx | File I/O validation (read errors, invalid JSON) |
+| ND01 | ND01xx | Filter operations (invalid ops, common mistakes) |
+| ND02 | ND02xx | Node structure (unknown keys, value types, zero-property params) |
+| ND03 | ND03xx | Parameter validation (deep param keys, param value types) |
+| ND04 | ND04xx | Expression syntax (broken brackets, suspect prefixes) |
+| ND05 | ND05xx | Credential validation (missing, empty, placeholder, leaking) |
+| ND06 | ND06xx | Connection validation (unconnected inputs, dangling refs) |
+| ND07 | ND07xx | Error handling (missing errorWorkflow, unhandled errors) |
+| ND08 | ND08xx | Naming & documentation (default names, missing notes) |
+
+Rules ND01xx-ND04xx and ND06xx are **strict** (structural correctness). ND05xx and 07xx are **advisory** (best practices). ND08xx are **hints** (atm only regarding naming clarity and documentation).
+
+Note: in future this may change and strict/advisory might not be clean ranges anymore.
+
+Use `--strict-only` to run only strict rules.
+
+Run `valn8n rule` to see the full list with descriptions.
+
+## Contributing
+
+I do not accept PRs with code changes at the moment. But feel free to post issues (with full workflows attached) in case you think there is an error in valn8n, or if you see an opportunity to improve it.

valn8n-0.1.0/README.md

@@ -0,0 +1,147 @@
+# valn8n
+
+A validator for [n8n](https://n8n.io/) workflow JSON files. Like `ruff` for Python, but for your n8n workflows.
+
+Checks for errors, warning, and hints regarding syntax and semantics of workflows. Output in different formats (rich in terminal, text, JSON, CSV), most LLMs seem to work with 'text' quite well (tightly followed by JSON, but more tokens).
+
+Also, `valn8n` allows me to asses the quality or hidden traps of workflows downloaded from the web, saving a lot of time not bothering with sometimes totally broken workflows.
+
+## Background
+
+I have been testing n8n on and off with LLM assisted workflow generation and couldn't find a n8n workflow validator that would find whatever silly mistake an LLM (even flagship ones) could sometimes generate.
+
+With `valn8n` however I can have the LLMs autocorrect those errors and am getting most n8n workflows as one-shot.
+
+## Requirements
+
+- Python >= 3.13
+- [uv](https://docs.astral.sh/uv/getting-started/installation/) package and project manager
+
+## Installation
+
+```bash
+uv tool install valn8n
+```
+
+## Quick Start
+
+```bash
+valn8n check my_workflow.json
+valn8n check --strict-only my_workflow.json
+```
+
+See also README in supplied demo workflows in `demo_valn8n/broken_vs_notbroken`.
+
+## Usage
+
+### Check a single file
+
+```bash
+valn8n check workflow.json
+```
+
+### Check a directory
+
+```bash
+valn8n check workflows/
+```
+
+### Select specific rules
+
+Only check rules ND01xx and ND05xx.
+
+```bash
+valn8n check --select ND01,ND05 workflow.json
+```
+
+### Ignore specific rules
+
+Ignore ND05xx and ND0802.
+
+```bash
+valn8n check --ignore ND05,ND0802 workflow.json
+```
+
+### Switching back on ignored rules
+
+Ignore ND05xx but not ND0502.
+
+```bash
+valn8n check --ignore ND05 --extend-select ND0502 workflow.json
+```
+
+### Strict-only mode
+
+Run only strict rules, skipping advisory and hint rules:
+
+```bash
+valn8n check --strict-only workflow.json
+```
+
+### JSON output (for CI)
+
+```bash
+valn8n check --fmt json workflow.json
+```
+
+### Quiet mode (summary only)
+
+```bash
+valn8n check -q workflow.json
+```
+
+### Tolerate unknown node keys
+
+```bash
+valn8n check --tolerate-node-keys '*' workflow.json
+```
+
+### List all rules
+
+```bash
+valn8n rule
+```
+
+## Output Formats
+
+| Format | Flag | Description |
+|--------|------|-------------|
+| Rich | `--fmt rich` | Colored terminal output (default) |
+| Text | `--fmt text` | Plain text |
+| JSON | `--fmt json` | Machine-readable JSON |
+| CSV | `--fmt csv` | Comma-separated values |
+| List | `--fmt lst` | One diagnostic per line |
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | No violations found |
+| 1 | Violations found |
+| 2 | Error (e.g. file not found, invalid arguments) |
+
+## Rules
+
+| Group | Range | Description |
+|-------|-------|-------------|
+| IO | IO00xx | File I/O validation (read errors, invalid JSON) |
+| ND01 | ND01xx | Filter operations (invalid ops, common mistakes) |
+| ND02 | ND02xx | Node structure (unknown keys, value types, zero-property params) |
+| ND03 | ND03xx | Parameter validation (deep param keys, param value types) |
+| ND04 | ND04xx | Expression syntax (broken brackets, suspect prefixes) |
+| ND05 | ND05xx | Credential validation (missing, empty, placeholder, leaking) |
+| ND06 | ND06xx | Connection validation (unconnected inputs, dangling refs) |
+| ND07 | ND07xx | Error handling (missing errorWorkflow, unhandled errors) |
+| ND08 | ND08xx | Naming & documentation (default names, missing notes) |
+
+Rules ND01xx-ND04xx and ND06xx are **strict** (structural correctness). ND05xx and 07xx are **advisory** (best practices). ND08xx are **hints** (atm only regarding naming clarity and documentation).
+
+Note: in future this may change and strict/advisory might not be clean ranges anymore.
+
+Use `--strict-only` to run only strict rules.
+
+Run `valn8n rule` to see the full list with descriptions.
+
+## Contributing
+
+I do not accept PRs with code changes at the moment. But feel free to post issues (with full workflows attached) in case you think there is an error in valn8n, or if you see an opportunity to improve it.

valn8n-0.1.0/demo_valn8n/broken_vs_notbroken/README.md

@@ -0,0 +1,17 @@
+# Demo
+
+## Comparison 'less-broken' vs 'totally broken' workflow
+
+We'll just look at 'strict' rules of `valn8n`. Run `valn8n check --strict-only lessbroken_3859-ai-customer-support-assistant-whatsapp-ready-works-for-any-business.json` which will result in one error (a wait between trials parameter apparently has a null value where it should have an int).
+
+Now compare with the proken version: `valn8n check --strict-only broken_1521_Whatsapp_Stickynote_Automation_Webhook.json` which has 42 errors, 13 warnings. Ouch. Feel free to paste both workflows into the n8n editor to also see the difference there.
+
+## Sources
+
+### Broken workflow
+
+`curl -L https://raw.githubusercontent.com/Zie619/n8n-workflows/main/workflows/Whatsapp/1521_Whatsapp_Stickynote_Automation_Webhook.json -o broken_1521_Whatsapp_Stickynote_Automation_Webhook.json`
+
+### Less broken workflow
+
+Downloaded on 15.03.2026 from: https://n8n.io/workflows/3859-ai-customer-support-assistant-whatsapp-ready-works-for-any-business/