Skip to content
CAI
Software that uses CAICheck a score

gjtorikian/html-proofer

60.1

Adequate · 6 November 2026

2.1k

lines of production code

Ruby

primary language

4

measurements over time

CAI band scale
CAI trend line
CAI lens gauges

What this system is

HTMLProofer is a Ruby gem that validates HTML files and directories for broken links, missing images, and accessibility issues. It provides a command-line interface and a programmatic API to check internal and external resources, including support for hash anchors, PDFs, and Open Graph tags. The system features asynchronous processing, configurable caching, and detailed reporting to help developers maintain link integrity and code quality.

How it got here

2013–2015 — Initial project scaffolding and test expansion

14 changes.

This period established the foundational structure of the html-proofer gem, including project configuration, dependency management, and development tooling. It focused heavily on building a robust test infrastructure by introducing Zeitwerk-based autoloading, local HTTP server helpers, and extensive HTML fixtures to validate links, images, scripts, and other web elements.

2016–2021 — v5.2.2 architectural overhaul

12 changes.

This period focused on a major architectural shift in HTML Proofer, introducing asynchronous processing, granular caching, and a dedicated CLI entry point. The codebase was refactored to use specific check classes for HTML elements and a new URL attribute handler, significantly enhancing internal and external link validation, including hash and PDF anchor support. Comprehensive test fixtures were added to cover these new behaviors and edge cases.

2022–2026 — CLI implementation and test expansion

10 changes.

This period focused on establishing the command-line interface by adding an executable entry point and a structured terminal reporter for failure output. Concurrently, the project significantly expanded its test coverage by introducing comprehensive fixtures and RSpec suites for core validation checks, caching mechanisms, and edge cases involving hash fragments and non-ASCII characters.

Features

Add Bundler binstub and structured terminal reporting for HTMLProofer

The project now includes a \bin/bundle\ binstub that ensures the correct Bundler version is activated based on the Gemfile.lock or CLI arguments, providing a consistent environment for running Bundler commands. Additionally, a new \lib/html\_proofer/reporter/terminal.rb\ reporter has been added, which formats HTMLProofer check failures into a structured, human-readable log output that includes the check name, file path, line number, description, and HTTP status code for each failure.

_bin, lib/html\proofer/reporter · high confidence

Added bootstrap and console helper scripts

New shell scripts have been added to the project to streamline local development setup and interaction. The \script/bootstrap\ script installs Ruby gems using Bundler, while \script/console\ leverages the bootstrap script to ensure dependencies are present before launching the interactive Ruby console.

script · high confidence

Executable entry point for HTMLProofer CLI

A new executable script at exe/htmlproofer has been added to allow users to run the HTMLProofer tool directly from the command line. This script initializes the CLI, executes the checks, and prints the total execution time to the console before exiting with the appropriate status code.

exe · high confidence

Initial project scaffolding and configuration

Establishes the foundational project structure by adding the MIT license, a Code of Conduct, and a CODEOWNERS file. Configures the development environment with a \.ruby-version\ file specifying Ruby 3.3.0, a \.rubocop.yml\ for code style enforcement (inheriting from rubocop-standard and using rubocop-rspec), and a \.gitignore\ to exclude build artifacts and IDE files. Includes a \Rakefile\ to automate testing (\spec\), linting (\rubocop\), and README validation, alongside an \UPGRADING.md\ guide for migrating from v3.x to v4.x.

(repo-wide) · high confidence

Behavioural changes

