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

package/dist/esm/internal/RemoteTree.js

@@ -0,0 +1,132 @@
+/**
+ * A tree another machine listed, served as a read-only `FileSystem`.
+ *
+ * `RemoteSearch` lists a root on the machine with `find` and brings back the
+ * bytes the search reads with `tar`; this module holds what came back and
+ * answers what the walk, the globs, and the matcher ask of a filesystem, so
+ * `PortableSearch` can search the copy as it searches a host.
+ *
+ * @since 1.0.0-rc.8
+ */
+import { Effect, Option, Stream } from "effect";
+import * as ByteSize from "effect/ByteSize";
+import * as FileSystem from "effect/FileSystem";
+import * as PlatformError from "effect/PlatformError";
+import * as Tar from "./Tar.js";
+const kinds = new Set(["d", "u", "f", "o", "D", "F", "L"]);
+/**
+ * The member names `tar` wrote for absolute paths, which it strips of their
+ * leading `/`, as those paths again.
+ *
+ * @private
+ * @since 1.0.0-rc.8
+ */
+export const absolute = (members) => new Map([...members].map(([name, bytes]) => [`/${name}`, bytes]));
+/**
+ * Reads NUL-terminated `<kind><path>` records up to an `E` record, then the
+ * tar stream of `.gitignore` files after it. `root` is the listed root, which
+ * is nobody's child. `undefined` when the bytes are not that shape.
+ *
+ * @private
+ * @since 1.0.0-rc.8
+ */
+export const parse = (bytes, root, path) => {
+    const decoder = new TextDecoder();
+    const listed = new Map();
+    const children = new Map();
+    let offset = 0;
+    for (;;) {
+        const end = bytes.indexOf(0, offset);
+        if (end === -1)
+            return undefined;
+        const record = decoder.decode(bytes.subarray(offset, end));
+        offset = end + 1;
+        if (record === "E")
+            break;
+        const kind = record.slice(0, 1);
+        if (!kinds.has(kind))
+            return undefined;
+        const entry = record.slice(1);
+        listed.set(entry, kind);
+        if (entry === root)
+            continue;
+        const parent = path.dirname(entry);
+        const siblings = children.get(parent);
+        if (siblings === undefined)
+            children.set(parent, [path.basename(entry)]);
+        else
+            siblings.push(path.basename(entry));
+    }
+    const ignores = Tar.files(bytes.subarray(offset));
+    return ignores === undefined ? undefined : { kinds: listed, children, contents: absolute(ignores) };
+};
+const refusal = (tag, method, path) => PlatformError.systemError({ _tag: tag, module: "FileSystem", method, pathOrDescriptor: path });
+/** What `stat` says each kind is: links resolved, a dangling one absent. */
+const types = {
+    d: "Directory",
+    u: "Directory",
+    D: "Directory",
+    f: "File",
+    F: "File",
+    o: "Unknown",
+    L: undefined
+};
+const info = (type, size) => ({
+    type,
+    size: ByteSize.bytes(BigInt(size)),
+    mtime: Option.none(),
+    atime: Option.none(),
+    birthtime: Option.none(),
+    dev: 0,
+    ino: Option.none(),
+    mode: 0,
+    nlink: Option.none(),
+    uid: Option.none(),
+    gid: Option.none(),
+    rdev: Option.none(),
+    blksize: Option.none(),
+    blocks: Option.none()
+});
+/**
+ * The tree as a read-only `FileSystem`, resolving paths with `path`. A file
+ * whose bytes did not come back is one the machine's user could not read,
+ * which the in-process peer skips exactly as it skips such a file on a host.
+ *
+ * @private
+ * @since 1.0.0-rc.8
+ */
+export const fileSystem = (tree, path) => {
+    const kindOf = (value) => tree.kinds.get(path.resolve(value));
+    const readFile = (value) => {
+        const bytes = tree.contents.get(path.resolve(value));
+        if (bytes !== undefined)
+            return Effect.succeed(bytes);
+        const type = types[kindOf(value) ?? "L"];
+        return Effect.fail(refusal(type === "File" ? "PermissionDenied" : type === undefined ? "NotFound" : "BadResource", "readFile", value));
+    };
+    return FileSystem.makeNoop({
+        stat: (value) => {
+            const type = types[kindOf(value) ?? "L"];
+            return type === undefined
+                ? Effect.fail(refusal("NotFound", "stat", value))
+                : Effect.succeed(info(type, tree.contents.get(path.resolve(value))?.length ?? 0));
+        },
+        readDirectory: (value) => {
+            const kind = kindOf(value);
+            if (kind === "d")
+                return Effect.succeed([...tree.children.get(path.resolve(value)) ?? []]);
+            const tag = kind === "u" ? "PermissionDenied" : kind === undefined || kind === "L" ? "NotFound" : "BadResource";
+            return Effect.fail(refusal(tag, "readDirectory", value));
+        },
+        readLink: (value) => {
+            const kind = kindOf(value);
+            return kind === "D" || kind === "F" || kind === "L"
+                ? Effect.succeed("")
+                : Effect.fail(refusal(kind === undefined ? "NotFound" : "BadResource", "readLink", value));
+        },
+        readFile,
+        readFileString: (value) => Effect.map(readFile(value), (bytes) => new TextDecoder().decode(bytes)),
+        stream: (value) => Stream.fromEffect(readFile(value))
+    });
+};
+//# sourceMappingURL=RemoteTree.js.map

