@inlang/sdk 0.1.0

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

@@ -0,0 +1,57 @@
+import { ProjectConfig } from "@inlang/project-config"
+import { Value } from "@sinclair/typebox/value"
+import { describe, test, expect } from "vitest"
+import { expectType } from "tsd"
+import { Plugin } from "@inlang/plugin"
+
+describe("Plugin", () => {
+	test("meta.id should enforce plugin.namespace.* patterns", () => {
+		expectType<`plugin.${string}.${string}`>("" as Plugin["meta"]["id"])
+
+		const mockPlugin: Plugin = {
+			meta: {
+				id: "plugin.namespace.placeholder",
+				displayName: { en: "" },
+				description: { en: "" },
+			},
+		}
+
+		const passCases = ["plugin.namespace.helloWorld", "plugin.namespace.i18n"]
+		const failCases = [
+			"namespace.hello_World",
+			"plugin.namespace-HelloWorld",
+			"lintRule.namespace.coolPlugin",
+		]
+
+		for (const pass of passCases) {
+			mockPlugin.meta.id = pass as any
+
+			// @ts-ignore - type mismatch error. fix after refactor
+			expect(Value.Check(Plugin, mockPlugin)).toBe(true)
+		}
+
+		for (const fail of failCases) {
+			mockPlugin.meta.id = fail as any
+			// @ts-ignore - type mismatch error. fix after refactor
+			expect(Value.Check(Plugin, mockPlugin)).toBe(false)
+		}
+	})
+
+	test("meta.id should be a valid inlang.config.setting key", () => {
+		const mockConfig: ProjectConfig = {
+			sourceLanguageTag: "en",
+			languageTags: ["en", "de"],
+			modules: [],
+			settings: {},
+		}
+		const cases = ["plugin.namespace.helloWorld", "plugin.namespace.i18n"]
+
+		for (const _case of cases) {
+			const config = { ...mockConfig, settings: { [_case]: {} } }
+			// @ts-ignore - type mismatch error. fix after refactor
+			expect(Value.Check(ProjectConfig, config)).toBe(true)
+			// @ts-ignore - type mismatch error. fix after refactor
+			expect(Value.Check(Plugin["properties"]["meta"]["properties"]["id"], _case)).toBe(true)
+		}
+	})
+})

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

@@ -0,0 +1,77 @@
+import type { LanguageTag } from "@inlang/language-tag"
+import type { NodeishFilesystem as LisaNodeishFilesystem } from "@lix-js/fs"
+import type {
+	PluginReturnedInvalidCustomApiError,
+	PluginLoadMessagesFunctionAlreadyDefinedError,
+	PluginSaveMessagesFunctionAlreadyDefinedError,
+	PluginHasInvalidIdError,
+	PluginHasInvalidSchemaError,
+	PluginUsesReservedNamespaceError,
+} from "./errors.js"
+import type { Message } from "@inlang/message"
+import type { JSONObject } from "@inlang/json-types"
+import type { CustomApiInlangIdeExtension, Plugin } from "@inlang/plugin"
+
+/**
+ * The filesystem is a subset of project lisa's nodeish filesystem.
+ *
+ * - only uses minimally required functions to decrease the API footprint on the ecosystem.
+ */
+export type NodeishFilesystemSubset = Pick<
+	LisaNodeishFilesystem,
+	"readFile" | "readdir" | "mkdir" | "writeFile"
+>
+
+/**
+ * Function that resolves (imports and initializes) the plugins.
+ */
+export type ResolvePluginsFunction = (args: {
+	plugins: Array<Plugin>
+	settings: Record<Plugin["meta"]["id"], JSONObject>
+	nodeishFs: NodeishFilesystemSubset
+}) => Promise<{
+	data: ResolvedPluginApi
+	errors: Array<
+		| PluginReturnedInvalidCustomApiError
+		| PluginLoadMessagesFunctionAlreadyDefinedError
+		| PluginSaveMessagesFunctionAlreadyDefinedError
+		| PluginHasInvalidIdError
+		| PluginHasInvalidSchemaError
+		| PluginUsesReservedNamespaceError
+	>
+}>
+
+/**
+ * The API after resolving the plugins.
+ */
+export type ResolvedPluginApi = {
+	loadMessages: (args: {
+		languageTags: LanguageTag[]
+		sourceLanguageTag: LanguageTag
+	}) => Promise<Message[]> | Message[]
+	saveMessages: (args: { messages: Message[] }) => Promise<void> | void
+	/**
+	 * Detect language tags in the project provided plugins.
+	 */
+	detectedLanguageTags: LanguageTag[]
+	/**
+	 * App specific APIs.
+	 *
+	 * @example
+	 *  // define
+	 *  customApi: ({ settings }) => ({
+	 * 	 "app.inlang.ide-extension": {
+	 * 	   messageReferenceMatcher: () => {
+	 * 		 // use settings
+	 * 		 settings.pathPattern
+	 * 		return
+	 * 	   }
+	 * 	 }
+	 *  })
+	 *  // use
+	 *  customApi['app.inlang.ide-extension'].messageReferenceMatcher()
+	 */
+	customApi: Record<`app.${string}.${string}` | `library.${string}.${string}`, unknown> & {
+		"app.inlang.ideExtension"?: CustomApiInlangIdeExtension
+	}
+}

