code-quality-lib 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NoonCore
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,385 @@
+# Code Quality Library
+
+[![npm version](https://img.shields.io/npm/v/code-quality-lib)](https://www.npmjs.com/package/code-quality-lib)
+[![CI/CD](https://github.com/NoonCore/code-quality-lib/actions/workflows/ci.yml/badge.svg)](https://github.com/NoonCore/code-quality-lib/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-included-blue)](https://www.typescriptlang.org/)
+
+> A configurable code quality checker for Node.js — auto-detects your package manager and runs **TypeScript**, **ESLint**, **Prettier**, **Knip**, and **Snyk** with all dependencies bundled.
+
+## Features
+
+- **All tools bundled** — no need to install TypeScript, ESLint, Prettier, Knip, or Snyk separately
+- **Auto-detects package manager** — npm, bun, pnpm, yarn
+- **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
+
+```bash
+npm install -D code-quality-lib     # npm
+bun add -D code-quality-lib         # bun
+pnpm add -D code-quality-lib        # pnpm
+yarn add -D code-quality-lib        # yarn
+```
+
+## Quick Start
+
+```bash
+# 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):
+
+🔧 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 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
+
+```javascript
+const { CodeQualityChecker, runQualityCheck } = require('code-quality-lib')
+
+// Quick — run all checks with defaults (auto-detects project configs)
+const result = await runQualityCheck()
+console.log(result.success ? 'All passed' : 'Some failed')
+
+// Advanced — custom configuration
+const customChecker = new CodeQualityChecker({
+  environments: {
+    development: { tools: ['ESLint', 'TypeScript'] },
+    ci: { tools: ['ESLint', 'TypeScript', 'Prettier', 'Knip', 'Snyk'] },
+  },
+  packageManager: 'npm',
+  commands: {
+    TypeScript: 'tsc --noEmit',
+    ESLint: 'eslint src/ --ext .ts,.tsx',
+  },
+})
+
+const result = await customChecker.run({ showLogs: true })
+console.log(result.results) // per-tool results array
+```
+
+## Configuration Options
+
+| 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
+
+The library intelligently resolves tools in this order:
+
+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
+
+Automatically detected by lock file presence:
+
+1. `bun.lock` / `bun.lockb` → bun
+2. `pnpm-lock.yaml` → pnpm
+3. `yarn.lock` → yarn
+4. `package-lock.json` → npm
+5. Fallback: checks installed binaries, defaults to npm
+
+## 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).
+
+## Requirements
+
+- **Node.js** >= 18.0.0
+
+## Testing & CI/CD
+
+Tested on every push across 4 runtimes:
+
+- **Node.js 25.x** (npm)
+- **Bun 1.3.x**
+- **pnpm 10.x**
+- **Yarn 4.13.0**
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

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"
+      ]
+    }
+  }
+}