browser-commander 0.17.0 → 0.17.2

package/tests/unit/scripts/changeset-formatter.test.js

@@ -0,0 +1,108 @@
+/**
+ * Guard for RC-G: `changeset version` aborting on a formatter that is not
+ * installed.
+ *
+ * @changesets/cli v3 formats the changelog it writes. With the default
+ * `"format": "auto"`, @changesets/format walks `defaultDetectOrder` --
+ * dprint, deno, oxfmt, biome, prettier -- and picks the first formatter whose
+ * config file it finds. `js/deno.json` existed -- orphaned configuration no
+ * workflow ever used -- so deno won over the prettier this package actually
+ * depends on. deno is the one entry in that table with
+ * no `packageName`, so it is spawned straight off PATH with no existence
+ * check and no npx fallback; GitHub's ubuntu-latest runner has no deno.
+ *
+ * `changeset version` therefore bumped package.json, wrote CHANGELOG.md, and
+ * then died with `spawn deno ENOENT` before deleting the changeset it had
+ * just consumed. The release still shipped -- 0.17.0 is on npm -- but
+ * `merged-loud-river.md` survived to be released a second time, and the
+ * half-written CHANGELOG.md kept trailing whitespace that fails
+ * `prettier --check`.
+ *
+ * Reproduction: experiments/ci-repro/repro-changeset-deno-formatter.mjs
+ * Analysis: dev/log/issues/83/pulls/84/analysis/root-causes.md, RC-G
+ */
+
+import assert from 'node:assert/strict';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, it } from 'node:test';
+
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), '../../..');
+const require = createRequire(import.meta.url);
+
+const config = JSON.parse(
+  readFileSync(join(packageRoot, '.changeset/config.json'), 'utf-8')
+);
+
+describe('changesets formatter', () => {
+  it('pins a formatter instead of auto-detecting one', () => {
+    assert.notEqual(
+      config.format,
+      undefined,
+      'omitting `format` means "auto", which detects whichever formatter ' +
+        'config happens to sit beside package.json and then fails on a ' +
+        'runner that has no such binary'
+    );
+    assert.notEqual(config.format, 'auto', 'same as omitting it');
+  });
+
+  it('pins a formatter this package can actually run', () => {
+    // `false` disables formatting, which is also a safe answer.
+    if (config.format === false) {
+      return;
+    }
+
+    const { defaultDetectOrder } = require('@changesets/format');
+    assert.ok(
+      defaultDetectOrder.includes(config.format),
+      `unknown formatter ${JSON.stringify(config.format)}; expected one of ${defaultDetectOrder.join(
+        ', '
+      )}`
+    );
+
+    // @changesets/format keeps the formatter table private, so mirror the
+    // one fact this test needs: which formatters it resolves through
+    // node_modules and which it spawns straight off PATH. `deno` is the
+    // single entry with no package, which is why it cannot be relied on.
+    const packageNames = {
+      dprint: 'dprint',
+      deno: null,
+      oxfmt: 'oxfmt',
+      biome: '@biomejs/biome',
+      prettier: 'prettier',
+    };
+    const packageName = packageNames[config.format];
+    assert.ok(
+      packageName,
+      `${config.format} is spawned straight off PATH with no npx fallback, ` +
+        'so it cannot be relied on inside a release job'
+    );
+    assert.ok(
+      existsSync(join(packageRoot, 'node_modules', packageName)),
+      `${packageName} is not installed in this package`
+    );
+  });
+
+  it('leaves no consumed changeset behind', () => {
+    const changesetDir = join(packageRoot, '.changeset');
+    const pending = readdirSync(changesetDir).filter(
+      (file) => file.endsWith('.md') && file !== 'README.md'
+    );
+
+    const changelog = readFileSync(join(packageRoot, 'CHANGELOG.md'), 'utf-8');
+    for (const file of pending) {
+      const body = readFileSync(join(changesetDir, file), 'utf-8')
+        .replace(/^---\s*\n[\s\S]*?\n---\s*\n/, '')
+        .trim();
+      const firstLine = body.split('\n')[0].trim();
+      assert.ok(
+        firstLine.length === 0 || !changelog.includes(firstLine),
+        `.changeset/${file} describes a change that CHANGELOG.md already ` +
+          'records as released; `changeset version` consumed it but did not ' +
+          'delete it, so the next release will publish it again'
+      );
+    }
+  });
+});

