@descent-vtt/spec-guard 0.11.0 → 0.12.0

package/dist/glob.d.ts

@@ -1,12 +1,21 @@
 /**
- * Dependency-free glob matching and directory walking.
+ * Glob matching and directory walking.
  *
  * Windows shells do not expand globs, so `spec-guard "docs/**\/*.md"` must
  * behave identically on every platform. spec-guard therefore always expands
  * patterns itself instead of trusting the shell.
+ *
+ * Matching is spec-core's, copied into src/vendor/spec-core: one automaton that
+ * keeps a set of live states and so cannot backtrack, in three named dialects.
+ * Each kind of pattern here is one of them, read case-sensitively on every host.
+ * `glob=` is `ripgrep`, `exclude=`, `module=` and a layer are `gitignore`, and
+ * a pattern matched against a whole path from where it starts - `dirs=`, a
+ * required entry's name - is `path`. What is walked, and what the walk skips,
+ * stays here. ADR-0015.
  */
 import { type Io } from './io.js';
 import { type ScopePolicy, type SkipReason } from './scope.js';
+import { type Glob } from './vendor/spec-core/pattern/index.js';
 /** True when the pattern contains glob metacharacters. */
 export declare function isGlob(pattern: string): boolean;
 /** Normalises Windows separators so every internal path uses `/`. */
@@ -15,47 +24,107 @@ export declare function toPosix(value: string): string;
  * Converts a glob to an anchored RegExp.
  * Supports `*`, `**`, `?`, `[...]` and `{a,b}` - the subset every developer
  * already knows from .gitignore and ripgrep.
+ *
+ * @deprecated Nothing in spec-guard matches with this any more: a glob is read
+ * by spec-core's automaton, which cannot backtrack (ADR-0015). This compiled
+ * `*-*-*-*-*-*x` to a pattern that took 28 seconds to fail a 121-character
+ * name, read `**` inside a segment as crossing directories, and took an unclosed
+ * `[` or `{` as a literal. It stays for callers of the API, and the tests keep
+ * it as the oracle for everything the two readings agree on.
  */
 export declare function globToRegExp(pattern: string, options?: {
     ignoreCase?: boolean;
 }): RegExp;
 /**
  * An include glob in the one form both engines are given: forward slashes, no
- * leading `./`, and a trailing slash read as everything under the directory.
+ * surrounding space, no leading `./`, and a trailing slash read as everything
+ * under the directory.
  *
  * ripgrep used to be handed the glob as written, and matched nothing for
- * `./src/*.ts` or `src/` while the scanner matched the files. ADR-0014.
+ * `./src/*.ts` or `src/` while the scanner matched the files. ADR-0014. The
+ * space is trimmed because spec-core trims it, and ripgrep would have read it
+ * as part of a name.
  */
 export declare function normalizeGlob(pattern: string): string;
 /**
  * An `exclude` pattern in the one form both engines are given: forward slashes,
- * no leading `./` and no trailing slash. A leading `/` stays, because it means
- * something: see `createExcludeMatcher`.
+ * no surrounding space, no leading `./` and no trailing slash. A leading `/`
+ * stays, because it means something: see `createExcludeMatcher`.
  *
  * ripgrep used to be handed the pattern as written, and read three shapes
  * differently from the scanner. `./build` and `src\build` excluded nothing, and
  * `build/` did not exclude a file named `build`. ADR-0014.
  */
 export declare function normalizeExclude(pattern: string): string;
