@openmixer/plugin-qualify 0.0.0-stage → 0.3.0

package/src/qualify-options.ts

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * The `plugin-qualify` CLI's OPTIONS, declared once. The parser, `--help` and the tests all read this table; every default is a declaration
+ * from `declarations.ts`, never a literal here.
+ */
+import { QUALIFY_QUANTA, QUALIFY_RATES } from "./qualify-declarations.js";
+import { HOST_PROFILES, OPENMIXER_CONSOLE_PROFILE } from "./host-profiles.js";
+
+/** How the result is printed. `text` = plugin, verdict, the reason that decided it. */
+export const OUTPUT_FORMATS = ["json", "text"] as const;
+export type OutputFormat = (typeof OUTPUT_FORMATS)[number];
+
+/** The exit codes, as the spec states them. */
+export const EXIT_CODE = {
+  /** Every named plugin rated `suitable`. */
+  allQualified: 0,
+  /** At least one plugin measured and rated below `suitable`. */
+  someNotQualified: 1,
+  /** A plugin could not be measured, or the arguments/targets could not be resolved. */
+  couldNotMeasure: 2,
+} as const;
+
+export interface QualifyOption {
+  /** `--rates`; a positional is not an option. */
+  readonly flag: string;
+  /** The value's name when the option takes one. */
+  readonly value?: string;
+  readonly describe: string;
+  /** The declared default, printed by `--help` — absent for a switch. */
+  readonly default?: string;
+}
+
+export const QUALIFY_OPTIONS: readonly QualifyOption[] = [
+  { flag: "--all", describe: "every plugin lilv finds (LV2_PATH honoured)" },
+  { flag: "--rates", value: "list", describe: "sample rates to measure at, comma-separated", default: QUALIFY_RATES.join(",") },
+  { flag: "--quanta", value: "list", describe: "quanta (frames) to rate cost at, comma-separated", default: QUALIFY_QUANTA.join(",") },
+  { flag: "--out", value: "dir", describe: "write one interchange JSON document per run into this directory" },
+  { flag: "--format", value: OUTPUT_FORMATS.join("|"), describe: "json = the verdicts as JSON; text = plugin, verdict, deciding reason", default: "text" },
+  { flag: "--isolate", describe: "a fresh worker per plugin, so a crash or hang takes only that plugin" },
+  { flag: "--no-host-sweep", describe: "offline lilv measurement only; no mod-host hosting sweep" },
+  {
+    flag: "--host-profile",
+    value: "file|id",
+    describe: `judge against this host (${HOST_PROFILES.map((p) => p.id).join(", ")}, or a profile JSON file); repeat or comma-separate for one verdict per profile`,
+    default: OPENMIXER_CONSOLE_PROFILE.id,
+  },
+  { flag: "--help", describe: "this text" },
+];

package/src/rating.ts

@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+//
+// The rating vocabulary every verdict speaks: four ratings, their severity order, the
+// worst-wins fold, and whether a reason is physics or taste.
+
+import type { VerdictRating } from "./measurement/vocabulary.js";
+
+/**
+ * How well a plugin fits a destination role. The four words are the interchange's
+ * (`VERDICT_RATINGS`, `measurement/vocabulary.ts`), so a written verdict speaks this vocabulary.
+ *
+ * - `suitable` — every dimension resolved and inside its budget.
+ * - `conditional` — nothing objectively disqualifies it, but something needs the operator's
+ *   attention: a taste warning, a topology difference, a look-ahead control that can be
+ *   turned up past the budget, a cost that eats most of the allowance.
+ * - `unknown` — an OBJECTIVE dimension could not be decided because the measurement is
+ *   missing or does not resolve at this rate. Not a pass and not a failure: an admission.
+ * - `unsuitable` — an objective dimension failed on measured evidence.
+ */
+export type SuitabilityRating = VerdictRating;
+
+/**
+ * Severity order for folding several reasons into one verdict:
+ * `unsuitable` > `unknown` > `conditional` > `suitable`.
+ *
+ * `unknown` outranks `conditional` on purpose. A conditional plugin is one the console has
+ * fully measured and has an opinion about; an unknown one is a plugin the console cannot
+ * vouch for at all. Reporting "there is a caution" while an objective dimension is
+ * un-measured would present the smaller finding as the whole story.
+ */
+export const RATING_SEVERITY: Readonly<Record<SuitabilityRating, number>> = {
+  suitable: 0,
+  conditional: 1,
+  unknown: 2,
+  unsuitable: 3,
+};
+
+/** The worst (most severe) of some ratings; `suitable` for an empty list. */
+export function worstRating(ratings: readonly SuitabilityRating[]): SuitabilityRating {
+  let worst: SuitabilityRating = "suitable";
+  for (const rating of ratings) {
+    if (RATING_SEVERITY[rating] > RATING_SEVERITY[worst]) worst = rating;
+  }
+  return worst;
+}
+
+/**
+ * Physics or taste. The distinction drives what a reason is ALLOWED to do
+ * (`contributedRating` in the catalog, `contributedHostingRating` here) and, downstream, whether an operator override is a formality
+ * or a decision — conflating them is how a tool becomes either nagging or dangerous.
+ */
+export type SuitabilityKind = "objective" | "advisory";

package/src/tool-paths.ts

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * Where the package's own tools live, resolved from this module so it follows the package
+ * wherever it is installed (a checkout, an RPM's bundled node_modules, a pnpm store). The
+ * tools are shipped RUNTIME artefacts, not dev scripts.
+ */
+import { fileURLToPath } from "node:url";
+
+/**
+ * `tools/` — `scan.py`, `benchmark.py`, `lv2-measure.mjs`, `hosting-sweep.mjs`. Resolved when a
+ * console asks, never at import: a consumer that only reads this package's declarations from a
+ * browser-like module graph (web-ui's conformance suites, `http:` module URLs) must load it.
+ */
+export function toolsDir(): string {
+  return fileURLToPath(new URL("../tools/", import.meta.url));
+}
+
+/** The measurement runner a console spawns for Setup > Plugin analysis. */
+export function lv2MeasureToolPath(): string {
+  return fileURLToPath(new URL("../tools/lv2-measure.mjs", import.meta.url));
+}
+
+/** The package's own build of the CLAP prober (`make -C native`). */
+export function clapQualifyToolPath(): string {
+  return fileURLToPath(new URL("../native/build/clap-qualify", import.meta.url));
+}
+
+/** The package's own build of the interposer the CLAP prober runs under. */
+export function rtInterposePath(): string {
+  return fileURLToPath(new URL("../native/build/rt_interpose.so", import.meta.url));
+}

package/tools/_declarations.py

@@ -0,0 +1,21 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+# Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+#
+# GENERATED by tools/gen-python-declarations.mjs — do not hand-edit.
+#
+# Source: src/qualify-declarations.ts. The Python tools cannot import a TS module, so this file
+# stands in for that import: regenerated and checked byte-identical instead of a second,
+# hand-typed copy of the figures (2026-09-17 declare-derive audit, F8).
+#
+# Regenerate: node tools/gen-python-declarations.mjs --write
+# Verify:     node tools/gen-python-declarations.mjs --check
+
+COST_REFERENCE_RATE = 96000
+QUANTUM_FRAMES = 1024
+MEASURE_BASE_RATE = 48000
+OPERATIONAL_RATE_FLOOR = 48000
+QUALIFY_RATES = (44100, 48000, 96000, 192000)
+QUALIFY_QUANTA = (128, 256, 512, 1024)
+PLUGIN_TIMEOUT_S = 15
+BOOT_TIMEOUT_S = 120
+COST_TIMEOUT_S = 60