@intentius/chant-lexicon-e2b 0.0.0-stage → 0.124.32

package/src/lint/rules/index.ts

@@ -0,0 +1,9 @@
+import type { LintRule } from "@intentius/chant/lint/rule";
+import { templateSizeRule } from "./template-size";
+import { pinnedImageRule } from "./pinned-image";
+
+export { templateSizeRule } from "./template-size";
+export { pinnedImageRule, isFloatingImage } from "./pinned-image";
+
+/** All lint rules the e2b lexicon provides. */
+export const rules: LintRule[] = [templateSizeRule, pinnedImageRule];

package/src/lint/rules/pinned-image.ts

@@ -0,0 +1,41 @@
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import { ts } from "@intentius/chant/lint/typescript";
+import { at, property, templateLiterals } from "./template-literal";
+
+/** An image reference with no tag or digest, or the `latest` tag. */
+export function isFloatingImage(image: string): boolean {
+  if (image.includes("@")) return false;
+  const lastSegment = image.slice(image.lastIndexOf("/") + 1);
+  const colon = lastSegment.indexOf(":");
+  return colon === -1 || lastSegment.slice(colon + 1) === "latest";
+}
+
+/**
+ * E2B002: A template's base image is pinned.
+ *
+ * A steward keeps one sandbox for months, but a template is rebuilt whenever
+ * someone runs `e2b template create`. With `fromImage` untagged or on `latest`,
+ * two builds of the same declaration can carry different Node or git
+ * versions, and a steward made from the second behaves differently with no
+ * change in the repository.
+ */
+export const pinnedImageRule: LintRule = {
+  id: "E2B002",
+  severity: "warning",
+  category: "correctness",
+  description: "A Template's fromImage should name a tag other than latest, or a digest",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+    for (const obj of templateLiterals(sourceFile)) {
+      const image = property(obj, "fromImage", sourceFile);
+      if (image && ts.isStringLiteralLike(image) && image.text.length > 0 && isFloatingImage(image.text)) {
+        diagnostics.push(
+          at(sourceFile, image, "E2B002", "warning", `fromImage "${image.text}" is not pinned; name a version tag such as node:22-bookworm, or a digest.`),
+        );
+      }
+    }
+    return diagnostics;
+  },
+};

package/src/lint/rules/rules.test.ts

@@ -0,0 +1,46 @@
+import { describe, test, expect } from "vitest";
+import * as ts from "typescript";
+import type { LintContext } from "@intentius/chant/lint/rule";
+import { templateSizeRule, pinnedImageRule, isFloatingImage } from "./index";
+
+function ctx(code: string): LintContext {
+  return { sourceFile: ts.createSourceFile("steward.ts", code, ts.ScriptTarget.Latest, true), entities: [], filePath: "steward.ts" };
+}
+
+describe("e2b lint rules", () => {
+  describe("E2B001: template size", () => {
+    test("flags a fractional or zero cpuCount and an odd or negative memoryMB", () => {
+      const diags = templateSizeRule.check(ctx(`new Template({ name: "a", fromImage: "node:22", cpuCount: 1.5, memoryMB: 1023 });`));
+      expect(diags.map((d) => d.ruleId)).toEqual(["E2B001", "E2B001"]);
+      expect(diags[0].message).toContain("cpuCount 1.5");
+      expect(diags[1].message).toContain("memoryMB 1023");
+      expect(templateSizeRule.check(ctx(`new Template({ cpuCount: 0, memoryMB: -512 });`))).toHaveLength(2);
+    });
+
+    test("passes whole sizes, computed values and other constructors", () => {
+      expect(templateSizeRule.check(ctx(`new Template({ cpuCount: 2, memoryMB: 2048 });`))).toHaveLength(0);
+      expect(templateSizeRule.check(ctx(`new Template({ cpuCount: n, memoryMB: 1024 * 2 });`))).toHaveLength(0);
+      expect(templateSizeRule.check(ctx(`new Machine({ cpuCount: 1.5, memoryMB: 3 });`))).toHaveLength(0);
+    });
+
+    test("reports the line of the offending value", () => {
+      const [d] = templateSizeRule.check(ctx(`new Template({\n  name: "a",\n  memoryMB: 511,\n});`));
+      expect(d.line).toBe(3);
+    });
+  });
+
+  describe("E2B002: pinned base image", () => {
+    test("isFloatingImage spots no tag and latest, and accepts tags and digests", () => {
+      for (const floating of ["node", "node:latest", "ghcr.io/acme/base", "registry:5000/acme/base"]) expect(isFloatingImage(floating), floating).toBe(true);
+      for (const pinned of ["node:22-bookworm", "registry:5000/acme/base:1.2", "node@sha256:abc"]) expect(isFloatingImage(pinned), pinned).toBe(false);
+    });
+
+    test("warns on an unpinned fromImage literal", () => {
+      const diags = pinnedImageRule.check(ctx(`new Template({ name: "a", fromImage: "node:latest" });`));
+      expect(diags).toHaveLength(1);
+      expect(diags[0]).toMatchObject({ ruleId: "E2B002", severity: "warning" });
+      expect(pinnedImageRule.check(ctx(`new Template({ name: "a", fromImage: "node:22-bookworm" });`))).toHaveLength(0);
+      expect(pinnedImageRule.check(ctx(`new Template({ name: "a", fromImage: base });`))).toHaveLength(0);
+    });
+  });
+});

