@socketsecurity/lib 6.0.7 → 6.0.9

package/dist/fleet/repo-config.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @file Fleet-convention config reader: a per-repo override (`.config/repo`)
+ *   layered over the cascaded fleet default (`.config/fleet`). A thin wrapper
+ *   over the generic `config/layers` reader that returns the named `{ fleet,
+ *   repo }` shape fleet callers use, plus the `{ fleet, repo }` array-merge
+ *   convenience. The generic, fleet-agnostic primitives (`readConfigLayers`,
+ *   `mergeConfigArray`) live in `config/layers`. Lives in the published lib
+ *   because it is the only import root the `.git-hooks/_shared` and
+ *   `.claude/hooks/_shared` trees (which do not cross-import) plus `.config/*`
+ *   can all reach.
+ */
+export declare const FLEET_LAYER_DIRS: readonly string[];
+export interface RepoConfigTiers<T> {
+    fleet: T | undefined;
+    repo: T | undefined;
+}
+export interface ResolveRepoConfigOptions {
+    repoRoot?: string | undefined;
+    cwd?: string | undefined;
+}
+/**
+ * Concatenate one array-valued key across the fleet + repo tiers. Fleet entries
+ * first, then repo entries. Convenience over `mergeConfigArray` for the `{
+ * fleet, repo }` shape.
+ *
+ * @param tiers - The `{ fleet, repo }` from `resolveRepoConfig`.
+ * @param key - The array-valued property to concatenate.
+ *
+ * @returns Fleet entries followed by repo entries; `[]` when neither is an
+ *   array.
+ */
+export declare function mergeRepoConfigArray<T extends Record<string, unknown>, K extends keyof T>(tiers: RepoConfigTiers<T>, key: K): Array<T[K] extends Array<infer E> ? E : never>;
+/**
+ * Fleet-convention reader: a repo override (`.config/repo`) layered over the
+ * cascaded fleet default (`.config/fleet`). A thin wrapper over
+ * `readConfigLayers` that returns the named `{ fleet, repo }` shape callers
+ * already use; either tier is `undefined` when absent or unparseable.
+ *
+ * @example
+ *   ;```typescript
+ *   const { fleet, repo } = resolveRepoConfig<VitestTiers>('vitest')
+ *   const nonIsolated = [
+ *     ...(fleet?.nonIsolated ?? []),
+ *     ...(repo?.nonIsolated ?? []),
+ *   ]
+ *   ```
+ *
+ * @param name - Base name of the config file (no directory, no `.json`).
+ * @param options - `repoRoot` / `cwd` for path resolution.
+ *
+ * @returns `{ fleet, repo }` parsed tiers; either may be `undefined`.
+ */
+export declare function resolveRepoConfig<T = unknown>(name: string, options?: ResolveRepoConfigOptions | undefined): RepoConfigTiers<T>;

package/dist/fleet/repo-config.js

