@theia/plugin-utils 1.75.0-next.28

package/src/node/package-nls.ts

@@ -0,0 +1,45 @@
+// *****************************************************************************
+// Copyright (C) 2021 TypeFox 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 * as path from 'path';
+import * as fs from 'fs-extra';
+import { isENOENT } from '../common/utils';
+import {
+    coerceLocalizations,
+    type PackageTranslation,
+} from '../common/package-nls';
+
+export async function loadPackageTranslations(pluginPath: string, locale?: string): Promise<PackageTranslation> {
+    const defaultPath = path.join(pluginPath, 'package.nls.json');
+    try {
+        const defaultValue = coerceLocalizations(await fs.readJson(defaultPath));
+        if (locale) {
+            const localizedPath = path.join(pluginPath, `package.nls.${locale}.json`);
+            if (await fs.pathExists(localizedPath)) {
+                return {
+                    translation: coerceLocalizations(await fs.readJson(localizedPath)),
+                    default: defaultValue
+                };
+            }
+        }
+        return { default: defaultValue };
+    } catch (error) {
+        if (isENOENT(error)) {
+            return {};
+        }
+        throw error;
+    }
+}

package/src/node/plugin-manifest.ts

@@ -0,0 +1,30 @@
+// *****************************************************************************
+// 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 * as path from 'path';
+import * as fs from 'fs-extra';
+import type { PluginManifest } from '../common/manifest-types';
+import { prepareLoadedManifest, type PrepareLoadedManifestOptions } from '../common/plugin-manifest';
+
+type LoadedManifest = Pick<PluginManifest, 'name' | 'publisher' | 'contributes' | 'activationEvents'>;
+
+export async function loadManifest<T extends LoadedManifest = PluginManifest>(
+    pluginPath: string,
+    options?: PrepareLoadedManifestOptions
+): Promise<T> {
+    const manifest = await fs.readJson(path.join(pluginPath, 'package.json')) as T;
+    return prepareLoadedManifest(manifest, options);
+}

package/src/node/plugin-model.ts

@@ -0,0 +1,33 @@
+// *****************************************************************************
+// 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 { readdirSync } from 'fs';
+import { toPluginUrl, type PluginIdentifierSource } from '../common/plugin-model';
+
+export function getPluginRootFileUrl(manifest: PluginIdentifierSource & { packagePath: string }, names: string[]): string | undefined {
+    const nameSet = new Set(names.map(n => n.toLowerCase()));
+    try {
+        const dir = readdirSync(manifest.packagePath, { withFileTypes: true });
+        for (const dirent of dir) {
+            if (dirent.isFile() && nameSet.has(dirent.name.toLowerCase())) {
+                return toPluginUrl(manifest, dirent.name);
+            }
+        }
+    } catch {
+        return undefined;
+    }
+    return undefined;
+}

package/src/node/read-grammars.spec.ts

@@ -0,0 +1,128 @@
+// *****************************************************************************
+// 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-extra';
+import * as os from 'os';
+import * as path from 'path';
+import { readGrammarFromDisk, getGrammarContributionValidationError } from './read-grammars';
+
+describe('readGrammarFromDisk', () => {
+
+    let pluginRoot: string;
+
+    beforeEach(async () => {
+        pluginRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'read-grammars-'));
+    });
+
+    afterEach(async () => {
+        await fs.remove(pluginRoot);
+    });
+
+    it('inlines JSON grammar file content', async () => {
+        await fs.writeJson(path.join(pluginRoot, 'sample.tmLanguage.json'), { scopeName: 'source.sample' });
+
+        const grammar = await readGrammarFromDisk({
+            language: 'sample',
+            scopeName: 'source.sample',
+            path: './sample.tmLanguage.json'
+        }, pluginRoot);
+
+        expect(grammar).to.deep.equal({
+            language: 'sample',
+            scope: 'source.sample',
+            format: 'json',
+            grammar: { scopeName: 'source.sample' },
+            grammarLocation: './sample.tmLanguage.json',
+            injectTo: undefined,
+            embeddedLanguages: undefined,
+            tokenTypes: undefined,
+            balancedBracketScopes: undefined,
+            unbalancedBracketScopes: undefined
+        });
+    });
+
+    it('passes through balanced and unbalanced bracket scopes', async () => {
+        await fs.writeJson(path.join(pluginRoot, 'sample.tmLanguage.json'), { scopeName: 'source.sample' });
+
+        const grammar = await readGrammarFromDisk({
+            language: 'sample',
+            scopeName: 'source.sample',
+            path: './sample.tmLanguage.json',
+            balancedBracketScopes: ['*'],
+            unbalancedBracketScopes: ['meta.template.expression']
+        }, pluginRoot);
+
+        expect(grammar!.balancedBracketScopes).to.deep.equal(['*']);
+        expect(grammar!.unbalancedBracketScopes).to.deep.equal(['meta.template.expression']);
+    });
+
+    it('reads plist grammar files as text', async () => {
+        const plist = '<?xml version="1.0"?><plist/>';
+        await fs.writeFile(path.join(pluginRoot, 'sample.tmLanguage'), plist);
+
+        const grammar = await readGrammarFromDisk({
+            scopeName: 'source.sample',
+            path: './sample.tmLanguage'
+        }, pluginRoot);
+
+        expect(grammar!.format).to.equal('plist');
+        expect(grammar!.grammar).to.equal(plist);
+    });
+
+    it('returns undefined for invalid manifest fields and reports via onError', async () => {
+        await fs.writeJson(path.join(pluginRoot, 'sample.tmLanguage.json'), { scopeName: 'source.sample' });
+        const errors: Array<{ type: string; err: unknown }> = [];
+        const onError = (type: string, err: unknown): void => { errors.push({ type, err }); };
+
+        expect(await readGrammarFromDisk({
+            scopeName: '',
+            path: './sample.tmLanguage.json'
+        }, pluginRoot, { onError })).to.equal(undefined);
+
+        expect(await readGrammarFromDisk({
+            scopeName: 'source.sample',
+            path: ''
+        }, pluginRoot, { onError })).to.equal(undefined);
+
+        expect(await readGrammarFromDisk({
+            scopeName: 'source.sample',
+            path: './sample.tmLanguage.json',
+            injectTo: 'text.html.basic' as unknown as string[]
+        }, pluginRoot, { onError })).to.equal(undefined);
+
+        expect(errors).to.have.length(3);
+        expect(errors.every(e => e.type === 'grammars')).to.equal(true);
+        expect(String(errors[0].err)).to.contain('scopeName');
+        expect(String(errors[1].err)).to.contain('path');
+        expect(String(errors[2].err)).to.contain('injectTo');
+    });
+
+    it('rejects grammar paths outside the plugin directory with onError', async () => {
+        expect(getGrammarContributionValidationError({
+            scopeName: 'source.sample',
+            path: '../outside.tmLanguage.json'
+        }, pluginRoot)).to.contain('escapes the plugin directory');
+
+        const errors: unknown[] = [];
+        expect(await readGrammarFromDisk({
+            scopeName: 'source.sample',
+            path: '../outside.tmLanguage.json'
+        }, pluginRoot, { onError: (_type, err) => errors.push(err) })).to.equal(undefined);
+
+        expect(String(errors[0])).to.contain('escapes the plugin directory');
+    });
+});

