@rtorcato/js-tooling 2.8.0 → 2.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/js-tooling",
-	"version": "2.8.0",
+	"version": "2.9.0",
 	"description": "JavaScript and TypeScript tooling for Node.js, React, Next.js, and Vitest.",
 	"type": "module",
 	"keywords": [
@@ -63,6 +63,10 @@
 		"tooling/vitest/vitest.setup.d.mts",
 		"tooling/vitest/jsdom-shims.mjs",
 		"tooling/vitest/jsdom-shims.d.mts",
+		"tooling/tests/exports-resolution.mjs",
+		"tooling/tests/exports-resolution.d.mts",
+		"tooling/tests/ssr-safety.mjs",
+		"tooling/tests/ssr-safety.d.mts",
 		"tooling/tsup/index.ts",
 		"tooling/biome/biome.json",
 		"tooling/semantic-release/*.mjs",
@@ -142,6 +146,14 @@
 		"./semantic-release/docker": {
 			"types": "./tooling/semantic-release/docker.d.mts",
 			"import": "./tooling/semantic-release/docker.mjs"
+		},
+		"./tests/exports-resolution": {
+			"types": "./tooling/tests/exports-resolution.d.mts",
+			"import": "./tooling/tests/exports-resolution.mjs"
+		},
+		"./tests/ssr-safety": {
+			"types": "./tooling/tests/ssr-safety.d.mts",
+			"import": "./tooling/tests/ssr-safety.mjs"
 		}
 	},
 	"dependencies": {

package/tooling/tests/exports-resolution.d.mts

@@ -0,0 +1,14 @@
+export interface ExportsResolutionTestOptions {
+	/** Absolute path to the package.json whose `exports` map will be validated. */
+	packageJsonPath: string
+	/** Absolute path to the source directory whose subfolders are cross-checked. */
+	srcDir: string
+	/** Folder names under `srcDir` to skip (e.g., `'tests'`, `'common'`). */
+	excludeDirs?: string[]
+}
+
+/**
+ * Asserts that a package.json `exports` map stays in sync with its source folders.
+ * Call from a Vitest test file; generates one describe block plus one it per folder.
+ */
+export function runExportsResolutionTest(options: ExportsResolutionTestOptions): void

package/tooling/tests/exports-resolution.mjs

@@ -0,0 +1,68 @@
+import { readdirSync, readFileSync } from 'node:fs'
+import { describe, expect, it } from 'vitest'
+
+/**
+ * Asserts that a package.json `exports` map stays in sync with its source folders.
+ *
+ * For every folder under `srcDir` (excluding `excludeDirs`), the package.json must
+ * expose a matching `./<name>` subpath export. Conversely, every subpath in the
+ * `exports` map (other than `.`) must point at a folder that exists in `srcDir`.
+ *
+ * Call this from a Vitest test file; it generates one `describe` block plus one
+ * `it` per folder, so failures pinpoint the drift.
+ *
+ * @example
+ * ```ts
+ * // src/tests/exports-resolution.test.ts
+ * import { fileURLToPath } from 'node:url'
+ * import { runExportsResolutionTest } from '@rtorcato/js-tooling/tests/exports-resolution'
+ *
+ * runExportsResolutionTest({
+ * 	packageJsonPath: fileURLToPath(new URL('../../package.json', import.meta.url)),
+ * 	srcDir: fileURLToPath(new URL('../', import.meta.url)),
+ * 	excludeDirs: ['tests'],
+ * })
+ * ```
+ *
+ * @param {object} options
+ * @param {string} options.packageJsonPath Absolute path to the package.json under test.
+ * @param {string} options.srcDir Absolute path to the source folder whose subdirectories should be cross-checked.
+ * @param {string[]} [options.excludeDirs] Folder names under `srcDir` to skip (e.g., `tests`, `common`).
+ */
+export function runExportsResolutionTest({ packageJsonPath, srcDir, excludeDirs = [] }) {
+	const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8'))
+
+	if (!pkg.exports || typeof pkg.exports !== 'object') {
+		throw new Error(`exports-resolution: package.json at ${packageJsonPath} has no exports map`)
+	}
+
+	const exportSubpaths = new Set(
+		Object.keys(pkg.exports)
+			.filter((k) => k !== '.')
+			.map((k) => k.replace(/^\.\//, ''))
+	)
+
+	const excluded = new Set(excludeDirs)
+	const moduleDirs = readdirSync(srcDir, { withFileTypes: true })
+		.filter((d) => d.isDirectory() && !excluded.has(d.name))
+		.map((d) => d.name)
+		.sort()
+
+	describe('package.json exports map', () => {
+		it('has at least one module', () => {
+			expect(moduleDirs.length).toBeGreaterThan(0)
+		})
+
+		for (const dir of moduleDirs) {
+			it(`exposes ./${dir}`, () => {
+				expect(exportSubpaths.has(dir)).toBe(true)
+			})
+		}
+
+		it('has no exports entries pointing at missing src/ folders', () => {
+			const moduleDirSet = new Set(moduleDirs)
+			const orphans = [...exportSubpaths].filter((k) => !moduleDirSet.has(k))
+			expect(orphans).toEqual([])
+		})
+	})
+}

package/tooling/tests/ssr-safety.d.mts

@@ -0,0 +1,14 @@
+export interface SsrSafetyTestOptions {
+	/** Absolute path to the source directory. */
+	srcDir: string
+	/** Folder names under `srcDir` to skip (e.g., `'tests'`, `'common'`). */
+	excludeDirs?: string[]
+	/** Entry filename inside each folder. Default: `'index.ts'`. */
+	moduleEntry?: string
+}
+
+/**
+ * Asserts that every module folder under `srcDir` can be imported in a Node
+ * environment without throwing. Call from a Vitest test file.
+ */
+export function runSsrSafetyTest(options: SsrSafetyTestOptions): void

package/tooling/tests/ssr-safety.mjs

@@ -0,0 +1,53 @@
+import { readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+/**
+ * Asserts that every module folder under `srcDir` can be imported in a Node
+ * environment without throwing (no DOM, no `window`, no `document`).
+ *
+ * For each folder under `srcDir` (excluding `excludeDirs`), the helper resolves
+ * `<srcDir>/<name>/<moduleEntry>` and `await import(...)` it. If the import
+ * throws or the module accesses a missing global at top level, the test fails.
+ *
+ * Use this as a contract test for libraries that promise SSR safety — i.e., that
+ * importing a module is always safe even when its underlying API isn't available.
+ *
+ * @example
+ * ```ts
+ * // src/tests/ssr-safety.test.ts (run with vitest --environment node)
+ * import { fileURLToPath } from 'node:url'
+ * import { runSsrSafetyTest } from '@rtorcato/js-tooling/tests/ssr-safety'
+ *
+ * runSsrSafetyTest({
+ * 	srcDir: fileURLToPath(new URL('../', import.meta.url)),
+ * 	excludeDirs: ['tests'],
+ * })
+ * ```
+ *
+ * @param {object} options
+ * @param {string} options.srcDir Absolute path to the source folder.
+ * @param {string[]} [options.excludeDirs] Folder names under `srcDir` to skip.
+ * @param {string} [options.moduleEntry] Entry filename inside each folder. Default: `'index.ts'`.
+ */
+export function runSsrSafetyTest({ srcDir, excludeDirs = [], moduleEntry = 'index.ts' }) {
+	const excluded = new Set(excludeDirs)
+	const moduleDirs = readdirSync(srcDir, { withFileTypes: true })
+		.filter((d) => d.isDirectory() && !excluded.has(d.name))
+		.map((d) => d.name)
+		.sort()
+
+	describe('SSR safety', () => {
+		it('has at least one module', () => {
+			expect(moduleDirs.length).toBeGreaterThan(0)
+		})
+
+		for (const dir of moduleDirs) {
+			it(`imports ./${dir}/${moduleEntry} without throwing`, async () => {
+				const moduleUrl = pathToFileURL(join(srcDir, dir, moduleEntry)).href
+				await expect(import(moduleUrl)).resolves.toBeDefined()
+			})
+		}
+	})
+}

package/tooling/vitest/vitest.config.mjs

@@ -11,13 +11,6 @@ export default defineConfig({
 		coverage: {
 			provider: 'v8',
 			reporter: ['text', 'json', 'html', 'json-summary'],
-			include: ['src/cli/generators/**/*.ts'],
-			thresholds: {
-				statements: 25,
-				lines: 25,
-				functions: 40,
-				branches: 17,
-			},
 		},
 	},
 	resolve: {