browser-commander 0.17.0 → 0.17.2

package/tests/unit/scripts/push-failure-classifier.test.js

@@ -0,0 +1,153 @@
+/**
+ * Guard for RC-1: a release job that treats every rejected push the same.
+ *
+ * Two rejections both print "rejected" and need opposite responses. A lost
+ * race is fixed by rebasing; a repository-rule violation can never be, and
+ * retrying it burns the retry and blames a race that never happened.
+ *
+ * The samples below are the literal wordings the two situations produce:
+ * `non-fast-forward` from the CI logs in dev/log/issues/85/pulls/86/ci-logs/,
+ * `fetch first` from the local reproduction in
+ * experiments/ci-repro/repro-release-push-race.sh.
+ *
+ * Analysis: dev/log/issues/85/pulls/86/analysis/root-causes.md, RC-1
+ */
+
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import {
+  NON_FAST_FORWARD_PATTERNS,
+  REPOSITORY_RULE_PATTERNS,
+  classifyPushFailure,
+  isBlockedByRepositoryRule,
+  isNonFastForward,
+} from '../../../../scripts/push-failure-classifier.mjs';
+
+/** Rejection text a lost race produces, verbatim. */
+const RACE_SAMPLES = [
+  {
+    label: 'non-fast-forward (remote commits already fetched)',
+    stderr: [
+      'To https://github.com/link-foundation/browser-commander',
+      ' ! [rejected]        HEAD -> main (non-fast-forward)',
+      "error: failed to push some refs to 'https://github.com/link-foundation/browser-commander'",
+      'hint: Updates were rejected because a pushed branch tip is behind its remote',
+    ].join('\n'),
+  },
+  {
+    label: 'fetch first (remote commits not yet fetched)',
+    stderr: [
+      ' ! [rejected]        HEAD -> main (fetch first)',
+      'error: failed to push some refs',
+      'hint: Updates were rejected because the remote contains work that you do not',
+      'hint: have locally.',
+    ].join('\n'),
+  },
+];
+
+/** Rejection text a ruleset or protected branch produces, verbatim. */
+const RULE_SAMPLES = [
+  {
+    label: 'GH013 repository ruleset',
+    stderr: [
+      'remote: error: GH013: Repository rule violations found for refs/heads/main.',
+      'remote: - Changes must be made through a pull request.',
+      ' ! [remote rejected] main -> main (push declined due to repository rule violations)',
+    ].join('\n'),
+  },
+  {
+    label: 'GH006 legacy protected branch',
+    stderr: [
+      'remote: error: GH006: Protected branch update failed for refs/heads/main.',
+      ' ! [remote rejected] main -> main (protected branch hook declined)',
+    ].join('\n'),
+  },
+];
+
+describe('push failure classifier', () => {
+  it('reads a lost race as non-fast-forward', () => {
+    for (const sample of RACE_SAMPLES) {
+      assert.equal(
+        classifyPushFailure(sample),
+        'non-fast-forward',
+        `${sample.label} must be retried by rebasing`
+      );
+      assert.equal(isNonFastForward(sample), true, sample.label);
+      assert.equal(isBlockedByRepositoryRule(sample), false, sample.label);
+    }
+  });
+
+  it('never reads a rule violation as a lost race', () => {
+    // This is the whole point of the module. A ruleset rejection contains the
+    // word "rejected" too, so a naive substring check retries a push that can
+    // never succeed.
+    for (const sample of RULE_SAMPLES) {
+      assert.equal(
+        classifyPushFailure(sample),
+        'repository-rule',
+        `${sample.label} must not be retried`
+      );
+      assert.equal(isNonFastForward(sample), false, sample.label);
+      assert.equal(isBlockedByRepositoryRule(sample), true, sample.label);
+    }
+  });
+
+  it('leaves an unrelated failure unclassified so it is not retried', () => {
+    const authFailure = {
+      stderr:
+        'fatal: could not read Username for https://github.com: No such device or address',
+    };
+    assert.equal(classifyPushFailure(authFailure), 'unknown');
+    assert.equal(isNonFastForward(authFailure), false);
+    assert.equal(isBlockedByRepositoryRule(authFailure), false);
+  });
+
+  it('ignores the generic wrapper message command-stream attaches', () => {
+    // command-stream rejects with "Command failed with exit code 1"; the
+    // classification has to rest on what git wrote, not on the wrapper.
+    const wrapped = {
+      message: 'Command failed with exit code 1',
+      stdout: '',
+      stderr: 'Everything up-to-date',
+    };
+    assert.equal(classifyPushFailure(wrapped), 'unknown');
+  });
+
+  it('reads a bare string as well as a command result', () => {
+    assert.equal(
+      classifyPushFailure(' ! [rejected] main -> main (non-fast-forward)'),
+      'non-fast-forward'
+    );
+    assert.equal(
+      classifyPushFailure('remote: error: GH013:'),
+      'repository-rule'
+    );
+  });
+
+  it('survives a failure with nothing to read', () => {
+    for (const empty of [null, undefined, {}, '']) {
+      assert.equal(classifyPushFailure(empty), 'unknown');
+    }
+  });
+
+  it('matches case-insensitively, because git and GitHub disagree on case', () => {
+    assert.equal(
+      classifyPushFailure({
+        stderr: 'REMOTE: ERROR: GH013: REPOSITORY RULE VIOLATIONS',
+      }),
+      'repository-rule'
+    );
+    assert.equal(
+      classifyPushFailure({
+        stderr: '! [REJECTED] main -> main (NON-FAST-FORWARD)',
+      }),
+      'non-fast-forward'
+    );
+  });
+
+  it('keeps the pattern lists frozen so a caller cannot widen them', () => {
+    assert.throws(() => REPOSITORY_RULE_PATTERNS.push('anything'));
+    assert.throws(() => NON_FAST_FORWARD_PATTERNS.push('anything'));
+  });
+});