package/src/lint/rules/template-literal.ts

@@ -0,0 +1,42 @@
+/** Helpers the e2b lint rules share: finding `new Template({...})` literals and reporting on them. */
+
+import type { LintDiagnostic } from "@intentius/chant/lint/rule";
+import { ts } from "@intentius/chant/lint/typescript";
+
+/** The object literal passed to each `new Template({...})` in the file. */
+export function templateLiterals(sourceFile: ts.SourceFile): ts.ObjectLiteralExpression[] {
+  const found: ts.ObjectLiteralExpression[] = [];
+  function visit(node: ts.Node): void {
+    if (ts.isNewExpression(node)) {
+      const callee = node.expression;
+      const name = ts.isIdentifier(callee) ? callee.text : ts.isPropertyAccessExpression(callee) ? callee.name.text : "";
+      const arg = node.arguments?.[0];
+      if (name === "Template" && arg && ts.isObjectLiteralExpression(arg)) found.push(arg);
+    }
+    ts.forEachChild(node, visit);
+  }
+  visit(sourceFile);
+  return found;
+}
+
+/** The initializer of `key` in an object literal, when it is written there. */
+export function property(obj: ts.ObjectLiteralExpression, key: string, sourceFile: ts.SourceFile): ts.Expression | undefined {
+  for (const p of obj.properties) {
+    if (ts.isPropertyAssignment(p) && p.name.getText(sourceFile) === key) return p.initializer;
+  }
+  return undefined;
+}
+
+/** A numeric literal's value, a negated one included; `undefined` for anything computed. */
+export function numberLiteral(expr: ts.Expression): number | undefined {
+  if (ts.isNumericLiteral(expr)) return Number(expr.text);
+  if (ts.isPrefixUnaryExpression(expr) && expr.operator === ts.SyntaxKind.MinusToken && ts.isNumericLiteral(expr.operand)) {
+    return -Number(expr.operand.text);
+  }
+  return undefined;
+}
+
+export function at(sourceFile: ts.SourceFile, node: ts.Node, ruleId: string, severity: LintDiagnostic["severity"], message: string): LintDiagnostic {
+  const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+  return { file: sourceFile.fileName, line: line + 1, column: character + 1, ruleId, severity, message };
+}

package/src/lint/rules/template-size.ts

