@augment-vir/node 31.44.0 → 31.46.0

package/dist/augments/fs/grep.d.ts

@@ -0,0 +1,183 @@
+import { type PartialWithUndefined } from '@augment-vir/common';
+import { type IsEqual, type RequireExactlyOne } from 'type-fest';
+/**
+ * Optional options for {@link grep}.
+ *
+ * @category Internal
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export type GrepOptions<CountOnly extends boolean = false> = PartialWithUndefined<{
+    patternSyntax: RequireExactlyOne<{
+        /**
+         * -E, --extended-regexp: Interpret PATTERNS as extended regular expressions (EREs, see
+         * below).
+         */
+        extendedRegExp: true;
+        /** -F, --fixed-strings: Interpret PATTERNS as fixed strings, not regular expressions. */
+        fixedStrings: true;
+        /**
+         * -G, --basic-regexp: Interpret PATTERNS as basic regular expressions (BREs, see below).
+         * This is the default.
+         */
+        basicRegExp: true;
+    }>;
+    /**
+     * If set to true, sets: -i, --ignore-case: Ignore case distinctions in patterns and input data,
+     * so that characters that differ only in case match each other.
+     */
+    ignoreCase: boolean;
+    /** -v, --invert-match: Invert the sense of matching, to select non-matching lines. */
+    invertMatch: boolean;
+    matchType: RequireExactlyOne<{
+        /**
+         * -w, --word-regexp: Select only those lines containing matches that form whole words. The
+         * test is that the matching substring must either be at the beginning of the line, or
+         * preceded by a non-word constituent character. Similarly, it must be either at the end of
+         * the line or followed by a non-word constituent character. Word-constituent characters are
+         * letters, digits, and the underscore. This option has no effect if -x is also specified.
+         */
+        wordRegExp: true;
+        /**
+         * -x, --line-regexp: Select only those matches that exactly match the whole line. For a
+         * regular expression pattern, this is like parenthesizing the pattern and then surrounding
+         * it with ^ and $.
+         */
+        lineRegExp: true;
+    }>;
+    output: RequireExactlyOne<{
+        /**
+         * -c, --count: Suppress normal output; instead print a count of matching lines for each
+         * input file. With the -v, --invert-match option (see above), count non-matching lines.
+         */
+        countOnly: CountOnly;
+        /**
+         * -l, --files-with-matches: Suppress normal output; instead print the name of each input
+         * file from which output would normally have been printed. Scanning each input file stops
+         * upon first match.
+         */
+        filesOnly: true;
+    }>;
+    /**
+     * --exclude=GLOB: Skip any command-line file with a name suffix that matches the pattern GLOB,
+     * using wildcard matching; a name suffix is either the whole name, or a trailing part that
+     * starts with a non-slash character immediately after a slash (/) in the name. When searching
+     * recursively, skip any subfile whose base name matches GLOB; the base name is the part after
+     * the last slash. A pattern can use *, ?, and [...] as wildcards, and \ to quote a wildcard or
+     * backslash character literally.
+     */
+    excludePatterns: string[];
+    /**
+     * -m NUM, --max-count=NUM: Stop reading a file after NUM matching lines. If NUM is zero, grep
+     * stops right away without reading input. A NUM of -1 is treated as infinity and grep does not
+     * stop; this is the default. If the input is standard input from a regular file, and NUM
+     * matching lines are output, grep ensures that the standard input is positioned to just after
+     * the last matching line before exiting, regardless of the presence of trailing context lines.
+     * This enables a calling process to resume a search. When grep stops after NUM matching lines,
+     * it outputs any trailing context lines. When the -c or --count option is also used, grep does
+     * not output a count greater than NUM. When the -v or --invert-match option is also used, grep
+     * stops after outputting NUM non-matching lines.
+     */
+    maxCount: number;
+    /**
+     * -r, --recursive: Read all files under each directory, recursively, following symbolic links
+     * only if they are on the command line. Note that if no file operand is given, grep searches
+     * the working directory. This is equivalent to the -d recurse option.
+     */
+    recursive: boolean;
+    /**
+     * If `true`, sets `--dereference-recursive` instead of `--recursive` when searching
+     * recursively.
+     *
+     * -R, --dereference-recursive: Read all files under each directory, recursively. Follow all
+     * symbolic links, unlike -r.
+     */
+    followSymLinks: boolean;
+    /**
+     * -U, --binary: Treat the file(s) as binary. By default, under MS-DOS and MS-Windows, grep
+     * guesses whether a file is text or binary as described for the --binary-files option. If grep
+     * decides the file is a text file, it strips the CR characters from the original file contents
+     * (to make regular expressions with ^ and $ work correctly). Specifying -U overrules this
+     * guesswork, causing all files to be read and passed to the matching mechanism verbatim; if the
+     * file is a text file with CR/LF pairs at the end of each line, this will cause some regular
+     * expressions to fail. This option has no effect on platforms other than MS-DOS and MS-
+     * Windows.
+     */
+    binary: boolean;
+    /**
+     * --exclude-dir=GLOB: Skip any command-line directory with a name suffix that matches the
+     * pattern GLOB. When searching recursively, skip any subdirectory whose base name matches GLOB.
+     * Ignore any redundant trailing slashes in GLOB.
+     */
+    excludeDirs: string[];
+    /**
+     * --include=GLOB: Search only files whose base name matches GLOB (using wildcard matching as
+     * described under --exclude). If contradictory --include and --exclude options are given, the
+     * last matching one wins. If no --include or --exclude options match, a file is included unless
+     * the first such option is --include.
+     */
+    includeFiles: string[];
+    /** Debugging option: if set to `true`, the grep CLI command will be printed before execution. */
+    printCommand: boolean;
+    /** The directory where the grep command where be run within. */
+    cwd: string;
+}>;
+/**
+ * Search location options for {@link grep}.
+ *
+ * @category Internal
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export type GrepSearchLocation = RequireExactlyOne<{
+    /** Search within multiple files. */
+    files: string[];
+    /**
+     * Search within multiple directories. Set `recursive` to `true` in options to search the
+     * directory recursively.
+     */
+    dirs: string[];
+    /**
+     * Search within a single directory. Set `recursive` to `true` in options to search the
+     * directory recursively.
+     */
+    dir: string;
+    /** Search within a single file. */
+    file: string;
+}>;
+/**
+ * Search pattern options for {@link grep}.
+ *
+ * @category Internal
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export type GrepSearchPattern = RequireExactlyOne<{
+    pattern: string;
+    patterns: string[];
+}>;
+/**
+ * Output of {@link grep}. Each key is an absolute file path. Values are array of matches lines for
+ * that file.
+ *
+ * @category Internal
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export type GrepMatches<CountOnly extends boolean = false> = IsEqual<CountOnly, true> extends true ? {
+    [FileName in string]: number;
+} : IsEqual<CountOnly, false> extends true ? {
+    [FileName in string]: string[];
+} : {
+    [FileName in string]: number;
+} | {
+    [FileName in string]: string[];
+};
+/**
+ * Run `grep`, matching patterns to specific lines in files or directories.
+ *
+ * @category Node : File
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export declare function grep<const CountOnly extends boolean = false>(grepSearchPattern: Readonly<GrepSearchPattern>, grepSearchLocation: Readonly<GrepSearchLocation>, options?: Readonly<GrepOptions<CountOnly>>): Promise<GrepMatches<CountOnly>>;

package/dist/augments/fs/grep.js

@@ -0,0 +1,153 @@
+import { assert, check } from '@augment-vir/assert';
+import { arrayToObject, getOrSet, log, safeMatch, } from '@augment-vir/common';
+import { join } from 'node:path';
+import { runShellCommand } from '../terminal/shell.js';
+function escape(input) {
+    return input.replaceAll('"', String.raw `\"`).replaceAll('\n', '');
+}
+/**
+ * Run `grep`, matching patterns to specific lines in files or directories.
+ *
+ * @category Node : File
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export async function grep(grepSearchPattern, grepSearchLocation, options = {}) {
+    const searchPatterns = (grepSearchPattern.patterns || [grepSearchPattern.pattern]).filter(check.isTruthy);
+    if (!searchPatterns.length) {
+        return {};
+    }
+    const searchLocation = grepSearchLocation.files
+        ? {
+            files: grepSearchLocation.files,
+        }
+        : grepSearchLocation.file
+            ? {
+                files: [grepSearchLocation.file],
+            }
+            : grepSearchLocation.dirs
+                ? {
+                    dirs: grepSearchLocation.dirs,
+                }
+                : grepSearchLocation.dir
+                    ? {
+                        dirs: [grepSearchLocation.dir],
+                    }
+                    : undefined;
+    if (!searchLocation ||
+        (searchLocation.dirs && !searchLocation.dirs.length) ||
+        (searchLocation.files && !searchLocation.files.length)) {
+        return {};
+    }
+    const searchParts = searchLocation.dirs
+        ? options.recursive
+            ? searchLocation.dirs
+            : searchLocation.dirs.map((dir) => join(dir, '*'))
+        : searchLocation.files;
+    const fullCommand = [
+        'grep',
+        options.patternSyntax?.basicRegExp
+            ? '--basic-regexp'
+            : options.patternSyntax?.extendedRegExp
+                ? '--extended-regexp'
+                : options.patternSyntax?.fixedStrings
+                    ? '--fixed-strings'
+                    : '',
+        options.ignoreCase ? '--ignore-case' : '',
+        options.invertMatch && !options.output?.filesOnly ? '--invert-match' : '',
+        options.matchType?.wordRegExp
+            ? '--word-regexp'
+            : options.matchType?.lineRegExp
+                ? '--line-regexp'
+                : '',
+        options.output?.countOnly
+            ? '--count'
+            : options.output?.filesOnly
+                ? options.invertMatch
+                    ? '--files-without-match'
+                    : '--files-with-matches'
+                : '',
+        '--color=never',
+        options.maxCount ? `--max-count=${options.maxCount}` : '',
+        '--no-messages',
+        '--with-filename',
+        '--null',
+        ...(options.excludePatterns?.length
+            ? options.excludePatterns.map((excludePattern) => `--exclude="${escape(excludePattern)}"`)
+            : []),
+        options.recursive
+            ? options.followSymLinks
+                ? '-RS'
+                : '--recursive'
+            : '',
+        ...(options.excludeDirs?.length
+            ? options.excludeDirs.map((excludeDir) => `--exclude-dir="${escape(excludeDir)}"`)
+            : []),
+        ...(options.includeFiles?.length
+            ? options.includeFiles.map((includeFile) => `--include="${escape(includeFile)}"`)
+            : []),
+        options.binary ? '--binary' : '',
+        ...searchPatterns.map((searchPattern) => `-e "${searchPattern}"`),
+        ...searchParts,
+    ]
+        .filter(check.isTruthy)
+        .join(' ');
+    if (options.printCommand) {
+        log.faint(`> ${fullCommand}`);
+    }
+    const result = await runShellCommand(fullCommand, {
+        cwd: options.cwd,
+    });
+    const trimmedOutput = result.stdout.trim();
+    if (result.exitCode === 1 || !trimmedOutput) {
+        /** No matches. */
+        return {};
+    }
+    else if (options.output?.countOnly) {
+        return arrayToObject(trimmedOutput.split(/[\0\n]/), (entry) => {
+            /** Ignore empty strings. */
+            /* node:coverage ignore next 3 */
+            if (!entry) {
+                return undefined;
+            }
+            const [, fileName, countString,] = safeMatch(entry, /(^.+):(\d+)$/);
+            assert.isDefined(fileName, `Failed parse grep file name from: '${entry}'`);
+            const count = Number(countString);
+            assert.isNumber(count, `Failed to parse grep number from: '${entry}'`);
+            if (!count) {
+                return undefined;
+            }
+            return {
+                key: fileName,
+                value: count,
+            };
+        }, {
+            useRequired: true,
+        });
+    }
+    else if (options.output?.filesOnly) {
+        return arrayToObject(trimmedOutput.split(/[\0\n]/), (entry) => {
+            /** Ignore empty strings. */
+            if (!entry) {
+                return undefined;
+            }
+            return {
+                key: entry,
+                value: [],
+            };
+        }, {
+            useRequired: true,
+        });
+    }
+    else {
+        const outputLines = trimmedOutput.split(/[\0\n]/);
+        const fileMatches = {};
+        outputLines.forEach((line, index) => {
+            if (!(index % 2)) {
+                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+                getOrSet(fileMatches, line, () => []).push(outputLines[index + 1]);
+            }
+        });
+        return fileMatches;
+    }
+}

