npm package: @promise-inc/web-guard
Description: All-in-one web quality guard. Performance, A11y, SEO, Schema, Security and UX checks in CI and locally.
Latest version: 0.1.0

# @promise-inc/web-guard

All-in-one web quality guard. Enforce Performance, Accessibility, SEO, Schema, Security, and UX standards in CI and locally.

<p align="center">
  <img src="https://raw.githubusercontent.com/promise-inc/web-guard/main/assets/demo.svg" alt="web-guard CLI output demo" width="680" />
</p>

## Why web-guard?

Checking web quality manually across multiple tools is slow and inconsistent. `web-guard` combines six audit pillars into a single CLI and API with:

- **6 pillars in one command** — performance, a11y, seo, schema, security, ux
- **Lighthouse + axe-core** — industry-standard engines under the hood
- **Threshold enforcement** — fail CI if any pillar drops below your standards
- **Presets** — lenient, recommended, and strict configs out of the box
- **Fix hints** — actionable suggestions when a check fails
- **JSON output** — pipe results to dashboards or custom reporters
- **Zero config** — sensible defaults, just pass a URL

## Quick Start

### CLI

```bash
# Run with defaults (all pillars, mobile, score >= 80)
npx web-guard --url https://example.com

# Use a preset
npx web-guard --url https://example.com --preset recommended

# Specific pillars only
npx web-guard --url https://example.com --pillars performance,seo

# Desktop mode
npx web-guard --url https://example.com --device desktop

# JSON output for CI pipelines
npx web-guard --url https://example.com --json

# CI mode (no colors)
npx web-guard --url https://example.com --ci
```

### Programmatic

```typescript
import { runWebGuard } from "@promise-inc/web-guard";

const result = await runWebGuard("https://example.com", {
  preset: "recommended",
  device: "mobile",
});

if (!result.passed) {
  console.log("Quality check failed:", result.pillarResults);
}
```

## CLI Options

| Option | Description | Default |
|--------|-------------|---------|
| `--url <url>` | URL to audit | — |
| `-p, --preset <name>` | Use a built-in preset | — |
| `--device <mobile\|desktop>` | Device emulation | `mobile` |
| `--pillars <list>` | Comma-separated pillars to run | all |
| `--json` | Output as JSON | `false` |
| `--ci` | No colors, clean output | `false` |

## Pillars

| Pillar | Engine | What it checks |
|--------|--------|----------------|
| **performance** | Lighthouse | Score, LCP, CLS, INP, TTFB, FCP |
| **a11y** | axe-core | WCAG violations by impact level |
| **seo** | HTML parsing | Title, meta description, headings, canonical, robots, sitemap |
| **schema** | JSON-LD | Structured data presence, valid JSON, required fields per @type |
| **security** | HTTP headers | CSP, HSTS, X-Frame-Options, Referrer-Policy, Permissions-Policy |
| **ux** | Puppeteer | Viewport meta, image dimensions, touch targets (44x44), font-display |

## Configuration

Create a `web-guard.config.json` (or `.js`/`.ts`) in your project root:

```json
{
  "url": "https://example.com",
  "preset": "recommended",
  "device": "mobile",
  "pillars": ["performance", "a11y", "seo"],
  "performance": {
    "minScore": 85,
    "lcp": 2500,
    "cls": 0.1,
    "inp": 200
  },
  "a11y": {
    "minScore": 90,
    "ignoreSeverities": ["minor"]
  },
  "seo": {
    "minScore": 80
  }
}
```

Or in `package.json`:

```json
{
  "web-guard": {
    "url": "https://example.com",
    "preset": "strict"
  }
}
```

### Config Cascade

Priority (highest to lowest):

1. CLI arguments
2. Config file (`web-guard.config.*`)
3. `package.json` `"web-guard"` field
4. Preset values
5. Defaults

## Presets

| Preset | Pillars | Min Score | Severity Filter |
|--------|---------|-----------|-----------------|
| `lenient` | performance, a11y, seo | 60 | Ignores minor + moderate |
| `recommended` | performance, a11y, seo, schema, security | 80 | Ignores minor |
| `strict` | All 6 pillars | 90 | All severities |

## Default Thresholds (Performance)

Based on [Google's Web Vitals recommendations](https://web.dev/vitals/):

| Metric | Limit | Description |
|--------|-------|-------------|
| LCP | 2500ms | Largest Contentful Paint |
| CLS | 0.1 | Cumulative Layout Shift |
| INP | 200ms | Interaction to Next Paint |
| TTFB | 800ms | Time to First Byte |
| FCP | 1800ms | First Contentful Paint |

## CI / GitHub Actions

```yaml
name: Web Quality Guard

on:
  pull_request:
    branches: [main]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install Chrome
        uses: browser-actions/setup-chrome@v1

      - name: Install dependencies
        run: npm ci

      - name: Run web-guard
        run: npx web-guard --url https://staging.example.com --preset recommended --ci
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | All pillars passed |
| 1 | One or more pillars failed |
| 2 | Runtime error |

## Requirements

- Node.js >= 18
- Chrome/Chromium installed (for Lighthouse and Puppeteer)

## How to report bugs

To report a bug, please first read our guide on [opening issues](https://github.com/promise-inc/web-guard/issues).

## How to contribute code

To open a pull request, please first read our guide on [opening pull requests](https://github.com/promise-inc/web-guard/pulls), which outlines our process for RFCs and pull requests.

## Also by Promise Inc.

| Package | Description |
|---------|-------------|
| [`@promise-inc/ps-guard`](https://github.com/promise-inc/ps-guard) | Lighthouse-based performance guard |
| [`@promise-inc/ai-guard`](https://github.com/promise-inc/ai-guard) | Detect AI-generated code patterns |
| [`@promise-inc/fs-guard`](https://github.com/promise-inc/fs-guard) | Validate project folder and file structure |
| [`@promise-inc/devlog`](https://github.com/promise-inc/devlog) | Logger with automatic context (file + line) |
| [`@promise-inc/ui-states`](https://github.com/promise-inc/ui-states) | Auto-generated skeleton loading states |
| [`@promise-inc/dev-reel`](https://github.com/promise-inc/dev-reel) | Animated SVG previews for READMEs |

---

Developed by [Promise Inc.](https://promise.codes)

## License

MIT © [Promise Inc.](https://promise.codes)