@@ -0,0 +1,36 @@
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import { at, numberLiteral, property, templateLiterals } from "./template-literal";
+
+/**
+ * E2B001: A template's CPU and memory are sizes E2B accepts.
+ *
+ * `cpuCount` is a whole number of vCPUs, at least one. `memoryMB` is a whole
+ * number of MiB, at least one and even: `e2b template create` refuses an odd
+ * one. Both are only checked when written as literals.
+ */
+export const templateSizeRule: LintRule = {
+  id: "E2B001",
+  severity: "error",
+  category: "correctness",
+  description: "A Template's cpuCount must be a positive integer and its memoryMB a positive even integer",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+    for (const obj of templateLiterals(sourceFile)) {
+      const cpu = property(obj, "cpuCount", sourceFile);
+      const cpuValue = cpu ? numberLiteral(cpu) : undefined;
+      if (cpu && cpuValue !== undefined && !(Number.isInteger(cpuValue) && cpuValue >= 1)) {
+        diagnostics.push(at(sourceFile, cpu, "E2B001", "error", `cpuCount ${cpuValue} is not a whole number of vCPUs; use 1 or more.`));
+      }
+      const mem = property(obj, "memoryMB", sourceFile);
+      const memValue = mem ? numberLiteral(mem) : undefined;
+      if (mem && memValue !== undefined && !(Number.isInteger(memValue) && memValue >= 2 && memValue % 2 === 0)) {
+        diagnostics.push(
+          at(sourceFile, mem, "E2B001", "error", `memoryMB ${memValue} is not a positive even number of MiB, which E2B requires.`),
+        );
+      }
+    }
+    return diagnostics;
+  },
+};

package/src/lsp/completions.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from "vitest";
+import { completions } from "./completions";
+
+const at = (linePrefix: string, wordAtCursor = "") => ({
+  uri: "file:///steward.ts",
+  content: linePrefix,
+  position: { line: 0, character: linePrefix.length },
+  wordAtCursor,
+  linePrefix,
+});
+
+describe("e2b LSP completions", () => {
+  it("offers Template after new", () => {
+    const items = completions(at("const s = new T", "T"));
+    expect(items.map((i) => i.label)).toEqual(["Template"]);
+    expect(items[0].detail).toBe("E2B::Template");
+  });
+
+  it("offers Template's properties inside its object", () => {
+    const labels = completions(at("new Template({ ")).map((i) => i.label);
+    for (const p of ["name", "fromImage", "run", "cpuCount", "memoryMB"]) expect(labels).toContain(p);
+  });
+});

package/src/lsp/completions.ts

@@ -0,0 +1,13 @@
+import type { CompletionContext, CompletionItem } from "@intentius/chant/lsp/types";
+import { LexiconIndex, lexiconCompletions } from "@intentius/chant/lsp/lexicon-providers";
+import { LEXICON_ENTRIES } from "../catalog";
+
+const index = new LexiconIndex(LEXICON_ENTRIES);
+
+/**
+ * e2b completions: `Template` after `new`, and its properties inside the
+ * object passed to it.
+ */
+export function completions(ctx: CompletionContext): CompletionItem[] {
+  return lexiconCompletions(ctx, index, "E2B sandbox template");
+}

package/src/lsp/hover.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { hover } from "./hover";
+
+const on = (word: string, lineText: string, content = lineText) => ({
+  uri: "file:///steward.ts",
+  content,
+  position: { line: 0, character: 0 },
+  word,
+  lineText,
+});
+
+describe("e2b LSP hover", () => {
+  it("describes Template with what it builds into and its properties", () => {
+    const info = hover(on("Template", "new Template({})"));
+    expect(info?.contents).toContain("E2B::Template");
+    expect(info?.contents).toContain("e2b template create");
+    expect(info?.contents).toContain("`fromImage: string`");
+  });
+
+  it("describes a Template property in a file that builds one", () => {
+    const info = hover(on("memoryMB", "  memoryMB: 2048,", 'new Template({\n  memoryMB: 2048,\n})'));
+    expect(info?.contents).toContain("even");
+  });
+
+  it("stays quiet on unrelated words", () => {
+    expect(hover(on("x", "const x = 42"))).toBeUndefined();
+    expect(hover(on("name", "const name = 'a'"))).toBeUndefined();
+  });
+});

package/src/lsp/hover.ts