The external URL validator now performs hash checks on external links by default (previously optional), meaning links with fragment identifiers are verified to exist on the target page. It also adds specific support for validating PDF hash links (e.g., \\#page=1\) by reading the PDF content. Additionally, the validator now handles servers that do not support HEAD requests by falling back to GET, and protects against responses lacking a Content-Type header.

_lib/html\_proofer/url\validator · high confidence

HTML Proofer v5.2.2: Async processing, granular caching, and enhanced failure reporting

HTML Proofer has been updated to version 5.2.2, introducing a major architectural shift to asynchronous file processing for improved performance. The tool now features a robust caching system that supports configurable timeframes for both internal and external links, allowing users to skip re-checking URLs that haven't changed within a specified period. Failure reporting has been enhanced to include full Nokogiri node access and element attributes, providing more context for debugging broken links. Additionally, the CLI now accepts regular expressions for the \--ignore-files\ option, and the default behavior for checking external hashes has been enabled.

_lib/html\proofer · high confidence

Introduction of Zeitwerk-based autoloading and simplified public API

The library now uses Zeitwerk for automatic constant loading, replacing the previous manual require structure. This change introduces a cleaner public API with dedicated entry points: \check\_file\ for single files, \check\_directory\ for a single directory, \check\_directories\ for multiple directories, and \check\_links\ for a list of URLs. The previous \check\ method has been removed in favor of these more specific methods, and the internal runner is now instantiated directly via these new helpers.

lib · high confidence

New CLI entry point and enhanced internal link hash validation

The tool now includes a dedicated CLI class (\lib/html\_proofer/cli.rb\) that parses command-line arguments and dispatches checks for files, directories, or raw link lists. Additionally, internal link validation has been significantly improved: the system now checks for the existence of URL fragments (hashes) within target files by default, using robust XPath queries that handle special characters like single quotes, and provides detailed failure messages when a file exists but the specific anchor is missing.

html-proofer · high confidence

New URL attribute class with improved path resolution and extension handling

A new \HTMLProofer::Attribute::Url\ class has been introduced to handle URL attributes, replacing previous inline logic. This change adds support for resolving directory index files (checking multiple configured index names when a directory is linked), handles extensionless URLs by applying an assumed extension, and correctly preserves trailing slashes for directory paths during existence checks. It also introduces logic to ignore protocol-relative URLs and supports extracting file size from the attribute string.

_lib/html\proofer/attribute · high confidence

New dedicated check classes for HTML elements

HTMLProofer now uses dedicated check classes (Favicon, Images, Links, OpenGraph, Scripts) to validate specific HTML elements. This refactoring introduces stricter validation for protocol-relative URLs (flagged as errors requiring explicit https://), adds Subresource Integrity (SRI) and CORS checks for external scripts and stylesheets, and improves handling of image srcsets and alt attributes.

_lib/html\proofer/check · high confidence

Test coverage

Added Open Graph test fixtures for image and URL validation; Added test coverage for Favicon, Image, Link, Open Graph, and Script checks; Added test fixture for Open Graph internal links; Added test fixture for anchor links with non-ASCII characters; Added test fixture for folder.html link validation; Added test fixture for hash link validation; Added test fixture for implicit internal link with hash; Added test fixture for root slash link handling; Added test fixture for version 2.1.0 blog post; Added test fixtures for HTML proofer link hashing; Added test fixtures for PHP file handling; Added test fixtures for favicon validation scenarios; Added test fixtures for hash validation on index URLs; Added test fixtures for internal link validation; Added test fixtures for nested relative images and Japanese language attributes; Added test fixtures for relative link resolution in subdirectories; Added test fixtures for script integrity and CORS validation; Added tests for URL attribute handling; Added tests for the terminal reporter; Added version 2 cache fixture files for link-proofer tests; Enhanced test infrastructure with local HTTP server and improved fixtures; Expanded HTML fixture coverage for validation edge cases; Expanded link validation test fixtures; Expanded test coverage for HTML-Proofer core components; Expanded test fixtures for image validation edge cases.

Dependencies

Initial gem release with Ruby 3.1+ support and modern dependencies

This change introduces the \html-proofer\ gem specification and development environment, establishing the project as a distributable Ruby gem. It enforces a minimum Ruby version of 3.1 (and less than 5.0) and defines runtime dependencies including \nokogiri\ (\~\> 1.13), \typhoeus\ (\~\> 1.3), \addressable\ (\~\> 2.3), and \async\ (\~\> 2.1). The development setup includes \rubocop\ for linting, \rspec\ for testing, and \vcr\ for HTTP mocking, while the gem itself provides an executable named \htmlproofer\ to validate HTML output for broken links, images, and accessibility issues.

(dependencies) · high confidence

Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

How this codebase got here

Score

  • CAI 61 → 60 (-0.8)
  • Rubric changed (rubric-2026.10.5 → rubric-2026.11.2) — scores are not directly comparable.

Lenses

  • Code Health 63 → 63 (+0.0)
  • Architecture 94 → 94 (+0.0)
  • Maturity 51 → 55 (+3.1)
  • Readiness 72 → 72 (+0.0)
  • Security 73 → 59 (-13.5)

Resolved (3)

  • Inconsistent naming for entry points based on input type. While descriptive, the mix of singular/plural nouns and specific vs generic terms (file vs directory vs links) creates a fragmented public API surface. Users must memorize which method corresponds to which input structure.
  • Internal Runner methods have overlapping responsibilities and unclear boundaries. check_files and process_files likely perform similar traversal logic, while check_list_of_links is a specific validation step. This suggests internal refactoring or clearer separation of concerns in the public-facing Runner interface if these are exposed.
  • Off-boarding risk: anonymized user #1

New (1)

  • Off-boarding risk: anonymized user #1

Architecture

  • Unchanged — 0 containers · 1 contexts · 0 edges

Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

Survey your own repository

gjtorikian/html-proofer was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.

About this page

  • The score is its most recent published measurement, taken on 6 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
  • Measured at commit 9357d77c19c1454dedd8d3fa9f46a7baada4ba34 — the exact code this score is about.
  • Scored under rubric-2026.11.2 — the same rubric and the same method as every other entry in this index.
  • Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.2+preprod-5c4e66d9318b.