@descent-vtt/spec-brief 0.1.0 → 0.2.0

package/dist/glob.d.ts

@@ -1,46 +1,41 @@
 /**
- * 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.
  */
-export type CharToken = {
-    readonly kind: 'literal';
-    readonly char: string;
-} | {
-    readonly kind: 'any';
-} | {
-    readonly kind: 'star';
-} | {
-    readonly kind: 'class';
-    readonly negated: boolean;
-    readonly ranges: readonly (readonly [number, number])[];
-};
-export type Segment = {
-    readonly kind: 'globstar';
-} | {
-    readonly kind: 'pattern';
-    readonly tokens: readonly CharToken[];
-    readonly literal: boolean;
-};
+import { isGlobSyntax, type Glob as CoreGlob, type LiteralReading, WITNESS_BUDGET, type Witness } from './vendor/spec-core/pattern/index.js';
+export { isGlobSyntax, type LiteralReading, WITNESS_BUDGET, type Witness };
+/** A literal path a pattern names, and how it was read. */
+export interface Literal {
+    readonly path: string;
+    readonly reading: LiteralReading;
+}
 export interface Glob {
     readonly source: string;
-    /** One sequence of segments per brace alternative; a path matches when any does. */
-    readonly alternatives: readonly (readonly Segment[])[];
+    /** The compiled pattern: spec-core's `path` dialect, case-sensitive. */
+    readonly compiled: CoreGlob;
+    /** Each path the pattern names with no glob syntax, one per brace alternative; empty when it has none. */
+    readonly literals: readonly Literal[];
 }
 export type GlobParse = {
     readonly ok: true;
@@ -49,31 +44,59 @@ export type GlobParse = {
     readonly ok: false;
     readonly error: string;
 };
-/** More alternatives than this is a pattern nobody meant. */
-export declare const MAX_ALTERNATIVES = 256;
 export interface ParseOptions {
-    /** Whether a literal path is a file, from the tree when it is known. */
-    readonly isFile?: ((path: string) => boolean) | undefined;
+    /**
+     * How a path with no glob syntax is read: `file`, that path alone;
+     * `directory`, everything beneath it; `either`, both. A function is asked
+     * per literal path, as {@link readingIn} answers for a tree. `file` when
+     * unset: a path nothing says is a directory is not read as one.
+     */
+    readonly literal?: LiteralReading | ((path: string) => LiteralReading) | undefined;
 }
+/** Parses a scope pattern, or says why it cannot. */
 export declare function parseGlob(source: string, options?: ParseOptions): GlobParse;
+/**
+ * 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 declare function matchGlob(glob: Glob, path: string): boolean;
 /**
- * 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 declare function intersectGlobs(a: Glob, b: Glob): string | null;
+export declare function globWitness(include: readonly Glob[], exclude?: readonly Glob[], budget?: number): Witness;
+/** Whether every path `inner` matches is matched by one of `outer`, or `undecided`. */
+export declare function globCovers(outer: readonly Glob[], inner: Glob, budget?: number): boolean | 'undecided';
 /**
- * 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 declare function intersectTokens(x: readonly CharToken[], y: readonly CharToken[]): string | null;
+export declare function intersectGlobs(a: Glob, b: Glob, budget?: number): string | 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.
+ * 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.
  */
+export declare function globBases(glob: Glob): readonly string[];
+/** The first of {@link globBases}: the 0.1 interface, kept for the library's callers. */
 export declare function globBase(glob: Glob): string;
+/** A name with an extension, `login.ts` or `.eslintrc.json`, and not a dot-name such as `.github`. */
+export declare function hasExtension(name: string): boolean;
+/** The files a tree holds, and every directory above one. */
+export interface Tree {
+    readonly files: ReadonlySet<string>;
+    readonly directories: ReadonlySet<string>;
+}
+/** The tree a list of files describes. Built once per list, which every brief of a run shares. */
+export declare function treeOf(files: readonly string[]): Tree;
+/** What the tree holds at a path: a file, a directory, or nothing. */
+export declare function held(tree: Tree, path: string): 'file' | 'directory' | null;
+/**
+ * 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 declare function readingIn(files: readonly string[] | null): (path: string) => LiteralReading;