flowlint 0.3.1 → 0.3.3

package/dist/packages/review/schemas/n8n-workflow.schema.json

@@ -0,0 +1,177 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "$id": "https://flowlint.dev/schemas/n8n-workflow.json",
+    "title": "n8n Workflow Schema",
+    "description": "JSON Schema for n8n workflow files (v1.x)",
+    "type": "object",
+    "required": ["nodes", "connections"],
+    "properties": {
+        "name": {
+            "type": "string",
+            "description": "Workflow name"
+        },
+        "nodes": {
+            "type": "array",
+            "description": "Array of workflow nodes",
+            "items": {
+                "type": "object",
+                "required": ["type", "name"],
+                "properties": {
+                    "id": {
+                        "type": "string",
+                        "minLength": 1,
+                        "description": "Unique node identifier"
+                    },
+                    "type": {
+                        "type": "string",
+                        "minLength": 1,
+                        "description": "Node type (e.g., n8n-nodes-base.httpRequest)"
+                    },
+                    "name": {
+                        "type": "string",
+                        "minLength": 1,
+                        "description": "Human-readable node name"
+                    },
+                    "parameters": {
+                        "type": "object",
+                        "description": "Node-specific configuration parameters"
+                    },
+                    "credentials": {
+                        "type": "object",
+                        "description": "Credential references for this node"
+                    },
+                    "position": {
+                        "type": "array",
+                        "description": "X,Y coordinates for UI placement",
+                        "items": {
+                            "type": "number"
+                        },
+                        "minItems": 2,
+                        "maxItems": 2
+                    },
+                    "continueOnFail": {
+                        "type": "boolean",
+                        "description": "Whether to continue execution on node failure"
+                    },
+                    "disabled": {
+                        "type": "boolean",
+                        "description": "Whether the node is disabled"
+                    },
+                    "notesInFlow": {
+                        "type": "boolean"
+                    },
+                    "notes": {
+                        "type": "string"
+                    },
+                    "typeVersion": {
+                        "type": "number",
+                        "description": "Version of the node type"
+                    }
+                },
+                "additionalProperties": true
+            }
+        },
+        "connections": {
+            "type": "object",
+            "description": "Map of node connections (source node ID -> connection details)",
+            "patternProperties": {
+                "^.*$": {
+                    "type": "object",
+                    "description": "Connection channels for a source node",
+                    "patternProperties": {
+                        "^(main|error|timeout|.*?)$": {
+                            "description": "Connection array for this channel",
+                            "oneOf": [
+                                {
+                                    "type": "array",
+                                    "items": {
+                                        "type": "object",
+                                        "required": ["node"],
+                                        "properties": {
+                                            "node": {
+                                                "type": "string",
+                                                "description": "Target node ID or name"
+                                            },
+                                            "type": {
+                                                "type": "string",
+                                                "description": "Connection type"
+                                            },
+                                            "index": {
+                                                "type": "number",
+                                                "description": "Output index"
+                                            }
+                                        }
+                                    }
+                                },
+                                {
+                                    "type": "array",
+                                    "items": {
+                                        "type": "array",
+                                        "items": {
+                                            "type": "object",
+                                            "required": ["node"],
+                                            "properties": {
+                                                "node": {
+                                                    "type": "string"
+                                                },
+                                                "type": {
+                                                    "type": "string"
+                                                },
+                                                "index": {
+                                                    "type": "number"
+                                                }
+                                            }
+                                        }
+                                    }
+                                }
+                            ]
+                        }
+                    }
+                }
+            }
+        },
+        "active": {
+            "type": "boolean",
+            "description": "Whether the workflow is active"
+        },
+        "settings": {
+            "type": "object",
+            "description": "Workflow settings"
+        },
+        "tags": {
+            "type": "array",
+            "description": "Workflow tags",
+            "items": {
+                "oneOf": [
+                    { "type": "string" },
+                    {
+                        "type": "object",
+                        "required": ["name"],
+                        "properties": {
+                            "id": { "type": "string" },
+                            "name": { "type": "string" }
+                        },
+                        "additionalProperties": true
+                    }
+                ]
+            }
+        },
+        "pinData": {
+            "type": "object",
+            "description": "Pinned execution data for testing"
+        },
+        "versionId": {
+            "type": "string",
+            "description": "Workflow version identifier"
+        },
+        "id": {
+            "type": ["string", "number"],
+            "description": "Workflow ID"
+        },
+        "meta": {
+            "type": "object",
+            "description": "Metadata"
+        }
+    },
+    "additionalProperties": true
+}

