or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli-interface.mdcore-validation.mdhtml-parsing.mdindex.mdissue-reporting.mdrules-configuration.md
tile.json

tessl/npm-htmlhint

HTMLHint is a comprehensive static analysis tool specifically designed for HTML code quality assurance and validation.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/htmlhint@1.6.x

To install, run

npx @tessl/cli install tessl/npm-htmlhint@1.6.0

index.mddocs/

HTMLHint

HTMLHint is a comprehensive static analysis tool specifically designed for HTML code quality assurance and validation. It provides developers with automated HTML linting capabilities through both command-line interface and programmatic API, offering extensive rule-based validation for HTML syntax, semantics, accessibility, and best practices.

Package Information

  • Package Name: htmlhint
  • Package Type: npm
  • Language: TypeScript
  • Installation: 
    npm install htmlhint

Core Imports

import { HTMLHint } from "htmlhint";

For CommonJS:

const { HTMLHint } = require("htmlhint");

Alternative imports for specific components:

import { HTMLHint, HTMLRules, Reporter, HTMLParser } from "htmlhint";

Basic Usage

import { HTMLHint } from "htmlhint";

// Basic HTML validation
const html = `<html>
  <head><title>Test</title></head>
  <body><h1>Hello World</h1></body>
</html>`;

// Validate with default rules
const hints = HTMLHint.verify(html);

if (hints.length > 0) {
  console.log('Issues found:');
  hints.forEach(hint => {
    console.log(`${hint.line}:${hint.col} - ${hint.message} (${hint.rule.id})`);
  });
} else {
  console.log('No issues found!');
}

Architecture

HTMLHint is built around several key components:

  • HTMLHint Core: Main singleton instance providing verification and formatting functionality
  • Rule System: Extensible collection of 42 built-in validation rules with custom rule support
  • HTML Parser: Event-driven parser for processing HTML structures and extracting elements/attributes
  • Reporter: Issue collection and reporting system with multiple severity levels
  • CLI Interface: Command-line tool with file processing, configuration management, and multiple output formats
  • Formatter System: Multiple output formats including JSON, XML, SARIF, HTML, and more

Export Structure

HTMLHint uses a singleton pattern with the following exports:

  • HTMLHint
    - Main singleton instance of HTMLHintCore with all rules pre-loaded
  • HTMLRules
    - Object containing all built-in rule implementations
  • Reporter
    - Reporter class for issue collection
  • HTMLParser
    - HTML parsing class for event-driven processing

The HTMLHint singleton is created from HTMLHintCore and automatically registers all built-in rules during initialization.

Capabilities

Core HTML Validation

Primary HTML validation functionality for analyzing HTML content against configurable rulesets. Supports both synchronous validation and custom rule configurations.

class HTMLHintCore {
  rules: { [id: string]: Rule };
  readonly defaultRuleset: Ruleset;
  
  verify(html: string, ruleset?: Ruleset): Hint[];
  addRule(rule: Rule): void;
  format(arrMessages: Hint[], options?: FormatOptions): string[];
}

const HTMLHint: HTMLHintCore;

Core Validation

Rule System

Comprehensive collection of 43+ built-in HTML validation rules covering syntax, semantics, accessibility, and best practices. Supports extensible custom rule development.

interface Rule {
  id: string;
  description: string;
  link?: string;
  init(parser: HTMLParser, reporter: Reporter, options: unknown): void;
}

interface Ruleset {
  'tagname-lowercase'?: boolean;
  'attr-value-double-quotes'?: boolean;
  'doctype-first'?: boolean;
  'tag-pair'?: boolean;
  'id-unique'?: boolean;
  // ... 38+ more rules
  [ruleId: string]: unknown;
}

Rules and Configuration

HTML Parsing

Event-driven HTML parser for processing document structures, extracting elements, attributes, and content with position tracking.

class HTMLParser {
  lastEvent: Partial<Block> | null;
  
  parse(html: string): void;
  addListener(types: string, listener: Listener): void;
  fire(type: string, data?: Partial<Block>): void;
  removeListener(type: string, listener: Listener): void;
  fixPos(event: Block, index: number): { line: number; col: number };
  getMapAttrs(arrAttrs: Attr[]): { [name: string]: string };
}

type Listener = (event: Block) => void;

HTML Parsing

Issue Reporting

Structured issue collection and reporting system with multiple severity levels, position tracking, and evidence capture.

class Reporter {
  html: string;
  lines: string[];
  brLen: number;
  ruleset: Ruleset;
  messages: Hint[];
  
  constructor(html: string, ruleset: Ruleset);
  info(message: string, line: number, col: number, rule: Rule, raw: string): void;
  warn(message: string, line: number, col: number, rule: Rule, raw: string): void;
  error(message: string, line: number, col: number, rule: Rule, raw: string): void;
}

interface Hint {
  type: ReportType;
  message: string;
  raw: string;
  evidence: string;
  line: number;
  col: number;
  rule: Rule;
}

Issue Reporting

Command Line Interface

Full-featured CLI for batch HTML validation with file globbing, configuration management, multiple output formats, and CI/CD integration support.

interface Formatter extends EventEmitter {
  getSupported(): string[];
  init(htmlhint: HTMLHintCore, options: { nocolor?: boolean }): void;
  setFormat(format: string): void;
}

// Available CLI formatters
type SupportedFormats = 'default' | 'json' | 'checkstyle' | 'junit' | 'sarif' | 'html' | 'markdown' | 'compact' | 'unix';

Command Line Interface

Types

Core Types

interface FormatOptions {
  colors?: boolean;
  indent?: number;
}

enum ReportType {
  error = "error",
  warning = "warning",
  info = "info"
}

interface Attr {
  name: string;
  value: string;
  quote: string;
  index: number;
  raw: string;
}

interface Block {
  tagName: string;
  attrs: Attr[];
  type: string;
  raw: string;
  pos: number;
  line: number;
  col: number;
  content: string;
  long: boolean;
  close: string;
  lastEvent?: Partial<Block>;
}