@pattern-algebra/core 0.0.0

package/dist/types/ast.d.ts

@@ -0,0 +1,158 @@
+import type { PatternError } from './errors';
+/**
+ * Root pattern node - the entry point for any parsed pattern.
+ * @public
+ */
+export 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[];
+}
+/**
+ * A node in the pattern AST. Patterns are sequences of segments or alternations.
+ * @public
+ */
+export type PatternNode = SegmentSequence | Alternation;
+/**
+ * A sequence of path segments (the most common case).
+ *
+ * @example
+ * "src/**\/*.ts" becomes:
+ *   segments: [Literal("src"), Globstar, Wildcard("*.ts")]
+ *
+ * @public
+ */
+export interface SegmentSequence {
+    readonly type: 'sequence';
+    readonly segments: readonly Segment[];
+}
+/**
+ * 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 interface Alternation {
+    readonly type: 'alternation';
+    readonly branches: readonly PatternNode[];
+}
+/**
+ * A segment represents one path component between slashes.
+ * @public
+ */
+export type Segment = LiteralSegment | WildcardSegment | GlobstarSegment | CharClassSegment | CompositeSegment;
+/**
+ * An exact literal match for a path segment.
+ *
+ * @example "package.json" matches only "package.json"
+ *
+ * @public
+ */
+export interface LiteralSegment {
+    readonly type: 'literal';
+    readonly value: string;
+}
+/**
+ * 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 interface WildcardSegment {
+    readonly type: 'wildcard';
+    /** Original pattern text for this segment */
+    readonly pattern: string;
+    /** Components for efficient prefix/suffix matching */
+    readonly parts: readonly WildcardPart[];
+}
+/**
+ * A part of a wildcard segment pattern.
+ * @public
+ */
+export type WildcardPart = {
+    readonly type: 'literal';
+    readonly value: string;
+} | {
+    readonly type: 'star';
+} | {
+    readonly type: 'question';
+};
+/**
+ * The ** globstar - matches zero or more complete segments.
+ * @public
+ */
+export interface GlobstarSegment {
+    readonly type: 'globstar';
+}
+/**
+ * A character class like [a-z] or [!0-9].
+ * @public
+ */
+export 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 interface CharRange {
+    /** Single character - start of range */
+    readonly start: string;
+    /** Single character - end of range */
+    readonly end: string;
+}
+/**
+ * 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 interface CompositeSegment {
+    readonly type: 'composite';
+    readonly parts: readonly SegmentPart[];
+}
+/**
+ * A part of a composite segment.
+ * @public
+ */
+export type SegmentPart = {
+    readonly type: 'literal';
+    readonly value: string;
+} | {
+    readonly type: 'star';
+} | {
+    readonly type: 'question';
+} | {
+    readonly type: 'charclass';
+    readonly spec: CharClassSegment;
+};
+//# sourceMappingURL=ast.d.ts.map

package/dist/types/ast.d.ts.map

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

package/dist/types/ast.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ast.js.map

package/dist/types/ast.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast.js","sourceRoot":"","sources":["../../src/types/ast.ts"],"names":[],"mappings":""}

package/dist/types/automaton.d.ts

@@ -0,0 +1,150 @@
+import type { PathPattern } from './ast';
+/**
+ * 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 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;
+}
+/**
+ * Quick rejection filters for fast path elimination.
+ * @public
+ */
+export 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 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 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;
+}
+/**
+ * A state in the segment automaton.
+ * @public
+ */
+export 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 type AutomatonTransition = LiteralTransition | WildcardTransition | GlobstarTransition | EpsilonTransition;
+/**
+ * Transition on an exact segment match.
+ * @public
+ */
+export interface LiteralTransition {
+    readonly type: 'literal';
+    readonly segment: string;
+    /** Target state ID */
+    readonly target: number;
+}
+/**
+ * A pattern matcher that can test if a segment matches.
+ * This can be either a native RegExp or a composite pattern.
+ * @public
+ */
+export interface SegmentMatcher {
+    /** Test if a string matches the pattern */
+    test(str: string): boolean;
+    /** The pattern source for debugging/serialization */
+    readonly source: string;
+}
+/**
+ * Transition matching any single segment (from * or ?).
+ * May have constraints from character classes or wildcards.
+ * @public
+ */
+export 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;
+}
+/**
+ * Globstar transition for ** (matches zero or more segments).
+ *
+ * Modeled as: epsilon to exit OR consume one segment and stay.
+ * @public
+ */
+export 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;
+}
+/**
+ * Epsilon transition (no input consumed).
+ * Used for NFA construction and alternation.
+ * @public
+ */
+export interface EpsilonTransition {
+    readonly type: 'epsilon';
+    readonly target: number;
+}
+//# sourceMappingURL=automaton.d.ts.map

