001 — commander 2.20.3

{
  "system": {
    "id": "001-commander",
    "purpose": "Re-cut of one seam in commander 2.20.3: separate the parse decision from the effect on the host process.",
    "scope": "Only option and argument parsing plus error reporting. Subcommands, help generation, variadic arguments and executable subcommands are out of scope.",
    "non_goals": [
      "a replacement for commander",
      "feature parity with any version",
      "a claim that the original is badly written"
    ]
  },
  "capability_index": {
    "SMS": { "parse": "src/SMS/parse.js — returns {kind:'ok'|'error'}; performs no effect" },
    "SCL": { "host-policy": "src/SCL/host-policy.js — whether this parser may write to the host and whether it may exit" },
    "TMS": {
      "messages/en": "English rendering of a parse error",
      "messages/zh": "Traditional Chinese rendering of the same"
    },
    "DMS": { "trace": "src/DMS/trace.js — what the parse did, still inspectable after a rejection" }
  },
  "upstream_reference": {
    "project": "commander",
    "version_examined": "2.20.3",
    "license": "MIT",
    "process_exit_call_sites": 8,
    "escape_hatches_added_upstream": {
      "exitOverride": "4.0.0",
      "configureOutput": "7.0.0"
    }
  }
}

// SCL — what this parser is permitted to do to its host, and who decides.
//
// In commander 2.20.3 this layer does not exist. The permission to write to
// stderr and to terminate the process is taken unconditionally at eight call
// sites, and the calling program has no way to withhold it. That is the
// knowledge/permission fusion the method warns about: the library knows the
// input is malformed, but nothing granted it the right to end the process.
//
// Making the policy a value has an effect that is easy to miss: the same parser
// now works in a CLI, in a test, and inside a long-running process, without the
// parser knowing which one it is in.

export const EXIT_CODE = Object.freeze({ USAGE: 1, OK: 0 });

/** A CLI: report to stderr, then end the process. What commander 2.x hardcodes. */
export function cliPolicy({ write = (text) => process.stderr.write(text), exit = (code) => process.exit(code) } = {}) {
  return Object.freeze({
    name: "cli",
    mayWrite: true,
    mayExit: true,
    onError(message) {
      write(`error: ${message}\n`);
      exit(EXIT_CODE.USAGE);
    },
  });
}

/** A test or an embedded host: collect, never exit. */
export function collectingPolicy() {
  const written = [];
  return Object.freeze({
    name: "collecting",
    mayWrite: true,
    mayExit: false,
    written,
    onError(message) {
      written.push(message);
    },
  });
}

/** Silent: the caller intends to render the failure itself. */
export function silentPolicy() {
  return Object.freeze({
    name: "silent",
    mayWrite: false,
    mayExit: false,
    onError() {},
  });
}

// SMS — the parse itself. Returns a result; performs no effect.
//
// This is the whole re-cut. commander 2.20.3 writes:
//
//     Command.prototype.unknownOption = function(flag) {
//       if (this._allowUnknownOption) return;
//       console.error("error: unknown option `%s'", flag);
//       process.exit(1);
//     };
//
// Three lines, of which two act on the host process. The caller cannot decline
// either one. Here the same knowledge — "this flag is unknown" — becomes a value
// the caller receives and decides about.

/** @typedef {{kind: "ok", options: object, args: string[]}} Ok */
/** @typedef {{kind: "error", code: string, detail: object}} Err */

export const ERROR = Object.freeze({
  UNKNOWN_OPTION: "unknown_option",
  MISSING_OPTION_ARGUMENT: "missing_option_argument",
  MISSING_ARGUMENT: "missing_argument",
});

/**
 * @param {{flags: string, takesValue: boolean, name: string}[]} spec
 * @param {string[]} argv
 * @param {{allowUnknown?: boolean, required?: string[]}} [config]
 * @returns {Ok | Err}
 */
export function parse(spec, argv, config = {}) {
  const byFlag = new Map();
  for (const option of spec) {
    for (const flag of option.flags.split(",").map((f) => f.trim())) byFlag.set(flag, option);
  }

  const options = {};
  const args = [];

  for (let i = 0; i < argv.length; i += 1) {
    const token = argv[i];

    if (!token.startsWith("-")) {
      args.push(token);
      continue;
    }

    const option = byFlag.get(token);
    if (!option) {
      if (config.allowUnknown) {
        args.push(token);
        continue;
      }
      return { kind: "error", code: ERROR.UNKNOWN_OPTION, detail: { flag: token } };
    }

    if (!option.takesValue) {
      options[option.name] = true;
      continue;
    }

    const value = argv[i + 1];
    // An option that wants a value and is followed by another flag is missing
    // its argument — the same case commander reports then exits on.
    if (value === undefined || value.startsWith("-")) {
      return { kind: "error", code: ERROR.MISSING_OPTION_ARGUMENT, detail: { flags: option.flags, got: value ?? null } };
    }
    options[option.name] = value;
    i += 1;
  }

  for (const name of config.required ?? []) {
    if (!(name in options)) {
      return { kind: "error", code: ERROR.MISSING_ARGUMENT, detail: { name } };
    }
  }

  return { kind: "ok", options, args };
}