package/tests/unit/scripts/check-release-format.test.js

@@ -0,0 +1,134 @@
+/**
+ * Guard for RC-E: the release commit that no workflow run ever checks.
+ *
+ * `version-and-commit.mjs` pushes the bump with `GITHUB_TOKEN`, and a push
+ * authenticated with `GITHUB_TOKEN` does not start a workflow run. When
+ * `changeset version` wrote a CHANGELOG.md that Prettier rejects, main's
+ * `format:check` went red and stayed red: the runs that could have reported it
+ * were exactly the ones the push never triggered.
+ *
+ * Analysis: dev/log/issues/83/pulls/84/analysis/root-causes.md, RC-E
+ */
+
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, it } from 'node:test';
+
+import {
+  FORMAT_CHECK_COMMAND,
+  assertGeneratedFilesAreFormatted,
+  formatFailureAnnotation,
+  formatFailureDetails,
+} from '../../../scripts/check-release-format.mjs';
+
+const jsRoot = join(dirname(fileURLToPath(import.meta.url)), '../../..');
+
+/** @returns {{log: (m: string) => void, error: (m: string) => void, lines: string[], errors: string[]}} */
+function recorder() {
+  const lines = [];
+  const errors = [];
+  return {
+    lines,
+    errors,
+    log: (message) => lines.push(String(message)),
+    error: (message) => errors.push(String(message)),
+  };
+}
+
+describe('release commit formatting gate', () => {
+  it('lets a formatted release commit through', async () => {
+    const console_ = recorder();
+    let ran = 0;
+
+    await assertGeneratedFilesAreFormatted(async () => {
+      ran += 1;
+    }, console_);
+
+    assert.equal(ran, 1);
+    assert.equal(console_.errors.length, 0);
+    assert.ok(console_.lines.some((line) => line.includes('is formatted')));
+  });
+
+  it('stops the release when the generated files fail the gate', async () => {
+    const console_ = recorder();
+    const failure = Object.assign(
+      new Error('Command failed with exit code 1'),
+      { stdout: '[warn] CHANGELOG.md\n', stderr: '' }
+    );
+
+    await assert.rejects(
+      assertGeneratedFilesAreFormatted(async () => {
+        throw failure;
+      }, console_),
+      // Rethrown unchanged: the caller's catch reports it and exits non-zero,
+      // so the push never happens.
+      (error) => error === failure
+    );
+
+    assert.ok(console_.errors[0].startsWith('::error title='));
+    assert.ok(console_.errors.includes('[warn] CHANGELOG.md'));
+  });
+
+  it('keeps the annotation on one line', () => {
+    // A workflow command ends at the first newline; anything after it is
+    // printed as plain log text and never becomes an annotation.
+    assert.ok(!formatFailureAnnotation().includes('\n'));
+    assert.ok(formatFailureAnnotation().startsWith('::error title='));
+  });
+
+  it('reads the reason out of the captured streams, not the message', () => {
+    // With errexit on, `error.message` is only "Command failed with exit code
+    // N". A call site that reported `message` would say nothing useful.
+    const details = formatFailureDetails({
+      message: 'Command failed with exit code 1',
+      stdout: '  [warn] CHANGELOG.md  ',
+      stderr: 'prettier: not found',
+    });
+
+    assert.equal(details, '[warn] CHANGELOG.md\nprettier: not found');
+    assert.equal(formatFailureDetails(new Error('boom')), '');
+    assert.equal(formatFailureDetails(undefined), '');
+  });
+
+  it('runs the same gate the lint job runs', () => {
+    // A gate that drifts from the one CI uses would pass here and fail there.
+    const workflow = readFileSync(
+      join(jsRoot, '../.github/workflows/js.yml'),
+      'utf8'
+    );
+    assert.ok(
+      workflow.includes(`run: ${FORMAT_CHECK_COMMAND}`),
+      `${FORMAT_CHECK_COMMAND} is no longer the workflow's formatting gate`
+    );
+
+    const script = readFileSync(
+      join(jsRoot, 'scripts/version-and-commit.mjs'),
+      'utf8'
+    );
+    assert.ok(
+      script.includes(FORMAT_CHECK_COMMAND),
+      'version-and-commit.mjs must run the same command it documents'
+    );
+  });
+
+  it('checks before it commits, not after it pushes', () => {
+    const script = readFileSync(
+      join(jsRoot, 'scripts/version-and-commit.mjs'),
+      'utf8'
+    );
+    const check = script.indexOf('assertGeneratedFilesAreFormatted(() =>');
+    const commit = script.indexOf('git commit');
+    // The raw `git push origin main` this used to look for is now
+    // pushWithRebaseRetry, which rebases when another release wrote to main
+    // first. See dev/log/issues/85/pulls/86/analysis/root-causes.md (RC-1).
+    const push = script.indexOf('pushWithRebaseRetry({');
+
+    assert.ok(check > 0 && commit > 0 && push > 0);
+    assert.ok(
+      check < commit && check < push,
+      'a check that runs after the push cannot stop a bad release commit'
+    );
+  });
+});

