@williamthorsen/nmr 0.38.0 → 0.40.0

package/dist/esm/tests.js

@@ -1,25 +1,37 @@
 import { describe, expect, it } from 'vitest';
 import { findMisplacedTestFiles, findUntieredTestFiles, TIER_NAMES } from "./tiers.js";
 import { findMonorepoRoot } from "./workspace.js";
-const MISPLACED_REMEDY = 'Every test file must sit under a `__tests__` directory, the only place the shared Vitest config collects from. Move each file below into one, or name its directory in `exclude`.';
+const MISPLACED_REMEDY = 'Every test file must be under a `__tests__` directory, the only place from which the shared Vitest config collects. Move each file below into one, or name its directory in `excludedBasenames`.';
 const UNTIERED_REMEDY = `Every collected test file must name its isolation tier in the segment before \`.test.\`, one of: ${TIER_NAMES.join(', ')}. Rename each file below to <subject>[.<aspect>].<tier>.test.ts.`;
+const RETIRED_OPTION_KEYS = new Map([['exclude', 'excludedBasenames']]);
 export function checkTestFileConventions(options = {}) {
+    assertNoRetiredOptions(options);
     describe('test file conventions', () => {
-        const { misplaced, rootDir, untiered } = reportTestFileConventions(options);
+        const { misplacedFiles, rootDir, untieredFiles } = reportTestFileConventions(options);
         it('every collected test file names its tier', () => {
-            expect(untiered, `${UNTIERED_REMEDY} Swept from ${rootDir}.`).toStrictEqual([]);
+            expect(untieredFiles, `${UNTIERED_REMEDY} Swept from ${rootDir}.`).toStrictEqual([]);
         });
-        it('every test file sits under a __tests__ directory', () => {
-            expect(misplaced, `${MISPLACED_REMEDY} Swept from ${rootDir}.`).toStrictEqual([]);
+        it('every test file is under a __tests__ directory', () => {
+            expect(misplacedFiles, `${MISPLACED_REMEDY} Swept from ${rootDir}.`).toStrictEqual([]);
         });
     });
 }
-export function reportTestFileConventions({ exclude, rootDir, } = {}) {
+export function reportTestFileConventions(options = {}) {
+    assertNoRetiredOptions(options);
+    const { excludedBasenames, rootDir } = options;
     const sweptRoot = rootDir ?? findMonorepoRoot();
-    const scanOptions = { ...(exclude !== undefined && { exclude }) };
+    const scanOptions = { ...(excludedBasenames !== undefined && { excludedBasenames }) };
     return {
-        misplaced: findMisplacedTestFiles(sweptRoot, scanOptions),
+        misplacedFiles: findMisplacedTestFiles(sweptRoot, scanOptions),
         rootDir: sweptRoot,
-        untiered: findUntieredTestFiles(sweptRoot, scanOptions),
+        untieredFiles: findUntieredTestFiles(sweptRoot, scanOptions),
     };
 }
+function assertNoRetiredOptions(options) {
+    for (const key of Object.keys(options)) {
+        const replacement = RETIRED_OPTION_KEYS.get(key);
+        if (replacement !== undefined) {
+            throw new TypeError(`Invalid test-file-conventions options: \`${key}\` was renamed to \`${replacement}\`.`);
+        }
+    }
+}

package/dist/esm/tiers.d.ts

@@ -1,30 +1,30 @@
-/** Collection patterns for the residual project, which claims every test file the named tiers leave. */
+/** Collection patterns for the residual project, which claims every test file that the named tiers leave. */
 export declare const ALL_TEST_PATTERNS: string[];
 /** Builds the collection patterns for one tier. */
 export declare function buildTierPatterns(tier: string): string[];
 /**
- * Walks `rootDir` for every `*.test.ts` or `*.test.tsx` file sitting outside a `__tests__` directory, returning
- * paths relative to it, POSIX-separated and sorted.
+ * Walks `rootDir` for every `*.test.ts` or `*.test.tsx` file outside a `__tests__` directory, returning paths
+ * relative to it, POSIX-separated and sorted.
  *
- * No project collects such a file, so it runs nowhere and reports nothing. Only a sweep of the tree tells it apart
- * from a file that runs and passes.
+ * The shared config's projects do not collect such a file, so it runs nowhere and reports nothing. Only a sweep of
+ * the tree tells it apart from a file that runs and passes.
  */
 export declare function findMisplacedTestFiles(rootDir: string, options?: TestFileScanOptions): string[];
 /**
- * Walks `rootDir` for every test file the shared config's projects collect, returning paths relative to it,
+ * Walks `rootDir` for every test file that the shared config's projects collect, returning paths relative to it,
  * POSIX-separated and sorted.
  *
- * A walk, because `node:fs` `globSync` does not descend into a dot-directory and honours no option that would make
- * it. Vitest's globber does, so the same pattern string means different things to the two: a check built on the glob
- * would report clean over every test file under a dot-directory.
+ * A walk, because `node:fs` `globSync` does not descend into a dot-directory and does not honour any option that
+ * would make it. Vitest's globber does, so the same pattern string means different things to the two: A check built
+ * on the glob would report clean over every test file under a dot-directory.
  */
 export declare function findTestFiles(rootDir: string, options?: TestFileScanOptions): string[];
 /**
- * Walks `rootDir` for every collected test file whose name selects no tier, returning paths relative to it,
+ * Walks `rootDir` for every collected test file whose name does not select a tier, returning paths relative to it,
  * POSIX-separated and sorted.
  *
- * `unit` is the residual project, so such a file runs under it and reports success: no test run tells it apart from
- * a conformant file.
+ * Because `unit` is the residual project, such a file runs under it and reports success: A test run cannot tell it
+ * apart from a conformant file.
  */
 export declare function findUntieredTestFiles(rootDir: string, options?: TestFileScanOptions): string[];
 /**
@@ -35,27 +35,31 @@ export declare function findUntieredTestFiles(rootDir: string, options?: TestFil
  */
 export declare function hasTierInfix(filePath: string): boolean;
 /**
- * Directory names that hold no test worth collecting: dependencies, build output, and generated reports.
+ * Names of directories that do not contain any test worth collecting: dependencies, build output, and generated
+ * reports.
  *
- * The one point where the collection glob and the walk must agree about scope. Over-reporting is a failure a
- * consumer cannot fix; under-reporting is the silence a conformance check exists to end.
+ * These and the paths that git ignores are the scope on which the collection glob and the walk must agree.
+ * Over-reporting is a failure that a consumer cannot fix; under-reporting hides the violations that a conformance
+ * check exists to report.
  */
 export declare const TEST_COLLECTION_EXCLUDE: string[];
-/** Options every sweep over a repo's test files takes. */
+/** Options that every sweep over a repo's test files takes. */
 export interface TestFileScanOptions {
     /**
-     * Directory basenames pruned at any depth, additive to `TEST_COLLECTION_EXCLUDE`.
+     * Directory basenames pruned at any depth, additive to `TEST_COLLECTION_EXCLUDE` and to the paths that git
+     * ignores.
      *
-     * Basenames rather than globs, so the array a repo passes here is the array it passes to the shared Vitest
-     * config's `testCollectionExclude`. A directory pruned from the sweep but still collected by Vitest is the
-     * silence these sweeps exist to end.
+     * Basenames rather than globs, so that a repo can pass the same array here and to the shared Vitest config's
+     * `testCollectionExclude`. Vitest still runs the files in a directory pruned from the sweep alone, and the sweep
+     * does not report them.
      */
-    exclude?: readonly string[];
+    excludedBasenames?: readonly string[];
 }
 /**
- * The isolation ladder, ordered by the furthest thing a test reaches. A tier names what a test reaches, never how it
- * invokes it: a test driving a compiler through its JavaScript API is `tool`, exactly as one spawning `tsc` would be.
- * Each named tier's name is also its filename infix, so `parse.tool.test.ts` lands in `tool`.
+ * The isolation ladder, ordered by the furthest thing that a test reaches. A tier names what a test reaches, never
+ * how it invokes it: A test driving a compiler through its JavaScript API is `tool`, exactly as one spawning `tsc`
+ * would be. Each named tier's name is also its filename infix, so `parse.tool.test.ts` is collected by the `tool`
+ * project.
  */
 export declare const TIER_NAMES: readonly ["unit", "tool", "localhost", "remote"];
 /** One of the four isolation tiers. */

package/dist/esm/tiers.js

@@ -1,5 +1,6 @@
 import { readdirSync } from 'node:fs';
 import path from 'node:path';
+import { listGitIgnoredPaths } from "./git-ignored-paths.js";
 const TEST_DIR = '__tests__';
 const TEST_EXTENSIONS = '{ts,tsx}';
 const TEST_GLOB_PREFIX = `**/${TEST_DIR}/**`;
@@ -23,26 +24,29 @@ export function hasTierInfix(filePath) {
 }
 export const TEST_COLLECTION_EXCLUDE = ['.git', 'coverage', 'dist', 'node_modules'];
 export const TIER_NAMES = ['unit', 'tool', 'localhost', 'remote'];
-function collectTestFiles(dir, relativeDir, inTestDir, context) {
+function collectTestFiles(dir, relativeDir, isInTestDir, context) {
     const entries = readdirSync(dir, { withFileTypes: true });
     for (const entry of entries) {
         const relativePath = relativeDir === '' ? entry.name : `${relativeDir}/${entry.name}`;
         if (entry.isDirectory()) {
-            if (context.pruned.has(entry.name))
+            if (context.pruned.has(entry.name) || context.ignoredPaths.has(`${relativePath}/`))
                 continue;
-            collectTestFiles(path.join(dir, entry.name), relativePath, inTestDir || entry.name === TEST_DIR, context);
+            collectTestFiles(path.join(dir, entry.name), relativePath, isInTestDir || entry.name === TEST_DIR, context);
         }
-        else if (inTestDir !== context.misplaced && TEST_FILE_PATTERN.test(entry.name)) {
-            context.found.push(relativePath);
+        else if (isInTestDir !== context.misplaced &&
+            TEST_FILE_PATTERN.test(entry.name) &&
+            !context.ignoredPaths.has(relativePath)) {
+            context.foundPaths.push(relativePath);
         }
     }
 }
-function walkTestFiles(rootDir, { exclude = [] }, misplaced) {
+function walkTestFiles(rootDir, { excludedBasenames = [] }, misplaced) {
     const context = {
-        found: [],
+        foundPaths: [],
+        ignoredPaths: new Set(listGitIgnoredPaths(rootDir)),
         misplaced,
-        pruned: new Set([...TEST_COLLECTION_EXCLUDE, ...exclude]),
+        pruned: new Set([...TEST_COLLECTION_EXCLUDE, ...excludedBasenames]),
     };
     collectTestFiles(rootDir, '', false, context);
-    return context.found.toSorted();
+    return context.foundPaths.toSorted();
 }

package/dist/esm/types.d.ts

@@ -6,7 +6,7 @@ export type { CommandVerbosity } from './verbosity.js';
 export interface BuildConfig {
     /**
      * Patterns added to the build's default ignore set. Extends rather than replaces, so that declaring one pattern
-     * cannot silently drop the defaults and start shipping a package's own tests.
+     * cannot silently drop the defaults and start publishing a package's own tests.
      * The programmatic `buildPackage` option of the same name behaves identically; its bare `ignorePatterns` replaces.
      */
     extraIgnorePatterns?: string[];
@@ -23,7 +23,7 @@ export interface CheckCacheConfig {
     /**
      * Command names added to the cacheable set. Extends rather than replaces, so that declaring one command
      * cannot silently drop the defaults. A name listed here promises exit-status-only semantics through its whole
-     * chain, hooks included, and has to resolve to a command: both lists are read by name alone, so a misspelt
+     * chain, hooks included, and has to resolve to a command: Both lists are read by name alone, so a misspelt
      * entry would otherwise be inert.
      */
     extraCommands?: string[];
@@ -31,13 +31,13 @@ export interface CheckCacheConfig {
 /** Output settings honored at the monorepo root. */
 export interface OutputConfig {
     /**
-     * The verbosity a run takes when neither `-q` nor the environment named one. Both of those outrank it, and it
-     * outranks agent-harness detection, so `full` here is also how a repo declines to be detected.
+     * The verbosity that a run takes when neither `-q` nor the environment named one. Both of those outrank it.
+     * Because it outranks agent-harness detection, `full` here is also how a repo declines to be detected.
      */
     commandVerbosity?: CommandVerbosity;
     /**
      * Environment-variable names added to the set whose presence marks an agent harness. Extends rather than
-     * replaces, so that declaring one name cannot silently drop the shipped list, and a repo absorbs a harness's
+     * replaces, so that declaring one name cannot silently drop the built-in list, and a repo handles a harness's
      * rename without waiting for an nmr release.
      */
     extraAgentEnvVars?: string[];

package/dist/esm/verbosity.d.ts

@@ -1,55 +1,57 @@
 import type { OutputConfig } from './types.js';
 /**
- * Environment variables a known agent harness sets, whose presence selects quiet when no level above them chose.
- * The identifiers belong to ecosystems nmr does not control and that rename, so `output.extraAgentEnvVars` extends
- * this list rather than a repo waiting for a release. `ROVO_CLI` anticipates a rename of `ROVODEV_CLI` that Rovo
- * has signalled but not made; a variable nobody sets never fires.
+ * Environment variables that a known agent harness sets, whose presence selects quiet when every level above them
+ * left the verbosity unset. `output.extraAgentEnvVars` extends the list. `ROVO_CLI` anticipates a rename of
+ * `ROVODEV_CLI` that Rovo has signalled but not made.
  */
 export declare const AGENT_ENV_VARS: readonly ["CLAUDECODE", "ROVODEV_CLI", "ROVO_CLI"];
 /**
  * The points on the loudness ladder. Both are spelled out rather than leaving `full` implicit in the variable's
- * absence, so a repo-level default is overridable from the environment in either direction.
+ * absence, so that a repo-level default is overridable from the environment in either direction.
  */
 export declare const COMMAND_VERBOSITIES: readonly ["full", "quiet"];
 /**
- * Carries the resolved verbosity down the spawned chain, so `-q` reaches every process rather than the first.
- * Deliberately not a keyed variable: it changes what a run prints and never what a command concludes, so folding
- * it into the cache key would stop a quiet run from hitting a pass a loud one recorded.
+ * Passes the resolved verbosity down the chain of spawned processes, so that `-q` applies to every process rather
+ * than only the first. The pass key does not include it: It changes what a run prints and never what a command
+ * concludes, so a quiet run can reuse a pass that a full run recorded.
  */
 export declare const COMMAND_VERBOSITY_ENV_VAR = "NMR_COMMAND_VERBOSITY";
-/** How loudly nmr reports the output of the commands it runs, which is never its own verdicts. */
+/** How loudly nmr reports the output of the commands that it runs, which is never its own verdicts. */
 export type CommandVerbosity = (typeof COMMAND_VERBOSITIES)[number];
 /**
- * Renders the rejection of a value off the loudness ladder, naming where it was written. Every source that accepts
- * a verbosity renders through this, so no two of them can come to name different ladders.
+ * Renders the rejection of a value off the loudness ladder, naming where it was written. Because every source that
+ * accepts a verbosity renders through this, the sources cannot come to name different ladders.
  */
 export declare function formatVerbosityRejection(source: string, value: string): string;
 /** Narrows a raw value to a point on the loudness ladder. */
 export declare function isCommandVerbosity(value: string): value is CommandVerbosity;
 /**
- * Reads the verbosity the environment names. An unrecognized value resolves to nothing at all, since falling back
- * would pick a mode nobody chose and hide a misspelling for the life of the shell.
+ * Reads the verbosity that the environment names. An unrecognized value is returned as an error, since a fallback
+ * would pick a mode that nobody chose and hide a misspelling for the life of the shell.
  *
- * An unset or empty variable names no verbosity rather than resolving to `full`, which is what leaves the config
- * and detection levels reachable: a floor written in here would outrank both of them.
+ * For an unset or empty variable, this returns a result without a verbosity rather than resolving to `full`, which
+ * is what leaves the config and detection levels reachable: A floor written in here would outrank both of them.
  */
 export declare function readVerbosityEnv(env: NodeJS.ProcessEnv): VerbosityRead;
 export interface ResolveVerbosityOptions {
-    /** Read for the detection level, and for that alone: the variable this module owns arrives as `envVerbosity`. */
+    /**
+     * Read for the detection level, and for that alone: The caller passes the variable that this module owns as
+     * `envVerbosity`.
+     */
     env: NodeJS.ProcessEnv;
     envVerbosity: CommandVerbosity | undefined;
+    hasQuietFlag: boolean;
     output: OutputConfig | undefined;
-    quietFlag: boolean;
 }
 /**
- * Resolves the verbosity this process runs at: the flag, then the environment, then the repo's config, then
+ * Resolves the verbosity at which this process runs: the flag, then the environment, then the repo's config, then
  * detection of a known agent harness, then `full`.
  *
- * Total by construction. The environment was validated as it was read and the config as it was loaded, so no
- * rejection is left for this to report and the whole ladder reads in one place.
+ * Total by construction. The environment was validated as it was read and the config as it was loaded, so this does
+ * not have any rejection left to report, and the whole ladder can be read in one place.
  */
 export declare function resolveVerbosity(options: ResolveVerbosityOptions): CommandVerbosity;
-/** The verbosity the environment names, if any, or the message naming why its value could not be read. */
+/** The verbosity that the environment names, if any, or the message naming why its value could not be read. */
 export type VerbosityRead = {
     ok: true;
     verbosity?: CommandVerbosity;

package/dist/esm/verbosity.js

@@ -9,18 +9,18 @@ export function isCommandVerbosity(value) {
     return names.includes(value);
 }
 export function readVerbosityEnv(env) {
-    const raw = env[COMMAND_VERBOSITY_ENV_VAR];
-    if (raw === undefined || raw === '') {
+    const rawValue = env[COMMAND_VERBOSITY_ENV_VAR];
+    if (rawValue === undefined || rawValue === '') {
         return { ok: true };
     }
-    if (!isCommandVerbosity(raw)) {
-        return { ok: false, error: formatVerbosityRejection(COMMAND_VERBOSITY_ENV_VAR, raw) };
+    if (!isCommandVerbosity(rawValue)) {
+        return { ok: false, error: formatVerbosityRejection(COMMAND_VERBOSITY_ENV_VAR, rawValue) };
     }
-    return { ok: true, verbosity: raw };
+    return { ok: true, verbosity: rawValue };
 }
 export function resolveVerbosity(options) {
-    const { env, envVerbosity, output, quietFlag } = options;
-    if (quietFlag)
+    const { env, envVerbosity, hasQuietFlag, output } = options;
+    if (hasQuietFlag)
         return 'quiet';
     if (envVerbosity !== undefined)
         return envVerbosity;

package/dist/esm/verdict.d.ts

@@ -3,33 +3,41 @@ import { type OutputStyle } from '@williamthorsen/nmr-core';
 import type { ReplayLine } from './check-cache.js';
 import type { ReportFormat } from './report-format.js';
 /**
- * The ceiling a rendered verdict, its newline included, is held to.
+ * The ceiling to which a rendered verdict, its newline included, is held.
  *
- * POSIX guarantees a write at or below `PIPE_BUF` reaches a pipe whole, and 512 is the smallest bound the
- * standard permits, so one write of a line this size cannot be interleaved by a concurrent scope under
- * `pnpm --recursive`. No Node API reports the platform's own bound, and a per-platform table would move the
- * truncation point from one machine to the next. The ceiling governs pipes: a terminal offers no such
- * guarantee at any size.
+ * POSIX guarantees that a write at or below `PIPE_BUF` arrives in a pipe whole, and 512 is the smallest bound that
+ * the standard permits, so one write of a line this size cannot be interleaved by a concurrent scope under
+ * `pnpm --recursive`. Node does not have an API that reports the platform's own bound, and a per-platform table
+ * would move the truncation point from one machine to the next. The ceiling applies to pipes: A terminal does not
+ * offer that guarantee at any size.
  */
-export declare const VERDICT_LINE_LIMIT = 512;
+export declare const VERDICT_LINE_LIMIT_BYTES = 512;
 /**
- * What a command nmr ran came to, holding the facts a reporting line is rendered from rather than the line
- * itself, so a machine-readable rendering spends the same record a human-readable one does.
+ * Why a command ran nothing, which the `no-op` outcome includes and `--json` serializes.
  *
- * A recalled pass carries its saving as a duration and not as a decision about whether to mention it: whether
- * one is worth naming belongs to rendering, and a consumer bypassing the renderer inherits neither the
- * threshold nor an obligation to restate it.
+ * `empty-workspace` and `empty-override` both leave a chain without any step in it, so the reason tells a command
+ * emptied by the workspace apart from one emptied by an override.
+ */
+export type NoOpReason = 'empty-override' | 'empty-workspace' | 'noop-override';
+/**
+ * The result of a command that nmr ran. It contains the facts from which a reporting line is rendered rather than
+ * the line itself, which lets a machine-readable rendering use the same record as a human-readable one.
+ *
+ * A recalled pass records its saving as a duration and not as a decision about whether to mention it: Whether
+ * one is worth naming belongs to rendering, and a consumer bypassing the renderer inherits neither the threshold
+ * nor an obligation to restate it.
  */
 export type Verdict = {
     command: string;
     scope: string;
 } & VerdictOutcome;
 /**
- * How a command ended, together with the facts that ending carries and no other does, and the trailing detail
- * a line reserves room for.
+ * How a command ended, together with the facts specific to that ending, and the trailing detail for which a line
+ * reserves room.
  *
- * A recalled pass carries the excerpts it replays rather than a composed detail string, so the marker naming
- * them a recording, and the ceiling they are held to, stay with the module that owns the line's grammar.
+ * A recalled pass contains the excerpts that it replays rather than a composed detail string, so that the marker
+ * naming them a recording, and the ceiling to which they are held, stay with the module that owns the line's
+ * grammar.
  */
 export type VerdictOutcome = {
     detail?: string;
@@ -47,32 +55,31 @@ export type VerdictOutcome = {
     replay?: ReplayLine[];
 } | {
     outcome: 'no-op';
-    reason: 'empty-override' | 'noop-override';
+    reason: NoOpReason;
 });
 /**
- * Renders a verdict as the line nmr reports it on, without the newline that terminates it.
+ * Renders a verdict as the line on which nmr reports it, without the newline that terminates it.
  *
- * The line ends without terminal punctuation and reserves its tail for `detail`, so a later change appends to
- * the grammar rather than rewriting it. A detail carrying nothing but line breaks takes its whole clause with
- * it, rather than leaving a separator pointing at nothing.
+ * The line ends without terminal punctuation and reserves its tail for `detail`, so that a later change appends to
+ * the grammar rather than rewriting it. When a detail contains nothing but line breaks, the line omits the detail's
+ * whole clause rather than leaving a separator pointing at nothing.
  *
- * The marker takes no padding column: every plain marker a verdict reaches for is four characters, so the
- * lines align by construction. `formatStatusLine` pads to a column that `BLOCK` widens, and no verdict is one.
+ * The marker does not take a padding column. Because every plain marker that a verdict uses is four characters,
+ * the lines align by construction. `formatStatusLine` pads to a column that `BLOCK` widens, and a verdict is never
+ * one.
  */
 export declare function renderVerdict(verdict: Verdict, style: OutputStyle): string;
 /**
- * Renders a verdict as the JSON object a machine consumer reads, without the newline that terminates it.
+ * Renders a verdict as the JSON object that a machine consumer reads, without the newline that terminates it.
  *
- * Held to the ceiling the prose line is held to, so one write still reaches a pipe whole where concurrent
- * scopes share a descriptor. Cuts land inside the record's text rather than across its structure, which is
- * what leaves the line parseable, and a record is fitted by rungs, each shedding what a reader can better
- * spare than the rung below it. What the ceiling costs is [documented](../docs/reporting.md#reporting-for-a-machine)
- * in the same order.
+ * Held to the same ceiling as the prose line, so that one write still arrives in a pipe whole when concurrent
+ * scopes share a descriptor. It cuts inside the record's text rather than across its structure, which leaves the
+ * line parseable, and fits a record by rungs, each shedding what a reader can better spare than the rung below it.
+ * Each rung is [documented](../docs/reporting.md#reporting-for-a-machine) in the same order.
  */
 export declare function serializeVerdict(verdict: Verdict): string;
 /**
- * Writes a verdict to a stream as a single write, which is what holds a line together when concurrent scopes
- * share one descriptor. Both renderings spend the one record, so neither can come to report what the other
- * does not.
+ * Writes a verdict to a stream as a single write, which keeps a line intact when concurrent scopes share one
+ * descriptor. Both renderings use the one record, so neither can come to report what the other does not.
  */
 export declare function writeVerdict(verdict: Verdict, stream: Writable, format: ReportFormat, style: OutputStyle): void;

package/dist/esm/verdict.js

@@ -2,7 +2,7 @@ import { STATUS_GLYPHS } from '@williamthorsen/nmr-core';
 import { NMR_GLYPHS } from "./glyphs.js";
 import { clampToBytes, TRUNCATION_MARK } from "./helpers/clampToBytes.js";
 import { formatDuration, formatSaving } from "./helpers/duration.js";
-export const VERDICT_LINE_LIMIT = 512;
+export const VERDICT_LINE_LIMIT_BYTES = 512;
 export function renderVerdict(verdict, style) {
     const { marker, phrase } = describeOutcome(verdict, style);
     const detail = flattenDetail(verdict.detail ?? renderReplay(verdict) ?? '');
@@ -10,15 +10,15 @@ export function renderVerdict(verdict, style) {
     return clampToBytes(`${marker} ${verdict.scope}: ${verdict.command}: ${phrase}${detailClause}`, LINE_BUDGET_BYTES);
 }
 export function serializeVerdict(verdict) {
-    const rendered = JSON.stringify(verdict);
-    return isWithinBudget(rendered) ? rendered : renderWithinBudget(verdict);
+    const renderedLine = JSON.stringify(verdict);
+    return isWithinBudget(renderedLine) ? renderedLine : renderWithinBudget(verdict);
 }
 export function writeVerdict(verdict, stream, format, style) {
     const line = format === 'json' ? serializeVerdict(verdict) : renderVerdict(verdict, style);
     stream.write(`${line}\n`);
 }
 const NEWLINE_BYTES = 1;
-const LINE_BUDGET_BYTES = VERDICT_LINE_LIMIT - NEWLINE_BYTES;
+const LINE_BUDGET_BYTES = VERDICT_LINE_LIMIT_BYTES - NEWLINE_BYTES;
 const MIN_CUT_BYTES = Buffer.byteLength(TRUNCATION_MARK);
 const REPLAY_MARKER = 'replayed:';
 function describeOutcome(verdict, style) {
@@ -40,13 +40,24 @@ function describeOutcome(verdict, style) {
             };
         }
         case 'no-op':
-            return {
-                marker: NMR_GLYPHS[style].noop.text,
-                phrase: `skipped, the override is ${verdict.reason === 'empty-override' ? 'empty' : 'a no-op'}`,
-            };
+            return { marker: NMR_GLYPHS[style].noop.text, phrase: `skipped, ${describeNoOpReason(verdict.reason)}` };
+        default: {
+            const unhandledVerdict = verdict;
+            throw new Error(`Unhandled verdict outcome: ${JSON.stringify(unhandledVerdict)}`);
+        }
+    }
+}
+function describeNoOpReason(reason) {
+    switch (reason) {
+        case 'empty-override':
+            return 'the override is empty';
+        case 'empty-workspace':
+            return 'the workspace does not declare any package';
+        case 'noop-override':
+            return 'the override is a no-op';
         default: {
-            const unhandled = verdict;
-            throw new Error(`Unhandled verdict outcome: ${JSON.stringify(unhandled)}`);
+            const unhandledReason = reason;
+            throw new Error(`Unhandled no-op reason: ${String(unhandledReason)}`);
         }
     }
 }
@@ -64,14 +75,16 @@ function renderReplay(verdict) {
 function flattenDetail(detail) {
     return detail.replaceAll(/[\r\n]+/gu, ' ').trim();
 }
-function findCutTarget(sizes, longest, overrunBytes) {
-    const below = sizes.filter((size) => size < longest && size > MIN_CUT_BYTES);
-    const share = Math.ceil(overrunBytes / sizes.filter((size) => size === longest).length);
-    const target = below.length === 0 ? longest - share : Math.max(...below, longest - overrunBytes);
+function findCutTarget(sizesBytes, longestSizeBytes, overrunBytes) {
+    const smallerSizesBytes = sizesBytes.filter((size) => size < longestSizeBytes && size > MIN_CUT_BYTES);
+    const share = Math.ceil(overrunBytes / sizesBytes.filter((size) => size === longestSizeBytes).length);
+    const target = smallerSizesBytes.length === 0
+        ? longestSizeBytes - share
+        : Math.max(...smallerSizesBytes, longestSizeBytes - overrunBytes);
     return Math.max(MIN_CUT_BYTES, target);
 }
-function isWithinBudget(rendered) {
-    return Buffer.byteLength(rendered) <= LINE_BUDGET_BYTES;
+function isWithinBudget(renderedLine) {
+    return Buffer.byteLength(renderedLine) <= LINE_BUDGET_BYTES;
 }
 function readAttribution(verdict) {
     if (verdict.outcome !== 'recalled' || verdict.replay === undefined) {
@@ -84,64 +97,64 @@ function readCuttableText(verdict) {
     return [verdict.detail ?? '', ...excerpts];
 }
 function renderClamped(record) {
-    const clamped = { ...record };
-    let rendered = JSON.stringify(clamped);
-    while (!isWithinBudget(rendered)) {
+    const clampedRecord = { ...record };
+    let renderedLine = JSON.stringify(clampedRecord);
+    while (!isWithinBudget(renderedLine)) {
         const fields = ['command', 'scope'];
-        const sizes = fields.map((field) => Buffer.byteLength(typeof clamped[field] === 'string' ? clamped[field] : ''));
-        const longest = Math.max(...sizes);
-        if (longest <= MIN_CUT_BYTES) {
-            return rendered;
+        const sizesBytes = fields.map((field) => Buffer.byteLength(typeof clampedRecord[field] === 'string' ? clampedRecord[field] : ''));
+        const longestSizeBytes = Math.max(...sizesBytes);
+        if (longestSizeBytes <= MIN_CUT_BYTES) {
+            return renderedLine;
         }
-        const target = findCutTarget(sizes, longest, Buffer.byteLength(rendered) - LINE_BUDGET_BYTES);
-        const field = fields[sizes.indexOf(longest)] ?? 'command';
-        clamped[field] = clampToBytes(typeof clamped[field] === 'string' ? clamped[field] : '', target);
-        rendered = JSON.stringify(clamped);
+        const target = findCutTarget(sizesBytes, longestSizeBytes, Buffer.byteLength(renderedLine) - LINE_BUDGET_BYTES);
+        const field = fields[sizesBytes.indexOf(longestSizeBytes)] ?? 'command';
+        clampedRecord[field] = clampToBytes(typeof clampedRecord[field] === 'string' ? clampedRecord[field] : '', target);
+        renderedLine = JSON.stringify(clampedRecord);
     }
-    return rendered;
+    return renderedLine;
 }
 function renderWithinBudget(verdict) {
-    const shortened = shortenCuttableText(verdict);
-    const shortenedLine = JSON.stringify(shortened);
+    const shortenedVerdict = shortenCuttableText(verdict);
+    const shortenedLine = JSON.stringify(shortenedVerdict);
     if (isWithinBudget(shortenedLine)) {
         return shortenedLine;
     }
-    const record = { ...shortened };
+    const record = { ...shortenedVerdict };
     delete record['detail'];
-    const attribution = readAttribution(shortened);
-    for (let kept = attribution.length; kept > 0; kept--) {
-        record['replay'] = attribution.slice(0, kept);
-        const rendered = JSON.stringify(record);
-        if (isWithinBudget(rendered)) {
-            return rendered;
+    const attribution = readAttribution(shortenedVerdict);
+    for (let keptCount = attribution.length; keptCount > 0; keptCount--) {
+        record['replay'] = attribution.slice(0, keptCount);
+        const renderedLine = JSON.stringify(record);
+        if (isWithinBudget(renderedLine)) {
+            return renderedLine;
         }
     }
     delete record['replay'];
-    const bare = JSON.stringify(record);
-    return isWithinBudget(bare) ? bare : renderClamped(record);
+    const bareLine = JSON.stringify(record);
+    return isWithinBudget(bareLine) ? bareLine : renderClamped(record);
 }
 function shortenCuttableText(verdict) {
     let candidate = verdict;
-    let rendered = JSON.stringify(candidate);
-    while (!isWithinBudget(rendered)) {
-        const shortened = shortenLongestText(candidate, Buffer.byteLength(rendered) - LINE_BUDGET_BYTES);
-        if (shortened === undefined) {
+    let renderedLine = JSON.stringify(candidate);
+    while (!isWithinBudget(renderedLine)) {
+        const shortenedVerdict = shortenLongestText(candidate, Buffer.byteLength(renderedLine) - LINE_BUDGET_BYTES);
+        if (shortenedVerdict === undefined) {
             return candidate;
         }
-        candidate = shortened;
-        rendered = JSON.stringify(candidate);
+        candidate = shortenedVerdict;
+        renderedLine = JSON.stringify(candidate);
     }
     return candidate;
 }
 function shortenLongestText(verdict, overrunBytes) {
     const texts = readCuttableText(verdict);
-    const sizes = texts.map((text) => Buffer.byteLength(text));
-    const longest = Math.max(...sizes);
-    if (longest <= MIN_CUT_BYTES) {
+    const sizesBytes = texts.map((text) => Buffer.byteLength(text));
+    const longestSizeBytes = Math.max(...sizesBytes);
+    if (longestSizeBytes <= MIN_CUT_BYTES) {
         return undefined;
     }
-    const index = sizes.indexOf(longest);
-    const target = findCutTarget(sizes, longest, overrunBytes);
+    const index = sizesBytes.indexOf(longestSizeBytes);
+    const target = findCutTarget(sizesBytes, longestSizeBytes, overrunBytes);
     return writeCuttableText(verdict, index, clampToBytes(texts[index] ?? '', target));
 }
 function writeCuttableText(verdict, index, value) {