@williamthorsen/nmr 0.30.0 → 0.32.0

package/dist/esm/helpers/readStringValues.js

@@ -0,0 +1,8 @@
+export function readStringValues(record) {
+    const result = {};
+    for (const [key, value] of Object.entries(record)) {
+        if (typeof value === 'string')
+            result[key] = value;
+    }
+    return result;
+}

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

@@ -0,0 +1 @@
+export declare function reportClosing(message: string, log?: (line: string) => void): void;

package/dist/esm/helpers/reportClosing.js

@@ -0,0 +1,3 @@
+export function reportClosing(message, log = console.info) {
+    log(`\n${message}`);
+}

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

@@ -0,0 +1,5 @@
+import type { RetainedOutput } from '../runner.js';
+export declare const TRANSCRIPT_LIMIT_BYTES = 262144;
+export declare function cleanTranscript(raw: string): string;
+export declare function composeTranscript(retained: RetainedOutput): string | undefined;
+export declare function formatElisionMarker(byteCount: number): string;

package/dist/esm/helpers/transcript.js

@@ -0,0 +1,59 @@
+export const TRANSCRIPT_LIMIT_BYTES = 262_144;
+const ANSI_PATTERN = /\u{1B}(?:\[[\u{30}-\u{3F}]*[\u{20}-\u{2F}]*[\u{40}-\u{7E}]|\][^\u{7}\u{1B}]*(?:\u{7}|\u{1B}\\))/gu;
+const END_LIMIT_BYTES = TRANSCRIPT_LIMIT_BYTES / 2;
+const STREAM_MARKER = '\n… nmr: stderr …\n';
+export function cleanTranscript(raw) {
+    return raw
+        .replaceAll(ANSI_PATTERN, '')
+        .split('\n')
+        .map((line) => renderCarriageReturns(line))
+        .join('\n');
+}
+export function composeTranscript(retained) {
+    const streams = [retained.stdout, retained.stderr]
+        .map((stream) => cleanTranscript(stream.toString('utf8')))
+        .filter((stream) => stream.trim() !== '');
+    if (streams.length === 0) {
+        return undefined;
+    }
+    return clampTranscript(streams.join(STREAM_MARKER));
+}
+export function formatElisionMarker(byteCount) {
+    const unit = byteCount === 1 ? 'byte' : 'bytes';
+    return `\n… nmr elided ${byteCount.toLocaleString('en-US')} ${unit} …\n`;
+}
+function alignEnd(buffer, end) {
+    let aligned = Math.min(buffer.length, end);
+    while (aligned > 0 && isContinuationByte(buffer[aligned])) {
+        aligned--;
+    }
+    return aligned;
+}
+function alignStart(buffer, start) {
+    let aligned = Math.max(0, start);
+    while (aligned < buffer.length && isContinuationByte(buffer[aligned])) {
+        aligned++;
+    }
+    return aligned;
+}
+function clampTranscript(transcript) {
+    const buffer = Buffer.from(transcript, 'utf8');
+    if (buffer.length <= TRANSCRIPT_LIMIT_BYTES) {
+        return transcript;
+    }
+    const headEnd = alignEnd(buffer, END_LIMIT_BYTES);
+    const tailStart = alignStart(buffer, buffer.length - END_LIMIT_BYTES);
+    const head = buffer.subarray(0, headEnd).toString('utf8');
+    const tail = buffer.subarray(tailStart).toString('utf8');
+    return `${head}${formatElisionMarker(tailStart - headEnd)}${tail}`;
+}
+function isContinuationByte(byte) {
+    return byte !== undefined && (byte & 0b1100_0000) === 0b1000_0000;
+}
+function renderCarriageReturns(line) {
+    if (!line.includes('\r')) {
+        return line;
+    }
+    const segments = line.split('\r').filter((segment) => segment.trim() !== '');
+    return segments.at(-1) ?? '';
+}

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, isError } 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 = isError(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

@@ -3,8 +3,16 @@ 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 {
-    source: 'default' | 'package';
+    origin: ScriptOrigin;
     steps: readonly Step[];
 }
 export declare function expandScript(script: ScriptValue, workspaceRoot: boolean): readonly Step[];

package/dist/esm/resolver.js

@@ -1,5 +1,7 @@
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
+import { hasErrnoCode } from '@williamthorsen/nmr-core';
+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";
@@ -41,33 +43,38 @@ export function expandScript(script, workspaceRoot) {
     if (typeof script === 'string') {
         return [{ kind: 'opaque', command: script }];
     }
-    return script.map((element) => composeNmrStep(element, workspaceRoot));
+    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') {
+        if (hasErrnoCode(error, 'ENOENT')) {
             return undefined;
         }
         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 {
@@ -91,7 +98,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 { source: 'package', steps: [{ kind: 'opaque', command: override }] };
+                return {
+                    origin: { tier: 'package', file: resolvePackageJsonPath(packageDir), key: commandName },
+                    steps: [{ kind: 'opaque', command: override }],
+                };
             }
         }
     }
@@ -102,5 +112,5 @@ export function resolveScript(commandName, registry, packageDir, workspaceRoot)
     if (registryEntry === undefined) {
         return undefined;
     }
-    return { source: 'default', steps: expandScript(registryEntry, workspaceRoot) };
+    return { origin: { tier: 'registry', key: commandName }, steps: expandScript(registryEntry, workspaceRoot) };
 }