package/tests/unit/scripts/ci-workflow-policy.test.js

@@ -260,3 +260,106 @@ jobs:
     });
   });
 });
+
+/**
+ * Build a two-job workflow whose `test` job varies only in how it relates to
+ * `lint`, so the fast-fail rule is the only thing a failure count can mean.
+ *
+ * @param {{needs: string, condition?: string}} parts
+ * @returns {string}
+ */
+function lintAndTest({ needs, condition = '' }) {
+  return [
+    'name: Test',
+    'on: push',
+    'permissions:',
+    '  contents: read',
+    'env:',
+    '  GIT_CONFIG_KEY_0: init.defaultBranch',
+    'jobs:',
+    '  lint:',
+    '    runs-on: ubuntu-latest',
+    '    timeout-minutes: 5',
+    '    concurrency:',
+    '      group: ${{ github.workflow }}-${{ github.ref }}-lint',
+    '      cancel-in-progress: true',
+    '    steps:',
+    '      - uses: actions/checkout@v6',
+    '  test:',
+    '    runs-on: ubuntu-latest',
+    '    timeout-minutes: 5',
+    '    concurrency:',
+    '      group: ${{ github.workflow }}-${{ github.ref }}-test',
+    '      cancel-in-progress: true',
+    `    needs: [${needs}]`,
+    condition,
+    '    steps:',
+    '      - uses: actions/checkout@v6',
+    '  pipeline-status:',
+    '    runs-on: ubuntu-latest',
+    '    timeout-minutes: 5',
+    '    concurrency:',
+    '      group: ${{ github.workflow }}-${{ github.ref }}-pipeline-status',
+    '      cancel-in-progress: true',
+    '    needs: [lint, test]',
+    '    steps:',
+    '      - run: bash scripts/check-pipeline-status.sh',
+    '',
+  ]
+    .filter((section) => section !== '')
+    .join('\n');
+}
+
+describe('fast-fail job ordering', () => {
+  it('rejects a test matrix that does not wait for lint', () => {
+    assert.equal(countFailures(lintAndTest({ needs: 'detect-changes' })), 1);
+  });
+
+  it('rejects a lint gate neutralised by !cancelled()', () => {
+    // `!cancelled()` overrides the implicit "all needs succeeded" rule, so
+    // `needs: [lint]` alone lets the matrix run after lint has already failed.
+    // The dependency is then decorative, which is worse than not having it:
+    // the graph claims a gate the run does not have.
+    assert.equal(
+      countFailures(
+        lintAndTest({
+          needs: 'lint',
+          condition: "    if: >-\n      !cancelled() && github.ref != 'x'",
+        })
+      ),
+      1
+    );
+  });
+
+  it('accepts a lint gate that restates the failure guard', () => {
+    assert.equal(
+      countFailures(
+        lintAndTest({
+          needs: 'lint',
+          condition:
+            "    if: >-\n      !cancelled() && !contains(needs.*.result, 'failure')",
+        })
+      ),
+      0
+    );
+  });
+
+  it('accepts a lint gate stated as an explicit result comparison', () => {
+    assert.equal(
+      countFailures(
+        lintAndTest({
+          needs: 'lint',
+          condition:
+            "    if: >-\n      !cancelled() && needs.lint.result == 'success'",
+        })
+      ),
+      0
+    );
+  });
+
+  it('accepts a plain dependency with no status function at all', () => {
+    // Without `always()` or `!cancelled()`, GitHub's own default already
+    // refuses to start the job when lint fails; nothing has to be restated.
+    assert.equal(countFailures(lintAndTest({ needs: 'lint' })), 0);
+  });
+});

