@augment-vir/node 31.2.1 → 31.4.0

package/dist/augments/npm/find-bin-path.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Finds the path to an npm package executable bin by searching in all ancestor `node_modules/.bin`
+ * folders, starting at the given `startPath`.
+ *
+ * @category Node : Npm
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export declare function findNpmBinPath({ binName, startPath, }: {
+    startPath: string;
+    binName: string;
+}): string | undefined;

package/dist/augments/npm/find-bin-path.js

@@ -0,0 +1,21 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { findAncestor } from '../path/ancestor.js';
+/**
+ * Finds the path to an npm package executable bin by searching in all ancestor `node_modules/.bin`
+ * folders, starting at the given `startPath`.
+ *
+ * @category Node : Npm
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export function findNpmBinPath({ binName, startPath, }) {
+    const binPath = join('node_modules', '.bin', binName);
+    const ancestor = findAncestor(startPath, (ancestor) => {
+        return existsSync(join(ancestor, binPath));
+    });
+    if (!ancestor) {
+        return undefined;
+    }
+    return join(ancestor, binPath);
+}

package/dist/augments/path/ancestor.d.ts

@@ -1,6 +1,31 @@
 import { type MaybePromise } from '@augment-vir/common';
-export declare function findAncestor(currentPath: string, callback: (path: string) => Promise<boolean>): Promise<string | undefined>;
-export declare function findAncestor(currentPath: string, callback: (path: string) => boolean): string | undefined;
+/**
+ * Find an ancestor file path that matches the given `callback`. If no matches are found all the way
+ * up until the system root, this returns `undefined`.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @returns `undefined` if no matches are found.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export declare function findAncestor(currentPath: string, callback: (path: string) => Promise<boolean>): Promise<string | undefined>; /**
+ * Find an ancestor file path that matches the given `callback`. If no matches are found all the
+ * way up until the system root, this returns `undefined`.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @returns `undefined` if no matches are found.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export declare function findAncestor(currentPath: string, callback: (path: string) => boolean): string | undefined; /**
+ * Find an ancestor file path that matches the given `callback`. If no matches are found all the
+ * way up until the system root, this returns `undefined`.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @returns `undefined` if no matches are found.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
 export declare function findAncestor(currentPath: string, callback: (path: string) => MaybePromise<boolean>): MaybePromise<string | undefined>;
 /**
  * Join a list of paths to the given `parentDirPath`. This is particularly useful for getting full

package/dist/augments/path/resolve-import.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Determines the path that will be imported into the given `startingPoint` from the given
+ * `importPath`. Resolves symlinks, tries to map `.js` extensions to `.ts` extensions when needed,
+ * and tries to find the best `node_modules` import for package imports.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @returns `undefined` if no matches are found.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export declare function resolveImportPath(importerFilePath: string, importPath: string): string | undefined;

package/dist/augments/path/resolve-import.js

@@ -0,0 +1,78 @@
+import { check } from '@augment-vir/assert';
+import { filterMap, getObjectTypedEntries } from '@augment-vir/common';
+import { existsSync, realpathSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+import { readTsconfig } from '../typescript/read-tsconfig.js';
+import { findAncestor } from './ancestor.js';
+import { replaceWithWindowsPathIfNeeded } from './os-path.js';
+/**
+ * Determines the path that will be imported into the given `startingPoint` from the given
+ * `importPath`. Resolves symlinks, tries to map `.js` extensions to `.ts` extensions when needed,
+ * and tries to find the best `node_modules` import for package imports.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @returns `undefined` if no matches are found.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export function resolveImportPath(importerFilePath, importPath) {
+    const foundTsconfig = readTsconfig(importerFilePath);
+    const mappedImportPath = foundTsconfig
+        ? mapImportPath(importPath, foundTsconfig.tsconfig, foundTsconfig.path)
+        : importPath;
+    if (mappedImportPath.startsWith(sep) || mappedImportPath.startsWith('/')) {
+        /** Absolute import */
+        return mapFilePath(replaceWithWindowsPathIfNeeded(mappedImportPath));
+    }
+    else if (mappedImportPath.startsWith('.')) {
+        /** Relative import */
+        return mapFilePath(resolve(dirname(importerFilePath), replaceWithWindowsPathIfNeeded(mappedImportPath)));
+    }
+    else {
+        /** Package import */
+        const isOrgPackage = mappedImportPath.startsWith('@');
+        const importPathParts = mappedImportPath.split('/');
+        const packagePath = isOrgPackage
+            ? join(...importPathParts.slice(0, 2))
+            : // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+                importPathParts[0];
+        const relevantNodeModulesParent = findAncestor(importerFilePath, (ancestorPath) => {
+            const isMatch = existsSync(join(ancestorPath, 'node_modules', packagePath));
+            return isMatch;
+        });
+        if (!relevantNodeModulesParent) {
+            return undefined;
+        }
+        return mapFilePath(join(relevantNodeModulesParent, 'node_modules', replaceWithWindowsPathIfNeeded(mappedImportPath)));
+    }
+}
+function mapFilePath(path) {
+    if (existsSync(path)) {
+        return realpathSync(path);
+    }
+    const tsPath = path.replace(/\.js$/, '.ts');
+    if (path.endsWith('.js') && existsSync(tsPath)) {
+        return realpathSync(tsPath);
+    }
+    return path;
+}
+function mapImportPath(importPath, tsconfig, tsconfigPath) {
+    const paths = tsconfig.options.paths;
+    if (!paths) {
+        return importPath;
+    }
+    const mappedPaths = filterMap(getObjectTypedEntries(paths), ([alias, paths]) => {
+        const aliasRegex = new RegExp('^' + String(alias).replace(/\*/g, '(.*)') + '$');
+        const match = importPath.match(aliasRegex);
+        if (!match) {
+            return undefined;
+        }
+        /** An empty paths is invalid anyway. */
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        return paths[0].replace(/\*/g, match[1]);
+    }, check.isTruthy);
+    if (!mappedPaths[0]) {
+        return importPath;
+    }
+    return resolve(tsconfig.options.baseUrl || dirname(tsconfigPath), mappedPaths[0]);
+}

