@inlang/sdk 0.1.0

package/src/resolve-modules/import.ts

@@ -0,0 +1,69 @@
+import { dedent } from "ts-dedent"
+import { normalizePath } from "@lix-js/fs"
+import type { NodeishFilesystemSubset } from "@inlang/plugin"
+import { ModuleImportError } from "./errors.js"
+
+/**
+ * Importing ES modules either from a local path, or from a url.
+ *
+ * - Name the import function `_import` to avoid shadowing the
+ *   native import function.
+ */
+export type ImportFunction = (uri: string) => Promise<any>
+
+/**
+ * Creates the import function.
+ *
+ * This function is required to import modules from a local path.
+ *
+ * @example
+ *   const $import = createImport({ readFile: fs.readFile, fetch });
+ *   const module = await _import('./some-module.js');
+ */
+export function createImport(args: {
+	/** the fs from which the file can be read */
+	readFile: NodeishFilesystemSubset["readFile"]
+	/** http client implementation */
+	fetch: typeof fetch
+}): (uri: string) => ReturnType<typeof $import> {
+	// resembles a native import api
+	return (uri: string) => $import(uri, args)
+}
+
+async function $import(
+	uri: string,
+	options: {
+		/**
+		 * Required to import from a local path.
+		 */
+		readFile: NodeishFilesystemSubset["readFile"]
+		/**
+		 * Required to import via network.
+		 */
+		fetch: typeof fetch
+	},
+): Promise<any> {
+	let moduleAsText: string
+
+	if (uri.startsWith("http")) {
+		moduleAsText = await (await options.fetch(uri)).text()
+	} else {
+		moduleAsText = await options.readFile(normalizePath(uri), { encoding: "utf-8" })
+	}
+
+	const moduleWithMimeType = "data:application/javascript," + encodeURIComponent(moduleAsText)
+
+	try {
+		return await import(/* @vite-ignore */ moduleWithMimeType)
+	} catch (error) {
+		let message = `Error while importing ${uri}: ${(error as Error)?.message ?? "Unknown error"}`
+		if (error instanceof SyntaxError && uri.includes("jsdelivr")) {
+			message += dedent`\n\n
+Are you sure that the file exists on JSDelivr?
+
+The error indicates that the imported file does not exist on JSDelivr. For non-existent files, JSDelivr returns a 404 text that JS cannot parse as a module and throws a SyntaxError.
+			`
+		}
+		throw new ModuleImportError(message, { module: uri, cause: error as Error })
+	}
+}

package/src/resolve-modules/index.ts

@@ -0,0 +1,2 @@
+export { resolveModules } from "./resolveModules.js"
+export { type ImportFunction, createImport } from "./import.js"

package/src/resolve-modules/message-lint-rules/errors.ts

@@ -0,0 +1,9 @@
+export class MessageLintRuleIsInvalidError extends Error {
+	public readonly module: string
+
+	constructor(message: string, options: { module: string; cause?: Error }) {
+		super(message)
+		this.module = options.module
+		this.name = "MessageLintRuleIsInvalidError"
+	}
+}

package/src/resolve-modules/message-lint-rules/resolveMessageLintRules.ts

@@ -0,0 +1,24 @@
+import { Value } from "@sinclair/typebox/value"
+import { MessageLintRule } from "@inlang/message-lint-rule"
+import { MessageLintRuleIsInvalidError } from "./errors.js"
+
+export const resolveMessageLintRules = (args: { messageLintRules: Array<MessageLintRule> }) => {
+	const result = {
+		data: [] as Array<MessageLintRule>,
+		errors: [] as MessageLintRuleIsInvalidError[],
+	}
+	for (const rule of args.messageLintRules) {
+		if (Value.Check(MessageLintRule, rule) === false) {
+			result.errors.push(
+				new MessageLintRuleIsInvalidError(`Couldn't parse lint rule "${rule.meta.id}"`, {
+					module: "not implemented",
+				}),
+			)
+			continue
+		} else {
+			result.data.push(rule)
+		}
+	}
+
+	return result
+}

