@still-running/health-check 1.0.0

package/dist/core/checks/others.js

@@ -0,0 +1,160 @@
+"use strict";
+/**
+ * CHECK 3 — credential expiry risk.
+ * CHECK 2 — triggers with no expected cadence.
+ * CHECK 1 — error handling. Table stakes: six free tools already do this, so it
+ *           is a short footer, never the headline.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkCredentialExpiry = checkCredentialExpiry;
+exports.checkCadence = checkCadence;
+exports.checkErrorHandling = checkErrorHandling;
+const providers_js_1 = require("../providers.js");
+// ---------------------------------------------------------------- check 3
+function checkCredentialExpiry(wf) {
+    const findings = [];
+    const seen = new Set();
+    for (const node of wf.nodes) {
+        if (node.disabled)
+            continue;
+        for (const cred of node.credentials) {
+            const provider = cred.providerId
+                ? providers_js_1.PROVIDERS.find((p) => p.id === cred.providerId)
+                : (0, providers_js_1.resolveProvider)(cred.rawType, wf.platform);
+            // One finding per provider per workflow, not one per node. An agency with
+            // eight Google Sheets nodes has one Google problem, not eight.
+            const key = provider ? provider.id : cred.rawType;
+            if (seen.has(key))
+                continue;
+            if (provider) {
+                seen.add(key);
+                const conditional = provider.rules.filter((r) => r.certainty === 'conditional');
+                const shortest = provider.rules[0];
+                const severity = !provider.autoRefreshable ? 'high' : conditional.length > 0 ? 'medium' : 'low';
+                findings.push({
+                    checkId: 'credential-expiry',
+                    severity,
+                    nodeId: node.id,
+                    nodeLabel: node.label,
+                    title: `${provider.displayName} connection on "${node.label}" — expiry depends on how it was set up`,
+                    ifItGoesQuiet: provider.autoRefreshable
+                        ? `The token stops refreshing, the trigger stops firing, and there is no failed run to see — because there is no run at all.`
+                        : `Nothing on ${provider.displayName} refreshes this automatically. When it lapses, someone has to paste in a new token by hand, and until they do the workflow is silent.`,
+                    detail: [
+                        `We cannot read the expiry from a pasted workflow — the export names the connection, not the settings behind it. Here is what it depends on:`,
+                        ...provider.rules.map((r) => `- ${r.condition}: ${r.window}. ${r.detail}`),
+                    ].join('\n'),
+                    howToCheck: (shortest?.howToCheck ?? conditional[0]?.howToCheck) || undefined,
+                    sources: provider.sources,
+                });
+            }
+            else if (cred.authKind === 'oauth2') {
+                seen.add(key);
+                findings.push({
+                    checkId: 'credential-expiry',
+                    severity: 'low',
+                    nodeId: node.id,
+                    nodeLabel: node.label,
+                    title: `"${node.label}" uses an OAuth connection we do not have expiry data for yet`,
+                    ifItGoesQuiet: 'If this provider expires refresh tokens on a schedule, the trigger stops and no error is raised.',
+                    detail: `Connection type: ${cred.rawType}. Not in our provider table yet.`,
+                });
+            }
+        }
+    }
+    return findings;
+}
+// ---------------------------------------------------------------- check 2
+function checkCadence(wf) {
+    if (wf.cadence.expectedIntervalKnown)
+        return [];
+    const triggers = wf.nodes.filter((n) => wf.triggerIds.includes(n.id) && !n.disabled);
+    // No trigger in the file at all — usually a fragment or a sub-workflow. Say
+    // that plainly instead of inventing a cadence complaint about nothing.
+    if (triggers.length === 0 || wf.cadence.kind === 'unknown') {
+        return [
+            {
+                checkId: 'no-cadence',
+                severity: 'info',
+                nodeId: null,
+                nodeLabel: null,
+                title: 'No trigger in this file',
+                ifItGoesQuiet: 'Nothing to say yet — without a trigger there is no expected rhythm to measure against.',
+                detail: 'This is either a fragment, or a sub-workflow called by another one. Paste the workflow that calls it to see how often this is meant to run.',
+            },
+        ];
+    }
+    const label = triggers[0]?.label ?? 'the trigger';
+    if (wf.cadence.kind === 'manual') {
+        return [
+            {
+                checkId: 'no-cadence',
+                severity: 'low',
+                nodeId: triggers[0]?.id ?? null,
+                nodeLabel: triggers[0]?.label ?? null,
+                title: 'This workflow only runs when somebody presses the button',
+                ifItGoesQuiet: 'Nothing to detect — a manual workflow that never runs is not broken.',
+                detail: 'Nothing to monitor here until it gets a schedule or a webhook.',
+            },
+        ];
+    }
+    return [
+        {
+            checkId: 'no-cadence',
+            severity: wf.cadence.kind === 'event' ? 'high' : 'medium',
+            nodeId: triggers[0]?.id ?? null,
+            nodeLabel: triggers[0]?.label ?? null,
+            title: `Nothing here says how often "${label}" should fire`,
+            ifItGoesQuiet: 'There is no expected rhythm to compare against, so an idle workflow and a dead workflow look identical. Nobody can tell you it stopped, because nobody knows what "running normally" looks like.',
+            detail: wf.cadence.kind === 'event'
+                ? `This fires on an outside event (${wf.cadence.description}). If the source stops sending — a renamed field, a revoked webhook, a client who turned something off — the workflow simply never runs. There is no failed execution, because there is no execution.`
+                : `Trigger type: ${wf.cadence.description}. Without an expected interval there is no baseline.`,
+            howToCheck: 'Write down the number you would expect on a normal day: runs per day, or rows per run. That single number is what turns silence into an alert.',
+        },
+    ];
+}
+// ---------------------------------------------------------------- check 1
+function checkErrorHandling(wf) {
+    const findings = [];
+    const live = wf.nodes.filter((n) => !n.disabled && n.role !== 'note');
+    const unhandled = live.filter((n) => (n.role === 'write' || n.role === 'read' || n.platformType.includes('httpRequest')) &&
+        !n.errorHandling.hasErrorBranch &&
+        !n.errorHandling.retries);
+    if (!wf.errorPolicy.workflowLevelHandler) {
+        findings.push({
+            checkId: 'error-handling',
+            severity: 'medium',
+            nodeId: null,
+            nodeLabel: null,
+            title: 'No workflow-level error handler is set',
+            ifItGoesQuiet: 'A step that throws stops the run. Somebody has to be watching the execution list to find out.',
+            detail: wf.platform === 'n8n'
+                ? 'This is a different miss from "a node has no error branch", and easier to overlook, because the canvas looks fine. It lives in workflow Settings -> Error Workflow.'
+                : 'No error route on the scenario. Make will retry per its own settings and then stop.',
+        });
+    }
+    if (wf.errorPolicy.storesFailedRuns === false) {
+        findings.push({
+            checkId: 'error-handling',
+            severity: 'high',
+            nodeId: null,
+            nodeLabel: null,
+            title: 'Incomplete executions are switched off',
+            ifItGoesQuiet: 'A run that fails part-way is not stored, so there is nothing to resume and nothing to inspect afterwards. The data that run was carrying is gone.',
+            detail: 'Make stores failed runs only when this is on, and it is off by default. Scenario settings -> Allow storing of Incomplete Executions.',
+        });
+    }
+    if (unhandled.length > 0) {
+        const names = unhandled.slice(0, 4).map((n) => `"${n.label}"`).join(', ');
+        findings.push({
+            checkId: 'error-handling',
+            severity: 'low',
+            nodeId: unhandled[0].id,
+            nodeLabel: unhandled[0].label,
+            title: `${unhandled.length} step${unhandled.length === 1 ? '' : 's'} with no retry and no error branch`,
+            ifItGoesQuiet: 'These throw on a bad day and the run stops where it stands, part-done.',
+            detail: `${names}${unhandled.length > 4 ? `, and ${unhandled.length - 4} more` : ''}. This is the check every free auditor already does — it is here for completeness, not because it is the interesting part.`,
+        });
+    }
+    return findings;
+}

package/dist/core/checks/protections.d.ts

@@ -0,0 +1,11 @@
+/**
+ * What is holding this workflow together.
+ *
+ * Most pastes produce nothing critical. A blank result panel teaches the reader
+ * that the tool found nothing useful, which is both untrue and the fastest way
+ * to lose them. So we say what protects it, from the same analysis — never
+ * invented, never padded. If none of these are true, we show nothing rather
+ * than reach for filler.
+ */
+import type { Protection, Workflow } from '../model.js';
+export declare function checkProtections(wf: Workflow): Protection[];

