@dbx-tools/path 0.1.9

package/.projen/deps.json

@@ -0,0 +1,44 @@
+{
+  "dependencies": [
+    {
+      "name": "@types/node",
+      "version": "catalog:",
+      "type": "build"
+    },
+    {
+      "name": "tsx",
+      "version": "^4.23.0",
+      "type": "build"
+    },
+    {
+      "name": "typescript",
+      "type": "build"
+    },
+    {
+      "name": "@dbx-tools/core",
+      "version": "workspace:*",
+      "type": "runtime"
+    },
+    {
+      "name": "@dbx-tools/shared-core",
+      "version": "workspace:*",
+      "type": "runtime"
+    },
+    {
+      "name": "chokidar",
+      "version": "^4.0.3",
+      "type": "runtime"
+    },
+    {
+      "name": "glob",
+      "version": "^10.5.0",
+      "type": "runtime"
+    },
+    {
+      "name": "minimatch",
+      "version": "^10.2.5",
+      "type": "runtime"
+    }
+  ],
+  "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"pnpm exec projen\"."
+}

package/.projen/files.json

@@ -0,0 +1,11 @@
+{
+  "files": [
+    ".projen/deps.json",
+    ".projen/files.json",
+    ".projen/tasks.json",
+    "package.json",
+    "test/tsconfig.json",
+    "tsconfig.json"
+  ],
+  "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"pnpm exec projen\"."
+}

package/.projen/tasks.json

@@ -0,0 +1,121 @@
+{
+  "manifestVersion": 3,
+  "env": {
+    "PATH": "$(pnpm -c exec \"node --print process.env.PATH\")"
+  },
+  "tasks": {
+    "build": {
+      "name": "build",
+      "description": "Full release build",
+      "steps": [
+        {
+          "spawn": "pre-compile"
+        },
+        {
+          "spawn": "compile"
+        },
+        {
+          "spawn": "post-compile"
+        },
+        {
+          "spawn": "test"
+        },
+        {
+          "spawn": "package"
+        }
+      ]
+    },
+    "compile": {
+      "name": "compile",
+      "description": "Only compile",
+      "steps": [
+        {
+          "execArgs": [
+            "tsc",
+            "--build"
+          ]
+        }
+      ]
+    },
+    "default": {
+      "name": "default",
+      "description": "Synthesize project files",
+      "steps": [
+        {
+          "exec": "pnpm exec projen default",
+          "cwd": "../../.."
+        }
+      ]
+    },
+    "install": {
+      "name": "install",
+      "description": "Install project dependencies and update lockfile (non-frozen)",
+      "steps": [
+        {
+          "exec": "pnpm i --no-frozen-lockfile"
+        }
+      ]
+    },
+    "install:ci": {
+      "name": "install:ci",
+      "description": "Install project dependencies using frozen lockfile",
+      "steps": [
+        {
+          "exec": "pnpm i --frozen-lockfile"
+        }
+      ]
+    },
+    "package": {
+      "name": "package",
+      "description": "Creates the distribution package",
+      "steps": [
+        {
+          "execArgs": [
+            "mkdir",
+            "-p",
+            "dist/js"
+          ]
+        },
+        {
+          "execArgs": [
+            "pnpm",
+            "pack",
+            "--pack-destination",
+            "dist/js"
+          ]
+        }
+      ]
+    },
+    "post-compile": {
+      "name": "post-compile",
+      "description": "Runs after successful compilation"
+    },
+    "pre-compile": {
+      "name": "pre-compile",
+      "description": "Prepare the project for compilation"
+    },
+    "test": {
+      "name": "test",
+      "description": "Run tests",
+      "steps": [
+        {
+          "exec": "tsx --test 'test/**/*.test.ts'"
+        }
+      ]
+    },
+    "watch": {
+      "name": "watch",
+      "description": "Watch & compile in the background",
+      "steps": [
+        {
+          "execArgs": [
+            "tsc",
+            "--build",
+            "-w"
+          ]
+        }
+      ]
+    }
+  },
+  "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"pnpm exec projen\"."
+}

package/README.md

