@alloy-js/core 0.23.0-dev.9 → 0.24.0-dev.1

package/src/components/AccessExpression.tsx

@@ -0,0 +1,344 @@
+import {
+  Children,
+  childrenArray,
+  ComponentCreator,
+  ComponentDefinition,
+  computed,
+  isComponentCreator,
+  OutputSymbol,
+  Refkeyable,
+  symbolForRefkey,
+  takeSymbols,
+} from "../index.js";
+
+/**
+ * Base props that all language-specific Part components must include.
+ * Language packages extend this with additional props.
+ */
+export interface BasePartProps {
+  refkey?: Refkeyable;
+  symbol?: OutputSymbol;
+}
+
+/**
+ * Configuration for creating a language-specific access expression component.
+ *
+ * @typeParam TPartProps - The Part component's props type (extends BasePartProps)
+ * @typeParam TPart - The descriptor type that formatPart receives
+ */
+export interface AccessExpressionConfig<
+  TPartProps extends BasePartProps,
+  TPart,
+> {
+  /**
+   * Convert Part props + resolved symbol into a plain descriptor object.
+   * Called once per Part during children processing. The returned descriptor
+   * is wrapped in a computed + getter delegation for reactive optimization.
+   */
+  createDescriptor(
+    props: TPartProps,
+    symbol: OutputSymbol | undefined,
+    first: boolean,
+  ): TPart;
+
+  /**
+   * Extract the base content from the first part (the leftmost identifier).
+   */
+  getBase(part: TPart): Children;
+
+  /**
+   * Format a non-first part given its descriptor and the previous part.
+   * Returns JSX children for that segment (e.g., `.foo`, `?.bar`, `[idx]`, `(args)`).
+   * `inCallChain` is true when rendering inside a chunked call chain.
+   */
+  formatPart(part: TPart, prevPart: TPart, inCallChain: boolean): Children;
+
+  /**
+   * Identify which parts are function calls, for call chain detection.
+   * When provided, the factory uses the chunked call chain algorithm
+   * (line breaks after each call group) when more than one call is detected.
+   * When omitted, the expression is always formatted linearly.
+   */
+  isCallPart?(part: TPart): boolean;
+
+  /**
+   * Additional check for whether call chain formatting should be used.
+   * Called only when `isCallPart` is provided and more than one call is detected.
+   * Return false to force linear formatting (e.g., TypeScript disables call
+   * chains when any part has `await`).
+   * Defaults to `() => true`.
+   */
+  canUseCallChains?(parts: TPart[]): boolean;
+
+  /**
+   * Post-process the accumulated expression after each part in linear
+   * (non-call-chain) mode. Use this for language-specific wrapping like
+   * TypeScript's `await` which wraps the entire expression so far.
+   * Defaults to identity (returns expression unchanged).
+   */
+  wrapPartResult?(
+    expression: Children,
+    part: TPart,
+    index: number,
+    isLast: boolean,
+  ): Children;
+}
+
+/**
+ * Create a language-specific access/member expression component pair.
+ *
+ * Returns `{ Expression, Part }` where:
+ * - `Expression` is the main component that collects Part children and renders the chain
+ * - `Part` is a no-op component whose props are consumed by Expression
+ *
+ * The factory handles:
+ * - Children collection and Part filtering
+ * - Symbol resolution (refkey → symbol via binder, single computed per part)
+ * - Reactive optimization (getter delegation over single computed per part)
+ * - Flattening nested Expression instances
+ * - `takeSymbols()` to prevent symbol leakage
+ * - Call chain detection and chunked formatting algorithm
+ */
+export function createAccessExpression<
+  TPartProps extends BasePartProps,
+  TPart extends Record<string, unknown>,
+>(config: AccessExpressionConfig<TPartProps, TPart>) {
+  // Additional component references to match during flattening.
+  // Used when the wrapper function (e.g. MemberExpression) differs
+  // from the inner Expression function.
+  const outerComponents: ComponentDefinition<any>[] = [];
+
+  function Expression(props: { children: Children }): Children {
+    const children = flattenExpression(childrenArray(() => props.children));
+    const parts = collectParts(children);
+    takeSymbols();
+
+    if (parts.length === 0) {
+      return <></>;
+    }
+
+    const { isCallPart, canUseCallChains } = config;
+
+    if (!isCallPart) {
+      return formatLinear(config, parts);
+    }
+
+    const isCallChain = computed(() => {
+      if (canUseCallChains && !canUseCallChains(parts)) {
+        return false;
+      }
+      let callCount = 0;
+      for (const part of parts) {
+        if (isCallPart(part)) callCount++;
+      }
+      return callCount > 1;
+    });
+
+    return () => {
+      return isCallChain.value ?
+          formatCallChain(config, parts)
+        : formatLinear(config, parts);
+    };
+  }
+
+  function Part(_props: TPartProps) {
+    // No-op — props are consumed by the parent Expression component.
+  }
+
+  function isExpressionComponent(child: unknown): boolean {
+    if (isComponentCreator(child, Expression)) return true;
+    for (const comp of outerComponents) {
+      if (isComponentCreator(child, comp as any)) return true;
+    }
+    return false;
+  }
+
+  function flattenExpression(children: Children[]): Children[] {
+    const flattened: Children[] = [];
+    for (const child of children) {
+      if (isExpressionComponent(child)) {
+        flattened.push(
+          ...flattenExpression(
+            childrenArray(() => (child as ComponentCreator).props.children),
+          ),
+        );
+      } else {
+        flattened.push(child);
+      }
+    }
+    return flattened;
+  }
+
+  function collectParts(children: Children[]): TPart[] {
+    const parts: TPart[] = [];
+    for (const child of children) {
+      if (!isComponentCreator(child, Part)) continue;
+      const partProps = child.props as TPartProps;
+      const first = parts.length === 0;
+
+      const symbolSource = computed(() => {
+        if (partProps.refkey) {
+          return symbolForRefkey(partProps.refkey).value;
+        } else if (partProps.symbol) {
+          return partProps.symbol;
+        }
+        return undefined;
+      });
+
+      const desc = computed(() =>
+        config.createDescriptor(partProps, symbolSource.value, first),
+      );
+
+      // Create getter-delegation object for reactive optimization.
+      // Property access on this object tracks the single `desc` computed.
+      const keys = Object.keys(
+        config.createDescriptor(partProps, undefined, first),
+      );
+      const proxy: Record<string, unknown> = {};
+      for (const key of keys) {
+        Object.defineProperty(proxy, key, {
+          get() {
+            return (desc.value as Record<string, unknown>)[key];
+          },
+          enumerable: true,
+        });
+      }
+
+      parts.push(proxy as TPart);
+    }
+    return parts;
+  }
+
+  /**
+   * Register an outer wrapper component for flattening support.
+   * Call this after creating the wrapper function:
+   *   `registerOuterComponent(MemberExpression);`
+   */
+  function registerOuterComponent(component: ComponentDefinition<any>) {
+    outerComponents.push(component);
+  }
+
+  return { Expression, Part, registerOuterComponent };
+}
+
+/**
+ * Format parts linearly (no call chain grouping).
+ */
+function formatLinear<TPartProps extends BasePartProps, TPart>(
+  config: AccessExpressionConfig<TPartProps, TPart>,
+  parts: TPart[],
+): Children {
+  return computed(() => {
+    let expression: Children = [];
+
+    for (let i = 0; i < parts.length; i++) {
+      const part = parts[i];
+
+      if (i === 0) {
+        (expression as Children[]).push(config.getBase(part));
+      } else {
+        const prevPart = parts[i - 1];
+        const partExpr = config.formatPart(part, prevPart, false);
+
+        if (Array.isArray(expression)) {
+          expression.push(partExpr);
+        } else {
+          expression = (
+            <>
+              {expression}
+              {partExpr}
+            </>
+          );
+        }
+      }
+
+      if (config.wrapPartResult) {
+        expression = config.wrapPartResult(
+          expression,
+          part,
+          i,
+          i === parts.length - 1,
+        );
+      }
+    }
+
+    return expression;
+  });
+}
+
+/**
+ * Format parts as a call chain with indented line breaks at call boundaries.
+ */
+function formatCallChain<TPartProps extends BasePartProps, TPart>(
+  config: AccessExpressionConfig<TPartProps, TPart>,
+  parts: TPart[],
+): Children {
+  return computed(() => {
+    const expression: Children[] = [];
+    const chunks: TPart[][] = [];
+    let pi = 0;
+
+    function pushPart() {
+      chunks.at(-1)!.push(parts[pi]);
+      pi++;
+    }
+
+    function pushChunk() {
+      chunks.push([]);
+    }
+
+    // First chunk: take parts up to and including the first call
+    pushChunk();
+    while (
+      pi < parts.length &&
+      (pi === parts.length - 1 ||
+        chunks.at(-1)!.length === 0 ||
+        !config.isCallPart!(parts[pi + 1]))
+    ) {
+      pushPart();
+      if (config.isCallPart!(chunks.at(-1)!.at(-1)!)) {
+        break;
+      }
+    }
+
+    // Remaining chunks: collect non-call parts then call parts
+    while (pi < parts.length) {
+      pushChunk();
+      while (pi < parts.length && !config.isCallPart!(parts[pi])) {
+        pushPart();
+      }
+      while (pi < parts.length && config.isCallPart!(parts[pi])) {
+        pushPart();
+      }
+    }
+
+    for (let ci = 0; ci < chunks.length; ci++) {
+      const chunk = chunks[ci];
+      const chunkExpr = [];
+      for (let cpi = 0; cpi < chunk.length; cpi++) {
+        if (ci === 0 && cpi === 0) {
+          chunkExpr.push(config.getBase(chunk[0]));
+          continue;
+        }
+        const part = chunk[cpi];
+        const prevPart = cpi === 0 ? chunks[ci - 1].at(-1)! : chunk[cpi - 1];
+        chunkExpr.push(config.formatPart(part, prevPart, true));
+      }
+
+      expression.push(
+        ci === 0 ? chunkExpr : (
+          <>
+            <sbr />
+            {chunkExpr}
+          </>
+        ),
+      );
+    }
+
+    return (
+      <group>
+        <indent>{expression}</indent>
+      </group>
+    );
+  });
+}