package/dist/core/checks/protections.js

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * What is holding this workflow together.
+ *
+ * Most pastes produce nothing critical. A blank result panel teaches the reader
+ * that the tool found nothing useful, which is both untrue and the fastest way
+ * to lose them. So we say what protects it, from the same analysis — never
+ * invented, never padded. If none of these are true, we show nothing rather
+ * than reach for filler.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkProtections = checkProtections;
+const zero_write_js_1 = require("./zero-write.js");
+function checkProtections(wf) {
+    const out = [];
+    const byId = new Map(wf.nodes.map((n) => [n.id, n]));
+    if (wf.cadence.expectedIntervalKnown) {
+        out.push({
+            kind: 'known-cadence',
+            nodeId: null,
+            nodeLabel: null,
+            title: `Runs ${wf.cadence.description}`,
+            detail: 'There is a stated rhythm here, so a missed run is measurable. Most of the workflows we see have no declared cadence at all, which is why nobody can tell idle from dead.',
+        });
+    }
+    if (wf.errorPolicy.workflowLevelHandler) {
+        out.push({
+            kind: 'error-handler',
+            nodeId: null,
+            nodeLabel: null,
+            title: 'A workflow-level error handler is set',
+            detail: wf.platform === 'n8n'
+                ? 'Anything that throws reaches your error workflow rather than sitting in the execution list waiting to be noticed.'
+                : 'The scenario has an error route, so a failure goes somewhere instead of just stopping.',
+        });
+    }
+    if (wf.errorPolicy.storesFailedRuns === true) {
+        out.push({
+            kind: 'stores-failed-runs',
+            nodeId: null,
+            nodeLabel: null,
+            title: 'Incomplete executions are switched on',
+            detail: 'Make keeps failed runs so you can look at them and resume them. This is off by default, so somebody turned it on deliberately.',
+        });
+    }
+    const alertIds = (0, zero_write_js_1.findAlertNodes)(wf);
+    const dom = (0, zero_write_js_1.computeDominators)(wf);
+    const writes = wf.nodes.filter((n) => n.role === 'write' && !n.disabled && !alertIds.has(n.id));
+    for (const w of writes) {
+        const dominators = dom.get(w.id) ?? new Set();
+        const gates = [...dominators]
+            .filter((d) => d !== w.id)
+            .map((d) => byId.get(d))
+            .filter((n) => !!n && !!n.zeroEmit);
+        if (gates.length === 0)
+            continue;
+        if (!gates.every((g) => (0, zero_write_js_1.isGuarded)(wf, g.id)))
+            continue;
+        out.push({
+            kind: 'guarded-write',
+            nodeId: w.id,
+            nodeLabel: w.label,
+            title: `"${w.label}" is covered if it gets nothing`,
+            detail: `Every step that could starve it — ${gates
+                .slice(0, 2)
+                .map((g) => `"${g.label}"`)
+                .join(', ')} — has somewhere else to send the empty case. The quiet run does not vanish.`,
+        });
+    }
+    if (alertIds.size > 0) {
+        const names = [...alertIds]
+            .map((id) => byId.get(id)?.label)
+            .filter(Boolean)
+            .slice(0, 2);
+        if (names.length) {
+            out.push({
+                kind: 'alert-branch',
+                nodeId: null,
+                nodeLabel: null,
+                title: `Somebody gets told: ${names.map((n) => `"${n}"`).join(', ')}`,
+                detail: 'There is a message on a branch that only runs when something goes the wrong way. That is the difference between a quiet failure and a known one.',
+            });
+        }
+    }
+    const retried = wf.nodes.filter((n) => n.errorHandling.retries && !n.disabled);
+    if (retried.length > 0) {
+        out.push({
+            kind: 'retries',
+            nodeId: retried[0].id,
+            nodeLabel: retried[0].label,
+            title: `${retried.length} step${retried.length === 1 ? '' : 's'} retry before giving up`,
+            detail: 'A blip on someone else\'s API does not end the run.',
+        });
+    }
+    return out;
+}

