flownav 0.1.1 → 0.1.3

package/README.md

@@ -11,7 +11,7 @@ It is read-only against n8n. Inspired by [graphify](https://github.com/safishams
 ## Why
 
 - **Token cost.** A real workflow export is large and mostly noise. `flownav explain "Node"` is about ten lines.
-- **The rename gap.** When you rename or delete a node, n8n updates the connections but not `$('Old Name')` inside other nodes' expressions or Code nodes. Those silently break. `flownav affected "Old Name" --rename` lists exactly which nodes and parameters will break, before you change anything.
+- **The rename gap.** The n8n editor tries to rewrite `$('Old Name')` references when you rename a node, but community reports describe that as imperfect, and references inside Code nodes' JavaScript are reported not to be rewritten. Renames that don't go through the editor (the API, edited JSON, an AI agent changing a workflow) don't get that rewrite step at all, and deleting a node never fixes the references to it. A broken reference fails silently. `flownav affected "Old Name" --rename` lists exactly which nodes and parameters reference the node by name, so you can check them before and after you change anything.
 - **Cross-workflow structure.** Sub-workflows, agent tool workflows, error workflows and webhook-to-webhook calls become edges, so you can ask what calls what across your whole instance.
 
 ## Install
@@ -112,8 +112,10 @@ outputs:
 $ flownav affected "Normalize" --rename
 wf-orders:Normalize — impact of rename
 2 node(s) reference "Normalize" by name and will break unless their expressions are rewritten:
-  ✗ wf-orders:Notify Sales uses {email}  in text
-  ✗ wf-orders:Orphan Code uses {email}  in jsCode
+  × wf-orders:Notify Sales uses {email}  in text
+      text: {{ 'Big order from ' + $('Normalize').item.json.email }}
+  × wf-orders:Orphan Code uses {email}  in jsCode
+      jsCode: L1: const row = $('Normalize').first().json.email;
 ```
 
 **A path, even across workflows**
@@ -158,12 +160,12 @@ $ flownav check
   ERROR dead-refs          [wf-orders] Orphan Code reads "Deleted Step", which does not exist
   WARN  fragile-reads      [wf-orders] Orphan Code reads $('Normalize') but Normalize is not upstream via main; it may not have run
   WARN  unreachable        [wf-orders] Orphan Code is not reachable from any trigger
-  INFO  cycles             [wf-orders] loop (Loop Over Items): Ping Self ⇄ Loop Orders
+  INFO  cycles             [wf-orders] loop (Loop Over Items): Ping Self <-> Loop Orders
   INFO  dead-ends          [wf-orders] Loop Orders output [0 done] is not connected
   INFO  no-error-handler   [wf-enrich] Enrich customer has no error workflow and no node-level error handling
 ```
 
-`check` exits with code 1 when it finds an `ERROR`, so it can run in CI.
+`check` exits with code 1 when it finds an `ERROR`. Use `--fail-on warn` (or `info`) to fail on less severe findings, `--fail-on none` to always exit 0, and `--only a,b` to run just some checks. See [Use it in CI](#use-it-in-ci).
 
 ## Using it with an AI agent
 
@@ -250,7 +252,8 @@ flownav path <A> <B> [--max N --kinds a,b]
 flownav find [--type --cred --text --name --resource --workflow --match --disabled --trigger]
 flownav affected <node> --rename|--delete|--schema|--behavior
 flownav callers <workflow> | calls <workflow> | uses --cred <c>
-flownav check [--only fragile-reads|dead-refs|cycles|unreachable|dead-ends|no-error-handler|webhook-no-respond]
+flownav check [--only a,b] [--fail-on error|warn|info|none]
+                                      checks: fragile-reads, dead-refs, cycles, unreachable, dead-ends, no-error-handler, webhook-no-respond
 flownav view [workflow] [--match text --collapse --focus <node> --depth N --out file.html --open]
 flownav diagram [workflow] [--match text --collapse --focus <node> --depth N --no-reads --dir LR|TD --out file.md]
 flownav diff old.json new.json        what changed between two graphs
@@ -260,6 +263,32 @@ flownav serve                         MCP server on stdio
 
 Global options: `--graph <file>` and `--format text|json`. Nodes are addressed as `Name` or `workflow:Name` (workflow id or name).
 
+## Use it in CI
+
+`flownav check` exits with code 1 when it finds an error, and `--only dead-refs` limits it to broken references (a node that reads a node that no longer exists, a connection to a missing node, a call to a missing workflow). Two ways to feed it, as a GitHub Actions example:
+
+```yaml
+name: n8n workflow check
+on: [pull_request]
+jobs:
+  flownav:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      # Option A: workflow JSON exported into the repo (e.g. ./workflows)
+      - run: npx -y flownav build ./workflows
+      # Option B: a live instance with a read-only API key stored as a secret
+      # - run: npx -y flownav sync --url ${{ secrets.N8N_URL }}
+      #   env:
+      #     N8N_API_KEY: ${{ secrets.N8N_API_KEY }}
+      - run: npx -y flownav check --only dead-refs
+```
+
+For a manual "before I touch this" step, run `flownav affected "Node" --rename` instead. flownav is static analysis: it can only gate on what it can see, so references built at runtime are reported as unresolved and are not failures.
+
 ## Privacy and safety
 
 - Read-only against n8n: the only network method is `GET`.

package/dist/assemble.js

@@ -1,7 +1,7 @@
 import { CROSS_KINDS } from './types.js';
 import { shortType } from './util.js';
 /** Bump whenever extraction logic changes so cached per-workflow results are not reused. */
-export const BUILDER_VERSION = 4;
+export const BUILDER_VERSION = 5;
 export const wfOf = (g, id) => {
     if (id.startsWith('wf:'))
         return id.slice(3);

package/dist/build.js

@@ -1,5 +1,16 @@
-import { expressionBodies, extractRefs } from './expressions.js';
+import { expressionBlocks, extractRefs } from './expressions.js';
 import { redactString, rlValue, sha, shortType, stable, trunc, walkStrings } from './util.js';
+const MAX_SNIPPETS = 3;
+const clip = (s, n = 140) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
+/** `L12: <the line>` for a reference at offset `at` of a code string. */
+function codeSnippet(raw, at) {
+    const line = raw.slice(0, at).split('\n').length;
+    const start = raw.lastIndexOf('\n', at - 1) + 1;
+    let end = raw.indexOf('\n', at);
+    if (end < 0)
+        end = raw.length;
+    return `L${line}: ${clip(raw.slice(start, end).trim())}`;
+}
 const CODE_KEYS = new Set(['jsCode', 'pythonCode', 'functionCode', 'code']);
 const CODE_TYPES = new Set(['code', 'function', 'functionItem']);
 const TRIGGER_NAMES = new Set(['webhook', 'manualTrigger', 'start', 'cron', 'interval']);
@@ -254,26 +265,35 @@ export function buildWorkflow(raw, id, file) {
         const envs = new Set();
         let dynamic = 0;
         walkStrings(n.parameters, (s, path, key) => {
-            let body;
             // Only {{ }} blocks are expressions; the rest of an "=" string is literal text
             // (e.g. an HTML page whose browser JS contains $('form')).
-            if (s.startsWith('='))
-                body = expressionBodies(s);
-            else if (isCodeNode && CODE_KEYS.has(key))
-                body = s;
-            if (!body)
-                return;
-            const ex = extractRefs(body);
-            dynamic += ex.dynamic;
-            ex.env.forEach((e) => envs.add(`res:env:${e}`));
-            ex.vars.forEach((e) => envs.add(`res:var:${e}`));
-            for (const name of ex.inferred)
-                inf.set(name, new Set([...(inf.get(name) ?? []), path]));
-            for (const r of ex.refs) {
-                const a = acc.get(r.name) ?? { fields: new Set(), params: new Set() };
-                r.fields.forEach((f) => a.fields.add(f));
-                a.params.add(path);
-                acc.set(r.name, a);
+            const units = [];
+            if (s.startsWith('=')) {
+                for (const b of expressionBlocks(s)) {
+                    const whole = clip(s.slice(b.start, b.end).replace(/\s+/g, ' ').trim());
+                    units.push({ body: b.body, snip: () => whole });
+                }
+            }
+            else if (isCodeNode && CODE_KEYS.has(key)) {
+                units.push({ body: s, snip: (at) => codeSnippet(s, at) });
+            }
+            for (const u of units) {
+                const ex = extractRefs(u.body);
+                dynamic += ex.dynamic;
+                ex.env.forEach((e) => envs.add(`res:env:${e}`));
+                ex.vars.forEach((e) => envs.add(`res:var:${e}`));
+                for (const name of ex.inferred)
+                    inf.set(name, new Set([...(inf.get(name) ?? []), path]));
+                for (const r of ex.refs) {
+                    const a = acc.get(r.name) ?? { fields: new Set(), params: new Set(), snips: new Map() };
+                    r.fields.forEach((f) => a.fields.add(f));
+                    a.params.add(path);
+                    for (const at of r.at) {
+                        const text = u.snip(at);
+                        a.snips.set(`${path}\u0000${text}`, { param: path, text });
+                    }
+                    acc.set(r.name, a);
+                }
             }
         });
         for (const [name, a] of acc) {
@@ -286,6 +306,7 @@ export function buildWorkflow(raw, id, file) {
             edges.push({
                 from: nid(name), to: nid(n.name), kind: 'reads', confidence: 'EXTRACTED',
                 fields: [...a.fields].sort(), params: [...a.params].sort(),
+                snippets: [...a.snips.values()].slice(0, MAX_SNIPPETS),
             });
         }
         // Names reached via a loop variable over a literal list: real dependencies, but only INFERRED.

package/dist/checks.js

@@ -126,7 +126,7 @@ export function runChecks(g, only) {
                         : undefined;
                 f.push({
                     check: 'cycles', severity: kind ? 'info' : 'warn', wf: w.id,
-                    message: `${kind ?? 'cycle without Loop Over Items or Wait'}: ${comp.map((id) => g.nodeById.get(id).name).join(' ⇄ ')}`,
+                    message: `${kind ?? 'cycle without Loop Over Items or Wait'}: ${comp.map((id) => g.nodeById.get(id).name).join(' <-> ')}`,
                 });
             }
         }

package/dist/cli.js

@@ -172,14 +172,21 @@ program.command('uses').requiredOption('--cred <c>').action((o) => run(() => emi
 program
     .command('check')
     .description(`Health checks (${ALL_CHECKS.join(', ')})`)
-    .option('--only <name>', 'run a single check')
+    .option('--only <names>', 'run only these checks (comma separated)')
+    .option('--fail-on <level>', 'exit 1 when a finding is at least this severe: error | warn | info | none', 'error')
     .action((o) => run(() => {
-    if (o.only && !ALL_CHECKS.includes(o.only))
-        throw new Error(`Unknown check. Choose: ${ALL_CHECKS.join(', ')}`);
+    const only = o.only ? String(o.only).split(',').map((s) => s.trim()).filter(Boolean) : undefined;
+    const bad = (only ?? []).filter((x) => !ALL_CHECKS.includes(x));
+    if (bad.length)
+        throw new Error(`Unknown check "${bad.join(', ')}". Choose from: ${ALL_CHECKS.join(', ')}`);
+    const rank = { error: 0, warn: 1, info: 2 };
+    const failOn = String(o.failOn);
+    if (failOn !== 'none' && !(failOn in rank))
+        throw new Error('--fail-on must be one of: error, warn, info, none');
     const g = load();
-    const f = runChecks(g, o.only ? [o.only] : undefined);
+    const f = runChecks(g, only);
     emit(formatFindings(g, f));
-    if (f.some((x) => x.severity === 'error'))
+    if (failOn !== 'none' && f.some((x) => rank[x.severity] <= rank[failOn]))
         process.exitCode = 1;
 })());
 program

package/dist/expressions.js

@@ -24,35 +24,51 @@ function field(tail, needAccessor) {
         .join('.');
 }
 const unescape = (s) => s.replace(/\\(.)/g, '$1');
-/** Text inside {{ ... }} blocks of an expression string. */
-export function expressionBodies(s) {
+/** `{{ ... }}` blocks of an expression string: the inner code and where the whole block sits. */
+export function expressionBlocks(s) {
     const out = [];
     const re = /\{\{([\s\S]*?)\}\}/g;
     let m;
     while ((m = re.exec(s)))
-        out.push(m[1]);
-    return out.join('\n');
+        out.push({ body: m[1], start: m.index, end: m.index + m[0].length });
+    return out;
+}
+/** Text inside {{ ... }} blocks of an expression string. */
+export function expressionBodies(s) {
+    return expressionBlocks(s).map((b) => b.body).join('\n');
 }
 // String literals worth keeping: the argument of $('X') / $items('X') / $node['X'] and ["field"] accesses.
 const KEEP_BEFORE = /(?:\$\(|\$items\(|\$node\[|[\w$\])]\[)\s*$/;
 /**
  * Blank out comments and string-literal contents so text such as an HTML page held in a
  * string (`"...$('form')..."`) is not mistaken for a node reference. Template-literal
- * `${...}` code is kept and scanned.
+ * `${...}` code is kept and scanned. The result has the same length as the input (removed
+ * characters become spaces, newlines are kept), so offsets and line numbers still line up.
  */
 export function stripLiterals(src) {
-    let out = '';
+    const a = src.split('');
+    const blank = (from, to) => {
+        for (let k = from; k < to; k++)
+            if (a[k] !== '\n')
+                a[k] = ' ';
+    };
+    const before = (i) => a.slice(Math.max(0, i - 24), i).join('');
     let i = 0;
     while (i < src.length) {
         const c = src[i];
         if (c === '/' && src[i + 1] === '/') {
-            while (i < src.length && src[i] !== '\n')
-                i++;
+            let j = i;
+            while (j < src.length && src[j] !== '\n')
+                j++;
+            blank(i, j);
+            i = j;
             continue;
         }
         if (c === '/' && src[i + 1] === '*') {
             const e = src.indexOf('*/', i + 2);
-            i = e < 0 ? src.length : e + 2;
+            const j = e < 0 ? src.length : e + 2;
+            blank(i, j);
+            i = j;
             continue;
         }
         if (c === '"' || c === "'") {
@@ -62,13 +78,16 @@ export function stripLiterals(src) {
                     j++;
                 j++;
             }
-            out += KEEP_BEFORE.test(out) ? src.slice(i, j + 1) : c + c;
+            if (!KEEP_BEFORE.test(before(i)))
+                blank(i + 1, Math.min(j, src.length));
             i = j + 1;
             continue;
         }
         if (c === '`') {
+            const keep = KEEP_BEFORE.test(before(i));
+            const texts = [];
+            let segStart = i + 1;
             let j = i + 1;
-            let code = '';
             while (j < src.length && src[j] !== '`') {
                 if (src[j] === '\\') {
                     j += 2;
@@ -84,20 +103,26 @@ export function stripLiterals(src) {
                             depth--;
                         k++;
                     }
-                    code += ` ${stripLiterals(src.slice(j + 2, k - 1))} `;
+                    texts.push([segStart, j]);
+                    const inner = stripLiterals(src.slice(j + 2, k - 1));
+                    for (let m = 0; m < inner.length; m++)
+                        a[j + 2 + m] = inner[m];
+                    segStart = k;
                     j = k;
                     continue;
                 }
                 j++;
             }
-            out += KEEP_BEFORE.test(out) ? src.slice(i, j + 1) : '``' + code;
+            texts.push([segStart, Math.min(j, src.length)]);
+            if (!keep)
+                for (const [s, e] of texts)
+                    blank(s, e);
             i = j + 1;
             continue;
         }
-        out += c;
         i++;
     }
-    return out;
+    return a.join('');
 }
 const STR = /(['"`])((?:\\.|(?!\1)[^\\])*)\1/g;
 /** Names in an array literal made only of string literals, else undefined. */
@@ -139,17 +164,18 @@ const RE_VARUSE = /\$(?:\(|items\()\s*([A-Za-z_$][\w$]*)\s*[,)]|\$node\s*\[\s*([
 export function extractRefs(raw) {
     const src = stripLiterals(raw);
     const byName = new Map();
-    const add = (name, f) => {
-        const set = byName.get(name) ?? new Set();
+    const add = (name, at, f) => {
+        const cur = byName.get(name) ?? { fields: new Set(), at: [] };
         if (f)
-            set.add(f);
-        byName.set(name, set);
+            cur.fields.add(f);
+        cur.at.push(at);
+        byName.set(name, cur);
     };
     const scan = (re, needAccessor) => {
         re.lastIndex = 0;
         let m;
         while ((m = re.exec(src))) {
-            add(unescape(m[2]), field(src.slice(re.lastIndex, re.lastIndex + 240), needAccessor));
+            add(unescape(m[2]), m.index, field(src.slice(re.lastIndex, re.lastIndex + 240), needAccessor));
         }
     };
     scan(RE_PAREN, true);
@@ -175,7 +201,7 @@ export function extractRefs(raw) {
         hit.forEach((n) => inferred.add(n));
     }
     return {
-        refs: [...byName].map(([name, f]) => ({ name, fields: [...f].sort() })),
+        refs: [...byName].map(([name, v]) => ({ name, fields: [...v.fields].sort(), at: v.at.sort((x, y) => x - y) })),
         inferred: [...inferred],
         env: names(RE_ENV),
         vars: names(RE_VARS),

package/dist/install.js

@@ -16,7 +16,7 @@ Then query the graph; do not open workflow JSON unless the graph cannot answer.
 - \`flownav path A B\` ordered paths with edge kinds and labels
 - \`flownav neighbors "<node>" --depth 2\`
 - \`flownav find --type httpRequest --cred slack --text "api.example"\`
-- \`flownav affected "<node>" --rename|--delete|--schema|--behavior\` **run before renaming or deleting a node**: expressions like \`$('Old Name')\` are not updated by n8n when connections are
+- \`flownav affected "<node>" --rename|--delete|--schema|--behavior\` **run before renaming or deleting a node**: references like \`$('Old Name')\` are not reliably rewritten (reportedly not inside Code nodes, and not for renames made through the API or by editing JSON), so list them first
 - \`flownav callers <workflow>\` / \`calls <workflow>\` cross-workflow links
 - \`flownav check\` fragile reads, dead refs, unreachable nodes, cycles, missing error handling
 

package/dist/mcp.js

@@ -17,7 +17,7 @@ const TOOLS = [
     { name: 'flownav_callers', description: 'Which workflows/nodes call this workflow (Execute Workflow, tool workflows, error workflow, webhook calls).', schema: { workflow: str }, run: (g, a) => callers(g, a.workflow) },
     { name: 'flownav_calls', description: 'What this workflow calls, plus unresolved dynamic calls.', schema: { workflow: str }, run: (g, a) => calls(g, a.workflow) },
     { name: 'flownav_uses', description: 'Nodes that use a credential (id, name or type).', schema: { credential: str }, run: (g, a) => uses(g, a.credential) },
-    { name: 'flownav_check', description: `Health checks: ${ALL_CHECKS.join(', ')}.`, schema: { only: str }, run: (g, a) => formatFindings(g, runChecks(g, a.only ? [a.only] : undefined)) },
+    { name: 'flownav_check', description: `Health checks: ${ALL_CHECKS.join(', ')}. Pass only="a,b" to run some.`, schema: { only: str }, run: (g, a) => formatFindings(g, runChecks(g, a.only ? String(a.only).split(',').map((x) => x.trim()) : undefined)) },
     { name: 'flownav_report', description: 'Full markdown workflow report.', schema: {}, run: (g) => report(g) },
 ];
 export function serve(graphFile) {

package/dist/queries.js

@@ -173,13 +173,15 @@ export function affected(g, q, mode = 'rename') {
     const readers = g.outE(n.id, ['reads']);
     const lines = [`${g.label(n.id)} — impact of ${mode}`];
     const data = { node: n.id, mode };
+    /** the reader line, then the exact expression or code line(s) under it */
+    const withSnips = (head, e) => [head, ...(e.snippets ?? []).map((s) => `      ${s.param}: ${s.text}`)];
     const fmtReader = (e) => `${g.label(e.to)}${e.fields?.length ? ` uses {${e.fields.join(', ')}}` : ''}  in ${(e.params ?? []).join(', ')}${e.confidence === 'INFERRED' ? '  (inferred from a literal name list)' : ''}`;
     if (mode === 'rename' || mode === 'delete') {
         lines.push(readers.length
             ? `${readers.length} node(s) reference "${n.name}" by name and will ${mode === 'rename' ? 'break unless their expressions are rewritten' : 'read a missing node'}:`
             : `No expression references "${n.name}" by name.${mode === 'rename' ? " Safe to rename (connections are keyed by name; update them with the rename)." : ''}`);
         for (const e of readers)
-            lines.push(`  ✗ ${fmtReader(e)}`);
+            lines.push(...withSnips(`  × ${fmtReader(e)}`, e));
         data.breaks = readers;
     }
     if (mode === 'delete') {
@@ -192,7 +194,7 @@ export function affected(g, q, mode = 'rename') {
         if (orphaned.length) {
             lines.push('lose their only input (become unreachable):');
             for (const d of orphaned)
-                lines.push(`  ✗ ${g.label(d)}`);
+                lines.push(`  × ${g.label(d)}`);
         }
         const heads = g.outE(n.id, ['capability']);
         if (heads.length) {
@@ -204,7 +206,7 @@ export function affected(g, q, mode = 'rename') {
         if (callers.length) {
             lines.push('callers that will fail:');
             for (const e of callers)
-                lines.push(`  ✗ ${g.label(e.from)}  (${edgeTag(e)})`);
+                lines.push(`  × ${g.label(e.from)}  (${edgeTag(e)})`);
         }
         data.orphaned = orphaned;
         data.callers = callers;
@@ -212,7 +214,7 @@ export function affected(g, q, mode = 'rename') {
     if (mode === 'schema') {
         lines.push(readers.length ? 'nodes reading fields from this node:' : 'No node reads this node by name.');
         for (const e of readers)
-            lines.push(`  ! ${fmtReader(e)}`);
+            lines.push(...withSnips(`  ! ${fmtReader(e)}`, e));
         const succ = g.outE(n.id, ['main']);
         if (succ.length) {
             lines.push('direct successors (may use $json / $input, field use is not tracked):');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "flownav",
-  "version": "0.1.1",
-  "description": "Typed node graph for n8n workflows: explain, path, affected (rename/delete safety), checks, and an MCP server so agents navigate workflows with far fewer tokens.",
+  "version": "0.1.3",
+  "description": "See what references an n8n node before you rename it. A typed graph of your workflows with a CLI and an MCP server, so AI agents read a few lines instead of the whole workflow JSON.",
   "author": "Omer Turkenits",
   "license": "MIT",
   "repository": {
@@ -32,8 +32,15 @@
   "keywords": [
     "n8n",
     "workflow",
+    "workflow-automation",
     "graph",
     "mcp",
+    "model-context-protocol",
+    "ai",
+    "ai-agents",
+    "claude",
+    "rename",
+    "static-analysis",
     "cli"
   ],
   "dependencies": {