package/tests/unit/scripts/push-with-rebase-retry.test.js

@@ -0,0 +1,302 @@
+/**
+ * Guard for RC-1 and RC-3.
+ *
+ * RC-1: the release jobs are serialised by a concurrency group but each one
+ * checks out `github.sha`, so every writer after the first holds a tree one
+ * commit behind main and its push is rejected. Nothing rebased and retried.
+ *
+ * RC-3: a retry rebases, which rewrites the release commit. A tag created
+ * before the push would keep pointing at the pre-rebase commit and be
+ * reachable from no branch -- reproduced as case 2 of
+ * experiments/ci-repro/repro-release-push-race.sh. So the release scripts must
+ * tag only after the push has succeeded.
+ *
+ * Analysis: dev/log/issues/85/pulls/86/analysis/root-causes.md
+ */
+
+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 {
+  DEFAULT_ATTEMPTS,
+  pushWithRebaseRetry,
+  resolveCurrentBranch,
+} from '../../../../scripts/push-with-rebase-retry.mjs';
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '../../../..');
+
+/** A rejection shaped like the one `command-stream` produces for git. */
+function rejection(stderr) {
+  return Object.assign(new Error('Command failed with exit code 1'), {
+    code: 1,
+    stdout: '',
+    stderr,
+  });
+}
+
+const RACE = ' ! [rejected]        HEAD -> main (non-fast-forward)\n';
+const RULE = [
+  'remote: error: GH013: Repository rule violations found for refs/heads/main.',
+  'remote: - Changes must be made through a pull request.',
+].join('\n');
+
+/**
+ * Build a fake git that fails the first `failures` pushes with `stderr`, then
+ * succeeds, recording every argv it was handed.
+ */
+function fakeGit({ failures = 0, stderr = RACE, stdout = '' } = {}) {
+  const calls = [];
+  let pushes = 0;
+  const git = async (args) => {
+    calls.push(args.join(' '));
+    if (args[0] === 'push') {
+      pushes++;
+      if (pushes <= failures) {
+        throw rejection(stderr);
+      }
+    }
+    return { stdout, stderr: '', code: 0 };
+  };
+  git.calls = calls;
+  return git;
+}
+
+/** Collect log lines instead of printing them. */
+function fakeLogger() {
+  const lines = [];
+  return { lines, log: (line) => lines.push(line) };
+}
+
+const silent = () => {};
+
+describe('pushWithRebaseRetry', () => {
+  it('pushes once when nothing else has written to the branch', async () => {
+    const git = fakeGit();
+    const result = await pushWithRebaseRetry({
+      git,
+      branch: 'main',
+      logger: fakeLogger(),
+      debugFn: silent,
+    });
+
+    assert.deepEqual(result, { pushed: true, via: 'direct', attempts: 1 });
+    assert.deepEqual(git.calls, ['push origin HEAD:main']);
+  });
+
+  it('rebases and retries after losing the race, as in run 33998729944', async () => {
+    const git = fakeGit({ failures: 1 });
+    const logger = fakeLogger();
+
+    const result = await pushWithRebaseRetry({
+      git,
+      branch: 'main',
+      logger,
+      debugFn: silent,
+    });
+
+    assert.deepEqual(result, { pushed: true, via: 'rebase', attempts: 2 });
+    assert.deepEqual(git.calls, [
+      'push origin HEAD:main',
+      'pull --rebase origin main',
+      'push origin HEAD:main',
+    ]);
+    assert.ok(
+      logger.lines.some((line) => line.startsWith('::warning::')),
+      'a recovered race must still be visible in the log'
+    );
+  });
+
+  it('does not retry a repository-rule rejection', async () => {
+    // Rebasing cannot satisfy a ruleset. Retrying it doubles the time the job
+    // takes to die and leaves a log blaming a race that never happened.
+    const git = fakeGit({ failures: DEFAULT_ATTEMPTS, stderr: RULE });
+    const logger = fakeLogger();
+
+    await assert.rejects(
+      pushWithRebaseRetry({ git, branch: 'main', logger, debugFn: silent })
+    );
+
+    assert.deepEqual(git.calls, ['push origin HEAD:main']);
+    assert.ok(
+      logger.lines.some(
+        (line) => line.startsWith('::error::') && line.includes('GH006/GH013')
+      ),
+      'the log must name the real cause'
+    );
+  });
+
+  it('does not retry a failure a rebase cannot fix', async () => {
+    const git = fakeGit({
+      failures: DEFAULT_ATTEMPTS,
+      stderr: 'fatal: could not read Username for https://github.com',
+    });
+
+    await assert.rejects(
+      pushWithRebaseRetry({
+        git,
+        branch: 'main',
+        logger: fakeLogger(),
+        debugFn: silent,
+      })
+    );
+    assert.deepEqual(git.calls, ['push origin HEAD:main']);
+  });
+
+  it('gives up after the configured number of attempts', async () => {
+    const git = fakeGit({ failures: 99 });
+
+    await assert.rejects(
+      pushWithRebaseRetry({
+        git,
+        branch: 'main',
+        attempts: 3,
+        logger: fakeLogger(),
+        debugFn: silent,
+      })
+    );
+
+    const pushes = git.calls.filter((call) => call.startsWith('push'));
+    assert.equal(pushes.length, 3, 'exactly `attempts` pushes, no more');
+  });
+
+  it('pushes the branch it is told to, not always main', async () => {
+    const git = fakeGit();
+    await pushWithRebaseRetry({
+      git,
+      remote: 'upstream',
+      branch: 'release',
+      logger: fakeLogger(),
+      debugFn: silent,
+    });
+    assert.deepEqual(git.calls, ['push upstream HEAD:release']);
+  });
+
+  it('stays silent on the debug channel unless tracing is switched on', async () => {
+    // The verbose mode has to default to off: a release log is read by people
+    // looking for the one line that matters.
+    const traced = [];
+    const git = fakeGit({ failures: 1 });
+    await pushWithRebaseRetry({
+      git,
+      branch: 'main',
+      logger: fakeLogger(),
+      debugFn: (...parts) => traced.push(parts.join(' ')),
+    });
+    assert.ok(traced.length > 0, 'the helper must offer tracing to inject');
+
+    const quiet = [];
+    const { debugWith } = await import('../../../../scripts/debug-print.mjs');
+    await pushWithRebaseRetry({
+      git: fakeGit(),
+      branch: 'main',
+      logger: fakeLogger(),
+      debugFn: (...parts) =>
+        debugWith({ env: {}, log: (l) => quiet.push(l) }, ...parts),
+    });
+    assert.deepEqual(quiet, [], 'debug output must be off by default');
+  });
+});
+
+describe('resolveCurrentBranch', () => {
+  it('reads the branch instead of assuming main', async () => {
+    // The Rust release used a bare `git push`, which follows the current
+    // branch's upstream; a hard-coded HEAD:main would change behaviour for a
+    // workflow_dispatch run started from another branch.
+    const git = fakeGit({ stdout: 'release-2.x\n' });
+    assert.equal(await resolveCurrentBranch(git), 'release-2.x');
+    assert.deepEqual(git.calls, ['rev-parse --abbrev-ref HEAD']);
+  });
+
+  it('falls back to main when git says nothing', async () => {
+    assert.equal(
+      await resolveCurrentBranch(fakeGit({ stdout: '  \n' })),
+      'main'
+    );
+  });
+
+  it('does not push HEAD:HEAD from a detached checkout', async () => {
+    // `git rev-parse --abbrev-ref HEAD` prints the literal "HEAD" when
+    // detached. Using it as the target branch would aim the push at a remote
+    // branch named HEAD instead of the release branch.
+    assert.equal(
+      await resolveCurrentBranch(fakeGit({ stdout: 'HEAD\n' })),
+      'main'
+    );
+    assert.equal(
+      await resolveCurrentBranch(fakeGit({ stdout: 'HEAD\n' }), 'release'),
+      'release'
+    );
+  });
+});
+
+describe('release scripts tag only after the push (RC-3)', () => {
+  const releaseScripts = [
+    'rust/scripts/version-and-commit.mjs',
+    'js/scripts/version-and-commit.mjs',
+  ];
+
+  for (const relativePath of releaseScripts) {
+    it(`${relativePath} never leaves an orphaned tag`, () => {
+      const source = readFileSync(join(repoRoot, relativePath), 'utf8');
+      const tagIndex = source.indexOf('git tag -a');
+      if (tagIndex === -1) {
+        return; // This script does not tag; nothing to order.
+      }
+      const pushIndex = source.indexOf('pushWithRebaseRetry({');
+      assert.notEqual(
+        pushIndex,
+        -1,
+        `${relativePath} must push through pushWithRebaseRetry`
+      );
+      assert.ok(
+        pushIndex < tagIndex,
+        `${relativePath} creates a tag before pushing; a rebase retry would ` +
+          'rewrite the commit and orphan that tag'
+      );
+    });
+  }
+
+  it('no release script pushes with the blanket --tags', () => {
+    // `git push --tags` also pushes every unrelated local tag the runner
+    // happens to have fetched.
+    for (const relativePath of releaseScripts) {
+      const source = readFileSync(join(repoRoot, relativePath), 'utf8');
+      assert.ok(
+        !source.includes('git push --tags'),
+        `${relativePath} must push its release tag by name`
+      );
+    }
+  });
+});
+
+describe('every release push site uses the shared helper', () => {
+  // The fix has to be applied everywhere: a single un-migrated push site
+  // reproduces the original failure the next time two releases run.
+  it('leaves no raw push to a shared branch behind', () => {
+    const sites = [
+      'js/scripts/version-and-commit.mjs',
+      'rust/scripts/version-and-commit.mjs',
+    ];
+    for (const relativePath of sites) {
+      const source = readFileSync(join(repoRoot, relativePath), 'utf8');
+      for (const raw of [
+        'git push`',
+        'git push origin main`',
+        'git push --tags`',
+        'git push origin HEAD:main`',
+      ]) {
+        assert.ok(
+          !source.includes(raw),
+          `${relativePath} still contains a raw \`${raw}\``
+        );
+      }
+      assert.ok(
+        source.includes('pushWithRebaseRetry'),
+        `${relativePath} must push through the shared helper`
+      );
+    }
+  });
+});

