@describe-me/core 0.5.0-next.0 → 0.5.0-next.1

package/README.md

@@ -32,7 +32,8 @@ The manifest types live in `@describe-me/core/types`, for tools that want to
 read `.describe-me/manifest.json` themselves. Stored snapshots point into
 `assets/` and `styles/` through `ASSET_URL_PREFIX` and `STYLE_URL_PREFIX`
 ([Output directory](https://github.com/grzehub/describe-me#output-directory) in
-the root README).
+the root README). `@describe-me/core/css-references` lists the `url()` and
+`@import` references in CSS text.
 
 See the [root README](https://github.com/grzehub/describe-me#readme) for the
 full picture.

package/dist/css-references.d.ts

@@ -0,0 +1,17 @@
+/** A `url()` or `@import` target in CSS text. */
+export interface CssReference {
+    /** The URL as written, without quotes or surrounding whitespace. */
+    url: string;
+    /** Offset of the URL's first character in the scanned text. */
+    start: number;
+    /** Offset just past the URL's last character. */
+    end: number;
+    /** `import` for an `@import` target, written as a string or as `url()`. */
+    kind: 'url' | 'import';
+}
+/**
+ * Every `url()` and `@import` target in CSS text, in source order, remote,
+ * `data:` and `#fragment` URLs included. Comments and other strings are
+ * skipped, so `content: "url(x)"` yields nothing.
+ */
+export declare function cssReferences(cssText: string): CssReference[];

package/dist/css-references.js

@@ -0,0 +1,129 @@
+/** Where a scan step can start: a comment, a string, an escape, `@import` or `url(`. */
+const TOKEN = /\/\*|["'\\]|@import|url\(/gi;
+const NAME_CHARACTER = /[\w\u0080-\uffff-]/;
+const WHITESPACE = /\s/;
+function isNameCharacter(char) {
+    return char !== undefined && NAME_CHARACTER.test(char);
+}
+function isQuote(char) {
+    return char === '"' || char === "'";
+}
+/** The offset of the quote that closes the string opening at `open`. A newline ends a broken string. */
+function closingQuote(css, open) {
+    let index = open + 1;
+    while (index < css.length) {
+        const char = css[index];
+        if (char === '\\') {
+            index += 2;
+            continue;
+        }
+        if (char === css[open] || char === '\n') {
+            return index;
+        }
+        index++;
+    }
+    return css.length;
+}
+/** The offset just past the comment opening at `open`. */
+function commentEnd(css, open) {
+    const close = css.indexOf('*/', open + 2);
+    return close === -1 ? css.length : close + 2;
+}
+function skipWhitespaceAndComments(css, start) {
+    let index = start;
+    while (index < css.length) {
+        if (WHITESPACE.test(css[index])) {
+            index++;
+        }
+        else if (css.startsWith('/*', index)) {
+            index = commentEnd(css, index);
+        }
+        else {
+            break;
+        }
+    }
+    return index;
+}
+/** `url(` at `index` as a function of its own, not the tail of a longer name such as `my-url(`. */
+function isUrlFunction(css, index) {
+    return css.slice(index, index + 4).toLowerCase() === 'url(' && !isNameCharacter(css[index - 1]);
+}
+function referenceOf(css, start, end, kind) {
+    if (end <= start) {
+        return null;
+    }
+    return { url: css.slice(start, end), start, end, kind };
+}
+/** The quoted string opening at `open`, as a reference. */
+function scanString(css, open, kind) {
+    const close = closingQuote(css, open);
+    return { reference: referenceOf(css, open + 1, close, kind), next: close + 1 };
+}
+/**
+ * The target of the `url(` starting at `index`. An unquoted URL runs until the
+ * first `)`, because a Google Fonts `css2` URL contains semicolons.
+ */
+function scanUrl(css, index, kind) {
+    let start = index + 'url('.length;
+    while (start < css.length && WHITESPACE.test(css[start])) {
+        start++;
+    }
+    if (isQuote(css[start])) {
+        return scanString(css, start, kind);
+    }
+    const close = css.indexOf(')', start);
+    if (close === -1) {
+        return { reference: null, next: start };
+    }
+    let end = close;
+    while (end > start && WHITESPACE.test(css[end - 1])) {
+        end--;
+    }
+    return { reference: referenceOf(css, start, end, kind), next: close + 1 };
+}
+/** The target of the `@import` starting at `index`: a string or a `url()`. */
+function scanImport(css, index) {
+    const target = skipWhitespaceAndComments(css, index + '@import'.length);
+    if (isQuote(css[target])) {
+        return scanString(css, target, 'import');
+    }
+    if (isUrlFunction(css, target)) {
+        return scanUrl(css, target, 'import');
+    }
+    return { reference: null, next: target };
+}
+function scanToken(css, index, token) {
+    const skipped = (next) => ({ reference: null, next });
+    if (token === '/*') {
+        return skipped(commentEnd(css, index));
+    }
+    if (token === '\\') {
+        return skipped(index + 2);
+    }
+    if (isQuote(token)) {
+        return skipped(closingQuote(css, index) + 1);
+    }
+    if (token.startsWith('@')) {
+        return isNameCharacter(css[index + token.length]) ? skipped(index + 1) : scanImport(css, index);
+    }
+    return isUrlFunction(css, index) ? scanUrl(css, index, 'url') : skipped(index + 1);
+}
+/**
+ * Every `url()` and `@import` target in CSS text, in source order, remote,
+ * `data:` and `#fragment` URLs included. Comments and other strings are
+ * skipped, so `content: "url(x)"` yields nothing.
+ */
+export function cssReferences(cssText) {
+    const references = [];
+    const token = new RegExp(TOKEN);
+    let match = token.exec(cssText);
+    while (match !== null) {
+        const scanned = scanToken(cssText, match.index, match[0]);
+        if (scanned.reference) {
+            references.push(scanned.reference);
+        }
+        token.lastIndex = scanned.next;
+        match = token.exec(cssText);
+    }
+    return references;
+}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './types.js';
+export { cssReferences, type CssReference } from './css-references.js';
 export { describeComponentType } from './describe-component-type.js';
 export { elementLabel } from './element-label.js';
 export { manifestDiagnostics } from './manifest-diagnostics.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from './types.js';
+export { cssReferences } from './css-references.js';
 export { describeComponentType } from './describe-component-type.js';
 export { elementLabel } from './element-label.js';
 export { manifestDiagnostics } from './manifest-diagnostics.js';

package/dist/types.d.ts

@@ -136,11 +136,17 @@ export interface Manifest {
     /** Keyed by component name, as reported by the framework adapter. */
     components: Record<string, ComponentDoc>;
     /**
-     * Asset URLs the snapshots point at on the test page's origin that could not
-     * be found in the project, as root-relative paths (`/lib/images/logo.svg`).
+     * Asset URLs the snapshots, the preview head or copied CSS files point at
+     * that could not be found in the project, as root-relative paths
+     * (`/lib/images/logo.svg`). Paths outside the root use the `/@fs/` form.
      * They will not load in the viewer. Absent in manifests written before 0.4.
      */
     assetsMissing?: string[];
+    /**
+     * The preview head HTML, with project files as `describe-me-asset:` URLs.
+     * Absent when `previewHead` is not set.
+     */
+    head?: string;
 }
 /** The name adapters fall back to when a component has no usable name. */
 export declare const ANONYMOUS_COMPONENT: "Anonymous";
@@ -156,6 +162,6 @@ export interface ManifestDiagnostics {
         name: string;
         tests: number;
     }[];
-    /** Root-relative asset paths that will not load in the viewer. */
+    /** Asset paths that will not load in the viewer, root-relative or in the `/@fs/` form. */
     assetsMissing: string[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@describe-me/core",
-  "version": "0.5.0-next.0",
+  "version": "0.5.0-next.1",
   "description": "Recorder and manifest types for describe-me: living component docs from your tests",
   "keywords": [
     "vitest",
@@ -38,6 +38,10 @@
     "./diagnostics": {
       "types": "./dist/manifest-diagnostics.d.ts",
       "default": "./dist/manifest-diagnostics.js"
+    },
+    "./css-references": {
+      "types": "./dist/css-references.d.ts",
+      "default": "./dist/css-references.js"
     }
   },
   "files": [