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

package/docs/guides/references-and-refkeys.md

@@ -0,0 +1,210 @@
+# References & Refkeys
+
+Alloy's refkey system lets you declare named symbols and reference them across files. When a reference is rendered, Alloy automatically computes the correct name, generates any needed imports, and handles name conflicts.
+
+## Creating Refkeys
+
+A **refkey** uniquely identifies a symbol. Create one with `refkey()`:
+
+```ts
+import { refkey } from "@alloy-js/core";
+
+// Unique refkey (different every call)
+const myKey = refkey();
+
+// Seeded refkey (same args → same refkey)
+const modelKey = refkey(schemaObject);
+```
+
+Seeded refkeys are the most common pattern. When you're generating code from input data (like a schema), pass the data object to `refkey()` and you'll always get the same key for the same object. This means you don't need to pass refkeys around — any code that has the original data object can recreate the same refkey.
+
+### Composite Refkeys
+
+Pass multiple arguments to create a composite key when you need multiple declarations for the same input:
+
+```tsx
+// Two declarations from the same schema
+<Declaration name="UserInput"  refkey={refkey(userSchema, "input")} />
+<Declaration name="UserOutput" refkey={refkey(userSchema, "output")} />
+```
+
+Arguments are compared by identity for objects and by value for primitives. The order matters — `refkey(a, b)` is different from `refkey(b, a)`.
+
+## Declaring Symbols
+
+Pass a refkey to a declaration component to register a symbol:
+
+```tsx
+<Declaration name="getUser" refkey={refkey(getUserOp)}>
+  {body}
+</Declaration>
+```
+
+The declaration component creates a symbol in the current scope, associated with that refkey. Other components can then reference it by the same refkey.
+
+## Referencing Symbols
+
+There are two ways to reference a declared symbol.
+
+### Inline Refkeys in JSX
+
+The simplest approach: use a refkey directly as a JSX child.
+
+```tsx
+<SourceFile path="client.ts">
+  const user = await {refkey(getUserOp)}();
+</SourceFile>
+```
+
+When a refkey appears as a JSX child, Alloy resolves it through the current source file's `reference` function. This renders the symbol's name and, if the declaration is in a different file or package, automatically generates the necessary import statement.
+
+The above might render:
+
+```ts
+import { getUser } from "./api.js";
+
+const user = await getUser();
+```
+
+### The Reference Component
+
+Each language package provides a `Reference` component for explicit control:
+
+```tsx
+import { Reference } from "@alloy-js/typescript";
+
+<Reference refkey={refkey(model)} type />;
+```
+
+The `type` prop (TypeScript-specific) generates `import type` instead of `import`. Most of the time inline refkeys are sufficient — use `Reference` when you need language-specific options.
+
+### Refkeys in `code` Templates
+
+Refkeys work inside `code` template expressions too:
+
+```tsx
+code`someExpression(${refkey(responseModel)})`;
+```
+
+This resolves the refkey and splices the rendered name into the output.
+
+## Namekeys
+
+A **namekey** is a special refkey that also carries a name and naming options. Use it when you want to both name and reference a symbol in one value:
+
+```tsx
+import { namekey } from "@alloy-js/core";
+
+const myClass = namekey("MyClass");
+
+return (
+  <>
+    <Declaration name={myClass}>{/* ... */}</Declaration>
+    {myClass}
+  </>
+);
+```
+
+This renders a declaration named `MyClass` and a reference to it. The namekey serves as both the `name` prop and a refkey.
+
+### Name Policy Bypass
+
+Namekeys can opt out of the language's name policy or conflict resolution:
+
+```tsx
+// Keep the exact name, don't apply camelCase/snake_case transforms
+const specialName = namekey("$internal", { ignoreNamePolicy: true });
+
+// Don't disambiguate if another symbol has the same name
+const fixedName = namekey("toString", { ignoreNameConflict: true });
+```
+
+### Refkey vs. Namekey
+
+|                | `refkey()`                           | `namekey()`                                  |
+| -------------- | ------------------------------------ | -------------------------------------------- |
+| **Purpose**    | Identify a symbol by its source data | Identify + name a symbol                     |
+| **Name**       | Set separately via `name` prop       | Carried in the namekey                       |
+| **Uniqueness** | Same args → same key                 | Always unique (like `refkey()` with no args) |
+| **Use when**   | Generating from input data           | Generating fixed/known names                 |
+
+Use `refkey(data)` when you're mapping input data to declarations — this is the common case. Use `namekey()` when you're creating declarations with known names that don't come from input data.
+
+## Member Refkeys
+
+Use `memberRefkey()` to reference a member of a symbol — for example, an instance property of a class:
+
+```ts
+import { memberRefkey } from "@alloy-js/core";
+
+const classKey = refkey(myClass);
+const propKey = memberRefkey(classKey, refkey(myClass, "id"));
+```
+
+Member refkeys resolve through the language's member resolution system, which handles things like `this.id` inside a class vs. `instance.id` outside.
+
+## Cross-File References
+
+Refkeys work across files automatically. When you reference a symbol declared in another file, the language package generates the necessary import:
+
+```tsx
+<SourceFile path="models.ts">
+  <Declaration name="User" refkey={refkey(userSchema)}>
+    {/* language-specific declaration body */}
+  </Declaration>
+</SourceFile>
+
+<SourceFile path="client.ts">
+  const user: {refkey(userSchema)} = await fetchUser();
+</SourceFile>
+```
+
+The language package handles the import generation. For example, in TypeScript `client.ts` renders with an auto-generated import:
+
+```ts
+import { User } from "./models.js";
+
+const user: User = await fetchUser();
+```
+
+This works across packages too — Alloy resolves the correct package name and path.
+
+**Order doesn't matter.** References can appear before their declarations in the component tree. Alloy resolves everything reactively, so forward references work naturally.
+
+## External Package Symbols
+
+Language packages provide helpers like `createPackage()` (TypeScript) or `createModule()` (Python) to declare symbols from external libraries that your generated code imports:
+
+```ts
+import { createPackage } from "@alloy-js/typescript";
+
+const node = createPackage({
+  name: "node:path",
+  descriptor: {
+    ".": { named: ["join", "resolve", "dirname"] },
+  },
+});
+
+// Reference in a component — auto-generates: import { join } from "node:path"
+code`${node.join}("a", "b")`;
+```
+
+These symbols aren't declared in the output tree — they exist only in the binder's symbol table and generate imports when referenced.
+
+## How Resolution Works
+
+When a refkey is encountered during rendering:
+
+1. The render pipeline detects the refkey (via `isRefkeyable()` check)
+2. It calls `sourceFile.reference({ refkey })` — the reference function provided by the language package's SourceFile component
+3. The language's `ref()` function calls `resolve()` from core, which searches the scope tree for the symbol matching the refkey
+4. Based on where the symbol is relative to the reference (local, different module, different package), the language package renders the appropriate syntax and generates any needed imports
+5. The result is reactive — if the symbol moves or is renamed, the reference updates automatically
+
+## Best Practices
+
+- **Seed refkeys from input data** — `refkey(schemaObj)` is better than passing refkeys around manually.
+- **Use composite keys for disambiguation** — `refkey(schema, "input")` vs `refkey(schema, "output")` when one input maps to multiple declarations.
+- **Use inline refkeys** (`{refkey(...)}` in JSX) for most references — simpler than `<Reference>`.
+- **Use `namekey` sparingly** — only when the name is known ahead of time and not derived from input data.
+- **Export declarations that need cross-file references** — a symbol must be reachable through the scope tree to be referenced.