package/src/resolve-modules/resolveModules.test.ts

@@ -0,0 +1,176 @@
+/* eslint-disable @typescript-eslint/no-non-null-assertion */
+import type { MessageLintRule } from "@inlang/message-lint-rule"
+import type { Plugin } from "@inlang/plugin"
+import { expect, it } from "vitest"
+import {
+	ModuleError,
+	ModuleExportIsInvalidError,
+	ModuleHasNoExportsError,
+	ModuleImportError,
+} from "./errors.js"
+import { resolveModules } from "./resolveModules.js"
+import type { ProjectConfig } from "@inlang/project-config"
+import type { InlangModule } from "@inlang/module"
+
+it("should return an error if a plugin cannot be imported", async () => {
+	const config: ProjectConfig = {
+		sourceLanguageTag: "en",
+		languageTags: ["de", "en"],
+		modules: ["https://myplugin.com/index.js"],
+		settings: {},
+	}
+
+	const resolved = await resolveModules({
+		config,
+		nodeishFs: {} as any,
+		_import: () => {
+			throw new ModuleImportError("Could not import", {
+				module: config.modules[0]!,
+				cause: new Error("Could not import"),
+			})
+		},
+	})
+
+	expect(resolved.errors[0]).toBeInstanceOf(ModuleImportError)
+})
+
+it("should resolve plugins and message lint rules successfully", async () => {
+	// Define mock data
+	const mockPlugin: Plugin = {
+		meta: {
+			id: "plugin.namespace.mock",
+			description: { en: "Mock plugin description" },
+			displayName: { en: "Mock Plugin" },
+		},
+		loadMessages: () => undefined as any,
+		saveMessages: () => undefined as any,
+		addCustomApi: () => ({
+			"app.inlang.ideExtension": {
+				messageReferenceMatcher: () => undefined as any,
+			},
+		}),
+	}
+
+	const mockMessageLintRule: MessageLintRule = {
+		meta: {
+			id: "messageLintRule.namespace.mock",
+			description: { en: "Mock lint rule description" },
+			displayName: { en: "Mock Lint Rule" },
+		},
+		message: () => undefined,
+	}
+
+	const config: ProjectConfig = {
+		sourceLanguageTag: "en",
+		languageTags: ["de", "en"],
+		modules: ["lint-rule.js", "plugin.js"],
+		settings: {},
+	}
+
+	const _import = async (name: string) => {
+		if (name === "lint-rule.js") {
+			return {
+				default: mockMessageLintRule,
+			}
+		} else {
+			return {
+				default: mockPlugin,
+			}
+		}
+	}
+
+	// Call the function
+	const resolved = await resolveModules({ config, _import, nodeishFs: {} as any })
+
+	// Assert results
+	expect(resolved.errors).toHaveLength(0)
+	// Check for the meta data of the plugin
+	expect(resolved.plugins.some((module) => module.meta.id === mockPlugin.meta.id)).toBeDefined()
+	// Check for the app specific api
+	expect(resolved.resolvedPluginApi["customApi"]?.["app.inlang.ideExtension"]).toBeDefined()
+	// Check for the lint rule
+	expect(resolved.messageLintRules[0]?.meta.id).toBe(mockMessageLintRule.meta.id)
+})
+
+it("should return an error if a module cannot be imported", async () => {
+	const config: ProjectConfig = {
+		sourceLanguageTag: "en",
+		languageTags: ["de", "en"],
+		modules: ["https://myplugin.com/index.js"],
+		settings: {},
+	}
+
+	const _import = async () => {
+		throw new ModuleImportError("Could not import", {
+			module: config.modules[0]!,
+			cause: new Error(),
+		})
+	}
+
+	// Call the function
+	const resolved = await resolveModules({ config, _import, nodeishFs: {} as any })
+
+	// Assert results
+	expect(resolved.errors[0]).toBeInstanceOf(ModuleImportError)
+})
+
+it("should return an error if a module does not export any plugins or lint rules", async () => {
+	const config: ProjectConfig = {
+		sourceLanguageTag: "en",
+		languageTags: ["de", "en"],
+		modules: ["https://myplugin.com/index.js"],
+		settings: {},
+	}
+
+	const _import = async () => ({
+		default: {},
+	})
+
+	// Call the function
+	const resolved = await resolveModules({ config, _import, nodeishFs: {} as any })
+
+	// Assert results
+	expect(resolved.errors[0]).toBeInstanceOf(ModuleHasNoExportsError)
+})
+
+it("should return an error if a module exports an invalid plugin or lint rule", async () => {
+	const config: ProjectConfig = {
+		sourceLanguageTag: "en",
+		languageTags: ["de", "en"],
+		modules: ["https://myplugin.com/index.js"],
+		settings: {},
+	}
+	const _import = async () =>
+		({
+			default: {
+				// @ts-expect-error - invalid meta of a plugin
+				meta: {
+					id: "plugin.namespace.mock",
+					description: { en: "Mock plugin description" },
+				},
+			},
+		} satisfies InlangModule)
+
+	const resolved = await resolveModules({ config, _import, nodeishFs: {} as any })
+	expect(resolved.errors[0]).toBeInstanceOf(ModuleExportIsInvalidError)
+})
+
+it("should handle other unhandled errors during plugin resolution", async () => {
+	const errorMessage = "Unhandled error during plugin resolution"
+	const config: ProjectConfig = {
+		sourceLanguageTag: "en",
+		languageTags: ["de", "en"],
+		modules: ["https://myplugin.com/index.js"],
+		settings: {},
+	}
+
+	const _import = async () => {
+		throw new Error(errorMessage)
+	}
+
+	// Call the function
+	const resolved = await resolveModules({ config, _import, nodeishFs: {} as any })
+
+	// Assert results
+	expect(resolved.errors[0]).toBeInstanceOf(ModuleError)
+})

