@williamthorsen/nmr-core 0.4.0 → 0.5.0

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.
package/README.md CHANGED
@@ -5,13 +5,13 @@ Shared utilities for node-monorepo-tools packages.
5
5
  This package serves as the shared library foundation for the monorepo. For the nmr CLI tool, see [`@williamthorsen/nmr`](../nmr).
6
6
 
7
7
  <!-- section:release-notes -->
8
- ## Release notes — v0.4.0 (2026-06-27)
8
+ ## Release notes — v0.5.0 (2026-06-30)
9
9
 
10
10
  ### 🎉 Features
11
11
 
12
- - Centralize the per-package build as an nmr-compile bin (#419)
12
+ - Reject unexpected positional arguments by default (#432)
13
13
 
14
- Introduces `nmr-compile`, a single command shipped with `@williamthorsen/nmr` that compiles each workspace package and now backs the default build. Consuming repos can delete their own per-package build script and pick up future build fixes just by upgrading nmr. Repeated builds with unchanged source now reliably skip recompiling instead of occasionally rebuilding for no reason, and import aliases now resolve correctly in symlinked checkouts.
14
+ Commands built on nmr-core now reject unexpected positional arguments by default. Commands that take positional arguments can opt back in to accept them.
15
15
  <!-- /section:release-notes -->
16
16
 
17
17
  ## Installation
package/dist/esm/.cache CHANGED
@@ -1 +1 @@
1
- 2a5f2011204cd14abe9e430e988f86878d4b990633d274860e093ee8af2d30ce
1
+ 013bcb628c595167bd8f50dc003360ccacb19b7c42d69ce5369dd4f6f7d65d58
@@ -1,8 +1,8 @@
1
1
  export declare const PACKAGE_NAME = "@williamthorsen/nmr-core";
2
2
  export { findPackageRoot } from './findPackageRoot.ts';
3
- export type { FlagDefinition, FlagSchema, ParsedArgs, ParsedFlags } from './parseArgs.ts';
4
- export { parseArgs, translateParseError } from './parseArgs.ts';
3
+ export type { FlagDefinition, FlagSchema, ParseArgsOptions, ParsedArgs, ParsedFlags, ParseErrorKind, } from './parseArgs.ts';
4
+ export { parseArgs, parseArgsOrExit, ParseError } from './parseArgs.ts';
5
5
  export { readPackageVersion } from './readPackageVersion.ts';
6
- export { printError, printSkip, printStep, printSuccess, reportWriteResult } from './terminal.ts';
6
+ export { formatErrorLine, printError, printSkip, printStep, printSuccess, reportError, reportWriteResult, } from './terminal.ts';
7
7
  export type { WriteOutcome, WriteResult } from './writeFileWithCheck.ts';
8
8
  export { writeFileWithCheck } from './writeFileWithCheck.ts';
package/dist/esm/index.js CHANGED
@@ -1,19 +1,30 @@
1
1
  const PACKAGE_NAME = "@williamthorsen/nmr-core";
2
2
  import { findPackageRoot } from "./findPackageRoot.js";
3
- import { parseArgs, translateParseError } from "./parseArgs.js";
3
+ import { parseArgs, parseArgsOrExit, ParseError } from "./parseArgs.js";
4
4
  import { readPackageVersion } from "./readPackageVersion.js";
5
- import { printError, printSkip, printStep, printSuccess, reportWriteResult } from "./terminal.js";
5
+ import {
6
+ formatErrorLine,
7
+ printError,
8
+ printSkip,
9
+ printStep,
10
+ printSuccess,
11
+ reportError,
12
+ reportWriteResult
13
+ } from "./terminal.js";
6
14
  import { writeFileWithCheck } from "./writeFileWithCheck.js";
7
15
  export {
8
16
  PACKAGE_NAME,
17
+ ParseError,
9
18
  findPackageRoot,
19
+ formatErrorLine,
10
20
  parseArgs,
21
+ parseArgsOrExit,
11
22
  printError,
12
23
  printSkip,
13
24
  printStep,
14
25
  printSuccess,
15
26
  readPackageVersion,
27
+ reportError,
16
28
  reportWriteResult,
17
- translateParseError,
18
29
  writeFileWithCheck
19
30
  };
@@ -11,5 +11,14 @@ export interface ParsedArgs<S extends FlagSchema> {
11
11
  flags: ParsedFlags<S>;
12
12
  positionals: string[];
13
13
  }
14
- export declare function parseArgs<S extends FlagSchema>(argv: string[], schema: S): ParsedArgs<S>;
15
- export declare function translateParseError(error: unknown): string;
14
+ export interface ParseArgsOptions {
15
+ allowPositionals?: boolean;
16
+ }
17
+ export type ParseErrorKind = 'unknown-flag' | 'missing-value' | 'unexpected-value' | 'unexpected-positional';
18
+ export declare class ParseError extends Error {
19
+ readonly kind: ParseErrorKind;
20
+ readonly flag: string;
21
+ constructor(kind: ParseErrorKind, flag: string);
22
+ }
23
+ export declare function parseArgs<S extends FlagSchema>(argv: string[], schema: S, options?: ParseArgsOptions): ParsedArgs<S>;
24
+ export declare function parseArgsOrExit<S extends FlagSchema>(argv: string[], schema: S, options?: ParseArgsOptions): ParsedArgs<S>;
@@ -1,93 +1,89 @@
1
- function handleEqualsForm(arg, eqIndex, longToKey, definitions) {
2
- const longFlag = arg.slice(0, eqIndex);
3
- const key = longToKey.get(longFlag);
4
- if (key === void 0) {
5
- throw new Error(`unknown flag '${longFlag}'`);
1
+ import process from "node:process";
2
+ import { parseArgs as nodeParseArgs } from "node:util";
3
+ import { reportError } from "./terminal.js";
4
+ class ParseError extends Error {
5
+ kind;
6
+ flag;
7
+ constructor(kind, flag) {
8
+ super(formatParseErrorMessage(kind, flag));
9
+ this.name = "ParseError";
10
+ this.kind = kind;
11
+ this.flag = flag;
6
12
  }
7
- const def = definitions.get(key);
8
- if (def?.type === "boolean") {
9
- throw new Error(`flag '${longFlag}' does not accept a value`);
10
- }
11
- const value = arg.slice(eqIndex + 1);
12
- if (value === "") {
13
- throw new Error(`${longFlag} requires a value`);
14
- }
15
- return { key, value };
16
- }
17
- function handleBareFlag(arg, index, argv, longToKey, shortToKey, definitions) {
18
- const key = longToKey.get(arg) ?? shortToKey.get(arg);
19
- if (key === void 0) {
20
- throw new Error(`unknown flag '${arg}'`);
21
- }
22
- const def = definitions.get(key);
23
- if (def?.type === "boolean") {
24
- return { key, value: true, advance: 0 };
25
- }
26
- const next = argv[index + 1];
27
- if (next === void 0 || next.startsWith("-") && next !== "-") {
28
- throw new Error(`${def?.long} requires a value`);
29
- }
30
- return { key, value: next, advance: 1 };
31
- }
32
- function buildLookupTables(schema) {
33
- const longToKey = /* @__PURE__ */ new Map();
34
- const shortToKey = /* @__PURE__ */ new Map();
35
- const definitions = /* @__PURE__ */ new Map();
36
- for (const [key, def] of Object.entries(schema)) {
37
- longToKey.set(def.long, key);
38
- definitions.set(key, def);
39
- if (def.short !== void 0) {
40
- shortToKey.set(def.short, key);
41
- }
42
- }
43
- return { longToKey, shortToKey, definitions };
44
13
  }
45
- function parseArgsInternal(argv, schema) {
46
- const { longToKey, shortToKey, definitions } = buildLookupTables(schema);
14
+ function parseArgs(argv, schema, options = {}) {
15
+ const nodeOptions = {};
16
+ const byName = /* @__PURE__ */ new Map();
47
17
  const flags = {};
48
18
  for (const [key, def] of Object.entries(schema)) {
19
+ const name = def.long.replace(/^--/, "");
20
+ nodeOptions[name] = def.short === void 0 ? { type: def.type } : { type: def.type, short: def.short.replace(/^-/, "") };
21
+ byName.set(name, { key, def });
49
22
  flags[key] = def.type === "boolean" ? false : void 0;
50
23
  }
24
+ const { tokens } = nodeParseArgs({
25
+ args: argv,
26
+ options: nodeOptions,
27
+ strict: false,
28
+ allowPositionals: true,
29
+ tokens: true
30
+ });
51
31
  const positionals = [];
52
- let pastDelimiter = false;
53
- for (let i = 0; i < argv.length; i++) {
54
- const arg = argv[i] ?? "";
55
- if (pastDelimiter) {
56
- positionals.push(arg);
32
+ for (const token of tokens) {
33
+ if (token.kind === "positional") {
34
+ if (options.allowPositionals !== true) {
35
+ throw new ParseError("unexpected-positional", token.value);
36
+ }
37
+ positionals.push(token.value);
57
38
  continue;
58
39
  }
59
- if (arg === "--") {
60
- pastDelimiter = true;
40
+ if (token.kind !== "option") {
61
41
  continue;
62
42
  }
63
- const eqIndex = arg.indexOf("=");
64
- if (eqIndex !== -1 && arg.startsWith("--")) {
65
- const { key, value } = handleEqualsForm(arg, eqIndex, longToKey, definitions);
66
- flags[key] = value;
67
- continue;
43
+ const entry = byName.get(token.name);
44
+ if (entry === void 0) {
45
+ throw new ParseError("unknown-flag", token.rawName);
68
46
  }
69
- if (arg.startsWith("-") && arg !== "-") {
70
- const { key, value, advance } = handleBareFlag(arg, i, argv, longToKey, shortToKey, definitions);
71
- flags[key] = value;
72
- i += advance;
47
+ if (entry.def.type === "boolean") {
48
+ if (token.value !== void 0) {
49
+ throw new ParseError("unexpected-value", token.rawName);
50
+ }
51
+ flags[entry.key] = true;
73
52
  continue;
74
53
  }
75
- positionals.push(arg);
54
+ const value = token.value;
55
+ if (value === void 0 || value === "" || !token.inlineValue && value.startsWith("-") && value !== "-") {
56
+ throw new ParseError("missing-value", token.rawName);
57
+ }
58
+ flags[entry.key] = value;
76
59
  }
77
60
  return { flags, positionals };
78
61
  }
79
- function parseArgs(argv, schema) {
80
- return parseArgsInternal(argv, schema);
62
+ function parseArgsOrExit(argv, schema, options = {}) {
63
+ try {
64
+ return parseArgs(argv, schema, options);
65
+ } catch (error) {
66
+ if (error instanceof ParseError) {
67
+ reportError(error.message);
68
+ process.exit(1);
69
+ }
70
+ throw error;
71
+ }
81
72
  }
82
- function translateParseError(error) {
83
- const message = error instanceof Error ? error.message : String(error);
84
- const flagMatch = message.match(/^unknown flag '(.+)'$/);
85
- if (flagMatch?.[1] !== void 0) {
86
- return `Unknown option: ${flagMatch[1]}`;
73
+ function formatParseErrorMessage(kind, flag) {
74
+ switch (kind) {
75
+ case "unknown-flag":
76
+ return `Unknown option: ${flag}`;
77
+ case "missing-value":
78
+ return `Missing value for option: ${flag}`;
79
+ case "unexpected-value":
80
+ return `Option does not accept a value: ${flag}`;
81
+ case "unexpected-positional":
82
+ return `Unexpected positional argument: ${flag}`;
87
83
  }
88
- return message;
89
84
  }
90
85
  export {
86
+ ParseError,
91
87
  parseArgs,
92
- translateParseError
88
+ parseArgsOrExit
93
89
  };
@@ -1,6 +1,9 @@
1
+ import type { Writable } from 'node:stream';
1
2
  import type { WriteResult } from './writeFileWithCheck.ts';
3
+ export declare function formatErrorLine(message: string): string;
4
+ export declare function printError(message: string): void;
5
+ export declare function printSkip(message: string): void;
2
6
  export declare function printStep(message: string): void;
3
7
  export declare function printSuccess(message: string): void;
4
- export declare function printSkip(message: string): void;
5
- export declare function printError(message: string): void;
8
+ export declare function reportError(message: string, stream?: Writable): void;
6
9
  export declare function reportWriteResult(result: WriteResult, dryRun: boolean): void;
@@ -1,3 +1,14 @@
1
+ import process from "node:process";
2
+ function formatErrorLine(message) {
3
+ return `Error: ${message}`;
4
+ }
5
+ function printError(message) {
6
+ process.stderr.write(` \u274C ${message}
7
+ `);
8
+ }
9
+ function printSkip(message) {
10
+ console.info(` \u26A0\uFE0F ${message}`);
11
+ }
1
12
  function printStep(message) {
2
13
  console.info(`
3
14
  > ${message}`);
@@ -5,11 +16,9 @@ function printStep(message) {
5
16
  function printSuccess(message) {
6
17
  console.info(` \u2705 ${message}`);
7
18
  }
8
- function printSkip(message) {
9
- console.info(` \u26A0\uFE0F ${message}`);
10
- }
11
- function printError(message) {
12
- console.error(` \u274C ${message}`);
19
+ function reportError(message, stream = process.stderr) {
20
+ stream.write(`${formatErrorLine(message)}
21
+ `);
13
22
  }
14
23
  function reportWriteResult(result, dryRun) {
15
24
  switch (result.outcome) {
@@ -47,9 +56,11 @@ function reportWriteResult(result, dryRun) {
47
56
  }
48
57
  }
49
58
  export {
59
+ formatErrorLine,
50
60
  printError,
51
61
  printSkip,
52
62
  printStep,
53
63
  printSuccess,
64
+ reportError,
54
65
  reportWriteResult
55
66
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@williamthorsen/nmr-core",
3
- "version": "0.4.0",
3
+ "version": "0.5.0",
4
4
  "private": false,
5
5
  "description": "Shared utilities for node-monorepo-tools packages",
6
6
  "keywords": [