@theia/plugin-utils 1.75.0-next.28

package/src/common/plugin-manifest.ts

@@ -0,0 +1,44 @@
+// *****************************************************************************
+// Copyright (C) 2026 Maksim Kachurin and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { UNPUBLISHED, VSCODE_BUILTIN_NAME_PREFIX } from './constants';
+import type { PluginManifest } from './manifest-types';
+import { updateActivationEvents } from './plugin-activation-events';
+
+export interface PrepareLoadedManifestOptions {
+    /** @default true */
+    updateActivationEvents?: boolean;
+}
+
+type LoadedManifest = Pick<PluginManifest, 'name' | 'publisher' | 'contributes' | 'activationEvents'>;
+
+export function stripVscodeBuiltinNamePrefix(manifest: Pick<PluginManifest, 'name'>): void {
+    if (manifest?.name?.startsWith(VSCODE_BUILTIN_NAME_PREFIX)) {
+        manifest.name = manifest.name.substring(VSCODE_BUILTIN_NAME_PREFIX.length);
+    }
+}
+
+export function prepareLoadedManifest<T extends LoadedManifest>(
+    manifest: T,
+    options?: PrepareLoadedManifestOptions
+): T {
+    stripVscodeBuiltinNamePrefix(manifest);
+    manifest.publisher ??= UNPUBLISHED;
+    if (options?.updateActivationEvents !== false) {
+        updateActivationEvents(manifest);
+    }
+    return manifest;
+}

package/src/common/plugin-model.spec.ts