package/dist/esm/internal/RemoteTree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RemoteTree.js","sourceRoot":"","sources":["../../../src/internal/RemoteTree.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * A tree another machine listed, served as a read-only `FileSystem`.\n *\n * `RemoteSearch` lists a root on the machine with `find` and brings back the\n * bytes the search reads with `tar`; this module holds what came back and\n * answers what the walk, the globs, and the matcher ask of a filesystem, so\n * `PortableSearch` can search the copy as it searches a host.\n *\n * @since 1.0.0-rc.8\n */\n\nimport type * as Path from \"@smthrs/kernel/Path\"\nimport { Effect, Option, Stream } from \"effect\"\nimport * as ByteSize from \"effect/ByteSize\"\nimport * as FileSystem from \"effect/FileSystem\"\nimport * as PlatformError from \"effect/PlatformError\"\nimport * as Tar from \"./Tar.ts\"\n\n/**\n * What one listed path is: `d` a directory, `u` a directory the machine's\n * user may not list, `f` a file, `o` anything else, and a symbolic link to a\n * directory (`D`), to a file (`F`), or to neither (`L`).\n *\n * @private\n * @since 1.0.0-rc.8\n */\nexport type Kind = \"d\" | \"u\" | \"f\" | \"o\" | \"D\" | \"F\" | \"L\"\n\n/**\n * One machine's listing of a root, and the bytes it brought back, by\n * absolute path.\n *\n * @private\n * @since 1.0.0-rc.8\n */\nexport interface Tree {\n  readonly kinds: ReadonlyMap<string, Kind>\n  readonly children: ReadonlyMap<string, ReadonlyArray<string>>\n  readonly contents: ReadonlyMap<string, Uint8Array>\n}\n\nconst kinds: ReadonlySet<string> = new Set([\"d\", \"u\", \"f\", \"o\", \"D\", \"F\", \"L\"])\n\n/**\n * The member names `tar` wrote for absolute paths, which it strips of their\n * leading `/`, as those paths again.\n *\n * @private\n * @since 1.0.0-rc.8\n */\nexport const absolute = (members: ReadonlyMap<string, Uint8Array>): ReadonlyMap<string, Uint8Array> =>\n  new Map([...members].map(([name, bytes]) => [`/${name}`, bytes]))\n\n/**\n * Reads NUL-terminated `<kind><path>` records up to an `E` record, then the\n * tar stream of `.gitignore` files after it. `root` is the listed root, which\n * is nobody's child. `undefined` when the bytes are not that shape.\n *\n * @private\n * @since 1.0.0-rc.8\n */\nexport const parse = (bytes: Uint8Array, root: string, path: Path.Path): Tree | undefined => {\n  const decoder = new TextDecoder()\n  const listed = new Map<string, Kind>()\n  const children = new Map<string, Array<string>>()\n  let offset = 0\n  for (;;) {\n    const end = bytes.indexOf(0, offset)\n    if (end === -1) return undefined\n    const record = decoder.decode(bytes.subarray(offset, end))\n    offset = end + 1\n    if (record === \"E\") break\n    const kind = record.slice(0, 1)\n    if (!kinds.has(kind)) return undefined\n    const entry = record.slice(1)\n    listed.set(entry, kind as Kind)\n    if (entry === root) continue\n    const parent = path.dirname(entry)\n    const siblings = children.get(parent)\n    if (siblings === undefined) children.set(parent, [path.basename(entry)])\n    else siblings.push(path.basename(entry))\n  }\n  const ignores = Tar.files(bytes.subarray(offset))\n  return ignores === undefined ? undefined : { kinds: listed, children, contents: absolute(ignores) }\n}\n\nconst refusal = (tag: PlatformError.SystemErrorTag, method: string, path: string): PlatformError.PlatformError =>\n  PlatformError.systemError({ _tag: tag, module: \"FileSystem\", method, pathOrDescriptor: path })\n\n/** What `stat` says each kind is: links resolved, a dangling one absent. */\nconst types: Readonly<Record<Kind, FileSystem.File.Type | undefined>> = {\n  d: \"Directory\",\n  u: \"Directory\",\n  D: \"Directory\",\n  f: \"File\",\n  F: \"File\",\n  o: \"Unknown\",\n  L: undefined\n}\n\nconst info = (type: FileSystem.File.Type, size: number): FileSystem.File.Info => ({\n  type,\n  size: ByteSize.bytes(BigInt(size)),\n  mtime: Option.none(),\n  atime: Option.none(),\n  birthtime: Option.none(),\n  dev: 0,\n  ino: Option.none(),\n  mode: 0,\n  nlink: Option.none(),\n  uid: Option.none(),\n  gid: Option.none(),\n  rdev: Option.none(),\n  blksize: Option.none(),\n  blocks: Option.none()\n})\n\n/**\n * The tree as a read-only `FileSystem`, resolving paths with `path`. A file\n * whose bytes did not come back is one the machine's user could not read,\n * which the in-process peer skips exactly as it skips such a file on a host.\n *\n * @private\n * @since 1.0.0-rc.8\n */\nexport const fileSystem = (tree: Tree, path: Path.Path): FileSystem.FileSystem => {\n  const kindOf = (value: string) => tree.kinds.get(path.resolve(value))\n  const readFile = (value: string) => {\n    const bytes = tree.contents.get(path.resolve(value))\n    if (bytes !== undefined) return Effect.succeed(bytes)\n    const type = types[kindOf(value) ?? \"L\"]\n    return Effect.fail(\n      refusal(type === \"File\" ? \"PermissionDenied\" : type === undefined ? \"NotFound\" : \"BadResource\", \"readFile\", value)\n    )\n  }\n  return FileSystem.makeNoop({\n    stat: (value) => {\n      const type = types[kindOf(value) ?? \"L\"]\n      return type === undefined\n        ? Effect.fail(refusal(\"NotFound\", \"stat\", value))\n        : Effect.succeed(info(type, tree.contents.get(path.resolve(value))?.length ?? 0))\n    },\n    readDirectory: (value) => {\n      const kind = kindOf(value)\n      if (kind === \"d\") return Effect.succeed([...tree.children.get(path.resolve(value)) ?? []])\n      const tag = kind === \"u\" ? \"PermissionDenied\" : kind === undefined || kind === \"L\" ? \"NotFound\" : \"BadResource\"\n      return Effect.fail(refusal(tag, \"readDirectory\", value))\n    },\n    readLink: (value) => {\n      const kind = kindOf(value)\n      return kind === \"D\" || kind === \"F\" || kind === \"L\"\n        ? Effect.succeed(\"\")\n        : Effect.fail(refusal(kind === undefined ? \"NotFound\" : \"BadResource\", \"readLink\", value))\n    },\n    readFile,\n    readFileString: (value) => Effect.map(readFile(value), (bytes) => new TextDecoder().decode(bytes)),\n    stream: (value) => Stream.fromEffect(readFile(value))\n  })\n}\n"]}

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

