@markuplint/ml-core 4.13.2 → 4.18.0

package/lib/ml-dom/token/token.js

@@ -10,7 +10,19 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
 var _MLToken_endCol, _MLToken_endLine, _MLToken_endOffset, _MLToken_fixed, _MLToken_raw, _MLToken_startCol, _MLToken_startLine, _MLToken_startOffset;
+/**
+ * Represents a single token in the markuplint AST.
+ * Wraps an AST token with positional information (line, column, offset)
+ * and provides both raw and fixed string representations.
+ *
+ * @template A - The AST token type this token wraps
+ */
 export class MLToken {
+    /**
+     * Creates a new MLToken instance from an AST token.
+     *
+     * @param astToken - The AST token to wrap
+     */
     constructor(astToken) {
         _MLToken_endCol.set(this, void 0);
         _MLToken_endLine.set(this, void 0);
@@ -32,61 +44,85 @@ export class MLToken {
         __classPrivateFieldSet(this, _MLToken_endOffset, astToken.endOffset, "f");
     }
     /**
+     * The ending column number (1-based) of this token in the source.
+     *
      * @implements `@markuplint/ml-core` API: `MLDOMToken`
      */
     get endCol() {
         return __classPrivateFieldGet(this, _MLToken_endCol, "f");
     }
     /**
+     * The ending line number (1-based) of this token in the source.
+     *
      * @implements `@markuplint/ml-core` API: `MLDOMToken`
      */
     get endLine() {
         return __classPrivateFieldGet(this, _MLToken_endLine, "f");
     }
     /**
+     * The ending character offset (0-based) of this token in the source.
+     *
      * @implements `@markuplint/ml-core` API: `MLDOMToken`
      */
     get endOffset() {
         return __classPrivateFieldGet(this, _MLToken_endOffset, "f");
     }
     /**
+     * The fixed (potentially modified) string content of this token.
+     *
      * @implements `@markuplint/ml-core` API: `MLDOMToken`
      */
     get fixed() {
         return __classPrivateFieldGet(this, _MLToken_fixed, "f");
     }
     /**
+     * The original raw string content of this token from the source.
+     *
      * @implements `@markuplint/ml-core` API: `MLDOMToken`
      */
     get raw() {
         return __classPrivateFieldGet(this, _MLToken_raw, "f");
     }
     /**
+     * The starting column number (1-based) of this token in the source.
+     *
      * @implements `@markuplint/ml-core` API: `MLDOMToken`
      */
     get startCol() {
         return __classPrivateFieldGet(this, _MLToken_startCol, "f");
     }
     /**
+     * The starting line number (1-based) of this token in the source.
+     *
      * @implements `@markuplint/ml-core` API: `MLDOMToken`
      */
     get startLine() {
         return __classPrivateFieldGet(this, _MLToken_startLine, "f");
     }
     /**
+     * The starting character offset (0-based) of this token in the source.
+     *
      * @implements `@markuplint/ml-core` API: `MLDOMToken`
      */
     get startOffset() {
         return __classPrivateFieldGet(this, _MLToken_startOffset, "f");
     }
     /**
+     * Replaces the fixed content of this token with the given string,
+     * used when applying lint fixes.
+     *
      * @implements `@markuplint/ml-core` API: `MLDOMToken`
+     * @param raw - The new string content to set as the fixed value
      */
     fix(raw) {
         __classPrivateFieldSet(this, _MLToken_fixed, raw, "f");
     }
     /**
+     * Returns the string representation of this token.
+     *
      * @implements `@markuplint/ml-core` API: `MLDOMToken`
+     * @param fixed - When true, returns the fixed content; otherwise returns the original raw content
+     * @returns The string content of this token
      */
     toString(fixed = false) {
         return fixed ? __classPrivateFieldGet(this, _MLToken_fixed, "f") : __classPrivateFieldGet(this, _MLToken_raw, "f");

package/lib/ml-rule/create-rule.d.ts

@@ -1,3 +1,12 @@
 import type { RuleSeed } from './types.js';
 import type { PlainData, RuleConfigValue } from '@markuplint/ml-config';
+/**
+ * Factory function for creating a type-safe rule seed.
+ * Returns the seed object as-is; primarily used for type inference.
+ *
+ * @template T - The type of the rule's configuration value
+ * @template O - The type of the rule's options
+ * @param seed - The rule seed definition containing verify/fix functions and defaults
+ * @returns The same seed object, now fully typed
+ */
 export declare function createRule<T extends RuleConfigValue, O extends PlainData = undefined>(seed: Readonly<RuleSeed<T, O>>): Readonly<RuleSeed<T, O>>;

package/lib/ml-rule/create-rule.js

@@ -1,3 +1,12 @@
+/**
+ * Factory function for creating a type-safe rule seed.
+ * Returns the seed object as-is; primarily used for type inference.
+ *
+ * @template T - The type of the rule's configuration value
+ * @template O - The type of the rule's options
+ * @param seed - The rule seed definition containing verify/fix functions and defaults
+ * @returns The same seed object, now fully typed
+ */
 export function createRule(seed) {
     return seed;
 }

package/lib/ml-rule/ml-rule.d.ts

@@ -3,6 +3,12 @@ import type { MLDocument } from '../ml-dom/node/document.js';
 import type { Ruleset } from '../ruleset/index.js';
 import type { LocaleSet } from '@markuplint/i18n';
 import type { GlobalRuleInfo, PlainData, Rule, RuleConfigValue, RuleInfo, Severity, Violation } from '@markuplint/ml-config';
+/**
+ * Represents a single markuplint rule that can verify documents and report violations.
+ *
+ * @template T - The type of the rule's configuration value
+ * @template O - The type of the rule's options
+ */
 export declare class MLRule<T extends RuleConfigValue, O extends PlainData = undefined> {
     #private;
     readonly defaultOptions: O;
@@ -22,9 +28,36 @@ export declare class MLRule<T extends RuleConfigValue, O extends PlainData = und
      * only for extending from 3rd party library
      */
     protected get v(): RuleSeed<T, O>['verify'];
+    /**
+     * Resolves the full rule information from a ruleset, including node-level
+     * and child-node-level overrides.
+     *
+     * @param ruleSet - The ruleset containing rule definitions and overrides
+     * @param ruleName - The name of this rule
+     * @returns The global rule info with node and child-node overrides
+     */
     getRuleInfo(ruleSet: Ruleset, ruleName: string): GlobalRuleInfo<T, O>;
+    /**
+     * Normalizes a raw rule setting into a fully resolved {@link RuleInfo} object,
+     * applying defaults for any unspecified fields.
+     *
+     * @param configSettings - The raw rule configuration value
+     * @returns The resolved rule info with defaults applied
+     */
     optimizeOption(configSettings: Rule<T, O> | null | undefined): RuleInfo<T, O>;
+    /**
+     * Executes this rule's verify (and optionally fix) function against a document,
+     * then collects and returns the resulting violations.
+     *
+     * @param document - The parsed document to verify
+     * @param locale - The locale set for translating violation messages
+     * @param fix - Whether to also run the fix function
+     * @returns An array of violations found by this rule
+     */
     verify(document: MLDocument<T, O>, locale: LocaleSet, fix: boolean): Promise<Violation[]>;
     private _optimize;
 }
+/**
+ * An MLRule with any value and option types. Used when the specific types are not known.
+ */
 export type AnyMLRule = MLRule<RuleConfigValue, PlainData>;

package/lib/ml-rule/ml-rule.js

@@ -14,6 +14,12 @@ import { deleteUndefProp } from '@markuplint/ml-config';
 // @ts-ignore
 import { isPlainObject } from 'is-plain-object';
 import { MLRuleContext } from './ml-rule-context.js';
+/**
+ * Represents a single markuplint rule that can verify documents and report violations.
+ *
+ * @template T - The type of the rule's configuration value
+ * @template O - The type of the rule's options
+ */
 export class MLRule {
     constructor(o) {
         _MLRule_f.set(this, void 0);
@@ -40,6 +46,14 @@ export class MLRule {
     get v() {
         return __classPrivateFieldGet(this, _MLRule_v, "f");
     }
+    /**
+     * Resolves the full rule information from a ruleset, including node-level
+     * and child-node-level overrides.
+     *
+     * @param ruleSet - The ruleset containing rule definitions and overrides
+     * @param ruleName - The name of this rule
+     * @returns The global rule info with node and child-node overrides
+     */
     getRuleInfo(ruleSet, ruleName) {
         const info = this._optimize(ruleSet.rules, ruleName);
         return {
@@ -48,6 +62,13 @@ export class MLRule {
             childNodeRules: ruleSet.childNodeRules.map(r => this._optimize(r.rules, ruleName)).filter(r => !r.disabled),
         };
     }
+    /**
+     * Normalizes a raw rule setting into a fully resolved {@link RuleInfo} object,
+     * applying defaults for any unspecified fields.
+     *
+     * @param configSettings - The raw rule configuration value
+     * @returns The resolved rule info with defaults applied
+     */
     optimizeOption(configSettings) {
         if (configSettings === undefined || typeof configSettings === 'boolean') {
             return {
@@ -79,6 +100,15 @@ export class MLRule {
             reason: undefined,
         };
     }
+    /**
+     * Executes this rule's verify (and optionally fix) function against a document,
+     * then collects and returns the resulting violations.
+     *
+     * @param document - The parsed document to verify
+     * @param locale - The locale set for translating violation messages
+     * @param fix - Whether to also run the fix function
+     * @returns An array of violations found by this rule
+     */
     async verify(
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     document, locale, fix) {

package/lib/ml-rule/types.d.ts

@@ -2,6 +2,13 @@ import type { MLRuleContext } from './ml-rule-context.js';
 import type { Attr, Element } from '../ml-dom/index.js';
 import type { Translator } from '@markuplint/i18n';
 import type { PlainData, Report, RuleConfigValue, Severity } from '@markuplint/ml-config';
+/**
+ * The definition of a markuplint rule, including verification logic, optional fix logic,
+ * and default configuration values.
+ *
+ * @template T - The type of the rule's configuration value (defaults to boolean)
+ * @template O - The type of the rule's options
+ */
 export type RuleSeed<T extends RuleConfigValue = boolean, O extends PlainData = undefined> = {
     readonly meta?: {
         readonly category?: 'validation' | 'style' | 'naming-convention' | 'a11y' | 'maintainability';
@@ -12,12 +19,46 @@ export type RuleSeed<T extends RuleConfigValue = boolean, O extends PlainData =
     verify(context: ReturnType<MLRuleContext<T, O>['provide']>): void | Promise<void>;
     fix?(context: ReturnType<MLRuleContext<T, O>['provide']>): void | Promise<void>;
 };
+/**
+ * A generic checker function that produces a violation report from parameters.
+ *
+ * @template T - The type of the rule's configuration value
+ * @template O - The type of the rule's options
+ * @template P - Additional parameters passed to the checker
+ */
 export type Checker<T extends RuleConfigValue, O extends PlainData = undefined, P extends Record<string, unknown> = {}> = (params: P) => CheckerReport<T, O>;
+/**
+ * A checker function that verifies a specific element and produces a violation report.
+ *
+ * @template T - The type of the rule's configuration value
+ * @template O - The type of the rule's options
+ * @template P - Additional parameters passed alongside the element
+ */
 export type ElementChecker<T extends RuleConfigValue, O extends PlainData = undefined, P extends Record<string, unknown> = {}> = (params: P & {
     el: Element<T, O>;
 }) => CheckerReport<T, O>;
+/**
+ * A checker function that verifies a specific attribute and produces a violation report.
+ *
+ * @template T - The type of the rule's configuration value
+ * @template O - The type of the rule's options
+ * @template P - Additional parameters passed alongside the attribute
+ */
 export type AttrChecker<T extends RuleConfigValue, O extends PlainData = undefined, P extends Record<string, unknown> = {}> = (params: P & {
     attr: Attr<T, O>;
 }) => CheckerReport<T, O>;
+/**
+ * A function that receives a translator and returns a violation report, or `null`/`undefined`
+ * if no violation was found.
+ *
+ * @template T - The type of the rule's configuration value
+ * @template O - The type of the rule's options
+ */
 export type CheckerReport<T extends RuleConfigValue, O extends PlainData = undefined> = (t: Translator) => Report<T, O> | undefined | null;
+/**
+ * A RuleSeed with wildcard value and option types.
+ *
+ * @template T - The type of the rule's configuration value
+ * @template O - The type of the rule's options
+ */
 export type AnyRuleSeed<T extends RuleConfigValue = RuleConfigValue, O extends PlainData = PlainData> = RuleSeed<T, O>;

package/lib/plugin/plugin.d.ts

@@ -1,2 +1,10 @@
 import type { PluginCreator, CreatePluginSettings } from './types.js';
+/**
+ * Factory function for creating a type-safe plugin creator.
+ * Returns the creator object as-is; primarily used for type inference.
+ *
+ * @template S - The settings type accepted by the plugin
+ * @param fn - The plugin creator definition
+ * @returns The same creator object, now fully typed
+ */
 export declare function createPlugin<S extends CreatePluginSettings>(fn: Readonly<PluginCreator<S>>): Readonly<PluginCreator<S>>;

package/lib/plugin/plugin.js

@@ -1,3 +1,11 @@
+/**
+ * Factory function for creating a type-safe plugin creator.
+ * Returns the creator object as-is; primarily used for type inference.
+ *
+ * @template S - The settings type accepted by the plugin
+ * @param fn - The plugin creator definition
+ * @returns The same creator object, now fully typed
+ */
 export function createPlugin(fn) {
     return fn;
 }

package/lib/plugin/types.d.ts

@@ -1,12 +1,33 @@
 import type { RuleSeed } from '../ml-rule/index.js';
 import type { Config } from '@markuplint/ml-config';
+/**
+ * A resolved markuplint plugin containing named rules and/or shared configurations.
+ */
 export type Plugin = {
+    /** The plugin name, used as a prefix for its rules (e.g. `"my-plugin/rule-name"`) */
     readonly name: string;
+    /** Custom rules provided by this plugin */
     readonly rules?: Readonly<Record<string, Readonly<RuleSeed<any, any>>>>;
+    /** Shared configurations that users can extend from */
     readonly configs?: Readonly<Record<string, Config>>;
 };
+/**
+ * A factory interface for creating plugins with custom settings.
+ *
+ * @template S - The settings type accepted by the plugin creator
+ */
 export type PluginCreator<S extends CreatePluginSettings> = {
+    /** The plugin name */
     readonly name: string;
+    /**
+     * Creates the plugin's rules and configs from the given settings.
+     *
+     * @param setting - The user-provided settings for this plugin
+     * @returns The plugin's rules and configurations
+     */
     create(setting: S): Omit<Plugin, 'name'>;
 };
+/**
+ * Base type for plugin settings. A readonly record of string keys to unknown values.
+ */
 export type CreatePluginSettings = Readonly<Record<string, unknown>>;

package/lib/ruleset/index.d.ts

@@ -1,7 +1,17 @@
 import type { ChildNodeRule, Config, NodeRule, Rules } from '@markuplint/ml-config';
+/**
+ * A resolved set of rules, node-specific rule overrides, and child-node-specific
+ * rule overrides extracted from a markuplint {@link Config}.
+ */
 export declare class Ruleset {
+    /** Rule overrides that apply to child nodes matching specific selectors */
     readonly childNodeRules: readonly ChildNodeRule[];
+    /** Rule overrides that apply to nodes matching specific selectors */
     readonly nodeRules: readonly NodeRule[];
+    /** The global rule definitions */
     readonly rules: Rules;
+    /**
+     * @param config - The markuplint configuration to extract rules from
+     */
     constructor(config: Config);
 }

package/lib/ruleset/index.js

@@ -1,4 +1,11 @@
+/**
+ * A resolved set of rules, node-specific rule overrides, and child-node-specific
+ * rule overrides extracted from a markuplint {@link Config}.
+ */
 export class Ruleset {
+    /**
+     * @param config - The markuplint configuration to extract rules from
+     */
     constructor(config) {
         this.rules = config.rules ?? {};
         this.nodeRules = config.nodeRules ?? [];

package/lib/test/index.d.ts

@@ -5,19 +5,60 @@ import type { MLASTNode, MLASTToken, MLParser } from '@markuplint/ml-ast';
 import type { Config, PlainData, Pretender, RuleConfigValue } from '@markuplint/ml-config';
 import type { MLMLSpec } from '@markuplint/ml-spec';
 import { MLDocument } from '../ml-dom/node/document.js';
+/**
+ * Options for creating test documents and elements.
+ */
 export type CreateTestOptions = {
+    /** The markuplint configuration to apply */
     readonly config?: Config;
+    /** A parser module or parser instance to use instead of the default HTML parser */
     readonly parser?: {
         readonly parser: Readonly<MLParser>;
     } | Readonly<MLParser>;
+    /** The HTML/ARIA specification data to use */
     readonly specs?: MLMLSpec;
+    /** Pretender definitions for component mapping */
     readonly pretenders?: readonly Pretender[];
 };
+/**
+ * Parses markup source code and returns a test document for use in rule tests.
+ *
+ * @template T - The rule config value type
+ * @template O - The rule options type
+ * @param sourceCode - The markup source code to parse
+ * @param options - Options for parser, config, specs, and pretenders
+ * @returns A parsed MLDocument instance
+ */
 export declare function createTestDocument<T extends RuleConfigValue = any, O extends PlainData = any>(sourceCode: string, options?: CreateTestOptions): MLDocument<T, O>;
+/**
+ * Parses markup source code and returns the flat list of AST nodes.
+ *
+ * @param sourceCode - The markup source code to parse
+ * @param options - Options for parser, config, specs, and pretenders
+ * @returns A readonly array of all nodes in the parsed document
+ */
 export declare function createTestNodeList(sourceCode: string, options?: CreateTestOptions): readonly MLNode<any, any, MLASTNode>[];
+/**
+ * Parses markup source code and returns the flat list of tokens.
+ *
+ * @param sourceCode - The markup source code to parse
+ * @param options - Options for parser, config, specs, and pretenders
+ * @returns A readonly array of all tokens in the parsed document
+ */
 export declare function createTestTokenList(sourceCode: string, options?: CreateTestOptions): readonly MLToken<MLASTToken>[];
+/**
+ * Parses markup source code and returns the first element node.
+ * Throws if the source does not produce an element as its first node.
+ *
+ * @param sourceCode - The markup source code containing an element
+ * @param options - Options for parser, config, specs, and pretenders
+ * @returns The first element in the parsed document
+ * @throws {TypeError} If the first node is not an element
+ */
 export declare function createTestElement(sourceCode: string, options?: CreateTestOptions): MLElement<any, any>;
 /**
- * for test suite
+ * Returns the default HTML spec as a schema tuple for use in test suites.
+ *
+ * @returns A single-element tuple containing the HTML specification
  */
 export declare function dummySchemas(): [MLMLSpec];

package/lib/test/index.js

@@ -2,6 +2,15 @@ import { parser } from '@markuplint/html-parser';
 import spec from '@markuplint/html-spec';
 import { convertRuleset } from '../convert-ruleset.js';
 import { MLDocument } from '../ml-dom/node/document.js';
+/**
+ * Parses markup source code and returns a test document for use in rule tests.
+ *
+ * @template T - The rule config value type
+ * @template O - The rule options type
+ * @param sourceCode - The markup source code to parse
+ * @param options - Options for parser, config, specs, and pretenders
+ * @returns A parsed MLDocument instance
+ */
 export function createTestDocument(sourceCode, options) {
     const ast = options?.parser
         ? 'parser' in options.parser
@@ -12,14 +21,37 @@ export function createTestDocument(sourceCode, options) {
     const document = new MLDocument(ast, ruleset, [options?.specs ?? {}, {}]);
     return document;
 }
+/**
+ * Parses markup source code and returns the flat list of AST nodes.
+ *
+ * @param sourceCode - The markup source code to parse
+ * @param options - Options for parser, config, specs, and pretenders
+ * @returns A readonly array of all nodes in the parsed document
+ */
 export function createTestNodeList(sourceCode, options) {
     const document = createTestDocument(sourceCode, options);
     return document.nodeList;
 }
+/**
+ * Parses markup source code and returns the flat list of tokens.
+ *
+ * @param sourceCode - The markup source code to parse
+ * @param options - Options for parser, config, specs, and pretenders
+ * @returns A readonly array of all tokens in the parsed document
+ */
 export function createTestTokenList(sourceCode, options) {
     const document = createTestDocument(sourceCode, options);
     return document.getTokenList();
 }
+/**
+ * Parses markup source code and returns the first element node.
+ * Throws if the source does not produce an element as its first node.
+ *
+ * @param sourceCode - The markup source code containing an element
+ * @param options - Options for parser, config, specs, and pretenders
+ * @returns The first element in the parsed document
+ * @throws {TypeError} If the first node is not an element
+ */
 export function createTestElement(sourceCode, options) {
     const document = createTestDocument(sourceCode, options);
     const el = document.nodeList[0];
@@ -29,7 +61,9 @@ export function createTestElement(sourceCode, options) {
     throw new TypeError(`Could not parse it to be an element from: ${sourceCode}`);
 }
 /**
- * for test suite
+ * Returns the default HTML spec as a schema tuple for use in test suites.
+ *
+ * @returns A single-element tuple containing the HTML specification
  */
 export function dummySchemas() {
     return [spec];

package/lib/types.d.ts

@@ -4,7 +4,15 @@ import type { LocaleSet } from '@markuplint/i18n';
 import type { MLParser, ParserOptions } from '@markuplint/ml-ast';
 import type { Pretender, SeverityOptions } from '@markuplint/ml-config';
 import type { ExtendedSpec, MLMLSpec } from '@markuplint/ml-spec';
+/**
+ * A tuple of the base HTML/ARIA specification and zero or more
+ * framework-specific extended specs (e.g. React, Vue, Svelte).
+ */
 export type MLSchema = readonly [MLMLSpec, ...ExtendedSpec[]];
+/**
+ * The set of dependencies required by {@link MLCore} to perform linting.
+ * Includes the parser, ruleset, rules, locale, schemas, and other settings.
+ */
 export type MLFabric = {
     readonly parser: Readonly<MLParser>;
     readonly ruleset: Partial<Readonly<Ruleset>>;

package/lib/violation-collector.d.ts

@@ -1,12 +1,45 @@
 import type { Violation } from '@markuplint/ml-config';
+/**
+ * Collects and manages lint violations across multiple files.
+ * Supports a maximum violation count to stop collecting early.
+ */
 export declare class ViolationCollector {
     #private;
+    /**
+     * @param maxCount - Maximum number of violations to collect; 0 means unlimited
+     */
     constructor(maxCount?: number);
+    /**
+     * Adds violations associated with a specific file path.
+     * Stops collecting once the maximum count is reached.
+     *
+     * @param filePath - The file that produced these violations
+     * @param violations - The violations to add
+     * @returns The current total number of collected violations
+     */
     pushWithFile(filePath: string, ...violations: readonly Violation[]): number;
+    /**
+     * The total number of collected violations.
+     */
     get length(): number;
+    /**
+     * Whether the collector has reached its maximum count and will no longer accept violations.
+     *
+     * @returns `true` if the collector is locked
+     */
     isLocked(): boolean;
+    /**
+     * Returns a copy of all collected violations as an array.
+     *
+     * @returns An array of violations with their associated file paths
+     */
     toArray(): (Violation & {
         filePath: string;
     })[];
+    /**
+     * Groups collected violations by their file path.
+     *
+     * @returns A Map from file path to an array of violations for that file
+     */
     groupByFile(): Map<string, Violation[]>;
 }

package/lib/violation-collector.js

@@ -10,7 +10,14 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
 var _ViolationCollector_violations, _ViolationCollector_maxCount, _ViolationCollector_locked;
+/**
+ * Collects and manages lint violations across multiple files.
+ * Supports a maximum violation count to stop collecting early.
+ */
 export class ViolationCollector {
+    /**
+     * @param maxCount - Maximum number of violations to collect; 0 means unlimited
+     */
     constructor(maxCount = 0) {
         _ViolationCollector_violations.set(this, []);
         _ViolationCollector_maxCount.set(this, 0);
@@ -18,6 +25,14 @@ export class ViolationCollector {
         __classPrivateFieldSet(this, _ViolationCollector_maxCount, maxCount, "f");
         __classPrivateFieldSet(this, _ViolationCollector_locked, false, "f");
     }
+    /**
+     * Adds violations associated with a specific file path.
+     * Stops collecting once the maximum count is reached.
+     *
+     * @param filePath - The file that produced these violations
+     * @param violations - The violations to add
+     * @returns The current total number of collected violations
+     */
     pushWithFile(filePath, ...violations) {
         if (__classPrivateFieldGet(this, _ViolationCollector_locked, "f")) {
             return __classPrivateFieldGet(this, _ViolationCollector_violations, "f").length;
@@ -31,15 +46,33 @@ export class ViolationCollector {
         }
         return __classPrivateFieldGet(this, _ViolationCollector_violations, "f").length;
     }
+    /**
+     * The total number of collected violations.
+     */
     get length() {
         return __classPrivateFieldGet(this, _ViolationCollector_violations, "f").length;
     }
+    /**
+     * Whether the collector has reached its maximum count and will no longer accept violations.
+     *
+     * @returns `true` if the collector is locked
+     */
     isLocked() {
         return __classPrivateFieldGet(this, _ViolationCollector_locked, "f");
     }
+    /**
+     * Returns a copy of all collected violations as an array.
+     *
+     * @returns An array of violations with their associated file paths
+     */
     toArray() {
         return [...__classPrivateFieldGet(this, _ViolationCollector_violations, "f")];
     }
+    /**
+     * Groups collected violations by their file path.
+     *
+     * @returns A Map from file path to an array of violations for that file
+     */
     groupByFile() {
         const grouped = new Map();
         for (const violation of __classPrivateFieldGet(this, _ViolationCollector_violations, "f")) {