@stainless-api/playgrounds 0.0.1-beta.0

package/src/codemirror/typescript/worker.ts

@@ -0,0 +1,292 @@
+import { createVirtualTypeScriptEnvironment, VirtualTypeScriptEnvironment } from '@typescript/vfs';
+import ts from './cdn-typescript';
+import * as Comlink from '../comlink';
+import { createWorker, HoverInfo } from '@stainless-api/codemirror-ts/worker';
+import { format } from 'prettier';
+import { parsers } from './prettier-plugin-external-typescript.vendor';
+import estree from 'prettier/plugins/estree';
+import { SourceMapConsumer } from 'source-map';
+import { LinesAndColumns } from 'lines-and-columns';
+
+type TypescriptTypes = NonNullable<typeof import('virtual:stl-playground/typescript.json').default>;
+
+// @ts-expect-error this is kinda awful but it makes ts autocomplete work without source patching
+Object.prototype.keepLegacyLimitationForAutocompletionSymbols = false;
+
+function escapeRegExp(text: string) {
+  return text.replace(/[-[\]{}()*+?.,\\^$|#\s]/g, '\\$&');
+}
+let realpathRe;
+const realpath = (typescriptTypes: TypescriptTypes, path: string) => {
+  realpathRe ??= new RegExp(
+    `^(${typescriptTypes!.links.map((e, i) => `(?<_${i}>${escapeRegExp(e[0])})`).join('|')})(/|$)`,
+  );
+  let match;
+  while ((match = path.match(realpathRe))) {
+    const entry =
+      typescriptTypes!.links[
+        Object.entries(match.groups!)
+          .find((e) => e[1])![0]
+          .slice(1) as `${number}`
+      ]!;
+    path = entry[1] + (match[2 + typescriptTypes!.links.length] ?? '') + path.slice(match[0].length);
+  }
+  return path;
+};
+
+function notImplemented(methodName: string): never {
+  throw new Error(`Method '${methodName}' is not implemented.`);
+}
+
+function audit<ArgsT extends unknown[], ReturnT>(
+  _name: string,
+  fn: (...args: ArgsT) => ReturnT,
+): (...args: ArgsT) => ReturnT {
+  return (...args) => {
+    const res = fn(...args);
+
+    //const smallRes = typeof res === "string" ? res.slice(0, 80) + "..." : res;
+    //debugLog("> " + name, ...args);
+    //debugLog("< " + smallRes);
+
+    return res;
+  };
+}
+
+// "/DOM.d.ts" => "/lib.dom.d.ts"
+const libize = (path: string) => path.replace('/', '/lib.').toLowerCase();
+
+/**
+ * Creates an in-memory System object which can be used in a TypeScript program, this
+ * is what provides read/write aspects of the virtual fs
+ */
+export function createSystem(typescriptTypes: TypescriptTypes, files: Map<string, string>): ts.System {
+  return {
+    args: [],
+    createDirectory: () => notImplemented('createDirectory'),
+    // TODO: could make a real file tree
+    directoryExists: audit('directoryExists', (directory) => {
+      directory = realpath(typescriptTypes, directory);
+      return Array.from(files.keys()).some((path) => path.startsWith(directory));
+    }),
+    exit: () => notImplemented('exit'),
+    fileExists: audit(
+      'fileExists',
+      (fileName) =>
+        files.has(realpath(typescriptTypes, fileName)) ||
+        files.has(realpath(typescriptTypes, libize(fileName))),
+    ),
+    getCurrentDirectory: () => '/',
+    getDirectories: () => [],
+    getExecutingFilePath: () => notImplemented('getExecutingFilePath'),
+    readDirectory: audit('readDirectory', (directory) => (directory === '/' ? Array.from(files.keys()) : [])),
+    readFile: audit(
+      'readFile',
+      (fileName) =>
+        files.get(realpath(typescriptTypes, fileName)) ??
+        files.get(realpath(typescriptTypes, libize(fileName))),
+    ),
+    resolvePath: (path) => realpath(typescriptTypes, path),
+    newLine: '\n',
+    useCaseSensitiveFileNames: true,
+    write: () => notImplemented('write'),
+    writeFile: (fileName, contents) => {
+      files.set(realpath(typescriptTypes, fileName), contents);
+    },
+    deleteFile: (fileName) => {
+      files.delete(realpath(typescriptTypes, fileName));
+    },
+  };
+}
+
+export type PromiseWithResolvers<T> = {
+  promise: Promise<T>;
+  resolve: (value: T) => void;
+  reject: (reason?: unknown) => void;
+};
+function promiseWithResolvers<T>(): PromiseWithResolvers<T> {
+  let resolve, reject;
+  const promise = new Promise<T>((_resolve, _reject) => {
+    resolve = _resolve;
+    reject = _reject;
+  });
+  return {
+    promise,
+    resolve: resolve!,
+    reject: reject!,
+  };
+}
+
+const compilerOpts: ts.CompilerOptions = {
+  module: ts.ModuleKind.NodeNext,
+  moduleResolution: ts.ModuleResolutionKind.NodeNext,
+  lib: ['esnext', 'webworker', 'webworker.iterable'],
+  types: ['stl-play'],
+  target: ts.ScriptTarget.ESNext,
+  moduleDetection: ts.ModuleDetectionKind.Force,
+};
+
+const initData = promiseWithResolvers<{
+  suggestedEnv: string[];
+  typescriptTypes: TypescriptTypes;
+}>();
+
+let typescriptTypes: TypescriptTypes;
+let fsMap: Map<string, string>;
+type RawCompletionItem = {
+  label: string;
+  type: Completion['type'];
+} & Pick<ts.CompletionEntryDetails, 'codeActions' | 'displayParts' | 'documentation' | 'tags'>;
+type RawCompletion = {
+  from: number;
+  options: RawCompletionItem[];
+};
+const worker: {
+  initialize(): Promise<void>;
+  updateFile({ path, code }: { path: string; code: string }): void;
+  getLints({ path }: { path: string }): Diagnostic[];
+  getAutocompletion({
+    path,
+    context,
+  }: {
+    path: string;
+    context: Pick<CompletionContext, 'pos' | 'explicit'>;
+  }): Promise<RawCompletion | null> | null;
+  getHover({ path, pos }: { path: string; pos: number }): HoverInfo | null;
+  getEnv(): VirtualTypeScriptEnvironment;
+} = createWorker({
+  env: (async () => {
+    const { typescriptTypes, suggestedEnv } = await initData.promise;
+    fsMap = new Map<string, string>(typescriptTypes.files as [string, string][]);
+    fsMap.set(
+      '/node_modules/@types/stl-play/package.json',
+      JSON.stringify({
+        name: '@types/stl-play',
+        types: 'index.d.ts',
+      }),
+    );
+    fsMap.set(
+      '/node_modules/@types/stl-play/index.d.ts',
+      `declare global {
+  declare var process: NodeJS.Process;
+  declare namespace NodeJS {
+    interface Dict<T> {
+      [key: string]: T | undefined;
+    }
+    interface ProcessEnv extends Dict<string> {\n${['TZ', ...suggestedEnv].map((e) => `      ${JSON.stringify(e)}?: string | undefined;\n`)}    }
+    interface Process {
+      /**
+       * The \`process.env\` property returns an object containing environment variables.
+       */
+      env: ProcessEnv;
+    }
+  }
+}
+export {}`,
+    );
+    const system = createSystem(typescriptTypes, fsMap);
+    return createVirtualTypeScriptEnvironment(system, [], ts, compilerOpts);
+  })(),
+});
+const api = {
+  ...worker,
+  async getHover(opts: { path: string; pos: number }): Promise<HoverInfo | null> {
+    const result = worker.getHover(opts);
+    if (result?.def) {
+      result.def = await Promise.all(result.def.map(fixDefInfo));
+    }
+    if (result?.typeDef) {
+      result.typeDef = await Promise.all(result.typeDef.map(fixDefInfo));
+    }
+    return result;
+  },
+  stlInit(initData_: Awaited<typeof initData.promise>) {
+    typescriptTypes = initData_.typescriptTypes;
+    initData.resolve(initData_);
+  },
+  async format(code: string) {
+    const result = (
+      await format(code, {
+        parser: 'typescript',
+        plugins: [{ parsers }, estree],
+        printWidth: 75,
+        singleQuote: true,
+      })
+    ).replace(/\n+$/, '');
+    if (result === code) return undefined;
+    return result;
+  },
+  async transform(code: string) {
+    return ts.transpileModule(code, {
+      fileName: 'input.mts',
+      compilerOptions: {
+        ...compilerOpts,
+        noCheck: true,
+      },
+      transformers: {
+        after: [
+          (ctx) => (file) =>
+            ts.visitEachChild(
+              file,
+              (child) =>
+                ts.isImportDeclaration(child)
+                  ? ctx.factory.updateImportDeclaration(
+                      child,
+                      child.modifiers,
+                      child.importClause,
+                      ts.isStringLiteral(child.moduleSpecifier)
+                        ? ctx.factory.createStringLiteral(
+                            child.moduleSpecifier.text.replace(
+                              /^(?!\.{0,2}\/|[a-z][a-z0-9+.-]+:)/,
+                              'https://esm.sh/',
+                            ),
+                          )
+                        : child.moduleSpecifier,
+                      child.attributes,
+                    )
+                  : child,
+              ctx,
+            ),
+        ],
+      },
+    }).outputText;
+  },
+};
+
+import mappingsWasm from 'source-map/lib/mappings.wasm?url&inline';
+import { Diagnostic } from '@codemirror/lint';
+import { Completion, CompletionContext } from '@codemirror/autocomplete';
+// @ts-expect-error - this is untyped
+SourceMapConsumer.initialize({ 'lib/mappings.wasm': mappingsWasm });
+
+const mapCache = new Map<string, { tracer: SourceMapConsumer; loc: LinesAndColumns } | null>();
+const fixDefInfo = async (def: ts.DefinitionInfo) => {
+  def.originalFileName = def.fileName.replace(/\.d\.m?ts$/, '.ts');
+  const path = realpath(typescriptTypes!, def.fileName + '.map');
+  let cached = mapCache.get(path);
+  if (cached === undefined) {
+    const dtsString = fsMap.get(realpath(typescriptTypes!, def.fileName));
+    const mapString = fsMap.get(path);
+    if (mapString && dtsString) {
+      cached = {
+        tracer: await new SourceMapConsumer(mapString),
+        loc: new LinesAndColumns(dtsString),
+      };
+      mapCache.set(path, cached);
+    } else {
+      mapCache.set(path, null);
+    }
+  }
+  if (cached) {
+    const loc = cached.loc.locationForIndex(def.textSpan.start);
+    if (loc) {
+      const { line } = cached.tracer.originalPositionFor(loc);
+      if (line) {
+        def.originalFileName += '#L' + line;
+      }
+    }
+  }
+  return def;
+};
+export type API = typeof api;
+Comlink.expose(api);

package/src/codemirror/typescript.tsx

@@ -0,0 +1,198 @@
+import { typescriptLanguage } from '@codemirror/lang-javascript';
+import tsWorkerURL from './typescript/worker?worker&url';
+import runnerWorkerURL from './typescript/runner?worker&url';
+import type { HoverInfo } from '@stainless-api/codemirror-ts/worker';
+import { tsAutocomplete, tsFacet, tsHover, tsLinter, tsSync, tsTwoslash } from '@stainless-api/codemirror-ts';
+import * as Comlink from './comlink';
+import { autocompletion } from '@codemirror/autocomplete';
+import type { JSDocTagInfo, QuickInfo, SymbolDisplayPart } from 'typescript';
+import type { Language } from './react';
+import { proxy, type Remote } from './comlink';
+import type { Logger } from '../Logs';
+import type { RunnerAPI } from './typescript/runner';
+import typescriptTypes from 'virtual:stl-playground/typescript.json';
+import authData from 'virtual:stl-playground/auth.json';
+import { docToHTML } from './fix-lsp-markdown';
+import { API } from './typescript/worker';
+import { EditorView } from '@codemirror/view';
+
+if (!typescriptTypes) {
+  throw new Error('TypeScript playgrounds failed to build.');
+}
+
+function displayPartsToString(displayParts: SymbolDisplayPart[] | undefined): string {
+  if (displayParts) {
+    return displayParts.map((displayPart) => displayPart.text).join('');
+  }
+  return '';
+}
+
+function maybeBlock(md: string) {
+  return markdown(md).startsWith('<p>') ? md : '\n' + md;
+}
+
+function tagToString(tag: JSDocTagInfo): string {
+  let tagLabel = `*@${tag.name}*`;
+  if (tag.name === 'param' && tag.text) {
+    const [paramName, ...rest] = tag.text;
+    tagLabel += ` \`${paramName!.text}\``;
+    if (rest.length > 0) tagLabel += ` — ${maybeBlock(rest.map((r) => r.text).join(' '))}`;
+  } else if (Array.isArray(tag.text)) {
+    tagLabel += ` — ${maybeBlock(tag.text.map((r) => r.text).join(' '))}`;
+  } else if (tag.text) {
+    tagLabel += ` — ${maybeBlock(tag.text)}`;
+  }
+  return tagLabel;
+}
+
+const markdown = (md: string) => {
+  return docToHTML(md, 'markdown');
+};
+
+const useMeta = /iPad|iPhone|iPod|Mac/.test(navigator.userAgent);
+type GoToOptions = {
+  gotoHandler?: (currentPath: string, hoverData: HoverInfo, view: EditorView) => true | undefined;
+};
+export function tsGoto(opts: GoToOptions = {}) {
+  return EditorView.domEventHandlers({
+    mousedown: (event, view) => {
+      const config = view.state.facet(tsFacet);
+      if (!config?.worker || !opts.gotoHandler) return false;
+
+      if (!(useMeta ? event.metaKey : event.ctrlKey)) return false;
+
+      event.preventDefault();
+
+      const pos = view.posAtCoords({
+        x: event.clientX,
+        y: event.clientY,
+      });
+
+      if (pos === null) return;
+
+      config.worker
+        .getHover({
+          path: config.path,
+          pos,
+        })
+        .then((hoverData: HoverInfo | null) => {
+          if (hoverData && opts.gotoHandler) {
+            opts.gotoHandler(config.path, hoverData, view);
+          }
+        });
+
+      return true;
+    },
+  });
+}
+
+export async function createTypescript(signal: AbortSignal, doc: string): Promise<Language> {
+  const { SandboxWorker } = await import('../sandbox-worker/index.js');
+  const innerWorker: Worker = new SandboxWorker(tsWorkerURL, { name: 'typescript' });
+  signal.addEventListener('abort', () => innerWorker.terminate());
+  const worker = Comlink.wrap<API>(innerWorker);
+  await worker.stlInit({
+    typescriptTypes: typescriptTypes!,
+    suggestedEnv: authData!
+      .flatMap((e) => e.opts)
+      .map((e) => e.read_env)
+      .filter((_) => typeof _ === 'string'),
+  });
+  await worker.initialize();
+  function renderTooltip({ quickInfo }: HoverInfo) {
+    const info = quickInfo as QuickInfo;
+    const elt = document.createElement('div');
+    elt.className = 'cm-lsp-hover-tooltip cm-lsp-documentation';
+    const documentation = displayPartsToString(info.documentation);
+    const tags = info.tags ? info.tags.map((tag) => tagToString(tag)).join('  \n\n') : '';
+
+    return {
+      dom: Object.assign(document.createElement('div'), {
+        innerHTML: markdown(
+          displayPartsToString(info.displayParts)
+            .split('\n')
+            .map((e) => '```typescript\n' + e + '\n```\n')
+            .join('') +
+            (documentation ? '\n\n---\n' + documentation : '') +
+            (tags ? '\n\n---\n' + tags : ''),
+        ),
+      }),
+    };
+  }
+  let runnerWorker: Worker;
+  let runnerAPI: Remote<RunnerAPI>;
+  const startRunner = () => {
+    if (runnerWorker) {
+      runnerWorker.terminate();
+      runnerAPI[Comlink.releaseProxy]();
+    }
+    runnerWorker = new SandboxWorker(runnerWorkerURL);
+    runnerAPI = Comlink.wrap<RunnerAPI>(runnerWorker);
+    runnerAPI.setLogger(
+      proxy((...args) => {
+        logger(...args);
+      }),
+    );
+  };
+  startRunner();
+
+  let logger: Logger;
+  return {
+    transport: undefined,
+    fileName: 'playground.mts',
+    extensions: [
+      typescriptLanguage,
+      tsFacet.of({ worker, path: '/play/playground.mts' }),
+      tsSync(),
+      tsLinter(),
+      autocompletion({
+        override: [tsAutocomplete()],
+      }),
+      tsHover({
+        renderTooltip,
+      }),
+      tsGoto({
+        gotoHandler(_path, hoverData, view) {
+          const def = hoverData.def?.[0] ?? hoverData.typeDef?.[0];
+          if (def?.originalFileName === '/play/playground.mts') {
+            view.dispatch({ selection: { anchor: def.textSpan.start, head: def.textSpan.start } });
+          }
+          console.log(def?.originalFileName);
+          return undefined;
+        },
+      }),
+      tsTwoslash(),
+    ],
+    doc,
+    setLogger(fn) {
+      logger = fn;
+    },
+    async expandLogHandle(handle) {
+      return await runnerAPI.expandLogHandle(handle);
+    },
+    async freeLogHandle(handle) {
+      return await runnerAPI.freeLogHandle(handle);
+    },
+    async setEnv(vars) {
+      return await runnerAPI.setEnv(vars);
+    },
+    async run(code, signal) {
+      signal.addEventListener('abort', startRunner);
+      try {
+        const transpiled = await worker.transform(code);
+        await runnerAPI.run(transpiled);
+      } catch (e) {
+        if (signal.aborted) {
+          logger({ type: 'error', parts: ['Aborted.'] });
+          return;
+        }
+        throw e;
+      } finally {
+        signal.removeEventListener('abort', startRunner);
+      }
+    },
+    async format(code) {
+      return worker.format(code);
+    },
+  };
+}

package/src/create.tsx

@@ -0,0 +1,44 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { signal } from '@preact/signals-core';
+import { Editor } from './codemirror/react';
+import { LogsContext } from './logs-context';
+import './playground.css';
+
+export type PlaygroundLanguage = 'python' | 'typescript' | 'http';
+
+export function createPlayground(props: {
+  lang: PlaygroundLanguage;
+  doc: string;
+  /** div.stl-snippet-request-container */
+  container: HTMLElement;
+}): () => Promise<void> {
+  const ready = new Promise<{ element: HTMLDivElement; onShow(): void }>((resolve) => {
+    const element = document.createElement('div');
+    const root = createRoot(element);
+    const nodes = (
+      <StrictMode>
+        <LogsContext value={signal([])}>
+          <Editor
+            {...props}
+            unmount={() => {
+              props.container.style.display = '';
+              root.unmount();
+              element.remove();
+            }}
+            onLoad={(onShow) => {
+              resolve({ element, onShow });
+            }}
+          />
+        </LogsContext>
+      </StrictMode>
+    );
+    root.render(nodes);
+  });
+  return () =>
+    ready.then(({ element, onShow }) => {
+      props.container.insertAdjacentElement('afterend', element);
+      props.container.style.display = 'none';
+      onShow();
+    });
+}

package/src/icon.tsx

@@ -0,0 +1,21 @@
+import style from '@stainless-api/docs-ui/style';
+
+export function PlaygroundIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width={16}
+      height={16}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className={'lucide ' + style.Icon}
+      aria-hidden="true"
+    >
+      <path d="m 1,2 h 1 a 4,4 0 0 1 4,4 v 1 m 5,15 H 10 A 4,4 0 0 1 6,18 V 6 a 4,4 0 0 1 4,-4 h 1 M 1,22 H 2 A 4,4 0 0 0 6,18 V 17 M 14.029059,8.147837 A 1.2853426,1.2853426 0 0 1 15.978924,7.0437277 L 22.40178,10.8959 a 1.2853426,1.2853426 0 0 1 0,2.208219 l -6.422856,3.852172 a 1.2853426,1.2853426 0 0 1 -1.949865,-1.105395 z" />
+    </svg>
+  );
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export default {
+  playgroundsBase: dirname(dirname(fileURLToPath(import.meta.url))),
+};

package/src/logs-context.ts

@@ -0,0 +1,5 @@
+import type { Signal } from '@preact/signals-core';
+import type { StateLog } from './Logs';
+import { createContext } from 'react';
+
+export const LogsContext = createContext<Signal<StateLog[]> | undefined>(undefined);