@askviraj/linter 1.1.0 → 1.1.3

package/node_modules/@rviscomi/capo.js/dist/types/adapters/adapter.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @file Base adapter interface for HTML tree operations
+ *
+ * This file defines the contract that all adapters must implement.
+ * Adapters abstract away environment-specific operations (browser DOM vs AST nodes)
+ * to make capo.js core logic reusable across different contexts.
+ */
+export type SourceLocation = {
+    line: number;
+    column: number;
+    endLine?: number;
+    endColumn?: number;
+};
+/**
+ * Base adapter interface
+ *
+ * Actual adapters should implement all these methods.
+ * This serves as both documentation and a reference implementation.
+ *
+ * @example
+ * import { BrowserAdapter } from './browser.js';
+ * import { ParserAdapter } from './parser.js';
+ *
+ * // For browser DOM:
+ * const adapter = new BrowserAdapter();
+ *
+ * // For ESLint HTML parser AST:
+ * const adapter = new ParserAdapter();
+ */
+export declare class AdapterInterface {
+    /**
+     * Check if node is an Element (not text, comment, etc.)
+     * @param {any} node - The node to check
+     * @returns {boolean}
+     */
+    isElement(node: any): boolean;
+    /**
+     * Get the tag name of an element (lowercase)
+     * @param {any} node - Element node
+     * @returns {string} - Tag name like 'meta', 'link', 'script'
+     */
+    getTagName(node: any): string;
+    /**
+     * Get attribute value from element
+     * @param {any} node - Element node
+     * @param {string} attrName - Attribute name (case-insensitive)
+     * @returns {string | null} - Attribute value or null if not found
+     */
+    getAttribute(node: any, attrName: string): string | null;
+    /**
+     * Check if element has a specific attribute
+     * @param {any} node - Element node
+     * @param {string} attrName - Attribute name (case-insensitive)
+     * @returns {boolean} - True if attribute exists
+     */
+    hasAttribute(node: any, attrName: string): boolean;
+    /**
+     * Get all attribute names for an element
+     * @param {any} node - Element node
+     * @returns {string[]} - Array of attribute names
+     */
+    getAttributeNames(node: any): string[];
+    /**
+     * Get text content of a node (for inline scripts/styles)
+     * @param {any} node - Element node
+     * @returns {string} - Text content
+     */
+    getTextContent(node: any): string;
+    /**
+     * Get child elements of a node
+     * @param {any} node - Parent node
+     * @returns {any[]} - Array of child element nodes (excluding text/comment nodes)
+     */
+    getChildren(node: any): any[];
+    /**
+     * Get parent element of a node
+     * @param {any} node - Child node
+     * @returns {any | null} - Parent element node, or null if no parent
+     */
+    getParent(node: any): any | null;
+    /**
+     * Get sibling elements of a node
+     * @param {any} node - Element node
+     * @returns {any[]} - Array of sibling element nodes (excluding the node itself)
+     */
+    getSiblings(node: any): any[];
+    /**
+     * Get source location for a node (optional, for linting)
+     * @param {any} node - Element node
+     * @returns {SourceLocation | null}
+     */
+    getLocation(node: any): SourceLocation | null;
+    /**
+     * Stringify element for logging/debugging
+     * @param {any} node - Element node
+     * @returns {string} - String representation like "<meta charset='utf-8'>"
+     */
+    stringify(node: any): string;
+}
+/**
+ * Validate that an object implements the HTMLAdapter interface
+ * @param {any} adapter - The adapter to validate
+ * @throws {Error} If adapter is missing required methods
+ */
+export declare function validateAdapter(adapter: any): void;

package/node_modules/@rviscomi/capo.js/dist/types/adapters/browser.d.ts