@@ -0,0 +1,119 @@
+# @dbx-tools/node-path
+
+Node filesystem path toolkit for discovery, matching, ignoring, scanning, and
+watching.
+
+Import this package when Node code needs consistent glob behavior across CLI,
+projen, barrel generation, OpenAPI generation, or docs tooling.
+
+Key features:
+
+- Lazy glob-backed file discovery that composes with shared-core sequences.
+- Glob-to-predicate matchers for include/exclude logic.
+- Centralized ignore rules for generated files, dependencies, package-manager
+  output, VCS folders, and build artifacts.
+- Workspace scan option types shared by synthesis and docs tooling.
+- Chokidar wrapper for watch loops that should follow the same ignore behavior.
+- Escaped glob pattern builders for generated matcher fragments.
+
+## Find Files
+
+```ts
+import { find, ignore } from "@dbx-tools/node-path";
+
+const files = find
+  .findFiles(["workspaces/**/src/**/*.ts"], {
+    ignore: ignore.ignorePatterns(),
+  })
+  .toArray();
+```
+
+`find.findFiles()` returns a lazy `Sequence<string>` from
+[`@dbx-tools/shared-core`](../../shared/core), so callers can map/filter without
+materializing immediately.
+
+Use this package instead of direct `glob` or `chokidar` calls when the result
+should agree with package discovery, barrel generation, or cleanup logic.
+
+## Compile Matchers
+
+```ts
+import { match } from "@dbx-tools/node-path";
+
+const isTest = match.toPathMatcher("**/*.test.ts");
+if (isTest("workspaces/shared/model/test/classify.test.ts")) {
+  skip();
+}
+```
+
+`match.toPathMatcher()` returns a composable shared-core predicate. Use
+`match.pathMatchTests()` when you need to inspect the compiled include/exclude
+tests.
+
+## Reuse Ignore Rules
+
+```ts
+import { ignore } from "@dbx-tools/node-path";
+
+const matcher = ignore.ignorePathMatcher({
+  generated: true,
+  dependencies: true,
+  vcs: true,
+});
+```
+
+The ignore helpers centralize repo-wide exclusions such as `node_modules`,
+generated files, build output, VCS metadata, and package-manager output.
+
+## Scan Workspace Packages
+
+```ts
+import { scan } from "@dbx-tools/node-path";
+
+const options: scan.FileScanOptions = {
+  roots: ["workspaces", "example-workspaces"],
+  followSymlinks: scan.FOLLOW_SYMLINKS_DEFAULT,
+};
+```
+
+`scan` exports shared scan option types used by the projen engine. Use the same
+options when implementing docs or analysis tools that should walk the workspace
+like synthesis does.
+
+## Watch Files
+
+```ts
+import { watch } from "@dbx-tools/node-path";
+
+const watcher = watch.watchFiles(["workspaces/**/src/**/*.ts"], {
+  ignoreInitial: true,
+});
+
+watcher.on("change", (file) => rebuild(file));
+```
+
+`watch.watchFiles()` wraps chokidar with the same path and ignore expectations
+used by the rest of the repo tooling.
+
+## Build Patterns
+
+```ts
+import { pattern } from "@dbx-tools/node-path";
+
+const nodeModulesPattern = pattern.directoryNamePattern("node_modules");
+const tsPattern = pattern.fileExtensionPattern("ts");
+```
+
+Pattern helpers keep generated glob fragments escaped and consistent.
+
+## Modules
+
+- `find` - glob-backed lazy file finding.
+- `match` - glob-to-predicate path matchers.
+- `ignore` - standard ignore pattern and matcher construction.
+- `scan` - workspace package scan option types and defaults.
+- `watch` - chokidar wrapper for file watching.
+- `pattern` - escaped directory-name and extension glob fragments.
+
+The projen engine uses this package in
+[`@dbx-tools/projen`](../projen).

package/index.ts

@@ -0,0 +1,15 @@
+// GENERATED by projen watch - DO NOT EDIT.
+// Regenerated from the exporting modules in ./src.
+// Hand edits are overwritten on the next watch; this file is read-only.
+
+export * as find from "./src/find";
+export * as ignore from "./src/ignore";
+export * as match from "./src/match";
+export * as pattern from "./src/pattern";
+export * as scan from "./src/scan";
+export * as watch from "./src/watch";
+export type { FileFindOptions } from "./src/find";
+export type { IgnorePatternOptions } from "./src/ignore";
+export type { PathMatchPredicate, PathMatcher, PathMatchInput } from "./src/match";
+export type { FileScanOptions, FileScanIgnoreOptions } from "./src/scan";
+export type { FileWatchOptions } from "./src/watch";

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@dbx-tools/path",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reggie-db/dbx-tools.git",
+    "directory": "workspaces/node/path"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "tsx": "^4.23.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "chokidar": "^4.0.3",
+    "glob": "^10.5.0",
+    "minimatch": "^10.2.5",
+    "@dbx-tools/shared-core": "0.1.9",
+    "@dbx-tools/core": "0.1.9"
+  },
+  "main": "index.ts",
+  "license": "UNLICENSED",
+  "version": "0.1.9",
+  "types": "index.ts",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./package.json": "./package.json"
+  },
+  "dbxToolsConfig": {
+    "tags": [
+      "node"
+    ]
+  },
+  "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"pnpm exec projen\".",
+  "scripts": {
+    "build": "projen build",
+    "compile": "projen compile",
+    "default": "projen default",
+    "package": "projen package",
+    "post-compile": "projen post-compile",
+    "pre-compile": "projen pre-compile",
+    "test": "projen test",
+    "watch": "projen watch",
+    "projen": "projen"
+  }
+}

package/src/find.ts