@@ -0,0 +1,79 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_config_layers = require('../config/layers.js');
+
+//#region src/fleet/repo-config.ts
+/**
+* @file Fleet-convention config reader: a per-repo override (`.config/repo`)
+*   layered over the cascaded fleet default (`.config/fleet`). A thin wrapper
+*   over the generic `config/layers` reader that returns the named `{ fleet,
+*   repo }` shape fleet callers use, plus the `{ fleet, repo }` array-merge
+*   convenience. The generic, fleet-agnostic primitives (`readConfigLayers`,
+*   `mergeConfigArray`) live in `config/layers`. Lives in the published lib
+*   because it is the only import root the `.git-hooks/_shared` and
+*   `.claude/hooks/_shared` trees (which do not cross-import) plus `.config/*`
+*   can all reach.
+*/
+const FLEET_LAYER_DIRS = [".config/fleet", ".config/repo"];
+/**
+* Concatenate one array-valued key across the fleet + repo tiers. Fleet entries
+* first, then repo entries. Convenience over `mergeConfigArray` for the `{
+* fleet, repo }` shape.
+*
+* @param tiers - The `{ fleet, repo }` from `resolveRepoConfig`.
+* @param key - The array-valued property to concatenate.
+*
+* @returns Fleet entries followed by repo entries; `[]` when neither is an
+*   array.
+*/
+function mergeRepoConfigArray(tiers, key) {
+	return require_config_layers.mergeConfigArray([tiers.fleet, tiers.repo], key);
+}
+/**
+* Fleet-convention reader: a repo override (`.config/repo`) layered over the
+* cascaded fleet default (`.config/fleet`). A thin wrapper over
+* `readConfigLayers` that returns the named `{ fleet, repo }` shape callers
+* already use; either tier is `undefined` when absent or unparseable.
+*
+* @example
+*   ;```typescript
+*   const { fleet, repo } = resolveRepoConfig<VitestTiers>('vitest')
+*   const nonIsolated = [
+*     ...(fleet?.nonIsolated ?? []),
+*     ...(repo?.nonIsolated ?? []),
+*   ]
+*   ```
+*
+* @param name - Base name of the config file (no directory, no `.json`).
+* @param options - `repoRoot` / `cwd` for path resolution.
+*
+* @returns `{ fleet, repo }` parsed tiers; either may be `undefined`.
+*/
+function resolveRepoConfig(name, options) {
+	const opts = {
+		__proto__: null,
+		...options
+	};
+	const base = {
+		cwd: opts.cwd,
+		rootDir: opts.repoRoot
+	};
+	const [fleet] = require_config_layers.readConfigLayers(name, {
+		...base,
+		dirs: [FLEET_LAYER_DIRS[0]]
+	});
+	const [repo] = require_config_layers.readConfigLayers(name, {
+		...base,
+		dirs: [FLEET_LAYER_DIRS[1]]
+	});
+	return {
+		fleet,
+		repo
+	};
+}
+
+//#endregion
+exports.FLEET_LAYER_DIRS = FLEET_LAYER_DIRS;
+exports.mergeRepoConfigArray = mergeRepoConfigArray;
+exports.resolveRepoConfig = resolveRepoConfig;

package/dist/fs/allowed-dirs-cache.d.ts

@@ -4,7 +4,17 @@
  *   `invalidatePathCache` with `paths/rewire.ts` so test-time path overrides
  *   flush the cache; the registration is the module's only side effect, so
  *   callers that just need to flush the cache imperatively can call
- *   `invalidatePathCache()` directly without that side effect repeating.
+ *   `invalidatePathCache()` directly without that side effect repeating. The
+ *   registration is deferred to a microtask (`registerInvalidationCallback`)
+ *   rather than run at top-level module load. This module sits in a require
+ *   cycle (`allowed-dirs-cache → _internal → paths/socket → …`); in the bundled
+ *   CJS the `registerCacheInvalidation` import binding from `paths/rewire` is
+ *   not yet initialized when this module first evaluates, so a synchronous
+ *   top-level call threw `registerCacheInvalidation is not defined` at require
+ *   time. Deferring to a microtask runs the call after the module graph has
+ *   settled, breaking the init-order hazard while keeping the load-time
+ *   registration contract (the callback is in place before any test hook
+ *   fires).
  */
 /**
  * Invalidate the cached allowed directories. Called automatically by the
@@ -19,3 +29,19 @@
  * @internal Used for test rewiring
  */
 export declare function invalidatePathCache(): void;
+/**
+ * Register `invalidatePathCache` with the rewire module after the current
+ * module-init turn, so the circular import is fully wired before the call.
+ * Guarded + self-rescheduling: in the require cycle (`allowed-dirs-cache →
+ * _internal → paths/socket → … → rewire`) the `registerCacheInvalidation` live
+ * binding can still be in its temporal dead zone when the first microtask fires
+ * under some import orders (vitest loads many modules concurrently), throwing
+ * `registerCacheInvalidation is not defined`. So check the binding is callable;
+ * if not, re-defer to the next microtask. The registration is a test-seam
+ * best-effort (it lets path-rewire flush this cache), so a bounded retry that
+ * lands on a later turn is correct — and a never-resolving binding (production,
+ * where rewire is unused) simply stops retrying without throwing.
+ *
+ * @internal
+ */
+export declare function registerInvalidationCallback(attempt?: number): void;

