@alloy-js/core 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alloy-js/core",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "",
   "main": "./dist/src/index.js",
   "exports": {
@@ -25,6 +25,10 @@
       "import": "./dist/src/components/index.js"
     }
   },
+  "browser": {
+    "./dist/src/write-output.js": "./dist/src/write-output.browser.js",
+    "./src/write-output.ts": "./src/write-output.browser.ts"
+  },
   "keywords": [],
   "author": "brian.terlson@microsoft.com",
   "license": "MIT",
@@ -32,6 +36,8 @@
     "@babel/core": "^7.24.7",
     "@babel/preset-typescript": "^7.24.7",
     "@vue/reactivity": "^3.4.30",
+    "chalk": "^5.3.0",
+    "cli-table3": "^0.6.5",
     "pathe": "^1.1.2",
     "@alloy-js/babel-preset": "~0.1.1"
   },
@@ -42,10 +48,7 @@
     "@rollup/plugin-typescript": "^11.1.6",
     "concurrently": "^8.2.2",
     "typescript": "^5.5.4",
-    "vitest": "^2.0.5"
-  },
-  "overrides": {
-    "esbuild": "0.23"
+    "vitest": "^3.0.4"
   },
   "type": "module",
   "scripts": {

package/src/binder.ts

@@ -1,14 +1,15 @@
-import { memo } from "@alloy-js/core/jsx-runtime";
 import {
   computed,
   effect,
   reactive,
+  ref,
   Ref,
   ShallowRef,
   shallowRef,
 } from "@vue/reactivity";
 import { useMemberScope } from "./context/member-scope.js";
 import { useScope } from "./context/scope.js";
+import { memo, untrack } from "./jsx-runtime.js";
 import { refkey, Refkey } from "./refkey.js";
 export type Metadata = object;
 
@@ -302,6 +303,42 @@ export interface Binder {
     key: Refkey,
   ): Ref<ResolutionResult<TScope, 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>;
+
+  /**
+   * The global scope. This is the root scope for all symbols.
+   */
   globalScope: OutputScope;
 }
 
@@ -325,11 +362,15 @@ export interface Binder {
  * When we resolve the refkey for `bar` from within `namespace scope 2`, we will get the following
  * resolution result:
  *
- * * **targetDeclaration**: symbol bar, the symbol we resolved.
- * * **commonScope**: global scope, because this is the most specific scope that contains both the declaration and the reference.
- * * **pathUp**: [namespace scope 2], because this is the scope between the reference and the common scope.
- * * **pathDown**: [namespace scope 1], because this is the scope between the common scope and the declaration
- * * **memberPath**: [foo, bar], because we resolved a member symbol and these are the symbols that lead from the base declaration to the member symbol.
+ * **targetDeclaration**: symbol bar, the symbol we resolved.
+ *
+ * **commonScope**: global scope, because this is the most specific scope that contains both the declaration and the reference.
+ *
+ * **pathUp**: [namespace scope 2], because this is the scope between the reference and the common scope.
+ *
+ * **pathDown**: [namespace scope 1], because this is the scope between the common scope and the declaration
+ *
+ * **memberPath**: [foo, bar], because we resolved a member symbol and these are the symbols that lead from the base declaration to the member symbol.
  */
 export interface ResolutionResult<
   TScope extends OutputScope,
@@ -377,6 +418,9 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
     addStaticMembersToSymbol,
     addInstanceMembersToSymbol,
     instantiateSymbolInto,
+    findSymbolName,
+    findScopeName,
+    resolveFQN: resolveFQN as any,
     globalScope: undefined as any,
   };
 
@@ -396,6 +440,14 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
 
   const knownDeclarations = new Map<Refkey, OutputSymbol>();
   const waitingDeclarations = new Map<Refkey, Ref<OutputSymbol | undefined>>();
+  const waitingSymbolNames = new Map<
+    OutputScope,
+    Map<string, Ref<OutputSymbol | undefined>>
+  >();
+  const waitingScopeNames = new Map<
+    OutputScope,
+    Map<string, Ref<OutputScope | undefined>>
+  >();
 
   return binder;
 
@@ -454,6 +506,14 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
       parentScope.children.add(scope);
     }
 
