fast-glob 3.3.3: Prove fast-glob 3.3.3 fg.sync automatically returns Entry objects when stats is enabled, matches nested files under baseNameMatch, and filters negative patterns order-independently.

# fast-glob 3.3.3 fg.sync behavior and option contract

## Prior Search Finding

A search for `fast-glob@3.3.3` matched sample `sha256:4162da16f769afd9695a488b0435b39d2d937e186d769e175acdf8b63233a0fc`, which verified de-duplication parity across the default async, sync, and stream modes. This contract focuses specifically on the synchronous API `fg.sync` and its option interactions.

## Pinned Release

- `fast-glob`: `3.3.3`

## Observed Behavior and Traps

### 1. `stats: true` Implicitly Enables Object Mode
Setting `stats: true` in `fg.sync` automatically returns an array of Entry objects containing `fs.Stats` and `Dirent` instances, even when `objectMode` is not explicitly set to `true`. Code that expects an array of path strings will fail loudly with a `TypeError` when performing string operations on returned elements.

### 2. `baseNameMatch: true` Matches Nested Hierarchies
When `baseNameMatch: true` is enabled, flat patterns like `*.js` match all matching files across nested directory trees without requiring recursive globstar wildcards (`**/*.js`).

### 3. Negated Pattern Resolution and Ordering
- A pattern array containing only negative patterns (e.g. `['!**/*.test.js']`) returns an empty array `[]`. This is a silent failure trap for callers expecting an inversion of the entire filesystem.
- When paired with positive patterns, negative patterns filter matching entries regardless of whether the negative pattern precedes or follows the positive pattern in the input array.

### 4. Traversal Depth Restriction
The `deep: 1` option restricts search traversal exclusively to top-level children, excluding matches in deeper nested subdirectories.

### 5. Hidden File and Directory Handling
By default (`dot: false`), wildcard patterns do not traverse into hidden directories or match dotfiles. However, explicit dot patterns (such as `.*`) match dotfiles directly without requiring `dot: true`.

### 6. Directory-Only Filtering
Specifying `onlyDirectories: true` returns exclusively directory paths and filters out regular files.