@@ -0,0 +1,128 @@
+import { iterable, type Sequence } from "@dbx-tools/shared-core";
+import { globIterateSync, IgnoreLike, type GlobOptionsWithFileTypesUnset } from "glob";
+import { ignorePathMatcher } from "./ignore";
+import { PathMatcher, PathMatchInput, pathMatchTests, toPathMatcher } from "./match";
+import { FileScanIgnoreOptions, FileScanOptions, FOLLOW_SYMLINKS_DEFAULT } from "./scan";
+
+type FileFindIgnore = PathMatchInput | readonly PathMatchInput[] | IgnoreLike;
+
+export interface FileFindOptions
+  extends
+    Omit<
+      GlobOptionsWithFileTypesUnset,
+      "ignore" | "follow" | "dot" | "cwd" | "includeChildMatches"
+    >,
+    Omit<FileScanOptions, "ignore" | "cwd"> {
+  cwd?: string | URL;
+  ignore?: FileFindIgnore;
+}
+/**
+ * Recursively lists files matching `pattern`, ignoring the shared default groups
+ * plus any caller `ignore` patterns (unless `ignore` is a lone predicate function,
+ * in which case only that predicate applies). The ignore list mirrors what
+ * {@link watchFiles} feeds through its matchers.
+ */
+export function findFiles(pattern: string | string[], options?: FileFindOptions): Sequence<string> {
+  return iterable.sequence(globIterateSync(pattern, toGlobOptions(options)));
+}
+
+function toGlobOptions(options: FileFindOptions | undefined): GlobOptionsWithFileTypesUnset {
+  const { cwd, ignore, ignoreOptions, followSymlinks, ...restOptions } = options ?? {};
+  return {
+    ...restOptions,
+    cwd: cwd ?? process.cwd(),
+    follow: followSymlinks ?? FOLLOW_SYMLINKS_DEFAULT,
+    ignore: normalizeIgnore(ignore, ignoreOptions),
+  };
+}
+
+const IGNORE_LIKE_FIELDS = [
+  "ignored",
+  "childrenIgnored",
+  "add",
+] as const satisfies readonly (keyof IgnoreLike)[];
+
+function isIgnoreLike(value: unknown): value is IgnoreLike {
+  if (Array.isArray(value)) return false;
+  if (typeof value === "object" && value !== null) {
+    for (const field of IGNORE_LIKE_FIELDS) {
+      if (field in value && typeof (value as any)[field] !== "function") {
+        return false;
+      }
+    }
+    return true;
+  }
+  return false;
+}
+/**
+ * Builds the {@link IgnoreLike} object {@link findFiles} hands to `glob`.
+ *
+ * A caller-supplied `IgnoreLike` (an object, not string/array) is consulted
+ * first - its `ignored`/`childrenIgnored` win - after which the shared
+ * {@link ignorePathMatcher} (the same matcher {@link watchFiles} uses) decides based on the
+ * package-relative path. `cacheDirectoryStats` is enabled because glob probes
+ * many paths per directory. Caller string/array patterns are merged into the
+ * matcher, and `add` forwards to both the caller object and the matcher.
+ */
+function normalizeIgnore(
+  ignore: FileFindIgnore | undefined,
+  ignoreOptions: FileScanIgnoreOptions | undefined,
+): IgnoreLike {
+  const ignoreLike: IgnoreLike | undefined = isIgnoreLike(ignore) ? ignore : undefined;
+  const ignorePathMatcherInputs: PathMatchInput[] | undefined =
+    ignore === undefined || ignoreLike ? undefined : Array.isArray(ignore) ? [...ignore] : [ignore];
+
+  const predicateOnly =
+    ignorePathMatcherInputs?.length === 1 && typeof ignorePathMatcherInputs[0] === "function";
+
+  let ignoreMatcher: PathMatcher = predicateOnly
+    ? toPathMatcher(ignorePathMatcherInputs[0])
+    : ignorePathMatcher(ignoreOptions);
+  if (ignorePathMatcherInputs && !predicateOnly) {
+    ignoreMatcher = ignoreMatcher.or(...pathMatchTests(...ignorePathMatcherInputs));
+  }
+  return {
+    ignored(path) {
+      if (ignoreLike?.ignored?.(path)) return true;
+      const patheRelative = path.relative();
+      const ignore = ignoreMatcher(patheRelative);
+      return ignore;
+    },
+    childrenIgnored(path) {
+      if (ignoreLike?.childrenIgnored?.(path)) return true;
+      const patheRelative = path.relative();
+      if (patheRelative) {
+        if (ignoreMatcher(patheRelative)) {
+          return true;
+        } else if (ignoreMatcher(patheRelative + "/")) {
+          return true;
+        }
+      }
+      return false;
+    },
+    add(ignore) {
+      ignoreLike?.add?.(ignore);
+      ignoreMatcher = ignoreMatcher.and(...pathMatchTests(ignore));
+    },
+  };
+}
+
+// Manual demo: run this file directly (e.g. `tsx src/find.ts`) to print the
+// files findFiles keeps for this package under the given ignore options.
+if (import.meta.main) {
+  const startTime = performance.now();
+  const cwd = process.cwd();
+  console.log(`Scanning: ${cwd}`);
+
+  const files = findFiles("**/*.*", {
+    ignore: ["**/index.ts", "**/example/**", "**/*.md"],
+    ignoreOptions: {
+      test: true,
+    },
+  });
+  for (const file of files) {
+    console.log(file);
+  }
+  const elapsed = performance.now() - startTime;
+  console.log(`Elapsed: ${elapsed}ms`);
+}

