browser-commander 0.16.1 → 0.17.1

package/tests/unit/scripts/read-manifest.test.js

@@ -0,0 +1,194 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import {
+  parseArguments,
+  readManifestField,
+  readTomlField,
+  replaceTomlField,
+} from '../../../../scripts/read-manifest.mjs';
+
+const repositoryRoot = join(
+  dirname(fileURLToPath(import.meta.url)),
+  '..',
+  '..',
+  '..',
+  '..'
+);
+
+/**
+ * The extraction the release jobs used before this script existed. Kept here so
+ * the regression it caused stays visible next to the fix.
+ * @param {string} content manifest source
+ * @returns {string[]} every line-anchored `version = "..."` match
+ */
+function legacyGrepVersions(content) {
+  return [...content.matchAll(/^version = "([^"]*)"/gm)].map(
+    (match) => match[1]
+  );
+}
+
+function readFixture(relativePath) {
+  return readFileSync(join(repositoryRoot, relativePath), 'utf8');
+}
+
+describe('read-manifest', () => {
+  it('reproduces the multi-match that broke the Python release', () => {
+    // Both `[project].version` and `[tool.scriv].version` are line-anchored, so
+    // the old grep wrote two lines into $GITHUB_OUTPUT and the step failed with
+    // "Invalid format 'literal: pyproject.toml: project.version'".
+    const matches = legacyGrepVersions(readFixture('python/pyproject.toml'));
+    assert.ok(
+      matches.length > 1,
+      'expected pyproject.toml to still carry more than one line-anchored version key'
+    );
+    assert.ok(matches.includes('literal: pyproject.toml: project.version'));
+  });
+
+  it('reads the project version despite the scriv literal', () => {
+    assert.equal(
+      readManifestField(join(repositoryRoot, 'python/pyproject.toml')),
+      readFixture('python/pyproject.toml').match(
+        /^\[project\][\s\S]*?^version = "([^"]+)"/m
+      )[1]
+    );
+  });
+
+  it('reads the crate version and name past [[bin]] and [lib]', () => {
+    const cargo = join(repositoryRoot, 'rust/Cargo.toml');
+    assert.match(readManifestField(cargo), /^\d+\.\d+\.\d+/);
+    assert.equal(
+      readManifestField(cargo, { field: 'name' }),
+      'browser-commander'
+    );
+  });
+
+  it('reads the npm package version', () => {
+    assert.match(
+      readManifestField(join(repositoryRoot, 'js/package.json')),
+      /^\d+\.\d+\.\d+/
+    );
+  });
+
+  it('ignores a version declared in another table', () => {
+    const toml = [
+      '[tool.scriv]',
+      'version = "literal: pyproject.toml: project.version"',
+      '',
+      '[project]',
+      'version = "1.2.3"',
+    ].join('\n');
+    assert.equal(readTomlField(toml, 'project', 'version'), '1.2.3');
+  });
+
+  it('ignores a commented-out key and keeps a # inside a value', () => {
+    const toml = [
+      '[package]',
+      '# version = "9.9.9"',
+      'version = "1.0.0" # released',
+      'description = "colors like #fff"',
+    ].join('\n');
+    assert.equal(readTomlField(toml, 'package', 'version'), '1.0.0');
+    assert.equal(
+      readTomlField(toml, 'package', 'description'),
+      'colors like #fff'
+    );
+  });
+
+  it('reads single-quoted TOML values', () => {
+    assert.equal(
+      readTomlField("[project]\nversion = '2.0.0'", 'project', 'version'),
+      '2.0.0'
+    );
+  });
+
+  it('fails loudly instead of emitting an empty version', () => {
+    assert.throws(
+      () =>
+        readManifestField('pyproject.toml', {
+          readFile: () => '[tool.scriv]\nversion = "literal: x"',
+        }),
+      /no non-empty "version" in \[project\]/
+    );
+  });
+
+  it('fails loudly on an empty value rather than releasing it', () => {
+    assert.throws(
+      () =>
+        readManifestField('Cargo.toml', {
+          readFile: () => '[package]\nversion = ""',
+        }),
+      /no non-empty "version"/
+    );
+  });
+
+  // The field name reaches this module through argv, so building a pattern
+  // from it let `.` match any character and let `(` throw SyntaxError instead
+  // of reporting a missing field. CodeQL flagged the same lines as
+  // js/regex-injection on PR #82.
+  it('compares the field name literally rather than as a pattern', () => {
+    const toml = ['[package]', 'axb = "wrong"', 'name = "right"'].join('\n');
+
+    assert.equal(readTomlField(toml, 'package', 'a.b'), undefined);
+    assert.throws(
+      () => replaceTomlField(toml, 'package', 'a.b', '9.9.9'),
+      /No \[package\] a\.b to update/
+    );
+  });
+
+  it('reports a missing field whose name is not a valid pattern', () => {
+    const toml = ['[package]', 'name = "right"'].join('\n');
+
+    assert.equal(readTomlField(toml, 'package', 'a('), undefined);
+  });
+
+  it('keeps spacing and a trailing comment when it rewrites a version', () => {
+    const toml = ['[package]', '  version   =   "1.2.3"  # keep "this"'].join(
+      '\n'
+    );
+
+    assert.equal(
+      replaceTomlField(toml, 'package', 'version', '9.9.9'),
+      ['[package]', '  version   =   "9.9.9"  # keep "this"'].join('\n')
+    );
+  });
+
+  it('refuses to bump a version it cannot rewrite', () => {
+    // Silently returning the file unchanged would publish the old version.
+    assert.throws(
+      () =>
+        replaceTomlField(
+          '[package]\nversion = 3',
+          'package',
+          'version',
+          '9.9.9'
+        ),
+      /is not a quoted string/
+    );
+  });
+
+  it('parses the CLI arguments the workflows pass', () => {
+    assert.deepEqual(
+      parseArguments([
+        'rust/Cargo.toml',
+        '--field',
+        'name',
+        '--output=crate_name',
+      ]),
+      {
+        manifest: 'rust/Cargo.toml',
+        field: 'name',
+        table: undefined,
+        output: 'crate_name',
+      }
+    );
+  });
+
+  it('rejects an invocation without exactly one manifest', () => {
+    assert.throws(() => parseArguments([]), /Usage:/);
+    assert.throws(() => parseArguments(['a.toml', 'b.toml']), /Usage:/);
+  });
+});

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 });
+    }
+  });
+});

