#15089

Committed 13 Jan 2026 07:24PM UTC coverage: 87.298% (+0.002%) from 87.296%

Build Type

push

Committed by

Commit Message

Merge 6435e8344 into dbcb4f2dd

Run Details

14410 of 17441 branches covered (82.62%)

Branch coverage included in aggregate %.

53 of 53 new or added lines in 11 files covered. (100.0%)

55 existing lines in 4 files now uncovered.

15103 of 16366 relevant lines covered (92.28%)

24217.83 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

76.67

/src/PluginInterface.ts

import type { Plugin } from './interfaces';
import { LogLevel, createLogger } from './logging';
import type { Logger } from './logging';
/*
 * we use `Required` everywhere here because we expect that the methods on plugin objects will
 * be optional, and we don't want to deal with `undefined`.
 * `extends (...args: any[]) => any` determines whether the thing we're dealing with is a function.
 * Returning `never` in the `as` clause of the `[key in object]` step deletes that key from the
 * resultant object.
 * on the right-hand side of the mapped type we are forced to use a conditional type a second time,
 * in order to be able to use the `Parameters` utility type on `Required<T>[K]`. This will always
 * be true because of the filtering done by the `[key in object]` clause, but TS requires the duplication.
 *
 * so put together: we iterate over all of the fields in T, deleting ones which are not (potentially
 * optional) functions. For the ones that are, we replace them with their parameters.
 *
 * this returns the type of an object whose keys are the names of the methods of T and whose values
 * are tuples containing the arguments that each method accepts.
 */
export type PluginEventArgs<T> = {
    [K in keyof Required<T> as Required<T>[K] extends (...args: any[]) => any ? K : never]:
    Required<T>[K] extends (...args: any[]) => any ? Parameters<Required<T>[K]> : never
};

export default class PluginInterface<T extends Plugin = Plugin> {
    constructor(
        plugins?: Plugin[],
        options?: {
            logger?: Logger;
            suppressErrors?: boolean;
        }
    ) {
        this.logger = options?.logger;
        this.suppressErrors = (options as any)?.suppressErrors === false ? false : true;
        for (const plugin of plugins ?? []) {
            this.add(plugin);
        }
        if (!this.logger) {
            this.logger = createLogger();
        }
        if (!this.logger) {
            this.logger = createLogger();
        }
    }

    private plugins: Plugin[] = [];
    private logger: Logger;

    /**
     * Should plugin errors cause the program to fail, or should they be caught and simply logged
     */
    private suppressErrors: boolean | undefined;

    /**
     * Call `event` on plugins
     */
    public emit<K extends keyof PluginEventArgs<T> & string>(event: K, ...args: PluginEventArgs<T>[K]) {
        this.logger.debug(`Emitting plugin event: ${event}`);
        for (let plugin of this.plugins) {
            if ((plugin as any)[event]) {
                try {
                    this.logger?.time(LogLevel.debug, [plugin.name, event], () => {
                        (plugin as any)[event](...args);
                    });
                } catch (err) {
                    this.logger?.error(`Error when calling plugin ${plugin.name}.${event}:`, (err as Error).stack);
                    if (!this.suppressErrors) {
                        throw err;
                    }
                }
            }
        }
        return args[0];
    }

    /**
     * Call `event` on plugins, but allow the plugins to return promises that will be awaited before the next plugin is notified
     */
    public async emitAsync<K extends keyof PluginEventArgs<T> & string>(event: K, ...args: PluginEventArgs<T>[K]): Promise<PluginEventArgs<T>[K][0]> {
        this.logger.debug(`Emitting async plugin event: ${event}`);
        for (let plugin of this.plugins) {
            if ((plugin as any)[event]) {
                try {
                    await this.logger?.time(LogLevel.debug, [plugin.name, event], async () => {
                        await Promise.resolve(
                            (plugin as any)[event](...args)
                        );
                    });
                } catch (err) {
                    this.logger?.error(`Error when calling plugin ${plugin.name}.${event}:`, (err as Error).stack);
                    if (!this.suppressErrors) {
                        throw err;
                    }
                }
            }
        }
        return args[0];
    }

