WIP: Initial API design

.ruby-version

@@ -0,0 +1 @@
+3.4.5

.vscodeignore

@@ -12,3 +12,5 @@ vsc-extension-quickstart.md
 **/*.map
 **/*.ts
 **/.vscode-test.*
+
+rubyEnvironmentsApi/**

README.md

@@ -13,6 +13,28 @@ TODO: this extension is getting extracted from the Ruby LSP.
 
 TODO
 
+```
+{
+    "extensionDependencies": [
+        "shopify.ruby-environments"
+    ],
+    "dependencies": {
+        "@shopify/ruby-environments": "..."
+    },
+}
+```
+
 ## API
 
 TODO
+
+```
+// Import the API
+import { RubyEnvironments } from '@shopify/ruby-environments';
+
+// Load the RubyEnvironments API
+const rubyEnvApi: RubyEnvironmentsApi = await RubyEnvironmentsApi.getApi();
+
+// Retrieve the resolved Ruby environment.
+const rubyEnv = await rubyEnvApi.getEnvironment(vscode.workspace.workspaceFolders[0]);
+```

activation.rb

@@ -0,0 +1,7 @@
+# Using .map.compact just so that it doesn't crash immediately on Ruby 2.6
+env = ENV.map do |k, v|
+  utf_8_value = v.dup.force_encoding(Encoding::UTF_8)
+  "#{k}RUBY_LSP_VS#{utf_8_value}" if utf_8_value.valid_encoding?
+end.compact
+env.unshift(RUBY_VERSION, Gem.path.join(","), !!defined?(RubyVM::YJIT))
+STDERR.print("RUBY_LSP_ACTIVATION_SEPARATOR#{env.join("RUBY_LSP_FS")}RUBY_LSP_ACTIVATION_SEPARATOR")

chruby_activation.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Typically, GEM_HOME points to $HOME/.gem/ruby/version_without_patch. For example, for Ruby 3.2.2, it would be
+# $HOME/.gem/ruby/3.2.0. However, chruby overrides GEM_HOME to use the patch part of the version, resulting in
+# $HOME/.gem/ruby/3.2.2. In our activation script, we check if a directory using the patch exists and then prefer
+# that over the default one.
+user_dir = Gem.user_dir
+paths = Gem.path
+default_dir = Gem.default_dir
+
+if paths.length > 2
+  paths.delete(default_dir)
+  paths.delete(user_dir)
+  first_path = paths[0]
+  user_dir = first_path if first_path && Dir.exist?(first_path)
+end
+
+newer_gem_home = File.join(File.dirname(user_dir), ARGV.first)
+gems = Dir.exist?(newer_gem_home) ? newer_gem_home : user_dir
+STDERR.print(
+  [
+    default_dir,
+    gems,
+    !!defined?(RubyVM::YJIT),
+    RUBY_VERSION
+  ].join("RUBY_LSP_ACTIVATION_SEPARATOR")
+)

eslint.config.mjs

@@ -32,10 +32,16 @@ export default tseslint.config(
       "**/dist/",
       ".vscode-test.mjs",
       "esbuild.js",
