npm package: @kevinloeffler/web-check
Description: This plugin enforces [Google Baseline](https://web.dev/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.
Author: Kevin Loeffler
Latest version: 1.0.8

# Web Check

<div align="center">
  <img src="https://gitlab.com/loefflerlabs/web-check-ci/-/raw/main/assets/logo.png?ref_type=heads" alt="Web Check Logo" width="300"/>
</div>

[![Pipeline Status](https://gitlab.com/loefflerlabs/web-check-ci/badges/main/pipeline.svg)](https://gitlab.com/loefflerlabs/web-check-ci/-/pipelines)
[![Coverage Report](https://gitlab.com/loefflerlabs/web-check-ci/badges/main/coverage.svg)](https://gitlab.com/loefflerlabs/web-check-ci/-/graphs/main/charts)
[![NPM Version](https://img.shields.io/npm/v/@kevinloeffler/web-check.svg)](https://www.npmjs.com/package/@kevinloeffler/web-check)
[![NPM Downloads](https://img.shields.io/npm/dm/@kevinloeffler/web-check.svg)](https://www.npmjs.com/package/@kevinloeffler/web-check)

## Baseline Plugin for GitLab CI/CD

This plugin enforces [Google Baseline](https://web.dev/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)**
```yaml
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**
```yaml
stages:
  - lint

include:
  - component: loefflerlabs/web-check-ci/templates/web-check.yml@v1.0.7
    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:

```yaml
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):**
```yaml
include:
  - component: loefflerlabs/web-check-ci/templates/web-check.yml@v1.0.7
    inputs:
      baseline_year: 2024
      severity: major
```

**Project Variables (Compatible):**
```yaml
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

```yaml
include:
  - component: loefflerlabs/web-check-ci/templates/web-check.yml@v1.0.7
    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

```bash
# 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:

```yaml
stages:
  - lint

include:
  - component: loefflerlabs/web-check-ci/templates/web-check.yml@v1.0.7
```

## Optional: override inputs

```yaml
include:
  - component: loefflerlabs/web-check-ci/templates/web-check.yml@v1.0.7
    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:

```json
{
  "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**:
   ```bash
   cd example-project
   npx @kevinloeffler/web-check --year 2024 --severity info
   ```

2. **Test with deny lists**:
   ```bash
   npx @kevinloeffler/web-check --year 2024 --deny "document-write"
   ```

3. **Test with allow lists**:
   ```bash
   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:

```bash
# 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:

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

# Development & Testing

Run the test suite:

```bash
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](LICENSE) file for details.