package/dist/augments/npm/npm-deps.d.ts

@@ -0,0 +1,38 @@
+/**
+ * All `package.json` keys that are parsed as direct dependencies.
+ *
+ * @category Internal
+ */
+export declare enum PackageJsonDependencyKey {
+    DevDependencies = "devDependencies",
+    Dependencies = "dependencies",
+    PeerDependencies = "peerDependencies"
+}
+/**
+ * A record of package names to package versions included in the direct dependencies. This is the
+ * output from {@link listAllDirectNpmDeps}.
+ *
+ * @category Internal
+ */
+export type NpmDeps = Record<string, NpmDep[]>;
+export type NpmDep = {
+    /** Path to the `package.json` file that depends on this. */
+    requiredBy: string;
+    dependencyKey: PackageJsonDependencyKey;
+    /**
+     * The version as it is directly noted in the `package.json` file. This might not necessarily
+     * correlate to any actually published versions.
+     */
+    versionValue: string;
+    /** If true, this dependency is part of the workspace's own packages. */
+    isWorkspace: boolean;
+};
+/**
+ * Finds all direct deps for the workspace at, or that contains, the given dir path.
+ *
+ * @category Node : Npm
+ * @category Package : @augment-vir/node
+ * @throws If no directory with a `package-lock.json` file is found.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export declare function listAllDirectNpmDeps(startDirPath: string): Promise<NpmDeps>;

package/dist/augments/npm/npm-deps.js

@@ -0,0 +1,47 @@
+import { check } from '@augment-vir/assert';
+import { filterMap, getEnumValues, getObjectTypedEntries, getOrSet } from '@augment-vir/common';
+import { readJsonFile } from '../fs/json.js';
+import { findAllPackageJsonFilePaths } from './package-json.js';
+/**
+ * All `package.json` keys that are parsed as direct dependencies.
+ *
+ * @category Internal
+ */
+export var PackageJsonDependencyKey;
+(function (PackageJsonDependencyKey) {
+    PackageJsonDependencyKey["DevDependencies"] = "devDependencies";
+    PackageJsonDependencyKey["Dependencies"] = "dependencies";
+    PackageJsonDependencyKey["PeerDependencies"] = "peerDependencies";
+})(PackageJsonDependencyKey || (PackageJsonDependencyKey = {}));
+/**
+ * Finds all direct deps for the workspace at, or that contains, the given dir path.
+ *
+ * @category Node : Npm
+ * @category Package : @augment-vir/node
+ * @throws If no directory with a `package-lock.json` file is found.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export async function listAllDirectNpmDeps(startDirPath) {
+    const packageJsonFilePaths = await findAllPackageJsonFilePaths(startDirPath);
+    const deps = {};
+    const packageJsonFiles = await Promise.all(packageJsonFilePaths.map(async (packageJsonFilePath) => {
+        return {
+            packageJsonFilePath,
+            packageJson: (await readJsonFile(packageJsonFilePath)),
+        };
+    }));
+    const allWorkspacePackageNames = filterMap(packageJsonFiles, (packageJsonFile) => packageJsonFile.packageJson.name, check.isTruthy);
+    packageJsonFiles.forEach(({ packageJson, packageJsonFilePath }) => {
+        getEnumValues(PackageJsonDependencyKey).forEach((dependencyKey) => {
+            getObjectTypedEntries(packageJson[dependencyKey] || {}).forEach(([dependencyName, versionValue,]) => {
+                getOrSet(deps, dependencyName, () => []).push({
+                    dependencyKey,
+                    requiredBy: packageJsonFilePath,
+                    versionValue,
+                    isWorkspace: allWorkspacePackageNames.includes(dependencyName),
+                });
+            });
+        });
+    });
+    return deps;
+}

package/dist/augments/npm/package-json.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Finds all `package.json` files contained within the workspaces present in the current
+ * `startDirPath`. A workspace root dir is found by recursively looking for a parent
+ * `package-lock.json` file.
+ *
+ * @category Node : Npm
+ * @category Package : @augment-vir/node
+ * @throws If no directory with a `package-lock.json` file is found.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export declare function findAllPackageJsonFilePaths(startDirPath: string): Promise<string[]>;
+/**
+ * Get all workspace package.json paths starting at the given directory path. The output is string
+ * sorted to keep it stable.
+ *
+ * @category Node : Npm
+ * @category Package : @augment-vir/node
+ * @throws Error if there is no `package.json` file at the given `rootDirPath`.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export declare function getWorkspacePackageJsonFilePaths(rootDirPath: string): Promise<string[]>;

package/dist/augments/npm/package-json.js

@@ -0,0 +1,48 @@
+import { check } from '@augment-vir/assert';
+import { filterMap, fromAsyncIterable } from '@augment-vir/common';
+import { existsSync } from 'node:fs';
+import { glob, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { findAncestor, joinFilesToDir } from '../path/ancestor.js';
+/**
+ * Finds all `package.json` files contained within the workspaces present in the current
+ * `startDirPath`. A workspace root dir is found by recursively looking for a parent
+ * `package-lock.json` file.
+ *
+ * @category Node : Npm
+ * @category Package : @augment-vir/node
+ * @throws If no directory with a `package-lock.json` file is found.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export async function findAllPackageJsonFilePaths(startDirPath) {
+    const packageRootDir = findAncestor(startDirPath, (dir) => existsSync(join(dir, 'package-lock.json')));
+    if (!packageRootDir) {
+        throw new Error(`Cannot find all package.json files: failed to find any directory with a package-lock.json file. Started at '${startDirPath}'.`);
+    }
+    const rootPackageJsonPath = join(packageRootDir, 'package.json');
+    return [
+        rootPackageJsonPath,
+        ...(await getWorkspacePackageJsonFilePaths(packageRootDir)),
+    ];
+}
+/**
+ * Get all workspace package.json paths starting at the given directory path. The output is string
+ * sorted to keep it stable.
+ *
+ * @category Node : Npm
+ * @category Package : @augment-vir/node
+ * @throws Error if there is no `package.json` file at the given `rootDirPath`.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export async function getWorkspacePackageJsonFilePaths(rootDirPath) {
+    const packageJson = JSON.parse(await readFile(join(rootDirPath, 'package.json'), 'utf8'));
+    /* node:coverage ignore next 3: this package only uses one type of workspace */
+    const patterns = check.isArray(packageJson.workspaces)
+        ? packageJson.workspaces
+        : packageJson.workspaces?.packages || [];
+    const matchedPaths = joinFilesToDir(rootDirPath, (await Promise.all(patterns.map(async (pattern) => {
+        return await fromAsyncIterable(glob(pattern, { cwd: rootDirPath }));
+    }))).flat());
+    const workspacePackageJsonPaths = filterMap(matchedPaths, (matchedPath) => join(matchedPath, 'package.json'), (packageJsonPath) => existsSync(packageJsonPath));
+    return workspacePackageJsonPaths.sort();
+}

