@checkstack/ui 1.11.0 → 1.12.0

package/src/components/CodeEditor/importSpecifiers.test.ts

@@ -0,0 +1,286 @@
+import { describe, expect, test } from "bun:test";
+import {
+  classifyBuiltinModule,
+  extractBuiltinModuleSpecifiers,
+  importablePackageNames,
+  importSpecifierCompletionContext,
+  mergeImportCompletionEntries,
+  packageNameFromSpecifier,
+  parseBareImportSpecifiers,
+  planAcquisitions,
+} from "./importSpecifiers";
+
+describe("packageNameFromSpecifier", () => {
+  test("plain", () => {
+    expect(packageNameFromSpecifier("lodash")).toBe("lodash");
+  });
+  test("subpath", () => {
+    expect(packageNameFromSpecifier("lodash/fp")).toBe("lodash");
+  });
+  test("scoped", () => {
+    expect(packageNameFromSpecifier("@babel/core")).toBe("@babel/core");
+  });
+  test("scoped subpath", () => {
+    expect(packageNameFromSpecifier("@scope/pkg/sub/deep")).toBe("@scope/pkg");
+  });
+});
+
+describe("parseBareImportSpecifiers", () => {
+  test("default, named, namespace, side-effect, type", () => {
+    const src = [
+      `import _ from "lodash";`,
+      `import { z } from "zod";`,
+      `import * as React from "react";`,
+      `import "side-effect-pkg";`,
+      `import type { Dayjs } from "dayjs";`,
+    ].join("\n");
+    const specs = parseBareImportSpecifiers(src);
+    expect(specs.sort()).toEqual(
+      ["dayjs", "lodash", "react", "side-effect-pkg", "zod"].sort(),
+    );
+  });
+
+  test("export-from, dynamic import, require", () => {
+    const src = [
+      `export { x } from "pkg-a";`,
+      `export * from "pkg-b";`,
+      `const p = await import("pkg-c");`,
+      `const q = require("pkg-d");`,
+    ].join("\n");
+    expect(parseBareImportSpecifiers(src).sort()).toEqual(
+      ["pkg-a", "pkg-b", "pkg-c", "pkg-d"].sort(),
+    );
+  });
+
+  test("ignores relative, node:, bun, and context", () => {
+    const src = [
+      `import a from "./local";`,
+      `import b from "../up";`,
+      `import { readFile } from "node:fs";`,
+      `import { Glob } from "bun";`,
+      `const c = context.trigger;`,
+      `import "context";`,
+    ].join("\n");
+    expect(parseBareImportSpecifiers(src)).toEqual([]);
+  });
+
+  test("scoped + subpath reduce to package name, deduped", () => {
+    const src = [
+      `import { debounce } from "lodash/debounce";`,
+      `import _ from "lodash";`,
+      `import { transform } from "@babel/core/lib/x";`,
+    ].join("\n");
+    expect(parseBareImportSpecifiers(src).sort()).toEqual(
+      ["@babel/core", "lodash"].sort(),
+    );
+  });
+
+  test("the lodash named-import case (acceptance)", () => {
+    expect(parseBareImportSpecifiers(`import { debounce } from "lodash";`)).toEqual(
+      ["lodash"],
+    );
+  });
+});
+
+describe("planAcquisitions", () => {
+  test("returns only new specifiers, order-stable, deduped", () => {
+    const plan = planAcquisitions({
+      specifiers: ["lodash", "zod", "lodash", "react"],
+      acquired: new Set(["zod"]),
+    });
+    expect(plan).toEqual(["lodash", "react"]);
+  });
+  test("empty when all acquired", () => {
+    expect(
+      planAcquisitions({
+        specifiers: ["a", "b"],
+        acquired: new Set(["a", "b"]),
+      }),
+    ).toEqual([]);
+  });
+});
+
+describe("importSpecifierCompletionContext", () => {
+  // The `partial` text starts just after the opening quote; the
+  // `replaceFromColumn` is its 1-based start column. For a line like
+  // `import {} from "lod` the partial is `lod` starting at column 17.
+  test("from-clause double quote", () => {
+    const line = `import {} from "lod`;
+    const ctx = importSpecifierCompletionContext(line);
+    expect(ctx).toEqual({ partial: "lod", replaceFromColumn: 17 });
+  });
+
+  test("from-clause single quote", () => {
+    const line = `import x from 'lo`;
+    expect(importSpecifierCompletionContext(line)).toEqual({
+      partial: "lo",
+      replaceFromColumn: 16,
+    });
+  });
+
+  test("namespace import (import * as x from)", () => {
+    const line = `import * as _ from "lod`;
+    expect(importSpecifierCompletionContext(line)?.partial).toBe("lod");
+  });
+
+  test("export ... from", () => {
+    const line = `export { x } from "lod`;
+    expect(importSpecifierCompletionContext(line)?.partial).toBe("lod");
+  });
+
+  test("bare side-effect import", () => {
+    const line = `import "lo`;
+    expect(importSpecifierCompletionContext(line)).toEqual({
+      partial: "lo",
+      replaceFromColumn: 9,
+    });
+  });
+
+  test("dynamic import()", () => {
+    const line = `const m = await import("lo`;
+    expect(importSpecifierCompletionContext(line)?.partial).toBe("lo");
+  });
+
+  test("require()", () => {
+    const line = `const m = require("lo`;
+    expect(importSpecifierCompletionContext(line)?.partial).toBe("lo");
+  });
+
+  test("scoped partial keeps the slash", () => {
+    const line = `import {} from "@scope/`;
+    expect(importSpecifierCompletionContext(line)?.partial).toBe("@scope/");
+  });
+
+  test("empty partial right after the opening quote", () => {
+    // `import {} from "` is 16 chars; the cursor sits at column 17 where the
+    // (empty) specifier begins.
+    const line = `import {} from "`;
+    expect(importSpecifierCompletionContext(line)).toEqual({
+      partial: "",
+      replaceFromColumn: 17,
+    });
+  });
+
+  test("returns null when not in an import string", () => {
+    expect(importSpecifierCompletionContext(`const x = 1;`)).toBeNull();
+    expect(importSpecifierCompletionContext(`const s = "hello`)).toBeNull();
+    expect(importSpecifierCompletionContext(`foo("bar`)).toBeNull();
+  });
+
+  test("returns null once the import string is already closed", () => {
+    expect(
+      importSpecifierCompletionContext(`import {} from "lodash"`),
+    ).toBeNull();
+    expect(importSpecifierCompletionContext(`import "lodash";`)).toBeNull();
+  });
+});
+
+describe("importablePackageNames", () => {
+  test("excludes @types/* companions", () => {
+    expect(
+      importablePackageNames(["lodash", "@types/lodash", "zod"]),
+    ).toEqual(["lodash", "zod"]);
+  });
+  test("dedupes and sorts", () => {
+    expect(
+      importablePackageNames(["zod", "lodash", "lodash", "@babel/core"]),
+    ).toEqual(["@babel/core", "lodash", "zod"]);
+  });
+  test("scoped non-@types names are kept", () => {
+    expect(importablePackageNames(["@babel/core", "@types/babel__core"])).toEqual(
+      ["@babel/core"],
+    );
+  });
+});
+
+describe("extractBuiltinModuleSpecifiers", () => {
+  // A small fixture mirroring how @types/node + bun-types declare importable
+  // modules (top-level `declare module "<spec>"`) alongside wildcard / asset
+  // shims that must be filtered out.
+  const fixture = [
+    `declare module "node:fs" { export function readFile(): void; }`,
+    `declare module "fs" { export function readFile(): void; }`,
+    `declare module 'node:path' { export const sep: string; }`,
+    `declare module "bun" { export const version: string; }`,
+    `declare module "bun:test" { export function test(): void; }`,
+    // Noise that must be dropped:
+    `declare module "*" { const c: unknown; export default c; }`,
+    `declare module "*.css" { const c: string; export default c; }`,
+    `declare module "*.txt" { const c: string; export default c; }`,
+  ].join("\n");
+
+  test("keeps real importable specifiers, drops wildcard/asset shims", () => {
+    expect(extractBuiltinModuleSpecifiers(fixture)).toEqual([
+      "bun",
+      "bun:test",
+      "fs",
+      "node:fs",
+      "node:path",
+    ]);
+  });
+
+  test("dedupes a repeated declaration", () => {
+    const src = `declare module "fs" {}\ndeclare module "fs" {}`;
+    expect(extractBuiltinModuleSpecifiers(src)).toEqual(["fs"]);
+  });
+
+  test("does not match an augmentation indented as a non-statement", () => {
+    // A `declare module` nested under another block won't be at line start;
+    // our anchor (`^\s*`) still allows leading whitespace, which is correct
+    // for real top-level declarations. This asserts the simple line-start
+    // behavior: a name on its own line is captured.
+    const src = `  declare module "node:os" {}`;
+    expect(extractBuiltinModuleSpecifiers(src)).toEqual(["node:os"]);
+  });
+
+  test("empty input yields empty list", () => {
+    expect(extractBuiltinModuleSpecifiers("")).toEqual([]);
+  });
+});
+
+describe("classifyBuiltinModule", () => {
+  test("bun and bun: specifiers are Bun built-ins", () => {
+    expect(classifyBuiltinModule("bun").detail).toBe("Bun built-in");
+    expect(classifyBuiltinModule("bun:test").detail).toBe("Bun built-in");
+  });
+  test("node and bare builtins are Node.js", () => {
+    expect(classifyBuiltinModule("node:fs").detail).toBe("Node.js");
+    expect(classifyBuiltinModule("fs").detail).toBe("Node.js");
+  });
+});
+
+describe("mergeImportCompletionEntries", () => {
+  test("built-ins always present; installed packages merged; sorted", () => {
+    const merged = mergeImportCompletionEntries({
+      builtins: ["node:fs", "bun"],
+      installedPackages: ["lodash", "zod"],
+    });
+    expect(merged.map((e) => e.name)).toEqual([
+      "bun",
+      "lodash",
+      "node:fs",
+      "zod",
+    ]);
+    expect(merged.find((e) => e.name === "bun")?.detail).toBe("Bun built-in");
+    expect(merged.find((e) => e.name === "node:fs")?.detail).toBe("Node.js");
+    expect(merged.find((e) => e.name === "lodash")?.detail).toBe(
+      "installed package",
+    );
+  });
+
+  test("built-ins present even with an empty allowlist", () => {
+    const merged = mergeImportCompletionEntries({
+      builtins: ["node:fs", "bun"],
+      installedPackages: [],
+    });
+    expect(merged.map((e) => e.name)).toEqual(["bun", "node:fs"]);
+  });
+
+  test("an installed package colliding with a built-in is labelled installed", () => {
+    const merged = mergeImportCompletionEntries({
+      builtins: ["fs"],
+      installedPackages: ["fs"],
+    });
+    expect(merged).toEqual([{ name: "fs", detail: "installed package" }]);
+  });
+});