+      "rubyEnvironmentsApi"
     ],
   },
   {
     rules: {
+      "@typescript-eslint/no-explicit-any": "off",
+      "@typescript-eslint/no-unsafe-assignment": "off",
+      "@typescript-eslint/no-unsafe-argument": "off",
+      "@typescript-eslint/no-unsafe-member-access": "off",
+      "@typescript-eslint/no-unsafe-return": "off",
       "@typescript-eslint/no-unused-vars": [
         "error",
         {

package.json

@@ -36,20 +36,25 @@
     "test": "vscode-test"
   },
   "devDependencies": {
+    "@eslint/js": "^9.32.0",
     "@types/mocha": "^10.0.10",
     "@types/node": "20.x",
+    "@types/sinon": "^17.0.4",
     "@types/vscode": "^1.102.0",
-    "@eslint/js": "^9.32.0",
-    "eslint": "^9.30.1",
-    "typescript-eslint": "^8.38.0",
-    "eslint-plugin-prettier": "^5.5.3",
-    "prettier": "^3.6.2",
     "@vscode/test-cli": "^0.0.11",
     "@vscode/test-electron": "^2.5.2",
     "@vscode/vsce": "^3.6.0",
     "esbuild": "^0.25.3",
+    "eslint": "^9.30.1",
+    "eslint-plugin-prettier": "^5.5.3",
     "npm-run-all": "^4.1.5",
     "ovsx": "^0.10.5",
-    "typescript": "^5.8.3"
+    "prettier": "^3.6.2",
+    "sinon": "^21.0.0",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.38.0"
+  },
+  "dependencies": {
+    "glob": "^11.0.3"
   }
 }

rubyEnvironmentsApi/.npmignore

@@ -0,0 +1,3 @@
+node_modules
+src
+tsconfig.json

rubyEnvironmentsApi/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022-present, Shopify Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

rubyEnvironmentsApi/README.md

@@ -0,0 +1,29 @@
+# Ruby environments
+
+This npm module provides a TypeScript API for interacting with Ruby environments VS Code extension.
+
+## Extension Settings
+
+```
+{
+    "extensionDependencies": [
+        "shopify.ruby-environments"
+    ],
+    "dependencies": {
+        "@shopify/ruby-environments": "..."
+    },
+}
+```
+
+## API
+
+```
+// Import the API
+import { RubyEnvironments } from '@shopify/ruby-environments';
+
+// Load the RubyEnvironments API
+const rubyEnvApi: RubyEnvironmentsApi = await RubyEnvironmentsApi.getApi();
+
+// Retrieve the resolved Ruby environment.
+const rubyEnv = await rubyEnvApi.getEnvironment(vscode.workspace.workspaceFolders[0]);
+```

rubyEnvironmentsApi/eslint.config.mjs

@@ -0,0 +1,50 @@
+// @ts-check
+
+import eslint from '@eslint/js';
+import tseslint from "typescript-eslint";
+import eslintPluginPrettier from "eslint-plugin-prettier";
+
+export default tseslint.config(
+  eslint.configs.recommended,
+  tseslint.configs.recommended,
+  tseslint.configs.recommendedTypeChecked,
+  {
+    plugins: {
+      prettier: eslintPluginPrettier,
+    },
+    rules: {
+      "prettier/prettier": "warn",
+    },
+  },
+  {
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+  },
+  {
+    ignores: [
+      "eslint.config.mjs",
+      "**/out/",
+    ],
+  },
+  {
+    rules: {
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        {
+          argsIgnorePattern: "^_",
+          varsIgnorePattern: "^_",
+          caughtErrorsIgnorePattern: "^_",
+        },
+      ],
+      "no-console": "warn",
+      "no-template-curly-in-string": "warn",
+      "eqeqeq": "error",
+      "no-invalid-this": "error",
+      "no-lonely-if": "error"
+    }
+  }
+);

rubyEnvironmentsApi/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@shopify/ruby-environments",
+  "version": "0.0.1",
+  "description": "API for the VS Code Ruby environments extension",
+  "main": "./out/index.js",
+  "types": "./out/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Shopify/ruby-environments.git"
+  },
+  "author": "Shopify",
+  "license": "MIT",
+  "scripts": {
+    "compile": "tsc -p ./",
+    "pretest": "yarn run compile-tests && yarn run compile && yarn run lint",
+    "check-types": "tsc --noEmit",
+    "format": "eslint . --fix && prettier '**/*.{ts,json,md,yaml,yml}' --write",
+    "lint": "eslint . && prettier '**/*.{ts,json,md,yaml,yml}' --check"
+  },
+  "devDependencies": {
+    "@types/node": "20.x",
+    "@types/vscode": "^1.102.0",
+    "@eslint/js": "^9.32.0",
+    "eslint": "^9.30.1",
+    "typescript-eslint": "^8.38.0",
+    "eslint-plugin-prettier": "^5.5.3",
+    "prettier": "^3.6.2",
+    "esbuild": "^0.25.3",
+    "typescript": "^5.8.3"
+  }
+}

