Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

test(docs): bind a version named in the docs to the one being released

Yudhi Armyndharis2aaa5b4ea2ee
diff --git a/package.json b/package.json
index 8506a7ac8..8851cb725 100644
--- a/package.json
+++ b/package.json
@@ -42,7 +42,7 @@
"lint:fix": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
"test": "jest",
"test:scripts": "node --test scripts/postinstall.spec.js scripts/patch-wwebjs-newsletter-preview.spec.js scripts/patch-wwebjs-status.spec.js scripts/patch-wwebjs-ready-sync.spec.js scripts/patch-wwebjs-participant-arity.spec.js scripts/patch-wwebjs-block.spec.js scripts/patch-wwebjs-group-description.spec.js scripts/patch-wwebjs-media-id.spec.js scripts/patch-baileys-appstate.spec.js scripts/patch-baileys-newsletter-create.spec.js scripts/dockerfile-patchers.spec.js scripts/check-upstream-surface.spec.mjs scripts/check-sdk-docs.spec.mjs scripts/check-audit.spec.mjs scripts/check-contract-shapes.spec.mjs scripts/cli-entrypoint-guard.spec.mjs",
- "test:docs": "jest src/common/changelog-sections.spec.ts src/common/ci-privilege-gate.spec.ts src/common/docs-ci-jobs.spec.ts src/common/docs-coverage-policy.spec.ts src/common/docs-metrics-list.spec.ts src/common/openapi/docs-06-contract.spec.ts src/common/test-lane-partition.spec.ts src/config/docs-env-example.spec.ts src/config/openapi-contract.spec.ts src/config/openapi-export-pins.spec.ts src/config/wa-web-version-example-pin.spec.ts src/engine/docs-29-counts.spec.ts src/engine/engine-inventory-parity.spec.ts src/engine/engine-parity.spec.ts src/engine/inventory-mapping-direction.spec.ts src/engine/adapters/baileys-voice-waveform.spec.ts src/engine/adapters/wwebjs-newsletter-preview.spec.ts src/modules/audit/audit-coverage.spec.ts src/modules/auth/global-route-fence-coverage.spec.ts src/modules/auth/query-session-scope-coverage.spec.ts src/modules/docker/compose-network.spec.ts src/modules/queue/bull-board-mount-coverage.spec.ts src/common/release-gate-parity.spec.ts src/database/migrations/__tests__/migration-drift.spec.ts --testPathIgnorePatterns=/node_modules/",
+ "test:docs": "jest src/common/changelog-sections.spec.ts src/common/ci-privilege-gate.spec.ts src/common/docs-ci-jobs.spec.ts src/common/docs-coverage-policy.spec.ts src/common/docs-metrics-list.spec.ts src/common/docs-next-version.spec.ts src/common/openapi/docs-06-contract.spec.ts src/common/test-lane-partition.spec.ts src/config/docs-env-example.spec.ts src/config/openapi-contract.spec.ts src/config/openapi-export-pins.spec.ts src/config/wa-web-version-example-pin.spec.ts src/engine/docs-29-counts.spec.ts src/engine/engine-inventory-parity.spec.ts src/engine/engine-parity.spec.ts src/engine/inventory-mapping-direction.spec.ts src/engine/adapters/baileys-voice-waveform.spec.ts src/engine/adapters/wwebjs-newsletter-preview.spec.ts src/modules/audit/audit-coverage.spec.ts src/modules/auth/global-route-fence-coverage.spec.ts src/modules/auth/query-session-scope-coverage.spec.ts src/modules/docker/compose-network.spec.ts src/modules/queue/bull-board-mount-coverage.spec.ts src/common/release-gate-parity.spec.ts src/database/migrations/__tests__/migration-drift.spec.ts --testPathIgnorePatterns=/node_modules/",
"test:watch": "jest --watch",
"test:cov": "jest --coverage",
"test:debug": "node --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand",
@@ -155,6 +155,7 @@
"src/common/docs-ci-jobs\\.spec\\.ts$",
"src/common/docs-coverage-policy\\.spec\\.ts$",
"src/common/docs-metrics-list\\.spec\\.ts$",
+ "src/common/docs-next-version\\.spec\\.ts$",
"src/common/openapi/docs-06-contract\\.spec\\.ts$",
"src/common/test-lane-partition\\.spec\\.ts$",
"src/config/docs-env-example\\.spec\\.ts$",
@@ -475,6 +476,7 @@
"src/common/docs-ci-jobs\\.spec\\.ts$",
"src/common/docs-coverage-policy\\.spec\\.ts$",
"src/common/docs-metrics-list\\.spec\\.ts$",
+ "src/common/docs-next-version\\.spec\\.ts$",
"src/common/openapi/docs-06-contract\\.spec\\.ts$",
"src/common/test-lane-partition\\.spec\\.ts$",
"src/config/docs-env-example\\.spec\\.ts$",
diff --git a/src/common/docs-next-version.spec.ts b/src/common/docs-next-version.spec.ts
new file mode 100644
index 000000000..f75102d5b
--- /dev/null
+++ b/src/common/docs-next-version.spec.ts
@@ -0,0 +1,76 @@
+import { readFileSync, readdirSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Documentation may describe the release being prepared before its tag exists, and several pages do:
+ * the migration guide and the runbooks tell an operator what changes "from 0.23.6" while
+ * `package.json` still carries the version before it. Nothing bound the two, so a version named in
+ * prose was only ever checked by someone reading it, and a typo, or a page left behind when the
+ * release number changed, would ship pointing operators at a version that never existed.
+ *
+ * The rule this pins is the narrow one that is always true:
+ *
+ * - a version OLDER than or equal to the package version is history and is not this spec's business;
+ * - a version NEWER than it is a forward reference to the release being prepared, so there may be
+ * exactly ONE of them, and the changelog must still be open (`[Unreleased]`) for it to make sense.
+ *
+ * So the day the tag is cut, bumping `package.json` is enough: the references become history and this
+ * spec falls silent. What it catches is the pair going out of step.
+ */
+const ROOT = join(__dirname, '..', '..');
+const SEMVER = /\b(\d+)\.(\d+)\.(\d+)\b/g;
+
+function packageVersion(): [number, number, number] {
+ const raw = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8')) as { version: string };
+ const parts = raw.version.split('.').map(Number);
+ return [parts[0], parts[1], parts[2]];
+}
+
+function isNewer(a: [number, number, number], b: [number, number, number]): boolean {
+ if (a[0] !== b[0]) return a[0] > b[0];
+ if (a[1] !== b[1]) return a[1] > b[1];
+ return a[2] > b[2];
+}
+
+/** Every doc file plus the changelog: the prose an operator reads, not the code. */
+function docFiles(): string[] {
+ const docsDir = join(ROOT, 'docs');
+ const docs = readdirSync(docsDir)
+ .filter(name => name.endsWith('.md'))
+ .map(name => join(docsDir, name));
+ return [...docs, join(ROOT, 'CHANGELOG.md'), join(ROOT, 'README.md')];
+}
+
+describe('a version named in the docs before its tag exists', () => {
+ it('is the same one everywhere, and only while the changelog is still open', () => {
+ const current = packageVersion();
+ const changelog = readFileSync(join(ROOT, 'CHANGELOG.md'), 'utf8');
+
+ const ahead = new Map<string, string[]>();
+ for (const file of docFiles()) {
+ const text = readFileSync(file, 'utf8');
+ // The changelog's own released headings are the history it exists to record, not forward
+ // references, so they are read from the body below rather than matched here.
+ const body = file.endsWith('CHANGELOG.md') ? text.split(/^## \[\d/m)[0] : text;
+ for (const match of body.matchAll(SEMVER)) {
+ const version: [number, number, number] = [Number(match[1]), Number(match[2]), Number(match[3])];
+ // Only this project's own version line. The docs name plenty of third-party versions, and
+ // some of them sort above ours; a gate that argued about a dependency bump would be noise.
+ // A forward reference to OpenWA is by construction the current minor or the next one.
+ if (version[0] !== current[0]) continue;
+ if (version[1] !== current[1] && version[1] !== current[1] + 1) continue;
+ if (!isNewer(version, current)) continue;
+ const key = match[0];
+ ahead.set(key, [...(ahead.get(key) ?? []), file.replace(ROOT + '/', '')]);
+ }
+ }
+
+ const named = [...ahead.keys()].sort();
+ expect(named.length).toBeLessThanOrEqual(1);
+
+ if (named.length === 1) {
+ // A forward reference only makes sense while the release it names is still being prepared.
+ expect(changelog).toContain('## [Unreleased]');
+ }
+ });
+});