Rust feature branch

.github/copilot-instructions.md

@@ -16,3 +16,59 @@ This repository is built on alloy which use JSX to define components. This is NO
   - DO NOT destructure props in the component definition
 
 Do not update changelogs, these are managed by `npx chronus`.
+
+## TypeScript/Symbol Patterns - Known Gotchas
+
+- For exported components that attach subcomponents (for example, `Component.Call = ...`), avoid private type aliases in public exported const annotations; API Extractor can fail. Prefer `export function Component(...) { ... }` and attach subcomponents as properties after declaration.
+  **Static memberSpaces in Symbol subclasses:** When subclassing symbols with custom `memberSpaces`, declare static `memberSpaces` as `readonly string[]` in both base and subclass. TypeScript tuple widening/narrowing on the static side causes incompatibility errors without explicit readonly string[] typing. Always validate symbol changes with: `pnpm --filter @alloy-js/rust build && pnpm --filter @alloy-js/rust test` (`pnpm --filter @alloy-js/rust build` runs `alloy build --with-dev` and `generate-docs`, so it also checks API surface generation).
+  **For SourceFile/CrateDirectory loop changes:** run `pnpm --filter @alloy-js/rust exec vitest run test/source-file-crate-directory.test.tsx` first for fast debugging, then run full `pnpm --filter @alloy-js/rust build && pnpm --filter @alloy-js/rust test`.
+  **For TypeAlias/ConstDeclaration loops:** run `pnpm --filter @alloy-js/rust exec vitest run test/type-alias-const.test.tsx` first, then run `pnpm --filter @alloy-js/rust test`.
+  **For import/reference integration loops:** run `pnpm --filter @alloy-js/rust exec vitest run test/imports.test.tsx test/reference.test.tsx` before full-suite validation to iterate faster.
+  **For Cargo.toml generation loops:** keep `CrateDirectory` Cargo.toml emission opt-in (`includeCargoToml`) so existing single-file `toRenderTo()` tests keep stable output.
+- For `CargoTomlFile` targets, emit explicit sections (`[lib] path = "lib.rs"` for libs, `[[bin]]` with `name`/`path` for bins) before `[dependencies]`; expect snapshot updates in cargo-toml/golden/stc tests.
+  **Validation workflow tip:** use `pnpm --filter @alloy-js/rust build && pnpm --filter @alloy-js/rust test` as the Rust package correctness gate; also run `pnpm --filter rust-example build` when touching sample crate exports, and fix TS2742 by replacing inferred exported `createCrate(...)` values with explicit descriptor constants (`as const`) plus exported type aliases.
+- In components using `scope.enclosingModule`, narrow to `RustModuleScope` (for example, `instanceof RustModuleScope`) before accessing `.types` or `.values`; `enclosingModule` is typed as `RustScopeBase`.
+- Avoid whitespace-only `code` template literals (for example, ``code` ` ``); they can crash core code rendering. Use plain string literals like `" "` for standalone spaces.
+- For `ModuleDirectory`, derive the module name from the last `path` segment before calling `addChildModule`, so nested paths register the correct child module.
+- For exported Rust APIs, avoid exposing private helper types through symbol-keyed fields on exported interfaces; API Extractor treats them as public and fails build with `ae-forgotten-export`.
+- For public builtins exports (for example `export const std = createCrate(...)` in `packages/rust/src/builtins/std.ts`), avoid relying on inferred/private descriptor shapes; this can trigger TS2742/API Extractor portability errors. Prefer explicit exported type aliases/interfaces for the export surface, then validate with `pnpm --filter @alloy-js/rust build && pnpm --filter @alloy-js/rust test`.
+- In `packages/rust/src/components/stc/index.ts`, prefer explicit named component imports (alias if needed) and `stc(ComponentAlias)` for exported wrappers; avoid `import * as base` + `stc(base.X)`, which can trigger API Extractor `ae-forgotten-export` private type leakage.
+- `Parameters` rendering requires `RustFunctionScope`; when testing `Parameters`/`Stc.Parameters`, render within a `FunctionDeclaration` instead of at module/root scope to avoid `Can't create parameter symbol outside of a function scope.`
+- For enum/struct sibling rendering, always insert explicit `<hbr />` separators between repeated children (variants/fields) and between doc comments and declaration attributes; debug quickly with `pnpm --filter @alloy-js/rust exec vitest run test/enum.test.tsx test/struct.test.tsx`, then confirm with full `pnpm --filter @alloy-js/rust build && pnpm --filter @alloy-js/rust test`.
+- For braced expression components that use `<Indent>` (for example `StructExpression`), do not add a leading `<hbr />` right after `" {"`; it introduces an extra blank line before the first indented entry.
+- In `TraitDeclaration`, a self-closing `FunctionDeclaration` is an abstract signature and must render with `;` (not `{}`); a trait method with children is a default implementation and renders with braces. For fast regression checks, run `pnpm --filter @alloy-js/rust exec vitest run test/function.test.tsx test/reference.test.tsx`.
+- In `SourceFile`/module registration flows, standalone non-root files should self-register with parent module declarations, but module-root files (`lib.rs`, `main.rs`, `mod.rs`) must never self-register.
+- In `ImplBlock`/`TraitDeclaration`, `FunctionDeclaration` defaults receiver to `&self`; set `receiver="none"` for associated functions like `new()`.
+- For `ModDeclarations` render-order regressions, first run `pnpm --filter @alloy-js/rust exec vitest run test/t045-render-order.test.tsx test/mod-declarations.test.tsx`, then run full rust validation.
+- For Rust generic rendering, keep lifetime parameters and type parameters in the same `TypeParameterProp[]`, but always render lifetimes first (`<'a, 'b, T>`), and quickly verify with `pnpm --filter @alloy-js/rust exec vitest run test/type-parameters.test.tsx test/lifetime-parameters.test.tsx`.
+- For `ImplBlock` generic forwarding, ensure `StructDeclaration`/`EnumDeclaration` register named type parameter symbols on `NamedTypeSymbol.typeParameters` whenever `typeParameters` are provided.
+- For trait-import tests that depend on `Reference` auto-use behavior, avoid Rust prelude traits (for example `Clone`) because prelude symbols intentionally skip `use` generation; assert imports with non-prelude traits like `std::fmt::Display`.
+- `LetBinding` intentionally does **not** register symbols in scope (T049 exclusions); treat it as syntax-only statement rendering with optional type/initializer and a trailing `;`.
+- In `FunctionCallExpression`-style components using `<group>` + `Wrap` (`when={args.length > 1}`), expect stable multiline output for multi-arg calls, and turbofish type-arg lists may also line-break under the same group; snapshot tests should assert multiline form.
+- For components using `<Wrap when={...}>`, line breaks occur only after print-width overflow; include at least one long argument in multi-arg tests when asserting multiline wrapping.
+- Ensure `DocComment`/`ModuleDocComment` end with a trailing line break before declarations; otherwise generated output can concatenate comment text and the next declaration.
+
+Critical rules:
+
+1. Do not invent architecture. Ground every important claim in actual repository code, file structure, symbols, or tests.
+2. Prefer concrete evidence over broad summaries.
+3. Distinguish clearly between:
+   - observed facts from the repo
+   - inferences from patterns
+   - proposals for the new language package
+4. When something is unclear, say so explicitly under "Open Questions" or "Ambiguities".
+5. Do not start implementing code unless explicitly asked. This phase is documentation and planning only.
+6. Write output directly to the requested markdown file.
+7. Use clear headings and bullet points where useful.
+8. When referencing repository files, include repository-relative paths.
+9. Focus only on the parts of the repo relevant to Alloy core and existing language packages.
+10. Optimize for future AI coding agents that will consume these documents.
+11. For symbol-model changes (like Rust T003), always validate with `pnpm --filter @alloy-js/rust build && pnpm --filter @alloy-js/rust test` before moving to dependent tasks.
+
+Quality bar:
+
+- Precise
+- Evidence-based
+- Dependency-aware
+- Implementation-oriented
+- Not generic

