[RFC]: Bringing `minimist` Dependency In-House
維護者通常 1 天內回覆
還沒有人認領這個 Issue。
評估
- 難度
- 5/5
- 預估耗時
- 一週以上
- 新手友好度
- 55/100
- Issue 類型
- 功能
- 描述清晰度
- 描述清楚
- 活躍度
- 冷清
- 技術堆疊
- javascript, nodejs
研究方向
從提議的 @stdlib/cli/parse-args 結構及其進入點 lib/main.js 開始,接著檢查 @stdlib/cli/ctor/lib/main.js 和列出的 _tools 使用者。執行 parse-args、cli/ctor 以及端對端 CLI 驗證命令。完成的標準是:已涵蓋文件所述的 minimist 行為,使用者改用 stdlib 套件,並移除 minimist。
由索引模型根據 Issue 內容生成。
描述
Replace minimist Dependency with In-House @stdlib/cli/parse-args
Replace the third-party minimist dependency with a stdlib-native equivalent to reduce supply-chain security risk and bring all production code into conformance with stdlib conventions (docs, tests, examples, benchmarks, backward-compatibility).
Background
minimistis used exclusively as a command-line argument parser- Primary consumer: [
@stdlib/cli/ctor/lib/main.js]— the central CLI class used by every stdlib package with a CLI - Secondary consumers: ~12 internal tool scripts under
@stdlib/_tools/package-json/scripts/and@stdlib/_tools/modules/pkg-deps/bin/cli - The existing code has a [TODO comment]:
// TODO: replace with stdlib equivalent - The minimist source is 264 lines — straightforward to reimplement
API Surface Analysis
The full minimist API supports these options: boolean, string, alias, default, stopEarly, -- separator, unknown callback, and dotted key expansion.
What stdlib actually uses (confirmed by auditing every cli_opts.json and direct call site):
| Option | Used? | Example |
|---|---|---|
boolean |
✅ Yes | ["help", "version"] |
string |
✅ Yes | ["split", "aliases"] |
alias |
✅ Yes | { "help": ["h"], "version": ["V"] } |
default |
❌ No | — |
stopEarly |
❌ No | — |
unknown |
❌ No | — |
-- separator |
❌ No | — |
[!IMPORTANT]
Decision: Implement the full minimist API (all 7 options) for backward-compatibility and completeness, but prioritize testing the 3 options actually used. This ensures the replacement is a true drop-in and supports any future stdlib packages that might need additional options.
Proposed Changes
1. New Package: @stdlib/cli/parse-args
Create a brand-new stdlib package that reimplements minimist's parseArgs(args, opts) function.
Folder Structure
lib/node_modules/@stdlib/cli/parse-args/
├── package.json
├── README.md
├── lib/
│ ├── index.js # Standard stdlib entry point
│ └── main.js # Core argument parser implementation
├── test/
│ ├── test.js # Main export, basic parsing, type checks
│ ├── test.bool.js # boolean option, --no- prefix, allBools
│ ├── test.string.js # string option, number coercion suppression
│ ├── test.alias.js # alias option, bidirectional resolution
│ ├── test.default.js # default option
│ ├── test.long.js # Long flags (--key, --key=val, --key val)
│ ├── test.short.js # Short flags (-k, -abc, -k=val, -k val)
│ ├── test.dash.js # -- separator and opts['--']
│ ├── test.stop_early.js # stopEarly option
│ ├── test.unknown.js # unknown callback
│ ├── test.num.js # Number coercion
│ └── test.proto.js # Prototype pollution prevention
├── benchmark/
│ └── benchmark.js # Performance benchmarks
├── examples/
│ └── index.js # Runnable usage examples
└── docs/
└── types/
├── index.d.ts # TypeScript declarations
└── test.ts # TypeScript compile-time tests
main.js
Core implementation. The function signature:
function parseArgs( args, opts ) → { _: Array, ...flags }
Behavior to reimplement (in order of parsing priority):
--key=value— long flag with inline value--no-key— long flag negation → setskey: false--key value— long flag with next-arg value--key(boolean) — long boolean flag →true-abc— short flag grouping (each letter is a boolean flag)-k value— short flag with next-arg value-k=value— short flag with inline value--— stop parsing, rest goes to_(orargv['--'])- Positional args — everything else goes to
_ - Number coercion — numeric strings → Number (unless
stringoption set) - Alias expansion — set value on all aliases simultaneously
- Default values — apply defaults for keys not explicitly set
stopEarly— after first positional, everything goes to_unknowncallback — called for undefined flags; if returnsfalse, skip- Prototype pollution guard — reject
__proto__andconstructor
2. Update Consumer: @stdlib/cli/ctor
[MODIFY] @stdlib/cli/ctor/lib/main.js
Single-line change on line 25:
-var parseArgs = require( 'minimist' ); // TODO: replace with stdlib equivalent
+var parseArgs = require( '@stdlib/cli/parse-args' );
3. Update Consumers: Internal Tool Scripts
[MODIFY] 12 files under @stdlib/_tools/
Same single-line change in each file:
-var parseArgs = require( 'minimist' );
+var parseArgs = require( '@stdlib/cli/parse-args' );
Files to update:
_tools/modules/pkg-deps/bin/cli_tools/package-json/scripts/update_directories_tools/package-json/scripts/update_license_tools/package-json/scripts/update_engines_node_version_tools/package-json/scripts/update_homepage_tools/package-json/scripts/update_author_tools/package-json/scripts/update_os_tools/package-json/scripts/update_bugs_tools/package-json/scripts/update_contributors_tools/package-json/scripts/update_engines_npm_version_tools/package-json/scripts/update_gypfile_tools/package-json/scripts/update_repository
4. Remove minimist from Dependencies
npm uninstall minimist
Verification Plan
Automated Tests
-
New package unit tests (primary verification):
make TESTS_FILTER=".*/cli/parse-args/.*" -
Existing
@stdlib/cli/ctortests (regression — must continue passing after swap):make TESTS_FILTER=".*/cli/ctor/.*" -
Equivalence test — Run the existing minimist test suite against our implementation to verify behavioral parity:
# We can create a shim that points minimist's tests at our implementation NODE_PATH=lib/node_modules node -e "var parse = require('@stdlib/cli/parse-args'); console.log(JSON.stringify(parse(['--foo', 'bar', '-abc', '--no-debug', '--count=5'])))"
Manual Verification
- End-to-end CLI test — Run a real stdlib CLI command and verify it still works:
NODE_PATH=lib/node_modules node bin/cli is-leap-year 2024 # Expected: true NODE_PATH=lib/node_modules node bin/cli is-leap-year 2023 # Expected: false NODE_PATH=lib/node_modules node bin/cli --help # Expected: prints usage text NODE_PATH=lib/node_modules node bin/cli --version # Expected: prints version
- 主要語言
- JavaScript
- 星號
- 6k
- 分支
- 1.3k
- 平均合併
- 1 天 21 小時
- 30 天內合併 PR
- 224
環境準備
在瀏覽器裡用你自己的 GitHub 帳號啟動這個專案的開發容器。
- 沒有 Dockerfile 或 Docker Compose 檔案
- 有 Pull Request 範本
- 閱讀貢獻指南
從這裡開始
- 先讀完整個 Issue,再讀專案的貢獻指南。
- 在 Issue 下留言說明你要接手 —— 這能避免兩個人做同樣的事。
- Fork 儲存庫,在一個分支上完成修改。
- 送出 Pull Request,並在描述裡引用這個 Issue 編號。
stdlib-js/stdlib 的其他 Issue
-
難度 2/5 1-3 小時 新手友好度 72/100
stdlib-js/stdlib#16655 · 1 則留言 ·
維護者通常 1 天內回覆
-
Fix JavaScript lint errors可能已有人在做 @protestershankar 於 6 天前認領。 未關閉Good First Issue
難度 2/5 1-3 小時 新手友好度 82/100
stdlib-js/stdlib#16563 · 3 則留言 ·
維護者通常 1 天內回覆
-
Fix C lint errors可能已有人在做 @raus7n 於 14 天前認領。 未關閉Good First Issue
難度 1/5 1 小時以內 新手友好度 82/100
stdlib-js/stdlib#16454 · 1 則留言 ·
維護者通常 1 天內回覆
-
Fix JavaScript lint errors可能已有人在做 @Devansh-18155 於 39 天前認領。 未關閉Good First Issue
難度 1/5 1 小時以內 新手友好度 82/100
stdlib-js/stdlib#15970 · 1 則留言 ·
維護者通常 1 天內回覆
-
Fix JavaScript lint errors可能已有人在做 @lb1192176991-lab 於 44 天前認領。 未關閉Good First Issue
難度 1/5 1 小時以內 新手友好度 90/100
stdlib-js/stdlib#15831 · 2 則留言 ·
維護者通常 1 天內回覆
相似的 Issue
-
難度 1/5 1 小時以內 新手友好度 69/100
維護者通常 1 天內回覆
-
bug ready-for-agent
難度 2/5 1-3 小時 新手友好度 72/100
nearform/unbreakci#897 · 1 則留言 · 1 個 reaction ·
維護者通常 1 天內回覆
-
automation chore ci-cd consistency developer-experience difficulty: easy discoverability documentation enhancement github-actions good first issue help wanted hygiene priority: P3 seo shell yaml
難度 1/5 1 小時以內 新手友好度 76/100
-
bug
難度 2/5 1-3 小時 新手友好度 84/100
swc-project/swc-next-issues#394 ·
-
難度 1/5 1-3 小時 新手友好度 88/100
githubnext/gh-aw-workshop#5790 ·
維護者通常 1 天內回覆