code-quality-lib 2.0.2 → 2.6.0

package/README.md

@@ -15,6 +15,9 @@
 - **CLI + Library** — use from terminal or programmatically
 - **Detailed reports** — generates `.quality-report.md` with AI-friendly error info
 - **`--logs` flag** — verbose terminal output for debugging
+- **`--fix` flag** — auto-fix ESLint and Prettier issues automatically
+- **Environment-based configs** — different tools for dev vs CI/CD
+- **Snyk token validation** — validates tokens before running security scans
 - **TypeScript definitions** — full type safety included
 
 ## Installation
@@ -29,73 +32,279 @@ yarn add -D code-quality-lib        # yarn
 ## Quick Start
 
 ```bash
-npx code-quality          # npm
-bunx code-quality         # bun
-pnpm dlx code-quality     # pnpm
-yarn dlx code-quality     # yarn
+# Install and run (first time will auto-start wizard)
+npm install -D code-quality-lib && npx code-quality
+
+# Or with bun
+bun add -D code-quality-lib && bunx code-quality
+
+# Or with yarn
+yarn add -D code-quality-lib && yarn code-quality
 ```
 
 ## CLI Usage
 
 ```bash
 code-quality              # run all quality checks
+code-quality --wizard     # run interactive setup wizard
+code-quality --config     # generate .code-quality.json config file
 code-quality --logs       # show detailed error output
+code-quality --fix        # auto-fix ESLint and Prettier issues
+code-quality --env dev    # run development checks (ESLint, TS, Prettier)
+code-quality --env ci     # run CI/CD checks (all tools)
+code-quality --env prod    # run production checks (all tools)
 code-quality --help       # show help
 code-quality --version    # show version
 ```
 