package/dist/fs/allowed-dirs-cache.js

@@ -1,8 +1,6 @@
 "use strict";
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_paths_rewire = require('../paths/rewire.js');
-const require_fs__internal = require('./_internal.js');
 
 //#region src/fs/allowed-dirs-cache.ts
 /**
@@ -11,7 +9,17 @@ const require_fs__internal = require('./_internal.js');
 *   `invalidatePathCache` with `paths/rewire.ts` so test-time path overrides
 *   flush the cache; the registration is the module's only side effect, so
 *   callers that just need to flush the cache imperatively can call
-*   `invalidatePathCache()` directly without that side effect repeating.
+*   `invalidatePathCache()` directly without that side effect repeating. The
+*   registration is deferred to a microtask (`registerInvalidationCallback`)
+*   rather than run at top-level module load. This module sits in a require
+*   cycle (`allowed-dirs-cache → _internal → paths/socket → …`); in the bundled
+*   CJS the `registerCacheInvalidation` import binding from `paths/rewire` is
+*   not yet initialized when this module first evaluates, so a synchronous
+*   top-level call threw `registerCacheInvalidation is not defined` at require
+*   time. Deferring to a microtask runs the call after the module graph has
+*   settled, breaking the init-order hazard while keeping the load-time
+*   registration contract (the callback is in place before any test hook
+*   fires).
 */
 /**
 * Invalidate the cached allowed directories. Called automatically by the
@@ -26,9 +34,34 @@ const require_fs__internal = require('./_internal.js');
 * @internal Used for test rewiring
 */
 function invalidatePathCache() {
-	require_fs__internal.clearAllowedDirectories();
+	clearAllowedDirectories();
 }
-require_paths_rewire.registerCacheInvalidation(invalidatePathCache);
+/**
+* Register `invalidatePathCache` with the rewire module after the current
+* module-init turn, so the circular import is fully wired before the call.
+* Guarded + self-rescheduling: in the require cycle (`allowed-dirs-cache →
+* _internal → paths/socket → … → rewire`) the `registerCacheInvalidation` live
+* binding can still be in its temporal dead zone when the first microtask fires
+* under some import orders (vitest loads many modules concurrently), throwing
+* `registerCacheInvalidation is not defined`. So check the binding is callable;
+* if not, re-defer to the next microtask. The registration is a test-seam
+* best-effort (it lets path-rewire flush this cache), so a bounded retry that
+* lands on a later turn is correct — and a never-resolving binding (production,
+* where rewire is unused) simply stops retrying without throwing.
+*
+* @internal
+*/
+function registerInvalidationCallback(attempt = 0) {
+	try {
+		if (typeof registerCacheInvalidation === "function") {
+			registerCacheInvalidation(invalidatePathCache);
+			return;
+		}
+	} catch {}
+	if (attempt < 10) queueMicrotask(() => registerInvalidationCallback(attempt + 1));
+}
+queueMicrotask(() => registerInvalidationCallback());
 
 //#endregion
-exports.invalidatePathCache = invalidatePathCache;
+exports.invalidatePathCache = invalidatePathCache;
+exports.registerInvalidationCallback = registerInvalidationCallback;