package/src/components/CodeEditor/importSpecifiers.ts

@@ -0,0 +1,267 @@
+// Pure helpers for the editor's lazy Automatic Type Acquisition (ATA) loop.
+//
+// `parseBareImportSpecifiers` extracts the BARE package specifiers a script
+// buffer imports/requires, so the editor can fetch + register only those
+// packages' `.d.ts` on demand. `planAcquisitions` diffs that set against the
+// already-acquired set so re-parsing on every keystroke never refetches.
+//
+// Both are pure + unit-tested (no monaco/DOM), per the no-DOM-tests rule.
+
+/** Bare specifiers we never try to acquire (already typed or runtime built-ins). */
+const IGNORED_SPECIFIERS = new Set<string>(["context"]);
+
+/**
+ * True for specifiers the editor must NOT try to acquire:
+ *  - relative paths (`./x`, `../x`) — not packages.
+ *  - `node:`-prefixed built-ins — already covered by the bundled @types/node.
+ *  - `bun` / `bun:*` — covered by the bundled bun-types.
+ *  - the injected `context` ambient global.
+ */
+function isIgnoredSpecifier(specifier: string): boolean {
+  if (specifier.length === 0) return true;
+  if (specifier.startsWith("./") || specifier.startsWith("../")) return true;
+  if (specifier === "." || specifier === "..") return true;
+  if (specifier.startsWith("node:")) return true;
+  if (specifier === "bun" || specifier.startsWith("bun:")) return true;
+  return IGNORED_SPECIFIERS.has(specifier);
+}
+
+/**
+ * Reduce a possibly-subpath specifier to the package name to acquire:
+ *  - `lodash/fp`        -> `lodash`
+ *  - `@scope/pkg/sub`   -> `@scope/pkg`
+ *  - `lodash`           -> `lodash`
+ *  - `@scope/pkg`       -> `@scope/pkg`
+ */
+export function packageNameFromSpecifier(specifier: string): string {
+  if (specifier.startsWith("@")) {
+    const parts = specifier.split("/");
+    return parts.slice(0, 2).join("/");
+  }
+  return specifier.split("/")[0];
+}
+
+/**
+ * Parse the unique BARE package names imported/required by a script buffer.
+ * Handles every import/require form:
+ *   import x from "p"; import {a} from "p"; import * as p from "p";
+ *   import "p"; import type {T} from "p"; export {a} from "p";
+ *   export * from "p"; const x = require("p"); await import("p")
+ * Ignores relative paths, `node:`/`bun` built-ins, and the `context` global.
+ * Subpath imports are reduced to their package name.
+ */
+export function parseBareImportSpecifiers(source: string): string[] {
+  const found = new Set<string>();
+
+  const patterns: RegExp[] = [
+    // import ... from "p"  /  export ... from "p"  (incl. import type)
+    /\b(?:import|export)\b[^;\n]*?\bfrom\s*["']([^"']+)["']/g,
+    // bare side-effect import:  import "p"
+    /\bimport\s*["']([^"']+)["']/g,
+    // dynamic import:  import("p")
+    /\bimport\s*\(\s*["']([^"']+)["']\s*\)/g,
+    // require:  require("p")
+    /\brequire\s*\(\s*["']([^"']+)["']\s*\)/g,
+  ];
+
+  for (const pattern of patterns) {
+    let match: RegExpExecArray | null = pattern.exec(source);
+    while (match !== null) {
+      const specifier = match[1];
+      if (!isIgnoredSpecifier(specifier)) {
+        found.add(packageNameFromSpecifier(specifier));
+      }
+      match = pattern.exec(source);
+    }
+  }
+
+  return [...found];
+}
+
+/**
+ * Given the specifiers currently in the buffer and the set already acquired,
+ * return only the NEW ones to fetch (order-stable). Pure planning step so the
+ * ATA loop never refetches an already-registered package.
+ */
+export function planAcquisitions({
+  specifiers,
+  acquired,
+}: {
+  specifiers: string[];
+  acquired: ReadonlySet<string>;
+}): string[] {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const specifier of specifiers) {
+    if (acquired.has(specifier) || seen.has(specifier)) continue;
+    seen.add(specifier);
+    out.push(specifier);
+  }
+  return out;
+}
+
+/**
+ * The cursor's position inside an import-string literal, as detected from the
+ * text on the current line up to (but not including) the cursor.
+ *
+ * `partial` is the specifier text already typed between the opening quote and
+ * the cursor; `replaceFromColumn` is the 1-based editor column of the FIRST
+ * specifier character (i.e. just after the opening quote), so a completion can
+ * replace the whole partial specifier without touching the quotes.
+ */
+export interface ImportSpecifierCompletionContext {
+  partial: string;
+  /** 1-based column where the specifier text starts (just after the quote). */
+  replaceFromColumn: number;
+}
+
+// The import/require lead-ins that put a following string literal in
+// module-specifier position. Each is matched at the END of the line-up-to-
+// cursor, immediately followed by an OPEN (unclosed) quote + the partial text.
+//
+//   ... from "      ->  from-clause (import/export)
+//   import "        ->  bare side-effect import
+//   import(" / require("  ->  dynamic import / require call
+//
+// We deliberately match only an UNCLOSED string (no closing quote between the
+// opening quote and the cursor) so completions never fire once the specifier
+// string is already closed.
+const IMPORT_STRING_LEAD_INS: RegExp[] = [
+  // `from "partial`  (import ... from / export ... from)
+  /\bfrom\s*(["'])([^"']*)$/,
+  // `import "partial`  (bare side-effect import) — `import` not followed by `(`
+  /\bimport\s*(["'])([^"']*)$/,
+  // `import("partial`  (dynamic import)
+  /\bimport\s*\(\s*(["'])([^"']*)$/,
+  // `require("partial`  (CJS require)
+  /\brequire\s*\(\s*(["'])([^"']*)$/,
+];
+
+/**
+ * Detect whether the cursor sits inside an import/require module-specifier
+ * STRING, and if so return the partial specifier + where it starts. Returns
+ * null otherwise (so a completion provider can bail and not pollute normal
+ * positions).
+ *
+ * `lineUpToCursor` is the current line's text from column 1 up to the cursor
+ * (exclusive). Pure + unit-tested; no editor/DOM dependency.
+ */
+export function importSpecifierCompletionContext(
+  lineUpToCursor: string,
+): ImportSpecifierCompletionContext | null {
+  for (const pattern of IMPORT_STRING_LEAD_INS) {
+    const match = pattern.exec(lineUpToCursor);
+    if (!match) continue;
+    const partial = match[2];
+    // The partial starts right after the opening quote. The quote's index is
+    // (matchEnd - partial.length - 1); the partial's first char is one past
+    // that. Editor columns are 1-based, so add 1 to the 0-based index.
+    const partialStartIndex = lineUpToCursor.length - partial.length;
+    return { partial, replaceFromColumn: partialStartIndex + 1 };
+  }
+  return null;
+}
+
+/**
+ * Filter a raw manifest package-name list down to the names a user can
+ * actually `import`: drop `@types/*` companions (you import `lodash`, never
+ * `@types/lodash`), dedupe, and sort. Pure + unit-tested.
+ */
+export function importablePackageNames(names: readonly string[]): string[] {
+  const out = new Set<string>();
+  for (const name of names) {
+    if (name.startsWith("@types/")) continue;
+    out.add(name);
+  }
+  return [...out].toSorted((a, b) => a.localeCompare(b));
+}
+
+/**
+ * Extract the importable built-in module specifiers from bundled stdlib
+ * declaration text (`@types/node` + `bun-types`). Every importable built-in is
+ * declared as a top-level `declare module "<spec>"` (e.g. `node:fs`, bare `fs`,
+ * `bun`, `bun:test`), so the authoritative name set is exactly those names.
+ *
+ * Filter rules (documented):
+ *  - Keep any `declare module "<spec>"` name that is a real specifier.
+ *  - DROP names containing a star character — those are wildcard / asset-glob
+ *    ambient shims (e.g. text/css asset globs or a "bun.lock" path glob), not
+ *    importable runtime modules.
+ *
+ * Pure + unit-tested. Used at BUILD time by the stdlib-types generator to emit
+ * the static name list the editor ships.
+ */
+export function extractBuiltinModuleSpecifiers(
+  declarationText: string,
+): string[] {
+  const out = new Set<string>();
+  // Top-level `declare module "<spec>"` (single or double quotes), anchored to
+  // a statement start (per line, via the `m` flag) so we don't match
+  // augmentation blocks nested deeper — though stdlib's importable modules are
+  // all declared at top level anyway.
+  const pattern = /^\s*declare\s+module\s+["']([^"']+)["']/gm;
+  let match: RegExpExecArray | null = pattern.exec(declarationText);
+  while (match !== null) {
+    const spec = match[1];
+    // Drop wildcard / asset-glob ambient shims (any name containing a star,
+    // e.g. an asset-glob like a ".txt" shim or a "bun.lock" path glob): those
+    // are ambient module shims, not importable runtime modules.
+    if (!spec.includes("*")) {
+      out.add(spec);
+    }
+    match = pattern.exec(declarationText);
+  }
+  return [...out].toSorted((a, b) => a.localeCompare(b));
+}
+
+/** A built-in import specifier plus how it should read in the completion list. */
+export interface BuiltinModuleSpecifier {
+  name: string;
+  /** Completion `detail`, e.g. "Node.js" or "Bun built-in". */
+  detail: string;
+}
+
+/**
+ * Classify a built-in specifier for completion display: `bun` and any
+ * `bun:`-prefixed specifier are Bun built-ins; everything else (the
+ * `node:`-prefixed and bare node builtins) is Node.js. Pure.
+ */
+export function classifyBuiltinModule(name: string): BuiltinModuleSpecifier {
+  const isBun = name === "bun" || name.startsWith("bun:");
+  return { name, detail: isBun ? "Bun built-in" : "Node.js" };
+}
+
+/** One entry in the merged import-name completion list. */
+export interface ImportCompletionEntry {
+  name: string;
+  /** Completion `detail`, e.g. "installed package" / "Node.js" / "Bun built-in". */
+  detail: string;
+}
+
+/**
+ * Merge the always-available runtime built-ins with the injected installed
+ * package names into the final import-name completion list. Built-ins are
+ * always present (importable in the sandbox regardless of the allowlist);
+ * installed packages augment them. Deduped (installed names win their own
+ * `detail`) and sorted. Pure + unit-tested.
+ */
+export function mergeImportCompletionEntries({
+  builtins,
+  installedPackages,
+}: {
+  builtins: readonly string[];
+  installedPackages: readonly string[];
+}): ImportCompletionEntry[] {
+  const byName = new Map<string, ImportCompletionEntry>();
+  for (const name of builtins) {
+    const { detail } = classifyBuiltinModule(name);
+    byName.set(name, { name, detail });
+  }
+  // Installed packages are already `@types/*`-free + deduped by the caller, but
+  // be defensive. An installed package name that collides with a built-in is
+  // re-labelled as an installed package (unlikely, but deterministic).
+  for (const name of installedPackages) {
+    byName.set(name, { name, detail: "installed package" });
+  }
+  return [...byName.values()].toSorted((a, b) => a.name.localeCompare(b.name));
+}

package/src/components/CodeEditor/index.ts

@@ -5,6 +5,8 @@ export {
   type TemplateProperty,
   type ShellEnvVar,
   type EditorMarker,
+  type AcquireTypes,
+  type AcquiredTypeFile,
 } from "./CodeEditor";
 
 export {
@@ -18,3 +20,25 @@ export {
   integrationScriptContext,
   type ScriptEditorContext,
 } from "./scriptContext";
+
+// Pure helper used by consumers (e.g. script-packages-frontend) to derive the
+// importable package-name list for the editor's import-specifier completions.
+export { importablePackageNames } from "./importSpecifiers";
+
+// Headless script validator: type-check scripts against their generated
+// `context` types without a mounted editor (drives the same standalone TS
+// worker). Used by the automation editor to surface type errors on collapsed
+// script-action cards.
+export {
+  validateTypeScriptSources,
+  type ScriptValidationInput,
+  type ScriptDiagnostic,
+} from "./validateScripts";
+
+// Subscribe to / query the monaco-vscode "services ready" transition so a
+// consumer (the automation editor's script validator + its hidden services
+// booter) can react the moment the first editor initializes the services.
+export {
+  onVscodeServicesReady,
+  areVscodeServicesReady,
+} from "./monacoTsService";