@descent-vtt/spec-brief 0.1.0 → 0.2.0

package/dist/glob.js

@@ -1,465 +1,136 @@
 /**
- * Globs: parsing, matching, and deciding whether two globs can name the same file.
+ * Scopes as globs: spec-core's `path` dialect, read the way spec-brief reads a
+ * brief.
  *
- * The dialect is the one people type: `**`, `*`, `?`, `[abc]`, `[!a-z]`,
- * `{a,b}` and `\` to escape. A pattern with no glob syntax at all names a
- * directory and everything beneath it, so `src/auth` covers
- * `src/auth/login.ts` - unless it names a file, one the tree holds or one with
- * an extension, which matches only itself. A trailing `/` always means a
- * directory. Paths
- * are repository-relative and POSIX, and matching is case-sensitive on every
- * host, because git's paths are and a result should not depend on who ran it.
- * `*` matches a leading dot; a scope that forgot its dotfiles is not a scope
- * that excludes them.
+ * The syntax, the automaton and the witness search are spec-core's, copied
+ * into `src/vendor/` and verified by hash, so the family's tools read one
+ * pattern the same way (spec-core ADR-0003). What is decided here is what
+ * spec-brief adds around it:
  *
- * Nothing here compiles to a `RegExp`. Matching and intersection are dynamic
- * programmes over the pattern and the subject, so a pattern of `*a*a*a*a*b`
- * against a long name costs the product of their lengths and cannot backtrack
- * into an exponent. The same property is why the sibling tools match their own
- * globs this way.
+ * - A pattern is relative to the repository root, so a leading `/` is refused
+ *   rather than rooted at the filesystem; and a list entry's `!` has no list to
+ *   belong to in a scope, so it is refused rather than read.
+ * - Paths compare case-sensitively on every host, as git's do.
+ * - A path with no glob syntax is read as the tree reads it: a file the tree
+ *   holds is that file, a directory it holds is everything beneath it, and a
+ *   path it does not hold is a file, unless it is written with a trailing `/`.
+ *   The tree, not the spelling, knows that `Dockerfile` is a file and
+ *   `docs/v1.2` a directory (ADR-0005, amended 2026-09-26).
+ * - A trailing `/**` is at least one segment, so `docs/**` is the directory's
+ *   contents and a collision witness is always a file.
+ *
+ * Nothing here compiles to a `RegExp`. Matching costs at most the pattern's
+ * size times the path's length, and a question about two scopes that cannot be
+ * answered within the search's budget answers `undecided`, never a guess.
  */
