@vestra-player/sdk 1.5.24 → 1.5.26

package/dist/capabilities.js

@@ -1,8 +1,12 @@
+import { capabilityInfo } from "./capability-rules.js";
 /**
  * Every manifest capability the player knows (`vestra/1`), in the player's
  * order, with the members it opens, the capabilities they also need and the
- * store's wording. The player's tests check that the names agree with the
- * player's `host/src/plugins.rs` and the labels with its plugin store.
+ * store's wording. Built from the player's own capability table (its
+ * `src/host/capabilities.json`, copied into the SDK) and the requests each
+ * member sends, the same rule `vestra-plugin check` and the SDK's
+ * TypeScript plugin apply; the player's tests check that the copy is
+ * current.
  *
  * A member not listed under any capability needs none (`plugin.tools`,
  * `plugin.storage`, `plugin.system`, `plugin.app`, `plugin.ui`,
@@ -21,237 +25,19 @@
  *
  * @since 1.5.14
  */
-export const CAPABILITY_INFO = Object.freeze({
-    "producer.av": {
-        apis: ["Player.openStream"],
-        requires: ["playback.control"],
-        label: "Provide audio and video it generates itself",
-        risky: false,
-    },
-    "playback.read": {
-        apis: [
-            "Player.state",
-            "Player.refresh",
-            "Player.stats",
-            "Player.chapters",
-            "Player.audioDevices",
-            "Timeline.marks",
-        ],
-        requires: [],
-        label: "Read what is playing and the position",
-        risky: false,
-    },
-    "playback.control": {
-        apis: [
-            "Player.open",
-            "Player.setPaused",
-            "Player.seek",
-            "Player.setRate",
-            "Player.restart",
-            "Player.close",
-            "Player.scrub",
-            "Player.setOutput",
-            "Player.provideSequence",
-            "Player.next",
-            "Player.previous",
-            "Player.addAudioTrack",
-            "Player.selectAudioTrack",
-            "Player.step",
-            "Player.setStepSeek",
-            "Player.setLoop",
-            "Player.setAudioDevice",
-            "Power.preventSleep",
-        ],
-        requires: [],
-        label: "Open media, control playback, keep the computer awake",
-        risky: false,
-    },
-    "source.resolve": {
-        apis: ["Resolvers.add"],
-        requires: [],
-        label: "Resolve online video addresses",
-        risky: false,
-    },
-    events: {
-        apis: [
-            "Player.onChange",
-            "Subtitles.onChange",
-            "Timeline.onChange",
-            "MainWindow.onChange",
-            "Appearance.onChange",
-            "PanelSlot.onChange",
-            "Panel.onChange",
-            "BackdropSlot.onChange",
-            "Resolvers.onFileTypesChange",
-        ],
-        requires: [],
-        label: "Receive playback changes as they happen",
-        risky: false,
-    },
-    commands: {
-        apis: ["Commands.add", "Host.run"],
-        requires: [],
-        label: "Add menu commands and shortcuts",
-        risky: false,
-    },
-    "ui.window": {
-        apis: ["Windows.create"],
-        requires: [],
-        label: "Open tool windows",
-        risky: false,
-    },
-    "ui.mount": {
-        apis: [
-            "Panels.mount",
-            "Panels.bottom",
-            "Panels.sidebar",
-            "Panels.backdrop",
-            "PanelSlot.onChange",
-            "Panel.onChange",
-            "BackdropSlot.onChange",
-        ],
-        requires: [],
-        label: "Show panels in the bottom bar, the sidebar or behind the video",
-        risky: false,
-    },
-    "ui.dialog": {
-        apis: [
-            "Dialogs.confirm",
-            "Dialogs.openFile",
-            "Dialogs.openFiles",
-            "Dialogs.openDirectory",
-            "Dialogs.saveFile",
-        ],
-        requires: [],
-        label: "Show file pickers and confirmations",
-        risky: false,
-    },
-    "plugins.manage": {
-        apis: [
-            "Packages.validate",
-            "Packages.validateArchive",
-            "Packages.setEnabled",
-            "Packages.reload",
-            "Packages.uninstall",
-        ],
-        requires: [],
-        label: "Install, uninstall and disable other plugins",
-        risky: true,
-    },
-    "processing.video": {
-        apis: ["Plugin.video.filter", "Plugin.video.view", "Plugin.video.render"],
-        requires: ["playback.read"],
-        label: "Process the picture (filters, shaders)",
-        risky: false,
-    },
-    "processing.audio": {
-        apis: ["Plugin.audio.filter"],
-        requires: ["playback.read", "events"],
-        label: "Process the sound",
-        risky: false,
-    },
-    "subtitles.read": {
-        apis: ["Subtitles.state", "Subtitles.onChange", "Subtitles.refresh"],
-        requires: [],
-        label: "Read subtitles",
-        risky: false,
-    },
-    "subtitles.control": {
-        apis: [
-            "Subtitles.select",
-            "Subtitles.load",
-            "Subtitles.remove",
-            "Subtitles.setStyle",
-        ],
-        requires: [],
-        label: "Load and change subtitles",
-        risky: false,
-    },
-    "media.read": {
-        apis: ["MediaCapture.capture", "Snapshot.export"],
-        requires: ["media.control"],
-        label: "Take snapshots and export clips",
-        risky: false,
-    },
-    "media.control": {
-        apis: ["MediaCapture.capture", "Snapshot.export"],
-        requires: ["media.read"],
-        label: "Take snapshots and export clips",
-        risky: false,
-    },
-    "ui.osd": {
-        apis: ["Osd.show", "Osd.panel"],
-        requires: [],
-        label: "Show messages on the video",
-        risky: false,
-    },
-    clipboard: {
-        apis: [
-            "Clipboard.readText",
-            "Clipboard.writeText",
-            "Clipboard.writeImage",
-        ],
-        requires: [],
-        label: "Read and write the clipboard",
-        risky: true,
-    },
-    "window.control": {
-        apis: [
-            "MainWindow.setVideoArea",
-            "MainWindow.setAlwaysOnTop",
-            "MainWindow.setCursorAutoHide",
-            "MainWindow.setPictureInPicture",
-        ],
-        requires: [],
-        label: "Adjust the main window (size, on top, picture-in-picture)",
-        risky: false,
-    },
-    "bindings.manage": {
-        apis: [
-            "Bindings.list",
-            "Bindings.set",
-            "Bindings.reset",
-            "Bindings.onChange",
-        ],
-        requires: [],
-        label: "Change all shortcuts",
-        risky: true,
-    },
-    "timeline.marks": {
-        apis: ["Timeline.layer"],
-        requires: [],
-        label: "Show marks on the progress bar",
-        risky: false,
-    },
-    "ui.drop": {
-        apis: ["Drops.provide", "Panel.onDrop"],
-        requires: [],
-        label: "Receive files dropped on the player",
-        risky: false,
-    },
-    "ui.settings": {
-        apis: ["Settings.page", "Settings.show"],
-        requires: [],
-        label: "Add pages to the Options window",
-        risky: false,
-    },
-    "ui.theme": {
-        apis: ["Appearance.set", "Appearance.setLanguage"],
-        requires: [],
-        label: "Change the player's palette",
-        risky: false,
-    },
-    secrets: {
-        apis: ["Secrets.get", "Secrets.set", "Secrets.delete"],
-        requires: [],
-        label: "Store sign-in details in the system keychain",
-        risky: true,
-    },
-});
+export const CAPABILITY_INFO = Object.freeze(Object.fromEntries(Object.entries(capabilityInfo()).map(([name, info]) => [
+    name,
+    Object.freeze({
+        apis: Object.freeze(info.apis),
+        requires: Object.freeze(info.requires),
+        label: info.label,
+        risky: info.risky,
+    }),
+])));
 /**
  * Manifest capabilities the player knows (`vestra/1`): the keys of
  * {@link CAPABILITY_INFO}, in the player's order. The same list as the
- * player's `host/src/plugins.rs`; the player's tests check that they agree.
+ * player's `host/capabilities.json`; the player's tests check that they agree.
  */
 export const CAPABILITIES = Object.freeze(Object.keys(CAPABILITY_INFO));
 /** The plugin API version this SDK implements (`manifest.apiVersion`). */