package/dist/packages/review/sniffer.d.ts

@@ -0,0 +1,15 @@
+import type { Octokit } from 'octokit';
+import type { PRFile } from './types';
+export type GlobSet = {
+    include: string[];
+    ignore: string[];
+};
+export declare function pickTargets(files: PRFile[], globs: GlobSet): PRFile[];
+export type FetchResult = {
+    contents: Map<string, string>;
+    errors: Array<{
+        filename: string;
+        error: string;
+    }>;
+};
+export declare function fetchRawFiles(gh: Octokit, repoFull: string, targets: PRFile[]): Promise<FetchResult>;

package/dist/packages/review/sniffer.js

@@ -0,0 +1,47 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pickTargets = pickTargets;
+exports.fetchRawFiles = fetchRawFiles;
+const logger_1 = require("../logger");
+const micromatch_1 = __importDefault(require("micromatch"));
+function pickTargets(files, globs) {
+    return files
+        .filter((file) => file.status !== 'removed')
+        .filter((file) => {
+        const normalized = file.filename.replace(/\\/g, '/');
+        const included = micromatch_1.default.isMatch(normalized, globs.include, { dot: true });
+        const ignored = micromatch_1.default.isMatch(normalized, globs.ignore, { dot: true });
+        return included && !ignored;
+    });
+}
+async function fetchRawFiles(gh, repoFull, targets) {
+    const [owner, repo] = repoFull.split('/');
+    const contents = new Map();
+    const errors = [];
+    for (const file of targets) {
+        if (!file.sha) {
+            errors.push({ filename: file.filename, error: 'Missing SHA (file may be removed)' });
+            continue;
+        }
+        try {
+            const { data: blob } = await gh.request('GET /repos/{owner}/{repo}/git/blobs/{file_sha}', {
+                owner,
+                repo,
+                file_sha: file.sha,
+            });
+            const raw = Buffer.from(blob.content, 'base64').toString('utf8');
+            contents.set(file.filename, raw);
+        }
+        catch (error) {
+            // Handle transient errors (404, timeouts, rate limits) gracefully
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            logger_1.logger.warn({ filename: file.filename, error: errorMsg }, 'failed to fetch file');
+            errors.push({ filename: file.filename, error: errorMsg });
+        }
+    }
+    return { contents, errors };
+}
+//# sourceMappingURL=sniffer.js.map

package/dist/packages/review/sniffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sniffer.js","sourceRoot":"","sources":["../../../packages/review/sniffer.ts"],"names":[],"mappings":";;;;;AAOA,kCASC;AAOD,sCAgCC;AArDD,sCAAmC;AACnC,4DAAoC;AAIpC,SAAgB,WAAW,CAAC,KAAe,EAAE,KAAc;IACzD,OAAO,KAAK;SACT,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC;SAC3C,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE;QACf,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QACrD,MAAM,QAAQ,GAAG,oBAAU,CAAC,OAAO,CAAC,UAAU,EAAE,KAAK,CAAC,OAAO,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;QAC9E,MAAM,OAAO,GAAG,oBAAU,CAAC,OAAO,CAAC,UAAU,EAAE,KAAK,CAAC,MAAM,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5E,OAAO,QAAQ,IAAI,CAAC,OAAO,CAAC;IAC9B,CAAC,CAAC,CAAC;AACP,CAAC;AAOM,KAAK,UAAU,aAAa,CACjC,EAAW,EACX,QAAgB,EAChB,OAAiB;IAEjB,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC1C,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC3C,MAAM,MAAM,GAA+C,EAAE,CAAC;IAE9D,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;QAC3B,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;YACd,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,mCAAmC,EAAE,CAAC,CAAC;YACrF,SAAS;QACX,CAAC;QAED,IAAI,CAAC;YACH,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,gDAAgD,EAAE;gBACxF,KAAK;gBACL,IAAI;gBACJ,QAAQ,EAAE,IAAI,CAAC,GAAG;aACnB,CAAC,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YACjE,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;QACnC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,kEAAkE;YAClE,MAAM,QAAQ,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACxE,eAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,sBAAsB,CAAC,CAAC;YAClF,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;AAC9B,CAAC"}

package/dist/packages/review/types.d.ts

