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

package/dist/cjs/Search.js

@@ -0,0 +1,51 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var Search_exports = {};
+__export(Search_exports, {
+  Search: () => Search,
+  layerNoop: () => layerNoop,
+  make: () => make,
+  makeNoop: () => makeNoop
+});
+module.exports = __toCommonJS(Search_exports);
+var import_effect = require("effect");
+var StdError = __toESM(require("./StdError.js"), 1);
+const Search = import_effect.Context.Service("@smthrs/std/Search");
+const make = (service) => Search.of(service);
+const makeNoop = () => {
+  const unavailable = () => import_effect.Effect.fail(
+    new StdError.StdError({
+      code: "provider_unavailable",
+      message: "No search implementation is configured"
+    })
+  );
+  return make({ grep: unavailable, glob: unavailable });
+};
+const layerNoop = import_effect.Layer.succeed(Search, makeNoop());
+//# sourceMappingURL=Search.js.map

package/dist/cjs/Search.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/Search.ts"],
+  "sourcesContent": ["/**\n * The implementation seam for the ripgrep search contract.\n *\n * Both implementations answer the same normalized calls. `PortableSearch`\n * performs the work in-process; `NativeSearch` drives the `rg` executable.\n * Callers select an implementation by Layer and cannot observe which one was\n * selected from the result.\n *\n * @since 1.0.0\n */\n\nimport { Context, Effect, Layer } from \"effect\"\nimport * as StdError from \"./StdError.ts\"\n\n/**\n * Normalized grep input shared by both implementations.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface GrepInput {\n  readonly pattern: string\n  readonly root: string\n  readonly fixedStrings: boolean\n  readonly ignoreCase: boolean\n  readonly smartCase: boolean\n  readonly globs: ReadonlyArray<string>\n  readonly beforeContext: number\n  readonly afterContext: number\n  readonly maxCount?: number | undefined\n  readonly filesWithMatches: boolean\n  /** Opt out of root-scoped .gitignore rules; defaults to false. */\n  readonly noIgnore?: boolean | undefined\n  readonly hidden: boolean\n  readonly symbols: boolean\n  readonly limit: number\n}\n\n/**\n * One matching or context line, as a peer produces it before grouping.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface GrepLine {\n  readonly file: string\n  readonly line: number\n  readonly text: string\n  readonly kind: \"match\" | \"context\"\n}\n\n/**\n * One context line carried inside the match it belongs to.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface ContextLine {\n  readonly line: number\n  readonly text: string\n}\n\n/**\n * The definition enclosing a hit, when the file's shape says so plainly.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface Symbol {\n  readonly kind: string\n  readonly name: string\n  readonly startLine: number\n  readonly endLine: number\n}\n\n/**\n * One hit: the matching line, the context that belongs to it, and the\n * definition it sits in.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface GrepMatch {\n  readonly file: string\n  readonly line: number\n  readonly text: string\n  readonly before: ReadonlyArray<ContextLine>\n  readonly after: ReadonlyArray<ContextLine>\n  readonly symbol?: Symbol | undefined\n}\n\n/**\n * Normalized grep output.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface GrepOutput {\n  readonly matches: ReadonlyArray<GrepMatch>\n  readonly files: ReadonlyArray<string>\n  readonly filesSearched: number\n  readonly skippedBinary: number\n  readonly truncated: boolean\n  readonly notice?: string | undefined\n}\n\n/**\n * Normalized glob input.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface GlobInput {\n  readonly pattern: string\n  readonly root: string\n  /** Opt out of root-scoped .gitignore rules; defaults to false. */\n  readonly noIgnore?: boolean | undefined\n  readonly hidden: boolean\n  readonly limit: number\n}\n\n/**\n * Normalized glob output.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface GlobOutput {\n  readonly paths: ReadonlyArray<string>\n  readonly total: number\n  readonly truncated: boolean\n  readonly notice?: string | undefined\n}\n\n/**\n * The one search contract implemented by native and portable peers.\n *\n * @category services\n * @since 1.0.0\n */\nexport interface Search {\n  readonly grep: (input: GrepInput) => Effect.Effect<GrepOutput, StdError.StdError>\n  readonly glob: (input: GlobInput) => Effect.Effect<GlobOutput, StdError.StdError>\n}\n\n/**\n * The {@link Search} service tag.\n *\n * @category services\n * @since 1.0.0\n */\nexport const Search: Context.Service<Search, Search> = Context.Service(\"@smthrs/std/Search\")\n\n/**\n * Builds a search service from its two operations.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const make = (service: Search): Search => Search.of(service)\n\n/**\n * Builds an unavailable search service for compositions that deliberately omit search.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const makeNoop = (): Search => {\n  const unavailable = () =>\n    Effect.fail(\n      new StdError.StdError({\n        code: \"provider_unavailable\",\n        message: \"No search implementation is configured\"\n      })\n    )\n  return make({ grep: unavailable, glob: unavailable })\n}\n\n/**\n * Provides {@link makeNoop}.\n *\n * @category layers\n * @since 1.0.0\n */\nexport const layerNoop: Layer.Layer<Search> = Layer.succeed(Search, makeNoop())\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAWA,oBAAuC;AACvC,eAA0B;AA2InB,MAAM,SAA0C,sBAAQ,QAAQ,oBAAoB;AAQpF,MAAM,OAAO,CAAC,YAA4B,OAAO,GAAG,OAAO;AAQ3D,MAAM,WAAW,MAAc;AACpC,QAAM,cAAc,MAClB,qBAAO;AAAA,IACL,IAAI,SAAS,SAAS;AAAA,MACpB,MAAM;AAAA,MACN,SAAS;AAAA,IACX,CAAC;AAAA,EACH;AACF,SAAO,KAAK,EAAE,MAAM,aAAa,MAAM,YAAY,CAAC;AACtD;AAQO,MAAM,YAAiC,oBAAM,QAAQ,QAAQ,SAAS,CAAC;",
+  "names": []
+}