package/dist/index.d.ts

@@ -1,11 +1,14 @@
 export * from './augments/fs/dir-contents.js';
 export * from './augments/fs/download.js';
+export * from './augments/fs/grep.js';
 export * from './augments/fs/json.js';
 export * from './augments/fs/read-dir.js';
 export * from './augments/fs/read-file.js';
 export * from './augments/fs/symlink.js';
 export * from './augments/fs/write.js';
 export * from './augments/npm/find-bin-path.js';
+export * from './augments/npm/npm-deps.js';
+export * from './augments/npm/package-json.js';
 export * from './augments/npm/query-workspace.js';
 export * from './augments/npm/read-package-json.js';
 export * from './augments/os/operating-system.js';

package/dist/index.js

@@ -1,11 +1,14 @@
 export * from './augments/fs/dir-contents.js';
 export * from './augments/fs/download.js';
+export * from './augments/fs/grep.js';
 export * from './augments/fs/json.js';
 export * from './augments/fs/read-dir.js';
 export * from './augments/fs/read-file.js';
 export * from './augments/fs/symlink.js';
 export * from './augments/fs/write.js';
 export * from './augments/npm/find-bin-path.js';
+export * from './augments/npm/npm-deps.js';
+export * from './augments/npm/package-json.js';
 export * from './augments/npm/query-workspace.js';
 export * from './augments/npm/read-package-json.js';
 export * from './augments/os/operating-system.js';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@augment-vir/node",