@@ -0,0 +1,63 @@
+/**
+ * The failure constructors and the literal escape both Search peers share.
+ *
+ * The validation and matching rules themselves are public, in
+ * `../SearchContract.ts`, because an external peer has to build on them. What
+ * is left here is what an external peer never calls: the three `StdError`
+ * shapes the contract fails with, the root-failure mapping, and the regex escape a fixed-string search
+ * applies before compiling.
+ *
+ * @since 1.0.0
+ */
+import type * as PlatformError from "effect/PlatformError";
+import * as StdError from "../StdError.ts";
+/**
+ * Constructs the common unsupported-pattern failure.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare const invalidPattern: (pattern: string, detail: string) => StdError.StdError;
+/**
+ * How every rejection {@link invalidPattern} writes begins.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare const rejectionPrefix = "Unsupported ripgrep pattern ";
+/**
+ * Constructs the common invalid-options failure.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare const invalidInput: (detail: string) => StdError.StdError;
+/**
+ * Constructs the common missing-root failure.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare const notFound: (path: string) => StdError.StdError;
+/**
+ * Maps a failure to inspect the search root onto the contract's failures.
+ *
+ * Only a root that does not exist is `not_found`. Every other reason a stat
+ * or listing can fail (a guarded host that fails closed, a permission the
+ * process lacks, an I/O error) is a host operation failing, and it is
+ * reported as `command_failed` with the platform's own message, so the
+ * caller reads the real cause instead of a missing-path claim about a path
+ * that exists.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare const rootFailure: (path: string, error: PlatformError.PlatformError) => StdError.StdError;
+/**
+ * Escapes literal text for JavaScript regular expressions.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare const escapeRegex: (value: string) => string;
+//# sourceMappingURL=SearchContract.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SearchContract.d.ts","sourceRoot":"","sources":["../../../src/internal/SearchContract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,KAAK,aAAa,MAAM,sBAAsB,CAAA;AAC1D,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAA;AAE1C;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,SAAS,MAAM,EAAE,QAAQ,MAAM,KAAG,QAAQ,CAAC,QACgC,CAAA;AAE1G;;;;;GAKG;AACH,eAAO,MAAM,eAAe,iCAAiC,CAAA;AAE7D;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,MAAM,KAAG,QAAQ,CAAC,QAC0C,CAAA;AAEjG;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,GAAI,MAAM,MAAM,KAAG,QAAQ,CAAC,QACuC,CAAA;AAExF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,EAAE,OAAO,aAAa,CAAC,aAAa,KAAG,QAAQ,CAAC,QAKyB,CAAA;AAEjH;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,MAAM,KAAG,MAAsD,CAAA"}

package/dist/esm/internal/SearchContract.js

@@ -0,0 +1,66 @@
+/**
+ * The failure constructors and the literal escape both Search peers share.
+ *
+ * The validation and matching rules themselves are public, in
+ * `../SearchContract.ts`, because an external peer has to build on them. What
+ * is left here is what an external peer never calls: the three `StdError`
+ * shapes the contract fails with, the root-failure mapping, and the regex escape a fixed-string search
+ * applies before compiling.
+ *
+ * @since 1.0.0
+ */
+import * as StdError from "../StdError.js";
+/**
+ * Constructs the common unsupported-pattern failure.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export const invalidPattern = (pattern, detail) => new StdError.StdError({ code: "invalid_pattern", message: `${rejectionPrefix}"${pattern}": ${detail}` });
+/**
+ * How every rejection {@link invalidPattern} writes begins.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export const rejectionPrefix = "Unsupported ripgrep pattern ";
+/**
+ * Constructs the common invalid-options failure.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export const invalidInput = (detail) => new StdError.StdError({ code: "invalid_input", message: `Invalid ripgrep options: ${detail}` });
+/**
+ * Constructs the common missing-root failure.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export const notFound = (path) => new StdError.StdError({ code: "not_found", message: `Path not found: ${path}`, path });
+/**
+ * Maps a failure to inspect the search root onto the contract's failures.
+ *
+ * Only a root that does not exist is `not_found`. Every other reason a stat
+ * or listing can fail (a guarded host that fails closed, a permission the
+ * process lacks, an I/O error) is a host operation failing, and it is
+ * reported as `command_failed` with the platform's own message, so the
+ * caller reads the real cause instead of a missing-path claim about a path
+ * that exists.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export const rootFailure = (path, error) => error.reason._tag === "NotFound"
+    ? notFound(path)
+    : error.reason._tag === "PermissionDenied"
+        ? new StdError.StdError({ code: "permission_denied", message: `Cannot search ${path}: ${error.message}`, path })
+        : new StdError.StdError({ code: "command_failed", message: `Cannot search ${path}: ${error.message}`, path });
+/**
+ * Escapes literal text for JavaScript regular expressions.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export const escapeRegex = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+//# sourceMappingURL=SearchContract.js.map

package/dist/esm/internal/SearchContract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SearchContract.js","sourceRoot":"","sources":["../../../src/internal/SearchContract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAA;AAE1C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,OAAe,EAAE,MAAc,EAAqB,EAAE,CACnF,IAAI,QAAQ,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,GAAG,eAAe,IAAI,OAAO,MAAM,MAAM,EAAE,EAAE,CAAC,CAAA;AAE1G;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,8BAA8B,CAAA;AAE7D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,MAAc,EAAqB,EAAE,CAChE,IAAI,QAAQ,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,4BAA4B,MAAM,EAAE,EAAE,CAAC,CAAA;AAEjG;;;;;GAKG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,IAAY,EAAqB,EAAE,CAC1D,IAAI,QAAQ,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,mBAAmB,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,CAAA;AAExF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,IAAY,EAAE,KAAkC,EAAqB,EAAE,CACjG,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,UAAU;IAC9B,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC;IAChB,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,kBAAkB;QAC1C,CAAC,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,mBAAmB,EAAE,OAAO,EAAE,iBAAiB,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC;QAChH,CAAC,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,iBAAiB,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC,CAAA;AAEjH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,KAAa,EAAU,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAA","sourcesContent":["/**\n * The failure constructors and the literal escape both Search peers share.\n *\n * The validation and matching rules themselves are public, in\n * `../SearchContract.ts`, because an external peer has to build on them. What\n * is left here is what an external peer never calls: the three `StdError`\n * shapes the contract fails with, the root-failure mapping, and the regex escape a fixed-string search\n * applies before compiling.\n *\n * @since 1.0.0\n */\n\nimport type * as PlatformError from \"effect/PlatformError\"\nimport * as StdError from \"../StdError.ts\"\n\n/**\n * Constructs the common unsupported-pattern failure.\n *\n * @private\n * @since 1.0.0\n */\nexport const invalidPattern = (pattern: string, detail: string): StdError.StdError =>\n  new StdError.StdError({ code: \"invalid_pattern\", message: `${rejectionPrefix}\"${pattern}\": ${detail}` })\n\n/**\n * How every rejection {@link invalidPattern} writes begins.\n *\n * @private\n * @since 1.0.0\n */\nexport const rejectionPrefix = \"Unsupported ripgrep pattern \"\n\n/**\n * Constructs the common invalid-options failure.\n *\n * @private\n * @since 1.0.0\n */\nexport const invalidInput = (detail: string): StdError.StdError =>\n  new StdError.StdError({ code: \"invalid_input\", message: `Invalid ripgrep options: ${detail}` })\n\n/**\n * Constructs the common missing-root failure.\n *\n * @private\n * @since 1.0.0\n */\nexport const notFound = (path: string): StdError.StdError =>\n  new StdError.StdError({ code: \"not_found\", message: `Path not found: ${path}`, path })\n\n/**\n * Maps a failure to inspect the search root onto the contract's failures.\n *\n * Only a root that does not exist is `not_found`. Every other reason a stat\n * or listing can fail (a guarded host that fails closed, a permission the\n * process lacks, an I/O error) is a host operation failing, and it is\n * reported as `command_failed` with the platform's own message, so the\n * caller reads the real cause instead of a missing-path claim about a path\n * that exists.\n *\n * @private\n * @since 1.0.0\n */\nexport const rootFailure = (path: string, error: PlatformError.PlatformError): StdError.StdError =>\n  error.reason._tag === \"NotFound\"\n    ? notFound(path)\n    : error.reason._tag === \"PermissionDenied\"\n    ? new StdError.StdError({ code: \"permission_denied\", message: `Cannot search ${path}: ${error.message}`, path })\n    : new StdError.StdError({ code: \"command_failed\", message: `Cannot search ${path}: ${error.message}`, path })\n\n/**\n * Escapes literal text for JavaScript regular expressions.\n *\n * @private\n * @since 1.0.0\n */\nexport const escapeRegex = (value: string): string => value.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\")\n"]}