package/dist/fs/copy.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @file Recursive copy for a file or directory tree, with three destination
+ *   modes (see {@link CopyMode}). Plain `fs.cp` (even with `force`) overwrites
+ *   files present in the source but never deletes destination files absent from
+ *   it, so copying onto an existing target leaves stale leftovers behind. The
+ *   `'pave'` mode makes the destination an exact copy of the source by staging
+ *   a fresh tree in a sibling temp directory and swapping it in with a single
+ *   rename — atomic, with no stale survivors.
+ */
+import type { PathLike } from 'node:fs';
+/**
+ * Named values for {@link CopyMode}. A frozen object rather than a TypeScript
+ * `enum` so the declaration is erasable (enums emit runtime helper code).
+ */
+export declare const CopyMode: Readonly<{
+    readonly Fill: 'fill';
+    readonly Overlay: 'overlay';
+    readonly Pave: 'pave';
+}>;
+/**
+ * How {@link copy} treats an existing destination.
+ *
+ * - `'overlay'` (default) — overwrite files present in the source but leave any
+ *   pre-existing destination-only files in place (a recursive `fs.cp`).
+ * - `'pave'` — replace the destination so it becomes an exact copy of the source;
+ *   destination entries absent from the source do not survive. The swap is
+ *   atomic (a sibling temp directory is renamed into place), so a partial tree
+ *   is never observable.
+ * - `'fill'` — copy only what the destination lacks: existing files stay
+ *   untouched (no-clobber), missing ones are added. Never throws on an existing
+ *   file.
+ *
+ * Maps to `cp` (overlay), `rsync --delete` / robocopy `/MIR` (pave), and
+ * `cp -n` (fill).
+ */
+export type CopyMode = (typeof CopyMode)[keyof typeof CopyMode];
+/**
+ * Options for {@link copy}.
+ */
+export interface CopyOptions {
+    /**
+     * Dereference symlinks — copy what each points to rather than the link
+     * itself.
+     *
+     * @default false
+     */
+    dereference?: boolean | undefined;
+    /**
+     * Predicate deciding which entries to copy. Return `false` to skip an entry
+     * (and, for a directory, everything beneath it). Receives resolved source
+     * and destination paths, matching `node:fs` `cp`'s `filter`.
+     */
+    filter?: ((source: string, destination: string) => boolean) | undefined;
+    /**
+     * How to treat an existing destination. See {@link CopyMode}.
+     *
+     * @default 'overlay'
+     */
+    mode?: CopyMode | undefined;
+    /**
+     * Abort signal to cancel the operation.
+     */
+    signal?: AbortSignal | undefined;
+}
+/**
+ * Recursively copy a file or directory tree from `from` to `to`.
+ *
+ * Works for both files and directories. The `mode` option chooses how an
+ * existing destination is treated — overlay (default), pave, or fill; see
+ * {@link CopyMode}.
+ *
+ * @example
+ *   ;```ts
+ *   // Overlay (default) — overwrite collisions, keep files already in dest:
+ *   await copy('./src', './dest')
+ *
+ *   // Pave — dest ends up identical to src, no stale survivors:
+ *   await copy('./vendor/upstream', './deps/upstream', { mode: CopyMode.Pave })
+ *
+ *   // Fill — add only what's missing, never overwrite an existing file:
+ *   await copy('./defaults', './config', { mode: CopyMode.Fill })
+ *   ```
+ *
+ * @param from - Source file or directory to copy.
+ * @param to - Destination path.
+ * @param options - Copy options (mode, filter, dereference, abort signal).
+ */
+export declare function copy(from: PathLike, to: PathLike, options?: CopyOptions | undefined): Promise<void>;

package/dist/fs/copy.js