package/dist/types/automaton.d.ts.map

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

package/dist/types/automaton.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=automaton.js.map

package/dist/types/automaton.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"automaton.js","sourceRoot":"","sources":["../../src/types/automaton.ts"],"names":[],"mappings":""}

package/dist/types/containment.d.ts

@@ -0,0 +1,257 @@
+/**
+ * Describes the relationship between two pattern sets.
+ * @public
+ */
+export type PatternRelationship = 'subset' | 'equal' | 'superset' | 'overlapping' | 'disjoint';
+/**
+ * Categories of reasons why containment may fail.
+ * Used to provide structured explanation data.
+ * @public
+ */
+export type ContainmentFailureReason = 'depth_mismatch' | 'prefix_mismatch' | 'suffix_mismatch' | 'segment_mismatch' | 'charclass_mismatch' | 'negation_conflict' | 'alternation_escape';
+/**
+ * A witness path that demonstrates a containment property.
+ * @public
+ */
+export 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;
+}
+/**
+ * Classification of witness paths for explanation generation.
+ * @public
+ */
+export type WitnessCategory = 'counterexample' | 'reverse_counterexample' | 'shared' | 'neither';
+/**
+ * Structured explanation of why two patterns have a particular relationship.
+ * Provides sufficient data for downstream systems to generate human-readable explanations.
+ * @public
+ */
+export 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[];
+}
+/**
+ * Comparison of what patterns allow at a specific segment position.
+ * @public
+ */
+export 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 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 type SegmentConstraintType = 'literal' | 'wildcard' | 'charclass' | 'any' | 'any_sequence' | 'end' | 'unreachable';
+/**
+ * High-level structural differences between patterns.
+ * @public
+ */
+export 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 pattern depth constraints.
+ * @public
+ */
+export 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;
+}
+/**
+ * Comparison of required path prefixes.
+ * @public
+ */
+export 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;
+}
+/**
+ * Comparison of required path suffixes (e.g., file extensions).
+ * @public
+ */
+export 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;
+}
+/**
+ * Comparison of pattern anchoring (absolute vs relative).
+ * @public
+ */
+export 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;
+}
+/**
+ * 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 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;
+}
+/**
+ * A human-readable description of a set of paths.
+ * @public
+ */
+export 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;
+}
+/**
+ * Detailed analysis of two patterns' relationship.
+ *
+ * Provides comprehensive data for understanding how two patterns relate,
+ * including the intersection and set differences.
+ *
+ * @public
+ */
+export 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;
+}
+//# sourceMappingURL=containment.d.ts.map

package/dist/types/containment.d.ts.map

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

package/dist/types/containment.js

@@ -0,0 +1,5 @@
+// =============================================================================
+// CONTAINMENT ANALYSIS
+// =============================================================================
+export {};
+//# sourceMappingURL=containment.js.map

package/dist/types/containment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"containment.js","sourceRoot":"","sources":["../../src/types/containment.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,uBAAuB;AACvB,gFAAgF"}

package/dist/types/errors.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Error codes for pattern validation failures.
+ * @public
+ */
+export 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';
+/**
+ * A pattern validation error with location information.
+ * @public
+ */
+export 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 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);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/types/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/types/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GACxB,kBAAkB,GAClB,kBAAkB,GAClB,gBAAgB,GAChB,iBAAiB,GACjB,eAAe,GACf,iBAAiB,GACjB,eAAe,GACf,gBAAgB,GAChB,gBAAgB,GAChB,eAAe,GACf,cAAc,GACd,iBAAiB,CAAA;AAErB;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,gCAAgC;IAChC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAA;IAE/B,uCAAuC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IAExB,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAE1B,wCAAwC;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED;;;;;;;GAOG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,gCAAgC;IAChC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAA;IAE/B,kCAAkC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IAEtB,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;gBAEX,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAOnF"}

package/dist/types/errors.js

@@ -0,0 +1,24 @@
+/**
+ * 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 class AutomatonLimitError extends Error {
+    /** Error classification code */
+    code;
+    /** The limit that was exceeded */
+    limit;
+    /** The actual value that exceeded the limit */
+    actual;
+    constructor(code, message, limit, actual) {
+        super(message);
+        this.name = 'AutomatonLimitError';
+        this.code = code;
+        this.limit = limit;
+        this.actual = actual;
+    }
+}
+//# sourceMappingURL=errors.js.map