@@ -0,0 +1,107 @@
+/**
+ * @file Browser DOM adapter
+ *
+ * Wraps native DOM Element APIs to implement the HTMLAdapter interface.
+ * This adapter is used in browser environments where capo.js operates
+ * on actual DOM elements.
+ */
+import { AdapterInterface } from './adapter.js';
+/**
+ * Browser DOM adapter
+ *
+ * Wraps native DOM Element APIs for use with capo.js core logic.
+ *
+ * @extends AdapterInterface
+ * @example
+ * import { BrowserAdapter } from './adapters/browser.js';
+ * import { analyzeHead } from '../analyzer.js';
+ *
+ * const adapter = new BrowserAdapter();
+ * const head = document.querySelector('head');
+ * const result = analyzeHead(head, adapter);
+ */
+export declare class BrowserAdapter extends AdapterInterface {
+    /**
+     * Check if node is an Element (not text, comment, etc.)
+     * @override
+     * @param {any} node - The node to check
+     * @returns {boolean}
+     */
+    isElement(node: any): boolean;
+    /**
+     * Get the tag name of an element (lowercase)
+     * @override
+     * @param {any} node - Element node
+     * @returns {string} - Tag name like 'meta', 'link', 'script'
+     */
+    getTagName(node: any): string;
+    /**
+     * Get attribute value from element
+     * @override
+     * @param {any} node - Element node
+     * @param {string} attrName - Attribute name (case-insensitive)
+     * @returns {string | null} - Attribute value or null if not found
+     */
+    getAttribute(node: any, attrName: string): string | null;
+    /**
+     * Check if element has a specific attribute
+     * @override
+     * @param {any} node - Element node
+     * @param {string} attrName - Attribute name (case-insensitive)
+     * @returns {boolean} - True if attribute exists
+     */
+    hasAttribute(node: any, attrName: string): boolean;
+    /**
+     * Get all attribute names for an element
+     * @override
+     * @param {any} node - Element node
+     * @returns {string[]} - Array of attribute names
+     */
+    getAttributeNames(node: any): string[];
+    /**
+     * Get text content of a node (for inline scripts/styles)
+     * @override
+     * @param {any} node - Element node
+     * @returns {string} - Text content
+     */
+    getTextContent(node: any): string;
+    /**
+     * Get child elements of a node
+     * @override
+     * @param {any} node - Parent node
+     * @returns {any[]} - Array of child element nodes (excluding text/comment nodes)
+     */
+    getChildren(node: any): any[];
+    /**
+     * Get parent element of a node
+     * @override
+     * @param {any} node - Child node
+     * @returns {any | null} - Parent element node, or null if no parent
+     */
+    getParent(node: any): any | null;
+    /**
+     * Get sibling elements of a node
+     * @override
+     * @param {any} node - Element node
+     * @returns {any[]} - Array of sibling element nodes (excluding the node itself)
+     */
+    getSiblings(node: any): any[];
+    /**
+     * Get source location for a node (optional, for linting)
+     *
+     * Browser DOM elements don't have source location information,
+     * so this always returns null.
+     *
+     * @override
+     * @param {any} node - Element node
+     * @returns {null}
+     */
+    getLocation(node: any): null;
+    /**
+     * Stringify element for logging/debugging
+     * @override
+     * @param {any} node - Element node
+     * @returns {string} - String representation like "<meta charset='utf-8'>"
+     */
+    stringify(node: any): string;
+}

package/node_modules/@rviscomi/capo.js/dist/types/adapters/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @file Adapter exports
+ *
+ * Central export point for all HTML adapters.
+ */
+export { AdapterInterface, validateAdapter } from './adapter.js';
+export { BrowserAdapter } from './browser.js';