package/dist/cjs/SearchConformance.d.ts

@@ -0,0 +1,115 @@
+/**
+ * A differential conformance kit for {@link Search} implementations.
+ *
+ * `Search` is a public extension seam: a host binds its own implementation and
+ * every `grep` and `glob` call in the package goes through it. Two peers ship
+ * here, and the contract they are held to used to live only in
+ * `test/SearchConformance.test.ts` — a file `package.json` does not publish, so
+ * a third-party peer had the seam and no way to prove it filled it. Worse, the
+ * cases there are hand-picked: they pin the divergences somebody already
+ * found. A literal `?` matched `fo` in one peer and `foo?` in the other for as
+ * long as nobody thought to write that case down.
+ *
+ * This module is the other half. It generates a tree and a batch of calls from
+ * a seed, runs them through two implementations, and reports every answer that
+ * differs. Nothing here knows which peer is right: a divergence is the finding,
+ * and the reference peer to compare against is the caller's choice —
+ * `PortableSearch` is the obvious one, because it needs no external binary.
+ *
+ * The generator deliberately stays inside the ground both peers claim to
+ * share: no symlinks, no unreadable directories, no CRLF, no NUL bytes, no
+ * filename a shell would have to quote. Those are the cases the hand-written
+ * table pins one by one, with an expected value that says which behaviour is
+ * intended. A generator cannot say that; it can only say the two disagree.
+ *
+ * @since 1.0.0
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import type * as Search from "./Search.ts";
+/**
+ * One file the generated tree contains.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface GeneratedFile {
+    /** Path relative to the tree root, always with `/` separators. */
+    readonly path: string;
+    readonly content: string;
+}
+/**
+ * A generated tree plus the calls to make against it.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Plan {
+    readonly seed: number;
+    readonly root: string;
+    readonly files: ReadonlyArray<GeneratedFile>;
+    readonly grep: ReadonlyArray<Search.GrepInput>;
+    readonly glob: ReadonlyArray<Search.GlobInput>;
+}
+/**
+ * One call two implementations answered differently.
+ *
+ * `subject` and `reference` are the rendered answers, so a report names the
+ * bytes that differ rather than saying only that they did.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Divergence {
+    readonly call: "grep" | "glob";
+    readonly input: Search.GrepInput | Search.GlobInput;
+    readonly subject: string;
+    readonly reference: string;
+}
+/**
+ * Builds a reproducible tree and call batch from a seed.
+ *
+ * The same seed and root always produce the same plan, so a divergence a run
+ * reports can be replayed exactly by rerunning that seed.
+ *
+ * @category generators
+ * @since 1.0.0
+ */
+export declare const plan: (options: {
+    readonly seed: number;
+    readonly root: string;
+    readonly files?: number | undefined;
+    readonly calls?: number | undefined;
+}) => Plan;
+/**
+ * Writes a plan's tree under its root.
+ *
+ * @category generators
+ * @since 1.0.0
+ */
+export declare const materialize: (target: Plan) => Effect.Effect<void, never, FileSystem.FileSystem | Path.Path>;
+/**
+ * Runs every call in a plan through two implementations and reports the
+ * answers that differ.
+ *
+ * A failure is compared like any other answer: two peers that refuse the same
+ * call with the same code agree, and one that refuses where the other answers
+ * has diverged.
+ *
+ * @category conformance
+ * @since 1.0.0
+ */
+export declare const compare: (options: {
+    readonly plan: Plan;
+    readonly subject: Search.Search;
+    readonly reference: Search.Search;
+}) => Effect.Effect<ReadonlyArray<Divergence>>;
+/**
+ * Renders divergences as the report a failing conformance run should print.
+ *
+ * @category conformance
+ * @since 1.0.0
+ */
+export declare const report: (divergences: ReadonlyArray<Divergence>) => string;
+//# sourceMappingURL=SearchConformance.d.ts.map

