Adding package versions + kind configuration support for PackageDirectory (#347)

perezd · bterlson · web-flow · commit 3f1e16b57014 · 2025-12-11T13:53:18.000-08:00
Co-authored-by: Brian Terlson &lt;brian.terlson@microsoft.com&gt;
diff --git a/.chronus/changes/peer-deps-2025-11-10-17-1-32.md b/.chronus/changes/peer-deps-2025-11-10-17-1-32.md
@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@alloy-js/typescript"
+---
+
+The PackageDirectory component can now specify what kind of dependency to create for package dependencies added by reference using the `packageDependencyKinds` prop.
diff --git a/.chronus/changes/peer-deps-2025-11-10-17-2-4.md b/.chronus/changes/peer-deps-2025-11-10-17-2-4.md
@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@alloy-js/typescript"
+---
+
+The PackageDirectory component can now specify what version of a dependency to create for package dependencies added by reference using the `packageVersions` prop.
diff --git a/packages/typescript/src/components/PackageDirectory.tsx b/packages/typescript/src/components/PackageDirectory.tsx
@@ -9,8 +9,11 @@ import {
   SourceDirectoryContext,
   splitProps,
   useContext,
+  Wrap,
 } from "@alloy-js/core";
 import { join } from "pathe";
+import { PackageMetadataContext } from "../context/package-metadata.js";
+import { ExternalPackage, getPackageScope } from "../create-package.js";
 import { TSPackageScope } from "../symbols/index.js";
 import { modulePath } from "../utils.js";
 import { PackageJsonFile, PackageJsonFileProps } from "./PackageJson.js";
@@ -20,6 +23,20 @@ export interface PackageDirectoryProps extends PackageJsonFileProps {
   tsConfig?: { outDir?: string };
   children?: Children;
   path?: string;
+
+  /**
+   * Optional configuration values for referenced external packages.
+   * By default, external packages are added as regular dependencies.
+   * However you can specify `peerDependencies` or `devDependencies` to change this behavior.
+   * Version can also be specified here to override the configured package version.
+   */
+  packages?: [
+    ExternalPackage,
+    {
+      version?: string;
+      kind?: "dependencies" | "peerDependencies" | "devDependencies";
+    },
+  ][];
 }
 
 export const PackageContext: ComponentContext<PackageContext> =
@@ -58,13 +75,38 @@ export function PackageDirectory(props: PackageDirectoryProps) {
     "devDependencies",
   ]);
 
