gurkencheck 0.0.6 → 0.0.9

package/dist/stats/similar.js

@@ -0,0 +1,173 @@
+/**
+ * Finding steps that are nearly, but not quite, the same step.
+ *
+ * `I am logged in` and `I'm logged in` are one behaviour written twice, and
+ * they cost two step definitions. Normalisation cannot join them - they
+ * really are different sentences - so they are grouped by how many single
+ * character edits it takes to turn one into the other.
+ *
+ * Edit distance is quadratic in the number of distinct steps, which on a
+ * large suite is millions of comparisons, so two cheap tests run first. Both
+ * are lower bounds on the distance, never overestimates, so a pair they
+ * reject could not have been close enough anyway:
+ *
+ * - two strings are at least as far apart as their lengths differ;
+ * - every edit changes the tally of characters by at most two, so half the
+ *   difference between two tallies is a floor on the distance as well.
+ */
+export const DEFAULT_SIMILARITY = { ratio: 0.85, minLength: 8, maxEdits: 3 };
+/** How many buckets the character tally uses. */
+const TALLY_SIZE = 32;
+/**
+ * A rough tally of the characters in a string.
+ *
+ * Characters share buckets, which can only make two tallies look more alike
+ * than they are - and since the tally is used to rule pairs out, looking more
+ * alike is the safe direction to be wrong in.
+ */
+function tally(text) {
+    const counts = new Array(TALLY_SIZE).fill(0);
+    for (let index = 0; index < text.length; index++) {
+        const bucket = text.charCodeAt(index) % TALLY_SIZE;
+        counts[bucket] = (counts[bucket] ?? 0) + 1;
+    }
+    return counts;
+}
+/**
+ * True when two tallies are far enough apart that no run of `limit` edits
+ * could join the strings behind them.
+ *
+ * This is the test almost every pair fails, so it stops as soon as the answer
+ * is settled rather than finishing the count.
+ */
+function tallyRulesOut(left, right, limit) {
+    const budget = limit * 2;
+    let sum = 0;
+    for (let bucket = 0; bucket < TALLY_SIZE; bucket++) {
+        sum += Math.abs((left[bucket] ?? 0) - (right[bucket] ?? 0));
+        if (sum > budget) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * The Levenshtein distance between two strings, giving up as soon as it is
+ * certain to exceed `limit` and returning `limit + 1` in that case.
+ *
+ * Every value in a row of the table is a lower bound on everything below it,
+ * so once the whole row is past the limit there is no way back.
+ */
+export function boundedEditDistance(left, right, limit) {
+    if (left === right) {
+        return 0;
+    }
+    if (Math.abs(left.length - right.length) > limit) {
+        return limit + 1;
+    }
+    const width = right.length;
+    let previous = Array.from({ length: width + 1 }, (_, index) => index);
+    let current = new Array(width + 1).fill(0);
+    for (let row = 1; row <= left.length; row++) {
+        current[0] = row;
+        let rowMinimum = row;
+        const leftCharacter = left.charCodeAt(row - 1);
+        for (let column = 1; column <= width; column++) {
+            const substitution = (previous[column - 1] ?? 0) + (leftCharacter === right.charCodeAt(column - 1) ? 0 : 1);
+            const deletion = (previous[column] ?? 0) + 1;
+            const insertion = (current[column - 1] ?? 0) + 1;
+            const best = Math.min(substitution, deletion, insertion);
+            current[column] = best;
+            if (best < rowMinimum) {
+                rowMinimum = best;
+            }
+        }
+        if (rowMinimum > limit) {
+            return limit + 1;
+        }
+        const finished = previous;
+        previous = current;
+        current = finished;
+    }
+    return previous[width] ?? limit + 1;
+}
+/** Disjoint sets, used to join pairs of close steps into groups. */
+function makeSets(size) {
+    const parent = Array.from({ length: size }, (_, index) => index);
+    function find(item) {
+        let root = item;
+        while ((parent[root] ?? root) !== root) {
+            root = parent[root] ?? root;
+        }
+        let walk = item;
+        while ((parent[walk] ?? walk) !== root) {
+            const next = parent[walk] ?? walk;
+            parent[walk] = root;
+            walk = next;
+        }
+        return root;
+    }
+    return {
+        find,
+        union(a, b) {
+            const rootA = find(a);
+            const rootB = find(b);
+            if (rootA !== rootB) {
+                parent[rootB] = rootA;
+            }
+        },
+    };
+}
+/**
+ * Groups entries whose text is close enough to be the same step written two
+ * ways. Entries that are close to nothing are left out, so every group
+ * returned has at least two members, in the order they were given in.
+ */
+export function groupSimilar(entries, options = DEFAULT_SIMILARITY) {
+    // Sorting by length lets the search stop early: once two steps are too
+    // different in length, every step after this one is longer still.
+    const candidates = entries
+        .map((entry, index) => ({ index, text: entry.text, tally: tally(entry.text) }))
+        .filter((candidate) => candidate.text.length >= options.minLength)
+        .sort((a, b) => a.text.length - b.text.length);
+    const sets = makeSets(entries.length);
+    let joined = false;
+    for (let i = 0; i < candidates.length; i++) {
+        const left = candidates[i];
+        for (let j = i + 1; j < candidates.length; j++) {
+            const right = candidates[j];
+            const limit = Math.min(options.maxEdits, Math.floor((1 - options.ratio) * right.text.length));
+            // Sorted by length, so once a step is too much longer than this one,
+            // every step after it is longer still.
+            if (right.text.length - left.text.length > limit) {
+                break;
+            }
+            if (limit < 1 || tallyRulesOut(left.tally, right.tally, limit)) {
+                continue;
+            }
+            if (boundedEditDistance(left.text, right.text, limit) <= limit) {
+                sets.union(left.index, right.index);
+                joined = true;
+            }
+        }
+    }
+    if (!joined) {
+        return [];
+    }
+    const groups = new Map();
+    for (const candidate of candidates) {
+        const root = sets.find(candidate.index);
+        const member = { index: candidate.index, entry: entries[candidate.index] };
+        const group = groups.get(root);
+        if (group === undefined) {
+            groups.set(root, [member]);
+        }
+        else {
+            group.push(member);
+        }
+    }
+    return [...groups.values()]
+        .filter((group) => group.length > 1)
+        .map((group) => group.sort((a, b) => a.index - b.index).map((member) => member.entry));
+}
+//# sourceMappingURL=similar.js.map

package/dist/stats/similar.js.map

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

package/dist/stats/types.d.ts

@@ -0,0 +1,159 @@
+/**
+ * The shape of a statistics run.
+ *
+ * Everything here is complete: no list is cut short, no number is rounded to
+ * fit a screen. Trimming is the formatters' job, so that the JSON output is a
+ * full dataset - one a later run can be compared against - while the text
+ * report stays short enough to read.
+ */
+/** A summary of a set of counts, for numbers whose average hides the shape. */
+export interface Distribution {
+    /** How many values went into the summary. */
+    count: number;
+    min: number;
+    median: number;
+    /** The value nine tenths of the set are at or below. */
+    p90: number;
+    max: number;
+    mean: number;
+}
+/** One scenario, named well enough to go and find it. */
+export interface ScenarioRef {
+    name: string;
+    file: string;
+    line: number;
+    /** Steps written in the scenario itself, Background steps excluded. */
+    steps: number;
+}
+/** One entry of the step vocabulary: a normalised step and where it is used. */
+export interface StepEntry {
+    /** The step text after normalisation - what makes two steps "the same". */
+    text: string;
+    /** How many written steps normalise to this text. */
+    count: number;
+    /** The step text as somebody actually wrote it, the first time it appears. */
+    example: string;
+    /** Where that first sighting is. */
+    file: string;
+    line: number;
+}
+/** Normalised steps that differ only slightly from each other. */
+export interface SimilarGroup {
+    /** The steps in the group, most used first. */
+    members: StepEntry[];
+    /** Written steps covered by the whole group. */
+    total: number;
+}
+/** How often a tag is written. */
+export interface TagEntry {
+    name: string;
+    count: number;
+}
+/** A file the Gherkin parser refused, and so could not be counted. */
+export interface UnreadableFile {
+    file: string;
+    /** The parser's complaint, or the rule name it maps onto. */
+    reason: string;
+    line: number;
+}
+/** How many files were written in each Gherkin dialect. */
+export interface LanguageEntry {
+    /** The Gherkin language code, such as `en` or `de`. */
+    code: string;
+    files: number;
+}
+/** What is in the feature files, counted. */
+export interface Inventory {
+    features: number;
+    rules: number;
+    backgrounds: number;
+    /** Scenarios that are not Scenario Outlines. */
+    scenarios: number;
+    scenarioOutlines: number;
+    examplesTables: number;
+    /** Body rows across every Examples table; header rows are not counted. */
+    examplesRows: number;
+    /** Steps as written, Background steps included. */
+    steps: number;
+    dataTables: number;
+    docStrings: number;
+}
+/** How the steps of the suite divide between Given, When and Then. */
+export interface KeywordMix {
+    given: number;
+    when: number;
+    then: number;
+    /**
+     * Steps whose keyword resolves to nothing: an `And` or `But` written before
+     * anything for it to carry on from.
+     */
+    other: number;
+}
+/** What the steps of the suite look like taken together. */
+export interface StepStats {
+    /** Steps as written, Background steps included. */
+    total: number;
+    /** Distinct steps after normalisation. */
+    unique: number;
+    /**
+     * `unique / total`. Low means the team shares a vocabulary; high means
+     * everybody invents their own phrasing, and the step definitions rot.
+     */
+    uniqueRatio: number;
+    /** Distinct steps written exactly once - usually accidental one-offs. */
+    usedOnce: number;
+    /** Every distinct step, most used first. */
+    vocabulary: StepEntry[];
+    /** Steps that are nearly, but not quite, each other. */
+    similar: SimilarGroup[];
+    /** Given/When/Then mix, with `And` and `But` resolved to what they follow. */
+    keywords: KeywordMix;
+    /** Words per step, as a proxy for how detailed the steps have become. */
+    wordsPerStep: Distribution;
+}
+/** What the scenarios of the suite look like taken together. */
+export interface ScenarioStats {
+    /**
+     * The number of test cases: one per Scenario, and one per row of every
+     * Examples table. This is the number that predicts how long a suite takes
+     * to run, and almost nobody's mental count of it is right.
+     */
+    effective: number;
+    /** Steps per scenario, Background steps excluded. */
+    stepsPerScenario: Distribution;
+    /** Every scenario, longest first. */
+    largest: ScenarioRef[];
+}
+/** What the tags of the suite look like taken together. */
+export interface TagStats {
+    /** Tags as written, counting a tag once for every node carrying it. */
+    total: number;
+    unique: number;
+    /** Every distinct tag, most used first. */
+    vocabulary: TagEntry[];
+    /** Tags written exactly once - very often a typo of one written often. */
+    usedOnce: string[];
+    /**
+     * Scenarios carrying no tag of their own and inheriting none, and so
+     * reachable by no tag expression.
+     */
+    untaggedScenarios: number;
+}
+/** Everything one statistics run found. */
+export interface Statistics {
+    files: {
+        /** Files the search matched. */
+        total: number;
+        /** Files the parser accepted, and so the ones every other number is from. */
+        parsed: number;
+        /** Files the parser refused. Nothing in them is counted. */
+        unreadable: UnreadableFile[];
+    };
+    inventory: Inventory;
+    scenarios: ScenarioStats;
+    steps: StepStats;
+    tags: TagStats;
+    /** Dialects in use, most common first. A single stray entry is a bug. */
+    languages: LanguageEntry[];
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/stats/types.js

@@ -0,0 +1,10 @@
+/**
+ * The shape of a statistics run.
+ *
+ * Everything here is complete: no list is cut short, no number is rounded to
+ * fit a screen. Trimming is the formatters' job, so that the JSON output is a
+ * full dataset - one a later run can be compared against - while the text
+ * report stays short enough to read.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/stats/types.js.map

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

package/dist/types.d.ts

@@ -50,6 +50,30 @@ export type Severity = 'error' | 'warning';
 export type RuleConfig = RuleState | readonly [RuleState, unknown];
 /** The parsed contents of a `.gurkencheckrc` file. */
 export type Configuration = Record<string, RuleConfig>;
+/**
+ * Somewhere for a rule to keep what it learns as a run goes on.
+ *
+ * A rule looking for duplicates has to remember what it has already seen.
+ * Keeping that in the module makes it process-global, so two runs at once - a
+ * language server checking two folders, a test suite running cases side by
+ * side - quietly corrupt each other's state. A context belongs to one rule in
+ * one run, so there is nothing shared and nothing to reset.
+ */
+export interface RunContext {
+    /** This rule's state for this run, made the first time it is asked for. */
+    state<T>(create: () => T): T;
+}
+/**
+ * A finding that could only be worked out once every file had been seen, so
+ * it has to say which file it is about.
+ */
+export interface RunFinding extends RuleError {
+    /**
+     * The file this is about, as it was given to the linter. Left out for a
+     * finding about the run as a whole rather than about any one file.
+     */
+    filePath?: string;
+}
 /**
  * A lint rule.
  *
@@ -68,11 +92,31 @@ export interface LintRule {
     /**
      * Returns the violations found in this file. A rule that needs to wait for
      * something - reading a file, asking a service - may return a promise.
+     *
+     * `context` is the same object for every file of a run, and a different one
+     * for every other run, so it is where anything remembered between files
+     * belongs.
+     */
+    run(feature: Feature | undefined, file: FeatureFile, configuration: unknown, context: RunContext): RuleError[] | Promise<RuleError[]>;
+    /**
+     * Called once before the first file, for a rule with something to set up.
+     * Rules that only accumulate as they go need nothing here: the context
+     * makes their state the first time they ask for it.
+     */
+    onRunStart?(configuration: unknown, context: RunContext): void;
+    /**
+     * The findings that could only be worked out once every file had been seen,
+     * such as two files sharing a name. Called once after the last file, and
+     * only for a rule the configuration switched on.
      */
-    run(feature: Feature | undefined, file: FeatureFile, configuration: unknown): RuleError[] | Promise<RuleError[]>;
+    onRunEnd?(configuration: unknown, context: RunContext): RunFinding[] | Promise<RunFinding[]>;
     /**
-     * Clears any state kept between files. Implemented by the rules that look
-     * for duplicates across a whole run; called once before each lint run.
+     * Clears any state kept between files.
+     *
+     * @deprecated Keep state in the `RunContext` handed to `run` instead. State
+     * in the module is shared by every run in the process, so two at once tread
+     * on each other. Still called before each run, for rules written before
+     * contexts existed.
      */
     reset?(): void;
 }

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,oBAAoB,CAAC;AAEhD,6CAA6C;AAC7C,MAAM,WAAW,WAAW;IAC1B,4EAA4E;IAC5E,YAAY,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,+BAA+B;AAC/B,MAAM,WAAW,SAAS;IACxB,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED,4CAA4C;AAC5C,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,SAAS,EAAE,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,KAAK,CAAC;AAE9C,kCAAkC;AAClC,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;AAE3C;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;AAEnE,sDAAsD;AACtD,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAEvD;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IACpC;;;OAGG;IACH,GAAG,CACD,OAAO,EAAE,OAAO,GAAG,SAAS,EAC5B,IAAI,EAAE,WAAW,EACjB,aAAa,EAAE,OAAO,GACrB,SAAS,EAAE,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IACtC;;;OAGG;IACH,KAAK,CAAC,IAAI,IAAI,CAAC;CAChB;AAED,mDAAmD;AACnD,MAAM,MAAM,YAAY,GAAG,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,oBAAoB,CAAC;AAEhD,6CAA6C;AAC7C,MAAM,WAAW,WAAW;IAC1B,4EAA4E;IAC5E,YAAY,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,+BAA+B;AAC/B,MAAM,WAAW,SAAS;IACxB,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED,4CAA4C;AAC5C,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,SAAS,EAAE,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,KAAK,CAAC;AAE9C,kCAAkC;AAClC,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;AAE3C;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;AAEnE,sDAAsD;AACtD,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAEvD;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACzB,2EAA2E;IAC3E,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,UAAW,SAAQ,SAAS;IAC3C;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IACpC;;;;;;;OAOG;IACH,GAAG,CACD,OAAO,EAAE,OAAO,GAAG,SAAS,EAC5B,IAAI,EAAE,WAAW,EACjB,aAAa,EAAE,OAAO,EACtB,OAAO,EAAE,UAAU,GAClB,SAAS,EAAE,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IACtC;;;;OAIG;IACH,UAAU,CAAC,CAAC,aAAa,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,GAAG,IAAI,CAAC;IAC/D;;;;OAIG;IACH,QAAQ,CAAC,CACP,aAAa,EAAE,OAAO,EACtB,OAAO,EAAE,UAAU,GAClB,UAAU,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IACxC;;;;;;;OAOG;IACH,KAAK,CAAC,IAAI,IAAI,CAAC;CAChB;AAED,mDAAmD;AACnD,MAAM,MAAM,YAAY,GAAG,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC"}

package/dist/util/glob.d.ts

@@ -3,6 +3,12 @@
  * slash-separated paths.
  */
 export declare function globToRegExp(pattern: string): RegExp;
+/**
+ * The directory a pattern's search starts from - the leading run of literal
+ * segments, resolved against `cwd`. What you would watch to be told about
+ * anything the pattern could match.
+ */
+export declare function globRoot(pattern: string, cwd?: string): string;
 export interface GlobOptions {
     /** Directory that relative patterns and returned paths are relative to. */
     cwd?: string;
@@ -17,4 +23,16 @@ export interface GlobOptions {
  * forward slashes. Directories are never returned. Results are sorted.
  */
 export declare function globSync(pattern: string, options?: GlobOptions): string[];
+/**
+ * The same search, handing each match over as it is found.
+ *
+ * Collecting a whole tree before anything else starts is time in which
+ * nothing is read, parsed or checked. This hands each match over as it is
+ * reached, so the work after it starts on the first file rather than on the
+ * last.
+ *
+ * The order is the order `globSync` returns, without anything being collected
+ * to sort: `byPathOrder` is what makes the two agree.
+ */
+export declare function globStream(pattern: string, options?: GlobOptions): AsyncGenerator<string>;
 //# sourceMappingURL=glob.d.ts.map

package/dist/util/glob.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"glob.d.ts","sourceRoot":"","sources":["../../src/util/glob.ts"],"names":[],"mappings":"AAeA;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CA8DpD;AA0DD,MAAM,WAAW,WAAW;IAC1B,2EAA2E;IAC3E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B;AAyBD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,MAAM,EAAE,CAmC7E"}
+{"version":3,"file":"glob.d.ts","sourceRoot":"","sources":["../../src/util/glob.ts"],"names":[],"mappings":"AAeA;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CA8DpD;AAgCD;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,GAAE,MAAsB,GAAG,MAAM,CAE7E;AAsFD,MAAM,WAAW,WAAW;IAC1B,2EAA2E;IAC3E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B;AA0DD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,MAAM,EAAE,CAsB7E;AAED;;;;;;;;;;GAUG;AACH,wBAAuB,UAAU,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,WAAgB,GACxB,cAAc,CAAC,MAAM,CAAC,CAsBxB"}

package/dist/util/glob.js

@@ -109,19 +109,44 @@ function staticPrefix(pattern) {
     }
     return literal.join('/');
 }
+/**
+ * The directory a pattern's search starts from - the leading run of literal
+ * segments, resolved against `cwd`. What you would watch to be told about
+ * anything the pattern could match.
+ */
+export function globRoot(pattern, cwd = process.cwd()) {
+    return path.resolve(cwd, staticPrefix(pattern.split(path.sep).join('/')));
+}
 function isHidden(name) {
     return name.startsWith('.');
 }
-function walk(directory, onFile) {
-    let entries;
+/**
+ * Orders the entries of a directory so that walking depth-first reaches files
+ * in the same order that sorting the finished paths would.
+ *
+ * Everything inside a directory `d` has a path starting `d/`, so `d` has to
+ * be ordered as `d/` rather than as `d`. Otherwise a sibling file called
+ * `d-1.feature` comes after the directory here and before it in a sorted
+ * list, because `-` sorts before `/` - and a walk that hands files over as it
+ * finds them would quietly report them in a different order from one that
+ * collects and sorts.
+ */
+function byPathOrder(a, b) {
+    const left = a.isDirectory() ? `${a.name}/` : a.name;
+    const right = b.isDirectory() ? `${b.name}/` : b.name;
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function readEntries(directory) {
     try {
-        entries = fs.readdirSync(directory, { withFileTypes: true });
+        return fs.readdirSync(directory, { withFileTypes: true }).sort(byPathOrder);
     }
     catch {
         // A missing or unreadable directory simply contributes no matches.
-        return;
+        return [];
     }
-    for (const entry of entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
+}
+function walk(directory, onFile) {
+    for (const entry of readEntries(directory)) {
         if (isHidden(entry.name)) {
             continue;
         }
@@ -134,6 +159,43 @@ function walk(directory, onFile) {
         }
     }
 }
+/**
+ * The same walk, handing each file over as it is reached.
+ *
+ * Each directory is still read synchronously. `fs.promises.readdir` was tried
+ * and is about 40% slower over a tree of a couple of thousand directories -
+ * a promise for each directory costs more than reading it does - and it
+ * bought nothing, because the only thing waiting on this walk is the work
+ * being fed by it. What matters is that the walk is no longer one long block:
+ * it gives way at every file, and the reading and checking downstream happen
+ * in the gaps.
+ */
+async function* walkStream(root) {
+    // An explicit stack rather than recursion: a recursive async generator
+    // delegates through one `yield*` per level of nesting for every file it
+    // hands over, so a deep tree pays for its depth on every single file.
+    const stack = [{ directory: root, entries: readEntries(root), index: 0 }];
+    while (stack.length > 0) {
+        const top = stack[stack.length - 1];
+        if (top.index >= top.entries.length) {
+            stack.pop();
+            continue;
+        }
+        const entry = top.entries[top.index++];
+        if (isHidden(entry.name)) {
+            continue;
+        }
+        const absolutePath = path.join(top.directory, entry.name);
+        if (entry.isDirectory()) {
+            // Pushed so that its contents come before the entries after it here,
+            // which is what a depth-first walk means.
+            stack.push({ directory: absolutePath, entries: readEntries(absolutePath), index: 0 });
+        }
+        else if (entry.isFile()) {
+            yield absolutePath;
+        }
+    }
+}
 /**
  * True when the path, or any directory leading to it, matches one of the
  * patterns.
@@ -156,42 +218,84 @@ function isIgnored(relativePath, ignores) {
     }
     return false;
 }
-/**
- * Returns the files matching `pattern`, as paths relative to `cwd` using
- * forward slashes. Directories are never returned. Results are sorted.
- */
-export function globSync(pattern, options = {}) {
+function newSearch(pattern, options) {
     const cwd = options.cwd ?? process.cwd();
     const normalisedPattern = pattern.split(path.sep).join('/');
     const matches = globToRegExp(normalisedPattern);
     const ignores = (options.ignore ?? []).map((ignorePattern) => globToRegExp(ignorePattern.split(path.sep).join('/')));
-    const searchRoot = path.resolve(cwd, staticPrefix(normalisedPattern));
-    const found = [];
     // An absolute pattern is matched against absolute paths: comparing it with
     // a path relative to cwd can never match, and the search would come back
     // empty rather than wrong, which reads as "nothing to report".
     const absolutePattern = path.isAbsolute(normalisedPattern);
+    return {
+        searchRoot: path.resolve(cwd, staticPrefix(normalisedPattern)),
+        match(absolutePath) {
+            const relativePath = path.relative(cwd, absolutePath).split(path.sep).join('/');
+            const candidate = absolutePattern ? absolutePath.split(path.sep).join('/') : relativePath;
+            if (!matches.test(candidate))
+                return undefined;
+            if (isIgnored(relativePath, ignores))
+                return undefined;
+            return relativePath;
+        },
+    };
+}
+/**
+ * Returns the files matching `pattern`, as paths relative to `cwd` using
+ * forward slashes. Directories are never returned. Results are sorted.
+ */
+export function globSync(pattern, options = {}) {
+    const search = newSearch(pattern, options);
+    const found = [];
     const consider = (absolutePath) => {
-        const relativePath = path.relative(cwd, absolutePath).split(path.sep).join('/');
-        const candidate = absolutePattern ? absolutePath.split(path.sep).join('/') : relativePath;
-        if (!matches.test(candidate))
-            return;
-        if (isIgnored(relativePath, ignores))
-            return;
-        found.push(relativePath);
+        const relativePath = search.match(absolutePath);
+        if (relativePath !== undefined) {
+            found.push(relativePath);
+        }
     };
-    const stats = statOrUndefined(searchRoot);
+    const stats = statOrUndefined(search.searchRoot);
     if (stats === undefined) {
         return [];
     }
     if (stats.isFile()) {
-        consider(searchRoot);
+        consider(search.searchRoot);
     }
     else {
-        walk(searchRoot, consider);
+        walk(search.searchRoot, consider);
     }
     return found.sort();
 }
+/**
+ * The same search, handing each match over as it is found.
+ *
+ * Collecting a whole tree before anything else starts is time in which
+ * nothing is read, parsed or checked. This hands each match over as it is
+ * reached, so the work after it starts on the first file rather than on the
+ * last.
+ *
+ * The order is the order `globSync` returns, without anything being collected
+ * to sort: `byPathOrder` is what makes the two agree.
+ */
+export async function* globStream(pattern, options = {}) {
+    const search = newSearch(pattern, options);
+    const stats = statOrUndefined(search.searchRoot);
+    if (stats === undefined) {
+        return;
+    }
+    if (stats.isFile()) {
+        const relativePath = search.match(search.searchRoot);
+        if (relativePath !== undefined) {
+            yield relativePath;
+        }
+        return;
+    }
+    for await (const absolutePath of walkStream(search.searchRoot)) {
+        const relativePath = search.match(absolutePath);
+        if (relativePath !== undefined) {
+            yield relativePath;
+        }
+    }
+}
 function statOrUndefined(target) {
     try {
         return fs.statSync(target);