Web Check

Baseline Plugin for GitLab CI/CD

This plugin enforces Google Baseline web compatibility via the web-features NPM package. It scans JS, CSS, and HTML for features outside the chosen baseline year and reports issues inline in GitLab Merge Requests.

Features

• Scans JS, CSS, and HTML for unsupported or disallowed features.
• Supports baseline year, severity, and allow/deny lists.
• Produces web compatibility reports integrated with merge requests.
• Works both file-based (.baseline.config.json) and pipeline-input-based (CI variables).
• Packaged as a CLI (npx @kevinloeffler/web-check) and as a GitLab CI/CD component.
• Dual compatibility: Works with both component inputs and project include variables.
• Robust template syntax: Fixed GitLab CI compatibility issues in v1.0.7.

Setup Instructions

1. Add to Your GitLab CI Pipeline

Create or edit .gitlab-ci.yml in your repository root:

Option 1: Project Include (Recommended)

stages:
  - lint

include:
  - project: 'loefflerlabs/web-check-ci'
    ref: 'v1.0.7'
    file: 'templates/web-check.yml'

variables:
  BASELINE_YEAR: 2024
  SEVERITY: major
  ALLOW: "fetch,css-grid"
  DENY: "document-write"

Option 2: Component Catalog

stages:
  - lint

include:
  - component: loefflerlabs/web-check-ci/templates/[email protected]
    inputs:
      baseline_year: 2024
      severity: major
      allow: "fetch,css-grid"
      deny: "document-write"

2. Configure GitLab Project Settings

1. Navigate to your GitLab project
2. Go to Settings > CI/CD
3. Expand Pipelines section
4. Ensure Auto DevOps is disabled if you're using custom CI
5. Save changes

⚠️ Common Configuration Issues

GitLab Component Path Errors: If you encounter "component path is not supported" or "no function matching 'not'" errors, use the Project Include method instead:

include:
  - project: 'loefflerlabs/web-check-ci'
    ref: 'v1.0.7'
    file: 'templates/web-check.yml'

variables:
  BASELINE_YEAR: 2024
  SEVERITY: major
  ALLOW: "fetch,css-grid"
  DENY: "document-write"

Fixed in v1.0.7:

• ✅ Removed unsupported not function from template syntax
• ✅ Added dual compatibility for both component inputs and project variables
• ✅ Enhanced error handling and template reliability

Component vs Project Include:

• Component method: Uses inputs: for configuration (modern approach)
• Project method: Uses variables: for configuration (more compatible)
• Both methods provide identical functionality and work with the same template

3. View Results

• Pipeline View: See pass/fail status in your pipeline
• Merge Requests: Compatibility issues appear as inline comments
• Code Quality Tab: View all compatibility violations in one place

Configuration Options

Configuration Methods

Web Check supports two configuration approaches that work with the same template:

Component Inputs (Modern):

include:
  - component: loefflerlabs/web-check-ci/templates/[email protected]
    inputs:
      baseline_year: 2024
      severity: major

Project Variables (Compatible):

include:
  - project: 'loefflerlabs/web-check-ci'
    ref: 'v1.0.7'
    file: 'templates/web-check.yml'
variables:
  BASELINE_YEAR: 2024
  SEVERITY: major

Configuration Parameters

| Component Input | Project Variable | Type | Default | Description | Valid Values | |----------------|------------------|------|---------|-------------|--------------| | baseline_year | BASELINE_YEAR | Number | 2025 | Google Baseline year to enforce | 2023, 2024, 2025 | | severity | SEVERITY | String | major | Issue severity level | info, minor, major, blocker | | allow | ALLOW | String | "" | Comma-separated allowed features | Any web feature names | | deny | DENY | String | "" | Comma-separated denied features | Any web feature names | | fail_on_issues | N/A | Boolean | true | Whether to fail pipeline when issues found | true, false |

Example with Custom Parameters

include:
  - component: loefflerlabs/web-check-ci/templates/[email protected]
    inputs:
      baseline_year: 2025
      severity: blocker
      allow: fetch,async-await,css-grid
      deny: document.write,eval
      fail_on_issues: false  # Only warn, don't fail pipeline

CLI Installation

# Install globally for CLI usage
npm install -g @kevinloeffler/web-check

# Or use directly without installation
npx @kevinloeffler/web-check --help

# For project-specific usage
npm install --save-dev @kevinloeffler/web-check

CLI Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | --year <number> | Number | 2023 | Baseline year to enforce | | --severity <level> | String | major | Severity level | | --allow <list> | String | "" | Comma-separated allowed features | | --deny <list> | String | "" | Comma-separated denied features | | -h, --help | Flag | - | Display help information |

Quick Start

Enable baseline web compatibility scanning in one line:

stages:
  - lint

include:
  - component: loefflerlabs/web-check-ci/templates/[email protected]

Optional: override inputs

include:
  - component: loefflerlabs/web-check-ci/templates/[email protected]
    inputs:
      baseline_year: 2025
      severity: blocker
      allow: fetch,async-await
      deny: document.write

Optional: use a repository config file

Add .baseline.config.json to the root of your repo:

{
  "baselineYear": 2024,
  "allow": ["fetch", "css-grid"],
  "deny": ["document.write", "eval"],
  "severity": "major"
}

CLI/pipeline inputs override .baseline.config.json if both are present

Example Project & Testing

This repository includes an example-project/ directory that demonstrates how Web Check works and provides a test environment for trying out different configurations.

What's in the Example Project

The example project contains intentional web compatibility issues:

• Legacy API Usage: document.write() calls that should be flagged when denied
• Modern Features: CSS container-queries and popover API usage for baseline testing
• GitLab CI Integration: A .gitlab-ci.yml file showing component usage
• Various File Types: JavaScript, CSS, and HTML files for comprehensive scanning

How to Use the Example Project

1. Test the CLI locally:

   cd example-project
   npx @kevinloeffler/web-check --year 2024 --severity info

2. Test with deny lists:

   npx @kevinloeffler/web-check --year 2024 --deny "document-write"

3. Test with allow lists:

   npx @kevinloeffler/web-check --year 2024 --allow "popover,css-container-queries"

4. Test the GitLab component: The example project includes a working .gitlab-ci.yml that demonstrates component integration.

Expected Results

When you run Web Check on the example project, you should see:

• Baseline issues for 2025 features when using --year 2024
• Denied feature warnings when using --deny "document-write"
• Clean results when using appropriate --allow lists

This makes it perfect for:

• Testing new versions before release
• Demonstrating the tool to stakeholders
• Learning how configuration options affect results
• Validating CI/CD component integration

Note: The example project is excluded from the main repository's CI scanning to prevent false failures, but remains available for manual testing and documentation.

Local CLI Usage

Install dependencies and run locally:

# Install and use locally
npm install -g @kevinloeffler/web-check
web-check --help

# Or use directly with npx
npx @kevinloeffler/web-check --help

Or pass options directly:

npx @kevinloeffler/web-check --year 2025 --severity blocker --allow fetch --deny document.write

Development & Testing

Run the test suite:

npm test              # Run tests with coverage
npm run test:ci       # Run tests with JUnit output for CI
npm run test:help     # Show CLI help

License

Licensed under the Apache License, Version 2.0. See the LICENSE file for details.