package/docs/guides/style-guide.md

@@ -0,0 +1,244 @@
+# Alloy JSX Style Guide
+
+Idiomatic patterns for writing Alloy JSX components. Alloy JSX is **not** React — it renders to source code text, not DOM elements. Do not use HTML elements like `<div>`, `<span>`, etc.
+
+## String Content
+
+Use plain string children or the `code` template tag. **Never** wrap string literals in expression braces.
+
+```tsx
+// ✅ Good — plain text children
+<Declaration>hello world</Declaration>;
+
+// ✅ Good — code template for interpolation
+code`Promise<${returnType}>`;
+
+// ✅ Good — code template for multi-line structured output
+return code`
+  <?xml version="1.0" encoding="UTF-8"?>
+  <project>
+    ${children}
+  </project>
+`;
+
+// ❌ Bad — unnecessary expression wrapper around a string
+<Declaration>{"hello world"}</Declaration>;
+```
+
+Use `code` template tags for any output that mixes static text with interpolated expressions. Use plain template literals only for inline fragments that won't appear directly in rendered output (e.g. computing a variable).
+
+When you introduce a JSX line break only for source formatting, preserve any rendered space that should still exist at that boundary with `{' '}`:
+
+```tsx
+// ✅ Good — line break is only for formatting, so keep the rendered space explicit
+<>
+  Hello{' '}
+  world
+</>
+
+// ❌ Avoid — the line break removed the intended space between words
+<>
+  Hello
+  world
+</>
+```
+
+## Conditional Rendering
+
+Use `{condition && content}` for short inline content like keywords, punctuation, or modifiers:
+
+```tsx
+// ✅ Good — short conditional modifier
+{
+  props.async && "async ";
+}
+{
+  props.nullable && "?";
+}
+{
+  !props.children && ";";
+}
+```
+
+Use `<Show when={}>` for larger conditional blocks:
+
+```tsx
+// ✅ Good — conditional block with Show
+<Show when={!!param.type}>
+  : <TypeSlot>{param.type}</TypeSlot>
+</Show>;
+
+// ❌ Avoid — large conditional blocks with &&
+{
+  props.typeParameters && (
+    <TypeParameterList parameters={props.typeParameters} />
+  );
+}
+```
+
+## Boolean Props
+
+Use shorthand for literal `true` values. Use explicit expressions when the value is conditional:
+
+```tsx
+// ✅ Good — shorthand for literal true
+<For each={items} comma hardline enderPunctuation>
+
+// ✅ Good — explicit expression when conditional
+<Indent
+  hardline={!props.inline && hasContent}
+  softline={props.inline || isEmpty}
+  trailingBreak
+>
+```
+
+## List Rendering
+
+Use `<For each={}>` to render lists in output. Use `.map()` only for transforming data before rendering:
+
+```tsx
+// ✅ Good — For in render output
+<For each={props.model.properties} comma hardline enderPunctuation>
+  {(prop) => <Property property={prop} />}
+</For>;
+
+// ✅ Good — .map() for data transformation
+const parameters = (props.parameters as string[]).map((name) => ({
+  name,
+  type: undefined,
+}));
+```
+
+## Fragments
+
+Use `<>...</>` to combine adjacent pieces of output without a wrapper. Prefer `code` template tags when the content is primarily text with interpolation:
+
+```tsx
+// ✅ Good — fragment for combining JSX pieces
+<>
+  {extendsClause}
+  {implementsClause}
+</>;
+
+// ✅ Good — code template when mixing text and expressions
+code`extends ${baseClass}`;
+```
+
+## Props
+
+Do not destructure props. Access them as `props.x`:
+
+```tsx
+// ✅ Good
+export function MyComponent(props: MyComponentProps) {
+  return (
+    <Declaration name={props.name} refkey={props.refkey}>
+      {props.children}
+    </Declaration>
+  );
+}
+
+// ❌ Bad — destructured props break reactivity
+export function MyComponent({ name, refkey, children }: MyComponentProps) {
+  // ...
+}
+```
+
+Use `splitProps` to separate props for forwarding:
+
+```tsx
+const [rest, forProps] = splitProps(props, ["children"]);
+```
+
+## Reactivity
+
+Use `computed()` for reactive derived values. Use `memo()` for memoizing children or component expressions:
+
+```tsx
+// ✅ Good — computed for a reactive signal
+const keyword = computed(() => (props.const ? "const" : "var"));
+
+// ✅ Good — memo for memoizing rendered children
+const resolvedChildren = memo(() =>
+  childrenArray(() => props.children, { preserveFragments: true }),
+);
+```
+
+## Component Return Patterns
+
+Choose your return style based on the content:
+
+- **JSX** for structural component trees
+- **`code` template** for text-heavy structured output
+- **`memo()`** wrapping reactive logic that determines what to render
+
+```tsx
+// JSX return
+export function MyComponent(props: MyComponentProps) {
+  return (
+    <Declaration name={props.name}>
+      <Indent hardline trailingBreak>
+        {props.children}
+      </Indent>
+    </Declaration>
+  );
+}
+
+// code template return
+export function XmlElement(props: XmlElementProps) {
+  return code`
+    <${props.tag}>
+      ${props.children}
+    </${props.tag}>
+  `;
+}
+
+// memo return for reactive branching
+export function ValueExpression(props: ValueExpressionProps): Children {
+  return memo((): Children => {
+    if (Array.isArray(props.jsValue)) {
+      return <ArrayExpression jsValue={props.jsValue} />;
+    }
+    return String(props.jsValue);
+  });
+}
+```
+
+## Symbols and References
+
+Use `refkey()` to capture symbols and reference them across files:
+
+```tsx
+// Creating a declaration with a refkey
+<InterfaceDeclaration name={props.model.name} refkey={refkey(props.model)}>
+  <For each={props.model.properties} comma hardline enderPunctuation>
+    {(prop) => <InterfaceMember name={prop.name} type={prop.type} />}
+  </For>
+</InterfaceDeclaration>;
+
+// Referencing the symbol elsewhere (auto-resolves name and imports)
+code`Promise<${refkey(responseModel)}>`;
+```
+
+## Component File Organization
+
+Structure component files as: imports, props interface, component function.
+
+```tsx
+import { Children, code, refkey } from "@alloy-js/core";
+import { Declaration } from "@alloy-js/typescript";
+
+export interface MyComponentProps {
+  name: string;
+  children?: Children;
+}
+
+export function MyComponent(props: MyComponentProps) {
+  return <Declaration name={props.name}>{props.children}</Declaration>;
+}
+```
+
+- File names use `kebab-case` (e.g. `my-component.tsx`)
+- Component names use `PascalCase`
+- Props interfaces are named `<ComponentName>Props`
+- Annotate return type as `Children` when the return is non-trivial