package/node_modules/@rviscomi/capo.js/dist/types/adapters/test-suite.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Reusable test suite for adapter validation
+ *
+ * This module provides a standard test suite that can be used to validate
+ * any custom adapter implementation. Consumers can import this and run it
+ * against their own adapters to ensure compliance with the AdapterInterface.
+ *
+ * @example
+ * import { describe } from 'node:test';
+ * import { runAdapterTestSuite } from '@rviscomi/capo.js/adapters/test-suite';
+ * import { MyCustomAdapter } from './my-adapter.js';
+ *
+ * describe('MyCustomAdapter', () => {
+ *   runAdapterTestSuite(MyCustomAdapter, {
+ *     createElement: (html) => {
+ *       // Return a node compatible with your adapter
+ *       return parseHtml(html);
+ *     }
+ *   });
+ * });
+ */
+export type AdapterTestSuiteOptions = {
+    /**
+     * - Function that creates test nodes from HTML strings
+     */
+    createElement: (html: string) => any;
+    /**
+     * - Whether adapter supports getLocation()
+     */
+    supportsLocation?: boolean;
+};
+/**
+ * @typedef {Object} AdapterTestSuiteOptions
+ * @property {(html: string) => any} createElement - Function that creates test nodes from HTML strings
+ * @property {boolean} [supportsLocation=false] - Whether adapter supports getLocation()
+ */
+/**
+ * Run the standard adapter test suite
+ *
+ * @param {new () => any} AdapterClass - The adapter class to test
+ * @param {AdapterTestSuiteOptions} options - Test configuration
+ */
+export declare function runAdapterTestSuite(AdapterClass: new () => any, options: AdapterTestSuiteOptions): void;
+/**
+ * Create a minimal compliance test
+ *
+ * This is a lighter-weight alternative that just checks the adapter
+ * implements all required methods without full behavior testing.
+ *
+ * @param {new () => any} AdapterClass - The adapter class to test
+ */
+export declare function testAdapterCompliance(AdapterClass: new () => any): void;