+/**
+ * Which part of a path decides whether a pattern matches it: its last segment,
+ * any one of its segments, or only the whole of it.
+ */
+export type PatternShape = 'last' | 'any' | 'whole';
+/** What of a path decides whether a glob or an exclusion matches it. */
+export declare function patternShape(pattern: string, kind: 'include' | 'exclude'): PatternShape;
+/**
+ * A predicate over paths from one compiled glob, asking the glob no more often
+ * than the pattern's shape requires.
+ *
+ * Every answer is the automaton's. But a Thompson automaton keeps a set of live
+ * states per character where a RegExp compiled to machine code, and asked of
+ * every path the matching took 26 times as long: 261 ms against 10 over the
+ * 10,446 paths in this repository's node_modules, for three globs and four
+ * exclusions (ADR-0015). A tree repeats its names - those paths hold 6,714
+ * distinct segments - and most patterns are one segment in every alternative,
+ * `*.ts`, `tests`, `node:fs`, whose answer for a path is their answer for its
+ * last segment or for one of its segments. So those are asked once per segment.
+ * Any other pattern can only match below the directories spec-core names as its
+ * bases, and a path outside all of them is answered without asking.
+ */
+export declare function globPredicate(glob: Pick<Glob, 'match' | 'bases'>, shape: PatternShape): (relativePath: string) => boolean;
+/**
+ * Why an include glob cannot be read, or null when it can.
+ *
+ * A malformed glob - an unclosed `[` or `{`, an extended glob such as `+(a|b)`,
+ * a `..` - used to be read anyway: as a literal, or as whatever the regular
+ * expression it compiled to happened to mean. A typo read as a literal is a
+ * filter that matches nothing and reports clean, so it is refused.
+ */
+export declare function globPatternError(pattern: string): string | null;
+/** Why a module pattern or a layer cannot be read, or null when it can. */
+export declare function modulePatternError(pattern: string, kind?: 'module' | 'layer'): string | null;
+/**
+ * A name a module pattern or a layer matches, or null when it matches none.
+ *
+ * The shortest spec-core's witness search finds, so a literal is itself -
+ * `node:fs`, `src/db` - and `@app/db/**` is a name just below `@app/db`.
+ * `spec-guard prove` imports it, to show a rule about the module that it can
+ * fail (ADR-0016).
+ */
+export declare function moduleWitness(pattern: string): string | null;
+/** Why a pattern read against a whole path - `dirs=`, a required entry's name - cannot be read, or null. */
+export declare function pathPatternError(pattern: string): string | null;
 /**
  * Why an exclude pattern can never leave anything out, or null when it can.
  *
- * Each of these matched nothing under both engines, and nothing said so. The
- * one that matters is `!`: in `.gitignore` it re-includes a path, and a list
- * copied from one kept `build` and silently lost `!build/generated/needed.ts`,
- * so the exclusion was wider than the list reads. A `..` or a drive path points
- * outside the root, where nothing is searched, and `.` or `/` names the root
- * itself, which no path under it is.
+ * Each of the first four matched nothing under both engines, and nothing said
+ * so. The one that matters is `!`: in `.gitignore` it re-includes a path, and a
+ * list copied from one kept `build` and silently lost
+ * `!build/generated/needed.ts`, so the exclusion was wider than the list reads.
+ * A `..` or a drive path points outside the root, where nothing is searched,
+ * and `.` or `/` names the root itself, which no path under it is. After those,
+ * whatever spec-core refuses: a malformed pattern excludes nothing either.
  */
 export declare function excludePatternError(pattern: string): string | null;
