html-validate 7.18.0 → 8.0.0

package/dist/types/browser.d.ts

@@ -144,10 +144,10 @@ export declare class Config {
     private config;
     private configurations;
     private initialized;
+    private resolvers;
     private metaTable;
     private plugins;
     private transformers;
-    private rootDir;
     /**
      * Create a new blank configuration. See also `Config.defaultConfig()`.
      */
@@ -155,7 +155,7 @@ export declare class Config {
     /**
      * Create configuration from object.
      */
-    static fromObject(options: ConfigData, filename?: string | null): Config;
+    static fromObject(resolvers: Resolver | Resolver[], options: ConfigData, filename?: string | null): Config;
     /* Excluded from this release type: fromFile */
     /* Excluded from this release type: validate */
     /**
@@ -183,10 +183,9 @@ export declare class Config {
      * @public
      * @param rhs - Configuration to merge with this one.
      */
-    merge(rhs: Config): Config;
+    merge(resolvers: Resolver[], rhs: Config): Config;
     private extendConfig;
     /* Excluded from this release type: getMetaTable */
-    /* Excluded from this release type: expandRelative */
     /* Excluded from this release type: get */
     /* Excluded from this release type: getRules */
     private static getRulesObject;
@@ -229,9 +228,6 @@ export declare class Config {
      */
     private getUnnamedTransformerFromPlugin;
     private getTransformerFromModule;
-    /* Excluded from this release type: rootDirCache */
-    /* Excluded from this release type: rootDirCache */
-    /* Excluded from this release type: findRootDir */
 }
 
 /**
@@ -287,16 +283,6 @@ export declare class ConfigError extends UserError {
     constructor(message: string, nested?: Error);
 }
 
-/**
- * @public
- */
-export declare interface ConfigFactory {
-    defaultConfig(): Config;
-    empty(): Config;
-    fromObject(options: ConfigData, filename?: string | null): Config;
-    fromFile(filename: string): Config;
-}
-
 /**
  * Configuration loader interface.
  *
@@ -306,9 +292,9 @@ export declare interface ConfigFactory {
  * @public
  */
 export declare abstract class ConfigLoader {
-    protected readonly configFactory: ConfigFactory;
+    protected readonly resolvers: Resolver[];
     protected readonly globalConfig: Config;
-    constructor(config?: ConfigData, configFactory?: ConfigFactory);
+    constructor(resolvers: Resolver[], config?: ConfigData);
     /**
      * Get configuration for given handle.
      *
@@ -317,13 +303,10 @@ export declare abstract class ConfigLoader {
      *
      * If [[configOverride]] is set it is merged with the final result.
      *
-     * Returning a [[Config]] instance is deprecated and support will be removed
-     * in the next major release.
-     *
      * @param handle - Unique handle to get configuration for.
      * @param configOverride - Optional configuration to merge final results with.
      */
-    abstract getConfigFor(handle: string, configOverride?: ConfigData): Config | ResolvedConfig;
+    abstract getConfigFor(handle: string, configOverride?: ConfigData): ResolvedConfig;
     /**
      * Flush configuration cache.
      *
@@ -332,6 +315,7 @@ export declare abstract class ConfigLoader {
      * @param handle - If given only the cache for given handle will be flushed.
      */
     abstract flushCache(handle?: string): void;
+    /* Excluded from this release type: _getGlobalConfig */
     /**
      * Default configuration used when no explicit configuration is passed to constructor.
      */
@@ -908,13 +892,29 @@ export declare class HtmlValidate {
      * @param hooks - Optional hooks (see [[Source]]) for definition.
      * @returns Report output.
      */
-    validateString(str: string): Report;
-    validateString(str: string, filename: string): Report;
-    validateString(str: string, hooks: SourceHooks): Report;
-    validateString(str: string, options: ConfigData): Report;
-    validateString(str: string, filename: string, hooks: SourceHooks): Report;
-    validateString(str: string, filename: string, options: ConfigData): Report;
-    validateString(str: string, filename: string, options: ConfigData, hooks: SourceHooks): Report;
+    validateString(str: string): Promise<Report>;
+    validateString(str: string, filename: string): Promise<Report>;
+    validateString(str: string, hooks: SourceHooks): Promise<Report>;
+    validateString(str: string, options: ConfigData): Promise<Report>;
+    validateString(str: string, filename: string, hooks: SourceHooks): Promise<Report>;
+    validateString(str: string, filename: string, options: ConfigData): Promise<Report>;
+    validateString(str: string, filename: string, options: ConfigData, hooks: SourceHooks): Promise<Report>;
+    /**
+     * Parse and validate HTML from string.
+     *
+     * @public
+     * @param str - Text to parse.
+     * @param filename - If set configuration is loaded for given filename.
+     * @param hooks - Optional hooks (see [[Source]]) for definition.
+     * @returns Report output.
+     */
+    validateStringSync(str: string): Report;
+    validateStringSync(str: string, filename: string): Report;
+    validateStringSync(str: string, hooks: SourceHooks): Report;
+    validateStringSync(str: string, options: ConfigData): Report;
+    validateStringSync(str: string, filename: string, hooks: SourceHooks): Report;
+    validateStringSync(str: string, filename: string, options: ConfigData): Report;
+    validateStringSync(str: string, filename: string, options: ConfigData, hooks: SourceHooks): Report;
     /**
      * Parse and validate HTML from [[Source]].
      *
@@ -922,7 +922,23 @@ export declare class HtmlValidate {
      * @param input - Source to parse.
      * @returns Report output.
      */
-    validateSource(input: Source, configOverride?: ConfigData): Report;
+    validateSource(input: Source, configOverride?: ConfigData): Promise<Report>;
+    /**
+     * Parse and validate HTML from [[Source]].
+     *
+     * @public
+     * @param input - Source to parse.
+     * @returns Report output.
+     */
+    validateSourceSync(input: Source, configOverride?: ConfigData): Report;
+    /**
+     * Parse and validate HTML from file.
+     *
+     * @public
+     * @param filename - Filename to read and parse.
+     * @returns Report output.
+     */
+    validateFile(filename: string): Promise<Report>;
     /**
      * Parse and validate HTML from file.
      *
@@ -930,7 +946,7 @@ export declare class HtmlValidate {
      * @param filename - Filename to read and parse.
      * @returns Report output.
      */
-    validateFile(filename: string): Report;
+    validateFileSync(filename: string): Report;
     /**
      * Parse and validate HTML from multiple files. Result is merged together to a
      * single report.
@@ -938,7 +954,25 @@ export declare class HtmlValidate {
      * @param filenames - Filenames to read and parse.
      * @returns Report output.
      */
-    validateMultipleFiles(filenames: string[]): Report;
+    validateMultipleFiles(filenames: string[]): Promise<Report>;
+    /**
+     * Parse and validate HTML from multiple files. Result is merged together to a
+     * single report.
+     *
+     * @param filenames - Filenames to read and parse.
+     * @returns Report output.
+     */
+    validateMultipleFilesSync(filenames: string[]): Report;
+    /**
+     * Returns true if the given filename can be validated.
+     *
+     * A file is considered to be validatable if the extension is `.html` or if a
+     * transformer matches the filename.
+     *
+     * This is mostly useful for tooling to determine whenever to validate the
+     * file or not. CLI tools will run on all the given files anyway.
+     */
+    canValidate(filename: string): Promise<boolean>;
     /**
      * Returns true if the given filename can be validated.
      *
@@ -948,7 +982,7 @@ export declare class HtmlValidate {
      * This is mostly useful for tooling to determine whenever to validate the
      * file or not. CLI tools will run on all the given files anyway.
      */
-    canValidate(filename: string): boolean;
+    canValidateSync(filename: string): boolean;
     /* Excluded from this release type: dumpTokens */
     /* Excluded from this release type: dumpEvents */
     /* Excluded from this release type: dumpTree */
@@ -965,30 +999,202 @@ export declare class HtmlValidate {
      * handled by html-validate but the path will be used when resolving
      * configuration. As a rule-of-thumb, set it to the elements json file.
      */
-    getElementsSchema(filename?: string): SchemaObject;
+    getElementsSchema(filename?: string): Promise<SchemaObject>;
+    /**
+     * Get effective metadata element schema.
+     *
+     * If a filename is given the configured plugins can extend the
+     * schema. Filename must not be an existing file or a filetype normally
+     * handled by html-validate but the path will be used when resolving
+     * configuration. As a rule-of-thumb, set it to the elements json file.
+     */
+    getElementsSchemaSync(filename?: string): SchemaObject;
+    /**
+     * Get contextual documentation for the given rule. The default configuration
+     * will be used.
+     *
+     * @example
+     *
+     * ```js
+     * const report = await htmlvalidate.validateFile("my-file.html");
+     * for (const result of report.results){
+     *   for (const message of result.messages){
+     *     const documentation = await htmlvalidate.getRuleDocumentation(message, result.filePath);
+     *     // do something with documentation
+     *   }
+     * }
+     * ```
+     *
+     * @public
+     * @since 8.0.0
+     * @param message - Message reported during validation
+     * @returns Contextual documentation or `null` if the rule does not exist.
+     */
+    getContextualDocumentation(message: Pick<Message, "ruleId" | "context">): Promise<RuleDocumentation | null>;
+    /**
+     * Get contextual documentation for the given rule. Configuration will be
+     * resolved for given filename.
+     *
+     * @example
+     *
+     * ```js
+     * const report = await htmlvalidate.validateFile("my-file.html");
+     * for (const result of report.results){
+     *   for (const message of result.messages){
+     *     const documentation = await htmlvalidate.getRuleDocumentation(message, result.filePath);
+     *     // do something with documentation
+     *   }
+     * }
+     * ```
+     *
+     * @public
+     * @since 8.0.0
+     * @param message - Message reported during validation
+     * @param filename - Filename used to resolve configuration.
+     * @returns Contextual documentation or `null` if the rule does not exist.
+     */
+    getContextualDocumentation(message: Pick<Message, "ruleId" | "context">, filename: string): Promise<RuleDocumentation | null>;
+    /**
+     * Get contextual documentation for the given rule using provided
+     * configuration.
+     *
+     * @example
+     *
+     * ```js
+     * const report = await htmlvalidate.validateFile("my-file.html");
+     * for (const result of report.results){
+     *   for (const message of result.messages){
+     *     const documentation = await htmlvalidate.getRuleDocumentation(message, result.filePath);
+     *     // do something with documentation
+     *   }
+     * }
+     * ```
+     *
+     * @public
+     * @since 8.0.0
+     * @param message - Message reported during validation
+     * @param config - Configuration to use.
+     * @returns Contextual documentation or `null` if the rule does not exist.
+     */
+    getContextualDocumentation(message: Pick<Message, "ruleId" | "context">, config: ResolvedConfig | Promise<ResolvedConfig>): Promise<RuleDocumentation | null>;
+    /**
+     * Get contextual documentation for the given rule. The default configuration
+     * will be used.
+     *
+     * @example
+     *
+     * ```js
+     * const report = htmlvalidate.validateFileSync("my-file.html");
+     * for (const result of report.results){
+     *   for (const message of result.messages){
+     *     const documentation = htmlvalidate.getRuleDocumentationSync(message, result.filePath);
+     *     // do something with documentation
+     *   }
+     * }
+     * ```
+     *
+     * @public
+     * @since 8.0.0
+     * @param message - Message reported during validation
+     * @returns Contextual documentation or `null` if the rule does not exist.
+     */
+    getContextualDocumentationSync(message: Pick<Message, "ruleId" | "context">): RuleDocumentation | null;
+    /**
+     * Get contextual documentation for the given rule. Configuration will be
+     * resolved for given filename.
+     *
+     * @example
+     *
+     * ```js
+     * const report = htmlvalidate.validateFileSync("my-file.html");
+     * for (const result of report.results){
+     *   for (const message of result.messages){
+     *     const documentation = htmlvalidate.getRuleDocumentationSync(message, result.filePath);
+     *     // do something with documentation
+     *   }
+     * }
+     * ```
+     *
+     * @public
+     * @since 8.0.0
+     * @param message - Message reported during validation
+     * @param filename - Filename used to resolve configuration.
+     * @returns Contextual documentation or `null` if the rule does not exist.
+     */
+    getContextualDocumentationSync(message: Pick<Message, "ruleId" | "context">, filename: string): RuleDocumentation | null;
+    /**
+     * Get contextual documentation for the given rule using provided
+     * configuration.
+     *
+     * @example
+     *
+     * ```js
+     * const report = htmlvalidate.validateFileSync("my-file.html");
+     * for (const result of report.results){
+     *   for (const message of result.messages){
+     *     const documentation = htmlvalidate.getRuleDocumentationSync(message, result.filePath);
+     *     // do something with documentation
+     *   }
+     * }
+     * ```
+     *
+     * @public
+     * @since 8.0.0
+     * @param message - Message reported during validation
+     * @param config - Configuration to use.
+     * @returns Contextual documentation or `null` if the rule does not exist.
+     */
+    getContextualDocumentationSync(message: Pick<Message, "ruleId" | "context">, config: ResolvedConfig): RuleDocumentation | null;
     /**
      * Get contextual documentation for the given rule.
      *
      * Typical usage:
      *
      * ```js
-     * const report = htmlvalidate.validateFile("my-file.html");
+     * const report = await htmlvalidate.validateFile("my-file.html");
      * for (const result of report.results){
-     *   const config = htmlvalidate.getConfigFor(result.filePath);
+     *   const config = await htmlvalidate.getConfigFor(result.filePath);
      *   for (const message of result.messages){
-     *     const documentation = htmlvalidate.getRuleDocumentation(message.ruleId, config, message.context);
+     *     const documentation = await htmlvalidate.getRuleDocumentation(message.ruleId, config, message.context);
      *     // do something with documentation
      *   }
      * }
      * ```
      *
+     * @public
+     * @deprecated Deprecated since 8.0.0, use [[getContextualDocumentation]] instead.
      * @param ruleId - Rule to get documentation for.
      * @param config - If set it provides more accurate description by using the
      * correct configuration for the file.
      * @param context - If set to `Message.context` some rules can provide
      * contextual details and suggestions.
      */
-    getRuleDocumentation(ruleId: string, config?: ResolvedConfig | null, context?: any | null): RuleDocumentation | null;
+    getRuleDocumentation(ruleId: string, config?: ResolvedConfig | Promise<ResolvedConfig> | null, context?: unknown | null): Promise<RuleDocumentation | null>;
+    /**
+     * Get contextual documentation for the given rule.
+     *
+     * Typical usage:
+     *
+     * ```js
+     * const report = htmlvalidate.validateFileSync("my-file.html");
+     * for (const result of report.results){
+     *   const config = htmlvalidate.getConfigForSync(result.filePath);
+     *   for (const message of result.messages){
+     *     const documentation = htmlvalidate.getRuleDocumentationSync(message.ruleId, config, message.context);
+     *     // do something with documentation
+     *   }
+     * }
+     * ```
+     *
+     * @public
+     * @deprecated Deprecated since 8.0.0, use [[getContextualDocumentationSync]] instead.
+     * @param ruleId - Rule to get documentation for.
+     * @param config - If set it provides more accurate description by using the
+     * correct configuration for the file.
+     * @param context - If set to `Message.context` some rules can provide
+     * contextual details and suggestions.
+     */
+    getRuleDocumentationSync(ruleId: string, config?: ResolvedConfig | null, context?: unknown | null): RuleDocumentation | null;
     /* Excluded from this release type: getParserFor */
     /**
      * Get configuration for given filename.
@@ -999,7 +1205,17 @@ export declare class HtmlValidate {
      * @param filename - Filename to get configuration for.
      * @param configOverride - Configuration to apply last.
      */
-    getConfigFor(filename: string, configOverride?: ConfigData): ResolvedConfig;
+    getConfigFor(filename: string, configOverride?: ConfigData): Promise<ResolvedConfig>;
+    /**
+     * Get configuration for given filename.
+     *
+     * See [[FileSystemConfigLoader]] for details.
+     *
+     * @public
+     * @param filename - Filename to get configuration for.
+     * @param configOverride - Configuration to apply last.
+     */
+    getConfigForSync(filename: string, configOverride?: ConfigData): ResolvedConfig;
     /**
      * Flush configuration cache. Clears full cache unless a filename is given.
      *
@@ -1566,7 +1782,7 @@ export declare class Reporter {
      * Merge two or more reports into a single one.
      */
     static merge(reports: Report[]): Report;
-    add<ContextType, OptionsType>(rule: Rule<ContextType, OptionsType>, message: string, severity: number, node: DOMNode | null, location: Location_2, context?: ContextType): void;
+    add<ContextType, OptionsType>(rule: Rule<ContextType, OptionsType>, message: string, severity: number, node: DOMNode | null, location: Location_2, context: ContextType): void;
     addManual(filename: string, message: DeferredMessage): void;
     save(sources?: Source[]): Report;
     protected isValid(): boolean;
@@ -1641,6 +1857,39 @@ export declare interface ResolvedConfigData {
     transformers: TransformerEntry[];
 }
 
+/**
+ * @public
+ * @since 8.0.0
+ */
+export declare interface Resolver {
+    /** Name of resolver, mostly for ease of debugging */
+    name: string;
+    /**
+     * Resolve table of element metadata.
+     */
+    resolveElements?(id: string, options: ResolverOptions): unknown | null;
+    /**
+     * Resolve a configuration to extend.
+     */
+    resolveConfig?(id: string, options: ResolverOptions): ConfigData | null;
+    /**
+     * Resolve a plugin.
+     */
+    resolvePlugin?(id: string, options: ResolverOptions): Plugin_2 | null;
+    /**
+     * Resolve a transformer.
+     */
+    resolveTransformer?(id: string, options: ResolverOptions): Transformer_2 | null;
+}
+
+/**
+ * @public
+ * @since 8.0.0
+ */
+export declare interface ResolverOptions {
+    cache: boolean;
+}
+
 /**
  * @public
  */
@@ -1781,11 +2030,13 @@ export declare abstract class Rule<ContextType = void, OptionsType = void> {
      * Called when requesting additional documentation for a rule. Some rules
      * provide additional context to provide context-aware suggestions.
      *
+     * @public
+     * @virtual
      * @param context - Error context given by a reported error.
      * @returns Rule documentation and url with additional details or `null` if no
      * additional documentation is available.
      */
-    documentation(context?: ContextType): RuleDocumentation | null;
+    documentation(context: ContextType): RuleDocumentation | null;
 }
 
 /* Excluded from this release type: RuleBlocker */
@@ -1989,11 +2240,61 @@ export declare interface SourceReadyEvent extends Event_2 {
  * @public
  */
 export declare class StaticConfigLoader extends ConfigLoader {
+    /**
+     * Create a static configuration loader with default resolvers.
+     *
+     * @param config - Global configuration
+     * @param configFactory - Optional configuration factory
+     */
+    constructor(config?: ConfigData);
+    /**
+     * Create a static configuration loader with custom resolvers.
+     *
+     * @param resolvers - Resolvers to use
+     * @param config - Global configuration
+     * @param configFactory - Optional configuration factory
+     */
+    constructor(resolvers: Resolver[], config?: ConfigData);
     getConfigFor(_handle: string, configOverride?: ConfigData): ResolvedConfig;
     flushCache(): void;
     protected defaultConfig(): Config;
 }
 
+/**
+ * Static resolver.
+ *
+ * @public
+ * @since 8.0.0
+ */
+export declare interface StaticResolver extends Required<Resolver> {
+    addElements(id: string, elements: MetaDataTable): void;
+    addConfig(id: string, config: ConfigData): void;
+    addPlugin(id: string, plugin: Plugin_2): void;
+    addTransformer(id: string, transformer: Transformer_2): void;
+}
+
+/**
+ * Create a new resolver for static content, i.e. plugins or transformers known
+ * at compile time.
+ *
+ * @public
+ * @since 8.0.0
+ */
+export declare function staticResolver(map?: StaticResolverMap): StaticResolver;
+
+/**
+ * Entries for the static resolver.
+ *
+ * @public
+ * @since 8.0.0
+ */
+export declare interface StaticResolverMap {
+    elements?: Record<string, MetaDataTable>;
+    configs?: Record<string, ConfigData>;
+    plugins?: Record<string, Plugin_2>;
+    transformers?: Record<string, Transformer_2>;
+}
+
 /* Excluded from this release type: StyleToken */
 
 /**
@@ -2056,55 +2357,6 @@ export declare interface TagStartEvent extends Event_2 {
     target: HtmlElement;
 }
 
-/**
- * @public
- */
-export declare class TemplateExtractor {
-    private ast;
-    private filename;
-    private data;
-    private constructor();
-    static fromFilename(filename: string): TemplateExtractor;
-    /**
-     * Create a new [[TemplateExtractor]] from javascript source code.
-     *
-     * `Source` offsets will be relative to the string, i.e. offset 0 is the first
-     * character of the string. If the string is only a subset of a larger string
-     * the offsets must be adjusted manually.
-     *
-     * @param source - Source code.
-     * @param filename - Optional filename to set in the resulting
-     * `Source`. Defauls to `"inline"`.
-     */
-    static fromString(source: string, filename?: string): TemplateExtractor;
-    /**
-     * Convenience function to create a [[Source]] instance from an existing file.
-     *
-     * @param filename - Filename with javascript source code. The file must exist
-     * and be readable by the user.
-     * @returns An array of Source's suitable for passing to [[Engine]] linting
-     * functions.
-     */
-    static createSource(filename: string): Source[];
-    /**
-     * Extract object properties.
-     *
-     * Given a key `"template"` this method finds all objects literals with a
-     * `"template"` property and creates a [[Source]] instance with proper offsets
-     * with the value of the property. For instance:
-     *
-     * ```
-     * const myObj = {
-     *   foo: 'bar',
-     * };
-     * ```
-     *
-     * The above snippet would yield a `Source` with the content `bar`.
-     *
-     */
-    extractObjectProperty(key: string): Source[];
-}
-
 /* Excluded from this release type: TemplatingToken */
 
 /**