pipechecker 0.2.2 → 0.2.5

package/README.md

@@ -1,206 +1,570 @@
-# 🔍 Pipecheck
+# PipeChecker
 
-[![CI](https://github.com/Ayyankhan101/PipeCheck/workflows/CI/badge.svg)](https://github.com/Ayyankhan101/PipeCheck/actions)
-[![Crates.io](https://img.shields.io/crates/v/pipecheck.svg)](https://crates.io/crates/pipecheck)
-[![npm](https://img.shields.io/npm/v/pipecheck.svg)](https://www.npmjs.com/package/pipecheck)
-[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](LICENSE-MIT)
+> **Catch CI/CD pipeline errors before you push — not after CI fails.**
 
-**A blazingly fast CI/CD pipeline auditor that catches errors before you push.**
+[![CI](https://github.com/Ayyankhan101/PipeChecker/actions/workflows/ci.yml/badge.svg)](https://github.com/Ayyankhan101/PipeChecker/actions/workflows/ci.yml)
+[![Crates.io](https://img.shields.io/crates/v/pipechecker.svg)](https://crates.io/crates/pipechecker)
+[![License](https://img.shields.io/badge/license-MIT%20%2F%20Apache--2.0-blue)](LICENSE-MIT)
+[![Test Coverage](https://img.shields.io/badge/tests-103%20passing-brightgreen)]()
+[![Rust](https://img.shields.io/badge/rust-2021-orange)](Cargo.toml)
 
-Stop wasting time debugging CI failures. Pipecheck validates your GitHub Actions, GitLab CI, and CircleCI configurations locally, catching syntax errors, circular dependencies, and security issues instantly.
+---
 
-## 🚀 Quick Start
+## What Problem Does This Solve?
 
-### Install via npm (recommended)
+Every developer has been here:
+
+```
+💀 You push a small change → CI fails 10 minutes later →
+   you fix it → push again → CI fails again → repeat 3 more times
+```
+
+**PipeChecker runs locally** and validates your CI/CD workflows **before** you commit, so you catch:
+
+| Catches | Example |
+|---------|---------|
+| ❌ **Circular dependencies** | Job A → Job B → Job A |
+| ❌ **Missing job references** | `needs: [build]` but no `build` job exists |
+| ❌ **Empty pipelines** | No jobs or steps defined |
+| ⚠️ **Hardcoded secrets** | `API_KEY=sk_live_abc123` in env vars |
+| ⚠️ **Undeclared env vars** | `${{ env.UNKNOWN }}` never defined |
+| ⚠️ **Unpinned actions** | `uses: actions/checkout` without `@v4` |
+| ⚠️ **Docker `:latest` tags** | `image: nginx:latest` (unreproducible builds) |
+| ⚠️ **Missing job timeouts** | No `timeout-minutes` set — jobs can run forever |
+
+---
+
+## Visual Overview
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    YOUR WORKFLOW FILE                    │
+│              (.github/workflows/ci.yml)                  │
+└────────────────────────┬────────────────────────────────┘
+                         │
+                         ▼
+              ┌──────────────────────┐
+              │    PIPECHECKER       │
+              │                      │
+              │  ┌────────────────┐  │
+              │  │  YAML Parser   │  │
+              │  │ GitHub/GitLab  │  │
+              │  │   CircleCI     │  │
+              │  └───────┬────────┘  │
+              │          │           │
+              │  ┌───────▼────────┐  │
+              │  │    Auditors    │  │
+              │  │                │  │
+              │  │  📋 Syntax     │  │
+              │  │  🔗 DAG/Cycle  │  │
+              │  │  🔒 Secrets    │  │
+              │  │  🐳 Docker     │  │
+              │  │  📌 Pinning    │  │
+              │  └───────┬────────┘  │
+              │          │           │
+              └──────────┼───────────┘
+                         │
+          ┌──────────────┼──────────────┐
+          ▼              ▼              ▼
+     ✅ PASS       ⚠️ WARNINGS    ❌ ERRORS
+   No issues     Fix before       Must fix
+   found!        production       before push
+```
+
+---
+
+## Supported Platforms
+
+| Platform | File Pattern | Status |
+|----------|-------------|--------|
+| **GitHub Actions** | `.github/workflows/*.yml` | ✅ Full support |
+| **GitLab CI** | `.gitlab-ci.yml` | ✅ Full support |
+| **CircleCI** | `.circleci/config.yml` | ✅ Full support |
+
+---
+
+## Installation
+
+### From crates.io
+```bash
+cargo install pipechecker
+```
+
+### From source
 ```bash
-npm install -g pipecheck
+git clone https://github.com/Ayyankhan101/PipeChecker.git
+cd PipeChecker
+cargo install --path .
 ```
 
-### Install via Cargo
+### Via npm (once published)
 ```bash
-cargo install pipecheck
+npm install -g pipechecker
 ```
 
-### Run
+---
+
+## Quick Start
+
+### 1. Check a single file
 ```bash
-pipecheck .github/workflows/ci.yml
+pipechecker .github/workflows/ci.yml
+```
+
+### 2. Auto-detect your workflow
+```bash
+pipechecker
+# ✓ Auto-detected: .github/workflows/ci.yml
+# Provider: GitHubActions
+# 0 errors, 0 warnings
+```
+
+### 3. Audit everything
+```bash
+pipechecker --all
+# Checking 3 workflow file(s)...
+#
+# 📄 .github/workflows/ci.yml
+#    Provider: GitHubActions
+#    ✅ No issues found
+#
+# 📄 .github/workflows/deploy.yml
+#    Provider: GitHubActions
+#    1 errors, 2 warnings
+#    ❌ ERROR: Circular dependency detected (job: deploy)
+#       💡 Remove one of the dependencies to break the cycle
+#    ⚠️ WARNING: Job 'deploy' has no steps
+#
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# Total: 1 errors, 2 warnings across 3 files
+```
+
+---
+
+## Interactive TUI
+
+PipeChecker includes a **terminal UI** for browsing results across multiple files:
+
+```bash
+pipechecker --tui
+```
+
+```
+┌──────────────────────────────────────────┐
+│  🔍 Pipecheck - Interactive Mode         │
+├──────────────────────────────────────────┤
+│  Workflows                               │
+│▶ ❌ deploy.yml │ 2 errors │ 1 warnings   │
+│  ✅ ci.yml     │ 0 errors │ 0 warnings   │
+│  ⚠️  lint.yml   │ 0 errors │ 3 warnings   │
+├──────────────────────────────────────────┤
+│  [↑/↓] Navigate  [Enter] Details  [Q] Quit│
+└──────────────────────────────────────────┘
+```
+
+**Keyboard shortcuts:**
+
+| Key | Action |
+|-----|--------|
+| `↑` / `k` | Move up |
+| `↓` / `j` | Move down |
+| `Enter` / `Space` | Toggle detail view |
+| `q` / `Esc` | Quit |
+
+---
+
+## All CLI Flags
+
+| Flag | Description |
+|------|-------------|
+| `FILE` | Path to a specific workflow file |
+| `--all`, `-a` | Audit **all** discovered workflow files |
+| `--tui` | Launch the interactive terminal UI |
+| `--watch`, `-w` | Watch for file changes and re-run audits |
+| `--fix` | Auto-fix issues (pin unpinned actions + Docker `:latest` tags) |
+| `--install-hook` | Install a git pre-commit hook |
+| `--format`, `-f` `<text\|json>` | Output format (default: `text`) |
+| `--strict`, `-s` | Treat warnings as errors (exit code 1) |
+| `--quiet`, `-q` | Only output errors — suppress warnings and info. Perfect for CI |
+| `--verbose` | Show diagnostic info (auditors ran, per-severity counts, discovered files) |
+| `--no-pinning` | Skip Docker image and action-pinning checks |
+| `--version` | Show version |
+| `--help` | Show help |
+
+---
+
+## Output Explained
+
+### Severity Levels
+
+| Symbol | Level | Meaning |
+|--------|-------|---------|
+| ❌ | **Error** | Must fix — will break your pipeline |
+| ⚠️ | **Warning** | Should fix — may cause issues later |
+| ℹ️ | **Info** | Informational — nothing to worry about |
+
+### Example output with details
+
+```
+Provider: GitHubActions
+2 errors, 1 warnings
+
+❌ ERROR: Circular dependency detected (job: deploy) [line 42]
+   💡 Remove one of the dependencies to break the cycle
+
+❌ ERROR: Job 'deploy' depends on non-existent job 'build' (job: deploy) [line 45]
+   💡 Add a job with id 'build' or remove the dependency
+
+⚠️ WARNING: Job 'lint' has no steps (job: lint) [line 12]
+   💡 Add steps to perform work in this job
 ```
 
-## ✨ Features
+Each issue includes:
+- **What** went wrong (clear message)
+- **Where** it happened (job name + line number)
+- **How** to fix it (actionable suggestion)
 
-- ✅ **Syntax Validation** - Parse and validate GitHub Actions, GitLab CI, and CircleCI configs
-- 🔄 **Dependency Analysis** - Detect circular dependencies in job workflows
-- 🔐 **Secrets Auditing** - Identify hardcoded secrets and environment variable issues
-- 🐳 **Docker Validation** - Check Docker image references and tags
-- 📊 **Multiple Output Formats** - Text and JSON output for CI integration
-- ⚡ **Fast** - Written in Rust for maximum performance
-- 🎯 **Zero Config** - Works out of the box
+---
 
-## 💡 Why Pipecheck?
+## JSON Output
 
-**Before Pipecheck:**
+Perfect for CI/CD integration or programmatic consumption:
+
+```bash
+pipechecker --format json
 ```
-git push
-→ Wait 5 minutes
-→ CI fails: "Circular dependency detected"
-→ Fix locally
-→ git push again
-→ Wait 5 minutes...
+
+```json
+{
+  "provider": "GitHubActions",
+  "issues": [
+    {
+      "severity": "Error",
+      "message": "Circular dependency detected: job-a -> job-b -> job-a",
+      "location": { "line": 42, "column": 3, "job": "deploy" },
+      "suggestion": "Remove one of the dependencies to break the cycle"
+    }
+  ],
+  "summary": "1 errors, 0 warnings"
+}
 ```
 
-**With Pipecheck:**
+---
+
+## Modes of Operation
+
+### 🔧 Auto-Fix Mode
+Automatically pins unpinned GitHub Actions to known versions:
+
+```bash
+pipechecker --fix
 ```
-pipecheck .github/workflows/ci.yml
-→ ❌ ERROR: Circular dependency detected: job-a -> job-c -> job-b
-→ Fix immediately
-→ git push with confidence ✅
+
 ```
+🔧 Auto-fix mode
+
+✨ Fixed 2 issue(s) in .github/workflows/ci.yml:
+
+  actions/checkout → actions/checkout@v4
+  actions/setup-node → actions/setup-node@v4
 
-## 📖 Usage
+💡 Review the changes and commit them!
+```
 
-### Quick Start
+### 👀 Watch Mode
+Monitors workflow files and re-runs on every save — perfect for development:
 
 ```bash
-# Auto-detect and check workflow
-pipecheck
+pipechecker --watch
+```
+
+```
+👀 Watching for workflow changes...
+   Press Ctrl+C to stop
 
-# Check specific file
-pipecheck .github/workflows/ci.yml
+🔄 File changed: .github/workflows/ci.yml
+Provider: GitHubActions
+0 errors, 0 warnings
+✅ All checks passed
+```
 
-# Check all workflows
-pipecheck --all
+### 🤫 Quiet Mode (CI-Friendly)
+Only output errors — suppress warnings and info. Perfect for CI pipelines where you want clean output:
 
-# Interactive TUI mode
-pipecheck --tui
+```bash
+pipechecker --quiet
+# or
+pipechecker -q
 ```
 
-### All Options
+```
+❌ Circular dependency detected (job: deploy) (in .github/workflows/deploy.yml)
+```
 
+Exit code is still `1` if there are errors — works perfectly with `--strict` for failing CI on any issue.
+
+### 📢 Verbose Mode
+See exactly what PipeChecker is doing — which files it found, which auditors ran, and per-severity breakdowns:
+
+```bash
+pipechecker --verbose
 ```
-CI/CD Pipeline Auditor - Catch errors before you push
 
-Usage: pipecheck [OPTIONS] [FILE]
+```
+📄 Auditing: .github/workflows/ci.yml
+🔍 Auditors ran: syntax, dag, secrets, pinning
+📊 Found: 0 errors, 1 warnings, 0 info
+⏱️  Checked in 3.2ms
+```
+
+### ⏱️ Timing Metrics
+Every audit now shows how long it took — because speed matters:
 
-Arguments:
-  [FILE]  Path to pipeline configuration file (auto-detects if not provided)
+```bash
+pipechecker .github/workflows/ci.yml
+```
 
-Options:
-  -a, --all              Check all workflow files in directory
-      --install-hook     Install pre-commit hook
-  -w, --watch            Watch for file changes and re-check
-      --fix              Automatically fix issues where possible
-      --tui              Interactive terminal UI mode
-  -f, --format <FORMAT>  Output format (text, json) [default: text]
-      --no-docker        Skip Docker image checks
-  -s, --strict           Enable strict mode (warnings as errors)
-  -h, --help             Print help
-  -V, --version          Print version
+```
+Provider: GitHubActions
+0 errors, 0 warnings
+✅ All checks passed
+⏱️  Checked in 2.1ms
 ```
 
-### Interactive Features
+### 🔒 Pre-commit Hook
+Never commit a broken workflow again:
 
 ```bash
-# Install pre-commit hook
-pipecheck --install-hook
+pipechecker --install-hook
+```
+
+```
+✅ Pre-commit hook installed!
+   Pipecheck will run before every commit
+   Use 'git commit --no-verify' to skip
+```
 
-# Watch mode - auto-recheck on file changes
-pipecheck --watch
+The hook automatically validates any workflow files you stage:
 
-# Interactive TUI mode
-pipecheck --tui
+```bash
+$ git commit -m "Update CI pipeline"
+🔍 Checking workflows with pipechecker...
+❌ ERROR: Circular dependency detected (job: deploy) [line 42]
+   💡 Remove one of the dependencies to break the cycle
 
-# Auto-fix issues (Coming soon!)
-pipecheck --fix
+❌ Workflow validation failed!
+Fix errors above or use 'git commit --no-verify' to skip
 ```
 
-### Configuration File
+---
+
+## Configuration File
 
-Create `.pipecheckrc.yml` in your project root:
+Create a `.pipecheckerrc.yml` in your project root to customize behavior:
 
 ```yaml
+# Files to skip (glob patterns supported)
 ignore:
-  - .github/workflows/old-*.yml
-  
+  - .github/workflows/experimental-*.yml
+  - .github/workflows/draft-*.yml
+  - old-pipeline.yml
+
+# Toggle individual audit rules
 rules:
-  circular_dependencies: true
-  missing_secrets: true
-  docker_latest_tag: true
+  circular_dependencies: true   # Detect dependency cycles
+  missing_secrets: true         # Flag hardcoded secrets
+  docker_latest_tag: true       # Warn about :latest tags
 ```
 
-### Output Formats
+PipeChecker searches for config in this order:
+1. `.pipecheckerrc.yml`
+2. `.pipecheckerrc.yaml`
+3. `.pipechecker.yml`
 
-```bash
-# Text output (default)
-pipecheck .github/workflows/ci.yml
+---
+
+## How the Auditors Work
+
+### 📋 Syntax Auditor
+Validates the structural integrity of your pipeline:
 
-# JSON output for CI integration
-pipecheck .github/workflows/ci.yml --format json
+- ✅ Jobs are defined
+- ✅ Steps exist within jobs
+- ✅ No duplicate job IDs
+- ✅ `needs` / `depends_on` targets exist
 
-# Strict mode (warnings as errors)
-pipecheck .github/workflows/ci.yml --strict
+### 🔗 DAG Auditor (Cycle Detection)
+Builds a **dependency graph** of your jobs and runs **Tarjan's Strongly Connected Components** algorithm:
 
-# Skip Docker checks
-pipecheck .github/workflows/ci.yml --no-docker
 ```
+  job-a ──depends──▶ job-b
+    ▲                   │
+    │                   ▼
+    └────depends──── job-c
+```
+→ ❌ **Circular dependency detected:** job-a → job-b → job-c → job-a
+
+### 🔒 Secrets Auditor
+Scans for security issues in environment variables and run blocks:
+
+```yaml
+env:
+  API_KEY: sk_live_abc123         # ⚠️ Hardcoded secret
+  TOKEN: ${{ secrets.TOKEN }}     # ✅ Correct way
+  RUN: echo ${{ secrets.API_KEY }} # ℹ️ Info — ensure it's configured
+  RUN: echo ${{ env.UNDEFINED }}  # ⚠️ Undeclared env var
+```
+
+Detects:
+- Hardcoded API keys, passwords, tokens
+- Secret references in `with:` blocks
+- Undeclared `${{ env.X }}` references
+- Suspicious values (long alphanumeric strings, base64)
 
-## 📋 Example Output
+### 🐳 Docker & 📌 Pinning Auditor
+Ensures reproducible builds:
 
+```yaml
+uses: actions/checkout              # ⚠️ No version pin
+uses: actions/checkout@v4           # ✅ Pinned
+image: nginx:latest                 # ⚠️ Unpredictable
+image: nginx:1.25-alpine            # ✅ Specific
 ```
+
+---
+
+## Real-World Examples
+
+### Example 1: Valid workflow
+```bash
+$ pipechecker .github/workflows/ci.yml
 Provider: GitHubActions
+0 errors, 0 warnings
+```
 
+### Example 2: Circular dependency
+```yaml
+jobs:
+  deploy:
+    needs: [test]
+    steps: [{ run: echo deploy }]
+  test:
+    needs: [deploy]
+    steps: [{ run: echo test }]
+```
+```bash
+$ pipechecker broken.yml
+Provider: GitHubActions
 1 errors, 0 warnings
 
-❌ ERROR: Circular dependency detected: job-a -> job-c -> job-b
+❌ ERROR: Circular dependency detected (job: deploy)
    💡 Remove one of the dependencies to break the cycle
+```
+
+### Example 3: Hardcoded secrets
+```yaml
+jobs:
+  build:
+    env:
+      API_SECRET: sk_live_hardcoded_value
+    steps: [{ run: echo building }]
+```
+```bash
+$ pipechecker secrets.yml
+Provider: GitHubActions
+0 errors, 1 warnings
+
+⚠️ WARNING: Job 'build' env 'API_SECRET' may contain a hardcoded secret
+   💡 Use secrets.API_SECRET instead of hardcoding
+```
+
+---
 
-ℹ️  INFO: Job 'build' uses secret: API_KEY
-   💡 Ensure this secret is configured in repository settings
+## Architecture
+
+```
+pipechecker/
+├── src/
+│   ├── main.rs          # CLI entry point (clap)
+│   ├── lib.rs           # Public API — audit_file, audit_content, discover_workflows
+│   ├── models.rs        # Core types — Pipeline, Job, Step, Issue, Severity
+│   ├── error.rs         # Error enum (thiserror)
+│   ├── config.rs        # .pipecheckerrc.yml loading
+│   ├── fix.rs           # Auto-fix for action pinning
+│   ├── tui.rs           # Interactive terminal UI (ratatui + crossterm)
+│   ├── parsers/
+│   │   ├── mod.rs       # Provider detection + dispatch
+│   │   ├── github.rs    # GitHub Actions YAML parser
+│   │   ├── gitlab.rs    # GitLab CI YAML parser
+│   │   └── circleci.rs  # CircleCI YAML parser
+│   └── auditors/
+│       ├── mod.rs       # Module gate
+│       ├── syntax.rs    # Structural validation
+│       ├── dag.rs       # Dependency graph + cycle detection (petgraph)
+│       ├── secrets.rs   # Secret/env var scanning (regex)
+│       └── pinning.rs   # Action/Docker image pinning
+├── tests/
+│   ├── parser_test.rs   # Parser integration tests
+│   └── auditors_test.rs # Auditor + fixture tests
+└── tests/fixtures/      # Sample workflow files for testing
 ```
 
-## 🔧 Supported Platforms
+---
 
-| Platform | Status | File Pattern |
-|----------|--------|--------------|
-| **GitHub Actions** | ✅ Full Support | `.github/workflows/*.yml` |
-| **GitLab CI** | ✅ Full Support | `.gitlab-ci.yml` |
-| **CircleCI** | ✅ Full Support | `.circleci/config.yml` |
+## CI/CD Integration
 
-## 🏗️ Use in CI/CD
+Add PipeChecker to your own CI pipeline:
 
-### GitHub Actions
 ```yaml
 - name: Validate workflows
   run: |
-    npm install -g pipecheck
-    pipecheck .github/workflows/*.yml --strict
+    cargo install pipechecker
+    pipechecker --all --strict --format json
 ```
 
-### GitLab CI
-```yaml
-validate:
-  script:
-    - cargo install pipecheck
-    - pipecheck .gitlab-ci.yml --strict
+Or use it as a pre-commit hook (recommended):
+
+```bash
+pipechecker --install-hook
 ```
 
-### Pre-commit Hook
+---
+
+## Development
+
+### Run tests
 ```bash
-#!/bin/bash
-pipecheck .github/workflows/*.yml --strict || exit 1
+cargo test
+# 103 tests — all passing
 ```
 
-## 🤝 Contributing
+### Lint & format
+```bash
+cargo clippy -- -D warnings
+cargo fmt -- --check
+```
 
-Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+### Coverage
+```bash
+cargo tarpaulin --fail-under 55
+```
+
+---
+
+## License
+
+This project is licensed under either **MIT** or **Apache-2.0** at your option.
+
+```
+SPDX: MIT OR Apache-2.0
+```
 
-## 📝 License
+---
 
-Licensed under either of:
-- MIT License ([LICENSE-MIT](LICENSE-MIT))
-- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
+<div align="center">
 
-at your option.
+**PipeChecker** — *because waiting 10 minutes for CI to tell you about a typo is nobody's idea of fun.*
 
-## 🌟 Show Your Support
+[Report a bug](https://github.com/Ayyankhan101/PipeCheck/issues) · [Request a feature](https://github.com/Ayyankhan101/PipeCheck/issues) · [Contributing](CONTRIBUTING.md)
 
-If Pipecheck saves you time, give it a ⭐ on GitHub!
+</div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pipechecker",
-  "version": "0.2.2",
+  "version": "0.2.5",
   "description": "CI/CD Pipeline Auditor - Catch errors before you push",
   "bin": {
     "pipechecker": "./bin/pipechecker.js"

package/scripts/install.js

@@ -62,7 +62,7 @@ async function install() {
 
   // Check if binary already exists
   if (fs.existsSync(binaryPath)) {
-    console.log('✓ Pipecheck binary already installed');
+    console.log('✓ Pipechecker binary already installed');
     return;
   }
 
@@ -78,7 +78,7 @@ async function install() {
   try {
     await download(url, binaryPath);
     fs.chmodSync(binaryPath, 0o755);
-    console.log('✓ Pipecheck installed successfully');
+    console.log('✓ Pipechecker installed successfully');
   } catch (error) {
     console.error(`Failed to download binary from ${url}`);
     console.error('Falling back to building from source...');
@@ -89,7 +89,7 @@ async function install() {
         process.platform === 'win32' ? 'pipechecker.exe' : 'pipechecker');
       fs.copyFileSync(sourceBinary, binaryPath);
       fs.chmodSync(binaryPath, 0o755);
-      console.log('✓ Pipecheck installed from source');
+      console.log('✓ Pipechecker installed from source');
     } catch (buildError) {
       console.error('Failed to build from source. Please ensure Rust is installed.');
       console.error('Visit https://rustup.rs to install Rust');