@pattern-algebra/core 0.0.0

package/dist/core-public.d.ts

@@ -0,0 +1,1253 @@
+/**
+ * Path Pattern Language Library
+ *
+ * A library for parsing, compiling, matching, and comparing path patterns
+ * (globs and restricted regexes). Designed for downstream use by policy systems.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Brace expansion creates alternation between pattern branches.
+ *
+ * @example
+ * "\{src,lib\}/**\/*.ts" becomes:
+ *   Alternation([
+ *     SegmentSequence([Literal("src"), Globstar, Wildcard("*.ts")]),
+ *     SegmentSequence([Literal("lib"), Globstar, Wildcard("*.ts")])
+ *   ])
+ *
+ * @public
+ */
+export declare interface Alternation {
+    readonly type: 'alternation';
+    readonly branches: readonly PatternNode[];
+}
+
+/**
+ * Analyze the relationship between two patterns in detail.
+ *
+ * Provides comprehensive information about how patterns relate,
+ * including the intersection and set differences.
+ *
+ * @param a - First compiled pattern
+ * @param b - Second compiled pattern
+ * @returns Full analysis of pattern relationship
+ *
+ * @public
+ */
+export declare function analyzePatterns(a: CompiledPattern, b: CompiledPattern): PatternAnalysis;
+
+/**
+ * Comparison of pattern anchoring (absolute vs relative).
+ * @public
+ */
+export declare interface AnchoringComparison {
+    /** Whether the anchoring differs between patterns */
+    readonly differ: boolean;
+    /** Whether pattern A is absolute (starts with / or ~) */
+    readonly patternAAbsolute: boolean;
+    /** Whether pattern B is absolute (starts with / or ~) */
+    readonly patternBAbsolute: boolean;
+    /** Human-readable explanation of the difference */
+    readonly explanation?: string;
+}
+
+/**
+ * Apply quick-reject filter to a path.
+ *
+ * @param path - Normalized path to check
+ * @param filter - Quick-reject filter
+ * @returns false if path definitely doesn't match, true if it might match
+ *
+ * @public
+ */
+export declare function applyQuickReject(path: string, filter: QuickRejectFilter): boolean;
+
+/**
+ * Determine if two patterns are disjoint (no common paths).
+ *
+ * @param a - First pattern
+ * @param b - Second pattern
+ * @returns true if patterns have no paths in common
+ *
+ * @public
+ */
+export declare function areDisjoint(a: CompiledPattern, b: CompiledPattern): boolean;
+
+/**
+ * Determine if two patterns are equivalent (match the same set of paths).
+ *
+ * @param a - First pattern
+ * @param b - Second pattern
+ * @returns true if patterns are equivalent
+ *
+ * @public
+ */
+export declare function areEquivalent(a: CompiledPattern, b: CompiledPattern): boolean;
+
+/**
+ * Error thrown when automaton operations exceed configured limits.
+ *
+ * This typically occurs during DFA construction when a pattern
+ * would result in exponential state explosion.
+ *
+ * @public
+ */
+export declare class AutomatonLimitError extends Error {
+    /** Error classification code */
+    readonly code: PatternErrorCode;
+    /** The limit that was exceeded */
+    readonly limit: number;
+    /** The actual value that exceeded the limit */
+    readonly actual: number;
+    constructor(code: PatternErrorCode, message: string, limit: number, actual: number);
+}
+
+/**
+ * A state in the segment automaton.
+ * @public
+ */
+export declare interface AutomatonState {
+    /** Unique identifier for this state (index in the states array) */
+    readonly id: number;
+    /** Transitions from this state */
+    readonly transitions: readonly AutomatonTransition[];
+    /** Is this an accepting state? */
+    readonly accepting: boolean;
+}
+
+/**
+ * A transition in the segment automaton.
+ * @public
+ */
+export declare type AutomatonTransition = LiteralTransition | WildcardTransition | GlobstarTransition | EpsilonTransition;
+
+/**
+ * Build a segment automaton from a pattern AST.
+ *
+ * The automaton operates on path segments (not characters).
+ * This representation enables:
+ * - O(n) matching where n is number of path segments
+ * - Standard automaton operations for containment checking
+ *
+ * @param pattern - Parsed pattern AST
+ * @returns Segment automaton (NFA)
+ *
+ * @public
+ */
+export declare function buildAutomaton(pattern: PathPattern): SegmentAutomaton;
+
+/**
+ * Build quick-reject filters for a pattern.
+ *
+ * Quick-reject filters enable fast elimination of non-matching paths
+ * before full automaton simulation.
+ *
+ * @param pattern - Pattern AST
+ * @returns Quick-reject filter configuration
+ *
+ * @public
+ */
+export declare function buildQuickRejectFilter(pattern: PathPattern): QuickRejectFilter;
+
+/**
+ * A character class like [a-z] or [!0-9].
+ * @public
+ */
+export declare interface CharClassSegment {
+    readonly type: 'charclass';
+    /** Whether this is a negated class (e.g., [!abc] or [^abc]) */
+    readonly negated: boolean;
+    /** Character ranges (e.g., a-z, 0-9) */
+    readonly ranges: readonly CharRange[];
+    /** Individual characters not in ranges */
+    readonly chars: string;
+}
+
+/**
+ * A character range within a character class.
+ * @public
+ */
+export declare interface CharRange {
+    /** Single character - start of range */
+    readonly start: string;
+    /** Single character - end of range */
+    readonly end: string;
+}
+
+/**
+ * Check if pattern A is contained within pattern B.
+ *
+ * A ⊆ B means: every path that matches A also matches B.
+ *
+ * Uses a hybrid approach:
+ * 1. Structural analysis for quick checks
+ * 2. Sample-based testing for validation
+ * 3. Automaton operations for complex cases (when available)
+ *
+ * @param a - First compiled pattern
+ * @param b - Second compiled pattern
+ * @returns Containment result with explanation data
+ *
+ * @public
+ */
+export declare function checkContainment(a: CompiledPattern, b: CompiledPattern): ContainmentResult;
+
+/**
+ * Find the common prefix path between two paths.
+ *
+ * @param pathA - First path
+ * @param pathB - Second path
+ * @returns The longest common ancestor path
+ *
+ * @example
+ * commonPrefix('/home/user/a/b', '/home/user/c/d')
+ * // => '/home/user'
+ *
+ * @public
+ */
+export declare function commonPrefix(pathA: string, pathB: string): string;
+
+/**
+ * A compiled pattern ready for efficient matching.
+ *
+ * Patterns are compiled to a form optimized for:
+ * 1. Fast rejection of non-matching paths
+ * 2. Minimal backtracking during matching
+ * 3. Support for containment analysis
+ *
+ * @public
+ */
+export declare interface CompiledPattern {
+    /** Original source pattern */
+    readonly source: string;
+    /** Parsed AST (for containment analysis) */
+    readonly ast: PathPattern;
+    /**
+     * Quick-reject filters applied before full matching.
+     * If any filter fails, the path definitely doesn't match.
+     */
+    readonly quickReject: QuickRejectFilter;
+    /**
+     * Segment automaton for matching.
+     * Operates on path segments, not characters.
+     */
+    readonly automaton: SegmentAutomaton;
+    /** Whether pattern can match paths of any depth (contains **) */
+    readonly isUnbounded: boolean;
+    /** Minimum number of segments this pattern requires */
+    readonly minSegments: number;
+    /** Maximum segments (undefined if unbounded) */
+    readonly maxSegments?: number;
+}
+
+/**
+ * Compile a pattern to an efficient matching form.
+ *
+ * The compiled pattern includes:
+ * - Original source and AST for debugging/analysis
+ * - Quick-reject filters for fast path elimination
+ * - Segment automaton for full matching
+ * - Depth constraints for optimization
+ *
+ * @param pattern - Parsed pattern AST
+ * @returns Compiled pattern ready for matching
+ *
+ * @public
+ */
+export declare function compilePattern(pattern: PathPattern): CompiledPattern;
+
+/**
+ * Complement a DFA by swapping accepting and non-accepting states.
+ *
+ * The complemented automaton accepts exactly the strings that the
+ * original automaton rejects, and vice versa.
+ *
+ * Note: Input must be deterministic. NFAs are automatically converted.
+ *
+ * @param automaton - The automaton to complement
+ * @returns Complemented automaton
+ *
+ * @public
+ */
+export declare function complement(automaton: SegmentAutomaton): SegmentAutomaton;
+
+/**
+ * A segment composed of multiple parts (literal + wildcard + charclass).
+ *
+ * @example "test-[0-9]*-spec.ts" is a composite of:
+ *   - literal "test-"
+ *   - charclass [0-9]
+ *   - star *
+ *   - literal "-spec.ts"
+ *
+ * @public
+ */
+export declare interface CompositeSegment {
+    readonly type: 'composite';
+    readonly parts: readonly SegmentPart[];
+}
+
+/**
+ * Structured explanation of why two patterns have a particular relationship.
+ * Provides sufficient data for downstream systems to generate human-readable explanations.
+ * @public
+ */
+export declare interface ContainmentExplanation {
+    /**
+     * High-level categorization of why containment fails (if it does).
+     * Empty array if A ⊆ B.
+     */
+    readonly failureReasons: readonly ContainmentFailureReason[];
+    /**
+     * Segment-by-segment comparison showing where patterns differ.
+     * Each entry describes one position in the path.
+     */
+    readonly segmentComparison: readonly SegmentComparisonEntry[];
+    /**
+     * Structural differences between the patterns.
+     */
+    readonly structuralDiffs: StructuralDifferences;
+    /**
+     * Witness paths that demonstrate the relationship.
+     * Includes counterexamples, shared paths, and illustrative examples.
+     */
+    readonly witnesses: readonly WitnessPath[];
+}
+
+/**
+ * Categories of reasons why containment may fail.
+ * Used to provide structured explanation data.
+ * @public
+ */
+export declare type ContainmentFailureReason = 'depth_mismatch' | 'prefix_mismatch' | 'suffix_mismatch' | 'segment_mismatch' | 'charclass_mismatch' | 'negation_conflict' | 'alternation_escape';
+
+/**
+ * Result of checking whether pattern A is contained within pattern B.
+ *
+ * A ⊆ B means: every path that matches A also matches B.
+ *
+ * This type provides rich structured data to enable downstream systems
+ * to generate human-readable explanations of containment results.
+ *
+ * @example
+ *   - "src/*.ts" ⊆ "src/**" (true)
+ *   - "src/**" ⊆ "src/*.ts" (false)
+ *   - "*.ts" ⊆ "*" (true)
+ *   - "\{src,lib\}/*.ts" ⊆ "**\/*.ts" (true)
+ *
+ * @public
+ */
+export declare interface ContainmentResult {
+    /** The first pattern being compared */
+    readonly patternA: string;
+    /** The second pattern being compared */
+    readonly patternB: string;
+    /** Is A a subset of B? (A ⊆ B) */
+    readonly isSubset: boolean;
+    /** Is B a subset of A? (B ⊆ A) */
+    readonly isSuperset: boolean;
+    /** Is A equal to B (mutual containment)? */
+    readonly isEqual: boolean;
+    /** Do the patterns have any overlap? (A ∩ B ≠ ∅) */
+    readonly hasOverlap: boolean;
+    /** Relationship classification */
+    readonly relationship: PatternRelationship;
+    /**
+     * Primary counterexample: a path that matches A but not B.
+     * Present when isSubset is false.
+     */
+    readonly counterexample?: string;
+    /**
+     * Reverse counterexample: a path that matches B but not A.
+     * Present when isSuperset is false.
+     */
+    readonly reverseCounterexample?: string;
+    /**
+     * Structured explanation data for generating human-readable descriptions.
+     */
+    readonly explanation: ContainmentExplanation;
+}
+
+/**
+ * Count the number of patterns that would result from expansion.
+ * Does not actually expand - useful for limit checking.
+ *
+ * @param source - Pattern source string
+ * @returns Estimated expansion count, or Infinity if it would exceed reasonable limits
+ *
+ * @public
+ */
+export declare function countBraceExpansions(source: string): number;
+
+/**
+ * Count the number of accepting paths of a given length.
+ *
+ * Useful for understanding the "size" of a pattern's language.
+ *
+ * @param automaton - The automaton
+ * @param maxDepth - Maximum path length to consider
+ * @returns Object with counts per depth
+ *
+ * @public
+ */
+export declare function countPaths(automaton: SegmentAutomaton, maxDepth: number): Map<number, number>;
+
+/**
+ * Default maximum number of DFA states before throwing an error.
+ * This prevents exponential blowup from patterns with many alternations.
+ *
+ * @public
+ */
+export declare const DEFAULT_MAX_DFA_STATES = 10000;
+
+/**
+ * Comparison of pattern depth constraints.
+ * @public
+ */
+export declare interface DepthComparison {
+    /** Whether the depth constraints differ between patterns */
+    readonly differ: boolean;
+    /** Minimum segment depth for pattern A */
+    readonly patternAMin: number;
+    /** Maximum segment depth for pattern A (or 'unbounded' for **) */
+    readonly patternAMax: number | 'unbounded';
+    /** Minimum segment depth for pattern B */
+    readonly patternBMin: number;
+    /** Maximum segment depth for pattern B (or 'unbounded' for **) */
+    readonly patternBMax: number | 'unbounded';
+    /** Human-readable explanation of the difference */
+    readonly explanation?: string;
+}
+
+/**
+ * Convert an NFA to a DFA using subset construction.
+ *
+ * The resulting DFA has states that correspond to sets of NFA states.
+ * Globstar transitions are handled by treating them as transitions
+ * that can match any segment.
+ *
+ * @param nfa - The NFA to determinize
+ * @param options - Optional configuration for the conversion
+ * @returns An equivalent DFA
+ * @throws AutomatonLimitError if DFA state count exceeds the configured limit
+ *
+ * @public
+ */
+export declare function determinize(nfa: SegmentAutomaton, options?: DeterminizeOptions): SegmentAutomaton;
+
+/**
+ * Options for DFA construction.
+ *
+ * @public
+ */
+export declare interface DeterminizeOptions {
+    /**
+     * Maximum number of DFA states to create before throwing an error.
+     * Set to `Infinity` to disable the limit (not recommended).
+     * @defaultValue 10000
+     */
+    maxStates?: number;
+}
+
+/**
+ * Epsilon transition (no input consumed).
+ * Used for NFA construction and alternation.
+ * @public
+ */
+export declare interface EpsilonTransition {
+    readonly type: 'epsilon';
+    readonly target: number;
+}
+
+/**
+ * Expand brace expressions in a pattern, creating multiple patterns.
+ *
+ * @example
+ * expandBraces(parsePattern('{src,lib}/*.ts'))
+ * // => [parsePattern('src/*.ts'), parsePattern('lib/*.ts')]
+ *
+ * @example
+ * expandBraces(parsePattern('file{1..3}.txt'))
+ * // => [parsePattern('file1.txt'), parsePattern('file2.txt'), parsePattern('file3.txt')]
+ *
+ * @param pattern - The pattern to expand
+ * @param maxExpansion - Maximum number of expanded patterns (default: 100)
+ * @returns Array of expanded patterns
+ *
+ * @public
+ */
+export declare function expandBraces(pattern: PathPattern, maxExpansion?: number): readonly PathPattern[];
+
+/**
+ * Find a witness string accepted by the automaton.
+ *
+ * If the automaton is non-empty, returns a path (sequence of segments)
+ * that leads to an accepting state.
+ *
+ * @param automaton - The automaton to find a witness for
+ * @returns A witness path string, or undefined if the language is empty
+ *
+ * @public
+ */
+export declare function findWitness(automaton: SegmentAutomaton): string | undefined;
+
+/**
+ * Get the basename (final segment) from a path.
+ *
+ * @param path - Path to extract basename from
+ * @returns The final segment of the path
+ *
+ * @public
+ */
+export declare function getBasename(path: string): string;
+
+/**
+ * Get the directory portion of a path (everything except the last segment).
+ *
+ * @param path - Path to extract directory from
+ * @returns The directory path
+ *
+ * @public
+ */
+export declare function getDirname(path: string): string;
+
+/**
+ * Get the file extension from a path segment or full path.
+ *
+ * @param pathOrSegment - A path or segment to extract extension from
+ * @returns The extension including the dot, or empty string if none
+ *
+ * @example
+ * getExtension('file.ts') // => '.ts'
+ * getExtension('file.test.ts') // => '.ts'
+ * getExtension('.gitignore') // => '' (dotfiles have no extension)
+ * getExtension('Makefile') // => ''
+ *
+ * @public
+ */
+export declare function getExtension(pathOrSegment: string): string;
+
+/**
+ * Get the maximum number of segments a pattern can match.
+ *
+ * @param pattern - Pattern AST
+ * @returns Maximum segment count, or undefined if unbounded (contains **)
+ *
+ * @public
+ */
+export declare function getMaxSegments(pattern: PathPattern): number | undefined;
+
+/**
+ * Get the minimum number of segments a pattern can match.
+ *
+ * @param pattern - Pattern AST
+ * @returns Minimum segment count
+ *
+ * @public
+ */
+export declare function getMinSegments(pattern: PathPattern): number;
+
+/**
+ * The ** globstar - matches zero or more complete segments.
+ * @public
+ */
+export declare interface GlobstarSegment {
+    readonly type: 'globstar';
+}
+
+/**
+ * Globstar transition for ** (matches zero or more segments).
+ *
+ * Modeled as: epsilon to exit OR consume one segment and stay.
+ * @public
+ */
+export declare interface GlobstarTransition {
+    readonly type: 'globstar';
+    /** Self-loop state (stays in same state consuming segments) */
+    readonly selfLoop: number;
+    /** Exit state (moves forward without consuming) */
+    readonly exit: number;
+}
+
+/**
+ * Determine if two patterns have any overlap.
+ *
+ * @param a - First pattern
+ * @param b - Second pattern
+ * @returns true if there exists a path matching both patterns
+ *
+ * @public
+ */
+export declare function hasOverlap(a: CompiledPattern, b: CompiledPattern): boolean;
+
+/**
+ * Compute the intersection of two automata using product construction.
+ *
+ * The resulting automaton accepts a string iff both input automata accept it.
+ * L(A ∩ B) = L(A) ∩ L(B)
+ *
+ * @param a - First automaton
+ * @param b - Second automaton
+ * @returns Intersection automaton
+ *
+ * @public
+ */
+export declare function intersect(a: SegmentAutomaton, b: SegmentAutomaton): SegmentAutomaton;
+
+/**
+ * Check if a path is absolute (starts with / or ~).
+ *
+ * @param path - Path to check
+ * @returns true if the path is absolute
+ *
+ * @public
+ */
+export declare function isAbsolutePath(path: string): boolean;
+
+/**
+ * Check if path A is a prefix of path B (A is an ancestor directory of B).
+ *
+ * @param ancestor - Potential ancestor path
+ * @param descendant - Potential descendant path
+ * @returns true if ancestor is a prefix of descendant
+ *
+ * @example
+ * isAncestorPath('/home/user', '/home/user/dev/file.ts') // => true
+ * isAncestorPath('/home/user', '/home/user') // => true (same path)
+ * isAncestorPath('/home/user', '/home/other') // => false
+ *
+ * @public
+ */
+export declare function isAncestorPath(ancestor: string, descendant: string): boolean;
+
+/**
+ * Check if an automaton's language is empty.
+ *
+ * Uses reachability analysis from the initial state to any accepting state.
+ *
+ * @param automaton - The automaton to check
+ * @returns true if the automaton accepts no strings
+ *
+ * @public
+ */
+export declare function isEmpty(automaton: SegmentAutomaton): boolean;
+
+/**
+ * Check if a pattern contains a globstar (**).
+ *
+ * @param pattern - Pattern AST
+ * @returns true if pattern is unbounded
+ *
+ * @public
+ */
+export declare function isUnbounded(pattern: PathPattern): boolean;
+
+/**
+ * Check if a pattern is valid (has no errors).
+ *
+ * @param pattern - The pattern to check
+ * @returns true if the pattern has no errors
+ *
+ * @public
+ */
+export declare function isValidPattern(pattern: PathPattern): boolean;
+
+/**
+ * An exact literal match for a path segment.
+ *
+ * @example "package.json" matches only "package.json"
+ *
+ * @public
+ */
+export declare interface LiteralSegment {
+    readonly type: 'literal';
+    readonly value: string;
+}
+
+/**
+ * Transition on an exact segment match.
+ * @public
+ */
+export declare interface LiteralTransition {
+    readonly type: 'literal';
+    readonly segment: string;
+    /** Target state ID */
+    readonly target: number;
+}
+
+/**
+ * Test if a path matches a compiled pattern.
+ *
+ * @param path - Absolute, normalized path (e.g., "/home/user/dev/foo.ts")
+ * @param pattern - Compiled pattern
+ * @returns true if path matches
+ *
+ * @public
+ */
+export declare function matchPath(path: string, pattern: CompiledPattern): boolean;
+
+/**
+ * Match a path against a pattern AST directly (without compilation).
+ *
+ * This is less efficient than using compiled patterns but useful for one-off matching.
+ *
+ * @param path - Normalized path
+ * @param pattern - Pattern AST
+ * @returns true if path matches
+ *
+ * @public
+ */
+export declare function matchPathDirect(path: string, pattern: PathPattern): boolean;
+
+/**
+ * Match a path with context (for ~ expansion and relative paths).
+ *
+ * @param path - Path to match (may be relative or contain ~)
+ * @param pattern - Compiled pattern
+ * @param context - Path context for normalization
+ * @returns true if normalized path matches
+ *
+ * @public
+ */
+export declare function matchPathWithContext(path: string, pattern: CompiledPattern, context: PathContext): boolean;
+
+/**
+ * Check if a path segment matches a segment pattern.
+ *
+ * @param segment - The actual path segment (e.g., "file.ts")
+ * @param pattern - The pattern segment from AST
+ * @returns true if the segment matches
+ *
+ * @public
+ */
+export declare function matchSegment(segment: string, pattern: Segment): boolean;
+
+/**
+ * Normalize a path to absolute form for consistent matching.
+ *
+ * Handles:
+ * - ~ expansion to home directory
+ * - Relative path resolution against cwd
+ * - . and .. resolution
+ * - Trailing slash normalization (removed)
+ * - Duplicate slash removal
+ * - Backslash to forward slash conversion (Windows compatibility)
+ *
+ * @param path - Input path (may be relative or contain ~)
+ * @param context - Context for resolution
+ * @returns Absolute, normalized path
+ *
+ * @public
+ */
+export declare function normalizePath(path: string, context: PathContext): string;
+
+/**
+ * Parse a pattern string into an AST.
+ *
+ * @param source - The pattern string to parse
+ * @returns Parsed PathPattern with AST and any errors
+ *
+ * @public
+ */
+export declare function parsePattern(source: string): PathPattern;
+
+/**
+ * Context for path resolution operations.
+ * @public
+ */
+export declare interface PathContext {
+    /** User's home directory for ~ expansion */
+    readonly homeDir: string;
+    /** Current working directory for relative path resolution */
+    readonly cwd: string;
+    /** Optional project root for project-relative patterns */
+    readonly projectRoot?: string;
+}
+
+/**
+ * Root pattern node - the entry point for any parsed pattern.
+ * @public
+ */
+export declare interface PathPattern {
+    /** Original pattern string for error messages and debugging */
+    readonly source: string;
+    /** Parsed structure */
+    readonly root: PatternNode;
+    /** Whether this is an absolute pattern (starts with / or ~) */
+    readonly isAbsolute: boolean;
+    /** Whether this is a negation pattern (starts with !) */
+    readonly isNegation: boolean;
+    /** Validation errors, if any */
+    readonly errors?: readonly PatternError[];
+}
+
+/**
+ * Split a normalized path into segments.
+ *
+ * @param path - A normalized absolute path (starting with /)
+ * @returns Array of path segments (excluding the root)
+ *
+ * @example
+ * pathToSegments('/home/user/dev/file.ts')
+ * // => ['home', 'user', 'dev', 'file.ts']
+ *
+ * @public
+ */
+export declare function pathToSegments(path: string): readonly string[];
+
+/**
+ * Detailed analysis of two patterns' relationship.
+ *
+ * Provides comprehensive data for understanding how two patterns relate,
+ * including the intersection and set differences.
+ *
+ * @public
+ */
+export declare interface PatternAnalysis {
+    readonly patternA: string;
+    readonly patternB: string;
+    readonly relationship: PatternRelationship;
+    /** Full containment result with explanation */
+    readonly containment: ContainmentResult;
+    /** Description of paths matching both patterns */
+    readonly intersection: PatternDescription;
+    /** Description of paths matching A but not B */
+    readonly aMinusB: PatternDescription;
+    /** Description of paths matching B but not A */
+    readonly bMinusA: PatternDescription;
+}
+
+/**
+ * Compute the complement of a pattern.
+ *
+ * The result matches paths that do NOT match the input pattern.
+ * L(result) = Σ* - L(a)
+ *
+ * @param a - Pattern to complement
+ * @returns Pattern matching paths not matched by a
+ *
+ * @public
+ */
+export declare function patternComplement(a: CompiledPattern): CompiledPattern;
+
+/**
+ * A human-readable description of a set of paths.
+ * @public
+ */
+export declare interface PatternDescription {
+    /** Is this set empty? */
+    readonly isEmpty: boolean;
+    /** Example paths from this set (if non-empty) */
+    readonly examples?: readonly string[];
+    /** Pattern representation (if expressible as a single pattern) */
+    readonly pattern?: string;
+    /** Natural language description */
+    readonly description: string;
+}
+
+/**
+ * Compute the difference of two patterns.
+ *
+ * The result matches paths that match a but NOT b.
+ * L(result) = L(a) - L(b) = L(a) ∩ L(¬b)
+ *
+ * @param a - Pattern to subtract from
+ * @param b - Pattern to subtract
+ * @returns Pattern matching paths in a but not in b
+ *
+ * @public
+ */
+export declare function patternDifference(a: CompiledPattern, b: CompiledPattern): CompiledPattern;
+
+/**
+ * A pattern validation error with location information.
+ * @public
+ */
+export declare interface PatternError {
+    /** Error classification code */
+    readonly code: PatternErrorCode;
+    /** Human-readable error description */
+    readonly message: string;
+    /** Character position in source where error starts */
+    readonly position?: number;
+    /** Length of the problematic section */
+    readonly length?: number;
+}
+
+/**
+ * Error codes for pattern validation failures.
+ * @public
+ */
+export declare type PatternErrorCode = 'INVALID_GLOBSTAR' | 'UNCLOSED_BRACKET' | 'UNCLOSED_BRACE' | 'EMPTY_CHARCLASS' | 'INVALID_RANGE' | 'EXPANSION_LIMIT' | 'NESTED_BRACES' | 'INVALID_ESCAPE' | 'BANNED_FEATURE' | 'INVALID_REGEX' | 'UNSAFE_REGEX' | 'DFA_STATE_LIMIT';
+
+/**
+ * Compute the intersection of two patterns.
+ *
+ * The result matches paths that match BOTH input patterns.
+ * L(result) = L(a) ∩ L(b)
+ *
+ * @param a - First pattern
+ * @param b - Second pattern
+ * @returns Pattern matching paths in both a and b
+ *
+ * @public
+ */
+export declare function patternIntersect(a: CompiledPattern, b: CompiledPattern): CompiledPattern;
+
+/**
+ * A node in the pattern AST. Patterns are sequences of segments or alternations.
+ * @public
+ */
+export declare type PatternNode = SegmentSequence | Alternation;
+
+/**
+ * Describes the relationship between two pattern sets.
+ * @public
+ */
+export declare type PatternRelationship = 'subset' | 'equal' | 'superset' | 'overlapping' | 'disjoint';
+
+/**
+ * Compute the union of two patterns.
+ *
+ * The result matches paths that match EITHER input pattern.
+ * L(result) = L(a) ∪ L(b)
+ *
+ * @param a - First pattern
+ * @param b - Second pattern
+ * @returns Pattern matching paths in a or b (or both)
+ *
+ * @public
+ */
+export declare function patternUnion(a: CompiledPattern, b: CompiledPattern): CompiledPattern;
+
+/**
+ * Comparison of required path prefixes.
+ * @public
+ */
+export declare interface PrefixComparison {
+    /** Whether the required prefixes differ between patterns */
+    readonly differ: boolean;
+    /** Required prefix for pattern A (if any) */
+    readonly patternAPrefix?: string;
+    /** Required prefix for pattern B (if any) */
+    readonly patternBPrefix?: string;
+    /** Human-readable explanation of the difference */
+    readonly explanation?: string;
+}
+
+/**
+ * Quick rejection filters for fast path elimination.
+ * @public
+ */
+export declare interface QuickRejectFilter {
+    /** If pattern requires specific prefix, check it first */
+    readonly requiredPrefix?: string;
+    /** If pattern requires specific suffix, check it first */
+    readonly requiredSuffix?: string;
+    /** Minimum path length (characters) */
+    readonly minLength?: number;
+    /** Required literal segments that must appear somewhere */
+    readonly requiredLiterals?: readonly string[];
+}
+
+/**
+ * A segment represents one path component between slashes.
+ * @public
+ */
+export declare type Segment = LiteralSegment | WildcardSegment | GlobstarSegment | CharClassSegment | CompositeSegment;
+
+/**
+ * A finite automaton that operates on path segments rather than characters.
+ *
+ * Key insight: treating segments as tokens rather than character-by-character
+ * matching dramatically simplifies the automaton and enables efficient
+ * containment checking.
+ *
+ * Alphabet:
+ *   - Each literal segment is a symbol
+ *   - "*" matches any single segment (wildcard transition)
+ *   - "**" is an epsilon loop (zero or more segments)
+ *
+ * This representation supports:
+ *   - O(n) matching where n is number of path segments
+ *   - Standard automaton operations (union, intersection, complement)
+ *   - Containment checking via (A ∩ B̄ = ∅)
+ *
+ * @public
+ */
+export declare interface SegmentAutomaton {
+    /** All states in the automaton */
+    readonly states: readonly AutomatonState[];
+    /** Index of the initial state */
+    readonly initialState: number;
+    /** Indices of accepting (final) states */
+    readonly acceptingStates: readonly number[];
+    /** Whether this automaton is deterministic */
+    readonly isDeterministic: boolean;
+}
+
+/**
+ * Comparison of what patterns allow at a specific segment position.
+ * @public
+ */
+export declare interface SegmentComparisonEntry {
+    /** Segment position (0-indexed from path root) */
+    readonly position: number;
+    /** What pattern A allows at this position */
+    readonly patternAAllows: SegmentConstraint;
+    /** What pattern B allows at this position */
+    readonly patternBAllows: SegmentConstraint;
+    /** Whether A's constraint is a subset of B's at this position */
+    readonly aSubsetOfB: boolean;
+    /** Brief description of the difference (if any) */
+    readonly difference?: string;
+}
+
+/**
+ * Describes what a pattern allows at a segment position.
+ * @public
+ */
+export declare interface SegmentConstraint {
+    /** The type of constraint */
+    readonly type: SegmentConstraintType;
+    /** For literal: the exact value required */
+    readonly literalValue?: string;
+    /** For wildcard: the pattern (e.g., "*.ts") */
+    readonly wildcardPattern?: string;
+    /** For charclass: description of allowed characters */
+    readonly charclassDescription?: string;
+    /** Whether this position can be skipped (due to ** before it) */
+    readonly optional: boolean;
+    /** Whether this position can repeat (is within a ** range) */
+    readonly repeatable: boolean;
+}
+
+/**
+ * Types of segment constraints.
+ * @public
+ */
+export declare type SegmentConstraintType = 'literal' | 'wildcard' | 'charclass' | 'any' | 'any_sequence' | 'end' | 'unreachable';
+
+/**
+ * A pattern matcher that can test if a segment matches.
+ * This can be either a native RegExp or a composite pattern.
+ * @public
+ */
+declare interface SegmentMatcher {
+    /** Test if a string matches the pattern */
+    test(str: string): boolean;
+    /** The pattern source for debugging/serialization */
+    readonly source: string;
+}
+
+/**
+ * A part of a composite segment.
+ * @public
+ */
+export declare type SegmentPart = {
+    readonly type: 'literal';
+    readonly value: string;
+} | {
+    readonly type: 'star';
+} | {
+    readonly type: 'question';
+} | {
+    readonly type: 'charclass';
+    readonly spec: CharClassSegment;
+};
+
+/**
+ * A sequence of path segments (the most common case).
+ *
+ * @example
+ * "src/**\/*.ts" becomes:
+ *   segments: [Literal("src"), Globstar, Wildcard("*.ts")]
+ *
+ * @public
+ */
+export declare interface SegmentSequence {
+    readonly type: 'sequence';
+    readonly segments: readonly Segment[];
+}
+
+/**
+ * Join segments back into a path.
+ *
+ * @param segments - Array of path segments
+ * @returns Absolute path string
+ *
+ * @example
+ * segmentsToPath(['home', 'user', 'dev', 'file.ts'])
+ * // => '/home/user/dev/file.ts'
+ *
+ * @public
+ */
+export declare function segmentsToPath(segments: readonly string[]): string;
+
+/**
+ * Build a RegExp from a segment pattern for automaton transitions.
+ *
+ * @param pattern - Segment pattern
+ * @returns RegExp that matches the segment, or null for globstar/literal
+ *
+ * @public
+ */
+export declare function segmentToRegex(pattern: Segment): RegExp | null;
+
+/**
+ * High-level structural differences between patterns.
+ * @public
+ */
+export declare interface StructuralDifferences {
+    /** Whether patterns have different depth bounds */
+    readonly depthDifference: DepthComparison;
+    /** Whether patterns require different prefixes */
+    readonly prefixDifference: PrefixComparison;
+    /** Whether patterns require different suffixes */
+    readonly suffixDifference: SuffixComparison;
+    /** Whether one pattern is anchored and the other isn't */
+    readonly anchoringDifference: AnchoringComparison;
+}
+
+/**
+ * Comparison of required path suffixes (e.g., file extensions).
+ * @public
+ */
+export declare interface SuffixComparison {
+    /** Whether the required suffixes differ between patterns */
+    readonly differ: boolean;
+    /** Required suffix for pattern A (e.g., ".ts") */
+    readonly patternASuffix?: string;
+    /** Required suffix for pattern B (e.g., ".js") */
+    readonly patternBSuffix?: string;
+    /** Human-readable explanation of the difference */
+    readonly explanation?: string;
+}
+
+/**
+ * Get a human-readable summary of the relationship between patterns.
+ *
+ * @param relationship - The pattern relationship
+ * @param patternA - Source of pattern A
+ * @param patternB - Source of pattern B
+ * @returns Human-readable description
+ *
+ * @public
+ */
+export declare function summarizeRelationship(relationship: PatternRelationship, patternA: string, patternB: string): string;
+
+/**
+ * Compute the union of two automata using NFA construction.
+ *
+ * The resulting automaton accepts a string iff either input automaton accepts it.
+ * L(A ∪ B) = L(A) ∪ L(B)
+ *
+ * We use NFA union: create a new initial state with epsilon transitions
+ * to both automata's initial states, then merge the states.
+ *
+ * @param a - First automaton
+ * @param b - Second automaton
+ * @returns Union automaton (NFA)
+ *
+ * @public
+ */
+export declare function union(a: SegmentAutomaton, b: SegmentAutomaton): SegmentAutomaton;
+
+/**
+ * Validate a pattern against the allowed feature set.
+ *
+ * Returns errors for:
+ * - Patterns that already have errors from parsing
+ * - Invalid globstar usage
+ * - Empty patterns
+ * - Other structural issues
+ *
+ * @param pattern - The parsed pattern to validate
+ * @returns Array of validation errors (empty if valid)
+ *
+ * @public
+ */
+export declare function validatePattern(pattern: PathPattern): readonly PatternError[];
+
+/**
+ * Library version.
+ * @public
+ */
+export declare const version = "0.0.0";
+
+/**
+ * A part of a wildcard segment pattern.
+ * @public
+ */
+export declare type WildcardPart = {
+    readonly type: 'literal';
+    readonly value: string;
+} | {
+    readonly type: 'star';
+} | {
+    readonly type: 'question';
+};
+
+/**
+ * A segment containing wildcards (* or ?).
+ *
+ * Compiles to a regex pattern for the segment.
+ *
+ * @example
+ *   "*.ts" -> parts: [{ type: "star" }, { type: "literal", value: ".ts" }]
+ *   "test-*-spec.js" -> complex pattern
+ *
+ * @public
+ */
+export declare interface WildcardSegment {
+    readonly type: 'wildcard';
+    /** Original pattern text for this segment */
+    readonly pattern: string;
+    /** Components for efficient prefix/suffix matching */
+    readonly parts: readonly WildcardPart[];
+}
+
+/**
+ * Transition matching any single segment (from * or ?).
+ * May have constraints from character classes or wildcards.
+ * @public
+ */
+export declare interface WildcardTransition {
+    readonly type: 'wildcard';
+    /** Pattern for segment matching (from *.ts, test-*, etc.) */
+    readonly pattern: RegExp | SegmentMatcher;
+    /** Original pattern string for serialization/debugging */
+    readonly patternSource: string;
+    readonly target: number;
+}
+
+/**
+ * Classification of witness paths for explanation generation.
+ * @public
+ */
+export declare type WitnessCategory = 'counterexample' | 'reverse_counterexample' | 'shared' | 'neither';
+
+/**
+ * A witness path that demonstrates a containment property.
+ * @public
+ */
+export declare interface WitnessPath {
+    /** The actual path string */
+    readonly path: string;
+    /** Which pattern(s) this path matches */
+    readonly matchesA: boolean;
+    readonly matchesB: boolean;
+    /**
+     * For counterexamples, the segment index where patterns diverge.
+     * Useful for highlighting the specific point of difference.
+     */
+    readonly divergenceIndex?: number;
+    /**
+     * Human-oriented classification of this witness.
+     */
+    readonly category: WitnessCategory;
+}
+
+export { }