package/tests/unit/scripts/run-with-budget-warning.test.js

@@ -0,0 +1,115 @@
+/**
+ * The wrapper that gives a long step its own deadline.
+ *
+ * A job killed by `timeout-minutes` is reported as cancelled, which is not a
+ * failure; a step that owns its budget exits non-zero instead, so the overrun
+ * turns a check red and names the deadline it blew. These tests pin the three
+ * properties the workflows depend on: the command's own exit status is passed
+ * through untouched, an overrun exits 124 with an error annotation, and the
+ * whole process tree is killed rather than just the direct child.
+ *
+ * See docs/CI-TIMEOUT-BUDGETS.md.
+ */
+
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync, rmSync } 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/run-with-budget-warning.sh');
+
+function runWrapper(args, env = {}) {
+  return runBashScript(SCRIPT, args, {
+    env: { BUDGET_GRACE_SECONDS: '1', ...env },
+  });
+}
+
+describe('run-with-budget-warning.sh', { skip: !BASH_AVAILABLE }, () => {
+  it('passes a successful command through', () => {
+    const { status, output } = runWrapper(['5', 'quick step', 'true']);
+
+    assert.equal(status, 0);
+    assert.match(
+      output,
+      /quick step finished in \d+s of its 5s budget \(exit 0\)/
+    );
+  });
+
+  it("passes a failing command's own exit status through", () => {
+    const { status } = runWrapper([
+      '5',
+      'failing step',
+      'bash',
+      '-c',
+      'exit 7',
+    ]);
+
+    assert.equal(status, 7);
+  });
+
+  it('exits 124 and annotates the overrun', () => {
+    const { status, output } = runWrapper(['1', 'slow step', 'sleep', '30']);
+
+    assert.equal(status, 124);
+    assert.match(
+      output,
+      /::error title=slow step exceeded its execution budget::/
+    );
+  });
+
+  it('kills the whole process group, not just the direct child', async () => {
+    // Test runners spawn workers; killing only the direct child leaves orphans
+    // holding the runner, which is why timeout(1) is not sufficient here. The
+    // worker is watched through the file it writes rather than through
+    // `kill -0`, which also succeeds for a killed-but-unreaped zombie.
+    const directory = mkdtempSync(path.join(tmpdir(), 'budget-wrapper-'));
+    const tickFile = path.join(directory, 'ticks');
+
+    try {
+      const { status } = runWrapper([
+        '1',
+        'step with a worker',
+        'bash',
+        '-c',
+        `while true; do echo tick >> ${JSON.stringify(tickFile)}; sleep 0.2; done & wait`,
+      ]);
+
+      assert.equal(status, 124);
+
+      const ticksAtTermination = readFileSync(tickFile, 'utf8').length;
+
+      assert.ok(ticksAtTermination > 0, 'the worker never started');
+
+      await new Promise((resolve) => setTimeout(resolve, 1500));
+
+      assert.equal(
+        readFileSync(tickFile, 'utf8').length,
+        ticksAtTermination,
+        'the worker outlived the budget termination'
+      );
+    } finally {
+      rmSync(directory, { force: true, recursive: true });
+    }
+  });
+
+  it('warns before the budget expires', () => {
+    const { status, output } = runWrapper(['10', 'warned step', 'sleep', '2'], {
+      BUDGET_WARN_PERCENT: '10',
+    });
+
+    assert.equal(status, 0);
+    assert.match(
+      output,
+      /::warning title=warned step is approaching its execution budget::/
+    );
+  });
+
+  it('rejects a budget that is not a positive number of seconds', () => {
+    assert.equal(runWrapper(['soon', 'bad budget', 'true']).status, 2);
+    assert.equal(runWrapper(['0', 'bad budget', 'true']).status, 2);
+    assert.equal(runWrapper(['5']).status, 2);
+  });
+});

