Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

test(cli): global-local reuses placed CLI copies a test left unchanged (#9932)

Christopher Chedeaudf5aded8ca82
diff --git a/packages/cli/test-utils/global-local-fixtures.mjs b/packages/cli/test-utils/global-local-fixtures.mjs
index 36e4af30ac..d89409f86e 100644
--- a/packages/cli/test-utils/global-local-fixtures.mjs
+++ b/packages/cli/test-utils/global-local-fixtures.mjs
@@ -13,7 +13,8 @@
* file is a hard link to the unpacked package except a rewritten
* package.json, and its `node_modules` links to this package's installed
* dependencies, so a copy costs almost nothing and runs as the release it
- * is labeled.
+ * is labeled. `recyclePlacedCopies()` gives a test's unchanged copies back
+ * for the next test to move into place.
* - `globalCli(layout, version)` places one where a package manager or a Node
* version manager puts a global install, with an `astryx` command for the
* search path.
@@ -112,11 +113,83 @@ export function packedCli() {
}
const [{filename}] = JSON.parse(result.stdout);
const dir = path.join(out, 'package');
- extractTarball(path.join(out, filename), dir);
+ packedTarball = path.join(out, filename);
+ extractTarball(packedTarball, dir);
packed = dir;
+ packedRecord = treeRecord(dir, {contents: true});
return dir;
}
+/** The tarball {@link packedCli} made, to unpack again. */
+let packedTarball = '';
+
+/**
+ * The packed tree as {@link packedCli} unpacked it. Every copy shares its
+ * files, so a test that writes into one of them in place changes them all.
+ * @type {Map<string, string> | null}
+ */
+let packedRecord = null;
+
+/**
+ * `dir` and each entry below it by its path: its type and mode, and for a
+ * file its inode. A file no other copy links, or any file with `contents`,
+ * also records its size and modification time. A symbolic link records its
+ * target and is not followed.
+ * @param {string} dir
+ * @param {{contents?: boolean}} [options]
+ * @returns {Map<string, string>}
+ */
+function treeRecord(dir, {contents = false} = {}) {
+ /** @type {Map<string, string>} */
+ const record = new Map([
+ ['.', `dir ${fs.lstatSync(dir, {bigint: true}).mode}`],
+ ]);
+ /**
+ * @param {string} folder
+ * @param {string} rel
+ */
+ const walk = (folder, rel) => {
+ for (const entry of fs.readdirSync(folder, {withFileTypes: true})) {
+ const at = path.join(folder, entry.name);
+ const entryRel = rel ? `${rel}/${entry.name}` : entry.name;
+ if (entry.isSymbolicLink()) {
+ record.set(entryRel, `link ${fs.readlinkSync(at)}`);
+ continue;
+ }
+ const stat = fs.lstatSync(at, {bigint: true});
+ if (entry.isDirectory()) {
+ record.set(entryRel, `dir ${stat.mode}`);
+ walk(at, entryRel);
+ } else {
+ record.set(
+ entryRel,
+ contents || stat.nlink === 1n
+ ? `file ${stat.ino} ${stat.mode} ${stat.size} ${stat.mtimeNs}`
+ : `file ${stat.ino} ${stat.mode}`,
+ );
+ }
+ }
+ };
+ walk(dir, '');
+ return record;
+}
+
+/**
+ * The first path whose entry differs between two records, or null.
+ * @param {Map<string, string>} before
+ * @param {Map<string, string>} after
+ * @returns {string | null}
+ */
+function firstChange(before, after) {
+ for (const [rel, entry] of before) {
+ if (after.get(rel) !== entry) return rel;
+ }
+ for (const rel of after.keys()) {
+ if (!before.has(rel)) return rel;
+ }
+ return null;
+}
+
/**
* Hard-link every file under `from` into `to`, copying across devices. Each
* folder named in `shared`, by its path below `from`, is one link to that
@@ -150,7 +223,9 @@ function linkTree(from, to, shared = new Set(), rel = '') {
}
/**
- * Put a copy of the packed CLI at `dir`, labeled `version`.
+ * Put a copy of the packed CLI at `dir`, labeled `version`. A copy that an
+ * earlier test gave back with the same label and options is moved there;
+ * otherwise a new one is linked.
* @param {string} dir the package folder to create
* @param {string} version
* The copy leaves out the global copy's background Core step
@@ -160,6 +235,105 @@ function linkTree(from, to, shared = new Set(), rel = '') {
* @returns {{dir: string, bin: string}}
*/
export function placeCli(dir, version, options = {}) {
+ const key = JSON.stringify([
+ version,
+ Boolean(options.coreStep),
+ options.engines ?? null,
+ ]);
+ const ready = fs.existsSync(dir) ? undefined : pool.get(key)?.pop();
+ if (ready) {
+ fs.mkdirSync(path.dirname(dir), {recursive: true});
+ fs.renameSync(ready.dir, dir);
+ placed.push({dir, key, record: ready.record});
+ } else {
+ buildCopy(dir, version, options);
+ placed.push({dir, key, record: treeRecord(dir)});
+ }
+ return {dir, bin: path.join(dir, 'clients', 'cli', 'bin', 'astryx.mjs')};
+}
+
+/**
+ * Copies that tests gave back, by label and options, each with the record it
+ * was placed with. The next placement with the same key moves one.
+ * @type {Map<string, {dir: string, record: Map<string, string>}[]>}
+ */
+const pool = new Map();
+
+/**
+ * Copies placed since the last {@link recyclePlacedCopies}.
+ * @type {{dir: string, key: string, record: Map<string, string>}[]}
+ */
+const placed = [];
+
+/** Pooled copies made so far, for unique folder names. */
+let pooledCount = 0;
+
+/**
+ * Give each copy placed since the last call back to the pool. The next
+ * placement of its label then moves it instead of linking its files again.
+ * Call it after the test's background steps settle and before its folders go.
+ * A copy whose entries changed stays where it is, for its folder's removal.
+ * So does every copy when `keep` is false: a step that is still running may
+ * still use one.
+ * @param {{keep?: boolean}} [options]
+ * @throws {Error} when a test wrote into a file every copy shares. The pool is
+ * then emptied, and the package is unpacked again from its tarball.
+ */
+export function recyclePlacedCopies({keep = true} = {}) {
+ const copies = placed.splice(0);
+ if (packed && packedRecord) {
+ const changed = firstChange(
+ packedRecord,
+ treeRecord(packed, {contents: true}),
+ );
+ if (changed) {
+ pool.clear();
+ fs.rmSync(path.join(path.dirname(packed), 'pool'), {
+ recursive: true,
+ force: true,
+ });
+ fs.rmSync(packed, {recursive: true, force: true});
+ extractTarball(packedTarball, packed);
+ packedRecord = treeRecord(packed, {contents: true});
+ throw new Error(
+ `A test changed ${changed}, which every placed CLI copy shares. Unlink a copy's file before you write it, as placeCli does for package.json.`,
+ );
+ }
+ }
+ if (!keep) return;
+ for (const copy of copies) {
+ let record;
+ try {
+ record = treeRecord(copy.dir);
+ } catch {
+ continue;
+ }
+ if (firstChange(copy.record, record)) continue;
+ const spot = path.join(
+ path.dirname(packedCli()),
+ 'pool',
+ String(pooledCount++),
+ );
+ fs.mkdirSync(path.dirname(spot), {recursive: true});
+ try {
+ fs.renameSync(copy.dir, spot);
+ } catch {
+ // Another file system, or a read-only folder: the copy stays put.
+ continue;
+ }
+ const ready = pool.get(copy.key) ?? [];
+ ready.push({dir: spot, record: copy.record});
+ pool.set(copy.key, ready);
+ }
+}
+
+/**
+ * Link a new copy of the packed CLI at `dir`, labeled `version`.
+ * @param {string} dir
+ * @param {string} version
+ * @param {{engines?: Record<string, string>, coreStep?: boolean}} options
+ */
+function buildCopy(dir, version, options) {
const from = packedCli();
// Templates and icons are two thirds of the packed files, and no module
// there imports the CLI's code or packages. One link to each serves every
@@ -182,7 +356,6 @@ export function placeCli(dir, version, options = {}) {
path.join(dir, 'node_modules'),
process.platform === 'win32' ? 'junction' : 'dir',
);
- return {dir, bin: path.join(dir, 'clients', 'cli', 'bin', 'astryx.mjs')};
}
/**
diff --git a/packages/cli/test-utils/global-local-fixtures.test.mjs b/packages/cli/test-utils/global-local-fixtures.test.mjs
new file mode 100644
index 0000000000..38c5b61619
--- /dev/null
+++ b/packages/cli/test-utils/global-local-fixtures.test.mjs
@@ -0,0 +1,89 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Verifies that placed CLI copies are reused only when unchanged: a
+ * test's copy goes back to the pool and the next placement moves it. A copy a
+ * test changed, or one a running step may still use, is never reused. A write
+ * into a file every copy shares is reported, and the next copy comes from a
+ * fresh unpack.
+ */
+
+import {afterAll, afterEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {
+ CLI_DIR,
+ packedCli,
+ placeCli,
+ recyclePlacedCopies,
+} from './global-local-fixtures.mjs';
+import {cleanupFixtures, tempDir} from './release-fixtures.mjs';
+
+afterEach(() => {
+ try {
+ recyclePlacedCopies();
+ } finally {
+ cleanupFixtures();
+ }
+});
+afterAll(() => {
+ fs.rmSync(path.dirname(packedCli()), {recursive: true, force: true});
+});
+
+/**
+ * The inode of a placed copy's package.json, which each new copy writes.
+ * @param {string} dir
+ */
+function manifestInode(dir) {
+ return fs.statSync(path.join(dir, 'package.json')).ino;
+}
+
+describe('placed CLI copies', () => {
+ it('moves a copy a test gave back into the next placement of its label', () => {
+ const first = placeCli(path.join(tempDir('place'), 'cli'), '9.0.0');
+ const inode = manifestInode(first.dir);
+ recyclePlacedCopies();
+ const second = placeCli(path.join(tempDir('place'), 'cli'), '9.0.0');
+ expect(manifestInode(second.dir)).toBe(inode);
+ const other = placeCli(path.join(tempDir('place'), 'cli'), '9.0.1');
+ expect(manifestInode(other.dir)).not.toBe(inode);
+ });
+
+ it('never reuses a copy while a step may still use it', () => {
+ const first = placeCli(path.join(tempDir('place'), 'cli'), '9.0.2');
+ const inode = manifestInode(first.dir);
+ recyclePlacedCopies({keep: false});
+ const second = placeCli(path.join(tempDir('place'), 'cli'), '9.0.2');
+ expect(manifestInode(second.dir)).not.toBe(inode);
+ });
+
+ it('never reuses a copy whose folder mode a test changed', () => {
+ const first = placeCli(path.join(tempDir('place'), 'cli'), '9.0.3');
+ const inode = manifestInode(first.dir);
+ fs.chmodSync(path.join(first.dir, 'clients'), 0o555);
+ recyclePlacedCopies();
+ fs.chmodSync(path.join(first.dir, 'clients'), 0o755);
+ const second = placeCli(path.join(tempDir('place'), 'cli'), '9.0.3');
+ expect(manifestInode(second.dir)).not.toBe(inode);
+ });
+
+ it('never reuses a copy a test changed', () => {
+ const first = placeCli(path.join(tempDir('place'), 'cli'), '9.0.0');
+ fs.rmSync(first.bin);
+ recyclePlacedCopies();
+ const second = placeCli(path.join(tempDir('place'), 'cli'), '9.0.0');
+ expect(fs.existsSync(second.bin)).toBe(true);
+ });
+
+ it('reports a write into a shared file, and places the next copy from a fresh unpack', () => {
+ const first = placeCli(path.join(tempDir('place'), 'cli'), '9.0.0');
+ const rel = path.join('foundation', 'fs', 'paths.mjs');
+ // A write in place, with no unlink first, changes the packed file too.
+ fs.appendFileSync(path.join(first.dir, rel), '\n// changed\n');
+ expect(() => recyclePlacedCopies()).toThrow(/foundation\/fs\/paths\.mjs/);
+ const second = placeCli(path.join(tempDir('place'), 'cli'), '9.0.0');
+ expect(fs.readFileSync(path.join(second.dir, rel), 'utf8')).toBe(
+ fs.readFileSync(path.join(CLI_DIR, rel), 'utf8'),
+ );
+ });
+});
diff --git a/packages/cli/test/global-local.test.mjs b/packages/cli/test/global-local.test.mjs
index e702107930..820effa4f5 100644
--- a/packages/cli/test/global-local.test.mjs
+++ b/packages/cli/test/global-local.test.mjs
@@ -21,6 +21,7 @@ import {
globalCli,
packedCli,
placeCli,
+ recyclePlacedCopies,
seedPackedRelease,
startRegistry,
} from '../test-utils/global-local-fixtures.mjs';
@@ -56,7 +57,11 @@ const computers = [];
// the message below and its folders are still removed.
afterEach(async () => {
const busy = await settleBackgroundSteps(computers.splice(0));
- cleanupFixtures();
+ try {
+ recyclePlacedCopies({keep: busy.length === 0});
+ } finally {
+ cleanupFixtures();
+ }
if (busy.length > 0) {
throw new Error(
`A background step was still writing into ${busy.join(', ')} 60 s after the test: it is stuck.`,