package/src/ignore.ts

@@ -0,0 +1,189 @@
+/**
+ * Built-in ignore glob patterns for file scanning and watching.
+ *
+ * This module owns the pattern catalog and option toggles only. Each group is
+ * compiled into {@link PathMatchPredicate} instances via {@link toPathMatcher};
+ * composition (`and`/`or`/`negate`) lives in {@link ./match}.
+ *
+ * Consumers:
+ * - {@link ignorePatterns} - yields the enabled glob strings (for projen prettier/gitignore).
+ * - {@link ignorePathMatcher} - returns a single {@link PathMatcher} for {@link findFiles}
+ *   and {@link watchFiles}.
+ */
+
+import { exec } from "@dbx-tools/core";
+import { functionModule, iterable, type Sequence } from "@dbx-tools/shared-core";
+import { PathMatcher, PathMatchPredicate, toPathMatcher } from "./match";
+import { directoryNamePattern, fileExtensionPattern } from "./pattern";
+
+/** Toggles for each built-in ignore group; omitted flags default to `true`. */
+export type IgnorePatternOptions = {
+  /** Build artifacts, dependency dirs, caches, logs, and OS junk files. */
+  defaults?: boolean;
+  /** Hidden dot-files and dot-directories (`.git`, `.vscode`, `.gitignore`, etc.). */
+  dot?: boolean;
+  /** Temporary directories (`tmp`, `.tmp`, `scratch`, etc.). */
+  temp?: boolean;
+  /** Test directories and `*.test.*` / `*.spec.*` naming conventions. */
+  test?: boolean;
+  /**
+   * Lockfile ignore group (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`,
+   * `bun.lockb`, etc.).
+   *
+   * - `true` - always ignore lockfiles.
+   * - `false` - never ignore lockfiles.
+   * - `"auto"` (default) - ignore when the active npm registry is not the public
+   *   npm registry (`registry.npmjs.org`), e.g. a company-internal registry.
+   */
+  lock?: boolean | "auto";
+};
+
+/**
+ * Memoized probe for {@link IgnorePatternOptions.lock} `"auto"`.
+ *
+ * Runs `npm`/`pnpm`/`yarn config get registry` (whichever succeeds first) and
+ * returns `true` when the registry host is not `registry.npmjs.org`.
+ */
+const lockIgnoreMatchersAutoEnabled = functionModule.memoize(() => {
+  let registryUrl: URL | undefined;
+  for (const command of ["npm", "pnpm", "yarn"]) {
+    const result = exec.spawnSync(command, ["config", "get", "registry"], {
+      stdout: "capture",
+      stderr: "ignore",
+      stdin: "ignore",
+    });
+    if (result.exitCode !== 0) continue;
+    const output = result.stdout;
+    if (output && output.includes("://")) {
+      const url = new URL(output);
+      if (url.protocol && url.hostname) {
+        registryUrl = url;
+        break;
+      }
+    }
+  }
+  if (registryUrl && registryUrl.hostname !== "registry.npmjs.org") {
+    return true;
+  }
+  return false;
+});
+
+/** Resolves whether the lockfile ignore group is enabled for the given options. */
+function lockIgnoreMatchersEnabled(options?: IgnorePatternOptions): boolean {
+  const value = options?.lock ?? "auto";
+  if (value === "auto") {
+    return lockIgnoreMatchersAutoEnabled();
+  }
+  return value;
+}
+
+/**
+ * Compiles glob strings into a `{ [glob]: PathMatchPredicate }` map.
+ *
+ * Keying by the source glob de-dupes and keeps each matcher beside its pattern.
+ */
+function compileMatchers(patterns: readonly string[]): Record<string, PathMatchPredicate> {
+  return Object.fromEntries(patterns.map((glob) => [glob, toPathMatcher(glob)]));
+}
+
+/** Build artifacts, dependency directories, caches, logs, and OS files. */
+const defaultIgnoreMatchers = compileMatchers([
+  "**/.DS_Store",
+  "**/Thumbs.db",
+  "**/Desktop.ini",
+  ...["log", "tsbuildinfo"].map((ext) => fileExtensionPattern(ext)),
+  "**/*-debug.log*",
+  "**/yarn-error.log*",
+  ...[
+    "node_modules",
+    "bower_components",
+    "jspm_packages",
+    "dist",
+    "lib",
+    "build",
+    "out",
+    "coverage",
+    ".cache",
+    ".parcel-cache",
+    ".turbo",
+    ".next",
+    ".nuxt",
+    ".svelte-kit",
+    ".pnpm-store",
+    ".nyc_output",
+  ].map((name) => directoryNamePattern(name)),
+]);
+
+/** Hidden dot-files and dot-directories such as `.git`, `.vscode`, `.idea`, etc. */
+const dotIgnoreMatchers = compileMatchers(
+  [".*"].flatMap((glob) => [`**/${glob}`, directoryNamePattern(glob, false)]),
+);
+
+/** Temporary directories, including hidden variants (`.tmp`, etc.). */
+const tempIgnoreMatchers = compileMatchers(
+  ["temp", "tmp", "temps", "scratch"]
+    .flatMap((name) => [name, `.${name}`])
+    .map((name) => directoryNamePattern(name)),
+);
+
+/** Test directories and common test-file naming conventions. */
+const testIgnoreMatchers = compileMatchers([
+  ...["test", "tests", "__tests__", "__snapshots__"]
+    .flatMap((name) => [name, `.${name}`])
+    .map((name) => directoryNamePattern(name)),
+  "**/*.test.*",
+  "**/*.spec.*",
+  "**/test.*",
+  "**/spec.*",
+]);
+
+/** Lockfiles (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `bun.lockb`, …). */
+const lockIgnoreMatchers = compileMatchers([
+  "**/bun.lockb",
+  ...["json", "yaml", "yml"].map((ext) => `**/*-lock.${ext}`),
+  ...["lock"].map((ext) => fileExtensionPattern(ext)),
+]);
+
+/**
+ * Collects the pre-compiled matcher maps for each enabled built-in group.
+ *
+ * Group toggles come from `options`; the lock group also respects
+ * {@link lockIgnoreMatchersEnabled} (`lock: "auto"` probes the npm registry).
+ */
+function ignoreMatchPredicates(
+  options?: IgnorePatternOptions,
+): Record<string, PathMatchPredicate>[] {
+  const ignoreMatchRecords: Record<string, PathMatchPredicate>[] = [];
+  if (options?.defaults ?? true) ignoreMatchRecords.push(defaultIgnoreMatchers);
+  if (options?.temp ?? true) ignoreMatchRecords.push(tempIgnoreMatchers);
+  if (options?.test ?? true) ignoreMatchRecords.push(testIgnoreMatchers);
+  if (options?.dot ?? true) ignoreMatchRecords.push(dotIgnoreMatchers);
+  if (lockIgnoreMatchersEnabled(options)) ignoreMatchRecords.push(lockIgnoreMatchers);
+  return ignoreMatchRecords;
+}
+
+/**
+ * Yields the glob strings for each enabled built-in ignore group.
+ *
+ * Useful when a consumer needs literal patterns (e.g. projen `.gitignore` /
+ * `.prettierignore`) rather than a compiled {@link PathMatcher}.
+ *
+ * @param options - Group toggles; omitted flags default to enabled.
+ */
+export function ignorePatterns(options?: IgnorePatternOptions): Sequence<string> {
+  return iterable.sequence(ignoreMatchPredicates(options)).flatMap(Object.keys).distinct();
+}
+
+/**
+ * Returns a {@link PathMatcher} for paths ignored by the enabled built-in groups.
+ *
+ * Matchers for each group are compiled once at module load; `options` only
+ * selects which groups participate. The lock group is included when
+ * {@link lockIgnoreMatchersEnabled} returns `true`.
+ *
+ * @param options - Group toggles; omitted flags default to enabled.
+ */
+export function ignorePathMatcher(options?: IgnorePatternOptions): PathMatcher {
+  const predicates = ignoreMatchPredicates(options).flatMap(Object.values);
+  return toPathMatcher(...predicates);
+}

