@smthrs/plan 1.0.0-rc.7 → 1.0.0-rc.9

package/dist/esm/FileSet.d.ts

@@ -43,7 +43,6 @@ export type BoundaryMode = typeof BoundaryMode.Type;
  *
  * @category accessors
  * @since 0.1.0
- * @slop
  */
 export declare const canonical: (path: string) => string;
 /**
@@ -59,10 +58,15 @@ export declare const canonical: (path: string) => string;
  * @since 1.0.0-rc.0
  */
 export declare const folded: (path: string) => string;
-/** Workspace-relative glob pattern.
+/**
+ * A non-empty workspace-relative path or pattern.
+ *
+ * Decoding fails with a `SchemaError` when {@link workspaceRelative} refuses
+ * the string. A bare `Pattern` in a declaration names one literal path; only a
+ * {@link Glob} gives `*` and `**` wildcard meaning.
+ *
  * @category schemas
  * @since 0.1.0
- * @slop
  */
 export declare const Pattern: Schema.NonEmptyString;
 /**
@@ -71,44 +75,59 @@ export declare const Pattern: Schema.NonEmptyString;
  * traversal, and the aliasing forms — `.` segments, empty segments — that
  * would let two spellings of one file defeat exact-string overlap detection.
  *
+ * C0 controls and DEL are refused as well.
+ *
  * @category predicates
  * @since 0.1.0
- * @slop
  */
 export declare const workspaceRelative: (pattern: string) => boolean;
-/** Bazel-style file glob.
+/**
+ * A Bazel-style file glob: the paths matching any `include` pattern and no
+ * `exclude` pattern.
+ *
+ * In a pattern, `*` matches within one path segment and a `**` segment
+ * matches zero or more whole segments. A trailing `**` needs its separator,
+ * so `src/**` does not match `src` itself.
+ *
  * @category schemas
  * @since 0.1.0
- * @slop
  */
 export declare const Glob: Schema.TaggedStruct<"Glob", {
     readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
     readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
 }>;
-/** Bazel-style file glob.
+/**
+ * The value form of {@link Glob}.
+ *
  * @category models
  * @since 0.1.0
- * @slop
  */
 export type Glob = typeof Glob.Type;
-/** A directory output captured and replayed as one tree artifact.
+/**
+ * A directory output captured and replayed as one tree artifact.
+ *
+ * It covers `path` and every path beneath it, compared in {@link folded}
+ * form.
+ *
  * @category schemas
  * @since 0.1.0
- * @slop
  */
 export declare const TreeArtifact: Schema.TaggedStruct<"TreeArtifact", {
     readonly path: Schema.NonEmptyString;
 }>;
-/** A directory output captured and replayed as one tree artifact.
+/**
+ * The value form of {@link TreeArtifact}.
+ *
  * @category models
  * @since 0.1.0
- * @slop
  */
 export type TreeArtifact = typeof TreeArtifact.Type;
-/** One leaf of a named filegroup.
+/**
+ * One leaf declaration: a literal path, a {@link Glob}, or a
+ * {@link TreeArtifact}. Write sets and filegroups hold entries.
+ *
  * @category schemas
  * @since 0.1.0
- * @slop
  */
 export declare const Entry: Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
     readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
@@ -116,31 +135,40 @@ export declare const Entry: Schema.Union<readonly [Schema.NonEmptyString, Schema
 }>, Schema.TaggedStruct<"TreeArtifact", {
     readonly path: Schema.NonEmptyString;
 }>]>;
-/** One leaf of a named filegroup.
+/**
+ * The value form of {@link Entry}.
+ *
  * @category models
  * @since 0.1.0
- * @slop
  */
 export type Entry = typeof Entry.Type;
-/** A declaration valid in a read set.
+/**
+ * One leaf declaration valid in a read set: a literal path or a {@link Glob}.
+ * A read set cannot name a {@link TreeArtifact}, which is an output form.
+ *
  * @category schemas
  * @since 0.1.0
- * @slop
  */
 export declare const ReadEntry: Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
     readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
     readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
 }>]>;
