@promise-inc/web-guard

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

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

# 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

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:

{
  "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:

{
  "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:

| 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

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.

How to contribute code

To open a pull request, please first read our guide on opening pull requests, which outlines our process for RFCs and pull requests.

Also by Promise Inc.

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

Developed by Promise Inc.

License

MIT © Promise Inc.