@arraypress/extension-kit 1.1.0 → 1.3.0

package/src/testing/package.d.ts

@@ -20,17 +20,75 @@ export declare function filesUnder(dir: string): Promise<string[]>;
  * @returns {Promise<string[]>} Entry names, sorted.
  */
 export declare function zipEntries(from: string, exclude?: readonly string[]): Promise<string[]>;
+export type ManifestFiles = {
+    /**
+     * The worker.
+     */
+    background?: {
+        service_worker?: string;
+    };
+    /**
+     * The options page.
+     */
+    options_ui?: {
+        page?: string;
+    };
+    /**
+     * The popup and toolbar icon.
+     */
+    action?: {
+        default_popup?: string;
+        default_icon?: string | Record<string, string>;
+    };
+    /**
+     * The side panel.
+     */
+    side_panel?: {
+        default_path?: string;
+    };
+    /**
+     * The extension's icons.
+     */
+    icons?: Record<string, string>;
+    /**
+     * Files pages may load.
+     */
+    web_accessible_resources?: {
+        resources: string[];
+    }[];
+};
+/**
+ * The parts of a manifest that name files.
+ *
+ * @typedef {object} ManifestFiles
+ * @property {{service_worker?: string}} [background] The worker.
+ * @property {{page?: string}} [options_ui] The options page.
+ * @property {{default_popup?: string, default_icon?: string | Record<string, string>}} [action] The popup and toolbar icon.
+ * @property {{default_path?: string}} [side_panel] The side panel.
+ * @property {Record<string, string>} [icons] The extension's icons.
+ * @property {{resources: string[]}[]} [web_accessible_resources] Files pages may load.
+ */
 /**
  * The paths a manifest names, from the extension's root.
  *
- * @param {Record<string, any>} manifest - The parsed `manifest.json`.
- * @returns {string[]} Worker, pages, icons, side panel and web-accessible resources.
+ * @param {ManifestFiles} manifest - The parsed `manifest.json`.
+ * @returns {string[]} Worker, pages, icons, side panel and web-accessible resources (less patterns with `*`).
+ */
+export declare function manifestReferences(manifest: ManifestFiles): string[];
+/**
+ * The file a reference names: the path without its `#fragment` or `?query`
+ * (`options.html#workspaces` is `options.html`). Pure.
+ *
+ * @param {string} reference - A path as the extension writes it.
+ * @returns {string} The path alone; '' for a reference to the page itself (`#top`).
  */
