@riebeckite/test 0.0.6

package/dist/e2e/run.d.ts

@@ -0,0 +1,100 @@
+import { type RequiredInstallPath } from "./assertions.js";
+import { type Logger } from "./logger.js";
+import { type PackageSpec, type PackedPackages } from "./pack.js";
+import { type NodeNextProjectSpec } from "./stage.js";
+/** Fixture directories copied into the temporary workspace. */
+export interface ExternalSiteFixture {
+    /** Site fixture, copied to `<temp>/site`. */
+    site: string;
+    /** Vault fixture, copied to `<temp>/vault` (next to the site). */
+    vault: string;
+}
+/** One CLI invocation performed against the installed site. */
+export interface CliCommandSpec {
+    /** Positional arguments, e.g. `["inspect", "config"]`. */
+    args: readonly string[];
+    /** Optional assertion over the combined CLI output. */
+    assertOutput?: (output: string) => void;
+}
+/** A repo-specific programmatic check run after the generic install checks. */
+export type SiteCheck = (workspace: ExternalSiteWorkspace, logger: Logger) => void;
+/** The temporary workspace shared by the engine and the caller's callbacks. */
+export interface ExternalSiteWorkspace {
+    repoRoot: string;
+    tempRoot: string;
+    siteDir: string;
+    vaultDir: string;
+    tarballDir: string;
+    packed: PackedPackages;
+}
+/** Repo-specific assertions supplied by the driver. */
+export interface ExternalSiteAssertions {
+    /** Assert on the built `dist/` output (and, if needed, the vault). */
+    buildOutput(siteDir: string, vaultDir: string): void;
+}
+export interface ExternalSiteE2EConfig {
+    /** Absolute repository root. */
+    repoRoot: string;
+    /** Packages to pack and inject as local tarball dependencies. */
+    packages: readonly PackageSpec[];
+    /** Fixture site and vault directories. */
+    fixture: ExternalSiteFixture;
+    /** Absolute path to the undeclared-dependency checker script. */
+    dependencyCheckScript: string;
+    /** Published package scope, e.g. `"@riebeckite"`. */
+    scope: string;
+    /** CLI name shown in step lines, e.g. `"riebeckite"`. */
+    cliName: string;
+    /** Resolve the installed CLI entry point from the site directory. */
+    resolveCliEntry(siteDir: string): string;
+    /** CLI invocations, in order, run after the install checks. */
+    cliCommands: readonly CliCommandSpec[];
+    /** Directory (relative to the site) the CLI runs from. Defaults to the site. */
+    cliWorkingDirectory?: string;
+    /** TypeScript projects to type-check after the build. */
+    typecheckProjects?: readonly string[];
+    /** Extra type libraries beyond `node`; verified after writing. */
+    additionalTypeLibraries?: readonly string[];
+    /** Extra `exclude` entries for the bundler project. */
+    bundlerTypeExclude?: readonly string[];
+    /** NodeNext project whose `include` is replaced, or omitted to skip. */
+    nodeNextProject?: NodeNextProjectSpec;
+    /** Paths that must exist inside the isolated install. */
+    requiredInstallPaths?: readonly RequiredInstallPath[];
+    /** Directory site sources must not traverse into. Defaults to `packages`. */
+    monorepoPackagesDirectory?: string;
+    /** Repo-specific checks run after the generic install assertions. */
+    siteChecks?: readonly SiteCheck[];
+    /** Build-output assertion supplied by the driver. */
+    assertions: ExternalSiteAssertions;
+    /**
+     * Run after the build and type-checks, before the workspace is removed. Lets
+     * a driver reuse the packed tarballs for a secondary site.
+     */
+    afterSiteChecks?: (workspace: ExternalSiteWorkspace) => void | Promise<void>;
+    /** `pnpm pack` concurrency. Defaults to 4. */
+    concurrency?: number;
+    /** Logger label. Defaults to `"e2e"`. */
+    stepLabel?: string;
+    /** Final success message appended after `PASS: `. */
+    passMessage?: string;
+    /** Environment variable that keeps the temporary workspace. */
+    keepEnv: string;
+    /** Prefix for the temporary directory. Defaults to `"riebeckite-e2e-"`. */
+    tempPrefix?: string;
+    /** Logger to reuse; a new one is created when omitted. */
+    logger?: Logger;
+}
+/**
+ * Run the generic external-consumer end-to-end sequence:
+ *
+ * pack -> make temp workspace -> copy fixture -> write consumer manifest and
+ * tsconfig -> `npm install` -> isolation / escape-hatch / artifact /
+ * declared-dependency assertions -> repo-specific checks -> CLI checks ->
+ * build-output assertion -> type-checks -> optional `afterSiteChecks`.
+ *
+ * Everything repo-specific (repository root, package list, fixtures, marker
+ * assertions, CLI shape, keep-temp variable) is injected through `config`. The
+ * temporary workspace is removed in `finally` unless `config.keepEnv` is set.
+ */
+export declare function runExternalSiteE2E(config: ExternalSiteE2EConfig): Promise<void>;

package/dist/e2e/stage.d.ts