.github/prompts/001-discovery.md

@@ -0,0 +1,64 @@
+You are working inside the Alloy monorepo.
+
+Your goal is to identify the minimum set of repository files required to understand:
+
+1. Alloy core
+2. How language packages extend Alloy
+3. The current implementations for TypeScript, Java, Python, and C#
+4. The testing patterns used by existing language packages
+5. Any contributor docs, architecture docs, package READMEs, or examples relevant to adding a new language package
+
+Do not write a full architecture summary yet.
+Do not propose a design for a target language yet.
+
+Instead, produce a discovery document at:
+
+docs/00-relevant-files.md
+
+The document must contain:
+
+# Purpose
+
+A short explanation of why these files matter for planning a new language package.
+
+# Core Files
+
+A list of the key files/directories needed to understand Alloy core.
+For each item include:
+
+- path
+- why it matters
+- what concept it likely covers
+
+# Existing Language Package Files
+
+For TypeScript, Java, Python, and C#, list the most important files/directories.
+For each item include:
+
+- path
+- package/language
+- why it matters
+- likely role in the package
+
+# Tests and Examples
+
+List the most relevant test/example files and why they matter.
+
+# Documentation
+
+List repo docs that appear important.
+
+# Recommended Reading Order
+
+Provide a practical reading order for the next analysis passes.
+
+# Exclusions
+
+List files/directories that appear large but likely irrelevant for this task.
+
+Constraints:
+
+- Be selective. Prefer quality over exhaustiveness.
+- Ground everything in the repo.
+- Do not guess beyond what the repo supports.
+- Keep the document concise but useful.

