@alloy-js/core 0.20.0-dev.4 → 0.20.0-dev.7

package/src/binder.ts

@@ -1,14 +1,13 @@
-import { computed, ref, Ref, ShallowRef, shallowRef } from "@vue/reactivity";
-import { useMemberScope } from "./context/member-scope.js";
+import { computed, Ref, ShallowRef, shallowRef } from "@vue/reactivity";
+import { useBinder } from "./context/binder.js";
+import { useMemberContext } from "./context/member-scope.js";
 import { useScope } from "./context/scope.js";
-import { effect, untrack } from "./reactivity.js";
-import { refkey, Refkey } from "./refkey.js";
-import { OutputSymbolFlags } from "./symbols/flags.js";
+import { effect } from "./reactivity.js";
+import { isMemberRefkey, refkey, Refkey } from "./refkey.js";
 import { OutputScope } from "./symbols/output-scope.js";
 import { type OutputSymbol } from "./symbols/output-symbol.js";
 import {
   formatRefkeys,
-  formatSymbol,
   formatSymbolName,
   trace,
   TracePhase,
@@ -41,52 +40,18 @@ export interface Binder {
     TSymbol extends OutputSymbol = OutputSymbol,
   >(
     currentScope: TScope | undefined,
-    currentMemberScope: TScope | undefined,
     key: Refkey,
+    options?: ResolveDeclarationByKeyOptions<TScope, TSymbol>,
   ): Ref<ResolutionResult<TScope, TSymbol> | undefined>;
 
-  getSymbolForRefkey<TSymbol extends OutputSymbol>(
-    refkey: Refkey,
-  ): Ref<TSymbol | undefined>;
-
   /**
-   * Find a symbol with a given name in the given scope. Returns a ref
-   * for the symbol, such that when the symbol is available, the ref value
-   * will update.
+   * Get a ref to the symbol associated with the given refkey. The value of the
+   * ref is undefined if the symbol has not been created yet.
    */
-  findSymbolName<
-    TScope extends OutputScope = OutputScope,
-    TSymbol extends OutputSymbol = OutputSymbol,
-  >(
-    currentScope: TScope | undefined,
-    name: string,
+  getSymbolForRefkey<TSymbol extends OutputSymbol>(
+    refkey: Refkey,
   ): Ref<TSymbol | undefined>;
 
-  findScopeName<TScope extends OutputScope = OutputScope>(
-    currentScope: TScope | undefined,
-    name: string,
-  ): Ref<TScope | undefined>;
-
-  /**
-   * Resolve a fully qualified name to a symbol. Access a nested scope by name
-   * with `::`, a nested static member with `.` and a nested instance member
-   * with `#`.
-   *
-   * Per-language packages may provide their own resolveFQN function that uses
-   * syntax more natural to that  language.
-   */
-  resolveFQN<
-    TScope extends OutputScope = OutputScope,
-    TSymbol extends OutputSymbol = OutputSymbol,
-  >(
-    fqn: string,
-  ): Ref<TSymbol | TScope | undefined>;
-
-  /**
-   * The global scope. This is the root scope for all symbols.
-   */
-  globalScope: OutputScope;
-
   /**
    * The name conflict resolver to use for this binder.
    */
@@ -119,7 +84,7 @@ export interface Binder {
  * scope: global scope
  * ├── scope: namespace scope 1
  * │   └── symbol: foo
- * │       └── static member scope
+ * │       └── static members
  * │           └── symbol: bar
  * └── scope: namespace scope 2
  *    └── (resolve bar from here)
@@ -139,11 +104,21 @@ export interface ResolutionResult<
   TSymbol extends OutputSymbol,
 > {
   /**
-   * The symbol for the resolved declaration.
+   * The resolved symbol. May be declared in a lexical scope or be a member symbol.
    */
-  targetDeclaration: TSymbol;
+  symbol: TSymbol;
+
   /**
-   * The scopes between the common scope and the reference
+   * When the symbol is a member symbol, this is the symbol of the lexical
+   * declaration which contains this member symbol, either as one of its own
+   * member symbols, or as a member of one of its members.
+   *
+   * When the symbol is a non-member symbol, this is the same as `symbol`.
+   */
+  lexicalDeclaration: TSymbol;
+
+  /**
+   * The scopes between the common scope and the reference.
    */
   pathUp: TScope[];
 
@@ -153,21 +128,78 @@ export interface ResolutionResult<
   pathDown: TScope[];
 
   /**
-   * The scope which contains both the reference and the declaration.
+   * The scopes from the root to scope of the lexical declaration.
+   */
+  fullSymbolPath: TScope[];
+
+  /**
+   * The scopes from the root to the scope of the reference.
+   */
+  fullReferencePath: TScope[];
+
+  /**
+   * The lexical scope which contains both the reference and the lexical
+   * declaration. Undefined when they do not share a common scope.
    */
   commonScope: TScope | undefined;
 
   /**
    * When resolving a member symbol, this is the path of symbols that lead from
-   * the base declaration to the member symbol.
+   * the lexical declaration to the member symbol.
    */
-  memberPath?: TSymbol[];
+  memberPath: TSymbol[];
+}
+
+/**
+ * Describes a member in a member access chain, tracking both the symbol
+ * and whether this specific member was accessed via a memberRefkey.
+ */
+export interface MemberDescriptor {
+  symbol: OutputSymbol;
+  isMemberAccess: boolean;
 }
 
 export interface NameConflictResolver {
   (name: string, symbols: OutputSymbol[]): void;
 }
 
+/**
+ * The context for a member resolution. This is used to properly resolve a
+ * member in the MemberResolver.
+ */
+export interface MemberResolutionContext<TScope extends OutputScope> {
+  /**
+   * The scopes that the member reference occurred in.
+   */
+  referencePath: TScope[];
+
+  /**
+   * Whether we are using member access e.g. via `memberRefkey`.
+   * This is true when the member was resolved using a memberRefkey,
+   * which may carry additional metadata about the member access in the future.
+   */
+  isMemberAccess: boolean;
+}
+
+/**
+ *
+ */
+export interface MemberResolver<
+  TScope extends OutputScope,
+  TSymbol extends OutputSymbol,
+> {
+  (
+    owner: TSymbol,
+    member: TSymbol,
+    context: MemberResolutionContext<TScope>,
+  ): void;
+}
+export interface ResolveDeclarationByKeyOptions<
+  TScope extends OutputScope,
+  TSymbol extends OutputSymbol,
+> {
+  memberResolver?: MemberResolver<TScope, TSymbol>;
+}
 export interface BinderOptions {
   nameConflictResolver?: NameConflictResolver;
 }
@@ -176,21 +208,12 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
   const binder: Binder = {
     resolveDeclarationByKey,
     getSymbolForRefkey,
-    findSymbolName,
-    findScopeName,
-    resolveFQN: resolveFQN as any,
-    globalScope: undefined as any,
     notifyScopeCreated,
     notifySymbolCreated,
     notifySymbolDeleted,
     nameConflictResolver: options.nameConflictResolver,
   };
 
-  binder.globalScope = new OutputScope("<global>", {
-    binder,
-    kind: "global",
-  });
-
   const knownDeclarations = new Map<Refkey, OutputSymbol>();
   const waitingDeclarations = new Map<Refkey, Ref<OutputSymbol | undefined>>();
   const waitingSymbolNames = new Map<
@@ -228,75 +251,112 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
     }
   }
 
-  function hasTransientScope(symbol: OutputSymbol) {
-    let sym: OutputSymbol | undefined = symbol;
-    let transient = false;
-    while (sym) {
-      if (sym.flags & OutputSymbolFlags.Transient) {
-        transient = true;
-        break;
-      }
-      if (sym.flags & ~OutputSymbolFlags.Member) {
-        break;
-      }
-
-      sym = sym.scope.owner;
-    }
-
-    return transient;
-  }
   function buildResult<
     TScope extends OutputScope = OutputScope,
     TSymbol extends OutputSymbol = OutputSymbol,
   >(
     currentScope: TScope | undefined,
-    currentMemberScope: TScope | undefined,
     targetDeclarationBase: TSymbol,
   ): ResolutionResult<TScope, TSymbol> {
-    trace(TracePhase.resolve.success, () => {
-      return `Resolved ${formatRefkeys(targetDeclarationBase.refkeys)} to ${formatSymbol(targetDeclarationBase)}`;
-    });
-    if (targetDeclarationBase.flags & OutputSymbolFlags.InstanceMember) {
-      // todo: handle referencing nested objects by refkey
-      return {
-        pathUp: [],
-        pathDown: [],
-        memberPath: [targetDeclarationBase],
-        commonScope: currentMemberScope,
-        targetDeclaration: targetDeclarationBase,
-      };
+    const { memberPath: targetMemberPath, scopeChain: targetChain } =
+      scopeAndMemberChain<TScope, TSymbol>(targetDeclarationBase);
+
+    let targetLexicalDeclaration =
+      targetMemberPath && targetMemberPath.length > 0 ?
+        (targetMemberPath[0].ownerSymbol! as TSymbol)
+      : targetDeclarationBase;
+    // when we are resolving from a scope which is a member scope and might have
+    // member scope parents, and any symbols in the member path are members of
+    // the member scope's owner symbol (i.e., those symbols are in scope where
+    // the reference is made), we replace the target member path with an entry
+    // on the scope chain.
+
+    // So, first we find all the owner symbols for any member scopes in scope
+    // for the reference.
+    const referenceChain = scopeChain(currentScope);
+
+    const inScopeSymbols = new Map<TSymbol, TScope>();
+    for (const scope of referenceChain) {
+      if (scope.isMemberScope) {
+        inScopeSymbols.set(scope.ownerSymbol! as TSymbol, scope);
+      }
     }
 
-    const { memberPath, scopeChain: targetChain } = scopeAndMemberChain<
-      TScope,
-      TSymbol
-    >(targetDeclarationBase);
-    const currentChain = scopeChain(currentScope);
+    // then if the lexical declaration symbol's members are in scope, remove the
+    // symbol from the member path and add its corresponding member scope to the
+    // target chain.
+    while (
+      targetMemberPath.length > 0 &&
+      inScopeSymbols.has(targetLexicalDeclaration)
+    ) {
+      targetChain.push(inScopeSymbols.get(targetLexicalDeclaration)!);
+      targetLexicalDeclaration = targetMemberPath.shift()!;
+    }
+
+    // Now we replace any scopes in the target chain with corresponding scopes
+    // from the reference chain.
+    for (const [index, scope] of targetChain.entries()) {
+      if (inScopeSymbols.has(scope.ownerSymbol! as TSymbol)) {
+        targetChain[index] = inScopeSymbols.get(scope.ownerSymbol! as TSymbol)!;
+      }
+    }
+
+    // Next we look for member scopes in the target chain that correspond to
+    // member scopes in the reference chain. We splice the reference chain into
+    // the target chain at that point. This ensures that we establish the proper
+    // common scope and path up/down even if the reference chain has additional
+    // scopes above it (e.g. a scope for the current source file).
+    const commonMemberContainer = targetChain.findIndex(
+      (scope) =>
+        scope.isMemberScope && inScopeSymbols.has(scope.ownerSymbol as TSymbol),
+    );
+
+    if (commonMemberContainer > -1) {
+      const sourceLocation = referenceChain.findIndex(
+        (scope) =>
+          scope.isMemberScope &&
+          scope.ownerSymbol === targetChain[commonMemberContainer].ownerSymbol,
+      );
+
+      // source location is guaranteed to exist at this point.
+      targetChain.splice(
+        0,
+        commonMemberContainer + 1,
+        ...referenceChain.slice(0, sourceLocation + 1),
+      );
+    }
+
+    // Now that we have the target chain and scopes, we can determine the common
+    // scopes and paths.
     let diffStart = 0;
     while (
       targetChain[diffStart] &&
-      currentChain[diffStart] &&
-      targetChain[diffStart] === currentChain[diffStart]
+      referenceChain[diffStart] &&
+      targetChain[diffStart] === referenceChain[diffStart]
     ) {
       diffStart++;
     }
-
-    const pathUp = currentChain.slice(diffStart);
+    const pathUp = referenceChain.slice(diffStart);
     const pathDown = targetChain.slice(diffStart);
-    const commonScope = targetChain[diffStart - 1] ?? null;
+    const commonScope = targetChain[diffStart - 1] ?? undefined;
 
     return {
       pathUp,
       pathDown,
-      memberPath,
+      memberPath: targetMemberPath,
       commonScope,
-      targetDeclaration:
-        memberPath && memberPath.length > 0 ?
-          memberPath.at(0)!
-        : targetDeclarationBase,
+      symbol: targetDeclarationBase,
+      lexicalDeclaration: targetLexicalDeclaration,
+      fullSymbolPath: targetChain,
+      fullReferencePath: referenceChain,
     };
   }
 
+  /**
+   * Walk from the provided symbol up to the non-member symbol. This constitutes
+   * the member path. Then, walk from the first non-member symbol's scope up to
+   * the global scope. This constitutes the scope chain.
+   */
   function scopeAndMemberChain<
     TScope extends OutputScope,
     TSymbol extends OutputSymbol,
@@ -305,15 +365,14 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
       memberPath: [] as TSymbol[],
       scopeChain: [] as TScope[],
     };
-
     let currentSymbol = symbol;
-    while (currentSymbol.flags & OutputSymbolFlags.StaticMember) {
-      result.memberPath.unshift(currentSymbol);
-      currentSymbol = currentSymbol.scope.owner! as TSymbol;
-    }
 
-    if (symbol.flags & OutputSymbolFlags.StaticMember) {
-      result.memberPath.unshift(currentSymbol);
+    if (currentSymbol.isMemberSymbol) {
+      result.memberPath = [];
+      while (currentSymbol.isMemberSymbol) {
+        result.memberPath.unshift(currentSymbol);
+        currentSymbol = currentSymbol.ownerSymbol as TSymbol;
+      }
     }
 
     const startScope = currentSymbol.scope as TScope;
@@ -339,7 +398,30 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
       return waitingDeclarations.get(refkey)! as ShallowRef<TSymbol>;
     }
 
-    const symbolRef = shallowRef<TSymbol | undefined>();
+    let symbolRef: ShallowRef<TSymbol | undefined>;
+
+    if (isMemberRefkey(refkey)) {
+      const baseSymbolRef: ShallowRef<TSymbol | undefined> =
+        getSymbolForRefkey<TSymbol>(refkey.base);
+      const memberSymbolRef: ShallowRef<TSymbol | undefined> =
+        getSymbolForRefkey<TSymbol>(refkey.member);
+
+      symbolRef = computed(() => {
+        // even though we don't necessarily need the base symbol to be available
+        // yet (the member symbol might already be declared on a type), we wait
+        // to resolve the member refkey until the base symbol is available.
+        const baseSymbol = baseSymbolRef.value;
+        const memberSymbol = memberSymbolRef.value;
+        if (!baseSymbol || !memberSymbol) {
+          return undefined;
+        }
+
+        return memberSymbol;
+      }) as ShallowRef<TSymbol | undefined>;
+    } else {
+      symbolRef = shallowRef<TSymbol | undefined>();
+    }
+
     waitingDeclarations.set(refkey, symbolRef);
     if (knownDeclarations.has(refkey)) {
       symbolRef.value = knownDeclarations.get(refkey) as TSymbol;
@@ -347,15 +429,23 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
     return symbolRef;
   }
 
+  /**
+   * There are two ways to reference a member symbol - directly via its refkey,
+   * and via a member refkey. In the former case, we just find the member
+   * symbol, and then compute its path directly from there. In hte latter case,
+   * we need to find the base of the member expression, and then add the members
+   * from the (possibly nested) member refkey to result.
+   */
   function resolveDeclarationByKey<
     TScope extends OutputScope = OutputScope,
     TSymbol extends OutputSymbol = OutputSymbol,
   >(
     currentScope: TScope | undefined,
-    currentMemberScope: TScope | undefined,
     refkey: Refkey,
+    options: ResolveDeclarationByKeyOptions<TScope, TSymbol> = {},
   ): ShallowRef<ResolutionResult<TScope, TSymbol> | undefined> {
     const resolvedSymbol = getSymbolForRefkey(refkey);
+
     return computed(() => {
       trace(
         TracePhase.resolve.pending,
@@ -374,33 +464,147 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
         () =>
           `${formatRefkeys(refkey)} resolved to ${formatSymbolName(symbol)}.`,
       );
-      if (hasTransientScope(symbol)) {
+      if (symbol.isTransient) {
         trace(
           TracePhase.resolve.failure,
-          () => `Symbol ${formatSymbolName(symbol)} in transient scope.`,
+          () => `Symbol ${formatSymbolName(symbol)} is transient.`,
         );
         return undefined;
       }
 
-      trace(
-        TracePhase.resolve.success,
-        () =>
-          `${formatRefkeys(refkey)} successfully resolved to ${formatSymbolName(symbol)}.`,
-      );
-      return buildResult(currentScope, currentMemberScope, symbol);
+      const chain = scopeChain(symbol.scope);
+      if (chain.some((scope) => scope.isTransient)) {
+        trace(
+          TracePhase.resolve.failure,
+          () => `Symbol ${formatSymbolName(symbol)} is in a transient scope.`,
+        );
+        return undefined;
+      }
+
+      let result: ResolutionResult<TScope, TSymbol>;
+      let memberDescriptorsFromRefkey: MemberDescriptor[];
+
+      if (isMemberRefkey(refkey)) {
+        memberDescriptorsFromRefkey = getMemberPathFromRefkey(refkey);
+
+        result = buildResult(
+          currentScope,
+          memberDescriptorsFromRefkey[0].symbol as TSymbol,
+        );
+      } else {
+        memberDescriptorsFromRefkey = [];
+        result = buildResult(currentScope, symbol);
+      }
+
+      // When we have member descriptors, this first entry is already part of the result due to passing it
+      // to buildResult above, so we don't need it here.
+      const newMemberPathDescriptors = memberDescriptorsFromRefkey.slice(1);
+      const allDescriptors = [
+        ...result.memberPath.map((s) => ({ symbol: s, isMemberAccess: false })),
+        ...newMemberPathDescriptors,
+      ];
+
+      // update the member path and resolved symbol from our member descriptors
+      // (if we have them)
+      if (memberDescriptorsFromRefkey.length > 0) {
+        for (const descriptor of newMemberPathDescriptors) {
+          result.memberPath.push(descriptor.symbol as TSymbol);
+        }
+        result.symbol = memberDescriptorsFromRefkey.at(-1)!.symbol as TSymbol;
+      }
+
+      // a subcomputed here ensures we don't lose the progress above When
+      // we fail to resolve because a type isn't available yet.
+      return computed(() => {
+        // resolve each member in the member path
+        let currentBase = result.lexicalDeclaration;
+
+        for (const descriptor of allDescriptors) {
+          const member = descriptor.symbol as TSymbol;
+          if (currentBase.isTyped && !currentBase.hasTypeSymbol) {
+            trace(
+              TracePhase.resolve.pending,
+              () =>
+                `${formatRefkeys(refkey)} needs type information from a parent type.`,
+            );
+            // waiting for type
+            return undefined;
+          }
+
+          resolveMember(currentBase, member, options.memberResolver, {
+            referencePath: result.fullReferencePath,
+            isMemberAccess: descriptor.isMemberAccess,
+          });
+
+          currentBase = member;
+        }
+
+        trace(
+          TracePhase.resolve.success,
+          () =>
+            `${formatRefkeys(refkey)} successfully resolved to ${formatSymbolName(symbol)}.`,
+        );
+        return result;
+      }).value;
     });
   }
 
-  function notifySymbolCreated(symbol: OutputSymbol): void {
-    if (symbol.flags & OutputSymbolFlags.Transient) {
-      // just ignore transient symbols.
-      return;
+  /**
+   * Extracts member descriptors from a refkey, tracking which members
+   * were accessed via memberRefkey for proper member resolution context.
+   */
+  function getMemberPathFromRefkey(refkey: Refkey): MemberDescriptor[] {
+    if (isMemberRefkey(refkey)) {
+      return [
+        ...getMemberPathFromRefkey(refkey.base),
+        {
+          symbol: getSymbolForRefkey(refkey.member).value!,
+          isMemberAccess: true,
+        },
+      ];
     }
+
+    return [
+      {
+        symbol: getSymbolForRefkey(refkey).value!,
+        isMemberAccess: false,
+      },
+    ];
+  }
+
+  function resolveMember(
+    base: OutputSymbol,
+    member: OutputSymbol,
+    memberResolver: MemberResolver<any, any> | undefined,
+    context: MemberResolutionContext<any>,
+  ) {
+    if (memberResolver) {
+      memberResolver(base, member, context);
+    } else {
+      // default member resolution
+      if (!member.isMemberSymbol) {
+        throw new Error(`${formatSymbolName(member)} is not a member symbol.`);
+      }
+
+      const memberOwner = base.hasTypeSymbol ? base.type : base.dealias();
+      if (member.ownerSymbol !== memberOwner) {
+        throw new Error(
+          `${formatSymbolName(
+            member,
+          )} is not a member of ${formatSymbolName(base)}.`,
+        );
+      }
+    }
+  }
+
+  function notifySymbolCreated(symbol: OutputSymbol): void {
     effect<Refkey[]>((oldRefkeys) => {
-      trace(
-        TracePhase.resolve.pending,
-        () => `Notifying resolutions for ${formatRefkeys(symbol.refkeys)}.`,
-      );
+      if (symbol.refkeys) {
+        trace(
+          TracePhase.resolve.pending,
+          () => `Notifying resolutions for ${formatRefkeys(symbol.refkeys)}.`,
+        );
+      }
 
       if (oldRefkeys) {
         for (const refkey of oldRefkeys) {
@@ -425,8 +629,13 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
           signal.value = symbol;
         }
 
+        const scope = symbol.scope;
+        if (!scope) {
+          continue;
+        }
+
         // notify those waiting for this symbol name
-        const waitingScope = waitingSymbolNames.get(symbol.scope);
+        const waitingScope = waitingSymbolNames.get(scope);
         if (waitingScope) {
           const waitingName = waitingScope.get(symbol.name);
           if (waitingName) {
@@ -438,113 +647,6 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
       return [...symbol.refkeys];
     });
   }
-
-  function findSymbolName<TSymbol extends OutputSymbol = OutputSymbol>(
-    scope: OutputScope | undefined,
-    name: string,
-  ): ShallowRef<TSymbol | undefined> {
-    return untrack(() => {
-      scope ??= binder.globalScope;
-      for (const sym of scope.symbols) {
-        if (sym.name === name) {
-          return shallowRef(sym) as Ref<TSymbol>;
-        }
-      }
-
-      const symRef = shallowRef<OutputSymbol | undefined>(undefined);
-      if (!waitingSymbolNames.has(scope)) {
-        waitingSymbolNames.set(scope, new Map());
-      }
-      const waiting = waitingSymbolNames.get(scope)!;
-      waiting.set(name, symRef);
-      return symRef as Ref<TSymbol | undefined>;
-    });
-  }
-
-  function findScopeName<TScope extends OutputScope = OutputScope>(
-    scope: OutputScope | undefined,
-    name: string,
-  ): ShallowRef<TScope | undefined> {
-    return untrack(() => {
-      scope ??= binder.globalScope;
-      for (const child of scope.children) {
-        if (child.name === name) {
-          return shallowRef(child) as Ref<TScope>;
-        }
-      }
-
-      const scopeRef = shallowRef<OutputScope | undefined>(undefined);
-      if (!waitingScopeNames.has(scope)) {
-        waitingScopeNames.set(scope, new Map());
-      }
-      const waiting = waitingScopeNames.get(scope)!;
-      waiting.set(name, scopeRef);
-
-      return scopeRef as Ref<TScope | undefined>;
-    });
-  }
-
-  function findScopeOrSymbolName(scope: OutputScope, name: string) {
-    return untrack(() => {
-      return computed(() => {
-        return (
-          findSymbolName(scope, name).value ?? findScopeName(scope, name).value
-        );
-      });
-    });
-  }
-
-  function resolveFQN(
-    fqn: string,
-  ): Ref<OutputScope | OutputSymbol | undefined> {
-    const parts = fqn.match(/[^.#]+|[.#]/g);
-    if (!parts) return ref(undefined);
-    if (parts.length === 0) return ref(undefined);
-
-    parts.unshift(".");
-
-    return computed(() => {
-      let base: OutputScope | OutputSymbol | undefined = binder.globalScope;
-
-      for (let i = 0; i < parts.length; i += 2) {
-        if (base === undefined) {
-          return;
-        }
-
-        const op = parts[i];
-        const name = parts[i + 1];
-
-        if (op === ".") {
-          if ("originalName" in base) {
-            if (!base.staticMemberScope) {
-              return undefined;
-            }
-
-            base = findSymbolName(
-              (base as OutputSymbol).staticMemberScope,
-              name,
-            ).value;
-          } else {
-            base = findScopeOrSymbolName(base, name).value;
-          }
-        } else if (op === "#") {
-          if ("originalName" in base) {
-            if (!base.instanceMemberScope) {
-              return undefined;
-            }
-            base = findSymbolName(
-              (base as OutputSymbol).instanceMemberScope,
-              name,
-            ).value;
-          } else {
-            return undefined;
-          }
-        }
-      }
-
-      return base;
-    });
-  }
 }
 
 /**
@@ -560,25 +662,44 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
 export function resolve<
   TScope extends OutputScope,
   TSymbol extends OutputSymbol,
->(refkey: Refkey): Ref<ResolutionResult<TScope, TSymbol>> {
+>(
+  refkey: Refkey,
+  options: ResolveDeclarationByKeyOptions<TScope, TSymbol> = {},
+): Ref<ResolutionResult<TScope, TSymbol>> {
   const scope = useScope();
-  const memberScope = useMemberScope();
-  const binder =
-    scope?.binder ??
-    memberScope?.instanceMembers?.binder ??
-    memberScope?.staticMembers?.binder;
+  const memberScope = useMemberContext();
+  const binder = scope?.binder ?? memberScope?.ownerSymbol.binder;
 
   if (!binder) {
     throw new Error("Can't resolve refkey without a binder");
   }
 
   return binder.resolveDeclarationByKey(
-    scope,
-    memberScope?.instanceMembers,
+    scope as TScope,
     refkey,
+    options,
   ) as any;
 }
 
+/**
+ * Get a ref to the symbol for the given refkey using the current binder. The
+ * value of the ref will be undefined when no symbol with that refkey has been
+ * created.
+ *
+ * @remarks
+ *
+ * This API may return a ref for undefined, but that does not mean that the symbol is
+ * not found. The symbol you're looking for may not have been declared yet. When the symbol
+ * is declared, the ref will be updated with the symbol.
+ */
+export function symbolForRefkey(refkey: Refkey) {
+  const binder = useBinder();
+  if (!binder) {
+    throw new Error("Can't resolve refkey without a binder");
+  }
+  return binder.getSymbolForRefkey(refkey);
+}
+
 const createSymbolsSymbol: unique symbol = Symbol();
 export function getSymbolCreator(
   creator: SymbolCreator,
@@ -593,29 +714,3 @@ export function getSymbolCreatorSymbol(): typeof createSymbolsSymbol {
 export interface SymbolCreator {
   [createSymbolsSymbol](binder: Binder): void;
 }
-
-/**
- * Use symbol flags to determine the scope in which a symbol with those flags
- * should be declared given the current context.
- *
- * @param flags - The symbol flags to use to determine the default scope.
- * @returns an {@link OutputScope} that is the default scope for the given
- * flags.
- */
-export function useDefaultScope(
-  flags: OutputSymbolFlags = OutputSymbolFlags.None,
-) {
-  if ((flags & OutputSymbolFlags.Member) === 0) {
-    return useScope();
-  } else {
-    const memberScope = useMemberScope();
-    if (!memberScope) {
-      throw new Error("Cannot declare member symbols without a member scope");
-    }
-    if (flags & OutputSymbolFlags.InstanceMember) {
-      return memberScope.instanceMembers;
-    } else {
-      return memberScope.staticMembers;
-    }
-  }
-}