package/src/match.ts

@@ -0,0 +1,69 @@
+/**
+ * Path matching and predicate composition for file scanning and watching.
+ *
+ * {@link toPathMatcher} compiles globs into {@link Predicate} values from
+ * shared-core (`and` / `or` / `negate`) for use by {@link findFiles} and
+ * {@link watchFiles}.
+ */
+
+import {
+  iterable,
+  predicate,
+  type Predicate,
+  type PredicateFunction,
+} from "@dbx-tools/shared-core";
+import { Minimatch } from "minimatch";
+import { ignorePathMatcher } from "./ignore";
+
+export type PathMatchPredicate = PredicateFunction<string>;
+
+/** A composable path test (`true` == match). */
+export type PathMatcher = Predicate<string>;
+
+/**
+ * Anything {@link toPathMatcher} accepts: a glob string (compiled with
+ * `dot: true`), or a custom `(path) => boolean`.
+ */
+export type PathMatchInput = PathMatchPredicate | string;
+
+/** Normalizes a {@link PathMatchInput} to a plain path test. */
+function toTest(pattern: PathMatchInput): PathMatchPredicate {
+  if (typeof pattern === "string") {
+    const matcher = new Minimatch(pattern, { dot: true });
+    return (path) => matcher.match(path);
+  }
+  return pattern;
+}
+
+/** Compiles path match inputs to predicate functions for `.and()` / `.or()`. */
+export function pathMatchTests(
+  ...inputs: readonly (PathMatchInput | null | undefined)[]
+): readonly PathMatchPredicate[] {
+  return iterable.sequence(inputs).nonNull().map(toTest).toArray();
+}
+
+/**
+ * Combines one or more patterns into a single {@link PathMatcher} (OR'd).
+ * Strings are compiled with `dot: true`; predicates are used as-is;
+ * `null`/`undefined` entries are skipped. With no matching patterns the result
+ * always returns `false`.
+ *
+ * @param patterns - Globs and/or predicates to OR together.
+ */
+export function toPathMatcher(
+  ...inputs: readonly (PathMatchInput | null | undefined)[]
+): PathMatcher {
+  const tests = pathMatchTests(...inputs);
+  if (tests.length === 0) return predicate.create(() => false);
+  return tests
+    .slice(1)
+    .reduce<PathMatcher>((acc, test) => acc.or(test), predicate.create(tests[0]!));
+}
+
+if (import.meta.main) {
+  const matcher = ignorePathMatcher({ test: true })
+    .negate()
+    .and(...pathMatchTests("**/cool.ts", "**/wow.ts"));
+  console.log(matcher("workspaces/node/file-scan/src/cool.ts"));
+  console.log(matcher("workspaces/node/file-scan/.src/cool.ts"));
+}