package/docs/index.md

@@ -0,0 +1,22 @@
+# @alloy-js/core
+
+## Conceptual Guides
+
+- [Components](components.md) — defining components, props, children, tagged children
+- [Control Flow](control-flow.md) — Show, For, Switch/Match
+- [Rendering](rendering.md) — the render pipeline, tree structure, output files
+- [Reactivity](reactivity.md) — reactive primitives, effects, memos, scheduling
+- [Formatting](formatting.md) — intrinsic elements, layout components, `code`/`text` tags
+- [Symbols & Scopes](symbols-and-scopes.md) — declarations, references, refkeys, name policies, the binder
+- [Context](context.md) — dependency injection through the component tree
+- [Debugging](debugging.md) — diagnostics, trace files, devtools
+
+## Framework Guides
+
+- [Style Guide](guides/style-guide.md) — idiomatic Alloy JSX patterns, conditional rendering, props, reactivity
+- [References & Refkeys](guides/references-and-refkeys.md) — symbol declarations, cross-file references, namekeys
+- [Language Package Guide](guides/language-package-guide.md) — creating a new `@alloy-js/<language>` package
+
+## API Reference
+
+- [API Reference](api/index.md) — auto-generated API documentation

package/docs/reactivity.md

@@ -0,0 +1,68 @@
+# Reactivity
+
+Alloy uses Vue's signal primitives from `@vue/reactivity`, wrapped with an owner/context system, a custom scheduler, and cleanup lifecycle.
+
+## Primitives
+
+- [**`ref(value)`**](api/functions/ref.md) — reactive container. Access/set via `.value`. Deep conversion.
+- [**`shallowRef(value)`**](api/functions/shallowRef.md) — no deep conversion. **Prefer in most cases.**
+- [**`computed(fn)`**](api/functions/computed.md) — derived reactive value (lazy, cached).
+- **`reactive(obj)`** — deeply reactive proxy.
+- [**`shallowReactive(obj)`**](api/functions/shallowReactive.md) — no deep conversion. **Prefer over `reactive()`.**
+
+## [`effect(fn, current?, options?)`](api/functions/effect.md)
+
+Re-runs `fn` when tracked dependencies change. Runs through Alloy's scheduler, creates a new [`Context`](api/types/Context.md) in the owner chain, supports cleanup via [`onCleanup()`](api/functions/onCleanup.md).
+
+## [`memo(fn, equal?, name?)`](api/functions/memo.md)
+
+Returns a getter caching the result of `fn`. Re-evaluates when dependencies change. If `equal` is true, skips downstream updates when the value is unchanged.
+
+```ts
+const fullName = memo(() => `${first.value} ${last.value}`);
+fullName(); // cached
+```
+
+## [`root(fn)`](api/functions/root.md)
+
+Creates an isolated reactive scope. Reactive reads inside `fn` are not tracked by any outer effect. The callback receives a dispose function. Returns the callback's return value.
+
+## [`untrack(fn)`](api/functions/untrack.md)
+
+Executes `fn` without tracking reactive dependencies. Useful for reading reactive values without subscribing, or performing side effects (e.g., registering imports) without creating unwanted dependencies.
+
+## [`onCleanup(fn)`](api/functions/onCleanup.md)
+
+Registers a cleanup function on the current context. Runs when the containing effect re-executes (before the next run) or when the containing root/component is disposed.
+
+Common uses:
+
+- Deleting symbols when a declaration is removed: `onCleanup(() => symbol.delete())`
+- Removing items from reactive collections
+- Dismissing diagnostics
+
+## Owner Chain
+
+Every [`effect()`](api/functions/effect.md) and [`root()`](api/functions/root.md) creates a [`Context`](api/types/Context.md) linked to its parent via `.owner`, forming a tree mirroring the component hierarchy. [`useContext()`](api/functions/useContext.md) traverses this chain.
+
+## Scheduler
+
+Synchronous dual-queue scheduler:
+
+- **Immediate queue** — drained first.
+- **Deferred queue** — drained after.
+
+`flushJobs()` runs synchronously during [`render()`](api/functions/render.md). `flushJobsAsync()` awaits pending promises — primarily useful in tests.
+
+## Reactivity in JSX
+
+The JSX transform wraps reactive expressions in effects. When a dependency changes, only that expression re-evaluates — the component function does not re-run.
+
+```tsx
+function Counter(props: { count: Ref<number> }) {
+  // Runs once. {props.count.value} is tracked in its own effect.
+  return <>Count: {props.count.value}</>;
+}
+```
+
+> **Warning:** Props may be reactive getters. `<Comp foo={myRef.value} />` compiles to a getter tracking `myRef`. Never use `/*@once*/` unless you're certain the value is non-reactive.

