@williamthorsen/nmr 0.37.0 → 0.38.0

package/dist/esm/commands/ensure-prepublish-hooks.js

@@ -1,5 +1,6 @@
 import { readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
+import { STATUS_GLYPHS } from '@williamthorsen/nmr-core';
 import { readPackageJson } from "../helpers/package-json.js";
 import { reportClosing } from "../helpers/reportClosing.js";
 import { isObject } from "../helpers/type-guards.js";
@@ -60,14 +61,14 @@ export function ensurePrepublishHooks(monorepoRoot, options) {
     const hasFailures = packages.some((p) => p.action === 'missing');
     return { packages, hasFailures };
 }
-export function reportPrepublishHooks(result, hookCommand) {
+export function reportPrepublishHooks(result, hookCommand, style) {
     const publishable = result.packages.filter((pkg) => !pkg.isPrivate);
     if (publishable.length === 0) {
         console.info('No publishable packages found.');
         return;
     }
     for (const pkg of publishable) {
-        console.info(renderHookStatus(pkg, hookCommand));
+        console.info(renderHookStatus(pkg, hookCommand, style));
     }
     reportClosing(describeHookRun(publishable));
 }
@@ -102,14 +103,15 @@ function describeHookRun(publishable) {
     }
     return `${packages} ${publishable.length === 1 ? 'has' : 'have'} prepublishOnly.`;
 }
-function renderHookStatus(pkg, hookCommand) {
+function renderHookStatus(pkg, hookCommand, style) {
+    const statuses = STATUS_GLYPHS[style];
     switch (pkg.action) {
         case 'ok':
-            return `✓ ${pkg.packageName}: prepublishOnly = "${pkg.prepublishOnly}"`;
+            return `${statuses.passed.text} ${pkg.packageName}: prepublishOnly = "${pkg.prepublishOnly}"`;
         case 'missing':
-            return `✗ ${pkg.packageName}: missing prepublishOnly`;
+            return `${statuses.failed.text} ${pkg.packageName}: missing prepublishOnly`;
         case 'fixed':
-            return `✓ ${pkg.packageName}: added prepublishOnly = "${hookCommand}"`;
+            return `${statuses.passed.text} ${pkg.packageName}: added prepublishOnly = "${hookCommand}"`;
         case 'would-fix':
             return `~ ${pkg.packageName}: would add prepublishOnly = "${hookCommand}"`;
     }

package/dist/esm/commands/report-catalog.d.ts

@@ -1,3 +1,4 @@
+import { type OutputStyle } from '@williamthorsen/nmr-core';
 /**
  * Reports the catalogued dependencies a package-scoped upgrade pass cannot see.
  *
@@ -8,4 +9,4 @@
  *
  * Runs ahead of the report produced by the workspace `upgrade` script.
  */
-export declare function reportCatalog(cwd: string): void;
+export declare function reportCatalog(cwd: string, style: OutputStyle): void;

package/dist/esm/commands/report-catalog.js

@@ -1,10 +1,11 @@
+import { formatGlyphLine } from '@williamthorsen/nmr-core';
 import { findContainingPackageDir } from "../context.js";
+import { NMR_GLYPHS } from "../glyphs.js";
 import { DEPENDENCY_FIELDS, readPackageJson } from "../helpers/package-json.js";
 import { reportClosing } from "../helpers/reportClosing.js";
 import { findMonorepoRoot, getWorkspacePackageDirs } from "../workspace.js";
-const CATALOG_ICON = '📚';
 const CATALOG_PROTOCOL = 'catalog:';
-export function reportCatalog(cwd) {
+export function reportCatalog(cwd, style) {
     const monorepoRoot = findMonorepoRoot(cwd);
     const packageDir = findContainingPackageDir(cwd, getWorkspacePackageDirs(monorepoRoot));
     if (packageDir === undefined) {
@@ -14,11 +15,11 @@ export function reportCatalog(cwd) {
     if (dependencies.length === 0) {
         return;
     }
-    console.warn(`${CATALOG_ICON} WARN: A package-scoped upgrade does not read the catalogs these come from:`);
+    console.warn(formatGlyphLine(NMR_GLYPHS, style, 'catalog', 'WARN: A package-scoped upgrade does not read the catalogs these come from:'));
     for (const { name, specifier } of dependencies) {
         console.warn(`- ${name} → ${specifier}`);
     }
-    reportClosing(`${CATALOG_ICON} ${describeCatalog(dependencies.length, monorepoRoot)}`, console.warn);
+    reportClosing(formatGlyphLine(NMR_GLYPHS, style, 'catalog', describeCatalog(dependencies.length, monorepoRoot)), console.warn);
 }
 function describeCatalog(count, monorepoRoot) {
     const subject = count === 1 ? '1 catalogued dependency went' : `${count} catalogued dependencies went`;

package/dist/esm/commands/report-overrides.d.ts

@@ -1,7 +1,8 @@
+import { type OutputStyle } from '@williamthorsen/nmr-core';
 /**
  * Reports the pnpm dependency overrides declared in the monorepo root's `pnpm-workspace.yaml`, and rejects a
  * `pnpm.overrides` block left behind in the root `package.json`.
  *
  * Runs ahead of the report produced by the root `upgrade` script.
  */
-export declare function reportOverrides(monorepoRoot: string): void;
+export declare function reportOverrides(monorepoRoot: string, style: OutputStyle): void;

package/dist/esm/commands/report-overrides.js

@@ -1,16 +1,17 @@
+import { formatGlyphLine } from '@williamthorsen/nmr-core';
+import { NMR_GLYPHS } from "../glyphs.js";
 import { getPnpmOverrides, readPackageJson } from "../helpers/package-json.js";
 import { reportClosing } from "../helpers/reportClosing.js";
 import { UserError } from "../UserError.js";
 import { readWorkspaceOverrides } from "../workspace.js";
-const OVERRIDES_ICON = '🔒';
-export function reportOverrides(monorepoRoot) {
+export function reportOverrides(monorepoRoot, style) {
     const declared = listEntries(readWorkspaceOverrides(monorepoRoot));
     if (declared.length > 0) {
-        console.warn(`${OVERRIDES_ICON} WARN: pnpm overrides are active:`);
+        console.warn(formatGlyphLine(NMR_GLYPHS, style, 'overrides', 'WARN: pnpm overrides are active:'));
         for (const [name, version] of declared) {
             console.warn(`- ${name} → ${version}`);
         }
-        reportClosing(`${OVERRIDES_ICON} ${describeOverrides(declared.length)}`, console.warn);
+        reportClosing(formatGlyphLine(NMR_GLYPHS, style, 'overrides', describeOverrides(declared.length)), console.warn);
     }
     rejectLegacyOverrides(monorepoRoot);
 }

package/dist/esm/config.js

@@ -33,7 +33,8 @@ const RECOGNIZED_KEYS = [...CONFIG_TIERS.root.honoredKeys, ...CONFIG_TIERS.works
 const RECOGNIZED_BUILD_KEYS = ['extraIgnorePatterns'];
 const RECOGNIZED_CHECK_CACHE_KEYS = ['enabled', 'excludeCommands', 'extraCommands'];
 const RECOGNIZED_OUTPUT_KEYS = ['commandVerbosity', 'extraAgentEnvVars'];
-const RECOGNIZED_STEP_KEYS = ['declinesArgs', 'run'];
+const RECOGNIZED_STEP_KEYS = ['run', 'shouldDeclineArguments'];
+const RETIRED_STEP_KEYS = new Map([['declinesArgs', 'shouldDeclineArguments']]);
 function isScriptRecord(value) {
     if (!isObject(value))
         return false;
@@ -50,8 +51,8 @@ function isScriptElement(value) {
         return true;
     if (!isObject(value) || typeof value['run'] !== 'string')
         return false;
-    const declinesArgs = value['declinesArgs'];
-    return declinesArgs === undefined || typeof declinesArgs === 'boolean';
+    const shouldDeclineArguments = value['shouldDeclineArguments'];
+    return shouldDeclineArguments === undefined || typeof shouldDeclineArguments === 'boolean';
 }
 function validateScriptField(value, fieldName, configPath) {
     if (!Object.hasOwn(value, fieldName) || value[fieldName] === undefined) {
@@ -60,7 +61,7 @@ function validateScriptField(value, fieldName, configPath) {
     const scripts = value[fieldName];
     if (!isScriptRecord(scripts)) {
         throw new UserError(`Invalid nmr config at ${configPath}: \`${fieldName}\` must be a Record<string, string | element[]>, ` +
-            'where an element is a command string or `{ run: string, declinesArgs?: boolean }`');
+            'where an element is a command string or `{ run: string, shouldDeclineArguments?: boolean }`');
     }
     assertValidElements(scripts, fieldName, configPath);
     return scripts;
@@ -71,6 +72,7 @@ function assertValidElements(scripts, fieldName, configPath) {
             continue;
         for (const spec of script) {
             if (typeof spec !== 'string') {
+                assertNoRetiredKeys(spec, RETIRED_STEP_KEYS, configPath, `${fieldName}.${command}.`);
                 assertRecognizedKeys(spec, RECOGNIZED_STEP_KEYS, configPath, `${fieldName}.${command}.`);
             }
             const element = typeof spec === 'string' ? spec : spec.run;
@@ -270,6 +272,14 @@ export async function loadWorkspaceConfig(packageDir) {
     assertTierKeys(config, CONFIG_TIERS.workspace, resolveConfigPath(packageDir));
     return config;
 }
+function assertNoRetiredKeys(value, retiredKeys, configPath, prefix) {
+    for (const key of Object.keys(value)) {
+        const replacement = retiredKeys.get(key);
+        if (replacement === undefined)
+            continue;
+        throw new UserError(`Invalid nmr config at ${configPath}: \`${prefix}${key}\` was renamed to \`${prefix}${replacement}\`.`);
+    }
+}
 function assertRecognizedKeys(value, recognizedKeys, configPath, prefix = '') {
     const unrecognized = Object.keys(value).filter((key) => !recognizedKeys.includes(key));
     if (unrecognized.length === 0) {

package/dist/esm/default-scripts.d.ts

@@ -1,6 +1,6 @@
 /**
  * One element of a composite, paired with what it does with the invocation's trailing arguments. The bare
- * string form of an element is this spec with `declinesArgs` left at its default.
+ * string form of an element is this spec with `shouldDeclineArguments` left at its default.
  */
 export interface StepSpec {
     /** A command name, optionally preceded by nmr's own flags, as it would be typed after `nmr`. */
@@ -9,7 +9,7 @@ export interface StepSpec {
      * Set where the trailing arguments cannot narrow this step's work: it is a prerequisite the narrowed steps
      * run against, or the tool it reaches would be misled by them. A declining step runs unnarrowed.
      */
-    declinesArgs?: boolean;
+    shouldDeclineArguments?: boolean;
 }
 export type ScriptValue = string | ReadonlyArray<string | StepSpec>;
 export type ScriptRegistry = Record<string, ScriptValue>;

package/dist/esm/default-scripts.js

@@ -1,6 +1,6 @@
 const GATE_PROJECTS = '--project unit --project tool';
-const TYPECHECK_STEP = { run: 'typecheck', declinesArgs: true };
-const ROOT_TYPECHECK_STEP = { run: 'root:typecheck', declinesArgs: true };
+const TYPECHECK_STEP = { run: 'typecheck', shouldDeclineArguments: true };
+const ROOT_TYPECHECK_STEP = { run: 'root:typecheck', shouldDeclineArguments: true };
 export const workspaceScripts = {
     build: ['compile'],
     check: [TYPECHECK_STEP, 'fmt:check', 'lint:check', 'test'],
@@ -32,7 +32,7 @@ export const rootScripts = {
     build: ['-R build'],
     check: [TYPECHECK_STEP, 'fmt:check', 'lint:check', 'test'],
     'check:strict': [TYPECHECK_STEP, 'fmt:check', 'lint:strict', 'test'],
-    ci: [{ run: 'build', declinesArgs: true }, 'check:strict'],
+    ci: [{ run: 'build', shouldDeclineArguments: true }, 'check:strict'],
     clean: 'nmr-clean',
     fix: ['lint', 'fmt'],
     'fix:check': ['fmt:check', 'lint:check'],
@@ -41,7 +41,7 @@ export const rootScripts = {
     lint: 'eslint --fix .',
     'lint:check': 'eslint .',
     'lint:strict': 'strict-lint',
-    prepush: [{ run: 'audit', declinesArgs: true }, 'ci'],
+    prepush: [{ run: 'audit', shouldDeclineArguments: true }, 'ci'],
     'report-overrides': 'nmr-report-overrides',
     'root:check': [ROOT_TYPECHECK_STEP, 'fmt:check', 'root:lint:check', 'root:test'],
     'root:lint': "eslint --fix --ignore-pattern 'packages/**' .",
@@ -59,6 +59,6 @@ export const rootScripts = {
     'test:tool': ['root:test:tool', '-R test:tool'],
     'test:unit': ['root:test:unit', '-R test:unit'],
     'test:watch': `vitest ${GATE_PROJECTS} --watch`,
-    typecheck: [ROOT_TYPECHECK_STEP, { run: '-R typecheck', declinesArgs: true }],
+    typecheck: [ROOT_TYPECHECK_STEP, { run: '-R typecheck', shouldDeclineArguments: true }],
     upgrade: 'nmr-report-overrides && nmr-taze --recursive',
 };

package/dist/esm/glyphs.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Glyphs that name no status; a status marker comes from nmr-core's `STATUS_GLYPHS`. A plain variant is empty
+ * where a word always follows the glyph, and a word where the glyph opens a line of its own.
+ *
+ * `noop` is a neutral circle: nothing ran because the repo asked for nothing to run, which is neither a
+ * failure nor a block.
+ */
+export declare const NMR_GLYPHS: Readonly<Record<"plain" | "rich", Readonly<Record<"overrides" | "clean" | "package" | "catalog" | "noop" | "recording", import("@williamthorsen/toolbelt.terminal/candidate").Glyph>>>>;
+export type NmrGlyphName = keyof (typeof NMR_GLYPHS)['rich'];

package/dist/esm/glyphs.js

@@ -0,0 +1,9 @@
+import { defineGlyphSet } from '@williamthorsen/nmr-core';
+export const NMR_GLYPHS = defineGlyphSet({
+    catalog: { plain: '', rich: '\u{1F4DA}' },
+    clean: { plain: '', rich: '\u{1F9F9}' },
+    noop: { plain: 'NOOP', rich: '\u{26AA}' },
+    overrides: { plain: '', rich: '\u{1F512}' },
+    package: { plain: '', rich: '\u{1F4E6}' },
+    recording: { plain: '', rich: '\u{1F4BE}' },
+});

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 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',
-        '  -?, --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/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);