@arraypress/extension-kit 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Sherlock / ArrayPress Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,218 @@
-# Temporary Holding Version
+# @arraypress/extension-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The pieces ArrayPress's Chrome extensions share, so each is written once:
+
+- **`chrome-ui.css`**: one stylesheet that makes an extension page look like Chrome's own
+  (chrome://settings for settings pages, chrome://bookmarks for manager pages, the side panel).
+- **A settings store on Chrome Sync**: one sync item per setting, per-computer settings in local,
+  debounced writes for options pages, and writes sync refuses kept on the computer and retried.
+- **The light/dark toolbar glyph**: pages (or an offscreen document) report the colour scheme, the
+  service worker shows the matching icon.
+- **About links**: README, Issues and PRIVACY.md in the extension's GitHub repository, plus
+  package-time warnings for placeholder links.
+- **Build and test helpers** (Node): toolbar icon rendering, zipping for the Chrome Web Store, a
+  fake `chrome.storage`, Playwright helpers, packaging checks, and a copied-code guard.
+
+Zero dependencies. Every runtime function takes the `chrome` APIs it uses as arguments, so tests run
+the real logic against fakes.
+
+## Install
+
+```bash
+npm install --save-dev @arraypress/extension-kit
+```
+
+### An extension without a bundler
+
+A packaged extension can't load files from outside its folder, so copy the browser half in on
+install, and never commit the copy:
+
+```json
+{
+  "scripts": { "postinstall": "extension-kit vendor extension/vendor/extension-kit" }
+}
+```
+
+```gitignore
+extension/vendor/
+```
+
+Then import it relatively, and link the stylesheet first on every page:
+
+```js
+import { startToolbarTheme } from '../vendor/extension-kit/index.js';
+```
+
+```html
+<link rel="stylesheet" href="../vendor/extension-kit/styles/chrome-ui.css">
+```
+
+The copy is made from the installed package every `npm install`, so it can't drift from the
+version in `package.json`. The zip helper leaves its `.d.ts` files out.
+
+### An extension with a bundler
+
+Import `@arraypress/extension-kit` directly and copy the stylesheet into the build from
+`STYLESHEET` (`@arraypress/extension-kit/build`), or resolve
+`@arraypress/extension-kit/chrome-ui.css`.
+
+## Settings
+
+```js
+import { createSettingsSaver, createSettingsStore } from '../vendor/extension-kit/index.js';
+
+export const store = createSettingsStore({
+  defaults: { menuStyle: 'single', sites: [] },
+  // Coerce anything (stored, typed, from a newer version) into valid settings.
+  normalize: (raw) => ({
+    menuStyle: raw.menuStyle === 'full' ? 'full' : 'single',
+    sites: Array.isArray(raw.sites) ? raw.sites.filter((site) => typeof site === 'string') : [],
+  }),
+  // Tied to this computer (say, they need a site permission Chrome grants per computer).
+  localKeys: ['sites'],
+});
+
+const settings = await store.load(chrome.storage);
+await store.save(chrome.storage, { menuStyle: 'full' }); // → { settings, synced }
+chrome.storage.onChanged.addListener((changes, area) => {
+  if (store.changed(changes, area).length) rebuildMenu();
+});
+
+// Options page: a burst of clicks is one sync write (sync allows 120 a minute).
+const saver = createSettingsSaver(store, chrome.storage, { onSaved: showSaved });
+saver.save({ menuStyle: 'full' });
+addEventListener('pagehide', () => saver.flush());
+```
+
+| Store member | What it does |
+|---|---|
+| `load(storage)` | Every setting: sync, then held refusals, then local, normalised. |
+| `save(storage, changes)` | Writes only the settings named, so another computer's change to a different one survives. Resolves to `{settings, synced}`. |
+| `writeSynced(storage, values)` | One sync write; what sync refuses (rate limit, an item over 8,192 bytes) is kept in local under `unsyncedKey` and retried with the next write. |
+| `retryUnsynced(storage)` | Try the held refusals again. |
+| `changed(changes, area)` | The settings a `chrome.storage.onChanged` event touches. |
+| `normalize(raw)`, `defaults`, `localKeys`, `syncedKeys`, `unsyncedKey` | The schema. |
+
+## Toolbar glyph
+
+```js
+// background.js: restore the last glyph, open the offscreen watcher, handle reports.
+startToolbarTheme(chrome);
+
+// offscreen/offscreen.js (manifest permission "offscreen"):
+watchSchemeOffscreen(chrome.runtime);
+
+// Every extension page:
+watchColorScheme(chrome).catch(() => {});
+```
+
+An extension that already runs on every page (a content script) can skip the offscreen document:
+call `createToolbarTheme({storage, action, extensionId})` in the worker and pass its `onMessage`
+the reports, which the content script sends with `reportColorScheme(media, stored,
+schemeSender(chrome.runtime))`.
+
+Render the glyphs from `icons/toolbar/glyph.svg` (and optional pixel-fitted `glyph-16.svg`):
+
+```js
+import { chromium } from 'playwright';
+import { renderToolbarIcons } from '@arraypress/extension-kit/build';
+await renderToolbarIcons({ chromium, dir: 'extension/icons/toolbar' });
+```
+
+Colours are Chrome 157's toolbar icon colours, #474747 / #C7C7C7 (sources in the file).
+
+## About links
+
+```js
+export const REPOSITORY = 'https://github.com/arraypress/upright';
+export const ABOUT_LINKS = githubAboutLinks(REPOSITORY); // { help, reportIssue, privacyPolicy }
+```
+
+At the end of `npm run package`, `printReleaseChecks(ABOUT_LINKS, REPOSITORY)` warns loudly while a
+link is a placeholder (`isPlaceholder`: example.com/.org/.net) and reminds you the repository must
+be public before the store listing goes live.
+
+## Build helpers (`@arraypress/extension-kit/build`)
+
+| Export | What it does |
+|---|---|
+| `zipExtension(from, to, exclude?)` | Zip a folder for the Chrome Web Store, files only, less `ZIP_EXCLUDE` (icon SVG sources, `.d.ts`, `.DS_Store`). |
+| `shipsFile(file)` | Whether a file ships, by the same rules. |
+| `vendorKit(dest)` | Copy the browser half into an extension (the `extension-kit vendor` command). |
+| `renderToolbarIcons({chromium, dir})` | See above. |
+| `placeholderWarning`, `repositoryReminder`, `printReleaseChecks` | See About links. |
+| `findDisallowedClones({runJscpd})` | Run jscpd and return clones `.jscpd-allowlist.json` doesn't cover (the `extension-kit duplication` command). |
+
+### Copied-code guard
+
+With `jscpd` as a devDependency and a `.jscpd.json`, `extension-kit duplication` fails on any clone
+except those listed, each with a reason:
+
+```json
+{ "allow": [{ "files": ["test/e2e/a.mjs", "test/e2e/b.mjs"], "reason": "Two fixtures that must stay literal." }] }
+```
+
+## Test helpers (`@arraypress/extension-kit/testing`)
+
+| Export | What it does |
+|---|---|
+| `fakeChromeStorage({local, sync, session, now})` | In-memory `chrome.storage`: JSON copies, `onChanged` for real changes only, sync's 8,192-byte item quota and 120 writes a minute. `settled()` waits for listeners. |
+| `launchExtension(chromium, dir, options)` | Load an unpacked extension into a fresh profile; `{context, worker, extensionId, url(page), profile, close()}`. |
+| `extensionProfile(chromium, dir, options)` | A profile to start the browser on more than once (a restart, a first start with a changed manifest): `{dir, launch(), remove()}`. |
+| `checkRunner()` | Named checks that report and go on: `check(name, fn)`, `fail(name)` for an error found outside a check, `finish()`. |
+| `serve(routes, {port})` | Serve test pages on 127.0.0.1 from a table, a `Map` or a function of the path; `{origin, port, server, close()}`. |
+| `until(fn, what, timeout?)` | Poll until truthy. |
+| `offscreenEmulator(cdp)` | Emulate light/dark inside the offscreen document. |
+| `recordIconCalls(worker)` | Record `chrome.action.setIcon` calls Chrome accepted. |
+| `filesUnder`, `zipEntries`, `missingReferences`, `manifestReferences` | For a packaging test: the zip is the folder, and every path the extension names resolves. |
+
+## Stylesheet classes
+
+| Piece | Markup |
+|---|---|
+| Page column (680px, 96%) | `<main class="page">` |
+| Toolbar (56px) | `<header class="toolbar">` with `.toolbar-start` (img + `h1`), `.toolbar-center`, `.toolbar-end` |
+| Search pill | `<label class="search-field"><svg class="icon">…</svg><input type="search"></label>` |
+| Section title | `<h2 class="section-title">` above its card |
+| Card (one per section) | `<section class="card">` |
+| Row (48px) | `.row` with `<span class="label">Text<span class="secondary">Help</span></span>` and a control |
+| Two-line row (64px) | `.row.two-line` |
+| Paragraph row | `<p class="row text"><span class="label">…</span></p>` |
+| Value at the end | `<span class="row-value">⌥⇧W</span>` |
+| Heading inside a card | `.card-heading` |
+| Link row | `<button class="link-row">` (›) or `.link-row.external` (↗), label as in `.row` |
+| No separator above | `.first` / `.continuation` (the first row of a card gets none by itself) |
+| List of rows | `<ul class="list">` of `li.row` |
+| Toggle (cr-toggle) | `<input type="checkbox" class="switch" role="switch">` |
+| Select (md-select) | plain `<select>` |
+| Text field (cr-input) | plain `<input>`, `<textarea>`; `.field` > `label` + input for a labelled one |
+| Buttons (cr-button) | plain `<button>`; `.action` filled; `.link` as a link; `.icon-button` 32px round |
+| Settings menu | `.nav` > `ul.nav-list` > `a.nav-item[aria-current="page"]`, `.nav-separator` |
+| Manager layout | `.manager`/`.layout`, `.sidebar` with `.tree` > `.tree-item`, `.main` with `.list-card` |
+| Menu (cr-action-menu) | `<dialog class="menu">` of `button[role="menuitem"]`, `hr` |
+| Dialog (cr-dialog) | `<dialog class="dialog"><form method="dialog">` `.dialog-title`, `.dialog-body`, `.dialog-buttons` |
+| Toast (cr-toast) | `<div class="toast">text <button>Undo</button></div>` |
+| Drawer (cr-drawer) | `<dialog class="drawer">` with `.drawer-head` and a `.nav` |
+| Side panel page | `<body class="side-panel">`: the panel's colours, a column 100vh high |
+| Panel tabs (cr-tabs) | `<div class="tabs" role="tablist">` of `button.tab[role="tab"][aria-selected]` |
+| Panel body | `.sp-scroller`; `.search-field` inside a panel is the white pill |
+| Panel card | `<section class="sp-card">` with `.sp-heading` (`h2` + 24px `.icon-button`s, `.expand[aria-expanded]`) |
+| Panel row (cr-url-list-item) | `ul.sp-list` > `li.sp-item`: `button.sp-item-main`, `.sp-icon`, `.sp-text` > `.sp-title` + `.sp-description`, `.sp-suffix` |
+| Panel empty state | `.sp-empty` with `.icon`, `h2`, `p` |
+| Panel footer + pill | `<footer class="sp-footer"><button class="floating">` |
+| Utilities | `.secondary`, `.error`, `.hint`, `.mono`, `.visually-hidden`, `.icon`, `.sprite` |
+
+Tokens (`--text`, `--text-secondary`, `--primary`, `--separator`, `--card`, `--page-bg`, `--hover`,
+`--selected-bg`, the side panel's `--sp-*`, …) switch with `prefers-color-scheme`; use them for
+anything a page adds. Values come from Chromium's source, checked against chrome://settings and
+chrome://bookmarks in Chromium 156 / Chrome 157; the sources are listed at the top of the file.
+
+## Development
+
+`npm test` runs ESLint, a strict TypeScript check of the JSDoc (`checkJs`), the tests, and the
+copied-code guard. The `.d.ts` files are generated from the JSDoc: `npm run types` writes them, and
+the type check fails while one is stale (it regenerates them into `.types/` and compares).
+
+## License
+
+MIT © 2026 David Sherlock / ArrayPress Limited

package/bin/extension-kit.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+/**
+ * The kit's command line, run from an extension's npm scripts:
+ *
+ *   extension-kit vendor <dir>   copy the browser half into <dir> (npm install runs it)
+ *   extension-kit duplication    fail on copied code jscpd finds, less .jscpd-allowlist.json
+ *
+ * @module bin/extension-kit
+ */
+
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { findDisallowedClones } from '../src/build/duplication.js';
+import { vendorKit } from '../src/build/vendor.js';
+
+const [command, arg] = process.argv.slice(2);
+
+if (command === 'vendor' && arg) {
+  await vendorKit(path.resolve(arg));
+  console.log(`extension-kit: copied into ${arg}`);
+} else if (command === 'duplication') {
+  // jscpd is the extension's devDependency, so resolve it from there.
+  const { runJscpd } = createRequire(path.join(process.cwd(), 'package.json'))('jscpd');
+  const clones = await findDisallowedClones({ runJscpd });
+  for (const clone of clones) console.error(`Copied code (${clone.lines} lines): ${clone.where}`);
+  if (clones.length) {
+    console.error(`\n${clones.length} clone(s). Move the shared code into one function, or list the pair with a reason in .jscpd-allowlist.json.`);
+    process.exitCode = 1;
+  } else {
+    console.log('No copied code.');
+  }
+} else {
+  console.error('Usage: extension-kit vendor <dir> | extension-kit duplication');
+  process.exitCode = 2;
+}

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@arraypress/extension-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "Shared pieces for Chrome extensions: Chrome's own page styles, a Chrome Sync settings store, the light/dark toolbar glyph, About links, and build and test helpers.",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./build": {
+      "types": "./src/build/index.d.ts",
+      "import": "./src/build/index.js"
+    },
+    "./testing": {
+      "types": "./src/testing/index.d.ts",
+      "import": "./src/testing/index.js"
+    },
+    "./chrome-ui.css": "./src/styles/chrome-ui.css"
+  },
+  "bin": {
+    "extension-kit": "bin/extension-kit.js"
+  },
+  "files": [
+    "src",
+    "bin"
+  ],
+  "scripts": {
+    "test": "npm run lint && npm run typecheck && node --test tests/*.test.js && npm run duplication",
+    "lint": "eslint .",
+    "typecheck": "tsc -p . && tsc -p tsconfig.types.json && diff -r -x '*.js' -x styles .types src && rm -rf .types",
+    "types": "tsc -p tsconfig.types.json && cp -R .types/. src/ && rm -rf .types",
+    "duplication": "node bin/extension-kit.js duplication"
+  },
+  "keywords": [
+    "chrome-extension",
+    "manifest-v3",
+    "chrome-storage",
+    "chrome-sync",
+    "settings",
+    "dark-mode",
+    "toolbar-icon",
+    "css"
+  ],
+  "author": "David Sherlock",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arraypress/extension-kit.git"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/chrome": "^0.3.7",
+    "@types/jsdom": "^30.0.0",
+    "@types/node": "^26.6.6",
+    "eslint": "^10.14.0",
+    "globals": "^17.14.0",
+    "jscpd": "^5.4.3",
+    "jsdom": "^31.0.0",
+    "playwright": "^1.64.0",
+    "typescript": "^7.0.2"
+  }
+}