package/dist/esm/internal/Symbols.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The definition a line sits inside, read off the file's own shape.
+ *
+ * A search hit is a line number, and a line number is not a read window. Agents
+ * guess one: `offset: line - 10, limit: 40`, which lands short (astropy-15569
+ * missed `get_lookup` by one line and probed the wrong binding) or long (six
+ * blind-offset reads on sympy-13878). The enclosing definition is the window the
+ * hit actually belongs to, and for indentation- and brace-structured source it
+ * is derivable from the text already in hand.
+ *
+ * This is a heuristic and reports only what it can see plainly: a declaration
+ * keyword, a name, and the block that keyword opens. When the shape is not
+ * plain — a match at top level, a language this table does not name, a
+ * declaration split across lines — it answers `undefined` rather than guessing,
+ * because a wrong window is worse than none.
+ *
+ * @since 1.0.0
+ */
+/**
+ * The definition enclosing a line.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Symbol {
+    readonly kind: string;
+    readonly name: string;
+    readonly startLine: number;
+    readonly endLine: number;
+}
+/**
+ * The definition enclosing a 1-based line, or `undefined` when there is none to
+ * read plainly.
+ *
+ * @category navigation
+ * @since 1.0.0
+ */
+export declare const enclosing: (lines: ReadonlyArray<string>, line: number) => Symbol | undefined;
+//# sourceMappingURL=Symbols.d.ts.map

