@inlang/sdk 0.22.0 → 0.24.0

package/src/loadProject.ts

@@ -23,12 +23,13 @@ import { ProjectSettings, Message, type NodeishFilesystemSubset } from "./versio
 import { tryCatch, type Result } from "@inlang/result"
 import { migrateIfOutdated } from "@inlang/project-settings/migration"
 import { createNodeishFsWithAbsolutePaths } from "./createNodeishFsWithAbsolutePaths.js"
-import { normalizePath, type NodeishFilesystem } from "@lix-js/fs"
+import { normalizePath } from "@lix-js/fs"
 import { isAbsolutePath } from "./isAbsolutePath.js"
 import { createNodeishFsWithWatcher } from "./createNodeishFsWithWatcher.js"
 import { maybeMigrateToDirectory } from "./migrations/migrateToDirectory.js"
+import { maybeCreateFirstProjectId } from "./migrations/maybeCreateFirstProjectId.js"
 import type { Repository } from "@lix-js/client"
-import { generateProjectId } from "./generateProjectId.js"
+import { capture } from "./telemetry/capture.js"
 
 const settingsCompiler = TypeCompiler.Compile(ProjectSettings)
 
@@ -36,24 +37,49 @@ const settingsCompiler = TypeCompiler.Compile(ProjectSettings)
  * Creates an inlang instance.
  *
  * @param projectPath - Absolute path to the inlang settings file.
- * @param nodeishFs - Filesystem that implements the NodeishFilesystemSubset interface.
+ * @param @deprecated nodeishFs - Filesystem that implements the NodeishFilesystemSubset interface.
  * @param _import - Use `_import` to pass a custom import function for testing,
  *   and supporting legacy resolvedModules such as CJS.
- * @param _capture - Use `_capture` to capture events for analytics.
  *
  */
