@williamthorsen/nmr-core 0.3.2 → 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
@@ -4,7 +4,15 @@ Shared utilities for node-monorepo-tools packages.
4
4
 
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
- <!-- section:release-notes --><!-- /section:release-notes -->
7
+ <!-- section:release-notes -->
8
+ ## Release notes — v0.5.0 (2026-06-30)
9
+
10
+ ### 🎉 Features
11
+
12
+ - Reject unexpected positional arguments by default (#432)
13
+
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
+ <!-- /section:release-notes -->
8
16
 
9
17
  ## Installation
10
18
 
package/dist/esm/.cache CHANGED
@@ -1 +1 @@
1
- 1dc24071a091c2b879e7ff50fa75a058fc98715554757f75dc49184e781ea464
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.3.2",
3
+ "version": "0.5.0",
4
4
  "private": false,
5
5
  "description": "Shared utilities for node-monorepo-tools packages",
6
6
  "keywords": [