package/dist/esm/internal/Symbols.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Symbols.d.ts","sourceRoot":"","sources":["../../../src/internal/Symbols.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAgBD;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM,MAAM,KAAG,MAAM,GAAG,SAkC/E,CAAA"}

package/dist/esm/internal/Symbols.js

@@ -0,0 +1,79 @@
+/**
+ * The definition a line sits inside, read off the file's own shape.
+ *
+ * A search hit is a line number, and a line number is not a read window. Agents
+ * guess one: `offset: line - 10, limit: 40`, which lands short (astropy-15569
+ * missed `get_lookup` by one line and probed the wrong binding) or long (six
+ * blind-offset reads on sympy-13878). The enclosing definition is the window the
+ * hit actually belongs to, and for indentation- and brace-structured source it
+ * is derivable from the text already in hand.
+ *
+ * This is a heuristic and reports only what it can see plainly: a declaration
+ * keyword, a name, and the block that keyword opens. When the shape is not
+ * plain — a match at top level, a language this table does not name, a
+ * declaration split across lines — it answers `undefined` rather than guessing,
+ * because a wrong window is worse than none.
+ *
+ * @since 1.0.0
+ */
+/**
+ * Declaration keywords this heuristic recognises across the languages the
+ * standard flows meet. Modifiers before the keyword are skipped, the name after
+ * it is captured, and everything else is left alone.
+ */
+const declaration = /^([ \t]*)(?:(?:async|export|default|public|private|protected|internal|static|final|abstract|open|pub(?:\([^)]*\))?|unsafe|const|declare)[ \t]+)*(def|class|function|fn|func|struct|impl|interface|trait|enum|module|namespace|type|sub|method)[ \t]+([A-Za-z_$][A-Za-z0-9_$]*)/;
+const closer = /^[ \t]*[)}\]]/;
+const indentOf = (line) => /^[ \t]*/.exec(line)[0].length;
+const blank = (line) => line.trim() === "";
+/**
+ * The definition enclosing a 1-based line, or `undefined` when there is none to
+ * read plainly.
+ *
+ * @category navigation
+ * @since 1.0.0
+ */
+export const enclosing = (lines, line) => {
+    const index = line - 1;
+    if (index < 0 || index >= lines.length)
+        return undefined;
+    // A blank match line has no indentation of its own; the nearest text above it
+    // does, and that is the block the blank line belongs to.
+    let reference = index;
+    while (reference > 0 && blank(lines[reference]))
+        reference--;
+    const indent = indentOf(lines[reference]);
+    let start = -1;
+    let parsed = null;
+    for (let candidate = index; candidate >= 0; candidate--) {
+        const text = lines[candidate];
+        if (blank(text))
+            continue;
+        const found = declaration.exec(text);
+        if (found === null)
+            continue;
+        if (candidate !== index && indentOf(text) >= indent)
+            continue;
+        start = candidate;
+        parsed = found;
+        break;
+    }
+    if (parsed === null)
+        return undefined;
+    const opening = indentOf(lines[start]);
+    let end = lines.length - 1;
+    for (let candidate = start + 1; candidate < lines.length; candidate++) {
+        const text = lines[candidate];
+        if (blank(text))
+            continue;
+        if (indentOf(text) > opening)
+            continue;
+        // A brace language closes the block at the declaration's own indentation,
+        // and that closing line is part of the definition rather than what follows.
+        end = closer.test(text) ? candidate : candidate - 1;
+        break;
+    }
+    while (end > start && blank(lines[end]))
+        end--;
+    return { kind: parsed[2], name: parsed[3], startLine: start + 1, endLine: end + 1 };
+};
+//# sourceMappingURL=Symbols.js.map