package/src/pattern.ts

@@ -0,0 +1,31 @@
+/**
+ * Glob pattern builders shared by ignore groups and matchers.
+ */
+
+/** Glob metacharacters; escaped so a directory or file name is matched literally. */
+const ESCAPE_GLOB_REGEXP = /([*?[\]{}()!+@\\])/g;
+
+/**
+ * Returns a glob matching all descendants of directories named `name`.
+ *
+ * By default, glob metacharacters in `name` are escaped so it is treated
+ * literally. Pass `false` for `escape` when `name` intentionally contains glob
+ * syntax.
+ *
+ * @param name - Directory base name (e.g. `node_modules`).
+ * @param escape - When `true` (default), escape glob metacharacters in `name`.
+ */
+export function directoryNamePattern(name: string, escape = true): string {
+  return `**/${escape ? name.replace(ESCAPE_GLOB_REGEXP, "\\$1") : name}/**`;
+}
+
+/**
+ * Returns a glob matching files with extension `extension` at any depth.
+ *
+ * @param extension - Extension with or without a leading dot (e.g. `log` or `.log`).
+ * @param escape - When `true` (default), escape glob metacharacters in `extension`.
+ */
+export function fileExtensionPattern(extension: string, escape = true): string {
+  const bare = extension.startsWith(".") ? extension.slice(1) : extension;
+  return `**/*.${escape ? bare.replace(ESCAPE_GLOB_REGEXP, "\\$1") : bare}`;
+}

package/src/scan.ts

@@ -0,0 +1,35 @@
+import { IgnorePatternOptions } from "./ignore";
+import { PathMatchInput } from "./match";
+
+export const FOLLOW_SYMLINKS_DEFAULT = false;
+
+export interface FileScanOptions {
+  /**
+   * Base directory used to resolve relative paths.
+   */
+  cwd?: string;
+
+  /**
+   * Ignore files or directories matching these patterns or predicates.
+   */
+  ignore?: PathMatchInput | readonly PathMatchInput[];
+  ignoreOptions?: FileScanIgnoreOptions;
+  /**
+   * Follow symbolic links.
+   *
+   * Maps to:
+   *   glob: follow
+   *   chokidar: followSymlinks
+   */
+  followSymlinks?: boolean;
+
+  /**
+   * Abort an in-progress operation.
+   *
+   * Ignored by chokidar after the watcher has been created.
+   */
+  signal?: AbortSignal;
+}
+
+/** Options controlling the generated ignore pattern list. */
+export type FileScanIgnoreOptions = IgnorePatternOptions;

package/src/watch.ts