+    if (waitingScopeNames.has(parentScope!)) {
+      const waiting = waitingScopeNames.get(parentScope!);
+      if (waiting?.has(name)) {
+        const ref = waiting.get(name)!;
+        ref.value = scope;
+      }
+    }
+
     return scope as T;
   }
 
@@ -757,6 +817,121 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
       const signal = waitingDeclarations.get(refkey)!;
       signal.value = symbol;
     }
+
+    const waitingScope = waitingSymbolNames.get(symbol.scope);
+    if (waitingScope) {
+      const waitingName = waitingScope.get(symbol.name);
+      if (waitingName) {
+        waitingName.value = symbol;
+      }
+    }
+  }
+
+  function findSymbolName<TSymbol extends OutputSymbol = OutputSymbol>(
+    scope: OutputScope | undefined,
+    name: string,
+  ): Ref<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,
+  ): Ref<TScope | undefined> {
+    return untrack(() => {
+      scope ??= binder.globalScope;
+      for (const child of scope.children) {
+        if (child.name === name) {
+          return ref(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;
+    });
   }
 }
 

package/src/components/Declaration.tsx

@@ -1,8 +1,8 @@
-import { Children } from "@alloy-js/core/jsx-runtime";
 import { OutputSymbol } from "../binder.js";
 import { useContext } from "../context.js";
 import { BinderContext } from "../context/binder.js";
 import { DeclarationContext } from "../context/declaration.js";
+import { Children } from "../jsx-runtime.js";
 import { Refkey, refkey } from "../refkey.js";
 
 export interface DeclarationProps {

package/src/components/Indent.tsx

@@ -1,6 +1,6 @@
-import { Children } from "@alloy-js/core/jsx-runtime";
 import { useContext } from "../context.js";
 import { IndentContext } from "../context/indent.js";
+import { Children } from "../jsx-runtime.js";
 
 export interface IndentProps {
   children?: Children;

package/src/components/MemberDeclaration.tsx

@@ -1,8 +1,8 @@
-import { Children } from "@alloy-js/core/jsx-runtime";
 import { OutputSymbol, OutputSymbolFlags } from "../binder.js";
 import { useContext } from "../context.js";
 import { BinderContext } from "../context/binder.js";
 import { MemberDeclarationContext } from "../context/member-declaration.js";
+import { Children } from "../jsx-runtime.js";
 import { Refkey, refkey } from "../refkey.js";
 
 export interface MemberDeclarationProps {

package/src/components/MemberScope.tsx

@@ -1,5 +1,5 @@
-import { Children } from "@alloy-js/core/jsx-runtime";
 import { OutputSymbol } from "../binder.js";
+import { Children } from "../jsx-runtime.js";
 
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 import { OutputSymbolFlags } from "../binder.js";

package/src/components/Output.tsx

@@ -1,4 +1,3 @@
-import { Children } from "@alloy-js/core/jsx-runtime";
 import {
   createOutputBinder,
   getSymbolCreator,
@@ -6,9 +5,11 @@ import {
 } from "../binder.js";
 import { BinderContext } from "../context/binder.js";
 import { NamePolicyContext } from "../context/name-policy.js";
+import { Children } from "../jsx-runtime.js";
 import { NamePolicy } from "../name-policy.js";
 import { SourceDirectory } from "./SourceDirectory.js";
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { extensionEffects } from "../slot.js";
 import { SourceFile } from "./SourceFile.js";
 
 export interface OutputProps {
@@ -58,7 +59,7 @@ export function Output(props: OutputProps) {
   }
 
   return <BinderContext.Provider value={binder}>
-    {
+    {() => { extensionEffects.forEach(e => e())}}{
       props.namePolicy ?
         <NamePolicyContext.Provider value={props.namePolicy}>
           {dir}

package/src/components/Scope.tsx

@@ -1,8 +1,8 @@
-import { Children } from "@alloy-js/core/jsx-runtime";
 import { OutputScope } from "../binder.js";
 import { useContext } from "../context.js";
 import { BinderContext } from "../context/binder.js";
 import { ScopeContext } from "../context/scope.js";
+import { Children } from "../jsx-runtime.js";
 
 export interface ScopeProps {
   kind?: string;

package/src/components/SourceDirectory.tsx

@@ -1,8 +1,8 @@
-import { Children, getContext } from "@alloy-js/core/jsx-runtime";
 import { shallowReactive } from "@vue/reactivity";
 import { join } from "pathe";
 import { useContext } from "../context.js";
 import { SourceDirectoryContext } from "../context/source-directory.js";
+import { Children, getContext } from "../jsx-runtime.js";
 
 export interface SourceDirectoryProps {
   path: string;

package/src/components/SourceFile.tsx

@@ -1,13 +1,9 @@
-import {
-  Children,
-  ComponentDefinition,
-  getContext,
-} from "@alloy-js/core/jsx-runtime";
 import { join } from "pathe";
 import { useContext } from "../context.js";
 import { IndentContext } from "../context/indent.js";
 import { SourceDirectoryContext } from "../context/source-directory.js";
 import { SourceFileContext } from "../context/source-file.js";
+import { Children, ComponentDefinition, getContext } from "../jsx-runtime.js";
 import { Refkey } from "../refkey.js";
 
 export interface SourceFileProps {

package/src/context/assignment.ts

@@ -1,5 +1,9 @@
 import { OutputSymbol } from "../binder.js";
-import { ComponentContext, createContext, useContext } from "../context.js";
+import {
+  ComponentContext,
+  createNamedContext,
+  useContext,
+} from "../context.js";
 
 export interface AssignmentContext {
   /**
@@ -31,7 +35,7 @@ export interface AssignmentContext {
  * symbols for the object value's properties.
  */
 export const AssignmentContext: ComponentContext<AssignmentContext> =
-  createContext();
+  createNamedContext("Assignment");
 
 /**
  * Creates a new {@link (AssignmentContext:interface)}.

package/src/context/binder.ts

@@ -1,5 +1,9 @@
 import { Binder } from "../binder.js";
-import { ComponentContext, createContext, useContext } from "../context.js";
+import {
+  ComponentContext,
+  createNamedContext,
+  useContext,
+} from "../context.js";
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 import type { Output } from "../components/Output.js";
 
@@ -7,7 +11,8 @@ import type { Output } from "../components/Output.js";
  * The binder context provides the binder instance to all components. This
  * context is provided by the {@link Output | output component}.
  */
-export const BinderContext: ComponentContext<Binder> = createContext();
+export const BinderContext: ComponentContext<Binder> =
+  createNamedContext("Binder");
 
 export function useBinder() {
   return useContext(BinderContext)!;

package/src/context/declaration.ts

@@ -1,5 +1,5 @@
 import { OutputSymbol } from "../binder.js";
-import { ComponentContext, createContext } from "../context.js";
+import { ComponentContext, createNamedContext } from "../context.js";
 
 export const DeclarationContext: ComponentContext<OutputSymbol> =
-  createContext();
+  createNamedContext("Declaration");

package/src/context/indent.ts

@@ -1,10 +1,17 @@
 import { IndentState } from "../components/Indent.jsx";
-import { ComponentContext, createContext } from "../context.js";
+import {
+  ComponentContext,
+  createContext,
+  createNamedContext,
+} from "../context.js";
 
-export const IndentContext: ComponentContext<IndentState> = createContext({
-  level: 0,
-  indent: "  ",
-  indentString: "",
-});
+export const IndentContext: ComponentContext<IndentState> = createNamedContext(
+  "Indent",
+  {
+    level: 0,
+    indent: "  ",
+    indentString: "",
+  },
+);
 
 export const TestContext: ComponentContext<string> = createContext("test");

package/src/context/member-declaration.ts

@@ -1,5 +1,5 @@
 import { OutputSymbol } from "../binder.js";
-import { ComponentContext, createContext } from "../context.js";
+import { ComponentContext, createNamedContext } from "../context.js";
 
 /**
  * Provides the symbol for the member currently being declared.
@@ -7,4 +7,4 @@ import { ComponentContext, createContext } from "../context.js";
  * @see {@link DeclarationContext} for getting the symbol for the current non-member declaration.
  */
 export const MemberDeclarationContext: ComponentContext<OutputSymbol> =
-  createContext();
+  createNamedContext("MemberDeclaration");

package/src/context/member-scope.ts

@@ -1,5 +1,9 @@
 import { OutputScope } from "../binder.js";
-import { ComponentContext, createContext, useContext } from "../context.js";
+import {
+  ComponentContext,
+  createNamedContext,
+  useContext,
+} from "../context.js";
 
 /**
  * The member scope context provides the instance and static member scopes that
@@ -10,7 +14,7 @@ export interface MemberScopeContext {
   instanceMembers?: OutputScope;
 }
 export const MemberScopeContext: ComponentContext<MemberScopeContext> =
-  createContext();
+  createNamedContext("MemberScope");
 
 export function useMemberScope() {
   return useContext(MemberScopeContext)!;

package/src/context/name-policy.ts

@@ -1,8 +1,12 @@
-import { ComponentContext, createContext, useContext } from "../context.js";
+import {
+  ComponentContext,
+  createNamedContext,
+  useContext,
+} from "../context.js";
 import { NamePolicy } from "../name-policy.js";
 
 export const NamePolicyContext: ComponentContext<NamePolicy<string>> =
-  createContext<NamePolicy<string>>({
+  createNamedContext<NamePolicy<string>>("NamePolicy", {
     getName(name) {
       return name;
     },

package/src/context/scope.ts

@@ -1,7 +1,12 @@
 import { OutputScope } from "../binder.js";
-import { ComponentContext, createContext, useContext } from "../context.js";
+import {
+  ComponentContext,
+  createNamedContext,
+  useContext,
+} from "../context.js";
 
-export const ScopeContext: ComponentContext<OutputScope> = createContext();
+export const ScopeContext: ComponentContext<OutputScope> =
+  createNamedContext("Scope");
 
 export function useScope() {
   return useContext(ScopeContext)!;

package/src/context/source-directory.ts

@@ -1,4 +1,4 @@
-import { ComponentContext, createContext } from "../context.js";
+import { ComponentContext, createNamedContext } from "../context.js";
 import { SourceFileContext } from "./source-file.js";
 
 export interface SourceDirectoryContext {
@@ -8,4 +8,4 @@ export interface SourceDirectoryContext {
 }
 
 export const SourceDirectoryContext: ComponentContext<SourceDirectoryContext> =
-  createContext();
+  createNamedContext("SourceDirectory");

package/src/context/source-file.ts

@@ -1,4 +1,4 @@
-import { ComponentContext, createContext } from "../context.js";
+import { ComponentContext, createNamedContext } from "../context.js";
 import { ComponentDefinition } from "../jsx-runtime.js";
 import { Refkey } from "../refkey.js";
 
@@ -9,4 +9,4 @@ export interface SourceFileContext {
 }
 
 export const SourceFileContext: ComponentContext<SourceFileContext> =
-  createContext();
+  createNamedContext("SourceFile");

package/src/context.ts

@@ -1,16 +1,17 @@
+import { shallowRef } from "@vue/reactivity";
 import {
   Children,
   ComponentDefinition,
   effect,
   getContext,
   untrack,
-} from "@alloy-js/core/jsx-runtime";
-import { shallowRef } from "@vue/reactivity";
+} from "./jsx-runtime.js";
 
 export interface ComponentContext<T> {
   id: symbol;
   default: T | undefined;
   Provider: ComponentDefinition<ContextProviderProps<T>>;
+  name?: string;
 }
 
 export interface ContextProviderProps<T = unknown> {
@@ -31,13 +32,17 @@ export function useContext<T>(context: ComponentContext<T>): T | undefined {
   return context.default;
 }
 
+export const contextsByKey = new Map<symbol, ComponentContext<any>>();
+
 export function createContext<T = unknown>(
   defaultValue?: T,
+  name?: string,
 ): ComponentContext<T> {
-  const id = Symbol("context");
-  return {
+  const id = Symbol(name ?? "context");
+  const ctx = {
     id,
     default: defaultValue,
+    name,
     Provider(props: ContextProviderProps<T>) {
       const context = getContext();
 
@@ -50,4 +55,10 @@ export function createContext<T = unknown>(
       return rendered.value;
     },
   };
+  contextsByKey.set(id, ctx);
+  return ctx;
+}
+
+export function createNamedContext<T>(name: string, defaultValue?: T) {
+  return createContext<T>(defaultValue, name);
 }