@@ -0,0 +1,89 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_primordials_object = require('../primordials/object.js');
+const require_paths__internal = require('../paths/_internal.js');
+const require_node_fs = require('../node/fs.js');
+const require_node_path = require('../node/path.js');
+const require_fs_safe = require('./safe.js');
+const require_fs_unique = require('./unique.js');
+
+//#region src/fs/copy.ts
+/**
+* @file Recursive copy for a file or directory tree, with three destination
+*   modes (see {@link CopyMode}). Plain `fs.cp` (even with `force`) overwrites
+*   files present in the source but never deletes destination files absent from
+*   it, so copying onto an existing target leaves stale leftovers behind. The
+*   `'pave'` mode makes the destination an exact copy of the source by staging
+*   a fresh tree in a sibling temp directory and swapping it in with a single
+*   rename — atomic, with no stale survivors.
+*/
+/**
+* Named values for {@link CopyMode}. A frozen object rather than a TypeScript
+* `enum` so the declaration is erasable (enums emit runtime helper code).
+*/
+const CopyMode = require_primordials_object.ObjectFreeze({
+	Fill: "fill",
+	Overlay: "overlay",
+	Pave: "pave"
+});
+/**
+* Recursively copy a file or directory tree from `from` to `to`.
+*
+* Works for both files and directories. The `mode` option chooses how an
+* existing destination is treated — overlay (default), pave, or fill; see
+* {@link CopyMode}.
+*
+* @example
+*   ;```ts
+*   // Overlay (default) — overwrite collisions, keep files already in dest:
+*   await copy('./src', './dest')
+*
+*   // Pave — dest ends up identical to src, no stale survivors:
+*   await copy('./vendor/upstream', './deps/upstream', { mode: CopyMode.Pave })
+*
+*   // Fill — add only what's missing, never overwrite an existing file:
+*   await copy('./defaults', './config', { mode: CopyMode.Fill })
+*   ```
+*
+* @param from - Source file or directory to copy.
+* @param to - Destination path.
+* @param options - Copy options (mode, filter, dereference, abort signal).
+*/
+async function copy(from, to, options) {
+	const fs = require_node_fs.getNodeFs();
+	const opts = {
+		__proto__: null,
+		...options
+	};
+	const { mode } = opts;
+	const fromStr = require_paths__internal.pathLikeToString(from);
+	const toStr = require_paths__internal.pathLikeToString(to);
+	const cpOptions = {
+		__proto__: null,
+		dereference: opts.dereference === true,
+		force: mode !== CopyMode.Fill,
+		recursive: true,
+		...opts.filter ? { filter: opts.filter } : {}
+	};
+	if (mode !== CopyMode.Pave) {
+		await fs.promises.cp(fromStr, toStr, cpOptions);
+		return;
+	}
+	const path = require_node_path.getNodePath();
+	const tmp = require_fs_unique.uniqueSync(`${toStr}.tmp`);
+	try {
+		await fs.promises.cp(fromStr, tmp, cpOptions);
+		await require_fs_safe.safeMkdir(path.dirname(toStr));
+		await require_fs_safe.safeDelete(toStr, { signal: opts.signal });
+		await fs.promises.rename(tmp, toStr);
+	} catch (e) {
+		/* c8 ignore start - best-effort cleanup of the staged copy on failure */
+		await require_fs_safe.safeDelete(tmp, { signal: opts.signal });
+		throw e;
+	}
+}
+
+//#endregion
+exports.CopyMode = CopyMode;
+exports.copy = copy;

package/dist/fs/find.js

@@ -2,11 +2,11 @@
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_runtime = require('../_virtual/_rolldown/runtime.js');
+const require_arrays_predicates = require('../arrays/predicates.js');
 const require_paths_normalize = require('../paths/normalize.js');
 const require_node_fs = require('../node/fs.js');
 const require_node_path = require('../node/path.js');
 const require_process_abort = require('../process/abort.js');
-const require_arrays_predicates = require('../arrays/predicates.js');
 const require_smol_path = require('../smol/path.js');
 const require_paths_walk = require('../paths/walk.js');
 let node_process = require("node:process");

package/dist/fs/read-json-cache.d.ts

@@ -30,6 +30,13 @@
  *     CWDs would get separate cache entries — correct but pessimistic.
  */
 import type { JsonValue } from '../json/types';