package/tests/unit/scripts/rust-changelog.test.js

@@ -0,0 +1,147 @@
+/**
+ * Guard for the half of RC-C that survives even after errexit is fixed.
+ *
+ * `rust/scripts/version-and-commit.mjs` carried its own copy of the changelog
+ * collector, and that copy never deleted the fragments it consumed. The
+ * standalone `rust/scripts/collect-changelog.mjs` did delete them, but only
+ * the `manual-release` job ever calls it — `auto-release` used the inline
+ * copy. So every automatic release re-published the same twelve entries.
+ *
+ * Both now share `rust/scripts/changelog.mjs`. These tests pin the behaviour
+ * the inline copy was missing.
+ *
+ * See dev/log/issues/83/pulls/84/analysis/root-causes.md, RC-C.
+ */
+
+import assert from 'node:assert/strict';
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  readFileSync,
+  readdirSync,
+  existsSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, it } from 'node:test';
+
+import {
+  collectFragments,
+  removeFragments,
+  updateChangelog,
+  INSERT_MARKER,
+} from '../../../../rust/scripts/changelog.mjs';
+
+/**
+ * Build a throwaway crate directory with changelog fragments.
+ * @param {{fragments?: Record<string,string>, changelog?: string|null}} [options]
+ */
+function fixture(options = {}) {
+  const { fragments = {}, changelog = null } = options;
+  const dir = mkdtempSync(join(tmpdir(), 'rust-changelog-'));
+  const changelogDir = join(dir, 'changelog.d');
+  mkdirSync(changelogDir);
+  writeFileSync(join(changelogDir, 'README.md'), 'not a fragment\n');
+  for (const [name, content] of Object.entries(fragments)) {
+    writeFileSync(join(changelogDir, name), content);
+  }
+  if (changelog !== null) {
+    writeFileSync(join(dir, 'CHANGELOG.md'), changelog);
+  }
+  return { dir, changelogDir };
+}
+
+const HEADER = `# Changelog
+
+All notable changes to this project will be documented in this file.
+
+${INSERT_MARKER}
+
+## [0.1.0] - 2024-12-30
+
+### Added
+
+- Initial release
+`;
+
+describe('rust changelog collector', () => {
+  it('deletes the fragments it consumed', () => {
+    const { dir, changelogDir } = fixture({
+      fragments: {
+        '38.added.md': '### Added\n\n- A thing\n',
+        '49.added.md': '### Added\n\n- Another thing\n',
+      },
+      changelog: HEADER,
+    });
+
+    updateChangelog(dir, '0.10.11', collectFragments(dir));
+    removeFragments(dir);
+
+    const left = readdirSync(changelogDir);
+    assert.deepEqual(
+      left,
+      ['README.md'],
+      'every consumed fragment must be gone; leaving them makes the next ' +
+        'release re-publish the same notes'
+    );
+  });
+
+  it('never deletes README.md', () => {
+    const { dir, changelogDir } = fixture({
+      fragments: { '1.added.md': '- x\n' },
+      changelog: HEADER,
+    });
+    removeFragments(dir);
+    assert.ok(existsSync(join(changelogDir, 'README.md')));
+  });
+
+  it('strips frontmatter carrying the bump type', () => {
+    const { dir } = fixture({
+      fragments: {
+        '81.fixed.md': '---\nbump: patch\n---\n\n### Fixed\n\n- A fix\n',
+      },
+      changelog: HEADER,
+    });
+    const fragments = collectFragments(dir);
+    assert.ok(!fragments.includes('bump: patch'));
+    assert.ok(fragments.includes('- A fix'));
+  });
+
+  it('inserts the new entry directly after the marker, above older releases', () => {
+    const { dir } = fixture({
+      fragments: { '38.added.md': '### Added\n\n- New thing\n' },
+      changelog: HEADER,
+    });
+
+    updateChangelog(dir, '0.10.11', collectFragments(dir));
+
+    const content = readFileSync(join(dir, 'CHANGELOG.md'), 'utf-8');
+    assert.ok(
+      content.indexOf('## [0.10.11]') < content.indexOf('## [0.1.0]'),
+      'newest release must come first'
+    );
+    assert.ok(
+      content.indexOf(INSERT_MARKER) < content.indexOf('## [0.10.11]'),
+      'the marker must stay above the entries so the next release can find it'
+    );
+  });
+
+  it('reports no fragments rather than writing an empty release section', () => {
+    const { dir } = fixture({ changelog: HEADER });
+    assert.equal(collectFragments(dir), '');
+  });
+
+  it('creates CHANGELOG.md when it does not exist yet', () => {
+    const { dir } = fixture({
+      fragments: { '1.added.md': '### Added\n\n- First\n' },
+    });
+
+    updateChangelog(dir, '0.1.0', collectFragments(dir));
+
+    const content = readFileSync(join(dir, 'CHANGELOG.md'), 'utf-8');
+    assert.ok(content.includes(INSERT_MARKER));
+    assert.ok(content.includes('## [0.1.0]'));
+    assert.ok(content.includes('- First'));
+  });
+});