@@ -0,0 +1,246 @@
+// *****************************************************************************
+// Copyright (C) 2026 Maksim Kachurin and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { expect } from 'chai';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import {
+    UNPUBLISHED,
+    VSCODE_EXTENSION_ACTIVATE,
+    VSCODE_EXTENSION_DEACTIVATE,
+    VSCODE_FRONTEND_INIT,
+    THEIA_PLUGIN_START_METHOD,
+    THEIA_PLUGIN_STOP_METHOD
+} from './constants';
+import {
+    applyTrustExtraction,
+    buildEntryPointForTheia,
+    buildEntryPointForVsCode,
+    buildLifecycle,
+    buildModel,
+    buildModelForTheia,
+    buildModelForVsCode,
+    getPluginId,
+    pickEngineType,
+    toPluginUrl
+} from './plugin-model';
+import { getPluginRootFileUrl } from '../node/plugin-model';
+import { manifest } from './test-helpers';
+
+describe('plugin-model', () => {
+
+    describe('getPluginId', () => {
+        it('sanitizes publisher and name', () => {
+            expect(getPluginId({ publisher: 'dbaeumer', name: 'vscode-eslint' })).to.equal('dbaeumer_vscode_eslint');
+        });
+
+        it('uses unpublished publisher when publisher is missing', () => {
+            expect(getPluginId({ name: 'my-ext' })).to.equal(getPluginId({ publisher: UNPUBLISHED, name: 'my-ext' }));
+        });
+    });
+
+    describe('toPluginUrl', () => {
+        it('encodes each path segment and keeps separators for static hosting', () => {
+            const url = toPluginUrl({ publisher: 'vscode', name: 'theme-monokai' }, './themes/monokai-color-theme.json');
+            expect(url).to.equal('hostedPlugin/vscode_theme_monokai/themes/monokai-color-theme.json');
+        });
+
+        it('encodes special characters inside a segment', () => {
+            expect(toPluginUrl({ publisher: 'acme', name: 'ext' }, 'media/my icon.png'))
+                .to.equal('hostedPlugin/acme_ext/media/my%20icon.png');
+            expect(toPluginUrl({ publisher: 'acme', name: 'ext' }, '$(folder)'))
+                .to.equal('hostedPlugin/acme_ext/%24(folder)');
+        });
+
+        it('resolves .. within the plugin root and ignores leading ..', () => {
+            expect(toPluginUrl({ publisher: 'acme', name: 'ext' }, 'themes/../icons/a.png'))
+                .to.equal('hostedPlugin/acme_ext/icons/a.png');
+            expect(toPluginUrl({ publisher: 'acme', name: 'ext' }, '../secret.json'))
+                .to.equal('hostedPlugin/acme_ext/secret.json');
+        });
+    });
+
+    describe('pickEngineType', () => {
+        it('prefers theiaPlugin over vscode when both are declared', () => {
+            expect(pickEngineType(manifest({
+                name: 'both-engines',
+                engines: { vscode: '^1.0.0', theiaPlugin: '*' }
+            }))).to.equal('theiaPlugin');
+        });
+
+        it('returns vscode when only vscode engine is declared', () => {
+            expect(pickEngineType(manifest({
+                name: 'vscode-only',
+                engines: { vscode: '^1.0.0' }
+            }))).to.equal('vscode');
+        });
+
+        it('throws when no supported engine is declared', () => {
+            expect(() => pickEngineType(manifest({ name: 'no-engine' }))).to.throw(/No vscode or theiaPlugin engine/);
+        });
+    });
+
+    describe('applyTrustExtraction', () => {
+        it('copies untrusted workspace support when declared', () => {
+            const result: { untrustedWorkspacesSupport?: boolean | 'limited' } = {};
+            applyTrustExtraction(manifest({
+                name: 'trusted',
+                capabilities: { untrustedWorkspaces: { supported: 'limited' } }
+            }), result);
+            expect(result.untrustedWorkspacesSupport).to.equal('limited');
+        });
+
+        it('leaves result unchanged when capabilities are absent', () => {
+            const result: { untrustedWorkspacesSupport?: boolean | 'limited' } = {};
+            applyTrustExtraction(manifest({ name: 'plain' }), result);
+            expect(result.untrustedWorkspacesSupport).to.equal(undefined);
+        });
+    });
+
+    describe('getPluginRootFileUrl', () => {
+        let tmpDir: string;
+
+        before(() => {
+            tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'plugin-utils-root-'));
+            fs.writeFileSync(path.join(tmpDir, 'README.md'), '# Readme');
+        });
+
+        after(() => {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        });
+
+        it('finds readme files case-insensitively', () => {
+            const url = getPluginRootFileUrl(manifest({ name: 'docs', packagePath: tmpDir }), ['readme.md']);
+            expect(url).to.equal('hostedPlugin/acme_docs/README.md');
+        });
+
+        it('returns undefined when directory is missing', () => {
+            expect(getPluginRootFileUrl(manifest({ name: 'missing', packagePath: '/no/such/path' }), ['readme.md'])).to.equal(undefined);
+        });
+    });
+
+    describe('buildEntryPointForTheia', () => {
+        it('maps theiaPlugin entry points and headless script', () => {
+            const entryPoint = buildEntryPointForTheia(manifest({
+                name: 'theia-ext',
+                theiaPlugin: {
+                    frontend: './lib/browser/main.js',
+                    backend: './lib/node/main.js',
+                    headless: './lib/headless.js'
+                }
+            }));
+            expect(entryPoint).to.deep.equal({
+                frontend: './lib/browser/main.js',
+                backend: './lib/node/main.js',
+                headless: './lib/headless.js'
+            });
+        });
+    });
+
+    describe('buildEntryPointForVsCode', () => {
+        it('prefers browser entry for ui-only extensions in web mode', () => {
+            const entryPoint = buildEntryPointForVsCode(manifest({
+                name: 'ui-extension',
+                browser: './dist/browser/extension.js',
+                main: './dist/node/extension.js',
+                extensionKind: ['ui']
+            }), { uiKind: 'web' });
+            expect(entryPoint.frontend).to.equal('./dist/browser/extension.js');
+            expect(entryPoint.backend).to.equal(undefined);
+        });
+
+        it('uses main as backend when browser is absent', () => {
+            const entryPoint = buildEntryPointForVsCode(manifest({
+                name: 'workspace-extension',
+                main: './dist/node/extension.js'
+            }), { uiKind: 'web' });
+            expect(entryPoint.backend).to.equal('./dist/node/extension.js');
+            expect(entryPoint.frontend).to.equal(undefined);
+        });
+
+        it('prefers backend when both main and browser exist without ui-only web hint', () => {
+            const entryPoint = buildEntryPointForVsCode(manifest({
+                name: 'hybrid',
+                browser: './dist/browser/extension.js',
+                main: './dist/node/extension.js',
+                extensionKind: ['workspace', 'ui']
+            }), { uiKind: 'web' });
+            expect(entryPoint.backend).to.equal('./dist/node/extension.js');
+            expect(entryPoint.frontend).to.equal(undefined);
+        });
+
+        it('forwards headless script from theiaPlugin section', () => {
+            const entryPoint = buildEntryPointForVsCode(manifest({
+                name: 'headless',
+                main: './main.js',
+                theiaPlugin: { headless: './headless.js' }
+            }));
+            expect(entryPoint.headless).to.equal('./headless.js');
+        });
+    });
+
+    describe('buildModel', () => {
+        it('builds theia plugin model with defaults', () => {
+            const model = buildModelForTheia(manifest({
+                name: 'Sample',
+                publisher: 'Acme',
+                packageUri: 'hostedPlugin/acme_Sample/'
+            }));
+            expect(model.id).to.equal('acme.sample');
+            expect(model.engine).to.deep.equal({ type: 'theiaPlugin', version: '*' });
+            expect(model.displayName).to.equal('Test Extension');
+            expect(model.packageUri).to.equal('hostedPlugin/acme_Sample/');
+        });
+
+        it('builds vscode model with icon url and web entry point', () => {
+            const model = buildModelForVsCode(manifest({
+                name: 'icon-ext',
+                icon: './media/icon.png',
+                browser: './browser.js',
+                extensionKind: ['ui'],
+                engines: { vscode: '^1.90.0' }
+            }), { uiKind: 'web' });
+            expect(model.engine).to.deep.equal({ type: 'vscode', version: '^1.90.0' });
+            expect(model.iconUrl).to.equal('hostedPlugin/acme_icon_ext/media/icon.png');
+            expect(model.entryPoint.frontend).to.equal('./browser.js');
+        });
+
+        it('uses UNPUBLISHED publisher and displayName fallback', () => {
+            const model = buildModel(manifest({ name: 'anon', publisher: undefined, displayName: undefined }), 'vscode');
+            expect(model.publisher).to.equal(UNPUBLISHED);
+            expect(model.displayName).to.equal('anon');
+        });
+    });
+
+    describe('buildLifecycle', () => {
+        it('uses theia start/stop for theiaPlugin engine', () => {
+            const lifecycle = buildLifecycle(manifest({ name: 'theia', publisher: 'acme' }), 'theiaPlugin');
+            expect(lifecycle.startMethod).to.equal(THEIA_PLUGIN_START_METHOD);
+            expect(lifecycle.stopMethod).to.equal(THEIA_PLUGIN_STOP_METHOD);
+            expect(lifecycle.frontendModuleName).to.equal('acme_theia');
+            expect(lifecycle.frontendInitPath).to.equal(undefined);
+        });
+
+        it('uses vscode activate/deactivate lifecycle', () => {
+            const lifecycle = buildLifecycle(manifest({ name: 'sample', publisher: 'acme' }), 'vscode');
+            expect(lifecycle.startMethod).to.equal(VSCODE_EXTENSION_ACTIVATE);
+            expect(lifecycle.stopMethod).to.equal(VSCODE_EXTENSION_DEACTIVATE);
+            expect(lifecycle.frontendInitPath).to.equal(VSCODE_FRONTEND_INIT);
+            expect(lifecycle.frontendModuleName).to.equal('acme_sample');
+        });
+    });
+});