+export interface CacheEntry {
+    ino: number;
+    size: number;
+    mtimeMs: number;
+    parsed: JsonValue;
+    insertedAt: number;
+}
 /**
  * Drop all cached entries. Tests call this between cases that depend on a fresh
  * read; long-running daemons can call it on file-watcher invalidation events

package/dist/fs/resolve-module.js

@@ -3,9 +3,9 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_runtime = require('../_virtual/_rolldown/runtime.js');
 const require_node_path = require('../node/path.js');
-let node_module = require("node:module");
 let node_process = require("node:process");
 node_process = require_runtime.__toESM(node_process);
+let node_module = require("node:module");
 
 //#region src/fs/resolve-module.ts
 /**
@@ -32,7 +32,11 @@ function requireResolveFrom(fromDir, specifier, options) {
 	}
 }
 function requireResolveFromCwd(specifier, options) {
-	return options && options.nothrow ? requireResolveFrom(node_process.default.cwd(), specifier, { nothrow: true }) : requireResolveFrom(node_process.default.cwd(), specifier);
+	options = {
+		__proto__: null,
+		...options
+	};
+	return options?.nothrow ? requireResolveFrom(node_process.default.cwd(), specifier, { nothrow: true }) : requireResolveFrom(node_process.default.cwd(), specifier);
 }
 
 //#endregion

package/dist/fs/safe.js

@@ -2,13 +2,13 @@
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_primordials_string = require('../primordials/string.js');
+const require_arrays_predicates = require('../arrays/predicates.js');
 const require_paths__internal = require('../paths/_internal.js');
 const require_primordials_array = require('../primordials/array.js');
 const require_node_fs = require('../node/fs.js');
 const require_node_path = require('../node/path.js');
 const require_errors_predicates = require('../errors/predicates.js');
 const require_primordials_globals = require('../primordials/globals.js');
-const require_arrays_predicates = require('../arrays/predicates.js');
 const require_objects_mutate = require('../objects/mutate.js');
 const require_promises_retry = require('../promises/retry.js');
 const require_fs__internal = require('./_internal.js');

package/dist/git/_internal.js

@@ -2,20 +2,20 @@
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_primordials_buffer = require('../primordials/buffer.js');
+const require_primordials_object = require('../primordials/object.js');
 const require_primordials_string = require('../primordials/string.js');
+const require_primordials_map_set = require('../primordials/map-set.js');
 const require_paths_normalize = require('../paths/normalize.js');
 const require_primordials_array = require('../primordials/array.js');
-const require_primordials_map_set = require('../primordials/map-set.js');
 const require_node_path = require('../node/path.js');
 const require_primordials_date = require('../primordials/date.js');
 const require_primordials_json = require('../primordials/json.js');
-const require_primordials_object = require('../primordials/object.js');
 const require_bin_which = require('../bin/which.js');
 const require_ansi_strip = require('../ansi/strip.js');
 const require_process_spawn_child = require('../process/spawn/child.js');
+const require_git_repo = require('./repo.js');
 const require_debug_output = require('../debug/output.js');
 const require_globs_matcher = require('../globs/matcher.js');
-const require_git_repo = require('./repo.js');
 
 //#region src/git/_internal.ts
 /**

package/dist/git/repo.js

@@ -1,12 +1,10 @@
 "use strict";
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_runtime = require('../_virtual/_rolldown/runtime.js');
 const require_primordials_map_set = require('../primordials/map-set.js');
 const require_node_fs = require('../node/fs.js');
 const require_node_path = require('../node/path.js');
-let node_process = require("node:process");
-node_process = require_runtime.__toESM(node_process);
+const require_primordials_process = require('../primordials/process.js');
 
 //#region src/git/repo.ts
 /**
@@ -112,7 +110,7 @@ function getCachedRealpath(pathname) {
 * @returns The resolved real path of `process.cwd()`.
 */
 function getCwd() {
-	return getCachedRealpath(node_process.default.cwd());
+	return getCachedRealpath(require_primordials_process.processCwd());
 }
 
 //#endregion

package/dist/git/staged.js

@@ -44,6 +44,10 @@ const require_git__internal = require('./_internal.js');
 * @returns Promise resolving to array of staged file paths.
 */
 async function getStagedFiles(options) {
+	options = {
+		__proto__: null,
+		...options
+	};
 	const args = require_git__internal.getGitDiffSpawnArgs(options?.cwd).staged;
 	return await require_git__internal.innerDiff(args, options);
 }
