[RFC]: Bringing `minimist` Dependency In-House

未關閉
#11,080 2 則留言 0 個 reaction 已指派 0 人 在 GitHub 檢視

維護者通常 1 天內回覆

還沒有人認領這個 Issue。

評估

難度
5/5
預估耗時
一週以上
新手友好度
55/100
Issue 類型
功能
描述清晰度
描述清楚
活躍度
冷清
技術堆疊
javascript, nodejs
領域
cli, tooling

研究方向

從提議的 @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

  • minimist is 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):

  1. --key=value — long flag with inline value
  2. --no-key — long flag negation → sets key: false
  3. --key value — long flag with next-arg value
  4. --key (boolean) — long boolean flag → true
  5. -abc — short flag grouping (each letter is a boolean flag)
  6. -k value — short flag with next-arg value
  7. -k=value — short flag with inline value
  8. -- — stop parsing, rest goes to _ (or argv['--'])
  9. Positional args — everything else goes to _
  10. Number coercion — numeric strings → Number (unless string option set)
  11. Alias expansion — set value on all aliases simultaneously
  12. Default values — apply defaults for keys not explicitly set
  13. stopEarly — after first positional, everything goes to _
  14. unknown callback — called for undefined flags; if returns false, skip
  15. Prototype pollution guard — reject __proto__ and constructor
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
  1. New package unit tests (primary verification):

    make TESTS_FILTER=".*/cli/parse-args/.*"
    
  2. Existing @stdlib/cli/ctor tests (regression — must continue passing after swap):

        make TESTS_FILTER=".*/cli/ctor/.*"
    
  3. 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
  1. 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

環境準備

在 Codespaces 中開啟

在瀏覽器裡用你自己的 GitHub 帳號啟動這個專案的開發容器。

從這裡開始

  1. 先讀完整個 Issue,再讀專案的貢獻指南。
  2. 在 Issue 下留言說明你要接手 —— 這能避免兩個人做同樣的事。
  3. Fork 儲存庫,在一個分支上完成修改。
  4. 送出 Pull Request,並在描述裡引用這個 Issue 編號。

stdlib-js/stdlib 的其他 Issue

查看 stdlib-js/stdlib 的全部 Issue

相似的 Issue

更多 JavaScript Issue

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。