@stealthscale/tool-testing 0.1.0

package/README.md

@@ -0,0 +1,17 @@
+# @stealthscale/tool-testing
+
+A **kit**: a dev-time library another repository takes.
+
+Builds a scratch workspace in the temporary directory, writes the manifests that go in it,
+and measures what a rendered element draws. A guard's spec, a package's spec, a story and a
+repository's own conformance spec all reach for the same three.
+
+A spec that reads the real workspace states the rule and derives its expectation from the
+tree. A spec that writes its own scratch workspace in `tmpdir` may pin exact counts and
+names, because it wrote them.
+
+## Install
+
+```sh
+bun add -d @stealthscale/tool-testing
+```

package/dist/index.d.mts

@@ -0,0 +1,186 @@
+//#region src/scratch.d.ts
+/**
+ * @fileoverview Builds a scratch workspace in the temporary directory for a specification
+ * that reads a tree: a guard, a generator, a release step. The spec writes the files it
+ * needs, runs the code under test against the directory, and removes it.
+ */
+/**
+ * Maps a path relative to the workspace root to the content of the file at that path.
+ */
+type ScratchFiles = Readonly<Record<string, string>>;
+/**
+ * Owns a temporary directory for a specification: writes into it, reads from it, lists it
+ * and removes it. `scratchWorkspace` creates one.
+ */
+declare class ScratchWorkspace {
+  /**
+   * Holds the absolute path of the directory.
+   */
+  readonly root: string;
+  /**
+   * Wraps a directory that already exists. `scratchWorkspace` calls this; a specification
+   * does not.
+   *
+   * @param {string} root - The absolute path of the directory.
+   */
+  constructor(root: string);
+  /**
+   * Lists every file below the root as a path relative to it, with `/` as the separator.
+   *
+   * @returns {string[]} The paths, sorted.
+   */
+  files(): string[];
+  /**
+   * Resolves a path relative to the root into an absolute one.
+   *
+   * @param {string} relative - The path to resolve.
+   * @returns {string} The absolute path.
+   * @throws {Error} When the path leaves the root.
+   */
+  path(relative: string): string;
+  /**
+   * Reads a file as UTF-8 text.
+   *
+   * @param {string} relative - The path to read.
+   * @returns {string} The file's content.
+   * @throws {Error} When the file does not exist or the path leaves the root.
+   */
+  read(relative: string): string;
+  /**
+   * Removes the directory and everything in it. A second call does nothing.
+   */
+  remove(): void;
+  /**
+   * Writes files, creating the directories they sit in. An existing file is overwritten.
+   *
+   * @param {ScratchFiles} files - The content per path.
+   * @throws {Error} When a path leaves the root.
+   */
+  write(files: ScratchFiles): void;
+}
+/**
+ * Creates a scratch workspace in the temporary directory and writes the files given.
+ *
+ * @param {ScratchFiles} [files] - The files to write first. Default: none.
+ * @returns {ScratchWorkspace} The workspace. The caller removes it.
+ */
+declare function scratchWorkspace(files?: ScratchFiles): ScratchWorkspace;
+/**
+ * Runs a function against a scratch workspace and removes the workspace afterwards, whether
+ * the function returned or threw.
+ *
+ * @template Result - The type the function returns.
+ * @param {ScratchFiles} files - The files to write first.
+ * @param {(workspace: ScratchWorkspace) => Result} run - The function to run.
+ * @returns {Result} The function's return value.
+ */
+declare function withScratchWorkspace<Result>(files: ScratchFiles, run: (workspace: ScratchWorkspace) => Result): Result;
+/**
+ * Runs an asynchronous function against a scratch workspace and removes the workspace after
+ * it settles, whether it resolved or rejected.
+ *
+ * @template Result - The type the function resolves to.
+ * @param {ScratchFiles} files - The files to write first.
+ * @param {(workspace: ScratchWorkspace) => Promise<Result>} run - The function to run.
+ * @returns {Promise<Result>} The value the function resolved to.
+ */
+declare function withScratchWorkspaceAsync<Result>(files: ScratchFiles, run: (workspace: ScratchWorkspace) => Promise<Result>): Promise<Result>;
+//#endregion
+//#region src/manifest.d.ts
+/**
+ * Holds the fields of a scratch manifest. Beyond the name, a field is whatever the
+ * specification needs the code under test to read.
+ */
+interface ManifestFields {
+  /**
+   * Names the package.
+   */
+  readonly name: string;
+  readonly [field: string]: unknown;
+}
+/**
+ * Serialises a manifest the way a package manager writes one: two-space indentation and a
+ * final newline.
+ *
+ * @param {ManifestFields} fields - The fields to write. `version` defaults to `0.0.0`.
+ * @returns {string} The JSON text.
+ */
+declare function manifest(fields: ManifestFields): string;
+/**
+ * Builds the files of one package under a directory: its manifest, and any other files at
+ * paths relative to that directory.
+ *
+ * @param {string} directory - The package's directory, relative to the workspace root.
+ * @param {ManifestFields} fields - The fields to write into the manifest.
+ * @param {ScratchFiles} [files] - Other files of the package, relative to its directory. Default: none.
+ * @returns {ScratchFiles} Every file of the package, keyed relative to the workspace root.
+ */
+declare function packageFiles(directory: string, fields: ManifestFields, files?: ScratchFiles): ScratchFiles;
+/**
+ * Builds the root manifest of a workspace: private, named `root`, with the globs given.
+ *
+ * @param {readonly string[]} workspaces - The workspace globs: `core/*`, `tools/*`.
+ * @param {Readonly<Record<string, unknown>>} [fields] - Other root fields, such as a catalog or devDependencies. Default: none.
+ * @returns {ScratchFiles} The root `package.json`.
+ */
+declare function workspaceFiles(workspaces: readonly string[], fields?: Readonly<Record<string, unknown>>): ScratchFiles;
+//#endregion
+//#region src/measure.d.ts
+/**
+ * @fileoverview Reads geometry off a rendered element, so a specification asserts what a
+ * reader would see rather than what a class name promises.
+ */
+/**
+ * Describes the box a measurement reads: the two inline edges of a rendered element.
+ */
+interface Box {
+  /**
+   * Holds the distance from the viewport's left edge to the element's, in pixels.
+   */
+  left: number;
+  /**
+   * Holds the distance from the viewport's left edge to the element's right edge, in pixels.
+   */
+  right: number;
+}
+/**
+ * Names what a measurement needs of an element: its box, and nothing else.
+ *
+ * Structural rather than `Element`, for two reasons. This package compiles without the DOM
+ * library, and a specification states the boxes it is measuring instead of laying out a
+ * document, which jsdom reports as zero anyway. A real element satisfies it, because
+ * `DOMRect` carries both edges.
+ */
+interface Measured {
+  /**
+   * Reads the element's box.
+   *
+   * @returns {Box} The box the element currently occupies.
+   */
+  getBoundingClientRect: () => Box;
+}
+/**
+ * Reads a CSS length as a number.
+ *
+ * `getComputedStyle` answers in `px` strings. A comparison against `NaN` is false rather than
+ * loud, so a measurement that failed to parse would pass while measuring nothing. The
+ * conversion lives here once, and a length with no number in it reads as `0`.
+ *
+ * @param {string} length - A computed length, with its unit.
+ * @returns {number} The number in front of the unit. `0` for a length with no number.
+ */
+declare function pixels(length: string): number;
+/**
+ * Measures how far apart two elements sit in the inline direction.
+ *
+ * Zero means flush: a shared border rather than a gap, which is the claim a segmented control
+ * makes. Reading it from the boxes rather than from a class catches the day the rounding and
+ * the border stop agreeing.
+ *
+ * @param {Measured} first - The left-hand element in a row.
+ * @param {Measured} second - The element after it.
+ * @returns {number} The gap between them, in pixels. Never negative.
+ */
+declare function seamBetween(first: Measured, second: Measured): number;
+//#endregion
+export { type Box, type ManifestFields, type Measured, type ScratchFiles, type ScratchWorkspace, manifest, packageFiles, pixels, scratchWorkspace, seamBetween, withScratchWorkspace, withScratchWorkspaceAsync, workspaceFiles };