package/dist/capability-check.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The capability checker: every use of a plugin API member whose capability
+ * the plugin's `manifest.json` does not declare. `vestra-plugin check` (and
+ * so `build` and `pack`) and the TypeScript language-service plugin
+ * (`@vestra-player/sdk/ts-plugin`) both run it; the rule is
+ * `capability-rules.ts` (the player's table and the SDK's requests).
+ *
+ * It is type-aware: a use is a property access, an element access with a
+ * literal name or a destructured property whose symbol is the SDK's
+ * declaration of a member in the table, however the object was reached
+ * (`plugin.player.seek`, `const { player } = plugin; player.seek`, a
+ * parameter typed `Player`, a `Panel` from `panels.mount`). Not detected:
+ * access with a computed name (`player[name]`), values typed `any` or
+ * `unknown`, plain JavaScript without types, members inherited from `View`
+ * (their object comes from a call that is checked) and options that need
+ * more (a `processed` capture, a file resolver).
+ *
+ * The TypeScript module is passed in, never imported: the CLI uses the
+ * SDK's own compiler, the editor its TypeScript server's.
+ *
+ * @internal
+ */
+import type TS from "typescript";
+import type { CapabilityRules } from "./capability-rules.ts";
+/** @internal The module plugins import the API types from. */
+export declare const SDK_MODULE = "@vestra-player/sdk";
+/** @internal The diagnostic code the editor shows (and its quick fix keys on). */
+export declare const CAPABILITY_DIAGNOSTIC = 95301;
+/** @internal One use of a member whose capability is not declared. */
+export interface CapabilityFinding {
+    /** The source file, as the program names it. */
+    readonly file: string;
+    /** 1-based line and column of the member's name. */
+    readonly line: number;
+    readonly column: number;
+    /** Offset and length of the member's name in the file. */
+    readonly start: number;
+    readonly length: number;
+    /** The member, `Interface.member` (`Player.seek`). */
+    readonly api: string;
+    /** The capability to declare. */
+    readonly capability: string;
+    /** The request that needs it. */
+    readonly method: string;
+    /** The declared-or-needed capability whose `requires` names it. */
+    readonly requiredBy?: string;
+    /** One line for people. */
+    readonly message: string;
+}
+/** @internal */
+export interface CheckOptions {
+    /** The files to check (others in the program are only read for types). */
+    readonly files: readonly string[];
+    /** The manifest's `capabilities`. */
+    readonly capabilities: readonly string[];
+    /** Default: the SDK's rules. */
+    readonly rules?: CapabilityRules;
+}
+/**
+ * Every use, in `options.files`, of a member whose capability the manifest
+ * does not declare, in file and position order.
+ *
+ * @internal
+ */
+export declare function findUndeclaredCapabilities(ts: typeof TS, program: TS.Program, options: CheckOptions): CapabilityFinding[];
+/**
+ * Whether a file belongs to the plugin's production code, given the
+ * directory of its `manifest.json`: not in `tests/`, `node_modules/`,
+ * `dist/`, `vendor/` or a dot directory (what `vestra-plugin build` leaves
+ * out), and not a declaration file.
+ *
+ * @internal
+ */
+export declare function isPluginSource(directory: string, file: string): boolean;
+/**
+ * The edit that adds a capability to a manifest's `capabilities` array, in
+ * the array's own layout; `undefined` when the text has no such array.
+ *
+ * @internal
+ */
+export declare function addCapabilityEdit(ts: typeof TS, text: string, capability: string): {
+    start: number;
+    length: number;
+    newText: string;
+} | undefined;