package/src/resolve-modules/resolveModules.ts

@@ -0,0 +1,97 @@
+import type { ResolveModuleFunction } from "./types.js"
+import { InlangModule } from "@inlang/module"
+import {
+	ModuleError,
+	ModuleImportError,
+	ModuleHasNoExportsError,
+	ModuleExportIsInvalidError,
+} from "./errors.js"
+import { tryCatch } from "@inlang/result"
+import { resolveMessageLintRules } from "./message-lint-rules/resolveMessageLintRules.js"
+import type { Plugin } from "@inlang/plugin"
+import { createImport } from "./import.js"
+import type { MessageLintRule } from "@inlang/message-lint-rule"
+import { resolvePlugins } from "./plugins/resolvePlugins.js"
+import { TypeCompiler } from "@sinclair/typebox/compiler"
+
+const ModuleCompiler = TypeCompiler.Compile(InlangModule)
+
+export const resolveModules: ResolveModuleFunction = async (args) => {
+	const _import = args._import ?? createImport({ readFile: args.nodeishFs.readFile, fetch })
+	const moduleErrors: Array<ModuleError> = []
+
+	const allPlugins: Array<Plugin> = []
+	const allMessageLintRules: Array<MessageLintRule> = []
+
+	const meta: Awaited<ReturnType<ResolveModuleFunction>>["meta"] = []
+
+	for (const module of args.config.modules) {
+		/**
+		 * -------------- BEGIN SETUP --------------
+		 */
+
+		const importedModule = await tryCatch<InlangModule>(() => _import(module))
+
+		// -- IMPORT MODULE --
+		if (importedModule.error) {
+			moduleErrors.push(
+				new ModuleImportError(`Couldn't import the plugin "${module}"`, {
+					module: module,
+					cause: importedModule.error as Error,
+				}),
+			)
+			continue
+		}
+
+		// -- MODULE DOES NOT EXPORT PLUGINS OR LINT RULES --
+		if (importedModule.data?.default?.meta?.id === undefined) {
+			moduleErrors.push(
+				new ModuleHasNoExportsError(`Module "${module}" has no exports.`, {
+					module: module,
+				}),
+			)
+			continue
+		}
+
+		const isValidModule = ModuleCompiler.Check(importedModule.data)
+
+		if (isValidModule === false) {
+			const errors = [...ModuleCompiler.Errors(importedModule.data)]
+			moduleErrors.push(
+				new ModuleExportIsInvalidError(`Module "${module}" is invalid: ` + errors, {
+					module: module,
+				}),
+			)
+			continue
+		}
+
+		meta.push({
+			module: module,
+			id: importedModule.data.default.meta.id,
+		})
+
+		if (importedModule.data.default.meta.id.startsWith("plugin.")) {
+			allPlugins.push(importedModule.data.default as Plugin)
+		} else if (importedModule.data.default.meta.id.startsWith("messageLintRule.")) {
+			allMessageLintRules.push(importedModule.data.default as MessageLintRule)
+		} else {
+			throw new Error(`Unimplemented module type. Must start with "plugin." or "messageLintRule.`)
+		}
+	}
+
+	const resolvedPlugins = await resolvePlugins({
+		plugins: allPlugins,
+		settings: args.config.settings as any, // TODO: fix type
+		nodeishFs: args.nodeishFs,
+	})
+
+	const resolvedLintRules = resolveMessageLintRules({ messageLintRules: allMessageLintRules })
+
+	return {
+		meta,
+		messageLintRules: allMessageLintRules,
+		plugins: allPlugins,
+		resolvedPluginApi: resolvedPlugins.data,
+		errors: [...moduleErrors, ...resolvedLintRules.errors, ...resolvedPlugins.errors],
+	}
+}

