@describe-me/core 0.5.0 → 0.5.1

package/README.md

@@ -14,6 +14,9 @@ Most people never install this package directly — `@describe-me/react` and
 pnpm add -D @describe-me/core
 ```
 
+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
 
 `step()` names a phase of a test. The DOM is captured after the body resolves,

package/dist/manifest-diagnostics.d.ts

@@ -1,8 +1,9 @@
 import { type Manifest, type ManifestDiagnostics } from './types.js';
 /**
  * List what the manifest could not document: anonymous components, named ones
- * without props, assets that will not load, font families that nothing loads
- * and hosts that frames load stylesheets from. The reporter prints it after a
- * run and the viewer shows it in the header, so both agree on what is missing.
+ * without props, assets that will not load, font families that nothing loads,
+ * hosts that frames load stylesheets from and problems in the project's setup.
+ * The reporter prints it after a run and the viewer shows it in the header, so
+ * both agree on what is missing.
  */
 export declare function manifestDiagnostics(manifest: Manifest): ManifestDiagnostics;

package/dist/manifest-diagnostics.js

@@ -5,9 +5,10 @@ function isHostElement(name) {
 }
 /**
  * List what the manifest could not document: anonymous components, named ones
- * without props, assets that will not load, font families that nothing loads
- * and hosts that frames load stylesheets from. The reporter prints it after a
- * run and the viewer shows it in the header, so both agree on what is missing.
+ * without props, assets that will not load, font families that nothing loads,
+ * hosts that frames load stylesheets from and problems in the project's setup.
+ * The reporter prints it after a run and the viewer shows it in the header, so
+ * both agree on what is missing.
  */
 export function manifestDiagnostics(manifest) {
     const anonymous = [];
@@ -33,5 +34,6 @@ export function manifestDiagnostics(manifest) {
         assetsMissing: manifest.assetsMissing ?? [],
         fontsMissing: manifest.fontsMissing ?? [],
         remoteStylesheets: manifest.remoteStylesheets ?? [],
+        setupWarnings: manifest.setupWarnings ?? [],
     };
 }

package/dist/recorder.d.ts

@@ -7,6 +7,8 @@ type Teardown = () => void;
  * `beforeInteraction()`, `setComponent()` and `onTeardown()`.
  */
 declare class Recorder {
+    /** Which contract this recorder follows, so another copy of core can refuse it. */
+    readonly protocol = 1;
     private slots;
     private currentGeneration;
     private inFlight;
@@ -27,8 +29,8 @@ declare class Recorder {
     get generation(): number;
     /**
      * Choose when the render frame is taken, from the next render capture on.
-     * The setup files call it with the plugin's options. An invalid `pending`
-     * selector throws.
+     * The setup files call it with the plugin's options. A `pending` selector
+     * the DOM rejects falls back to `'lazy'` with a warning.
      */
     configure(options: RecorderOptions): void;
     /**

package/dist/recorder.js

@@ -5,16 +5,18 @@ import { realTimers } from './real-timers.js';
 import { serializeDocument } from './serialize-document.js';
 import { settle } from './settle.js';
 import { ANONYMOUS_COMPONENT, } from './types.js';
-/** Fails in the setup file rather than in the first test that renders. */
-function assertValidSelector(selector) {
-    if (typeof document === 'undefined') {
-        return;
-    }
+/**
+ * Bump it whenever the contract between the recorder and the adapters or setup
+ * files changes: a method or property added, removed or changed in meaning.
+ */
+const RECORDER_PROTOCOL = 1;
+function isValidSelector(selector) {
     try {
         document.querySelector(selector);
+        return true;
     }
     catch {
-        throw new Error(`describe-me: renderFrame.pending is not a valid CSS selector: "${selector}"`);
+        return false;
     }
 }
 /**
@@ -24,6 +26,8 @@ function assertValidSelector(selector) {
  * `beforeInteraction()`, `setComponent()` and `onTeardown()`.
  */
 class Recorder {
+    /** Which contract this recorder follows, so another copy of core can refuse it. */
+    protocol = RECORDER_PROTOCOL;
     // One per capture, in call order, so a frame sits where it was asked for.
     slots = [];
     currentGeneration = 0;
@@ -60,13 +64,17 @@ class Recorder {
     }
     /**
      * Choose when the render frame is taken, from the next render capture on.
-     * The setup files call it with the plugin's options. An invalid `pending`
-     * selector throws.
+     * The setup files call it with the plugin's options. A `pending` selector
+     * the DOM rejects falls back to `'lazy'` with a warning.
      */
     configure(options) {
         const renderFrame = options.renderFrame ?? 'eager';
-        if (typeof renderFrame === 'object') {
-            assertValidSelector(renderFrame.pending);
+        if (typeof renderFrame === 'object' &&
+            typeof document !== 'undefined' &&
+            !isValidSelector(renderFrame.pending)) {
+            console.warn(`describe-me: renderFrame.pending is not a valid CSS selector: "${renderFrame.pending}". Render frames fall back to 'lazy'.`);
+            this.renderFrame = 'lazy';
+            return;
         }
         this.renderFrame = renderFrame;
     }
@@ -227,6 +235,21 @@ class Recorder {
     }
 }
 const RECORDER_KEY = Symbol.for('describe-me.recorder');
+function protocolOf(existing) {
+    if (typeof existing !== 'object' || existing === null) {
+        return undefined;
+    }
+    const candidate = existing;
+    if (typeof candidate.protocol === 'number') {
+        return candidate.protocol;
+    }
+    // 0.5.0 did not stamp its recorder. It is the first version with `flush()`,
+    // and its contract is protocol 1.
+    if (typeof candidate.flush === 'function') {
+        return 1;
+    }
+    return undefined;
+}
 /**
  * The adapter and the setup file may receive two copies of this module: Vite
  * pre-bundles the adapter together with its own copy of core, while a linked
@@ -237,7 +260,16 @@ const RECORDER_KEY = Symbol.for('describe-me.recorder');
  */
 function sharedRecorder() {
     const scope = globalThis;
-    scope[RECORDER_KEY] ??= new Recorder();
-    return scope[RECORDER_KEY];
+    const existing = scope[RECORDER_KEY];
+    if (existing === undefined) {
+        const created = new Recorder();
+        scope[RECORDER_KEY] = created;
+        return created;
+    }
+    const found = protocolOf(existing);
+    if (found !== RECORDER_PROTOCOL) {
+        throw new Error(`describe-me: all describe-me packages must be on the same version. Another copy of @describe-me/core created the test recorder (protocol ${found ?? 'none'}, expected ${RECORDER_PROTOCOL}). Install @describe-me/core, @describe-me/react, @describe-me/vitest and describe-me at one version.`);
+    }
+    return existing;
 }
 export const recorder = sharedRecorder();

package/dist/types.d.ts

@@ -157,8 +157,17 @@ export interface ComponentDoc {
     file: string;
     props: PropDoc[];
 }
+/** The package that wrote a manifest. */
+export interface ManifestGenerator {
+    /** The package name, e.g. `@describe-me/vitest`. */
+    name: string;
+    /** Its version, e.g. `0.5.1`. */
+    version: string;
+}
 export interface Manifest {
     version: 1;
+    /** The package and version that wrote the manifest. Absent in manifests written before 0.5.1. */
+    generator?: ManifestGenerator;
     generatedAt: string;
     root: string;
     modules: ManifestModule[];
@@ -186,6 +195,12 @@ export interface Manifest {
      * manifests written before 0.5, which counts as empty.
      */
     remoteStylesheets?: RemoteStylesheet[];
+    /**
+     * Problems the plugin found in the project's setup, one sentence each.
+     * Absent when there are none and in manifests written before 0.5.1, which
+     * counts as empty.
+     */
+    setupWarnings?: string[];
 }
 /** A font family that the captured CSS uses but no `@font-face`, font stylesheet or preview head loads. */
 export interface FontMissing {
@@ -223,4 +238,6 @@ export interface ManifestDiagnostics {
     fontsMissing: FontMissing[];
     /** Hosts that frames load stylesheets from. */
     remoteStylesheets: RemoteStylesheet[];
+    /** Problems in the project's setup that can make tests fail. */
+    setupWarnings: string[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@describe-me/core",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Recorder and manifest types for describe-me: living component docs from your tests",
   "keywords": [
     "vitest",