package/dist/index.mjs

@@ -0,0 +1,210 @@
+import { mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve, sep } from "node:path";
+//#region src/scratch.ts
+/**
+* @fileoverview Builds a scratch workspace in the temporary directory for a specification
+* that reads a tree: a guard, a generator, a release step. The spec writes the files it
+* needs, runs the code under test against the directory, and removes it.
+*/
+/**
+* Lists every file below a directory.
+*
+* @param {string} directory - The directory to walk, absolute.
+* @param {string} prefix - The directory's path relative to the root. It ends in `/`, or is empty for the root.
+* @returns {string[]} The paths relative to the root, in directory order.
+*/
+function walk(directory, prefix) {
+	return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => entry.isDirectory() ? walk(join(directory, entry.name), `${prefix}${entry.name}/`) : [`${prefix}${entry.name}`]);
+}
+/**
+* Owns a temporary directory for a specification: writes into it, reads from it, lists it
+* and removes it. `scratchWorkspace` creates one.
+*/
+var ScratchWorkspace = class {
+	/**
+	* Holds the absolute path of the directory.
+	*/
+	root;
+	/**
+	* Wraps a directory that already exists. `scratchWorkspace` calls this; a specification
+	* does not.
+	*
+	* @param {string} root - The absolute path of the directory.
+	*/
+	constructor(root) {
+		this.root = root;
+	}
+	/**
+	* Lists every file below the root as a path relative to it, with `/` as the separator.
+	*
+	* @returns {string[]} The paths, sorted.
+	*/
+	files() {
+		return walk(this.root, "").toSorted();
+	}
+	/**
+	* Resolves a path relative to the root into an absolute one.
+	*
+	* @param {string} relative - The path to resolve.
+	* @returns {string} The absolute path.
+	* @throws {Error} When the path leaves the root.
+	*/
+	path(relative) {
+		const target = resolve(this.root, relative);
+		if (target !== this.root && !target.startsWith(this.root + sep)) throw new Error(`${relative} leaves the scratch workspace`);
+		return target;
+	}
+	/**
+	* Reads a file as UTF-8 text.
+	*
+	* @param {string} relative - The path to read.
+	* @returns {string} The file's content.
+	* @throws {Error} When the file does not exist or the path leaves the root.
+	*/
+	read(relative) {
+		return readFileSync(this.path(relative), "utf8");
+	}
+	/**
+	* Removes the directory and everything in it. A second call does nothing.
+	*/
+	remove() {
+		rmSync(this.root, {
+			force: true,
+			recursive: true
+		});
+	}
+	/**
+	* Writes files, creating the directories they sit in. An existing file is overwritten.
+	*
+	* @param {ScratchFiles} files - The content per path.
+	* @throws {Error} When a path leaves the root.
+	*/
+	write(files) {
+		for (const [relative, content] of Object.entries(files)) {
+			const target = this.path(relative);
+			mkdirSync(dirname(target), { recursive: true });
+			writeFileSync(target, content);
+		}
+	}
+};
+/**
+* Creates a scratch workspace in the temporary directory and writes the files given.
+*
+* @param {ScratchFiles} [files] - The files to write first. Default: none.
+* @returns {ScratchWorkspace} The workspace. The caller removes it.
+*/
+function scratchWorkspace(files = {}) {
+	const workspace = new ScratchWorkspace(mkdtempSync(join(tmpdir(), "stealth-")));
+	workspace.write(files);
+	return workspace;
+}
+/**
+* Runs a function against a scratch workspace and removes the workspace afterwards, whether
+* the function returned or threw.
+*
+* @template Result - The type the function returns.
+* @param {ScratchFiles} files - The files to write first.
+* @param {(workspace: ScratchWorkspace) => Result} run - The function to run.
+* @returns {Result} The function's return value.
+*/
+function withScratchWorkspace(files, run) {
+	const workspace = scratchWorkspace(files);
+	try {
+		return run(workspace);
+	} finally {
+		workspace.remove();
+	}
+}
+/**
+* Runs an asynchronous function against a scratch workspace and removes the workspace after
+* it settles, whether it resolved or rejected.
+*
+* @template Result - The type the function resolves to.
+* @param {ScratchFiles} files - The files to write first.
+* @param {(workspace: ScratchWorkspace) => Promise<Result>} run - The function to run.
+* @returns {Promise<Result>} The value the function resolved to.
+*/
+async function withScratchWorkspaceAsync(files, run) {
+	const workspace = scratchWorkspace(files);
+	try {
+		return await run(workspace);
+	} finally {
+		workspace.remove();
+	}
+}
+//#endregion
+//#region src/manifest.ts
+/**
+* Serialises a manifest the way a package manager writes one: two-space indentation and a
+* final newline.
+*
+* @param {ManifestFields} fields - The fields to write. `version` defaults to `0.0.0`.
+* @returns {string} The JSON text.
+*/
+function manifest(fields) {
+	return `${JSON.stringify({
+		version: "0.0.0",
+		...fields
+	}, null, 2)}\n`;
+}
+/**
+* Builds the files of one package under a directory: its manifest, and any other files at
+* paths relative to that directory.
+*
+* @param {string} directory - The package's directory, relative to the workspace root.
+* @param {ManifestFields} fields - The fields to write into the manifest.
+* @param {ScratchFiles} [files] - Other files of the package, relative to its directory. Default: none.
+* @returns {ScratchFiles} Every file of the package, keyed relative to the workspace root.
+*/
+function packageFiles(directory, fields, files = {}) {
+	const entries = [[`${directory}/package.json`, manifest(fields)], ...Object.entries(files).map(([path, content]) => [`${directory}/${path}`, content])];
+	return Object.fromEntries(entries);
+}
+/**
+* Builds the root manifest of a workspace: private, named `root`, with the globs given.
+*
+* @param {readonly string[]} workspaces - The workspace globs: `core/*`, `tools/*`.
+* @param {Readonly<Record<string, unknown>>} [fields] - Other root fields, such as a catalog or devDependencies. Default: none.
+* @returns {ScratchFiles} The root `package.json`.
+*/
+function workspaceFiles(workspaces, fields = {}) {
+	return { "package.json": manifest({
+		name: "root",
+		private: true,
+		workspaces: [...workspaces],
+		...fields
+	}) };
+}
+//#endregion
+//#region src/measure.ts
+/**
+* Reads a CSS length as a number.
+*
+* `getComputedStyle` answers in `px` strings. A comparison against `NaN` is false rather than
+* loud, so a measurement that failed to parse would pass while measuring nothing. The
+* conversion lives here once, and a length with no number in it reads as `0`.
+*
+* @param {string} length - A computed length, with its unit.
+* @returns {number} The number in front of the unit. `0` for a length with no number.
+*/
+function pixels(length) {
+	const value = Number.parseFloat(length);
+	return Number.isNaN(value) ? 0 : value;
+}
+/**
+* Measures how far apart two elements sit in the inline direction.
+*
+* Zero means flush: a shared border rather than a gap, which is the claim a segmented control
+* makes. Reading it from the boxes rather than from a class catches the day the rounding and
+* the border stop agreeing.
+*
+* @param {Measured} first - The left-hand element in a row.
+* @param {Measured} second - The element after it.
+* @returns {number} The gap between them, in pixels. Never negative.
+*/
+function seamBetween(first, second) {
+	return Math.abs(second.getBoundingClientRect().left - first.getBoundingClientRect().right);
+}
+//#endregion
+export { manifest, packageFiles, pixels, scratchWorkspace, seamBetween, withScratchWorkspace, withScratchWorkspaceAsync, workspaceFiles };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@stealthscale/tool-testing",
+  "version": "0.1.0",
+  "description": "Builds the scratch workspace a specification reads a tree from, writes the manifests in it, and measures what a rendered element draws.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stealth-scale/tooling.git",
+    "directory": "tools/testing"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "imports": {
+    "#*": "./src/*"
+  },
+  "exports": {
+    ".": {
+      "tooling-source": "./src/index.ts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": "./dist/index.mjs",
+      "./package.json": "./package.json"
+    },
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vp pack src/index.ts"
+  },
+  "devDependencies": {
+    "@stealthscale/tool-config": "^0.1.0"
+  }
+}