{"case":{"believed":"fg.sync with stats: true returns string path arrays unless objectMode is explicitly requested, flat basename patterns never match nested directories, and pattern array order changes negative pattern filtering.","caseId":"case:sha256:56e18cf55bc42e5541b0ca81efbd67dcd3b8acad6f37e43b3067a8c68fdb0830","contract":["fg.sync with stats: true automatically produces an array of Entry objects containing fs.Stats and Dirent instances without requiring objectMode: true.","fg.sync with baseNameMatch: true matches nested files matching the basename pattern across directory subtrees without wildcard prefixes.","fg.sync with a negative pattern alone returns an empty array, while pairing negative and positive patterns filters results identically regardless of pattern order.","fg.sync with deep: 1 restricts search traversal to immediate children, excluding deeper nested matches.","fg.sync with default dot: false ignores hidden files and directories in wildcard queries, while explicit leading-dot patterns match them directly.","fg.sync with onlyDirectories: true returns exclusively directory paths while ignoring files."],"goal":"Prove fast-glob 3.3.3 fg.sync automatically returns Entry objects when stats is enabled, matches nested files under baseNameMatch, and filters negative patterns order-independently.","kind":"HOW","packages":["pkg:npm/fast-glob@3.3.3"],"schemaVersion":1,"symbols":["fg.sync"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","ecosystem":"npm","executionContext":"node","language":"node","os":"linux","packageManager":"npm","runtime":"node","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/fast-glob@3.3.3"],"schemaVersion":1,"symbols":["fg.sync"],"verifierAdapter":"node-typescript@1"}

{}

export const secret = true;

export const index = true;

export const isTest = true;

export const child = true;

export const childTest = true;

export const nested = true;

{
  "name": "fast-glob-sync-contract",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "fast-glob-sync-contract",
      "version": "1.0.0",
      "dependencies": {
        "fast-glob": "3.3.3"
      }
    },
    "node_modules/@nodelib/fs.scandir": {
      "version": "2.1.5",
      "resolved": "https://registry.npmjs.org/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz",
      "integrity": "sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g==",
      "license": "MIT",
      "dependencies": {
        "@nodelib/fs.stat": "2.0.5",
        "run-parallel": "^1.1.9"
      },
      "engines": {
        "node": ">= 8"
      }
    },
    "node_modules/@nodelib/fs.stat": {
      "version": "2.0.5",
      "resolved": "https://registry.npmjs.org/@nodelib/fs.stat/-/fs.stat-2.0.5.tgz",
      "integrity": "sha512-RkhPPp2zrqDAQA/2jNhnztcPAlv64XdhIp7a7454A5ovI7Bukxgt7MX7udwAu3zg1DcpPU0rz3VV1SeaqvY4+A==",
      "license": "MIT",
      "engines": {
        "node": ">= 8"
      }
    },
    "node_modules/@nodelib/fs.walk": {
      "version": "1.2.8",
      "resolved": "https://registry.npmjs.org/@nodelib/fs.walk/-/fs.walk-1.2.8.tgz",
      "integrity": "sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg==",
      "license": "MIT",
      "dependencies": {
        "@nodelib/fs.scandir": "2.1.5",
        "fastq": "^1.6.0"
      },
      "engines": {
        "node": ">= 8"
      }
    },
    "node_modules/braces": {
      "version": "3.0.3",
      "resolved": "https://registry.npmjs.org/braces/-/braces-3.0.3.tgz",
      "integrity": "sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==",
      "license": "MIT",
      "dependencies": {
        "fill-range": "^7.1.1"
      },
      "engines": {
        "node": ">=8"
      }
    },
    "node_modules/fast-glob": {
      "version": "3.3.3",
      "resolved": "https://registry.npmjs.org/fast-glob/-/fast-glob-3.3.3.tgz",
      "integrity": "sha512-7MptL8U0cqcFdzIzwOTHoilX9x5BrNqye7Z/LuC7kCMRio1EMSyqRK3BEAUD7sXRq4iT4AzTVuZdhgQ2TCvYLg==",
      "license": "MIT",
      "dependencies": {
        "@nodelib/fs.stat": "^2.0.2",
        "@nodelib/fs.walk": "^1.2.3",
        "glob-parent": "^5.1.2",
        "merge2": "^1.3.0",
        "micromatch": "^4.0.8"
      },
      "engines": {
        "node": ">=8.6.0"
      }
    },
    "node_modules/fastq": {
      "version": "1.20.1",
      "resolved": "https://registry.npmjs.org/fastq/-/fastq-1.20.1.tgz",
      "integrity": "sha512-GGToxJ/w1x32s/D2EKND7kTil4n8OVk/9mycTc4VDza13lOvpUZTGX3mFSCtV9ksdGBVzvsyAVLM6mHFThxXxw==",
      "license": "ISC",
      "dependencies": {
        "reusify": "^1.0.4"
      }
    },
    "node_modules/fill-range": {
      "version": "7.1.1",
      "resolved": "https://registry.npmjs.org/fill-range/-/fill-range-7.1.1.tgz",
      "integrity": "sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg==",
      "license": "MIT",
      "dependencies": {
        "to-regex-range": "^5.0.1"
      },
      "engines": {
        "node": ">=8"
      }
    },
    "node_modules/glob-parent": {
      "version": "5.1.2",
      "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-5.1.2.tgz",
      "integrity": "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==",
      "license": "ISC",
      "dependencies": {
        "is-glob": "^4.0.1"
      },
      "engines": {
        "node": ">= 6"
      }
    },
    "node_modules/is-extglob": {
      "version": "2.1.1",
      "resolved": "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz",
      "integrity": "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==",
      "license": "MIT",
      "engines": {
        "node": ">=0.10.0"
      }
    },
    "node_modules/is-glob": {
      "version": "4.0.3",
      "resolved": "https://registry.npmjs.org/is-glob/-/is-glob-4.0.3.tgz",
      "integrity": "sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==",
      "license": "MIT",
      "dependencies": {
        "is-extglob": "^2.1.1"
      },
      "engines": {
        "node": ">=0.10.0"
      }
    },
    "node_modules/is-number": {
      "version": "7.0.0",
      "resolved": "https://registry.npmjs.org/is-number/-/is-number-7.0.0.tgz",
      "integrity": "sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==",
      "license": "MIT",
      "engines": {
        "node": ">=0.12.0"
      }
    },
    "node_modules/merge2": {
      "version": "1.4.1",
      "resolved": "https://registry.npmjs.org/merge2/-/merge2-1.4.1.tgz",
      "integrity": "sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==",
      "license": "MIT",
      "engines": {
        "node": ">= 8"
      }
    },
    "node_modules/micromatch": {
      "version": "4.0.8",
      "resolved": "https://registry.npmjs.org/micromatch/-/micromatch-4.0.8.tgz",
      "integrity": "sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==",
      "license": "MIT",
      "dependencies": {
        "braces": "^3.0.3",
        "picomatch": "^2.3.1"
      },
      "engines": {
        "node": ">=8.6"
      }
    },
    "node_modules/picomatch": {
      "version": "2.3.2",
      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.2.tgz",
      "integrity": "sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA==",
      "license": "MIT",
      "engines": {
        "node": ">=8.6"
      },
      "funding": {
        "url": "https://github.com/sponsors/jonschlinkert"
      }
    },
    "node_modules/queue-microtask": {
      "version": "1.2.3",
      "resolved": "https://registry.npmjs.org/queue-microtask/-/queue-microtask-1.2.3.tgz",
      "integrity": "sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==",
      "funding": [
        {
          "type": "github",
          "url": "https://github.com/sponsors/feross"
        },
        {
          "type": "patreon",
          "url": "https://www.patreon.com/feross"
        },
        {
          "type": "consulting",
          "url": "https://feross.org/support"
        }
      ],
      "license": "MIT"
    },
    "node_modules/reusify": {
      "version": "1.1.0",
      "resolved": "https://registry.npmjs.org/reusify/-/reusify-1.1.0.tgz",
      "integrity": "sha512-g6QUff04oZpHs0eG5p83rFLhHeV00ug/Yf9nZM6fLeUrPguBTkTQOdpAWWspMh55TZfVQDPaN3NQJfbVRAxdIw==",
      "license": "MIT",
      "engines": {
        "iojs": ">=1.0.0",
        "node": ">=0.10.0"
      }
    },
    "node_modules/run-parallel": {
      "version": "1.2.0",
      "resolved": "https://registry.npmjs.org/run-parallel/-/run-parallel-1.2.0.tgz",
      "integrity": "sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==",
      "funding": [
        {
          "type": "github",
          "url": "https://github.com/sponsors/feross"
        },
        {
          "type": "patreon",
          "url": "https://www.patreon.com/feross"
        },
        {
          "type": "consulting",
          "url": "https://feross.org/support"
        }
      ],
      "license": "MIT",
      "dependencies": {
        "queue-microtask": "^1.2.2"
      }
    },
    "node_modules/to-regex-range": {
      "version": "5.0.1",
      "resolved": "https://registry.npmjs.org/to-regex-range/-/to-regex-range-5.0.1.tgz",
      "integrity": "sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==",
      "license": "MIT",
      "dependencies": {
        "is-number": "^7.0.0"
      },
      "engines": {
        "node": ">=8.0"
      }
    }
  }
}

{
  "name": "fast-glob-sync-contract",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "fast-glob": "3.3.3"
  }
}

