Merge pull request #9 from Shopify/rmf-initial-implementation

Initial API proposal for Ruby Environments extension

Author: rafaelfranca

.github/workflows/publish.yml

@@ -16,6 +16,7 @@ jobs:
         with:
           node-version: "22.17.0"
           cache: "yarn"
+          registry-url: "https://registry.npmjs.org"
 
       - name: 📦 Install dependencies
         run: yarn --frozen-lockfile
@@ -33,6 +34,14 @@ jobs:
         env:
           VSCE_PAT: ${{ secrets.VSCE_PAT }}
 
+      - name: Publish types to npm
+        if: "!github.event.release.prerelease"
+        run: |
+          cd npm
+          npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
       # Prereleases
       - name: Package and publish prerelease extension in the marketplace
         if: "github.event.release.prerelease"
@@ -41,3 +50,11 @@ jobs:
           node_modules/.bin/vsce publish --pre-release --packagePath ruby-environments.vsix
         env:
           VSCE_PAT: ${{ secrets.VSCE_PAT }}
+
+      - name: Publish prerelease types to npm
+        if: "github.event.release.prerelease"
+        run: |
+          cd npm
+          npm publish --access public --tag next
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.gitignore

@@ -3,3 +3,4 @@ dist
 node_modules
 .vscode-test/
 *.vsix
