@describe-me/vitest 0.5.0 → 0.5.1

package/README.md

@@ -10,6 +10,9 @@ reporter that writes `.describe-me/`.
 pnpm add -D @describe-me/vitest @describe-me/react describe-me
 ```
 
+All describe-me packages must be on the same version
+([Add it to your project](https://github.com/grzehub/describe-me#add-it-to-your-project)).
+
 ## Usage
 
 One line in the Vitest config registers the setup file and the reporter, and

package/dist/asset-store.js

@@ -1,7 +1,8 @@
 import { createHash } from 'node:crypto';
-import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync, } from 'node:fs';
 import { dirname, extname, join, resolve, sep } from 'node:path';
 import { ASSET_URL_PREFIX } from '@describe-me/core/types';
+import { collectableFiles } from './collectable-files.js';
 import { cssAssetReferences } from './css-asset-references.js';
 import { rewriteCssReferences } from './rewrite-css-references.js';
 import { rewriteHeadReferences } from './rewrite-head-references.js';
@@ -233,7 +234,7 @@ export class AssetStore {
      * re-run were rewritten by an earlier run.
      */
     collectGarbage(files, inlineTexts = []) {
-        const stored = readdirSync(this.dir);
+        const stored = collectableFiles(this.dir);
         if (stored.length === 0) {
             return;
         }

package/dist/collectable-files.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The names of the entries in `dir` that garbage collection may delete. No
+ * store writes a folder, so a folder belongs to someone else and is left out.
+ */
+export declare function collectableFiles(dir: string): string[];

package/dist/collectable-files.js

@@ -0,0 +1,10 @@
+import { readdirSync } from 'node:fs';
+/**
+ * The names of the entries in `dir` that garbage collection may delete. No
+ * store writes a folder, so a folder belongs to someone else and is left out.
+ */
+export function collectableFiles(dir) {
+    return readdirSync(dir, { withFileTypes: true })
+        .filter((entry) => !entry.isDirectory())
+        .map((entry) => entry.name);
+}

package/dist/plugin.d.ts

@@ -25,7 +25,9 @@ export interface DescribeMeOptions {
      * DOM environments only. Load the browser build of styled-components (v5+)
      * instead of the Node one, whose `createGlobalStyle` never inserts its CSS on
      * the client: global resets and fonts would be missing from every snapshot.
-     * Applied when styled-components is installed. Default: true.
+     * Applied when styled-components is installed. For 6.0 to 6.3 it also points
+     * `tslib` at the `tslib.es6.mjs` they resolve, so the optimizer keeps its
+     * exports. Default: true.
      */
     styledComponentsBrowserBuild?: boolean;
     /**

package/dist/plugin.js

@@ -4,7 +4,7 @@ import { projectModulePath } from './project-module-path.js';
 import { registerExports } from './register-exports.js';
 import DescribeMeReporter from './reporter.js';
 import { RUNTIME_OPTIONS_KEY } from './runtime-options.js';
-import { styledComponentsBrowserBuild } from './styled-components-browser-build.js';
+import { styledComponentsBrowserBuild, } from './styled-components-browser-build.js';
 import { validateRenderFrame } from './validate-render-frame.js';
 /** For each framework and environment: the render module tests import, and our adapter that wraps it. */
 const RENDER_MODULES = {
@@ -49,7 +49,7 @@ function browserConfig(renderModule) {
         },
     };
 }
-function domConfig(userConfig, options) {
+function domConfig(userConfig, styledComponents) {
     const userTest = userConfig.test;
     const test = {
         setupFiles: ['@describe-me/vitest/setup-dom'],
@@ -65,14 +65,19 @@ function domConfig(userConfig, options) {
     else if (userTest.css === false) {
         console.warn('describe-me: `test.css` is false, so imported stylesheets are stubbed and will be missing from the snapshots.');
     }
-    const styledComponents = options.styledComponentsBrowserBuild === false
-        ? undefined
-        : styledComponentsBrowserBuild(userConfig.root ?? process.cwd());
     if (!styledComponents) {
         return { test };
     }
     console.info('describe-me: using the browser build of styled-components, for createGlobalStyle');
-    return { resolve: styledComponents.resolve, test: { ...test, ...styledComponents.test } };
+    const { config } = styledComponents;
+    return { resolve: config.resolve, test: { ...test, ...config.test } };
+}
+/** Looked up before the reporter is created, which needs its warning. */
+function styledComponentsFor(environment, userConfig, options) {
+    if (environment !== 'dom' || options.styledComponentsBrowserBuild === false) {
+        return undefined;
+    }
+    return styledComponentsBrowserBuild(userConfig.root ?? process.cwd());
 }
 /**
  * One-line integration: `plugins: [describeMe()]`.
@@ -110,16 +115,21 @@ export function describeMe(options = {}) {
                 renderFrame: validateRenderFrame(options.renderFrame),
             };
             const provide = { [RUNTIME_OPTIONS_KEY]: runtimeOptions };
+            const styledComponents = styledComponentsFor(environment, userConfig, options);
+            const setupWarnings = styledComponents?.warning ? [styledComponents.warning] : [];
             const reporter = new DescribeMeReporter({
                 outDir,
                 include: options.include,
                 exclude: options.exclude,
                 previewHead: options.previewHead,
+                setupWarnings,
             });
             // Vite concatenates arrays when merging, so only add `default` when the
             // user has not chosen their own reporters; otherwise they would lose it.
             const reporters = userConfig.test?.reporters ? [reporter] : ['default', reporter];
-            const config = environment === 'browser' ? browserConfig(renderModule) : domConfig(userConfig, options);
+            const config = environment === 'browser'
+                ? browserConfig(renderModule)
+                : domConfig(userConfig, styledComponents);
             return { ...config, test: { ...config.test, reporters, provide } };
         },
         async resolveId(source, importer) {

package/dist/print-diagnostics.d.ts

@@ -1,8 +1,9 @@
 import type { Manifest } from '@describe-me/core/types';
 /**
- * Warn, one line per kind, about what the manifest could not document. Prints
- * nothing when everything is named, documented and loadable, every font is
- * loaded and no stylesheet comes from a remote host. The viewer shows the same
- * list in its header.
+ * Warn about what the manifest could not document, one line per kind. Setup
+ * warnings come first, one line each, because they can explain failing tests.
+ * Prints nothing when the setup is sound, everything is named, documented and
+ * loadable, every font is loaded and no stylesheet comes from a remote host.
+ * The viewer shows the same list in its header.
  */
 export declare function printDiagnostics(manifest: Manifest): void;

package/dist/print-diagnostics.js

@@ -13,13 +13,17 @@ function plural(count, one, many) {
     return `${count} ${count === 1 ? one : many}`;
 }
 /**
- * Warn, one line per kind, about what the manifest could not document. Prints
- * nothing when everything is named, documented and loadable, every font is
- * loaded and no stylesheet comes from a remote host. The viewer shows the same
- * list in its header.
+ * Warn about what the manifest could not document, one line per kind. Setup
+ * warnings come first, one line each, because they can explain failing tests.
+ * Prints nothing when the setup is sound, everything is named, documented and
+ * loadable, every font is loaded and no stylesheet comes from a remote host.
+ * The viewer shows the same list in its header.
  */
 export function printDiagnostics(manifest) {
-    const { anonymous, undocumented, assetsMissing, fontsMissing, remoteStylesheets } = manifestDiagnostics(manifest);
+    const { setupWarnings, anonymous, undocumented, assetsMissing, fontsMissing, remoteStylesheets } = manifestDiagnostics(manifest);
+    for (const warning of setupWarnings) {
+        console.warn(`describe-me: ${warning}`);
+    }
     if (anonymous.length > 0) {
         console.warn(`describe-me: ${plural(anonymous.length, 'test renders', 'tests render')} an anonymous component; export it from a project module or give it a displayName`);
     }

package/dist/read-generator.d.ts

@@ -0,0 +1,7 @@
+import type { ManifestGenerator } from '@describe-me/core/types';
+/**
+ * The name and version of this package, for the manifest's `generator`, or
+ * `undefined` when its package.json cannot be read, so the manifest is still
+ * written.
+ */
+export declare function readGenerator(): ManifestGenerator | undefined;

package/dist/read-generator.js

@@ -0,0 +1,21 @@
+import { readFileSync } from 'node:fs';
+/**
+ * The name and version of this package, for the manifest's `generator`, or
+ * `undefined` when its package.json cannot be read, so the manifest is still
+ * written.
+ */
+export function readGenerator() {
+    try {
+        // The compiled file sits in `dist/`, one level below the package root, and
+        // `exports` does not list `./package.json`.
+        const file = new URL('../package.json', import.meta.url);
+        const { name, version } = JSON.parse(readFileSync(file, 'utf8'));
+        if (typeof name !== 'string' || typeof version !== 'string') {
+            return undefined;
+        }
+        return { name, version };
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/reporter.d.ts

@@ -18,11 +18,15 @@ export interface DescribeMeReporterOptions {
      * Project files it links are copied into the output directory. Default: none.
      */
     previewHead?: string;
+    /** Problems in the project's setup, filled by the plugin. Default: none. */
+    setupWarnings?: string[];
 }
 export default class DescribeMeReporter implements Reporter {
     private readonly outDirOption;
     private readonly isRecordedFile;
     private readonly previewHead;
+    private readonly generator;
+    private readonly setupWarnings;
     private root;
     private outDir;
     private snapshots;

package/dist/reporter.js

@@ -13,6 +13,7 @@ import { fileFilter } from './file-filter.js';
 import { FontAudit } from './font-audit.js';
 import { isRecordedTest } from './is-recorded-test.js';
 import { printDiagnostics } from './print-diagnostics.js';
+import { readGenerator } from './read-generator.js';
 import { SnapshotStore } from './snapshot-store.js';
 import { stableTestIds } from './stable-test-ids.js';
 import { StyleStore } from './style-store.js';
@@ -27,6 +28,8 @@ export default class DescribeMeReporter {
     outDirOption;
     isRecordedFile;
     previewHead;
+    generator;
+    setupWarnings;
     root = process.cwd();
     outDir = '';
     snapshots;
@@ -42,6 +45,8 @@ export default class DescribeMeReporter {
         });
         // A blank head, such as an empty preview-head.html, is the same as none.
         this.previewHead = options.previewHead?.trim() ? options.previewHead : undefined;
+        this.generator = readGenerator();
+        this.setupWarnings = options.setupWarnings ?? [];
     }
     onInit(vitest) {
         this.root = vitest.config.root;
@@ -136,6 +141,7 @@ export default class DescribeMeReporter {
         const assetsMissing = this.assets.missing();
         const manifest = {
             version: 1,
+            generator: this.generator,
             generatedAt: new Date().toISOString(),
             root: this.root,
             modules,
@@ -150,6 +156,10 @@ export default class DescribeMeReporter {
         const styleFiles = this.styles.collectGarbage(snapshotFiles);
         this.assets.collectGarbage([...snapshotFiles, ...styleFiles], head === undefined ? [] : [head]);
         this.auditFonts(manifest);
+        // Never seeded from the last run: the plugin checks the setup on every start.
+        if (this.setupWarnings.length > 0) {
+            manifest.setupWarnings = this.setupWarnings;
+        }
         writeFileSync(join(this.outDir, 'manifest.json'), JSON.stringify(manifest, null, 2));
         printDiagnostics(manifest);
     }

package/dist/snapshot-store.js

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
-import { existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { collectableFiles } from './collectable-files.js';
 /**
  * Content-addressed store for the serialized DOM of every frame, living in
  * `<outDir>/snapshots`. Identical DOM across tests or runs is written once.
@@ -27,7 +28,7 @@ export class SnapshotStore {
         for (const path of referenced) {
             keep.add(path.replace('snapshots/', ''));
         }
-        for (const file of readdirSync(this.dir)) {
+        for (const file of collectableFiles(this.dir)) {
             if (!keep.has(file)) {
                 rmSync(join(this.dir, file), { force: true });
             }

package/dist/style-store.js

@@ -1,7 +1,8 @@
 import { createHash } from 'node:crypto';
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { STYLE_URL_PREFIX } from '@describe-me/core/types';
+import { collectableFiles } from './collectable-files.js';
 import { splitStylesheet } from './split-stylesheet.js';
 /** Shorter sheets stay inline, where they cost less than a reference and a file of their own. */
 const MIN_EXTRACTED_LENGTH = 256;
@@ -54,7 +55,7 @@ export class StyleStore {
             }
         }
         const kept = [];
-        for (const file of readdirSync(this.dir)) {
+        for (const file of collectableFiles(this.dir)) {
             if (keep.has(file)) {
                 kept.push(`styles/${file}`);
             }

package/dist/styled-components-browser-build.d.ts

@@ -1,4 +1,10 @@
 import type { ViteUserConfig } from 'vitest/config';
+/** The config that loads the browser build, and a setup problem found on the way. */
+export interface StyledComponentsBrowserBuild {
+    config: ViteUserConfig;
+    /** Set when the build's tslib cannot be aliased, so it may fail to load. */
+    warning?: string;
+}
 /**
  * The Vite and Vitest config that makes a DOM environment load the browser
  * build of styled-components, or undefined when the project does not use
@@ -11,5 +17,9 @@ import type { ViteUserConfig } from 'vitest/config';
  * styled-components through Node, which ignores the alias, and would get a
  * second instance whose styles its serializer cannot see. Bundling both
  * together gives them one.
+ *
+ * The optimizer bundles tslib's UMD file without its default export, which the
+ * browser build of 6.0 to 6.3 destructures. An alias is the only resolution the
+ * optimizer applies, so `tslib` is aliased to its ES module for the whole config.
  */
-export declare function styledComponentsBrowserBuild(root: string): ViteUserConfig | undefined;
+export declare function styledComponentsBrowserBuild(root: string): StyledComponentsBrowserBuild | undefined;

package/dist/styled-components-browser-build.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join, resolve } from 'node:path';
+import { styledComponentsTslib } from './styled-components-tslib.js';
 function resolverFor(root) {
     // createRequire wants an absolute file inside the directory; it does not have to exist.
     const requireFromRoot = createRequire(join(resolve(root), 'package.json'));
@@ -41,6 +42,10 @@ function browserModule(pkg) {
  * styled-components through Node, which ignores the alias, and would get a
  * second instance whose styles its serializer cannot see. Bundling both
  * together gives them one.
+ *
+ * The optimizer bundles tslib's UMD file without its default export, which the
+ * browser build of 6.0 to 6.3 destructures. An alias is the only resolution the
+ * optimizer applies, so `tslib` is aliased to its ES module for the whole config.
  */
 export function styledComponentsBrowserBuild(root) {
     const resolveFromRoot = resolverFor(root);
@@ -62,8 +67,17 @@ export function styledComponentsBrowserBuild(root) {
     if (resolveFromRoot('jest-styled-components')) {
         include.push('jest-styled-components');
     }
-    return {
-        resolve: { alias: [{ find: /^styled-components$/, replacement }] },
+    const alias = [{ find: /^styled-components$/, replacement }];
+    const tslib = styledComponentsTslib(manifest);
+    if (tslib.kind === 'alias') {
+        alias.push({ find: /^tslib$/, replacement: tslib.replacement });
+    }
+    const config = {
+        resolve: { alias },
         test: { deps: { optimizer: { client: { enabled: true, include } } } },
     };
+    if (tslib.kind === 'warning') {
+        return { config, warning: tslib.warning };
+    }
+    return { config };
 }

package/dist/styled-components-tslib.d.ts

@@ -0,0 +1,16 @@
+/** How the browser build of styled-components gets its tslib helpers. */
+export type StyledComponentsTslib = {
+    kind: 'untouched';
+} | {
+    kind: 'alias';
+    replacement: string;
+} | {
+    kind: 'warning';
+    warning: string;
+};
+/**
+ * Where `tslib` should point for the styled-components whose `package.json`
+ * is given. Only 6.0 to 6.3 import tslib, and only tslib 2.5.3 and later ship
+ * the `tslib.es6.mjs` that keeps its exports intact through the optimizer.
+ */
+export declare function styledComponentsTslib(styledComponentsManifest: string): StyledComponentsTslib;

package/dist/styled-components-tslib.js

@@ -0,0 +1,40 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+function readPackage(manifest) {
+    return JSON.parse(readFileSync(manifest, 'utf8'));
+}
+function resolveTslib(styledComponentsManifest) {
+    try {
+        return createRequire(styledComponentsManifest).resolve('tslib/package.json');
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Where `tslib` should point for the styled-components whose `package.json`
+ * is given. Only 6.0 to 6.3 import tslib, and only tslib 2.5.3 and later ship
+ * the `tslib.es6.mjs` that keeps its exports intact through the optimizer.
+ */
+export function styledComponentsTslib(styledComponentsManifest) {
+    const styledComponents = readPackage(styledComponentsManifest);
+    if (!styledComponents.dependencies?.tslib) {
+        return { kind: 'untouched' };
+    }
+    // Resolved from styled-components itself, so a nested or pnpm-linked tslib
+    // wins over whatever the project hoists.
+    const tslibManifest = resolveTslib(styledComponentsManifest);
+    if (!tslibManifest) {
+        return { kind: 'untouched' };
+    }
+    const replacement = join(dirname(tslibManifest), 'tslib.es6.mjs');
+    if (existsSync(replacement)) {
+        return { kind: 'alias', replacement };
+    }
+    const tslib = readPackage(tslibManifest);
+    return {
+        kind: 'warning',
+        warning: `styled-components ${styledComponents.version} resolves tslib ${tslib.version}, which has no tslib.es6.mjs, so its browser build may fail to load ("Cannot destructure property '__extends'"). Upgrade styled-components to 6.1.10 or later, or override tslib to 2.5.3 or later.`,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@describe-me/vitest",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Vitest integration for describe-me: plugin, setup file and reporter",
   "keywords": [
     "vitest",
@@ -59,12 +59,13 @@
   ],
   "dependencies": {
     "picomatch": "^4.0.3",
-    "@describe-me/core": "^0.5.0"
+    "@describe-me/core": "^0.5.1"
   },
   "peerDependencies": {
     "vitest": "^4.0.0 || ^5.0.0",
     "typescript": "^5.0.0 || ^6.0.0",
-    "@testing-library/user-event": "^14.0.0"
+    "@testing-library/user-event": "^14.0.0",
+    "describe-me": "^0.5.1"
   },
   "peerDependenciesMeta": {
     "typescript": {
@@ -72,6 +73,9 @@
     },
     "@testing-library/user-event": {
       "optional": true
+    },
+    "describe-me": {
+      "optional": true
     }
   },
   "devDependencies": {