package/dist/capability-check.js

@@ -0,0 +1,203 @@
+import { memberNeeds, RULES } from "./capability-rules.js";
+/** @internal The module plugins import the API types from. */
+export const SDK_MODULE = "@vestra-player/sdk";
+/** @internal The diagnostic code the editor shows (and its quick fix keys on). */
+export const CAPABILITY_DIAGNOSTIC = 95_301;
+const memberCache = new WeakMap();
+/**
+ * The module `@vestra-player/sdk` as the program resolved it: from the
+ * first import or export of it in the program's own (non-declaration) files.
+ */
+function sdkModule(ts, program, checker) {
+    for (const file of program.getSourceFiles()) {
+        if (file.isDeclarationFile || program.isSourceFileFromExternalLibrary(file))
+            continue;
+        for (const statement of file.statements) {
+            const specifier = ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement)
+                ? statement.moduleSpecifier
+                : undefined;
+            if (specifier &&
+                ts.isStringLiteral(specifier) &&
+                specifier.text === SDK_MODULE) {
+                const module = checker.getSymbolAtLocation(specifier);
+                if (module)
+                    return module;
+            }
+        }
+    }
+    return undefined;
+}
+/** The SDK's declarations of the members in the table. */
+function sdkMembers(ts, program, rules) {
+    const cached = memberCache.get(program);
+    if (cached && rules === RULES)
+        return cached;
+    const members = new Map();
+    const checker = program.getTypeChecker();
+    const module = sdkModule(ts, program, checker);
+    if (module) {
+        const exports = new Map();
+        for (const symbol of checker.getExportsOfModule(module))
+            exports.set(symbol.name, symbol.flags & ts.SymbolFlags.Alias
+                ? checker.getAliasedSymbol(symbol)
+                : symbol);
+        for (const api of Object.keys(rules.apis)) {
+            const [head, ...path] = api.split(".");
+            const root = exports.get(head);
+            if (!root || !path.length)
+                continue;
+            let type = checker.getDeclaredTypeOfSymbol(root);
+            let property;
+            for (const name of path) {
+                property = type?.getProperty(name);
+                type = property && checker.getTypeOfSymbol(property);
+            }
+            for (const declaration of property?.declarations ?? [])
+                if (!members.has(declaration))
+                    members.set(declaration, api);
+        }
+    }
+    if (rules === RULES)
+        memberCache.set(program, members);
+    return members;
+}
+/**
+ * Every use, in `options.files`, of a member whose capability the manifest
+ * does not declare, in file and position order.
+ *
+ * @internal
+ */
+export function findUndeclaredCapabilities(ts, program, options) {
+    const rules = options.rules ?? RULES;
+    const files = options.files
+        .map((file) => program.getSourceFile(file))
+        .filter((file) => !!file);
+    if (!files.length)
+        return [];
+    const members = sdkMembers(ts, program, rules);
+    if (!members.size)
+        return [];
+    const checker = program.getTypeChecker();
+    const findings = [];
+    const memberOf = (symbol) => {
+        for (const declaration of symbol?.declarations ?? []) {
+            const api = members.get(declaration);
+            if (api)
+                return api;
+        }
+        return undefined;
+    };
+    for (const file of files) {
+        const report = (name, symbol) => {
+            const api = memberOf(symbol);
+            if (!api)
+                return;
+            const start = name.getStart(file);
+            const { line, character } = file.getLineAndCharacterOfPosition(start);
+            for (const need of memberNeeds(api, options.capabilities, rules) ?? []) {
+                if (options.capabilities.includes(need.capability))
+                    continue;
+                findings.push({
+                    file: file.fileName,
+                    line: line + 1,
+                    column: character + 1,
+                    start,
+                    length: name.getEnd() - start,
+                    api,
+                    capability: need.capability,
+                    method: need.method,
+                    ...(need.requiredBy ? { requiredBy: need.requiredBy } : {}),
+                    message: need.requiredBy
+                        ? `${api} needs the capability "${need.capability}" (required by "${need.requiredBy}"), which manifest.json does not declare`
+                        : `${api} needs the capability "${need.capability}", which manifest.json does not declare`,
+                });
+            }
+        };
+        const visit = (node) => {
+            if (ts.isPropertyAccessExpression(node))
+                report(node.name, checker.getSymbolAtLocation(node.name));
+            else if (ts.isElementAccessExpression(node) &&
+                ts.isStringLiteralLike(node.argumentExpression))
+                report(node.argumentExpression, checker.getSymbolAtLocation(node.argumentExpression));
+            else if (ts.isBindingElement(node) &&
+                ts.isObjectBindingPattern(node.parent)) {
+                const name = node.propertyName ?? node.name;
+                const text = ts.isIdentifier(name) || ts.isStringLiteralLike(name)
+                    ? name.text
+                    : undefined;
+                if (text !== undefined)
+                    report(name, checker.getTypeAtLocation(node.parent).getProperty(text));
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(file);
+    }
+    return findings;
+}
+/**
+ * Whether a file belongs to the plugin's production code, given the
+ * directory of its `manifest.json`: not in `tests/`, `node_modules/`,
+ * `dist/`, `vendor/` or a dot directory (what `vestra-plugin build` leaves
+ * out), and not a declaration file.
+ *
+ * @internal
+ */
+export function isPluginSource(directory, file) {
+    const normal = (path) => path.replaceAll("\\", "/").replace(/\/$/, "");
+    const base = normal(directory);
+    const path = normal(file);
+    const caseless = /^[a-z]:\//i.test(path);
+    const same = (a, b) => caseless ? a.toLowerCase() === b.toLowerCase() : a === b;
+    if (!same(path.slice(0, base.length + 1), `${base}/`))
+        return false;
+    if (/\.d\.[mc]?ts$/.test(path) || !/\.[mc]?tsx?$/.test(path))
+        return false;
+    const parts = path
+        .slice(base.length + 1)
+        .split("/")
+        .slice(0, -1);
+    return !parts.some((part) => part.startsWith(".") ||
+        ["tests", "node_modules", "dist", "vendor"].includes(part));
+}
+/**
+ * The edit that adds a capability to a manifest's `capabilities` array, in
+ * the array's own layout; `undefined` when the text has no such array.
+ *
+ * @internal
+ */
+export function addCapabilityEdit(ts, text, capability) {
+    const json = ts.parseJsonText("manifest.json", text);
+    const root = json.statements[0]?.expression;
+    if (!root || !ts.isObjectLiteralExpression(root))
+        return undefined;
+    const property = root.properties.find((each) => ts.isPropertyAssignment(each) &&
+        ts.isStringLiteral(each.name) &&
+        each.name.text === "capabilities");
+    const array = property?.initializer;
+    if (!array || !ts.isArrayLiteralExpression(array))
+        return undefined;
+    const quoted = JSON.stringify(capability);
+    const last = array.elements.at(-1);
+    if (!last) {
+        const start = array.getStart(json);
+        return {
+            start,
+            length: array.getEnd() - start,
+            newText: `[${quoted}]`,
+        };
+    }
+    const first = array.elements[0];
+    const lineStart = text.lastIndexOf("\n", first.getStart(json)) + 1;
+    const multiline = text
+        .slice(array.getStart(json), first.getStart(json))
+        .includes("\n");
+    const indent = text.slice(lineStart, first.getStart(json));
+    return {
+        start: last.getEnd(),
+        length: 0,
+        // The manifest's own line endings (CRLF on many Windows checkouts).
+        newText: multiline
+            ? `,${text.includes("\r\n") ? "\r\n" : "\n"}${indent}${quoted}`
+            : `, ${quoted}`,
+    };
+}

package/dist/capability-rules.d.ts

@@ -0,0 +1,102 @@
+import type { ApiRequest } from "./api-requests.ts";
+/**
+ * What a request needs, as the player's `capabilities.json` writes it:
+ * `null` (nothing), a capability name, a choice by a string parameter, or a
+ * choice by whether the plugin declared a capability.
+ *
+ * @internal
+ */
+export type Needs = null | string | {
+    readonly param: string;
+    readonly cases: Readonly<Record<string, string | null>>;
+    readonly otherwise: string | null;
+} | {
+    readonly ifDeclared: string;
+    readonly then: string;
+    readonly otherwise: string;
+};
+/** @internal One RPC method of the player's table (`prefix.*` covers a prefix). */
+export interface HostMethod {
+    readonly name: string;
+    readonly needs: Needs;
+}
+/** @internal One manifest capability of the player's table. */
+export interface HostCapability {
+    readonly name: string;
+    readonly label: string;
+    readonly risky: boolean;
+    readonly requires: readonly string[];
+    readonly residency: string;
+    readonly methods: readonly HostMethod[];
+}
+/** @internal The player's `src/host/capabilities.json`. */
+export interface HostCapabilities {
+    readonly about: string;
+    readonly apiVersion: string;
+    readonly capabilities: readonly HostCapability[];
+    readonly uncapable: readonly HostMethod[];
+}
+/** @internal Both tables; tests pass their own. */
+export interface CapabilityRules {
+    readonly host: HostCapabilities;
+    readonly apis: Readonly<Record<string, readonly ApiRequest[]>>;
+}
+/** @internal The SDK's rules: the synced player table and `API_REQUESTS`. */
+export declare const RULES: CapabilityRules;
+/**
+ * The player's entry for a method, as the player routes it: the exact name
+ * first, then the first `prefix.*` entry whose prefix it starts with.
+ * `undefined`: the player does not know the method.
+ *
+ * @internal
+ */
+export declare function hostMethod(method: string, host?: HostCapabilities): HostMethod | undefined;
+/**
+ * The capability one request needs, as the player decides it
+ * (`capabilities::Route::needs`): `null` for none, `undefined` for a method
+ * the player does not know.
+ *
+ * @param method - The wire method.
+ * @param params - Its string parameters that a `Needs::Param` rule reads.
+ * @param declared - Whether the plugin declared a capability.
+ *
+ * @internal
+ */
+export declare function requestNeeds(method: string, params: Readonly<Record<string, string>> | undefined, declared: (capability: string) => boolean, host?: HostCapabilities): string | null | undefined;
+/**
+ * One capability a member needs: the request that needs it, and the
+ * capability whose `requires` brought it in (absent when the request needs
+ * it directly).
+ *
+ * @internal
+ */
+export interface MemberNeed {
+    readonly capability: string;
+    readonly method: string;
+    readonly requiredBy?: string;
+}
+/**
+ * Every capability a member of the plugin API needs with the given manifest:
+ * those its requests need and, through `requires`, those they need in turn.
+ * `undefined`: the member is not in the table (it needs none).
+ *
+ * @param api - The member as `Interface.member` (`Player.seek`).
+ * @param capabilities - The manifest's capabilities.
+ *
+ * @internal
+ */
+export declare function memberNeeds(api: string, capabilities: readonly string[], rules?: CapabilityRules): MemberNeed[] | undefined;
+/**
+ * `CAPABILITY_INFO` from the tables: the label, highlight and requirements
+ * from the player's table; the members from `API_REQUESTS` (every member a
+ * request of which needs the capability, in the table's order; requests
+ * marked `also` are left out, as they are documented at the member).
+ *
+ * @internal
+ */
+export declare function capabilityInfo(rules?: CapabilityRules): Record<string, {
+    apis: string[];
+    requires: string[];
+    label: string;
+    risky: boolean;
+}>;