package/dist/core/checks/zero-write.d.ts

@@ -0,0 +1,27 @@
+/**
+ * CHECK 4 — write steps that can complete having written zero rows.
+ *
+ * The question this answers is NOT "did this workflow write nothing" — static
+ * JSON can never answer that. It answers "can this workflow finish green having
+ * written nothing, and would anyone notice". That is a blind-spot report, not a
+ * bug report, and the wording throughout keeps that distinction.
+ *
+ * Method: for every write node W, find the nodes that DOMINATE it — the steps
+ * that every path from a trigger to W must pass through. If any dominator can
+ * emit zero items, W is skipped entirely and the run still reports success.
+ *
+ * Dominators rather than path enumeration, because a 246-node workflow with 40
+ * branches has too many paths to walk, and because a gate only truly starves W
+ * if there is no alternative path around it. Dominance is exactly that property.
+ */
+import type { Finding, Workflow } from '../model.js';
+/** Iterative dominator computation from a virtual entry over all triggers. */
+export declare function computeDominators(wf: Workflow): Map<string, Set<string>>;
+/**
+ * Is the empty case caught? A gate is "guarded" when something else leaves it —
+ * an else branch, an error route, an alert. Then somebody at least hears about
+ * the empty run. Unguarded means the silence is total.
+ */
+export declare function isGuarded(wf: Workflow, gateId: string): boolean;
+export declare function findAlertNodes(wf: Workflow): Set<string>;
+export declare function checkZeroWrite(wf: Workflow): Finding[];