package/dist/esm/internal/Symbols.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Symbols.js","sourceRoot":"","sources":["../../../src/internal/Symbols.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAeH;;;;GAIG;AACH,MAAM,WAAW,GACf,gRAAgR,CAAA;AAElR,MAAM,MAAM,GAAG,eAAe,CAAA;AAE9B,MAAM,QAAQ,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAA;AAE1E,MAAM,KAAK,GAAG,CAAC,IAAY,EAAW,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,CAAA;AAE3D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,KAA4B,EAAE,IAAY,EAAsB,EAAE;IAC1F,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,CAAA;IACtB,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,IAAI,KAAK,CAAC,MAAM;QAAE,OAAO,SAAS,CAAA;IACxD,8EAA8E;IAC9E,yDAAyD;IACzD,IAAI,SAAS,GAAG,KAAK,CAAA;IACrB,OAAO,SAAS,GAAG,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,SAAS,CAAE,CAAC;QAAE,SAAS,EAAE,CAAA;IAC7D,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAE,CAAC,CAAA;IAC1C,IAAI,KAAK,GAAG,CAAC,CAAC,CAAA;IACd,IAAI,MAAM,GAA2B,IAAI,CAAA;IACzC,KAAK,IAAI,SAAS,GAAG,KAAK,EAAE,SAAS,IAAI,CAAC,EAAE,SAAS,EAAE,EAAE,CAAC;QACxD,MAAM,IAAI,GAAG,KAAK,CAAC,SAAS,CAAE,CAAA;QAC9B,IAAI,KAAK,CAAC,IAAI,CAAC;YAAE,SAAQ;QACzB,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACpC,IAAI,KAAK,KAAK,IAAI;YAAE,SAAQ;QAC5B,IAAI,SAAS,KAAK,KAAK,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,MAAM;YAAE,SAAQ;QAC7D,KAAK,GAAG,SAAS,CAAA;QACjB,MAAM,GAAG,KAAK,CAAA;QACd,MAAK;IACP,CAAC;IACD,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,SAAS,CAAA;IACrC,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAE,CAAC,CAAA;IACvC,IAAI,GAAG,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAA;IAC1B,KAAK,IAAI,SAAS,GAAG,KAAK,GAAG,CAAC,EAAE,SAAS,GAAG,KAAK,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,CAAC;QACtE,MAAM,IAAI,GAAG,KAAK,CAAC,SAAS,CAAE,CAAA;QAC9B,IAAI,KAAK,CAAC,IAAI,CAAC;YAAE,SAAQ;QACzB,IAAI,QAAQ,CAAC,IAAI,CAAC,GAAG,OAAO;YAAE,SAAQ;QACtC,0EAA0E;QAC1E,4EAA4E;QAC5E,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAA;QACnD,MAAK;IACP,CAAC;IACD,OAAO,GAAG,GAAG,KAAK,IAAI,KAAK,CAAC,KAAK,CAAC,GAAG,CAAE,CAAC;QAAE,GAAG,EAAE,CAAA;IAC/C,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAE,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAE,EAAE,SAAS,EAAE,KAAK,GAAG,CAAC,EAAE,OAAO,EAAE,GAAG,GAAG,CAAC,EAAE,CAAA;AACvF,CAAC,CAAA","sourcesContent":["/**\n * The definition a line sits inside, read off the file's own shape.\n *\n * A search hit is a line number, and a line number is not a read window. Agents\n * guess one: `offset: line - 10, limit: 40`, which lands short (astropy-15569\n * missed `get_lookup` by one line and probed the wrong binding) or long (six\n * blind-offset reads on sympy-13878). The enclosing definition is the window the\n * hit actually belongs to, and for indentation- and brace-structured source it\n * is derivable from the text already in hand.\n *\n * This is a heuristic and reports only what it can see plainly: a declaration\n * keyword, a name, and the block that keyword opens. When the shape is not\n * plain — a match at top level, a language this table does not name, a\n * declaration split across lines — it answers `undefined` rather than guessing,\n * because a wrong window is worse than none.\n *\n * @since 1.0.0\n */\n\n/**\n * The definition enclosing a line.\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 * Declaration keywords this heuristic recognises across the languages the\n * standard flows meet. Modifiers before the keyword are skipped, the name after\n * it is captured, and everything else is left alone.\n */\nconst declaration =\n  /^([ \\t]*)(?:(?:async|export|default|public|private|protected|internal|static|final|abstract|open|pub(?:\\([^)]*\\))?|unsafe|const|declare)[ \\t]+)*(def|class|function|fn|func|struct|impl|interface|trait|enum|module|namespace|type|sub|method)[ \\t]+([A-Za-z_$][A-Za-z0-9_$]*)/\n\nconst closer = /^[ \\t]*[)}\\]]/\n\nconst indentOf = (line: string): number => /^[ \\t]*/.exec(line)![0].length\n\nconst blank = (line: string): boolean => line.trim() === \"\"\n\n/**\n * The definition enclosing a 1-based line, or `undefined` when there is none to\n * read plainly.\n *\n * @category navigation\n * @since 1.0.0\n */\nexport const enclosing = (lines: ReadonlyArray<string>, line: number): Symbol | undefined => {\n  const index = line - 1\n  if (index < 0 || index >= lines.length) return undefined\n  // A blank match line has no indentation of its own; the nearest text above it\n  // does, and that is the block the blank line belongs to.\n  let reference = index\n  while (reference > 0 && blank(lines[reference]!)) reference--\n  const indent = indentOf(lines[reference]!)\n  let start = -1\n  let parsed: RegExpExecArray | null = null\n  for (let candidate = index; candidate >= 0; candidate--) {\n    const text = lines[candidate]!\n    if (blank(text)) continue\n    const found = declaration.exec(text)\n    if (found === null) continue\n    if (candidate !== index && indentOf(text) >= indent) continue\n    start = candidate\n    parsed = found\n    break\n  }\n  if (parsed === null) return undefined\n  const opening = indentOf(lines[start]!)\n  let end = lines.length - 1\n  for (let candidate = start + 1; candidate < lines.length; candidate++) {\n    const text = lines[candidate]!\n    if (blank(text)) continue\n    if (indentOf(text) > opening) continue\n    // A brace language closes the block at the declaration's own indentation,\n    // and that closing line is part of the definition rather than what follows.\n    end = closer.test(text) ? candidate : candidate - 1\n    break\n  }\n  while (end > start && blank(lines[end]!)) end--\n  return { kind: parsed[2]!, name: parsed[3]!, startLine: start + 1, endLine: end + 1 }\n}\n"]}

package/dist/esm/internal/Tar.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The regular files of a tar stream.
+ *
+ * `RemoteSearch` brings a machine's files back with its own `tar`, because
+ * every image ships one and it frames each file with its name and size. GNU
+ * and BusyBox `tar` write GNU long names, `bsdtar` writes POSIX extended
+ * headers, and `xargs` may start `tar` more than once, so the stream can hold
+ * several archives one after another. This reads all of them.
+ *
+ * @since 1.0.0-rc.8
+ */
+/**
+ * Every regular file the stream holds, by member name, or `undefined` when
+ * the stream is not whole tar archives: a header whose checksum does not
+ * hold, a member cut short, or a last archive with no end. A `tar` that
+ * stopped between two members wrote no end, so its missing files are not
+ * mistaken for files it could not read.
+ *
+ * @private
+ * @since 1.0.0-rc.8
+ */
+export declare const files: (stream: Uint8Array) => ReadonlyMap<string, Uint8Array> | undefined;
+//# sourceMappingURL=Tar.d.ts.map

