@alloy-js/python 0.4.0-dev.2 → 0.4.0-dev.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alloy-js/python",
-  "version": "0.4.0-dev.2",
+  "version": "0.4.0-dev.5",
   "description": "Python bindings for Alloy",
   "repository": {
     "type": "git",
@@ -8,9 +8,11 @@
   },
   "exports": {
     ".": {
+      "development": "./dist/dev/src/index.js",
       "import": "./dist/src/index.js"
     },
     "./stc": {
+      "development": "./dist/dev/src/components/stc/index.js",
       "import": "./dist/src/components/stc/index.js"
     }
   },
@@ -18,12 +20,12 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "@alloy-js/core": "~0.22.0 || >= 0.23.0-dev.8",
+    "@alloy-js/core": "~0.22.0 || >= 0.23.0-dev.12",
     "change-case": "^5.4.4",
     "pathe": "^2.0.3"
   },
   "devDependencies": {
-    "@alloy-js/cli": "~0.22.0 || >= 0.23.0-dev.3",
+    "@alloy-js/cli": "~0.22.0 || >= 0.23.0-dev.4",
     "@alloy-js/rollup-plugin": "~0.1.0 || >= 0.1.1-dev.1",
     "@microsoft/api-extractor": "~7.52.8",
     "@rollup/plugin-typescript": "^12.1.2",
@@ -34,7 +36,7 @@
   "type": "module",
   "scripts": {
     "generate-docs": "api-extractor run",
-    "build": "alloy build && pnpm run generate-docs",
+    "build": "alloy build --with-dev && pnpm run generate-docs",
     "clean": "rimraf dist/ .temp/",
     "test:watch": "vitest -w",
     "watch": "alloy build --watch",

package/src/components/CallSignature.tsx

@@ -13,6 +13,7 @@ import {
 import { createPythonSymbol } from "../symbol-creation.js";
 import { PythonOutputSymbol } from "../symbols/index.js";
 import { Atom } from "./Atom.jsx";
+import { TypeRefContext } from "./TypeRefContext.jsx";
 
 export type ParameterMarker = "*" | "/";
 
@@ -75,7 +76,10 @@ function parameter(param: DeclaredParameterDescriptor) {
     <group>
       {param.symbol.name}
       <Show when={!!param.type}>
-        : <TypeSlot>{param.type}</TypeSlot>
+        :{" "}
+        <TypeRefContext>
+          <TypeSlot>{param.type}</TypeSlot>
+        </TypeRefContext>
       </Show>
       <Show when={param.default !== undefined}>
         <Show when={!param.type}>=</Show>
@@ -184,7 +188,7 @@ export function CallSignature(props: CallSignatureProps) {
     props.returnType ?
       <>
         {" -> "}
-        {props.returnType}
+        <TypeRefContext>{props.returnType}</TypeRefContext>
       </>
     : undefined;
 

package/src/components/ImportStatement.tsx

@@ -6,6 +6,53 @@ export interface ImportStatementsProps {
   joinImportsFromSameModule?: boolean;
 }
 
+export interface CategorizedImports {
+  /** Imports used only in type annotation contexts (for TYPE_CHECKING block) */
+  typeImports: ImportRecords;
+  /** Regular imports used at runtime */
+  valueImports: ImportRecords;
+}
+
+/**
+ * Categorize import records into type-only and value imports.
+ * Type-only imports are those used only in type annotation contexts.
+ * Value imports are regular imports used at runtime.
+ */
+export function categorizeImportRecords(
+  records: ImportRecords,
+): CategorizedImports {
+  const typeImports = new Map() as ImportRecords;
+  const valueImports = new Map() as ImportRecords;
+
+  for (const [module, properties] of records) {
+    if (!properties.symbols || properties.symbols.size === 0) {
+      // Module-level imports without symbols go to value imports
+      valueImports.set(module, properties);
+      continue;
+    }
+
+    const typeSymbols = new Set<ImportedSymbol>();
+    const valueSymbols = new Set<ImportedSymbol>();
+
+    for (const sym of properties.symbols) {
+      if (sym.local.isTypeOnly) {
+        typeSymbols.add(sym);
+      } else {
+        valueSymbols.add(sym);
+      }
+    }
+
+    if (typeSymbols.size > 0) {
+      typeImports.set(module, { symbols: typeSymbols });
+    }
+    if (valueSymbols.size > 0) {
+      valueImports.set(module, { symbols: valueSymbols });
+    }
+  }
+
+  return { typeImports, valueImports };
+}
+
 /**
  * A component that renders import statements based on the provided import records.
  *
@@ -16,11 +63,11 @@ export interface ImportStatementsProps {
  */
 export function ImportStatements(props: ImportStatementsProps) {
   // Sort the import records by module name
-  const imports = computed(() =>
-    [...props.records].sort(([a], [b]) => {
+  const imports = computed(() => {
+    return [...props.records].sort(([a], [b]) => {
       return a.name.localeCompare(b.name);
-    }),
-  );
+    });
+  });
 
   return mapJoin(
     () => imports.value,
@@ -45,7 +92,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/Reference.tsx

@@ -1,4 +1,5 @@
 import { computed, emitSymbol, Refkey } from "@alloy-js/core";
+import { isTypeRefContext } from "../context/type-ref-context.js";
 import { ref } from "../symbols/index.js";
 
 export interface ReferenceProps {
@@ -13,7 +14,8 @@ export interface ReferenceProps {
  * It takes a `refkey` prop which is the key of the symbol to reference.
  */
 export function Reference({ refkey }: ReferenceProps) {
-  const reference = ref(refkey);
+  const inTypeRef = isTypeRefContext();
+  const reference = ref(refkey, { type: inTypeRef });
   const symbolRef = computed(() => reference()[1]);
 
   emitSymbol(symbolRef);