package/src/about/links.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The links on an extension's About card ("Get help", "Report an issue",
+ * "Privacy policy"), kept in the extension's GitHub repository: the README,
+ * Issues and PRIVACY.md. The repository must be public before the extension
+ * is published, or these links show GitHub's 404; the build helpers'
+ * `repositoryReminder` says so at package time.
+ *
+ * @module about/links
+ */
+export type AboutLinks = {
+    /**
+     * "Get help with …": the README.
+     */
+    help: string;
+    /**
+     * "Report an issue": GitHub Issues.
+     */
+    reportIssue: string;
+    /**
+     * "Privacy policy": PRIVACY.md on the main branch.
+     */
+    privacyPolicy: string;
+};
+/**
+ * @typedef {object} AboutLinks
+ * @property {string} help "Get help with …": the README.
+ * @property {string} reportIssue "Report an issue": GitHub Issues.
+ * @property {string} privacyPolicy "Privacy policy": PRIVACY.md on the main branch.
+ */
+/**
+ * The About card's links for a GitHub repository.
+ *
+ * @param {string} repository - The repository's address, no trailing slash.
+ * @returns {Readonly<AboutLinks>} The three links.
+ * @example
+ * githubAboutLinks('https://github.com/arraypress/upright').reportIssue;
+ * // 'https://github.com/arraypress/upright/issues'
+ */
+export declare function githubAboutLinks(repository: string): Readonly<AboutLinks>;
+/**
+ * Whether a link is a placeholder: its host is one reserved for examples
+ * (RFC 2606), or a subdomain of one. A `mailto:` link or a real domain isn't.
+ *
+ * @param {string} url - An absolute URL.
+ * @returns {boolean} True for example.com, example.org, example.net and their subdomains.
+ * @throws {TypeError} When `url` isn't an absolute URL.
+ * @example
+ * isPlaceholder('https://www.example.org/help'); // true
+ * isPlaceholder('https://notexample.com/');      // false
+ */
+export declare function isPlaceholder(url: string): boolean;