@@ -0,0 +1,160 @@
+import { Stats } from "fs";
+import { isAbsolute, relative, resolve } from "path";
+import { ChokidarOptions, MatchFunction, watch } from "chokidar";
+import { hasMagic } from "glob";
+import { findFiles, type FileFindOptions } from "./find";
+import { ignorePathMatcher } from "./ignore";
+import { pathMatchTests } from "./match";
+import { FileScanIgnoreOptions, FileScanOptions, FOLLOW_SYMLINKS_DEFAULT } from "./scan";
+
+export interface FileWatchOptions
+  extends Omit<ChokidarOptions, "ignored">, Omit<FileScanOptions, "ignore"> {
+  ignore?: string | string[] | MatchFunction | MatchFunction[];
+}
+
+interface NormalizedFileWatchOptions extends Omit<FileWatchOptions, "ignore" | "ignoreOptions"> {
+  ignored: MatchFunction;
+}
+
+/**
+ * Watches files and directories for real-time changes, applying the shared
+ * ignore groups so it prunes the same paths {@link findFiles} skips for the
+ * same patterns.
+ */
+export function watchFiles(paths: string | string[], options?: FileWatchOptions) {
+  const normalized = toNormalizedFileWatchOptions(options);
+  const { ignored, cwd, followSymlinks, ...chokidarOptions } = normalized;
+  const { paths: literals, globs } = partitionPaths(paths);
+
+  let watchPaths: string[];
+  if (globs.length > 0) {
+    const distinctWatchPaths = new Set(literals);
+    for (const path of findFiles(globs, toFindFilesOptions(normalized))) {
+      distinctWatchPaths.add(path);
+    }
+    watchPaths = [...distinctWatchPaths];
+  } else {
+    watchPaths = literals;
+  }
+
+  return watch(watchPaths, {
+    ...chokidarOptions,
+    cwd,
+    followSymlinks,
+    ignored,
+  });
+}
+
+function partitionPaths(paths: string | string[]): { paths: string[]; globs: string[] } {
+  const globs: string[] = [];
+  const literals: string[] = [];
+  for (const path of Array.isArray(paths) ? paths : [paths]) {
+    (hasMagic(path) ? globs : literals).push(path);
+  }
+  return { paths: literals, globs };
+}
+
+/**
+ * Builds {@link NormalizedFileWatchOptions} first: all caller ignore inputs and
+ * built-in groups are consolidated into one chokidar {@link MatchFunction}. When
+ * `stats` marks a directory, the matcher also tests `path + "/"` for pruning.
+ */
+function toNormalizedFileWatchOptions(options?: FileWatchOptions): NormalizedFileWatchOptions & {
+  cwd: string;
+  followSymlinks: boolean;
+} {
+  const { cwd, ignore, followSymlinks, ignoreOptions, ...chokidarOptions } = options ?? {};
+  return {
+    ...chokidarOptions,
+    cwd: cwd ?? process.cwd(),
+    followSymlinks: followSymlinks ?? FOLLOW_SYMLINKS_DEFAULT,
+    ignored: toWatchMatchFunction(ignore, ignoreOptions, cwd ?? process.cwd()),
+  };
+}
+
+/** Glob expansion reuses the normalized ignore matcher as a cwd-relative path predicate. */
+function toFindFilesOptions(
+  normalized: NormalizedFileWatchOptions & { cwd: string; followSymlinks: boolean },
+): FileFindOptions {
+  const { ignored, cwd, followSymlinks } = normalized;
+  return {
+    cwd,
+    followSymlinks,
+    ignore: (path) => ignored(path, undefined),
+  };
+}
+
+/**
+ * Consolidates built-in ignore groups, caller glob patterns, and caller
+ * {@link MatchFunction}s into one ignore test. Directory pruning uses `stats`
+ * when chokidar supplies it; glob expansion passes `undefined`.
+ */
+function toWatchMatchFunction(
+  ignore: FileWatchOptions["ignore"] | undefined,
+  ignoreOptions: FileScanIgnoreOptions | undefined,
+  cwd: string,
+): MatchFunction {
+  const patterns: string[] = [];
+  const functions: MatchFunction[] = [];
+
+  if (ignore !== undefined) {
+    for (const item of Array.isArray(ignore) ? ignore : [ignore]) {
+      if (typeof item === "string") patterns.push(item);
+      else functions.push(item);
+    }
+  }
+
+  let matcher = ignorePathMatcher(ignoreOptions);
+  if (patterns.length > 0) matcher = matcher.or(...pathMatchTests(...patterns));
+
+  const matchPath = (path: string, stats?: Stats): boolean => {
+    const rel = toCwdRelativePath(path, cwd);
+    if (matcher(rel)) return true;
+    for (const fn of functions) {
+      if (fn(rel, stats)) return true;
+    }
+    if (stats?.isDirectory()) {
+      const directoryPath = rel + "/";
+      if (matcher(directoryPath)) return true;
+      for (const fn of functions) {
+        if (fn(directoryPath, stats)) return true;
+      }
+    }
+    return false;
+  };
+
+  return matchPath;
+}
+
+/** Aligns chokidar paths with the cwd-relative form {@link findFiles} uses. */
+function toCwdRelativePath(path: string, cwd: string): string {
+  if (!isAbsolute(path)) return path;
+  const rel = relative(cwd, path);
+  return rel === "" ? "." : rel;
+}
+
+// Manual demo: run this file directly (e.g. `tsx src/watch.ts`) to watch this
+// package and log every file event as it happens.
+if (import.meta.main) {
+  const dir = import.meta.dirname;
+  console.log("--- Starting File Watcher ---");
+  let cwd = resolve(dir, "..");
+  cwd = "/Users/reggie.pierce/Projects/github-reggie-db/dbx-tools";
+  console.log(`Working Directory: ${cwd}`);
+
+  const watcher = watchFiles("**/src/**", {
+    cwd,
+    ignoreInitial: false,
+    ignore: ["**/index.ts", "**/core/**"],
+    ignoreOptions: {
+      temp: false,
+    },
+  });
+  watcher.on("all", (event: string, path: string) => {
+    console.log(`[${event.toUpperCase()}] ${path}`);
+  });
+  watcher.on("error", (error) => {
+    console.error("Watcher error:", error);
+  });
+  console.log("Watcher started");
+}

package/test/fixtures/sample-tree/.hidden/secret.ts

@@ -0,0 +1 @@
+export const secret = true;

package/test/fixtures/sample-tree/example/skip.ts

@@ -0,0 +1 @@
+export const skip = true;

package/test/fixtures/sample-tree/src/index.ts

@@ -0,0 +1 @@
+export {};

package/test/fixtures/sample-tree/src/keep.ts

@@ -0,0 +1 @@
+export const keep = true;

package/test/match-parity.test.ts