import assert from "node:assert/strict";
import fg from "fast-glob";

// 1. stats: true automatically produces Entry objects containing fs.Stats and Dirent
const statsEntries = fg.sync("**/*.js", { cwd: "fixtures", stats: true });
assert.ok(statsEntries.length > 0);
assert.equal(typeof statsEntries[0], "object");
assert.equal(typeof statsEntries[0].name, "string");
assert.equal(typeof statsEntries[0].path, "string");
assert.equal(typeof statsEntries[0].dirent.isFile, "function");
assert.equal(typeof statsEntries[0].stats.isFile, "function");
assert.equal(statsEntries[0].stats.isFile(), true);

// 2. baseNameMatch: true enables flat basename patterns to match nested files recursively
const flatResult = fg.sync("*.js", { cwd: "fixtures" });
assert.deepEqual(flatResult.sort(), ["index.js", "index.test.js"]);

const baseNameResult = fg.sync("*.js", { cwd: "fixtures", baseNameMatch: true });
assert.deepEqual(baseNameResult.sort(), [
  "index.js",
  "index.test.js",
  "sub/child.js",
  "sub/child.test.js",
  "sub/deep/nested.js",
]);

// 3. Negated patterns alone return empty array, but filter order-independently when paired with positive patterns
const negativeOnly = fg.sync(["!**/*.test.js"], { cwd: "fixtures" });
assert.deepEqual(negativeOnly, []);

const posThenNeg = fg.sync(["**/*.js", "!**/*.test.js"], { cwd: "fixtures" });
const negThenPos = fg.sync(["!**/*.test.js", "**/*.js"], { cwd: "fixtures" });
const expectedFiltered = ["index.js", "sub/child.js", "sub/deep/nested.js"];
assert.deepEqual(posThenNeg.sort(), expectedFiltered);
assert.deepEqual(negThenPos.sort(), expectedFiltered);

// 4. deep option restricts recursion depth (deep: 1 only searches top directory)
const deep1 = fg.sync("**/*.js", { cwd: "fixtures", deep: 1 });
assert.deepEqual(deep1.sort(), ["index.js", "index.test.js"]);

const deep2 = fg.sync("**/*.js", { cwd: "fixtures", deep: 2 });
assert.deepEqual(deep2.sort(), [
  "index.js",
  "index.test.js",
  "sub/child.js",
  "sub/child.test.js",
]);

// 5. dot: false skips dotfiles and hidden folders in wildcards, while explicit dot patterns match them
const wildcardNoDot = fg.sync("*", { cwd: "fixtures" });
assert.deepEqual(wildcardNoDot.sort(), ["index.js", "index.test.js"]);

const explicitDot = fg.sync(".*", { cwd: "fixtures" });
assert.deepEqual(explicitDot, [".config.json"]);

const withDot = fg.sync("**/*.js", { cwd: "fixtures", dot: true });
assert.ok(withDot.includes(".hidden/secret.js"));

// 6. onlyDirectories filters exclusively for directories
const dirsOnly = fg.sync("*", { cwd: "fixtures", onlyDirectories: true });
assert.deepEqual(dirsOnly, ["sub"]);

console.log("CONTRACT PASS: fast-glob 3.3.3 fg.sync behavior verified");