@williamthorsen/nmr 0.36.0 → 0.38.0

package/dist/esm/help.js

@@ -1,19 +1,25 @@
 import { isHookName } from "./helpers/hook-name.js";
+import { OUTPUT_STYLE_ENV_VAR, OUTPUT_STYLE_FLAG } from "./output-style.js";
 import { buildRootRegistry, buildWorkspaceRegistry, describeScript, isSelfReferential, readPackageJsonScripts, } from "./resolver.js";
 export function generateHelp(config, packageDir, useRoot) {
     const lines = [
         'Usage: nmr [flags] <command> [args...]',
         '',
         'Flags:',
-        '  -F, --filter <pattern>   Run command in matching packages',
-        '  -R, --recursive          Run command in all packages',
-        '  -w, --workspace-root     Use root scripts, running at the monorepo root',
-        "  -q, --quiet              Suppress command output, keeping nmr's verdicts",
-        '      --json               Report one JSON object per command, withholding command output',
-        '      --log                Print the recorded run instead of running (up to 256 KiB)',
-        '      --no-cache           Run even if this tree already passed; record the result',
-        '  -?, --help               Show this help',
-        '  -V, --version            Show version number',
+        '  -F, --filter <pattern>      Run command in packages whose manifest name matches',
+        '  -R, --recursive             Run command in all packages',
+        '  -w, --workspace-root        Use root scripts, running at the monorepo root',
+        "  -q, --quiet                 Suppress command output, keeping nmr's verdicts",
+        '      --json                  Report one JSON object per command, withholding command output',
+        '      --log                   Print the recorded run instead of running (up to 256 KiB)',
+        '      --no-cache              Run even if this tree already passed; record the result',
+        `      ${OUTPUT_STYLE_FLAG} <style>  Output style: auto (default), plain, or rich`,
+        '  -?, --help                  Show this help',
+        '  -V, --version               Show version number',
+        '',
+        'Environment:',
+        `  ${OUTPUT_STYLE_ENV_VAR}            Output style: auto (default), plain, or rich. auto prints`,
+        '                              plain, without emoji, when CI is set or the stream is not a terminal.',
         '',
         'Workspace commands:',
     ];

package/dist/esm/helpers/filter-selection.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Asks pnpm what a `-F` pattern selects, so an invocation that would select nothing is caught before it
+ * delegates, and one selecting several packages is told from one selecting a single package.
+ *
+ * pnpm's own selector answers rather than a matcher of nmr's: `-F` means the whole selector language, names
+ * and globs alongside `./path`, `{dir}`, `pkg...`, `!negation`, and `[since]`, and a matcher here would leave
+ * every form but the simplest silently unchecked.
+ *
+ * Runs from the monorepo root, where the delegate runs, so a path pattern resolves against the same directory
+ * in the probe as in the run it stands in for.
+ *
+ * The listing counts the root project wherever the filter leaves it standing, while the `exec` a delegation
+ * composes runs there only where the pattern selects the root positively: `-F '!./packages/*'` lists the root
+ * and executes nowhere. A listing of the root alone is therefore the one reading the listing cannot settle,
+ * and it is put to `exec` itself. Every other listing settles on its own, and counts the packages beside the
+ * root: two of them run in two scopes, while one beside the root may run in that package alone.
+ */
+export declare function readFilterSelection(pattern: string, monorepoRoot: string): FilterSelection;
+/**
+ * Reduces a listing to what it proves about the selection.
+ *
+ * Every outcome the probe cannot read resolves to `unresolved`, which claims nothing about the selection, and the
+ * invocation delegates as it would have. A pattern pnpm rejects rather than resolves, such as a bad git ref in
+ * a changed-since selector, is pnpm's to report, and reporting it here as a match failure would name a
+ * different fault than the one the user has.
+ */
+export declare function interpretSelectionProbe(probe: SelectionProbe, monorepoRoot: string): ProbeReading;
+/**
+ * Reduces a marked delegate run to what it proves: a scope that wrote the marker is a scope the run reached. The
+ * run is made only for a listing of the root alone, so that scope is the only one.
+ */
+export declare function interpretDelegateProbe(probe: SelectionProbe): FilterSelection;
+/** What a `-F` pattern selected, as far as pnpm could be asked. `multiple` is two or more packages beside the root. */
+export type FilterSelection = 'empty' | 'multiple' | 'single' | 'unresolved';
+/** What a listing proves, `root-only` being the reading that only the delegate can settle. */
+export type ProbeReading = FilterSelection | 'root-only';
+/** The part of a probe's completion a selection is read from. */
+export interface SelectionProbe {
+    error: Error | undefined;
+    status: number | null;
+    stdout: string;
+}

package/dist/esm/helpers/filter-selection.js

@@ -0,0 +1,61 @@
+import { spawnSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { isObject } from "./type-guards.js";
+const SELECTION_MARKER = 'nmr-selected-scope';
+export function readFilterSelection(pattern, monorepoRoot) {
+    const listing = spawnSync('pnpm', ['ls', '--filter', pattern, '--depth', '-1', '--json'], {
+        cwd: monorepoRoot,
+        encoding: 'utf8',
+    });
+    const reading = interpretSelectionProbe({ error: listing.error, status: listing.status, stdout: listing.stdout }, monorepoRoot);
+    return reading === 'root-only' ? readDelegateSelection(pattern, monorepoRoot) : reading;
+}
+export function interpretSelectionProbe(probe, monorepoRoot) {
+    if (probe.error !== undefined || probe.status !== 0) {
+        return 'unresolved';
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(probe.stdout);
+    }
+    catch {
+        return 'unresolved';
+    }
+    if (!Array.isArray(parsed)) {
+        return 'unresolved';
+    }
+    if (parsed.length === 0) {
+        return 'empty';
+    }
+    const packageCount = parsed.filter((entry) => !isRootEntry(entry, monorepoRoot)).length;
+    if (packageCount === 0) {
+        return 'root-only';
+    }
+    return packageCount === 1 ? 'single' : 'multiple';
+}
+export function interpretDelegateProbe(probe) {
+    if (probe.error !== undefined || probe.status !== 0) {
+        return 'unresolved';
+    }
+    return probe.stdout.includes(SELECTION_MARKER) ? 'single' : 'empty';
+}
+function isRootEntry(entry, monorepoRoot) {
+    if (!isObject(entry) || typeof entry['path'] !== 'string') {
+        return false;
+    }
+    return readRealPath(entry['path']) === readRealPath(monorepoRoot);
+}
+function readRealPath(target) {
+    try {
+        return realpathSync(target);
+    }
+    catch {
+        return path.resolve(target);
+    }
+}
+function readDelegateSelection(pattern, monorepoRoot) {
+    const probe = spawnSync('pnpm', ['--filter', pattern, 'exec', process.execPath, '--eval', `process.stdout.write('${SELECTION_MARKER}')`], { cwd: monorepoRoot, encoding: 'utf8' });
+    return interpretDelegateProbe({ error: probe.error, status: probe.status, stdout: probe.stdout });
+}

package/dist/esm/output-style.d.ts

@@ -0,0 +1,41 @@
+import type { Writable } from 'node:stream';
+import { type StreamStyleResolution } from '@williamthorsen/nmr-core';
+/**
+ * Reports whether a stream is backed by a terminal, which is what detection reads where no source names a
+ * style. A stream carrying no `isTTY`, which is the one a test injects, is not one.
+ */
+export declare function isTerminalStream(stream: Writable): boolean;
+/**
+ * Carries the resolved style down the spawned chain, so the flag reaches every process rather than the first
+ * and a child writing to a pipe renders as its parent does rather than detecting plain on its own descriptor.
+ *
+ * Deliberately not a keyed variable, on neither the pass key nor the retention key: it changes how a run
+ * renders and never what a command concludes, so folding it into either would stop a plain run from hitting a
+ * pass a rich one recorded.
+ */
+export declare const OUTPUT_STYLE_ENV_VAR = "NMR_OUTPUT_STYLE";
+/**
+ * The flag naming a style for one invocation, which outranks `OUTPUT_STYLE_ENV_VAR`.
+ *
+ * `nmr` alone carries it. A standalone bin takes the variable, which `nmr <command>` exports to it, so adding
+ * a style to a bin does not mean adding a flag to each bin's own parser.
+ */
+export declare const OUTPUT_STYLE_FLAG = "--output-style";
+/**
+ * Resolves the style of each output stream: the flag, then `NMR_OUTPUT_STYLE`, then detection from `CI`, the
+ * stream's terminal state, and `TERM`.
+ *
+ * Never throws. A value naming no style is returned in `invalid`, for the caller to report with
+ * `describeInvalidOutputStyle`, because the caller has to render that complaint in some style.
+ *
+ * The flag's raw value is handed to nmr-core as an assignment rather than narrowed here, so nmr rejects a
+ * misspelling in the words its siblings use and no second ladder can come to name a different one.
+ */
+export declare function resolveOutputStyles(options: ResolveOutputStylesOptions): StreamStyleResolution;
+export interface ResolveOutputStylesOptions {
+    env: NodeJS.ProcessEnv;
+    /** The value the flag was given, absent where the invocation carries none, as a bin's invocation always does. */
+    flagValue?: string | undefined;
+    stderrIsTty: boolean;
+    stdoutIsTty: boolean;
+}

package/dist/esm/output-style.js

@@ -0,0 +1,17 @@
+import { resolveStreamStyles } from '@williamthorsen/nmr-core';
+export function isTerminalStream(stream) {
+    return 'isTTY' in stream && stream.isTTY === true;
+}
+export const OUTPUT_STYLE_ENV_VAR = 'NMR_OUTPUT_STYLE';
+export const OUTPUT_STYLE_FLAG = '--output-style';
+export function resolveOutputStyles(options) {
+    const { env, flagValue, stderrIsTty, stdoutIsTty } = options;
+    return resolveStreamStyles({
+        argv: flagValue === undefined ? [] : [`${OUTPUT_STYLE_FLAG}=${flagValue}`],
+        env,
+        envVar: OUTPUT_STYLE_ENV_VAR,
+        flag: OUTPUT_STYLE_FLAG,
+        stderrIsTty,
+        stdoutIsTty,
+    });
+}

package/dist/esm/recording.d.ts

@@ -1,3 +1,4 @@
+import { type OutputStyle } from '@williamthorsen/nmr-core';
 import { type CheckCacheEntry } from './check-cache.js';
 /**
  * What this invocation would be recorded under, insofar as an entry records the same facts. A mismatch is read
@@ -75,6 +76,7 @@ export declare function renderRecording(options: {
     command: string;
     recording: Recording;
     scope: string;
+    style: OutputStyle;
 }): string;
 /**
  * Renders a refusal on the one line a fan-out can attribute, in the grammar a verdict uses: the scope, the
@@ -84,6 +86,7 @@ export declare function renderRefusal(options: {
     command: string;
     refusal: RecordingRefusal;
     scope: string;
+    style: OutputStyle;
 }): string;
 /**
  * Resolves what one scope has to show for one command.

package/dist/esm/recording.js

@@ -1,14 +1,17 @@
+import { formatGlyphLine, STATUS_GLYPHS } from '@williamthorsen/nmr-core';
 import { readCheckCacheEntry, readTranscript } from "./check-cache.js";
+import { NMR_GLYPHS } from "./glyphs.js";
 import { formatDuration } from "./helpers/duration.js";
 export function renderRecording(options) {
     const { entry } = options.recording;
     const age = formatDuration(Math.max(0, Date.now() - Date.parse(entry.recordedAt)));
-    const header = `📼 ${options.scope}: ${options.command} — recorded ${entry.recordedAt} (${age} ago), ` +
-        `ran in ${formatDuration(entry.durationMs)}\n$ ${entry.commandString}\n\n`;
+    const header = formatGlyphLine(NMR_GLYPHS, options.style, 'recording', `${options.scope}: ${options.command} — recorded ${entry.recordedAt} (${age} ago), ` +
+        `ran in ${formatDuration(entry.durationMs)}`) + `\n$ ${entry.commandString}\n\n`;
     return `${header}${appendNewline(renderBody(options.recording))}`;
 }
 export function renderRefusal(options) {
-    return `📭 ${options.scope}: ${options.command}: no recording; ${describeRefusal(options.command, options.refusal)}`;
+    const { text } = STATUS_GLYPHS[options.style].warning;
+    return `${text} ${options.scope}: ${options.command}: no recording; ${describeRefusal(options.command, options.refusal)}`;
 }
 export async function resolveRecording(options) {
     const { anchorDir, command, monorepoRoot } = options;

package/dist/esm/resolveBinStyles.d.ts

@@ -0,0 +1,12 @@
+import { type StreamStyles } from '@williamthorsen/nmr-core';
+/**
+ * Resolves the style of the running process's own output streams, and rejects a variable naming no style.
+ *
+ * What a standalone bin calls. A bin carries no `--output-style` of its own: the flag is `nmr`'s, and what
+ * reaches a bin is the variable that `nmr <command>` exports to it, so a bin run through nmr renders as nmr
+ * does and one run on its own detects its streams.
+ *
+ * Throws rather than exiting, so the bin's own boundary reports the message and sets the exit code, as it does
+ * for every other failure in what the caller declared.
+ */
+export declare function resolveBinStyles(): StreamStyles;

package/dist/esm/resolveBinStyles.js

@@ -0,0 +1,16 @@
+import process from 'node:process';
+import { describeInvalidOutputStyle } from '@williamthorsen/nmr-core';
+import { resolveOutputStyles } from "./output-style.js";
+import { UserError } from "./UserError.js";
+export function resolveBinStyles() {
+    const { invalid, styles } = resolveOutputStyles({
+        env: process.env,
+        flagValue: undefined,
+        stderrIsTty: process.stderr.isTTY,
+        stdoutIsTty: process.stdout.isTTY,
+    });
+    if (invalid !== undefined) {
+        throw new UserError(describeInvalidOutputStyle(invalid));
+    }
+    return styles;
+}

package/dist/esm/resolver.js

@@ -46,7 +46,7 @@ export function expandScript(script, workspaceRoot) {
     }
     return script.map((element) => typeof element === 'string'
         ? composeNmrStep(element, workspaceRoot)
-        : composeNmrStep(element.run, workspaceRoot, element.declinesArgs));
+        : composeNmrStep(element.run, workspaceRoot, element.shouldDeclineArguments));
 }
 export function describeScript(script) {
     return typeof script === 'string' ? script : `[${script.map(describeElement).join(', ')}]`;
@@ -55,7 +55,7 @@ function describeElement(element) {
     if (typeof element === 'string') {
         return element;
     }
-    return element.declinesArgs === true ? `${element.run} (no args)` : element.run;
+    return element.shouldDeclineArguments === true ? `${element.run} (no args)` : element.run;
 }
 export function readPackageJsonScripts(packageDir) {
     const file = resolvePackageJsonPath(packageDir);