+  let pkgMeta: PackageMetadataContext | undefined = undefined;
+  if (props.packages) {
+    pkgMeta = {
+      versionSpecifiers: new Map(),
+      dependencyType: new Map(),
+    };
+    for (const [pkg, config] of props.packages) {
+      if (!config) {
+        throw new Error("Package configuration must be provided");
+      }
+      if (config.version) {
+        pkgMeta.versionSpecifiers.set(getPackageScope(pkg), config.version);
+      }
+      if (config.kind) {
+        pkgMeta.dependencyType.set(getPackageScope(pkg), config.kind);
+      }
+    }
+  }
+
   return (
     <SourceDirectory path={props.path ?? "."}>
       <PackageContext.Provider value={packageContext}>
         <Scope value={packageContext.scope}>
-          <PackageJsonFile {...pkgJsonProps} devDependencies={devDeps} />
-          <TSConfigJson {...props.tsConfig} />
-          {props.children}
+          <Wrap
+            when={!!pkgMeta}
+            with={PackageMetadataContext.Provider}
+            props={{ value: pkgMeta }}
+          >
+            <PackageJsonFile {...pkgJsonProps} devDependencies={devDeps} />
+            <TSConfigJson {...props.tsConfig} />
+            {props.children}
+          </Wrap>
         </Scope>
       </PackageContext.Provider>
     </SourceDirectory>
diff --git a/packages/typescript/src/components/PackageJson.tsx b/packages/typescript/src/components/PackageJson.tsx
@@ -1,4 +1,5 @@
-import { memo, SourceFile } from "@alloy-js/core";
+import { memo, SourceFile, useContext } from "@alloy-js/core";
+import { PackageMetadataContext } from "../context/package-metadata.js";
 import { modulePath } from "../utils.js";
 import { usePackage } from "./PackageDirectory.js";
 
@@ -73,8 +74,32 @@ export interface PackageExports {
  */
 export function PackageJsonFile(props: PackageJsonFileProps) {
   const pkg = usePackage();
+  const pkgMeta = useContext(PackageMetadataContext);
+
+  const dependencies = memo(() => {
+    const kinds = {
+      dependencies: props.dependencies,
+      devDependencies: props.devDependencies,
+      peerDependencies: props.peerDependencies,
+    };
+
+    if (pkg) {
+      for (const dependency of pkg.scope.dependencies) {
+        const kind = pkgMeta?.dependencyType.get(dependency) ?? "dependencies";
+        const versionSpecifier =
+          pkgMeta?.versionSpecifiers.get(dependency) ?? dependency.version;
+
+        kinds[kind] ??= {};
+        kinds[kind][dependency.name] = versionSpecifier;
+      }
+    }
+
+    return kinds;
+  });
 
   const jsonContent = memo(() => {
+    const deps = dependencies();
+
     const pkgJson = {
       name: props.name,
       version: props.version,
@@ -83,20 +108,9 @@ export function PackageJsonFile(props: PackageJsonFileProps) {
       license: props.license,
       homepage: props.homepage,
       type: props.type ?? "module",
-      dependencies:
-        props.dependencies || (pkg && pkg.scope.dependencies.size > 0) ?
-          Object.fromEntries([
-            ...Object.entries(props.dependencies ?? {}),
-            ...(pkg ?
-              Array.from(pkg.scope.dependencies).map((dependency) => [
-                dependency.name,
-                dependency.version,
-              ])
-            : []),
-          ])
-        : undefined,
-      devDependencies: props.devDependencies,
-      peerDependencies: props.peerDependencies,
+      dependencies: deps.dependencies,
+      devDependencies: deps.devDependencies,
+      peerDependencies: deps.peerDependencies,
       scripts: props.scripts,
       exports: undefined as any,
     };
diff --git a/packages/typescript/src/components/TypeDeclaration.tsx b/packages/typescript/src/components/TypeDeclaration.tsx
@@ -13,7 +13,7 @@ export const TypeDeclaration = ensureTypeRefContext(
           <JSDoc children={props.doc} />
           <hbr />
         </Show>
-        <Declaration {...props} nameKind="type">
+        <Declaration {...props} kind="type" nameKind="type">
           type <Name /> = {props.children};
         </Declaration>
       </>
diff --git a/packages/typescript/src/context/index.ts b/packages/typescript/src/context/index.ts
@@ -1 +1,2 @@
 // type ref context isn't exported because it conflicts with the component of the same name.
+export * from "./package-metadata.js";
diff --git a/packages/typescript/src/context/package-metadata.ts b/packages/typescript/src/context/package-metadata.ts
@@ -0,0 +1,13 @@
+import { ComponentContext, createNamedContext } from "@alloy-js/core";
+import { TSPackageScope } from "../symbols/ts-package-scope.js";
+
+export interface PackageMetadataContext {
+  versionSpecifiers: Map<TSPackageScope, string>;
+  dependencyType: Map<
+    TSPackageScope,
+    "dependencies" | "peerDependencies" | "devDependencies"
+  >;
+}
+
+export const PackageMetadataContext: ComponentContext<PackageMetadataContext> =
+  createNamedContext<PackageMetadataContext>("PackageMetadataContext");
diff --git a/packages/typescript/src/create-package.ts b/packages/typescript/src/create-package.ts
@@ -165,10 +165,19 @@ function assignMembers(
   }
 }
 
+const packageScopeSymbol: unique symbol = Symbol();
+/**
+ * Retrieve the package scope associated with an external package created via
+ * createPackage.
+ */
+export function getPackageScope(pkg: ExternalPackage) {
+  return (pkg as any)[packageScopeSymbol];
+}
+
 function createSymbols(
   binder: Binder,
   props: CreatePackageProps<PackageDescriptor>,
-  refkeys: Record<string, any>,
+  refkeys: Record<string | typeof packageScopeSymbol, any>,
 ) {
   const pkgScope = new TSPackageScope(
     props.name,
@@ -180,6 +189,8 @@ function createSymbols(
     },
   );
 
+  refkeys[packageScopeSymbol] = pkgScope;
+
   for (const [path, symbols] of Object.entries(props.descriptor)) {
     const keys = path === "." ? refkeys : refkeys[path];
     const moduleScope = new TSModuleScope(path, pkgScope, {
@@ -252,13 +263,20 @@ function createRefkeysForMembers(
   }
 }
 
+export interface ExternalPackage {
+  [externalPackageSymbol]: true;
+}
+
+const externalPackageSymbol: unique symbol = Symbol("ExternalPackageSymbol");
+
 export function createPackage<const T extends PackageDescriptor>(
   props: CreatePackageProps<T>,
-): PackageRefkeys<T> & SymbolCreator {
+): PackageRefkeys<T> & SymbolCreator & ExternalPackage {
   const refkeys: any = {
     [getSymbolCreatorSymbol()](binder: Binder) {
       createSymbols(binder, props, refkeys);
     },
+    [externalPackageSymbol]: true,
   };
 
   for (const [path, symbols] of Object.entries(props.descriptor)) {
diff --git a/packages/typescript/test/externals.test.tsx b/packages/typescript/test/externals.test.tsx
@@ -1,4 +1,4 @@
-import { Output } from "@alloy-js/core";
+import { Output, render } from "@alloy-js/core";
 import { expect, it } from "vitest";
 import { fs } from "../src/builtins/node.js";
 import {
@@ -187,3 +187,152 @@ it("can import static members", () => {
     `,
   });
 });
+
+it("can specify packages as dev dependencies", () => {
+  const testLib = createPackage({
+    name: "testLib",
+    version: "1.0.0",
+    descriptor: {
+      ".": {
+        named: ["foo"],
+      },
+    },
+  });
+
+  expect(
+    <Output externals={[testLib, fs]}>
+      <PackageDirectory
+        path="."
+        name="test"
+        version="1.0.0"
+        packages={[[testLib, { version: "2.0.0", kind: "devDependencies" }]]}
+      >
+        <SourceFile path="index.ts">{testLib.foo};</SourceFile>
+      </PackageDirectory>
+    </Output>,
+  ).toRenderTo({
+    "package.json": `
+      {
+        "name": "test",
+        "version": "1.0.0",
+        "type": "module",
+        "devDependencies": {
+          "typescript": "^5.5.2",
+          "testLib": "2.0.0"
+        }
+      }
+    `,
+    "tsconfig.json": expect.anything(),
+    "index.ts": expect.anything(),
+  });
+});
+
+it("can specify packages as peer dependencies", () => {
+  const testLib = createPackage({
+    name: "testLib",
+    version: "1.0.0",
+    descriptor: {
+      ".": {
+        named: ["foo"],
+      },
+    },
+  });
+
+  expect(
+    <Output externals={[testLib, fs]}>
+      <PackageDirectory
+        path="."
+        name="test"
+        version="1.0.0"
+        packages={[[testLib, { version: "2.0.0", kind: "peerDependencies" }]]}
+      >
+        <SourceFile path="index.ts">{testLib.foo};</SourceFile>
+      </PackageDirectory>
+    </Output>,
+  ).toRenderTo({
+    "package.json": `
+      {
+        "name": "test",
+        "version": "1.0.0",
+        "type": "module",
+        "devDependencies": {
+          "typescript": "^5.5.2"
+        },
+        "peerDependencies": {
+          "testLib": "2.0.0"
+        }
+      }
+    `,
+    "tsconfig.json": expect.anything(),
+    "index.ts": expect.anything(),
+  });
+});
+
+it("can inherit package version as peer dependency", () => {
+  const testLib = createPackage({
+    name: "testLib",
+    version: "1.0.0",
+    descriptor: {
+      ".": {
+        named: ["foo"],
+      },
+    },
+  });
+
+  expect(
+    <Output externals={[testLib, fs]}>
+      <PackageDirectory
+        path="."
+        name="test"
+        version="1.0.0"
+        packages={[[testLib, { kind: "peerDependencies" }]]}
+      >
+        <SourceFile path="index.ts">{testLib.foo};</SourceFile>
+      </PackageDirectory>
+    </Output>,
+  ).toRenderTo({
+    "package.json": `
+      {
+        "name": "test",
+        "version": "1.0.0",
+        "type": "module",
+        "devDependencies": {
+          "typescript": "^5.5.2"
+        },
+        "peerDependencies": {
+          "testLib": "1.0.0"
+        }
+      }
+    `,
+    "tsconfig.json": expect.anything(),
+    "index.ts": expect.anything(),
+  });
+});
+
+it("must throw an error if package configuration is not provided", () => {
+  const testLib = createPackage({
+    name: "testLib",
+    version: "1.0.0",
+    descriptor: {
+      ".": {
+        named: ["foo"],
+      },
+    },
+  });
+
+  expect(() =>
+    render(
+      <Output externals={[testLib, fs]}>
+        <PackageDirectory
+          path="."
+          name="test"
+          version="1.0.0"
+          // @ts-expect-error explicitly testing missing package config.
+          packages={[[testLib]]}
+        >
+          <SourceFile path="index.ts">{testLib.foo};</SourceFile>
+        </PackageDirectory>
+      </Output>,
+    ),
+  ).toThrowError("Package configuration must be provided");
+});

Original file line number	Diff line number	Diff line change
`@@ -1 +1,2 @@`
`1`	`1`	`// type ref context isn't exported because it conflicts with the component of the same name.`
	`2`	`+export * from "./package-metadata.js";`