package/dist/core/checks/zero-write.js

@@ -0,0 +1,245 @@
+"use strict";
+/**
+ * CHECK 4 — write steps that can complete having written zero rows.
+ *
+ * The question this answers is NOT "did this workflow write nothing" — static
+ * JSON can never answer that. It answers "can this workflow finish green having
+ * written nothing, and would anyone notice". That is a blind-spot report, not a
+ * bug report, and the wording throughout keeps that distinction.
+ *
+ * Method: for every write node W, find the nodes that DOMINATE it — the steps
+ * that every path from a trigger to W must pass through. If any dominator can
+ * emit zero items, W is skipped entirely and the run still reports success.
+ *
+ * Dominators rather than path enumeration, because a 246-node workflow with 40
+ * branches has too many paths to walk, and because a gate only truly starves W
+ * if there is no alternative path around it. Dominance is exactly that property.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeDominators = computeDominators;
+exports.isGuarded = isGuarded;
+exports.findAlertNodes = findAlertNodes;
+exports.checkZeroWrite = checkZeroWrite;
+const model_js_1 = require("../model.js");
+/** Iterative dominator computation from a virtual entry over all triggers. */
+function computeDominators(wf) {
+    const ENTRY = '\u0000entry';
+    const ids = wf.nodes.filter((n) => !n.disabled).map((n) => n.id);
+    const idSet = new Set(ids);
+    const preds = new Map();
+    for (const id of ids)
+        preds.set(id, []);
+    preds.set(ENTRY, []);
+    for (const e of wf.edges) {
+        // Error branches are not the normal path; a node reached only via an error
+        // branch should not be treated as part of the happy path.
+        if (e.channel === 'error')
+            continue;
+        if (!idSet.has(e.from) || !idSet.has(e.to))
+            continue;
+        preds.get(e.to).push(e.from);
+    }
+    for (const t of wf.triggerIds) {
+        if (idSet.has(t))
+            preds.get(t).push(ENTRY);
+    }
+    // Nodes with no predecessor at all hang off the entry, otherwise they are
+    // unreachable and dominance is undefined for them.
+    for (const id of ids) {
+        if (preds.get(id).length === 0)
+            preds.get(id).push(ENTRY);
+    }
+    const all = new Set([ENTRY, ...ids]);
+    const dom = new Map();
+    dom.set(ENTRY, new Set([ENTRY]));
+    for (const id of ids)
+        dom.set(id, new Set(all));
+    let changed = true;
+    let guard = 0;
+    while (changed && guard++ < 200) {
+        changed = false;
+        for (const id of ids) {
+            const ps = preds.get(id);
+            let next = null;
+            for (const p of ps) {
+                const dp = dom.get(p);
+                if (!dp)
+                    continue;
+                if (next === null) {
+                    next = new Set(dp);
+                }
+                else {
+                    for (const x of [...next])
+                        if (!dp.has(x))
+                            next.delete(x);
+                }
+            }
+            if (next === null)
+                next = new Set();
+            next.add(id);
+            const cur = dom.get(id);
+            if (next.size !== cur.size || [...next].some((x) => !cur.has(x))) {
+                dom.set(id, next);
+                changed = true;
+            }
+        }
+    }
+    return dom;
+}
+/**
+ * Is the empty case caught? A gate is "guarded" when something else leaves it —
+ * an else branch, an error route, an alert. Then somebody at least hears about
+ * the empty run. Unguarded means the silence is total.
+ */
+function isGuarded(wf, gateId) {
+    const out = wf.edges.filter((e) => e.from === gateId);
+    const channels = new Set(out.map((e) => e.channel));
+    // More than one live output channel means the empty/false case goes somewhere.
+    if (channels.size > 1)
+        return true;
+    if (channels.has('error'))
+        return true;
+    // A downstream alert node directly off this gate also counts.
+    return out.some((e) => {
+        const n = wf.nodes.find((x) => x.id === e.to);
+        return n?.role === 'alert' || n?.role === 'error-handler';
+    });
+}
+/**
+ * A message sent on a false/else/error branch is an alert, not a data write.
+ * Distinguishing these is what stops the check flagging every Slack node in
+ * every workflow — and it tells us whether the empty case reaches a human.
+ */
+const ALERT_CHANNELS = new Set(['false', 'else', 'error']);
+const ALERT_TARGETS = /slack|telegram|discord|gmail|email|twilio|whatsapp|pushover/i;
+function findAlertNodes(wf) {
+    const alerts = new Set();
+    for (const e of wf.edges) {
+        if (!ALERT_CHANNELS.has(e.channel))
+            continue;
+        const n = wf.nodes.find((x) => x.id === e.to);
+        if (!n)
+            continue;
+        if (n.writeKind === 'send' && ALERT_TARGETS.test(n.platformType + ' ' + (n.writeTarget ?? ''))) {
+            alerts.add(n.id);
+        }
+    }
+    for (const n of wf.nodes) {
+        if (n.role === 'error-handler')
+            alerts.add(n.id);
+    }
+    return alerts;
+}
+function checkZeroWrite(wf) {
+    const findings = [];
+    const byId = new Map(wf.nodes.map((n) => [n.id, n]));
+    const alertIds = findAlertNodes(wf);
+    // Alerts are not data writes. A skipped alert is a real problem but a
+    // different one, and lumping them together is what makes these tools noisy.
+    const writes = wf.nodes.filter((n) => n.role === 'write' && !n.disabled && !alertIds.has(n.id));
+    if (writes.length === 0)
+        return findings;
+    /**
+     * Could anything in this workflow notice an empty run? Either somebody gets
+     * told, or there is a known rhythm to measure against. If neither, silence is
+     * total — and that is the only case worth shouting about.
+     */
+    const hasSafetyNet = alertIds.size > 0 ||
+        wf.cadence.expectedIntervalKnown ||
+        wf.errorPolicy.workflowLevelHandler;
+    const dom = computeDominators(wf);
+    const soleWrite = writes.length === 1;
+    for (const w of writes) {
+        const dominators = dom.get(w.id) ?? new Set();
+        const starvers = [];
+        for (const dId of dominators) {
+            if (dId === w.id)
+                continue;
+            const d = byId.get(dId);
+            if (!d || !d.zeroEmit)
+                continue;
+            starvers.push({ node: d, guarded: isGuarded(wf, dId) });
+        }
+        // A gate sitting on an edge (Make puts filters on links, not in modules).
+        const gateEdges = wf.edges.filter((e) => e.gate && dominators.has(e.from) && dominators.has(e.to));
+        if (starvers.length === 0 && gateEdges.length === 0) {
+            // Nothing upstream can starve it. Still worth one quiet note if the write
+            // is set to swallow its own failures.
+            if (w.errorHandling.continueOnFail) {
+                findings.push({
+                    checkId: 'zero-write',
+                    severity: 'medium',
+                    nodeId: w.id,
+                    nodeLabel: w.label,
+                    title: `"${w.label}" is set to carry on when it fails`,
+                    ifItGoesQuiet: `The write fails, the run continues to the end, and the execution is recorded as a success. Nothing writes and nothing is flagged.`,
+                    detail: 'Continue-on-fail is the right setting when a later step handles the failure. Nothing downstream of this node looks like it does.',
+                });
+            }
+            continue;
+        }
+        const unguarded = starvers.filter((s) => !s.guarded);
+        const structural = unguarded.filter((s) => s.node.zeroEmit.certainty === 'structural');
+        const worst = structural[0] ?? unguarded[0] ?? starvers[0];
+        if (!worst)
+            continue;
+        let severity;
+        if (structural.length > 0 && !hasSafetyNet) {
+            // Nothing here could tell you it happened.
+            severity = soleWrite ? 'critical' : 'high';
+        }
+        else if (structural.length > 0) {
+            // Real, but something in the workflow would surface it.
+            severity = soleWrite ? 'medium' : 'low';
+        }
+        else if (unguarded.length > 0) {
+            severity = hasSafetyNet ? 'low' : 'medium';
+        }
+        else {
+            severity = 'low';
+        }
+        const chainNames = [...new Set([...structural, ...unguarded, ...starvers]
+                .slice(0, 3)
+                .map((s) => `"${s.node.label}"`))].join(' -> ');
+        const target = w.writeTarget ? ` to ${w.writeTarget}` : '';
+        findings.push({
+            checkId: 'zero-write',
+            severity,
+            nodeId: w.id,
+            nodeLabel: w.label,
+            title: `"${w.label}" can be skipped entirely and the run still finishes green`,
+            ifItGoesQuiet: `${worst.node.zeroEmit.cause} Every path to "${w.label}" goes through it, so nothing is written${target}, ` +
+                `every step shows as successful, and the execution list looks exactly like a normal day.` +
+                (soleWrite ? ' This is the only write in the workflow, so the run does nothing at all.' : ''),
+            detail: `Chain: ${chainNames} -> "${w.label}". ` +
+                (worst.guarded
+                    ? 'There is another branch off that step, so the empty case does reach something.'
+                    : 'Nothing else leaves that step, so the empty case reaches nobody.') +
+                (worst.node.errorHandling.alwaysOutputData
+                    ? ' Note: that step has "always output data" switched on, so it pushes an empty item through rather than stopping — the write may run and write a blank row instead of nothing at all.'
+                    : ''),
+            howToCheck: (hasSafetyNet
+                ? 'Something in this workflow would surface an empty run, so this is worth knowing rather than worth panicking about. '
+                : 'Nothing in this workflow would surface an empty run: no alert branch, no expected rhythm, no error handler. ') +
+                'Static analysis can only tell you this is possible. Whether it is happening needs run history: compare items written per run against the same run a week ago.',
+        });
+    }
+    // A 246-node workflow can generate forty of these. Three is a report; forty
+    // is wallpaper that gets closed.
+    findings.sort((a, b) => model_js_1.SEVERITY_ORDER[a.severity] - model_js_1.SEVERITY_ORDER[b.severity]);
+    if (findings.length > 3) {
+        const rest = findings.length - 3;
+        const top = findings.slice(0, 3);
+        top.push({
+            checkId: 'zero-write',
+            severity: 'info',
+            nodeId: null,
+            nodeLabel: null,
+            title: `${rest} more write step${rest === 1 ? '' : 's'} with the same pattern`,
+            ifItGoesQuiet: 'Same story as above, further down the workflow.',
+            detail: 'Showing the three that matter most. The rest follow the same shape.',
+        });
+        return top;
+    }
+    return findings;
+}