-/** A declaration valid in a read set.
+/**
+ * The value form of {@link ReadEntry}.
+ *
  * @category models
  * @since 0.1.0
- * @slop
  */
 export type ReadEntry = typeof ReadEntry.Type;
-/** A named reusable collection expanded before measurement.
+/**
+ * A named, reusable list of {@link Entry} declarations.
+ *
+ * {@link expand} replaces a filegroup with its entries in place before any
+ * overlap check or measurement, so the name never reaches the boundary.
+ * Filegroups do not nest.
+ *
  * @category schemas
  * @since 0.1.0
- * @slop
  */
 export declare const Filegroup: Schema.TaggedStruct<"Filegroup", {
     readonly name: Schema.NonEmptyString;
@@ -151,16 +179,19 @@ export declare const Filegroup: Schema.TaggedStruct<"Filegroup", {
         readonly path: Schema.NonEmptyString;
     }>]>>;
 }>;
-/** A named reusable collection expanded before measurement.
+/**
+ * The value form of {@link Filegroup}.
+ *
  * @category models
  * @since 0.1.0
- * @slop
  */
 export type Filegroup = typeof Filegroup.Type;
-/** A named read-only collection.
+/**
+ * A {@link Filegroup} restricted to {@link ReadEntry} declarations, for use
+ * in a read set. It shares the `"Filegroup"` tag.
+ *
  * @category schemas
  * @since 0.1.0
- * @slop
  */
 export declare const ReadFilegroup: Schema.TaggedStruct<"Filegroup", {
     readonly name: Schema.NonEmptyString;
@@ -169,16 +200,19 @@ export declare const ReadFilegroup: Schema.TaggedStruct<"Filegroup", {
         readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
     }>]>>;
 }>;
-/** A named read-only collection.
+/**
+ * The value form of {@link ReadFilegroup}.
+ *
  * @category models
  * @since 0.1.0
- * @slop
  */
 export type ReadFilegroup = typeof ReadFilegroup.Type;
-/** Any declaration accepted by a plan effect set.
+/**
+ * Any declaration accepted in a write set: an {@link Entry} or a
+ * {@link Filegroup}.
+ *
  * @category schemas
  * @since 0.1.0
- * @slop
  */
 export declare const Declaration: Schema.Union<readonly [Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
     readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
@@ -194,16 +228,19 @@ export declare const Declaration: Schema.Union<readonly [Schema.Union<readonly [
         readonly path: Schema.NonEmptyString;
     }>]>>;
 }>]>;
-/** Any declaration accepted by a plan effect set.
+/**
+ * The value form of {@link Declaration}.
+ *
  * @category models
  * @since 0.1.0
- * @slop
  */
 export type Declaration = typeof Declaration.Type;
-/** Any declaration accepted by a plan read set.
+/**
+ * Any declaration accepted in a read set: a {@link ReadEntry} or a
+ * {@link ReadFilegroup}.
+ *
  * @category schemas
  * @since 0.1.0
- * @slop
  */
 export declare const ReadDeclaration: Schema.Union<readonly [Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
     readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
@@ -215,52 +252,86 @@ export declare const ReadDeclaration: Schema.Union<readonly [Schema.Union<readon
         readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
     }>]>>;
 }>]>;
-/** Any declaration accepted by a plan read set.
+/**
+ * The value form of {@link ReadDeclaration}.
+ *
  * @category models
  * @since 0.1.0
- * @slop
  */
 export type ReadDeclaration = typeof ReadDeclaration.Type;
-/** Creates a named filegroup.
+/**
+ * Creates a {@link Filegroup}. It does not validate `name` or `entries`;
+ * decode through {@link Filegroup} when the input is untrusted.
+ *
+ * @param name - The filegroup name.
+ * @param entries - The entries the filegroup expands to, in order.
+ * @returns The filegroup value.
  * @category constructors
  * @since 0.1.0
- * @slop
  */
 export declare const makeFilegroup: (name: string, entries: ReadonlyArray<Entry>) => Filegroup;