package/src/about/links.js

@@ -0,0 +1,48 @@
+/**
+ * The links on an extension's About card ("Get help", "Report an issue",
+ * "Privacy policy"), kept in the extension's GitHub repository: the README,
+ * Issues and PRIVACY.md. The repository must be public before the extension
+ * is published, or these links show GitHub's 404; the build helpers'
+ * `repositoryReminder` says so at package time.
+ *
+ * @module about/links
+ */
+
+/**
+ * @typedef {object} AboutLinks
+ * @property {string} help "Get help with …": the README.
+ * @property {string} reportIssue "Report an issue": GitHub Issues.
+ * @property {string} privacyPolicy "Privacy policy": PRIVACY.md on the main branch.
+ */
+
+/**
+ * The About card's links for a GitHub repository.
+ *
+ * @param {string} repository - The repository's address, no trailing slash.
+ * @returns {Readonly<AboutLinks>} The three links.
+ * @example
+ * githubAboutLinks('https://github.com/arraypress/upright').reportIssue;
+ * // 'https://github.com/arraypress/upright/issues'
+ */
+export function githubAboutLinks(repository) {
+  return Object.freeze({
+    help: `${repository}#readme`,
+    reportIssue: `${repository}/issues`,
+    privacyPolicy: `${repository}/blob/main/PRIVACY.md`,
+  });
+}
+
+/**
+ * Whether a link is a placeholder: its host is one reserved for examples
+ * (RFC 2606), or a subdomain of one. A `mailto:` link or a real domain isn't.
+ *
+ * @param {string} url - An absolute URL.
+ * @returns {boolean} True for example.com, example.org, example.net and their subdomains.
+ * @throws {TypeError} When `url` isn't an absolute URL.
+ * @example
+ * isPlaceholder('https://www.example.org/help'); // true
+ * isPlaceholder('https://notexample.com/');      // false
+ */
+export function isPlaceholder(url) {
+  return /(^|\.)example\.(com|org|net)$/.test(new URL(url).hostname);
+}

