Make Concordance extensible

Basic API for augmenting the themes and appending plugins. Fixes #1861.

Author: novemberborn

entrypoints/plugin.mjs

@@ -1,4 +1,4 @@
 import * as plugin from '../lib/worker/plugin.cjs';
 
-const {registerSharedWorker} = plugin;
-export {registerSharedWorker};
+const {extendCondordance, registerSharedWorker} = plugin;
+export {extendCondordance, registerSharedWorker};

lib/concordance-options.js

@@ -85,18 +85,48 @@ const colorTheme = {
 	undefined: ansiStyles.yellow,
 };
 
-const plainTheme = JSON.parse(JSON.stringify(colorTheme), value => typeof value === 'string' ? stripAnsi(value) : value);
+const stripColor = colorTheme => JSON.parse(JSON.stringify(colorTheme), value => typeof value === 'string' ? stripAnsi(value) : value);
 
-const theme = chalk.level > 0 ? colorTheme : plainTheme;
+const plainTheme = stripColor(colorTheme);
+
+let plugins = [];
 
 const concordanceOptions = {
 	// Use Node's object inspection depth, clamped to a minimum of 3
 	get maxDepth() {
 		return Math.max(3, inspect.defaultOptions.depth);
 	},
-	theme,
+	plugins,
+	theme: chalk.level > 0 ? colorTheme : plainTheme,
 };
 
 export default concordanceOptions;
 
-export const snapshotManager = {theme: plainTheme};
+export const snapshotManager = {plugins, theme: plainTheme};
+
+export const maxColorLevel = forceColor.level;
+
+export function extendTheme(theme) {
+	for (const [key, value] of theme) {
+		if (typeof value === 'object') {
+			colorTheme[key] = {...colorTheme[key], ...value};
+			plainTheme[key] = {...plainTheme[key], ...stripColor(value)};
+		} else {
+			colorTheme[key] = value;
+			plainTheme[key] = stripColor({value}).value;
+		}
+	}
+
+	// The theme object is used as a cache key so it needs to be changed for
+	// changes to take effect.
+	concordanceOptions.theme = {...concordanceOptions.theme};
+	snapshotManager.theme = {...snapshotManager.theme};
+}
+
+export function appendPlugin(plugin) {
+	// The plugins array is used as a cache key so it needs to be changed for
+	// changes to take effect.
+	plugins = [...plugins, plugin];
+	concordanceOptions.plugins = plugins;
+	snapshotManager.plugins = plugins;
+}

lib/worker/base.js

@@ -6,6 +6,7 @@ import {workerData} from 'node:worker_threads';
 import setUpCurrentlyUnhandled from 'currently-unhandled';
 
 import {set as setChalk} from '../chalk.js';
+import * as concordanceOptions from '../concordance-options.js';
 import nowAndTimers from '../now-and-timers.cjs';
 import providerManager from '../provider-manager.js';
 import Runner from '../runner.js';
@@ -24,6 +25,8 @@ const run = async options => {
 	setOptions(options);
 	setChalk(options.chalkOptions);
 
+	refs.concordanceOptions = concordanceOptions;
+
 	if (options.chalkOptions.level > 0) {
 		const {stdout, stderr} = process;
 		global.console = Object.assign(global.console, new console.Console({stdout, stderr, colorMode: true}));

lib/worker/plugin.cjs

@@ -2,7 +2,7 @@ const pkg = require('../../package.json');
 
 const {registerSharedWorker: register} = require('./channel.cjs');
 const options = require('./options.cjs');
-const {sharedWorkerTeardowns, waitForReady} = require('./state.cjs');
+const {refs, sharedWorkerTeardowns, waitForReady} = require('./state.cjs');
 
 require('./guard-environment.cjs'); // eslint-disable-line import/no-unassigned-import
 
@@ -128,3 +128,23 @@ function registerSharedWorker({
 }
 
 exports.registerSharedWorker = registerSharedWorker;
+
+function extendConcordance({supportedProtocols}) {
+	if (!supportedProtocols.includes('ava-4.1')) {
+		throw new Error(`This version of AVA (${pkg.version}) does not support any of the desired Concordance extension protocols: ${supportedProtocols.join(',')}`);
+	}
+
+	return {
+		maxColorLevel: refs.concordanceOptions.maxColorLevel,
+
+		extendTheme(theme) {
+			refs.concordanceOptions.extendTheme(theme);
+		},
+
+		appendPlugin(plugin) {
+			refs.concordanceOptions.appendPlugin(plugin);
+		},
+	};
+}
+
+exports.extendConcordance = extendConcordance;

plugin.d.ts

@@ -75,3 +75,34 @@ export namespace SharedWorker {
 
 export function registerSharedWorker<Data = unknown>(options: SharedWorker.Plugin.RegistrationOptions<'ava-4', Data>): SharedWorker.Plugin.Protocol<Data>;
 // Add overloads for additional protocols.
+
+export namespace Concordance {
+	export type ProtocolIdentifier = 'ava-4.1';
+
+	export type RegistrationOptions<Identifier extends ProtocolIdentifier> = {
+		readonly supportedProtocols: readonly Identifier[];
+	};
+
+	export interface Theme { // eslint-disable-line @typescript-eslint/consistent-indexed-object-style
+		[field: string]: string | Theme;
+	}
+
+	// N.B. Concordance doesn't have a type definition we can re-export.
+	export type Plugin = {
+		name: string;
+		apiVersion: number;
+		minimalConcordanceVersion?: string;
+		serializerVersion: number;
+		theme?: Theme;
+		register: (api: Record<string, unknown>) => (value: unknown) => Function | null; // eslint-disable-line @typescript-eslint/ban-types
+	};
+
+	export type Protocol = {
+		readonly maxColorLevel: number;
+		extendTheme: (theme: Theme) => void;
+		appendPlugin: (plugin: Plugin) => void;
+	};
+}
+
+export function extendConcordance(options: Concordance.RegistrationOptions<'ava-4.1'>): Concordance.Protocol;
+// Add overloads for additional protocols.