@vestra-player/sdk 1.5.25 → 1.5.26

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;
+}>;

package/dist/capability-rules.js

@@ -0,0 +1,132 @@
+/**
+ * The capability rule, as data: which manifest capability a request needs
+ * (the player's table, `HOST_CAPABILITIES`, synced from its
+ * `src/host/capabilities.json`) and which requests each public member of the
+ * plugin API sends (`API_REQUESTS`). `CAPABILITY_INFO`, `vestra-plugin check`
+ * and the TypeScript language-service plugin are all built from these two
+ * tables, so they and the player cannot disagree.
+ *
+ * @internal
+ */
+import { API_REQUESTS } from "./api-requests.js";
+import { HOST_CAPABILITIES } from "./host-capabilities.js";
+/** @internal The SDK's rules: the synced player table and `API_REQUESTS`. */
+export const RULES = {
+    host: HOST_CAPABILITIES,
+    apis: API_REQUESTS,
+};
+/**
+ * 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 function hostMethod(method, host = RULES.host) {
+    const all = [
+        ...host.capabilities.flatMap((capability) => capability.methods),
+        ...host.uncapable,
+    ];
+    return (all.find((entry) => entry.name === method) ??
+        all.find((entry) => entry.name.endsWith(".*") && method.startsWith(entry.name.slice(0, -1))));
+}
+/**
+ * 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 function requestNeeds(method, params, declared, host = RULES.host) {
+    const entry = hostMethod(method, host);
+    if (!entry)
+        return undefined;
+    const needs = entry.needs;
+    if (needs === null || typeof needs === "string")
+        return needs;
+    if ("param" in needs) {
+        const value = params?.[needs.param];
+        return value !== undefined && Object.hasOwn(needs.cases, value)
+            ? needs.cases[value]
+            : needs.otherwise;
+    }
+    return declared(needs.ifDeclared) ? needs.then : needs.otherwise;
+}
+/**
+ * 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 function memberNeeds(api, capabilities, rules = RULES) {
+    const requests = rules.apis[api];
+    if (!requests)
+        return undefined;
+    // An `ifDeclared` rule is decided last, as if the plugin had declared what
+    // the member's other requests need: `Player.seek` needs `playback.control`
+    // for `source.submit`, and with it `source.operation` needs nothing more.
+    const declared = (name) => capabilities.includes(name) ||
+        needs.some((need) => need.capability === name);
+    const conditional = (request) => {
+        const rule = hostMethod(request.method, rules.host)?.needs;
+        return typeof rule === "object" && rule !== null && "ifDeclared" in rule;
+    };
+    const needs = [];
+    const add = (need) => {
+        if (needs.some((each) => each.capability === need.capability))
+            return;
+        needs.push(need);
+        const entry = rules.host.capabilities.find((capability) => capability.name === need.capability);
+        for (const required of entry?.requires ?? [])
+            add({
+                capability: required,
+                method: need.method,
+                requiredBy: need.capability,
+            });
+    };
+    for (const request of [
+        ...requests.filter((request) => !conditional(request)),
+        ...requests.filter(conditional),
+    ]) {
+        const capability = requestNeeds(request.method, request.params, declared, rules.host);
+        if (capability)
+            add({ capability, method: request.method });
+    }
+    return needs;
+}
+/**
+ * `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 function capabilityInfo(rules = RULES) {
+    const info = {};
+    for (const capability of rules.host.capabilities)
+        info[capability.name] = {
+            apis: [],
+            requires: [...capability.requires],
+            label: capability.label,
+            risky: capability.risky,
+        };
+    for (const [api, requests] of Object.entries(rules.apis))
+        for (const request of requests) {
+            if (request.also)
+                continue;
+            const capability = requestNeeds(request.method, request.params, () => true, rules.host);
+            const entry = capability ? info[capability] : undefined;
+            if (entry && !entry.apis.includes(api))
+                entry.apis.push(api);
+        }
+    return info;
+}

package/dist/host-capabilities.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The player's capability table, copied from its `src/host/capabilities.json`
+ * by `npm run capabilities:sync -- <player repository>`. Do not edit: change
+ * the player's capability modules, regenerate its JSON and sync again.
+ *
+ * @internal
+ */
+import type { HostCapabilities } from "./capability-rules.ts";
+/** @internal */
+export declare const HOST_CAPABILITIES: HostCapabilities;