@descent-vtt/spec-graph 0.4.0 → 0.5.0

package/dist/regex.d.ts

@@ -0,0 +1,64 @@
+/**
+ * A regular-expression matcher that cannot backtrack.
+ *
+ * `~=` is the one predicate in the selector language that used to hand a
+ * user-supplied string to `RegExp` and wait. That is tolerable at a prompt,
+ * where a human can press Ctrl-C. It is not tolerable in `.spec-graph.json`,
+ * where the same string runs unattended in CI against every node in the corpus.
+ *
+ * The cost is neither theoretical nor exotic. `^([A-Za-z0-9_]+[ ]?)+$` is what
+ * somebody writes to say "the title is words separated by single spaces", and
+ * against a title that does not match, V8 tries one branch per way of cutting
+ * each word into pieces:
+ *
+ * ```text
+ *                                                          RegExp      here
+ * the quick brown fox jumps over the lazy dog!               0.9s      11us
+ * the quick brown fox jumps over the lazy dog and!           5.4s      12us
+ * the quick brown fox jumps over the lazy dog and keeps!     103s      13us
+ * ```
+ *
+ * Each word of k letters can be cut into pieces 2^(k-1) ways, and the engine
+ * tries the product of those, which is why adding one five-letter word costs
+ * another factor of sixteen. A sixty-character title does not finish this year.
+ *
+ * So a pattern here is compiled to a **non-deterministic finite automaton** and
+ * simulated over the subject one character at a time (Thompson, 1968), keeping
+ * a set of live states instead of a stack of choices. Each state is visited at
+ * most once per position, which makes the work exactly O(pattern x subject):
+ * the right-hand column above, growing with the subject and not with the
+ * pattern's ambiguity.
+ *
+ * What it costs is a dialect. Backreferences and lookaround are not regular and
+ * have no place in a linear automaton, so they are **rejected while compiling**,
+ * with a message and an offset, rather than accepted and then slow. That is the
+ * whole trade: a predicate that finishes, against a short list of constructs
+ * that a documentation selector never needed.
+ *
+ * Matching is case-insensitive and unanchored because that is what `~=` has
+ * always been - `new RegExp(source, 'i')` and `.test()`. There are no capture
+ * groups at all: nothing asks where the match was, only whether there was one,
+ * which is why this is a plain NFA simulation rather than a Pike VM.
+ *
+ * See ADR-0017.
+ */
+/** A pattern that will not compile, and where in it the problem starts. */
+export declare class PatternError extends Error {
+    /** Offset into the pattern source. */
+    readonly offset: number;
+    constructor(message: string, offset: number);
+}
+/** A compiled pattern. Immutable, reusable, and safe to cache. */
+export interface Matcher {
+    /** True when the pattern matches anywhere in the subject. */
+    test(subject: string): boolean;
+    /** State count. Published for the size test, and for nothing else. */
+    readonly size: number;
+}
+/**
+ * Compiles a pattern into a matcher.
+ *
+ * Throws {@link PatternError} on anything it cannot run in linear time, which
+ * is the point: the alternative to a message here is a build that stops.
+ */
+export declare function compilePattern(source: string): Matcher;