-/** Expands filegroups deterministically, preserving declaration order.
+/**
+ * Replaces each {@link Filegroup} with its entries, in place, and keeps every
+ * other declaration as it is. Order is preserved and duplicates are kept.
+ *
+ * @param declarations - Write-set declarations, possibly holding filegroups.
+ * @returns The flat list of entries.
  * @category accessors
  * @since 0.1.0
- * @slop
  */
 export declare const expand: (declarations: ReadonlyArray<Declaration>) => ReadonlyArray<Entry>;
-/** Expands read filegroups deterministically, preserving declaration order.
+/**
+ * {@link expand} for read sets: replaces each {@link ReadFilegroup} with its
+ * entries, in place, preserving order and duplicates.
+ *
+ * @param declarations - Read-set declarations, possibly holding filegroups.
+ * @returns The flat list of read entries.
  * @category accessors
  * @since 0.1.0
- * @slop
  */
 export declare const expandReads: (declarations: ReadonlyArray<ReadDeclaration>) => ReadonlyArray<ReadEntry>;
-/** Whether a value is a glob declaration.
+/**
+ * Whether a value carries the `"Glob"` tag. It checks only the tag, not the
+ * patterns.
+ *
+ * @param value - Any value.
+ * @returns `true` for an object whose `_tag` is `"Glob"`.
  * @category guards
  * @since 0.1.0
- * @slop
  */
 export declare const isGlob: (value: unknown) => value is Glob;
-/** Whether a value is a tree artifact declaration.
+/**
+ * Whether a value carries the `"TreeArtifact"` tag. It checks only the tag,
+ * not the path.
+ *
+ * @param value - Any value.
+ * @returns `true` for an object whose `_tag` is `"TreeArtifact"`.
  * @category guards
  * @since 0.1.0
- * @slop
  */
 export declare const isTreeArtifact: (value: unknown) => value is TreeArtifact;
-/** Tests one workspace-relative path against one Bazel-style pattern.
+/**
+ * Whether `path` matches `pattern` under {@link Glob} wildcard rules.
+ *
+ * The pattern is read in its {@link canonical} spelling; the path is matched
+ * as given, case-sensitively, with `/` as its only separator.
+ *
+ * @param pattern - A Bazel-style pattern such as `src/*.ts` or `docs/**`.
+ * @param path - A workspace-relative path.
+ * @returns `true` when the path matches.
  * @category predicates
  * @since 0.1.0
- * @slop
  */
 export declare const matchesPattern: (pattern: string, path: string) => boolean;