package/tests/unit/scripts/release-tags.test.js

@@ -0,0 +1,96 @@
+/**
+ * Guard for RC-D: the JS package and the Rust crate sharing one tag
+ * namespace.
+ *
+ * Both released as `v<version>`, and their version numbers overlap -- 0.4.0,
+ * 0.9.1 and 0.10.0 exist on both npm and crates.io. `git tag` refuses to
+ * recreate an existing tag, so whichever language got there first owns the
+ * name and the other silently releases without one. `v0.10.11` is a Rust
+ * crate version, but in this repository it points at the commit that
+ * released JS 0.17.0.
+ *
+ * Python already avoided this with a `python-v` prefix. The prefixes now
+ * live in one place so that the three cannot drift back into each other.
+ *
+ * Analysis: dev/log/issues/83/pulls/84/analysis/root-causes.md, RC-D
+ */
+
+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 { TAG_PREFIXES, releaseTag } from '../../../../scripts/release-tags.mjs';
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '../../../..');
+
+describe('release tag namespaces', () => {
+  it('gives every language its own prefix', () => {
+    const prefixes = Object.values(TAG_PREFIXES);
+    assert.equal(
+      new Set(prefixes).size,
+      prefixes.length,
+      'two languages sharing a prefix means one of them cannot tag its release'
+    );
+  });
+
+  it('cannot produce the same tag for two languages at the same version', () => {
+    // The versions that actually collided.
+    for (const version of ['0.4.0', '0.9.1', '0.10.0', '0.10.11', '0.17.0']) {
+      const tags = Object.keys(TAG_PREFIXES).map((language) =>
+        releaseTag(language, version)
+      );
+      assert.equal(
+        new Set(tags).size,
+        tags.length,
+        `version ${version} produces a duplicate tag: ${tags.join(', ')}`
+      );
+    }
+  });
+
+  it('keeps `v*` matching the JS package only', () => {
+    // Release tooling and humans both list JS releases with `git tag -l 'v*'`.
+    for (const [language, prefix] of Object.entries(TAG_PREFIXES)) {
+      if (language === 'js') {
+        continue;
+      }
+      assert.ok(
+        !prefix.startsWith('v'),
+        `${language} uses ${prefix}, which a 'v*' glob would also match`
+      );
+    }
+  });
+
+  it('rejects an unknown language rather than guessing a prefix', () => {
+    assert.throws(() => releaseTag('perl', '1.0.0'), /perl/);
+  });
+
+  it('matches the prefixes the workflows actually pass', () => {
+    const expected = {
+      'python.yml': TAG_PREFIXES.python,
+      'rust.yml': TAG_PREFIXES.rust,
+    };
+
+    for (const [file, prefix] of Object.entries(expected)) {
+      const workflow = readFileSync(
+        join(repoRoot, '.github/workflows', file),
+        'utf-8'
+      );
+      const passed = [...workflow.matchAll(/--tag-prefix "([^"]*)"/g)].map(
+        (match) => match[1]
+      );
+      assert.ok(
+        passed.length > 0,
+        `${file} passes no --tag-prefix, so it falls back to the default`
+      );
+      for (const value of passed) {
+        assert.equal(
+          value,
+          prefix,
+          `${file} passes --tag-prefix "${value}" but scripts/release-tags.mjs says "${prefix}"`
+        );
+      }
+    }
+  });
+});