-export const loadProject = async (args: {
+export async function loadProject(args: {
 	projectPath: string
-	repo?: Repository
-	nodeishFs: NodeishFilesystem
+	nodeishFs: Repository["nodeishFs"]
+	/**
+	 * The app id is used to identify the app that is using the SDK.
+	 *
+	 * We use the app id to group events in telemetry to answer questions
+	 * like "Which apps causes these errors?" or "Which apps are used more than others?".
+	 *
+	 * @example
+	 * 	appId: "app.inlang.badge"
+	 */
+	appId?: string
 	_import?: ImportFunction
-	_capture?: (id: string, props: Record<string, unknown>) => void
-}): Promise<InlangProject> => {
-	const projectPath = normalizePath(args.projectPath)
+}): Promise<InlangProject>
 
-	// -- migrate if outdated ------------------------------------------------
+/**
+ * @param projectPath - Absolute path to the inlang settings file.
+ * @param repo - An instance of a lix repo as returned by `openRepository`.
+ * @param _import - Use `_import` to pass a custom import function for testing,
+ *   and supporting legacy resolvedModules such as CJS.
+ *
+ */
+export async function loadProject(args: {
+	projectPath: string
+	repo: Repository
+	appId?: string
+	_import?: ImportFunction
+}): Promise<InlangProject>
 
-	await maybeMigrateToDirectory({ nodeishFs: args.nodeishFs, projectPath })
+export async function loadProject(args: {
+	projectPath: string
+	repo?: Repository
+	appId?: string
+	_import?: ImportFunction
+	nodeishFs?: Repository["nodeishFs"]
+}): Promise<InlangProject> {
+	const projectPath = normalizePath(args.projectPath)
 
 	// -- validation --------------------------------------------------------
 	// the only place where throwing is acceptable because the project
@@ -72,35 +98,37 @@ export const loadProject = async (args: {
 		)
 	}
 
-	// -- load project ------------------------------------------------------
-	let idError: Error | undefined
-	return await createRoot(async () => {
-		const [initialized, markInitAsComplete, markInitAsFailed] = createAwaitable()
-		const nodeishFs = createNodeishFsWithAbsolutePaths({
-			projectPath,
-			nodeishFs: args.nodeishFs,
-		})
+	let fs: Repository["nodeishFs"]
+	if (args.nodeishFs) {
+		// TODO: deprecate
+		fs = args.nodeishFs
+	} else if (args.repo) {
+		fs = args.repo.nodeishFs
+	} else {
+		throw new LoadProjectInvalidArgument(`Repo missing from arguments.`, { argument: "repo" })
+	}
 
-		let projectId: string | undefined
+	const nodeishFs = createNodeishFsWithAbsolutePaths({
+		projectPath,
+		nodeishFs: fs,
+	})
 
-		try {
-			projectId = await nodeishFs.readFile(projectPath + "/project_id", {
-				encoding: "utf-8",
-			})
-		} catch (error) {
-			// @ts-ignore
-			if (error.code === "ENOENT") {
-				if (args.repo) {
-					projectId = await generateProjectId(args.repo, projectPath)
-					if (projectId) {
-						await nodeishFs.writeFile(projectPath + "/project_id", projectId)
-					}
-				}
-			} else {
-				idError = error as Error
-			}
-		}
+	// -- migratations ------------------------------------------------
+
+	await maybeMigrateToDirectory({ nodeishFs: fs, projectPath })
+	await maybeCreateFirstProjectId({ projectPath, repo: args.repo })
+
+	// -- load project ------------------------------------------------------
 
+	return await createRoot(async () => {
+		// TODO remove tryCatch after https://github.com/opral/monorepo/issues/2013
+		// - a repo will always be present
+		// - if a repo is present, the project id will always be present
+		const { data: projectId } = await tryCatch(() =>
+			fs.readFile(args.projectPath + "/project_id", { encoding: "utf-8" })
+		)
+
+		const [initialized, markInitAsComplete, markInitAsFailed] = createAwaitable()
 		// -- settings ------------------------------------------------------------
 
 		const [settings, _setSettings] = createSignal<ProjectSettings>()
@@ -113,12 +141,7 @@ export const loadProject = async (args: {
 			// }
 
 			loadSettings({ settingsFilePath: projectPath + "/settings.json", nodeishFs })
-				.then((settings) => {
-					setSettings(settings)
-					// rename settings to get a convenient access to the data in Posthog
-					const project_settings = settings
-					args._capture?.("SDK used settings", { project_settings, group: projectId })
-				})
+				.then((settings) => setSettings(settings))
 				.catch((err) => {
 					markInitAsFailed(err)
 				})
@@ -218,7 +241,7 @@ export const loadProject = async (args: {
 						module:
 							resolvedModules()?.meta.find((m) => m.id.includes(rule.id))?.module ??
 							"Unknown module. You stumbled on a bug in inlang's source code. Please open an issue.",
-						// default to warning, see https://github.com/inlang/monorepo/issues/1254
+						// default to warning, see https://github.com/opral/monorepo/issues/1254
 						level: settingsValue["messageLintRuleLevels"]?.[rule.id] ?? "warning",
 					} satisfies InstalledMessageLintRule)
 			) satisfies Array<InstalledMessageLintRule>
@@ -285,6 +308,29 @@ export const loadProject = async (args: {
 			debouncedSave(messagesQuery.getAll())
 		})
 
+		/**
+		 * Utility to escape reactive tracking and avoid multiple calls to
+		 * the capture event.
+		 *
+		 * Should be addressed with https://github.com/opral/monorepo/issues/1772
+		 */
+		let projectLoadedCapturedAlready = false
+
+		if (projectId && projectLoadedCapturedAlready === false) {
+			projectLoadedCapturedAlready = true
+			// TODO ensure that capture is "awaited" without blocking the the app from starting
+			await capture("SDK loaded project", {
+				projectId,
+				properties: {
+					appId: args.appId,
+					settings: settings(),
+					installedPluginIds: installedPlugins().map((p) => p.id),
+					installedMessageLintRuleIds: installedMessageLintRules().map((r) => r.id),
+					numberOfMessages: messagesQuery.includedMessageIds().length,
+				},
+			})
+		}
+
 		return {
 			installed: {
 				plugins: createSubscribable(() => installedPlugins()),
@@ -292,10 +338,7 @@ export const loadProject = async (args: {
 			},
 			errors: createSubscribable(() => [
 				...(initializeError ? [initializeError] : []),
-				...(idError ? [idError] : []),
 				...(resolvedModules() ? resolvedModules()!.errors : []),
-				// have a query error exposed
-				//...(lintErrors() ?? []),
 			]),
 			settings: createSubscribable(() => settings() as ProjectSettings),
 			setSettings,

package/src/migrations/maybeCreateFirstProjectId.test.ts

@@ -0,0 +1,34 @@
+import { generateProjectId } from "./maybeCreateFirstProjectId.js"
+import { it, expect } from "vitest"
+import { openRepository } from "@lix-js/client/src/openRepository.ts"
+import { mockRepo, createNodeishMemoryFs } from "@lix-js/client"
+import { type Snapshot } from "@lix-js/fs"
+// eslint-disable-next-line no-restricted-imports -- test
+import { readFileSync } from "node:fs"
+
+const ciTestRepo: Snapshot = JSON.parse(
+	readFileSync("./mocks/ci-test-repo-no-shallow.json", { encoding: "utf-8" })
+)
+const repo = await mockRepo({ fromSnapshot: ciTestRepo as Snapshot })
+
+it("should return if repo is undefined", async () => {
+	const projectId = await generateProjectId({ repo: undefined, projectPath: "mocked_project_path" })
+	expect(projectId).toBeUndefined()
+})
+
+it("should generate a project id", async () => {
+	const projectId = await generateProjectId({ repo, projectPath: "mocked_project_path" })
+	expect(projectId).toBe("432d7ef29c510e99d95e2d14ef57a0797a1603859b5a851b7dff7e77161b8c08")
+})
+
+it("should return undefined if repoMeta contains error", async () => {
+	const repoWithError = await openRepository("https://github.com/inlang/no-exist", {
+		nodeishFs: createNodeishMemoryFs(),
+	})
+
+	const projectId = await generateProjectId({
+		repo: repoWithError,
+		projectPath: "mocked_project_path",
+	})
+	expect(projectId).toBeUndefined()
+})

package/src/migrations/maybeCreateFirstProjectId.ts

@@ -0,0 +1,43 @@
+import type { Repository } from "@lix-js/client"
+import { hash } from "@lix-js/client"
+
+/**
+ * Creates a project id if it does not exist yet.
+ *
+ * - this is a migration to ensure that all projects have a project id
+ * - new projects are created with a project id (in the future)
+ */
+export async function maybeCreateFirstProjectId(args: {
+	projectPath: string
+	repo?: Repository
+}): Promise<void> {
+	// the migration assumes a repository
+	if (args.repo === undefined) {
+		return
+	}
+	try {
+		await args.repo.nodeishFs.readFile(args.projectPath + "/project_id", {
+			encoding: "utf-8",
+		})
+	} catch (error) {
+		// @ts-ignore
+		if (error.code === "ENOENT" && args.repo) {
+			const projectId = await generateProjectId({ repo: args.repo, projectPath: args.projectPath })
+			if (projectId) {
+				await args.repo.nodeishFs.writeFile(args.projectPath + "/project_id", projectId)
+			}
+		}
+	}
+}
+
+export async function generateProjectId(args: { repo?: Repository; projectPath: string }) {
+	if (!args.repo || !args.projectPath) {
+		return undefined
+	}
+	const firstCommitHash = await args.repo.getFirstCommitHash()
+
+	if (firstCommitHash) {
+		return hash(`${firstCommitHash + args.projectPath}`)
+	}
+	return undefined
+}

package/src/migrations/migrateToDirectory.ts

@@ -3,7 +3,7 @@ import type { NodeishFilesystem } from "@lix-js/fs"
 
 /**
  * Migrates to the new project directory structure
- * https://github.com/inlang/monorepo/issues/1678
+ * https://github.com/opral/monorepo/issues/1678
  */
 export const maybeMigrateToDirectory = async (args: {
 	nodeishFs: NodeishFilesystem
@@ -51,9 +51,9 @@ The \`project.inlang.json\` file is now contained in a project directory e.g. \`
 ## Why is this happening?
 
 See this RFC https://docs.google.com/document/d/1OYyA1wYfQRbIJOIBDliYoWjiUlkFBNxH_U2R4WpVRZ4/edit#heading=h.pecv6xb7ial6 
-and the following GitHub issue for more information https://github.com/inlang/monorepo/issues/1678.
+and the following GitHub issue for more information https://github.com/opral/monorepo/issues/1678.
 
-- Monorepo support https://github.com/inlang/monorepo/discussions/258. 
+- Monorepo support https://github.com/opral/monorepo/discussions/258. 
 - Required for many other future features like caching, first class offline support, and more. 
 - Stablize the inlang project format.
 `

package/src/telemetry/capture.ts

@@ -0,0 +1,49 @@
+import { ENV_VARIABLES } from "../env-variables/index.js"
+
+/**
+ * List of telemetry events for typesafety.
+ *
+ * - prefix with `SDK` to avoid collisions with other apps
+ * - use past tense to indicate that the event is completed
+ */
+const events = ["SDK loaded project"] as const
+
+/**
+ * Capture an event.
+ *
+ * - manually calling the PostHog API because the SDKs were not platform angostic (and generally bloated)
+ */
+export const capture = async (
+	event: (typeof events)[number],
+	args: {
+		projectId: string
+		/**
+		 * Please use snake_case for property names.
+		 */
+		properties: Record<string, any>
+	}
+) => {
+	// do not send events if the token is not set
+	// (assuming this eases testing)
+	if (ENV_VARIABLES.PUBLIC_POSTHOG_TOKEN === undefined) {
+		return
+	}
+	try {
+		await fetch("https://eu.posthog.com/capture/", {
+			method: "POST",
+			body: JSON.stringify({
+				api_key: ENV_VARIABLES.PUBLIC_POSTHOG_TOKEN,
+				event,
+				// id is "unknown" because no user information is available
+				distinct_id: "unknown",
+				properties: {
+					$groups: { project: args.projectId },
+					...args.properties,
+				},
+			}),
+		})
+	} catch (e) {
+		// TODO implement sentry logging
+		// do not console.log and avoid exposing internal errors to the user
+	}
+}

package/dist/generateProjectId.d.ts

@@ -1,3 +0,0 @@
-import type { Repository } from "@lix-js/client";
-export declare function generateProjectId(repo: Repository, projectPath: string): Promise<string | undefined>;
-//# sourceMappingURL=generateProjectId.d.ts.map

package/dist/generateProjectId.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"generateProjectId.d.ts","sourceRoot":"","sources":["../src/generateProjectId.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAGhD,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,+BAU5E"}

package/dist/generateProjectId.js

@@ -1,11 +0,0 @@
-import { hash } from "@lix-js/client";
-export async function generateProjectId(repo, projectPath) {
-    if (!repo || !projectPath) {
-        return undefined;
-    }
-    const repoMeta = await repo.getMeta();
-    if (repoMeta && !("error" in repoMeta)) {
-        return hash(`${repoMeta.id + projectPath}`);
-    }
-    return undefined;
-}

package/dist/generateProjectId.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=generateProjectId.test.d.ts.map

package/dist/generateProjectId.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"generateProjectId.test.d.ts","sourceRoot":"","sources":["../src/generateProjectId.test.ts"],"names":[],"mappings":""}

package/dist/generateProjectId.test.js

@@ -1,18 +0,0 @@
-import { generateProjectId } from "./generateProjectId.js";
-import { describe, it, expect } from "vitest";
-import { openRepository } from "@lix-js/client/src/openRepository.ts";
-import { mockRepo, createNodeishMemoryFs } from "@lix-js/client";
-describe("generateProjectId", async () => {
-    const repo = await mockRepo();
-    it("should generate a project id", async () => {
-        const projectId = await generateProjectId(repo, "mocked_project_path");
-        expect(projectId).toBe("0c83325bf9068eb01091c522d4b8e3765aff42e36fc781c041b44439bbe3e734");
-    });
-    it("should return undefined if repoMeta contains error", async () => {
-        const errorRepo = await openRepository("https://github.com/inlang/no-exist", {
-            nodeishFs: createNodeishMemoryFs(),
-        });
-        const projectId = await generateProjectId(errorRepo, "mocked_project_path");
-        expect(projectId).toBeUndefined();
-    });
-});

package/src/generateProjectId.test.ts

@@ -1,22 +0,0 @@
-import { generateProjectId } from "./generateProjectId.js"
-import { describe, it, expect } from "vitest"
-import { openRepository } from "@lix-js/client/src/openRepository.ts"
-import { mockRepo, createNodeishMemoryFs } from "@lix-js/client"
-
-describe("generateProjectId", async () => {
-	const repo = await mockRepo()
-
-	it("should generate a project id", async () => {
-		const projectId = await generateProjectId(repo, "mocked_project_path")
-		expect(projectId).toBe("0c83325bf9068eb01091c522d4b8e3765aff42e36fc781c041b44439bbe3e734")
-	})
-
-	it("should return undefined if repoMeta contains error", async () => {
-		const errorRepo = await openRepository("https://github.com/inlang/no-exist", {
-			nodeishFs: createNodeishMemoryFs(),
-		})
-
-		const projectId = await generateProjectId(errorRepo, "mocked_project_path")
-		expect(projectId).toBeUndefined()
-	})
-})

package/src/generateProjectId.ts

@@ -1,14 +0,0 @@
-import type { Repository } from "@lix-js/client"
-import { hash } from "@lix-js/client"
-
-export async function generateProjectId(repo: Repository, projectPath: string) {
-	if (!repo || !projectPath) {
-		return undefined
-	}
-	const repoMeta = await repo.getMeta()
-
-	if (repoMeta && !("error" in repoMeta)) {
-		return hash(`${repoMeta.id + projectPath}`)
-	}
-	return undefined
-}