rubyEnvironmentsApi/src/index.ts

@@ -0,0 +1,92 @@
+import { WorkspaceFolder, extensions } from "vscode";
+
+/**
+ * Identifiers for supported Ruby version managers.
+ */
+export enum ManagerIdentifier {
+  Asdf = "asdf",
+  Auto = "auto",
+  Chruby = "chruby",
+  Rbenv = "rbenv",
+  Rvm = "rvm",
+  Shadowenv = "shadowenv",
+  Mise = "mise",
+  RubyInstaller = "rubyInstaller",
+  None = "none",
+  Custom = "custom",
+}
+
+/**
+ * Configuration for a Ruby version manager.
+ * @property identifier The type of version manager in use.
+ */
+export interface ManagerConfiguration {
+  /** The type of version manager in use. */
+  identifier: ManagerIdentifier;
+}
+
+/**
+ * Represents a fully resolved Ruby environment for a workspace.
+ * @property env The environment variables for the Ruby process.
+ * @property rubyVersion The active Ruby version (optional).
+ * @property yjitEnabled Whether YJIT is enabled (optional).
+ * @property gemPath Array of gem paths for the environment.
+ * @property versionManager The configuration of the version manager used.
+ */
+export interface RubyEnvironment {
+  /** The environment variables for the Ruby process. */
+  env: NodeJS.ProcessEnv;
+  /** The active Ruby version, if detected. */
+  rubyVersion?: string;
+  /** Whether YJIT is enabled, if detected. */
+  yjitEnabled?: boolean;
+  /** Array of gem paths for the environment. */
+  gemPath: string[];
+  /** The configuration of the version manager used. */
+  versionManager: ManagerConfiguration;
+}
+
+/**
+ * Main API for interacting with Ruby environments in VS Code extensions.
+ */
+export interface RubyEnvironmentsApi {
+  /**
+   * Get the resolved Ruby environment for a workspace folder.
+   * @param workspaceFolder The workspace folder to resolve the environment for.
+   */
+  getEnvironment(workspaceFolder: WorkspaceFolder): Promise<RubyEnvironment>;
+
+  /**
+   * Update the Ruby environment for a workspace folder.
+   * @param env The environment variables to update.
+   * @param workspaceFolder The workspace folder to update.
+   */
+  updateEnvironment(env: NodeJS.ProcessEnv, workspaceFolder: WorkspaceFolder): Promise<void>;
+
+  /**
+   * Force the Ruby environment extension to re-resolve the environment for a workspace folder.
+   * @param workspaceFolder The workspace folder to refresh.
+   */
+  refreshEnvironment(workspaceFolder: WorkspaceFolder): Promise<void>;
+}
+
+/**
+ * The extension identifier for the Ruby environments API.
+ */
+const EXTENSION_NAME = "shopify.ruby-environments";
+
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export namespace RubyEnvironmentsApi {
+  /**
+   * Return the API exported by the Ruby Environments extension.
+   * @throws If the extension is not found or cannot be activated.
+   */
+  export async function getApi(): Promise<RubyEnvironmentsApi> {
+    const extension = extensions.getExtension(EXTENSION_NAME);
+    if (!extension) {
+      throw new Error(`Extension ${EXTENSION_NAME} not found`);
+    }
+    await extension.activate();
+    return extension.exports as RubyEnvironmentsApi;
+  }
+}

rubyEnvironmentsApi/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "module": "Node16",
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "sourceMap": true,
+    "rootDir": "src",
+    "strict": true /* enable all strict type-checking options */,
+    "outDir": "out" /* Specify an output folder for all emitted files. */,
+    "declaration": true /* Generate .d.ts files from TypeScript and JavaScript files in your project. */,
+    "declarationMap": true /* Create sourcemaps for d.ts files. */
+  }
+}