// TMS — one renderer for parse errors. Swappable, and unaware of any sibling.
//
// commander 2.20.3 embeds these strings at the point of failure, inside the same
// three lines that also write and exit. Pulling them into a TMS is what makes
// them translatable at all.

import { ERROR } from "../../SMS/parse.js";

export function englishMessages() {
  return Object.freeze({
    name: "en",
    render(result) {
      switch (result.code) {
        case ERROR.UNKNOWN_OPTION:
          return `unknown option \`${result.detail.flag}'`;
        case ERROR.MISSING_OPTION_ARGUMENT:
          return result.detail.got
            ? `option \`${result.detail.flags}' argument missing, got \`${result.detail.got}'`
            : `option \`${result.detail.flags}' argument missing`;
        case ERROR.MISSING_ARGUMENT:
          return `missing required argument \`${result.detail.name}'`;
        default:
          return `parse failed: ${result.code}`;
      }
    },
  });
}

// TMS — a second renderer, structurally parallel and unaware of the first.
//
// It exists to make the boundary real rather than theoretical: if the English
// renderer owned the phrasing, this file would have to import it, and the two
// would stop being separately loadable.

import { ERROR } from "../../SMS/parse.js";

export function chineseMessages() {
  return Object.freeze({
    name: "zh",
    render(result) {
      switch (result.code) {
        case ERROR.UNKNOWN_OPTION:
          return `無法辨識的選項 \`${result.detail.flag}'`;
        case ERROR.MISSING_OPTION_ARGUMENT:
          return result.detail.got
            ? `選項 \`${result.detail.flags}' 缺少參數，讀到的是 \`${result.detail.got}'`
            : `選項 \`${result.detail.flags}' 缺少參數`;
        case ERROR.MISSING_ARGUMENT:
          return `缺少必要參數 \`${result.detail.name}'`;
        default:
          return `解析失敗：${result.code}`;
      }
    },
  });
}

// DMS — what the parse did, separate from what it returned.
//
// commander 2.x has no equivalent. A failed parse ends the process, so there is
// nothing left to inspect: the exit code is the entire report.

export function createTrace() {
  const events = [];
  return {
    record(event, data = {}) { events.push({ event, ...data }); },
    events: () => [...events],
    humanView() {
      if (!events.length) return "Nothing recorded.";
      return events.map((e) => {
        if (e.event === "parse.ok") return `Parsed ${e.optionCount} option(s) and ${e.argCount} argument(s).`;
        if (e.event === "parse.error") return `Rejected: ${e.message}`;
        if (e.event === "policy.declined") return `Policy "${e.policy}" declined to ${e.action}.`;
        return e.event;
      }).join("\n");
    },
  };
}

// Island test. Run: node src/island-test.js
//
// The claim being tested is the one the re-cut exists for: the parser decides
// nothing about the host, and either message renderer works without the other.

import assert from "node:assert/strict";
import { parse, ERROR } from "./SMS/parse.js";
import { silentPolicy, collectingPolicy } from "./SCL/host-policy.js";
import { chineseMessages } from "./TMS/messages/zh.js";

let failures = 0;
function check(name, fn) {
  try {
    fn();
    console.log(`  [OK]   ${name}`);
  } catch (error) {
    failures += 1;
    console.log(`  [FAIL] ${name} — ${error.message}`);
  }
}

const SPEC = [
  { flags: "-p, --port", name: "port", takesValue: true },
  { flags: "-v, --verbose", name: "verbose", takesValue: false },
];

console.log("island test: SMS/parse alone, no policy and no renderer loaded");

check("a valid parse returns a value", () => {
  const r = parse(SPEC, ["--port", "8080", "build"]);
  assert.equal(r.kind, "ok");
  assert.deepEqual(r.options, { port: "8080" });
  assert.deepEqual(r.args, ["build"]);
});

check("an unknown option is data, not an exit", () => {
  const r = parse(SPEC, ["--porrt"]);
  assert.equal(r.kind, "error");
  assert.equal(r.code, ERROR.UNKNOWN_OPTION);
  assert.equal(r.detail.flag, "--porrt");
});