@@ -0,0 +1,35 @@
+import type { HoverContext, HoverInfo } from "@intentius/chant/lsp/types";
+import { LEXICON_ENTRIES, TEMPLATE_PROPERTIES } from "../catalog";
+
+/**
+ * e2b hover: the `Template` class, with its properties and what it builds
+ * into, and each of its properties by name.
+ */
+export function hover(ctx: HoverContext): HoverInfo | undefined {
+  const { word } = ctx;
+  if (!word) return undefined;
+
+  const entry = LEXICON_ENTRIES[word];
+  if (entry) {
+    const lines = [
+      `**${word}**`,
+      "",
+      `E2B type: \`${entry.resourceType}\``,
+      "",
+      "*A sandbox template, written out as `e2b.<name>.Dockerfile` and built with `e2b template create`.*",
+      "",
+      ...Object.entries(TEMPLATE_PROPERTIES).map(
+        ([name, p]) => `- \`${name}${p.required ? "" : "?"}: ${p.type}\`: ${p.description}`,
+      ),
+    ];
+    return { contents: lines.join("\n") };
+  }
+
+  // A property name only means a Template property on a line that builds one
+  // or inside its object, so the hover stays quiet on an unrelated `name`.
+  const prop = TEMPLATE_PROPERTIES[word];
+  if (prop && /\bTemplate\b|^\s*\w+\??\s*:/.test(ctx.lineText ?? "") && ctx.content.includes("Template")) {
+    return { contents: `**${word}**${prop.required ? "" : " (optional)"}: \`${prop.type}\`\n\n${prop.description}` };
+  }
+  return undefined;
+}

package/src/op/ledger-sync.test.ts