package/docs/rendering.md

@@ -0,0 +1,41 @@
+# Rendering
+
+Alloy renders a component tree into output files. The pipeline has three layers.
+
+## Pipeline
+
+```
+Component Tree  →  Rendered Text Tree  →  Output Files
+   (JSX)           (strings + hooks)       (formatted text)
+```
+
+1. [**`render(children, options?)`**](api/functions/render.md) — entry point. Returns an [`OutputDirectory`](api/types/OutputDirectory.md).
+2. [**`renderTree(children)`**](api/functions/renderTree.md) — evaluates components into a [`RenderedTextTree`](api/types/RenderedTextTree.md). Components run inside reactive effects and re-execute when dependencies change.
+3. **`sourceFilesForTree(tree)`** — walks the rendered tree, calling [`printTree()`](api/functions/printTree.md) per file to produce a formatted string for each source file.
+
+`renderTree()`, `printTree()`, and `sourceFilesForTree()` are available individually for advanced use cases.
+
+## Key Components
+
+- [**`<Output>`**](api/components/Output.md) — root. Sets up binder, format options, name policy, base path.
+- [**`<SourceDirectory>`**](api/components/SourceDirectory.md) — directory in the output tree.
+- [**`<SourceFile>`**](api/components/SourceFile.md) — file with `path`, `filetype`, optional print options.
+
+```tsx
+render(
+  <Output>
+    <SourceDirectory path="src">
+      <SourceFile path="index.ts" filetype="typescript">
+        console.log("hello");
+      </SourceFile>
+    </SourceDirectory>
+  </Output>,
+);
+```
+
+## File Operations
+
+- [**`<AppendFile>`**](api/components/AppendFile.md) — append to an existing output file.
+- [**`<CopyFile>`**](api/components/CopyFile.md) — copy from the host filesystem into output.
+- [**`<UpdateFile>`**](api/components/UpdateFile.md) — read and transform an existing output file.
+- [**`<TemplateFile>`**](api/components/TemplateFile.md) — read a host file, transform, write to output.