package/src/build/duplication.d.ts

@@ -0,0 +1,116 @@
+/**
+ * A guard against copied code: run jscpd over a repository with its
+ * `.jscpd.json` and fail on any clone, except the deliberate ones listed,
+ * each with its reason, in `.jscpd-allowlist.json`:
+ *
+ *     { "allow": [{ "files": ["test/a.js", "test/b.js"], "reason": "…" }] }
+ *
+ * A clone is allowed when both of its files are in one entry. jscpd is the
+ * caller's (a devDependency), passed in as its `runJscpd`, so this package
+ * needs none.
+ *
+ * @module build/duplication
+ */
+export type Clone = {
+    /**
+     * First file, relative to the scan's folder.
+     */
+    first: string;
+    /**
+     * Second file (may equal `first`).
+     */
+    second: string;
+    /**
+     * How many lines it spans.
+     */
+    lines: number;
+    /**
+     * "a.js:10-20 ~ b.js:30-40", for messages.
+     */
+    where: string;
+};
+export type AllowEntry = {
+    /**
+     * Files whose clones of each other are allowed.
+     */
+    files: string[];
+    /**
+     * Why the copy stays.
+     */
+    reason: string;
+};
+export type RunJscpd = (args: readonly string[], options: {
+    cwd: string;
+    encoding: 'utf8';
+}) => {
+    status: number | null;
+    stderr: string;
+    error?: Error;
+};
+/**
+ * One clone from jscpd's JSON report, reduced to where it is.
+ *
+ * @typedef {object} Clone
+ * @property {string} first First file, relative to the scan's folder.
+ * @property {string} second Second file (may equal `first`).
+ * @property {number} lines How many lines it spans.
+ * @property {string} where "a.js:10-20 ~ b.js:30-40", for messages.
+ */
+/**
+ * One deliberate exception.
+ *
+ * @typedef {object} AllowEntry
+ * @property {string[]} files Files whose clones of each other are allowed.
+ * @property {string} reason Why the copy stays.
+ */
+/**
+ * jscpd's `runJscpd` (from the `jscpd` package): spawns its binary.
+ *
+ * @typedef {(args: readonly string[], options: {cwd: string, encoding: 'utf8'}) => {status: number | null, stderr: string, error?: Error}} RunJscpd
+ */
+/**
+ * The clones jscpd's JSON report lists.
+ *
+ * @param {{duplicates?: {firstFile: {name: string, start: number, end: number}, secondFile: {name: string, start: number, end: number}, lines: number}[]}} report
+ *   The parsed `jscpd-report.json`.
+ * @returns {Clone[]} One entry per clone.
+ */
+export declare function clonesFromReport(report: {
+    duplicates?: {
+        firstFile: {
+            name: string;
+            start: number;
+            end: number;
+        };
+        secondFile: {
+            name: string;
+            start: number;
+            end: number;
+        };
+        lines: number;
+    }[];
+}): Clone[];
+/**
+ * The clones no allowlist entry covers.
+ *
+ * @param {readonly Clone[]} clones - What jscpd found.
+ * @param {readonly AllowEntry[]} allow - The deliberate exceptions.
+ * @returns {Clone[]} The clones to fail on.
+ * @example
+ * disallowedClones(clones, [{ files: ['a.js', 'b.js'], reason: 'fixtures' }]);
+ */
+export declare function disallowedClones(clones: readonly Clone[], allow: readonly AllowEntry[]): Clone[];
+/**
+ * Run jscpd in `cwd` (it reads `.jscpd.json` there) and report clones the
+ * allowlist doesn't cover.
+ *
+ * @param {object} options - How to run.
+ * @param {RunJscpd} options.runJscpd - From the `jscpd` package.
+ * @param {string} [options.cwd] - The repository. Default the current folder.
+ * @returns {Promise<Clone[]>} The disallowed clones; empty means clean.
+ * @throws {Error} When jscpd can't run.
+ */
+export declare function findDisallowedClones({ runJscpd, cwd }: {
+    runJscpd: RunJscpd;
+    cwd?: string;
+}): Promise<Clone[]>;