@openmixer/plugin-qualify 0.18.0 → 0.18.2

package/dist/qualify-sync.d.ts

@@ -1,7 +1,10 @@
 import { type HostProfile } from "./host-profiles.js";
 import { type PinEntry } from "./pins-file.js";
 import { type PinFilesRun } from "./hostd-pin-files.js";
+import { type ProbeRun } from "./probe-runner.js";
 import { type GridSpec } from "./measurement-grid.js";
+import { type AdapterPassOptions } from "./qualify-adapter-pass.js";
+import { type IsolatedRunner } from "./qualify-isolated.js";
 import { type MemoryBound } from "./memory-bound.js";
 import { type NotMeasured } from "./qualification-record.js";
 /** The settings file a system service reads, `key value` per line. */
@@ -32,6 +35,8 @@ export interface SyncSettings {
     readonly cellsPerPluginBudget: number;
     /** The memory bound of every run; `undefined` is `off`. */
     readonly memory?: MemoryBound;
+    /** The notes an instrument with no declared capacity holds in a memory-only run. */
+    readonly memoryNotes: number;
     readonly hostdPort: number;
     readonly hostdFeedbackPort: number;
     readonly settleS: number;
@@ -57,6 +62,14 @@ export interface SyncArgs {
     readonly noWait: boolean;
     /** `--refresh-pins`: refresh the pins' files from plugin-hostd and measure nothing (the package's upgrade runs it). */
     readonly refreshPins: boolean;
+    /** `--rejudge`: the verdicts, tiers and pins derived again from the records' figures, measuring nothing. */
+    readonly rejudge: boolean;
+    /** `--memory-only`: the footprint of each recorded plugin at the Pi's cells, merged into its record. */
+    readonly memoryOnly: boolean;
+    /** `--adapter-only`: the run of each LV2 plugin under the adapter at the Pi's cells, merged into its record. */
+    readonly adapterOnly: boolean;
+    /** `--isolated-only`: the missing isolated step of each record already judged, extending its run. */
+    readonly isolatedOnly: boolean;
     readonly help: boolean;
     /** The settings given as flags, by key. */
     readonly values: ReadonlyMap<string, string>;
@@ -89,15 +102,30 @@ export interface SyncItem {
     readonly files: readonly string[];
     /** The LV2 plugin's uri. */
     readonly uri?: string;
+    /** The LV2 plugin's binary as lilv loads it, an absolute path that may lie outside `root` (a complement's). */
+    readonly binary?: string;
 }
+/** One LV2 plugin as lilv resolves it over the whole search path: the bundle its version rule takes, and its binary. */
+export interface Lv2Resolved {
+    readonly uri: string;
+    readonly bundle: string;
+    readonly binary?: string | null;
+}
+/** The bundles lilv takes over `dirs`, or why it could not say. A stand-in in tests. */
+export type Lv2Resolve = (dirs: readonly string[]) => readonly Lv2Resolved[] | {
+    readonly problem: string;
+};
+/** lilv itself, one world over the whole search path (tools/lv2_resolve.py), as every host built on it resolves (#199). */
+export declare const LILV_RESOLVE: Lv2Resolve;
 /**
  * Every item on the search paths. A `.clap` is one item; an LV2 plugin is one item, found in the first bundle on the
  * LV2 directories that declares it, as plugin-hostd finds it. A directory that cannot be read is a problem named, and
  * the others are still walked.
  */
-export declare function discoverSyncItems(settings: Pick<SyncSettings, "lv2Dirs" | "clapDirs">): {
+export declare function discoverSyncItems(settings: Pick<SyncSettings, "lv2Dirs" | "clapDirs">, lv2Resolve?: Lv2Resolve): {
     items: SyncItem[];
     problems: string[];
+    notes: string[];
 };
 /** One file of a set: its SHA-256, as plugin-hostd's `pin.h` digests it, and the stat it was taken at. */
 export interface FileDigest {
@@ -130,6 +158,13 @@ export declare const SYNC_CODE: {
     /** The probe runner wrote no document to judge. */
     readonly notMeasured: "qualify.sync.not-measured";
 };
+/**
+ * Why a plugin is unmeasured because of the machine it ran on rather than what it is (#192): an EACCES, EPERM or
+ * ENOSPC the run hit, or a measurement that could not run or wrote no document. Such a plugin is measured again by
+ * the next run although its files are unchanged; a reason of the plugin's own (probe.limit.not-implemented, no such
+ * plugin, a crash) is not. `undefined` for every other outcome.
+ */
+export declare function machineReason(p: Pick<SyncPlugin, "outcome" | "code" | "detail">): string | undefined;
 /** What the quick qualification never measures, stated in every record it writes. */
 export declare const QUICK_NOT_MEASURED: readonly NotMeasured[];
 export interface SyncPlugin {
@@ -168,12 +203,21 @@ export declare function recordedAsIs(item: SyncItem, entry: SyncEntry | undefine
     same: boolean;
     files?: FileDigest[];
 };
+/**
+ * The entry of an LV2 plugin a host now loads from another bundle than it was qualified in, when its binary is the
+ * same bytes (#199): the entry with the new bundle and the new bundle's file digests, its verdicts and records kept.
+ * `undefined` when the item is not that case: not LV2, no entry, the same bundle, a binary that cannot be read, or one
+ * whose bytes differ from the recorded binary's (then it is measured again).
+ */
+export declare function sameBinaryElsewhere(item: SyncItem, entry: SyncEntry | undefined): SyncEntry | undefined;
 export interface SyncContext {
     readonly settings: SyncSettings;
     readonly env: Readonly<Record<string, string | undefined>>;
     readonly log: (line: string) => void;
     /** The run of `plugin-hostd --pin-files`, a stand-in in tests. */
     readonly pinFilesRun?: PinFilesRun;
+    /** The isolated step, a stand-in in tests. */
+    readonly isolatedRunner?: IsolatedRunner;
 }
 /**
  * Every pin of the state with the files plugin-hostd collects for its plugin now, measured again by nothing
@@ -189,6 +233,16 @@ export declare function refreshPins(ctx: SyncContext, state: SyncState): {
 };
 /** One item qualified, whatever happens to it: an error of the sync's own while measuring it is its outcome, not the run's end. */
 export declare function qualifyItem(ctx: SyncContext, item: SyncItem, files: readonly FileDigest[]): SyncEntry;
+/**
+ * The isolated steps the records of a state still owe, each extending its record's run. A plugin's pin follows its step, and
+ * a step that could not run stays owed: the next pass tries it again.
+ */
+export declare function isolatedPass(ctx: SyncContext, state: SyncState): {
+    readonly state: SyncState;
+    readonly isolated: number;
+    readonly refused: number;
+    readonly notRun: number;
+};
 /** The pin file's text: every whole pin of the state, the worse verdict kept for a uri pinned twice. */
 export declare function syncPinsText(state: SyncState): string;
 /** The pin lines of `after` that `before` does not hold as they are. */
@@ -241,6 +295,32 @@ export interface SyncSummary {
     readonly sent?: number;
     /** The pins whose files were refreshed from plugin-hostd without a measurement (plugin-qualify#239). */
     readonly refreshed?: number;
+    /** `--rejudge`: the records whose verdicts changed, the ones that stood, and the ones that owe a measurement. */
+    readonly rejudge?: {
+        readonly changed: number;
+        readonly unchanged: number;
+        readonly owing: number;
+    };
+    /** `--memory-only`: the plugins measured, those whose footprints were already merged, and those no run could read. */
+    readonly memoryOnly?: {
+        readonly measured: number;
+        readonly already: number;
+        readonly failed: number;
+    };
+    /** Every plugin the run measured was unmeasured for this one reason of the machine ({@link machineReason}): the run failed. */
+    readonly machineFailure?: string;
+    /** `--isolated-only`: how the steps ended. */
+    readonly isolatedOnly?: {
+        readonly isolated: number;
+        readonly refused: number;
+        readonly notRun: number;
+    };
+    /** `--adapter-only`: the plugins run, those done already at these host versions, and those whose host could not be run. */
+    readonly adapterOnly?: {
+        readonly measured: number;
+        readonly already: number;
+        readonly failed: number;
+    };
 }
 /**
  * Why a reader that is not the sync's user (the console, #221) cannot read the descriptors: the directory or one of its
@@ -263,8 +343,24 @@ export interface SyncRunOptions {
     readonly force?: boolean;
     /** `--refresh-pins`: only refresh the pins' files from plugin-hostd and send the changed ones; measure nothing. */
     readonly refreshOnly?: boolean;
+    /** `--rejudge`: derive the verdicts again from the records' figures; measure nothing. */
+    readonly rejudge?: boolean;
+    /** `--memory-only`: take only the footprints; `force` takes those already merged again. */
+    readonly memoryOnly?: boolean;
+    /** The isolated step, a stand-in in tests. */
+    readonly isolatedRunner?: IsolatedRunner;
+    /** `--isolated-only`: take only the isolated steps records still owe. */
+    readonly isolatedOnly?: boolean;
+    /** `--adapter-only`: take only the adapter runs; `force` takes those already done again. */
+    readonly adapterOnly?: boolean;
+    /** Stand-ins for the pass's hosts, in tests. */
+    readonly adapterPass?: AdapterPassOptions;
     /** The run of `plugin-hostd --pin-files`, a stand-in in tests. */
     readonly pinFilesRun?: PinFilesRun;
+    /** The run of the probe runner in a memory-only pass, a stand-in in tests. */
+    readonly probeRun?: ProbeRun;
+    /** How LV2 plugins are resolved to the bundle a host loads: lilv itself unless a test stands in (#199). */
+    readonly lv2Resolve?: Lv2Resolve;
     /** False under `--no-wait`: a run in progress is not waited for; the holder runs once more at its end instead. */
     readonly wait?: boolean;
     readonly env?: Readonly<Record<string, string | undefined>>;