@qontinui/ui-bridge 0.3.0 → 0.3.1

package/dist/specs/index.d.mts

@@ -0,0 +1,365 @@
+import { a8 as SearchCriteria, f as AssertionType, e as AssertionResult, A as AIDiscoveredElement, d as AssertionRequest } from '../types-D_ypYl3T.mjs';
+import { A as AssertionConfig } from '../assertions-CTw1hfOx.mjs';
+import { D as DiscoveredElement } from '../types-CJGrBEhC.mjs';
+import '../types-suaYwWWg.mjs';
+
+/**
+ * Spec Types
+ *
+ * Type definitions for the UI Bridge specification system.
+ * Specs define declarative assertions about UI elements that can be
+ * authored, stored, executed, and used for regression testing.
+ */
+
+type SpecCategory = 'element-presence' | 'accessibility' | 'form-validation' | 'state-consistency' | 'modal-dialog' | 'navigation' | 'cross-page-consistency' | 'custom';
+type SpecSeverity = 'critical' | 'warning' | 'info';
+type SpecSource = 'auto' | 'manual' | 'ai-generated';
+/**
+ * Unified target for spec assertions.
+ * Bridges to AssertionRequest.target (string | SearchCriteria).
+ */
+type SpecTarget = {
+    type: 'elementId';
+    elementId: string;
+    label?: string;
+} | {
+    type: 'search';
+    criteria: SearchCriteria;
+    label?: string;
+};
+/**
+ * A condition that must be met for an assertion to be evaluated.
+ * If the condition is not met, the assertion is skipped (passes with no opinion).
+ *
+ * Use case: "Button is disabled WHEN runner is not connected"
+ * - The assertion only has an opinion when the runner is NOT connected
+ * - When connected, the assertion should skip (not fail)
+ */
+type AssertionCondition = {
+    /** Check if a target element exists */
+    type: 'exists';
+    target: SpecTarget;
+} | {
+    /** Check if a target element does NOT exist */
+    type: 'notExists';
+    target: SpecTarget;
+} | {
+    /** Check if a target element has specific text content */
+    type: 'hasText';
+    target: SpecTarget;
+    text: string;
+};
+/**
+ * A single spec assertion — wraps an AssertionRequest with metadata.
+ */
+interface SpecAssertion {
+    id: string;
+    description: string;
+    category: SpecCategory;
+    severity: SpecSeverity;
+    target: SpecTarget;
+    /** Strongly typed assertion type from ui-bridge/ai */
+    assertionType: AssertionType;
+    expected?: unknown;
+    attributeName?: string;
+    propertyName?: string;
+    message?: string;
+    timeout?: number;
+    source: SpecSource;
+    reviewed: boolean;
+    enabled: boolean;
+    notes?: string;
+    /**
+     * Optional condition that must be met for this assertion to be evaluated.
+     * If condition is not met, the assertion is skipped (passes with no opinion).
+     *
+     * Example: "A is false when B is false" → condition checks if B is false,
+     * and only then evaluates whether A is false. If B is true, skip.
+     */
+    condition?: AssertionCondition;
+}
+/**
+ * A named collection of related spec assertions.
+ */
+interface SpecGroup {
+    id: string;
+    name: string;
+    description: string;
+    category: SpecCategory;
+    assertions: SpecAssertion[];
+    stateId?: string;
+    transitionId?: string;
+    source: SpecSource;
+    tags?: string[];
+}
+interface SpecMetadata {
+    component?: string;
+    author?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    pageUrl?: string;
+    tags?: string[];
+    /** Explicit element source: "control" for runner UI, "external" for browser tab */
+    elementSource?: 'control' | 'external';
+    [key: string]: unknown;
+}
+/**
+ * Top-level spec config — the JSON file format.
+ */
+interface SpecConfig {
+    version: '1.0.0';
+    description?: string;
+    groups: SpecGroup[];
+    /** Ungrouped assertions (convenience for simple specs) */
+    assertions?: SpecAssertion[];
+    metadata?: SpecMetadata;
+}
+interface SpecAssertionResult {
+    assertionId: string;
+    groupId?: string;
+    severity: SpecSeverity;
+    category: SpecCategory;
+    skipped: boolean;
+    /** Reason for skipping (if skipped) */
+    skipReason?: 'disabled' | 'condition_not_met' | 'filtered';
+    /** The underlying assertion result (null if skipped) */
+    result: AssertionResult | null;
+}
+interface SpecGroupResult {
+    groupId: string;
+    groupName: string;
+    assertionResults: SpecAssertionResult[];
+    passedCount: number;
+    failedCount: number;
+    skippedCount: number;
+    passed: boolean;
+    durationMs: number;
+    timestamp: number;
+}
+interface SpecExecutionResult {
+    specVersion: string;
+    groupResults: SpecGroupResult[];
+    ungroupedResults: SpecAssertionResult[];
+    totalAssertions: number;
+    passedCount: number;
+    failedCount: number;
+    skippedCount: number;
+    passed: boolean;
+    durationMs: number;
+    timestamp: number;
+}
+interface SpecExecutionOptions {
+    categories?: SpecCategory[];
+    severities?: SpecSeverity[];
+    groupIds?: string[];
+    assertionIds?: string[];
+    stopOnFailure?: boolean;
+    skipUnreviewed?: boolean;
+    timeout?: number;
+}
+interface SpecCoverage {
+    totalElements: number;
+    specifiedElements: number;
+    coveragePercent: number;
+    specifiedIds: string[];
+    unspecifiedIds: string[];
+    timestamp: number;
+}
+type SpecEventType = 'spec:loaded' | 'spec:unloaded' | 'spec:updated' | 'spec:cleared' | 'spec:assertion-added' | 'spec:assertion-removed' | 'spec:group-added' | 'spec:group-removed';
+interface SpecEvent {
+    type: SpecEventType;
+    specId?: string;
+    groupId?: string;
+    assertionId?: string;
+    timestamp: number;
+}
+declare const SPEC_CONFIG_VERSION = "1.0.0";
+declare const SPEC_FILE_EXTENSION = ".spec.uibridge.json";
+declare const VALID_ASSERTION_TYPES: readonly AssertionType[];
+declare const VALID_SPEC_CATEGORIES: readonly SpecCategory[];
+declare const VALID_SPEC_SEVERITIES: readonly SpecSeverity[];
+declare const VALID_SPEC_SOURCES: readonly SpecSource[];
+
+/**
+ * Spec Validator
+ *
+ * Structural validation for .spec.uibridge.json files.
+ * No JSON Schema dependency — validates manually.
+ */
+
+interface ValidationError {
+    path: string;
+    message: string;
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+}
+declare function isValidAssertionType(value: unknown): value is AssertionType;
+declare function isValidSpecCategory(value: unknown): value is SpecCategory;
+declare function isValidSpecSeverity(value: unknown): value is SpecSeverity;
+declare function isValidSpecSource(value: unknown): value is SpecSource;
+declare function validateSpecAssertion(data: unknown, path?: string): ValidationError[];
+declare function validateSpecGroup(data: unknown, path?: string): ValidationError[];
+declare function validateSpecConfig(data: unknown): ValidationResult;
+
+/**
+ * Spec Migration
+ *
+ * Converts legacy TestGeneratorOutput format (from qontinui-schemas)
+ * to the new SpecConfig format.
+ */
+
+interface LegacyTestTarget {
+    type: 'elementId' | 'formId' | 'modalId';
+    elementId?: string;
+    formId?: string;
+    modalId?: string;
+    label?: string;
+}
+interface LegacyTestAssertion {
+    id: string;
+    description: string;
+    category: string;
+    severity: string;
+    target: LegacyTestTarget;
+    assertionType: string;
+    expected?: unknown;
+    attributeName?: string;
+    source: string;
+    reviewed: boolean;
+    enabled: boolean;
+    notes?: string;
+}
+interface LegacyTestSpecification {
+    id: string;
+    name: string;
+    description: string;
+    category: string;
+    assertions: LegacyTestAssertion[];
+    stateId: string;
+    transitionId?: string;
+    source: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface LegacyTestGeneratorOutput {
+    version: string;
+    projectId?: string;
+    generatorType?: string;
+    states?: unknown[];
+    transitions?: unknown[];
+    testSpecifications: LegacyTestSpecification[];
+    snapshotMetadata?: Record<string, unknown>;
+    explorationMetadata?: Record<string, unknown>;
+    createdAt?: string;
+    updatedAt?: string;
+}
+/**
+ * Coerce a raw string to a valid AssertionType, or return null.
+ */
+declare function coerceAssertionType(raw: string): AssertionType | null;
+/**
+ * Convert a legacy TestTarget to a SpecTarget.
+ */
+declare function migrateLegacyTarget(legacy: LegacyTestTarget): SpecTarget;
+/**
+ * Convert a legacy TestAssertion to a SpecAssertion.
+ */
+declare function migrateLegacyAssertion(legacy: LegacyTestAssertion): SpecAssertion;
+/**
+ * Convert a legacy TestGeneratorOutput to a SpecConfig.
+ */
+declare function migrateFromTestGeneratorOutput(legacy: LegacyTestGeneratorOutput): SpecConfig;
+
+/**
+ * Spec Store
+ *
+ * In-memory store for spec configs with CRUD operations,
+ * import/export, coverage tracking, and event emission.
+ * Follows the AnnotationStore pattern.
+ */
+
+type SpecListener = (event: SpecEvent) => void;
+interface SpecFilterOptions {
+    categories?: SpecCategory[];
+    severities?: SpecSeverity[];
+    enabledOnly?: boolean;
+    reviewedOnly?: boolean;
+}
+declare class SpecStore {
+    private configs;
+    private listeners;
+    load(specId: string, config: SpecConfig): void;
+    unload(specId: string): boolean;
+    get(specId: string): SpecConfig | undefined;
+    has(specId: string): boolean;
+    getIds(): string[];
+    getAll(): Map<string, SpecConfig>;
+    get count(): number;
+    clear(): void;
+    addGroup(specId: string, group: SpecGroup): boolean;
+    removeGroup(specId: string, groupId: string): boolean;
+    getGroup(specId: string, groupId: string): SpecGroup | undefined;
+    addAssertion(specId: string, groupId: string | null, assertion: SpecAssertion): boolean;
+    removeAssertion(specId: string, groupId: string | null, assertionId: string): boolean;
+    toggleAssertion(specId: string, groupId: string | null, assertionId: string): boolean;
+    markReviewed(specId: string, groupId: string | null, assertionId: string): boolean;
+    getAllAssertions(): SpecAssertion[];
+    filterAssertions(opts: SpecFilterOptions): SpecAssertion[];
+    getCoverage(allElementIds: string[]): SpecCoverage;
+    importConfig(specId: string, config: SpecConfig): boolean;
+    exportConfig(specId: string): SpecConfig | undefined;
+    on(listener: SpecListener): () => void;
+    private emit;
+    private findAssertion;
+}
+declare function getGlobalSpecStore(): SpecStore;
+declare function resetGlobalSpecStore(): void;
+
+/**
+ * Spec Executor
+ *
+ * Converts SpecAssertions to AssertionRequests and delegates
+ * to the existing AssertionExecutor from ui-bridge/ai.
+ */
+
+/**
+ * Resolve a SpecTarget to an AssertionRequest target.
+ *
+ * For elementId targets, returns a SearchCriteria with idPattern for exact
+ * ID matching rather than a raw string (which would be treated as a text search).
+ */
+declare function resolveTarget(target: SpecTarget): string | SearchCriteria;
+declare class SpecExecutor {
+    private assertionExecutor;
+    constructor(config?: Partial<AssertionConfig>);
+    /**
+     * Update the element registry (pass-through to AssertionExecutor).
+     */
+    updateElements(elements: Array<DiscoveredElement | AIDiscoveredElement>): void;
+    /**
+     * Convert a SpecAssertion to an AssertionRequest.
+     */
+    toAssertionRequest(assertion: SpecAssertion): AssertionRequest;
+    /**
+     * Evaluate a condition to determine if an assertion should be executed.
+     * Returns true if the condition is met (assertion should run),
+     * false if condition is not met (assertion should skip/pass).
+     */
+    private evaluateCondition;
+    /**
+     * Execute a single SpecAssertion.
+     */
+    executeAssertion(assertion: SpecAssertion): Promise<SpecAssertionResult>;
+    /**
+     * Execute all assertions in a SpecGroup.
+     */
+    executeGroup(group: SpecGroup, options?: SpecExecutionOptions): Promise<SpecGroupResult>;
+    /**
+     * Execute a full SpecConfig.
+     */
+    execute(config: SpecConfig, options?: SpecExecutionOptions): Promise<SpecExecutionResult>;
+}
+
+export { type AssertionCondition, AssertionType, type LegacyTestAssertion, type LegacyTestGeneratorOutput, type LegacyTestSpecification, type LegacyTestTarget, SPEC_CONFIG_VERSION, SPEC_FILE_EXTENSION, SearchCriteria, type SpecAssertion, type SpecAssertionResult, type SpecCategory, type SpecConfig, type SpecCoverage, type SpecEvent, type SpecEventType, type SpecExecutionOptions, type SpecExecutionResult, SpecExecutor, type SpecFilterOptions, type SpecGroup, type SpecGroupResult, type SpecListener, type SpecMetadata, type SpecSeverity, type SpecSource, SpecStore, type SpecTarget, VALID_ASSERTION_TYPES, VALID_SPEC_CATEGORIES, VALID_SPEC_SEVERITIES, VALID_SPEC_SOURCES, type ValidationError, type ValidationResult, coerceAssertionType, getGlobalSpecStore, isValidAssertionType, isValidSpecCategory, isValidSpecSeverity, isValidSpecSource, migrateFromTestGeneratorOutput, migrateLegacyAssertion, migrateLegacyTarget, resetGlobalSpecStore, resolveTarget, validateSpecAssertion, validateSpecConfig, validateSpecGroup };