@@ -79,6 +83,10 @@ async function getStagedFiles(options) {
 * @returns Array of staged file paths.
 */
 function getStagedFilesSync(options) {
+	options = {
+		__proto__: null,
+		...options
+	};
 	const args = require_git__internal.getGitDiffSpawnArgs(options?.cwd).staged;
 	return require_git__internal.innerDiffSync(args, options);
 }

package/dist/git/tracked.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @file Tracked-status + submodule-membership probes for a working-tree path.
+ *   `isTracked` answers "does git track this exact path?"; `getSubmodulePaths`
+ *   lists the repo's submodule mount points; `isInSubmodule` answers "does this
+ *   path live inside one?"; `isUntrackedNonSubmodulePath` composes them into
+ *   the safe-to-touch condition for cleanup tooling — never delete a tracked
+ *   file or reach into a submodule's own tree (which would dirty it).
+ */
+/**
+ * The repo's submodule mount points as normalized, repo-root-relative paths
+ * (e.g. `vendor/acorn`). Reads `git config` on `.gitmodules`, so it lists
+ * declared submodules whether or not they are initialized — the case a
+ * stderr-message check on `git ls-files` misses.
+ *
+ * @example
+ *   ;```typescript
+ *   await getSubmodulePaths()
+ *   // => ['packages/acorn/upstream/acorn', 'vendor/mbedtls']
+ *   ```
+ */
+export declare function getSubmodulePaths(options?: GitPathOptions | undefined): Promise<string[]>;
+/**
+ * Whether `targetPath` lives inside one of the repo's submodules. Resolves the
+ * submodule list itself; for a batch sweep prefer `getSubmodulePaths` once plus
+ * `pathIsUnderSubmodule` per path.
+ *
+ * @example
+ *   ;```typescript
+ *   await isInSubmodule('vendor/mbedtls/x.py')  // => true
+ *   await isInSubmodule('src/index.ts')         // => false
+ *   ```
+ */
+export declare function isInSubmodule(targetPath: string, options?: GitPathOptions | undefined): Promise<boolean>;
+export interface GitPathOptions {
+    /**
+     * The git working-tree directory the path is resolved against.
+     *
+     * @default process.cwd()
+     */
+    cwd?: string | undefined;
+}
+/**
+ * Whether git tracks `targetPath` exactly. Uses `git ls-files --error-unmatch`,
+ * which exits non-zero for an untracked path. A path inside a submodule, or one
+ * git does not know, returns `false`.
+ *
+ * @example
+ *   ;```typescript
+ *   await isTracked('src/index.ts')        // => true
+ *   await isTracked('.DS_Store')           // => false
+ *   ```
+ */
+export declare function isTracked(targetPath: string, options?: GitPathOptions | undefined): Promise<boolean>;
+/**
+ * Whether `targetPath` is git does NOT track AND does not live inside a
+ * submodule — the safe-to-touch condition for cleanup tooling. A tracked path
+ * is a deliberate file; a submodule-internal path belongs to that submodule's
+ * own git (touching it would dirty the submodule). Composes `isTracked` +
+ * `getSubmodulePaths`/`pathIsUnderSubmodule`. Fails closed — any check error
+ * resolves to `false`.
+ *
+ * For a batch sweep, call `getSubmodulePaths` once and compose `isTracked` +
+ * `pathIsUnderSubmodule` per path to avoid re-reading `.gitmodules` each time.
+ *
+ * @example
+ *   ;```typescript
+ *   await isUntrackedNonSubmodulePath('.DS_Store')        // => true
+ *   await isUntrackedNonSubmodulePath('src/index.ts')     // => false (tracked)
+ *   await isUntrackedNonSubmodulePath('vendor/sub/x.pyc') // => false (submodule)
+ *   ```
+ */
+export declare function isUntrackedNonSubmodulePath(targetPath: string, options?: GitPathOptions | undefined): Promise<boolean>;
+/**
+ * Whether `relativePath` (repo-root-relative) lies at or under any of
+ * `submodulePaths`. Pure — pass the result of `getSubmodulePaths` so the git
+ * read happens once for a whole sweep.
+ *
+ * @example
+ *   ;```typescript
+ *   pathIsUnderSubmodule('vendor/mbedtls/scripts/__pycache__', ['vendor/mbedtls'])
+ *   // => true
+ *   ```
+ */
+export declare function pathIsUnderSubmodule(relativePath: string, submodulePaths: string[]): boolean;