browser-commander 0.17.0 → 0.17.1

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

package/.changeset/merged-loud-river.md

@@ -1,7 +0,0 @@
----
-'browser-commander': minor
----
-
-Restore the release pipeline. `const { $ } = await use('command-stream')` returned `undefined` on the Node 24 the release jobs pin, because Node 23 added a synthetic `'module.exports'` named export for CommonJS namespaces that use-m's unwrapping does not recognise, so every JS and Rust release died on its first shell call with `TypeError: $ is not a function`. Dependencies now load through `scripts/use-module.mjs`, which detects that namespace shape and unwraps it. Manifest fields are read by TOML table through `scripts/read-manifest.mjs` instead of a line-anchored `grep`, which matched duplicate keys in other tables and wrote two lines into `$GITHUB_OUTPUT`. The duplication gate had `format` set to a reporter name, so jscpd scanned zero files and passed unconditionally; it now scans the tree against a recorded baseline.
-
-Add the `fingerprint` subsystem, which removes the differences between a browser this library controls and one started by hand. `navigator.webdriver` stays false because the `AutomationControlled` Blink feature is disabled at launch, and `launchBrowser()` no longer passes the engine defaults a real Chrome does not carry. `resolveFingerprintProfile()` validates the 19 environment fields a page can read -- user agent and client hints, languages and locale, time zone, platform, cores, memory, screen, viewport, touch, WebGL strings, geolocation and the media preferences -- `createFingerprintPreset()` builds internally consistent Windows, macOS, Linux and Android machines, and `applyFingerprint()` installs a profile over CDP for both Playwright and Puppeteer. `FINGERPRINT_LIMITATIONS` documents what still cannot be made identical, and `relevantFingerprintLimitations()` narrows it to the entries a given profile and browser actually hit. The excluded defaults include Playwright's unconditional `--enable-unsafe-swiftshader`, which would otherwise give an automated browser a SwiftShader WebGL context on a machine where a hand-started Chrome has none.

package/deno.json

@@ -1,7 +0,0 @@
-{
-  "nodeModulesDir": "auto",
-  "test": {
-    "include": ["tests/"],
-    "exclude": ["examples/", "node_modules/"]
-  }
-}