@williamthorsen/nmr 0.38.0 → 0.40.0

package/dist/esm/resolver.d.ts

@@ -2,22 +2,22 @@ import { type ScriptRegistry, type ScriptValue } from './resolve-scripts.js';
 import { type Step } from './steps.js';
 import type { NmrConfig } from './types.js';
 /**
- * Replace the first token of a command with a `devBin` substitute.
+ * Replaces the first token of a command with a `devBin` substitute.
  * Relative paths in the replacement are resolved from `monorepoRoot`.
  */
 export declare function applyDevBin(command: string, devBin: Record<string, string> | undefined, monorepoRoot: string): string;
 /**
  * Applies a `devBin` substitution to each opaque step, leaving nmr's own compositions alone.
  *
- * A structural step names a command nmr resolves for itself, so substituting its first token would replace the
- * `nmr` that carries the composite rather than the leaf tool `devBin` documents replacing.
+ * A structural step names a command that nmr resolves for itself, so substituting its first token would replace
+ * the `nmr` that runs the composite rather than the leaf tool that `devBin` documents replacing.
  */
 export declare function applyDevBinToSteps(steps: readonly Step[], devBin: Record<string, string> | undefined, monorepoRoot: string): readonly Step[];
 /**
  * Where a resolved script was read from.
  *
  * `registry` covers the built-in defaults and the repo-wide config together, which resolution cannot tell
- * apart: it receives the two already merged. A caller holding the config refines the two.
+ * apart: It receives the two already merged. A caller that has the config refines the two.
  */
 export type ScriptOrigin = {
     tier: 'registry';
@@ -32,13 +32,13 @@ export interface ResolvedScript {
     steps: readonly Step[];
 }
 /**
- * Expands a script value into the ordered steps it runs as: a string is one opaque step, and an array is one
+ * Expands a script value into the ordered steps that it runs as: a string is one opaque step, and an array is one
  * structural step per element.
  *
  * A bare string element and the `{ run }` spec compose the same step. The spec's only addition is the
- * declaration of what the step does with the invocation's trailing arguments, which position cannot carry.
+ * declaration of what the step does with the invocation's trailing arguments, which position cannot express.
  */
-export declare function expandScript(script: ScriptValue, workspaceRoot: boolean): readonly Step[];
+export declare function expandScript(script: ScriptValue, isWorkspaceRoot: boolean): readonly Step[];
 /**
  * Returns a description of a script for help output.
  */
@@ -47,8 +47,7 @@ export declare function describeScript(script: ScriptValue): string;
  * Reads a package.json's `scripts`, rejecting any value that is not a string.
  *
  * npm and pnpm read a script as a string too, so a value of any other type is malformed however it got there.
- * Dropping one silently would run the registry's entry in its place, which is what an array written here after
- * being told a step list resolves a shelled-nmr crossing would otherwise do.
+ * Dropping one silently would run the registry's entry in its place.
  */
 export declare function readPackageJsonScripts(packageDir: string): Record<string, string> | undefined;
 /**
@@ -62,20 +61,17 @@ export declare function buildWorkspaceRegistry(config: NmrConfig): ScriptRegistr
  */
 export declare function buildRootRegistry(config: NmrConfig): ScriptRegistry;
 /**
- * Returns a `package.json` entry that re-invokes the command it is declared under alongside other steps, or
- * `undefined` where the entry declares no such thing.
+ * Returns a `package.json` entry that re-invokes the command under which it is declared alongside other steps,
+ * or `undefined` when the entry does not.
  *
- * Resolution discards a self-referential entry however it reads, so an entry that chains loses the steps it
+ * Resolution discards a self-referential entry however it reads, so an entry that chains loses the steps that it
  * chained. This is what an invocation rejects on, read where the command runs rather than raised from
- * resolution: the same scripts are resolved speculatively, for packages nobody named.
+ * resolution: The same scripts are resolved speculatively, for packages that nobody named.
  */
 export declare function findChainedSelfReference(packageDir: string | undefined, commandName: string): string | undefined;
 /**
- * Reports whether a `package.json` entry re-invokes the command it is declared under, wherever the
- * re-invocation stands in it, e.g. `"build": "nmr build"` or `"build": "rdy compile && nmr build"`.
- *
- * Honouring one spawns a shell that runs the same command in the same directory, reaching the same entry
- * again without bound, so resolution discards it.
+ * Reports whether a `package.json` entry re-invokes the command under which it is declared, wherever the
+ * re-invocation appears in it, e.g. `"build": "nmr build"` or `"build": "rdy compile && nmr build"`.
  */
 export declare function isSelfReferential(script: string, commandName: string, packageDir: string): boolean;
 /**
@@ -85,6 +81,6 @@ export declare function isSelfReferential(script: string, commandName: string, p
  * 3. Per-package overrides (package.json scripts)
  *
  * Returns undefined if the command is not found in the registry. A package.json override of `""` (indicating
- * skip) resolves to a single opaque step carrying it, which renders back to the empty string.
+ * skip) resolves to a single opaque step containing it, which renders back to the empty string.
  */
-export declare function resolveScript(commandName: string, registry: ScriptRegistry, packageDir: string | undefined, workspaceRoot: boolean): ResolvedScript | undefined;
+export declare function resolveScript(commandName: string, registry: ScriptRegistry, packageDir: string | undefined, isWorkspaceRoot: boolean): ResolvedScript | undefined;

package/dist/esm/resolver.js

@@ -12,13 +12,13 @@ export function applyDevBin(command, devBin, monorepoRoot) {
     }
     const spaceIndex = command.indexOf(' ');
     const firstToken = spaceIndex === -1 ? command : command.slice(0, spaceIndex);
-    const rest = spaceIndex === -1 ? '' : command.slice(spaceIndex);
+    const restOfCommand = spaceIndex === -1 ? '' : command.slice(spaceIndex);
     const replacement = devBin[firstToken];
     if (replacement === undefined) {
         return command;
     }
     const resolvedReplacement = resolveReplacementPaths(replacement, monorepoRoot);
-    return resolvedReplacement + rest;
+    return resolvedReplacement + restOfCommand;
 }
 export function applyDevBinToSteps(steps, devBin, monorepoRoot) {
     if (!devBin) {
@@ -40,13 +40,13 @@ function resolveReplacementPaths(replacement, monorepoRoot) {
     })
         .join(' ');
 }
