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
To install, run
npx @tessl/cli install tessl/npm-htmlhint@1.6.00
# HTMLHint
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: htmlhint
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install htmlhint`
10
11
## Core Imports
12
13
```typescript
14
import { HTMLHint } from "htmlhint";
15
```
16
17
For CommonJS:
18
19
```javascript
20
const { HTMLHint } = require("htmlhint");
21
```
22
23
Alternative imports for specific components:
24
25
```typescript
26
import { HTMLHint, HTMLRules, Reporter, HTMLParser } from "htmlhint";
27
```
28
29
## Basic Usage
30
31
```typescript
32
import { HTMLHint } from "htmlhint";
33
34
// Basic HTML validation
35
const html = `<html>
36
<head><title>Test</title></head>
37
<body><h1>Hello World</h1></body>
38
</html>`;
39
40
// Validate with default rules
41
const hints = HTMLHint.verify(html);
42
43
if (hints.length > 0) {
44
console.log('Issues found:');
45
hints.forEach(hint => {
46
console.log(`${hint.line}:${hint.col} - ${hint.message} (${hint.rule.id})`);
47
});
48
} else {
49
console.log('No issues found!');
50
}
51
```
52
53
## Architecture
54
55
HTMLHint is built around several key components:
56
57
- **HTMLHint Core**: Main singleton instance providing verification and formatting functionality
58
- **Rule System**: Extensible collection of 42 built-in validation rules with custom rule support
59
- **HTML Parser**: Event-driven parser for processing HTML structures and extracting elements/attributes
60
- **Reporter**: Issue collection and reporting system with multiple severity levels
61
- **CLI Interface**: Command-line tool with file processing, configuration management, and multiple output formats
62
- **Formatter System**: Multiple output formats including JSON, XML, SARIF, HTML, and more
63
64
### Export Structure
65
66
HTMLHint uses a singleton pattern with the following exports:
67
68
- `HTMLHint` - Main singleton instance of HTMLHintCore with all rules pre-loaded
69
- `HTMLRules` - Object containing all built-in rule implementations
70
- `Reporter` - Reporter class for issue collection
71
- `HTMLParser` - HTML parsing class for event-driven processing
72
73
The HTMLHint singleton is created from HTMLHintCore and automatically registers all built-in rules during initialization.
74
75
## Capabilities
76
77
### Core HTML Validation
78
79
Primary HTML validation functionality for analyzing HTML content against configurable rulesets. Supports both synchronous validation and custom rule configurations.
80
81
```typescript { .api }
82
class HTMLHintCore {
83
rules: { [id: string]: Rule };
84
readonly defaultRuleset: Ruleset;
85
86
verify(html: string, ruleset?: Ruleset): Hint[];
87
addRule(rule: Rule): void;
88
format(arrMessages: Hint[], options?: FormatOptions): string[];
89
}
90
91
const HTMLHint: HTMLHintCore;
92
```
93
94
[Core Validation](./core-validation.md)
95
96
### Rule System
97
98
Comprehensive collection of 43+ built-in HTML validation rules covering syntax, semantics, accessibility, and best practices. Supports extensible custom rule development.
99
100
```typescript { .api }
101
interface Rule {
102
id: string;
103
description: string;
104
link?: string;
105
init(parser: HTMLParser, reporter: Reporter, options: unknown): void;
106
}
107
108
interface Ruleset {
109
'tagname-lowercase'?: boolean;
110
'attr-value-double-quotes'?: boolean;
111
'doctype-first'?: boolean;
112
'tag-pair'?: boolean;
113
'id-unique'?: boolean;
114
// ... 38+ more rules
115
[ruleId: string]: unknown;
116
}
117
```
118
119
[Rules and Configuration](./rules-configuration.md)
120
121
### HTML Parsing
122
123
Event-driven HTML parser for processing document structures, extracting elements, attributes, and content with position tracking.
124
125
```typescript { .api }
126
class HTMLParser {
127
lastEvent: Partial<Block> | null;
128
129
parse(html: string): void;
130
addListener(types: string, listener: Listener): void;
131
fire(type: string, data?: Partial<Block>): void;
132
removeListener(type: string, listener: Listener): void;
133
fixPos(event: Block, index: number): { line: number; col: number };
134
getMapAttrs(arrAttrs: Attr[]): { [name: string]: string };
135
}
136
137
type Listener = (event: Block) => void;
138
```
139
140
[HTML Parsing](./html-parsing.md)
141
142
### Issue Reporting
143
144
Structured issue collection and reporting system with multiple severity levels, position tracking, and evidence capture.
145
146
```typescript { .api }
147
class Reporter {
148
html: string;
149
lines: string[];
150
brLen: number;
151
ruleset: Ruleset;
152
messages: Hint[];
153
154
constructor(html: string, ruleset: Ruleset);
155
info(message: string, line: number, col: number, rule: Rule, raw: string): void;
156
warn(message: string, line: number, col: number, rule: Rule, raw: string): void;
157
error(message: string, line: number, col: number, rule: Rule, raw: string): void;
158
}
159
160
interface Hint {
161
type: ReportType;
162
message: string;
163
raw: string;
164
evidence: string;
165
line: number;
166
col: number;
167
rule: Rule;
168
}
169
```
170
171
[Issue Reporting](./issue-reporting.md)
172
173
### Command Line Interface
174
175
Full-featured CLI for batch HTML validation with file globbing, configuration management, multiple output formats, and CI/CD integration support.
176
177
```typescript { .api }
178
interface Formatter extends EventEmitter {
179
getSupported(): string[];
180
init(htmlhint: HTMLHintCore, options: { nocolor?: boolean }): void;
181
setFormat(format: string): void;
182
}
183
184
// Available CLI formatters
185
type SupportedFormats = 'default' | 'json' | 'checkstyle' | 'junit' | 'sarif' | 'html' | 'markdown' | 'compact' | 'unix';
186
```
187
188
[Command Line Interface](./cli-interface.md)
189
190
## Types
191
192
### Core Types
193
194
```typescript { .api }
195
interface FormatOptions {
196
colors?: boolean;
197
indent?: number;
198
}
199
200
enum ReportType {
201
error = "error",
202
warning = "warning",
203
info = "info"
204
}
205
206
interface Attr {
207
name: string;
208
value: string;
209
quote: string;
210
index: number;
211
raw: string;
212
}
213
214
interface Block {
215
tagName: string;
216
attrs: Attr[];
217
type: string;
218
raw: string;
219
pos: number;
220
line: number;
221
col: number;
222
content: string;
223
long: boolean;
224
close: string;
225
lastEvent?: Partial<Block>;
226
}
227
```