@engine262/engine262 0.0.1-01e9fa95a4e8a1c042efd00492309a2de4998fd0

package/lib-src/inspector/context.mts

@@ -0,0 +1,361 @@
+import type { Protocol } from 'devtools-protocol';
+import { getInspector } from './objects/index.mts';
+import type { Inspector } from './index.mts';
+import {
+  EnsureCompletion, JSStringValue, ManagedRealm, ObjectValue, SymbolValue, ThrowCompletion, Value,
+  getHostDefinedErrorDetails,
+  type Agent,
+  type CallFrame,
+  type CallSite,
+  type NullValue,
+  type ValueCompletion,
+  getCurrentStack,
+  isECMAScriptFunctionObject,
+  SymbolDescriptiveString,
+  type EnvironmentRecordWithThisBinding,
+  EnvironmentRecord,
+  DeclarativeEnvironmentRecord,
+  ObjectEnvironmentRecord,
+  FunctionEnvironmentRecord,
+  GlobalEnvironmentRecord,
+  ModuleEnvironmentRecord,
+  OrdinaryObjectCreate,
+  Descriptor,
+  isArgumentExoticObject,
+  surroundingAgent,
+  IsAccessorDescriptor,
+  isIntegerIndex,
+  type OrdinaryObject,
+} from '#self';
+
+interface InspectedRealmDescriptor {
+  readonly realm: ManagedRealm;
+  readonly descriptor: Protocol.Runtime.ExecutionContextDescription;
+  readonly agent: Agent;
+  detach(): void;
+}
+
+export class InspectorContext {
+  #io: Inspector;
+
+  constructor(io: Inspector) {
+    this.#io = io;
+  }
+
+  realms: (InspectedRealmDescriptor | undefined)[] = [];
+
+  attachRealm(realm: ManagedRealm, agent: Agent) {
+    const id = this.realms.length;
+    const descriptor: Protocol.Runtime.ExecutionContextDescription = {
+      id,
+      origin: realm.HostDefined.specifier || 'vm://repl',
+      name: realm.HostDefined.name || 'engine262',
+      uniqueId: id.toString(),
+    };
+    this.realms.push({
+      realm,
+      descriptor,
+      agent,
+      detach: () => {
+        realm.HostDefined.attachingInspector = oldInspector;
+        realm.HostDefined.attachingInspectorReportError = function attachingInspectorReportError(realm, error) {
+          if (this.attachingInspector && realm instanceof ManagedRealm) {
+            (this.attachingInspector as Inspector).console(realm, 'error' as Protocol.Runtime.ConsoleAPICalledEventType, [error]);
+          }
+        };
+      },
+    });
+    const oldInspector = realm.HostDefined.attachingInspector;
+    realm.HostDefined.attachingInspector = this.#io;
+    this.#io.sendEvent['Runtime.executionContextCreated']({ context: descriptor });
+  }
+
+  detachAgent(agent: Agent) {
+    for (const realm of this.realms) {
+      if (realm?.agent === agent) {
+        this.detachRealm(realm.realm);
+      }
+    }
+  }
+
+  detachRealm(realm: ManagedRealm) {
+    const index = this.realms.findIndex((c) => c?.realm === realm);
+    if (index === -1) {
+      return;
+    }
+    const { descriptor } = this.realms[index]!;
+    realm.HostDefined.attachingInspector = undefined;
+    realm.HostDefined.attachingInspectorReportError = undefined;
+    this.realms[index] = undefined;
+    this.#io.sendEvent['Runtime.executionContextDestroyed']({ executionContextId: descriptor.id, executionContextUniqueId: descriptor.uniqueId });
+  }
+
+  getRealm(realm: ManagedRealm | string | number | undefined) {
+    if (realm === undefined) {
+      if (surroundingAgent.runningExecutionContext && surroundingAgent.currentRealmRecord instanceof ManagedRealm) {
+        realm = surroundingAgent.currentRealmRecord;
+      } else {
+        return undefined;
+      }
+    }
+    if (typeof realm === 'string') {
+      return this.realms.find((c) => c?.descriptor.uniqueId === realm);
+    } else if (typeof realm === 'number') {
+      return this.realms[realm];
+    }
+    return this.realms.find((c) => c?.realm === realm);
+  }
+
+  /** @deprecated in this case we are guessing the realm should be using, which may create bad result */
+  getAnyRealm() {
+    return this.realms.find(Boolean);
+  }
+
+  #idToObject = new Map<string, ObjectValue | SymbolValue>();
+
+  #objectToId = new Map<ObjectValue | SymbolValue, string>();
+
+  #objectCounter = 1;
+
+  #internObject(object: ObjectValue | SymbolValue, group = 'default') {
+    if (this.#objectToId.has(object)) {
+      return this.#objectToId.get(object)!;
+    }
+    const id = `${group}:${this.#objectCounter}`;
+    this.#objectCounter += 1;
+    this.#idToObject.set(id, object);
+    this.#objectToId.set(object, id);
+    return id;
+  }
+
+  releaseObject(id: string) {
+    const object = this.#idToObject.get(id);
+    if (object) {
+      this.#idToObject.delete(id);
+      this.#objectToId.delete(object);
+    }
+  }
+
+  releaseObjectGroup(group: string) {
+    for (const [id, object] of this.#idToObject.entries()) {
+      if (id.startsWith(group)) {
+        this.#idToObject.delete(id);
+        this.#objectToId.delete(object);
+      }
+    }
+  }
+
+  getObject(objectId: string) {
+    return this.#idToObject.get(objectId);
+  }
+
+  toRemoteObject(value: Value, options: { objectGroup?: string, generatePreview?: boolean }): Protocol.Runtime.RemoteObject {
+    return getInspector(value).toRemoteObject(value, (val) => this.#internObject(val, options.objectGroup), this, options.generatePreview);
+  }
+
+  getProperties({
+    objectId, accessorPropertiesOnly, generatePreview, nonIndexedPropertiesOnly, ownProperties,
+  }: Protocol.Runtime.GetPropertiesRequest): Protocol.Runtime.GetPropertiesResponse {
+    const object = this.getObject(objectId);
+    if (!(object instanceof ObjectValue)) {
+      return { result: [] };
+    }
+    const wrap = (v: Value) => this.toRemoteObject(v, { generatePreview });
+
+    const properties: Protocol.Runtime.PropertyDescriptor[] = [];
+    const internalProperties: Protocol.Runtime.InternalPropertyDescriptor[] = [];
+    const privateProperties: Protocol.Runtime.PrivatePropertyDescriptor[] = [];
+
+    if (!accessorPropertiesOnly) {
+      object.PrivateElements.forEach((value) => {
+        const desc: Protocol.Runtime.PrivatePropertyDescriptor = {
+          name: value.Key.Description.stringValue(),
+        };
+        if (value.Value) desc.value = wrap(value.Value);
+        if (value.Getter) desc.get = wrap(value.Getter);
+        if (value.Setter) desc.set = wrap(value.Setter);
+        privateProperties.push(desc);
+      });
+
+      const exoticProperties = getInspector(object).exoticProperties?.(object, (val) => this.#internObject(val), this, generatePreview);
+      if (exoticProperties) {
+        properties.push(...exoticProperties);
+      }
+    }
+
+    (() => {
+      let p: NullValue | ObjectValue = object;
+      while (p instanceof ObjectValue) {
+        for (const key of p.properties.keys()) {
+          if (nonIndexedPropertiesOnly && isIntegerIndex(key)) {
+            continue;
+          }
+          const desc = (p.properties.get(key));
+          if (!desc) {
+            return;
+          }
+          if (accessorPropertiesOnly && !IsAccessorDescriptor(desc)) {
+            continue;
+          }
+          const descriptor: Protocol.Runtime.PropertyDescriptor = {
+            name: key instanceof JSStringValue
+              ? key.stringValue()
+              : SymbolDescriptiveString(key).stringValue(),
+            writable: desc.Writable === Value.true,
+            configurable: desc.Configurable === Value.true,
+            enumerable: desc.Enumerable === Value.true,
+            isOwn: p === object,
+          };
+          if (desc.Value && !('HostUninitializedBindingMarkerObject' in desc.Value)) descriptor.value = wrap(desc.Value);
+          if (desc.Getter) descriptor.get = wrap(desc.Getter);
+          if (desc.Setter) descriptor.set = wrap(desc.Setter);
+          if (key instanceof SymbolValue) descriptor.symbol = wrap(key);
+          properties.push(descriptor);
+        }
+
+        if (ownProperties) {
+          break;
+        }
+        if ('Prototype' in p) {
+          p = (p as OrdinaryObject).Prototype;
+        } else {
+          p = Value.null;
+        }
+      }
+    })();
+
+    const additionalInternalFields = getInspector(object).toInternalProperties?.(object, (val) => this.#internObject(val, 'default'), this, generatePreview);
+    if (additionalInternalFields) {
+      internalProperties.push(...additionalInternalFields);
+    }
+
+    if ('Prototype' in object) {
+      internalProperties.push({
+        name: '[[Prototype]]',
+        value: wrap(object.Prototype as Value),
+      });
+    }
+
+    return { result: properties, internalProperties, privateProperties };
+  }
+
+  createExceptionDetails(completion: ThrowCompletion | Value, isPromise: boolean): Protocol.Runtime.ExceptionDetails {
+    const value = completion instanceof ThrowCompletion ? completion.Value : completion;
+    const { callStack } = getHostDefinedErrorDetails(value);
+    const frames = InspectorContext.callSiteToCallFrame(callStack);
+    const exceptionId = this.#objectCounter;
+    this.#objectCounter += 1;
+    return {
+      text: isPromise ? 'Uncaught (in promise)' : 'Uncaught',
+      stackTrace: callStack ? { callFrames: frames } : undefined,
+      exception: getInspector(value).toRemoteObject(value, (val) => this.#internObject(val), this, false),
+      lineNumber: frames[0]?.lineNumber || 0,
+      columnNumber: frames[0]?.columnNumber || 0,
+      exceptionId,
+      scriptId: frames[0]?.scriptId,
+      url: frames[0]?.url,
+    };
+  }
+
+  static callSiteToCallFrame(callSite: readonly (CallSite | CallFrame)[] | undefined): Protocol.Runtime.CallFrame[] {
+    return callSite?.map((call) => call.toCallFrame()!).filter(Boolean) || [];
+  }
+
+  createEvaluationResult(completion: ValueCompletion): Protocol.Runtime.EvaluateResponse {
+    completion = EnsureCompletion(completion);
+    if (!(completion.Value instanceof Value)) {
+      throw new RangeError('Invalid completion value');
+    }
+    return {
+      exceptionDetails: completion instanceof ThrowCompletion ? this.createExceptionDetails(completion, false) : undefined,
+      result: this.toRemoteObject(completion.Value, {}),
+    };
+  }
+
+  getDebuggerCallFrame(): Protocol.Debugger.CallFrame[] {
+    const stacks = getCurrentStack(false);
+    const length = surroundingAgent.executionContextStack.length;
+    return stacks.map((stack, index): Protocol.Debugger.CallFrame => {
+      if (!stack.getScriptId()) {
+        return undefined!;
+      }
+      const scopeChain: Protocol.Debugger.Scope[] = [];
+      let env: EnvironmentRecord | null = stack.context.LexicalEnvironment;
+      while (env instanceof EnvironmentRecord) {
+        const result = getDisplayObjectFromEnvironmentRecord(env);
+        if (result) {
+          scopeChain.push({ type: result.type, object: this.toRemoteObject(result.object, {}) });
+        }
+        env = env.OuterEnv;
+      }
+      return {
+        callFrameId: String(length - index - 1),
+        functionName: stack.getFunctionName() || '<anonymous>',
+        location: {
+          scriptId: stack.getScriptId()!,
+          lineNumber: (stack.lineNumber || 1) - 1,
+          columnNumber: (stack.columnNumber || 1) - 1,
+        },
+        this: this.toRemoteObject(HostGetThisEnvironment(stack.context.LexicalEnvironment), {}),
+        url: stack.getSpecifier() || '',
+        canBeRestarted: false,
+        functionLocation: isECMAScriptFunctionObject(stack.context.Function) ? {
+          lineNumber: (stack.context.Function.ECMAScriptCode?.location.start.line || 1) - 1,
+          columnNumber: (stack.context.Function.ECMAScriptCode?.location.start.column || 1) - 1,
+          scriptId: stack.getScriptId() || '',
+        } : undefined,
+        scopeChain,
+      };
+    }).filter(Boolean);
+  }
+
+  evaluateMode: 'script' | 'module' | 'console' = 'script';
+}
+
+function HostGetThisEnvironment(env: EnvironmentRecord | null): Value {
+  while (env !== null) {
+    const exists = env.HasThisBinding();
+    if (exists === Value.true) {
+      const value = (env as EnvironmentRecordWithThisBinding).GetThisBinding();
+      if (value instanceof ThrowCompletion) {
+        return Value.undefined;
+      }
+      return value as Value;
+    }
+    const outer = env.OuterEnv;
+    env = outer;
+  }
+  throw new ReferenceError('No this environment found');
+}
+
+export function getDisplayObjectFromEnvironmentRecord(record: EnvironmentRecord): undefined | { type: Protocol.Debugger.Scope['type'], object: ObjectValue } {
+  if (record instanceof DeclarativeEnvironmentRecord) {
+    const object = OrdinaryObjectCreate(Value.null, ['HostInspectorScopePreview']);
+    for (const [key, binding] of record.bindings) {
+      const value = binding.initialized ? binding.value! : OrdinaryObjectCreate(Value.null, ['HostUninitializedBindingMarkerObject']);
+      if (isArgumentExoticObject(value)) {
+        continue;
+      }
+      object.properties.set(key, Descriptor({
+        Enumerable: isArgumentExoticObject(value) ? Value.false : Value.true,
+        Value: value,
+        Writable: binding.mutable ? Value.true : Value.false,
+      }));
+    }
+    let type: Protocol.Debugger.Scope['type'] = 'block';
+    if (record instanceof FunctionEnvironmentRecord) {
+      type = 'local';
+    } else if (record instanceof ModuleEnvironmentRecord) {
+      type = 'module';
+    }
+    if (type !== 'local' && !object.properties.size) {
+      return undefined;
+    }
+    return { type, object };
+  } else if (record instanceof ObjectEnvironmentRecord) {
+    return { type: record.IsWithEnvironment === Value.true ? 'with' : 'global', object: record.BindingObject };
+  } else if (record instanceof GlobalEnvironmentRecord) {
+    return { type: 'global', object: record.GlobalThisValue };
+  }
+  throw new TypeError('Unknown environment record');
+}

package/lib-src/inspector/evaluator.mts

@@ -0,0 +1,19 @@
+import type { InspectorContext } from './context.mts';
+import {
+  isEvaluator, ManagedRealm, skipDebugger, surroundingAgent, type PlainCompletion, type PlainEvaluator,
+} from '#self';
+
+export function nativeEvalInAnyRealm<T>(enterPreview: boolean, context: InspectorContext, closure: (() => PlainCompletion<T>) | (() => PlainEvaluator<T>)): PlainCompletion<T> | undefined {
+  const realm = surroundingAgent.runningExecutionContext?.Realm as ManagedRealm || context.getAnyRealm()?.realm;
+  if (!realm) return undefined;
+
+  const exitPreview = enterPreview ? surroundingAgent.debugger_scopePreview() : undefined;
+  const pop = realm.pushTopContext();
+  let result = closure();
+  if (isEvaluator(result)) {
+    result = skipDebugger(result);
+  }
+  pop?.();
+  exitPreview?.[Symbol.dispose]();
+  return result;
+}

package/lib-src/inspector/index.mts

@@ -0,0 +1,209 @@
+import type { Protocol } from 'devtools-protocol';
+import { InspectorContext } from './context.mts';
+import * as impl from './methods.mts';
+import type { DebuggerContext, DebuggerPreference, DevtoolEvents } from './types.mts';
+import { getParsedEvent } from './internal-utils.mts';
+import type {
+  Agent, Arguments, HostPromiseRejectionTracker, ManagedRealm, Realm, Value,
+} from '#self';
+
+const ignoreNamespaces = ['Network'];
+const ignoreMethods: string[] = [];
+
+export type { DebuggerPreference } from './types.mts';
+export { createConsole } from './utils.mts';
+
+interface AgentRecord {
+  readonly agent: Agent;
+  onDetach(): void;
+}
+export abstract class Inspector {
+  #context = new InspectorContext(this);
+
+  #agents: AgentRecord[] = [];
+
+  #unhandledExceptionIds = new WeakMap<Value, number>();
+
+  attachAgent(agent: Agent, priorRealms: ManagedRealm[]) {
+    const oldOnDebugger = agent.hostDefinedOptions.onDebugger;
+    agent.hostDefinedOptions.onDebugger = (reason) => {
+      oldOnDebugger?.(reason);
+      const pausedEvent: Protocol.Debugger.PausedEvent = {
+        reason: reason?.reason ?? 'debugCommand',
+        callFrames: this.#context.getDebuggerCallFrame(),
+      };
+      if (reason?.hitBreakpoints) {
+        pausedEvent.hitBreakpoints = [...reason.hitBreakpoints];
+      }
+      this.sendEvent['Debugger.paused'](pausedEvent);
+    };
+
+    agent.hostDefinedOptions.hostHooks ??= {};
+    agent.hostDefinedOptions.hostHooks.HostPromiseRejectionTrackers ??= new Set();
+    const tracker: HostPromiseRejectionTracker = (promise, operation) => {
+      if (operation === 'reject') {
+        const detail = this.#context.createExceptionDetails(promise, true);
+        this.#unhandledExceptionIds.set(promise, detail.exceptionId);
+        this.sendEvent['Runtime.exceptionThrown']({
+          timestamp: Date.now(),
+          exceptionDetails: detail,
+        });
+      } else {
+        const id = this.#unhandledExceptionIds.get(promise);
+        if (id) {
+          this.sendEvent['Runtime.exceptionRevoked']({
+            reason: 'Handler added to rejected promise',
+            exceptionId: id,
+          });
+        }
+      }
+    };
+    agent.hostDefinedOptions.hostHooks.HostPromiseRejectionTrackers.add(tracker);
+
+    const oldOnRealmCreated = agent.hostDefinedOptions.onRealmCreated;
+    agent.hostDefinedOptions.onRealmCreated = (realm) => {
+      oldOnRealmCreated?.(realm);
+      this.#context.attachRealm(realm, agent);
+    };
+
+    const oldOnScriptParsed = agent.hostDefinedOptions.onScriptParsed;
+    agent.hostDefinedOptions.onScriptParsed = (script, id) => {
+      oldOnScriptParsed?.(script, id);
+      const realmId = this.#context.getRealm(script.Realm as ManagedRealm)?.descriptor.id;
+      if (realmId === undefined) {
+        return;
+      }
+      this.sendEvent['Debugger.scriptParsed'](getParsedEvent(script, id, realmId));
+    };
+    this.#agents.push({
+      agent,
+      onDetach: () => {
+        agent.hostDefinedOptions.onDebugger = oldOnDebugger;
+        agent.hostDefinedOptions.onRealmCreated = oldOnRealmCreated;
+        agent.hostDefinedOptions.onScriptParsed = oldOnScriptParsed;
+        agent.hostDefinedOptions.hostHooks!.HostPromiseRejectionTrackers!.delete(tracker);
+        this.#agents = this.#agents.filter((x) => x.agent !== agent);
+      },
+    });
+    priorRealms.forEach((realm) => {
+      this.#context.attachRealm(realm, agent);
+    });
+  }
+
+  detachAgent(agent: Agent) {
+    const record = this.#agents.find((x) => x.agent === agent);
+    record?.onDetach();
+    this.#context.detachAgent(agent);
+  }
+
+  protected abstract send(data: object): void;
+
+  readonly preference: DebuggerPreference = { previewDebug: false };
+
+  protected onMessage(id: unknown, methodArg: string, params: unknown): void {
+    if (ignoreMethods.includes(methodArg)) {
+      return;
+    }
+    const [namespace, method] = methodArg.split('.');
+    if (ignoreNamespaces.includes(namespace)) {
+      return;
+    }
+    if (!(namespace in impl)) {
+      this.sendEvent['Runtime.consoleAPICalled']({
+        timestamp: Date.now(),
+        type: 'warning',
+        executionContextId: 0,
+        args: [{
+          type: 'string',
+          value: `engine262 internal error: Namespace not implemented: ${namespace}.*`,
+        }],
+      });
+      return;
+    }
+    const ns = (impl as Record<string, object>)[namespace];
+    if (!(method in ns)) {
+      this.sendEvent['Runtime.consoleAPICalled']({
+        timestamp: Date.now(),
+        type: 'warning',
+        executionContextId: 0,
+        args: [{
+          type: 'string',
+          value: `engine262 internal error: Method not implemented: ${namespace}.${method}`,
+        }],
+      });
+      return;
+    }
+
+    const f = (ns as Record<string, (args: unknown, context: DebuggerContext) => unknown>)[method];
+    new Promise((resolve) => {
+      resolve(f(params, this.#debugContext));
+    }).then((result = {}) => {
+      this.send({ id, result });
+    });
+  }
+
+  sendEvent: DevtoolEvents = Object.create(new Proxy({}, {
+    get: (_, key: string) => {
+      const f = (params: Record<string, unknown>) => {
+        if (this.#debuggerAttached) {
+          this.send({ method: key, params });
+        }
+      };
+      Object.defineProperty(this.sendEvent, key, { value: f });
+      return f;
+    },
+  }));
+
+  console(realm: Realm, type: Protocol.Runtime.ConsoleAPICalledEventType, args: Arguments) {
+    const context = this.#context.getRealm(realm as ManagedRealm);
+    if (!context) {
+      return;
+    }
+    this.sendEvent['Runtime.consoleAPICalled']({
+      type,
+      args: args.map((x) => this.#context.toRemoteObject(x, { })),
+      executionContextId: context.descriptor.id,
+      timestamp: Date.now(),
+    });
+  }
+
+  #debuggerAttached = false;
+
+  onDebuggerDisconnect() {
+    this.#debuggerAttached = false;
+  }
+
+  #onDebuggerConnected() {
+    this.#context.realms.forEach((realm) => {
+      if (realm) {
+        this.sendEvent['Runtime.executionContextCreated']({
+          context: realm.descriptor,
+        });
+      }
+    });
+    this.#agents.forEach(({ agent }) => {
+      agent.parsedSources.forEach((script, id) => {
+        const realmId = this.#context.getRealm(script.Realm as ManagedRealm)?.descriptor.id;
+        if (realmId === undefined) {
+          return;
+        }
+        this.sendEvent['Debugger.scriptParsed'](getParsedEvent(script, id, realmId));
+      });
+    });
+  }
+
+  #debugContext: DebuggerContext = {
+    sendEvent: this.sendEvent,
+    preference: this.preference,
+    context: this.#context,
+    onDebuggerConnect: () => {
+      if (!this.#debuggerAttached) {
+        this.#debuggerAttached = true;
+        this.#onDebuggerConnected();
+      }
+    },
+    onDebuggerDisconnect: () => {
+      this.#debuggerAttached = false;
+    },
+  };
+}

package/lib-src/inspector/internal-utils.mts

@@ -0,0 +1,18 @@
+import type { Protocol } from 'devtools-protocol';
+import { SourceTextModuleRecord, type DynamicParsedCodeRecord, type ScriptRecord } from '#self';
+
+export function getParsedEvent(source: ScriptRecord | SourceTextModuleRecord | DynamicParsedCodeRecord, id: string, executionContextId: number): Protocol.Debugger.ScriptParsedEvent {
+  const lines = source.ECMAScriptCode.sourceText.split('\n');
+  return {
+    isModule: source instanceof SourceTextModuleRecord,
+    scriptId: id,
+    url: source.HostDefined?.specifier || `vm:///${id}`,
+    startLine: 0,
+    startColumn: 0,
+    endLine: lines.length,
+    endColumn: lines.pop()!.length,
+    executionContextId,
+    hash: '',
+    buildId: '',
+  };
+}