flowlint 0.5.3 → 0.6.1

package/README.md

@@ -1,6 +1,6 @@
-# FlowLint CLI
+# FlowLint CLI
 
-Static analysis tool for n8n workflows - detect issues early, fix them faster.
+Command-line tool for static analysis of n8n workflows.
 
 ## Installation
 
@@ -8,391 +8,81 @@ Static analysis tool for n8n workflows - detect issues early, fix them faster.
 npm install -g flowlint
 ```
 
-Or use with npx (no installation required):
+Or use npx:
 
 ```bash
-npx flowlint scan ./workflows
+npx flowlint scan .
 ```
 
-## Quick Start
+## Usage
 
-Scan workflows in the current directory:
+### Scan workflows
 
 ```bash
-flowlint scan .
-```
-
-Scan a specific directory:
-
-```bash
-flowlint scan ./workflows
-```
-
-Scan with a custom config file:
-
-```bash
-flowlint scan . --config .flowlint.yml
-```
-
-## Output Formats
-
-FlowLint supports multiple output formats for different use cases:
-
-### Stylish (Default)
-
-Human-readable console output with colors and formatting:
-
-```bash
-flowlint scan .
-```
-
-### JSON
-
-Machine-readable JSON output:
-
-```bash
-flowlint scan . --format json
-flowlint scan . --format json --out-file report.json
-```
-
-### SARIF
-
-SARIF 2.1.0 format for GitHub Code Scanning and other security platforms:
-
-```bash
-flowlint scan . --format sarif --out-file results.sarif
-```
-
-### JUnit XML
-
-JUnit XML format for CI/CD platforms (Jenkins, GitLab CI, CircleCI, etc.):
-
-```bash
-flowlint scan . --format junit --out-file results.xml
-```
-
-### GitHub Actions
-
-GitHub Actions workflow commands for inline annotations in workflow logs:
-
-```bash
-flowlint scan . --format github-actions
-```
-
-## Command Reference
-
-### `scan`
-
-Scan workflow files for issues.
-
-```bash
-flowlint scan [path] [options]
-```
-
-**Arguments:**
-- `path` - Directory to scan (default: current directory)
-
-**Options:**
-- `--config <path>` - Path to `.flowlint.yml` config file
-- `--format <format>` - Output format: `stylish`, `json`, `sarif`, `junit`, `github-actions` (default: `stylish`)
-- `--out-file <path>` - Write results to file (format inferred from extension or `--format`)
-- `--fail-on-error` - Exit with code 1 if errors found
-
-**Examples:**
-
-```bash
-# Scan current directory with default config
+# Scan current directory
 flowlint scan
 
 # Scan specific directory
-flowlint scan ./my-workflows
-
-# Use custom config
-flowlint scan --config custom-config.yml
-
-# Output JSON to file
-flowlint scan --format json --out-file report.json
-
-# Generate SARIF for GitHub Code Scanning
-flowlint scan --format sarif --out-file results.sarif
+flowlint scan ./workflows
 
-# Generate JUnit XML for Jenkins
-flowlint scan --format junit --out-file test-results.xml
+# Output as JSON
+flowlint scan --format json
 
-# Fail CI build if errors found
+# Fail on errors (for CI)
 flowlint scan --fail-on-error
 ```
 
-## CI/CD Integration
-
-### GitHub Actions
-
-#### Option 1: SARIF Upload (Recommended)
-
-Upload results to GitHub Code Scanning for permanent PR annotations:
-
-```yaml
-name: FlowLint
-
-on:
-  pull_request:
-    paths:
-      - '**.json'
-
-jobs:
-  flowlint:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      security-events: write  # Required for SARIF upload
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Run FlowLint
-        run: npx flowlint scan --format sarif --out-file results.sarif
-        continue-on-error: true  # Don't fail workflow on findings
-
-      - name: Upload SARIF results
-        uses: github/codeql-action/upload-sarif@v3
-        if: always()
-        with:
-          sarif_file: results.sarif
-```
-
-#### Option 2: Workflow Annotations
-
-Show findings directly in workflow logs:
+### Initialize configuration
 
-```yaml
-name: FlowLint
-
-on:
-  pull_request:
-    paths:
-      - '**.json'
-
-jobs:
-  flowlint:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Run FlowLint
-        run: npx flowlint scan --format github-actions --fail-on-error
-```
-
-#### Option 3: Both (Best of Both Worlds)
-
-Combine both approaches for immediate feedback and permanent annotations:
-
-```yaml
-name: FlowLint
-
-on:
-  pull_request:
-    paths:
-      - '**.json'
-
-jobs:
-  flowlint:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      security-events: write
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Run FlowLint (Workflow Annotations)
-        run: npx flowlint scan --format github-actions
-        continue-on-error: true
-
-      - name: Run FlowLint (SARIF)
-        run: npx flowlint scan --format sarif --out-file results.sarif
-        continue-on-error: true
-
-      - name: Upload SARIF results
-        uses: github/codeql-action/upload-sarif@v3
-        if: always()
-        with:
-          sarif_file: results.sarif
-
-      - name: Check for blocking issues
-        run: npx flowlint scan --fail-on-error
-```
-
-### GitLab CI
-
-```yaml
-flowlint:
-  stage: test
-  image: node:22
-  script:
-    - npx flowlint scan --format junit --out-file flowlint-results.xml
-  artifacts:
-    when: always
-    reports:
-      junit: flowlint-results.xml
-```
-
-### Jenkins
-
-```groovy
-pipeline {
-  agent any
-
-  stages {
-    stage('FlowLint') {
-      steps {
-        sh 'npx flowlint scan --format junit --out-file flowlint-results.xml'
-      }
-      post {
-        always {
-          junit 'flowlint-results.xml'
-        }
-      }
-    }
-  }
-}
-```
-
-### CircleCI
-
-```yaml
-version: 2.1
-
-jobs:
-  flowlint:
-    docker:
-      - image: cimg/node:22.0
-    steps:
-      - checkout
-      - run:
-          name: Run FlowLint
-          command: npx flowlint scan --format junit --out-file test-results/flowlint.xml
-      - store_test_results:
-          path: test-results
+```bash
+flowlint init
 ```
 