@@ -0,0 +1,55 @@
+import type { Logger } from "./logger.js";
+import type { PackedPackages } from "./pack.js";
+export interface StageIsolatedSiteOptions {
+    /** Fixture site directory copied to `siteDir`. */
+    fixtureSite: string;
+    /** Fixture vault directory copied to `vaultDir` (next to the site). */
+    fixtureVault: string;
+    /** Destination site directory. */
+    siteDir: string;
+    /** Destination vault directory. */
+    vaultDir: string;
+}
+/**
+ * Copy the fixture site and vault into the temporary workspace. The vault is
+ * staged next to the site, not inside it, so any code that assumes content
+ * lives under the site root fails immediately.
+ */
+export declare function stageIsolatedSite(options: StageIsolatedSiteOptions): void;
+/**
+ * Rewrite the staged site manifest so every packed package resolves to its
+ * local tarball. Packages already declared as dev dependencies stay there;
+ * everything else moves to `dependencies`. An `overrides` entry is added for
+ * each package so transitive requirements also resolve locally.
+ */
+export declare function writeFileDependencies(siteDir: string, packed: PackedPackages): void;
+/** A NodeNext TypeScript project to constrain after staging. */
+export interface NodeNextProjectSpec {
+    /** Config path relative to the site directory. */
+    config: string;
+    /** Replacement `include` entries. */
+    include: readonly string[];
+}
+export interface LayerExternalConsumerTypesOptions {
+    /**
+     * Type libraries to layer on top of the always-added `node` types. The
+     * engine verifies each one after writing.
+     */
+    additionalTypeLibraries: readonly string[];
+    /** Extra `exclude` entries for the bundler project. */
+    exclude?: readonly string[];
+    /** NodeNext project whose `include` is replaced, or omitted to skip. */
+    nodeNext?: NodeNextProjectSpec;
+    logger: Logger;
+}
+/**
+ * Layer the external-consumer type requirement onto the staged site before
+ * installation:
+ *
+ * - add `node` plus `additionalTypeLibraries` to `site/tsconfig.json` and
+ *   exclude the editor-only declarations;
+ * - optionally restrict a NodeNext project to its published-entry import test.
+ *
+ * Everything is verified after writing so a silent no-op cannot pass.
+ */
+export declare function layerExternalConsumerTypes(siteDir: string, options: LayerExternalConsumerTypesOptions): void;

package/dist/golden.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Dependency-free golden assertion for `node:test`.
+ *
+ * Node's built-in snapshot assertion (`t.assert.snapshot`) needs Node 22.3+,
+ * but Riebeckite supports Node 20.19+, so tests record expected output as
+ * committed golden files and compare against them here instead.
+ *
+ * A missing golden file fails the test. Run `pnpm test:update` at the
+ * repository root (or set `UPDATE_GOLDEN=1` for a single package) to write the
+ * current output.
+ */
+export interface GoldenOptions {
+    /**
+     * Normalize CRLF/CR to LF and collapse trailing newlines to one. Defaults to
+     * true so golden files stay stable across platforms and editors.
+     */
+    normalize?: boolean;
+    /** Extra context shown when the assertion fails. */
+    message?: string;
+}
+export declare function assertGolden(actual: string, golden: URL, options?: GoldenOptions): void;
+export declare function assertGoldenJson(value: unknown, golden: URL, options?: GoldenOptions): void;

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared unit-test utilities for Riebeckite packages.
+ *
+ * This entry point stays dependency-free and platform-neutral so any package
+ * can use it in its own `test/*.test.ts` without pulling in build tooling.
+ *
+ * The external-consumer end-to-end engine lives in the separate
+ * `@riebeckite/test/e2e` entry point because it orchestrates processes, the
+ * filesystem, and published tarballs.
+ */
+export { assertGolden, assertGoldenJson, type GoldenOptions, } from "./golden.js";

package/dist/index.js

@@ -0,0 +1,40 @@
+// golden.ts
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+function normalizeText(value) {
+  return `${value.replace(/\r\n?/g, "\n").replace(/\n+$/, "")}
+`;
+}
+function relative(file) {
+  return path.relative(process.cwd(), file) || file;
+}
+function assertGolden(actual, golden, options = {}) {
+  const normalize = options.normalize ?? true;
+  const value = normalize ? normalizeText(actual) : actual;
+  const file = fileURLToPath(golden);
+  const label = options.message ? `${options.message}: ` : "";
+  if (process.env.UPDATE_GOLDEN === "1") {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, value, "utf8");
+    return;
+  }
+  assert.ok(
+    fs.existsSync(file),
+    `${label}Missing golden file ${relative(file)}. Run \`pnpm test:update\` to create it.`
+  );
+  const recorded = fs.readFileSync(file, "utf8");
+  assert.equal(
+    value,
+    normalize ? normalizeText(recorded) : recorded,
+    `${label}Golden mismatch for ${relative(file)}. Run \`pnpm test:update\` to accept the new output.`
+  );
+}
+function assertGoldenJson(value, golden, options = {}) {
+  assertGolden(JSON.stringify(value, null, 2), golden, options);
+}
+export {
+  assertGolden,
+  assertGoldenJson
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@riebeckite/test",
+  "version": "0.0.6",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "source": "./index.ts",
+      "default": "./dist/index.js"
+    },
+    "./e2e": {
+      "types": "./dist/e2e/index.d.ts",
+      "import": "./dist/e2e/index.js",
+      "source": "./e2e/index.ts",
+      "default": "./dist/e2e/index.js"
+    }
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "README_ja.md",
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "tsx": "^4.22.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Rerurate514/riebeckite.git",
+    "directory": "packages/test"
+  },
+  "homepage": "https://github.com/Rerurate514/riebeckite#readme",
+  "bugs": {
+    "url": "https://github.com/Rerurate514/riebeckite/issues"
+  },
+  "description": "Shared test utilities and a generic external-site end-to-end engine for Riebeckite packages.",
+  "keywords": [
+    "riebeckite",
+    "testing",
+    "test-utilities",
+    "golden",
+    "e2e"
+  ],
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "node ../../scripts/build_package.mjs",
+    "test": "node --import tsx --test \"test/*.test.ts\""
+  }
+}