package/src/resolve-modules/types.ts

@@ -0,0 +1,71 @@
+import type { ProjectConfig } from "@inlang/project-config"
+import type { MessageLintRule } from "@inlang/message-lint-rule"
+import type { Plugin } from "@inlang/plugin"
+import type {
+	NodeishFilesystemSubset,
+	ResolvePluginsFunction,
+	ResolvedPluginApi,
+} from "./plugins/types.js"
+import type { ModuleHasNoExportsError, ModuleImportError } from "./errors.js"
+import type { ImportFunction } from "./import.js"
+import type { resolveMessageLintRules } from "./message-lint-rules/resolveMessageLintRules.js"
+
+/**
+ * Function that resolves modules from the config.
+ *
+ * Pass a custom `_import` function to override the default import function.
+ */
+export type ResolveModuleFunction = (args: {
+	config: ProjectConfig
+	nodeishFs: NodeishFilesystemSubset
+	_import?: ImportFunction
+}) => Promise<{
+	/**
+	 * Metadata about the resolved module.
+	 *
+	 * @example
+	 * [{
+	 * 	  id: "plugin.inlang.json",
+	 * 	  module: "https://myplugin.com/index.js"
+	 * }]
+	 */
+	meta: Array<{
+		/**
+		 * The module link.
+		 *
+		 * @example "https://myplugin.com/index.js"
+		 */
+		module: string
+		/**
+		 * The resolved item id of the module.
+		 */
+		id: Plugin["meta"]["id"] | MessageLintRule["meta"]["id"]
+	}>
+	/**
+	 * The resolved plugins.
+	 */
+	plugins: Array<Plugin>
+	/**
+	 * The resolved message lint rules.
+	 */
+	messageLintRules: Array<MessageLintRule>
+	/**
+	 * The resolved api provided by plugins.
+	 */
+	resolvedPluginApi: ResolvedPluginApi
+	/**
+	 * Errors during the resolution process.
+	 *
+	 * This includes errors from:
+	 * - importing module
+	 * - resolving plugins
+	 * - resolving lint rules
+	 * - resolving the runtime plugin api
+	 */
+	errors: Array<
+		| ModuleHasNoExportsError
+		| ModuleImportError
+		| Awaited<ReturnType<ResolvePluginsFunction>>["errors"][number]
+		| Awaited<ReturnType<typeof resolveMessageLintRules>>["errors"][number]
+	>
+}>

