@replikanti/flowlint-core 0.6.0

package/README.md

@@ -0,0 +1,74 @@
+# @flowlint/core
+
+Core linting engine for n8n workflows. This package provides the fundamental building blocks for analyzing and validating n8n workflow files.
+
+## Installation
+
+```bash
+npm install @flowlint/core
+```
+
+## Usage
+
+```typescript
+import { parseN8n, runAllRules, loadConfig, defaultConfig } from '@flowlint/core';
+
+// Parse a workflow from JSON string
+const workflow = parseN8n(workflowJsonString);
+
+// Run all linting rules
+const findings = runAllRules(workflow, {
+  path: 'my-workflow.n8n.json',
+  cfg: defaultConfig,
+});
+
+// Process findings
+findings.forEach(finding => {
+  console.log([${finding.severity.toUpperCase()}] ${finding.rule}: ${finding.message});
+});
+```
+
+## API
+
+### Parser
+
+- `parseN8n(doc: string): Graph` - Parse n8n workflow JSON/YAML into a graph structure
+
+### Linting
+
+- `runAllRules(graph: Graph, ctx: RuleContext): Finding[]` - Run all enabled rules
+
+### Configuration
+
+- `loadConfig(configPath?: string): FlowLintConfig` - Load configuration from file
+- `defaultConfig: FlowLintConfig` - Default configuration
+- `parseConfig(content: string): FlowLintConfig` - Parse config from YAML string
+
+### Validation
+
+- `validateN8nWorkflow(data: unknown): void` - Validate workflow structure
+
+## Rules
+
+This package includes 14 built-in rules:
+
+| Rule | Description | Severity |
+|------|-------------|----------|
+| R1 | Rate limit retry | must |
+| R2 | Error handling | must |
+| R3 | Idempotency | should |
+| R4 | Secrets exposure | must |
+| R5 | Dead ends | nit |
+| R6 | Long running | should |
+| R7 | Alert/log enforcement | should |
+| R8 | Unused data | nit |
+| R9 | Config literals | should |
+| R10 | Naming convention | nit |
+| R11 | Deprecated nodes | should |
+| R12 | Unhandled error path | must |
+| R13 | Webhook acknowledgment | must |
+| R14 | Retry-After compliance | should |
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,230 @@
+interface RateLimitRetryConfig {
+    enabled: boolean;
+    max_concurrency?: number;
+    default_retry?: {
+        count: number;
+        strategy: string;
+        base_ms: number;
+    };
+}
+interface ErrorHandlingConfig {
+    enabled: boolean;
+    forbid_continue_on_fail?: boolean;
+}
+interface IdempotencyConfig {
+    enabled: boolean;
+    key_field_candidates?: string[];
+}
+interface SecretsConfig {
+    enabled: boolean;
+    denylist_regex?: string[];
+}
+interface DeadEndsConfig {
+    enabled: boolean;
+}
+interface LongRunningConfig {
+    enabled: boolean;
+    max_iterations?: number;
+    timeout_ms?: number;
+}
+interface UnusedDataConfig {
+    enabled: boolean;
+}
+interface UnhandledErrorPathConfig {
+    enabled: boolean;
+}
+interface AlertLogEnforcementConfig {
+    enabled: boolean;
+}
+interface DeprecatedNodesConfig {
+    enabled: boolean;
+}
+interface NamingConventionConfig {
+    enabled: boolean;
+    generic_names?: string[];
+}
+interface ConfigLiteralsConfig {
+    enabled: boolean;
+    denylist_regex?: string[];
+}
+interface WebhookAcknowledgmentConfig {
+    enabled: boolean;
+    heavy_node_types?: string[];
+}
+interface RetryAfterComplianceConfig {
+    enabled: boolean;
+    suggest_exponential_backoff?: boolean;
+    suggest_jitter?: boolean;
+}
+interface RulesConfig {
+    rate_limit_retry: RateLimitRetryConfig;
+    error_handling: ErrorHandlingConfig;
+    idempotency: IdempotencyConfig;
+    secrets: SecretsConfig;
+    dead_ends: DeadEndsConfig;
+    long_running: LongRunningConfig;
+    unused_data: UnusedDataConfig;
+    unhandled_error_path: UnhandledErrorPathConfig;
+    alert_log_enforcement: AlertLogEnforcementConfig;
+    deprecated_nodes: DeprecatedNodesConfig;
+    naming_convention: NamingConventionConfig;
+    config_literals: ConfigLiteralsConfig;
+    webhook_acknowledgment: WebhookAcknowledgmentConfig;
+    retry_after_compliance: RetryAfterComplianceConfig;
+}
+interface FilesConfig {
+    include: string[];
+    ignore: string[];
+}
+interface ReportConfig {
+    annotations: boolean;
+    summary_limit: number;
+}
+interface FlowLintConfig {
+    files: FilesConfig;
+    report: ReportConfig;
+    rules: RulesConfig;
+}
+type RuleConfig = {
+    enabled: boolean;
+    [key: string]: unknown;
+};
+declare const defaultConfig: FlowLintConfig;
+
+/**
+ * Isomorphic config loader for FlowLint
+ * Works in both Node.js and browser environments
+ */
+
+/**
+ * Parse config from YAML string
+ */
+declare function parseConfig(content: string): FlowLintConfig;
+/**
+ * Load config - isomorphic function
+ * In browser: returns defaultConfig (no filesystem access)
+ * In Node.js: optionally loads from file path
+ */
+declare function loadConfig(configPath?: string): FlowLintConfig;
+/**
+ * Validate config structure
+ */
+declare function validateConfig(config: unknown): config is FlowLintConfig;
+
+/**
+ * Types module exports
+ */
+type PRFile = {
+    filename: string;
+    status: string;
+    sha?: string;
+    patch?: string;
+};
+type FindingSeverity = 'must' | 'should' | 'nit';
+type Finding = {
+    rule: string;
+    severity: FindingSeverity;
+    path: string;
+    message: string;
+    raw_details?: string;
+    nodeId?: string;
+    line?: number;
+    documentationUrl?: string;
+};
+type NodeRef = {
+    id: string;
+    type: string;
+    name?: string;
+    params?: Record<string, unknown>;
+    cred?: Record<string, unknown>;
+    flags?: {
+        continueOnFail?: boolean;
+        retryOnFail?: boolean | string;
+        waitBetweenTries?: number | string;
+        maxTries?: number | string;
+    };
+};
+type Edge = {
+    from: string;
+    to: string;
+    on?: 'success' | 'error' | 'timeout';
+};
+type Graph = {
+    nodes: NodeRef[];
+    edges: Edge[];
+    meta: Record<string, unknown>;
+};
+type RuleContext$1 = {
+    path: string;
+    cfg: FlowLintConfig;
+    nodeLines?: Record<string, number>;
+};
+type RuleRunner = (graph: Graph, ctx: RuleContext$1) => Finding[];
+
+declare function parseN8n(doc: string): Graph;
+
+type RuleContext = {
+    path: string;
+    cfg: FlowLintConfig;
+    nodeLines?: Record<string, number>;
+};
+declare function runAllRules(graph: Graph, ctx: RuleContext): Finding[];
+
+declare class ValidationError extends Error {
+    errors: Array<{
+        path: string;
+        message: string;
+        suggestion?: string;
+    }>;
+    constructor(errors: Array<{
+        path: string;
+        message: string;
+        suggestion?: string;
+    }>);
+}
+/**
+ * Validate n8n workflow structure
+ * Throws ValidationError with detailed messages if validation fails
+ */
+declare function validateN8nWorkflow(data: any): void;
+
+/**
+ * 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
+ */
+declare function flattenConnections(value: any): any[];
+declare function isApiNode(type: string): boolean;
+declare function isMutationNode(type: string): boolean;
+declare function isErrorProneNode(type: string): boolean;
+declare function isNotificationNode(type: string): boolean;
+declare function isTerminalNode(type: string, name?: string): boolean;
+declare function getExampleLink(ruleId: string): string;
+
+/**
+ * Findings utilities
+ * Shared logic for processing and analyzing findings across both review engine and CLI
+ */
+
+interface FindingsSummary {
+    must: number;
+    should: number;
+    nit: number;
+    total: number;
+}
+/**
+ * Count findings by severity level
+ */
+declare function countFindingsBySeverity(findings: Finding[]): FindingsSummary;
+/**
+ * Sort findings by severity
+ */
+declare function sortFindingsBySeverity(findings: Finding[]): Finding[];
+
+export { type Edge, type FilesConfig, type Finding, type FindingSeverity, type FlowLintConfig, type Graph, type NodeRef, type PRFile, type ReportConfig, type RuleConfig, type RuleContext$1 as RuleContext, type RuleRunner, ValidationError, countFindingsBySeverity, defaultConfig, flattenConnections, getExampleLink, isApiNode, isErrorProneNode, isMutationNode, isNotificationNode, isTerminalNode, loadConfig, parseConfig, parseN8n, runAllRules, sortFindingsBySeverity, validateConfig, validateN8nWorkflow };

