code-quality-lib 2.0.2 → 2.5.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,35 +32,244 @@ 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
 ```
 
+### 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):
+
+⚙️  Use project config files (.eslintrc, .prettierrc, etc.)?
+Answer "No" to use bundled configs from code-quality-lib
+Use project configs? (y/N):
+
+🔧 Select tools to run (default = all checked):
+[✓] TypeScript? (Y/n):
+[✓] ESLint? (Y/n):
+[✓] Prettier? (Y/n):
+[✓] Knip? (Y/n):
+[✓] Snyk? (Y/n):
+
+🌍 Load .env file before running checks?
+Load .env? (Y/n):
+
+📋 Configuration Summary:
+──────────────────────────────────────────────────
+📦 Package Manager: npm
+⚙️  Config: Bundled configs
+🔧 Tools: TypeScript, ESLint, Prettier, Knip, Snyk
+🌍 Load .env: Yes
+──────────────────────────────────────────────────
+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
+- **Bundled configs default** — Uses library's built-in configs by default
+
+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
+{
+  "version": "1.0.0",
+  "environments": {
+    "development": {
+      "tools": ["ESLint", "TypeScript", "Prettier"]
+    },
+    "ci": {
+      "tools": ["ESLint", "TypeScript", "Prettier", "Knip", "Snyk"]
+    },
+    "production": {
+      "tools": ["ESLint", "TypeScript", "Prettier", "Knip", "Snyk"]
+    }
+  },
+  "packageManager": "npm",
+  "useProjectConfig": true,
+  "loadEnv": true
+}
+```
+
+### 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 config = require('./.code-quality/config.json')
+const checker = new CodeQualityChecker(config)
+await checker.run()
+```
+
+### Config Modes
+
+**Use Project Configs (Default)**
+
+```json
+{
+  "useProjectConfig": true
+}
+```
+
+Uses your project's existing config files (`.eslintrc.js`, `.prettierrc`, `tsconfig.json`, etc.)
+
+**Use Reference Configs**
+
+```json
+{
+  "useProjectConfig": false
+}
+```
+
+Uses reference configs from `.code-quality/` directory as starting point for new projects
+
 ## Library Usage
 
 ```javascript
-const { CodeQualityChecker, runQualityCheck } = require('code-quality-lib');
+const { CodeQualityChecker, runQualityCheck } = require('code-quality-lib')
 
 // Quick — run all checks with defaults (uses project's config files)
-const result = await runQualityCheck();
-console.log(result.success ? 'All passed' : 'Some failed');
+const result = await runQualityCheck()
+console.log(result.success ? 'All passed' : 'Some failed')
 
 // Use bundled configs instead of project's configs
 const checker = new CodeQualityChecker({
   useProjectConfig: false, // use library's bundled .eslintrc, .prettierrc, etc.
-});
-await checker.run();
+})
+await checker.run()
 
 // Custom — select tools, override commands
 const customChecker = new CodeQualityChecker({
@@ -68,34 +280,58 @@ const customChecker = new CodeQualityChecker({
     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                                                                                 |
+| ------------------ | ------------------------------------ | ------------- | ------------------------------------------------------------------------------------------- |
+| `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                                                                            |
+| `environment`      | `string`                             | auto-detected | Override environment (development, ci, production)                                          |
+| `environments`     | `Record<string, EnvironmentConfig>`  | -             | Environment-specific tool configurations                                                    |
+
+**EnvironmentConfig:**
+
+```typescript
+interface EnvironmentConfig {
+  tools: string[]
+}
+```
 
-## Bundled Tools
+## Tool Resolution
 
-All tools are included as dependencies — zero extra setup:
+The library intelligently resolves tools in this order:
 
-| 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 |
+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
+
+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 +346,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 +397,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/index.d.ts

@@ -1,49 +1,60 @@
+export interface EnvironmentConfig {
+  tools: string[]
+}
+
 export interface CodeQualityOptions {
   /** Load environment variables from .env file (default: true) */
-  loadEnv?: boolean;
+  loadEnv?: boolean
   /** Use project's own config files instead of bundled configs (default: true) */
-  useProjectConfig?: boolean;
+  useProjectConfig?: boolean
   /** Array of tool names to run (default: all tools) */
-  tools?: string[];
+  tools?: string[]
   /** Custom commands for each tool, keyed by tool name */
-  commands?: Record<string, string>;
+  commands?: Record<string, string>
   /** Custom descriptions for each tool, keyed by tool name */
-  descriptions?: Record<string, string>;
+  descriptions?: Record<string, string>
   /** Force a specific package manager (auto-detected if not specified) */
-  packageManager?: 'bun' | 'pnpm' | 'yarn' | 'npm';
+  packageManager?: 'bun' | 'pnpm' | 'yarn' | 'npm'
   /** Show detailed error logs in terminal */
-  showLogs?: boolean;
+  showLogs?: boolean
+  /** Set the active environment (default: development) */
+  environment?: string
+  /** Environment-specific tool configurations */
+  environments?: Record<string, EnvironmentConfig>
 }
 
 export interface CommandResult {
-  success: boolean;
-  output: string;
+  success: boolean
+  output: string
 }
 
 export interface CheckResult {
-  name: string;
-  description: string;
-  success: boolean;
-  output: string;
+  name: string
+  description: string
+  success: boolean
+  output: string
+  errors: number
+  warnings: number
+  errorLines: string[]
 }
 
 export interface QualityCheckResult {
-  success: boolean;
-  message: string;
-  results: CheckResult[];
+  success: boolean
+  message: string
+  results: CheckResult[]
 }
 
 export class CodeQualityChecker {
-  options: Required<Omit<CodeQualityOptions, 'showLogs'>>;
+  options: Required<Omit<CodeQualityOptions, 'showLogs'>>
 
-  constructor(options?: CodeQualityOptions);
+  constructor(options?: CodeQualityOptions)
 
   /** Execute a single shell command and return the result */
-  runCommand(command: string, description: string): CommandResult;
+  runCommand(command: string, description: string): CommandResult
 
   /** Run all configured quality checks */
-  run(options?: { showLogs?: boolean }): Promise<QualityCheckResult>;
+  run(options?: { showLogs?: boolean }): Promise<QualityCheckResult>
 }
 
 /** Convenience function to run quality checks without instantiating the class */
-export function runQualityCheck(options?: CodeQualityOptions): Promise<QualityCheckResult>;
+export function runQualityCheck(options?: CodeQualityOptions): Promise<QualityCheckResult>