package/tests/unit/scripts/required-docs.test.js

@@ -0,0 +1,145 @@
+/**
+ * The documentation gate (CI/CD best practice #12).
+ *
+ * The repository already checks the two mechanical properties of its
+ * documentation: `scripts/check-file-line-limits.sh` scans every tracked `.md`
+ * file against the 1500-line limit, and `.github/workflows/links.yml` runs
+ * lychee over `./**\/*.md`, which resolves relative paths as well as URLs.
+ * Neither notices a document that stopped existing, and neither notices one of
+ * the three language READMEs quietly losing the section the other two still
+ * have - the exact drift `docs/feature-parity.md` exists to prevent.
+ *
+ * The template covers only the first half of that (a required-files list in
+ * `validate-docs`); the shared-section list is what a tri-language repository
+ * needs on top.
+ *
+ * These tests pin the enforcement mechanics against a fixture built from the
+ * script's own `--list` output, and pin the repository itself against the real
+ * requirement table.
+ */
+
+import assert from 'node:assert/strict';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { describe, it } from 'node:test';
+
+import { BASH_AVAILABLE, repoPath, runBashScript } from '../../helpers/repo.js';
+
+const SCRIPT = repoPath('scripts/check-required-docs.sh');
+
+function run(args = [], options = {}) {
+  return runBashScript(SCRIPT, args, options);
+}
+
+/** The requirement table, read back from the script that enforces it. */
+function requirements() {
+  const { status, output } = run(['--list']);
+  assert.equal(status, 0, output);
+
+  const table = new Map();
+  for (const line of output.split('\n')) {
+    if (!line.trim()) {
+      continue;
+    }
+    const [file, section = ''] = line.split('\t');
+    if (!table.has(file)) {
+      table.set(file, []);
+    }
+    if (section) {
+      table.get(file).push(section);
+    }
+  }
+  return table;
+}
+
+/**
+ * A throwaway tree that satisfies the table, so a test can take exactly one
+ * thing away from it and watch the script notice.
+ */
+function fixture(table) {
+  const root = mkdtempSync(path.join(tmpdir(), 'required-docs-'));
+  for (const [file, sections] of table) {
+    const target = path.join(root, file);
+    mkdirSync(path.dirname(target), { recursive: true });
+    writeFileSync(
+      target,
+      `# Title\n\n${sections.map((section) => `## ${section}\n\nBody.\n`).join('\n')}`
+    );
+  }
+  return root;
+}
+
+describe('check-required-docs.sh', { skip: !BASH_AVAILABLE }, () => {
+  it('passes on this repository', () => {
+    const { status, output } = run();
+    assert.equal(status, 0, output);
+  });
+
+  it('requires the three language READMEs to share a section list', () => {
+    const table = requirements();
+    const js = table.get('js/README.md');
+    assert.ok(js?.length, 'js/README.md carries no required sections');
+    assert.deepEqual(table.get('python/README.md'), js);
+    assert.deepEqual(table.get('rust/README.md'), js);
+  });
+
+  it('fails on a required document that is missing', () => {
+    const table = requirements();
+    const root = fixture(table);
+    try {
+      rmSync(path.join(root, 'python/README.md'));
+      const { status, output } = run([root]);
+      assert.notEqual(status, 0);
+      assert.match(output, /python\/README\.md/);
+      assert.match(output, /missing/i);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it('fails on a required section that is missing, and names it', () => {
+    const table = requirements();
+    const root = fixture(table);
+    const dropped = table.get('rust/README.md')[0];
+    try {
+      writeFileSync(
+        path.join(root, 'rust/README.md'),
+        `# Title\n\n${table
+          .get('rust/README.md')
+          .filter((section) => section !== dropped)
+          .map((section) => `## ${section}\n\nBody.\n`)
+          .join('\n')}`
+      );
+      const { status, output } = run([root]);
+      assert.notEqual(status, 0);
+      assert.match(output, new RegExp(`rust/README\\.md`));
+      assert.ok(
+        output.includes(dropped),
+        `expected the report to name the missing section ${dropped}`
+      );
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it('reads a heading only as a heading, not as prose that mentions it', () => {
+    const table = requirements();
+    const root = fixture(table);
+    const [section] = table.get('js/README.md');
+    try {
+      writeFileSync(
+        path.join(root, 'js/README.md'),
+        `# Title\n\nSee the ${section} section below.\n\n${table
+          .get('js/README.md')
+          .slice(1)
+          .map((heading) => `## ${heading}\n\nBody.\n`)
+          .join('\n')}`
+      );
+      const { status } = run([root]);
+      assert.notEqual(status, 0);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});