driftdetect-core 0.1.0

package/dist/rules/variant-manager.d.ts

@@ -0,0 +1,388 @@
+/**
+ * Variant Manager - Manages intentional deviations from patterns
+ *
+ * Variants allow developers to mark code as intentionally deviating from
+ * established patterns. Once a variant is created, the enforcement system
+ * will stop flagging matching code.
+ *
+ * @requirements 26.1 - THE Variant_System SHALL allow creating named variants of patterns
+ * @requirements 26.2 - THE Variant SHALL specify scope: global, directory, or file
+ * @requirements 26.3 - THE Variant SHALL include a reason explaining why it's intentional
+ * @requirements 26.5 - THE Variant_System SHALL store variants in .drift/patterns/variants/
+ */
+import { EventEmitter } from 'node:events';
+import type { PatternVariant, VariantScope, PatternLocation } from '../store/types.js';
+/**
+ * Input for creating a new variant
+ *
+ * @requirements 26.1 - Create named variants
+ * @requirements 26.2 - Specify scope
+ * @requirements 26.3 - Include reason
+ */
+export interface CreateVariantInput {
+    /** Pattern ID this variant applies to */
+    patternId: string;
+    /** Human-readable name for the variant */
+    name: string;
+    /** Reason explaining why this deviation is intentional */
+    reason: string;
+    /** Scope of the variant */
+    scope: VariantScope;
+    /** Scope value (directory path or file path, depending on scope) */
+    scopeValue?: string;
+    /** Locations covered by this variant */
+    locations: PatternLocation[];
+    /** User who created the variant (optional) */
+    createdBy?: string;
+    /** Description of the variant (optional) */
+    description?: string;
+}
+/**
+ * Input for updating an existing variant
+ */
+export interface UpdateVariantInput {
+    /** Human-readable name for the variant */
+    name?: string;
+    /** Reason explaining why this deviation is intentional */
+    reason?: string;
+    /** Scope of the variant */
+    scope?: VariantScope;
+    /** Scope value (directory path or file path, depending on scope) */
+    scopeValue?: string;
+    /** Locations covered by this variant */
+    locations?: PatternLocation[];
+    /** Whether the variant is active */
+    active?: boolean;
+}
+/**
+ * Query options for filtering variants
+ */
+export interface VariantQuery {
+    /** Filter by pattern ID */
+    patternId?: string;
+    /** Filter by pattern IDs */
+    patternIds?: string[];
+    /** Filter by scope */
+    scope?: VariantScope | VariantScope[];
+    /** Filter by active status */
+    active?: boolean;
+    /** Filter by file path (variants that cover this file) */
+    file?: string;
+    /** Filter by directory path (variants that cover this directory) */
+    directory?: string;
+    /** Search in name and reason */
+    search?: string;
+    /** Filter by creator */
+    createdBy?: string;
+}
+/**
+ * Configuration options for the variant manager
+ */
+export interface VariantManagerConfig {
+    /** Root directory for .drift folder (defaults to project root) */
+    rootDir: string;
+    /** Whether to auto-save changes */
+    autoSave: boolean;
+    /** Debounce time for auto-save in milliseconds */
+    autoSaveDebounce: number;
+    /** Whether to create backup before save */
+    createBackup: boolean;
+    /** Maximum number of backups to keep */
+    maxBackups: number;
+}
+/**
+ * Default variant manager configuration
+ */
+export declare const DEFAULT_VARIANT_MANAGER_CONFIG: VariantManagerConfig;
+/**
+ * Events emitted by the variant manager
+ */
+export type VariantManagerEventType = 'variant:created' | 'variant:updated' | 'variant:deleted' | 'variant:activated' | 'variant:deactivated' | 'file:loaded' | 'file:saved' | 'error';
+/**
+ * Event payload for variant manager events
+ */
+export interface VariantManagerEvent {
+    /** Event type */
+    type: VariantManagerEventType;
+    /** Variant ID (if applicable) */
+    variantId?: string;
+    /** Pattern ID (if applicable) */
+    patternId?: string;
+    /** Additional event data */
+    data?: Record<string, unknown>;
+    /** ISO timestamp of the event */
+    timestamp: string;
+}
+/**
+ * Error thrown when a variant is not found
+ */
+export declare class VariantNotFoundError extends Error {
+    readonly variantId: string;
+    constructor(variantId: string);
+}
+/**
+ * Error thrown when a variant operation fails
+ */
+export declare class VariantManagerError extends Error {
+    readonly errorCause: Error | undefined;
+    constructor(message: string, errorCause?: Error);
+}
+/**
+ * Error thrown when variant input is invalid
+ */
+export declare class InvalidVariantInputError extends Error {
+    readonly field?: string | undefined;
+    constructor(message: string, field?: string | undefined);
+}
+/**
+ * Variant Manager - Manages intentional deviations from patterns
+ *
+ * Variants are stored in .drift/patterns/variants/ directory.
+ * Each variant specifies a scope (global, directory, or file) and
+ * includes a reason explaining why the deviation is intentional.
+ *
+ * @requirements 26.1 - Create named variants of patterns
+ * @requirements 26.2 - Variants specify scope: global, directory, or file
+ * @requirements 26.3 - Variants include reason for deviation
+ * @requirements 26.5 - Variants stored in .drift/patterns/variants/
+ */
+export declare class VariantManager extends EventEmitter {
+    private readonly config;
+    private readonly variantsDir;
+    private variants;
+    private loaded;
+    private dirty;
+    private saveTimeout;
+    constructor(config?: Partial<VariantManagerConfig>);
+    /**
+     * Initialize the variant manager
+     *
+     * Creates necessary directories and loads existing variants.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Ensure the directory structure exists
+     *
+     * @requirements 26.5 - Store variants in .drift/patterns/variants/
+     */
+    private ensureDirectoryStructure;
+    /**
+     * Check if the manager is initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Load all variants from disk
+     *
+     * @requirements 26.5 - Load variants from .drift/patterns/variants/
+     */
+    loadAll(): Promise<void>;
+    /**
+     * Save all variants to disk
+     *
+     * @requirements 26.5 - Persist variants in .drift/patterns/variants/
+     */
+    saveAll(): Promise<void>;
+    /**
+     * Create a backup of a file
+     */
+    private createBackup;
+    /**
+     * Clean up old backups, keeping only the most recent ones
+     */
+    private cleanupBackups;
+    /**
+     * Schedule an auto-save if enabled
+     */
+    private scheduleAutoSave;
+    /**
+     * Create a new variant
+     *
+     * @requirements 26.1 - Create named variants of patterns
+     * @requirements 26.2 - Specify scope: global, directory, or file
+     * @requirements 26.3 - Include reason explaining why it's intentional
+     *
+     * @param input - Variant creation input
+     * @returns The created variant
+     */
+    create(input: CreateVariantInput): PatternVariant;
+    /**
+     * Validate create input
+     */
+    private validateCreateInput;
+    /**
+     * Get a variant by ID
+     *
+     * @param id - Variant ID
+     * @returns The variant or undefined if not found
+     */
+    get(id: string): PatternVariant | undefined;
+    /**
+     * Get a variant by ID, throwing if not found
+     *
+     * @param id - Variant ID
+     * @returns The variant
+     * @throws VariantNotFoundError if variant not found
+     */
+    getOrThrow(id: string): PatternVariant;
+    /**
+     * Check if a variant exists
+     *
+     * @param id - Variant ID
+     * @returns True if variant exists
+     */
+    has(id: string): boolean;
+    /**
+     * Update an existing variant
+     *
+     * @param id - Variant ID
+     * @param updates - Partial variant updates
+     * @returns The updated variant
+     * @throws VariantNotFoundError if variant not found
+     */
+    update(id: string, updates: UpdateVariantInput): PatternVariant;
+    /**
+     * Delete a variant
+     *
+     * @param id - Variant ID
+     * @returns True if variant was deleted
+     */
+    delete(id: string): boolean;
+    /**
+     * Activate a variant
+     *
+     * @param id - Variant ID
+     * @returns The updated variant
+     */
+    activate(id: string): PatternVariant;
+    /**
+     * Deactivate a variant
+     *
+     * @param id - Variant ID
+     * @returns The updated variant
+     */
+    deactivate(id: string): PatternVariant;
+    /**
+     * Query variants with filtering
+     *
+     * @param query - Query options
+     * @returns Matching variants
+     */
+    query(query?: VariantQuery): PatternVariant[];
+    /**
+     * Check if a variant covers a specific file
+     */
+    private variantCoversFile;
+    /**
+     * Check if a variant covers a specific directory
+     */
+    private variantCoversDirectory;
+    /**
+     * Get all variants
+     */
+    getAll(): PatternVariant[];
+    /**
+     * Get all active variants
+     */
+    getActive(): PatternVariant[];
+    /**
+     * Get all inactive variants
+     */
+    getInactive(): PatternVariant[];
+    /**
+     * Get variants for a specific pattern
+     *
+     * @param patternId - Pattern ID
+     * @returns Variants for the pattern
+     */
+    getByPatternId(patternId: string): PatternVariant[];
+    /**
+     * Get active variants for a specific pattern
+     *
+     * @param patternId - Pattern ID
+     * @returns Active variants for the pattern
+     */
+    getActiveByPatternId(patternId: string): PatternVariant[];
+    /**
+     * Get variants by scope
+     *
+     * @param scope - Variant scope
+     * @returns Variants with the specified scope
+     */
+    getByScope(scope: VariantScope): PatternVariant[];
+    /**
+     * Get variants that cover a specific file
+     *
+     * @param filePath - File path
+     * @returns Variants that cover the file
+     */
+    getByFile(filePath: string): PatternVariant[];
+    /**
+     * Get active variants that cover a specific file
+     *
+     * @param filePath - File path
+     * @returns Active variants that cover the file
+     */
+    getActiveByFile(filePath: string): PatternVariant[];
+    /**
+     * Check if a location is covered by any active variant for a pattern
+     *
+     * This is the primary method used by the enforcement system to determine
+     * if a violation should be suppressed.
+     *
+     * @requirements 26.4 - WHEN a variant is created, THE Enforcement_System SHALL stop flagging matching code
+     *
+     * @param patternId - Pattern ID
+     * @param location - Location to check
+     * @returns True if the location is covered by an active variant
+     */
+    isLocationCovered(patternId: string, location: PatternLocation): boolean;
+    /**
+     * Check if a variant covers a specific location
+     *
+     * A variant covers a location if:
+     * 1. The file is within the variant's scope (global, directory, or file)
+     * 2. AND either:
+     *    a. The variant has only one location (the "anchor" location used for validation)
+     *       which means it covers the entire scope
+     *    b. The variant has multiple locations that include this specific location
+     */
+    private variantCoversLocation;
+    /**
+     * Get the variant that covers a specific location (if any)
+     *
+     * @param patternId - Pattern ID
+     * @param location - Location to check
+     * @returns The covering variant or undefined
+     */
+    getCoveringVariant(patternId: string, location: PatternLocation): PatternVariant | undefined;
+    /**
+     * Get statistics about variants
+     */
+    getStats(): VariantStats;
+    /**
+     * Emit a variant manager event
+     */
+    private emitEvent;
+    /**
+     * Clean up resources
+     */
+    dispose(): void;
+}
+/**
+ * Statistics about variants
+ */
+export interface VariantStats {
+    /** Total number of variants */
+    total: number;
+    /** Number of active variants */
+    active: number;
+    /** Number of inactive variants */
+    inactive: number;
+    /** Variants by scope */
+    byScope: Record<VariantScope, number>;
+    /** Variants by pattern ID */
+    byPattern: Record<string, number>;
+    /** Number of patterns with variants */
+    patternsWithVariants: number;
+}
+//# sourceMappingURL=variant-manager.d.ts.map

package/dist/rules/variant-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"variant-manager.d.ts","sourceRoot":"","sources":["../../src/rules/variant-manager.ts"],"names":[],"mappings":"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"}