@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.