@smthrs/std 0.0.0-stage → 1.0.0-rc.4

package/dist/esm/SearchContract.d.ts

@@ -0,0 +1,114 @@
+/**
+ * The validation and matching rules every Search implementation shares.
+ *
+ * Both peers shipped here match globs through {@link includedByGlobs} and
+ * canonicalize them through {@link canonicalGlob}, so the two implementations
+ * cannot drift on what a pattern means, and an external peer binding its own
+ * `Search` builds on the same functions. {@link unsatisfiableNotice} is the
+ * shared explanation for empty answers caused by impossible globs or ignore
+ * exclusions.
+ *
+ * @since 1.0.0
+ */
+import type * as Path from "@smthrs/kernel/Path";
+import { Effect } from "effect";
+import type * as FileSystem from "effect/FileSystem";
+import type * as StdError from "./StdError.ts";
+/**
+ * Validates Smithers Ripgrep ASCII v1. It is deliberately the intersection of
+ * Rust regex and JavaScript RegExp: ASCII patterns, captures, alternation,
+ * ASCII character classes and ordinary quantifiers. Lookaround,
+ * backreferences, named/inline groups, Unicode/shorthand classes and control
+ * escapes are rejected before either implementation runs. Patterns are
+ * limited to 4096 bytes, counted repetitions to 1000, group nesting to 128
+ * and expanded state machines to 8192 states. Both peers share this
+ * compilation boundary; portable matching never backtracks over input.
+ *
+ * @category validation
+ * @since 1.0.0
+ */
+export declare const validatePattern: (pattern: string, fixedStrings: boolean) => StdError.StdError | undefined;
+/**
+ * Whether `error` is a pattern or glob rejection this contract wrote.
+ *
+ * Those messages are host-authored and name the construct that broke, so a
+ * caller may show them to a model. A peer's `invalid_pattern` built from
+ * `rg`'s stderr is not one of them and stays private.
+ *
+ * @category validation
+ * @since 1.0.0
+ */
+export declare const isContractRejection: (error: StdError.StdError) => boolean;
+/**
+ * Validates the portable `-g` grammar before either peer sees it.
+ *
+ * @category validation
+ * @since 1.0.0
+ */
+export declare const validateGlob: (glob: string) => StdError.StdError | undefined;
+/**
+ * Compiles a pattern after common validation.
+ *
+ * @category matching
+ * @since 1.0.0
+ */
+export declare const expression: (pattern: string, fixedStrings: boolean, insensitive: boolean) => RegExp;
+/**
+ * Rewrites a glob into the one spelling both peers match against.
+ *
+ * `.` is never a path component either peer can produce, so a leading `./` and
+ * every interior `/./` would silently make a pattern unmatchable. Both are
+ * folded into the root anchor, which is what a caller writing `./src/**` means.
+ * Trailing spaces are dropped because `rg` reads `-g` by gitignore's rules and
+ * drops them too, so `"a.ts "` finds `a.ts` in the native peer and has to find
+ * it in the in-process one. A leading `!` is preserved so exclusion globs
+ * canonicalize the same way.
+ *
+ * @category matching
+ * @since 1.0.0
+ */
+export declare const canonicalGlob: (glob: string) => string;
+/**
+ * Matches the supported `-g` subset against a root-relative candidate path.
+ *
+ * A pattern without `/` matches the basename at any depth. Every other pattern
+ * is matched against the candidate's path relative to the search root, anchored
+ * at the root, whether or not it carries the optional leading `/`.
+ *
+ * @category matching
+ * @since 1.0.0
+ */
+export declare const matchesGlob: (pattern: string, relative: string, basename: string) => boolean;
+/**
+ * Applies ripgrep `-g` ordering: positive globs include and `!` globs exclude.
+ *
+ * @category matching
+ * @since 1.0.0
+ */
+export declare const includedByGlobs: (globs: ReadonlyArray<string>, relative: string, basename: string) => boolean;
+/**
+ * Explains the positive globs that no file under the root could ever match.
+ *
+ * A search that returns nothing is ambiguous: the tree may hold no match, or
+ * the pattern may be unsatisfiable — an absolute path written where a
+ * root-relative one belongs, a directory that does not exist, a skipped
+ * directory, a hidden path with `hidden` left false. Callers attach the result
+ * to `notice` when they produced no entries. Ignore exclusions name the
+ * `noIgnore: true` escape hatch, while impossible globs explain the correction.
+ * This keeps the cases
+ * distinguishable. Exclusion globs are ignored: excluding what is not there
+ * changes nothing.
+ *
+ * @category diagnostics
+ * @since 1.0.0
+ */
+export declare const unsatisfiableNotice: (options: {
+    readonly fileSystem: FileSystem.FileSystem;
+    readonly path: Path.Path;
+    readonly root: string;
+    readonly globs: ReadonlyArray<string>;
+    readonly noIgnore?: boolean | undefined;
+    readonly ignored?: boolean | undefined;
+    readonly hidden: boolean;
+}) => Effect.Effect<string | undefined>;
+//# sourceMappingURL=SearchContract.d.ts.map

package/dist/esm/SearchContract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SearchContract.d.ts","sourceRoot":"","sources":["../../src/SearchContract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,KAAK,IAAI,MAAM,qBAAqB,CAAA;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAC/B,OAAO,KAAK,KAAK,UAAU,MAAM,mBAAmB,CAAA;AAIpD,OAAO,KAAK,KAAK,QAAQ,MAAM,eAAe,CAAA;AAE9C;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,eAAe,GAAI,SAAS,MAAM,EAAE,cAAc,OAAO,KAAG,QAAQ,CAAC,QAAQ,GAAG,SAiE5F,CAAA;AAwED;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,GAAI,OAAO,QAAQ,CAAC,QAAQ,KAAG,OACsB,CAAA;AAErF;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,KAAG,QAAQ,CAAC,QAAQ,GAAG,SA8B/D,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,SAAS,MAAM,EAAE,cAAc,OAAO,EAAE,aAAa,OAAO,KAAG,MAwBzF,CAAA;AA4CD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,MAAM,KAAG,MAK5C,CAAA;AA+BD;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,GAAI,SAAS,MAAM,EAAE,UAAU,MAAM,EAAE,UAAU,MAAM,KAAG,OACqC,CAAA;AAEvH;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,aAAa,CAAC,MAAM,CAAC,EAAE,UAAU,MAAM,EAAE,UAAU,MAAM,KAAG,OAQlG,CAAA;AAoDD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,mBAAmB,GAAI,SAAS;IAC3C,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC,UAAU,CAAA;IAC1C,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACtC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CACzB,KAAG,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,SAAS,CAuChC,CAAA"}