-    "version": "31.44.0",
+    "version": "31.46.0",
     "description": "A collection of augments, helpers types, functions, and classes only for Node.js (backend) JavaScript environments.",
     "keywords": [
         "augment",
@@ -38,8 +38,8 @@
         "test:update": "npm test"
     },
     "dependencies": {
-        "@augment-vir/assert": "^31.44.0",
-        "@augment-vir/common": "^31.44.0",
+        "@augment-vir/assert": "^31.46.0",
+        "@augment-vir/common": "^31.46.0",
         "@date-vir/duration": "^8.0.0",
         "ansi-styles": "^6.2.3",
         "sanitize-filename": "^1.6.3",
@@ -49,7 +49,7 @@
         "typed-event-target": "^4.1.0"
     },
     "devDependencies": {
-        "@augment-vir/test": "^31.44.0",
+        "@augment-vir/test": "^31.46.0",
         "@types/node": "^24.9.1",
         "@web/dev-server-esbuild": "^1.0.4",
         "@web/test-runner": "^0.20.2",

package/src/augments/fs/grep.ts

@@ -0,0 +1,379 @@
+import {assert, check} from '@augment-vir/assert';
+import {
+    arrayToObject,
+    getOrSet,
+    log,
+    safeMatch,
+    type PartialWithUndefined,
+    type SelectFrom,
+} from '@augment-vir/common';
+import {join} from 'node:path';
+import {type IsEqual, type RequireExactlyOne} from 'type-fest';
+import {runShellCommand} from '../terminal/shell.js';
+
+/**
+ * Optional options for {@link grep}.
+ *
+ * @category Internal
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export type GrepOptions<CountOnly extends boolean = false> = PartialWithUndefined<{
+    patternSyntax: RequireExactlyOne<{
+        /**
+         * -E, --extended-regexp: Interpret PATTERNS as extended regular expressions (EREs, see
+         * below).
+         */
+        extendedRegExp: true;
+        /** -F, --fixed-strings: Interpret PATTERNS as fixed strings, not regular expressions. */
+        fixedStrings: true;
+        /**
+         * -G, --basic-regexp: Interpret PATTERNS as basic regular expressions (BREs, see below).
+         * This is the default.
+         */
+        basicRegExp: true;
+    }>;
+    /**
+     * If set to true, sets: -i, --ignore-case: Ignore case distinctions in patterns and input data,
+     * so that characters that differ only in case match each other.
+     */
+    ignoreCase: boolean;
+    /** -v, --invert-match: Invert the sense of matching, to select non-matching lines. */
+    invertMatch: boolean;
+    matchType: RequireExactlyOne<{
+        /**
+         * -w, --word-regexp: Select only those lines containing matches that form whole words. The
+         * test is that the matching substring must either be at the beginning of the line, or
+         * preceded by a non-word constituent character. Similarly, it must be either at the end of
+         * the line or followed by a non-word constituent character. Word-constituent characters are
+         * letters, digits, and the underscore. This option has no effect if -x is also specified.
+         */
+        wordRegExp: true;
+        /**
+         * -x, --line-regexp: Select only those matches that exactly match the whole line. For a
+         * regular expression pattern, this is like parenthesizing the pattern and then surrounding
+         * it with ^ and $.
+         */
+        lineRegExp: true;
+    }>;
+
+    output: RequireExactlyOne<{
+        /**
+         * -c, --count: Suppress normal output; instead print a count of matching lines for each
+         * input file. With the -v, --invert-match option (see above), count non-matching lines.
+         */
+        countOnly: CountOnly;
+        /**
+         * -l, --files-with-matches: Suppress normal output; instead print the name of each input
+         * file from which output would normally have been printed. Scanning each input file stops
+         * upon first match.
+         */
+        filesOnly: true;
+    }>;
+
+    /**
+     * --exclude=GLOB: Skip any command-line file with a name suffix that matches the pattern GLOB,
+     * using wildcard matching; a name suffix is either the whole name, or a trailing part that
+     * starts with a non-slash character immediately after a slash (/) in the name. When searching
+     * recursively, skip any subfile whose base name matches GLOB; the base name is the part after
+     * the last slash. A pattern can use *, ?, and [...] as wildcards, and \ to quote a wildcard or
+     * backslash character literally.
+     */
+    excludePatterns: string[];
+
+    /**
+     * -m NUM, --max-count=NUM: Stop reading a file after NUM matching lines. If NUM is zero, grep
+     * stops right away without reading input. A NUM of -1 is treated as infinity and grep does not
+     * stop; this is the default. If the input is standard input from a regular file, and NUM
+     * matching lines are output, grep ensures that the standard input is positioned to just after
+     * the last matching line before exiting, regardless of the presence of trailing context lines.
+     * This enables a calling process to resume a search. When grep stops after NUM matching lines,
+     * it outputs any trailing context lines. When the -c or --count option is also used, grep does
+     * not output a count greater than NUM. When the -v or --invert-match option is also used, grep
+     * stops after outputting NUM non-matching lines.
+     */
+    maxCount: number;
+    /**
+     * -r, --recursive: Read all files under each directory, recursively, following symbolic links
+     * only if they are on the command line. Note that if no file operand is given, grep searches
+     * the working directory. This is equivalent to the -d recurse option.
+     */
+    recursive: boolean;
+    /**
+     * If `true`, sets `--dereference-recursive` instead of `--recursive` when searching
+     * recursively.
+     *
+     * -R, --dereference-recursive: Read all files under each directory, recursively. Follow all
+     * symbolic links, unlike -r.
+     */
+    followSymLinks: boolean;
+    /**
+     * -U, --binary: Treat the file(s) as binary. By default, under MS-DOS and MS-Windows, grep
+     * guesses whether a file is text or binary as described for the --binary-files option. If grep
+     * decides the file is a text file, it strips the CR characters from the original file contents
+     * (to make regular expressions with ^ and $ work correctly). Specifying -U overrules this
+     * guesswork, causing all files to be read and passed to the matching mechanism verbatim; if the
+     * file is a text file with CR/LF pairs at the end of each line, this will cause some regular
+     * expressions to fail. This option has no effect on platforms other than MS-DOS and MS-
+     * Windows.
+     */
+    binary: boolean;
+    /**
+     * --exclude-dir=GLOB: Skip any command-line directory with a name suffix that matches the
+     * pattern GLOB. When searching recursively, skip any subdirectory whose base name matches GLOB.
+     * Ignore any redundant trailing slashes in GLOB.
+     */
+    excludeDirs: string[];
+    /**
+     * --include=GLOB: Search only files whose base name matches GLOB (using wildcard matching as
+     * described under --exclude). If contradictory --include and --exclude options are given, the
+     * last matching one wins. If no --include or --exclude options match, a file is included unless
+     * the first such option is --include.
+     */
+    includeFiles: string[];
+    /** Debugging option: if set to `true`, the grep CLI command will be printed before execution. */
+    printCommand: boolean;
+    /** The directory where the grep command where be run within. */
+    cwd: string;
+}>;
+
+/**
+ * Search location options for {@link grep}.
+ *
+ * @category Internal
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export type GrepSearchLocation = RequireExactlyOne<{
+    /** Search within multiple files. */
+    files: string[];
+    /**
+     * Search within multiple directories. Set `recursive` to `true` in options to search the
+     * directory recursively.
+     */
+    dirs: string[];
+
+    /**
+     * Search within a single directory. Set `recursive` to `true` in options to search the
+     * directory recursively.
+     */
+    dir: string;
+    /** Search within a single file. */
+    file: string;
+}>;
+
+/**
+ * Search pattern options for {@link grep}.
+ *
+ * @category Internal
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export type GrepSearchPattern = RequireExactlyOne<{
+    pattern: string;
+    patterns: string[];
+}>;
+
+function escape(input: string) {
+    return input.replaceAll('"', String.raw`\"`).replaceAll('\n', '');
+}
+
+/**
+ * Output of {@link grep}. Each key is an absolute file path. Values are array of matches lines for
+ * that file.
+ *
+ * @category Internal
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export type GrepMatches<CountOnly extends boolean = false> =
+    IsEqual<CountOnly, true> extends true
+        ? {[FileName in string]: number}
+        : IsEqual<CountOnly, false> extends true
+          ? {[FileName in string]: string[]}
+          : {[FileName in string]: number} | {[FileName in string]: string[]};
+
+/**
+ * Run `grep`, matching patterns to specific lines in files or directories.
+ *
+ * @category Node : File
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export async function grep<const CountOnly extends boolean = false>(
+    grepSearchPattern: Readonly<GrepSearchPattern>,
+    grepSearchLocation: Readonly<GrepSearchLocation>,
+    options: Readonly<GrepOptions<CountOnly>> = {},
+): Promise<GrepMatches<CountOnly>> {
+    const searchPatterns: string[] = (
+        grepSearchPattern.patterns || [grepSearchPattern.pattern]
+    ).filter(check.isTruthy);
+
+    if (!searchPatterns.length) {
+        return {};
+    }
+
+    const searchLocation: SelectFrom<GrepSearchLocation, {files: true; dirs: true}> | undefined =
+        grepSearchLocation.files
+            ? {
+                  files: grepSearchLocation.files,
+              }
+            : grepSearchLocation.file
+              ? {
+                    files: [grepSearchLocation.file],
+                }
+              : grepSearchLocation.dirs
+                ? {
+                      dirs: grepSearchLocation.dirs,
+                  }
+                : grepSearchLocation.dir
+                  ? {
+                        dirs: [grepSearchLocation.dir],
+                    }
+                  : undefined;
+
+    if (
+        !searchLocation ||
+        (searchLocation.dirs && !searchLocation.dirs.length) ||
+        (searchLocation.files && !searchLocation.files.length)
+    ) {
+        return {};
+    }
+
+    const searchParts = searchLocation.dirs
+        ? options.recursive
+            ? searchLocation.dirs
+            : searchLocation.dirs.map((dir) => join(dir, '*'))
+        : searchLocation.files;
+
+    const fullCommand = [
+        'grep',
+        options.patternSyntax?.basicRegExp
+            ? '--basic-regexp'
+            : options.patternSyntax?.extendedRegExp
+              ? '--extended-regexp'
+              : options.patternSyntax?.fixedStrings
+                ? '--fixed-strings'
+                : '',
+        options.ignoreCase ? '--ignore-case' : '',
+        options.invertMatch && !options.output?.filesOnly ? '--invert-match' : '',
+        options.matchType?.wordRegExp
+            ? '--word-regexp'
+            : options.matchType?.lineRegExp
+              ? '--line-regexp'
+              : '',
+        options.output?.countOnly
+            ? '--count'
+            : options.output?.filesOnly
+              ? options.invertMatch
+                  ? '--files-without-match'
+                  : '--files-with-matches'
+              : '',
+        '--color=never',
+        options.maxCount ? `--max-count=${options.maxCount}` : '',
+        '--no-messages',
+        '--with-filename',
+        '--null',
+        ...(options.excludePatterns?.length
+            ? options.excludePatterns.map(
+                  (excludePattern) => `--exclude="${escape(excludePattern)}"`,
+              )
+            : []),
+        options.recursive
+            ? options.followSymLinks
+                ? '-RS'
+                : '--recursive'
+            : '',
+        ...(options.excludeDirs?.length
+            ? options.excludeDirs.map((excludeDir) => `--exclude-dir="${escape(excludeDir)}"`)
+            : []),
+        ...(options.includeFiles?.length
+            ? options.includeFiles.map((includeFile) => `--include="${escape(includeFile)}"`)
+            : []),
+        options.binary ? '--binary' : '',
+        ...searchPatterns.map((searchPattern) => `-e "${searchPattern}"`),
+        ...searchParts,
+    ]
+        .filter(check.isTruthy)
+        .join(' ');
+
+    if (options.printCommand) {
+        log.faint(`> ${fullCommand}`);
+    }
+
+    const result = await runShellCommand(fullCommand, {
+        cwd: options.cwd,
+    });
+
+    const trimmedOutput = result.stdout.trim();
+
+    if (result.exitCode === 1 || !trimmedOutput) {
+        /** No matches. */
+        return {};
+    } else if (options.output?.countOnly) {
+        return arrayToObject(
+            trimmedOutput.split(/[\0\n]/),
+            (entry) => {
+                /** Ignore empty strings. */
+                /* node:coverage ignore next 3 */
+                if (!entry) {
+                    return undefined;
+                }
+
+                const [
+                    ,
+                    fileName,
+                    countString,
+                ] = safeMatch(entry, /(^.+):(\d+)$/);
+
+                assert.isDefined(fileName, `Failed parse grep file name from: '${entry}'`);
+
+                const count = Number(countString);
+
+                assert.isNumber(count, `Failed to parse grep number from: '${entry}'`);
+                if (!count) {
+                    return undefined;
+                }
+
+                return {
+                    key: fileName,
+                    value: count,
+                };
+            },
+            {
+                useRequired: true,
+            },
+        ) satisfies Record<string, number> as GrepMatches<CountOnly>;
+    } else if (options.output?.filesOnly) {
+        return arrayToObject(
+            trimmedOutput.split(/[\0\n]/),
+            (entry) => {
+                /** Ignore empty strings. */
+                if (!entry) {
+                    return undefined;
+                }
+
+                return {
+                    key: entry,
+                    value: [],
+                };
+            },
+            {
+                useRequired: true,
+            },
+        ) satisfies Record<string, string[]> as GrepMatches<CountOnly>;
+    } else {
+        const outputLines = trimmedOutput.split(/[\0\n]/);
+
+        const fileMatches: Record<string, string[]> = {};
+
+        outputLines.forEach((line, index) => {
+            if (!(index % 2)) {
+                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+                getOrSet(fileMatches, line, () => []).push(outputLines[index + 1]!);
+            }
+        });
+
+        return fileMatches;
+    }
+}