-/** Tests one file path against a glob, including exclusions.
+/**
+ * Whether `path` matches some `include` pattern of `glob` and no `exclude`
+ * pattern, each tested with {@link matchesPattern}. Case-sensitive.
+ *
+ * @param glob - The glob to test.
+ * @param path - A workspace-relative path.
+ * @returns `true` when the glob selects the path.
  * @category predicates
  * @since 0.1.0
- * @slop
  */
 export declare const matchesGlob: (glob: Glob, path: string) => boolean;
 /**
@@ -282,7 +353,6 @@ export declare const matchesGlob: (glob: Glob, path: string) => boolean;
  *
  * @category predicates
  * @since 0.1.0
- * @slop
  */
 export declare const overlaps: (left: Entry, right: Entry) => boolean;
 //# sourceMappingURL=FileSet.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"FileSet.d.ts","sourceRoot":"","sources":["../../src/FileSet.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"FileSet.d.ts","sourceRoot":"","sources":["../../src/FileSet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,YAAY,gDAAwC,CAAA;AAEjE;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC,IAAI,CAAA;AAEnD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,SAAS,GAAI,MAAM,MAAM,KAAG,MAAqD,CAAA;AAE9F;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,MAAM,GAAI,MAAM,MAAM,KAAG,MAAwD,CAAA;AAE9F;;;;;;;;;GASG;AACH,eAAO,MAAM,OAAO,uBAKnB,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAAI,SAAS,MAAM,KAAG,OAUnD,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,IAAI;;;EAGf,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,IAAI,CAAA;AAEnC;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY;;EAEvB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC,IAAI,CAAA;AAEnD;;;;;;GAMG;AACH,eAAO,MAAM,KAAK;;;;;IAA8C,CAAA;AAEhE;;;;;GAKG;AACH,MAAM,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,IAAI,CAAA;AAErC;;;;;;GAMG;AACH,eAAO,MAAM,SAAS;;;IAAgC,CAAA;AAEtD;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,SAAS,CAAC,IAAI,CAAA;AAE7C;;;;;;;;;GASG;AACH,eAAO,MAAM,SAAS;;;;;;;;EAGpB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,SAAS,CAAC,IAAI,CAAA;AAE7C;;;;;;GAMG;AACH,eAAO,MAAM,aAAa;;;;;;EAGxB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC,IAAI,CAAA;AAErD;;;;;;GAMG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;IAAmC,CAAA;AAE3D;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC,IAAI,CAAA;AAEjD;;;;;;GAMG;AACH,eAAO,MAAM,eAAe;;;;;;;;;IAA2C,CAAA;AAEvE;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAC,IAAI,CAAA;AAEzD;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,MAAM,EAAE,SAAS,aAAa,CAAC,KAAK,CAAC,KAAG,SAI1E,CAAA;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,MAAM,GAAI,cAAc,aAAa,CAAC,WAAW,CAAC,KAAG,aAAa,CAAC,KAAK,CAGlF,CAAA;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,GAAI,cAAc,aAAa,CAAC,eAAe,CAAC,KAAG,aAAa,CAAC,SAAS,CAG/F,CAAA;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,MAAM,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,IACwC,CAAA;AAEzF;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,YACwC,CAAA;AA4EjG;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,GAAI,SAAS,MAAM,EAAE,MAAM,MAAM,KAAG,OAAwC,CAAA;AAEvG;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,IAAI,EAAE,MAAM,MAAM,KAAG,OAEiB,CAAA;AAexE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,QAAQ,GAAI,MAAM,KAAK,EAAE,OAAO,KAAK,KAAG,OAepD,CAAA"}

package/dist/esm/FileSet.js

@@ -36,7 +36,6 @@ export const BoundaryMode = Schema.Literals(["hard", "expected"]);
  *
  * @category accessors
  * @since 0.1.0
- * @slop
  */
 export const canonical = (path) => path.replaceAll("\\", "/").normalize("NFC");
 /**
@@ -52,10 +51,15 @@ export const canonical = (path) => path.replaceAll("\\", "/").normalize("NFC");
  * @since 1.0.0-rc.0
  */
 export const folded = (path) => canonical(path).toUpperCase().normalize("NFC");