@@ -0,0 +1,38 @@
+export type PRFile = {
+    filename: string;
+    status: string;
+    sha?: string;
+    patch?: string;
+};
+export type FindingSeverity = 'must' | 'should' | 'nit';
+export type Finding = {
+    rule: string;
+    severity: FindingSeverity;
+    path: string;
+    message: string;
+    raw_details?: string;
+    nodeId?: string;
+    line?: number;
+    documentationUrl?: string;
+};
+export type NodeRef = {
+    id: string;
+    type: string;
+    name?: string;
+    params?: Record<string, unknown>;
+    cred?: Record<string, unknown>;
+    flags?: {
+        continueOnFail?: boolean;
+        retryOnFail?: boolean | string;
+    };
+};
+export type Edge = {
+    from: string;
+    to: string;
+    on?: 'success' | 'error' | 'timeout';
+};
+export type Graph = {
+    nodes: NodeRef[];
+    edges: Edge[];
+    meta: Record<string, unknown>;
+};

package/dist/packages/review/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/packages/review/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../packages/review/types.ts"],"names":[],"mappings":""}

package/dist/packages/review/utils/findings.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Findings utilities
+ * Shared logic for processing and analyzing findings across both review engine and CLI
+ */
+import type { Finding } from '../types';
+export interface FindingsSummary {
+    must: number;
+    should: number;
+    nit: number;
+    total: number;
+}
+/**
+ * Count findings by severity level
+ */
+export declare function countFindingsBySeverity(findings: Finding[]): FindingsSummary;
+/**
+ * Get severity order for sorting
+ */
+export declare function getSeverityOrder(): Record<string, number>;
+/**
+ * Sort findings by severity
+ */
+export declare function sortFindingsBySeverity(findings: Finding[]): Finding[];

package/dist/packages/review/utils/findings.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * Findings utilities
+ * Shared logic for processing and analyzing findings across both review engine and CLI
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.countFindingsBySeverity = countFindingsBySeverity;
+exports.getSeverityOrder = getSeverityOrder;
+exports.sortFindingsBySeverity = sortFindingsBySeverity;
+/**
+ * Count findings by severity level
+ */
+function countFindingsBySeverity(findings) {
+    return {
+        must: findings.filter((f) => f.severity === 'must').length,
+        should: findings.filter((f) => f.severity === 'should').length,
+        nit: findings.filter((f) => f.severity === 'nit').length,
+        total: findings.length,
+    };
+}
+/**
+ * Get severity order for sorting
+ */
+function getSeverityOrder() {
+    return { must: 0, should: 1, nit: 2 };
+}
+/**
+ * Sort findings by severity
+ */
+function sortFindingsBySeverity(findings) {
+    const order = getSeverityOrder();
+    return [...findings].sort((a, b) => order[a.severity] - order[b.severity]);
+}
+//# sourceMappingURL=findings.js.map

package/dist/packages/review/utils/findings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"findings.js","sourceRoot":"","sources":["../../../../packages/review/utils/findings.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AAcH,0DAOC;AAKD,4CAEC;AAKD,wDAGC;AAzBD;;GAEG;AACH,SAAgB,uBAAuB,CAAC,QAAmB;IACzD,OAAO;QACL,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,MAAM,CAAC,CAAC,MAAM;QAC1D,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,MAAM;QAC9D,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,KAAK,CAAC,CAAC,MAAM;QACxD,KAAK,EAAE,QAAQ,CAAC,MAAM;KACvB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAgB,gBAAgB;IAC9B,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC;AACxC,CAAC;AAED;;GAEG;AACH,SAAgB,sBAAsB,CAAC,QAAmB;IACxD,MAAM,KAAK,GAAG,gBAAgB,EAAE,CAAC;IACjC,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;AAC7E,CAAC"}