-### Azure Pipelines
-
-```yaml
-trigger:
-  branches:
-    include:
-      - main
-      - develop
-
-pool:
-  vmImage: 'ubuntu-latest'
-
-steps:
-  - task: NodeTool@0
-    inputs:
-      versionSpec: '22.x'
-
-  - script: npx flowlint scan --format junit --out-file flowlint-results.xml
-    displayName: 'Run FlowLint'
-
-  - task: PublishTestResults@2
-    condition: always()
-    inputs:
-      testResultsFormat: 'JUnit'
-      testResultsFiles: 'flowlint-results.xml'
-      failTaskOnFailedTests: true
-```
+Creates a `.flowlint.yml` file in the current directory.
 
 ## Configuration
 
-Create a `.flowlint.yml` file in your repository root:
+Create a `.flowlint.yml` file:
 
 ```yaml
 files:
   include:
-    - '**/*.json'
+    - "**/*.n8n.json"
   ignore:
-    - 'node_modules/**'
-    - 'dist/**'
-
-report:
-  annotations: true
-  summary_limit: 100
+    - "node_modules/**"
 
 rules:
-  R1:
+  rate_limit_retry:
     enabled: true
-  R2:
+  error_handling:
     enabled: true
-  # ... etc
-```
-
-See [FlowLint documentation](https://flowlint.dev) for complete configuration reference.
-
-## Exit Codes
-
-- `0` - Success (no errors or only warnings/suggestions)
-- `1` - Analysis found blocking issues (when using `--fail-on-error`)
-- `2` - Runtime error (invalid config, file not found, etc.)
-
-## Rule Severity Levels
-
-- **must** - Blocks PR (errors) - Critical issues that must be fixed
-- **should** - Warnings - Important issues that should be addressed
-- **nit** - Suggestions - Minor improvements
-
-## Supported Rules
-
-FlowLint currently implements the following rules:
-
-- **R1** - Rate Limit & Retry
-- **R2** - Error Handling
-- **R3** - Idempotency
-- **R4** - Secrets
-- **R5** - Dead Ends
-- **R6** - Long Running
-- **R7** - Alert/Log Enforcement
-- **R8** - Unused Data
-- **R9** - Config Literals
-- **R10** - Naming Convention
-- **R11** - Deprecated Nodes
-- **R12** - Unhandled Error Path
-- **R13** - Webhook Acknowledgment
-- **R14** - HTTP Retry-After Compliance
-
-See [RULES.md](https://github.com/Replikanti/flowlint-examples/blob/main/README.md) for detailed rule documentation.
-
-## Troubleshooting
+  # ... more rules
+```
+
+## 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 |
 
-### No workflows found
-
-Make sure your workflow files match the glob patterns in `.flowlint.yml`:
-
-```yaml
-files:
-  include:
-    - '**/*.json'  # Adjust pattern as needed
-```
-
-### SARIF upload fails in GitHub Actions
-
-Ensure you have the correct permissions:
-
-```yaml
-permissions:
-  contents: read
-  security-events: write  # Required for SARIF upload
-```
-
-### JUnit results not showing in CI
-
-Make sure the file path in your CI configuration matches the `--out-file` path.
+## License
 
-## Links
+MIT
 
-- [Documentation](https://flowlint.dev)
-- [GitHub Repository](https://github.com/Replikanti/flowlint-app)
-- [Issue Tracker](https://github.com/Replikanti/flowlint-app/issues)
-- [npm Package](https://www.npmjs.com/package/flowlint)
 
-## License
+## Dependencies
 
-MIT
+This tool depends on [@replikanti/flowlint-core](https://www.npmjs.com/package/@replikanti/flowlint-core) for linting logic.