package/src/common/plugin-model.ts

@@ -0,0 +1,194 @@
+// *****************************************************************************
+// Copyright (C) 2026 Maksim Kachurin and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import {
+    PLUGINS_BASE_PATH,
+    THEIA_PLUGIN_START_METHOD,
+    THEIA_PLUGIN_STOP_METHOD,
+    UNPUBLISHED,
+    VSCODE_EXTENSION_ACTIVATE,
+    VSCODE_EXTENSION_DEACTIVATE,
+    VSCODE_FRONTEND_INIT
+} from './constants';
+import type {
+    PluginEntryPoint,
+    PluginLifecycle,
+    PluginModel,
+    PluginManifest,
+    PluginPackageCapabilities
+} from './manifest-types';
+
+export interface PluginIdentifierSource {
+    publisher?: string;
+    name: string;
+}
+
+export interface VsCodeBuildOptions {
+    /** When `'web'`, UI-only extensions prefer the browser entry point (Codespaces behavior). */
+    uiKind?: 'web' | 'desktop';
+}
+
+export function getPluginId(plugin: PluginIdentifierSource): string {
+    return `${plugin.publisher ?? UNPUBLISHED}_${plugin.name}`.replace(/\W/g, '_');
+}
+
+/**
+ * Builds a static-friendly plugin asset URL: `hostedPlugin/<id>/<segments...>`.
+ * Path separators stay literal `/`; each segment is `encodeURIComponent`'d so plain
+ * static file servers (browser-only) resolve assets without needing Express `:path(*)` decoding.
+ * `.` is dropped and `..` is resolved within the plugin root (leading `..` is ignored).
+ */
+export function toPluginUrl(pck: PluginIdentifierSource, relativePath: string): string {
+    const segments: string[] = [];
+    for (const segment of relativePath.replace(/\\/g, '/').split('/')) {
+        if (!segment || segment === '.') {
+            continue;
+        }
+        if (segment === '..') {
+            // Drop parent segment when present; ignore leading `..` so URLs never contain
+            // literal `..` (encodeURIComponent does not encode dots).
+            segments.pop();
+            continue;
+        }
+        segments.push(encodeURIComponent(segment));
+    }
+    return `${PLUGINS_BASE_PATH}/${getPluginId(pck)}/${segments.join('/')}`;
+}
+
+/**
+ * Explicit `theiaPlugin` engine takes priority over `vscode`.
+ */
+export function pickEngineType(manifest: PluginManifest): 'theiaPlugin' | 'vscode' {
+    if (manifest.engines?.theiaPlugin !== undefined) {
+        return 'theiaPlugin';
+    }
+    if (manifest.engines?.vscode !== undefined) {
+        return 'vscode';
+    }
+    throw new Error(`No vscode or theiaPlugin engine in ${manifest.name}`);
+}
+
+export function applyTrustExtraction(
+    manifest: { capabilities?: PluginPackageCapabilities },
+    result: { untrustedWorkspacesSupport?: boolean | 'limited' }
+): void {
+    const untrustedWorkspacesSupport = manifest.capabilities?.untrustedWorkspaces?.supported;
+    if (untrustedWorkspacesSupport !== undefined) {
+        result.untrustedWorkspacesSupport = untrustedWorkspacesSupport;
+    }
+}
+
+/** Minimal `pathToFileURL(...).href` without importing Node's `url` (keeps this module worker-safe). */
+function pathToFileUrlHref(absolutePath: string): string {
+    const normalized = absolutePath.replace(/\\/g, '/');
+    if (/^[a-zA-Z]:\//.test(normalized)) {
+        return `file:///${normalized}`;
+    }
+    return `file://${normalized.startsWith('/') ? normalized : `/${normalized}`}`;
+}
+
+export function buildEntryPointForTheia(manifest: PluginManifest): PluginEntryPoint {
+    const result: PluginEntryPoint = {
+        frontend: manifest.theiaPlugin?.frontend,
+        backend: manifest.theiaPlugin?.backend
+    };
+    if (manifest.theiaPlugin?.headless) {
+        result.headless = manifest.theiaPlugin.headless;
+    }
+    return result;
+}
+
+export function buildEntryPointForVsCode(manifest: PluginManifest, options?: VsCodeBuildOptions): PluginEntryPoint {
+    const entryPoint: PluginEntryPoint = {};
+    const preferFrontend = options?.uiKind === 'web'
+        && manifest.extensionKind?.length === 1
+        && manifest.extensionKind[0] === 'ui';
+
+    if (manifest.browser && (!manifest.main || preferFrontend)) {
+        entryPoint.frontend = manifest.browser;
+    } else {
+        entryPoint.backend = manifest.main;
+    }
+    if (manifest.theiaPlugin?.headless) {
+        entryPoint.headless = manifest.theiaPlugin.headless;
+    }
+    return entryPoint;
+}
+
+export function buildModelForTheia(manifest: PluginManifest): PluginModel {
+    const publisher = manifest.publisher ?? UNPUBLISHED;
+    const packageUri = manifest.packageUri ?? pathToFileUrlHref(manifest.packagePath);
+
+    return {
+        packagePath: manifest.packagePath,
+        packageUri,
+        id: `${publisher.toLowerCase()}.${manifest.name.toLowerCase()}`,
+        name: manifest.name,
+        publisher,
+        version: manifest.version,
+        displayName: manifest.displayName ?? manifest.name,
+        description: manifest.description ?? '',
+        l10n: manifest.l10n,
+        engine: {
+            type: 'theiaPlugin',
+            version: manifest.engines?.theiaPlugin ?? '*'
+        },
+        entryPoint: buildEntryPointForTheia(manifest),
+    };
+}
+
+export function buildModelForVsCode(manifest: PluginManifest, options?: VsCodeBuildOptions): PluginModel {
+    const publisher = manifest.publisher ?? UNPUBLISHED;
+    const packageUri = manifest.packageUri ?? pathToFileUrlHref(manifest.packagePath);
+    return {
+        packagePath: manifest.packagePath,
+        packageUri,
+        id: `${publisher.toLowerCase()}.${manifest.name.toLowerCase()}`,
+        name: manifest.name,
+        publisher,
+        version: manifest.version,
+        displayName: manifest.displayName ?? manifest.name,
+        description: manifest.description ?? '',
+        l10n: manifest.l10n,
+        engine: {
+            type: 'vscode',
+            version: manifest.engines?.vscode ?? '*'
+        },
+        entryPoint: buildEntryPointForVsCode(manifest, options),
+        iconUrl: manifest.icon ? toPluginUrl(manifest, manifest.icon) : undefined,
+    };
+}
+
+export function buildModel(manifest: PluginManifest, engineType: 'theiaPlugin' | 'vscode', options?: VsCodeBuildOptions): PluginModel {
+    return engineType === 'theiaPlugin' ? buildModelForTheia(manifest) : buildModelForVsCode(manifest, options);
+}
+
+export function buildLifecycle(manifest: PluginManifest, engineType: 'theiaPlugin' | 'vscode'): PluginLifecycle {
+    const frontendModuleName = getPluginId(manifest);
+    if (engineType === 'theiaPlugin') {
+        return {
+            startMethod: THEIA_PLUGIN_START_METHOD,
+            stopMethod: THEIA_PLUGIN_STOP_METHOD,
+            frontendModuleName,
+        };
+    }
+    return {
+        startMethod: VSCODE_EXTENSION_ACTIVATE,
+        stopMethod: VSCODE_EXTENSION_DEACTIVATE,
+        frontendModuleName,
+        frontendInitPath: VSCODE_FRONTEND_INIT
+    };
+}