package/tests/unit/scripts/command-error-text.test.js

@@ -0,0 +1,83 @@
+/**
+ * Guard for the second half of the errexit change.
+ *
+ * Turning `errexit` on in loadCommandStream() makes a failed command reject —
+ * but `command-stream`'s rejection carries only
+ *
+ *   message : "Command failed with exit code 101"
+ *   code    : 101
+ *   stdout  : ""
+ *   stderr  : "error: crate version 0.10.11 is already uploaded\n"
+ *
+ * The diagnostic text a caller needs to branch on is in `stderr`, *not* in
+ * `message`. Three release scripts were written as
+ * `error.message.includes('already exists')`, which silently stops matching the
+ * moment the promise actually rejects. Left unfixed, enabling errexit would
+ * convert a harmless re-run over an already-published version into a red
+ * release job.
+ *
+ * `commandErrorText()` is the shared accessor those call sites use instead.
+ */
+
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import { commandErrorText } from '../../../../scripts/use-module.mjs';
+
+describe('commandErrorText', () => {
+  it('finds text that command-stream puts in stderr rather than message', () => {
+    const error = Object.assign(
+      new Error('Command failed with exit code 101'),
+      {
+        code: 101,
+        stdout: '',
+        stderr: 'error: crate version 0.10.11 is already uploaded\n',
+      }
+    );
+
+    assert.equal(
+      error.message.includes('already uploaded'),
+      false,
+      'precondition: the message alone does not carry the reason'
+    );
+    assert.ok(commandErrorText(error).includes('already uploaded'));
+  });
+
+  it('includes stdout, which is where gh reports an existing release', () => {
+    const error = Object.assign(new Error('Command failed with exit code 1'), {
+      code: 1,
+      stdout: '{"message":"Reference already exists"}',
+      stderr: '',
+    });
+
+    assert.ok(commandErrorText(error).includes('already exists'));
+  });
+
+  it('keeps the message so an unrecognised failure is still describable', () => {
+    const error = Object.assign(new Error('Command failed with exit code 7'), {
+      code: 7,
+      stdout: '',
+      stderr: '',
+    });
+
+    assert.match(commandErrorText(error), /exit code 7/);
+  });
+
+  it('tolerates Buffer stdio, which is what capture returns without an encoding', () => {
+    const error = Object.assign(new Error('Command failed with exit code 1'), {
+      code: 1,
+      stdout: Buffer.from('already exists'),
+      stderr: Buffer.from(''),
+    });
+
+    assert.ok(commandErrorText(error).includes('already exists'));
+  });
+
+  it('does not throw on a non-command error, or on null', () => {
+    assert.equal(commandErrorText(new Error('plain')), 'plain');
+    assert.equal(commandErrorText(null), '');
+    assert.equal(commandErrorText(undefined), '');
+    // A thrown string is not an Error but must still be describable.
+    assert.equal(commandErrorText('boom'), 'boom');
+  });
+});

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/pre-commit-config.test.js

@@ -70,6 +70,11 @@ const MIRRORED_COMMANDS = [
     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',