@alloy-js/core 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alloy-js/core",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "",
   "main": "./dist/src/index.js",
   "exports": {
@@ -9,6 +9,7 @@
       "import": "./dist/src/index.js"
     },
     "./jsx-runtime": {
+      "types": "./dist/src/jsx-runtime.d.ts",
       "development": "./src/jsx-runtime.ts",
       "import": "./dist/src/jsx-runtime.js"
     },
@@ -25,6 +26,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 +37,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"
   },
@@ -41,11 +48,8 @@
     "@rollup/plugin-babel": "^6.0.4",
     "@rollup/plugin-typescript": "^11.1.6",
     "concurrently": "^8.2.2",
-    "typescript": "^5.5.4",
-    "vitest": "^2.0.5"
-  },
-  "overrides": {
-    "esbuild": "0.23"
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.4"
   },
   "type": "module",
   "scripts": {

package/src/binder.ts

@@ -1,14 +1,16 @@
-import { memo } from "@alloy-js/core/jsx-runtime";
 import {
   computed,
   effect,
   reactive,
+  ref,
   Ref,
   ShallowRef,
   shallowRef,
 } from "@vue/reactivity";
+import { useBinder } from "./context/binder.js";
 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;
 
@@ -222,6 +224,21 @@ export interface OutputScope {
   getSymbolNames(): Set<string>;
 }
 
+export type CreateSymbolOptions<T extends OutputSymbol = OutputSymbol> = {
+  name: string;
+  scope?: OutputScope;
+  refkey?: Refkey;
+  flags?: OutputSymbolFlags;
+} & Omit<T, keyof OutputSymbol>;
+
+export type CreateScopeOptions<T extends OutputScope = OutputScope> = {
+  kind: T["kind"];
+  name: string;
+  parent?: OutputScope | undefined;
+  flags?: OutputScopeFlags;
+  owner?: OutputSymbol;
+} & Omit<T, keyof OutputScope>;
+
 /**
  * The binder tracks all output scopes and symbols. Scopes are nested containers
  * for symbols.
@@ -240,28 +257,13 @@ export interface Binder {
    * Create a new scope. The scope will be added to the parent scope's children.
    * The returned scope object is reactive.
    */
-  createScope<T extends OutputScope>(
-    args: {
-      kind: T["kind"];
-      name: string;
-      parent?: OutputScope | undefined;
-      flags?: OutputScopeFlags;
-      owner?: OutputSymbol;
-    } & Omit<T, keyof OutputScope>,
-  ): T;
+  createScope<T extends OutputScope>(args: CreateScopeOptions<T>): T;
 
   /**
    * Create a new symbol. The symbol will be added to the parent scope's symbols.
    * The returned symbol object is reactive.
    */
-  createSymbol<T extends OutputSymbol>(
-    args: {
-      name: string;
-      scope?: OutputScope;
-      refkey?: unknown;
-      flags?: OutputSymbolFlags;
-    } & Omit<T, keyof OutputSymbol>,
-  ): T;
+  createSymbol<T extends OutputSymbol>(args: CreateSymbolOptions<T>): T;
 
   /**
    * Instantiate the static members of a symbol into the instance members of
@@ -302,6 +304,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 +363,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 +419,9 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
     addStaticMembersToSymbol,
     addInstanceMembersToSymbol,
     instantiateSymbolInto,
+    findSymbolName,
+    findScopeName,
+    resolveFQN: resolveFQN as any,
     globalScope: undefined as any,
   };
 
@@ -396,18 +441,18 @@ 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;
 
-  function createScope<T extends OutputScope>(
-    args: {
-      kind: string;
-      name: string;
-      parent?: OutputScope;
-      flags?: OutputScopeFlags;
-      owner?: OutputSymbol;
-    } & Omit<T, keyof OutputScope>,
-  ): T {
+  function createScope<T extends OutputScope>(args: CreateScopeOptions<T>): T {
     const {
       kind,
       name,
@@ -454,16 +499,19 @@ 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;
   }
 
   function createSymbol<T extends OutputSymbol>(
-    args: {
-      name: string;
-      scope?: OutputScope;
-      refkey?: Refkey;
-      flags?: OutputSymbolFlags;
-    } & Omit<T, keyof OutputSymbol>,
+    args: CreateSymbolOptions<T>,
   ): T {
     const {
       name,
@@ -531,7 +579,7 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
     scope.symbolsByRefkey.set(symbol.refkey, symbol);
 
     deconflict(symbol);
-    notifyRefkey(refkey, symbol);
+    notifyRefkey(symbol);
 
     return symbol;
   }
@@ -747,16 +795,132 @@ export function createOutputBinder(options: BinderOptions = {}): Binder {
     return computed(() => cb(declSignal.value));
   }
 
-  function notifyRefkey(
-    refkey: Refkey | undefined,
-    symbol: OutputSymbol,
-  ): void {
-    if (!refkey) return;
-    knownDeclarations.set(refkey, symbol);
-    if (waitingDeclarations.has(refkey)) {
-      const signal = waitingDeclarations.get(refkey)!;
-      signal.value = symbol;
-    }
+  function notifyRefkey(symbol: OutputSymbol): void {
+    effect(() => {
+      const refkey = symbol.refkey;
+      if (!refkey) return;
+
+      knownDeclarations.set(refkey, symbol);
+      if (waitingDeclarations.has(refkey)) {
+        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;
+    });
   }
 }
 
@@ -774,7 +938,7 @@ export function resolve<
   TScope extends OutputScope,
   TSymbol extends OutputSymbol,
 >(refkey: Refkey): Ref<ResolutionResult<TScope, TSymbol>> {
-  const scope = useScope();
+  const scope = useScope() ?? useBinder().globalScope;
   const memberScope = useMemberScope();
   const binder = scope.binder;
 

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,8 +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 { extensionEffects } from "../slot.js";
 import { SourceDirectory } from "./SourceDirectory.js";
+
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 import { SourceFile } from "./SourceFile.js";
 
@@ -58,7 +60,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,12 +1,12 @@
-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;
-  children?: Children[];
+  children?: Children;
 }
 
 export function SourceDirectory(props: SourceDirectoryProps) {

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 {
@@ -21,7 +17,7 @@ export interface SourceFileProps {
    */
   filetype: string;
 
-  children?: Children[];
+  children?: Children;
 
   /**
    * The component to use to render refkeys references within the file's

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,9 @@
 import { OutputSymbol } from "../binder.js";
-import { ComponentContext, createContext } from "../context.js";
+import {
+  ComponentContext,
+  createNamedContext,
+  useContext,
+} from "../context.js";
 
 /**
  * Provides the symbol for the member currently being declared.
@@ -7,4 +11,8 @@ 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");
+
+export function useMemberDeclaration() {
+  return useContext(MemberDeclarationContext);
+}

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)!;