package/src/augments/npm/npm-deps.ts

@@ -0,0 +1,85 @@
+import {check} from '@augment-vir/assert';
+import {filterMap, getEnumValues, getObjectTypedEntries, getOrSet} from '@augment-vir/common';
+import {type PackageJson} from 'type-fest';
+import {readJsonFile} from '../fs/json.js';
+import {findAllPackageJsonFilePaths} from './package-json.js';
+
+/**
+ * All `package.json` keys that are parsed as direct dependencies.
+ *
+ * @category Internal
+ */
+export enum PackageJsonDependencyKey {
+    DevDependencies = 'devDependencies',
+    Dependencies = 'dependencies',
+    PeerDependencies = 'peerDependencies',
+}
+
+/**
+ * A record of package names to package versions included in the direct dependencies. This is the
+ * output from {@link listAllDirectNpmDeps}.
+ *
+ * @category Internal
+ */
+export type NpmDeps = Record<string, NpmDep[]>;
+export type NpmDep = {
+    /** Path to the `package.json` file that depends on this. */
+    requiredBy: string;
+    dependencyKey: PackageJsonDependencyKey;
+    /**
+     * The version as it is directly noted in the `package.json` file. This might not necessarily
+     * correlate to any actually published versions.
+     */
+    versionValue: string;
+    /** If true, this dependency is part of the workspace's own packages. */
+    isWorkspace: boolean;
+};
+
+/**
+ * Finds all direct deps for the workspace at, or that contains, the given dir path.
+ *
+ * @category Node : Npm
+ * @category Package : @augment-vir/node
+ * @throws If no directory with a `package-lock.json` file is found.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export async function listAllDirectNpmDeps(startDirPath: string): Promise<NpmDeps> {
+    const packageJsonFilePaths = await findAllPackageJsonFilePaths(startDirPath);
+
+    const deps: NpmDeps = {};
+
+    const packageJsonFiles = await Promise.all(
+        packageJsonFilePaths.map(async (packageJsonFilePath) => {
+            return {
+                packageJsonFilePath,
+                packageJson: (await readJsonFile(packageJsonFilePath)) as PackageJson,
+            };
+        }),
+    );
+
+    const allWorkspacePackageNames = filterMap(
+        packageJsonFiles,
+        (packageJsonFile) => packageJsonFile.packageJson.name,
+        check.isTruthy,
+    );
+
+    packageJsonFiles.forEach(({packageJson, packageJsonFilePath}) => {
+        getEnumValues(PackageJsonDependencyKey).forEach((dependencyKey) => {
+            getObjectTypedEntries(packageJson[dependencyKey] || {}).forEach(
+                ([
+                    dependencyName,
+                    versionValue,
+                ]) => {
+                    getOrSet(deps, dependencyName, () => []).push({
+                        dependencyKey,
+                        requiredBy: packageJsonFilePath,
+                        versionValue,
+                        isWorkspace: allWorkspacePackageNames.includes(dependencyName),
+                    });
+                },
+            );
+        });
+    });
+
+    return deps;
+}

package/src/augments/npm/package-json.ts

@@ -0,0 +1,75 @@
+import {check} from '@augment-vir/assert';
+import {filterMap, fromAsyncIterable} from '@augment-vir/common';
+import {existsSync} from 'node:fs';
+import {glob, readFile} from 'node:fs/promises';
+import {join} from 'node:path';
+import {type PackageJson} from 'type-fest';
+import {findAncestor, joinFilesToDir} from '../path/ancestor.js';
+
+/**
+ * Finds all `package.json` files contained within the workspaces present in the current
+ * `startDirPath`. A workspace root dir is found by recursively looking for a parent
+ * `package-lock.json` file.
+ *
+ * @category Node : Npm
+ * @category Package : @augment-vir/node
+ * @throws If no directory with a `package-lock.json` file is found.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export async function findAllPackageJsonFilePaths(startDirPath: string) {
+    const packageRootDir = findAncestor(startDirPath, (dir) =>
+        existsSync(join(dir, 'package-lock.json')),
+    );
+
+    if (!packageRootDir) {
+        throw new Error(
+            `Cannot find all package.json files: failed to find any directory with a package-lock.json file. Started at '${startDirPath}'.`,
+        );
+    }
+
+    const rootPackageJsonPath = join(packageRootDir, 'package.json');
+
+    return [
+        rootPackageJsonPath,
+        ...(await getWorkspacePackageJsonFilePaths(packageRootDir)),
+    ];
+}
+
+/**
+ * Get all workspace package.json paths starting at the given directory path. The output is string
+ * sorted to keep it stable.
+ *
+ * @category Node : Npm
+ * @category Package : @augment-vir/node
+ * @throws Error if there is no `package.json` file at the given `rootDirPath`.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export async function getWorkspacePackageJsonFilePaths(rootDirPath: string): Promise<string[]> {
+    const packageJson: PackageJson = JSON.parse(
+        await readFile(join(rootDirPath, 'package.json'), 'utf8'),
+    );
+
+    /* node:coverage ignore next 3: this package only uses one type of workspace */
+    const patterns = check.isArray(packageJson.workspaces)
+        ? packageJson.workspaces
+        : packageJson.workspaces?.packages || [];
+
+    const matchedPaths: string[] = joinFilesToDir(
+        rootDirPath,
+        (
+            await Promise.all(
+                patterns.map(async (pattern) => {
+                    return await fromAsyncIterable(glob(pattern, {cwd: rootDirPath}));
+                }),
+            )
+        ).flat(),
+    );
+
+    const workspacePackageJsonPaths = filterMap(
+        matchedPaths,
+        (matchedPath) => join(matchedPath, 'package.json'),
+        (packageJsonPath) => existsSync(packageJsonPath),
+    );
+
+    return workspacePackageJsonPaths.sort();
+}

package/src/index.ts

@@ -1,11 +1,14 @@
 export * from './augments/fs/dir-contents.js';
 export * from './augments/fs/download.js';
+export * from './augments/fs/grep.js';
 export * from './augments/fs/json.js';
 export * from './augments/fs/read-dir.js';
 export * from './augments/fs/read-file.js';
 export * from './augments/fs/symlink.js';
 export * from './augments/fs/write.js';
 export * from './augments/npm/find-bin-path.js';
+export * from './augments/npm/npm-deps.js';
+export * from './augments/npm/package-json.js';
 export * from './augments/npm/query-workspace.js';
 export * from './augments/npm/read-package-json.js';
 export * from './augments/os/operating-system.js';