@alloy-js/python 0.4.0-dev.0 → 0.4.0-dev.3

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@alloy-js/python",
-  "version": "0.4.0-dev.0",
+  "version": "0.4.0-dev.3",
   "description": "Python bindings for Alloy",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alloy-framework/alloy.git"
+  },
   "exports": {
     ".": {
       "import": "./dist/src/index.js"
@@ -14,18 +18,18 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "@alloy-js/core": "~0.22.0 || >= 0.23.0-dev.0",
+    "@alloy-js/core": "~0.22.0 || >= 0.23.0-dev.10",
     "change-case": "^5.4.4",
     "pathe": "^2.0.3"
   },
   "devDependencies": {
-    "@alloy-js/cli": "~0.22.0 || >= 0.23.0-dev.0",
-    "@alloy-js/rollup-plugin": "~0.1.0 || >= 0.1.1-dev.0",
+    "@alloy-js/cli": "~0.22.0 || >= 0.23.0-dev.3",
+    "@alloy-js/rollup-plugin": "~0.1.0 || >= 0.1.1-dev.1",
     "@microsoft/api-extractor": "~7.52.8",
     "@rollup/plugin-typescript": "^12.1.2",
     "concurrently": "^9.2.0",
     "typescript": "^5.8.3",
-    "vitest": "^3.2.4"
+    "vitest": "3.2.4"
   },
   "type": "module",
   "scripts": {

package/src/components/ImportStatement.tsx

@@ -45,7 +45,7 @@ export function ImportStatements(props: ImportStatementsProps) {
           return sortedSymbols.map((symbol, idx, arr) => (
             <>
               <ImportStatement path={targetPath} symbols={new Set([symbol])} />
-              {idx < arr.length - 1 && <hbr />}
+              {/*@once*/ idx < arr.length - 1 && <hbr />}
             </>
           ));
         }

package/src/components/MemberExpression.tsx

@@ -1,57 +1,126 @@
 import {
   Children,
-  childrenArray,
   computed,
+  createAccessExpression,
   For,
-  isComponentCreator,
   List,
   OutputSymbol,
-  reactive,
-  ref,
   Refkey,
   Show,
-  takeSymbols,
-  ToRefs,
-  useBinder,
 } from "@alloy-js/core";
 
 export interface MemberExpressionProps {
   children: Children;
 }
 
-const MEMBER_ACCESS_TYPES = {
-  ATTRIBUTE: "attribute",
-  SUBSCRIPTION: "subscription",
-  CALL: "call",
-} as const;
+type PartDescriptor = {
+  type: "call" | "subscription" | "attribute";
+  name: Children | undefined;
+  expression: Children | undefined;
+  quoted: boolean;
+  args: Children[] | undefined;
+};
 
-interface AttributeDescriptor extends PartDescriptorBase {
-  type: typeof MEMBER_ACCESS_TYPES.ATTRIBUTE;
-  name: Children;
-}
+const exclusiveParts: (keyof MemberExpressionPartProps)[] = [
+  "args",
+  "refkey",
+  "symbol",
+  "id",
+  "key",
+  "keys",
+  "slice",
+];
 
-interface SubscriptionDescriptor extends PartDescriptorBase {
-  type: typeof MEMBER_ACCESS_TYPES.SUBSCRIPTION;
-  expression: Children;
-  quoted: boolean;
-}
+const { Expression, Part, registerOuterComponent } = createAccessExpression<
+  MemberExpressionPartProps,
+  PartDescriptor
+>({
+  createDescriptor(partProps, sym, first) {
+    const foundProps = exclusiveParts.filter((key) => key in partProps);
+    if (foundProps.length > 1) {
+      throw new Error(
+        `Only one of ${foundProps.join(", ")} can be used for a MemberExpression part at a time`,
+      );
+    }
 
-interface CallDescriptor extends PartDescriptorBase {
-  type: typeof MEMBER_ACCESS_TYPES.CALL;
-  args: Children[];
-}
+    // Validate slice syntax
+    if (partProps.slice) {
+      const { start, stop, step } = partProps.slice;
+      if (!start && !stop && !step) {
+        throw new Error("MemberExpression.Part: slice object cannot be empty");
+      }
+    }
 
-interface PartDescriptorBase {
-  type:
-    | typeof MEMBER_ACCESS_TYPES.CALL
-    | typeof MEMBER_ACCESS_TYPES.SUBSCRIPTION
-    | typeof MEMBER_ACCESS_TYPES.ATTRIBUTE;
-}
+    // Validate keys array
+    if (partProps.keys?.length === 0) {
+      throw new Error("MemberExpression.Part: keys array cannot be empty");
+    }
+
+    if (partProps.args !== undefined) {
+      return {
+        type: "call" as const,
+        name: undefined,
+        expression: undefined,
+        quoted: false,
+        args: partProps.args === true ? [] : (partProps.args as Children[]),
+      };
+    } else if (
+      partProps.key !== undefined ||
+      partProps.keys !== undefined ||
+      partProps.slice !== undefined
+    ) {
+      return {
+        type: "subscription" as const,
+        name: undefined,
+        expression: getSubscriptionValue(partProps),
+        quoted:
+          partProps.key !== undefined && typeof partProps.key === "string",
+        args: undefined,
+      };
+    } else {
+      let name: Children;
+      if (first && partProps.refkey) {
+        name = partProps.refkey;
+      } else if (partProps.id !== undefined) {
+        if (!isValidIdentifier(partProps.id)) {
+          throw new Error(`Invalid identifier: ${partProps.id}`);
+        }
+        name = partProps.id;
+      } else if (sym) {
+        name = sym.name;
+      } else {
+        name = "<unresolved symbol>";
+      }
 
-type PartDescriptor =
-  | AttributeDescriptor
-  | SubscriptionDescriptor
-  | CallDescriptor;
+      return {
+        type: "attribute" as const,
+        name,
+        expression: undefined,
+        quoted: false,
+        args: undefined,
+      };
+    }
+  },
+
+  getBase(part) {
+    if (part.type !== "attribute") {
+      throw new Error(
+        "The first part of a MemberExpression must be an id or refkey",
+      );
+    }
+    return part.name;
+  },
+
+  formatPart(part, _prevPart, _inCallChain) {
+    if (part.type === "call") {
+      return formatCallOutput(part);
+    } else if (part.type === "attribute") {
+      return formatAttributeOutput(part);
+    } else {
+      return formatSubscriptionOutput(part);
+    }
+  },
+});
 
 /**
  * Create a member expression from parts. Each part can provide one of
@@ -83,237 +152,20 @@ type PartDescriptor =
  * ```
  */
 export function MemberExpression(props: MemberExpressionProps): Children {
-  const children = childrenArray(() => props.children);
-  const parts = childrenToPartDescriptors(children);
-  // any symbols emitted from the children won't be relevant to
-  // parent scopes. TODO: emit the proper symbol if we know it?
-  takeSymbols();
-
-  if (parts.length === 0) {
-    return <></>;
-  }
-
-  return computed(() => {
-    return formatChain(parts);
-  });
+  return Expression(props);
 }
 
 /**
- * Build part descriptors from the children of a MemberExpression.
- */
-function childrenToPartDescriptors(children: Children[]): PartDescriptor[] {
-  const parts: PartDescriptor[] = [];
-  for (const child of children) {
-    if (!isComponentCreator(child, MemberExpression.Part)) {
-      // we ignore non-parts
-      continue;
-    }
-
-    parts.push(
-      createPartDescriptorFromProps(child.props, child === children[0]),
-    );
-  }
-
-  return parts;
-}
-
-const exclusiveParts: (keyof MemberExpressionPartProps)[] = [
-  "args",
-  "refkey",
-  "symbol",
-  "id",
-  "key",
-  "keys",
-  "slice",
-];
-/**
- * Creates a reactive part descriptor from the given part props.
+ * A part of a member expression. Each part can provide one of the following
+ * props:
  *
- * @param partProps The props for the part.
- * @param first Whether this is the first part in the expression. Refkeys are
- * handled specially for the first part.
- */
-function createPartDescriptorFromProps(
-  partProps: MemberExpressionPartProps,
-  first: boolean,
-) {
-  const foundProps = exclusiveParts.filter((key) => {
-    return key in partProps;
-  });
-
-  if (foundProps.length > 1) {
-    throw new Error(
-      `Only one of ${foundProps.join(", ")} can be used for a MemberExpression part at a time`,
-    );
-  }
-
-  // Validate slice syntax
-  if (partProps.slice) {
-    const { start, stop, step } = partProps.slice;
-    if (!start && !stop && !step) {
-      throw new Error("MemberExpression.Part: slice object cannot be empty");
-    }
-  }
-
-  // Validate keys array
-  if (partProps.keys?.length === 0) {
-    throw new Error("MemberExpression.Part: keys array cannot be empty");
-  }
-
-  const symbolSource = computed(() => {
-    if (partProps.refkey) {
-      return getSymbolForRefkey(partProps.refkey).value;
-    } else if (partProps.symbol) {
-      return partProps.symbol;
-    } else {
-      return undefined;
-    }
-  });
-
-  // Return different descriptor types based on what props are provided
-  let part: ToRefs<PartDescriptor>;
-  if (partProps.args !== undefined) {
-    // CallDescriptor
-    part = {
-      type: computed(() => {
-        return "call" as const;
-      }),
-      args: ref<any>(partProps.args === true ? [] : partProps.args),
-    };
-  } else if (
-    partProps.key !== undefined ||
-    partProps.keys !== undefined ||
-    partProps.slice !== undefined
-  ) {
-    // SubscriptionDescriptor
-    part = {
-      type: computed(() => {
-        return "subscription" as const;
-      }),
-      expression: computed(() => {
-        return getSubscriptionValue(partProps);
-      }),
-      quoted: computed(() => {
-        return partProps.key !== undefined && typeof partProps.key === "string";
-      }),
-    };
-  } else {
-    // IdentifierDescriptor
-    part = {
-      type: computed(() => {
-        return "attribute" as const;
-      }),
-      name: computed(() => {
-        if (first && partProps.refkey) {
-          return partProps.refkey;
-        } else if (partProps.id !== undefined) {
-          if (!isValidIdentifier(partProps.id)) {
-            throw new Error(`Invalid identifier: ${partProps.id}`);
-          }
-          return partProps.id;
-        } else if (symbolSource.value) {
-          return symbolSource.value.name;
-        } else {
-          return "<unresolved symbol>";
-        }
-      }),
-    };
-  }
-  return reactive(part);
-}
-
-/**
- * Convert a refkey to a symbol ref using the current binder.
- */
-function getSymbolForRefkey(refkey: Refkey) {
-  const binder = useBinder();
-  return binder!.getSymbolForRefkey(refkey);
-}
-
-/**
- * Format a chain of parts into a MemberExpression.
- */
-function formatChain(parts: PartDescriptor[]): Children {
-  return computed(() => {
-    const expression: Children[] = [];
-
-    for (let i = 0; i < parts.length; i++) {
-      const part = parts[i];
-      if (i === 0) {
-        if (!isAttributeDescriptor(part)) {
-          throw new Error(
-            "The first part of a MemberExpression must be an id or refkey",
-          );
-        }
-        expression.push(part.name);
-      } else {
-        if (isCallDescriptor(part)) {
-          expression.push(formatCallOutput(part));
-        } else if (isAttributeDescriptor(part)) {
-          expression.push(formatAttributeOutput(part));
-        } else if (isSubscriptionDescriptor(part)) {
-          expression.push(formatSubscriptionOutput(part));
-        }
-      }
-    }
-
-    return expression;
-  });
-}
-
-/**
- * Format a part of a member expression that is an array access.
- * This is used for parts like `foo[0]` or `foo["bar"]`.
+ * * **id**: The identifier for the member expression part
+ * * **refkey**: A refkey for a symbol whose name becomes the identifier
+ * * **symbol**: a symbol whose name becomes the identifier part
+ * * **args**: create a method call with the given args
  */
-function formatSubscriptionOutput(part: SubscriptionDescriptor) {
-  return (
-    <group>
-      {""}[
-      <indent>
-        <sbr />
-        {part.quoted && '"'}
-        {part.expression}
-        {part.quoted && '"'}
-      </indent>
-      <sbr />]
-    </group>
-  );
-}
-
-function formatAttributeOutput(part: AttributeDescriptor) {
-  return (
-    <group>
-      <indent>
-        <ifBreak> \</ifBreak>
-        <sbr />
-        {"."}
-        {part.name}
-      </indent>
-    </group>
-  );
-}
-
-function formatCallOutput(part: CallDescriptor) {
-  const args = computed(() => {
-    return typeof part.args === "boolean" ? [] : (part.args ?? []);
-  });
-
-  return (
-    <group>
-      {""}(<Show when={args.value.length <= 1}>{args.value[0]}</Show>
-      <Show when={args.value.length > 1}>
-        <indent>
-          <sbr />
-          <For each={args} comma line>
-            {(arg) => arg}
-          </For>
-        </indent>
-        <sbr />
-      </Show>
-      )
-    </group>
-  );
-}
+MemberExpression.Part = Part;
+registerOuterComponent(MemberExpression);
 
 export interface MemberExpressionPartProps {
   /**
@@ -359,43 +211,6 @@ export interface MemberExpressionPartProps {
    */
   args?: Children[] | boolean;
 }
-/**
- * A part of a member expression. Each part can provide one of the following
- * props:
- *
- * * **id**: The identifier for the member expression part
- * * **refkey**: A refkey for a symbol whose name becomes the identifier
- * * **symbol**: a symbol whose name becomes the identifier part
- * * **args**: create a method call with the given args
- */
-MemberExpression.Part = function (props: MemberExpressionPartProps) {
-  /**
-   * This component does nothing except hold props which are retrieved by
-   * the `MemberExpression` component.
-   */
-};
-
-function isValidIdentifier(id: Children) {
-  if (typeof id === "string" && id.includes('"')) {
-    return false;
-  }
-  return true;
-}
-function isCallDescriptor(part: PartDescriptor): part is CallDescriptor {
-  return "type" in part && part.type === MEMBER_ACCESS_TYPES.CALL;
-}
-
-function isAttributeDescriptor(
-  part: PartDescriptor,
-): part is AttributeDescriptor {
-  return "type" in part && part.type === MEMBER_ACCESS_TYPES.ATTRIBUTE;
-}
-
-function isSubscriptionDescriptor(
-  part: PartDescriptor,
-): part is SubscriptionDescriptor {
-  return "type" in part && part.type === MEMBER_ACCESS_TYPES.SUBSCRIPTION;
-}
 
 export interface SubscriptionProps {
   /**
@@ -421,6 +236,67 @@ export interface SubscriptionProps {
   };
 }
 
+// --- Formatting helpers ---
+
+function formatSubscriptionOutput(part: PartDescriptor) {
+  return (
+    <group>
+      {""}[
+      <indent>
+        <sbr />
+        {part.quoted && '"'}
+        {part.expression}
+        {part.quoted && '"'}
+      </indent>
+      <sbr />]
+    </group>
+  );
+}
+
+function formatAttributeOutput(part: PartDescriptor) {
+  return (
+    <group>
+      <indent>
+        <ifBreak> \</ifBreak>
+        <sbr />
+        {"."}
+        {part.name}
+      </indent>
+    </group>
+  );
+}
+
+function formatCallOutput(part: PartDescriptor) {
+  const args = computed(() => {
+    return typeof part.args === "boolean" ? [] : (part.args ?? []);
+  });
+
+  return (
+    <group>
+      {""}(<Show when={args.value.length <= 1}>{args.value[0]}</Show>
+      <Show when={args.value.length > 1}>
+        <indent>
+          <sbr />
+          <For each={args} comma line>
+            {(arg) => arg}
+          </For>
+        </indent>
+        <sbr />
+      </Show>
+      )
+    </group>
+  );
+}
+
+// --- Utilities ---
+
+function isValidIdentifier(id: Children) {
+  if (typeof id === "string" && id.includes('"')) {
+    return false;
+  }
+  return true;
+}
+
 function getSubscriptionValue(partProps: SubscriptionProps): Children {
   // Handle tuple keys: obj[a, b] → (a, b)
   if (partProps.keys?.length) {

package/src/components/MemberScope.tsx

@@ -1,4 +1,8 @@
-import { Children, MemberScope as CoreMemberScope } from "@alloy-js/core";
+import {
+  Children,
+  MemberScope as CoreMemberScope,
+  createScope,
+} from "@alloy-js/core";
 import { PythonMemberScope } from "../symbols/python-member-scope.js";
 import { PythonOutputSymbol } from "../symbols/python-output-symbol.js";
 import { usePythonScope } from "../symbols/scopes.js";
@@ -8,9 +12,17 @@ export interface MemberScopeProps {
 }
 
 export function MemberScope(props: MemberScopeProps) {
-  const memberScope = new PythonMemberScope("member-scope", usePythonScope(), {
-    ownerSymbol: props.ownerSymbol,
-  });
+  const parentScope = usePythonScope();
+  const binder = props.ownerSymbol.binder ?? parentScope?.binder;
+  const memberScope = createScope(
+    PythonMemberScope,
+    "member-scope",
+    parentScope,
+    {
+      ownerSymbol: props.ownerSymbol,
+      binder,
+    },
+  );
 
   return (
     <CoreMemberScope value={memberScope}>{props.children}</CoreMemberScope>

package/src/components/SourceFile.tsx

@@ -3,6 +3,7 @@ import {
   ComponentContext,
   SourceFile as CoreSourceFile,
   createNamedContext,
+  createScope,
   isComponentCreator,
   List,
   Scope,
@@ -145,7 +146,7 @@ export function SourceFile(props: SourceFileProps) {
   const path: string = join(currentDir, props.path)
     .replace(/\.py$/, "")
     .replace(/\//g, ".");
-  const scope = new PythonModuleScope(path, undefined);
+  const scope = createScope(PythonModuleScope, path, undefined);
   const sfContext: PythonSourceFileContext = {
     scope: scope,
     module: path,

package/src/create-module.ts

@@ -1,5 +1,6 @@
 import {
   type Binder,
+  createScope,
   getSymbolCreatorSymbol,
   type Refkey,
   refkey,
@@ -36,9 +37,12 @@ function createSymbols(
     // Otherwise, we append the path to the module name
     const fullModuleScopeName = props.name + (path === "." ? "" : `.${path}`);
     const keys = refkeys[path];
-    const moduleScope = new PythonModuleScope(fullModuleScopeName, undefined, {
-      binder: binder,
-    });
+    const moduleScope = createScope(
+      PythonModuleScope,
+      fullModuleScopeName,
+      undefined,
+      { binder },
+    );
 
     // Create a symbol for each exported name
     for (const exportedName of symbols ?? []) {

package/src/symbol-creation.ts

@@ -2,7 +2,8 @@ import {
   Namekey,
   OutputScopeOptions,
   OutputSpace,
-  useBinder,
+  createScope,
+  createSymbol,
   useContext,
 } from "@alloy-js/core";
 import { PythonSourceFileContext } from "./components/SourceFile.js";
@@ -62,10 +63,10 @@ export function createPythonSymbol(
     }
   }
 
-  const binder = options.binder ?? currentScope?.binder ?? useBinder();
+  const binder = options.binder ?? currentScope?.binder;
 
-  return new PythonOutputSymbol(name, targetSpace, {
-    binder: binder,
+  return createSymbol(PythonOutputSymbol, name, targetSpace, {
+    binder,
     aliasTarget: options.aliasTarget,
     refkeys: options.refkeys,
     metadata: options.metadata,
@@ -81,6 +82,10 @@ export function createLexicalScope(
   options: OutputScopeOptions = {},
 ) {
   const parent = usePythonScope();
+  const binder = options.binder ?? parent?.binder;
 
-  return new PythonLexicalScope(name, parent, options);
+  return createScope(PythonLexicalScope, name, parent, {
+    ...options,
+    binder,
+  });
 }

package/src/symbols/python-module-scope.ts

@@ -1,4 +1,4 @@
-import { reactive, shallowReactive } from "@alloy-js/core";
+import { createSymbol, reactive, shallowReactive } from "@alloy-js/core";
 import { PythonLexicalScope } from "./python-lexical-scope.js";
 import { PythonOutputSymbol } from "./python-output-symbol.js";
 
@@ -46,7 +46,8 @@ export class PythonModuleScope extends PythonLexicalScope {
       });
     }
 
-    const localSymbol = new PythonOutputSymbol(
+    const localSymbol = createSymbol(
+      PythonOutputSymbol,
       targetSymbol.name,
       this.symbols,
       { binder: this.binder, aliasTarget: targetSymbol },
@@ -60,4 +61,12 @@ export class PythonModuleScope extends PythonLexicalScope {
 
     return localSymbol;
   }
+
+  override get debugInfo(): Record<string, unknown> {
+    return {
+      ...super.debugInfo,
+      importedSymbolCount: this.#importedSymbols.size,
+      importedModuleCount: this.#importedModules.size,
+    };
+  }
 }