laxy-verify 0.1.2 → 1.0.1

package/README.md

@@ -1,163 +1,150 @@
-# laxy-verify
-
-Frontend quality gate for any project. Checks your build and runs a Lighthouse audit — outputs a Silver/Bronze/Unverified grade.
-
-```bash
-npx laxy-verify .
-```
-
-```
-  Laxy Verify — ✅ Silver
-  ========================================
-
-  Build:          PASS (12.3s)
-
-  Lighthouse Scores:
-    Performance:     87  / 70  ✓
-    Accessibility:   92  / 85  ✓
-    SEO:             88  / 80  ✓
-    Best Practices:  90  / 80  ✓
-
-  Grade: Silver
-```
-
-> Want Gold? Gold requires E2E tests on top of build + Lighthouse. Run full verification at [laxy.dev](https://laxy.dev).
-
----
-
-## Install
-
-```bash
-# Run once (no install needed)
-npx laxy-verify .
-
-# Or install globally
-npm install -g laxy-verify
-laxy-verify .
-```
-
----
-
-## Usage
-
-```bash
-laxy-verify [dir] [options]
-
-Arguments:
-  dir                   Project directory (default: current directory)
-
-Options:
-  --format <type>       Output format: console, json, md (default: console)
-  --ci                  CI mode: relaxed thresholds, 3 Lighthouse runs
-  --skip-lighthouse     Build check only, skip Lighthouse
-  --runs <number>       Number of Lighthouse runs
-  --port <number>       Dev server port (default: 3000)
-```
-
-### Examples
-
-```bash
-# Check current directory
-npx laxy-verify .
-
-# Build check only (fast)
-npx laxy-verify . --skip-lighthouse
-
-# CI mode with JSON output
-npx laxy-verify . --ci --format json
-
-# Markdown output (for PR comments)
-npx laxy-verify . --format md
-```
-
----
-
-## Exit Codes
-
-| Code | Meaning |
-|------|---------|
-| `0` | Silver or Gold — all checks passed |
-| `1` | Bronze — build passed, Lighthouse failed (soft fail) |
-| `2` | Unverified — build failed |
-| `3` | Config error — no package.json, no build script |
-
----
-
-## Grades
-
-| Grade | Condition |
-|-------|-----------|
-| ✅ Silver | Build passed + all Lighthouse thresholds met |
-| 🔨 Bronze | Build passed, Lighthouse failed or skipped |
-| ⚠️ Unverified | Build failed |
-
-> 🏆 **Gold** requires E2E tests. Use [Laxy](https://laxy.dev) for full Gold verification.
-
----
-
-## GitHub Action
-
-Add this to `.github/workflows/verify.yml`:
-
-```yaml
-name: Laxy Verify
-
-on:
-  pull_request:
-
-jobs:
-  verify:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: psungmin24/laxy-verify@v1
-        with:
-          format: md
-```
-
-On every PR, laxy-verify will:
-1. Run `npm run build`
-2. Start your dev server and run Lighthouse
-3. Post a comment with the grade and scores
-
-### Action Inputs
-
-| Input | Default | Description |
-|-------|---------|-------------|
-| `node-version` | `20` | Node.js version |
-| `skip-lighthouse` | `false` | Build check only |
-| `format` | `md` | Output format |
-
----
-
-## Configuration
-
-Create `.laxy.yml` in your project root to customize thresholds:
-
-```yaml
-thresholds:
-  performance: 70
-  accessibility: 85
-  seo: 80
-  bestPractices: 80
-
-port: 3000
-runs: 1
-```
-
----
-
-## Supported Frameworks
-
-Automatically detects and runs the right build command:
-
-- **Next.js** — `next build`
-- **Vite** — `vite build`
-- **Create React App** — `react-scripts build`
-- **Custom** — reads `scripts.build` from `package.json`
-
----
-
-## License
-
-MIT
+# laxy-verify
+
+Frontend quality gate for AI-generated code. Build + Lighthouse verification with grade output (Gold/Silver/Bronze/Unverified).
+
+```bash
+npx laxy-verify --init    # Auto-detect framework, generate config
+npx laxy-verify .         # Run verification
+npx laxy-verify --badge   # Show shields.io badge
+```
+
+## Quick Start
+
+### 1. Initialize
+
+```bash
+cd your-project
+npx laxy-verify --init
+```
+
+This generates `.laxy.yml` and `.github/workflows/laxy-verify.yml` automatically by detecting your framework and package manager.
+
+### 2. Run Locally
+
+```bash
+npx laxy-verify .
+```
+
+### 3. Add to CI
+
+Push the generated workflow file. Every PR gets a quality gate with grade comment and status check.
+
+## Grades
+
+| Grade | Requirement |
+|-------|------------|
+| **Silver** | Build passes + Lighthouse exceeds all thresholds |
+| **Bronze** | Build passes (Lighthouse not run or below threshold) |
+| **Unverified** | Build failed |
+
+`fail_on` controls the minimum acceptable grade. Default: `bronze`.
+
+## Configuration
+
+All fields optional in `.laxy.yml`:
+
+```yaml
+framework: "auto"           # auto | nextjs | vite | cra | sveltekit
+build_command: ""           # default: auto-detected from package.json
+dev_command: ""             # default: auto-detected
+package_manager: "auto"     # auto | npm | pnpm | yarn | bun
+port: 3000                  # dev server port
+build_timeout: 300          # seconds (default 5m)
+dev_timeout: 60             # seconds for dev server start (90 in CI mode)
+lighthouse_runs: 1          # @lhci/cli runs (CI mode auto-sets to 3)
+
+thresholds:
+  performance: 70           # CI mode applies -10 offset (effective: 60)
+  accessibility: 85
+  seo: 80
+  best_practices: 80
+
+fail_on: "bronze"           # unverified | bronze | silver | gold
+                            # unverified = never fail (informational only)
+```
+
+**fail_on vs build failure:** Build failure always produces grade `Unverified` and exit code 1, regardless of `fail_on`. `fail_on: unverified` means informational only (always exit 0).
+
+**--ci flag:** Lowers Performance threshold by 10, sets `lighthouse_runs=3` (when not explicitly set), and increases `dev_timeout` to 90s. Auto-set when `CI=true` env var exists.
+
+## CLI Options
+
+```
+npx laxy-verify [project-dir]   Default: current directory
+
+Options:
+  --format   console | json       Output format (default: console)
+  --ci                            CI mode: -10 Performance, runs=3
+  --config   <path>               Path to .laxy.yml
+  --fail-on  unverified|bronze|silver|gold  Override fail_on
+  --skip-lighthouse               Build-only verification (max Bronze)
+  --badge                         Show shields.io badge (reads .laxy-result.json)
+  --init                          Generate .laxy.yml + GitHub workflow
+```
+
+## exit codes
+
+| Code | Meaning |
+|------|--------|
+| 0 | Grade meets or exceeds `fail_on` threshold |
+| 1 | Grade worse than `fail_on`, or build failed |
+| 2 | Configuration error (no package.json, invalid YAML, etc.) |
+
+## GitHub Action
+
+```yaml
+- uses: psungmin24/laxy-verify@v1
+  with:
+    github-token: ${{ secrets.GITHUB_TOKEN }}
+    fail-on: silver    # optional, default: bronze
+    config: .laxy.yml  # optional
+```
+
+Posts a PR comment with grade and Lighthouse scores, and sets a commit status check.
+
+## Limitations (v1)
+
+- **Monorepos:** Not supported. Run `npx laxy-verify apps/web` for the app subdirectory.
+- **Lighthouse accuracy:** Scores are measured in dev mode (`npm run dev`). Production scores are typically higher.
+- **Fork PRs:** Comments and status checks are not posted on PRs from forks (GitHub security restriction).
+- **Yarn Berry:** May require manual `package_manager` configuration if using Corepack.
+
+## Expected CI Timing
+
+- Build: 15-30s
+- Dev server start: 5-20s
+- Lighthouse (1 run): ~15s
+- Lighthouse (3 runs CI): ~45s
+- **Total: 35-95s per PR**
+
+## .laxy-result.json
+
+Written after every run:
+
+```json
+{
+  "grade": "Silver",
+  "timestamp": "2026-04-07T10:30:00Z",
+  "build": { "success": true, "durationMs": 12300, "errors": [] },
+  "lighthouse": { "performance": 87, "accessibility": 92, "seo": 88, "bestPractices": 90, "runs": 1 },
+  "thresholds": { "performance": 70, "accessibility": 85, "seo": 80, "bestPractices": 80 },
+  "ciMode": false,
+  "framework": "nextjs",
+  "exitCode": 0,
+  "config_fail_on": "bronze"
+}
+```
+
+Use `npx laxy-verify --badge` to output a shields.io badge markdown from this file.
+
+## Badge
+
+```bash
+npx laxy-verify --badge
+```
+
+Output: `![Laxy Verify: Silver](https://img.shields.io/badge/laxy_verify-silver-brightgreen)`
+
+## License
+
+MIT

package/dist/badge.d.ts

@@ -0,0 +1 @@
+export declare function generateBadge(grade: string): string;

package/dist/badge.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateBadge = generateBadge;
+function generateBadge(grade) {
+    const gradeLower = grade.toLowerCase();
+    const colors = {
+        gold: "yellow",
+        silver: "brightgreen",
+        bronze: "blue",
+        unverified: "lightgrey",
+    };
+    const color = colors[gradeLower] ?? "lightgrey";
+    return `![Laxy Verify: ${grade}](https://img.shields.io/badge/laxy_verify-${gradeLower}-${color})`;
+}

package/dist/build.d.ts

@@ -0,0 +1,11 @@
+export interface BuildResult {
+    success: boolean;
+    durationMs: number;
+    errors: string[];
+}
+export declare class BuildError extends Error {
+    errors: string[];
+    timedOut: boolean;
+    constructor(message: string, errors: string[], timedOut?: boolean);
+}
+export declare function runBuild(command: string, timeoutSec: number): Promise<BuildResult>;

package/dist/build.js

@@ -0,0 +1,67 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BuildError = void 0;
+exports.runBuild = runBuild;
+const node_child_process_1 = require("node:child_process");
+const tree_kill_1 = __importDefault(require("tree-kill"));
+class BuildError extends Error {
+    errors;
+    timedOut;
+    constructor(message, errors, timedOut = false) {
+        super(message);
+        this.errors = errors;
+        this.timedOut = timedOut;
+        this.name = "BuildError";
+    }
+}
+exports.BuildError = BuildError;
+function runBuild(command, timeoutSec) {
+    return new Promise((resolve, reject) => {
+        const startTime = Date.now();
+        const stderrLines = [];
+        const errorLines = [];
+        console.log(`\n Building: ${command}`);
+        const proc = (0, node_child_process_1.spawn)(command, { shell: true, stdio: ["ignore", "pipe", "pipe"] });
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            if (proc.pid) {
+                (0, tree_kill_1.default)(proc.pid, "SIGKILL");
+            }
+            reject(new BuildError(`Build timed out after ${timeoutSec}s`, errorLines, true));
+        }, timeoutSec * 1000);
+        proc.stdout?.on("data", (chunk) => {
+            // Print build output to console
+            const lines = chunk.toString().split("\n").filter(Boolean);
+            for (const line of lines) {
+                console.log(`  ${line}`);
+            }
+        });
+        proc.stderr?.on("data", (chunk) => {
+            const text = chunk.toString();
+            const lines = text.split("\n").filter(Boolean);
+            stderrLines.push(...lines);
+            errorLines.push(...lines);
+            for (const line of lines) {
+                console.error(`  ${line}`);
+            }
+        });
+        proc.on("exit", (code) => {
+            clearTimeout(timer);
+            const durationMs = Date.now() - startTime;
+            const success = code === 0;
+            resolve({
+                success,
+                durationMs,
+                errors: success ? [] : errorLines,
+            });
+        });
+        proc.on("error", (err) => {
+            clearTimeout(timer);
+            reject(new BuildError(`Build process failed: ${err.message}`, errorLines));
+        });
+    });
+}