package/src/components/Block.tsx

@@ -31,6 +31,18 @@ export interface BlockProps {
  * Create an indented block of source text. The block has `opener` text which is
  * added prior to the block, which defaults to `"{"`, and `closer` text which is
  * added after the block, which defaults to `"}"`.
+ *
+ * @remarks
+ *
+ * When `children` is empty, `Block` renders as `{}` (opener immediately followed
+ * by closer) with no indented content — no explicit empty check is needed before
+ * passing children.
+ *
+ * @example
+ * ```tsx
+ * // Safe even when props.members is empty — renders `{}`
+ * <Block>{props.members}</Block>
+ * ```
  */
 export function Block(props: BlockProps) {
   const ContentSlot = createContentSlot();

package/src/components/For.tsx

@@ -80,15 +80,19 @@ export function For<
   const cb = props.children;
   const options = baseListPropsToMapJoinArgs(props);
   options.skipFalsy = props.skipFalsy;
-  return memo(() => {
-    const maybeRef = props.each;
+  return memo(
+    () => {
+      const maybeRef = props.each;
 
-    return (mapJoin as any)(
-      typeof maybeRef === "function" ? maybeRef : (
-        () => (isRef(maybeRef) ? maybeRef.value : maybeRef)
-      ),
-      cb,
-      options,
-    );
-  });
+      return (mapJoin as any)(
+        typeof maybeRef === "function" ? maybeRef : (
+          () => (isRef(maybeRef) ? maybeRef.value : maybeRef)
+        ),
+        cb,
+        options,
+      );
+    },
+    undefined,
+    "For",
+  );
 }

package/src/components/List.tsx

@@ -39,7 +39,17 @@ export interface BaseListProps {
   ender?: Children;
 
   /**
-   * Place the join punctuation at the end, but without a line break.
+   * Place the join punctuation at the end, without a line break. The punctuation
+   * is emitted unconditionally in flat and broken modes.
+   *
+   * To add trailing punctuation only in broken mode, use `ender` with `<ifBreak>`
+   * inside a `<group>` with a non-hardline joiner (e.g. `line`):
+   *
+   * ```tsx
+   * <group>
+   *   <List comma line ender={<ifBreak>,</ifBreak>}>...</List>
+   * </group>
+   * ```
    */
   enderPunctuation?: boolean;
 }
@@ -57,10 +67,13 @@ export interface ListProps extends BaseListProps {
  */
 export function List(props: ListProps) {
   const [rest, forProps] = splitProps(props, ["children"]);
-  const resolvedChildren = memo(() =>
-    childrenArray(() => rest.children, {
-      preserveFragments: true,
-    }),
+  const resolvedChildren = memo(
+    () =>
+      childrenArray(() => rest.children, {
+        preserveFragments: true,
+      }),
+    undefined,
+    "List:children",
   );
   return (
     <For each={resolvedChildren} {...forProps} skipFalsy>

package/src/components/MemberDeclaration.tsx

@@ -60,16 +60,16 @@ export type MemberDeclarationProps =
  *
  * This component must be called in one of two ways: with a name and an optional
  * refkey, or else passing in the symbol. When called with a name and refkey, a
- * symbol will be created in the current scope (provided by
- * {@link MemberDeclarationContext}) with that name and refkey. If a refkey is not
- * provided, `refkey(props.name)` is used.
+ * `BasicSymbol` will be created in the current member space. When called with a
+ * `name`, the owning scope must be a `BasicScope`; for custom scope/symbol
+ * types, pass a pre-created `symbol` instead.
  *
  * When called with a symbol, that symbol is merely exposed via
- * {@link MemberDeclarationContext}. It is assumed that the caller of this component
- * has created the symbol with the `createSymbol` API on the
- * {@link BinderContext}.
+ * {@link MemberDeclarationContext} (not {@link DeclarationContext}). Use
+ * {@link MemberName} (not `<Name />`) to render the declared member's name.
  *
  * @see {@link BinderContext}
+ * @see {@link MemberName}
  */
 export function MemberDeclaration(props: MemberDeclarationProps) {
   const binder = useContext(BinderContext);

package/src/components/MemberName.tsx

@@ -1,6 +1,12 @@
 import { useContext } from "../context.js";
 import { MemberDeclarationContext } from "../context/member-declaration.js";
 
+/**
+ * Renders the name of the current member declaration from
+ * {@link MemberDeclarationContext}. Use this inside a
+ * {@link MemberDeclaration} component instead of `<Name />`, which reads from
+ * the top-level {@link DeclarationContext}.
+ */
 export function MemberName() {
   const declSymbol = useContext(MemberDeclarationContext);
   if (!declSymbol) {

package/src/components/MemberScope.tsx

@@ -56,6 +56,11 @@ export type MemberScopeProps =
  * like. In some languages, this scope may provide symbols which are can be
  * referenced lexically, but in other languages, these members may not be in
  * scope and instead must be referenced via the owner symbol itself.
+ *
+ * When called with `name` (without `value`), this delegates to `<Scope>` which
+ * creates a `BasicScope`. The same restriction applies: the parent scope must
+ * be a `BasicScope`. For custom scope types, create your scope and pass it via
+ * the `value` prop.
  */
 export function MemberScope(props: MemberScopeProps) {
   if ("value" in props) {

package/src/components/Output.tsx

@@ -1,6 +1,7 @@
 import {
   createOutputBinder,
   getSymbolCreator,
+  NameConflictResolver,
   SymbolCreator,
 } from "../binder.js";
 import { BinderContext } from "../context/binder.js";
@@ -28,8 +29,10 @@ export interface OutputProps extends PrintTreeOptions {
 
   /**
    * Policy for handling multiple symbols declared with the same name.
+   *
+   * @see {@link NameConflictResolver}
    */
-  nameConflictResolver?: (name: string, symbols: any[]) => void;
+  nameConflictResolver?: NameConflictResolver;
 
   /**
    * The base path for the output contents. Defaults to "."

package/src/components/Scope.tsx

@@ -47,6 +47,12 @@ export type ScopeProps = ScopePropsWithValue | ScopePropsWithInfo;
  * Declare a scope for this component's children. Any symbols and scopes
  * declared in the children of this component will be in this scope.
  *
+ * @remarks
+ *
+ * When called with `name` (without `value`), this creates a `BasicScope`. The
+ * parent scope must also be a `BasicScope`; for custom scope types, create your
+ * scope and pass it via the `value` prop instead.
+ *
  * @see {@link ScopeContext}
  */
 export function Scope(props: ScopeProps) {

package/src/components/SourceFile.tsx

@@ -17,6 +17,11 @@ export interface SourceFileProps extends PrintTreeOptions {
 
   /**
    * The type of contents in this file.
+   *
+   * @remarks
+   * This is a metadata hint only. It does not trigger formatting or content
+   * processing. The value is forwarded to debug tooling and the
+   * `ContentOutputFile` output metadata.
    */
   filetype: string;
 
@@ -28,8 +33,23 @@ export interface SourceFileProps extends PrintTreeOptions {
    */
   reference?: ComponentDefinition<{ refkey: Refkey }>;
   /**
-   * The header of the file. This is rendered before the contents of the file.
-   * This is useful for adding license headers or other metadata to the file.
+   * Content rendered before the file body, separated from it by a hard line
+   * break. The separator is emitted whenever `header` is not `undefined` —
+   * including when it is an empty string or a component that renders nothing.
+   * To suppress both the header and the separator, omit this prop entirely.
+   *
+   * @example
+   * ```tsx
+   * // Omitting `header` suppresses both header and separator:
+   * <SourceFile filetype="txt" path="output/data.txt">
+   *   {children}
+   * </SourceFile>
+   *
+   * // An empty string still emits the separator newline:
+   * <SourceFile filetype="txt" path="output/data.txt" header="">
+   *   {children}
+   * </SourceFile>
+   * ```
    */
   header?: Children;
 }

package/src/components/Switch.tsx

@@ -27,15 +27,19 @@ export function Switch(props: SwitchProps) {
   const children = childrenArray(() => props.children);
   const matches = findKeyedChildren(children, matchTag);
 
-  return memo(() => {
-    for (const match of matches) {
-      if (match.props.when || match.props.else) {
-        return match.props.children;
+  return memo(
+    () => {
+      for (const match of matches) {
+        if (match.props.when || match.props.else) {
+          return match.props.children;
+        }
       }
-    }
 
-    return undefined;
-  });
+      return undefined;
+    },
+    undefined,
+    "Switch",
+  );
 }
 
 export interface MatchProps {

package/src/components/index.tsx

@@ -1,3 +1,4 @@
+export * from "./AccessExpression.jsx";
 export * from "./AppendFile.jsx";
 export * from "./Block.js";
 export * from "./CopyFile.jsx";

package/src/context/binder.ts

@@ -14,6 +14,10 @@ import type { Output } from "../components/Output.js";
 export const BinderContext: ComponentContext<Binder> =
   createNamedContext("Binder");
 
+/**
+ * Returns the current {@link Binder} from context, or `undefined` if no
+ * binder is available. The binder is provided by the {@link Output} component.
+ */
 export function useBinder() {
   return useContext(BinderContext);
 }

package/src/context/format-options.ts

@@ -3,10 +3,23 @@ import { PrintTreeOptions } from "../render.js";
 
 export interface CommonFormatOptions extends PrintTreeOptions {}
 
+/**
+ * Base format options provider and consumer for all file types. Language
+ * packages create their own via {@link createFormatOptionsContextFor}.
+ */
 export const { Provider: FormatOptions, useFormatOptions } =
   createFormatOptionsContextFor<CommonFormatOptions>("*");
 
-/** Create a format options context for a specific file type */
+/**
+ * Create a format options context for a specific file type. Returns a
+ * `Provider` component and a `useFormatOptions` hook.
+ *
+ * @remarks
+ *
+ * Merge precedence: `defaults` (lowest) → Provider `value` → `overrides`
+ * argument to `useFormatOptions()` (highest). Undefined override values are
+ * ignored.
+ */
 export function createFormatOptionsContextFor<T>(
   filetype: string,
   defaults?: T,

package/src/context/scope.ts

@@ -8,6 +8,10 @@ import type { OutputScope } from "../symbols/output-scope.js";
 export const ScopeContext: ComponentContext<OutputScope> =
   createNamedContext("Scope");
 
+/**
+ * Returns the current {@link OutputScope} from context. Must be called inside
+ * a component that is a descendant of a `<Scope>` provider.
+ */
 export function useScope() {
   return useContext(ScopeContext)!;
 }

package/src/context/source-directory.ts

@@ -9,5 +9,14 @@ export interface SourceDirectoryContext {
   path: string;
 }
 
+/**
+ * Always provided by `<Output>` — `useContext(SourceDirectoryContext)` is
+ * never `undefined` inside an `<Output>` tree. At the root of the tree,
+ * `path` equals the `basePath` prop on `<Output>` (default `"./"`); nested
+ * `<SourceDirectory>` components update `path` relative to their parent.
+ *
+ * @see {@link Output}
+ * @see {@link SourceDirectory}
+ */
 export const SourceDirectoryContext: ComponentContext<SourceDirectoryContext> =
   createNamedContext("SourceDirectory");

package/src/debug/cli.ts

@@ -1,6 +1,7 @@
 import Table from "cli-table3";
 import pc from "picocolors";
 import { contextsByKey } from "../context.js";
+import { stdoutWrite } from "../host/node-host.js";
 import { getContext, untrack } from "../reactivity.js";
 import { isReactiveTarget } from "./effects.js";
 
@@ -143,7 +144,7 @@ export function debugStack() {
         currentContext.componentOwner &&
         currentContext.componentOwner.component.name !== "Provider"
       ) {
-        process.stdout.write(
+        stdoutWrite(
           style.component.name(currentContext.componentOwner.component.name) +
             "\n",
         );
@@ -164,7 +165,7 @@ export function debugStack() {
           : pc.gray("(none)"),
         ]);
 
-        process.stdout.write(table.toString() + "\n\n");
+        stdoutWrite(table.toString() + "\n\n");
         foundContexts = [];
       }