package/src/resolve-modules/plugins/errors.ts

@@ -0,0 +1,57 @@
+import type { Plugin } from "@inlang/plugin"
+
+type PluginErrorOptions = {
+	plugin: Plugin["meta"]["id"]
+} & Partial<Error>
+
+class PluginError extends Error {
+	public readonly plugin: string
+
+	constructor(message: string, options: PluginErrorOptions) {
+		super(message)
+		this.name = "PluginError"
+		this.plugin = options.plugin
+	}
+}
+
+export class PluginHasInvalidIdError extends PluginError {
+	constructor(message: string, options: PluginErrorOptions) {
+		super(message, options)
+		this.name = "PluginHasInvalidIdError"
+	}
+}
+
+export class PluginUsesReservedNamespaceError extends PluginError {
+	constructor(message: string, options: PluginErrorOptions) {
+		super(message, options)
+		this.name = "PluginUsesReservedNamespaceError"
+	}
+}
+
+export class PluginHasInvalidSchemaError extends PluginError {
+	constructor(message: string, options: PluginErrorOptions) {
+		super(message, options)
+		this.name = "PluginHasInvalidSchemaError"
+	}
+}
+
+export class PluginLoadMessagesFunctionAlreadyDefinedError extends PluginError {
+	constructor(message: string, options: PluginErrorOptions) {
+		super(message, options)
+		this.name = "PluginLoadMessagesFunctionAlreadyDefinedError"
+	}
+}
+
+export class PluginSaveMessagesFunctionAlreadyDefinedError extends PluginError {
+	constructor(message: string, options: PluginErrorOptions) {
+		super(message, options)
+		this.name = "PluginSaveMessagesFunctionAlreadyDefinedError"
+	}
+}
+
+export class PluginReturnedInvalidCustomApiError extends PluginError {
+	constructor(message: string, options: PluginErrorOptions) {
+		super(message, options)
+		this.name = "PluginReturnedInvalidCustomApiError"
+	}
+}

package/src/resolve-modules/plugins/resolvePlugins.test.ts