package/dist/cjs/SearchConformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SearchConformance.d.ts","sourceRoot":"","sources":["../../src/SearchConformance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,UAAU,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,IAAI,MAAM,aAAa,CAAA;AACnC,OAAO,KAAK,KAAK,MAAM,MAAM,aAAa,CAAA;AAG1C;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED;;;;;GAKG;AACH,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,CAAA;IAC5C,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,SAAS,CAAC,CAAA;IAC9C,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,SAAS,CAAC,CAAA;CAC/C;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,CAAA;IACnD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAiDD;;;;;;;;GAQG;AACH,eAAO,MAAM,IAAI,GAAI,SAAS;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACpC,KAAG,IAyEH,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GACtB,QAAQ,IAAI,KACX,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,UAAU,CAAC,UAAU,GAAG,IAAI,CAAC,IAAI,CAW3D,CAAA;AAaJ;;;;;;;;;;GAUG;AACH,eAAO,MAAM,OAAO,GAAI,SAAS;IAC/B,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAA;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,CAAA;CAClC,KAAG,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,UAAU,CAAC,CAcvC,CAAA;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,MAAM,GAAI,aAAa,aAAa,CAAC,UAAU,CAAC,KAAG,MAOhD,CAAA"}

package/dist/cjs/SearchConformance.js

