@williamthorsen/nmr 0.30.0 → 0.32.0

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

@@ -0,0 +1,40 @@
+import { findContainingPackageDir } from "../context.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) {
+    const monorepoRoot = findMonorepoRoot(cwd);
+    const packageDir = findContainingPackageDir(cwd, getWorkspacePackageDirs(monorepoRoot));
+    if (packageDir === undefined) {
+        return;
+    }
+    const dependencies = findCataloguedDependencies(packageDir);
+    if (dependencies.length === 0) {
+        return;
+    }
+    console.warn(`${CATALOG_ICON} 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);
+}
+function describeCatalog(count, monorepoRoot) {
+    const subject = count === 1 ? '1 catalogued dependency went' : `${count} catalogued dependencies went`;
+    const object = count === 1 ? 'it' : 'them';
+    return `${subject} unread. Run \`nmr upgrade\` from ${monorepoRoot} to include ${object}.`;
+}
+function findCataloguedDependencies(packageDir) {
+    const pkg = readPackageJson(packageDir);
+    const found = new Map();
+    for (const field of DEPENDENCY_FIELDS) {
+        const declared = Object.entries(pkg[field] ?? {});
+        for (const [name, specifier] of declared) {
+            if (specifier.startsWith(CATALOG_PROTOCOL) && !found.has(name)) {
+                found.set(name, specifier);
+            }
+        }
+    }
+    return [...found].map(([name, specifier]) => ({ name, specifier })).toSorted((a, b) => a.name.localeCompare(b.name));
+}

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