package/src/common/protocol-shims.ts

@@ -0,0 +1,148 @@
+// *****************************************************************************
+// Copyright (C) 2026 Maksim Kachurin and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+/**
+ * Structural subset of `@theia/core` / `@theia/task` types used by normalize-contributions.
+ * Keep in sync with:
+ * `packages/core/src/common/json-schema.ts`,
+ * `packages/core/src/common/preferences/preference-schema.ts`,
+ * `packages/core/src/common/color.ts`,
+ * `packages/task/src/common/task-protocol.ts`.
+ */
+
+export type JSONPrimitive = boolean | number | string | null;
+
+export type JSONValue = JSONPrimitive | JSONObject | JSONValue[];
+
+export interface JSONObject {
+    [key: string]: JSONValue;
+}
+
+export type JsonType = 'string' | 'array' | 'number' | 'integer' | 'object' | 'boolean' | 'null';
+
+export interface IJSONSchema {
+    id?: string;
+    $id?: string;
+    $schema?: string;
+    type?: JsonType | JsonType[];
+    owner?: string;
+    group?: string;
+    title?: string;
+    default?: JSONValue;
+    definitions?: IJSONSchemaMap;
+    description?: string;
+    properties?: IJSONSchemaMap;
+    patternProperties?: IJSONSchemaMap;
+    additionalProperties?: boolean | IJSONSchema;
+    minProperties?: number;
+    maxProperties?: number;
+    dependencies?: IJSONSchemaMap | { [prop: string]: string[] };
+    items?: IJSONSchema | IJSONSchema[];
+    prefixItems?: IJSONSchema[];
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+    additionalItems?: boolean | IJSONSchema;
+    pattern?: string;
+    minLength?: number;
+    maxLength?: number;
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: boolean | number;
+    exclusiveMaximum?: boolean | number;
+    multipleOf?: number;
+    required?: string[];
+    $ref?: string;
+    anyOf?: IJSONSchema[];
+    allOf?: IJSONSchema[];
+    oneOf?: IJSONSchema[];
+    not?: IJSONSchema;
+    enum?: JSONValue[];
+    format?: string;
+    const?: JSONValue;
+    contains?: IJSONSchema;
+    propertyNames?: IJSONSchema;
+    $comment?: string;
+    if?: IJSONSchema;
+    then?: IJSONSchema;
+    else?: IJSONSchema;
+    defaultSnippets?: IJSONSchemaSnippet[];
+    errorMessage?: string;
+    patternErrorMessage?: string;
+    deprecationMessage?: string;
+    markdownDeprecationMessage?: string;
+    enumItemLabels?: string[];
+    enumDescriptions?: string[];
+    markdownEnumDescriptions?: string[];
+    markdownDescription?: string;
+    doNotSuggest?: boolean;
+    allowComments?: boolean;
+    allowTrailingCommas?: boolean;
+}
+
+export interface IJSONSchemaMap {
+    [name: string]: IJSONSchema;
+}
+
+export interface IJSONSchemaSnippet {
+    label?: string;
+    description?: string;
+    body?: JSONValue;
+    bodyText?: string;
+}
+
+/** Keep numeric values aligned with `PreferenceScope` in `@theia/core`. */
+export enum PreferenceScope {
+    Default = 0,
+    User = 1,
+    Workspace = 2,
+    Folder = 3,
+}
+
+export interface PreferenceDataProperty extends IJSONSchema {
+    overridable?: boolean;
+    included?: boolean;
+    hidden?: boolean;
+    scope?: PreferenceScope;
+    typeDetails?: unknown;
+    tags?: string[];
+}
+
+export interface PreferenceSchema {
+    scope?: PreferenceScope;
+    title?: string;
+    defaultOverridable?: boolean;
+    properties: { [name: string]: PreferenceDataProperty };
+}
+
+export interface ColorDefinition {
+    id: string;
+    defaults?: { light: string; dark: string; hc: string };
+    description: string;
+}
+
+export interface TaskDefinition {
+    taskType: string;
+    source: string;
+    properties: {
+        required?: string[];
+        all: string[];
+        schema: IJSONSchema;
+    };
+}
+
+/** Same segment as `CSSIcon.iconNameSegment` in `@theia/core`. */
+export const ICON_NAME_SEGMENT = '[A-Za-z0-9]+';

package/src/common/test-helpers.ts

@@ -0,0 +1,44 @@
+// *****************************************************************************
+// Copyright (C) 2026 Maksim Kachurin and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import type { NormalizeContributionsContext } from './contribution-types';
+import type { PluginManifest } from './manifest-types';
+import { toPluginUrl } from './plugin-model';
+
+export function manifest(partial: Partial<PluginManifest> & Pick<PluginManifest, 'name'>): PluginManifest {
+    return {
+        version: '1.0.0',
+        publisher: 'acme',
+        packagePath: '/tmp/plugin',
+        displayName: 'Test Extension',
+        ...partial
+    };
+}
+
+export function createNormalizeCtx(
+    pluginOverrides?: Partial<PluginManifest>,
+    ctxOverrides?: Partial<NormalizeContributionsContext>
+): NormalizeContributionsContext {
+    const plugin = manifest({ name: 'test-ext', ...pluginOverrides });
+    return {
+        plugin,
+        resolveUrl: relativePath => toPluginUrl(plugin, relativePath),
+        resolveUri: (pck, relativePath) => toPluginUrl(pck, relativePath),
+        onError: () => undefined,
+        onWarn: () => undefined,
+        ...ctxOverrides
+    };
+}