@@ -0,0 +1,172 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var SearchConformance_exports = {};
+__export(SearchConformance_exports, {
+  compare: () => compare,
+  materialize: () => materialize,
+  plan: () => plan,
+  report: () => report
+});
+module.exports = __toCommonJS(SearchConformance_exports);
+var Effect = __toESM(require("effect/Effect"), 1);
+var FileSystem = __toESM(require("effect/FileSystem"), 1);
+var Path = __toESM(require("effect/Path"), 1);
+const random = (seed) => {
+  let state = seed >>> 0;
+  return () => {
+    state = state + 1831565813 >>> 0;
+    let value = Math.imul(state ^ state >>> 15, 1 | state);
+    value = value + Math.imul(value ^ value >>> 7, 61 | value) ^ value;
+    return ((value ^ value >>> 14) >>> 0) / 4294967296;
+  };
+};
+const pick = (next, values) => values[Math.floor(next() * values.length)];
+const chance = (next, probability) => next() < probability;
+const stems = ["alpha", "beta", "gamma", "Delta", "e-psilon", "ze_ta", "eta2", "th.eta", "iota", "kappa"];
+const extensions = [".ts", ".js", ".txt", ".py", ".md"];
+const directories = ["", "one", "one/two", "three", "three/four/five"];
+const lines = [
+  "needle",
+  "a needle in the line",
+  "Needle capitalised",
+  "no match here",
+  "needle? with a question mark",
+  "a+b and x*y and [z]",
+  "def widen(value):",
+  "class Widget:",
+  "    needle = value",
+  "function widen(value) {",
+  "",
+  "trailing needle"
+];
+const patterns = ["needle", "Needle", "needle?", "a+b", "[z]", "^needle$", "widen", "no match at all"];
+const globPatterns = ["**/*.ts", "*.ts", "**/*", "one/**/*.ts", "**/*.{ts,js}", "**/alpha*"];
+const plan = (options) => {
+  const next = random(options.seed);
+  const fileCount = options.files ?? 12;
+  const callCount = options.calls ?? 12;
+  const files = [];
+  for (let index = 0; index < fileCount; index++) {
+    const directory = pick(next, directories);
+    const name = `${pick(next, stems)}${index}${pick(next, extensions)}`;
+    const path = directory === "" ? name : `${directory}/${name}`;
+    const body = [];
+    for (let line = 0; line < 1 + Math.floor(next() * 8); line++) body.push(pick(next, lines));
+    files.push({ path, content: `${body.join("\n")}${chance(next, 0.8) ? "\n" : ""}` });
+  }
+  if (fileCount > 0) {
+    files.push(
+      { path: ".gitignore", content: "*.ignored\n!keep.ignored\n/root-only.ts\ncache/\n" },
+      { path: "drop.ignored", content: "needle\n" },
+      { path: "keep.ignored", content: "needle\n" },
+      { path: "root-only.ts", content: "needle\n" },
+      { path: "cache/a.ts", content: "needle\n" },
+      { path: "nested/.gitignore", content: "!keep.ignored\n/anchored.ts\nframes/\n" },
+      { path: "nested/keep.ignored", content: "needle\n" },
+      { path: "nested/drop.ignored", content: "needle\n" },
+      { path: "nested/anchored.ts", content: "needle\n" },
+      { path: "nested/deep/anchored.ts", content: "needle\n" },
+      { path: "nested/root-only.ts", content: "needle\n" },
+      { path: "nested/frames/a.ts", content: "needle\n" },
+      { path: "other/frames", content: "needle\n" }
+    );
+  }
+  const roots = [options.root, ...files.map((entry) => `${options.root}/${entry.path}`)];
+  const grep = [];
+  for (let index = 0; index < callCount; index++) {
+    const fixedStrings = chance(next, 0.4);
+    const ignoreCase = chance(next, 0.25);
+    grep.push({
+      pattern: pick(next, patterns),
+      root: chance(next, 0.75) ? options.root : pick(next, roots),
+      fixedStrings,
+      ignoreCase,
+      smartCase: !ignoreCase && chance(next, 0.3),
+      globs: chance(next, 0.4) ? [pick(next, ["*.ts", "*.txt", "!*.js", "**/*.ts"])] : [],
+      beforeContext: Math.floor(next() * 3),
+      afterContext: Math.floor(next() * 3),
+      ...chance(next, 0.3) ? { maxCount: 1 + Math.floor(next() * 2) } : {},
+      filesWithMatches: chance(next, 0.25),
+      hidden: chance(next, 0.5),
+      noIgnore: chance(next, 0.25),
+      symbols: chance(next, 0.3),
+      limit: 1 + Math.floor(next() * 40)
+    });
+  }
+  const glob = [];
+  for (let index = 0; index < callCount; index++) {
+    glob.push({
+      pattern: pick(next, globPatterns),
+      root: options.root,
+      hidden: chance(next, 0.5),
+      noIgnore: chance(next, 0.25),
+      limit: 1 + Math.floor(next() * 20)
+    });
+  }
+  return { seed: options.seed, root: options.root, files, grep, glob };
+};
+const materialize = (target) => Effect.gen(function* () {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  yield* Effect.forEach(target.files, (entry) => {
+    const absolute = path.join(target.root, ...entry.path.split("/"));
+    return fileSystem.makeDirectory(path.dirname(absolute), { recursive: true }).pipe(
+      Effect.andThen(fileSystem.writeFileString(absolute, entry.content)),
+      Effect.orDie
+    );
+  }, { discard: true });
+});
+const rendered = (effect) => effect.pipe(
+  Effect.match({
+    onSuccess: (value) => JSON.stringify(value),
+    onFailure: (error) => JSON.stringify({ failure: error.code })
+  })
+);
+const compare = (options) => Effect.gen(function* () {
+  const divergences = [];
+  for (const input of options.plan.grep) {
+    const subject = yield* rendered(options.subject.grep(input));
+    const reference = yield* rendered(options.reference.grep(input));
+    if (subject !== reference) divergences.push({ call: "grep", input, subject, reference });
+  }
+  for (const input of options.plan.glob) {
+    const subject = yield* rendered(options.subject.glob(input));
+    const reference = yield* rendered(options.reference.glob(input));
+    if (subject !== reference) divergences.push({ call: "glob", input, subject, reference });
+  }
+  return divergences;
+});
+const report = (divergences) => divergences.map(
+  (divergence) => [
+    `${divergence.call}(${JSON.stringify(divergence.input)})`,
+    `  subject:   ${divergence.subject}`,
+    `  reference: ${divergence.reference}`
+  ].join("\n")
+).join("\n\n");
+//# sourceMappingURL=SearchConformance.js.map

