@williamthorsen/nmr 0.29.0 → 0.31.0

package/dist/esm/recording.d.ts

@@ -0,0 +1,65 @@
+import type { CheckCacheEntry } from './check-cache.js';
+export interface RunIdentity {
+    commandString: string;
+    nmrVersion: string;
+    nodeVersion: string;
+    treeHash: string | undefined;
+}
+export interface Recording {
+    entry: CheckCacheEntry;
+    transcript?: string;
+}
+export type KeyDifference = {
+    ingredient: 'tree';
+} | {
+    ingredient: 'command-string';
+} | {
+    ingredient: 'nmr-version';
+    current: string;
+    recorded: string;
+} | {
+    ingredient: 'node-version';
+    current: string;
+    recorded: string;
+} | {
+    ingredient: 'other';
+};
+export type RecordingLookup = {
+    ok: true;
+    recording: Recording;
+} | {
+    ok: false;
+    refusal: RecordingRefusal;
+};
+export type RecordingRefusal = {
+    kind: 'uncacheable';
+} | {
+    kind: 'gate-aside';
+} | {
+    kind: 'unrecorded';
+} | {
+    kind: 'mismatched';
+    ageMs: number;
+    difference: KeyDifference;
+} | {
+    kind: 'no-output';
+    ageMs: number;
+};
+export declare function renderRecording(options: {
+    command: string;
+    recording: Recording;
+    scope: string;
+}): string;
+export declare function renderRefusal(options: {
+    command: string;
+    refusal: RecordingRefusal;
+    scope: string;
+}): string;
+export declare function resolveRecording(options: {
+    anchorDir: string;
+    command: string;
+    current: RunIdentity;
+    isCacheable: boolean;
+    key: string | undefined;
+    monorepoRoot: string;
+}): Promise<RecordingLookup>;

package/dist/esm/recording.js