package/dist/augments/prisma.d.ts

@@ -12,17 +12,17 @@ export type { PrismaMigrationStatus } from '../prisma/prisma-migrations.js';
  *
  * - Deploy to production
  *
- *   - {@link prisma.migration.applyProd}
+ *   - `prisma.migration.applyProd()`
  * - Update dev environment
  *
- *   - Apply migrations: {@link prisma.migration.applyDev}
+ *   - Apply migrations: `prisma.migration.applyDev`
  *
  *       - If throws {@link PrismaMigrationNeededError}, prompt user for a new migration name and pass it to
- *               {@link prisma.migration.create}
- *       - If throws {@link PrismaResetNeededError}, reset the database with {@link prisma.database.resetDev}
+ *               `prisma.migration.create`
+ *       - If throws {@link PrismaResetNeededError}, reset the database with `prisma.database.resetDev`
  *   - Generate client: `prisma.client.isCurrent`
  *
- *       - If `false`, run {@link prisma.client.generate}
+ *       - If `false`, run `prisma.client.generate`
  *
  * @category Prisma : Node
  * @category Package : @augment-vir/node
@@ -50,7 +50,7 @@ export declare const prisma: {
         applyProd: typeof applyPrismaMigrationsToProd;
         /**
          * Apply all migrations. Meant for a development environment, with less protections than
-         * {@link prisma.migration.applyProd}.
+         * `prisma.migration.applyProd()`
          *
          * @throws `PrismaMigrationNeededError` when a new migration is required so the user needs
          *   to input a name.
@@ -70,8 +70,8 @@ export declare const prisma: {
          */
         resetDev: typeof resetDevPrismaDatabase;
         /**
-         * Uses {@link prisma.database.diff} to detect if there are any differences between the
-         * current database and the Prisma schema that should control it.
+         * Uses `prisma.database.diff` to detect if there are any differences between the current
+         * database and the Prisma schema that should control it.
          */
         hasDiff: typeof doesPrismaDiffExist;
         /**
@@ -102,8 +102,8 @@ export declare const prisma: {
          */
         isCurrent: typeof isGeneratedPrismaClientCurrent;
         /**
-         * Adds a collection of create data to a database through a `PrismaClient` instance. This is
-         * particularly useful for setting up mocks in a mock PrismaClient.
+         * Adds a collection of create data entries to a database through a `PrismaClient` instance.
+         * This is particularly useful for setting up mocks in a mock PrismaClient.
          *
          * @example
          *

package/dist/augments/prisma.js

@@ -10,17 +10,17 @@ export * from '../prisma/prisma-errors.js';
  *
  * - Deploy to production
  *
- *   - {@link prisma.migration.applyProd}
+ *   - `prisma.migration.applyProd()`
  * - Update dev environment
  *
- *   - Apply migrations: {@link prisma.migration.applyDev}
+ *   - Apply migrations: `prisma.migration.applyDev`
  *
  *       - If throws {@link PrismaMigrationNeededError}, prompt user for a new migration name and pass it to
- *               {@link prisma.migration.create}
- *       - If throws {@link PrismaResetNeededError}, reset the database with {@link prisma.database.resetDev}
+ *               `prisma.migration.create`
+ *       - If throws {@link PrismaResetNeededError}, reset the database with `prisma.database.resetDev`
  *   - Generate client: `prisma.client.isCurrent`
  *
- *       - If `false`, run {@link prisma.client.generate}
+ *       - If `false`, run `prisma.client.generate`
  *
  * @category Prisma : Node
  * @category Package : @augment-vir/node
@@ -48,7 +48,7 @@ export const prisma = {
         applyProd: applyPrismaMigrationsToProd,
         /**
          * Apply all migrations. Meant for a development environment, with less protections than
-         * {@link prisma.migration.applyProd}.
+         * `prisma.migration.applyProd()`
          *
          * @throws `PrismaMigrationNeededError` when a new migration is required so the user needs
          *   to input a name.
@@ -68,8 +68,8 @@ export const prisma = {
          */
         resetDev: resetDevPrismaDatabase,
         /**
-         * Uses {@link prisma.database.diff} to detect if there are any differences between the
-         * current database and the Prisma schema that should control it.
+         * Uses `prisma.database.diff` to detect if there are any differences between the current
+         * database and the Prisma schema that should control it.
          */
         hasDiff: doesPrismaDiffExist,
         /**
@@ -100,8 +100,8 @@ export const prisma = {
          */
         isCurrent: isGeneratedPrismaClientCurrent,
         /**
-         * Adds a collection of create data to a database through a `PrismaClient` instance. This is
-         * particularly useful for setting up mocks in a mock PrismaClient.
+         * Adds a collection of create data entries to a database through a `PrismaClient` instance.
+         * This is particularly useful for setting up mocks in a mock PrismaClient.
          *
          * @example
          *
@@ -142,7 +142,7 @@ export const prisma = {
          * ]);
          * ```
          */
-        addData: addData,
+        addData,
         /**
          * Dump data from the current database through a `PrismaClient` instance.
          *

package/dist/augments/terminal/run-cli-script.d.ts

@@ -6,7 +6,9 @@
  * @category Package : @augment-vir/node
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
-export declare const ExtensionToRunner: Record<string, string>;
+export declare const ExtensionToRunner: Record<string, string | {
+    npx: string;
+}>;
 /**
  * Runs a script path as if it had been run directly, as much as possible.
  *
@@ -14,7 +16,7 @@ export declare const ExtensionToRunner: Record<string, string>;
  * @category Package : @augment-vir/node
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
-export declare function runCliScript(path: string, 
+export declare function runCliScript(scriptPath: string, 
 /** This should just be `__filename` (for CJS) or `import.meta.filename` (for ESM). */
 cliScriptFilePath: string, 
 /**

package/dist/augments/terminal/run-cli-script.js

@@ -1,6 +1,8 @@
 /* node:coverage disable */
 /** This file cannot be tested because it calls `process.exit`. */
-import { extname } from 'node:path';
+import { check } from '@augment-vir/assert';
+import { dirname, extname } from 'node:path';
+import { findNpmBinPath } from '../npm/find-bin-path.js';
 import { interpolationSafeWindowsPath } from '../path/os-path.js';
 import { extractRelevantArgs } from './relevant-args.js';
 import { runShellCommand } from './shell.js';
@@ -12,7 +14,9 @@ import { runShellCommand } from './shell.js';
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
 export const ExtensionToRunner = {
-    '.ts': 'tsx',
+    '.ts': {
+        npx: 'tsx',
+    },
     '.js': 'node',
     '.sh': 'bash',
 };
@@ -23,7 +27,7 @@ export const ExtensionToRunner = {
  * @category Package : @augment-vir/node
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
-export async function runCliScript(path, 
+export async function runCliScript(scriptPath, 
 /** This should just be `__filename` (for CJS) or `import.meta.filename` (for ESM). */
 cliScriptFilePath, 
 /**
@@ -36,12 +40,18 @@ binName) {
         binName,
         fileName: cliScriptFilePath,
     });
-    const extension = extname(path);
+    const extension = extname(scriptPath);
     const runner = ExtensionToRunner[extension];
     if (!runner) {
         throw new Error("No runner configured for file extension '${extension}' in '${path}'");
     }
-    const results = await runShellCommand(interpolationSafeWindowsPath([runner, path, ...args].join(' ')), {
+    const runnerPath = check.isString(runner)
+        ? runner
+        : findNpmBinPath({
+            binName: runner.npx,
+            startPath: dirname(cliScriptFilePath),
+        }) || runner.npx;
+    const results = await runShellCommand(interpolationSafeWindowsPath([runnerPath, scriptPath, ...args].join(' ')), {
         hookUpToConsole: true,
     });
     process.exit(results.exitCode || 0);

package/dist/augments/typescript/read-tsconfig.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Finds the closest `tsconfig.json` file and parses it.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @returns `undefined` if no tsconfig was found or if a found tsconfig fails to parse.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export declare function readTsconfig(startingPath: string): {
+    tsconfig: import("typescript").ParsedCommandLine;
+    path: string;
+} | undefined;

package/dist/augments/typescript/read-tsconfig.js

@@ -0,0 +1,32 @@
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { parseJsonConfigFileContent, readConfigFile, sys } from 'typescript';
+import { findAncestor } from '../path/ancestor.js';
+/**
+ * Finds the closest `tsconfig.json` file and parses it.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @returns `undefined` if no tsconfig was found or if a found tsconfig fails to parse.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export function readTsconfig(startingPath) {
+    const tsconfigDirPath = findAncestor(startingPath, (ancestorPath) => existsSync(join(ancestorPath, 'tsconfig.json')));
+    const tsconfigPath = tsconfigDirPath ? join(tsconfigDirPath, 'tsconfig.json') : undefined;
+    if (!tsconfigPath) {
+        return undefined;
+    }
+    // eslint-disable-next-line @typescript-eslint/unbound-method
+    const { config, error } = readConfigFile(tsconfigPath, sys.readFile);
+    if (error) {
+        return undefined;
+    }
+    const parsedConfig = parseJsonConfigFileContent(config, sys, dirname(tsconfigPath));
+    if (parsedConfig.errors.length) {
+        return undefined;
+    }
+    return {
+        tsconfig: parsedConfig,
+        path: tsconfigPath,
+    };
+}

package/dist/docker/containers/container-info.d.ts

@@ -1,7 +1,7 @@
 import type { JsonCompatibleArray, JsonCompatibleObject } from '@augment-vir/common';
 import type { DockerContainerStatus } from './container-status.js';
 /**
- * Properties on {@link DockerContainerInfo}.State, retrieved from {@link getContainerInfo}.
+ * Properties on {@link DockerContainerInfo}.State, retrieved from `docker.container.getInfo()`.
  *
  * @category Node : Docker : Util
  * @category Package : @augment-vir/node
@@ -22,8 +22,8 @@ export type DockerContainerInfoState = {
 };
 /** This type signature is incomplete. Add to it as necessary. */
 /**
- * Properties on the output from {@link getContainerInfo}. Not all these properties are filled in all
- * the way, particularly most of properties with nested objects.
+ * Properties on the output from `docker.container.getInfo()`. Not all these properties are filled
+ * in all the way, particularly most of properties with nested objects.
  *
  * @category Node : Docker : Util
  * @category Package : @augment-vir/node

package/dist/index.d.ts

@@ -6,14 +6,17 @@ 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/query-workspace.js';
 export * from './augments/npm/read-package-json.js';
 export * from './augments/os/operating-system.js';
 export * from './augments/path/ancestor.js';
 export * from './augments/path/os-path.js';
+export * from './augments/path/resolve-import.js';
 export * from './augments/path/root.js';
 export * from './augments/prisma.js';
 export * from './augments/terminal/question.js';
 export * from './augments/terminal/relevant-args.js';
 export * from './augments/terminal/run-cli-script.js';
 export * from './augments/terminal/shell.js';
+export * from './augments/typescript/read-tsconfig.js';

package/dist/index.js

@@ -6,14 +6,17 @@ 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/query-workspace.js';
 export * from './augments/npm/read-package-json.js';
 export * from './augments/os/operating-system.js';
 export * from './augments/path/ancestor.js';
 export * from './augments/path/os-path.js';
+export * from './augments/path/resolve-import.js';
 export * from './augments/path/root.js';
 export * from './augments/prisma.js';
 export * from './augments/terminal/question.js';
 export * from './augments/terminal/relevant-args.js';
 export * from './augments/terminal/run-cli-script.js';
 export * from './augments/terminal/shell.js';
+export * from './augments/typescript/read-tsconfig.js';

package/dist/prisma/model-data.d.ts

@@ -1,8 +1,8 @@
 import { BasePrismaClient, PrismaAllModelsCreate, type PartialWithUndefined, type PrismaAllBasicModels, type PrismaModelName } from '@augment-vir/common';
 import type { IsAny } from 'type-fest';
 /**
- * Params for {@link addData}. This is similar to {@link PrismaAllModelsCreate} but allows an array of
- * {@link PrismaAllModelsCreate} for sequential data creation.
+ * Params for `prisma.client.addData()`. This is similar to {@link PrismaAllModelsCreate} but allows
+ * an array of {@link PrismaAllModelsCreate} for sequential data creation.
  *
  * @category Prisma : Node
  * @category Package : @augment-vir/node

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@augment-vir/node",
-    "version": "31.2.1",
+    "version": "31.4.0",
     "description": "A collection of augments, helpers types, functions, and classes only for Node.js (backend) JavaScript environments.",
     "keywords": [
         "augment",
@@ -37,27 +37,31 @@
         "test:update": "npm test"
     },
     "dependencies": {
-        "@augment-vir/assert": "^31.2.1",
-        "@augment-vir/common": "^31.2.1",
-        "@date-vir/duration": "^7.0.1",
+        "@augment-vir/assert": "^31.4.0",
+        "@augment-vir/common": "^31.4.0",
+        "@date-vir/duration": "^7.1.1",
         "ansi-styles": "^6.2.1",
         "terminate": "^2.8.0",
-        "type-fest": "^4.29.0",
+        "type-fest": "^4.31.0",
         "typed-event-target": "^4.0.2"
     },
     "devDependencies": {
-        "@augment-vir/test": "^31.2.1",
-        "@prisma/client": "^5.22.0",
-        "@types/node": "^22.10.0",
+        "@augment-vir/test": "^31.4.0",
+        "@prisma/client": "^6.1.0",
+        "@types/node": "^22.10.5",
         "@web/dev-server-esbuild": "^1.0.3",
         "@web/test-runner": "^0.19.0",
         "@web/test-runner-commands": "^0.9.0",
         "@web/test-runner-playwright": "^0.11.0",
         "@web/test-runner-visual-regression": "^0.10.0",
-        "c8": "^10.1.2",
-        "concurrently": "^9.1.0",
+        "c8": "^10.1.3",
+        "concurrently": "^9.1.2",
         "istanbul-smart-text-reporter": "^1.1.5",
-        "prisma": "^5.22.0"
+        "prisma": "^6.1.0",
+        "typescript": "^5.7.2"
+    },
+    "peerDependencies": {
+        "typescript": "*"
     },
     "engines": {
         "node": ">=22"

package/src/augments/npm/find-bin-path.ts

@@ -0,0 +1,31 @@
+import {existsSync} from 'node:fs';
+import {join} from 'node:path';
+import {findAncestor} from '../path/ancestor.js';
+
+/**
+ * Finds the path to an npm package executable bin by searching in all ancestor `node_modules/.bin`
+ * folders, starting at the given `startPath`.
+ *
+ * @category Node : Npm
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export function findNpmBinPath({
+    binName,
+    startPath,
+}: {
+    startPath: string;
+    binName: string;
+}): string | undefined {
+    const binPath = join('node_modules', '.bin', binName);
+
+    const ancestor = findAncestor(startPath, (ancestor) => {
+        return existsSync(join(ancestor, binPath));
+    });
+
+    if (!ancestor) {
+        return undefined;
+    }
+
+    return join(ancestor, binPath);
+}

package/src/augments/path/ancestor.ts

@@ -3,14 +3,39 @@ import {type MaybePromise} from '@augment-vir/common';
 import {dirname, join} from 'node:path';
 import {systemRootPath} from './root.js';
 
+/**
+ * Find an ancestor file path that matches the given `callback`. If no matches are found all the way
+ * up until the system root, this returns `undefined`.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @returns `undefined` if no matches are found.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
 export function findAncestor(
     currentPath: string,
     callback: (path: string) => Promise<boolean>,
-): Promise<string | undefined>;
+): Promise<string | undefined>; /**
+ * Find an ancestor file path that matches the given `callback`. If no matches are found all the
+ * way up until the system root, this returns `undefined`.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @returns `undefined` if no matches are found.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
 export function findAncestor(
     currentPath: string,
     callback: (path: string) => boolean,
-): string | undefined;
+): string | undefined; /**
+ * Find an ancestor file path that matches the given `callback`. If no matches are found all the
+ * way up until the system root, this returns `undefined`.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @returns `undefined` if no matches are found.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
 export function findAncestor(
     currentPath: string,
     callback: (path: string) => MaybePromise<boolean>,

package/src/augments/path/resolve-import.ts

@@ -0,0 +1,116 @@
+import {check} from '@augment-vir/assert';
+import {filterMap, getObjectTypedEntries} from '@augment-vir/common';
+import {existsSync, realpathSync} from 'node:fs';
+import {dirname, join, resolve, sep} from 'node:path';
+import {ParsedCommandLine} from 'typescript';
+import {readTsconfig} from '../typescript/read-tsconfig.js';
+import {findAncestor} from './ancestor.js';
+import {replaceWithWindowsPathIfNeeded} from './os-path.js';
+
+/**
+ * Determines the path that will be imported into the given `startingPoint` from the given
+ * `importPath`. Resolves symlinks, tries to map `.js` extensions to `.ts` extensions when needed,
+ * and tries to find the best `node_modules` import for package imports.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @returns `undefined` if no matches are found.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export function resolveImportPath(
+    importerFilePath: string,
+    importPath: string,
+): string | undefined {
+    const foundTsconfig = readTsconfig(importerFilePath);
+
+    const mappedImportPath = foundTsconfig
+        ? mapImportPath(importPath, foundTsconfig.tsconfig, foundTsconfig.path)
+        : importPath;
+
+    if (mappedImportPath.startsWith(sep) || mappedImportPath.startsWith('/')) {
+        /** Absolute import */
+
+        return mapFilePath(replaceWithWindowsPathIfNeeded(mappedImportPath));
+    } else if (mappedImportPath.startsWith('.')) {
+        /** Relative import */
+        return mapFilePath(
+            resolve(dirname(importerFilePath), replaceWithWindowsPathIfNeeded(mappedImportPath)),
+        );
+    } else {
+        /** Package import */
+
+        const isOrgPackage = mappedImportPath.startsWith('@');
+        const importPathParts = mappedImportPath.split('/');
+
+        const packagePath: string = isOrgPackage
+            ? join(...importPathParts.slice(0, 2))
+            : // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+              importPathParts[0]!;
+
+        const relevantNodeModulesParent = findAncestor(importerFilePath, (ancestorPath) => {
+            const isMatch = existsSync(join(ancestorPath, 'node_modules', packagePath));
+
+            return isMatch;
+        });
+
+        if (!relevantNodeModulesParent) {
+            return undefined;
+        }
+
+        return mapFilePath(
+            join(
+                relevantNodeModulesParent,
+                'node_modules',
+                replaceWithWindowsPathIfNeeded(mappedImportPath),
+            ),
+        );
+    }
+}
+
+function mapFilePath(path: string): string {
+    if (existsSync(path)) {
+        return realpathSync(path);
+    }
+
+    const tsPath = path.replace(/\.js$/, '.ts');
+
+    if (path.endsWith('.js') && existsSync(tsPath)) {
+        return realpathSync(tsPath);
+    }
+
+    return path;
+}
+
+function mapImportPath(
+    importPath: string,
+    tsconfig: ParsedCommandLine,
+    tsconfigPath: string,
+): string {
+    const paths = tsconfig.options.paths;
+    if (!paths) {
+        return importPath;
+    }
+
+    const mappedPaths = filterMap(
+        getObjectTypedEntries(paths),
+        ([alias, paths]) => {
+            const aliasRegex = new RegExp('^' + String(alias).replace(/\*/g, '(.*)') + '$');
+            const match = importPath.match(aliasRegex);
+
+            if (!match) {
+                return undefined;
+            }
+
+            /** An empty paths is invalid anyway. */
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            return paths[0]!.replace(/\*/g, match[1]!);
+        },
+        check.isTruthy,
+    );
+
+    if (!mappedPaths[0]) {
+        return importPath;
+    }
+
+    return resolve(tsconfig.options.baseUrl || dirname(tsconfigPath), mappedPaths[0]);
+}

package/src/augments/prisma.ts

@@ -29,17 +29,17 @@ export type {PrismaMigrationStatus} from '../prisma/prisma-migrations.js';
  *
  * - Deploy to production
  *
- *   - {@link prisma.migration.applyProd}
+ *   - `prisma.migration.applyProd()`
  * - Update dev environment
  *
- *   - Apply migrations: {@link prisma.migration.applyDev}
+ *   - Apply migrations: `prisma.migration.applyDev`
  *
  *       - If throws {@link PrismaMigrationNeededError}, prompt user for a new migration name and pass it to
- *               {@link prisma.migration.create}
- *       - If throws {@link PrismaResetNeededError}, reset the database with {@link prisma.database.resetDev}
+ *               `prisma.migration.create`
+ *       - If throws {@link PrismaResetNeededError}, reset the database with `prisma.database.resetDev`
  *   - Generate client: `prisma.client.isCurrent`
  *
- *       - If `false`, run {@link prisma.client.generate}
+ *       - If `false`, run `prisma.client.generate`
  *
  * @category Prisma : Node
  * @category Package : @augment-vir/node
@@ -67,7 +67,7 @@ export const prisma = {
         applyProd: applyPrismaMigrationsToProd,
         /**
          * Apply all migrations. Meant for a development environment, with less protections than
-         * {@link prisma.migration.applyProd}.
+         * `prisma.migration.applyProd()`
          *
          * @throws `PrismaMigrationNeededError` when a new migration is required so the user needs
          *   to input a name.
@@ -87,8 +87,8 @@ export const prisma = {
          */
         resetDev: resetDevPrismaDatabase,
         /**
-         * Uses {@link prisma.database.diff} to detect if there are any differences between the
-         * current database and the Prisma schema that should control it.
+         * Uses `prisma.database.diff` to detect if there are any differences between the current
+         * database and the Prisma schema that should control it.
          */
         hasDiff: doesPrismaDiffExist,
         /**
@@ -119,8 +119,8 @@ export const prisma = {
          */
         isCurrent: isGeneratedPrismaClientCurrent,
         /**
-         * Adds a collection of create data to a database through a `PrismaClient` instance. This is
-         * particularly useful for setting up mocks in a mock PrismaClient.
+         * Adds a collection of create data entries to a database through a `PrismaClient` instance.
+         * This is particularly useful for setting up mocks in a mock PrismaClient.
          *
          * @example
          *
@@ -161,7 +161,7 @@ export const prisma = {
          * ]);
          * ```
          */
-        addData: addData,
+        addData,
         /**
          * Dump data from the current database through a `PrismaClient` instance.
          *

package/src/augments/terminal/run-cli-script.ts

@@ -1,7 +1,9 @@
 /* node:coverage disable */
 /** This file cannot be tested because it calls `process.exit`. */
 
-import {extname} from 'node:path';
+import {check} from '@augment-vir/assert';
+import {dirname, extname} from 'node:path';
+import {findNpmBinPath} from '../npm/find-bin-path.js';
 import {interpolationSafeWindowsPath} from '../path/os-path.js';
 import {extractRelevantArgs} from './relevant-args.js';
 import {runShellCommand} from './shell.js';
@@ -13,8 +15,10 @@ import {runShellCommand} from './shell.js';
  * @category Package : @augment-vir/node
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
-export const ExtensionToRunner: Record<string, string> = {
-    '.ts': 'tsx',
+export const ExtensionToRunner: Record<string, string | {npx: string}> = {
+    '.ts': {
+        npx: 'tsx',
+    },
     '.js': 'node',
     '.sh': 'bash',
 };
@@ -27,7 +31,7 @@ export const ExtensionToRunner: Record<string, string> = {
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
 export async function runCliScript(
-    path: string,
+    scriptPath: string,
     /** This should just be `__filename` (for CJS) or `import.meta.filename` (for ESM). */
     cliScriptFilePath: string,
     /**
@@ -42,7 +46,7 @@ export async function runCliScript(
         fileName: cliScriptFilePath,
     });
 
-    const extension = extname(path);
+    const extension = extname(scriptPath);
 
     const runner = ExtensionToRunner[extension];
 
@@ -50,8 +54,15 @@ export async function runCliScript(
         throw new Error("No runner configured for file extension '${extension}' in '${path}'");
     }
 
+    const runnerPath = check.isString(runner)
+        ? runner
+        : findNpmBinPath({
+              binName: runner.npx,
+              startPath: dirname(cliScriptFilePath),
+          }) || runner.npx;
+
     const results = await runShellCommand(
-        interpolationSafeWindowsPath([runner, path, ...args].join(' ')),
+        interpolationSafeWindowsPath([runnerPath, scriptPath, ...args].join(' ')),
         {
             hookUpToConsole: true,
         },

package/src/augments/typescript/read-tsconfig.ts

@@ -0,0 +1,41 @@
+import {existsSync} from 'node:fs';
+import {dirname, join} from 'node:path';
+import {parseJsonConfigFileContent, readConfigFile, sys} from 'typescript';
+import {findAncestor} from '../path/ancestor.js';
+
+/**
+ * Finds the closest `tsconfig.json` file and parses it.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @returns `undefined` if no tsconfig was found or if a found tsconfig fails to parse.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export function readTsconfig(startingPath: string) {
+    const tsconfigDirPath = findAncestor(startingPath, (ancestorPath) =>
+        existsSync(join(ancestorPath, 'tsconfig.json')),
+    );
+    const tsconfigPath = tsconfigDirPath ? join(tsconfigDirPath, 'tsconfig.json') : undefined;
+
+    if (!tsconfigPath) {
+        return undefined;
+    }
+
+    // eslint-disable-next-line @typescript-eslint/unbound-method
+    const {config, error} = readConfigFile(tsconfigPath, sys.readFile);
+
+    if (error) {
+        return undefined;
+    }
+
+    const parsedConfig = parseJsonConfigFileContent(config, sys, dirname(tsconfigPath));
+
+    if (parsedConfig.errors.length) {
+        return undefined;
+    }
+
+    return {
+        tsconfig: parsedConfig,
+        path: tsconfigPath,
+    };
+}

package/src/docker/containers/container-info.ts

@@ -3,7 +3,7 @@ import {runShellCommand} from '../../augments/terminal/shell.js';
 import type {DockerContainerStatus} from './container-status.js';
 
 /**
- * Properties on {@link DockerContainerInfo}.State, retrieved from {@link getContainerInfo}.
+ * Properties on {@link DockerContainerInfo}.State, retrieved from `docker.container.getInfo()`.
  *
  * @category Node : Docker : Util
  * @category Package : @augment-vir/node
@@ -26,8 +26,8 @@ export type DockerContainerInfoState = {
 /** This type signature is incomplete. Add to it as necessary. */
 
 /**
- * Properties on the output from {@link getContainerInfo}. Not all these properties are filled in all
- * the way, particularly most of properties with nested objects.
+ * Properties on the output from `docker.container.getInfo()`. Not all these properties are filled
+ * in all the way, particularly most of properties with nested objects.
  *
  * @category Node : Docker : Util
  * @category Package : @augment-vir/node

package/src/index.ts

@@ -6,14 +6,17 @@ 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/query-workspace.js';
 export * from './augments/npm/read-package-json.js';
 export * from './augments/os/operating-system.js';
 export * from './augments/path/ancestor.js';
 export * from './augments/path/os-path.js';
+export * from './augments/path/resolve-import.js';
 export * from './augments/path/root.js';
 export * from './augments/prisma.js';
 export * from './augments/terminal/question.js';
 export * from './augments/terminal/relevant-args.js';
 export * from './augments/terminal/run-cli-script.js';
 export * from './augments/terminal/shell.js';
+export * from './augments/typescript/read-tsconfig.js';

package/src/prisma/model-data.ts

@@ -20,8 +20,8 @@ import {
 import type {IsAny} from 'type-fest';
 
 /**
- * Params for {@link addData}. This is similar to {@link PrismaAllModelsCreate} but allows an array of
- * {@link PrismaAllModelsCreate} for sequential data creation.
+ * Params for `prisma.client.addData()`. This is similar to {@link PrismaAllModelsCreate} but allows
+ * an array of {@link PrismaAllModelsCreate} for sequential data creation.
  *
  * @category Prisma : Node
  * @category Package : @augment-vir/node