@@ -0,0 +1,340 @@
+/* eslint-disable @typescript-eslint/no-non-null-assertion */
+import { describe, expect, it } from "vitest"
+import { resolvePlugins } from "./resolvePlugins.js"
+import {
+	PluginLoadMessagesFunctionAlreadyDefinedError,
+	PluginSaveMessagesFunctionAlreadyDefinedError,
+	PluginHasInvalidIdError,
+	PluginUsesReservedNamespaceError,
+	PluginReturnedInvalidCustomApiError,
+	PluginHasInvalidSchemaError,
+} from "./errors.js"
+import type { Plugin } from "@inlang/plugin"
+
+describe("generally", () => {
+	it("should return an error if a plugin uses an invalid id", async () => {
+		const mockPlugin: Plugin = {
+			meta: {
+				// @ts-expect-error - invalid id
+				id: "no-namespace",
+				description: { en: "My plugin description" },
+				displayName: { en: "My plugin" },
+			},
+			loadMessages: () => undefined as any,
+			saveMessages: () => undefined as any,
+			addCustomApi() {
+				return {}
+			},
+		}
+
+		const resolved = await resolvePlugins({
+			plugins: [mockPlugin],
+			settings: {},
+			nodeishFs: {} as any,
+		})
+
+		expect(resolved.errors[0]).toBeInstanceOf(PluginHasInvalidIdError)
+	})
+
+	it("should return an error if a plugin uses APIs that are not available", async () => {
+		const mockPlugin: Plugin = {
+			meta: {
+				id: "plugin.namespace.undefinedApi",
+				description: { en: "My plugin description" },
+				displayName: { en: "My plugin" },
+			},
+			// @ts-expect-error the key is not available in type
+			nonExistentKey: {
+				nonexistentOptions: "value",
+			},
+			loadMessages: () => undefined as any,
+			saveMessages: () => undefined as any,
+		}
+
+		const resolved = await resolvePlugins({
+			plugins: [mockPlugin],
+			settings: {},
+			nodeishFs: {} as any,
+		})
+
+		expect(resolved.errors.length).toBe(1)
+		expect(resolved.errors[0]).toBeInstanceOf(PluginHasInvalidSchemaError)
+	})
+
+	it("should not initialize a plugin that uses the 'inlang' namespace except for inlang whitelisted plugins", async () => {
+		const mockPlugin: Plugin = {
+			meta: {
+				id: "plugin.inlang.notWhitelisted",
+				description: { en: "My plugin description" },
+				displayName: { en: "My plugin" },
+			},
+			loadMessages: () => undefined as any,
+		}
+
+		const resolved = await resolvePlugins({
+			plugins: [mockPlugin],
+			settings: {},
+			nodeishFs: {} as any,
+		})
+
+		expect(resolved.errors.length).toBe(1)
+		expect(resolved.errors[0]).toBeInstanceOf(PluginUsesReservedNamespaceError)
+	})
+})
+
+describe("loadMessages", () => {
+	it("should load messages from a local source", async () => {
+		const mockPlugin: Plugin = {
+			meta: {
+				id: "plugin.namespace.placeholder",
+				description: { en: "My plugin description" },
+				displayName: { en: "My plugin" },
+			},
+			loadMessages: async () => [{ id: "test", expressions: [], selectors: [], variants: [] }],
+		}
+
+		const resolved = await resolvePlugins({
+			plugins: [mockPlugin],
+			settings: {},
+			nodeishFs: {} as any,
+		})
+
+		expect(
+			await resolved.data.loadMessages!({
+				languageTags: ["en"],
+				sourceLanguageTag: "en",
+			}),
+		).toEqual([{ id: "test", expressions: [], selectors: [], variants: [] }])
+	})
+
+	it("should collect an error if function is defined twice in multiple plugins", async () => {
+		const mockPlugin: Plugin = {
+			meta: {
+				id: "plugin.namepsace.loadMessagesFirst",
+				description: { en: "My plugin description" },
+				displayName: { en: "My plugin" },
+			},
+			loadMessages: async () => undefined as any,
+		}
+		const mockPlugin2: Plugin = {
+			meta: {
+				id: "plugin.namepsace.loadMessagesSecond",
+				description: { en: "My plugin description" },
+				displayName: { en: "My plugin" },
+			},
+			loadMessages: async () => undefined as any,
+		}
+
+		const resolved = await resolvePlugins({
+			plugins: [mockPlugin, mockPlugin2],
+			nodeishFs: {} as any,
+			settings: {},
+		})
+
+		expect(resolved.errors).toHaveLength(1)
+		expect(resolved.errors[0]).toBeInstanceOf(PluginLoadMessagesFunctionAlreadyDefinedError)
+	})
+})
+
+describe("saveMessages", () => {
+	it("should save messages to a local source", async () => {
+		const mockPlugin: Plugin = {
+			meta: {
+				id: "plugin.namespace.placeholder",
+				description: { en: "My plugin description" },
+				displayName: { en: "My plugin" },
+			},
+			saveMessages: async () => undefined as any,
+		}
+
+		const resolved = await resolvePlugins({
+			plugins: [mockPlugin],
+			nodeishFs: {} as any,
+			settings: {},
+		})
+
+		expect(resolved.errors).toHaveLength(0)
+	})
+
+	it("should collect an error if function is defined twice in multiple plugins", async () => {
+		const mockPlugin: Plugin = {
+			meta: {
+				id: "plugin.namepsace.saveMessages",
+				description: { en: "My plugin description" },
+				displayName: { en: "My plugin" },
+			},
+			saveMessages: async () => undefined as any,
+		}
+		const mockPlugin2: Plugin = {
+			meta: {
+				id: "plugin.namepsace.saveMessages2",
+				description: { en: "My plugin description" },
+				displayName: { en: "My plugin" },
+			},
+
+			saveMessages: async () => undefined as any,
+		}
+
+		const resolved = await resolvePlugins({
+			plugins: [mockPlugin, mockPlugin2],
+			settings: {},
+			nodeishFs: {} as any,
+		})
+
+		expect(resolved.errors).toHaveLength(1)
+		expect(resolved.errors[0]).toBeInstanceOf(PluginSaveMessagesFunctionAlreadyDefinedError)
+	})
+})
+
+describe("detectedLanguageTags", () => {
+	it("should merge language tags from plugins", async () => {
+		const mockPlugin: Plugin = {
+			meta: {
+				id: "plugin.namepsace.detectedLanguageTags",
+				description: { en: "My plugin description" },
+				displayName: { en: "My plugin" },
+			},
+			detectedLanguageTags: async () => ["de", "en"],
+			addCustomApi: () => {
+				return {}
+			},
+		}
+		const mockPlugin2: Plugin = {
+			meta: {
+				id: "plugin.namepsace.detectedLanguageTags2",
+				description: { en: "My plugin description" },
+				displayName: { en: "My plugin" },
+			},
+			addCustomApi: () => {
+				return {}
+			},
+			detectedLanguageTags: async () => ["de", "fr"],
+		}
+
+		const resolved = await resolvePlugins({
+			plugins: [mockPlugin, mockPlugin2],
+			settings: {},
+			nodeishFs: {} as any,
+		})
+
+		expect(resolved.data.detectedLanguageTags).toEqual(["de", "en", "fr"])
+	})
+})
+
+describe("addCustomApi", () => {
+	it("it should resolve app specific api", async () => {
+		const mockPlugin: Plugin = {
+			meta: {
+				id: "plugin.namespace.placeholder",
+				description: { en: "My plugin description" },
+				displayName: { en: "My plugin" },
+			},
+
+			addCustomApi: () => ({
+				"my-app": {
+					messageReferenceMatcher: () => undefined as any,
+				},
+			}),
+		}
+
+		const resolved = await resolvePlugins({
+			plugins: [mockPlugin],
+			settings: {},
+			nodeishFs: {} as any,
+		})
+
+		expect(resolved.data.customApi).toHaveProperty("my-app")
+	})
+
+	it("it should resolve multiple app specific apis", async () => {
+		const mockPlugin: Plugin = {
+			meta: {
+				id: "plugin.namespace.placeholder",
+				description: { en: "My plugin description" },
+				displayName: { en: "My plugin" },
+			},
+			addCustomApi: () => ({
+				"my-app-1": {
+					functionOfMyApp1: () => undefined as any,
+				},
+				"my-app-2": {
+					functionOfMyApp2: () => undefined as any,
+				},
+			}),
+		}
+		const mockPlugin2: Plugin = {
+			meta: {
+				id: "plugin.namespace.placeholder2",
+				description: { en: "My plugin description" },
+				displayName: { en: "My plugin" },
+			},
+
+			addCustomApi: () => ({
+				"my-app-3": {
+					functionOfMyApp3: () => undefined as any,
+				},
+			}),
+		}
+
+		const resolved = await resolvePlugins({
+			plugins: [mockPlugin, mockPlugin2],
+			settings: {},
+			nodeishFs: {} as any,
+		})
+
+		expect(resolved.data.customApi).toHaveProperty("my-app-1")
+		expect(resolved.data.customApi).toHaveProperty("my-app-2")
+		expect(resolved.data.customApi).toHaveProperty("my-app-3")
+	})
+
+	it("it should throw an error if return value is not an object", async () => {
+		const mockPlugin: Plugin = {
+			meta: {
+				id: "plugin.namespace.placeholder",
+				description: { en: "My plugin description" },
+				displayName: { en: "My plugin" },
+			},
+			// @ts-expect-error - invalid return type
+			addCustomApi: () => undefined,
+		}
+
+		const resolved = await resolvePlugins({
+			plugins: [mockPlugin],
+			settings: {},
+			nodeishFs: {} as any,
+		})
+
+		expect(resolved.errors).toHaveLength(1)
+		expect(resolved.errors[0]).toBeInstanceOf(PluginReturnedInvalidCustomApiError)
+	})
+
+	it("it should throw an error if the passed options are not defined inside customApi", async () => {
+		const mockPlugin: Plugin = {
+			meta: {
+				id: "plugin.namepsace.placeholder",
+				description: { en: "My plugin description" },
+				displayName: { en: "My plugin" },
+			},
+			addCustomApi: () => ({
+				"app.inlang.placeholder": {
+					messageReferenceMatcher: () => {
+						return { hello: "world" }
+					},
+				},
+			}),
+		}
+
+		const resolved = await resolvePlugins({
+			plugins: [mockPlugin],
+			settings: {},
+			nodeishFs: {} as any,
+		})
+
+		expect(resolved.data.customApi).toHaveProperty("app.inlang.placeholder")
+		expect(
+			(resolved.data.customApi?.["app.inlang.placeholder"] as any).messageReferenceMatcher(),
+		).toEqual({
+			hello: "world",
+		})
+	})
+})