.github/prompts/002-core-understanding.md

@@ -0,0 +1,99 @@
+You are working inside the Alloy monorepo.
+
+Your task is to understand Alloy core deeply enough that a later agent can design a new <TARGET_LANGUAGE> language package without misplacing responsibilities between core and language-specific libraries.
+
+Write the output to:
+
+<CORE_DOC>
+
+Do not design <TARGET_LANGUAGE> yet.
+Do not describe implementation tasks yet.
+This document must be primarily descriptive, not prescriptive.
+
+Study the repository and produce a markdown document with the following exact sections:
+
+# 1. Objective
+
+Explain the purpose of this document and how it will be used later.
+
+# 2. What Alloy Appears to Be
+
+Describe Alloy's role as a code generation framework based on repository evidence.
+Summarize the apparent generation model in plain language.
+
+# 3. Core Architectural Model
+
+Explain the core architecture of Alloy.
+Cover the major abstractions and how they appear to work together.
+
+At minimum analyze:
+
+- rendering model
+- component/composition model
+- context/providers/hooks if present
+- document/file generation model
+- symbol/reference model
+- scope and name resolution model
+- formatting/printing model
+- extension/plugin surfaces for language packages
+
+# 4. Key Core Concepts
+
+Create a glossary of the most important concepts in Alloy core.
+For each concept include:
+
+- name
+- what it means
+- why it matters
+- key files where it is defined or exercised
+
+# 5. Core-to-Language Extension Surface
+
+Describe exactly how language packages appear to build on core.
+Identify the likely contracts, APIs, primitives, or patterns that language packages rely on.
+
+Separate:
+
+- clearly observed extension points
+- inferred extension patterns
+
+# 6. Source File Inventory
+
+List the most important core files and directories.
+For each include:
+
+- path
+- purpose
+- notable exported types/functions/components/classes
+- why it is relevant to new language support
+
+# 7. Invariants and Constraints
+
+Document the important invariants or architectural constraints that later work must respect.
+Examples:
+
+- what core appears to own
+- what language packages appear to own
+- assumptions about rendering
+- assumptions about symbol handling
+- assumptions about output structure
+
+# 8. Testing Patterns in Core
+
+Describe how core behavior is tested and what that implies for future language packages.
+
+# 9. Ambiguities / Open Questions
+
+List anything that is unclear, inconsistent, or underdocumented in the repo.
+
+# 10. Key Takeaways for Future Language Package Design
+
+Summarize the most important lessons from core that a planner must not miss.
+
+Requirements:
+
+- Ground important claims in repository-relative file paths.
+- Be concrete.
+- Separate fact from inference.
+- Do not propose new abstractions unless necessary to explain an observed gap.
+- Optimize the document for later AI agents that will design and implement <TARGET_LANGUAGE>.

