Implement initial API

Author: rafaelfranca

README.md

@@ -7,12 +7,86 @@ 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.
+
+### Getting the API
+
+```typescript
+const rubyEnvExtension = vscode.extensions.getExtension("Shopify.ruby-environments");
+
+if (rubyEnvExtension) {
+  const api = rubyEnvExtension.exports;
+  // Use the API...
+}
+```
+
+### Activating the Ruby Environment
+
+Request the extension to activate Ruby for a specific workspace:
+
+```typescript
+api.activate(vscode.workspace.workspaceFolders?.[0]);
+```
+
+### Getting the Current Ruby Definition
+
+Retrieve the currently activated Ruby environment:
+
+```typescript
+const ruby = 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
+const disposable = api.onDidRubyChange((event) => {
+  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"]
+}
+```

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;
+}