@site-os/check

@site-os/check

Fork notice. This package is a hard fork of Cap-go/seo-checker by Capgo (MIT, with permission), used as the foundation for siteOS. Upstream remains the canonical static SEO checker; this fork extends it with remote URL crawling, a local server spawn mode, and dashboard integration. See LICENSE for dual copyright.

OSS SEO checker for static sites and CI pipelines. Performs comprehensive SEO analysis with ~250 wired rules (from a catalog of 1274 — see CHECKS.md for the live list) covering metadata, content quality, accessibility, structured data, and more. The static --dist mode inherited from upstream is preserved; remote URL crawling and --start modes are being added on top.

Inspired by Ahrefs SEO Audit and Lighthouse SEO audits.

Installation

npm install @site-os/check
# or
bun add @site-os/check

CLI Usage

# Run with default settings (scans ./dist)
npx @site-os/check

# Specify dist path
npx @site-os/check --dist ./build

# Output as JSON
npx @site-os/check --output json

# Generate a sample config file
npx @site-os/check --generate-config

CLI Options

Option	Description	Default
--dist <path>	Path to dist folder	./dist
--config <path>	Path to config file	siteos-check.config.json
--output <format>	Output format: console, json, sarif, github	console
--report <path>	Path to write report file	-
--fail-on <level>	Fail on: error, warning, notice	error
--max-issues <n>	Maximum issues before stopping	0 (unlimited)
--generate-config	Generate a sample config file	-

Configuration

Create a siteos-check.config.json file:

{
  "distPath": "./dist",
  "baseUrl": "https://example.com",
  "languages": ["en", "es", "fr"],
  "defaultLanguage": "en",
  "rules": {
    "disabled": ["SEO00186", "SEO00189"],
    "severityOverrides": {
      "SEO00135": "notice"
    }
  },
  "exclusions": [
    {
      "ruleId": "SEO00147",
      "filePath": "404.html",
      "reason": "404 page intentionally has broken link examples"
    }
  ],
  "failOn": ["error"],
  "maxIssues": 0,
  "outputFormat": "console"
}

Programmatic Usage

import {
  checkDuplicates,
  printReport,
  runPageChecks,
  scanDistFolder
} from '@site-os/check'

const config = {
  distPath: './dist',
  baseUrl: 'https://example.com',
  languages: ['en'],
  defaultLanguage: 'en',
}

// Scan the dist folder
const siteData = await scanDistFolder(config)

// Run checks on each page
const issues = []
for (const page of siteData.pages.values()) {
  issues.push(...runPageChecks(page, config, siteData))
}

// Check for duplicates
issues.push(...checkDuplicates(siteData, config))

console.log(`Found ${issues.length} SEO issues`)

Rules Categories

The checker wires ~250 rules (exact list in CHECKS.md, generated from the catalog's wired flag) across these categories:

• Metadata: Title, description, canonical, charset, lang
• Content Length: Title/description/heading length limits
• Content Format: Whitespace, encoding, caps, punctuation
• Headings: H1 presence, hierarchy, duplicates
• Indexability: Robots directives, canonical issues
• Links: Broken links, anchor text, nofollow usage
• Images: Alt text, file size, broken references
• Social Tags: OpenGraph, Twitter cards
• International SEO: Hreflang, lang attributes
• Structured Data: JSON-LD validation
• Accessibility: Landmarks, skip links, ARIA
• Robots.txt & Sitemap: Validation and consistency

Output Formats

Console (default)

Colored terminal output grouped by category with severity indicators.

JSON

Machine-readable JSON with all issues and statistics.

SARIF

Static Analysis Results Interchange Format for CI/CD integration.

GitHub

GitHub Actions workflow commands format. Issues appear as annotations in the PR/commit view.

# Use in GitHub Actions
npx @site-os/check --output github

Example workflow:

- name: SEO Check
  run: npx @site-os/check --output github --fail-on error,warning

License

MIT — see LICENSE for dual copyright (Capgo for original work, Vincent Ventalon for modifications).