.github/prompts/003-compare-language-packages.md

@@ -0,0 +1,105 @@
+You are working inside the Alloy monorepo.
+
+Your task is to compare the existing Alloy language packages so that a future agent can identify the stable patterns for implementing a new <TARGET_LANGUAGE> package.
+
+Study the repository and write the output to:
+
+<PATTERNS_DOC>
+
+Use the previously generated core understanding document as context:
+<CORE_DOC>
+
+The purpose of this document is not to restate core, but to extract reusable patterns and package-shape expectations from the existing language packages.
+
+Analyze the existing language packages for:
+
+- TypeScript
+- Java
+- Python
+- C#
+
+Produce a markdown document with the following exact sections:
+
+# 1. Objective
+
+Explain how this comparison will inform the design of <TARGET_LANGUAGE> support.
+
+# 2. Packages Compared
+
+List the package paths examined for TypeScript, Java, Python, and C#.
+
+# 3. Common Package Anatomy
+
+Describe the recurring structure shared by the existing language packages.
+Examples may include:
+
+- package layout
+- public API surface
+- component organization
+- symbol/reference helpers
+- file/module abstractions
+- declaration and expression modeling
+- formatting utilities
+- tests and examples
+
+# 4. Cross-Language Concept Matrix
+
+Create a detailed comparison matrix covering at least:
+
+- source file / module representation
+- imports / usings / package declarations / namespaces
+- identifiers and symbol references
+- literals
+- expressions
+- statements
+- declarations
+- type references
+- functions / methods
+- classes / interfaces / structs / equivalents
+- visibility/modifiers/annotations/decorators where applicable
+- comments / doc comments
+- formatting / whitespace / delimiters
+- test strategy
+
+For each concept, explain:
+
+- how TypeScript handles it
+- how Java handles it
+- how Python handles it
+- how C# handles it
+- what seems to be the shared principle
+- what varies by language
+
+# 5. Reusable Patterns
+
+List the architectural and implementation patterns that appear reusable for any new language package.
+
+# 6. Divergent or Language-Specific Patterns
+
+List the parts that vary significantly and should not be over-generalized.
+
+# 7. Implied Minimum Viable Surface for a New Language Package
+
+Based on the existing packages, infer the likely minimum set of capabilities a new language package should provide.
+
+This section should be an inferred checklist, not yet a target-language proposal.
+
+# 8. Testing Patterns Across Language Packages
+
+Describe how the existing language packages test themselves and what a new package should likely emulate.
+
+# 9. Gaps, Inconsistencies, and Risks
+
+Identify inconsistencies between existing packages or any uncertainty that could affect planning for <TARGET_LANGUAGE>.
+
+# 10. Takeaways for Designing <TARGET_LANGUAGE>
+
+Summarize the most important reusable lessons.
+
+Requirements:
+
+- Ground all major claims in actual repository evidence.
+- Use repository-relative paths.
+- Distinguish observed package behavior from inferred patterns.
+- Do not design <TARGET_LANGUAGE> yet except where explicitly asked in section 10 to state takeaways.
+- Optimize for future planning and implementation agents.