@@ -0,0 +1,96 @@
+import { readCheckCacheEntry, readTranscript } from "./check-cache.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`;
+    return `${header}${appendNewline(renderBody(options.recording))}`;
+}
+export function renderRefusal(options) {
+    return `📭 ${options.scope}: ${options.command}: no recording; ${describeRefusal(options.command, options.refusal)}`;
+}
+export async function resolveRecording(options) {
+    const { anchorDir, command, monorepoRoot } = options;
+    if (!options.isCacheable) {
+        return { ok: false, refusal: { kind: 'uncacheable' } };
+    }
+    if (options.key === undefined) {
+        return { ok: false, refusal: { kind: 'gate-aside' } };
+    }
+    const entry = await readCheckCacheEntry({ anchorDir, command, monorepoRoot });
+    if (entry === undefined) {
+        return { ok: false, refusal: { kind: 'unrecorded' } };
+    }
+    const ageMs = Math.max(0, Date.now() - Date.parse(entry.recordedAt));
+    if (entry.key !== options.key) {
+        return { ok: false, refusal: { kind: 'mismatched', ageMs, difference: findKeyDifference(entry, options.current) } };
+    }
+    const transcript = await readTranscript({ anchorDir, command, monorepoRoot });
+    if (transcript === undefined && (entry.retention?.replay.length ?? 0) === 0) {
+        return { ok: false, refusal: { kind: 'no-output', ageMs } };
+    }
+    return { ok: true, recording: { entry, ...(transcript !== undefined && { transcript }) } };
+}
+function appendNewline(body) {
+    return body.endsWith('\n') ? body : `${body}\n`;
+}
+function describeDifference(difference) {
+    switch (difference.ingredient) {
+        case 'tree':
+            return 'on a tree this is not';
+        case 'command-string':
+            return 'over a command chain this is not';
+        case 'nmr-version':
+            return `under nmr ${difference.recorded}, not ${difference.current}`;
+        case 'node-version':
+            return `under Node ${difference.recorded}, not ${difference.current}`;
+        case 'other':
+            return 'under an install or environment this run does not share';
+        default: {
+            const unhandled = difference;
+            throw new Error(`Unhandled key difference: ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+function describeRefusal(command, refusal) {
+    switch (refusal.kind) {
+        case 'uncacheable':
+            return `\`${command}\` is outside the check-result cache, so no run of it is recorded`;
+        case 'gate-aside':
+            return 'the check-result cache is standing aside here (NMR_DEBUG=1 reports why)';
+        case 'unrecorded':
+            return 'nothing has recorded a pass for this scope';
+        case 'mismatched':
+            return `the last pass was ${formatDuration(refusal.ageMs)} ago, ${describeDifference(refusal.difference)}`;
+        case 'no-output':
+            return `the pass ${formatDuration(refusal.ageMs)} ago retained none, as a run printing nothing or writing to a terminal does`;
+        default: {
+            const unhandled = refusal;
+            throw new Error(`Unhandled refusal: ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+function findKeyDifference(entry, current) {
+    if (current.treeHash !== undefined && entry.treeHash !== current.treeHash) {
+        return { ingredient: 'tree' };
+    }
+    if (entry.commandString !== current.commandString) {
+        return { ingredient: 'command-string' };
+    }
+    if (entry.nmrVersion !== current.nmrVersion) {
+        return { ingredient: 'nmr-version', current: current.nmrVersion, recorded: entry.nmrVersion };
+    }
+    if (entry.nodeVersion !== current.nodeVersion) {
+        return { ingredient: 'node-version', current: current.nodeVersion, recorded: entry.nodeVersion };
+    }
+    return { ingredient: 'other' };
+}
+function renderBody(recording) {
+    if (recording.transcript !== undefined) {
+        return recording.transcript;
+    }
+    return (recording.entry.retention?.replay ?? [])
+        .map((line) => `${line.scope}: ${line.command}: ${line.excerpt}`)
+        .join('\n');
+}

package/dist/esm/replay-assembly.d.ts

@@ -0,0 +1,9 @@
+import type { ReplayLine } from './check-cache.js';
+import type { Step } from './steps.js';
+export declare function assembleReplay(options: {
+    anchorDir: string;
+    monorepoRoot: string;
+    runId: string;
+    steps: readonly Step[];
+    treeHash: string;
+}): Promise<ReplayLine[]>;

package/dist/esm/replay-assembly.js

@@ -0,0 +1,26 @@
+import { readCheckCacheEntry } from "./check-cache.js";
+import { readNmrStep } from "./steps.js";
+import { getWorkspacePackageDirs } from "./workspace.js";
+export async function assembleReplay(options) {
+    const { anchorDir, monorepoRoot, runId, steps, treeHash } = options;
+    const candidates = steps.flatMap((step) => {
+        const target = readNmrStep(step);
+        if (target === undefined) {
+            return [];
+        }
+        const scopeDirs = target.isDelegate
+            ? resolveDelegateScopes(monorepoRoot)
+            : [target.isWorkspaceRoot ? monorepoRoot : anchorDir];
+        return scopeDirs.map((scopeDir) => ({ anchorDir: scopeDir, command: target.command, monorepoRoot }));
+    });
+    const entries = await Promise.all(candidates.map((candidate) => readCheckCacheEntry(candidate)));
+    return entries.flatMap((entry) => entry?.treeHash === treeHash && entry.retention?.runId === runId ? entry.retention.replay : []);
+}
+function resolveDelegateScopes(monorepoRoot) {
+    try {
+        return getWorkspacePackageDirs(monorepoRoot);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/esm/report-format.d.ts

@@ -0,0 +1,18 @@
+export declare function formatReportFormatRejection(source: string, value: string): string;
+export declare function isReportFormat(value: string): value is ReportFormat;
+export declare function readReportFormatEnv(env: NodeJS.ProcessEnv): ReportFormatRead;
+export declare const REPORT_FORMAT_ENV_VAR = "NMR_REPORT_FORMAT";
+export declare const REPORT_FORMATS: readonly ["text", "json"];
+export type ReportFormat = (typeof REPORT_FORMATS)[number];
+export type ReportFormatRead = {
+    ok: true;
+    format?: ReportFormat;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function resolveReportFormat(options: ResolveReportFormatOptions): ReportFormat;
+export interface ResolveReportFormatOptions {
+    envFormat: ReportFormat | undefined;
+    jsonFlag: boolean;
+}

package/dist/esm/report-format.js

@@ -0,0 +1,25 @@
+export function formatReportFormatRejection(source, value) {
+    return `${source} is \`${value}\`, which is not one of: ${REPORT_FORMATS.join(', ')}`;
+}
+export function isReportFormat(value) {
+    const names = REPORT_FORMATS;
+    return names.includes(value);
+}
+export function readReportFormatEnv(env) {
+    const raw = env[REPORT_FORMAT_ENV_VAR];
+    if (raw === undefined || raw === '') {
+        return { ok: true };
+    }
+    if (!isReportFormat(raw)) {
+        return { ok: false, error: formatReportFormatRejection(REPORT_FORMAT_ENV_VAR, raw) };
+    }
+    return { ok: true, format: raw };
+}
+export const REPORT_FORMAT_ENV_VAR = 'NMR_REPORT_FORMAT';
+export const REPORT_FORMATS = ['text', 'json'];
+export function resolveReportFormat(options) {
+    const { envFormat, jsonFlag } = options;
+    if (jsonFlag)
+        return 'json';
+    return envFormat ?? 'text';
+}

package/dist/esm/reportCliFailure.d.ts

@@ -0,0 +1,2 @@
+import type { Writable } from 'node:stream';
+export declare function reportCliFailure(error: unknown, stderr: Writable): void;

package/dist/esm/reportCliFailure.js

@@ -0,0 +1,11 @@
+import { reportError } from '@williamthorsen/nmr-core';
+import { describeError } from '@williamthorsen/toolbelt.errors';
+import { UserError } from "./UserError.js";
+export function reportCliFailure(error, stderr) {
+    if (error instanceof UserError) {
+        reportError(error.message, stderr);
+        return;
+    }
+    const detail = error instanceof Error && error.stack !== undefined ? error.stack : describeError(error);
+    stderr.write(`${detail}\n`);
+}

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

@@ -1,4 +1,4 @@
 import type { ScriptRegistry } from './default-scripts.js';
-export type { ScriptRegistry, ScriptValue } from './default-scripts.js';
+export type { ScriptRegistry, ScriptValue, StepSpec } from './default-scripts.js';
 export declare function getDefaultWorkspaceScripts(): ScriptRegistry;
 export declare function getDefaultRootScripts(): ScriptRegistry;

package/dist/esm/resolver.d.ts

@@ -1,11 +1,21 @@
 import type { ScriptRegistry, ScriptValue } from './resolve-scripts.js';
+import type { Step } from './steps.js';
 import type { NmrConfig } from './types.js';
 export declare function applyDevBin(command: string, devBin: Record<string, string> | undefined, monorepoRoot: string): string;
+export declare function applyDevBinToSteps(steps: readonly Step[], devBin: Record<string, string> | undefined, monorepoRoot: string): readonly Step[];
+export type ScriptOrigin = {
+    tier: 'registry';
+    key: string;
+} | {
+    tier: 'package';
+    file: string;
+    key: string;
+};
 export interface ResolvedScript {
-    command: string;
-    source: 'default' | 'package';
+    origin: ScriptOrigin;
+    steps: readonly Step[];
 }
-export declare function expandScript(script: ScriptValue, workspaceRoot: boolean): string;
+export declare function expandScript(script: ScriptValue, workspaceRoot: boolean): readonly Step[];
 export declare function describeScript(script: ScriptValue): string;
 export declare function readPackageJsonScripts(packageDir: string): Record<string, string> | undefined;
 export declare function buildWorkspaceRegistry(config: NmrConfig): ScriptRegistry;

package/dist/esm/resolver.js

@@ -1,7 +1,9 @@
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
+import { parsePackageJson, readScriptRecord, resolvePackageJsonPath } from "./helpers/package-json.js";
 import { isObject } from "./helpers/type-guards.js";
 import { getDefaultRootScripts, getDefaultWorkspaceScripts } from "./resolve-scripts.js";
+import { composeNmrStep } from "./steps.js";
 export function applyDevBin(command, devBin, monorepoRoot) {
     if (!devBin) {
         return command;
@@ -16,6 +18,12 @@ export function applyDevBin(command, devBin, monorepoRoot) {
     const resolvedReplacement = resolveReplacementPaths(replacement, monorepoRoot);
     return resolvedReplacement + rest;
 }
+export function applyDevBinToSteps(steps, devBin, monorepoRoot) {
+    if (!devBin) {
+        return steps;
+    }
+    return steps.map((step) => step.kind === 'opaque' ? { kind: 'opaque', command: applyDevBin(step.command, devBin, monorepoRoot) } : step);
+}
 function resolveReplacementPaths(replacement, monorepoRoot) {
     const tokens = replacement.split(' ');
     return tokens
@@ -32,29 +40,26 @@ function resolveReplacementPaths(replacement, monorepoRoot) {
 }
 export function expandScript(script, workspaceRoot) {
     if (typeof script === 'string') {
-        return script;
+        return [{ kind: 'opaque', command: script }];
     }
-    const flag = workspaceRoot ? '-w ' : '';
-    return script.map((s) => `nmr ${flag}${s}`).join(' && ');
+    return script.map((element) => typeof element === 'string'
+        ? composeNmrStep(element, workspaceRoot)
+        : composeNmrStep(element.run, workspaceRoot, element.declinesArgs));
 }
 export function describeScript(script) {
-    return typeof script === 'string' ? script : `[${script.join(', ')}]`;
+    return typeof script === 'string' ? script : `[${script.map(describeElement).join(', ')}]`;
+}
+function describeElement(element) {
+    if (typeof element === 'string') {
+        return element;
+    }
+    return element.declinesArgs === true ? `${element.run} (no args)` : element.run;
 }
 export function readPackageJsonScripts(packageDir) {
+    const file = resolvePackageJsonPath(packageDir);
+    let raw;
     try {
-        const raw = readFileSync(path.join(packageDir, 'package.json'), 'utf8');
-        const parsed = JSON.parse(raw);
-        if (!isObject(parsed))
-            return undefined;
-        const scripts = parsed['scripts'];
-        if (!isObject(scripts))
-            return undefined;
-        const result = {};
-        for (const [key, val] of Object.entries(scripts)) {
-            if (typeof val === 'string')
-                result[key] = val;
-        }
-        return result;
+        raw = readFileSync(file, 'utf8');
     }
     catch (error) {
         if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
@@ -62,6 +67,13 @@ export function readPackageJsonScripts(packageDir) {
         }
         throw error;
     }
+    const parsed = parsePackageJson(raw, file);
+    if (!isObject(parsed))
+        return undefined;
+    const scripts = parsed['scripts'];
+    if (!isObject(scripts))
+        return undefined;
+    return readScriptRecord(packageDir, scripts);
 }
 export function buildWorkspaceRegistry(config) {
     return {
@@ -85,7 +97,10 @@ export function resolveScript(commandName, registry, packageDir, workspaceRoot)
         if (pkgScripts && Object.hasOwn(pkgScripts, commandName)) {
             const override = pkgScripts[commandName];
             if (override !== undefined && !isSelfReferential(override, commandName)) {
-                return { command: override, source: 'package' };
+                return {
+                    origin: { tier: 'package', file: resolvePackageJsonPath(packageDir), key: commandName },
+                    steps: [{ kind: 'opaque', command: override }],
+                };
             }
         }
     }
@@ -96,5 +111,5 @@ export function resolveScript(commandName, registry, packageDir, workspaceRoot)
     if (registryEntry === undefined) {
         return undefined;
     }
-    return { command: expandScript(registryEntry, workspaceRoot), source: 'default' };
+    return { origin: { tier: 'registry', key: commandName }, steps: expandScript(registryEntry, workspaceRoot) };
 }

package/dist/esm/runCli.d.ts

@@ -1,4 +1,5 @@
 import type { Writable } from 'node:stream';
+export declare const RUN_IF_PRESENT_ENV_VAR = "NMR_RUN_IF_PRESENT";
 export interface RunCliOptions {
     args: string[];
     cwd: string;