@@ -0,0 +1,136 @@
+/**
+ * `ledger_sync`, the steward's reconciliation of its `chant/lifecycle` branch
+ * with the repository's, run against real git: a bare repository, the
+ * steward's long-lived clone and a second checkout that approves gates.
+ *
+ * The case it exists for: the steward keeps run records on its local branch
+ * only (chant pushes facts, not runs), so an approval pushed from elsewhere
+ * leaves the two branches diverged, and chant refuses to read a diverged
+ * ledger.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { LEDGER_SYNC_FN } from "./runtime";
+
+const BRANCH = "refs/heads/chant/lifecycle";
+const IDENTITY = ["-c", "user.name=test", "-c", "user.email=test@example.com"];
+
+let root: string;
+
+function git(cwd: string, ...args: string[]): string {
+  return execFileSync("git", [...IDENTITY, ...args], { cwd, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+}
+
+/** Append `line` to `path` on the clone's ledger branch, as chant's plumbing does: no checkout. */
+function append(cwd: string, path: string, line: string): void {
+  const parent = (() => {
+    try {
+      return git(cwd, "rev-parse", "--verify", "-q", BRANCH);
+    } catch {
+      return "";
+    }
+  })();
+  const existing = parent ? (() => { try { return git(cwd, "show", `${parent}:${path}`) + "\n"; } catch { return ""; } })() : "";
+  const blob = execFileSync("git", ["hash-object", "-w", "--stdin"], { cwd, input: `${existing}${line}\n`, encoding: "utf8" }).trim();
+  const env = { ...process.env, GIT_INDEX_FILE: join(cwd, ".git", "test-index") };
+  if (parent) execFileSync("git", ["read-tree", parent], { cwd, env });
+  else execFileSync("git", ["read-tree", "--empty"], { cwd, env });
+  execFileSync("git", ["update-index", "--add", "--cacheinfo", `100644,${blob},${path}`], { cwd, env });
+  const tree = execFileSync("git", ["write-tree"], { cwd, env, encoding: "utf8" }).trim();
+  const commit = execFileSync("git", [...IDENTITY, "commit-tree", tree, ...(parent ? ["-p", parent] : []), "-m", line], { cwd, encoding: "utf8" }).trim();
+  git(cwd, "update-ref", BRANCH, commit);
+}
+
+function sync(cwd: string): string {
+  git(cwd, "fetch", "--quiet", "origin", "+refs/heads/*:refs/remotes/origin/*");
+  return execFileSync("bash", ["-c", `${LEDGER_SYNC_FN}\nledger_sync`], { cwd, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
+}
+
+function remoteFile(path: string): string[] {
+  return git(join(root, "remote.git"), "show", `chant/lifecycle:${path}`).split("\n");
+}
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), "e2b-ledger-"));
+  execFileSync("git", ["init", "--quiet", "--bare", "remote.git"], { cwd: root });
+  for (const clone of ["steward", "laptop"]) {
+    execFileSync("git", ["clone", "--quiet", join(root, "remote.git"), clone], { cwd: root, stdio: "pipe" });
+  }
+});
+
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true });
+});
+
+describe("ledger_sync", () => {
+  it("does nothing without a local ledger", () => {
+    sync(join(root, "steward"));
+    expect(() => git(join(root, "remote.git"), "rev-parse", "--verify", "chant/lifecycle")).toThrow();
+  });
+
+  it("pushes local-only run records when the steward is only ahead", () => {
+    const steward = join(root, "steward");
+    append(steward, "local/runs__deploy.jsonl", '{"id":"r1"}');
+    sync(steward);
+    expect(remoteFile("local/runs__deploy.jsonl")).toEqual(['{"id":"r1"}']);
+  });
+
+  it("merges a diverged ledger, keeping both sides' lines, and pushes it", () => {
+    const steward = join(root, "steward");
+    const laptop = join(root, "laptop");
+
+    // The steward's gate: its pending fact is pushed, as chant pushes it.
+    append(steward, "_gates/deploy.jsonl", '{"kind":"pending"}');
+    git(steward, "push", "--quiet", "origin", `${BRANCH}:${BRANCH}`);
+    // Its run record stays local, as chant leaves it.
+    append(steward, "local/runs__deploy.jsonl", '{"id":"r1","status":"gated"}');
+
+    // An approval from another checkout.
+    git(laptop, "fetch", "--quiet", "origin", `+${BRANCH}:${BRANCH}`);
+    append(laptop, "_gates/deploy.jsonl", '{"kind":"resolution"}');
+    git(laptop, "push", "--quiet", "origin", `${BRANCH}:${BRANCH}`);
+
+    const stderr = sync(steward);
+    void stderr;
+
+    expect(remoteFile("_gates/deploy.jsonl")).toEqual(['{"kind":"pending"}', '{"kind":"resolution"}']);
+    expect(remoteFile("local/runs__deploy.jsonl")).toEqual(['{"id":"r1","status":"gated"}']);
+    // Both tips are ancestors of the merge, so neither side diverges from it again.
+    const tip = git(steward, "rev-parse", BRANCH);
+    expect(git(join(root, "remote.git"), "rev-parse", "chant/lifecycle")).toBe(tip);
+    git(laptop, "fetch", "--quiet", "origin", `${BRANCH}:${BRANCH}`);
+    expect(git(laptop, "rev-parse", BRANCH)).toBe(tip);
+  });
+
+  it("unions an append-only file both sides wrote to", () => {
+    const steward = join(root, "steward");
+    const laptop = join(root, "laptop");
+    append(steward, "local/runs__deploy.jsonl", '{"id":"r1"}');
+    git(steward, "push", "--quiet", "origin", `${BRANCH}:${BRANCH}`);
+    append(steward, "local/runs__deploy.jsonl", '{"id":"r2"}');
+    git(laptop, "fetch", "--quiet", "origin", `+${BRANCH}:${BRANCH}`);
+    append(laptop, "local/runs__deploy.jsonl", '{"id":"l1"}');
+    git(laptop, "push", "--quiet", "origin", `${BRANCH}:${BRANCH}`);
+
+    sync(steward);
+    expect(remoteFile("local/runs__deploy.jsonl")).toEqual(['{"id":"r1"}', '{"id":"l1"}', '{"id":"r2"}']);
+  });
+
+  it("leaves a steward that is behind for chant's own fetch", () => {
+    const steward = join(root, "steward");
+    const laptop = join(root, "laptop");
+    append(steward, "_gates/deploy.jsonl", '{"kind":"pending"}');
+    git(steward, "push", "--quiet", "origin", `${BRANCH}:${BRANCH}`);
+    git(laptop, "fetch", "--quiet", "origin", `+${BRANCH}:${BRANCH}`);
+    append(laptop, "_gates/deploy.jsonl", '{"kind":"resolution"}');
+    git(laptop, "push", "--quiet", "origin", `${BRANCH}:${BRANCH}`);
+
+    const before = git(steward, "rev-parse", BRANCH);
+    sync(steward);
+    expect(git(steward, "rev-parse", BRANCH)).toBe(before);
+  });
+});