-/** Workspace-relative glob pattern.
+/**
+ * A non-empty workspace-relative path or pattern.
+ *
+ * Decoding fails with a `SchemaError` when {@link workspaceRelative} refuses
+ * the string. A bare `Pattern` in a declaration names one literal path; only a
+ * {@link Glob} gives `*` and `**` wildcard meaning.
+ *
  * @category schemas
  * @since 0.1.0
- * @slop
  */
 export const Pattern = Schema.NonEmptyString.check(Schema.makeFilter((pattern) => workspaceRelative(pattern) || "file patterns must be workspace-relative and cannot traverse upward", { title: "workspaceRelativePattern" }));
 /**
@@ -64,9 +68,10 @@ export const Pattern = Schema.NonEmptyString.check(Schema.makeFilter((pattern) =
  * traversal, and the aliasing forms — `.` segments, empty segments — that
  * would let two spellings of one file defeat exact-string overlap detection.
  *
+ * C0 controls and DEL are refused as well.
+ *
  * @category predicates
  * @since 0.1.0
- * @slop
  */
 export const workspaceRelative = (pattern) => {
     for (let index = 0; index < pattern.length; index++) {
@@ -82,97 +87,143 @@ export const workspaceRelative = (pattern) => {
         return false;
     return segments.every((segment) => segment !== ".." && segment !== "." && segment !== "");
 };
-/** Bazel-style file glob.
+/**
+ * A Bazel-style file glob: the paths matching any `include` pattern and no
+ * `exclude` pattern.
+ *
+ * In a pattern, `*` matches within one path segment and a `**` segment
+ * matches zero or more whole segments. A trailing `**` needs its separator,
+ * so `src/**` does not match `src` itself.
+ *
  * @category schemas
  * @since 0.1.0
- * @slop
  */
 export const Glob = Schema.TaggedStruct("Glob", {
     include: Schema.NonEmptyArray(Pattern),
     exclude: Schema.optional(Schema.Array(Pattern))
 });
-/** A directory output captured and replayed as one tree artifact.
+/**
+ * A directory output captured and replayed as one tree artifact.
+ *
+ * It covers `path` and every path beneath it, compared in {@link folded}
+ * form.
+ *
  * @category schemas
  * @since 0.1.0
- * @slop
  */
 export const TreeArtifact = Schema.TaggedStruct("TreeArtifact", {
     path: Pattern
 });
-/** One leaf of a named filegroup.
+/**
+ * One leaf declaration: a literal path, a {@link Glob}, or a
+ * {@link TreeArtifact}. Write sets and filegroups hold entries.
+ *
  * @category schemas
  * @since 0.1.0
- * @slop
  */
 export const Entry = Schema.Union([Pattern, Glob, TreeArtifact]);
-/** A declaration valid in a read set.
+/**
+ * One leaf declaration valid in a read set: a literal path or a {@link Glob}.
+ * A read set cannot name a {@link TreeArtifact}, which is an output form.
+ *
  * @category schemas
  * @since 0.1.0
- * @slop
  */
 export const ReadEntry = Schema.Union([Pattern, Glob]);
-/** A named reusable collection expanded before measurement.
+/**
+ * A named, reusable list of {@link Entry} declarations.
+ *
+ * {@link expand} replaces a filegroup with its entries in place before any
+ * overlap check or measurement, so the name never reaches the boundary.
+ * Filegroups do not nest.
+ *
  * @category schemas
  * @since 0.1.0
- * @slop
  */
 export const Filegroup = Schema.TaggedStruct("Filegroup", {
     name: Schema.NonEmptyString,
     entries: Schema.Array(Entry)
 });
-/** A named read-only collection.
+/**
+ * A {@link Filegroup} restricted to {@link ReadEntry} declarations, for use
+ * in a read set. It shares the `"Filegroup"` tag.
+ *
  * @category schemas
  * @since 0.1.0
- * @slop
  */
 export const ReadFilegroup = Schema.TaggedStruct("Filegroup", {
     name: Schema.NonEmptyString,
     entries: Schema.Array(ReadEntry)
 });
-/** Any declaration accepted by a plan effect set.
+/**
+ * Any declaration accepted in a write set: an {@link Entry} or a
+ * {@link Filegroup}.
+ *
  * @category schemas
  * @since 0.1.0
- * @slop
  */
 export const Declaration = Schema.Union([Entry, Filegroup]);
-/** Any declaration accepted by a plan read set.
+/**
+ * Any declaration accepted in a read set: a {@link ReadEntry} or a
+ * {@link ReadFilegroup}.
+ *
  * @category schemas
  * @since 0.1.0
- * @slop
  */
 export const ReadDeclaration = Schema.Union([ReadEntry, ReadFilegroup]);
-/** Creates a named filegroup.
+/**
+ * Creates a {@link Filegroup}. It does not validate `name` or `entries`;
+ * decode through {@link Filegroup} when the input is untrusted.
+ *
+ * @param name - The filegroup name.
+ * @param entries - The entries the filegroup expands to, in order.
+ * @returns The filegroup value.
  * @category constructors
  * @since 0.1.0
- * @slop
  */
 export const makeFilegroup = (name, entries) => ({
     _tag: "Filegroup",
     name,
     entries
 });
-/** Expands filegroups deterministically, preserving declaration order.
+/**
+ * Replaces each {@link Filegroup} with its entries, in place, and keeps every
+ * other declaration as it is. Order is preserved and duplicates are kept.
+ *
+ * @param declarations - Write-set declarations, possibly holding filegroups.
+ * @returns The flat list of entries.
  * @category accessors
  * @since 0.1.0
- * @slop
  */
 export const expand = (declarations) => declarations.flatMap((declaration) => typeof declaration !== "string" && declaration._tag === "Filegroup" ? declaration.entries : [declaration]);
-/** Expands read filegroups deterministically, preserving declaration order.
+/**
+ * {@link expand} for read sets: replaces each {@link ReadFilegroup} with its
+ * entries, in place, preserving order and duplicates.
+ *
+ * @param declarations - Read-set declarations, possibly holding filegroups.
+ * @returns The flat list of read entries.
  * @category accessors
  * @since 0.1.0
- * @slop
  */
 export const expandReads = (declarations) => declarations.flatMap((declaration) => typeof declaration !== "string" && declaration._tag === "Filegroup" ? declaration.entries : [declaration]);
-/** Whether a value is a glob declaration.
+/**
+ * Whether a value carries the `"Glob"` tag. It checks only the tag, not the
+ * patterns.
+ *
+ * @param value - Any value.
+ * @returns `true` for an object whose `_tag` is `"Glob"`.
  * @category guards
  * @since 0.1.0
- * @slop
  */
 export const isGlob = (value) => typeof value === "object" && value !== null && "_tag" in value && value._tag === "Glob";
-/** Whether a value is a tree artifact declaration.
+/**
+ * Whether a value carries the `"TreeArtifact"` tag. It checks only the tag,
+ * not the path.
+ *
+ * @param value - Any value.
+ * @returns `true` for an object whose `_tag` is `"TreeArtifact"`.
  * @category guards
  * @since 0.1.0
- * @slop
  */
 export const isTreeArtifact = (value) => typeof value === "object" && value !== null && "_tag" in value && value._tag === "TreeArtifact";
 /** KMP searches a literal without rescanning a long near-matching prefix. */
@@ -252,16 +303,28 @@ const patternMatcher = (pattern) => {
     patternMatchers.set(key, matcher);
     return matcher;
 };
-/** Tests one workspace-relative path against one Bazel-style pattern.
+/**
+ * Whether `path` matches `pattern` under {@link Glob} wildcard rules.
+ *
+ * The pattern is read in its {@link canonical} spelling; the path is matched
+ * as given, case-sensitively, with `/` as its only separator.
+ *
+ * @param pattern - A Bazel-style pattern such as `src/*.ts` or `docs/**`.
+ * @param path - A workspace-relative path.
+ * @returns `true` when the path matches.
  * @category predicates
  * @since 0.1.0
- * @slop
  */
 export const matchesPattern = (pattern, path) => patternMatcher(pattern)(path);
-/** Tests one file path against a glob, including exclusions.
+/**
+ * Whether `path` matches some `include` pattern of `glob` and no `exclude`
+ * pattern, each tested with {@link matchesPattern}. Case-sensitive.
+ *
+ * @param glob - The glob to test.
+ * @param path - A workspace-relative path.
+ * @returns `true` when the glob selects the path.
  * @category predicates
  * @since 0.1.0
- * @slop
  */
 export const matchesGlob = (glob, path) => glob.include.some((pattern) => matchesPattern(pattern, path)) &&
     !(glob.exclude ?? []).some((pattern) => matchesPattern(pattern, path));
@@ -295,7 +358,6 @@ const matchesGlobFolded = (glob, path) => {
  *
  * @category predicates
  * @since 0.1.0
- * @slop
  */
 export const overlaps = (left, right) => {
     if (typeof left === "string" && typeof right === "string")