package/src/test-utilities/createMessage.test.ts

@@ -0,0 +1,100 @@
+import { expect, test } from "vitest"
+import { createMessage } from "./createMessage.js"
+
+test("should create a simple message", () => {
+	expect(
+		createMessage("welcome", {
+			de: "Hallo inlang",
+		}),
+	).toMatchInlineSnapshot(`
+		{
+		  "id": "welcome",
+		  "selectors": [],
+		  "variants": [
+		    {
+		      "languageTag": "de",
+		      "match": {},
+		      "pattern": [
+		        {
+		          "type": "Text",
+		          "value": "Hallo inlang",
+		        },
+		      ],
+		    },
+		  ],
+		}
+	`)
+})
+
+test("should create a message with pattern", () => {
+	expect(
+		createMessage("greeting", {
+			en: [
+				{ type: "Text", value: "Hi " },
+				{ type: "VariableReference", name: "name" },
+				{ type: "Text", value: '"' },
+			],
+		}),
+	).toMatchInlineSnapshot(`
+			{
+			  "id": "greeting",
+			  "selectors": [],
+			  "variants": [
+			    {
+			      "languageTag": "en",
+			      "match": {},
+			      "pattern": [
+			        {
+			          "type": "Text",
+			          "value": "Hi ",
+			        },
+			        {
+			          "name": "name",
+			          "type": "VariableReference",
+			        },
+			        {
+			          "type": "Text",
+			          "value": "\\"",
+			        },
+			      ],
+			    },
+			  ],
+			}
+		`)
+})
+
+test("should create a message with a pattern", () => {
+	expect(
+		createMessage("welcome", {
+			en: "hello inlang",
+			de: [{ type: "Text", value: "Hallo inlang" }],
+		}),
+	).toMatchInlineSnapshot(`
+			{
+			  "id": "welcome",
+			  "selectors": [],
+			  "variants": [
+			    {
+			      "languageTag": "en",
+			      "match": {},
+			      "pattern": [
+			        {
+			          "type": "Text",
+			          "value": "hello inlang",
+			        },
+			      ],
+			    },
+			    {
+			      "languageTag": "de",
+			      "match": {},
+			      "pattern": [
+			        {
+			          "type": "Text",
+			          "value": "Hallo inlang",
+			        },
+			      ],
+			    },
+			  ],
+			}
+		`)
+})

package/src/test-utilities/createMessage.ts

@@ -0,0 +1,20 @@
+import type { Message, Pattern } from "@inlang/message"
+
+export const createMessage = (id: string, patterns: Record<string, Pattern | string>) =>
+	({
+		id,
+		selectors: [],
+		variants: Object.entries(patterns).map(([languageTag, patterns]) => ({
+			languageTag,
+			match: {},
+			pattern:
+				typeof patterns === "string"
+					? [
+							{
+								type: "Text",
+								value: patterns,
+							},
+					  ]
+					: patterns,
+		})),
+	} satisfies Message)

package/src/test-utilities/index.ts

@@ -0,0 +1 @@
+export { createMessage } from "./createMessage.js"

package/src/versionedInterfaces.ts

@@ -0,0 +1,9 @@
+// Re-exporting for easier importing
+
+export * from "@inlang/json-types"
+export * from "@inlang/language-tag"
+export * from "@inlang/message-lint-rule"
+export * from "@inlang/message"
+export * from "@inlang/plugin"
+export * from "@inlang/project-config"
+export * from "@inlang/translatable"