+/** The error for the first pattern in a list that cannot be read, by the given check, or null. */
+export declare function patternListError(patterns: readonly string[], check: (pattern: string) => string | null): string | null;
 /** The error for the first pattern in a list that can never exclude anything, or null. */
 export declare function excludeListError(patterns: readonly string[]): string | null;
 /**
  * Builds a predicate over root-relative POSIX paths.
  *
  * Following ripgrep's `-g` semantics, a pattern without a `/` is matched
- * against the file's basename (`*.ts` matches `src/deep/a.ts`), while a pattern
- * containing `/` is matched against the whole relative path.
+ * against the file's name at any depth (`*.ts` matches `src/deep/a.ts`), while
+ * a pattern containing `/` is matched against the whole relative path. Each
+ * alternative of a `{a,b}` decides that for itself. Throws for a pattern that
+ * cannot be read; a directive's patterns are refused before a matcher is built.
  */
 export declare function createGlobMatcher(patterns: readonly string[]): (relativePath: string) => boolean;
 /**
@@ -68,18 +137,43 @@ export declare function createGlobMatcher(patterns: readonly string[]): (relativ
  * directory, not a file of that name. ripgrep's `-g !pattern` already behaves
  * this way; matching it here is what keeps the two engines from disagreeing.
  *
- * The rule is one line: a pattern without a slash is tested against every path
- * segment; a pattern with a slash is tested against the path and each of its
- * ancestor directories.
- *
- * A leading slash counts, as it does in `.gitignore`: `/build` is the `build`
- * at the root, where `build` is one at any depth. ripgrep always read it that
- * way, and the scanner used to match nothing for it, so a rule excluding
- * `/target` gave a different count on a tree large enough for `auto` to pick
- * ripgrep. The slash is not part of any path, so it is dropped once it has
- * anchored the pattern.
+ * The rule is one line: a pattern matches a path or any directory above it,
+ * and it is anchored at the root when it holds a `/` anywhere but at its end.
+ * A leading slash anchors and is otherwise dropped, as it is in `.gitignore`:
+ * `/build` is the `build` at the root, where `build` is one at any depth.
+ * ripgrep always read it that way, and the scanner used to match nothing for
+ * it, so a rule excluding `/target` gave a different count on a tree large
+ * enough for `auto` to pick ripgrep.
  */
 export declare function createExcludeMatcher(patterns: readonly string[]): (relativePath: string) => boolean;
+/**
+ * Builds a predicate for one pattern matched against a whole path from where
+ * it starts: `dirs="*"` against a directory below a target, a required entry's
+ * name against the names in a directory. `*` is one segment, `**` any number of
+ * them, and a pattern with no glob syntax names one path exactly.
+ */
+export declare function createPathMatcher(pattern: string): (relativePath: string) => boolean;
+/**
+ * The globs ripgrep is handed for one normalised pattern: the same set of
+ * paths spec-core reads it as, spelled so that ripgrep's globset reads it the
+ * same way.
+ *
+ * Handed the pattern as spec-guard normalised it, ripgrep still read four
+ * shapes differently from the scanner, and each is measured in ADR-0015:
+ * - it decides whether a glob is anchored from the whole glob, where spec-core
+ *   decides for each alternative of its braces, so `{src/*.ts,*.md}` found
+ *   `*.md` only at the root;
+ * - it drops an empty alternative, so `{,src/}a.ts` never found `a.ts`;
+ * - it keeps `.` and empty segments, which spec-core drops, so `src/./a.ts`
+ *   matched nothing;
+ * - it refuses a `}` that closes nothing, which spec-core reads as itself.
+ *
+ * So the braces are expanded here, one glob per alternative, each alternative
+ * is cleaned of `.` and empty segments and anchored or not by its own shape,
+ * and a lone `}` is written as the class `[}]`. Only ever given a pattern
+ * spec-core accepts, since a directive's are refused before anything runs.
+ */
+export declare function ripgrepGlobs(normalized: string): string[];
 export interface WalkOptions {
     /**
      * What may be walked. Defaults to DEFAULT_SCOPE.
@@ -157,10 +251,20 @@ export declare function globBase(pattern: string): {
     base: string;
     rest: string;
 };
+/**
+ * Why a spec pattern cannot be read, or null when it can.
+ *
+ * Asked by the command line and the configuration before anything runs, in the
+ * words `expandSpecPatterns` would throw. A path with no glob syntax is a path,
+ * found or not; only a glob can be malformed.
+ */
+export declare function specPatternError(pattern: string): string | null;
 /**
  * Expands CLI spec patterns into a sorted, de-duplicated list of absolute file
  * paths. Plain paths are taken literally; a directory expands to the Markdown
- * files it contains.
+ * files it contains; a glob is read by `readSpecGlob`. A pattern spec-core
+ * refuses is an error that names it, where it used to be read as a literal and
+ * match nothing.
  */
 export declare function expandSpecPatterns(patterns: readonly string[], root: string, defaultExtensions?: readonly string[], io?: Io): Promise<string[]>;
 //# sourceMappingURL=glob.d.ts.map

package/dist/glob.d.ts.map

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