@@ -1,12 +1,35 @@
 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) {
-    const pkg = readPackageJson(monorepoRoot);
-    const overrides = getPnpmOverrides(pkg);
-    if (!overrides || Object.keys(overrides).length === 0) {
-        return;
+    const declared = listEntries(readWorkspaceOverrides(monorepoRoot));
+    if (declared.length > 0) {
+        console.warn(`${OVERRIDES_ICON} WARN: pnpm overrides are active:`);
+        for (const [name, version] of declared) {
+            console.warn(`- ${name} → ${version}`);
+        }
+        reportClosing(`${OVERRIDES_ICON} ${describeOverrides(declared.length)}`, console.warn);
     }
-    console.warn('🔒 WARN: pnpm overrides are active! Check whether these are still needed:');
-    for (const [name, version] of Object.entries(overrides)) {
-        console.warn(`- ${name} → ${version}`);
+    rejectLegacyOverrides(monorepoRoot);
+}
+function describeOverrides(count) {
+    return count === 1
+        ? '1 override is active. Check whether it is still needed.'
+        : `${count} overrides are active. Check whether they are still needed.`;
+}
+function listEntries(overrides) {
+    return Object.entries(overrides ?? {}).toSorted(([a], [b]) => a.localeCompare(b));
+}
+function rejectLegacyOverrides(monorepoRoot) {
+    const legacy = listEntries(getPnpmOverrides(readPackageJson(monorepoRoot)));
+    if (legacy.length === 0) {
+        return;
     }
+    throw new UserError([
+        'pnpm 11 reads no `pnpm.overrides` from package.json, so these pin nothing while an upgrade run with `--write` goes on rewriting them:',
+        ...legacy.map(([name, version]) => `- ${name} → ${String(version)}`),
+        'Move them to the `overrides` block in pnpm-workspace.yaml, quoting each version, or run `pnpx codemod run pnpm-v10-to-v11`.',
+    ].join('\n'));
 }

package/dist/esm/commands/taze.js

@@ -2,6 +2,7 @@ import { spawnSync } from 'node:child_process';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 import { reportError } from '@williamthorsen/nmr-core';
+import { describeError } from '@williamthorsen/toolbelt.errors';
 const TAZE_CLI_SPECIFIER = 'taze/cli';
 export function runTaze(args, options = {}) {
     const stderr = options.stderr ?? process.stderr;
@@ -12,7 +13,7 @@ export function runTaze(args, options = {}) {
         cliPath = resolveCliPath();
     }
     catch (error) {
-        const detail = error instanceof Error ? error.message : String(error);
+        const detail = describeError(error);
         reportError(`Could not resolve '${TAZE_CLI_SPECIFIER}' from nmr's dependencies. Reinstall the workspace to restore it. (${detail})`, stderr);
         return 1;
     }

package/dist/esm/config.d.ts

@@ -1,4 +1,5 @@
 import type { NmrConfig } from './types.js';
+export declare const CONFIG_RELATIVE_PATH: string;
 export declare function resolveConfigPath(baseDir: string): string;
 export declare function loadConfig(baseDir: string): Promise<NmrConfig>;
 export declare function loadRootConfig(monorepoRoot: string): Promise<NmrConfig>;

package/dist/esm/config.js

@@ -11,12 +11,15 @@ import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { isObject, isStringRecord } from "./helpers/type-guards.js";
 import { findUnexpressibleToken } from "./steps.js";
+import { UserError } from "./UserError.js";
+import { formatVerbosityRejection, isCommandVerbosity } from "./verbosity.js";
 const CONFIG_FILENAME = 'nmr.config.ts';
 const CONFIG_DIR = '.config';
+export const CONFIG_RELATIVE_PATH = path.join(CONFIG_DIR, CONFIG_FILENAME);
 const CONFIG_TIERS = {
     root: {
         label: 'a monorepo-root config',
-        honoredKeys: ['checkCache', 'devBin', 'rootScripts', 'workspaceScripts'],
+        honoredKeys: ['checkCache', 'devBin', 'output', 'rootScripts', 'workspaceScripts'],
         elsewhere: "the package's own config",
     },
     workspace: {
@@ -28,6 +31,8 @@ const CONFIG_TIERS = {
 const RECOGNIZED_KEYS = [...CONFIG_TIERS.root.honoredKeys, ...CONFIG_TIERS.workspace.honoredKeys];
 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'];
 export function resolveConfigPath(baseDir) {
     return path.join(baseDir, CONFIG_DIR, CONFIG_FILENAME);
 }
@@ -35,33 +40,46 @@ function isScriptRecord(value) {
     if (!isObject(value))
         return false;
     for (const v of Object.values(value)) {
-        if (typeof v !== 'string' && !Array.isArray(v))
-            return false;
-        if (Array.isArray(v) && v.some((item) => typeof item !== 'string'))
+        if (typeof v === 'string')
+            continue;
+        if (!Array.isArray(v) || !v.every(isScriptElement))
             return false;
     }
     return true;
 }
+function isScriptElement(value) {
+    if (typeof value === 'string')
+        return true;
+    if (!isObject(value) || typeof value['run'] !== 'string')
+        return false;
+    const declinesArgs = value['declinesArgs'];
+    return declinesArgs === undefined || typeof declinesArgs === 'boolean';
+}
 function validateScriptField(value, fieldName, configPath) {
     if (!Object.hasOwn(value, fieldName) || value[fieldName] === undefined) {
         return undefined;
     }
     const scripts = value[fieldName];
     if (!isScriptRecord(scripts)) {
-        throw new Error(`Invalid nmr config at ${configPath}: \`${fieldName}\` must be a Record<string, string | string[]>`);
+        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 }`');
     }
-    assertExpressibleElements(scripts, fieldName, configPath);
+    assertValidElements(scripts, fieldName, configPath);
     return scripts;
 }
-function assertExpressibleElements(scripts, fieldName, configPath) {
+function assertValidElements(scripts, fieldName, configPath) {
     for (const [command, script] of Object.entries(scripts)) {
         if (typeof script === 'string')
             continue;
-        for (const element of script) {
+        for (const spec of script) {
+            if (typeof spec !== 'string') {
+                assertRecognizedKeys(spec, RECOGNIZED_STEP_KEYS, configPath, `${fieldName}.${command}.`);
+            }
+            const element = typeof spec === 'string' ? spec : spec.run;
             const token = findUnexpressibleToken(element);
             if (token === undefined)
                 continue;
-            throw new Error(`Invalid nmr config at ${configPath}: \`${fieldName}.${command}\` element \`${element}\` carries ` +
+            throw new UserError(`Invalid nmr config at ${configPath}: \`${fieldName}.${command}\` element \`${element}\` carries ` +
                 `\`${token}\`, which is neither a command name nor an nmr flag. Name it as a script of its own and ` +
                 `reference that name here.`);
         }
@@ -76,12 +94,12 @@ function validateBuildField(value, configPath) {
         return undefined;
     }
     if (!isObject(build)) {
-        throw new Error(`Invalid nmr config at ${configPath}: \`build\` must be an object`);
+        throw new UserError(`Invalid nmr config at ${configPath}: \`build\` must be an object`);
     }
     assertRecognizedKeys(build, RECOGNIZED_BUILD_KEYS, configPath, 'build.');
     const extraIgnorePatterns = build['extraIgnorePatterns'];
     if (extraIgnorePatterns !== undefined && !isStringArray(extraIgnorePatterns)) {
-        throw new Error(`Invalid nmr config at ${configPath}: \`build.extraIgnorePatterns\` must be a string[]`);
+        throw new UserError(`Invalid nmr config at ${configPath}: \`build.extraIgnorePatterns\` must be a string[]`);
     }
     return extraIgnorePatterns === undefined ? {} : { extraIgnorePatterns };
 }
@@ -91,14 +109,14 @@ function validateCheckCacheField(value, configPath) {
         return undefined;
     }
     if (!isObject(checkCache)) {
-        throw new Error(`Invalid nmr config at ${configPath}: \`checkCache\` must be an object`);
+        throw new UserError(`Invalid nmr config at ${configPath}: \`checkCache\` must be an object`);
     }
     assertRecognizedKeys(checkCache, RECOGNIZED_CHECK_CACHE_KEYS, configPath, 'checkCache.');
     const config = {};
     const enabled = checkCache['enabled'];
     if (enabled !== undefined) {
         if (typeof enabled !== 'boolean') {
-            throw new TypeError(`Invalid nmr config at ${configPath}: \`checkCache.enabled\` must be a boolean`);
+            throw new UserError(`Invalid nmr config at ${configPath}: \`checkCache.enabled\` must be a boolean`);
         }
         config.enabled = enabled;
     }
@@ -108,24 +126,51 @@ function validateCheckCacheField(value, configPath) {
             continue;
         }
         if (!isStringArray(commands)) {
-            throw new Error(`Invalid nmr config at ${configPath}: \`checkCache.${field}\` must be a string[]`);
+            throw new UserError(`Invalid nmr config at ${configPath}: \`checkCache.${field}\` must be a string[]`);
         }
         config[field] = commands;
     }
     return config;
 }
+function validateOutputField(value, configPath) {
+    const output = value['output'];
+    if (output === undefined) {
+        return undefined;
+    }
+    if (!isObject(output)) {
+        throw new UserError(`Invalid nmr config at ${configPath}: \`output\` must be an object`);
+    }
+    assertRecognizedKeys(output, RECOGNIZED_OUTPUT_KEYS, configPath, 'output.');
+    const config = {};
+    const commandVerbosity = output['commandVerbosity'];
+    if (commandVerbosity !== undefined) {
+        if (typeof commandVerbosity !== 'string' || !isCommandVerbosity(commandVerbosity)) {
+            const rendered = typeof commandVerbosity === 'string' ? commandVerbosity : JSON.stringify(commandVerbosity);
+            throw new UserError(`Invalid nmr config at ${configPath}: ${formatVerbosityRejection('`output.commandVerbosity`', rendered)}`);
+        }
+        config.commandVerbosity = commandVerbosity;
+    }
+    const extraAgentEnvVars = output['extraAgentEnvVars'];
+    if (extraAgentEnvVars !== undefined) {
+        if (!isStringArray(extraAgentEnvVars)) {
+            throw new UserError(`Invalid nmr config at ${configPath}: \`output.extraAgentEnvVars\` must be a string[]`);
+        }
+        config.extraAgentEnvVars = extraAgentEnvVars;
+    }
+    return config;
+}
 function validateStringRecordField(value, fieldName, configPath) {
     if (!Object.hasOwn(value, fieldName) || value[fieldName] === undefined) {
         return undefined;
     }
     if (!isStringRecord(value[fieldName])) {
-        throw new Error(`Invalid nmr config at ${configPath}: \`${fieldName}\` must be a Record<string, string>`);
+        throw new UserError(`Invalid nmr config at ${configPath}: \`${fieldName}\` must be a Record<string, string>`);
     }
     return value[fieldName];
 }
 function validateConfig(value, configPath) {
     if (!isObject(value)) {
-        throw new Error(`Invalid nmr config at ${configPath}: expected an object, got ${typeof value}`);
+        throw new UserError(`Invalid nmr config at ${configPath}: expected an object, got ${typeof value}`);
     }
     assertRecognizedKeys(value, RECOGNIZED_KEYS, configPath);
     const config = {};
@@ -138,6 +183,9 @@ function validateConfig(value, configPath) {
     const devBin = validateStringRecordField(value, 'devBin', configPath);
     if (devBin)
         config.devBin = devBin;
+    const output = validateOutputField(value, configPath);
+    if (output)
+        config.output = output;
     const workspaceScripts = validateScriptField(value, 'workspaceScripts', configPath);
     if (workspaceScripts)
         config.workspaceScripts = workspaceScripts;
@@ -170,7 +218,7 @@ function assertRecognizedKeys(value, recognizedKeys, configPath, prefix = '') {
     if (unrecognized.length === 0) {
         return;
     }
-    throw new Error(`Invalid nmr config at ${configPath}: unrecognized ${unrecognized.length === 1 ? 'key' : 'keys'} ` +
+    throw new UserError(`Invalid nmr config at ${configPath}: unrecognized ${unrecognized.length === 1 ? 'key' : 'keys'} ` +
         `${formatKeyList(unrecognized, prefix)}. Recognized: ${formatKeyList(recognizedKeys, prefix)}.`);
 }
 function assertTierKeys(config, tier, configPath) {
@@ -178,7 +226,7 @@ function assertTierKeys(config, tier, configPath) {
     if (unsupported.length === 0) {
         return;
     }
-    throw new Error(`Invalid nmr config at ${configPath}: ${tier.label} honors ${tier.honoredKeys.toSorted().join(', ')} alone, ` +
+    throw new UserError(`Invalid nmr config at ${configPath}: ${tier.label} honors ${tier.honoredKeys.toSorted().join(', ')} alone, ` +
         `not ${unsupported.toSorted().join(', ')}. Move those keys to ${tier.elsewhere}.`);
 }
 function formatKeyList(keys, prefix) {

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

@@ -1,4 +1,8 @@
-export type ScriptValue = string | string[];
+export interface StepSpec {
+    run: string;
+    declinesArgs?: boolean;
+}
+export type ScriptValue = string | ReadonlyArray<string | StepSpec>;
 export type ScriptRegistry = Record<string, ScriptValue>;
 export declare const workspaceScripts: ScriptRegistry;
 export declare const rootScripts: ScriptRegistry;

package/dist/esm/default-scripts.js

@@ -1,8 +1,10 @@
 const GATE_PROJECTS = '--project unit --project tool';
+const TYPECHECK_STEP = { run: 'typecheck', declinesArgs: true };
+const ROOT_TYPECHECK_STEP = { run: 'root:typecheck', declinesArgs: true };
 export const workspaceScripts = {
     build: ['compile'],
-    check: ['typecheck', 'fmt:check', 'lint:check', 'test'],
-    'check:strict': ['typecheck', 'fmt:check', 'lint:strict', 'test:coverage'],
+    check: [TYPECHECK_STEP, 'fmt:check', 'lint:check', 'test'],
+    'check:strict': [TYPECHECK_STEP, 'fmt:check', 'lint:strict', 'test:coverage'],
     clean: 'nmr-clean',
     compile: 'nmr-compile',
     fix: ['lint', 'fmt'],
@@ -12,6 +14,7 @@ export const workspaceScripts = {
     lint: 'eslint --fix .',
     'lint:check': 'eslint .',
     'lint:strict': 'strict-lint',
+    'report-catalog': 'nmr-report-catalog',
     test: `pnpm exec vitest ${GATE_PROJECTS}`,
     'test:all': 'pnpm exec vitest',
     'test:coverage': `pnpm exec vitest ${GATE_PROJECTS} --coverage`,
@@ -19,7 +22,7 @@ export const workspaceScripts = {
     'test:unit': 'pnpm exec vitest --project unit',
     'test:watch': `pnpm exec vitest ${GATE_PROJECTS} --watch`,
     typecheck: 'tsgo --noEmit',
-    upgrade: 'nmr-taze --include-locked',
+    upgrade: 'nmr-report-catalog && nmr-taze --include-locked',
     'view-coverage': 'open coverage/index.html',
 };
 export const rootScripts = {
@@ -27,9 +30,9 @@ export const rootScripts = {
     'audit:dev': 'pnpm exec v11y --dev',
     'audit:prod': 'pnpm exec v11y --prod',
     build: ['-R build'],
-    check: ['typecheck', 'fmt:check', 'lint:check', 'test'],
-    'check:strict': ['typecheck', 'fmt:check', 'lint:strict', 'test:coverage'],
-    ci: ['build', 'check:strict'],
+    check: [TYPECHECK_STEP, 'fmt:check', 'lint:check', 'test'],
+    'check:strict': [TYPECHECK_STEP, 'fmt:check', 'lint:strict', 'test:coverage'],
+    ci: [{ run: 'build', declinesArgs: true }, 'check:strict'],
     clean: 'nmr-clean',
     fix: ['lint', 'fmt'],
     'fix:check': ['fmt:check', 'lint:check'],
@@ -38,9 +41,9 @@ export const rootScripts = {
     lint: 'eslint --fix .',
     'lint:check': 'eslint .',
     'lint:strict': 'strict-lint',
-    prepush: ['audit', 'ci'],
+    prepush: [{ run: 'audit', declinesArgs: true }, 'ci'],
     'report-overrides': 'nmr-report-overrides',
-    'root:check': ['root:typecheck', 'fmt:check', 'root:lint:check', 'root:test'],
+    'root:check': [ROOT_TYPECHECK_STEP, 'fmt:check', 'root:lint:check', 'root:test'],
     'root:lint': "eslint --fix --ignore-pattern 'packages/**' .",
     'root:lint:check': "eslint --ignore-pattern 'packages/**' .",
     'root:lint:strict': "strict-lint --ignore-pattern 'packages/**' .",
@@ -49,13 +52,13 @@ export const rootScripts = {
     'root:test:tool': 'vitest --config ./vitest.root.config.ts --project tool',
     'root:test:unit': 'vitest --config ./vitest.root.config.ts --project unit',
     'root:typecheck': 'tsgo --noEmit',
-    'root:upgrade': 'nmr-taze --include-locked',
+    'root:upgrade': 'nmr-report-overrides && nmr-taze --include-locked',
     test: ['root:test', '-R test'],
     'test:all': ['root:test:all', '-R test:all'],
     'test:coverage': ['root:test', '-R test:coverage'],
     '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', '-R typecheck'],
+    typecheck: [ROOT_TYPECHECK_STEP, { run: '-R typecheck', declinesArgs: true }],
     upgrade: 'nmr-report-overrides && nmr-taze --include-locked --recursive',
 };

package/dist/esm/defineConfig.d.ts

@@ -1,3 +1,3 @@
 import type { NmrConfig } from './types.js';
-export type { BuildConfig, CheckCacheConfig, NmrConfig } from './types.js';
+export type { BuildConfig, CheckCacheConfig, CommandVerbosity, NmrConfig, OutputConfig, ScriptValue, StepSpec, } from './types.js';
 export declare function defineConfig(config: NmrConfig): NmrConfig;

package/dist/esm/help.js

@@ -8,7 +8,9 @@ export function generateHelp(config, packageDir, useRoot) {
         '  -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 output on success; show full output on failure',
+        "  -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',

package/dist/esm/helpers/clampToBytes.d.ts

@@ -0,0 +1,2 @@
+export declare const TRUNCATION_MARK = "\u2026";
+export declare function clampToBytes(value: string, budgetBytes: number): string;

package/dist/esm/helpers/clampToBytes.js

@@ -0,0 +1,20 @@
+export const TRUNCATION_MARK = '…';
+export function clampToBytes(value, budgetBytes) {
+    if (Buffer.byteLength(value) <= budgetBytes) {
+        return value;
+    }
+    const budget = budgetBytes - Buffer.byteLength(TRUNCATION_MARK);
+    if (budget < 0) {
+        return '';
+    }
+    let kept = '';
+    let bytes = 0;
+    for (const character of value) {
+        const size = Buffer.byteLength(character);
+        if (bytes + size > budget)
+            break;
+        kept += character;
+        bytes += size;
+    }
+    return `${kept}${TRUNCATION_MARK}`;
+}

package/dist/esm/helpers/createBoundedBuffer.js

@@ -1,3 +1,4 @@
+import { formatElisionMarker } from "./transcript.js";
 const DEFAULT_HEAD_LIMIT_BYTES = 1_048_576;
 const DEFAULT_TAIL_LIMIT_BYTES = 1_048_576;
 export function createBoundedBuffer(options = {}) {
@@ -54,7 +55,3 @@ export function createBoundedBuffer(options = {}) {
     }
     return { append, toBuffer };
 }
-function formatElisionMarker(byteCount) {
-    const unit = byteCount === 1 ? 'byte' : 'bytes';
-    return `\n… nmr elided ${byteCount.toLocaleString('en-US')} ${unit} …\n`;
-}

package/dist/esm/helpers/deriveExcerpt.d.ts

@@ -0,0 +1 @@
+export declare function deriveExcerpt(transcript: string): string | undefined;

package/dist/esm/helpers/deriveExcerpt.js

@@ -0,0 +1,30 @@
+import { clampToBytes } from "./clampToBytes.js";
+import { cleanTranscript } from "./transcript.js";
+const MAX_BLOCK_LINES = 8;
+const MAX_EXCERPT_BYTES = 2_048;
+const NON_RULE_CHARACTER = /[^-=_~*+.|:#]/u;
+export function deriveExcerpt(transcript) {
+    const lines = cleanTranscript(transcript).split('\n');
+    let end = lines.length;
+    while (end > 0 && isBlank(lines[end - 1])) {
+        end--;
+    }
+    let start = end;
+    while (start > 0 && !isBlank(lines[start - 1])) {
+        start--;
+    }
+    const excerpt = lines
+        .slice(Math.max(start, end - MAX_BLOCK_LINES), end)
+        .filter((line) => !isRuleOnly(line))
+        .join(' ')
+        .replaceAll(/\s+/gu, ' ')
+        .trim();
+    return excerpt === '' ? undefined : clampToBytes(excerpt, MAX_EXCERPT_BYTES);
+}
+function isBlank(line) {
+    return line === undefined || line.trim() === '';
+}
+function isRuleOnly(line) {
+    const content = line.replaceAll(/\s/gu, '');
+    return content !== '' && !NON_RULE_CHARACTER.test(content);
+}

package/dist/esm/helpers/duration.js

@@ -1,21 +1,28 @@
 export function formatDuration(milliseconds) {
-    const seconds = Math.round(milliseconds / MILLISECONDS_PER_SECOND);
-    if (seconds < SECONDS_PER_MINUTE) {
-        return `${seconds}s`;
+    const total = Math.max(0, milliseconds);
+    if (total < MILLISECONDS_PER_MINUTE) {
+        return `${truncateToTenth(total)}s`;
     }
-    const minutes = Math.round(seconds / SECONDS_PER_MINUTE);
-    if (minutes < MINUTES_PER_HOUR) {
-        return `${minutes}m`;
+    const totalMinutes = Math.floor(total / MILLISECONDS_PER_MINUTE);
+    if (totalMinutes < MINUTES_PER_HOUR) {
+        const seconds = Math.floor(total / MILLISECONDS_PER_SECOND) % SECONDS_PER_MINUTE;
+        return joinUnits(`${totalMinutes}m`, seconds, 's');
     }
-    return `${Math.round(minutes / MINUTES_PER_HOUR)}h`;
+    return joinUnits(`${Math.floor(totalMinutes / MINUTES_PER_HOUR)}h`, totalMinutes % MINUTES_PER_HOUR, 'm');
 }
 export function formatSaving(milliseconds) {
     if (!Number.isFinite(milliseconds) || milliseconds < MILLISECONDS_PER_SECOND) {
         return undefined;
     }
-    return `${SPEED_BOOST_ICON} saved ~${formatDuration(milliseconds)}`;
+    return `saved ~${formatDuration(milliseconds)}`;
 }
+const MILLISECONDS_PER_MINUTE = 60_000;
 const MILLISECONDS_PER_SECOND = 1_000;
 const MINUTES_PER_HOUR = 60;
 const SECONDS_PER_MINUTE = 60;
-const SPEED_BOOST_ICON = '🚀';
+function joinUnits(major, minor, minorUnit) {
+    return minor === 0 ? major : `${major} ${minor}${minorUnit}`;
+}
+function truncateToTenth(milliseconds) {
+    return Math.floor(milliseconds / 100) / 10;
+}

package/dist/esm/helpers/package-json.d.ts

@@ -1,12 +1,19 @@
-export interface PackageJson {
+export declare const DEPENDENCY_FIELDS: readonly ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"];
+export type DependencyField = (typeof DEPENDENCY_FIELDS)[number];
+export type PackageJson = {
     name?: string;
     private?: boolean;
     version?: string;
     packageManager?: string;
     scripts?: Record<string, string>;
     pnpm?: {
-        overrides?: Record<string, string>;
+        overrides?: Record<string, unknown>;
     };
-}
+} & {
+    [K in DependencyField]?: Record<string, string>;
+};
 export declare function readPackageJson(dir: string): PackageJson;
-export declare function getPnpmOverrides(pkg: PackageJson): Record<string, string> | undefined;
+export declare function getPnpmOverrides(pkg: PackageJson): Record<string, unknown> | undefined;
+export declare function parsePackageJson(raw: string, file: string): unknown;
+export declare function readScriptRecord(dir: string, scripts: Record<string, unknown>): Record<string, string>;
+export declare function resolvePackageJsonPath(dir: string): string;

package/dist/esm/helpers/package-json.js

@@ -1,10 +1,22 @@
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
+import { describeError } from '@williamthorsen/toolbelt.errors';
+import { CONFIG_RELATIVE_PATH } from "../config.js";
+import { UserError } from "../UserError.js";
+import { isMonorepoRoot } from "../workspace.js";
+import { readStringValues } from "./readStringValues.js";
 import { isObject } from "./type-guards.js";
+export const DEPENDENCY_FIELDS = [
+    'dependencies',
+    'devDependencies',
+    'optionalDependencies',
+    'peerDependencies',
+];
 export function readPackageJson(dir) {
-    const parsed = JSON.parse(readFileSync(path.join(dir, 'package.json'), 'utf8'));
+    const file = resolvePackageJsonPath(dir);
+    const parsed = parsePackageJson(readFileSync(file, 'utf8'), file);
     if (!isObject(parsed)) {
-        throw new TypeError(`Invalid package.json in ${dir}: expected an object`);
+        throw new UserError(`Invalid package.json in ${dir}: expected an object`);
     }
     const pkg = {};
     if (typeof parsed['name'] === 'string')
@@ -16,24 +28,18 @@ export function readPackageJson(dir) {
     if (typeof parsed['packageManager'] === 'string')
         pkg.packageManager = parsed['packageManager'];
     if (isObject(parsed['scripts'])) {
-        const scripts = {};
-        const scriptEntries = Object.entries(parsed['scripts']);
-        for (const [key, val] of scriptEntries) {
-            if (typeof val === 'string')
-                scripts[key] = val;
-        }
-        pkg.scripts = scripts;
+        pkg.scripts = readScriptRecord(dir, parsed['scripts']);
     }
     if (isObject(parsed['pnpm'])) {
         const pnpm = parsed['pnpm'];
         if (isObject(pnpm['overrides'])) {
-            const overrides = {};
-            const overrideEntries = Object.entries(pnpm['overrides']);
-            for (const [key, val] of overrideEntries) {
-                if (typeof val === 'string')
-                    overrides[key] = val;
-            }
-            pkg.pnpm = { overrides };
+            pkg.pnpm = { overrides: pnpm['overrides'] };
+        }
+    }
+    for (const field of DEPENDENCY_FIELDS) {
+        const declared = parsed[field];
+        if (isObject(declared)) {
+            pkg[field] = readStringValues(declared);
         }
     }
     return pkg;
@@ -42,11 +48,34 @@ export function getPnpmOverrides(pkg) {
     if (!isObject(pkg.pnpm))
         return undefined;
     const overrides = pkg.pnpm.overrides;
-    if (!isObject(overrides))
-        return undefined;
-    for (const value of Object.values(overrides)) {
-        if (typeof value !== 'string')
-            return undefined;
+    return isObject(overrides) ? overrides : undefined;
+}
+export function parsePackageJson(raw, file) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new UserError(`Invalid package.json at ${file}: ${describeError(error)}`);
+    }
+}
+export function readScriptRecord(dir, scripts) {
+    const result = {};
+    for (const [key, value] of Object.entries(scripts)) {
+        if (typeof value !== 'string') {
+            throw new UserError(formatMalformedScript(dir, key, value));
+        }
+        result[key] = value;
+    }
+    return result;
+}
+export function resolvePackageJsonPath(dir) {
+    return path.join(dir, 'package.json');
+}
+function formatMalformedScript(dir, key, value) {
+    const rejection = `Invalid package.json at ${resolvePackageJsonPath(dir)}: \`scripts.${key}\` must be a string.`;
+    if (!Array.isArray(value)) {
+        return rejection;
     }
-    return overrides;
+    const field = isMonorepoRoot(dir) ? 'rootScripts' : 'workspaceScripts';
+    return `${rejection} A step list belongs in \`${CONFIG_RELATIVE_PATH}\` under \`${field}\`.`;
 }

package/dist/esm/helpers/readStringValues.d.ts

@@ -0,0 +1 @@
+export declare function readStringValues(record: Record<string, unknown>): Record<string, string>;