-## Library Usage
+### Interactive Wizard
+
+Use the wizard to configure options before running:
+
+```bash
+code-quality --wizard
+```
+
+The wizard will guide you through:
+
+```
+🧙‍♂️ Code Quality Setup Wizard
+──────────────────────────────────────────────────
+Let's configure your quality checks!
+
+📦 Detected package manager: npm
+Use npm? (Y/n):
+
+🔧 Select tools to run (default = all checked):
+[✓] TypeScript? (Y/n):
+[✓] ESLint? (Y/n):
+[✓] Prettier? (Y/n):
+[✓] Knip? (Y/n):
+[✓] Snyk? (Y/n):
+
+🌍 Set up environment-specific tool sets?
+This allows different tools for development vs CI/CD
+Configure environments? (y/N):
+
+📋 Configuration Summary:
+──────────────────────────────────────────────────
+📦 Package Manager: npm
+⚙️  Config: Project configs (detected)
+🔧 Tools: TypeScript, ESLint, Prettier, Knip, Snyk
+🌍 Load .env: Yes (always)
+──────────────────────────────────────────────────
+Run checks with these settings? (Y/n):
+```
+
+**Smart Features:**
+
+- **Remember settings** — First run creates `.code-quality.json`, future runs skip questions
+- **Yes/No questions** — Simple Y/n prompts with sensible defaults
+- **Checkbox-style tools** — Each tool can be individually enabled/disabled
+- **Always uses project configs** — Automatically detects and uses your existing ESLint/Prettier configs
+- **Always loads .env** — Environment variables are always available for your tools
+
+After confirmation, it runs the quality checks with your selected settings.
+
+### Auto-Wizard on First Run
+
+If you run `code-quality` without any configuration file, it automatically starts the wizard:
+
+```bash
+code-quality    # First run: no config found → starts wizard
+code-quality    # Subsequent runs: uses saved settings
+```
+
+This ensures proper setup on first use while being fast on subsequent runs.
+
+### Terminal Output
+
+The CLI provides step-by-step progress like setup wizards:
+
+```
+🚀 Code Quality Setup
+──────────────────────────────────────────────────
+📦 Package Manager: npm
+⚙️  Config: Project configs
+🔧 Tools: 5 quality checks
+
+ 1. TypeScript... ✅ Done
+ 2. ESLint... ✅ Done
+ 3. Prettier... ✅ Done
+ 4. Knip... ✅ Done
+ 5. Snyk... ✅ Done
+
+──────────────────────────────────────────────────
+📊 Quality Check Summary
+
+✅ TypeScript  Passed
+✅ ESLint      Passed
+✅ Prettier    Passed
+✅ Knip        Passed
+✅ Snyk        Passed
+
+──────────────────────────────────────────────────
+🎉 Success! All quality checks passed.
+
+✅ Your code is ready for production!
+```
+
+### Auto-Fix with --fix
+
+Automatically fix ESLint and Prettier issues:
+
+```bash
+code-quality --fix                    # Fix all issues
+code-quality --env prod --fix          # Fix in production mode
+code-quality --ESLint --fix           # Fix only ESLint
+code-quality --Prettier --fix         # Fix only Prettier
+```
+
+The `--fix` flag will:
+
+1. Run quality checks normally
+2. If ESLint or Prettier fail, automatically run:
+   - `eslint --fix` for ESLint issues
+   - `prettier --write` for Prettier issues
+3. Re-run checks to verify fixes
+4. Show final results
+
+### Environment-Based Configuration
+
+Different tool sets for different environments:
+
+```bash
+code-quality --env development    # ESLint, TypeScript, Prettier
+code-quality --env ci             # All tools (ESLint, TS, Prettier, Knip, Snyk)
+code-quality --env production     # All tools (ESLint, TS, Prettier, Knip, Snyk)
+```
+
+Or configure environments in `.code-quality/config.json`:
+
+```json
+{
+  "environments": {
+    "development": {
+      "tools": ["ESLint", "TypeScript", "Prettier"]
+    },
+    "ci": {
+      "tools": ["ESLint", "TypeScript", "Prettier", "Knip", "Snyk"]
+    },
+    "production": {
+      "tools": ["ESLint", "TypeScript", "Prettier", "Knip", "Snyk"]
+    }
+  },
+  "packageManager": "npm"
+}
+```
+
+### Configuration Directory
+
+Generate a configuration directory with reference configs:
+
+```bash
+code-quality --config
+```
+
+This creates `.code-quality/` directory with:
+
+- **config.json** — Main configuration file
+- **tsconfig.json** — TypeScript reference config
+- **eslint.config.mjs** — ESLint reference config
+- **.prettierrc** — Prettier reference config
+- **knip.json** — Knip reference config
+- **README.md** — Usage documentation
+
+The CLI automatically loads `.code-quality/config.json` if it exists:
+
+```bash
+code-quality    # uses your custom config
+```
+
+Or use it programmatically:
 
 ```javascript
-const { CodeQualityChecker, runQualityCheck } = require('code-quality-lib');
+const config = require('./.code-quality/config.json')
+const checker = new CodeQualityChecker(config)
+await checker.run()
+```
+
+### Configuration
+
+The library automatically detects and uses your project's existing configuration files (`.eslintrc`, `.prettierrc`, `tsconfig.json`, etc.) if they exist. If no project configs are found, it uses bundled configurations.
+
+**Environment variables** from `.env` files are always loaded automatically.
+
+## Library Usage
 