package/src/node/read-grammars.ts

@@ -0,0 +1,97 @@
+// *****************************************************************************
+// 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 * as path from 'path';
+import * as fs from 'fs-extra';
+import { isObject } from '../common/utils';
+import type {
+    GrammarsContribution,
+    NormalizeContributionsContext,
+    PluginPackageGrammarsContribution,
+} from '../common/contribution-types';
+
+export type { GrammarsContribution } from '../common/contribution-types';
+
+/**
+ * Returns a validation error message, or `undefined` if the contribution is valid.
+ * Mirrors VS Code `validateGrammarExtensionPoint` manifest checks (without language registry lookup),
+ * plus a path-containment guard against escaping the plugin directory.
+ */
+export function getGrammarContributionValidationError(
+    rawGrammar: PluginPackageGrammarsContribution,
+    pluginPath: string
+): string | undefined {
+    if (typeof rawGrammar.scopeName !== 'string' || rawGrammar.scopeName.length === 0) {
+        return `Invalid grammar contribution: 'scopeName' must be a non-empty string (path: ${String(rawGrammar.path)}).`;
+    }
+    if (typeof rawGrammar.path !== 'string' || rawGrammar.path.length === 0) {
+        return `Invalid grammar contribution '${rawGrammar.scopeName}': 'path' must be a non-empty string.`;
+    }
+    if (rawGrammar.language !== undefined && typeof rawGrammar.language !== 'string') {
+        return `Invalid grammar contribution '${rawGrammar.scopeName}': 'language' must be a string when set.`;
+    }
+    if (rawGrammar.injectTo !== undefined
+        && (!Array.isArray(rawGrammar.injectTo) || rawGrammar.injectTo.some(scope => typeof scope !== 'string'))) {
+        return `Invalid grammar contribution '${rawGrammar.scopeName}': 'injectTo' must be a string array when set.`;
+    }
+    if (rawGrammar.embeddedLanguages !== undefined && !isObject(rawGrammar.embeddedLanguages)) {
+        return `Invalid grammar contribution '${rawGrammar.scopeName}': 'embeddedLanguages' must be an object when set.`;
+    }
+    if (rawGrammar.tokenTypes !== undefined && !isObject(rawGrammar.tokenTypes)) {
+        return `Invalid grammar contribution '${rawGrammar.scopeName}': 'tokenTypes' must be an object when set.`;
+    }
+    const resolvedPluginPath = path.resolve(pluginPath);
+    const grammarPath = path.resolve(resolvedPluginPath, rawGrammar.path);
+    const relativePath = path.relative(resolvedPluginPath, grammarPath);
+    if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+        return `Invalid grammar contribution '${rawGrammar.scopeName}': path '${rawGrammar.path}' escapes the plugin directory.`;
+    }
+    return undefined;
+}
+
+export async function readGrammarFromDisk(
+    rawGrammar: PluginPackageGrammarsContribution,
+    pluginPath: string,
+    log?: Pick<NormalizeContributionsContext, 'onError'>
+): Promise<GrammarsContribution | undefined> {
+    const validationError = getGrammarContributionValidationError(rawGrammar, pluginPath);
+    if (validationError) {
+        log?.onError('grammars', validationError);
+        return undefined;
+    }
+
+    let grammar: string | object;
+    const grammarPath = path.resolve(pluginPath, rawGrammar.path);
+
+    if (rawGrammar.path.endsWith('json')) {
+        grammar = await fs.readJson(grammarPath);
+    } else {
+        grammar = await fs.readFile(grammarPath, 'utf8');
+    }
+
+    return {
+        language: rawGrammar.language,
+        scope: rawGrammar.scopeName,
+        format: rawGrammar.path.endsWith('json') ? 'json' : 'plist',
+        grammar,
+        grammarLocation: rawGrammar.path,
+        injectTo: rawGrammar.injectTo,
+        embeddedLanguages: rawGrammar.embeddedLanguages,
+        tokenTypes: rawGrammar.tokenTypes,
+        balancedBracketScopes: rawGrammar.balancedBracketScopes,
+        unbalancedBracketScopes: rawGrammar.unbalancedBracketScopes
+    };
+}