package/dist/esm/internal/Tar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tar.d.ts","sourceRoot":"","sources":["../../../src/internal/Tar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAsCH;;;;;;;;;GASG;AACH,eAAO,MAAM,KAAK,GAAI,QAAQ,UAAU,KAAG,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,SAoC5E,CAAA"}

package/dist/esm/internal/Tar.js

@@ -0,0 +1,97 @@
+/**
+ * The regular files of a tar stream.
+ *
+ * `RemoteSearch` brings a machine's files back with its own `tar`, because
+ * every image ships one and it frames each file with its name and size. GNU
+ * and BusyBox `tar` write GNU long names, `bsdtar` writes POSIX extended
+ * headers, and `xargs` may start `tar` more than once, so the stream can hold
+ * several archives one after another. This reads all of them.
+ *
+ * @since 1.0.0-rc.8
+ */
+const decoder = new TextDecoder();
+/** Bytes up to the first NUL, as text. */
+const text = (bytes) => {
+    const end = bytes.indexOf(0);
+    return decoder.decode(end === -1 ? bytes : bytes.subarray(0, end));
+};
+/** An octal header field, or `undefined` when it holds anything else. */
+const octal = (bytes) => {
+    const digits = text(bytes).trim();
+    return /^[0-7]+$/.test(digits) ? Number.parseInt(digits, 8) : undefined;
+};
+/** The header's checksum, computed with the checksum field read as spaces. */
+const checksum = (header) => {
+    let sum = 0;
+    for (let index = 0; index < 512; index++)
+        sum += index >= 148 && index < 156 ? 32 : header[index];
+    return sum;
+};
+/** The `path` record of a POSIX extended header: `<length> <key>=<value>\n` records. */
+const paxPath = (data) => {
+    let offset = 0;
+    let path;
+    while (offset < data.length) {
+        const space = data.indexOf(32, offset);
+        const length = space === -1 ? Number.NaN : Number(decoder.decode(data.subarray(offset, space)));
+        if (!Number.isSafeInteger(length) || length <= space - offset || offset + length > data.length)
+            return path;
+        const record = decoder.decode(data.subarray(space + 1, offset + length - 1));
+        if (record.startsWith("path="))
+            path = record.slice("path=".length);
+        offset += length;
+    }
+    return path;
+};
+/**
+ * Every regular file the stream holds, by member name, or `undefined` when
+ * the stream is not whole tar archives: a header whose checksum does not
+ * hold, a member cut short, or a last archive with no end. A `tar` that
+ * stopped between two members wrote no end, so its missing files are not
+ * mistaken for files it could not read.
+ *
+ * @private
+ * @since 1.0.0-rc.8
+ */
+export const files = (stream) => {
+    const found = new Map();
+    let longName;
+    let extended;
+    let ended = true;
+    for (let offset = 0; offset + 512 <= stream.length;) {
+        const header = stream.subarray(offset, offset + 512);
+        offset += 512;
+        // Zero blocks end one archive; `xargs` may have started another.
+        ended = header.every((byte) => byte === 0);
+        if (ended)
+            continue;
+        const size = octal(header.subarray(124, 136));
+        if (size === undefined || octal(header.subarray(148, 156)) !== checksum(header))
+            return undefined;
+        if (offset + size > stream.length)
+            return undefined;
+        const data = stream.subarray(offset, offset + size);
+        offset += Math.ceil(size / 512) * 512;
+        const type = String.fromCharCode(header[156]);
+        if (type === "L") {
+            longName = text(data);
+            continue;
+        }
+        if (type === "x") {
+            extended = paxPath(data) ?? extended;
+            continue;
+        }
+        // A long link name and a global header describe no member of their own.
+        if (type === "K" || type === "g")
+            continue;
+        if (type === "0" || type === "\0" || type === "7") {
+            const prefix = decoder.decode(header.subarray(257, 263)) === "ustar\0" ? text(header.subarray(345, 500)) : "";
+            const short = text(header.subarray(0, 100));
+            found.set(extended ?? longName ?? (prefix === "" ? short : `${prefix}/${short}`), data.slice());
+        }
+        longName = undefined;
+        extended = undefined;
+    }
+    return ended ? found : undefined;
+};
+//# sourceMappingURL=Tar.js.map