check("a missing option value is data, not an exit", () => {
  const r = parse(SPEC, ["--port", "--verbose"]);
  assert.equal(r.kind, "error");
  assert.equal(r.code, ERROR.MISSING_OPTION_ARGUMENT);
});

check("allowUnknown keeps the token instead of failing", () => {
  const r = parse(SPEC, ["--porrt"], { allowUnknown: true });
  assert.equal(r.kind, "ok");
  assert.deepEqual(r.args, ["--porrt"]);
});

check("parse touches no host global", () => {
  // If parse called process.exit the way commander does, this test file would
  // end here and the remaining checks would never print — which is exactly the
  // failure mode that makes the original hard to unit test.
  const original = process.exit;
  let called = false;
  process.exit = () => { called = true; };
  parse(SPEC, ["--porrt"]);
  parse(SPEC, ["--port"]);
  process.exit = original;
  assert.equal(called, false);
});

console.log("\nisland test: TMS/messages/zh alone, English renderer never imported");

check("the Chinese renderer works with no sibling loaded", () => {
  const r = parse(SPEC, ["--porrt"]);
  const text = chineseMessages().render(r);
  assert.match(text, /無法辨識的選項/);
});

check("a silent policy performs no effect at all", () => {
  const policy = silentPolicy();
  assert.equal(policy.mayWrite, false);
  assert.equal(policy.mayExit, false);
  policy.onError("anything");
});

check("a collecting policy captures instead of exiting", () => {
  const policy = collectingPolicy();
  policy.onError("unknown option `--porrt'");
  assert.equal(policy.written.length, 1);
  assert.equal(policy.mayExit, false);
});

console.log(failures ? `\n${failures} check(s) failed` : "\nall island checks passed");
process.exit(failures ? 1 : 0);

// The same three inputs, run under three different host policies.
//
// In commander 2.20.3 the first of these ends the process and the other two are
// not expressible.

import { parse } from "./SMS/parse.js";
import { cliPolicy, collectingPolicy, silentPolicy } from "./SCL/host-policy.js";
import { englishMessages } from "./TMS/messages/en.js";
import { chineseMessages } from "./TMS/messages/zh.js";
import { createTrace } from "./DMS/trace.js";

const SPEC = [
  { flags: "-p, --port", name: "port", takesValue: true },
  { flags: "-v, --verbose", name: "verbose", takesValue: false },
];

const CASES = [
  { label: "valid", argv: ["--port", "8080", "--verbose", "build"] },
  { label: "unknown option", argv: ["--porrt", "8080"] },
  { label: "option missing its value", argv: ["--port", "--verbose"] },
];

function run(policy, messages) {
  const trace = createTrace();
  const results = [];

  for (const testCase of CASES) {
    const result = parse(SPEC, testCase.argv, { required: [] });

    if (result.kind === "ok") {
      trace.record("parse.ok", { optionCount: Object.keys(result.options).length, argCount: result.args.length });
      results.push(`${testCase.label.padEnd(24)} ok    ${JSON.stringify(result.options)} args=${JSON.stringify(result.args)}`);
      continue;
    }

    const message = messages.render(result);
    trace.record("parse.error", { message });
    if (!policy.mayWrite) trace.record("policy.declined", { policy: policy.name, action: "write" });
    policy.onError(message);
    results.push(`${testCase.label.padEnd(24)} error ${result.code}`);
  }

  return { results, trace };
}

// A CLI policy that reports where the process would have died, rather than
// dying — so this file can demonstrate all three without ending early.
const wouldExit = [];
const reportingCli = cliPolicy({
  write: (text) => wouldExit.push(`stderr: ${text.trim()}`),
  exit: (code) => wouldExit.push(`process.exit(${code}) <- commander 2.20.3 stops here`),
});

for (const [policy, messages] of [
  [reportingCli, englishMessages()],
  [collectingPolicy(), chineseMessages()],
  [silentPolicy(), englishMessages()],
]) {
  console.log(`\n--- policy: ${policy.name} / messages: ${messages.name} ---`);
  const { results, trace } = run(policy, messages);
  for (const line of results) console.log(`  ${line}`);
  console.log("  DMS:");
  for (const line of trace.humanView().split("\n")) console.log(`    ${line}`);
  if (policy.name === "cli") for (const line of wouldExit) console.log(`    ${line}`);
  if (policy.written) for (const line of policy.written) console.log(`    collected: ${line}`);
}

console.log("\nSame parser, three hosts. The parse never decided whether to end the process.");