    /**
     * Add a plugin to the beginning of the list of plugins
     */
    public addFirst<T extends Plugin = Plugin>(plugin: T) {
        if (!this.has(plugin)) {
            this.plugins.unshift(plugin);
        }
        return plugin;
    }

    /**
     * Add a plugin to the end of the list of plugins
     */
    public add<T extends Plugin = Plugin>(plugin: T) {
        if (!this.has(plugin)) {
            this.sanitizePlugin(plugin);
            this.plugins.push(plugin);
        }
        return plugin;
    }

    /**
     * Find deprecated or removed historic plugin hooks, and warn about them.
     * Some events can be forwards-converted
     */
    private sanitizePlugin(plugin: Plugin) {
        const removedHooks = [
            'beforePrepublish',
            'afterPrepublish'
        ];
        for (const removedHook of removedHooks) {
            if (plugin[removedHook]) {
                this.logger?.error(`Plugin "${plugin.name}": event ${removedHook} is no longer supported and will never be called`);
            }
        }

        const upgradeWithWarn = {
            beforePublish: 'beforeSerializeProgram',
            afterPublish: 'afterSerializeProgram',
            beforeProgramTranspile: 'beforeBuildProgram',
            afterProgramTranspile: 'afterBuildProgram',
            beforeFileParse: 'beforeProvideFile',
            afterFileParse: 'afterProvideFile',
            beforeFileTranspile: 'beforePrepareFile',
            afterFileTranspile: 'afterPrepareFile',
            beforeFileDispose: 'beforeRemoveFile',
            afterFileDispose: 'afterRemoveFile',
            beforeProgramCreate: 'beforeProvideProgram',
            afterProgramCreate: 'afterProvideProgram',
            beforeProgramValidate: 'beforeValidateProgram',
            onProgramValidate: 'validateProgram',
            beforeProgramDispose: 'beforeRemoveProgram',
            afterScopeCreate: 'afterProvideScope',
            beforeScopeDispose: 'beforeRemoveScope',
            onScopeDispose: 'removeScope',
            afterScopeDispose: 'afterRemoveScope',
            beforeScopeValidate: 'beforeValidateScope',
            onScopeValidate: 'validateScope',
            afterScopeValidate: 'afterValidateScope',
            onGetCodeActions: 'provideCodeActions',
            onGetSemanticTokens: 'provideSemanticTokens',
            beforeFileAdd: 'beforeAddFile',
            afterFileAdd: 'afterAddFile',
            beforeFileRemove: 'beforeRemoveFile',
            afterFileRemove: 'afterRemoveFile',
            beforeFileValidate: 'beforeValidateFile',
            onFileValidate: 'validateFile',
            afterFileValidate: 'afterValidateFile',
            onSerializeProgram: 'serializeProgram'
        };

        for (const [oldEvent, newEvent] of Object.entries(upgradeWithWarn)) {
            if (plugin[oldEvent]) {
                if (!plugin[newEvent]) {
                    plugin[newEvent] = plugin[oldEvent];
                    this.logger?.warn(`Plugin '${plugin.name}': event '${oldEvent}' is no longer supported. It has been converted to '${newEvent}' but you may encounter issues as their signatures may not match.`);
                } else {
                    this.logger?.warn(`Plugin "${plugin.name}": event '${oldEvent}' is no longer supported and will never be called`);
                }
            }
        }
    }

    public has(plugin: Plugin) {
        return this.plugins.includes(plugin);
    }

    public remove<T extends Plugin = Plugin>(plugin: T) {
        if (this.has(plugin)) {
            this.plugins.splice(this.plugins.indexOf(plugin), 1);
        }
        return plugin;
    }

    /**
     * Remove all plugins
     */
    public clear() {
        this.plugins = [];
    }
}