package/dist/index.d.ts

@@ -0,0 +1,230 @@
+interface RateLimitRetryConfig {
+    enabled: boolean;
+    max_concurrency?: number;
+    default_retry?: {
+        count: number;
+        strategy: string;
+        base_ms: number;
+    };
+}
+interface ErrorHandlingConfig {
+    enabled: boolean;
+    forbid_continue_on_fail?: boolean;
+}
+interface IdempotencyConfig {
+    enabled: boolean;
+    key_field_candidates?: string[];
+}
+interface SecretsConfig {
+    enabled: boolean;
+    denylist_regex?: string[];
+}
+interface DeadEndsConfig {
+    enabled: boolean;
+}
+interface LongRunningConfig {
+    enabled: boolean;
+    max_iterations?: number;
+    timeout_ms?: number;
+}
+interface UnusedDataConfig {
+    enabled: boolean;
+}
+interface UnhandledErrorPathConfig {
+    enabled: boolean;
+}
+interface AlertLogEnforcementConfig {
+    enabled: boolean;
+}
+interface DeprecatedNodesConfig {
+    enabled: boolean;
+}
+interface NamingConventionConfig {
+    enabled: boolean;
+    generic_names?: string[];
+}
+interface ConfigLiteralsConfig {
+    enabled: boolean;
+    denylist_regex?: string[];
+}
+interface WebhookAcknowledgmentConfig {
+    enabled: boolean;
+    heavy_node_types?: string[];
+}
+interface RetryAfterComplianceConfig {
+    enabled: boolean;
+    suggest_exponential_backoff?: boolean;
+    suggest_jitter?: boolean;
+}
+interface RulesConfig {
+    rate_limit_retry: RateLimitRetryConfig;
+    error_handling: ErrorHandlingConfig;
+    idempotency: IdempotencyConfig;
+    secrets: SecretsConfig;
+    dead_ends: DeadEndsConfig;
+    long_running: LongRunningConfig;
+    unused_data: UnusedDataConfig;
+    unhandled_error_path: UnhandledErrorPathConfig;
+    alert_log_enforcement: AlertLogEnforcementConfig;
+    deprecated_nodes: DeprecatedNodesConfig;
+    naming_convention: NamingConventionConfig;
+    config_literals: ConfigLiteralsConfig;
+    webhook_acknowledgment: WebhookAcknowledgmentConfig;
+    retry_after_compliance: RetryAfterComplianceConfig;
+}
+interface FilesConfig {
+    include: string[];
+    ignore: string[];
+}
+interface ReportConfig {
+    annotations: boolean;
+    summary_limit: number;
+}
+interface FlowLintConfig {
+    files: FilesConfig;
+    report: ReportConfig;
+    rules: RulesConfig;
+}
+type RuleConfig = {
+    enabled: boolean;
+    [key: string]: unknown;
+};
+declare const defaultConfig: FlowLintConfig;
+
+/**
+ * Isomorphic config loader for FlowLint
+ * Works in both Node.js and browser environments
+ */
+
+/**
+ * Parse config from YAML string
+ */
+declare function parseConfig(content: string): FlowLintConfig;
+/**
+ * Load config - isomorphic function
+ * In browser: returns defaultConfig (no filesystem access)
+ * In Node.js: optionally loads from file path
+ */
+declare function loadConfig(configPath?: string): FlowLintConfig;
+/**
+ * Validate config structure
+ */
+declare function validateConfig(config: unknown): config is FlowLintConfig;
+
+/**
+ * Types module exports
+ */
+type PRFile = {
+    filename: string;
+    status: string;
+    sha?: string;
+    patch?: string;
+};
+type FindingSeverity = 'must' | 'should' | 'nit';
+type Finding = {
+    rule: string;
+    severity: FindingSeverity;
+    path: string;
+    message: string;
+    raw_details?: string;
+    nodeId?: string;
+    line?: number;
+    documentationUrl?: string;
+};
+type NodeRef = {
+    id: string;
+    type: string;
+    name?: string;
+    params?: Record<string, unknown>;
+    cred?: Record<string, unknown>;
+    flags?: {
+        continueOnFail?: boolean;
+        retryOnFail?: boolean | string;
+        waitBetweenTries?: number | string;
+        maxTries?: number | string;
+    };
+};
+type Edge = {
+    from: string;
+    to: string;
+    on?: 'success' | 'error' | 'timeout';
+};
+type Graph = {
+    nodes: NodeRef[];
+    edges: Edge[];
+    meta: Record<string, unknown>;
+};
+type RuleContext$1 = {
+    path: string;
+    cfg: FlowLintConfig;
+    nodeLines?: Record<string, number>;
+};
+type RuleRunner = (graph: Graph, ctx: RuleContext$1) => Finding[];
+
+declare function parseN8n(doc: string): Graph;
+
+type RuleContext = {
+    path: string;
+    cfg: FlowLintConfig;
+    nodeLines?: Record<string, number>;
+};
+declare function runAllRules(graph: Graph, ctx: RuleContext): Finding[];
+
+declare class ValidationError extends Error {
+    errors: Array<{
+        path: string;
+        message: string;
+        suggestion?: string;
+    }>;
+    constructor(errors: Array<{
+        path: string;
+        message: string;
+        suggestion?: string;
+    }>);
+}
+/**
+ * Validate n8n workflow structure
+ * Throws ValidationError with detailed messages if validation fails
+ */
+declare function validateN8nWorkflow(data: any): void;
+
+/**
+ * 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
+ */
+declare function flattenConnections(value: any): any[];
+declare function isApiNode(type: string): boolean;
+declare function isMutationNode(type: string): boolean;
+declare function isErrorProneNode(type: string): boolean;
+declare function isNotificationNode(type: string): boolean;
+declare function isTerminalNode(type: string, name?: string): boolean;
+declare function getExampleLink(ruleId: string): string;
+
+/**
+ * Findings utilities
+ * Shared logic for processing and analyzing findings across both review engine and CLI
+ */
+
+interface FindingsSummary {
+    must: number;
+    should: number;
+    nit: number;
+    total: number;
+}
+/**
+ * Count findings by severity level
+ */
+declare function countFindingsBySeverity(findings: Finding[]): FindingsSummary;
+/**
+ * Sort findings by severity
+ */
+declare function sortFindingsBySeverity(findings: Finding[]): Finding[];
+
+export { type Edge, type FilesConfig, type Finding, type FindingSeverity, type FlowLintConfig, type Graph, type NodeRef, type PRFile, type ReportConfig, type RuleConfig, type RuleContext$1 as RuleContext, type RuleRunner, ValidationError, countFindingsBySeverity, defaultConfig, flattenConnections, getExampleLink, isApiNode, isErrorProneNode, isMutationNode, isNotificationNode, isTerminalNode, loadConfig, parseConfig, parseN8n, runAllRules, sortFindingsBySeverity, validateConfig, validateN8nWorkflow };