package/node_modules/@rviscomi/capo.js/dist/types/analyzer.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Core DOM-agnostic analyzer for capo.js
+ * Provides single-pass analysis of HTML <head> elements
+ *
+ * @module analyzer
+ */
+export type AdapterInterface = import('./adapters/adapter.js').AdapterInterface;
+export type WeightInfo = {
+    /**
+     * - The DOM/AST element
+     */
+    element: any;
+    /**
+     * - Computed weight (0-10)
+     */
+    weight: number;
+};
+export type ValidationWarning = {
+    /**
+     * - The rule identifier
+     */
+    ruleId?: string;
+    /**
+     * - Warning message
+     */
+    warning: string;
+    /**
+     * - Associated element
+     */
+    element?: any;
+    /**
+     * - Associated elements array
+     */
+    elements?: Array<any>;
+};
+export type CustomValidation = {
+    /**
+     * - The rule identifier
+     */
+    ruleId?: string;
+    /**
+     * - The element with validation issues
+     */
+    element: any;
+    /**
+     * - Validation warning messages
+     */
+    warnings: Array<string>;
+    /**
+     * - Extra diagnostic payload
+     */
+    payload?: any;
+};
+export type AnalysisResult = {
+    /**
+     * - Weight information for each element
+     */
+    weights: Array<WeightInfo>;
+    /**
+     * - Document-level validation warnings
+     */
+    validationWarnings: Array<ValidationWarning>;
+    /**
+     * - Element-level validation warnings
+     */
+    customValidations: Array<CustomValidation>;
+    /**
+     * - Reference to the analyzed head element
+     */
+    headElement: any;
+};
+export type OrderingViolation = {
+    index: number;
+    currentElement: any;
+    nextElement: any;
+    currentWeight: number;
+    nextWeight: number;
+    currentCategory: string;
+    nextCategory: string;
+    message: string;
+};
+export type AnalysisResultWithOrdering = AnalysisResult & {
+    orderingViolations: Array<OrderingViolation>;
+};
+export type AnalyzeHeadOptions = {
+    /**
+     * - Whether to include document-level validation warnings
+     */
+    includeValidation?: boolean;
+    /**
+     * - Whether to include element-level custom validations
+     */
+    includeCustomValidations?: boolean;
+};
+/**
+ * @typedef {import('./adapters/adapter.js').AdapterInterface} AdapterInterface
+ *
+ * @typedef {Object} WeightInfo
+ * @property {any} element - The DOM/AST element
+ * @property {number} weight - Computed weight (0-10)
+ */
+/**
+ * @typedef {Object} ValidationWarning
+ * @property {string} [ruleId] - The rule identifier
+ * @property {string} warning - Warning message
+ * @property {any} [element] - Associated element
+ * @property {Array<any>} [elements] - Associated elements array
+ */
+/**
+ * @typedef {Object} CustomValidation
+ * @property {string} [ruleId] - The rule identifier
+ * @property {any} element - The element with validation issues
+ * @property {Array<string>} warnings - Validation warning messages
+ * @property {any} [payload] - Extra diagnostic payload
+ */
+/**
+ * @typedef {Object} AnalysisResult
+ * @property {Array<WeightInfo>} weights - Weight information for each element
+ * @property {Array<ValidationWarning>} validationWarnings - Document-level validation warnings
+ * @property {Array<CustomValidation>} customValidations - Element-level validation warnings
+ * @property {any} headElement - Reference to the analyzed head element
+ */
+/**
+ * @typedef {Object} OrderingViolation
+ * @property {number} index
+ * @property {any} currentElement
+ * @property {any} nextElement
+ * @property {number} currentWeight
+ * @property {number} nextWeight
+ * @property {string} currentCategory
+ * @property {string} nextCategory
+ * @property {string} message
+ */
+/**
+ * @typedef {AnalysisResult & { orderingViolations: Array<OrderingViolation> }} AnalysisResultWithOrdering
+ */
+/**
+ * @typedef {Object} AnalyzeHeadOptions
+ * @property {boolean} [includeValidation=true] - Whether to include document-level validation warnings
+ * @property {boolean} [includeCustomValidations=true] - Whether to include element-level custom validations
+ */
+/**
+ * Analyze the head element and return element weights, validation warnings, and custom validations.
+ *
+ * @param {any} headNode - The head element to analyze
+ * @param {AdapterInterface} adapter - Adapter for element operations
+ * @param {AnalyzeHeadOptions} [options={}] - Analysis options
+ * @returns {AnalysisResult} Analysis results
+ *
+ * @example
+ * const adapter = new BrowserAdapter();
+ * const results = analyzeHead(head, adapter);
+ *
+ * console.log(`Found ${results.weights.length} elements`);
+ * console.log(`${results.validationWarnings.length} document warnings`);
+ */
+export declare function analyzeHead(headNode: any, adapter: AdapterInterface, options?: AnalyzeHeadOptions): AnalysisResult;
+/**
+ * Get weight category name from weight value
+ *
+ * @param {number} weight - Weight value (0-10)
+ * @returns {string} Category name
+ *
+ * @example
+ * getWeightCategory(10); // 'META'
+ * getWeightCategory(9);  // 'TITLE'
+ * getWeightCategory(0);  // 'OTHER'
+ */
+export declare function getWeightCategory(weight: number): string;
+/**
+ * Check if elements are in optimal order
+ *
+ * @param {Array<WeightInfo>} weights - Weight information array
+ * @returns {Array<OrderingViolation>} Array of ordering violations
+ *
+ * @example
+ * const weights = analyzeHead(head, adapter).weights;
+ * const violations = checkOrdering(weights);
+ * console.log(`${violations.length} ordering issues found`);
+ */
+export declare function checkOrdering(weights: Array<WeightInfo>): Array<OrderingViolation>;
+/**
+ * Analyze and return both weights and ordering violations
+ * Convenience function that combines analyzeHead() and checkOrdering()
+ *
+ * @param {any} headNode - The <head> element
+ * @param {AdapterInterface} adapter - HTMLAdapter implementation
+ * @param {AnalyzeHeadOptions} [options={}] - Analysis options
+ * @returns {AnalysisResultWithOrdering} Combined analysis with weights, violations, and validations
+ *
+ * @example
+ * const analysis = analyzeHeadWithOrdering(head, adapter);
+ * console.log(`${analysis.orderingViolations.length} ordering issues`);
+ */
+export declare function analyzeHeadWithOrdering(headNode: any, adapter: AdapterInterface, options?: AnalyzeHeadOptions): AnalysisResultWithOrdering;