-// Quick — run all checks with defaults (uses project's config files)
-const result = await runQualityCheck();
-console.log(result.success ? 'All passed' : 'Some failed');
+```javascript
+const { CodeQualityChecker, runQualityCheck } = require('code-quality-lib')
 
-// Use bundled configs instead of project's configs
-const checker = new CodeQualityChecker({
-  useProjectConfig: false, // use library's bundled .eslintrc, .prettierrc, etc.
-});
-await checker.run();
+// Quick — run all checks with defaults (auto-detects project configs)
+const result = await runQualityCheck()
+console.log(result.success ? 'All passed' : 'Some failed')
 
-// Custom — select tools, override commands
+// Advanced — custom configuration
 const customChecker = new CodeQualityChecker({
-  tools: ['TypeScript', 'ESLint'],
-  packageManager: 'pnpm',
+  environments: {
+    development: { tools: ['ESLint', 'TypeScript'] },
+    ci: { tools: ['ESLint', 'TypeScript', 'Prettier', 'Knip', 'Snyk'] },
+  },
+  packageManager: 'npm',
   commands: {
     TypeScript: 'tsc --noEmit',
     ESLint: 'eslint src/ --ext .ts,.tsx',
   },
-  loadEnv: false,
-});
+})
 
-const result = await customChecker.run({ showLogs: true });
-console.log(result.results); // per-tool results array
+const result = await customChecker.run({ showLogs: true })
+console.log(result.results) // per-tool results array
 ```
 
 ## Configuration Options
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `useProjectConfig` | `boolean` | `true` | Use project's config files (`.eslintrc.js`, `.prettierrc`, etc.) instead of bundled configs |
-| `tools` | `string[]` | All 5 tools | Which tools to run |
-| `packageManager` | `'npm' \| 'bun' \| 'pnpm' \| 'yarn'` | auto-detected | Force a specific package manager |
-| `commands` | `Record<string, string>` | bundled paths | Custom commands per tool |
-| `descriptions` | `Record<string, string>` | built-in | Custom descriptions per tool |
-| `loadEnv` | `boolean` | `true` | Load `.env` file |
+| Option             | Type                                 | Default       | Description                                                                                 |
+| ------------------ | ------------------------------------ | ------------- | ------------------------------------------------------------------------------------------- |
+| `tools`            | `string[]`                           | All 5 tools   | Which tools to run (deprecated - use environments instead)                                    |
+| `packageManager`   | `'npm' \| 'bun' \| 'pnpm' \| 'yarn'` | auto-detected | Force a specific package manager                                                            |
+| `commands`         | `Record<string, string>`             | bundled paths | Custom commands per tool                                                                    |
+| `descriptions`     | `Record<string, string>`             | built-in      | Custom descriptions per tool                                                                |
+| `environment`      | `string`                             | auto-detected | Override environment (development, ci, production)                                          |
+| `environments`     | `Record<string, EnvironmentConfig>`  | -             | Environment-specific tool configurations                                                    |
+
+**EnvironmentConfig:**
+
+```typescript
+interface EnvironmentConfig {
+  tools: string[]
+}
+```
+
+## Tool Resolution
 
-## Bundled Tools
+The library intelligently resolves tools in this order:
 
-All tools are included as dependencies — zero extra setup:
+1. **Project's `node_modules/.bin`** — Uses your project's installed versions first
+2. **Library's bundled tools** — Falls back to bundled versions if not found in project
+3. **Custom commands** — If you specify custom commands in config, uses them as-is
 
-| Tool | Description |
-|------|-------------|
-| **TypeScript** | Type checking (`tsc --noEmit`) |
-| **ESLint** | Linting with plugins (react, sonarjs, unicorn, import, prettier) |
-| **Prettier** | Code formatting validation |
-| **Knip** | Dead code and unused export detection |
-| **Snyk** | Security vulnerability scanning |
+This means:
+
+- ✅ Uses your project's tool versions and configurations by default
+- ✅ Works out-of-the-box with bundled tools as fallback
+- ✅ Custom commands use tools from your project's PATH
+
+### Bundled Tools
+
+All tools are included as dependencies for fallback:
+
+| Tool           | Description                                                      |
+| -------------- | ---------------------------------------------------------------- |
+| **TypeScript** | Type checking (`tsc --noEmit`)                                   |
+| **ESLint**     | Linting with plugins (react, sonarjs, unicorn, import, prettier) |
+| **Prettier**   | Code formatting validation                                       |
+| **Knip**       | Dead code and unused export detection                            |
+| **Snyk**       | Security vulnerability scanning                                  |
 
 ## Package Manager Detection
 
@@ -110,12 +319,46 @@ Automatically detected by lock file presence:
 ## Error Reporting
 
 Every run generates `.quality-report.md` with:
+
 - Status of each check (pass/fail)
 - Full error output for failed checks
 - AI-friendly structured information for automated fixes
 
 Add `.quality-report.md` to your `.gitignore`.
 