1	import type { Plugin } from './interfaces';
2	import { LogLevel, createLogger } from './logging';	1✔
3	import type { Logger } from './logging';
4	/*
5	* we use `Required` everywhere here because we expect that the methods on plugin objects will
6	* be optional, and we don't want to deal with `undefined`.
7	* `extends (...args: any[]) => any` determines whether the thing we're dealing with is a function.
8	* Returning `never` in the `as` clause of the `[key in object]` step deletes that key from the
9	* resultant object.
10	* on the right-hand side of the mapped type we are forced to use a conditional type a second time,
11	* in order to be able to use the `Parameters` utility type on `Required<T>[K]`. This will always
12	* be true because of the filtering done by the `[key in object]` clause, but TS requires the duplication.
13	*
14	* so put together: we iterate over all of the fields in T, deleting ones which are not (potentially
15	* optional) functions. For the ones that are, we replace them with their parameters.
16	*
17	* this returns the type of an object whose keys are the names of the methods of T and whose values
18	* are tuples containing the arguments that each method accepts.
19	*/
20	export type PluginEventArgs<T> = {
21	[K in keyof Required<T> as Required<T>[K] extends (...args: any[]) => any ? K : never]:
22	Required<T>[K] extends (...args: any[]) => any ? Parameters<Required<T>[K]> : never
23	};
24
25	export default class PluginInterface<T extends Plugin = Plugin> {	1✔
26	constructor(
27	plugins?: Plugin[],
28	options?: {
29	logger?: Logger;
30	suppressErrors?: boolean;
31	}
32	) {
33	this.logger = options?.logger;	2,137✔
34	this.suppressErrors = (options as any)?.suppressErrors === false ? false : true;	2,137!
35	for (const plugin of plugins ?? []) {	2,137✔
36	this.add(plugin);	×
37	}
38	if (!this.logger) {	2,137✔
39	this.logger = createLogger();	1✔
40	}
41	if (!this.logger) {	2,137!
42	this.logger = createLogger();	×
43	}
44	}
45
46	private plugins: Plugin[] = [];	2,137✔
47	private logger: Logger;
48
49	/**
50	* Should plugin errors cause the program to fail, or should they be caught and simply logged
51	*/
52	private suppressErrors: boolean \| undefined;
53
54	/**
55	* Call `event` on plugins
56	*/
57	public emit<K extends keyof PluginEventArgs<T> & string>(event: K, ...args: PluginEventArgs<T>[K]) {
58	this.logger.debug(`Emitting plugin event: ${event}`);	46,096✔
59	for (let plugin of this.plugins) {	46,096✔
60	if ((plugin as any)[event]) {	49,221✔
61	try {	14,125✔
62	this.logger?.time(LogLevel.debug, [plugin.name, event], () => {	14,125!
63	(plugin as any)[event](...args);	14,125✔
64	});
65	} catch (err) {
66	this.logger?.error(`Error when calling plugin ${plugin.name}.${event}:`, (err as Error).stack);	3!
67	if (!this.suppressErrors) {	3!
68	throw err;	×
69	}
70	}
71	}
72	}
73	return args[0];	46,096✔
74	}
75
76	/**
77	* Call `event` on plugins, but allow the plugins to return promises that will be awaited before the next plugin is notified
78	*/
79	public async emitAsync<K extends keyof PluginEventArgs<T> & string>(event: K, ...args: PluginEventArgs<T>[K]): Promise<PluginEventArgs<T>[K][0]> {
80	this.logger.debug(`Emitting async plugin event: ${event}`);	11,883✔
81	for (let plugin of this.plugins) {	11,883✔
82	if ((plugin as any)[event]) {	22,809✔
83	try {	4,301✔
84	await this.logger?.time(LogLevel.debug, [plugin.name, event], async () => {	4,301!
85	await Promise.resolve(	4,301✔
86	(plugin as any)[event](...args)
87	);
88	});
89	} catch (err) {
90	this.logger?.error(`Error when calling plugin ${plugin.name}.${event}:`, (err as Error).stack);	2!
91	if (!this.suppressErrors) {	2!
92	throw err;	×
93	}
94	}
95	}
96	}
97	return args[0];	11,883✔
98	}
99
100	/**
101	* Add a plugin to the beginning of the list of plugins
102	*/
103	public addFirst<T extends Plugin = Plugin>(plugin: T) {
104	if (!this.has(plugin)) {	2,466!
105	this.plugins.unshift(plugin);	2,466✔
106	}
107	return plugin;	2,466✔
108	}
109
110	/**
111	* Add a plugin to the end of the list of plugins
112	*/
113	public add<T extends Plugin = Plugin>(plugin: T) {
114	if (!this.has(plugin)) {	162✔
115	this.sanitizePlugin(plugin);	161✔
116	this.plugins.push(plugin);	161✔
117	}
118	return plugin;	162✔
119	}
120
121	/**
122	* Find deprecated or removed historic plugin hooks, and warn about them.
123	* Some events can be forwards-converted
124	*/
125	private sanitizePlugin(plugin: Plugin) {
126	const removedHooks = [	161✔
127	'beforePrepublish',
128	'afterPrepublish'
129	];
130	for (const removedHook of removedHooks) {	161✔
131	if (plugin[removedHook]) {	322!
132	this.logger?.error(`Plugin "${plugin.name}": event ${removedHook} is no longer supported and will never be called`);	×
133	}
134	}
135
136	const upgradeWithWarn = {	161✔
137	beforePublish: 'beforeSerializeProgram',
138	afterPublish: 'afterSerializeProgram',
139	beforeProgramTranspile: 'beforeBuildProgram',
140	afterProgramTranspile: 'afterBuildProgram',
141	beforeFileParse: 'beforeProvideFile',
142	afterFileParse: 'afterProvideFile',
143	beforeFileTranspile: 'beforePrepareFile',
144	afterFileTranspile: 'afterPrepareFile',
145	beforeFileDispose: 'beforeRemoveFile',
146	afterFileDispose: 'afterRemoveFile',
147	beforeProgramCreate: 'beforeProvideProgram',
148	afterProgramCreate: 'afterProvideProgram',
149	beforeProgramValidate: 'beforeValidateProgram',
150	onProgramValidate: 'validateProgram',
151	beforeProgramDispose: 'beforeRemoveProgram',
152	afterScopeCreate: 'afterProvideScope',
153	beforeScopeDispose: 'beforeRemoveScope',
154	onScopeDispose: 'removeScope',
155	afterScopeDispose: 'afterRemoveScope',
156	beforeScopeValidate: 'beforeValidateScope',
157	onScopeValidate: 'validateScope',
158	afterScopeValidate: 'afterValidateScope',
159	onGetCodeActions: 'provideCodeActions',
160	onGetSemanticTokens: 'provideSemanticTokens',
161	beforeFileAdd: 'beforeAddFile',
162	afterFileAdd: 'afterAddFile',
163	beforeFileRemove: 'beforeRemoveFile',
164	afterFileRemove: 'afterRemoveFile',
165	beforeFileValidate: 'beforeValidateFile',
166	onFileValidate: 'validateFile',
167	afterFileValidate: 'afterValidateFile',
168	onSerializeProgram: 'serializeProgram'
169	};
170
171	for (const [oldEvent, newEvent] of Object.entries(upgradeWithWarn)) {	161✔
172	if (plugin[oldEvent]) {	5,152✔
173	if (!plugin[newEvent]) {	1!
174	plugin[newEvent] = plugin[oldEvent];	1✔
175	this.logger?.warn(`Plugin '${plugin.name}': event '${oldEvent}' is no longer supported. It has been converted to '${newEvent}' but you may encounter issues as their signatures may not match.`);	1!
176	} else {
UNCOV 177	this.logger?.warn(`Plugin "${plugin.name}": event '${oldEvent}' is no longer supported and will never be called`);	×
178	}
179	}
180	}
181	}
182
183	public has(plugin: Plugin) {
184	return this.plugins.includes(plugin);	2,983✔
185	}
186
187	public remove<T extends Plugin = Plugin>(plugin: T) {
188	if (this.has(plugin)) {	352!
189	this.plugins.splice(this.plugins.indexOf(plugin), 1);	352✔
190	}
191	return plugin;	352✔
192	}
193
194	/**
195	* Remove all plugins
196	*/
197	public clear() {
UNCOV 198	this.plugins = [];	×
199	}
200	}

rokucommunity / brighterscript / #15089

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous