uilint-core 0.2.97 → 0.2.99

package/dist/index-K_PXN36M.d.ts

@@ -0,0 +1,643 @@
+/**
+ * Core types for UILint
+ */
+interface UILintIssue {
+    id: string;
+    type: "color" | "typography" | "spacing" | "component" | "responsive" | "accessibility";
+    message: string;
+    element?: string;
+    selector?: string;
+    currentValue?: string;
+    expectedValue?: string;
+    suggestion?: string;
+}
+interface StyleGuide {
+    colors: ColorRule[];
+    typography: TypographyRule[];
+    spacing: SpacingRule[];
+    components: ComponentRule[];
+}
+interface ColorRule {
+    name: string;
+    value: string;
+    usage: string;
+}
+interface TypographyRule {
+    element: string;
+    fontFamily?: string;
+    fontSize?: string;
+    fontWeight?: string;
+    lineHeight?: string;
+}
+interface SpacingRule {
+    name: string;
+    value: string;
+}
+interface ComponentRule {
+    name: string;
+    styles: string[];
+}
+interface ExtractedStyles {
+    colors: Map<string, number>;
+    fontSizes: Map<string, number>;
+    fontFamilies: Map<string, number>;
+    fontWeights: Map<string, number>;
+    spacing: Map<string, number>;
+    borderRadius: Map<string, number>;
+}
+interface SerializedStyles {
+    colors: Record<string, number>;
+    fontSizes: Record<string, number>;
+    fontFamilies: Record<string, number>;
+    fontWeights: Record<string, number>;
+    spacing: Record<string, number>;
+    borderRadius: Record<string, number>;
+}
+interface DOMSnapshot {
+    html: string;
+    styles: ExtractedStyles;
+    elementCount: number;
+    timestamp: number;
+}
+interface AnalysisResult {
+    issues: UILintIssue[];
+    suggestedStyleGuide?: string;
+    analysisTime: number;
+}
+/**
+ * Lightweight issue type used for per-source scanning (e.g. via data-loc).
+ * This intentionally differs from `UILintIssue` (which is for styleSummary analysis).
+ */
+interface UILintScanIssue {
+    /** Line number in the source file (1-based). */
+    line?: number;
+    /** Human-readable description of the issue. */
+    message: string;
+    /** Optional data-loc reference (format: "path:line:column") */
+    dataLoc?: string;
+}
+interface UILintSourceScanResult {
+    issues: UILintScanIssue[];
+}
+/**
+ * Represents an active generation span that can be ended with output data.
+ * Returned by onGenerationStart when instrumentation is enabled.
+ */
+interface InstrumentationSpan {
+    /** End the span with the generation output and optional usage metrics */
+    end: (output: string, usage?: {
+        promptTokens?: number;
+        completionTokens?: number;
+        totalTokens?: number;
+        error?: string;
+    }) => void;
+}
+/**
+ * Optional instrumentation callbacks for LLM observability.
+ * Allows plugging in any observability tool (Langfuse, OpenTelemetry, etc.)
+ * without adding hard dependencies to uilint-core.
+ */
+interface LLMInstrumentationCallbacks {
+    /**
+     * Called when an LLM generation starts.
+     * Return an InstrumentationSpan to track the generation, or void to skip.
+     */
+    onGenerationStart?: (params: {
+        /** Operation name (e.g., "ollama-generate", "analyze-styles") */
+        name: string;
+        /** Model identifier */
+        model: string;
+        /** The prompt sent to the LLM */
+        prompt: string;
+        /** Optional metadata */
+        metadata?: Record<string, unknown>;
+    }) => InstrumentationSpan | void;
+}
+interface OllamaClientOptions {
+    baseUrl?: string;
+    model?: string;
+    timeout?: number;
+    /** Optional instrumentation callbacks for observability (Langfuse, OpenTelemetry, etc.) */
+    instrumentation?: LLMInstrumentationCallbacks;
+}
+type StreamProgressCallback = (latestLine: string, fullResponse: string, 
+/** The text delta just received (optional, for printing raw streamed output) */
+delta?: string, 
+/**
+ * The "thinking" delta just received (optional, for models that support Ollama's `think`).
+ * For chat this comes from `chunk.message.thinking`; for generate this comes from `chunk.thinking`.
+ */
+thinkingDelta?: string) => void;
+interface ExtractedStyleValues {
+    colors: string[];
+    fontSizes: string[];
+    fontFamilies: string[];
+    spacing: string[];
+    borderRadius: string[];
+}
+interface TailwindThemeTokens {
+    configPath: string;
+    colors: string[];
+    spacingKeys: string[];
+    borderRadiusKeys: string[];
+    fontFamilyKeys: string[];
+    fontSizeKeys: string[];
+}
+
+/**
+ * LLM prompt builders for UILint analysis
+ */
+/**
+ * Builds a prompt for style analysis
+ */
+declare function buildAnalysisPrompt(styleSummary: string, styleGuide: string | null): string;
+interface BuildSourceAnalysisPromptOptions {
+    /**
+     * Optional filename/path for extra context in the prompt.
+     */
+    filePath?: string;
+    /**
+     * Optional hint about language (e.g. tsx, jsx, html).
+     */
+    languageHint?: string;
+    /**
+     * Optional additional context (e.g., Tailwind tokens, extracted utilities).
+     * Keep this concise; it's appended verbatim.
+     */
+    extraContext?: string;
+}
+/**
+ * Builds a prompt for analyzing a raw source file/snippet (TSX/JSX/etc) directly,
+ * without attempting to parse it as HTML/DOM.
+ */
+declare function buildSourceAnalysisPrompt(source: string, styleGuide: string | null, options?: BuildSourceAnalysisPromptOptions): string;
+interface BuildSourceScanPromptOptions {
+    /**
+     * Display filename/path for context in the prompt.
+     */
+    filePath?: string;
+    /**
+     * Optional focus target for manual scan UX.
+     */
+    componentName?: string;
+    componentLine?: number;
+    /**
+     * If true, the scan is for the selected element + children (UI text only).
+     */
+    includeChildren?: boolean;
+    /**
+     * Optional list of data-loc values (format: "path:line:column") that the model MUST
+     * restrict issues to (so UI can highlight exactly).
+     */
+    dataLocs?: string[];
+}
+/**
+ * Builds a prompt for scanning a source file/snippet for issues that can be mapped
+ * back to rendered DOM elements via `data-loc`.
+ *
+ * Response schema (JSON):
+ * { "issues": [{ "line"?: number, "message": string, "dataLoc"?: string }] }
+ */
+declare function buildSourceScanPrompt(sourceCode: string, styleGuide: string | null, options?: BuildSourceScanPromptOptions): string;
+/**
+ * Builds a prompt for style guide generation
+ */
+declare function buildStyleGuidePrompt(styleSummary: string): string;
+
+/**
+ * Ollama API client for LLM interactions
+ */
+
+declare class OllamaClient {
+    private baseUrl;
+    private model;
+    private timeout;
+    private instrumentation?;
+    constructor(options?: OllamaClientOptions);
+    /**
+     * Low-level completion API for custom prompts (used by installers/tools).
+     *
+     * When `json` is true, Ollama is requested to emit JSON (best-effort).
+     */
+    complete(prompt: string, options?: {
+        json?: boolean;
+        stream?: boolean;
+        onProgress?: StreamProgressCallback;
+    }): Promise<string>;
+    /**
+     * Analyzes styles and returns issues
+     */
+    analyzeStyles(styleSummary: string, styleGuide: string | null, onProgress?: StreamProgressCallback): Promise<AnalysisResult>;
+    /**
+     * Analyzes a raw source file/snippet (TSX/JSX/etc) directly and returns issues.
+     * This bypasses HTML/DOM parsing entirely.
+     */
+    analyzeSource(source: string, styleGuide: string | null, onProgress?: StreamProgressCallback, options?: BuildSourceAnalysisPromptOptions): Promise<AnalysisResult>;
+    /**
+     * Generates a style guide from detected styles
+     */
+    generateStyleGuide(styleSummary: string): Promise<string | null>;
+    /**
+     * Core generate method that calls Ollama API
+     */
+    private generate;
+    /**
+     * Streaming generate method that calls Ollama API with streaming
+     * and reports progress via callback
+     */
+    private generateStreaming;
+    /**
+     * Parses issues from LLM response
+     */
+    private parseIssuesResponse;
+    /**
+     * Checks if Ollama is available
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Gets the current model
+     */
+    getModel(): string;
+    /**
+     * Sets the model
+     */
+    setModel(model: string): void;
+    /**
+     * Sets instrumentation callbacks for observability.
+     * This allows configuring instrumentation after construction.
+     */
+    setInstrumentation(instrumentation: LLMInstrumentationCallbacks | undefined): void;
+    /**
+     * Returns true if instrumentation is currently configured.
+     */
+    hasInstrumentation(): boolean;
+}
+declare function getOllamaClient(options?: OllamaClientOptions): OllamaClient;
+
+/**
+ * Single source of truth for Ollama defaults used across the monorepo.
+ */
+/**
+ * Default Ollama model used when none is provided.
+ *
+ * Note: This should match the model we recommend users `ollama pull`.
+ */
+declare const UILINT_DEFAULT_OLLAMA_MODEL = "qwen3-coder:30b";
+
+interface FormatViolationsOptions {
+    /**
+     * Optional context label (e.g., filename) to include as a single header line.
+     * Keep this empty for the most minimal output.
+     */
+    context?: string;
+    /**
+     * Include the trailing "consult the style guide" message.
+     * Defaults to true.
+     */
+    includeFooter?: boolean;
+    /**
+     * Override the footer message.
+     */
+    footerMessage?: string;
+}
+/**
+ * Ensures issues are safe/minimal to print or serialize:
+ * - drops `suggestion` (we only want violations)
+ * - trims string fields
+ */
+declare function sanitizeIssues(issues: UILintIssue[]): UILintIssue[];
+/**
+ * Minimal human-readable rendering of violations.
+ * Intended for CLI/MCP text output.
+ */
+declare function formatViolationsText(issues: UILintIssue[], options?: FormatViolationsOptions): string;
+
+/**
+ * Style extraction from DOM elements
+ */
+
+/**
+ * Extracts all computed styles from elements in the document
+ * Works in both browser and JSDOM environments
+ */
+declare function extractStyles(root: Element | Document, getComputedStyle: (el: Element) => CSSStyleDeclaration): ExtractedStyles;
+/**
+ * Extracts styles from browser DOM (uses window.getComputedStyle)
+ */
+declare function extractStylesFromDOM(root?: Element | Document): ExtractedStyles;
+/**
+ * Converts ExtractedStyles maps to plain objects for serialization
+ */
+declare function serializeStyles(styles: ExtractedStyles): SerializedStyles;
+/**
+ * Converts SerializedStyles back to ExtractedStyles
+ */
+declare function deserializeStyles(serialized: SerializedStyles): ExtractedStyles;
+/**
+ * Creates a summary of extracted styles for LLM analysis
+ */
+declare function createStyleSummary(styles: ExtractedStyles, options?: CreateStyleSummaryOptions): string;
+interface CreateStyleSummaryOptions {
+    /**
+     * Optional HTML/TSX-ish string used to extract utility classes (Tailwind etc).
+     */
+    html?: string;
+    /**
+     * Optional Tailwind theme tokens (typically from tailwind.config.*).
+     */
+    tailwindTheme?: TailwindThemeTokens | null;
+}
+/**
+ * Truncates HTML to a maximum length
+ */
+declare function truncateHTML(html: string, maxLength?: number): string;
+
+/**
+ * Parse Markdown style guides into structured data
+ */
+
+/**
+ * Parses a Markdown style guide into a structured object
+ */
+declare function parseStyleGuide(markdown: string): StyleGuide;
+/**
+ * Parses sections from a Markdown style guide (simpler format)
+ */
+declare function parseStyleGuideSections(content: string): Record<string, string>;
+/**
+ * Extracts specific values from the style guide
+ */
+declare function extractStyleValues(content: string): ExtractedStyleValues;
+interface TailwindAllowlist {
+    allowAnyColor: boolean;
+    allowStandardSpacing: boolean;
+    allowedTailwindColors: Set<string>;
+    allowedUtilities: Set<string>;
+    allowedSpacingKeys: Set<string>;
+    allowedBorderRadiusKeys: Set<string>;
+    allowedFontSizeKeys: Set<string>;
+    allowedFontFamilyKeys: Set<string>;
+}
+/**
+ * Extract Tailwind / utility-class allowlist configuration from a style guide.
+ *
+ * Expected formats:
+ * - A JSON code block inside a "## Tailwind" section (preferred; produced by UILint)
+ * - Fallback: inline backticked utilities within the Tailwind section
+ */
+declare function extractTailwindAllowlist(content: string): TailwindAllowlist;
+
+/**
+ * Generate Markdown style guides from extracted styles
+ */
+
+/**
+ * Generates a Markdown style guide from extracted styles
+ */
+interface GenerateStyleGuideOptions {
+    /**
+     * Optional HTML/TSX-ish string used to extract utility classes (Tailwind etc).
+     */
+    html?: string;
+    /**
+     * Optional Tailwind theme tokens (typically from tailwind.config.*).
+     */
+    tailwindTheme?: TailwindThemeTokens | null;
+}
+declare function generateStyleGuideFromStyles(styles: ExtractedStyles, options?: GenerateStyleGuideOptions): string;
+/**
+ * Converts a StyleGuide object back to Markdown
+ */
+declare function styleGuideToMarkdown(guide: StyleGuide): string;
+
+/**
+ * Style guide schema and utilities
+ */
+
+/**
+ * Creates an empty style guide structure
+ */
+declare function createEmptyStyleGuide(): StyleGuide;
+/**
+ * Validates a style guide object
+ */
+declare function validateStyleGuide(guide: unknown): guide is StyleGuide;
+/**
+ * Merges detected styles into an existing style guide
+ */
+declare function mergeStyleGuides(existing: StyleGuide, detected: Partial<StyleGuide>): StyleGuide;
+/**
+ * Creates a color rule
+ */
+declare function createColorRule(name: string, value: string, usage?: string): ColorRule;
+/**
+ * Creates a typography rule
+ */
+declare function createTypographyRule(element: string, options?: Partial<Omit<TypographyRule, "element">>): TypographyRule;
+/**
+ * Creates a spacing rule
+ */
+declare function createSpacingRule(name: string, value: string): SpacingRule;
+/**
+ * Creates a component rule
+ */
+declare function createComponentRule(name: string, styles: string[]): ComponentRule;
+
+/**
+ * Types for UI consistency analysis
+ */
+/**
+ * Relevant computed styles for consistency checking
+ */
+interface StyleSnapshot {
+    fontSize?: string;
+    fontWeight?: string;
+    color?: string;
+    backgroundColor?: string;
+    padding?: string;
+    borderRadius?: string;
+    border?: string;
+    boxShadow?: string;
+    gap?: string;
+}
+/**
+ * Element roles for grouping and analysis
+ */
+type ElementRole = "button" | "link" | "heading" | "input" | "card" | "container" | "text" | "other";
+/**
+ * Snapshot of a single DOM element with its styles and context
+ */
+interface ElementSnapshot {
+    /** Unique ID mapping to data-elements attribute, e.g. "el-47" */
+    id: string;
+    /** HTML tag name */
+    tag: string;
+    /** Inferred semantic role */
+    role: ElementRole;
+    /** Truncated innerText (max 50 chars) */
+    text: string;
+    /** From data-ui-component attribute if present */
+    component?: string;
+    /** Ancestor context like "header > nav" */
+    context: string;
+    /** Relevant computed styles */
+    styles: StyleSnapshot;
+    /** Element dimensions */
+    rect: {
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Elements grouped by role for batch analysis
+ */
+interface GroupedSnapshot {
+    buttons: ElementSnapshot[];
+    headings: ElementSnapshot[];
+    cards: ElementSnapshot[];
+    links: ElementSnapshot[];
+    inputs: ElementSnapshot[];
+    containers: ElementSnapshot[];
+}
+/**
+ * Violation categories detected by consistency analysis
+ */
+type ViolationCategory = "spacing" | "color" | "typography" | "sizing" | "borders" | "shadows";
+/**
+ * Severity levels for violations
+ */
+type ViolationSeverity = "error" | "warning" | "info";
+/**
+ * A consistency violation detected between similar elements
+ */
+interface Violation {
+    /** Element IDs involved in the violation, e.g. ["el-3", "el-7"] */
+    elementIds: string[];
+    /** Category of the inconsistency */
+    category: ViolationCategory;
+    /** Severity level */
+    severity: ViolationSeverity;
+    /** Human-readable description */
+    message: string;
+    /** Detailed information about the violation */
+    details: {
+        /** The CSS property that differs */
+        property: string;
+        /** The differing values found */
+        values: string[];
+        /** Optional suggestion for fixing */
+        suggestion?: string;
+    };
+}
+/**
+ * Result of consistency analysis
+ */
+interface ConsistencyResult {
+    violations: Violation[];
+    /** Number of elements analyzed */
+    elementCount: number;
+    /** Time taken in milliseconds */
+    analysisTime: number;
+}
+
+/**
+ * LLM prompt builders for UI consistency analysis
+ */
+
+/**
+ * Builds a single prompt for analyzing ALL element groups
+ * This reduces LLM calls to 1 for better performance
+ */
+declare function buildConsistencyPrompt(snapshot: GroupedSnapshot): string;
+/**
+ * Counts total elements across all groups
+ */
+declare function countElements(snapshot: GroupedSnapshot): number;
+/**
+ * Checks if a snapshot has any groups worth analyzing (2+ elements)
+ */
+declare function hasAnalyzableGroups(snapshot: GroupedSnapshot): boolean;
+
+/**
+ * Consistency analysis logic - shared between CLI and API routes
+ */
+
+/**
+ * Parses and validates a GroupedSnapshot from JSON string
+ */
+declare function parseGroupedSnapshot(json: string): GroupedSnapshot | null;
+/**
+ * Parses violations from LLM response with defensive handling
+ */
+declare function parseViolationsResponse(response: string): Violation[];
+/**
+ * Validates and filters violations to ensure correct structure
+ */
+declare function validateViolations(violations: unknown[]): Violation[];
+interface AnalyzeConsistencyOptions {
+    /** Ollama model to use */
+    model?: string;
+    /** Ollama base URL */
+    baseUrl?: string;
+}
+/**
+ * Analyzes a grouped snapshot for UI consistency violations
+ * This is the main entry point for consistency analysis
+ */
+declare function analyzeConsistency(snapshot: GroupedSnapshot, options?: AnalyzeConsistencyOptions): Promise<ConsistencyResult>;
+/**
+ * Formats violations for plain text output
+ */
+declare function formatConsistencyViolations(violations: Violation[]): string;
+
+/**
+ * Shared logger for UILint packages
+ * Outputs styled messages to stderr to avoid interfering with stdout
+ */
+
+/**
+ * Log a message to the console (silent during tests).
+ * Use this for development/debugging logs that shouldn't appear in test output.
+ */
+declare function devLog(...args: unknown[]): void;
+/**
+ * Log a warning to the console (silent during tests).
+ * Use this for development warnings that shouldn't appear in test output.
+ */
+declare function devWarn(...args: unknown[]): void;
+/**
+ * Log an error to the console (silent during tests).
+ * Use this for development errors that shouldn't appear in test output.
+ */
+declare function devError(...args: unknown[]): void;
+/**
+ * Log an info message to stderr
+ */
+declare function logInfo(message: string): void;
+/**
+ * Log a success message to stderr
+ */
+declare function logSuccess(message: string): void;
+/**
+ * Log a warning message to stderr
+ */
+declare function logWarning(message: string): void;
+/**
+ * Log an error message to stderr
+ */
+declare function logError(message: string): void;
+/**
+ * Log a debug message to stderr (dimmed)
+ */
+declare function logDebug(message: string): void;
+/**
+ * Create a progress logger that updates the same line
+ * Returns methods to update and finish the progress
+ */
+declare function createProgress(initialMessage: string): {
+    update: (message: string) => void;
+    succeed: (message: string) => void;
+    fail: (message: string) => void;
+};
+
+export { type ElementRole as $, type AnalysisResult as A, deserializeStyles as B, type ColorRule as C, type DOMSnapshot as D, type ExtractedStyles as E, createStyleSummary as F, truncateHTML as G, parseStyleGuide as H, type InstrumentationSpan as I, parseStyleGuideSections as J, extractStyleValues as K, type LLMInstrumentationCallbacks as L, extractTailwindAllowlist as M, generateStyleGuideFromStyles as N, type OllamaClientOptions as O, styleGuideToMarkdown as P, createEmptyStyleGuide as Q, validateStyleGuide as R, type StreamProgressCallback as S, type TailwindThemeTokens as T, type UILintIssue as U, mergeStyleGuides as V, createColorRule as W, createTypographyRule as X, createSpacingRule as Y, createComponentRule as Z, type StyleSnapshot as _, logSuccess as a, type ElementSnapshot as a0, type GroupedSnapshot as a1, type ViolationCategory as a2, type ViolationSeverity as a3, type Violation as a4, type ConsistencyResult as a5, type AnalyzeConsistencyOptions as a6, buildConsistencyPrompt as a7, countElements as a8, hasAnalyzableGroups as a9, parseGroupedSnapshot as aa, parseViolationsResponse as ab, validateViolations as ac, analyzeConsistency as ad, formatConsistencyViolations as ae, devLog as af, devWarn as ag, devError as ah, logWarning as b, logError as c, logDebug as d, createProgress as e, type UILintScanIssue as f, type UILintSourceScanResult as g, type StyleGuide as h, type TypographyRule as i, type SpacingRule as j, type ComponentRule as k, logInfo as l, type SerializedStyles as m, type ExtractedStyleValues as n, OllamaClient as o, getOllamaClient as p, UILINT_DEFAULT_OLLAMA_MODEL as q, buildAnalysisPrompt as r, buildSourceAnalysisPrompt as s, buildSourceScanPrompt as t, buildStyleGuidePrompt as u, formatViolationsText as v, sanitizeIssues as w, extractStyles as x, extractStylesFromDOM as y, serializeStyles as z };