@openmixer/plugin-qualify 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,204 @@
-# Temporary Holding Version
+# plugin-qualify
 
-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.
+Can this audio plugin be hosted in a real-time audio engine, and at what cost? `plugin-qualify`
+scans a plugin, measures it offline (latency and CPU cost per rate and quantum), runs it
+under a real host (mod-host, with an AddressSanitizer build), and gives one verdict.
+Licence: GPL-3.0-or-later (`LICENSE`).
+
+## Install
+
+plugin-qualify is published, signed, in the FreeMixer package channel, for Fedora 44 (x86_64, aarch64)
+and for Debian bookworm and trixie, including Raspberry Pi OS (amd64, arm64).
+
+Fedora:
+
+```
+sudo dnf config-manager addrepo --from-repofile=https://freemixer.github.io/rpm/freemixer.repo
+sudo dnf install plugin-qualify
+```
+
+Debian and Raspberry Pi OS:
+
+```
+sudo install -d /etc/apt/keyrings
+sudo curl -fsSL -o /etc/apt/keyrings/freemixer.asc https://freemixer.github.io/deb/freemixer.asc
+echo "deb [signed-by=/etc/apt/keyrings/freemixer.asc] https://freemixer.github.io/deb/debian/$(. /etc/os-release && echo $VERSION_CODENAME) ./" | sudo tee /etc/apt/sources.list.d/freemixer.list
+sudo apt update
+sudo apt install plugin-qualify
+```
+
+There is no npm package on the registry yet; the GitHub release carries the packed one,
+`openmixer-plugin-qualify-<version>.tgz`, which `pnpm add` takes by its download URL. To run from a
+checkout instead (Node.js 20 or newer and pnpm 10, see `BUILDING.md`):
+
+```
+git clone https://github.com/FreeMixer/plugin-qualify.git
+cd plugin-qualify
+pnpm install
+pnpm exec plugin-qualify --help
+```
+
+It needs Node.js 18 or newer to run. The measuring tools also want Python 3 with the lilv bindings
+(`python3-lilv`) and, for the hosting sweep, `mod-host`. The `Containerfile` builds an image with all of
+them. The commands below are written as `plugin-qualify`; from a checkout run them with `pnpm exec`.
+
+## Run it on your own plugin
+
+```
+plugin-qualify urn:example:my-plugin          # one plugin, by URI
+plugin-qualify ./my-plugin.lv2                # every plugin in a bundle
+plugin-qualify --all                          # everything lilv finds (LV2_PATH honoured)
+plugin-qualify --help                         # every option and its default
+```
+
+`--format json` prints the verdicts as JSON; `--out <dir>` writes the full measurement document.
+`--isolate` measures each plugin in a fresh worker so a crash or hang takes only that plugin;
+`--no-host-sweep` measures offline only, without mod-host. The `Containerfile` builds an image
+with lilv, mod-host and the ASan mod-host, if you do not want to install them yourself.
+
+Exit code: `0` every plugin qualified, `1` some did not, `2` something could not be measured.
+
+## CLAP plugins: the RT-safety verdict
+
+A `.clap` file, or a directory holding one, is scanned by `omx-clap-scan` (from omx-clap-core; set
+`OMX_CLAP_SCAN` to its path when it is not on `PATH`) and each plugin in it is then qualified by the
+CLAP prober built from `native/` (`make -C native deps all`, see `BUILDING.md`):
+
+```
+plugin-qualify ./my-fx.clap                   # every plugin in the file
+plugin-qualify --out ./out ./my-fx.clap       # and its RT-safety documents
+```
+
+The prober runs each plugin headless at every `--rates` rate, under an interposer that counts the
+allocations, locks and syscalls its `process()` makes while every parameter is swept, and prints
+the file's SHA-256 beside what it measured. The verdict is the real-time-safety one: **suitable**
+only on a clean count, **unsuitable** on any allocation, lock, syscall, main-thread host call from
+`process()` or `CLAP_PROCESS_ERROR`, **unknown** when it could not be counted. `--out` writes one
+document per plugin binary and host profile, named `<sha256>.<profile>.rt-safety.json`, so a
+verdict never outlives the bytes it was measured on. `OMX_CLAP_QUALIFY` and `OMX_RT_INTERPOSE`
+name the prober and the interposer when they are not the checkout's own build.
+
+The prober also scans: `OMX_CLAP_SCAN=native/build/clap-qualify` makes it the scanner, and its scan
+keeps what a console needs to draw a third-party plugin's controls: an enum parameter's labels (as
+the plugin's `value_to_text` renders them), each parameter's module, and the plugin's
+remote-control pages.
+
+## What the verdicts mean
+
+- **suitable**: every dimension was measured and passed. Safe to run inside the engine's own
+  process. This is the only verdict that counts as qualified.
+- **conditional**: it works, with a caution (for example a high cost at small quanta). It is
+  run isolated, and the deciding reason names the caution.
+- **unknown**: something was not measured. An unmeasured plugin is never a pass.
+- **unsuitable**: a measured failure: a crash, a memory error in the plugin's own binary, a
+  real-time violation (allocation, locks or syscalls in `run()`), or a required feature the
+  host does not provide.
+
+The worst dimension decides. The text output prints the plugin, its verdict and the reason that
+decided it.
+
+## Reproducing a failure
+
+1. Run the plugin alone: `plugin-qualify --format json --out ./out <uri>`.
+2. The document in `./out` names the dimension that failed and, for a crash, the sanitizer class
+   and the object of the faulting frame.
+3. Run the ASan mod-host (`mod-host-asan` in the image) with just that plugin to get the full
+   sanitizer report.
+
+`fixtures/zero-path.lv2` is a known-bad plugin (a zero-size `atom:Path` overread). It should
+rate **unsuitable**; if it does not, the sweep is not catching memory errors.
+
+## For other projects (zynthian, MOD, packagers)
+
+The measurements describe the plugin and never the host: latency and cost per rate, whether it
+survives a thousand lifecycles and a three-hour soak, whether `run()` allocates, locks or makes
+syscalls, and which LV2 features it requires. They are taken once. The **verdict** is a separate
+step: the same measurements judged against a **host profile**, the facts that differ between
+hosts. Two projects share the measurements and differ only in the profile they choose.
+
+### Choosing a host profile
+
+```
+plugin-qualify --host-profile jalv ./my-synth.lv2                  # zynthian: one jalv process per plugin
+plugin-qualify --host-profile mod-host ./my-fx.lv2                 # MOD: one shared mod-host process
+plugin-qualify --host-profile jalv,mod-host,openmixer-console <uri>  # one verdict per profile
+plugin-qualify --host-profile ./my-host.json <uri>                 # your own host
+```
+
+| profile | isolation | instruments | LV2 features read from | cost budget (P95 of a core, rate / quantum) |
+|---|---|---|---|---|
+| `openmixer-console` (default) | in-process (the console's RT thread) | no | the console's in-process table | 0.05 at 96000 / 1024 |
+| `jalv` | per-process | yes | jalv 1.6.8 `src/jalv.c` (zynthian's fork passes the same list) | 0.25 at 48000 / 256 |
+| `mod-host` | shared-process | yes | mod-host f14a230 `src/effects.c` | 0.05 at 48000 / 128 |
+
+The `jalv` and `mod-host` budgets are defaults, not a measurement of your board. State your own
+by writing a profile file. Every field is required; a missing or mistyped field is refused and
+never filled in with a default:
+
+```json
+{
+  "id": "zynthian-v5",
+  "lv2Features": ["http://lv2plug.in/ns/ext/urid#map", "http://lv2plug.in/ns/ext/urid#unmap",
+                  "http://lv2plug.in/ns/ext/worker#schedule", "http://lv2plug.in/ns/ext/log#log",
+                  "http://lv2plug.in/ns/ext/options#options",
+                  "http://lv2plug.in/ns/ext/state#loadDefaultState",
+                  "http://lv2plug.in/ns/ext/buf-size#powerOf2BlockLength",
+                  "http://lv2plug.in/ns/ext/buf-size#fixedBlockLength",
+                  "http://lv2plug.in/ns/ext/buf-size#boundedBlockLength"],
+  "clapExtensions": null,
+  "instruments": true,
+  "cost": { "coreFractionCeiling": 0.3, "rate": 48000, "quantum": 256 },
+  "latency": "uncompensated",
+  "isolation": "per-process"
+}
+```
+
+What each field changes. `lv2Features` is what the host passes to `instantiate`: a plugin that
+requires anything else is **unsuitable** on that host. `clapExtensions` is `null` for a host with
+no CLAP path. `instruments: true` means a MIDI input is fed, and a plugin with no audio input but
+a MIDI input and an audio output rates as an instrument. `cost` is the per-instance ceiling, and
+the rate and quantum the verdict is judged at. `latency: "compensated"` means the host aligns on
+the plugin's latency, so a latency that moves with a control is a caution. `isolation` decides
+whether spawned threads and a linked GUI toolkit count as cautions: they do only when the plugin
+shares its process. An unmeasured dimension is **unknown** on every host.
+
+With several profiles, the exit code is `0` only if every plugin qualifies under every profile.
+
+### The JSON document
+
+`--out <dir>` writes one interchange document per run (`lv2-plugin-measurements`, format 1.2,
+the same format the OpenMixer console reads). The
+`plugins` array holds the raw, host-free measurements. Beside it, `hostProfiles` holds each
+profile the run judged against, in full, and `verdicts` holds one entry per plugin per profile:
+
+```json
+{ "uri": "urn:example:verb", "host": "jalv", "rating": "unknown", "qualified": false,
+  "deciding": "hosting.stability.unsoaked" }
+```
+
+`host` is the `id` of an entry in `hostProfiles`. `deciding` is a stable code, absent when the
+plugin is `suitable`. If you have your own host rules, re-derive them from `plugins` and do not
+trust another host's verdict.
+
+### As a library
+
+`classifyPluginHosting(plugin, { rate, quantum, profile })` gives one verdict, and
+`qualifyPlugins(measured, { profiles })` gives one per plugin per profile. `readHostProfile(json)`
+validates a profile file, and `judgedDocument(run, plugins, profiles, verdicts)` builds the
+document. All of them are exported from the package root. The package depends on no other
+OpenMixer package.
+
+### The container image
+
+```
+podman build -t plugin-qualify -f Containerfile .
+podman run --rm -v "$PWD/my-plugins:/plugins:ro" -e LV2_PATH=/plugins -v "$PWD/out:/out" \
+  plugin-qualify --host-profile jalv --all --out /out
+```
+
+The image has lilv, the distribution's mod-host and an AddressSanitizer build of mod-host.
+
+**Status:** the pure steps are in place and tested: target resolution, profile resolution, the
+verdict, the document and the exit code. The command-line entry point does not yet drive the
+measuring tools (`tools/lv2-measure.mjs`, the mod-host sweep). A run that would measure exits
+`2` and names the missing step, rather than rate a plugin on less than was asked.

package/bin/plugin-qualify.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * `plugin-qualify` — the entry point (spec 2026-09-25-plugin-qualify.md §5). Every decision is a
+ * pure function in `src/qualify-cli.ts`; this file only reads argv, prints and exits.
+ *
+ * CLAP targets are qualified here: the prober (`native/clap-qualify`) runs each under the interposer
+ * and every plugin gets its RT-safety verdict document, per binary hash and console.
+ *
+ * NOT YET WIRED for LV2 (refused with exit 2, never a silent partial run): driving the offline pass
+ * (`tools/lv2-measure.mjs`) for a named subset and the mod-host hosting sweep from this entry
+ * point. Until then a run that would measure an LV2 refuses and says which step is missing.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import {
+  ClapScanError,
+  EXIT_CODE,
+  clapLoader,
+  exitCodeFor,
+  helpText,
+  lv2Loader,
+  parseQualifyArgs,
+  qualifyClapTargets,
+  resolveHostProfiles,
+  resolveTargets,
+  rtSafetyDocumentName,
+  textTable,
+} from "../dist/index.js";
+
+const parsed = parseQualifyArgs(process.argv.slice(2));
+if (!parsed.ok) {
+  process.stderr.write(`plugin-qualify: ${parsed.error}\n\n${helpText()}`);
+  process.exit(EXIT_CODE.couldNotMeasure);
+}
+if (parsed.args.help) {
+  process.stdout.write(helpText());
+  process.exit(EXIT_CODE.allQualified);
+}
+const profiles = resolveHostProfiles(parsed.args.hostProfiles);
+if (!profiles.ok) {
+  for (const r of profiles.refused) process.stderr.write(`plugin-qualify: --host-profile ${r.spec}: ${r.problem}\n`);
+  process.exit(EXIT_CODE.couldNotMeasure);
+}
+for (const p of profiles.profiles) process.stderr.write(`plugin-qualify: host profile ${p.id} (${p.isolation})\n`);
+if (!parsed.args.all) {
+  let r;
+  try {
+    r = resolveTargets(parsed.args.targets, [clapLoader(), lv2Loader]);
+  } catch (e) {
+    if (!(e instanceof ClapScanError)) throw e;
+    process.stderr.write(`plugin-qualify: ${e.message}\n`);
+    process.exit(EXIT_CODE.couldNotMeasure);
+  }
+  if (!r.ok) {
+    process.stderr.write(`plugin-qualify: no plugin found for: ${r.refused.join(", ")}\n`);
+    process.exit(EXIT_CODE.couldNotMeasure);
+  }
+  for (const p of r.plugins) process.stderr.write(`plugin-qualify: target ${p.uri}${p.bundle ? ` (${p.bundle})` : ""}\n`);
+  if (r.plugins.every((p) => p.format === "clap")) {
+    const pass = qualifyClapTargets(r.plugins, { rates: parsed.args.rates, profiles: profiles.profiles });
+    for (const f of pass.failures) process.stderr.write(`plugin-qualify: ${f.uri}: ${f.problem}\n`);
+    if (parsed.args.out !== undefined) {
+      mkdirSync(parsed.args.out, { recursive: true });
+      for (const doc of pass.documents) writeFileSync(join(parsed.args.out, rtSafetyDocumentName(doc)), `${JSON.stringify(doc, null, 2)}\n`);
+    }
+    process.stdout.write(parsed.args.format === "json" ? `${JSON.stringify(pass.documents, null, 2)}\n` : textTable(pass.verdicts));
+    process.exit(exitCodeFor(pass.verdicts));
+  }
+}
+process.stderr.write(
+  "plugin-qualify: measuring from this entry point is not wired yet " +
+    "(offline pass: tools/lv2-measure.mjs; hosting sweep: mod-host) — refusing rather than rating on less\n",
+);
+process.exit(EXIT_CODE.couldNotMeasure);

package/dist/clap-loader.d.ts

@@ -0,0 +1,147 @@
+import type { PluginLoader } from "./loader.js";
+export declare class ClapScanError extends Error {
+    constructor(message: string);
+}
+export interface ClapScanParam {
+    readonly id: number;
+    readonly name: string;
+    readonly module: string;
+    /** null where the plugin leaves the bound open (JSON has no infinity). */
+    readonly min: number | null;
+    readonly max: number | null;
+    readonly default: number | null;
+    readonly flags: readonly string[];
+    /** An enum parameter's labels, as `value_to_text` renders each whole value of its range. */
+    readonly labels?: readonly ClapScanLabel[];
+}
+export interface ClapScanLabel {
+    readonly value: number;
+    readonly label: string;
+}
+/** A remote-control page: eight slots, each a parameter id or null when empty. */
+export interface ClapScanRemotePage {
+    readonly id: number;
+    readonly section: string;
+    readonly name: string;
+    readonly params: readonly (number | null)[];
+    readonly forPreset: boolean;
+}
+export interface ClapScanPort {
+    readonly id: number;
+    readonly name: string;
+    readonly role: "main" | "aux";
+    readonly channels: number;
+}
+/** A plugin the scanner created and read. */
+export interface ClapScanPlugin {
+    readonly id: string;
+    readonly name: string;
+    readonly vendor: string;
+    readonly version: string;
+    readonly description: string;
+    readonly url: string;
+    readonly features: readonly string[];
+    readonly params: readonly ClapScanParam[];
+    /** Absent where the scanner does not read the pages. */
+    readonly remote_controls?: readonly ClapScanRemotePage[];
+    readonly audio_ports: {
+        readonly inputs: readonly ClapScanPort[];
+        readonly outputs: readonly ClapScanPort[];
+    };
+    readonly note_ports: {
+        readonly inputs: number;
+        readonly outputs: number;
+    };
+    /** Frames, present only when the plugin reported more than 0 before it was activated. */
+    readonly latency?: number;
+}
+/** A plugin whose descriptor was read but which could not be created or initialised. */
+export interface ClapScanPluginError {
+    readonly id: string;
+    readonly name: string;
+    readonly error: string;
+}
+export type ClapScanFile = {
+    readonly path: string;
+    readonly plugins: readonly (ClapScanPlugin | ClapScanPluginError)[];
+} | {
+    readonly path: string;
+    readonly error: string;
+};
+export interface ClapScanDocument {
+    readonly scanner: string;
+    readonly version: string;
+    readonly files: readonly ClapScanFile[];
+}
+/** The scanner's stdout as its document, or a {@link ClapScanError} saying how it differs. */
+export declare function parseClapScan(text: string): ClapScanDocument;
+/** One control, shaped as the catalog's `PluginParam` (structurally; this package imports no other). */
+export interface ClapDescriptorParam extends ClapControlBounds {
+    readonly isInteger: boolean;
+    readonly isToggle: boolean;
+    readonly isEnumeration: boolean;
+    readonly kind: "control";
+    /** The CLAP parameter id in decimal — the key `param_set` takes. */
+    readonly symbol: string;
+    readonly name: string;
+    /** The parameter's module path (`Filter/Envelope`), where the plugin names one. */
+    readonly module?: string;
+    /** An enum parameter's labels, where the scan read them. */
+    readonly scalePoints?: readonly {
+        readonly label: string;
+        readonly value: number;
+    }[];
+}
+/** A remote-control page, its slots as parameter symbols (null where empty). */
+export interface ClapDescriptorRemotePage {
+    readonly id: number;
+    readonly section: string;
+    readonly name: string;
+    readonly params: readonly (string | null)[];
+}
+/** Each bound is absent where the plugin leaves it open. */
+interface ClapControlBounds {
+    readonly min?: number;
+    readonly max?: number;
+    readonly default?: number;
+}
+/** A scanned CLAP plugin as the catalog's `PluginDescriptor` reads it — a declared fact of the scan. */
+export interface ClapDescriptorRow {
+    readonly uri: string;
+    readonly name: string;
+    readonly lv2Class: null;
+    readonly audioInputs: number;
+    readonly audioOutputs: number;
+    readonly hasMidiIn: boolean;
+    readonly params: readonly ClapDescriptorParam[];
+    readonly format: "clap";
+    readonly binaryPath: string;
+    readonly latency?: {
+        readonly reportedFrames: number;
+    };
+    /** The plugin's remote-control pages (presets' own pages excluded), where the scan read them. */
+    readonly remoteControls?: readonly ClapDescriptorRemotePage[];
+}
+/**
+ * The rows for every plugin the scanner created. A hidden or read-only parameter is not a
+ * control anyone may set, so it is not offered as one. Nothing here claims a qualification:
+ * the `clap` measurement stays absent, which the verdict reads as `unknown`.
+ */
+export declare function clapScanDescriptors(doc: ClapScanDocument): ClapDescriptorRow[];
+/** What a run of the scanner gave back; `error` is a spawn failure (absent binary, timeout). */
+export interface ClapScanRunResult {
+    readonly status: number | null;
+    readonly stdout: string;
+    readonly error?: Error;
+}
+export type ClapScanRun = (tool: string, args: readonly string[], timeoutMs: number) => ClapScanRunResult;
+/** The scanner binary: the declared setting when set, else the declared default (on `PATH`). */
+export declare function clapScanTool(env: Readonly<Record<string, string | undefined>>): string;
+export interface ClapLoaderOptions {
+    /** Runs the scanner; the default spawns it. Injectable so the seam is testable without the binary. */
+    readonly run?: ClapScanRun;
+    /** Where the one setting is read from; the default is `process.env`. */
+    readonly env?: Readonly<Record<string, string | undefined>>;
+}
+export declare function clapLoader(options?: ClapLoaderOptions): PluginLoader;
+export {};

package/dist/clap-loader.js

@@ -0,0 +1,252 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * The CLAP implementation of the one discovery seam (`loader.ts`). A target that is a `.clap` file, or a
+ * directory holding one, is scanned by `omx-clap-scan --json` (the scanner of omx-clap-host),
+ * located by the ONE declared setting; `urn:clap:<id>` is one plugin without a scan. The
+ * scanner's JSON is the input: {@link clapScanDescriptors} normalises it into the interchange
+ * rows. A scan that cannot be read is a {@link ClapScanError}, never an empty result.
+ *
+ * plugin-qualify's own prober writes the same document (`native/clap-qualify --json`, set as the
+ * scanner by the same setting), and with it an enum parameter's labels and the plugin's
+ * remote-control pages; a row keeps them, and each parameter's module, wherever the scan read them.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { CLAP_SCAN_TIMEOUT_S, CLAP_SCAN_TOOL_DEFAULT, CLAP_SCAN_TOOL_ENV } from "./qualify-declarations.js";
+/** The scanner's own name in its document — anything else is not its output. */
+const SCANNER_NAME = "omx-clap-scan";
+/** The same document from plugin-qualify's own prober (`native/clap-qualify --json`). */
+const SCANNER_NAMES = [SCANNER_NAME, "clap-qualify"];
+const CLAP_URI = /^urn:clap:(\S+)$/;
+const CLAP_SUFFIX = ".clap";
+/** A `.clap` directory listing can be tens of megabytes of JSON. */
+const MAX_SCAN_BYTES = 1 << 30;
+export class ClapScanError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ClapScanError";
+    }
+}
+function isRecord(v) {
+    return Object.prototype.toString.call(v) === "[object Object]";
+}
+function bad(what) {
+    throw new ClapScanError(`${SCANNER_NAME} output is not its document: ${what}`);
+}
+function str(o, key, where) {
+    const v = o[key];
+    return typeof v === "string" ? v : bad(`${where} has no string ${key}`);
+}
+function num(o, key, where) {
+    const v = o[key];
+    return typeof v === "number" ? v : bad(`${where} has no number ${key}`);
+}
+function list(o, key, where) {
+    const v = o[key];
+    return Array.isArray(v) ? v : bad(`${where} has no array ${key}`);
+}
+function bound(o, key, where) {
+    const v = o[key];
+    return v === null ? null : typeof v === "number" ? v : bad(`${where} has no number or null ${key}`);
+}
+function parsePort(v, where) {
+    if (!isRecord(v))
+        return bad(`${where} is not an object`);
+    const role = str(v, "role", where);
+    if (role !== "main" && role !== "aux")
+        return bad(`${where} has role ${role}`);
+    return { id: num(v, "id", where), name: str(v, "name", where), role, channels: num(v, "channels", where) };
+}
+function parseLabel(v, where) {
+    if (!isRecord(v))
+        return bad(`${where} is not an object`);
+    return { value: num(v, "value", where), label: str(v, "label", where) };
+}
+function parsePage(v, where) {
+    if (!isRecord(v))
+        return bad(`${where} is not an object`);
+    const slots = list(v, "params", where).map((p) => (p === null || typeof p === "number" ? p : bad(`${where} has a slot that is not an id or null`)));
+    const forPreset = v["forPreset"];
+    if (typeof forPreset !== "boolean")
+        return bad(`${where} has no boolean forPreset`);
+    return { id: num(v, "id", where), section: str(v, "section", where), name: str(v, "name", where), params: slots, forPreset };
+}
+function parsePlugin(v, where) {
+    if (!isRecord(v))
+        return bad(`${where} is not an object`);
+    const id = str(v, "id", where);
+    const name = str(v, "name", where);
+    if (typeof v["error"] === "string")
+        return { id, name, error: v["error"] };
+    const ports = v["audio_ports"];
+    const notes = v["note_ports"];
+    if (!isRecord(ports))
+        return bad(`${where} has no audio_ports`);
+    if (!isRecord(notes))
+        return bad(`${where} has no note_ports`);
+    const params = list(v, "params", where).map((p, i) => {
+        const w = `${where} param ${i}`;
+        if (!isRecord(p))
+            return bad(`${w} is not an object`);
+        return {
+            id: num(p, "id", w),
+            name: str(p, "name", w),
+            module: str(p, "module", w),
+            min: bound(p, "min", w),
+            max: bound(p, "max", w),
+            default: bound(p, "default", w),
+            flags: list(p, "flags", w).map((f) => (typeof f === "string" ? f : bad(`${w} has a flag that is not a string`))),
+            ...(p["labels"] === undefined ? {} : { labels: list(p, "labels", w).map((l, k) => parseLabel(l, `${w} label ${k}`)) }),
+        };
+    });
+    const pages = v["remote_controls"] === undefined ? undefined : list(v, "remote_controls", where).map((r, i) => parsePage(r, `${where} page ${i}`));
+    return {
+        id,
+        name,
+        vendor: str(v, "vendor", where),
+        version: str(v, "version", where),
+        description: str(v, "description", where),
+        url: str(v, "url", where),
+        features: list(v, "features", where).map((f) => (typeof f === "string" ? f : bad(`${where} has a feature that is not a string`))),
+        params,
+        audio_ports: {
+            inputs: list(ports, "inputs", `${where} audio_ports`).map((p, i) => parsePort(p, `${where} input ${i}`)),
+            outputs: list(ports, "outputs", `${where} audio_ports`).map((p, i) => parsePort(p, `${where} output ${i}`)),
+        },
+        note_ports: { inputs: num(notes, "inputs", `${where} note_ports`), outputs: num(notes, "outputs", `${where} note_ports`) },
+        ...(pages === undefined ? {} : { remote_controls: pages }),
+        ...(v["latency"] === undefined ? {} : { latency: num(v, "latency", where) }),
+    };
+}
+/** The scanner's stdout as its document, or a {@link ClapScanError} saying how it differs. */
+export function parseClapScan(text) {
+    let doc;
+    try {
+        doc = JSON.parse(text);
+    }
+    catch {
+        throw new ClapScanError(`${SCANNER_NAME} printed something that is not JSON`);
+    }
+    if (!isRecord(doc))
+        return bad("not an object");
+    const scanner = doc["scanner"];
+    if (typeof scanner !== "string" || !SCANNER_NAMES.includes(scanner))
+        return bad(`scanner is ${JSON.stringify(scanner)}`);
+    const files = list(doc, "files", "the document").map((f, i) => {
+        const where = `file ${i}`;
+        if (!isRecord(f))
+            return bad(`${where} is not an object`);
+        const path = str(f, "path", where);
+        if (typeof f["error"] === "string")
+            return { path, error: f["error"] };
+        return { path, plugins: list(f, "plugins", `file ${path}`).map((p, j) => parsePlugin(p, `plugin ${j} of ${path}`)) };
+    });
+    return { scanner, version: str(doc, "version", "the document"), files };
+}
+function isPlugin(p) {
+    return !("error" in p);
+}
+function controlOf(p) {
+    const stepped = p.flags.includes("stepped");
+    return {
+        kind: "control",
+        symbol: String(p.id),
+        name: p.name,
+        ...(p.min === null ? {} : { min: p.min }),
+        ...(p.max === null ? {} : { max: p.max }),
+        ...(p.default === null ? {} : { default: p.default }),
+        isInteger: stepped,
+        isToggle: stepped && p.min === 0 && p.max === 1,
+        isEnumeration: p.flags.includes("enum"),
+        ...(p.module === "" ? {} : { module: p.module }),
+        ...(p.labels === undefined || p.labels.length === 0 ? {} : { scalePoints: p.labels.map(({ label, value }) => ({ label, value })) }),
+    };
+}
+function pageOf(page) {
+    return { id: page.id, section: page.section, name: page.name, params: page.params.map((id) => (id === null ? null : String(id))) };
+}
+const channels = (ports) => ports.reduce((n, p) => n + p.channels, 0);
+/**
+ * The rows for every plugin the scanner created. A hidden or read-only parameter is not a
+ * control anyone may set, so it is not offered as one. Nothing here claims a qualification:
+ * the `clap` measurement stays absent, which the verdict reads as `unknown`.
+ */
+export function clapScanDescriptors(doc) {
+    const rows = [];
+    for (const file of doc.files) {
+        if (!("plugins" in file))
+            continue;
+        const binaryPath = resolve(file.path);
+        for (const p of file.plugins) {
+            if (!isPlugin(p))
+                continue;
+            rows.push({
+                uri: `urn:clap:${p.id}`,
+                name: p.name,
+                lv2Class: null,
+                audioInputs: channels(p.audio_ports.inputs),
+                audioOutputs: channels(p.audio_ports.outputs),
+                hasMidiIn: p.note_ports.inputs > 0,
+                params: p.params.filter((q) => !q.flags.includes("hidden") && !q.flags.includes("readonly")).map(controlOf),
+                format: "clap",
+                binaryPath,
+                ...(p.latency === undefined ? {} : { latency: { reportedFrames: p.latency } }),
+                ...(p.remote_controls === undefined ? {} : { remoteControls: p.remote_controls.filter((r) => !r.forPreset).map(pageOf) }),
+            });
+        }
+    }
+    return rows;
+}
+const spawnScan = (tool, args, timeoutMs) => {
+    const r = spawnSync(tool, [...args], { encoding: "utf8", timeout: timeoutMs, maxBuffer: MAX_SCAN_BYTES });
+    return { status: r.status, stdout: r.stdout ?? "", ...(r.error === undefined ? {} : { error: r.error }) };
+};
+/** The scanner binary: the declared setting when set, else the declared default (on `PATH`). */
+export function clapScanTool(env) {
+    const named = env[CLAP_SCAN_TOOL_ENV];
+    return named === undefined || named === "" ? CLAP_SCAN_TOOL_DEFAULT : named;
+}
+function holdsClap(dir) {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+        const p = join(dir, e.name);
+        const isDir = e.isDirectory() || (e.isSymbolicLink() && existsSync(p) && statSync(p).isDirectory());
+        if (isDir ? holdsClap(p) : e.name.endsWith(CLAP_SUFFIX))
+            return true;
+    }
+    return false;
+}
+function scan(target, options) {
+    const tool = clapScanTool(options.env ?? process.env);
+    const r = (options.run ?? spawnScan)(tool, ["--json", target], CLAP_SCAN_TIMEOUT_S * 1000);
+    if (r.error !== undefined) {
+        throw new ClapScanError(`cannot run the CLAP scanner "${tool}" (${r.error.message}): set ${CLAP_SCAN_TOOL_ENV} to the omx-clap-scan binary of omx-clap-host`);
+    }
+    if (r.status !== 0)
+        throw new ClapScanError(`${tool} exited ${String(r.status)} scanning ${target}`);
+    return parseClapScan(r.stdout);
+}
+export function clapLoader(options = {}) {
+    return {
+        format: "clap",
+        resolve(target) {
+            const named = CLAP_URI.exec(target);
+            if (named !== null)
+                return [{ format: "clap", uri: target }];
+            if (!existsSync(target))
+                return undefined;
+            const st = statSync(target);
+            if (st.isFile() ? !target.endsWith(CLAP_SUFFIX) : !st.isDirectory() || !holdsClap(target))
+                return undefined;
+            return clapScanDescriptors(scan(target, options)).map((row) => ({
+                format: "clap",
+                uri: row.uri,
+                bundle: dirname(row.binaryPath),
+                binary: basename(row.binaryPath),
+                binaryPath: row.binaryPath,
+            }));
+        },
+    };
+}
+//# sourceMappingURL=clap-loader.js.map