package/dist/cjs/SearchConformance.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/SearchConformance.ts"],
+  "sourcesContent": ["/**\n * A differential conformance kit for {@link Search} implementations.\n *\n * `Search` is a public extension seam: a host binds its own implementation and\n * every `grep` and `glob` call in the package goes through it. Two peers ship\n * here, and the contract they are held to used to live only in\n * `test/SearchConformance.test.ts` \u2014 a file `package.json` does not publish, so\n * a third-party peer had the seam and no way to prove it filled it. Worse, the\n * cases there are hand-picked: they pin the divergences somebody already\n * found. A literal `?` matched `fo` in one peer and `foo?` in the other for as\n * long as nobody thought to write that case down.\n *\n * This module is the other half. It generates a tree and a batch of calls from\n * a seed, runs them through two implementations, and reports every answer that\n * differs. Nothing here knows which peer is right: a divergence is the finding,\n * and the reference peer to compare against is the caller's choice \u2014\n * `PortableSearch` is the obvious one, because it needs no external binary.\n *\n * The generator deliberately stays inside the ground both peers claim to\n * share: no symlinks, no unreadable directories, no CRLF, no NUL bytes, no\n * filename a shell would have to quote. Those are the cases the hand-written\n * table pins one by one, with an expected value that says which behaviour is\n * intended. A generator cannot say that; it can only say the two disagree.\n *\n * @since 1.0.0\n */\n\nimport * as Effect from \"effect/Effect\"\nimport * as FileSystem from \"effect/FileSystem\"\nimport * as Path from \"effect/Path\"\nimport type * as Search from \"./Search.ts\"\nimport type * as StdError from \"./StdError.ts\"\n\n/**\n * One file the generated tree contains.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface GeneratedFile {\n  /** Path relative to the tree root, always with `/` separators. */\n  readonly path: string\n  readonly content: string\n}\n\n/**\n * A generated tree plus the calls to make against it.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface Plan {\n  readonly seed: number\n  readonly root: string\n  readonly files: ReadonlyArray<GeneratedFile>\n  readonly grep: ReadonlyArray<Search.GrepInput>\n  readonly glob: ReadonlyArray<Search.GlobInput>\n}\n\n/**\n * One call two implementations answered differently.\n *\n * `subject` and `reference` are the rendered answers, so a report names the\n * bytes that differ rather than saying only that they did.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface Divergence {\n  readonly call: \"grep\" | \"glob\"\n  readonly input: Search.GrepInput | Search.GlobInput\n  readonly subject: string\n  readonly reference: string\n}\n\n/**\n * mulberry32: 32 bits of state, uniform enough for fixture generation and\n * reproducible from a seed on every host, which a shared `Math.random` is not.\n */\nconst random = (seed: number): () => number => {\n  let state = seed >>> 0\n  return () => {\n    state = (state + 0x6D2B79F5) >>> 0\n    let value = Math.imul(state ^ (state >>> 15), 1 | state)\n    value = (value + Math.imul(value ^ (value >>> 7), 61 | value)) ^ value\n    return ((value ^ (value >>> 14)) >>> 0) / 4_294_967_296\n  }\n}\n\nconst pick = <A>(next: () => number, values: ReadonlyArray<A>): A => values[Math.floor(next() * values.length)]!\n\nconst chance = (next: () => number, probability: number): boolean => next() < probability\n\n// Names both peers walk identically: no separator, no dot prefix outside the\n// two deliberate hidden entries, no name a directory skip list contains, and\n// no character that would need quoting on a command line.\nconst stems = [\"alpha\", \"beta\", \"gamma\", \"Delta\", \"e-psilon\", \"ze_ta\", \"eta2\", \"th.eta\", \"iota\", \"kappa\"] as const\nconst extensions = [\".ts\", \".js\", \".txt\", \".py\", \".md\"] as const\nconst directories = [\"\", \"one\", \"one/two\", \"three\", \"three/four/five\"] as const\n\n// Lines drawn from a vocabulary that mixes the needle, near misses, regex\n// metacharacters that must survive `fixedStrings`, and definition headers the\n// `symbols` option reads.\nconst lines = [\n  \"needle\",\n  \"a needle in the line\",\n  \"Needle capitalised\",\n  \"no match here\",\n  \"needle? with a question mark\",\n  \"a+b and x*y and [z]\",\n  \"def widen(value):\",\n  \"class Widget:\",\n  \"    needle = value\",\n  \"function widen(value) {\",\n  \"\",\n  \"trailing needle\"\n] as const\n\nconst patterns = [\"needle\", \"Needle\", \"needle?\", \"a+b\", \"[z]\", \"^needle$\", \"widen\", \"no match at all\"] as const\n\nconst globPatterns = [\"**/*.ts\", \"*.ts\", \"**/*\", \"one/**/*.ts\", \"**/*.{ts,js}\", \"**/alpha*\"] as const\n\n/**\n * Builds a reproducible tree and call batch from a seed.\n *\n * The same seed and root always produce the same plan, so a divergence a run\n * reports can be replayed exactly by rerunning that seed.\n *\n * @category generators\n * @since 1.0.0\n */\nexport const plan = (options: {\n  readonly seed: number\n  readonly root: string\n  readonly files?: number | undefined\n  readonly calls?: number | undefined\n}): Plan => {\n  const next = random(options.seed)\n  const fileCount = options.files ?? 12\n  const callCount = options.calls ?? 12\n  const files: Array<GeneratedFile> = []\n  for (let index = 0; index < fileCount; index++) {\n    const directory = pick(next, directories)\n    // The index makes every generated path unique, including repeated random picks.\n    const name = `${pick(next, stems)}${index}${pick(next, extensions)}`\n    const path = directory === \"\" ? name : `${directory}/${name}`\n    const body: Array<string> = []\n    for (let line = 0; line < 1 + Math.floor(next() * 8); line++) body.push(pick(next, lines))\n    files.push({ path, content: `${body.join(\"\\n\")}${chance(next, 0.8) ? \"\\n\" : \"\"}` })\n  }\n\n  // Always exercise precedence, anchoring, directory pruning and nested\n  // negation alongside each seed's generated content (without a git repo).\n  if (fileCount > 0) {\n    files.push(\n      { path: \".gitignore\", content: \"*.ignored\\n!keep.ignored\\n/root-only.ts\\ncache/\\n\" },\n      { path: \"drop.ignored\", content: \"needle\\n\" },\n      { path: \"keep.ignored\", content: \"needle\\n\" },\n      { path: \"root-only.ts\", content: \"needle\\n\" },\n      { path: \"cache/a.ts\", content: \"needle\\n\" },\n      { path: \"nested/.gitignore\", content: \"!keep.ignored\\n/anchored.ts\\nframes/\\n\" },\n      { path: \"nested/keep.ignored\", content: \"needle\\n\" },\n      { path: \"nested/drop.ignored\", content: \"needle\\n\" },\n      { path: \"nested/anchored.ts\", content: \"needle\\n\" },\n      { path: \"nested/deep/anchored.ts\", content: \"needle\\n\" },\n      { path: \"nested/root-only.ts\", content: \"needle\\n\" },\n      { path: \"nested/frames/a.ts\", content: \"needle\\n\" },\n      { path: \"other/frames\", content: \"needle\\n\" }\n    )\n  }\n\n  const roots = [options.root, ...files.map((entry) => `${options.root}/${entry.path}`)]\n  const grep: Array<Search.GrepInput> = []\n  for (let index = 0; index < callCount; index++) {\n    const fixedStrings = chance(next, 0.4)\n    // `Grep.run` refuses `ignoreCase` together with `smartCase` as mutually\n    // exclusive, so a generated call carrying both would be exploring ground\n    // the contract does not describe.\n    const ignoreCase = chance(next, 0.25)\n    grep.push({\n      pattern: pick(next, patterns),\n      root: chance(next, 0.75) ? options.root : pick(next, roots),\n      fixedStrings,\n      ignoreCase,\n      smartCase: !ignoreCase && chance(next, 0.3),\n      globs: chance(next, 0.4) ? [pick(next, [\"*.ts\", \"*.txt\", \"!*.js\", \"**/*.ts\"])] : [],\n      beforeContext: Math.floor(next() * 3),\n      afterContext: Math.floor(next() * 3),\n      ...(chance(next, 0.3) ? { maxCount: 1 + Math.floor(next() * 2) } : {}),\n      filesWithMatches: chance(next, 0.25),\n      hidden: chance(next, 0.5),\n      noIgnore: chance(next, 0.25),\n      symbols: chance(next, 0.3),\n      limit: 1 + Math.floor(next() * 40)\n    })\n  }\n\n  const glob: Array<Search.GlobInput> = []\n  for (let index = 0; index < callCount; index++) {\n    glob.push({\n      pattern: pick(next, globPatterns),\n      root: options.root,\n      hidden: chance(next, 0.5),\n      noIgnore: chance(next, 0.25),\n      limit: 1 + Math.floor(next() * 20)\n    })\n  }\n\n  return { seed: options.seed, root: options.root, files, grep, glob }\n}\n\n/**\n * Writes a plan's tree under its root.\n *\n * @category generators\n * @since 1.0.0\n */\nexport const materialize = (\n  target: Plan\n): Effect.Effect<void, never, FileSystem.FileSystem | Path.Path> =>\n  Effect.gen(function*() {\n    const fileSystem = yield* FileSystem.FileSystem\n    const path = yield* Path.Path\n    yield* Effect.forEach(target.files, (entry) => {\n      const absolute = path.join(target.root, ...entry.path.split(\"/\"))\n      return fileSystem.makeDirectory(path.dirname(absolute), { recursive: true }).pipe(\n        Effect.andThen(fileSystem.writeFileString(absolute, entry.content)),\n        Effect.orDie\n      )\n    }, { discard: true })\n  })\n\n/** A typed answer rendered so two of them can be compared as text. */\nconst rendered = <A>(\n  effect: Effect.Effect<A, StdError.StdError>\n): Effect.Effect<string> =>\n  effect.pipe(\n    Effect.match({\n      onSuccess: (value) => JSON.stringify(value),\n      onFailure: (error) => JSON.stringify({ failure: error.code })\n    })\n  )\n\n/**\n * Runs every call in a plan through two implementations and reports the\n * answers that differ.\n *\n * A failure is compared like any other answer: two peers that refuse the same\n * call with the same code agree, and one that refuses where the other answers\n * has diverged.\n *\n * @category conformance\n * @since 1.0.0\n */\nexport const compare = (options: {\n  readonly plan: Plan\n  readonly subject: Search.Search\n  readonly reference: Search.Search\n}): Effect.Effect<ReadonlyArray<Divergence>> =>\n  Effect.gen(function*() {\n    const divergences: Array<Divergence> = []\n    for (const input of options.plan.grep) {\n      const subject = yield* rendered(options.subject.grep(input))\n      const reference = yield* rendered(options.reference.grep(input))\n      if (subject !== reference) divergences.push({ call: \"grep\", input, subject, reference })\n    }\n    for (const input of options.plan.glob) {\n      const subject = yield* rendered(options.subject.glob(input))\n      const reference = yield* rendered(options.reference.glob(input))\n      if (subject !== reference) divergences.push({ call: \"glob\", input, subject, reference })\n    }\n    return divergences\n  })\n\n/**\n * Renders divergences as the report a failing conformance run should print.\n *\n * @category conformance\n * @since 1.0.0\n */\nexport const report = (divergences: ReadonlyArray<Divergence>): string =>\n  divergences.map((divergence) =>\n    [\n      `${divergence.call}(${JSON.stringify(divergence.input)})`,\n      `  subject:   ${divergence.subject}`,\n      `  reference: ${divergence.reference}`\n    ].join(\"\\n\")\n  ).join(\"\\n\\n\")\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/cjs/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/cjs/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"}