@@ -0,0 +1,99 @@
+/**
+ * Parity tests: the same ignore patterns must make {@link findFiles} and
+ * {@link watchFiles} keep the same set of files. Both run against a temp copy of
+ * the fixture tree (see the note below the imports for why a temp root is used)
+ * and their results are asserted equal, then checked against a concrete list.
+ */
+import assert from "node:assert/strict";
+import { cpSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, relative, sep, isAbsolute } from "node:path";
+import { after, before, describe, it } from "node:test";
+import { fileURLToPath } from "node:url";
+import { findFiles } from "../src/find";
+import { watchFiles } from "../src/watch";
+
+const FIXTURE_SOURCE = fileURLToPath(new URL("fixtures/sample-tree", import.meta.url));
+
+// glob matches ignore patterns against cwd-relative paths, while chokidar
+// matches them against absolute paths. The real fixture lives under a `test/`
+// directory, so the default `**/test/**` group would match in watch (absolute)
+// but not in scan (relative) - a mismatch unrelated to the shared patterns.
+// Copying the tree to a neutral temp root removes that ancestor so the two are
+// compared purely on pattern parity.
+let root: string;
+
+before(() => {
+  root = mkdtempSync(join(tmpdir(), "file-scan-parity-"));
+  cpSync(FIXTURE_SOURCE, root, { recursive: true });
+});
+
+after(() => {
+  rmSync(root, { recursive: true, force: true });
+});
+
+const toPosix = (path: string): string => path.split(sep).join("/");
+
+/** Files fileScan keeps for the fixture (relative, posix) given `ignore`. */
+function scannedFiles(ignore: string | string[] | undefined): Set<string> {
+  return new Set([...findFiles("**", { cwd: root, nodir: true, ignore })].map(toPosix));
+}
+
+/** Files fileWatch reports for the (static) fixture (relative, posix), then closes. */
+async function watchedFiles(ignore: string | string[] | undefined): Promise<Set<string>> {
+  const files = new Set<string>();
+  const watcher = watchFiles(root, {
+    cwd: root,
+    ignore,
+    persistent: false,
+    ignoreInitial: false,
+  });
+  watcher.on("add", (path) => {
+    const rel = isAbsolute(path) ? relative(root, path) : path;
+    files.add(toPosix(rel === "" ? "." : rel));
+  });
+  try {
+    await new Promise<void>((resolve, reject) => {
+      watcher.once("ready", () => resolve());
+      watcher.once("error", reject);
+    });
+  } finally {
+    await watcher.close();
+  }
+  return files;
+}
+
+/**
+ * The same ignore patterns must make fileScan and fileWatch keep the same files.
+ * Asserts parity, then returns the (shared) sorted result for concrete checks.
+ */
+async function keptByBoth(patterns: string | string[] | undefined): Promise<string[]> {
+  const scanned = [...scannedFiles(patterns)].sort();
+  const watched = [...(await watchedFiles(patterns))].sort();
+  assert.deepEqual(watched, scanned);
+  return scanned;
+}
+
+describe("scan/watch matching parity", () => {
+  // `.hidden` (dot group) and any node_modules/dist (default groups) are dropped
+  // by both; only the plain source files survive the default ignore list.
+  it("keeps the same files with only the default ignore groups", async () => {
+    assert.deepEqual(await keptByBoth(undefined), [
+      "example/skip.ts",
+      "src/index.ts",
+      "src/keep.ts",
+    ]);
+  });
+
+  it("keeps the same files ignoring a file pattern", async () => {
+    assert.deepEqual(await keptByBoth("**/index.ts"), ["example/skip.ts", "src/keep.ts"]);
+  });
+
+  it("keeps the same files ignoring a directory pattern", async () => {
+    assert.deepEqual(await keptByBoth(["**/example/**"]), ["src/index.ts", "src/keep.ts"]);
+  });
+
+  it("keeps the same files ignoring multiple patterns", async () => {
+    assert.deepEqual(await keptByBoth(["**/index.ts", "**/example/**"]), ["src/keep.ts"]);
+  });
+});

package/test/tsconfig.json

@@ -0,0 +1,14 @@
+// ~~ Generated by projen. To modify, edit .projenrc.js and run "pnpm exec projen".
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "rootDir": ".."
+  },
+  "include": [
+    "**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}

package/tsconfig.json

@@ -0,0 +1,41 @@
+// ~~ Generated by projen. To modify, edit .projenrc.js and run "pnpm exec projen".
+{
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib",
+    "alwaysStrict": true,
+    "declaration": true,
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "inlineSourceMap": true,
+    "inlineSources": true,
+    "lib": [
+      "ES2022"
+    ],
+    "module": "ESNext",
+    "noEmitOnError": false,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitAny": true,
+    "noImplicitReturns": true,
+    "noImplicitThis": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "resolveJsonModule": true,
+    "strict": true,
+    "strictNullChecks": true,
+    "strictPropertyInitialization": true,
+    "stripInternal": true,
+    "target": "ES2022",
+    "types": [
+      "node"
+    ],
+    "moduleResolution": "bundler",
+    "skipLibCheck": true
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}