-/** More alternatives than this is a pattern nobody meant. */
-export const MAX_ALTERNATIVES = 256;
-const SLASH = 0x2f;
-const GLOBSTAR = { kind: 'globstar' };
-/** A name with an extension, `login.ts` or `.eslintrc.json`, and not a dot-directory such as `.github`. */
-function hasExtension(name) {
-    return /.\.[^.]+$/.test(name);
-}
+import { AutomatonTooLarge, globCovers as coreCovers, globWitness as coreWitness, isGlobSyntax, parseGlob as coreParse, WITNESS_BUDGET, } from './vendor/spec-core/pattern/index.js';
+import { segments } from './vendor/spec-core/path/index.js';
+export { isGlobSyntax, WITNESS_BUDGET };
+/** Parses a scope pattern, or says why it cannot. */
 export function parseGlob(source, options = {}) {
-    let pattern = source.trim();
-    if (pattern.length === 0)
-        return { ok: false, error: 'the pattern is empty' };
+    const pattern = source.trim();
     if (pattern.startsWith('!'))
         return { ok: false, error: 'negated patterns are not supported; narrow the positive pattern' };
     if (pattern.startsWith('/'))
         return { ok: false, error: 'a pattern is relative to the repository root and cannot start with "/"' };
-    if (/(?:^|[^\\])[@+!?*]\(/.test(pattern))
-        return { ok: false, error: 'extended globs such as "+(a|b)" are not supported' };
-    // A leading "./" needs no stripping: "." segments are dropped below.
-    if (pattern.endsWith('/'))
-        pattern = `${pattern}**`;
-    const expanded = expandBraces(pattern);
-    if (typeof expanded === 'string')
-        return { ok: false, error: expanded };
-    const alternatives = [];
-    for (const alternative of expanded) {
-        const segments = [];
-        for (const raw of alternative.split('/')) {
-            if (raw === '' || raw === '.')
-                continue;
-            if (raw === '..')
-                return { ok: false, error: 'a pattern cannot leave the repository with ".."' };
-            if (raw === '**') {
-                if (segments[segments.length - 1]?.kind !== 'globstar')
-                    segments.push(GLOBSTAR);
-                continue;
-            }
-            const tokens = tokenize(raw);
-            if (typeof tokens === 'string')
-                return { ok: false, error: tokens };
-            segments.push({ kind: 'pattern', tokens, literal: tokens.every((t) => t.kind === 'literal') });
-        }
-        if (segments.length === 0)
-            return { ok: false, error: 'the pattern names no path' };
-        // A path with no glob syntax names a directory and everything beneath it,
-        // unless it names a file: one the tree has, or one with an extension.
-        // Treating a file as a directory would let "src/a.ts" overlap
-        // "**/session.ts" through a "src/a.ts/session.ts" nobody can create.
-        if (segments.every((s) => s.kind === 'pattern' && s.literal)) {
-            const path = segments
-                .map((s) => (s.kind === 'pattern' ? s.tokens.map((t) => (t.kind === 'literal' ? t.char : '')).join('') : ''))
-                .join('/');
-            const last = path.slice(path.lastIndexOf('/') + 1);
-            if (options.isFile?.(path) !== true && !hasExtension(last))
-                segments.push(GLOBSTAR);
-        }
-        alternatives.push(segments);
-    }
-    return { ok: true, glob: { source, alternatives } };
-}
-/** Expands `{a,b}` groups, innermost last, or says why the pattern is malformed. */
-function expandBraces(pattern) {
-    let open = -1;
-    let depth = 0;
-    for (let i = 0; i < pattern.length; i += 1) {
-        const ch = pattern.charAt(i);
-        if (ch === '\\') {
-            i += 1;
-            continue;
-        }
-        if (ch === '[') {
-            const close = classEnd(pattern, i);
-            if (close > 0)
-                i = close;
-            continue;
-        }
-        if (ch === '{') {
-            if (depth === 0)
-                open = i;
-            depth += 1;
-        }
-        else if (ch === '}') {
-            if (depth === 0)
-                return 'a "}" closes no "{"';
-            depth -= 1;
-            if (depth === 0) {
-                const options = splitTopLevel(pattern.slice(open + 1, i));
-                const prefix = pattern.slice(0, open);
-                const suffix = pattern.slice(i + 1);
-                const results = [];
-                for (const option of options) {
-                    const expanded = expandBraces(`${prefix}${option}${suffix}`);
-                    if (typeof expanded === 'string')
-                        return expanded;
-                    results.push(...expanded);
-                    if (results.length > MAX_ALTERNATIVES)
-                        return `the braces expand to more than ${MAX_ALTERNATIVES} patterns`;
-                }
-                return results;
-            }
-        }
-    }
-    if (depth > 0)
-        return 'a "{" is never closed';
-    return [pattern];
-}
-function splitTopLevel(body) {
-    const parts = [];
-    let depth = 0;
-    let start = 0;
-    for (let i = 0; i < body.length; i += 1) {
-        const ch = body.charAt(i);
-        if (ch === '\\')
-            i += 1;
-        else if (ch === '{')
-            depth += 1;
-        else if (ch === '}')
-            depth -= 1;
-        else if (ch === ',' && depth === 0) {
-            parts.push(body.slice(start, i));
-            start = i + 1;
-        }
-    }
-    parts.push(body.slice(start));
-    return parts;
-}
-/** The index of the `]` closing a class opened at `open`, or -1. */
-function classEnd(pattern, open) {
-    let i = open + 1;
-    if (pattern.charAt(i) === '!' || pattern.charAt(i) === '^')
-        i += 1;
-    if (pattern.charAt(i) === ']')
-        i += 1;
-    for (; i < pattern.length; i += 1) {
-        const ch = pattern.charAt(i);
-        if (ch === '/')
-            return -1;
-        if (ch === ']')
-            return i;
-    }
-    return -1;
-}
-function tokenize(segment) {
-    const tokens = [];
-    const chars = Array.from(segment);
-    for (let i = 0; i < chars.length; i += 1) {
-        const ch = chars[i];
-        if (ch === '\\') {
-            const next = chars[i + 1];
-            // A backslash before a letter, a digit or nothing is a Windows separator, not an escape.
-            if (next === undefined || /[A-Za-z0-9]/.test(next))
-                return '"\\" escapes glob syntax; separate directories with "/"';
-            tokens.push({ kind: 'literal', char: next });
-            i += 1;
-        }
-        else if (ch === '*') {
-            if (tokens[tokens.length - 1]?.kind !== 'star')
-                tokens.push({ kind: 'star' });
-        }
-        else if (ch === '?') {
-            tokens.push({ kind: 'any' });
-        }
-        else if (ch === '[') {
-            const parsed = readClass(chars, i);
-            if (typeof parsed === 'string')
-                return parsed;
-            tokens.push(parsed.token);
-            i = parsed.end;
-        }
-        else {
-            tokens.push({ kind: 'literal', char: ch });
-        }
-    }
-    return tokens;
-}
-function readClass(chars, open) {
-    let i = open + 1;
-    let negated = false;
-    if (chars[i] === '!' || chars[i] === '^') {
-        negated = true;
-        i += 1;
-    }
-    const ranges = [];
-    let first = true;
-    for (; i < chars.length; i += 1) {
-        const ch = chars[i];
-        // Never empty: the first character is always a member, even "]".
-        if (ch === ']' && !first)
-            return { token: { kind: 'class', negated, ranges }, end: i };
-        first = false;
-        let lo = ch;
-        if (ch === '\\' && chars[i + 1] !== undefined) {
-            i += 1;
-            lo = chars[i];
-        }
-        let hi = lo;
-        if (chars[i + 1] === '-' && chars[i + 2] !== undefined && chars[i + 2] !== ']') {
-            hi = chars[i + 2];
-            i += 2;
-        }
-        const from = lo.codePointAt(0);
-        const to = hi.codePointAt(0);
-        if (to < from)
-            return `the range "${lo}-${hi}" runs backwards`;
-        ranges.push([from, to]);
-    }
-    return 'a "[" is never closed';
-}
-function splitPath(path) {
-    return path.split('/').filter((s) => s !== '' && s !== '.');
-}
-/** Membership of a class. A slash is never asked about: paths are matched a segment at a time. */
-function inClass(token, point) {
-    const inside = token.ranges.some(([lo, hi]) => point >= lo && point <= hi);
-    return token.negated ? !inside : inside;
-}
-function charMatches(token, char) {
-    switch (token.kind) {
-        case 'literal':
-            return token.char === char;
-        case 'any':
-            return true;
-        case 'class':
-            return inClass(token, char.codePointAt(0));
-    }
-}
-/** Whether one segment of a path matches a pattern segment's tokens. */
-function tokensMatch(tokens, subject) {
-    const chars = Array.from(subject);
-    // next[j]: tokens[i+1..] match chars[j..]; filled from the end of both.
-    let next = new Array(chars.length + 1).fill(false);
-    next[chars.length] = true;
-    for (let i = tokens.length - 1; i >= 0; i -= 1) {
-        const token = tokens[i];
-        const row = new Array(chars.length + 1).fill(false);
-        for (let j = chars.length; j >= 0; j -= 1) {
-            row[j] =
-                token.kind === 'star'
-                    ? next[j] || (j < chars.length && row[j + 1])
-                    : j < chars.length && charMatches(token, chars[j]) && next[j + 1];
-        }
-        next = row;
+    const given = options.literal ?? 'file';
+    const literals = [];
+    const literal = (path) => {
+        const reading = typeof given === 'function' ? given(path) : given;
+        literals.push({ path, reading });
+        return reading;
+    };
+    try {
+        const parsed = coreParse(pattern, { dialect: 'path', caseSensitive: true, literal });
+        return parsed.ok ? { ok: true, glob: { source, compiled: parsed.glob, literals } } : parsed;
     }
-    return next[0];
-}
-function segmentsMatch(segments, path) {
-    let next = new Array(path.length + 1).fill(false);
-    next[path.length] = true;
-    for (let i = segments.length - 1; i >= 0; i -= 1) {
-        const segment = segments[i];
-        const row = new Array(path.length + 1).fill(false);
-        for (let j = path.length; j >= 0; j -= 1) {
-            row[j] =
-                segment.kind === 'globstar'
-                    ? next[j] || (j < path.length && row[j + 1])
-                    : j < path.length && tokensMatch(segment.tokens, path[j]) && next[j + 1];
-        }
-        next = row;
+    catch (error) {
+        // Too many states is a pattern nobody meant; anything else is a defect to surface.
+        if (error instanceof AutomatonTooLarge)
+            return { ok: false, error: error.message };
+        throw error;
     }
-    return next[0];
 }
+/**
+ * Whether a path matches. The path is read as a repository path: empty and
+ * `.` segments are dropped, so `./src//a.ts` is `src/a.ts`.
+ */
 export function matchGlob(glob, path) {
-    const segments = splitPath(path);
-    if (segments.length === 0)
-        return false;
-    return glob.alternatives.some((alternative) => segmentsMatch(alternative, segments));
+    const canonical = segments(path).join('/');
+    return canonical !== '' && glob.compiled.match(canonical);
 }
 /**
- * A path both globs match, or `null` when there is none. The answer is exact
- * for the dialect above: a `null` means no file can be in both scopes, and a
- * path is a witness a reader can check by eye.
+ * A shortest path every glob in `include` matches and none in `exclude` does,
+ * `none` as a proof that there is no such path, or `undecided` when the search
+ * met its budget first.
  */
-export function intersectGlobs(a, b) {
-    for (const left of a.alternatives) {
-        for (const right of b.alternatives) {
-            const witness = intersectSegments(left, right);
-            if (witness !== null)
-                return witness.length === 0 ? 'x' : witness.join('/');
-        }
-    }
-    return null;
+export function globWitness(include, exclude = [], budget = WITNESS_BUDGET) {
+    return coreWitness(include.map((g) => g.compiled), exclude.map((g) => g.compiled), budget);
 }
-const ANY_SEGMENT = [{ kind: 'star' }];
-function intersectSegments(p, q) {
-    const memo = new Map();
-    const width = q.length + 1;
-    const visit = (i, j) => {
-        const key = i * width + j;
-        const cached = memo.get(key);
-        if (cached !== undefined)
-            return cached;
-        const result = step(i, j);
-        memo.set(key, result);
-        return result;
-    };
-    const prepend = (head, tail) => head === null || tail === null ? null : [head, ...tail];
-    const step = (i, j) => {
-        if (i === p.length && j === q.length)
-            return [];
-        const x = p[i];
-        const y = q[j];
-        if (x?.kind === 'globstar') {
-            const skip = visit(i + 1, j);
-            if (skip !== null)
-                return skip;
-            if (y === undefined)
-                return null;
-            if (y.kind === 'globstar')
-                return visit(i, j + 1);
-            return prepend(intersectTokens(y.tokens, ANY_SEGMENT), visit(i, j + 1));
-        }
-        if (y?.kind === 'globstar') {
-            const skip = visit(i, j + 1);
-            if (skip !== null)
-                return skip;
-            if (x === undefined)
-                return null;
-            return prepend(intersectTokens(x.tokens, ANY_SEGMENT), visit(i + 1, j));
-        }
-        if (x === undefined || y === undefined)
-            return null;
-        const head = intersectTokens(x.tokens, y.tokens);
-        return head === null ? null : prepend(head, visit(i + 1, j + 1));
-    };
-    return visit(0, 0);
+/** Whether every path `inner` matches is matched by one of `outer`, or `undecided`. */
+export function globCovers(outer, inner, budget = WITNESS_BUDGET) {
+    return coreCovers(outer.map((g) => g.compiled), inner.compiled, budget);
 }
 /**
- * A non-empty string both token sequences match, or `null`.
- *
- * Complete by a shortest-witness argument: in a shortest common string, no
- * character is absorbed by a star on both sides at once (dropping it would
- * leave a shorter one), so every character advances at least one sequence,
- * and the five moves below are all the ways that can happen.
+ * A path both globs match, or `null` when there is none: the 0.1 interface,
+ * kept for the library's callers. It cannot say `undecided`, so a search that
+ * meets its budget throws; {@link globWitness} answers in three ways.
  */
-export function intersectTokens(x, y) {
-    const memo = new Map();
-    const width = y.length + 1;
-    const visit = (i, j) => {
-        const key = i * width + j;
-        const cached = memo.get(key);
-        if (cached !== undefined)
-            return cached;
-        const result = step(i, j);
-        memo.set(key, result);
-        return result;
-    };
-    const prepend = (head, tail) => head === null || tail === null ? null : head + tail;
-    const step = (i, j) => {
-        if (i === x.length && j === y.length)
-            return '';
-        const a = x[i];
-        const b = y[j];
-        if (a?.kind === 'star') {
-            const skip = visit(i + 1, j);
-            if (skip !== null)
-                return skip;
-            if (b === undefined)
-                return null;
-            if (b.kind === 'star')
-                return visit(i, j + 1);
-            return prepend(witnessChar(b), visit(i, j + 1));
-        }
-        if (b?.kind === 'star') {
-            const skip = visit(i, j + 1);
-            if (skip !== null)
-                return skip;
-            if (a === undefined)
-                return null;
-            return prepend(witnessChar(a), visit(i + 1, j));
-        }
-        if (a === undefined || b === undefined)
-            return null;
-        return prepend(meet(a, b), visit(i + 1, j + 1));
-    };
-    const witness = visit(0, 0);
-    // Empty only when both sides are nothing but stars, and then any name will do.
-    return witness === '' ? 'x' : witness;
-}
-function accepts(token, point) {
-    if (point === SLASH)
-        return false;
-    switch (token.kind) {
-        case 'literal':
-            return token.char.codePointAt(0) === point;
-        case 'any':
-            return true;
-        case 'class':
-            return inClass(token, point);
+export function intersectGlobs(a, b, budget = WITNESS_BUDGET) {
+    const witness = globWitness([a, b], [], budget);
+    if (witness.kind === 'undecided') {
+        throw new Error(`whether "${a.source}" and "${b.source}" meet is undecided within the search's budget`);
     }
+    return witness.kind === 'found' ? witness.path : null;
 }
 /**
- * Every point where the set of characters all the tokens accept could begin.
- *
- * Each token accepts a union of intervals: a literal one point, a positive
- * class its ranges, a negated class and `?` everything outside theirs. Less the
- * slash. The least character of an intersection of such sets is the left end
- * of one of its intervals, so it is one of these points, and checking them
- * all decides the intersection exactly. `0` is also the point after the
- * slash, and readable characters go first, so that a witness is one a person
- * would type.
+ * The directories a walk must enter to find every match, one per brace
+ * alternative: the leading literal segments, or a literal file's directory.
+ * `''` for an alternative that can match at the root.
  */
-function candidates(tokens) {
-    const points = [0x78, 0x61, 0x30, 0x5f, 0x2d, 0x21, 0];
-    for (const token of tokens) {
-        if (token.kind === 'literal')
-            points.push(token.char.codePointAt(0));
-        if (token.kind === 'class') {
-            for (const [lo, hi] of token.ranges)
-                points.push(lo, hi + 1);
-        }
-    }
-    return points;
+export function globBases(glob) {
+    return glob.compiled.bases;
 }
-/** A character every token accepts, or `null` when there is none. */
-function pick(tokens) {
-    for (const point of candidates(tokens)) {
-        if (point <= 0x10ffff && tokens.every((t) => accepts(t, point)))
-            return String.fromCodePoint(point);
-    }
-    return null;
+/** The first of {@link globBases}: the 0.1 interface, kept for the library's callers. */
+export function globBase(glob) {
+    // One base per alternative, and a pattern has at least one.
+    return glob.compiled.bases[0];
 }
-function witnessChar(token) {
-    return pick([token]);
+/** A name with an extension, `login.ts` or `.eslintrc.json`, and not a dot-name such as `.github`. */
+export function hasExtension(name) {
+    return /.\.[^.]+$/.test(name);
+}
+const trees = new WeakMap();
+/** The tree a list of files describes. Built once per list, which every brief of a run shares. */
+export function treeOf(files) {
+    const known = trees.get(files);
+    if (known !== undefined)
+        return known;
+    const directories = new Set();
+    for (const file of files) {
+        for (let slash = file.indexOf('/'); slash !== -1; slash = file.indexOf('/', slash + 1))
+            directories.add(file.slice(0, slash));
+    }
+    const tree = { files: new Set(files), directories };
+    trees.set(files, tree);
+    return tree;
 }
-function meet(a, b) {
-    return pick([a, b]);
+/** What the tree holds at a path: a file, a directory, or nothing. */
+export function held(tree, path) {
+    if (tree.files.has(path))
+        return 'file';
+    return tree.directories.has(path) ? 'directory' : null;
 }
 /**
- * The directory a glob is rooted in: its leading literal segments. A pattern
- * that names a file is rooted in that file's directory.
+ * How a tree reads a literal path: a directory it holds is a directory, and
+ * anything else is a file. Without a tree nothing is known to be a directory,
+ * so every literal is a file; a trailing `/` says otherwise, and never reaches
+ * this question.
  */
-export function globBase(glob) {
-    const first = glob.alternatives[0];
-    const literal = [];
-    for (const segment of first) {
-        if (segment.kind !== 'pattern' || !segment.literal)
-            break;
-        literal.push(segment.tokens.map((t) => (t.kind === 'literal' ? t.char : '')).join(''));
-    }
-    // A literal file path is rooted in its directory; a literal directory in itself.
-    if (literal.length === first.length)
-        literal.pop();
-    return literal.join('/');
+export function readingIn(files) {
+    if (files === null)
+        return () => 'file';
+    const tree = treeOf(files);
+    return (path) => (held(tree, path) === 'directory' ? 'directory' : 'file');
 }
 //# sourceMappingURL=glob.js.map