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

package/dist/src/binder.d.ts

@@ -1,6 +1,5 @@
 import { Ref } from "@vue/reactivity";
 import { Refkey } from "./refkey.js";
-import { OutputSymbolFlags } from "./symbols/flags.js";
 import { OutputScope } from "./symbols/output-scope.js";
 import { type OutputSymbol } from "./symbols/output-symbol.js";
 export type Metadata = object;
@@ -25,28 +24,12 @@ export interface Binder {
      * @see {@link resolve} a convenience function that uses the current scope and
      * binder.
      */
-    resolveDeclarationByKey<TScope extends OutputScope = OutputScope, TSymbol extends OutputSymbol = OutputSymbol>(currentScope: TScope | undefined, currentMemberScope: TScope | undefined, key: Refkey): 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.
-     */
-    findSymbolName<TScope extends OutputScope = OutputScope, TSymbol extends OutputSymbol = OutputSymbol>(currentScope: TScope | undefined, name: string): 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>;
+    resolveDeclarationByKey<TScope extends OutputScope = OutputScope, TSymbol extends OutputSymbol = OutputSymbol>(currentScope: TScope | undefined, key: Refkey, options?: ResolveDeclarationByKeyOptions<TScope, TSymbol>): Ref<ResolutionResult<TScope, TSymbol> | undefined>;
     /**
-     * The global scope. This is the root scope for all symbols.
+     * 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.
      */
-    globalScope: OutputScope;
+    getSymbolForRefkey<TSymbol extends OutputSymbol>(refkey: Refkey): Ref<TSymbol | undefined>;
     /**
      * The name conflict resolver to use for this binder.
      */
@@ -75,7 +58,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)
@@ -92,11 +75,19 @@ export interface Binder {
  */
 export interface ResolutionResult<TScope extends OutputScope, TSymbol extends OutputSymbol> {
     /**
-     * The symbol for the resolved declaration.
+     * The resolved symbol. May be declared in a lexical scope or be a member symbol.
+     */
+    symbol: TSymbol;
+    /**
+     * 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`.
      */
-    targetDeclaration: TSymbol;
+    lexicalDeclaration: TSymbol;
     /**
-     * The scopes between the common scope and the reference
+     * The scopes between the common scope and the reference.
      */
     pathUp: TScope[];
     /**
@@ -104,18 +95,60 @@ export interface ResolutionResult<TScope extends OutputScope, TSymbol extends Ou
      */
     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;
 }
@@ -130,21 +163,24 @@ export declare function createOutputBinder(options?: BinderOptions): Binder;
  * 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 resolution result.
  */
-export declare function resolve<TScope extends OutputScope, TSymbol extends OutputSymbol>(refkey: Refkey): Ref<ResolutionResult<TScope, TSymbol>>;
+export declare function resolve<TScope extends OutputScope, TSymbol extends OutputSymbol>(refkey: Refkey, options?: ResolveDeclarationByKeyOptions<TScope, TSymbol>): Ref<ResolutionResult<TScope, TSymbol>>;
+/**
+ * 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 declare function symbolForRefkey(refkey: Refkey): Ref<OutputSymbol | undefined, OutputSymbol | undefined>;
 declare const createSymbolsSymbol: unique symbol;
 export declare function getSymbolCreator(creator: SymbolCreator): SymbolCreator[typeof createSymbolsSymbol];
 export declare 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 declare function useDefaultScope(flags?: OutputSymbolFlags): OutputScope | undefined;
 export {};
 //# sourceMappingURL=binder.d.ts.map

package/dist/src/binder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"binder.d.ts","sourceRoot":"","sources":["../../src/binder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"binder.d.ts","sourceRoot":"","sources":["../../src/binder.ts"],"names":[],"mappings":"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"}