@williamthorsen/nmr-core 0.14.0 → 0.15.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,4 +1,49 @@
1
1
  [
2
+ {
3
+ "version": "0.15.1",
4
+ "date": "2026-11-06",
5
+ "sections": [
6
+ {
7
+ "title": "🐛 Bug fixes",
8
+ "audience": "all",
9
+ "items": [
10
+ {
11
+ "description": "Fixes the issue that `nmr` and `v11y-check` printed a Node system error, such as `EACCES` or `ENOENT`, as an internal error with a stack trace rather than as `Error: <message>`. (#1158)",
12
+ "hash": "3a62cc768b23f37156c846f32fd4acaa70f7f931",
13
+ "entry": 2
14
+ }
15
+ ]
16
+ }
17
+ ]
18
+ },
19
+ {
20
+ "version": "0.15.0",
21
+ "date": "2026-11-05",
22
+ "sections": [
23
+ {
24
+ "title": "🎉 Features",
25
+ "audience": "all",
26
+ "items": [
27
+ {
28
+ "description": "Adds `reportCrash` to `@williamthorsen/nmr-core`, which writes `<bin>: internal error: <message>` followed by the error's stack frames, so that a CLI can report a crash differently from a handled error written by `reportError`. (#1153)",
29
+ "hash": "0289c032b00438984efcf7466f2b3055b4dbc546",
30
+ "entry": 3
31
+ }
32
+ ]
33
+ },
34
+ {
35
+ "title": "🏗️ Internal features",
36
+ "audience": "dev",
37
+ "items": [
38
+ {
39
+ "description": "Adds `UserError` and `reportFailure` to `@williamthorsen/nmr-core` so that a CLI's last-resort handler prints an anticipated failure as `Error: <message>` and anything else as an internal error, and makes `ParseError` extend `UserError`. (#1157)",
40
+ "hash": "ef1ed5f50bf0b01f19b6d6fe82a40322a8286002",
41
+ "entry": 3
42
+ }
43
+ ]
44
+ }
45
+ ]
46
+ },
2
47
  {
3
48
  "version": "0.14.0",
4
49
  "date": "2026-10-27",
package/CHANGELOG.md CHANGED
@@ -2,6 +2,22 @@
2
2
 
3
3
  All notable changes to this project will be documented in this file.
4
4
 
5
+ ## 0.15.1 — 2026-11-06
6
+
7
+ ### 🐛 Bug fixes
8
+
9
+ - Fixes the issue that `nmr` and `v11y-check` printed a Node system error, such as `EACCES` or `ENOENT`, as an internal error with a stack trace rather than as `Error: <message>`. (#1158)
10
+
11
+ ## 0.15.0 — 2026-11-05
12
+
13
+ ### 🎉 Features
14
+
15
+ - Adds `reportCrash` to `@williamthorsen/nmr-core`, which writes `<bin>: internal error: <message>` followed by the error's stack frames, so that a CLI can report a crash differently from a handled error written by `reportError`. (#1153)
16
+
17
+ ### 🏗️ Internal features
18
+
19
+ - Adds `UserError` and `reportFailure` to `@williamthorsen/nmr-core` so that a CLI's last-resort handler prints an anticipated failure as `Error: <message>` and anything else as an internal error, and makes `ParseError` extend `UserError`. (#1157)
20
+
5
21
  ## 0.14.0 — 2026-10-27
6
22
 
7
23
  ### 🎉 Features
package/README.md CHANGED
@@ -7,13 +7,11 @@ Shared utilities for node-monorepo-tools packages.
7
7
  This package serves as the shared library foundation for the monorepo. For the nmr CLI tool, see [`@williamthorsen/nmr`](../nmr).
8
8
 
9
9
  <!-- section:release-notes -->
10
- ## Release notes — v0.14.0 (2026-10-27)
10
+ ## Release notes — v0.15.1 (2026-11-06)
11
11
 
12
- ### 🎉 Features
12
+ ### 🐛 Bug fixes
13
13
 
14
- - Report the time that a build-cache hit saved (#1112)
15
-
16
- Adds the time that a build-cache hit saved to the skip line printed by `nmr-compile`, as in `Skipping build, saved ~2.1s.`, when the skipped emit took at least a second. The change also measures the durations that nmr reports on the monotonic clock, so that an adjustment of the system clock during a run no longer shortens or negates them.
14
+ - Fixes the issue that `nmr` and `v11y-check` printed a Node system error, such as `EACCES` or `ENOENT`, as an internal error with a stack trace rather than as `Error: <message>`. (#1158)
17
15
  <!-- /section:release-notes -->
18
16
 
19
17
  ## Installation
@@ -0,0 +1,10 @@
1
+ /**
2
+ * A failure that the tool anticipated -- in the user's input, config, or environment, including a failed external
3
+ * command -- rather than a fault in the tool.
4
+ *
5
+ * A CLI's last-resort handler prints one of these, or a Node system error, as `Error: <message>`, and anything else as an
6
+ * internal error.
7
+ */
8
+ export declare class UserError extends Error {
9
+ constructor(message: string, options?: ErrorOptions);
10
+ }
@@ -0,0 +1,6 @@
1
+ export class UserError extends Error {
2
+ constructor(message, options) {
3
+ super(message, options);
4
+ this.name = 'UserError';
5
+ }
6
+ }
@@ -1 +1 @@
1
- export const GIT_OUTPUT_LIMIT_BYTES = 64 * 1_024 * 1_024;
1
+ export const GIT_OUTPUT_LIMIT_BYTES = 64 * 1024 * 1024;
@@ -5,13 +5,15 @@ export { GIT_OUTPUT_LIMIT_BYTES } from './gitOutputLimit.js';
5
5
  export { hasErrnoCode } from './hasErrnoCode.js';
6
6
  export type { WorkingTreeHashResult } from './hashWorkingTree.js';
7
7
  export { hashWorkingTree, readHeadSha } from './hashWorkingTree.js';
8
+ export { isAnticipatedFailure } from './isAnticipatedFailure.js';
8
9
  export type { FlagDefinition, FlagSchema, ParseArgsOptions, ParsedArgs, ParsedFlags, ParseErrorKind, } from './parseArgs.js';
9
10
  export { parseArgs, parseArgsOrExit, ParseError } from './parseArgs.js';
10
11
  export type { GlyphSet, InvalidOutputStyle, OutputStyle, ResolveStreamStylesOptions, StatusGlyphName, StreamStyleResolution, StreamStyles, TruncateToWidthOptions, } from './terminal.js';
11
- export { defineGlyphSet, describeInvalidOutputStyle, formatErrorLine, formatGlyphLine, formatStatusLine, measureGlyphColumn, measureWidth, printError, printSkip, printStep, printSuccess, reportError, reportTemplateUpdate, reportWriteResult, resolveStreamStyles, STATUS_GLYPHS, truncateToWidth, wrapToWidth, } from './terminal.js';
12
+ export { defineGlyphSet, describeInvalidOutputStyle, formatErrorLine, formatGlyphLine, formatStatusLine, measureGlyphColumn, measureWidth, printError, printSkip, printStep, printSuccess, reportCrash, reportError, reportFailure, reportTemplateUpdate, reportWriteResult, resolveStreamStyles, STATUS_GLYPHS, truncateToWidth, wrapToWidth, } from './terminal.js';
12
13
  export { startTimer } from './timer.js';
13
14
  export type { ManagedFileOutcome, ManagedFileResult } from './updateManagedFile.js';
14
15
  export { updateManagedFile } from './updateManagedFile.js';
16
+ export { UserError } from './UserError.js';
15
17
  export type { WriteOutcome, WriteResult } from './writeFileWithCheck.js';
16
18
  export { writeFileWithCheck } from './writeFileWithCheck.js';
17
19
  export { findPackageRoot, resolveSelfVersion } from '@williamthorsen/toolbelt.packaging/candidate';
package/dist/esm/index.js CHANGED
@@ -3,9 +3,11 @@ export { readCacheEntry, readGuardedCacheEntry, readJsonCacheEntry, removeCacheD
3
3
  export { GIT_OUTPUT_LIMIT_BYTES } from "./gitOutputLimit.js";
4
4
  export { hasErrnoCode } from "./hasErrnoCode.js";
5
5
  export { hashWorkingTree, readHeadSha } from "./hashWorkingTree.js";
6
+ export { isAnticipatedFailure } from "./isAnticipatedFailure.js";
6
7
  export { parseArgs, parseArgsOrExit, ParseError } from "./parseArgs.js";
7
- export { defineGlyphSet, describeInvalidOutputStyle, formatErrorLine, formatGlyphLine, formatStatusLine, measureGlyphColumn, measureWidth, printError, printSkip, printStep, printSuccess, reportError, reportTemplateUpdate, reportWriteResult, resolveStreamStyles, STATUS_GLYPHS, truncateToWidth, wrapToWidth, } from "./terminal.js";
8
+ export { defineGlyphSet, describeInvalidOutputStyle, formatErrorLine, formatGlyphLine, formatStatusLine, measureGlyphColumn, measureWidth, printError, printSkip, printStep, printSuccess, reportCrash, reportError, reportFailure, reportTemplateUpdate, reportWriteResult, resolveStreamStyles, STATUS_GLYPHS, truncateToWidth, wrapToWidth, } from "./terminal.js";
8
9
  export { startTimer } from "./timer.js";
9
10
  export { updateManagedFile } from "./updateManagedFile.js";
11
+ export { UserError } from "./UserError.js";
10
12
  export { writeFileWithCheck } from "./writeFileWithCheck.js";
11
13
  export { findPackageRoot, resolveSelfVersion } from '@williamthorsen/toolbelt.packaging/candidate';
@@ -0,0 +1,5 @@
1
+ /**
2
+ * Reports whether a thrown value is a failure that a CLI reports as `Error: <message>` rather than as an internal
3
+ * error: a `UserError`, or a Node system error such as `EACCES` or `ENOENT`, which comes from the environment.
4
+ */
5
+ export declare function isAnticipatedFailure(error: unknown): error is Error;
@@ -0,0 +1,12 @@
1
+ import { isError } from '@williamthorsen/toolbelt.errors';
2
+ import { UserError } from "./UserError.js";
3
+ export function isAnticipatedFailure(error) {
4
+ return error instanceof UserError || isSystemError(error);
5
+ }
6
+ function isSystemError(error) {
7
+ return (isError(error) &&
8
+ 'code' in error &&
9
+ typeof error.code === 'string' &&
10
+ 'syscall' in error &&
11
+ typeof error.syscall === 'string');
12
+ }
@@ -1,3 +1,4 @@
1
+ import { UserError } from './UserError.js';
1
2
  /** Schema entry describing a single CLI flag. */
2
3
  export interface FlagDefinition {
3
4
  long: string;
@@ -29,7 +30,7 @@ export type ParseErrorKind = 'unknown-flag' | 'missing-value' | 'unexpected-valu
29
30
  * positional value for `'unexpected-positional'`. Its `message` is composed from those fields, so error
30
31
  * wording is uniform across every kind.
31
32
  */
32
- export declare class ParseError extends Error {
33
+ export declare class ParseError extends UserError {
33
34
  readonly kind: ParseErrorKind;
34
35
  readonly flag: string;
35
36
  constructor(kind: ParseErrorKind, flag: string);
@@ -1,8 +1,9 @@
1
1
  import process from 'node:process';
2
2
  import { parseArgs as nodeParseArgs } from 'node:util';
3
3
  import { reportError } from "./terminal.js";
4
+ import { UserError } from "./UserError.js";
4
5
  const initialFlagValues = { boolean: false, string: undefined };
5
- export class ParseError extends Error {
6
+ export class ParseError extends UserError {
6
7
  kind;
7
8
  flag;
8
9
  constructor(kind, flag) {
@@ -41,8 +41,18 @@ export declare function printSkip(message: string, style?: OutputStyle): void;
41
41
  export declare function printStep(message: string): void;
42
42
  /** Prints a success message to stdout, in the style detected for stdout unless one is given. */
43
43
  export declare function printSuccess(message: string, style?: OutputStyle): void;
44
+ /**
45
+ * Writes an unexpected crash, a bug in the tool, as `<bin>: internal error: <message>` followed by the error's stack
46
+ * frames. A handled error goes through `reportError` instead, so that a reader can tell the two apart.
47
+ */
48
+ export declare function reportCrash(bin: string, error: unknown, stream?: Writable): void;
44
49
  /** Writes the canonical `Error: <message>` line to `stream`, which an in-process CLI sets to its own `Writable`. */
45
50
  export declare function reportError(message: string, stream?: Writable): void;
51
+ /**
52
+ * Writes a failure that reached a CLI's last-resort handler: an anticipated failure (see `isAnticipatedFailure`) as
53
+ * `Error: <message>`, and anything else as an internal error through `reportCrash`.
54
+ */
55
+ export declare function reportFailure(bin: string, error: unknown, stream?: Writable): void;
46
56
  /**
47
57
  * Prints a status line for a managed-file result, followed by its diff indented beneath it: a failure to stderr,
48
58
  * every other outcome to stdout.
@@ -1,5 +1,7 @@
1
1
  import process from 'node:process';
2
+ import { describeError, isError } from '@williamthorsen/toolbelt.errors';
2
3
  import { detectOutputStyle, measureGlyphColumn, resolveOutputStyle, STATUS_GLYPHS, } from '@williamthorsen/toolbelt.terminal/candidate';
4
+ import { isAnticipatedFailure } from "./isAnticipatedFailure.js";
3
5
  export { defineGlyphSet, describeInvalidOutputStyle, measureGlyphColumn, measureWidth, STATUS_GLYPHS, truncateToWidth, wrapToWidth, } from '@williamthorsen/toolbelt.terminal/candidate';
4
6
  export function formatErrorLine(message) {
5
7
  return `Error: ${message}`;
@@ -26,9 +28,21 @@ export function printStep(message) {
26
28
  export function printSuccess(message, style = detectStreamStyle(process.stdout)) {
27
29
  console.info(` ${formatStatusLine(style, 'passed', message)}`);
28
30
  }
31
+ export function reportCrash(bin, error, stream = process.stderr) {
32
+ const frames = isError(error) && error.stack !== undefined ? extractStackFrames(error.stack) : '';
33
+ const header = `${bin}: internal error: ${describeError(error)}\n`;
34
+ stream.write(frames === '' ? header : `${header}${frames}\n`);
35
+ }
29
36
  export function reportError(message, stream = process.stderr) {
30
37
  stream.write(`${formatErrorLine(message)}\n`);
31
38
  }
39
+ export function reportFailure(bin, error, stream = process.stderr) {
40
+ if (isAnticipatedFailure(error)) {
41
+ reportError(describeError(error), stream);
42
+ return;
43
+ }
44
+ reportCrash(bin, error, stream);
45
+ }
32
46
  export function reportTemplateUpdate(result, isDryRun, styles) {
33
47
  const style = styles?.stdout;
34
48
  switch (result.outcome) {
@@ -101,6 +115,11 @@ export function resolveStreamStyles(options) {
101
115
  function detectStreamStyle(stream) {
102
116
  return detectOutputStyle({ env: process.env, isTty: stream.isTTY === true });
103
117
  }
118
+ function extractStackFrames(stack) {
119
+ const lines = stack.split('\n');
120
+ const firstFrameIndex = lines.findIndex((line) => /^\s+at /.test(line));
121
+ return firstFrameIndex === -1 ? '' : lines.slice(firstFrameIndex).join('\n');
122
+ }
104
123
  function indentLines(text, indent) {
105
124
  return text
106
125
  .split('\n')
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@williamthorsen/nmr-core",
3
- "version": "0.14.0",
3
+ "version": "0.15.1",
4
4
  "private": false,
5
5
  "description": "Shared utilities for node-monorepo-tools packages",
6
6
  "keywords": [
@@ -49,8 +49,8 @@
49
49
  },
50
50
  "devDependencies": {
51
51
  "@williamthorsen/toolbelt.testing": "0.8.0",
52
- "@williamthorsen/toolbelt.vitest": "0.13.0",
53
- "vitest": "5.0.5"
52
+ "@williamthorsen/toolbelt.vitest": "0.13.1",
53
+ "vitest": "5.1.0"
54
54
  },
55
55
  "engines": {
56
56
  "node": ">=24.16.0"