-export function expandScript(script, workspaceRoot) {
+export function expandScript(script, isWorkspaceRoot) {
     if (typeof script === 'string') {
         return [{ kind: 'opaque', command: script }];
     }
     return script.map((element) => typeof element === 'string'
-        ? composeNmrStep(element, workspaceRoot)
-        : composeNmrStep(element.run, workspaceRoot, element.shouldDeclineArguments));
+        ? composeNmrStep(element, isWorkspaceRoot)
+        : composeNmrStep(element.run, isWorkspaceRoot, element.shouldDeclineArguments));
 }
 export function describeScript(script) {
     return typeof script === 'string' ? script : `[${script.map(describeElement).join(', ')}]`;
@@ -59,9 +59,9 @@ function describeElement(element) {
 }
 export function readPackageJsonScripts(packageDir) {
     const file = resolvePackageJsonPath(packageDir);
-    let raw;
+    let rawText;
     try {
-        raw = readFileSync(file, 'utf8');
+        rawText = readFileSync(file, 'utf8');
     }
     catch (error) {
         if (hasErrnoCode(error, 'ENOENT')) {
@@ -69,10 +69,10 @@ export function readPackageJsonScripts(packageDir) {
         }
         throw error;
     }
-    const parsed = parsePackageJson(raw, file);
-    if (!isObject(parsed))
+    const parsedManifest = parsePackageJson(rawText, file);
+    if (!isObject(parsedManifest))
         return undefined;
-    const scripts = parsed['scripts'];
+    const scripts = parsedManifest['scripts'];
     if (!isObject(scripts))
         return undefined;
     return readScriptRecord(packageDir, scripts);
@@ -108,15 +108,15 @@ export function findChainedSelfReference(packageDir, commandName) {
 export function isSelfReferential(script, commandName, packageDir) {
     return readSelfReference({ anchoredAtRoot: isMonorepoRoot(packageDir), commandName, script }) !== undefined;
 }
-export function resolveScript(commandName, registry, packageDir, workspaceRoot) {
+export function resolveScript(commandName, registry, packageDir, isWorkspaceRoot) {
     if (packageDir) {
         const pkgScripts = readPackageJsonScripts(packageDir);
         if (pkgScripts && Object.hasOwn(pkgScripts, commandName)) {
-            const override = pkgScripts[commandName];
-            if (override !== undefined && !isSelfReferential(override, commandName, packageDir)) {
+            const overrideCommand = pkgScripts[commandName];
+            if (overrideCommand !== undefined && !isSelfReferential(overrideCommand, commandName, packageDir)) {
                 return {
                     origin: { tier: 'package', file: resolvePackageJsonPath(packageDir), key: commandName },
-                    steps: [{ kind: 'opaque', command: override }],
+                    steps: [{ kind: 'opaque', command: overrideCommand }],
                 };
             }
         }
@@ -128,5 +128,5 @@ export function resolveScript(commandName, registry, packageDir, workspaceRoot)
     if (registryEntry === undefined) {
         return undefined;
     }
-    return { origin: { tier: 'registry', key: commandName }, steps: expandScript(registryEntry, workspaceRoot) };
+    return { origin: { tier: 'registry', key: commandName }, steps: expandScript(registryEntry, isWorkspaceRoot) };
 }

package/dist/esm/runCli.d.ts

@@ -1,7 +1,7 @@
 import type { Writable } from 'node:stream';
 /**
- * Marks a run made on a delegating caller's behalf, where a command the registry does not define exits 0
- * rather than failing.
+ * Marks a run made on a delegating caller's behalf, in which a command that the registry does not define, and a
+ * `--log` with nothing to show, exit 0 rather than failing.
  */
 export declare const RUN_IF_PRESENT_ENV_VAR = "NMR_RUN_IF_PRESENT";
 /** @internal */
@@ -10,11 +10,11 @@ export interface RunCliOptions {
     args: string[];
     /** Working directory used to resolve the nmr execution context. */
     cwd: string;
-    /** Environment for `runCli` (used for `NMR_RUN_IF_PRESENT` reads and `-R` writes). */
+    /** Environment from which `runCli` reads its settings, and the base of the one that its children inherit. */
     env: NodeJS.ProcessEnv;
-    /** Stream for normal output (help text, override messages). */
+    /** Stream for normal output: help, version, verdicts, recordings, and override notices. */
     stdout: Writable;
-    /** Stream for error output (unknown command, parse errors). */
+    /** Stream for errors, warnings, and debug notes. */
     stderr: Writable;
 }
 /** @internal */
@@ -23,7 +23,7 @@ export interface RunCliResult {
 }
 /**
  * Executes the nmr CLI flow in-process and returns the resulting exit code.
- * Holds no global state, reads no `process.*` globals, never calls `process.exit`.
+ * Does not hold global state, does not read `process.*` globals, and never calls `process.exit`.
  *
  * @internal
  */