-export declare function manifestReferences(manifest: Record<string, any>): string[];
+export declare function referencedPath(reference: string): string;
 /**
  * Every path the extension names that isn't a file inside it: relative
  * imports in its scripts, `chrome.runtime.getURL('…')` paths, `src`/`href`
- * in its pages, the manifest's entries, and any `extra` paths.
+ * in its pages, the manifest's entries, and any `extra` paths. A `#fragment`
+ * or `?query` is ignored: `getURL('options.html#workspaces')` names
+ * `options.html`.
  *
  * @param {string} dir - The extension folder.
  * @param {readonly string[]} [extra] - More paths from the root (say, a script injected by name).

package/src/testing/package.js

@@ -43,28 +43,57 @@ export async function zipEntries(from, exclude) {
   }
 }
 
+/**
+ * The parts of a manifest that name files.
+ *
+ * @typedef {object} ManifestFiles
+ * @property {{service_worker?: string}} [background] The worker.
+ * @property {{page?: string}} [options_ui] The options page.
+ * @property {{default_popup?: string, default_icon?: string | Record<string, string>}} [action] The popup and toolbar icon.
+ * @property {{default_path?: string}} [side_panel] The side panel.
+ * @property {Record<string, string>} [icons] The extension's icons.
+ * @property {{resources: string[]}[]} [web_accessible_resources] Files pages may load.
+ */
+
 /**
  * The paths a manifest names, from the extension's root.
  *
- * @param {Record<string, any>} manifest - The parsed `manifest.json`.
- * @returns {string[]} Worker, pages, icons, side panel and web-accessible resources.
+ * @param {ManifestFiles} manifest - The parsed `manifest.json`.
+ * @returns {string[]} Worker, pages, icons, side panel and web-accessible resources (less patterns with `*`).
  */
 export function manifestReferences(manifest) {
+  const icon = manifest.action?.default_icon;
   return [
     manifest.background?.service_worker,
     manifest.options_ui?.page,
     manifest.action?.default_popup,
     manifest.side_panel?.default_path,
     ...Object.values(manifest.icons ?? {}),
-    ...Object.values(manifest.action?.default_icon ?? {}),
-    ...(manifest.web_accessible_resources ?? []).flatMap((/** @type {{resources: string[]}} */ entry) => entry.resources),
-  ].filter((ref) => typeof ref === 'string' && !ref.includes('*'));
+    ...(typeof icon === 'string' ? [icon] : Object.values(icon ?? {})),
+    ...(manifest.web_accessible_resources ?? []).flatMap((entry) => entry.resources),
+  ].filter((ref) => typeof ref === 'string').filter((ref) => !ref.includes('*'));
+}
+
+/**
+ * The file a reference names: the path without its `#fragment` or `?query`
+ * (`options.html#workspaces` is `options.html`). Pure.
+ *
+ * @param {string} reference - A path as the extension writes it.
+ * @returns {string} The path alone; '' for a reference to the page itself (`#top`).
+ */
+export function referencedPath(reference) {
+  return reference.replace(/[?#].*$/s, '');
 }
 
+/** A reference with a scheme (`https:`, `data:`, `mailto:`) or protocol-relative: not a file of the extension. */
+const ELSEWHERE = /^(?:[a-z][a-z\d+.-]*:|\/\/)/i;
+
 /**
  * Every path the extension names that isn't a file inside it: relative
  * imports in its scripts, `chrome.runtime.getURL('…')` paths, `src`/`href`
- * in its pages, the manifest's entries, and any `extra` paths.
+ * in its pages, the manifest's entries, and any `extra` paths. A `#fragment`
+ * or `?query` is ignored: `getURL('options.html#workspaces')` names
+ * `options.html`.
  *
  * @param {string} dir - The extension folder.
  * @param {readonly string[]} [extra] - More paths from the root (say, a script injected by name).
@@ -76,7 +105,9 @@ export async function missingReferences(dir, extra = []) {
   const missing = [];
   /** @param {string} from @param {string} target */
   const check = (from, target) => {
-    const file = path.resolve(root, from, target);
+    const name = referencedPath(target);
+    if (!name || ELSEWHERE.test(target)) return;
+    const file = path.resolve(root, from, name);
     if (!file.startsWith(root) || !existsSync(file)) missing.push(`${from || 'root'} → ${target}`);
   };
   for (const file of await filesUnder(root)) {
@@ -87,7 +118,7 @@ export async function missingReferences(dir, extra = []) {
       for (const [, ref] of source.matchAll(/getURL\('([^']+)'\)/g)) check('', ref);
     } else if (file.endsWith('.html')) {
       const source = await readFile(path.join(root, file), 'utf8');
-      for (const [, ref] of source.matchAll(/(?:src|href)="([^"#:]+)"/g)) check(from, ref);
+      for (const [, ref] of source.matchAll(/(?:src|href)="([^"]+)"/g)) check(from, ref);
     }
   }
   const manifest = JSON.parse(await readFile(path.join(root, 'manifest.json'), 'utf8'));

package/src/testing/pool.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Working through a list a few at a time: a live check of many sites, each
+ * in one of a few browsers.
+ *
+ * @module testing/pool
+ */
+/**
+ * Run `work` on every item, at most `limit` at once, each slot taking the
+ * next item as it finishes one. Errors are `work`'s to handle: one that
+ * throws stops its slot, and the returned promise rejects once the others
+ * are done.
+ *
+ * @template T
+ * @param {readonly T[]} items - The items.
+ * @param {number} limit - At most this many at once.
+ * @param {(item: T, slot: number, index: number) => Promise<void>} work - Deals with one item;
+ *   `slot` (0 to limit − 1) is the same for everything one slot does, for per-slot resources
+ *   (a browser each).
+ * @returns {Promise<void>} Once every item is done.
+ * @example
+ * await eachLimited(sites, 3, async (site, slot) => check(site, browsers[slot]));
+ */
+export declare function eachLimited<T>(items: readonly T[], limit: number, work: (item: T, slot: number, index: number) => Promise<void>): Promise<void>;

package/src/testing/pool.js

@@ -0,0 +1,33 @@
+/**
+ * Working through a list a few at a time: a live check of many sites, each
+ * in one of a few browsers.
+ *
+ * @module testing/pool
+ */
+
+/**
+ * Run `work` on every item, at most `limit` at once, each slot taking the
+ * next item as it finishes one. Errors are `work`'s to handle: one that
+ * throws stops its slot, and the returned promise rejects once the others
+ * are done.
+ *
+ * @template T
+ * @param {readonly T[]} items - The items.
+ * @param {number} limit - At most this many at once.
+ * @param {(item: T, slot: number, index: number) => Promise<void>} work - Deals with one item;
+ *   `slot` (0 to limit − 1) is the same for everything one slot does, for per-slot resources
+ *   (a browser each).
+ * @returns {Promise<void>} Once every item is done.
+ * @example
+ * await eachLimited(sites, 3, async (site, slot) => check(site, browsers[slot]));
+ */
+export async function eachLimited(items, limit, work) {
+  let next = 0;
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, async (_, slot) => {
+    while (next < items.length) {
+      const index = next;
+      next += 1;
+      await work(items[index], slot, index);
+    }
+  }));
+}

package/src/testing/saved-groups.d.ts

@@ -0,0 +1,33 @@
+export type SavedTabGroup = {
+    /**
+     * Its title.
+     */
+    title: string;
+    /**
+     * Whether it's pinned to the saved groups bar.
+     */
+    pinned: boolean;
+    /**
+     * Its tabs' addresses, in order.
+     */
+    urls: string[];
+};
+export type ProtoField = {
+    field: number;
+    value: number | Buffer;
+};
+/**
+ * Chrome's saved tab groups in a closed profile.
+ *
+ * @param {string} profile - The profile folder (as `extensionProfile` gives it).
+ * @returns {Promise<SavedTabGroup[]>} The saved groups, in no particular order; none when the
+ *   profile has no store yet.
+ * @throws {Error} When the store has compacted tables this doesn't read.
+ * @example
+ * const profile = await extensionProfile(chromium, 'extension');
+ * const { worker, close } = await profile.launch();
+ * await worker.evaluate(async () => chrome.tabGroups.update(await chrome.tabs.group({tabIds: [tabId]}), {title: 'Research'}));
+ * await close();
+ * const groups = await savedTabGroups(profile.dir); // → [{title: 'Research', pinned: true, urls: [...]}]
+ */
+export declare function savedTabGroups(profile: string): Promise<SavedTabGroup[]>;

package/src/testing/saved-groups.js

@@ -0,0 +1,222 @@
+/**
+ * Chrome's saved tab groups, read from a closed profile: no extension API lists them and their
+ * UI (the saved groups bar, the Tab groups menu) is native, so e2e checks read the store itself.
+ *
+ * Chromium keeps them in the profile's `Sync Data/LevelDB` (a DataTypeStore, kept even when
+ * signed out), one record per group and one per tab, keyed `saved_tab_group-dt-<guid>`. Each
+ * value is a `SavedTabGroupData` proto whose field 2 is the `SavedTabGroupSpecifics`
+ * (components/sync/protocol/saved_tab_group_specifics.proto): 1 guid, 4 group (2 title,
+ * 3 colour, 4 pinned position: present when pinned to the bar), 5 tab (1 group guid, 2 position,
+ * 3 url). A fresh test profile never fills a LevelDB log (4 MB) so everything is in `*.log`
+ * files, which this reads; it refuses a store that has compacted tables.
+ *
+ * Read only after the browser has closed, so every write is on disk.
+ *
+ * @module testing/saved-groups
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * A saved group as Chrome keeps it.
+ *
+ * @typedef {object} SavedTabGroup
+ * @property {string} title Its title.
+ * @property {boolean} pinned Whether it's pinned to the saved groups bar.
+ * @property {string[]} urls Its tabs' addresses, in order.
+ */
+
+/**
+ * One protobuf field: its number and value (a number for varints, the bytes for the rest).
+ *
+ * @typedef {{field: number, value: number | Buffer}} ProtoField
+ */
+
+const KEY_PREFIX = 'saved_tab_group-dt-';
+/** LevelDB log blocks: 32 KB, each record with a 7-byte header (checksum, length, type). */
+const BLOCK = 32768;
+const HEADER = 7;
+/** Record types: a whole batch, or its first, middle or last fragment. */
+const FULL = 1;
+const FIRST = 2;
+const MIDDLE = 3;
+const LAST = 4;
+
+/**
+ * Read a varint (LevelDB lengths, protobuf keys and values). Numbers past 2^53 lose precision,
+ * which only affects timestamps this never reads.
+ *
+ * @param {Buffer} buf - The bytes.
+ * @param {number} at - Where it starts.
+ * @returns {[value: number, next: number]} Its value and the offset after it.
+ */
+function varint(buf, at) {
+  let value = 0;
+  let scale = 1;
+  let byte;
+  do {
+    byte = buf[at++];
+    value += (byte & 0x7f) * scale;
+    scale *= 128;
+  } while (byte & 0x80);
+  return [value, at];
+}
+
+/**
+ * The write batches in one LevelDB log file, fragments joined.
+ *
+ * @param {Buffer} buf - The file.
+ * @returns {Buffer[]} Its batches, in order.
+ */
+function batches(buf) {
+  /** @type {Buffer[]} */
+  const out = [];
+  /** @type {Buffer[]} */
+  let pending = [];
+  let at = 0;
+  while (at + HEADER <= buf.length) {
+    const left = BLOCK - (at % BLOCK);
+    if (left < HEADER) {
+      at += left; // Block trailer: zero padding.
+      continue;
+    }
+    const length = buf.readUInt16LE(at + 4);
+    const type = buf[at + 6];
+    if (type === 0 && length === 0) {
+      at += left; // Pre-allocated, unwritten space.
+      continue;
+    }
+    const data = buf.subarray(at + HEADER, at + HEADER + length);
+    at += HEADER + length;
+    if (type === FULL) out.push(data);
+    else if (type === FIRST) pending = [data];
+    else if (type === MIDDLE) pending.push(data);
+    else if (type === LAST) out.push(Buffer.concat([...pending, data]));
+  }
+  return out;
+}
+
+/**
+ * Apply one batch to the live keys: puts set a key, deletes remove it.
+ *
+ * @param {Buffer} batch - Sequence (8 bytes), count (4), then each tagged put or delete.
+ * @param {Map<string, Buffer>} live - The keys, changed in place.
+ */
+function apply(batch, live) {
+  const count = batch.readUInt32LE(8);
+  let at = 12;
+  for (let i = 0; i < count; i++) {
+    const put = batch[at++] === 1;
+    let length;
+    [length, at] = varint(batch, at);
+    const key = batch.subarray(at, at + length).toString('latin1');
+    at += length;
+    if (!put) {
+      live.delete(key);
+      continue;
+    }
+    [length, at] = varint(batch, at);
+    live.set(key, batch.subarray(at, at + length));
+    at += length;
+  }
+}
+
+/**
+ * The fields of one protobuf message (one level).
+ *
+ * @param {Buffer} buf - The message.
+ * @returns {ProtoField[]} Its fields, in order.
+ */
+function fields(buf) {
+  /** @type {ProtoField[]} */
+  const out = [];
+  let at = 0;
+  while (at < buf.length) {
+    let key;
+    [key, at] = varint(buf, at);
+    const field = Math.floor(key / 8);
+    const wire = key % 8;
+    if (wire === 0) {
+      let value;
+      [value, at] = varint(buf, at);
+      out.push({ field, value });
+    } else if (wire === 2) {
+      let length;
+      [length, at] = varint(buf, at);
+      out.push({ field, value: buf.subarray(at, at + length) });
+      at += length;
+    } else if (wire === 1 || wire === 5) {
+      const size = wire === 1 ? 8 : 4;
+      out.push({ field, value: buf.subarray(at, at + size) });
+      at += size;
+    } else {
+      throw new Error(`Unexpected protobuf wire type ${wire}`);
+    }
+  }
+  return out;
+}
+
+/**
+ * A field's bytes.
+ *
+ * @param {ProtoField[]} message - The message's fields.
+ * @param {number} field - The field number.
+ * @returns {Buffer | undefined} Its bytes, when present and not a number.
+ */
+const bytesOf = (message, field) => {
+  const value = message.find((f) => f.field === field)?.value;
+  return Buffer.isBuffer(value) ? value : undefined;
+};
+
+/**
+ * Chrome's saved tab groups in a closed profile.
+ *
+ * @param {string} profile - The profile folder (as `extensionProfile` gives it).
+ * @returns {Promise<SavedTabGroup[]>} The saved groups, in no particular order; none when the
+ *   profile has no store yet.
+ * @throws {Error} When the store has compacted tables this doesn't read.
+ * @example
+ * const profile = await extensionProfile(chromium, 'extension');
+ * const { worker, close } = await profile.launch();
+ * await worker.evaluate(async () => chrome.tabGroups.update(await chrome.tabs.group({tabIds: [tabId]}), {title: 'Research'}));
+ * await close();
+ * const groups = await savedTabGroups(profile.dir); // → [{title: 'Research', pinned: true, urls: [...]}]
+ */
+export async function savedTabGroups(profile) {
+  const dir = path.join(profile, 'Default', 'Sync Data', 'LevelDB');
+  const files = await readdir(dir).catch(() => /** @type {string[]} */ ([]));
+  if (files.some((file) => file.endsWith('.ldb'))) throw new Error(`${dir} has compacted tables; only logs are read`);
+  /** @type {Map<string, Buffer>} */
+  const live = new Map();
+  for (const file of files.filter((name) => name.endsWith('.log')).sort()) {
+    for (const batch of batches(await readFile(path.join(dir, file)))) apply(batch, live);
+  }
+
+  /** @type {Map<string, SavedTabGroup>} */
+  const groups = new Map();
+  /** @type {{group: string, position: number, url: string}[]} */
+  const tabs = [];
+  for (const [key, value] of live) {
+    if (!key.startsWith(KEY_PREFIX)) continue;
+    const specifics = bytesOf(fields(value), 2);
+    if (!specifics) continue;
+    const spec = fields(specifics);
+    const guid = bytesOf(spec, 1)?.toString('utf8') ?? '';
+    const group = bytesOf(spec, 4);
+    const tab = bytesOf(spec, 5);
+    if (group) {
+      const g = fields(group);
+      groups.set(guid, { title: bytesOf(g, 2)?.toString('utf8') ?? '', pinned: g.some((f) => f.field === 4), urls: [] });
+    } else if (tab) {
+      const t = fields(tab);
+      const position = t.find((f) => f.field === 2)?.value;
+      tabs.push({
+        group: bytesOf(t, 1)?.toString('utf8') ?? '',
+        position: typeof position === 'number' ? position : 0,
+        url: bytesOf(t, 3)?.toString('utf8') ?? '',
+      });
+    }
+  }
+  for (const tab of tabs.sort((a, b) => a.position - b.position)) groups.get(tab.group)?.urls.push(tab.url);
+  return [...groups.values()];
+}

package/src/testing/time.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Time limits for tests that drive a real browser, where a page that stops
+ * responding would otherwise hold a run up forever.
+ *
+ * @module testing/time
+ */
+/**
+ * Settle `promise` within `ms`, or settle the way `late` says. The timer is
+ * cleared as soon as either happens, so a finished run isn't kept waiting
+ * for it. The work itself isn't stopped.
+ *
+ * @template T
+ * @param {Promise<T>} promise - The work.
+ * @param {number} ms - The limit.
+ * @param {(resolve: (value: T) => void, reject: (error: Error) => void) => void} late - Runs when the
+ *   limit passes first.
+ * @returns {Promise<T>} The work's outcome, or `late`'s.
+ */
+export declare function deadline<T>(promise: Promise<T>, ms: number, late: (resolve: (value: T) => void, reject: (error: Error) => void) => void): Promise<T>;
+/**
+ * A promise's value within a time limit, or `fallback` when it's late or
+ * fails: for a step a live run should give up on and go past (a renderer
+ * that stopped responding, a close that never returns). The work itself
+ * isn't stopped; the timer is cleared once it settles.
+ *
+ * @template T
+ * @param {Promise<T>} promise - The work.
+ * @param {number} ms - The limit.
+ * @param {T} fallback - What to give if it's late or fails.
+ * @returns {Promise<T>} Its value, or the fallback. Never rejects.
+ * @example
+ * const list = await within(handled(worker, page), 8000, []);
+ * await within(page.close(), 15000, undefined);
+ */
+export declare function within<T>(promise: Promise<T>, ms: number, fallback: T): Promise<T>;

package/src/testing/time.js

@@ -0,0 +1,46 @@
+/**
+ * Time limits for tests that drive a real browser, where a page that stops
+ * responding would otherwise hold a run up forever.
+ *
+ * @module testing/time
+ */
+
+/**
+ * Settle `promise` within `ms`, or settle the way `late` says. The timer is
+ * cleared as soon as either happens, so a finished run isn't kept waiting
+ * for it. The work itself isn't stopped.
+ *
+ * @template T
+ * @param {Promise<T>} promise - The work.
+ * @param {number} ms - The limit.
+ * @param {(resolve: (value: T) => void, reject: (error: Error) => void) => void} late - Runs when the
+ *   limit passes first.
+ * @returns {Promise<T>} The work's outcome, or `late`'s.
+ */
+export function deadline(promise, ms, late) {
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  let timer;
+  const limit = new Promise((resolve, reject) => {
+    timer = setTimeout(() => late(resolve, reject), ms);
+  });
+  return /** @type {Promise<T>} */ (Promise.race([promise, limit])).finally(() => clearTimeout(timer));
+}
+
+/**
+ * A promise's value within a time limit, or `fallback` when it's late or
+ * fails: for a step a live run should give up on and go past (a renderer
+ * that stopped responding, a close that never returns). The work itself
+ * isn't stopped; the timer is cleared once it settles.
+ *
+ * @template T
+ * @param {Promise<T>} promise - The work.
+ * @param {number} ms - The limit.
+ * @param {T} fallback - What to give if it's late or fails.
+ * @returns {Promise<T>} Its value, or the fallback. Never rejects.
+ * @example
+ * const list = await within(handled(worker, page), 8000, []);
+ * await within(page.close(), 15000, undefined);
+ */
+export function within(promise, ms, fallback) {
+  return deadline(promise.catch(() => fallback), ms, (resolve) => resolve(fallback));
+}

package/src/testing/warnings.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Chrome's own install warnings for a manifest ("Read your browsing
+ * history"), the lines its install dialog and the Chrome Web Store list, read
+ * with `chrome.management.getPermissionWarningsByManifest` (no `management`
+ * permission needed) in a loaded extension's service worker. For an e2e check
+ * that a permission adds no warning, or that the warnings are exactly the
+ * ones the store listing explains.
+ *
+ * @module testing/warnings
+ */
+import type { Worker } from 'playwright';
+export type Manifest = Record<string, unknown>;
+/** @import { Worker } from 'playwright' */
+/**
+ * A manifest, as `manifest.json` parses.
+ *
+ * @typedef {Record<string, unknown>} Manifest
+ */
+/**
+ * The manifest less some permissions (from `permissions`, `optional_permissions`
+ * and `host_permissions`). Pure: `manifest` is left as it was.
+ *
+ * @param {Manifest} manifest - The manifest.
+ * @param {readonly string[]} names - The permissions (or host patterns) to leave out.
+ * @returns {Manifest} A copy without them.
+ * @example
+ * withoutPermissions({permissions: ['tabs', 'alarms']}, ['alarms']); // → {permissions: ['tabs']}
+ */
+export declare function withoutPermissions(manifest: Manifest, names: readonly string[]): Manifest;
+/**
+ * Chrome's install warnings for a manifest, as this browser words them.
+ *
+ * @param {Worker} worker - A loaded extension's service worker (`launchExtension`'s `worker`).
+ * @param {Manifest} manifest - The manifest to ask about (it needn't be the loaded extension's).
+ * @returns {Promise<string[]>} The warnings, in Chrome's order.
+ * @example
+ * assert.deepEqual(await installWarnings(worker, manifest), ['Read your browsing history']);
+ */
+export declare function installWarnings(worker: Worker, manifest: Manifest): Promise<string[]>;
+/**
+ * Chrome's install warnings for a manifest, with and without some permissions,
+ * and the ones only the permissions bring (a warning they reword counts).
+ *
+ * @param {Worker} worker - A loaded extension's service worker.
+ * @param {Manifest} manifest - The manifest.
+ * @param {readonly string[]} names - The permissions in question.
+ * @returns {Promise<{warnings: string[], without: string[], added: string[]}>} The warnings with
+ *   them, without them, and those in the first list only.
+ * @example
+ * const { warnings, added } = await warningsAddedBy(worker, manifest, ['alarms']);
+ * assert.deepEqual(added, []); // alarms asks the user nothing
+ */
+export declare function warningsAddedBy(worker: Worker, manifest: Manifest, names: readonly string[]): Promise<{
+    warnings: string[];
+    without: string[];
+    added: string[];
+}>;