package/dist/esm/SearchContract.js

@@ -0,0 +1,461 @@
+/**
+ * The validation and matching rules every Search implementation shares.
+ *
+ * Both peers shipped here match globs through {@link includedByGlobs} and
+ * canonicalize them through {@link canonicalGlob}, so the two implementations
+ * cannot drift on what a pattern means, and an external peer binding its own
+ * `Search` builds on the same functions. {@link unsatisfiableNotice} is the
+ * shared explanation for empty answers caused by impossible globs or ignore
+ * exclusions.
+ *
+ * @since 1.0.0
+ */
+import { Effect } from "effect";
+import * as LinearRegex from "./internal/LinearRegex.js";
+import { escapeRegex, invalidPattern, rejectionPrefix } from "./internal/SearchContract.js";
+import * as Walk from "./internal/Walk.js";
+/**
+ * Validates Smithers Ripgrep ASCII v1. It is deliberately the intersection of
+ * Rust regex and JavaScript RegExp: ASCII patterns, captures, alternation,
+ * ASCII character classes and ordinary quantifiers. Lookaround,
+ * backreferences, named/inline groups, Unicode/shorthand classes and control
+ * escapes are rejected before either implementation runs. Patterns are
+ * limited to 4096 bytes, counted repetitions to 1000, group nesting to 128
+ * and expanded state machines to 8192 states. Both peers share this
+ * compilation boundary; portable matching never backtracks over input.
+ *
+ * @category validation
+ * @since 1.0.0
+ */
+export const validatePattern = (pattern, fixedStrings) => {
+    if (pattern.length > 4096)
+        return invalidPattern(pattern, "patterns must not exceed 4096 bytes");
+    if (!/^[\x20-\x7e]*$/.test(pattern))
+        return invalidPattern(pattern, "patterns must contain printable ASCII only");
+    if (fixedStrings)
+        return undefined;
+    if (pattern.includes("(?"))
+        return invalidPattern(pattern, "special groups and lookaround are not supported");
+    let inClass = false;
+    let classCharacters = 0;
+    for (let index = 0; index < pattern.length; index++) {
+        const character = pattern[index];
+        if (character === "\\") {
+            const escaped = pattern[index + 1];
+            if (escaped === undefined || /[A-Za-z0-9]/.test(escaped)) {
+                return invalidPattern(pattern, "backreferences, shorthand classes and encoded escapes are not supported");
+            }
+            index++;
+            if (inClass)
+                classCharacters++;
+            continue;
+        }
+        if (character === "[" && inClass) {
+            return invalidPattern(pattern, "nested and named character classes are not supported");
+        }
+        if (character === "[") {
+            inClass = true;
+            classCharacters = 0;
+            continue;
+        }
+        if (character === "{" && !inClass) {
+            const closing = pattern.indexOf("}", index + 1);
+            if (closing >= 0) {
+                const counts = pattern.slice(index + 1, closing).split(",").filter((value) => value.length > 0);
+                if (counts.some((value) => /^\d+$/.test(value) && Number(value) > 1000)) {
+                    return invalidPattern(pattern, "repetition counts above 1000 are not supported");
+                }
+            }
+        }
+        if (character === "]" && inClass) {
+            if (classCharacters === 0 || (classCharacters === 1 && pattern[index - 1] === "^")) {
+                return invalidPattern(pattern, "empty character classes are not supported");
+            }
+            inClass = false;
+            continue;
+        }
+        if (inClass) {
+            if ((character === "&" && pattern[index + 1] === "&") ||
+                (character === "-" && pattern[index + 1] === "-") ||
+                (character === "~" && pattern[index + 1] === "~")) {
+                return invalidPattern(pattern, "character-class set operations are not supported");
+            }
+            classCharacters++;
+        }
+    }
+    try {
+        new RegExp(pattern, "u");
+    }
+    catch (error) {
+        return invalidPattern(pattern, malformed(pattern) ?? engineReason(error));
+    }
+    try {
+        LinearRegex.compile(pattern, false);
+        return undefined;
+    }
+    catch (error) {
+        // LinearRegex.compile throws Error for its nesting and state budgets.
+        return invalidPattern(pattern, error.message);
+    }
+};
+const countedRepetition = /^\{\d+(,\d*)?\}/;
+/**
+ * Names the first construct that keeps `pattern` from parsing, with its
+ * 1-based column and the escape that makes it literal.
+ *
+ * A caller told only that a pattern is unsupported guesses at which character
+ * broke it; `Rule({` reads as a literal search to its author and as an unclosed
+ * group plus a count with no digits to the parser. Only the syntax errors a
+ * search author commonly makes are named here; anything else falls back to the
+ * engine's own reason.
+ */
+const malformed = (pattern) => {
+    const open = [];
+    let repeatable = false;
+    for (let index = 0; index < pattern.length; index++) {
+        const character = pattern[index];
+        const at = `"${character}" at column ${index + 1}`;
+        if (character === "\\") {
+            index++;
+            repeatable = true;
+            continue;
+        }
+        if (character === "[") {
+            let end = index + 1;
+            if (pattern[end] === "^")
+                end++;
+            while (end < pattern.length && pattern[end] !== "]")
+                end += pattern[end] === "\\" ? 2 : 1;
+            if (end >= pattern.length)
+                return `${at} is never closed; write \\[ for a literal bracket`;
+            index = end;
+            repeatable = true;
+            continue;
+        }
+        if (character === "(") {
+            open.push(index);
+            repeatable = false;
+            continue;
+        }
+        if (character === ")") {
+            if (open.pop() === undefined)
+                return `${at} closes nothing; write \\) for a literal parenthesis`;
+            repeatable = true;
+            continue;
+        }
+        if (character === "{") {
+            const count = countedRepetition.exec(pattern.slice(index));
+            if (count === null)
+                return `${at} is not a repetition count; write \\{ for a literal brace`;
+            if (!repeatable)
+                return `${at} repeats nothing; write \\{ for a literal brace`;
+            index += count[0].length - 1;
+            continue;
+        }
+        if (character === "}" || character === "]") {
+            return `${at} closes nothing; write \\${character} for a literal ${character === "}" ? "brace" : "bracket"}`;
+        }
+        if (character === "*" || character === "+" || character === "?") {
+            if (!repeatable)
+                return `${at} repeats nothing; write \\${character} for a literal ${character}`;
+            continue;
+        }
+        repeatable = character !== "|" && character !== "^" && character !== "$";
+    }
+    const unclosed = open.at(-1);
+    return unclosed === undefined
+        ? undefined
+        : `"(" at column ${unclosed + 1} is never closed; write \\( for a literal parenthesis`;
+};
+/** The JavaScript engine's reason, without its prefix or its echo of the pattern. */
+const engineReason = (error) => {
+    const reason = error.message.replace(/^Invalid regular expression: (\/.*\/[a-z]*: )?/, "").trim();
+    return `invalid expression: ${reason}`;
+};
+/**
+ * Whether `error` is a pattern or glob rejection this contract wrote.
+ *
+ * Those messages are host-authored and name the construct that broke, so a
+ * caller may show them to a model. A peer's `invalid_pattern` built from
+ * `rg`'s stderr is not one of them and stays private.
+ *
+ * @category validation
+ * @since 1.0.0
+ */
+export const isContractRejection = (error) => error.code === "invalid_pattern" && error.message.startsWith(`${rejectionPrefix}"`);
+/**
+ * Validates the portable `-g` grammar before either peer sees it.
+ *
+ * @category validation
+ * @since 1.0.0
+ */
+export const validateGlob = (glob) => {
+    const pattern = glob.startsWith("!") ? glob.slice(1) : glob;
+    // `rg` drops the trailing spaces and then ignores a glob that is left blank,
+    // which filters nothing at all. Rejecting it keeps a typo from silently
+    // widening the search instead of narrowing it.
+    if (pattern.replace(/ +$/, "").length === 0)
+        return invalidPattern(glob, "glob patterns must not be empty");
+    if (!/^[\x20-\x7e]*$/.test(pattern))
+        return invalidPattern(glob, "globs must contain printable ASCII only");
+    if (pattern.includes("\\") || pattern.includes("[") || pattern.includes("]")) {
+        return invalidPattern(glob, "glob escapes and character classes are not supported");
+    }
+    let inBrace = false;
+    let alternatives = 1;
+    let expansionCount = 1;
+    for (let index = 0; index < pattern.length; index++) {
+        const character = pattern[index];
+        if (character === "{") {
+            if (inBrace)
+                return invalidPattern(glob, "nested brace alternatives are not supported");
+            inBrace = true;
+            alternatives = 1;
+        }
+        else if (character === "," && inBrace) {
+            alternatives++;
+        }
+        else if (character === "}") {
+            if (!inBrace || alternatives < 2)
+                return invalidPattern(glob, "braces must contain alternatives");
+            inBrace = false;
+            expansionCount *= alternatives;
+            if (expansionCount > 256)
+                return invalidPattern(glob, "glob brace expansion exceeds 256 patterns");
+        }
+    }
+    if (inBrace)
+        return invalidPattern(glob, "glob braces must be balanced");
+    return undefined;
+};
+/**
+ * Compiles a pattern after common validation.
+ *
+ * @category matching
+ * @since 1.0.0
+ */
+export const expression = (pattern, fixedStrings, insensitive) => {
+    const input = fixedStrings ? escapeRegex(pattern) : pattern;
+    let source = "";
+    let inClass = false;
+    for (let index = 0; index < input.length; index++) {
+        const character = input[index];
+        if (character === "\\") {
+            source += `${character}${input[index + 1] ?? ""}`;
+            index++;
+        }
+        else if (character === "[") {
+            inClass = true;
+            source += character;
+        }
+        else if (character === "]" && inClass) {
+            inClass = false;
+            source += character;
+        }
+        else if (!inClass && character === ".") {
+            source += "[^\\n]";
+        }
+        else if (!inClass && character === "$") {
+            source += "(?![\\s\\S])";
+        }
+        else {
+            source += character;
+        }
+    }
+    return new RegExp(source, insensitive ? "iu" : "u");
+};
+const expandBraces = (pattern) => {
+    const opening = pattern.indexOf("{");
+    if (opening < 0)
+        return [pattern];
+    const closing = pattern.indexOf("}", opening + 1);
+    if (closing < 0)
+        return [pattern];
+    const alternatives = pattern.slice(opening + 1, closing).split(",");
+    if (alternatives.length < 2)
+        return [pattern];
+    return alternatives.flatMap((alternative) => expandBraces(`${pattern.slice(0, opening)}${alternative}${pattern.slice(closing + 1)}`));
+};
+const globExpression = (pattern) => {
+    let source = "";
+    for (let index = 0; index < pattern.length; index++) {
+        const character = pattern[index];
+        const next = pattern[index + 1];
+        if (character === "*" && next === "*" &&
+            (index === 0 || pattern[index - 1] === "/") &&
+            (pattern[index + 2] === undefined || pattern[index + 2] === "/")) {
+            source += pattern[index + 2] === "/" ? "(?:.*/)?" : ".*";
+            index += pattern[index + 2] === "/" ? 2 : 1;
+        }
+        else if (character === "*")
+            source += "[^/]*";
+        else if (character === "?")
+            source += "[^/]";
+        else
+            source += character.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&");
+    }
+    return new RegExp(`^${source}$`);
+};
+const outsidePrintableAscii = /[^\x20-\x7e]/;
+// Printable ASCII is its own UTF-8 encoding, and paths are overwhelmingly
+// printable ASCII, so the encoder only runs for the paths that need it.
+const utf8ByteString = (value) => outsidePrintableAscii.test(value)
+    ? Array.from(new TextEncoder().encode(value), (byte) => String.fromCharCode(byte)).join("")
+    : value;
+/**
+ * Rewrites a glob into the one spelling both peers match against.
+ *
+ * `.` is never a path component either peer can produce, so a leading `./` and
+ * every interior `/./` would silently make a pattern unmatchable. Both are
+ * folded into the root anchor, which is what a caller writing `./src/**` means.
+ * Trailing spaces are dropped because `rg` reads `-g` by gitignore's rules and
+ * drops them too, so `"a.ts "` finds `a.ts` in the native peer and has to find
+ * it in the in-process one. A leading `!` is preserved so exclusion globs
+ * canonicalize the same way.
+ *
+ * @category matching
+ * @since 1.0.0
+ */
+export const canonicalGlob = (glob) => {
+    const excluded = glob.startsWith("!");
+    const pattern = excluded ? glob.slice(1) : glob;
+    const canonical = pattern.replace(/ +$/, "").replace(/\/\.(?=\/)/g, "").replace(/^\.\//, "/");
+    return excluded ? `!${canonical}` : canonical;
+};
+const compiled = new Map();
+/**
+ * Compiles one glob into its alternatives, once per distinct pattern.
+ *
+ * The in-process peer asks whether a pattern matches for every candidate file
+ * in the walk, so canonicalizing, brace expanding and compiling the pattern
+ * inside that loop makes the work quadratic in the tree. A pattern compiles to
+ * the same matchers every time, so the compilation is cached; the cache is
+ * bounded because callers, not the tree, supply the patterns.
+ */
+const compileGlob = (pattern) => {
+    const cached = compiled.get(pattern);
+    if (cached !== undefined)
+        return cached;
+    const matchers = expandBraces(canonicalGlob(pattern)).map((expanded) => {
+        const rooted = expanded.startsWith("/");
+        const normalized = rooted ? expanded.slice(1) : expanded;
+        return { byPath: rooted || normalized.includes("/"), expression: globExpression(normalized) };
+    });
+    if (compiled.size >= 256)
+        compiled.clear();
+    compiled.set(pattern, matchers);
+    return matchers;
+};
+/**
+ * Matches the supported `-g` subset against a root-relative candidate path.
+ *
+ * A pattern without `/` matches the basename at any depth. Every other pattern
+ * is matched against the candidate's path relative to the search root, anchored
+ * at the root, whether or not it carries the optional leading `/`.
+ *
+ * @category matching
+ * @since 1.0.0
+ */
+export const matchesGlob = (pattern, relative, basename) => compileGlob(pattern).some((matcher) => matcher.expression.test(utf8ByteString(matcher.byPath ? relative : basename)));
+/**
+ * Applies ripgrep `-g` ordering: positive globs include and `!` globs exclude.
+ *
+ * @category matching
+ * @since 1.0.0
+ */
+export const includedByGlobs = (globs, relative, basename) => {
+    const positives = globs.filter((glob) => !glob.startsWith("!"));
+    let included = positives.length === 0;
+    for (const glob of globs) {
+        const excluded = glob.startsWith("!");
+        if (matchesGlob(excluded ? glob.slice(1) : glob, relative, basename))
+            included = !excluded;
+    }
+    return included;
+};
+const wildcard = /[*?{}]/;
+const literalDirectory = (pattern) => {
+    if (!pattern.includes("/"))
+        return [];
+    const segments = pattern.replace(/^\//, "").split("/").filter((segment) => segment.length > 0);
+    const wildcardAt = segments.findIndex((segment) => wildcard.test(segment));
+    return wildcardAt < 0 ? segments.slice(0, -1) : segments.slice(0, wildcardAt);
+};
+const rootRelativeSuffix = (pattern, root, path) => {
+    const anchored = pattern.replace(/^\/+/, "");
+    const patternRoot = path.sep === "\\" ? root.replaceAll("\\", "/") : root;
+    const stem = patternRoot.replace(/^\/+/, "").replace(/\/+$/, "");
+    return stem.length > 0 && anchored.startsWith(`${stem}/`) ? anchored.slice(stem.length + 1) : undefined;
+};
+const unsatisfiedReason = (options, pattern) => Effect.gen(function* () {
+    const reasons = [];
+    for (const alternative of expandBraces(pattern)) {
+        const segments = literalDirectory(alternative);
+        if (segments.length === 0)
+            return undefined;
+        const skipped = segments.find((segment) => Walk.skippedDirectories.has(segment));
+        if (skipped !== undefined) {
+            reasons.push(`${skipped} is never descended into; name it as the search root to look inside it`);
+            continue;
+        }
+        if (!options.hidden && segments.some((segment) => segment.startsWith("."))) {
+            reasons.push("hidden paths are excluded unless hidden is true");
+            continue;
+        }
+        const directory = segments.join("/");
+        const present = yield* options.fileSystem.stat(options.path.join(options.root, directory)).pipe(Effect.map((info) => info.type === "Directory"), Effect.orElseSucceed(() => false));
+        if (present)
+            return undefined;
+        reasons.push(`there is no ${directory} directory there`);
+    }
+    return reasons[0];
+});
+/**
+ * Explains the positive globs that no file under the root could ever match.
+ *
+ * A search that returns nothing is ambiguous: the tree may hold no match, or
+ * the pattern may be unsatisfiable — an absolute path written where a
+ * root-relative one belongs, a directory that does not exist, a skipped
+ * directory, a hidden path with `hidden` left false. Callers attach the result
+ * to `notice` when they produced no entries. Ignore exclusions name the
+ * `noIgnore: true` escape hatch, while impossible globs explain the correction.
+ * This keeps the cases
+ * distinguishable. Exclusion globs are ignored: excluding what is not there
+ * changes nothing.
+ *
+ * @category diagnostics
+ * @since 1.0.0
+ */
+export const unsatisfiableNotice = (options) => Effect.gen(function* () {
+    // Globs filter a walk. A root that names one file is searched whatever the
+    // globs say — `rg` always searches a path given on the command line — so
+    // there is no unsatisfiable pattern to report and no directory to stat.
+    const walkable = yield* options.fileSystem.stat(options.root).pipe(Effect.map((info) => info.type === "Directory"), Effect.orElseSucceed(() => false));
+    if (!walkable)
+        return undefined;
+    const sentences = [];
+    for (const glob of options.globs) {
+        if (glob.startsWith("!"))
+            continue;
+        const canonical = canonicalGlob(glob);
+        const reason = yield* unsatisfiedReason(options, canonical);
+        if (reason === undefined)
+            continue;
+        const suffix = rootRelativeSuffix(canonical, options.root, options.path);
+        sentences.push(`No file under ${options.root} can match "${glob}": ${suffix === undefined
+            ? reason
+            : `glob patterns are relative to the search root, so use "${suffix}" instead`}.`);
+    }
+    // An impossible glob cannot be repaired by opting out of ignores.
+    if (sentences.length > 0 && sentences.length === options.globs.filter((glob) => !glob.startsWith("!")).length) {
+        return sentences.join(" ");
+    }
+    const included = (relative, basename) => includedByGlobs(options.globs, relative, basename);
+    const ignored = options.noIgnore ? false : options.ignored ??
+        (yield* Walk.files(options.fileSystem, options.path, options.root, options.hidden, false, included).pipe(Effect.map((walked) => walked.ignored), Effect.orElseSucceed(() => false)));
+    if (ignored) {
+        sentences.push("No results; ignore files excluded paths. Retry with noIgnore: true to include them.");
+    }
+    return sentences.length === 0 ? undefined : sentences.join(" ");
+});
+//# sourceMappingURL=SearchContract.js.map

package/dist/esm/SearchContract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SearchContract.js","sourceRoot":"","sources":["../../src/SearchContract.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The validation and matching rules every Search implementation shares.\n *\n * Both peers shipped here match globs through {@link includedByGlobs} and\n * canonicalize them through {@link canonicalGlob}, so the two implementations\n * cannot drift on what a pattern means, and an external peer binding its own\n * `Search` builds on the same functions. {@link unsatisfiableNotice} is the\n * shared explanation for empty answers caused by impossible globs or ignore\n * exclusions.\n *\n * @since 1.0.0\n */\n\nimport type * as Path from \"@smthrs/kernel/Path\"\nimport { Effect } from \"effect\"\nimport type * as FileSystem from \"effect/FileSystem\"\nimport * as LinearRegex from \"./internal/LinearRegex.ts\"\nimport { escapeRegex, invalidPattern, rejectionPrefix } from \"./internal/SearchContract.ts\"\nimport * as Walk from \"./internal/Walk.ts\"\nimport type * as StdError from \"./StdError.ts\"\n\n/**\n * Validates Smithers Ripgrep ASCII v1. It is deliberately the intersection of\n * Rust regex and JavaScript RegExp: ASCII patterns, captures, alternation,\n * ASCII character classes and ordinary quantifiers. Lookaround,\n * backreferences, named/inline groups, Unicode/shorthand classes and control\n * escapes are rejected before either implementation runs. Patterns are\n * limited to 4096 bytes, counted repetitions to 1000, group nesting to 128\n * and expanded state machines to 8192 states. Both peers share this\n * compilation boundary; portable matching never backtracks over input.\n *\n * @category validation\n * @since 1.0.0\n */\nexport const validatePattern = (pattern: string, fixedStrings: boolean): StdError.StdError | undefined => {\n  if (pattern.length > 4096) return invalidPattern(pattern, \"patterns must not exceed 4096 bytes\")\n  if (!/^[\\x20-\\x7e]*$/.test(pattern)) return invalidPattern(pattern, \"patterns must contain printable ASCII only\")\n  if (fixedStrings) return undefined\n  if (pattern.includes(\"(?\")) return invalidPattern(pattern, \"special groups and lookaround are not supported\")\n  let inClass = false\n  let classCharacters = 0\n  for (let index = 0; index < pattern.length; index++) {\n    const character = pattern[index]\n    if (character === \"\\\\\") {\n      const escaped = pattern[index + 1]\n      if (escaped === undefined || /[A-Za-z0-9]/.test(escaped)) {\n        return invalidPattern(pattern, \"backreferences, shorthand classes and encoded escapes are not supported\")\n      }\n      index++\n      if (inClass) classCharacters++\n      continue\n    }\n    if (character === \"[\" && inClass) {\n      return invalidPattern(pattern, \"nested and named character classes are not supported\")\n    }\n    if (character === \"[\") {\n      inClass = true\n      classCharacters = 0\n      continue\n    }\n    if (character === \"{\" && !inClass) {\n      const closing = pattern.indexOf(\"}\", index + 1)\n      if (closing >= 0) {\n        const counts = pattern.slice(index + 1, closing).split(\",\").filter((value) => value.length > 0)\n        if (counts.some((value) => /^\\d+$/.test(value) && Number(value) > 1000)) {\n          return invalidPattern(pattern, \"repetition counts above 1000 are not supported\")\n        }\n      }\n    }\n    if (character === \"]\" && inClass) {\n      if (classCharacters === 0 || (classCharacters === 1 && pattern[index - 1] === \"^\")) {\n        return invalidPattern(pattern, \"empty character classes are not supported\")\n      }\n      inClass = false\n      continue\n    }\n    if (inClass) {\n      if (\n        (character === \"&\" && pattern[index + 1] === \"&\") ||\n        (character === \"-\" && pattern[index + 1] === \"-\") ||\n        (character === \"~\" && pattern[index + 1] === \"~\")\n      ) {\n        return invalidPattern(pattern, \"character-class set operations are not supported\")\n      }\n      classCharacters++\n    }\n  }\n  try {\n    new RegExp(pattern, \"u\")\n  } catch (error) {\n    return invalidPattern(pattern, malformed(pattern) ?? engineReason(error as Error))\n  }\n  try {\n    LinearRegex.compile(pattern, false)\n    return undefined\n  } catch (error) {\n    // LinearRegex.compile throws Error for its nesting and state budgets.\n    return invalidPattern(pattern, (error as Error).message)\n  }\n}\n\nconst countedRepetition = /^\\{\\d+(,\\d*)?\\}/\n\n/**\n * Names the first construct that keeps `pattern` from parsing, with its\n * 1-based column and the escape that makes it literal.\n *\n * A caller told only that a pattern is unsupported guesses at which character\n * broke it; `Rule({` reads as a literal search to its author and as an unclosed\n * group plus a count with no digits to the parser. Only the syntax errors a\n * search author commonly makes are named here; anything else falls back to the\n * engine's own reason.\n */\nconst malformed = (pattern: string): string | undefined => {\n  const open: Array<number> = []\n  let repeatable = false\n  for (let index = 0; index < pattern.length; index++) {\n    const character = pattern[index]!\n    const at = `\"${character}\" at column ${index + 1}`\n    if (character === \"\\\\\") {\n      index++\n      repeatable = true\n      continue\n    }\n    if (character === \"[\") {\n      let end = index + 1\n      if (pattern[end] === \"^\") end++\n      while (end < pattern.length && pattern[end] !== \"]\") end += pattern[end] === \"\\\\\" ? 2 : 1\n      if (end >= pattern.length) return `${at} is never closed; write \\\\[ for a literal bracket`\n      index = end\n      repeatable = true\n      continue\n    }\n    if (character === \"(\") {\n      open.push(index)\n      repeatable = false\n      continue\n    }\n    if (character === \")\") {\n      if (open.pop() === undefined) return `${at} closes nothing; write \\\\) for a literal parenthesis`\n      repeatable = true\n      continue\n    }\n    if (character === \"{\") {\n      const count = countedRepetition.exec(pattern.slice(index))\n      if (count === null) return `${at} is not a repetition count; write \\\\{ for a literal brace`\n      if (!repeatable) return `${at} repeats nothing; write \\\\{ for a literal brace`\n      index += count[0].length - 1\n      continue\n    }\n    if (character === \"}\" || character === \"]\") {\n      return `${at} closes nothing; write \\\\${character} for a literal ${character === \"}\" ? \"brace\" : \"bracket\"}`\n    }\n    if (character === \"*\" || character === \"+\" || character === \"?\") {\n      if (!repeatable) return `${at} repeats nothing; write \\\\${character} for a literal ${character}`\n      continue\n    }\n    repeatable = character !== \"|\" && character !== \"^\" && character !== \"$\"\n  }\n  const unclosed = open.at(-1)\n  return unclosed === undefined\n    ? undefined\n    : `\"(\" at column ${unclosed + 1} is never closed; write \\\\( for a literal parenthesis`\n}\n\n/** The JavaScript engine's reason, without its prefix or its echo of the pattern. */\nconst engineReason = (error: Error): string => {\n  const reason = error.message.replace(/^Invalid regular expression: (\\/.*\\/[a-z]*: )?/, \"\").trim()\n  return `invalid expression: ${reason}`\n}\n\n/**\n * Whether `error` is a pattern or glob rejection this contract wrote.\n *\n * Those messages are host-authored and name the construct that broke, so a\n * caller may show them to a model. A peer's `invalid_pattern` built from\n * `rg`'s stderr is not one of them and stays private.\n *\n * @category validation\n * @since 1.0.0\n */\nexport const isContractRejection = (error: StdError.StdError): boolean =>\n  error.code === \"invalid_pattern\" && error.message.startsWith(`${rejectionPrefix}\"`)\n\n/**\n * Validates the portable `-g` grammar before either peer sees it.\n *\n * @category validation\n * @since 1.0.0\n */\nexport const validateGlob = (glob: string): StdError.StdError | undefined => {\n  const pattern = glob.startsWith(\"!\") ? glob.slice(1) : glob\n  // `rg` drops the trailing spaces and then ignores a glob that is left blank,\n  // which filters nothing at all. Rejecting it keeps a typo from silently\n  // widening the search instead of narrowing it.\n  if (pattern.replace(/ +$/, \"\").length === 0) return invalidPattern(glob, \"glob patterns must not be empty\")\n  if (!/^[\\x20-\\x7e]*$/.test(pattern)) return invalidPattern(glob, \"globs must contain printable ASCII only\")\n  if (pattern.includes(\"\\\\\") || pattern.includes(\"[\") || pattern.includes(\"]\")) {\n    return invalidPattern(glob, \"glob escapes and character classes are not supported\")\n  }\n  let inBrace = false\n  let alternatives = 1\n  let expansionCount = 1\n  for (let index = 0; index < pattern.length; index++) {\n    const character = pattern[index]\n    if (character === \"{\") {\n      if (inBrace) return invalidPattern(glob, \"nested brace alternatives are not supported\")\n      inBrace = true\n      alternatives = 1\n    } else if (character === \",\" && inBrace) {\n      alternatives++\n    } else if (character === \"}\") {\n      if (!inBrace || alternatives < 2) return invalidPattern(glob, \"braces must contain alternatives\")\n      inBrace = false\n      expansionCount *= alternatives\n      if (expansionCount > 256) return invalidPattern(glob, \"glob brace expansion exceeds 256 patterns\")\n    }\n  }\n  if (inBrace) return invalidPattern(glob, \"glob braces must be balanced\")\n  return undefined\n}\n\n/**\n * Compiles a pattern after common validation.\n *\n * @category matching\n * @since 1.0.0\n */\nexport const expression = (pattern: string, fixedStrings: boolean, insensitive: boolean): RegExp => {\n  const input = fixedStrings ? escapeRegex(pattern) : pattern\n  let source = \"\"\n  let inClass = false\n  for (let index = 0; index < input.length; index++) {\n    const character = input[index]\n    if (character === \"\\\\\") {\n      source += `${character}${input[index + 1] ?? \"\"}`\n      index++\n    } else if (character === \"[\") {\n      inClass = true\n      source += character\n    } else if (character === \"]\" && inClass) {\n      inClass = false\n      source += character\n    } else if (!inClass && character === \".\") {\n      source += \"[^\\\\n]\"\n    } else if (!inClass && character === \"$\") {\n      source += \"(?![\\\\s\\\\S])\"\n    } else {\n      source += character\n    }\n  }\n  return new RegExp(source, insensitive ? \"iu\" : \"u\")\n}\n\nconst expandBraces = (pattern: string): ReadonlyArray<string> => {\n  const opening = pattern.indexOf(\"{\")\n  if (opening < 0) return [pattern]\n  const closing = pattern.indexOf(\"}\", opening + 1)\n  if (closing < 0) return [pattern]\n  const alternatives = pattern.slice(opening + 1, closing).split(\",\")\n  if (alternatives.length < 2) return [pattern]\n  return alternatives.flatMap((alternative) =>\n    expandBraces(\n      `${pattern.slice(0, opening)}${alternative}${pattern.slice(closing + 1)}`\n    )\n  )\n}\n\nconst globExpression = (pattern: string): RegExp => {\n  let source = \"\"\n  for (let index = 0; index < pattern.length; index++) {\n    const character = pattern[index]!\n    const next = pattern[index + 1]\n    if (\n      character === \"*\" && next === \"*\" &&\n      (index === 0 || pattern[index - 1] === \"/\") &&\n      (pattern[index + 2] === undefined || pattern[index + 2] === \"/\")\n    ) {\n      source += pattern[index + 2] === \"/\" ? \"(?:.*/)?\" : \".*\"\n      index += pattern[index + 2] === \"/\" ? 2 : 1\n    } else if (character === \"*\") source += \"[^/]*\"\n    else if (character === \"?\") source += \"[^/]\"\n    else source += character.replace(/[\\\\^$.*+?()[\\]{}|]/g, \"\\\\$&\")\n  }\n  return new RegExp(`^${source}$`)\n}\n\nconst outsidePrintableAscii = /[^\\x20-\\x7e]/\n\n// Printable ASCII is its own UTF-8 encoding, and paths are overwhelmingly\n// printable ASCII, so the encoder only runs for the paths that need it.\nconst utf8ByteString = (value: string): string =>\n  outsidePrintableAscii.test(value)\n    ? Array.from(new TextEncoder().encode(value), (byte) => String.fromCharCode(byte)).join(\"\")\n    : value\n\n/**\n * Rewrites a glob into the one spelling both peers match against.\n *\n * `.` is never a path component either peer can produce, so a leading `./` and\n * every interior `/./` would silently make a pattern unmatchable. Both are\n * folded into the root anchor, which is what a caller writing `./src/**` means.\n * Trailing spaces are dropped because `rg` reads `-g` by gitignore's rules and\n * drops them too, so `\"a.ts \"` finds `a.ts` in the native peer and has to find\n * it in the in-process one. A leading `!` is preserved so exclusion globs\n * canonicalize the same way.\n *\n * @category matching\n * @since 1.0.0\n */\nexport const canonicalGlob = (glob: string): string => {\n  const excluded = glob.startsWith(\"!\")\n  const pattern = excluded ? glob.slice(1) : glob\n  const canonical = pattern.replace(/ +$/, \"\").replace(/\\/\\.(?=\\/)/g, \"\").replace(/^\\.\\//, \"/\")\n  return excluded ? `!${canonical}` : canonical\n}\n\ninterface CompiledGlob {\n  readonly byPath: boolean\n  readonly expression: RegExp\n}\n\nconst compiled = new Map<string, ReadonlyArray<CompiledGlob>>()\n\n/**\n * Compiles one glob into its alternatives, once per distinct pattern.\n *\n * The in-process peer asks whether a pattern matches for every candidate file\n * in the walk, so canonicalizing, brace expanding and compiling the pattern\n * inside that loop makes the work quadratic in the tree. A pattern compiles to\n * the same matchers every time, so the compilation is cached; the cache is\n * bounded because callers, not the tree, supply the patterns.\n */\nconst compileGlob = (pattern: string): ReadonlyArray<CompiledGlob> => {\n  const cached = compiled.get(pattern)\n  if (cached !== undefined) return cached\n  const matchers = expandBraces(canonicalGlob(pattern)).map((expanded) => {\n    const rooted = expanded.startsWith(\"/\")\n    const normalized = rooted ? expanded.slice(1) : expanded\n    return { byPath: rooted || normalized.includes(\"/\"), expression: globExpression(normalized) }\n  })\n  if (compiled.size >= 256) compiled.clear()\n  compiled.set(pattern, matchers)\n  return matchers\n}\n\n/**\n * Matches the supported `-g` subset against a root-relative candidate path.\n *\n * A pattern without `/` matches the basename at any depth. Every other pattern\n * is matched against the candidate's path relative to the search root, anchored\n * at the root, whether or not it carries the optional leading `/`.\n *\n * @category matching\n * @since 1.0.0\n */\nexport const matchesGlob = (pattern: string, relative: string, basename: string): boolean =>\n  compileGlob(pattern).some((matcher) => matcher.expression.test(utf8ByteString(matcher.byPath ? relative : basename)))\n\n/**\n * Applies ripgrep `-g` ordering: positive globs include and `!` globs exclude.\n *\n * @category matching\n * @since 1.0.0\n */\nexport const includedByGlobs = (globs: ReadonlyArray<string>, relative: string, basename: string): boolean => {\n  const positives = globs.filter((glob) => !glob.startsWith(\"!\"))\n  let included = positives.length === 0\n  for (const glob of globs) {\n    const excluded = glob.startsWith(\"!\")\n    if (matchesGlob(excluded ? glob.slice(1) : glob, relative, basename)) included = !excluded\n  }\n  return included\n}\n\nconst wildcard = /[*?{}]/\n\nconst literalDirectory = (pattern: string): ReadonlyArray<string> => {\n  if (!pattern.includes(\"/\")) return []\n  const segments = pattern.replace(/^\\//, \"\").split(\"/\").filter((segment) => segment.length > 0)\n  const wildcardAt = segments.findIndex((segment) => wildcard.test(segment))\n  return wildcardAt < 0 ? segments.slice(0, -1) : segments.slice(0, wildcardAt)\n}\n\nconst rootRelativeSuffix = (pattern: string, root: string, path: Path.Path): string | undefined => {\n  const anchored = pattern.replace(/^\\/+/, \"\")\n  const patternRoot = path.sep === \"\\\\\" ? root.replaceAll(\"\\\\\", \"/\") : root\n  const stem = patternRoot.replace(/^\\/+/, \"\").replace(/\\/+$/, \"\")\n  return stem.length > 0 && anchored.startsWith(`${stem}/`) ? anchored.slice(stem.length + 1) : undefined\n}\n\nconst unsatisfiedReason = (\n  options: {\n    readonly fileSystem: FileSystem.FileSystem\n    readonly path: Path.Path\n    readonly root: string\n    readonly hidden: boolean\n  },\n  pattern: string\n): Effect.Effect<string | undefined> =>\n  Effect.gen(function*() {\n    const reasons: Array<string> = []\n    for (const alternative of expandBraces(pattern)) {\n      const segments = literalDirectory(alternative)\n      if (segments.length === 0) return undefined\n      const skipped = segments.find((segment) => Walk.skippedDirectories.has(segment))\n      if (skipped !== undefined) {\n        reasons.push(`${skipped} is never descended into; name it as the search root to look inside it`)\n        continue\n      }\n      if (!options.hidden && segments.some((segment) => segment.startsWith(\".\"))) {\n        reasons.push(\"hidden paths are excluded unless hidden is true\")\n        continue\n      }\n      const directory = segments.join(\"/\")\n      const present = yield* options.fileSystem.stat(options.path.join(options.root, directory)).pipe(\n        Effect.map((info) => info.type === \"Directory\"),\n        Effect.orElseSucceed(() => false)\n      )\n      if (present) return undefined\n      reasons.push(`there is no ${directory} directory there`)\n    }\n    return reasons[0]\n  })\n\n/**\n * Explains the positive globs that no file under the root could ever match.\n *\n * A search that returns nothing is ambiguous: the tree may hold no match, or\n * the pattern may be unsatisfiable — an absolute path written where a\n * root-relative one belongs, a directory that does not exist, a skipped\n * directory, a hidden path with `hidden` left false. Callers attach the result\n * to `notice` when they produced no entries. Ignore exclusions name the\n * `noIgnore: true` escape hatch, while impossible globs explain the correction.\n * This keeps the cases\n * distinguishable. Exclusion globs are ignored: excluding what is not there\n * changes nothing.\n *\n * @category diagnostics\n * @since 1.0.0\n */\nexport const unsatisfiableNotice = (options: {\n  readonly fileSystem: FileSystem.FileSystem\n  readonly path: Path.Path\n  readonly root: string\n  readonly globs: ReadonlyArray<string>\n  readonly noIgnore?: boolean | undefined\n  readonly ignored?: boolean | undefined\n  readonly hidden: boolean\n}): Effect.Effect<string | undefined> =>\n  Effect.gen(function*() {\n    // Globs filter a walk. A root that names one file is searched whatever the\n    // globs say — `rg` always searches a path given on the command line — so\n    // there is no unsatisfiable pattern to report and no directory to stat.\n    const walkable = yield* options.fileSystem.stat(options.root).pipe(\n      Effect.map((info) => info.type === \"Directory\"),\n      Effect.orElseSucceed(() => false)\n    )\n    if (!walkable) return undefined\n    const sentences: Array<string> = []\n    for (const glob of options.globs) {\n      if (glob.startsWith(\"!\")) continue\n      const canonical = canonicalGlob(glob)\n      const reason = yield* unsatisfiedReason(options, canonical)\n      if (reason === undefined) continue\n      const suffix = rootRelativeSuffix(canonical, options.root, options.path)\n      sentences.push(\n        `No file under ${options.root} can match \"${glob}\": ${\n          suffix === undefined\n            ? reason\n            : `glob patterns are relative to the search root, so use \"${suffix}\" instead`\n        }.`\n      )\n    }\n    // An impossible glob cannot be repaired by opting out of ignores.\n    if (sentences.length > 0 && sentences.length === options.globs.filter((glob) => !glob.startsWith(\"!\")).length) {\n      return sentences.join(\" \")\n    }\n    const included = (relative: string, basename: string) => includedByGlobs(options.globs, relative, basename)\n    const ignored = options.noIgnore ? false : options.ignored ??\n      (yield* Walk.files(options.fileSystem, options.path, options.root, options.hidden, false, included).pipe(\n        Effect.map((walked) => walked.ignored),\n        Effect.orElseSucceed(() => false)\n      ))\n    if (ignored) {\n      sentences.push(\"No results; ignore files excluded paths. Retry with noIgnore: true to include them.\")\n    }\n    return sentences.length === 0 ? undefined : sentences.join(\" \")\n  })\n"]}