@html-validate/plugin-utils`

Plugin utilities and helpers for writing plugins to HTML-Validate

API

import { Source } from "html-validate";

export interface Position {
  column: number;
  line: number;
}

export function positionFromOffset(text: string, offset: number): [line: number, column: number];

export function positionToOffset(position: Position, data: string): number;

export class TemplateExtractor {
  static fromString(source: string, filename?: string): TemplateExtractor;
  extractObjectProperty(key: string): Source[];
}

Usage

TemplateExtractor

Extracts HTML-snippets from Javascript based files.

/* javascript with HTML in the "template" property */
const sourceCode = `
  export default {
    template: "<p>lorem ipsum</i>",
  }
`;

/* extract HTML snippets */
const templateExtractor = TemplateExtractor.fromString(sourceCode);
const snippets = templateExtractor.extractObjectProperty("template");

Typically used in a transformation plugin to but it could also be validated directly:

for (const snippet of snippets) {
  const result = htmlvalidate.validateSource(snippet);
  console.log(result);
}

Test utils

normalizeReport

Normalizes a report so it is suitable for unittesting:

• filePath is normalized to a path relative to rootDir.
• fixable{Error,Warning}Count is reset to 0.

The version option should be the version of html-validate the original report was generated. The returned report is updated to the latest supported version.

Syntax

import { type Result } from "html-validate";

function normalizeReport(
  report: Report,
  options: {
    rootDir: string;
    version: string;
  },
): Report;

Parameters

• report the original report.
• options.rootDir - path to rewrite report paths to be relative to.
• options.version - the version of html-validate that was used to generate the report.

Return value

A normalized copy of the report.

runCli

Run the html-validate CLI, typically for an integration test.

The CLI is run in a child process and the report is read from a separate file descriptor so it is not mixed with stdout.

Syntax

import { type Report } from "html-validate";

function runCli(options: {
  cliPath: string;
  cwd: string;
  args: string[];
  formatter: "json";
}): Promise<{
  exitCode: number;
  stdout: string;
  stderr: string;
  report: string;
  json(): Report;
}>;

Parameters

• options.cliPath - resolved path to the html-validate binary (e.g. bin/html-validate.mjs).
• options.cwd - working directory to run the CLI in.
• options.args - additional CLI arguments, e.g. the files to validate.
• options.formatter - formatter used for the report, currently only "json" is supported.

Return value

A promise resolving to an object with:

• exitCode - the exit code of the process.
• stdout - captured standard output.
• stderr - captured standard error.
• report - the raw report as a string.
• json() - parses report and returns it as an object.

The promise is rejected if the process fails to start or is terminated by a signal.

Example

import path from "node:path";
import { runCli } from "@html-validate/plugin-utils/test-utils";

const pkg = require.resolve("html-validate/package.json");
const cliPath = path.join(path.dirname(pkg), "bin/html-validate.mjs");

const result = await runCli({
  cliPath,
  cwd: "path/to/project",
  args: ["src/index.html"],
  formatter: "json",
});
expect(result.exitCode).toBe(0);
expect(result.json().valid).toBe(true);