+## Snyk Token Validation
+
+The library validates Snyk tokens before running security scans:
+
+```bash
+# Set your Snyk token
+export SNYK_TOKEN=your_token_here
+
+# Or add to .env file
+echo "SNYK_TOKEN=your_token_here" >> .env
+
+# Run with validation
+code-quality --env production
+```
+
+**Token Validation Features:**
+
+- **Pre-scan validation** - Checks token before running full scan
+- **Clear cache** - Forces token validation by clearing Snyk cache
+- **Detailed errors** - Shows helpful fix instructions for invalid tokens
+- **Fallback handling** - Graceful degradation for token issues
+
+**Error Messages:**
+
+```
+❌ Snyk token validation failed. Token may be expired or invalid.
+
+To fix:
+1. Get a new token at: https://snyk.io/login
+2. Set SNYK_TOKEN in your .env file
+3. Or run: npx snyk auth
+```
+
 ## AI Skills
 
 This library includes `.ai/skills/` — markdown files that teach AI coding assistants (Cursor, Copilot, Windsurf, etc.) to follow the project's coding standards. See [`.ai/skills/README.md`](.ai/skills/README.md).
@@ -127,6 +370,7 @@ This library includes `.ai/skills/` — markdown files that teach AI coding assi
 ## Testing & CI/CD
 
 Tested on every push across 4 runtimes:
+
 - **Node.js 25.x** (npm)
 - **Bun 1.3.x**
 - **pnpm 10.x**

package/config/.prettierignore

@@ -0,0 +1,87 @@
+# Quality reports and configuration
+.quality-report.md
+.code-quality/
+
+# Build outputs
+dist/
+build/
+.next/
+out/
+
+# Dependencies
+node_modules/
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Coverage directory used by tools like istanbul
+coverage/
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# Dependency directories
+jspm_packages/
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variables file
+.env
+.env.test
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+.parcel-cache
+
+# next.js build output
+.next
+
+# nuxt.js build output
+.nuxt
+
+# vuepress build output
+.vuepress/dist
+
+# Serverless directories
+.serverless
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# TernJS port file
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+.vscode-test
+
+.venv

package/config/.prettierrc

@@ -0,0 +1,17 @@
+{
+  "semi": false,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "endOfLine": "lf",
+  "arrowParens": "always",
+  "bracketSpacing": true,
+  "bracketSameLine": false,
+  "quoteProps": "as-needed",
+  "jsxSingleQuote": true,
+  "proseWrap": "preserve",
+  "htmlWhitespaceSensitivity": "css",
+  "embeddedLanguageFormatting": "auto"
+}

package/config/README.md

@@ -0,0 +1,32 @@
+# Code Quality Configuration
+
+This directory contains reference configuration files for code quality tools.
+
+## Files
+
+- **eslint.config.mjs** - ESLint flat config with React, TypeScript, and accessibility rules
+- **tsconfig.json** - TypeScript configuration with strict settings
+- **.prettierrc** - Prettier formatting rules
+- **.prettierrcignore** - Files to ignore when formatting
+- **knip.json** - Dead code detection configuration
+
+## Usage
+
+These files are automatically copied to your project's `.code-quality/` directory when you run:
+
+```bash
+code-quality --init
+# or
+code-quality --wizard
+```
+
+## Customization
+
+You can modify these files after copying them to suit your project's needs.
+
+## Notes
+
+- ESLint config uses conditional loading for optional plugins (Next.js, jsx-a11y, prettier)
+- TypeScript config is optimized for React/Next.js projects
+- Prettier config matches ESLint semicolon settings
+- Knip config is set to ignore test files and dependencies

package/config/config.json

@@ -0,0 +1,30 @@
+{
+  "packageManager": "bun",
+  "environments": {
+    "development": {
+      "tools": [
+        "ESLint",
+        "TypeScript",
+        "Prettier"
+      ]
+    },
+    "ci": {
+      "tools": [
+        "ESLint",
+        "TypeScript",
+        "Prettier",
+        "Knip",
+        "Snyk"
+      ]
+    },
+    "production": {
+      "tools": [
+        "ESLint",
+        "TypeScript",
+        "Prettier",
+        "Knip",
+        "Snyk"
+      ]
+    }
+  }
+}