package/node_modules/@rviscomi/capo.js/dist/types/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Capo.js v2 - DOM-agnostic HTML <head> analyzer
+ *
+ * Main entry point for programmatic usage.
+ * Exports both the core analyzer API and adapter implementations.
+ *
+ * @module capo
+ */
+export { analyzeHead, analyzeHeadWithOrdering, checkOrdering, getWeightCategory } from './analyzer.js';
+export type AnalysisResult = import('./analyzer.js').AnalysisResult;
+export type WeightInfo = import('./analyzer.js').WeightInfo;
+export type ValidationWarning = import('./analyzer.js').ValidationWarning;
+export type CustomValidation = import('./analyzer.js').CustomValidation;
+export type OrderingViolation = import('./analyzer.js').OrderingViolation;
+export type AnalysisResultWithOrdering = import('./analyzer.js').AnalysisResultWithOrdering;
+export type AnalyzeHeadOptions = import('./analyzer.js').AnalyzeHeadOptions;
+/**
+ * @typedef {import('./analyzer.js').AnalysisResult} AnalysisResult
+ * @typedef {import('./analyzer.js').WeightInfo} WeightInfo
+ * @typedef {import('./analyzer.js').ValidationWarning} ValidationWarning
+ * @typedef {import('./analyzer.js').CustomValidation} CustomValidation
+ * @typedef {import('./analyzer.js').OrderingViolation} OrderingViolation
+ * @typedef {import('./analyzer.js').AnalysisResultWithOrdering} AnalysisResultWithOrdering
+ * @typedef {import('./analyzer.js').AnalyzeHeadOptions} AnalyzeHeadOptions
+ */
+export { ElementWeights, getWeight, getHeadWeights, isMeta, isTitle, isPreconnect, isAsyncScript, isImportStyles, isSyncScript, isSyncStyles, isPreload, isDeferScript, isPrefetchPrerender, isOriginTrial, isMetaCSP } from './lib/rules.js';
+export { VALID_HEAD_ELEMENTS, isValidElement, hasValidationWarning, getValidationWarnings, getCustomValidations } from './lib/validation.js';
+export { BrowserAdapter } from './adapters/browser.js';
+export { AdapterInterface, validateAdapter } from './adapters/adapter.js';

package/node_modules/@rviscomi/capo.js/dist/types/lib/colors.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Generate color swatches for a given hue
+ * @param {number} hue
+ * @returns {string[]}
+ */
+export declare function generateSwatches(hue: number): string[];
+/** @type {string[]} */
+export declare const DEFAULT: string[];
+/** @type {string[]} */
+export declare const PINK: string[];
+/** @type {string[]} */
+export declare const BLUE: string[];
+/** @type {Record<string, string[]>} */
+export declare const Palettes: Record<string, string[]>;
+/**
+ * Get striped background gradient for invalid element visualization
+ * @param {string} elementColor
+ * @returns {string}
+ */
+export declare function getInvalidBackgroundColor(elementColor: string): string;

package/node_modules/@rviscomi/capo.js/dist/types/lib/io.d.ts

