@williamthorsen/nmr 0.29.0 → 0.31.0

package/bin/nmr-report-catalog.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+try {
+  await import('../dist/esm/cli-report-catalog.js');
+} catch (error) {
+  if (error.code === 'ERR_MODULE_NOT_FOUND') {
+    process.stderr.write('nmr-report-catalog: build output not found — run `pnpm run bootstrap` first\n');
+  } else {
+    process.stderr.write(`nmr-report-catalog: failed to load: ${error.message}\n`);
+  }
+  process.exit(1);
+}

package/dist/esm/UserError.d.ts

@@ -0,0 +1,3 @@
+export declare class UserError extends Error {
+    constructor(message: string);
+}

package/dist/esm/UserError.js

@@ -0,0 +1,6 @@
+export class UserError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UserError';
+    }
+}

package/dist/esm/check-cache.d.ts

@@ -1,4 +1,5 @@
 import type { Writable } from 'node:stream';
+import type { OutputChannels } from './runner.js';
 import type { CheckCacheConfig, NmrConfig } from './types.js';
 export interface CheckCacheEntry {
     key: string;
@@ -10,6 +11,22 @@ export interface CheckCacheEntry {
     durationMs: number;
     recordedAt: string;
     buildDigests: Record<string, string>;
+    retention?: Retention;
+}
+export interface EntryRef {
+    anchorDir: string;
+    command: string;
+    monorepoRoot: string;
+}
+export interface ReplayLine {
+    command: string;
+    excerpt: string;
+    scope: string;
+}
+export interface Retention {
+    key: string;
+    replay: ReplayLine[];
+    runId: string;
 }
 export interface BuildOutputState {
     missing: string[];
@@ -28,7 +45,17 @@ export declare const CURRENT_RUNTIME: RuntimeIdentity;
 export declare const DEBUG_ENV_VAR = "NMR_DEBUG";
 export declare const DEFAULT_CACHEABLE_COMMANDS: string[];
 export declare const NO_CACHE_ENV_VAR = "NMR_NO_CACHE";
+export declare const RUN_ID_ENV_VAR = "NMR_RUN_ID";
 export declare const TREE_SNAPSHOT_ENV_VAR = "NMR_TREE_SNAPSHOT";
+export declare function certifyRetention(options: {
+    anchorDir: string;
+    command: string;
+    entry: CheckCacheEntry;
+    env: NodeJS.ProcessEnv;
+    monorepoRoot: string;
+    runId: string;
+    stderr: Writable;
+}): Promise<void>;
 export declare function computeCacheKey(options: {
     anchorDir: string;
     command: string;
@@ -45,18 +72,26 @@ export declare function computeCacheKey(options: {
     ok: false;
     reason: string;
 };
+export declare function computeRetentionKey(options: {
+    channels: OutputChannels;
+    env: NodeJS.ProcessEnv;
+    passKey: string;
+}): string;
 export declare function encodeTreeSnapshot(snapshot: TreeSnapshot): string;
 export declare function findStaleBuildOutput(earlier: Record<string, string>, later: Record<string, string>): string | undefined;
 export declare function formatMisplacedNoCacheWarning(command: string): string;
-export declare function formatSkipLine(command: string, entry: CheckCacheEntry, now: number): string;
+export declare function isCacheableCommand(checkCache: CheckCacheConfig | undefined, command: string): boolean;
 export declare function readBuildOutputState(monorepoRoot: string, config: NmrConfig): Promise<BuildOutputState>;
 export declare function readCheckCacheEntry(options: {
     anchorDir: string;
     command: string;
     monorepoRoot: string;
 }): Promise<CheckCacheEntry | undefined>;
+export declare function readTranscript(ref: EntryRef): Promise<string | undefined>;
+export declare function recordTranscript(ref: EntryRef, transcript: string | undefined): Promise<void>;
 export declare function removeCheckCache(scopeDir: string): Promise<void>;
 export declare function resolveCacheableCommands(checkCache: CheckCacheConfig | undefined): Set<string>;
+export declare function resolveRunId(env: NodeJS.ProcessEnv): string;
 export declare function resolveTreeSnapshot(options: {
     monorepoRoot: string;
     env: NodeJS.ProcessEnv;

package/dist/esm/check-cache.js

@@ -1,14 +1,16 @@
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { readFileSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
-import { hashWorkingTree, readHeadSha, readJsonCacheEntry, removeCacheDir, resolveCacheEntryPath, writeCacheEntry, } from '@williamthorsen/nmr-core';
+import { hashWorkingTree, readCacheEntry, readHeadSha, readJsonCacheEntry, removeCacheDir, removeCacheEntry, resolveCacheEntryPath, writeCacheEntry, } from '@williamthorsen/nmr-core';
+import { describeError } from '@williamthorsen/toolbelt.errors';
 import { hasBuildOutput, readBuildDigest } from "./commands/build-output.js";
 import { loadWorkspaceConfig } from "./config.js";
-import { formatDuration, formatSaving } from "./helpers/duration.js";
+import { isHookName } from "./helpers/hook-name.js";
 import { isObject, isStringRecord } from "./helpers/type-guards.js";
 import { getDefaultWorkspaceScripts } from "./resolve-scripts.js";
 import { buildWorkspaceRegistry, resolveScript } from "./resolver.js";
+import { renderChain } from "./steps.js";
 import { getWorkspacePackageDirs } from "./workspace.js";
 export const CURRENT_RUNTIME = {
     arch: process.arch,
@@ -38,6 +40,7 @@ export const DEFAULT_CACHEABLE_COMMANDS = [
     'typecheck',
 ];
 export const NO_CACHE_ENV_VAR = 'NMR_NO_CACHE';
+export const RUN_ID_ENV_VAR = 'NMR_RUN_ID';
 export const TREE_SNAPSHOT_ENV_VAR = 'NMR_TREE_SNAPSHOT';
 const BUILT_IN_COMPILE = 'nmr-compile';
 const CACHE_TOOL = 'nmr-check';
@@ -47,7 +50,26 @@ const INSTALL_FINGERPRINT_FILES = [
 ];
 const KEY_FORMAT = 'nmr-check-cache-v1';
 const KEYED_ENV_VARS = ['LANG', 'LC_ALL', 'NODE_OPTIONS', 'TZ'];
+const RETENTION_KEY_FORMAT = 'nmr-retention-v1';
+const RETENTION_KEYED_ENV_VARS = ['CI', 'COLUMNS', 'FORCE_COLOR', 'NO_COLOR', 'TERM'];
 const UNSAFE_SLUG_CHARACTERS = /[^\w.-]+/g;
+export async function certifyRetention(options) {
+    const { entry, runId } = options;
+    if (entry.retention === undefined || entry.retention.runId === runId) {
+        return;
+    }
+    try {
+        await writeCheckCacheEntry({
+            anchorDir: options.anchorDir,
+            command: options.command,
+            monorepoRoot: options.monorepoRoot,
+            entry: { ...entry, retention: { ...entry.retention, runId } },
+        });
+    }
+    catch (error) {
+        writeDebugNote(`could not certify ${options.command}: ${describeError(error)}`, options.env, options.stderr);
+    }
+}
 export function computeCacheKey(options) {
     const fingerprint = resolveInstallFingerprint(options.monorepoRoot);
     if (!fingerprint.ok) {
@@ -67,16 +89,16 @@ export function computeCacheKey(options) {
         runtime.arch,
         fingerprint.fingerprint,
     ];
-    for (const name of KEYED_ENV_VARS) {
-        const value = options.env[name];
-        parts.push(name, value === undefined ? 'unset' : 'set', value ?? '');
-    }
-    const hash = createHash('sha256');
-    for (const part of parts) {
-        hash.update(part);
-        hash.update('\0');
-    }
-    return { ok: true, key: hash.digest('hex') };
+    return { ok: true, key: digestParts([...parts, ...composeEnvParts(KEYED_ENV_VARS, options.env)]) };
+}
+export function computeRetentionKey(options) {
+    const parts = [
+        RETENTION_KEY_FORMAT,
+        options.passKey,
+        describeChannel(options.channels.stdout),
+        describeChannel(options.channels.stderr),
+    ];
+    return digestParts([...parts, ...composeEnvParts(RETENTION_KEYED_ENV_VARS, options.env)]);
 }
 export function encodeTreeSnapshot(snapshot) {
     return `${snapshot.hash} ${snapshot.headSha}`;
@@ -89,11 +111,8 @@ export function formatMisplacedNoCacheWarning(command) {
     return (`⚠️ --no-cache after the command name is passed to \`${command}\`, not read by nmr. ` +
         `Did you mean \`nmr --no-cache ${command}\`?`);
 }
-export function formatSkipLine(command, entry, now) {
-    const age = formatDuration(Math.max(0, now - Date.parse(entry.recordedAt)));
-    const saving = formatSaving(entry.durationMs);
-    const savingClause = saving === undefined ? '' : ` (${saving})`;
-    return `⏭️ ${command}: passed ${age} ago on this tree${savingClause}.`;
+export function isCacheableCommand(checkCache, command) {
+    return !isHookName(command) && checkCache?.enabled !== false && resolveCacheableCommands(checkCache).has(command);
 }
 export async function readBuildOutputState(monorepoRoot, config) {
     const state = { missing: [], digests: {} };
@@ -125,7 +144,23 @@ export async function readBuildOutputState(monorepoRoot, config) {
     return state;
 }
 export async function readCheckCacheEntry(options) {
-    return readJsonCacheEntry(resolveEntryPath(options), isCheckCacheEntry);
+    const parsed = await readJsonCacheEntry(resolveEntryPath(options), isParsedCheckCacheEntry);
+    if (parsed === undefined) {
+        return undefined;
+    }
+    const { retention, ...pass } = parsed;
+    return isRetention(retention) ? { ...pass, retention } : pass;
+}
+export async function readTranscript(ref) {
+    return readCacheEntry(resolveEntryPath(ref, '.log'));
+}
+export async function recordTranscript(ref, transcript) {
+    const entryPath = resolveEntryPath(ref, '.log');
+    if (transcript === undefined) {
+        await removeCacheEntry(entryPath);
+        return;
+    }
+    await writeCacheEntry(entryPath, transcript);
 }
 export async function removeCheckCache(scopeDir) {
     await removeCacheDir({ tool: CACHE_TOOL, scopeDir });
@@ -138,6 +173,10 @@ export function resolveCacheableCommands(checkCache) {
     }
     return commands;
 }
+export function resolveRunId(env) {
+    const inherited = env[RUN_ID_ENV_VAR];
+    return inherited === undefined || inherited === '' ? randomUUID() : inherited;
+}
 export function resolveTreeSnapshot(options) {
     const inherited = decodeTreeSnapshot(options.env[TREE_SNAPSHOT_ENV_VAR]);
     if (inherited !== undefined && readHeadSha(options.monorepoRoot) === inherited.headSha) {
@@ -167,6 +206,12 @@ export function writeDebugNote(message, env, stderr) {
         stderr.write(`nmr check-cache: ${message}\n`);
     }
 }
+function composeEnvParts(names, env) {
+    return names.flatMap((name) => {
+        const value = env[name];
+        return [name, value === undefined ? 'unset' : 'set', value ?? ''];
+    });
+}
 function decodeTreeSnapshot(encoded) {
     if (encoded === undefined) {
         return undefined;
@@ -177,7 +222,18 @@ function decodeTreeSnapshot(encoded) {
     }
     return { hash, headSha };
 }
-function isCheckCacheEntry(value) {
+function describeChannel(channel) {
+    return channel === 'pipe' ? 'pipe' : 'descriptor';
+}
+function digestParts(parts) {
+    const hash = createHash('sha256');
+    for (const part of parts) {
+        hash.update(part);
+        hash.update('\0');
+    }
+    return hash.digest('hex');
+}
+function isParsedCheckCacheEntry(value) {
     if (!isObject(value)) {
         return false;
     }
@@ -192,19 +248,32 @@ function isCheckCacheEntry(value) {
 }
 function isProbeSubject(packageDir, registry) {
     const build = resolveScript('build', registry, packageDir, false);
-    if (build === undefined || build.source === 'package') {
+    if (build === undefined || build.origin.tier === 'package') {
         return false;
     }
     const compile = resolveScript('compile', registry, packageDir, false);
-    return compile !== undefined && compile.command === BUILT_IN_COMPILE;
+    return compile !== undefined && renderChain(compile.steps) === BUILT_IN_COMPILE;
+}
+function isReplayLine(value) {
+    return (isObject(value) &&
+        typeof value['command'] === 'string' &&
+        typeof value['excerpt'] === 'string' &&
+        typeof value['scope'] === 'string');
+}
+function isRetention(value) {
+    return (isObject(value) &&
+        typeof value['key'] === 'string' &&
+        typeof value['runId'] === 'string' &&
+        Array.isArray(value['replay']) &&
+        value['replay'].every((line) => isReplayLine(line)));
 }
-function resolveEntryPath(options) {
+function resolveEntryPath(options, extension = '.json') {
     const anchorDir = path.resolve(options.anchorDir);
     const ref = {
         tool: CACHE_TOOL,
         scopeDir: options.monorepoRoot,
         slug: `${path.basename(anchorDir)}-${options.command.replaceAll(UNSAFE_SLUG_CHARACTERS, '-')}`,
-        extension: '.json',
+        extension,
         discriminators: [anchorDir, options.command],
     };
     return resolveCacheEntryPath(ref);

package/dist/esm/cli-build.js

@@ -1,4 +1,5 @@
 import { reportError } from '@williamthorsen/nmr-core';
+import { describeError } from '@williamthorsen/toolbelt.errors';
 import { buildPackage } from "./commands/build.js";
 import { loadWorkspaceConfig } from "./config.js";
 try {
@@ -9,6 +10,6 @@ try {
     });
 }
 catch (error) {
-    reportError(error instanceof Error ? error.message : String(error));
+    reportError(describeError(error));
     process.exitCode = 1;
 }

package/dist/esm/cli-clean.js

@@ -1,9 +1,10 @@
 import { reportError } from '@williamthorsen/nmr-core';
+import { describeError } from '@williamthorsen/toolbelt.errors';
 import { runClean } from "./commands/clean.js";
 try {
     await runClean(process.cwd());
 }
 catch (error) {
-    reportError(error instanceof Error ? error.message : String(error));
+    reportError(describeError(error));
     process.exitCode = 1;
 }

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

@@ -1,4 +1,5 @@
 import { parseArgsOrExit, reportError } from '@williamthorsen/nmr-core';
+import { describeError } from '@williamthorsen/toolbelt.errors';
 import { DEFAULT_HOOK, ensurePrepublishHooks } from "./commands/ensure-prepublish-hooks.js";
 import { findMonorepoRoot } from "./workspace.js";
 const flagSchema = {
@@ -38,6 +39,6 @@ try {
     }
 }
 catch (error) {
-    reportError(error instanceof Error ? error.message : String(error));
+    reportError(describeError(error));
     process.exitCode = 1;
 }

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,11 @@
+import process from 'node:process';
+import { reportError } from '@williamthorsen/nmr-core';
+import { describeError } from '@williamthorsen/toolbelt.errors';
+import { reportCatalog } from "./commands/report-catalog.js";
+try {
+    reportCatalog(process.cwd());
+}
+catch (error) {
+    reportError(describeError(error));
+    process.exitCode = 1;
+}

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

@@ -1,4 +1,5 @@
 import { reportError } from '@williamthorsen/nmr-core';
+import { describeError } from '@williamthorsen/toolbelt.errors';
 import { reportOverrides } from "./commands/report-overrides.js";
 import { findMonorepoRoot } from "./workspace.js";
 try {
@@ -6,6 +7,6 @@ try {
     reportOverrides(monorepoRoot);
 }
 catch (error) {
-    reportError(error instanceof Error ? error.message : String(error));
+    reportError(describeError(error));
     process.exitCode = 1;
 }

package/dist/esm/cli-taze.js

@@ -1,10 +1,11 @@
 import process from 'node:process';
 import { reportError } from '@williamthorsen/nmr-core';
+import { describeError } from '@williamthorsen/toolbelt.errors';
 import { runTaze } from "./commands/taze.js";
 try {
     process.exitCode = runTaze(process.argv.slice(2));
 }
 catch (error) {
-    reportError(error instanceof Error ? error.message : String(error));
+    reportError(describeError(error));
     process.exitCode = 1;
 }

package/dist/esm/cli.js

@@ -1,4 +1,5 @@
 import process from 'node:process';
+import { reportCliFailure } from "./reportCliFailure.js";
 import { runCli } from "./runCli.js";
 try {
     const { exitCode } = await runCli({
@@ -11,6 +12,6 @@ try {
     process.exitCode = exitCode;
 }
 catch (error) {
-    process.stderr.write(`${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);
+    reportCliFailure(error, process.stderr);
     process.exitCode = 1;
 }

package/dist/esm/commands/clean.js

@@ -4,7 +4,8 @@ import { removeCheckCache } from "../check-cache.js";
 import { loadRootConfig } from "../config.js";
 import { findContainingPackageDir } from "../context.js";
 import { applyDevBin, buildWorkspaceRegistry, resolveScript } from "../resolver.js";
-import { runCommand } from "../runner.js";
+import { resolveChannel, runCommand } from "../runner.js";
+import { renderChain } from "../steps.js";
 import { findMonorepoRoot, getWorkspacePackageDirs } from "../workspace.js";
 import { resolveBuildCachePath } from "./build-output.js";
 const CLEAN_ICON = '🧹';
@@ -44,15 +45,18 @@ async function sweepWorkspace(monorepoRoot, workspacePackageDirs) {
     const registry = buildWorkspaceRegistry(config);
     for (const packageDir of workspacePackageDirs) {
         const resolved = resolveScript(CLEAN_COMMAND, registry, packageDir, false);
-        if (resolved === undefined || resolved.command === '') {
+        const resolvedCommand = resolved === undefined ? undefined : renderChain(resolved.steps);
+        if (resolvedCommand === undefined || resolvedCommand === '') {
             continue;
         }
-        if (resolved.command === BUILT_IN_CLEAN) {
+        if (resolvedCommand === BUILT_IN_CLEAN) {
             await cleanPackage(packageDir);
             continue;
         }
-        const command = applyDevBin(resolved.command, config.devBin, monorepoRoot);
-        const { exitCode } = await runCommand(command, packageDir);
+        const command = applyDevBin(resolvedCommand, config.devBin, monorepoRoot);
+        const { exitCode } = await runCommand(command, packageDir, {
+            channels: { stderr: resolveChannel(process.stderr, false), stdout: resolveChannel(process.stdout, false) },
+        });
         if (exitCode !== 0) {
             throw new Error(`nmr-clean: \`${command}\` failed in ${path.basename(packageDir)} with exit code ${exitCode}.`);
         }

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

@@ -0,0 +1 @@
+export declare function reportCatalog(cwd: string): void;

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

@@ -0,0 +1,34 @@
+import { findContainingPackageDir } from "../context.js";
+import { DEPENDENCY_FIELDS, readPackageJson } from "../helpers/package-json.js";
+import { findMonorepoRoot, getWorkspacePackageDirs } from "../workspace.js";
+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;
+    }
+    const subject = dependencies.length === 1 ? '1 dependency comes' : `${dependencies.length} dependencies come`;
+    console.warn(`📚 WARN: ${subject} from a catalog, which a package-scoped upgrade does not read:`);
+    for (const { name, specifier } of dependencies) {
+        console.warn(`- ${name} → ${specifier}`);
+    }
+    console.warn(`Run \`nmr upgrade\` from ${monorepoRoot} to include them.`);
+}
+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,27 @@
 import { getPnpmOverrides, readPackageJson } from "../helpers/package-json.js";
+import { UserError } from "../UserError.js";
+import { readWorkspaceOverrides } from "../workspace.js";
 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('🔒 WARN: pnpm overrides are active! Check whether these are still needed:');
+        for (const [name, version] of declared) {
+            console.warn(`- ${name} → ${version}`);
+        }
     }
-    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 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>;