+npm/*.d.ts

.vscodeignore

@@ -3,10 +3,19 @@
 out/**
 node_modules/**
 src/**
+npm/**
+.github/**
+.dev/**
+.shadowenv.d/**
 .gitignore
 .yarnrc
+.prettierignore
+.prettierrc.json
 esbuild.js
+dev.yml
+CLAUDE.md
 vsc-extension-quickstart.md
+yarn.lock
 **/tsconfig.json
 **/eslint.config.mjs
 **/*.map

README.md

@@ -7,12 +7,104 @@ need to activate the Ruby environment in order to launch Ruby executables, such
 
 ## Features
 
-TODO: this extension is getting extracted from the Ruby LSP.
+- **Automatic Ruby detection**: Discovers the Ruby interpreter installed on your machine
+- **Version manager integrations**: Supports popular version managers including:
+  - [chruby](https://github.com/postmodern/chruby)
+  - [rbenv](https://github.com/rbenv/rbenv)
+  - [rvm](https://rvm.io/)
+  - [asdf](https://asdf-vm.com/) (with ruby plugin)
+  - [mise](https://mise.jdx.dev/)
+- **Environment activation**: Composes the correct environment variables (`PATH`, `GEM_HOME`, `GEM_PATH`, etc.) to match your shell configuration
+- **JIT detection**: Identifies available JIT compilers (YJIT, ZJIT) for the activated Ruby version
+- **Shell support**: Works with various shells including bash, zsh, fish, and PowerShell
+- **Extension API**: Provides a programmatic API for other extensions to access the activated Ruby environment
 
 ## Extension Settings
 
 TODO
 
 ## API
 
-TODO
+This extension exposes an API that other extensions can use to access the activated Ruby environment.
+
+### TypeScript Types
+
+Type definitions are available as a separate npm package:
+
+```bash
+npm install --save-dev @shopify/ruby-environments-types
+```
+
+### Getting the API
+
+```typescript
+import type { RubyEnvironmentsApi } from "@shopify/ruby-environments-types";
+
+const rubyEnvExtension = vscode.extensions.getExtension<RubyEnvironmentsApi>("Shopify.ruby-environments");
+
+if (rubyEnvExtension) {
+  if (!rubyEnvExtension.isActive) {
+    await rubyEnvExtension.activate();
+  }
+
+  const api: RubyEnvironmentsApi = rubyEnvExtension.exports;
+  // Use the API...
+}
+```
+
+### Activating the Ruby Environment
+
+Request the extension to activate Ruby for a specific workspace:
+
+```typescript
+await api.activate(vscode.workspace.workspaceFolders?.[0]);
+```
+
+### Getting the Current Ruby Definition
+
+Retrieve the currently activated Ruby environment:
+
+```typescript
+import type { RubyDefinition } from "@shopify/ruby-environments-types";
+
+const ruby: RubyDefinition | null = api.getRuby();
+
+if (ruby === null) {
+  console.log("Ruby environment not yet activated");
+} else if (ruby.error) {
+  console.log("Ruby activation failed");
+} else {
+  console.log(`Ruby version: ${ruby.rubyVersion}`);
+  console.log(`Available JITs: ${ruby.availableJITs.join(", ")}`);
+  console.log(`GEM_PATH: ${ruby.gemPath.join(":")}`);
+}
+```
+
+### Subscribing to Ruby Environment Changes
+
+Listen for changes to the Ruby environment (e.g., when the user switches Ruby versions):
+
+```typescript
+import type { RubyChangeEvent } from "@shopify/ruby-environments-types";
+
+const disposable = api.onDidRubyChange((event: RubyChangeEvent) => {
+  console.log(`Ruby changed in workspace: ${event.workspace?.name}`);
+
+  if (!event.ruby.error) {
+    console.log(`New Ruby version: ${event.ruby.rubyVersion}`);
+  }
+});
+
+// Add to your extension's subscriptions for automatic cleanup
+context.subscriptions.push(disposable);
+```
+
+### Extension Dependency
+
+To ensure your extension loads after Ruby Environments, add it as a dependency in your `package.json`:
+
+```json
+{
+  "extensionDependencies": ["Shopify.ruby-environments"]
+}
+```

dev.yml

@@ -1,5 +1,7 @@
 name: ruby-environments
 
+nix: true
+
 up:
   - node:
       yarn: true

npm/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@shopify/ruby-environments-types",
+  "description": "Type definitions for the Ruby Environments VS Code extension",
+  "version": "0.0.1",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Shopify/ruby-environments.git"
+  },
+  "license": "MIT",
+  "types": "./extension.d.ts",
+  "files": [
+    "extension.d.ts"
+  ],
+  "scripts": {
+    "build": "tsc ../src/extension.ts --emitDeclarationOnly --declaration --declarationDir . --moduleResolution node --skipLibCheck",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ruby",
+    "vscode",
+    "types",
+    "typescript"
+  ]
+}

package.json

@@ -20,13 +20,15 @@
   "contributes": {},
   "scripts": {
     "vscode:prepublish": "yarn run package",
-    "compile": "yarn run check-types && yarn run lint && node esbuild.js",
+    "compile": "yarn run check-types && yarn run lint && node esbuild.js && yarn run build:types",
     "watch": "npm-run-all -p watch:*",
     "watch:esbuild": "node esbuild.js --watch",
     "watch:tsc": "tsc --noEmit --watch --project tsconfig.json",
-    "package": "yarn run check-types && yarn run lint && node esbuild.js --production",
+    "build:types": "tsc --emitDeclarationOnly --declaration --declarationDir dist",
+    "package": "yarn run check-types && yarn run lint && node esbuild.js --production && yarn run build:types",
     "package_release": "vsce package --out ruby-environments.vsix",
     "package_prerelease": "vsce package --pre-release --out ruby-environments.vsix",
+    "npm:publish": "cd npm && npm publish --access public",
     "compile-tests": "tsc -p . --outDir out",
     "watch-tests": "tsc -p . -w --outDir out",
     "pretest": "yarn run compile-tests && yarn run compile && yarn run lint",

src/extension.ts

@@ -1,11 +1,68 @@
 import * as vscode from "vscode";
 
-// The public API that gets exposed to other extensions that depend on Ruby environments
-// eslint-disable-next-line @typescript-eslint/no-empty-object-type
-interface RubyEnvironmentsApi {}
+/**
+ * Represents a Ruby environment that failed to activate
+ */
+export interface RubyError {
+  error: true;
+}
+
+/**
+ * JIT compiler types supported by Ruby
+ */
+export enum JitType {
+  YJIT = "YJIT",
+  ZJIT = "ZJIT",
+}
+
+/**
+ * Represents a successfully activated Ruby environment
+ */
+export interface RubyEnvironment {
+  error: false;
+  rubyVersion: string;
+  availableJITs: JitType[];
+  env: NodeJS.ProcessEnv;
+  gemPath: string[];
+}
+
+/**
+ * Represents a Ruby environment definition - either an error or a successful environment
+ */
+export type RubyDefinition = RubyError | RubyEnvironment;
+
+/**
+ * Event data emitted when the Ruby environment changes
+ */
+export interface RubyChangeEvent {
+  workspace: vscode.WorkspaceFolder | undefined;
+  ruby: RubyDefinition;
+}
+
+/**
+ * The public API that gets exposed to other extensions that depend on Ruby environments
+ */
+export interface RubyEnvironmentsApi {
+  /** Activate the extension for a specific workspace */
+  activate: (workspace: vscode.WorkspaceFolder | undefined) => Promise<void>;
+  /** Get the current Ruby definition */
+  getRuby: () => RubyDefinition | null;
+  /** Event that fires when the Ruby environment changes */
+  onDidRubyChange: vscode.Event<RubyChangeEvent>;
+}
+
+// Event emitter for Ruby environment changes
+const rubyChangeEmitter = new vscode.EventEmitter<RubyChangeEvent>();
+
+export function activate(context: vscode.ExtensionContext): RubyEnvironmentsApi {
+  // Ensure the event emitter is disposed when the extension is deactivated
+  context.subscriptions.push(rubyChangeEmitter);
 
-export function activate(_context: vscode.ExtensionContext): RubyEnvironmentsApi {
-  return {};
+  return {
+    activate: async (_workspace: vscode.WorkspaceFolder | undefined) => {},
+    getRuby: () => null,
+    onDidRubyChange: rubyChangeEmitter.event,
+  };
 }
 
 export function deactivate() {}

src/test/extension.test.ts

@@ -1,7 +1,75 @@
 import * as assert from "assert";
+import { suite, test, beforeEach, afterEach } from "mocha";
+import { activate, deactivate, RubyEnvironmentsApi } from "../extension";
+import { FakeContext, createContext } from "./helpers";
 
 suite("Extension Test Suite", () => {
-  test("Sample test", () => {
-    assert.strictEqual(1 + 1, 2);
+  suite("activate", () => {
+    let context: FakeContext;
+
+    beforeEach(() => {
+      context = createContext();
+    });
+
+    afterEach(() => {
+      context.dispose();
+    });
+
+    test("returns an object implementing RubyEnvironmentsApi", async () => {
+      const api = activate(context);
+
+      assert.strictEqual(typeof api, "object", "activate should return an object");
+      assert.strictEqual(typeof api.activate, "function", "API should have an activate method");
+      assert.strictEqual(typeof api.getRuby, "function", "API should have a getRuby method");
+      assert.strictEqual(typeof api.onDidRubyChange, "function", "API should have an onDidRubyChange event");
+
+      const result = api.activate(undefined);
+      assert.ok(result instanceof Promise, "activate should return a Promise");
+      await result;
+    });
+
+    test("returned API conforms to RubyEnvironmentsApi interface", () => {
+      const api = activate(context);
+
+      const typedApi: RubyEnvironmentsApi = api;
+      assert.ok(typedApi, "API should conform to RubyEnvironmentsApi interface");
+    });
+
+    test("getRuby returns null initially", () => {
+      const api = activate(context);
+
+      assert.strictEqual(api.getRuby(), null, "getRuby should return null before activation");
+    });
+
+    test("onDidRubyChange allows subscribing to events", () => {
+      const api = activate(context);
+
+      let eventFired = false;
+      const disposable = api.onDidRubyChange(() => {
+        eventFired = true;
+      });
+
+      assert.ok(disposable, "onDidRubyChange should return a disposable");
+      assert.strictEqual(typeof disposable.dispose, "function", "disposable should have a dispose method");
+
+      disposable.dispose();
+      assert.strictEqual(eventFired, false, "event should not have fired yet");
+    });
+
+    test("adds event emitter to context subscriptions for disposal", () => {
+      assert.strictEqual(context.subscriptions.length, 0, "subscriptions should be empty initially");
+
+      activate(context);
+
+      assert.strictEqual(context.subscriptions.length, 1, "should add emitter to subscriptions");
+    });
+  });
+
+  suite("deactivate", () => {
+    test("can be called without errors", () => {
+      assert.doesNotThrow(() => {
+        deactivate();
+      }, "deactivate should not throw errors");
+    });
   });
 });

src/test/helpers.ts

@@ -0,0 +1,16 @@
+import * as vscode from "vscode";
+
+export type FakeContext = vscode.ExtensionContext & { dispose: () => void };
+
+export function createContext(): FakeContext {
+  const subscriptions: vscode.Disposable[] = [];
+
+  return {
+    subscriptions,
+    dispose: () => {
+      subscriptions.forEach((subscription) => {
+        subscription.dispose();
+      });
+    },
+  } as unknown as FakeContext;
+}