package/src/resolve-modules/plugins/resolvePlugins.ts

@@ -0,0 +1,170 @@
+/* eslint-disable @typescript-eslint/no-non-null-assertion */
+import type { ResolvePluginsFunction } from "./types.js"
+import { Plugin } from "@inlang/plugin"
+import {
+	PluginReturnedInvalidCustomApiError,
+	PluginLoadMessagesFunctionAlreadyDefinedError,
+	PluginSaveMessagesFunctionAlreadyDefinedError,
+	PluginHasInvalidIdError,
+	PluginHasInvalidSchemaError,
+	PluginUsesReservedNamespaceError,
+} from "./errors.js"
+import { deepmerge } from "deepmerge-ts"
+import { TypeCompiler } from "@sinclair/typebox/compiler"
+import { tryCatch } from "@inlang/result"
+
+const whitelistedPlugins = [
+	"plugin.inlang.json",
+	"plugin.inlang.i18next",
+	"plugin.inlang.paraglideJs",
+]
+// @ts-ignore - type mismatch error
+const PluginCompiler = TypeCompiler.Compile(Plugin)
+
+export const resolvePlugins: ResolvePluginsFunction = async (args) => {
+	const result: Awaited<ReturnType<ResolvePluginsFunction>> = {
+		data: {
+			loadMessages: undefined as any,
+			saveMessages: undefined as any,
+			detectedLanguageTags: [],
+			customApi: {},
+		},
+		errors: [],
+	}
+
+	for (const plugin of args.plugins) {
+		const errors = [...PluginCompiler.Errors(plugin)]
+
+		/**
+		 * -------------- RESOLVE PLUGIN --------------
+		 */
+
+		// -- INVALID ID in META --
+		const hasInvalidId = errors.some((error) => error.path === "/meta/id")
+		if (hasInvalidId) {
+			result.errors.push(
+				new PluginHasInvalidIdError(
+					`Plugin ${plugin.meta.id} has an invalid id "${plugin.meta.id}". It must be kebap-case and contain a namespace like project.my-plugin.`,
+					{ plugin: plugin.meta.id },
+				),
+			)
+		}
+
+		// -- USES RESERVED NAMESPACE --
+		if (plugin.meta.id.includes("inlang") && !whitelistedPlugins.includes(plugin.meta.id)) {
+			result.errors.push(
+				new PluginUsesReservedNamespaceError(
+					`Plugin ${plugin.meta.id} uses reserved namespace 'inlang'.`,
+					{
+						plugin: plugin.meta.id,
+					},
+				),
+			)
+		}
+
+		// -- USES INVALID SCHEMA --
+		if (errors.length > 0) {
+			result.errors.push(
+				new PluginHasInvalidSchemaError(
+					`Plugin ${plugin.meta.id} uses an invalid schema. Please check the documentation for the correct Plugin type.`,
+					{
+						plugin: plugin.meta.id,
+						cause: errors,
+					},
+				),
+			)
+		}
+
+		// -- ALREADY DEFINED LOADMESSAGES / SAVEMESSAGES / DETECTEDLANGUAGETAGS --
+		if (typeof plugin.loadMessages === "function" && result.data.loadMessages !== undefined) {
+			result.errors.push(
+				new PluginLoadMessagesFunctionAlreadyDefinedError(
+					`Plugin ${plugin.meta.id} defines the loadMessages function, but it was already defined by another plugin.`,
+					{ plugin: plugin.meta.id },
+				),
+			)
+		}
+
+		if (typeof plugin.saveMessages === "function" && result.data.saveMessages !== undefined) {
+			result.errors.push(
+				new PluginSaveMessagesFunctionAlreadyDefinedError(
+					`Plugin ${plugin.meta.id} defines the saveMessages function, but it was already defined by another plugin.`,
+					{ plugin: plugin.meta.id },
+				),
+			)
+		}
+
+		// --- ADD APP SPECIFIC API ---
+		if (typeof plugin.addCustomApi === "function") {
+			// TODO: why do we call this function 2 times (here for validation and later for retrieving the actual value)?
+			const { data: customApi, error } = tryCatch(() =>
+				plugin.addCustomApi!({
+					settings: args.settings?.[plugin.meta.id] ?? {},
+				}),
+			)
+			if (error) {
+				// @ts-ignore
+				delete error.stack
+				result.errors.push(error as any) // TODO: add correct error type
+			}
+			if (typeof customApi !== "object") {
+				result.errors.push(
+					new PluginReturnedInvalidCustomApiError(
+						`Plugin ${plugin.meta.id} defines the addCustomApi function, but it does not return an object.`,
+						{ plugin: plugin.meta.id, cause: error },
+					),
+				)
+			}
+		}
+
+		// -- CONTINUE IF ERRORS --
+		if (result.errors.length > 0) {
+			continue
+		}
+
+		/**
+		 * -------------- BEGIN ADDING TO RESULT --------------
+		 */
+
+		if (typeof plugin.loadMessages === "function") {
+			result.data.loadMessages = (_args) =>
+				plugin.loadMessages!({
+					..._args,
+					settings: args.settings?.[plugin.meta.id] ?? {},
+					nodeishFs: args.nodeishFs,
+				})
+		}
+
+		if (typeof plugin.saveMessages === "function") {
+			result.data.saveMessages = (_args) =>
+				plugin.saveMessages!({
+					..._args,
+					settings: args.settings?.[plugin.meta.id] ?? {},
+					nodeishFs: args.nodeishFs,
+				})
+		}
+
+		if (typeof plugin.detectedLanguageTags === "function") {
+			const detectedLangugeTags = await plugin.detectedLanguageTags!({
+				settings: args.settings?.[plugin.meta.id] ?? {},
+				nodeishFs: args.nodeishFs,
+			})
+			result.data.detectedLanguageTags = [
+				...new Set([...result.data.detectedLanguageTags, ...detectedLangugeTags]),
+			]
+		}
+
+		if (typeof plugin.addCustomApi === "function") {
+			const { data: customApi } = tryCatch(() =>
+				plugin.addCustomApi!({
+					settings: args.settings?.[plugin.meta.id] ?? {},
+				}),
+			)
+			if (customApi) {
+				result.data.customApi = deepmerge(result.data.customApi, customApi)
+			}
+		}
+	}
+
+	return result
+}