browser-commander 0.16.1 → 0.17.1

package/tests/unit/scripts/command-stream-errexit.test.js

@@ -0,0 +1,132 @@
+/**
+ * Guard for the failure mode that made three release defects invisible.
+ *
+ * `command-stream` resolves its `$` promise on a non-zero exit code instead of
+ * rejecting, so the idiom every release script in this repository is written
+ * around —
+ *
+ *   try { await $`some-command`; } catch { process.exit(1); }
+ *
+ * — is dead code under the library's defaults. On 2026-09-05 that turned a
+ * crashed `changeset version` into a green JS release (run 33974450016) and a
+ * Rust release that never committed its version bump into a green Rust release
+ * (run 33974450069). See dev/log/issues/83/pulls/84/analysis/root-causes.md,
+ * RC-B and RC-C.
+ *
+ * `loadCommandStream()` is the single place every consumer obtains `$` from, so
+ * it is the single place the default can be corrected. These tests pin that:
+ * a non-zero exit must reject, and the rejection must carry the exit code so a
+ * caller can still branch on it.
+ *
+ * The tests need network access, because use-m is fetched from a CDN. When it
+ * is unreachable they skip, matching use-module-integration.test.js.
+ */
+
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import {
+  loadCommandStream,
+  USE_M_URL,
+} from '../../../../scripts/use-module.mjs';
+
+async function hasNetwork() {
+  try {
+    return (await fetch(USE_M_URL, { method: 'HEAD' })).ok;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Load command-stream, or a reason to skip.
+ * @param {import('node:test').TestContext} t
+ * @returns {Promise<Record<string, any> | null>}
+ */
+async function load(t) {
+  if (process.platform === 'win32') {
+    // Same upstream limitation use-module-integration.test.js documents:
+    // use-m imports the resolved file by absolute path, which the Windows ESM
+    // loader rejects. The Linux and macOS runs cover this.
+    t.skip('use-m cannot import absolute paths on Windows');
+    return null;
+  }
+  if (!(await hasNetwork())) {
+    t.skip(`${USE_M_URL} is unreachable, so use-m cannot be evaluated`);
+    return null;
+  }
+  try {
+    return await loadCommandStream();
+  } catch (error) {
+    if (
+      /fetch|network|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|registry/i.test(
+        error.message
+      )
+    ) {
+      t.skip(error.message);
+      return null;
+    }
+    throw error;
+  }
+}
+
+describe('loadCommandStream makes a failed command fail', () => {
+  it('turns errexit on, so the release scripts catch what they try to catch', async (t) => {
+    const cs = await load(t);
+    if (!cs) {
+      return;
+    }
+
+    assert.equal(
+      cs.shell.settings().errexit,
+      true,
+      'errexit must be enabled by loadCommandStream; with the library default ' +
+        'of false, every try/catch around $ in the release scripts is unreachable'
+    );
+  });
+
+  it('rejects on a non-zero exit and reports the exit code', async (t) => {
+    const cs = await load(t);
+    if (!cs) {
+      return;
+    }
+    const { $ } = cs;
+
+    await assert.rejects(
+      () => $`exit 7`,
+      (error) => {
+        assert.equal(error.code, 7, 'the exit code must survive on the error');
+        return true;
+      },
+      'a command exiting 7 must reject, not resolve'
+    );
+  });
+
+  it('still resolves with stdout on success', async (t) => {
+    const cs = await load(t);
+    if (!cs) {
+      return;
+    }
+    const { $ } = cs;
+
+    // errexit must not turn every command into a throw: the success path is
+    // what the release scripts read version numbers and git status out of.
+    const result = await $`echo errexit-ok`;
+    assert.match(String(result.stdout), /errexit-ok/);
+  });
+
+  it('reports a non-zero exit for the exact command that broke the Rust release', async (t) => {
+    const cs = await load(t);
+    if (!cs) {
+      return;
+    }
+    const { $ } = cs;
+
+    // `git diff --cached --quiet` exits 1 when there ARE staged changes.
+    // rust/scripts/version-and-commit.mjs relied on that becoming a rejection
+    // and, because it did not, reported "No changes to commit" after staging
+    // two modified files. `false` stands in for it here so the test needs no
+    // git fixture; the contract under test is identical.
+    await assert.rejects(() => $`false`, 'a command exiting 1 must reject');
+  });
+});

package/tests/unit/scripts/debug-print.test.js

@@ -0,0 +1,67 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import {
+  debugWith,
+  formatDebugLines,
+  isDebugEnabled,
+  readEnvVar,
+} from '../../../../scripts/debug-print.mjs';
+
+describe('debug-print', () => {
+  it('stays off by default so release logs are not noisy', () => {
+    assert.equal(isDebugEnabled({}), false);
+    assert.equal(isDebugEnabled({ CI_SCRIPTS_DEBUG: '0' }), false);
+    assert.equal(isDebugEnabled({ CI_SCRIPTS_DEBUG: '' }), false);
+  });
+
+  it('turns on through the local toggle or either Actions debug switch', () => {
+    assert.equal(isDebugEnabled({ CI_SCRIPTS_DEBUG: '1' }), true);
+    assert.equal(isDebugEnabled({ CI_SCRIPTS_DEBUG: 'true' }), true);
+    assert.equal(isDebugEnabled({ RUNNER_DEBUG: '1' }), true);
+    assert.equal(isDebugEnabled({ ACTIONS_STEP_DEBUG: 'true' }), true);
+  });
+
+  it('prefixes every line so Actions renders it in the debug stream', () => {
+    assert.deepEqual(formatDebugLines(['a\nb']), ['::debug::a', '::debug::b']);
+    assert.deepEqual(formatDebugLines(['keys', { a: 1 }]), [
+      '::debug::keys {',
+      '::debug::  "a": 1',
+      '::debug::}',
+    ]);
+  });
+
+  it('prints nothing when debug output is off', () => {
+    const printed = [];
+    assert.deepEqual(
+      debugWith({ env: {}, log: (l) => printed.push(l) }, 'x'),
+      []
+    );
+    assert.deepEqual(printed, []);
+  });
+
+  it('prints through the injected logger when debug output is on', () => {
+    const printed = [];
+    debugWith(
+      { env: { CI_SCRIPTS_DEBUG: '1' }, log: (line) => printed.push(line) },
+      'loaded',
+      { keys: ['default'] }
+    );
+    assert.equal(printed[0], '::debug::loaded {');
+  });
+
+  it('treats an unreadable environment as unset instead of throwing', () => {
+    // Deno raises NotCapable on the property read when --allow-env is absent;
+    // tracing must never be the reason a script fails.
+    const hostile = new Proxy(
+      {},
+      {
+        get() {
+          throw new Error('NotCapable');
+        },
+      }
+    );
+    assert.equal(readEnvVar('CI_SCRIPTS_DEBUG', hostile), undefined);
+    assert.equal(isDebugEnabled(hostile), false);
+  });
+});

package/tests/unit/scripts/jscpd-config.test.js

@@ -0,0 +1,141 @@
+/**
+ * Guard against a duplication gate that reports success without reading code.
+ *
+ * `.jscpd.json` used to set `"format": "console"`, but jscpd's `format` selects
+ * the *file formats* to scan, not the reporter. No file has the extension
+ * `console`, so `npm run check:duplication` analysed 0 files, found 0 clones and
+ * exited 0 for every commit - a green check that proved nothing. The static
+ * assertions below pin the keys that caused it; the end-to-end run proves the
+ * shipped config still reaches a real file.
+ */
+
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import {
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { describe, it } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const JS_ROOT = path.resolve(
+  fileURLToPath(new URL('.', import.meta.url)),
+  '../../..'
+);
+const CONFIG_PATH = path.join(JS_ROOT, '.jscpd.json');
+const JSCPD_PACKAGE = path.join(JS_ROOT, 'node_modules', 'jscpd');
+
+/**
+ * Resolve jscpd's CLI entry point, not its `node_modules/.bin` shim.
+ *
+ * On Windows npm writes three shims - `jscpd`, `jscpd.cmd` and `jscpd.ps1` -
+ * and the extensionless one is a Bourne script that `CreateProcess` cannot
+ * execute, so `execFileSync(.bin/jscpd)` fails with ENOENT there while working
+ * on Linux and macOS. Reading `bin.jscpd` out of the package manifest gives the
+ * same file npm links to, on every platform, and survives an upstream rename.
+ */
+function resolveJscpdCli() {
+  const manifest = path.join(JSCPD_PACKAGE, 'package.json');
+  if (!existsSync(manifest)) {
+    return null;
+  }
+  const { bin } = JSON.parse(readFileSync(manifest, 'utf-8'));
+  const entry = typeof bin === 'string' ? bin : bin?.jscpd;
+  if (!entry) {
+    return null;
+  }
+  const cli = path.join(JSCPD_PACKAGE, entry);
+  return existsSync(cli) ? cli : null;
+}
+
+const config = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8'));
+
+describe('.jscpd.json', () => {
+  it('does not restrict the scan to a format named after a reporter', () => {
+    // `format` is a comma-separated list of jscpd language ids ("javascript",
+    // "markup", ...). Naming a reporter there silently matches nothing.
+    assert.equal(
+      config.format,
+      undefined,
+      '`format` filters which file types are scanned; use `reporters` instead'
+    );
+  });
+
+  it('selects reporters through the `reporters` array', () => {
+    assert.ok(Array.isArray(config.reporters), '`reporters` must be an array');
+    assert.ok(
+      config.reporters.includes('console'),
+      'console output is what makes a failing run readable in CI logs'
+    );
+  });
+
+  it('asks to ignore comments through `mode`, not an unknown key', () => {
+    // jscpd warns "unknown field 'skipComments'" and carries on; `mode: weak`
+    // is the supported spelling of the same intent.
+    assert.equal(config.skipComments, undefined);
+    assert.equal(config.mode, 'weak');
+  });
+});
+
+describe('the shipped jscpd config scans real files', () => {
+  it('reports at least one analysed source for a one-file project', (t) => {
+    const jscpdCli = resolveJscpdCli();
+    if (!jscpdCli) {
+      return t.skip(
+        `jscpd is not installed under ${JSCPD_PACKAGE}; run npm ci in js/`
+      );
+    }
+
+    const fixture = mkdtempSync(path.join(tmpdir(), 'jscpd-config-'));
+    try {
+      // jscpd reads `.jscpd.json` from the directory it is invoked in, so the
+      // fixture gets a copy of the real config rather than a --config path.
+      writeFileSync(
+        path.join(fixture, '.jscpd.json'),
+        readFileSync(CONFIG_PATH)
+      );
+      writeFileSync(
+        path.join(fixture, 'sample.js'),
+        [
+          'export function sample(value) {',
+          '  return value + 1;',
+          '}',
+          '',
+        ].join('\n')
+      );
+
+      const output = path.join(fixture, 'report');
+      execFileSync(
+        process.execPath,
+        [
+          jscpdCli,
+          '.',
+          '--reporters',
+          'json',
+          '--output',
+          output,
+          '--no-colors',
+        ],
+        {
+          cwd: fixture,
+          stdio: 'pipe',
+        }
+      );
+
+      const report = JSON.parse(
+        readFileSync(path.join(output, 'jscpd-report.json'), 'utf-8')
+      );
+      assert.ok(
+        report.statistics.total.sources > 0,
+        `jscpd analysed ${report.statistics.total.sources} files; the config excludes everything`
+      );
+    } finally {
+      rmSync(fixture, { recursive: true, force: true });
+    }
+  });
+});

package/tests/unit/scripts/pre-commit-config.test.js

@@ -0,0 +1,214 @@
+/**
+ * The local quality gate has to be the same gate CI uses.
+ *
+ * Before this test the repository claimed pre-commit hooks through husky:
+ * `js/package.json` ran `"prepare": "husky || true"`, husky refused with
+ * `.git can't be found` because npm runs `prepare` inside `js/`, and `|| true`
+ * threw the refusal away. `git config --get core.hooksPath` stayed empty, so
+ * `js/.husky/pre-commit` never ran for anyone - the same shape of failure as the
+ * `|| true` that once hid a Prettier error in the release job.
+ *
+ * The replacement is a repository-root `.pre-commit-config.yaml` whose local
+ * hooks run the exact commands the workflows run. The assertions below pin that
+ * correspondence: change a lint command in a workflow without changing the hook
+ * (or the other way round) and this test fails.
+ */
+
+import assert from 'node:assert/strict';
+import { existsSync, readFileSync } from 'node:fs';
+import { describe, it } from 'node:test';
+
+import {
+  normalizeNewlines,
+  readRepoText,
+  repoPath,
+} from '../../helpers/repo.js';
+
+/**
+ * Every local hook, mapped to the workflow step it has to mirror.
+ *
+ * `command` is matched twice: it must appear inside the hook's `entry`, and the
+ * workflow must contain a `run:` step that is exactly that command.
+ */
+const MIRRORED_COMMANDS = [
+  { id: 'js-eslint', workflow: 'js.yml', command: 'npm run lint' },
+  { id: 'js-prettier', workflow: 'js.yml', command: 'npm run format:check' },
+  {
+    id: 'js-duplication',
+    workflow: 'js.yml',
+    command: 'npm run check:duplication',
+  },
+  { id: 'python-ruff', workflow: 'python.yml', command: 'ruff check .' },
+  {
+    id: 'python-ruff-format',
+    workflow: 'python.yml',
+    command: 'ruff format --check .',
+  },
+  { id: 'python-mypy', workflow: 'python.yml', command: 'mypy src' },
+  {
+    id: 'python-mypy-scripts',
+    workflow: 'python.yml',
+    command: 'mypy --python-version 3.13 scripts tests/unit/scripts',
+  },
+  {
+    id: 'rust-fmt',
+    workflow: 'rust.yml',
+    command: 'cargo fmt --all -- --check',
+  },
+  {
+    id: 'rust-clippy',
+    workflow: 'rust.yml',
+    command: 'cargo clippy --all-targets --all-features',
+  },
+  {
+    id: 'file-line-limits',
+    workflow: 'quality.yml',
+    command: 'bash scripts/check-file-line-limits.sh',
+  },
+  {
+    id: 'shared-fingerprint-assets',
+    workflow: 'quality.yml',
+    command: 'bash scripts/check-shared-fingerprint-assets.sh',
+  },
+  {
+    id: 'required-docs',
+    workflow: 'quality.yml',
+    command: 'bash scripts/check-required-docs.sh',
+  },
+  {
+    id: 'repo-scripts-lint',
+    workflow: 'quality.yml',
+    command:
+      'node js/node_modules/eslint/bin/eslint.js scripts experiments rust/scripts',
+  },
+  {
+    id: 'ci-workflow-policy',
+    workflow: 'ci-policy.yml',
+    command: 'node scripts/check-ci-workflows.mjs',
+  },
+];
+
+/**
+ * Collect the `repo: local` hooks as `id -> lines of that hook`.
+ *
+ * A regex reader rather than a YAML parser, for the same reason
+ * `scripts/check-ci-workflows.mjs` uses one: this repository ships no YAML
+ * dependency, and a policy check that needs one is a policy check that stops
+ * being run.
+ *
+ * @param {string} text - contents of .pre-commit-config.yaml
+ * @returns {Map<string, string[]>}
+ */
+function readLocalHooks(text) {
+  const localSection = text.slice(text.indexOf('- repo: local'));
+  const hooks = new Map();
+  let current = null;
+
+  for (const line of localSection.split(/\r?\n/)) {
+    const id = line.match(/^\s*-\s+id:\s+(\S+)/);
+    if (id) {
+      current = [];
+      hooks.set(id[1], current);
+      continue;
+    }
+    if (current) {
+      current.push(line);
+    }
+  }
+  return hooks;
+}
+
+/**
+ * @param {string[]} lines - the lines of one hook
+ * @returns {string} the hook's `entry` value
+ */
+function entryOf(lines) {
+  const entry = lines.find((line) => /^\s*entry:\s/.test(line));
+  return entry ? entry.replace(/^\s*entry:\s+/, '').trim() : '';
+}
+
+const localHooks = readLocalHooks(readRepoText('.pre-commit-config.yaml'));
+
+const workflow = (name) => readRepoText('.github', 'workflows', name);
+
+describe('local hooks run the commands CI runs', () => {
+  for (const { id, workflow: file, command } of MIRRORED_COMMANDS) {
+    it(`${id} runs \`${command}\`, the same as ${file}`, () => {
+      const lines = localHooks.get(id);
+      assert.ok(lines, `no \`${id}\` hook in .pre-commit-config.yaml`);
+      assert.ok(
+        entryOf(lines).includes(command),
+        `${id} must run \`${command}\`; its entry is \`${entryOf(lines)}\``
+      );
+      assert.ok(
+        workflow(file).includes(`run: ${command}\n`),
+        `${file} no longer has a step running \`${command}\`; the hook and the workflow have drifted apart`
+      );
+    });
+  }
+
+  it('reads a workflow checked out with Windows line endings', () => {
+    // The twelve assertions above match `run: <command>\n`. On windows-latest
+    // git checks the repository out with CRLF endings, so every one of them
+    // failed there while passing on Linux - run 33963736349, twelve failures,
+    // none of them a real drift. Reading through readRepoText() is what makes
+    // the assertion about this repository rather than about the runner.
+    const crlfWorkflow = normalizeNewlines(
+      workflow('js.yml').replaceAll('\n', '\r\n')
+    );
+
+    assert.ok(crlfWorkflow.includes('run: npm run lint\n'));
+  });
+
+  it('leaves no local hook unpinned', () => {
+    const pinned = new Set(MIRRORED_COMMANDS.map((m) => m.id));
+    const unpinned = [...localHooks.keys()].filter((id) => !pinned.has(id));
+    assert.deepEqual(
+      unpinned,
+      [],
+      'every local hook must be listed in MIRRORED_COMMANDS so it cannot drift from CI'
+    );
+  });
+
+  it('never lets pre-commit append filenames to a `bash -c` entry', () => {
+    // `bash -c 'cmd' a.js b.js` passes the files as $0/$1, which bash ignores:
+    // the hook would keep passing while checking something else entirely.
+    for (const [id, lines] of localHooks) {
+      assert.ok(
+        lines.some((line) => /^\s*pass_filenames:\s+false\s*$/.test(line)),
+        `${id} must set pass_filenames: false`
+      );
+    }
+  });
+
+  it('gives clippy the flag that makes a warning fatal in CI', () => {
+    // rust.yml sets RUSTFLAGS at workflow level, which is the only reason
+    // `cargo clippy` without `-D warnings` is a real gate there.
+    assert.ok(entryOf(localHooks.get('rust-clippy')).includes('-Dwarnings'));
+    assert.ok(workflow('rust.yml').includes('RUSTFLAGS: -Dwarnings'));
+  });
+});
+
+describe('the previous hook wiring is gone', () => {
+  const manifest = JSON.parse(
+    readFileSync(repoPath('js', 'package.json'), 'utf-8')
+  );
+
+  it('installs no git hook through a masked command', () => {
+    for (const [name, command] of Object.entries(manifest.scripts)) {
+      assert.ok(
+        !/\|\|\s*true\s*$/.test(command),
+        `npm script \`${name}\` ends in \`|| true\`, which hides its own failure`
+      );
+    }
+  });
+
+  it('keeps no husky wiring that cannot reach .git from js/', () => {
+    // husky refuses any path containing `..` and requires `.git` in the working
+    // directory, so it cannot manage a repository-root hook from this package.
+    assert.equal(manifest.devDependencies.husky, undefined);
+    assert.equal(manifest.devDependencies['lint-staged'], undefined);
+    assert.equal(manifest['lint-staged'], undefined);
+    assert.ok(!existsSync(repoPath('js', '.husky')));
+  });
+});