@@ -0,0 +1,166 @@
+export type Options = import('./options.js').Options;
+export type AnalysisResult = import('../analyzer.js').AnalysisResult;
+export type ConsoleOutput = {
+    log: (...args: any[]) => void;
+    warn: (...args: any[]) => void;
+    error: (...args: any[]) => void;
+    groupCollapsed: (...args: any[]) => void;
+    groupEnd: () => void;
+};
+export type HeadWeightInfo = {
+    element?: any;
+    weight: number;
+    isValid?: boolean;
+    customValidations?: Record<string, any>;
+};
+export type ElementVisualization = {
+    visual: string;
+    style: string;
+};
+export type HeadVisualization = {
+    visual: string;
+    styles: string[];
+};
+/**
+ * @typedef {import('./options.js').Options} Options
+ * @typedef {import('../analyzer.js').AnalysisResult} AnalysisResult
+ *
+ * @typedef {Object} ConsoleOutput
+ * @property {(...args: any[]) => void} log
+ * @property {(...args: any[]) => void} warn
+ * @property {(...args: any[]) => void} error
+ * @property {(...args: any[]) => void} groupCollapsed
+ * @property {() => void} groupEnd
+ *
+ * @typedef {Object} HeadWeightInfo
+ * @property {any} [element]
+ * @property {number} weight
+ * @property {boolean} [isValid]
+ * @property {Record<string, any>} [customValidations]
+ *
+ * @typedef {Object} ElementVisualization
+ * @property {string} visual
+ * @property {string} style
+ *
+ * @typedef {Object} HeadVisualization
+ * @property {string} visual
+ * @property {string[]} styles
+ */
+export declare class IO {
+    document: Document | null;
+    options: import("./options.js").Options;
+    console: any;
+    isStaticHead: boolean;
+    /** @type {any} */
+    head: any;
+    /**
+     * @param {Document|null} document
+     * @param {Options} options
+     * @param {ConsoleOutput|any} [output=window.console]
+     */
+    constructor(document: Document | null, options: Options, output?: ConsoleOutput | any);
+    /**
+     * @param {string} html
+     * @returns {string}
+     */
+    static formatStaticHeadHTML(html: string): string;
+    /**
+     * @param {any} head
+     */
+    initFromStaticHead(head: any): void;
+    /**
+     * @param {string} html
+     */
+    initFromHTML(html: string): void;
+    /**
+     * @returns {Promise<void>}
+     */
+    init(): Promise<void>;
+    /**
+     * @returns {Promise<string>}
+     */
+    getStaticHTML(): Promise<string>;
+    /**
+     * @returns {any}
+     */
+    getHead(): any;
+    /**
+     * @param {any} element
+     * @returns {string}
+     */
+    stringifyElement(element: any): string;
+    /**
+     * @param {any} element
+     * @returns {any}
+     */
+    getLoggableElement(element: any): any;
+    /**
+     * Create an element from a CSS selector
+     * @param {string} selector
+     * @returns {any}
+     */
+    createElementFromSelector(selector: string): any;
+    /**
+     * @param {AnalysisResult} result
+     * @returns {HeadWeightInfo[]}
+     */
+    logAnalysis(result: AnalysisResult): HeadWeightInfo[];
+    /**
+     * @param {Object} params
+     * @param {number|string} params.weight
+     * @param {string} params.selector
+     * @param {string} params.html
+     * @param {boolean} [params.isValid]
+     * @param {Record<string, any>} [params.customValidations]
+     */
+    logElementFromSelector({ weight, selector, html, isValid, customValidations }: {
+        weight: number | string;
+        selector: string;
+        html: string;
+        isValid?: boolean;
+        customValidations?: Record<string, any>;
+    }): void;
+    /**
+     * @param {Object} params
+     * @param {ElementVisualization} params.viz
+     * @param {number} params.weight
+     * @param {any} params.element
+     * @param {boolean} [params.isValid]
+     * @param {Record<string, any>} [params.customValidations]
+     * @param {boolean} [params.omitPrefix]
+     */
+    logElement({ viz, weight, element, isValid, customValidations, omitPrefix }: {
+        viz: ElementVisualization;
+        weight: number;
+        element: any;
+        isValid?: boolean;
+        customValidations?: Record<string, any>;
+        omitPrefix?: boolean;
+    }): void;
+    /**
+     * @param {Array<import('../analyzer.js').ValidationWarning>} warnings
+     */
+    logValidationWarnings(warnings: Array<import('../analyzer.js').ValidationWarning>): void;
+    /**
+     * @param {number} weight
+     * @returns {string}
+     */
+    getColor(weight: number): string;
+    /**
+     * @param {HeadWeightInfo[]} elements
+     * @returns {HeadVisualization}
+     */
+    getHeadVisualization(elements: HeadWeightInfo[]): HeadVisualization;
+    /**
+     * @param {number} weight
+     * @param {boolean} [isValid=true]
+     * @returns {ElementVisualization}
+     */
+    getElementVisualization(weight: number, isValid?: boolean): ElementVisualization;
+    /**
+     * @param {string} groupName
+     * @param {any} headElement
+     * @param {HeadWeightInfo[]} headWeights
+     */
+    visualizeHead(groupName: string, headElement: any, headWeights: HeadWeightInfo[]): void;
+}