package/dist/esm/internal/Tar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tar.js","sourceRoot":"","sources":["../../../src/internal/Tar.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The regular files of a tar stream.\n *\n * `RemoteSearch` brings a machine's files back with its own `tar`, because\n * every image ships one and it frames each file with its name and size. GNU\n * and BusyBox `tar` write GNU long names, `bsdtar` writes POSIX extended\n * headers, and `xargs` may start `tar` more than once, so the stream can hold\n * several archives one after another. This reads all of them.\n *\n * @since 1.0.0-rc.8\n */\n\nconst decoder = new TextDecoder()\n\n/** Bytes up to the first NUL, as text. */\nconst text = (bytes: Uint8Array): string => {\n  const end = bytes.indexOf(0)\n  return decoder.decode(end === -1 ? bytes : bytes.subarray(0, end))\n}\n\n/** An octal header field, or `undefined` when it holds anything else. */\nconst octal = (bytes: Uint8Array): number | undefined => {\n  const digits = text(bytes).trim()\n  return /^[0-7]+$/.test(digits) ? Number.parseInt(digits, 8) : undefined\n}\n\n/** The header's checksum, computed with the checksum field read as spaces. */\nconst checksum = (header: Uint8Array): number => {\n  let sum = 0\n  for (let index = 0; index < 512; index++) sum += index >= 148 && index < 156 ? 32 : header[index]!\n  return sum\n}\n\n/** The `path` record of a POSIX extended header: `<length> <key>=<value>\\n` records. */\nconst paxPath = (data: Uint8Array): string | undefined => {\n  let offset = 0\n  let path: string | undefined\n  while (offset < data.length) {\n    const space = data.indexOf(32, offset)\n    const length = space === -1 ? Number.NaN : Number(decoder.decode(data.subarray(offset, space)))\n    if (!Number.isSafeInteger(length) || length <= space - offset || offset + length > data.length) return path\n    const record = decoder.decode(data.subarray(space + 1, offset + length - 1))\n    if (record.startsWith(\"path=\")) path = record.slice(\"path=\".length)\n    offset += length\n  }\n  return path\n}\n\n/**\n * Every regular file the stream holds, by member name, or `undefined` when\n * the stream is not whole tar archives: a header whose checksum does not\n * hold, a member cut short, or a last archive with no end. A `tar` that\n * stopped between two members wrote no end, so its missing files are not\n * mistaken for files it could not read.\n *\n * @private\n * @since 1.0.0-rc.8\n */\nexport const files = (stream: Uint8Array): ReadonlyMap<string, Uint8Array> | undefined => {\n  const found = new Map<string, Uint8Array>()\n  let longName: string | undefined\n  let extended: string | undefined\n  let ended = true\n  for (let offset = 0; offset + 512 <= stream.length;) {\n    const header = stream.subarray(offset, offset + 512)\n    offset += 512\n    // Zero blocks end one archive; `xargs` may have started another.\n    ended = header.every((byte) => byte === 0)\n    if (ended) continue\n    const size = octal(header.subarray(124, 136))\n    if (size === undefined || octal(header.subarray(148, 156)) !== checksum(header)) return undefined\n    if (offset + size > stream.length) return undefined\n    const data = stream.subarray(offset, offset + size)\n    offset += Math.ceil(size / 512) * 512\n    const type = String.fromCharCode(header[156]!)\n    if (type === \"L\") {\n      longName = text(data)\n      continue\n    }\n    if (type === \"x\") {\n      extended = paxPath(data) ?? extended\n      continue\n    }\n    // A long link name and a global header describe no member of their own.\n    if (type === \"K\" || type === \"g\") continue\n    if (type === \"0\" || type === \"\\0\" || type === \"7\") {\n      const prefix = decoder.decode(header.subarray(257, 263)) === \"ustar\\0\" ? text(header.subarray(345, 500)) : \"\"\n      const short = text(header.subarray(0, 100))\n      found.set(extended ?? longName ?? (prefix === \"\" ? short : `${prefix}/${short}`), data.slice())\n    }\n    longName = undefined\n    extended = undefined\n  }\n  return ended ? found : undefined\n}\n"]}

package/dist/esm/internal/TestReport.d.ts

@@ -0,0 +1,52 @@
+/**
+ * What a test runner said, read out of what it printed.
+ *
+ * A suite's answer is two facts — how many passed, and which ones failed — and
+ * a runner spends twenty to thirty kilobytes of stdout saying them. Paying a
+ * model to read that is the expensive way to learn a number, and the measured
+ * program shows what it costs: sixteen frames on sphinx-8721 existed because a
+ * pre-existing failure was never isolated, and the failure *names* were in the
+ * output all along.
+ *
+ * The parsers below recognise the report shapes the standard runners print.
+ * Precision is the design constraint, exactly as in `Probe`: a reader claims a
+ * complete report only when the runner printed an authoritative completion
+ * statement and the observed outcomes agree with it. Pytest requires a tally,
+ * TAP requires a plan with every planned outcome, and unittest requires its
+ * `Ran` line plus an `OK` or `FAILED` summary. Incomplete captures still return
+ * the outcomes they contain with `parsed: false`. A wrong failure set is worse
+ * than no failure set, because attribution is built on it.
+ *
+ * @since 1.0.0
+ */
+/**
+ * One run's outcome as this module could read it.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Report {
+    readonly passed: number;
+    readonly failed: ReadonlyArray<string>;
+    readonly reportedFailed: number | undefined;
+    readonly parsed: boolean;
+}
+/**
+ * Reads one run's report, or says plainly that it could not.
+ *
+ * @category parsing
+ * @since 1.0.0
+ */
+export declare const parse: (text: string) => Report;
+/**
+ * How two runs of the same command differ, which is the whole of attribution.
+ *
+ * @category parsing
+ * @since 1.0.0
+ */
+export declare const attribute: (current: Report, base: Report) => {
+    readonly introduced: ReadonlyArray<string>;
+    readonly preexisting: ReadonlyArray<string>;
+    readonly fixed: ReadonlyArray<string>;
+} | undefined;
+//# sourceMappingURL=TestReport.d.ts.map

package/dist/esm/internal/TestReport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TestReport.d.ts","sourceRoot":"","sources":["../../../src/internal/TestReport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACtC,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3C,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CACzB;AAiHD;;;;;GAKG;AACH,eAAO,MAAM,KAAK,GAAI,MAAM,MAAM,KAAG,MAiBpC,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,SAAS,GACpB,SAAS,MAAM,EACf,MAAM,MAAM,KACX;IACD,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IAC1C,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IAC3C,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CACtC,GAAG,SASH,CAAA"}