package/dist/packages/review/utils/merge.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Deep merge utilities
+ * Shared logic for merging configuration objects
+ */
+/**
+ * Deep merge configuration objects
+ */
+export declare function deepMerge<T>(base: T, override: Record<string, unknown>): T;
+/**
+ * Recursively merge source object into target object
+ */
+export declare function mergeInto(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown>;

package/dist/packages/review/utils/merge.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * Deep merge utilities
+ * Shared logic for merging configuration objects
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deepMerge = deepMerge;
+exports.mergeInto = mergeInto;
+/**
+ * Deep merge configuration objects
+ */
+function deepMerge(base, override) {
+    const baseCopy = JSON.parse(JSON.stringify(base));
+    if (!override)
+        return baseCopy;
+    return mergeInto(baseCopy, override);
+}
+/**
+ * Recursively merge source object into target object
+ */
+function mergeInto(target, source) {
+    for (const [key, value] of Object.entries(source)) {
+        if (value === undefined || value === null)
+            continue;
+        if (Array.isArray(value)) {
+            target[key] = value;
+        }
+        else if (typeof value === 'object') {
+            if (typeof target[key] !== 'object' || target[key] === null) {
+                target[key] = {};
+            }
+            mergeInto(target[key], value);
+        }
+        else {
+            target[key] = value;
+        }
+    }
+    return target;
+}
+//# sourceMappingURL=merge.js.map

package/dist/packages/review/utils/merge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge.js","sourceRoot":"","sources":["../../../../packages/review/utils/merge.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AAKH,8BAIC;AAKD,8BAeC;AA3BD;;GAEG;AACH,SAAgB,SAAS,CAAI,IAAO,EAAE,QAAiC;IACrE,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;IAClD,IAAI,CAAC,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC/B,OAAO,SAAS,CAAC,QAAe,EAAE,QAAQ,CAAM,CAAC;AACnD,CAAC;AAED;;GAEG;AACH,SAAgB,SAAS,CAAC,MAA+B,EAAE,MAA+B;IACxF,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;YAAE,SAAS;QACpD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACtB,CAAC;aAAM,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YACrC,IAAI,OAAO,MAAM,CAAC,GAAG,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;gBAC5D,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC;YACnB,CAAC;YACD,SAAS,CAAC,MAAM,CAAC,GAAG,CAA4B,EAAE,KAAgC,CAAC,CAAC;QACtF,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACtB,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/packages/review/utils.d.ts

@@ -0,0 +1,60 @@
+import type { Graph, NodeRef } from './types';
+/**
+ * Shared utility functions for workflow parsing and validation
+ */
+/**
+ * Helper to flatten nested connection arrays from n8n workflow connections.
+ * Connections can be nested in various ways (arrays of arrays, objects with node properties).
+ * This recursively flattens them to a simple array of connection objects.
+ *
+ * @param value - The connection value to flatten (can be array, object, or primitive)
+ * @returns Array of connection objects with 'node' property
+ */
+export declare function flattenConnections(value: any): any[];
+/**
+ * Build validation error objects from a collection of items using provided templates.
+ * This utility eliminates code duplication in validation error construction.
+ *
+ * @template T - Type of items to process
+ * @param items - Set or array of items to convert to validation errors
+ * @param errorConfig - Configuration object containing:
+ *   - path: The JSON path where the error occurred
+ *   - messageTemplate: Function to generate error message for each item
+ *   - suggestionTemplate: Function to generate actionable suggestion for each item
+ * @returns Array of validation error objects with path, message, and suggestion fields
+ *
+ * @example
+ * ```typescript
+ * const duplicates = new Set(['node1', 'node2']);
+ * const errors = buildValidationErrors(duplicates, {
+ *   path: 'nodes[].id',
+ *   messageTemplate: (id) => `Duplicate node ID: "${id}"`,
+ *   suggestionTemplate: (id) => `Remove or rename the duplicate node with ID "${id}".`
+ * });
+ * ```
+ */
+export declare function buildValidationErrors<T>(items: Set<T> | T[], errorConfig: {
+    path: string;
+    messageTemplate: (item: T) => string;
+    suggestionTemplate: (item: T) => string;
+}): Array<{
+    path: string;
+    message: string;
+    suggestion: string;
+}>;
+export declare function collectStrings(value: unknown, out?: string[]): string[];
+export declare function toRegex(pattern: string): RegExp;
+export declare function isApiNode(type: string): boolean;
+export declare function isMutationNode(type: string): boolean;
+export declare function isErrorProneNode(type: string): boolean;
+export declare function isNotificationNode(type: string): boolean;
+export declare function isErrorHandlerNode(type: string, name?: string): boolean;
+export declare function isRejoinNode(graph: Graph, nodeId: string): boolean;
+export declare function isMeaningfulConsumer(node: NodeRef): boolean;
+export declare function containsCandidate(value: unknown, candidates: string[]): boolean;
+export declare function isTerminalNode(type: string, name?: string): boolean;
+export declare function readNumber(source: any, paths: string[]): number | undefined;
+export declare function findAllDownstreamNodes(graph: Graph, startNodeId: string): Set<string>;
+export declare function findAllUpstreamNodes(graph: Graph, startNodeId: string): Set<string>;
+export declare const EXAMPLES_BASE_URL = "https://github.com/Replikanti/flowlint/tree/main/flowlint-examples";
+export declare function getExampleLink(ruleId: string): string;